nestjs-docfy 0.19 ist ein Sicherheitsrelease mit Breaking Changes. Zum Migrationsleitfaden →

Sicherheit & Migration auf 0.19

nestjs-docfy 0.19 sperrt standardmäßig jede Angriffsfläche ab. Diese Seite listet jeden Standard, die Option, die ihn lockert, und was du beim Upgrade ändern musst.

0.19 enthält Breaking Changes
Sie sorgen dafür, dass die Bibliothek kein Einfallstor in deine App wird. Die meisten Projekte brauchen nur ein oder zwei der Schritte unten.

Standardmäßig sicher

Alles, was einen Standard schwächt, hat einen expliziten Optionsnamen und fällt so im Code-Review auf:

  • Build-Werkzeuge (ts-morph, commander, picocolors, openapi-typescript) werden nicht mehr in Produktion installiert: Sie sind optionale Peers und werden als Dev-Dependencies installiert.
  • Mit NODE_ENV=production ist der "Try it out"-Proxy deaktiviert, außer du setzt proxyAuthorize (oder allowProxyInProduction).
  • Der Proxy akzeptiert nur Content-Type: application/json, leitet nie Host oder Set-Cookie weiter und erreicht nur die Server aus der Spec.
  • Die Docs-UI wird mit einer strikten Content-Security-Policy (script-src 'self'), nosniff und Framing nur vom selben Origin ausgeliefert. Abschalten mit securityHeaders: false.
  • Contract-Tests senden nur GET, HEAD und OPTIONS, außer du übergibst --allow-writes.
  • Der wiederverwendbare PR-Check-Workflow verlangt docfy-version und docfy-ref und führt so nie unfixierten Code aus.

Nest-Guards und die Docs-Routen

DocfyUiModule.setup() registriert seine Routen direkt am HTTP-Adapter, daher laufen Nest-Guards dort nie. Schütze die Docs mit einer Middleware, die vor setup() registriert wird, und den Proxy mit 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,
});

Migration auf 0.19

Geh jeden Punkt durch, der auf dein Projekt zutrifft:

  1. Nutze Node.js 22.12 oder neuer. Node 18 und 20 erhalten keine Sicherheitsupdates mehr.
  2. Wenn du das CLI oder das Compiler-Plugin nutzt, führe npm install --save-dev ts-morph commander picocolors aus (plus openapi-typescript für generate-client).
  3. Wenn du "Try it out" in Produktion nutzt, ergänze proxyAuthorize. Nutze allowProxyInProduction: true nur, wenn etwas anderes den Mount-Pfad bereits schützt.
  4. Wenn du den Proxy aus einem eigenen Client aufrufst, sende Content-Type: application/json; alles andere bekommt 415.
  5. Wenn "Try it out" andere Origins direkt aufruft oder die Docs externe Ressourcen laden, ergänze sie mit cspConnectSrc oder ersetze die Policy mit contentSecurityPolicy.
  6. Contract-Tests, die schreibende Endpunkte brauchen, nehmen --allow-writes; eine Base-URL, die nicht localhost ist und außerhalb der Server der Spec liegt, braucht --no-restrict-to-servers.
  7. Aufrufer des wiederverwendbaren PR-Check-Workflows müssen docfy-version und docfy-ref übergeben.
  8. Eigene Controller-Globs passen jetzt exakt: *.ctrl.ts passt nicht mehr auf users.ctrl.tsx.

Wie du gewarnt wirst

  • Beim Start: eine Warnung im Log für jede riskante Konfiguration und ein Fehler, wenn der Proxy in Produktion deaktiviert wird.
  • In der Docs-UI: ein Banner mit den Problemen, nur außerhalb der Produktion.
  • In nestjs-docfy doctor: [security]-Befunde aus einer statischen Analyse deiner setup()-Aufrufe.
  • In Proxy-Antworten: Der Header X-Docfy-Proxy-Error nennt den Grund für die Ablehnung.

Eine Sicherheitslücke melden

Ein Sicherheitsproblem gefunden? Nutze das private GitHub-Formular Report a vulnerability, kein öffentliches Issue. Ein Standard, der einen Angreifer hineinlässt, zählt als Sicherheitslücke.