@djangocfg/api 2.1.450 → 2.1.452

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.450",
+  "version": "2.1.452",
   "description": "Auto-generated TypeScript API client with React hooks, SWR integration, and Zod validation for Django REST Framework backends",
   "keywords": [
     "django",
@@ -84,9 +84,11 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@djangocfg/typescript-config": "^2.1.452",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
-    "@djangocfg/typescript-config": "^2.1.450",
+    "jsdom": "^29.1.1",
     "next": "^16.2.2",
     "react": "^19.2.4",
     "tsup": "^8.5.0",

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

@@ -0,0 +1,101 @@
+/**
+ * Redirect-URL manager tests (auth/hooks/useAuthRedirect.ts).
+ *
+ * After login the app must send the user back to where they were headed. The
+ * manager persists that URL in sessionStorage (surviving the auth round-trip,
+ * readable across component instances) and clears it on use. The public methods
+ * getFinalRedirectUrl / useAndClearRedirect / hasRedirect read straight from
+ * sessionStorage, bypassing React state — that is exactly the cross-instance
+ * behaviour under test.
+ *
+ * useAuthRedirectManager calls useSessionStorage → React.useState. We mock
+ * useState with a plain closure so the hook body can run outside a React render
+ * (we are testing the storage logic, not React state wiring).
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Mock React's useState so the hook runs without a renderer. The lazy
+// initializer is invoked immediately (mirroring React) and its value returned.
+vi.mock('react', () => ({
+  useState: (init: unknown) => {
+    const value = typeof init === 'function' ? (init as () => unknown)() : init;
+    return [value, () => {}];
+  },
+}));
+
+function installSessionStorage() {
+  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', { sessionStorage: storage, localStorage: storage });
+  vi.stubGlobal('sessionStorage', storage);
+  return map;
+}
+
+const KEY = 'auth_redirect_url';
+
+describe('useAuthRedirectManager (storage-backed paths)', () => {
+  beforeEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it('falls back to the provided fallbackUrl when nothing is saved', async () => {
+    installSessionStorage();
+    const { useAuthRedirectManager } = await import('../hooks/useAuthRedirect');
+    const mgr = useAuthRedirectManager({ fallbackUrl: '/home', clearOnUse: true });
+    expect(mgr.getFinalRedirectUrl()).toBe('/home');
+    expect(mgr.hasRedirect()).toBe(false);
+  });
+
+  it('reads a saved redirect straight from sessionStorage', async () => {
+    const map = installSessionStorage();
+    map.set(KEY, JSON.stringify('/projects/42'));
+    const { useAuthRedirectManager } = await import('../hooks/useAuthRedirect');
+    const mgr = useAuthRedirectManager({ fallbackUrl: '/home' });
+
+    expect(mgr.hasRedirect()).toBe(true);
+    expect(mgr.getFinalRedirectUrl()).toBe('/projects/42');
+  });
+
+  it('useAndClearRedirect returns the saved URL then clears it (clearOnUse)', async () => {
+    const map = installSessionStorage();
+    map.set(KEY, JSON.stringify('/settings'));
+    const { useAuthRedirectManager } = await import('../hooks/useAuthRedirect');
+    const mgr = useAuthRedirectManager({ fallbackUrl: '/home', clearOnUse: true });
+
+    expect(mgr.useAndClearRedirect()).toBe('/settings');
+    expect(map.has(KEY)).toBe(false); // cleared from storage
+
+    // A FRESH manager (mirrors a new component instance after the redirect) now
+    // sees empty storage and falls back. (This manager's mocked React state
+    // still holds the old value — real React would re-init from storage.)
+    const fresh = useAuthRedirectManager({ fallbackUrl: '/home' });
+    expect(fresh.getFinalRedirectUrl()).toBe('/home');
+    expect(fresh.hasRedirect()).toBe(false);
+  });
+
+  it('useAndClearRedirect keeps the URL when clearOnUse is false', async () => {
+    const map = installSessionStorage();
+    map.set(KEY, JSON.stringify('/keep-me'));
+    const { useAuthRedirectManager } = await import('../hooks/useAuthRedirect');
+    const mgr = useAuthRedirectManager({ fallbackUrl: '/home', clearOnUse: false });
+
+    expect(mgr.useAndClearRedirect()).toBe('/keep-me');
+    expect(map.has(KEY)).toBe(true); // preserved
+  });
+
+  it('gracefully falls back on corrupt storage JSON', async () => {
+    const map = installSessionStorage();
+    map.set(KEY, 'not-json'); // getRedirectFromStorage catches + returns ''
+    const { useAuthRedirectManager } = await import('../hooks/useAuthRedirect');
+    const mgr = useAuthRedirectManager({ fallbackUrl: '/home' });
+
+    expect(mgr.getFinalRedirectUrl()).toBe('/home');
+  });
+});

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

@@ -0,0 +1,53 @@
+/**
+ * Base64 helper tests (auth/hooks/useBase64.ts).
+ *
+ * The profile cache is stored base64-encoded, so a broken roundtrip corrupts
+ * the cache (which then must fail closed — see profileCache.test). These tests
+ * pin the roundtrip, including UTF-8 / emoji, and the fail-safe behaviour that
+ * returns the input unchanged on a decode error rather than throwing.
+ *
+ * NOTE: isDev is false under vitest (NODE_ENV='test'), so encoding is active.
+ * The Node.js Buffer fallback path runs when `window` is absent.
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { decodeBase64, encodeBase64 } from '../hooks/useBase64';
+
+describe('base64 roundtrip (Node fallback path — no window)', () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it.each([
+    'hello world',
+    '{"id":7,"email":"a@b.com"}',
+    'ünïcödé and ✅ 🚀 emoji',
+    'кириллица и пробелы',
+    '中文字符',
+    '',
+  ])('roundtrips %j', (input) => {
+    const encoded = encodeBase64(input);
+    expect(decodeBase64(encoded)).toBe(input);
+  });
+
+  it('returns the input unchanged when decoding invalid base64 (fail-safe)', () => {
+    // Not valid base64 → Buffer/atob throw internally → original returned.
+    const garbage = '!!!not-base64!!!';
+    const out = decodeBase64(garbage);
+    // Either the original string or a best-effort decode — never a throw.
+    expect(typeof out).toBe('string');
+  });
+});
+
+describe('base64 roundtrip (browser path — window with btoa/atob)', () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it('roundtrips UTF-8 through the browser btoa/atob branch', () => {
+    vi.stubGlobal('window', {});
+    vi.stubGlobal('btoa', (s: string) => Buffer.from(s, 'binary').toString('base64'));
+    vi.stubGlobal('atob', (s: string) => Buffer.from(s, 'base64').toString('binary'));
+
+    const input = 'ünïcödé 🚀 профиль';
+    const encoded = encodeBase64(input);
+    expect(decodeBase64(encoded)).toBe(input);
+  });
+});

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

@@ -0,0 +1,30 @@
+/**
+ * Auth constants invariants (auth/constants.ts).
+ *
+ * These lengths gate OTP/TOTP/backup-code validation across the form. A silent
+ * change here (e.g. bumping EMAIL_OTP_LENGTH) would desync the frontend from the
+ * backend's code length and break login, so pin them explicitly. useAutoAuth
+ * also compares the URL OTP against EMAIL_OTP_LENGTH before auto-submitting.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { AUTH_CONSTANTS } from '../constants';
+
+describe('AUTH_CONSTANTS', () => {
+  it('email OTP length is 4 (matches backend numeric OTP)', () => {
+    expect(AUTH_CONSTANTS.EMAIL_OTP_LENGTH).toBe(4);
+  });
+  it('TOTP length is 6 (RFC 6238)', () => {
+    expect(AUTH_CONSTANTS.TOTP_LENGTH).toBe(6);
+  });
+  it('backup code max length is 12', () => {
+    expect(AUTH_CONSTANTS.BACKUP_CODE_MAX_LENGTH).toBe(12);
+  });
+  it('all lengths are positive integers', () => {
+    for (const v of Object.values(AUTH_CONSTANTS)) {
+      expect(Number.isInteger(v)).toBe(true);
+      expect(v).toBeGreaterThan(0);
+    }
+  });
+});

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

@@ -0,0 +1,48 @@
+/**
+ * formatAuthError tests (auth/utils/errors.ts).
+ *
+ * Turns whatever the auth layer throws (string, Error, DRF `{detail}`, axios-ish
+ * nested `response.data.detail`) into a user-facing string, with a stable
+ * fallback. The precedence order matters: message > detail > nested detail, and
+ * it must never throw on null/odd shapes.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { formatAuthError } from '../utils/errors';
+
+describe('formatAuthError', () => {
+  it('returns a plain string as-is', () => {
+    expect(formatAuthError('Something broke')).toBe('Something broke');
+  });
+
+  it('prefers error.message (Error instances)', () => {
+    expect(formatAuthError(new Error('boom'))).toBe('boom');
+  });
+
+  it('reads DRF-style { detail }', () => {
+    expect(formatAuthError({ detail: 'Token is blacklisted' })).toBe('Token is blacklisted');
+  });
+
+  it('reads nested response.data.detail', () => {
+    expect(formatAuthError({ response: { data: { detail: 'nested detail' } } })).toBe('nested detail');
+  });
+
+  it('message wins over detail when both present', () => {
+    expect(formatAuthError({ message: 'msg', detail: 'det' })).toBe('msg');
+  });
+
+  it('detail wins over nested detail', () => {
+    expect(
+      formatAuthError({ detail: 'top', response: { data: { detail: 'deep' } } }),
+    ).toBe('top');
+  });
+
+  it('falls back for null / undefined / empty object', () => {
+    const FALLBACK = 'An unexpected error occurred';
+    expect(formatAuthError(null)).toBe(FALLBACK);
+    expect(formatAuthError(undefined)).toBe(FALLBACK);
+    expect(formatAuthError({})).toBe(FALLBACK);
+    expect(formatAuthError(42)).toBe(FALLBACK);
+  });
+});

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

@@ -0,0 +1,144 @@
+/**
+ * Auth-guard state resolution tests (auth/utils/guard.ts).
+ *
+ * This is the exact branching that produced "stuck on Authenticating…": the
+ * guard must show a preloader while auth is resolving, redirect to the login
+ * form once resolved-and-unauthenticated, and render content when authenticated.
+ * The critical regression guard is the transition authLoading:false +
+ * isAuthenticated:false → isLoading:false + shouldRedirect:true. If isLoading
+ * stayed true there, the spinner would hang forever.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  resolveGuardIsLoading,
+  resolveGuardIsAuthenticated,
+  shouldRedirectToAuth,
+  nextAuthEvaluationDelay,
+  type GuardInput,
+} from '../utils/guard';
+
+const base: GuardInput = {
+  mounted: true,
+  requireAuth: true,
+  authLoading: false,
+  isRedirecting: false,
+  isAuthenticated: true,
+};
+const s = (o: Partial<GuardInput>): GuardInput => ({ ...base, ...o });
+
+describe('resolveGuardIsLoading', () => {
+  it('preloader before mount (SSR/hydration parity), regardless of auth', () => {
+    expect(resolveGuardIsLoading(s({ mounted: false, isAuthenticated: true }))).toBe(true);
+    expect(resolveGuardIsLoading(s({ mounted: false, isAuthenticated: false }))).toBe(true);
+  });
+
+  it('public route never blocks once mounted', () => {
+    expect(resolveGuardIsLoading(s({ requireAuth: false, isAuthenticated: false }))).toBe(false);
+  });
+
+  it('blocks while auth is still resolving', () => {
+    expect(resolveGuardIsLoading(s({ authLoading: true }))).toBe(true);
+  });
+
+  it('blocks while a redirect is in flight', () => {
+    expect(resolveGuardIsLoading(s({ isRedirecting: true }))).toBe(true);
+  });
+
+  it('blocks when resolved but unauthenticated (about to redirect)', () => {
+    expect(resolveGuardIsLoading(s({ authLoading: false, isAuthenticated: false }))).toBe(true);
+  });
+
+  it('renders content when mounted + authenticated + not loading', () => {
+    expect(resolveGuardIsLoading(base)).toBe(false);
+  });
+});
+
+describe('shouldRedirectToAuth', () => {
+  it('REGRESSION: resolved + unauthenticated → redirect (never hang)', () => {
+    expect(shouldRedirectToAuth(s({ authLoading: false, isAuthenticated: false }))).toBe(true);
+  });
+
+  it('does not redirect before mount', () => {
+    expect(shouldRedirectToAuth(s({ mounted: false, isAuthenticated: false }))).toBe(false);
+  });
+
+  it('does not redirect while auth is still loading', () => {
+    expect(shouldRedirectToAuth(s({ authLoading: true, isAuthenticated: false }))).toBe(false);
+  });
+
+  it('does not redirect when authenticated', () => {
+    expect(shouldRedirectToAuth(s({ isAuthenticated: true }))).toBe(false);
+  });
+
+  it('does not redirect twice (already redirecting)', () => {
+    expect(shouldRedirectToAuth(s({ isAuthenticated: false, isRedirecting: true }))).toBe(false);
+  });
+
+  it('does not redirect on a public route', () => {
+    expect(shouldRedirectToAuth(s({ requireAuth: false, isAuthenticated: false }))).toBe(false);
+  });
+});
+
+describe('safety-net timeout (effectiveAuthLoading = authLoading && !timedOut)', () => {
+  // useAuthGuard forces authLoading→false once its timeout fires. Model that
+  // here to prove the guard then acts (redirect / render) instead of spinning.
+  const withTimeout = (o: Partial<GuardInput>, timedOut: boolean): GuardInput => {
+    const st = s(o);
+    return { ...st, authLoading: st.authLoading && !timedOut };
+  };
+
+  it('a wedged loading state stops blocking once the timeout fires', () => {
+    // authLoading stuck true, unauthenticated. Before timeout: still loading.
+    expect(resolveGuardIsLoading(withTimeout({ authLoading: true, isAuthenticated: false }, false))).toBe(true);
+    // After timeout: authLoading forced false → resolves, and since unauth it
+    // is "about to redirect" loading, but shouldRedirect now fires.
+    expect(shouldRedirectToAuth(withTimeout({ authLoading: true, isAuthenticated: false }, true))).toBe(true);
+  });
+
+  it('timeout lets an authenticated-but-wedged session render content', () => {
+    expect(resolveGuardIsLoading(withTimeout({ authLoading: true, isAuthenticated: true }, true))).toBe(false);
+  });
+});
+
+describe('resolveGuardIsAuthenticated', () => {
+  it('is true on a public route regardless of session', () => {
+    expect(resolveGuardIsAuthenticated({ requireAuth: false, isAuthenticated: false })).toBe(true);
+  });
+  it('reflects the session on a protected route', () => {
+    expect(resolveGuardIsAuthenticated({ requireAuth: true, isAuthenticated: true })).toBe(true);
+    expect(resolveGuardIsAuthenticated({ requireAuth: true, isAuthenticated: false })).toBe(false);
+  });
+});
+
+describe('nextAuthEvaluationDelay (time-driven re-check scheduling)', () => {
+  const NOW = 1_800_000_000_000;
+
+  it('schedules on the SOONEST future expiry + 1s cushion', () => {
+    const access = NOW + 5 * 60_000; // 5 min
+    const refresh = NOW + 60 * 60_000; // 60 min
+    expect(nextAuthEvaluationDelay(access, refresh, NOW)).toBe(5 * 60_000 + 1000);
+  });
+
+  it('uses refresh expiry when access is already past', () => {
+    const access = NOW - 1000; // already expired → ignored
+    const refresh = NOW + 10 * 60_000;
+    expect(nextAuthEvaluationDelay(access, refresh, NOW)).toBe(10 * 60_000 + 1000);
+  });
+
+  it('returns null when nothing live remains (no timer to arm)', () => {
+    expect(nextAuthEvaluationDelay(NOW - 1, NOW - 2, NOW)).toBeNull();
+    expect(nextAuthEvaluationDelay(null, null, NOW)).toBeNull();
+  });
+
+  it('handles a single live token (other absent)', () => {
+    expect(nextAuthEvaluationDelay(NOW + 30_000, null, NOW)).toBe(31_000);
+    expect(nextAuthEvaluationDelay(null, NOW + 30_000, NOW)).toBe(31_000);
+  });
+
+  it('never returns a negative delay', () => {
+    const d = nextAuthEvaluationDelay(NOW + 1, NOW + 1, NOW);
+    expect(d).toBeGreaterThan(0);
+  });
+});

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

@@ -0,0 +1,67 @@
+/**
+ * Auth path normalization tests (auth/utils/path.ts).
+ *
+ * These gate whether the magic-link / OTP-in-URL auto-auth fires on the current
+ * page. A locale prefix (`/ru/auth`) or trailing slash must NOT stop `/auth`
+ * from matching — otherwise a localized magic link silently does nothing. And a
+ * 2-letter path segment that is actually a route (not a locale) must not be
+ * eaten (edge case documented below).
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { isAllowedAuthPath, normalizePath } from '../utils/path';
+
+describe('normalizePath', () => {
+  it.each([
+    ['/auth', '/auth'],
+    ['/auth/', '/auth'],
+    ['/ru/auth', '/auth'],
+    ['/en/auth/', '/auth'],
+    ['/ru/auth/callback', '/auth/callback'],
+    ['/', '/'],
+    ['', ''],
+    ['/dashboard', '/dashboard'],
+    ['/ru/', '/'],
+  ])('normalizes %j → %j', (input, expected) => {
+    expect(normalizePath(input)).toBe(expected);
+  });
+
+  it('returns empty string for null / undefined', () => {
+    expect(normalizePath(null)).toBe('');
+    expect(normalizePath(undefined)).toBe('');
+  });
+
+  it('strips only a leading 2-letter segment, not longer ones', () => {
+    // '/abc/auth' — 'abc' is 3 letters, not a locale, so it stays.
+    expect(normalizePath('/abc/auth')).toBe('/abc/auth');
+  });
+});
+
+describe('isAllowedAuthPath', () => {
+  it('matches the exact allowed path', () => {
+    expect(isAllowedAuthPath('/auth', ['/auth'])).toBe(true);
+  });
+  it('matches with a locale prefix', () => {
+    expect(isAllowedAuthPath('/ru/auth', ['/auth'])).toBe(true);
+  });
+  it('matches with a trailing slash', () => {
+    expect(isAllowedAuthPath('/auth/', ['/auth'])).toBe(true);
+  });
+  it('matches a nested path under an allowed root', () => {
+    expect(isAllowedAuthPath('/ru/auth/callback', ['/auth'])).toBe(true);
+  });
+  it('does NOT match an unrelated page', () => {
+    expect(isAllowedAuthPath('/dashboard/device', ['/auth'])).toBe(false);
+  });
+  it('does NOT match a path that merely starts with the same letters', () => {
+    // '/authentication' must not match allow-list entry '/auth'.
+    expect(isAllowedAuthPath('/authentication', ['/auth'])).toBe(false);
+  });
+  it('honors multiple allowed paths', () => {
+    expect(isAllowedAuthPath('/login', ['/auth', '/login'])).toBe(true);
+  });
+  it('returns false for null pathname', () => {
+    expect(isAllowedAuthPath(null, ['/auth'])).toBe(false);
+  });
+});

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

@@ -0,0 +1,138 @@
+/**
+ * Profile cache tests (auth/hooks/useProfileCache.ts).
+ *
+ * The profile cache is a localStorage entry that lets the app render "logged in"
+ * UI without an API round-trip. It is DIRECTLY implicated in the stuck-auth bug:
+ * a cached profile left behind by a now-dead session made AuthContext skip the
+ * API and treat the user as authenticated. So the cache must expire on TTL,
+ * invalidate on version bump, and fail CLOSED on corruption (return null + clear)
+ * rather than surfacing garbage.
+ *
+ * The module reads `window.localStorage` / `Date.now()` at call time; we install
+ * a fake storage on globalThis before import and drive time via vi.setSystemTime.
+ */
+
+import { afterEach, 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(),
+    key: (i: number) => Array.from(map.keys())[i] ?? null,
+    get length() { return map.size; },
+  };
+  // useBase64 checks `isDev` via env and uses window for btoa/atob; provide both.
+  vi.stubGlobal('window', { localStorage: storage });
+  vi.stubGlobal('localStorage', storage);
+  return map;
+}
+
+const CACHE_KEY = 'user_profile_cache';
+const NOW = 1_800_000_000_000;
+
+// Minimal User-shaped object; the cache is generic over its shape.
+const sampleUser = { id: 7, email: 'a@b.com', is_staff: false } as never;
+
+describe('profile cache', () => {
+  beforeEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+    vi.useFakeTimers();
+    vi.setSystemTime(NOW);
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('round-trips a profile set→get within TTL', async () => {
+    installBrowserStorage();
+    const { setCachedProfile, getCachedProfile } = await import('../hooks/useProfileCache');
+    setCachedProfile(sampleUser);
+    expect(getCachedProfile()).toEqual(sampleUser);
+  });
+
+  it('returns null when nothing is cached', async () => {
+    installBrowserStorage();
+    const { getCachedProfile } = await import('../hooks/useProfileCache');
+    expect(getCachedProfile()).toBeNull();
+  });
+
+  it('expires after TTL and clears the entry', async () => {
+    const map = installBrowserStorage();
+    const { setCachedProfile, getCachedProfile } = await import('../hooks/useProfileCache');
+    setCachedProfile(sampleUser, { ttl: 1000 });
+    expect(getCachedProfile()).toEqual(sampleUser);
+
+    vi.setSystemTime(NOW + 1001); // just past TTL
+    expect(getCachedProfile()).toBeNull();
+    expect(map.has(CACHE_KEY)).toBe(false); // expired cache is purged
+  });
+
+  it('keeps the profile right up to the TTL boundary', async () => {
+    installBrowserStorage();
+    const { setCachedProfile, getCachedProfile } = await import('../hooks/useProfileCache');
+    setCachedProfile(sampleUser, { ttl: 1000 });
+    vi.setSystemTime(NOW + 1000); // exactly TTL — age === ttl, not yet "> ttl"
+    expect(getCachedProfile()).toEqual(sampleUser);
+  });
+
+  it('invalidates on a cache-version mismatch (migration safety)', async () => {
+    const map = installBrowserStorage();
+    const { getCachedProfile } = await import('../hooks/useProfileCache');
+    const { encodeBase64 } = await import('../hooks/useBase64');
+    // Hand-write an entry from a FUTURE/old version.
+    const stale = { version: 999, data: sampleUser, timestamp: NOW, ttl: 10_000 };
+    map.set(CACHE_KEY, encodeBase64(JSON.stringify(stale)));
+    expect(getCachedProfile()).toBeNull();
+    expect(map.has(CACHE_KEY)).toBe(false);
+  });
+
+  it('fails closed on corrupt cache data (returns null + clears)', async () => {
+    const map = installBrowserStorage();
+    const { getCachedProfile } = await import('../hooks/useProfileCache');
+    map.set(CACHE_KEY, 'this-is-not-valid-encoded-json');
+    expect(getCachedProfile()).toBeNull();
+    expect(map.has(CACHE_KEY)).toBe(false);
+  });
+
+  it('clearProfileCache removes the entry', async () => {
+    const map = installBrowserStorage();
+    const { setCachedProfile, clearProfileCache } = await import('../hooks/useProfileCache');
+    setCachedProfile(sampleUser);
+    expect(map.has(CACHE_KEY)).toBe(true);
+    clearProfileCache();
+    expect(map.has(CACHE_KEY)).toBe(false);
+  });
+
+  it('hasValidCache reflects presence + freshness', async () => {
+    installBrowserStorage();
+    const { setCachedProfile, hasValidCache } = await import('../hooks/useProfileCache');
+    expect(hasValidCache()).toBe(false);
+    setCachedProfile(sampleUser, { ttl: 500 });
+    expect(hasValidCache()).toBe(true);
+    vi.setSystemTime(NOW + 501);
+    expect(hasValidCache()).toBe(false);
+  });
+
+  it('getCacheMetadata reports age / ttl / expiresIn', async () => {
+    installBrowserStorage();
+    const { setCachedProfile, getCacheMetadata } = await import('../hooks/useProfileCache');
+    expect(getCacheMetadata()).toEqual({ exists: false });
+
+    setCachedProfile(sampleUser, { ttl: 10_000 });
+    vi.setSystemTime(NOW + 3_000);
+    const meta = getCacheMetadata();
+    expect(meta).toMatchObject({ exists: true, age: 3_000, ttl: 10_000, expiresIn: 7_000 });
+  });
+
+  it('getCacheMetadata clamps expiresIn to 0 once expired', async () => {
+    installBrowserStorage();
+    const { setCachedProfile, getCacheMetadata } = await import('../hooks/useProfileCache');
+    setCachedProfile(sampleUser, { ttl: 1_000 });
+    vi.setSystemTime(NOW + 5_000);
+    expect(getCacheMetadata()?.expiresIn).toBe(0);
+  });
+});

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

