@waaskey/sdk 0.3.1 → 0.4.0

package/dist/index.cjs

@@ -519,6 +519,17 @@ async function deriveKey(secret, salt) {
     "decrypt"
   ]);
 }
+async function deriveKeyFromBytes(material, salt, info) {
+  const s = subtle();
+  const baseKey = await s.importKey("raw", material, "HKDF", false, ["deriveKey"]);
+  return s.deriveKey(
+    { name: "HKDF", hash: "SHA-256", salt, info: new TextEncoder().encode(info) },
+    baseKey,
+    { name: "AES-GCM", length: AES_KEY_BITS },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
 async function seal(key, plaintext) {
   const iv = randomBytes(IV_BYTES);
   const data = new TextEncoder().encode(plaintext);
@@ -561,6 +572,60 @@ function base64ToBytes(base64) {
   return bytes;
 }
 
+// src/recovery-envelope.ts
+var KEK_INFO = "waaskey-backup-kek-v1";
+var DEK_INFO = "waaskey-backup-dek-v1";
+async function sealRecoveryBackup(share, recoveryCode, passkey) {
+  const dataKeyBytes = randomBytes(32);
+  const dataKey = await deriveKeyFromBytes(dataKeyBytes, new Uint8Array(0), DEK_INFO);
+  const ciphertext = await seal(dataKey, share);
+  const codeSalt = freshSalt();
+  const keyWraps = [
+    {
+      method: "passphrase",
+      wrapped: await seal(await deriveKey(recoveryCode, codeSalt), bytesToBase64(dataKeyBytes)),
+      salt: bytesToBase64(codeSalt)
+    }
+  ];
+  if (passkey) {
+    const prfSalt = base64ToBytes(passkey.salt);
+    keyWraps.push({
+      method: "passkey_prf",
+      wrapped: await seal(await deriveKeyFromBytes(base64ToBytes(passkey.secret), prfSalt, KEK_INFO), bytesToBase64(dataKeyBytes)),
+      salt: passkey.salt,
+      credentialId: passkey.credentialId
+    });
+  }
+  return { ciphertext, keyWraps };
+}
+async function openRecoveryBackup(envelope, opener) {
+  const prfWrap = envelope.keyWraps.find((w) => w.method === "passkey_prf");
+  if (opener.passkeySecret !== void 0 && prfWrap) {
+    const kek = await deriveKeyFromBytes(base64ToBytes(opener.passkeySecret), base64ToBytes(prfWrap.salt), KEK_INFO);
+    return openWith(envelope.ciphertext, prfWrap, kek, "passkey");
+  }
+  const codeWrap = envelope.keyWraps.find((w) => w.method === "passphrase");
+  if (opener.recoveryCode !== void 0 && codeWrap) {
+    const kek = await deriveKey(opener.recoveryCode, base64ToBytes(codeWrap.salt));
+    return openWith(envelope.ciphertext, codeWrap, kek, "recovery code");
+  }
+  const enrolled = envelope.keyWraps.map((w) => w.method).join(", ") || "none";
+  throw new WaaskeyError(`No key available to open this backup \u2014 it is wrapped for [${enrolled}] and none of those was supplied.`, "recovery_failed");
+}
+async function openWith(ciphertext, wrap, kek, label) {
+  let dataKeyBytes;
+  try {
+    dataKeyBytes = base64ToBytes(await open(kek, wrap.wrapped));
+  } catch (cause) {
+    throw new WaaskeyError(`Could not unwrap the backup key with the ${label} \u2014 wrong ${label}?`, "recovery_failed", { cause });
+  }
+  try {
+    return await open(await deriveKeyFromBytes(dataKeyBytes, new Uint8Array(0), DEK_INFO), ciphertext);
+  } catch (cause) {
+    throw new WaaskeyError("The backup key does not open this backup \u2014 the stored ciphertext and key wrap do not belong together.", "recovery_failed", { cause });
+  }
+}
+
 // src/recovery.ts
 var MIN_FACTORS = 3;
 var Recovery = class {
@@ -598,7 +663,7 @@ var Recovery = class {
       { challengeId: params.challengeId, verifications: await hashRecoveryFactors(params.verifications) },
       options.signal
     );
-    const share = await this.decrypt(res.ciphertext, params.recoveryCode);
+    const share = await this.decrypt(res, params);
     await this.deps.shareStore?.put(walletId, share);
     this.deps.analytics?.track("wallet.recovered", { walletId });
     return { share, refreshedAt: res.refreshedAt };
@@ -613,22 +678,17 @@ var Recovery = class {
    * device-loss so a leaked backup can't be replayed against a still-valid old share.
    */
   async retrieveShare(walletId, params, options = {}) {
-    const ciphertext = await fetchRecoveryCiphertext(this.http, walletId, params, options.signal);
-    return this.decrypt(ciphertext, params.recoveryCode);
+    return this.decrypt(await fetchRecoveryBackup(this.http, walletId, params, options.signal), params);
   }
-  async decrypt(ciphertext, recoveryCode) {
-    try {
-      return await openWithPassword(recoveryCode, ciphertext);
-    } catch (cause) {
-      throw new WaaskeyError("Could not decrypt the recovery share \u2014 wrong recovery code?", "recovery_failed", { cause });
-    }
+  decrypt(backup, params) {
+    return openRecoveryBlob(backup, params);
   }
 };
 async function buildRecoveryRegistration(params) {
   const recoveryCode = params.recoveryCode ?? generateRecoveryCode();
-  const ciphertext = await sealWithPassword(recoveryCode, params.share);
+  const backup = params.passkey ? await sealRecoveryBackup(params.share, recoveryCode, params.passkey) : { ciphertext: await sealWithPassword(recoveryCode, params.share), keyWraps: void 0 };
   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 ?? []
@@ -636,19 +696,31 @@ async function buildRecoveryRegistration(params) {
   if (factors.length < MIN_FACTORS) {
     throw new WaaskeyError(`Recovery requires at least ${MIN_FACTORS} factors.`, "validation");
   }
-  return { recoveryCode, payload: { ciphertext, factors } };
+  return { recoveryCode, payload: { ciphertext: backup.ciphertext, factors, ...backup.keyWraps ? { keyWraps: backup.keyWraps } : {} } };
 }
 function postRecoveryRegistration(http, walletId, payload, signal) {
   return http.request("POST", `/v1/wallets/${walletId}/recovery/register`, payload, signal);
 }
-async function fetchRecoveryCiphertext(http, walletId, params, signal) {
-  const res = await http.request(
+async function fetchRecoveryBackup(http, walletId, params, signal) {
+  return http.request(
     "POST",
     `/v1/wallets/${walletId}/recovery/verify`,
     { challengeId: params.challengeId, verifications: await hashRecoveryFactors(params.verifications) },
     signal
   );
-  return res.ciphertext;
+}
+async function openRecoveryBlob(backup, opener) {
+  if (backup.keyWraps?.length) {
+    return openRecoveryBackup({ ciphertext: backup.ciphertext, keyWraps: backup.keyWraps }, opener);
+  }
+  if (opener.recoveryCode === void 0) {
+    throw new WaaskeyError("This backup predates passkey wrapping and can only be opened with the recovery code.", "recovery_failed");
+  }
+  try {
+    return await openWithPassword(opener.recoveryCode, backup.ciphertext);
+  } catch (cause) {
+    throw new WaaskeyError("Could not decrypt the recovery share \u2014 wrong recovery code?", "recovery_failed", { cause });
+  }
 }
 async function registerRecoveryShare(http, walletId, params, signal) {
   const { recoveryCode, payload } = await buildRecoveryRegistration(params);
@@ -656,7 +728,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";
@@ -694,6 +766,47 @@ function toMpcCurve(curve) {
   }
   return curve;
 }
+var DEVICE_ENC_STORE_KEY = "__waaskey_device_enc_v1__";
+async function getOrCreateDeviceEncKeypair(shareStore) {
+  const existing = await shareStore.get(DEVICE_ENC_STORE_KEY);
+  if (existing !== null) return parseDeviceEncKeypair(existing);
+  const keypair = generateDeviceEncKeypair();
+  await shareStore.put(DEVICE_ENC_STORE_KEY, JSON.stringify(keypair));
+  return keypair;
+}
+function generateDeviceEncKeypair() {
+  const secret = ed25519_js.x25519.utils.randomSecretKey();
+  const publicKey = ed25519_js.x25519.getPublicKey(secret);
+  if (isAllZero(publicKey)) {
+    throw new WaaskeyError("Generated an all-zero X25519 encryption public key \u2014 refusing to seal keygen packages to it.", "keygen_failed");
+  }
+  return { secretHex: bytesToHex(secret), publicHex: bytesToHex(publicKey) };
+}
+function parseDeviceEncKeypair(blob) {
+  let parsed;
+  try {
+    parsed = JSON.parse(blob);
+  } catch (cause) {
+    throw new WaaskeyError("Stored device encryption keypair is corrupt \u2014 it is not valid JSON.", "keygen_failed", { cause });
+  }
+  if (!isHex32(parsed.secretHex) || !isHex32(parsed.publicHex)) {
+    throw new WaaskeyError("Stored device encryption keypair is malformed \u2014 expected 32-byte (64 hex) secret + public keys.", "keygen_failed", {
+      details: { keys: Object.keys(parsed) }
+    });
+  }
+  return { secretHex: parsed.secretHex, publicHex: parsed.publicHex };
+}
+function isHex32(v) {
+  return typeof v === "string" && /^[0-9a-fA-F]{64}$/.test(v);
+}
+function isAllZero(bytes) {
+  return bytes.every((byte) => byte === 0);
+}
+function bytesToHex(bytes) {
+  let hex = "";
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}
 
 // src/internal.ts
 function throwIfAborted(signal) {
@@ -719,6 +832,7 @@ function delay(ms, signal) {
 }
 
 // src/reshare.ts
+var USER_BACKUP_ROLE = "user_backup";
 var Reshare = class {
   constructor(http, deps = {}) {
     this.http = http;
@@ -726,6 +840,116 @@ var Reshare = class {
   }
   http;
   deps;
+  /**
+   * Rotate the wallet onto a NEW committee, keeping its address, and drive this device's whole half of
+   * the ceremony (#488).
+   *
+   * The client is not a bystander here: the platform holds ONE share and cannot reach the threshold, so
+   * without this device's deal there is no ceremony at all.
+   *
+   * 1. Open the ceremony with the committee asked for (an empty request re-issues the current one).
+   * 2. DEAL from this device's current-epoch share — pure and local; every sub-share leaves sealed.
+   * 3. For each CLIENT-held new holder — identified by custody KIND, never by role name — fetch its
+   *    material and assemble its new-epoch core locally, refusing any share that reproduces a different
+   *    public key.
+   * 4. Acknowledge each one. The `user_backup` holder's ack carries its new share re-sealed under the
+   *    user's EXISTING recovery code, so the wallet's no-lock-out property survives the rotation; the
+   *    last acknowledgement drives the backend's atomic cutover.
+   *
+   * The assembled cores are BARE (no aux): the wallet is `reshareAuxPending` until aux-completion, which
+   * is {@link complete}'s job — and which re-assembles from the material itself, so nothing here needs
+   * to be kept on the device between the two. Nothing here can leave the device worse off — the old-epoch share is
+   * untouched, and a ceremony that fails cuts nothing over.
+   */
+  async rotate(walletId, params = {}, options = {}) {
+    const { mpc, shareStore } = this.deps;
+    if (!mpc || !shareStore) {
+      throw new WaaskeyError("Driving a reshare requires a device MPC core and a share store \u2014 pass `mpc` and `shareStore` to `new Waaskey(...)`.", "device_core_required");
+    }
+    if (!mpc.runReshareDeal || !mpc.runReshareAssemble) {
+      throw new WaaskeyError("The configured MPC core does not support reshare \u2014 use a client-wasm built with the `reshare` feature.", "unsupported");
+    }
+    const { signal } = options;
+    throwIfAborted(signal);
+    const wallet = await this.http.request("GET", `/v1/wallets/${walletId}`, void 0, signal);
+    if (!wallet.publicKey) {
+      throw new WaaskeyError("The wallet has no public key yet \u2014 only an ACTIVE wallet can be reshared.", "reshare_failed", { details: { walletId } });
+    }
+    const share = await shareStore.get(epochShareKey(walletId, wallet.keyEpoch));
+    if (!share) {
+      throw new WaaskeyError(`This device holds no share for wallet "${walletId}" at epoch ${wallet.keyEpoch} \u2014 it cannot deal the reshare.`, "reshare_failed");
+    }
+    throwIfAborted(signal);
+    const ceremony = await this.http.request("POST", `/v1/wallets/${walletId}/reshare-embedded`, params, signal);
+    const encKeypair = await getOrCreateDeviceEncKeypair(shareStore);
+    const curve = toMpcCurve(ceremony.curve);
+    const clientHolders = ceremony.newParties.filter((_role, i) => isClientCustody(ceremony.newCustodyKinds[i]));
+    try {
+      throwIfAborted(signal);
+      const dealt = await mpc.runReshareDeal({
+        curve,
+        share,
+        quorumIndices: ceremony.quorumIndices,
+        newPreimages: ceremony.newPreimages,
+        newThreshold: ceremony.newThreshold,
+        recipientPubkeys: ceremony.recipientPubkeys
+      });
+      await this.http.request(
+        "POST",
+        `/v1/wallets/${walletId}/reshare-drop/${ceremony.id}/deal`,
+        { commitments: dealt.commitments, sealedSubShares: dealt.sealedSubShares },
+        signal
+      );
+      let { status } = ceremony;
+      for (const role of clientHolders) {
+        throwIfAborted(signal);
+        const material = await this.http.request(
+          "GET",
+          `/v1/wallets/${walletId}/reshare-drop/${ceremony.id}/assembly?role=${encodeURIComponent(role)}`,
+          void 0,
+          signal
+        );
+        const assembled = await mpc.runReshareAssemble({
+          curve,
+          newPosition: material.newPosition,
+          newPreimages: material.newPreimages,
+          newThreshold: material.newThreshold,
+          wallet: material.wallet,
+          commitments: material.commitments,
+          subShares: material.subShares,
+          encryptionSecret: encKeypair.secretHex
+        });
+        assertPublicKey(assembled.sharedPublicKey, wallet.publicKey, walletId);
+        const body = role === USER_BACKUP_ROLE ? { backupCiphertext: await this.sealBackup(assembled.core, params.recoveryCode) } : {};
+        const ack = await this.http.request(
+          "POST",
+          `/v1/wallets/${walletId}/reshare-drop/${ceremony.id}/assembled?role=${encodeURIComponent(role)}`,
+          body,
+          signal
+        );
+        ({ status } = ack);
+      }
+      this.deps.analytics?.track("wallet.reshared", { walletId, curve: ceremony.curve });
+      return { walletId, ceremonyId: ceremony.id, status, keyEpoch: ceremony.keyEpoch, assembledRoles: clientHolders, sharedPublicKey: wallet.publicKey };
+    } catch (cause) {
+      if (cause instanceof WaaskeyError) throw cause;
+      throw new WaaskeyError("The reshare ceremony failed.", "reshare_failed", { cause });
+    }
+  }
+  /**
+   * Re-seal the new `user_backup` core under the user's EXISTING recovery code. The code never leaves
+   * the device — only the ciphertext does — which is the same trust model registration has, and the
+   * reason the server cannot check WHICH code sealed it.
+   */
+  async sealBackup(core, recoveryCode) {
+    if (!recoveryCode) {
+      throw new WaaskeyError(
+        "This committee keeps a `user_backup` holder, so its new share must be re-sealed under the wallet existing recovery code \u2014 pass `recoveryCode` to `reshare.rotate(...)`.",
+        "reshare_failed"
+      );
+    }
+    return sealWithPassword(recoveryCode, core);
+  }
   /**
    * Complete this device's share for a device-retaining reshare and make the wallet signable on the
    * device under the new epoch.
@@ -756,6 +980,7 @@ var Reshare = class {
     if (!wallet.publicKey) {
       throw new WaaskeyError("The wallet has no public key yet \u2014 it must be an ACTIVE reshared wallet to complete on device.", "reshare_failed", { details: { walletId } });
     }
+    const encKeypair = await getOrCreateDeviceEncKeypair(shareStore);
     throwIfAborted(signal);
     let completed;
     try {
@@ -766,7 +991,8 @@ var Reshare = class {
         newThreshold: material.newThreshold,
         wallet: material.wallet,
         commitments: material.commitments,
-        subShares: material.subShares
+        subShares: material.subShares,
+        encryptionSecret: encKeypair.secretHex
       });
       assertPublicKey(assembled.sharedPublicKey, wallet.publicKey, walletId);
       throwIfAborted(signal);
@@ -796,6 +1022,9 @@ var Reshare = class {
 function epochShareKey(walletId, keyEpoch) {
   return keyEpoch <= 1 ? walletId : `${walletId}@epoch-${keyEpoch}`;
 }
+function isClientCustody(kind) {
+  return kind !== void 0 && kind !== "platform_signer" && kind !== "platform_recovery";
+}
 function assertPublicKey(actual, expected, walletId) {
   if (actual !== expected) {
     throw new WaaskeyError("The reshared share reproduced a DIFFERENT public key than the wallet \u2014 aborting (device share not stored).", "reshare_pubkey_mismatch", {
@@ -870,46 +1099,50 @@ function deserializeEddsaShare(blob) {
   }
   return { keyPackage: parsed.keyPackage, publicKeyPackage: parsed.publicKeyPackage };
 }
-var DEVICE_ENC_STORE_KEY = "__waaskey_device_enc_v1__";
-async function getOrCreateDeviceEncKeypair(shareStore) {
-  const existing = await shareStore.get(DEVICE_ENC_STORE_KEY);
-  if (existing !== null) return parseDeviceEncKeypair(existing);
-  const keypair = generateDeviceEncKeypair();
-  await shareStore.put(DEVICE_ENC_STORE_KEY, JSON.stringify(keypair));
-  return keypair;
-}
-function generateDeviceEncKeypair() {
-  const secret = ed25519_js.x25519.utils.randomSecretKey();
-  const publicKey = ed25519_js.x25519.getPublicKey(secret);
-  if (isAllZero(publicKey)) {
-    throw new WaaskeyError("Generated an all-zero X25519 encryption public key \u2014 refusing to seal keygen packages to it.", "keygen_failed");
-  }
-  return { secretHex: bytesToHex(secret), publicHex: bytesToHex(publicKey) };
-}
-function parseDeviceEncKeypair(blob) {
-  let parsed;
-  try {
-    parsed = JSON.parse(blob);
-  } catch (cause) {
-    throw new WaaskeyError("Stored device encryption keypair is corrupt \u2014 it is not valid JSON.", "keygen_failed", { cause });
-  }
-  if (!isHex32(parsed.secretHex) || !isHex32(parsed.publicHex)) {
-    throw new WaaskeyError("Stored device encryption keypair is malformed \u2014 expected 32-byte (64 hex) secret + public keys.", "keygen_failed", {
-      details: { keys: Object.keys(parsed) }
-    });
+
+// 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 } }
+    );
   }
-  return { secretHex: parsed.secretHex, publicHex: parsed.publicHex };
+  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 isHex32(v) {
-  return typeof v === "string" && /^[0-9a-fA-F]{64}$/.test(v);
+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 isAllZero(bytes) {
-  return bytes.every((byte) => byte === 0);
-}
-function bytesToHex(bytes) {
-  let hex = "";
-  for (const byte of bytes) hex += byte.toString(16).padStart(2, "0");
-  return hex;
+function sessionRoles(session) {
+  return session.signerPosition === 0 ? [session.role, session.peerRole] : [session.peerRole, session.role];
 }
 
 // src/share-blob.ts
@@ -978,6 +1211,7 @@ async function getSigningAssertion(challenge, options = {}) {
 }
 
 // src/wallet.ts
+var DEVICE_ROLE = "device";
 var Wallet = class {
   constructor(http, data, analytics, device = {}) {
     this.http = http;
@@ -1052,56 +1286,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
@@ -1121,19 +1405,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
@@ -1168,6 +1493,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 {
@@ -1179,7 +1505,7 @@ var Wallet = class {
         keyPackage,
         publicKeyPackage,
         participants: session.participants,
-        message: session.message,
+        message,
         relayToken: session.relayToken
       }));
     } catch (cause) {
@@ -1228,6 +1554,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)) {
@@ -1239,7 +1585,7 @@ function normalizeDigest(digest) {
 // src/wallets.ts
 var BACKUP_REGISTER_ATTEMPTS = 3;
 var BACKUP_REGISTER_BACKOFF_MS = 200;
-var USER_BACKUP_ROLE = "user_backup";
+var USER_BACKUP_ROLE2 = "user_backup";
 var DEFAULT_ACTIVATION_TIMEOUT_MS = 6e4;
 var DEFAULT_POLL_INTERVAL_MS = 1e3;
 var Wallets = class {
@@ -1551,7 +1897,7 @@ var Wallets = class {
    */
   async runSecpKeygen(mpc, shareStore, primePool, walletId, ceremony, curve, backup, signal) {
     const extras = ceremony.additionalParties ?? [];
-    const unsupported = extras.filter((party) => party.role !== USER_BACKUP_ROLE);
+    const unsupported = extras.filter((party) => party.role !== USER_BACKUP_ROLE2);
     if (unsupported.length > 0) {
       throw new WaaskeyError(
         `The keygen ceremony carries an additional client party this SDK cannot drive (${unsupported.map((party) => party.role).join(", ")}) \u2014 refusing to keygen, since leaving a party unjoined would hang the ceremony.`,
@@ -1559,7 +1905,7 @@ var Wallets = class {
         { details: { roles: unsupported.map((party) => party.role) } }
       );
     }
-    const userBackupParty = extras.find((party) => party.role === USER_BACKUP_ROLE);
+    const userBackupParty = extras.find((party) => party.role === USER_BACKUP_ROLE2);
     if (!userBackupParty) {
       const pregeneratedPrimes = primePool ? await primePool.take(curve) : void 0;
       throwIfAborted(signal);
@@ -1679,8 +2025,8 @@ var Wallets = class {
     const { signal } = options;
     throwIfAborted(signal);
     const digest = normalizeDigest(params.digest);
-    const ciphertext = await this.fetchUserBackupCiphertext(walletId, params, signal);
-    const share = await restoreUserBackupShare(ciphertext, params.recoveryCode);
+    const backup = await this.fetchUserBackup(walletId, params, signal);
+    const share = await restoreUserBackupShare(backup, params);
     throwIfAborted(signal);
     const body = { digest };
     if (params.chainId !== void 0) body["chainId"] = params.chainId;
@@ -1690,7 +2036,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 });
@@ -1699,13 +2045,15 @@ var Wallets = class {
     return signature;
   }
   /**
-   * Retrieve the sealed `user_backup` ciphertext via the recovery gate ({@link fetchRecoveryCiphertext}),
-   * mapping a "no recovery share registered" (404) to the actionable `share_not_found` — this wallet has no
-   * client-held `user_backup` backup to co-sign with (its device-loss recovery is the custodial path instead).
+   * Retrieve the sealed `user_backup` backup via the recovery gate ({@link fetchRecoveryBackup}) — the
+   * ciphertext AND its key wraps (#510), since a backup registered with a passkey is an envelope and
+   * the wraps are what open it. Maps a "no recovery share registered" (404) to the actionable
+   * `share_not_found` — this wallet has no client-held `user_backup` backup to co-sign with (its
+   * device-loss recovery is the custodial path instead).
    */
-  async fetchUserBackupCiphertext(walletId, params, signal) {
+  async fetchUserBackup(walletId, params, signal) {
     try {
-      return await fetchRecoveryCiphertext(this.http, walletId, params, signal);
+      return await fetchRecoveryBackup(this.http, walletId, params, signal);
     } catch (cause) {
       if (cause instanceof WaaskeyError && cause.code === "not_found") {
         throw new WaaskeyError(
@@ -1827,38 +2175,15 @@ var Wallets = class {
     }
   }
 };
-async function restoreUserBackupShare(ciphertext, recoveryCode) {
+async function restoreUserBackupShare(backup, opener) {
   let blob;
   try {
-    blob = await openWithPassword(recoveryCode, ciphertext);
+    blob = await openRecoveryBlob(backup, opener);
   } catch (cause) {
-    throw new WaaskeyError("Could not open the user_backup backup \u2014 wrong recovery code?", "invalid_recovery_code", { cause });
+    throw new WaaskeyError("Could not open the user_backup backup \u2014 wrong recovery code or passkey?", "invalid_recovery_code", { cause });
   }
   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}`;
 }
@@ -1875,7 +2200,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:";
@@ -1967,13 +2302,12 @@ function isReadyMemberSignCeremony(ceremony) {
 }
 
 // src/client.ts
-var DEFAULT_BASE_URL = "https://api.waaskey.com";
 var Waaskey = class {
   /** The `wallets` resource. */
   wallets;
   /** The `recovery` resource — multi-factor, client-encrypted wallet recovery. */
   recovery;
-  /** The `reshare` resource — device-side completion of a device-retaining reshare (#318). */
+  /** The `reshare` resource — this device's half of a committee rotation (#488) and the aux-completion that follows (#318). */
   reshare;
   /** The `balances` resource — client-side balance reads from a chain provider (no backend). */
   balances;
@@ -1989,7 +2323,10 @@ var Waaskey = class {
     if (!options?.apiKey) {
       throw new Error("Waaskey: `apiKey` is required.");
     }
-    const http = new HttpClient(options.apiKey, options.baseUrl ?? DEFAULT_BASE_URL, options.fetch);
+    if (!options.baseUrl) {
+      throw new Error("Waaskey: `baseUrl` is required \u2014 pass the URL of your Waaskey API (there is no default).");
+    }
+    const http = new HttpClient(options.apiKey, options.baseUrl, options.fetch);
     const analytics = new Analytics(resolveSink(options.analytics, http));
     this.auth = new Auth(http);
     this.members = new Members(http);
@@ -2024,6 +2361,15 @@ function resolveSink(analytics, http) {
   return analytics ?? new HttpAnalyticsSink(http);
 }
 
+// src/passkey/recovery-factor.ts
+function passkeyFactorEnrollment(credentialId) {
+  return { type: "passkey", credential: credentialId };
+}
+async function passkeyFactorVerification(challenge, options = {}) {
+  const assertion = await getSigningAssertion(challenge, options);
+  return { type: "passkey", token: JSON.stringify(assertion) };
+}
+
 // src/mpc/wasm-core.ts
 var WasmMpcCore = class {
   constructor(load) {
@@ -2089,7 +2435,10 @@ var WasmMpcCore = class {
         new_threshold: params.newThreshold,
         wallet: params.wallet,
         commitments: params.commitments,
-        sub_shares: params.subShares
+        sub_shares: params.subShares,
+        // The core opens the SEALED sub-shares with this before it can verify or assemble anything;
+        // omitting it (as this did until #488) makes the call fail on its own parameter parse.
+        encryption_secret: params.encryptionSecret
       })
     );
     if (!raw || typeof raw.core_json !== "string") {
@@ -2097,6 +2446,26 @@ var WasmMpcCore = class {
     }
     return { core: raw.core_json, sharedPublicKey: decodePublicKey(raw.shared_public_key_json) };
   }
+  async runReshareDeal(params) {
+    const wasm = await this.init();
+    if (!wasm.reshareDeal) {
+      throw new Error(reshareFeatureHint("reshareDeal"));
+    }
+    const raw = await wasm.reshareDeal(
+      JSON.stringify({
+        curve: params.curve,
+        share: JSON.parse(params.share),
+        quorum_indices: params.quorumIndices,
+        new_preimages: params.newPreimages,
+        new_threshold: params.newThreshold,
+        recipient_pubkeys: params.recipientPubkeys
+      })
+    );
+    if (!raw || !Array.isArray(raw.sealed_sub_shares_hex)) {
+      throw new Error("client-wasm returned an unexpected reshareDeal result");
+    }
+    return { commitments: raw.commitments_json, sealedSubShares: raw.sealed_sub_shares_hex };
+  }
   async runCompleteReshare(params) {
     const wasm = await this.init();
     if (!wasm.completeReshare) {
@@ -2332,7 +2701,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.");
@@ -2797,6 +3166,10 @@ exports.isPasskeySupported = isPasskeySupported;
 exports.isPrfSupported = isPrfSupported;
 exports.loadClientWasm = loadClientWasm;
 exports.memberShareKey = memberShareKey;
+exports.openRecoveryBackup = openRecoveryBackup;
+exports.passkeyFactorEnrollment = passkeyFactorEnrollment;
+exports.passkeyFactorVerification = passkeyFactorVerification;
+exports.sealRecoveryBackup = sealRecoveryBackup;
 exports.userBackupPendingKey = userBackupPendingKey;
 exports.validateCustodyPolicy = validateCustodyPolicy;
 exports.verifyWasmIntegrity = verifyWasmIntegrity;