Mi plantilla NestJS 12 + Prisma 7 para APIs en producción: cómo está hecha, cómo usarla y qué aprendí probándola

Hace unas semanas publiqué mi plantilla de Hono + Prisma para APIs en producción. Esta es su gemela en NestJS: nestjs-prisma-production-starter, un repositorio de GitHub marcado como template (MIT) con una API REST lista para llevar a producción: sesiones con estado que se pueden revocar al instante, rotación de refresh tokens con detección de robo, Argon2id, 2FA con TOTP, recuperación de contraseña, rate limiting en base de datos, Prisma 7 sobre SQLite (o Turso), validación con Zod y documentación OpenAPI con Scalar.

La idea es la misma que con Hono: no quiero otro «hola mundo», quiero algo que puedas clonar, arrancar y desplegar sin reinventar la parte aburrida y peligrosa. Y como con Hono, no me limito a contarte lo que dice el README: la he descargado, compilado, probado y atacado (en local, contra mi propia instancia) para contarte qué hay de verdad dentro, qué funciona y qué todavía no está pulido.

Qué es y para quién es

Es una API REST de «tareas» con usuarios, que sirve de esqueleto para cualquier backend serio. El dominio es deliberadamente pequeño (tareas, usuarios, sesiones, auditoría) para que todo el esfuerzo se vea en lo que importa: autenticación, seguridad, datos, pruebas y despliegue.

Lo más distintivo es que tiene tres niveles de autenticación que eliges con una variable (AUTH_MODE):

Con none tienes una API pública sin usuarios; con basic, usuarios, sesiones, roles y auditoría; con full (el valor por defecto), además verificación de email, recuperación de contraseña y 2FA. Lo que no aplica no se monta en el router ni aparece en OpenAPI. Lo he comprobado arrancando los tres modos:

Es para ti si quieres una base con las decisiones de seguridad ya tomadas (y razonadas), y quieres NestJS porque tu equipo ya lo usa, porque te gusta su estructura modular o porque la inyección de dependencias te encaja. Si lo que buscas es algo más pequeño y rápido de leer, tienes la de Hono; al final del artículo te cuento cuándo elegiría una u otra.

Descarga: cuatro formas de tenerla

Requisitos: Node.js 24.9 o superior y npm 11 o superior (están en engines; yo la he probado con Node 24.21.0 y no he probado versiones anteriores).

