@djangocfg/api 2.1.580 → 2.1.581

package/dist/clients.d.cts

@@ -863,6 +863,14 @@ type OtpRequestResponse = {
      * Webmail deep-link for the recipient's provider, or null if the domain is unknown.
      */
     webmail?: WebmailLink | null;
+    /**
+     * Seconds until a new code may be requested for this email.
+     */
+    resend_in?: number;
+    /**
+     * Seconds the code stays valid.
+     */
+    expires_in?: number;
 };
 /**
  * Serializer for OTP verification.

package/dist/clients.d.ts

@@ -863,6 +863,14 @@ type OtpRequestResponse = {
      * Webmail deep-link for the recipient's provider, or null if the domain is unknown.
      */
     webmail?: WebmailLink | null;
+    /**
+     * Seconds until a new code may be requested for this email.
+     */
+    resend_in?: number;
+    /**
+     * Seconds the code stays valid.
+     */
+    expires_in?: number;
 };
 /**
  * Serializer for OTP verification.

package/dist/index.d.cts

@@ -1009,6 +1009,14 @@ type OtpRequestResponse = {
      * Webmail deep-link for the recipient's provider, or null if the domain is unknown.
      */
     webmail?: WebmailLink | null;
+    /**
+     * Seconds until a new code may be requested for this email.
+     */
+    resend_in?: number;
+    /**
+     * Seconds the code stays valid.
+     */
+    expires_in?: number;
 };
 /**
  * Serializer for OTP verification.

package/dist/index.d.ts

@@ -1009,6 +1009,14 @@ type OtpRequestResponse = {
      * Webmail deep-link for the recipient's provider, or null if the domain is unknown.
      */
     webmail?: WebmailLink | null;
+    /**
+     * Seconds until a new code may be requested for this email.
+     */
+    resend_in?: number;
+    /**
+     * Seconds the code stays valid.
+     */
+    expires_in?: number;
 };
 /**
  * Serializer for OTP verification.

package/package.json

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

package/src/_api/generated/_cfg_accounts/openapi.json

@@ -1730,6 +1730,16 @@
               }
             ],
             "description": "Webmail deep-link for the recipient's provider, or null if the domain is unknown."
+          },
+          "resend_in": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Seconds until a new code may be requested for this email."
+          },
+          "expires_in": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Seconds the code stays valid."
           }
         },
         "required": [

package/src/_api/generated/_cfg_accounts/schemas/OTPRequestResponse.ts

@@ -8,6 +8,8 @@ import { WebmailLinkSchema } from "./WebmailLink";
 export const OTPRequestResponseSchema = z.object({
   message: z.string(),
   webmail: WebmailLinkSchema.nullable().optional(),
+  resend_in: z.number().int().min(0).optional(),
+  expires_in: z.number().int().min(0).optional(),
 });
 
 export type OTPRequestResponse = z.infer<typeof OTPRequestResponseSchema>;

package/src/_api/generated/openapi.json

@@ -2365,6 +2365,16 @@
               }
             ],
             "description": "Webmail deep-link for the recipient's provider, or null if the domain is unknown."
+          },
+          "resend_in": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Seconds until a new code may be requested for this email."
+          },
+          "expires_in": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Seconds the code stays valid."
           }
         },
         "required": [

package/src/_api/generated/types.gen.ts

@@ -522,6 +522,14 @@ export type OtpRequestResponse = {
      * Webmail deep-link for the recipient's provider, or null if the domain is unknown.
      */
     webmail?: WebmailLink | null;