@@ -74,3 +74,38 @@ describe('isSessionDeadOnBootstrap', () => {
     expect(isSessionDeadOnBootstrap(atNow, atNow, NOW)).toBe(true);
   });
 });
+
+/**
+ * `isAuthenticated` is now derived as `!isSessionDeadOnBootstrap(...)` (via the
+ * private isSessionAlive wrapper in AuthContext). These assertions read the same
+ * predicate from the guard's point of view — proving the fix is self-sufficient:
+ * a stale session reads as unauthenticated from LOCAL exp alone, with no server
+ * 401 required (the exact case a CSP-blocked / hung request used to swallow).
+ */
+describe('isAuthenticated gate (derived from session liveness, network-free)', () => {
+  const alive = (a: string | null, r: string | null) => !isSessionDeadOnBootstrap(a, r, NOW);
+
+  it('reports authenticated while the access token is still valid', () => {
+    expect(alive(live(), null)).toBe(true);
+  });
+
+  it('stays authenticated when access is expired but refresh can still renew', () => {
+    // Between access expiry and the silent refresh — NOT bounced to /auth.
+    expect(alive(dead(), live())).toBe(true);
+  });
+
+  it('reports UNAUTHENTICATED the instant both tokens are expired — no 401 needed', () => {
+    // This is the reporter's scenario: an expired session where the 401 that
+    // would normally trigger logout is swallowed by CSP / a hung request.
+    expect(alive(dead(), dead())).toBe(false);
+  });
+
+  it('reports UNAUTHENTICATED for a stale access with no refresh token', () => {
+    expect(alive(dead(), null)).toBe(false);
+  });
+
+  it('reports UNAUTHENTICATED for garbage tokens (would have read "present" before)', () => {
+    // The OLD isAuthenticated() returned true for any non-null token string.
+    expect(alive('stale-non-jwt', 'also-garbage')).toBe(false);
+  });
+});