nestjs-docfy 0.19 は破壊的変更を含むセキュリティリリースです。 移行ガイドを読む →

セキュリティと 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 への移行

プロジェクトに当てはまる項目を一つずつ確認してください:

  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. カスタムのコントローラー glob は完全一致になりました。*.ctrl.ts は users.ctrl.tsx にマッチしなくなります。

警告の受け取り方

  • 起動時:危険な設定ごとにログへ警告が出て、本番環境でプロキシが無効化されたときはエラーが出ます。
  • ドキュメント UI 内:問題を一覧するバナー。本番環境以外でのみ表示されます。
  • nestjs-docfy doctor 内:setup() 呼び出しの静的解析による [security] の指摘。
  • プロキシのレスポンス内:X-Docfy-Proxy-Error ヘッダーがリクエストを拒否した理由を示します。

脆弱性の報告

セキュリティ上の問題を見つけましたか?公開 issue ではなく、GitHub の非公開フォーム Report a vulnerability を使ってください。攻撃者を通してしまうデフォルトは脆弱性として扱います。