+    /**
+     * Seconds until a new code may be requested for this email.
+     */
+    resend_in?: number;
+    /**
+     * Seconds the code stays valid.
+     */
+    expires_in?: number;
 };
 
 /**

package/src/auth/__tests__/twoFactorChallenge.test.tsx

@@ -0,0 +1,37 @@
+// @vitest-environment jsdom
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  beginTwoFactorChallenge,
+  endTwoFactorChallenge,
+  useTwoFactorChallenge,
+} from '../hooks/useTwoFactorChallenge';
+
+describe('twoFactorChallenge', () => {
+  afterEach(() => act(() => endTwoFactorChallenge()));
+
+  it('starts with no challenge', () => {
+    const { result } = renderHook(() => useTwoFactorChallenge());
+    expect(result.current).toBeNull();
+  });
+
+  it('publishes a begun challenge to every subscriber', () => {
+    const a = renderHook(() => useTwoFactorChallenge());
+    const b = renderHook(() => useTwoFactorChallenge());
+
+    act(() => beginTwoFactorChallenge({ sessionId: 's-1' }));
+
+    expect(a.result.current).toEqual({ sessionId: 's-1' });
+    expect(b.result.current).toEqual({ sessionId: 's-1' });
+  });
+
+  it('clears the challenge when it ends', () => {
+    const { result } = renderHook(() => useTwoFactorChallenge());
+
+    act(() => beginTwoFactorChallenge({ sessionId: 's-1' }));
+    act(() => endTwoFactorChallenge());
+
+    expect(result.current).toBeNull();
+  });
+});

package/src/auth/constants.ts

@@ -10,6 +10,8 @@ export const AUTH_CONSTANTS = {
   TOTP_LENGTH: 6,
   /** Backup code max length. */
   BACKUP_CODE_MAX_LENGTH: 12,
+  /** Resend cooldown (s) when the server does not state one. Mirrors the backend per-email cooldown. */
+  RESEND_COOLDOWN_SECONDS: 30,
 } as const;
 
 // Route conventions are NOT exported here on purpose. The '/auth' and '/'

package/src/auth/context/AuthContext.tsx

@@ -257,6 +257,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
           success: true,
           message: result.message || 'OTP code sent to your email address',
           webmail: result.webmail ?? null,
