# _MAP: OQI-001 - Fundamentos y Autenticación

**Ultima actualizacion:** 2025-12-05
**Estado:** ✅ Completado
**Version:** 1.0.0
**Épica:** OQI-001
**Nombre:** Fundamentos y Autenticación Multi-proveedor
**Story Points:** 50 SP
**Presupuesto:** $25,000 MXN
**Prioridad:** P0 (Crítica)

---

## Proposito

Esta épica establece la infraestructura base del proyecto y el sistema de autenticación completo con soporte para múltiples proveedores OAuth, autenticación por email/password, teléfono (SMS/WhatsApp), y seguridad avanzada con 2FA.

---

## Contenido

### Estructura de Carpetas

```
OQI-001-fundamentos-auth/
├── _MAP.md                          # Este índice
├── README.md                        # Resumen ejecutivo
├── requerimientos/                  # Requerimientos funcionales
│   ├── RF-AUTH-001-oauth.md        # OAuth multi-proveedor
│   ├── RF-AUTH-002-email.md        # Email/password auth
│   ├── RF-AUTH-003-phone.md        # Phone auth (SMS/WhatsApp)
│   ├── RF-AUTH-004-2fa.md          # Two-factor authentication
│   └── RF-AUTH-005-sessions.md     # Gestión de sesiones
├── especificaciones/                # Especificaciones técnicas
│   ├── ET-AUTH-001-oauth.md        # Spec OAuth providers
│   ├── ET-AUTH-002-jwt.md          # Spec JWT tokens
│   ├── ET-AUTH-003-database.md     # Spec esquema DB
│   ├── ET-AUTH-004-api.md          # Spec API endpoints
│   └── ET-AUTH-005-security.md     # Spec seguridad
├── historias-usuario/               # User stories
│   ├── US-AUTH-001-registro-email.md
│   ├── US-AUTH-002-login-email.md
│   ├── US-AUTH-003-oauth-google.md
│   ├── US-AUTH-004-oauth-facebook.md
│   ├── US-AUTH-005-oauth-twitter.md
│   ├── US-AUTH-006-oauth-apple.md
│   ├── US-AUTH-007-oauth-github.md
│   ├── US-AUTH-008-phone-sms.md
│   ├── US-AUTH-009-phone-whatsapp.md
│   ├── US-AUTH-010-2fa-setup.md
│   ├── US-AUTH-011-password-reset.md
│   └── US-AUTH-012-session-management.md
├── implementacion/                  # Trazabilidad
│   └── TRACEABILITY.yml            # Mapeo req -> código
└── pruebas/                         # Tests
    ├── TEST-AUTH-001-unit.md
    └── TEST-AUTH-002-integration.md
```

---

## Requerimientos Funcionales

| ID | Nombre | Prioridad | Estado |
|----|--------|-----------|--------|
| [RF-AUTH-001](./requerimientos/RF-AUTH-001-oauth.md) | OAuth Multi-proveedor | P0 | ✅ |
| [RF-AUTH-002](./requerimientos/RF-AUTH-002-email.md) | Autenticación Email | P0 | ✅ |
| [RF-AUTH-003](./requerimientos/RF-AUTH-003-phone.md) | Autenticación Teléfono | P1 | ✅ |
| [RF-AUTH-004](./requerimientos/RF-AUTH-004-2fa.md) | Two-Factor Auth | P1 | ✅ |
| [RF-AUTH-005](./requerimientos/RF-AUTH-005-sessions.md) | Gestión Sesiones | P0 | ✅ |

---

## Especificaciones Técnicas

| ID | Nombre | Componente | Estado |
|----|--------|------------|--------|
| [ET-AUTH-001](./especificaciones/ET-AUTH-001-oauth.md) | OAuth Providers | Backend | ✅ |
| [ET-AUTH-002](./especificaciones/ET-AUTH-002-jwt.md) | JWT Tokens | Backend | ✅ |
| [ET-AUTH-003](./especificaciones/ET-AUTH-003-database.md) | Esquema DB | Database | ✅ |
| [ET-AUTH-004](./especificaciones/ET-AUTH-004-api.md) | API Endpoints | Backend | ✅ |
| [ET-AUTH-005](./especificaciones/ET-AUTH-005-security.md) | Seguridad | Backend | ✅ |

---

## Historias de Usuario

