---
id: EPIC-MCH-002
type: Epic
title: "MCH-002: Autenticacion"
code: MCH-002
status: Completado
phase: 1
priority: P0
story_points: 13
created_at: 2026-01-05
updated_at: 2026-01-17
simco_version: "4.0.1"
dependencies:
  blocks: ["MCH-003", "MCH-004"]
  depends_on: ["MCH-001"]
---

# MCH-002: Autenticacion

## Metadata
- **Codigo:** MCH-002
- **Fase:** 1 - MVP Core
- **Prioridad:** P0 (Critica)
- **Estado:** Completado
- **Story Points:** 13
- **Fecha inicio:** 2026-01-05
- **Fecha fin:** 2026-01-06

## Descripcion

Sistema de autenticacion adaptado a micro-negocios mexicanos: login via telefono con OTP (SMS/WhatsApp), PIN de 4 digitos para acceso rapido, soporte biometrico opcional, y JWT para sesiones.

## Objetivos

1. Login via telefono + OTP
2. PIN de 4 digitos para acceso rapido
3. Soporte biometrico (Face ID/huella)
4. Gestion de sesiones JWT
5. Roles: owner, employee, viewer

## Alcance

### Incluido
- Registro con telefono
- OTP via SMS/WhatsApp
- PIN de 4 digitos
- JWT con refresh tokens
- Roles basicos (owner/employee/viewer)
- Logout y revocacion de sesiones

### Excluido
- OAuth (Google, Facebook) - fase posterior
- 2FA via TOTP - fase posterior
- SSO empresarial

## Flujos de Usuario

### Registro Inicial
```
1. Usuario ingresa telefono
2. Se envia OTP via SMS/WhatsApp
3. Usuario verifica OTP
4. Usuario configura PIN de 4 digitos
5. Se crea tenant automaticamente (para owners)
6. Usuario accede al dashboard
```

### Login Subsecuente
```
1. Usuario ingresa telefono
2. Usuario ingresa PIN de 4 digitos
   - O usa biometrico si esta configurado
3. JWT generado
4. Acceso al sistema
```

### Login por OTP (sin PIN)
```
1. Usuario selecciona "Olvide mi PIN"
2. Se envia OTP
3. Usuario verifica OTP
4. Puede reconfigurrar PIN
```

## Modelo de Datos

### Tablas (schema: auth)
- `users`: id, tenant_id, phone, email, password_hash, name, role, pin_hash, status
- `sessions`: id, user_id, token, device_info, expires_at, revoked_at
- `roles`: id, tenant_id, name, permissions (JSONB)

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /auth/register | Registro nuevo usuario |
| POST | /auth/send-otp | Enviar OTP a telefono |
| POST | /auth/verify-otp | Verificar OTP |
| POST | /auth/set-pin | Configurar PIN |
| POST | /auth/login | Login con telefono + PIN |
| POST | /auth/login-otp | Login solo con OTP |
| GET | /auth/me | Usuario actual |
| POST | /auth/refresh | Renovar JWT |
| POST | /auth/logout | Cerrar sesion |
| DELETE | /auth/sessions | Revocar todas las sesiones |

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL auth schema | Completado | `04-auth.sql` |
| auth.module.ts | Completado | `modules/auth/` |
| JwtStrategy | Completado | `strategies/jwt.strategy.ts` |
| Guards | Completado | `guards/` |

## Dependencias

### Depende de
- MCH-001 (Infraestructura)

### Bloquea a
- MCH-003 (Productos)
- MCH-004 (POS)
- Todos los modulos que requieren auth

## Criterios de Aceptacion de Epica

- [x] Registro con telefono funcional
- [x] OTP se envia correctamente
- [x] PIN de 4 digitos funciona
- [x] JWT se genera y valida
- [x] Roles owner/employee/viewer funcionan
- [x] Sesiones se pueden revocar

---

## Historias de Usuario

### MCH-US-010: Registro con Telefono y OTP

**Como** propietario de un micro-negocio
**Quiero** registrarme usando mi numero de telefono y verificar con OTP
**Para** crear mi cuenta de forma sencilla sin necesidad de email

**Story Points:** 3

**Criterios de Aceptacion:**
- [CA-010-1] El usuario puede ingresar su numero de telefono mexicano (10 digitos)
- [CA-010-2] Se envia OTP de 6 digitos via SMS o WhatsApp
- [CA-010-3] OTP expira en 5 minutos
- [CA-010-4] Maximo 3 intentos de verificacion antes de bloqueo temporal
- [CA-010-5] Al verificar exitosamente, se crea el tenant automaticamente

**Tareas:**
| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-010-01 | DDL tabla auth.users con campos phone, pin_hash | DDL | Completado |
| MCH-TT-010-02 | Endpoint POST /auth/register | Backend | Completado |
| MCH-TT-010-03 | Endpoint POST /auth/send-otp | Backend | Completado |
| MCH-TT-010-04 | Endpoint POST /auth/verify-otp | Backend | Completado |
| MCH-TT-010-05 | Servicio OTPService con integracion SMS | Backend | Completado |
| MCH-TT-010-06 | Tests unitarios de registro | Test | Completado |

---

### MCH-US-011: Login con PIN de 4 Digitos

**Como** usuario registrado
**Quiero** acceder a mi cuenta usando un PIN de 4 digitos
**Para** entrar rapidamente sin tener que esperar un OTP cada vez

**Story Points:** 3

**Criterios de Aceptacion:**
- [CA-011-1] Usuario puede configurar PIN de 4 digitos despues del registro
- [CA-011-2] PIN se almacena hasheado (bcrypt)
- [CA-011-3] Login exitoso con telefono + PIN genera JWT
- [CA-011-4] 5 intentos fallidos bloquean la cuenta temporalmente (15 min)
- [CA-011-5] Opcion "Olvide mi PIN" envia OTP para recuperacion

**Tareas:**
| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-011-01 | Endpoint POST /auth/set-pin | Backend | Completado |
| MCH-TT-011-02 | Endpoint POST /auth/login (telefono + PIN) | Backend | Completado |
| MCH-TT-011-03 | Endpoint POST /auth/login-otp (recuperacion) | Backend | Completado |
| MCH-TT-011-04 | Logica de bloqueo por intentos fallidos | Backend | Completado |
| MCH-TT-011-05 | Tests unitarios de login | Test | Completado |

---

### MCH-US-012: Gestion de Sesiones JWT

**Como** sistema de autenticacion
**Quiero** manejar sesiones con JWT y refresh tokens
**Para** mantener sesiones seguras y permitir logout remoto

**Story Points:** 5

**Criterios de Aceptacion:**
- [CA-012-1] JWT access token con expiracion de 7 dias
- [CA-012-2] Refresh token con expiracion de 30 dias
- [CA-012-3] Endpoint GET /auth/me retorna usuario actual
- [CA-012-4] Endpoint POST /auth/refresh renueva el JWT
- [CA-012-5] Endpoint POST /auth/logout revoca sesion actual
- [CA-012-6] Endpoint DELETE /auth/sessions revoca todas las sesiones
- [CA-012-7] Sessions incluyen device_info para identificacion

**Tareas:**
| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-012-01 | DDL tabla auth.sessions | DDL | Completado |
| MCH-TT-012-02 | JwtStrategy con Passport | Backend | Completado |
| MCH-TT-012-03 | Endpoint GET /auth/me | Backend | Completado |
| MCH-TT-012-04 | Endpoint POST /auth/refresh | Backend | Completado |
| MCH-TT-012-05 | Endpoint POST /auth/logout | Backend | Completado |
| MCH-TT-012-06 | Endpoint DELETE /auth/sessions | Backend | Completado |
| MCH-TT-012-07 | Tests de sesiones | Test | Completado |

---

### MCH-US-013: Sistema de Roles Basicos

**Como** propietario del negocio
**Quiero** asignar roles a mis empleados (owner, employee, viewer)
**Para** controlar que acciones puede realizar cada persona

**Story Points:** 2

**Criterios de Aceptacion:**
- [CA-013-1] Rol owner tiene acceso completo al tenant
- [CA-013-2] Rol employee puede operar POS y ver reportes basicos
- [CA-013-3] Rol viewer solo puede consultar sin modificar
- [CA-013-4] Roles se almacenan en tabla auth.roles con permisos JSONB
- [CA-013-5] Guards validan permisos en cada endpoint protegido

**Tareas:**
| ID | Tarea | Tipo | Estado |
|----|-------|------|--------|
| MCH-TT-013-01 | DDL tabla auth.roles | DDL | Completado |
| MCH-TT-013-02 | RolesGuard para proteger endpoints | Backend | Completado |
| MCH-TT-013-03 | Decorador @Roles() para controllers | Backend | Completado |
| MCH-TT-013-04 | Seed de roles por defecto | Backend | Completado |
| MCH-TT-013-05 | Tests de autorizacion | Test | Completado |

---

## Resumen de Story Points

| Historia | SP | Estado |
|----------|-----|--------|
| MCH-US-010: Registro con Telefono y OTP | 3 | Completado |
| MCH-US-011: Login con PIN de 4 Digitos | 3 | Completado |
| MCH-US-012: Gestion de Sesiones JWT | 5 | Completado |
| MCH-US-013: Sistema de Roles Basicos | 2 | Completado |
| **TOTAL** | **13** | **Completado** |

---

## Configuracion

```typescript
// JWT Config
{
  secret: process.env.JWT_SECRET,
  expiresIn: '7d',
  refreshExpiresIn: '30d'
}

// OTP Config
{
  length: 6,
  expiresIn: '5m',
  maxAttempts: 3
}
```

---

**Ultima actualizacion:** 2026-01-17