リモートセットアップ (WSS)

ワークステーション上の zerocode を別のマシン（Raspberry Pi、ホームサーバー、VPS など）で稼働しているデーモンに接続します。

3つのトポロジー（直接接続、デーモンからリレー、クライアントからリレー経由）すべてを対象とした、設定項目ごとの完全なガイドについては、セキュアトランスポート（エンドツーエンド設定）を参照してください。

WSS プレーンは相互認証（mTLS）です。 すべてのクライアントが証明書を提示し、サーバーのみの認証や未認証の経路はありません。クライアント証明書を取得する簡単な方法は、登録（以下）です。証明書を手動で管理する必要はありません。自分で発行する場合は、後述の「ワークステーション上で」の持ち込み手順を参照してください。--tls-skip-verify は、自己署名されたデーモン証明書に対する サーバー 証明書の検証を緩和するだけであり、いずれの場合もクライアント証明書は必要です。

登録（推奨）

証明書なしのクライアントを初めて対話的に接続すると、zerocode が自動的に登録します:

zerocode --connect wss://<remote-host>:9781

デーモンの一度限りの ペアリングコード（起動時にデーモンのログに出力されます）の入力を求め、デーモンのコンソールで照合する 短い認証文字列 (SAS) を表示します（これにより中間者 CA を検出できます）。その後、クライアント証明書を取得し、<config-dir>/tls 配下にキャッシュします。以降の実行ではゼロ設定で、証明書は有効期間の約50%で自動更新されます。非対話的に登録するには zerocode --enroll --connect wss://<remote-host>:9781 を使用します。

証明書を持たないクライアントが登録せずに WSS プレーンへ接続した場合、次に取るべきアクションが明確な「先に登録してください」というメッセージが表示され（デーモンは拒否した未移行クライアントをログに記録します）、サイレントハングにはなりません。失効済みの証明書はハンドシェイク時に拒否されます（発行済み証明書台帳に基づくため）。そのため、紛失したデバイスを失効させると、次回の接続から反映されます。

allow_unpaired_enrollment in the [enroll] section is reserved for a future code-less migration flow. This release rejects any non-empty value at daemon startup; leave it empty and use the printed pairing code.

リモートホスト（デーモン側）にて

1. WSS を有効にします。 Config ペイン（またはゲートウェイ / zeroclaw config set）から wss の設定を行います：

   [wss]
   enabled = true
   

   cert_path / key_path は空のまま（デフォルト）にします。デーモンは初回起動時に <data_dir>/tls/ 配下へ独自の CA とサーバー証明書を自動生成するため、自分で openssl を実行する必要はありません。独自のサーバー証明書を使用する場合にのみ設定し、いずれの場合も絶対パスを使用してください。設定では ~ は展開されません。

2. ファイアウォールのポートを開く:

   sh

   sudo ufw allow 9781/tcp
   

   デフォルトの WSS ポートは 9781 です。[wss] セクションの port = <number> で変更できます。

3. デーモンを起動 (または再起動) する:

   sh

   zeroclaw daemon
   

   0.0.0.0:9781 で WSS リスナーが開始されたことを確認するログ行が表示されるはずです。

ワークステーション上で（zerocode 側）

上記の登録が、クライアント証明書を取得する最も迅速な方法です。対話形式で登録する代わりに、自分で用意したクライアント証明書を使用する場合:

1. デーモンホストでクライアント証明書を発行（デーモンの mTLS CA から）：

   zeroclaw security issue-client-cert --name my-laptop --out-dir /tmp/my-laptop-tls
   

   これにより、ca.crt、client.crt、client.key が --out-dir に書き込まれます。その名前の既存の証明書を上書きするには、--force を追加します。

2. ワークステーションの <config-dir>/tls/ に 3 つのファイルをコピーする（その後、zerocode --connect wss://<remote-ip>:9781 が自動的にそれらを見つけます）、またはそれらを明示的に指定します:

   sh

   zerocode --connect wss://<remote-ip>:9781 \
     --tls-ca-cert     /path/ca.crt \
     --tls-client-cert /path/client.crt \
     --tls-client-key  /path/client.key
   

   ca.crt はデーモンのサーバー証明書に署名したものと同じ CA なので、サーバーも検証されます。--tls-ca-cert を省略し、ピン留めしていない自己署名のデーモン証明書を使用する場合にのみ、--tls-skip-verify が必要です。

以上です。接続が切断された場合、zerocode は自動的に再接続します。

設定リファレンス

wssセクション: