kitcn 0.33.5 → 0.33.7

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # kitcn
 
+## 0.33.7
+
+### Patch Changes
+
+- [#475](https://github.com/udecode/kitcn/pull/475) [`9e513f8`](https://github.com/udecode/kitcn/commit/9e513f85d4742efa041840c45989dfd3e96c883e) Thanks [@EfficiencyCorp](https://github.com/EfficiencyCorp)! - ## Patches
+
+  - Fix `onTokenIdentityChange` letting a token of another user or session into
+    the auth store, Convex, cRPC HTTP headers or the TanStack Start loader: the
+    SSR token, restored sessions, sign-in tokens, JWTs without `exp` and
+    concurrent first tokens are all held to the page's identity and every
+    mounted provider's current `tokenIdentityBaseline` getter, including changes
+    made by `onTokenIdentityAdmitted` before publication.
+  - Fix an identity guard trip staying local to one provider: every mounted
+    provider now hands out no token and publishes unauthenticated, each guarded
+    one closes its client and calls `onTokenIdentityChange` once, including a
+    guard enabled after the trip, and sign-in
+    mutations fail with `TOKEN_IDENTITY_CHANGED` until the page reloads.
+  - Fix the `optimisticAuth` window reopening after Convex refused a token: it
+    now ends at the Convex client's first auth result.
+
+## 0.33.6
+
+### Patch Changes
+
+- [#473](https://github.com/udecode/kitcn/pull/473) [`16e0bb4`](https://github.com/udecode/kitcn/commit/16e0bb46d66a4d7166d577793fcb47f8161efa5d) Thanks [@EfficiencyCorp](https://github.com/EfficiencyCorp)! - - Add opt-in optimistic auth and document identity admission to
+  `ConvexAuthProvider`, with the same guarded token source for Convex and cRPC
+  HTTP requests.
+  - Add Convex-native `optimisticUpdate` support to cRPC `mutationOptions`.
+  - Reuse the Convex client's logger for server HTTP clients so construction is
+    deterministic during prerendering.
+
 ## 0.33.5
 
 ### Patch Changes

package/dist/aggregate/index.d.ts

@@ -1,5 +1,5 @@
 import { Vn as ConvexTextBuilderInitial, Zt as ConvexTableWithColumns } from "../capabilities-Bxzoofl4.js";
-import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-qH6-NCM9.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-DAqhUREe.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Infer, Value } from "convex/values";
 import { DocumentByName, GenericDataModel, GenericDatabaseReader, GenericDatabaseWriter, TableNamesInDataModel } from "convex/server";

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

@@ -398,6 +398,75 @@ type ConvexAuthProviderProps = {
     queryName: string;
   }) => void; /** Custom function to detect UNAUTHORIZED errors. Default checks code property. */
   isUnauthorized?: (error: unknown) => boolean;
