Cookie Auth Proxy

ローカル開発用ツールのため、通常は client app の devDependency として追加します。

npm install -D @mug-lab/cookie-auth-proxy

Cookie Auth Proxy is intended for local development. Install it as a devDependency in your client app project.

注意 / Notice

このツールはローカル開発支援用です。公開サーバとして動かすことは想定していません。 認証済み Cookie を扱えるため、実 Cookie 値を設定ファイル、スタブ、README、Issue、ログなどに残さないでください。 保守は best effort です。

This is a local development helper. It is not intended to be exposed as a public server. Because it can handle authenticated cookies, do not store real cookie values in config files, stubs, README files, issues, logs, or other shared artifacts. Maintenance is provided on a best-effort basis.

概要 / Overview

Cookie でセッションIDや認証状態を渡すタイプの Web アプリを、ローカル開発しやすくするためのプロキシです。

Cookie Auth Proxy is a local development proxy for web applications that use cookies to pass session IDs or authentication state to the server.

ブラウザは http://localhost:4300 のプロキシにアクセスします。プロキシはパスベースで、ローカルの client dev server とリモート API にリクエストを振り分けます。API に送るリクエストだけに認証済み Cookie を注入できるため、フロントエンドはローカルで動かしつつ、API は既存の検証環境やテスト用デプロイを使えます。

The browser accesses the proxy at http://localhost:4300. The proxy routes requests by path to either a local client dev server or a remote API origin. It can inject an authenticated cookie only into API requests, so you can run the frontend locally while using an existing validation environment or test API deployment.

特定のフロントエンドフレームワークには依存しません。Cookie 認証の Web アプリであれば、フレームワークを問わず利用できます。

This tool is frontend-framework agnostic. It can be used with any web app that relies on cookie-based authentication.

アーキテクチャ / Architecture

アーキテクチャ図は GitHub README で描画されます。npm 上でソース表示になる場合は GitHub README を参照してください。

The architecture diagram is rendered on GitHub. If it appears as source text on npm, see the GitHub README.

flowchart LR
  Browser["Browser"]
  Proxy["Cookie Auth Proxy<br/>localhost:4300"]
  Admin["Admin UI<br/>localhost:4301"]
  Client["Client dev server<br/>localhost:8080"]
  API["Remote API origin"]
  Rules["Runtime settings<br/>Cookie / Origin / Stubs / Overrides"]
  Files["Startup import files<br/>stubs / overrides"]

  Browser -->|"App access"| Proxy
  Admin -->|"Update settings<br/>inspect history"| Rules
  Files -->|"Load on startup"| Rules
  Rules --> Proxy
  Proxy -->|"Non API paths"| Client
  Proxy -->|"API paths + injected Cookie"| API
  API -->|"Response headers/body rewrite<br/>history capture"| Proxy
  Proxy --> Browser

通常の画面アクセスは localhost:4300 のプロキシを経由します。プロキシはパス設定に従って、client dev server または remote API origin に振り分けます。API リクエストには管理画面または設定ファイルで指定した Cookie を注入し、レスポンスは必要に応じて localhost 向けに書き換えます。

Application traffic goes through the proxy at localhost:4300. The proxy routes each request to either the client dev server or the remote API origin based on path settings. API requests can receive an injected Cookie from the admin UI or config file, and responses are rewritten for localhost when needed.

主な機能 / Features

• パスベースで client dev server と API server に振り分け / Route requests by path to a client dev server or API server
• API origin、client origin、API Cookie を管理画面から実行時変更 / Change API origin, client origin, and API Cookie at runtime from the admin UI
• API 通信履歴の確認、フィルタ、レスポンスコピー / Inspect, filter, and copy API history and responses
• 履歴からスタブ、JSON Override を作成 / Create stubs and JSON Overrides from captured history
• スタブのインポート、エクスポート、起動時自動読み込み / Import, export, and auto-load stubs at startup
• JSON Override のインポート、エクスポート、起動時自動読み込み / Import, export, and auto-load JSON Overrides at startup
• API origin のホワイトリスト制限 / Restrict API origins with an allowlist
• 管理画面への注意文言表示 / Show team notices in the admin UI
• npm package として導入、または clone/zip で単体利用 / Use as an npm package, or run standalone from a clone or zip

クイックスタート

client app のプロジェクトに devDependency として追加します。

npm install -D @mug-lab/cookie-auth-proxy

プロジェクトルートで初期設定を作成します。

npx cookie-auth-proxy init

