@waaskey/sdk 0.4.1 → 0.6.0

package/dist/index.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
 var ed25519_js = require('@noble/curves/ed25519.js');
+var secp256k1_js = require('@noble/curves/secp256k1.js');
+var sha3_js = require('@noble/hashes/sha3.js');
 
 // src/analytics/analytics.ts
 var Analytics = class {
@@ -316,6 +318,99 @@ async function broadcast(signedTx, options) {
   return { txHash: json.result };
 }
 
+// src/devices.ts
+var DEVICE_ID_KEY = "waaskey:device-id";
+var Devices = class {
+  constructor(http, store) {
+    this.http = http;
+    this.store = store;
+  }
+  http;
+  store;
+  /**
+   * This device's stable id, minting and persisting one on first use.
+   *
+   * A caller with no configured store must pass its own id to {@link register} — an id that is
+   * regenerated per call is worse than none: the registry would fill with orphan devices and none
+   * of them would match the share this browser actually holds.
+   *
+   * @throws {WaaskeyError} `device_store_required` — no store configured to persist the id.
+   */
+  async deviceId() {
+    if (!this.store) {
+      throw new WaaskeyError("A stable device id needs somewhere to live \u2014 pass `deviceStore` to `new Waaskey(...)`, or supply `deviceId` yourself.", "device_store_required");
+    }
+    const existing = await this.store.get(DEVICE_ID_KEY);
+    if (existing) return existing;
+    const minted = crypto.randomUUID();
+    await this.store.set(DEVICE_ID_KEY, minted);
+    return minted;
+  }
+  /**
+   * The persisted device id, or `undefined` when this client has never minted one.
+   *
+   * Read-only on purpose: it is how other resources DEFAULT to this device without minting an
+   * identity as a side effect of joining a ceremony. A silently minted id would be one this
+   * device never registered and holds no share for.
+   */
+  async stored() {
+    return await this.store?.get(DEVICE_ID_KEY) ?? void 0;
+  }
+  /**
+   * Register (or re-register) this device under the caller's member seat.
+   *
+   * Idempotent by `deviceId`: the backend upserts, so calling it on every start refreshes
+   * `lastSeenAt` and rotates the encryption public key without creating a second device. That
+   * matters — a duplicate device would appear in the picker as a share-holder candidate that holds
+   * nothing.
+   *
+   * `encryptionPublicKey` is this device's X25519 key; dealers seal reshare sub-shares and FROST
+   * round-2 packages to it, so a device that will hold a share should register one.
+   */
+  async register(registration, signal) {
+    const deviceId = registration.deviceId ?? await this.deviceId();
+    return this.http.requestAsMember(
+      "POST",
+      "/v1/devices",
+      { deviceId, label: registration.label, ...registration.encryptionPublicKey ? { encryptionPublicKey: registration.encryptionPublicKey } : {} },
+      signal
+    );
+  }
+  /** The caller's own registered devices — this one and their others. */
+  async list(signal) {
+    return this.http.requestAsMember("GET", "/v1/devices", void 0, signal);
+  }
+  /**
+   * The caller's devices, each marked whether it is THIS client (#57).
+   *
+   * A device-management UI cannot work this out on its own: the registry returns a member's
+   * devices with no notion of who is asking, and the only thing that distinguishes this browser is
+   * the id stored here. Getting it wrong is not cosmetic — "revoke" next to the wrong row revokes
+   * the device the user is standing on, and the backend will happily do it.
+   *
+   * Every device reads as "not this one" when this client has no stored id, which is the honest
+   * answer: it has no identity to match against.
+   */
+  async mine(signal) {
+    const [devices, current] = await Promise.all([this.list(signal), this.stored()]);
+    return devices.map((device) => ({ ...device, isThisDevice: current !== void 0 && device.deviceId === current }));
+  }
+  /**
+   * Revoke one of the caller's own devices by its registry id (not its `deviceId`).
+   *
+   * The backend tombstones any live shares it holds, and REFUSES (409) when that would strand a
+   * wallet mid-keygen or drop an active wallet below its signing threshold — losing the ability to
+   * sign is not something a device-management action gets to do quietly.
+   */
+  async revoke(id, signal) {
+    await this.http.requestAsMember("DELETE", `/v1/devices/${encodeURIComponent(id)}`, void 0, signal);
+  }
+  /** Forget this browser's device id, so the next {@link deviceId} mints a new one. */
+  async forget() {
+    await this.store?.delete(DEVICE_ID_KEY);
+  }
+};
+
 // src/http.ts
 var HttpClient = class {
   apiKey;
@@ -460,6 +555,36 @@ var Members = class {
   memberSignOut() {
     this.held = void 0;
   }
+  /**
+   * The tenant's team members, optionally narrowed to the share-holder-eligible roster (#57) —
+   * what a wallet creator picks share-holders from.
+   *
+   * `canHoldShare` is a per-membership capability, not part of the login identity, so it is only
+   * on this view: the session's own `member` does not carry it (see {@link eligibility}).
+   */
+  async list(options = {}, signal) {
+    const query = options.canHoldShare === void 0 ? "" : `?canHoldShare=${options.canHoldShare}`;
+    return this.http.requestAsMember("GET", `/v1/members${query}`, void 0, signal);
+  }
+  /**
+   * Whether the logged-in member may hold a wallet key share, and who else may — one call, because
+   * a device-picker UI needs both at once.
+   *
+   * It reads the roster to answer a question about the caller because the member session does not
+   * carry `canHoldShare` (the backend's session view is the login identity, `IMember`). Worth
+   * knowing rather than hiding: a UI that offers "hold a share on this device" to an ineligible
+   * member produces a create that the backend refuses at binding time, after the user has chosen.
+   *
+   * @throws {WaaskeyError} `unauthorized` — no member session is held.
+   */
+  async eligibility(signal) {
+    const self = this.held?.member;
+    if (!self) {
+      throw new WaaskeyError("Share-holder eligibility is a property of the logged-in member \u2014 call `members.loginWithFirebase(...)` first.", "unauthorized");
+    }
+    const eligible = await this.list({ canHoldShare: true }, signal);
+    return { canHoldShare: eligible.some((member) => member.id === self.id), eligible };
+  }
 };
 function mapFirebaseMemberError(error) {
   if (error instanceof WaaskeyError && error.status === 401) {
@@ -486,6 +611,54 @@ var Onramp = class {
   }
 };
 
+// src/passkey/assertion.ts
+function isPasskeyAssertionSupported() {
+  return typeof globalThis.navigator !== "undefined" && typeof globalThis.navigator.credentials !== "undefined";
+}
+async function defaultAssertionCeremony() {
+  let mod;
+  try {
+    mod = await import('@simplewebauthn/browser');
+  } catch {
+    throw new WaaskeyError('Passkey step-up requires "@simplewebauthn/browser" installed, or pass a custom ceremony.', "unsupported");
+  }
+  return {
+    get: (options) => mod.startAuthentication({ optionsJSON: options })
+  };
+}
+async function getSigningAssertion(challenge, options = {}) {
+  if (options.ceremony === void 0 && !isPasskeyAssertionSupported()) {
+    throw new WaaskeyError("Passkey step-up is not available in this runtime (no WebAuthn API).", "unsupported");
+  }
+  const ceremony = options.ceremony ?? await defaultAssertionCeremony();
+  const rpId = options.rpId ?? (typeof location === "undefined" ? void 0 : location.hostname);
+  const requestOptions = {
+    challenge,
+    userVerification: "required",
+    ...rpId ? { rpId } : {},
+    ...options.credentialId ? { allowCredentials: [{ id: options.credentialId, type: "public-key" }] } : {}
+  };
+  try {
+    return await ceremony.get(requestOptions);
+  } catch (cause) {
+    if (cause instanceof WaaskeyError) throw cause;
+    const msg = cause instanceof Error ? cause.message : String(cause);
+    if (/cancel|abort|not allowed|user gesture/i.test(msg)) {
+      throw new WaaskeyError("Passkey authentication was cancelled by the user.", "aborted", { cause });
+    }
+    throw new WaaskeyError("Passkey step-up assertion failed.", "unsupported", { cause });
+  }
+}
+
+// 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/storage/crypto.ts
 var PBKDF2_ITERATIONS = 21e4;
 var PBKDF2_HASH = "SHA-256";
@@ -687,8 +860,12 @@ var Recovery = class {
 async function buildRecoveryRegistration(params) {
   const recoveryCode = params.recoveryCode ?? generateRecoveryCode();
   const backup = params.passkey ? await sealRecoveryBackup(params.share, recoveryCode, params.passkey) : { ciphertext: await sealWithPassword(recoveryCode, params.share), keyWraps: void 0 };
+  if (params.passkeyFactor && !params.passkey) {
+    throw new WaaskeyError("passkeyFactor requires `passkey` \u2014 a factor for a credential this backup cannot open would be a lock-out.", "validation");
+  }
+  const strongFactor = params.passkeyFactor ? passkeyFactorEnrollment(params.passkey.credentialId) : { type: "recovery_code", credential: await sha256Hex(recoveryCode) };
   const factors = [
-    { type: "recovery_code", credential: await sha256Hex(recoveryCode) },
+    strongFactor,
     { type: "totp", credential: params.totpSecret },
     { type: "email_otp", credential: params.email },
     ...params.extraFactors ?? []
@@ -1035,6 +1212,259 @@ function assertPublicKey(actual, expected, walletId) {
 function serializeCompletedShare(completed) {
   return JSON.stringify({ keyShare: completed.keyShare, sharedPublicKey: completed.sharedPublicKey });
 }
+var SessionKeys = class {
+  constructor(http, walletUrl) {
+    this.http = http;
+    this.walletUrl = walletUrl;
+  }
+  http;
+  walletUrl;
+  /**
+   * Ask a user for a permission, and get back a link to send them to (#113).
+   *
+   * The keypair is generated HERE and only its public half is registered, so nothing secret ever
+   * travels: not in the request, not in the link, not through the wallet. The private key in the
+   * result is the app's to keep — there is no way to retrieve it later, by design.
+   *
+   * The link is where the user answers. Open it, or render it as a QR code for a wallet on another
+   * device. Then wait for the answer with {@link waitForDecision}.
+   *
+   * @example
+   * ```ts
+   * const req = await waaskey.sessionKeys.request({
+   *   walletId, label: 'Dungeon Quest — one battle',
+   *   scope: { allowedContracts: [game], maxCalls: 50, periodSeconds: 3600, maxCallsPerPeriod: 10 },
+   *   expiresAt: new Date(Date.now() + 24 * 3600_000),
+   * });
+   * showQrCode(req.url);
+   * const { status, key, narrowed } = await waaskey.sessionKeys.waitForDecision(req.sessionKeyId);
+   * ```
+   */
+  async request(params, signal) {
+    if (!this.walletUrl) {
+      throw new WaaskeyError("Waaskey: `walletUrl` is required to request a permission \u2014 pass it to the client, pointing at the wallet that answers.", "validation");
+    }
+    const privateKey = generatePrivateKey();
+    const publicKey = `0x${toHex(secp256k1_js.secp256k1.getPublicKey(hexToBytes(privateKey), true))}`;
+    const key = await this.http.request(
+      "POST",
+      "/aa/session-keys",
+      {
+        walletId: params.walletId,
+        publicKey,
+        permissions: params.scope,
+        expiresAt: toIso(params.expiresAt),
+        label: params.label,
+        requesterId: params.requesterId,
+        paymasterPolicyId: params.paymasterPolicyId
+      },
+      signal
+    );
+    return { sessionKeyId: key.id, privateKey, publicKey, url: permissionUrl(this.walletUrl, key.id), status: key.grantStatus ?? "approved" };
+  }
+  /** One permission as it now stands — including whether its owner has answered yet. */
+  get(sessionKeyId, signal) {
+    return this.http.request("GET", `/aa/session-keys/${encodeURIComponent(sessionKeyId)}`, void 0, signal);
+  }
+  /**
+   * The app that asked for a permission — who it says it is, and whether its domain proved it.
+   *
+   * A wallet rendering a consent screen needs this, and hand-rolling the call is how a client ends
+   * up showing `name` without `status` beside it — which reads as verified whether or not it is.
+   */
+  requester(requesterId, signal) {
+    return this.http.request("GET", `/aa/requesters/${encodeURIComponent(requesterId)}`, void 0, signal);
+  }
+  /**
+   * Wait for the user to answer a permission request (#113).
+   *
+   * Polls, rather than waiting on a redirect back: a user who answers on their phone, or closes the
+   * tab, or takes a minute to read the screen would otherwise strand the app with no answer at all.
+   *
+   * Returns as soon as the wallet's owner has decided — `declined` is an answer, not an error, and
+   * is returned rather than thrown so the app can say something useful. A request that is never
+   * answered times out, which IS an error: it is indistinguishable from a user who walked away.
+   *
+   * `narrowed` says the user accepted less than was asked (they may narrow, never widen), so an app
+   * can adapt to the smaller scope instead of failing opaquely on the first call outside it.
+   */
+  async waitForDecision(sessionKeyId, options = {}) {
+    const { timeoutMs = 5 * 6e4, pollMs = 2e3, signal, asked } = options;
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const key = await this.get(sessionKeyId, signal);
+      const status = key.grantStatus ?? "approved";
+      if (status !== "pending") {
+        return { status, key, narrowed: asked ? wasNarrowed(asked, key) : false };
+      }
+      if (Date.now() + pollMs >= deadline) {
+        throw new WaaskeyError(`Waaskey: the permission request was not answered within ${Math.round(timeoutMs / 1e3)}s.`, "permission_request_timeout", {
+          details: { sessionKeyId }
+        });
+      }
+      await delay2(pollMs, signal);
+    }
+  }
+  /** The tenant's active session keys, newest first (optionally for one wallet). */
+  list(walletId, signal) {
+    const query = walletId ? `?walletId=${encodeURIComponent(walletId)}` : "";
+    return this.http.request("GET", `/aa/session-keys${query}`, void 0, signal);
+  }
+  /**
+   * Sign a call with a session key and submit it as a UserOperation.
+   *
+   * The op is prepared server-side first, because its gas and paymaster fields are part of what the
+   * signature covers: signing a locally-guessed op would produce a signature for an operation the
+   * bundler never sees. Those exact fields are then sent back with the signature, so what was
+   * signed is what is submitted.
+   *
+   * @example
+   * ```ts
+   * const { userOpHash } = await waaskey.sessionKeys.send({
+   *   sessionKeyId, privateKey,           // the granted permission
+   *   sender, chainId: 'evm:1',           // the smart account it acts for
+   *   callData, contract, selector, valueWei: '0x0',
+   * });
+   * ```
+   */
+  async send(params, signal) {
+    const prepared = await this.http.request(
+      "POST",
+      "/aa/user-ops/prepare",
+      { sender: params.sender, callData: params.callData, chainId: params.chainId, nonce: params.nonce },
+      signal
+    );
+    const signature = signUserOpHash(prepared.userOpHash, params.privateKey);
+    try {
+      return await this.http.request(
+        "POST",
+        `/aa/session-keys/${encodeURIComponent(params.sessionKeyId)}/send`,
+        {
+          sender: params.sender,
+          nonce: prepared.nonce,
+          callData: params.callData,
+          signature,
+          chainId: params.chainId,
+          entryPoint: prepared.entryPoint,
+          contract: params.contract,
+          selector: params.selector,
+          valueWei: params.valueWei,
+          // Exactly the op that was signed — see the note above.
+          prepared: {
+            initCode: prepared.initCode,
+            callGasLimit: prepared.callGasLimit,
+            verificationGasLimit: prepared.verificationGasLimit,
+            preVerificationGas: prepared.preVerificationGas,
+            maxFeePerGas: prepared.maxFeePerGas,
+            maxPriorityFeePerGas: prepared.maxPriorityFeePerGas,
+            paymasterAndData: prepared.paymasterAndData
+          }
+        },
+        signal
+      );
+    } catch (error) {
+      throw asPermissionError(error);
+    }
+  }
+};
+function signUserOpHash(userOpHash, privateKey) {
+  const hash = hexToBytes(userOpHash);
+  if (hash.length !== 32) {
+    throw new WaaskeyError("Waaskey: userOpHash must be 32 bytes.", "validation");
+  }
+  const prefix = new TextEncoder().encode("Ethereum Signed Message:\n32");
+  const digest = sha3_js.keccak_256(concat(prefix, hash));
+  const signature = secp256k1_js.secp256k1.sign(digest, hexToBytes(privateKey), { prehash: false, format: "recovered" });
+  const [recovery] = signature;
+  if (recovery === void 0) {
+    throw new WaaskeyError("Waaskey: could not sign the userOpHash.", "sign_failed");
+  }
+  return `0x${toHex(signature.slice(1))}${(27 + recovery).toString(16).padStart(2, "0")}`;
+}
+function asPermissionError(error) {
+  if (!(error instanceof WaaskeyError) || error.status !== 422) return error;
+  const code = fromServerCode(error.details) ?? fromWording(error.message);
+  return code ? new WaaskeyError(error.message, code, { status: error.status, details: error.details }) : error;
+}
+function fromServerCode(details) {
+  const code = details?.code;
+  if (typeof code !== "string") return void 0;
+  const byCode = {
+    expired: "permission_expired",
+    revoked: "permission_revoked",
+    scope_chain: "permission_scope",
+    scope_contract: "permission_scope",
+    scope_selector: "permission_scope",
+    value_exceeded: "permission_value_exceeded",
+    calls_exhausted: "permission_exhausted",
+    // Both rate bounds mean the same thing to a caller: wait for the next period, do not re-request
+    // the grant. The message says which one ran out.
+    rate_calls_exhausted: "permission_rate_limited",
+    rate_value_exceeded: "permission_rate_limited"
+  };
+  return byCode[code];
+}
+function fromWording(message) {
+  const reason = message.toLowerCase();
+  return reason.includes("expired") ? "permission_expired" : reason.includes("inactive") ? "permission_revoked" : reason.includes("maxcalls") ? "permission_exhausted" : reason.includes("value exceeds") ? "permission_value_exceeded" : reason.includes("allowlist") || reason.includes("not permitted") ? "permission_scope" : void 0;
+}
+function generatePrivateKey() {
+  return `0x${toHex(secp256k1_js.secp256k1.utils.randomSecretKey())}`;
+}
+function permissionUrl(walletUrl, sessionKeyId) {
+  const base = walletUrl.endsWith("/") ? walletUrl.slice(0, -1) : walletUrl;
+  return `${base}/permissions/${encodeURIComponent(sessionKeyId)}`;
+}
+function toIso(when) {
+  return typeof when === "string" ? when : when.toISOString();
+}
+function wasNarrowed(asked, key) {
+  const got = key.permissions ?? {};
+  const tighter = (before, after) => {
+    if (after === void 0) return false;
+    if (before === void 0) return true;
+    return BigInt(after) < BigInt(before);
+  };
+  const shorter = (before, after) => (after?.length ?? 0) > 0 && (before?.length ?? 0) !== (after?.length ?? 0);
+  return tighter(asked.maxCalls, got.maxCalls) || tighter(asked.maxValueWei, got.maxValueWei) || tighter(asked.maxCallsPerPeriod, got.maxCallsPerPeriod) || tighter(asked.maxValueWeiPerPeriod, got.maxValueWeiPerPeriod) || shorter(asked.allowedContracts, got.allowedContracts) || shorter(asked.allowedSelectors, got.allowedSelectors) || shorter(asked.allowedChains, got.allowedChains);
+}
+function delay2(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new WaaskeyError("Waaskey: the permission request was aborted.", "aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new WaaskeyError("Waaskey: the permission request was aborted.", "aborted"));
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function hexToBytes(hex) {
+  const clean = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+  if (clean.length % 2 !== 0 || /[^0-9a-fA-F]/.test(clean)) {
+    throw new WaaskeyError("Waaskey: expected a hex string.", "validation");
+  }
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function concat(a, b) {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a);
+  out.set(b, a.length);
+  return out;
+}
+function toHex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
 
 // src/custody.ts
 var CUSTODY_KINDS = /* @__PURE__ */ new Set(["user_device", "user_backup", "platform_signer", "platform_recovery", "external_party"]);
@@ -1171,45 +1601,6 @@ function deserializeShare(blob) {
   };
 }
 
-// src/passkey/assertion.ts
-function isPasskeyAssertionSupported() {
-  return typeof globalThis.navigator !== "undefined" && typeof globalThis.navigator.credentials !== "undefined";
-}
-async function defaultAssertionCeremony() {
-  let mod;
-  try {
-    mod = await import('@simplewebauthn/browser');
-  } catch {
-    throw new WaaskeyError('Passkey step-up requires "@simplewebauthn/browser" installed, or pass a custom ceremony.', "unsupported");
-  }
-  return {
-    get: (options) => mod.startAuthentication({ optionsJSON: options })
-  };
-}
-async function getSigningAssertion(challenge, options = {}) {
-  if (options.ceremony === void 0 && !isPasskeyAssertionSupported()) {
-    throw new WaaskeyError("Passkey step-up is not available in this runtime (no WebAuthn API).", "unsupported");
-  }
-  const ceremony = options.ceremony ?? await defaultAssertionCeremony();
-  const rpId = options.rpId ?? (typeof location === "undefined" ? void 0 : location.hostname);
-  const requestOptions = {
-    challenge,
-    userVerification: "required",
-    ...rpId ? { rpId } : {},
-    ...options.credentialId ? { allowCredentials: [{ id: options.credentialId, type: "public-key" }] } : {}
-  };
-  try {
-    return await ceremony.get(requestOptions);
-  } catch (cause) {
-    if (cause instanceof WaaskeyError) throw cause;
-    const msg = cause instanceof Error ? cause.message : String(cause);
-    if (/cancel|abort|not allowed|user gesture/i.test(msg)) {
-      throw new WaaskeyError("Passkey authentication was cancelled by the user.", "aborted", { cause });
-    }
-    throw new WaaskeyError("Passkey step-up assertion failed.", "unsupported", { cause });
-  }
-}
-
 // src/wallet.ts
 var DEVICE_ROLE = "device";
 var Wallet = class {
@@ -1653,7 +2044,7 @@ var Wallets = class {
     if (curve === "ed25519") {
       await this.runEddsaKeygen(mpc, shareStore, created.id, ceremony, deviceEncKeypair);
     } else {
-      await this.runSecpKeygen(mpc, shareStore, primePool, created.id, ceremony, curve, options.backup, signal);
+      await this.runSecpKeygen(mpc, shareStore, primePool, created.id, ceremony, curve, options.backup, signal, options.onRecoveryEnrolled);
     }
     this.deps.analytics?.track("wallet.created", { walletId: created.id, chain: params.chain, curve });
     if (options.waitForActive === false) {
@@ -1753,13 +2144,15 @@ var Wallets = class {
     }
     const { signal } = options;
     throwIfAborted(signal);
+    const deviceId = await this.resolveDeviceId(options.deviceId);
+    const query = deviceId ? `?deviceId=${encodeURIComponent(deviceId)}` : "";
     const [ceremony, shareholders] = await Promise.all([
-      this.http.requestAsMember("GET", `/v1/wallets/${walletId}/ceremony/mine`, void 0, signal),
+      this.http.requestAsMember("GET", `/v1/wallets/${walletId}/ceremony/mine${query}`, void 0, signal),
       this.http.requestAsMember("GET", `/v1/wallets/${walletId}/shareholders`, void 0, signal)
     ]);
     const roles = buildMemberRoster(shareholders, ceremony.parties);
     throwIfAborted(signal);
-    const joined = await this.http.requestAsMember("POST", `/v1/wallets/${walletId}/ceremony/join`, void 0, signal);
+    const joined = await this.http.requestAsMember("POST", `/v1/wallets/${walletId}/ceremony/join${query}`, void 0, signal);
     throwIfAborted(signal);
     let keygen;
     try {
@@ -1776,7 +2169,7 @@ var Wallets = class {
       if (cause instanceof WaaskeyError) throw cause;
       throw new WaaskeyError("The member device keygen ceremony failed.", "keygen_failed", { cause });
     }
-    await shareStore.put(memberShareKey(walletId, membershipIdFromRole(ceremony.role)), serializeShare(keygen));
+    await shareStore.put(memberShareKey(walletId, membershipIdFromRole(ceremony.role), deviceId), serializeShare(keygen));
     return joined;
   }
   /**
@@ -1807,12 +2200,13 @@ var Wallets = class {
     const { signal } = options;
     throwIfAborted(signal);
     await this.http.requestAsMember("POST", `/v1/wallets/${walletId}/sign-requests/${reqId}/approve`, void 0, signal);
-    const ceremony = await this.waitUntilReady(walletId, reqId, options);
+    const deviceId = await this.resolveDeviceId(options.deviceId);
+    const ceremony = await this.waitUntilReady(walletId, reqId, options, deviceId);
     const membershipId = membershipIdFromRole(ceremony.role);
-    const blob = await shareStore.get(memberShareKey(walletId, membershipId));
+    const blob = await shareStore.get(memberShareKey(walletId, membershipId, deviceId));
     if (!blob) {
       throw new WaaskeyError(`No stored device share for wallet "${walletId}" / member "${membershipId}" \u2014 this device never completed joinCeremony.`, "share_not_found", {
-        details: { walletId, membershipId }
+        details: { walletId, membershipId, ...deviceId ? { deviceId } : {} }
       });
     }
     const { keyShare } = deserializeShare(blob);
@@ -1895,7 +2289,7 @@ var Wallets = class {
    * Any additional party the client cannot drive (a non-`user_backup` role) is refused up front — leaving
    * it unjoined would hang the whole ceremony, so failing loud beats silently deadlocking.
    */
-  async runSecpKeygen(mpc, shareStore, primePool, walletId, ceremony, curve, backup, signal) {
+  async runSecpKeygen(mpc, shareStore, primePool, walletId, ceremony, curve, backup, signal, onEnrolled) {
     const extras = ceremony.additionalParties ?? [];
     const unsupported = extras.filter((party) => party.role !== USER_BACKUP_ROLE2);
     if (unsupported.length > 0) {
@@ -1907,10 +2301,15 @@ var Wallets = class {
     }
     const userBackupParty = extras.find((party) => party.role === USER_BACKUP_ROLE2);
     if (!userBackupParty) {
-      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, ceremony.relayUrl));
+      const lease = primePool ? await primePool.borrow(curve) : void 0;
+      try {
+        throwIfAborted(signal);
+        const [keygen] = await this.runKeygenParties(mpc, [{ ...ceremony, curve, pregeneratedPrimes: lease?.primes }]);
+        lease?.consume();
+        await shareStore.put(walletId, serializeShare(keygen, ceremony.relayUrl));
+      } finally {
+        await lease?.release();
+      }
       return;
     }
     if (!backup) {
@@ -1919,15 +2318,42 @@ var Wallets = class {
         "validation"
       );
     }
-    const [devicePrimes, backupPrimes] = primePool ? await Promise.all([primePool.take(curve), primePool.take(curve)]) : [void 0, void 0];
+    const [deviceLease, backupLease] = primePool ? await Promise.all([primePool.borrow(curve), primePool.borrow(curve)]) : [void 0, void 0];
+    try {
+      await this.runNonCustodialKeygen(
+        mpc,
+        shareStore,
+        walletId,
+        ceremony,
+        userBackupParty,
+        curve,
+        backup,
+        signal,
+        deviceLease?.primes,
+        backupLease?.primes,
+        () => {
+          deviceLease?.consume();
+          backupLease?.consume();
+        },
+        onEnrolled
+      );
+    } finally {
+      await Promise.all([deviceLease?.release(), backupLease?.release()]);
+    }
+  }
+  /** The `[device, server, user_backup]` ceremony itself — see {@link runSecpKeygen} for why the primes are leased. */
+  async runNonCustodialKeygen(mpc, shareStore, walletId, ceremony, userBackupParty, curve, backup, signal, devicePrimes, backupPrimes, onDerived, onEnrolled) {
     throwIfAborted(signal);
     const [deviceKeygen, backupKeygen] = await this.runKeygenParties(mpc, [
       { ...ceremony, curve, pregeneratedPrimes: devicePrimes },
       { ...userBackupParty, curve, pregeneratedPrimes: backupPrimes }
     ]);
+    onDerived();
     await shareStore.put(walletId, serializeShare(deviceKeygen, ceremony.relayUrl));
     throwIfAborted(signal);
-    const { payload } = await buildRecoveryRegistration({ share: serializeShare(backupKeygen), ...backup });
+    const enrolment = await resolveRecoveryEnrolment(backup);
+    onEnrolled?.(enrolment.outcome);
+    const { payload } = await buildRecoveryRegistration({ share: serializeShare(backupKeygen), ...backup, ...enrolment.params });
     await shareStore.put(userBackupPendingKey(walletId), JSON.stringify(payload));
     await this.registerBackup(walletId, payload, signal);
     await shareStore.remove(userBackupPendingKey(walletId));
@@ -2159,14 +2585,26 @@ var Wallets = class {
     }
   }
   /** Poll the member's own sign ceremony until the t-of-n quorum is fixed AND this member is selected, or throw on timeout. */
-  async waitUntilReady(walletId, reqId, options) {
+  /**
+   * The device id to act as: an explicit one, else the client's stored id, else none.
+   *
+   * `undefined` is a legitimate answer, not a failure — a single-device member and every existing
+   * consumer built before per-device shares work exactly as they did, on the un-suffixed key and
+   * the un-parameterised endpoints.
+   */
+  async resolveDeviceId(explicit) {
+    if (explicit) return explicit;
+    return this.deps.devices ? this.deps.devices.stored() : void 0;
+  }
+  async waitUntilReady(walletId, reqId, options, deviceId) {
     const timeoutMs = options.readyTimeoutMs ?? DEFAULT_ACTIVATION_TIMEOUT_MS;
     const intervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     const { signal } = options;
     const deadline = Date.now() + timeoutMs;
     for (; ; ) {
       throwIfAborted(signal);
-      const ceremony = await this.http.requestAsMember("GET", `/v1/wallets/${walletId}/sign-requests/${reqId}/ceremony/mine`, void 0, signal);
+      const query = deviceId ? `?deviceId=${encodeURIComponent(deviceId)}` : "";
+      const ceremony = await this.http.requestAsMember("GET", `/v1/wallets/${walletId}/sign-requests/${reqId}/ceremony/mine${query}`, void 0, signal);
       if (isReadyMemberSignCeremony(ceremony)) return ceremony;
       if (Date.now() >= deadline) {
         throw new WaaskeyError("The signing quorum did not fix (or did not select this member) before the timeout.", "sign_ceremony_timeout", { details: { walletId, reqId } });
@@ -2184,8 +2622,9 @@ async function restoreUserBackupShare(backup, opener) {
   }
   return deserializeShare(blob).keyShare;
 }
-function memberShareKey(walletId, membershipId) {
-  return `${walletId}@member-${membershipId}`;
+function memberShareKey(walletId, membershipId, deviceId) {
+  const base = `${walletId}@member-${membershipId}`;
+  return deviceId ? `${base}:${deviceId}` : base;
 }
 function userBackupPendingKey(walletId) {
   return `${walletId}:user_backup_pending`;
@@ -2300,6 +2739,26 @@ function readEddsaEncRoster(ceremony, encKeypair) {
 function isReadyMemberSignCeremony(ceremony) {
   return ceremony.ready && ceremony.quorumRoles !== void 0 && ceremony.signerPosition !== void 0 && ceremony.participants !== void 0 && ceremony.digest !== void 0;
 }
+async function resolveRecoveryEnrolment(backup) {
+  if (backup.passkey) {
+    return {
+      params: { passkey: backup.passkey, passkeyFactor: backup.passkeyFactor ?? true },
+      outcome: { strongFactor: backup.passkeyFactor === false ? "recovery_code" : "passkey" }
+    };
+  }
+  if (!backup.passkeyEnroller) {
+    return { params: {}, outcome: { strongFactor: "recovery_code", fallbackReason: "no_passkey_enroller" } };
+  }
+  try {
+    const credential = await backup.passkeyEnroller();
+    if (!credential) {
+      return { params: {}, outcome: { strongFactor: "recovery_code", fallbackReason: "device_cannot_prf" } };
+    }
+    return { params: { passkey: credential, passkeyFactor: true }, outcome: { strongFactor: "passkey" } };
+  } catch {
+    return { params: {}, outcome: { strongFactor: "recovery_code", fallbackReason: "enrolment_failed" } };
+  }
+}
 
 // src/client.ts
 var Waaskey = class {
@@ -2315,8 +2774,12 @@ var Waaskey = class {
   auth;
   /** The `members` resource — org-member (dashboard "plane B") bearer login for headless consumers. */
   members;
+  /** The `devices` resource — this client as a member DEVICE that can hold an MPC share (#53). */
+  devices;
   /** The `onramp` resource — fund the wallet with fiat via a provider on-ramp. */
   onramp;
+  /** The `sessionKeys` resource — act with a delegated, scoped permission (#112). */
+  sessionKeys;
   /** Default fetch used by the optional {@link broadcast} helper (from `WaaskeyOptions.fetch`). */
   defaultFetch;
   constructor(options) {
@@ -2331,11 +2794,13 @@ var Waaskey = class {
     this.auth = new Auth(http);
     this.members = new Members(http);
     http.useMemberAccessToken(() => this.members.accessToken);
-    this.wallets = new Wallets(http, { mpc: options.mpc, shareStore: options.shareStore, primePool: options.primePool, analytics });
+    this.devices = new Devices(http, options.deviceStore);
+    this.wallets = new Wallets(http, { mpc: options.mpc, shareStore: options.shareStore, primePool: options.primePool, analytics, devices: this.devices });
     this.recovery = new Recovery(http, { shareStore: options.shareStore, analytics });
     this.reshare = new Reshare(http, { mpc: options.mpc, shareStore: options.shareStore, analytics });
     this.balances = new Balances(options.chains, options.fetch);
     this.onramp = new Onramp(http);
+    this.sessionKeys = new SessionKeys(http, options.walletUrl);
     this.defaultFetch = options.fetch;
   }
   /**
@@ -2361,13 +2826,66 @@ function resolveSink(analytics, http) {
   return analytics ?? new HttpAnalyticsSink(http);
 }
 
-// src/passkey/recovery-factor.ts
-function passkeyFactorEnrollment(credentialId) {
-  return { type: "passkey", credential: credentialId };
+// src/secret-envelope.ts
+var KEK_INFO2 = "waaskey-unlock-kek-v1";
+function newUnlockSecret() {
+  return bytesToBase64(randomBytes(32));
+}
+async function sealSecret(secret, methods) {
+  const wraps = [];
+  if (methods.passphrase !== void 0) {
+    const salt = freshSalt();
+    wraps.push({ method: "passphrase", wrapped: await seal(await deriveKey(methods.passphrase, salt), secret), salt: bytesToBase64(salt) });
+  }
+  if (methods.passkey) {
+    const salt = base64ToBytes(methods.passkey.salt);
+    wraps.push({
+      method: "passkey_prf",
+      wrapped: await seal(await deriveKeyFromBytes(base64ToBytes(methods.passkey.secret), salt, KEK_INFO2), secret),
+      salt: methods.passkey.salt,
+      credentialId: methods.passkey.credentialId
+    });
+  }
+  if (wraps.length === 0) {
+    throw new WaaskeyError("An unlock envelope needs at least one method \u2014 a secret nothing can unwrap is unrecoverable.", "validation");
+  }
+  return { wraps };
 }
-async function passkeyFactorVerification(challenge, options = {}) {
-  const assertion = await getSigningAssertion(challenge, options);
-  return { type: "passkey", token: JSON.stringify(assertion) };
+async function addMethod(envelope, secret, method) {
+  const added = await sealSecret(secret, method);
+  const kinds = new Set(added.wraps.map((wrap) => wrap.method));
+  return { wraps: [...envelope.wraps.filter((wrap) => !kinds.has(wrap.method)), ...added.wraps] };
+}
+function removeMethod(envelope, method) {
+  const wraps = envelope.wraps.filter((wrap) => wrap.method !== method);
+  if (wraps.length === 0) {
+    throw new WaaskeyError(`Removing '${method}' would leave nothing that can unlock this device \u2014 enrol another method first.`, "validation");
+  }
+  return { wraps };
+}
+async function openSecret(envelope, opener) {
+  const prfWrap = envelope.wraps.find((wrap) => wrap.method === "passkey_prf");
+  if (opener.passkeySecret !== void 0 && prfWrap) {
+    const kek = await deriveKeyFromBytes(base64ToBytes(opener.passkeySecret), base64ToBytes(prfWrap.salt), KEK_INFO2);
+    return unwrap(prfWrap, kek, "passkey");
+  }
+  const passphraseWrap = envelope.wraps.find((wrap) => wrap.method === "passphrase");
+  if (opener.passphrase !== void 0 && passphraseWrap) {
+    const kek = await deriveKey(opener.passphrase, base64ToBytes(passphraseWrap.salt));
+    return unwrap(passphraseWrap, kek, "passphrase");
+  }
+  const enrolled = envelope.wraps.map((wrap) => wrap.method).join(", ") || "none";
+  throw new WaaskeyError(`Nothing supplied can unlock this device \u2014 it accepts [${enrolled}].`, "unauthorized");
+}
+function enrolledMethods(envelope) {
+  return envelope.wraps.map((wrap) => wrap.method);
+}
+async function unwrap(wrap, kek, label) {
+  try {
+    return await open(kek, wrap.wrapped);
+  } catch (cause) {
+    throw new WaaskeyError(`Could not unlock with the ${label} \u2014 wrong ${label}?`, "unauthorized", { cause });
+  }
 }
 
 // src/mpc/wasm-core.ts
@@ -2801,11 +3319,13 @@ var PrimePool = class {
     this.store = options.store ?? new MemoryPrimeStore();
     this.targetSize = Math.max(1, options.targetSize ?? 2);
     this.autoRefill = options.autoRefill ?? false;
+    this.concurrency = Math.max(1, options.concurrency ?? 1);
   }
   core;
   store;
   targetSize;
   autoRefill;
+  concurrency;
   /** Per-curve in-flight refill, so concurrent calls don't over-generate. */
   refilling = /* @__PURE__ */ new Map();
   /**
@@ -2820,8 +3340,10 @@ var PrimePool = class {
     return task;
   }
   async refill(curve) {
-    while (await this.store.size(curve) < this.targetSize) {
-      await this.store.add(curve, await this.core.pregeneratePrimes(curve));
+    for (let missing = this.targetSize - await this.store.size(curve); missing > 0; missing = this.targetSize - await this.store.size(curve)) {
+      const batch = Math.min(missing, this.concurrency);
+      const generated = await Promise.all(Array.from({ length: batch }, () => this.core.pregeneratePrimes(curve)));
+      for (const primes of generated) await this.store.add(curve, primes);
     }
   }
   /**
@@ -2836,6 +3358,28 @@ var PrimePool = class {
     if (this.autoRefill) void this.ensure(curve).catch(() => void 0);
     return primes;
   }
+  /**
+   * Claim primes as a LEASE, so a failed ceremony gives them back (#83).
+   *
+   * Prefer this over {@link take} anywhere the primes feed a ceremony that can fail: `take` hands
+   * them over unconditionally, and a keygen that dies on a relay timeout then costs the next
+   * attempt a full generation it did not need to pay.
+   */
+  async borrow(curve) {
+    const primes = await this.take(curve);
+    let settled = false;
+    return {
+      primes,
+      consume: () => {
+        settled = true;
+      },
+      release: async () => {
+        if (settled) return;
+        settled = true;
+        await this.store.add(curve, primes);
+      }
+    };
+  }
 };
 
 // src/storage/indexeddb-store.ts
@@ -3137,6 +3681,7 @@ exports.Analytics = Analytics;
 exports.Auth = Auth;
 exports.Balances = Balances;
 exports.CLIENT_WASM_VERSION = CLIENT_WASM_VERSION;
+exports.Devices = Devices;
 exports.EncryptedShareStore = EncryptedShareStore;
 exports.EvmRpcProvider = EvmRpcProvider;
 exports.HttpAnalyticsSink = HttpAnalyticsSink;
@@ -3149,13 +3694,16 @@ exports.PasskeyPrfSecretProvider = PasskeyPrfSecretProvider;
 exports.PrimePool = PrimePool;
 exports.Recovery = Recovery;
 exports.Reshare = Reshare;
+exports.SessionKeys = SessionKeys;
 exports.Waaskey = Waaskey;
 exports.WaaskeyError = WaaskeyError;
 exports.Wallet = Wallet;
 exports.Wallets = Wallets;
 exports.WasmMpcCore = WasmMpcCore;
+exports.addMethod = addMethod;
 exports.broadcast = broadcast;
 exports.createVerifiedClientWasmLoader = createVerifiedClientWasmLoader;
+exports.enrolledMethods = enrolledMethods;
 exports.epochShareKey = epochShareKey;
 exports.formatUnits = formatUnits;
 exports.generateRecoveryCode = generateRecoveryCode;
@@ -3166,10 +3714,15 @@ exports.isPasskeySupported = isPasskeySupported;
 exports.isPrfSupported = isPrfSupported;
 exports.loadClientWasm = loadClientWasm;
 exports.memberShareKey = memberShareKey;
+exports.newUnlockSecret = newUnlockSecret;
 exports.openRecoveryBackup = openRecoveryBackup;
+exports.openSecret = openSecret;
 exports.passkeyFactorEnrollment = passkeyFactorEnrollment;
 exports.passkeyFactorVerification = passkeyFactorVerification;
+exports.removeMethod = removeMethod;
 exports.sealRecoveryBackup = sealRecoveryBackup;
+exports.sealSecret = sealSecret;
+exports.signUserOpHash = signUserOpHash;
 exports.userBackupPendingKey = userBackupPendingKey;
 exports.validateCustodyPolicy = validateCustodyPolicy;
 exports.verifyWasmIntegrity = verifyWasmIntegrity;