@muhkoo/connect 0.4.0-alpha.1 → 0.6.0-alpha.11

package/dist/server/index.js

@@ -1,6 +1,10 @@
 import { prove, verify as verify$1 } from '@zk-kit/groth16';
 import { p256 } from '@noble/curves/nist.js';
 import { buildPoseidon } from 'circomlibjs';
+import { entropyToMnemonic, validateMnemonic, mnemonicToEntropy } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
+import { scrypt } from '@noble/hashes/scrypt.js';
+import { ristretto255_oprf } from '@noble/curves/ed25519.js';
 
 /**
  * WebCrypto subtle-interface resolver.
@@ -439,7 +443,7 @@ function fromHex(hex) {
     return out;
 }
 /** Encode a byte array as a standard base64 string. */
-function toBase64(bytes) {
+function toBase64$1(bytes) {
     let binary = "";
     for (let i = 0; i < bytes.length; i++) {
         binary += String.fromCharCode(bytes[i]);
@@ -447,7 +451,7 @@ function toBase64(bytes) {
     return btoa(binary);
 }
 /** Decode a standard base64 string to bytes. */
-function fromBase64(b64) {
+function fromBase64$1(b64) {
     const binary = atob(b64);
     const ab = new ArrayBuffer(binary.length);
     const out = new Uint8Array(ab);
@@ -457,13 +461,13 @@ function fromBase64(b64) {
 }
 /** Encode a byte array as a base64url string (no padding). */
 function toBase64Url(bytes) {
-    return toBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    return toBase64$1(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 /** Decode a base64url string (with or without padding) to bytes. */
 function fromBase64Url(b64url) {
     const padded = b64url.replace(/-/g, "+").replace(/_/g, "/") +
         "=".repeat((4 - (b64url.length % 4)) % 4);
-    return fromBase64(padded);
+    return fromBase64$1(padded);
 }
 /** Concatenate any number of byte arrays into a single Uint8Array. */
 function concatBytes(...arrays) {
@@ -1041,10 +1045,10 @@ class KeyStore {
     async packDehydratedKeys(id) {
         const dehydrated = await this.dehydrateKeyPair(id);
         const combined = JSON.stringify(dehydrated);
-        return toBase64(new TextEncoder().encode(combined));
+        return toBase64$1(new TextEncoder().encode(combined));
     }
     async hydrateFromPacked(id, masterKey) {
-        const decoded = utf8Decode(fromBase64(masterKey));
+        const decoded = utf8Decode(fromBase64$1(masterKey));
         const dehydrated = JSON.parse(decoded);
         await this.hydrateKeyPair(id, dehydrated);
     }
@@ -1875,8 +1879,8 @@ class ChunkCipher {
      */
     generateKeyMaterial() {
         return {
-            key: toBase64(randomBytes(AES_GCM_KEY_BYTES)),
-            iv: toBase64(randomBytes(AES_GCM_IV_BYTES)),
+            key: toBase64$1(randomBytes(AES_GCM_KEY_BYTES)),
+            iv: toBase64$1(randomBytes(AES_GCM_IV_BYTES)),
         };
     }
     /**
@@ -1885,7 +1889,7 @@ class ChunkCipher {
      * GCM behavior).
      */
     async encryptChunk(plaintext, material) {
-        return encryptAesGcm(fromBase64(material.key), fromBase64(material.iv), plaintext);
+        return encryptAesGcm(fromBase64$1(material.key), fromBase64$1(material.iv), plaintext);
     }
     /**
      * Inverse of {@link encryptChunk}. Throws if the auth tag fails — that
@@ -1894,7 +1898,7 @@ class ChunkCipher {
      */
     async decryptChunk(ciphertext, material) {
         try {
-            return await decryptAesGcm(fromBase64(material.key), fromBase64(material.iv), ciphertext);
+            return await decryptAesGcm(fromBase64$1(material.key), fromBase64$1(material.iv), ciphertext);
         }
         catch {
             // WebCrypto throws a vague OperationError on GCM tag mismatch.
@@ -2370,6 +2374,39 @@ class AuthClient {
         const res = await this.fetchFn(`${this.baseUrl}/api/auth/verify`, this.json("POST", { token }));
         return await this.parse("verify", res);
     }
+    // ---- Identity vault (M1.0) ----------------------------------------------
+    /** Blinded OPRF evaluation — the server-gated half of a password/recovery wrap key. */
+    async oprfEvaluate(username, blinded) {
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/oprf`, this.json("POST", { username, blinded }));
+        return await this.parse("oprfEvaluate", res);
+    }
+    /** Read a factor record for `username` (returns an indistinguishable decoy if absent). */
+    async vaultRead(username, factorType) {
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/vault`, this.json("POST", { username, factorType }));
+        return await this.parse("vaultRead", res);
+    }
+    /** Add/replace a factor (session-authed; the seed is already wrapped client-side). */
+    async vaultPutFactor(token, factor) {
+        const init = this.json("PUT", { factor });
+        init.headers["Authorization"] = `Bearer ${token}`;
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/vault/factor`, init);
+        return await this.parse("vaultPutFactor", res);
+    }
+    /** List the user's factor metadata (no ciphertext). Session-authed. */
+    async vaultFactors(token) {
+        const init = { method: "GET", headers: { Authorization: `Bearer ${token}` } };
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/vault/factors`, init);
+        return await this.parse("vaultFactors", res);
+    }
+    /** Remove a factor by id (can't remove the last one). Session-authed. */
+    async vaultDeleteFactor(token, id) {
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/vault/factor`, {
+            method: "DELETE",
+            headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+            body: JSON.stringify({ id }),
+        });
+        return await this.parse("vaultDeleteFactor", res);
+    }
     // -------------------------------------------------------------------------
     // Internals
     // -------------------------------------------------------------------------
@@ -2487,7 +2524,31 @@ async function deriveIdentity(username, password) {
     if (typeof password !== "string" || password.length === 0) {
         throw new Error("deriveIdentity: `password` is required");
     }
-    const seed = await pbkdf2Bytes(password, "muhkoo-zk-v1:" + username, SCALAR_BYTES);
+    const seed = await deriveMasterSeedFromPassword(username, password);
+    return deriveIdentityFromSeed(seed);
+}
+/**
+ * Legacy master-seed derivation: `PBKDF2(password, "muhkoo-zk-v1:"||username)`.
+ *
+ * This was the *only* path pre-vault, where the identity descended directly from
+ * the password. It's kept so existing accounts still re-derive their seed (and
+ * the vault can adopt that exact seed on migration, preserving the commitment).
+ * New accounts use a random seed (`vault.randomSeed`) instead, so their identity
+ * is no longer a function of the password.
+ */
+async function deriveMasterSeedFromPassword(username, password) {
+    return pbkdf2Bytes(password, "muhkoo-zk-v1:" + username, SCALAR_BYTES);
+}
+/**
+ * Derive the (unchanged) ZK identity from a 32-byte **master seed**. The seed is
+ * HKDF-expanded into secret/salt + the P-256 ECDSA & ECDH keypairs exactly as
+ * before — so the resulting commitment is byte-identical for a given seed. The
+ * vault wraps THIS seed under each recovery factor.
+ */
+async function deriveIdentityFromSeed(seed) {
+    if (!(seed instanceof Uint8Array) || seed.length !== SCALAR_BYTES) {
+        throw new Error(`deriveIdentityFromSeed: expected a ${SCALAR_BYTES}-byte seed`);
+    }
     const secretBytes = await hkdfExpand(seed, "zk-secret", SCALAR_BYTES);
     const saltBytes = await hkdfExpand(seed, "zk-salt", SCALAR_BYTES);
     const ecdsaPriv = await hkdfExpand(seed, "ecdsa-priv", SCALAR_BYTES);
@@ -2716,6 +2777,16 @@ async function signMessage(message, privateKey) {
     return bytesToBase64(new Uint8Array(sig));
 }
 
+/**
+ * SDK build version — stamped to the console when a {@link Client} is created.
+ *
+ * During active development, bump the `-alpha.N` suffix whenever we ship a build
+ * so we can confirm in the browser console that the page is running the build we
+ * expect (and isn't serving a stale cached bundle). Keep this in sync with
+ * `package.json` `version`.
+ */
+const VERSION = "0.6.0-alpha.11";
+
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
  * accelerator over HTTP.
@@ -2933,6 +3004,10 @@ function defaultSessionStore(keyPrefix) {
 class SessionState {
     session = null;
     _identity = null;
+    /** The 32-byte master seed, in-memory only (never persisted). Held after
+     *  login/register so additional recovery factors (passkey, phrase) can be
+     *  enrolled, and a password can be changed, without re-deriving. */
+    _seed = null;
     store;
     constructor(store) {
         this.store = store ?? new MemorySessionStore();
@@ -2974,6 +3049,14 @@ class SessionState {
     setIdentity(identity) {
         this._identity = identity;
     }
+    /** The in-memory master seed (or null when locked / not held). */
+    get seed() {
+        return this._seed;
+    }
+    /** Hold the master seed in memory (set on login/register when available). */
+    setSeed(seed) {
+        this._seed = seed;
+    }
     /** Load a persisted session (used by `restore()`); identity stays null. */
     async loadPersisted() {
         const loaded = await this.store.load();
@@ -2985,10 +3068,251 @@ class SessionState {
     async clear() {
         this.session = null;
         this._identity = null;
+        if (this._seed)
+            this._seed.fill(0); // wipe the master seed
+        this._seed = null;
         await this.store.clear();
     }
 }
 
+/**
+ * Recovery phrase (M1.2) — a 24-word BIP39 mnemonic that ENCODES the 32-byte
+ * master seed directly. Nothing is stored server-side (the phrase *is* the seed),
+ * so it's a fully offline, self-sovereign recovery factor: enter the phrase →
+ * decode → master seed → identity. A `phrase-marker` factor is kept in the vault
+ * only so the UI can show "recovery phrase: enabled".
+ */
+/** Encode a 32-byte master seed as a 24-word BIP39 recovery phrase. */
+function seedToMnemonic(seed) {
+    if (!(seed instanceof Uint8Array) || seed.length !== 32) {
+        throw new Error("seedToMnemonic: expected a 32-byte seed");
+    }
+    return entropyToMnemonic(seed, wordlist);
+}
+function normalize(mnemonic) {
+    return mnemonic.trim().toLowerCase().replace(/\s+/g, " ");
+}
+/** Decode a recovery phrase back to the 32-byte master seed. Throws if invalid. */
+function mnemonicToSeed(mnemonic) {
+    const m = normalize(mnemonic);
+    if (!validateMnemonic(m, wordlist))
+        throw new Error("Invalid recovery phrase.");
+    return mnemonicToEntropy(m, wordlist);
+}
+
+/**
+ * Identity vault primitives (M1.0).
+ *
+ * The vault decouples the identity from the password: a random 32-byte **master
+ * seed** yields the (unchanged) ZK identity via {@link deriveIdentityFromSeed},
+ * and that seed is AES-256-GCM-wrapped under one key *per factor* (password,
+ * passkey, recovery phrase). Server stores only ciphertext.
+ *
+ * This module holds the PURE primitives (seed gen, the memory-hard password
+ * pre-hash, AES-GCM wrap/unwrap, the OPRF -> wrap-key HKDF). The networked
+ * orchestration (calling the server's OPRF endpoint, fetching/storing factor
+ * records) lives in the AuthNamespace, which has transport access.
+ *
+ * Memory-hard KDF: we use **scrypt** (vetted, in `@noble/hashes`, runs in
+ * browser + Workers + Node - no wasm dependency) instead of argon2id; it is the
+ * pre-hash fed into the OPRF, so even if the OPRF key ever leaked, guesses still
+ * pay the scrypt cost.
+ */
+const TE = 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. */
+function randomSeed() {
+    return crypto.getRandomValues(new Uint8Array(32));
+}
+/** Memory-hard pre-hash of the password - the OPRF input. Salted by username. */
+function passwordPreHash(username, password) {
+    return scrypt(TE.encode(password), TE.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.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.encode(info) }, prk, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
+async function wrapSeed(seed, key) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, seed);
+    return { iv: toBase64(iv), ct: toBase64(new Uint8Array(ct)) };
+}
+/** Decrypt a wrapped seed. Throws (AES-GCM tag failure) on a wrong key. */
+async function unwrapSeed(wrapped, key) {
+    const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64(wrapped.iv) }, key, fromBase64(wrapped.ct));
+    return new Uint8Array(pt);
+}
+function toBase64(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes.length; i++)
+        s += String.fromCharCode(bytes[i]);
+    return btoa(s);
+}
+function fromBase64(b64) {
+    const s = atob(b64);
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++)
+        out[i] = s.charCodeAt(i);
+    return out;
+}
+
+/**
+ * OPRF (Oblivious PRF) — RFC 9497, ristretto255-SHA512, mode 0x00.
+ *
+ * Used to gate the password/recovery factors of the identity vault
+ * ({@link ./vault}). The wrap key for a password factor is
+ * `HKDF(OPRF(serverKey, scrypt(password)))`, so:
+ *   - the client cannot derive the wrap key offline (it needs the server's
+ *     secret-keyed evaluation), and
+ *   - the server learns nothing — it only ever sees a *blinded* group element,
+ *     never the password or the resulting key.
+ *
+ * Net effect: a stolen vault blob is NOT offline-crackable; every guess costs a
+ * round-trip to a rate-limited server endpoint. The same OPRF backs the M2
+ * Google/email factors.
+ *
+ * Thin wrapper over `@noble/curves`' vetted `ristretto255_oprf` so the protocol
+ * (blind / blindEvaluate / finalize) lives in one named place. CLIENT uses
+ * {@link oprfBlind} + {@link oprfFinalize}; SERVER uses {@link oprfDeriveKey} +
+ * {@link oprfBlindEvaluate} (imported by the accelerator's VaultDO).
+ */
+const OPRF = ristretto255_oprf.oprf;
+// Domain separation for the server key derivation (RFC 9497 `info`).
+new TextEncoder().encode("muhkoo-oprf-v1");
+/** CLIENT: blind `input` (e.g. `scrypt(password)`) before the server eval. */
+function oprfBlind(input) {
+    const { blind, blinded } = OPRF.blind(input);
+    return { blind, blinded };
+}
+/** CLIENT: fold the server's blinded evaluation into the final 64-byte OPRF output. */
+function oprfFinalize(input, blind, evaluated) {
+    return OPRF.finalize(input, blind, evaluated);
+}
+
+/**
+ * Passkey factor (M1.1) — WebAuthn with the **PRF extension**.
+ *
+ * A passkey becomes a device-bound, platform-synced source of a stable secret:
+ * for a fixed salt, the authenticator's PRF returns the same 32 bytes, which we
+ * HKDF into an AES key that wraps the master seed. The server never sees the
+ * passkey — it's purely a local key source; the ZK proof remains the server auth.
+ *
+ * BROWSER ONLY (`navigator.credentials`). The PRF extension fields aren't in the
+ * standard DOM types yet, so they're reached through narrow casts.
+ */
+function rand(n) {
+    return crypto.getRandomValues(new Uint8Array(n));
+}
+/** Whether this environment can do WebAuthn at all. (PRF support is checked at enroll.) */
+function passkeySupported() {
+    return (typeof navigator !== "undefined" &&
+        !!navigator.credentials &&
+        typeof PublicKeyCredential !== "undefined");
+}
+/**
+ * Whether this browser's authenticator can do the **PRF extension** our passkey
+ * factor needs. A browser can save passkeys (e.g. for password autofill) yet not
+ * expose PRF — PRF is what derives the stable secret we wrap the seed under, so a
+ * passkey without it is useless to us.
+ *
+ * Uses `PublicKeyCredential.getClientCapabilities()` (the `extension:prf` cap)
+ * where available. Returns:
+ *   - `true`  — PRF is supported,
+ *   - `false` — definitively NOT supported (hide the option),
+ *   - `null`  — couldn't determine (older browser without the capabilities API);
+ *              the caller may optimistically allow and let enroll surface a real
+ *              error if it turns out PRF isn't there.
+ */
+async function passkeyPrfCapable() {
+    if (!passkeySupported())
+        return false;
+    const PC = PublicKeyCredential;
+    if (typeof PC.getClientCapabilities !== "function")
+        return null;
+    try {
+        const caps = await PC.getClientCapabilities();
+        // The spec keys extension caps as `extension:<name>`; tolerate variants.
+        const prf = caps["extension:prf"] ?? caps["extensions:prf"] ?? caps["prf"];
+        return typeof prf === "boolean" ? prf : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Best-effort registrable RP id — the host. Apps spanning subdomains should pass
+ *  the parent domain (e.g. "muhkoo.dev") explicitly. */
+function defaultRpId() {
+    return typeof location !== "undefined" ? location.hostname : "";
+}
+/**
+ * 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.
+ */
+async function createPasskeyWithPrf(opts) {
+    if (!passkeySupported())
+        throw new Error("Passkeys aren't supported in this browser.");
+    const created = (await navigator.credentials.create({
+        publicKey: {
+            rp: { id: opts.rpId, name: opts.rpName },
+            user: { id: rand(16), name: opts.username, displayName: opts.username },
+            challenge: rand(32),
+            pubKeyCredParams: [{ type: "public-key", alg: -7 }, { type: "public-key", alg: -257 }],
+            authenticatorSelection: { residentKey: "preferred", userVerification: "preferred" },
+            extensions: { prf: {} },
+        },
+    }));
+    if (!created)
+        throw new Error("Passkey creation was cancelled.");
+    const credentialId = new Uint8Array(created.rawId);
+    // Don't trust `prf.enabled` from create() alone — several browsers only report
+    // PRF support on the first get() eval, so a precheck false-negatives. Try the
+    // actual PRF eval; if it yields a result, PRF works.
+    const prfSalt = rand(32);
+    let prfOutput;
+    try {
+        prfOutput = await evaluatePasskeyPrf(opts.rpId, credentialId, prfSalt);
+    }
+    catch {
+        // Empty PRF result almost always means a third-party credential manager
+        // (e.g. a browser password-manager extension) handled the request instead of
+        // the platform authenticator, and that manager doesn't implement PRF. The
+        // device's built-in passkey (Touch ID / Windows Hello / iCloud Keychain)
+        // normally does — so steer the user there rather than blaming the device.
+        throw new Error("That passkey can't be used for recovery — it didn't return a PRF result. " +
+            "A browser password-manager extension may have handled it; try again and " +
+            "pick your device's built-in passkey (Touch ID / Windows Hello), or use a " +
+            "recovery phrase instead.");
+    }
+    return { credentialId, prfSalt, prfOutput };
+}
+/** Evaluate a passkey's PRF for `salt` → 32 bytes. Used at recover/login. */
+async function evaluatePasskeyPrf(rpId, credentialId, salt) {
+    if (!passkeySupported())
+        throw new Error("Passkeys aren't supported in this browser.");
+    const assertion = (await navigator.credentials.get({
+        publicKey: {
+            rpId,
+            challenge: rand(32),
+            allowCredentials: [{ type: "public-key", id: credentialId }],
+            userVerification: "preferred",
+            extensions: { prf: { eval: { first: salt } } },
+        },
+    }));
+    if (!assertion)
+        throw new Error("Passkey authentication was cancelled.");
+    const results = assertion.getClientExtensionResults()?.prf?.results;
+    if (!results?.first)
+        throw new Error("Your passkey didn't return a PRF result.");
+    return new Uint8Array(results.first);
+}
+
 /**
  * `client.auth` — user authentication, exposed today through the `zk`
  * sub-namespace (`client.auth.zk.login(...)`). Leaving room under `auth` for
@@ -3005,6 +3329,24 @@ class SessionState {
  * {@link SessionState} so the storage + message namespaces can reuse it for
  * at-rest encryption and the messaging ratchet without re-deriving.
  */
+/**
+ * Thrown when the identity vault can't be reached to unlock the seed — a network
+ * failure, a 5xx, or the per-user rate limit (429). This is distinct from a wrong
+ * password, and is surfaced so `login`/`unlock` do NOT silently fall back to the
+ * legacy password derivation (which, for a vault account, yields a misleading
+ * "commitment mismatch"). Callers should ask the user to retry, not re-enter a
+ * password.
+ */
+class VaultUnavailableError extends Error {
+    constructor(cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause ?? "");
+        super(/too many|rate.?limit|\b429\b/i.test(detail)
+            ? "Too many attempts — please wait a moment and try again."
+            : "Couldn't reach the secure vault. Check your connection and try again.");
+        this.name = "VaultUnavailableError";
+        this.cause = cause;
+    }
+}
 /**
  * ZK identity auth. One instance per {@link Client}; reads/writes the shared
  * {@link SessionState}.
@@ -3015,13 +3357,18 @@ class ZkAuth {
         this.deps = deps;
     }
     /**
-     * Register a new user, then (by default) sign them in. The identity is
-     * derived deterministically from `(username, password)` — the same inputs
-     * reproduce it on any device, so there's no key material to ship around.
+     * Register a new user, then (by default) sign them in.
+     *
+     * M1.0: the identity now descends from a **random master seed** (not the
+     * password), so it's recoverable + the password can be changed. We register
+     * the commitment, sign in with the in-memory identity to get a token, then
+     * enroll the OPRF-gated **password factor** (the seed wrapped under a key the
+     * server can't derive offline). Future logins unlock the seed via that factor.
      */
     async register(params) {
         const { username, password, email = null, login = true } = params;
-        const identity = await deriveIdentity(username, password);
+        const seed = randomSeed();
+        const identity = await deriveIdentityFromSeed(seed);
         const commitment = await this.commitmentFor(identity);
         await this.deps.auth.register({
             username,
@@ -3030,19 +3377,52 @@ class ZkAuth {
             ecdsaPublicKey: await exportPublicKeyBase64(identity.ecdsaKeyPair.publicKey),
             email,
         });
-        if (login) {
-            return this.login(username, password);
-        }
-        return { username, commitment };
+        // Sign in with the in-memory (random-seed) identity to obtain a session
+        // token, then enroll the password factor so the next login can recover
+        // the seed. (A token is required to write the factor.)
+        const user = await this.proveAndStore(username, identity, {});
+        await this.enrollPasswordFactor(username, password, seed, this.deps.session.token);
+        this.deps.session.setSeed(seed); // held so a passkey/phrase can be enrolled next
+        if (!login)
+            await this.logout();
+        return user;
     }
     /**
-     * Sign in: re-derive the identity, prove knowledge of it against a fresh
-     * server challenge, and trade the proof for a session token. On success
-     * both the session and the identity are stored on the client.
+     * Sign in. M1.0 is **vault-first**: read the password factor and OPRF-unwrap
+     * the master seed → identity. If that fails (a pre-vault account, whose factor
+     * is absent so the server returns a decoy, or a wrong password), fall back to
+     * the legacy password-derived identity. Either way we then prove knowledge of
+     * the identity and trade it for a session token.
      */
     async login(username, password, opts = {}) {
-        const identity = await deriveIdentity(username, password);
-        return this.proveAndStore(username, identity, opts);
+        // Vault-first; fall back to the legacy password-derived seed (pre-vault
+        // accounts). Either way we end up with the master seed, which we hold so
+        // recovery factors can be enrolled.
+        const vaultSeed = await this.tryUnlockSeed(username, password);
+        const seed = vaultSeed ?? await deriveMasterSeedFromPassword(username, password);
+        const identity = await deriveIdentityFromSeed(seed);
+        const user = await this.proveAndStore(username, identity, opts);
+        this.deps.session.setSeed(seed);
+        // Migrate a legacy account into the vault on first vault-aware login: it has
+        // no password factor (`vaultSeed` is null), so enroll one now — wrapping the
+        // exact legacy-derived seed the proof just validated, so the commitment is
+        // preserved. Best-effort; the legacy path still works if this fails.
+        if (!vaultSeed)
+            await this.migrateLegacyPasswordFactor(username, password, seed);
+        return user;
+    }
+    /** Enroll the password factor for a legacy (pre-vault) account. Idempotent +
+     *  best-effort; failure just means we retry on the next login. */
+    async migrateLegacyPasswordFactor(username, password, seed) {
+        const token = this.deps.session.token;
+        if (!token)
+            return;
+        try {
+            await this.enrollPasswordFactor(username, password, seed, token);
+        }
+        catch {
+            /* migrate next time */
+        }
     }
     /**
      * Silently re-authenticate the current user without prompting for a
@@ -3140,12 +3520,138 @@ class ZkAuth {
         if (!username || !expected) {
             throw new Error("ZkAuth.unlock: no active session to unlock — sign in first.");
         }
-        const identity = await deriveIdentity(username, password);
+        const vaultSeed = await this.tryUnlockSeed(username, password);
+        const seed = vaultSeed ?? await deriveMasterSeedFromPassword(username, password);
+        const identity = await deriveIdentityFromSeed(seed);
         const commitment = await this.commitmentFor(identity);
         if (commitment !== expected) {
             throw new Error("ZkAuth.unlock: incorrect password (commitment mismatch).");
         }
         this.deps.session.setIdentity(identity);
+        this.deps.session.setSeed(seed);
+        // Migrate a legacy account into the vault if it has no password factor.
+        if (!vaultSeed)
+            await this.migrateLegacyPasswordFactor(username, password, seed);
+    }
+    /**
+     * Generate a 24-word **recovery phrase** that encodes the master seed, and
+     * record a marker in the vault so the UI knows one exists. Show the returned
+     * phrase to the user ONCE — it's never stored server-side (the phrase *is* the
+     * seed). Requires being signed in (the seed must be held in memory).
+     */
+    async enrollRecoveryPhrase() {
+        const seed = this.deps.session.seed;
+        const token = this.deps.session.token;
+        if (!seed || !token) {
+            throw new Error("Sign in first to set up a recovery phrase.");
+        }
+        const mnemonic = seedToMnemonic(seed);
+        await this.deps.auth.vaultPutFactor(token, { id: "phrase", type: "phrase-marker", createdAt: Date.now() });
+        return mnemonic;
+    }
+    /**
+     * Recover an account with its recovery phrase (the "forgot password" path).
+     * Decodes the phrase to the master seed → identity → session. After this,
+     * call {@link changePassword} to set a new password. No server lookup needed.
+     */
+    async recoverWithPhrase(username, mnemonic, opts = {}) {
+        const seed = mnemonicToSeed(mnemonic);
+        const identity = await deriveIdentityFromSeed(seed);
+        const user = await this.proveAndStore(username, identity, opts);
+        this.deps.session.setSeed(seed);
+        return user;
+    }
+    /**
+     * Change the password — re-wraps the (unchanged) master seed under the new
+     * password's OPRF-gated key. The identity/commitment never moves. Requires
+     * being signed in (or freshly recovered) so the seed is held.
+     */
+    async changePassword(newPassword) {
+        const seed = this.deps.session.seed;
+        const username = this.deps.session.username;
+        const token = this.deps.session.token;
+        if (!seed || !username || !token) {
+            throw new Error("Sign in first to change your password.");
+        }
+        await this.enrollPasswordFactor(username, newPassword, seed, token);
+    }
+    /** Whether this browser can use passkeys (WebAuthn) at all. */
+    passkeyAvailable() {
+        return passkeySupported();
+    }
+    /**
+     * Whether this browser's authenticator can do the **PRF extension** our
+     * passkey factor requires. A browser may support passkeys generally but not
+     * PRF — in which case enrolling one would fail. Resolves `true`/`false`, or
+     * `null` when it can't be determined (no capabilities API). Use this to gate
+     * the passkey UI so users don't hit a dead-end error.
+     */
+    async passkeyPrfAvailable() {
+        return passkeyPrfCapable();
+    }
+    /**
+     * Add a **passkey** recovery factor. Creates a WebAuthn passkey with PRF,
+     * wraps the master seed under its PRF output, and stores the factor. The
+     * passkey (synced via the platform's keychain) then unlocks the account on
+     * any device — no password. Requires being signed in (seed held in memory).
+     */
+    async enrollPasskey(opts) {
+        const seed = this.deps.session.seed;
+        const token = this.deps.session.token;
+        const username = this.deps.session.username;
+        if (!seed || !token || !username) {
+            throw new Error("Sign in first to add a passkey.");
+        }
+        const rpId = opts?.rpId ?? defaultRpId();
+        const { credentialId, prfSalt, prfOutput } = await createPasskeyWithPrf({
+            rpId,
+            rpName: opts?.rpName ?? "Muhkoo",
+            username,
+        });
+        const key = await wrapKeyFromBytes(prfOutput, "muhkoo-passkey-wrap");
+        const wrapped = await wrapSeed(seed, key);
+        await this.deps.auth.vaultPutFactor(token, {
+            id: `passkey:${toBase64(credentialId).slice(0, 16)}`,
+            type: "passkey",
+            wrap: wrapped.ct,
+            iv: wrapped.iv,
+            params: { credentialId: toBase64(credentialId), prfSalt: toBase64(prfSalt), rpId },
+            label: opts?.label ?? "Passkey",
+            createdAt: Date.now(),
+        });
+    }
+    /**
+     * Sign in with a passkey (no password). Reads the passkey factor, evaluates
+     * its PRF, unwraps the master seed → identity → session.
+     */
+    async loginWithPasskey(username, opts = {}) {
+        const { factor } = await this.deps.auth.vaultRead(username, "passkey");
+        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 key = await wrapKeyFromBytes(prfOutput, "muhkoo-passkey-wrap");
+        const seed = await unwrapSeed({ iv: factor.iv, ct: factor.wrap }, key);
+        const identity = await deriveIdentityFromSeed(seed);
+        const user = await this.proveAndStore(username, identity, opts);
+        this.deps.session.setSeed(seed);
+        return user;
+    }
+    /** List the user's enrolled login methods (metadata only). Session-authed. */
+    async listFactors() {
+        const token = this.deps.session.token;
+        if (!token)
+            throw new Error("Sign in first to view your login methods.");
+        const { factors } = await this.deps.auth.vaultFactors(token);
+        return factors;
+    }
+    /** Remove a login method by id (can't remove your only one). Session-authed. */
+    async removeFactor(id) {
+        const token = this.deps.session.token;
+        if (!token)
+            throw new Error("Sign in first to manage your login methods.");
+        await this.deps.auth.vaultDeleteFactor(token, id);
     }
     /** Sign out: clears the session, identity, and persisted token. */
     async logout() {
@@ -3170,6 +3676,16 @@ class ZkAuth {
     get token() {
         return this.deps.session.token;
     }
+    /**
+     * The master seed as base64, or `null` when locked. The host app uses this to
+     * wrap app-level data (e.g. chat ratchet keys) to the **seed** instead of the
+     * password — so that data survives password changes and can be unlocked by a
+     * passwordless (passkey) login, both of which recover the same seed.
+     */
+    get seedBase64() {
+        const seed = this.deps.session.seed;
+        return seed ? toBase64(seed) : null;
+    }
     // -------------------------------------------------------------------------
     /** Poseidon commitment for an identity — the value the server stores. */
     async commitmentFor(identity) {
@@ -3178,6 +3694,73 @@ class ZkAuth {
         const ecdsaPubHex = await exportPublicKeyHex(identity.ecdsaKeyPair.publicKey);
         return buildCommitment(identity.secretHex, identity.saltHex, ecdsaPubHex);
     }
+    // ---- Identity vault (M1.0) ----------------------------------------------
+    /**
+     * Derive the OPRF-gated wrap key for the password factor: `scrypt(password)`
+     * is blinded, evaluated by the server's secret OPRF key (so it can't be
+     * derived offline), unblinded, then HKDF'd into an AES-GCM key.
+     */
+    async passwordWrapKey(username, password) {
+        const pre = passwordPreHash(username, password);
+        const { blind, blinded } = oprfBlind(pre);
+        const { evaluated } = await this.deps.auth.oprfEvaluate(username, toBase64(blinded));
+        return wrapKeyFromOprf(oprfFinalize(pre, blind, fromBase64(evaluated)));
+    }
+    /**
+     * Try to recover the master seed from the password factor.
+     *
+     * Returns `null` only when the vault read SUCCEEDS but the seed can't be
+     * unwrapped — i.e. there's no real factor (a pre-vault/legacy account, whose
+     * read returns a decoy that won't unwrap) or the password is wrong. The caller
+     * then legitimately falls back to the legacy password-derived identity.
+     *
+     * Throws {@link VaultUnavailableError} when the vault itself can't be reached
+     * (network / 5xx / rate-limit) — so a *transient* failure is NOT silently
+     * turned into a legacy fallback (which would surface as "commitment mismatch").
+     */
+    async tryUnlockSeed(username, password) {
+        const read = await this.deps.auth
+            .vaultRead(username, "password")
+            .catch((e) => { throw new VaultUnavailableError(e); });
+        const factor = read.factor;
+        if (!factor?.wrap || !factor?.iv)
+            return null; // genuinely no factor → legacy account
+        const key = await this
+            .passwordWrapKey(username, password)
+            .catch((e) => { throw new VaultUnavailableError(e); }); // OPRF eval unreachable / rate-limited
+        try {
+            return await unwrapSeed({ iv: factor.iv, ct: factor.wrap }, key);
+        }
+        catch {
+            return null; // factor present but won't unwrap → wrong password, or a decoy
+        }
+    }
+    /**
+     * Enroll/replace the password factor for `username` — wraps `seed` under the
+     * OPRF-gated key and stores it (needs a session `token`).
+     *
+     * Retries: this is the step that persists the (otherwise in-memory-only)
+     * master seed. If it fails after a fresh registration the account would be
+     * unrecoverable, so we retry a few times before surfacing the error.
+     */
+    async enrollPasswordFactor(username, password, seed, token) {
+        const key = await this.passwordWrapKey(username, password);
+        const wrapped = await wrapSeed(seed, key);
+        const factor = { id: "password", type: "password", wrap: wrapped.ct, iv: wrapped.iv, createdAt: Date.now() };
+        let lastErr;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                await this.deps.auth.vaultPutFactor(token, factor);
+                return;
+            }
+            catch (err) {
+                lastErr = err;
+                await new Promise((r) => setTimeout(r, 200 * (attempt + 1)));
+            }
+        }
+        throw new Error("Registration could not finish securing your account (vault enrollment failed). " +
+            "Please try again. " + (lastErr instanceof Error ? lastErr.message : ""));
+    }
 }
 /** `client.auth` — the auth namespace. Strategies hang off here. */
 class AuthNamespace {
@@ -3216,13 +3799,13 @@ class StorageCipher {
         const iv = randomBytes(AES_GCM_IV_BYTES);
         const plaintext = utf8Encode(JSON.stringify(value));
         const ciphertext = await encryptAesGcm(key, iv, plaintext);
-        return { _enc: "a256gcm", iv: toBase64(iv), ct: toBase64(ciphertext) };
+        return { _enc: "a256gcm", iv: toBase64$1(iv), ct: toBase64$1(ciphertext) };
     }
     /** Open an {@link EncryptedEnvelope} back into the original value. */
     async decrypt(envelope) {
         const key = await this.keyPromise;
-        const iv = fromBase64(envelope.iv);
-        const ciphertext = fromBase64(envelope.ct);
+        const iv = fromBase64$1(envelope.iv);
+        const ciphertext = fromBase64$1(envelope.ct);
         const plaintext = await decryptAesGcm(key, iv, ciphertext);
         return JSON.parse(utf8Decode(plaintext));
     }
@@ -3674,6 +4257,92 @@ class KvNamespace {
     }
 }
 
+/**
+ * `client.db` — the app's scalable database. A developer defines tables in the
+ * Muhkoo portal (columns + indexes); each table is backed by its own Durable
+ * Object SQLite instance and reachable through a sanitized REST gateway. This
+ * namespace wraps that gateway:
+ *
+ *   const todos = client.db.table('todos');
+ *   const { id } = await todos.insert({ title: 'Buy milk', done: false });
+ *   const one    = await todos.get(id);
+ *   const { rows, nextCursor } = await todos.query({
+ *     where: [{ column: 'done', op: 'eq', value: false }],
+ *     orderBy: { column: 'rank', dir: 'asc' },
+ *     limit: 50,
+ *   });
+ *   await todos.update(id, { done: true });
+ *   await todos.delete(id);
+ *
+ * Authorization is the **app key** ({@link HttpClient} stamps it on every
+ * request); the appId + environment are resolved server-side from the key, so a
+ * key can only ever reach its own app's tables. The front end never touches the
+ * database directly — this REST surface is the only gateway, and all input is
+ * validated against the table's schema (parameterized statements, column +
+ * operator allowlists). There is no raw-SQL passthrough.
+ *
+ * Schema is authored in the portal, not here (the SDK reads + writes rows, it
+ * doesn't create tables). Pagination is keyset-based: pass the `nextCursor` from
+ * a previous `query()` back as `cursor` to fetch the next page.
+ */
+/** A handle to one table — the ergonomic surface for row operations. */
+class DbTable {
+    http;
+    name;
+    constructor(http, name) {
+        this.http = http;
+        this.name = name;
+    }
+    base() {
+        return `/api/db/${encodeURIComponent(this.name)}`;
+    }
+    /** Insert a row. Returns the created row and its primary-key value. */
+    async insert(values) {
+        return this.http.post(this.base(), { values });
+    }
+    /** Fetch a row by primary key, or `null` if it doesn't exist. */
+    async get(id) {
+        try {
+            const res = await this.http.get(`${this.base()}/${encodeURIComponent(String(id))}`);
+            return res.row;
+        }
+        catch (e) {
+            if (e?.status === 404)
+                return null;
+            throw e;
+        }
+    }
+    /** Query rows with filters, ordering, and keyset pagination. */
+    async query(query = {}) {
+        return this.http.post(`${this.base()}/query`, query);
+    }
+    /** Update a row by primary key. Returns the updated row. */
+    async update(id, values) {
+        return this.http.patch(`${this.base()}/${encodeURIComponent(String(id))}`, { values });
+    }
+    /** Delete a row by primary key. Returns the number of rows removed (0 or 1). */
+    async delete(id) {
+        const res = await this.http.del(`${this.base()}/${encodeURIComponent(String(id))}`);
+        return res.deleted ?? 0;
+    }
+}
+class DbNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * A handle to a table defined in the portal. The optional type parameter
+     * gives row operations a typed shape:
+     *
+     *   interface Todo { _id: number; title: string; done: boolean }
+     *   const todos = client.db.table<Todo>('todos');
+     */
+    table(name) {
+        return new DbTable(this.deps.http, name);
+    }
+}
+
 /**
  * Wire types for the storage layer.
  *
@@ -5248,12 +5917,12 @@ function canonicalMessage(fields) {
 /** Sign the canonical bytes with the sender's ECDSA identity private key. */
 async function signSpaceMessage(canonical, ecdsaPriv) {
     const sig = await getSubtle().sign(ECDSA_SIGN, ecdsaPriv, utf8Encode(canonical));
-    return toBase64(new Uint8Array(sig));
+    return toBase64$1(new Uint8Array(sig));
 }
 /** Verify a signature over the canonical bytes against the sender's ECDSA key. */
 async function verifySpaceMessage(canonical, sigB64, ecdsaPub) {
     try {
-        return await getSubtle().verify(ECDSA_SIGN, ecdsaPub, fromBase64(sigB64), utf8Encode(canonical));
+        return await getSubtle().verify(ECDSA_SIGN, ecdsaPub, fromBase64$1(sigB64), utf8Encode(canonical));
     }
     catch {
         return false;
@@ -5289,8 +5958,8 @@ async function wrapSpaceKey(kSpace, epoch, recipientEcdhPub) {
     return {
         epoch,
         ephemeralPub: await exportEcdhPublicKey(eph.publicKey),
-        iv: toBase64(iv),
-        ciphertext: toBase64(ciphertext),
+        iv: toBase64$1(iv),
+        ciphertext: toBase64$1(ciphertext),
         alg: WRAP_ALG,
     };
 }
@@ -5302,7 +5971,7 @@ async function unwrapSpaceKey(wrapped, ownEcdhPriv) {
     const ephPub = await importEcdhPublicKey(wrapped.ephemeralPub);
     const shared = new Uint8Array(await getSubtle().deriveBits({ name: "ECDH", public: ephPub }, ownEcdhPriv, P384_BITS));
     const wrapKey = await deriveBitsHkdf(shared, WRAP_INFO, AES_GCM_KEY_BYTES, utf8Encode(`epoch:${wrapped.epoch}`));
-    return decryptAesGcm(wrapKey, fromBase64(wrapped.iv), fromBase64(wrapped.ciphertext));
+    return decryptAesGcm(wrapKey, fromBase64$1(wrapped.iv), fromBase64$1(wrapped.ciphertext));
 }
 // ---------------------------------------------------------------------------
 // Message sealing
@@ -5311,14 +5980,14 @@ async function unwrapSpaceKey(wrapped, ownEcdhPriv) {
 async function sealSerialized(kSpace, serialized) {
     const iv = randomBytes(AES_GCM_IV_BYTES);
     const ciphertext = await encryptAesGcm(kSpace, iv, utf8Encode(serialized));
-    return { iv: toBase64(iv), ciphertext: toBase64(ciphertext) };
+    return { iv: toBase64$1(iv), ciphertext: toBase64$1(ciphertext) };
 }
 /**
  * Open a sealed payload back into its serialized message string. Throws (GCM
  * tag failure) on the wrong group key or a tampered ciphertext.
  */
 async function openSerialized(kSpace, iv, ciphertext) {
-    const plaintext = await decryptAesGcm(kSpace, fromBase64(iv), fromBase64(ciphertext));
+    const plaintext = await decryptAesGcm(kSpace, fromBase64$1(iv), fromBase64$1(ciphertext));
     return utf8Decode(plaintext);
 }
 
@@ -6110,7 +6779,7 @@ class SpaceKeyring {
         if (!cached)
             return false;
         for (const [epochStr, b64] of Object.entries(cached)) {
-            this.keys.set(Number(epochStr), fromBase64(b64));
+            this.keys.set(Number(epochStr), fromBase64$1(b64));
         }
         this.epoch = Math.max(0, ...Array.from(this.keys.keys()));
         return this.keys.size > 0;
@@ -6120,7 +6789,7 @@ class SpaceKeyring {
             return;
         const out = {};
         for (const [epoch, key] of this.keys)
-            out[String(epoch)] = toBase64(key);
+            out[String(epoch)] = toBase64$1(key);
         // Best-effort: caching is an optimization; a write failure (e.g. locked
         // storage) must not break key acquisition.
         try {
@@ -6596,8 +7265,13 @@ class SpaceNamespace {
  * (viewers can read). Authorization rides the user session token; non-owner
  * editors pass their management Space via `opts.space`.
  *
- * v1 is "prompts + persona": a system prompt, a model, named prompt `skills`,
- * and `triggers` that decide when the agent speaks. No tools, no code.
+ * An agent is "prompts + persona": a system prompt, a model, named prompt
+ * `skills`, and `triggers` that decide when it speaks — plus optional `tools`
+ * that let it act on the app (query/write its database, call its functions,
+ * resolve its channels) via a server-side function-calling loop. See
+ * {@link AgentToolsConfig}. Pair with the `@MuhkooAgent`/`@MuhkooSpace`/
+ * `@MuhkooDB`/`@MuhkooFunction` decorators + `ejectAgentPrompt`/`ejectAgentTools`
+ * to generate `systemPrompt` and `tools` straight from your app's surface.
  */
 class AgentsNamespace {
     deps;
@@ -6745,6 +7419,8 @@ class Client {
     auth;
     /** Per-user key/value storage — `client.kv.set(...)`, etc. */
     kv;
+    /** App scalable database — `client.db.table('todos').query(...)`, etc. */
+    db;
     /** File storage — `client.storage.writeFile(...)`, etc. */
     storage;
     /** Realtime messaging — `client.message.subscribe(...)`, etc. */
@@ -6762,6 +7438,13 @@ class Client {
     /** Shared in-flight recovery so a burst of 401s triggers one re-auth. */
     recoverInFlight = null;
     constructor(options = {}) {
+        // Build stamp — always logged (independent of logLevel) so the running
+        // build is identifiable in the console. Catches stale cached bundles
+        // during development; bump `VERSION` (and package.json) each build.
+        try {
+            console.info(`[@muhkoo/connect] initialized — v${VERSION}`);
+        }
+        catch { /* console may be unavailable in some runtimes */ }
         if (options.logLevel && typeof globalThis.appLogger?.setLevel === "function") {
             globalThis.appLogger.setLevel(options.logLevel);
         }
@@ -6782,6 +7465,7 @@ class Client {
         const wsBaseUrl = toWsBase(this.baseUrl);
         this.auth = new AuthNamespace({ auth: authClient, circuits, session: this.session });
         this.kv = new KvNamespace({ http: this.http, session: this.session, wsBaseUrl });
+        this.db = new DbNamespace({ http: this.http });
         this.storage = new StorageNamespace({ http: this.http, baseUrl: this.baseUrl, kv: this.kv });
         this.message = new MessageNamespace({ http: this.http, session: this.session, wsBaseUrl });
         // Group keys are cached in the user's PersonalSpace (encrypted at rest
@@ -6852,6 +7536,177 @@ class Client {
     }
 }
 
+/**
+ * Muhkoo app decorators — declare your app's agent-facing surface in code, then
+ * "eject" a system prompt you hand to a Programmable Agent.
+ *
+ * You annotate a plain class with `@MuhkooAgent` (the app's identity + how the
+ * agent should behave) plus per-surface decorators — `@MuhkooSpace`,
+ * `@MuhkooDB`, `@MuhkooFunction` — that describe what each channel, table, and
+ * function is *for*. {@link ejectAgentPrompt} reads those annotations and
+ * produces a `systemPrompt` string:
+ *
+ * ```ts
+ * @MuhkooAgent({
+ *   name: "Chat Assistant",
+ *   purpose: "A helpful assistant inside a real-time team chat.",
+ *   guidance: ["Keep replies short.", "Only chime in when relevant."],
+ * })
+ * class ChatAssistant {
+ *   @MuhkooSpace({ description: "Main team discussion." })            general!: string;
+ *   @MuhkooDB({ access: "read", description: "Chat message history." }) messages!: unknown;
+ *   @MuhkooFunction({ description: "Open a support ticket." })         openTicket!: () => void;
+ * }
+ *
+ * const systemPrompt = ejectAgentPrompt(ChatAssistant);
+ * await client.agents.create({ handle: "assistant", displayName: "Assistant", systemPrompt });
+ * ```
+ *
+ * The ejected prompt owns the **semantic** layer — what the app is, how to act,
+ * and what each surface means. The Muhkoo runtime separately appends the
+ * **authoritative** roster (exact columns, function parameters, and the closed
+ * list of callable tools), so the prompt here never needs to restate schema and
+ * can't drift from it. Decorators only describe; they never change runtime
+ * behavior, so they're safe to apply to a throwaway descriptor class.
+ *
+ * Requires `experimentalDecorators` (already enabled in this package). Metadata
+ * is captured in a per-class registry — no `reflect-metadata` dependency.
+ */
+// Per-class metadata store, keyed by the class constructor. Member decorators
+// run during class-body evaluation (before the class decorator), so each
+// decorator get-or-creates the descriptor and they all converge on one entry.
+const REGISTRY = new WeakMap();
+function descriptorFor(ctor) {
+    let d = REGISTRY.get(ctor);
+    if (!d) {
+        d = { spaces: [], tables: [], functions: [] };
+        REGISTRY.set(ctor, d);
+    }
+    return d;
+}
+/** Resolve the owning class constructor from a decorator `target` — the
+ *  prototype for instance members, the constructor itself for static ones. */
+function ctorOf(target) {
+    return typeof target === "function" ? target : target.constructor;
+}
+/**
+ * Class decorator. Declares the app's agent identity, purpose, and behavioral
+ * guidance. Apply it to the class whose members carry the surface decorators.
+ */
+function MuhkooAgent(meta) {
+    return (target) => {
+        descriptorFor(target).agent = meta;
+    };
+}
+/** Member decorator. Marks a channel/Space the agent can resolve and post to. */
+function MuhkooSpace(meta) {
+    return ((target, propertyKey) => {
+        descriptorFor(ctorOf(target)).spaces.push({
+            name: meta.name ?? String(propertyKey),
+            description: meta.description,
+        });
+    });
+}
+/** Member decorator. Marks an app database table the agent can query/mutate. */
+function MuhkooDB(meta) {
+    return ((target, propertyKey) => {
+        descriptorFor(ctorOf(target)).tables.push({
+            table: meta.table ?? String(propertyKey),
+            access: meta.access ?? "read",
+            description: meta.description,
+        });
+    });
+}
+/** Member decorator. Marks a serverless function the agent can call. */
+function MuhkooFunction(meta) {
+    return ((target, propertyKey) => {
+        descriptorFor(ctorOf(target)).functions.push({
+            name: meta.name ?? String(propertyKey),
+            description: meta.description,
+        });
+    });
+}
+/** Read back the raw descriptor a class accumulated (for tooling/tests). */
+function getMuhkooAppDescriptor(appClass) {
+    return REGISTRY.get(appClass);
+}
+/**
+ * Compose the agent system prompt from a `@MuhkooAgent`-decorated class. Throws
+ * if the class isn't decorated. The result is the semantic layer only — the
+ * runtime appends exact schema + the closed tool list at invocation time.
+ */
+function ejectAgentPrompt(appClass) {
+    const d = REGISTRY.get(appClass);
+    if (!d || !d.agent) {
+        throw new Error("ejectAgentPrompt: the class must be decorated with @MuhkooAgent");
+    }
+    const { agent } = d;
+    const lines = [];
+    lines.push(`You are ${agent.name}. ${agent.purpose}`.trim());
+    if (agent.guidance?.length) {
+        lines.push("", "Guidance:");
+        for (const g of agent.guidance)
+            lines.push(`- ${g}`);
+    }
+    if (d.spaces.length) {
+        lines.push("", "Channels (Spaces) you can resolve with resolve_channel and post messages into:");
+        for (const s of d.spaces)
+            lines.push(`- ${s.name}: ${s.description}`);
+    }
+    if (d.tables.length) {
+        lines.push("", "App database tables:");
+        for (const t of d.tables) {
+            const verbs = t.access === "write"
+                ? "read & write — db_query/db_get/db_insert/db_update/db_delete"
+                : "read-only — db_query/db_get";
+            lines.push(`- ${t.table} (${verbs}): ${t.description}`);
+        }
+    }
+    if (d.functions.length) {
+        lines.push("", "Functions you can invoke with call_function:");
+        for (const f of d.functions)
+            lines.push(`- ${f.name}: ${f.description}`);
+    }
+    if (agent.instructions?.trim()) {
+        lines.push("", agent.instructions.trim());
+    }
+    // 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;
+    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.");
+    }
+    lines.push("- Always end your turn with a short written reply (one or two sentences). Never finish with only tool calls and no message, and never reply with an empty message.", "- Don't restate function names, parameters, JSON, or your list of tools to the user — just give them the answer.");
+    lines.push("", "The exact columns, function parameters, and the full list of callable tools are supplied to you by the runtime. Follow that authoritative list — never invent tables, columns, functions, or tools.");
+    return lines.join("\n");
+}
+/**
+ * Derive a suggested tools allowlist from a decorated class — the db tables
+ * (and whether any are writable), the callable functions, and whether channels
+ * are in play. Pair with {@link ejectAgentPrompt} when configuring the agent.
+ *
+ * If any tables/functions are present the result has `enabled: true`; to
+ * actually grant tools you must also pass a function-calling `model` in the same
+ * `client.agents.create`/`update` call (the server enforces this).
+ */
+function ejectAgentTools(appClass, opts) {
+    const d = REGISTRY.get(appClass);
+    if (!d) {
+        throw new Error("ejectAgentTools: the class must be decorated with @MuhkooAgent");
+    }
+    const anyWrite = d.tables.some((t) => t.access === "write");
+    const mode = d.tables.length === 0 ? "off" : anyWrite ? "write" : "read";
+    return {
+        enabled: d.tables.length > 0 || d.functions.length > 0 || d.spaces.length > 0,
+        db: { mode, tables: d.tables.map((t) => t.table) },
+        functions: d.functions.map((f) => f.name),
+        channels: d.spaces.length > 0,
+        maxIterations: opts?.maxIterations ?? 6,
+    };
+}
+
 const appLogger$1 = new Logger("connect", 'ERROR');
 globalThis.appLogger = appLogger$1;
 
@@ -7388,5 +8243,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, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, compilePrograms, concatBytes, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deserialize, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateId, getIPAddress, getId, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNumber, log, manifestToStat, poseidonHash, quickVerify, randomBytes, serialize, shardHash, signMessage, toBase64, toBase64Url, toField, toHex, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
+export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DbNamespace, DbTable, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, VERSION, VaultUnavailableError, WSTransport, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, compilePrograms, concatBytes, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, ejectAgentPrompt, ejectAgentTools, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, fromBase64$1 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateId, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNumber, log, manifestToStat, poseidonHash, quickVerify, randomBytes, serialize, shardHash, signMessage, toBase64$1 as toBase64, toBase64Url, toField, toHex, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
 //# sourceMappingURL=index.js.map