@robelest/convex-auth 0.0.2-preview.1 → 0.0.2

package/dist/client/index.js

@@ -1,49 +1,111 @@
+import { ConvexHttpClient } from "convex/browser";
 const VERIFIER_STORAGE_KEY = "__convexAuthOAuthVerifier";
 const JWT_STORAGE_KEY = "__convexAuthJWT";
 const REFRESH_TOKEN_STORAGE_KEY = "__convexAuthRefreshToken";
 const RETRY_BACKOFF = [500, 2000];
 const RETRY_JITTER = 100;
-export function createAuthClient(options) {
-    const { transport, storage = typeof window === "undefined" ? null : window.localStorage, storageNamespace, replaceURL = (url) => {
-        if (typeof window !== "undefined") {
-            window.history.replaceState({}, "", url);
-        }
-    }, shouldHandleCode, onChange, } = options;
-    const escapedNamespace = storageNamespace.replace(/[^a-zA-Z0-9]/g, "");
+/**
+ * Resolve the Convex deployment URL from the client.
+ *
+ * `ConvexReactClient` exposes `.url` directly.
+ * `ConvexClient` exposes `.client.url` via `BaseConvexClient`.
+ */
+function resolveUrl(convex, explicit) {
+    if (explicit)
+        return explicit;
+    const c = convex;
+    const url = c.url ?? c.client?.url;
+    if (typeof url === "string")
+        return url;
+    throw new Error("Could not determine Convex deployment URL. Pass `url` explicitly.");
+}
+/**
+ * Create a framework-agnostic auth client.
+ *
+ * ### SPA mode (default)
+ *
+ * ```ts
+ * import { ConvexClient } from 'convex/browser'
+ * import { client } from '\@robelest/convex-auth/client'
+ *
+ * const convex = new ConvexClient(CONVEX_URL)
+ * const auth = client({ convex })
+ * ```
+ *
+ * ### SSR / proxy mode
+ *
+ * ```ts
+ * const auth = client({
+ *   convex,
+ *   proxy: '/api/auth',
+ *   initialToken: tokenFromServer, // read from httpOnly cookie during SSR
+ * })
+ * ```
+ *
+ * In proxy mode all auth operations go through the proxy URL.
+ * Tokens are stored in httpOnly cookies server-side — the client
+ * only holds the JWT in memory.
+ */
+export function client(options) {
+    const { convex, proxy } = options;
+    // In proxy mode, default storage to null (cookies handle persistence).
+    const storage = options.storage !== undefined
+        ? options.storage
+        : proxy
+            ? null
+            : typeof window === "undefined"
+                ? null
+                : window.localStorage;
+    const replaceURL = options.replaceURL ??
+        ((url) => {
+            if (typeof window !== "undefined") {
+                window.history.replaceState({}, "", url);
+            }
+        });
+    const url = proxy ? undefined : resolveUrl(convex, options.url);
+    const escapedNamespace = proxy
+        ? proxy.replace(/[^a-zA-Z0-9]/g, "")
+        : url.replace(/[^a-zA-Z0-9]/g, "");
     const key = (name) => `${name}_${escapedNamespace}`;
     const subscribers = new Set();
-    let token = null;
-    let isLoading = true;
+    // Unauthenticated HTTP client for code verification & OAuth exchange.
+    // Only needed in SPA mode — proxy mode routes everything through the proxy.
+    const httpClient = proxy ? null : new ConvexHttpClient(url);
+    // ---------------------------------------------------------------------------
+    // State
+    // ---------------------------------------------------------------------------
+    // If a server-provided token was supplied (SSR hydration), start authenticated.
+    const serverToken = options.token ?? null;
+    const hasServerToken = serverToken !== null;
+    let token = serverToken;
+    let isLoading = !hasServerToken;
     let snapshot = {
         isLoading,
-        isAuthenticated: false,
+        isAuthenticated: hasServerToken,
         token,
     };
     let handlingCodeFlow = false;
-    const logVerbose = (message) => {
-        if (transport.verbose) {
-            transport.logger?.logVerbose?.(message);
-            console.debug(`${new Date().toISOString()} ${message}`);
-        }
-    };
     const notify = () => {
         for (const cb of subscribers)
             cb();
     };
     const updateSnapshot = () => {
-        const nextSnapshot = {
+        const next = {
             isLoading,
             isAuthenticated: token !== null,
             token,
         };
-        if (snapshot.isLoading === nextSnapshot.isLoading &&
-            snapshot.isAuthenticated === nextSnapshot.isAuthenticated &&
-            snapshot.token === nextSnapshot.token) {
+        if (snapshot.isLoading === next.isLoading &&
+            snapshot.isAuthenticated === next.isAuthenticated &&
+            snapshot.token === next.token) {
             return false;
         }
-        snapshot = nextSnapshot;
+        snapshot = next;
         return true;
     };
+    // ---------------------------------------------------------------------------
+    // Storage helpers (SPA mode only)
+    // ---------------------------------------------------------------------------
     const storageGet = async (name) => storage ? ((await storage.getItem(key(name))) ?? null) : null;
     const storageSet = async (name, value) => {
         if (storage)
@@ -53,8 +115,10 @@ export function createAuthClient(options) {
         if (storage)
             await storage.removeItem(key(name));
     };
+    // ---------------------------------------------------------------------------
+    // Token management
+    // ---------------------------------------------------------------------------
     const setToken = async (args) => {
-        const wasAuthenticated = token !== null;
         if (args.tokens === null) {
             token = null;
             if (args.shouldStore) {
@@ -69,9 +133,6 @@ export function createAuthClient(options) {
                 await storageSet(REFRESH_TOKEN_STORAGE_KEY, args.tokens.refreshToken);
             }
         }
-        if (wasAuthenticated !== (token !== null)) {
-            await onChange?.();
-        }
         const hadPendingLoad = isLoading;
         isLoading = false;
         const changed = updateSnapshot();
@@ -79,12 +140,31 @@ export function createAuthClient(options) {
             notify();
         }
     };
+    // ---------------------------------------------------------------------------
+    // Proxy fetch helper
+    // ---------------------------------------------------------------------------
+    const proxyFetch = async (body) => {
+        const response = await fetch(proxy, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            credentials: "include",
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({}));
+            throw new Error(error.error ?? `Proxy request failed: ${response.status}`);
+        }
+        return response.json();
+    };
+    // ---------------------------------------------------------------------------
+    // Code verification with retries (SPA mode only)
+    // ---------------------------------------------------------------------------
     const verifyCode = async (args) => {
         let lastError;
         let retry = 0;
         while (retry < RETRY_BACKOFF.length) {
             try {
-                return await transport.unauthenticatedCall("auth:signIn", "code" in args
+                return await httpClient.action("auth:signIn", "code" in args
                     ? { params: { code: args.code }, verifier: args.verifier }
                     : args);
             }
@@ -95,7 +175,6 @@ export function createAuthClient(options) {
                     break;
                 const wait = RETRY_BACKOFF[retry] + RETRY_JITTER * Math.random();
                 retry++;
-                logVerbose(`verifyCode network retry ${retry}/${RETRY_BACKOFF.length} in ${wait}ms`);
                 await new Promise((resolve) => setTimeout(resolve, wait));
             }
         }
@@ -103,9 +182,15 @@ export function createAuthClient(options) {
     };
     const verifyCodeAndSetToken = async (args) => {
         const { tokens } = await verifyCode(args);
-        await setToken({ shouldStore: true, tokens: tokens ?? null });
+        await setToken({
+            shouldStore: true,
+            tokens: tokens ?? null,
+        });
         return tokens !== null;
     };
+    // ---------------------------------------------------------------------------
+    // signIn
+    // ---------------------------------------------------------------------------
     const signIn = async (provider, args) => {
         const params = args instanceof FormData
             ? Array.from(args.entries()).reduce((acc, [k, v]) => {
@@ -113,16 +198,52 @@ export function createAuthClient(options) {
                 return acc;
             }, {})
             : args ?? {};
+        if (proxy) {
+            // Proxy mode: POST to the proxy endpoint.
+            const result = await proxyFetch({
+                action: "auth:signIn",
+                args: { provider, params },
+            });
+            if (result.redirect !== undefined) {
+                const redirectUrl = new URL(result.redirect);
+                // Verifier is stored server-side in an httpOnly cookie.
+                if (typeof window !== "undefined") {
+                    window.location.href = redirectUrl.toString();
+                }
+                return { signingIn: false, redirect: redirectUrl };
+            }
+            if (result.totpRequired) {
+                return { signingIn: false, totpRequired: true, verifier: result.verifier };
+            }
+            if (result.tokens !== undefined) {
+                // Proxy returns { token, refreshToken: "dummy" }.
+                // Store JWT in memory only — real refresh token is in httpOnly cookie.
+                await setToken({
+                    shouldStore: false,
+                    tokens: result.tokens === null ? null : { token: result.tokens.token },
+                });
+                return { signingIn: result.tokens !== null };
+            }
+            return { signingIn: false };
+        }
+        // SPA mode: call Convex directly.
         const verifier = (await storageGet(VERIFIER_STORAGE_KEY)) ?? undefined;
         await storageRemove(VERIFIER_STORAGE_KEY);
-        const result = await transport.authenticatedCall("auth:signIn", { provider, params, verifier });
+        const result = await convex.action("auth:signIn", {
+            provider,
+            params,
+            verifier,
+        });
         if (result.redirect !== undefined) {
-            const url = new URL(result.redirect);
+            const redirectUrl = new URL(result.redirect);
             await storageSet(VERIFIER_STORAGE_KEY, result.verifier);
             if (typeof window !== "undefined") {
-                window.location.href = url.toString();
+                window.location.href = redirectUrl.toString();
             }
-            return { signingIn: false, redirect: url };
+            return { signingIn: false, redirect: redirectUrl };
+        }
+        if (result.totpRequired) {
+            return { signingIn: false, totpRequired: true, verifier: result.verifier };
         }
         if (result.tokens !== undefined) {
             await setToken({
@@ -133,34 +254,82 @@ export function createAuthClient(options) {
         }
         return { signingIn: false };
     };
+    // ---------------------------------------------------------------------------
+    // signOut
+    // ---------------------------------------------------------------------------
     const signOut = async () => {
+        if (proxy) {
+            try {
+                await proxyFetch({ action: "auth:signOut", args: {} });
+            }
+            catch {
+                // Already signed out is fine.
+            }
+            await setToken({ shouldStore: false, tokens: null });
+            return;
+        }
+        // SPA mode.
         try {
-            await transport.authenticatedCall("auth:signOut");
+            await convex.action("auth:signOut", {});
         }
         catch {
             // Already signed out is fine.
         }
         await setToken({ shouldStore: true, tokens: null });
     };
+    // ---------------------------------------------------------------------------
+    // fetchAccessToken — called by convex.setAuth()
+    // ---------------------------------------------------------------------------
     const fetchAccessToken = async ({ forceRefreshToken, }) => {
         if (!forceRefreshToken)
             return token;
+        if (proxy) {
+            // Proxy mode: POST to the proxy to refresh.
+            // The proxy reads the real refresh token from the httpOnly cookie.
+            const tokenBeforeRefresh = token;
+            return await browserMutex("__convexAuthProxyRefresh", async () => {
+                // Another tab/call may have already refreshed.
+                if (token !== tokenBeforeRefresh)
+                    return token;
+                try {
+                    const result = await proxyFetch({
+                        action: "auth:signIn",
+                        args: { refreshToken: true },
+                    });
+                    if (result.tokens) {
+                        await setToken({
+                            shouldStore: false,
+                            tokens: { token: result.tokens.token },
+                        });
+                    }
+                    else {
+                        await setToken({ shouldStore: false, tokens: null });
+                    }
+                }
+                catch {
+                    await setToken({ shouldStore: false, tokens: null });
+                }
+                return token;
+            });
+        }
+        // SPA mode: refresh via localStorage + httpClient.
         const tokenBeforeLockAcquisition = token;
         return await browserMutex(REFRESH_TOKEN_STORAGE_KEY, async () => {
             const tokenAfterLockAcquisition = token;
             if (tokenAfterLockAcquisition !== tokenBeforeLockAcquisition) {
-                logVerbose(`fetchAccessToken using synchronized token, is null: ${tokenAfterLockAcquisition === null}`);
                 return tokenAfterLockAcquisition;
             }
             const refreshToken = (await storageGet(REFRESH_TOKEN_STORAGE_KEY)) ?? null;
             if (!refreshToken) {
-                logVerbose("fetchAccessToken found no refresh token");
                 return null;
             }
             await verifyCodeAndSetToken({ refreshToken });
             return token;
         });
     };
+    // ---------------------------------------------------------------------------
+    // OAuth code flow (SPA mode only — server handles this in proxy mode)
+    // ---------------------------------------------------------------------------
     const handleCodeFlow = async () => {
         if (typeof window === "undefined")
             return;
@@ -169,24 +338,20 @@ export function createAuthClient(options) {
         const code = new URLSearchParams(window.location.search).get("code");
         if (!code)
             return;
-        const shouldRun = shouldHandleCode === undefined
-            ? true
-            : typeof shouldHandleCode === "function"
-                ? shouldHandleCode()
-                : shouldHandleCode;
-        if (!shouldRun)
-            return;
         handlingCodeFlow = true;
-        const url = new URL(window.location.href);
-        url.searchParams.delete("code");
+        const codeUrl = new URL(window.location.href);
+        codeUrl.searchParams.delete("code");
         try {
-            await replaceURL(url.pathname + url.search + url.hash);
+            await replaceURL(codeUrl.pathname + codeUrl.search + codeUrl.hash);
             await signIn(undefined, { code });
         }
         finally {
             handlingCodeFlow = false;
         }
     };
+    // ---------------------------------------------------------------------------
+    // Hydrate from storage (SPA mode only)
+    // ---------------------------------------------------------------------------
     const hydrateFromStorage = async () => {
         const storedToken = (await storageGet(JWT_STORAGE_KEY)) ?? null;
         await setToken({
@@ -194,36 +359,485 @@ export function createAuthClient(options) {
             tokens: storedToken === null ? null : { token: storedToken },
         });
     };
-    const getSnapshot = () => snapshot;
-    const subscribe = (cb) => {
-        subscribers.add(cb);
-        return () => subscribers.delete(cb);
+    // ---------------------------------------------------------------------------
+    // Subscribe
+    // ---------------------------------------------------------------------------
+    /**
+     * Subscribe to auth state changes. Immediately invokes the callback
+     * with the current state and returns an unsubscribe function.
+     *
+     * ```ts
+     * const unsub = auth.onChange(setState)
+     * ```
+     */
+    const onChange = (cb) => {
+        cb(snapshot);
+        const wrapped = () => cb(snapshot);
+        subscribers.add(wrapped);
+        return () => {
+            subscribers.delete(wrapped);
+        };
     };
-    if (typeof window !== "undefined") {
+    // ---------------------------------------------------------------------------
+    // Initialization
+    // ---------------------------------------------------------------------------
+    // Cross-tab sync via storage events (SPA mode only).
+    if (!proxy && typeof window !== "undefined") {
         const onStorage = (event) => {
             void (async () => {
-                if (event.key !== key(JWT_STORAGE_KEY)) {
+                if (event.key !== key(JWT_STORAGE_KEY))
                     return;
-                }
-                const value = event.newValue;
                 await setToken({
                     shouldStore: false,
-                    tokens: value === null ? null : { token: value },
+                    tokens: event.newValue === null ? null : { token: event.newValue },
                 });
             })();
         };
         window.addEventListener("storage", onStorage);
     }
+    // Auto-wire: feed our tokens into the Convex client so
+    // queries and mutations are automatically authenticated.
+    convex.setAuth(fetchAccessToken);
+    // Auto-hydrate and handle code flow.
+    if (typeof window !== "undefined") {
+        if (proxy) {
+            // Proxy mode: if no initialToken was provided, try a refresh
+            // to pick up any existing session from httpOnly cookies.
+            if (!hasServerToken) {
+                void fetchAccessToken({ forceRefreshToken: true });
+            }
+            else {
+                // initialToken already set — mark loading as done.
+                isLoading = false;
+                updateSnapshot();
+            }
+        }
+        else {
+            // SPA mode: hydrate from localStorage, then handle OAuth code flow.
+            void hydrateFromStorage().then(() => handleCodeFlow());
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Passkey helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Base64url encode/decode helpers for the WebAuthn credential API.
+     * These run client-side only (browser context).
+     */
+    const base64urlEncode = (buffer) => {
+        const bytes = new Uint8Array(buffer);
+        let binary = "";
+        for (let i = 0; i < bytes.byteLength; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    };
+    const base64urlDecode = (str) => {
+        const padded = str.replace(/-/g, "+").replace(/_/g, "/");
+        const binary = atob(padded);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes;
+    };
+    const passkey = {
+        /**
+         * Check if WebAuthn passkeys are supported in the current environment.
+         */
+        isSupported: () => {
+            return (typeof window !== "undefined" &&
+                typeof window.PublicKeyCredential !== "undefined");
+        },
+        /**
+         * Check if conditional UI (autofill-assisted passkey sign-in) is supported.
+         *
+         * ```ts
+         * if (await auth.passkey.isAutofillSupported()) {
+         *   auth.passkey.authenticate({ autofill: true });
+         * }
+         * ```
+         */
+        isAutofillSupported: async () => {
+            if (typeof window === "undefined")
+                return false;
+            if (typeof window.PublicKeyCredential === "undefined")
+                return false;
+            if (typeof window.PublicKeyCredential.isConditionalMediationAvailable !== "function") {
+                return false;
+            }
+            return window.PublicKeyCredential.isConditionalMediationAvailable();
+        },
+        /**
+         * Register a new passkey for the current or new user.
+         *
+         * Performs the full two-round-trip WebAuthn registration ceremony:
+         * 1. Requests creation options from the server (challenge, RP info)
+         * 2. Calls `navigator.credentials.create()` with the options
+         * 3. Sends the attestation back to the server for verification
+         * 4. Server creates user + account + passkey records and returns tokens
+         *
+         * Works in both SPA and proxy (SSR) modes.
+         *
+         * ```ts
+         * await auth.passkey.register({ name: "MacBook Touch ID" });
+         * ```
+         *
+         * @param opts.name - Friendly name for this passkey
+         * @param opts.email - Email to associate with the new account
+         * @param opts.userName - Username for the credential (defaults to email)
+         * @param opts.userDisplayName - Display name for the credential
+         * @returns `{ signingIn: true }` on success
+         */
+        register: async (opts) => {
+            const phase1Params = {
+                flow: "register-options",
+                email: opts?.email,
+                userName: opts?.userName,
+                userDisplayName: opts?.userDisplayName,
+            };
+            // Phase 1: Get registration options from server
+            let phase1Result;
+            if (proxy) {
+                phase1Result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: { provider: "passkey", params: phase1Params },
+                });
+            }
+            else {
+                phase1Result = await convex.action("auth:signIn", {
+                    provider: "passkey",
+                    params: phase1Params,
+                });
+            }
+            if (!phase1Result.options) {
+                throw new Error("Server did not return passkey registration options");
+            }
+            const options = phase1Result.options;
+            // Convert base64url strings to ArrayBuffers for the credential API
+            const createOptions = {
+                publicKey: {
+                    rp: options.rp,
+                    user: {
+                        id: base64urlDecode(options.user.id).buffer,
+                        name: options.user.name,
+                        displayName: options.user.displayName,
+                    },
+                    challenge: base64urlDecode(options.challenge).buffer,
+                    pubKeyCredParams: options.pubKeyCredParams,
+                    timeout: options.timeout,
+                    attestation: options.attestation,
+                    authenticatorSelection: options.authenticatorSelection,
+                    excludeCredentials: (options.excludeCredentials ?? []).map((cred) => ({
+                        type: cred.type ?? "public-key",
+                        id: base64urlDecode(cred.id).buffer,
+                        transports: cred.transports,
+                    })),
+                },
+            };
+            // Phase 2: Create credential via browser API
+            const credential = (await navigator.credentials.create(createOptions));
+            if (!credential) {
+                throw new Error("Passkey registration was cancelled");
+            }
+            const response = credential.response;
+            // Extract transports if available
+            const transports = typeof response.getTransports === "function"
+                ? response.getTransports()
+                : undefined;
+            const phase2Params = {
+                flow: "register-verify",
+                clientDataJSON: base64urlEncode(response.clientDataJSON),
+                attestationObject: base64urlEncode(response.attestationObject),
+                transports,
+                passkeyName: opts?.name,
+                email: opts?.email,
+            };
+            // Phase 3: Send attestation to server for verification
+            let phase2Result;
+            if (proxy) {
+                // In proxy mode the verifier is stored in an httpOnly cookie by the proxy.
+                // We pass it back explicitly so the proxy can forward it to Convex.
+                phase2Result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: {
+                        provider: "passkey",
+                        params: phase2Params,
+                        verifier: phase1Result.verifier,
+                    },
+                });
+            }
+            else {
+                phase2Result = await convex.action("auth:signIn", {
+                    provider: "passkey",
+                    params: phase2Params,
+                    verifier: phase1Result.verifier,
+                });
+            }
+            if (phase2Result.tokens) {
+                if (proxy) {
+                    await setToken({
+                        shouldStore: false,
+                        tokens: phase2Result.tokens === null
+                            ? null
+                            : { token: phase2Result.tokens.token },
+                    });
+                }
+                else {
+                    await setToken({
+                        shouldStore: true,
+                        tokens: phase2Result.tokens,
+                    });
+                }
+                return { signingIn: true };
+            }
+            return { signingIn: false };
+        },
+        /**
+         * Authenticate with an existing passkey.
+         *
+         * Performs the full two-round-trip WebAuthn authentication ceremony:
+         * 1. Requests assertion options from the server (challenge, allowed credentials)
+         * 2. Calls `navigator.credentials.get()` with the options
+         * 3. Sends the assertion back to the server for signature verification
+         * 4. Server verifies signature, updates counter, creates session, returns tokens
+         *
+         * Works in both SPA and proxy (SSR) modes.
+         *
+         * ```ts
+         * // Discoverable credential (no email needed)
+         * await auth.passkey.authenticate();
+         *
+         * // Scoped to a specific user's credentials
+         * await auth.passkey.authenticate({ email: "user@example.com" });
+         *
+         * // Autofill-assisted (conditional UI)
+         * await auth.passkey.authenticate({ autofill: true });
+         * ```
+         *
+         * @param opts.email - Scope to credentials for this email's user
+         * @param opts.autofill - Use conditional mediation (autofill UI)
+         * @returns `{ signingIn: true }` on success
+         */
+        authenticate: async (opts) => {
+            const phase1Params = {
+                flow: "auth-options",
+                email: opts?.email,
+            };
+            // Phase 1: Get assertion options from server
+            let phase1Result;
+            if (proxy) {
+                phase1Result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: { provider: "passkey", params: phase1Params },
+                });
+            }
+            else {
+                phase1Result = await convex.action("auth:signIn", {
+                    provider: "passkey",
+                    params: phase1Params,
+                });
+            }
+            if (!phase1Result.options) {
+                throw new Error("Server did not return passkey authentication options");
+            }
+            const options = phase1Result.options;
+            // Convert base64url strings to ArrayBuffers for the credential API
+            const getOptions = {
+                publicKey: {
+                    challenge: base64urlDecode(options.challenge).buffer,
+                    timeout: options.timeout,
+                    rpId: options.rpId,
+                    userVerification: options.userVerification,
+                    allowCredentials: (options.allowCredentials ?? []).map((cred) => ({
+                        type: cred.type ?? "public-key",
+                        id: base64urlDecode(cred.id).buffer,
+                        transports: cred.transports,
+                    })),
+                },
+                ...(opts?.autofill ? { mediation: "conditional" } : {}),
+            };
+            // Phase 2: Get credential via browser API
+            const credential = (await navigator.credentials.get(getOptions));
+            if (!credential) {
+                throw new Error("Passkey authentication was cancelled");
+            }
+            const response = credential.response;
+            const phase2Params = {
+                flow: "auth-verify",
+                credentialId: base64urlEncode(credential.rawId),
+                clientDataJSON: base64urlEncode(response.clientDataJSON),
+                authenticatorData: base64urlEncode(response.authenticatorData),
+                signature: base64urlEncode(response.signature),
+            };
+            // Phase 3: Send assertion to server for verification
+            let phase2Result;
+            if (proxy) {
+                phase2Result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: {
+                        provider: "passkey",
+                        params: phase2Params,
+                        verifier: phase1Result.verifier,
+                    },
+                });
+            }
+            else {
+                phase2Result = await convex.action("auth:signIn", {
+                    provider: "passkey",
+                    params: phase2Params,
+                    verifier: phase1Result.verifier,
+                });
+            }
+            if (phase2Result.tokens) {
+                if (proxy) {
+                    await setToken({
+                        shouldStore: false,
+                        tokens: phase2Result.tokens === null
+                            ? null
+                            : { token: phase2Result.tokens.token },
+                    });
+                }
+                else {
+                    await setToken({
+                        shouldStore: true,
+                        tokens: phase2Result.tokens,
+                    });
+                }
+                return { signingIn: true };
+            }
+            return { signingIn: false };
+        },
+    };
+    const totp = {
+        /**
+         * Start TOTP enrollment. Must be authenticated.
+         *
+         * Returns a URI for QR code display and a base32 secret for manual entry.
+         *
+         * ```ts
+         * const setup = await auth.totp.setup();
+         * // Display QR code from setup.uri
+         * // Or show setup.secret for manual entry
+         * ```
+         */
+        setup: async (opts) => {
+            const params = { flow: "setup" };
+            if (opts?.name)
+                params.name = opts.name;
+            if (opts?.accountName)
+                params.accountName = opts.accountName;
+            if (proxy) {
+                const result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: { provider: "totp", params },
+                });
+                return { uri: result.totpSetup.uri, secret: result.totpSetup.secret, verifier: result.verifier, totpId: result.totpSetup.totpId };
+            }
+            const result = await convex.action("auth:signIn", {
+                provider: "totp",
+                params,
+            });
+            return { uri: result.totpSetup.uri, secret: result.totpSetup.secret, verifier: result.verifier, totpId: result.totpSetup.totpId };
+        },
+        /**
+         * Complete TOTP enrollment by verifying the first code from the authenticator app.
+         *
+         * ```ts
+         * await auth.totp.confirm({ code: "123456", verifier: setup.verifier, totpId: setup.totpId });
+         * ```
+         */
+        confirm: async (opts) => {
+            const params = {
+                flow: "confirm",
+                code: opts.code,
+                totpId: opts.totpId,
+            };
+            if (proxy) {
+                const result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: { provider: "totp", params, verifier: opts.verifier },
+                });
+                if (result.tokens) {
+                    await setToken({
+                        shouldStore: false,
+                        tokens: result.tokens === null ? null : { token: result.tokens.token },
+                    });
+                }
+                return;
+            }
+            const result = await convex.action("auth:signIn", {
+                provider: "totp",
+                params,
+                verifier: opts.verifier,
+            });
+            if (result.tokens) {
+                await setToken({
+                    shouldStore: true,
+                    tokens: result.tokens ?? null,
+                });
+            }
+        },
+        /**
+         * Complete 2FA verification during sign-in.
+         *
+         * Called after a credentials sign-in returns `totpRequired: true`.
+         *
+         * ```ts
+         * const result = await auth.signIn("password", { email, password });
+         * if (result.totpRequired) {
+         *   await auth.totp.verify({ code: "123456", verifier: result.verifier! });
+         * }
+         * ```
+         */
+        verify: async (opts) => {
+            const params = {
+                flow: "verify",
+                code: opts.code,
+            };
+            if (proxy) {
+                const result = await proxyFetch({
+                    action: "auth:signIn",
+                    args: { provider: "totp", params, verifier: opts.verifier },
+                });
+                if (result.tokens) {
+                    await setToken({
+                        shouldStore: false,
+                        tokens: result.tokens === null ? null : { token: result.tokens.token },
+                    });
+                }
+                return;
+            }
+            const result = await convex.action("auth:signIn", {
+                provider: "totp",
+                params,
+                verifier: opts.verifier,
+            });
+            if (result.tokens) {
+                await setToken({
+                    shouldStore: true,
+                    tokens: result.tokens ?? null,
+                });
+            }
+        },
+    };
     return {
+        /** Current auth state snapshot. */
+        get state() {
+            return snapshot;
+        },
         signIn,
         signOut,
-        fetchAccessToken,
-        handleCodeFlow,
-        hydrateFromStorage,
-        getSnapshot,
-        subscribe,
+        onChange,
+        /** Passkey (WebAuthn) authentication helpers. */
+        passkey,
+        /** TOTP two-factor authentication helpers. */
+        totp,
     };
 }
+// ---------------------------------------------------------------------------
+// Browser mutex — ensures only one tab refreshes a token at a time.
+// ---------------------------------------------------------------------------
 async function browserMutex(key, callback) {
     const lockManager = globalThis?.navigator?.locks;
     return lockManager !== undefined