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=productionstaat de "Try it out"-proxy uit, tenzij jeproxyAuthorize(ofallowProxyInProduction) instelt. - De proxy accepteert alleen
Content-Type: application/json, stuurt nooitHostofSet-Cookiedoor en bereikt alleen de servers uit de spec. - De docs-UI wordt geleverd met een strikte Content-Security-Policy (
script-src 'self'),nosniffen framing alleen vanaf dezelfde origin. Uitzetten metsecurityHeaders: false. - Contracttests sturen alleen
GET,HEADenOPTIONS, tenzij je--allow-writesmeegeeft. - De herbruikbare PR-check-workflow vereist
docfy-versionendocfy-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:
- Gebruik Node.js 22.12 of nieuwer. Node 18 en 20 krijgen geen beveiligingsupdates meer.
- Gebruik je de CLI of de compiler-plugin, voer dan
npm install --save-dev ts-morph commander picocolorsuit (plusopenapi-typescriptvoor generate-client). - Gebruik je "Try it out" in productie, voeg dan
proxyAuthorizetoe. GebruikallowProxyInProduction: truealleen als iets anders het mount-pad al beschermt. - Roep je de proxy aan vanuit een eigen client, stuur dan
Content-Type: application/jsonmee; al het andere krijgt415. - Roept "Try it out" andere origins rechtstreeks aan of laden de docs externe bronnen, voeg ze dan toe met
cspConnectSrcof vervang de policy metcontentSecurityPolicy. - 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-serversnodig. - Wie de herbruikbare PR-check-workflow gebruikt, moet
docfy-versionendocfy-refmeegeven. - Eigen controller-globs matchen nu exact:
*.ctrl.tsmatcht niet meer metusers.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-Errorvertelt 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.