lael-labs/executor

apps/cloud/src/auth/route-paths.ts+10−0

@@ -0,0 +1,10 @@
	1	// Route sets shared between the SSR auth gate (server) and the root
	2	// AuthGate (client) — one source of truth so the two layers can't disagree
	3	// about which pages a given auth state may see. Pure data, safe in both
	4	// bundles.
	5
	6	/** Pages that render for SIGNED-OUT visitors (the gate lets them through). */
	7	export const PUBLIC_PATHS = new Set(["/login"]);
	8
	9	/** Pages an authenticated-but-org-less user is FOR (everything else redirects to onboarding). */
	10	export const ONBOARDING_PATHS = new Set(["/create-org", "/setup-mcp"]);

apps/cloud/src/auth/ssr-gate.ts+128−18

@@ -1,13 +1,19 @@
1	// ---------------------------------------------------------------------------	1	// ---------------------------------------------------------------------------
2	// SSR auth gate — the server-side session check for DOCUMENT requests.	2	// SSR auth gate — the server-side session check for DOCUMENT requests.
3	//	3	//
4	// Before this gate, every signed-out visitor was served the SPA, whose root	4	// The sealed `wos-session` cookie is verified right here in the worker
5	// AuthGate SSRs the AUTHENTICATED app-shell skeleton until a client-side
6	// `/account/me` round trip 401s — the "bad skeleton on unauthed state" flash.
7	// The sealed `wos-session` cookie can be verified right here in the worker
8	// (unseal + JWT check against cached JWKS — no per-request WorkOS round trip	5	// (unseal + JWT check against cached JWKS — no per-request WorkOS round trip
9	// except token refresh), so signed-out visitors are 302'd to /login before any	6	// except token refresh), so by the time the SPA is served the server KNOWS
10	// app HTML exists, and signed-in visitors proceed knowing the session is real.	7	// who it's serving:
		8	//
		9	// - signed out → 302 /login (carrying ?returnTo=) before any app HTML exists
		10	// - org-less → 302 /create-org (onboarding owns those sessions)
		11	// - signed in → the document is served WITH the verified identity: the
		12	// auth-hint travels to the SSR render via request-middleware context (the
		13	// root loader picks it up), and is minted as a cookie when the browser
		14	// doesn't hold a current one — so the very first paint is the real app
		15	// shell, never a skeleton. The hint is display-only; /account/me remains
		16	// the authority and the client keeps it fresh from then on.
11	//	17	//
12	// Scope: GET/HEAD requests that are document navigations (sec-fetch-dest /	18	// Scope: GET/HEAD requests that are document navigations (sec-fetch-dest /
13	// accept), excluding app-owned paths (/api, /mcp — they answer for themselves	19	// accept), excluding app-owned paths (/api, /mcp — they answer for themselves
@@ -15,19 +21,31 @@ · 1 unmodified line
15	// ---------------------------------------------------------------------------	21	// ---------------------------------------------------------------------------
16		22
17	import { createMiddleware } from "@tanstack/react-start";	23	import { createMiddleware } from "@tanstack/react-start";
18	import { Effect, Exit, ManagedRuntime } from "effect";	24	import { Effect, Exit, Layer, ManagedRuntime } from "effect";
19		25
20	import { AUTH_HINT_COOKIE } from "@executor-js/react/multiplayer/auth-hint";	26	import {
		27	AUTH_HINT_COOKIE,
		28	AUTH_HINT_MAX_AGE_SECONDS,
		29	decodeAuthHint,
		30	encodeAuthHint,
		31	type AuthHint,
		32	} from "@executor-js/react/multiplayer/auth-hint";
21		33
22	import { isAppOwnedPath } from "../app-paths";	34	import { isAppOwnedPath } from "../app-paths";
		35	import { makeDbLayer } from "../db/db";
		36	import { makeUserStoreLayer, UserStoreService } from "./context";
23	import { parseCookie } from "./cookies";	37	import { parseCookie } from "./cookies";
		38	import { sealedSessionDisplayName } from "./middleware";
24	import { loginPath, safeReturnTo } from "./return-to";	39	import { loginPath, safeReturnTo } from "./return-to";
		40	import { ONBOARDING_PATHS, PUBLIC_PATHS } from "./route-paths";
