@aranzatech/aranza-auth 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -4,7 +4,63 @@ All notable changes to this project will be documented in this file.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [0.2.2] - 2026-07-03
+
+### Added
+
+- **OpenAPI / Swagger**: `@ApiProperty` en DTOs, `setupAuthSwagger()`, `MeResponseDto`, `ApiAuthUnauthorizedResponse`, `@ApiExtraModels`, feature flags en descripción OpenAPI, `exportPath` para `openapi.json`.
+- **`POST /auth/resend-verification`**: reenvío anti-enumeración.
+- **JWT claims**: `typ: "access" | "refresh"`, `jti` en refresh, opcional `jwtIssuer` / `jwtAudience`.
+- **Refresh payload mínimo**: sin PII en refresh JWT.
+- **`jwtValidationCacheTtlMs`**: cache opcional en `JwtStrategy` (0–5 min).
+- **`AUTH_RATE_LIMIT_ROUTES`**: mapa ruta → preset throttler.
+- **Cookie helpers**: `buildRefreshTokenCookie()`, `buildClearRefreshTokenCookie()`.
+- **Mongo admin**: `setAccountDisabled()`, `findUnverifiedByEmail()`, índice `{ email, disabled }`.
+- **E2E**: Supertest smoke tests + flujo login → me → refresh → logout → change-password → resend-verification.
+- **`AuthHooksConstructor`**: tipado sin `any[]`.
+- **`AuthErrorCode.UNAUTHORIZED`**: token ausente o inválido en rutas protegidas.
+
+### Fixed
+
+- **P0 lockout bypass**: `lockedUntil` en JWT validate, refresh y login.
+- **P0 access tokens tras password change**: claim `pwdAt`.
+- **P0 refresh rotation race**: `rotateRefreshTokenHashIfMatch` atómico.
+- **P0 lockout timing leak**: bcrypt antes del lockout check.
+- **P0 error codes**: `AuthErrorCode` en todos los mensajes.
+- **Reset password**: `PASSWORD_UNCHANGED` si la contraseña es igual.
+- **Login HTTP 200** (no 201).
+- **`routePrefix`**: sin `@Controller("auth")` hardcodeado.
+- **Lockout race**: `$inc` atómico.
+- **Hooks DI unificado** en `forRoot` / `forRootAsync`.
+- **`DefaultAuthHooks`**: sin `sub` duplicado en `buildJwtPayload`.
+- **`JwtAuthGuard`**: rutas protegidas sin Bearer devuelven `UNAUTHORIZED`.
+- **Docs**: README/SECURITY alineados con v0.2.2; **`publish.yml`** usa `npm run ci`.
+
+### Changed
+
+- **Breaking (error messages)**: `INVALID_CREDENTIALS`, `INVALID_REFRESH_TOKEN` son códigos.
+- **Breaking (refresh JWT)**: payload reducido — re-login tras upgrade desde ≤0.2.1.
+- **Breaking (refresh hash)**: HMAC-SHA256 en lugar de bcrypt — invalida hashes almacenados; re-login requerido.
+- CI: `npm audit --audit-level=high` falla el pipeline.
+- README: `forbidNonWhitelisted: true`.
+
+### Security
+
+- Warning en boot si `refreshTokenRotation: false`.
+- Refresh hash con HMAC + `timingSafeEqual` (más rápido que bcrypt en cada refresh).
+
+### Tests / CI
+
+- **113 tests** (unit + e2e Supertest).
+- Coverage gates: AuthService ≥80%, TokenService ≥75%, MongoAuthRepository ≥70%, total ≥65%.
+- `npm run ci` — pipeline local completo.
+- `overrides` en `package.json` para audit limpio (`esbuild`, `multer`).
+
+## [0.2.1] - 2026-07-03
+
+### Fixed
+
+- CI coverage gate: Vitest escribe rutas absolutas en `coverage-summary.json` — match por sufijo de archivo.
 
 ## [0.2.0] - 2026-07-03
 
@@ -78,7 +134,9 @@ First public release.
 - **Adapter MongoDB** (`@aranzatech/aranza-auth/mongo`).
 - Build dual ESM/CJS, tests (`vitest`), CI GitHub Actions.
 
-[Unreleased]: https://github.com/aranzatech/aranza-auth/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/aranzatech/aranza-auth/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/aranzatech/aranza-auth/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/aranzatech/aranza-auth/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/aranzatech/aranza-auth/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/aranzatech/aranza-auth/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/aranzatech/aranza-auth/compare/v0.1.0...v0.1.1

