workspace-v1/shared/catalog/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

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

{
  "@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

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

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

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

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

---

Variables de Entorno Requeridas

# 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
• Passport.js
• JWT.io

---

Mantenido por: Sistema NEXUS Proyecto origen: Gamilit Platform