@djangocfg/api 2.1.56 → 2.1.58

package/src/auth/hooks/useAuthFormState.ts

@@ -0,0 +1,60 @@
+"use client"
+
+import { useCallback, useState } from 'react';
+
+import type { AuthChannel, AuthFormState, AuthFormStateHandlers, AuthStep } from '../types';
+
+export interface UseAuthFormStateReturn extends AuthFormState, AuthFormStateHandlers {}
+
+/**
+ * Hook for auth form state management.
+ * Pure state - no side effects, no API calls.
+ */
+export const useAuthFormState = (
+  initialIdentifier = '',
+  initialChannel: AuthChannel = 'email'
+): UseAuthFormStateReturn => {
+  const [identifier, setIdentifier] = useState(initialIdentifier);
+  const [channel, setChannel] = useState<AuthChannel>(initialChannel);
+  const [otp, setOtp] = useState('');
+  const [isLoading, setIsLoading] = useState(false);
+  const [acceptedTerms, setAcceptedTerms] = useState(false);
+  const [step, setStep] = useState<AuthStep>('identifier');
+  const [error, setError] = useState('');
+
+  // 2FA state
+  const [twoFactorSessionId, setTwoFactorSessionId] = useState<string | null>(null);
+  const [shouldPrompt2FA, setShouldPrompt2FA] = useState(false);
+  const [twoFactorCode, setTwoFactorCode] = useState('');
+  const [useBackupCode, setUseBackupCode] = useState(false);
+
+  const clearError = useCallback(() => setError(''), []);
+
+  return {
+    // State
+    identifier,
+    channel,
+    otp,
+    isLoading,
+    acceptedTerms,
+    step,
+    error,
+    twoFactorSessionId,
+    shouldPrompt2FA,
+    twoFactorCode,
+    useBackupCode,
+    // Handlers
+    setIdentifier,
+    setChannel,
+    setOtp,
+    setAcceptedTerms,
+    setError,
+    clearError,
+    setStep,
+    setIsLoading,
+    setTwoFactorSessionId,
+    setShouldPrompt2FA,
+    setTwoFactorCode,
+    setUseBackupCode,
+  };
+};

package/src/auth/hooks/useAuthValidation.ts

@@ -0,0 +1,77 @@
+"use client"
+
+import { useCallback } from 'react';
+
+import type { AuthChannel, AuthFormValidation } from '../types';
+
+// Email regex - RFC 5322 simplified
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// Phone regex - E.164 format (+[country][number], 7-15 digits)
+const PHONE_REGEX = /^\+[1-9]\d{6,14}$/;
+
+/**
+ * Hook for auth identifier validation.
+ * Pure functions - no state, no side effects.
+ */
+export const useAuthValidation = (): AuthFormValidation => {
+  /**
+   * Detect channel type from identifier string.
+   * Returns 'email' if contains @, 'phone' if starts with + and matches E.164.
+   */
+  const detectChannelFromIdentifier = useCallback((id: string): AuthChannel | null => {
+    if (!id) return null;
+
+    // Email detection - contains @
+    if (id.includes('@')) {
+      return 'email';
+    }
+
+    // Phone detection - starts with + and matches E.164 format
+    if (id.startsWith('+') && PHONE_REGEX.test(id)) {
+      return 'phone';
+    }
+
+    return null;
+  }, []);
+
+  /**
+   * Validate identifier format based on channel type.
+   */
+  const validateIdentifier = useCallback((id: string, channelType?: AuthChannel): boolean => {
+    if (!id) return false;
+
+    const channel = channelType || detectChannelFromIdentifier(id);
+
+    if (channel === 'email') {
+      return EMAIL_REGEX.test(id);
+    }
+
+    if (channel === 'phone') {
+      return PHONE_REGEX.test(id);
+    }
+
+    return false;
+  }, [detectChannelFromIdentifier]);
+
+  return {
+    detectChannelFromIdentifier,
+    validateIdentifier,
+  };
+};
+
+// Export standalone functions for use outside React
+export const detectChannelFromIdentifier = (id: string): AuthChannel | null => {
+  if (!id) return null;
+  if (id.includes('@')) return 'email';
+  if (id.startsWith('+') && PHONE_REGEX.test(id)) return 'phone';
+  return null;
+};
+
+export const validateIdentifier = (id: string, channelType?: AuthChannel): boolean => {
+  if (!id) return false;
+  const channel = channelType || detectChannelFromIdentifier(id);
+  if (channel === 'email') return EMAIL_REGEX.test(id);
+  if (channel === 'phone') return PHONE_REGEX.test(id);
+  return false;
+};

