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

package/dist/server/index.js

@@ -2867,7 +2867,7 @@ async function signMessage(message, privateKey) {
  * pre-hash fed into the OPRF, so even if the OPRF key ever leaked, guesses still
  * pay the scrypt cost.
  */
-const TE$1 = new TextEncoder();
+const TE$2 = new TextEncoder();
 // Interactive-login scrypt params (~100ms on a laptop). N must be a power of 2.
 const SCRYPT = { N: 1 << 15, r: 8, p: 1, dkLen: 32 };
 /** 32 random bytes - the master seed for a brand-new identity. */
@@ -2876,17 +2876,17 @@ function randomSeed() {
 }
 /** Memory-hard pre-hash of the password - the OPRF input. Salted by username. */
 function passwordPreHash(username, password) {
-    return scrypt(TE$1.encode(password), TE$1.encode("muhkoo-vault-v1:" + username.toLowerCase()), SCRYPT);
+    return scrypt(TE$2.encode(password), TE$2.encode("muhkoo-vault-v1:" + username.toLowerCase()), SCRYPT);
 }
 /** HKDF the 64-byte OPRF output into a non-extractable AES-256-GCM wrap key. */
 async function wrapKeyFromOprf(oprfOutput) {
     const prk = await crypto.subtle.importKey("raw", oprfOutput, { name: "HKDF" }, false, ["deriveKey"]);
-    return crypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(), info: TE$1.encode("muhkoo-vault-wrap") }, prk, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+    return crypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(), info: TE$2.encode("muhkoo-vault-wrap") }, prk, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
 }
 /** HKDF arbitrary 32-byte key material (e.g. a passkey PRF output) into an AES-GCM wrap key. */
 async function wrapKeyFromBytes(keyMaterial, info) {
     const prk = await crypto.subtle.importKey("raw", keyMaterial, { name: "HKDF" }, false, ["deriveKey"]);
-    return crypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(), info: TE$1.encode(info) }, prk, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+    return crypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(), info: TE$2.encode(info) }, prk, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
 }
 async function wrapSeed(seed, key) {
     const iv = crypto.getRandomValues(new Uint8Array(12));
@@ -2954,8 +2954,8 @@ function fromBase64(b64) {
  * 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).
  */
-const TE = new TextEncoder();
-const TD = new TextDecoder();
+const TE$1 = new TextEncoder();
+const TD$1 = new TextDecoder();
 /** Seal the master seed under a fresh one-time key for the redirect handoff. */
 async function sealSeed(seed) {
     const ktRaw = crypto.getRandomValues(new Uint8Array(32));
@@ -2964,13 +2964,13 @@ async function sealSeed(seed) {
     const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, key, seed));
     const envelope = { v: 1, iv: toBase64(iv), ct: toBase64(ct) };
     return {
-        sealedKeys: toBase64(TE.encode(JSON.stringify(envelope))),
+        sealedKeys: toBase64(TE$1.encode(JSON.stringify(envelope))),
         fragmentKey: base64UrlEncode(ktRaw),
     };
 }
 /** Recover the master seed from the sealed envelope + the fragment key. */
 async function unsealSeed(sealedKeys, fragmentKey) {
-    const envelope = JSON.parse(TD.decode(fromBase64(sealedKeys)));
+    const envelope = JSON.parse(TD$1.decode(fromBase64(sealedKeys)));
     if (envelope.v !== 1)
         throw new Error(`Unsupported handoff envelope version ${envelope.v}`);
     const ktRaw = base64UrlDecode(fragmentKey);
@@ -3048,7 +3048,7 @@ async function sealSeedToDevice(seed, devicePublicKeyB64) {
     const iv = crypto.getRandomValues(new Uint8Array(12));
     const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, key, seed));
     const envelope = { v: 2, epk: toBase64(epkRaw), iv: toBase64(iv), ct: toBase64(ct) };