未インストールの状態で直接実行する場合は npx @mug-lab/cookie-auth-proxy init を使います。devDependencyとして追加した後は、bin名の cookie-auth-proxy で実行できます。

init は次のファイルを作成します。

<client-project-root>/
  cookie-auth-proxy.config.json
  cookie-auth-proxy/
    cookie-auth-proxy.schema.json
    stubs/
      README.md
    overrides/
      README.md

cookie-auth-proxy.config.json の clientOrigin と apiOrigin を環境に合わせて変更します。 configには $schema が設定されるため、VS Codeなどのエディタで設定項目の補完や型チェックを利用できます。

{
  "clientOrigin": "http://localhost:8080",
  "apiOrigin": "https://api.invalid",
  "apiRequestOrigin": ""
}

client app 側の package.json に script を追加します。

{
  "scripts": {
    "cookie-auth-proxy:init": "cookie-auth-proxy init",
    "cookie-auth-proxy": "cookie-auth-proxy --config cookie-auth-proxy.config.json"
  }
}

client dev server を別ターミナルで起動したうえで、プロキシを起動します。

npm run cookie-auth-proxy

起動後は次の URL を開きます。

• 管理画面: http://localhost:4301
• プロキシ経由のアプリ: http://localhost:4300

設定ファイルを作らずに起動し、管理画面から Client Origin と API Origin を入力することもできます。

サポートフォルダの変更

スタブや Override の置き場を変えたい場合は、init 時に --support-dir を指定します。パスはプロジェクトルートからの相対パスです。

npx cookie-auth-proxy init --support-dir tools/cookie-auth-proxy

この場合、次のように作成されます。

<client-project-root>/
  cookie-auth-proxy.config.json
  tools/
    cookie-auth-proxy/
      cookie-auth-proxy.schema.json
      stubs/
        README.md
      overrides/
        README.md

同時に cookie-auth-proxy.config.json の startupStubImportDir と startupOverrideImportDir も更新されます。

既存ファイルを上書きしたい場合は --force を付けます。

npx cookie-auth-proxy init --force

スタンドアロン利用

このリポジトリを clone したり、zip で展開してそのまま使う場合は、同梱の config.json を読みます。

npm install
npm start

スタンドアロン用の config.json は、リポジトリ直下の stubs と overrides を起動時インポート先として使います。

設定ファイル

npm package として client app に導入する場合は、通常 cookie-auth-proxy.config.json を使います。スタンドアロン利用では config.json を使います。

基本形は次のような設定です。

{
  "listenHost": "localhost",
  "listenPort": 4300,
  "clientOrigin": "http://localhost:8080",
  "apiOrigin": "https://api.invalid",
  "apiRequestOrigin": "",
  "apiPathPatterns": ["^/api(?:/|$)"],
  "apiPathExcludes": [
    "^/$",
    "^/favicon\\.ico$",
    "^/(?:assets|static)(?:/|$)",
    "^/sockjs-node(?:/|$)"
  ],
  "apiCookie": "sessionId=; authState=",
  "startupStubImportDir": "cookie-auth-proxy/stubs",
  "startupOverrideImportDir": "cookie-auth-proxy/overrides",
  "serverAppPath": "/",
  "adminHost": "localhost",
  "adminPort": 4301,
  "historyLimit": 200,
  "maxAdminBodyBytes": 1048576,
  "maxRequestBodyInspectionBytes": 10485760,
  "maxResponseBodyRewriteBytes": 52428800,
  "maxHistoryBodyBytes": 524288,
  "allowRemoteAccess": false
}

apiOrigin は空文字でも起動できます。その場合、管理画面から API origin を設定するまで API リクエストは 502 になります。

apiRequestOrigin は、API へ送る Origin / Referer ヘッダーの基準Originです。空文字の場合は apiOrigin に追従します。フロントエンドとAPIが別オリジンで、API側がフロントエンドのOriginを許可している場合は、認証済みCookieを取得したフロントエンドのOriginを指定します。

{
  "clientOrigin": "http://localhost:8080",
  "apiOrigin": "https://api.invalid",
  "apiRequestOrigin": "https://app.invalid"
}

apiCookie は Cookie 名だけを設定しておくこともできます。

{
  "apiCookie": "sessionId=; authState="
}

実際の Cookie 値は認証情報です。共有リポジトリにコミットしない運用をおすすめします。

起動オプション

cookie-auth-proxy [apiOrigin] [options]

主なオプションです。