package/src/auth/hooks/useGithubAuth.ts

@@ -12,7 +12,11 @@ export interface UseGithubAuthOptions {
   sourceUrl?: string;
   onSuccess?: (user: any, isNewUser: boolean) => void;
   onError?: (error: string) => void;
+  /** Callback when 2FA is required */
+  onRequires2FA?: (sessionId: string, shouldPrompt2FA: boolean) => void;
   redirectUrl?: string;
+  /** Skip automatic redirect after success (caller handles navigation) */
+  skipRedirect?: boolean;
 }
 
 export interface UseGithubAuthReturn {
@@ -42,7 +46,7 @@ export interface UseGithubAuthReturn {
  * ```
  */
 export const useGithubAuth = (options: UseGithubAuthOptions = {}): UseGithubAuthReturn => {
-  const { sourceUrl, onSuccess, onError, redirectUrl } = options;
+  const { sourceUrl, onSuccess, onError, onRequires2FA, redirectUrl, skipRedirect = false } = options;
   const router = useCfgRouter();
 
   const [isLoading, setIsLoading] = useState(false);
@@ -132,6 +136,21 @@ export const useGithubAuth = (options: UseGithubAuthOptions = {}): UseGithubAuth
         state,
       });
 
+      // Check if 2FA is required
+      if (response.requires_2fa && response.session_id) {
+        authLogger.info('GitHub OAuth requires 2FA, session:', response.session_id);
+
+        // Track 2FA requirement
+        Analytics.event(AnalyticsEvent.AUTH_OAUTH_START, {
+          category: AnalyticsCategory.AUTH,
+          label: 'github-2fa-required',
+        });
+
+        // Call 2FA callback
+        onRequires2FA?.(response.session_id, response.should_prompt_2fa || false);
+        return;
+      }
+
       if (!response.access || !response.refresh) {
         throw new Error('Invalid response from OAuth callback');
       }
@@ -155,10 +174,12 @@ export const useGithubAuth = (options: UseGithubAuthOptions = {}): UseGithubAuth
       // Call success callback
       onSuccess?.(response.user, response.is_new_user || false);
 
-      // Redirect to dashboard or specified URL
-      // Use hardPush for full page reload - ensures all React contexts reinitialize
-      const finalRedirectUrl = redirectUrl || '/dashboard';
-      router.hardPush(finalRedirectUrl);
+      // Redirect (unless skipRedirect is true)
+      if (!skipRedirect) {
+        // Use hardPush for full page reload - ensures all React contexts reinitialize
+        const finalRedirectUrl = redirectUrl || '/dashboard';
+        router.hardPush(finalRedirectUrl);
+      }
 
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : 'GitHub authentication failed';

package/src/auth/hooks/useTwoFactor.ts

@@ -0,0 +1,239 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+
+import { useCfgRouter } from '@djangocfg/ui-nextjs/hooks';
+
+import { apiAccounts, apiTotp } from '../../clients';
+import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
+import { authLogger } from '../utils/logger';
+
+export interface UseTwoFactorOptions {
+  /** Callback on successful 2FA verification */
+  onSuccess?: (user: any) => void;
+  /** Callback on error */
+  onError?: (error: string) => void;
+  /** URL to redirect after successful verification */
+  redirectUrl?: string;
+  /** Skip automatic redirect after success (caller handles navigation) */
+  skipRedirect?: boolean;
+}
+
+export interface UseTwoFactorReturn {
+  /** Loading state */
+  isLoading: boolean;
+  /** Error message */
+  error: string | null;
+  /** Warning message (e.g., low backup codes) */
+  warning: string | null;
+  /** Remaining backup codes (if backup code was used) */
+  remainingBackupCodes: number | null;
+  /** Verify TOTP code */
+  verifyTOTP: (sessionId: string, code: string) => Promise<boolean>;
+  /** Verify backup code */
+  verifyBackupCode: (sessionId: string, backupCode: string) => Promise<boolean>;
+  /** Clear error */
+  clearError: () => void;
+}
+
+/**
+ * Hook for 2FA verification during login.
+ *
+ * Usage:
+ * 1. After OTP/OAuth verification returns requires_2fa=true and session_id
+ * 2. Show 2FA form and collect TOTP code from user
+ * 3. Call verifyTOTP(sessionId, code) to complete authentication
+ *
+ * @example
+ * ```tsx
+ * const { isLoading, error, verifyTOTP, verifyBackupCode } = useTwoFactor({
+ *   onSuccess: (user) => console.log('Logged in:', user),
+ *   onError: (error) => console.error(error),
+ *   redirectUrl: '/dashboard',
+ * });
+ *
+ * const handleSubmit = async (code: string) => {
+ *   if (useBackupCode) {
+ *     await verifyBackupCode(sessionId, code);
+ *   } else {
+ *     await verifyTOTP(sessionId, code);
+ *   }
+ * };
+ * ```
+ */
+export const useTwoFactor = (options: UseTwoFactorOptions = {}): UseTwoFactorReturn => {
+  const { onSuccess, onError, redirectUrl, skipRedirect = false } = options;
+  const router = useCfgRouter();
+
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [warning, setWarning] = useState<string | null>(null);
+  const [remainingBackupCodes, setRemainingBackupCodes] = useState<number | null>(null);
+
+  const clearError = useCallback(() => {
+    setError(null);
+  }, []);
+
+  /**
+   * Handle successful 2FA verification
+   */
+  const handleSuccess = useCallback((response: {
+    access_token: string;
+    refresh_token: string;
+    user: any;
+    warning?: string;
+    remaining_backup_codes?: number;
+  }) => {
+    // Save tokens
+    apiAccounts.setToken(response.access_token, response.refresh_token);
+
+    // Set warning if any
+    if (response.warning) {
+      setWarning(response.warning);
+    }
+
+    // Set remaining backup codes if provided
+    if (response.remaining_backup_codes !== undefined) {
+      setRemainingBackupCodes(response.remaining_backup_codes);
+    }
+
+    // Track successful 2FA
+    Analytics.event(AnalyticsEvent.AUTH_LOGIN_SUCCESS, {
+      category: AnalyticsCategory.AUTH,
+      label: '2fa',
+    });
+
+    // Set user ID for tracking
+    if (response.user?.id) {
+      Analytics.setUser(String(response.user.id));
+    }
+
+    // Call success callback
+    onSuccess?.(response.user);
+
+    // Redirect (unless skipRedirect is true)
+    if (!skipRedirect) {
+      const finalRedirectUrl = redirectUrl || '/dashboard';
+      authLogger.info('2FA successful, redirecting to:', finalRedirectUrl);
+      router.hardPush(finalRedirectUrl);
+    }
+  }, [onSuccess, redirectUrl, router, skipRedirect]);
+
+  /**
+   * Verify TOTP code from authenticator app
+   */
+  const verifyTOTP = useCallback(async (sessionId: string, code: string): Promise<boolean> => {
+    if (!sessionId) {
+      const msg = 'Missing 2FA session ID';
+      setError(msg);
+      onError?.(msg);
+      return false;
+    }
+
+    if (!code || code.length !== 6) {
+      const msg = 'Please enter a 6-digit code';
+      setError(msg);
+      onError?.(msg);
+      return false;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      authLogger.info('Verifying TOTP code...');
+
+      const response = await apiTotp.totp_verification.totpVerifyCreate({
+        session_id: sessionId,
+        code,
+      });
+
+      if (!response.access_token || !response.refresh_token) {
+        throw new Error('Invalid response from 2FA verification');
+      }
+
+      handleSuccess(response);
+      return true;
+
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Invalid verification code';
+      authLogger.error('2FA TOTP verification error:', err);
+      setError(errorMessage);
+      onError?.(errorMessage);
+
+      // Track failed 2FA
+      Analytics.event(AnalyticsEvent.AUTH_OTP_VERIFY_FAIL, {
+        category: AnalyticsCategory.AUTH,
+        label: '2fa-totp',
+      });
+
+      return false;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [handleSuccess, onError]);
+
+  /**
+   * Verify backup recovery code
+   */
+  const verifyBackupCode = useCallback(async (sessionId: string, backupCode: string): Promise<boolean> => {
+    if (!sessionId) {
+      const msg = 'Missing 2FA session ID';
+      setError(msg);
+      onError?.(msg);
+      return false;
+    }
+
+    if (!backupCode || backupCode.length < 8) {
+      const msg = 'Please enter your backup code';
+      setError(msg);
+      onError?.(msg);
+      return false;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      authLogger.info('Verifying backup code...');
+
+      const response = await apiTotp.totp_verification.totpVerifyBackupCreate({
+        session_id: sessionId,
+        backup_code: backupCode.replace(/\s+/g, ''), // Remove spaces
+      });
+
+      if (!response.access_token || !response.refresh_token) {
+        throw new Error('Invalid response from backup code verification');
+      }
+
+      handleSuccess(response);
+      return true;
+
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Invalid backup code';
+      authLogger.error('2FA backup code verification error:', err);
+      setError(errorMessage);
+      onError?.(errorMessage);
+
+      // Track failed 2FA
+      Analytics.event(AnalyticsEvent.AUTH_OTP_VERIFY_FAIL, {
+        category: AnalyticsCategory.AUTH,
+        label: '2fa-backup',
+      });
+
+      return false;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [handleSuccess, onError]);
+
+  return {
+    isLoading,
+    error,
+    warning,
+    remainingBackupCodes,
+    verifyTOTP,
+    verifyBackupCode,
+    clearError,
+  };
+};

package/src/auth/hooks/useTwoFactorSetup.ts

@@ -0,0 +1,213 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+
+import { apiTotp } from '../../clients';
+import { authLogger } from '../utils/logger';
+
+export interface TwoFactorSetupData {
+  /** Device ID to use for confirmation */
+  deviceId: string;
+  /** Base32-encoded TOTP secret (for manual entry) */
+  secret: string;
+  /** otpauth:// URI for QR code generation */
+  provisioningUri: string;
+  /** Base64-encoded QR code image (data URI) */
+  qrCodeBase64: string;
+  /** Seconds until setup expires */
+  expiresIn: number;
+}
+
+export interface UseTwoFactorSetupOptions {
+  /** Callback when setup is confirmed and backup codes are generated */
+  onComplete?: (backupCodes: string[]) => void;
+  /** Callback on error */
+  onError?: (error: string) => void;
+}
+
+export interface UseTwoFactorSetupReturn {
+  /** Loading state */
+  isLoading: boolean;
+  /** Error message */
+  error: string | null;
+  /** Setup data (QR code, secret, etc.) */
+  setupData: TwoFactorSetupData | null;
+  /** Backup codes after confirmation */
+  backupCodes: string[] | null;
+  /** Warning message about backup codes */
+  backupCodesWarning: string | null;
+  /** Current setup step */
+  setupStep: 'idle' | 'scanning' | 'confirming' | 'complete';
+  /** Start 2FA setup - returns QR code data */
+  startSetup: (deviceName?: string) => Promise<TwoFactorSetupData | null>;
+  /** Confirm setup with TOTP code - returns backup codes */
+  confirmSetup: (code: string) => Promise<string[] | null>;
+  /** Reset setup state */
+  resetSetup: () => void;
+  /** Clear error */
+  clearError: () => void;
+}
+
+/**
+ * Hook for 2FA setup (enabling TOTP authentication).
+ *
+ * Flow:
+ * 1. Call startSetup() to get QR code and provisioning URI
+ * 2. User scans QR code with authenticator app
+ * 3. Call confirmSetup(code) with the 6-digit code from app
+ * 4. Show backup codes to user (they must save these!)
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   isLoading,
+ *   error,
+ *   setupData,
+ *   backupCodes,
+ *   setupStep,
+ *   startSetup,
+ *   confirmSetup,
+ * } = useTwoFactorSetup({
+ *   onComplete: (codes) => console.log('Backup codes:', codes),
+ *   onError: (error) => console.error(error),
+ * });
+ *
+ * // Start setup
+ * const data = await startSetup('My iPhone');
+ *
+ * // Show QR code
+ * <QRCodeSVG value={data.provisioningUri} />
+ *
+ * // Confirm with code from app
+ * const codes = await confirmSetup('123456');
+ * ```
+ */
+export const useTwoFactorSetup = (options: UseTwoFactorSetupOptions = {}): UseTwoFactorSetupReturn => {
+  const { onComplete, onError } = options;
+
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [setupData, setSetupData] = useState<TwoFactorSetupData | null>(null);
+  const [backupCodes, setBackupCodes] = useState<string[] | null>(null);
+  const [backupCodesWarning, setBackupCodesWarning] = useState<string | null>(null);
+  const [setupStep, setSetupStep] = useState<'idle' | 'scanning' | 'confirming' | 'complete'>('idle');
+
+  const clearError = useCallback(() => {
+    setError(null);
+  }, []);
+
+  const resetSetup = useCallback(() => {
+    setSetupData(null);
+    setBackupCodes(null);
+    setBackupCodesWarning(null);
+    setSetupStep('idle');
+    setError(null);
+  }, []);
+
+  /**
+   * Start 2FA setup - generates QR code and secret
+   */
+  const startSetup = useCallback(async (deviceName?: string): Promise<TwoFactorSetupData | null> => {
+    setIsLoading(true);
+    setError(null);
+    setSetupStep('scanning');
+
+    try {
+      authLogger.info('Starting 2FA setup...');
+
+      const response = await apiTotp.totp_setup.create({
+        device_name: deviceName,
+      });
+
+      const data: TwoFactorSetupData = {
+        deviceId: response.device_id,
+        secret: response.secret,
+        provisioningUri: response.provisioning_uri,
+        qrCodeBase64: response.qr_code_base64,
+        expiresIn: response.expires_in,
+      };
+
+      setSetupData(data);
+      authLogger.info('2FA setup initiated, expires in:', data.expiresIn, 'seconds');
+
+      return data;
+
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Failed to start 2FA setup';
+      authLogger.error('2FA setup error:', err);
+      setError(errorMessage);
+      setSetupStep('idle');
+      onError?.(errorMessage);
+      return null;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [onError]);
+
+  /**
+   * Confirm 2FA setup with TOTP code from authenticator app
+   */
+  const confirmSetup = useCallback(async (code: string): Promise<string[] | null> => {
+    if (!setupData) {
+      const msg = 'Setup not started. Call startSetup() first.';
+      setError(msg);
+      onError?.(msg);
+      return null;
+    }
+
+    if (!code || code.length !== 6) {
+      const msg = 'Please enter a 6-digit code';
+      setError(msg);
+      onError?.(msg);
+      return null;
+    }
+
+    setIsLoading(true);
+    setError(null);
+    setSetupStep('confirming');
+
+    try {
+      authLogger.info('Confirming 2FA setup...');
+
+      const response = await apiTotp.totp_setup.confirmCreate({
+        device_id: setupData.deviceId,
+        code,
+      });
+
+      const codes = response.backup_codes;
+      setBackupCodes(codes);
+      setBackupCodesWarning(response.backup_codes_warning);
+      setSetupStep('complete');
+
+      authLogger.info('2FA setup confirmed, backup codes generated:', codes.length);
+
+      // Call completion callback
+      onComplete?.(codes);
+
+      return codes;
+
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Invalid code. Please try again.';
+      authLogger.error('2FA setup confirmation error:', err);
+      setError(errorMessage);
+      setSetupStep('scanning'); // Go back to scanning step
+      onError?.(errorMessage);
+      return null;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [setupData, onComplete, onError]);
+
+  return {
+    isLoading,
+    error,
+    setupData,
+    backupCodes,
+    backupCodesWarning,
+    setupStep,
+    startSetup,
+    confirmSetup,
+    resetSetup,
+    clearError,
+  };
+};

package/src/auth/index.ts

@@ -30,5 +30,8 @@ export * from './context';
 // Hooks
 export * from './hooks';
 
+// Types (single source of truth)
+export * from './types';
+
 // Utils (validation, errors, analytics)
 export * from './utils';