Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

Spec for the end-to-end encrypted Cloudflare relay, accounts and multiple computers

leepokai025f6d28caf2
diff --git a/CLAUDE.md b/CLAUDE.md
index 8368f7e2..f7b1bfed 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,9 +21,10 @@ Bot-based remote for coding agents: persistent named bots on your computer, mess
- **Thread ≠ session**: a bot is one endless transcript (SQLite `entries`, ordered by `seq`); the ACP session underneath is resumed with `session/load` or replaced by *New session*.
- **Chat shows only**: user messages, the *final* agent message of each turn (`data.final`), permission cards, notices. Narration, thoughts, tool calls, plans are trace entries (Full conversation sheet).
- **Sync**: every mutation stamps a global `rev`. Clients call `GET /events?since=<rev>` (catch-up in rev order, then live). Emission happens under `Hub::emit_lock` so events leave in rev order. Clients upsert by id; never skip undecodable events (the iOS app rewinds to rev 0).
-- API: `POST /api/<method>` + SSE, bearer token (`~/.codync/token`). Default port **19222**, binds 0.0.0.0 for Tailscale/LAN.
+- API: `POST /api/<method>` + SSE with the bearer token (`~/.codync/token`) is **loopback only** (Mac app, SSH tunnel, local helpers). Phones and other remote clients use the E2E channel (`/channel` direct, or the Cloudflare relay). Default port **19222**.
+- Remote access (Cloudflare relay primary, direct LAN/Tailscale alternative, accounts, SSH): [docs/remote-relay-spec.md](docs/remote-relay-spec.md).
- Remote screen (`host/src/screen.rs` is the reference): phones view/control the computer over WebRTC (hardware H.264, non-trickle SDP relayed by `screenOffer`, input on data channels `input` / `input-fast`); bots get the built-in `computer` MCP server (`codync-host mcp computer`, `host/src/mcp.rs`) when their `computer` flag is on. Capture/input live in a helper on `~/.codync/screen.sock`: `apps/screen` (macOS, launchd agent via `SMAppService`, owns the TCC grants) or `apps/screen-linux` (`codync-screen`: portals + GStreamer, started by the host). Off by default; `setScreenEnabled` is accepted only from loopback. An interactive phone takes over (bots may only look).
-- Push: iOS registers its APNs token with `relay/` → gets an AES-GCM ticket → gives it to the host. Only two alert kinds: *needs you* and *done*, suppressed while the iOS app is connected.
+- Push: iOS registers its APNs token with `relay/` → gets an AES-GCM ticket → gives it (plus its X25519 push key) to the host; the host seals title/body to that key and a Notification Service Extension opens it, so `relay/` sees only generic text. Only two alert kinds: *needs you* and *done*, suppressed while the iOS app is connected.
- Usage: local only — `claude -p /usage --no-session-persistence`, the Claude status line (`codync-host statusline`, wrapping any existing one), Claude ACP `usage_update` rate-limit meta, Codex rollout files. Never call provider APIs with agent credentials.
- macOS app is thin: embeds `codync-host` in `Contents/MacOS` (Xcode post-build script runs cargo), installs it as a launchd agent via `codync-host install`; menu bar shows status/pairing/usage and opens the native chat window (NavigationSplitView over `CodyncUI`). Not sandboxed, not Mac App Store (the host must spawn CLIs).
diff --git a/docs/bot-computer-ssh-plan.md b/docs/bot-computer-ssh-plan.md
index 3cb38adf..f93cf9b1 100644
--- a/docs/bot-computer-ssh-plan.md
+++ b/docs/bot-computer-ssh-plan.md
@@ -1,7 +1,7 @@
# Bot、computer、帳號切換與 SSH 遠端執行計畫
日期:2026-09-25
-狀態:規劃;補充 [Cloudflare 帳號與裝置管理計畫](cloudflare-account-device-plan.md)。
+狀態:規劃;補充 [Cloudflare 帳號與裝置管理計畫](cloudflare-account-device-plan.md)。實作細節(SSH tunnel、多 computer store、中繼)以 [遠端連線實作規格](remote-relay-spec.md) 為準。
## 1. 產品目標
diff --git a/docs/cloudflare-account-device-plan.md b/docs/cloudflare-account-device-plan.md
index a320fed1..397f305a 100644
--- a/docs/cloudflare-account-device-plan.md
+++ b/docs/cloudflare-account-device-plan.md
@@ -3,6 +3,14 @@
日期:2026-09-25
狀態:規劃文件;尚未實作或部署。文中的時間、容量與保留期限是建議產品設定,不是服務商限制。
+> **2026-09-25 更新:實作以 [遠端連線實作規格](remote-relay-spec.md) 為準。** 與本文不同之處:
+> - Cloudflare 中繼(Workers + 每台電腦一個 Durable Object)是第一版的**主要**離家連線路徑;LAN/Tailscale 直連是替代,Tailscale 不是必要條件。
+> - 中繼**端對端加密**:直連與中繼共用同一套 E2E channel(Ed25519 + X25519 + HKDF-SHA256 + ChaCha20-Poly1305),Worker/DO 只看得到密文與路由 metadata。
+> - Host 是授權權威:本機 QR 配對與帳號 grant 都寫進 host 的已授權裝置表,host 簽署 ACL 發佈到 DO;無帳號的本機模式也能用中繼。
+> - 電腦離線時,DO 保存手機→電腦的加密 mailbox(24 小時、可取消、依序投遞)。
+> - Computer ID 由 host 公鑰推導;D1 表名、API 路徑與欄位以規格 §8 為準(`computers`、`/v1/computers`…)。
+> - 共用 pairing token 只接受 loopback;手機一律以逐裝置金鑰連線。
+
## 1. 目標與核心決策
讓使用者在 Mac 和 iPhone 登入同一個 Codync 帳號後,能找到自己的電腦、完成首次授權、管理已授權裝置,並在之後擴充訂閱與免 Tailscale 的遠端連線。
@@ -13,9 +21,9 @@
- **Cloudflare Workers + D1**:帳號與電腦的歸屬、裝置授權、撤權、必要的管理資料。
- **電腦上的 codync-host + SQLite**:bots、threads、entries、專案設定、agent 執行與實際操作權限。
- **既有 Cloudflare 推播 relay**:APNs 通知與 Live Activities,逐步補上帳號與裝置授權。
-- **後續 Durable Objects + WebSocket**:協調及中繼手機與 host 的連線。
+- **Durable Objects + WebSocket**:每台 host 一個,端對端加密中繼、presence 與離線 mailbox(第一版即實作)。
-第一版先完成帳號與裝置管理,直連仍使用 Tailscale/受保護的本機網路連線。聊天、程式碼與本機 SQLite 不會整份複製到 D1。
+第一版同時完成帳號、裝置管理與 Cloudflare 中繼;LAN/Tailscale 直連為替代路徑。聊天、程式碼與本機 SQLite 不會整份複製到 D1。
保留不登入的本機模式。登入是使用雲端管理功能的必要條件,不是本機 agent 執行的必要條件。
@@ -67,7 +75,7 @@ SQLite 是資料庫引擎;本機 SQLite 存在使用者電腦,D1 的資料
雲端目錄的價值:新手機即使還沒連到 Mac,也能知道帳號擁有哪些電腦,並啟動授權流程。電腦離線時仍能顯示清單,但無法讀取最新 bots、聊天或執行新指令。
-既有推播內容可能經 Cloudflare 與 Apple 處理;未來聊天中繼也會處理傳輸內容。「不持久化聊天」不等於「內容從不經過雲端」,也不等於端對端加密。
+推播的標題與內文由 host 以裝置的 push key 加密,Cloudflare(`relay/`)與 APNs 只看到通用文字與 ID(規格 §6.7)。聊天中繼採端對端加密:Cloudflare 只經手密文與路由 metadata(computer/裝置公鑰、時間、大小),見 [規格](remote-relay-spec.md) §15。
## 4. 服務配置與範圍
@@ -77,7 +85,7 @@ SQLite 是資料庫引擎;本機 SQLite 存在使用者電腦,D1 的資料
| Workers,新增 `codync-api` | 帳號 API、claim、授權、撤權、webhook | 第一版 |
| D1 | 管理資料與事件去重 | 第一版 |
| 現有 `codync-relay` Worker | APNs 與 Live Activities | 延用並升級 |
-| Durable Objects | 每台 host 的連線協調、WebSocket 中繼、即時撤權通知 | 第二階段 |
+| Durable Objects | 每台 host 的 E2E 中繼、presence、離線 mailbox、即時撤權 | 第一版 |
| R2 | 使用者明確選擇的附件/備份 | 有實際需求再導入 |
| Queues | 推播與 webhook 的背景處理、重試 | 量體或可靠性需要時導入 |
| Workers KV | 非關鍵設定快取 | 非必要;不作為授權與撤權權威來源 |
@@ -173,7 +181,7 @@ Worker 驗證 Clerk token 的簽章、issuer、到期與適用的 audience/aut
### 7.3 明確的撤權時效
-第一版採短 lease,建議 grant 最長 15 分鐘。host 有網路時每 30 秒檢查授權版本,目標在 60 秒內中止被撤權連線;第二階段改為中繼即時通知並保留輪詢/到期後備機制。
+帳號型 grant 採 15 分鐘 lease,由 host 拉取授權狀態時延長。撤權時 Worker 立即通知 DO 封鎖該裝置並提醒 host 拉取狀態;另有每 5 分鐘輪詢與 lease 到期作後備。
雲端不可達時,不允許無限延長帳號型遠端存取。lease 到期後停止該裝置的讀寫與 screen control,即使 SSE/WebSocket 已建立也要檢查到期並關閉。host 上原有本機任務可繼續執行。
@@ -186,9 +194,9 @@ Worker 驗證 Clerk token 的簽章、issuer、到期與適用的 audience/aut
- Clerk publishable key 可存在 App;Clerk secret、APNs key、雲端簽章私鑰只放 Worker secrets。
- iOS/macOS 的裝置私鑰與 grant 放 Keychain;widget 使用必要的 Keychain access group,不將 token 放 App Group UserDefaults。
- host 私鑰使用 OS 安全儲存或受限制權限的檔案;Linux 至少使用專屬使用者與 `0600`。
-- 第一版優先 Tailscale 的加密連線;一般 LAN 需有已驗證的 TLS/配對信任機制才啟用新帳號型遠端權限,不能直接把長效 token 暴露在普通 HTTP。
+- 所有遠端連線(LAN、Tailscale、中繼)都走同一套 E2E channel;長效 token 只接受 loopback。
- 不在 URL query、一般 log、分析事件或 crash report 中記錄憑證。現有 query token 相容入口需列入退場範圍。
-- 若未來需要中繼無法讀取內容,另做端對端加密設計與審查,不能把 TLS 描述成端對端加密。
+- 中繼的端對端加密設計見 [規格](remote-relay-spec.md) §3、§6;不能把 TLS 描述成端對端加密。
## 8. D1 資料模型
@@ -268,7 +276,7 @@ API 使用 `/v1`,錯誤固定為 `{ error: { code, message }, requestId }`。
| 手機切換網路 | 重新驗證連線,沿用 host `rev` 補事件;送訊息用既有 nonce 去重 |
| 撤權時有正在執行的工作 | 阻止後續存取;工作是否停止由獨立 stop/本機控制決定 |
-第一版不在雲端替離線 host 排隊執行命令。手機保留未送出內容時,要清楚標示,恢復後依冪等鍵送出;permission 回覆等時效性操作不得盲目重播。
+電腦離線時,手機的新訊息以加密 mailbox 暫存在 DO(24 小時、可取消),電腦上線後依序送出並以 `clientNonce` 去重;只有 `send` 可入 mailbox,permission 回覆等時效性操作不得盲目重播。
## 12. 第二階段:免 Tailscale 的遠端連線
@@ -284,7 +292,7 @@ API 使用 `/v1`,錯誤固定為 `{ error: { code, message }, requestId }`。
WebRTC 優先直連,必要時使用 TURN;憑證需短效且受裝置授權約束。Cloudflare 是否承接 TURN、其容量和費用,在該階段核對官方文件後決定。
-只做傳輸層 TLS 的中繼可接觸明文。若選擇端對端加密,需要另外定義首次信任、換機、key rotation、撤權與復原,不在本計畫第一版順帶承諾。
+中繼採端對端加密;首次信任(QR 或 SAS 比對)、換機、key rotation、撤權與復原定義於 [規格](remote-relay-spec.md)。
## 13. 儲存庫實作位置
@@ -402,7 +410,7 @@ Worker 執行 typecheck 與具 D1 binding 的整合測試;Rust 執行 auth/
| 雲端失聯可用多久 | 帳號型 grant 最長 15 分鐘;本機使用不受影響 | P2 |
| 重新登入是否恢復舊批准 | 同一 installation 金鑰可重新驗證;已撤銷裝置需重新批准 | P2 |
| 是否雲端保存聊天 | 第一版不保存 | 若進 P4 同步 |
-| 中繼是否端對端加密 | 未承諾;單獨設計 | P3 前 |
+| 中繼是否端對端加密 | **已定案:是**(見規格) | — |
| 付款方式/方案 | 尚未選定 | P4 前 |
| 團隊共享/多 owner | 第一版不做;每台 host 一個 owner | 後續獨立需求 |
diff --git a/docs/remote-relay-spec.md b/docs/remote-relay-spec.md
new file mode 100644
index 00000000..aff219ef
--- /dev/null
+++ b/docs/remote-relay-spec.md
@@ -0,0 +1,1134 @@
+# 遠端連線實作規格:Cloudflare 中繼(主要)、直連(替代)、帳號與 SSH
+
+日期:2026-09-25(rev 2:安全與可實作性審查後修訂)
+狀態:**實作規格**,交給平行的 CLOUD/HOST/APPLE-KIT/APPLE-APPS 四條 track。與 [帳號與裝置計畫](cloudflare-account-device-plan.md)、[SSH 計畫](bot-computer-ssh-plan.md) 衝突時,以本文件為準。
+測試向量:[remote-relay-vectors.json](remote-relay-vectors.json)(由 [remote-relay-vectors.py](remote-relay-vectors.py) 以固定種子產生,`python3` + `cryptography`;三種語言的實作都必須逐欄通過)。
+
+本文件中「必須/不得」是介面契約;沒有寫到的內部結構由各 track 自行決定。各 track 之間**只透過本文件溝通**,發現本文件有矛盾或缺漏時停下回報,不要自行發明另一套 wire format。
+
+---
+
+## 0. 決策摘要
+
+| # | 決策 | 理由 |
+|---|---|---|
+| D1 | **Cloudflare 中繼是離家連線的主要路徑**;LAN/Tailscale 直連是替代:client 先平行試直連(1.5 秒內完成握手就用),否則走中繼。Tailscale 永遠不是必要條件。 | 使用者不用裝 VPN、不用開 port。 |
+| D2 | **端對端加密(locked box)**。直連和中繼**用同一套 channel 協定**:Ed25519 簽章的臨時 X25519 ECDH → HKDF-SHA256 → ChaCha20-Poly1305。Worker/DO 只看得到密文與路由 metadata。 | 一套協定、一份測試向量;LAN 上也不再有明文 token。 |
+| D3 | 每台 computer 一個 Durable Object(SQLite storage、WebSocket Hibernation):presence、轉送密文、離線 mailbox(手機→電腦,24h TTL,可取消,依序投遞,ack 後刪除)。電腦→手機的補送仍由 host 的 `rev`/events 語意負責。 | 符合產品決策;DO 不保存聊天。 |
+| D4 | **Host 是授權的唯一權威**。host 在本機 SQLite 保存「已授權裝置」表;**只有兩條路能新增列**:本機 QR 配對(§4.1)與 host 自己的核准動作(`decideAccessRequest` approve,§4.2 B)。雲端 state **只能縮短**授權(刪除列、延長既有列的 lease),永遠不能新增。host 把此表簽成 **ACL** 發佈到自己的 DO,DO 據此放行 WebSocket;E2E 握手時 host 再驗一次。 | 無帳號模式也能用中繼(host 以機器金鑰向雲端註冊,不需帳號);雲端被攻破也無法新增可解密的裝置(新增要 host 本機的使用者動作、ACL 要 host 簽、握手要 host 私鑰);撤權有兩道即時關卡(DO 封鎖 + host 關 channel)。 |
+| D5 | **Computer ID 由 host 簽章公鑰推導**:`computerId = b64url(SHA-256(hostSignPub)[0..16])`。不由雲端分配。 | 自我驗證、離線可得、無法被搶註;DO 名稱可直接推導。代價:換 host 金鑰 = 新 computer(見 §3.5)。 |
+| D6 | 帳號 → Computers → Bots:新增 `AccountStore`(`[ComputerID: BotStore]`),`BotReference = accountId + computerId + botId`。 | 產品決策 5。 |
+| D7 | 共用 bearer token(`~/.codync/token`)**只接受 loopback 連線**(Mac App 本機、SSH tunnel、statusline、MCP、TUI、Linux App)。手機與其他遠端 client 一律走 E2E channel。 | 移除「一個 token 開所有手機」的舊模型;不留相容路徑。 |
+| D8 | SSH:macOS App 以系統 OpenSSH `-L` 轉發到遠端 host 的 loopback API;遠端側看到的是 loopback 呼叫者,所以 SSH 帳號等同本機使用者權限(能讀 `~/.codync/token` 的人本來就有這權限)。 | 產品決策 6;重用 loopback API,不需要額外授權層。 |
+| D9 | 版本升為 **3.0.0**(`MARKETING_VERSION`、`host/Cargo.toml`):手機↔host 協定不相容(無 token 直連),依 CLAUDE.md 規則升 major。 | 2.x App 不會誤連 3.x host。 |
+| D10 | **推播內容也加密**:host 以裝置註冊的 X25519 push key 封裝通知標題/內文(§6.7),APNs 只帶通用文字 + `mutable-content`,iOS Notification Service Extension 解開。Live Activity 只推狀態 enum,不推自由文字。 | 決策 2:Cloudflare(`relay/`)只看得到密文。 |
+
+**審查後的取捨(rev 2)**:
+- 撤權後的 DO 解封鎖以 **grantId** 判斷(新核准才解),不比較時間戳(見 §7.3);比 `stateAt` 方案少一個跨時鐘欄位。
+- Mailbox 不在 host 端追蹤已見過的 `epk`:重用 epk 的洩漏發生在送出端、密文已在雲端,host 拒收也無法補救;改以 client 端 MUST(§6.4)與測試保證。
+- SSH 目標設了 `ProxyJump`/`ProxyCommand` 時不做 keyscan、也不做 `SSH_ASKPASS` 首次確認:要求使用者先在終端機連過一次(host key 已在 `~/.ssh/known_hosts`)。少見情境,換來不必實作 askpass helper。
+- 推播選擇「加密 + NSE」而非「只送通用文字」:保留 Grok Bot 式的通知預覽。
+
+明確不做(這一版):雲端保存聊天、Mac 當手機的 SSH gateway、手機原生 SSH、TURN、host 金鑰輪替後沿用舊授權、團隊共享。
+
+---
+
+## 1. 名詞與 ID
+
+| 名稱 | 格式 | 說明 |
+|---|---|---|
+| `hostSignPub` / `signKey` | 32 bytes Ed25519 公鑰,b64url | host 身分金鑰 |
+| `hostBoxPub` / `boxKey` | 32 bytes X25519 公鑰,b64url | 只用於 mailbox 封裝 |
+| `computerId` | `b64url(SHA-256(hostSignPub)[0..16])`,22 字元 | computer 的穩定 ID(D1 `computers.id`、DO 名稱、Apple `ComputerID`) |
+| `hostId` | 既有 UUID(`store.kv host_id`) | **意義不變**:本機資料庫身分,client 用來偵測「換了一個資料庫要重置 mirror」 |
+| `deviceKey` / `dk` | 32 bytes Ed25519 公鑰,b64url | 每個 App 安裝 × 每個帳號 context 一把 |
+| `clientNonce` | 既有 UUID 字串 | `send` 去重;mailbox 的冪等鍵 |
+| `grantId`、`requestId`、`claimId`、`deviceId` | `grt_`/`req_`/`clm_`/`dev_` + b64url(16 random bytes) | D1 資源 ID |
+| `link` | b64url(12 random bytes) | DO 為每條 device WebSocket 指派,host 端用來多工 |
+| `pushKey` | 32 bytes X25519 公鑰,b64url | 每個 App 安裝 × 帳號 context 一把,只用於推播封裝(§6.7) |
+
+編碼規則(**只適用於本規格新定義的欄位**:金鑰、簽章、nonce、`d`、blob、ID、ACL、QR 參數):二進位一律 **base64url、無 padding**(RFC 4648 §5)。時間一律 **Unix epoch 毫秒整數**(JSON number)。字串比對大小寫敏感。
+
+**Inner RPC 的 body 與事件 payload 逐位元組等於今日 HTTP/SSE 的 JSON**,不套用上述規則(例如 `termInput.data`、term `output.data` 維持標準 padded base64;screen SDP 維持原格式)。
+
+命名:`cloud` 一律指 Cloudflare 帳號/中繼服務的 base URL(QR `cloud=`、`hello.cloud`、`Computer.cloud`);`relay` 一律指既有 APNs 推播 relay(`registerDevice.relay`、kv `relay_url`)。
+
+---
+
+## 2. Track 分工與檔案所有權
+
+| Track | 獨占路徑 | 產出 |
+|---|---|---|
+| **CLOUD** | `cloud/**`(新建)、`relay/**`(只改 §6.7 的 `mutableContent` 透傳)、`.github/workflows/cloud.yml`(新建) | Worker(`/v1` API + Clerk + D1)、`ComputerRelay` DO、migrations、vitest、e2e 測試、`cloud/README.md`、CI |
+| **HOST** | `host/**`、`.github/workflows/host.yml` | identity、channel、relay client、cloud client、逐裝置授權、loopback-only token、CLI |
+| **APPLE-KIT** | `kit/**`、`.github/workflows/kit.yml`(新建,`swift test`) | `DeviceIdentity`、channel 加密、`HostTransport`、`HostConnector`、`CloudClient`、`AccountStore`、`BotStore` 調整、models |
+| **APPLE-APPS** | `apps/ios/**`(含 `apps/ios/Widgets`、新 `apps/ios/NotificationService`)、`apps/macos/**`、`apps/shared/**`、`project.yml`、`Codync.xcodeproj`(只經 `xcodegen generate`)、`docs/clerk-macos.md`、`.github/workflows/release-macos.yml` | UI、帳號流程、Mac 核准介面、SSH、Notification Service Extension、entitlements、設定檔 |
+
+- `relay/`(APNs 推播)只加一個欄位:`/push` body 的 `mutableContent: true` → `aps["mutable-content"] = 1`。其他不變。推播撤權由 host 端「ticket 綁定 deviceKey、撤權即刪」達成(§9.4)。
+- `docs/structure.md` 的 `cloud/` 一行已由本規格作者加入。
+- `apps/linux/**`、`apps/screen*/**`:不動(它們只用 loopback token / unix socket)。
+- 共用唯讀檔:`docs/remote-relay-spec.md`、`docs/remote-relay-vectors.json`。任何 track 要改它們 → 回報 orchestrator,不自行修改。
+- `CLAUDE.md`、`docs/cloudflare-account-device-plan.md`、`docs/bot-computer-ssh-plan.md`:由本規格作者更新;各 track 不改。
+- 版本:HOST 把 `host/Cargo.toml` 的 `version` 設為 `3.0.0`;APPLE-APPS 把 `project.yml` 的 `MARKETING_VERSION` 設為 `3.0.0`(`CURRENT_PROJECT_VERSION` 只在上傳時遞增)。
+
+**順序**:四條 track 同時開始,各自以 `remote-relay-vectors.json` 做單元測試,互不等待。APPLE-APPS 依賴 APPLE-KIT 的公開 API(§10.1 已定死簽章),可先以本文件寫 UI,kit 完成後接上。跨 track 整合測試(§12.1)由 CLOUD 擁有,在 HOST 合併後執行。
+
+---
+
+## 3. 身分與金鑰
+
+### 3.1 Host
+
+- 首次啟動產生兩把金鑰:Ed25519 `sign`、X25519 `box`(兩者獨立,不互相轉換)。
+- 存於 `data_dir()/identity.json`,權限 `0600`,**不放 SQLite**(避免複製資料庫就複製身分):
+ ```json
+ {"v":1,"sign":"<b64url 32-byte seed>","box":"<b64url 32-byte scalar>"}
+ ```
+- 寫入:先寫 `identity.json.tmp`(0600)再 rename。讀取失敗(格式錯)→ 啟動失敗並說明,不自動覆蓋。
+- `computerId` 由 `sign` 公鑰推導(§1)。
+
+### 3.2 Device(iPhone、Mac 作為 client)
+
+- 只有一把 Ed25519 金鑰(`Curve25519.Signing.PrivateKey`)。
+- 每個 `SharedStore.Context.id`(帳號 namespace,`local` 或 hash(userID))一把,避免跨帳號關聯。
+- 另有一把 X25519 **push key**(`Curve25519.KeyAgreement.PrivateKey`),同樣每 context 一把,只用於解開推播(§6.7)。
+- Keychain:`kSecClassGenericPassword`,`kSecAttrService = "com.pokai.Codync.device-key"`(push key 用 `"com.pokai.Codync.push-key"`),`kSecAttrAccount = context.id`,值 = 32-byte `rawRepresentation`,`kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`,`kSecAttrSynchronizable = false`。
+- macOS:**不設** `kSecUseDataProtectionKeychain`(Mac App 是 Developer ID、未 sandbox、沒有 entitlements 檔;data protection keychain 需要 provisioning profile 背書的 entitlement,否則 `-34018`)。使用 login keychain,不設 access group。
+- iOS App、Widgets、NotificationService 共用 access group `$(AppIdentifierPrefix)com.pokai.Codync`(APPLE-APPS 在 `project.yml` 對這三個 target 加 `keychain-access-groups` entitlement;kit 從 Info.plist `CodyncKeychainGroup` 讀 group,缺值則不設 group)。
+- 私鑰永不離開 Keychain/process;雲端只存公鑰。
+- 帳號登出/移除帳號:刪除該 context 的 device key、computers 快取、mailbox 草稿、widget snapshot。
+
+### 3.3 Per-(device, host) E2E 金鑰
+
+沒有長期共用對稱金鑰。**每次 channel 連線**做一次 signed-ephemeral ECDH(§6.2),得到兩個方向的 32-byte 金鑰;連線結束即丟棄(前向保密)。雙方的長期身分金鑰是 pin 住的公鑰:
+
+| 流程 | device 如何得知 host 公鑰 | host 如何得知 device 公鑰 |
+|---|---|---|
+| QR(本機、無帳號) | QR 內 `sk`/`bk`(可信的實體通道) | 配對時在 E2E channel 內以一次性 pairing code 證明(§4.1) |
+| 帳號 + 存取申請 | `GET /v1/computers` 取 `signKey`(雲端傳遞)+**commit-then-reveal SAS 6 碼比對**防止雲端換鑰(§4.2) | D1 access request → host 在電腦上由使用者核准(同一組 SAS) |
+
+`boxKey`(mailbox 用)**只從已驗證來源 pin**:QR 的 `bk`,或 E2E channel 內 inner `hello` 回應的 `boxKey`。雲端回傳的 `boxKey` 只作顯示,不得用於封裝。尚未 pin `boxKey` 的 computer 不提供 mailbox(帳號流程的手機在核准後第一次連線即取得,因為核准當下 host 必定在線)。
+
+### 3.4 撤權
+
+| 動作 | 效果 |
+|---|---|
+| 在電腦上撤銷裝置(Mac UI/`codync-host devices revoke`) | host 刪除裝置列與其 push tickets、Live Activity tickets → 立即關閉該裝置所有 channel → 發佈新 ACL → DO 關閉其 WebSocket;帳號來源的另呼叫 `DELETE` 對應 grant(見 §8.4 `POST /v1/host/grants/{id}/revoke`) |
+| 雲端撤銷 grant/裝置/解除綁定/刪帳號 | Worker 寫 D1 → 呼叫 DO `/internal/block`(`[{dk, grantId}]`,立即關閉並封鎖)→ DO 通知 host `cloud.changed` → host 拉 `/v1/host/state` 並刪除裝置列 |
+| host 連不到雲端 | 帳號來源裝置的 lease 最長 15 分鐘後失效,host 關閉 channel;本機(QR)來源裝置不受影響 |
+
+### 3.5 輪替
+
+- **Channel 金鑰**:每次連線新產生;任一方向 counter 達 2^32 或連線滿 24 小時 → host 以 close code `4011 rekey` 關閉,client 立即重連。
+- **Device key**:不做原地輪替。要換 → 刪 key、重新配對/重新申請。
+- **Host key**:不做原地輪替。刪除 `identity.json` 即成為新 computer(新 `computerId`),所有裝置需重新配對;舊 D1 列由使用者在帳號中移除。這是刻意的簡化(D5)。
+- **Loopback token**:`codync-host reset-token` 照舊,只影響本機 helper。
+
+---
+
+## 4. 配對與授權流程
+
+### 4.1 QR 配對(無帳號也可用)
+
+QR/連結保留 `codync://pair` scheme,**移除 `token`**,欄位:
+
+```
+codync://pair?v=3&name=<pct>&id=<computerId>&sk=<signPub>&bk=<boxPub>&code=<pairing code>&urls=<pct a,b>&cloud=<pct cloud base URL>
+```
+
+| 欄位 | 必填 | 說明 |
+|---|---|---|
+| `v` | 是 | 固定 `3`;缺或不同 → App 顯示「請更新電腦上的 Codync」 |
+| `id` | 是 | 必須等於 `computerId(sk)`,否則拒絕 |
+| `sk`, `bk` | 是 | host 公鑰 |
+| `code` | 是 | 16 random bytes,b64url;一次性、10 分鐘;host 最多同時 5 組(新的擠掉最舊的) |
+| `urls` | 否 | 直連候選(既有 `service::addresses`,`http://ip:port` 形式),可為空 |
+| `cloud` | 否 | host 使用的 cloud base URL(`https://…`;DEBUG build 另允許 `http://127.0.0.1:*`/`http://localhost:*`);缺 = host 關閉雲端 |
+| `name` | 否 | 顯示名稱 |
+
+`urls` 與 `cloud` 至少要有一個。`offerId = b64url(SHA-256("codync/offer/v1" ‖ codeBytes)[0..16])`。
+
+流程:
+1. 使用者在電腦上開 QR(Mac 選單 → loopback `pairing`;或 `codync-host pair`)。host 產生 code,記在記憶體,並立即發佈含 `offers` 的新 ACL。
+2. 手機載入/建立 device key,用 §7.5 的連線策略連線,hello 帶 `"pair": true`(中繼另需 URL `pair=<offerId>`)。
+3. 握手成功(手機已用 QR 的 `sk` 驗證 host)後,第一個 request 必須是:
+ ```json
+ {"id":1,"m":"pair","b":{"code":"<code>","name":"Kevin's iPhone","platform":"ios"}}
+ ```
+4. host 驗 code(常數時間比較、未過期、未用過)→ 刪除該 code → 新增裝置列(`source=local`,`grant_id=NULL`,`scopes=["control","screen"]`,無 lease)→ 回 `{"id":1,"ok":{"computerId":"…","name":"…"}}` → **關閉這條 channel,close code `4100 paired`**(中繼:host 依序送 `data`(回應)→ `close {link, code:4100}` → 新 ACL(移除 offer、加入 dk);同一條 host socket 保序,所以回應一定先到)。
+5. client 收到 `4100` 立即以一般模式重連(§7.5,不帶 `pair`)。直連與中繼行為相同;DO 不需要「升級」pairing socket。
+
+`Caller::Pairing` 的 channel 只接受 `pair`:第一個 inner 訊息不是 `pair`、或 `pair` 之後還有任何訊息 → 關閉 `4002 protocolError`。
+
+錯誤與限流:
+- 沒有任何未過期的 pairing code 時,`pair:true` 的 `hello` 在做 ECDH/簽章驗證**之前**就回 `reject pairingClosed` 並關閉。
+- 限流只計算「到達 `pair` request」的嘗試:每個來源(直連:peer IP;中繼:link)每分鐘 3 次,全 host 每分鐘 10 次;超過回 `reject rateLimited`。
+- code 錯/過期 → `{"err":{"status":403,"message":"This pairing code expired. Show a new one on the computer."}}` 並關閉 channel。
+
+### 4.2 帳號流程
+
+**A. 電腦加入帳號(claim)**—在該電腦上的 Mac App(或經 SSH tunnel 的 Mac App)操作:
+1. Mac App(Clerk 已登入)`POST /v1/claims` → `{claimId, nonce, expiresAt}`(5 分鐘)。
+2. Mac App 呼叫 loopback `claimSign {claimId, nonce, userId}` → host 回傳註冊資料與簽章:
+ `sig = Ed25519_host("codync/claim/v1\n" + claimId + "\n" + nonce + "\n" + userId + "\n" + computerId + "\n" + boxKey)`(UTF-8,**無結尾換行**;向量 `claim`)。Worker 以此 `boxKey` 建立或更新 `computers.box_pub`,不接受 client 另給的值。
+3. Mac App `POST /v1/claims/{claimId}/complete`(Clerk)帶上 host 回傳的內容。Worker 驗 Clerk、claim、簽章,原子化設定 owner。
+4. Worker 通知 DO `cloud.changed` → host 拉 state 得知 owner。
+
+**B. 手機取得存取權**(commit-then-reveal SAS,ZRTP/BLE numeric comparison 同型):
+1. 手機登入後 `POST /v1/devices`(Clerk + 該 device key 的 `Codync-Sig`)。
+2. `GET /v1/computers`(帶 `Codync-Sig` 則回傳每台的 `access`)。
+3. 對 `access == "none"` 的電腦:手機產生 32 random bytes `nD`(只存記憶體),`POST /v1/computers/{id}/access-requests {"commit": b64url(SHA-256("codync/sascommit/v1" ‖ dk ‖ nD))}` → `{requestId, expiresAt}`。
+4. Worker 通知 DO → host 拉 state → 看到新申請(含 `commit`)→ host 產生 32 random bytes `nH`(存本機記憶體,每個 requestId 只產生一次)→ `POST /v1/host/access-requests/{id}/nonce {"nonce": nH}`(已有 host nonce → `409 conflict`,host 不得換)。
+5. 手機輪詢 `GET /v1/access-requests/{id}`(每 2 秒)→ 出現 `hostNonce` 後才 `POST /v1/access-requests/{id}/reveal {"nonce": nD}` → Worker 存入並通知 DO `cloud.changed`。手機此時計算 SAS 顯示「在電腦上確認代碼 123456」。
+6. host 拉 state 取得 `deviceNonce` → 驗 `SHA-256("codync/sascommit/v1" ‖ dk ‖ nD) == commit`(不符 → 自動 deny 並記 `warn`)→ 計算 SAS → `accessRequests` 事件 → Mac App 顯示核准對話框(裝置名稱、平台、帳號 email、SAS)。**`nD` 驗證通過前 host 不顯示 SAS、不接受 approve**(`decideAccessRequest` 回 409)。無 GUI 的 host:`codync-host access list|approve|deny`。
+7. 核准 → host `POST /v1/host/access-requests/{id}/decision {"decision":"approve"}` → D1 建立 grant → 回 `grantId` → host **以自己顯示給使用者的 `dk` 與回傳的 `grantId`** 新增裝置列(`source=account`,lease 15 分鐘)→ 發佈 ACL。
+8. 手機輪詢到 `approved` → 連線(§7.5)。第一次 `hello` 回應帶 `boxKey`,此時 pin(§3.3)。
+
+**SAS**:`sas = uint32_be(SHA-256("codync/sas/v2" ‖ hostSignPub ‖ dk ‖ nD ‖ nH)[0..4]) mod 1_000_000`,左補零成 6 位數(向量 `sas`)。手機用從雲端拿到的 `signKey` 算、host 用自己的公鑰與申請內 dk 算。因為雙方的 nonce 在對方的值確定之後才揭露,被攻破的雲端每次申請只有 10⁻⁶ 的機會讓兩邊代碼相同,無法離線搜尋金鑰。手機核准後 pin 住算 SAS 用的那把 `signKey`,之後以 `welcome.sig` 驗證。
+
+### 4.3 授權表與 ACL(host 為權威)
+
+host 的授權裝置表(§9.2)每一列:`key, name, platform, source(local|account), grant_id, scopes, lease_until`。
+
+規則(**雲端只能縮短授權,不能新增**):
+- 新增列只有兩條路:§4.1 的 `pair`(`source=local`,`grant_id=NULL`)與 §4.2 B 的 host 核准(`source=account`,`grant_id` = decision 回傳值,`key` = host 顯示給使用者的 dk)。
+- 套用 `/v1/host/state` 時,只看本機已有的 `source=account` 列:`(grant_id, key)` 出現在 `grants` → `lease_until = now + 15min`;不在 → 刪除(同 transaction 刪 push/activity tickets)。
+- state 裡本機不認識的 grant(或 `grant_id` 相同但 `deviceKey` 不同)→ 忽略並 `tracing::warn!(grant_id, "unknown grant from cloud ignored")`;不新增、不改寫任何列。`source=local` 的列不受 state 影響。
+- 狀態拉取成功時才延長 lease;連不到雲端就讓 lease 自然到期。
+- `lease_until` 過期的列視同不存在(不必立即刪;下次拉取時清)。
+- 每次連上 relay(含重連):先完成一次 state 拉取(最多等 10 秒)才送 `acl`/`ready`;拉取成功之前,`source=account` 的列在直連與中繼上都不接受握手。
+- 表有任何變動 → `acl_ver` 前進(§7.3 規則)→ 發佈 ACL。
+
+ACL(host 簽章,DO 驗證;逐位元組簽章,不做 JSON 正規化;向量 `acl`):
+```json
+{"v":1,"computerId":"…","ver":12,
+ "devices":[{"dk":"…","grant":"grt_…"}, {"dk":"…","grant":null}],
+ "offers":[{"id":"<offerId>","exp":1790000600000}]}
+```
+`grant: null` = 本機配對。ACL 不帶 lease 與 scopes:lease 與 scope 由 host 在握手與每個 request 時判斷,DO 只做「是否列在最新 ACL、是否被封鎖」的粗篩(§7.1)。發佈格式見 §7.3 `acl`。
+
+---
+
+## 5. Codync-Sig:HTTP/WebSocket 請求簽章
+
+用於:host → `/v1/host/*`、host/device → `/v1/relay/*`(WebSocket upgrade)、device 在 `/v1/devices`、`/v1/computers/{id}/access-requests`、`/v1/access-requests/{id}/reveal` 與 `GET /v1/computers` 的持有證明。
+
+Header:
+```
+Codync-Sig: v=1,kid=<b64url pub>,ts=<ms>,nonce=<b64url 16 random bytes>,sig=<b64url 64-byte sig>
+```
+簽章輸入(UTF-8,`\n` 分隔,無結尾換行):
+```
+codync-sig-v1
+<METHOD 大寫>
+<authority:小寫的 Host header 值,含非預設 port,例如 codync-cloud-staging.x.workers.dev 或 127.0.0.1:8787>
+<path + query,與實際送出的 request-target 逐字相同>
+<ts>
+<nonce>
+<b64url(SHA-256(body bytes))> ← 無 body(GET、WS)用空字串的 hash
+```
+驗證:`|now - ts| ≤ 300_000`;`(kid, nonce)` 在 10 分鐘內未出現過(HTTP:D1 `sig_nonces`;relay:DO 的 `nonces` 表);Ed25519 驗證(Worker 用 WebCrypto `Ed25519`)。Worker 以 `new URL(request.url).host`(小寫)比對 authority,所以 staging 簽的 header 在 production 無效。失敗 → `401 {"error":{"code":"badSignature"}}`。向量:`requestSig`。
+
+---
+
+## 6. 密碼學規格(channel、mailbox)
+
+所有向量在 `remote-relay-vectors.json`。`‖` = 位元組串接;ASCII 標籤不含結尾 NUL。
+
+### 6.1 Channel 訊息(明文 JSON,WebSocket text frame)
+
+| `t` | 方向 | 欄位 |
+|---|---|---|
+| `hello` | device→host | `v`=1, `dk`, `ek`(device 臨時 X25519 公鑰), `n`(32 random bytes), `sig`, `pair`(bool,選填) |
+| `welcome` | host→device | `v`=1, `ek`(host 臨時 X25519 公鑰), `sig` |
+| `reject` | host→device | `code`(`unauthorized`/`revoked`/`leaseExpired`/`badSignature`/`unsupportedVersion`/`pairingClosed`/`rateLimited`), `message` |
+| `f` | 雙向 | `c`(u64 counter,JSON number), `d`(b64url 密文+tag) |
+
+### 6.2 握手
+
+```
+cidRaw = SHA-256(hostSignPub)[0..16]
+hs1 輸入 = "codync/hs1/v1" ‖ cidRaw ‖ dk ‖ ekD ‖ n (13+16+32+32+32 bytes)
+hello.sig = Ed25519_device(hs1 輸入)
+TH = SHA-256("codync/hs2/v1" ‖ cidRaw ‖ dk ‖ ekD ‖ n ‖ ekH)
+welcome.sig = Ed25519_host(TH)
+ss = X25519(ekD_priv, ekH) ← 全零結果必須拒絕
+prk = HKDF-Extract(salt = TH, ikm = ss)
+kD2H = HKDF-Expand(prk, "codync/d2h/v1", 32)
+kH2D = HKDF-Expand(prk, "codync/h2d/v1", 32)
+```
+- host 的檢查順序(便宜的先做):
+ 1. 中繼 link:`hello.dk` 必須等於 DO 在 `open` 給的 `dk`;`pair` 必須與 `open.pair` 相同。不符 → `4002`。
+ 2. `pair == true`:沒有未過期的 pairing code → `reject pairingClosed`(不做任何密碼運算);限流見 §4.1。
+ 3. `pair != true`:`dk` 必須是有效授權(§4.3,含「relay 連上後 state 已拉取」條件)。否則 `reject unauthorized|revoked|leaseExpired`。
+ 4. 驗 `hello.sig` → 產生 `ekH` → `welcome`。
+- 裝置的 `connected` 與 `last_seen_at` **只在收到第一個成功解密的 `f` 之後**才更新(重放的 `hello` 無法推導金鑰,不得讓裝置看起來在線)。
+- device:用 pin 住的 `hostSignPub` 驗 `welcome.sig`;失敗 → 視為攻擊,關閉並回報 `.unauthorized("This computer's identity changed…")`,**不**改走其他路徑重試同一 host key。
+- 握手期限:host 收到連線後 10 秒內沒有 `hello` 就關閉;device 送出 `hello` 後 10 秒內沒 `welcome` 就放棄。
+
+### 6.3 Frame 加密
+
+```
+nonce(12) = 0x00000000 ‖ u64_be(c)
+aad = "codync/frame/v1" ‖ u64_be(c)
+plaintext = flag(1 byte: 0x00 最後一段, 0x01 還有後續) ‖ chunk bytes
+d = ChaCha20-Poly1305(kDir, nonce, plaintext, aad) (密文 ‖ 16-byte tag)
+```
+- 每個方向各自從 `c = 0` 起算,每 frame +1;接收方要求 `c` 恰為預期值,否則關閉(close `4002 protocolError`)。這同時提供重放與重排保護。
+- 一則 inner 訊息(§6.5 的 JSON)UTF-8 編碼後切成 ≤ 256 KiB 的 chunk;接收方串接直到 flag `0x00`,再 JSON parse。
+- 重組上限:device→host 1 MiB;host→device 16 MiB。超過 → 關閉 `4013 tooLarge`。
+
+### 6.4 Mailbox 封裝(device → 離線 host)
+
+```
+epk, eprv = 新的 X25519 金鑰對
+ss = X25519(eprv, hostBoxPub) ← 全零拒絕
+prk = HKDF-Extract(salt = "codync/mbox/v1" ‖ cidRaw ‖ dk ‖ epk, ikm = ss)
+key = HKDF-Expand(prk, "codync/mbox-key/v1", 32)
+ct = ChaCha20-Poly1305(key, nonce = 12 × 0x00, plaintext = inner JSON, aad = dk ‖ UTF-8(clientNonce))
+sig = Ed25519_device("codync/mbox/v1" ‖ cidRaw ‖ epk ‖ ct)
+blob = epk(32) ‖ sig(64) ‖ ct
+```
+固定 nonce 安全的前提:**每次封裝都必須產生新的 `epk`(MUST)**,不得快取或重用。重試時只能重送當初存下的同一個 blob,或以新的 `epk` 重新封裝。kit 與 TS 參考實作各有一個測試:連續封裝兩次同一則訊息,`epk` 不同。inner JSON:
+```json
+{"m":"send","b":{"botId":"…","text":"…","clientNonce":"<同 envelope>"},"ts":1790000000000}
+```
+`hostBoxPub` 只能用 §3.3 pin 住的值。host 檢查:dk 目前有效 → 驗 sig → 解密(aad 用 envelope 的 `from` 與 `nonce`)→ `b.clientNonce == nonce` → `now - ts ≤ 25h` → `m` 只允許 `send` → 走一般 `send` dispatch(既有 `find_by_nonce` 去重)。
+
+### 6.5 Inner RPC(加密 frame 內的 JSON)
+
+對應既有 `POST /api/<method>` 與 `GET /events`、`GET /term/{id}`:
+
+| 訊息 | 方向 | 形式 |
+|---|---|---|
+| request | d→h | `{"id":N,"m":"<method>","b":<body 或 null>}` |
+| 成功 | h→d | `{"id":N,"ok":<與 HTTP 回應 body 相同的 JSON>}` |
+| 失敗 | h→d | `{"id":N,"err":{"status":<HTTP 狀態碼>,"message":"…"}}`(status 對應今日 `ApiError`:400/403/404/500) |
+| 訂閱 | d→h | `{"id":N,"sub":"events","b":{"since":<rev>,"client":"ios"|"mac"}}` 或 `{"id":N,"sub":"term","b":{"term":"<id>"}}` |
+| 串流事件 | h→d | `{"id":N,"ev":<與今日 SSE `data:` 完全相同的 JSON>}` |
+| 串流結束 | h→d | `{"id":N,"end":true}`(term exit 之後)或 `err` |
+| 取消 | d→h | `{"id":N,"cancel":true}`:訂閱 → host 停止串流並回 `end`;一般 request → host 丟棄回應(**不中止已開始的 mutation**) |
+
+- `id`:device 端遞增 u32,連線內唯一。
+- 每條 channel 最多 32 個進行中的 request、4 個訂閱;超過回 `err 429`。
+- `events` 訂閱的語意與 SSE 完全相同(先 subscribe、再 catch-up、`hello` 在最前、落後時送 `{"type":"resync"}`);`client == "ios"` 時計入 `hub.ios_clients`(推播抑制)。
+- 串流沒有額外的 keep-alive;存活由 WebSocket ping(§7.6)負責。
+
+### 6.6 方法權限(host 以 `Caller` 判斷)
+
+| 類別 | 方法 | 允許的 caller |
+|---|---|---|
+| loopback 專用 | `setScreenEnabled`, `pairing`, `computerCall`, `claimSign`, `unclaim`, `devices`, `revokeDevice`, `accessRequests`, `decideAccessRequest`, `cloudStatus`, `setCloud` | `Caller::Local`(loopback + token) |
+| 配對中 | `pair` | 只在 pairing 狀態的 channel;配對完成後不可再呼叫 |
+| screen scope | `screenOffer`, `screenClose`, `screenTakeover` | Local,或 scopes 含 `screen` 的裝置 |
+| control scope | 其餘所有既有方法(`hello`, `sync`, `history`, `createBot`, `updateBot`, `deleteBot`, `markRead`, `send`, `stop`, `newSession`, `respondPermission`, `registerDevice`, `registerActivity`, `refreshBackends`, `usage`, `listDirs`, market/skills/connectors、`agentSetup`, `agentAuth`, `agentAuthenticate`, `setAgentEnv`, `termInput`, `termResize`, `termClose`, `screenStatus`) | Local,或 scopes 含 `control` 的裝置 |
+
+v1 發出的 grant 一律 `["control","screen"]`。
+
+### 6.7 推播封裝(host → APNs → 手機)
+
+裝置在 `registerDevice` 帶 `pushKey`(§1)。host 對每個 ticket:
+```
+epk, eprv = 新的 X25519 金鑰對(每則通知、每個 ticket 各自新產生)
+ss = X25519(eprv, pushKey) ← 全零拒絕
+prk = HKDF-Extract(salt = "codync/push/v1" ‖ cidRaw ‖ pushKey ‖ epk, ikm = ss)
+key = HKDF-Expand(prk, "codync/push-key/v1", 32)
+ct = ChaCha20-Poly1305(key, nonce = 12 × 0x00, plaintext = {"title","body"} JSON, aad = cidRaw)
+sealed = b64url(epk ‖ ct)
+```
+送給 `relay/` 的 body:`alert = {"title":"Codync","body":"Needs you"|"Done"}`(通用文字,依 kind)、`mutableContent: true`、`threadId = botId`、`category = kind`、`data = {"botId","computerId","ctx":<SharedStore.Context.id>,"sealed"}`。Notification Service Extension 依 `ctx` 從共用 Keychain 取 push key、解開後替換 title/body;解不開就保留通用文字。Live Activity 的 `contentState` 只含 `status` 與 `startedAt`(`activity` 固定為空字串),不含任何自由文字。向量 `push`。
+
+---
+
+## 7. Relay wire protocol(Worker + DO)
+
+### 7.1 URL
+
+| 用途 | URL | 認證 |
+|---|---|---|
+| host | `GET {cloud}/v1/relay/host?v=1`(Upgrade: websocket) | `Codync-Sig`,kid = hostSignPub;Worker 由 kid 推導 `computerId`,D1 `computers` 必須存在且 `status='active'`(先 `/v1/host/register`) |
+| device | `GET {cloud}/v1/relay/device/{computerId}?v=1[&pair=<offerId>]` | `Codync-Sig`,kid = deviceKey;DO 以 ACL 判斷 |
+
+`v` 不是 `1` → HTTP `426 {"error":{"code":"upgradeRequired"}}`。`{computerId}` 必須符合 `^[A-Za-z0-9_-]{22}$`,否則 `400`(不轉給 DO)。
+
+Worker → DO 的轉送**不沿用 client 的 URL**:Worker 自己建立新 request `new Request("https://do/relay", {headers})`(只帶 `Upgrade`、`Sec-WebSocket-*` 與下列內部 header),交給 `env.RELAY.get(env.RELAY.idFromName(computerId))`。內部 header:`X-Codync-Internal: 1`、`X-Codync-Role`、`X-Codync-Key`、`X-Codync-Nonce`、`X-Codync-Ts`、`X-Codync-Pair`(offerId 或空)、`X-Codync-Computer`。DO 只以 pathname 完全等於 `/relay`、`/internal/block`、`/internal/changed` 路由,且全部要求 `X-Codync-Internal: 1`;其他 → `404`。因為 client 的 request 永遠不會被原樣轉進 DO,外部無法觸及 `/internal/*`。DO 檢查 nonce 重放後才 `acceptWebSocket`。
+
+Device 准入(DO):
+- `dk` 在 `blocked` 表 → `403`。
+- `pair` 參數存在:`offerId` 必須在 ACL `offers` 且未過期;同時最多 2 條 pairing socket,每條最長 120 秒、最多 16 則訊息;不能 `mbox.*`。
+- 否則 `dk` 必須列在最新 ACL 的 `devices`。**DO 不看 lease**:lease 只由 host 在握手與每個 request 時判斷,所以 host 離線多久,帳號裝置都能連上 DO 看 presence、用 mailbox(host 上線後處理 `mbox.item` 時再驗一次)。
+- DO 從未收過 ACL(host 從未連過)→ `404 {"error":{"code":"unknownComputer"}}`。
+- 每台 computer 最多 16 條 device socket → 超過 `429`。
+
+### 7.2 Hibernation 與 attachment
+
+- 一律 `ctx.acceptWebSocket(ws, [role])`,tag 為 `"host"` 或 `"device"`。
+- `ws.serializeAttachment`:host `{role:"host", kid, ready: boolean}`;device `{role:"device", dk, link, pair: boolean, offer?: string}`。
+- **「host 在線」的唯一定義**:存在一條 host socket 且其 attachment `ready == true`。presence、mailbox 接受與否(§7.7)、`data` 轉送全部用這一個定義。
+- `ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair('{"t":"ping"}', '{"t":"pong"}'))`:client 必須送**完全相同**的字串 `{"t":"ping"}`。
+- 新的 host 連線到來時,舊 host socket 以 `4009 replaced` 關閉;所有 device socket 收到 `presence online:false`(新 host socket 的 `ready` 之後再送 `online:true`)。
+- host 端:relay socket 每次重新連線,都丟棄全部 link 狀態(channel、訂閱、進行中的 request)。
+- device 端:每次收到 `presence online:true` 都丟棄舊 channel 金鑰、重新送 `hello`。
+
+### 7.3 Host socket 訊息(外層 JSON,DO 可讀)
+
+Host → DO:
+
+| `t` | 欄位 | 行為 |
+|---|---|---|
+| `acl` | `d`(ACL JSON bytes 的 b64url), `sig` | DO 以 host kid 驗簽、`computerId` 必須相符 → 否則 `{"t":"error","code":"badAcl","ver":<已存>}`。`ver` ≤ 已存 ver → `{"t":"error","code":"staleVersion","ver":<已存>}`,host 設 `acl_ver = max(本機, ver) + 1` 重新簽發。成功 → 存起來;以 `4003 revoked` 關閉 dk 不再列在 `devices` 的一般 socket;以 `4410 pairingExpired` 關閉其 offer 不再列在 `offers` 的 pairing socket;**解除封鎖只在**新 ACL 以「不同且非 null 的 `grant`」列出被封鎖的 dk 時(即 host 做了一次新的核准;`blocked` 表存 `(dk, grant_id)`);回 `{"t":"acl.ok","ver":N}` |
+| `ready` | — | host 已完成 state 拉取(§4.3)並發佈 ACL。DO 把 host attachment 設 `ready:true`、送 `presence online:true` 給所有 device、對每條 device socket 送 `open`、開始送 mailbox。之後新接受的 device socket 立即送 `open` |
+| `data` | `link`, `m`(channel 訊息物件) | host 必須 ready;將 `m` 原樣(`JSON.stringify(m)`)送到該 link 的 device socket |
+| `close` | `link`, `code`, `reason` | 關閉該 device socket |
+| `mbox.ack` | `seq`, `ok`(bool), `code`(`ok:false` 時:`unauthorized`/`unknownBot`/`invalid`) | 刪除 mailbox 項目,通知發送裝置 `mbox.delivered` 或 `mbox.failed` |
+| `ping` | — | auto-response |
+
+DO → Host:
+
+| `t` | 欄位 |
+|---|---|
+| `open` | `link`, `dk`, `pair`(bool) |
+| `data` | `link`, `m`(device 送來的 channel 訊息物件) |
+| `close` | `link`(device 斷線) |
+| `mbox.item` | `seq`, `from`(dk), `nonce`(clientNonce), `d`(blob b64url), `exp` |
+| `cloud.changed` | —(Worker 通知:請立刻拉 `/v1/host/state`) |
+| `acl.ok` / `error` | 見上 |
+
+### 7.4 Device socket 訊息
+
+Device → DO:channel 訊息(`hello`、`f`)原樣送出,DO 包成 `{"t":"data","link","m"}` 轉給 host(host 不在線(§7.2 定義)→ 丟棄,並回一次 `presence`)。以及:
+
+| `t` | 欄位 | 回應 |
+|---|---|---|
+| `mbox.put` | `nonce`(clientNonce), `exp`(≤ now+24h;缺省 now+24h), `d`(blob) | `{"t":"mbox.ok","nonce","state":"queued"}`;錯誤 `{"t":"mbox.err","nonce","code"}`,code:`hostOnline`(請改用 channel)、`tooLarge`、`full`、`invalid`、`pairing` |
+| `mbox.cancel` | `nonce` | 未投遞 → 刪除並回 `{"t":"mbox.cancelled","nonce"}`;已送出給 host 但未 ack、或不存在 → `{"t":"mbox.gone","nonce","state":"delivering"|"unknown"}` |
+| `mbox.list` | — | `{"t":"mbox.items","items":[{"nonce","exp","state":"queued"|"delivering"}]}`(只列該 dk 的) |
+| `ping` | — | auto-response `pong` |
+
+DO → Device(除了 host 轉來的 channel 訊息 `welcome`/`reject`/`f` 之外):
+
+| `t` | 欄位 |
+|---|---|
+| `presence` | `online`(bool), `lastSeenAt`(ms 或 null)— 連線建立時送一次,之後狀態變化時送(含 host 被 replaced 時的 false→true) |
+| `mbox.delivered` | `nonce` |
+| `mbox.failed` | `nonce`, `code` |
+| `mbox.expired` | `nonce` |
+| `mbox.*` 回應 | 見上 |
+
+Channel 訊息與 DO 訊息的 `t` 值不重疊:channel 只有 `hello`/`welcome`/`reject`/`f`。
+
+### 7.5 Client 連線策略(Apple 與整合測試共通)
+
+1. 平行對所有 `urls`(`http://h:p` → `ws://h:p/channel?v=1`)開 WebSocket 並握手;**1.5 秒**內第一個完成握手的勝出。
+2. 都失敗且有 `cloud` → 連 `{cloud}/v1/relay/device/{computerId}`。每次收到 `presence online:true` 就(重新)送 `hello`;`online:false` → 狀態 `computerOffline(lastSeen)`,保持 socket(可用 mailbox),等下一個 `online:true`。
+3. 兩者都不可用 → `offline("Can't reach …")`,退避重試。
+4. App 回前景、網路路徑改變(`NWPathMonitor`)→ 重新跑 1–3(可能從中繼換回直連);events 以當前 `rev` 重新訂閱。
+5. 每次 inner `hello` 成功後,把回應的 `urls`、`cloud`、`device`、`name`、`boxKey` 合併進持久化的 `Computer`(§3.3、§10.2);帳號來源的 computer 因此在第一次中繼連線後也能試 LAN 直連。
+
+### 7.6 心跳、重連、限流
+
+- 心跳:host 與 device 每 30 秒送 `{"t":"ping"}`(中繼);直連時 host 每 15 秒送 WebSocket Ping frame,client 45 秒沒收到任何資料視為斷線。
+- DO alarm:只要有 socket 或 mailbox 項目就每 60 秒一次:host socket 的 `ctx.getWebSocketAutoResponseTimestamp()` 超過 90 秒 → 以 `1011` 關閉並標記離線;清除過期 mailbox(通知 `mbox.expired`)與過期 nonces。
+- 重連退避:host 1 s 起倍增至 60 s、device 1 s 起倍增至 30 s,皆 full jitter;穩定 60 秒後重置。
+- `4100 paired` → 立即以一般模式重連(§4.1)。
+- 不重試的 close code:`4001 unauthorized`、`4003 revoked`、`4410 pairingExpired`(device 顯示需重新授權);`4009 replaced` → host 等 5 分鐘再試並記錄 `error`(可能有人複製了 `identity.json`);`4400 unsupportedVersion` → 顯示需要更新。
+- 限流(DO 記憶體 token bucket,休眠後重置可接受):**只計 device → DO 方向**,每條 device socket 每 10 秒 ≤ 200 則、≤ 8 MiB;超過 `4008 rateLimited`。host → device(含 `sync` 補送)不限。
+- 單則 WebSocket 訊息 ≤ 1 MiB(Cloudflare 限制);§6.3 的 256 KiB chunk 保證不超過。
+
+Close code 總表:`1000` 正常、`1011` 內部錯誤/逾時、`4001 unauthorized`、`4002 protocolError`、`4003 revoked`、`4004 unknownComputer`、`4008 rateLimited`、`4009 replaced`、`4011 rekey`、`4013 tooLarge`、`4100 paired`、`4400 unsupportedVersion`、`4410 pairingExpired`。
+
+### 7.7 Mailbox 規則
+
+- 只在 host 不在線時接受(§7.2 的唯一定義:沒有 `ready:true` 的 host socket)。
+- 冪等:`(dk, nonce)` 唯一;重送同一組回傳現有狀態,不重複入列。
+- 上限:單則 blob ≤ 64 KiB;每 dk ≤ 50 則;每 computer ≤ 500 則、總計 ≤ 8 MiB。
+- 投遞:host `ready` 後,DO 依 `seq` 遞增逐則送 `mbox.item`(狀態改 `delivering`);host 逐則處理並 `mbox.ack`。host 斷線時 `delivering` 退回 `queued`,重連後重送(host 以 clientNonce 去重)。
+- TTL 到期 → 刪除 + `mbox.expired`。
+
+---
+
+## 8. CLOUD track:`cloud/`
+
+### 8.1 結構與設定
+
+```
+cloud/
+ package.json tsconfig.json wrangler.toml README.md
+ migrations/0001_init.sql
+ src/index.ts 路由(可用 hono,或像 relay/ 一樣手寫)
+ src/auth.ts Clerk 驗證、Codync-Sig 驗證
+ src/api.ts /v1 handlers
+ src/relay.ts ComputerRelay Durable Object
+ test/*.test.ts vitest + @cloudflare/vitest-pool-workers
+ test/e2e/relay.e2e.ts 跨 track 整合測試
+```
+依賴:`@clerk/backend`、`svix`(webhook);測試:`vitest`、`@cloudflare/vitest-pool-workers`、`@noble/curves`、`@noble/ciphers`、`@noble/hashes`。Worker 端 Ed25519 驗證用 WebCrypto,不引入加密套件。
+
+`wrangler.toml`:
+```toml
+name = "codync-cloud"
+main = "src/index.ts"
+compatibility_date = "2026-09-01"
+compatibility_flags = ["nodejs_compat"]
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["ComputerRelay"]
+
+# production(部署需 owner 確認)
+[vars]
+CLERK_ISSUER = "<production Clerk Frontend API URL>"
+[[d1_databases]]
+binding = "DB"
+database_name = "codync"
+database_id = "<production id>"
+migrations_dir = "migrations"
+[[durable_objects.bindings]]
+name = "RELAY"
+class_name = "ComputerRelay"
+[triggers]
+crons = ["*/15 * * * *"]
+
+[env.staging]
+vars = { CLERK_ISSUER = "https://sunny-mollusk-8651.clerk.accounts.dev" }
+d1_databases = [{ binding = "DB", database_name = "codync-staging", database_id = "<由 wrangler d1 create 取得>", migrations_dir = "migrations" }]
+durable_objects.bindings = [{ name = "RELAY", class_name = "ComputerRelay" }]
+triggers = { crons = ["*/15 * * * *"] }
+
+[env.dev] # wrangler dev / e2e:本機 D1,CLERK_JWT_KEY 由測試注入
+vars = { CLERK_ISSUER = "https://clerk.test.local" }
+d1_databases = [{ binding = "DB", database_name = "codync-dev", database_id = "dev", migrations_dir = "migrations" }]
+durable_objects.bindings = [{ name = "RELAY", class_name = "ComputerRelay" }]
+```
+Worker 名稱:production `codync-cloud`,staging `codync-cloud-staging`。
+
+### 8.2 D1 schema(`migrations/0001_init.sql`)
+
+```sql
+CREATE TABLE accounts (
+ user_id TEXT PRIMARY KEY, -- Clerk sub
+ email TEXT,
+ status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','deleted')),
+ created_at INTEGER NOT NULL,
+ deleted_at INTEGER
+);
+
+CREATE TABLE computers (
+ id TEXT PRIMARY KEY, -- computerId
+ sign_pub TEXT NOT NULL UNIQUE,
+ box_pub TEXT NOT NULL,
+ owner_user_id TEXT REFERENCES accounts(user_id),
+ name TEXT NOT NULL,
+ platform TEXT NOT NULL CHECK (platform IN ('macos','linux')),
+ device TEXT, -- laptop|macmini|…|linux(host 的 Device)
+ version TEXT NOT NULL,
+ status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','blocked')),
+ online INTEGER NOT NULL DEFAULT 0, -- DO 寫入
+ last_seen_at INTEGER, -- DO 寫入
+ claimed_at INTEGER,
+ created_at INTEGER NOT NULL,
+ updated_at INTEGER NOT NULL
+);
+CREATE INDEX computers_owner ON computers(owner_user_id);
+
+CREATE TABLE devices (
+ id TEXT PRIMARY KEY, -- dev_…
+ owner_user_id TEXT NOT NULL REFERENCES accounts(user_id),
+ sign_pub TEXT NOT NULL,
+ name TEXT NOT NULL,
+ platform TEXT NOT NULL CHECK (platform IN ('ios','macos')),
+ created_at INTEGER NOT NULL,
+ last_used_at INTEGER,
+ revoked_at INTEGER,
+ UNIQUE (owner_user_id, sign_pub)
+);
+
+CREATE TABLE claims (
+ id TEXT PRIMARY KEY, -- clm_…
+ user_id TEXT NOT NULL REFERENCES accounts(user_id),
+ nonce TEXT NOT NULL,
+ expires_at INTEGER NOT NULL,
+ consumed_at INTEGER,
+ computer_id TEXT
+);
+
+CREATE TABLE access_requests (
+ id TEXT PRIMARY KEY, -- req_…
+ computer_id TEXT NOT NULL REFERENCES computers(id),
+ device_id TEXT NOT NULL REFERENCES devices(id),
+ user_id TEXT NOT NULL REFERENCES accounts(user_id),
+ status TEXT NOT NULL CHECK (status IN ('pending','approved','denied','expired','cancelled')),
+ commit_hash TEXT NOT NULL, -- SHA-256("codync/sascommit/v1" ‖ dk ‖ nD)
+ host_nonce TEXT, -- nH,host 設一次
+ device_nonce TEXT, -- nD,host_nonce 存在後裝置才可設
+ created_at INTEGER NOT NULL,
+ expires_at INTEGER NOT NULL, -- created_at + 10 min
+ decided_at INTEGER,
+ grant_id TEXT
+);
+CREATE INDEX access_requests_computer ON access_requests(computer_id, status);
+CREATE UNIQUE INDEX access_requests_one_pending ON access_requests(computer_id, device_id) WHERE status = 'pending';
+
+CREATE TABLE grants (
+ id TEXT PRIMARY KEY, -- grt_…
+ computer_id TEXT NOT NULL REFERENCES computers(id),
+ device_id TEXT NOT NULL REFERENCES devices(id),
+ scopes TEXT NOT NULL, -- JSON array
+ status TEXT NOT NULL CHECK (status IN ('active','revoked')),
+ created_at INTEGER NOT NULL,
+ revoked_at INTEGER,
+ revoked_reason TEXT -- owner|deviceRevoked|unclaimed|accountDeleted
+);
+CREATE UNIQUE INDEX grants_active ON grants(computer_id, device_id) WHERE status = 'active';
+
+CREATE TABLE sig_nonces (
+ kid TEXT NOT NULL,
+ nonce TEXT NOT NULL,
+ expires_at INTEGER NOT NULL,
+ PRIMARY KEY (kid, nonce)
+);
+
+CREATE TABLE processed_events (
+ provider TEXT NOT NULL,
+ event_id TEXT NOT NULL,
+ processed_at INTEGER NOT NULL,
+ PRIMARY KEY (provider, event_id)
+);
+
+CREATE TABLE audit_events (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ actor TEXT NOT NULL, -- user_id / computer:<id> / system
+ action TEXT NOT NULL,
+ target TEXT,
+ result TEXT NOT NULL,
+ created_at INTEGER NOT NULL
+);
+CREATE INDEX audit_time ON audit_events(created_at);
+```
+
+原子性要求(每項以單一 `db.batch([...])` 完成,並檢查 `meta.changes`):
+- **claim complete**:`UPDATE claims SET consumed_at=?t, computer_id=?c WHERE id=?id AND user_id=?u AND consumed_at IS NULL AND expires_at>?now` → `UPDATE computers SET owner_user_id=?u, claimed_at=?t, updated_at=?t WHERE id=?c AND owner_user_id IS NULL AND EXISTS(SELECT 1 FROM claims WHERE id=?id AND consumed_at=?t)`。第一句 0 changes → `410 claimExpired`;第二句 0 changes 且 owner 已是同一 user → 200(冪等);其他 owner → `409 alreadyClaimed`。
+- **approve**:`UPDATE access_requests SET status='approved', decided_at=?, grant_id=?g WHERE id=? AND computer_id=? AND status='pending' AND expires_at>?now` → `INSERT INTO grants (...) SELECT ... WHERE EXISTS(SELECT 1 FROM access_requests WHERE id=? AND grant_id=?g) ON CONFLICT DO NOTHING`;若因 `grants_active` 衝突,回傳既有 active grant。
+- **reveal**:`UPDATE access_requests SET device_nonce=? WHERE id=? AND user_id=? AND status='pending' AND host_nonce IS NOT NULL AND device_nonce IS NULL`;0 changes → 依狀態回 `409 conflict`/`410 requestExpired`/`404`。Worker **不**驗 commit(host 驗)。
+- **host nonce**:`UPDATE access_requests SET host_nonce=? WHERE id=? AND computer_id=? AND status='pending' AND host_nonce IS NULL`;0 changes → `409 conflict`。
+- 所有查詢都帶 owner 範圍;別人的資源一律回 `404 notFound`(不洩漏存在)。建立 access request 同時要求 `computers.owner_user_id = clerk.sub` **且** `devices.owner_user_id = clerk.sub`(device 由 Sig(dev) 的 kid 找出),任一不符 → `404`。
+
+Cron(每 15 分鐘):刪除 `sig_nonces` 過期、`claims` 過期 1 天、`access_requests` pending 過期 → `expired`(同時清空 `host_nonce`/`device_nonce`)、`audit_events` 超過 30 天。
+
+### 8.3 認證
+
+- **Clerk**:`Authorization: Bearer <session JWT>`。以 `@clerk/backend` 的 `verifyToken(token, opts)` 驗證:有 `CLERK_JWT_KEY` 時用 `jwtKey`(networkless,dev/e2e 使用),否則用 `secretKey: CLERK_SECRET_KEY`(自動抓 JWKS、快取、支援輪替);`authorizedParties` 取 `CLERK_AUTHORIZED_PARTIES`(逗號分隔,可空;native token 通常沒有 `azp`,有則必須在清單內)。另外檢查 `iss === CLERK_ISSUER`、`sub` 存在、`sid` 存在。`email` 取自自訂 session claim `email`(owner 在 Clerk 設定,§14.3),缺則為 null。每個 Clerk 請求 `INSERT OR IGNORE INTO accounts`;`status='deleted'` → `403 accountDeleted`。
+- **Codync-Sig**:§5。
+- **Webhook**:`POST /v1/webhooks/clerk`,`svix` 以 `CLERK_WEBHOOK_SECRET` 驗證,`svix-id` 寫入 `processed_events` 去重。
+
+錯誤格式(所有 `/v1`):
+```json
+{"error":{"code":"notFound","message":"…"},"requestId":"<cf-ray 或 uuid>"}
+```
+code 清單:`badRequest`(400) `unauthenticated`(401) `badSignature`(401) `forbidden`(403) `accountDeleted`(403) `notFound`(404) `alreadyClaimed`(409) `conflict`(409) `claimExpired`(410) `requestExpired`(410) `upgradeRequired`(426) `rateLimited`(429) `internal`(500)。
+
+### 8.4 `/v1` HTTP API
+
+所有 body 為 JSON;時間為 ms。「Clerk」= 需要 Bearer;「Sig(dev)」= 需要該 device key 的 `Codync-Sig`;「Sig(host)」= host key 的 `Codync-Sig`。
+
+**公開**
+- `GET /v1/health` → `{"ok":true,"version":"3.0.0"}`
+
+**Clerk(使用者)**
+- `GET /v1/me` → `{"userId","email","createdAt"}`
+- `POST /v1/devices`(Clerk + Sig(dev))`{"name","platform":"ios"|"macos"}` → `{"device":{"deviceId","deviceKey","name","platform","createdAt"}}`。以 `(owner, sign_pub)` upsert;已撤銷的同一把 key → `403 forbidden`(需換 key)。
+- `GET /v1/devices` → `{"devices":[{"deviceId","deviceKey","name","platform","createdAt","lastUsedAt","revoked":bool}]}`
+- `DELETE /v1/devices/{deviceId}` → `{}`;撤銷裝置與其所有 grants(`deviceRevoked`),對相關 computers 呼叫 DO `/internal/block` + `cloud.changed`。
+- `POST /v1/claims` → `{"claimId","nonce","expiresAt"}`(nonce = 16 random bytes b64url)
+- `POST /v1/claims/{claimId}/complete` `{"computerId","signKey","boxKey","name","platform","device","version","sig"}` → `{"computer":<Computer>}`。驗:`computerId == derive(signKey)`、sig(§4.2 A,輸入含 `boxKey`)、claim 有效;computer 列不存在時一併建立,`box_pub` 一律取自簽過的 `boxKey`。
+- `GET /v1/computers`(Clerk,選配 Sig(dev))→ `{"computers":[Computer]}`,
+ `Computer = {"computerId","name","platform","device","signKey","boxKey","version","online":bool,"lastSeenAt","claimedAt","access":"none"|"pending"|"granted"|null}`(`access` 只在帶 Sig(dev) 且該 device 屬於此帳號時計算;`boxKey` 僅供顯示,client 不得用於封裝,§3.3)
+- `PATCH /v1/computers/{id}` `{"name"}` → `{"computer":…}`(只改雲端顯示名稱)
+- `DELETE /v1/computers/{id}` → `{}`;解除綁定:owner=NULL、grants 全撤(`unclaimed`)、pending requests → `cancelled`、DO block + changed。
+- `POST /v1/computers/{id}/access-requests`(Clerk + Sig(dev),device 須已註冊未撤銷;computer 與 device 都必須屬於 `clerk.sub`,否則 `404`)`{"commit"}` → `{"requestId","expiresAt"}`;已有 pending → 先把它改為 `cancelled` 再建新的(commit 不可重用);已有 active grant → `409 conflict`。成功後 DO `cloud.changed`。每帳號每小時最多 20 筆 → `429`。
+- `GET /v1/access-requests/{id}` → `{"requestId","computerId","status","expiresAt","hostNonce"?,"grantId"?}`(只有申請者可見)
+- `POST /v1/access-requests/{id}/reveal`(Clerk + Sig(dev),必須是申請的那個 device)`{"nonce"}` → `{}`;成功後 DO `cloud.changed`。
+- `DELETE /v1/access-requests/{id}` → `{}`(申請者取消 pending)
+- `GET /v1/computers/{id}/grants` → `{"grants":[{"grantId","deviceId","deviceName","platform","scopes","createdAt"}]}`
+- `DELETE /v1/computers/{id}/grants/{grantId}` → `{}`(`owner`)+ DO block + changed
+
+**Sig(host)(不需要帳號)**
+- `POST /v1/host/register` `{"boxKey","name","platform","device","version"}` → `{"computerId","owned":bool}`。以 kid 推導 id;upsert(`name`/`device`/`version`/`box_pub`/`updated_at`)。同 IP 每分鐘最多 10 次新建(Workers Rate Limiting binding;平台不支援時先略過並在 README 註記)。
+- `GET /v1/host/state` →
+ ```json
+ {"owner":{"userId":"user_…","email":"[email protected]"} | null,
+ "grants":[{"grantId","deviceKey","deviceName","platform","scopes":["control","screen"]}],
+ "requests":[{"requestId","deviceKey","deviceName","platform","email","commit","hostNonce"?,"deviceNonce"?,"createdAt","expiresAt"}]}
+ ```
+ grants 只含:grant active、device 未撤銷、device.owner == computer.owner。host 只把它當成「可續約/應刪除」的清單(§4.3)。
+- `POST /v1/host/access-requests/{id}/nonce` `{"nonce"}` → `{}`(§8.2;已設過 → `409`)
+- `POST /v1/host/grants/{grantId}/revoke` `{}` → `{}`(host 在本機撤銷帳號來源裝置時同步 D1,`revoked_reason='owner'`;失敗只記 `warn`,本機撤銷已生效)
+- `POST /v1/host/access-requests/{id}/decision` `{"decision":"approve"|"deny"}` → `{"status","grantId"?}`(§8.2 原子性;request 過期 → `410 requestExpired`;approve 要求 `device_nonce IS NOT NULL`,否則 `409`)
+- `POST /v1/host/unclaim` `{}` → `{}`(在電腦上移出帳號;同 `DELETE /v1/computers/{id}` 的效果)
+
+**Relay**:§7.1。**Webhook**:`user.deleted` → accounts `status='deleted'`、devices 撤銷、grants 撤銷(`accountDeleted`)、computers owner=NULL、DO block + changed。
+
+### 8.5 `ComputerRelay` DO
+
+- DO SQLite 表:`meta(k TEXT PRIMARY KEY, v TEXT)`(`signKey`、`aclVer`、`aclD`、`aclSig`、`lastSeenAt`)、`mailbox(seq INTEGER PRIMARY KEY AUTOINCREMENT, dk TEXT, nonce TEXT, blob BLOB, size INTEGER, exp INTEGER, state TEXT, UNIQUE(dk, nonce))`、`nonces(kid TEXT, nonce TEXT, exp INTEGER, PRIMARY KEY(kid, nonce))`、`blocked(dk TEXT PRIMARY KEY, grant_id TEXT, blocked_at INTEGER)`。
+- 內部端點(只經 Worker 自建的 request 呼叫,§7.1):`POST /internal/block {"devices":[{"dk","grantId"}]}`(upsert `blocked`、以 `4003` 關閉相符 socket、送 host `cloud.changed`)、`POST /internal/changed`(送 host `cloud.changed`;host 離線則忽略)。解除封鎖規則見 §7.3 `acl`。
+- host 連上/斷線 → `UPDATE computers SET online=?, last_seen_at=? WHERE id=?`(D1 binding;列不存在即 no-op)。
+- DO 不解析 `f` 的內容、不保存 channel 訊息。
+
+### 8.6 CLOUD 測試
+
+- 單元(vitest-pool-workers):Codync-Sig 向量(含 authority)、重放、時間窗、跨 authority 拒絕;claim 向量;ACL 驗證(向量 `acl`)、ver 單調與 `staleVersion` 回傳已存 ver;封鎖後以相同 grant 的 ACL 不解封、以新 grant 解封;`computerId` 格式錯誤 400、偽造 `/internal/*` 路徑不可達;access request 跨帳號 computer 404、reveal 早於 host nonce 409、approve 早於 reveal 409;host 未 ready 時 mailbox 仍接受、`data` 丟棄;ready 後新 device socket 立即收到 `open`;host replaced 時 device 收到 false→true presence;claim 競爭(兩帳號同時 complete);approve 雙擊;跨帳號 404;webhook 去重;mailbox 冪等、上限、取消、TTL、依序投遞、host 斷線重送;presence;auto-response;device 准入(封鎖、pairing 限制、offer 消失 → 4410);host 離線超過 15 分鐘帳號裝置仍可 `mbox.put`;`relay/` 的 `mutableContent` 透傳。
+- 以 `@noble/*` 在 TS 寫一份 device/host 參考實作(測試用),先通過 `remote-relay-vectors.json`,再用於 e2e。
+
+---
+
+## 9. HOST track:`host/src`
+
+### 9.1 新模組
+
+| 檔案 | 內容 |
+|---|---|
+| `identity.rs` | `Identity { sign: SigningKey, box_secret: StaticSecret }`、`load_or_create(dir)`、`computer_id()`、`sign_pub_b64()`、`box_pub_b64()`、`sign_request(method, path_query, body) -> String`(Codync-Sig header 值) |
+| `crypto.rs` | 握手、frame seal/open、chunking、mailbox open、SAS commit/code、offer id、claim 簽章輸入、push seal;全部以向量測試 |
+| `channel.rs` | 與傳輸無關的 channel:`run(hub, Transport, ChannelKind)`;握手、授權、inner RPC、訂閱、lease 監看 |
+| `relay.rs` | 對 `{cloud}/v1/relay/host` 的出站 WebSocket:ACL 發佈、link 多工、mailbox 處理、重連 |
+| `cloud.rs` | `/v1/host/*` HTTP client(`crate::http()`)、state 輪詢、核准決定、`CloudStatus` |
+| `devices.rs`(或併入 `store.rs`) | 授權裝置表、`Caller`、`Scope`、`DeviceSource` |
+
+依賴(最新相容版本):`ed25519-dalek`(`rand_core`)、`x25519-dalek`(`static_secrets`)、`chacha20poly1305`、`hkdf`、`rand_core`(`getrandom`)、`tokio-tungstenite`(rustls + webpki roots)、`axum` 開 `ws` feature。注意 `hkdf` 與既有 `sha2 = 0.11` 的 `digest` 版本需一致;必要時 `hkdf` 用自己相容的 `sha2`,不要手寫 HKDF。
+
+### 9.2 Store
+
+`Store::open` 新增 schema 版本(kv `schema`);升到 3 時 `DROP TABLE devices`(舊 push ticket 表,手機重連時會重新註冊)並建立:
+```sql
+CREATE TABLE devices(
+ key TEXT PRIMARY KEY, name TEXT NOT NULL, platform TEXT NOT NULL,
+ source TEXT NOT NULL, grant_id TEXT, scopes TEXT NOT NULL,
+ lease_until INTEGER, created_at INTEGER NOT NULL, last_seen_at INTEGER);
+CREATE TABLE push_tickets(
+ ticket TEXT PRIMARY KEY, device_key TEXT NOT NULL, push_key TEXT, ctx TEXT, name TEXT, created_at INTEGER NOT NULL);
+CREATE TABLE activity_tickets(
+ ticket TEXT PRIMARY KEY, bot_id TEXT NOT NULL, device_key TEXT NOT NULL, created_at INTEGER NOT NULL);
+```
+`hub.activities`(記憶體 map)改由 `activity_tickets` 取代。
+Rust 以 enum 表示:`DeviceSource { Local, Account }`、`Scope { Control, Screen }`(serde camelCase 字串)。刪除裝置時同一 transaction 刪除其 `push_tickets` 與 `activity_tickets`。kv 新增:`acl_ver`、`cloud_url`、`cloud_enabled`。
+
+`acl_ver` 與 DO 的已存 ver 可能不一致(資料庫被刪、還原,但 `identity.json` 還在):收到 `staleVersion`/`badAcl` 附帶的 `ver` 時,設 `acl_ver = max(acl_ver, ver) + 1` 並重新簽發一次(只重試一次,再失敗記 `error`)。測試:刪除資料庫、保留 identity 後重啟,ACL 能被 DO 接受。
+
+### 9.3 Hub
+
+新增欄位:`identity: Identity`、`auth: watch::Sender<u64>`(裝置表 generation;每次變動 +1,channel 據此重新檢查自己的 dk)、`pairing_codes: Mutex<Vec<PairingCode>>`、`cloud: Mutex<CloudStatus>`、`access_requests: Mutex<Vec<AccessRequest>>`(含 host 自己的 `nH`,只存記憶體;host 重啟後對同一申請 post nonce 會得到 409 → 該申請自動 deny,手機重新申請)。刪除 `activities`(改存 `activity_tickets`,§9.2)。`token` 保留(loopback)。
+
+### 9.4 API 變更(`api.rs`)
+
+- `authorized()`:只接受 `Authorization: Bearer`(刪除 `?token=`)**且** `peer.ip().to_canonical().is_loopback()`(`--bind ::` 時 IPv4 會以 `::ffff:127.0.0.1` 出現;附單元測試)。`events`/`term_stream`/`statusline` 都要 `ConnectInfo`。
+- `dispatch(hub, caller: &Caller, method, body)`;`enum Caller { Local, Device { key: String, scopes: Vec<Scope> }, Pairing { key: String } }`;權限依 §6.6,拒絕回 403。取代今日只針對 `setScreenEnabled` 的特例。
+- 抽出 `events_stream(hub, since, client, caller) -> impl Stream<Item = Value>`(SSE 與 channel 共用;`Caller::Device` 看不到 `accessRequests`/`cloud` 事件)與 `term_events(hub, id)`。
+- `GET /health` → `{"ok":true,"hostId","computerId","version"}`。
+- `GET /channel?v=1`:axum WebSocket,交給 `channel::run`。
+- `hello` 回應新增:`computerId`、`signKey`、`boxKey`、`protocol: 1`、`cloud`(啟用時的 cloud URL,否則 null)。events 的 `hello` 事件新增 `computerId`。
+- `registerDevice {ticket, name, relay, pushKey, ctx}`:ticket 綁定 `Caller::Device.key`(Local 呼叫則 `device_key = "local"`);`push::notify` 讀 `push_tickets` 並依 §6.7 封裝(沒有 `pushKey` 的 ticket 只收通用文字)。
+- `registerActivity`:ticket 寫入 `activity_tickets`,綁定 caller 的 device key;`live_activity_update` 不再送 `activity` 文字。
+- 新 loopback 方法:
+
+| 方法 | body | 回應 |
+|---|---|---|
+| `pairing` | — | `{"pairingUrl","urls","svg","expiresAt"}`(每次呼叫產生新 code) |
+| `devices` | — | `{"devices":[{"key","name","platform","source","scopes","leaseUntil","createdAt","lastSeenAt","connected":bool}]}` |
+| `revokeDevice` | `{"key"}` | `{}` |
+| `accessRequests` | — | `{"requests":[AccessRequest]}` |
+| `decideAccessRequest` | `{"requestId","approve":bool}` | `{}`(approve:`nD` 未驗證 → 409;成功後以 host 顯示的 dk + 回傳的 grantId 新增裝置並發佈 ACL) |
+| `claimSign` | `{"claimId","nonce","userId"}` | `{"computerId","signKey","boxKey","name","platform","device","version","sig"}` |
+| `unclaim` | — | `{}` |
+| `cloudStatus` | — | `CloudStatus` |
+| `setCloud` | `{"enabled":bool,"url"?}` | `CloudStatus` |
+
+`AccessRequest = {"requestId","deviceKey","deviceName","platform","email","code"(SAS;`nD` 驗證前為 null),"createdAt","expiresAt"}`
+`CloudStatus = {"enabled","url","registered","connected","owner":{"userId","email"}|null,"lastError"}`
+新 event(只給 Local):`{"type":"accessRequests","requests":[…]}`、`{"type":"cloud","cloud":CloudStatus}`;不帶 rev(與 `usage`/`screen` 同類)。
+
+### 9.5 Channel(`channel.rs`)
+
+- 同一實作服務兩種傳輸:直連(axum WebSocket)與中繼 link(`relay.rs` 以 mpsc 餵入 `m`、以共用 sink 送出 `{"t":"data","link","m"}`)。
+- 流程:等 `hello` → 驗證 → `welcome` → 迴圈:組裝 frame → 解析 inner → request 以 `tokio::spawn` 呼叫 `api::dispatch`(同一 channel 的回應可亂序)→ 回 `ok`/`err`;`sub` 啟動串流任務;`cancel` 中止串流。
+- 每個 request 前檢查 dk 仍有效(查 `hub.auth` generation 快取);`watch` 變動 → 立即重查,失效 → 送 `reject`(或 close `4003`)並結束所有串流。`lease_until` 到期時以 timer 主動關閉。
+- 第一個成功解密的 frame 之後才標記 connected、更新 `devices.last_seen_at`(§6.2)。
+- pairing channel(`Caller::Pairing`):只處理一個 `pair`,回應後以 `4100` 關閉(§4.1)。
+
+### 9.6 Relay 與 cloud client
+
+- cloud URL:env `CODYNC_CLOUD_URL` > kv `cloud_url` > `cloud::DEFAULT_CLOUD_URL: Option<&str>`(目前 `None`,production 部署時填入)。三者皆無 → 雲端停用(不重試、`CloudStatus.enabled=false`)。`CODYNC_CLOUD=off` 一律停用;`host/tests/e2e.rs` 設 `CODYNC_CLOUD=off`。
+- 啟動(雲端啟用時):`POST /v1/host/register`(退避重試,最長 30 分鐘間隔)→ 連 `/v1/relay/host` → **state 拉取(§4.3,最多 10 秒)** → 送 `acl` → 等 `acl.ok`(`staleVersion` 處理見 §9.2)→ 送 `ready`。每次重連都走同一順序,並丟棄全部 link 狀態。
+- state 拉取:每次 relay 連上時、收到 `cloud.changed` 時、有 owner 時每 5 分鐘;套用 §4.3 規則(只續約/刪除,不新增);對 `hostNonce` 為空的新申請 post nonce(§4.2 B 4);`deviceNonce` 出現時驗 commit、算 SAS、emit `accessRequests`;owner 變更時 emit `cloud` 事件。
+- `mbox.item`:依序處理;§6.4 驗證;回 `mbox.ack`(`ok`/`code`)。
+- ping 每 30 秒;§7.6 退避與 close code 處理。
+- tracing 結構化欄位(`computer_id`、`link`、`error = format!("{e:#}")`);**不記錄**金鑰、密文、pairing code、訊息內容。
+
+### 9.7 CLI
+
+- `codync-host pair [--json]`:改呼叫本機 loopback `pairing`(host 需在執行中,否則明確提示)。JSON:`{"name","computerId","signKey","boxKey","urls","cloud","pairingUrl","expiresAt"}`。
+- `codync-host info --json`(不需 host 執行中):`{"name","computerId","signKey","boxKey","version","port","token","running":bool}` — SSH 設定用;`token` 為 loopback token。`info` **只讀** `identity.json` 與 token,絕不建立:檔案不存在 → stderr `start codync-host once first`、exit 1。只有 `serve` 會建立 identity。
+- `codync-host access list|approve <requestId|SAS>|deny <requestId>`、`codync-host devices list|revoke <key>`、`codync-host cloud [--enable|--disable] [--url URL]`:皆走 loopback API。
+- TUI `--url`:說明改為「遠端請用 SSH tunnel 轉到 loopback」。
+
+### 9.8 HOST 測試
+
+- `crypto.rs`:通過 `remote-relay-vectors.json` 全部欄位(`include_str!("../../docs/remote-relay-vectors.json")`)。
+- 授權:未知 dk 被拒、pairing 流程(回應後 4100、pairing channel 上非 `pair` 被關)、無 code 時 `pair:true` 在 ECDH 前被拒、code 單次、lease 到期關閉 channel、撤權關閉進行中的 events 訂閱並刪 push/activity tickets、scope 拒絕、loopback-only 方法經 channel 被拒、非 loopback bearer 被拒、`::ffff:127.0.0.1` 視為 loopback。
+- state 套用:未知 grant 被忽略(表不變)、已知 grant 續約、缺席者刪除;relay 連上後 state 拉取前帳號裝置握手被拒;relay link 上 `hello.dk != open.dk` 被關;SAS commit 不符自動 deny、reveal 前 approve 被拒。
+- `acl_ver`:刪 DB 保留 identity → `staleVersion` 後以 `max+1` 成功。
+- `tests/e2e.rs` 延伸:以 Rust 測試端的 device 實作走直連 `/channel`:pair → hello → events → `send`(fake agent)→ 收到回覆。
+
+---
+
+## 10. APPLE-KIT track:`kit/`
+
+### 10.1 公開 API(APPLE-APPS 依賴這些名稱與簽章)
+
+```swift
+// CodyncKit/Models/Computer.swift
+public typealias ComputerID = String
+public struct Computer: Codable, Hashable, Sendable, Identifiable {
+ public var id: ComputerID
+ public var name: String
+ public var signKey: String // pin:QR `sk`,或帳號流程 SAS 通過後的 signKey
+ public var boxKey: String? // pin:只來自 QR `bk` 或 E2E `hello`(§3.3);nil = 尚無 mailbox
+ public var urls: [String]
+ public var cloud: URL?
+ public var device: String?
+ public var color: String?
+}
+public struct BotReference: Codable, Hashable, Sendable {
+ public var accountId: String? // = SharedStore.Context.accountID(原始 Clerk userID;nil = 本機 context)
+ public var computerId: ComputerID
+ public var botId: String
+}
+
+// CodyncKit/Client/Pairing.swift(取代 HostClient.swift 裡的舊 Pairing)
+public struct Pairing: Hashable, Sendable { // 掃到的 QR;暫存,不持久化
+ public var computer: Computer
+ public var code: String
+ public init?(url: URL); public init?(string: String)
+}
+
+// CodyncKit/Client/DeviceIdentity.swift
+public struct DeviceIdentity: Sendable {
+ public let publicKey: String // Ed25519,b64url
+ public let pushKey: String // X25519,b64url(§6.7)
+ public static func load(context: SharedStore.Context) throws -> DeviceIdentity // 沒有就建立(兩把)
+ public static func delete(context: SharedStore.Context)
+ public func signatureHeader(method: String, authority: String, pathAndQuery: String, body: Data) throws -> String
+ /// NSE 用:以 context.id 找 push key 解開 §6.7 的 `sealed`;失敗回 nil。
+ public static func openPush(sealed: String, computerId: ComputerID, contextID: String) -> (title: String, body: String)?
+}
+
+// CodyncKit/Client/HostTransport.swift
+public enum HostRoute: Sendable, Equatable { case loopback, direct, relay }
+public enum HostStreamRequest: Sendable { case events(since: Int64, client: String), term(String) }
+public enum LinkState: Sendable, Equatable {
+ case connecting, ready(HostRoute), hostOffline(lastSeen: Date?), unauthorized(String), failed(String)
+}
+public protocol HostTransport: Sendable {
+ func call(_ method: String, body: Data, timeout: TimeInterval) async throws -> Data
+ /// nonisolated:actor 實作在內部起 Task。每個元素 = 一則 SSE data JSON。
+ func stream(_ request: HostStreamRequest) -> AsyncThrowingStream<Data, Error>
+ /// 每次呼叫回傳一條新的 stream:先 yield 目前狀態,之後每次變化。可多個消費者。
+ func states() -> AsyncStream<LinkState>
+}
+// 路由切換(中繼↔直連)或重新握手時,transport 以 HostError.unreachable 結束所有已開的 stream;
+// 重新訂閱由 BotStore 負責(以它目前的 rev)。LoopbackTransport.states() 只 yield `.ready(.loopback)`。
+
+public struct HostClient: Sendable {
+ public let transport: any HostTransport
+ public init(transport: any HostTransport)
+ public init(baseURL: URL, token: String) // loopback(Mac 本機、SSH tunnel)
+ // 既有 typed 方法(hello/sync/send/… 與 Market.swift 的擴充)保持原樣,改走 transport
+}
+
+public enum HostError: LocalizedError, Sendable {
+ case http(Int, String)
+ case unreachable
+ case computerOffline(lastSeen: Date?)
+ case unauthorized(String)
+ case upgradeRequired
+}
+
+// CodyncKit/Client/HostConnector.swift
+public enum HostConnector {
+ /// §7.5:直連優先(1.5 s),否則中繼。回傳的 transport 在 host 離線時仍存活(presence/mailbox)。
+ public static func connect(_ computer: Computer, identity: DeviceIdentity) async throws -> ChannelTransport
+ /// §4.1:以 QR 配對(收到 4100 即完成),回傳可持久化的 Computer。
+ public static func pair(_ pairing: Pairing, identity: DeviceIdentity, deviceName: String, platform: String) async throws -> Computer
+}
+public actor ChannelTransport: HostTransport {
+ public nonisolated func call(_ method: String, body: Data, timeout: TimeInterval) async throws -> Data
+ public nonisolated func stream(_ request: HostStreamRequest) -> AsyncThrowingStream<Data, Error>
+ public nonisolated func states() -> AsyncStream<LinkState>
+ public nonisolated func computerUpdates() -> AsyncStream<Computer> // 每次 hello 成功後合併的新值(§7.5 步驟 5)
+ // mailbox
+ public func enqueue(botId: String, text: String, clientNonce: String) async throws // 無 boxKey → HostError.computerOffline
+ public func cancelQueued(clientNonce: String) async -> MailboxCancel // .cancelled / .delivering / .unknown
+ public func listQueued() async -> [QueuedItem]
+ public nonisolated func mailboxEvents() -> AsyncStream<MailboxEvent> // .delivered/.failed(code)/.expired(nonce)
+}
+
+// CodyncKit/Client/CloudClient.swift
+public struct CloudClient: Sendable {
+ public init(baseURL: URL, identity: DeviceIdentity?, token: @escaping @Sendable () async throws -> String)
+ public func me() async throws -> CloudAccount
+ public func registerDevice(name: String, platform: String) async throws
+ public func computers() async throws -> [CloudComputer]
+ public func renameComputer(_ id: ComputerID, name: String) async throws
+ public func removeComputer(_ id: ComputerID) async throws
+ /// §4.2 B 3–5 全流程:commit → 等 hostNonce → reveal;回傳時 `code` 已可顯示。nD 只在記憶體。
+ public func requestAccess(_ id: ComputerID, signKey: String) async throws -> AccessTicket // requestId, expiresAt, code(SAS)
+ public func accessStatus(_ requestId: String) async throws -> AccessStatus // pending/approved/denied/expired/cancelled
+ public func cancelAccess(_ requestId: String) async throws
+ public func devices() async throws -> [CloudDevice]
+ public func revokeDevice(_ deviceId: String) async throws
+ public func grants(_ id: ComputerID) async throws -> [CloudGrant]
+ public func revokeGrant(_ id: ComputerID, grantId: String) async throws
+ public func createClaim() async throws -> ClaimChallenge
+ public func completeClaim(_ claimId: String, signed: ClaimSignature) async throws -> CloudComputer
+}
+public extension HostClient { // loopback-only 方法(Mac)
+ func claimSign(claimId: String, nonce: String, userId: String) async throws -> ClaimSignature
+ func accessRequests() async throws -> [AccessRequest]
+ func decideAccessRequest(_ id: String, approve: Bool) async throws
+ func devices() async throws -> [AuthorizedDevice]
+ func revokeDevice(_ key: String) async throws
+ func cloudStatus() async throws -> CloudStatus
+ func setCloud(enabled: Bool) async throws -> CloudStatus
+ func unclaim() async throws
+}
+
+// CodyncKit/Client/SharedStore.swift(取代既有的 pairing/computers/preferredURL/orderedPairing/usage/bots)
+public enum SharedStore {
+ public static let appGroup: String
+ public static let relayURL: String // APNs 推播 relay(不變)
+ public static var activeAccountID: String? { get set }
+ public static var activeContext: Context { get }
+ public struct Context {
+ public let accountID: String?
+ public var id: String { get } // digest(accountID) 或 "local"
+ public var computers: [Computer] { get nonmutating set }
+ public var bots: [BotSnapshot] { get nonmutating set } // BotSnapshot { computerId, bot }
+ public var usage: [ComputerID: Usage] { get nonmutating set }
+ public var lastComputerId: ComputerID? { get nonmutating set } // 最近活躍的 BotStore;Usage widget 只看這台
+ public func botURL(_ ref: BotReference) -> URL
+ public func reference(from url: URL) -> BotReference? // scope 不符或格式錯 → nil(取代 acceptsBotURL)
+ }
+ // 移除所有 static 的 pairing / computers / orderedPairing / preferredURL / usage / bots
+}
+// deep link 格式:codync://bot/<botId>?scope=<Context.id>&computer=<computerId>
+
+// CodyncUI/Store/BotStore.swift(調整)
+@MainActor @Observable public final class BotStore {
+ public enum Connection: Equatable {
+ case unpaired, connecting, online
+ case computerOffline(lastSeen: Date?) // 中繼說電腦不在線
+ case offline(String) // 完全連不到(無直連也無中繼)
+ case unauthorized(String) // 撤權/lease 到期/身分不符
+ }
+ // `isOffline` 對後三者為 true;`== .online` 的既有比較照常可用。
+ public enum Route: Sendable, Hashable { case loopback(baseURL: URL, token: String), channel }
+ /// `.channel` 時 BotStore 自己以 `DeviceIdentity.load(context: storage)` 取得身分。
+ public init(computer: Computer, route: Route, clientKind: String, storage: SharedStore.Context)
+ public private(set) var computer: Computer
+ public private(set) var client: HostClient?
+ public private(set) var connection: Connection
+ public private(set) var hostRoute: HostRoute?
+ public private(set) var accessRequests: [AccessRequest] // 只有 loopback 會有
+ public private(set) var cloud: CloudStatus? // 只有 loopback 會有
+ public var onConnected: (@MainActor (BotStore) -> Void)? // 取代 onPaired
+ public var onUsageChanged: (@MainActor (ComputerID, Usage) -> Void)?
+ public func cancelQueued(_ entry: Entry)
+ // 移除:pair(_:)、forget(_:)、unpair()、computers、pairing、persistsPairing
+}
+
+// CodyncUI/Store/AccountStore.swift(新增)
+@MainActor @Observable public final class AccountStore {
+ public init(storage: SharedStore.Context, clientKind: String, cloud: CloudClient?)
+ public let storage: SharedStore.Context
+ public var accountId: String? { storage.accountID }
+ public private(set) var computers: [Computer]
+ public private(set) var stores: [ComputerID: BotStore]
+ public private(set) var cloudComputers: [CloudComputer] // 帳號中但本機尚未授權者也列出
+ public private(set) var pendingAccess: [ComputerID: AccessTicket]
+ public var selection: BotReference?
+ public var roster: [RosterItem] { get } // 跨 computer 彙整、排序同 BotStore.roster
+ public func store(for id: ComputerID) -> BotStore?
+ public func pair(_ pairing: Pairing, deviceName: String, platform: String) async throws -> Computer
+ public func attach(_ computer: Computer, route: BotStore.Route) // Mac 本機/SSH
+ public func detach(_ id: ComputerID)
+ public func forget(_ id: ComputerID)
+ public func refreshCloud() async
+ public func requestAccess(_ id: ComputerID) async throws -> AccessTicket
+ public func setColor(_ id: ComputerID, _ color: String)
+ public func setActive(_ active: Bool)
+ public func retire()
+ public var onBotUpdated: (@MainActor (BotReference, Bot) -> Void)?
+ public var onConnected: (@MainActor (BotStore) -> Void)?
+ public var onSent: (@MainActor (BotReference, Bot) -> Void)?
+}
+public struct RosterItem: Identifiable, Sendable { public var ref: BotReference; public var bot: Bot; public var computer: Computer; public var id: BotReference { ref } }
+```
+型別欄位(`CloudComputer`、`AccessTicket`、`AccessStatus`、`AccessRequest`、`AuthorizedDevice`、`CloudStatus`、`ClaimChallenge`、`ClaimSignature`、`CloudAccount`、`CloudDevice`、`CloudGrant`、`QueuedItem`、`MailboxEvent`、`MailboxCancel`、`BotSnapshot`)直接對應 §7.4/§8.4/§9.4 的 JSON,`Codable` 解碼寬鬆(未知欄位忽略、選填欄位 optional)。以上簽章是最小集合;kit 可以多加,不能改名或改型別。
+
+### 10.2 實作要點
+
+- `LoopbackTransport`:今日 `HostClient.call`/`sse` 的邏輯搬過來(Bearer header,無 `?token=`)。
+- `ChannelTransport`(actor):WebSocket(`URLSessionWebSocketTask`)+ §6 加密+ §6.5 RPC 多工;`states()`、mailbox API 如上。收到 `4100` 時自動以一般模式重連。
+- `HostConnector.connect(computer:identity:)` 實作 §7.5;`HostConnector.pair(_:identity:deviceName:platform:)` 實作 §4.1。
+- `BotStore.runStream`:訂閱 `transport.states()` 推 `connection`;stream 以 `unreachable` 結束時以目前 `rev` 重新訂閱;`computerOffline` 時不做盲目退避,等 presence。`computerUpdates()` 的新值寫回 `computer` 並由 AccountStore 持久化。`send` 在 `computerOffline` 且有 `boxKey` 時:本地 entry `status = "waiting"`,成功入列後保持,`mbox.delivered` 後等 events 的正式 entry 取代(既有 clientNonce 取代邏輯),`failed`/`expired` → `"failed"`(可重試:重試 = 重新封裝、新的 `epk`,§6.4)。`cancelQueued` → 成功則移除本地 entry;`delivering` 顯示「已送出」。`status == "waiting"` 的本地 entry **要寫入快取**(重開 App 仍看得到並可取消),啟動時以 `listQueued()` 對帳。
+- 快取檔名改以 `computer.id` 取代 `pairing.token` 的 digest。`SharedStore.Context.computers` 不含任何秘密,可留在 App Group UserDefaults。舊資料不遷移,使用者重新配對。
+- `onUsageChanged` 寫 `storage.usage[computerId]`;BotStore 變成 active/送出訊息時寫 `storage.lastComputerId`。
+- `BotActivityAttributes` 新增 `computerId`;`ContentState.activity` 保留欄位但 host 永遠送空字串(§6.7)。
+- `ThreadView`、`BotRow`、`ChatRows`:顯示 `computerOffline`(「電腦目前離線,訊息會在它上線時送出」)、`unauthorized`、`waiting` 狀態(含取消按鈕,icon-only + accessibility label)。
+- kit 不依賴 ClerkKit;Clerk token 由 App 以 closure 注入 `CloudClient`。
+- Keychain:§3.2(macOS 不設 data protection keychain)。
+
+### 10.3 APPLE-KIT 測試(`swift test`)
+
+`remote-relay-vectors.json` 全欄位(握手、frame、chunk、mailbox、SAS commit/code、offer、Codync-Sig、push);mailbox 連續封裝兩次 `epk` 不同;`Pairing(url:)` 的 v3 解析與拒絕(`id` 不符、缺 `code`、`cloud` 非 https);`botURL`/`reference(from:)` 來回與跨 scope 拒絕;`states()` 多消費者;RPC 多工與取消(以假的 WebSocket);`BotStore` 在 `computerOffline` 時的 `waiting`/取消/到期;`AccountStore` 兩台 computer 相同 bot ID 不混淆、帳號切換後舊回覆不寫入。
+
+---
+
+## 11. APPLE-APPS track
+
+### 11.1 共通
+
+- `apps/shared/AccountSession.swift`:新增 `func sessionToken() async throws -> String`(ClerkKit 1.5.6 的 session token API,以實際 SDK 名稱為準)。
+- 設定檔:`ClerkConfig.plist` 改名為 `AccountConfig.plist`,keys `clerkPublishableKey`、`cloudURL`(目前填 staging URL);env `CODYNC_CLOUD_URL` 可覆寫。兩個 App 都要。
+- `project.yml`:`MARKETING_VERSION: 3.0.0`;iOS、Widgets、NotificationService 加 `keychain-access-groups: [$(AppIdentifierPrefix)com.pokai.Codync]`,Info.plist 加 `CodyncKeychainGroup`;新增 `NotificationService` app-extension target(`apps/ios/NotificationService/`,bundle id `com.pokai.Codync.ios.NotificationService`,依賴 CodyncKit,embed 進 iOS App);macOS **不加** entitlements(§3.2);改完執行 `xcodegen generate`。
+- `.github/workflows/release-macos.yml`:配合 `AccountConfig.plist` 改名。
+
+### 11.2 iOS
+
+- `AppStore` 改持有 `AccountStore`(取代單一 `BotStore`);`RootView` 以 `accountStore.selection` 導覽,進入聊天時把 `accountStore.store(for: ref.computerId)` 注入 `ThreadView` 的 environment。
+- Bot 清單:`accountStore.roster`,每列顯示 computer 名稱與其連線狀態(單台離線不影響其他)。
+- 新增 bot:先選 computer(只列 online 的),再開 `BotEditorView`(用該 computer 的 store)。
+- Computers 頁(取代 `SettingsView` 的電腦區):本機配對與帳號電腦合併(依 `computerId`);每台分別顯示「已加入帳號/已授權/可連線(直連/中繼)」;未授權的帳號電腦顯示「申請存取」→ 顯示 SAS 並輪詢;支援移除、改色、撤銷(帳號)。
+- Pairing:`AccountStore.pair`;文案改為「不需要 Tailscale;在家用 Wi-Fi 直連,其他地方透過加密中繼」,Tailscale 步驟移為選配說明。
+- 推播:`PushRegistrar` 對每個 `onConnected` 的 store 呼叫 `registerDevice {ticket, name, relay, pushKey: identity.pushKey, ctx: storage.id}`;通知點擊以 `userInfo["ctx"]`、`["computerId"]`、`["botId"]` 組 `BotReference`,只有 `ctx == storage.id` 且 computer 屬於目前 context 才導覽。
+- NotificationService:`DeviceIdentity.openPush(sealed:computerId:contextID:)` 成功 → 替換 title/body;失敗保留通用文字。30 秒內完成,不做網路。
+- Widgets:從 `SharedStore.Context` snapshot 顯示(`bots` 為 `[BotSnapshot]`);Usage widget 只顯示 `usage[lastComputerId]`,重新整理時只對 `lastComputerId` 那台 `HostConnector.connect` + `usage` 單次呼叫(直連或中繼),失敗用快取。Live Activity 只顯示狀態(沒有 activity 文字)。deep link 用 `botURL(BotReference)`。
+- 登入後:`CloudClient.registerDevice` → `refreshCloud`。登出/切換:`retire()`、刪該 context 的 device key 與快取(§3.2)。
+
+### 11.3 macOS
+
+- `HostController` 保留本機 host 管理;本機 store 以 `.loopback(baseURL: 127.0.0.1:port, token:)` attach 到 Mac 的 `AccountStore`。Mac 也有自己的 device key,可經 channel 連帳號中的其他電腦。
+- 核准介面:本機(與每條 SSH)store 的 `accessRequests` 非空 → 選單列圖示加提示、跳出核准 sheet(裝置名稱、平台、email、SAS 大字、Approve/Deny 文字按鈕;`code == nil`(對方尚未揭露)時顯示等待中、Approve 停用)。
+- 帳號:「將這台 Mac 加入帳號」(claim 流程 §4.2 A)、「移出帳號」(`unclaim`)、「已授權裝置」清單與撤銷(`devices`/`revokeDevice`)、「可從任何地方連線」開關(`setCloud`),並顯示 `cloudStatus`。
+- `ChatWindow` sidebar 顯示跨 computer bots,新增 bot 先選 computer。
+
+### 11.4 SSH(`apps/macos/App/SSHTunnel.swift` 等)
+
+- Profile(非秘密,存 UserDefaults):`id`、`alias` 或 `hostname`、`port`、`user`、`identityFile?`、`remotePort`(預設 19222)、`computerId`(首次連線後記住)、`name`。
+- 輸入驗證:hostname/alias `^[A-Za-z0-9._-]+$` 且不以 `-` 開頭;user `^[A-Za-z_][A-Za-z0-9._-]*$`;port 1–65535;identityFile 必須是存在的檔案。以 `Process` 的 argv 陣列傳遞,**永不**經 shell 組字串。
+- App 的 known_hosts:`~/.codync/ssh_known_hosts`(路徑無空白)。每個 ssh 呼叫都帶這組 argv(兩個元素;值內以**字面雙引號**包住絕對路徑,因為 ssh 自己的 config tokenizer 會以空白切開 `UserKnownHostsFile`,argv quoting 無效):
+ `-o`, `UserKnownHostsFile="<HOME>/.ssh/known_hosts" "<HOME>/.codync/ssh_known_hosts"`,以及 `-o`, `StrictHostKeyChecking=yes`。
+- 解析目標:先跑 `ssh -G [-p port] [-l user] -- <dest>`,取 `hostname`、`port`、`hostkeyalias`、`proxyjump`、`proxycommand`。known_hosts 查詢名稱 = `hostkeyalias` 或 `hostname`,port ≠ 22 時寫成 `[name]:port`。
+- Host key 判定(不解析 ssh 的 stderr 文字):
+ 1. `ssh-keygen -F <name> -f <file>` 對兩個 known_hosts 檔各查一次。
+ 2. 找到 → 直接連線(`StrictHostKeyChecking=yes` 由 ssh 自己把關)。
+ 3. 沒找到且未設 `proxyjump`/`proxycommand` → `ssh-keyscan -p <port> -- <hostname>`,以 `ssh-keygen -lf -` 顯示指紋請使用者確認 → 以 `<name>` 為主機名寫入 `~/.codync/ssh_known_hosts`。
+ 4. 沒找到但設了 proxy → 不 keyscan,提示「請先在終端機以 ssh 連線一次以確認主機金鑰」(見 §0 取捨)。
+ 5. 找到了但連線以 exit 255 失敗、且 keyscan(無 proxy 時)取得的金鑰都不在已記錄的條目中 → 判定為**主機金鑰已變更**,阻擋並說明,不提供略過。
+- 取得遠端資訊:`ssh <opts> -- <dest> "sh -lc 'codync-host info --json'"`(固定字串,無使用者輸入)。解析失敗 → 「遠端未安裝 codync-host」並顯示安裝指令(複製按鈕;不自動安裝)。
+- Tunnel:`ssh -N -T -o ExitOnForwardFailure=yes -o ServerAliveInterval=15 -o ServerAliveCountMax=3 -o ForwardAgent=no -o ForwardX11=no -o BatchMode=yes -o StrictHostKeyChecking=yes -o 'UserKnownHostsFile="…" "…"' -L 127.0.0.1:<localPort>:127.0.0.1:<remotePort> [-p port] [-i key] [-l user] -- <dest>`;localPort 以綁定 port 0 取得。監看 process,斷線以 1→30 s 退避重啟;`computerId` 與 profile 記錄不符 → 停止並警告。
+- 連上後:`AccountStore.attach(computer, route: .loopback(baseURL: 127.0.0.1:localPort, token: token))`;token 每次連線以 `info --json` 取得,不持久化。
+- 多個 bots 共用一條 tunnel;只有 detach/移除 profile 才終止。
+- 遠端 host 也可自行連雲端中繼:Mac 經 tunnel 呼叫 `pairing` 顯示 QR 給手機、或 `claimSign` 將遠端加入帳號。
+
+### 11.5 APPLE-APPS 測試
+
+編譯 iOS/macOS/Widgets;UI 流程手動驗收(§12.2);SSH argv 組裝(含 `UserKnownHostsFile` 的字面雙引號與 `ssh -G` 輸出解析)與輸入驗證寫成可測的純函式並附單元測試(放在 `kit/Tests` 以外時,至少在 DEBUG 啟動時跑 `assert`-based self-check)。
+
+---
+
+## 12. 跨 track 驗證
+
+### 12.1 整合測試(CLOUD 擁有:`cloud/test/e2e/relay.e2e.ts`,`npm run e2e`)
+
+1. `wrangler d1 migrations apply codync-dev --local --env dev`;測試產生 RSA 金鑰,將公鑰 PEM 設為 `CLERK_JWT_KEY` 啟動 `wrangler dev --env dev --port 8787`。
+2. 以 `CODYNC_HOME=<tmp> CODYNC_CLOUD_URL=http://127.0.0.1:8787` 啟動 `host/target/debug/codync-host serve --bind 127.0.0.1 --port <free>`。
+3. 等 D1 出現 computer 列、DO presence online。
+4. TS 假手機:loopback `pairing` 取 URL → 以 `pair=<offerId>` 走中繼 → `pair` → `hello` → `createBot`(backend `custom`,command 為 `python3 host/tests/fake_agent.py`)→ `events` 訂閱 → `send` → 收到 agent 回覆。
+5. 關閉 host → device 收到 `presence online:false` → `mbox.put` 一則 `send` → `mbox.cancel` 另一則 → 重啟 host → 收到 `mbox.delivered`、events 出現該 clientNonce 的 entry、被取消的不存在。
+6. 帳號流程:自簽 JWT → `POST /v1/claims` → loopback `claimSign` → complete → 第二支假手機 `POST /v1/devices` → access request(commit)→ 等 hostNonce → reveal → loopback `accessRequests` 的 `code` 等於手機算出的 SAS → `decideAccessRequest` → 以中繼連線成功 → `DELETE …/grants/{id}` → 1 秒內 socket 以 `4003` 關閉 → host 重連後(state 拉取前後)該 dk 都無法再連。
+6b. 雲端惡意注入:直接在 D1 插入一筆 grant(第三把 key)→ host 拉 state 後該 key 仍被拒、ACL 不含它。
+6c. pairing 經中繼:`pair` 回應後 link 以 `4100` 關閉,假手機以一般模式重連成功,且可超過 16 則訊息。
+7. 直連:同一假手機以 `ws://127.0.0.1:<port>/channel` 握手成功;以非 loopback 位址用 bearer token 呼叫 `/api/hello` → 401。
+
+### 12.2 手動驗收(owner + 實機)
+
+兩個 Google 帳號、兩支 iPhone(或模擬器 + 實機)、一台 Mac、一台 Linux(SSH)。
+
+---
+
+## 13. 驗收條件
+
+- 手機在行動網路(無 Tailscale)可與家中 NAT 後的 Mac 聊天、stop、回應權限、開 remote screen 訊號;`cloud` Worker log、DO storage 與 `relay/` 推播 Worker 收到的 body 中都找不到任何明文訊息、bot 名稱、token 或 pairing code。
+- 同一 Wi-Fi 下自動走直連(UI 顯示直連);離開 Wi-Fi 後在 10 秒內改走中繼且不重複訊息。
+- 帳號裝置在電腦離線超過 15 分鐘後仍看得到「電腦離線」並可排入 mailbox。
+- 電腦睡眠:手機顯示「電腦離線(上次 …)」而不是「連不到」;送出的訊息顯示「等待電腦上線」可取消;電腦醒來後依序送出、每則只執行一次;24 小時後未送出者顯示失敗。
+- 未登入:QR 配對後同樣可經中繼使用;登入不會自動宣告本機配對的電腦。
+- 帳號:新手機申請 → Mac 顯示相同 SAS → 核准 → 可連線;撤銷後 5 秒內(host 在線)斷線,host 連不到雲端時最長 15 分鐘失效;手機 B 不受影響。
+- 另一帳號猜到 computerId/requestId/grantId 仍全部 404。
+- 非 loopback 的 bearer token 一律 401;`setScreenEnabled`、`pairing`、`claimSign` 等經 channel 呼叫一律 403。
+- 多 computer:本機 bot 與 SSH bot 並列,兩台有相同 bot ID 時 send/stop 不會送錯;SSH host key 變更時阻擋。
+- CI:`cargo fmt --check`、`cargo clippy --all-targets -- -D warnings`、`cargo test`;`cloud`:`npm run typecheck && npm test`;`swift test`(kit);Xcode 三個 target 可編譯。
+
+---
+
+## 14. 部署(staging 可由實作者執行;production 需 owner 確認)
+
+### 14.1 Staging
+
+```bash
+cd cloud && npm ci
+npx wrangler d1 create codync-staging # 將 database_id 填入 [env.staging]
+npx wrangler d1 migrations apply codync-staging --env staging --remote
+npx wrangler secret put CLERK_SECRET_KEY --env staging # owner 輸入 sk_test_…
+npx wrangler secret put CLERK_WEBHOOK_SECRET --env staging # owner 輸入 whsec_…
+npx wrangler deploy --env staging # → https://codync-cloud-staging.<account subdomain>.workers.dev
+```
+Host 測 staging:`codync-host cloud --url https://codync-cloud-staging.<sub>.workers.dev`(或 env `CODYNC_CLOUD_URL`)。Apple:`AccountConfig.plist` 的 `cloudURL`。
+
+### 14.2 Secrets 與 vars
+
+| 名稱 | 種類 | 說明 |
+|---|---|---|
+| `CLERK_SECRET_KEY` | secret(owner 輸入) | `verifyToken` 取 JWKS 用 |
+| `CLERK_WEBHOOK_SECRET` | secret(owner 輸入) | Svix 簽章 |
+| `CLERK_ISSUER` | var | Clerk Frontend API URL |
+| `CLERK_AUTHORIZED_PARTIES` | var(選填) | 逗號分隔 |
+| `CLERK_JWT_KEY` | var(只給 dev/e2e) | networkless 驗證用的公鑰 PEM;staging/production 不設 |
+
+### 14.3 Owner 手動步驟
+
+0. 允許實作者建立 staging 資源:`wrangler login` 已登入的 Cloudflare 帳號(或提供 `CLOUDFLARE_API_TOKEN`,權限 Workers Scripts:Edit、D1:Edit、Durable Objects)。
+1. Clerk Dashboard(staging = `sunny-mollusk-8651`):確認 iOS native app(`com.pokai.Codync.ios`)已註冊並允許 `com.pokai.Codync.ios://callback`;**Sessions → Customize session token** 加入 `{"email": "{{user.primary_email_address}}"}`;**Webhooks** 新增 `https://codync-cloud-staging.<sub>.workers.dev/v1/webhooks/clerk`,訂閱 `user.deleted`,複製 signing secret。
+2. 輸入上面兩個 secrets。
+3. Production:另建 Clerk production instance、`wrangler d1 create codync`、填 `wrangler.toml` 頂層、secrets 不加 `--env`、`npx wrangler deploy`;把 production URL 填入 `host/src/cloud.rs` 的 `DEFAULT_CLOUD_URL` 與 Release 版 `AccountConfig.plist`。
+4. Apple Developer:新增 `com.pokai.Codync.ios.NotificationService` App ID 與 keychain access group 後,讓 Xcode 自動簽章更新 provisioning profiles。
+5. `relay/` 的 `mutableContent` 變更需重新部署推播 Worker(`cd relay && npx wrangler deploy`,現有 production;需 owner 確認)。
+
+---
+
+## 15. 風險與未決
+
+| 風險 | 說明/緩解 |
+|---|---|
+| 帳號流程的 host 公鑰由雲端傳遞 | 被攻破的 Worker 可換公鑰做 MITM;commit-then-reveal SAS 讓每次嘗試只有 10⁻⁶ 成功率,但前提是使用者真的比對。UI 必須把 SAS 放大並要求明確按 Approve。QR 流程不受影響。 |
+| 推播 metadata | APNs/`relay/` 看得到 botId、computerId、context id、kind 與時間;內容已封裝(D10)。 |
+| Worker/DO 可見 metadata | computerId、deviceKey、連線時間、訊息大小與頻率、mailbox 的 clientNonce 與失敗碼。文件與隱私說明需如實寫。 |
+| 任何人可產生金鑰並註冊 computer | register 依 IP 限流、`computers.status='blocked'` 可封鎖;費用告警需在 production 前設定。 |
+| `identity.json` 被複製 | 兩台機器搶同一 DO → `4009 replaced` 互踢並記錄錯誤;不自動修復。 |
+| ClerkKit/Workers 限制 | ClerkKit session token API 名稱、Workers Rate Limiting binding、WebSocket 1 MiB 上限需在實作時對照當時文件;chunk 256 KiB 預留空間。 |
+| `hkdf`/`sha2` 版本 | 見 §9.1。 |
+| 協定升級 | 手機↔host 升 major 3;2.x App 需要更新才能連 3.x host。 |
+| Production URL 未定 | `DEFAULT_CLOUD_URL = None` 時雲端停用(只有 QR + 直連);production 部署時填入 host 常數與 Release 設定檔。 |
+| host 撤銷帳號裝置但 `POST /v1/host/grants/{id}/revoke` 失敗 | 本機已撤銷且 state 不能把它加回(§4.3),D1 只是顯示仍 granted;下次成功時補送。 |
+| 直連 LAN 的 `ws://` | 內容已 E2E;但 metadata(連線、大小)在 LAN 可見,可接受。 |
diff --git a/docs/remote-relay-vectors.json b/docs/remote-relay-vectors.json
new file mode 100644
index 00000000..9213d922
--- /dev/null
+++ b/docs/remote-relay-vectors.json
@@ -0,0 +1,109 @@
+{
+ "about": "Codync relay protocol v1 (spec rev 2) test vectors. All binary values are base64url without padding. Private keys are 32-byte seeds/scalars.",
+ "keys": {
+ "hostSignSeed": "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE",
+ "hostSignPub": "iojj3XQJ8ZX9UtstPLpdcspnCb8dlBIb83SIAbQPb1w",
+ "hostBoxPriv": "AgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgI",
+ "hostBoxPub": "zo060cy2M-x7cMF4FKXHbs0CloUFDTRHRboFhw5YfVk",
+ "deviceSignSeed": "AwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwM",
+ "deviceSignPub": "7UkoxijRwsbq6QM4kFmVYSlZJzpcY_k2NsFGFKyHN9E",
+ "computerId": "NHUPmL1Z_PyUbaRaqr6TOw"
+ },
+ "handshake": {
+ "deviceEphPriv": "BAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQ",
+ "deviceEphPub": "rAGyIJ6GNU-4UyN7XeD0-rE8f8v0M6YcAZNpYX_s8Qs",
+ "hostEphPriv": "BQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQU",
+ "hostEphPub": "UKYUCbHd0DJemxa3AOcZ6XcsBwALG9d4bpB8ZT0gSV0",
+ "n": "BgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgY",
+ "hs1SignInput": "Y29keW5jL2hzMS92MTR1D5i9Wfz8lG2kWqq-kzvtSSjGKNHCxurpAziQWZVhKVknOlxj-TY2wUYUrIc30awBsiCehjVPuFMje13g9PqxPH_L9DOmHAGTaWF_7PELBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgY",
+ "hs1Sig": "7F0tTLaOB5xiRkBtZ5qnqVitvXGT4TJh6WVmAxhX9zfN3M_HCZEKcaOcDrwFUhAQVlbqrIW2EKlEC-pSmnC9Bw",
+ "transcriptHash": "Izf0n0agxBlQtGgceW_Kg92x36o7eECmXx1gq6akjEQ",
+ "hs2Sig": "uuLbU1qoC5QVTFiUshIAgvfqfsiG1L8By0JLFKdvUHbtIcZI3C0FQ-gAK-dcoVnR04kpcVts4cqYyGhLN-aGCw",
+ "sharedSecret": "WFV1gOHNAQ2R6bm_vIrq8ARYNa0kD15AN6i6DRpQJQ4",
+ "prk": "2dhjsdsI1b_jaotlvs-J5EbUJguOrqmdIfXw6x_DdnY",
+ "kD2H": "1HJ_53qNQs1iYvYSgA6TICF9PXYnWqTttX50iKDak6g",
+ "kH2D": "ufkpFHql7P2nGlgxMnLUkfj2rndwSyYkV6qBXQYaBwk"
+ },
+ "frames": [
+ {
+ "dir": "d2h",
+ "c": 0,
+ "final": true,
+ "message": "{\"id\":1,\"m\":\"hello\",\"b\":{}}",
+ "plaintext": "AHsiaWQiOjEsIm0iOiJoZWxsbyIsImIiOnt9fQ",
+ "d": "msFbawc5vuzGzQ2jEFqHufWb4Sd_psneSeURptNDkZlg_QdiJ4xQrmkmKv4"
+ },
+ {
+ "dir": "h2d",
+ "c": 0,
+ "final": true,
+ "message": "{\"id\":1,\"ok\":{\"name\":\"Mac\"}}",
+ "plaintext": "AHsiaWQiOjEsIm9rIjp7Im5hbWUiOiJNYWMifX0",
+ "d": "aRQzFj9U3b0gaEI0BPe9aIN_ZrYg7z-9vxCYxaNWh0mO88lc3ui4z77mh9ad"
+ },
+ {
+ "dir": "d2h",
+ "c": 1,
+ "final": false,
+ "message": "{\"id\":2,\"m\":\"se",
+ "plaintext": "AXsiaWQiOjIsIm0iOiJzZQ",
+ "d": "T_ah29RGkMAVrbIAaAskC_TRqsk2cZ4_9R_UZPdxNmk"
+ }
+ ],
+ "sas": {
+ "deviceNonce": "CgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgo",
+ "hostNonce": "CwsLCwsLCwsLCwsLCwsLCwsLCwsLCwsLCwsLCwsLCws",
+ "commit": "DYyvV-_e0NX_aq9NHh9_hexs6X7Q9zozrrV_4XgaDmk",
+ "code": "919055"
+ },
+ "claim": {
+ "claimId": "clm_AAAAAAAAAAAAAAAAAAAAAA",
+ "nonce": "DAwMDAwMDAwMDAwMDAwMDA",
+ "userId": "user_2abc",
+ "computerId": "NHUPmL1Z_PyUbaRaqr6TOw",
+ "boxKey": "zo060cy2M-x7cMF4FKXHbs0CloUFDTRHRboFhw5YfVk",
+ "canonical": "codync/claim/v1\nclm_AAAAAAAAAAAAAAAAAAAAAA\nDAwMDAwMDAwMDAwMDAwMDA\nuser_2abc\nNHUPmL1Z_PyUbaRaqr6TOw\nzo060cy2M-x7cMF4FKXHbs0CloUFDTRHRboFhw5YfVk",
+ "sig": "PcyiODIPeoD-QQMPInP1cyeutGpZa5gx9v5ako5VUpiGqVpjNZ_rbVygjnFEk71Qccu6E1Pp7jByp1b7FgZqAg"
+ },
+ "push": {
+ "pushPriv": "DAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAw",
+ "pushPub": "l8OxC01sEzp46l3MHPZCHT-Brjex9ijOFMpvzncw8zM",
+ "ephPriv": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0",
+ "ephPub": "sweuhmDvrtTWpl9mQIlokupKHwB1VVxInRMSouFnfCg",
+ "sharedSecret": "st-FN3PPuxd81A7OMYloqcdkTOQVUxVLKXbvq9X4gy4",
+ "key": "L-Qewn801bLGsFMtGGhRzSeO_3rvf9iE7gvfZYdItbc",
+ "plaintext": "{\"title\":\"Reviewer\",\"body\":\"Run cargo test --all?\"}",
+ "sealed": "sweuhmDvrtTWpl9mQIlokupKHwB1VVxInRMSouFnfCgCZ8_grq-NNgg0Hluwk_c4tGIEcdY8N9JFqwH1LSn_rrQ3WjWwJoA70jCx_CLV8uIkxfDuP_Y0KBoFuqHRciLzJGga"
+ },
+ "pairing": {
+ "code": "CAgICAgICAgICAgICAgICA",
+ "offerId": "kO-TaDO8k1QnECGLj3N78A"
+ },
+ "mailbox": {
+ "ephPriv": "BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc",
+ "ephPub": "E75P6uryBMf9M1j8nAByGIHRdCeBKCJ-xnTzf3_pe20",
+ "clientNonce": "3F2504E0-4F89-11D3-9A0C-0305E82C3301",
+ "sharedSecret": "WG952knp7uq_wxJyfAEyBevU2AAPUHJajs56QBlVmik",
+ "key": "qlg6JHw_7N4scGwdrFWnUHmtiPvzFiXKxnXGbTmUnEE",
+ "plaintext": "{\"m\":\"send\",\"b\":{\"botId\":\"b1\",\"text\":\"hi\",\"clientNonce\":\"3F2504E0-4F89-11D3-9A0C-0305E82C3301\"},\"ts\":1790000000000}",
+ "ciphertext": "A6jcZA_zeme5U7SVSHdZeDGyFxiQsGXSWnCqc4BVS6gmyCqNpP8z3YbI6rRwMduLloB97ouQMs6Ffkj8b76Rxvmj3IdJOhUBrmYYDxCQLgTaeWbQ-huBE0oT8mmnJvN_cwJLrnnlZRB35h2EjZJjYbz82sFLQ8sATZg_umR5YxYAwog",
+ "sig": "c1pqDRq0IiuUlnP7rhRTrvh0WGPGTGGKqYprLZoVFLHYyRh7QeGqqz0xdI52a0ssY7rY-RHodfxtEVgwwcR4Dw",
+ "blob": "E75P6uryBMf9M1j8nAByGIHRdCeBKCJ-xnTzf3_pe21zWmoNGrQiK5SWc_uuFFOu-HRYY8ZMYYqpimstmhUUsdjJGHtB4aqrPTF0jnZrSyxjutj5Eeh1_G0RWDDBxHgPA6jcZA_zeme5U7SVSHdZeDGyFxiQsGXSWnCqc4BVS6gmyCqNpP8z3YbI6rRwMduLloB97ouQMs6Ffkj8b76Rxvmj3IdJOhUBrmYYDxCQLgTaeWbQ-huBE0oT8mmnJvN_cwJLrnnlZRB35h2EjZJjYbz82sFLQ8sATZg_umR5YxYAwog"
+ },
+ "requestSig": {
+ "method": "GET",
+ "authority": "codync-cloud-staging.example.workers.dev",
+ "pathAndQuery": "/v1/relay/device/NHUPmL1Z_PyUbaRaqr6TOw?v=1",
+ "ts": 1790000000000,
+ "nonce": "CQkJCQkJCQkJCQkJCQkJCQ",
+ "bodySha256": "47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU",
+ "canonical": "codync-sig-v1\nGET\ncodync-cloud-staging.example.workers.dev\n/v1/relay/device/NHUPmL1Z_PyUbaRaqr6TOw?v=1\n1790000000000\nCQkJCQkJCQkJCQkJCQkJCQ\n47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU",
+ "sig": "mVB9S1-w-cbCdvnhUlKSE2BDPL1nhlAsk5nTZWcVNEb9_-czaBck0eDSJvLLh25YgG11I1zqA0CHKUoGEKu2DA",
+ "header": "Codync-Sig: v=1,kid=7UkoxijRwsbq6QM4kFmVYSlZJzpcY_k2NsFGFKyHN9E,ts=1790000000000,nonce=CQkJCQkJCQkJCQkJCQkJCQ,sig=mVB9S1-w-cbCdvnhUlKSE2BDPL1nhlAsk5nTZWcVNEb9_-czaBck0eDSJvLLh25YgG11I1zqA0CHKUoGEKu2DA"
+ },
+ "acl": {
+ "json": "{\"v\":1,\"computerId\":\"NHUPmL1Z_PyUbaRaqr6TOw\",\"ver\":1,\"devices\":[{\"dk\":\"7UkoxijRwsbq6QM4kFmVYSlZJzpcY_k2NsFGFKyHN9E\",\"grant\":null}],\"offers\":[{\"id\":\"kO-TaDO8k1QnECGLj3N78A\",\"exp\":1790000600000}]}",
+ "d": "eyJ2IjoxLCJjb21wdXRlcklkIjoiTkhVUG1MMVpfUHlVYmFSYXFyNlRPdyIsInZlciI6MSwiZGV2aWNlcyI6W3siZGsiOiI3VWtveGlqUndzYnE2UU00a0ZtVllTbFpKenBjWV9rMk5zRkdGS3lITjlFIiwiZ3JhbnQiOm51bGx9XSwib2ZmZXJzIjpbeyJpZCI6ImtPLVRhRE84azFRbkVDR0xqM043OEEiLCJleHAiOjE3OTAwMDA2MDAwMDB9XX0",
+ "sig": "y0Nxt8C-i61TVgZwiLIId70FrkMkMdsLXHiEvPpPfXZFP443QGbAUfrD0HESW93Dmje-N8Rk1nDA3yK3fM5vCQ"
+ }
+}
diff --git a/docs/remote-relay-vectors.py b/docs/remote-relay-vectors.py
new file mode 100644
index 00000000..336ec258
--- /dev/null
+++ b/docs/remote-relay-vectors.py
@@ -0,0 +1,138 @@
+# Generates docs/remote-relay-vectors.json (Codync relay crypto, protocol v1 (spec rev 2)).
+import base64, hashlib, json, struct
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF, HKDFExpand
+from cryptography.hazmat.primitives import hashes, hmac
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+b64 = lambda b: base64.urlsafe_b64encode(b).rstrip(b"=").decode()
+raw = lambda k: k.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+sha = lambda b: hashlib.sha256(b).digest()
+
+def extract(salt, ikm):
+ h = hmac.HMAC(salt, hashes.SHA256()); h.update(ikm); return h.finalize()
+def expand(prk, info, n=32):
+ return HKDFExpand(hashes.SHA256(), n, info).derive(prk)
+
+host_sign = Ed25519PrivateKey.from_private_bytes(b"\x01"*32)
+host_box = X25519PrivateKey.from_private_bytes(b"\x02"*32)
+dev_sign = Ed25519PrivateKey.from_private_bytes(b"\x03"*32)
+dev_eph = X25519PrivateKey.from_private_bytes(b"\x04"*32)
+host_eph = X25519PrivateKey.from_private_bytes(b"\x05"*32)
+n = b"\x06"*32
+mbox_eph = X25519PrivateKey.from_private_bytes(b"\x07"*32)
+code = b"\x08"*16
+sig_nonce = b"\x09"*16
+
+hk, bk, dk, ekd, ekh = raw(host_sign), raw(host_box), raw(dev_sign), raw(dev_eph), raw(host_eph)
+cid = sha(hk)[:16]
+
+hs1_input = b"codync/hs1/v1" + cid + dk + ekd + n
+hs1_sig = dev_sign.sign(hs1_input)
+th = sha(b"codync/hs2/v1" + cid + dk + ekd + n + ekh)
+hs2_sig = host_sign.sign(th)
+shared = dev_eph.exchange(X25519PublicKey.from_public_bytes(ekh))
+assert shared == host_eph.exchange(X25519PublicKey.from_public_bytes(ekd))
+prk = extract(th, shared)
+k_d2h = expand(prk, b"codync/d2h/v1")
+k_h2d = expand(prk, b"codync/h2d/v1")
+
+def frame(key, counter, flag, msg):
+ nonce = b"\x00"*4 + struct.pack(">Q", counter)
+ aad = b"codync/frame/v1" + struct.pack(">Q", counter)
+ pt = bytes([flag]) + msg.encode()
+ return b64(ChaCha20Poly1305(key).encrypt(nonce, pt, aad)), b64(pt)
+
+req = '{"id":1,"m":"hello","b":{}}'
+res = '{"id":1,"ok":{"name":"Mac"}}'
+f_d2h0 = frame(k_d2h, 0, 0, req)
+f_h2d0 = frame(k_h2d, 0, 0, res)
+f_d2h1_more = frame(k_d2h, 1, 1, '{"id":2,"m":"se')
+
+# SAS: commit-then-reveal (device commits to nd before it sees nh)
+nd = b"\x0a"*32
+nh = b"\x0b"*32
+sas_commit = sha(b"codync/sascommit/v1" + dk + nd)
+sas_n = struct.unpack(">I", sha(b"codync/sas/v2" + hk + dk + nd + nh)[:4])[0] % 1_000_000
+offer = sha(b"codync/offer/v1" + code)[:16]
+
+# mailbox
+epk = raw(mbox_eph)
+mshared = mbox_eph.exchange(X25519PublicKey.from_public_bytes(bk))
+client_nonce = "3F2504E0-4F89-11D3-9A0C-0305E82C3301"
+mprk = extract(b"codync/mbox/v1" + cid + dk + epk, mshared)
+mkey = expand(mprk, b"codync/mbox-key/v1")
+mpt = '{"m":"send","b":{"botId":"b1","text":"hi","clientNonce":"%s"},"ts":1790000000000}' % client_nonce
+mct = ChaCha20Poly1305(mkey).encrypt(b"\x00"*12, mpt.encode(), dk + client_nonce.encode())
+msig = dev_sign.sign(b"codync/mbox/v1" + cid + epk + mct)
+blob = epk + msig + mct
+
+# Codync-Sig request signing
+path = "/v1/relay/device/%s?v=1" % b64(cid)
+ts = 1790000000000
+authority = "codync-cloud-staging.example.workers.dev"
+canon = "codync-sig-v1\nGET\n%s\n%s\n%d\n%s\n%s" % (authority, path, ts, b64(sig_nonce), b64(sha(b"")))
+req_sig = dev_sign.sign(canon.encode())
+header = "v=1,kid=%s,ts=%d,nonce=%s,sig=%s" % (b64(dk), ts, b64(sig_nonce), b64(req_sig))
+
+# ACL
+acl = json.dumps({"v":1,"computerId":b64(cid),"ver":1,"devices":[{"dk":b64(dk),"grant":None}],"offers":[{"id":b64(offer),"exp":ts+600000}]}, separators=(",",":"))
+acl_sig = host_sign.sign(acl.encode())
+
+# claim signature (UTF-8, "\n"-separated, no trailing newline)
+claim_canon = "codync/claim/v1\n%s\n%s\n%s\n%s\n%s" % ("clm_AAAAAAAAAAAAAAAAAAAAAA", "DAwMDAwMDAwMDAwMDAwMDA", "user_2abc", b64(cid), b64(bk))
+claim_sig = host_sign.sign(claim_canon.encode())
+
+# sealed push payload (host -> phone via APNs, opened in the Notification Service Extension)
+push_priv = X25519PrivateKey.from_private_bytes(b"\x0c"*32)
+push_pub = raw(push_priv)
+push_eph = X25519PrivateKey.from_private_bytes(b"\x0d"*32)
+pepk = raw(push_eph)
+pshared = push_eph.exchange(X25519PublicKey.from_public_bytes(push_pub))
+pprk = extract(b"codync/push/v1" + cid + push_pub + pepk, pshared)
+pkey = expand(pprk, b"codync/push-key/v1")
+ppt = '{"title":"Reviewer","body":"Run cargo test --all?"}'
+pct = ChaCha20Poly1305(pkey).encrypt(b"\x00"*12, ppt.encode(), cid)
+
+out = {
+ "about": "Codync relay protocol v1 (spec rev 2) test vectors. All binary values are base64url without padding. Private keys are 32-byte seeds/scalars.",
+ "keys": {
+ "hostSignSeed": b64(b"\x01"*32), "hostSignPub": b64(hk),
+ "hostBoxPriv": b64(b"\x02"*32), "hostBoxPub": b64(bk),
+ "deviceSignSeed": b64(b"\x03"*32), "deviceSignPub": b64(dk),
+ "computerId": b64(cid),
+ },
+ "handshake": {
+ "deviceEphPriv": b64(b"\x04"*32), "deviceEphPub": b64(ekd),
+ "hostEphPriv": b64(b"\x05"*32), "hostEphPub": b64(ekh),
+ "n": b64(n),
+ "hs1SignInput": b64(hs1_input), "hs1Sig": b64(hs1_sig),
+ "transcriptHash": b64(th), "hs2Sig": b64(hs2_sig),
+ "sharedSecret": b64(shared), "prk": b64(prk),
+ "kD2H": b64(k_d2h), "kH2D": b64(k_h2d),
+ },
+ "frames": [
+ {"dir":"d2h","c":0,"final":True,"message":req,"plaintext":f_d2h0[1],"d":f_d2h0[0]},
+ {"dir":"h2d","c":0,"final":True,"message":res,"plaintext":f_h2d0[1],"d":f_h2d0[0]},
+ {"dir":"d2h","c":1,"final":False,"message":'{"id":2,"m":"se',"plaintext":f_d2h1_more[1],"d":f_d2h1_more[0]},
+ ],
+ "sas": {"deviceNonce": b64(nd), "hostNonce": b64(nh), "commit": b64(sas_commit), "code": "%06d" % sas_n},
+ "claim": {"claimId": "clm_AAAAAAAAAAAAAAAAAAAAAA", "nonce": "DAwMDAwMDAwMDAwMDAwMDA", "userId": "user_2abc",
+ "computerId": b64(cid), "boxKey": b64(bk), "canonical": claim_canon, "sig": b64(claim_sig)},
+ "push": {"pushPriv": b64(b"\x0c"*32), "pushPub": b64(push_pub), "ephPriv": b64(b"\x0d"*32), "ephPub": b64(pepk),
+ "sharedSecret": b64(pshared), "key": b64(pkey), "plaintext": ppt, "sealed": b64(pepk + pct)},
+ "pairing": {"code": b64(code), "offerId": b64(offer)},
+ "mailbox": {
+ "ephPriv": b64(b"\x07"*32), "ephPub": b64(epk), "clientNonce": client_nonce,
+ "sharedSecret": b64(mshared), "key": b64(mkey),
+ "plaintext": mpt, "ciphertext": b64(mct), "sig": b64(msig), "blob": b64(blob),
+ },
+ "requestSig": {
+ "method":"GET","authority":authority,"pathAndQuery":path,"ts":ts,"nonce":b64(sig_nonce),"bodySha256":b64(sha(b"")),
+ "canonical": canon, "sig": b64(req_sig), "header": "Codync-Sig: " + header,
+ },
+ "acl": {"json": acl, "d": b64(acl.encode()), "sig": b64(acl_sig)},
+}
+print(json.dumps(out, indent=2))
diff --git a/docs/structure.md b/docs/structure.md
index b0a544f7..05cda0c5 100644
--- a/docs/structure.md
+++ b/docs/structure.md
@@ -1,10 +1,10 @@
# Layout & naming
```
-apps/{ios,macos,linux} one folder per client (iOS widgets in apps/ios/Widgets)
+apps/{ios,macos,linux} one folder per client (iOS widgets in apps/ios/Widgets, push decryption in apps/ios/NotificationService)
kit/Sources/CodyncKit/ Models/ Client/ Design/ (no CodyncUI, widget-safe)
kit/Sources/CodyncUI/ Store/ Bots/ Thread/ Marketplace/ Usage/ Resources/, cross-platform glue at root (Platform.swift)
-host/ relay/ web/ packaging/
+host/ cloud/ relay/ web/ packaging/
```
- Directories: lowercase for repo-level roles (`apps/`, `kit/`, `host/`); PascalCase inside Swift targets (`Views/`, `Thread/`). Apple app folders are `App/` (entry point, app-wide services), `Views/`, `Resources/` (Info.plist, entitlements, xcprivacy, xcassets).