セキュリティと 0.19 への移行
nestjs-docfy 0.19 はデフォルトであらゆる攻撃面を閉じます。このページでは各デフォルト、それを緩めるオプション、アップグレード時に変更すべき点を説明します。
0.19 には破壊的変更があります
ライブラリがアプリへの侵入口にならないようにするための変更です。ほとんどのプロジェクトで必要なのは、以下の手順のうち 1 つか 2 つです。
デフォルトで安全
デフォルトを弱めるものにはすべて明示的なオプション名があるため、コードレビューで目に留まります:
- ビルドツール(
ts-morph、commander、picocolors、openapi-typescript)は本番環境にインストールされなくなりました。オプションの peer 依存として、開発依存でインストールします。 NODE_ENV=productionでは、proxyAuthorize(またはallowProxyInProduction)を設定しない限り「Try it out」プロキシは無効です。- プロキシは
Content-Type: application/jsonのみを受け付け、HostやSet-Cookieを転送せず、spec の servers にのみ接続します。 - ドキュメント UI は厳格な Content-Security-Policy(
script-src 'self')、nosniff、同一オリジンのみのフレーム埋め込みで配信されます。securityHeaders: falseで無効化できます。 - コントラクトテストは、
--allow-writesを渡さない限りGET、HEAD、OPTIONSのみを送信します。 - 再利用可能な PR チェック workflow では
docfy-versionとdocfy-refが必須なので、バージョン未固定のコードは実行されません。
Nest の guard とドキュメントのルート
DocfyUiModule.setup() はルートを HTTP アダプターに直接登録するため、Nest の guard はこれらのルートでは決して実行されません。ドキュメントは setup() の前に登録したミドルウェアで、プロキシは 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を渡す必要があります。 - カスタムのコントローラー glob は完全一致になりました。
*.ctrl.tsはusers.ctrl.tsxにマッチしなくなります。
警告の受け取り方
- 起動時:危険な設定ごとにログへ警告が出て、本番環境でプロキシが無効化されたときはエラーが出ます。
- ドキュメント UI 内:問題を一覧するバナー。本番環境以外でのみ表示されます。
nestjs-docfy doctor内:setup() 呼び出しの静的解析による[security]の指摘。- プロキシのレスポンス内:
X-Docfy-Proxy-Errorヘッダーがリクエストを拒否した理由を示します。
脆弱性の報告
セキュリティ上の問題を見つけましたか?公開 issue ではなく、GitHub の非公開フォーム Report a vulnerability を使ってください。攻撃者を通してしまうデフォルトは脆弱性として扱います。