# セキュリティ設計書

## 概要

本ドキュメントは、Webpack 5.105.3（JavaScriptモジュールバンドラー）のセキュリティ設計について記載する。Webpackはビルドツールであり、一般的なWebアプリケーションのような認証・認可システムは持たないが、HTTPリソース取得、入力検証、キャッシュ管理、ハッシュ処理などの領域において堅牢なセキュリティ機構を実装している。

## 認証設計

### 認証方式

本プロジェクトはビルドツールのため、ユーザー認証機構は実装されていない。ビルド時にHTTPリソースを取得する際のプロキシ認証（CONNECT メソッド）のみ対応している。

- **プロキシ認証**: `lib/schemes/HttpUriPlugin.js` にて、HTTP CONNECTメソッドによるプロキシトンネリングを実装。プロキシサーバーへの接続時にステータスコード200を検証する。

### セッション管理

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| セッション管理 | 該当なし | ビルドツールのためセッション管理は不要 |
| ロックファイル | `lock.json`（バージョン1） | HTTPリソースの整合性管理に使用（`lib/schemes/HttpUriPlugin.js`） |

## 認可設計

### 権限体系

| ロール | 権限 | 説明 |
| --- | --- | --- |
| ビルド実行者 | 全権限 | Webpackの実行者はビルドプロセス全体を制御する |

### アクセス制御

ビルドツールとしてのアクセス制御は、HTTPリソース取得時の `allowedUris` ポリシーで実現している。

- **allowedUrisポリシー** (`schemas/plugins/schemes/HttpUriPlugin.json`): 外部リソースの取得先を制限するホワイトリスト方式。正規表現、文字列前方一致、カスタムフィルタ関数の3種類で指定可能。
- **リダイレクト制限** (`lib/schemes/HttpUriPlugin.js`): 最大リダイレクト回数を5回に制限（`MAX_REDIRECTS = 5`）。リダイレクト先URLのプロトコル検証（http/httpsのみ許可）と`allowedUris`ポリシーの再検証を実施。
- **プロトコルホワイトリスト**: リダイレクト先URLのプロトコルをhttp/httpsに限定し、不正なプロトコルへのリダイレクトを防止。

## 通信セキュリティ

| 項目 | 対策 |
| --- | --- |
| HTTPS | HTTPリソース取得時にhttp/httpsスキームを明示的にサポート（`lib/schemes/HttpUriPlugin.js`）。プロキシ経由のCONNECTトンネリングに対応 |
| プロキシ | HTTP CONNECTメソッドによるプロキシトンネリング実装。ステータスコード200検証後にソケット接続を確立 |
| リダイレクト検証 | リダイレクト先URLのプロトコル検証、`allowedUris`ポリシー再検証、最大5回のリダイレクト制限 |

## データセキュリティ

### 暗号化

| 対象 | 暗号化方式 |
| --- | --- |
| コンテンツ整合性検証 | SHA-512（SubResource Integrity相当、`lib/schemes/HttpUriPlugin.js`） |
| モジュールハッシュ | xxhash64（高速非暗号化ハッシュ、デフォルト）、MD4（WebAssembly実装）、SHA-256/SHA-512（Node.js crypto対応） |
| キャッシュETag | `createHash` 経由でbase64ダイジェスト生成（`lib/cache/getLazyHashedEtag.js`） |
| シリアライゼーション | ハッシュ関数によるバッファ整合性検証（`lib/serialization/ObjectMiddleware.js`） |

ハッシュアルゴリズムの選択は `lib/util/createHash.js` で一元管理されており、以下のアルゴリズムをサポートする:
- **xxhash64**: WebAssembly実装の高速非暗号化ハッシュ（ファイル識別用）
- **md4**: WebAssembly実装の非暗号化ハッシュ（互換性用）
- **native-md4**: Node.js crypto モジュール経由のMD4
- **sha256/sha512等**: Node.js crypto モジュール対応の暗号化ハッシュ

### 機密情報管理

環境変数の管理は `lib/DotenvPlugin.js` で実装されている。

- **プレフィックスフィルタリング**: デフォルトプレフィックス `WEBPACK_` に合致する環境変数のみをビルド成果物に公開。意図しない環境変数の漏洩を防止する。
- **.envファイルテンプレート**: `.env`, `.env.local`, `.env.[mode]`, `.env.[mode].local` の4段階で環境別の設定を管理。
- **変数展開時の循環参照検出**: `expandValue` 関数内で `Set` を使用した自己参照検出を実装し、無限ループを防止。
- **プロトタイプ汚染対策**: `.env`ファイルのパース結果を `Object.create(null)` で生成し、プロトタイプチェーンからの汚染を防止。

