Skip to main content
사용자 대상 채팅 UI의 경우, Chat XDK를 JavaScript/WASM 패키지(@xdevplatform/chat-xdk)를 통해 브라우저에서 실행하세요. 개인 신원 및 서명 키는 사용자의 기기에 머무릅니다. 서버(그리고 X)는 오직 암호문, 공개 키, OAuth 토큰만 볼 수 있으며, 메시지를 암호화하고 서명하는 데 사용되는 PIN이나 개인 키 자료는 결코 볼 수 없습니다. 이 페이지는 클라이언트 앱을 위한 권장 아키텍처입니다. 모든 앱 유형에 적용되는 PIN 및 키 취급 규칙은 개인 키 다루기를 참고하세요.

왜 UI 앱에 WASM인가

최종 사용자는 자신의 암호화 PIN을 절대 백엔드에 붙여 넣어서는 안 되며, 백엔드는 그들의 신원 개인 키를 절대 보유해서는 안 됩니다. 서드파티 서버가 사용자의 PIN이나 루트 개인 키를 받게 되면, 해당 서드파티는 그 신원에 감싸진 대화 키를 사용자가 OAuth 접근을 취소한 후에도 복호화할 수 있습니다. 클라이언트 사이드 WASM은 정상적인 앱에서 이러한 종류의 실패를 방지합니다.
PIN이나 개인 키를 서드파티와 공유하는 것은 암호화 DM의 비밀번호를 공유하는 것과 같습니다. OAuth 연결 해제는 앱이 이미 획득한 키를 취소하지 않습니다. 키가 브라우저를 떠나지 않도록 WASM을 우선하세요; 그럴 수 없는 경우에는 위험을 명확히 문서화하세요. 개인 키 다루기를 참고하세요.

권장 아키텍처

암호화(브라우저)와 API 전송(백엔드 또는 사용자 토큰이 있는 직접 X API)을 분리하세요: 일반적인 패턴(브라우저 채팅 클라이언트와 같은 내부 데모에서 사용)은 다음과 같습니다: 프런트엔드의 WASM + React(또는 유사한 것), **Next.js(또는 다른) API 라우트의 TypeScript XDK**로 브라우저가 원한다면 장기 시크릿으로 api.x.com에 직접 접근하지 않도록 합니다. 암호화는 여전히 브라우저에서만 실행됩니다.

브라우저 패키지 설치

컴파일된 WASM 엔진은 @xdevplatform/chat-xdk 내부에 포함되어 있어 소비자를 위한 별도의 Rust 툴체인은 없습니다. 최신 브라우저(SSR과 코드를 공유하는 경우 Node.js 18+; 암호화는 오직 클라이언트에서만 실행)가 필요합니다.

세션 흐름 (PIN 한 번, 키는 메모리에 유지)

메시지마다 PIN을 요청하지 마세요. 브라우저 세션당 한 번 잠금 해제하고, Chat 인스턴스를 메모리에 유지한 다음(모듈 싱글턴, React context 등), 잠금 해제된 해당 인스턴스에 대해 암호화하고 복호화하세요.

UX 기대치

모든 액션마다 PIN을 다시 요청하지 마세요. 데모 앱은 단순함을 위해 종종 unlock을 반복 호출합니다. 프로덕션 UI는 한 번만 잠금 해제하고, 인스턴스를 메모리에 유지하며, 리로드, 로그아웃 또는 lock() 이후에만 PIN을 다시 요청해야 합니다.

서버가 볼 수 있는 것

Juicebox의 realm 토큰은 사용자의 PIN이 아닙니다. 해당 사용자 및 키 버전에 대한 백업 프로토콜을 인가합니다. 이미 사용자 OAuth 컨텍스트를 보유한 백엔드에서 계속 발급하세요.

브라우저의 보안 키 백업

클라이언트 앱은 원시 키 파일이 아닌 보안 키 백업(패스코드를 사용하는 setup / unlock)을 사용해야 합니다:
  1. 사용자의 공개 키 레코드(public_key.fields=juicebox_config)에서 juicebox_config를 로드합니다.
  2. createChat({ juiceboxConfig, getAuthToken }).
  3. 최초: generateKeypairs → X에 공개 키 등록 → setup(pin).
  4. 이후: 이 기기에서(또는 동일한 PIN을 사용하는 새 기기에서) unlock(pin).
Chat XDK의 브라우저 경로는 키를 WASM으로 복구하며 원시 개인 키 내보내기를 공개 createChat 표면에 노출하지 않으므로, 애플리케이션 JavaScript가 루트 키 바이트를 페이지로 끌어오도록 권장되지 않습니다. 손수 작성한 localStorage 키 덤프보다 이 모델을 선호하세요. 전체 등록 및 잠금 해제 단계: 시작하기. 개념: 암호화 기초.

브라우저 하드닝 체크리스트

  • Chat XDK는 오직 클라이언트 번들에서만 실행하세요(잠금 해제된 키의 SSR 금지).
  • 잠금 해제된 Chat 인스턴스를 라이브 세션 시크릿처럼 취급하세요: window에 두지 말고, 로그로 남기지 말며, 분석에 게시하지 마세요.
  • XSS로부터 방어하세요: CSP, 신중한 dangerouslySetInnerHTML / 마크다운 렌더링, 의존성 위생. 채팅 앱의 XSS는 키가 네트워크에 도달하지 않더라도 메모리에 있는 키에 접근할 수 있습니다.
  • 모든 곳에서 HTTPS를 사용하세요; 암호화 페이지를 안전하지 않은 스크립트와 혼합하지 마세요.
  • 최소 OAuth 스코프를 선호하세요; 필요할 때만 DM 스코프를 요청하고 제품 UI에서 설명하세요.
  • 로그아웃 시 lock() / **free()**를 호출하고 인스턴스를 폐기하세요.
저장 권장사항(어떤 것을 localStorage에 두지 말아야 하는지, 세션 지속성에 대해 어떻게 생각해야 하는지)은 개인 키 다루기에 있습니다.

다음 단계

  1. 개인 키 다루기 — PIN 경고, 저장, 봇 대 UI 앱
  2. 시작하기 — 전체 키 등록과 첫 메시지
  3. Chat XDKcreateChat, encrypt, decrypt의 API 참조
  4. 실시간 이벤트 — 로컬 복호화를 위한 암호문을 클라이언트에 전달