# Módulo Auth

**Epic:** OQI-001 - Fundamentos Auth
**Progreso:** 95%
**Responsable:** Backend + Frontend Teams

## Descripción

El módulo de autenticación proporciona un sistema completo de registro, login, recuperación de contraseña, y gestión de sesiones para la plataforma de trading. Incluye soporte para autenticación social (Google, Facebook, Apple) y por teléfono, además de características avanzadas de seguridad como gestión de dispositivos y sesiones activas.

Este módulo es crítico para toda la plataforma, ya que controla el acceso a todas las funcionalidades y gestiona la identidad del usuario a través de JWT tokens con auto-refresh.

## Componentes

### Páginas

- `Login.tsx` - Página principal de inicio de sesión con opciones de social login y phone authentication
- `Register.tsx` - Formulario de registro de nuevos usuarios con validación en tiempo real
- `ForgotPassword.tsx` - Flujo de recuperación de contraseña mediante email
- `ResetPassword.tsx` - Página para establecer nueva contraseña con token de verificación
- `VerifyEmail.tsx` - Confirmación de email para activación de cuenta
- `AuthCallback.tsx` - Callback handler para proveedores OAuth (Google, Facebook, Apple)
- `SecuritySettings.tsx` - Panel de configuración de seguridad y gestión de sesiones

### Componentes Reutilizables

- `PhoneLoginForm.tsx` - Formulario especializado para autenticación por número de teléfono
- `SocialLoginButtons.tsx` - Botones de login para Google, Facebook y Apple con iconos branded
- `DeviceCard.tsx` - Tarjeta de visualización de dispositivo activo con información de navegador/OS
- `SessionsList.tsx` - Lista de sesiones activas del usuario con opción de revocación

## Estructura de Carpetas

```
modules/auth/
├── components/
│   ├── PhoneLoginForm.tsx     - Phone number login with SMS verification
│   ├── SocialLoginButtons.tsx - Google, Facebook, Apple OAuth buttons
│   ├── DeviceCard.tsx         - Session/device display card with revoke
│   ├── SessionsList.tsx       - Active sessions list with management
│   ├── TwoFactorSetup.tsx     - 2FA setup wizard (QR, verify, backup codes)
│   └── TwoFactorVerifyModal.tsx - 2FA verification during login
├── hooks/
│   └── use2FA.ts              - React Query hooks for 2FA operations
├── pages/
│   ├── Login.tsx              - Main login page with 2FA inline support
│   ├── Register.tsx           - User registration
│   ├── ForgotPassword.tsx     - Password recovery email request
│   ├── ResetPassword.tsx      - Set new password with token
│   ├── VerifyEmail.tsx        - Email verification confirmation
│   ├── AuthCallback.tsx       - OAuth callback handler
│   └── SecuritySettings.tsx   - Security hub (sessions, password, 2FA)
└── README.md
```

**Nota:** Los hooks, services, stores y types de autenticación se encuentran en la capa compartida:
- **Store:** `apps/frontend/src/stores/authStore.ts` (Zustand)
- **Service:** `apps/frontend/src/services/auth.service.ts` (Axios)
- **Types:** `apps/frontend/src/types/auth.types.ts`

## APIs Consumidas

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/auth/login` | POST | Autenticación con email/password o teléfono |
| `/auth/register` | POST | Registro de nuevo usuario |
| `/auth/forgot-password` | POST | Solicitar email de recuperación de contraseña |
| `/auth/reset-password` | POST | Confirmar nueva contraseña con token |
| `/auth/verify-email` | GET | Verificar email con token de activación |
| `/auth/session` | GET | Validar sesión actual y obtener información de expiración |
| `/auth/logout` | POST | Cerrar sesión y revocar token |
| `/auth/social/:provider` | GET | Iniciar flujo OAuth con proveedor social |
| `/auth/social/callback` | GET | Callback de OAuth providers |
| `/auth/change-password` | POST | Change user password |
| `/auth/2fa/status` | GET | Get 2FA status for current user |
| `/auth/2fa/setup` | POST | Generate QR code and secret for 2FA setup |
| `/auth/2fa/enable` | POST | Enable 2FA with verification code |
| `/auth/2fa/disable` | POST | Disable 2FA with verification code |
| `/auth/2fa/backup-codes` | POST | Regenerate backup codes |
| `/auth/sessions` | GET | List all active sessions |
| `/auth/sessions/:id` | DELETE | Revoke a specific session |
| `/auth/logout-all` | POST | Revoke all sessions except current |

## Uso Rápido

```tsx
import { Login, Register } from '@/modules/auth';
import { useAuthStore } from '@/stores/authStore';

