kitcn 0.33.6 → 0.33.8

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # kitcn
 
+## 0.33.8
+
+### Patch Changes
+
+- [#478](https://github.com/udecode/kitcn/pull/478) [`03b1ad1`](https://github.com/udecode/kitcn/commit/03b1ad1bd72333ce3867f79d8f079193cf77c170) Thanks [@zbeyens](https://github.com/zbeyens)! - ## Patches
+
+  - Support app-owned synchronous or asynchronous JWT cache clocks for Next.js partial prefetching and private-cache rendering.
+
+## 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

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-BzAJnWt4.js";
+import { C as ConvexNumberBuilderInitial, E as ConvexIdBuilderInitial, N as ConvexCustomBuilderInitial } from "../where-clause-compiler-CTblNxLo.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

@@ -400,21 +400,42 @@ type ConvexAuthProviderProps = {
   isUnauthorized?: (error: unknown) => boolean;
   /**
    * Run auth-bound queries as soon as an unexpired JWT is held instead of
-   * after Convex confirms it. 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, and
-   * never opens the gate again. Default `false`.
+   * 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 it obtains. A token for another user or session is refused before
-   * it is cached, so neither Convex, the optimistic gate nor HTTP headers ever
-   * see it: the Convex client is closed (dropping queued requests and
-   * optimistic updates), every later token request answers null, and this is
-   * called, typically to reload the page. Same-session refreshes pass
-   * through. Off when not set.
+   * 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;
   /**
@@ -426,20 +447,23 @@ type ConvexAuthProviderProps = {
    * 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 a token must match both the
-   * identity it returns and the one this guard already admitted; any
-   * mismatch trips the guard. 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`.
+   * 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 as it is
-   * handed to Convex or HTTP headers, cached tokens included, so 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
+   * 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;

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 = () => {
@@ -136,11 +169,59 @@ const clearSessionAtom = (authClient) => {
 */
 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,10 +229,11 @@ function ConvexAuthProvider({ children, client, authClient, convexQueryClient, i
 			authClient,
 			client,
 			convexQueryClient,
-			onTokenIdentityAdmitted,
+			guard,
+			inheritedTrip,
 			onTokenIdentityChange,
 			optimisticAuth,
-			tokenIdentityBaseline,
+			refusedInitialToken,
 			children
 		})
 	});
@@ -160,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, optimisticAuth, onTokenIdentityChange, onTokenIdentityAdmitted, tokenIdentityBaseline }) {
+function ConvexAuthProviderInner({ children, client, authClient, convexQueryClient, guard, inheritedTrip, optimisticAuth, onTokenIdentityChange, refusedInitialToken }) {
 	const authStore = useAuthStore();
 	convexQueryClient?.updateAuthStore(authStore);
 	const { data: session, isPending } = authClient.useSession();
@@ -171,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);
@@ -194,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 () => {
@@ -207,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();
@@ -243,42 +384,23 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 		authStore,
 		authClient
 	]);
