@muhkoo/connect 0.10.12-alpha.0 → 0.10.14-alpha.0

package/dist/connect.d.ts

@@ -2482,7 +2482,7 @@ declare class SessionState {
 
 /**
  * `client.auth.hosted` — centralized hosted auth (auth.muhkoo.dev).
- * AUTH_HOSTED_PLAN.md.
+ * AUTH_HOSTED_PLAN.md; TV device pairing per `muhkoo/auth/docs/tv-device-pairing-spec.md`.
  *
  * Two sides share this class:
  *   - **Developer apps** call {@link login} (redirect to the hosted page) and
@@ -2498,6 +2498,22 @@ declare class SessionState {
  *   page →  (user authenticates) → POST /api/auth/grant → redirect_uri?code&state#k=<K_t>
  *   app  →  POST /api/auth/token {code, code_verifier} → {sessionToken, sealedKeys}
  *        →  unseal sealedKeys with K_t → master seed → session ready
+ *
+ * ## Device pairing (v2 — TVs and other keyboard-less devices)
+ *
+ * The redirect flow above is unchanged and remains the fallback for anything
+ * with a browser and a keyboard. A device with no redirect to receive instead
+ * displays a code and **polls**:
+ *
+ *   TV   →  {@link startDevicePairing} → shows `userCode` + `verificationCode`
+ *   user →  opens auth.muhkoo.dev/link, signs in, {@link lookupDevicePairing}
+ *   user →  compares the verification code on both screens,
+ *           {@link approveDevicePairing} seals the seed TO the TV's public key
+ *   TV   →  {@link waitForDevicePairing} → unseal → own ZK session → persisted
+ *
+ * Same invariant as v1: the accelerator relays a sealed envelope it cannot read.
+ * Only the key agreement changes (ECDH to a key the TV generated, instead of a
+ * one-time key delivered in a URL fragment a TV can't receive).
  */
 
 interface HostedAuthDeps {
@@ -2505,10 +2521,171 @@ interface HostedAuthDeps {
     session: SessionState;
     /** Base URL of the hosted auth SPA (e.g. https://auth.muhkoo.dev). */
     authBaseUrl: string;
+    /**
+     * Absolute URL of the accelerator (e.g. https://api.muhkoo.dev) — the origin
+     * the `/api/auth/device*` endpoints live on.
+     *
+     * Optional for backwards compatibility: `AuthNamespace` does not pass it
+     * today, so it is resolved from the {@link AuthClient} at call time (see
+     * `apiBase`). Pass it explicitly whenever you construct `HostedAuth` yourself.
+     */
+    apiBaseUrl?: string;
+    /**
+     * `preimagePoK` circuit assets, used when a paired device mints its OWN ZK
+     * session. Defaults to {@link defaultCircuitUrls} anchored at `apiBaseUrl` —
+     * which matches `Client`'s own default. Supply it if the app overrode
+     * `ClientOptions.circuits`.
+     */
+    circuits?: CircuitUrls;
+    /** Custom fetch — defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Sleep used by the poll loop. Injectable so tests don't burn wall-clock. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** One in-flight pairing attempt. Hold it; pass it back into poll/wait/cancel. */
+interface DevicePairingSession {
+    /** Opaque; carry it back into poll/wait/cancel. Never render it. */
+    deviceCode: string;
+    /** Show this, large. Formatted `"XXXX-XXXX"`. */
+    userCode: string;
+    /**
+     * Show this too, and tell the user it must match the browser. Computed
+     * LOCALLY from this device's own public key — the server's copy is never
+     * trusted (that binding is the only MITM defence in the flow).
+     */
+    verificationCode: string;
+    verificationUri: string;
+    /** Same URI with the code pre-filled — render as a QR code. */
+    verificationUriComplete: string;
+    /** Absolute epoch-ms. */
+    expiresAt: number;
+    /** Server-recommended seconds between polls; may grow via `slow_down`. */
+    interval: number;
+    /** Ephemeral private key for this attempt. In memory only, never persisted. */
+    privateKey: CryptoKey;
+    /**
+     * This attempt's own public half, base64 raw SEC1.
+     *
+     * NOT in the spec's §7 listing, but REQUIRED: `unsealSeedFromDevice` takes
+     * the recipient key as a third argument because it is mixed into the KDF to
+     * defeat a point-negation substitution. The shipped crypto is authoritative;
+     * carrying the public half here costs nothing (a device always holds both).
+     */
+    devicePublicKeyB64: string;
+}
+/** The result of one poll. Discriminated on `status`. */
+type DevicePairingPoll = {
+    status: "pending";
+    interval: number;
+    expiresIn: number;
+} | {
+    status: "slow_down";
+    interval: number;
+    retryAfter: number;
+} | {
+    status: "approved";
+    user: AuthUser;
+} | {
+    status: "denied";
+} | {
+    status: "expired";
+};
+interface StartDevicePairingOptions {
+    appId: string;
+    /** Human label shown to the approver. Default: a UA-derived guess. */
+    label?: string;
 }
-interface AuthUser$1 {
-    username: string;
-    commitment: string;
+interface WaitForDevicePairingOptions {
+    signal?: AbortSignal;
+    /** Called before each sleep — drive a countdown / "waiting…" UI. */
+    onTick?: (remainingMs: number, interval: number) => void;
+}
+/** A pending pairing, resolved by the approver from the typed `user_code`. */
+interface DevicePairingRequest {
+    userCode: string;
+    devicePublicKeyB64: string;
+    /** Recomputed locally by the SDK; compare with what the TV shows. */
+    verificationCode: string;
+    deviceFingerprint: string;
+    deviceLabel: string;
+    appId: string;
+    appLabel: string;
+    isKnownDevice: boolean;
+    requiresReauth: boolean;
+    expiresAt: number;
+}
+/** A device the account has paired, as listed on the security page. */
+interface PairedDevice {
+    id: string;
+    label: string;
+    appId: string;
+    pairedAt: number;
+    lastSeenAt: number;
+    activeSession: boolean;
+}
+/**
+ * Why a pairing ended.
+ *
+ * `denied` / `expired` / `aborted` / `rate_limited` are the four the spec names
+ * for {@link HostedAuth.waitForDevicePairing}. The rest are additive and exist
+ * because the flow genuinely produces them:
+ *   - `network` — the reference loop in spec §9.2 throws it after 5 consecutive
+ *     transport failures;
+ *   - `commitment_mismatch` — spec §10.8's MANDATORY client check failed (the
+ *     seed does not derive the commitment the server sent). This is what turns
+ *     §10.2's substitution attack from silent into loud;
+ *   - `account_mismatch` — spec §10.2 detection 2: this device was previously
+ *     paired to a DIFFERENT account. Refuse rather than silently adopt;
+ *   - `reauth_required` — see {@link ReauthRequiredError};
+ *   - `invalid_user_code` — client-side canonicalization rejected the input;
+ *   - `error` — anything else; read `.code` for the server's machine code.
+ */
+type DevicePairingErrorReason = "denied" | "expired" | "aborted" | "rate_limited" | "network" | "commitment_mismatch" | "account_mismatch" | "reauth_required" | "invalid_user_code" | "error";
+/**
+ * Any terminal failure of the pairing flow.
+ *
+ * `.reason` drives the device's UI state machine; `.code` carries the server's
+ * machine error code verbatim (spec §6.7) for the cases the reason collapses —
+ * e.g. `consent_required`, `too_many_devices`, `key_mismatch` all arrive as
+ * `reason: "error"` with a distinct `.code`.
+ */
+declare class DevicePairingError extends Error {
+    readonly reason: DevicePairingErrorReason;
+    /** Machine code from the error envelope (`{error, message}`), when there was one. */
+    readonly code?: string;
+    readonly status?: number;
+    /** Seconds, from `Retry-After`, when the server sent one. */
+    readonly retryAfter?: number;
+    /** Any extra fields the error envelope carried (e.g. `version`). */
+    readonly details?: Record<string, unknown>;
+    constructor(reason: DevicePairingErrorReason, opts?: {
+        message?: string;
+        code?: string;
+        status?: number;
+        retryAfter?: number;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+/**
+ * Approving a **new** device needs a recently authenticated approver (spec
+ * §10.7, `FRESH_AUTH_MAX_AGE_MS`). The hosted page catches this, prompts for a
+ * password / passkey / Google factor, and retries the approval.
+ *
+ * Server-enforced, not a UI convention — `requiresReauth` on
+ * {@link DevicePairingRequest} is only the hint.
+ */
+declare class ReauthRequiredError extends DevicePairingError {
+    /** How long ago the approver's session authenticated, in seconds. */
+    readonly authAgeSeconds?: number;
+    /** The freshness window the server enforces, in seconds. */
+    readonly maxAgeSeconds?: number;
+    constructor(opts?: {
+        message?: string;
+        authAgeSeconds?: number;
+        maxAgeSeconds?: number;
+        status?: number;
+    });
 }
 declare class HostedAuth {
     private readonly deps;
@@ -2541,7 +2718,7 @@ declare class HostedAuth {
      * code (+ PKCE verifier) for the session, unseal the seed from the fragment,
      * establish the session, and scrub the URL. Returns the signed-in user.
      */
-    handleCallback(): Promise<AuthUser$1>;
+    handleCallback(): Promise<AuthUser>;
     /**
      * (Hosted-page side) Finish an /authorize request after the user has
      * authenticated here: seal the in-memory seed, mint the grant, and return
@@ -2554,12 +2731,190 @@ declare class HostedAuth {
         codeChallenge: string;
         state: string;
     }): Promise<string>;
+    /**
+     * (Device side) Begin pairing. Generates the ephemeral ECDH keypair, ensures
+     * a persistent device identity key exists, signs a possession proof over it,
+     * and calls `POST /api/auth/device/code`.
+     *
+     * Display `userCode` (large, monospace) **and** `verificationCode`, then call
+     * {@link waitForDevicePairing}. The verification code returned here is
+     * computed locally from this device's own public key — the server also
+     * returns a copy, which is ignored on purpose: trusting it would forfeit the
+     * entire MITM binding (spec §6.1, §10.1).
+     */
+    startDevicePairing(opts: StartDevicePairingOptions): Promise<DevicePairingSession>;
+    /**
+     * (Device side) One poll of `POST /api/auth/device/token`.
+     *
+     * On `"approved"` this does the whole tail of the flow before returning: it
+     * unseals the envelope with the ephemeral private key, derives the identity,
+     * **verifies the commitment matches** (spec §10.8 — mandatory, and the check
+     * that makes a substituted seed loud rather than silent), mints the device's
+     * OWN long-lived ZK session, registers the device via `PUT /api/auth/devices`,
+     * and persists the identity for cold starts.
+     *
+     * Prefer {@link waitForDevicePairing}; use this only for a custom loop. A
+     * transport failure REJECTS (the caller decides whether to retry); protocol
+     * outcomes resolve as a status.
+     */
+    pollDevicePairing(session: DevicePairingSession): Promise<DevicePairingPoll>;
+    /**
+     * (Device side) Poll to completion with the interval + `slow_down` backoff of
+     * spec §9.
+     *
+     * The server's `interval` is authoritative: on `slow_down` the client moves to
+     * `max(serverInterval, own + 5, retryAfter)` so the two can't drift into a
+     * permanent slow_down loop. Sleeps carry ±10 % jitter so a rack of devices
+     * restarted together doesn't synchronise, and the loop stops at `expiresAt`
+     * without waiting for the server to say so.
+     *
+     * Resolves with the signed-in user, or rejects with {@link DevicePairingError}.
+     */
+    waitForDevicePairing(session: DevicePairingSession, opts?: WaitForDevicePairingOptions): Promise<AuthUser>;
+    /**
+     * (Device side) Abandon an attempt. Marks the session dead so an in-flight
+     * {@link waitForDevicePairing} rejects with `aborted` on its next tick, and
+     * clears the device code.
+     *
+     * The ephemeral `CryptoKey` cannot be zeroed from JS — dropping the last
+     * reference to `session` is what makes it unrecoverable, so don't keep the
+     * object around. Deliberately does NOT notify the server: the pairing is
+     * single-use and expires on its own, and an unauthenticated "cancel" endpoint
+     * would just be another way to grief someone else's pending code.
+     */
+    cancelDevicePairing(session: DevicePairingSession): void;
+    /**
+     * (Device side) Cold-start path. Reads the persisted device identity,
+     * re-derives the ZK identity from the stored seed, mints a fresh session, and
+     * touches `PUT /api/auth/devices`.
+     *
+     * Returns `null` when nothing is persisted, when the blob doesn't derive its
+     * own pinned commitment (corrupt/tampered storage), or when the account no
+     * longer accepts the identity — call {@link startDevicePairing} then.
+     */
+    resumeDeviceSession(): Promise<AuthUser | null>;
+    /** (Device side) Wipe the persisted seed, the device identity key, and the session. */
+    forgetDeviceSession(): Promise<void>;
+    /** (Device side) Whether a persisted device identity exists. Cheap: no crypto, no network. */
+    hasDeviceSession(): Promise<boolean>;
+    /**
+     * (Hosted page) Resolve a typed `user_code` into the pending request.
+     * Session-authed.
+     *
+     * `verificationCode` is recomputed here from the returned device key — the
+     * server's copy is discarded. Both screens must show independently derived
+     * values or the comparison proves nothing.
+     */
+    lookupDevicePairing(userCode: string): Promise<DevicePairingRequest>;
+    /**
+     * (Hosted page) Seal the in-memory seed to the device's public key and post
+     * the ciphertext. Requires an unlocked seed — the user just authenticated
+     * here — exactly like {@link completeAuthorize}. The server stores and relays
+     * the envelope verbatim and can't read it.
+     *
+     * Show the user the verification code and the device label FIRST, and only
+     * call this on an explicit tap. Throws {@link ReauthRequiredError} when the
+     * account's last authentication is too old for a new device; the page should
+     * prompt for a factor and retry. A stale legal agreement arrives as
+     * `DevicePairingError` with `.code === "consent_required"` and
+     * `.details.version`.
+     */
+    approveDevicePairing(req: DevicePairingRequest, opts?: {
+        label?: string;
+    }): Promise<{
+        deviceId: string;
+    }>;
+    /**
+     * (Hosted page) Refuse a pairing. No re-auth and no consent gate — declining
+     * must never be harder than accepting. Leaves a tombstone so the device is
+     * told "declined" rather than an indistinguishable "expired".
+     */
+    denyDevicePairing(userCode: string): Promise<void>;
+    /**
+     * The account's paired devices. Session-authed.
+     *
+     * UI copy note (spec §10.6): removing a device forces a full re-approval next
+     * time, but be careful what you promise. It does NOT sign the device out —
+     * the server returns `session_revoked: false`, and that session runs until it
+     * expires — and it cannot take back the master seed the device already holds.
+     * Users assume "remove" means "locked out immediately"; it does not.
+     */
+    listPairedDevices(): Promise<PairedDevice[]>;
+    /**
+     * Un-pair a device. Session-authed.
+     *
+     * It stops being a "known" device, so pairing it again needs full approval
+     * with a fresh factor. It does NOT end that device's current session — the
+     * server reports `session_revoked: false` — and it cannot take back the
+     * master seed the device already holds. Do not write UI copy promising an
+     * immediate sign-out; users will assume it and be wrong.
+     */
+    revokePairedDevice(id: string): Promise<void>;
+    /**
+     * The whole tail of an approved pairing: unseal → derive → **verify** →
+     * authenticate → register → persist. Split out of `pollDevicePairing` so the
+     * ordering (and the two refusals) stay readable.
+     */
+    private adoptSealedSeed;
+    /**
+     * Run the standard ZK challenge → Groth16 proof → authenticate round-trip for
+     * an identity derived from a seed the caller already holds, and store the
+     * resulting session.
+     *
+     * Identical to `ZkAuth.login()`'s tail (`proveAndStore`) — same challenge,
+     * same circuit, same signature — so the commitment is byte-identical to
+     * `zk.login(username, password)` by construction. No new endpoint, no circuit
+     * change, no alternative derivation.
+     *
+     * (Spec §7 puts this on `AuthNamespace` as `loginWithSeed`; see the report —
+     * it lives here because `AuthNamespace.ts` was out of scope for this change,
+     * and `proveAndStore` is private.)
+     */
+    private mintSession;
+    /**
+     * `PUT /api/auth/devices` — the device checks in after each self-login so the
+     * security page can show "last seen" and revoke the right session. Never
+     * creates a record (only approve does), so a 404 here is expected on a device
+     * whose pairing was revoked. Best-effort by design.
+     */
+    private touchPairedDevice;
+    /** Reject a session that {@link cancelDevicePairing} has retired. */
+    private assertLive;
+    private sleep;
+    /**
+     * One round-trip to a `/api/auth/device*` endpoint. Never throws on a non-2xx
+     * — the poll path has to inspect 401/403/429 itself — so callers that don't
+     * want that follow up with {@link throwForStatus}.
+     */
+    private deviceApi;
+    /** Turn a non-2xx device-endpoint response into the right typed error. */
+    private throwForStatus;
+    /**
+     * Accelerator origin for the device endpoints.
+     *
+     * Prefers the explicit dep. Falls back to the {@link AuthClient}'s own base
+     * URL, because `AuthNamespace` builds `HostedAuth` without one today and a
+     * hard-coded default would silently point a staging or local build at
+     * production. Last resort: map the auth SPA host (`auth.…` → `api.…`).
+     */
+    private apiBase;
+    private circuits;
     private location;
     private store;
     private take;
     /** Drop `code`, `state`, and the `#k` fragment from the address bar. */
     private scrubUrl;
 }
+/**
+ * Canonicalize a typed `user_code`: uppercase, drop whitespace and `-`.
+ *
+ * We deliberately do NOT guess (`O → 0`, `I → 1`, …). Both members of every
+ * confusable pair are excluded from the alphabet, so a typed `O` is a genuine
+ * misread — telling the user is more useful than silently resolving it.
+ */
+declare function canonicalUserCode(input: string): string;
+/** Group a canonical code for display and for the wire: `"K7QD3MXR"` → `"K7QD-3MXR"`. */
+declare function formatUserCode(canonical: string): string;
 
 /**
  * `client.auth` — user authentication, exposed today through the `zk`
@@ -2867,6 +3222,7 @@ declare class AuthNamespace {
     readonly hosted: HostedAuth;
     constructor(deps: ZkAuthDeps & {
         authBaseUrl: string;
+        apiBaseUrl?: string;
     });
     /** Convenience pass-through: the currently signed-in user, or `null`. */
     get user(): AuthUser | null;
@@ -5164,6 +5520,155 @@ declare class Client {
     recoverSession(): Promise<boolean>;
 }
 
+/**
+ * `deviceStore` — at-rest persistence for a paired device (the TV).
+ *
+ * A device that has completed {@link HostedAuth.startDevicePairing} holds the
+ * account's **master seed**. Android WebView has no WebAuthn, so the passkey
+ * wrapping used elsewhere isn't available, and re-pairing on every cold start
+ * is not acceptable UX for a set-top box. So the seed is persisted, encrypted:
+ *
+ * | Item                     | Where                                | Form |
+ * | ------------------------ | ------------------------------------ | ---- |
+ * | wrapping key             | IndexedDB (`muhkoo.device.v1`)       | `CryptoKey`, AES-GCM-256, **non-extractable** |
+ * | device identity keypair  | IndexedDB (`muhkoo.device.v1`)       | `CryptoKeyPair`, ECDSA P-256, private half **non-extractable** |
+ * | sealed identity blob     | localStorage `muhkoo.tv.identity.v1` | `{"v":1,"iv":…,"ct":…}` over `JSON{username, commitment, seed(b64), pairedAt}` |
+ *
+ * The split is deliberate — ciphertext in one backend, key in another, and the
+ * key non-extractable so JS can *use* it but not export it.
+ *
+ * ## Be honest about what this is worth
+ *
+ * **This is obfuscation, not protection.** It raises the cost of a casual
+ * `localStorage` dump to "nothing useful", and that is all:
+ *
+ *   - **XSS on the device origin** cannot *exfiltrate* the wrapping key (it is
+ *     non-extractable) but can absolutely call `decrypt` and read the seed. The
+ *     only mitigation is that there is no third-party script in the shell —
+ *     enforce a strict CSP with no `unsafe-inline`, no CDN, no remote fonts.
+ *   - **ADB / root / a backup extraction / a forensic image recovers the seed.**
+ *     The IndexedDB LevelDB files hold the AES key bytes in the clear; WebCrypto
+ *     "non-extractable" is a JS-API boundary, not an OS one. **A stolen device is
+ *     a stolen identity.**
+ *
+ * That is not an implementation shortcut, it is the shape of the problem: any
+ * wrapping key usable without user interaction lives somewhere equally readable
+ * on a keyboard-less device with no hardware key store exposed to WebView.
+ * Reduce the blast radius with `android:allowBackup="false"`,
+ * `android:debuggable="false"`, a strict CSP, and by storing *only* the 32-byte
+ * seed + username + commitment (never a session token, never a recovery phrase).
+ *
+ * ## Documented upgrade path — no protocol change
+ *
+ * If the native shell exposes a Keystore bridge:
+ *
+ * ```java
+ * @JavascriptInterface public String wrap(String b64plain);    // AES-GCM, StrongBox when present
+ * @JavascriptInterface public String unwrap(String b64cipher);
+ * ```
+ *
+ * this module prefers `globalThis.MuhkooKeystore` automatically and falls back
+ * to the WebCrypto scheme otherwise. The Keystore key is hardware-backed and
+ * non-exportable at the OS level, so a copied filesystem image alone becomes
+ * useless. Nothing on the wire, in the endpoint contracts, or in the SDK surface
+ * changes — only the two functions below do, internally.
+ *
+ * ## Degradation
+ *
+ * Nothing here throws at import time. On a runtime with neither backend (SSR,
+ * Workers, Node) the module still loads: {@link loadDeviceIdentity} returns
+ * `null`, {@link persistDeviceIdentity} throws a typed
+ * {@link DeviceStoreUnavailableError} the caller can swallow, and
+ * {@link deviceIdentityKey} falls back to an **in-memory** keypair for the
+ * lifetime of the process (so pairing still works; the device is just never
+ * recognised as "known" on a later run).
+ */
+/** localStorage key holding the AES-GCM-sealed identity blob. */
+declare const DEVICE_IDENTITY_STORAGE_KEY = "muhkoo.tv.identity.v1";
+/** IndexedDB database holding the non-extractable keys. */
+declare const DEVICE_KEY_DB_NAME = "muhkoo.device.v1";
+/** What a paired device persists. The seed **is** the identity — treat it as such. */
+interface PersistedDeviceIdentity {
+    username: string;
+    /** Decimal-string Poseidon commitment. Pinned: a later pairing that yields a
+     *  different commitment for this device must be refused, not adopted. */
+    commitment: string;
+    /** The 32-byte master seed. */
+    seed: Uint8Array;
+    pairedAt: number;
+}
+/** Thrown when persistence is impossible (no IndexedDB and/or no localStorage). */
+declare class DeviceStoreUnavailableError extends Error {
+    constructor(what: string);
+}
+/** Key/value store for live `CryptoKey` objects (IndexedDB in the browser). */
+interface DeviceKeyVault {
+    get(id: string): Promise<unknown | null>;
+    put(id: string, value: unknown): Promise<void>;
+    /** Delete the entire store — used by `clearDeviceIdentity`. */
+    destroy(): Promise<void>;
+}
+/** String store for the sealed blob (localStorage in the browser). */
+interface DeviceBlobStore {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/** The native Keystore bridge, when the shell provides one (see module docs). */
+interface MuhkooKeystoreBridge {
+    wrap(b64plain: string): string | Promise<string>;
+    unwrap(b64cipher: string): string | Promise<string>;
+}
+/**
+ * Point the store at explicit backends (or `null` to force "unavailable"), and
+ * reset the memoized device keypair. Testing / embedding seam — pass `{}` to
+ * restore the default browser backends.
+ */
+declare function configureDeviceStore(opts?: {
+    keys?: DeviceKeyVault | null;
+    blobs?: DeviceBlobStore | null;
+    keystore?: MuhkooKeystoreBridge | null;
+}): void;
+/**
+ * True when {@link deviceIdentityKey} had to fall back to an in-memory keypair
+ * because no key vault was available. Such a device can pair, but will never be
+ * recognised as "known" afterwards (so approval always needs a fresh factor).
+ */
+declare function deviceIdentityIsEphemeral(): boolean;
+/**
+ * The device's **persistent** ECDSA P-256 identity keypair, created on first
+ * call. This is not a browser fingerprint — it is a key, and every
+ * `POST /api/auth/device/code` proves possession of it. Without that proof,
+ * "known device" would be an unauthenticated string anyone could claim in order
+ * to skip the approver's re-authentication.
+ *
+ * The private half is non-extractable and never leaves IndexedDB as bytes.
+ */
+declare function deviceIdentityKey(): Promise<CryptoKeyPair>;
+/** `base64url(SHA-256(raw SEC1 device identity public key))` — 43 chars. */
+declare function deviceFingerprint(): Promise<string>;
+/** Whether a sealed identity blob exists. Cheap: no crypto, no IndexedDB, no network. */
+declare function hasDeviceIdentity(): Promise<boolean>;
+/**
+ * Seal and store the identity. Throws {@link DeviceStoreUnavailableError} when
+ * there is nowhere to put it — callers should treat that as "this device won't
+ * resume", not as a pairing failure.
+ */
+declare function persistDeviceIdentity(v: PersistedDeviceIdentity): Promise<void>;
+/**
+ * Recover the persisted identity, or `null` when there is none / it can't be
+ * opened (wiped IndexedDB, a different browser profile, a corrupted blob).
+ * Never throws — a cold start with unreadable storage must fall back to a fresh
+ * pairing, not to an error screen.
+ */
+declare function loadDeviceIdentity(): Promise<PersistedDeviceIdentity | null>;
+/**
+ * Wipe everything: the sealed blob **and** the whole key database — so the
+ * wrapping key never outlives the ciphertext it opens, and the device identity
+ * key is regenerated (a re-pair is then correctly treated as a new device).
+ */
+declare function clearDeviceIdentity(): Promise<void>;
+
 /**
  * Passkey factor (M1.1) — WebAuthn with the **PRF extension**.
  *
@@ -5210,6 +5715,23 @@ declare function defaultRpId(): string;
  * sign-in (and offer to enroll a passkey for this origin) instead.
  */
 declare function rpIdUsableForOrigin(rpId: string | undefined | null, host?: string): boolean;
+/**
+ * Would {@link AuthNamespace.loginWithPasskey} accept a factor recorded with
+ * this `rpId`, from `host`?
+ *
+ * This is deliberately NOT the same as {@link rpIdUsableForOrigin}. That answers
+ * a raw WebAuthn question and is `false` for a missing rpId. But a factor with
+ * NO recorded rpId predates per-origin enrolment, and `loginWithPasskey`
+ * resolves it as `params.rpId ?? host` — so it IS usable, from anywhere.
+ *
+ * Callers deciding "should I even try a passkey here?" must use this one.
+ * Reaching for `rpIdUsableForOrigin` instead silently excludes every legacy
+ * passkey holder, which has locked real users out of production twice.
+ *
+ * The `?? host` fallback applies to nullish only, matching `loginWithPasskey`:
+ * an empty-string rpId stays unusable rather than resolving to the host.
+ */
+declare function passkeyUsableFromOrigin(rpId: string | undefined | null, host?: string): boolean;
 /** Thrown when the account's passkey belongs to a different origin. Callers
  *  should treat this as "no passkey here" and fall back to another factor. */
 declare class PasskeyOriginError extends Error {
@@ -6137,5 +6659,5 @@ declare class KeyringClient implements KeyringTransport {
     fetchMetadata(): Promise<SpaceMetadata | null>;
 }
 
-export { ACCESS_TOKEN_SCOPES, AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AccessTokensNamespace, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbCache, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PasskeyOriginError, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VaultUnavailableError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, buildCommitment, compareHlc, compilePrograms, createPasskeyWithPrf, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultRpId, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, evaluatePasskeyPrf, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, generateDevicePairingKeypair, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isOfflineCapable, isP2pCapable, isProvisional, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, pairingVerificationCode, passkeyPrfCapable, passkeySupported, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, shardHash, signMessage, stableStringify, toField, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
-export type { ACL, ACLEntry, AccessTokenInfo, AccessTokensNamespaceDeps, AgentConfig, AgentCreateInput, AgentDbToolMode, AgentProvisioned, AgentScopeOpts, AgentSkill, AgentToolsConfig, AgentTrigger, AgentTriggerType, AgentUpdateInput, AgentsNamespaceDeps, AttachedPeerNetwork, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, BlockStore, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, CachedSpaceMessage, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, ConnectivityOptions, ConnectivityState, CreateAccessTokenInput, CreatedAccessToken, DbQueryPage, DehydratedKeypair, DehydratedKeys, DevicePairingKeypair, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EngineHandle, EngineHost, EphemeralEvent, EpochKeyProvider, FileManifest, FileNamespaceDeps, FileStat, FileStorageOptions, FunctionCaps, FunctionConfig, FunctionDeployInput, FunctionInvokeOptions, FunctionScopeOpts, FunctionTrigger, FunctionTriggerType, FunctionTriggers, FunctionUpdateInput, FunctionsNamespaceDeps, Groth16Proof, Hasher, HlcParts, HlcState, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, KvEntry, KvNamespaceDeps, LoginOptions, LwwMap, LwwRegister, MessageBody, MessageDeletedEvent, MessageEntry, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOp, MessageOptions, MessageSubscription, MuhkooAgentMeta, MuhkooAgentToolsConfig, MuhkooAppDescriptor, MuhkooDBAccess, MuhkooDBMeta, MuhkooFunctionMeta, MuhkooMessageEvent, MuhkooSpaceMeta, OAuthProvider, OfflineEntry, OfflineManagerDeps, OfflineStore, OutSink, PacketCipher, PacketHeaders, PacketOptions, Participant, PasskeyEnrollment, PeerBlockSource, PeerExchangeOptions, PeerId, PeerNetworkOptions, PeerTransport, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, Pkce, PublicKeyJWK, QueueEntry, RatchetState, ReceiveResult, RegisterParams, Replayer, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, Scope, SealedHandoff, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardByteCache, ShardClientOptions, SharedSpaceClientOptions, SignalEnvelope, SignalKind, SignalingSpace, SnapshotNamespaceDeps, SnarkProof, SpaceChannelLike, SpaceCursor, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, SpaceOfflineAdapter, StorageChangeEvent, StoreName, StoredSession, Subscription, UserIdentity, VaultFactor, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WebRtcTransportOptions, WrappedPayload, WriteFileInput, WriteFileOptions, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };
+export { ACCESS_TOKEN_SCOPES, AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AccessTokensNamespace, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DEVICE_IDENTITY_STORAGE_KEY, DEVICE_KEY_DB_NAME, DbCache, DevicePairingError, DeviceStoreUnavailableError, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HostedAuth, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PasskeyOriginError, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, ReauthRequiredError, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VaultUnavailableError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, buildCommitment, canonicalUserCode, clearDeviceIdentity, compareHlc, compilePrograms, configureDeviceStore, createPasskeyWithPrf, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultRpId, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deviceFingerprint, deviceIdentityIsEphemeral, deviceIdentityKey, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, evaluatePasskeyPrf, exportPublicKeyBase64, exportPublicKeyHex, formatUserCode, generateAuthProof, generateDevicePairingKeypair, generatePkce, getMuhkooAppDescriptor, getSubtle, hasDeviceIdentity, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isOfflineCapable, isP2pCapable, isProvisional, loadDeviceIdentity, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, pairingVerificationCode, passkeyPrfCapable, passkeySupported, passkeyUsableFromOrigin, persistDeviceIdentity, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, shardHash, signMessage, stableStringify, toField, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
+export type { ACL, ACLEntry, AccessTokenInfo, AccessTokensNamespaceDeps, AgentConfig, AgentCreateInput, AgentDbToolMode, AgentProvisioned, AgentScopeOpts, AgentSkill, AgentToolsConfig, AgentTrigger, AgentTriggerType, AgentUpdateInput, AgentsNamespaceDeps, AttachedPeerNetwork, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, BlockStore, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, CachedSpaceMessage, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, ConnectivityOptions, ConnectivityState, CreateAccessTokenInput, CreatedAccessToken, DbQueryPage, DehydratedKeypair, DehydratedKeys, DeviceBlobStore, DeviceKeyVault, DevicePairingErrorReason, DevicePairingKeypair, DevicePairingPoll, DevicePairingRequest, DevicePairingSession, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EngineHandle, EngineHost, EphemeralEvent, EpochKeyProvider, FileManifest, FileNamespaceDeps, FileStat, FileStorageOptions, FunctionCaps, FunctionConfig, FunctionDeployInput, FunctionInvokeOptions, FunctionScopeOpts, FunctionTrigger, FunctionTriggerType, FunctionTriggers, FunctionUpdateInput, FunctionsNamespaceDeps, Groth16Proof, Hasher, HlcParts, HlcState, HostedAuthDeps, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, KvEntry, KvNamespaceDeps, LoginOptions, LwwMap, LwwRegister, MessageBody, MessageDeletedEvent, MessageEntry, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOp, MessageOptions, MessageSubscription, MuhkooAgentMeta, MuhkooAgentToolsConfig, MuhkooAppDescriptor, MuhkooDBAccess, MuhkooDBMeta, MuhkooFunctionMeta, MuhkooKeystoreBridge, MuhkooMessageEvent, MuhkooSpaceMeta, OAuthProvider, OfflineEntry, OfflineManagerDeps, OfflineStore, OutSink, PacketCipher, PacketHeaders, PacketOptions, PairedDevice, Participant, PasskeyEnrollment, PeerBlockSource, PeerExchangeOptions, PeerId, PeerNetworkOptions, PeerTransport, Permission, PermissionCheckRequest, PermissionCheckResult, PersistedDeviceIdentity, PersonalSpaceClientOptions, Pkce, PublicKeyJWK, QueueEntry, RatchetState, ReceiveResult, RegisterParams, Replayer, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, Scope, SealedHandoff, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardByteCache, ShardClientOptions, SharedSpaceClientOptions, SignalEnvelope, SignalKind, SignalingSpace, SnapshotNamespaceDeps, SnarkProof, SpaceChannelLike, SpaceCursor, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, SpaceOfflineAdapter, StartDevicePairingOptions, StorageChangeEvent, StoreName, StoredSession, Subscription, UserIdentity, VaultFactor, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WaitForDevicePairingOptions, WebRtcTransportOptions, WrappedPayload, WriteFileInput, WriteFileOptions, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };