@djangocfg/api 2.1.449 → 2.1.452

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,6 +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, getTokenExpiry } from '../utils/jwt';
+import { nextAuthEvaluationDelay } from '../utils/guard';
 import { AccountsProvider, useAccountsContext } from './AccountsContext';
 
 import type { AuthConfig, AuthContextType, AuthProviderProps, UserProfile } from './types';
@@ -41,6 +43,58 @@ 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
+};
+
+/**
+ * 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();
@@ -69,6 +123,43 @@ 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), []);
+
+  // 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.
+  const onUnauthorizedRef = useRef(false);
+
   const router = useCfgRouter();
   const pathname = usePathname();
   const queryParams = useQueryParams();
@@ -76,17 +167,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 +199,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 +254,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 +385,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,8 +748,13 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
     () => ({
       user,
       isLoading,
-      // Consider authenticated if we have valid tokens, even without user profile
-      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,
@@ -622,6 +779,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/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;