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=productionist der "Try it out"-Proxy deaktiviert, außer du setztproxyAuthorize(oderallowProxyInProduction). - Der Proxy akzeptiert nur
Content-Type: application/json, leitet nieHostoderSet-Cookieweiter und erreicht nur die Server aus der Spec. - Die Docs-UI wird mit einer strikten Content-Security-Policy (
script-src 'self'),nosniffund Framing nur vom selben Origin ausgeliefert. Abschalten mitsecurityHeaders: false. - Contract-Tests senden nur
GET,HEADundOPTIONS, außer du übergibst--allow-writes. - Der wiederverwendbare PR-Check-Workflow verlangt
docfy-versionunddocfy-refund 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:
- Nutze Node.js 22.12 oder neuer. Node 18 und 20 erhalten keine Sicherheitsupdates mehr.
- Wenn du das CLI oder das Compiler-Plugin nutzt, führe
npm install --save-dev ts-morph commander picocolorsaus (plusopenapi-typescriptfür generate-client). - Wenn du "Try it out" in Produktion nutzt, ergänze
proxyAuthorize. NutzeallowProxyInProduction: truenur, wenn etwas anderes den Mount-Pfad bereits schützt. - Wenn du den Proxy aus einem eigenen Client aufrufst, sende
Content-Type: application/json; alles andere bekommt415. - Wenn "Try it out" andere Origins direkt aufruft oder die Docs externe Ressourcen laden, ergänze sie mit
cspConnectSrcoder ersetze die Policy mitcontentSecurityPolicy. - 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. - Aufrufer des wiederverwendbaren PR-Check-Workflows müssen
docfy-versionunddocfy-refübergeben. - Eigene Controller-Globs passen jetzt exakt:
*.ctrl.tspasst nicht mehr aufusers.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-Errornennt 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.