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

package/dist/client/index.js

@@ -1,4 +1,12 @@
 import { AUTH_ERRORS, isAuthError, parseAuthError } from "../server/errors.js";
+import { browserMutex, getStorageListenerRegistry } from "../runtime/browser.js";
+import { createDeviceClient } from "../factors/device.js";
+import { createInviteManager } from "../runtime/invite.js";
+import { createPasskeyClient } from "../factors/passkey.js";
+import { createProxyHelpers, isRetriableProxyRefreshError, isTransientNetworkError } from "../runtime/proxy.js";
+import { createStorageHelpers } from "../runtime/storage.js";
+import { createTotpClient } from "../factors/totp.js";
+import { Fx } from "@robelest/fx";
 import { ConvexHttpClient } from "convex/browser";
 import { ConvexError } from "convex/values";
 
@@ -6,8 +14,11 @@ import { ConvexError } from "convex/values";
 const VERIFIER_STORAGE_KEY = "__convexAuthOAuthVerifier";
 const JWT_STORAGE_KEY = "__convexAuthJWT";
 const REFRESH_TOKEN_STORAGE_KEY = "__convexAuthRefreshToken";
-const RETRY_BACKOFF = [500, 2e3];
-const RETRY_JITTER = 100;
+const INVITE_TOKEN_KEY = "__convexAuthPendingInvite";
+const INVITE_EMAIL_KEY = "__convexAuthPendingInviteEmail";
+const RETRY_BASE_MS = 500;
+const RETRY_MAX_RETRIES = 2;
+const AUTH_HANDSHAKE_TIMEOUT_MS = 5e3;
 /**
 * Resolve the Convex deployment URL from the client.
 *
@@ -32,9 +43,10 @@ function resolveUrl(convex, explicit) {
 * ```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
@@ -42,8 +54,8 @@ function resolveUrl(convex, explicit) {
 * ```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
 * });
 * ```
 *
@@ -52,50 +64,189 @@ function resolveUrl(convex, explicit) {
 * 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.
 */
 function client(options) {
-	const { convex, proxy } = options;
+	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;
+	}
 	const storage = options.storage !== void 0 ? options.storage : proxy ? null : typeof window === "undefined" ? null : window.localStorage;
