@djangocfg/api 2.1.57 → 2.1.58

package/README.md

@@ -18,6 +18,7 @@ This package provides everything needed for authentication and user management:
 - **Auth System** - Complete authentication module with contexts, hooks, and utilities
 - **JWT Management** - Automatic token refresh and storage
 - **OAuth Integration** - GitHub OAuth with callback handling
+- **Two-Factor Authentication** - TOTP-based 2FA setup and verification
 - **Server Middleware** - Proxy middleware for Next.js
 - **Shared Storage** - Authentication storage used by all extensions
 
@@ -26,13 +27,17 @@ This package provides everything needed for authentication and user management:
 ```
 src/
 ├── generated/
-│   └── cfg_accounts/       # Generated API client
-│       ├── api/            # API class with all endpoints
-│       ├── schemas/        # Zod validation schemas
-│       └── types/          # TypeScript types
+│   ├── cfg_accounts/       # Generated API client (accounts, profiles, OAuth)
+│   │   ├── api/            # API class with all endpoints
+│   │   ├── schemas/        # Zod validation schemas
+│   │   └── types/          # TypeScript types
+│   └── cfg_totp/           # Generated TOTP/2FA client
+│       ├── api/            # TOTP device, setup, verification endpoints
+│       ├── schemas/        # TOTP-specific schemas
+│       └── types/          # TOTP types
 └── auth/
     ├── context/            # AuthProvider, AccountsProvider
-    ├── hooks/              # useAuth, useAuthGuard, useGithubAuth, etc.
+    ├── hooks/              # useAuth, useAuthGuard, useGithubAuth, useTwoFactor, etc.
     ├── middlewares/        # Next.js proxy middleware
     └── utils/              # Validation, errors, logger, analytics
 ```
@@ -88,7 +93,20 @@ This is handled automatically by `createExtensionAPI()` from `@djangocfg/ext-bas
 
 ## Auth Module
 
-Complete OTP-based authentication system with React contexts, hooks, and utilities.
+Complete authentication system with OTP, OAuth, and Two-Factor Authentication (2FA) support.
+
+### Authentication Flow
+
+```
+1. User enters email/phone → OTP sent
+2. User enters OTP code → Verify
+   ├── If 2FA enabled → Show TOTP verification
+   │   └── User enters 6-digit TOTP → Verify
+   └── If no 2FA → Continue
+3. Success screen with logo → Auto-redirect to dashboard
+```
+
+All authentication methods (OTP, OAuth, 2FA) show a success screen with your logo before redirecting.
 
 ### Setup
 
@@ -122,8 +140,10 @@ export default function RootLayout({ children }) {
 import {
   useAuth,              // Main auth context (user, isAuthenticated, OTP methods)
   useAuthGuard,         // Protect routes (redirect if not authenticated)
-  useAuthForm,          // OTP form state management (identifier, otp, steps)
+  useAuthForm,          // Auth form state management (OTP + 2FA steps)
   useGithubAuth,        // GitHub OAuth integration
+  useTwoFactor,         // 2FA verification (verify TOTP code)
+  useTwoFactorSetup,    // 2FA setup flow (generate QR, verify, enable)
   useAutoAuth,          // Auto-authentication on mount
   useLocalStorage,      // localStorage helper
   useSessionStorage,    // sessionStorage helper
@@ -185,7 +205,7 @@ export default function DashboardPage() {
 
 ### useAuthForm
 
-Manage OTP authentication form state (two-step flow):
+Manage authentication form state with OTP and 2FA support:
 
 ```tsx
 'use client';
@@ -197,7 +217,7 @@ export function OTPLoginForm() {
     identifier,        // Email or phone number
     channel,           // 'email' | 'phone'
     otp,               // 6-digit OTP code
-    step,              // 'identifier' | 'otp'
+    step,              // 'identifier' | 'otp' | '2fa' | '2fa-setup' | 'success'
     isLoading,
     error,
     acceptedTerms,
@@ -304,6 +324,98 @@ export function GithubLoginButton() {
 
 OAuth callback is handled automatically by `@djangocfg/layouts` AuthLayout component.
 
+### useTwoFactor
+
+Verify 2FA code during authentication:
+
+```tsx
+'use client';
+import { useTwoFactor } from '@djangocfg/api/auth';
+
+export function TwoFactorVerify({ sessionId }: { sessionId: string }) {
+  const {
+    verify,        // (code: string) => Promise<void>
+    isLoading,     // boolean
+    error,         // string | null
+  } = useTwoFactor({
+    sessionId,
+    onSuccess: (user) => console.log('2FA verified:', user),
+    onError: (error) => console.error('2FA failed:', error),
+    redirectUrl: '/dashboard',
+    skipRedirect: false, // Set true if handling navigation manually
+  });
+
+  const [code, setCode] = useState('');
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); verify(code); }}>
+      <input
+        type="text"
+        value={code}
+        onChange={(e) => setCode(e.target.value)}
+        placeholder="000000"
+        maxLength={6}
+      />
+      <button type="submit" disabled={isLoading || code.length < 6}>
+        {isLoading ? 'Verifying...' : 'Verify'}
+      </button>
+    </form>
+  );
+}
+```
+
+### useTwoFactorSetup
+
+Setup 2FA for authenticated users:
+
+```tsx
+'use client';
+import { useTwoFactorSetup } from '@djangocfg/api/auth';
+
+export function TwoFactorSetup() {
+  const {
+    // State
+    qrCode,        // Base64 QR code image
+    secret,        // Manual entry secret
+    isEnabled,     // Current 2FA status
+    isLoading,
+    error,
+
+    // Actions
+    startSetup,    // () => Promise<void> - generates QR code
+    verifySetup,   // (code: string) => Promise<void> - enables 2FA
+    disable,       // () => Promise<void> - disables 2FA
+    checkStatus,   // () => Promise<boolean> - refresh status
+  } = useTwoFactorSetup({
+    onSetupComplete: () => console.log('2FA enabled successfully'),
+    onDisabled: () => console.log('2FA disabled'),
+    onError: (error) => console.error('2FA setup error:', error),
+  });
+
+  if (isEnabled) {
+    return (
+      <div>
+        <p>Two-factor authentication is enabled</p>
+        <button onClick={disable}>Disable 2FA</button>
+      </div>
+    );
+  }
+
+  if (qrCode) {
+    return (
+      <div>
+        <img src={qrCode} alt="2FA QR Code" />
+        <p>Secret: {secret}</p>
+        <input placeholder="Enter code from app" />
+        <button onClick={() => verifySetup('123456')}>Verify & Enable</button>
+      </div>
+    );
+  }
+
+  return <button onClick={startSetup}>Set up 2FA</button>;
+}
+```
+
 ## Server Components & API Routes
 
 Use fetchers for server-side data fetching:
@@ -471,6 +583,10 @@ Auth events are automatically tracked when analytics is enabled:
 // - AUTH_OAUTH_START
 // - AUTH_OAUTH_SUCCESS
 // - AUTH_OAUTH_FAIL
+// - AUTH_2FA_SETUP_START
+// - AUTH_2FA_SETUP_COMPLETE
+// - AUTH_2FA_VERIFY_SUCCESS
+// - AUTH_2FA_VERIFY_FAIL
 ```
 
 Analytics setup is handled by `@djangocfg/layouts` package.