nestjs-docfy 0.19 est une version de sécurité avec des changements incompatibles. Lire le guide de migration →

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.

La 0.19 contient des changements incompatibles
Ils empêchent la bibliothèque de devenir une porte d'entrée vers votre app. La plupart des projets n'ont besoin que d'une ou deux des étapes ci-dessous.

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éfinissez proxyAuthorize (ou allowProxyInProduction).
  • Le proxy n'accepte que Content-Type: application/json, ne relaie jamais Host ni Set-Cookie et n'atteint que les servers du spec.
  • L'UI de la doc est servie avec une Content-Security-Policy stricte (script-src 'self'), nosniff et un framing limité à la même origine. Désactivez-les avec securityHeaders: false.
  • Les tests de contrat n'envoient que GET, HEAD et OPTIONS, sauf si vous passez --allow-writes.
  • Le workflow réutilisable de vérification de PR exige docfy-version et docfy-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 :

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,
});

Migrer vers la 0.19

Passez en revue chaque point qui s'applique à votre projet :

  1. Utilisez Node.js 22.12 ou plus récent. Node 18 et 20 ne reçoivent plus de correctifs de sécurité.
  2. Si vous utilisez le CLI ou le plugin du compilateur, lancez npm install --save-dev ts-morph commander picocolors (plus openapi-typescript pour generate-client).
  3. Si vous utilisez "Try it out" en production, ajoutez proxyAuthorize. N'utilisez allowProxyInProduction: true que si autre chose protège déjà le mount path.
  4. Si vous appelez le proxy depuis votre propre client, envoyez Content-Type: application/json ; tout le reste reçoit 415.
  5. Si "Try it out" appelle d'autres origines directement ou si la doc charge des ressources distantes, ajoutez-les avec cspConnectSrc ou remplacez la politique avec contentSecurityPolicy.
  6. 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.
  7. Les utilisateurs du workflow réutilisable de PR doivent passer docfy-version et docfy-ref.
  8. Les globs de controllers personnalisés correspondent désormais exactement : *.ctrl.ts ne 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-Error indique 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é.