@xdevplatform/chat-xdk 0.1.0 → 0.2.1

package/index.js

@@ -5,8 +5,14 @@
  * 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.
+ * Each `ChatWithJuicebox` instance holds its own Juicebox client, but the
+ * juicebox-sdk WASM resolves its auth-token callback through a single
+ * process-global (`JuiceboxGetAuthToken`). Every Juicebox operation re-arms
+ * that global with its own instance's token getter just before running, so
+ * *sequential* use of multiple instances in one runtime is correct.
+ * *Concurrent* Juicebox operations across instances in one process are not
+ * supported: the last-armed instance's token getter services all in-flight
+ * calls.
  */
 
 function isNodeRuntime() {
@@ -46,11 +52,13 @@ function toPinBytes(pin) {
  * descending run of digits. Never applied on unlock.
  */
 function validatePinStrength(pinBytes) {
+  // Error messages match the native core's weak-PIN errors byte-for-byte so
+  // callers can match on them across bindings.
   if (pinBytes.length < MIN_PIN_LENGTH) {
-    throw new Error(`Weak PIN: must be at least ${MIN_PIN_LENGTH} characters`);
+    throw new Error(`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');
+    throw new Error('PIN must not be a single repeated character');
   }
   const allDigits = pinBytes.every((b) => b >= 0x30 && b <= 0x39);
   let ascending = true;
@@ -60,7 +68,7 @@ function validatePinStrength(pinBytes) {
     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');
+    throw new Error('PIN must not be a sequential run of digits');
   }
 }
 
@@ -90,9 +98,15 @@ 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");
+    // Node 18 ships WebCrypto but does not expose it on the global scope,
+    // and the wasm module's random-byte source requires globalThis.crypto.
+    if (typeof globalThis.crypto === "undefined") {
+      const { webcrypto } = await import("crypto");
+      globalThis.crypto = webcrypto;
+    }
+    // Dynamic import, not require(): the wasm glue is ESM, and require(esm)
+    // only exists on Node >= 20.19 while this package supports Node 18+.
+    wasmModule = await import("./pkg/chat_xdk_wasm.js");
     init =
       wasmModule?.default ||
       wasmModule?.init ||
@@ -141,6 +155,104 @@ async function loadJuiceboxSdk() {
   return await import("juicebox-sdk");
 }
 
+/**
+ * Resolve the PIN guess budget for Juicebox registration, matching the
+ * native bindings: a `max_guess_count` that is a non-negative integer
+ * (including 0) applies as-is; a fractional, negative, or non-numeric value
+ * falls back to the shape default — 20 for the `sdk_config` and
+ * `key_store_token_map_json` shapes, 5 otherwise. An explicit
+ * `maxGuessCount` option overrides the config under
+ * the same integer rule. Exported for tests; `createChat` calls it
+ * internally.
+ *
+ * @param {Object} configValue - Parsed Juicebox config JSON from the X API
+ * @param {number} [maxGuessCount] - Explicit override from createChat options
+ * @returns {number} The number of PIN guesses to register with
+ */
+export function resolveMaxGuessCount(configValue, maxGuessCount) {
+  if (Number.isSafeInteger(maxGuessCount) && maxGuessCount >= 0) {
+    return maxGuessCount;
+  }
+  const fromConfig = configValue?.max_guess_count;
+  if (Number.isSafeInteger(fromConfig) && fromConfig >= 0) {
+    return fromConfig;
+  }
+  return typeof configValue?.sdk_config === "string" ||
+    typeof configValue?.key_store_token_map_json === "string"
+    ? 20
+    : 5;
+}
+
+/**
+ * Derive the value to hand the Juicebox `Configuration` constructor from a
+ * parsed X API config. The `sdk_config` wrapper shape is unwrapped to its
+ * embedded SDK config JSON string (which the Juicebox constructor accepts
+ * directly); the X API `juicebox_config` object shape is unwrapped to its
+ * `key_store_token_map_json` string, which is used **verbatim** because it
+ * carries each realm's `public_key` and the server's register/recover
+ * thresholds — the realms require both; a raw realms config passes through
+ * unchanged; a bare `token_map` shape (an array of
+ * `{ key, value: { address } }` entries, no `key_store_token_map_json`) is
+ * converted to a realms config with majority recover threshold, the same
+ * derivation the native bindings apply. A non-array `token_map` is rejected
+ * here, with the same message the core parser uses, rather than handed to
+ * the Juicebox constructor to fail obscurely. Realm auth tokens are not
+ * taken from the config in this wrapper — they come from the `getAuthToken`
+ * callback.
+ */
+export function juiceboxClientConfig(configValue) {
+  if (typeof configValue?.sdk_config === "string") {
+    return configValue.sdk_config;
+  }
+  if (configValue?.key_store_token_map_json !== undefined) {
+    if (typeof configValue.key_store_token_map_json !== "string") {
+      throw new Error("key_store_token_map_json must be a string");
+    }
+    // A malformed embedded config is an error rather than a fall-through to
+    // the lossy token_map derivation, which would silently drop the realm
+    // public keys and produce configs that can never reach the recover
+    // threshold. It must parse to a JSON object — merely valid JSON like
+    // "42" or "[]" would be handed to the Juicebox constructor to fail
+    // obscurely at setup/unlock time.
+    let parsed;
+    try {
+      parsed = JSON.parse(configValue.key_store_token_map_json);
+    } catch (e) {
+      throw new Error(`Invalid key_store_token_map_json: ${e.message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("Invalid key_store_token_map_json: not a JSON object");
+    }
+    return configValue.key_store_token_map_json;
+  }
+  if (
+    configValue?.token_map !== undefined &&
+    configValue?.realms === undefined &&
+    !Array.isArray(configValue.token_map)
+  ) {
+    throw new Error("Missing token_map or sdk_config");
+  }
+  if (Array.isArray(configValue?.token_map) && configValue?.realms === undefined) {
+    const realms = configValue.token_map.map((entry) => {
+      const id = entry?.key;
+      const address = entry?.value?.address;
+      if (typeof id !== "string" || typeof address !== "string") {
+        throw new Error(
+          "Invalid token_map entry: expected { key, value: { address } }",
+        );
+      }
+      return { id, address };
+    });
+    return {
+      realms,
+      register_threshold: realms.length,
+      recover_threshold: Math.floor(realms.length / 2) + 1,
+      pin_hashing_mode: "Standard2019",
+    };
+  }
+  return configValue;
+}
+
 // ChatWithJuicebox — JS wrapper that owns both a WasmChat and a Juicebox client
 
 /**
@@ -153,18 +265,36 @@ export class ChatWithJuicebox {
   #inner;
   #juiceboxClient;
   #numGuesses;
+  // The raw `maxGuessCount` createChat option (undefined when not provided),
+  // kept so updateConfig re-resolves the budget under the same override
+  // semantics as construction: an explicit option keeps winning.
+  #maxGuessCountOverride;
   #JuiceboxConfiguration;
   #JuiceboxClient;
+  // Points the process-global `JuiceboxGetAuthToken` at this instance's token
+  // getter. Called before every Juicebox network operation so sequential use
+  // of multiple instances presents the right tokens (last-armed wins).
+  #armAuthTokenHook;
 
-  constructor(wasmChat, juiceboxClient, numGuesses, JuiceboxConfiguration, JuiceboxClientCtor) {
+  constructor(
+    wasmChat,
+    juiceboxClient,
+    numGuesses,
+    JuiceboxConfiguration,
+    JuiceboxClientCtor,
+    armAuthTokenHook,
+    maxGuessCountOverride,
+  ) {
     this.#inner = wasmChat;
     this.#juiceboxClient = juiceboxClient;
     this.#numGuesses = numGuesses;
+    this.#maxGuessCountOverride = maxGuessCountOverride;
     this.#JuiceboxConfiguration = JuiceboxConfiguration;
     this.#JuiceboxClient = JuiceboxClientCtor;
+    this.#armAuthTokenHook = armAuthTokenHook ?? (() => {});
   }
 
-  // Juicebox lifecycle (JS-only — no globalThis, no singletons)
+  // Juicebox lifecycle (handled in this JS layer)
 
   /**
    * Register existing keys with Juicebox. Call generateKeypairs() first.
@@ -178,6 +308,7 @@ export class ChatWithJuicebox {
     validatePinStrength(pinBytes);
     const secretBytes = this.#inner.exportKeys();
     try {
+      this.#armAuthTokenHook();
       await this.#juiceboxClient.register(
         pinBytes,
         secretBytes,
@@ -202,6 +333,7 @@ export class ChatWithJuicebox {
     const ownsPin = typeof pin === 'string';
     let secretBytes;
     try {
+      this.#armAuthTokenHook();
       secretBytes = await this.#juiceboxClient.recover(pinBytes, new Uint8Array(0));
     } catch (err) {
       throw new Error(`Juicebox recovery failed: ${formatJuiceboxError(err, RECOVER_REASON_BY_VALUE)}`);
@@ -217,6 +349,7 @@ export class ChatWithJuicebox {
 
   /** Delete keys from Juicebox. Warning: Irreversible. */
   async delete() {
+    this.#armAuthTokenHook();
     await this.#juiceboxClient.delete();
     this.#inner.lock();
   }
@@ -229,6 +362,7 @@ export class ChatWithJuicebox {
     await this.unlock(oldPin);
     const secretBytes = this.#inner.exportKeys();
     try {
+      this.#armAuthTokenHook();
       await this.#juiceboxClient.register(
         newPinBytes,
         secretBytes,
@@ -243,11 +377,16 @@ export class ChatWithJuicebox {
     }
   }
 
-  /** Update Juicebox config (e.g. to refresh auth tokens). Re-creates the client. */
+  /**
+   * Update Juicebox config (e.g. to refresh auth tokens). Re-creates the
+   * client and re-resolves the PIN guess budget from the new config; an
+   * explicit createChat `maxGuessCount` override keeps winning.
+   */
   updateConfig(juiceboxConfig) {
     const configValue = JSON.parse(juiceboxConfig);
-    const config = new this.#JuiceboxConfiguration(configValue);
+    const config = new this.#JuiceboxConfiguration(juiceboxClientConfig(configValue));
     this.#juiceboxClient = new this.#JuiceboxClient(config, []);
+    this.#numGuesses = resolveMaxGuessCount(configValue, this.#maxGuessCountOverride);
   }
 
   // Forwarded crypto methods — delegate to inner WasmChat
@@ -261,35 +400,42 @@ export class ChatWithJuicebox {
   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 ?? []);
+    return this.#inner.decryptEvent(eventB64, conversationKeys, signingKeys);
   }
   decryptEvents(events, signingKeys) {
-    return this.#inner.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); }
+  encryptMessage(params) { return this.#inner.encryptMessage(params); }
+  encryptReply(params) { return this.#inner.encryptReply(params); }
+  encryptAddReaction(params) { return this.#inner.encryptAddReaction(params); }
+  encryptRemoveReaction(params) { return this.#inner.encryptRemoveReaction(params); }
   encryptStream(plaintext, key) { return this.#inner.encryptStream(plaintext, key); }
   decryptStream(encrypted, key) { return this.#inner.decryptStream(encrypted, key); }
+  streamEncryptor(key) { return this.#inner.streamEncryptor(key); }
+  streamDecryptor(key) { return this.#inner.streamDecryptor(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);
+  prepareConversationKeyChange(params) { return this.#inner.prepareConversationKeyChange(params); }
+  prepareGroupMembersChange(params) { return this.#inner.prepareGroupMembersChange(params); }
+  prepareGroupCreate(params) { return this.#inner.prepareGroupCreate(params); }
+
+  /**
+   * Release the WASM-side crypto engine: clears key material (`lock()`) and
+   * frees the underlying WASM object. The instance must not be used
+   * afterwards. When reusing the instance, `lock()` alone suffices for key
+   * hygiene.
+   */
+  free() {
+    this.#inner.lock();
+    this.#inner.free();
   }
-  signAddMembers(...args) { return this.#inner.signAddMembers(...args); }
-  signKeyChange(...args) { return this.#inner.signKeyChange(...args); }
 }
 
 /**
@@ -299,7 +445,9 @@ export class ChatWithJuicebox {
  * @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
+ * @param {number} [options.maxGuessCount] - Optional override for the PIN guess
+ *                                           budget (see CreateChatOptions)
+ * @returns {Promise<ChatWithJuicebox>} Initialized chat instance
  * 
  * @example
  * const chat = await createChat({
@@ -328,21 +476,29 @@ export async function createChat(options) {
     throw new Error('getAuthToken must be an async function');
   }
 
-  // Load Juicebox WASM SDK
+  // Load Juicebox WASM SDK. Tests inject stub constructors through the
+  // internal `juiceboxModule` option so this flow runs without the
+  // juicebox-sdk WASM or network realms; it is not part of the public API.
   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 (options.juiceboxModule) {
+    JuiceboxClientCtor = options.juiceboxModule.Client;
+    JuiceboxConfiguration = options.juiceboxModule.Configuration;
+  } else {
+    try {
+      const juiceboxModule = await loadJuiceboxSdk();
+      JuiceboxClientCtor = juiceboxModule.Client;
+      JuiceboxConfiguration = juiceboxModule.Configuration;
+    } catch (e) {
+      throw new Error(
+        "Failed to load juicebox-sdk (an optional peer dependency). " +
+        "Install it with `npm install juicebox-sdk`, or 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');
@@ -350,8 +506,10 @@ export async function createChat(options) {
 
   // 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) => {
+  // The global is process-wide, so each instance re-arms it with its own
+  // token getter immediately before every Juicebox operation; concurrent
+  // Juicebox operations across instances are not supported (last-armed wins).
+  const authTokenHook = async (realmId) => {
     const realmIdHex =
       typeof realmId === "string"
         ? realmId
@@ -360,15 +518,16 @@ export async function createChat(options) {
             .join("");
     return await getAuthToken(realmIdHex);
   };
+  const armAuthTokenHook = () => {
+    globalThis.JuiceboxGetAuthToken = authTokenHook;
+  };
+  armAuthTokenHook();
 
   const configValue = JSON.parse(juiceboxConfig);
-  const config = new JuiceboxConfiguration(configValue);
+  const config = new JuiceboxConfiguration(juiceboxClientConfig(configValue));
   const juiceboxClient = new JuiceboxClientCtor(config, []);
 
-  const numGuesses =
-    Number.isFinite(maxGuessCount) && Number(maxGuessCount) > 0
-      ? Math.floor(Number(maxGuessCount))
-      : 5;
+  const numGuesses = resolveMaxGuessCount(configValue, maxGuessCount);
 
   // Load Rust WASM crypto engine
   const wasmModule = await initWasmModule();
@@ -380,6 +539,8 @@ export async function createChat(options) {
     numGuesses,
     JuiceboxConfiguration,
     JuiceboxClientCtor,
+    armAuthTokenHook,
+    maxGuessCount,
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdevplatform/chat-xdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "X Chat SDK - End-to-end encryption for X Direct Messages",
   "type": "module",
   "main": "index.js",
@@ -8,10 +8,14 @@
   "exports": {
     ".": "./index.js"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "files": [
     "index.js",
     "index.d.ts",
-    "pkg/**"
+    "pkg",
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public"