-    return toBase64(TE.encode(JSON.stringify(envelope)));
+    return toBase64(TE$1.encode(JSON.stringify(envelope)));
 }
 /**
  * (Device side) Recover the master seed from a v2 envelope using the ephemeral
@@ -3064,7 +3064,7 @@ async function sealSeedToDevice(seed, devicePublicKeyB64) {
  * recipient matters. A device always holds both halves, so this costs nothing.
  */
 async function unsealSeedFromDevice(sealedKeys, privateKey, devicePublicKeyB64) {
-    const envelope = JSON.parse(TD.decode(fromBase64Loose(sealedKeys)));
+    const envelope = JSON.parse(TD$1.decode(fromBase64Loose(sealedKeys)));
     if (envelope.v !== 2)
         throw new Error(`Unsupported device-handoff envelope version ${envelope.v}`);
     const devicePubRaw = decodePairingPublicKey(devicePublicKeyB64);
@@ -3124,7 +3124,7 @@ async function pairingVerificationCode(devicePublicKeyB64) {
     const bits = new Uint8Array(await crypto.subtle.deriveBits({
         name: "PBKDF2",
         hash: "SHA-256",
-        salt: TE.encode(PAIRING_CODE_DOMAIN),
+        salt: TE$1.encode(PAIRING_CODE_DOMAIN),
         iterations: PAIRING_CODE_ITERATIONS,
     }, material, 256));
     // Rejection-sample so all 30 symbols are equally likely. 256 is not a
@@ -3171,7 +3171,7 @@ async function pairingVerificationCode(devicePublicKeyB64) {
 async function deriveDeviceSealKey(priv, pub, epkRaw, devicePubRaw, usages) {
     const shared = new Uint8Array(await crypto.subtle.deriveBits({ name: "ECDH", public: pub }, priv, 256));
     const prk = await crypto.subtle.importKey("raw", shared, { name: "HKDF" }, false, ["deriveBits"]);
-    const label = TE.encode(HKDF_INFO_V2);
+    const label = TE$1.encode(HKDF_INFO_V2);
     const info = new Uint8Array(label.length + devicePubRaw.length);
     info.set(label, 0);
     info.set(devicePubRaw, label.length);
@@ -3211,7 +3211,7 @@ function fromBase64Loose(s) {
 /** Generate a PKCE verifier + S256 challenge for the authorize→token exchange. */
 async function generatePkce() {
     const codeVerifier = base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
-    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", TE.encode(codeVerifier)));
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", TE$1.encode(codeVerifier)));
     return { codeVerifier, codeChallenge: base64UrlEncode(digest) };
 }
 /** A random URL-safe value for the OAuth `state` (CSRF binding on the callback). */
@@ -3233,7 +3233,7 @@ function base64UrlDecode(s) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.10.12-alpha.0";
+const VERSION = "0.10.13-alpha.0";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -3846,9 +3846,376 @@ async function evaluatePasskeyPrf(rpId, credentialId, salt) {
     return new Uint8Array(results.first);
 }
 
+/**
+ * `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).
+ */
+const TE = new TextEncoder();
+const TD = new TextDecoder();
+/** localStorage key holding the AES-GCM-sealed identity blob. */
+const DEVICE_IDENTITY_STORAGE_KEY = "muhkoo.tv.identity.v1";
+/** IndexedDB database holding the non-extractable keys. */
+const DEVICE_KEY_DB_NAME = "muhkoo.device.v1";
+const DEVICE_KEY_STORE = "keys";
+const WRAP_KEY_ID = "wrap";
+const IDENTITY_KEY_ID = "identity";
+/** Thrown when persistence is impossible (no IndexedDB and/or no localStorage). */
+class DeviceStoreUnavailableError extends Error {
+    constructor(what) {
+        super(`Device identity can't be persisted here: ${what}. ` +
+            "Pairing still works, but this device will have to pair again after a restart.");
+        this.name = "DeviceStoreUnavailableError";
+    }
+}
+let injectedKeys;
+let injectedBlobs;
+let injectedKeystore;
+/** Memoized so a pairing attempt and its follow-up touch use one keypair. */
+let identityMemo = null;
+let identityEphemeral = false;
+/**
+ * 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.
+ */
+function configureDeviceStore(opts = {}) {
+    injectedKeys = opts.keys;
+    injectedBlobs = opts.blobs;
+    injectedKeystore = opts.keystore;
+    identityMemo = null;
+    identityEphemeral = false;
+}
+/**
+ * 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).
+ */
+function deviceIdentityIsEphemeral() {
+    return identityEphemeral;
+}
+// ---- public API ------------------------------------------------------------
+/**
+ * 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.
+ */
+async function deviceIdentityKey() {
+    if (!identityMemo)
+        identityMemo = loadOrCreateIdentityKey();
+    try {
+        return await identityMemo;
+    }
+    catch (e) {
+        identityMemo = null; // don't cache a failure
+        throw e;
+    }
+}
+/** `base64url(SHA-256(raw SEC1 device identity public key))` — 43 chars. */
+async function deviceFingerprint() {
+    const pair = await deviceIdentityKey();
+    return fingerprintOf(pair.publicKey);
+}
+/** Whether a sealed identity blob exists. Cheap: no crypto, no IndexedDB, no network. */
+async function hasDeviceIdentity() {
+    return blobStore()?.get(DEVICE_IDENTITY_STORAGE_KEY) != null;
+}
+/**
+ * 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.
+ */
+async function persistDeviceIdentity(v) {
+    if (!(v?.seed instanceof Uint8Array) || v.seed.length !== 32) {
+        throw new Error("persistDeviceIdentity: expected a 32-byte seed.");
+    }
+    const blobs = blobStore();
+    if (!blobs)
+        throw new DeviceStoreUnavailableError("no localStorage");
+    const plain = TE.encode(JSON.stringify({
+        username: v.username,
+        commitment: v.commitment,
+        seed: toBase64(v.seed),
+        pairedAt: v.pairedAt,
+    }));
+    const bridge = keystoreBridge();
+    let envelope;
+    if (bridge) {
+        envelope = { v: 1, ks: 1, ct: await bridge.wrap(toBase64(plain)) };
+    }
+    else {
+        const key = await wrapKey(true);
+        if (!key)
+            throw new DeviceStoreUnavailableError("no IndexedDB for the wrapping key");
+        const iv = crypto.getRandomValues(new Uint8Array(12));
+        const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, key, plain));
+        envelope = { v: 1, iv: toBase64(iv), ct: toBase64(ct) };
+    }
+    blobs.set(DEVICE_IDENTITY_STORAGE_KEY, JSON.stringify(envelope));
+}
+/**
+ * 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.
+ */
+async function loadDeviceIdentity() {
+    const blobs = blobStore();
+    const raw = blobs?.get(DEVICE_IDENTITY_STORAGE_KEY);
+    if (!raw)
+        return null;
+    try {
+        const envelope = JSON.parse(raw);
+        if (envelope?.v !== 1)
+            return null;
+        let plain;
+        const bridge = keystoreBridge();
+        if (envelope.ks === 1) {
+            if (!bridge)
+                return null; // sealed by the native shell; nothing else can open it
+            plain = fromBase64(await bridge.unwrap(envelope.ct));
+        }
+        else {
+            const key = await wrapKey(false);
+            if (!key || !envelope.iv)
+                return null;
+            plain = new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64(envelope.iv) }, key, fromBase64(envelope.ct)));
+        }
+        const parsed = JSON.parse(TD.decode(plain));
+        if (!parsed?.username || !parsed?.commitment || !parsed?.seed)
+            return null;
+        const seed = fromBase64(parsed.seed);
+        if (seed.length !== 32)
+            return null;
+        return {
+            username: parsed.username,
+            commitment: parsed.commitment,
+            seed,
+            pairedAt: typeof parsed.pairedAt === "number" ? parsed.pairedAt : 0,
+        };
+    }
+    catch {
+        return 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).
+ */
+async function clearDeviceIdentity() {
+    identityMemo = null;
+    identityEphemeral = false;
+    try {
+        blobStore()?.remove(DEVICE_IDENTITY_STORAGE_KEY);
+    }
+    catch { /* nothing to remove */ }
+    try {
+        await keyVault()?.destroy();
+    }
+    catch { /* already gone */ }
+}
+async function fingerprintOf(publicKey) {
+    const raw = new Uint8Array(await crypto.subtle.exportKey("raw", publicKey));
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", raw));
+    return toBase64(digest).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function loadOrCreateIdentityKey() {
+    const vault = keyVault();
+    if (vault) {
+        const existing = (await vault.get(IDENTITY_KEY_ID));
+        if (existing?.privateKey && existing?.publicKey) {
+            identityEphemeral = false;
+            return existing;
+        }
+    }
+    // `extractable: false` applies to the PRIVATE half only — WebCrypto always
+    // allows exporting a public key, which is what the fingerprint needs.
+    const pair = (await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, false, ["sign", "verify"]));
+    if (vault) {
+        try {
+            await vault.put(IDENTITY_KEY_ID, pair);
+            identityEphemeral = false;
+            return pair;
+        }
+        catch { /* structured clone refused / quota — fall through */ }
+    }
+    // No durable home: keep it for this process only. Pairing still works; the
+    // device just won't be recognised next boot.
+    identityEphemeral = true;
+    return pair;
+}
+/**
+ * The AES-GCM wrapping key. `create` generates + stores one when absent;
+ * otherwise a missing key means the blob is unopenable (return null, not throw).
+ */
+async function wrapKey(create) {
+    const vault = keyVault();
+    if (!vault)
+        return null;
+    const existing = (await vault.get(WRAP_KEY_ID));
+    if (existing)
+        return existing;
+    if (!create)
+        return null;
+    const key = await crypto.subtle.generateKey({ name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+    await vault.put(WRAP_KEY_ID, key);
+    return key;
+}
+function keystoreBridge() {
+    if (injectedKeystore !== undefined)
+        return injectedKeystore;
+    const ks = globalThis.MuhkooKeystore;
+    return typeof ks?.wrap === "function" && typeof ks?.unwrap === "function" ? ks : null;
+}
+function blobStore() {
+    if (injectedBlobs !== undefined)
+        return injectedBlobs;
+    try {
+        const ls = globalThis.localStorage;
+        if (!ls)
+            return null;
+        ls.getItem("muhkoo.__probe__"); // Safari private mode throws on access, not on typeof
+        return {
+            get: (k) => ls.getItem(k),
+            set: (k, v) => ls.setItem(k, v),
+            remove: (k) => ls.removeItem(k),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function keyVault() {
+    if (injectedKeys !== undefined)
+        return injectedKeys;
+    const idb = globalThis.indexedDB;
+    if (!idb)
+        return null;
+    return indexedDbVault(idb);
+}
+/** Minimal promise wrapper over one object store. Opened per operation — these
+ *  are cold-start-rare calls, and holding a connection open would block the
+ *  `deleteDatabase` that `clearDeviceIdentity` needs to win. */
+function indexedDbVault(idb) {
+    const open = () => new Promise((resolve, reject) => {
+        const req = idb.open(DEVICE_KEY_DB_NAME, 1);
+        req.onupgradeneeded = () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(DEVICE_KEY_STORE))
+                db.createObjectStore(DEVICE_KEY_STORE);
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+        req.onblocked = () => reject(new Error("IndexedDB open blocked"));
+    });
+    return {
+        async get(id) {
+            const db = await open();
+            try {
+                return await new Promise((resolve, reject) => {
+                    const req = db.transaction(DEVICE_KEY_STORE, "readonly").objectStore(DEVICE_KEY_STORE).get(id);
+                    req.onsuccess = () => resolve(req.result ?? null);
+                    req.onerror = () => reject(req.error);
+                });
+            }
+            finally {
+                db.close();
+            }
+        },
+        async put(id, value) {
+            const db = await open();
+            try {
+                await new Promise((resolve, reject) => {
+                    const tx = db.transaction(DEVICE_KEY_STORE, "readwrite");
+                    tx.objectStore(DEVICE_KEY_STORE).put(value, id);
+                    tx.oncomplete = () => resolve();
+                    tx.onerror = () => reject(tx.error);
+                    tx.onabort = () => reject(tx.error);
+                });
+            }
+            finally {
+                db.close();
+            }
+        },
+        destroy() {
+            return new Promise((resolve, reject) => {
+                const req = idb.deleteDatabase(DEVICE_KEY_DB_NAME);
+                req.onsuccess = () => resolve();
+                req.onerror = () => reject(req.error);
+                // A live connection elsewhere would block the delete; the blob is
+                // already gone by then, so don't hang the sign-out on it.
+                req.onblocked = () => resolve();
+            });
+        },
+    };
+}
+
 /**
  * `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
@@ -3864,8 +4231,98 @@ async function evaluatePasskeyPrf(rpId, credentialId, salt) {
  *   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).
  */
 const PKCE_STORE_KEY = "muhkoo.hosted.pkce";
+// ---- device pairing: constants (tv-device-pairing-spec.md §4.5, §9) --------
+/** RFC-8628-style backoff step applied on every `slow_down` (spec §9.1). */
+const SLOW_DOWN_STEP_S = 5;
+/** Ceiling for the transport-failure backoff, so a flaky TV Wi-Fi still recovers. */
+const MAX_BACKOFF_INTERVAL_S = 30;
+/** Consecutive transport failures tolerated before giving up on a pairing. */
+const MAX_CONSECUTIVE_NETWORK_ERRORS = 5;
+/** Server-sanitized anyway; clipped here so the request is never rejected for it. */
+const DEVICE_LABEL_MAX = 64;
+/** §4.4 signing-input prefixes. Changing either breaks server verification. */
+const DEVICE_PAIR_SIG_PREFIX = "muhkoo-device-pair-v1";
+const DEVICE_TOUCH_SIG_PREFIX = "muhkoo-device-touch-v1";
+/**
+ * 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`.
+ */
+class DevicePairingError extends Error {
+    reason;
+    /** Machine code from the error envelope (`{error, message}`), when there was one. */
+    code;
+    status;
+    /** Seconds, from `Retry-After`, when the server sent one. */
+    retryAfter;
+    /** Any extra fields the error envelope carried (e.g. `version`). */
+    details;
+    constructor(reason, opts = {}) {
+        super(opts.message ?? DEFAULT_PAIRING_MESSAGES[reason]);
+        this.name = "DevicePairingError";
+        this.reason = reason;
+        this.code = opts.code;
+        this.status = opts.status;
+        this.retryAfter = opts.retryAfter;
+        this.details = opts.details;
+        if (opts.cause !== undefined)
+            this.cause = opts.cause;
+    }
+}
+const DEFAULT_PAIRING_MESSAGES = {
+    denied: "Sign-in was declined on the other device.",
+    expired: "That code expired. Get a new code and try again.",
+    aborted: "Pairing was cancelled.",
+    rate_limited: "Too many attempts — wait a moment and start again.",
+    network: "Couldn't reach Muhkoo. Check the connection and try again.",
+    commitment_mismatch: "The account handed back doesn't match the key material — pairing aborted. " +
+        "Do not sign in on this device; report it.",
+    account_mismatch: "This device was previously signed in as a different account.",
+    reauth_required: "Confirm it's you before approving a new device.",
+    invalid_user_code: `Codes are ${PAIRING_CODE_LENGTH} characters from ${PAIRING_CODE_ALPHABET} — no O, I, L, U, 0 or 1.`,
+    error: "Device pairing failed.",
+};
+/**
+ * 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.
+ */
+class ReauthRequiredError extends DevicePairingError {
+    /** How long ago the approver's session authenticated, in seconds. */
+    authAgeSeconds;
+    /** The freshness window the server enforces, in seconds. */
+    maxAgeSeconds;
+    constructor(opts = {}) {
+        super("reauth_required", { message: opts.message, code: "reauth_required", status: opts.status ?? 401 });
+        this.name = "ReauthRequiredError";
+        this.authAgeSeconds = opts.authAgeSeconds;
+        this.maxAgeSeconds = opts.maxAgeSeconds;
+    }
+}
 class HostedAuth {
     deps;
     constructor(deps) {
@@ -3963,6 +4420,561 @@ class HostedAuth {
         url.hash = `k=${fragmentKey}`;
         return url.toString();
     }
+    // =========================================================================
+    // Device pairing — device (TV) side
+    // =========================================================================
+    /**
+     * (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).
+     */
+    async startDevicePairing(opts) {
+        if (!opts?.appId)
+            throw new DevicePairingError("error", { message: "startDevicePairing: `appId` is required." });
+        const pairing = await generateDevicePairingKeypair();
+        const identityKey = await deviceIdentityKey();
+        const deviceIdentityKeyB64 = await exportPublicKeyBase64(identityKey.publicKey);
+        const issuedAt = Date.now();
+        const signature = await signMessage([DEVICE_PAIR_SIG_PREFIX, opts.appId, pairing.publicKeyB64, String(issuedAt)].join("|"), identityKey.privateKey);
+        const res = await this.deviceApi("POST", "/api/auth/device/code", {
+            app_id: opts.appId,
+            device_public_key: pairing.publicKeyB64,
+            device_identity_key: deviceIdentityKeyB64,
+            device_signature: signature,
+            issued_at: issuedAt,
+            device_label: (opts.label ?? defaultDeviceLabel()).slice(0, DEVICE_LABEL_MAX),
+        });
+        this.throwForStatus(res);
+        const body = res.body;
+        if (!body?.device_code || !body?.user_code) {
+            throw new DevicePairingError("error", { message: "Device pairing start returned no code." });
+        }
+        const expiresIn = numberOr(body.expires_in, 600);
+        const verificationUri = body.verification_uri || `${this.deps.authBaseUrl}/link`;
+        return {
+            deviceCode: body.device_code,
+            userCode: body.user_code,
+            // LOCAL derivation — never `body.verification_code`.
+            verificationCode: await pairingVerificationCode(pairing.publicKeyB64),
+            verificationUri,
+            verificationUriComplete: body.verification_uri_complete
+                || `${verificationUri}?code=${encodeURIComponent(body.user_code)}`,
+            expiresAt: Date.now() + expiresIn * 1000,
+            interval: numberOr(body.interval, 5),
+            privateKey: pairing.privateKey,
+            devicePublicKeyB64: pairing.publicKeyB64,
+        };
+    }
+    /**
+     * (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.
+     */
+    async pollDevicePairing(session) {
+        this.assertLive(session);
+        const res = await this.deviceApi("POST", "/api/auth/device/token", { device_code: session.deviceCode });
+        if (res.status === 429 && res.code === "slow_down") {
+            const interval = numberOr(res.body?.interval, session.interval + SLOW_DOWN_STEP_S);
+            return { status: "slow_down", interval, retryAfter: res.retryAfter ?? interval };
+        }
+        // `expired_token` is deliberately uniform server-side for unknown /
+        // expired / already-redeemed codes, so all three land here.
+        if (res.status === 401 && res.code === "expired_token")
+            return { status: "expired" };
+        if (res.status === 403 && res.code === "access_denied")
+            return { status: "denied" };
+        this.throwForStatus(res);
+        const body = res.body;
+        if (body?.status === "pending") {
+            return {
+                status: "pending",
+                interval: numberOr(body.interval, session.interval),
+                expiresIn: numberOr(body.expires_in, Math.max(0, Math.round((session.expiresAt - Date.now()) / 1000))),
+            };
+        }
+        if (body?.status === "denied")
+            return { status: "denied" };
+        if (body?.status === "expired")
+            return { status: "expired" };
+        if (body?.status !== "approved") {
+            throw new DevicePairingError("error", { message: `Unexpected pairing status "${body?.status}".` });
+        }
+        if (!body.sealed_keys || !body.username || !body.commitment) {
+            throw new DevicePairingError("error", { message: "Approved pairing was missing its sealed payload." });
+        }
+        const user = await this.adoptSealedSeed(session, {
+            sealedKeys: body.sealed_keys,
+            username: body.username,
+            commitment: body.commitment,
+        });
+        return { status: "approved", user };
+    }
+    /**
+     * (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}.
+     */
+    async waitForDevicePairing(session, opts = {}) {
+        let interval = session.interval;
+        let consecutiveNetworkErrors = 0;
+        for (;;) {
+            if (opts.signal?.aborted)
+                throw new DevicePairingError("aborted");
+            this.assertLive(session);
+            const remaining = session.expiresAt - Date.now();
+            if (remaining <= 0)
+                throw new DevicePairingError("expired");
+            opts.onTick?.(remaining, interval);
+            const jitter = 1 + (Math.random() * 0.2 - 0.1);
+            await this.sleep(Math.min(interval * 1000 * jitter, remaining), opts.signal);
+            let result;
+            try {
+                result = await this.pollDevicePairing(session);
+                consecutiveNetworkErrors = 0;
+            }
+            catch (e) {
+                // A protocol verdict (denied, budget exhausted, a failed
+                // commitment check) is terminal — it must NOT be swallowed by the
+                // transport-retry arm the way the spec's reference loop would.
+                if (e instanceof DevicePairingError)
+                    throw e;
+                // Transport failure: a TV's Wi-Fi drops constantly, and the
+                // pairing stays valid server-side until it expires. Back off.
+                if (++consecutiveNetworkErrors > MAX_CONSECUTIVE_NETWORK_ERRORS) {
+                    throw new DevicePairingError("network", { cause: e });
+                }
+                interval = Math.min(interval * 2, MAX_BACKOFF_INTERVAL_S);
+                continue;
+            }
+            switch (result.status) {
+                case "pending":
+                    interval = result.interval; // server-authoritative
+                    break;
+                case "slow_down":
+                    interval = Math.max(result.interval, interval + SLOW_DOWN_STEP_S, result.retryAfter);
+                    break;
+                case "approved":
+                    return result.user;
+                case "denied":
+                    throw new DevicePairingError("denied");
+                case "expired":
+                    throw new DevicePairingError("expired");
+            }
+        }
+    }
+    /**
+     * (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) {
+        if (!session)
+            return;
+        cancelledPairings.add(session);
+        session.deviceCode = "";
+    }
+    /**
+     * (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.
+     */
+    async resumeDeviceSession() {
+        const persisted = await loadDeviceIdentity();
+        if (!persisted)
+            return null;
+        try {
+            const identity = await deriveIdentityFromSeed(persisted.seed);
+            const commitment = await commitmentFor(identity);
+            // Storage integrity: the seed must still derive the commitment it was
+            // stored with. A mismatch means the blob was swapped, not that the
+            // account changed — refuse it rather than authenticate as someone else.
+            if (commitment !== persisted.commitment)
+                return null;
+            const user = await this.mintSession(persisted.username, identity, persisted.seed, { rememberMe: true });
+            await this.touchPairedDevice();
+            return user;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** (Device side) Wipe the persisted seed, the device identity key, and the session. */
+    async forgetDeviceSession() {
+        await clearDeviceIdentity();
+        await this.deps.session.clear();
+    }
+    /** (Device side) Whether a persisted device identity exists. Cheap: no crypto, no network. */
+    async hasDeviceSession() {
+        return hasDeviceIdentity();
+    }
+    // =========================================================================
+    // Device pairing — approver (hosted page) side
+    // =========================================================================
+    /**
+     * (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.
+     */
+    async lookupDevicePairing(userCode) {
+        const code = formatUserCode(canonicalUserCode(userCode));
+        const res = await this.deviceApi("POST", "/api/auth/device/lookup", { user_code: code }, true);
+        this.throwForStatus(res);
+        const body = res.body;
+        if (!body?.device_public_key) {
+            throw new DevicePairingError("error", { message: "Pairing lookup returned no device key." });
+        }
+        const isKnown = body.is_known_device === true;
+        return {
+            userCode: body.user_code || code,
+            devicePublicKeyB64: body.device_public_key,
+            verificationCode: await pairingVerificationCode(body.device_public_key),
+            deviceFingerprint: body.device_fingerprint ?? "",
+            deviceLabel: body.device_label ?? "TV",
+            appId: body.app_id ?? "",
+            appLabel: body.app_label ?? "",
+            isKnownDevice: isKnown,
+            requiresReauth: body.requires_reauth ?? !isKnown,
+            expiresAt: Date.now() + numberOr(body.expires_in, 0) * 1000,
+        };
+    }
+    /**
+     * (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`.
+     */
+    async approveDevicePairing(req, opts = {}) {
+        const seed = this.deps.session.seed;
+        if (!this.deps.session.token || !seed) {
+            throw new DevicePairingError("error", { message: "Authenticate the user before approving a device." });
+        }
+        if (!req?.devicePublicKeyB64) {
+            throw new DevicePairingError("error", { message: "approveDevicePairing: the request has no device key." });
+        }
+        const code = formatUserCode(canonicalUserCode(req.userCode));
+        const sealedKeys = await sealSeedToDevice(seed, req.devicePublicKeyB64);
+        const res = await this.deviceApi("POST", "/api/auth/device/approve", {
+            user_code: code,
+            device_public_key: req.devicePublicKeyB64,
+            sealed_keys: sealedKeys,
+            device_label: (opts.label ?? req.deviceLabel ?? "").slice(0, DEVICE_LABEL_MAX) || undefined,
+        }, true);
+        this.throwForStatus(res);
+        return { deviceId: String(res.body?.device_id ?? req.deviceFingerprint ?? "") };
+    }
+    /**
+     * (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".
+     */
+    async denyDevicePairing(userCode) {
+        const code = formatUserCode(canonicalUserCode(userCode));
+        const res = await this.deviceApi("POST", "/api/auth/device/deny", { user_code: code }, true);
+        this.throwForStatus(res);
+    }
+    // =========================================================================
+    // Device pairing — paired-device management
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async listPairedDevices() {
+        const res = await this.deviceApi("GET", "/api/auth/devices", undefined, true);
+        this.throwForStatus(res);
+        const rows = res.body?.devices ?? [];
+        return rows.map((raw) => {
+            const d = raw;
+            return {
+                id: d.id ?? "",
+                label: d.label ?? "",
+                appId: d.app_id ?? "",
+                pairedAt: numberOr(d.paired_at, 0),
+                lastSeenAt: numberOr(d.last_seen_at, 0),
+                activeSession: d.active_session === true,
+            };
+        });
+    }
+    /** Remove a paired device and revoke its session. Session-authed. */
+    async revokePairedDevice(id) {
+        if (!id)
+            throw new DevicePairingError("error", { message: "revokePairedDevice: `id` is required." });
+        const res = await this.deviceApi("DELETE", "/api/auth/devices", { id }, true);
+        this.throwForStatus(res);
+    }
+    // ---- device pairing internals -------------------------------------------
+    /**
+     * 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.
+     */
+    async adoptSealedSeed(session, payload) {
+        let seed;
+        try {
+            seed = await unsealSeedFromDevice(payload.sealedKeys, session.privateKey, session.devicePublicKeyB64);
+        }
+        catch (e) {
+            throw new DevicePairingError("commitment_mismatch", {
+                message: "The sealed key material couldn't be opened on this device — pairing aborted.",
+                cause: e,
+            });
+        }
+        const identity = await deriveIdentityFromSeed(seed);
+        const commitment = await commitmentFor(identity);
+        // §10.8, mandatory: the seed we were handed must derive the commitment the
+        // server claims. A compromised API can seal an attacker-controlled seed to
+        // this device (§10.2) — this is the check that makes that loud.
+        if (commitment !== payload.commitment) {
+            throw new DevicePairingError("commitment_mismatch", {
+                details: { expected: payload.commitment, derived: commitment },
+            });
+        }
+        // §10.2 detection 2 — commitment pinning across re-pairs. A device that
+        // was signed in as someone else must fail closed, not silently switch.
+        const pinned = await loadDeviceIdentity();
+        if (pinned && pinned.commitment !== commitment) {
+            throw new DevicePairingError("account_mismatch", {
+                details: { pinnedUsername: pinned.username, offeredUsername: payload.username },
+            });
+        }
+        // The device mints its OWN session rather than sharing the approver's, so
+        // revoking the TV doesn't sign out the phone that approved it.
+        const user = await this.mintSession(payload.username, identity, seed, { rememberMe: true });
+        // Both are best-effort: the user IS signed in at this point, and failing
+        // the whole pairing over a bookkeeping call would be worse than degrading.
+        await this.touchPairedDevice();
+        try {
+            await persistDeviceIdentity({ username: user.username, commitment, seed, pairedAt: Date.now() });
+        }
+        catch (e) {
+            appLoggerWarn("device identity could not be persisted; this device will pair again after a restart", e);
+        }
+        return user;
+    }
+    /**
+     * 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.)
+     */
+    async mintSession(username, identity, seed, opts = {}) {
+        const ecdsaPubHex = await exportPublicKeyHex(identity.ecdsaKeyPair.publicKey);
+        const challenge = await this.deps.auth.getChallenge(username);
+        const { proof, publicSignals, commitment } = await generateAuthProof({
+            secretHex: identity.secretHex,
+            saltHex: identity.saltHex,
+            ecdsaPubHex,
+            nonceHex: challenge.nonce,
+            circuits: this.circuits(),
+        });
+        const signature = await signMessage(JSON.stringify(proof), identity.ecdsaKeyPair.privateKey);
+        const result = await this.deps.auth.authenticate({
+            challengeId: challenge.challengeId,
+            proof: {
+                commitment,
+                // The accelerator expects the original hex nonce, not the
+                // field-reduced version fed into the circuit.
+                nonce: challenge.nonce,
+                response: { proof, publicSignals },
+                signature,
+            },
+            rememberMe: opts.rememberMe,
+        });
+        await this.deps.session.setSession({ token: result.token, username: result.username, commitment });
+        this.deps.session.setIdentity(identity);
+        this.deps.session.setSeed(seed);
+        return { username: result.username, commitment };
+    }
+    /**
+     * `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.
+     */
+    async touchPairedDevice() {
+        try {
+            const identityKey = await deviceIdentityKey();
+            const fingerprint = await deviceFingerprint();
+            const issuedAt = Date.now();
+            const signature = await signMessage([DEVICE_TOUCH_SIG_PREFIX, fingerprint, String(issuedAt)].join("|"), identityKey.privateKey);
+            await this.deviceApi("PUT", "/api/auth/devices", {
+                fingerprint,
+                issued_at: issuedAt,
+                device_signature: signature,
+            }, true);
+        }
+        catch (e) {
+            appLoggerWarn("device check-in failed", e);
+        }
+    }
+    /** Reject a session that {@link cancelDevicePairing} has retired. */
+    assertLive(session) {
+        if (!session || cancelledPairings.has(session) || !session.deviceCode) {
+            throw new DevicePairingError("aborted");
+        }
+    }
+    sleep(ms, signal) {
+        if (this.deps.sleep)
+            return this.deps.sleep(ms, signal);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, ms);
+            const onAbort = () => {
+                clearTimeout(timer);
+                reject(new DevicePairingError("aborted"));
+            };
+            if (signal?.aborted)
+                return onAbort();
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    /**
+     * 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}.
+     */
+    async deviceApi(method, path, body, withSession = false) {
+        const headers = {};
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (withSession) {
+            const token = this.deps.session.token;
+            if (!token)
+                throw new DevicePairingError("error", { code: "unauthorized", status: 401, message: "Sign in first." });
+            // X-Muhkoo-Session, not `Authorization: Bearer` — the accelerator's
+            // session resolver prefers it and raw SPA fetches must use it.
+            headers["X-Muhkoo-Session"] = token;
+        }
+        const fetchFn = this.deps.fetch ?? globalThis.fetch?.bind(globalThis);
+        if (typeof fetchFn !== "function")
+            throw new Error("HostedAuth: no fetch available.");
+        const res = await fetchFn(`${this.apiBase()}${path}`, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        let parsed = null;
+        try {
+            parsed = await res.json();
+        }
+        catch { /* empty or non-JSON body */ }
+        const envelope = (parsed ?? {});
+        const retryAfterHeader = Number(res.headers?.get?.("Retry-After"));
+        return {
+            status: res.status,
+            ok: res.ok,
+            body: parsed,
+            code: res.ok || typeof envelope.error !== "string" ? undefined : envelope.error,
+            message: typeof envelope.message === "string"
+                ? envelope.message
+                : typeof envelope.error === "string" ? envelope.error : undefined,
+            retryAfter: Number.isFinite(retryAfterHeader) && retryAfterHeader > 0 ? retryAfterHeader : null,
+        };
+    }
+    /** Turn a non-2xx device-endpoint response into the right typed error. */
+    throwForStatus(res) {
+        if (res.ok)
+            return;
+        const details = (res.body ?? undefined);
+        if (res.code === "reauth_required") {
+            throw new ReauthRequiredError({
+                message: res.message,
+                status: res.status,
+                authAgeSeconds: numberOrUndefined(details?.auth_age_seconds),
+                maxAgeSeconds: numberOrUndefined(details?.max_age_seconds),
+            });
+        }
+        throw new DevicePairingError(reasonForCode(res.code, res.status), {
+            message: res.message,
+            code: res.code,
+            status: res.status,
+            retryAfter: res.retryAfter ?? undefined,
+            details,
+        });
+    }
+    /**
+     * 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.…`).
+     */
+    apiBase() {
+        const explicit = this.deps.apiBaseUrl;
+        if (explicit)
+            return explicit.replace(/\/+$/, "");
+        const fromAuthClient = this.deps.auth?.baseUrl;
+        if (typeof fromAuthClient === "string" && fromAuthClient)
+            return fromAuthClient.replace(/\/+$/, "");
+        try {
+            const url = new URL(this.deps.authBaseUrl);
+            url.hostname = url.hostname.replace(/^auth\./, "api.");
+            url.pathname = "";
+            return url.toString().replace(/\/+$/, "");
+        }
+        catch {
+            throw new Error("HostedAuth: can't resolve the accelerator base URL — pass `apiBaseUrl`.");
+        }
+    }
+    circuits() {
+        return this.deps.circuits ?? defaultCircuitUrls(this.apiBase());
+    }
     // ---- internals ----------------------------------------------------------
     location() {
         const loc = globalThis.location;
@@ -3999,6 +5011,92 @@ class HostedAuth {
             h.replaceState(null, "", loc.pathname);
     }
 }
+// ---- device pairing: module helpers ----------------------------------------
+/** Sessions retired by {@link HostedAuth.cancelDevicePairing}. Weak so a dropped
+ *  session is collectable — this must not become a leak on a device that runs
+ *  for months. */
+const cancelledPairings = new WeakSet();
+/**
+ * Map a server error code to the reason the device's state machine branches on.
+ * Codes with no dedicated reason land on `"error"` and stay readable through
+ * {@link DevicePairingError.code}.
+ */
+function reasonForCode(code, status) {
+    switch (code) {
+        case "expired_token":
+        case "pairing_not_found":
+            return "expired";
+        case "access_denied":
+            return "denied";
+        case "slow_down":
+        case "rate_limited":
+        case "too_many_requests":
+            return "rate_limited";
+        case "reauth_required":
+            return "reauth_required";
+        case "invalid_user_code":
+            return "invalid_user_code";
+        default:
+            return status === 429 ? "rate_limited" : "error";
+    }
+}
+/**
+ * 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.
+ */
+function canonicalUserCode(input) {
+    const code = String(input ?? "").toUpperCase().replace(/[\s-]/g, "");
+    if (code.length !== PAIRING_CODE_LENGTH)
+        throw new DevicePairingError("invalid_user_code");
+    for (const ch of code) {
+        if (!PAIRING_CODE_ALPHABET.includes(ch))
+            throw new DevicePairingError("invalid_user_code");
+    }
+    return code;
+}
+/** Group a canonical code for display and for the wire: `"K7QD3MXR"` → `"K7QD-3MXR"`. */
+function formatUserCode(canonical) {
+    const half = Math.ceil(canonical.length / 2);
+    return `${canonical.slice(0, half)}-${canonical.slice(half)}`;
+}
+/** Poseidon commitment for an identity — the value the server stores. */
+async function commitmentFor(identity) {
+    const ecdsaPubHex = await exportPublicKeyHex(identity.ecdsaKeyPair.publicKey);
+    return buildCommitment(identity.secretHex, identity.saltHex, ecdsaPubHex);
+}
+/**
+ * A label the approver can recognise, guessed from the user agent. Android TV
+ * user agents are famously uninformative, so this is a coarse family name —
+ * §6.4 lets the approver rename the device at approval time.
+ */
+function defaultDeviceLabel() {
+    const ua = globalThis.navigator?.userAgent ?? "";
+    if (/AFT[A-Z]/i.test(ua))
+        return "Fire TV";
+    if (/Android.*TV|GoogleTV|Chromecast/i.test(ua))
+        return "Android TV";
+    if (/AppleTV|tvOS/i.test(ua))
+        return "Apple TV";
+    if (/Tizen|Web0S|WebOS|SMART-TV|BRAVIA|HbbTV|NetCast/i.test(ua))
+        return "Smart TV";
+    return "TV";
+}
+function numberOr(v, fallback) {
+    return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+function numberOrUndefined(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+/** Non-fatal diagnostics. The SDK logger is optional, so never let it throw. */
+function appLoggerWarn(message, err) {
+    try {
+        globalThis.appLogger?.warn?.(`[hosted-auth] ${message}:`, err instanceof Error ? err.message : err);
+    }
+    catch { /* diagnostics must never break the flow */ }
+}
 
 /**
  * `client.auth` — user authentication, exposed today through the `zk`
@@ -4650,7 +5748,18 @@ class AuthNamespace {
     hosted;
     constructor(deps) {
         this.zk = new ZkAuth(deps);
-        this.hosted = new HostedAuth({ auth: deps.auth, session: deps.session, authBaseUrl: deps.authBaseUrl });
+        this.hosted = new HostedAuth({
+            auth: deps.auth,
+            session: deps.session,
+            authBaseUrl: deps.authBaseUrl,
+            // Forwarded explicitly so device pairing resolves the accelerator
+            // origin and the circuit assets the SAME way the rest of the client
+            // does. Without these, `HostedAuth` falls back to reading
+            // `AuthClient.baseUrl` reflectively and to `defaultCircuitUrls`,
+            // which silently ignores an app's `ClientOptions.circuits` override.
+            apiBaseUrl: deps.apiBaseUrl,
+            circuits: deps.circuits,
+        });
     }
     /** Convenience pass-through: the currently signed-in user, or `null`. */
     get user() {
@@ -11530,7 +12639,11 @@ class Client {
         const authClient = new AuthClient({ baseUrl: this.baseUrl, fetch: this.http.fetch });
         const wsBaseUrl = toWsBase(this.baseUrl);
         const authBaseUrl = (options.authBaseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/+$/, "");
-        this.auth = new AuthNamespace({ auth: authClient, circuits, session: this.session, authBaseUrl });
+        this.auth = new AuthNamespace({
+            auth: authClient, circuits, session: this.session, authBaseUrl,
+            // The accelerator origin, for `auth.hosted`'s device-pairing endpoints.
+            apiBaseUrl: this.baseUrl,
+        });
         const deferShardUpload = offlineEnabled
             ? (hash) => this.offline.deferShardUpload(hash)
             : undefined;
@@ -12488,5 +13601,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
     default: loadRsWasm
 });
 
-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_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbCache, DbNamespace, DbTable, 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, Logger, 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, Ready, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VERSION, VaultUnavailableError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, compareHlc, compilePrograms, concatBytes, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, fromBase64$1 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateDevicePairingKeypair, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isP2pCapable, isProvisional, log, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, pairingVerificationCode, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, serialize, shardHash, signMessage, stableStringify, toBase64$1 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
+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_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DEVICE_IDENTITY_STORAGE_KEY, DEVICE_KEY_DB_NAME, DbCache, DbNamespace, DbTable, 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, Logger, 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, Ready, ReauthRequiredError, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VERSION, VaultUnavailableError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, canonicalUserCode, clearDeviceIdentity, compareHlc, compilePrograms, concatBytes, configureDeviceStore, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, deviceFingerprint, deviceIdentityIsEphemeral, deviceIdentityKey, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, formatUserCode, fromBase64$1 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateDevicePairingKeypair, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, hasDeviceIdentity, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isP2pCapable, isProvisional, loadDeviceIdentity, log, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, pairingVerificationCode, persistDeviceIdentity, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, serialize, shardHash, signMessage, stableStringify, toBase64$1 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
 //# sourceMappingURL=index.js.map