@muhkoo/connect 0.6.0-alpha.11 → 0.7.0-alpha.4

package/dist/server/index.js

@@ -1,9 +1,9 @@
 import { prove, verify as verify$1 } from '@zk-kit/groth16';
 import { p256 } from '@noble/curves/nist.js';
 import { buildPoseidon } from 'circomlibjs';
+import { scrypt } from '@noble/hashes/scrypt.js';
 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';
 
 /**
@@ -2380,14 +2380,75 @@ class AuthClient {
         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 }));
+    /**
+     * Gated split-key OPRF evaluation (M2 — email/google factors). Requires a
+     * live `verifyToken` from {@link emailOtpVerify}; returns BOTH trust
+     * domains' evaluations. The recover token is consumed by this call.
+     */
+    async oprfEvaluateGated(username, blinded, factorType, purpose, verifyToken) {
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/oprf`, this.json("POST", { username, blinded, factorType, purpose, verifyToken }));
+        return await this.parse("oprfEvaluateGated", res);
+    }
+    /**
+     * Request an email OTP. With a session `token` this is the ENROLL flow
+     * (code sent to `email`); without one it's RECOVER (code sent to the
+     * account's enrolled address — the response is uniform either way).
+     */
+    async emailOtpStart(opts) {
+        const init = this.json("POST", { email: opts.email, username: opts.username });
+        if (opts.token)
+            init.headers["X-Muhkoo-Session"] = opts.token;
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/email/start`, init);
+        await this.parse("emailOtpStart", res);
+    }
+    /** Trade an emailed code for a single-use verifyToken (+ the proven address). */
+    async emailOtpVerify(opts) {
+        const init = this.json("POST", { code: opts.code, username: opts.username });
+        if (opts.token)
+            init.headers["X-Muhkoo-Session"] = opts.token;
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/email/verify`, init);
+        return await this.parse("emailOtpVerify", res);
+    }
+    /**
+     * Verify a Google ID token (M2.3). With a session `token` it's the ENROLL
+     * gate; without, it's RECOVER/LOGIN (the Google account must already be
+     * linked). Returns a single-use verifyToken bound to the account's `sub`.
+     */
+    async googleVerify(opts) {
+        const init = this.json("POST", { idToken: opts.idToken, username: opts.username });
+        if (opts.token)
+            init.headers["X-Muhkoo-Session"] = opts.token;
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/google/verify`, init);
+        return await this.parse("googleVerify", res);
+    }
+    // ---- Hosted-auth authorization-code flow (H0) ---------------------------
+    /** Mint a single-use authorization code for an app (called by the hosted page; session-authed). */
+    async grant(token, body) {
+        const init = this.json("POST", body);
+        init.headers["X-Muhkoo-Session"] = token;
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/grant`, init);
+        return await this.parse("grant", res);
+    }
+    /** Exchange an authorization code + PKCE verifier for the session + sealed key material. */
+    async token(body) {
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/token`, this.json("POST", body));
+        return await this.parse("token", res);
+    }
+    /**
+     * Read a factor record for `username` (returns an indistinguishable decoy if
+     * absent). Gated types (email) require the recover `verifyToken`.
+     */
+    async vaultRead(username, factorType, verifyToken) {
+        const res = await this.fetchFn(`${this.baseUrl}/api/auth/vault`, this.json("POST", { username, factorType, verifyToken }));
         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 });
