@djangocfg/api 2.1.450 → 2.1.452

package/src/auth/__tests__/useAuthForm.2fa.test.ts

@@ -7,38 +7,48 @@
  * branch relies on.
  */
 
+// @vitest-environment jsdom
 import { act, renderHook } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { useAuthForm } from '../hooks/useAuthForm';
 
-// Mock dependencies
-jest.mock('../context', () => ({
+// useAuthForm pulls in useAutoAuth → useCfgRouter → next/navigation, which
+// throws outside an app-router provider. Stub the navigation surface it uses.
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ push: vi.fn(), replace: vi.fn(), prefetch: vi.fn(), back: vi.fn() }),
+  usePathname: () => '/auth',
+  useSearchParams: () => new URLSearchParams(),
+}));
+
+// Mock dependencies (migrated from Jest → Vitest)
+vi.mock('../context', () => ({
   useAuth: () => ({
-    requestOTP: jest.fn().mockResolvedValue({ success: true }),
-    verifyOTP: jest.fn(),
-    getSavedEmail: jest.fn().mockReturnValue(null),
-    saveEmail: jest.fn(),
-    clearSavedEmail: jest.fn(),
-    getSavedPhone: jest.fn().mockReturnValue(null),
-    savePhone: jest.fn(),
-    clearSavedPhone: jest.fn(),
+    requestOTP: vi.fn().mockResolvedValue({ success: true }),
+    verifyOTP: vi.fn(),
+    getSavedEmail: vi.fn().mockReturnValue(null),
+    saveEmail: vi.fn(),
+    clearSavedEmail: vi.fn(),
+    getSavedPhone: vi.fn().mockReturnValue(null),
+    savePhone: vi.fn(),
+    clearSavedPhone: vi.fn(),
   }),
 }));
 
