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

package/dist/browser/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';
 
 const _isTty = (() => {
     try {
@@ -259,7 +263,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]);
@@ -267,7 +271,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);
@@ -277,13 +281,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) {
@@ -1114,10 +1118,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);
     }
@@ -1948,8 +1952,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)),
         };
     }
     /**
@@ -1958,7 +1962,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
@@ -1967,7 +1971,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.
@@ -4293,6 +4297,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
     // -------------------------------------------------------------------------
@@ -4410,7 +4447,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);
@@ -4639,6 +4700,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.
@@ -4856,6 +4927,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();
@@ -4897,6 +4972,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();
@@ -4908,10 +4991,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
@@ -4928,6 +5252,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}.
@@ -4938,13 +5280,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,
@@ -4953,19 +5300,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
@@ -5063,12 +5443,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() {
@@ -5093,6 +5599,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) {
@@ -5101,6 +5617,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 {
@@ -5139,13 +5722,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));
     }
@@ -5305,6 +5888,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);
+    }
+}
+
 /**
  * `client.storage` — file storage. Hides the `FileStorage` / `ShardClient` /
  * `SharedSpaceClient` primitives behind the unified client.
@@ -5517,12 +6186,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;
@@ -5558,8 +6227,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,
     };
 }
@@ -5571,7 +6240,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
@@ -5580,14 +6249,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);
 }
 
@@ -6379,7 +7048,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;
@@ -6389,7 +7058,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 {
@@ -6865,8 +7534,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;
@@ -7014,6 +7688,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. */
@@ -7031,6 +7707,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);
         }
@@ -7051,6 +7734,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
@@ -7121,6 +7805,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,
+    };
+}
+
 /**
  * PacketCipher — the strategy `Network` uses to seal/open a packet's payload.
  *
@@ -7187,5 +8042,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, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, shardHash, signMessage, toField, unwrapWithPassphrase, verify, 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, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, VaultUnavailableError, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, ejectAgentPrompt, ejectAgentTools, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, shardHash, signMessage, toField, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
 //# sourceMappingURL=index.js.map