@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

package/src/client/index.ts

@@ -1,6 +1,39 @@
+import { Fx } from "@robelest/fx";
 import { ConvexHttpClient } from "convex/browser";
 import { ConvexError, Value } from "convex/values";
 
+import { AUTH_ERRORS } from "../server/errors";
+import { browserMutex, getStorageListenerRegistry } from "./runtime/browser";
+import { createDeviceClient } from "./factors/device";
+import { createInviteManager } from "./runtime/invite";
+import { createPasskeyClient } from "./factors/passkey";
+import {
+  createProxyHelpers,
+  isRetriableProxyRefreshError,
+  isTransientNetworkError,
+} from "./runtime/proxy";
+import { createStorageHelpers } from "./runtime/storage";
+import { createTotpClient } from "./factors/totp";
+import type {
+  AuthApiRefs,
+  AuthClient,
+  AuthFlowContext,
+  AuthHandshakeErrorCode,
+  AuthSession,
+  AuthState,
+  ClientOptions,
+  ConvexTransport,
+  DeviceClient,
+  DeviceCodeResult,
+  HandshakeWaiter,
+  PasskeyClient,
+  PendingInvite,
+  SignInActionResult,
+  SignInResult,
+  Storage,
+  TotpClient,
+} from "./core/types";
+
 // Re-export error utilities so consumers can import from `@robelest/convex-auth/client`.
 export {
   isAuthError,
@@ -8,139 +41,29 @@ export {
   AUTH_ERRORS,
   type AuthErrorCode,
 } from "../server/errors";
-
-/**
- * Structural interface for any Convex client.
- * Satisfied by `ConvexClient` (`convex/browser`),
- * `ConvexReactClient` (`convex/react`), and similar transports.
- *
- * `clearAuth` is present on `ConvexReactClient` and `BaseConvexClient`
- * but not on the simplified `ConvexClient`. When available we call it
- * during sign-out for a clean deauthentication.
- */
-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>;
-}
-
-type AuthSession = {
-  token: string;
-  refreshToken: string;
-};
-
-/**
- * Device code response returned when signing in with the `"device"` provider.
- *
- * The device displays the `userCode` (or `verificationUriComplete`) and
- * polls via `auth.device.poll()` until the user authorizes.
- */
-export type DeviceCodeResult = {
-  /** High-entropy device code used for polling (keep secret). */
-  deviceCode: string;
-  /** Short human-readable code the user enters (e.g. "WDJB-MJHT"). */
-  userCode: string;
-  /** Base verification URL (e.g. "https://myapp.com/device"). */
-  verificationUri: string;
-  /** Verification URL with user code pre-filled as `?code=XXXX-XXXX`. */
-  verificationUriComplete: string;
-  /** Lifetime of the codes in seconds. */
-  expiresIn: number;
-  /** Minimum polling interval in seconds. */
-  interval: number;
-};
-
-/**
- * Result of a `signIn` call.
- *
- * - `signingIn: true` — credentials were accepted and the user is authenticated.
- * - `redirect` — OAuth flow initiated; redirect the user to `redirect.toString()`.
- * - `totpRequired` — credentials valid but 2FA is needed; call `auth.totp.verify()`.
- * - `deviceCode` — device flow initiated; display the code and poll via `auth.device.poll()`.
- * - `verifier` — opaque string for multi-step flows (TOTP, passkey).
- */
-export type SignInResult = {
-  /** `true` when sign-in completed and the user is authenticated. */
-  signingIn: boolean;
-  /** OAuth redirect URL. Present when the provider requires a browser redirect. */
-  redirect?: URL;
-  /** `true` when the account has TOTP enabled and a code is required. */
-  totpRequired?: boolean;
-  /** Device code response for the device authorization flow (RFC 8628). */
-  deviceCode?: DeviceCodeResult;
-  /** Opaque verifier for multi-step flows (pass to `totp.verify` or passkey phase 2). */
-  verifier?: string;
-};
-
-/** Reactive auth state snapshot returned by `auth.state` and `auth.onChange`. */
-export type AuthState = {
-  /** `true` during initial hydration before the first token is resolved. */
-  isLoading: boolean;
-  /** `true` when a valid JWT exists (user is signed in). */
-  isAuthenticated: boolean;
-  /** The raw JWT string, or `null` when not authenticated. */
-  token: string | null;
-};
-
-/** 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>;
-  /**
-   * 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 type {
+  AuthApiRefs,
+  AuthClient,
+  AuthState,
+  ClientOptions,
+  DeviceClient,
+  DeviceCodeResult,
+  PasskeyClient,
+  PendingInvite,
+  SignInResult,
+  Storage,
+  TotpClient,
+} from "./core/types";
 
 const VERIFIER_STORAGE_KEY = "__convexAuthOAuthVerifier";
 const JWT_STORAGE_KEY = "__convexAuthJWT";
 const REFRESH_TOKEN_STORAGE_KEY = "__convexAuthRefreshToken";
+const INVITE_TOKEN_KEY = "__convexAuthPendingInvite";
+const INVITE_EMAIL_KEY = "__convexAuthPendingInviteEmail";
 
-const RETRY_BACKOFF = [500, 2000];
-const RETRY_JITTER = 100;
+const RETRY_BASE_MS = 500;
+const RETRY_MAX_RETRIES = 2;
+const AUTH_HANDSHAKE_TIMEOUT_MS = 5000;
 
 /**
  * Resolve the Convex deployment URL from the client.
@@ -169,9 +92,10 @@ function resolveUrl(convex: ConvexTransport, explicit?: string): string {
  * ```ts
  * import { ConvexClient } from 'convex/browser';
  * import { client } from '@robelest/convex-auth/client';
+ * import { api } from '../convex/_generated/api';
  *
  * const convex = new ConvexClient(CONVEX_URL);
- * const auth = client({ convex });
+ * const auth = client({ convex, api: api.auth });
  * ```
  *
  * ### SSR / proxy mode
@@ -179,8 +103,8 @@ function resolveUrl(convex: ConvexTransport, explicit?: string): string {
  * ```ts
  * const auth = client({
  *   convex,
- *   proxy: '/api/auth',
- *   token: tokenFromServer, // JWT read from httpOnly cookie during SSR
+ *   proxyPath: '/api/auth',
+ *   tokenSeed: tokenFromServer, // JWT read from httpOnly cookie during SSR
  * });
  * ```
  *
@@ -189,10 +113,26 @@ function resolveUrl(convex: ConvexTransport, explicit?: string): string {
  * holds the JWT in memory only.
  *
  * @param options - Client configuration. See {@link ClientOptions}.
- * @returns Auth client with `signIn`, `signOut`, `onChange`, `state`, `passkey`, and `totp`.
+ * @typeParam Api - An AuthApiRefs type determining which factor helpers are available.
+ * @returns Auth client with conditional `passkey`, `totp`, and `device` helpers.
+ * @throws {Error} When the Convex deployment URL cannot be determined and `url` is not passed explicitly.
+ * @throws {Error} When `proxyPath` is not set and the `api` option is missing.
  */
