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

package/dist/browser/index.js

@@ -5022,6 +5022,29 @@ function fromBase64(b64) {
  * 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).
  */
 const TE = new TextEncoder();
 const TD = new TextDecoder();
@@ -5047,6 +5070,236 @@ async function unsealSeed(sealedKeys, fragmentKey) {
     const seed = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64(envelope.iv) }, key, fromBase64(envelope.ct));
     return new Uint8Array(seed);
 }
+// ---- v2: ECDH device pairing ----------------------------------------------
+//
+// Deliberately a SEPARATE unseal entry point rather than one `unsealSeed` that
+// dispatches on `envelope.v`. The two versions do not just differ in envelope
+// shape — their *second argument* is a different kind of thing entirely (v1: a
+// base64url string plucked out of a URL fragment; v2: a non-extractable
+// `CryptoKey`). Overloading one function on a `string | CryptoKey` union would
+// buy nothing at the call sites (each caller statically knows which flow it is
+// in) while adding a narrowing branch to the v1 path, which is live in
+// production hosted auth. Each function still validates `v` and rejects the
+// other version's envelope, so a mis-routed envelope fails loudly rather than
+// being interpreted under the wrong scheme.
+/** P-256 curve parameters for the pairing ECDH. */
+const PAIRING_CURVE = { name: "ECDH", namedCurve: "P-256" };
+/**
+ * HKDF `info` for the v2 seal. Versioned and domain-separated: v1 derives no
+ * key at all (K_t is raw random), so no v1 key can ever collide with this, and
+ * a future v3 must pick a new label rather than reuse this one.
+ */
+const HKDF_INFO_V2 = "muhkoo/hosted-handoff/v2/device-seal";
+/** Domain separator for {@link pairingVerificationCode} — distinct from the seal KDF. */
+const PAIRING_CODE_DOMAIN = "muhkoo/hosted-handoff/v2/pairing-code";
+/**
+ * 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.
+ */
+const PAIRING_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTVWXYZ23456789";
+/** Length of the pairing verification code, in characters. 30^8 ≈ 39.3 bits. */
+const PAIRING_CODE_LENGTH = 8;
+/**
+ * PBKDF2 iterations for the verification code. This is NOT protecting a
+ * password — it is a deliberate work factor on an attacker precomputing codes.
+ * See {@link pairingVerificationCode}.
+ */
+const PAIRING_CODE_ITERATIONS = 200_000;
+/**
+ * (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.
+ */
+async function generateDevicePairingKeypair() {
+    const pair = (await crypto.subtle.generateKey(PAIRING_CURVE, false, ["deriveBits"]));
+    const raw = new Uint8Array(await crypto.subtle.exportKey("raw", pair.publicKey));
+    return { publicKeyB64: toBase64(raw), privateKey: pair.privateKey };
+}
+/**
+ * (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.
+ */
+async function sealSeedToDevice(seed, devicePublicKeyB64) {
+    const devicePubRaw = decodePairingPublicKey(devicePublicKeyB64);
+    const devicePub = await importPairingPublicKey(devicePubRaw);
+    const ephemeral = (await crypto.subtle.generateKey(PAIRING_CURVE, false, ["deriveBits"]));
+    const epkRaw = new Uint8Array(await crypto.subtle.exportKey("raw", ephemeral.publicKey));
+    const key = await deriveDeviceSealKey(ephemeral.privateKey, devicePub, epkRaw, devicePubRaw, ["encrypt"]);
+    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)));
+}
+/**
+ * (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.
+ */
+async function unsealSeedFromDevice(sealedKeys, privateKey, devicePublicKeyB64) {
+    const envelope = JSON.parse(TD.decode(fromBase64Loose(sealedKeys)));
+    if (envelope.v !== 2)
+        throw new Error(`Unsupported device-handoff envelope version ${envelope.v}`);
+    const devicePubRaw = decodePairingPublicKey(devicePublicKeyB64);
+    const epkRaw = decodePairingPublicKey(envelope.epk);
+    const epk = await importPairingPublicKey(epkRaw);
+    const key = await deriveDeviceSealKey(privateKey, epk, epkRaw, devicePubRaw, ["decrypt"]);
+    const seed = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64Loose(envelope.iv) }, key, fromBase64Loose(envelope.ct));
+    return new Uint8Array(seed);
+}
+/**
+ * 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.
+ */
+async function pairingVerificationCode(devicePublicKeyB64) {
+    const pubRaw = decodePairingPublicKey(devicePublicKeyB64);
+    const material = await crypto.subtle.importKey("raw", pubRaw, { name: "PBKDF2" }, false, [
+        "deriveBits",
+    ]);
+    // Enough bytes that rejection sampling (below) effectively never runs dry:
+    // each byte is rejected with p = 16/256, so 32 bytes yields 8 symbols with
+    // overwhelming probability.
+    const bits = new Uint8Array(await crypto.subtle.deriveBits({
+        name: "PBKDF2",
+        hash: "SHA-256",
+        salt: TE.encode(PAIRING_CODE_DOMAIN),
+        iterations: PAIRING_CODE_ITERATIONS,
+    }, material, 256));
+    // Rejection-sample so all 30 symbols are equally likely. 256 is not a
+    // multiple of 30, so a plain modulo would over-weight the first 16 symbols.
+    const n = PAIRING_CODE_ALPHABET.length;
+    const limit = Math.floor(256 / n) * n; // 240
+    let out = "";
+    for (let i = 0; i < bits.length && out.length < PAIRING_CODE_LENGTH; i++) {
+        if (bits[i] >= limit)
+            continue;
+        out += PAIRING_CODE_ALPHABET[bits[i] % n];
+    }
+    if (out.length < PAIRING_CODE_LENGTH) {
+        // Astronomically unlikely (p < 2^-40); fail loudly rather than return a
+        // short code that two screens would still "agree" on.
+        throw new Error("Pairing code derivation ran out of entropy.");
+    }
+    // Grouped for human comparison — the format the spec and both UIs display.
+    return out.slice(0, 4) + "-" + out.slice(4);
+}
+// ---- v2 internals ----------------------------------------------------------
+/**
+ * ECDH → HKDF-SHA256 → AES-256-GCM key.
+ *
+ * The raw ECDH output is never used as a key directly; it is extracted+expanded
+ * with BOTH public keys mixed in:
+ *
+ *   - the sender's ephemeral key as HKDF **salt**, and
+ *   - the recipient's device key appended to the HKDF **info**.
+ *
+ * Binding the recipient is not decoration. P-256 ECDH returns only the shared
+ * point's x-coordinate, and negating a public key — `(x, y)` → `(x, p−y)`, which
+ * is still on the curve and which ANYONE can compute from the published key —
+ * yields the SAME x. So without the recipient in the KDF, a seal addressed to
+ * the negated key still decrypts under the honest private key, even though that
+ * negated key displays a DIFFERENT {@link pairingVerificationCode}. That would
+ * leave the human code as the only thing rejecting a substituted recipient.
+ * Mixing `devicePubRaw` in makes the substitution fail in the crypto layer,
+ * where it belongs.
+ *
+ * (The salt is load-bearing for the same reason — it is what makes a swapped
+ * `epk` derive a different key. Do not "simplify" either input away.)
+ */
+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 info = new Uint8Array(label.length + devicePubRaw.length);
+    info.set(label, 0);
+    info.set(devicePubRaw, label.length);
+    const okm = await crypto.subtle.deriveBits({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: epkRaw,
+        info: info,
+    }, prk, 256);
+    return crypto.subtle.importKey("raw", okm, { name: "AES-GCM" }, false, usages);
+}
+/** Decode + shape-check a raw SEC1 uncompressed P-256 public key. */
+function decodePairingPublicKey(b64) {
+    if (typeof b64 !== "string" || b64.length === 0) {
+        throw new Error("Pairing public key must be a non-empty base64 string.");
+    }
+    const raw = fromBase64Loose(b64);
+    if (raw.length !== 65 || raw[0] !== 0x04) {
+        throw new Error("Pairing public key must be a 65-byte uncompressed P-256 point.");
+    }
+    return raw;
+}
+/** Import a raw P-256 point for ECDH. Rejects points that are not on the curve. */
+function importPairingPublicKey(raw) {
+    return crypto.subtle.importKey("raw", raw, PAIRING_CURVE, false, []);
+}
+/**
+ * Base64 decode that also accepts the URL-safe alphabet and missing padding —
+ * pairing public keys may travel through query strings, QR payloads, or JSON
+ * depending on the client, and rejecting a key over `-` vs `+` would be a
+ * miserable failure mode to debug.
+ */
+function fromBase64Loose(s) {
+    const norm = s.replace(/-/g, "+").replace(/_/g, "/");
+    return fromBase64(norm.padEnd(Math.ceil(norm.length / 4) * 4, "="));
+}
 /** Generate a PKCE verifier + S256 challenge for the authorize→token exchange. */
 async function generatePkce() {
     const codeVerifier = base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
@@ -5072,7 +5325,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.11-alpha.0";
+const VERSION = "0.10.12-alpha.0";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -12034,5 +12287,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_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 { ACCESS_TOKEN_SCOPES, AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AccessTokensNamespace, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DbCache, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PasskeyOriginError, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VaultUnavailableError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, buildCommitment, compareHlc, compilePrograms, createPasskeyWithPrf, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultRpId, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, evaluatePasskeyPrf, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, generateDevicePairingKeypair, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isOfflineCapable, isP2pCapable, isProvisional, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, pairingVerificationCode, passkeyPrfCapable, passkeySupported, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, shardHash, signMessage, stableStringify, toField, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
 //# sourceMappingURL=index.js.map