package/README.md

@@ -16,13 +16,14 @@ Ideal para reutilizar auth en todos tus proyectos AranzaTech: instalas, configur
 - [Endpoints](#endpoints)
 - [Proteger rutas propias](#proteger-rutas-propias)
 - [Rate limiting (producción)](#rate-limiting-producción)
+- [Swagger / OpenAPI](#swagger--openapi)
 - [Seguridad en producción](#seguridad-en-producción)
 - [Extender con AuthHooks](#extender-con-authhooks)
 - [Extender el schema MongoDB](#extender-el-schema-mongodb)
 - [Flujos opcionales (email y password)](#flujos-opcionales-email-y-password)
 - [Exports públicos](#exports-públicos)
 - [Requisitos del proyecto consumidor](#requisitos-del-proyecto-consumidor)
-- [Limitaciones conocidas (v0.1.0)](#limitaciones-conocidas-v010)
+- [Limitaciones conocidas (v0.2.x)](#limitaciones-conocidas-v02x)
 - [Roadmap](#roadmap)
 - [Licencia](#licencia)
 
@@ -39,7 +40,7 @@ npm install @aranzatech/aranza-auth
 ```bash
 npm install @nestjs/common @nestjs/core @nestjs/jwt @nestjs/passport \
   @nestjs/mongoose mongoose passport passport-jwt bcryptjs \
-  class-validator class-transformer reflect-metadata
+  class-validator class-transformer reflect-metadata @nestjs/swagger
 ```
 
 > NestJS **11+** recomendado.
@@ -94,7 +95,11 @@ Los DTOs usan `class-validator`. Activa el pipe global en `main.ts`:
 import { ValidationPipe } from "@nestjs/common";
 
 app.useGlobalPipes(
-  new ValidationPipe({ whitelist: true, transform: true }),
+  new ValidationPipe({
+    whitelist: true,
+    forbidNonWhitelisted: true,
+    transform: true,
+  }),
 );
 ```
 
@@ -127,8 +132,13 @@ Con eso ya tienes auth funcional para un POC.
 | `MONGODB_URI` | Sí | Connection string de MongoDB |
 | `JWT_SECRET` | Sí | Secret para access tokens |
 | `JWT_REFRESH_SECRET` | Sí | Secret para refresh tokens (distinto al anterior) |
+| `JWT_EXPIRES_IN` | No | TTL access token (default `1h` si lo mapeas en config) |
+| `JWT_REFRESH_EXPIRES_IN` | No | TTL refresh token (default `7d`) |
+| `JWT_ISSUER` / `JWT_AUDIENCE` | No | Solo si configuras `jwtIssuer` / `jwtAudience` |
 | `FRONTEND_URL` | No | Base URL para links en emails (verify/reset) |
 
+Ver `.env.example` en el repo como plantilla para apps consumidoras (la lib no lee `.env` directamente).
+
 ---
 
 ## Configuración del módulo
@@ -153,19 +163,46 @@ AuthModule.forRootAsync({
     features: {
       emailVerification: false,   // default: false
       passwordReset: false,       // default: false
-      refreshTokenRotation: true,   // default: true
+      refreshTokenRotation: true, // default: true
+      accountLockout: false,      // default: false
+    },
+
+    // ── Lockout (si accountLockout: true) ────────────────
+    lockout: {
+      maxAttempts: 5,              // default: 5
+      lockoutDurationMs: 15 * 60_000, // default: 15 min
     },
 
+    // ── JWT issuer/audience (opcional) ───────────────────
+    jwtIssuer: "my-api",
+    jwtAudience: "my-app",
+
+    // ── Performance (opcional) ───────────────────────────
+    jwtValidationCacheTtlMs: 0,  // 0 = siempre validar en DB; max 300000 (5 min)
+
+    // ── Ruta del controller ──────────────────────────────
+    routePrefix: "auth",  // default: "auth" → /auth/login
+
+    // ── Password policy ──────────────────────────────────
+    bcryptRounds: 10,           // 10–14, default 10
+    passwordComplexity: false,  // upper + lower + digit
+
     // ── TTL de tokens de email/reset ─────────────────────
     emailVerificationTokenTtlMs: 24 * 60 * 60 * 1000,  // 24h
     passwordResetTokenTtlMs: 15 * 60 * 1000,           // 15min
 
     // ── Hooks personalizados ─────────────────────────────
-    hooks: AppAuthHooks,  // default: DefaultAuthHooks
+    hooks: AppAuthHooks,       // default: DefaultAuthHooks (Nest DI vía ModuleRef)
+    // hooksProvider: { ... }, // alternativa: provider Nest completo
   }),
+  // routePrefix y hooks también pueden ir aquí (nivel forRootAsync):
+  // routePrefix: "auth",
+  // hooks: AppAuthHooks,
 }),
 ```
 
+`AuthModule.forRoot(options)` acepta las mismas opciones de forma síncrona (sin `imports`/`inject`).
+
 ### Orden de imports
 
 `MongoAuthModule.forFeature()` debe importarse **dentro** de `AuthModule.forRootAsync`:
@@ -198,6 +235,7 @@ Todo está **desactivado por defecto**. Sin declarar `features`, obtienes el mí
 | `emailVerification` | `false` | Envía email al register, bloquea login hasta verificar |
 | `passwordReset` | `false` | Habilita `forgot-password` y `reset-password` |
 | `refreshTokenRotation` | `true` | Guarda hash del refresh token en DB y lo rota |
+| `accountLockout` | `false` | Bloquea cuenta tras N intentos fallidos de login |
 
 ### Modo POC (solo login/register)
 
@@ -212,7 +250,7 @@ AuthModule.forRootAsync({
 ```
 
 - Register crea cuenta con `emailVerified: true` → login inmediato.
-- Endpoints `verify-email`, `forgot-password`, `reset-password` responden **404**.
+- Endpoints `verify-email`, `resend-verification`, `forgot-password`, `reset-password` responden **404**.
 
 ### Modo producción
 
@@ -234,11 +272,12 @@ hooks: AppAuthHooks,  // debe implementar sendEmail
 | Método | Ruta | Auth | Feature | Body | Respuesta |
 |--------|------|------|---------|------|-----------|
 | `POST` | `/auth/register` | — | — | `{ email?, username?, password }` | `{ registered: true }` |
-| `POST` | `/auth/login` | — | — | `{ email?, username?, password }` | `{ accessToken, refreshToken }` |
+| `POST` | `/auth/login` | — | — | `{ email?, username?, password }` | `{ accessToken, refreshToken }` (**HTTP 200**) |
 | `POST` | `/auth/refresh` | — | — | `{ refreshToken }` | `{ accessToken, refreshToken }` |
 | `POST` | `/auth/logout` | Bearer | — | — | `{ loggedOut: true }` |
 | `GET` | `/auth/me` | Bearer | — | — | objeto enriquecido via hooks |
 | `POST` | `/auth/verify-email` | — | `emailVerification` | `{ token }` | `{ verified: true }` |
+| `POST` | `/auth/resend-verification` | — | `emailVerification` | `{ email }` | `{ sent: true }` |
 | `POST` | `/auth/forgot-password` | — | `passwordReset` | `{ email }` | `{ sent: true }` |
 | `POST` | `/auth/reset-password` | — | `passwordReset` | `{ token, newPassword }` | `{ reset: true }` |
 | `POST` | `/auth/change-password` | Bearer | — | `{ currentPassword, newPassword }` | `{ changed: true }` |
@@ -249,13 +288,15 @@ hooks: AppAuthHooks,  // debe implementar sendEmail
 
 | Código | Mensaje | Causa |
 |--------|---------|-------|
-| `401` | `Invalid credentials` | Email/username o password incorrectos |
+| `401` | `INVALID_CREDENTIALS` | Email/username o password incorrectos |
 | `401` | `EMAIL_NOT_VERIFIED` | Feature `emailVerification` activa y email sin verificar |
 | `401` | `ACCOUNT_DISABLED` | Cuenta desactivada |
 | `401` | `ACCOUNT_LOCKED` | Demasiados intentos fallidos (`features.accountLockout`) |
+| `401` | `PASSWORD_CHANGED` | Access token emitido antes del último cambio de contraseña |
 | `401` | `REFRESH_TOKEN_REUSE` | Refresh reutilizado; sesiones revocadas |
 | `401` | `INVALID_CURRENT_PASSWORD` | Contraseña actual incorrecta en change-password |
-| `401` | `Invalid refresh token` | Refresh expirado, revocado o inválido |
+| `401` | `INVALID_REFRESH_TOKEN` | Refresh expirado, revocado o inválido |
+| `401` | `UNAUTHORIZED` | Sin Bearer token o token inválido en ruta protegida |
 | `404` | — | Feature desactivada (endpoint no disponible) |
 | `400` | `TOKEN_INVALID_OR_EXPIRED` | Token de verify/reset inválido o expirado |
 | `400` | `PASSWORD_UNCHANGED` | Nueva contraseña igual a la actual |
@@ -327,10 +368,73 @@ Presets exportados:
 |--------|-----------------|--------|
 | `default` | Rutas auth generales | 10 req/min |
 | `credentials` | `/auth/login`, `/auth/register`, `/auth/refresh` | 5 req/min |
-| `passwordReset` | `/auth/forgot-password` | 3 req/min |
+| `passwordReset` | `/auth/forgot-password`, `/auth/reset-password`, `/auth/resend-verification` | 3 req/min |
+
+Mapa por ruta (`AUTH_RATE_LIMIT_ROUTES`):
+
+```typescript
+import { AUTH_RATE_LIMIT_ROUTES } from "@aranzatech/aranza-auth";
+// AUTH_RATE_LIMIT_ROUTES.login → preset credentials
+// AUTH_RATE_LIMIT_ROUTES["resend-verification"] → preset passwordReset
+```
 
 > Aplica `@Throttle()` por controlador o ruta según tu política de seguridad.
 
+### Refresh token en cookie (opcional)
+
+```typescript
+import { buildRefreshTokenCookie } from "@aranzatech/aranza-auth";
+
+@Post("login")
+async login(@Body() dto: LoginDto, @Res({ passthrough: true }) res: Response) {
+  const tokens = await this.authService.login(dto);
+  res.setHeader("Set-Cookie", buildRefreshTokenCookie(tokens.refreshToken));
+  return { accessToken: tokens.accessToken };
+}
+```
+
+---
+
+## Swagger / OpenAPI
+
+Instala `@nestjs/swagger` en tu app (peer dependency):
+
+```bash
+npm install @nestjs/swagger
+```
+
+En `main.ts`:
+
+```typescript
+import { setupAuthSwagger } from "@aranzatech/aranza-auth";
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  setupAuthSwagger(app, {
+    title: "Mi API",
+    description: "Documentación OpenAPI",
+    path: "api", // → http://localhost:3000/api
+    version: "1.0",
+    features: {
+      emailVerification: true,
+      passwordReset: true,
+      accountLockout: true,
+    },
+    exportPath: "./openapi.json", // opcional: escribe el spec al arrancar
+  });
+
+  await app.listen(3000);
+}
+```
+
+Los endpoints `/auth/*` aparecen bajo el tag **`auth`**. Rutas protegidas usan **Bearer JWT** (`access-token`).
+
+Para probar en Swagger UI:
+1. `POST /auth/login` → copia `accessToken`
+2. Click **Authorize** → pega el token
+3. Llama `GET /auth/me` o tus rutas con `@ApiBearerAuth('access-token')`
+
 ---
 
 ## Seguridad en producción
@@ -352,6 +456,11 @@ AuthModule.forRootAsync({
       emailVerification: true,
       passwordReset: true,
       refreshTokenRotation: true,
+      accountLockout: true,
+    },
+    lockout: {
+      maxAttempts: 5,
+      lockoutDurationMs: 15 * 60_000,
     },
   }),
 });
@@ -359,8 +468,19 @@ AuthModule.forRootAsync({
 
 ### Refresh tokens en cookies (recomendado)
 
+Usa los helpers exportados (HttpOnly, Secure, SameSite=strict):
+
+```typescript
+import { buildRefreshTokenCookie, buildClearRefreshTokenCookie } from "@aranzatech/aranza-auth";
+
+res.setHeader("Set-Cookie", buildRefreshTokenCookie(tokens.refreshToken));
+// logout:
+res.setHeader("Set-Cookie", buildClearRefreshTokenCookie());
+```
+
+Alternativa manual:
+
 ```typescript
-// En login/refresh handler de tu app — no devolver refresh en JSON body
 res.cookie("refreshToken", tokens.refreshToken, {
   httpOnly: true,
   secure: true,
@@ -399,7 +519,7 @@ interface MyAuthAccount extends BaseAuthAccount {
 export class AppAuthHooks implements AuthHooks<MyAuthAccount> {
   constructor(private readonly orgService: OrgService) {}
 
-  /** Campos extra en el JWT */
+  /** Campos extra en el JWT (no incluyas `sub` — lo añade la lib) */
   async buildJwtPayload(account: MyAuthAccount) {
     return {
       orgId: account.orgId,
@@ -495,6 +615,17 @@ MongoAuthModule.forFeature({
 
 > `identifierField` en `MongoAuthModule.forFeature()` debe coincidir con el de `AuthModule`.
 
+### Métodos extra en `MongoAuthRepository`
+
+Útiles para admin o scripts (inyecta `MongoAuthRepository` o implementa en tu propio repo):
+
+| Método | Uso |
+|--------|-----|
+| `setAccountDisabled(id, disabled)` | Deshabilitar/habilitar cuenta |
+| `findUnverifiedByEmail(email)` | Buscar cuenta pendiente de verificación |
+
+Índice compuesto `{ email: 1, disabled: 1 }` incluido para lookups frecuentes.
+
 ---
 
 ## Flujos opcionales (email y password)
@@ -504,7 +635,8 @@ MongoAuthModule.forFeature({
 1. Activa `features.emailVerification: true`
 2. Implementa `sendEmail` en hooks
 3. Register envía email con token → usuario visita link → `POST /auth/verify-email` con `{ token }`
-4. Login bloqueado hasta `emailVerified: true`
+4. Si el usuario no recibió el email: `POST /auth/resend-verification` con `{ email }` → siempre `{ sent: true }`
+5. Login bloqueado hasta `emailVerified: true`
 
 Si usas `identifierField: "username"`, el register **debe incluir `email`** además del username.
 
@@ -522,8 +654,19 @@ Si usas `identifierField: "username"`, el register **debe incluir `email`** adem
 
 | Import | Contenido |
 |--------|-----------|
-| `@aranzatech/aranza-auth` | `AuthModule`, `AuthService`, guards, DTOs, interfaces, tokens, `AUTH_RATE_LIMIT_PRESETS` |
-| `@aranzatech/aranza-auth/mongo` | `MongoAuthModule`, `MongoAuthRepository`, schemas |
+| `@aranzatech/aranza-auth` | `AuthModule`, `AuthService`, guards, DTOs, `setupAuthSwagger`, `AuthErrorCode`, cookie helpers, rate-limit presets |
+| `@aranzatech/aranza-auth/mongo` | `MongoAuthModule`, `MongoAuthRepository`, `baseAuthAccountSchema` |
+
+Principales exports:
+
+| Símbolo | Uso |
+|---------|-----|
+| `AuthErrorCode` | Códigos de error (`INVALID_CREDENTIALS`, `UNAUTHORIZED`, …) |
+| `AUTH_RATE_LIMIT_PRESETS` / `AUTH_RATE_LIMIT_ROUTES` | Throttling con `@nestjs/throttler` |
+| `buildRefreshTokenCookie` / `buildClearRefreshTokenCookie` | Cookies HttpOnly para refresh |
+| `MeResponseDto` / `ResendVerificationDto` | Swagger + tipos |
+| `AuthHooksConstructor` | Tipado de hooks custom con Nest DI |
+| `setupAuthSwagger` | Swagger UI + Bearer JWT |
 
 ### Tokens de inyección
 
@@ -549,24 +692,45 @@ import { AUTH_MODULE_OPTIONS, AUTH_HOOKS, AUTH_REPOSITORY } from "@aranzatech/ar
 
 ---
 
-## Limitaciones conocidas (v0.1.x)
+## Limitaciones conocidas (v0.2.x)
 
 | Limitación | Workaround / versión futura |
 |------------|----------------------------|
 | Solo adapter MongoDB | Prisma en v0.4.0 |
 | Sin OAuth (Google, GitHub, etc.) | v0.3.0 |
+| Una sesión refresh por cuenta (`refreshTokenHash` único) | Multi-device en roadmap |
+| `jwtValidationCacheTtlMs > 0` retrasa revoke/disable en access tokens | Usar `0` si necesitas revocación inmediata |
+
+---
+
+## Migración desde ≤0.2.1
+
+1. Actualiza a `@aranzatech/aranza-auth@0.2.2`.
+2. **Re-login obligatorio**: refresh JWT y hashes almacenados cambiaron (payload mínimo + HMAC-SHA256).
+3. Los clientes deben parsear `AuthErrorCode` en `message` (no strings legibles).
+4. Activa `forbidNonWhitelisted: true` en `ValidationPipe`.
+5. Opcional: `jwtIssuer` / `jwtAudience`, cookies con `buildRefreshTokenCookie()`.
 
 ---
 
 ## Roadmap
 
 - [x] **0.2.0** — Security hardening, `change-password`, hooks con DI, audit trail, account lockout, `routePrefix`
+- [x] **0.2.2** — Swagger, P0/P1/P2 audit, JWT claims, resend-verification, E2E smoke tests
 - [ ] **0.3.0** — OAuth (Google, GitHub)
 - [ ] **0.4.0** — Adapter Prisma
 - [ ] **0.5.0** — Migración de AranzaFlow como caso de referencia
 
 ---
 
+## Desarrollo
+
+```bash
+npm install
+npm run ci    # lint + tests + coverage gates + audit + build
+npm test      # solo tests
+```
+
 ## Licencia
 
 MIT © [AranzaTech](https://github.com/aranzatech)

package/SECURITY.md

@@ -30,9 +30,15 @@ We aim to respond within **72 hours** and publish a fix or mitigation within **1
 | Behavior | Mitigation |
 |----------|------------|
 | **Logout** clears refresh token hash only; access JWT remains valid until expiry | Use short access TTL (15–60 min) |
+| **Access tokens after password change** | Invalidated via `pwdAt` claim (v0.2.2+) when `passwordChangedAt` is newer |
 | **Register duplicate** returns `{ registered: true }` without revealing existence | By design (anti-enumeration) |
 | **Forgot password** always returns `{ sent: true }` | By design (anti-enumeration) |
 | **Refresh token reuse** revokes all refresh sessions for the account | Monitor `REFRESH_TOKEN_REUSE` errors |
+| **`refreshTokenRotation: false`** | Refresh is stateless until JWT expiry — stolen tokens cannot be revoked; warning logged at boot |
+| **Refresh JWT payload** | Minimal claims only (`sub`, `typ`, `jti`, `pwdAt`) — no PII in refresh token |
+| **Refresh hash storage** | HMAC-SHA256 (v0.2.2+) — upgrade from ≤0.2.1 requires re-login |
+| **Single `refreshTokenHash`** | One active refresh session per account (document in your app if multi-device needed) |
+| **`jwtValidationCacheTtlMs`** | Optional in-memory cache; disable (`0`) for immediate disable/revoke on access |
 
 ## Hardening Checklist (Production)
 
@@ -48,11 +54,16 @@ We aim to respond within **72 hours** and publish a fix or mitigation within **1
 
 | Code | Meaning |
 |------|---------|
+| `PASSWORD_CHANGED` | Access token issued before last password change |
+| `PASSWORD_UNCHANGED` | New password equals current on change/reset |
+| `INVALID_CREDENTIALS` | Wrong email/username or password |
+| `INVALID_REFRESH_TOKEN` | Refresh expired, revoked, or invalid |
 | `REFRESH_TOKEN_REUSE` | Stale refresh token used — all refresh sessions revoked |
 | `ACCOUNT_LOCKED` | Too many failed login attempts |
 | `INVALID_CURRENT_PASSWORD` | Wrong password on change-password |
 | `EMAIL_NOT_VERIFIED` | Login or access blocked until email verified |
 | `ACCOUNT_DISABLED` | Account disabled by admin |
 | `TOKEN_INVALID_OR_EXPIRED` | Email verify or password reset token invalid |
+| `UNAUTHORIZED` | Missing or invalid Bearer token on protected routes |
 
 Export: `AuthErrorCode` from `@aranzatech/aranza-auth`.

package/dist/{auth-repository.interface-9PpDVOs8.d.cts → auth-repository.interface--1rv0RCD.d.cts}

@@ -8,6 +8,7 @@ interface BaseAuthAccount {
     disabled: boolean;
     lastLoginAt?: Date;
     passwordChangedAt?: Date;
+    lockedUntil?: Date | null;
     createdAt?: Date;
     updatedAt?: Date;
 }
@@ -36,6 +37,9 @@ interface AuthHooks<TAccount extends BaseAuthAccount = BaseAuthAccount> {
     sendEmail?(type: "verify" | "reset", to: string, token: string): Promise<void>;
 }
 
+/** Constructor type for custom `AuthHooks` implementations with Nest DI. */
+type AuthHooksConstructor = abstract new (...args: never[]) => AuthHooks;
+
 type AuthIdentifierField = "email" | "username";
 interface AuthFeatures {
     /** Require verified email before login. Sends verification email on register. Default: `false`. */
@@ -58,6 +62,10 @@ interface AuthJwtConfig {
     expiresIn?: string;
     refreshSecret: string;
     refreshExpiresIn?: string;
+    /** Optional JWT `iss` claim — validated on access and refresh tokens. */
+    jwtIssuer?: string;
+    /** Optional JWT `aud` claim — validated on access and refresh tokens. */
+    jwtAudience?: string;
 }
 interface AuthModuleOptions extends AuthJwtConfig {
     /** Field used for login/register lookup. Default: `email`. */
@@ -76,8 +84,13 @@ interface AuthModuleOptions extends AuthJwtConfig {
     passwordComplexity?: boolean;
     /** Lockout settings when `features.accountLockout` is enabled. */
     lockout?: AuthLockoutOptions;
+    /**
+     * Cache JWT user validation in memory for this many ms (0 = always hit DB).
+     * Useful for high-traffic APIs; disable when immediate revoke/disable is critical.
+     */
+    jwtValidationCacheTtlMs?: number;
     /** Custom hooks class (`useClass` — supports Nest DI). Defaults to `DefaultAuthHooks`. */
-    hooks?: new (...args: any[]) => AuthHooks;
+    hooks?: AuthHooksConstructor;
     /** Full Nest provider for hooks. Takes precedence over `hooks`. */
     hooksProvider?: _nestjs_common.Provider;
 }
@@ -85,7 +98,7 @@ interface AuthModuleAsyncOptions {
     /** Route prefix for auth controller. Default: `auth`. */
     routePrefix?: string;
     /** Custom hooks class (`useClass` with Nest DI via `ModuleRef`). */
-    hooks?: new (...args: any[]) => AuthHooks;
+    hooks?: AuthHooksConstructor;
     /** Full Nest provider for hooks. Takes precedence over `hooks`. */
     hooksProvider?: _nestjs_common.Provider;
     imports?: unknown[];
@@ -106,6 +119,8 @@ interface IAuthRepository<TAccount extends BaseAuthAccount = BaseAuthAccount> {
     findById(id: string): Promise<BaseAuthAccount | null>;
     findByIdWithSecrets(id: string): Promise<AuthAccountWithSecrets | null>;
     updateRefreshTokenHash(id: string, hash: string | null): Promise<void>;
+    /** Atomically replaces refresh hash when it still matches `expectedHash`. */
+    rotateRefreshTokenHashIfMatch(id: string, expectedHash: string, newHash: string): Promise<boolean>;
     updatePasswordHash(id: string, passwordHash: string): Promise<void>;
     setEmailVerificationToken(id: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findByEmailVerificationTokenHash(tokenHash: string): Promise<BaseAuthAccount | null>;
@@ -115,6 +130,10 @@ interface IAuthRepository<TAccount extends BaseAuthAccount = BaseAuthAccount> {
     clearResetToken(id: string): Promise<void>;
     recordLoginSuccess(id: string): Promise<void>;
     recordLoginFailure(id: string, lockout?: AuthLockoutOptions): Promise<void>;
+    /** Enable or disable an account (admin / hooks use). */
+    setAccountDisabled(id: string, disabled: boolean): Promise<void>;
+    /** Find unverified account by email (email verification flows). */
+    findUnverifiedByEmail(email: string): Promise<BaseAuthAccount | null>;
 }
 
-export type { AuthModuleOptions as A, BaseAuthAccount as B, CreateAccountData as C, IAuthRepository as I, RegisterInput as R, AuthModuleAsyncOptions as a, AuthHooks as b, AuthTokens as c, AuthAccountWithSecrets as d, AuthFeatures as e, AuthIdentifierField as f, AuthJwtConfig as g, AuthLockoutOptions as h };
+export type { AuthFeatures as A, BaseAuthAccount as B, CreateAccountData as C, IAuthRepository as I, RegisterInput as R, AuthModuleOptions as a, AuthModuleAsyncOptions as b, AuthHooks as c, AuthTokens as d, AuthAccountWithSecrets as e, AuthHooksConstructor as f, AuthIdentifierField as g, AuthJwtConfig as h, AuthLockoutOptions as i };

package/dist/{auth-repository.interface-9PpDVOs8.d.ts → auth-repository.interface--1rv0RCD.d.ts}

@@ -8,6 +8,7 @@ interface BaseAuthAccount {
     disabled: boolean;
     lastLoginAt?: Date;
     passwordChangedAt?: Date;
+    lockedUntil?: Date | null;
     createdAt?: Date;
     updatedAt?: Date;
 }
@@ -36,6 +37,9 @@ interface AuthHooks<TAccount extends BaseAuthAccount = BaseAuthAccount> {
     sendEmail?(type: "verify" | "reset", to: string, token: string): Promise<void>;
 }
 
+/** Constructor type for custom `AuthHooks` implementations with Nest DI. */
+type AuthHooksConstructor = abstract new (...args: never[]) => AuthHooks;
+
 type AuthIdentifierField = "email" | "username";
 interface AuthFeatures {
     /** Require verified email before login. Sends verification email on register. Default: `false`. */
@@ -58,6 +62,10 @@ interface AuthJwtConfig {
     expiresIn?: string;
     refreshSecret: string;
     refreshExpiresIn?: string;
+    /** Optional JWT `iss` claim — validated on access and refresh tokens. */
+    jwtIssuer?: string;
+    /** Optional JWT `aud` claim — validated on access and refresh tokens. */
+    jwtAudience?: string;
 }
 interface AuthModuleOptions extends AuthJwtConfig {
     /** Field used for login/register lookup. Default: `email`. */
@@ -76,8 +84,13 @@ interface AuthModuleOptions extends AuthJwtConfig {
     passwordComplexity?: boolean;
     /** Lockout settings when `features.accountLockout` is enabled. */
     lockout?: AuthLockoutOptions;
+    /**
+     * Cache JWT user validation in memory for this many ms (0 = always hit DB).
+     * Useful for high-traffic APIs; disable when immediate revoke/disable is critical.
+     */
+    jwtValidationCacheTtlMs?: number;
     /** Custom hooks class (`useClass` — supports Nest DI). Defaults to `DefaultAuthHooks`. */
-    hooks?: new (...args: any[]) => AuthHooks;
+    hooks?: AuthHooksConstructor;
     /** Full Nest provider for hooks. Takes precedence over `hooks`. */
     hooksProvider?: _nestjs_common.Provider;
 }
@@ -85,7 +98,7 @@ interface AuthModuleAsyncOptions {
     /** Route prefix for auth controller. Default: `auth`. */
     routePrefix?: string;
     /** Custom hooks class (`useClass` with Nest DI via `ModuleRef`). */
-    hooks?: new (...args: any[]) => AuthHooks;
+    hooks?: AuthHooksConstructor;
     /** Full Nest provider for hooks. Takes precedence over `hooks`. */
     hooksProvider?: _nestjs_common.Provider;
     imports?: unknown[];
@@ -106,6 +119,8 @@ interface IAuthRepository<TAccount extends BaseAuthAccount = BaseAuthAccount> {
     findById(id: string): Promise<BaseAuthAccount | null>;
     findByIdWithSecrets(id: string): Promise<AuthAccountWithSecrets | null>;
     updateRefreshTokenHash(id: string, hash: string | null): Promise<void>;
+    /** Atomically replaces refresh hash when it still matches `expectedHash`. */
+    rotateRefreshTokenHashIfMatch(id: string, expectedHash: string, newHash: string): Promise<boolean>;
     updatePasswordHash(id: string, passwordHash: string): Promise<void>;
     setEmailVerificationToken(id: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findByEmailVerificationTokenHash(tokenHash: string): Promise<BaseAuthAccount | null>;
@@ -115,6 +130,10 @@ interface IAuthRepository<TAccount extends BaseAuthAccount = BaseAuthAccount> {
     clearResetToken(id: string): Promise<void>;
     recordLoginSuccess(id: string): Promise<void>;
     recordLoginFailure(id: string, lockout?: AuthLockoutOptions): Promise<void>;
+    /** Enable or disable an account (admin / hooks use). */
+    setAccountDisabled(id: string, disabled: boolean): Promise<void>;
+    /** Find unverified account by email (email verification flows). */
+    findUnverifiedByEmail(email: string): Promise<BaseAuthAccount | null>;
 }
 
-export type { AuthModuleOptions as A, BaseAuthAccount as B, CreateAccountData as C, IAuthRepository as I, RegisterInput as R, AuthModuleAsyncOptions as a, AuthHooks as b, AuthTokens as c, AuthAccountWithSecrets as d, AuthFeatures as e, AuthIdentifierField as f, AuthJwtConfig as g, AuthLockoutOptions as h };
+export type { AuthFeatures as A, BaseAuthAccount as B, CreateAccountData as C, IAuthRepository as I, RegisterInput as R, AuthModuleOptions as a, AuthModuleAsyncOptions as b, AuthHooks as c, AuthTokens as d, AuthAccountWithSecrets as e, AuthHooksConstructor as f, AuthIdentifierField as g, AuthJwtConfig as h, AuthLockoutOptions as i };