25	import { WorkOSClient } from "./workos";	41	import { WorkOSClient } from "./workos";
26		42
27	const SESSION_COOKIE = "wos-session";	43	const SESSION_COOKIE = "wos-session";
28	/** Mirrors the handlers' COOKIE_OPTIONS (path /, HttpOnly, Lax, 7d, Secure). */	44	/** Mirrors the handlers' COOKIE_OPTIONS (path /, HttpOnly, Lax, 7d, Secure). */
29	const SESSION_COOKIE_ATTRIBUTES = "Path=/; HttpOnly; Secure; SameSite=Lax";	45	const SESSION_COOKIE_ATTRIBUTES = "Path=/; HttpOnly; Secure; SameSite=Lax";
30	const SESSION_MAX_AGE = 60 * 60 * 24 * 7;	46	const SESSION_MAX_AGE = 60 * 60 * 24 * 7;
		47	/** Same attributes the client write uses — minus HttpOnly: the SPA reads it. */
		48	const HINT_COOKIE_ATTRIBUTES = "Path=/; Secure; SameSite=Lax";
31		49
32	const isDocumentRequest = (request: Request): boolean => {	50	const isDocumentRequest = (request: Request): boolean => {
33	if (request.method !== "GET" && request.method !== "HEAD") return false;	51	if (request.method !== "GET" && request.method !== "HEAD") return false;
@@ -48,7 +66,14 @@ const isDocumentRequest = (request: Request): boolean => { · 14 unmodified lines
48	let runtime: ManagedRuntime.ManagedRuntime<WorkOSClient, unknown> \| undefined;	66	let runtime: ManagedRuntime.ManagedRuntime<WorkOSClient, unknown> \| undefined;
49	const getRuntime = () => (runtime ??= ManagedRuntime.make(WorkOSClient.Default));	67	const getRuntime = () => (runtime ??= ManagedRuntime.make(WorkOSClient.Default));
50		68
51	type VerifiedSession = { readonly refreshedSession?: string \| undefined };	69	type VerifiedSession = {
		70	readonly userId: string;
		71	readonly email: string;
		72	readonly name: string \| null;
		73	readonly avatarUrl: string \| null;
		74	readonly organizationId: string \| null;
		75	readonly refreshedSession?: string \| undefined;
		76	};
52		77
53	// EVERY failure collapses to "signed out" — WorkOS errors inside the effect	78	// EVERY failure collapses to "signed out" — WorkOS errors inside the effect
54	// and layer-construction errors like a bad cookie password (runPromiseExit	79	// and layer-construction errors like a bad cookie password (runPromiseExit
@@ -58,9 +83,75 @@ const verifySession = async (sealed: string): Promise<VerifiedSession \| null> => · 3 unmodified lines
58	const exit = await getRuntime().runPromiseExit(	83	const exit = await getRuntime().runPromiseExit(
59	Effect.flatMap(WorkOSClient.asEffect(), (workos) => workos.authenticateSealedSession(sealed)),	84	Effect.flatMap(WorkOSClient.asEffect(), (workos) => workos.authenticateSealedSession(sealed)),
60	);	85	);
61	return Exit.isSuccess(exit) ? exit.value : null;	86	if (!Exit.isSuccess(exit) \|\| exit.value === null) return null;
		87	const result = exit.value;
		88	return {
		89	userId: result.userId,
		90	email: result.email,
		91	name: sealedSessionDisplayName(result),
		92	avatarUrl: result.avatarUrl ?? null,
		93	organizationId: result.organizationId ?? null,
		94	refreshedSession: result.refreshedSession,
		95	};
62	};	96	};
63		97
		98	// ── Auth hint ────────────────────────────────────────────────────────────────
		99
		100	/**
		101	* The hint this request should be served with: the browser's own cookie when
		102	* it already matches the verified identity, else one minted fresh from the
		103	* session. `mint` is set when the cookie must also be (re)written — identity
		104	* data freshness (a renamed user/org) is the CLIENT's job via /account/me,
		105	* so the gate only steps in when the ids are wrong, never to rewrite display
		106	* fields (which would ping-pong with the client's authoritative write).
		107	*/
		108	const resolveAuthHint = async (
		109	session: VerifiedSession,
		110	cookieHeader: string \| null,
		111	): Promise<{ hint: AuthHint; mint: boolean }> => {
		112	const existing = decodeAuthHint(parseCookie(cookieHeader, AUTH_HINT_COOKIE));
		113	if (
		114	existing &&
		115	existing.user.id === session.userId &&
		116	(existing.organization?.id ?? null) === session.organizationId
		117	) {
		118	return { hint: existing, mint: false };
		119	}
		120	return {
		121	hint: {
		122	v: 1,
		123	user: {
		124	id: session.userId,
		125	email: session.email,
		126	name: session.name,
		127	avatarUrl: session.avatarUrl,
		128	},
		129	organization: session.organizationId
		130	? { id: session.organizationId, name: await organizationName(session.organizationId) }
		131	: null,
		132	},
		133	mint: true,
		134	};
		135	};
		136
		137	// The sealed session carries the org ID but not its name; the local mirror
		138	// has it. Only consulted when minting (absent/mismatched hint) — never on the
		139	// steady-state path — and over per-request layers, because a connection cached
		140	// in the shared runtime would be reused across requests, which Cloudflare
		141	// forbids. A miss or failure reads as "" — display-only, corrected by the
		142	// client's /account/me write.
		143	const organizationName = async (organizationId: string): Promise<string> => {
		144	const exit = await getRuntime().runPromiseExit(
		145	Effect.flatMap(UserStoreService.asEffect(), (users) =>
		146	users.use((store) => store.getOrganization(organizationId)),
		147	).pipe(Effect.provide(Layer.provide(makeUserStoreLayer(), makeDbLayer()))),
		148	);
		149	return Exit.isSuccess(exit) ? (exit.value?.name ?? "") : "";
		150	};
		151
		152	const hintSetCookie = (hint: AuthHint) =>
		153	`${AUTH_HINT_COOKIE}=${encodeAuthHint(hint)}; ${HINT_COOKIE_ATTRIBUTES}; Max-Age=${AUTH_HINT_MAX_AGE_SECONDS}`;
		154
64	const sessionSetCookie = (sealed: string) =>	155	const sessionSetCookie = (sealed: string) =>
65	`${SESSION_COOKIE}=${sealed}; ${SESSION_COOKIE_ATTRIBUTES}; Max-Age=${SESSION_MAX_AGE}`;	156	`${SESSION_COOKIE}=${sealed}; ${SESSION_COOKIE_ATTRIBUTES}; Max-Age=${SESSION_MAX_AGE}`;
66		157
@@ -88,12 +179,13 @@ export const authGateMiddleware = createMiddleware({ type: "request" }).server( · 21 unmodified lines
88	async ({ pathname, request, next }) => {	179	async ({ pathname, request, next }) => {
89	if (isAppOwnedPath(pathname) \|\| !isDocumentRequest(request)) return next();	180	if (isAppOwnedPath(pathname) \|\| !isDocumentRequest(request)) return next();
90		181
91	const sealed = parseCookie(request.headers.get("cookie"), SESSION_COOKIE);	182	const cookieHeader = request.headers.get("cookie");
		183	const sealed = parseCookie(cookieHeader, SESSION_COOKIE);
92	const url = new URL(request.url);	184	const url = new URL(request.url);
93		185
94	// /login is the one page signed-out visitors are FOR; a signed-in visitor	186	// Public pages are what signed-out visitors are FOR; a signed-in visitor
95	// landing here is bounced straight back to where they were headed.	187	// landing on /login is bounced straight back to where they were headed.
96	if (pathname === "/login") {	188	if (PUBLIC_PATHS.has(pathname)) {
97	const session = sealed ? await verifySession(sealed) : null;	189	const session = sealed ? await verifySession(sealed) : null;
98	if (!session) return next();	190	if (!session) return next();
99	return redirect(safeReturnTo(url.searchParams.get("returnTo")) ?? "/", {	191	return redirect(safeReturnTo(url.searchParams.get("returnTo")) ?? "/", {
@@ -118,14 +210,32 @@ export const authGateMiddleware = createMiddleware({ type: "request" }).server( · 18 unmodified lines
118	return redirect("/", { refreshedSession: session.refreshedSession });	210	return redirect("/", { refreshedSession: session.refreshedSession });
119	}	211	}
120		212
121	const result = await next();	213	// A session with no organization belongs in onboarding — same decision
		214	// the client AuthGate makes mid-session, made here before the document
		215	// exists so the app shell is never painted for an org-less session.
		216	if (!session.organizationId && !ONBOARDING_PATHS.has(pathname)) {
		217	return redirect("/create-org", { refreshedSession: session.refreshedSession });
		218	}
		219
		220	// Serve the document WITH the verified identity: the hint rides to the
		221	// SSR render through middleware context (the root loader reads it), so
		222	// the server paints the real authenticated shell — no loading state, no
		223	// skeleton. Set-cookie writes ride on the rendered response.
		224	const { hint, mint } = await resolveAuthHint(session, cookieHeader);
		225	const result = await next({ context: { authHint: hint } });
		226	if (!mint && !session.refreshedSession) return result;
		227
		228	const response = new Response(result.response.body, result.response);
		229	if (mint) {
		230	// The browser holds no current hint — mint one so the NEXT load (and
		231	// any client-side read) sees the same identity this render used.
		232	response.headers.append("set-cookie", hintSetCookie(hint));
		233	}
122	if (session.refreshedSession) {	234	if (session.refreshedSession) {
123	// WorkOS refresh tokens are single-use: the rotated sealed session MUST	235	// WorkOS refresh tokens are single-use: the rotated sealed session MUST
124	// reach the browser or the next expiry logs the user out.	236	// reach the browser or the next expiry logs the user out.
125	const response = new Response(result.response.body, result.response);
126	response.headers.append("set-cookie", sessionSetCookie(session.refreshedSession));	237	response.headers.append("set-cookie", sessionSetCookie(session.refreshedSession));
127	return response;
128	}	238	}
129	return result;	239	return { ...result, response };
130	},	240	},
131	);	241	);

apps/cloud/src/routes/__root.tsx+33−83

 import type { FrontendErrorReporter } from "@executor-js/react/api/error-reporting";
 import { ExecutorProvider } from "@executor-js/react/api/provider";
 import { OrganizationProvider } from "@executor-js/react/api/organization-context";
-import { Skeleton } from "@executor-js/react/components/skeleton";
 import { Toaster } from "@executor-js/react/components/sonner";
 import { ExecutorPluginsProvider } from "@executor-js/sdk/client";
 import { plugins as clientPlugins } from "virtual:executor/plugins-client";
+import type { AuthHint } from "@executor-js/react/multiplayer/auth-hint";
 import { AuthProvider, useAuth } from "../web/auth";
 import { loginPath } from "../auth/return-to";
+import { ONBOARDING_PATHS, PUBLIC_PATHS } from "../auth/route-paths";
 import { SupportOptions } from "../web/components/support-options";
 import { Shell } from "../web/shell";
 import appCss from "@executor-js/react/globals.css?url";
-const ONBOARDING_PATHS = new Set(["/create-org", "/setup-mcp"]);
-// Routes that render for SIGNED-OUT visitors — the auth gate stays out of
-// their way entirely (the SSR gate in auth/ssr-gate.ts bounces signed-in
-// visitors off /login before the document is even served).
-const PUBLIC_PATHS = new Set(["/login"]);
 if (typeof window !== "undefined" && import.meta.env.VITE_PUBLIC_SENTRY_DSN) {
   Sentry.init({
     dsn: import.meta.env.VITE_PUBLIC_SENTRY_DSN,
 export const Route = createRootRoute({
   notFoundComponent: NotFoundPage,
+  // The verified identity the SSR gate attached to this document request
+  // (ssr-gate.ts → middleware context → serverContext). Loader data is
+  // dehydrated, so the client's first render sees the SAME hint the server
+  // rendered with — the two can't disagree. Client-side re-runs have no
+  // serverContext and return null, which is fine: the hint only seeds
+  // initial state (AuthProvider holds it from there).
+  loader: (opts) => ({
+    authHint:
+      (opts as { serverContext?: { authHint?: AuthHint | null } }).serverContext?.authHint ?? null,
+  }),
   head: () => ({
     meta: [
       { charSet: "utf-8" },
 }
 function RootComponent() {
+  const { authHint } = Route.useLoaderData();
   return (
     <PostHogProvider client={posthog}>
-      <AuthProvider>
+      <AuthProvider initialHint={authHint}>
         <AuthGate />
       </AuthProvider>
     </PostHogProvider>
   );
 }
-function ShellSkeleton() {
+// Neutral, layout-free placeholder for the moments no UI is correct yet: a
-  return (
+// redirect in flight, or the (post-gate, near-impossible) hint-less verified
-    <div className="flex h-screen overflow-hidden">
+// load. Never the app shell's silhouette — that bet is the bug this file's
-      {/* Desktop sidebar skeleton */}
+// gate exists to prevent.
-      <aside className="hidden w-52 shrink-0 border-r border-sidebar-border bg-sidebar md:flex md:flex-col lg:w-56">
+function BlankScreen() {
-        <div className="flex h-12 shrink-0 items-center border-b border-sidebar-border px-4">
+  return <div className="h-screen bg-background" />;
-          <Skeleton className="h-4 w-20" />
-        </div>
-        <nav className="flex flex-1 flex-col gap-1 overflow-y-auto p-2">
-          <Skeleton className="h-7 w-full rounded-md" />
-          <Skeleton className="h-7 w-full rounded-md" />
-          <Skeleton className="h-7 w-full rounded-md" />
-          <Skeleton className="h-7 w-full rounded-md" />
-          <div className="mt-5 mb-2 px-2.5">
-            <Skeleton className="h-3 w-14" />
-          </div>
-          <div className="flex flex-col gap-1">
-            <Skeleton className="h-7 w-11/12 rounded-md" />
-            <Skeleton className="h-7 w-10/12 rounded-md" />
-            <Skeleton className="h-7 w-9/12 rounded-md" />
-          </div>
-        </nav>
-        <div className="shrink-0 border-t border-sidebar-border px-3 py-2.5">
-          <div className="flex items-center gap-2.5">
-            <Skeleton className="size-7 rounded-full" />
-            <div className="flex min-w-0 flex-1 flex-col gap-1">
-              <Skeleton className="h-3 w-24" />
-              <Skeleton className="h-3 w-16" />
-            </div>
-          </div>
-        </div>
-      </aside>
-      {/* Main content skeleton */}
-      <main className="flex min-h-0 flex-1 flex-col overflow-hidden">
-        {/* Mobile top bar */}
-        <div className="flex h-12 shrink-0 items-center justify-between border-b border-border bg-background px-4 md:hidden">
-          <Skeleton className="size-7 rounded-md" />
-          <Skeleton className="h-4 w-20" />
-          <div className="w-7 shrink-0" />
-        </div>
-        <div className="flex min-h-0 flex-1 flex-col gap-6 px-6 py-8">
-          <div className="flex items-center justify-between">
-            <div className="flex flex-col gap-2">
-              <Skeleton className="h-6 w-40" />
-              <Skeleton className="h-4 w-64" />
-            </div>
-            <Skeleton className="h-8 w-28 rounded-md" />
-          </div>
-          <div className="grid gap-3 sm:grid-cols-2 xl:grid-cols-3">
-            {Array.from({ length: 6 }).map((_, i) => (
-              <Skeleton key={i} className="h-24 w-full rounded-lg" />
-            ))}
-          </div>
-        </div>
-      </main>
-    </div>
-  );
 }
 function ShellErrorFallback() {
   const isOnboardingRoute = ONBOARDING_PATHS.has(location.pathname);
   const isPublicRoute = PUBLIC_PATHS.has(location.pathname);
+  // The SSR gate already bounced fresh org-less document requests to
+  // /create-org; this catches the MID-SESSION transitions (org deleted,
+  // membership revoked → /account/me now reports no org).
   const needsOrgRedirect =
     auth.status === "authenticated" &&
     auth.organization == null &&
     return <Outlet />;
   }
-  // Signed-out visitors never reach this point on a fresh document request —
+  // Every state that isn't "authenticated with an org, on a page that wants
-  // the SSR gate (auth/ssr-gate.ts) redirected them to /login before the SPA
+  // the shell" is a moment between redirects or an edge the gates make
-  // was served. So "loading" here means a VERIFIED signed-in user whose
+  // near-impossible (a verified user whose hint hasn't seeded yet). Neutral
-  // /account/me is still in flight (and usually not even that: the auth-hint
+  // blank — the one placeholder that's correct whatever happens next. The
-  // cookie resolves them to "authenticated" a frame after mount), making the
+  // app-shell skeleton this file used to render here is exactly the
-  // app-shell skeleton the right placeholder again.
+  // wrong-UI flash the SSR gate + hint exist to prevent.
-  if (auth.status === "loading") {
+  if (auth.status === "loading" || auth.status === "unauthenticated") {
-    return <ShellSkeleton />;
+    return <BlankScreen />;
-  }
-  // Mid-session sign-out (logout elsewhere, expiry): blank for the moment the
-  // redirect effect above needs — never a skeleton for an app they're out of.
-  if (auth.status === "unauthenticated") {
-    return <div className="h-screen bg-background" />;
   }
   if (isOnboardingRoute) {
   }
   if (auth.organization == null) {
-    return <ShellSkeleton />;
+    return <BlankScreen />;
   }
   return (
     <AutumnProvider pathPrefix="/api/billing">
       <Sentry.ErrorBoundary fallback={<ShellErrorFallback />} showDialog={false}>
         <ExecutorProvider onHandledError={captureFrontendError}>
-          <React.Suspense fallback={<ShellSkeleton />}>
+          <React.Suspense fallback={<BlankScreen />}>
             <ExecutorPluginsProvider plugins={clientPlugins}>
               <OrganizationProvider organizationId={auth.organization.id}>
                 <Shell />

apps/cloud/src/web/auth.tsx+13−2

   useAuth,
   type IdentifyFn,
 } from "@executor-js/react/multiplayer/auth-context";
+import type { AuthHint } from "@executor-js/react/multiplayer/auth-hint";
 import { CloudApiClient } from "./client";
 // ── Provider ───────────────────────────────────────────────────────────────
-export const AuthProvider = ({ children }: { children: React.ReactNode }) => {
+export const AuthProvider = ({
+  children,
+  initialHint,
+}: {
+  children: React.ReactNode;
+  initialHint?: AuthHint | null;
+}) => {
   const posthog = usePostHog();
   const onIdentify = React.useCallback<IdentifyFn>(
     [posthog],
   );
-  return <SharedAuthProvider onIdentify={onIdentify}>{children}</SharedAuthProvider>;
+  return (
+    <SharedAuthProvider onIdentify={onIdentify} initialHint={initialHint}>
+      {children}
+    </SharedAuthProvider>
+  );
 };

e2e/cloud/auth-hint.test.ts+36−35

@@ -1,10 +1,11 @@
1	// Cloud-specific: the auth-hint cookie lifecycle. The sealed session is	1	// Cloud-specific: the auth-hint lifecycle that lets the app paint the REAL
2	// HttpOnly, so on a fresh page load the SPA can't know it's signed in until	2	// authenticated shell with no full-page skeleton, ever. The sealed session is
3	// /account/me resolves — the hint (executor-auth-hint, non-HttpOnly, written	3	// HttpOnly, so the SPA can't derive identity from it — instead the SSR gate
4	// by AuthProvider once /account/me confirms) is what lets the NEXT load paint	4	// verifies the session per document request, renders the shell from that
5	// the real app shell immediately instead of a skeleton. These scenarios pin	5	// verified identity, and MINTS the non-HttpOnly hint cookie
6	// the full loop: confirmed identity writes it, the next load seeds from it	6	// (executor-auth-hint) when the browser doesn't hold a current one. From
7	// while the probe is still in flight, and logout takes it away.	7	// then on AuthProvider keeps the hint fresh on every confirmed /account/me
		8	// and logout takes it away with the session.
8	import { expect } from "@effect/vitest";	9	import { expect } from "@effect/vitest";
9	import { Effect } from "effect";	10	import { Effect } from "effect";
10		11
@@ -14,7 +15,7 @@ import { Browser, Target } from "../src/services"; · 3 unmodified lines
14	const HINT_COOKIE = "executor-auth-hint";	15	const HINT_COOKIE = "executor-auth-hint";
15		16
16	scenario(	17	scenario(
17	"Auth hint · a confirmed session writes the hint, and the next load paints the real shell from it",	18	"Auth hint · the FIRST load on a fresh browser paints the real shell — the gate minted the hint",
18	{},	19	{},
19	Effect.gen(function* () {	20	Effect.gen(function* () {
20	const browser = yield* Browser;	21	const browser = yield* Browser;
@@ -22,25 +23,10 @@ scenario( · 1 unmodified line
22	const identity = yield* target.newIdentity();	23	const identity = yield* target.newIdentity();
23		24
24	yield* browser.session(identity, async ({ page, step }) => {	25	yield* browser.session(identity, async ({ page, step }) => {
25	const hintCookie = async () =>	26	// Hold the auth probe open from the very first request. This browser
26	(await page.context().cookies()).find((cookie) => cookie.name === HINT_COOKIE);	27	// has NEVER loaded the app — no hint cookie exists — which used to be
27		28	// the one case that still showed a full-page skeleton for the whole
28	await step("First signed-in load → /account/me confirms → the hint is written", async () => {	29	// /account/me round trip.
29	await page.goto("/", { waitUntil: "commit" });
30	await page.getByRole("link", { name: "Policies" }).waitFor();
31	// The write happens in an effect after /account/me resolves.
32	await expect.poll(hintCookie, { timeout: 10_000 }).toBeTruthy();
33	});
34
35	const hint = (await hintCookie())!;
36	expect(hint.httpOnly, "the hint is readable by the SPA — that's its job").toBe(false);
37	expect(
38	decodeURIComponent(hint.value),
39	"it carries the confirmed identity (display data only)",
40	).toContain(identity.label);
41
42	// Hold the auth probe open on the SECOND load. Without the hint this
43	// window is a full-page skeleton; with it, the real shell.
44	let probeResolved = false;	30	let probeResolved = false;
45	await page.route("**/api/account/me", async (route) => {	31	await page.route("**/api/account/me", async (route) => {
46	await new Promise((resolve) => setTimeout(resolve, 2_000));	32	await new Promise((resolve) => setTimeout(resolve, 2_000));
@@ -48,19 +34,34 @@ scenario( · 1 unmodified line
48	await route.continue();	34	await route.continue();
49	});	35	});
50		36
51	await step("Reload: the real app shell paints while /account/me is in flight", async () => {	37	await step("First-ever load: the real app shell, immediately", async () => {
52	await page.goto("/", { waitUntil: "commit" });	38	await page.goto("/", { waitUntil: "commit" });
53	// Real nav text — the loading skeleton has no text at all.	39	// Real nav text — a skeleton has no text at all.
54	await page.getByRole("link", { name: "Policies" }).waitFor();	40	await page.getByRole("link", { name: "Policies" }).waitFor();
55	});	41	});
56		42
57	expect(probeResolved, "the shell did NOT wait for /account/me — the hint seeded it").toBe(	43	expect(probeResolved, "the shell did NOT wait for /account/me").toBe(false);
58	false,	44	// The full-page skeleton was a text-free silhouette; the real shell has
59	);	45	// the nav AND this identity's own data in the footer — the SSR render
		46	// knew who it was serving. (Per-SECTION skeletons for in-flight data
		47	// are fine; the silhouette of the whole app is what must never paint.)
		48	// newIdentity names the org after the user (`Org user-xxxx`), so the
		49	// footer's org line is identity-specific text no other user would show.
		50	const orgName = `Org ${identity.label.split("@")[0]}`;
60	expect(	51	expect(
61	await page.getByRole("link", { name: "Billing" }).isVisible(),	52	await page.getByText(orgName).first().isVisible(),
62	"it is the full signed-in nav, not a placeholder",	53	"the shell footer shows THIS identity's organization",
63	).toBe(true);	54	).toBe(true);
		55
		56	// The identity the shell painted from is now pinned for next time: the
		57	// gate minted the hint cookie on the document response itself.
		58	const hint = (await page.context().cookies()).find((c) => c.name === HINT_COOKIE);
		59	expect(hint, "the gate minted the hint on the first response").toBeTruthy();
		60	expect(hint!.httpOnly, "the hint is readable by the SPA — that's its job").toBe(false);
		61	expect(
		62	decodeURIComponent(hint!.value),
		63	"it carries the verified identity (display data only)",
		64	).toContain(identity.label);
64	});	65	});
65	}),	66	}),
66	);	67	);
@@ -74,7 +75,7 @@ scenario( · 7 unmodified lines
74	const identity = yield* target.newIdentity();	75	const identity = yield* target.newIdentity();
75		76
76	yield* browser.session(identity, async ({ page, step }) => {	77	yield* browser.session(identity, async ({ page, step }) => {
77	await step("Load the app signed in (the hint gets written)", async () => {	78	await step("Load the app signed in (the hint arrives with it)", async () => {
78	await page.goto("/", { waitUntil: "commit" });	79	await page.goto("/", { waitUntil: "commit" });
79	await page.getByRole("link", { name: "Policies" }).waitFor();	80	await page.getByRole("link", { name: "Policies" }).waitFor();
80	await expect	81	await expect

e2e/cloud/session-gate.test.ts+28−0

@@ -81,6 +81,34 @@ scenario( · 80 unmodified lines
81	}),	81	}),
82	);	82	);
83		83
		84	scenario(
		85	"Session gate · an org-less session is sent to onboarding before the app shell exists",
		86	{},
		87	Effect.gen(function* () {
		88	// Gate: the REST API plane is mounted on this target.
		89	yield* Api;
		90	const target = yield* Target;
		91
		92	// A verified user with no organization belongs in onboarding — the gate
		93	// decides that at the edge, so the app shell (whose every query needs an
		94	// org) is never even served.
		95	const orgless = yield* target.newIdentity({ org: false });
		96	const gated = yield* documentRequest(
		97	new URL("/tools", target.baseUrl),
		98	orgless.headers!.cookie!,
		99	);
		100	expect(gated.status, "the app page is not served org-less").toBe(302);
		101	expect(gated.headers.get("location"), "…onboarding owns this session").toBe("/create-org");
		102
		103	// The onboarding page itself is served (no redirect loop).
		104	const onboarding = yield* documentRequest(
		105	new URL("/create-org", target.baseUrl),
		106	orgless.headers!.cookie!,
		107	);
		108	expect(onboarding.status, "/create-org renders for the org-less session").toBe(200);
		109	}),
		110	);
		111
84	// The sealed wos-session is iron-sealed JSON { accessToken, refreshToken, … }.	112	// The sealed wos-session is iron-sealed JSON { accessToken, refreshToken, … }.
85	// Corrupting the access token's signature makes the gate's verify fail the	113	// Corrupting the access token's signature makes the gate's verify fail the
86	// same way an EXPIRED token does (invalid JWT → refresh path) — without	114	// same way an EXPIRED token does (invalid JWT → refresh path) — without

e2e/cloud/unauthenticated-skeleton.test.ts+10−3

         await page.goto("/this-page-does-not-exist", { waitUntil: "commit" });
         await page.getByText("Page not found").waitFor();
       });
+      // The 404 renders INSIDE the real shell (nav + identity), not as a
+      // text-free full-page silhouette. Per-section skeletons in the sidebar
+      // (the integration list mid-fetch) are honest loading states and fine.
       expect(
-        await page.locator('[data-slot="skeleton"]').count(),
+        await page.getByRole("link", { name: "Policies" }).isVisible(),
-        "no app-shell skeleton on the 404 page",
+        "the real shell frames the 404",
-      ).toBe(0);
+      ).toBe(true);
+      expect(
+        await page.getByText("Go home").isVisible(),
+        "with the 404 page's action, not a dead end",
+      ).toBe(true);
     });
   }),
 );

packages/react/src/multiplayer/auth-context.tsx+34−8

 // as loading — which the host should never let happen for signed-out users
 // (cloud redirects them to /login during SSR). The hint is display-only;
 // the resolved `/account/me` answer always wins.
+//
+// Hosts whose server can see the hint at render time (cloud: the SSR gate
+// passes it through the root loader) provide `initialHint`, and the
+// authenticated shell is SSR'd outright — both the server render and the
+// first client render derive from the same dehydrated value, so they agree
+// by construction. Hosts without that seam (self-host) omit it and keep the
+// post-mount cookie read: SSR paints loading, the hint applies a frame later.
 // ---------------------------------------------------------------------------
 export type AuthUser = {
 const AuthProviderClient = ({
   children,
   onIdentify,
+  initialHint = null,
 }: {
   children: React.ReactNode;
   onIdentify?: IdentifyFn;
+  initialHint?: AuthHint | null;
 }) => {
   const result = useAtomValue(meAtom);
-  // The hint applies one frame AFTER mount: SSR always renders the loading
+  // With a server-provided hint the first client render matches the SSR'd
-  // state and the first client render must match that HTML, so the cookie
+  // authenticated HTML outright (both derive from the same dehydrated value).
-  // read is deferred to an effect (the documented pattern for client-only
+  // Without one, the cookie read is deferred to an effect: SSR rendered
-  // values). The flip costs a frame, not a network round trip.
+  // loading, and the first client render must match that HTML — the flip
-  const [hint, setHint] = useState<AuthHint | null>(null);
+  // costs a frame, not a network round trip. Initial-value-only state: later
+  // loader re-runs (which lose the server context) must not yank the seed.
+  const [hint, setHint] = useState<AuthHint | null>(initialHint);
   useEffect(() => {
-    setHint(readAuthHintCookie());
+    setHint((current) => current ?? readAuthHintCookie());
   }, []);
   // What `/account/me` actually said — the authority. The atom value only
 export const AuthProvider = ({
   children,
   onIdentify,
+  initialHint = null,
 }: {
   children: React.ReactNode;
   onIdentify?: IdentifyFn;
+  /**
+   * The auth hint as the HOST's server saw it on this request (cloud: from
+   * the SSR gate via the root loader, dehydrated to the client). When set,
+   * SSR paints the authenticated shell instead of a loading state.
+   */
+  initialHint?: AuthHint | null;
 }) => {
   if (typeof window === "undefined") {
-    return <AuthContext.Provider value={{ status: "loading" }}>{children}</AuthContext.Provider>;
+    return (
+      <AuthContext.Provider value={hintState(initialHint) ?? { status: "loading" }}>
+        {children}
+      </AuthContext.Provider>
+    );
   }
-  return <AuthProviderClient onIdentify={onIdentify}>{children}</AuthProviderClient>;
+  return (
+    <AuthProviderClient onIdentify={onIdentify} initialHint={initialHint}>
+      {children}
+    </AuthProviderClient>
+  );
 };

packages/react/src/multiplayer/auth-hint.tsx+3−2

 const AuthHintFromJson = Schema.fromJsonString(AuthHintSchema);
 const decodeAuthHintJson = Schema.decodeUnknownOption(AuthHintFromJson);
-const encodeAuthHintJson = Schema.encodeSync(AuthHintFromJson);
 // The cookie value arrives percent-encoded; a truncated/corrupted one can
 // make decodeURIComponent itself throw, which must read as "no hint".
 const decodeUriComponentOption = Option.liftThrowable(decodeURIComponent);
-/** Encode a hint as a cookie VALUE (URI-encoded JSON). */
+const encodeAuthHintJson = Schema.encodeSync(AuthHintFromJson);
+/** Encode a hint as a wire-ready cookie VALUE (URI-encoded JSON). */
 export const encodeAuthHint = (hint: AuthHint): string =>
   encodeURIComponent(encodeAuthHintJson(hint));