# MCH-002: Autenticacion

## Metadata
- **Codigo:** MCH-002
- **Fase:** 1 - MVP Core
- **Prioridad:** P0
- **Estado:** Completado
- **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

- [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

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