# 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

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

### Configuracion de Paths

```json
{
  "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

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

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

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

```markdown
- [ ] 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