-jest.mock('../hooks/useTwoFactor', () => ({
+vi.mock('../hooks/useTwoFactor', () => ({
   useTwoFactor: () => ({
     isLoading: false,
     warning: null,
-    verifyTOTP: jest.fn(),
-    verifyBackupCode: jest.fn(),
+    verifyTOTP: vi.fn(),
+    verifyBackupCode: vi.fn(),
   }),
 }));
 
-jest.mock('../utils/logger', () => ({
+vi.mock('../utils/logger', () => ({
   authLogger: {
-    info: jest.fn(),
-    warn: jest.fn(),
-    error: jest.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
   },
 }));
 
@@ -49,7 +59,7 @@ describe('useAuthForm - 2FA', () => {
   };
 
   beforeEach(() => {
-    jest.clearAllMocks();
+    vi.clearAllMocks();
   });
 
   describe('step transitions', () => {

package/src/auth/__tests__/useTokenRefresh.dom.test.tsx

@@ -0,0 +1,167 @@
+// @vitest-environment jsdom
+
+/**
+ * useTokenRefresh DOM tests.
+ *
+ * The proactive refresher decides WHEN to refresh (expiry timer, window focus,
+ * network reconnect) and delegates HOW to triggerRefresh. It is central to the
+ * stuck-auth bug: a proactive refresh that fails on a dead/blacklisted token
+ * must surface onRefreshError so AuthContext can collapse the session to the
+ * login form. These tests mock the api store + triggerRefresh and drive timers
+ * and window events.
+ */
+
+import { renderHook, act } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Mocks must be declared before importing the hook under test.
+const mockGetToken = vi.fn<() => string | null>();
+const mockGetRefreshToken = vi.fn<() => string | null>();
+const mockTriggerRefresh = vi.fn<() => Promise<string | null>>();
+
+vi.mock('../../', () => ({
+  api: {
+    getToken: () => mockGetToken(),
+    getRefreshToken: () => mockGetRefreshToken(),
+  },
+}));
+vi.mock('../refreshHandler', () => ({
+  triggerRefresh: () => mockTriggerRefresh(),
+}));
+
+import { useTokenRefresh } from '../hooks/useTokenRefresh';
+
+const NOW = 1_800_000_000_000;
+const expSeconds = (ms: number) => Math.floor(ms / 1000);
+function b64url(o: unknown) {
+  return Buffer.from(JSON.stringify(o), 'utf8').toString('base64')
+    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function jwt(exp: number) {
+  return `${b64url({ alg: 'HS256' })}.${b64url({ exp })}.sig`;
+}
+const liveToken = () => jwt(expSeconds(NOW + 60 * 60_000)); // +1h — not expiring
+const expiringToken = () => jwt(expSeconds(NOW + 60_000)); // +1m — within 10m threshold
+
+describe('useTokenRefresh', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(NOW);
+    mockGetToken.mockReset();
+    mockGetRefreshToken.mockReset();
+    mockTriggerRefresh.mockReset();
+    mockGetRefreshToken.mockReturnValue('R-valid');
+    mockTriggerRefresh.mockResolvedValue('access-new');
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('refreshes on mount when the token is expiring soon', async () => {
+    mockGetToken.mockReturnValue(expiringToken());
+    renderHook(() => useTokenRefresh({ enabled: true }));
+    // initial checkAndRefresh runs in an effect
+    await act(async () => { await Promise.resolve(); });
+    expect(mockTriggerRefresh).toHaveBeenCalledTimes(1);
+  });
+
+  it('does NOT refresh on mount when the token is fresh', async () => {
+    mockGetToken.mockReturnValue(liveToken());
+    renderHook(() => useTokenRefresh({ enabled: true }));
+    await act(async () => { await Promise.resolve(); });
+    expect(mockTriggerRefresh).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when there is no access token', async () => {
+    mockGetToken.mockReturnValue(null);
+    renderHook(() => useTokenRefresh({ enabled: true }));
+    await act(async () => { await Promise.resolve(); });
+    expect(mockTriggerRefresh).not.toHaveBeenCalled();
+  });
+
+  it('is inert when disabled', async () => {
+    mockGetToken.mockReturnValue(expiringToken());
+    renderHook(() => useTokenRefresh({ enabled: false }));
+    await act(async () => { await Promise.resolve(); });
+    expect(mockTriggerRefresh).not.toHaveBeenCalled();
+  });
+
+  it('fires onRefresh with the new token on success', async () => {
+    mockGetToken.mockReturnValue(expiringToken());
+    const onRefresh = vi.fn();
+    const { result } = renderHook(() => useTokenRefresh({ enabled: true, onRefresh }));
+    await act(async () => { await result.current.refreshToken(); });
+    expect(onRefresh).toHaveBeenCalledWith('access-new');
+  });
+
+  it('fires onRefreshError when the refresh fails (dead/blacklisted token)', async () => {
+    // Fresh token so the mount-effect check does NOT auto-refresh; we drive the
+    // failing refresh explicitly to isolate the error path.
+    mockGetToken.mockReturnValue(liveToken());
+    mockTriggerRefresh.mockResolvedValue(null); // refresh failed
+    const onRefreshError = vi.fn();
+    const { result } = renderHook(() => useTokenRefresh({ enabled: true, onRefreshError }));
+    await act(async () => { await Promise.resolve(); }); // let mount effect settle (no-op)
+    expect(mockTriggerRefresh).not.toHaveBeenCalled();
+
+    await act(async () => {
+      const ok = await result.current.refreshToken();
+      expect(ok).toBe(false);
+    });
+    expect(onRefreshError).toHaveBeenCalledTimes(1);
+    expect(onRefreshError.mock.calls[0][0]).toBeInstanceOf(Error);
+  });
+
+  it('refreshToken returns false and skips trigger when no refresh token exists', async () => {
+    mockGetToken.mockReturnValue(expiringToken());
+    mockGetRefreshToken.mockReturnValue(null);
+    const { result } = renderHook(() => useTokenRefresh({ enabled: true }));
+    await act(async () => {
+      const ok = await result.current.refreshToken();
+      expect(ok).toBe(false);
+    });
+    expect(mockTriggerRefresh).not.toHaveBeenCalled();
+  });
+
+  it('refreshes on window focus when the token is expiring', async () => {
+    mockGetToken.mockReturnValue(expiringToken());
+    renderHook(() => useTokenRefresh({ enabled: true }));
+    await act(async () => { await Promise.resolve(); }); // consume mount check
+    mockTriggerRefresh.mockClear();
+
+    await act(async () => {
+      window.dispatchEvent(new Event('focus'));
+      await Promise.resolve();
+    });
+    expect(mockTriggerRefresh).toHaveBeenCalledTimes(1);
+  });
+
+  it('refreshes on network reconnect (online event)', async () => {
+    mockGetToken.mockReturnValue(expiringToken());
+    renderHook(() => useTokenRefresh({ enabled: true }));
+    await act(async () => { await Promise.resolve(); });
+    mockTriggerRefresh.mockClear();
+
+    await act(async () => {
+      window.dispatchEvent(new Event('online'));
+      await Promise.resolve();
+    });
+    expect(mockTriggerRefresh).toHaveBeenCalledTimes(1);
+  });
+
+  it('removes its event listeners on unmount', async () => {
+    mockGetToken.mockReturnValue(expiringToken());
+    const { unmount } = renderHook(() => useTokenRefresh({ enabled: true }));
+    await act(async () => { await Promise.resolve(); });
+    unmount();
+    mockTriggerRefresh.mockClear();
+
+    await act(async () => {
+      window.dispatchEvent(new Event('focus'));
+      window.dispatchEvent(new Event('online'));
+      await Promise.resolve();
+    });
+    expect(mockTriggerRefresh).not.toHaveBeenCalled();
+  });
+});

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

@@ -1,37 +1,41 @@
+// @vitest-environment jsdom
 /**
  * Tests for useTwoFactorStatus hook
  *
  * Tests the hook for checking and managing 2FA status in ProfileLayout.
+ * (Migrated from Jest to Vitest: jest.* → vi.*, added jsdom env + vi import.)
  */
 
-import { act, renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { useTwoFactorStatus } from '../hooks/useTwoFactorStatus';
 
-// Mock apiTotp
-const mockList = jest.fn();
-const mockDisableCreate = jest.fn();
-
-jest.mock('../../clients', () => ({
-  apiTotp: {
-    totp_management: {
-      list: () => mockList(),
-      disableCreate: (data: any) => mockDisableCreate(data),
-    },
+// The hook calls the generated SDK (CfgTotp.cfgTotpDevicesRetrieve /
+// cfgTotpDisableCreate), NOT the old apiTotp.totp_management surface — the hook
+// was refactored and this suite was stale. Mock the SDK the hook actually uses.
+// Retrieve resolves to `{ data }`; disable is awaited for its side effect only.
+const mockDevicesRetrieve = vi.fn();
+const mockDisableCreate = vi.fn();
+
+vi.mock('../../_api/generated/sdk.gen', () => ({
+  CfgTotp: {
+    cfgTotpDevicesRetrieve: () => mockDevicesRetrieve(),
+    cfgTotpDisableCreate: (args: any) => mockDisableCreate(args),
   },
 }));
 
-jest.mock('../utils/logger', () => ({
+vi.mock('../utils/logger', () => ({
   authLogger: {
-    info: jest.fn(),
-    warn: jest.fn(),
-    error: jest.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
   },
 }));
 
 describe('useTwoFactorStatus', () => {
   beforeEach(() => {
-    jest.clearAllMocks();
+    vi.clearAllMocks();
   });
 
   describe('initial state', () => {
@@ -47,17 +51,19 @@ describe('useTwoFactorStatus', () => {
 
   describe('fetchStatus', () => {
     it('should fetch 2FA status successfully when enabled', async () => {
-      mockList.mockResolvedValue({
-        has_2fa_enabled: true,
-        devices: [
-          {
-            id: '123',
-            name: 'My Authenticator',
-            created_at: '2024-01-01T00:00:00Z',
-            last_used_at: '2024-01-02T00:00:00Z',
-            is_primary: true,
-          },
-        ],
+      mockDevicesRetrieve.mockResolvedValue({
+        data: {
+          has_2fa_enabled: true,
+          devices: [
+            {
+              id: '123',
+              name: 'My Authenticator',
+              created_at: '2024-01-01T00:00:00Z',
+              last_used_at: '2024-01-02T00:00:00Z',
+              is_primary: true,
+            },
+          ],
+        },
       });
 
       const { result } = renderHook(() => useTwoFactorStatus());
@@ -79,9 +85,11 @@ describe('useTwoFactorStatus', () => {
     });
 
     it('should fetch 2FA status successfully when disabled', async () => {
-      mockList.mockResolvedValue({
-        has_2fa_enabled: false,
-        devices: [],
+      mockDevicesRetrieve.mockResolvedValue({
+        data: {
+          has_2fa_enabled: false,
+          devices: [],
+        },
       });
 
       const { result } = renderHook(() => useTwoFactorStatus());
@@ -96,7 +104,7 @@ describe('useTwoFactorStatus', () => {
     });
 
     it('should handle fetch error', async () => {
-      mockList.mockRejectedValue(new Error('Network error'));
+      mockDevicesRetrieve.mockRejectedValue(new Error('Network error'));
 
       const { result } = renderHook(() => useTwoFactorStatus());
 
@@ -110,7 +118,7 @@ describe('useTwoFactorStatus', () => {
 
     it('should set loading state during fetch', async () => {
       let resolvePromise: (value: any) => void;
-      mockList.mockReturnValue(
+      mockDevicesRetrieve.mockReturnValue(
         new Promise((resolve) => {
           resolvePromise = resolve;
         })
@@ -129,7 +137,7 @@ describe('useTwoFactorStatus', () => {
 
       // Resolve
       await act(async () => {
-        resolvePromise!({ has_2fa_enabled: true, devices: [] });
+        resolvePromise!({ data: { has_2fa_enabled: true, devices: [] } });
         await fetchPromise;
       });
 
@@ -146,7 +154,7 @@ describe('useTwoFactorStatus', () => {
 
       // Set initial state
       await act(async () => {
-        mockList.mockResolvedValue({ has_2fa_enabled: true, devices: [] });
+        mockDevicesRetrieve.mockResolvedValue({ data: { has_2fa_enabled: true, devices: [] } });
         await result.current.fetchStatus();
       });
 
@@ -161,7 +169,8 @@ describe('useTwoFactorStatus', () => {
       expect(success!).toBe(true);
       expect(result.current.has2FAEnabled).toBe(false);
       expect(result.current.devices).toEqual([]);
-      expect(mockDisableCreate).toHaveBeenCalledWith({ code: '123456' });
+      // The hook calls cfgTotpDisableCreate({ body: { code }, throwOnError: true }).
+      expect(mockDisableCreate).toHaveBeenCalledWith({ body: { code: '123456' }, throwOnError: true });
     });
 
     it('should reject invalid code format', async () => {
@@ -207,7 +216,7 @@ describe('useTwoFactorStatus', () => {
 
   describe('clearError', () => {
     it('should clear error', async () => {
-      mockList.mockRejectedValue(new Error('Some error'));
+      mockDevicesRetrieve.mockRejectedValue(new Error('Some error'));
 
       const { result } = renderHook(() => useTwoFactorStatus());
 

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

@@ -0,0 +1,54 @@
+/**
+ * Identifier/email validation tests.
+ *
+ * Two copies of the email regex exist (utils/validation.validateEmail and
+ * hooks/useAuthValidation.validateIdentifier) and gate whether the login form
+ * lets a submit through. They must agree and must reject the usual malformed
+ * inputs (spaces, double-@, missing TLD) without being so strict they reject
+ * valid addresses (plus-tags, subdomains).
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { validateEmail } from '../utils/validation';
+import { validateIdentifier } from '../hooks/useAuthValidation';
+
+const VALID = [
+  'a@b.co',
+  'user@example.com',
+  'user.name@example.com',
+  'user+tag@example.com',
+  'user@sub.example.co.uk',
+  'USER@EXAMPLE.COM',
+  '123@numbers.io',
+];
+
+const INVALID = [
+  '',
+  'plainstring',
+  'no-at-sign.com',
+  '@no-local.com',
+  'no-domain@',
+  'no-tld@example',
+  'two@@example.com',
+  'spaces in@example.com',
+  'trailing@space.com ',
+  ' leading@space.com',
+  'new\nline@example.com',
+  'a@b@c.com',
+];
+
+describe('validateEmail (utils/validation)', () => {
+  it.each(VALID)('accepts %s', (email) => {
+    expect(validateEmail(email)).toBe(true);
+  });
+  it.each(INVALID)('rejects %j', (email) => {
+    expect(validateEmail(email)).toBe(false);
+  });
+});
+
+describe('validateIdentifier (useAuthValidation) matches validateEmail', () => {
+  it.each([...VALID, ...INVALID])('agrees on %j', (input) => {
+    expect(validateIdentifier(input)).toBe(validateEmail(input));
+  });
+});

package/src/auth/context/AuthContext.tsx

@@ -19,7 +19,8 @@ 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 { isTokenExpired, getTokenExpiry } from '../utils/jwt';
+import { nextAuthEvaluationDelay } from '../utils/guard';
 import { AccountsProvider, useAccountsContext } from './AccountsContext';
 
 import type { AuthConfig, AuthContextType, AuthProviderProps, UserProfile } from './types';
@@ -69,6 +70,31 @@ export const isSessionDeadOnBootstrap = (
   return refreshDead; // access dead + refresh dead/absent → unrecoverable
 };
 
+/**
+ * Live, network-free authentication check — the single source of truth for
+ * `isAuthenticated`. Reads the persisted tokens and validates their `exp`
+ * LOCALLY, so the answer never depends on a server 401 arriving (which CSP, a
+ * hung request, or an offline network can silently swallow).
+ *
+ * A session is alive while it is not `isSessionDeadOnBootstrap` — i.e. the
+ * access token is still valid, OR a usable refresh token exists to renew it.
+ * We deliberately do NOT require a live access token: between access expiry and
+ * the silent refresh the session is still recoverable, and flipping to
+ * "unauthenticated" there would bounce the user to /auth on every protected
+ * page. Only access-dead AND refresh-dead means truly logged out.
+ *
+ * Note: `isAuthenticated()` in the generated store only checks token PRESENCE,
+ * not expiry — this wrapper adds the expiry gate the guard needs.
+ */
+const isSessionAlive = (now = Date.now()): boolean => {
+  if (typeof window === 'undefined') return false;
+  return !isSessionDeadOnBootstrap(
+    apiAccounts.getToken(),
+    apiAccounts.getRefreshToken(),
+    now,
+  );
+};
+
 // Internal provider that uses AccountsContext
 const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config }) => {
   const accounts = useAccountsContext();
@@ -108,6 +134,27 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
   const [authTick, setAuthTick] = useState(0);
   const bumpAuthTick = useCallback(() => setAuthTick((t) => t + 1), []);
 
+  // Time-driven re-evaluation of `isAuthenticated`. Because the flag is derived
+  // from token `exp` (not from a server event), a session can silently expire
+  // while the tab sits open — with nothing to trigger a recompute. So we arm a
+  // timer for the next moment the answer could change: whichever of the access
+  // / refresh tokens expires next. When it fires we bump the tick; the memo
+  // recomputes; the guard flips to unauthenticated and redirects — no 401 (and
+  // thus no CSP/offline dependency) required. Re-armed whenever tokens change
+  // (authTick) so a fresh refresh pushes the deadline out.
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const delay = nextAuthEvaluationDelay(
+      getTokenExpiry(apiAccounts.getToken()),
+      getTokenExpiry(apiAccounts.getRefreshToken()),
+      Date.now(),
+    );
+    if (delay === null) return; // nothing live to expire
+    // setTimeout caps at ~24.8 days; clamp so a far-future refresh doesn't overflow.
+    const timer = setTimeout(bumpAuthTick, Math.min(delay, 2_000_000_000));
+    return () => clearTimeout(timer);
+  }, [authTick, bumpAuthTick]);
+
   // 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.
@@ -701,10 +748,13 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
     () => ({
       user,
       isLoading,
-      // 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(),
+      // Authenticated iff the session is locally alive (access valid OR a usable
+      // refresh token) — validated by `exp`, NOT by mere token presence. This is
+      // what makes the guard self-sufficient: an expired session reads as
+      // unauthenticated WITHOUT waiting for a server 401 (which CSP / a hung
+      // request / offline can swallow). `authTick` (in deps) forces recompute
+      // after tokens are cleared/set, since token state lives in storage.
+      isAuthenticated: isSessionAlive(),
       isAdminUser,
       loadCurrentProfile,
       checkAuthAndRedirect,

package/src/auth/hooks/useAutoAuth.ts

@@ -5,6 +5,7 @@ import { useEffect, useRef } from 'react';
 
 import { AUTH_CONSTANTS } from '../constants';
 import { authLogger } from '../utils/logger';
+import { isAllowedAuthPath } from '../utils/path';
 import { useCfgRouter } from './useCfgRouter';
 import { useQueryParams } from './useQueryParams';
 
@@ -16,21 +17,11 @@ export interface UseAutoAuthOptions {
   allowedPaths?: string[];
 }
 
-/**
- * Strip a leading 2-letter locale segment and any trailing slash so paths
- * compare consistently regardless of the next-intl locale prefix.
- * e.g. '/ru/auth/' -> '/auth', '/auth' -> '/auth', '/' -> '/'
- */
-const normalizePath = (path: string | null): string => {
-  if (!path) return '';
-  const withoutLocale = path.replace(/^\/[a-z]{2}(?=\/|$)/, '');
-  const trimmed = withoutLocale.replace(/\/+$/, '');
-  return trimmed || '/';
-};
-
 /**
  * Hook for automatic authentication from URL query parameters
- * Detects OTP from URL and triggers callback
+ * Detects OTP from URL and triggers callback.
+ * (Path normalization / allow-list matching live in ../utils/path so they can
+ * be unit-tested independently of the hook.)
  */
 export const useAutoAuth = (options: UseAutoAuthOptions = {}) => {
   const { onOTPDetected, cleanupUrl = true, allowedPaths = ['/auth'] } = options;
@@ -40,10 +31,7 @@ export const useAutoAuth = (options: UseAutoAuthOptions = {}) => {
 
   // Check if current path is in allowed paths, ignoring the locale prefix
   // (next-intl may keep it in the URL, e.g. /ru/auth) and trailing slashes.
-  const normalizedPath = normalizePath(pathname);
-  const isAllowedPath = allowedPaths.some(
-    path => normalizedPath === path || normalizedPath.startsWith(path + '/')
-  );
+  const isAllowedPath = isAllowedAuthPath(pathname, allowedPaths);
 
   const queryOtp = queryParams.get('otp') || '';
   const queryEmail = queryParams.get('email') || undefined;

package/src/auth/utils/guard.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure auth-guard state resolution.
+ *
+ * This is the decision that produced the "stuck on Authenticating…" bug: given
+ * the auth state, should the UI show a preloader, redirect to login, or render
+ * the protected content? Extracted from useAuthGuard (which lives in a package
+ * with no test infra) so the branching can be unit-tested in isolation — the
+ * hook just wires React state (mounted / isRedirecting) into these functions.
+ *
+ * Invariant that fixes the bug: once auth is resolved (`authLoading === false`)
+ * and the user is unauthenticated, `isLoading` must become false so the guard
+ * redirects to the form instead of spinning forever.
+ */
+
+export interface GuardInput {
+  /** First client render matches SSR (preloader) until mounted, to avoid hydration mismatch. */
+  mounted: boolean;
+  /** Whether this route requires authentication. */
+  requireAuth: boolean;
+  /** AuthContext still resolving initial state. */
+  authLoading: boolean;
+  /** A redirect to the auth page is in flight. */
+  isRedirecting: boolean;
+  /** User currently has a (valid-looking) session. */
+  isAuthenticated: boolean;
+}
+
+/**
+ * True while the guard should render a preloader rather than the protected
+ * content. Mirrors useAuthGuard's formula exactly.
+ */
+export function resolveGuardIsLoading(s: GuardInput): boolean {
+  if (!s.mounted) return true; // pre-hydration: always preloader
+  if (!s.requireAuth) return false; // public route: never blocks
+  return s.authLoading || s.isRedirecting || !s.isAuthenticated;
+}
+
+/**
+ * Whether the guard should trigger a redirect to the auth page. Only once
+ * mounted, on a protected route, after auth resolved, when unauthenticated and
+ * not already redirecting. This is the branch that must fire for a dead session.
+ */
+export function shouldRedirectToAuth(s: GuardInput): boolean {
+  return (
+    s.mounted &&
+    s.requireAuth &&
+    !s.authLoading &&
+    !s.isAuthenticated &&
+    !s.isRedirecting
+  );
+}
+
+/** The effective authenticated flag the guard exposes to consumers. */
+export function resolveGuardIsAuthenticated(s: Pick<GuardInput, 'requireAuth' | 'isAuthenticated'>): boolean {
+  return !s.requireAuth || s.isAuthenticated;
+}
+
+/**
+ * Delay (ms from `now`) until `isAuthenticated` should next be re-evaluated,
+ * given the access/refresh expiry timestamps (ms epoch, or null if absent).
+ *
+ * `isAuthenticated` is derived from token `exp`, so it can change with no event
+ * to trigger a recompute — a tab left open silently crosses an expiry boundary.
+ * We schedule a wake-up at the SOONEST future expiry (the next moment the answer
+ * could flip), plus a 1s cushion so we re-check strictly after the inclusive
+ * boundary. Returns null when nothing live remains to expire (no timer needed).
+ * Callers should clamp the result to the platform setTimeout ceiling.
+ */
+export function nextAuthEvaluationDelay(
+  accessExp: number | null,
+  refreshExp: number | null,
+  now: number,
+): number | null {
+  const future = [accessExp, refreshExp].filter(
+    (d): d is number => d !== null && d > now,
+  );
+  if (future.length === 0) return null;
+  return Math.max(0, Math.min(...future) - now) + 1000;
+}