@xdevplatform/chat-xdk 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# chat-xdk JavaScript/WASM bindings
+
+JavaScript/WASM bindings for the X Chat SDK — end-to-end encryption for X Direct Messages.
+
+## Architecture
+
+```
+JavaScript (chat-xdk) → wasm-bindgen → Rust WASM (chat_xdk_wasm) → chat-xdk-core
+```
+
+The Rust WASM layer is a pure crypto engine; Juicebox key-storage lifecycle is orchestrated in the JS wrapper (`index.js`).
+
+## Prerequisites
+
+- **Node.js 18+**
+- [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/)
+
+## Setup
+
+### 1. Build chat-xdk WASM
+
+```bash
+cd crates/wasm
+wasm-pack build --target nodejs --out-dir pkg    # or --target web for browser bundlers
+```
+
+### 2. Build juicebox-sdk WASM
+
+`juicebox-sdk` is not on npm — it must be built from source.
+Clone [juicebox-sdk](https://github.com/juicebox-systems/juicebox-sdk) as a sibling of `chat-xdk`:
+
+```bash
+git clone https://github.com/juicebox-systems/juicebox-sdk.git ../juicebox-sdk
+cd ../juicebox-sdk/rust/sdk/bridge/wasm
+wasm-pack build --target nodejs --out-dir pkg --out-name juicebox-sdk
+```
+
+The `--out-name juicebox-sdk` flag is required so the output files match the names
+that `index.js` imports (`juicebox-sdk.js`, `juicebox-sdk_bg.js`, `juicebox-sdk_bg.wasm`).
+Use the same `--target` for both builds (`nodejs` for Node, `web` or `bundler` for browsers).
+
+### 3. Install dependencies
+
+```bash
+cd crates/wasm/js
+npm install
+npm install ../../juicebox-sdk/rust/sdk/bridge/wasm/pkg   # links juicebox-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createChat } from "chat-xdk";
+
+const chat = await createChat({
+  juiceboxConfig: configJson,
+  getAuthToken: async (realmId) => await myBackend.getToken(realmId),
+});
+await chat.unlock("2580");
+
+// Initial load — batch decrypt with automatic key extraction
+const result = chat.decryptEvents(rawEvents, [
+  { userId: "111", publicKeyVersion: "v1", publicKey: "BASE64..." },
+  { userId: "222", publicKeyVersion: "v1", publicKey: "BASE64..." },
+]);
+
+for (const dm of result.messages) {
+  if (dm.event.type === "message") {
+    console.log(dm.event.senderId, dm.event.content.text);
+  }
+}
+
+// Cache keys, then use decryptEvent for individual events
+const cachedKeys = result.conversationKeys.keys;
+const event = chat.decryptEvent(webhookEventB64, cachedKeys, senderSigningKeys);
+```
+
+## API
+
+See the **JS** column of the unified tables in [`docs/API.md`](../../../docs/API.md) for the full method list, parameters, and return types.
+
+## Security limitations
+
+The underlying protocol provides **no forward secrecy and no post-compromise
+security**: compromise of an identity private key exposes all conversation
+keys ever encrypted to that public key — and therefore all past and future
+messages in those conversations. Key rotation does not retroactively protect
+messages encrypted under a previous key. See
+[docs/CRYPTO.md — Known Limitations](../../../docs/CRYPTO.md#known-limitations).
+
+### Key export is not exposed in the browser build
+
+Raw private-key export and import are not part of this binding's public API.
+`exportKeys()` would return unencrypted private key material to page
+JavaScript, where any script that can reach the chat instance — including code
+injected via XSS or a compromised dependency — could exfiltrate the identity
+permanently. Keys are managed inside the Juicebox layer (`setup`/`unlock`)
+instead, so raw key bytes never cross into application JavaScript.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,558 @@
+/**
+ * X Chat SDK - TypeScript Definitions
+ */
+
+/**
+ * Public keys returned from getPublicKeys().
+ */
+export interface PublicKeys {
+  /** Base64-encoded identity public key */
+  identity: string;
+  /** Base64-encoded signing public key */
+  signing: string;
+}
+
+/**
+ * Public key registration fields for the X API.
+ */
+export interface PublicKeyRegistration {
+  identityPublicKeySignature: string;
+  publicKey: string;
+  publicKeyFingerprint?: string;
+  registrationMethod: string;
+  signingPublicKey: string;
+  signingPublicKeySignature?: string;
+}
+
+/**
+ * Public key registration payload for the X API.
+ */
+export interface PublicKeyRegistrationPayload {
+  publicKey: PublicKeyRegistration;
+  version?: string;
+  generateVersion: boolean;
+}
+
+/**
+ * Result from encrypt*ForApi methods.
+ */
+export interface SendPayload {
+  /** Base64-encoded Thrift MessageCreateEvent. */
+  encryptedContent: string;
+  /** Base64-encoded ECDSA signature. */
+  signature: string;
+  /** Base64-encoded Thrift MessageEventSignature. */
+  encodedEventSignature: string;
+  /** Signature metadata (signing key version + signature protocol version). */
+  signatureInfo: { publicKeyVersion: string; signatureVersion: string };
+  /** Version of the conversation key used to encrypt the content (a snowflake/timestamp string). */
+  conversationKeyVersion: string;
+  /** Whether the X API should send a push notification for this message. */
+  shouldNotify: boolean;
+}
+
+/**
+ * Result from signAddMembers / signKeyChange.
+ */
+export interface ActionSignature {
+  messageId: string;
+  encodedMessageEventDetail: string;
+  signature: string;
+  signatureVersion: string;
+  publicKeyVersion: string;
+  signaturePayload: string;
+}
+
+/**
+ * A recipient for encryptConversationKeyForRecipients.
+ */
+export interface RecipientInput {
+  /** The recipient's user ID (snowflake string). */
+  userId: string;
+  /** Base64-encoded identity public key (SEC1 or SPKI). */
+  publicKey: string;
+  /** Key version string from the X API. */
+  keyVersion: string;
+}
+
+/**
+ * A signing key entry for decryptEvent and decryptEvents.
+ * Pass all known signing keys for all participants; the SDK matches by userId + version.
+ */
+export interface SigningKeyEntry {
+  /** The participant's user ID (snowflake string). */
+  userId: string;
+  /** Signing key version from the X API (a snowflake/timestamp string). */
+  publicKeyVersion: string;
+  /** Base64-encoded signing public key (SEC1 or SPKI). */
+  publicKey: string;
+  /** Base64-encoded identity public key for this user. */
+  identityPublicKey: string;
+  /** Base64-encoded raw r||s signature proving the signing key is bound to the identity key. Returned by the X API. */
+  identityPublicKeySignature: string;
+}
+
+/** Map of key version → raw conversation key bytes. */
+export type ConversationKeyMap = { [version: string]: Uint8Array };
+
+/**
+ * Result from extractConversationKeys.
+ * Contains the key map plus the latest version for convenience.
+ */
+export interface ConversationKeyResult {
+  /** Map of key version → raw conversation key bytes. */
+  keys: ConversationKeyMap;
+  /** The latest (highest) key version, for encrypting new messages. */
+  latestVersion: string | null;
+}
+
+/**
+ * A single decrypted message from decryptEvents.
+ */
+export interface DecryptedMessage {
+  /** The decrypted event. */
+  event: Event;
+  /** Original base64 event string (for reference). */
+  originalB64?: string;
+}
+
+/**
+ * Result from decryptEvents batch API.
+ */
+export interface DecryptEventsResult {
+  /** Successfully decrypted messages. */
+  messages: DecryptedMessage[];
+  /** Extracted conversation keys (for caching). */
+  conversationKeys: ConversationKeyResult;
+  /** Errors encountered during decryption (index → error message). */
+  errors: { [index: number]: string };
+}
+
+/**
+ * Image dimensions returned by detectImageDimensions.
+ */
+export interface ImageDimensions {
+  width: number;
+  height: number;
+}
+
+/**
+ * Encrypted key for a single recipient (from encryptConversationKeyForRecipients).
+ */
+export interface EncryptedKeyForRecipient {
+  userId: string;
+  encryptedKey: string;
+  publicKeyVersion: string;
+}
+
+/**
+ * A public key input for prepareConversationKeys.
+ *
+ * Represents a single public key version for a user, as returned by the
+ * X API `GET /2/dm/encryption/public_keys` endpoint.
+ *
+ * Pass the full array — the SDK groups by userId and picks the latest
+ * version per user automatically.
+ */
+export interface PublicKeyInput {
+  /** The user's user ID (snowflake string). */
+  userId: string;
+  /** Base64-encoded identity public key (SEC1 or SPKI). */
+  publicKey: string;
+  /** Key version string from the X API. */
+  keyVersion: string;
+}
+
+/**
+ * Result from prepareConversationKeys.
+ *
+ * Contains everything needed to POST to the X API for group creation
+ * or key initialization — no further transformation required.
+ */
+export interface PreparedConversationKeys {
+  /** Raw conversation key bytes (32 bytes). Store locally for encrypting messages. */
+  conversationKey: Uint8Array;
+  /** Timestamp-based version string for this conversation key. */
+  conversationKeyVersion: string;
+  /** Encrypted keys for each participant, ready to POST to the API. */
+  participantKeys: EncryptedKeyForRecipient[];
+}
+
+/**
+ * Entity descriptor tuple: [startByteOffset, endByteOffset, entityType].
+ * entityType is one of: "url", "mention", "hashtag", "cashtag", "email", "address", "phoneNumber".
+ */
+export type EntityTuple = [number, number, string];
+
+// NOTE: AttachmentDescriptor uses snake_case as it's part of the Thrift protocol
+// and matches the wire format used by the X API
+/**
+ * Attachment descriptor object.
+ */
+export type AttachmentDescriptor =
+  | { attachment_type: 'media'; media_hash_key: string; width: number; height: number; filesize_bytes: number; filename: string; media_type?: number; duration_millis?: number }
+  | { attachment_type: 'url'; url: string; display_title?: string }
+  | { attachment_type: 'post'; rest_id?: string; post_url?: string };
+
+/**
+ * Decrypted event from the SDK.
+ * Meta fields (sequenceId, id, senderId, etc.) are flattened to top level.
+ */
+export interface Event {
+  /** Discriminates which event variant this is. */
+  type: 'message' | 'keyChange' | 'typing' | 'readReceipt' | 'groupChange' | 
+        'messageDeleted' | 'memberDeleted' | 'conversationDeleted' | 
+        'settingsChange' | 'markedUnread' | 'failure' | 'unknown';
+  /** Flattened from meta: unique sequence ID for ordering. */
+  sequenceId?: string;
+  /** Flattened from meta: unique message/event ID (snowflake string). */
+  id?: string;
+  /** Flattened from meta: sender's user ID (snowflake string). */
+  senderId?: string;
+  /** Flattened from meta: conversation ID (snowflake string). */
+  conversationId?: string;
+  /** Flattened from meta: event creation timestamp in milliseconds. */
+  createdAtMsec?: number;
+  /** For message events: the decrypted message content. */
+  content?: MessageContent;
+  /** Whether the event signature was verified. */
+  verified?: boolean;
+  /** For message events: attachments included with the message (if any). */
+  attachments?: AttachmentInfo[];
+  /** For message events: media hash keys derived from attachments (if any). */
+  mediaHashes?: MediaHashReference[];
+  /** For keyChange events: the new conversation key version (a snowflake/timestamp string). */
+  keyVersion?: string;
+  /** For keyChange events: encrypted conversation keys, one per participant. */
+  participantKeys?: ParticipantKey[];
+  /** Index signature for additional event-specific fields. */
+  [key: string]: any;
+}
+
+/**
+ * Decrypted message content. Permissive convenience shape: `contentType`
+ * discriminates which fields are present. For the precisely-typed discriminated
+ * union, import `MessageContent` from the package's `./types` entry.
+ */
+export interface MessageContent {
+  /**
+   * Discriminates the content kind: 'text', 'reaction', 'reactionRemoved',
+   * 'edit', 'markRead', 'markUnread', or 'unknown'.
+   */
+  contentType?: string;
+  /** Present on 'text' content. */
+  text?: string;
+  /** Present on 'edit' content. */
+  newText?: string;
+  /** Present on 'reaction' and 'reactionRemoved' content. */
+  emoji?: string;
+  /** Present on 'reaction', 'reactionRemoved', and 'edit' content. */
+  targetMessageId?: string;
+  /** Present on 'text' content: rich-text entities. */
+  entities?: unknown[];
+  /** Present on 'text' content: message attachments. */
+  attachments?: unknown[];
+  /** Present on 'text' content: reply-to preview. */
+  replyingToPreview?: unknown;
+  /** Present on 'text' content: forwarded message metadata. */
+  forwardedMessage?: unknown;
+  /** Present on 'text' content: the surface the message was sent from. */
+  sentFrom?: string | number;
+  /** Present on 'text' content: quick-reply payload. */
+  quickReply?: unknown;
+  /** Present on 'text' content: call-to-action buttons. */
+  ctas?: unknown[];
+  /** Present on 'unknown' content: the unrecognized numeric type id. */
+  typeId?: number;
+  /** Index signature for additional content-specific fields. */
+  [key: string]: any;
+}
+
+export interface ParticipantKey {
+  userId: string;
+  encryptedKey: string;
+  publicKeyVersion: string;
+}
+
+export interface MediaHashReference {
+  source: string;
+  mediaHashKey: string;
+}
+
+/**
+ * An attachment on a decrypted message. Permissive convenience shape: the
+ * fields are flattened and `attachmentType` discriminates which apply. For the
+ * precisely-typed per-variant union, import `AttachmentInfo` from the package's
+ * `./types` entry.
+ */
+export interface AttachmentInfo {
+  /** One of: 'media', 'url', 'post', 'unifiedCard', 'money'. */
+  attachmentType?: string;
+  mediaHashKey?: string;
+  dimensions?: { width?: number; height?: number };
+  mediaType?: string;
+  durationMillis?: number;
+  filesizeBytes?: number;
+  filename?: string;
+  attachmentId?: string;
+  legacyMediaUrlHttps?: string;
+  legacyMediaPreviewUrl?: string;
+  url?: string;
+  bannerImageMediaHashKey?: string;
+  faviconImageMediaHashKey?: string;
+  displayTitle?: string;
+  restId?: string;
+  postUrl?: string;
+  fallbackText?: string;
+  /** Index signature for additional attachment-specific fields. */
+  [key: string]: any;
+}
+
+/**
+ * Options for creating a Chat instance with Juicebox integration.
+ */
+export interface CreateChatOptions {
+  /** 
+   * Juicebox configuration JSON from the X API.
+   * Obtain this from: GET /2/dm/encryption/juicebox/config
+   */
+  juiceboxConfig: string;
+  
+  /**
+   * Async function to get a Juicebox auth token for a realm.
+   * 
+   * @param realmId - Hex-encoded realm ID
+   * @returns Promise resolving to the auth token string
+   * 
+   * @example
+   * async (realmId) => {
+   *   const response = await fetch(`/api/juicebox/token?realm=${realmId}`, {
+   *     headers: { Authorization: `Bearer ${userToken}` }
+   *   });
+   *   return response.text();
+   * }
+   */
+  getAuthToken: (realmId: string) => Promise<string>;
+
+  /**
+   * Optional number of PIN guesses allowed before lockout.
+   */
+  maxGuessCount?: number;
+}
+
+/**
+ * Common interface for all Chat methods (shared by Chat and ChatWithJuicebox).
+ *
+ * The raw WASM `Chat` class provides only crypto operations.
+ * `ChatWithJuicebox` (returned by `createChat()`) adds Juicebox lifecycle methods.
+ */
+interface ChatCrypto {
+  /** When enabled, `decryptEvent` throws for unverified messages. */
+  setRejectUnverified(reject: boolean): void;
+
+  /** Generate new keypairs and return the registration payload. */
+  generateKeypairs(): PublicKeyRegistrationPayload;
+
+  /** Get current public keys. */
+  getPublicKeys(): PublicKeys;
+
+  /** Get the fingerprint of the loaded identity public key for out-of-band verification. */
+  getPublicKeyFingerprint(): string;
+
+  /** Returns true when both identity and signing keys are loaded. */
+  isUnlocked(): boolean;
+
+  /** Returns true when the identity key is loaded (sufficient for decryption). */
+  hasIdentityKey(): boolean;
+
+  /** Clear keys from memory. */
+  lock(): void;
+
+  /** Decrypt an encrypted conversation key (ECIES). */
+  decryptConversationKey(encryptedKeyB64: string): Uint8Array;
+
+  /** Generate a new conversation key. */
+  generateConversationKey(): Uint8Array;
+
+  /** Extract and decrypt conversation keys from raw KeyChange event strings. */
+  extractConversationKeys(events: string[]): ConversationKeyResult;
+
+  /**
+   * Decrypt multiple events in batch (recommended API).
+   *
+   * This method:
+   * 1. Extracts conversation keys from any KeyChange events
+   * 2. For each message, finds the correct signing key by matching userId + version
+   * 3. Decrypts the message using the appropriate conversation key
+   *
+   * @param events - Raw base64-encoded event strings from the webhook
+   * @param signingKeys - All known signing keys for all participants (with userId)
+   */
+  decryptEvents(events: string[], signingKeys?: SigningKeyEntry[]): DecryptEventsResult;
+
+  /** Decrypt a raw webhook event payload. */
+  decryptEvent(eventB64: string, conversationKeys: ConversationKeyMap, signingKeys?: SigningKeyEntry[]): Event;
+
+  /** Sign data. Returns raw signature bytes (64 bytes). */
+  sign(data: Uint8Array): Uint8Array;
+
+  /** Verify a signature. */
+  verify(publicKeyB64: string, signature: Uint8Array, data: Uint8Array): boolean;
+
+  /** Encrypt a text message. */
+  encryptMessage(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
+
+  /** Encrypt a reply. */
+  encryptReply(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, replyToSequenceId: string, replyToSenderId?: number | null, replyToText?: string | null, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, replyToEntities?: EntityTuple[] | null, replyToAttachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
+
+  /** Encrypt a reaction-add. */
+  encryptAddReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
+
+  /** Encrypt a reaction-remove. */
+  encryptRemoveReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
+
+  /** Encrypt a stream (e.g. media). */
+  encryptStream(plaintext: Uint8Array, conversationKey: Uint8Array): Uint8Array;
+
+  /** Decrypt a streaming-encrypted payload (e.g. media). */
+  decryptStream(encrypted: Uint8Array, conversationKey: Uint8Array): Uint8Array;
+
+  /** Encrypt a UTF-8 string and return base64 ciphertext. Use for metadata fields like group names. */
+  encrypt(plaintext: string, conversationKey: Uint8Array): string;
+
+  /** Decrypt a base64-encoded ciphertext and return the UTF-8 plaintext. Use for metadata fields like group names. */
+  decrypt(ciphertextB64: string, conversationKey: Uint8Array): string;
+
+  /** Encrypt a conversation key for one or more recipients. */
+  encryptConversationKeyForRecipients(conversationKey: Uint8Array, recipients: RecipientInput[]): EncryptedKeyForRecipient[];
+
+  /**
+   * Prepare conversation keys for all participants in one call.
+   *
+   * This is the recommended method for both group creation and key
+   * initialization. Pass the flat array of public keys from the X API;
+   * the SDK groups by userId, picks the latest version per user,
+   * generates a fresh conversation key, and encrypts it for everyone.
+   *
+   * @param publicKeys - Array of PublicKeyInput from the X API
+   * @returns PreparedConversationKeys ready to POST to the API
+   */
+  prepareConversationKeys(publicKeys: PublicKeyInput[]): PreparedConversationKeys;
+
+  /** Build and sign a GroupMemberAdd action signature. */
+  signAddMembers(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, newMemberIds: string[], currentMemberIds: string[], currentAdminIds: string[], currentPendingMemberIds: string[], conversationKeyVersion: string, currentTitle?: string | null, currentAvatarUrl?: string | null, currentTtlMsec?: number | null): ActionSignature;
+
+  /** Build and sign a ConversationKeyChange action signature. */
+  signKeyChange(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, conversationKeyVersion: string, conversationKey: Uint8Array): ActionSignature;
+}
+
+/** Internal crypto engine wrapped by ChatWithJuicebox. Not part of the public API. */
+declare class Chat implements ChatCrypto {
+  constructor();
+
+  setRejectUnverified(reject: boolean): void;
+  generateKeypairs(): PublicKeyRegistrationPayload;
+  /** Set the registered public key version (call after unlock()). */
+  setKeyVersion(version: string): void;
+  getPublicKeys(): PublicKeys;
+  getPublicKeyFingerprint(): string;
+  isUnlocked(): boolean;
+  hasIdentityKey(): boolean;
+  lock(): void;
+  decryptConversationKey(encryptedKeyB64: string): Uint8Array;
+  generateConversationKey(): Uint8Array;
+  extractConversationKeys(events: string[]): ConversationKeyResult;
+  decryptEvents(events: string[], signingKeys?: SigningKeyEntry[]): DecryptEventsResult;
+  decryptEvent(eventB64: string, conversationKeys: ConversationKeyMap, signingKeys?: SigningKeyEntry[]): Event;
+  sign(data: Uint8Array): Uint8Array;
+  verify(publicKeyB64: string, signature: Uint8Array, data: Uint8Array): boolean;
+  verifyKeyBinding(identityPublicKeyB64: string, signingPublicKeyB64: string, identityPublicKeySignatureB64: string): boolean;
+  encryptMessage(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
+  encryptReply(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, replyToSequenceId: string, replyToSenderId?: number | null, replyToText?: string | null, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, replyToEntities?: EntityTuple[] | null, replyToAttachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
+  encryptAddReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
+  encryptRemoveReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
+  encryptStream(plaintext: Uint8Array, conversationKey: Uint8Array): Uint8Array;
+  decryptStream(encrypted: Uint8Array, conversationKey: Uint8Array): Uint8Array;
+  encrypt(plaintext: string, conversationKey: Uint8Array): string;
+  decrypt(ciphertextB64: string, conversationKey: Uint8Array): string;
+  encryptConversationKeyForRecipients(conversationKey: Uint8Array, recipients: RecipientInput[]): EncryptedKeyForRecipient[];
+  prepareConversationKeys(publicKeys: PublicKeyInput[]): PreparedConversationKeys;
+  signAddMembers(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, newMemberIds: string[], currentMemberIds: string[], currentAdminIds: string[], currentPendingMemberIds: string[], conversationKeyVersion: string, currentTitle?: string | null, currentAvatarUrl?: string | null, currentTtlMsec?: number | null): ActionSignature;
+  signKeyChange(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, conversationKeyVersion: string, conversationKey: Uint8Array): ActionSignature;
+}
+
+/**
+ * Chat with integrated Juicebox key storage (returned by `createChat()`).
+ *
+ * Key material is managed inside the Juicebox layer.
+ */
+export declare class ChatWithJuicebox implements ChatCrypto {
+  /**
+   * Register keys with Juicebox. The PIN must meet strength requirements
+   * (4+ characters, not a single repeated character or sequential digit
+   * run). Pass a Uint8Array to be able to zero the buffer afterwards.
+   */
+  setup(pin: string | Uint8Array): Promise<PublicKeys>;
+  unlock(pin: string | Uint8Array): Promise<void>;
+  delete(): Promise<void>;
+  /** The new PIN must meet the same strength requirements as setup(). */
+  changePin(oldPin: string | Uint8Array, newPin: string | Uint8Array): Promise<void>;
+  updateConfig(juiceboxConfig: string): void;
+
+  setRejectUnverified(reject: boolean): void;
+  generateKeypairs(): PublicKeyRegistrationPayload;
+  /** Set the registered public key version (call after unlock()). */
+  setKeyVersion(version: string): void;
+  getPublicKeys(): PublicKeys;
+  getPublicKeyFingerprint(): string;
+  isUnlocked(): boolean;
+  hasIdentityKey(): boolean;
+  lock(): void;
+  decryptConversationKey(encryptedKeyB64: string): Uint8Array;
+  generateConversationKey(): Uint8Array;
+  extractConversationKeys(events: string[]): ConversationKeyResult;
+  decryptEvents(events: string[], signingKeys?: SigningKeyEntry[]): DecryptEventsResult;
+  decryptEvent(eventB64: string, conversationKeys: ConversationKeyMap, signingKeys?: SigningKeyEntry[]): Event;
+  sign(data: Uint8Array): Uint8Array;
+  verify(publicKeyB64: string, signature: Uint8Array, data: Uint8Array): boolean;
+  verifyKeyBinding(identityPublicKeyB64: string, signingPublicKeyB64: string, identityPublicKeySignatureB64: string): boolean;
+  encryptMessage(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
+  encryptReply(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, replyToSequenceId: string, replyToSenderId?: number | null, replyToText?: string | null, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, replyToEntities?: EntityTuple[] | null, replyToAttachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
+  encryptAddReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
+  encryptRemoveReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
+  encryptStream(plaintext: Uint8Array, conversationKey: Uint8Array): Uint8Array;
+  decryptStream(encrypted: Uint8Array, conversationKey: Uint8Array): Uint8Array;
+  encrypt(plaintext: string, conversationKey: Uint8Array): string;
+  decrypt(ciphertextB64: string, conversationKey: Uint8Array): string;
+  encryptConversationKeyForRecipients(conversationKey: Uint8Array, recipients: RecipientInput[]): EncryptedKeyForRecipient[];
+  prepareConversationKeys(publicKeys: PublicKeyInput[]): PreparedConversationKeys;
+  signAddMembers(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, newMemberIds: string[], currentMemberIds: string[], currentAdminIds: string[], currentPendingMemberIds: string[], conversationKeyVersion: string, currentTitle?: string | null, currentAvatarUrl?: string | null, currentTtlMsec?: number | null): ActionSignature;
+  signKeyChange(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, conversationKeyVersion: string, conversationKey: Uint8Array): ActionSignature;
+}
+
+/**
+ * Create a Chat instance with integrated Juicebox key storage.
+ *
+ * Each call creates an independent instance with its own Juicebox client.
+ */
+export declare function createChat(options: CreateChatOptions): Promise<ChatWithJuicebox>;
+
+// Utility Functions
+
+/** Encode bytes to base64 string. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+
+/** Decode base64 string to bytes. Returns undefined if invalid. */
+export declare function base64ToBytes(b64: string): Uint8Array | undefined;
+
+/** Encode bytes to lowercase hex string. */
+export declare function bytesToHex(bytes: Uint8Array): string;
+
+/** Decode hex string to bytes. Returns undefined if invalid. */
+export declare function hexToBytes(hex: string): Uint8Array | undefined;
+
+/** Detect MIME type from file bytes. Returns the MIME type string or undefined. */
+export declare function detectMimeType(bytes: Uint8Array): string | undefined;
+
+/** Detect image dimensions from file bytes. Returns { width, height } or null. */
+export declare function detectImageDimensions(bytes: Uint8Array): ImageDimensions | null;