Clawnetリファクタリング（プロトコル＋認証統一）

目的

以下を網羅する単一の厳密なドキュメント:

  • 現状: プロトコル、フロー、信頼境界。
  • 課題: 承認、マルチホップルーティング、UI重複。
  • 提案する新しい状態: 1つのプロトコル、スコープ付きロール、統一認証/ペアリング、TLSピンニング。
  • アイデンティティモデル: 安定ID＋かわいいスラッグ。
  • 移行計画、リスク、未解決の問題。

目標

  • すべてのクライアント（macアプリ、CLI、iOS、Android、ヘッドレスノード）に1つのプロトコル。
  • すべてのネットワーク参加者を認証＋ペアリング。
  • ロールの明確化: ノード vs オペレーター。
  • 承認をユーザーがいる場所に中央ルーティング。
  • すべてのリモートトラフィックにTLS暗号化＋オプションのピンニング。
  • 最小限のコード重複。
  • 1台のマシンが1回だけ表示される（UI/ノードの重複エントリなし）。

現状

2つのプロトコル

  1. Gateway WebSocket（制御プレーン） — 完全なAPIサーフェス。デフォルトバインドはループバック。認証はトークン/パスワード。TLSピンニングなし。
  2. Bridge（ノードトランスポート） — 狭い許可リストサーフェス、ノードアイデンティティ＋ペアリング。TCP上のJSONL。オプションのTLS＋証明書フィンガープリントピンニング。

課題

  • 2つのプロトコルスタックの保守。
  • リモートノードでの承認: プロンプトがユーザーのいる場所ではなくノードホストに表示。
  • TLSピンニングがBridgeにのみ存在。
  • アイデンティティの重複: 同じマシンが複数インスタンスとして表示。
  • 曖昧なロール。

提案する新しい状態（Clawnet）

1つのプロトコル、2つのロール

ロール＋スコープ付きの単一WSプロトコル。

  • ロール: node（機能ホスト）
  • ロール: operator（制御プレーン）
  • オペレーター用オプションスコープ: operator.read、operator.write、operator.admin

統一認証＋ペアリング

すべてのクライアントがdeviceId、displayName、role＋scope＋caps＋commandsを提供。

統一ペアリングフロー:

  1. クライアントが未認証で接続。
  2. Gatewayがペアリングリクエストを作成。
  3. オペレーターUIがプロンプトを表示。承認/拒否。
  4. Gatewayがデバイス公開鍵、ロール、スコープ、機能にバインドされた認証情報を発行。
  5. クライアントがトークンを保存し、認証済みで再接続。

TLSの全面適用

既存のBridge TLSランタイム＋フィンガープリントピンニングをWSに適用。

承認の再設計（中央集約）

承認をGatewayホスティングに移行し、UIをオペレータークライアントに配信。すべてのオペレーターにブロードキャストし、最初の解決が優先。

アイデンティティ＋スラッグ

  • 安定ID: キーペアフィンガープリント（公開鍵ハッシュ）。
  • かわいいスラッグ（ロブスターテーマ）: 人間向けラベルのみ。例: scarlet-claw、saltwave、mantis-pinch。

移行戦略

フェーズ0〜6: ドキュメント＋整合 → WSへのロール/スコープ追加 → Bridge互換 → 中央承認 → TLS統一 → Bridge廃止 → デバイスバウンド認証。

まとめ

  • 現状: WS制御プレーン＋Bridgeノードトランスポート。
  • 課題: 承認＋重複＋2つのスタック。
  • 提案: 明示的なロール＋スコープ付き1つのWSプロトコル、統一ペアリング＋TLSピンニング、Gatewayホスト承認、安定デバイスID＋かわいいスラッグ。
  • 結果: シンプルなUX、強化されたセキュリティ、重複削減、モバイルルーティングの改善。
次へ
Overview
arrow_forward