Segurança e migração para a 0.19
O nestjs-docfy 0.19 trava toda a superfície por padrão. Esta página lista cada default, a opção que o afrouxa e o que mudar ao atualizar.
A 0.19 tem breaking changes
Elas existem para que a lib não vire porta de entrada para o seu app. A maioria dos projetos precisa de um ou dois dos passos abaixo.
Seguro por padrão
Tudo que enfraquece um default tem um nome de opção explícito, então aparece no code review:
- As ferramentas de build (
ts-morph,commander,picocolors,openapi-typescript) não são mais instaladas em produção: viraram peer opcional, instalado como dependência de desenvolvimento. - Com
NODE_ENV=production, o proxy do "Try it out" fica desligado, a menos que você definaproxyAuthorize(ouallowProxyInProduction). - O proxy só aceita
Content-Type: application/json, nunca repassaHostnemSet-Cookiee só alcança os servers do spec. - A UI das docs é servida com Content-Security-Policy estrita (
script-src 'self'),nosniffe framing só da mesma origem. Para desligar, usesecurityHeaders: false. - Os testes de contrato só disparam
GET,HEADeOPTIONS, a menos que você passe--allow-writes. - O workflow reutilizável de PR exige
docfy-versionedocfy-ref, então nunca roda código sem versão fixada.
Guards do Nest e as rotas das docs
DocfyUiModule.setup() registra as rotas direto no adapter HTTP, então os guards do Nest nunca rodam nelas. Proteja as docs com um middleware registrado antes do setup(), e o proxy com 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,
});Migrando para a 0.19
Passe por cada item que se aplica ao seu projeto:
- Use Node.js 22.12 ou mais recente. Node 18 e 20 não recebem mais patches de segurança.
- Se você usa o CLI ou o plugin do compilador, rode
npm install --save-dev ts-morph commander picocolors(maisopenapi-typescriptpara o generate-client). - Se você usa o "Try it out" em produção, adicione
proxyAuthorize. UseallowProxyInProduction: truesó quando outra coisa já protege o mount path. - Se você chama o proxy por um cliente próprio, envie
Content-Type: application/json; qualquer outro recebe415. - Se o "Try it out" chama outras origens direto ou as docs carregam recursos remotos, adicione-os com
cspConnectSrcou troque a política comcontentSecurityPolicy. - Testes de contrato que precisam de endpoints de escrita usam
--allow-writes; uma base URL que não é localhost e está fora dos servers do spec precisa de--no-restrict-to-servers. - Quem usa o workflow reutilizável de PR precisa passar
docfy-versionedocfy-ref. - Globs customizados de controllers agora casam exatamente:
*.ctrl.tsnão casa mais comusers.ctrl.tsx.
Como você será avisado
- No boot: um aviso nos logs para cada configuração arriscada, e um erro quando o proxy é desligado em produção.
- Na UI das docs: um banner listando os problemas, exibido só fora de produção.
- No
nestjs-docfy doctor: achados[security]de uma análise estática das suas chamadas a setup(). - Nas respostas do proxy: o header
X-Docfy-Proxy-Errordiz por que a requisição foi rejeitada.
Reportando uma vulnerabilidade
Encontrou um problema de segurança? Use o formulário privado Report a vulnerability do GitHub, não uma issue pública. Um default que deixa um atacante entrar conta como vulnerabilidade.