-export function client(options: ClientOptions) {
-  const { convex, proxy } = options;
+export function client<
+  Api extends AuthApiRefs<boolean, boolean, boolean> = AuthApiRefs,
+>(options: ClientOptions<Api>): AuthClient<Api> {
+  const { convex, proxyPath, api: apiRefs } = options;
+  const proxy = proxyPath;
+
+  function requireApiRefs() {
+    if (!apiRefs) {
+      throw new Error(
+        "The `api` option is required when `proxyPath` is not set. " +
+          "Pass { api: api.auth }.",
+      );
+    }
+    return apiRefs;
+  }
 
   // In proxy mode, default storage to null (cookies handle persistence).
   const storage =
@@ -204,20 +144,79 @@ export function client(options: ClientOptions) {
           ? null
           : window.localStorage;
 
-  const replaceURL =
-    options.replaceURL ??
+  const replaceUrl =
+    options.replaceUrl ??
     ((url: string) => {
       if (typeof window !== "undefined") {
         window.history.replaceState({}, "", url);
       }
     });
 
+  // ---------------------------------------------------------------------------
+  // Location — SSR-safe URL reading
+  // ---------------------------------------------------------------------------
+
+  function getLocation(): URL | null {
+    if (typeof options.location === "function") return options.location();
+    if (options.location instanceof URL) return options.location;
+    if (typeof window !== "undefined") return new URL(window.location.href);
+    return null;
+  }
+
+  /**
+   * SSR-safe URL parameter reader.
+   *
+   * Uses the `location` option if provided, otherwise falls back to
+   * `window.location` (returns `null` during SSR where `window` is unavailable).
+   *
+   * @param name - The query parameter name.
+   * @returns The parameter value, or `null` if not present or in SSR.
+   *
+   * @example
+   * ```ts
+   * const workspaceId = auth.param("workspace");
+   * const tab = auth.param("tab") ?? "issues";
+   * ```
+   */
+  function param(name: string): string | null {
+    const loc = getLocation();
+    return loc?.searchParams.get(name) ?? null;
+  }
+
+  function cleanUrlParams(params: string[]) {
+    const loc = getLocation();
+    if (!loc) return;
+    const searchParams = new URLSearchParams(loc.search);
+    let changed = false;
+    for (const p of params) {
+      if (searchParams.has(p)) {
+        searchParams.delete(p);
+        changed = true;
+      }
+    }
+    if (changed) {
+      const next = searchParams.toString()
+        ? `${loc.pathname}?${searchParams}`
+        : loc.pathname;
+      void replaceUrl(next);
+    }
+  }
+
   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: string) => `${name}_${escapedNamespace}`;
+  const {
+    get: storageGet,
+    set: storageSet,
+    remove: storageRemove,
+  } = createStorageHelpers({ storage, key });
+  const { isAbsoluteUrl, proxyFetch, resolveProxyUrl } = createProxyHelpers({
+    proxy,
+  });
   const subscribers = new Set<() => void>();
+  let disposeStorageListener: (() => void) | null = null;
 
   // Unauthenticated HTTP client for code verification & OAuth exchange.
   // Only needed in SPA mode — proxy mode routes everything through the proxy.
@@ -227,30 +226,173 @@ export function client(options: ClientOptions) {
   // State
   // ---------------------------------------------------------------------------
 
-  // If a server-provided token was supplied (SSR hydration), start authenticated.
-  const serverToken = options.token ?? null;
+  // If a server-provided token was supplied (SSR hydration), treat it as
+  // immediately authenticated to avoid a handshake-only loading screen.
+  const serverToken =
+    typeof options.tokenSeed === "string" && options.tokenSeed.trim().length > 0
+      ? options.tokenSeed
+      : null;
   const hasServerToken = serverToken !== null;
 
   let token: string | null = serverToken;
   let isLoading = !hasServerToken;
+  let authConfirmed = hasServerToken;
+  let handshakePending = false;
+  let authEpoch = 0;
+  let destroyed = false;
+  const handshakeWaiters = new Set<HandshakeWaiter>();
   let snapshot: AuthState = {
+    phase: hasServerToken
+      ? "authenticated"
+      : isLoading
+        ? "loading"
+        : "unauthenticated",
     isLoading,
     isAuthenticated: hasServerToken,
     token,
   };
   let handlingCodeFlow = false;
 
+  const createHandshakeError = (
+    code: AuthHandshakeErrorCode,
+    context: Record<string, unknown>,
+  ) => {
+    return new ConvexError({
+      code,
+      message: AUTH_ERRORS[code],
+      ...context,
+    } as Value);
+  };
+
+  const settleHandshakeWaiters = (
+    epoch: number,
+    outcome:
+      | { type: "resolve" }
+      | { type: "reject"; error: ConvexError<Value> },
+  ) => {
+    for (const waiter of Array.from(handshakeWaiters)) {
+      if (waiter.epoch !== epoch) {
+        continue;
+      }
+      clearTimeout(waiter.timeoutId);
+      handshakeWaiters.delete(waiter);
+      if (outcome.type === "resolve") {
+        waiter.resolve();
+      } else {
+        waiter.reject(outcome.error);
+      }
+    }
+  };
+
+  const rejectObsoleteHandshakeWaiters = (activeEpoch: number) => {
+    for (const waiter of Array.from(handshakeWaiters)) {
+      if (waiter.epoch >= activeEpoch) {
+        continue;
+      }
+      clearTimeout(waiter.timeoutId);
+      handshakeWaiters.delete(waiter);
+      waiter.reject(
+        createHandshakeError("AUTH_HANDSHAKE_REJECTED", {
+          ...waiter.context,
+          reason: "token_changed",
+        }),
+      );
+    }
+  };
+
+  const waitForAuthHandshake = async (context: AuthFlowContext) => {
+    if (token === null) {
+      return;
+    }
+    if (authConfirmed && !handshakePending) {
+      return;
+    }
+    if (!handshakePending) {
+      throw createHandshakeError("AUTH_HANDSHAKE_REJECTED", {
+        ...context,
+        reason: "auth_rejected",
+      });
+    }
+
+    const epoch = authEpoch;
+    await new Promise<void>((resolve, reject) => {
+      const waiterRef: { current: HandshakeWaiter | null } = { current: null };
+      const timeoutId = setTimeout(() => {
+        if (waiterRef.current !== null) {
+          handshakeWaiters.delete(waiterRef.current);
+        }
+        reject(
+          createHandshakeError("AUTH_HANDSHAKE_TIMEOUT", {
+            ...context,
+            timeoutMs: AUTH_HANDSHAKE_TIMEOUT_MS,
+          }),
+        );
+      }, AUTH_HANDSHAKE_TIMEOUT_MS);
+
+      const waiter: HandshakeWaiter = {
+        epoch,
+        context,
+        resolve,
+        reject,
+        timeoutId,
+      };
+      waiterRef.current = waiter;
+      handshakeWaiters.add(waiter);
+    });
+  };
+
+  const handleConvexAuthChange = (isAuthenticated: boolean) => {
+    if (destroyed) {
+      return;
+    }
+
+    if (isAuthenticated) {
+      authConfirmed = true;
+      handshakePending = false;
+      settleHandshakeWaiters(authEpoch, { type: "resolve" });
+    } else {
+      authConfirmed = false;
+      // Do not reject immediately while a handshake is pending.
+      // Convex can transiently emit `false` while reauth is still in flight,
+      // and a subsequent `true` confirms the same session.
+    }
+
+    if (updateSnapshot()) {
+      notify();
+    }
+  };
+
   const notify = () => {
     for (const cb of subscribers) cb();
   };
 
   const updateSnapshot = () => {
+    const phaseDispatch = {
+      tag:
+        token !== null && handshakePending
+          ? "handshake"
+          : isLoading
+            ? "loading"
+            : token !== null && authConfirmed
+              ? "authenticated"
+              : "unauthenticated",
+    } as const;
+
+    const phase = {
+      handshake: "handshake",
+      loading: "loading",
+      authenticated: "authenticated",
+      unauthenticated: "unauthenticated",
+    }[phaseDispatch.tag] as AuthState["phase"];
+
     const next: AuthState = {
-      isLoading,
-      isAuthenticated: token !== null,
+      phase,
+      isLoading: phase === "loading" || phase === "handshake",
+      isAuthenticated: phase === "authenticated",
       token,
     };
     if (
+      snapshot.phase === next.phase &&
       snapshot.isLoading === next.isLoading &&
       snapshot.isAuthenticated === next.isAuthenticated &&
       snapshot.token === next.token
@@ -261,28 +403,54 @@ export function client(options: ClientOptions) {
     return true;
   };
 
-  // ---------------------------------------------------------------------------
-  // Storage helpers (SPA mode only)
-  // ---------------------------------------------------------------------------
-
-  const storageGet = async (name: string) =>
-    storage ? ((await storage.getItem(key(name))) ?? null) : null;
-  const storageSet = async (name: string, value: string) => {
-    if (storage) await storage.setItem(key(name), value);
-  };
-  const storageRemove = async (name: string) => {
-    if (storage) await storage.removeItem(key(name));
+  const finalizeLoadingState = () => {
+    if (!isLoading) {
+      return;
+    }
+    isLoading = false;
+    if (updateSnapshot()) {
+      notify();
+    }
   };
 
+  const inviteManager = createInviteManager({
+    param,
+    storageGet,
+    storageSet,
+    storageRemove,
+    cleanUrlParams,
+    tokenKey: INVITE_TOKEN_KEY,
+    emailKey: INVITE_EMAIL_KEY,
+  });
+  const getPendingInvite = () => inviteManager.getPendingInvite();
+  const persistInvite = () => inviteManager.persistInvite();
+  const acceptInvite = () => inviteManager.acceptInvite();
+
   // ---------------------------------------------------------------------------
   // Token management
   // ---------------------------------------------------------------------------
 
+  const bindConvexAuth = () => {
+    convex.setAuth(fetchAccessToken, handleConvexAuthChange);
+  };
+
   const setToken = async (
     args:
-      | { shouldStore: true; tokens: AuthSession | null }
-      | { shouldStore: false; tokens: { token: string } | null },
+      | {
+          shouldStore: true;
+          tokens: AuthSession | null;
+          requireHandshake?: boolean;
+          resyncConvexAuth?: boolean;
+        }
+      | {
+          shouldStore: false;
+          tokens: { token: string } | null;
+          requireHandshake?: boolean;
+          resyncConvexAuth?: boolean;
+        },
   ) => {
+    const previousToken = token;
+
     if (args.tokens === null) {
       token = null;
       if (args.shouldStore) {
@@ -296,49 +464,72 @@ export function client(options: ClientOptions) {
         await storageSet(REFRESH_TOKEN_STORAGE_KEY, args.tokens.refreshToken);
       }
     }
+
+    if (token !== previousToken) {
+      authEpoch += 1;
+      rejectObsoleteHandshakeWaiters(authEpoch);
+    }
+
+    if (token === null) {
+      authConfirmed = false;
+      handshakePending = false;
+      settleHandshakeWaiters(authEpoch, {
+        type: "reject",
+        error: createHandshakeError("AUTH_HANDSHAKE_REJECTED", {
+          reason: "token_cleared",
+        }),
+      });
+    } else {
+      const shouldEnterHandshake =
+        args.requireHandshake === true || !authConfirmed;
+      if (shouldEnterHandshake) {
+        authConfirmed = false;
+        handshakePending = true;
+      } else {
+        handshakePending = false;
+      }
+    }
+
     const hadPendingLoad = isLoading;
     isLoading = false;
     const changed = updateSnapshot();
+    if (args.resyncConvexAuth !== false) {
+      bindConvexAuth();
+    }
     if (hadPendingLoad || changed) {
-      // Re-sync the Convex client so it picks up the new token immediately.
-      // Without this, the initial convex.setAuth(fetchAccessToken) from
-      // initialization never re-polls and queries run unauthenticated after
-      // magic link code exchange.
-      if (!proxy) {
-        convex.setAuth(fetchAccessToken);
-      }
       notify();
     }
   };
 
-  // ---------------------------------------------------------------------------
-  // Proxy fetch helper
-  // ---------------------------------------------------------------------------
-
-  const proxyFetch = async (body: Record<string, unknown>) => {
-    const response = await fetch(proxy!, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      credentials: "include",
-      body: JSON.stringify(body),
+  const setTokenAndMaybeWait = async (
+    args:
+      | {
+          shouldStore: true;
+          tokens: AuthSession | null;
+          waitForHandshake: boolean;
+          context: AuthFlowContext;
+        }
+      | {
+          shouldStore: false;
+          tokens: { token: string } | null;
+          waitForHandshake: boolean;
+          context: AuthFlowContext;
+        },
+  ): Promise<boolean> => {
+    const { waitForHandshake, context, ...tokenArgs } = args;
+    await setToken({
+      ...(tokenArgs as
+        | { shouldStore: true; tokens: AuthSession | null }
+        | { shouldStore: false; tokens: { token: string } | null }),
+      requireHandshake: waitForHandshake,
     });
-    if (!response.ok) {
-      const errorBody = await response.json().catch(() => ({} as Record<string, unknown>));
-      // Reconstruct ConvexError when the proxy forwards structured auth error data.
-      if (
-        typeof errorBody === "object" &&
-        errorBody !== null &&
-        "authError" in errorBody &&
-        typeof (errorBody as Record<string, unknown>).authError === "object"
-      ) {
-        throw new ConvexError((errorBody as Record<string, unknown>).authError as Value);
-      }
-      throw new Error(
-        (errorBody as Record<string, unknown>).error as string ??
-          `Proxy request failed: ${response.status}`,
-      );
+    if (tokenArgs.tokens === null) {
+      return false;
+    }
+    if (waitForHandshake) {
+      await waitForAuthHandshake(context);
     }
-    return response.json();
+    return true;
   };
 
   // ---------------------------------------------------------------------------
@@ -348,40 +539,58 @@ export function client(options: ClientOptions) {
   const verifyCode = async (
     args: { code: string; verifier?: string } | { refreshToken: string },
   ) => {
-    let lastError: unknown;
-    let retry = 0;
-    while (retry < RETRY_BACKOFF.length) {
-      try {
-        return await httpClient!.action(
-          "auth:signIn" as any,
-          "code" in args
-            ? { params: { code: args.code }, verifier: args.verifier }
-            : args,
-        );
-      } catch (e) {
-        lastError = e;
-        const isNetworkError =
-          e instanceof Error && /network/i.test(e.message || "");
-        if (!isNetworkError) break;
-        const wait = RETRY_BACKOFF[retry]! + RETRY_JITTER * Math.random();
-        retry++;
-        await new Promise((resolve) => setTimeout(resolve, wait));
-      }
-    }
-    throw lastError;
+    const verifyCodeRetryPolicy = Fx.retry.while(
+      Fx.retry.compose(
+        Fx.retry.jittered(Fx.retry.exponential(RETRY_BASE_MS)),
+        Fx.retry.recurs(RETRY_MAX_RETRIES),
+      ),
+      (meta) => isTransientNetworkError(meta.input),
+    );
+
+    return Fx.run(
+      Fx.from({
+        ok: () =>
+          httpClient!.action(
+            requireApiRefs().signIn,
+            "code" in args
+              ? { params: { code: args.code }, verifier: args.verifier }
+              : args,
+          ),
+        err: (e) => e,
+      }).pipe(
+        Fx.retry(verifyCodeRetryPolicy),
+        Fx.recover((e) => Fx.fatal(e)),
+      ),
+    );
   };
 
   const verifyCodeAndSetToken = async (
     args: { code: string; verifier?: string } | { refreshToken: string },
+    opts?: { resyncConvexAuth?: boolean },
   ) => {
     const { tokens } = await verifyCode(args);
     await setToken({
       shouldStore: true,
       tokens: (tokens as AuthSession | null) ?? null,
+      resyncConvexAuth: opts?.resyncConvexAuth,
     });
     return tokens !== null;
   };
 
+  const normalizeDeviceCodeResult = (device_code: any): DeviceCodeResult => {
+    return {
+      deviceCode: device_code.deviceCode,
+      userCode: device_code.userCode,
+      verificationUri:
+        device_code.verification_uri ?? device_code.verificationUri,
+      verificationUriComplete:
+        device_code.verification_uri_complete ??
+        device_code.verificationUriComplete,
+      expiresIn: device_code.expiresIn,
+      interval: device_code.interval,
+    };
+  };
+
   // ---------------------------------------------------------------------------
   // signIn
   // ---------------------------------------------------------------------------
@@ -394,6 +603,7 @@ export function client(options: ClientOptions) {
    * @param args - Provider-specific arguments. Pass a `Record<string, Value>`
    *   or `FormData`. Common fields: `email`, `password`, `code`, `redirectTo`.
    * @returns A {@link SignInResult} indicating the outcome.
+   * @throws {ConvexError} When the server action rejects the sign-in attempt (e.g. invalid credentials, provider error, or rate limiting).
    *
    * @example Email magic link
    * ```ts
@@ -403,8 +613,8 @@ export function client(options: ClientOptions) {
    * @example Password
    * ```ts
    * const result = await auth.signIn('password', { email, password, flow: 'signIn' });
-   * if (result.totpRequired) {
-   *   await auth.totp.verify({ code: totpCode, verifier: result.verifier! });
+   * if (result.kind === 'totpRequired') {
+   *   await auth.totp.verify({ code: totpCode, verifier: result.verifier });
    * }
    * ```
    *
@@ -417,80 +627,121 @@ export function client(options: ClientOptions) {
     provider?: string,
     args?: FormData | Record<string, Value>,
   ): Promise<SignInResult> => {
+    // Persist invite before potential OAuth redirect
+    await persistInvite();
+
     const params =
       args instanceof FormData
-        ? Array.from(args.entries()).reduce(
-            (acc, [k, v]) => {
-              acc[k] = v as string;
-              return acc;
-            },
-            {} as Record<string, string>,
-          )
-        : args ?? {};
+        ? (() => {
+            const formParams: Record<string, Value> = {};
+            args.forEach((value, key) => {
+              formParams[key] = typeof value === "string" ? value : value.name;
+            });
+            return formParams;
+          })()
+        : (args ?? {});
+    const flow =
+      typeof params.flow === "string" && params.flow.length > 0
+        ? params.flow
+        : "signIn";
+
+    const handleSignInActionResult = async (
+      result: SignInActionResult,
+      options: { shouldStore: boolean; persistVerifier: boolean },
+    ): Promise<SignInResult> =>
+      Fx.run(
+        Fx.match(result, result.kind, {
+          redirect: (redirectResult) =>
+            Fx.from({
+              ok: async () => {
+                const redirectUrl = new URL(redirectResult.redirect);
+                if (options.persistVerifier) {
+                  await storageSet(
+                    VERIFIER_STORAGE_KEY,
+                    redirectResult.verifier,
+                  );
+                }
+                if (typeof window !== "undefined") {
+                  window.location.href = redirectUrl.toString();
+                }
+                return {
+                  kind: "redirect" as const,
+                  redirect: redirectUrl,
+                  verifier: redirectResult.verifier,
+                };
+              },
+              err: (e) => e as never,
+            }),
+          totpRequired: (totpRequiredResult) =>
+            Fx.succeed({
+              kind: "totpRequired" as const,
+              verifier: totpRequiredResult.verifier,
+            }),
+          deviceCode: (deviceCodeResult) =>
+            Fx.succeed({
+              kind: "deviceCode" as const,
+              deviceCode: normalizeDeviceCodeResult(
+                deviceCodeResult.deviceCode,
+              ),
+            }),
+          signedIn: (signedInResult) =>
+            Fx.from({
+              ok: async () => {
+                const signingIn = await setTokenAndMaybeWait(
+                  options.shouldStore
+                    ? {
+                        shouldStore: true as const,
+                        tokens: signedInResult.tokens,
+                        waitForHandshake: true,
+                        context: { provider, flow },
+                      }
+                    : {
+                        shouldStore: false as const,
+                        tokens:
+                          signedInResult.tokens === null
+                            ? null
+                            : { token: signedInResult.tokens.token },
+                        waitForHandshake: true,
+                        context: { provider, flow },
+                      },
+                );
+                return signingIn
+                  ? ({ kind: "signedIn" as const } as SignInResult)
+                  : ({ kind: "started" as const } as SignInResult);
+              },
+              err: (e) => e as never,
+            }),
+          started: (_startedResult) => Fx.succeed({ kind: "started" as const }),
+          passkeyOptions: (_passkeyOptionsResult) =>
+            Fx.succeed({ kind: "started" as const }),
+          totpSetup: (_totpSetupResult) =>
+            Fx.succeed({ kind: "started" as const }),
+        }),
+      );
 
     if (proxy) {
-      // Proxy mode: POST to the proxy endpoint.
-      const result = await proxyFetch({
+      const result = (await proxyFetch({
         action: "auth:signIn",
         args: { provider, params },
+      })) as SignInActionResult;
+      return handleSignInActionResult(result, {
+        shouldStore: false,
+        persistVerifier: false,
       });
-      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.deviceCode !== undefined) {
-        return { signingIn: false, deviceCode: result.deviceCode as DeviceCodeResult };
-      }
-      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 convex.action("auth:signIn" as any, {
+    const result = (await convex.action(requireApiRefs().signIn, {
       provider,
       params,
       verifier,
+    })) as SignInActionResult;
+    return handleSignInActionResult(result, {
+      shouldStore: true,
+      persistVerifier: true,
     });
-    if (result.redirect !== undefined) {
-      const redirectUrl = new URL(result.redirect);
-      await storageSet(VERIFIER_STORAGE_KEY, result.verifier!);
-      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.deviceCode !== undefined) {
-      return { signingIn: false, deviceCode: result.deviceCode as DeviceCodeResult };
-    }
-    if (result.tokens !== undefined) {
-      await setToken({
-        shouldStore: true,
-        tokens: (result.tokens as AuthSession | null) ?? null,
-      });
-      return { signingIn: result.tokens !== null };
-    }
-    return { signingIn: false };
   };
 
   // ---------------------------------------------------------------------------
@@ -506,22 +757,24 @@ export function client(options: ClientOptions) {
    */
   const signOut = async () => {
     if (proxy) {
-      try {
-        await proxyFetch({ action: "auth:signOut", args: {} });
-      } catch {
-        // Already signed out is fine.
-      }
+      await Fx.run(
+        Fx.from({
+          ok: () => proxyFetch({ action: "auth:signOut", args: {} }),
+          err: () => undefined,
+        }).pipe(Fx.recover(() => Fx.succeed(undefined))),
+      );
       await setToken({ shouldStore: false, tokens: null });
       if (convex.clearAuth) convex.clearAuth();
       return;
     }
 
     // SPA mode.
-    try {
-      await convex.action("auth:signOut" as any, {});
-    } catch {
-      // Already signed out is fine.
-    }
+    await Fx.run(
+      Fx.from({
+        ok: () => convex.action(requireApiRefs().signOut, {}),
+        err: () => undefined,
+      }).pipe(Fx.recover(() => Fx.succeed(undefined))),
+    );
     await setToken({ shouldStore: true, tokens: null });
     if (convex.clearAuth) convex.clearAuth();
   };
@@ -540,26 +793,71 @@ export function client(options: ClientOptions) {
     if (proxy) {
       // Proxy mode: POST to the proxy to refresh.
       // The proxy reads the real refresh token from the httpOnly cookie.
+      const resolvedProxyUrl = await resolveProxyUrl();
+      if (
+        typeof window === "undefined" &&
+        !(await isAbsoluteUrl(resolvedProxyUrl))
+      ) {
+        finalizeLoadingState();
+        return token;
+      }
+
       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 });
-        }
+
+        const proxyRefreshRetryPolicy = Fx.retry.while(
+          Fx.retry.compose(
+            Fx.retry.jittered(Fx.retry.exponential(RETRY_BASE_MS)),
+            Fx.retry.recurs(RETRY_MAX_RETRIES),
+          ),
+          (meta) => isRetriableProxyRefreshError(meta.input),
+        );
+
+        await Fx.run(
+          Fx.from({
+            ok: () =>
+              proxyFetch({
+                action: "auth:signIn",
+                args: { refreshToken: true },
+              }),
+            err: (e) => e,
+          }).pipe(
+            Fx.retry(proxyRefreshRetryPolicy),
+            Fx.chain((result: any) =>
+              Fx.from({
+                ok: async () => {
+                  if (result.tokens) {
+                    await setToken({
+                      shouldStore: false,
+                      tokens: { token: result.tokens.token },
+                      resyncConvexAuth: false,
+                    });
+                  } else {
+                    await setToken({
+                      shouldStore: false,
+                      tokens: null,
+                      resyncConvexAuth: false,
+                    });
+                  }
+                },
+                err: (e) => e,
+              }),
+            ),
+            Fx.inspect((error) =>
+              Fx.sync(() =>
+                console.error("[convex-auth] Proxy refresh failed:", error),
+              ),
+            ),
+            Fx.recover(() => {
+              if (token === null) {
+                finalizeLoadingState();
+              }
+              return Fx.succeed(undefined);
+            }),
+          ),
+        );
         return token;
       });
     }
@@ -574,9 +872,13 @@ export function client(options: ClientOptions) {
       const refreshToken =
         (await storageGet(REFRESH_TOKEN_STORAGE_KEY)) ?? null;
       if (!refreshToken) {
+        finalizeLoadingState();
         return null;
       }
-      await verifyCodeAndSetToken({ refreshToken });
+      await verifyCodeAndSetToken(
+        { refreshToken },
+        { resyncConvexAuth: false },
+      );
       return token;
     });
   };
@@ -591,14 +893,32 @@ export function client(options: ClientOptions) {
     const code = new URLSearchParams(window.location.search).get("code");
     if (!code) return;
     handlingCodeFlow = true;
-    const codeUrl = new URL(window.location.href);
-    codeUrl.searchParams.delete("code");
-    try {
-      await replaceURL(codeUrl.pathname + codeUrl.search + codeUrl.hash);
-      await signIn(undefined, { code });
-    } finally {
-      handlingCodeFlow = false;
-    }
+    await Fx.run(
+      Fx.from({
+        ok: async () => {
+          await signIn(undefined, { code });
+          const codeUrl = new URL(window.location.href);
+          codeUrl.searchParams.delete("code");
+          await replaceUrl(codeUrl.pathname + codeUrl.search + codeUrl.hash);
+        },
+        err: (e) => e,
+      }).pipe(
+        Fx.recover(() => Fx.succeed(undefined)),
+        Fx.tap(() =>
+          Fx.sync(() => {
+            handlingCodeFlow = false;
+          }),
+        ),
+        Fx.inspect(() =>
+          Fx.sync(() => {
+            handlingCodeFlow = false;
+          }),
+        ),
+      ),
+    );
+    // The flag is always reset — Fx.recover above ensures success path,
+    // but reset defensively here too.
+    handlingCodeFlow = false;
   };
 
   // ---------------------------------------------------------------------------
@@ -643,636 +963,124 @@ export function client(options: ClientOptions) {
 
   // Cross-tab sync via storage events (SPA mode only).
   if (!proxy && typeof window !== "undefined") {
+    const registryKey = key(JWT_STORAGE_KEY);
+    const registry = getStorageListenerRegistry();
+    const existingListener = registry[registryKey];
+    if (existingListener !== undefined) {
+      window.removeEventListener("storage", existingListener);
+    }
+
     const onStorage = (event: StorageEvent) => {
-      void (async () => {
+      Fx.detach(async () => {
         if (event.key !== key(JWT_STORAGE_KEY)) return;
         await setToken({
           shouldStore: false,
-          tokens:
-            event.newValue === null ? null : { token: event.newValue },
+          tokens: event.newValue === null ? null : { token: event.newValue },
         });
-      })();
+      }, "[convex-auth] Storage event handler failed:");
     };
     window.addEventListener("storage", onStorage);
+    registry[registryKey] = onStorage;
+    disposeStorageListener = () => {
+      if (registry[registryKey] === onStorage) {
+        delete registry[registryKey];
+      }
+      window.removeEventListener("storage", onStorage);
+    };
   }
 
   // Auto-wire: feed our tokens into the Convex client so
   // queries and mutations are automatically authenticated.
-  convex.setAuth(fetchAccessToken);
+  bindConvexAuth();
 
   // 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.
+      // Proxy mode: eagerly resolve auth once on startup so routes that only
+      // read auth state (and do not issue Convex queries yet) don't stay in
+      // the initial loading phase.
       if (!hasServerToken) {
-        void fetchAccessToken({ forceRefreshToken: true });
-      } else {
-        // initialToken already set — mark loading as done.
-        isLoading = false;
-        updateSnapshot();
+        Fx.detach(
+          () => fetchAccessToken({ forceRefreshToken: true }),
+          "[convex-auth] Proxy token refresh failed:",
+        );
       }
     } else {
       // SPA mode: hydrate from localStorage, then handle OAuth code flow.
-      void hydrateFromStorage().then(() =>
-        handleCodeFlow().catch((error: unknown) => {
-          console.error("[convex-auth] Code exchange failed:", error);
-        }),
-      );
+      Fx.detach(async () => {
+        await Fx.run(
+          Fx.from({
+            ok: async () => {
+              await hydrateFromStorage();
+              await handleCodeFlow();
+            },
+            err: (e) => e,
+          }).pipe(
+            Fx.inspect((error) =>
+              Fx.sync(() =>
+                console.error(
+                  "[convex-auth] Client initialization failed:",
+                  error,
+                ),
+              ),
+            ),
+            Fx.recover((_error) =>
+              Fx.from({
+                ok: () => setToken({ shouldStore: false, tokens: null }),
+                err: (e) => e,
+              }).pipe(Fx.recover(() => Fx.succeed(undefined))),
+            ),
+          ),
+        );
+      }, "[convex-auth] SPA initialization failed:");
     }
   }
 
   // ---------------------------------------------------------------------------
-  // Passkey helpers
+  // Auth factor helpers
   // ---------------------------------------------------------------------------
 
-  /**
-   * Base64url encode/decode helpers for the WebAuthn credential API.
-   * These run client-side only (browser context).
-   */
-  const base64urlEncode = (buffer: ArrayBuffer): string => {
-    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: string): Uint8Array => {
-    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: (): boolean => {
-      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 (): Promise<boolean> => {
-      if (typeof window === "undefined") return false;
-      if (typeof window.PublicKeyCredential === "undefined") return false;
-      if (
-        typeof (
-          window.PublicKeyCredential as any
-        ).isConditionalMediationAvailable !== "function"
-      ) {
-        return false;
-      }
-      return (
-        window.PublicKeyCredential as any
-      ).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?: {
-        name?: string;
-        email?: string;
-        userName?: string;
-        userDisplayName?: string;
-      },
-    ): Promise<SignInResult> => {
-      const phase1Params = {
-        flow: "register-options",
-        email: opts?.email,
-        userName: opts?.userName,
-        userDisplayName: opts?.userDisplayName,
-      };
-
-      // Phase 1: Get registration options from server
-      let phase1Result: any;
-      if (proxy) {
-        phase1Result = await proxyFetch({
-          action: "auth:signIn",
-          args: { provider: "passkey", params: phase1Params },
-        });
-      } else {
-        phase1Result = await convex.action("auth:signIn" as any, {
-          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: CredentialCreationOptions = {
-        publicKey: {
-          rp: options.rp,
-          user: {
-            id: base64urlDecode(options.user.id).buffer as ArrayBuffer,
-            name: options.user.name,
-            displayName: options.user.displayName,
-          },
-          challenge: base64urlDecode(options.challenge).buffer as ArrayBuffer,
-          pubKeyCredParams: options.pubKeyCredParams,
-          timeout: options.timeout,
-          attestation: options.attestation,
-          authenticatorSelection: options.authenticatorSelection,
-          excludeCredentials: (options.excludeCredentials ?? []).map(
-            (cred: any) => ({
-              type: cred.type ?? "public-key",
-              id: base64urlDecode(cred.id).buffer as ArrayBuffer,
-              transports: cred.transports,
-            }),
-          ),
-        },
-      };
-
-      // Phase 2: Create credential via browser API
-      const credential = (await navigator.credentials.create(
-        createOptions,
-      )) as PublicKeyCredential | null;
-      if (!credential) {
-        throw new Error("Passkey registration was cancelled");
-      }
-
-      const response =
-        credential.response as AuthenticatorAttestationResponse;
-
-      // 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: any;
-      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" as any, {
-          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 as AuthSession,
-          });
-        }
-        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?: { email?: string; autofill?: boolean },
-    ): Promise<SignInResult> => {
-      const phase1Params = {
-        flow: "auth-options",
-        email: opts?.email,
-      };
-
-      // Phase 1: Get assertion options from server
-      let phase1Result: any;
-      if (proxy) {
-        phase1Result = await proxyFetch({
-          action: "auth:signIn",
-          args: { provider: "passkey", params: phase1Params },
-        });
-      } else {
-        phase1Result = await convex.action("auth:signIn" as any, {
-          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: CredentialRequestOptions = {
-        publicKey: {
-          challenge: base64urlDecode(options.challenge).buffer as ArrayBuffer,
-          timeout: options.timeout,
-          rpId: options.rpId,
-          userVerification: options.userVerification,
-          allowCredentials: (options.allowCredentials ?? []).map(
-            (cred: any) => ({
-              type: cred.type ?? "public-key",
-              id: base64urlDecode(cred.id).buffer as ArrayBuffer,
-              transports: cred.transports,
-            }),
-          ),
-        },
-        ...(opts?.autofill ? { mediation: "conditional" as any } : {}),
-      };
-
-      // Phase 2: Get credential via browser API
-      const credential = (await navigator.credentials.get(
-        getOptions,
-      )) as PublicKeyCredential | null;
-      if (!credential) {
-        throw new Error("Passkey authentication was cancelled");
-      }
-
-      const response =
-        credential.response as AuthenticatorAssertionResponse;
-
-      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: any;
-      if (proxy) {
-        phase2Result = await proxyFetch({
-          action: "auth:signIn",
-          args: {
-            provider: "passkey",
-            params: phase2Params,
-            verifier: phase1Result.verifier,
-          },
-        });
-      } else {
-        phase2Result = await convex.action("auth:signIn" as any, {
-          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 as AuthSession,
-          });
-        }
-        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?: { name?: string; accountName?: string },
-    ): Promise<{ uri: string; secret: string; verifier: string; totpId: string }> => {
-      const params: Record<string, any> = { 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" as any, {
-        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: {
-      code: string;
-      verifier: string;
-      totpId: string;
-    }): Promise<void> => {
-      const params: Record<string, any> = {
-        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" as any, {
-        provider: "totp",
-        params,
-        verifier: opts.verifier,
-      });
-      if (result.tokens) {
-        await setToken({
-          shouldStore: true,
-          tokens: (result.tokens as AuthSession | null) ?? 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: { code: string; verifier: string }): Promise<void> => {
-      const params: Record<string, any> = {
-        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" as any, {
-        provider: "totp",
-        params,
-        verifier: opts.verifier,
-      });
-      if (result.tokens) {
-        await setToken({
-          shouldStore: true,
-          tokens: (result.tokens as AuthSession | null) ?? null,
-        });
-      }
-    },
-  };
-
-  const device = {
-    /**
-     * Poll for device authorization status.
-     *
-     * The device calls this repeatedly (respecting `interval`) after
-     * initiating a device flow via `signIn("device")`. Returns when
-     * the user authorizes, or throws on timeout/denial.
-     *
-     * ```ts
-     * const result = await auth.signIn("device");
-     * const { deviceCode } = result;
-     * // Display deviceCode.userCode to the user, then poll:
-     * await auth.device.poll(deviceCode);
-     * // User is now signed in
-     * ```
-     *
-     * @param code - The {@link DeviceCodeResult} from `signIn("device")`.
-     * @returns Resolves when the device is authorized and tokens are stored.
-     * @throws When the code expires, is denied, or polling encounters an error.
-     */
-    poll: async (code: DeviceCodeResult): Promise<void> => {
-      const intervalMs = code.interval * 1000;
-      const expiresAt = Date.now() + code.expiresIn * 1000;
-
-      while (Date.now() < expiresAt) {
-        await new Promise((resolve) => setTimeout(resolve, intervalMs));
-
-        try {
-          let result: any;
-          const params: Record<string, any> = {
-            flow: "poll",
-            deviceCode: code.deviceCode,
-          };
-
-          if (proxy) {
-            result = await proxyFetch({
-              action: "auth:signIn",
-              args: { provider: "device", params },
-            });
-          } else {
-            result = await convex.action("auth:signIn" as any, {
-              provider: "device",
-              params,
-            });
-          }
-
-          // Authorized — tokens received
-          if (result.tokens) {
-            if (proxy) {
-              await setToken({
-                shouldStore: false,
-                tokens:
-                  result.tokens === null
-                    ? null
-                    : { token: result.tokens.token },
-              });
-            } else {
-              await setToken({
-                shouldStore: true,
-                tokens: (result.tokens as AuthSession | null) ?? null,
-              });
-            }
-            return;
-          }
-        } catch (e: unknown) {
-          // Handle expected polling errors
-          if (e instanceof ConvexError) {
-            const data = e.data as Record<string, unknown>;
-            const code_ = data?.code as string | undefined;
-            if (code_ === "DEVICE_AUTHORIZATION_PENDING") {
-              continue; // Keep polling
-            }
-            if (code_ === "DEVICE_SLOW_DOWN") {
-              // Back off by adding one interval
-              await new Promise((resolve) =>
-                setTimeout(resolve, intervalMs),
-              );
-              continue;
-            }
-          }
-          // Non-recoverable error — rethrow
-          throw e;
-        }
-      }
-
-      throw new Error("Device authorization timed out.");
-    },
+  const passkey = createPasskeyClient({
+    proxy,
+    convex,
+    requireApiRefs,
+    proxyFetch,
+    setTokenAndMaybeWait,
+  });
 
-    /**
-     * Authorize a device from the verification page.
-     *
-     * Called by an authenticated user on the verification page after
-     * they enter the user code displayed on the device.
-     *
-     * ```ts
-     * // On the /device verification page:
-     * await auth.device.verify(userCode);
-     * ```
-     *
-     * @param userCode - The user code entered by the user (e.g. "WDJB-MJHT").
-     */
-    verify: async (userCode: string): Promise<void> => {
-      const params: Record<string, any> = {
-        flow: "verify",
-        userCode,
-      };
+  const totp = createTotpClient({
+    proxy,
+    convex,
+    requireApiRefs,
+    proxyFetch,
+    setTokenAndMaybeWait,
+  });
 
-      if (proxy) {
-        await proxyFetch({
-          action: "auth:signIn",
-          args: { provider: "device", params },
-        });
-      } else {
-        await convex.action("auth:signIn" as any, {
-          provider: "device",
-          params,
-        });
-      }
-    },
-  };
+  const device = createDeviceClient({
+    proxy,
+    convex,
+    requireApiRefs,
+    proxyFetch,
+    setTokenAndMaybeWait,
+  });
 
   return {
     /** Current auth state snapshot. */
     get state(): AuthState {
       return snapshot;
     },
+    /** SSR-safe URL param reader. */
+    param,
+    /** Pending invite from URL or recovered from storage. Null if none. */
+    get invite(): PendingInvite | null {
+      const pendingInvite = getPendingInvite();
+      if (!pendingInvite) return null;
+      return {
+        token: pendingInvite.token,
+        email: pendingInvite.email,
+        accept: acceptInvite,
+      };
+    },
     /** Sign in with a provider. See {@link SignInResult} for return shape. */
     signIn,
     /** Sign out and clear all token state. */
@@ -1285,94 +1093,42 @@ export function client(options: ClientOptions) {
     totp,
     /** Device authorization (RFC 8628) helpers. */
     device,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Browser mutex — ensures only one tab refreshes a token at a time.
-// ---------------------------------------------------------------------------
-
-async function browserMutex<T>(
-  key: string,
-  callback: () => Promise<T>,
-): Promise<T> {
-  const lockManager = (globalThis as any)?.navigator?.locks;
-  return lockManager !== undefined
-    ? await lockManager.request(key, callback)
-    : await manualMutex(key, callback);
-}
-
-function getMutexValue(key: string): {
-  currentlyRunning: Promise<void> | null;
-  waiting: Array<() => Promise<void>>;
-} {
-  if ((globalThis as any).__convexAuthMutexes === undefined) {
-    (globalThis as any).__convexAuthMutexes = {} as Record<
-      string,
-      {
-        currentlyRunning: Promise<void> | null;
-        waiting: Array<() => Promise<void>>;
-      }
-    >;
-  }
-  let mutex = (globalThis as any).__convexAuthMutexes[key];
-  if (mutex === undefined) {
-    (globalThis as any).__convexAuthMutexes[key] = {
-      currentlyRunning: null,
-      waiting: [],
-    };
-  }
-  mutex = (globalThis as any).__convexAuthMutexes[key];
-  return mutex;
-}
-
-function setMutexValue(
-  key: string,
-  value: {
-    currentlyRunning: Promise<void> | null;
-    waiting: Array<() => Promise<void>>;
-  },
-) {
-  (globalThis as any).__convexAuthMutexes[key] = value;
-}
-
-async function enqueueCallbackForMutex(
-  key: string,
-  callback: () => Promise<void>,
-) {
-  const mutex = getMutexValue(key);
-  if (mutex.currentlyRunning === null) {
-    setMutexValue(key, {
-      currentlyRunning: callback().finally(() => {
-        const nextCb = getMutexValue(key).waiting.shift();
-        getMutexValue(key).currentlyRunning = null;
-        setMutexValue(key, {
-          ...getMutexValue(key),
-          currentlyRunning:
-            nextCb === undefined ? null : enqueueCallbackForMutex(key, nextCb),
-        });
-      }),
-      waiting: [],
-    });
-  } else {
-    setMutexValue(key, {
-      ...mutex,
-      waiting: [...mutex.waiting, callback],
-    });
-  }
-}
-
-async function manualMutex<T>(
-  key: string,
-  callback: () => Promise<T>,
-): Promise<T> {
-  const outerPromise = new Promise<T>((resolve, reject) => {
-    const wrappedCallback: () => Promise<void> = () => {
-      return callback()
-        .then((v) => resolve(v))
-        .catch((e) => reject(e));
-    };
-    void enqueueCallbackForMutex(key, wrappedCallback);
-  });
-  return outerPromise;
+    /**
+     * Tear down this auth client instance.
+     *
+     * Removes the cross-tab `storage` event listener, clears all
+     * `onChange` subscribers, and rejects any in-flight handshake
+     * waiters. Call this when the client is no longer needed
+     * (e.g. on SPA unmount or hot-module replacement) to prevent
+     * memory leaks and stale callbacks.
+     *
+     * @example
+     * ```ts
+     * // SvelteKit onDestroy
+     * import { onDestroy } from "svelte";
+     * const auth = client({ convex, api: api.auth });
+     * onDestroy(() => auth.destroy());
+     * ```
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = auth.onChange((state) => console.log(state.phase));
+     *
+     * // Later, during cleanup:
+     * unsubscribe();
+     * auth.destroy();
+     * ```
+     */
+    destroy: () => {
+      destroyed = true;
+      settleHandshakeWaiters(authEpoch, {
+        type: "reject",
+        error: createHandshakeError("AUTH_HANDSHAKE_REJECTED", {
+          reason: "destroyed",
+        }),
+      });
+      disposeStorageListener?.();
+      subscribers.clear();
+    },
+  } as AuthClient<Api>;
 }