michangarrito/docs/01-epicas/MCH-002-autenticacion.md

id	type	title	code	status	phase	priority	story_points	created_at	updated_at	simco_version	dependencies
EPIC-MCH-002	Epic	MCH-002: Autenticacion	MCH-002	Completado	1	P0	13	2026-01-05	2026-01-17	4.0.1	blocks depends_on MCH-003 MCH-004 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

• Registro con telefono funcional
• OTP se envia correctamente
• PIN de 4 digitos funciona
• JWT se genera y valida
• Roles owner/employee/viewer funcionan
• 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

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

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

---

Ultima actualizacion: 2026-01-17