trading-platform-frontend-v2/src/modules/auth

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

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

# 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)

• 2FA Implementation - Autenticación de dos factores con TOTP (setup wizard, verify modal, backup codes)
• Session Management - Lista de sesiones activas con revocación individual y masiva
• Password Change - Cambio de contraseña desde SecuritySettings
• 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