+          resendIn: result.resend_in,
         };
       } catch (error) {
         logAuthFailure(authLogger, 'Request OTP failed:', error);

package/src/auth/hooks/index.ts

@@ -38,6 +38,14 @@ export {
   type TwoFactorDevice,
 } from './useTwoFactor';
 
+// 2FA challenge handoff between the sign-in step and the challenge dialog
+export {
+  beginTwoFactorChallenge,
+  endTwoFactorChallenge,
+  useTwoFactorChallenge,
+  type TwoFactorChallenge,
+} from './useTwoFactorChallenge';
+
 // Auth guards and redirects
 export {
   consumeSavedRedirect,

package/src/auth/hooks/useAuthForm.ts

@@ -8,7 +8,7 @@ import { authLogger } from '../utils/logger';
 import { useAuthFormState } from './useAuthFormState';
 import { useAuthValidation } from './useAuthValidation';
 import { useAutoAuth } from './useAutoAuth';
-import { useTwoFactorVerify } from './useTwoFactorVerify';
+import { beginTwoFactorChallenge } from './useTwoFactorChallenge';
 
 import type { AuthFormReturn, UseAuthFormOptions } from '../types';
 /**
@@ -56,38 +56,17 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
     acceptedTerms,
     marketingConsent,
     rememberMe,
-    twoFactorSessionId,
-    twoFactorCode,
-    useBackupCode,
     setIdentifier,
     setOtp,
     setStep,
     setError,
     setIsLoading,
     clearError,
-    setTwoFactorSessionId,
-    setShouldPrompt2FA,
-    setTwoFactorCode,
-    setUseBackupCode,
     startRateLimitCountdown,
+    startResendCountdown,
     setWebmail,
   } = formState;
 
-  // 2FA verification hook - skip redirect so we can show success screen
-  const twoFactor = useTwoFactorVerify({
-    onSuccess: () => {
-      authLogger.info('2FA verification successful, showing success screen');
-      setStep('success');
-      onOTPSuccess?.();
-    },
-    onError: (error) => {
-      setError(error);
-      onError?.(error);
-    },
-    redirectUrl,
-    skipRedirect: true, // We handle navigation via success step
-  });
-
   const { validateIdentifier } = validation;
 
   // ─────────────────────────────────────────────────────────────────────────
@@ -139,8 +118,17 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
       return;
     }
 
-    setIsLoading(true);
     clearError();
+    setOtp('');
+    setWebmail(null);
+    // Optimistic: the code screen opens now; a failed request rolls back to the identifier step.
+    setStep('otp');
+
+    const rollBack = (msg: string) => {
+      setStep('identifier');
+      setError(msg);
+      onError?.(msg);
+    };
 
     try {
       // Only apps that opted in send consent fields — absent option ⇒ body unchanged.
@@ -152,30 +140,23 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
       if (result.success) {
         saveIdentifierToStorage(identifier);
         setWebmail(result.webmail ?? null);
-        setStep('otp');
+        startResendCountdown(result.resendIn ?? AUTH_CONSTANTS.RESEND_COOLDOWN_SECONDS);
         onIdentifierSuccess?.(identifier);
+      } else if (result.retryAfter) {
+        setStep('identifier');
+        startRateLimitCountdown(result.retryAfter);
       } else {
-        if (result.retryAfter) {
-          startRateLimitCountdown(result.retryAfter);
-          clearError();
-        } else {
-          setError(result.message);
-          onError?.(result.message);
-        }
+        rollBack(result.message);
       }
     } catch {
-      const msg = 'An unexpected error occurred';
-      setError(msg);
-      onError?.(msg);
-    } finally {
-      setIsLoading(false);
+      rollBack('An unexpected error occurred');
     }
   }, [
     identifier, acceptedTerms, requireTermsAcceptance,
     marketingConsent, marketingConsentOption,
     validateIdentifier, requestOTP, saveIdentifierToStorage,
-    setError, setIsLoading, setStep, clearError, setWebmail,
-    startRateLimitCountdown, onIdentifierSuccess, onError, sourceUrl,
+    setError, setOtp, setStep, clearError, setWebmail,
+    startRateLimitCountdown, startResendCountdown, onIdentifierSuccess, onError, sourceUrl,
   ]);
 
   // Core OTP submit - accepts explicit values to avoid stale closures
@@ -197,12 +178,9 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
       // Skip redirect - we'll show success screen first
       const result = await verifyOTP(submitIdentifier, submitOtp, sourceUrl, redirectUrl, true, rememberMe);
 
-      // Check if 2FA is required (user has TOTP device)
       if (result.requires_2fa && result.session_id) {
         authLogger.info('2FA required after OTP verification');
-        setTwoFactorSessionId(result.session_id);
-        setShouldPrompt2FA(result.should_prompt_2fa || false);
-        setStep('2fa');
+        beginTwoFactorChallenge({ sessionId: result.session_id });
         saveIdentifierToStorage(submitIdentifier);
         return true; // OTP was successful, now need 2FA
       }
@@ -210,9 +188,6 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
       if (result.success) {
         saveIdentifierToStorage(submitIdentifier);
 
-        // Sign-in only verifies identity. Setting up 2FA is owned by
-        // ProfileLayout, so we never branch into a setup prompt here — the
-        // backend's `should_prompt_2fa` hint is intentionally ignored.
         authLogger.info('OTP verification successful, showing success screen');
         setStep('success');
         onOTPSuccess?.();
@@ -230,7 +205,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
     } finally {
       setIsLoading(false);
     }
-  }, [verifyOTP, saveIdentifierToStorage, setError, setIsLoading, clearError, onOTPSuccess, onError, sourceUrl, redirectUrl, rememberMe, setTwoFactorSessionId, setShouldPrompt2FA, setStep]);
+  }, [verifyOTP, saveIdentifierToStorage, setError, setIsLoading, clearError, onOTPSuccess, onError, sourceUrl, redirectUrl, rememberMe, setStep]);
 
   const handleOTPSubmit = useCallback(async (e: React.FormEvent) => {
     e.preventDefault();
@@ -241,8 +216,8 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
   // Password Submit
   // ─────────────────────────────────────────────────────────────────────────
 
-  // The password credential lands on the SAME step machine as the OTP code:
-  // both end at '2fa' or 'success', so the layout renders one set of screens.
+  // The password credential lands on the same outcomes as the OTP code:
+  // a 2FA challenge or 'success'.
   const submitPassword = useCallback(async (
     submitIdentifier: string,
     submitPassword_: string,
@@ -274,9 +249,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
 
       if (result.requires_2fa && result.session_id) {
         authLogger.info('2FA required after password login');
-        setTwoFactorSessionId(result.session_id);
-        setShouldPrompt2FA(result.should_prompt_2fa || false);
-        setStep('2fa');
+        beginTwoFactorChallenge({ sessionId: result.session_id });
         saveIdentifierToStorage(submitIdentifier);
         return true; // Password was accepted, now need 2FA
       }
@@ -310,7 +283,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
   }, [
     login, validateIdentifier, saveIdentifierToStorage, setError, setIsLoading,
     clearError, startRateLimitCountdown, onOTPSuccess, onError, redirectUrl,
-    rememberMe, setTwoFactorSessionId, setShouldPrompt2FA, setStep,
+    rememberMe, setStep,
   ]);
 
   const handlePasswordSubmit = useCallback(async (e: React.FormEvent) => {
@@ -333,6 +306,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
       if (result.success) {
         saveIdentifierToStorage(identifier);
         setWebmail(result.webmail ?? null);
+        startResendCountdown(result.resendIn ?? AUTH_CONSTANTS.RESEND_COOLDOWN_SECONDS);
         setOtp('');
       } else {
         if (result.retryAfter) {
@@ -350,7 +324,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
     } finally {
       setIsLoading(false);
     }
-  }, [identifier, marketingConsent, marketingConsentOption, requestOTP, saveIdentifierToStorage, setOtp, setError, setIsLoading, clearError, startRateLimitCountdown, setWebmail, onError, sourceUrl]);
+  }, [identifier, marketingConsent, marketingConsentOption, requestOTP, saveIdentifierToStorage, setOtp, setError, setIsLoading, clearError, startRateLimitCountdown, startResendCountdown, setWebmail, onError, sourceUrl]);
 
   const handleBackToIdentifier = useCallback(() => {
     setStep('identifier');
@@ -362,39 +336,6 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
     clearError();
   }, [setStep, clearError]);
 
-  // ─────────────────────────────────────────────────────────────────────────
-  // 2FA Handlers
-  // ─────────────────────────────────────────────────────────────────────────
-
-  const handle2FASubmit = useCallback(async (e: React.FormEvent) => {
-    e.preventDefault();
-
-    if (!twoFactorSessionId) {
-      const msg = 'Missing 2FA session';
-      setError(msg);
-      onError?.(msg);
-      return;
-    }
-
-    if (useBackupCode) {
-      await twoFactor.verifyBackupCode(twoFactorSessionId, twoFactorCode);
-    } else {
-      await twoFactor.verifyTOTP(twoFactorSessionId, twoFactorCode);
-    }
-  }, [twoFactorSessionId, twoFactorCode, useBackupCode, twoFactor, setError, onError]);
-
-  const handleUseBackupCode = useCallback(() => {
-    setUseBackupCode(true);
-    setTwoFactorCode('');
-    clearError();
-  }, [setUseBackupCode, setTwoFactorCode, clearError]);
-
-  const handleUseTOTP = useCallback(() => {
-    setUseBackupCode(false);
-    setTwoFactorCode('');
-    clearError();
-  }, [setUseBackupCode, setTwoFactorCode, clearError]);
-
   // ─────────────────────────────────────────────────────────────────────────
   // Auto-auth from URL
   // ─────────────────────────────────────────────────────────────────────────
@@ -458,21 +399,11 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
     handleBackToIdentifier,
     forceOTPStep,
 
-    // 2FA handlers
-    handle2FASubmit,
-    handleUseBackupCode,
-    handleUseTOTP,
-
     // Validation
     ...validation,
 
     // Auto-submit ref
     isAutoSubmittingFromUrl: isAutoSubmitFromUrlRef,
-
-    // 2FA state from hook (for loading indicator)
-    is2FALoading: twoFactor.isLoading,
-    twoFactorWarning: twoFactor.warning,
-    twoFactorAttemptsRemaining: twoFactor.attemptsRemaining,
   };
 };
 

package/src/auth/hooks/useAuthFormState.ts

@@ -10,6 +10,32 @@ const formatCountdown = (s: number): string => {
   return m > 0 ? `${m}:${String(s % 60).padStart(2, '0')}` : `${s}s`;
 };
 
+const useCountdown = () => {
+  const [seconds, setSeconds] = useState(0);
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const start = useCallback((from: number) => {
+    if (timerRef.current) clearInterval(timerRef.current);
+    setSeconds(from);
+    timerRef.current = setInterval(() => {
+      setSeconds((prev) => {
+        if (prev <= 1) {
+          clearInterval(timerRef.current!);
+          timerRef.current = null;
+          return 0;
+        }
+        return prev - 1;
+      });
+    }, 1000);
+  }, []);
+
+  useEffect(() => () => {
+    if (timerRef.current) clearInterval(timerRef.current);
+  }, []);
+
+  return { seconds, start };
+};
+
 export interface UseAuthFormStateReturn extends AuthFormState, AuthFormStateHandlers {}
 
 /**
@@ -27,39 +53,14 @@ export const useAuthFormState = (
   // null until the marketing-consent feature (if enabled) resolves its
   // jurisdiction-aware default — the layout owns that decision.
   const [marketingConsent, setMarketingConsent] = useState<boolean | null>(null);
-  const [rememberMe, setRememberMe] = useState(false);
+  // Signed in for 30 days unless an app opts into showing the choice.
+  const [rememberMe, setRememberMe] = useState(true);
   const [step, setStep] = useState<AuthStep>('identifier');
   const [error, setError] = useState('');
   const [webmail, setWebmail] = useState<WebmailLink | null>(null);
 
-  // 2FA state
-  const [twoFactorSessionId, setTwoFactorSessionId] = useState<string | null>(null);
-  const [shouldPrompt2FA, setShouldPrompt2FA] = useState(false);
-  const [twoFactorCode, setTwoFactorCode] = useState('');
-  const [useBackupCode, setUseBackupCode] = useState(false);
-
-  // Rate limit countdown
-  const [rateLimitSeconds, setRateLimitSeconds] = useState(0);
-  const rateLimitTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
-
-  const startRateLimitCountdown = useCallback((seconds: number) => {
-    if (rateLimitTimerRef.current) clearInterval(rateLimitTimerRef.current);
-    setRateLimitSeconds(seconds);
-    rateLimitTimerRef.current = setInterval(() => {
-      setRateLimitSeconds((prev) => {
-        if (prev <= 1) {
-          clearInterval(rateLimitTimerRef.current!);
-          rateLimitTimerRef.current = null;
-          return 0;
-        }
-        return prev - 1;
-      });
-    }, 1000);
-  }, []);
-
-  useEffect(() => () => {
-    if (rateLimitTimerRef.current) clearInterval(rateLimitTimerRef.current);
-  }, []);
+  const rateLimit = useCountdown();
+  const resend = useCountdown();
 
   const clearError = useCallback(() => setError(''), []);
 
@@ -74,13 +75,11 @@ export const useAuthFormState = (
     rememberMe,
     step,
     error,
-    twoFactorSessionId,
-    shouldPrompt2FA,
-    twoFactorCode,
-    useBackupCode,
-    rateLimitSeconds,
-    isRateLimited: rateLimitSeconds > 0,
-    rateLimitLabel: formatCountdown(rateLimitSeconds),
+    rateLimitSeconds: rateLimit.seconds,
+    isRateLimited: rateLimit.seconds > 0,
+    rateLimitLabel: formatCountdown(rateLimit.seconds),
+    resendSeconds: resend.seconds,
+    resendLabel: formatCountdown(resend.seconds),
     webmail,
     // Handlers
     setIdentifier,
@@ -93,11 +92,8 @@ export const useAuthFormState = (
     clearError,
     setStep,
     setIsLoading,
-    setTwoFactorSessionId,
-    setShouldPrompt2FA,
-    setTwoFactorCode,
-    setUseBackupCode,
-    startRateLimitCountdown,
+    startRateLimitCountdown: rateLimit.start,
+    startResendCountdown: resend.start,
     setWebmail,
   };
 };

package/src/auth/hooks/useTwoFactorChallenge.ts

@@ -0,0 +1,35 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+
+/** A pending login that needs a TOTP or backup code before tokens are issued. */
+export interface TwoFactorChallenge {
+  sessionId: string;
+}
+
+// Module-scoped on purpose: one sign-in is in flight per page, and the sign-in
+// form and the challenge dialog share it without either importing the other.
+let current: TwoFactorChallenge | null = null;
+const listeners = new Set<() => void>();
+
+const set = (next: TwoFactorChallenge | null): void => {
+  current = next;
+  for (const listener of [...listeners]) listener();
+};
+
+const subscribe = (listener: () => void): (() => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+/** Called by whichever step received `requires_2fa` (OTP, password, OAuth callback). */
+export const beginTwoFactorChallenge = (challenge: TwoFactorChallenge): void => set(challenge);
+
+/** Called when the challenge is verified or abandoned. */
+export const endTwoFactorChallenge = (): void => set(null);
+
+/** The pending challenge, or null. */
+export const useTwoFactorChallenge = (): TwoFactorChallenge | null =>
+  useSyncExternalStore(subscribe, () => current, () => null);