@djangocfg/api 2.1.449 → 2.1.452

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.449",
+  "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.449",
+    "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__/jwt.test.ts

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