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=productionel proxy de "Try it out" queda desactivado salvo que definasproxyAuthorize(oallowProxyInProduction). - El proxy solo acepta
Content-Type: application/json, nunca reenvíaHostniSet-Cookiey solo llega a los servers del spec. - La UI de la documentación se sirve con una Content-Security-Policy estricta (
script-src 'self'),nosniffy framing solo del mismo origen. Desactívalo consecurityHeaders: false. - Los tests de contrato solo disparan
GET,HEADyOPTIONSsalvo que pases--allow-writes. - El workflow reutilizable de PR exige
docfy-versionydocfy-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:
- Usa Node.js 22.12 o superior. Node 18 y 20 ya no reciben parches de seguridad.
- Si usas el CLI o el plugin del compilador, ejecuta
npm install --save-dev ts-morph commander picocolors(másopenapi-typescriptpara generate-client). - Si usas "Try it out" en producción, añade
proxyAuthorize. UsaallowProxyInProduction: truesolo cuando otra cosa ya protege el mount path. - Si llamas al proxy desde tu propio cliente, envía
Content-Type: application/json; cualquier otro recibe415. - Si "Try it out" llama a otros orígenes directamente o la documentación carga recursos remotos, añádelos con
cspConnectSrco reemplaza la política concontentSecurityPolicy. - 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. - Quien usa el workflow reutilizable de PR debe pasar
docfy-versionydocfy-ref. - Los globs personalizados de controllers ahora coinciden exactamente:
*.ctrl.tsya no coincide conusers.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-Errorindica 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.