localhost UI
klaus ui で起動する Web UI。フローの実行(ライブ進捗付き)と履歴の閲覧ができるランナー + ビューアであり、フロー定義の編集はエディタで行う(git-native 思想)。実行・アサーション・履歴のロジックはすべて CLI と同じ src/core を使う。
起動
bash
klaus ui [-p <n>] [-H <host>] [--no-open]- 起動するとトークン付き URL(
http://127.0.0.1:<port>/?token=…)が表示され、ブラウザが自動で開く - UI アセット(
dist/ui)が未ビルドの場合は 503 で案内が出る。開発リポジトリではpnpm build:allを先に実行すること(npm インストール版にはビルド済みで同梱される) - フロー一覧・履歴はサーバーを起動した cwd を基準に読まれる。検証したいプロジェクトのルートで起動すること
画面
- 単発 API 実行(デフォルト画面): フローを介さず1件のリクエストをその場で実行するタブ。method / URL / ヘッダー / クエリパラメータ / ボディをフォームで編集し、選択中の環境で
を展開して実行する。結果はステータス・所要時間・レスポンスヘッダー・ボディで表示され、レスポンスボディから JSONPath で値を抽出して選択中の環境に保存できる(保存はキー単位のマージで、他のキーは変更しない) - フロー一覧(サイドバー): cwd 配下のフロー YAML を一覧表示。パースエラーのあるファイルはエラーアイコン + 理由付きで表示され実行不可。フローを選択すると実行ビューに切り替わる。上部の環境セレクタで
--env相当の切替、実行ボタンで実行開始 - 実行ビュー: ステップが running → pass/fail にライブで遷移(SSE 配信)。「Step n / m」の全体進捗、失敗ステップは自動展開してリクエスト / レスポンス詳細(JSON)を表示、成功ステップはデフォルト折り畳み。完了時にサマリー表示
- 環境エディタ: 環境セレクタ横の編集ボタンから開閉し、選択中の環境の key-value をテーブルで編集できる。保存すると YAML 上の既存コメントを保持したまま該当ファイルへ書き戻す
- 履歴ブラウザ:
.klaus/history/*.jsonlを新しい順に表示。run 単位でグルーピングされ、行クリックでステップ詳細にドリルダウン。フローでのフィルタと「さらに読み込む」ページング
セキュリティモデル
ローカル専用の設計であり、リバースプロキシ等で外部公開してはならない。
| 対策 | 内容 |
|---|---|
| バインド | 既定は 127.0.0.1。-H/--host(または klaus.config.yaml の ui.host)で変更可能 |
| 認証トークン | 起動時に crypto.randomBytes(32) で生成。比較はタイミングセーフ |
| 初回アクセス | GET /?token=… の検証成功で klaus_token Cookie(SameSite=Strict / HttpOnly)を発行 |
| API 認証 | 全 /api/* で X-Klaus-Token ヘッダー必須(不一致 401) |
| CSRF | POST/PUT/DELETE はさらに Cookie 一致 + Origin ヘッダーが存在する場合は同一オリジンのみ許可 |
| DNS rebinding | 全リクエストで Host が 127.0.0.1:<port> / localhost:<port> 以外なら 403(--host に非ループバックアドレスを明示指定した場合は、ポート一致のみの検証に緩和) |
| CORS | ヘッダーを一切付けない(同一オリジン配信のみ) |
| path traversal | ファイルパスを受ける API・静的配信で cwd / dist/ui 外への解決を 403 で拒否 |
上記の認証トークンは、起動時に stdout へ表示されるだけでなく、ブラウザ自動起動コマンド(open / xdg-open / cmd /c start)の引数としても渡される。共有のマルチユーザーホストでは、この引数が他のローカルユーザーからプロセス一覧(ps や /proc/<pid>/cmdline)経由で読める可能性がある。該当する環境では --no-open を指定してブラウザの自動起動を避け、表示された URL を自分で開くこと。詳細は SECURITY.md を参照。
HTTP API の仕様と内部構成は ../dev/ui-api.md を参照。