nestjs-docfy 0.19 es una versión de seguridad con cambios incompatibles. Lee la guía de migración →

Seguridad y migración a la 0.19

nestjs-docfy 0.19 bloquea toda la superficie por defecto. Esta página lista cada valor por defecto, la opción que lo relaja y qué cambiar al actualizar.

La 0.19 tiene cambios incompatibles
Existen para que la librería no se convierta en una puerta de entrada a tu app. La mayoría de los proyectos necesita uno o dos de los pasos de abajo.

Seguro por defecto

Todo lo que debilita un valor por defecto tiene un nombre de opción explícito, así aparece en el code review:

  • Las herramientas de build (ts-morph, commander, picocolors, openapi-typescript) ya no se instalan en producción: son peers opcionales, instalados como dependencias de desarrollo.
  • Con NODE_ENV=production el proxy de "Try it out" queda desactivado salvo que definas proxyAuthorize (o allowProxyInProduction).
  • El proxy solo acepta Content-Type: application/json, nunca reenvía Host ni Set-Cookie y solo llega a los servers del spec.
  • La UI de la documentación se sirve con una Content-Security-Policy estricta (script-src 'self'), nosniff y framing solo del mismo origen. Desactívalo con securityHeaders: false.
  • Los tests de contrato solo disparan GET, HEAD y OPTIONS salvo que pases --allow-writes.
  • El workflow reutilizable de PR exige docfy-version y docfy-ref, así nunca ejecuta código sin versión fijada.

Guards de Nest y las rutas de la documentación

DocfyUiModule.setup() registra sus rutas directamente en el adaptador HTTP, así que los guards de Nest nunca se ejecutan en ellas. Protege la documentación con un middleware registrado antes de setup(), y el proxy con proxyAuthorize:

ts
// Registered before setup(): only allowed callers reach the docs UI
app.use('/docs', (req, res, next) => (isAllowedToSeeDocs(req) ? next() : res.status(404).end()));

DocfyUiModule.setup('/docs', app, {
  openApiDocument: document,
  // Runs for every "Try it out" proxy request; docfy-ui calls it same-origin, so cookies are sent
  proxyAuthorize: async (req) => (await currentUser(req))?.roles.includes('developer') ?? false,
});

Migrar a la 0.19

Revisa cada punto que aplique a tu proyecto:

  1. Usa Node.js 22.12 o superior. Node 18 y 20 ya no reciben parches de seguridad.
  2. Si usas el CLI o el plugin del compilador, ejecuta npm install --save-dev ts-morph commander picocolors (más openapi-typescript para generate-client).
  3. Si usas "Try it out" en producción, añade proxyAuthorize. Usa allowProxyInProduction: true solo cuando otra cosa ya protege el mount path.
  4. Si llamas al proxy desde tu propio cliente, envía Content-Type: application/json; cualquier otro recibe 415.
  5. Si "Try it out" llama a otros orígenes directamente o la documentación carga recursos remotos, añádelos con cspConnectSrc o reemplaza la política con contentSecurityPolicy.
  6. Los tests de contrato que necesitan endpoints de escritura usan --allow-writes; una base URL que no es localhost y está fuera de los servers del spec necesita --no-restrict-to-servers.
  7. Quien usa el workflow reutilizable de PR debe pasar docfy-version y docfy-ref.
  8. Los globs personalizados de controllers ahora coinciden exactamente: *.ctrl.ts ya no coincide con users.ctrl.tsx.

Cómo se te avisa

  • Al arrancar: un aviso en los logs por cada configuración arriesgada, y un error cuando el proxy queda desactivado en producción.
  • En la UI de la documentación: un banner con los problemas, mostrado solo fuera de producción.
  • En nestjs-docfy doctor: hallazgos [security] de un análisis estático de tus llamadas a setup().
  • En las respuestas del proxy: el header X-Docfy-Proxy-Error indica por qué se rechazó la petición.

Reportar una vulnerabilidad

¿Encontraste un problema de seguridad? Usa el formulario privado Report a vulnerability de GitHub, no una issue pública. Un valor por defecto que deja entrar a un atacante cuenta como vulnerabilidad.