@waaskey/sdk 0.3.0 → 0.3.2

package/dist/index.js

@@ -626,7 +626,7 @@ async function buildRecoveryRegistration(params) {
   const recoveryCode = params.recoveryCode ?? generateRecoveryCode();
   const ciphertext = await sealWithPassword(recoveryCode, params.share);
   const factors = [
-    { type: "recovery_code", credentialHash: await sha256Hex(recoveryCode) },
+    { type: "recovery_code", credential: await sha256Hex(recoveryCode) },
     { type: "totp", credential: params.totpSecret },
     { type: "email_otp", credential: params.email },
     ...params.extraFactors ?? []
@@ -654,7 +654,7 @@ async function registerRecoveryShare(http, walletId, params, signal) {
   return { recoveryCode, share };
 }
 async function hashRecoveryFactors(verifications) {
-  return Promise.all(verifications.map(async (v) => v.type === "recovery_code" && v.token !== void 0 ? { type: v.type, credentialHash: await sha256Hex(v.token) } : v));
+  return Promise.all(verifications.map(async (v) => v.type === "recovery_code" && typeof v.token === "string" ? { type: v.type, token: await sha256Hex(v.token) } : v));
 }
 function generateRecoveryCode() {
   const alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
@@ -910,6 +910,51 @@ function bytesToHex(bytes) {
   return hex;
 }
 
+// src/session-sign.ts
+function toDeviceSignParams(ceremony, share, digest) {
+  const { roles, participants, signerPosition } = ceremony;
+  if (participants.length !== 2 || roles.length !== 2 || signerPosition < 0 || signerPosition > 1) {
+    throw new WaaskeyError(
+      `Unexpected sign descriptor: the quorum must be exactly 2 parties with signerPosition in {0, 1} (got ${participants.length} participants, ${roles.length} roles, signerPosition ${signerPosition}).`,
+      "sign_failed",
+      { details: { roles, participants, signerPosition } }
+    );
+  }
+  const peerPosition = 1 - signerPosition;
+  return {
+    curve: toMpcCurve(ceremony.curve),
+    relayUrl: ceremony.relayUrl,
+    sessionId: ceremony.sessionId,
+    role: roles[signerPosition],
+    peerRole: roles[peerPosition],
+    partyIndex: signerPosition,
+    peerPartyIndex: peerPosition,
+    relayToken: ceremony.relayToken,
+    share,
+    participants,
+    signerPosition,
+    digest
+  };
+}
+function toSessionSignParams(session, share, digest) {
+  return toDeviceSignParams(
+    {
+      curve: session.curve,
+      relayUrl: session.relayUrl,
+      sessionId: session.sessionId,
+      roles: sessionRoles(session),
+      participants: session.participants,
+      signerPosition: session.signerPosition,
+      relayToken: session.relayToken
+    },
+    share,
+    digest
+  );
+}
+function sessionRoles(session) {
+  return session.signerPosition === 0 ? [session.role, session.peerRole] : [session.peerRole, session.role];
+}
+
 // src/share-blob.ts
 function serializeShare(keygen, relayUrl) {
   return JSON.stringify({
@@ -976,6 +1021,7 @@ async function getSigningAssertion(challenge, options = {}) {
 }
 
 // src/wallet.ts
+var DEVICE_ROLE = "device";
 var Wallet = class {
   constructor(http, data, analytics, device = {}) {
     this.http = http;
@@ -1050,56 +1096,106 @@ var Wallet = class {
    */
   async sign(digest, options = {}) {
     const message = normalizeDigest(digest);
-    const body = { message };
-    await this.attachStepUp(body, "sign", options);
-    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)]);
+    const quorum = this.signQuorum();
+    const devicePosition = quorum?.indexOf(DEVICE_ROLE) ?? -1;
+    if (devicePosition < 0) {
+      const body = { message };
+      await this.attachStepUp(body, "sign", options);
+      const res = await this.http.request("POST", `/v1/wallets/${this.id}/sign`, body, options.signal);
+      this.analytics?.track("wallet.signed", { walletId: this.id, curve: this.data.curve });
+      return res.signature;
+    }
+    const { mpc, keyShare } = await this.loadDeviceParty(quorum, "signing");
+    const startBody = { digest: message };
+    await this.attachStepUp(startBody, "sign", options);
+    const session = await this.http.request("POST", `/v1/wallets/${this.id}/sign-session`, startBody, options.signal);
+    const { signature } = await this.runDeviceSign(mpc, this.toSignCeremony(session, quorum), keyShare, message);
     this.analytics?.track("wallet.signed", { walletId: this.id, curve: this.data.curve });
-    return res.signature;
+    return 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.
+   * The roles that will actually sign — the first `threshold` of the wallet's party list (#292),
+   * mirroring the signer's own derivation. `undefined` when the topology is unknown (a legacy
+   * wallet record), which callers treat as "let the server decide".
    */
-  startDeviceCoSign(digest) {
+  signQuorum() {
     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;
+    return roles.slice(0, threshold);
+  }
+  /**
+   * Everything this device needs to join a ceremony, resolved BEFORE one is started (#89): the MPC
+   * core, the routed-sign capability a >2-party quorum needs, and the stored key share.
+   *
+   * Each failure is a typed error thrown straight to the caller, and the ordering is the point: a
+   * device that cannot co-sign must never leave the platform party waiting on the relay for a
+   * counterpart that will never arrive. That wait ends at the party-runner timeout (~210s) and
+   * reaches the caller as an opaque 5xx — minutes after a knowable, local cause.
+   */
+  async loadDeviceParty(quorum, action) {
     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(...)\`.`,
+        `This wallet's signing quorum [${quorum.join(", ")}] includes the device, so ${action} 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 });
-    })();
+    if (quorum.length > 2 && !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");
+    }
+    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 signing quorum.`, "share_not_found");
+    }
+    const { keyShare } = deserializeShare(blob);
+    return { mpc, keyShare };
+  }
+  /**
+   * Normalize a sign-session descriptor into the shared {@link DeviceCeremony}. The 2-party roster
+   * comes from the descriptor's own `role`/`peerRole` (authoritative — the relay token is bound to
+   * that role); a larger quorum carries no server-sent roster, so the wallet's own party slice — the
+   * same slice the signer derives — supplies it.
+   */
+  toSignCeremony(session, quorum) {
+    return {
+      curve: session.curve,
+      relayUrl: session.relayUrl,
+      sessionId: session.sessionId,
+      roles: session.participants.length === 2 ? sessionRoles(session) : quorum,
+      participants: session.participants,
+      signerPosition: session.signerPosition,
+      relayToken: session.relayToken
+    };
+  }
+  /**
+   * Run this device's half of a started ceremony. A 2-party quorum uses the plain single-peer
+   * transport; anything larger MUST be roster-routed, or the transport attributes every inbound
+   * message to the one configured peer and the protocol aborts on the third party's first message
+   * (waas-core#131).
+   */
+  runDeviceSign(mpc, ceremony, keyShare, digest) {
+    if (ceremony.participants.length === 2) {
+      return mpc.runSign(toDeviceSignParams(ceremony, keyShare, digest));
+    }
+    if (!mpc.runMemberSign) {
+      throw new WaaskeyError(
+        `This wallet's sign quorum has ${ceremony.participants.length} parties, which needs an MPC core with routed (member-ceremony) sign support.`,
+        "unsupported"
+      );
+    }
+    return mpc.runMemberSign({
+      curve: toMpcCurve(ceremony.curve),
+      relayUrl: ceremony.relayUrl,
+      sessionId: ceremony.sessionId,
+      relayToken: ceremony.relayToken,
+      roles: ceremony.roles,
+      share: keyShare,
+      participants: ceremony.participants,
+      signerPosition: ceremony.signerPosition,
+      digest
+    });
   }
   /**
    * Send a transaction from this wallet. The platform builds the chain-specific transaction
@@ -1119,19 +1215,60 @@ var Wallet = class {
     if (this.data.curve === "ed25519") {
       return this.sendEd25519(params, options);
     }
+    const quorum = this.signQuorum();
+    if ((quorum?.indexOf(DEVICE_ROLE) ?? -1) >= 0) {
+      return this.sendWithDevice(params, options, quorum);
+    }
     const body = { ...params };
     await this.attachStepUp(body, "send", options);
     const res = await this.http.request("POST", `/v1/wallets/${this.id}/send`, body, options.signal);
     this.analytics?.track("wallet.sent", { walletId: this.id, chain: params.chainId });
     return res;
   }
+  /**
+   * Device-co-signed send for a secp wallet — the cggmp24 counterpart of {@link sendEd25519}:
+   *
+   * 1. **START** (`POST …/send-session`): the platform runs the transfer gates, builds the unsigned
+   *    tx, puts its own party on the relay in the background, and returns the 32-byte digest plus
+   *    the relay coordination. It does NOT wait for the ceremony.
+   * 2. **CO-SIGN**: this device runs its half over the relay with its stored share; cggmp24 hands
+   *    the completed signature to both parties.
+   * 3. **ASSEMBLE** (`POST …/send-session/:txId/assemble`): the platform verifies the signature
+   *    (recovers to the wallet key AND equals its own party's) and embeds it into the wire tx.
+   *
+   * Every device-side precondition is resolved BEFORE the START (see {@link loadDeviceParty}), so a
+   * device that cannot co-sign costs nothing: no tx is built and no platform party is left waiting.
+   *
+   * **A co-sign that fails after a successful START rejects with its typed error.** START is not the
+   * commit point — it yields an *unsigned* tx and a pending session, and nothing broadcastable exists
+   * until ASSEMBLE returns a `signedTx` — so there is no result to salvage by swallowing the failure,
+   * and no fallback to `POST /send` (the platform cannot reach the threshold on this wallet alone, so
+   * a retry there would only hang). The backend expires the abandoned session and fails the tx row.
+   */
+  async sendWithDevice(params, options, quorum) {
+    const { signal } = options;
+    const { mpc, keyShare } = await this.loadDeviceParty(quorum, "sending");
+    throwIfAborted(signal);
+    const startBody = { ...params };
+    await this.attachStepUp(startBody, "send", options);
+    throwIfAborted(signal);
+    const session = await this.http.request("POST", `/v1/wallets/${this.id}/send-session`, startBody, signal);
+    const digest = sendPayload(session, "digest");
+    throwIfAborted(signal);
+    const { signature } = await this.runDeviceSign(mpc, toSendCeremony(session), keyShare, digest);
+    throwIfAborted(signal);
+    const assemble = { signature };
+    const res = await this.http.request("POST", `/v1/wallets/${this.id}/send-session/${session.txId}/assemble`, assemble, signal);
+    this.analytics?.track("wallet.sent", { walletId: this.id, chain: params.chainId });
+    return res;
+  }
   /**
    * Device-co-signed send for an ed25519 (FROST) wallet (#110) — the browser holds the device FROST
    * share and co-signs 2-party with the backend `server` party over the relay:
    *
    * 1. **START** (`POST …/send-session`): the backend builds the unsigned tx (chain adapter), starts
    *    its server FROST party on the relay in the background, and returns the raw `message` bytes to
-   *    sign + the relay coordination ({@link EddsaSendSession}).
+   *    sign + the relay coordination ({@link SendSessionResponse}).
    * 2. **CO-SIGN**: the device runs `signEddsa` over the relay with its stored `{keyPackage,
    *    publicKeyPackage}` share; the two parties aggregate the RFC 8032 signature (returned locally).
    * 3. **ASSEMBLE** (`POST …/send-session/:txId/assemble`): the backend embeds the aggregated
@@ -1166,6 +1303,7 @@ var Wallet = class {
     await this.attachStepUp(startBody, "send", options);
     throwIfAborted(signal);
     const session = await this.http.request("POST", `/v1/wallets/${this.id}/send-session`, startBody, signal);
+    const message = sendPayload(session, "message");
     throwIfAborted(signal);
     let signature;
     try {
@@ -1177,7 +1315,7 @@ var Wallet = class {
         keyPackage,
         publicKeyPackage,
         participants: session.participants,
-        message: session.message,
+        message,
         relayToken: session.relayToken
       }));
     } catch (cause) {
@@ -1226,6 +1364,26 @@ async function attachPasskeyStepUp(http, walletId, body, operation, options) {
   body["passkeyAssertion"] = await getSigningAssertion(challenge, { credentialId: options.passkeyCredentialId });
   body["passkeyChallengeId"] = challengeId;
 }
+function toSendCeremony(session) {
+  return {
+    curve: session.curve,
+    relayUrl: session.relayUrl,
+    sessionId: session.sessionId,
+    roles: session.roles,
+    participants: session.participants,
+    signerPosition: session.signerPosition,
+    relayToken: session.relayToken
+  };
+}
+function sendPayload(session, field) {
+  const payload = session[field];
+  if (!payload) {
+    throw new WaaskeyError(`The send session did not return the \`${field}\` this wallet's curve (${session.curve}) signs.`, "sign_failed", {
+      details: { txId: session.txId, curve: session.curve }
+    });
+  }
+  return payload;
+}
 function normalizeDigest(digest) {
   const hex = digest.startsWith("0x") || digest.startsWith("0X") ? digest.slice(2) : digest;
   if (!/^[0-9a-fA-F]{64}$/.test(hex)) {
@@ -1688,7 +1846,7 @@ var Wallets = class {
     throwIfAborted(signal);
     let signature;
     try {
-      ({ signature } = await mpc.runSign(toUserBackupSignParams(session, share, digest)));
+      ({ signature } = await mpc.runSign(toSessionSignParams(session, share, digest)));
     } catch (cause) {
       if (cause instanceof WaaskeyError) throw cause;
       throw new WaaskeyError("The user_backup device recover-sign ceremony failed.", "sign_failed", { cause });
@@ -1834,29 +1992,6 @@ async function restoreUserBackupShare(ciphertext, recoveryCode) {
   }
   return deserializeShare(blob).keyShare;
 }
-function toUserBackupSignParams(session, share, digest) {
-  if (session.participants.length !== 2 || session.signerPosition < 0 || session.signerPosition > 1) {
-    throw new WaaskeyError(
-      `Unexpected recover-sign descriptor: the {server, user_backup} quorum must be exactly 2 parties with signerPosition in {0, 1} (got ${session.participants.length} participants, signerPosition ${session.signerPosition}).`,
-      "sign_failed",
-      { details: { participants: session.participants, signerPosition: session.signerPosition } }
-    );
-  }
-  return {
-    curve: toMpcCurve(session.curve),
-    relayUrl: session.relayUrl,
-    sessionId: session.sessionId,
-    role: session.role,
-    peerRole: session.peerRole,
-    partyIndex: session.signerPosition,
-    peerPartyIndex: 1 - session.signerPosition,
-    relayToken: session.relayToken,
-    share,
-    participants: session.participants,
-    signerPosition: session.signerPosition,
-    digest
-  };
-}
 function memberShareKey(walletId, membershipId) {
   return `${walletId}@member-${membershipId}`;
 }
@@ -1873,7 +2008,17 @@ function parseBackupPayload(stored, walletId) {
   if (typeof parsed.ciphertext !== "string" || !Array.isArray(parsed.factors)) {
     throw new WaaskeyError(`The pending user_backup backup for wallet "${walletId}" is malformed.`, "backup_failed", { details: { walletId, keys: Object.keys(parsed) } });
   }
-  return { ciphertext: parsed.ciphertext, factors: parsed.factors };
+  return { ciphertext: parsed.ciphertext, factors: parsed.factors.map((factor) => normalizeStoredFactor(factor, walletId)) };
+}
+function normalizeStoredFactor(factor, walletId) {
+  const { type, credential, credentialHash } = factor ?? {};
+  const value = typeof credential === "string" && credential !== "" ? credential : credentialHash;
+  if (typeof type !== "string" || type === "" || typeof value !== "string" || value === "") {
+    throw new WaaskeyError(`The pending user_backup backup for wallet "${walletId}" is malformed \u2014 a factor entry is missing its type or credential.`, "backup_failed", {
+      details: { walletId, factorKeys: Object.keys(factor ?? {}) }
+    });
+  }
+  return { type, credential: value };
 }
 function membershipIdFromRole(role) {
   const prefix = "member:";
@@ -2330,7 +2475,7 @@ function decodePublicKey(sharedPublicKeyJson) {
 
 // src/mpc/load-wasm.ts
 var CLIENT_WASM_PACKAGE = "@waaskey/client-wasm";
-var CLIENT_WASM_VERSION = "0.2.1";
+var CLIENT_WASM_VERSION = "0.2.2";
 async function verifyWasmIntegrity(bytes, expectedSha384) {
   if (!expectedSha384 || !expectedSha384.startsWith("sha384-")) {
     throw new Error("Waaskey: an expected SHA-384 integrity hash (sha384-<base64>) is required to load the wasm MPC core.");
@@ -2373,14 +2518,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);