nestjs-docfy 0.19 é um release de segurança com breaking changes. Leia o guia de migração →

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ê defina proxyAuthorize (ou allowProxyInProduction).
  • O proxy só aceita Content-Type: application/json, nunca repassa Host nem Set-Cookie e só alcança os servers do spec.
  • A UI das docs é servida com Content-Security-Policy estrita (script-src 'self'), nosniff e framing só da mesma origem. Para desligar, use securityHeaders: false.
  • Os testes de contrato só disparam GET, HEAD e OPTIONS, a menos que você passe --allow-writes.
  • O workflow reutilizável de PR exige docfy-version e docfy-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:

  1. Use Node.js 22.12 ou mais recente. Node 18 e 20 não recebem mais patches de segurança.
  2. Se você usa o CLI ou o plugin do compilador, rode npm install --save-dev ts-morph commander picocolors (mais openapi-typescript para o generate-client).
  3. Se você usa o "Try it out" em produção, adicione proxyAuthorize. Use allowProxyInProduction: true só quando outra coisa já protege o mount path.
  4. Se você chama o proxy por um cliente próprio, envie Content-Type: application/json; qualquer outro recebe 415.
  5. Se o "Try it out" chama outras origens direto ou as docs carregam recursos remotos, adicione-os com cspConnectSrc ou troque a política com contentSecurityPolicy.
  6. 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.
  7. Quem usa o workflow reutilizável de PR precisa passar docfy-version e docfy-ref.
  8. Globs customizados de controllers agora casam exatamente: *.ctrl.ts não casa mais com users.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-Error diz 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.