@djangocfg/api 2.1.449 → 2.1.450

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.449",
+  "version": "2.1.450",
   "description": "Auto-generated TypeScript API client with React hooks, SWR integration, and Zod validation for Django REST Framework backends",
   "keywords": [
     "django",
@@ -86,7 +86,7 @@
   "devDependencies": {
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
-    "@djangocfg/typescript-config": "^2.1.449",
+    "@djangocfg/typescript-config": "^2.1.450",
     "next": "^16.2.2",
     "react": "^19.2.4",
     "tsup": "^8.5.0",

package/src/auth/__tests__/jwt.test.ts

@@ -0,0 +1,119 @@
+/**
+ * JWT expiry-helper tests (auth/utils/jwt.ts).
+ *
+ * These functions decide whether the client should trust a persisted token or
+ * treat the session as dead. They must FAIL CLOSED: anything undecodable counts
+ * as expired, so garbage in localStorage sends the user to the login form
+ * rather than looping on 401s. (This is the automated version of the user's
+ * manual "clear localStorage and the form appeared".)
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { getTokenExpiry, isTokenExpired, isTokenExpiringSoon } from '../utils/jwt';
+
+const NOW = 1_800_000_000_000; // fixed "now" in ms (injected, not Date.now())
+
+/** Base64url without padding — mirrors real JWT segment encoding. */
+function b64url(obj: unknown): string {
+  const json = JSON.stringify(obj);
+  const b64 = Buffer.from(json, 'utf8').toString('base64');
+  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** Build a syntactically valid 3-segment JWT with the given payload. */
+function jwt(payload: Record<string, unknown>): string {
+  const header = b64url({ alg: 'HS256', typ: 'JWT' });
+  const body = b64url(payload);
+  return `${header}.${body}.signature`;
+}
+
+/** exp claim is in SECONDS in a real JWT. */
+const expSeconds = (ms: number) => Math.floor(ms / 1000);
+
+describe('getTokenExpiry', () => {
+  it('extracts exp (converted to ms) from a well-formed token', () => {
+    const token = jwt({ exp: expSeconds(NOW) });
+    expect(getTokenExpiry(token)).toBe(expSeconds(NOW) * 1000);
+  });
+
+  it('returns null for null / undefined / empty', () => {
+    expect(getTokenExpiry(null)).toBeNull();
+    expect(getTokenExpiry(undefined)).toBeNull();
+    expect(getTokenExpiry('')).toBeNull();
+  });
+
+  it('returns null for a non-JWT string (wrong segment count)', () => {
+    expect(getTokenExpiry('not-a-jwt')).toBeNull();
+    expect(getTokenExpiry('only.two')).toBeNull();
+    expect(getTokenExpiry('a.b.c.d')).toBeNull();
+  });
+
+  it('returns null when the payload is not valid base64/JSON', () => {
+    expect(getTokenExpiry('aaa.!!!!.bbb')).toBeNull();
+  });
+
+  it('returns null when exp is missing or non-numeric', () => {
+    expect(getTokenExpiry(jwt({ sub: 'user' }))).toBeNull();
+    expect(getTokenExpiry(jwt({ exp: 'soon' }))).toBeNull();
+    expect(getTokenExpiry(jwt({ exp: null }))).toBeNull();
+  });
+
+  it('handles a non-object payload (e.g. a JSON number) as no-exp', () => {
+    const header = b64url({ alg: 'HS256' });
+    const body = b64url(42 as unknown as Record<string, unknown>);
+    expect(getTokenExpiry(`${header}.${body}.sig`)).toBeNull();
+  });
+});
+
+describe('isTokenExpired (fail-closed)', () => {
+  it('false for a token that expires in the future', () => {
+    const token = jwt({ exp: expSeconds(NOW + 60_000) });
+    expect(isTokenExpired(token, 0, NOW)).toBe(false);
+  });
+
+  it('true for a token already past exp', () => {
+    const token = jwt({ exp: expSeconds(NOW - 1) });
+    expect(isTokenExpired(token, 0, NOW)).toBe(true);
+  });
+
+  it('true exactly at exp (boundary is inclusive → expired)', () => {
+    const token = jwt({ exp: expSeconds(NOW) });
+    expect(isTokenExpired(token, 0, NOW)).toBe(true);
+  });
+
+  it('skew treats a soon-to-expire token as already expired', () => {
+    const token = jwt({ exp: expSeconds(NOW + 30_000) }); // expires in 30s
+    expect(isTokenExpired(token, 60_000, NOW)).toBe(true); // 60s skew
+    expect(isTokenExpired(token, 10_000, NOW)).toBe(false); // 10s skew
+  });
+
+  it('true (fail-closed) for null / garbage / no-exp tokens', () => {
+    expect(isTokenExpired(null, 0, NOW)).toBe(true);
+    expect(isTokenExpired(undefined, 0, NOW)).toBe(true);
+    expect(isTokenExpired('garbage', 0, NOW)).toBe(true);
+    expect(isTokenExpired(jwt({ sub: 'x' }), 0, NOW)).toBe(true);
+  });
+});
+
+describe('isTokenExpiringSoon', () => {
+  it('true when expiry is within the threshold', () => {
+    const token = jwt({ exp: expSeconds(NOW + 5 * 60_000) }); // 5 min
+    expect(isTokenExpiringSoon(token, 10 * 60_000, NOW)).toBe(true);
+  });
+
+  it('false when expiry is beyond the threshold', () => {
+    const token = jwt({ exp: expSeconds(NOW + 20 * 60_000) }); // 20 min
+    expect(isTokenExpiringSoon(token, 10 * 60_000, NOW)).toBe(false);
+  });
+
+  it('false (not "soon") for undecodable tokens — the expired path owns those', () => {
+    expect(isTokenExpiringSoon(null, 10 * 60_000, NOW)).toBe(false);
+    expect(isTokenExpiringSoon('garbage', 10 * 60_000, NOW)).toBe(false);
+  });
+
+  it('true for an already-expired but decodable token', () => {
+    const token = jwt({ exp: expSeconds(NOW - 1000) });
+    expect(isTokenExpiringSoon(token, 10 * 60_000, NOW)).toBe(true);
+  });
+});

package/src/auth/__tests__/onUnauthorized.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Unrecoverable-401 contract test.
+ *
+ * Regression guard for the "stuck on Authenticating…" bug: when the refresh
+ * token is dead (expired, or blacklisted after rotation), the refresh handler
+ * fails and the session is UNRECOVERABLE. The client must then:
+ *   - report failure from the proactive path (`refreshNow()` → null), and
+ *   - fire `auth.onUnauthorized(cb)` from the reactive (interceptor) path,
+ * so the app can clear tokens and show the login form. If neither fires, stale
+ * tokens sit in storage and the guard hangs forever.
+ *
+ * The store reads `window.localStorage` and captures `isBrowser` at import
+ * time, so we install a minimal localStorage on globalThis BEFORE importing it.
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+function installBrowserStorage() {
+  const map = new Map<string, string>();
+  const storage = {
+    getItem: (k: string) => (map.has(k) ? map.get(k)! : null),
+    setItem: (k: string, v: string) => void map.set(k, v),
+    removeItem: (k: string) => void map.delete(k),
+    clear: () => map.clear(),
+  };
+  vi.stubGlobal('window', { localStorage: storage, location: { protocol: 'http:' } });
+  vi.stubGlobal('localStorage', storage);
+  return map;
+}
+
+describe('unrecoverable 401 handling', () => {
+  beforeEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it('refreshNow() returns null when the refresh handler fails (blacklisted token)', async () => {
+    installBrowserStorage();
+    const { auth } = await import('../../_api/generated/helpers/auth');
+
+    auth.setToken('access-stale');
+    auth.setRefreshToken('R-blacklisted');
+
+    // Model a server that rejects the (blacklisted) refresh token.
+    auth.setRefreshHandler(async () => {
+      const err = new Error('Token is blacklisted') as Error & { code: string };
+      err.code = 'token_not_valid';
+      throw err;
+    });
+
+    const store = auth as unknown as { refreshNow?: () => Promise<string | null> };
+    if (typeof store.refreshNow !== 'function') return; // pre-regen: skip gracefully
+
+    const result = await store.refreshNow();
+    expect(result).toBeNull(); // proactive path reports the dead session
+  });
+
+  it('refreshNow() returns null when there is no refresh token at all', async () => {
+    installBrowserStorage();
+    const { auth } = await import('../../_api/generated/helpers/auth');
+
+    auth.setToken('access-orphan');
+    // no refresh token set
+    auth.setRefreshHandler(async () => ({ access: 'never', refresh: 'never' }));
+
+    const store = auth as unknown as { refreshNow?: () => Promise<string | null> };
+    if (typeof store.refreshNow !== 'function') return;
+
+    expect(await store.refreshNow()).toBeNull();
+  });
+
+  it('onUnauthorized callback can be registered and cleared (wiring the login-form escape hatch)', async () => {
+    installBrowserStorage();
+    const { auth } = await import('../../_api/generated/helpers/auth');
+
+    // The AuthContext relies on this being a no-throw registration surface.
+    const cb = vi.fn();
+    expect(() => auth.onUnauthorized(cb)).not.toThrow();
+    expect(() => auth.onUnauthorized(null)).not.toThrow();
+  });
+});
+
+/**
+ * Reactive path: the response interceptor installed by installAuthOnClient must
+ * call onUnauthorized(response) when a 401 cannot be recovered, and must NOT
+ * call it when the refresh handler rescues the request. We install the auth
+ * machinery onto a FAKE client that just captures the response interceptor, then
+ * invoke it with a synthetic 401 — exercising the real recovery branch logic.
+ */
+describe('response interceptor → onUnauthorized (reactive 401 path)', () => {
+  beforeEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  async function installOnFakeClient() {
+    installBrowserStorage();
+    const { auth, installAuthOnClient } = await import('../../_api/generated/helpers/auth');
+
+    let responseInterceptor:
+      | ((res: Response, req: Request) => Promise<Response> | Response)
+      | null = null;
+
+    const fakeClient = {
+      setConfig: () => {},
+      interceptors: {
+        request: { use: () => {} },
+        response: {
+          use: (fn: (res: Response, req: Request) => Promise<Response> | Response) => {
+            responseInterceptor = fn;
+          },
+        },
+        error: { use: () => {} },
+      },
+    };
+
+    installAuthOnClient(fakeClient as never);
+    return { auth, invoke: () => responseInterceptor! };
+  }
+
+  function res401(): Response {
+    return new Response(JSON.stringify({ detail: 'Token is blacklisted', code: 'token_not_valid' }), {
+      status: 401,
+      headers: { 'content-type': 'application/json' },
+    });
+  }
+  function req(url = 'http://localhost:8000/cfg/accounts/profile/'): Request {
+    return new Request(url, { method: 'GET' });
+  }
+
+  it('fires onUnauthorized when there is NO refresh handler / token', async () => {
+    const { auth, invoke } = await installOnFakeClient();
+    const onUnauth = vi.fn();
+    auth.onUnauthorized(onUnauth);
+    // No refresh token, no handler → tryRefresh returns null → onUnauthorized fires.
+
+    const out = await invoke()(res401(), req());
+    expect(onUnauth).toHaveBeenCalledTimes(1);
+    expect(out.status).toBe(401); // original 401 surfaced
+  });
+
+  it('fires onUnauthorized when the refresh handler FAILS (blacklisted token)', async () => {
+    const { auth, invoke } = await installOnFakeClient();
+    auth.setToken('access-stale');
+    auth.setRefreshToken('R-dead');
+    auth.setRefreshHandler(async () => {
+      throw new Error('Token is blacklisted');
+    });
+    const onUnauth = vi.fn();
+    auth.onUnauthorized(onUnauth);
+
+    const out = await invoke()(res401(), req());
+    expect(onUnauth).toHaveBeenCalledTimes(1);
+    expect(out.status).toBe(401);
+  });
+
+  it('does NOT fire onUnauthorized on a non-401 response', async () => {
+    const { auth, invoke } = await installOnFakeClient();
+    const onUnauth = vi.fn();
+    auth.onUnauthorized(onUnauth);
+
+    const ok = new Response('{}', { status: 200 });
+    const out = await invoke()(ok, req());
+    expect(onUnauth).not.toHaveBeenCalled();
+    expect(out.status).toBe(200);
+  });
+
+  it('does NOT fire onUnauthorized when refresh SUCCEEDS and retry is attempted', async () => {
+    const { auth, invoke } = await installOnFakeClient();
+    auth.setToken('access-stale');
+    auth.setRefreshToken('R-good');
+    auth.setRefreshHandler(async () => ({ access: 'access-fresh', refresh: 'R-rotated' }));
+    const onUnauth = vi.fn();
+    auth.onUnauthorized(onUnauth);
+
+    // The interceptor retries via global fetch after a successful refresh.
+    // Stub fetch to return 200 for the retry so onUnauthorized is not reached.
+    const fetchMock = vi.fn(async () => new Response('{}', { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const out = await invoke()(res401(), req());
+    expect(fetchMock).toHaveBeenCalledTimes(1); // retry happened
+    expect(onUnauth).not.toHaveBeenCalled(); // recovered → no logout
+    expect(out.status).toBe(200);
+    expect(auth.getToken()).toBe('access-fresh'); // rotated tokens persisted
+    expect(auth.getRefreshToken()).toBe('R-rotated');
+  });
+
+  it('fires onUnauthorized when the retry STILL returns 401', async () => {
+    const { auth, invoke } = await installOnFakeClient();
+    auth.setToken('access-stale');
+    auth.setRefreshToken('R-good');
+    auth.setRefreshHandler(async () => ({ access: 'access-fresh', refresh: 'R-rotated' }));
+    const onUnauth = vi.fn();
+    auth.onUnauthorized(onUnauth);
+
+    // Refresh succeeds but the retried request is still rejected (401).
+    const fetchMock = vi.fn(async () => new Response('{}', { status: 401 }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const out = await invoke()(res401(), req());
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(onUnauth).toHaveBeenCalledTimes(1); // dead even after refresh+retry
+    expect(out.status).toBe(401);
+  });
+});

package/src/auth/__tests__/sessionBootstrap.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Bootstrap dead-session detection (isSessionDeadOnBootstrap in AuthContext).
+ *
+ * This is the decision that, at app start, either shows the login form or lets
+ * the app try to use / refresh the persisted tokens. It reproduces the exact
+ * scenario the user hit: stale tokens in localStorage that can never recover,
+ * where the fix used to be "clear localStorage by hand". The session is DEAD
+ * only when the access token is unusable AND the refresh token can't save it.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { isSessionDeadOnBootstrap } from '../context/AuthContext';
+
+const NOW = 1_800_000_000_000;
+const expSeconds = (ms: number) => Math.floor(ms / 1000);
+
+function b64url(obj: unknown): string {
+  return Buffer.from(JSON.stringify(obj), 'utf8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+function jwt(payload: Record<string, unknown>): string {
+  return `${b64url({ alg: 'HS256' })}.${b64url(payload)}.sig`;
+}
+const live = () => jwt({ exp: expSeconds(NOW + 3_600_000) }); // +1h
+const dead = () => jwt({ exp: expSeconds(NOW - 3_600_000) }); // -1h
+
+describe('isSessionDeadOnBootstrap', () => {
+  it('ALIVE: live access + live refresh', () => {
+    expect(isSessionDeadOnBootstrap(live(), live(), NOW)).toBe(false);
+  });
+
+  it('ALIVE: live access even if refresh is dead (access still works)', () => {
+    expect(isSessionDeadOnBootstrap(live(), dead(), NOW)).toBe(false);
+  });
+
+  it('ALIVE: live access even with no refresh token', () => {
+    expect(isSessionDeadOnBootstrap(live(), null, NOW)).toBe(false);
+  });
+
+  it('ALIVE: dead access but LIVE refresh (refresh can rescue it)', () => {
+    expect(isSessionDeadOnBootstrap(dead(), live(), NOW)).toBe(false);
+  });
+
+  it('DEAD: dead access + dead refresh (the classic stuck state)', () => {
+    expect(isSessionDeadOnBootstrap(dead(), dead(), NOW)).toBe(true);
+  });
+
+  it('DEAD: dead access + no refresh token', () => {
+    expect(isSessionDeadOnBootstrap(dead(), null, NOW)).toBe(true);
+  });
+
+  it('DEAD: both tokens null (empty storage that still triggered init)', () => {
+    expect(isSessionDeadOnBootstrap(null, null, NOW)).toBe(true);
+  });
+
+  it('DEAD: garbage access + garbage refresh (corrupt storage — user cleared this by hand)', () => {
+    expect(isSessionDeadOnBootstrap('garbage', 'also-garbage', NOW)).toBe(true);
+  });
+
+  it('DEAD: garbage access + no refresh', () => {
+    expect(isSessionDeadOnBootstrap('xxxxx', null, NOW)).toBe(true);
+  });
+
+  it('ALIVE: garbage access but a LIVE refresh token still lets us recover', () => {
+    expect(isSessionDeadOnBootstrap('garbage', live(), NOW)).toBe(false);
+  });
+
+  it('DEAD: access expired exactly at now + refresh expired (inclusive boundary)', () => {
+    const atNow = jwt({ exp: expSeconds(NOW) });
+    expect(isSessionDeadOnBootstrap(atNow, atNow, NOW)).toBe(true);
+  });
+});

package/src/auth/context/AuthContext.tsx

@@ -19,6 +19,7 @@ import { useTokenRefresh } from '../hooks/useTokenRefresh';
 import { ensureRefreshHandler } from '../refreshHandler';
 import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
 import { authLogger } from '../utils/logger';
+import { isTokenExpired } from '../utils/jwt';
 import { AccountsProvider, useAccountsContext } from './AccountsContext';
 
 import type { AuthConfig, AuthContextType, AuthProviderProps, UserProfile } from './types';
@@ -41,6 +42,33 @@ const hasValidTokens = (): boolean => {
   return apiAccounts.isAuthenticated();
 };
 
+/**
+ * Decide, at bootstrap, whether the persisted tokens are a DEAD session that
+ * can never be recovered — so we should clear storage and show the login form
+ * instead of firing doomed API calls.
+ *
+ * Pure + injectable (tokens passed in) so it can be unit-tested without a store.
+ *
+ * A session is dead when the access token is missing/expired/malformed AND the
+ * refresh token cannot save it (missing or itself expired/malformed). If either
+ * the access token is still live, OR a usable refresh token exists, the session
+ * is NOT dead — normal init proceeds (and refresh will run if needed).
+ *
+ * This is exactly the state the user used to fix by hand ("cleared localStorage
+ * and then the form appeared"): stale/blacklisted-companion tokens left in
+ * storage with no path forward.
+ */
+export const isSessionDeadOnBootstrap = (
+  accessToken: string | null,
+  refreshToken: string | null,
+  now = Date.now(),
+): boolean => {
+  const accessDead = isTokenExpired(accessToken, 0, now);
+  if (!accessDead) return false; // access still usable → alive
+  const refreshDead = isTokenExpired(refreshToken, 0, now);
+  return refreshDead; // access dead + refresh dead/absent → unrecoverable
+};
+
 // Internal provider that uses AccountsContext
 const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config }) => {
   const accounts = useAccountsContext();
@@ -69,6 +97,22 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
   });
 
   const [initialized, setInitialized] = useState(false);
+
+  // Reactivity tick for `isAuthenticated`. Token state lives in the auth store
+  // (localStorage), NOT React state — so `apiAccounts.isAuthenticated()` is read
+  // once when the context value is memoised and would go stale after tokens are
+  // cleared (e.g. a blacklisted-refresh 401). Bumping this on every auth-state
+  // transition forces the memo to recompute, so the guard reliably flips to
+  // "unauthenticated" and the login form is shown instead of an endless
+  // "Authenticating…" spinner.
+  const [authTick, setAuthTick] = useState(0);
+  const bumpAuthTick = useCallback(() => setAuthTick((t) => t + 1), []);
+
+  // Latches once a dead session has been handled, so the redirect-to-login only
+  // fires once even if both the interceptor (auth.onUnauthorized) and the
+  // proactive-refresh error path trip for the same expired session.
+  const onUnauthorizedRef = useRef(false);
+
   const router = useCfgRouter();
   const pathname = usePathname();
   const queryParams = useQueryParams();
@@ -76,17 +120,10 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
   // Use localStorage hook for email
   const [storedEmail, setStoredEmail, clearStoredEmail] = useLocalStorage<string | null>(EMAIL_STORAGE_KEY, null);
 
-  // Automatic token refresh - refreshes token before expiry, on focus, and on network reconnect
-  useTokenRefresh({
-    enabled: true,
-    onRefresh: (newToken) => {
-      authLogger.info('Token auto-refreshed successfully');
-    },
-    onRefreshError: (error) => {
-      authLogger.warn('Token auto-refresh failed:', error.message);
-      // Don't logout on refresh error - user might still have valid session
-    },
-  });
+  // Automatic token refresh - refreshes token before expiry, on focus, and on network reconnect.
+  // NOTE: onRefreshError is wired below, after clearAuthState is defined
+  // (see handleProactiveRefreshError), so it can collapse a dead session to the
+  // login form. useTokenRefresh only runs when a refresh token exists.
 
   // Map AccountsContext profile to UserProfile
   const user = accounts.profile as UserProfile | null;
@@ -115,7 +152,36 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
     // Note: user is now managed by AccountsContext, will auto-update
     setInitialized(true);
     setIsLoading(false);
-  }, []);
+    // Tokens just went away — recompute `isAuthenticated` so the guard shows
+    // the login form instead of hanging on the preloader.
+    bumpAuthTick();
+  }, [bumpAuthTick]);
+
+  // Proactive-refresh failure handler. useTokenRefresh (expiry timer / focus /
+  // reconnect) runs OUTSIDE the response interceptor, so its failures do NOT go
+  // through auth.onUnauthorized. A failed proactive refresh means the refresh
+  // token is dead (expired, or blacklisted after rotation) → the session is
+  // unrecoverable → clear it and show the login form. This is what was missing:
+  // the old handler just logged a warning and left stale tokens, so the app hung
+  // on "Authenticating…" forever.
+  const handleProactiveRefreshError = useCallback((error: Error) => {
+    authLogger.warn('Proactive token refresh failed — session is dead, redirecting to login:', error.message);
+    // Guard against the redirect firing twice if the interceptor path already tripped.
+    if (onUnauthorizedRef.current) return;
+    onUnauthorizedRef.current = true;
+    clearAuthState('proactiveRefresh:failed');
+    const authCallbackUrl = configRef.current?.routes?.defaultAuthCallback || defaultRoutes.defaultAuthCallback;
+    router.hardReplace(authCallbackUrl);
+  }, [clearAuthState, router]);
+
+  // Automatic token refresh — refreshes before expiry, on focus, and on reconnect.
+  useTokenRefresh({
+    enabled: true,
+    onRefresh: () => {
+      authLogger.info('Token auto-refreshed successfully');
+    },
+    onRefreshError: handleProactiveRefreshError,
+  });
 
   // Global error handler for auth-related errors
   // Only clears auth on actual authentication errors (401), not on any API error
@@ -141,6 +207,34 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
     return false;
   }, [clearAuthState]);
 