• --config <path>: 設定ファイルを指定
• --api <origin>: API origin を指定
• --api-request-origin <origin>: API へ送る Origin / Referer の基準Originを指定
• --client <origin>: client dev server の origin を指定
• --cookie <cookie>: API に注入する Cookie を指定
• --host <host>: プロキシの listen host を指定
• --port <port>: プロキシの listen port を指定
• --admin-host <host>: 管理画面の listen host を指定
• --admin-port <port>: 管理画面の listen port を指定
• --allow-remote-access: localhost 以外の host でlistenすることを明示許可
• --dry-run: 起動せずに設定と起動時Importを検証
• --startup-stub-import-dir <path>: 起動時に読み込むスタブフォルダを指定
• --startup-override-import-dir <path>: 起動時に読み込む Override フォルダを指定
• --server-app-path <path>: 管理画面の Open Server App ボタンで開くパスを指定
• --logLevel <silent|error|info|debug>: ログレベルを指定
• --version, -v: バージョンを表示
• --help, -h: ヘルプを表示

一時的に API origin を変える場合は、位置引数または --api を使います。

npm run cookie-auth-proxy -- https://test-api.invalid

npm run cookie-auth-proxy -- --api https://test-api.invalid

設定値の優先順位は次の順です。

CLI arguments > environment variables > config file > defaults

設定とローカル環境をまとめて確認する場合は doctor を使います。

cookie-auth-proxy doctor --config cookie-auth-proxy.config.json

doctor は config、起動時Importフォルダ、port空き、API origin allowlist などを確認します。設定だけを検証して終了したい場合は --dry-run を使います。

cookie-auth-proxy --config cookie-auth-proxy.config.json --dry-run

環境変数

次の環境変数でも指定できます。

• API_ORIGIN
• API_REQUEST_ORIGIN
• API_COOKIE
• CLIENT_ORIGIN
• PROXY_HOST
• PROXY_PORT
• STARTUP_STUB_IMPORT_DIR
• STARTUP_OVERRIDE_IMPORT_DIR
• SERVER_APP_PATH
• ADMIN_HOST
• ADMIN_PORT
• ALLOW_REMOTE_ACCESS
• LOG_LEVEL

cmd.exe:

set API_ORIGIN=https://test-api.invalid
npm run cookie-auth-proxy

PowerShell:

$env:API_ORIGIN = "https://test-api.invalid"
npm run cookie-auth-proxy

bash / ksh:

API_ORIGIN=https://test-api.invalid npm run cookie-auth-proxy

認証 Cookie

事前に本物の API origin でログイン済み Cookie を取得できている場合、その Cookie を API 向けリクエストに注入できます。Cookie は API にだけ付与され、client dev server に転送されるリクエストには付与されません。

管理画面の API Cookie で Cookie 名と値を項目ごとに編集できます。値はマスク表示できます。

起動時に直接指定することもできます。

cmd.exe:

npm run cookie-auth-proxy -- --cookie "sessionId=xxxxx; authState=yyyyy"

PowerShell:

npm run cookie-auth-proxy -- --cookie "sessionId=xxxxx; authState=yyyyy"

bash / ksh:

npm run cookie-auth-proxy -- --cookie 'sessionId=xxxxx; authState=yyyyy'

Shell や VSCode の入力履歴に残る可能性があるため、共有端末では注意してください。

パス振り分け

apiPathPatterns に一致するパスは API server へ転送します。初期値は /api 配下です。

{
  "apiPathPatterns": [
    "^/api(?:/|$)"
  ]
}

一致しないパスは client dev server へ転送します。/graphql や /v1 なども API にしたい場合は追加してください。

{
  "apiPathPatterns": [
    "^/api(?:/|$)",
    "^/graphql$",
    "^/v1(?:/|$)"
  ]
}

apiPathExcludes に一致するパスは API 判定から除外します。アセットや dev server 用の WebSocket 系パスを client 側へ逃がしたい場合に使います。

Origin 制限

誤って本番環境などに向けないように、API origin をホワイトリスト制限できます。空配列の場合は制限なしです。

{
  "apiOriginAllowedPatterns": [
    "^https://(?:api|test-api)\\.invalid$"
  ]
}

制限に一致しない apiOrigin は、起動時も管理画面からの変更時もエラーになります。管理画面では入力欄の下にエラーメッセージが表示されます。

管理画面

プロキシ起動中は http://localhost:4301 で管理画面を開けます。

できること:

• Client Origin と API Origin の変更
• API Cookie の項目別編集
• API 通信履歴の確認
• 履歴からスタブを作成
• 履歴から JSON Override を作成
• スタブの追加、編集、コピー、削除、並び替え、インポート、エクスポート
• JSON Override の追加、編集、コピー、削除、並び替え、インポート、エクスポート
• スタブと JSON Override の名前、Method、Path Pattern フィルタ
• プロキシ経由のアプリを別タブで開く
• API origin 側のサーバアプリを別タブで開く

管理画面で変更した値は実行中のプロキシプロセスにだけ反映されます。設定ファイルには書き戻しません。

管理画面にメンバー向けの注意文言を表示したい場合は adminNotice を設定します。

{
  "adminNotice": "テスト期間中のため、更新リクエストは禁止です。"
}

改行もそのまま表示されます。

通信履歴

履歴タブでは API server との通信を確認できます。

• 新しい履歴ほど上に表示
• ステータス系統で色分け
• ステータスフィルタ
• パスの正規表現フィルタ
• レスポンスヘッダーとレスポンス Body の確認
• JSON Body の整形表示
• レスポンス Body のコピー
• 展開時のStub/JSON Override適用情報の確認
• 履歴からスタブまたは JSON Override を追加

履歴件数は historyLimit で制限できます。画面表示しない古い履歴は切り捨てます。

{
  "historyLimit": 200,
  "maxHistoryBodyBytes": 524288
}

レスポンス Body が maxHistoryBodyBytes を超えた場合、履歴には新しい側の一部だけを保存します。画面上にはサイズ上限で切り捨てられたことを表示します。

スタブ

スタブは、条件に一致した API リクエストへ固定レスポンスを返す機能です。複数マッチした場合は、上にあるスタブが優先されます。

主な条件:

• method
• pathPattern
• queryParams
• requestBody

pathPattern は query string より前のパス部分に対して判定します。query string や POST Body などの一部項目だけを条件にしたい場合は queryParams と requestBody を使います。値は正規表現として判定されます。

{
  "method": "POST",
  "pathPattern": "^/api/users$",
  "queryParams": {
    "role": "^admin$"
  },
  "requestBody": {
    "status": "^(active|pending)$"
  }
}

スタブは管理画面で作成、編集、コピー、削除、並び替えできます。全体トグルと行単位トグルがあります。全体トグルが OFF の場合、行単位トグルが ON でもスタブは適用されません。

起動時に startupStubImportDir 配下の JSON ファイルをすべて読み込みます。

{
  "startupStubImportDir": "cookie-auth-proxy/stubs"
}

エクスポートしたスタブ JSON はチーム共有用にコミットできます。レスポンス Body が JSON の場合、エクスポートファイルでは文字列ではなく JSON 値として出力します。既存のローカルレスポンス JSON 資産からコピーしやすい形式です。

JSON Override

JSON Override は、API server から返ってきた JSON レスポンスの一部プロパティを上書きまたは追加する機能です。スタブと違い、API server への通信は実行されます。

用途例:

• ユーザー属性だけ切り替える
• 権限フラグだけ変更する
• レスポンス全体は実 API を使い、一部だけテスト値にする

条件はスタブと同じく、method、pathPattern、queryParams、requestBody を使えます。複数マッチした場合は、上にある Override から順に適用されます。

Override JSON に書いたプロパティは、同じプロパティがあれば上書きし、なければ追加します。

{
  "role": "admin",
  "featureFlags": {
    "newDashboard": true
  }
}

JSON Override も管理画面で追加、編集、コピー、削除、並び替え、インポート、エクスポートできます。全体トグルが OFF の場合、行単位トグルが ON でも適用されません。

起動時に startupOverrideImportDir 配下の JSON ファイルをすべて読み込みます。

{
  "startupOverrideImportDir": "cookie-auth-proxy/overrides"
}

レスポンス書き換え

API へ送るリクエストでは、Host と Origin を API origin に合わせます。

API から返ってきたレスポンスでは、ローカルプロキシで扱いやすいように次の値を書き換えます。

• Set-Cookie の Domain
• HTTP ローカル実行時の Secure
• HTTP ローカル実行時の SameSite=None
• Location
• Content-Location
• Refresh
• テキスト系レスポンス Body 内の API origin

外部認証サービスなど、Location を API origin から localhost へ通常書き換えしたくないパスでは preserveLocationHeaderPatterns を使います。

{
  "preserveLocationHeaderPatterns": [
    "^/auth(?:/|$)"
  ]
}

さらに、そのまま維持した Location ヘッダ内のクエリパラメータだけを書き換えたい場合は locationHeaderQueryOverrides を使います。認証ミドルウェアやアプリ実装によって必要なパラメータ名は変わるため、プロジェクト側の仕様に合わせて設定してください。