+  /**
+   * Run auth-bound queries as soon as an unexpired JWT is held instead of
+   * after Convex confirms it, until the Convex client reports its first auth
+   * result (confirmed or refused); after that the gate follows Convex's
+   * confirmed state for the client's lifetime, remounts included. Convex
+   * sends them after Authenticate on the same socket and evaluates none of
+   * them if the token is refused; a refused token sets `isAuthenticated` back
+   * to false, which resets auth-bound queries. With the identity guard, only
+   * a token the guard admits opens it. No effect over a client the TanStack
+   * Start loader already authenticated. Every provider over one Convex client
+   * must use the same setting: mixing optimistic and non-optimistic providers
+   * over one client is unsupported, because results the client reports
+   * before an optimistic provider mounts are not seen. Default `false`.
+   */
+  optimisticAuth?: boolean;
+  /**
+   * Fix the identity (JWT `sub` and `sessionId`) the document speaks for: the
+   * one it holds when it mounts (`initialToken`), or, with none, the first
+   * token that carries one. Guarantees: (1) a token of another user or
+   * session (or a JWT without an identity once one is established) is never
+   * cached, published, or handed to Convex, cRPC HTTP or the Start loader;
+   * (2) when a trip happens (this or another provider, or the Start loader,
+   * refuses one), this provider stops handing out tokens (null), publishes
+   * unauthenticated, calls `client.close()` (Convex's close semantics govern
+   * its queued work) and then this, once, where the app should reload the
+   * page. A provider that mounts (or shows again) on a page that is already
+   * tripped starts tripped and does the same, once, so a trip that happened
+   * while no guarded provider was mounted still reaches the app.
+   * The trip is page-wide in the browser (never on the server); sign-in
+   * mutations fail with `AuthMutationError` code `TOKEN_IDENTITY_CHANGED`
+   * until the reload. It governs the token kitcn supplies, not an
+   * `Authorization` header the app sets itself. Same-session refreshes pass
+   * through. Off when not set: a page that never enables it is unchanged.
+   * Once a guarded provider establishes the page identity, it persists until
+   * the reload, binding every provider (with or without this) and the Start
+   * loader, even after that provider unmounts. Two kitcn versions or
+   * revisions on one page (dev HMR across revisions included) are
+   * unsupported: they share no page identity until the reload.
+   */
+  onTokenIdentityChange?: () => void;
+  /**
+   * The identity (`sub|sessionId`, as the guard decodes it from a JWT) the
+   * document already speaks for when this provider mounts, for an app that
+   * mounts the provider more than once in one document (for example one per
+   * route group, over a shared Convex client). The guard starts from it
+   * instead of from `initialToken` or the first token obtained, so a remount
+   * without a token still refuses another user's or session's token.
+   *
+   * A fixed value is read on the first render only. A getter is read at
+   * every admission, cached tokens included, and while this provider is
+   * mounted it binds every provider's admissions. A token must match all of:
+   * the page identity (the first one a provider knew), this provider's
+   * baseline and admitted identity, and every mounted getter's current
+   * answer; any mismatch trips the page. So a provider kept mounted but
+   * hidden (React `<Activity>`) cannot resume under an identity the document
+   * has since moved away from. A getter returning null does not constrain.
+   * Needs `onTokenIdentityChange`.
+   */
+  tokenIdentityBaseline?: string | null | (() => string | null);
+  /**
+   * Called synchronously with every token the identity guard admits, before
+   * Convex or HTTP headers receive it: a fresh token when it is admitted and
+   * cached, a cached token each time it is handed out. The document can claim
+   * the identity at that moment (for example the first token a document
+   * without one obtains). Never called for a refused token. Read from a ref,
+   * so passing a new function does not re-run effects. Needs
+   * `onTokenIdentityChange`.
+   */
+  onTokenIdentityAdmitted?: (token: string) => void;
 };
 /**
  * Unified auth provider for Convex + Better Auth.
@@ -414,7 +483,11 @@ declare function ConvexAuthProvider({
   initialToken,
   onMutationUnauthorized,
   onQueryUnauthorized,
-  isUnauthorized
+  isUnauthorized,
+  optimisticAuth,
+  onTokenIdentityChange,
+  onTokenIdentityAdmitted,
+  tokenIdentityBaseline
 }: ConvexAuthProviderProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 export { type AuthClient, type AuthClientWithPlugins, ConvexAuthProvider, type ConvexAuthProviderClient, ConvexAuthProviderProps, ConvexAuthProviderQueryClient, type PluginsWithCrossDomain, type PluginsWithoutCrossDomain, convexClient };

package/dist/auth/client/index.js

@@ -1,7 +1,7 @@
 'use client';
-import { A as CRPCClientError, C as decodeJwtExp, D as readAuthSessionFallbackToken, E as readAuthSessionFallbackData, O as writeAuthSessionFallbackData, T as clearAuthSessionFallback, d as isSessionSyncGraceActive, g as useAuthValue, h as useAuthStore, j as defaultIsUnauthorized, n as AuthProvider, o as ConvexProviderWithAuth$1, s as FetchAccessTokenContext, t as AUTH_SESSION_SYNC_GRACE_MS } from "../../auth-store-x3_wvhTR.js";
+import { C as FetchAccessTokenContext, D as isSessionSyncGraceActive, H as readAuthSessionFallbackData, K as CRPCClientError, M as useAuthValue, S as ConvexProviderWithAuth$1, U as readAuthSessionFallbackToken, V as clearAuthSessionFallback, W as writeAuthSessionFallbackData, _ as AUTH_SESSION_SYNC_GRACE_MS, a as admitToken, c as identityGuardInPlay, d as isTokenAdmissible, f as joinPage, g as tripDocument, h as subscribeDocumentTrip, i as publishToken, j as useAuthStore, l as isDocumentTripped, m as pageRegistry, n as publishAuthState, o as attachStoreGuard, p as mountGuard, q as defaultIsUnauthorized, s as decodeTokenSubjectSessionIdentity, t as admitStoreToken, u as isJwt, v as AuthProvider, z as decodeJwtExp } from "../../token-gate-CEzbXArg.js";
 import { useConvexAuth } from "convex/react";
-import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/auth/internal/convex-client.ts
@@ -12,6 +12,39 @@ const convexClient = () => {
 	};
 };
 
+//#endregion
+//#region src/auth-client/client-settlement.ts
+function watchClientSettlement(client) {
+	const registry = pageRegistry();
+	if (!registry || registry.watchedClients.has(client)) return;
+	registry.watchedClients.add(client);
+	const setAuth = client.setAuth.bind(client);
+	client.setAuth = (fetchToken, onChange, onRefreshChange) => setAuth(fetchToken, (isAuthenticated) => {
+		settleClient(client);
+		onChange?.(isAuthenticated);
+	}, onRefreshChange);
+}
+function settleClient(client) {
+	const registry = pageRegistry();
+	if (!registry || registry.settledClients.has(client)) return;
+	registry.settledClients.add(client);
+	for (const listener of [...registry.settlementListeners.get(client) ?? []]) listener();
+}
+const isClientSettled = (client) => pageRegistry()?.settledClients.has(client) ?? false;
+const subscribeClientSettlement = (client, listener) => {
+	const registry = pageRegistry();
+	if (!registry) return () => {};
+	let clientListeners = registry.settlementListeners.get(client);
+	if (!clientListeners) {
+		clientListeners = /* @__PURE__ */ new Set();
+		registry.settlementListeners.set(client, clientListeners);
+	}
+	clientListeners.add(listener);
+	return () => {
+		clientListeners.delete(listener);
+	};
+};
+
 //#endregion
 //#region src/auth-client/convex-auth-provider.tsx
 const defaultMutationHandler = () => {
@@ -134,13 +167,61 @@ const clearSessionAtom = (authClient) => {
 * Structure: AuthProvider wraps ConvexAuthProviderInner so that
 * useAuthStore() is available when creating fetchAccessToken.
 */
-function ConvexAuthProvider({ children, client, authClient, convexQueryClient, initialToken, onMutationUnauthorized, onQueryUnauthorized, isUnauthorized }) {
+function ConvexAuthProvider({ children, client, authClient, convexQueryClient, initialToken, onMutationUnauthorized, onQueryUnauthorized, isUnauthorized, optimisticAuth = false, onTokenIdentityChange, onTokenIdentityAdmitted, tokenIdentityBaseline }) {
 	useOTTHandler(authClient);
+	useMemo(() => {
+		if (optimisticAuth) watchClientSettlement(client);
+	}, [client, optimisticAuth]);
+	const baselineRef = useRef(tokenIdentityBaseline);
+	baselineRef.current = tokenIdentityBaseline;
+	const onAdmittedRef = useRef(onTokenIdentityAdmitted);
+	onAdmittedRef.current = onTokenIdentityAdmitted;
+	const [{ guard, inheritedTrip, refusedInitialToken }] = useState(() => {
+		const guarded = onTokenIdentityChange !== void 0;
+		const getter = typeof tokenIdentityBaseline === "function";
+		const fixed = getter ? null : tokenIdentityBaseline ?? null;
+		const created = {
+			baseline: () => {
+				if (!created.guarded) return null;
+				return created.hasGetter ? resolveTokenIdentityBaseline(baselineRef.current) : fixed;
+			},
+			guarded,
+			hasGetter: guarded && getter,
+			heldToken: () => null,
+			identity: guarded ? fixed : null,
+			onAdmitted: (token) => onAdmittedRef.current?.(token),
+			tripped: isDocumentTripped()
+		};
+		const refused = !created.tripped && !!initialToken && !isTokenAdmissible(initialToken, created, "hold");
+		if (refused) created.tripped = true;
+		else if (guarded) created.identity ??= decodeTokenSubjectSessionIdentity(initialToken ?? null);
+		return {
+			guard: created,
+			inheritedTrip: isDocumentTripped(),
+			refusedInitialToken: refused
+		};
+	});
+	useLayoutEffect(() => {
+		const guarded = onTokenIdentityChange !== void 0;
+		guard.hasGetter = guarded && typeof tokenIdentityBaseline === "function";
+		if (guarded === guard.guarded) return;
+		guard.guarded = guarded;
+		if (!guarded) return;
+		guard.identity ??= (guard.hasGetter ? null : guard.baseline()) ?? decodeTokenSubjectSessionIdentity(guard.heldToken());
+		joinPage(guard);
+	});
 	return /* @__PURE__ */ jsx(AuthProvider, {
-		initialValues: useMemo(() => ({
+		initialValues: useMemo(() => refusedInitialToken || inheritedTrip ? {
+			expiresAt: null,
+			token: null
+		} : {
 			expiresAt: initialToken ? decodeJwtExp(initialToken) : null,
 			token: initialToken ?? null
-		}), [initialToken]),
+		}, [
+			initialToken,
+			inheritedTrip,
+			refusedInitialToken
+		]),
 		isUnauthorized: isUnauthorized ?? defaultIsUnauthorized,
 		onMutationUnauthorized: onMutationUnauthorized ?? defaultMutationHandler,
 		onQueryUnauthorized: onQueryUnauthorized ?? (() => {}),
@@ -148,6 +229,11 @@ function ConvexAuthProvider({ children, client, authClient, convexQueryClient, i
 			authClient,
 			client,
 			convexQueryClient,
+			guard,
+			inheritedTrip,
+			onTokenIdentityChange,
+			optimisticAuth,
+			refusedInitialToken,
 			children
 		})
 	});
@@ -156,7 +242,7 @@ function ConvexAuthProvider({ children, client, authClient, convexQueryClient, i
 * Inner provider that has access to AuthStore via useAuthStore().
 * Creates fetchAccessToken and passes it through context (no race condition).
 */
-function ConvexAuthProviderInner({ children, client, authClient, convexQueryClient }) {
+function ConvexAuthProviderInner({ children, client, authClient, convexQueryClient, guard, inheritedTrip, optimisticAuth, onTokenIdentityChange, refusedInitialToken }) {
 	const authStore = useAuthStore();
 	convexQueryClient?.updateAuthStore(authStore);
 	const { data: session, isPending } = authClient.useSession();
@@ -167,13 +253,14 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 	const isMountedRef = useRef(false);
 	sessionRef.current = session;
 	isPendingRef.current = isPending;
+	const isOpaqueUnderGuard = useCallback((token) => identityGuardInPlay(guard) && !isJwt(token), [guard]);
 	const getCachedJwt = useCallback((minTimeRemainingMs = 0) => {
 		const cachedToken = authStore.get("token");
-		if (!cachedToken) return null;
+		if (!cachedToken || isOpaqueUnderGuard(cachedToken)) return null;
 		const expiresAt = decodeJwtExp(cachedToken);
 		if (expiresAt === null || expiresAt <= Date.now() + minTimeRemainingMs) return null;
 		return cachedToken;
-	}, [authStore]);
+	}, [authStore, isOpaqueUnderGuard]);
 	useEffect(() => {
 		if (hasActiveSessionData(session)) {
 			authStore.set("sessionSyncGraceUntil", null);
@@ -190,6 +277,62 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 		isPending,
 		authStore
 	]);
+	const onTokenIdentityChangeRef = useRef(onTokenIdentityChange);
+	onTokenIdentityChangeRef.current = onTokenIdentityChange;
+	attachStoreGuard(authStore.store, guard);
+	const [guardTripped, setGuardTripped] = useState(refusedInitialToken || inheritedTrip);
+	const quarantinedRef = useRef(false);
+	const tripNotifiedRef = useRef(false);
+	const announcedTokenRef = useRef(null);
+	const quarantine = useCallback(() => {
+		guard.tripped = true;
+		authStore.set("token", null);
+		authStore.set("expiresAt", null);
+		authStore.set("sessionSyncGraceUntil", null);
+		authStore.set("isAuthenticated", false);
+		authStore.set("isLoading", false);
+		setGuardTripped(true);
+	}, [authStore, guard]);
+	const tripGuard = useCallback(() => {
+		guard.tripped = true;
+		if (!quarantinedRef.current) {
+			quarantinedRef.current = true;
+			quarantine();
+		}
+		tripDocument();
+		if (tripNotifiedRef.current || !onTokenIdentityChangeRef.current) return;
+		tripNotifiedRef.current = true;
+		try {
+			Promise.resolve(client.close()).catch(() => {});
+		} catch {}
+		try {
+			onTokenIdentityChangeRef.current?.();
+		} catch (error) {
+			console.error("[ConvexAuthProvider] onTokenIdentityChange threw", error);
+		}
+	}, [
+		client,
+		guard,
+		quarantine
+	]);
+	useLayoutEffect(() => {
+		guard.heldToken = () => authStore.get("token");
+		const unsubscribe = subscribeDocumentTrip(tripGuard);
+		const unmount = mountGuard(guard);
+		if (refusedInitialToken || isDocumentTripped()) tripGuard();
+		return () => {
+			unmount();
+			unsubscribe();
+		};
+	}, [
+		authStore,
+		guard,
+		refusedInitialToken,
+		tripGuard
+	]);
+	useLayoutEffect(() => {
+		if (onTokenIdentityChange && isDocumentTripped()) tripGuard();
+	}, [onTokenIdentityChange, tripGuard]);
 	useEffect(() => {
 		isMountedRef.current = true;
 		return () => {
@@ -203,9 +346,11 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 		restoredTokenRef.current = persistedToken;
 		const persistedSessionData = readAuthSessionFallbackData();
 		const graceUntil = Date.now() + AUTH_SESSION_SYNC_GRACE_MS;
-		authStore.set("token", persistedToken);
-		authStore.set("expiresAt", decodeJwtExp(persistedToken));
-		authStore.set("sessionSyncGraceUntil", graceUntil);
+		if (!publishToken(authStore, persistedToken, {
+			announce: true,
+			sessionSyncGraceUntil: graceUntil,
+			use: "restore"
+		})) return;
 		if (persistedSessionData) syncSessionAtom(authClient, persistedSessionData);
 		const ownsToken = () => authStore.get("token") === persistedToken;
 		const shouldStop = () => !isMountedRef.current || !ownsToken();
@@ -244,17 +389,18 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 			if (pendingTokenRef.current) return pendingTokenRef.current;
 			const cachedToken = authStore.get("token");
 			const fetchOptions = { throw: false };
-			if (cachedToken && decodeJwtExp(cachedToken) === null) {
+			if (cachedToken && (decodeJwtExp(cachedToken) === null || isOpaqueUnderGuard(cachedToken))) {
 				fetchOptions.credentials = "omit";
 				fetchOptions.headers = { Authorization: `Bearer ${cachedToken}` };
 			}
 			pendingTokenRef.current = authClient.convex.token({ fetchOptions }).then((result) => {
-				const jwt = result.data?.token || null;
+				const jwt = result?.data?.token || null;
 				if (jwt) {
-					const exp = decodeJwtExp(jwt);
-					authStore.set("token", jwt);
-					authStore.set("expiresAt", exp);
-					authStore.set("sessionSyncGraceUntil", null);
+					if (!publishToken(authStore, jwt, {
+						announce: true,
+						sessionSyncGraceUntil: null
+					})) return null;
+					announcedTokenRef.current = jwt;
 					return jwt;
 				}
 				const cachedJwt = getCachedJwt();
@@ -304,11 +450,7 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 					return fetchFreshToken();
 				}
 				const freshToken = await fetchFreshTokenForced();
-				if (!freshToken && cachedJwt) {
-					authStore.set("token", cachedJwt);
-					authStore.set("expiresAt", decodeJwtExp(cachedJwt));
-					return cachedJwt;
-				}
+				if (!freshToken && cachedJwt) return publishToken(authStore, cachedJwt, { announce: false }) ? cachedJwt : null;
 				return freshToken;
 			}
 			authStore.set("token", null);
@@ -319,15 +461,28 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 		const cachedToken = authStore.get("token");
 		const expiresAt = authStore.get("expiresAt");
 		const timeRemaining = expiresAt ? expiresAt - Date.now() : 0;
-		if (!forceRefreshToken && cachedToken && expiresAt && timeRemaining >= 6e4) return cachedToken;
+		if (!forceRefreshToken && cachedToken && expiresAt && timeRemaining >= 6e4 && !isOpaqueUnderGuard(cachedToken)) return cachedToken;
 		if (!forceRefreshToken && pendingTokenRef.current) return pendingTokenRef.current;
 		if (forceRefreshToken) return fetchFreshTokenForced();
 		return fetchFreshToken();
 	}, [
 		authStore,
 		authClient,
-		getCachedJwt
+		getCachedJwt,
+		isOpaqueUnderGuard
 	]);
+	const guardedFetchAccessToken = useCallback(async (args = {}) => {
+		if (isDocumentTripped()) return null;
+		const token = await fetchAccessToken(args);
+		if (!token) return null;
+		const announced = announcedTokenRef.current === token;
+		if (announced) announcedTokenRef.current = null;
+		return admitToken(token, {
+			announce: !announced,
+			guard,
+			use: "handout"
+		}) ? token : null;
+	}, [fetchAccessToken, guard]);
 	const useAuth = useCallback(function useConvexAuthHook() {
 		const token = authStore.get("token");
 		const hasSession = hasActiveSessionData(sessionRef.current);
@@ -335,15 +490,20 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 		return {
 			isLoading: isPendingRef.current && !token,
 			isAuthenticated: sessionMissing ? false : hasSession || token !== null,
-			fetchAccessToken
+			fetchAccessToken: guardedFetchAccessToken
 		};
-	}, [fetchAccessToken, authStore]);
+	}, [guardedFetchAccessToken, authStore]);
 	return /* @__PURE__ */ jsx(FetchAccessTokenContext.Provider, {
-		value: fetchAccessToken,
+		value: guardedFetchAccessToken,
 		children: /* @__PURE__ */ jsx(ConvexProviderWithAuth$1, {
 			client,
 			useAuth,
-			children: /* @__PURE__ */ jsx(AuthStateSync, { children })
+			children: /* @__PURE__ */ jsx(AuthStateSync, {
+				client,
+				guardTripped,
+				optimisticAuth,
+				children
+			})
 		})
 	});
 }
@@ -359,22 +519,68 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 * 5. Without defensive check, we'd sync { isLoading: false, isAuthenticated: false }
 * 6. Queries would throw UNAUTHORIZED before token is validated
 */
-function AuthStateSync({ children }) {
+function AuthStateSync({ children, client, guardTripped, optimisticAuth = false }) {
 	const { isLoading: convexIsLoading, isAuthenticated } = useConvexAuth();
 	const authStore = useAuthStore();
 	const token = useAuthValue("token");
+	const subscribe = useCallback((listener) => subscribeClientSettlement(client, listener), [client]);
+	const getSettled = useCallback(() => isClientSettled(client), [client]);
+	const settled = useSyncExternalStore(subscribe, getSettled, getSettled);
 	useEffect(() => {
-		const isLoading = convexIsLoading || !!token && !isAuthenticated;
-		authStore.set("isLoading", isLoading);
-		authStore.set("isAuthenticated", isAuthenticated);
+		publishAuthState(authStore, resolveAuthGate({
+			admitHeldToken: (held) => admitStoreToken(authStore, held, { use: "hold" }),
+			convexIsLoading,
+			guardTripped: guardTripped || isDocumentTripped(),
+			isAuthenticated,
+			optimisticWindow: optimisticAuth && !settled && !isClientSettled(client),
+			token: authStore.get("token")
+		}));
 	}, [
+		client,
 		convexIsLoading,
+		guardTripped,
 		isAuthenticated,
+		optimisticAuth,
+		settled,
 		token,
 		authStore
 	]);
 	return children;
 }
+function resolveTokenIdentityBaseline(baseline) {
+	return typeof baseline === "function" ? baseline() : baseline ?? null;
+}
+/**
+* The auth state published to the store, which is what every query gate reads.
+*
+* Without `optimisticAuth` this is the confirmed state: queries wait until
+* Convex has confirmed the token. With it, until the Convex client reports its
+* first auth result, a held, unexpired JWT counts as authenticated while
+* Convex confirms it, so auth-bound queries subscribe at once; Convex sends
+* them after Authenticate on the same socket, and a refused token closes the
+* socket before any of them is evaluated. When Convex refuses the token,
+* `isAuthenticated` falls back to false, which resets auth-bound queries (see
+* `CRPCProviderInner`), and the window is over: no token reopens it.
+*/
+function resolveAuthGate({ admitHeldToken, convexIsLoading, guardTripped, isAuthenticated, optimisticWindow, token }) {
+	if (guardTripped || token !== null && !admitHeldToken(token)) return {
+		isAuthenticated: false,
+		isLoading: false
+	};
+	if (optimisticWindow && convexIsLoading && token !== null && isOptimisticToken(token)) return {
+		isAuthenticated: true,
+		isLoading: false
+	};
+	return {
+		isAuthenticated,
+		isLoading: convexIsLoading || !!token && !isAuthenticated
+	};
+}
+function isOptimisticToken(token) {
+	if (!isJwt(token)) return false;
+	const expiresAt = decodeJwtExp(token);
+	return expiresAt !== null && expiresAt > Date.now();
+}
 /**
 * Handles cross-domain one-time token (OTT) verification.
 */

package/dist/auth/generated/index.d.ts

@@ -1,2 +1,2 @@
-import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, b as GenericAuthBeforeResult, i as getGeneratedAuthDisabledReason, n as GeneratedAuthDisabledReasonKind, r as createDisabledAuthRuntime, t as AuthRuntime, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../../generated-contract-disabled-PdNGvNYP.js";
+import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, b as GenericAuthBeforeResult, i as getGeneratedAuthDisabledReason, n as GeneratedAuthDisabledReasonKind, r as createDisabledAuthRuntime, t as AuthRuntime, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../../generated-contract-disabled-QZXEzUnd.js";
 export { type AuthRuntime, BetterAuthOptionsWithoutDatabase, type GeneratedAuthDisabledReasonKind, GenericAuthBeforeResult, GenericAuthDefinition, GenericAuthTriggerChange, GenericAuthTriggerHandlers, GenericAuthTriggers, createDisabledAuthRuntime, defineAuth, getGeneratedAuthDisabledReason };

package/dist/auth/index.d.ts

@@ -1,7 +1,7 @@
 import { a as QueryCtxWithPreferredOrmQueryTable, n as LookupByIdResultByCtx, t as DocByCtx } from "../query-context-BkNjkDCk.js";
 import { t as GetAuth } from "../types-ex0-J-SC.js";
 import { t as GenericCtx } from "../context-utils-Cbv4r0AA.js";
-import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, _ as updateManyHandler, a as AuthFunctions, b as GenericAuthBeforeResult, c as consumeOneHandler, d as createHandler, f as deleteManyHandler, g as incrementOneHandler, h as findOneHandler, i as getGeneratedAuthDisabledReason, l as countHandler, m as findManyHandler, n as GeneratedAuthDisabledReasonKind, o as Triggers, p as deleteOneHandler, r as createDisabledAuthRuntime, s as createClient, t as AuthRuntime, u as createApi, v as updateOneHandler, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../generated-contract-disabled-PdNGvNYP.js";
+import { C as GenericAuthTriggerHandlers, S as GenericAuthTriggerChange, T as defineAuth, _ as updateManyHandler, a as AuthFunctions, b as GenericAuthBeforeResult, c as consumeOneHandler, d as createHandler, f as deleteManyHandler, g as incrementOneHandler, h as findOneHandler, i as getGeneratedAuthDisabledReason, l as countHandler, m as findManyHandler, n as GeneratedAuthDisabledReasonKind, o as Triggers, p as deleteOneHandler, r as createDisabledAuthRuntime, s as createClient, t as AuthRuntime, u as createApi, v as updateOneHandler, w as GenericAuthTriggers, x as GenericAuthDefinition, y as BetterAuthOptionsWithoutDatabase } from "../generated-contract-disabled-QZXEzUnd.js";
 import * as convex_values0 from "convex/values";
 import { Infer } from "convex/values";
 import { AuthConfig, DocumentByName, GenericDataModel, GenericMutationCtx, GenericQueryCtx, GenericSchema, PaginationOptions, PaginationResult, SchemaDefinition, TableNamesInDataModel } from "convex/server";
@@ -109,31 +109,31 @@ type AdapterPaginationOptions = PaginationOptions & {
 };
 declare const adapterWhereValidator: convex_values0.VObject<{
   mode?: "sensitive" | "insensitive" | undefined;
+  operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
   connector?: "AND" | "OR" | undefined;
-  operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-  field: string;
   value: string | number | boolean | string[] | number[] | null;
+  field: string;
 }, {
   connector: convex_values0.VUnion<"AND" | "OR" | undefined, [convex_values0.VLiteral<"AND", "required">, convex_values0.VLiteral<"OR", "required">], "optional", never>;
   field: convex_values0.VString<string, "required">;
   mode: convex_values0.VUnion<"sensitive" | "insensitive" | undefined, [convex_values0.VLiteral<"sensitive", "required">, convex_values0.VLiteral<"insensitive", "required">], "optional", never>;
-  operator: convex_values0.VUnion<"lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
+  operator: convex_values0.VUnion<"eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
   value: convex_values0.VUnion<string | number | boolean | string[] | number[] | null, [convex_values0.VString<string, "required">, convex_values0.VFloat64<number, "required">, convex_values0.VBoolean<boolean, "required">, convex_values0.VArray<string[], convex_values0.VString<string, "required">, "required">, convex_values0.VArray<number[], convex_values0.VFloat64<number, "required">, "required">, convex_values0.VNull<null, "required">], "required", never>;
-}, "required", "mode" | "connector" | "field" | "operator" | "value">;
+}, "required", "mode" | "operator" | "value" | "field" | "connector">;
 declare const adapterArgsValidator: convex_values0.VObject<{
+  limit?: number | undefined;
   where?: {
     mode?: "sensitive" | "insensitive" | undefined;
+    operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
     connector?: "AND" | "OR" | undefined;
-    operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-    field: string;
     value: string | number | boolean | string[] | number[] | null;
+    field: string;
   }[] | undefined;
-  limit?: number | undefined;
-  offset?: number | undefined;
   select?: string[] | undefined;
+  offset?: number | undefined;
   sortBy?: {
-    field: string;
     direction: "asc" | "desc";
+    field: string;
   } | undefined;
   model: string;
 }, {
@@ -142,32 +142,32 @@ declare const adapterArgsValidator: convex_values0.VObject<{
   offset: convex_values0.VFloat64<number | undefined, "optional">;
   select: convex_values0.VArray<string[] | undefined, convex_values0.VString<string, "required">, "optional">;
   sortBy: convex_values0.VObject<{
-    field: string;
     direction: "asc" | "desc";
+    field: string;
   } | undefined, {
     direction: convex_values0.VUnion<"asc" | "desc", [convex_values0.VLiteral<"asc", "required">, convex_values0.VLiteral<"desc", "required">], "required", never>;
     field: convex_values0.VString<string, "required">;
-  }, "optional", "field" | "direction">;
+  }, "optional", "direction" | "field">;
   where: convex_values0.VArray<{
     mode?: "sensitive" | "insensitive" | undefined;
+    operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
     connector?: "AND" | "OR" | undefined;
-    operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-    field: string;
     value: string | number | boolean | string[] | number[] | null;
+    field: string;
   }[] | undefined, convex_values0.VObject<{
     mode?: "sensitive" | "insensitive" | undefined;
+    operator?: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined;
     connector?: "AND" | "OR" | undefined;
-    operator?: "lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined;
-    field: string;
     value: string | number | boolean | string[] | number[] | null;
+    field: string;
   }, {
     connector: convex_values0.VUnion<"AND" | "OR" | undefined, [convex_values0.VLiteral<"AND", "required">, convex_values0.VLiteral<"OR", "required">], "optional", never>;
     field: convex_values0.VString<string, "required">;
     mode: convex_values0.VUnion<"sensitive" | "insensitive" | undefined, [convex_values0.VLiteral<"sensitive", "required">, convex_values0.VLiteral<"insensitive", "required">], "optional", never>;
-    operator: convex_values0.VUnion<"lt" | "lte" | "gt" | "gte" | "eq" | "in" | "not_in" | "ne" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
+    operator: convex_values0.VUnion<"eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with" | undefined, [convex_values0.VLiteral<"lt", "required">, convex_values0.VLiteral<"lte", "required">, convex_values0.VLiteral<"gt", "required">, convex_values0.VLiteral<"gte", "required">, convex_values0.VLiteral<"eq", "required">, convex_values0.VLiteral<"in", "required">, convex_values0.VLiteral<"not_in", "required">, convex_values0.VLiteral<"ne", "required">, convex_values0.VLiteral<"contains", "required">, convex_values0.VLiteral<"starts_with", "required">, convex_values0.VLiteral<"ends_with", "required">], "optional", never>;
     value: convex_values0.VUnion<string | number | boolean | string[] | number[] | null, [convex_values0.VString<string, "required">, convex_values0.VFloat64<number, "required">, convex_values0.VBoolean<boolean, "required">, convex_values0.VArray<string[], convex_values0.VString<string, "required">, "required">, convex_values0.VArray<number[], convex_values0.VFloat64<number, "required">, "required">, convex_values0.VNull<null, "required">], "required", never>;
-  }, "required", "mode" | "connector" | "field" | "operator" | "value">, "optional">;
-}, "required", "model" | "where" | "limit" | "offset" | "select" | "sortBy" | "sortBy.field" | "sortBy.direction">;
+  }, "required", "mode" | "operator" | "value" | "field" | "connector">, "optional">;
+}, "required", "limit" | "where" | "model" | "select" | "offset" | "sortBy" | "sortBy.direction" | "sortBy.field">;
 declare const hasUniqueFields: (betterAuthSchema: BetterAuthDBSchema, model: string, input: Record<string, any>) => boolean;
 declare const checkUniqueFields: <Schema extends SchemaDefinition<any, any>>(ctx: GenericQueryCtx<GenericDataModel>, schema: Schema, betterAuthSchema: BetterAuthDBSchema, table: string, input: Record<string, any>, doc?: Record<string, any>) => Promise<void>;
 declare const selectFields: <T extends TableNamesInDataModel<GenericDataModel>, D extends DocumentByName<GenericDataModel, T>>(doc: D | null, select?: string[]) => D | null;