El repositorio está marcado como plantilla en GitHub (is_template: true) y tiene licencia MIT. Es un repositorio muy joven: main tiene 30 commits, todos entre el 22 y el 23 de octubre de 2026 (el PR #8 añade diez más).

Puesta en marcha en tres pasos

git clone https://github.com/Collanteslu/nestjs-prisma-production-starter.git
cd nestjs-prisma-production-starter
npm ci
cp .env.example .env

Abre .env y rellena los dos secretos JWT (la app no arranca sin ellos, salvo con AUTH_MODE=none):

openssl rand -base64 48   # úsalo para JWT_SECRET
openssl rand -base64 48   # y otro distinto para JWT_REFRESH_SECRET

Después, cliente de Prisma, migraciones y a correr:

npx prisma generate
npx prisma migrate deploy
npm run dev

La API escucha en http://localhost:3011. En desarrollo, con la base de datos vacía, se siembran dos usuarios de ejemplo ([email protected] y [email protected], contraseña password123) y tres tareas. En producción nunca se siembran demos: solo se crea el administrador inicial si defines ADMIN_EMAIL y ADMIN_PASSWORD.

Qué trae y qué versiones

Dos decisiones que merece la pena entender:

• nestjs-zod está vendorizada. La versión publicada declara peer dependencies que se quedan en Nest y Swagger 11, y esta plantilla va con Nest 12. En vez de forzar --legacy-peer-deps o un overrides, el repositorio incluye una copia compilada en vendor/nestjs-zod y la instala con file:. Funciona, pero significa que esa pieza no se actualiza sola.
• Express 5, no Fastify. Nest 12 usa Express 5 por defecto y la plantilla se apoya en ello (por ejemplo, el comodín de rutas {*splat} de path-to-regexp v8, que verás en la parte de autenticación).

Si quieres entender cómo piensa NestJS por dentro antes de meterte en la plantilla, te recomiendo NestJS 12 a fondo; y para ver cómo se compara con los demás, la comparativa de Hono, Fastify, Express y NestJS.

La estructura del proyecto

nestjs-prisma-production-starter/
├── prisma/                 # schema.prisma + 10 migraciones versionadas
├── src/
│   ├── main.ts             # arranque: orden estricto (ver más abajo)
│   ├── configure-app.ts    # helmet, CORS, límites de body, Swagger/Scalar
│   ├── app.module.ts       # AppModule.forRoot(env): monta módulos según AUTH_MODE
│   ├── config/             # env.ts (Zod) + tokens de inyección
│   ├── database/           # PrismaService, MigrationsGuard, SeedService
│   ├── auth/               # login/registro/refresh/logout, JwtAuthGuard, AdminGuard
│   ├── sessions/           # sesiones, rotación y revocación de refresh tokens
│   ├── users/  tasks/  audit/
│   ├── mfa/                # TOTP + códigos de recuperación
│   ├── mail/               # recuperación, verificación y cola EmailOutbox
│   ├── rate-limit/         # guard, bloqueo por cuenta y almacén en BD
│   ├── jobs/               # CleanupService (cada hora)
│   ├── common/             # pipe, interceptores, filtro, middleware, utilidades
│   └── generated/          # cliente de Prisma (generado, no se versiona)
├── test/                   # 13 suites de Jest
├── contract/               # harness HTTP ejecutable (11 escenarios)
├── bruno/                  # colección de Bruno (32 peticiones)
├── scripts/                # bruno-smoke.sh, ops-rehearsal.sh, lockout-key.mjs, docker-smoke.sh (PR #8)
├── vendor/nestjs-zod/      # integración Zod vendorizada
├── Dockerfile  docker-compose.yml  docker-entrypoint.sh
└── AGENTS.md               # documentación larga (unas 500 líneas) del comportamiento

Los scripts de npm que vas a usar:

Y por dónde pasa una petición, de un vistazo:

La parte de Express (configureApp()) hace lo propio de HTTP; Nest ordena después guards → pipe → controlador → interceptor → filtro de excepciones. Todo lo global se registra en AppModule con los tokens APP_GUARD, APP_PIPE, APP_INTERCEPTOR y APP_FILTER:

{ provide: APP_GUARD, useExisting: JwtAuthGuard },   // 1º: ¿quién eres? (deny-by-default)
{ provide: APP_GUARD, useClass: RateLimitGuard },    // 2º: ¿cuántas veces?
{ provide: APP_PIPE, useClass: ContractValidationPipe },
{ provide: APP_INTERCEPTOR, useClass: TransformInterceptor },   // sobre de respuesta
{ provide: APP_FILTER, useClass: AllExceptionsFilter },

Detalle que me gusta: JwtAuthGuard se registra con useExisting, no con useClass, para que el guard global y el AuthPrefixMiddleware compartan la misma instancia y la verificación del token exista una sola vez en el código.

Configuración que falla rápido

Lo primero que hace main.ts es loadEnv(): valida todas las variables de entorno con Zod y, si algo está mal, la app se niega a arrancar con un mensaje que dice qué falta. Las reglas de producción son estrictas. Esto es lo que pasa de verdad (salidas reales):

# Sin secretos (AUTH_MODE=full por defecto)
❌ Critical startup failure: Invalid or missing environment configuration:
{
  "JWT_SECRET": [
    "JWT_SECRET is required unless AUTH_MODE=none (generate one with: openssl rand -base64 48)"
  ],
  "JWT_REFRESH_SECRET": [ "JWT_REFRESH_SECRET is required unless AUTH_MODE=none (…)" ]
}
exit=1

# NODE_ENV=production con el mismo secreto en los dos JWT y sin clave de MFA
{
  "JWT_REFRESH_SECRET": [ "JWT_REFRESH_SECRET must differ from JWT_SECRET" ],
  "MFA_ENCRYPTION_KEY": [ "MFA_ENCRYPTION_KEY (>= 32 chars) is required in production with AUTH_MODE=full so TOTP secrets are encrypted with a dedicated, stable key (…)" ]
}
exit=1

# NODE_ENV=production con CORS_ORIGINS=*
{
  "CORS_ORIGINS": [ "CORS_ORIGINS=\"*\" is rejected in production: list the real origins, or set CORS_ALLOW_WILDCARD=true to allow any origin deliberately" ]
}
exit=1

Comprobé todas las reglas de producción de una en una: secretos de menos de 16 caracteres (rechazados), mismo secreto para ambos JWT (rechazado en cualquier entorno, porque un refresh token se aceptaría como access token), CORS_ORIGINS=* (rechazado salvo CORS_ALLOW_WILDCARD=true), MAIL_TRANSPORT=log en producción (rechazado, porque escribiría en el log los enlaces de recuperación, que son credenciales vivas) y SMTP con ignoreTLS=true (rechazado). Cada una termina con código de salida 1.

El fragmento de env.ts que lo hace posible usa superRefine de Zod 4:

.superRefine((cfg, ctx) => {
  const authEnabled = cfg.AUTH_MODE !== "none";
  if (authEnabled) {
    for (const key of ["JWT_SECRET", "JWT_REFRESH_SECRET"] as const) {
      if (!cfg[key]) ctx.addIssue({ code: "custom", path: [key],
        message: `${key} is required unless AUTH_MODE=none (generate one with: openssl rand -base64 48)` });
    }
  }
  if (authEnabled && cfg.JWT_SECRET && cfg.JWT_SECRET === cfg.JWT_REFRESH_SECRET) {
    // Same secret in ANY environment: a refresh token would then verify as an access token
    ctx.addIssue({ code: "custom", path: ["JWT_REFRESH_SECRET"],
      message: "JWT_REFRESH_SECRET must differ from JWT_SECRET" });
  }
  if (cfg.NODE_ENV !== "production") return;
  // … endurecimiento solo para producción …
})

Y el .env.example viene comentado en español, con el porqué de cada variable (proxy, CORS, rate limits, TTL de recuperación…). Lo que más vas a tocar:

Referencia completa de variables

El esquema de src/config/env.ts define 36 variables. Esta es la tabla completa, sacada del código (no del README), con el valor por defecto que aplica la aplicación:

Fíjate en un detalle: las cadenas vacías cuentan como «sin definir». Es lo que hace que el docker-compose.yml pueda pasar CORS_ORIGINS=${CORS_ORIGINS:-} sin romper nada: si no defines la variable, llega vacía y se aplica el valor por defecto.

Además de los límites de cada variable, hay reglas cruzadas. Las ejecuté llamando a parseEnv() con cada combinación (salida real, una línea por caso):

RECHAZA AUTH_MODE=none + ADMIN_EMAIL → ADMIN_EMAIL / ADMIN_PASSWORD have no effect with AUTH_MODE=none (there are no users)
RECHAZA MAIL_TRANSPORT=smtp sin SMTP_URL → SMTP_URL is required when MAIL_TRANSPORT=smtp
RECHAZA REQUIRE_EMAIL_VERIFICATION sin transporte que entregue → … needs a mail transport that delivers (MAIL_TRANSPORT=smtp), otherwise nobody could verify
RECHAZA REQUIRE_EMAIL_VERIFICATION con AUTH_MODE=basic → … needs AUTH_MODE=full (email verification is off otherwise)
RECHAZA MFA_ENCRYPTION_KEY_PREVIOUS sin la actual → … only works together with MFA_ENCRYPTION_KEY
RECHAZA producción + smtp sin APP_URL → APP_URL is required in production when MAIL_TRANSPORT=smtp (it builds the emailed links)
RECHAZA producción + APP_URL en http → APP_URL must use https in production when MAIL_TRANSPORT=smtp
RECHAZA ADMIN_PASSWORD de 73 caracteres → Too big: expected string to have <=72 characters
RECHAZA TRUST_PROXY_HOPS=0 → Too small: expected number to be >=1
OK      producción mínima (2 JWT distintos + MFA_ENCRYPTION_KEY) → CORS_ORIGINS=[], MAIL_TRANSPORT=none

Las reglas que solo se aplican en producción, leídas directamente en el superRefine (estas no las ejecuté una a una: son lectura de código): MAIL_TRANSPORT=log se rechaza porque escribiría en los logs los enlaces de recuperación con credenciales vivas; CORS_ORIGINS=* se rechaza salvo CORS_ALLOW_WILDCARD=true; los secretos JWT necesitan 32 caracteres; MAIL_TRANSPORT=memory se rechaza («solo para pruebas»); y una SMTP_URL con ignoreTLS=true o rejectUnauthorized=false se rechaza para que nadie degrade el canal a texto plano.

La última línea es el mínimo absoluto para arrancar en producción: dos secretos JWT distintos de 32+ caracteres y la clave de MFA. Y fíjate en lo que implica el resultado: CORS queda vacío (ningún origen cruzado) y el correo en none hasta que lo configures. Es una configuración cerrada por defecto, que es lo que se espera de una plantilla de producción.

Prisma 7: modelo, migraciones y cliente

Nueve modelos pequeños

El esquema tiene nueve tablas con su propio propósito (prisma/schema.prisma):

Un detalle de diseño: el cliente de Prisma se crea con omit global para que password, totpSecret y totpLastStep no salgan en ninguna consulta salvo que lo pidas explícitamente (omit: { password: false }). Es una de esas decisiones que evitan filtrar un hash por un include descuidado, y lo comprobé en el ataque: pedir include=user,password no devuelve ningún campo de contraseña.

Migraciones versionadas, nunca db push

Hay diez migraciones en prisma/migrations/ (de 0_init a 20261023090922_email_outbox). El arranque comprueba que el historial de la base coincide con el del repositorio; si no, no arranca. Esto es lo que ocurre en producción con una base nueva sin migrar (salida real, recortada):

ERROR [Bootstrap] Migration history does not match prisma/migrations:
  Pending: 0_init, 20260929000000_hash_refresh_tokens_and_indexes, 20261001211304_rate_limit_buckets, …
MigrationsGuard
exit=1

Mensaje claro y fail closed. En contenedor, el docker-entrypoint.sh es quien aplica las migraciones (prisma migrate deploy) antes de arrancar. Lo ejecuté primero sin Docker, directamente con sh ./docker-entrypoint.sh node dist/main.js y un DATABASE_URL=file:…/data/prod.db en un directorio que no existía:

🚀 Aplicando migraciones de base de datos...
SQLite database prod.db created at file:/…/data/prod.db
10 migrations found in prisma/migrations
Applying migration `0_init`
…
Applying migration `20261023090922_email_outbox`
⚡ Iniciando servidor NestJS...

El script crea el directorio, aplica las 10 migraciones, arranca el servidor, /healthz responde y /docs da 404 (producción). Y cuando la base existe pero no tiene historial de migraciones (un caso real si migras desde otra herramienta), no inventa nada: se niega a hacer el baseline automático y te da el procedimiento manual:

Error: P3005
The database schema is not empty. …
❌ No se aplicaron las migraciones.
   La base de datos existe SIN historial de migraciones (P3005). Procedimiento manual:
     1. Copia de seguridad del fichero/BD actual.
     2. Verificar que el esquema existente es el esperado …
     3. Solo si el esquema coincide:  node node_modules/prisma/build/index.js migrate resolve --applied 0_init
     4. node node_modules/prisma/build/index.js migrate deploy
   Nunca ejecutes resolve en un esquema que no hayas verificado.
exit=1

Esto es lo que quiero de una plantilla de producción: que un fallo se note en el arranque y no a las tres de la madrugada.

El cliente: libSQL, WAL y Turso

PrismaService extiende PrismaClient con el adaptador PrismaLibSql. Si defines TURSO_DATABASE_URL, se usa Turso; si no, el fichero local. Al arrancar aplica los pragmas de SQLite (en mi log: SQLite pragmas applied at startup (journalMode=wal)) y el adaptador espera hasta 5 segundos al único escritor de SQLite en vez de fallar con SQLITE_BUSY bajo concurrencia.

El seed

SeedService corre tras la comprobación de migraciones. Fuera de producción siembra los dos usuarios demo y tres tareas; con AUTH_MODE=none siembra dos tareas públicas de ejemplo; en producción solo crea el administrador inicial si la base está vacía y has definido ADMIN_EMAIL y ADMIN_PASSWORD. Lo verifiqué: en el arranque en producción, el login de [email protected] da 401 (no existe) y el del administrador del entorno da 200.

El punto de entrada: orden estricto

El main.ts documenta su propio orden y es muy didáctico:

const env = loadEnv();                         // 1. valida .env con Zod (o aborta)
Logger.overrideLogger(nestLogLevels(env.LOG_LEVEL));   // 2. nivel de log
const app = await NestFactory.create<NestExpressApplication>(AppModule.forRoot(env), {
  bodyParser: false,   // el body se configura de forma explícita en configureApp()
  abortOnError: false,
});
await configureApp(app, env, features);        // 3. helmet, CORS, límites, docs
await app.init();
await prisma.applySqlitePragmas();             // 4. pragmas de SQLite
await assertMigrationsUpToDate(prisma);        // 5. migraciones al día o exit(1)
await app.get(SeedService).run();              // 6. seed
cleanup.start();  outbox?.start();             // 7. limpieza horaria y worker de correo
installShutdownHooks(app, …);                  // 8. cierre ordenado (tope 10 s)
await app.listen(env.PORT, "0.0.0.0");         // 9. y solo entonces, escuchar

Dos observaciones: la app solo escucha cuando todo lo anterior ha ido bien, y en el apagado (SIGTERM) cierra el servidor, para los trabajos y desconecta Prisma. Lo medí: del SIGTERM a la salida pasan 39–47 ms sin tráfico.

configureApp() fija el resto: helmet, una CSP específica solo para /docs, Referrer-Policy: no-referrer y Cache-Control: no-store en todas las respuestas, CORS por lista, y un json({ limit: 100 KB }) con un manejador de errores de body que responde 400 (JSON mal formado) o 413 (demasiado grande). También desactiva x-powered-by y los etags, y usa el query parser simple.

Módulos e inyección de dependencias: el mapa completo

Si vienes de Hono o de Express, esta es la parte de NestJS que más cuesta al principio y la que más compensa después. Por eso la recorro entera, con el código real.

Un módulo es una caja con puertas

En Nest todo vive dentro de un @Module. Un módulo declara qué controladores monta, qué proveedores (servicios) crea, qué importa de otros módulos y qué exporta para que otros lo usen. Lo que no exportas es privado. Esta plantilla tiene 14 módulos: el raíz, seis globales (disponibles en todas partes sin importarlos) y siete «de funcionalidad». Este es el reparto, sacado de los ficheros *.module.ts:

Fíjate en RateLimitModule, AuditModule o MfaModule: son globales porque casi cualquier controlador los necesita y repetir imports: [AuditModule] en cada módulo sería ruido. El precio es el de siempre con lo global: un módulo nuevo puede usar AuditService sin declarar de dónde viene, y eso oculta dependencias. Es una decisión razonable aquí; en un proyecto con veinte módulos de dominio yo preferiría importar explícitamente.

AppModule.forRoot(env): un módulo dinámico

El módulo raíz no es un decorador estático. Es una función que recibe el entorno ya validado y devuelve la definición del módulo:

static forRoot(env: Env): DynamicModule {
  const features = featuresOf(env);
  return {
    module: AppModule,
    imports: [
      ConfigProviderModule.forEnv(env),
      DatabaseModule, RateLimitModule, AuditModule, MailModule,
      MfaModule,
      TasksModule,
      ...(features.auth ? [SessionsModule, AuthModule, UsersModule, AuditLogsModule] : []),
      ...(features.accountSecurity ? [RecoveryModule, MfaRoutesModule] : []),
    ],
    controllers: [HealthController, SystemController],
    providers: [ SeedService, CleanupService, JwtAuthGuard, /* … APP_GUARD, APP_PIPE, … */ ],
  };
}

Eso resuelve algo que en Hono se hace con if al montar rutas: con AUTH_MODE=none las rutas de autenticación no existen (no es que devuelvan 404 por una condición, es que el módulo nunca se carga). El entorno entra por un token de inyección, no por una variable global:

export const APP_ENV = Symbol("APP_ENV");
// en el proveedor:   { provide: APP_ENV, useValue: env }
// en cualquier clase: constructor(@Inject(APP_ENV) private readonly env: Env) {}

La consecuencia práctica es la que más me gusta de este diseño: los tests pueden construir la aplicación con el entorno que quieran (AppModule.forRoot(loadEnv()) con otras variables) sin tocar process.env más allá de lo imprescindible.

Los cinco proveedores globales y su orden

AppModule registra cinco piezas con los tokens especiales APP_GUARD, APP_PIPE, APP_INTERCEPTOR y APP_FILTER. Se aplican a todas las rutas, y el orden en que Nest las ejecuta es fijo:

Una nota sobre el paso 2: en AppModule el guard aparece dos veces, JwtAuthGuard como proveedor normal y { provide: APP_GUARD, useExisting: JwtAuthGuard }. No es un descuido: el AuthPrefixMiddleware necesita la misma instancia del guard para llamar a authenticate(), y useExisting evita que Nest cree dos instancias distintas.

Dos consecuencias de este orden que merece la pena saber, porque no son evidentes:

1. El rate limit se ejecuta después de autenticar. Como /login y /register son @Public(), para ellas el guard de JWT es un simple «pasa», y el límite por IP actúa de verdad. Pero en una ruta protegida, un cliente sin token recibe 401 antes de gastar un solo contador.
2. La validación ocurre antes que tu código. Tu controlador nunca ve un cuerpo, un query o unos params sin validar. Lo que evita filtrar campos sensibles en la salida no es un serializador, sino el omit global de Prisma (la contraseña y el material de 2FA nunca salen de la base de datos salvo en el login). En main había además un ZodSerializerInterceptor registrado globalmente que no validaba nada: ninguna ruta de la plantilla declara un esquema de respuesta (busqué ZodResponse y ZodSerializerDto en src/: solo aparecía en un comentario del controlador de salud). El PR #8 lo quita para que nadie crea que las respuestas se validan; si algún día quieres validar la salida, añade un DTO de respuesta por ruta y vuelve a registrarlo.

Decoradores propios: @Public, @AuthUser, @RateLimit

Los decoradores de Nest son metadatos más una convención. Los tres que usa la plantilla ocupan menos de 15 líneas cada uno:

// @Public(): marca la ruta; el guard lee el metadato con Reflector
export const IS_PUBLIC_KEY = "isPublic";
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

// @AuthUser(): extrae el usuario que el guard dejó en la petición
export const AuthUser = createParamDecorator(
  (_data: unknown, ctx: ExecutionContext): AuthUserPayload =>
    ctx.switchToHttp().getRequest<RequestWithUser>().user as AuthUserPayload,
);

Y así quedan en un controlador (el de login, recortado): @Post("login") @Public() @HttpCode(200) @RateLimit("login") @TopLevelEnvelope(). Cuatro decoradores y sabes qué hace la ruta sin abrir el método: pública, devuelve 200, limitada y con el sobre «plano». Esa legibilidad por metadatos es el argumento a favor de NestJS; el argumento en contra es que hay que conocer el sistema para entender qué ocurre entre los decoradores (el orden de la tabla anterior).

El sobre de respuesta

Todas las respuestas tienen la misma forma (TransformInterceptor), también los errores (AllExceptionsFilter), con un requestId para rastrear en los logs. Es la misma forma que usa la plantilla de Hono:

{
  "success": false,
  "message": "Validation error in request payload",
  "errors": { "title": ["Title must be at least 3 characters long"] },
  "meta": {
    "requestId": "3681cb18-ac3c-4363-a142-0293a3fe5646",
    "timestamp": "2026-10-24T05:51:20.061Z",
    "durationMs": 2.4,
    "apiVersion": "2.0.0"
  }
}

Una ruta que no existe responde con el mismo sobre ("Route not found: GET /nada", 404). Lo único que no va envuelto es /healthz, a propósito, para que lo consuma un orquestador:

{"status":"healthy","timestamp":"2026-10-24T05:44:46.666Z","uptimeSeconds":7,"database":{"status":"connected","latencyMs":1}}

Los logs de Nest, por el contrario, no son JSON: salen en texto con el formato [Nest] pid - fecha LOG [Contexto] mensaje. En main, dentro de un contenedor llevaban además códigos de color ANSI salvo que definieras NO_COLOR=1 (lo medí: 62 líneas con secuencias ESC sin la variable, 0 con ella). El PR #8 lo corrige: en producción el logger se crea con colors: false (el nivel sale de LOG_LEVEL, en src/logging.ts, con su prueba) y en la imagen del PR conté 0 líneas con ESC de 110 sin tocar nada. Siguen siendo texto, no JSON (ver «Lo que queda por pulir»).

Validación y errores: el viaje de una petición mala

El 80 % del trabajo de una API real es decir «no» con educación y con la misma forma siempre. Aquí hay tres piezas que lo hacen y que conviene entender juntas: los esquemas de Zod, el ContractValidationPipe y el AllExceptionsFilter.

Un esquema, tres usos

Los esquemas viven en src/schemas/request.schemas.ts (Zod 4) y se usan para tres cosas a la vez: validar la entrada, tipar el controlador y generar OpenAPI. El pegamento es createZodDto de nestjs-zod (versión 5.5.0, vendorizada en vendor/ porque la plantilla fija esa versión):

export const createTaskSchema = z.object({ title: z.string().min(3, "Title must be at least 3 characters long").max(100) /* … */ });
export class CreateTaskRequest extends createZodDto(createTaskSchema) {}

// en el controlador:
async create(@Body() dto: CreateTaskRequest) { /* dto ya está validado y tipado */ }

El truco es que CreateTaskRequest es una clase real (Nest necesita clases para los metadatos de @Body()) cuyo contenido se deriva del esquema. Con class-validator tendrías el esquema repartido en decoradores; aquí es un objeto que puedes reutilizar, componer (.extend, .pick, ...listParams) y probar suelto.

El pipe: el mensaje depende de dónde falló

ContractValidationPipe envuelve al ZodValidationPipe de nestjs-zod por una razón concreta: la librería solo lleva el ZodError, y la API de referencia (la de Hono) devuelve un mensaje distinto según el origen del fallo. El pipe lo traduce. Salida real contra mi instancia local:

POST /api/tasks   {"title":"ab","status":"nope"}
HTTP 400
{"success":false,"message":"Validation error in request payload",
 "errors":{"title":["Title must be at least 3 characters long"]}, "meta":{…}}

GET /api/tasks?limit=-5
HTTP 400
{"success":false,"message":"Invalid request query parameters",
 "errors":{"limit":["Too small: expected number to be >=1"]}, "meta":{…}}

Mira la primera: yo envié también "status":"nope" y no aparece en errors. Es el comportamiento por defecto de z.object: los campos desconocidos se descartan en silencio, no se rechazan. Es lo contrario de .strict(). Para una API pública suele ser lo cómodo; si prefieres que un cliente con un campo mal escrito se entere, tendrías que añadir .strict() en los esquemas. Y es la razón por la que mi prueba de asignación masiva (role: "admin" en el registro) terminó en role: "user": el campo no llega al servicio.

El filtro: la tabla de traducción

AllExceptionsFilter es un @Catch() sin argumentos: atrapa todo. Lo que hace es una cadena de if ordenada de lo más específico a lo más general. La tabla, leída del código y confirmada con las pruebas del repositorio y con curl donde se indica:

Tres detalles finos que me parecen buenas decisiones:

• El 404 de enrutado se reescribe. Nest responde por defecto Cannot GET /nada; el filtro lo cambia a Route not found: GET /nada para que sea idéntico al de la plantilla de Hono. Sin eso, un cliente tendría que tratar dos formatos de 404.
• El 500 no filtra nada en producción. Solo con NODE_ENV=development el mensaje del error interno se incluye en details; con production el cuerpo es siempre Internal server error. y la traza va al log. (Esto lo leo del código; no provoqué un 500 real para verlo.)
• Los errores de body-parser no pasan por el filtro. Express procesa el cuerpo antes de que Nest enrute, así que el 400/413 sale de un middleware de error en configure-app.ts, no del filtro. Los dos usan el mismo constructor de cuerpos (buildErrorPayload) para que el resultado sea idéntico; hay incluso una rama «cinturón y tirantes» en el filtro por si algún día cambia el orden.

Un 404 que no es lo que parece

Una petición GET /api/tasks/no-es-uuid devuelve 404 («Task with ID 'no-es-uuid' not found»), no 400. Los identificadores se tratan como cadenas opacas: no se exige formato UUID en la ruta. Es coherente con el diseño (un id que no existe y un id mal formado son lo mismo para el cliente) y evita validar de más, pero conviene saberlo si esperabas un 400.

Registro: el hueco entre «comprobar» y «crear»

El register hace primero un findUnique por email y, si no existe, un create. Entre ambas operaciones hay un hueco en el que otra petición puede colarse. Lo que decide el resultado no es el código de la aplicación, sino el índice único de la base de datos y el filtro (P2002 → 409). Lo probé con 8 peticiones simultáneas con el mismo email, tres rondas, y luego con 12 en la batería de ataques:

ronda 1 (8 registros simultáneos, mismo email):   1 × 201   7 × 409
ronda 2:                                          1 × 201   7 × 409
ronda 3:                                          1 × 201   7 × 409
12 registros simultáneos del mismo email:         201: 1, 409: 11
SELECT email, count(*) … GROUP BY email  →  una fila por email (3 filas, count=1)
logs: 0 líneas ERROR

Exactamente un ganador, ningún 500 y ninguna fila duplicada. Esa es la diferencia entre «comprobar y luego insertar» a secas y hacerlo con una restricción única detrás: la comprobación previa es solo para dar un mensaje amable; la garantía la da el índice.

Autenticación por dentro

Este es el corazón de la plantilla y la parte en la que más tiempo he invertido. Te lo cuento en el orden en que ocurre.

1. Contraseñas: Argon2id, con un truco contra el timing

src/common/utils/password.ts usa Argon2id con los parámetros mínimos recomendados por OWASP (19 MiB de memoria, 2 iteraciones, 1 hilo):

const ARGON2_OPTIONS = { memoryCost: 19_456, timeCost: 2, parallelism: 1 } as const;

export async function comparePassword(plainPassword: string, stored: string): Promise<boolean> {
  if (stored.startsWith("$argon2")) return verify(stored, plainPassword);
  if (stored.startsWith("$2")) return bcrypt.compare(plainPassword, stored); // legacy
  return false;   // formato desconocido: falla cerrado
}

export function needsRehash(stored: string): boolean {
  return !stored.startsWith("$argon2");
}

Tres cosas buenas aquí. Primera: un formato de hash desconocido nunca autentica. Segunda: si vienes de una versión antigua con bcrypt, los hashes antiguos siguen valiendo y se actualizan en el sitio tras el siguiente login correcto (migración progresiva, sin reescribir nada en masa). Tercera: cuando el email no existe, el login compara contra un hash falso real (getDummyHash()), para que existir o no existir tarde lo mismo. Lo comprobé en la base de datos: los hashes guardados tienen la forma $argon2id$v=19$m=19456,t=2,p=1$….

¿Y el timing? Medí el login de un email existente con contraseña incorrecta contra uno inexistente, en varias rondas (limpiando los contadores entre una y otra): las medianas se solapan (17,9–34,7 ms existente, 18–23,4 ms inexistente) y un login correcto tarda unos 17 ms. No es una prueba estadística seria, pero no vi ninguna diferencia sistemática.

2. El login, paso a paso

El método login de auth.controller.ts hace, en este orden:

1. Bloqueo por cuenta antes de mirar la contraseña (5 fallos → 429 durante 15 minutos), incluso para emails que no existen.
2. Busca el usuario (con omit: { password: false } solo aquí) y compara con el hash real o con el falso.
3. Si falla: lockout.recordFailure(email) y un registro LOGIN_FAILED en auditoría con un seudónimo del email (nunca la dirección en claro).
4. Solo después de acertar la contraseña comprueba si la cuenta está bloqueada o sin verificar (así no se puede enumerar el estado de una cuenta sin saber su contraseña).
5. Si el usuario tiene 2FA activado, exige el código TOTP o un código de recuperación (MFA_REQUIRED / MFA_INVALID).
6. Rehash a Argon2id si hace falta, reinicio del contador y creación de la sesión.

{
  "success": true,
  "message": "Authentication successful",
  "accessToken": "eyJhbGciOiJIUzI1NiIs…",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs…",
  "expiresIn": 900,
  "sessionId": "24bd1ca5-75b1-42b1-8…",
  "user": { "id": "user-2", "name": "Ana García", "email": "[email protected]", "role": "user" },
  "meta": { "requestId": "20e9a244-…", "timestamp": "2026-10-24T05:51:19.946Z", "durationMs": 137.34, "apiVersion": "2.0.0" }
}

El access token dura 15 minutos y lleva el sessionId; el refresh token se firma con otro secreto y la sesión tiene un tope absoluto de 7 días. Los refresh tokens se guardan solo como hash SHA-256.

3. El guard que lo revisa todo en cada petición

JwtAuthGuard es global: todas las rutas exigen autenticación salvo las marcadas con @Public() (deny-by-default, mejor que al revés). Este es su corazón, recortado:

payload = this.jwt.verify<JwtPayload>(token, { secret: this.env.JWT_SECRET, algorithms: ["HS256"] });
// …
const [user, session] = await Promise.all([
  this.prisma.user.findUnique({ where: { id: payload.userId },
    select: { id: true, role: true, isBlocked: true, blockedReason: true, deletedAt: true } }),
  this.prisma.session.findUnique({ where: { id: payload.sessionId },
    select: { userId: true, isActive: true, expiresAt: true } }),
]);
if (!user || user.deletedAt)  throw new UnauthorizedException("…no longer exists.");
if (user.isBlocked)           throw new ForbiddenException("Access denied: Account has been suspended…");
if (!session?.isActive || session.userId !== user.id || session.expiresAt < new Date())
  throw new UnauthorizedException("Session has been revoked or expired. Please sign in again.");
request.user = { userId, sessionId, email, role: user.role };   // el rol sale de la BD

Por eso un token con la firma perfecta puede dar 401 (la sesión se revocó) o 403 (el usuario está bloqueado) antes de que caduque, y por eso el rol se lee de la base de datos y no del token: si degradas a un administrador, el cambio vale en la siguiente petición. El precio: dos lecturas de BD por petición autenticada (son por clave primaria y van en paralelo con Promise.all).

Hay una pieza más, el AuthPrefixMiddleware, que existe por una razón sutil: un guard global solo se ejecuta en rutas que coinciden. Sin él, un sondeo a /api/tasks/lo/que/sea sin token devolvería 404 y filtraría qué rutas existen. Con él, los cuatro prefijos protegidos (/api/sessions, /api/users, /api/tasks, /api/audit-logs) y todas sus subrutas dan 401 sin token. Con Express 5 el comodín se escribe {*splat}:

...["api/sessions", "api/users", "api/tasks", "api/audit-logs"].flatMap((prefix) => [
  { path: prefix, method: RequestMethod.ALL },
  { path: `${prefix}/{*splat}`, method: RequestMethod.ALL },
]),

Lo comprobé con curl: GET /api/tasks/no/existe sin token → 401; con token → 404.

4. Rotación de refresh tokens y detección de robo

Cada refresh token solo vale una vez. El truco para que dos peticiones simultáneas no ganen las dos es un updateMany atómico dentro de una transacción:

const rotated = await this.prisma.$transaction(async (tx) => {
  const claimed = await tx.refreshToken.updateMany({
    where: { tokenHash, sessionId, usedAt: null, expiresAt: { gt: now } },
    data: { usedAt: now },
  });
  if (claimed.count !== 1) return false;       // alguien lo usó antes que yo
  await tx.refreshToken.create({ data: { tokenHash: hashToken(next.refreshToken), userId: user.id, sessionId, expiresAt: next.refreshExpiresAt } });
  return true;
});
// si no ganó: ¿fue hace menos de REFRESH_REUSE_GRACE_SECONDS (10 s)? → 409 (concurrente)
// si fue hace más → se considera robo: revokeSession(sessionId) y 401

Lo que pasó en mis pruebas reales:

Es decir: la «familia» de tokens es la sesión, y revocarla no desloguea al usuario en sus otros dispositivos. Matiz honesto: la ventana de gracia de 10 s significa que un atacante que reproduzca un token dentro de esos segundos solo recibe un 409, no una revocación.

5. Fuerza bruta, bloqueo y rate limiting

Hay dos capas y conviene no confundirlas:

• Por IP (RateLimitGuard): contadores de ventana fija en la base de datos (RateLimitBucket), así que valen para varias instancias. Se aplica solo a las rutas con @RateLimit(...): login 10/min, refresh 30/min, registro 5/h, recuperación y MFA. Devuelve X-RateLimit-Limit y X-RateLimit-Remaining. Si el almacén falla, en las rutas críticas aplica una ventana local en memoria (RATE_LIMIT_ON_DB_FAILURE=local) en vez de abrirse.
• Por cuenta (LoginLockoutService): 5 fallos → 15 minutos de bloqueo, con una clave seudonimizada, comprobado antes de la contraseña.

intentos 1–5 con contraseña incorrecta → 401
intento 6 (incluso con la contraseña CORRECTA) → 429, Retry-After: 900
la sesión admin que ya estaba abierta → sigue funcionando
11ª petición de login desde una IP → 429
13 emails distintos desde la misma IP → 429 a partir del 11º
rotando X-Forwarded-For / CF-Connecting-IP / X-Real-IP con TRUST_PROXY=false → 429 igualmente

Un matiz que conviene saber: el bloqueo por cuenta es también una palanca de denegación: cualquiera puede dejar a un usuario sin poder iniciar sesión 15 minutos (sus sesiones abiertas no se ven afectadas). Es un compromiso habitual y está documentado, pero es un compromiso.

6. 2FA con TOTP y códigos de recuperación

Con AUTH_MODE=full, un usuario puede activar TOTP (SHA-1, 6 dígitos, 30 s, ±1 ventana). Los detalles que importan y que comprobé de extremo a extremo:

• Para iniciar la configuración (/api/auth/mfa/setup) hay que reconfirmar la contraseña: con una incorrecta, 403.
• El secreto se guarda cifrado con AES-256-GCM (en la BD empieza por v1.); la clave es MFA_ENCRYPTION_KEY, y con MFA_ENCRYPTION_KEY_PREVIOUS se puede rotar sin perder los dispositivos ya enrolados (el ensayo ops-rehearsal.sh mfa-rotation pasó: K1 → K1+K2 → K2, con el secreto recifrado de forma perezosa).
• enable con 000000 → 400; con un código real → devuelve 10 códigos de recuperación (solo se guardan sus hashes).
• Login sin código → MFA_REQUIRED; código erróneo → MFA_INVALID (y cuenta como fallo para el bloqueo); código correcto → 200.
• Un código TOTP no se puede reutilizar (totpLastStep): repetirlo da 401. Un código de recuperación funciona una vez y luego da 401.

7. Verificación de email y recuperación de contraseña

Los correos no se envían dentro de la petición HTTP: se encolan en EmailOutbox y un worker los entrega con reintentos acotados (5 intentos, con espera). Los enlaces llevan un token aleatorio de un solo uso del que solo se guarda el hash SHA-256, y está atado al email al que se envió: si el usuario cambia de email, el enlace viejo deja de valer. forgot-password valida el cuerpo y responde sin revelar si la cuenta existe (hay una prueba del contrato que lo fija; con MAIL_TRANSPORT=none lo vi devolver 202).

Esta parte la comprobé con el harness de contrato (grupo recovery, 11 pruebas en verde) usando un servidor SMTP de pruebas que incluye el propio repositorio. No he probado un envío real con un proveedor SMTP.

8. El limitador por dentro: una fila, una sentencia

El limitador por IP y el bloqueo por cuenta comparten una sola tabla, RateLimitBucket, que es lo más simple que se puede imaginar:

CREATE TABLE "RateLimitBucket" ("key" TEXT NOT NULL PRIMARY KEY, "count" INTEGER NOT NULL, "resetAt" DATETIME NOT NULL)

Después de seis intentos de login fallidos a [email protected] y un séptimo con la contraseña correcta (que también dio 429), esto es lo que había en la tabla (consulta real a la base de datos de mi instancia local):

('rl:login:127.0.0.1',                       7, '2026-10-24T06:35:14.252+00:00')   ← 7 peticiones en la ventana de 1 min
('lockout:a163bdfbd5cea78c30b92db0067a6552', 5, '2026-10-24T06:49:14.395+00:00')   ← 5 fallos, bloqueo 15 min

Dos cosas se ven a simple vista. El 6.º intento ya devolvió 429 y no sumó al contador de fallos (se quedó en 5): la comprobación de bloqueo va antes de la contraseña. Y la clave de bloqueo no lleva el email, lleva un seudónimo (lockout:a163…), un HMAC con una clave derivada de JWT_SECRET. Quien lea la tabla no obtiene direcciones de correo.

El código que incrementa el contador es esta función de 30 líneas:

async hit(key: string, windowMs: number): Promise<Bucket> {
  for (let attempt = 0; attempt < 3; attempt++) {
    const now = new Date();
    // 1) incremento atómico de una ventana viva
    const updated = await this.prisma.rateLimitBucket.updateMany({
      where: { key, resetAt: { gt: now } }, data: { count: { increment: 1 } },
    });
    if (updated.count === 0) {
      // 2) no hay ventana viva: borra la caducada (si existe) y abre una nueva
      await this.prisma.rateLimitBucket.deleteMany({ where: { key, resetAt: { lte: now } } });
      try {
        return await this.prisma.rateLimitBucket.create({ data: { key, count: 1, resetAt: new Date(now.getTime() + windowMs) }, select: { count: true, resetAt: true } });
      } catch (error) {
        // 3) otra instancia abrió la ventana primero: reintenta como incremento
        if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === "P2002") continue;
        throw error;
      }
    }
    const bucket = await this.prisma.rateLimitBucket.findUnique({ where: { key }, select: { count: true, resetAt: true } });
    if (bucket) return bucket;
  }
  throw new Error(`Could not update rate limit bucket '${key}'`);
}

