feat(pairing): add receiver-bound one-time links

docs/cli-reference.md

@@ -479,6 +479,20 @@ reply-URI destinations, and invocations without `--host` are rejected before
 reading the configuration or starting SSH. Omitting the pair preserves the
 existing default SSH behavior.
 
+### One-time pairing links (v1.3 candidate)
+
+Both endpoints need `pairing-offer-v1` and the existing Unix Python 3.11+ relay extra. These are candidate commands, not published v1.3 support:
+
+```sh
+session-peer device rotation-status --state /private/client-state
+session-peer device offer --state /private/device-state --peer-key CLIENT-CURRENT-64-HEX-KEY --direct PRIVATE-IP:3770 --show-link
+session-peer device pair --state /private/client-state --link --route direct
+session-peer device offer-status --state /private/device-state --offer-id OFFER-UUID
+session-peer device offer-cancel --state /private/device-state --offer-id OFFER-UUID
+```
+
+Creation confirms both identities and shows the link only on the owner terminal. `--link` takes no value: input is hidden and bounded; the client independently confirms the receiver's current fingerprint before trust staging or networking. No terminal means refusal, not echo fallback or automatic consent. Never put a link in argv, browser history, logs or issue reports. Guided setup offers link/private-file choices; existing file commands remain supported. Cancellation affects only that offer's pending trust, not completed pairing; use explicit peer revocation after completion. Expired cold links are refused; only exact saved context can reconcile an already-consumed authenticated result. Pairing never replaces the receiving target policy or native approval. See the [paired-device guide](paired-devices.md) for key-rotation restrictions, expiry, quotas, interruption and the threat model.
+
 ### Updating
 
 For package-managed installs, use the same manager that installed the command:

docs/i18n-manifest.json

@@ -15,15 +15,15 @@
     "docs/ai-assistant-guide.md": "9624ec96b92fb688fae3be3c94cb3564c77985091be451fbf1f056a1af9b9d9c",
     "docs/antigravity.md": "f2b5122a0ce6e6fb5bd4d8ed50ce2c8bd2dc9c98ec8ce328405cf7c2cd24229d",
     "docs/architecture/agent-transports.md": "01a4e3942e87acb476595859f2e37f9653ea1e3bc19ebc68dced1adf20a6966f",
-    "docs/cli-reference.md": "5d4a52e5eda0e3287e45fd1d8bd852acee76af9917e759431efd84d247a73b0e",
+    "docs/cli-reference.md": "7b1e6e8d12069b45e12b65ebc02e2317f42ba0fe2b27e386b70d4616cd21c581",
     "docs/compatibility-v1.md": "7e551aad37a369faff7e370728376763efb54c2c9e9cfd8556a0c19aabc3d103",
     "docs/contracts/handoff-v1.md": "46a953010c49214bd8f969412f26713384fbe09a0ba78ebf0fef75da40d0d889",
     "docs/diagnostics.md": "0949e53612eeab2cd7c7bbda498e14d71e9cb1b1189aa7722030cb8702cd8481",
     "docs/download-metrics.md": "ded60e7b84d14ce779f8d639516b4e390358a06ef76b677dc9c1f997fb626a9f",
     "docs/handoff-runtime.md": "80800abed85d4af1a2e2001448b39f6cf02ae12912cde0fde90c6863124e5220",
     "docs/mcp.md": "a64010cdd63f2cde6a0052450bed2d05faa0f19c93c76143cb0d585d36f8ff62",
     "docs/multi-home-list.md": "f8d8e3adf727e4842ea7c4d45e8f6523b11d0513bf2509d4d1204645875e6489",
-    "docs/paired-devices.md": "44c70f99d3f8f8ff9f6f86d128913ada69f4cc4e794c724cfc214f7f8ea78f20",
+    "docs/paired-devices.md": "fc174600f246292b3b877a2321e1a21861ce6e5fa5c586f56c89a0bd7181907b",
     "docs/relay-auth.md": "e6da5291ce6a9da31e79e66ceeff7e9fef7e95046359acbf04d708c96ffab62f",
     "docs/relay-development-plan.md": "0abf750b36275ea4e467a0020e560277f08689f2d574aed7674133705383b1ff",
     "docs/relay-edge-policy.md": "c1c7f7a1c4303943c78ca334dab4034f66c0c272e40c007d07c3da2a496155eb",

docs/ja/cli-reference.md

