Security & migrating to 0.19
nestjs-docfy 0.19 locks every surface down by default. This page lists each default, the option that loosens it, and what to change when you upgrade.
0.19 contains breaking changes
They exist so the library can't become an entry point into your app. Most projects need one or two of the steps below.
Secure by default
Anything that weakens a default has an explicit option name, so it shows up in code review:
- Build tooling (
ts-morph,commander,picocolors,openapi-typescript) is no longer installed into production: it's an optional peer, installed as a dev dependency. - With
NODE_ENV=productionthe "Try it out" proxy is disabled unless you setproxyAuthorize(orallowProxyInProduction). - The proxy only accepts
Content-Type: application/json, never relaysHostorSet-Cookie, and only reaches the spec's servers. - The docs UI is served with a strict Content-Security-Policy (
script-src 'self'),nosniffand same-origin framing. Opt out withsecurityHeaders: false. - Contract tests fire only
GET,HEADandOPTIONSunless you pass--allow-writes. - The reusable PR-check workflow requires
docfy-versionanddocfy-ref, so it never runs unpinned code.
Nest guards and the docs routes
DocfyUiModule.setup() registers its routes on the raw HTTP adapter, so Nest guards never run for them. Protect the docs with a middleware registered before setup(), and the proxy with 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,
});Migrating to 0.19
Go through each item that applies to your project:
- Use Node.js 22.12 or newer. Node 18 and 20 no longer get security patches.
- If you use the CLI or the compiler plugin, run
npm install --save-dev ts-morph commander picocolors(plusopenapi-typescriptfor generate-client). - If you use "Try it out" in production, add
proxyAuthorize. UseallowProxyInProduction: trueonly when something else already protects the mount path. - If you call the proxy from your own client, send
Content-Type: application/json; anything else gets415. - If "Try it out" calls other origins directly or the docs load remote resources, add them with
cspConnectSrcor replace the policy withcontentSecurityPolicy. - Contract tests that need write endpoints take
--allow-writes; a non-localhost base URL outside the spec's servers needs--no-restrict-to-servers. - Callers of the reusable PR-check workflow must pass
docfy-versionanddocfy-ref. - Custom controller globs now match exactly:
*.ctrl.tsno longer matchesusers.ctrl.tsx.
How you'll be warned
- At boot: a warning in your logs for each risky setup, and an error when the proxy is disabled in production.
- In the docs UI: a banner listing the issues, shown only outside production.
- In
nestjs-docfy doctor:[security]findings from a static scan of your setup() calls. - In proxy responses: the
X-Docfy-Proxy-Errorheader says why a request was rejected.
Reporting a vulnerability
Found a security problem? Use GitHub's private Report a vulnerability form, not a public issue. A default that lets an attacker in counts as a vulnerability.