+    /**
+     * Add/replace a factor (session-authed; the seed is already wrapped
+     * client-side). Email factors additionally require (and consume) the
+     * enroll `verifyToken`; the stored address must be the verified one.
+     */
+    async vaultPutFactor(token, factor, verifyToken) {
+        const init = this.json("PUT", { factor, verifyToken });
         init.headers["Authorization"] = `Bearer ${token}`;
         const res = await this.fetchFn(`${this.baseUrl}/api/auth/vault/factor`, init);
         return await this.parse("vaultPutFactor", res);
@@ -2777,6 +2838,129 @@ async function signMessage(message, privateKey) {
     return bytesToBase64(new Uint8Array(sig));
 }
 
+/**
+ * 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$1 = 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$1.encode(password), TE$1.encode("muhkoo-vault-v1:" + username.toLowerCase()), SCRYPT);
+}
+/** HKDF the 64-byte OPRF output into a non-extractable AES-256-GCM wrap key. */
+async function wrapKeyFromOprf(oprfOutput) {
+    const prk = await crypto.subtle.importKey("raw", oprfOutput, { name: "HKDF" }, false, ["deriveKey"]);
+    return crypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(), info: TE$1.encode("muhkoo-vault-wrap") }, prk, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
+/** HKDF arbitrary 32-byte key material (e.g. a passkey PRF output) into an AES-GCM wrap key. */
+async function wrapKeyFromBytes(keyMaterial, info) {
+    const prk = await crypto.subtle.importKey("raw", keyMaterial, { name: "HKDF" }, false, ["deriveKey"]);
+    return crypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(), info: TE$1.encode(info) }, prk, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
+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;
+}
+
+/**
+ * Hosted-auth handoff crypto (auth.muhkoo.dev — AUTH_HOSTED_PLAN.md §3).
+ *
+ * The hosted page authenticates the user and ends up holding the master seed.
+ * To pass it to the developer's app without it ever sitting server-readable or
+ * landing in browser history:
+ *
+ *   1. {@link sealSeed} generates a one-time key K_t, AES-256-GCM-seals the seed
+ *      under it, and returns the ciphertext envelope (`sealedKeys`, stored in
+ *      the grant the server relays but can't read) plus K_t (`fragmentKey`,
+ *      placed ONLY in the redirect URL fragment — fragments never hit a server).
+ *   2. The app exchanges the code for `sealedKeys`, reads K_t from the fragment,
+ *      and {@link unsealSeed} recovers the seed, then strips the fragment.
+ *
+ * Trust-equivalent to today's embedded SDK (the app still ends up with the
+ * seed) while moving credential entry onto the Muhkoo origin. The envelope is
+ * versioned so a future per-app-key handoff (v2) can swap in without a protocol
+ * change.
+ */
+const TE = new TextEncoder();
+const TD = new TextDecoder();
+/** Seal the master seed under a fresh one-time key for the redirect handoff. */
+async function sealSeed(seed) {
+    const ktRaw = crypto.getRandomValues(new Uint8Array(32));
+    const key = await crypto.subtle.importKey("raw", ktRaw, { name: "AES-GCM" }, false, ["encrypt"]);
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ct = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, key, seed));
+    const envelope = { v: 1, iv: toBase64(iv), ct: toBase64(ct) };
+    return {
+        sealedKeys: toBase64(TE.encode(JSON.stringify(envelope))),
+        fragmentKey: base64UrlEncode(ktRaw),
+    };
+}
+/** Recover the master seed from the sealed envelope + the fragment key. */
+async function unsealSeed(sealedKeys, fragmentKey) {
+    const envelope = JSON.parse(TD.decode(fromBase64(sealedKeys)));
+    if (envelope.v !== 1)
+        throw new Error(`Unsupported handoff envelope version ${envelope.v}`);
+    const ktRaw = base64UrlDecode(fragmentKey);
+    const key = await crypto.subtle.importKey("raw", ktRaw, { name: "AES-GCM" }, false, ["decrypt"]);
+    const seed = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64(envelope.iv) }, key, fromBase64(envelope.ct));
+    return new Uint8Array(seed);
+}
+/** Generate a PKCE verifier + S256 challenge for the authorize→token exchange. */
+async function generatePkce() {
+    const codeVerifier = base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", TE.encode(codeVerifier)));
+    return { codeVerifier, codeChallenge: base64UrlEncode(digest) };
+}
+/** A random URL-safe value for the OAuth `state` (CSRF binding on the callback). */
+function randomState() {
+    return base64UrlEncode(crypto.getRandomValues(new Uint8Array(16)));
+}
+function base64UrlEncode(bytes) {
+    return toBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(s) {
+    return fromBase64(s.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(s.length / 4) * 4, "="));
+}
+
 /**
  * SDK build version — stamped to the console when a {@link Client} is created.
  *
@@ -2785,7 +2969,7 @@ async function signMessage(message, privateKey) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.6.0-alpha.11";
+const VERSION = "0.7.0-alpha.4";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -3100,69 +3284,6 @@ function mnemonicToSeed(mnemonic) {
     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.
  *
@@ -3196,6 +3317,55 @@ function oprfFinalize(input, blind, evaluated) {
     return OPRF.finalize(input, blind, evaluated);
 }
 
+/**
+ * Verification-gated vault factors (M2 — email, later Google).
+ *
+ * These factors have NO client-side secret: the user proves *channel control*
+ * (an email OTP) and the server releases a split-key OPRF evaluation —
+ * `wrapKey = HKDF( OPRF(K1, input) ‖ OPRF(K2, input) )` where K1 lives on the
+ * accelerator and K2 in a separate trust domain, so no single server-side
+ * compromise can derive the wrap key offline. See accelerator
+ * `AUTH_M2_PLAN.md` §1; the canonical reference implementation is
+ * accelerator `tests/gated-oprf.test.ts` — keep these derivations in
+ * byte-exact lockstep with it.
+ */
+/**
+ * Deterministic OPRF input for an email factor. Public-ish by design (the
+ * verification gate, not the input, is what protects the eval) — but it must
+ * be stable forever: username + address are lowercased, the tag is versioned.
+ */
+async function emailFactorInput(username, email) {
+    const tag = `muhkoo/factor:email:v1:${username.toLowerCase()}:${email.toLowerCase()}`;
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(tag));
+    return new Uint8Array(digest);
+}
+/**
+ * Deterministic OPRF input for a google factor — keyed on the stable Google
+ * account id (`sub`), not the email (which can change). Same versioning rules
+ * as {@link emailFactorInput}.
+ */
+async function googleFactorInput(username, sub) {
+    const tag = `muhkoo/factor:google:v1:${username.toLowerCase()}:${sub}`;
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(tag));
+    return new Uint8Array(digest);
+}
+/** Blind a gated input for the split eval (same blind serves both domains). */
+function gatedBlind(input) {
+    return oprfBlind(input);
+}
+/**
+ * Fold the two domains' evaluations into the AES-256-GCM wrap key:
+ * unblind each, concatenate, HKDF with the gated-factor domain separation.
+ */
+async function gatedWrapKey(input, blind, evaluatedB64, evaluated2B64) {
+    const out1 = oprfFinalize(input, blind, fromBase64(evaluatedB64));
+    const out2 = oprfFinalize(input, blind, fromBase64(evaluated2B64));
+    const ikm = new Uint8Array(out1.length + out2.length);
+    ikm.set(out1);
+    ikm.set(out2, out1.length);
+    return wrapKeyFromBytes(ikm, "muhkoo-gated-wrap-v1");
+}
+
 /**
  * Passkey factor (M1.1) — WebAuthn with the **PRF extension**.
  *
@@ -3313,6 +3483,160 @@ async function evaluatePasskeyPrf(rpId, credentialId, salt) {
     return new Uint8Array(results.first);
 }
 
+/**
+ * `client.auth.hosted` — centralized hosted auth (auth.muhkoo.dev).
+ * AUTH_HOSTED_PLAN.md.
+ *
+ * Two sides share this class:
+ *   - **Developer apps** call {@link login} (redirect to the hosted page) and
+ *     {@link handleCallback} (exchange the returned code → session + seed). The
+ *     app carries no snarkjs and never sees the user's credentials.
+ *   - **The hosted page** (the muhkoo/auth SPA), once it has authenticated the
+ *     user via the normal `client.auth.zk.*` flow, calls
+ *     {@link completeAuthorize} to seal the seed, mint the grant, and build the
+ *     redirect-back URL.
+ *
+ * Flow (authorization-code + PKCE + sealed-seed handoff):
+ *   app  →  GET  auth.muhkoo.dev/authorize?app_id&redirect_uri&state&code_challenge
+ *   page →  (user authenticates) → POST /api/auth/grant → redirect_uri?code&state#k=<K_t>
+ *   app  →  POST /api/auth/token {code, code_verifier} → {sessionToken, sealedKeys}
+ *        →  unseal sealedKeys with K_t → master seed → session ready
+ */
+const PKCE_STORE_KEY = "muhkoo.hosted.pkce";
+class HostedAuth {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * (App side) Begin hosted login: stash a PKCE verifier + state, then send
+     * the browser to the hosted authorize page. Returns the URL it redirects to
+     * (also useful for popup mode / tests). `redirectUri` must be registered for
+     * the app in the portal.
+     */
+    async login(opts) {
+        const { codeVerifier, codeChallenge } = await generatePkce();
+        const state = randomState();
+        this.store({ codeVerifier, state, appId: opts.appId, redirectUri: opts.redirectUri });
+        const url = `${this.deps.authBaseUrl}/authorize?` + new URLSearchParams({
+            app_id: opts.appId,
+            redirect_uri: opts.redirectUri,
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: "S256",
+        }).toString();
+        if (opts.redirect !== false)
+            this.location().assign(url);
+        return url;
+    }
+    /**
+     * (App side) Send the user to centralized account & security management on
+     * the hosted page (auth.muhkoo.dev/security) — manage passkeys, recovery
+     * phrase, email, Google, change password, and remove login methods, all in
+     * one place. `returnUri` (default: the current URL) gives the hosted page a
+     * "Back to app" target. Redirects the browser; resolves to the URL.
+     */
+    async manageAccount(opts = {}) {
+        const ret = opts.returnUri ?? this.location().href;
+        const url = `${this.deps.authBaseUrl}/security?` + new URLSearchParams({ return: ret }).toString();
+        this.location().assign(url);
+        return url;
+    }
+    /** Whether the current URL looks like a hosted-auth callback (has code + state). */
+    isCallback() {
+        try {
+            const q = new URLSearchParams(this.location().search);
+            return q.has("code") && q.has("state");
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * (App side) Complete login on the callback URL: verify state, exchange the
+     * code (+ PKCE verifier) for the session, unseal the seed from the fragment,
+     * establish the session, and scrub the URL. Returns the signed-in user.
+     */
+    async handleCallback() {
+        const loc = this.location();
+        const query = new URLSearchParams(loc.search);
+        const code = query.get("code");
+        const state = query.get("state");
+        const fragmentKey = new URLSearchParams(loc.hash.replace(/^#/, "")).get("k");
+        if (!code || !state)
+            throw new Error("Not a hosted-auth callback.");
+        if (!fragmentKey)
+            throw new Error("Missing handoff key — the login link was altered.");
+        const stash = this.take();
+        if (!stash || stash.state !== state)
+            throw new Error("State mismatch — possible CSRF; start login again.");
+        const res = await this.deps.auth.token({ code, codeVerifier: stash.codeVerifier, appId: stash.appId });
+        const seed = await unsealSeed(res.sealedKeys, fragmentKey);
+        const identity = await deriveIdentityFromSeed(seed);
+        await this.deps.session.setSession({ token: res.sessionToken, username: res.username, commitment: res.commitment });
+        this.deps.session.setIdentity(identity);
+        this.deps.session.setSeed(seed);
+        this.scrubUrl();
+        return { username: res.username, commitment: res.commitment };
+    }
+    /**
+     * (Hosted-page side) Finish an /authorize request after the user has
+     * authenticated here: seal the in-memory seed, mint the grant, and return
+     * the URL to redirect the browser back to. The seed must be held (the user
+     * just signed in via `client.auth.zk.*`).
+     */
+    async completeAuthorize(opts) {
+        const token = this.deps.session.token;
+        const seed = this.deps.session.seed;
+        if (!token || !seed)
+            throw new Error("Authenticate the user before completing authorization.");
+        const { sealedKeys, fragmentKey } = await sealSeed(seed);
+        const { code } = await this.deps.auth.grant(token, {
+            appId: opts.appId, redirectUri: opts.redirectUri, codeChallenge: opts.codeChallenge, sealedKeys,
+        });
+        const url = new URL(opts.redirectUri);
+        url.searchParams.set("code", code);
+        url.searchParams.set("state", opts.state);
+        url.hash = `k=${fragmentKey}`;
+        return url.toString();
+    }
+    // ---- internals ----------------------------------------------------------
+    location() {
+        const loc = globalThis.location;
+        if (!loc)
+            throw new Error("Hosted auth requires a browser environment.");
+        return loc;
+    }
+    store(v) {
+        const ss = globalThis.sessionStorage;
+        if (!ss)
+            throw new Error("Hosted auth requires sessionStorage.");
+        ss.setItem(PKCE_STORE_KEY, JSON.stringify(v));
+    }
+    take() {
+        const ss = globalThis.sessionStorage;
+        if (!ss)
+            return null;
+        const raw = ss.getItem(PKCE_STORE_KEY);
+        if (!raw)
+            return null;
+        ss.removeItem(PKCE_STORE_KEY);
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Drop `code`, `state`, and the `#k` fragment from the address bar. */
+    scrubUrl() {
+        const h = globalThis.history;
+        const loc = this.location();
+        if (h?.replaceState)
+            h.replaceState(null, "", loc.pathname);
+    }
+}
+
 /**
  * `client.auth` — user authentication, exposed today through the `zk`
  * sub-namespace (`client.auth.zk.login(...)`). Leaving room under `auth` for
@@ -3561,6 +3885,137 @@ class ZkAuth {
         this.deps.session.setSeed(seed);
         return user;
     }
+    /**
+     * Add an **email** as a recovery + login factor (M2 verification-gated:
+     * the server only releases the split-key OPRF eval after the address is
+     * OTP-verified). Sends the code, then returns a `confirm` continuation:
+     *
+     *   const { confirm } = await client.auth.zk.enrollEmailFactor("me@x.com");
+     *   await confirm(codeFromInbox);
+     *
+     * Requires being signed in with the seed held (like the other enrolls).
+     * Custody note: gated factors trade some custody for recoverability — the
+     * trade-off should be disclosed in the enroll UI.
+     */
+    async enrollEmailFactor(email) {
+        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 recovery email.");
+        }
+        await this.deps.auth.emailOtpStart({ token, email });
+        return {
+            email,
+            confirm: async (code) => {
+                const { verifyToken, email: verified } = await this.deps.auth.emailOtpVerify({ token, code });
+                const input = await emailFactorInput(username, verified);
+                const { blind, blinded } = gatedBlind(input);
+                const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64(blinded), "email", "enroll", verifyToken);
+                const key = await gatedWrapKey(input, blind, evals.evaluated, evals.evaluated2);
+                const wrapped = await wrapSeed(seed, key);
+                await this.deps.auth.vaultPutFactor(token, { id: "email", type: "email", wrap: wrapped.ct, iv: wrapped.iv, params: { email: verified }, createdAt: Date.now() }, verifyToken);
+            },
+        };
+    }
+    /**
+     * Recover an account via its enrolled **email** factor. Sends a code to the
+     * enrolled address (the response never reveals whether one exists), then
+     * `confirm(code)` completes: gated read + split-key eval → unwrap seed →
+     * normal ZK login. After this, call {@link changePassword} to set a new
+     * password.
+     *
+     *   const { confirm } = await client.auth.zk.recoverWithEmail("alice");
+     *   const user = await confirm(codeFromInbox);
+     */
+    async recoverWithEmail(username, opts = {}) {
+        await this.deps.auth.emailOtpStart({ username });
+        return {
+            confirm: async (code) => {
+                const { verifyToken, email } = await this.deps.auth.emailOtpVerify({ username, code });
+                const { factor } = await this.deps.auth.vaultRead(username, "email", verifyToken);
+                if (!factor?.wrap || !factor?.iv) {
+                    throw new Error("This account has no email recovery set up.");
+                }
+                const input = await emailFactorInput(username, email);
+                const { blind, blinded } = gatedBlind(input);
+                const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64(blinded), "email", "recover", verifyToken);
+                const key = await gatedWrapKey(input, blind, evals.evaluated, evals.evaluated2);
+                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;
+            },
+        };
+    }
+    // --- Google factor (M2.3) ------------------------------------------------
+    // Google is pure authentication UX: its verified ID token gates the
+    // split-key OPRF eval that releases the master seed. The ZK identity layer
+    // is unchanged. The app obtains `idToken` via Google Identity Services and
+    // passes it in; the SDK never renders Google UI.
+    /**
+     * Link a Google account as a recovery + login factor. Requires being signed
+     * in with the seed held. `idToken` is a fresh Google ID token (GIS).
+     */
+    async enrollGoogleFactor(idToken) {
+        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 link a Google account.");
+        const { verifyToken, sub, emailHint } = await this.deps.auth.googleVerify({ idToken, token });
+        const input = await googleFactorInput(username, sub);
+        const { blind, blinded } = gatedBlind(input);
+        const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64(blinded), "google", "enroll", verifyToken);
+        const key = await gatedWrapKey(input, blind, evals.evaluated, evals.evaluated2);
+        const wrapped = await wrapSeed(seed, key);
+        await this.deps.auth.vaultPutFactor(token, { id: "google", type: "google", wrap: wrapped.ct, iv: wrapped.iv, params: { sub, emailHint: emailHint ?? undefined }, createdAt: Date.now() }, verifyToken);
+    }
+    /**
+     * Sign in with Google — verify the ID token, unlock the seed via the gated
+     * split-key eval, and establish a session. Same machinery serves "Sign in
+     * with Google" and "recover with Google"; the account must have linked the
+     * factor first.
+     */
+    async loginWithGoogle(username, idToken, opts = {}) {
+        const { verifyToken, sub } = await this.deps.auth.googleVerify({ idToken, username });
+        const { factor } = await this.deps.auth.vaultRead(username, "google", verifyToken);
+        if (!factor?.wrap || !factor?.iv)
+            throw new Error("No Google account is linked to this username.");
+        const input = await googleFactorInput(username, sub);
+        const { blind, blinded } = gatedBlind(input);
+        const evals = await this.deps.auth.oprfEvaluateGated(username, toBase64(blinded), "google", "recover", verifyToken);
+        const key = await gatedWrapKey(input, blind, evals.evaluated, evals.evaluated2);
+        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;
+    }
+    /**
+     * Register a brand-new, **passwordless** account whose only factor is Google.
+     * A random master seed is generated and wrapped under the Google-gated key;
+     * the user can add a password / passkey / phrase later. The ZK registration
+     * is identical to a password signup.
+     */
+    async registerWithGoogle(username, idToken) {
+        const seed = randomSeed();
+        const identity = await deriveIdentityFromSeed(seed);
+        const commitment = await this.commitmentFor(identity);
+        await this.deps.auth.register({
+            username,
+            commitment,
+            ecdhPublicKey: await exportPublicKeyBase64(identity.ecdhKeyPair.publicKey),
+            ecdsaPublicKey: await exportPublicKeyBase64(identity.ecdsaKeyPair.publicKey),
+            email: null,
+        });
+        const user = await this.proveAndStore(username, identity, {});
+        this.deps.session.setSeed(seed);
+        // Enroll Google as the sole factor (session + seed are now in hand).
+        await this.enrollGoogleFactor(idToken);
+        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
@@ -3638,7 +4093,11 @@ class ZkAuth {
         this.deps.session.setSeed(seed);
         return user;
     }
-    /** List the user's enrolled login methods (metadata only). Session-authed. */
+    /**
+     * List the user's enrolled login methods (metadata only). Session-authed.
+     * Gated factors (email/google) carry a `masked` display hint
+     * ("m•••@gmail.com"); the full value is never returned.
+     */
     async listFactors() {
         const token = this.deps.session.token;
         if (!token)
@@ -3765,8 +4224,11 @@ class ZkAuth {
 /** `client.auth` — the auth namespace. Strategies hang off here. */
 class AuthNamespace {
     zk;
+    /** Centralized hosted auth (auth.muhkoo.dev) — `client.auth.hosted.login(...)`. */
+    hosted;
     constructor(deps) {
         this.zk = new ZkAuth(deps);
+        this.hosted = new HostedAuth({ auth: deps.auth, session: deps.session, authBaseUrl: deps.authBaseUrl });
     }
     /** Convenience pass-through: the currently signed-in user, or `null`. */
     get user() {
@@ -7324,6 +7786,7 @@ class AgentsNamespace {
  *   });
  *   // HTTP-reachable at  hello--<slug>.fns.muhkoo.dev
  *   await client.functions.enable(appId, config.functionId, spaceId); // Space-bound
+ *   const out = await client.functions.invoke({ name: 'hello', slug }, { body: { q: 1 } });
  *
  * These are MANAGEMENT calls — the function itself runs on the accelerator
  * (uploaded just-in-time, decrypted only at invocation). Only an app's owner or
@@ -7337,6 +7800,18 @@ class AgentsNamespace {
  * triggers: `http` (its own subdomain) and `space` (invoked on Space messages,
  * like a Programmable Agent).
  */
+/** The hosted platform's HTTP-function zone. */
+const DEFAULT_FN_HOST_SUFFIX = "fns.muhkoo.dev";
+/** Bodies `fetch` accepts natively — everything else is JSON-encoded. */
+function isRawBody(body) {
+    return (typeof body === "string" ||
+        body instanceof FormData ||
+        body instanceof Blob ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body) ||
+        body instanceof URLSearchParams ||
+        (typeof ReadableStream !== "undefined" && body instanceof ReadableStream));
+}
 class FunctionsNamespace {
     deps;
     constructor(deps) {
@@ -7375,6 +7850,71 @@ class FunctionsNamespace {
     async disable(appId, functionId, spaceId, opts = {}) {
         return this.deps.http.post(this.path(appId, `/${encodeURIComponent(functionId)}/disable`, {}), { targetSpaceId: spaceId, space: opts.space });
     }
+    /**
+     * Invoke an HTTP-triggered function and parse its JSON response.
+     *
+     *   const out = await client.functions.invoke({ name: 'hello', slug: 'myapp' });
+     *   const out = await client.functions.invoke('hello--myapp', { body: { q: 1 } });
+     *   const out = await client.functions.invoke('https://hello--myapp.fns.muhkoo.dev/x');
+     *
+     * The request carries the SDK's credentials (`X-Muhkoo-Key` and, when a
+     * user is signed in, `X-Muhkoo-Session`) — the platform passes the session
+     * token through to the function, which can verify it server-side via
+     * `POST /api/auth/verify` to establish the caller's identity.
+     *
+     * Non-2xx responses throw {@link HttpError}. For functions that return
+     * something other than JSON, use {@link invokeRaw}.
+     */
+    async invoke(target, opts = {}) {
+        const res = await this.invokeRaw(target, opts);
+        let parsed = null;
+        try {
+            parsed = await res.json();
+        }
+        catch {
+            // Non-JSON body — fall through to the status-only error below.
+        }
+        if (!res.ok) {
+            const msg = parsed && typeof parsed === "object" && "error" in parsed
+                ? String(parsed.error)
+                : `${res.status} ${res.statusText}`;
+            throw new HttpError(msg, res.status, parsed);
+        }
+        return parsed;
+    }
+    /** Invoke an HTTP-triggered function and return the raw `Response`. */
+    async invokeRaw(target, opts = {}) {
+        const init = {
+            method: opts.method ?? (opts.body !== undefined ? "POST" : "GET"),
+        };
+        const headers = new Headers(opts.headers);
+        if (opts.body !== undefined) {
+            if (isRawBody(opts.body)) {
+                init.body = opts.body;
+            }
+            else {
+                init.body = JSON.stringify(opts.body);
+                if (!headers.has("Content-Type"))
+                    headers.set("Content-Type", "application/json");
+            }
+        }
+        init.headers = headers;
+        return this.deps.http.fetch(this.invokeUrl(target, opts.path), init);
+    }
+    /** Resolve an invoke target to the function's absolute URL. */
+    invokeUrl(target, path = "") {
+        const suffix = this.deps.fnHostSuffix ?? DEFAULT_FN_HOST_SUFFIX;
+        let base;
+        if (typeof target === "string") {
+            base = /^https?:\/\//.test(target) ? target : `https://${target}.${suffix}`;
+        }
+        else {
+            base = `https://${target.name}--${target.slug}.${suffix}`;
+        }
+        if (!path)
+            return base;
+        return `${base.replace(/\/+$/, "")}${path.startsWith("/") ? "" : "/"}${path}`;
+    }
     path(appId, suffix, opts) {
         const q = opts.space ? `?space=${encodeURIComponent(opts.space)}` : "";
         return `/api/apps/${encodeURIComponent(appId)}/functions${suffix}${q}`;
@@ -7406,6 +7946,8 @@ class FunctionsNamespace {
  */
 /** The hosted Muhkoo Accelerator — the default {@link ClientOptions.baseUrl}. */
 const DEFAULT_BASE_URL = "https://api.muhkoo.dev";
+/** The hosted auth SPA — the default {@link ClientOptions.authBaseUrl}. */
+const DEFAULT_AUTH_BASE_URL = "https://auth.muhkoo.dev";
 /**
  * Turn the HTTP base URL into a websocket base (`http(s)://` → `ws(s)://`).
  * The accelerator serves spaces over both on the same origin.
@@ -7463,7 +8005,8 @@ class Client {
         const circuits = options.circuits ?? defaultCircuitUrls(this.baseUrl);
         const authClient = new AuthClient({ baseUrl: this.baseUrl, fetch: this.http.fetch });
         const wsBaseUrl = toWsBase(this.baseUrl);
-        this.auth = new AuthNamespace({ auth: authClient, circuits, session: this.session });
+        const authBaseUrl = (options.authBaseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/+$/, "");
+        this.auth = new AuthNamespace({ auth: authClient, circuits, session: this.session, authBaseUrl });
         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 });
@@ -7482,7 +8025,7 @@ class Client {
             cache: spaceKeyCache,
         });
         this.agents = new AgentsNamespace({ http: this.http });
-        this.functions = new FunctionsNamespace({ http: this.http });
+        this.functions = new FunctionsNamespace({ http: this.http, fnHostSuffix: options.functionsHostSuffix });
     }
     /** The currently signed-in user, or `null`. */
     get user() {
@@ -8243,5 +8786,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, 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 };
+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, DEFAULT_FN_HOST_SUFFIX, 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, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNumber, log, manifestToStat, poseidonHash, quickVerify, randomBytes, randomState, sealSeed, serialize, shardHash, signMessage, toBase64$1 as toBase64, toBase64Url, toField, toHex, unsealSeed, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
 //# sourceMappingURL=index.js.map