安全与迁移到 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
逐项检查适用于你项目的内容:
- 使用 Node.js 22.12 或更高版本。Node 18 和 20 已不再获得安全补丁。
- 如果你使用 CLI 或编译器插件,运行
npm install --save-dev ts-morph commander picocolors(使用 generate-client 时再加上openapi-typescript)。 - 如果你在生产环境使用 "Try it out",请添加
proxyAuthorize。只有在挂载路径已由其他机制保护时,才使用allowProxyInProduction: true。 - 如果你从自己的客户端调用代理,请发送
Content-Type: application/json;其他类型会收到415。 - 如果 "Try it out" 直接调用其他源,或文档加载远程资源,请用
cspConnectSrc添加它们,或用contentSecurityPolicy替换整个策略。 - 需要写操作端点的契约测试请使用
--allow-writes;不是 localhost 且不在 spec servers 中的 base URL 需要--no-restrict-to-servers。 - 可复用 PR workflow 的调用方必须传入
docfy-version和docfy-ref。 - 自定义的 controller glob 现在精确匹配:
*.ctrl.ts不再匹配users.ctrl.tsx。
你会如何收到提醒
- 启动时:每个有风险的配置都会在日志中给出警告,代理在生产环境被关闭时会输出错误。
- 在文档 UI 中:一个列出问题的横幅,仅在非生产环境显示。
- 在
nestjs-docfy doctor中:对 setup() 调用做静态分析得出的[security]结果。 - 在代理响应中:
X-Docfy-Proxy-Error响应头说明请求被拒绝的原因。
报告漏洞
发现了安全问题?请使用 GitHub 的私密表单 Report a vulnerability,不要提交公开 issue。让攻击者得以进入的默认值也算作漏洞。