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.
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=productionil proxy di "Try it out" è disattivato, a meno che tu non impostiproxyAuthorize(oallowProxyInProduction). - Il proxy accetta solo
Content-Type: application/json, non inoltra maiHostnéSet-Cookiee raggiunge solo i server dello spec. - La UI della documentazione è servita con una Content-Security-Policy rigorosa (
script-src 'self'),nosniffe framing solo dalla stessa origine. Disattivali consecurityHeaders: false. - I test di contratto inviano solo
GET,HEADeOPTIONS, a meno che tu non passi--allow-writes. - Il workflow riutilizzabile di controllo delle PR richiede
docfy-versionedocfy-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:
// 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:
- Usa Node.js 22.12 o successivo. Node 18 e 20 non ricevono più patch di sicurezza.
- Se usi il CLI o il plugin del compilatore, esegui
npm install --save-dev ts-morph commander picocolors(piùopenapi-typescriptper generate-client). - Se usi "Try it out" in produzione, aggiungi
proxyAuthorize. UsaallowProxyInProduction: truesolo quando qualcos'altro protegge già il mount path. - Se chiami il proxy da un tuo client, invia
Content-Type: application/json; qualsiasi altro riceve415. - Se "Try it out" chiama altre origini direttamente o la documentazione carica risorse remote, aggiungile con
cspConnectSrco sostituisci la policy concontentSecurityPolicy. - 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. - Chi usa il workflow riutilizzabile delle PR deve passare
docfy-versionedocfy-ref. - I glob personalizzati dei controller ora corrispondono esattamente:
*.ctrl.tsnon corrisponde più ausers.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-Errorspiega 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à.