@xdevplatform/chat-xdk 0.1.0

package/index.js

@@ -0,0 +1,394 @@
+/**
+ * X Chat SDK - JavaScript Wrapper
+ *
+ * Juicebox key-storage lifecycle is handled entirely in this JS layer.
+ * The Rust WASM `Chat` is a pure crypto engine that never touches
+ * globalThis or module-level singletons.
+ *
+ * Each `ChatWithJuicebox` instance holds its **own** Juicebox client, so
+ * multiple users / configs can coexist safely in the same runtime.
+ */
+
+function isNodeRuntime() {
+  return (
+    typeof process !== "undefined" &&
+    Boolean(process.versions && process.versions.node)
+  );
+}
+
+const REGISTER_REASON_BY_VALUE = {
+  0: "InvalidAuth",
+  1: "UpgradeRequired",
+  2: "RateLimitExceeded",
+  3: "Assertion",
+  4: "Transient",
+};
+
+const RECOVER_REASON_BY_VALUE = {
+  0: "InvalidPin",
+  1: "NotRegistered",
+  2: "InvalidAuth",
+  3: "UpgradeRequired",
+  4: "RateLimitExceeded",
+  5: "Assertion",
+  6: "Transient",
+};
+
+const MIN_PIN_LENGTH = 4;
+
+function toPinBytes(pin) {
+  return typeof pin === 'string' ? new TextEncoder().encode(pin) : pin;
+}
+
+/**
+ * Validate PIN strength for new registrations: at least MIN_PIN_LENGTH
+ * characters, not a single repeated character, not an ascending or
+ * descending run of digits. Never applied on unlock.
+ */
+function validatePinStrength(pinBytes) {
+  if (pinBytes.length < MIN_PIN_LENGTH) {
+    throw new Error(`Weak PIN: must be at least ${MIN_PIN_LENGTH} characters`);
+  }
+  if (pinBytes.every((b) => b === pinBytes[0])) {
+    throw new Error('Weak PIN: must not be a single repeated character');
+  }
+  const allDigits = pinBytes.every((b) => b >= 0x30 && b <= 0x39);
+  let ascending = true;
+  let descending = true;
+  for (let i = 1; i < pinBytes.length; i++) {
+    if (pinBytes[i] !== pinBytes[i - 1] + 1) ascending = false;
+    if (pinBytes[i] !== pinBytes[i - 1] - 1) descending = false;
+  }
+  if (allDigits && (ascending || descending)) {
+    throw new Error('Weak PIN: must not be a sequential run of digits');
+  }
+}
+
+function formatJuiceboxError(err, reasonMap) {
+  if (!err) {
+    return "Unknown Juicebox error";
+  }
+  const reasonValue = err.reason ?? err.reasonCode ?? err.code;
+  const reason =
+    typeof reasonValue === "number" ? reasonMap[reasonValue] : reasonValue;
+  const guessesRemaining =
+    err.guesses_remaining ?? err.guessesRemaining ?? err.guesses;
+  const parts = [];
+  if (reason) {
+    parts.push(`reason=${reason}`);
+  }
+  if (guessesRemaining !== undefined) {
+    parts.push(`guesses_remaining=${guessesRemaining}`);
+  }
+  if (!parts.length) {
+    return `Unknown Juicebox error: ${String(err)}`;
+  }
+  return parts.join(" ");
+}
+
+async function initWasmModule() {
+  let wasmModule;
+  let init;
+  if (isNodeRuntime()) {
+    const { createRequire } = await import("module");
+    const require = createRequire(import.meta.url);
+    wasmModule = require("./pkg/chat_xdk_wasm.js");
+    init =
+      wasmModule?.default ||
+      wasmModule?.init ||
+      wasmModule?.__wbindgen_init;
+    if (typeof init !== "function") {
+      throw new Error("WASM init function not found in chat_xdk_wasm module.");
+    }
+    const fs = await import("fs");
+    const wasmUrl = new URL("./pkg/chat_xdk_wasm_bg.wasm", import.meta.url);
+    let wasmBytes;
+    try {
+      wasmBytes = fs.readFileSync(wasmUrl);
+    } catch (err) {
+      const { fileURLToPath } = await import("url");
+      wasmBytes = fs.readFileSync(fileURLToPath(wasmUrl));
+    }
+    await init({ module_or_path: wasmBytes });
+  } else {
+    wasmModule = await import("./pkg/chat_xdk_wasm.js");
+    init =
+      wasmModule?.default ||
+      wasmModule?.init ||
+      wasmModule?.__wbindgen_init;
+    if (typeof init !== "function") {
+      throw new Error("WASM init function not found in chat_xdk_wasm module.");
+    }
+    await init();
+  }
+  return wasmModule;
+}
+
+async function loadJuiceboxSdk() {
+  if (isNodeRuntime()) {
+    const juiceboxBg = await import("juicebox-sdk/juicebox-sdk_bg.js");
+    const { createRequire } = await import("module");
+    const require = createRequire(import.meta.url);
+    const fs = await import("fs");
+    const wasmPath = require.resolve("juicebox-sdk/juicebox-sdk_bg.wasm");
+    const wasmBytes = fs.readFileSync(wasmPath);
+    const { instance } = await WebAssembly.instantiate(wasmBytes, {
+      "./juicebox-sdk_bg.js": juiceboxBg,
+    });
+    juiceboxBg.__wbg_set_wasm(instance.exports);
+    return juiceboxBg;
+  }
+  return await import("juicebox-sdk");
+}
+
+// ChatWithJuicebox — JS wrapper that owns both a WasmChat and a Juicebox client
+
+/**
+ * JS wrapper that combines the Rust WASM crypto engine with per-instance
+ * Juicebox key storage.  Every crypto method is forwarded transparently;
+ * setup/unlock/delete/changePin/updateConfig are handled in pure JS.
+ */
+export class ChatWithJuicebox {
+  /** @type {import('./pkg/chat_xdk_wasm.js').Chat} */
+  #inner;
+  #juiceboxClient;
+  #numGuesses;
+  #JuiceboxConfiguration;
+  #JuiceboxClient;
+
+  constructor(wasmChat, juiceboxClient, numGuesses, JuiceboxConfiguration, JuiceboxClientCtor) {
+    this.#inner = wasmChat;
+    this.#juiceboxClient = juiceboxClient;
+    this.#numGuesses = numGuesses;
+    this.#JuiceboxConfiguration = JuiceboxConfiguration;
+    this.#JuiceboxClient = JuiceboxClientCtor;
+  }
+
+  // Juicebox lifecycle (JS-only — no globalThis, no singletons)
+
+  /**
+   * Register existing keys with Juicebox. Call generateKeypairs() first.
+   * The PIN must meet minimum strength requirements (4+ characters, not a
+   * single repeated character or a sequential digit run). Accepts a string
+   * or a Uint8Array; pass a Uint8Array if you want to zero it afterwards.
+   */
+  async setup(pin) {
+    const pinBytes = toPinBytes(pin);
+    const ownsPin = typeof pin === 'string';
+    validatePinStrength(pinBytes);
+    const secretBytes = this.#inner.exportKeys();
+    try {
+      await this.#juiceboxClient.register(
+        pinBytes,
+        secretBytes,
+        new Uint8Array(0),
+        this.#numGuesses,
+      );
+    } catch (err) {
+      throw new Error(`Juicebox register failed: ${formatJuiceboxError(err, REGISTER_REASON_BY_VALUE)}`);
+    } finally {
+      secretBytes.fill(0);
+      if (ownsPin) pinBytes.fill(0);
+    }
+    return this.#inner.getPublicKeys();
+  }
+
+  /**
+   * Unlock: Recover keys from Juicebox using PIN (string or Uint8Array).
+   * No strength validation — existing registrations must stay recoverable.
+   */
+  async unlock(pin) {
+    const pinBytes = toPinBytes(pin);
+    const ownsPin = typeof pin === 'string';
+    let secretBytes;
+    try {
+      secretBytes = await this.#juiceboxClient.recover(pinBytes, new Uint8Array(0));
+    } catch (err) {
+      throw new Error(`Juicebox recovery failed: ${formatJuiceboxError(err, RECOVER_REASON_BY_VALUE)}`);
+    } finally {
+      if (ownsPin) pinBytes.fill(0);
+    }
+    try {
+      this.#inner.importKeys(secretBytes);
+    } finally {
+      secretBytes.fill(0);
+    }
+  }
+
+  /** Delete keys from Juicebox. Warning: Irreversible. */
+  async delete() {
+    await this.#juiceboxClient.delete();
+    this.#inner.lock();
+  }
+
+  /** Re-register keys with a new PIN. The new PIN must meet strength requirements. */
+  async changePin(oldPin, newPin) {
+    const newPinBytes = toPinBytes(newPin);
+    const ownsNewPin = typeof newPin === 'string';
+    validatePinStrength(newPinBytes);
+    await this.unlock(oldPin);
+    const secretBytes = this.#inner.exportKeys();
+    try {
+      await this.#juiceboxClient.register(
+        newPinBytes,
+        secretBytes,
+        new Uint8Array(0),
+        this.#numGuesses,
+      );
+    } catch (err) {
+      throw new Error(`Juicebox re-registration failed: ${formatJuiceboxError(err, REGISTER_REASON_BY_VALUE)}`);
+    } finally {
+      secretBytes.fill(0);
+      if (ownsNewPin) newPinBytes.fill(0);
+    }
+  }
+
+  /** Update Juicebox config (e.g. to refresh auth tokens). Re-creates the client. */
+  updateConfig(juiceboxConfig) {
+    const configValue = JSON.parse(juiceboxConfig);
+    const config = new this.#JuiceboxConfiguration(configValue);
+    this.#juiceboxClient = new this.#JuiceboxClient(config, []);
+  }
+
+  // Forwarded crypto methods — delegate to inner WasmChat
+
+  setRejectUnverified(reject) { return this.#inner.setRejectUnverified(reject); }
+  generateKeypairs() { return this.#inner.generateKeypairs(); }
+  setKeyVersion(version) { return this.#inner.setKeyVersion(version); }
+  getPublicKeys() { return this.#inner.getPublicKeys(); }
+  getPublicKeyFingerprint() { return this.#inner.getPublicKeyFingerprint(); }
+  isUnlocked() { return this.#inner.isUnlocked(); }
+  hasIdentityKey() { return this.#inner.hasIdentityKey(); }
+  lock() { return this.#inner.lock(); }
+  decryptConversationKey(b64) { return this.#inner.decryptConversationKey(b64); }
+  generateConversationKey() { return this.#inner.generateConversationKey(); }
+  extractConversationKeys(events) { return this.#inner.extractConversationKeys(events); }
+  decryptEvent(eventB64, conversationKeys, signingKeys) {
+    return this.#inner.decryptEvent(eventB64, conversationKeys, signingKeys ?? []);
+  }
+  decryptEvents(events, signingKeys) {
+    return this.#inner.decryptEvents(events, signingKeys ?? []);
+  }
+  sign(data) { return this.#inner.sign(data); }
+  verify(publicKeyB64, signature, data) { return this.#inner.verify(publicKeyB64, signature, data); }
+  verifyKeyBinding(identityPublicKeyB64, signingPublicKeyB64, identityPublicKeySignatureB64) {
+    return this.#inner.verifyKeyBinding(identityPublicKeyB64, signingPublicKeyB64, identityPublicKeySignatureB64);
+  }
+  encryptMessage(...args) { return this.#inner.encryptMessage(...args); }
+  encryptReply(...args) { return this.#inner.encryptReply(...args); }
+  encryptAddReaction(...args) { return this.#inner.encryptAddReaction(...args); }
+  encryptRemoveReaction(...args) { return this.#inner.encryptRemoveReaction(...args); }
+  encryptStream(plaintext, key) { return this.#inner.encryptStream(plaintext, key); }
+  decryptStream(encrypted, key) { return this.#inner.decryptStream(encrypted, key); }
+  encrypt(plaintext, key) { return this.#inner.encrypt(plaintext, key); }
+  decrypt(ciphertext, key) { return this.#inner.decrypt(ciphertext, key); }
+  encryptConversationKeyForRecipients(key, recipients) {
+    return this.#inner.encryptConversationKeyForRecipients(key, recipients);
+  }
+  prepareConversationKeys(publicKeys) {
+    return this.#inner.prepareConversationKeys(publicKeys);
+  }
+  signAddMembers(...args) { return this.#inner.signAddMembers(...args); }
+  signKeyChange(...args) { return this.#inner.signKeyChange(...args); }
+}
+
+/**
+ * Create a Chat instance with integrated Juicebox support.
+ * 
+ * @param {Object} options - Configuration options
+ * @param {string} options.juiceboxConfig - Juicebox configuration JSON from X API
+ * @param {Function} options.getAuthToken - Async function to get auth token for a realm
+ *                                          Signature: (realmId: string) => Promise<string>
+ * @returns {Promise<Chat>} Initialized Chat instance
+ * 
+ * @example
+ * const chat = await createChat({
+ *   juiceboxConfig: configFromXApi,
+ *   getAuthToken: async (realmId) => {
+ *     const response = await fetch('/api/juicebox/token?realm=' + realmId);
+ *     return response.text();
+ *   },
+ * });
+ * 
+ * // First time setup
+ * const payload = chat.generateKeypairs();
+ * // POST payload to X API, then call setup once you have juiceboxConfig
+ * await chat.setup("2580");
+ * 
+ * // Subsequent sessions
+ * await chat.unlock("2580");
+ */
+export async function createChat(options) {
+  const { juiceboxConfig, getAuthToken, maxGuessCount } = options;
+
+  if (!juiceboxConfig) {
+    throw new Error('juiceboxConfig is required');
+  }
+  if (!getAuthToken || typeof getAuthToken !== 'function') {
+    throw new Error('getAuthToken must be an async function');
+  }
+
+  // Load Juicebox WASM SDK
+  let JuiceboxClientCtor;
+  let JuiceboxConfiguration;
+  try {
+    const juiceboxModule = await loadJuiceboxSdk();
+    JuiceboxClientCtor = juiceboxModule.Client;
+    JuiceboxConfiguration = juiceboxModule.Configuration;
+  } catch (e) {
+    throw new Error(
+      'Failed to load juicebox-sdk. ' +
+      'Build it from https://github.com/juicebox-systems/juicebox-sdk:\n' +
+      '  cd juicebox-sdk/rust/sdk/bridge/wasm && wasm-pack build --target nodejs --out-dir pkg --out-name juicebox-sdk\n' +
+      '  npm install /path/to/juicebox-sdk/rust/sdk/bridge/wasm/pkg\n' +
+      'Original error: ' + e.message
+    );
+  }
+  if (!JuiceboxConfiguration) {
+    throw new Error('juicebox-sdk Configuration export is missing');
+  }
+
+  // The juicebox-sdk WASM resolves `JuiceboxGetAuthToken` as a bare-name
+  // global on every register/recover/delete call (not just construction).
+  // We must keep it set for the lifetime of the client.
+  globalThis.JuiceboxGetAuthToken = async (realmId) => {
+    const realmIdHex =
+      typeof realmId === "string"
+        ? realmId
+        : Array.from(realmId)
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+    return await getAuthToken(realmIdHex);
+  };
+
+  const configValue = JSON.parse(juiceboxConfig);
+  const config = new JuiceboxConfiguration(configValue);
+  const juiceboxClient = new JuiceboxClientCtor(config, []);
+
+  const numGuesses =
+    Number.isFinite(maxGuessCount) && Number(maxGuessCount) > 0
+      ? Math.floor(Number(maxGuessCount))
+      : 5;
+
+  // Load Rust WASM crypto engine
+  const wasmModule = await initWasmModule();
+  const wasmChat = new wasmModule.Chat();
+
+  return new ChatWithJuicebox(
+    wasmChat,
+    juiceboxClient,
+    numGuesses,
+    JuiceboxConfiguration,
+    JuiceboxClientCtor,
+  );
+}
+
+// Re-export utility functions.
+export {
+  bytesToBase64,
+  base64ToBytes,
+  bytesToHex,
+  hexToBytes,
+  detectMimeType,
+  detectImageDimensions,
+} from './pkg/chat_xdk_wasm.js';

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@xdevplatform/chat-xdk",
+  "version": "0.1.0",
+  "description": "X Chat SDK - End-to-end encryption for X Direct Messages",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "pkg/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "juicebox-sdk": "^0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "juicebox-sdk": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "x",
+    "twitter",
+    "chat",
+    "encryption",
+    "e2ee",
+    "end-to-end-encryption",
+    "dm",
+    "direct-messages"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xdevplatform/chat-xdk"
+  }
+}