+  // Unrecoverable-401 handler from the generated client. Fires ONLY when a 401
+  // could not be recovered by the refresh path — no refresh token, no handler,
+  // the refresh call failed (e.g. "Token is blacklisted" after rotation), or
+  // the retried request still 401'd. Transparently-recovered 401s never reach
+  // here. This is the single place that guarantees a dead session collapses to
+  // the login form: clear tokens + hard-redirect to /auth.
+  //
+  // Without this, a proactive refresh (useTokenRefresh) hitting a blacklisted
+  // token would just log a warning and leave stale tokens in storage, so the
+  // guard stayed on "Authenticating…" forever and never rendered the form.
+  useEffect(() => {
+    const handler = () => {
+      if (onUnauthorizedRef.current) return; // de-dupe concurrent 401s
+      onUnauthorizedRef.current = true;
+      authLogger.warn('Unrecoverable 401 (refresh failed) — clearing session and redirecting to login');
+      clearAuthState('onUnauthorized:401');
+      const authCallbackUrl = configRef.current?.routes?.defaultAuthCallback || defaultRoutes.defaultAuthCallback;
+      router.hardReplace(authCallbackUrl);
+    };
+    apiAccounts.onUnauthorized(handler);
+    return () => {
+      // Only clear if we're still the registered handler (StrictMode double-mount
+      // can register a newer one before this cleanup runs).
+      apiAccounts.onUnauthorized(null);
+    };
+    // clearAuthState/router are stable (useCallback); configRef is a ref.
+  }, [clearAuthState, router]);
+
   // SWR onError: auto-logout on 401 from any SWR hook
   const isAutoLoggingOutRef = useRef(false);
   const swrOnError = useCallback((error: any) => {
@@ -244,6 +338,17 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
       authLogger.info('Refresh token from API:', refreshToken ? `${refreshToken.substring(0, 20)}...` : 'null');
       authLogger.info('localStorage keys:', Object.keys(localStorage).filter(k => k.includes('token') || k.includes('auth')));
 
+      // Fail-fast: if storage holds a DEAD session (access expired/malformed AND
+      // refresh unusable), clear it and show the login form immediately — never
+      // fire doomed profile/refresh calls that just 401 and hang the UI. This is
+      // the automated version of "clear localStorage, then the form appears".
+      // Skipped in iframe mode: the parent frame owns token delivery there.
+      if (!isInIframe && isSessionDeadOnBootstrap(token, refreshToken)) {
+        authLogger.warn('Bootstrap: dead session in storage (access + refresh both unusable) — clearing and showing login');
+        clearAuthState('initializeAuth:deadSession');
+        return;
+      }
+
       const hasTokens = hasValidTokens();
       authLogger.info('Has tokens:', hasTokens);
 
@@ -596,7 +701,9 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
     () => ({
       user,
       isLoading,
-      // Consider authenticated if we have valid tokens, even without user profile
+      // Consider authenticated if we have valid tokens, even without user profile.
+      // `authTick` (in deps) forces recompute after tokens are cleared/set, since
+      // token state lives in storage, not React state.
       isAuthenticated: apiAccounts.isAuthenticated(),
       isAdminUser,
       loadCurrentProfile,
@@ -622,6 +729,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
     [
       user,
       isLoading,
+      authTick, // recompute isAuthenticated when tokens are cleared/set
       isAdminUser,
       loadCurrentProfile,
       checkAuthAndRedirect,

package/src/auth/hooks/useTokenRefresh.ts

@@ -24,6 +24,7 @@ import { useCallback, useEffect } from 'react';
 import { api as apiAccounts } from '../../';
 import { triggerRefresh } from '../refreshHandler';
 import { authLogger } from '../utils/logger';
+import { isTokenExpiringSoon } from '../utils/jwt';
 
 // Configuration
 const TOKEN_REFRESH_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes before expiry
@@ -38,29 +39,10 @@ interface UseTokenRefreshOptions {
   onRefreshError?: (error: Error) => void;
 }
 
-/**
- * Decode JWT and get expiry time (ms epoch), or null if undecodable.
- */
-function getTokenExpiry(token: string): number | null {
-  try {
-    const payload = JSON.parse(atob(token.split('.')[1]));
-    return payload.exp * 1000;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Check if token is expiring within the threshold.
- */
-function isTokenExpiringSoon(token: string, thresholdMs: number): boolean {
-  const expiry = getTokenExpiry(token);
-  if (!expiry) return false;
-  return expiry - Date.now() < thresholdMs;
-}
-
 /**
  * Hook for proactive automatic token refresh.
+ * (JWT expiry helpers live in ../utils/jwt so they can be unit-tested and
+ * reused by the auth-bootstrap validation path.)
  */
 export function useTokenRefresh(options: UseTokenRefreshOptions = {}) {
   const { enabled = true, onRefresh, onRefreshError } = options;