@waaskey/sdk 0.2.0 → 0.3.0

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 {
@@ -658,11 +664,21 @@ interface PrimePoolOptions {
     targetSize?: number;
     /** Persistence for the pool. Defaults to an in-memory store. */
     store?: PrimePoolStore;
+    /**
+     * Kick off a refill automatically after every {@link PrimePool.take}. Default `false`:
+     * unless the core generates primes in a Web Worker, wasm prime generation is a
+     * synchronous CPU burn on the calling thread — a "background" refill starves the event
+     * loop and stalls the very keygen ceremony the take() was for (it also freezes a
+     * browser UI). Refill explicitly via {@link PrimePool.ensure} (`wallets.prewarm`) at
+     * boot/idle, or set `true` only when the core is worker-backed.
+     */
+    autoRefill?: boolean;
 }
 declare class PrimePool {
     private readonly core;
     private readonly store;
     private readonly targetSize;
+    private readonly autoRefill;
     /** Per-curve in-flight refill, so concurrent calls don't over-generate. */
     private readonly refilling;
     constructor(core: PrimeGenerator, options?: PrimePoolOptions);
@@ -674,8 +690,9 @@ declare class PrimePool {
     private refill;
     /**
      * Claim a prime for a keygen. Returns a cached one instantly when the pool is warm; otherwise
-     * generates one inline (the slow fallback) so keygen never fails on an empty pool. Either way it
-     * kicks off a background refill so the next wallet is instant.
+     * generates one inline (the slow fallback) so keygen never fails on an empty pool. Refill the
+     * pool for the next wallet via {@link ensure} at idle (or opt into `autoRefill` when the core
+     * is worker-backed).
      */
     take(curve: MpcCurve): Promise<string>;
 }
@@ -1089,6 +1106,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
@@ -2082,6 +2105,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**.
@@ -2370,6 +2402,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 {
@@ -658,11 +664,21 @@ interface PrimePoolOptions {
     targetSize?: number;
     /** Persistence for the pool. Defaults to an in-memory store. */
     store?: PrimePoolStore;
+    /**
+     * Kick off a refill automatically after every {@link PrimePool.take}. Default `false`:
+     * unless the core generates primes in a Web Worker, wasm prime generation is a
+     * synchronous CPU burn on the calling thread — a "background" refill starves the event
+     * loop and stalls the very keygen ceremony the take() was for (it also freezes a
+     * browser UI). Refill explicitly via {@link PrimePool.ensure} (`wallets.prewarm`) at
+     * boot/idle, or set `true` only when the core is worker-backed.
+     */
+    autoRefill?: boolean;
 }
 declare class PrimePool {
     private readonly core;
     private readonly store;
     private readonly targetSize;
+    private readonly autoRefill;
     /** Per-curve in-flight refill, so concurrent calls don't over-generate. */
     private readonly refilling;
     constructor(core: PrimeGenerator, options?: PrimePoolOptions);
@@ -674,8 +690,9 @@ declare class PrimePool {
     private refill;
     /**
      * Claim a prime for a keygen. Returns a cached one instantly when the pool is warm; otherwise
-     * generates one inline (the slow fallback) so keygen never fails on an empty pool. Either way it
-     * kicks off a background refill so the next wallet is instant.
+     * generates one inline (the slow fallback) so keygen never fails on an empty pool. Refill the
+     * pool for the next wallet via {@link ensure} at idle (or opt into `autoRefill` when the core
+     * is worker-backed).
      */
     take(curve: MpcCurve): Promise<string>;
 }
@@ -1089,6 +1106,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
@@ -2082,6 +2105,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**.
@@ -2370,6 +2402,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) {
@@ -2298,10 +2413,12 @@ var PrimePool = class {
     this.core = core;
     this.store = options.store ?? new MemoryPrimeStore();
     this.targetSize = Math.max(1, options.targetSize ?? 2);
+    this.autoRefill = options.autoRefill ?? false;
   }
   core;
   store;
   targetSize;
+  autoRefill;
   /** Per-curve in-flight refill, so concurrent calls don't over-generate. */
   refilling = /* @__PURE__ */ new Map();
   /**
@@ -2322,13 +2439,14 @@ var PrimePool = class {
   }
   /**
    * Claim a prime for a keygen. Returns a cached one instantly when the pool is warm; otherwise
-   * generates one inline (the slow fallback) so keygen never fails on an empty pool. Either way it
-   * kicks off a background refill so the next wallet is instant.
+   * generates one inline (the slow fallback) so keygen never fails on an empty pool. Refill the
+   * pool for the next wallet via {@link ensure} at idle (or opt into `autoRefill` when the core
+   * is worker-backed).
    */
   async take(curve) {
     const cached = await this.store.take(curve);
     const primes = cached ?? await this.core.pregeneratePrimes(curve);
-    void this.ensure(curve).catch(() => void 0);
+    if (this.autoRefill) void this.ensure(curve).catch(() => void 0);
     return primes;
   }
 };