{
  "preserveLocationHeaderPatterns": [
    "^/auth(?:/|$)"
  ],
  "locationHeaderQueryOverrides": [
    {
      "pathPattern": "^/auth(?:/|$)",
      "locationPattern": "^https://login\\.invalid/",
      "queryParams": {
        "redirect_uri": "{publicOrigin}/auth/callback"
      }
    }
  ]
}

使えるテンプレート変数は {publicOrigin}、{apiOrigin}、{clientOrigin} です。

Open Server App

管理画面の Open Server App ボタンは、現在の API Origin と serverAppPath を組み合わせて別タブで開きます。

{
  "serverAppPath": "/dashboard"
}

serverAppPath は CLI や環境変数でも上書きできます。

cookie-auth-proxy --server-app-path /dashboard

VSCode

VSCode の task や launch から起動する場合は、client app のプロジェクトルートに .vscode/tasks.json と .vscode/launch.json を置く構成を想定しています。

npm package として導入している場合、プロキシ起動 task は次のような形にできます。

{
  "label": "cookie-auth-proxy: start",
  "type": "npm",
  "script": "cookie-auth-proxy",
  "isBackground": true,
  "problemMatcher": []
}

Chrome デバッグ構成では url を管理画面にしておくと、起動後に Open App からプロキシ経由のアプリを開けます。

{
  "name": "Debug Cookie Auth Proxy Admin",
  "type": "chrome",
  "request": "launch",
  "url": "http://localhost:4301",
  "webRoot": "${workspaceFolder}",
  "preLaunchTask": "cookie-auth-proxy: start"
}

client app 側のブレークポイントを使う場合は、client dev server の起動 task と組み合わせてください。

セキュリティメモ

このツールはローカル開発用です。公開サーバとして使うことは想定していません。

おすすめ:

• adminHost と listenHost は基本的に localhost のまま使う
• 管理APIはCORSを許可しない。ブラウザのcross-site管理リクエストも拒否する
• 管理APIは起動プロセスごとのCSRFトークンを要求する
• API向けリクエストも、ブラウザのcross-siteリクエストらしいものは拒否する
• 実 API Cookie を設定ファイルや共有リポジトリにコミットしない
• 履歴表示や履歴からのStub作成では、認証系ヘッダをマスクまたは除外する
• apiOriginAllowedPatterns で誤接続先を制限する
• テスト期間中の注意事項は adminNotice に表示する
• スタブと Override は更新系 API を誤って実行しないための退避策としても使う
• サンプルの origin には .invalid など実在しない予約用途の値を使う
• スタブ、Override、設定ファイル内の正規表現は信頼できるものだけ使う

Cookie のセッション期限が短い場合でも、Cookie 自体は認証情報です。取り扱いはアクセストークンに近いものとして考えてください。

履歴詳細では sensitiveHeaderNames に一致するヘッダ値を *** として表示します。履歴からStubを作る場合、同じヘッダはStubレスポンスヘッダから除外します。必要に応じてプロジェクト固有のヘッダ名を追加してください。

{
  "sensitiveHeaderNames": [
    "authorization",
    "cookie",
    "set-cookie",
    "x-api-key"
  ],
  "sensitiveCookieNames": [
    "sessionId"
  ]
}

正規表現には、明らかに危険なネスト量指定子やバックリファレンスを拒否する軽量ガードを入れています。ただし完全な ReDoS 防止ではありません。チーム共有の import ファイルはコードと同じようにレビューしてください。

管理APIにはメモリ保護用のBody上限があります。APIリクエストBodyは Content-Length が無い場合、または maxRequestBodyInspectionBytes を超える場合、Stub/Override条件判定用のBody解析だけをスキップし、リクエスト自体はAPIへ転送します。

レスポンスBodyのOrigin書き換えとJSON Overrideは maxResponseBodyRewriteBytes 以下の場合だけ実行します。上限を超えた場合、ヘッダ書き換えは維持しつつBodyは未加工のままストリーミングします。履歴には body passthrough や override skipped として表示します。

履歴に保存するレスポンスBodyにも表示用の上限があります。必要に応じて maxAdminBodyBytes、maxRequestBodyInspectionBytes、maxResponseBodyRewriteBytes、maxHistoryBodyBytes を調整してください。

開発メモ / Development Note

このプロジェクトは AI コーディング支援ツールを利用して開発されています。変更内容はメンテナが確認し、保守します。

This project is developed with assistance from AI coding tools. Changes are reviewed and maintained by the project maintainer.

License

MIT