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

package/dist/browser/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';
 
 const _isTty = (() => {
@@ -4303,14 +4303,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);
@@ -4700,6 +4761,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.
  *
@@ -4708,7 +4892,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
@@ -5023,69 +5207,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.
  *
@@ -5119,6 +5240,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**.
  *
@@ -5236,6 +5406,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
@@ -5484,6 +5808,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
@@ -5561,7 +6016,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)
@@ -5688,8 +6147,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() {
@@ -7593,6 +8055,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
@@ -7606,6 +8069,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) {
@@ -7644,6 +8119,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}`;
@@ -7675,6 +8215,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.
@@ -7732,7 +8274,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 });
@@ -7751,7 +8294,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() {
@@ -8042,5 +8585,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, 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 };
+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_AUTH_BASE_URL, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, 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, generatePkce, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, randomState, sealSeed, shardHash, signMessage, toField, unsealSeed, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
 //# sourceMappingURL=index.js.map