mock-server

mTLS通信の検証まで可能な、WebUI付きモックサーバー。

WebUIで定義したエンドポイントに対し、受信内容（ヘッダー・Cookie・パラメータ・ボディ・証明書・認証・時間）を検証し、定義したスリープ時間の後にレスポンスを返します。リクエスト・レスポンス・検証結果・所要時間を記録して後から参照でき、性能試験用にロギングを簡略化できます。

通常のHTTPSサーバーは不正なクライアント証明書をTLSハンドシェイクの時点で拒否するため、「なぜNGだったか」を記録できません。本ツールはTLS層では接続を通し、アプリケーション層で証明書を検証することで、証明書検証の結果そのものを試験の観測対象にします。

現在のステータス

要件定義・アーキテクチャ設計・HTTP垂直スライス（Phase 1-a）が完了しています。 TLS/mTLS、WebUI、DB永続化は未着手です。

中核となる技術的前提（TLS層でフェイルオープンして証明書をアプリ層で検証できること）は、Node.js 24 上で実機検証済みです。

フェーズ	状態
要件定義	✅ 完了
アーキテクチャ設計	✅ 完了
Phase 0（中核仮説の実証）	✅ 完了
Phase 1-a（基盤とHTTP垂直スライス）	✅ 完了
Phase 1-b以降（レスポンステンプレート、DB永続化、WebUI 等）	⬜ 未着手

ドキュメント

文書	内容
docs/requirements.md	要件定義書。決定事項30件と実機検証結果を含む
docs/ai-dlc/SYSTEM_ARCHITECTURE.md	アーキテクチャ設計。モジュール境界と判断根拠
docs/ai-dlc/TASK_SPEC.md	次に着手するタスクの仕様
AGENTS.md	AIエージェント向けの行動規範と設計原則
docs/phase0-probe/	Phase 0 の実機検証スクリプト

開発環境

Node.js 24 LTS 以上が必要です（node:sqlite と node:test を標準機能として使用）。

nvm use          # .nvmrc に従って Node 24 を使う
npm install

コマンド	内容
npm run dev	定義ファイルを読み込みHTTPリスナーを起動（--watch 付き）
npm test	node:test によるユニット・E2Eテスト
npm run typecheck	tsc --noEmit（src/ と test/ の両方）
npm run lint	Biome によるLint
npm run build	src/ を dist/ へトランスパイル（npm start で実行）

npm run dev は追加設定なしでも動作し、既定では同梱のサンプル定義（examples/definitions.example.json）をモックHTTPポート8080、管理WebUIポート8081（127.0.0.1）で起動します。挙動は環境変数で上書きできます（値は既定値）。

MOCK_HTTP_PORT=8080 \
MOCK_HTTP_HOST=0.0.0.0 \
MOCK_ADMIN_PORT=8081 \
MOCK_ADMIN_HOST=127.0.0.1 \
MOCK_DEFINITIONS_FILE=./examples/definitions.example.json \
MOCK_DB_PATH=./mock-server.sqlite \
npm run dev

.env ファイルでも設定できます（npm run dev / npm start は Node標準の --env-file-if-exists=.env で自動的に読み込みます。ファイルが無くてもエラーにはなりません）。

cp .env.example .env
# .env を編集（閉域・内部ネットワーク内でWebUIを公開する場合は MOCK_ADMIN_HOST=0.0.0.0 に変更）
npm run dev

シェルで設定した環境変数は .env の値より優先されます。.env は秘密情報を含み得るためコミットしないでください（.gitignore 済み）。

現時点（Phase 1-a）でできることは、JSONファイルで定義したエンドポイントへのHTTPマッチング・ヘッダー/クエリ/パスパラメータの検証・スリープ・ログのSQLite記録までです。TLS/mTLS・WebUI・DB永続化・レスポンステンプレートは未実装です。定義ファイルの書式は examples/definitions.example.json を参照してください。

制約

• サーバーレス環境では動作しません。 生のTLSソケットに触れる必要があるため、常駐プロセスとして動作させます
• 上流のロードバランサやリバースプロキシでTLS終端しないでください。 証明書情報が又聞きになり、検証の忠実性が失われます
• 管理用WebUIは証明書発行機能を持つため、既定で 127.0.0.1 にのみバインドします。Docker実行時も -p 127.0.0.1:8080:8080 のようにホストのループバックへ限定してください