@estifanos-sh/convex-auth 0.0.1-preview.0

package/dist/client/index.js

@@ -0,0 +1,976 @@
+import { LOG_LEVELS, logMessage } from "../shared/log.js";
+import { retryWithBackoff } from "../shared/retry.js";
+import { createDeferred } from "./core/types.js";
+import { createHandshakeError } from "./errors.js";
+import { createDeviceClient } from "./factors/device.js";
+import { createTotpClient } from "./factors/totp.js";
+import { createInviteManager } from "./runtime/invite.js";
+import { localMutex } from "./runtime/mutex.js";
+import { ProxyRequestError, isAuthRefreshRejection, isRetriableProxyRefreshError, isTransientNetworkError, parseProxyErrorBody } from "./runtime/proxy.js";
+import { createStorageHelpers } from "./runtime/storage.js";
+import { ConvexError } from "convex/values";
+
+//#region src/client/index.ts
+/**
+* Framework-agnostic auth client for `@estifanos-sh/convex-auth/client`.
+*
+* Exposes the {@link client} factory, which wires auth tokens into a Convex
+* transport and returns `signIn`, `signOut`, `subscribe`, `getSnapshot`, and the
+* factor helpers enabled by the configured providers. Platform entrypoints
+* (`browser`, `expo`) layer concrete runtime defaults on top of this.
+*
+* @module
+*/
+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_BASE_MS = 500;
+const RETRY_MAX_RETRIES = 2;
+const DEFAULT_AUTH_HANDSHAKE_TIMEOUT_MS = 5e3;
+const FORCED_REFRESH_REUSE_MS = 1e4;
+const retryWithJitteredBackoff = (fn, shouldRetry) => retryWithBackoff(fn, {
+	maxRetries: RETRY_MAX_RETRIES,
+	baseMs: RETRY_BASE_MS,
+	jitterMode: "centered",
+	shouldRetry
+});
+/**
+* Resolve the Convex deployment URL from the client.
+*
+* `ConvexReactClient` exposes `.url` directly.
+* `ConvexClient` exposes `.client.url` via `BaseConvexClient`.
+*
+* @param convex - The Convex transport to read the deployment URL from.
+* @param explicit - An explicit URL that short-circuits discovery.
+* @returns The resolved deployment URL.
+* @throws {Error} When no URL can be determined and `explicit` is not provided.
+* @internal
+*/
+function resolveUrl(convex, explicit) {
+	if (explicit) return explicit;
+	const candidate = convex;
+	const client = typeof candidate.client === "object" && candidate.client !== null ? candidate.client : void 0;
+	const url = candidate.url ?? client?.url;
+	if (typeof url === "string") return url;
+	throw new Error("Could not determine Convex deployment URL. Pass `url` explicitly.");
+}
+const STABLE_STRINGIFY_MAX_DEPTH = 32;
+function stableStringify(value, depth = 0) {
+	if (depth > STABLE_STRINGIFY_MAX_DEPTH) throw new Error("stableStringify: input exceeds maximum nesting depth");
+	if (value === void 0) return "null";
+	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item, depth + 1)).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).filter(([, entryValue]) => entryValue !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue, depth + 1)}`).join(",")}}`;
+	return JSON.stringify(value);
+}
+function buildSignInRequestKey(provider, params) {
+	return stableStringify({
+		provider: provider ?? null,
+		params
+	});
+}
+function formDataEntries(formData) {
+	return formData;
+}
+function resolveExplicitToken(value) {
+	if (value === void 0) return void 0;
+	if (value === null) return null;
+	if (value.trim().length === 0) return null;
+	if (value.trim() !== value) throw new Error("The `token` option must not include leading or trailing whitespace.");
+	return value;
+}
+/**
+* Decode the `sub` (subject / user id) claim from a JWT access token without
+* verifying its signature. Used only to compare identities across browser tabs
+* — never for authorization. Returns `null` when the token cannot be decoded.
+*/
+function decodeJwtSubject(jwt) {
+	try {
+		const payloadSegment = jwt.split(".")[1];
+		if (payloadSegment === void 0 || payloadSegment.length === 0) return null;
+		const normalized = payloadSegment.replace(/-/g, "+").replace(/_/g, "/");
+		const padded = normalized + "=".repeat((4 - normalized.length % 4) % 4);
+		if (typeof atob !== "function") return null;
+		const claims = JSON.parse(atob(padded));
+		return typeof claims.sub === "string" ? claims.sub : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Create a framework-agnostic auth client.
+*
+* Returns an object with `signIn`, `signOut`, `subscribe`, `getSnapshot`, and any
+* factor helpers enabled by your configured providers. Platform-specific
+* WebAuthn support is added by higher-level entrypoints such as
+* `@estifanos-sh/convex-auth/browser`.
+*
+* ### SPA mode (default)
+*
+* ```ts
+* import { ConvexClient } from 'convex/browser';
+* import { client } from '@estifanos-sh/convex-auth/client';
+* import { api } from '../convex/_generated/api';
+*
+* const convex = new ConvexClient(CONVEX_URL);
+* const auth = client({ convex, api: api.auth });
+* ```
+*
+* ### Proxy mode
+*
+* ```ts
+* const auth = client({
+*   convex,
+*   proxyPath: '/api/auth',
+*   runtime: myRuntime,
+* });
+* ```
+*
+* In proxy mode all auth operations go through the injected proxy runtime.
+* Tokens are stored in httpOnly cookies server-side — the client
+* holds the JWT in memory only.
+*
+* The client resolves auth through a Convex confirmation handshake. For SSR,
+* pass the server-known token via `token` so hydration starts from the same
+* resolved state. The returned client also auto-wires its tokens into the
+* passed Convex client via `setAuth`, so queries and mutations are
+* authenticated without further configuration.
+*
+* While a sign-in handshake is pending, a transient `false` from the Convex
+* client does not reject the session: Convex can emit `false` mid-reauth and a
+* subsequent `true` confirms the same session. Rejection happens only on
+* timeout or when the token actually changes or clears.
+*
+* @param options - Client configuration. See {@link ClientOptions}.
+* @typeParam Api - An AuthApiRefs type determining which factor helpers are available.
+* @returns Auth client with conditional `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.
+* @throws {Error} When `proxyPath` is set and `runtime.proxy` is missing.
+* @throws {Error} When `token` has leading or trailing whitespace. An empty or
+*   whitespace-only string is treated as an explicit signed-out seed, not an error.
+*/
+function client(options) {
+	const { convex, proxyPath, api: apiRefs } = options;
+	const proxy = proxyPath;
+	const runtime = options.runtime ?? {};
+	const adapters = options.adapters ?? {};
+	const adapterFactories = options.adapterFactories ?? {};
+	function requireProxyRuntime() {
+		if (!runtime.proxy) throw new Error("The `runtime.proxy` option is required when `proxyPath` is set. Use `@estifanos-sh/convex-auth/browser` for browser defaults or inject a proxy runtime explicitly.");
+		return runtime.proxy;
+	}
+	function requireApiRefs() {
+		if (!apiRefs) throw new Error("The `api` option is required when `proxyPath` is not set. Pass { api: api.auth }.");
+		return apiRefs;
+	}
+	function requireHttpClient() {
+		if (!httpClient) throw new Error("The `httpClient` option is required when `proxyPath` is not set in a non-browser runtime. Use `@estifanos-sh/convex-auth/browser` for browser defaults or pass an action-only transport explicitly.");
+		return httpClient;
+	}
+	const storage = options.storage !== void 0 ? options.storage : runtime.storage !== void 0 ? runtime.storage : null;
+	const proxyRuntime = proxy ? requireProxyRuntime() : null;
+	function getLocation() {
+		if (typeof options.location === "function") return options.location();
+		if (options.location instanceof URL) return options.location;
+		if (runtime.location) return runtime.location.get();
+		return null;
+	}
+	/**
+	* SSR-safe URL parameter reader.
+	*
+	* Uses the injected location source when provided.
+	*
+	* @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;
+		if (!runtime.location) 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;
+			runtime.location.replace(next);
+		}
+	}
+	const url = proxy ? void 0 : resolveUrl(convex, options.url);
+	const escapedNamespace = (proxy ?? url).replace(/^https?:\/\//, "").replace(/[^a-zA-Z0-9]/g, "_");
+	const key = (name) => `${name}_${escapedNamespace}`;
+	const { get: storageGet, set: storageSet, remove: storageRemove } = createStorageHelpers({
+		storage,
+		key
+	});
+	const withAuthStorageMutex = async (callback) => {
+		const mutexKey = `__convexAuthStorage_${escapedNamespace}`;
+		return runtime.mutex ? await runtime.mutex.withKey(mutexKey, callback) : await localMutex(mutexKey, callback);
+	};
+	const proxyFetch = async (body) => {
+		if (!proxy) throw new Error("Proxy fetch requested without proxyPath.");
+		const response = await proxyRuntime.fetch(body, proxy);
+		if (!response.ok) {
+			let errorBody = {};
+			try {
+				errorBody = parseProxyErrorBody(await response.json());
+			} catch {
+				errorBody = {};
+			}
+			if (typeof errorBody === "object" && errorBody !== null && "authError" in errorBody && typeof errorBody.authError === "object") throw new ConvexError(errorBody.authError);
+			throw new ProxyRequestError(response.status, errorBody.error);
+		}
+		try {
+			return await response.json();
+		} catch {
+			throw new Error("Proxy response was not valid JSON");
+		}
+	};
+	const subscribers = /* @__PURE__ */ new Set();
+	let disposeStorageListener = null;
+	const httpClient = proxy ? null : options.httpClient ?? null;
+	const readInitialToken = () => {
+		if (!storage) return null;
+		try {
+			const raw = storage.getItem(key(JWT_STORAGE_KEY));
+			return typeof raw === "string" && raw.length > 0 ? raw : null;
+		} catch {
+			return null;
+		}
+	};
+	const explicitToken = resolveExplicitToken(options.token);
+	const tokenProvided = explicitToken !== void 0;
+	const serverToken = tokenProvided ? explicitToken : readInitialToken();
+	const hasServerToken = serverToken !== null;
+	const handshakeTimeoutMs = typeof options.handshakeTimeoutMs === "number" && options.handshakeTimeoutMs > 0 ? options.handshakeTimeoutMs : DEFAULT_AUTH_HANDSHAKE_TIMEOUT_MS;
+	let token = serverToken;
+	let isLoading = !hasServerToken && !tokenProvided;
+	let authConfirmed = hasServerToken;
+	let handshakePending = false;
+	let authEpoch = 0;
+	let lastForcedRefreshTime = 0;
+	let forcedRefreshPromise = null;
+	let destroyed = false;
+	let deauthGraceTimer = null;
+	let activeSignIn = null;
+	let initializePromise = null;
+	const handshakeWaiters = /* @__PURE__ */ new Set();
+	let snapshot = {
+		phase: hasServerToken ? "authenticated" : isLoading ? "loading" : "unauthenticated",
+		isLoading,
+		isAuthenticated: hasServerToken,
+		token
+	};
+	const computePublic = () => {
+		if (snapshot.token !== null && snapshot.phase === "authenticated") return {
+			status: "signedIn",
+			token: snapshot.token
+		};
+		if (snapshot.phase === "loading" || snapshot.phase === "handshake") return {
+			status: "loading",
+			token: null
+		};
+		return {
+			status: "signedOut",
+			token: null
+		};
+	};
+	let publicSnapshot = computePublic();
+	const authStatesEqual = (left, right) => left.status === right.status && left.token === right.token;
+	const refreshPublic = () => {
+		const next = computePublic();
+		if (authStatesEqual(publicSnapshot, next)) return false;
+		publicSnapshot = next;
+		return true;
+	};
+	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.deferred.resolve(void 0);
+			else waiter.deferred.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.deferred.reject(createHandshakeError("AUTH_HANDSHAKE_REJECTED", {
+				...waiter.context,
+				reason: "token_changed"
+			}));
+		}
+	};
+	const rejectAllHandshakeWaiters = (error) => {
+		for (const waiter of Array.from(handshakeWaiters)) {
+			clearTimeout(waiter.timeoutId);
+			handshakeWaiters.delete(waiter);
+			waiter.deferred.reject(error);
+		}
+	};
+	const clearDeauthGrace = () => {
+		if (deauthGraceTimer !== null) {
+			clearTimeout(deauthGraceTimer);
+			deauthGraceTimer = null;
+		}
+	};
+	/**
+	* Arm the bounded re-handshake window after Convex reports a confirmed
+	* session as unauthenticated. The public snapshot is intentionally left on
+	* the confirmed state so a transient mid-rotation `false` does not flicker the
+	* UI; only if no confirming `true` arrives before the window elapses (and the
+	* token identity is unchanged) do we sign out.
+	*/
+	const startDeauthGrace = () => {
+		if (deauthGraceTimer !== null) return;
+		const epoch = authEpoch;
+		deauthGraceTimer = setTimeout(() => {
+			deauthGraceTimer = null;
+			if (destroyed || authEpoch !== epoch || !authConfirmed || token === null) return;
+			setToken({
+				shouldStore: true,
+				tokens: null
+			}).catch((error) => {
+				logMessage("convex-auth/client", LOG_LEVELS.ERROR, ["[convex-auth] Sign-out after server-side deauthentication failed:", error]);
+			});
+		}, handshakeTimeoutMs);
+	};
+	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;
+		const deferred = createDeferred();
+		const waiter = {
+			epoch,
+			context,
+			deferred,
+			timeoutId: setTimeout(() => {
+				handshakeWaiters.delete(waiter);
+				deferred.reject(createHandshakeError("AUTH_HANDSHAKE_TIMEOUT", {
+					...context,
+					timeoutMs: handshakeTimeoutMs
+				}));
+				if (!destroyed && authEpoch === epoch && token !== null && handshakePending) {
+					const timedOutToken = token;
+					withAuthStorageMutex(async () => {
+						if (destroyed || authEpoch !== epoch || token !== timedOutToken || !handshakePending) return;
+						await storageRemove(JWT_STORAGE_KEY);
+						if (destroyed || authEpoch !== epoch || token !== timedOutToken || !handshakePending) return;
+						await setToken({
+							shouldStore: false,
+							tokens: null
+						});
+					}).catch((error) => {
+						logMessage("convex-auth/client", LOG_LEVELS.ERROR, ["[convex-auth] Sign-out after handshake timeout failed:", error]);
+					});
+				}
+			}, handshakeTimeoutMs)
+		};
+		handshakeWaiters.add(waiter);
+		try {
+			await deferred.promise;
+		} finally {
+			clearTimeout(waiter.timeoutId);
+			handshakeWaiters.delete(waiter);
+		}
+	};
+	const handleConvexAuthChange = (isAuthenticated) => {
+		if (destroyed) return;
+		if (isAuthenticated) {
+			authConfirmed = true;
+			handshakePending = false;
+			clearDeauthGrace();
+			settleHandshakeWaiters(authEpoch, { type: "resolve" });
+		} else if (token === null || !authConfirmed) {
+			authConfirmed = false;
+			if (token !== null) handshakePending = true;
+		} else startDeauthGrace();
+		if (updateSnapshot()) notify();
+	};
+	const notify = () => {
+		refreshPublic();
+		for (const cb of subscribers) cb();
+	};
+	const updateSnapshot = () => {
+		const phase = token !== null && handshakePending ? "handshake" : isLoading ? "loading" : token !== null && authConfirmed ? "authenticated" : "unauthenticated";
+		const next = {
+			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) return false;
+		snapshot = next;
+		return true;
+	};
+	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();
+	const bindConvexAuth = () => {
+		convex.setAuth(fetchAccessToken, handleConvexAuthChange);
+	};
+	const setToken = async (args) => {
+		const previousToken = token;
+		token = args.tokens === null ? null : args.tokens.token;
+		const tokenChanged = token !== previousToken;
+		if (tokenChanged) {
+			authEpoch += 1;
+			rejectObsoleteHandshakeWaiters(authEpoch);
+			clearDeauthGrace();
+		}
+		if (args.tokens === null) lastForcedRefreshTime = 0;
+		if (args.shouldStore) await withAuthStorageMutex(async () => {
+			if (args.tokens === null) {
+				await storageRemove(JWT_STORAGE_KEY);
+				await storageRemove(REFRESH_TOKEN_STORAGE_KEY);
+			} else if ("refreshToken" in args.tokens) {
+				await storageSet(JWT_STORAGE_KEY, args.tokens.token);
+				await storageSet(REFRESH_TOKEN_STORAGE_KEY, args.tokens.refreshToken);
+			}
+		});
+		if (token === null) {
+			authConfirmed = false;
+			handshakePending = false;
+			settleHandshakeWaiters(authEpoch, {
+				type: "reject",
+				error: createHandshakeError("AUTH_HANDSHAKE_REJECTED", { reason: "token_cleared" })
+			});
+		} else if (!(authConfirmed && args.resyncConvexAuth === false && args.requireHandshake !== true) && (args.requireHandshake === true || tokenChanged || !authConfirmed)) {
+			authConfirmed = false;
+			handshakePending = true;
+		} else handshakePending = false;
+		const hadPendingLoad = isLoading;
+		isLoading = false;
+		const changed = updateSnapshot();
+		if (args.resyncConvexAuth !== false) bindConvexAuth();
+		if (hadPendingLoad || changed) notify();
+	};
+	const setTokenAndMaybeWait = async (args) => {
+		const { waitForHandshake, context, ...tokenArgs } = args;
+		await setToken({
+			...tokenArgs,
+			requireHandshake: waitForHandshake
+		});
+		if (tokenArgs.tokens === null) return false;
+		if (waitForHandshake) await waitForAuthHandshake(context);
+		return true;
+	};
+	const adapterDeps = {
+		proxy,
+		convex,
+		requireApiRefs,
+		proxyFetch,
+		setTokenAndMaybeWait
+	};
+	const webauthnAdapter = adapters.webauthn ?? adapterFactories.webauthn?.(adapterDeps);
+	const verifyCode = async (args) => {
+		return retryWithJitteredBackoff(() => requireHttpClient().action(requireApiRefs().signIn, "code" in args ? {
+			params: { code: args.code },
+			verifier: args.verifier
+		} : args), isTransientNetworkError);
+	};
+	const normalizeDeviceCodeResult = (device_code) => {
+		const input = device_code;
+		return {
+			deviceCode: input.deviceCode,
+			userCode: input.userCode,
+			verificationUri: input.verification_uri ?? input.verificationUri ?? "",
+			verificationUriComplete: input.verification_uri_complete ?? input.verificationUriComplete ?? "",
+			expiresIn: input.expiresIn,
+			interval: input.interval
+		};
+	};
+	const isSignedInResult = (result) => result.kind === "signedIn";
+	/**
+	* Hand an OAuth authorization URL to the platform launcher.
+	*
+	* Browser-style runtimes navigate away and return nothing, so the caller
+	* receives the `redirect` result. Session-style runtimes (Expo) return the
+	* callback URL, which is completed inline and resolves to `signedIn`.
+	*/
+	const launchOAuth = async (redirect, verifier) => {
+		const redirectResult = {
+			kind: "redirect",
+			redirect,
+			verifier
+		};
+		if (!runtime.oauth) return redirectResult;
+		const callback = await runtime.oauth.open(redirect);
+		if (callback === void 0) return redirectResult;
+		return (await completeOAuth(callback)).handled ? { kind: "signedIn" } : redirectResult;
+	};
+	/**
+	* Sign in with a provider.
+	*
+	* @param provider - Provider ID (e.g. `"email"`, `"password"`, `"google"`).
+	*   Omit when exchanging an OAuth code (the code carries the provider info).
+	* @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
+	* await auth.signIn('email', { email: 'user@example.com' });
+	* ```
+	*
+	* @example Password
+	* ```ts
+	* const result = await auth.signIn('password', { email, password, flow: 'signIn' });
+	* if (result.kind === 'totpRequired') {
+	*   await auth.totp.verify({ code: totpCode, verifier: result.verifier });
+	* }
+	* ```
+	*
+	* @example OAuth (returns a redirect URL)
+	* ```ts
+	* const result = await auth.signIn('google');
+	* if (result.kind === 'redirect') {
+	*   window.location.href = result.redirect.toString();
+	* }
+	* ```
+	*/
+	const signIn = async (provider, args) => {
+		if (destroyed) throw new Error("Convex auth client has been destroyed.");
+		await persistInvite();
+		const rawParams = args instanceof FormData ? (() => {
+			const formParams = {};
+			for (const [key$1, value] of formDataEntries(args)) if (typeof value === "string") formParams[key$1] = value;
+			return formParams;
+		})() : args ?? {};
+		const params = options.oauthRedirectTo !== void 0 && rawParams.redirectTo === void 0 ? {
+			...rawParams,
+			redirectTo: options.oauthRedirectTo
+		} : rawParams;
+		const flow = typeof params.flow === "string" && params.flow.length > 0 ? params.flow : "signIn";
+		const signInKey = buildSignInRequestKey(provider, params);
+		const handleSignInActionResult = async (result, resultOptions) => {
+			if (result.kind === "redirect") {
+				const redirectUrl = new URL(result.redirect);
+				if (resultOptions.persistVerifier) await storageSet(VERIFIER_STORAGE_KEY, result.verifier);
+				return {
+					kind: "redirect",
+					redirect: redirectUrl,
+					verifier: result.verifier
+				};
+			}
+			if (result.kind === "totpRequired") return {
+				kind: "totpRequired",
+				verifier: result.verifier
+			};
+			if (result.kind === "deviceCode") return {
+				kind: "deviceCode",
+				deviceCode: normalizeDeviceCodeResult(result.deviceCode)
+			};
+			if (result.kind === "signedIn") return await setTokenAndMaybeWait(resultOptions.shouldStore ? {
+				shouldStore: true,
+				tokens: result.session,
+				waitForHandshake: true,
+				context: {
+					provider,
+					flow
+				}
+			} : {
+				shouldStore: false,
+				tokens: result.session === null ? null : { token: result.session.token },
+				waitForHandshake: true,
+				context: {
+					provider,
+					flow
+				}
+			}) ? { kind: "signedIn" } : { kind: "started" };
+			return { kind: "started" };
+		};
+		if (activeSignIn !== null) {
+			if (activeSignIn.key === signInKey) return await activeSignIn.promise;
+			throw new Error("Another sign-in flow is already in progress.");
+		}
+		const runSignInAction = async () => {
+			if (proxy) return await handleSignInActionResult(await proxyFetch({
+				action: "auth:signIn",
+				args: {
+					provider,
+					params
+				}
+			}), {
+				shouldStore: false,
+				persistVerifier: false
+			});
+			const verifier = await storageGet(VERIFIER_STORAGE_KEY) ?? void 0;
+			try {
+				const result = await convex.action(requireApiRefs().signIn, {
+					provider,
+					params,
+					verifier
+				});
+				if (params.code !== void 0) await storageRemove(VERIFIER_STORAGE_KEY);
+				return await handleSignInActionResult(result, {
+					shouldStore: true,
+					persistVerifier: true
+				});
+			} catch (error) {
+				if (params.code !== void 0) {
+					const convexCode = error instanceof ConvexError && typeof error.data?.code === "string" ? error.data.code : null;
+					if (convexCode !== null && ["INVALID_VERIFICATION_CODE", "INVALID_VERIFIER"].includes(convexCode)) await storageRemove(VERIFIER_STORAGE_KEY);
+				}
+				throw error;
+			}
+		};
+		const signInPromise = (async () => {
+			const result = await runSignInAction();
+			return result.kind === "redirect" ? await launchOAuth(result.redirect, result.verifier) : result;
+		})();
+		activeSignIn = {
+			key: signInKey,
+			promise: signInPromise
+		};
+		try {
+			return await signInPromise;
+		} finally {
+			if (activeSignIn?.promise === signInPromise) activeSignIn = null;
+		}
+	};
+	/**
+	* Sign out the current user.
+	*
+	* Invalidates the server session and clears local token state.
+	* Errors are silently caught — calling `signOut` on an already
+	* signed-out user is a no-op.
+	*/
+	const signOut = async () => {
+		if (destroyed) return;
+		if (proxy) {
+			try {
+				await proxyFetch({
+					action: "auth:signOut",
+					args: {}
+				});
+			} catch {}
+			await setToken({
+				shouldStore: false,
+				tokens: null
+			});
+			if (convex.clearAuth) convex.clearAuth();
+			return;
+		}
+		try {
+			await convex.action(requireApiRefs().signOut, {});
+		} catch {}
+		await setToken({
+			shouldStore: true,
+			tokens: null
+		});
+		if (convex.clearAuth) convex.clearAuth();
+	};
+	const fetchAccessToken = async ({ forceRefreshToken }) => {
+		if (destroyed) return null;
+		if (!forceRefreshToken) return token;
+		if (forcedRefreshPromise !== null) return await forcedRefreshPromise;
+		if (token !== null && Date.now() - lastForcedRefreshTime < FORCED_REFRESH_REUSE_MS) return token;
+		forcedRefreshPromise = (async () => {
+			try {
+				return await refreshAccessToken();
+			} finally {
+				forcedRefreshPromise = null;
+			}
+		})();
+		return await forcedRefreshPromise;
+	};
+	async function refreshAccessToken() {
+		const mutex = runtime.mutex;
+		const withMutex = mutex ? (key$1, callback) => mutex.withKey(key$1, callback) : localMutex;
+		if (proxy) {
+			const tokenBeforeRefresh = token;
+			return await withMutex(`__convexAuthProxyRefresh_${escapedNamespace}`, async () => {
+				if (token !== tokenBeforeRefresh) return token;
+				const epochAtRefreshStart = authEpoch;
+				try {
+					const result = await retryWithJitteredBackoff(() => proxyFetch({
+						action: "auth:signIn",
+						args: { refreshToken: true }
+					}), isRetriableProxyRefreshError);
+					if (destroyed || authEpoch !== epochAtRefreshStart) return token;
+					if (isSignedInResult(result) && result.session) {
+						await setToken({
+							shouldStore: false,
+							tokens: { token: result.session.token },
+							resyncConvexAuth: false
+						});
+						lastForcedRefreshTime = Date.now();
+					} else await setToken({
+						shouldStore: false,
+						tokens: null,
+						resyncConvexAuth: false
+					});
+				} catch (error) {
+					logMessage("convex-auth/client", LOG_LEVELS.ERROR, ["[convex-auth] Proxy refresh failed:", error]);
+					if (destroyed || authEpoch !== epochAtRefreshStart) return token;
+					if (isAuthRefreshRejection(error)) await setToken({
+						shouldStore: false,
+						tokens: null,
+						resyncConvexAuth: false
+					});
+					else if (token === null) finalizeLoadingState();
+				}
+				return token;
+			});
+		}
+		const tokenBeforeLockAcquisition = token;
+		return await withMutex(key(REFRESH_TOKEN_STORAGE_KEY), async () => {
+			const tokenAfterLockAcquisition = token;
+			if (tokenAfterLockAcquisition !== tokenBeforeLockAcquisition) return tokenAfterLockAcquisition;
+			const refreshToken = await storageGet(REFRESH_TOKEN_STORAGE_KEY) ?? null;
+			if (!refreshToken) {
+				await setToken({
+					shouldStore: true,
+					tokens: null,
+					resyncConvexAuth: false
+				});
+				return null;
+			}
+			const epochAtRefreshStart = authEpoch;
+			try {
+				const result = await verifyCode({ refreshToken });
+				if (destroyed || authEpoch !== epochAtRefreshStart) return token;
+				if (result.kind !== "signedIn") throw new Error("Code exchange did not return tokens.");
+				await setToken({
+					shouldStore: true,
+					tokens: result.session,
+					resyncConvexAuth: false
+				});
+				lastForcedRefreshTime = Date.now();
+			} catch (error) {
+				if (destroyed || authEpoch !== epochAtRefreshStart) return token;
+				if (isAuthRefreshRejection(error)) {
+					await setToken({
+						shouldStore: true,
+						tokens: null,
+						resyncConvexAuth: false
+					});
+					return null;
+				}
+				logMessage("convex-auth/client", LOG_LEVELS.ERROR, ["[convex-auth] Token refresh failed transiently, keeping session:", error]);
+			}
+			return token;
+		});
+	}
+	const resolveOAuthInput = (input) => {
+		if (input instanceof URL) return {
+			code: input.searchParams.get("code"),
+			cleanupUrl: input.searchParams.has("code") ? (() => {
+				const next = new URL(input.toString());
+				next.searchParams.delete("code");
+				next.searchParams.delete("state");
+				return next;
+			})() : null
+		};
+		if (typeof input === "object") return {
+			code: input.code,
+			cleanupUrl: null
+		};
+		try {
+			const url$1 = new URL(input);
+			return {
+				code: url$1.searchParams.get("code"),
+				cleanupUrl: url$1.searchParams.has("code") ? (() => {
+					const next = new URL(url$1.toString());
+					next.searchParams.delete("code");
+					next.searchParams.delete("state");
+					return next;
+				})() : null
+			};
+		} catch {
+			return {
+				code: input,
+				cleanupUrl: null
+			};
+		}
+	};
+	const replaceWithCleanupUrl = async (cleanupUrl) => {
+		if (!runtime.location) return;
+		const current = runtime.location.get();
+		const relativeUrl = current !== null && cleanupUrl.origin === current.origin ? `${cleanupUrl.pathname}${cleanupUrl.search}${cleanupUrl.hash}` : cleanupUrl.toString();
+		await runtime.location.replace(relativeUrl);
+	};
+	const completeOAuth = async (input) => {
+		const { code, cleanupUrl } = resolveOAuthInput(input);
+		if (!code) return { handled: false };
+		if ((await signIn(void 0, { code })).kind !== "signedIn") throw new Error("OAuth code exchange did not complete sign-in.");
+		if (cleanupUrl) await replaceWithCleanupUrl(cleanupUrl);
+		return {
+			handled: true,
+			cleanupUrl
+		};
+	};
+	const hydrateFromStorage = async () => {
+		const storedToken = await storageGet(JWT_STORAGE_KEY) ?? null;
+		await setToken({
+			shouldStore: false,
+			tokens: storedToken === null ? null : { token: storedToken },
+			resyncConvexAuth: storedToken !== null && storedToken !== token
+		});
+	};
+	const initialize = async () => {
+		if (destroyed) return;
+		if (initializePromise !== null) return await initializePromise;
+		initializePromise = (async () => {
+			if (proxy) {
+				if (!tokenProvided && !hasServerToken && runtime.environment !== "server") try {
+					await fetchAccessToken({ forceRefreshToken: true });
+				} catch (error) {
+					logMessage("convex-auth/client", LOG_LEVELS.ERROR, ["[convex-auth] Proxy token refresh failed:", error]);
+				}
+				return;
+			}
+			if (!tokenProvided && !hasServerToken) try {
+				await hydrateFromStorage();
+			} catch {
+				try {
+					await setToken({
+						shouldStore: false,
+						tokens: null,
+						resyncConvexAuth: false
+					});
+				} catch {}
+			}
+			try {
+				const loc = runtime.location?.get() ?? null;
+				if (loc && loc.searchParams.has("code") && loc.searchParams.has("state")) await completeOAuth(loc);
+			} catch (error) {
+				logMessage("convex-auth/client", LOG_LEVELS.ERROR, ["[convex-auth] OAuth completion failed:", error]);
+			}
+		})();
+		try {
+			await initializePromise;
+		} finally {
+			initializePromise = Promise.resolve();
+		}
+	};
+	const subscribe = (handler) => {
+		let last = null;
+		const emit = () => {
+			const state = publicSnapshot;
+			if (last !== null && authStatesEqual(last, state)) return;
+			last = state;
+			handler(state);
+		};
+		emit();
+		subscribers.add(emit);
+		return () => {
+			subscribers.delete(emit);
+		};
+	};
+	if (!proxy && runtime.sync) {
+		const logStorageSyncError = (error) => {
+			logMessage("convex-auth/client", LOG_LEVELS.ERROR, ["[convex-auth] Storage event handler failed:", error]);
+		};
+		disposeStorageListener = runtime.sync.subscribe(key(JWT_STORAGE_KEY), (value) => {
+			if (destroyed) return;
+			if (value === token) return;
+			if (value === null) {
+				setToken({
+					shouldStore: false,
+					tokens: null
+				}).catch(logStorageSyncError);
+				return;
+			}
+			const incoming = value;
+			if (authConfirmed && token !== null) {
+				const currentSubject = decodeJwtSubject(token);
+				const incomingSubject = decodeJwtSubject(incoming);
+				if (currentSubject !== null && incomingSubject === currentSubject) setToken({
+					shouldStore: false,
+					tokens: { token: incoming },
+					resyncConvexAuth: false
+				}).catch(logStorageSyncError);
+				return;
+			}
+			setToken({
+				shouldStore: false,
+				tokens: { token: incoming }
+			}).catch(logStorageSyncError);
+		}) ?? null;
+	}
+	bindConvexAuth();
+	initialize().catch((error) => {
+		logMessage("convex-auth/client", LOG_LEVELS.ERROR, ["[convex-auth] Client initialization failed:", error]);
+		finalizeLoadingState();
+	});
+	return {
+		initialize,
+		param,
+		get invite() {
+			const pendingInvite = getPendingInvite();
+			if (!pendingInvite) return null;
+			return {
+				token: pendingInvite.token,
+				email: pendingInvite.email,
+				accept: acceptInvite
+			};
+		},
+		completeOAuth,
+		signIn,
+		signOut,
+		subscribe,
+		getSnapshot: () => publicSnapshot,
+		totp: adapters.totp ?? createTotpClient({
+			proxy,
+			convex,
+			requireApiRefs,
+			proxyFetch,
+			setTokenAndMaybeWait
+		}),
+		device: adapters.device ?? createDeviceClient({
+			proxy,
+			convex,
+			requireApiRefs,
+			proxyFetch,
+			setTokenAndMaybeWait
+		}),
+		destroy: () => {
+			destroyed = true;
+			clearDeauthGrace();
+			rejectAllHandshakeWaiters(createHandshakeError("AUTH_HANDSHAKE_REJECTED", { reason: "destroyed" }));
+			disposeStorageListener?.();
+			subscribers.clear();
+		},
+		...webauthnAdapter ? { webauthn: webauthnAdapter } : {}
+	};
+}
+
+//#endregion
+export { client, resolveUrl };
+//# sourceMappingURL=index.js.map