@waaskey/sdk 0.2.1 → 0.3.1

package/dist/index.d.cts

@@ -212,6 +212,12 @@ interface DeviceKeygenParams extends CeremonyParams {
      * this device's private aux material and are NEVER sent to the server.
      */
     pregeneratedPrimes?: string;
+    /**
+     * The FULL party roster (`roles[i]` = relay role of protocol index `i`), when the backend
+     * provides it (waas-core#131). Required to route a `parties > 2` ceremony — the plain 2-party
+     * transport cannot attribute messages from more than one peer.
+     */
+    roles?: string[];
 }
 /** Result of the device half of keygen — the device's share never leaves the device. */
 interface DeviceKeygenResult {
@@ -603,24 +609,6 @@ interface VerifiedWasmLoaderOptions {
  * ```
  */
 declare function createVerifiedClientWasmLoader(options: VerifiedWasmLoaderOptions): ClientWasmLoader;
-/**
- * Convenience loader for the Waaskey client-wasm engine — dynamically imports `@waaskey/client-wasm`
- * (the wasm-pack/bundler build, auto-initialized on import) and returns it as a {@link ClientWasmModule}:
- *
- * ```ts
- * import { Waaskey, WasmMpcCore, loadClientWasm } from '@waaskey/sdk';
- * const waaskey = new Waaskey({ apiKey, mpc: new WasmMpcCore(loadClientWasm), shareStore });
- * ```
- *
- * ⚠️ **No integrity verification (issue #40).** A bundler-target build instantiates the wasm on
- * import, so its bytes cannot be checked first. For production — where a registry compromise or
- * dependency-confusion attack on `@waaskey/client-wasm` could exfiltrate the plaintext device share
- * — use {@link createVerifiedClientWasmLoader} with a vendored `.wasm` and the pinned SHA-384 instead.
- *
- * `@waaskey/client-wasm` is an OPTIONAL peer dependency pinned to {@link CLIENT_WASM_VERSION}: install
- * it alongside the SDK in apps that create wallets. The indirect import specifier keeps it out of
- * static module resolution — so a missing install fails here with an actionable message, not at build.
- */
 declare const loadClientWasm: ClientWasmLoader;
 
 /**
@@ -1100,6 +1088,12 @@ interface WalletCeremony {
     threshold: number;
     /** Short-lived relay token (JWT) the device presents to join this keygen session; present only when relay auth is enabled. */
     relayToken?: string;
+    /**
+     * The FULL party roster: `roles[i]` is the relay role of protocol index `i` (waas-core#131).
+     * Needed by the routed transport whenever `parties > 2` (e.g. `['device', 'server', 'recovery']`);
+     * older backends omit it — the SDK then reconstructs the standard 3-party topology.
+     */
+    roles?: string[];
     /**
      * The FROST DKG round-2 encryption roster — **ed25519 keygen only** (#114, backend `IWalletCeremony`).
      * One X25519 encryption PUBLIC key (32-byte hex) per party, in `parties`/protocol-index order, so
@@ -2093,6 +2087,15 @@ declare class Wallet {
      * pre-built assertion via `options.passkeyAssertion` (with its `options.passkeyChallengeId`).
      */
     sign(digest: string, options?: SignOptions): Promise<string>;
+    /**
+     * Start this device's half of a secp sign ceremony when the wallet's sign quorum requires it.
+     * The quorum is the first `threshold` roles of the wallet's party list (#292) — for the default
+     * `[device, server, recovery]`/2 that is `[device, server]`, so the device MUST be online and
+     * co-signing. Returns `undefined` when the quorum is platform-only (or the wallet is not secp) —
+     * the POST then completes alone, unchanged. A device-present quorum without the device deps or
+     * stored share fails fast with a typed error instead of a guaranteed server-side timeout.
+     */
+    private startDeviceCoSign;
     /**
      * Send a transaction from this wallet. The platform builds the chain-specific transaction
      * and co-signs it with the 2-of-3 MPC quorum, returning the **signed raw transaction**.
@@ -2381,6 +2384,13 @@ declare class Wallets {
      * `[device, user_backup]` ceremony — one place owns the error contract so both paths stay identical.
      */
     private runKeygenParties;
+    /**
+     * Run ONE client keygen party over the right transport. A 2-party ceremony uses the plain
+     * single-peer path; anything larger MUST be roster-routed — the 2-party transport attributes
+     * every inbound message to the one configured peer, so a third party's very first message
+     * aborts the protocol with "route received message" (waas-core#131).
+     */
+    private runKeygenParty;
     /**
      * Run the device half of an ed25519 (FROST) keygen (#110) and seal the resulting `{keyPackage,
      * publicKeyPackage}` share — the EdDSA counterpart of the cggmp24 `runKeygen` branch in {@link create}.

package/dist/index.d.ts

@@ -212,6 +212,12 @@ interface DeviceKeygenParams extends CeremonyParams {
      * this device's private aux material and are NEVER sent to the server.
      */
     pregeneratedPrimes?: string;
+    /**
+     * The FULL party roster (`roles[i]` = relay role of protocol index `i`), when the backend
+     * provides it (waas-core#131). Required to route a `parties > 2` ceremony — the plain 2-party
+     * transport cannot attribute messages from more than one peer.
+     */
+    roles?: string[];
 }
 /** Result of the device half of keygen — the device's share never leaves the device. */
 interface DeviceKeygenResult {
@@ -603,24 +609,6 @@ interface VerifiedWasmLoaderOptions {
  * ```
  */
 declare function createVerifiedClientWasmLoader(options: VerifiedWasmLoaderOptions): ClientWasmLoader;
-/**
- * Convenience loader for the Waaskey client-wasm engine — dynamically imports `@waaskey/client-wasm`
- * (the wasm-pack/bundler build, auto-initialized on import) and returns it as a {@link ClientWasmModule}:
- *
- * ```ts
- * import { Waaskey, WasmMpcCore, loadClientWasm } from '@waaskey/sdk';
- * const waaskey = new Waaskey({ apiKey, mpc: new WasmMpcCore(loadClientWasm), shareStore });
- * ```
- *
- * ⚠️ **No integrity verification (issue #40).** A bundler-target build instantiates the wasm on
- * import, so its bytes cannot be checked first. For production — where a registry compromise or
- * dependency-confusion attack on `@waaskey/client-wasm` could exfiltrate the plaintext device share
- * — use {@link createVerifiedClientWasmLoader} with a vendored `.wasm` and the pinned SHA-384 instead.
- *
- * `@waaskey/client-wasm` is an OPTIONAL peer dependency pinned to {@link CLIENT_WASM_VERSION}: install
- * it alongside the SDK in apps that create wallets. The indirect import specifier keeps it out of
- * static module resolution — so a missing install fails here with an actionable message, not at build.
- */
 declare const loadClientWasm: ClientWasmLoader;
 
 /**
@@ -1100,6 +1088,12 @@ interface WalletCeremony {
     threshold: number;
     /** Short-lived relay token (JWT) the device presents to join this keygen session; present only when relay auth is enabled. */
     relayToken?: string;
+    /**
+     * The FULL party roster: `roles[i]` is the relay role of protocol index `i` (waas-core#131).
+     * Needed by the routed transport whenever `parties > 2` (e.g. `['device', 'server', 'recovery']`);
+     * older backends omit it — the SDK then reconstructs the standard 3-party topology.
+     */
+    roles?: string[];
     /**
      * The FROST DKG round-2 encryption roster — **ed25519 keygen only** (#114, backend `IWalletCeremony`).
      * One X25519 encryption PUBLIC key (32-byte hex) per party, in `parties`/protocol-index order, so
@@ -2093,6 +2087,15 @@ declare class Wallet {
      * pre-built assertion via `options.passkeyAssertion` (with its `options.passkeyChallengeId`).
      */
     sign(digest: string, options?: SignOptions): Promise<string>;
+    /**
+     * Start this device's half of a secp sign ceremony when the wallet's sign quorum requires it.
+     * The quorum is the first `threshold` roles of the wallet's party list (#292) — for the default
+     * `[device, server, recovery]`/2 that is `[device, server]`, so the device MUST be online and
+     * co-signing. Returns `undefined` when the quorum is platform-only (or the wallet is not secp) —
+     * the POST then completes alone, unchanged. A device-present quorum without the device deps or
+     * stored share fails fast with a typed error instead of a guaranteed server-side timeout.
+     */
+    private startDeviceCoSign;
     /**
      * Send a transaction from this wallet. The platform builds the chain-specific transaction
      * and co-signs it with the 2-of-3 MPC quorum, returning the **signed raw transaction**.
@@ -2381,6 +2384,13 @@ declare class Wallets {
      * `[device, user_backup]` ceremony — one place owns the error contract so both paths stay identical.
      */
     private runKeygenParties;
+    /**
+     * Run ONE client keygen party over the right transport. A 2-party ceremony uses the plain
+     * single-peer path; anything larger MUST be roster-routed — the 2-party transport attributes
+     * every inbound message to the one configured peer, so a third party's very first message
+     * aborts the protocol with "route received message" (waas-core#131).
+     */
+    private runKeygenParty;
     /**
      * Run the device half of an ed25519 (FROST) keygen (#110) and seal the resulting `{keyPackage,
      * publicKeyPackage}` share — the EdDSA counterpart of the cggmp24 `runKeygen` branch in {@link create}.

package/dist/index.js

@@ -910,6 +910,32 @@ function bytesToHex(bytes) {
   return hex;
 }
 
+// src/share-blob.ts
+function serializeShare(keygen, relayUrl) {
+  return JSON.stringify({
+    keyShare: keygen.keyShare,
+    auxInfo: keygen.auxInfo,
+    sharedPublicKey: keygen.sharedPublicKey,
+    ...relayUrl === void 0 ? {} : { relayUrl }
+  });
+}
+function deserializeShare(blob) {
+  let parsed;
+  try {
+    parsed = JSON.parse(blob);
+  } catch (cause) {
+    throw new WaaskeyError("Stored device share is corrupt \u2014 it is not valid JSON.", "share_not_found", { cause });
+  }
+  if (typeof parsed.keyShare !== "string") {
+    throw new WaaskeyError("Stored device share is malformed \u2014 it is missing its KeyShare.", "share_not_found", { details: { keys: Object.keys(parsed) } });
+  }
+  return {
+    keyShare: parsed.keyShare,
+    sharedPublicKey: typeof parsed.sharedPublicKey === "string" ? parsed.sharedPublicKey : void 0,
+    relayUrl: typeof parsed.relayUrl === "string" ? parsed.relayUrl : void 0
+  };
+}
+
 // src/passkey/assertion.ts
 function isPasskeyAssertionSupported() {
   return typeof globalThis.navigator !== "undefined" && typeof globalThis.navigator.credentials !== "undefined";
@@ -1026,10 +1052,55 @@ var Wallet = class {
     const message = normalizeDigest(digest);
     const body = { message };
     await this.attachStepUp(body, "sign", options);
-    const res = await this.http.request("POST", `/v1/wallets/${this.id}/sign`, body, options.signal);
+    const coSign = this.startDeviceCoSign(message);
+    const post = this.http.request("POST", `/v1/wallets/${this.id}/sign`, body, options.signal);
+    const [res] = coSign === void 0 ? [await post] : await Promise.all([post, coSign.catch(() => void 0)]);
     this.analytics?.track("wallet.signed", { walletId: this.id, curve: this.data.curve });
     return res.signature;
   }
+  /**
+   * Start this device's half of a secp sign ceremony when the wallet's sign quorum requires it.
+   * The quorum is the first `threshold` roles of the wallet's party list (#292) — for the default
+   * `[device, server, recovery]`/2 that is `[device, server]`, so the device MUST be online and
+   * co-signing. Returns `undefined` when the quorum is platform-only (or the wallet is not secp) —
+   * the POST then completes alone, unchanged. A device-present quorum without the device deps or
+   * stored share fails fast with a typed error instead of a guaranteed server-side timeout.
+   */
+  startDeviceCoSign(digest) {
+    if (this.data.curve === "ed25519") return void 0;
+    const roles = this.data.parties;
+    const { threshold } = this.data;
+    if (!Array.isArray(roles) || typeof threshold !== "number") return void 0;
+    const quorum = roles.slice(0, threshold);
+    const pos = quorum.indexOf("device");
+    if (pos < 0) return void 0;
+    const { mpc, shareStore } = this.device;
+    if (!mpc || !shareStore) {
+      throw new WaaskeyError(
+        `This wallet's sign quorum [${quorum.join(", ")}] includes the device, so signing requires the device MPC core and share store \u2014 pass \`mpc\` and \`shareStore\` to \`new Waaskey(...)\`.`,
+        "device_core_required"
+      );
+    }
+    return (async () => {
+      const blob = await shareStore.get(this.id);
+      if (!blob) {
+        throw new WaaskeyError(`No stored device share for wallet ${this.id} \u2014 this device cannot join the sign quorum.`, "share_not_found");
+      }
+      const { keyShare, relayUrl } = deserializeShare(blob);
+      if (!relayUrl) {
+        throw new WaaskeyError("The stored device share predates relay-URL persistence \u2014 re-create the wallet (or recover) to enable device-present signing.", "share_not_found");
+      }
+      const participants = quorum.map((_role, index) => index);
+      const base = { curve: toMpcCurve(this.data.curve), relayUrl, sessionId: this.id, share: keyShare, participants, signerPosition: pos, digest };
+      if (quorum.length === 2) {
+        return mpc.runSign({ ...base, role: quorum[pos], peerRole: quorum[1 - pos], partyIndex: pos, peerPartyIndex: 1 - pos });
+      }
+      if (!mpc.runMemberSign) {
+        throw new WaaskeyError(`This wallet's sign quorum has ${quorum.length} parties, which needs an MPC core with routed (member-ceremony) sign support.`, "unsupported");
+      }
+      return mpc.runMemberSign({ ...base, roles: quorum });
+    })();
+  }
   /**
    * Send a transaction from this wallet. The platform builds the chain-specific transaction
    * and co-signs it with the 2-of-3 MPC quorum, returning the **signed raw transaction**.
@@ -1491,7 +1562,7 @@ var Wallets = class {
       const pregeneratedPrimes = primePool ? await primePool.take(curve) : void 0;
       throwIfAborted(signal);
       const [keygen] = await this.runKeygenParties(mpc, [{ ...ceremony, curve, pregeneratedPrimes }]);
-      await shareStore.put(walletId, serializeShare(keygen));
+      await shareStore.put(walletId, serializeShare(keygen, ceremony.relayUrl));
       return;
     }
     if (!backup) {
@@ -1506,7 +1577,7 @@ var Wallets = class {
       { ...ceremony, curve, pregeneratedPrimes: devicePrimes },
       { ...userBackupParty, curve, pregeneratedPrimes: backupPrimes }
     ]);
-    await shareStore.put(walletId, serializeShare(deviceKeygen));
+    await shareStore.put(walletId, serializeShare(deviceKeygen, ceremony.relayUrl));
     throwIfAborted(signal);
     const { payload } = await buildRecoveryRegistration({ share: serializeShare(backupKeygen), ...backup });
     await shareStore.put(userBackupPendingKey(walletId), JSON.stringify(payload));
@@ -1651,12 +1722,39 @@ var Wallets = class {
    */
   async runKeygenParties(mpc, params) {
     try {
-      return await Promise.all(params.map((party) => mpc.runKeygen(party)));
+      return await Promise.all(params.map((party) => this.runKeygenParty(mpc, party, params)));
     } catch (cause) {
       if (cause instanceof WaaskeyError) throw cause;
       throw new WaaskeyError("The device keygen ceremony failed.", "keygen_failed", { cause });
     }
   }
+  /**
+   * Run ONE client keygen party over the right transport. A 2-party ceremony uses the plain
+   * single-peer path; anything larger MUST be roster-routed — the 2-party transport attributes
+   * every inbound message to the one configured peer, so a third party's very first message
+   * aborts the protocol with "route received message" (waas-core#131).
+   */
+  runKeygenParty(mpc, party, batch) {
+    if (party.parties <= 2) {
+      return mpc.runKeygen(party);
+    }
+    if (!mpc.runMemberKeygen) {
+      throw new WaaskeyError(
+        `This keygen ceremony has ${party.parties} parties, which needs an MPC core with routed (member-ceremony) keygen support \u2014 use a client-wasm build exposing keygenMember.`,
+        "unsupported"
+      );
+    }
+    return mpc.runMemberKeygen({
+      curve: party.curve,
+      relayUrl: party.relayUrl,
+      sessionId: party.sessionId,
+      roles: ceremonyRoster(party, batch),
+      partyIndex: party.partyIndex,
+      threshold: party.threshold,
+      relayToken: party.relayToken,
+      pregeneratedPrimes: party.pregeneratedPrimes
+    });
+  }
   /**
    * Run the device half of an ed25519 (FROST) keygen (#110) and seal the resulting `{keyPackage,
    * publicKeyPackage}` share — the EdDSA counterpart of the cggmp24 `runKeygen` branch in {@link create}.
@@ -1727,21 +1825,6 @@ var Wallets = class {
     }
   }
 };
-function serializeShare(keygen) {
-  return JSON.stringify({ keyShare: keygen.keyShare, auxInfo: keygen.auxInfo, sharedPublicKey: keygen.sharedPublicKey });
-}
-function deserializeShare(blob) {
-  let parsed;
-  try {
-    parsed = JSON.parse(blob);
-  } catch (cause) {
-    throw new WaaskeyError("Stored device share is corrupt \u2014 it is not valid JSON.", "share_not_found", { cause });
-  }
-  if (typeof parsed.keyShare !== "string") {
-    throw new WaaskeyError("Stored device share is malformed \u2014 it is missing its KeyShare.", "share_not_found", { details: { keys: Object.keys(parsed) } });
-  }
-  return { keyShare: parsed.keyShare, sharedPublicKey: typeof parsed.sharedPublicKey === "string" ? parsed.sharedPublicKey : void 0 };
-}
 async function restoreUserBackupShare(ciphertext, recoveryCode) {
   let blob;
   try {
@@ -1799,6 +1882,38 @@ function membershipIdFromRole(role) {
   }
   return role.slice(prefix.length);
 }
+function ceremonyRoster(party, batch) {
+  if (party.roles) {
+    if (party.roles.length !== party.parties) {
+      throw new WaaskeyError(`The ceremony roster names ${party.roles.length} parties but the ceremony has ${party.parties}.`, "validation");
+    }
+    return party.roles;
+  }
+  const roles = new Array(party.parties).fill(void 0);
+  const put = (index, role) => {
+    if (role === void 0) return;
+    if (index < 0 || index >= party.parties) {
+      throw new WaaskeyError(`Ceremony party index ${index} is out of range for a ${party.parties}-party ceremony.`, "validation");
+    }
+    if (roles[index] !== void 0 && roles[index] !== role) {
+      throw new WaaskeyError(`Conflicting ceremony roles for party index ${index}: "${roles[index]}" vs "${role}".`, "validation");
+    }
+    roles[index] = role;
+  };
+  for (const entry of batch) {
+    put(entry.partyIndex, entry.role ?? "device");
+    put(entry.peerPartyIndex, entry.peerRole ?? "server");
+  }
+  const gaps = roles.reduce((acc, role, index) => role === void 0 ? [...acc, index] : acc, []);
+  if (gaps.length > 1) {
+    throw new WaaskeyError(
+      `The ${party.parties}-party keygen ceremony leaves ${gaps.length} party slots unnamed \u2014 this backend must supply the full ceremony roster (roles).`,
+      "validation"
+    );
+  }
+  if (gaps.length === 1) roles[gaps[0]] = "recovery";
+  return roles;
+}
 function buildMemberRoster(shareholders, parties) {
   const roles = new Array(parties).fill(void 0);
   for (const shareholder of shareholders) {
@@ -2258,14 +2373,30 @@ function createVerifiedClientWasmLoader(options) {
     return mod;
   };
 }
+var clientWasm;
 var loadClientWasm = async () => {
+  return clientWasm ??= importAndInit();
+};
+async function importAndInit() {
+  let mod;
   try {
-    const mod = await import(CLIENT_WASM_PACKAGE);
-    return mod;
+    mod = await import(CLIENT_WASM_PACKAGE);
   } catch (cause) {
     throw new Error("Waaskey: creating a wallet needs the wasm engine \u2014 install '@waaskey/client-wasm' alongside '@waaskey/sdk'.", { cause });
   }
-};
+  const init = mod["default"] ?? mod["init"];
+  if (typeof init === "function") {
+    try {
+      await init();
+    } catch (cause) {
+      throw new Error(
+        "Waaskey: the wasm engine failed to initialize. In the browser this loader fetches the `.wasm` next to the module \u2014 serve it, or pass a loader built with `createVerifiedClientWasmLoader({ wasmUrl, expectedSha384 })`. On Node use `NodeWorkerMpcCore` from `@waaskey/sdk/node`, which loads the binary from disk in a worker thread.",
+        { cause }
+      );
+    }
+  }
+  return mod;
+}
 function toBase64(bytes) {
   let binary = "";
   for (const byte of bytes) binary += String.fromCharCode(byte);