# US-AUTH-010: Configurar 2FA

**Version:** 1.0.0
**Fecha:** 2025-12-05
**Estado:** ✅ Implementado
**Story Points:** 5
**Prioridad:** P1 (Alta)
**Épica:** [OQI-001](../_MAP.md)

---

## Historia de Usuario

**Como** usuario de OrbiQuant
**Quiero** poder activar autenticación de dos factores
**Para** proteger mi cuenta con una capa adicional de seguridad

---

## Criterios de Aceptación

### AC-001: Acceso a configuración 2FA

**Dado** que estoy logueado en mi cuenta
**Cuando** voy a Configuración > Seguridad
**Entonces** debería ver una opción para "Activar autenticación de dos factores"

### AC-002: Generación de código QR

**Dado** que hago click en "Activar 2FA"
**Cuando** se inicia el proceso de configuración
**Entonces** debería ver:
- Un código QR para escanear
- El secreto manual como alternativa
- Instrucciones claras

### AC-003: Lista de apps compatibles

**Dado** que estoy configurando 2FA
**Cuando** veo las instrucciones
**Entonces** debería ver una lista de apps compatibles:
- Google Authenticator
- Microsoft Authenticator
- Authy
- 1Password

### AC-004: Verificación de código

**Dado** que escaneé el código QR con mi app
**Cuando** ingreso el código de 6 dígitos generado
**Entonces** debería verificarse correctamente si es válido

### AC-005: Código inválido

**Dado** que escaneé el código QR con mi app
**Cuando** ingreso un código incorrecto
**Entonces** debería ver "Código incorrecto, intenta de nuevo"

### AC-006: Generación de backup codes

**Dado** que verifico el código correctamente
**Cuando** se activa el 2FA
**Entonces** debería:
1. Ver 10 códigos de respaldo
2. Poder copiarlos al portapapeles
3. Poder descargarlos como archivo
4. Ver advertencia de guardarlos en lugar seguro

### AC-007: Confirmación de guardado

**Dado** que veo mis códigos de respaldo
**Cuando** no confirmo que los guardé
**Entonces** no debería poder continuar

### AC-008: 2FA activado exitosamente

**Dado** que confirmé guardar mis códigos
**Cuando** continúo
**Entonces** debería:
1. Ver "2FA activado exitosamente"
2. Recibir email de confirmación
3. Ver indicador de 2FA activo en mi perfil

### AC-009: Login con 2FA

**Dado** que tengo 2FA activado
**Cuando** hago login con email/password
**Entonces** debería:
1. Ver un segundo paso pidiendo código 2FA
2. Poder ingresar código de mi app
3. Tener opción de usar código de respaldo

### AC-010: Desactivar 2FA

**Dado** que tengo 2FA activado
**Cuando** intento desactivarlo
**Entonces** debería:
1. Ingresar un código 2FA válido
2. Confirmar la acción
3. Recibir email de notificación

---

## Flujo Visual

