@waaskey/sdk 0.3.2 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialRequestOptionsJSON, AuthenticationResponseJSON } from '@simplewebauthn/browser';
+import { PublicKeyCredentialRequestOptionsJSON, AuthenticationResponseJSON, PublicKeyCredentialCreationOptionsJSON } from '@simplewebauthn/browser';
 
 /** Thin typed HTTP client over fetch — the single place requests are issued. */
 declare class HttpClient {
@@ -270,8 +270,50 @@ interface DeviceReshareAssembleParams {
     wallet: unknown;
     /** One Feldman-commitments object per dealer (the broadcast set), opaque JSON. */
     commitments: unknown[];
-    /** This device's private sub-share from each dealer, one per dealer, opaque JSON. */
+    /**
+     * This device's SEALED sub-share from each dealer, one per dealer — hex ciphertext, opened with
+     * {@link encryptionSecret} before the core verifies and assembles it.
+     */
     subShares: unknown[];
+    /**
+     * This holder's X25519 SECRET key (32-byte hex) — the counterpart of the public key the dealers
+     * sealed to, and the only thing that can open {@link subShares}.
+     *
+     * Required: dealers seal every sub-share (waas-core #365 M-A), so an assemble without it cannot
+     * even parse its inputs. SECRET — never log it.
+     */
+    encryptionSecret: string;
+}
+/**
+ * Parameters for the device's reshare **deal** stage ({@link MpcCore.runReshareDeal}) — the OLD
+ * holder's half, computed locally from its current share. Pure: no relay, no rounds.
+ */
+interface DeviceReshareDealParams {
+    curve: MpcCurve;
+    /** This holder's CURRENT (old-epoch) key share JSON. Secret — never log it. */
+    share: string;
+    /** Keygen indices of the authorising old quorum, from the ceremony plan. */
+    quorumIndices: number[];
+    /** New share preimages `I'` (32-byte big-endian hex scalars), new-holder order. */
+    newPreimages: string[];
+    /** The new signing threshold `t'`. */
+    newThreshold: number;
+    /**
+     * Each NEW holder's X25519 PUBLIC key (32-byte hex), in new-holder order. The dealer seals
+     * sub-share `k` to `recipientPubkeys[k]`, so only ciphertext leaves the device.
+     */
+    recipientPubkeys: string[];
+}
+/**
+ * Result of the device reshare **deal** — what the ceremony expects back: the PUBLIC commitments
+ * to broadcast and one SEALED sub-share per new holder. No plaintext sub-share is ever produced
+ * outside the core.
+ */
+interface DeviceReshareDealResult {
+    /** The dealer's public Feldman commitments (opaque JSON) — broadcast to every new holder. */
+    commitments: unknown;
+    /** One sealed sub-share (hex ciphertext) per NEW holder, in new-holder order. */
+    sealedSubShares: string[];
 }
 /**
  * Result of the device reshare **assemble** — the bare NEW-epoch core. It cannot sign yet
@@ -441,6 +483,12 @@ interface MpcCore {
      * it (the web wasm needs a `--features reshare` build).
      */
     runReshareAssemble?(params: DeviceReshareAssembleParams): Promise<DeviceReshareAssembleResult>;
+    /**
+     * Deal this holder's contribution to a reshare (#488) — the OLD-holder stage, pure and local.
+     * Optional: only a core built with the reshare capability implements it (the web wasm needs a
+     * `--features reshare` build).
+     */
+    runReshareDeal?(params: DeviceReshareDealParams): Promise<DeviceReshareDealResult>;
     /**
      * Complete a reshared bare core into a signable share by running the aux-info ceremony over the
      * NEW committee (#318 / #95). Relay-driven, mirroring keygen's aux phase. Optional: only a core
@@ -489,6 +537,11 @@ interface ClientWasmModule {
      * Synchronous in the core (no relay); the SDK awaits it uniformly.
      */
     reshareAssemble?(paramsJson: string): unknown | Promise<unknown>;
+    /**
+     * Device reshare **deal** — the old holder's local contribution; returns
+     * `{ commitments_json, sealed_sub_shares_hex }`. Present only in a `--features reshare` build.
+     */
+    reshareDeal?(paramsJson: string): unknown | Promise<unknown>;
     /**
      * Device **complete-reshare** — run the aux ceremony over the new committee and return the
      * signable share as `{ keyshare_json, shared_public_key_json }`. Present only in a
@@ -537,6 +590,7 @@ declare class WasmMpcCore implements MpcCore {
     runSign(params: DeviceSignParams): Promise<DeviceSignResult>;
     pregeneratePrimes(curve: MpcCurve): Promise<string>;
     runReshareAssemble(params: DeviceReshareAssembleParams): Promise<DeviceReshareAssembleResult>;
+    runReshareDeal(params: DeviceReshareDealParams): Promise<DeviceReshareDealResult>;
     runCompleteReshare(params: DeviceCompleteReshareParams): Promise<DeviceCompleteReshareResult>;
     runMemberKeygen(params: MemberKeygenParams): Promise<DeviceKeygenResult>;
     runMemberSign(params: MemberSignParams): Promise<DeviceSignResult>;
@@ -869,8 +923,16 @@ type CustodyType = 'embedded' | 'shared' | 'self_custody';
 interface WaaskeyOptions {
     /** Publishable API key issued from the Waaskey dashboard. */
     apiKey: string;
-    /** API base URL. Defaults to the Waaskey production API. */
-    baseUrl?: string;
+    /**
+     * API base URL — REQUIRED, with no default.
+     *
+     * There used to be one (`https://api.waaskey.com`), and it does not resolve: every consumer that
+     * omitted this got an NXDOMAIN on its first call and a `network` error with nothing pointing at the
+     * cause. A default that cannot work is worse than none, because it moves the failure from the
+     * constructor — where the fix is obvious — to every request. When a public hostname exists, the
+     * default can come back.
+     */
+    baseUrl: string;
     /** Custom fetch implementation (e.g. for non-browser runtimes). Defaults to global `fetch`. */
     fetch?: typeof fetch;
     /**
@@ -971,6 +1033,17 @@ interface WalletBackupParams {
     email: string;
     /** Extra factor enrolments beyond the standard three. */
     extraFactors?: FactorEnrollment[];
+    /**
+     * A passkey PRF secret to ALSO wrap the backup key with (#510) — pass what
+     * `PasskeyPrfSecretProvider.enroll()` returned. The backup then opens with either the passkey or the
+     * recovery code, so a forgotten code is no longer a lost wallet. Omit to keep the recovery code as
+     * the only key.
+     */
+    passkey?: {
+        secret: string;
+        salt: string;
+        credentialId: string;
+    };
 }
 /** Options for `wallets.joinCeremony(...)` (#349). */
 interface JoinCeremonyOptions {
@@ -1144,6 +1217,10 @@ interface WalletData {
     custodyKinds: CustodyKind[];
     /** Count of {@link custodyKinds} entries the platform itself holds (`platform_signer` + `platform_recovery`). */
     platformShareCount: number;
+    /** The wallet's key epoch: 1 at creation, bumped by every reshare. The public key and address are unchanged across one. */
+    keyEpoch: number;
+    /** True while a reshared committee still needs its aux material regenerated — the wallet cannot sign until it clears. */
+    reshareAuxPending: boolean;
     /**
      * The wallet's custody attestation (#293): `embedded` when `platformShareCount >= threshold`
      * (platform alone is custodial-capable — the default 2-of-3), `self_custody` when
@@ -1534,8 +1611,15 @@ interface OnrampWidgetUrl {
     /** ISO timestamp when the signed URL expires, if applicable. */
     expiresAt?: string;
 }
-/** The recovery factors a wallet enrols (backend `RecoveryFactor`). */
-type RecoveryFactor = 'recovery_code' | 'totp' | 'email_otp';
+/**
+ * The recovery factors a wallet enrols (backend `RecoveryFactor`).
+ *
+ * `passkey` is enrolled INSTEAD of `recovery_code` when the product wants a recovery flow with nothing
+ * to remember (#510). Note the gate is an AND of every enrolled factor, not M-of-N — so enrolling a
+ * passkey makes that passkey required. Passkeys sync across a user's devices where a written code does
+ * not, which is what makes the trade reasonable, but it is a trade.
+ */
+type RecoveryFactor = 'recovery_code' | 'totp' | 'email_otp' | 'passkey';
 /**
  * Enrolment of one factor at register time (backend `FactorEnrollmentDto`).
  *
@@ -1550,7 +1634,11 @@ type RecoveryFactor = 'recovery_code' | 'totp' | 'email_otp';
  */
 interface FactorEnrollment {
     type: RecoveryFactor;
-    /** recovery_code → lowercase-hex SHA-256 of the code; totp → base32 secret; email_otp → email address. */
+    /**
+     * recovery_code → lowercase-hex SHA-256 of the code; totp → base32 secret; email_otp → email address;
+     * passkey → the base64url credential id of an ALREADY-registered passkey (public, not a secret) —
+     * build it with `passkeyFactorEnrollment`.
+     */
     credential: string;
 }
 /**
@@ -1566,7 +1654,11 @@ interface FactorEnrollment {
  */
 interface FactorVerification {
     type: RecoveryFactor;
-    /** recovery_code → the plaintext code (the SDK sends its SHA-256); totp → current 6-digit OTP; email_otp → the emailed OTP. */
+    /**
+     * recovery_code → the plaintext code (the SDK sends its SHA-256); totp → current 6-digit OTP;
+     * email_otp → the emailed OTP; passkey → a WebAuthn assertion as JSON, which no user can type —
+     * build it with `passkeyFactorVerification`.
+     */
     token: string;
 }
 /** A registered recovery record's metadata (backend `RecoveryShareResponse`). */
@@ -1575,22 +1667,51 @@ interface RecoveryShareInfo {
     walletId: string;
     factors: RecoveryFactor[];
     createdAt: string;
+    /** Which key-wrapping methods are enrolled — a single entry means a single point of failure. */
+    wrapMethods?: ('passkey_prf' | 'passphrase')[];
 }
 /** Response to initiating a recovery session (backend `RecoveryChallengeResponse`). */
 interface RecoveryChallengeResponse {
     challengeId: string;
     requiredFactors: RecoveryFactor[];
+    /**
+     * The WebAuthn challenge to sign, present only when a `passkey` factor is enrolled (#510). Server-random
+     * and single-use with this session — feed it to `passkeyFactorVerification`.
+     */
+    passkeyChallenge?: string;
+}
+/**
+ * How the key that opens a backup was wrapped (backend `RecoveryKeyWrap`, #510).
+ *
+ * The share is sealed under a data key; that key is wrapped once per method, and every wrapping opens
+ * the SAME share — so losing one path is survivable. Everything here is safe for the server to hold:
+ * a wrapped key is noise without its key-encryption key, and those live only inside the user's
+ * authenticator or in the user's head.
+ */
+interface RecoveryKeyWrap {
+    /** `passkey_prf` — key from a WebAuthn PRF output; `passphrase` — key from the recovery code. */
+    method: 'passkey_prf' | 'passphrase';
+    /** The data key, wrapped under this method's key-encryption key. */
+    wrapped: string;
+    /** Salt to reproduce that key-encryption key (the PRF evaluation salt, or the KDF salt). */
+    salt: string;
+    /** For `passkey_prf`: which credential to assert. */
+    credentialId?: string;
 }
 /** Encrypted share returned after verifying factors (backend `RecoveryRetrieveResponse`). */
 interface RecoveryRetrieveResponse {
     id: string;
     ciphertext: string;
+    /** Wrapped copies of the key that opens `ciphertext`. Empty for a backup registered before #510. */
+    keyWraps?: RecoveryKeyWrap[];
 }
 /** Result of device-loss recovery — factors verified + shares rotated (backend `RecoverWalletResponse`). */
 interface RecoverWalletResponse {
     recovered: boolean;
     id: string;
     ciphertext: string;
+    /** Wrapped copies of the key that opens `ciphertext`. Empty for a backup registered before #510. */
+    keyWraps?: RecoveryKeyWrap[];
     refreshedAt: string;
 }
 /** Parameters for `recovery.register(...)`. */
@@ -1605,6 +1726,17 @@ interface RegisterRecoveryParams {
     email: string;
     /** Extra factor enrolments beyond the standard three. */
     extraFactors?: FactorEnrollment[];
+    /**
+     * A passkey PRF secret to ALSO wrap the backup key with (#510) — pass what
+     * `PasskeyPrfSecretProvider.enroll()` returned. The backup then opens with either the passkey or the
+     * recovery code, so a forgotten code is no longer a lost wallet. Omit to keep the recovery code as
+     * the only key.
+     */
+    passkey?: {
+        secret: string;
+        salt: string;
+        credentialId: string;
+    };
 }
 /** Parameters for `recovery.recover(...)` / `recovery.retrieveShare(...)`. */
 interface RecoverParams {
@@ -1612,8 +1744,18 @@ interface RecoverParams {
     challengeId: string;
     /** One verification per enrolled factor. */
     verifications: FactorVerification[];
-    /** The recovery code — decrypts the retrieved share client-side. */
-    recoveryCode: string;
+    /**
+     * The recovery code — opens the retrieved share client-side. Optional only when `passkeySecret` is
+     * supplied AND the backup was registered with a passkey wrap (#510); one of the two is required, and
+     * a backup registered before #510 accepts nothing but the code.
+     */
+    recoveryCode?: string;
+    /**
+     * A passkey PRF output (base64) to open the backup with instead of the code (#510) — pass the
+     * `secret` from `PasskeyPrfSecretProvider.unlock(credentialId, { salt })`, using the `salt` and
+     * `credentialId` the backup's `keyWraps` carry. Never sent to the server.
+     */
+    passkeySecret?: string;
 }
 /**
  * Parameters for `wallets.recoverSign(...)` — the device-loss RECOVERY CO-SIGN of a non-custodial
@@ -1675,6 +1817,96 @@ interface ReshareCompletionCeremony {
     /** Short-lived relay token (JWT) the device presents to join the reshare-aux session; present only when relay auth is enabled. */
     relayToken?: string;
 }
+/**
+ * A client-dealt reshare ceremony the backend opened (`POST /v1/wallets/:id/reshare-embedded`) — the
+ * client's whole instruction set for its half: who deals, the committee being rotated onto, where each
+ * sub-share must be sealed, and the coordination preimages both stages must agree on.
+ */
+interface ReshareCeremony {
+    id: string;
+    walletId: string;
+    status: string;
+    curve: WalletCurve;
+    /** OLD party indices of the authorising quorum — passed to the deal unchanged. */
+    quorumIndices: number[];
+    /** The OLD authorising quorum (this client's party plus the platform's). */
+    dealers: {
+        role: string;
+        index: number;
+    }[];
+    /** The NEW ordered party roles, length `n'`. */
+    newParties: string[];
+    /** The NEW signing threshold `t'`. */
+    newThreshold: number;
+    /**
+     * The NEW per-party custody kinds, parallel to {@link newParties}. This is what tells the client
+     * which holders are ITS to assemble and acknowledge — the role names cannot, since the platform's
+     * party is `server` on an embedded committee and `platform` on a member one.
+     */
+    newCustodyKinds: CustodyKind[];
+    /** Each NEW holder's X25519 recipient pubkey (32-byte hex), parallel to {@link newParties}. */
+    recipientPubkeys: string[];
+    /** Fresh 32-byte-hex coordination preimages, one per NEW holder. */
+    newPreimages: string[];
+    /** The NEW key epoch the reshared shares are inserted under. */
+    keyEpoch: number;
+    expiresAt: string;
+}
+/** One client holder's assemble material (`GET …/reshare-drop/:ceremonyId/assembly?role=…`). */
+interface ReshareAssemblyMaterial {
+    ceremonyId: string;
+    walletId: string;
+    status: string;
+    curve: WalletCurve;
+    /** This holder's 0-based position in the new committee. */
+    newPosition: number;
+    newThreshold: number;
+    newPreimages: string[];
+    /** The unchanged `WalletPublicInfo` JSON. */
+    wallet: unknown;
+    /** The wallet's public key — every assembled share must reproduce it. */
+    expectedPublicKey: string;
+    /** One Feldman-commitments object per dealer, in dealer order. */
+    commitments: unknown[];
+    /** This holder's SEALED sub-share from each dealer, parallel to {@link commitments}. */
+    subShares: string[];
+}
+/** Parameters for `reshare.rotate(...)` — the committee to move the wallet onto. */
+interface ReshareRotateParams {
+    /** The new ordered party roles. Omit to re-issue the current committee at a new epoch. */
+    parties?: string[];
+    /** The new signing threshold `t'`. Omit to keep the current one. */
+    threshold?: number;
+    /** The new per-party custody kinds, parallel to {@link parties}. Omit to derive from role names. */
+    custodyKinds?: CustodyKind[];
+    /**
+     * Accept a committee with no user-held backup on a wallet that has one. Refused by default —
+     * the address would not change, so nothing would show that the wallet had stopped being recoverable.
+     */
+    acknowledgeBackupLoss?: boolean;
+    /**
+     * The user's EXISTING recovery code. Required when the new committee keeps a `user_backup` holder:
+     * that holder's new share is re-sealed under it so the wallet's backup survives the rotation. The
+     * code never leaves the device — only the sealed ciphertext is sent.
+     */
+    recoveryCode?: string;
+}
+/** Result of `reshare.rotate(...)` — the ceremony the client drove, and what it produced locally. */
+interface ReshareRotateResult {
+    walletId: string;
+    ceremonyId: string;
+    /** The ceremony's terminal status — `complete` once the last acknowledgement drove the cutover. */
+    status: string;
+    /** The wallet's NEW key epoch. */
+    keyEpoch: number;
+    /** The client-held holders this device assembled, in new-committee order. */
+    assembledRoles: string[];
+    /**
+     * The wallet's public key, verified UNCHANGED by every assembled share — the funds-safety invariant
+     * of a reshare.
+     */
+    sharedPublicKey: string;
+}
 /** Parameters for `reshare.complete(...)` — everything the device needs to finish its NEW-epoch share. */
 interface ReshareCompletionParams {
     /** Assemble material from the reshare response ({@link ReshareWalletResponse.deviceMaterial}). */
@@ -2016,6 +2248,36 @@ declare class Reshare {
     private readonly http;
     private readonly deps;
     constructor(http: HttpClient, deps?: ReshareDeps);
+    /**
+     * 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.
+     */
+    rotate(walletId: string, params?: ReshareRotateParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<ReshareRotateResult>;
+    /**
+     * 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.
+     */
+    private sealBackup;
     /**
      * Complete this device's share for a device-retaining reshare and make the wallet signable on the
      * device under the new epoch.
@@ -2432,11 +2694,13 @@ declare class Wallets {
      */
     recoverSign(walletId: string, params: RecoverSignParams, options?: SignOptions): Promise<string>;
     /**
-     * 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).
      */
-    private fetchUserBackupCiphertext;
+    private fetchUserBackup;
     /**
      * Run one or more device keygen parties (each `mpc.runKeygen`), concurrently, mapping any failure to a
      * single `keygen_failed`. Used for both the single `device` party and the two-party non-custodial
@@ -2487,6 +2751,7 @@ declare function userBackupPendingKey(walletId: string): string;
  *
  * const waaskey = new Waaskey({
  *   apiKey: process.env.WAASKEY_PUBLISHABLE_KEY!,
+ *   baseUrl: process.env.WAASKEY_API_URL!,
  *   mpc: new WasmMpcCore(loadClientWasm),
  *   shareStore: EncryptedShareStore.browser(sessionSecret),
  * });
@@ -2499,7 +2764,7 @@ declare class Waaskey {
     readonly wallets: Wallets;
     /** The `recovery` resource — multi-factor, client-encrypted wallet recovery. */
     readonly 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). */
     readonly reshare: Reshare;
     /** The `balances` resource — client-side balance reads from a chain provider (no backend). */
     readonly balances: Balances;
@@ -2549,6 +2814,175 @@ declare function isNonCustodial(wallet: Pick<WalletData, 'platformShareCount' |
  */
 declare function validateCustodyPolicy(params: Pick<CreateWalletParams, 'threshold' | 'parties' | 'custodyKinds' | 'custodyType'>): void;
 
+/** A backup blob plus the wrapped copies of the key that opens it. */
+interface RecoveryBackupEnvelope {
+    /** The share, sealed under a random data key. Opaque to the server. */
+    ciphertext: string;
+    /** One wrapped copy of that data key per enrolled method. */
+    keyWraps: RecoveryKeyWrap[];
+}
+/** A passkey PRF secret to wrap the backup key with — the exact shape `PasskeyPrfSecretProvider` returns. */
+interface PasskeyBackupKey {
+    /** Base64 PRF output (32 bytes). Never persisted, never sent to the server. */
+    secret: string;
+    /** Base64 PRF evaluation salt — non-secret, stored with the wrap so it can be reproduced. */
+    salt: string;
+    /** The credential whose PRF derives this key, so recovery asserts the right passkey. */
+    credentialId: string;
+}
+/**
+ * Seal a share into an envelope: a random data key encrypts the share, and that data key is wrapped
+ * once per method (#510 / waas-backend#510).
+ *
+ * The point of the indirection is that EVERY wrapping opens the SAME share. A user whose passkey is
+ * gone still has the recovery code; a user who never wrote the code down still has the passkey. Sealing
+ * the share directly under one secret — which is what this SDK did before — makes losing that one
+ * secret the same as losing the wallet.
+ *
+ * The recovery-code wrap is always produced: it is the path that works on any device, in any browser,
+ * with no authenticator support. The passkey wrap is added when the caller supplies a PRF secret.
+ *
+ * Nothing here is decryptable server-side. The server receives the ciphertext, the wrapped keys, their
+ * salts and a credential id — none of which yields a key-encryption key. That is what keeps the
+ * platform below the signing threshold; a change that lets the server derive one would quietly make a
+ * non-custodial wallet custodial.
+ */
+declare function sealRecoveryBackup(share: string, recoveryCode: string, passkey?: PasskeyBackupKey): Promise<RecoveryBackupEnvelope>;
+/**
+ * Open an envelope with whichever key the user still has.
+ *
+ * A passkey secret is preferred when one is supplied and the enrollment carries a matching wrap —
+ * that is the path with nothing to remember. Otherwise the recovery code opens it.
+ *
+ * A blob registered before envelopes existed arrives with NO wraps; that case is handled by the
+ * caller ({@link Recovery}), which falls back to opening the ciphertext with the recovery code
+ * directly. Deciding by `keyWraps.length` rather than by sniffing the blob's shape keeps the two
+ * formats from ever being confused for one another.
+ */
+declare function openRecoveryBackup(envelope: RecoveryBackupEnvelope, opener: {
+    recoveryCode?: string;
+    passkeySecret?: string;
+}): Promise<string>;
+
+/**
+ * Passkey step-up signing assertion (Pattern B).
+ *
+ * The backend accepts an optional `passkeyAssertion` (`AuthenticationResponseJSON`)
+ * on sign/send/recover DTOs and verifies it server-side.  This module runs the
+ * WebAuthn assertion over a **server-issued one-time challenge** and returns the
+ * typed `AuthenticationResponseJSON` ready to be included in the POST body.
+ *
+ * ### Challenge (issue #39 — replay-safe)
+ * The challenge is a random nonce the **server** mints (via a step-up challenge
+ * endpoint), NOT a value derived from the request payload. `Wallet.sign`/`send`
+ * fetch it, run the assertion over it, and echo its `challengeId` on the request;
+ * the server verifies the assertion against the stored challenge and **burns** it,
+ * so a captured assertion cannot be replayed for a later identical payload.
+ *
+ * ### Wiring in Wallet
+ * ```ts
+ * // In wallet.sign() (handled by Wallet.resolveStepUp):
+ * const { challengeId, challenge } = await http.request('POST', '/v1/wallets/${id}/stepup/challenge', { operation: 'sign' });
+ * const assertion = await getSigningAssertion(challenge, { credentialId });
+ * await http.request('POST', '/v1/wallets/${id}/sign', { message, passkeyAssertion: assertion, passkeyChallengeId: challengeId });
+ *
+ * // Caller opts in:
+ * await wallet.sign(digest, { requirePasskey: true });
+ * ```
+ */
+
+/**
+ * Returns `true` if the current runtime has WebAuthn available — i.e. the SDK
+ * can attempt a passkey assertion.  Use this as a fast pre-flight before calling
+ * `getSigningAssertion()` when you want to show/hide a "sign with passkey" button.
+ */
+declare function isPasskeyAssertionSupported(): boolean;
+/**
+ * Override the WebAuthn `credentials.get` call.  Useful for React Native (native
+ * passkey module) or unit tests (mock the assertion response).
+ */
+interface SigningAssertionCeremony {
+    get(options: PublicKeyCredentialRequestOptionsJSON): Promise<AuthenticationResponseJSON>;
+}
+/** Options for `getSigningAssertion()`. */
+interface SigningAssertionOptions {
+    /**
+     * Restrict the assertion to a specific credential.  Pass the `credentialId`
+     * that was enrolled (e.g. from `PasskeyPrfSecretProvider.enroll()`).  When
+     * omitted the browser presents all resident credentials for the RP.
+     */
+    credentialId?: string;
+    /**
+     * Fully qualified domain name of the relying party.  Defaults to the current
+     * origin's hostname in the browser.
+     */
+    rpId?: string;
+    /**
+     * Custom ceremony implementation (for React Native or tests).
+     */
+    ceremony?: SigningAssertionCeremony;
+}
+/**
+ * Run a WebAuthn assertion over a **server-issued one-time `challenge`** and return
+ * the typed `AuthenticationResponseJSON` to attach as `passkeyAssertion` in the
+ * request body.
+ *
+ * @param challenge — the base64url one-time challenge nonce from the server's
+ *   step-up challenge endpoint ({@link StepUpChallengeResponse.challenge}). It is
+ *   passed to the authenticator verbatim; the server verifies the assertion against
+ *   the stored challenge and burns it, so the assertion cannot be replayed.
+ * @param options — optional ceremony override and credential hint.
+ *
+ * @throws `WaaskeyError('unsupported')` when WebAuthn is not available in this runtime.
+ * @throws `WaaskeyError('aborted')` when the user cancels the authenticator prompt.
+ */
+declare function getSigningAssertion(challenge: string, options?: SigningAssertionOptions): Promise<AuthenticationResponseJSON>;
+
+/**
+ * The `passkey` recovery factor (waas-backend#510) — proving possession of a registered passkey
+ * instead of typing a recovery code.
+ *
+ * This is what lets an app offer `{passkey, totp, email_otp}`: three factors, none of them a secret
+ * the user has to remember. The PRF wrap protects the backup blob at rest, but the blob is only
+ * released once every enrolled factor verifies, so as long as the only strong factor was a memorized
+ * code, the code stayed mandatory.
+ *
+ * The factor's token is a WebAuthn assertion, not a value a person can type — which is why an app
+ * needs this helper rather than an input field.
+ */
+/**
+ * Enrol a registered passkey as a recovery factor.
+ *
+ * The `credential` is the credential id, which is public and useless on its own — the private key
+ * never leaves the authenticator. The credential must ALREADY be registered with the platform: the
+ * server refuses an unknown id, because a factor that can never be satisfied is a lock-out the user
+ * would discover only while recovering from a device they no longer have.
+ */
+declare function passkeyFactorEnrollment(credentialId: string): FactorEnrollment;
+/**
+ * Produce the `passkey` factor's proof for a recovery challenge.
+ *
+ * Pass the `passkeyChallenge` the challenge endpoint issued for THIS session: the server checks the
+ * assertion against those exact bytes and consumes them, so an assertion captured from an earlier
+ * attempt is worthless. The assertion travels as JSON in the factor's `token`, which is the only value
+ * property the API's factor DTO accepts.
+ *
+ * ```ts
+ * const { challengeId, requiredFactors, passkeyChallenge } = await waaskey.recovery.challenge(walletId);
+ * const verifications = [
+ *   await passkeyFactorVerification(passkeyChallenge!),
+ *   { type: 'totp', token: code },
+ *   { type: 'email_otp', token: otp },
+ * ];
+ * await waaskey.recovery.recover(walletId, { challengeId, verifications, passkeySecret });
+ * ```
+ *
+ * @throws `WaaskeyError('unsupported')` when WebAuthn is unavailable in this runtime (pass a
+ *   `ceremony` for React Native or tests).
+ * @throws `WaaskeyError('aborted')` when the user cancels the authenticator prompt.
+ */
+declare function passkeyFactorVerification(challenge: string, options?: SigningAssertionOptions): Promise<FactorVerification>;
+
 /**
  * **Optional** client-side broadcast helper.
  *
@@ -2697,78 +3131,4 @@ declare class PasskeyPrfSecretProvider {
     }): Promise<PasskeyPrfResult>;
 }
 
-/**
- * Passkey step-up signing assertion (Pattern B).
- *
- * The backend accepts an optional `passkeyAssertion` (`AuthenticationResponseJSON`)
- * on sign/send/recover DTOs and verifies it server-side.  This module runs the
- * WebAuthn assertion over a **server-issued one-time challenge** and returns the
- * typed `AuthenticationResponseJSON` ready to be included in the POST body.
- *
- * ### Challenge (issue #39 — replay-safe)
- * The challenge is a random nonce the **server** mints (via a step-up challenge
- * endpoint), NOT a value derived from the request payload. `Wallet.sign`/`send`
- * fetch it, run the assertion over it, and echo its `challengeId` on the request;
- * the server verifies the assertion against the stored challenge and **burns** it,
- * so a captured assertion cannot be replayed for a later identical payload.
- *
- * ### Wiring in Wallet
- * ```ts
- * // In wallet.sign() (handled by Wallet.resolveStepUp):
- * const { challengeId, challenge } = await http.request('POST', '/v1/wallets/${id}/stepup/challenge', { operation: 'sign' });
- * const assertion = await getSigningAssertion(challenge, { credentialId });
- * await http.request('POST', '/v1/wallets/${id}/sign', { message, passkeyAssertion: assertion, passkeyChallengeId: challengeId });
- *
- * // Caller opts in:
- * await wallet.sign(digest, { requirePasskey: true });
- * ```
- */
-
-/**
- * Returns `true` if the current runtime has WebAuthn available — i.e. the SDK
- * can attempt a passkey assertion.  Use this as a fast pre-flight before calling
- * `getSigningAssertion()` when you want to show/hide a "sign with passkey" button.
- */
-declare function isPasskeyAssertionSupported(): boolean;
-/**
- * Override the WebAuthn `credentials.get` call.  Useful for React Native (native
- * passkey module) or unit tests (mock the assertion response).
- */
-interface SigningAssertionCeremony {
-    get(options: PublicKeyCredentialRequestOptionsJSON): Promise<AuthenticationResponseJSON>;
-}
-/** Options for `getSigningAssertion()`. */
-interface SigningAssertionOptions {
-    /**
-     * Restrict the assertion to a specific credential.  Pass the `credentialId`
-     * that was enrolled (e.g. from `PasskeyPrfSecretProvider.enroll()`).  When
-     * omitted the browser presents all resident credentials for the RP.
-     */
-    credentialId?: string;
-    /**
-     * Fully qualified domain name of the relying party.  Defaults to the current
-     * origin's hostname in the browser.
-     */
-    rpId?: string;
-    /**
-     * Custom ceremony implementation (for React Native or tests).
-     */
-    ceremony?: SigningAssertionCeremony;
-}
-/**
- * Run a WebAuthn assertion over a **server-issued one-time `challenge`** and return
- * the typed `AuthenticationResponseJSON` to attach as `passkeyAssertion` in the
- * request body.
- *
- * @param challenge — the base64url one-time challenge nonce from the server's
- *   step-up challenge endpoint ({@link StepUpChallengeResponse.challenge}). It is
- *   passed to the authenticator verbatim; the server verifies the assertion against
- *   the stored challenge and burns it, so the assertion cannot be replayed.
- * @param options — optional ceremony override and credential hint.
- *
- * @throws `WaaskeyError('unsupported')` when WebAuthn is not available in this runtime.
- * @throws `WaaskeyError('aborted')` when the user cancels the authenticator prompt.
- */
-declare function getSigningAssertion(challenge: string, options?: SigningAssertionOptions): Promise<AuthenticationResponseJSON>;
-
-export { Analytics, type AnalyticsEvent, type AnalyticsEventType, type AnalyticsSink, Auth, type Balance, Balances, type BroadcastOptions, type BroadcastResult, CLIENT_WASM_VERSION, type CeremonyParams, type Chain, type ChainConfig, type ChainProvider, type ClientWasmLoader, type ClientWasmModule, type CreateMemberWalletParams, type CreateWalletOptions, type CreateWalletParams, type CreateWalletResponse, type CustodyKind, type CustodyType, type DeviceCompleteReshareParams, type DeviceCompleteReshareResult, type DeviceKeygenParams, type DeviceKeygenResult, type DeviceReshareAssembleParams, type DeviceReshareAssembleResult, type DeviceReshareMaterial, type DeviceSignParams, type DeviceSignResult, type EddsaAssembleRequest, type EddsaCeremonyParams, type EddsaKeygenParams, type EddsaKeygenResult, type EddsaSendSession, type EddsaSignParams, type EddsaSignResult, type EmailStartResult, type EmbeddedSession, EncryptedShareStore, type EndUser, EvmRpcProvider, type FactorEnrollment, type FactorVerification, type FirebaseAuthRequest, HttpAnalyticsSink, IndexedDbKeyValueStore, type JoinCeremonyOptions, type JoinSignCeremonyOptions, type KeyValueStore, type Member, type MemberCeremony, type MemberCeremonyJoinResponse, type MemberCeremonyParams, type MemberKeygenParams, type MemberRole, type MemberSession, type MemberSignCeremony, type MemberSignParams, Members, type MembershipScope, MemoryKeyValueStore, MemoryPrimeStore, type MpcCore, type MpcCurve, Onramp, type OnrampWidgetParams, type OnrampWidgetUrl, type Page, type PageQuery, type PasskeyAssertionJSON, type PasskeyCeremony, type PasskeyPrfEnrollOptions, type PasskeyPrfResult, PasskeyPrfSecretProvider, type PrfCeremony, PrimePool, type PrimePoolOptions, type PrimePoolStore, type RecoverParams, type RecoverSignParams, type RecoverWalletResponse, Recovery, type RecoveryChallengeResponse, type RecoveryFactor, type RecoveryRetrieveResponse, type RecoveryShareInfo, type RegisterRecoveryParams, Reshare, type ReshareCompletionCeremony, type ReshareCompletionParams, type ReshareCompletionResult, type ReshareWalletResponse, type SendOptions, type SendParams, type SendResult, type ShareStore, type SignMessageResponse, type SignOptions, type SignRequestsQuery, type SignSessionResponse, type Signature, type SignatureKind, type SigningAssertionCeremony, type SigningAssertionOptions, type SigningRequestResponse, type SigningRequestStatus, type StepUpChallengeResponse, type StepUpOperation, type TokenBalanceOptions, type TxStatus, type VerifiedWasmLoaderOptions, Waaskey, WaaskeyError, type WaaskeyErrorCode, type WaaskeyErrorOptions, type WaaskeyOptions, Wallet, type WalletActionType, type WalletBackupParams, type WalletCeremony, type WalletCurve, type WalletData, type WalletShareholder, type WalletStatus, Wallets, WasmMpcCore, broadcast, createVerifiedClientWasmLoader, epochShareKey, formatUnits, generateRecoveryCode, getSigningAssertion, isNonCustodial, isPasskeyAssertionSupported, isPasskeySupported, isPrfSupported, loadClientWasm, memberShareKey, userBackupPendingKey, validateCustodyPolicy, verifyWasmIntegrity };
+export { Analytics, type AnalyticsEvent, type AnalyticsEventType, type AnalyticsSink, Auth, type Balance, Balances, type BroadcastOptions, type BroadcastResult, CLIENT_WASM_VERSION, type CeremonyParams, type Chain, type ChainConfig, type ChainProvider, type ClientWasmLoader, type ClientWasmModule, type CreateMemberWalletParams, type CreateWalletOptions, type CreateWalletParams, type CreateWalletResponse, type CustodyKind, type CustodyType, type DeviceCompleteReshareParams, type DeviceCompleteReshareResult, type DeviceKeygenParams, type DeviceKeygenResult, type DeviceReshareAssembleParams, type DeviceReshareAssembleResult, type DeviceReshareMaterial, type DeviceSignParams, type DeviceSignResult, type EddsaAssembleRequest, type EddsaCeremonyParams, type EddsaKeygenParams, type EddsaKeygenResult, type EddsaSendSession, type EddsaSignParams, type EddsaSignResult, type EmailStartResult, type EmbeddedSession, EncryptedShareStore, type EndUser, EvmRpcProvider, type FactorEnrollment, type FactorVerification, type FirebaseAuthRequest, HttpAnalyticsSink, IndexedDbKeyValueStore, type JoinCeremonyOptions, type JoinSignCeremonyOptions, type KeyValueStore, type Member, type MemberCeremony, type MemberCeremonyJoinResponse, type MemberCeremonyParams, type MemberKeygenParams, type MemberRole, type MemberSession, type MemberSignCeremony, type MemberSignParams, Members, type MembershipScope, MemoryKeyValueStore, MemoryPrimeStore, type MpcCore, type MpcCurve, Onramp, type OnrampWidgetParams, type OnrampWidgetUrl, type Page, type PageQuery, type PasskeyAssertionJSON, type PasskeyBackupKey, type PasskeyCeremony, type PasskeyPrfEnrollOptions, type PasskeyPrfResult, PasskeyPrfSecretProvider, type PrfCeremony, PrimePool, type PrimePoolOptions, type PrimePoolStore, type RecoverParams, type RecoverSignParams, type RecoverWalletResponse, Recovery, type RecoveryBackupEnvelope, type RecoveryChallengeResponse, type RecoveryFactor, type RecoveryKeyWrap, type RecoveryRetrieveResponse, type RecoveryShareInfo, type RegisterRecoveryParams, Reshare, type ReshareAssemblyMaterial, type ReshareCeremony, type ReshareCompletionCeremony, type ReshareCompletionParams, type ReshareCompletionResult, type ReshareRotateParams, type ReshareRotateResult, type ReshareWalletResponse, type SendOptions, type SendParams, type SendResult, type ShareStore, type SignMessageResponse, type SignOptions, type SignRequestsQuery, type SignSessionResponse, type Signature, type SignatureKind, type SigningAssertionCeremony, type SigningAssertionOptions, type SigningRequestResponse, type SigningRequestStatus, type StepUpChallengeResponse, type StepUpOperation, type TokenBalanceOptions, type TxStatus, type VerifiedWasmLoaderOptions, Waaskey, WaaskeyError, type WaaskeyErrorCode, type WaaskeyErrorOptions, type WaaskeyOptions, Wallet, type WalletActionType, type WalletBackupParams, type WalletCeremony, type WalletCurve, type WalletData, type WalletShareholder, type WalletStatus, Wallets, WasmMpcCore, broadcast, createVerifiedClientWasmLoader, epochShareKey, formatUnits, generateRecoveryCode, getSigningAssertion, isNonCustodial, isPasskeyAssertionSupported, isPasskeySupported, isPrfSupported, loadClientWasm, memberShareKey, openRecoveryBackup, passkeyFactorEnrollment, passkeyFactorVerification, sealRecoveryBackup, userBackupPendingKey, validateCustodyPolicy, verifyWasmIntegrity };