Sécurité et migration vers la 0.19
nestjs-docfy 0.19 verrouille toute la surface par défaut. Cette page liste chaque valeur par défaut, l'option qui l'assouplit et ce qu'il faut changer lors de la mise à jour.
Sûr par défaut
Tout ce qui affaiblit une valeur par défaut porte un nom d'option explicite, donc visible en revue de code :
- Les outils de build (
ts-morph,commander,picocolors,openapi-typescript) ne sont plus installés en production : ce sont des peers optionnels, installés en dépendances de développement. - Avec
NODE_ENV=production, le proxy de "Try it out" est désactivé sauf si vous définissezproxyAuthorize(ouallowProxyInProduction). - Le proxy n'accepte que
Content-Type: application/json, ne relaie jamaisHostniSet-Cookieet n'atteint que les servers du spec. - L'UI de la doc est servie avec une Content-Security-Policy stricte (
script-src 'self'),nosniffet un framing limité à la même origine. Désactivez-les avecsecurityHeaders: false. - Les tests de contrat n'envoient que
GET,HEADetOPTIONS, sauf si vous passez--allow-writes. - Le workflow réutilisable de vérification de PR exige
docfy-versionetdocfy-ref, il n'exécute donc jamais de code non épinglé.
Les guards Nest et les routes de la doc
DocfyUiModule.setup() enregistre ses routes directement sur l'adaptateur HTTP, donc les guards Nest ne s'y exécutent jamais. Protégez la doc avec un middleware enregistré avant setup(), et le proxy avec proxyAuthorize :
// 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,
});Migrer vers la 0.19
Passez en revue chaque point qui s'applique à votre projet :
- Utilisez Node.js 22.12 ou plus récent. Node 18 et 20 ne reçoivent plus de correctifs de sécurité.
- Si vous utilisez le CLI ou le plugin du compilateur, lancez
npm install --save-dev ts-morph commander picocolors(plusopenapi-typescriptpour generate-client). - Si vous utilisez "Try it out" en production, ajoutez
proxyAuthorize. N'utilisezallowProxyInProduction: trueque si autre chose protège déjà le mount path. - Si vous appelez le proxy depuis votre propre client, envoyez
Content-Type: application/json; tout le reste reçoit415. - Si "Try it out" appelle d'autres origines directement ou si la doc charge des ressources distantes, ajoutez-les avec
cspConnectSrcou remplacez la politique aveccontentSecurityPolicy. - Les tests de contrat qui ont besoin des endpoints d'écriture prennent
--allow-writes; une base URL qui n'est pas localhost et hors des servers du spec nécessite--no-restrict-to-servers. - Les utilisateurs du workflow réutilisable de PR doivent passer
docfy-versionetdocfy-ref. - Les globs de controllers personnalisés correspondent désormais exactement :
*.ctrl.tsne correspond plus àusers.ctrl.tsx.
Comment vous êtes averti
- Au démarrage : un avertissement dans les logs pour chaque configuration risquée, et une erreur quand le proxy est désactivé en production.
- Dans l'UI de la doc : un bandeau listant les problèmes, affiché uniquement hors production.
- Dans
nestjs-docfy doctor: des constats[security]issus d'une analyse statique de vos appels à setup(). - Dans les réponses du proxy : l'en-tête
X-Docfy-Proxy-Errorindique pourquoi la requête a été rejetée.
Signaler une vulnérabilité
Vous avez trouvé un problème de sécurité ? Utilisez le formulaire privé Report a vulnerability de GitHub, pas une issue publique. Une valeur par défaut qui laisse entrer un attaquant compte comme une vulnérabilité.