No hay leer–modificar–escribir en código de aplicación: cada paso es una sentencia atómica y la carrera se resuelve con la clave primaria (el P2002) y un bucle de hasta tres intentos. Es un diseño que funciona con varias instancias compartiendo una base de datos (Turso), que es justo para lo que está pensado.

Para el bloqueo, recordFailure añade una pieza más: tras sumar el fallo llama a slide(), que empuja resetAt hacia adelante. Es una ventana deslizante: el bloqueo se mide desde el último fallo, no desde el primero. Sin ello, cinco fallos repartidos a lo largo de 14 minutos desbloquearían la cuenta un minuto después del último.

Y el guard, cuando la tabla no está disponible, no se limita a «abrir la mano»:

// RATE_LIMIT_ON_DB_FAILURE=local (por defecto): login, refresh, register, recuperación y MFA
// siguen limitados con una ventana en memoria del proceso; el resto de rutas falla abierto.
// Además cuenta métricas: storeFailures, localAllowed, localBlocked, openAllowed.

9. TOTP: comprobado contra los vectores de la RFC 6238

La plantilla no usa ninguna librería de TOTP: implementa HOTP/TOTP en unas 80 líneas con node:crypto (createHmac("sha1", …), truncamiento dinámico, timingSafeEqual). Eso se puede fiar si y solo si coincide con los vectores oficiales, así que los ejecuté contra TotpService compilado. El apéndice B de la RFC 6238 da códigos de 8 dígitos para el secreto ASCII 12345678901234567890; el servicio emite 6, que son los seis últimos dígitos:

secreto base32: GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
t=59           RFC: 94287082 → últimos 6: 287082 | servicio: 287082 OK
t=1111111109   RFC: 07081804 → últimos 6: 081804 | servicio: 081804 OK
t=1111111111   RFC: 14050471 → últimos 6: 050471 | servicio: 050471 OK
t=1234567890   RFC: 89005924 → últimos 6: 005924 | servicio: 005924 OK
t=2000000000   RFC: 69279037 → últimos 6: 279037 | servicio: 279037 OK

Cinco de cinco. Y el comportamiento alrededor del código, también real:

mismo paso, lastStep=null                  → 56666666   (paso aceptado: se devuelve el contador)
mismo paso, lastStep=paso                  → null       (repetición rechazada)
código del paso anterior (+30 s después)   → 56666666   (dentro de la ventana ±1)
código con 90 s de retraso                 → null       (fuera de ventana)
código '12345' (5 dígitos)                 → null

El método verifyTotp recorre siempre los tres candidatos (paso−1, paso, paso+1) y no sale al primer acierto, con timingSafeEqual en cada comparación: así el tiempo de respuesta no revela cuál coincidió. La condición step > lastStep impide reutilizar un código, y MfaService la convierte en una sentencia atómica (updateMany … WHERE totpLastStep IS NULL OR totpLastStep < step): dos peticiones simultáneas con el mismo código no pueden ganar las dos.

El cifrado en reposo, ejecutado igualmente:

cifrado: v1 . 16 car. . 22 car. . 43 car.          ← versión . IV (12 bytes) . etiqueta GCM . texto cifrado
dos cifrados del mismo secreto iguales?  false      ← IV aleatorio
descifrar con K1:                       {"secret":"GEZD…","fromPreviousKey":false}
descifrar con K2 (previous=K1):         {"secret":"GEZD…","fromPreviousKey":true}   ← y MfaService lo recifra con K2
descifrar con una clave ajena      →    Unable to decrypt TOTP secret: no configured MFA key matches
cifrado manipulado (1 carácter)    →    Unable to decrypt TOTP secret: no configured MFA key matches

Esa última línea es la gracia de AES-GCM: no solo cifra, autentica. Cambiar un solo carácter del texto cifrado hace que el descifrado falle en vez de devolver basura. Y los códigos de recuperación (xguy-uxd6-6b4o-b7km, 16 caracteres base32 = 80 bits aleatorios) se guardan solo como SHA-256: 80 bits de entropía hacen innecesario un hash lento.

10. La bandeja de salida de correo: simulada con tiempo virtual

La verificación de email y la recuperación de contraseña dependen de que el correo salga aunque el proveedor falle o el proceso se reinicie. Eso lo resuelve EmailOutboxService, un patrón conocido (transactional outbox): la petición solo escribe una fila (EmailOutbox) y un worker la entrega, con reintentos. Las piezas, en orden:

• Reclamar una fila es atómico: updateMany WHERE id = … AND status = 'pending' pasa la fila a sending. Dos instancias no pueden entregar el mismo correo; la que pierde la carrera busca la siguiente.
• Filas huérfanas. Si un worker muere con la fila en sending, a los 5 minutos otro la vuelve a pending.
• El token se crea al entregar, no al encolar. Así el token en claro nunca se guarda: en la fila solo hay userId y type.
• Fallos terminales sin reintentar: con MAIL_TRANSPORT=none, o si la cuenta ya no existe o está bloqueada, la fila se retira en el acto (no tiene sentido reintentar).

