workspace-v1/core/modules/auth/README.md

Auth - Core Module

Modulo: core/modules/auth/ Version: 0.1.0 Fecha: 2026-01-03 Owner: Backend-Agent Estado: desarrollo

---

Descripcion

Modulo de autenticacion compartido que provee guards, decorators y utilidades JWT para proyectos NestJS. Complementa el catalogo core/catalog/auth/ con codigo listo para importar.

---

Instalacion

Prerequisitos

npm install @nestjs/jwt @nestjs/passport passport-jwt bcrypt
npm install -D @types/passport-jwt @types/bcrypt

Configuracion de Paths

{
  "compilerOptions": {
    "paths": {
      "@core/modules/*": ["../../core/modules/*"]
    }
  }
}

---

API Publica (Planificada)

Guards

Guard	Descripcion	Uso
JwtAuthGuard	Protege rutas con JWT	@UseGuards(JwtAuthGuard)
RolesGuard	Verifica roles de usuario	@UseGuards(RolesGuard)
PermissionsGuard	Verifica permisos	@UseGuards(PermissionsGuard)

Decorators

Decorator	Descripcion	Ejemplo
@CurrentUser()	Extrae usuario actual	@CurrentUser() user: User
@Roles()	Define roles requeridos	@Roles('admin', 'editor')
@Public()	Marca ruta como publica	@Public()

Servicios

Servicio	Descripcion
TokenService	Generacion/validacion JWT
PasswordService	Hashing con bcrypt
SessionService	Gestion de sesiones

---

Ejemplos de Uso

Ejemplo 1: Proteger Controller

import { JwtAuthGuard, CurrentUser, Roles } from '@core/modules/auth';

@Controller('users')
@UseGuards(JwtAuthGuard)
export class UsersController {
  @Get('profile')
  getProfile(@CurrentUser() user: User) {
    return user;
  }

  @Get('admin')
  @Roles('admin')
  @UseGuards(RolesGuard)
  adminOnly() {
    return { message: 'Admin access' };
  }
}

Ejemplo 2: Hash de Password

import { PasswordService } from '@core/modules/auth';

const passwordService = new PasswordService();

// Hash
const hash = await passwordService.hash('myPassword123');

// Verify
const isValid = await passwordService.verify('myPassword123', hash);

---

Dependencias

Internas

Modulo	Uso
@core/modules/utils	Validaciones

Externas (npm)

Paquete	Version	Uso
@nestjs/jwt	^10.0	Tokens JWT
@nestjs/passport	^10.0	Estrategias auth
passport-jwt	^4.0	Estrategia JWT
bcrypt	^5.0	Hashing passwords

---

Relacion con Catalogo

Este modulo (core/modules/auth/) provee codigo importable.

El catalogo (core/catalog/auth/) provee documentacion y referencia para implementaciones completas.

Usar modules/auth cuando:
  - Necesitas guards/decorators listos
  - Proyecto ya tiene auth y solo extiende

Usar catalog/auth cuando:
  - Implementas auth desde cero
  - Necesitas documentacion completa
  - Requieres DDL y estructura de tablas

---

Estado Actual

- [ ] JwtAuthGuard implementado
- [ ] RolesGuard implementado
- [ ] CurrentUser decorator
- [ ] Roles decorator
- [ ] Public decorator
- [ ] TokenService
- [ ] PasswordService
- [ ] SessionService
- [ ] Tests unitarios
- [ ] Documentacion completa

---

Changelog

v0.1.0 (2026-01-03)

• Estructura inicial
• README con planificacion

---

Modulo: core/modules/auth/ | Owner: Backend-Agent | Estado: desarrollo