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

package/dist/client/index.d.ts

@@ -1,49 +1,103 @@
-import { FunctionReference, OptionalRestArgs } from "convex/server";
 import { Value } from "convex/values";
-type AuthActionCaller = {
-    authenticatedCall<Action extends FunctionReference<"action", "public">>(action: Action, ...args: OptionalRestArgs<Action>): Promise<Action["_returnType"]>;
-    unauthenticatedCall<Action extends FunctionReference<"action", "public">>(action: Action, ...args: OptionalRestArgs<Action>): Promise<Action["_returnType"]>;
-    verbose?: boolean;
-    logger?: {
-        logVerbose?: (message: string) => void;
-    };
-};
-export interface TokenStorage {
+/**
+ * Structural interface for any Convex client.
+ * Satisfied by both `ConvexClient` (`convex/browser`) and
+ * `ConvexReactClient` (`convex/react`).
+ */
+interface ConvexTransport {
+    action(action: any, args: any): Promise<any>;
+    setAuth(fetchToken: (args: {
+        forceRefreshToken: boolean;
+    }) => Promise<string | null | undefined>, onChange?: (isAuthenticated: boolean) => void): void;
+    clearAuth(): void;
+}
+/** Pluggable key-value storage (defaults to `localStorage`). */
+export interface Storage {
     getItem(key: string): string | null | undefined | Promise<string | null | undefined>;
     setItem(key: string, value: string): void | Promise<void>;
     removeItem(key: string): void | Promise<void>;
 }
-export type AuthSession = {
-    token: string;
-    refreshToken: string;
-};
-export type SignInResult = {
+type SignInResult = {
     signingIn: boolean;
     redirect?: URL;
 };
-export type AuthSnapshot = {
+/** Reactive auth state snapshot returned by `auth.state` and `auth.onChange`. */
+export type AuthState = {
     isLoading: boolean;
     isAuthenticated: boolean;
     token: string | null;
 };
-export type AuthClientOptions = {
-    transport: AuthActionCaller;
-    storage?: TokenStorage | null;
-    storageNamespace: string;
+/** Options for {@link client}. */
+export type ClientOptions = {
+    /** Any Convex client (`ConvexClient` or `ConvexReactClient`). */
+    convex: ConvexTransport;
+    /**
+     * Convex deployment URL. Derived automatically from the client internals
+     * when omitted — pass explicitly only if auto-detection fails.
+     */
+    url?: string;
+    /**
+     * Key-value storage for persisting tokens.
+     *
+     * - Defaults to `localStorage` in SPA mode.
+     * - Defaults to `null` (in-memory only) when `proxy` is set,
+     *   since httpOnly cookies handle persistence.
+     */
+    storage?: Storage | null;
+    /** Override how the URL bar is updated after OAuth code exchange. */
     replaceURL?: (relativeUrl: string) => void | Promise<void>;
-    shouldHandleCode?: (() => boolean) | boolean;
-    onChange?: () => Promise<unknown>;
+    /**
+     * SSR proxy endpoint (e.g. `"/api/auth"`).
+     *
+     * When set, `signIn`/`signOut`/token refresh POST to this URL
+     * (with `credentials: "include"`) instead of calling Convex directly.
+     * The server handles httpOnly cookies for token persistence.
+     *
+     * Pair with {@link ClientOptions.token} for flash-free SSR hydration.
+     */
+    proxy?: string;
+    /**
+     * JWT from server-side hydration.
+     *
+     * In proxy mode the server reads the JWT from an httpOnly cookie
+     * and passes it to the client during SSR. This avoids a loading
+     * flash on first render — the client is immediately authenticated.
+     */
+    token?: string | null;
 };
-export declare function createAuthClient(options: AuthClientOptions): {
+/**
+ * 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 declare function client(options: ClientOptions): {
+    /** Current auth state snapshot. */
+    readonly state: AuthState;
     signIn: (provider?: string, args?: FormData | Record<string, Value>) => Promise<SignInResult>;
     signOut: () => Promise<void>;
-    fetchAccessToken: ({ forceRefreshToken, }: {
-        forceRefreshToken: boolean;
-    }) => Promise<string | null>;
-    handleCodeFlow: () => Promise<void>;
-    hydrateFromStorage: () => Promise<void>;
-    getSnapshot: () => AuthSnapshot;
-    subscribe: (cb: () => void) => () => boolean;
+    onChange: (cb: (state: AuthState) => void) => (() => void);
 };
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAMtC,KAAK,gBAAgB,GAAG;IACtB,iBAAiB,CAAC,MAAM,SAAS,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACpE,MAAM,EAAE,MAAM,EACd,GAAG,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAClC,mBAAmB,CAAC,MAAM,SAAS,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACtE,MAAM,EAAE,MAAM,EACd,GAAG,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE;QACP,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;KACxC,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrF,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,gBAAgB,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7C,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACnC,CAAC;AASF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB;wBAoI5C,MAAM,SACV,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,KACtC,OAAO,CAAC,YAAY,CAAC;;+CAiDrB;QACD,iBAAiB,EAAE,OAAO,CAAC;KAC5B,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;;;uBAoDF,YAAY;oBAEb,MAAM,IAAI;EA8BlC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEtC;;;;GAIG;AACH,UAAU,eAAe;IACvB,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7C,OAAO,CACL,UAAU,EAAE,CAAC,IAAI,EAAE;QACjB,iBAAiB,EAAE,OAAO,CAAC;KAC5B,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EACxC,QAAQ,CAAC,EAAE,CAAC,eAAe,EAAE,OAAO,KAAK,IAAI,GAC5C,IAAI,CAAC;IACR,SAAS,IAAI,IAAI,CAAC;CACnB;AAED,gEAAgE;AAChE,MAAM,WAAW,OAAO;IACtB,OAAO,CACL,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAClE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAOD,KAAK,YAAY,GAAG;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB,CAAC;AAEF,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAEF,kCAAkC;AAClC,MAAM,MAAM,aAAa,GAAG;IAC1B,iEAAiE;IACjE,MAAM,EAAE,eAAe,CAAC;IACxB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,qEAAqE;IACrE,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAyBF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa;IAoazC,mCAAmC;oBACtB,SAAS;wBAlPX,MAAM,SACV,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,KACtC,OAAO,CAAC,YAAY,CAAC;;mBA4LF,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC;EA2DhE"}

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,46 @@ 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.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.tokens !== undefined) {
             await setToken({
@@ -133,34 +248,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 +332,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 +353,77 @@ 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());
+        }
+    }
     return {
+        /** Current auth state snapshot. */
+        get state() {
+            return snapshot;
+        },
         signIn,
         signOut,
-        fetchAccessToken,
-        handleCodeFlow,
-        hydrateFromStorage,
-        getSnapshot,
-        subscribe,
+        onChange,
     };
 }
+// ---------------------------------------------------------------------------
+// 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