create-astram-app 0.5.0 → 0.7.0

package/template/frontend/index.html

@@ -2,6 +2,22 @@
 <html lang="en" suppressHydrationWarning>
   <head>
     <meta charset="UTF-8" />
+    <!--
+      Content-Security-Policy (D11). The session tokens live in localStorage, so no script
+      may run unless it is served from this origin: no inline scripts, no eval, no third-party
+      script hosts. Allowed beyond 'self':
+        style-src 'unsafe-inline'  the UI kit (sonner, Radix scroll lock) injects <style> tags
+        fonts.googleapis/gstatic   the Inter/JetBrains Mono import in src/index.css
+        img-src data: blob:        the MFA QR code is a data: URL
+      `npm run dev` relaxes script-src/connect-src for Vite's React-refresh preamble and HMR
+      websocket (see `devCsp` in vite.config.js); the built app gets this policy unchanged.
+      Add an API origin to connect-src if the frontend calls one other than same-origin /api.
+      frame-ancestors cannot be set in a <meta>; send it (or X-Frame-Options) as a header.
+    -->
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: blob:; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'"
+    />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <link rel="icon" type="image/png" href="/favicon.png" />
     <title>__APP_NAME__</title>

package/template/frontend/package.json

@@ -12,7 +12,7 @@
     "test": "node --test src/**/*.test.mjs"
   },
   "dependencies": {
-    "@astram/frontend-core": "^0.4.0",
+    "@astram/frontend-core": "^0.5.1",
     "@astram/sdk": "^0.2.0",
     "@radix-ui/react-alert-dialog": "^1.1.19",
     "@radix-ui/react-avatar": "^1.1.10",

package/template/frontend/src/App.jsx

@@ -10,7 +10,9 @@
 import { useEffect } from 'react';
 import { Navigate, Route, Routes, useLocation } from 'react-router-dom';
 import { useAuth, useCan } from './auth/AuthContext';
+import { Loader2 } from 'lucide-react';
 import { saveReturnPath } from './platform/returnPathStore';
+import { decideRoute, REENROLL_PATH } from './auth/routeGate';
 import Login from './pages/Login';
 import ForgotPassword from './pages/ForgotPassword';
 import ResetPassword from './pages/ResetPassword';
@@ -35,9 +37,6 @@ import GrantsPage from './pages/cross-tenant/GrantsPage';
 import GrantForm from './pages/cross-tenant/GrantForm';
 import InboxPage from './pages/cross-tenant/InboxPage';
 
-/** The single forced-re-enroll screen path (the enforcement's frontend twin). */
-const REENROLL_PATH = '/account/reenroll';
-
 /** Only-when-signed-out (auth screens bounce authenticated users to the app). */
 function PublicOnly({ children }) {
   const { isAuthenticated } = useAuth();
@@ -61,12 +60,11 @@ function PublicOnly({ children }) {
  * means the user reaches the page and then gets 403'd by its data calls).
  */
 function RequireAuth({ children, gate }) {
-  const { isAuthenticated, mustReenroll } = useAuth();
+  const { isAuthenticated, mustReenroll, authFactsReady } = useAuth();
   // Called UNCONDITIONALLY (Rules of Hooks) — `useCan(undefined)` simply resolves to
   // `false` when no gate is set, so the ungated case is handled by short-circuiting on
   // `gate &&` below rather than skipping the hook call itself.
   const canGate = useCan(gate);
-  const allowed = !gate || canGate;
   const location = useLocation();
   // Remember where the user was so the next login returns them here. Persisted to
   // localStorage (via saveReturnPath) so it survives a full reload / browser restart —
@@ -78,32 +76,96 @@ function RequireAuth({ children, gate }) {
     if (!isAuthenticated) saveReturnPath(fullPath);
   }, [isAuthenticated, fullPath]);
 
-  if (!isAuthenticated) {
-    return <Navigate to="/login" replace state={{ from: fullPath }} />;
-  }
-  if (mustReenroll && location.pathname !== REENROLL_PATH) {
-    return <Navigate to={REENROLL_PATH} replace />;
+  // A gated route waits for the auth facts (a reload or deep link renders before they load),
+  // then decides; a failed load resolves to an empty projection and is denied (routeGate.js).
+  switch (
+    decideRoute({
+      isAuthenticated,
+      mustReenroll,
+      pathname: location.pathname,
+      gate,
+      factsReady: authFactsReady,
+      canGate,
+    })
+  ) {
+    case 'login':
+      return <Navigate to="/login" replace state={{ from: fullPath }} />;
+    case 'reenroll':
+      return <Navigate to={REENROLL_PATH} replace />;
+    case 'loading':
+      return (
+        <div
+          role="status"
+          aria-live="polite"
+          className="flex min-h-svh items-center justify-center"
+        >
+          <Loader2 className="size-6 animate-spin text-muted-foreground" aria-hidden="true" />
+          <span className="sr-only">Loading…</span>
+        </div>
+      );
+    case 'deny':
+      return <Navigate to="/dashboard" replace />;
+    default:
+      return children;
   }
-  if (gate && !allowed) {
-    return <Navigate to="/dashboard" replace />;
-  }
-  return children;
 }
 
 export default function App() {
   return (
     <Routes>
-      <Route path="/login" element={<PublicOnly><Login /></PublicOnly>} />
-      <Route path="/forgot-password" element={<PublicOnly><ForgotPassword /></PublicOnly>} />
-      <Route path="/reset-password" element={<PublicOnly><ResetPassword /></PublicOnly>} />
-      <Route path="/dashboard" element={<RequireAuth><Dashboard /></RequireAuth>} />
+      <Route
+        path="/login"
+        element={
+          <PublicOnly>
+            <Login />
+          </PublicOnly>
+        }
+      />
+      <Route
+        path="/forgot-password"
+        element={
+          <PublicOnly>
+            <ForgotPassword />
+          </PublicOnly>
+        }
+      />
+      <Route
+        path="/reset-password"
+        element={
+          <PublicOnly>
+            <ResetPassword />
+          </PublicOnly>
+        }
+      />
+      <Route
+        path="/dashboard"
+        element={
+          <RequireAuth>
+            <Dashboard />
+          </RequireAuth>
+        }
+      />
       {/* Forced re-enroll — a standalone full-screen flow (NOT an account tab). While
           the session is `mustReenroll`, RequireAuth pins every other protected route
           here; this path is the one RequireAuth lets through so the screen can load. */}
-      <Route path="/account/reenroll" element={<RequireAuth><ReenrollPage /></RequireAuth>} />
+      <Route
+        path="/account/reenroll"
+        element={
+          <RequireAuth>
+            <ReenrollPage />
+          </RequireAuth>
+        }
+      />
       {/* Account — a persistent layout with per-tab child routes (bookmarkable, back
           works). /account redirects to the Profile tab. */}
-      <Route path="/account" element={<RequireAuth><AccountLayout /></RequireAuth>}>
+      <Route
+        path="/account"
+        element={
+          <RequireAuth>
+            <AccountLayout />
+          </RequireAuth>
+        }
+      >
         <Route index element={<Navigate to="/account/profile" replace />} />
         <Route path="profile" element={<ProfilePage />} />
         <Route path="password" element={<ChangePasswordPage />} />

package/template/frontend/src/auth/AuthContext.jsx

@@ -20,12 +20,15 @@ import {
   createRecordPolicyService,
   createRecordShareService,
   createServiceAccountService,
+  createRefreshingHttp,
   isAuthenticated,
   principalOf,
 } from '@astram/frontend-core';
 import { createWebHttpClient } from '../platform/httpClient';
 import { createWebSessionStore } from '../platform/sessionStore';
 import { createWebShieldTransport } from '../platform/shieldTransport';
+import { saveReturnPath } from '../platform/returnPathStore';
+import { establishSession as runEstablishSession } from './sessionFlow';
 
 const AuthContext = createContext(null);
 
@@ -53,17 +56,38 @@ export function AuthProvider({ children }) {
   // token across login/refresh/logout without needing to be reconstructed (mirrors
   // `reenrollRef` above for the identical reason).
   const tokenRef = useRef(null);
+  const sessionIdRef = useRef(null);
+
+  // Session-lifecycle callbacks for the refreshing http client (built once, below). Late-bound
+  // through a ref because they need `persist`/`setProfile`/… which are declared further down.
+  const sessionEventsRef = useRef({ refreshed: () => {}, expired: () => {} });
 
   // Build the shared services from the injected web platform adapters (once). The
   // LOGIC is @astram/frontend-core; only the http client + storage are web-specific here.
   const services = useRef(null);
   if (!services.current) {
-    // The http client gets an app-wide interceptor: a 403 whose body is EXACTLY
+    // The raw http client gets an app-wide interceptor: a 403 whose body is EXACTLY
     // `{ error: 'reenrollment_required' }` (the enforced-re-enroll gate, §4) flips the
     // app into the forced re-enroll flow. Matched narrowly so a future permission-deny
     // 403 never triggers it.
-    const http = createWebHttpClient({ onReenrollRequired: () => markReenroll() });
+    const rawHttp = createWebHttpClient({ onReenrollRequired: () => markReenroll() });
     const store = createWebSessionStore();
+    // Token refresh (#12): every service talks through `http`, which turns a 401 on a
+    // request that carried a bearer token into ONE shared refresh (single-flight, and a
+    // cross-tab `navigator.locks` section that re-reads localStorage first so two tabs
+    // never spend the same refresh token), then retries the request once. A rejected
+    // refresh clears the session (→ login); a 503 keeps it (the server did not spend the
+    // token; the next request retries). The refresh call itself uses the RAW client, and
+    // forwards the wrapper's abort signal so a hung refresh times out (an outage, not a
+    // logout) instead of holding the cross-tab lock.
+    const refresher = createAuthService(rawHttp);
+    const http = createRefreshingHttp({
+      http: rawHttp,
+      store,
+      refresh: (refreshToken, opts) => refresher.refresh(refreshToken, opts),
+      onRefreshed: (next) => sessionEventsRef.current.refreshed(next),
+      onSessionExpired: () => sessionEventsRef.current.expired(),
+    });
     services.current = {
       auth: createAuthService(http),
       identity: createIdentityService(http),
@@ -83,17 +107,32 @@ export function AuthProvider({ children }) {
       // NEVER the security boundary: the server's decide() on every @Classified route
       // is the real enforcement (see shieldTransport.js's header doc). `getToken` reads
       // `tokenRef.current` (not a closed-over value) so the SAME client instance always
-      // sees the CURRENT token across a refresh, without being rebuilt.
+      // sees the CURRENT token across a refresh, without being rebuilt. It uses the
+      // refreshing `http` too, so an expired token is refreshed before a 401 reaches it.
       shield: createShieldClient({
         transport: createWebShieldTransport({ http, getToken: () => tokenRef.current }),
         clock: systemClock,
         scheduler: { sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)) },
       }),
       store,
+      // The auth service over the RAW client: logout goes through it so a 401 there can never
+      // trigger a refresh / session-expired path (which would save a stale return path).
+      rawAuth: refresher,
     };
   }
-  const { auth, identity, audit, crossTenant, recordPolicy, recordShare, serviceAccounts, account, shield, store } =
-    services.current;
+  const {
+    auth,
+    identity,
+    audit,
+    crossTenant,
+    recordPolicy,
+    recordShare,
+    serviceAccounts,
+    account,
+    shield,
+    store,
+    rawAuth,
+  } = services.current;
 
   const [state, setState] = useState(() => store.load()); // SessionState | null
   // The signed-in user's DISPLAY profile (name/email/company/roles) from GET /auth/me.
@@ -109,12 +148,41 @@ export function AuthProvider({ children }) {
   // Keep `tokenRef` in lockstep with the persisted session's access token so the shield
   // transport (built once, above) always reads the CURRENT token.
   tokenRef.current = state?.tokens?.accessToken ?? null;
+  // The current session id, read by the cross-tab listener below to tell a token rotation
+  // (same session) from a different sign-in.
+  useEffect(() => {
+    sessionIdRef.current = state?.session?.sessionId ?? null;
+  });
 
   const persist = (value) => {
     setState(value);
     store.save(value);
   };
 
+  // Everything derived from a session that must not outlive it.
+  const resetSessionViews = () => {
+    setProfile(null);
+    setAuthFacts(null); // fail-closed: no session -> no cached facts to (mis)trust
+    clearReenroll();
+  };
+
+  // Wire the refreshing http client's lifecycle callbacks (the client is built once above;
+  // these run only after a network round-trip, so binding them in an effect is early enough).
+  useEffect(() => {
+    sessionEventsRef.current = {
+      // Tokens rotated (here or in another tab): the wrapper already saved them.
+      refreshed: (next) => setState(next),
+      // Refresh rejected, or the session was signed out in another tab: drop it and
+      // remember where the user was. RequireAuth then redirects to /login, which returns
+      // here after the next sign-in.
+      expired: () => {
+        saveReturnPath(window.location.pathname + window.location.search);
+        persist(null);
+        resetSessionViews();
+      },
+    };
+  });
+
   // Fetch the display profile for the current access token. Best-effort: on any
   // non-ok (401/404/501/unreachable) we simply clear it and the UI falls back to the
   // interim identity hint — the profile is enrichment, never a gate.
@@ -153,23 +221,36 @@ export function AuthProvider({ children }) {
       setAuthFacts(null);
       return;
     }
-    const projection = await shield.getAuthFacts(principalId);
-    setAuthFacts(projection);
+    let projection;
+    try {
+      projection = await shield.getAuthFacts(principalId);
+    } catch {
+      projection = null; // getAuthFacts is documented never to throw; belt and braces
+    }
+    // Fail closed: an unusable result becomes an EMPTY projection (resolved, nothing allowed),
+    // so a gated route stops waiting and denies instead of hanging or allowing.
+    setAuthFacts(projection ?? { principalId: '', facts: [], projectedAt: Date.now() });
   };
 
   // The shared post-authentication work: persist the session + fetch the display
   // profile + the auth-facts projection. Both a plain login and an MFA-completed login
   // end here, so the session is established identically regardless of which path
   // authenticated the user.
-  const establishSession = async (session, tokens, identityHint) => {
-    // Keep the identity hint the user signed in with as an interim label; the real
-    // display profile is fetched from /auth/me right after (names, never UUIDs).
-    persist({ session, tokens, identityHint });
-    await Promise.all([
-      loadProfile(tokens?.accessToken),
-      refreshAuthFacts(session?.principalId ?? null),
-    ]);
-  };
+  // Keeps the identity hint the user signed in with as an interim label; the real display
+  // profile is fetched from /auth/me right after (names, never UUIDs). The token ref is
+  // published before the fetches (see sessionFlow.js) so the first auth-facts call is authed.
+  const establishSession = (session, tokens, identityHint) =>
+    runEstablishSession(
+      { session, tokens, identityHint },
+      {
+        persist,
+        setCurrentToken: (token) => {
+          tokenRef.current = token;
+        },
+        loadProfile,
+        refreshAuthFacts,
+      },
+    );
 
   const login = async (identityHint, password) => {
     const r = await auth.login(identityHint, password);
@@ -208,7 +289,7 @@ export function AuthProvider({ children }) {
     setProfile(null);
     setAuthFacts(null); // fail-closed: no session -> no cached facts to (mis)trust
     clearReenroll(); // a fresh sign-in starts unrestricted
-    await auth.logout(sessionId);
+    await rawAuth.logout(sessionId); // raw client: no refresh/expiry path on a logout
   };
 
   // On mount (e.g. a page refresh that rehydrated a persisted session), fetch the
@@ -221,6 +302,28 @@ export function AuthProvider({ children }) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // Cross-tab: another tab rotated the tokens, signed out, or signed in as someone else.
+  // localStorage fires `storage` only in the OTHER tabs; follow it so this tab never keeps
+  // using a token that is gone, and never shows the previous user's profile/facts.
+  useEffect(
+    () =>
+      store.subscribe((next) => {
+        const prevSessionId = sessionIdRef.current;
+        setState(next);
+        if (!next) {
+          resetSessionViews();
+          return;
+        }
+        if (next.session?.sessionId !== prevSessionId) {
+          resetSessionViews();
+          void loadProfile(next.tokens?.accessToken);
+          void refreshAuthFacts(principalOf(next));
+        }
+      }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
   // Phase E slice 2 (ADR-0011 frontend twin) — POKE `getAuthFacts` periodically + on
   // window focus so the SDK's own version-staleness check (client.ts's
   // `isProjectionFresh`, driven by shieldTransport's `currentVersion()`) actually RUNS.
@@ -313,6 +416,11 @@ export function AuthProvider({ children }) {
       // resolves. Most call sites should prefer `useCan(key)` below; exposed for
       // completeness / debugging.
       authFacts,
+      // True once the projection has resolved for this session (a failed load resolves to an
+      // empty projection). A session without a principal can never load facts: treat it as
+      // resolved-with-nothing so gated routes deny instead of waiting forever. RequireAuth
+      // waits on this before deciding a gated route (see routeGate.js).
+      authFactsReady: authFacts !== null || (isAuthenticated(state) && !principalOf(state)),
       // `can(permissionKey)` — is the given permission key present as an ALLOWED fact in
       // the current projection? FAIL-CLOSED: an absent fact, OR no projection fetched
       // yet (`authFacts === null`), both read as `false` (can't) — never optimistically
@@ -320,12 +428,24 @@ export function AuthProvider({ children }) {
       // NEVER the security boundary — the server's decide() on every @Classified route
       // is the real enforcement (see shieldTransport.js's header doc).
       can: (permissionKey) =>
-        Boolean(
-          authFacts?.facts?.some((f) => f.action === permissionKey && f.allowed === true),
-        ),
+        Boolean(authFacts?.facts?.some((f) => f.action === permissionKey && f.allowed === true)),
     }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [state, auth, identity, audit, crossTenant, recordPolicy, recordShare, serviceAccounts, account, shield, profile, mustReenroll, authFacts],
+    [
+      state,
+      auth,
+      identity,
+      audit,
+      crossTenant,
+      recordPolicy,
+      recordShare,
+      serviceAccounts,
+      account,
+      shield,
+      profile,
+      mustReenroll,
+      authFacts,
+    ],
   );
 
   return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;

package/template/frontend/src/auth/routeGate.js

@@ -0,0 +1,31 @@
+/**
+ * The protected-route decision RequireAuth renders, kept free of React so `node --test` can
+ * check it. UX only: the server's decide() on every @Classified route is the enforcement.
+ */
+
+/** The single forced-re-enroll screen path (the enforcement's frontend twin). */
+export const REENROLL_PATH = '/account/reenroll';
+
+/**
+ * `factsReady` is true once the auth-facts projection has resolved for this session. A failed
+ * load resolves to an EMPTY projection (the SDK is fail-closed), so it is "ready" with no
+ * facts and a gated route is denied. `canGate` is never consulted before that.
+ *
+ * @param {{ isAuthenticated: boolean, mustReenroll: boolean, pathname: string,
+ *           gate?: string, factsReady: boolean, canGate: boolean }} input
+ * @returns {'login' | 'reenroll' | 'loading' | 'deny' | 'render'}
+ */
+export function decideRoute({
+  isAuthenticated,
+  mustReenroll,
+  pathname,
+  gate,
+  factsReady,
+  canGate,
+}) {
+  if (!isAuthenticated) return 'login';
+  if (mustReenroll && pathname !== REENROLL_PATH) return 'reenroll';
+  if (gate && !factsReady) return 'loading';
+  if (gate && !canGate) return 'deny';
+  return 'render';
+}

package/template/frontend/src/auth/routeGate.test.mjs

@@ -0,0 +1,59 @@
+// routeGate.test.mjs — E2E finding: a full reload or deep link to a gated page bounced to
+// /dashboard because RequireAuth decided while the auth facts were still loading. It must
+// wait for them, then decide, and still fail closed.
+//
+//   node --test src/auth/routeGate.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { decideRoute, REENROLL_PATH } from './routeGate.js';
+
+const base = { isAuthenticated: true, mustReenroll: false, pathname: '/users', canGate: false };
+
+describe('decideRoute', () => {
+  test('gated page, facts not loaded yet (reload / deep link) → loading, not a redirect', () => {
+    assert.equal(
+      decideRoute({ ...base, gate: 'identity:user:read', factsReady: false }),
+      'loading',
+    );
+  });
+
+  test('gated page, facts loaded and the key allowed → render', () => {
+    assert.equal(
+      decideRoute({ ...base, gate: 'identity:user:read', factsReady: true, canGate: true }),
+      'render',
+    );
+  });
+
+  test('fail closed: facts loaded without the key (incl. a failed load = empty projection) → deny', () => {
+    assert.equal(
+      decideRoute({ ...base, gate: 'identity:user:read', factsReady: true, canGate: false }),
+      'deny',
+    );
+  });
+
+  test('fail closed: canGate is never trusted before the facts are ready', () => {
+    assert.equal(
+      decideRoute({ ...base, gate: 'identity:user:read', factsReady: false, canGate: true }),
+      'loading',
+    );
+  });
+
+  test('ungated page renders without waiting for facts', () => {
+    assert.equal(decideRoute({ ...base, factsReady: false }), 'render');
+  });
+
+  test('signed out → login, before any facts or gate check', () => {
+    assert.equal(
+      decideRoute({ ...base, isAuthenticated: false, gate: 'x:y:z', factsReady: false }),
+      'login',
+    );
+  });
+
+  test('mustReenroll pins every other route to the re-enroll screen', () => {
+    assert.equal(decideRoute({ ...base, mustReenroll: true, factsReady: true }), 'reenroll');
+    assert.equal(
+      decideRoute({ ...base, mustReenroll: true, pathname: REENROLL_PATH, factsReady: true }),
+      'render',
+    );
+  });
+});

package/template/frontend/src/auth/sessionFlow.js

@@ -0,0 +1,27 @@
+/**
+ * Session-flow steps AuthContext runs, kept free of React so `node --test` can check them.
+ */
+
+/**
+ * Establish a session after login / MFA: persist it, then fetch the display profile and the
+ * auth-facts projection.
+ *
+ * @param {{ session: object, tokens: { accessToken?: string }, identityHint?: string }} input
+ * @param {{
+ *   persist: (state: object) => void,
+ *   setCurrentToken: (token: string | null) => void,
+ *   loadProfile: (accessToken: string | undefined) => Promise<void>,
+ *   refreshAuthFacts: (principalId: string | null) => Promise<void>,
+ * }} deps
+ */
+export async function establishSession({ session, tokens, identityHint }, deps) {
+  deps.persist({ session, tokens, identityHint });
+  // `persist` is a React setState: the token ref the shield transport reads is only synced on
+  // the NEXT render. Publish the new token now, or the first auth-facts fetch goes out with no
+  // bearer (401 → empty projection → admin nav hidden until the next poll).
+  deps.setCurrentToken(tokens?.accessToken ?? null);
+  await Promise.all([
+    deps.loadProfile(tokens?.accessToken),
+    deps.refreshAuthFacts(session?.principalId ?? null),
+  ]);
+}

package/template/frontend/src/auth/sessionFlow.test.mjs

@@ -0,0 +1,63 @@
+// sessionFlow.test.mjs — E2E finding: after a fresh login the first GET /identity/auth-facts
+// went out with NO bearer (the shield transport reads the token from a ref that React had
+// not updated yet), so the admin nav stayed hidden until the next poll.
+//
+//   node --test src/auth/sessionFlow.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { establishSession } from './sessionFlow.js';
+import { createWebShieldTransport } from '../platform/shieldTransport.js';
+
+const fake = (label) => `fake-${label}`;
+const ACCESS = fake('access');
+
+describe('establishSession', () => {
+  test('the auth-facts fetch carries the NEW access token (no 401 on first login)', async () => {
+    // AuthContext wiring: the transport reads `tokenRef.current`, which React only
+    // updates on the next render — after establishSession has already fetched.
+    const tokenRef = { current: null };
+    const seen = [];
+    const http = {
+      get: async (path, opts) => {
+        seen.push({ path, bearer: opts?.bearerToken ?? null });
+        return opts?.bearerToken === ACCESS
+          ? { ok: true, status: 200, data: { principalId: 'p1', facts: [], projectedAt: 1 } }
+          : { ok: false, status: 401, data: null };
+      },
+    };
+    const transport = createWebShieldTransport({ http, getToken: () => tokenRef.current });
+    let projection = null;
+
+    await establishSession(
+      { session: { principalId: 'p1' }, tokens: { accessToken: ACCESS }, identityHint: 'a' },
+      {
+        persist: () => {}, // setState: the ref is NOT updated until a later render
+        setCurrentToken: (t) => {
+          tokenRef.current = t;
+        },
+        loadProfile: async () => {},
+        refreshAuthFacts: async () => {
+          projection = await transport.fetchProjection('p1');
+        },
+      },
+    );
+
+    assert.deepEqual(seen, [{ path: '/identity/auth-facts', bearer: ACCESS }]);
+    assert.deepEqual(projection, { principalId: 'p1', facts: [], projectedAt: 1 });
+  });
+
+  test('persists before fetching, and passes the access token to the profile load', async () => {
+    const order = [];
+    await establishSession(
+      { session: { principalId: 'p1' }, tokens: { accessToken: ACCESS } },
+      {
+        persist: () => order.push('persist'),
+        setCurrentToken: () => order.push('token'),
+        loadProfile: async (t) => order.push(`profile:${t === ACCESS}`),
+        refreshAuthFacts: async (p) => order.push(`facts:${p}`),
+      },
+    );
+    assert.deepEqual(order.slice(0, 2).sort(), ['persist', 'token']);
+    assert.deepEqual(order.slice(2).sort(), ['facts:p1', 'profile:true']);
+  });
+});

package/template/frontend/src/components/EntityList.jsx

@@ -66,13 +66,7 @@ import {
 } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
-import {
-  Card,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from '@/components/ui/card';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import {
   Select,

package/template/frontend/src/components/PageHeader.jsx

@@ -26,7 +26,10 @@ export default function PageHeader({ title, section, icon: Icon = Shield, action
         {title}
       </h1>
       {/* Breadcrumb (relocated from the app header): Section › Page — no leading icon. */}
-      <nav aria-label="Breadcrumb" className="mt-1 flex items-center gap-2 text-sm text-muted-foreground">
+      <nav
+        aria-label="Breadcrumb"
+        className="mt-1 flex items-center gap-2 text-sm text-muted-foreground"
+      >
         {section ? (
           <>
             <span>{section}</span>
@@ -46,9 +49,7 @@ export default function PageHeader({ title, section, icon: Icon = Shield, action
   return (
     <div className="mb-4 flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
       {titleAndCrumb}
-      {actions && (
-        <div className="flex shrink-0 items-center gap-2 max-sm:w-full">{actions}</div>
-      )}
+      {actions && <div className="flex shrink-0 items-center gap-2 max-sm:w-full">{actions}</div>}
     </div>
   );
 }