ペアリング・再ペアリング・マシンの共有

Terminull を実行しているマシンには、ビーコン ID と公開鍵からなる恒久的な識別情報があり、それを含む terminull://pair QR コードが表示されます。QR コードは2 種類あり、スキャンの結果はどちらの QR かと誰がスキャンしたかで決まります。このセクションはその違いに尽きます。一方の QR はマシンを譲り渡し、もう一方は貸し出します。

ペアリング — マシンを初めて接続する

macOS ではセットアップウィザードの最終ページに QR が表示され、メニューバーの「QR でデバイスを追加」からいつでも呼び出せます。ヘッドレスの Linux では terminull サービスがペアリング URL をテキストで出力します（SSH 越しではターミナルの QR は読み取れないため）。それをアプリに貼り付けるか、Mac のウィンドウにドラッグしてください。

Windows ではインストーラーの最後のステップに QR が表示され、トレイアイコンの Pair a phone (QR) からいつでも呼び出せます。任意のターミナルで terminull qr を実行しても表示できます。

アプリでスキャンすると、そのマシンはあなたのアカウントにひも付けられ、あなたがオーナーになります。アプリはビーコン ID と公開鍵を登録し、マシンは恒久的な認証トークンを一度取得してオンラインになります。QR に含まれるのはビーコン ID、マシンの公開鍵、一時的な鍵交換用の鍵、ホームリレーのアドレス、そして 1 回限りのクレームコードだけです。あなたのコードやセッション、認証情報が含まれることはありません。

ヘッドレス環境で QR を取得する

インストール直後のサービスは、未ペアリングの状態で初めて起動したときに自前の出力へペアリング QR を表示し、いずれかのデバイスがひも付けを済ませると表示をやめます。その後に改めて QR が必要なときは、稼働中のサービスに要求します。

terminull-admin qr        # print a QR (needs the service running)
terminull-admin qr --url  # just the pairing link, on stdout

QR が描画されるのはサービス側の出力であり、コマンドを打った端末ではありません。手元の端末にはリンクが返ってきます。systemd 環境ではその出力はジャーナルなので、そちらで表示させます。

journalctl --user -u terminull --no-pager -o cat -n 40

-o cat は省略できません。付けないと journald が各行の先頭にタイムスタンプとユニット名を付けるため、コードの各行が横にずれます。ぱっと見は正しく見えても読み取れません。

SSH 越しでは画像よりリンクの方が扱いやすいことがほとんどです。terminull-admin qr --url は貼り付け可能な URL をそのまま出力します。自前のレンダラーに渡せばジャーナルを介さずに済みます: terminull-admin qr --url | qrencode -t ANSI

つまずきやすい点が 2 つあります。インストーラーはこのコマンドをサービス自身の環境に置くため、シェルから見つからない場合はフルパス ~/.local/share/terminull/venv/bin/terminull-admin を使ってください。またこのコマンドはローカルソケット経由で稼働中のサービスと通信するので、「terminull is not running」は文字どおりの意味です。systemctl --user start terminull で起動してからやり直してください。出力されたものはオーナー QR として、前述の注意をすべて守って扱ってください。

再ペアリング — 同じアカウントでもう一度スキャンする

すでにそのマシンを所有しているアカウントでオーナー QR を再度スキャンするのは再ひも付けであり、何度繰り返しても安全です。保存されている公開鍵と名前が更新され、トークン取得の受付が再度開きます。失われるものはありません。セッションは電話ではなくマシン自身にあるため、その後もすべて残っています。

自分の 2 台目のデバイスを追加するとき（iPhone に加えて iPad を使うなど）、アプリを再インストールしたとき、完全アンインストールでマシンの識別情報をリセットしたときに再ペアリングしてください。最後のケースでは鍵が再生成されますが、再ひも付けが書き戻すのはまさにその鍵です。

オーナー QR は秘密情報です。別のアカウントがスキャンした場合、それは参加ではなく所有権の移転です。サーバーは保留として記録し、マシンが次にポーリングした時点で有効になり、マシンはあなたのアカウントから外れます。クレームコードを持っていること自体がマシンへの物理的アクセスの証明であり、だからこそ権限として扱われます。所有権を手放さずに他の人を招き入れたい場合は、下記の共有 QR を使ってください。

アプリでアカウントを開き、対象のマシンを見つけて横の QR アイコンをタップします。マシンは2 分間有効な新しいコードを生成してサーバーに登録し、残り時間のカウントダウン付きで共有 QR を表示します。（背後にアカウントを持たない LAN 専用マシンでは共有は利用できません。）

別のアカウントがスキャンすると、そのアカウントはメンバーとして参加します。マシンが相手の一覧に表示され、プッシュ通知が届き、そのマシンでセッションを実行できます。所有権は変わらず、マシンの認証トークンにも影響しません。すでに参加済みのメンバーは、あなたが新しく共有を開かなくてもいつでも再スキャンできます。

有効期限は表示だけでなくサーバー側で強制されます。一致するコードのないスキャンは「このマシンは現在共有されていません」として拒否され、期限切れのものは「この共有コードは期限切れです。オーナーに新しい QR を依頼してください」となります。そのため、古い共有 QR のスクリーンショットは無意味です。共有を恒久的な許可ではなく、意図的で一時的な行為にしておくことが狙いです。

今見ているのはどちらの QR か

	オーナー QR	共有 QR
見つかる場所	セットアップウィザード、またはメニューバー →「QR でデバイスを追加」	アプリ → アカウント → マシン横の QR アイコン
有効な期間	マシンの識別情報がリセットされるまで	2 分間（カウントダウン付き）
自分のアカウントでスキャンした場合	再ペアリングされる — 何度でも安全	特に変化なし。すでに追加済み
他人のアカウントでスキャンされた場合	マシンの所有権が移る	メンバーとして参加。オーナーはあなたのまま
スクリーンショットしても安全か	いいえ — パスワードと同じ扱いを	2 分が過ぎれば無害

LAN 専用ペアリング

pairing_mode = "lan" を設定したマシンは、完全にローカルネットワーク内でペアリングします。QR は LAN 専用として印が付き、アプリはアカウントへのひも付けを省略し、どの段階でもサーバーは介在しません。マシンには同じネットワークからのみ接続でき、プッシュ通知やクラウド AI アシストは利用できません。共有もできません。共有はサーバーを介する仕組みであり、このモードにはサーバーが存在しないためです。