-	const replaceURL = options.replaceURL ?? ((url$1) => {
+	const replaceUrl = options.replaceUrl ?? ((url$1) => {
 		if (typeof window !== "undefined") window.history.replaceState({}, "", url$1);
 	});
+	function getLocation() {
+		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) {
+		return getLocation()?.searchParams.get(name) ?? null;
+	}
+	function cleanUrlParams(params) {
+		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) replaceUrl(searchParams.toString() ? `${loc.pathname}?${searchParams}` : loc.pathname);
+	}
 	const url = proxy ? void 0 : 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 { get: storageGet, set: storageSet, remove: storageRemove } = createStorageHelpers({
+		storage,
+		key
+	});
+	const { isAbsoluteUrl, proxyFetch, resolveProxyUrl } = createProxyHelpers({ proxy });
 	const subscribers = /* @__PURE__ */ new Set();
+	let disposeStorageListener = null;
 	const httpClient = proxy ? null : new ConvexHttpClient(url);
-	const serverToken = options.token ?? null;
+	const serverToken = typeof options.tokenSeed === "string" && options.tokenSeed.trim().length > 0 ? options.tokenSeed : null;
 	const hasServerToken = serverToken !== null;
 	let token = serverToken;
 	let isLoading = !hasServerToken;
+	let authConfirmed = hasServerToken;
+	let handshakePending = false;
+	let authEpoch = 0;
+	let destroyed = false;
+	const handshakeWaiters = /* @__PURE__ */ new Set();
 	let snapshot = {
+		phase: hasServerToken ? "authenticated" : isLoading ? "loading" : "unauthenticated",
 		isLoading,
 		isAuthenticated: hasServerToken,
 		token
 	};
 	let handlingCodeFlow = false;
+	const createHandshakeError = (code, context) => {
+		return new ConvexError({
+			code,
+			message: AUTH_ERRORS[code],
+			...context
+		});
+	};
+	const settleHandshakeWaiters = (epoch, outcome) => {
+		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) => {
+		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) => {
+		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((resolve, reject) => {
+			const waiterRef = { current: null };
+			const waiter = {
+				epoch,
+				context,
+				resolve,
+				reject,
+				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)
+			};
+			waiterRef.current = waiter;
+			handshakeWaiters.add(waiter);
+		});
+	};
+	const handleConvexAuthChange = (isAuthenticated) => {
+		if (destroyed) return;
+		if (isAuthenticated) {
+			authConfirmed = true;
+			handshakePending = false;
+			settleHandshakeWaiters(authEpoch, { type: "resolve" });
+		} else authConfirmed = false;
+		if (updateSnapshot()) notify();
+	};
 	const notify = () => {
 		for (const cb of subscribers) cb();
 	};
 	const updateSnapshot = () => {
+		const phase = {
+			handshake: "handshake",
+			loading: "loading",
+			authenticated: "authenticated",
+			unauthenticated: "unauthenticated"
+		}[{ tag: token !== null && handshakePending ? "handshake" : isLoading ? "loading" : token !== null && authConfirmed ? "authenticated" : "unauthenticated" }.tag];
 		const next = {
-			isLoading,
-			isAuthenticated: token !== null,
+			phase,
+			isLoading: phase === "loading" || phase === "handshake",
+			isAuthenticated: phase === "authenticated",
 			token
 		};
-		if (snapshot.isLoading === next.isLoading && snapshot.isAuthenticated === next.isAuthenticated && snapshot.token === next.token) return false;
+		if (snapshot.phase === next.phase && snapshot.isLoading === next.isLoading && snapshot.isAuthenticated === next.isAuthenticated && snapshot.token === next.token) return false;
 		snapshot = next;
 		return true;
 	};
