nestjs-docfy 0.19 is a security release with breaking changes. Read the migration guide →

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=production the "Try it out" proxy is disabled unless you set proxyAuthorize (or allowProxyInProduction).
  • The proxy only accepts Content-Type: application/json, never relays Host or Set-Cookie, and only reaches the spec's servers.
  • The docs UI is served with a strict Content-Security-Policy (script-src 'self'), nosniff and same-origin framing. Opt out with securityHeaders: false.
  • Contract tests fire only GET, HEAD and OPTIONS unless you pass --allow-writes.
  • The reusable PR-check workflow requires docfy-version and docfy-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:

  1. Use Node.js 22.12 or newer. Node 18 and 20 no longer get security patches.
  2. If you use the CLI or the compiler plugin, run npm install --save-dev ts-morph commander picocolors (plus openapi-typescript for generate-client).
  3. If you use "Try it out" in production, add proxyAuthorize. Use allowProxyInProduction: true only when something else already protects the mount path.
  4. If you call the proxy from your own client, send Content-Type: application/json; anything else gets 415.
  5. If "Try it out" calls other origins directly or the docs load remote resources, add them with cspConnectSrc or replace the policy with contentSecurityPolicy.
  6. Contract tests that need write endpoints take --allow-writes; a non-localhost base URL outside the spec's servers needs --no-restrict-to-servers.
  7. Callers of the reusable PR-check workflow must pass docfy-version and docfy-ref.
  8. Custom controller globs now match exactly: *.ctrl.ts no longer matches users.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-Error header 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.