El comentario del código decía «5 intentos, ≈15 minutos» (en main sigue diciéndolo). Quise comprobarlo y lo hice sin red ni SMTP: instancié el servicio compilado con una base de datos en memoria falsa y un transporte que siempre falla, y avancé un reloj virtual:

WARN  Email delivery failed (attempt 1/5, type=email_verify), retrying in 30s
t=   0 s → intento 1 fallido, estado=pending
WARN  Email delivery failed (attempt 2/5, …), retrying in 60s
t=  30 s → intento 2 fallido, estado=pending
WARN  Email delivery failed (attempt 3/5, …), retrying in 120s
t=  90 s → intento 3 fallido, estado=pending
WARN  Email delivery failed (attempt 4/5, …), retrying in 240s
t= 210 s → intento 4 fallido, estado=pending
ERROR Email delivery abandoned after 5 attempts (type=email_verify)
t= 450 s → intento 5 fallido, estado=failed
métricas: {"enqueued":0,"sent":0,"retried":4,"failed":1}

El resultado real: se rinde a los 450 segundos (7,5 minutos), no a los ≈15 minutos del comentario. La tabla de esperas tenía cinco valores (30, 60, 120, 240 y 480 s), pero el quinto intento es el último y, al fallar, no hay un «siguiente»: la espera de 480 s nunca se usaba. Es un detalle menor (el usuario siempre puede pedir otro enlace), pero es el tipo de cosa que solo aparece cuando ejecutas el código. El PR #8 deja la tabla en cuatro esperas (30, 60, 120 y 240 s) y corrige el comentario a «7,5 minutos»: el comportamiento no cambia, solo deja de mentir. (La traza de arriba es la medida original sobre 758a0ac; no la repetí con el cambio.)

11. La limpieza horaria

CleanupService arranca con un ciclo inmediato y un temporizador cada hora (con unref(), para no impedir que el proceso termine). Qué borra y cuándo:

Hay una sutileza que me gustó: purgar un refresh token rotado no rompe la detección de robo. Un token ya purgado que alguien reproduzca no coincide con ninguna fila, y el código lo trata igual que uno reutilizado (revoca la sesión). Y los fallos de limpieza se atrapan y se registran: un error en la limpieza nunca tumba la petición ni el proceso.

Los recursos: tareas, usuarios, sesiones y auditoría

Con AUTH_MODE=full el OpenAPI generado tiene 25 paths, 31 operaciones y 18 esquemas. Así se reparten (las etiquetas son las de Scalar):

Las listas aceptan paginación, ordenación y filtros con corchetes, y include para relaciones. Un ejemplo real con el administrador de la demo (todas las tareas, las que contienen «UI», con su usuario):

curl -g "localhost:3011/api/tasks?scope=all&filter[title][contains]=UI&include=user&sort=-createdAt" \
  -H "authorization: Bearer $TOKEN"

{
  "success": true,
  "data": [
    { "id": "task-3", "userId": "user-2", "title": "Design Frontend UI",
      "description": "Build web dashboard consuming the REST API.", "completed": false,
      "deletedAt": null, "createdAt": "2026-10-24T05:43:37.489Z",
      "user": { "id": "user-2", "email": "[email protected]", "name": "Ana García" } }
  ],
  "pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1, "hasNextPage": false, "hasPrevPage": false },
  "meta": { "requestId": "7cf2680b-…", "timestamp": "2026-10-24T05:44:12.010Z", "durationMs": 8.09, "apiVersion": "2.0.0" }
}

Reglas de acceso que verifiqué con un usuario normal: 403 en todas las rutas de administrador (usuarios, auditoría, scope=all), y 404 (no 403) al pedir una tarea o una sesión ajena, para que no se pueda sondear qué identificadores existen. Los ataques de asignación masiva no funcionan: registrarse con role: "admin" da role: "user", un PUT con role no lo cambia y una tarea enviada con userId, id o deletedAt ignora esos campos. Las tareas se borran de forma lógica (DELETE) y se pueden restaurar (POST …/restore). Además hay protecciones del último administrador: no se puede degradar, bloquear ni borrar (409/400).

Documentación OpenAPI y Scalar

La documentación se genera con @nestjs/swagger y la integración con Zod, y se sirve con Scalar en /docs (y el JSON en /openapi.json). Verifiqué que /docs responde 200 text/html en desarrollo y 404 en producción (salvo ENABLE_DOCS=true), con una CSP propia solo para esa ruta. La spec es OpenAPI 3.0.0 con un esquema de seguridad BearerAuth, y el repositorio incluye una prueba que la valida con @apidevtools/swagger-parser. Y, como te enseñé arriba, los módulos desactivados por AUTH_MODE desaparecen de la documentación.

A diferencia de la de Hono, donde cada ruta se declara una sola vez y la documentación sale del mismo código que valida, aquí la validación (Zod) y la documentación (decoradores @ApiOperation…) se escriben en sitios distintos del controlador. Funciona y la prueba de contrato ayuda a que no se desincronicen, pero la posibilidad de que deriven existe.

Tutorial: añadir un recurso nuevo (notas privadas), de punta a punta

Hasta aquí he descrito la plantilla. Ahora la uso. El ejercicio: añadir un recurso Note (notas privadas de cada usuario) con CRUD completo, siguiendo las convenciones del repositorio. Lo hice en una copia del repositorio, no en el original, y todo lo que ves a continuación está ejecutado: el código, las migraciones, las pruebas y las respuestas. El resultado fue un modelo de Prisma, una migración, 4 ficheros nuevos, 3 líneas en app.module.ts (con el import) y 7 pruebas.

Paso 1: el modelo (prisma/schema.prisma)

model Note {
  id        String   @id @default(uuid())
  userId    String
  title     String
  body      String   @default("")
  pinned    Boolean  @default(false)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  user User @relation(fields: [userId], references: [id], onDelete: Cascade)

  // Listado del dueño: primero las fijadas, luego las más recientes
  @@index([userId, pinned, createdAt])
}

Y en model User, la relación inversa: notes Note[]. Dos decisiones: onDelete: Cascade (si se borra un usuario, se van sus notas, igual que ocurre con sus sesiones) y un índice compuesto que coincide con la consulta del listado (dueño → fijadas → fecha).

Paso 2: la migración

npx prisma migrate dev --name notes

Prisma generó prisma/migrations/20261024061724_notes/migration.sql con este contenido, sin que yo escribiera una línea de SQL:

-- CreateTable
CREATE TABLE "Note" (
    "id" TEXT NOT NULL PRIMARY KEY,
    "userId" TEXT NOT NULL,
    "title" TEXT NOT NULL,
    "body" TEXT NOT NULL DEFAULT '',
    "pinned" BOOLEAN NOT NULL DEFAULT false,
    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updatedAt" DATETIME NOT NULL,
    CONSTRAINT "Note_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User" ("id") ON DELETE CASCADE ON UPDATE CASCADE
);

-- CreateIndex
CREATE INDEX "Note_userId_pinned_createdAt_idx" ON "Note"("userId", "pinned", "createdAt");

La migración se versiona en git y es lo que ejecuta el contenedor al arrancar (prisma migrate deploy). Un detalle curioso: al guardar el esquema, prisma format realineó las columnas de otro modelo (EmailOutbox) que yo no toqué. Es solo espacio en blanco, pero te ensucia el diff: revisa siempre qué ficheros cambian antes de hacer commit.

Paso 3: los esquemas de Zod (src/schemas/request.schemas.ts)

/** Notas: crear (los valores por defecto los pone Zod) */
export const createNoteSchema = z.object({
  title: z.string().trim()
    .min(1, { message: "Title is required" })
    .max(100, { message: "Title cannot exceed 100 characters" })
    .meta({ example: "Idea para el viernes" }),
  body: z.string().max(5000, { message: "Body cannot exceed 5000 characters" }).optional().default(""),
  pinned: z.boolean().optional().default(false),
});

/** Notas: actualizar. Sin `default()`: un PUT parcial no debe pisar campos que no envía */
export const updateNoteSchema = z
  .object({
    title: z.string().trim().min(1).max(100).optional(),
    body: z.string().max(5000).optional(),
    pinned: z.boolean().optional(),
  })
  .refine((data) => Object.keys(data).length > 0, {
    message: "Provide at least one field to update (title, body or pinned)",
  });

/** Notas: query del listado */
export const noteQuerySchema = z.object({
  ...listParams,
  pinned: z.enum(["true", "false"]).optional(),
  sortBy: z.enum(["createdAt", "title"]).default("createdAt"),
});

Mira la diferencia entre crear y actualizar: en crear, body y pinned llevan .default(); en actualizar, no. Si los llevaran, un PUT con solo { "title": "nuevo" } pondría body a "" y pinned a false: borraría datos sin avisar. Es un error clásico con Zod y lo cubre una de las pruebas. El .refine rechaza un cuerpo vacío ({}), y listParams reutiliza la paginación del resto de la API.

Paso 4: DTO, servicio, controlador y módulo

El DTO son tres líneas (createZodDto convierte cada esquema en una clase):

export class CreateNoteRequest extends createZodDto(createNoteSchema) {}
export class UpdateNoteRequest extends createZodDto(updateNoteSchema) {}
export class NoteQuery extends createZodDto(noteQuerySchema) {}

El servicio es el lugar para la regla importante: toda consulta lleva el userId del dueño, de modo que olvidarlo sea imposible por construcción.

@Injectable()
export class NotesService {
  constructor(private readonly prisma: PrismaService) {}

  async list(userId: string, q: { page: number; limit: number; search?: string; pinned?: string; sortBy: "createdAt" | "title"; order: "asc" | "desc" }) {
    const where: Prisma.NoteWhereInput = { userId };
    if (q.pinned !== undefined) where.pinned = q.pinned === "true";
    if (q.search) where.OR = [{ title: { contains: q.search } }, { body: { contains: q.search } }];
    const [total, items] = await Promise.all([
      this.prisma.note.count({ where }),
      this.prisma.note.findMany({
        where, skip: (q.page - 1) * q.limit, take: q.limit,
        orderBy: [{ pinned: "desc" }, { [q.sortBy]: q.order }],   // las fijadas siempre primero
      }),
    ]);
    return { total, items };
  }

  /** 404 tanto si no existe como si es de otro usuario: no se puede sondear qué ids existen */
  async getOwned(userId: string, id: string) {
    const note = await this.prisma.note.findFirst({ where: { id, userId } });
    if (!note) throw new NotFoundException(`Note with ID '${id}' not found.`);
    return note;
  }

  create(userId: string, data: { title: string; body: string; pinned: boolean }) {
    return this.prisma.note.create({ data: { ...data, userId } });
  }
  async update(userId: string, id: string, data: Prisma.NoteUpdateInput) {
    await this.getOwned(userId, id);
    return this.prisma.note.update({ where: { id }, data });
  }
  async remove(userId: string, id: string) {
    await this.getOwned(userId, id);
    await this.prisma.note.delete({ where: { id } });
  }
}

Fíjate en getOwned: devuelve 404 tanto si la nota no existe como si es de otro usuario. Un 403 le diría a un atacante «ese id existe, pero no es tuyo». El 404 no filtra nada.

El controlador es donde se ve el estilo de Nest: decoradores para la ruta, la documentación OpenAPI y la inyección. Estos son los puntos clave (completo, son 80 líneas):

@ApiTags("Notes")
@ApiBearerAuth("BearerAuth")
@Controller("api/notes")
export class NotesController {
  constructor(private readonly notes: NotesService, private readonly audit: AuditService) {}

