@waaskey/sdk 0.4.2 → 0.6.0

package/dist/index.d.ts

@@ -699,9 +699,46 @@ declare class MemoryPrimeStore implements PrimePoolStore {
 interface PrimeGenerator {
     pregeneratePrimes(curve: MpcCurve): Promise<string>;
 }
+/**
+ * A claim on pooled primes (#83).
+ *
+ * A keygen that fails — a server timeout, a dropped relay — used to take its primes out of the
+ * pool and never give them back, so every retry paid another full safe-prime generation: 5–10
+ * minutes of CPU in single-threaded WASM, right after something had already gone wrong. A lease
+ * makes the ownership explicit: primes leave the pool for good only when a ceremony actually
+ * derived key material from them.
+ */
+interface PrimeLease {
+    /** The primes to hand the ceremony. */
+    readonly primes: string;
+    /**
+     * The ceremony derived key material from these — they are spent and must never be reused.
+     */
+    consume(): void;
+    /**
+     * The ceremony did not complete: put them back for the retry.
+     *
+     * Returning primes a failed ceremony may have already published an `N` for is a deliberate
+     * call, not an oversight. The private halves never left the device; a party that re-runs with
+     * the same Paillier key is in the same position as one that simply has not refreshed its aux
+     * info yet, which is the normal state between refreshes. The alternative — burning another
+     * full generation on every retry — is a cost users actually pay.
+     */
+    release(): Promise<void>;
+}
 interface PrimePoolOptions {
     /** How many spare primes to keep cached per curve. Default 2. */
     targetSize?: number;
+    /**
+     * How many primes to generate at once when refilling. Default 1.
+     *
+     * Nothing in one prime search depends on another, so a worker-backed core can fill the pool in
+     * parallel and turn `targetSize` full generations of wall-clock into roughly one (#109). The
+     * default stays 1 because on a core that generates INLINE there are no cores to spare: the
+     * searches share the calling thread, so raising this would not finish sooner and would only
+     * delay the first prime becoming usable. Raise it when the core is worker-backed.
+     */
+    concurrency?: number;
     /** Persistence for the pool. Defaults to an in-memory store. */
     store?: PrimePoolStore;
     /**
@@ -719,6 +756,7 @@ declare class PrimePool {
     private readonly store;
     private readonly targetSize;
     private readonly autoRefill;
+    private readonly concurrency;
     /** Per-curve in-flight refill, so concurrent calls don't over-generate. */
     private readonly refilling;
     constructor(core: PrimeGenerator, options?: PrimePoolOptions);
@@ -735,6 +773,14 @@ declare class PrimePool {
      * is worker-backed).
      */
     take(curve: MpcCurve): Promise<string>;
+    /**
+     * 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.
+     */
+    borrow(curve: MpcCurve): Promise<PrimeLease>;
 }
 
 /**
@@ -861,7 +907,7 @@ declare class IndexedDbKeyValueStore implements KeyValueStore {
  * (`{ statusCode, message, error }`) to a code; orchestration failures (device keygen,
  * missing share, cancellation) use the SDK-side codes.
  */
-type WaaskeyErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'validation' | 'conflict' | 'rate_limited' | 'server_error' | 'network' | 'unsupported_chain' | 'provider_error' | 'device_core_required' | 'keygen_failed' | 'sign_failed' | 'reshare_failed' | 'reshare_pubkey_mismatch' | 'share_not_found' | 'recovery_failed' | 'invalid_recovery_code' | 'backup_failed' | 'wallet_activation_timeout' | 'sign_ceremony_timeout' | 'unauthenticated' | 'firebase_not_enabled' | 'mfa_required' | 'no_member' | 'unsupported' | 'aborted' | 'unknown';
+type WaaskeyErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'validation' | 'conflict' | 'rate_limited' | 'server_error' | 'network' | 'unsupported_chain' | 'provider_error' | 'device_core_required' | 'device_store_required' | 'keygen_failed' | 'sign_failed' | 'reshare_failed' | 'reshare_pubkey_mismatch' | 'share_not_found' | 'recovery_failed' | 'invalid_recovery_code' | 'backup_failed' | 'wallet_activation_timeout' | 'sign_ceremony_timeout' | 'unauthenticated' | 'firebase_not_enabled' | 'mfa_required' | 'no_member' | 'unsupported' | 'permission_expired' | 'permission_revoked' | 'permission_scope' | 'permission_value_exceeded' | 'permission_exhausted' | 'permission_rate_limited' | 'permission_request_timeout' | 'permission_declined' | 'aborted' | 'unknown';
 interface WaaskeyErrorOptions {
     /** HTTP status, when the error originates from an API response. */
     status?: number;
@@ -935,6 +981,14 @@ interface WaaskeyOptions {
     baseUrl: string;
     /** Custom fetch implementation (e.g. for non-browser runtimes). Defaults to global `fetch`. */
     fetch?: typeof fetch;
+    /**
+     * Where a permission request sends the user to answer it — the wallet that holds their key (#113).
+     *
+     * Required only by `sessionKeys.request`, and deliberately not defaulted: which wallet is "the"
+     * wallet is a product decision (your own app, waaskey mobile, the extension), and guessing it
+     * would send users somewhere that cannot answer.
+     */
+    walletUrl?: string;
     /**
      * Device-party MPC core (e.g. `WasmMpcCore`). Required to create a wallet — the
      * device runs its half of the keygen ceremony with this.
@@ -945,6 +999,15 @@ interface WaaskeyOptions {
      * `EncryptedShareStore.browser(secret)`). Required to create a wallet.
      */
     shareStore?: ShareStore;
+    /**
+     * Where this client's stable **device id** is persisted (e.g. `new IndexedDbKeyValueStore()`).
+     * Required to act as a member DEVICE — registering, and joining a member-bound wallet's
+     * ceremonies as `member:<membershipId>:<deviceId>`.
+     *
+     * Deliberately NOT the sealed share store: the device id is public (it is in every party role),
+     * and sealing it would make it unavailable before unlock — exactly when registration needs it.
+     */
+    deviceStore?: KeyValueStore;
     /**
      * Optional pool of pre-generated Paillier primes (`new PrimePool(mpc)`). When set,
      * `wallets.prewarm(chain)` fills it off the hot path and `wallets.create` claims from
@@ -1003,6 +1066,15 @@ interface CreateWalletOptions {
     activationTimeoutMs?: number;
     /** Poll interval while waiting for activation, ms. Default 1000. */
     pollIntervalMs?: number;
+    /**
+     * What the backup ended up enrolled with (#105) — called once, before `create` resolves.
+     *
+     * The app needs this to say the right thing: a passkey-guarded wallet must NOT be shown a
+     * "write this code down" screen for a code nobody will ever ask for, and a code-guarded one must.
+     * Guessing from device capability is not enough, because enrolment can fall back for reasons the
+     * app cannot see.
+     */
+    onRecoveryEnrolled?: (enrolment: RecoveryEnrolment) => void;
     /**
      * Recovery-backup material for a **non-custodial** `[device, server, user_backup]` create (#351/#78):
      * REQUIRED when the returned ceremony carries a `user_backup` party ({@link WalletCeremony.additionalParties}).
@@ -1024,6 +1096,28 @@ interface CreateWalletOptions {
  * secret and never leaves the device (only its SHA-256 is enrolled), so a lost code is an
  * unrecoverable backup.
  */
+/**
+ * Produces a passkey PRF credential for recovery enrolment, or `undefined` when this device cannot
+ * (no platform authenticator, no PRF extension, the user declined).
+ *
+ * A function rather than a class so a React Native or a test caller can supply one without the
+ * browser WebAuthn surface; `PasskeyPrfSecretProvider.enroll` fits it directly.
+ */
+type PasskeyEnroller = () => Promise<{
+    secret: string;
+    salt: string;
+    credentialId: string;
+} | undefined>;
+/** Which factor ended up guarding the backup, and why (#105). */
+interface RecoveryEnrolment {
+    /**
+     * The strong factor that was enrolled. `recovery_code` means the user MUST be shown their code;
+     * `passkey` means they must not be told to write down a code they will never be asked for.
+     */
+    strongFactor: 'passkey' | 'recovery_code';
+    /** Why the passkey was not used. Absent when it was. */
+    fallbackReason?: 'no_passkey_enroller' | 'device_cannot_prf' | 'enrolment_failed';
+}
 interface WalletBackupParams {
     /** High-entropy recovery code that seals the user_backup share. Show it to the user once — it is the only key to the backup and never leaves the client. */
     recoveryCode: string;
@@ -1033,6 +1127,17 @@ interface WalletBackupParams {
     email: string;
     /** Extra factor enrolments beyond the standard three. */
     extraFactors?: FactorEnrollment[];
+    /**
+     * Enrol a passkey INSTEAD of the recovery code when this device can produce a PRF — the #511
+     * default (waas-backend#511), made automatic here rather than left as an opt-in (#105).
+     *
+     * Called once during `create`. Return the credential to enrol it as the strong factor; return
+     * `undefined` (or throw) and the recovery code is used instead. A device without PRF is a
+     * permanent property of that device, not a user error, so the fallback is silent — but which of
+     * the two was enrolled is reported through `onRecoveryEnrolled`, because it decides whether the
+     * app must tell the user to write a code down.
+     */
+    passkeyEnroller?: PasskeyEnroller;
     /**
      * 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
@@ -1066,6 +1171,42 @@ interface WalletBackupParams {
 interface JoinCeremonyOptions {
     /** Cancel the join (roster ack + the relay keygen ceremony). */
     signal?: AbortSignal;
+    /**
+     * Which of the member's devices is joining (#54). Required when the member holds several — the
+     * backend cannot guess which one, and the share is sealed under this device's own key.
+     * Defaults to the client's stored device id when a `deviceStore` is configured.
+     */
+    deviceId?: string;
+}
+/**
+ * One of a member's registered devices (#53). Mirrors the backend `IMemberDevice`.
+ */
+interface Device {
+    /** Registry id — what {@link Devices.revoke} takes (NOT the client-generated `deviceId`). */
+    id: string;
+    /** The owning member seat. */
+    membershipId: string;
+    /** The client-generated stable id this device is known by in party roles. */
+    deviceId: string;
+    /** Human-friendly label, e.g. "Chrome on MacBook Pro". */
+    label: string;
+    createdAt: string;
+    /** Last re-registration; null until the device re-registers after creation. */
+    lastSeenAt: string | null;
+    /** The device's X25519 encryption public key (32-byte hex), when it registered one. */
+    encryptionPublicKey?: string | null;
+}
+/** What {@link Devices.register} sends. */
+interface DeviceRegistration {
+    /** Human-friendly label shown in device pickers and the dashboard. */
+    label: string;
+    /** Override the stored id — for a caller with no `deviceStore` of its own. */
+    deviceId?: string;
+    /**
+     * This device's X25519 encryption public key (32-byte non-zero hex). Dealers seal reshare
+     * sub-shares and FROST round-2 packages to it, so a device that will hold a share needs one.
+     */
+    encryptionPublicKey?: string;
 }
 /** Options for `wallets.joinSignCeremony(...)` (#349). */
 interface JoinSignCeremonyOptions {
@@ -1075,6 +1216,11 @@ interface JoinSignCeremonyOptions {
     readyTimeoutMs?: number;
     /** Poll interval while waiting for the quorum, ms. Default 1000. */
     pollIntervalMs?: number;
+    /**
+     * Which of the member's devices is signing (#54) — it must be the device whose share this
+     * client holds. Defaults to the client's stored device id when a `deviceStore` is configured.
+     */
+    deviceId?: string;
 }
 /**
  * A WebAuthn assertion attached for passkey step-up (issue #21/#39) — the structural
@@ -1760,6 +1906,17 @@ interface RegisterRecoveryParams {
     email: string;
     /** Extra factor enrolments beyond the standard three. */
     extraFactors?: FactorEnrollment[];
+    /**
+     * Enrol a passkey INSTEAD of the recovery code when this device can produce a PRF — the #511
+     * default (waas-backend#511), made automatic here rather than left as an opt-in (#105).
+     *
+     * Called once during `create`. Return the credential to enrol it as the strong factor; return
+     * `undefined` (or throw) and the recovery code is used instead. A device without PRF is a
+     * permanent property of that device, not a user error, so the fallback is silent — but which of
+     * the two was enrolled is reported through `onRecoveryEnrolled`, because it decides whether the
+     * app must tell the user to write a code down.
+     */
+    passkeyEnroller?: PasskeyEnroller;
     /**
      * 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
@@ -2051,6 +2208,18 @@ interface Member {
     totpEnabled: boolean;
     createdAt: string;
 }
+/**
+ * A team member as the members roster returns them (#57) — the login identity plus the
+ * per-membership capability a creator picks share-holders by.
+ */
+interface TeamMember extends Member {
+    /**
+     * Whether this membership may hold a wallet key share (#342). Defaults from the role
+     * (owner/admin true, member false) and is togglable by a manager — so it is NOT derivable from
+     * `role`, and guessing it in a picker offers users a choice the backend will refuse.
+     */
+    canHoldShare: boolean;
+}
 /**
  * A held org-member bearer session (mirrors the backend `FirebaseAuthResponse`). Returned by
  * {@link Members.loginWithFirebase} and held by the client so member-scoped calls authenticate with
@@ -2069,6 +2238,169 @@ interface MemberSession {
     member: Member;
 }
 
+/** A granted session key, as the API lists it (#112). */
+interface SessionKey {
+    id: string;
+    walletId: string;
+    /** Compressed secp256k1 public key of the key; the private half never leaves the grantee. */
+    publicKey: string;
+    permissions: {
+        allowedContracts?: string[];
+        allowedSelectors?: string[];
+        /** Per-call value cap (hex wei). */
+        maxValueWei?: string;
+        /** Lifetime call budget — how much the grant is worth in total. */
+        maxCalls?: number;
+        allowedChains?: string[];
+        /** Length of the rate window in seconds; set whenever a per-period cap is (#538). */
+        periodSeconds?: number;
+        /** Calls allowed within one period — a rate, on top of the lifetime `maxCalls`. */
+        maxCallsPerPeriod?: number;
+        /** Total value allowed within one period (hex wei). */
+        maxValueWeiPerPeriod?: string;
+    };
+    expiresAt: string;
+    /**
+     * What this permission is for, in the granter's words (#534).
+     *
+     * Metadata only — it takes no part in any authorization decision. Without it a client can list a
+     * permission by its public key alone, which tells a user nothing about which grant they are
+     * about to revoke.
+     */
+    label?: string | null;
+    /**
+     * The registered app that asked for this permission, when one did (#539).
+     *
+     * An id, not a name: resolve it through `waaskey.sessionKeys.requester(id)` and read its
+     * `status` — only a `verified` requester may be presented to a user as identity.
+     */
+    requesterId?: string | null;
+    /** The sponsorship policy funding this permission's gas (#539). */
+    paymasterPolicyId?: string | null;
+    /** Whether the wallet's owner has answered the request for this permission (#553). */
+    grantStatus?: PermissionGrantStatus;
+    /** When they approved it; null while pending or after a refusal. */
+    approvedAt?: string | null;
+    callsUsed: number;
+    /** Start of the rate window the usage below is counted in; null until the first call. */
+    periodStartedAt?: string | null;
+    /** Calls spent in the current period — stale once that period has lapsed. */
+    periodCallsUsed?: number;
+    /** Value spent in the current period, decimal wei — stale once that period has lapsed. */
+    periodValueWeiUsed?: string;
+    active: boolean;
+    createdAt: string;
+}
+/** What a session key needs to act: the permission, the account, and the call. */
+interface SessionKeySendParams {
+    /** Id of the granted session key (the API knows its public half). */
+    sessionKeyId: string;
+    /** The session key's PRIVATE key (hex). Never sent anywhere — it signs locally. */
+    privateKey: string;
+    /** Smart account the operation is for. */
+    sender: string;
+    /** waas chain id, e.g. `evm:1`. */
+    chainId: string;
+    /** ABI-encoded `execute` calldata of the call. */
+    callData: string;
+    /** Target contract — checked against the key's allowlist. */
+    contract: string;
+    /** 4-byte selector — checked against the key's allowlist. */
+    selector: string;
+    /** Call value in wei (hex) — checked against the key's cap. */
+    valueWei: string;
+    /** Account nonce; the server resolves the current one when omitted. */
+    nonce?: string;
+}
+/** What the bundler accepted. */
+interface SessionKeySendResult {
+    userOpHash: string;
+}
+/** The scope an app asks a user for (#113). Every bound is optional; omitting one asks for no limit. */
+interface PermissionScope {
+    /** Contracts the key may call; omitted = any. */
+    allowedContracts?: string[];
+    /** 4-byte selectors it may call; omitted = any. */
+    allowedSelectors?: string[];
+    /** Chains it may act on (waas ids, e.g. `evm:1`); omitted = any. */
+    allowedChains?: string[];
+    /** Per-call value cap (hex wei). */
+    maxValueWei?: string;
+    /** Lifetime call budget — how much the grant is worth in total. */
+    maxCalls?: number;
+    /** Length of the rate window in seconds; required with either per-period cap. */
+    periodSeconds?: number;
+    /** Calls allowed within one period — a rate, on top of `maxCalls`. */
+    maxCallsPerPeriod?: number;
+    /** Total value allowed within one period (hex wei). */
+    maxValueWeiPerPeriod?: string;
+}
+/** What an app asks for when it requests a permission (#113). */
+interface PermissionRequestParams {
+    /** The wallet being asked. */
+    walletId: string;
+    /** The scope wanted. The user may narrow it; they can never widen it. */
+    scope: PermissionScope;
+    /** When it should expire. */
+    expiresAt: Date | string;
+    /** What it is for, in words the user will read. */
+    label?: string;
+    /** The registered app doing the asking — the wallet shows its proven domain. */
+    requesterId?: string;
+    /** Sponsorship policy funding its gas, when the app pays. */
+    paymasterPolicyId?: string;
+}
+/**
+ * A permission that has been asked for and not yet answered.
+ *
+ * `privateKey` never leaves the caller: the SDK generated the pair locally and registered only the
+ * public half, so nothing secret is on the wire, in the link, or in the wallet.
+ */
+interface PermissionRequest {
+    /** Id of the pending grant — poll it, and use it to sign once approved. */
+    sessionKeyId: string;
+    /** The private half, held only here. Store it as you would any signing key. */
+    privateKey: string;
+    /** Its public half, which is what the API was told. */
+    publicKey: string;
+    /** Where to send the user to answer: open it, or render it as a QR code. */
+    url: string;
+    /** Whether an answer is still outstanding — `approved` already for a wallet with no owner to ask. */
+    status: PermissionGrantStatus;
+}
+/**
+ * An app that may ask a user for a permission (#539).
+ *
+ * `name` and `iconUrl` are what the app CLAIMS about itself and are never verified; `origin` is the
+ * only part that can carry trust, and only when `status` is `verified` — meaning that domain
+ * published a document naming the tenant. A consent screen that shows an unproven domain as proven
+ * is worse than one that shows nothing.
+ */
+interface AppRequester {
+    id: string;
+    /** The https origin that identifies the app. */
+    origin: string;
+    /** Claimed by the app; never verified. */
+    name: string;
+    /** Claimed by the app; never verified. */
+    iconUrl?: string | null;
+    status: 'pending' | 'verified' | 'failed';
+    /** When the domain last proved the claim; null until it has. */
+    verifiedAt?: string | null;
+    /** Why the last check failed — what the app's operator has to fix. */
+    lastFailure?: string | null;
+}
+/** Whether the wallet's owner has answered a permission request. */
+type PermissionGrantStatus = 'pending' | 'approved' | 'declined';
+/** The answer to a permission request, and what was actually granted (#113). */
+interface PermissionDecision {
+    status: PermissionGrantStatus;
+    /** The permission as it now stands — the scope the user accepted, which may be narrower than asked. */
+    key: SessionKey;
+    /** True when the user accepted less than was asked for, so an app can adapt instead of failing opaquely. */
+    narrowed: boolean;
+}
+
 /**
  * Embedded end-user authentication (#6) — Privy-style login that maps an end-user to a
  * non-custodial wallet, distinct from the dashboard member auth. The developer's API key
@@ -2150,6 +2482,86 @@ interface PasskeyCeremony {
     get(options: unknown): Promise<unknown>;
 }
 
+/**
+ * This browser (or Node process) as a **member device** (#53) — the client half of the
+ * per-membership device registry the multi-device wallet model is built on.
+ *
+ * A member-bound wallet gives each device its OWN share, and the parties are named
+ * `member:<membershipId>:<deviceId>`. That only works if a device can say which one it is,
+ * consistently, across reloads — so the id is minted once and persisted, never derived from
+ * anything the browser may change (a user agent, an install id, a session).
+ *
+ * The id is **not a secret and not a credential**: it appears verbatim in the protocol roles every
+ * other party sees, and holding it grants nothing. What proves the device is the share it holds and
+ * the member session it registered under. Which is why it is kept in a plain
+ * {@link KeyValueStore} rather than the sealed share store — sealing a public identifier would only
+ * make it unavailable before unlock, when registration needs it most.
+ *
+ * Every call here is MEMBER-scoped (`Authorization: Bearer <member access token>`, or the ambient
+ * dashboard cookie): a device belongs to a member seat, not to a tenant API key.
+ */
+declare class Devices {
+    private readonly http;
+    private readonly store?;
+    constructor(http: HttpClient, store?: KeyValueStore | undefined);
+    /**
+     * 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.
+     */
+    deviceId(): Promise<string>;
+    /**
+     * 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.
+     */
+    stored(): Promise<string | undefined>;
+    /**
+     * 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.
+     */
+    register(registration: DeviceRegistration, signal?: AbortSignal): Promise<Device>;
+    /** The caller's own registered devices — this one and their others. */
+    list(signal?: AbortSignal): Promise<Device[]>;
+    /**
+     * 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.
+     */
+    mine(signal?: AbortSignal): Promise<Array<Device & {
+        isThisDevice: boolean;
+    }>>;
+    /**
+     * 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.
+     */
+    revoke(id: string, signal?: AbortSignal): Promise<void>;
+    /** Forget this browser's device id, so the next {@link deviceId} mints a new one. */
+    forget(): Promise<void>;
+}
+
 /**
  * Org-member (dashboard "plane B") authentication — a bearer member login for a NON-browser
  * consumer (a Node app, or the browser extension via the SDK) that cannot carry the ambient
@@ -2193,6 +2605,31 @@ declare class Members {
     restore(session: MemberSession): void;
     /** Clear the held member session (sign out); member calls fall back to the cookie path afterwards. */
     memberSignOut(): void;
+    /**
+     * 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}).
+     */
+    list(options?: {
+        canHoldShare?: boolean;
+    }, signal?: AbortSignal): Promise<TeamMember[]>;
+    /**
+     * 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.
+     */
+    eligibility(signal?: AbortSignal): Promise<{
+        canHoldShare: boolean;
+        eligible: TeamMember[];
+    }>;
 }
 
 /**
@@ -2356,6 +2793,108 @@ declare class Reshare {
  */
 declare function epochShareKey(walletId: string, keyEpoch: number): string;
 
+/**
+ * The `sessionKeys` resource — exercise a delegated permission (#112).
+ *
+ * A session key is a scoped, time-limited signer the wallet granted: it may call certain contracts,
+ * certain selectors, up to a value, a bounded number of times. Creating and revoking one has been
+ * possible for a while; USING one had no client at all, which is what this closes.
+ *
+ * Two credentials are involved and they are not interchangeable — the surprise everyone hits once:
+ *
+ *  * the **API key** on the client, which must carry the `SIGN` scope: the session private key
+ *    alone does not reach the API;
+ *  * the **session private key**, which never leaves the caller and is what actually authorizes the
+ *    operation on-chain.
+ */
+declare class SessionKeys {
+    private readonly http;
+    private readonly walletUrl?;
+    constructor(http: HttpClient, walletUrl?: string | undefined);
+    /**
+     * 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);
+     * ```
+     */
+    request(params: PermissionRequestParams, signal?: AbortSignal): Promise<PermissionRequest>;
+    /** One permission as it now stands — including whether its owner has answered yet. */
+    get(sessionKeyId: string, signal?: AbortSignal): Promise<SessionKey>;
+    /**
+     * 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: string, signal?: AbortSignal): Promise<AppRequester>;
+    /**
+     * 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.
+     */
+    waitForDecision(sessionKeyId: string, options?: WaitForDecisionOptions): Promise<PermissionDecision>;
+    /** The tenant's active session keys, newest first (optionally for one wallet). */
+    list(walletId?: string, signal?: AbortSignal): Promise<SessionKey[]>;
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    send(params: SessionKeySendParams, signal?: AbortSignal): Promise<SessionKeySendResult>;
+}
+/**
+ * Sign a UserOperation hash the way a SimpleAccount verifies it: over the EIP-191 personal-sign
+ * form, not the raw hash. The account contract recovers from
+ * `userOpHash.toEthSignedMessageHash()`, so anything else is a signature the chain rejects — and
+ * the API now rejects it earlier, which is the same answer sooner.
+ */
+declare function signUserOpHash(userOpHash: string, privateKey: string): string;
+/** How long to wait for an answer, and how often to look. */
+interface WaitForDecisionOptions {
+    /** Give up after this long. Default 5 minutes. */
+    timeoutMs?: number;
+    /** How often to ask. Default every 2 seconds. */
+    pollMs?: number;
+    signal?: AbortSignal;
+    /** The scope that was asked for; supply it to learn whether the user narrowed it. */
+    asked?: PermissionScope;
+}
+
 /** Device-party dependencies a {@link Wallet} needs to co-sign an ed25519 (FROST) transaction locally. */
 interface WalletDeviceDeps {
     mpc?: MpcCore;
@@ -2524,6 +3063,8 @@ interface WalletsDeps {
     primePool?: PrimePool;
     /** Optional analytics emitter for wallet lifecycle events. */
     analytics?: Analytics;
+    /** This client's device identity (#53) — supplies the default `deviceId` for member ceremonies. */
+    devices?: Devices;
 }
 /**
  * The `wallets` resource: create and load wallets, plus the approver actions
@@ -2694,6 +3235,8 @@ declare class Wallets {
      * it unjoined would hang the whole ceremony, so failing loud beats silently deadlocking.
      */
     private runSecpKeygen;
+    /** The `[device, server, user_backup]` ceremony itself — see {@link runSecpKeygen} for why the primes are leased. */
+    private runNonCustodialKeygen;
     /**
      * Register a sealed user_backup {@link RecoveryRegisterPayload} server-side, with a small bounded retry
      * on TRANSIENT failures (network / 5xx / rate-limit) — a flaky moment must not cost the backup. A
@@ -2776,14 +3319,30 @@ declare class Wallets {
     /** Poll the wallet until keygen completes (ACTIVE), or throw on failure/timeout. */
     private waitUntilActive;
     /** Poll the member's own sign ceremony until the t-of-n quorum is fixed AND this member is selected, or throw on timeout. */
+    /**
+     * 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.
+     */
+    private resolveDeviceId;
     private waitUntilReady;
 }
 /**
  * Storage key for a member-bound wallet's per-member share (#349) — distinct from the embedded
  * flow's bare `walletId` key ({@link Wallet}'s single device share), since several members' shares
  * for the SAME wallet may live in one {@link ShareStore} (e.g. a shared device, or a test harness).
+ *
+ * With `deviceId` (#54) the key is per DEVICE as well: one member may hold DISTINCT shares of the
+ * same wallet across their own devices (browser, phone), and a device must only ever read its own.
+ *
+ * Without it the key keeps its original shape, and that is not a convenience — a share sealed under
+ * the old key by an earlier SDK version is still in the user's browser, and a key change that could
+ * not find it would look exactly like a lost wallet. Same reasoning as `epochShareKey` keeping
+ * epoch 1 on the bare wallet id.
  */
-declare function memberShareKey(walletId: string, membershipId: string): string;
+declare function memberShareKey(walletId: string, membershipId: string, deviceId?: string): string;
 /**
  * Storage key for a non-custodial wallet's PENDING user_backup backup (#351/#78) — the sealed
  * {@link RecoveryRegisterPayload} ciphertext {@link Wallets.create} persists before registering it
@@ -2823,8 +3382,12 @@ declare class Waaskey {
     readonly auth: Auth;
     /** The `members` resource — org-member (dashboard "plane B") bearer login for headless consumers. */
     readonly members: Members;
+    /** The `devices` resource — this client as a member DEVICE that can hold an MPC share (#53). */
+    readonly devices: Devices;
     /** The `onramp` resource — fund the wallet with fiat via a provider on-ramp. */
     readonly onramp: Onramp;
+    /** The `sessionKeys` resource — act with a delegated, scoped permission (#112). */
+    readonly sessionKeys: SessionKeys;
     /** Default fetch used by the optional {@link broadcast} helper (from `WaaskeyOptions.fetch`). */
     private readonly defaultFetch?;
     constructor(options: WaaskeyOptions);
@@ -3034,6 +3597,93 @@ declare function passkeyFactorEnrollment(credentialId: string): FactorEnrollment
  */
 declare function passkeyFactorVerification(challenge: string, options?: SigningAssertionOptions): Promise<FactorVerification>;
 
+/** How an envelope's secret is wrapped. Both may be present — either one opens it. */
+type UnlockMethod = 'passkey_prf' | 'passphrase';
+/** One wrapped copy of the secret. Every field here is NON-secret and safe to store beside the data. */
+interface UnlockKeyWrap {
+    method: UnlockMethod;
+    /** The secret, sealed under the key this method derives. */
+    wrapped: string;
+    /** Base64 salt: the PBKDF2 salt for a passphrase, the PRF evaluation salt for a passkey. */
+    salt: string;
+    /** Which passkey to authenticate with (`passkey_prf` only). */
+    credentialId?: string;
+}
+/** A secret that several methods can unlock. */
+interface SecretEnvelope {
+    wraps: UnlockKeyWrap[];
+}
+/** A passkey PRF secret — the exact shape `PasskeyPrfSecretProvider` returns. */
+interface PasskeyUnlockKey {
+    /** Base64 PRF output. Never persisted. */
+    secret: string;
+    /** Base64 PRF evaluation salt — non-secret, stored with the wrap so it can be replayed. */
+    salt: string;
+    credentialId: string;
+}
+/**
+ * A local **unlock envelope**: one secret, wrapped once per method the user enrolled (#52 B4).
+ *
+ * A browser member device seals its key share at rest under a secret, and that secret has to come
+ * from the user on every unlock — never from storage, or a stolen browser profile carries the key to
+ * its own ciphertext. Two things can supply it, and neither is good enough alone:
+ *
+ * - a **passkey** (WebAuthn PRF) — nothing to remember, but not every browser implements PRF, and a
+ *   lost device takes the only key with it;
+ * - a **passphrase** — works everywhere and moves between browsers, but is one more thing to know.
+ *
+ * So the secret is not derived from either. It is random, and each method wraps a copy of it. Any
+ * enrolled method opens the envelope, a method can be added later without re-sealing anything the
+ * secret protects, and losing one method is not losing the wallet — which is the whole reason the
+ * same shape already backs the recovery backup (`recovery-envelope.ts`).
+ *
+ * Nothing here is secret at rest: the wraps, salts and credential id yield nothing without the
+ * authenticator or the passphrase.
+ */
+declare function newUnlockSecret(): string;
+/**
+ * Wrap `secret` for the given methods. At least one is required — an envelope nothing can open is
+ * a wallet nobody can use.
+ *
+ * @throws {WaaskeyError} `validation` — no method supplied.
+ */
+declare function sealSecret(secret: string, methods: {
+    passphrase?: string;
+    passkey?: PasskeyUnlockKey;
+}): Promise<SecretEnvelope>;
+/**
+ * Add (or replace) one method on an existing envelope, so a user can enrol a passphrase on a
+ * device that already unlocks by passkey — or the reverse — without touching what the secret seals.
+ *
+ * Replacing rather than appending is deliberate: two wraps of the same method are two passphrases
+ * that both work, one of which the user does not know they set.
+ */
+declare function addMethod(envelope: SecretEnvelope, secret: string, method: {
+    passphrase?: string;
+    passkey?: PasskeyUnlockKey;
+}): Promise<SecretEnvelope>;
+/**
+ * Drop a method. Refuses to remove the last one — an envelope with no wraps is a share nobody,
+ * including its owner, can ever open again.
+ *
+ * @throws {WaaskeyError} `validation` — removing this method would leave nothing.
+ */
+declare function removeMethod(envelope: SecretEnvelope, method: UnlockMethod): SecretEnvelope;
+/**
+ * Open the envelope with whatever the user has.
+ *
+ * A passkey is preferred when both are available and enrolled: it is the path with nothing to type.
+ *
+ * @throws {WaaskeyError} `unauthorized` — nothing supplied matches an enrolled method, or the
+ * passphrase is wrong.
+ */
+declare function openSecret(envelope: SecretEnvelope, opener: {
+    passphrase?: string;
+    passkeySecret?: string;
+}): Promise<string>;
+/** Which methods this envelope accepts — what an unlock screen offers. */
+declare function enrolledMethods(envelope: SecretEnvelope): UnlockMethod[];
+
 /**
  * **Optional** client-side broadcast helper.
  *
@@ -3182,4 +3832,4 @@ declare class PasskeyPrfSecretProvider {
     }): Promise<PasskeyPrfResult>;
 }
 
-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 };
+export { Analytics, type AnalyticsEvent, type AnalyticsEventType, type AnalyticsSink, type AppRequester, 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 Device, type DeviceCompleteReshareParams, type DeviceCompleteReshareResult, type DeviceKeygenParams, type DeviceKeygenResult, type DeviceRegistration, type DeviceReshareAssembleParams, type DeviceReshareAssembleResult, type DeviceReshareMaterial, type DeviceSignParams, type DeviceSignResult, Devices, 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 PasskeyEnroller, type PasskeyPrfEnrollOptions, type PasskeyPrfResult, PasskeyPrfSecretProvider, type PasskeyUnlockKey, type PermissionDecision, type PermissionGrantStatus, type PermissionRequest, type PermissionRequestParams, type PermissionScope, type PrfCeremony, type PrimeLease, PrimePool, type PrimePoolOptions, type PrimePoolStore, type RecoverParams, type RecoverSignParams, type RecoverWalletResponse, Recovery, type RecoveryBackupEnvelope, type RecoveryChallengeResponse, type RecoveryEnrolment, 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 SecretEnvelope, type SendOptions, type SendParams, type SendResult, SessionKeys, 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 TeamMember, type TokenBalanceOptions, type TxStatus, type UnlockKeyWrap, type UnlockMethod, type VerifiedWasmLoaderOptions, Waaskey, WaaskeyError, type WaaskeyErrorCode, type WaaskeyErrorOptions, type WaaskeyOptions, type WaitForDecisionOptions, Wallet, type WalletActionType, type WalletBackupParams, type WalletCeremony, type WalletCurve, type WalletData, type WalletShareholder, type WalletStatus, Wallets, WasmMpcCore, addMethod, broadcast, createVerifiedClientWasmLoader, enrolledMethods, epochShareKey, formatUnits, generateRecoveryCode, getSigningAssertion, isNonCustodial, isPasskeyAssertionSupported, isPasskeySupported, isPrfSupported, loadClientWasm, memberShareKey, newUnlockSecret, openRecoveryBackup, openSecret, passkeyFactorEnrollment, passkeyFactorVerification, removeMethod, sealRecoveryBackup, sealSecret, signUserOpHash, userBackupPendingKey, validateCustodyPolicy, verifyWasmIntegrity };