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

package/dist/browser/index.js

@@ -4537,8 +4537,12 @@ class AuthClient {
      * Read a factor record for `username` (returns an indistinguishable decoy if
      * absent). Gated types (email) require the recover `verifyToken`.
      */
-    async vaultRead(username, factorType, verifyToken) {
-        const res = await this.fetchFn(`${this.baseUrl}/api/auth/vault`, this.json("POST", { username, factorType, verifyToken }));
+    async vaultRead(username, factorType, verifyToken, 
+    /** Passkeys are per-origin: naming the caller's host returns THAT origin's
+     *  passkey instead of whichever was enrolled first (which WebAuthn would
+     *  refuse). Ignored for other factor types. */
+    rpId) {
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/vault`, this.json("POST", { username, factorType, verifyToken, rpId }));
         return await this.parse("vaultRead", res);
     }
     /**
@@ -5018,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();
@@ -5043,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)));
@@ -5068,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.10-alpha.0";
+const VERSION = "0.10.12-alpha.0";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -5129,6 +5386,8 @@ class HttpClient {
     /** Origin of {@link baseUrl} — credentials are only attached same-origin. */
     baseOrigin;
     apiKey;
+    /** Scoped machine access token — takes precedence over {@link apiKey} on `X-Muhkoo-Key`. */
+    accessToken;
     getSessionToken;
     onUnauthorized;
     fetchFn;
@@ -5143,6 +5402,7 @@ class HttpClient {
             this.baseOrigin = "";
         }
         this.apiKey = opts.apiKey ?? null;
+        this.accessToken = opts.accessToken ?? null;
         this.getSessionToken = opts.getSessionToken ?? (() => null);
         this.onUnauthorized = opts.onUnauthorized ?? null;
         const f = opts.fetch ?? globalThis.fetch;
@@ -5163,8 +5423,11 @@ class HttpClient {
         // server-reflected path that escapes `baseUrl`) must NOT receive the app
         // key or session token, or it becomes a token-exfiltration vector.
         if (this.isSameOrigin(input)) {
-            if (this.apiKey)
-                headers.set("X-Muhkoo-Key", this.apiKey);
+            // Access token and app key resolve through the same accelerator path
+            // and ride the same header; the access token takes precedence.
+            const key = this.accessToken ?? this.apiKey;
+            if (key)
+                headers.set("X-Muhkoo-Key", key);
             const token = this.getSessionToken();
             if (token)
                 headers.set("X-Muhkoo-Session", token);
@@ -5578,6 +5841,35 @@ async function passkeyPrfCapable() {
 function defaultRpId() {
     return typeof location !== "undefined" ? location.hostname : "";
 }
+/**
+ * Can a passkey enrolled under `rpId` be used from the CURRENT origin?
+ *
+ * WebAuthn only accepts an RP id that is the origin's own host or a registrable
+ * *parent* of it — so a passkey enrolled on `app.example.com` is unusable on
+ * `app.example.net`, and one enrolled on a full host is unusable from a sibling
+ * host. An app served on BOTH a custom domain and the platform host therefore
+ * needs one passkey per origin.
+ *
+ * Call this BEFORE `navigator.credentials.get()`: passing a foreign rpId throws
+ * a raw "The requested RPID did not match the origin or related origins", which
+ * is a dead end for the user. Checking first lets the caller fall back to normal
+ * sign-in (and offer to enroll a passkey for this origin) instead.
+ */
+function rpIdUsableForOrigin(rpId, host) {
+    const h = host ?? (typeof location !== "undefined" ? location.hostname : "");
+    if (!rpId || !h)
+        return false;
+    return h === rpId || h.endsWith(`.${rpId}`);
+}
+/** Thrown when the account's passkey belongs to a different origin. Callers
+ *  should treat this as "no passkey here" and fall back to another factor. */
+class PasskeyOriginError extends Error {
+    code = "passkey_wrong_origin";
+    constructor(message = "No passkey is enrolled for this site. Sign in another way, then add one for this device.") {
+        super(message);
+        this.name = "PasskeyOriginError";
+    }
+}
 /**
  * Create a passkey with PRF and return its credential id, a fresh PRF salt, and
  * the PRF output for that salt. Throws if the authenticator can't do PRF.
@@ -6271,12 +6563,22 @@ class ZkAuth {
      * its PRF, unwraps the master seed → identity → session.
      */
     async loginWithPasskey(username, opts = {}) {
-        const { factor } = await this.deps.auth.vaultRead(username, "passkey");
+        // Ask for THIS origin's passkey — they're enrolled per-origin, so the
+        // account's first passkey may belong to a different host entirely.
+        const host = defaultRpId();
+        const { factor } = await this.deps.auth.vaultRead(username, "passkey", undefined, host);
         const params = factor?.params;
         if (!factor?.wrap || !factor?.iv || !params?.credentialId || !params?.prfSalt) {
             throw new Error("No passkey is set up for this account.");
         }
-        const prfOutput = await evaluatePasskeyPrf(params.rpId ?? defaultRpId(), fromBase64(params.credentialId), fromBase64(params.prfSalt));
+        const rpId = params.rpId ?? host;
+        // Refuse a foreign rpId up front: WebAuthn would throw a raw "requested
+        // RPID did not match the origin", which reads as a hard failure to the
+        // user. A typed error lets the app fall back to another factor and offer
+        // to enroll a passkey for this origin.
+        if (!rpIdUsableForOrigin(rpId, host))
+            throw new PasskeyOriginError();
+        const prfOutput = await evaluatePasskeyPrf(rpId, fromBase64(params.credentialId), fromBase64(params.prfSalt));
         const key = await wrapKeyFromBytes(prfOutput, "muhkoo-passkey-wrap");
         const seed = await unwrapSeed({ iv: factor.iv, ct: factor.wrap }, key);
         const identity = await deriveIdentityFromSeed(seed);
@@ -6296,6 +6598,27 @@ class ZkAuth {
         const { factors } = await this.deps.auth.vaultFactors(token);
         return factors;
     }
+    /**
+     * Is a passkey enrolled that can unlock from THIS origin?
+     *
+     * Passkeys are origin-bound, so an app served on both a custom domain and the
+     * platform host needs one per host. Use this to decide whether to offer
+     * "Unlock with passkey" or go straight to sign-in — prompting with another
+     * origin's passkey fails with a raw WebAuthn error. Requires a session
+     * (metadata read); returns false when signed out or unsupported.
+     */
+    async hasPasskeyForThisOrigin() {
+        if (!passkeySupported())
+            return false;
+        try {
+            const host = defaultRpId();
+            const factors = await this.listFactors();
+            return factors.some((f) => f.type === "passkey" && rpIdUsableForOrigin(f.rpId, host));
+        }
+        catch {
+            return false;
+        }
+    }
     /** Remove a login method by id (can't remove your only one). Session-authed. */
     async removeFactor(id) {
         const token = this.deps.session.token;
@@ -10109,6 +10432,59 @@ class FunctionsNamespace {
     }
 }
 
+/**
+ * `client.accessTokens` — manage an app's **access tokens**: scoped, expiring,
+ * non-ZK machine-to-machine credentials (`mk_<env>_at_…`).
+ *
+ *   const { plaintext } = await client.accessTokens.create(appId, {
+ *     scopes: ["db:read", "db:write"], env: "live", expiresInDays: 30,
+ *     label: "ci-runner",
+ *   });
+ *   // hand `plaintext` to the machine caller as its ClientOptions.accessToken
+ *
+ * These are MANAGEMENT calls — creating/listing/revoking tokens is authorized by
+ * the developer session (same as the `agents`/`functions` namespaces). The token
+ * itself resolves through the SAME accelerator path as an app key (the
+ * `X-Muhkoo-Key` header), but is scoped to a fixed vocabulary of permissions and
+ * expires. The plaintext is returned ONCE, on create — store it then; it can't
+ * be read back.
+ */
+/** All valid {@link Scope}s, in canonical order. */
+const ACCESS_TOKEN_SCOPES = [
+    "db:read",
+    "db:write",
+    "kv:read",
+    "kv:write",
+    "storage:read",
+    "storage:write",
+    "messages:read",
+    "messages:write",
+    "functions:invoke",
+    "ai:infer",
+];
+class AccessTokensNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** List the app's access tokens (metadata only — never the plaintext). */
+    async list(appId) {
+        const res = await this.deps.http.get(this.path(appId, ""));
+        return res.tokens ?? [];
+    }
+    /** Mint an access token (owner/editor only). The plaintext is returned once. */
+    async create(appId, input) {
+        return this.deps.http.post(this.path(appId, ""), input);
+    }
+    /** Revoke an access token by its `keyId`. */
+    async revoke(appId, keyId) {
+        return this.deps.http.del(this.path(appId, `/${encodeURIComponent(keyId)}`));
+    }
+    path(appId, suffix) {
+        return `/api/apps/${encodeURIComponent(appId)}/access-tokens${suffix}`;
+    }
+}
+
 /**
  * `ChatKeyVault` — SDK-owned lifecycle for a member's long-lived ratchet/space
  * keypair (the connect `KeyStore` entry keyed by the member id / username).
@@ -11356,6 +11732,8 @@ class Client {
     agents;
     /** Serverless functions — `client.functions.deploy(appId, …)`, etc. */
     functions;
+    /** Access tokens — `client.accessTokens.create(appId, …)`, etc. */
+    accessTokens;
     /** Offline cache + sync — `client.offline.status`, `client.offline.snapshot`, etc. */
     offline;
     session;
@@ -11409,6 +11787,7 @@ class Client {
         this.http = new HttpClient({
             baseUrl: this.baseUrl,
             apiKey: options.apiKey,
+            accessToken: options.accessToken,
             getSessionToken: () => this.session.token,
             fetch: reportingFetch,
             // Self-heal stale sessions: on a 401, try a silent re-auth (only
@@ -11485,6 +11864,7 @@ class Client {
         });
         this.agents = new AgentsNamespace({ http: this.http });
         this.functions = new FunctionsNamespace({ http: this.http, fnHostSuffix: options.functionsHostSuffix });
+        this.accessTokens = new AccessTokensNamespace({ http: this.http });
         // Replay deferred shard uploads on reconnect. The bytes live in the
         // Cache API keyed by hash; re-PUT them through a (defer-free) shard
         // client so a failure surfaces as transient and the entry stays queued.
@@ -11634,6 +12014,7 @@ function MuhkooDB(meta) {
             table: meta.table ?? String(propertyKey),
             access: meta.access ?? "read",
             description: meta.description,
+            backend: meta.backend ?? false,
         });
     });
 }
@@ -11673,9 +12054,12 @@ function ejectAgentPrompt(appClass) {
         for (const s of d.spaces)
             lines.push(`- ${s.name}: ${s.description}`);
     }
-    if (d.tables.length) {
+    // Backend-only tables are deliberately withheld — the agent should never be
+    // told about server-managed / internal state it can't (and shouldn't) touch.
+    const promptTables = d.tables.filter((t) => !t.backend);
+    if (promptTables.length) {
         lines.push("", "App database tables:");
-        for (const t of d.tables) {
+        for (const t of promptTables) {
             const verbs = t.access === "write"
                 ? "read & write — db_query/db_get/db_insert/db_update/db_delete"
                 : "read-only — db_query/db_get";
@@ -11693,7 +12077,7 @@ function ejectAgentPrompt(appClass) {
     // How to respond — the load-bearing behavioral contract. Without this, models
     // (especially gpt-oss) tend to run tool calls and then end their turn with no
     // user-facing message, so the user sees the work happen but gets no reply.
-    const hasTools = d.tables.length > 0 || d.functions.length > 0;
+    const hasTools = promptTables.length > 0 || d.functions.length > 0;
     lines.push("", "How to respond:");
     if (hasTools) {
         lines.push("- When you need information or need to make a change, call your tools immediately — don't ask the user to do it, and don't describe or name the tools to them.", "- After your tool calls return, you MUST send one final reply to the channel, in plain language, that answers the request using the results.");
@@ -11903,5 +12287,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
   default: loadRsWasm
 });
 
-export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, 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, 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, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isOfflineCapable, isP2pCapable, isProvisional, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, 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