@djangocfg/api 2.1.619 → 2.1.621

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.619",
+  "version": "2.1.621",
   "description": "Auto-generated TypeScript API client with React hooks, SWR integration, and Zod validation for Django REST Framework backends",
   "keywords": [
     "django",
@@ -91,7 +91,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.619",
+    "@djangocfg/typescript-config": "^2.1.621",
     "@testing-library/react": "^16.3.3",
     "@types/node": "^25.9.5",
     "@types/react": "19.3.0",

package/src/_api/generated/helpers/auth.ts

@@ -16,6 +16,25 @@ const storage = 'cfg' === 'cfg' ? cfgStorage : createStorage('cfg');
 
 const isBrowser = typeof window !== 'undefined';
 
+/**
+ * Auth trace hook. The reader lives in `@djangocfg/api` (`auth/trace.ts`) and installs `globalThis.__cfgAuthTrace`;
+ * until it does, events queue on `globalThis` so none are lost. Never pass a token, a code or an address.
+ */
+type TraceFields = Record<string, string | number | boolean | null>;
+function trace(ev: string, fields?: TraceFields): void {
+  try {
+    const g = globalThis as Record<string, unknown>;
+    const sink = g.__cfgAuthTrace as ((e: string, f?: TraceFields) => void) | undefined;
+    if (sink) { sink(ev, fields); return; }
+    const queue = (g.__cfgAuthTraceQ as unknown[] | undefined) ?? [];
+    g.__cfgAuthTraceQ = queue;
+    if (queue.length < 100) queue.push([Date.now(), ev, fields]);
+  } catch { /* tracing never breaks auth */ }
+}
+function pathOf(url: string): string {
+  try { return new URL(url, 'http://x').pathname; } catch { return ''; }
+}
+
 export type StorageMode = 'localStorage' | 'sessionStorage' | 'cookie';
 
 // ── Storage backends (browser-only; server-side reads return null) ─────────
@@ -281,7 +300,7 @@ function notifySessionChanged(): void {
   const changed =
     next.status !== _snapshot.status ||
     next.accessExpiresAt !== _snapshot.accessExpiresAt;
-  if (changed) _snapshot = next;
+  if (changed) { _snapshot = next; trace('store.snapshot', { status: next.status }); }
   scheduleExpiryFlip();
   if (!changed) return;
   for (const listener of Array.from(_sessionListeners)) {
@@ -418,15 +437,18 @@ export const auth = {
   // ── Bearer token ──────────────────────────────────────────────────
   getToken(): string | null { return _storage.get(ACCESS_KEY); },
   setToken(token: string | null): void {
+    trace('store.setToken', { present: token !== null });
     _storage.set(ACCESS_KEY, token);
     notifySessionChanged();
   },
   getRefreshToken(): string | null { return _storage.get(REFRESH_KEY); },
   setRefreshToken(token: string | null): void {
+    trace('store.setRefreshToken', { present: token !== null });
     _storage.set(REFRESH_KEY, token);
     notifySessionChanged();
   },
   clearTokens(): void {
+    trace('store.clearTokens');
     // Clear every backend, not just the active one. Sign-out must leave nothing
     // behind anywhere — including tokens an older build stranded in
     // sessionStorage — or the next page load could resurrect a dead session.
@@ -452,6 +474,7 @@ export const auth = {
    * rotation); `refresh: null` explicitly drops it.
    */
   setSession(tokens: { access: string; refresh?: string | null }): void {
+    trace('store.setSession', { refresh: tokens.refresh === undefined ? 'kept' : tokens.refresh === null ? 'dropped' : 'set' });
     _storage.set(ACCESS_KEY, tokens.access);
     if (tokens.refresh !== undefined) _storage.set(REFRESH_KEY, tokens.refresh);
     notifySessionChanged();
@@ -603,7 +626,8 @@ async function tryRefresh(): Promise<string | null> {
     const refresh = auth.getRefreshToken();
     if (!refresh) return null;
     const result = await _refreshHandler!(refresh);
-    if (!result?.access) return null;
+    if (!result?.access) { trace('refresh', { ok: false, why: 'no-access' }); return null; }
+    trace('refresh', { ok: true, rotated: Boolean(result.refresh) });
     auth.setToken(result.access);
     if (result.refresh) auth.setRefreshToken(result.refresh);
     return result.access;
@@ -621,6 +645,7 @@ async function tryRefresh(): Promise<string | null> {
       }
       return await runRefresh();
     } catch {
+      trace('refresh', { ok: false, why: 'threw' });
       return null;
     } finally {
       _refreshInflight = null;
@@ -637,7 +662,8 @@ async function tryRefresh(): Promise<string | null> {
  * `onUnauthorized` slot. Apps only route to login; they never own the
  * clear-before-redirect ordering.
  */
-function expireSession(response: Response): void {
+function expireSession(response: Response, why: string): void {
+  trace('store.expire', { why, status: response.status, path: pathOf(response.url), handlers: _sessionExpiredHandlers.size });
   auth.clearTokens();
   for (const cb of Array.from(_sessionExpiredHandlers)) {
     try { cb(response); } catch {}
@@ -852,18 +878,19 @@ export function installAuthOnClient(client: HeyClient): void {
     // A refusal from the sign-in endpoints themselves (wrong OTP / password, bad OAuth code) is a credential error, not
     // a dead session: expiring here reloads the sign-in page and wipes the error the user is reading.
     if (/\/accounts\/(otp|oauth|login|register|token)\b/.test(request.url)) {
+      trace('401.passthrough', { path: pathOf(request.url) });
       return response;
     }
 
     // Already retried once — give up to avoid loops.
     if (request.headers.get(RETRY_MARKER)) {
-      expireSession(response);
+      expireSession(response, 'retry-marker');
       return response;
     }
 
     const newToken = await tryRefresh();
     if (!newToken) {
-      expireSession(response);
+      expireSession(response, 'refresh-failed');
       return response;
     }
 
@@ -881,7 +908,7 @@ export function installAuthOnClient(client: HeyClient): void {
     }
     try {
       const retried = await fetch(retry);
-      if (retried.status === 401) expireSession(retried);
+      if (retried.status === 401) expireSession(retried, 'retry-401');
       return retried;
     } catch {
       // Network error on the retry. The refresh SUCCEEDED (we hold a fresh

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

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveAuthStatus, type AuthStateInput } from '../utils/authState';
+
+const base: AuthStateInput = {
+  clientReady: true,
+  snapshotAuthenticated: false,
+  storeAuthenticated: false,
+  profileSettled: false,
+  timedOut: false,
+};
+const at = (over: Partial<AuthStateInput>) => resolveAuthStatus({ ...base, ...over });
+
+describe('resolveAuthStatus', () => {
+  it('is resolving until the client has read the session (hydration commit)', () => {
+    expect(at({ clientReady: false })).toBe('resolving');
+    expect(at({ clientReady: false, snapshotAuthenticated: true, storeAuthenticated: true, profileSettled: true })).toBe('resolving');
+  });
+
+  it('is anonymous when store and snapshot both say signed out', () => {
+    expect(at({})).toBe('anonymous');
+  });
+
+  it('is authenticated once the profile settled', () => {
+    expect(at({ snapshotAuthenticated: true, storeAuthenticated: true, profileSettled: true })).toBe('authenticated');
+  });
+
+  it('is resolving while a live session loads its profile', () => {
+    expect(at({ snapshotAuthenticated: true, storeAuthenticated: true })).toBe('resolving');
+  });
+
+  it('waits while the snapshot lags behind the store', () => {
+    expect(at({ snapshotAuthenticated: false, storeAuthenticated: true })).toBe('resolving');
+  });
+
+  it('never stays resolving once the timer fired', () => {
+    expect(at({ snapshotAuthenticated: true, storeAuthenticated: true, timedOut: true })).toBe('authenticated');
+    expect(at({ snapshotAuthenticated: false, storeAuthenticated: true, timedOut: true })).toBe('anonymous');
+  });
+
+  it('terminates for every input once clientReady and timedOut', () => {
+    for (const snap of [true, false]) for (const store of [true, false]) for (const prof of [true, false]) {
+      expect(at({ snapshotAuthenticated: snap, storeAuthenticated: store, profileSettled: prof, timedOut: true })).not.toBe('resolving');
+    }
+  });
+});

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

@@ -67,6 +67,13 @@ describe('resolveAuthError — transport strings never reach the UI', () => {
     expect(key).toBe(AUTH_ERROR_KEYS.serverUnavailable);
   });
 
+  it('HTTP 0 (no response: network, CORS, API restarting) is a network error, not "HTTP 0:"', () => {
+    const { message, key } = resolveAuthError({ message: 'HTTP 0: ', statusCode: 0, name: 'APIError' });
+
+    expect(message).not.toMatch(/HTTP/);
+    expect(key).toBe(AUTH_ERROR_KEYS.networkError);
+  });
+
   it('rejects it even when statusText filled it in', () => {
     expect(formatAuthError({ message: 'HTTP 500: Internal Server Error', statusCode: 500 }))
       .not.toMatch(/HTTP/);

package/src/auth/context/AccountsContext.tsx

@@ -60,6 +60,7 @@ import type {
     PasswordLoginRequest,
     PasswordLoginResponse,
 } from '../../_api/generated/_cfg_accounts/types.gen';
+import { authTrace } from '../trace';
 
 export type { PatchedCfgUserUpdateRequest, User, CfgUserUpdateRequest as UserProfileUpdateRequest };
 
@@ -216,6 +217,7 @@ export function AccountsProvider({ children }: AccountsProviderProps) {
       // Storage is always localStorage: session length is the token lifetime
       // the server chose. A sessionStorage switch would strand the tokens — the
       // module reinitializes to localStorage on the next page load.
+      authTrace('accounts.otp.session');
       auth.setSession({ access: result.access, refresh: result.refresh });
       try {
         await refreshProfile({ callerId, force: true });
@@ -251,6 +253,7 @@ export function AccountsProvider({ children }: AccountsProviderProps) {
         authLogger.warn('Refresh-token blacklist failed (logged out locally anyway)');
       });
     }
+    authTrace('accounts.logout');
     auth.clearSession();
     setProfile(undefined);
     setProfileError(null);

package/src/auth/context/AuthContext.tsx

@@ -38,6 +38,8 @@ import { purgeLegacyTokenStorage } from '../hooks/legacyStorage';
 import { useAuthRedirectManager } from '../hooks/useAuthRedirect';
 import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
 import { formatAuthError, logAuthFailure } from '../utils/errors';
+import { resolveAuthStatus } from '../utils/authState';
+import { authTrace } from '../trace';
 import { isDev, isBrowser } from '../utils/env';
 import { authLogger } from '../utils/logger';
 import { AccountsProvider, useAccountsContext } from './AccountsContext';
@@ -143,19 +145,17 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
       const hasTokens = Boolean(auth.getToken() || auth.getRefreshToken());
       if (hasTokens && !auth.isAuthenticated()) {
         authLogger.warn('Dead session in storage — clearing');
+        authTrace('bootstrap.purge', { why: 'dead-tokens' });
         auth.clearSession();
         clearProfileCache();
       } else if (!hasTokens && !auth.isAuthenticated()) {
         // No session at all: a leftover profile cache and the old localStorage tokens (pre-cookie auth) must not keep
         // the private UI alive. Drop them; the page's own guard then sends the user to /auth.
+        authTrace('bootstrap.purge', { why: 'no-session' });
         clearProfileCache();
         purgeLegacyTokenStorage();
         if (accountsRef.current.profile) accountsRef.current.logout();
       }
-      // The hydration commit serves the SERVER snapshot ('anonymous') even when the store holds a live session. Settling
-      // now would let the page guard read "loaded and signed out" and bounce to /auth; the snapshot flips on the next
-      // render and this effect runs again with the real value.
-      if (auth.isAuthenticated()) return;
       setProfileSettled(true);
       return;
     }
@@ -164,6 +164,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
       return;
     }
     profileAttemptedRef.current = true;
+    authTrace('bootstrap.profile.start');
     let cancelled = false;
     accountsRef.current
       .refreshProfile({ callerId: 'AuthProvider:bootstrap' })
@@ -172,6 +173,9 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
         // onSessionExpired funnel below. Anything else (network, 5xx) keeps
         // the session — the user can retry.
         authLogger.warn('Profile load failed (session kept):', error);
+        authTrace('bootstrap.profile.failed', {
+          status: error instanceof APIError ? error.statusCode : 0,
+        });
       })
       .finally(() => {
         if (!cancelled) setProfileSettled(true);
@@ -183,15 +187,56 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
 
   const isLoading = !profileSettled;
 
+  // ── The one linear state ───────────────────────────────────────────────────
+  // clientReady: the hydration commit is over (the server snapshot is always 'anonymous', so before this the
+  // snapshot proves nothing). timedOut: ONE safety timer, so 'resolving' always ends.
+  const [clientReady, setClientReady] = useState(false);
+  const [timedOut, setTimedOut] = useState(false);
+  useEffect(() => {
+    setClientReady(true);
+    const timer = setTimeout(() => setTimedOut(true), 8000);
+    return () => clearTimeout(timer);
+  }, []);
+  const status = resolveAuthStatus({
+    clientReady,
+    snapshotAuthenticated: isAuthenticated,
+    storeAuthenticated: isBrowser ? auth.isAuthenticated() : false,
+    profileSettled,
+    timedOut,
+  });
+  const lastStatusRef = useRef<string>('');
+  useEffect(() => {
+    if (lastStatusRef.current === status) return;
+    lastStatusRef.current = status;
+    authTrace('status', {
+      status,
+      snapshot: isAuthenticated,
+      store: auth.isAuthenticated(),
+      profileSettled,
+      timedOut,
+      path: pathname ?? '',
+    });
+  }, [status, isAuthenticated, profileSettled, timedOut, pathname]);
+  useEffect(() => {
+    (globalThis as Record<string, unknown>).__cfgAuthNow = () => ({
+      status,
+      snapshot: isAuthenticated,
+      store: auth.isAuthenticated(),
+      hasToken: Boolean(auth.getToken()),
+      hasRefresh: Boolean(auth.getRefreshToken()),
+      profileSettled,
+      timedOut,
+    });
+  }, [status, isAuthenticated, profileSettled, timedOut]);
+
   // ── The ONE exit: terminal 401 → login ─────────────────────────────────────
   // The store has already cleared the session before this fires (subscribers
   // flipped to 'anonymous'), so the handler only routes. Registration returns
   // its own unsubscribe — StrictMode double-mounts compose instead of racing.
-  const expiredHandledRef = useRef(false);
+  // One hard navigation per page is enforced in useCfgRouter, so no per-handler dedupe flag is needed.
   useEffect(() => {
     const unsubscribe = auth.onSessionExpired(() => {
-      if (expiredHandledRef.current) return;
-      expiredHandledRef.current = true;
+      authTrace('expired.handler', { path: pathname ?? '' });
       authLogger.warn('Session expired (terminal 401) — redirecting to login');
       clearProfileCache();
       Analytics.event(AnalyticsEvent.AUTH_SESSION_EXPIRED, {
@@ -200,7 +245,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
       router.hardReplace(routesRef.current.defaultAuthCallback);
     });
     return unsubscribe;
-  }, [router]);
+  }, [router, pathname]);
 
   // ── Redirect authenticated users away from the auth page ──────────────────
   // Stands down while a login flow on this page owns navigation (success
@@ -212,6 +257,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
     if (pathname === routes.auth && !queryParams.get('flow')) {
       const saved = redirectManager.hasRedirect() ? redirectManager.getRedirect() : null;
       if (saved) redirectManager.clearRedirect();
+      authTrace('leave-auth', { to: saved || routes.defaultCallback, saved: Boolean(saved) });
       router.push(saved || routes.defaultCallback);
     }
   }, [isAuthenticated, pathname, queryParams, routes, router, redirectManager]);
@@ -245,6 +291,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
   const requestOTP = useCallback(
     async (identifier: string, sourceUrl?: string, consent?: OTPRequestConsent): Promise<OTPRequestResult> => {
       // A login attempt invalidates whatever session was lying around.
+      authTrace('otp.request');
       auth.clearSession();
 
       try {
@@ -311,6 +358,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
         // The caller opting out of redirect commits to handling ALL navigation
         // for this login — including the 2FA continuation and success screen.
         pendingManualNavRef.current = Boolean(skipRedirect);
+        authTrace('otp.verify', { skipRedirect: Boolean(skipRedirect) });
 
         const result = await accountsRef.current.verifyOTP({
           identifier,
@@ -394,6 +442,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
         // The caller opting out of redirect commits to handling ALL navigation
         // for this login — including the 2FA continuation and success screen.
         pendingManualNavRef.current = Boolean(skipRedirect);
+        authTrace('password.login', { skipRedirect: Boolean(skipRedirect) });
 
         const result = await accountsRef.current.loginWithPassword({
           email,
@@ -487,6 +536,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
   }, []);
 
   const logout = useCallback((): void => {
+    authTrace('logout');
     Analytics.event(AnalyticsEvent.AUTH_LOGOUT, {
       category: AnalyticsCategory.AUTH,
     });
@@ -528,6 +578,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
     () => ({
       user,
       isLoading,
+      status,
       // Reactive: flips via the store snapshot (token writes, refreshes,
       // expiry timer, cross-tab/cross-store sync) — no ticks, no polling.
       isAuthenticated,
@@ -555,6 +606,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
     [
       user,
       isLoading,
+      status,
       isAuthenticated,
       isAdminUser,
       routes,
@@ -600,6 +652,7 @@ export const AuthProvider = memo(AuthProviderRaw);
 const defaultAuthState: AuthContextType = {
   user: null,
   isLoading: false,
+  status: 'anonymous',
   isAuthenticated: false,
   isAdminUser: false,
   routes: resolveAuthRoutes(),

package/src/auth/context/types.ts

@@ -37,6 +37,8 @@ export interface ResolvedAuthRoutes {
 export interface AuthContextType {
   user: UserProfile | null;
   isLoading: boolean;
+  /** The one linear auth state: 'resolving' until the client has read the session and its profile, then 'authenticated' or 'anonymous'. */
+  status: 'resolving' | 'authenticated' | 'anonymous';
   isAuthenticated: boolean;
   isAdminUser: boolean;
   /** Resolved route conventions (config override or framework default). */

package/src/auth/hooks/useCfgRouter.ts

@@ -18,6 +18,23 @@
 import { useRouter as useNextRouter } from 'next/navigation';
 import { useCallback, useMemo } from 'react';
 
+import { authTrace } from '../trace';
+
+/**
+ * A hard navigation unloads the page. Once one is in flight, a second one (two 401s, the guard and an effect, a double
+ * click) is dropped: the first decides. Reset when the page is restored from the back/forward cache.
+ */
+let hardNavigating = false;
+if (typeof window !== 'undefined') {
+  window.addEventListener('pageshow', (e) => {
+    if (e.persisted) hardNavigating = false;
+  });
+}
+
+function fromPath(): string {
+  return typeof window === 'undefined' ? '' : window.location.pathname;
+}
+
 /**
  * Get base path from environment variable
  */
@@ -67,6 +84,7 @@ export function useCfgRouter() {
   const basePath = useMemo(() => getBasePath(), []);
 
   const push = useCallback((href: string, options?: { scroll?: boolean }) => {
+    authTrace('nav.push', { from: fromPath(), to: href });
     if (basePath) {
       // App Router doesn't handle basePath automatically, use window.location
       window.location.href = withBasePath(href, basePath);
@@ -77,6 +95,7 @@ export function useCfgRouter() {
   }, [router, basePath]);
 
   const replace = useCallback((href: string, options?: { scroll?: boolean }) => {
+    authTrace('nav.replace', { from: fromPath(), to: href });
     if (basePath) {
       // App Router doesn't handle basePath automatically, use window.location
       window.location.replace(withBasePath(href, basePath));
@@ -100,6 +119,12 @@ export function useCfgRouter() {
    * ```
    */
   const hardPush = useCallback((href: string) => {
+    if (hardNavigating) {
+      authTrace('nav.hardPush.ignored', { from: fromPath(), to: href });
+      return;
+    }
+    hardNavigating = true;
+    authTrace('nav.hardPush', { from: fromPath(), to: href });
     window.location.href = withBasePath(href, basePath);
   }, [basePath]);
 
@@ -116,6 +141,12 @@ export function useCfgRouter() {
    * ```
    */
   const hardReplace = useCallback((href: string) => {
+    if (hardNavigating) {
+      authTrace('nav.hardReplace.ignored', { from: fromPath(), to: href });
+      return;
+    }
+    hardNavigating = true;
+    authTrace('nav.hardReplace', { from: fromPath(), to: href });
     window.location.replace(withBasePath(href, basePath));
   }, [basePath]);
 

package/src/auth/hooks/useOAuthLogin.ts

@@ -16,6 +16,7 @@ import { authLogger } from '../utils/logger';
 import { type OAuthFailureCode, type OAuthProviderId, readOAuthFailure } from '../utils/oauthErrors';
 import { consumeSavedRedirect } from './useAuthRedirect';
 import { useCfgRouter } from './useCfgRouter';
+import { authTrace } from '../trace';
 
 /**
  * The user payload as the OAuth endpoint declares it.
@@ -138,6 +139,7 @@ export const useOAuthLogin = (options: UseOAuthLoginOptions = {}): UseOAuthLogin
     setErrorCode(null);
     // Match the OTP flow: a new login must not leave an older persistent
     // session available after this browser is intentionally made session-only.
+    authTrace('oauth.start');
     auth.clearSession();
 
     try {
@@ -200,6 +202,7 @@ export const useOAuthLogin = (options: UseOAuthLoginOptions = {}): UseOAuthLogin
       }
 
       // The ONE write path — atomic pair + session notification.
+      authTrace('oauth.session');
       auth.setSession({ access: response.access, refresh: response.refresh });
 
       Analytics.event(AnalyticsEvent.AUTH_LOGIN_SUCCESS, {

package/src/auth/hooks/useTwoFactorVerify.ts

@@ -11,6 +11,7 @@ import { formatAuthError, logAuthFailure } from '../utils/errors';
 import { consumeSavedRedirect } from './useAuthRedirect';
 import { useCfgRouter } from './useCfgRouter';
 import { extractAttemptsRemaining, isValidTotpCode } from './twoFactor.shared';
+import { authTrace } from '../trace';
 
 export interface UseTwoFactorVerifyOptions {
   /** Callback on successful 2FA verification */
@@ -71,6 +72,7 @@ export const useTwoFactorVerify = (
     // Save tokens — the ONE write path (atomic pair + session notification).
     // Storage is always localStorage; session length is the server's call.
     // See AccountsContext.verifyOTP.
+    authTrace('2fa.session');
     auth.setSession({ access: response.access_token, refresh: response.refresh_token });
 
     if (response.warning) {

package/src/auth/index.ts

@@ -27,6 +27,9 @@
 // Constants
 export * from './constants';
 
+// Persisted auth trace: `authTrace(ev, fields)` and the readers behind `window.__cfgAuth`.
+export * from './trace';
+
 // Contexts
 export * from './context';