Clawnetのリファクタリング：プロトコルと認証の統合

複数のプロトコルを並行してメンテナンスするのは、開発者にとって大きな負担です。特に、認証フローが分散していたり、デバイスのアイデンティティが重複していたりすると、デバッグや機能拡張の難易度が急激に上がってしまいます。

リモートノードでの承認リクエストが、肝心の操作画面ではなく実行先のサーバー側に表示されてしまうといった問題も、開発の現場ではよくある悩みです。こうした課題を解決するために、Clawnetではプロトコルと認証の統合（Clawnet refactor）を進めています。

必要なもの

このリファクタリング後の環境を利用するために必要な要素は以下の通りです。

• Gateway: プロトコルを統合し、承認を管理する中心コンポーネント
• Role: node（実行環境）または operator（操作 UI）のいずれか
• Scope: operator.read, operator.write, operator.admin などの権限定義
• deviceId: デバイスの公開鍵から生成される一意の識別子

クイックスタート

新しい Clawnet プロトコルでの接続とペアリングは、以下の 4 ステップで完了します。

1. 未認証状態で接続する

クライアントはまず、deviceId、displayName、希望する role を指定して Gateway に接続します。

2. ペアリングリクエストの作成

Gateway は接続を受け取ると、そのデバイス専用の pairing request を作成します。

3. オペレーターによる承認

operator ロールを持つユーザーの UI に承認プロンプトが表示されます。ここで承認されると、Gateway はデバイスの公開鍵に紐付いた認証情報を発行します。

4. 認証済み状態で再接続

クライアントは発行されたトークンを保存し、次回から認証済みとして再接続します。この際、デバイス鍵ペアによる署名検証が行われるため、トークンの使い回しを防ぐことができます。

トラブルシューティング

設計上、想定される問題と解決策をまとめました。

• 同じデバイスが UI 上で 2 つ表示される

  • 原因：macOS app が operator と node の両方のロールで個別に接続している可能性があります。
  • 解決策：両方の接続で同じ deviceId を使用してください。Gateway がこれらを 1 つの「インスタンス」として統合し、適切なバッジを表示します。

• リモートノードへのコマンドが実行できない

  • 原因：operator ロールに適切な scope（例：operator.write）が付与されていない、または承認がタイムアウト（デフォルト 60 秒）した可能性があります。
  • 解決策：Gateway のログを確認し、operator.approvals スコープを持つクライアントが正しく承認を処理しているか確認してください。

• TLS 接続に失敗する

  • 原因：TLS pinning（証明書の固定）の設定に不整合がある可能性があります。
  • 解決策：Discovery TXT レコードで広告されているフィンガープリントと、クライアント側で検証しているフィンガープリントが一致しているか確認してください。

• サイレント承認（SSH 経由など）が機能しない

  • 原因：ローカルループバック接続以外で、SSH チャレンジなどの条件を満たしていない可能性があります。
  • 解決策：セキュリティ保護のため、自動承認はログに記録されます。Gateway の監査ログを確認し、条件が正しく適用されているか確認してください。

最後に

このリファクタリングにより、プロトコルの重複が解消され、よりセキュアで一貫性のある開発が可能になります。具体的な実装の詳細や、既存の Bridge プロトコルからの移行スケジュールについては、AI Setup Assistant で確認してください。

次のステップ

• src/gateway/server/ws-connection/message-handler.ts: 新しい WebSocket メッセージハンドラーの構成
• docs/gateway/protocol.md: 統合プロトコルの詳細仕様