## 入出力対策

| 脅威 | 対策 |
| --- | --- |
| URLインジェクション | `sanitizeUrlForError` 関数でエラーメッセージ中のURLをホスト部分のみに制限、改行文字除去、200文字制限（`lib/schemes/HttpUriPlugin.js`） |
| パストラバーサル | `toSafePath` 関数で特殊文字をアンダースコアに置換、先頭・末尾の特殊文字を除去（`lib/schemes/HttpUriPlugin.js`） |
| 設定インジェクション | JSON Schemaによるwebpack設定の厳密なバリデーション（`lib/validateSchema.js`）。不正なプロパティに対する修正提案（DID_YOU_MEAN）を提示 |
| .envインジェクション | 正規表現による厳密なキー・値パース。クォート処理とエスケープ処理を適切に実装（`lib/DotenvPlugin.js`） |
| プロトタイプ汚染 | `.env`パース結果に `Object.create(null)` を使用し、`__proto__` 等のプロトタイプ汚染を防止 |
| オープンリダイレクト | リダイレクト先URLのプロトコル検証（http/httpsのみ）、`allowedUris`ポリシー再検証、最大リダイレクト回数制限 |
| CSP | ランタイムモジュールで `eval` 使用時のCSP対応をコメント記載（`lib/runtime/GlobalRuntimeModule.js`） |

## 監査ログ

| ログ種別 | 記録内容 | 保持期間 |
| --- | --- | --- |
| エラーログ | ビルドエラー、設定エラー、リソース取得エラー | ビルド実行中のみ（コンソール出力） |
| 警告ログ | 非推奨設定の使用、パフォーマンス警告 | ビルド実行中のみ（コンソール出力） |
| 情報ログ | ビルド進捗、モジュール解決結果 | ビルド実行中のみ（コンソール出力） |
| デバッグログ | HTTPリソース取得の詳細（ステータスコード、サイズ、リダイレクト先） | ビルド実行中のみ（コンソール出力） |
| プロファイルログ | ビルドパフォーマンス測定（`process.hrtime` ベース） | ビルド実行中のみ（コンソール出力） |
| キャッシュログ | Cache-Controlヘッダーによるキャッシュ不可理由 | ビルド実行中のみ（コンソール出力） |

ロギングは `lib/logging/Logger.js` で定義された `WebpackLogger` クラスにより実現される。ログレベルは `error`, `warn`, `info`, `log`, `debug`, `trace` の6段階で制御可能。`lib/logging/createConsoleLogger.js` にてフィルタリングとラベル付き出力を実装している。

## 備考

### プロジェクト特性に関する補足

Webpackはビルドツール（コンパイラ）であり、Webアプリケーションサーバーではないため、以下のセキュリティ項目は設計対象外となる:

- **認証・認可**: エンドユーザー認証やロールベースアクセス制御は不要
- **CORS設定**: HTTPサーバーを持たないため不要
- **CSRF対策**: フォーム送信機能を持たないため不要
- **XSS防止**: HTML出力を生成しないため直接的な対策は不要（ただし、バンドル生成コードにおけるXSS注入の可能性はコメントで認識されている）

### キャッシュセキュリティ

- **unsafeCache機構**: `lib/Compilation.js` にて `WeakMap` ベースのキャッシュ管理を実装。名前に"unsafe"が含まれるのは、キャッシュされたモジュールが変更された場合にビルド結果が不整合になる可能性があるため。
- **キャッシュクリーンアップ**: `Module.cleanupForCache()` メソッドにてキャッシュデータの明示的なクリーンアップを実装。

### 整合性検証（SubResource Integrity）

`lib/schemes/HttpUriPlugin.js` にて、外部HTTPリソース取得時にSHA-512ベースの整合性検証を実装。ロックファイル（`lock.json`）にリソースごとのintegrityハッシュを保存し、再取得時に検証を行う。`integrity: "ignore"` 設定により検証をスキップすることも可能。

### HTMLサニタイズ

開発依存として `rehype-sanitize` パッケージ（v6.0.0）を使用し、ドキュメント生成時のHTMLサニタイズを実施。

### 静的解析

ESLint（v9.39.2）とcspell（v9.4.0）による静的解析とスペルチェックをCI/CDパイプラインで実行し、コード品質とセキュリティの維持を支援。
