nestjs-docfy 0.19 è una release di sicurezza con breaking change. Leggi la guida alla migrazione →

Sicurezza e migrazione alla 0.19

nestjs-docfy 0.19 blocca ogni superficie per impostazione predefinita. Questa pagina elenca ogni default, l'opzione che lo allenta e cosa cambiare durante l'aggiornamento.

La 0.19 contiene breaking change
Servono a evitare che la libreria diventi una porta d'ingresso nella tua app. La maggior parte dei progetti ha bisogno solo di uno o due dei passaggi qui sotto.

Sicuro per impostazione predefinita

Tutto ciò che indebolisce un default ha un nome di opzione esplicito, così emerge nella code review:

  • Gli strumenti di build (ts-morph, commander, picocolors, openapi-typescript) non vengono più installati in produzione: sono peer opzionali, installati come dipendenze di sviluppo.
  • Con NODE_ENV=production il proxy di "Try it out" è disattivato, a meno che tu non imposti proxyAuthorize (o allowProxyInProduction).
  • Il proxy accetta solo Content-Type: application/json, non inoltra mai Host né Set-Cookie e raggiunge solo i server dello spec.
  • La UI della documentazione è servita con una Content-Security-Policy rigorosa (script-src 'self'), nosniff e framing solo dalla stessa origine. Disattivali con securityHeaders: false.
  • I test di contratto inviano solo GET, HEAD e OPTIONS, a meno che tu non passi --allow-writes.
  • Il workflow riutilizzabile di controllo delle PR richiede docfy-version e docfy-ref, quindi non esegue mai codice senza versione fissata.

Le guard di Nest e le route della documentazione

DocfyUiModule.setup() registra le sue route direttamente sull'adapter HTTP, quindi le guard di Nest non vengono mai eseguite su di esse. Proteggi la documentazione con un middleware registrato prima di setup(), e il proxy con 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,
});

Migrare alla 0.19

Controlla ogni punto che si applica al tuo progetto:

  1. Usa Node.js 22.12 o successivo. Node 18 e 20 non ricevono più patch di sicurezza.
  2. Se usi il CLI o il plugin del compilatore, esegui npm install --save-dev ts-morph commander picocolors (più openapi-typescript per generate-client).
  3. Se usi "Try it out" in produzione, aggiungi proxyAuthorize. Usa allowProxyInProduction: true solo quando qualcos'altro protegge già il mount path.
  4. Se chiami il proxy da un tuo client, invia Content-Type: application/json; qualsiasi altro riceve 415.
  5. Se "Try it out" chiama altre origini direttamente o la documentazione carica risorse remote, aggiungile con cspConnectSrc o sostituisci la policy con contentSecurityPolicy.
  6. I test di contratto che richiedono endpoint di scrittura usano --allow-writes; una base URL che non è localhost e fuori dai server dello spec richiede --no-restrict-to-servers.
  7. Chi usa il workflow riutilizzabile delle PR deve passare docfy-version e docfy-ref.
  8. I glob personalizzati dei controller ora corrispondono esattamente: *.ctrl.ts non corrisponde più a users.ctrl.tsx.

Come vieni avvisato

  • All'avvio: un avviso nei log per ogni configurazione rischiosa, e un errore quando il proxy viene disattivato in produzione.
  • Nella UI della documentazione: un banner con i problemi, mostrato solo fuori dalla produzione.
  • In nestjs-docfy doctor: risultati [security] da un'analisi statica delle tue chiamate a setup().
  • Nelle risposte del proxy: l'header X-Docfy-Proxy-Error spiega perché la richiesta è stata rifiutata.

Segnalare una vulnerabilità

Hai trovato un problema di sicurezza? Usa il modulo privato Report a vulnerability di GitHub, non una issue pubblica. Un default che lascia entrare un attaccante conta come vulnerabilità.