```
┌──────────────────────────────────────────────────────────────────────────┐
│                                                                          │
│  PASO 1: Configuración de seguridad                                      │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                                                                    │ │
│  │  ⚙️ Configuración > Seguridad                                      │ │
│  │                                                                    │ │
│  │  ┌──────────────────────────────────────────────────────────────┐│ │
│  │  │                                                              ││ │
│  │  │  🔐 Autenticación de dos factores                           ││ │
│  │  │                                                              ││ │
│  │  │  Estado: ❌ Desactivado                                      ││ │
│  │  │                                                              ││ │
│  │  │  Agrega una capa extra de seguridad a tu cuenta.            ││ │
│  │  │  Necesitarás tu teléfono para iniciar sesión.               ││ │
│  │  │                                                              ││ │
│  │  │  [Activar 2FA]                                              ││ │
│  │  │                                                              ││ │
│  │  └──────────────────────────────────────────────────────────────┘│ │
│  │                                                                    │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                              │                                           │
│                              ▼                                           │
│  PASO 2: Escanear código QR                                              │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                                                                    │ │
│  │  📱 Configura tu aplicación de autenticación                       │ │
│  │                                                                    │ │
│  │  1. Descarga una app de autenticación:                            │ │
│  │     • Google Authenticator                                        │ │
│  │     • Microsoft Authenticator                                     │ │
│  │     • Authy                                                       │ │
│  │                                                                    │ │
│  │  2. Escanea este código QR:                                       │ │
│  │                                                                    │ │
│  │     ┌─────────────────┐                                           │ │
│  │     │  ▄▄▄▄▄  ▄▄▄▄▄  │                                           │ │
│  │     │  █   █  █   █  │                                           │ │
│  │     │  █████  █████  │                                           │ │
│  │     │  █   █  █   █  │                                           │ │
│  │     │  ▀▀▀▀▀  ▀▀▀▀▀  │                                           │ │
│  │     └─────────────────┘                                           │ │
│  │                                                                    │ │
│  │  ¿No puedes escanear? Ingresa este código manualmente:            │ │
│  │  JBSWY3DPEHPK3PXP  [Copiar]                                       │ │
│  │                                                                    │ │
│  │  3. Ingresa el código de 6 dígitos:                               │ │
│  │     ┌─────────────────────────────┐                               │ │
│  │     │  _ _ _ _ _ _                │                               │ │
│  │     └─────────────────────────────┘                               │ │
│  │                                                                    │ │
│  │  [Cancelar]                               [Verificar y activar]   │ │
│  │                                                                    │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                              │                                           │
│                              ▼                                           │
│  PASO 3: Guardar códigos de respaldo                                     │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                                                                    │ │
│  │  🔑 Guarda tus códigos de respaldo                                 │ │
│  │                                                                    │ │
│  │  ⚠️ IMPORTANTE: Guarda estos códigos en un lugar seguro.          │ │
│  │  Si pierdes acceso a tu app de autenticación, estos códigos       │ │
│  │  son la única forma de acceder a tu cuenta.                       │ │
│  │                                                                    │ │
│  │  ┌──────────────────────────────────────────────────────────────┐│ │
│  │  │                                                              ││ │
│  │  │  A1B2C3D4    E5F6G7H8    I9J0K1L2    M3N4O5P6              ││ │
│  │  │  Q7R8S9T0    U1V2W3X4    Y5Z6A7B8    C9D0E1F2              ││ │
│  │  │  G3H4I5J6    K7L8M9N0                                       ││ │
│  │  │                                                              ││ │
│  │  └──────────────────────────────────────────────────────────────┘│ │
│  │                                                                    │ │
│  │  [📋 Copiar códigos]  [⬇️ Descargar como archivo]                 │ │
│  │                                                                    │ │
│  │  ☐ He guardado mis códigos de respaldo en un lugar seguro        │ │
│  │                                                                    │ │
│  │                                              [Continuar]          │ │
│  │                                                                    │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                              │                                           │
│                              ▼                                           │
│  PASO 4: Confirmación                                                    │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                                                                    │ │
│  │  ✅ 2FA activado exitosamente                                      │ │
│  │                                                                    │ │
│  │  Tu cuenta ahora está protegida con autenticación de dos          │ │
│  │  factores. Necesitarás tu app de autenticación cada vez que       │ │
│  │  inicies sesión.                                                  │ │
│  │                                                                    │ │
│  │  [Volver a configuración]                                         │ │
│  │                                                                    │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

---

## Login con 2FA

```
┌──────────────────────────────────────────────────────────────────────────┐
│                                                                          │
│  PASO 1: Login normal                                                    │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                                                                    │ │
│  │  Email: usuario@example.com                                        │ │
│  │  Password: ••••••••                                                │ │
│  │                                                                    │ │
│  │  [Iniciar sesión]                                                  │ │
│  │                                                                    │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                              │                                           │
│                              ▼                                           │
│  PASO 2: Verificación 2FA                                                │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                                                                    │ │
│  │  🔐 Verificación de dos factores                                   │ │
│  │                                                                    │ │
│  │  Ingresa el código de 6 dígitos de tu app de autenticación:       │ │
│  │                                                                    │ │
│  │     ┌─────────────────────────────┐                               │ │
│  │     │  _ _ _ _ _ _                │                               │ │
│  │     └─────────────────────────────┘                               │ │
│  │                                                                    │ │
│  │  [Verificar]                                                       │ │
│  │                                                                    │ │
│  │  ¿Problemas para acceder? Usa un código de respaldo               │ │
│  │                                                                    │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

---

## Notas Técnicas

### Librería TOTP

```typescript
import speakeasy from 'speakeasy';

// Generar secreto
const secret = speakeasy.generateSecret({
  length: 20,
  name: `OrbiQuant:${user.email}`,
  issuer: 'OrbiQuant IA',
});

// Verificar código
const verified = speakeasy.totp.verify({
  secret: user.twoFactorSecret,
  encoding: 'base32',
  token: code,
  window: 1, // ±30 segundos
});
```

### Almacenamiento Seguro

- Secreto TOTP encriptado con AES-256-GCM
- Backup codes hasheados con bcrypt
- Nunca loguear secretos

### Frontend

- Componente: `apps/frontend/src/modules/settings/pages/Security.tsx`
- QR generado con `qrcode` npm package

### Backend

- Service: `apps/backend/src/modules/auth/services/twofa.service.ts`
- Endpoints:
  - `POST /auth/2fa/setup`
  - `POST /auth/2fa/enable`
  - `POST /auth/2fa/verify`
  - `POST /auth/2fa/disable`

---

## Requerimientos Relacionados

- [RF-AUTH-004: Two-Factor Authentication](../requerimientos/RF-AUTH-004-2fa.md)

## Especificaciones Relacionadas

- [ET-AUTH-005: Security](../especificaciones/ET-AUTH-005-security.md)