@@ -434,6 +434,20 @@ session-peer doctor --host worker --ssh-config '/home/alice/SSH Profiles/work.co
 
 環境変数、MCP リクエスト、ReplyTo アドレス、保存済みプリセットからは選択できません。Windows、`setup`、ペアリング済みデバイス経路、プリセットとの併用、返信 URI 宛先、`--host` のない呼び出しは、設定を読む前および SSH 起動前に拒否します。両フラグを省略した場合は従来の既定 SSH 動作を維持します。
 
+### ワンタイムペアリングリンク（v1.3候補）
+
+両端で `pairing-offer-v1` と既存のUnix Python 3.11+ relay追加依存関係が必要です。以下は候補コマンドであり、公開済みのv1.3対応ではありません。
+
+```sh
+session-peer device rotation-status --state /private/client-state
+session-peer device offer --state /private/device-state --peer-key CLIENT-CURRENT-64-HEX-KEY --direct PRIVATE-IP:3770 --show-link
+session-peer device pair --state /private/client-state --link --route direct
+session-peer device offer-status --state /private/device-state --offer-id OFFER-UUID
+session-peer device offer-cancel --state /private/device-state --offer-id OFFER-UUID
+```
+
+作成時に双方のIDを確認し、所有者の端末だけにリンクを表示します。`--link` に値は付けません。上限付きの非表示入力を使い、クライアントが独立して確認した受信端末の現在の鍵のフィンガープリントを入力してから信頼登録・接続を行います。端末がなければ入力表示や自動承認に切り替えず拒否します。リンクを引数、ブラウザー履歴、ログ、Issueに残さないでください。設定ガイドはリンク・非公開ファイルを選択でき、既存のファイル用コマンドも維持します。取消しはそのオファーの保留信頼だけに適用され、完了済みペアリングには明示的な失効操作が必要です。履歴のない期限切れリンクは拒否し、完全一致する保存記録がある場合だけ完了済みの認証結果を確認できます。ペアリングは受信対象のポリシーやネイティブCLIの承認の代わりにはなりません。鍵更新の制限、期限、回数制限、中断、脅威モデルは[ペアリングガイド](paired-devices.md)を参照してください。
+
 <a id="updating"></a>
 ### 更新
 

docs/ja/paired-devices.md

@@ -50,6 +50,56 @@ session-peer setup --mode relay --interactive --role client --no-browser
 
 受信側はデバイス認証前の直接接続を最大 16 本、Relay に attach された接続を最大 2 本まで許可し、認証済み接続 8 本とは別に管理します。TLS はネットワークとスケジューリングの遅延を含めて 2 秒以内に完了する必要があります。TLS 後、クライアント証明書のない初期ペアリング接続には、単一のペアリング要求と応答を完了するためにさらに 2 秒が与えられます。認証済み要求の期限は 45 秒のままです。この短い期限は正常な遅い接続も拒否する場合があります。アイドル状態または TLS が遅い直接ソケット 8 本があっても、ペアリング済みの直接接続と Relay 要求を受け付ける余地が残ります。ただし、認証前の直接接続枠 16 本がすべて埋まると、ペアリング済みの直接接続も拒否される可能性があり、予約された Relay 枠 2 本も飽和する場合があります。任意のフラッド攻撃に対する可用性は保証されません。超過ソケットや受信側のシャットダウン開始後のソケットには処理タスクを作成しません。集計した入場カウンターは ID を含めずに拒否とクリーンアップ失敗を保持します。明示的に有効化した `receiver_admission` イベントは、固定カウンターと許可リスト内の理由を 1 分に最大 1 回報告します。アプリケーションの自動再試行は有効になりません。
 