  @Get()
  @ApiOperation({ summary: "Listar mis notas", description: "Paginado; las fijadas salen primero." })
  async list(@Query() q: NoteQuery, @AuthUser() user: AuthUserPayload) {
    const { total, items } = await this.notes.list(user.userId, q);
    return { data: items, pagination: buildPagination(total, q.page, q.limit) };
  }

  @Post()
  async create(@Body() dto: CreateNoteRequest, @AuthUser() user: AuthUserPayload, @Req() req: Request) {
    const note = await this.notes.create(user.userId, dto);
    await this.audit.record(req, { userId: user.userId, action: "CREATE", entity: "Note", entityId: note.id });
    return { message: "Note created successfully.", data: note };
  }
  // PUT :id, DELETE :id y GET :id siguen el mismo patrón
}

Nota que no hay ningún @UseGuards. No hace falta: el guard de JWT es global y deny-by-default, así que un controlador nuevo nace protegido. Tampoco construyo el sobre de respuesta ni gestiono errores: devuelvo { data, pagination } y el TransformInterceptor lo envuelve; lanzo NotFoundException y el filtro lo convierte al formato de error. Cada pieza hace una cosa, y yo solo escribo la que es mía.

El módulo, por último, tiene diez líneas:

@Module({ controllers: [NotesController], providers: [NotesService] })
export class NotesModule {}

Ni PrismaService ni AuditService aparecen en imports: son globales (ver la tabla de módulos).

Paso 5: registrarlo (y el gotcha que me dio un 404)

En app.module.ts hay que hacer dos cosas, y la segunda es la que se olvida:

// 1) montar el módulo solo cuando hay autenticación
...(features.auth ? [SessionsModule, AuthModule, UsersModule, AuditLogsModule, NotesModule] : []),

// 2) añadir el prefijo al AuthPrefixMiddleware
...["api/sessions", "api/users", "api/tasks", "api/audit-logs", "api/notes"].flatMap(/* … */)

Lo primero es obvio: con AUTH_MODE=none las notas no tienen dueño, así que el módulo no se monta. Lo segundo no lo es. Escribí primero la prueba «una subruta inexistente sin token debe dar 401» y falló con 404:

await http().get("/api/notes").expect(401);
await http().get("/api/notes/a/b/c").expect(401);   // sin el prefijo en el middleware: 404

Sin el prefijo, la ruta /api/notes sí era 401 (el guard global la cubre), pero /api/notes/a/b/c daba 404 y, con ello, filtraba que /api/notes es un prefijo real. Añadí "api/notes" a la lista y pasó. Esa es la trampa de la plantilla: la protección profunda de rutas depende de una lista escrita a mano. Y, como cuento en la sección de pruebas, en 758a0ac ninguna prueba del repositorio la vigilaba: si añadías un recurso y olvidabas la línea, nadie te avisaba. Mi prueba la convierte en una comprobación automática. El PR #8 añade test/auth-prefix.middleware.spec.ts, que recorre los cuatro prefijos originales, pero esa lista de la prueba también está escrita a mano: un recurso nuevo sigue necesitando su propia comprobación, como la mía.

Paso 6: las pruebas

Las pruebas siguen el estilo del repositorio (supertest contra la aplicación real, sin simular la base de datos): test/notes.spec.ts tiene 7 casos y cubre lo que importa de este recurso. Estos son los casos, con los nombres tal como los escribí en el fichero:

 PASS  test/notes.spec.ts
  notes: un recurso nuevo de punta a punta
    ✓ exige autenticación, también en subrutas que no existen
    ✓ valida el cuerpo y aplica los valores por defecto
    ✓ lista solo las notas propias, con las fijadas primero
    ✓ una nota ajena responde 404, igual que una que no existe
    ✓ un PUT parcial no pisa los campos que no envía y uno vacío da 400
    ✓ borrar y dejar rastro en la auditoría
    ✓ aparece en la especificación OpenAPI

La suite completa con mis 7 pruebas nuevas (sobre 758a0ac, con las 62 de entonces):

Test Suites: 10 passed, 10 total
Tests:       69 passed, 69 total
Time:        10.366 s

Es decir, 62 originales + 7 nuevas = 69, en 10 segundos. La rama del PR #8 tiene hoy 84 pruebas en 13 suites; no repetí el tutorial encima de ella. Durante el desarrollo me encontré dos problemas más, ambos con su solución en «Problemas reales y cómo los resolví»: un 429 inesperado al registrar tantos usuarios de prueba desde la misma IP (el límite de registro es 5 por hora) y el DATABASE_URL exportado que rompía la suite (corregido en el PR #8).

Paso 7: probarlo con curl

Levanté la copia con node dist/main.js y probé a mano. Respuestas reales (con los meta recortados):

# crear (el título llega con espacios; Zod lo recorta y pone los valores por defecto)
POST /api/notes {"title":"  Idea para el viernes  ","pinned":true}
HTTP 201
{"success":true,"message":"Note created successfully.",
 "data":{"id":"19ba614d-fd75-46e4-826a-4e0129af2467","userId":"080ff971-…","title":"Idea para el viernes","body":"","pinned":true,
         "createdAt":"2026-10-24T06:33:58.922Z","updatedAt":"2026-10-24T06:33:58.922Z"},"meta":{…}}

# crear con datos inválidos (dos errores a la vez, agrupados por campo)
POST /api/notes {"title":"","body":123}
HTTP 400
{"success":false,"message":"Validation error in request payload",
 "errors":{"title":["Title is required"],"body":["Invalid input: expected string, received number"]},"meta":{…}}

# listar con limit=2 (3 notas en total: la fijada primero, luego la más reciente)
GET /api/notes?limit=2
HTTP 200
{"success":true,"data":[ {"title":"Idea para el viernes","pinned":true,…}, {"title":"Llamar al banco","pinned":false,…} ],
 "pagination":{"total":3,"page":1,"limit":2,"totalPages":2,"hasNextPage":true,"hasPrevPage":false},"meta":{…}}

# buscar
GET /api/notes?search=banco   →   ['Llamar al banco']  {total: 1, page: 1, limit: 10, totalPages: 1, …}

# PUT vacío
PUT /api/notes/<id> {}
HTTP 400
{"success":false,"message":"Validation error in request payload",
 "errors":{"_root":["Provide at least one field to update (title, body or pinned)"]},"meta":{…}}

Paso 8: la documentación se actualiza sola

Sin tocar nada de OpenAPI, el documento pasó de 25 rutas y 31 operaciones a 27 rutas y 36 operaciones (/api/notes y /api/notes/{id}), y de 18 a 20 esquemas (CreateNoteRequest y UpdateNoteRequest). Eso es lo mejor de generar la especificación desde el código: no hay un fichero que se te olvide.

Lo que cuesta añadir un recurso

Contando solo lo que escribí: un modelo de 14 líneas, ~30 de esquemas Zod, 4 ficheros de código (DTO, servicio, controlador, módulo: unas 150 líneas en total), 3 líneas de registro y 108 de pruebas. Cada pieza tiene su sitio y ninguna es opcional. En Hono hay menos ceremonia (rutas y esquemas en un par de ficheros); aquí hay más ficheros, pero cada uno es predecible, y en un equipo grande eso es una ventaja: nadie discute dónde va cada cosa.

Probar la API

Las pruebas del repositorio (reales, en mi máquina)

Las 13 suites de Jest son app, auth-prefix.middleware, concurrency, email-outbox, env-guards, lockout-key, logging, password, rate-limit-resilience, system-docs, test-isolation, totp y trust-proxy (las cuatro que no estaban en main son auth-prefix.middleware, logging, system-docs y test-isolation). Me gusta que la concurrencia tenga su propia suite: comprueba que de varios refresh simultáneos gana exactamente uno, que la revocación gana a un refresh que corre a la vez, y que los contadores de rate limit son atómicos (admiten exactamente max). Y test-isolation fija que la suite nunca escribe en una base remota ni habla con un servidor de correo real.

El harness de contrato (npm run contract) arranca la app con una base de datos nueva por modo y ejecuta 11 escenarios HTTP (system, mounting, auth, sessions, tasks, users, audit, recovery, mfa, ratelimit, ratelimit-login) con un servidor SMTP de pruebas incluido. Fija los comportamientos concretos que tenía la plantilla de Hono: ids de la semilla, mensajes, códigos de estado. Es lo que da sentido al «paridad» del que habla el README.

Si rompo el código, ¿lo notan las pruebas? Un experimento de mutaciones