| ID | Titulo | Puntos | Estado |
|----|--------|--------|--------|
| [US-AUTH-001](./historias-usuario/US-AUTH-001-registro-email.md) | Registro con Email | 5 | ✅ |
| [US-AUTH-002](./historias-usuario/US-AUTH-002-login-email.md) | Login con Email | 3 | ✅ |
| [US-AUTH-003](./historias-usuario/US-AUTH-003-oauth-google.md) | Login con Google | 5 | ✅ |
| [US-AUTH-004](./historias-usuario/US-AUTH-004-oauth-facebook.md) | Login con Facebook | 5 | ✅ |
| [US-AUTH-005](./historias-usuario/US-AUTH-005-oauth-twitter.md) | Login con X/Twitter | 5 | ✅ |
| [US-AUTH-006](./historias-usuario/US-AUTH-006-oauth-apple.md) | Login con Apple | 5 | ✅ |
| [US-AUTH-007](./historias-usuario/US-AUTH-007-oauth-github.md) | Login con GitHub | 3 | ✅ |
| [US-AUTH-008](./historias-usuario/US-AUTH-008-phone-sms.md) | Login con SMS | 5 | ✅ |
| [US-AUTH-009](./historias-usuario/US-AUTH-009-phone-whatsapp.md) | Login con WhatsApp | 5 | ✅ |
| [US-AUTH-010](./historias-usuario/US-AUTH-010-2fa-setup.md) | Configurar 2FA | 5 | ✅ |
| [US-AUTH-011](./historias-usuario/US-AUTH-011-password-reset.md) | Recuperar Contraseña | 3 | ✅ |
| [US-AUTH-012](./historias-usuario/US-AUTH-012-session-management.md) | Gestión Sesiones | 3 | ✅ |

**Total Story Points:** 52 SP (ajustado a 50 SP en planificación)

---

## Stack Técnico

### Backend

| Tecnología | Versión | Uso |
|------------|---------|-----|
| Express.js | 4.18.x | API Server |
| Passport.js | 0.7.x | OAuth strategies |
| jsonwebtoken | 9.x | JWT tokens |
| bcryptjs | 2.x | Password hashing |
| speakeasy | 2.x | TOTP 2FA |
| Twilio | 4.x | SMS/WhatsApp |
| Nodemailer | 6.x | Email sending |
| Zod | 3.x | Validation |

### Frontend

| Tecnología | Versión | Uso |
|------------|---------|-----|
| React | 18.x | UI Framework |
| TanStack Query | 5.x | Data fetching |
| Zustand | 4.x | Auth state |
| React Router | 6.x | Routing |

### Database

| Tecnología | Schema | Tablas |
|------------|--------|--------|
| PostgreSQL | public | users, profiles, oauth_accounts, sessions |
| Redis | - | Session cache, rate limiting |

---

## Proveedores OAuth Soportados

| Proveedor | Client ID Config | Scopes |
|-----------|------------------|--------|
| Google | `GOOGLE_CLIENT_ID` | profile, email |
| Facebook | `FACEBOOK_APP_ID` | email, public_profile |
| X/Twitter | `TWITTER_CLIENT_ID` | tweet.read, users.read |
| Apple | `APPLE_CLIENT_ID` | name, email |
| GitHub | `GITHUB_CLIENT_ID` | read:user, user:email |

---

## Métricas de la Épica

| Métrica | Target | Actual |
|---------|--------|--------|
| Story Points | 50 | 50 ✅ |
| Cobertura Tests | 80% | TBD |
| Endpoints API | 25 | 25 ✅ |
| Proveedores OAuth | 5 | 5 ✅ |
| Tiempo Response Auth | <200ms | TBD |

---

## Dependencias

```
OQI-001 (Auth) ──────────┬──▶ OQI-002 (Education)
                         ├──▶ OQI-003 (Trading)
                         ├──▶ OQI-004 (Investment)
                         └──▶ OQI-005 (Payments)
```

Todas las demás épicas dependen de OQI-001 para autenticación y autorización.

---

## Criterios de Aceptación

- [x] Usuario puede registrarse con email y verificar cuenta
- [x] Usuario puede hacer login con email/password
- [x] Usuario puede autenticarse con Google
- [x] Usuario puede autenticarse con Facebook
- [x] Usuario puede autenticarse con X/Twitter
- [x] Usuario puede autenticarse con Apple
- [x] Usuario puede autenticarse con GitHub
- [x] Usuario puede autenticarse con SMS OTP
- [x] Usuario puede autenticarse con WhatsApp OTP
- [x] Usuario puede configurar 2FA con TOTP
- [x] Usuario puede recuperar contraseña
- [x] Usuario puede gestionar sesiones activas
- [x] Rate limiting implementado (5 req/15min auth)
- [x] Tokens JWT con refresh implementado

---

## Referencias

- [Fase MVP](../_MAP.md)
- [Arquitectura General](../../00-vision-general/ARQUITECTURA-GENERAL.md)
- [Stack Tecnológico](../../00-vision-general/STACK-TECNOLOGICO.md)
- [ADR-003: Autenticación Multi-proveedor](../../97-adr/ADR-003-autenticacion-multiproveedor.md)