+## ワンタイムペアリングリンク（v1.3候補）
+
+以下は開発候補であり、公開済みのv1.3機能ではありません。両端で新しい `pairing-offer-v1` プロトコルが必要です。従来の非公開招待ファイルも引き続き使えます。既存のUnix Python 3.11+とrelay追加依存関係を使用し、Windows対応、仲介サービス、Webページ、公開待受ポートやホステッドサービスは追加しません。
+
+各端末を初期化し、信頼できる経路で公開IDを確認します。`device rotation-status` は安定した端末IDと現在の鍵のフィンガープリントを表示します。鍵の更新後には両者が異なる場合があります。受信対象のポリシーは別途確認してください。ペアリングは全セッションへのアクセス権を付与したり、ネイティブCLIの承認手順を変更したり、エージェントの実行を許可したりするものではありません。
+
+受信端末で自身のIDと接続先クライアントの現在の鍵を明示的に確認し、制御端末にリンクを表示します。
+
+```sh
+session-peer device offer --state /private/device-state \
+  --peer-key CLIENT-CURRENT-64-HEX-KEY --direct PRIVATE-IP:3770 --show-link
+```
+
+長い `session-peer://pair/v1#...` リンクを非公開で渡します。クライアントでは入力内容を表示しない端末プロンプトに入力してください。リンクを `--link` の後や他のコマンド引数に入れないでください。
+
+```sh
+session-peer device pair --state /private/client-state --link --route direct
+session-peer device offer-status --state /private/device-state --offer-id OFFER-UUID
+session-peer device offer-cancel --state /private/device-state --offer-id OFFER-UUID
+```
+
+クライアントは自身の現在の鍵が指定された鍵と一致するかを確認し、候補の受信者IDや経路を表示する前に、独立して確認した現在のフィンガープリントを求めます。一致した場合だけ双方のIDと経路を表示し、最終確認を受けます。未確認の画面表示をコピーするようには誘導しませんが、入力の入手先を証明できるわけではありません。リンク自身のID表記を認証根拠にはしません。信頼登録とネットワーク接続は確認後に行い、受信者も作成時に確認済みクライアントIDをトランザクション内で再検査します。制御端末を利用できない場合、秘密を表示したり自動承認したりせず拒否します。設定ガイドのリンク・非公開ファイル選択も同じ確認手順を使います。自動化には既存のファイル用コマンドを利用できます。
+
+クライアントの安定IDと鍵世代は、完全一致する既存の有効な鍵登録から取得します。新しい鍵ならフィンガープリントと世代0を使用します。既知の保留・旧世代・失効済み鍵を新しい鍵とは扱いません。必要な既存登録がない更新済み受信者・クライアント鍵は、この方式では拒否します。フィンガープリントの入力だけで別の安定IDの権限は作れません。必要に応じて従来の信頼できるファイル・回復手順を使い、秘密鍵や端末状態をコピーしないでください。
+
+### 有効期限、取消し、中断後の確認
+
+オファーには256ビットの秘密値があり、受信端末のシステム時計で10分後に失効します。指定した現在の鍵1つに結び付きます。状態はopen、reserved、consumed、cancelled、expiredです。予約、認証済みの招待別確定、取消し、失効は受信端末のDBで直列化します。別の招待が保留登録を奪ったり、ペアリング済み端末を保留に戻したりすることはできません。取消しはそのオファーの保留信頼だけを除去し、既存の鍵登録や完了したペアリングは失効させません。完了後は該当端末で既存の明示的な `device revoke --peer RECEIVER-OR-CLIENT-PRINCIPAL` を使って信頼を取り消します。
+
+中断した確定結果は、オファーID、保護されたリンク内容のダイジェスト、受信端末ID・鍵、現在のクライアント鍵が一致する保存記録がある場合だけ確認できます。一致する履歴のない期限切れリンクは、接続前に拒否します。期限後の確認は認証済み確定要求で完了済み結果を取得するだけであり、再準備、延長、失効の解除はできません。受信者が結果を削除した後は、そのpeerがペアリング済みでも元のオファーの確定を確認できません。この実装には過去の結果再構成や期限後の修復コマンドはありません。双方の状態を保持し、運用者と明示的な回復計画を立ててください。無闇な鍵失効は回復を難しくする場合があります。ネイティブメッセージの送信や自動再送は行いません。
+
+作成は毎分5件、有効なオファーは8件までです。準備要求は全体で毎分32回、各オファーで毎分8回に永続的に制限し、失敗した推測も数えます。全体の制限は従来の非公開ファイル方式にも適用します。満杯の枠は拒否された試行で更新・延長しません。未知のIDごとに状態を作りません。終了結果は7日間保持し、オファー数の上限は1,024件です。削除可能なメタデータと招待行は一緒に整理します。未認証の負荷を含め、制限で正当なペアリングも一時的に拒否され得ます。ペアリング済みのネイティブ要求にはこの準備枠を使いません。これはリソース制限であり、IDや配送の証拠ではありません。受信端末の時計が信頼できることを前提とします。信頼変更の直前に期限を検査しますが、永続化の完了は後になる場合があります。クライアントの時計ずれで早く拒否されることもあります。
+
+クライアントの完全一致処理記録も1,024件に制限し、暗黙には追い出しません。上限でも既存の一致する記録は再確認できます。初期実装には自動削除も明示的なクライアント記録整理コマンドもなく、受信結果とは異なり7日後も残るため、新しいリンクでのペアリングが将来拒否され得ます。新規記録は `pairing_intent_capacity` で拒否し、結果確認の根拠を残します。更新前のファイル方式の保留登録は、1つの有効な招待、証明書、有効鍵、有効期限から所有関係を証明できる場合だけ引き継ぎます。曖昧または証明不能な有効保留状態は保持して拒否し、別の招待に割り当てず運用者の確認を求めます。確実に失効した保留信頼はトランザクション内で整理できますが、鍵登録は保持し、ペアリング済み・失効済みpeerは削除しません。別の有効な招待は保留予約を引き継げないため、ファイルを変える場合は失効まで待つ必要があり得ます。拒否を回避するために端末DBを削除したり元のネイティブメッセージを再送したりしないでください。
+
+設定ガイドでの作成が確認後に中断した場合、非公開の設定記録にはDB作成前から公開オファーIDが残ります。未作成が確定した拒否は再試行できます。不明な場合は以下の明示的な状態確認・取消しを使います。ID指定を省略すれば保存済みIDを使います。履歴がないことは未作成の証拠ではなく、結果が削除された可能性もあるためunknownです。状態確認では保留を続けます。履歴が見つからない保存済みIDを明示的に取り消しても、終了するのはローカルの待機だけで、遠隔の権限やペアリング済みの信頼を取り消す処理は行いません。返されたIDは次の明示的に確認された作成まで現行記録に残りますが、永続監査ログではありません。既知の有効オファーは明示的に取り消すまで保留、保持された終端結果なら意図を解消します。別のIDで解除はしません。手動表示で捕捉した失敗も状態確認・取消し用の公開IDを返しますが、プロセス障害後に残るのは設定ガイドの記録だけです。新しいオファーの自動作成や秘密値の再表示は行いません。
+
+復元・隔離状態では期限整理、削除、回数記録の前に回復フェンスを適用します。そのオファー状態は過去の診断証拠であり現在の権限ではなく、設定保留を解消できません。フェンス中のペアリング変更・取消しは拒否します。回復は別の明示的な手順です。
+
+```sh
+session-peer setup --mode relay --state /private/device-state --action offer-status --offer-id OFFER-UUID --apply
+session-peer setup --mode relay --state /private/device-state --action offer-cancel --offer-id OFFER-UUID --apply
+```
+
+### 脅威モデルと秘密値の扱い
+
+専用の接続仲介サーバーや短い数字コードは使いません。サイズを制限した独自URIには既存の招待と指定公開鍵が入り、ブラウザーで開いたり取得したりせず、OSのURLハンドラーも登録しません。リンクは認証情報です。URIの `#` 以降に含まれていても、端末の録画、クリップボードやブラウザーの履歴に残ります。アドレスバー、ログ、解析ツール、信頼できない参加者のいる会話、Issueに貼らないでください。通常のJSON、診断、設定ジャーナルにはリンクや生の秘密値を入れません。非公開の処理記録に残せるのは保護されたダイジェストと公開ID情報だけです。
+
+既存の証明書固定によるエンドツーエンドTLSとクライアント秘密鍵の所有証明は引き続き必須です。侵害された中間者は接続メタデータの観測、遅延、再生、サービス拒否ができますが、端末の秘密鍵やエージェントメッセージの平文は受け取りません。受信証明書の置換は独立したフィンガープリント確認で拒否されます。正規リンクが漏れても別のクライアント鍵を承認できません。指定された公開証明書を知る者は予約による妨害を試みられますが、所有証明やネイティブ対象の権限は得られません。端末・秘密鍵またはID確認経路の侵害は保護範囲外です。ホスト側の可用性、消費・ACK、exactly-onceについて新しい保証はしません。
+
 ## 接続失敗の診断と安全な接続再試行
 
 `no_authenticated_route` は `retryAllowed:false` と `consumptionConfirmed:false` を維持します。`routeFailures` は経路ごとの最後の `stage`、許可リスト内の `reason`、`attempts` を示します。限定された `attemptHistory` は各試行の段階・理由・`elapsedMs` を保持し、HTTP 拒否には `httpStatus`、WebSocket の切断には `closeCode` が含まれる場合があります。制御、入場、アップグレード、attach、ピア TLS、probe の失敗を区別し、URL・認証情報・生の例外・メッセージ本文は記録しません。2 回目で成功した場合は `setupDegraded:true`、`setupAttempts:2`、`setupFailureHistory` が付き、正常な安定性試験の合格とは見なしません。