nestjs-docfy 0.19 is een beveiligingsrelease met breaking changes. Lees de migratiegids →

Beveiliging en migratie naar 0.19

nestjs-docfy 0.19 sluit standaard elk aanvalsoppervlak af. Deze pagina somt elke standaard op, de optie die hem versoepelt en wat je bij de upgrade moet aanpassen.

0.19 bevat breaking changes
Ze zorgen ervoor dat de bibliotheek geen toegangspoort tot je app wordt. De meeste projecten hebben maar één of twee van de stappen hieronder nodig.

Standaard veilig

Alles wat een standaard verzwakt heeft een expliciete optienaam, zodat het opvalt in de code review:

  • Build-tools (ts-morph, commander, picocolors, openapi-typescript) worden niet meer in productie geïnstalleerd: het zijn optionele peers, geïnstalleerd als dev-dependencies.
  • Met NODE_ENV=production staat de "Try it out"-proxy uit, tenzij je proxyAuthorize (of allowProxyInProduction) instelt.
  • De proxy accepteert alleen Content-Type: application/json, stuurt nooit Host of Set-Cookie door en bereikt alleen de servers uit de spec.
  • De docs-UI wordt geleverd met een strikte Content-Security-Policy (script-src 'self'), nosniff en framing alleen vanaf dezelfde origin. Uitzetten met securityHeaders: false.
  • Contracttests sturen alleen GET, HEAD en OPTIONS, tenzij je --allow-writes meegeeft.
  • De herbruikbare PR-check-workflow vereist docfy-version en docfy-ref, dus hij draait nooit code zonder vastgezette versie.

Nest-guards en de docs-routes

DocfyUiModule.setup() registreert zijn routes direct op de HTTP-adapter, dus Nest-guards draaien daar nooit. Bescherm de docs met een middleware die vóór setup() wordt geregistreerd, en de proxy met 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,
});

Migreren naar 0.19

Loop elk punt na dat op je project van toepassing is:

  1. Gebruik Node.js 22.12 of nieuwer. Node 18 en 20 krijgen geen beveiligingsupdates meer.
  2. Gebruik je de CLI of de compiler-plugin, voer dan npm install --save-dev ts-morph commander picocolors uit (plus openapi-typescript voor generate-client).
  3. Gebruik je "Try it out" in productie, voeg dan proxyAuthorize toe. Gebruik allowProxyInProduction: true alleen als iets anders het mount-pad al beschermt.
  4. Roep je de proxy aan vanuit een eigen client, stuur dan Content-Type: application/json mee; al het andere krijgt 415.
  5. Roept "Try it out" andere origins rechtstreeks aan of laden de docs externe bronnen, voeg ze dan toe met cspConnectSrc of vervang de policy met contentSecurityPolicy.
  6. Contracttests die schrijvende endpoints nodig hebben gebruiken --allow-writes; een base-URL die geen localhost is en buiten de servers van de spec valt, heeft --no-restrict-to-servers nodig.
  7. Wie de herbruikbare PR-check-workflow gebruikt, moet docfy-version en docfy-ref meegeven.
  8. Eigen controller-globs matchen nu exact: *.ctrl.ts matcht niet meer met users.ctrl.tsx.

Hoe je gewaarschuwd wordt

  • Bij het opstarten: een waarschuwing in je logs voor elke riskante configuratie, en een fout wanneer de proxy in productie wordt uitgeschakeld.
  • In de docs-UI: een banner met de problemen, alleen buiten productie.
  • In nestjs-docfy doctor: [security]-bevindingen uit een statische analyse van je setup()-aanroepen.
  • In proxy-responses: de header X-Docfy-Proxy-Error vertelt waarom een verzoek is geweigerd.

Een kwetsbaarheid melden

Een beveiligingsprobleem gevonden? Gebruik het privéformulier Report a vulnerability van GitHub, geen openbare issue. Een standaard die een aanvaller binnenlaat telt als kwetsbaarheid.