nestjs-docfy 0.19 是一个包含破坏性变更的安全版本。 阅读迁移指南 →

安全与迁移到 0.19

nestjs-docfy 0.19 默认锁定所有攻击面。本页列出每个默认值、放宽它的选项,以及升级时需要修改的内容。

0.19 包含破坏性变更
这些变更是为了防止这个库成为进入你应用的入口。大多数项目只需要下面的一两个步骤。

默认安全

任何削弱默认值的做法都有一个明确的选项名,因此会在代码评审中显现出来:

  • 构建工具(ts-morph、commander、picocolors、openapi-typescript)不再安装到生产环境:它们是可选的 peer 依赖,以开发依赖的方式安装。
  • 在 NODE_ENV=production 下,"Try it out" 代理默认关闭,除非你设置了 proxyAuthorize(或 allowProxyInProduction)。
  • 代理只接受 Content-Type: application/json,从不转发 Host 或 Set-Cookie,并且只访问 spec 中的 servers。
  • 文档 UI 以严格的 Content-Security-Policy(script-src 'self')、nosniff 和仅同源嵌入的方式提供。使用 securityHeaders: false 关闭。
  • 契约测试只发送 GET、HEAD 和 OPTIONS,除非你传入 --allow-writes。
  • 可复用的 PR 检查 workflow 必须提供 docfy-version 和 docfy-ref,因此永远不会运行未固定版本的代码。

Nest guards 与文档路由

DocfyUiModule.setup() 直接在 HTTP 适配器上注册路由,所以 Nest guards 永远不会作用于这些路由。请用在 setup() 之前注册的 middleware 保护文档,并用 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,
});

迁移到 0.19

逐项检查适用于你项目的内容:

  1. 使用 Node.js 22.12 或更高版本。Node 18 和 20 已不再获得安全补丁。
  2. 如果你使用 CLI 或编译器插件,运行 npm install --save-dev ts-morph commander picocolors(使用 generate-client 时再加上 openapi-typescript)。
  3. 如果你在生产环境使用 "Try it out",请添加 proxyAuthorize。只有在挂载路径已由其他机制保护时,才使用 allowProxyInProduction: true。
  4. 如果你从自己的客户端调用代理,请发送 Content-Type: application/json;其他类型会收到 415。
  5. 如果 "Try it out" 直接调用其他源,或文档加载远程资源,请用 cspConnectSrc 添加它们,或用 contentSecurityPolicy 替换整个策略。
  6. 需要写操作端点的契约测试请使用 --allow-writes;不是 localhost 且不在 spec servers 中的 base URL 需要 --no-restrict-to-servers。
  7. 可复用 PR workflow 的调用方必须传入 docfy-version 和 docfy-ref。
  8. 自定义的 controller glob 现在精确匹配:*.ctrl.ts 不再匹配 users.ctrl.tsx。

你会如何收到提醒

  • 启动时:每个有风险的配置都会在日志中给出警告,代理在生产环境被关闭时会输出错误。
  • 在文档 UI 中:一个列出问题的横幅,仅在非生产环境显示。
  • 在 nestjs-docfy doctor 中:对 setup() 调用做静态分析得出的 [security] 结果。
  • 在代理响应中:X-Docfy-Proxy-Error 响应头说明请求被拒绝的原因。

报告漏洞

发现了安全问题?请使用 GitHub 的私密表单 Report a vulnerability,不要提交公开 issue。让攻击者得以进入的默认值也算作漏洞。