workspace-v1/shared/catalog/auth/_reference/README.md

AUTH - REFERENCE IMPLEMENTATION

Versión: 1.0.0 | Fecha: 2025-12-12 | Nivel: Catalog (3)

---

ÍNDICE DE ARCHIVOS

Archivo	Descripción	LOC	Patrón Principal
auth.service.reference.ts	Servicio completo de autenticación JWT	230	Register, Login, Refresh, Logout
jwt-auth.guard.reference.ts	Guard para proteger rutas con JWT	~60	Passport JWT Guard
jwt.strategy.reference.ts	Estrategia Passport para validación JWT	~70	Passport Strategy
roles.guard.reference.ts	Guard para control de acceso basado en roles	~65	RBAC (Role-Based Access Control)

---

CÓMO USAR

Flujo de adopción recomendado

PASO_1: Identificar necesidades
  - ¿Necesitas autenticación completa? → auth.service.reference.ts
  - ¿Solo proteger rutas? → jwt-auth.guard.reference.ts
  - ¿Control por roles? → roles.guard.reference.ts + jwt.strategy.reference.ts

PASO_2: Copiar archivos base
  - Copiar archivos necesarios a tu módulo de auth
  - Renombrar eliminando ".reference"

PASO_3: Adaptar imports
  - Ajustar rutas de entidades (User, Profile, UserSession)
  - Ajustar DTOs según tu esquema
  - Configurar conexión a BD correcta (@InjectRepository)

PASO_4: Configurar variables de entorno
  - JWT_SECRET
  - JWT_EXPIRES_IN (default: 15m)
  - REFRESH_TOKEN_EXPIRES (default: 7d)
  - BCRYPT_COST (default: 10)

PASO_5: Implementar entidades requeridas
  - User: id, email, encrypted_password, role
  - Profile: id, user_id, email, ...
  - UserSession: id, user_id, refresh_token, expires_at, is_revoked

PASO_6: Validar integración
  - npm run build
  - npm run lint
  - Pruebas de endpoints: /auth/register, /auth/login, /auth/refresh

---

PATRONES IMPLEMENTADOS

1. Autenticación JWT (auth.service.reference.ts)

Características:

• Registro con email único
• Password hasheado con bcrypt (cost 10)
• Access token (15m) + Refresh token (7d)
• Gestión de sesiones con revocación
• Refresh token hasheado (SHA-256) en BD

Endpoints típicos:

POST /auth/register   → { accessToken, refreshToken, user }
POST /auth/login      → { accessToken, refreshToken, user }
POST /auth/refresh    → { accessToken, refreshToken, user }
POST /auth/logout     → { message: 'Logout successful' }

2. Guards de protección

jwt-auth.guard.reference.ts:

// Uso en controladores
@UseGuards(JwtAuthGuard)
@Get('profile')
getProfile(@Request() req) {
  return req.user; // Usuario del token JWT
}

roles.guard.reference.ts:

// Control de acceso por roles
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('admin', 'moderator')
@Delete('users/:id')
deleteUser(@Param('id') id: string) {
  // Solo admin y moderator pueden ejecutar
}

3. Estrategia JWT (jwt.strategy.reference.ts)

Funcionalidad:

• Valida tokens en cada request
• Extrae payload del token
• Inyecta req.user con datos del usuario

---

NOTAS DE ADAPTACIÓN

Variables a reemplazar

// EN auth.service.reference.ts
User              → Tu entidad de usuario
Profile           → Tu entidad de perfil (opcional)
UserSession       → Tu entidad de sesiones
RegisterUserDto   → Tu DTO de registro

// EN jwt.strategy.reference.ts
JWT_SECRET        → process.env.JWT_SECRET
userRepository    → Tu repositorio/servicio de usuarios

// EN roles.guard.reference.ts
@Roles()          → Tu decorador custom (crear si no existe)

Dependencias requeridas

npm install --save @nestjs/jwt @nestjs/passport passport passport-jwt bcrypt
npm install --save-dev @types/passport-jwt @types/bcrypt

Esquema de base de datos

-- Tabla users (adaptar según tu schema)
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  encrypted_password VARCHAR(255) NOT NULL,
  role VARCHAR(50) DEFAULT 'user',
  created_at TIMESTAMP DEFAULT NOW()
);

-- Tabla user_sessions
CREATE TABLE user_sessions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  refresh_token VARCHAR(64) NOT NULL, -- SHA-256 hash (64 chars)
  expires_at TIMESTAMP NOT NULL,
  is_revoked BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_user_sessions_refresh_token ON user_sessions(refresh_token);

---

CASOS DE USO COMUNES

1. Integrar autenticación en proyecto nuevo

// 1. Copiar auth.service.reference.ts → auth.service.ts
// 2. Copiar guards y strategy
// 3. Configurar en auth.module.ts:

@Module({
  imports: [
    TypeOrmModule.forFeature([User, Profile, UserSession], 'auth'),
    JwtModule.register({
      secret: process.env.JWT_SECRET,
      signOptions: { expiresIn: '15m' },
    }),
    PassportModule,
  ],
  providers: [AuthService, JwtStrategy, RolesGuard],
  controllers: [AuthController],
  exports: [AuthService],
})
export class AuthModule {}

2. Migrar de autenticación básica a JWT

// Antes: session-based
@UseGuards(SessionGuard)

// Después: JWT-based
@UseGuards(JwtAuthGuard)

3. Agregar roles a usuarios existentes

// 1. Migrar BD: ALTER TABLE users ADD COLUMN role VARCHAR(50) DEFAULT 'user';
// 2. Implementar RolesGuard (roles.guard.reference.ts)
// 3. Usar decorador @Roles() en rutas protegidas

---

CHECKLIST DE VALIDACIÓN

Antes de marcar como completo:

• Build pasa: npm run build
• Lint pasa: npm run lint
• Registro funciona: POST /auth/register
• Login funciona: POST /auth/login
• Refresh funciona: POST /auth/refresh
• Guards protegen rutas correctamente
• Tokens expiran según configuración
• Logout revoca sesión en BD
• Roles bloquean acceso no autorizado

---

REFERENCIAS CRUZADAS

Dependencias en @CATALOG

• session-management: Para gestión avanzada de sesiones multi-dispositivo
• multi-tenancy: Si necesitas autenticación por tenant
• rate-limiting: Proteger endpoints de auth contra brute-force

Relacionado con SIMCO

• @OP_BACKEND: Operaciones de backend (crear service, guards)
• @SIMCO-REUTILIZAR: Este catálogo es candidato para reutilización
• @SIMCO-VALIDAR: Validar implementación antes de deploy

Documentación adicional

• NestJS Auth: https://docs.nestjs.com/security/authentication
• Passport JWT: http://www.passportjs.org/packages/passport-jwt/
• bcrypt: https://github.com/kelektiv/node.bcrypt.js

---

Mantenido por: Core Team | Origen: gamilit/apps/backend/src/modules/auth/