Que una suite esté en verde no dice mucho; lo que importa es si se pondría en rojo ante un fallo. Así que hice un experimento sencillo, de los que se llaman pruebas de mutación hechas a mano: copié el repositorio, rompí a propósito once trozos de código críticos (de uno en uno, restaurando después cada uno), y ejecuté las dos suites que trae la plantilla: las 62 pruebas de Jest y el «arnés de contrato» (95 pruebas HTTP contra el servidor compilado). Cada mutante es una frase: «¿qué pasaría si alguien cambiara esto?». (El experimento es del 24 de octubre, sobre 758a0ac; el único mutante que repetí sobre la rama del PR #8 es M8, más abajo.)

(«No compila»: TypeScript rechazó mi mutación antes de poder ejecutar el arnés. Es una defensa gratis, pero no una prueba de que la suite lo vería.)

Lectura honesta del resultado: de 11 mutantes, 7 los detecta alguna de las dos suites y 4 sobreviven a las dos (M1, M1b, M4 y M8; con el PR #8, M8 deja de sobrevivir). Y se ve algo interesante: las dos suites son complementarias. Jest atrapa fallos de lógica fina (TOTP, el hash falso, el entorno); el arnés de contrato atrapa lo que se ve desde fuera (que la contraseña no salga en las respuestas). Ninguna de las dos por sí sola vale: Jest se dejó pasar M9; el contrato se dejó pasar M5, M6 y M7.

Los supervivientes merecen un párrafo cada uno:

• M8, el prefijo olvidado. Es el fallo que me dio el 404 en el tutorial de «notas». Si alguien quita api/tasks de la lista del middleware, ninguna prueba falla, y a partir de ahí GET /api/tasks/lo/que/sea sin token devuelve 404 en vez de 401. No hay explotación directa (no se expone ningún dato), pero sí un filtrado de qué rutas existen. La solución eran unas pocas líneas de prueba, y es lo primero que añadí en mi copia (mi prueba de «notas» ya lo hace para su prefijo). El PR #8 incorpora esa prueba, y repetí M8 sobre la rama: quito api/tasks de la lista y ahora fallan 2 pruebas. No repetí los otros diez mutantes.
• M1 y M1b, la rotación no atómica. Aquí está lo más instructivo. El código real usa un updateMany condicional, que es lo correcto. Pero cuando lo sustituí por «leer y luego escribir», ninguna suite lo notó, ni siquiera ampliando la carrera con 25 ms de espera. La razón es SQLite: con una base de datos embebida de un solo escritor, las transacciones interactivas se serializan y el código no atómico parece atómico. Dicho de otro modo: la prueba de concurrencia de esta plantilla no puede distinguir el código correcto del incorrecto en SQLite. Con Turso (varias instancias contra una base de datos remota) la carrera sí existiría. El código está bien; lo que falta es una prueba que lo demuestre en un entorno donde importe.
• M4, el contador del limitador. Sustituí el updateMany atómico por «leer el contador, sumar uno y escribir». Ninguna de las dos suites lo notó, por la misma razón que en M1: con un solo escritor la carrera no se materializa, y los tests de límite hacen peticiones secuenciales. El código real es correcto; lo que falta es una prueba que lo demuestre bajo concurrencia real.

Un último detalle de higiene, y una corrección de mi propio experimento: en una primera pasada del arnés de contrato, M2 y M4 mostraron decenas de fallos con fetch failed. No eran fallos de la plantilla ni detección real: yo mismo había matado con pkill el servidor de otra prueba que corría en paralelo en la misma máquina. Repetí todos los mutantes del arnés de contrato con la máquina en reposo y los números de la tabla son los de esa repetición limpia (M2 pasó de «22 fallos» a 1 y M4 de «detectado» a «sobrevive»). Lo cuento porque un experimento contaminado que no se corrige es peor que no hacerlo.

La integración continua

El workflow «CI & Typecheck» ejecuta: npm audit, comprobación de que las migraciones coinciden con el esquema (migrate diff), typecheck, build, ESLint, construcción de la imagen Docker, escaneo con Trivy (falla con vulnerabilidades altas o críticas con arreglo disponible), un SBOM CycloneDX como artefacto, Jest con cobertura y la matriz de contrato (full/basic/none) más el humo de Bruno. Las acciones están fijadas por SHA y Dependabot revisa npm, Docker y Actions cada semana. El último run de main (758a0ac, el 23 de octubre a las 19:42, hora de Madrid) terminó en verde. La parte de Docker y Trivy sí la ejecuté yo en local (resultados en «Docker y despliegue»; adelanto: en 758a0ac Trivy marcaba un multer alto que habría hecho fallar ese paso, y con el PR #8 sale limpio); el SBOM no lo generé, así que de ese paso me fío del historial de CI. El PR #8 no toca ningún workflow (el token con el que lo subí no tiene permiso workflow), así que la CI no se ha ejecutado con los cambios, sigue sin prettier --check y todo lo anterior lo comprobé en local.

Lo que he atacado (y qué pasó)

Todo lo que sigue lo lancé solo contra mi instancia local (base de datos de laboratorio, puertos de loopback). Es una batería con scripts propios (fetch de Node), no una herramienta de pentesting, y no sustituye una auditoría; pero cubre lo que más suele romperse:

Estos son los números del TRUST_PROXY real (14 logins con emails distintos, TRUST_PROXY=true, TRUST_PROXY_HOPS=1), que es donde más suelen equivocarse las plantillas:

Es el mismo problema de la IP real que anoté en la plantilla de Hono; aquí TRUST_PROXY_HOPS es un número y solo se lee X-Forwarded-For desde la derecha. La parte de «mi red tiene que estar cerrada» sigue siendo responsabilidad tuya.

Segunda tanda: asignación masiva, tipos, tokens falsos y rutas

Con la primera tanda cubrí fuerza bruta, inyección, JWT y cabeceras. En la segunda fui a por lo que un revisor de seguridad probaría después. Todo contra mi instancia local (nada fuera de mi máquina), con respuestas reales:

Lo que más me gusta de esta tabla es la fila del token «firmado con la clave real»: aunque un atacante consiguiera el secreto JWT y fabricara un token con role=admin, no obtendría privilegios, porque la plantilla ignora el rol del token y lo lee de la base de datos en cada petición. Ese es el coste de dos consultas por petición que mencioné antes, y aquí se ve lo que compra.

Endurecimiento de seguridad: lo que hay y lo que falta

Resumen de lo que hay, todo comprobado salvo lo marcado:

• Cabeceras (helmet + propias), verificadas en una respuesta: Content-Security-Policy, Strict-Transport-Security: max-age=31536000; includeSubDomains, Referrer-Policy: no-referrer, Cache-Control: no-store, X-Content-Type-Options: nosniff, Cross-Origin-Opener-Policy y Cross-Origin-Resource-Policy: same-origin, X-Frame-Options: SAMEORIGIN, más X-Request-Id y Server-Timing.
• Fail closed en configuración, migraciones y formatos de hash desconocidos (visto arriba).
• Secretos: JWT distintos, de 32+ caracteres en producción; clave de MFA dedicada y rotable.
• Datos personales en logs de seguridad: el email se seudonimiza; las contraseñas y TOTP nunca salen en consultas (omit).
• CORS por lista en producción; en desarrollo es *, y lo verifiqué (Access-Control-Allow-Origin: *); en producción solo respondió al origen configurado.
• Documentación apagada en producción (/docs y /openapi.json → 404).
• Contenedor (probado, ver «Docker y despliegue»): usuario node, sistema de ficheros de solo lectura, cap_drop: ALL, no-new-privileges, 512 MB y 1 CPU, puerto publicado solo en 127.0.0.1.
• Cadena de suministro en CI: base fijada por digest, acciones fijadas por SHA, npm audit (0 avisos en la rama del PR #8), Trivy (lo ejecuté en local; 0 altos o críticos con arreglo) y SBOM (sin probar localmente).
• Copias de seguridad cifradas: el ensayo ops-rehearsal.sh backup-restore hace un VACUUM INTO, cifra el resultado con age (ChaCha20-Poly1305), comprueba que un fichero manipulado se rechaza, restaura y verifica que el login y el grupo system del contrato funcionan sobre lo restaurado. Lo ejecuté tras instalar age 1.2.1 y pasó entero.

Esto es lo que devuelve GET /healthz en una instancia local (recortado):

HTTP/1.1 200 OK
X-Request-Id: 548dad19-62a2-4dec-b324-9f1c925eb14e
Content-Security-Policy: default-src 'self';base-uri 'self';…;script-src 'self';…;upgrade-insecure-requests
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin
Referrer-Policy: no-referrer
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
Cache-Control: no-store
Access-Control-Allow-Origin: *        # modo desarrollo
Server-Timing: total;dur=1.5

{"status":"healthy","timestamp":"…","uptimeSeconds":1,"database":{"status":"connected","latencyMs":0}}

Y lo que no hace (o hace con matices) está en «Lo que queda por pulir» más abajo.

Docker y despliegue

El Dockerfile

Dos etapas sobre node:24-alpine fijada por digest (en main era node:25-alpine, una línea sin LTS; el PR #8 vuelve a 24, que coincide con engines, con la CI y con AGENTS.md): la primera instala dependencias, genera el cliente de Prisma y compila; la segunda instala solo producción (npm ci --omit=dev --ignore-scripts, reconstruyendo únicamente los paquetes de Prisma que necesitan descargar su motor, y borrando typescript, que entra como peer opcional de Prisma), borra de la imagen final npm, npx, corepack y yarn (menos superficie, y se van las dependencias que npm vendoriza consigo mismo, con CVEs propios; en main solo se borraban npm y npx), copia dist y el cliente generado, y corre como usuario node. Como ya no hay npx en la imagen, el docker-entrypoint.sh ejecuta la CLI de Prisma directamente con node node_modules/prisma/build/index.js, y valida el entorno con el propio loadEnv() de la aplicación antes de migrar:

ENV DATABASE_URL=file:/app/data/prod.db
…
RUN npm ci --omit=dev --ignore-scripts \
  && npm rebuild @prisma/engines prisma \
  && rm -rf node_modules/typescript node_modules/@typescript \
  && npm cache clean --force
…
RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack /opt/yarn-* \
  && rm -f /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack /usr/local/bin/yarn /usr/local/bin/yarnpkg
USER node
…
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
  CMD wget -qO- "http://127.0.0.1:${PORT}/healthz" >/dev/null || exit 1
ENTRYPOINT ["./docker-entrypoint.sh"]
CMD ["node", "dist/main.js"]

# docker-entrypoint.sh (fragmento): primero validar, después migrar
node -e 'require("./dist/config/env.js").loadEnv()'
PRISMA="node node_modules/prisma/build/index.js"
$PRISMA migrate deploy

docker-compose.yml

ports:
  - "127.0.0.1:3011:3011"      # nunca en todas las interfaces
read_only: true
tmpfs: [ /tmp ]
security_opt: [ "no-new-privileges:true" ]
cap_drop: [ ALL ]
mem_limit: 512m
cpus: "1.0"
volumes:
  - sqlite_data:/app/data      # el fichero SQLite vive aquí

Los secretos se leen del entorno con ${JWT_SECRET:?…}: si faltan, docker compose ni arranca.

Lo que pasó cuando la construí y la ejecuté de verdad

Instalé Docker 26.1.5 en mi máquina de pruebas (con dockerd lanzado a mano, sin systemd), docker-compose 2.26.1 y Trivy 0.76.1, y lo repetí todo con el commit 758a0ac (24 de octubre) y otra vez, tras las correcciones, con la rama del PR #8 (25 de octubre). Estas son las medidas de la rama del PR, con lo que medí en 758a0ac entre paréntesis:

En 758a0ac lo ejecuté con las mismas opciones del docker-compose.yml (--read-only, --tmpfs /tmp, --cap-drop ALL, no-new-privileges, 512 MB, 1 CPU, volumen en /app/data) y después con el propio docker-compose up -d: el contenedor quedó Up … 127.0.0.1:3011->3011/tcp, y docker inspect confirmó ReadonlyRootfs=true, CapDrop=[ALL], memoria 536.870.912 bytes, 1 CPU y no-new-privileges:true. Sobre la rama del PR repetí la ejecución con esas opciones (docker run) y el scripts/docker-smoke.sh; no volví a levantar el docker-compose, porque el PR no toca el de Nest. Un detalle útil: docker compose lee automáticamente el .env del directorio, así que para comprobar que sin variables no arranca tuve que usar --env-file /dev/null; entonces sí:

error while interpolating services.api.environment.[]: required variable JWT_SECRET is missing a value: Define JWT_SECRET en el entorno o en .env

Mi primer intento de arrancar el contenedor (en 758a0ac) falló por una razón instructiva: las variables no llegaron al contenedor (un despiste mío con sudo) y el log fue este (recortado):

🚀 Aplicando migraciones de base de datos...
SQLite database prod.db created at file:/app/data/prod.db
10 migrations found in prisma/migrations
Applying migration `0_init`
…
Applying migration `20261023090922_email_outbox`
⚡ Iniciando servidor NestJS...
❌ Critical startup failure: Invalid or missing environment configuration:
{
  "JWT_SECRET": [ "JWT_SECRET is required unless AUTH_MODE=none (…)", "JWT_SECRET must contain at least 32 characters in production (…)" ],
  "MFA_ENCRYPTION_KEY": [ "MFA_ENCRYPTION_KEY (>= 32 chars) is required in production with AUTH_MODE=full so TOTP secrets are encrypted with a dedicated, stable key (…)" ]
}

Dos lecturas: el fallo es claro y a prueba de errores (dice qué variable falta y cómo generarla), pero fíjate en el orden: en main las migraciones se aplican antes de validar el entorno, porque el script de entrada migra y solo después arranca Node. Con un despliegue mal configurado la base de datos ya se ha modificado cuando la aplicación se niega a arrancar. Lo comprobé después con un volumen vacío y sin secretos: el contenedor salía con código 1 y dejaba un prod.db de 192 KB con las migraciones aplicadas.

El PR #8 invierte el orden. El entrypoint ejecuta primero el loadEnv() de la aplicación. Repetí la prueba con un volumen vacío y sin secretos: el contenedor sale con código 1 y el mismo mensaje, pero ya no hay migraciones ni prod.db: el volumen sigue vacío.

❌ Critical startup failure: Invalid or missing environment configuration:
{
  "JWT_SECRET": [ "JWT_SECRET is required unless AUTH_MODE=none (…)", "JWT_SECRET must contain at least 32 characters in production (…)" ],
  "JWT_REFRESH_SECRET": [ … ],
  "MFA_ENCRYPTION_KEY": [ … ]
}

Dos cosas más que solo se ven al ejecutarla en contenedor:

• Los logs ya no salen con colores ANSI en producción (corregido en el PR #8). En 758a0ac, dentro del contenedor ConsoleLogger pintaba con códigos de escape si no se le decía lo contrario: sin NO_COLOR, 62 líneas del arranque contenían secuencias ESC; con -e NO_COLOR=1, 0. En la imagen del PR, sin ninguna variable, conté 0 líneas con ESC de 110 (docker logs). Si usas main, pon NO_COLOR=1 en tu entorno; los logs siguen siendo texto, no JSON.
• El consumo en contenedor se mide de dos maneras. En 758a0ac, con la aplicación en reposo, docker stats marcaba 79,4 MiB y VmRSS dentro del contenedor 148.020 kB (≈144,6 MiB). Con la imagen del PR (Node 24.22.1) medí 93,8 MiB y 160.880 kB (≈157 MiB), unos segundos después de arrancar y de hacer un login; no sé cuánto de la subida es de la versión de Node y cuánto de cuándo se mide, y no repetí la medida con el mismo protocolo. No son medidas contradictorias: docker stats descuenta la caché de ficheros del cgroup y VmRSS cuenta las páginas residentes, incluidas las que vienen del binario de Node mapeado (esta explicación es mía, no la he verificado con el cgroup). Para comparar con otra plantilla, usa siempre la misma medida.

Quedan sin probar la generación real del SBOM y el despliegue en Coolify (más abajo).

Desplegar en Coolify

Los pasos serían los mismos que con la plantilla de Hono (te los conté en el artículo de Coolify): crear la aplicación desde el repositorio con el build pack de Dockerfile, puerto 3011, un volumen persistente en /app/data (sin él pierdes la base de datos en cada despliegue), y estas variables:

NODE_ENV=production
AUTH_MODE=full
JWT_SECRET=…                 # openssl rand -base64 48
JWT_REFRESH_SECRET=…         # otro distinto
MFA_ENCRYPTION_KEY=…         # otro más, y no lo pierdas
CORS_ORIGINS=https://app.tudominio.com
[email protected]
ADMIN_PASSWORD=…             # solo se usa si la BD está vacía
TRUST_PROXY=true
TRUST_PROXY_HOPS=1           # Traefik; 2 si hay Cloudflare delante de Traefik
MAIL_TRANSPORT=smtp
SMTP_URL=smtps://usuario:[email protected]:465
APP_URL=https://api.tudominio.com

Si publicas detrás de Cloudflare, te interesarán Cloudflare Tunnel a fondo (así no abres ningún puerto) y WAF y DDoS a fondo como segunda línea delante de los límites de la propia API.

Lista de comprobación antes de salir a producción

Esta es la lista que yo seguiría con la plantilla, ordenada por «lo que más duele si se olvida». En la última columna te digo cómo lo sé: probado (lo ejecuté), código (lo deduzco leyendo los ficheros) o sin probar.

Hay una más que no cabe en una tabla: lee AGENTS.md (unas 500 líneas). Es la mejor documentación del repositorio, mejor que el README, y recoge el porqué de cada decisión de seguridad.

Rendimiento y consumo

Medí las dos plantillas el 25 de octubre en la misma máquina, compiladas (dist/), con LOG_LEVEL=error, bases SQLite nuevas y autocannon (20 conexiones, 8 s), tres rondas alternadas cada una, sobre las ramas de los dos PR (Nest 623e447, Hono fc44204) y con Node 24.21.0. Es una referencia orientativa: la máquina es compartida y esto no es un banco de pruebas serio. La primera ronda de NestJS salió más lenta en el login (55 ms de mediana en caliente, frente a 28 y 33 en las otras dos) y no sé por qué, así que doy las tres.

(En 758a0ac y 644a5d2, el 24 de octubre y con dos rondas, salió algo parecido: arranque 826 / 700 ms frente a 657 / 670 ms, RSS en reposo 186 / 189 frente a 153 / 150 MiB y /api/tasks a 904 / 878 frente a 758 / 712 req/s.)

La lectura honesta: no hay diferencias que cambien una decisión. NestJS consume unos 34 MiB más en reposo y arranca unos 240 ms más tarde; en rendimiento bruto de rutas va por delante en esta prueba (unas 900 frente a unas 750 req/s en /api/tasks). La diferencia grande en login, de unas 10 veces, es el algoritmo de hash, no el framework (bcryptjs a 12 rondas frente a Argon2id a los mínimos de OWASP), así que no es una comparación de frameworks.

Hono o NestJS: cuándo elegir cuál

Son dos plantillas con el mismo contrato HTTP y distinta filosofía. Estos son los datos reales de cada repositorio el 25 de octubre, en la rama de su PR de correcciones (Hono en fc44204, PR #23; NestJS en 623e447, PR #8). Los dos están ya fusionados en main (el 25 de octubre: Hono a las 12:54, NestJS a las 12:55, hora de Madrid; el árbol de Git de main es idéntico al de cada rama). Antes de la fusión, main estaba en 644a5d2 (Hono, 7 de octubre) y 758a0ac (NestJS, 23 de octubre):

(Un aviso: en el artículo de Hono conté 60 pruebas y Node 20/22; el repositorio ha seguido creciendo desde entonces: main tiene 144 pruebas y la rama de su PR #23, 148. Los números de la tabla son los del repositorio, no los del artículo.)

Elige Hono si quieres lo más pequeño y fácil de leer, un cliente tipado de extremo a extremo para tu frontend, logs JSON de serie, o si te interesa poder mover el código a otros entornos de ejecución (Workers, Bun…). Te lo conté con detalle en Hono a fondo.

Elige NestJS si tu equipo ya trabaja con Nest o va a crecer (módulos, inyección de dependencias, convenciones que todo el mundo reconoce), si prefieres que cada responsabilidad (guard, pipe, interceptor, filtro) tenga un sitio, o si valoras lo operativo que trae esta plantilla (cola de correo, rotación de claves, ensayos de copia de seguridad, contenedor endurecido). El precio es más código, más «ceremonia» y un arranque algo más pesado.

Y si dudas entre más opciones, Express a fondo, Fastify a fondo y la comparativa de los cuatro te dan el contexto de por qué existen las dos plantillas.

Problemas reales y cómo los resolví

Esta es la sección que más me habría gustado encontrar antes de empezar. Son los tropiezos que tuve de verdad al trabajar con la plantilla, con el síntoma exacto (para que lo encuentres si te pasa) y la solución que funcionó.

Los números 2, 7, 8 y 10 no son errores de uso, sino de cómo estaba empaquetada la plantilla en main; el PR #8 (ya fusionado) los corrige.

Lo que aprendí probándola

1. Un guard global solo vigila las rutas que existen. Con un guard deny-by-default casi todo queda protegido, pero un sondeo sin token a una subruta inexistente bajo /api/tasks, /api/users… respondería 404 en lugar de 401, y eso filtra la forma de tu API. El AuthPrefixMiddleware lo evita (lo comprobé: GET /api/tasks/x/y/z sin token → 401; una ruta fuera de esos prefijos, /api/noexiste, → 404) y es un buen recordatorio de probar el caso feo, no solo el camino feliz (y de que ese caso tenga su prueba: el PR #8 añade la que faltaba).
2. Compartir la instancia importa. useExisting en lugar de useClass para el guard global permite que el middleware y el guard usen exactamente el mismo objeto y el token se verifique una vez.
3. Las operaciones atómicas ganan a leer y luego escribir. La rotación de refresh tokens con updateMany condicionado es lo que hace que «de tres refresh a la vez, gana uno» sea cierto, y tiene su propia suite para demostrarlo.
4. Comprobar el bloqueo antes de la contraseña (y compararla contra un hash falso cuando la cuenta no existe) evita que el login revele cuentas.
5. Que algo sea rápido no lo hace más seguro, y que algo sea lento tampoco: la diferencia de unas 10 veces en el login con Hono es el algoritmo, no el framework.
6. La protección contra repetición tiene sus costes de UX: el TOTP que usas para activar el 2FA no vale para el siguiente login en el mismo intervalo de 30 s.
7. Mis propios errores de prueba me enseñaron cosas. Mis tests fallaban solo porque tenía una variable de entorno exportada, y mi prueba de «arranque sin secretos» arrancó igualmente porque dotenv cargó el .env del repositorio (hay que lanzarla desde otro directorio). Las dos cosas ya están anotadas para que no te pasen (y la primera, corregida en el PR #8).
8. Un harness de contrato entre dos implementaciones es una gran idea: es lo que permite mantener dos plantillas con el mismo comportamiento sin que se separen en silencio.

Lo que queda por pulir

Quiero ser tan honesto aquí como en el artículo de Hono. En la primera pasada (24 de octubre, 758a0ac) no encontré ningún fallo crítico en mis pruebas de seguridad, pero sí catorce cosas que arreglaría. El 25 de octubre corregí en el PR #8 las que se podían arreglar sin tocar la lógica de autenticación; el PR ya está fusionado, y la columna «Estado» distingue lo que está corregido en el PR #8 (y por tanto ya en main; era lo que estaba roto en 758a0ac) de lo que sigue igual. Severidad según mi criterio:

Otras cosas que quedan fuera del PR y que conviene tener presentes: los cambios de CI (formato, npm audit también de desarrollo) los he dejado sin hacer por el permiso del token; npm 11 solo avisa de los scripts de instalación de las dependencias (@prisma/engines) y una versión futura de npm podría exigir declararlos; y @scarf/scarf, una dependencia transitiva del paquete de Scalar, tiene un script de instalación que envía estadísticas de uso: no se ejecuta en la imagen (--ignore-scripts), pero sí en un npm install de desarrollo.

Sin probar (lo repito para que no haya malentendidos): la generación real del SBOM y la propia ejecución de la CI de GitHub (tampoco con los cambios del PR #8); el envío real de correo por SMTP; Turso; el despliegue en Coolify; y varias instancias a la vez contra la misma base (el rate limit en BD está pensado para eso, pero no lo he medido).

Conclusión

Después de instalarla, compilarla, construirla en Docker, pasarle sus pruebas (62 en main, 84 en la rama del PR #8), 95 escenarios de contrato, 29 peticiones de Bruno, dos baterías de ataques, un experimento de mutaciones y los ensayos de operación (rotación de la clave de MFA y copia de seguridad cifrada), y de añadirle un recurso nuevo con su prueba (69 con las mías, sobre 758a0ac), mi opinión es clara: es una plantilla seria. Las decisiones difíciles (sesiones con estado, rotación con detección de robo, bloqueo antes de la contraseña, fail closed en configuración, IP real detrás de un proxy, copias cifradas) están bien tomadas y demostradas con pruebas, no solo escritas en un README. Y donde no lo están, la propia suite y los ensayos me han dicho dónde mirar.

Lo que más me gusta: el modo AUTH_MODE que desmonta de verdad lo que no usas, la rotación de refresh con su suite de concurrencia, el contenedor endurecido que arranca y se para limpio (sale con código 0 al recibir SIGTERM), y que la propia plantilla te enseñe cómo se rompe (mensajes claros al arrancar, ensayos operativos). Lo que más le faltaba lo he corregido en el PR #8, a la espera de que se fusione: la auditoría de multer (de 4 avisos altos a 0, y Trivy a 0), las dependencias sobrantes, la versión de Node (imagen, CI y engines alineadas en 24), el orden «validar y después migrar», los colores en los logs, el aislamiento de las pruebas y la prueba del middleware que el experimento de mutaciones echó en falta. Lo que queda son sobre todo decisiones de diseño que he preferido dejarte a ti (el bloqueo de cuenta como palanca de denegación de servicio, la enumeración de usuarios en el registro y la cobertura del rate limit), los logs JSON, una prueba de concurrencia que distinga el código atómico en SQLite y los cambios de CI.

Frente a la de Hono, Nest gana en operaciones y seguridad «de fábrica» y pierde en tamaño, en pruebas unitarias y en el cliente tipado. Si no tienes preferencia de framework, empieza por la de Hono por su simplicidad; si tu equipo ya vive en Nest, esta es una base muy buena.

Enlaces

• Repositorio: Collanteslu/nestjs-prisma-production-starter
• Correcciones de este artículo: PR #8 (Nest, fusionado el 25 de octubre) y PR #23 (Hono, fusionado el 25 de octubre)
• La gemela en Hono: Mi plantilla Hono + Prisma 7 y Hono a fondo
• El framework: NestJS 12 a fondo
• El contexto: Express a fondo, Fastify a fondo y la comparativa de los cuatro
• Despliegue: Coolify, tu PaaS autoalojado, Cloudflare Tunnel a fondo y WAF y DDoS a fondo