workspace-v1/shared/libs/auth/README.md

# Autenticación y Autorización

**Versión:** 1.0.0
**Origen:** projects/gamilit
**Estado:** Producción
**Última actualización:** 2025-12-08

---

## Descripción

Sistema completo de autenticación y autorización basado en JWT con:
- Registro y login de usuarios
- Tokens de acceso y refresh
- Gestión de sesiones
- Guards y decoradores
- Sistema de roles (RBAC)
- Recuperación de contraseña
- Verificación de email

---

## Características

| Característica | Descripción |
|----------------|-------------|
| JWT Access Tokens | Tokens de corta duración (15min) para autenticación |
| JWT Refresh Tokens | Tokens de larga duración (7d) para renovación |
| Password Hashing | bcrypt con cost 10 |
| Session Management | Sesiones persistentes en BD con metadata |
| Role-Based Access | Sistema RBAC con guards y decoradores |
| Multi-tenant | Soporte para múltiples tenants |
| Security Logging | Registro de intentos de autenticación |

---

## Stack Tecnológico

```yaml
backend:
  framework: NestJS
  orm: TypeORM
  auth_library: "@nestjs/passport"
  jwt_library: "@nestjs/jwt"
  hashing: bcrypt
  validation: class-validator

database:
  engine: PostgreSQL
  schemas:
    - auth (usuarios principales)
    - auth_management (perfiles, sesiones, tokens)
```

---

## Dependencias NPM

```json
{
  "@nestjs/jwt": "^10.x",
  "@nestjs/passport": "^10.x",
  "passport": "^0.7.x",
  "passport-jwt": "^4.x",
  "bcrypt": "^5.x",
  "class-validator": "^0.14.x",
  "class-transformer": "^0.5.x"
}
```

---

## Tablas Requeridas

| Schema | Tabla | Propósito |
|--------|-------|-----------|
| auth | users | Usuarios del sistema |
| auth_management | profiles | Perfiles extendidos |
| auth_management | tenants | Multi-tenancy |
| auth_management | roles | Definición de roles |
| auth_management | user_roles | Asignación de roles |
| auth_management | user_sessions | Sesiones activas |
| auth_management | auth_attempts | Log de intentos |
| auth_management | password_reset_tokens | Tokens de reset |
| auth_management | email_verification_tokens | Tokens de verificación |

---

## Estructura del Módulo

```
auth/
├── auth.module.ts              # Módulo principal
├── controllers/
│   ├── auth.controller.ts      # Login, register, refresh
│   ├── password.controller.ts  # Reset, change password
│   └── users.controller.ts     # Profile, preferences
├── services/
│   ├── auth.service.ts         # Lógica de autenticación
│   ├── session-management.service.ts
│   ├── security.service.ts
│   ├── password-recovery.service.ts
│   └── email-verification.service.ts
├── entities/
│   ├── user.entity.ts
│   ├── profile.entity.ts
│   ├── tenant.entity.ts
│   ├── role.entity.ts
│   ├── user-role.entity.ts
│   ├── user-session.entity.ts
│   ├── auth-attempt.entity.ts
│   └── ...
├── dto/
│   ├── login.dto.ts
│   ├── register-user.dto.ts
│   ├── refresh-token.dto.ts
│   ├── change-password.dto.ts
│   └── ...
├── guards/
│   ├── jwt-auth.guard.ts
│   └── roles.guard.ts
├── strategies/
│   └── jwt.strategy.ts
├── decorators/
│   └── roles.decorator.ts
└── __tests__/
    ├── auth.controller.spec.ts
    ├── auth.service.spec.ts
    └── ...
```

---

## Endpoints Principales

| Método | Ruta | Descripción | Auth |
|--------|------|-------------|------|
| POST | /auth/register | Registro público | No |
| POST | /auth/login | Login con email/password | No |
| POST | /auth/refresh | Renovar access token | Refresh Token |
| POST | /auth/logout | Cerrar sesión | JWT |
| GET | /auth/me | Obtener usuario actual | JWT |
| POST | /auth/change-password | Cambiar contraseña | JWT |
| POST | /auth/request-reset | Solicitar reset password | No |
| POST | /auth/reset-password | Reset con token | Token |

---

## Uso Rápido

### 1. Proteger una ruta con JWT

```typescript
import { Controller, Get, UseGuards, Request } from '@nestjs/common';
import { JwtAuthGuard } from '@/modules/auth/guards';

@Controller('protected')
export class ProtectedController {
  @Get()
  @UseGuards(JwtAuthGuard)
  getProtectedData(@Request() req) {
    // req.user contiene el payload del JWT
    return { userId: req.user.id, email: req.user.email };
  }
}
```

### 2. Proteger por roles

```typescript
import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard, RolesGuard } from '@/modules/auth/guards';
import { Roles } from '@/modules/auth/decorators';
import { RoleEnum } from '@/shared/constants';

@Controller('admin')
@UseGuards(JwtAuthGuard, RolesGuard)
export class AdminController {
  @Get()
  @Roles(RoleEnum.ADMIN, RoleEnum.SUPER_ADMIN)
  adminOnly() {
    return { message: 'Solo para administradores' };
  }
}
```

### 3. Configurar el módulo

```typescript
// app.module.ts
import { AuthModule } from '@/modules/auth/auth.module';

@Module({
  imports: [
    AuthModule,
    // ... otros módulos
  ],
})
export class AppModule {}
```

---

## Variables de Entorno Requeridas

```env
# JWT
JWT_SECRET=your-super-secret-key-change-in-production
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

# Base de datos (para TypeORM)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=your_database
DB_USER=your_user
DB_PASSWORD=your_password
```

---

## Flujos de Autenticación

### Login Flow

```
1. Cliente envía email + password
2. AuthService valida credenciales
3. Si válidas:
   - Genera access token (15min)
   - Genera refresh token (7d)
   - Crea sesión en BD
   - Registra intento exitoso
4. Retorna tokens + user data
```

### Refresh Flow

```
1. Cliente envía refresh token
2. AuthService verifica token
3. Busca sesión en BD por hash del refresh token
4. Si válida y no expirada:
   - Genera nuevos tokens
   - Actualiza sesión
5. Retorna nuevos tokens
```

---

## Seguridad

- Passwords hasheados con bcrypt (cost 10)
- Refresh tokens hasheados en BD (SHA256)
- Tokens JWT con expiración corta
- Sesiones con metadata (IP, User-Agent, dispositivo)
- Logging de todos los intentos de auth
- Soft delete para usuarios (no eliminación física)

---

## Adaptaciones Necesarias

Al implementar en un nuevo proyecto, ajustar:

1. **Enum de roles**: Definir roles específicos del proyecto
2. **Schema de BD**: Puede ser diferente a `auth`/`auth_management`
3. **Campos de User entity**: Agregar/quitar según necesidades
4. **Conexión TypeORM**: Ajustar nombre de conexión si no es 'auth'
5. **Variables de entorno**: Configurar JWT_SECRET único

---

## Referencias

- [NestJS Authentication](https://docs.nestjs.com/security/authentication)
- [Passport.js](http://www.passportjs.org/)
- [JWT.io](https://jwt.io/)

---

**Mantenido por:** Sistema NEXUS
**Proyecto origen:** Gamilit Platform