-	const onTokenIdentityChangeRef = useRef(onTokenIdentityChange);
-	onTokenIdentityChangeRef.current = onTokenIdentityChange;
-	const onTokenIdentityAdmittedRef = useRef(onTokenIdentityAdmitted);
-	onTokenIdentityAdmittedRef.current = onTokenIdentityAdmitted;
-	const tokenIdentityBaselineRef = useRef(tokenIdentityBaseline);
-	tokenIdentityBaselineRef.current = tokenIdentityBaseline;
-	const identityGuardRef = useRef(null);
-	identityGuardRef.current ??= {
-		identity: (typeof tokenIdentityBaseline === "function" ? null : resolveTokenIdentityBaseline(tokenIdentityBaseline)) ?? decodeTokenSubjectSessionIdentity(authStore.get("token")),
-		currentDocumentIdentity: typeof tokenIdentityBaseline === "function" ? () => resolveTokenIdentityBaseline(tokenIdentityBaselineRef.current) : null,
-		tripped: false
-	};
-	const admitToken = useCallback((token, onAdmitted) => guardTokenIdentity({
-		client,
-		guard: identityGuardRef.current,
-		onAdmitted,
-		onIdentityChange: onTokenIdentityChangeRef.current,
-		token
-	}), [client]);
 	const fetchAccessToken = useCallback(async ({ forceRefreshToken = false } = {}) => {
 		const fetchFreshToken = () => {
 			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;
-				if (jwt && !admitToken(jwt)) return 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();
@@ -328,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);
@@ -343,7 +461,7 @@ 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();
@@ -351,14 +469,20 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 		authStore,
 		authClient,
 		getCachedJwt,
-		admitToken
+		isOpaqueUnderGuard
 	]);
 	const guardedFetchAccessToken = useCallback(async (args = {}) => {
-		if (identityGuardRef.current?.tripped) return null;
+		if (isDocumentTripped()) return null;
 		const token = await fetchAccessToken(args);
-		if (!token || !admitToken(token, onTokenIdentityAdmittedRef.current)) return null;
-		return token;
-	}, [fetchAccessToken, admitToken]);
+		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);
@@ -375,6 +499,8 @@ function ConvexAuthProviderInner({ children, client, authClient, convexQueryClie
 			client,
 			useAuth,
 			children: /* @__PURE__ */ jsx(AuthStateSync, {
+				client,
+				guardTripped,
 				optimisticAuth,
 				children
 			})
@@ -393,89 +519,55 @@ 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, optimisticAuth = false }) {
+function AuthStateSync({ children, client, guardTripped, optimisticAuth = false }) {
 	const { isLoading: convexIsLoading, isAuthenticated } = useConvexAuth();
 	const authStore = useAuthStore();
 	const token = useAuthValue("token");
-	const rejectedTokenRef = useRef(null);
+	const subscribe = useCallback((listener) => subscribeClientSettlement(client, listener), [client]);
+	const getSettled = useCallback(() => isClientSettled(client), [client]);
+	const settled = useSyncExternalStore(subscribe, getSettled, getSettled);
 	useEffect(() => {
-		const gate = resolveAuthGate({
-			convexIsLoading,
-			isAuthenticated,
-			optimisticAuth,
-			rejectedToken: rejectedTokenRef.current,
-			token
-		});
-		if (optimisticAuth && isTokenRejectedByConvex({
+		publishAuthState(authStore, resolveAuthGate({
+			admitHeldToken: (held) => admitStoreToken(authStore, held, { use: "hold" }),
 			convexIsLoading,
+			guardTripped: guardTripped || isDocumentTripped(),
 			isAuthenticated,
-			token
-		})) rejectedTokenRef.current = token;
-		authStore.set("isLoading", gate.isLoading);
-		authStore.set("isAuthenticated", gate.isAuthenticated);
+			optimisticWindow: optimisticAuth && !settled && !isClientSettled(client),
+			token: authStore.get("token")
+		}));
 	}, [
+		client,
 		convexIsLoading,
+		guardTripped,
 		isAuthenticated,
 		optimisticAuth,
+		settled,
 		token,
 		authStore
 	]);
 	return children;
 }
-function decodeTokenSubjectSessionIdentity(token) {
-	if (!token) return null;
-	try {
-		const segment = token.split(".")[1];
-		if (!segment) return null;
-		const payload = JSON.parse(atob(segment.replaceAll("-", "+").replaceAll("_", "/")));
-		if (typeof payload !== "object" || payload === null) return null;
-		const sub = "sub" in payload ? payload.sub : null;
-		const sessionId = "sessionId" in payload ? payload.sessionId : null;
-		if (typeof sub !== "string") return null;
-		return `${sub}|${typeof sessionId === "string" ? sessionId : ""}`;
-	} catch {
-		return null;
-	}
-}
 function resolveTokenIdentityBaseline(baseline) {
 	return typeof baseline === "function" ? baseline() : baseline ?? null;
 }
-function guardTokenIdentity({ client, guard, onAdmitted, onIdentityChange, token }) {
-	if (!onIdentityChange) return true;
-	if (guard.tripped) return false;
-	const identity = decodeTokenSubjectSessionIdentity(token);
-	if (identity === null) return true;
-	const current = guard.currentDocumentIdentity?.() ?? null;
-	if ((guard.identity === null || guard.identity === identity) && (current === null || current === identity)) {
-		guard.identity = identity;
-		onAdmitted?.(token);
-		return true;
-	}
-	guard.tripped = true;
-	client.close();
-	onIdentityChange();
-	return false;
-}
-/**
-* Convex has settled on "not authenticated" while a token is still held: the
-* server refused it (or refused its refresh).
-*/
-function isTokenRejectedByConvex({ convexIsLoading, isAuthenticated, token }) {
-	return !!token && !convexIsLoading && !isAuthenticated;
-}
 /**
 * 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, a held, unexpired JWT that Convex
-* has not refused yet 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`).
+* 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({ convexIsLoading, isAuthenticated, optimisticAuth, rejectedToken, token }) {
-	if (optimisticAuth && convexIsLoading && isOptimisticToken(token, rejectedToken)) return {
+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
 	};
@@ -484,8 +576,8 @@ function resolveAuthGate({ convexIsLoading, isAuthenticated, optimisticAuth, rej
 		isLoading: convexIsLoading || !!token && !isAuthenticated
 	};
 }
-function isOptimisticToken(token, rejectedToken) {
-	if (!token || token === rejectedToken) return false;
+function isOptimisticToken(token) {
+	if (!isJwt(token)) return false;
 	const expiresAt = decodeJwtExp(token);
 	return expiresAt !== null && expiresAt > Date.now();
 }

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-CFLQf8Wg.js";
 export { type AuthRuntime, BetterAuthOptionsWithoutDatabase, type GeneratedAuthDisabledReasonKind, GenericAuthBeforeResult, GenericAuthDefinition, GenericAuthTriggerChange, GenericAuthTriggerHandlers, GenericAuthTriggers, createDisabledAuthRuntime, defineAuth, getGeneratedAuthDisabledReason };