// Uso en router
<Route path="/login" element={<Login />} />
<Route path="/register" element={<Register />} />

// Uso de store
function MyComponent() {
  const { user, isAuthenticated, login, logout } = useAuthStore();

  const handleLogin = async () => {
    await login('user@example.com', 'password123');
  };

  return (
    <div>
      {isAuthenticated ? (
        <>
          <p>Bienvenido, {user?.email}</p>
          <button onClick={logout}>Cerrar sesión</button>
        </>
      ) : (
        <button onClick={handleLogin}>Iniciar sesión</button>
      )}
    </div>
  );
}
```

## Características Principales

### Autenticación Social
- ✅ Google OAuth 2.0
- ✅ Facebook Login
- ✅ Apple Sign In
- Flujo seguro con PKCE (Proof Key for Code Exchange)

### Autenticación por Teléfono
- SMS verification con código de 6 dígitos
- Rate limiting para prevenir abuso
- Soporte internacional de números

### Seguridad
- JWT tokens con expiración configurable
- Refresh tokens para renovación automática
- Device tracking y fingerprinting
- Gestión de sesiones concurrentes
- IP logging para auditoría

### Gestión de Sesiones
- Visualización de dispositivos activos
- Revocación individual de sesiones
- Notificaciones de nuevos inicios de sesión
- Timeout automático por inactividad

## Tests

```bash
# Tests unitarios del módulo
npm run test modules/auth

# Tests E2E de flujos de autenticación
npm run test:e2e auth
```

## Roadmap

### Completados (P0)
- [x] **2FA Implementation** - Autenticación de dos factores con TOTP (setup wizard, verify modal, backup codes)
- [x] **Session Management** - Lista de sesiones activas con revocación individual y masiva
- [x] **Password Change** - Cambio de contraseña desde SecuritySettings
- [x] **Password Recovery** - Flujo completo de recuperación (forgot + reset)

### Pendientes - Alta Prioridad (P0)
- [ ] **Auto-refresh Tokens** (60h) - Renovación automática de JWT sin logout forzado
- [ ] **CSRF Protection** (16h) - Protección contra Cross-Site Request Forgery

### Mediano Plazo (P1-P2)
- [ ] **Biometric Authentication** (30h) - Face ID / Touch ID para mobile
- [ ] **Magic Link Login** (20h) - Login sin contraseña via email
- [ ] **Session Analytics** (15h) - Dashboard de actividad de sesiones

### Largo Plazo (P3)
- [ ] **WebAuthn/FIDO2** (50h) - Autenticación con hardware keys
- [ ] **Account Linking** (25h) - Vincular múltiples proveedores OAuth a una cuenta
- [ ] **Passwordless Login** (40h) - Login completamente sin contraseña

## Dependencias

- `zustand` - State management
- `axios` - HTTP client
- `react-router-dom` - Routing
- `zod` - Validation schemas

## Documentación Relacionada

- **ET Specs:** No aplica (funcionalidad base)
- **User Stories:** US-AUTH-001 a US-AUTH-005
- **Backend API Docs:** `/docs/api/auth.md`
- **Security Guidelines:** `/docs/security/authentication.md`

---

**Última actualización:** 2026-01-25
**Autor:** Claude Opus 4.5
