@muhkoo/connect 0.10.11-alpha.0 → 0.10.13-alpha.0

package/dist/connect.d.ts

@@ -2232,6 +2232,29 @@ declare function signMessage(message: string, privateKey: CryptoKey): Promise<st
  * seed) while moving credential entry onto the Muhkoo origin. The envelope is
  * versioned so a future per-app-key handoff (v2) can swap in without a protocol
  * change.
+ *
+ * ## v2 — device pairing (TV / no-redirect handoff)
+ *
+ * v1's K_t rides in the redirect URL *fragment*, which works only because the
+ * receiving app is a browser page that can read `location.hash`. A TV app has
+ * no redirect to receive: it polls. So v2 keeps the *entire* v1 shape — the
+ * server relays a sealed envelope it cannot read — and replaces only the key
+ * agreement:
+ *
+ *   - the TV generates an ephemeral P-256 ECDH keypair in memory and publishes
+ *     the public half ({@link generateDevicePairingKeypair});
+ *   - the hosted page (the component that already holds the unlocked seed and
+ *     already owns sealing) seals *to that public key* with a fresh ephemeral
+ *     keypair of its own ({@link sealSeedToDevice}) — ECDH → HKDF-SHA256 →
+ *     AES-256-GCM;
+ *   - the TV recovers the seed with its private key
+ *     ({@link unsealSeedFromDevice}).
+ *
+ * The server stores and relays the v2 envelope byte-for-byte, exactly as it
+ * does for v1, and can read neither. The one thing ECDH cannot supply is proof
+ * that the public key the hosted page sealed to is *the TV's* rather than an
+ * attacker's — that is what {@link pairingVerificationCode} is for, and it is
+ * the only MITM defence in the flow (see the entropy note on that function).
  */
 interface SealedHandoff {
     /** base64 JSON envelope — relayed by the server in the grant; server-opaque. */
@@ -2243,6 +2266,101 @@ interface SealedHandoff {
 declare function sealSeed(seed: Uint8Array): Promise<SealedHandoff>;
 /** Recover the master seed from the sealed envelope + the fragment key. */
 declare function unsealSeed(sealedKeys: string, fragmentKey: string): Promise<Uint8Array>;
+/**
+ * Alphabet for the pairing verification code: 30 symbols, every confusable pair
+ * removed in BOTH directions — no `0`/`O`, no `1`/`I`/`L`, and no `U` (which is
+ * read as `V` on the low-resolution, far-viewed type a TV renders). Because the
+ * user compares this string across two screens by eye, unambiguity beats the
+ * convenience of a power-of-two alphabet; the derivation below rejection-samples
+ * to avoid the modulo bias that costs us.
+ */
+declare const PAIRING_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTVWXYZ23456789";
+/** Length of the pairing verification code, in characters. 30^8 ≈ 39.3 bits. */
+declare const PAIRING_CODE_LENGTH = 8;
+/** An ephemeral ECDH keypair generated by the pairing device (the TV). */
+interface DevicePairingKeypair {
+    /** base64 raw (SEC1 uncompressed, 65 bytes) public key — safe to publish. */
+    publicKeyB64: string;
+    /**
+     * Non-extractable private half. In-memory only, one per pairing attempt:
+     * it is never persisted and never leaves the device, so a captured pairing
+     * transcript is undecryptable once the attempt ends.
+     */
+    privateKey: CryptoKey;
+}
+/**
+ * (Device side) Generate the ephemeral P-256 ECDH keypair for one pairing
+ * attempt. Call this once per attempt and throw it away when the attempt ends —
+ * reusing a keypair across attempts would let an old, observed ciphertext be
+ * decrypted by whoever later obtains the key.
+ */
+declare function generateDevicePairingKeypair(): Promise<DevicePairingKeypair>;
+/**
+ * (Hosted-page side) Seal the master seed *to a device's* pairing public key.
+ *
+ * A fresh ephemeral keypair is generated per call and its public half is
+ * carried in the envelope (`epk`), so sealing the same seed to the same device
+ * twice yields unrelated ciphertext — and the sealer retains nothing that could
+ * later reopen the envelope.
+ *
+ * Returns the v2 `sealedKeys` string, which slots into exactly the same server
+ * field as v1: relayed verbatim, never read.
+ */
+declare function sealSeedToDevice(seed: Uint8Array, devicePublicKeyB64: string): Promise<string>;
+/**
+ * (Device side) Recover the master seed from a v2 envelope using the ephemeral
+ * private key from {@link generateDevicePairingKeypair}.
+ *
+ * Throws on any tamper: a substituted `epk` yields a different shared secret
+ * (or fails point validation outright), and any edit to `iv`/`ct` fails the
+ * AES-GCM tag. There is no path that returns partially-authenticated bytes.
+ *
+ * `devicePublicKeyB64` is the caller's OWN public half (from
+ * {@link generateDevicePairingKeypair}). It is required, not optional, because
+ * it is mixed into the KDF — see {@link deriveDeviceSealKey} for why binding the
+ * recipient matters. A device always holds both halves, so this costs nothing.
+ */
+declare function unsealSeedFromDevice(sealedKeys: string, privateKey: CryptoKey, devicePublicKeyB64: string): Promise<Uint8Array>;
+/**
+ * Short code derived deterministically from the device's pairing public key,
+ * displayed on BOTH the TV and the approving browser so the human can confirm
+ * they match before approving.
+ *
+ * ## What this is worth (be honest about it)
+ *
+ * ~39.3 bits (30^8), rendered in an unambiguous 30-symbol alphabet and grouped
+ * as `XXXX-XXXX` for comparison. Alongside the recipient-key binding in
+ * {@link deriveDeviceSealKey}, this is what stops a substituted device key: the
+ * KDF rejects a *negated* key, and this code is what a human uses to reject a
+ * wholly *attacker-generated* one, which the crypto cannot detect on its own —
+ * ECDH proves nothing about WHOSE public key it is.
+ *
+ * Two attacks, and what each actually costs:
+ *
+ *   1. **Online grind.** Generate keypairs until one's code equals the honest
+ *      TV's. ~2^39 trials. Naively that reads as "keygen + hash", but a real
+ *      attacker never generates keys: walking `P_{i+1} = P_i + G` while tracking
+ *      `d_i = d_0 + i` makes each trial one point-add plus one derivation. With
+ *      a plain hash that is well under a core-day — which is why this uses
+ *      PBKDF2-SHA256 at {@link PAIRING_CODE_ITERATIONS} iterations instead. The
+ *      work factor applies per trial, pushing the same grind to the order of
+ *      10^5 core-days. The target is also only learned when pairing starts, so
+ *      the grind is online against the pairing TTL (keep it minutes).
+ *   2. **Precomputed table.** The reason this is not a plain hash. A table over
+ *      candidate keys is computed once and reused forever; with SHA-256 that is
+ *      cheap enough to be the preferred attack. The iteration count multiplies
+ *      the table's build cost by the same 2 * 10^5.
+ *
+ * Neither is a proof of security, and an adversary with ASIC-scale hardware
+ * changes these numbers. If the margin is ever judged insufficient, raise
+ * {@link PAIRING_CODE_LENGTH} — 10 characters buys ~49 bits for two more
+ * characters of human comparison, and is display-only: it does not touch the
+ * envelope or the wire format.
+ *
+ * The cost is paid once per pairing, on two idle devices, so ~200k iterations
+ * is imperceptible here in a way it would not be on a hot path.
+ */
+declare function pairingVerificationCode(devicePublicKeyB64: string): Promise<string>;
 interface Pkce {
     codeVerifier: string;
     codeChallenge: string;
@@ -2364,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
@@ -2380,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 {
@@ -2387,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;
@@ -2423,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
@@ -2436,12 +2731,180 @@ 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 signs it out and forces a full
+     * re-approval, but it **does not take back the encryption key the device
+     * already holds**. Say so — users will assume otherwise.
+     */
+    listPairedDevices(): Promise<PairedDevice[]>;
+    /** Remove a paired device and revoke its session. Session-authed. */
+    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`
@@ -2749,6 +3212,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;
@@ -5046,6 +5510,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**.
  *
@@ -6019,5 +6632,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, 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, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isOfflineCapable, isP2pCapable, isProvisional, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, passkeyPrfCapable, passkeySupported, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, rpIdUsableForOrigin, sealSeed, shardHash, signMessage, stableStringify, toField, tombstoneRow, unpack, unsealSeed, 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, 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, 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 };