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

```yaml
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:**
```typescript
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:**
```typescript
// Uso en controladores
@UseGuards(JwtAuthGuard)
@Get('profile')
getProfile(@Request() req) {
  return req.user; // Usuario del token JWT
}
```

**roles.guard.reference.ts:**
```typescript
// 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

```typescript
// 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

```bash
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

```sql
-- 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

```typescript
// 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

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

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

### 3. Agregar roles a usuarios existentes

```typescript
// 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/