-	const storageGet = async (name) => storage ? await storage.getItem(key(name)) ?? null : null;
-	const storageSet = async (name, value) => {
-		if (storage) await storage.setItem(key(name), value);
+	const finalizeLoadingState = () => {
+		if (!isLoading) return;
+		isLoading = false;
+		if (updateSnapshot()) notify();
 	};
-	const storageRemove = async (name) => {
-		if (storage) await storage.removeItem(key(name));
+	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();
+	const bindConvexAuth = () => {
+		convex.setAuth(fetchAccessToken, handleConvexAuthChange);
 	};
 	const setToken = async (args) => {
+		const previousToken = token;
 		if (args.tokens === null) {
 			token = null;
 			if (args.shouldStore) {
@@ -109,53 +260,66 @@ function client(options) {
 				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 if (args.requireHandshake === true || !authConfirmed) {
+			authConfirmed = false;
+			handshakePending = true;
+		} else handshakePending = false;
 		const hadPendingLoad = isLoading;
 		isLoading = false;
 		const changed = updateSnapshot();
-		if (hadPendingLoad || changed) {
-			if (!proxy) convex.setAuth(fetchAccessToken);
-			notify();
-		}
+		if (args.resyncConvexAuth !== false) bindConvexAuth();
+		if (hadPendingLoad || changed) notify();
 	};
-	const proxyFetch = async (body) => {
-		const response = await fetch(proxy, {
-			method: "POST",
-			headers: { "Content-Type": "application/json" },
-			credentials: "include",
-			body: JSON.stringify(body)
+	const setTokenAndMaybeWait = async (args) => {
+		const { waitForHandshake, context, ...tokenArgs } = args;
+		await setToken({
+			...tokenArgs,
+			requireHandshake: waitForHandshake
 		});
-		if (!response.ok) {
-			const errorBody = await response.json().catch(() => ({}));
-			if (typeof errorBody === "object" && errorBody !== null && "authError" in errorBody && typeof errorBody.authError === "object") throw new ConvexError(errorBody.authError);
-			throw new Error(errorBody.error ?? `Proxy request failed: ${response.status}`);
-		}
-		return response.json();
+		if (tokenArgs.tokens === null) return false;
+		if (waitForHandshake) await waitForAuthHandshake(context);
+		return true;
 	};
 	const verifyCode = async (args) => {
-		let lastError;
-		let retry = 0;
-		while (retry < RETRY_BACKOFF.length) try {
-			return await httpClient.action("auth:signIn", "code" in args ? {
+		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);
-		} catch (e) {
-			lastError = e;
-			if (!(e instanceof Error && /network/i.test(e.message || ""))) break;
-			const wait = RETRY_BACKOFF[retry] + RETRY_JITTER * Math.random();
-			retry++;
-			await new Promise((resolve) => setTimeout(resolve, wait));
-		}
-		throw lastError;
+			} : args),
+			err: (e) => e
+		}).pipe(Fx.retry(verifyCodeRetryPolicy), Fx.recover((e) => Fx.fatal(e))));
 	};
-	const verifyCodeAndSetToken = async (args) => {
+	const verifyCodeAndSetToken = async (args, opts) => {
 		const { tokens } = await verifyCode(args);
 		await setToken({
 			shouldStore: true,
-			tokens: tokens ?? null
+			tokens: tokens ?? null,
+			resyncConvexAuth: opts?.resyncConvexAuth
 		});
 		return tokens !== null;
 	};
+	const normalizeDeviceCodeResult = (device_code) => {
+		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
+		};
+	};
 	/**
 	* Sign in with a provider.
 	*
@@ -164,6 +328,7 @@ function client(options) {
 	* @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
@@ -173,8 +338,8 @@ function client(options) {
 	* @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 });
 	* }
 	* ```
 	*
@@ -184,77 +349,83 @@ function client(options) {
 	* ```
 	*/
 	const signIn = async (provider, args) => {
-		const params = args instanceof FormData ? Array.from(args.entries()).reduce((acc, [k, v]) => {
-			acc[k] = v;
-			return acc;
-		}, {}) : args ?? {};
-		if (proxy) {
-			const result$1 = await proxyFetch({
-				action: "auth:signIn",
-				args: {
-					provider,
-					params
-				}
+		await persistInvite();
+		const params = args instanceof FormData ? (() => {
+			const formParams = {};
+			args.forEach((value, key$1) => {
+				formParams[key$1] = typeof value === "string" ? value : value.name;
 			});
-			if (result$1.redirect !== void 0) {
-				const redirectUrl = new URL(result$1.redirect);
-				if (typeof window !== "undefined") window.location.href = redirectUrl.toString();
-				return {
-					signingIn: false,
-					redirect: redirectUrl
-				};
-			}
-			if (result$1.totpRequired) return {
-				signingIn: false,
-				totpRequired: true,
-				verifier: result$1.verifier
-			};
-			if (result$1.deviceCode !== void 0) return {
-				signingIn: false,
-				deviceCode: result$1.deviceCode
-			};
-			if (result$1.tokens !== void 0) {
-				await setToken({
-					shouldStore: false,
-					tokens: result$1.tokens === null ? null : { token: result$1.tokens.token }
-				});
-				return { signingIn: result$1.tokens !== null };
+			return formParams;
+		})() : args ?? {};
+		const flow = typeof params.flow === "string" && params.flow.length > 0 ? params.flow : "signIn";
+		const handleSignInActionResult = async (result, options$1) => Fx.run(Fx.match(result, result.kind, {
+			redirect: (redirectResult) => Fx.from({
+				ok: async () => {
+					const redirectUrl = new URL(redirectResult.redirect);
+					if (options$1.persistVerifier) await storageSet(VERIFIER_STORAGE_KEY, redirectResult.verifier);
+					if (typeof window !== "undefined") window.location.href = redirectUrl.toString();
+					return {
+						kind: "redirect",
+						redirect: redirectUrl,
+						verifier: redirectResult.verifier
+					};
+				},
+				err: (e) => e
+			}),
+			totpRequired: (totpRequiredResult) => Fx.succeed({
+				kind: "totpRequired",
+				verifier: totpRequiredResult.verifier
+			}),
+			deviceCode: (deviceCodeResult) => Fx.succeed({
+				kind: "deviceCode",
+				deviceCode: normalizeDeviceCodeResult(deviceCodeResult.deviceCode)
+			}),
+			signedIn: (signedInResult) => Fx.from({
+				ok: async () => {
+					return await setTokenAndMaybeWait(options$1.shouldStore ? {
+						shouldStore: true,
+						tokens: signedInResult.tokens,
+						waitForHandshake: true,
+						context: {
+							provider,
+							flow
+						}
+					} : {
+						shouldStore: false,
+						tokens: signedInResult.tokens === null ? null : { token: signedInResult.tokens.token },
+						waitForHandshake: true,
+						context: {
+							provider,
+							flow
+						}
+					}) ? { kind: "signedIn" } : { kind: "started" };
+				},
+				err: (e) => e
+			}),
+			started: (_startedResult) => Fx.succeed({ kind: "started" }),
+			passkeyOptions: (_passkeyOptionsResult) => Fx.succeed({ kind: "started" }),
+			totpSetup: (_totpSetupResult) => Fx.succeed({ kind: "started" })
+		}));
+		if (proxy) return handleSignInActionResult(await proxyFetch({
+			action: "auth:signIn",
+			args: {
+				provider,
+				params
 			}
-			return { signingIn: false };
-		}
+		}), {
+			shouldStore: false,
+			persistVerifier: false
+		});
 		const verifier = await storageGet(VERIFIER_STORAGE_KEY) ?? void 0;
 		await storageRemove(VERIFIER_STORAGE_KEY);
-		const result = await convex.action("auth:signIn", {
+		return handleSignInActionResult(await convex.action(requireApiRefs().signIn, {
 			provider,
 			params,
 			verifier
+		}), {
+			shouldStore: true,
+			persistVerifier: true
 		});
-		if (result.redirect !== void 0) {
-			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 !== void 0) return {
-			signingIn: false,
-			deviceCode: result.deviceCode
-		};
-		if (result.tokens !== void 0) {
-			await setToken({
-				shouldStore: true,
-				tokens: result.tokens ?? null
-			});
-			return { signingIn: result.tokens !== null };
-		}
-		return { signingIn: false };
 	};
 	/**
 	* Sign out the current user.
@@ -265,12 +436,13 @@ function client(options) {
 	*/
 	const signOut = async () => {
 		if (proxy) {
-			try {
-				await proxyFetch({
+			await Fx.run(Fx.from({
+				ok: () => proxyFetch({
 					action: "auth:signOut",
 					args: {}
-				});
-			} catch {}
+				}),
+				err: () => void 0
+			}).pipe(Fx.recover(() => Fx.succeed(void 0))));
 			await setToken({
 				shouldStore: false,
 				tokens: null
@@ -278,9 +450,10 @@ function client(options) {
 			if (convex.clearAuth) convex.clearAuth();
 			return;
 		}
-		try {
-			await convex.action("auth:signOut", {});
-		} catch {}
+		await Fx.run(Fx.from({
+			ok: () => convex.action(requireApiRefs().signOut, {}),
+			err: () => void 0
+		}).pipe(Fx.recover(() => Fx.succeed(void 0))));
 		await setToken({
 			shouldStore: true,
 			tokens: null
@@ -290,28 +463,39 @@ function client(options) {
 	const fetchAccessToken = async ({ forceRefreshToken }) => {
 		if (!forceRefreshToken) return token;
 		if (proxy) {
+			const resolvedProxyUrl = await resolveProxyUrl();
+			if (typeof window === "undefined" && !await isAbsoluteUrl(resolvedProxyUrl)) {
+				finalizeLoadingState();
+				return token;
+			}
 			const tokenBeforeRefresh = token;
 			return await browserMutex("__convexAuthProxyRefresh", async () => {
 				if (token !== tokenBeforeRefresh) return token;
-				try {
-					const result = await proxyFetch({
+				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 }
-					});
-					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
-					});
-				}
+					}),
+					err: (e) => e
+				}).pipe(Fx.retry(proxyRefreshRetryPolicy), Fx.chain((result) => 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(void 0);
+				})));
 				return token;
 			});
 		}
@@ -320,8 +504,11 @@ function client(options) {
 			const tokenAfterLockAcquisition = token;
 			if (tokenAfterLockAcquisition !== tokenBeforeLockAcquisition) return tokenAfterLockAcquisition;
 			const refreshToken = await storageGet(REFRESH_TOKEN_STORAGE_KEY) ?? null;
-			if (!refreshToken) return null;
-			await verifyCodeAndSetToken({ refreshToken });
+			if (!refreshToken) {
+				finalizeLoadingState();
+				return null;
+			}
+			await verifyCodeAndSetToken({ refreshToken }, { resyncConvexAuth: false });
 			return token;
 		});
 	};
@@ -331,14 +518,20 @@ function client(options) {
 		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(void 0, { code });
-		} finally {
+		await Fx.run(Fx.from({
+			ok: async () => {
+				await signIn(void 0, { 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(void 0)), Fx.tap(() => Fx.sync(() => {
 			handlingCodeFlow = false;
-		}
+		})), Fx.inspect(() => Fx.sync(() => {
+			handlingCodeFlow = false;
+		}))));
+		handlingCodeFlow = false;
 	};
 	const hydrateFromStorage = async () => {
 		const storedToken = await storageGet(JWT_STORAGE_KEY) ?? null;
@@ -367,413 +560,93 @@ function client(options) {
 		};
 	};
 	if (!proxy && typeof window !== "undefined") {
+		const registryKey = key(JWT_STORAGE_KEY);
+		const registry = getStorageListenerRegistry();
+		const existingListener = registry[registryKey];
+		if (existingListener !== void 0) window.removeEventListener("storage", existingListener);
 		const onStorage = (event) => {
-			(async () => {
+			Fx.detach(async () => {
 				if (event.key !== key(JWT_STORAGE_KEY)) return;
 				await setToken({
 					shouldStore: false,
 					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);
+		};
 	}
-	convex.setAuth(fetchAccessToken);
-	if (typeof window !== "undefined") if (proxy) if (!hasServerToken) fetchAccessToken({ forceRefreshToken: true });
-	else {
-		isLoading = false;
-		updateSnapshot();
-	}
-	else hydrateFromStorage().then(() => handleCodeFlow().catch((error) => {
-		console.error("[convex-auth] Code exchange failed:", error);
-	}));
-	/**
-	* Base64url encode/decode helpers for the WebAuthn credential API.
-	* These run client-side only (browser context).
-	*/
-	const base64urlEncode = (buffer) => {
-		const bytes = new Uint8Array(buffer);
-		let binary = "";
-		for (let i = 0; i < bytes.byteLength; i++) binary += String.fromCharCode(bytes[i]);
-		return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-	};
-	const base64urlDecode = (str) => {
-		const padded = str.replace(/-/g, "+").replace(/_/g, "/");
-		const binary = atob(padded);
-		const bytes = new Uint8Array(binary.length);
-		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-		return bytes;
-	};
+	bindConvexAuth();
+	if (typeof window !== "undefined") if (proxy) {
+		if (!hasServerToken) Fx.detach(() => fetchAccessToken({ forceRefreshToken: true }), "[convex-auth] Proxy token refresh failed:");
+	} else 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(void 0))))));
+	}, "[convex-auth] SPA initialization failed:");
 	return {
 		get state() {
 			return snapshot;
 		},
+		param,
+		get invite() {
+			const pendingInvite = getPendingInvite();
+			if (!pendingInvite) return null;
+			return {
+				token: pendingInvite.token,
+				email: pendingInvite.email,
+				accept: acceptInvite
+			};
+		},
 		signIn,
 		signOut,
 		onChange,
-		passkey: {
-			isSupported: () => {
-				return typeof window !== "undefined" && typeof window.PublicKeyCredential !== "undefined";
-			},
-			isAutofillSupported: async () => {
-				if (typeof window === "undefined") return false;
-				if (typeof window.PublicKeyCredential === "undefined") return false;
-				if (typeof window.PublicKeyCredential.isConditionalMediationAvailable !== "function") return false;
-				return window.PublicKeyCredential.isConditionalMediationAvailable();
-			},
-			register: async (opts) => {
-				const phase1Params = {
-					flow: "register-options",
-					email: opts?.email,
-					userName: opts?.userName,
-					userDisplayName: opts?.userDisplayName
-				};
-				let phase1Result;
-				if (proxy) phase1Result = await proxyFetch({
-					action: "auth:signIn",
-					args: {
-						provider: "passkey",
-						params: phase1Params
-					}
-				});
-				else phase1Result = await convex.action("auth:signIn", {
-					provider: "passkey",
-					params: phase1Params
-				});
-				if (!phase1Result.options) throw new Error("Server did not return passkey registration options");
-				const options$1 = phase1Result.options;
-				const createOptions = { publicKey: {
-					rp: options$1.rp,
-					user: {
-						id: base64urlDecode(options$1.user.id).buffer,
-						name: options$1.user.name,
-						displayName: options$1.user.displayName
-					},
-					challenge: base64urlDecode(options$1.challenge).buffer,
-					pubKeyCredParams: options$1.pubKeyCredParams,
-					timeout: options$1.timeout,
-					attestation: options$1.attestation,
-					authenticatorSelection: options$1.authenticatorSelection,
-					excludeCredentials: (options$1.excludeCredentials ?? []).map((cred) => ({
-						type: cred.type ?? "public-key",
-						id: base64urlDecode(cred.id).buffer,
-						transports: cred.transports
-					}))
-				} };
-				const credential = await navigator.credentials.create(createOptions);
-				if (!credential) throw new Error("Passkey registration was cancelled");
-				const response = credential.response;
-				const transports = typeof response.getTransports === "function" ? response.getTransports() : void 0;
-				const phase2Params = {
-					flow: "register-verify",
-					clientDataJSON: base64urlEncode(response.clientDataJSON),
-					attestationObject: base64urlEncode(response.attestationObject),
-					transports,
-					passkeyName: opts?.name,
-					email: opts?.email
-				};
-				let phase2Result;
-				if (proxy) phase2Result = await proxyFetch({
-					action: "auth:signIn",
-					args: {
-						provider: "passkey",
-						params: phase2Params,
-						verifier: phase1Result.verifier
-					}
-				});
-				else phase2Result = await convex.action("auth:signIn", {
-					provider: "passkey",
-					params: phase2Params,
-					verifier: phase1Result.verifier
-				});
-				if (phase2Result.tokens) {
-					if (proxy) await setToken({
-						shouldStore: false,
-						tokens: phase2Result.tokens === null ? null : { token: phase2Result.tokens.token }
-					});
-					else await setToken({
-						shouldStore: true,
-						tokens: phase2Result.tokens
-					});
-					return { signingIn: true };
-				}
-				return { signingIn: false };
-			},
-			authenticate: async (opts) => {
-				const phase1Params = {
-					flow: "auth-options",
-					email: opts?.email
-				};
-				let phase1Result;
-				if (proxy) phase1Result = await proxyFetch({
-					action: "auth:signIn",
-					args: {
-						provider: "passkey",
-						params: phase1Params
-					}
-				});
-				else phase1Result = await convex.action("auth:signIn", {
-					provider: "passkey",
-					params: phase1Params
-				});
-				if (!phase1Result.options) throw new Error("Server did not return passkey authentication options");
-				const options$1 = phase1Result.options;
-				const getOptions = {
-					publicKey: {
-						challenge: base64urlDecode(options$1.challenge).buffer,
-						timeout: options$1.timeout,
-						rpId: options$1.rpId,
-						userVerification: options$1.userVerification,
-						allowCredentials: (options$1.allowCredentials ?? []).map((cred) => ({
-							type: cred.type ?? "public-key",
-							id: base64urlDecode(cred.id).buffer,
-							transports: cred.transports
-						}))
-					},
-					...opts?.autofill ? { mediation: "conditional" } : {}
-				};
-				const credential = await navigator.credentials.get(getOptions);
-				if (!credential) throw new Error("Passkey authentication was cancelled");
-				const response = credential.response;
-				const phase2Params = {
-					flow: "auth-verify",
-					credentialId: base64urlEncode(credential.rawId),
-					clientDataJSON: base64urlEncode(response.clientDataJSON),
-					authenticatorData: base64urlEncode(response.authenticatorData),
-					signature: base64urlEncode(response.signature)
-				};
-				let phase2Result;
-				if (proxy) phase2Result = await proxyFetch({
-					action: "auth:signIn",
-					args: {
-						provider: "passkey",
-						params: phase2Params,
-						verifier: phase1Result.verifier
-					}
-				});
-				else phase2Result = await convex.action("auth:signIn", {
-					provider: "passkey",
-					params: phase2Params,
-					verifier: phase1Result.verifier
-				});
-				if (phase2Result.tokens) {
-					if (proxy) await setToken({
-						shouldStore: false,
-						tokens: phase2Result.tokens === null ? null : { token: phase2Result.tokens.token }
-					});
-					else await setToken({
-						shouldStore: true,
-						tokens: phase2Result.tokens
-					});
-					return { signingIn: true };
-				}
-				return { signingIn: false };
-			}
-		},
-		totp: {
-			setup: async (opts) => {
-				const params = { flow: "setup" };
-				if (opts?.name) params.name = opts.name;
-				if (opts?.accountName) params.accountName = opts.accountName;
-				if (proxy) {
-					const result$1 = await proxyFetch({
-						action: "auth:signIn",
-						args: {
-							provider: "totp",
-							params
-						}
-					});
-					return {
-						uri: result$1.totpSetup.uri,
-						secret: result$1.totpSetup.secret,
-						verifier: result$1.verifier,
-						totpId: result$1.totpSetup.totpId
-					};
-				}
-				const result = await convex.action("auth:signIn", {
-					provider: "totp",
-					params
-				});
-				return {
-					uri: result.totpSetup.uri,
-					secret: result.totpSetup.secret,
-					verifier: result.verifier,
-					totpId: result.totpSetup.totpId
-				};
-			},
-			confirm: async (opts) => {
-				const params = {
-					flow: "confirm",
-					code: opts.code,
-					totpId: opts.totpId
-				};
-				if (proxy) {
-					const result$1 = await proxyFetch({
-						action: "auth:signIn",
-						args: {
-							provider: "totp",
-							params,
-							verifier: opts.verifier
-						}
-					});
-					if (result$1.tokens) await setToken({
-						shouldStore: false,
-						tokens: result$1.tokens === null ? null : { token: result$1.tokens.token }
-					});
-					return;
-				}
-				const result = await convex.action("auth:signIn", {
-					provider: "totp",
-					params,
-					verifier: opts.verifier
-				});
-				if (result.tokens) await setToken({
-					shouldStore: true,
-					tokens: result.tokens ?? null
-				});
-			},
-			verify: async (opts) => {
-				const params = {
-					flow: "verify",
-					code: opts.code
-				};
-				if (proxy) {
-					const result$1 = await proxyFetch({
-						action: "auth:signIn",
-						args: {
-							provider: "totp",
-							params,
-							verifier: opts.verifier
-						}
-					});
-					if (result$1.tokens) await setToken({
-						shouldStore: false,
-						tokens: result$1.tokens === null ? null : { token: result$1.tokens.token }
-					});
-					return;
-				}
-				const result = await convex.action("auth:signIn", {
-					provider: "totp",
-					params,
-					verifier: opts.verifier
-				});
-				if (result.tokens) await setToken({
-					shouldStore: true,
-					tokens: result.tokens ?? null
-				});
-			}
-		},
-		device: {
-			poll: async (code) => {
-				const intervalMs = code.interval * 1e3;
-				const expiresAt = Date.now() + code.expiresIn * 1e3;
-				while (Date.now() < expiresAt) {
-					await new Promise((resolve) => setTimeout(resolve, intervalMs));
-					try {
-						let result;
-						const params = {
-							flow: "poll",
-							deviceCode: code.deviceCode
-						};
-						if (proxy) result = await proxyFetch({
-							action: "auth:signIn",
-							args: {
-								provider: "device",
-								params
-							}
-						});
-						else result = await convex.action("auth:signIn", {
-							provider: "device",
-							params
-						});
-						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 ?? null
-							});
-							return;
-						}
-					} catch (e) {
-						if (e instanceof ConvexError) {
-							const code_ = e.data?.code;
-							if (code_ === "DEVICE_AUTHORIZATION_PENDING") continue;
-							if (code_ === "DEVICE_SLOW_DOWN") {
-								await new Promise((resolve) => setTimeout(resolve, intervalMs));
-								continue;
-							}
-						}
-						throw e;
-					}
-				}
-				throw new Error("Device authorization timed out.");
-			},
-			verify: async (userCode) => {
-				const params = {
-					flow: "verify",
-					userCode
-				};
-				if (proxy) await proxyFetch({
-					action: "auth:signIn",
-					args: {
-						provider: "device",
-						params
-					}
-				});
-				else await convex.action("auth:signIn", {
-					provider: "device",
-					params
-				});
-			}
+		passkey: createPasskeyClient({
+			proxy,
+			convex,
+			requireApiRefs,
+			proxyFetch,
+			setTokenAndMaybeWait
+		}),
+		totp: createTotpClient({
+			proxy,
+			convex,
+			requireApiRefs,
+			proxyFetch,
+			setTokenAndMaybeWait
+		}),
+		device: createDeviceClient({
+			proxy,
+			convex,
+			requireApiRefs,
+			proxyFetch,
+			setTokenAndMaybeWait
+		}),
+		destroy: () => {
+			destroyed = true;
+			settleHandshakeWaiters(authEpoch, {
+				type: "reject",
+				error: createHandshakeError("AUTH_HANDSHAKE_REJECTED", { reason: "destroyed" })
+			});
+			disposeStorageListener?.();
+			subscribers.clear();
 		}
 	};
 }
-async function browserMutex(key, callback) {
-	const lockManager = globalThis?.navigator?.locks;
-	return lockManager !== void 0 ? await lockManager.request(key, callback) : await manualMutex(key, callback);
-}
-function getMutexValue(key) {
-	if (globalThis.__convexAuthMutexes === void 0) globalThis.__convexAuthMutexes = {};
-	let mutex = globalThis.__convexAuthMutexes[key];
-	if (mutex === void 0) globalThis.__convexAuthMutexes[key] = {
-		currentlyRunning: null,
-		waiting: []
-	};
-	mutex = globalThis.__convexAuthMutexes[key];
-	return mutex;
-}
-function setMutexValue(key, value) {
-	globalThis.__convexAuthMutexes[key] = value;
-}
-async function enqueueCallbackForMutex(key, callback) {
-	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 === void 0 ? null : enqueueCallbackForMutex(key, nextCb)
-			});
-		}),
-		waiting: []
-	});
-	else setMutexValue(key, {
-		...mutex,
-		waiting: [...mutex.waiting, callback]
-	});
-}
-async function manualMutex(key, callback) {
-	return new Promise((resolve, reject) => {
-		const wrappedCallback = () => {
-			return callback().then((v) => resolve(v)).catch((e) => reject(e));
-		};
-		enqueueCallbackForMutex(key, wrappedCallback);
-	});
-}
 
 //#endregion
 export { AUTH_ERRORS, client, isAuthError, parseAuthError };