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.
Remote relay protocol
Reviewed 2026-09-26. This reference preserves the channel's numbered wire-contract sections. It describes the implemented architecture; it is not a deployment acceptance report. Historical work assignments and proposed SDK definitions have been replaced by source entry points.
Shared deterministic vectors and their generator are consumed by Rust, Swift and TypeScript; see fixture maintenance.
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 是授權的唯一權威(中繼本身只給帳號內的電腦與同帳號手機用,見 optional sign-in)。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。 |
依帳號與電腦隔離狀態。 |
| D7 | 共用 bearer token(~/.codync/token)只接受 loopback 連線(桌面 App 本機、SSH tunnel、statusline、MCP、TUI)。手機與其他遠端 client 一律走 E2E channel。 |
移除「一個 token 開所有手機」的舊模型;不留相容路徑。 |
| D8 | SSH:桌面 App(apps/desktop/src/main/ssh.ts)以系統 OpenSSH -L 轉發到遠端 host 的 loopback API;遠端側看到的是 loopback 呼叫者,所以 SSH 帳號等同本機使用者權限(能讀 ~/.codync/token 的人本來就有這權限)。 |
產品決策 6;重用 loopback API,不需要額外授權層。 |
| D10 | 推播內容也加密:host 以裝置註冊的 X25519 push key 封裝通知標題/內文(§6.7),APNs 只帶通用文字 + mutable-content,iOS Notification Service Extension 解開。Live Activity 只推狀態 enum,不推自由文字。 |
決策 2:Cloudflare(relay/)只看得到密文。 |
審查後的取捨(rev 2):
- 撤權後的 DO 解封鎖以 grantId 判斷(新 grant 或本機配對的 null grant),不比較時間戳(見 §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 式的通知預覽。
明確不做(這一版):雲端保存聊天、桌面 App 當手機的 SSH gateway、手機原生 SSH、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. Implementation map
| Area | Source |
|---|---|
| Worker API / authentication / DO | cloud/src/api.ts, routes/, auth.ts, relay.ts |
| Cloud schema | cloud/migrations/ |
| Android transport / crypto / pairing | apps/android/core/; device storage in apps/android/app/ |
| Host identity / crypto / channel | host/src/remote/identity.rs, crypto.rs, channel.rs |
| Host cloud / relay | host/src/remote/cloud.rs, relay.rs |
| Swift transports / identity | apps/ios/Kit/Sources/CodyncKit/Client/ |
| Account and per-computer state | apps/ios/Kit/Sources/CodyncUI/ |
| iOS account integration | apps/ios/App/AccountSession.swift |
| Desktop account, device key, cloud API | apps/desktop/src/main/account.ts, cloud.ts |
See architecture and file structure. Application/host compatibility follows mutual minimum versions (compatibility); channel v, QR version and Worker package version are separate values.
3. 身分與金鑰
3.1 Host
- 首次啟動產生兩把金鑰:Ed25519
sign、X25519box(兩者獨立,不互相轉換)。 - 存於
data_dir()/identity.json,權限0600,不放 SQLite(避免複製資料庫就複製身分):{"v":1,"sign":"<b64url 32-byte seed>","box":"<b64url 32-byte scalar>"} - 寫入:先寫
identity.json.tmp(0600)再 rename。讀取失敗(格式錯)→ 啟動失敗並說明,不自動覆蓋。 computerId由sign公鑰推導(§1)。
3.2 Device(iPhone、桌面 App 作為 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-byterawRepresentation,kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,kSecAttrSynchronizable = false。 - 桌面 App(
apps/desktop/src/main/cloud.ts):每個帳號一把 Ed25519 device key,seed 以 ElectronsafeStorage(OS keychain)加密後存在 app 的 userData 目錄;只用於雲端/v1API 的Codync-Sig。 - iOS App、Widgets、NotificationService 共用 access group
$(AppIdentifierPrefix)com.pokai.Codync(project.yml對這三個 target 加keychain-access-groupsentitlement;CodyncKit從 Info.plistCodyncKeychainGroup讀 group,缺值則不設 group)。 - 私鑰永不離開 Keychain/process;雲端只存公鑰。
- 帳號登出:先在 Clerk 登出(失敗就什麼都不變)。成功後只停通知、保留金鑰:連得到的電腦呼叫
unregisterDevice刪掉 push tickets;雲端POST /v1/devices/sign-out(用登出前先取的 session token)標記這台裝置已登出,帳號的其他電腦下次拉/v1/host/state時依signedOutDevices刪掉它在登出前登記的 push tickets。各自最多數秒、失敗不擋登出。該 context 的 device key、computers、草稿都留著,同一帳號登回來直接連上(POST /v1/devices清掉標記)。Start over/刪除帳號才交還金鑰:連得到的電腦呼叫forgetDevice(舊版 host 改呼叫unregisterDevice),雲端DELETE /v1/devices/{id}(刪除帳號由user.deletedwebhook 處理),再刪除 device key、computers 快取、mailbox 草稿、widget snapshot;Start over 連這支手機上登出過的帳號一起刪。刪除帳號先在 Clerk 刪除使用者,成功後才交還給電腦。 - 有 Clerk 的 build 可以不登入(optional sign-in):
localcontext 是未登入空間,只走直連、配對不帶憑證。某個帳號 context 第一次使用時,若local有電腦或金鑰:該 context 在這支手機上是新的(沒有金鑰、沒有電腦)就整包搬過去,金鑰一起搬,電腦不用重新掃;已有自己的金鑰就只合併電腦清單,那些電腦會顯示需要重新配對。之後清掉local(iOSSharedStore.Context.adopt(from:)、AndroidLocalStore.adopt)。
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 撤權
| 動作 | 效果 |
|---|---|
裝置自己離開(Start over/刪除帳號:forgetDevice,只能移除呼叫者自己) |
與在電腦上撤銷相同;帳號來源的 grant 一併撤銷 |
裝置登出(unregisterDevice + POST /v1/devices/sign-out) |
不撤權:只刪 push tickets,裝置列與 grant 都留著 |
在電腦上撤銷裝置(桌面 App/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 配對(同一個帳號,2.36.0 起)
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):先 CODYNC_EXTERNAL_URL 設的網址(https://host 等,只能是 host 根路徑),再 Tailscale,再 LAN(http://ip:port,略過 Docker、Podman、Kubernetes、libvirt、LXD 的容器橋接介面;依 192.168、10、172.16/12 排序);最多 16 個(手機只留前 16 個);可為空 |
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])。
流程:
- 使用者在電腦上開 QR(桌面 App 選單列 → loopback
pairing;或codync-host pair)。host 產生 code,記在記憶體,並立即發佈含offers的新 ACL。 - 手機載入/建立 device key,用 §7.5 的連線策略連線,hello 帶
"pair": true(中繼另需 URLpair=<offerId>)。 - 握手成功(手機已用 QR 的
sk驗證 host)後,第一個 request 必須是:{"id":1,"m":"pair","b":{"code":"<code>","name":"Kevin's iPhone","platform":"ios", "certificate":{"payload":"…","sig":"…"},"claim":{"claimId":"clm_…","nonce":"…"}}}certificate是雲端簽的裝置憑證(POST /v1/devices/certificate,payload{v:1, deviceKey, userId, email, exp},簽"codync/device-cert/v1\n" + payload,host 用編譯進去的公鑰離線驗證,host/src/remote/certificate.rs)。claim是手機先向雲端要的 claim(POST /v1/claims),選填。 - host 先驗憑證與帳號,再花掉 code(optional sign-in):沒有憑證的是未登入手機:經 Codync 中繼 → 403;電腦在帳號裡 → 403;電腦不在帳號 → 在電腦上問。憑證不是這把 device key 的 → 403,絕不當成沒有憑證。電腦在別的帳號 → 403,訊息帶 owner 遮罩過的 email;電腦在手機的帳號 → 直接放行;電腦不在任何帳號 → 在電腦上問(loopback 的
pairingRequests事件/方法、decidePairing {requestId, approve, join?},最多 2 分鐘,兩邊顯示同一組 6 位數sha256("codync/pair-check/v1" ‖ dk ‖ hostSignKey);問題帶canJoin、phoneOnly、removes)。回答加入帳號時 host 簽手機的 claim,回應帶claim,手機自己POST /v1/claims/{id}/complete;回答只讓手機連時不簽,電腦留在帳號外,手機只能直連。問之前:經 Codync 中繼、又沒帶 claim 的已登入手機 → 403(加入帳號是它唯一的路,不問也不花 code);直連而沒帶 claim 的是canJoin: false。claim 簽不了 → 403,不花 code。 - client 收到
4100立即以一般模式重連(§7.5,不帶pair)。直連與中繼行為相同;DO 不需要「升級」pairing socket。
之後加入帳號:hello 帶 canJoinAccount(用 Codync 雲端、電腦不在任何帳號)時,已登入的手機顯示 Add to account。手機 POST /v1/claims,呼叫 control scope 的 joinAccount {claimId, nonce, certificate};host 驗憑證後在電腦上問(canJoin: true, phoneOnly: false),同意才記下這台裝置的帳號並簽 claim(owner::join_from_phone),手機完成 claim。host 不再自己要求加入。
sign_claim 簽之後 5 分鐘內,host 保持中繼連線並在 hello 給中繼位址(owner::wants_relay、url_for_phones),讓手機完成 claim、讓雲端通知 host。電腦不在帳號時 hello.cloud 是空的,host 也不掛中繼 socket,只有配對碼有效或剛簽 claim 時才連;平時每 5 分鐘用 HTTP 拉一次 state。帳號改變時,host 關閉 channel(4011)讓手機重讀 hello,並移除沒有帳號的手機。
區網探索:電腦不在帳號時,host 用 mDNS 廣播 service _codync._tcp(remote/discovery.rs),instance 名稱是 computer ID,TXT 帶 id(computer ID)與 urls(逗號分隔、只放區網位址、最多 240 bytes;Tailscale 名稱與位址不放,那些位址本來就不靠區網探索)。手機(LocalDiscovery)把找到的位址加進直連競速;handshake 仍驗 pin 住的 key,所以找到的內容不被信任。電腦在帳號裡就不廣播。
Caller::Pairing 的 channel 只接受 pair:第一個 inner 訊息不是 pair、或 pair 之後還有任何訊息 → 關閉 4002 protocolError。
錯誤與限流:
- 沒有任何未過期的 pairing code 時,
pair:true的hello在做 ECDH/簽章驗證之前就回reject pairingClosed並關閉。 - 限流只計算「到達
pairrequest」的嘗試:每個來源(直連: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)—在該電腦上的桌面 App(或經 SSH tunnel 的桌面 App)操作:
- 桌面 App(Clerk 已登入)
POST /v1/claims→{claimId, nonce, expiresAt}(5 分鐘)。 - 桌面 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 另給的值。 - 桌面 App
POST /v1/claims/{claimId}/complete(Clerk)帶上 host 回傳的內容。Worker 驗 Clerk、claim、簽章,原子化設定 owner。 - Worker 通知 DO
cloud.changed→ host 拉 state 得知 owner。
手機也會讓 host 簽 claim:配對時(§4.1 第 4 步),以及配對沒加入帳號時之後的 control scope joinAccount(§4.1「之後加入帳號」)。
B. 手機取得存取權(commit-then-reveal SAS,ZRTP/BLE numeric comparison 同型):
- 手機登入後
POST /v1/devices(Clerk + 該 device key 的Codync-Sig)。 GET /v1/computers(帶Codync-Sig則回傳每台的access)。 手機在「電腦與設定」(Computers)列出帳號裡的電腦,不需掃 QR Code;存取申請只在使用者點該電腦的 Ask for access 後才開始(登入或重新整理都不會自動申請),點下後才顯示 6 位數代碼;關閉申請畫面後,等待中的申請仍以橫幅顯示代碼,直到電腦回應。核准後顯示該電腦的 bots。首次裝置授權仍由電腦上的使用者確認。- 對
access == "none"的電腦:手機產生 32 random bytesnD(只存記憶體),POST /v1/computers/{id}/access-requests {"commit": b64url(SHA-256("codync/sascommit/v1" ‖ dk ‖ nD))}→{requestId, expiresAt}。 - Worker 通知 DO → host 拉 state → 看到新申請(含
commit)→ host 產生 32 random bytesnH(存本機記憶體,每個 requestId 只產生一次)→POST /v1/host/access-requests/{id}/nonce {"nonce": nH}(已有 host nonce →409 conflict,host 不得換)。 - 手機輪詢
GET /v1/access-requests/{id}(每 2 秒)→ 出現hostNonce後才POST /v1/access-requests/{id}/reveal {"nonce": nD}→ Worker 存入並通知 DOcloud.changed。手機此時計算 SAS 顯示「在電腦上確認代碼 123456」。 - host 拉 state 取得
deviceNonce→ 驗SHA-256("codync/sascommit/v1" ‖ dk ‖ nD) == commit(不符 → 自動 deny 並記warn)→ 計算 SAS →accessRequests事件 → 桌面 App 顯示核准對話框(裝置名稱、平台、帳號 email、SAS)。nD驗證通過前 host 不顯示 SAS、不接受 approve(decideAccessRequest回 409)。無 GUI 的 host:codync-host access list|approve|deny。 - 核准 → host
POST /v1/host/access-requests/{id}/decision {"decision":"approve"}→ D1 建立 grant → 回grantId→ host 以自己顯示給使用者的dk與回傳的grantId新增裝置列(source=account,lease 15 分鐘)→ 發佈 ACL。 - 手機輪詢到
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 的授權裝置表(host/src/api/devices.rs)每一列: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的列在直連與中繼上都不接受握手。 - 連線期間每 5 分鐘再拉一次,有沒有 owner 都拉:漏接的
cloud.changed(例如剛被 claim)由此補上;成功的拉取也清掉lastError。 - 表有任何變動 →
acl_ver前進(§7.3 規則)→ 發佈 ACL。
ACL(host 簽章,DO 驗證;逐位元組簽章,不做 JSON 正規化;向量 acl):
{"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-dev.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,所以 dev 簽的 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 的檢查順序(便宜的先做):
- 中繼 link:
hello.dk必須等於 DO 在open給的dk;pair必須與open.pair相同。不符 →4002。 pair == true:沒有未過期的 pairing code →reject pairingClosed(不做任何密碼運算);限流見 §4.1。pair != true:dk必須是有效授權(§4.3,含「relay 連上後 state 已拉取」條件)。否則reject unauthorized|revoked|leaseExpired。- 驗
hello.sig→ 產生ekH→welcome。
- 中繼 link:
- 裝置的
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恰為預期值,否則關閉(close4002 protocolError)。這同時提供重放與重排保護。 - 一則 inner 訊息(§6.5 的 JSON)UTF-8 編碼後切成 ≤ 256 KiB 的 chunk;接收方串接直到 flag
0x00,再 JSON parse。 - 重組上限:已授權 device→host 8 MiB(含 5 MiB 自訂圖片的 base64/JSON);僅供配對的 channel 維持 1 MiB;host→device 16 MiB。超過 → 關閉
4013 tooLarge。單一 WebSocket 訊息仍使用 256 KiB chunks。
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:
{"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":,"client":"ios" |
| 串流事件 | 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。 screenCandidatessubscribes with{"id":N,"sub":"screenCandidates","b":{"session":"<screen-session-id>"}}. Itsevvalues areready, orderedcandidate,complete, orerror;endcloses the subscription. It requires screen scope and ownership of that screen session.events訂閱的語意與 SSE 完全相同(先 subscribe、再 catch-up、hello在最前且catchUp為其後 catch-up 事件數、落後時送{"type":"resync"});client == "ios"時計入hub.ios_clients(推播抑制)。- Bot 刪除標記會保留在 host 資料庫;增量同步與
since = 0的全量同步都傳送它們。手機及桌面在版本更新或解碼重試時會保留快取並重設同步游標,必須收到刪除標記才能移除舊 Bot、對話與草稿;終端使用相同的事件串流。 - 串流沒有額外的 keep-alive;存活由 WebSocket ping(§7.6)負責。
6.6 方法權限(host 以 Caller 判斷)
| 類別 | 方法 | 允許的 caller |
|---|---|---|
| loopback 專用 | setScreenEnabled, pairing, computerCall, computerTools, chatCall, teamCall, manageCall, memoryCall, routineCall, composioCall, claimSign, unclaim, devices, revokeDevice, accessRequests, decideAccessRequest, pairingRequests, decidePairing, pairingCodeOpen, cloudStatus, setCloud, setCloudUrl |
Caller::Local(loopback + token);pairingRequests 事件也只送給 loopback |
| 配對中 | pair |
只在 pairing 狀態的 channel;配對完成後不可再呼叫 |
| screen scope | screenPrepare, screenOffer, screenCandidate, screenClose, screenTakeover |
Local,或 scopes 含 screen 的裝置 |
| control scope | 其餘所有既有方法(hello, joinAccount, history, createBot, updateBot, renameSection, deleteBot, markRead, send, stop, newSession, respondPermission, registerDevice, unregisterDevice, forgetDevice, registerActivity, refreshBackends, usage, listDirs, market/skills/connectors、agentSetup, agentAuth, agentAuthenticate, setAgentEnv, termInput, termResize, termClose, screenStatus) |
Local,或 scopes 含 control 的裝置 |
The screenCandidates subscription also requires screen scope and belongs to its device’s screen session. It carries ordered candidates and completion separately from chat events; see remote screen.
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","subtitle"?,"body"} JSON, aad = cidRaw)
sealed = b64url(epk ‖ ct)
送給 relay/ 的 body:alert 為 Codync 與依 kind 選擇的通用說明句、mutableContent: true、threadId = computerId:botId、category = done|needsInput|failed、data = {"botId","computerId","ctx":<SharedStore.Context.id>,"sealed"}。Notification Service Extension 依 ctx 從共用 Keychain 取 push key、解開後替換 title/subtitle/body;解不開就保留通用文字。Live Activity 的 contentState 只含 status 與 startedAt(activity 固定為空字串),不含任何自由文字。向量 push 保留沒有 subtitle 的相容格式。通知呈現、票券更新、ActivityKit 時間與部署驗收見 通知與 Live Activity 設計。
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;RELAY_NEEDS_ACCOUNT=1 時 Worker 先查:一般 socket 要電腦有 owner,且 deviceKey 在 D1 devices 屬於同一個 owner、未撤銷、未登出;pairing socket 要 deviceKey 屬於任一帳號;否則 403 needsAccount。接著 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):
- 一般 socket 的
dk在blocked表 →403;pairing socket 仍可申請配對。 pair參數存在:offerId必須在 ACLoffers且未過期;同時最多 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 立即退役(見 §7.6),之後以
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 |
hooks |
hooks:[{"id","key","enabled"}](完整集合,≤ 1000) |
取代 DO 存的 webhook 集合(§7.8);格式錯誤 → {"t":"error","code":"badHooks"} 且保留舊集合。成功 → {"t":"hooks.ok","n"} |
hook.ack |
seq, ok(bool), retry(bool), code |
ok 或 retry:false → 刪除;retry:true → 退回 queued,not_before = now + min(30 s·2^attempts, 15 min) |
assistant.result |
id, ok(bool), result 或 error |
回答同 id 的 assistant.call(§7.9);沒有等待中的 id 就忽略 |
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 |
hook.item |
seq, hook(routine id), delivery, headers(白名單,小寫名), body(b64url), at |
assistant.call |
id, user(Clerk user id), tool(list_bots/message_bot/read_replies), args(§7.9) |
hooks.ok |
n |
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" |
mbox.list |
— | `{"t":"mbox.items","items":[{"nonce","exp","state":"queued" |
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 與整合測試共通)
- 平行對所有
urls(http://h:p→ws://h:p/channel?v=1,https://h→wss://h/channel?v=1)開 WebSocket 並握手;1.5 秒內第一個完成握手的勝出。 - 都失敗且有
cloud→ 連{cloud}/v1/relay/device/{computerId}。每次收到presence online:true就(重新)送hello;online:false→ 狀態computerOffline(lastSeen),保持 socket(可用 mailbox),等下一個online:true。 - 兩者都不可用 →
offline("Can't reach …"),退避重試。 - App 回前景、網路路徑改變(
NWPathMonitor)→ 重新跑 1–3(可能從中繼換回直連);events 以當前rev重新訂閱。 - 每次 inner
hello成功後,把回應的urls、cloud、device、name、boxKey合併進持久化的Computer(§3.3、§10);帳號來源的 computer 因此在第一次中繼連線後也能試 LAN 直連。
7.6 心跳、重連、限流
- 心跳:host 與 device 每 30 秒送
{"t":"ping"}(中繼);直連時 host 每 15 秒送 WebSocket Ping frame,client 45 秒沒收到任何資料視為斷線。 - DO alarm:只要有 socket 或 mailbox 項目就每 60 秒一次:任何 socket(host 與 device)的
ctx.getWebSocketAutoResponseTimestamp()超過 90 秒 → 退役:attachment 記retired,之後 DO 不再送任何東西給它;host 標記離線,device 通知 hostclose該 link。退役的 socket 不立刻關:對已經連不到的 peer 呼叫close()會讓 DO 一直醒著(計 duration)到 TCP 放棄為止,放著不動則不會。它之後再說話(收到訊息、或 ping 時間晚於退役時間)就以記下的 code 關閉;若 DO 從退役起一直沒睡過(同一個 instance 還記得它),下一次 alarm 也關它,因為卡在它佇列裡的資料可能正是 DO 睡不著的原因,只有關掉才會釋放。清除過期 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。
7.8 公開 routine webhook
讓外部服務(GitHub、監控、腳本)觸發 routine,不需要公網 IP、開 port 或使用者自己的 tunnel:沿用 host 主動連出的 relay socket。只給帳號內的電腦:host 對不在帳號的電腦不給網址(needsAccount),RELAY_NEEDS_ACCOUNT=1 時 Worker 回 403 needsAccount。
- 網址:
POST {cloud}/v1/hooks/{computerId}/{routineId}。Worker 檢查兩個 id 的格式、body ≤ 64 KiB(否則413 tooLarge)、HOOK_LIMITER(每「來源 IP + hook」每分鐘 60 次 →429)、computer 存在且active(否則404,不為隨機 id 建 DO),再把原 request 轉給該 computer 的 DO/internal/hook。 - 註冊:host 在
ready後送hooks,之後每當集合改變(新增/刪除 webhook routine、暫停/恢復、換 key)就重送整個集合。只含有webhook或eventtrigger 的 routine。 - 驗證(DO 一次、host 再一次):
Authorization: Bearer <key>(常數時間比較),或X-Hub-Signature-256: sha256=<hex HMAC-SHA256(key, 原始 body)>(GitHub 與相容服務)。未知 hook 與錯誤 key 一律401 unauthorized,無法探測 id。已暫停 →409 paused。host 是最終權威:DO 的集合過期或被竄改時,host 仍會拒絕。 - 去重:delivery id 取
X-Delivery-Id、X-GitHub-Delivery或Idempotency-Key(可列印 ASCII、≤ 200;不合法 →400 badDeliveryId;都沒有 → DO 產生 UUID)。DO 以(hook, delivery)唯一;佇列中的重送回202 {"duplicate":true}。已投遞後的重送由 host 以保留中的 run 紀錄去重。 - 佇列(DO
hookbox):每 hook ≤ 100、每 computer ≤ 1000 則、總計 ≤ 16 MiB(滿 →429 full,Retry-After: 60);TTL 72 小時。成功入列 →202 {"delivery","queued":true}。 - 投遞:host
ready時,DO 依seq一次送一則hook.item(狀態delivering),跳過not_before未到的;host 斷線時退回queued。alarm 清除過期項目,並在最早的not_before喚醒。 - 轉給 host 的 header 白名單:
authorization、content-type、user-agent、x-delivery-id、idempotency-key、x-github-event、x-github-delivery、x-github-hook-id、x-hub-signature-256。 - Host 處理(
routines::hooks):驗證 → GitHubping回 ok 不執行 → 暫停回paused→ 轉成 event(JSON 物件原樣;GitHub →{source:"github", event:"<event>.<action>", repo, sender, text, url, payload};其他 →{text})→ trigger 不符回 ok(忽略)→ 排入 run。routine 正在執行 →retry:true。 - 信任邊界:webhook 內容在 Cloudflare 以 HTTPS 解開,雲端看得到明文,也存著 key(用來驗 HMAC)。這不是 §6 的端對端加密;App 與文件都需明講。
7.9 Cloud assistant(MCP connector)
讓使用者已在用的雲端助理(ChatGPT、Claude 等 MCP client)以 Codync 帳號登入後,列出、指派並讀回使用者的 bot。設計與設定:cloud assistants。
- 網址:
https://mcp.codync.dev/mcp(dev:dev-mcp.codync.dev),同一個 Worker 的 custom domain(cloud/src/routes/assistant.ts)。Streamable HTTP,只用 POST 與 JSON 回應,無 session、無 server stream(GET /mcp:未登入401,登入405)。同時服務 2026-07-28 無狀態 client(_meta帶版本、server/discover、不支援的版本 →-32022)與initializeclient(2025-03-26~2025-11-25)。 - 登入:Clerk 是 authorization server,Worker 只是 protected resource。未帶有效 token →
401,WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp", scope="profile email";metadata 指向 Clerk issuer(/.well-known/oauth-authorization-server也代轉 Clerk 的,給舊 client)。Client 以 CIMD 註冊(DCR 關閉)。Token 必須是 Clerk 發的 OAuth access token(at+jwt,或 opaque 時向 Clerk 驗),aud必須等於<origin>/mcp;App 的 session token 不算。ASSISTANT_LIMITER:每帳號每分鐘 120 次。 - 路由:Worker 只把呼叫送到 token 帳號擁有、
active的 computer。list_computers由 Worker 從 D1 回答;其餘工具:指定computer(名稱或 id)→ 該台;未指定時帳號只有一台、或只有一台在線 → 該台;list_bots/read_replies在多台在線時每台都問並合併成{computers:[{computer, …}]};message_bot則要求指定。 - DO:
POST /internal/assistant {user, tool, args}→ host 不在線503 {"ok":false,"code":"offline"};否則送assistant.call,在 request 存活期間等同id的assistant.result,最多 10 秒(逾時{"ok":false,"code":"timeout"},舊 host 會忽略這個訊息)。host 斷線時等待中的呼叫一律offline。只在 request 存活時佔用 DO,不排隊、不存任何內容。 - Host(
chat::team::assistant):預設關閉,setAssistants(loopback only:桌面 app 與 TUI 的 Cloud assistants 開關,或codync-host cloud --assistants on|off)才開,且電腦不在 Codync 帳號裡時拒絕打開(這條連線還沒有成功的 state pull 時回「帳號還不知道」;關永遠可以),state pull 回owner: null時自動關掉,下次加入的帳號要重新同意;user必須等於 host 的 owner(/v1/host/state);private relay 上不處理。message_bot走一般 bot request(Back::Assistant),回覆留在 host 記憶體給read_replies(最新 50 則,同時最多 16 則執行中,重啟即忘)。reachableByAssistants關掉的 bot 不列出、不收。list_bots也列同一 network 裡其他電腦提供的 bot(reviewer@laptop);對它們的message_bot是一封由cloud-assistant@<這台>寄出的 codync-network 信,結果回到同一份 replies。收信的電腦自己再檢查:它的 Cloud assistants 開關(所以它也要在帳號裡)、該 bot 的reachableByAssistants與 network rules。Host 在 relay session 外另起 task 回答assistant.call(第一次列出時可能要等其他電腦最多 5 秒),不會卡住同一條連線上的裝置訊息。 - 信任邊界:和 §7.8 一樣,雲端以 HTTPS 解開並看得到這些呼叫與回覆的明文,不是 §6 的端對端加密。因此要電腦本機同意(開關)才放行,雲端無法自行替電腦打開;App 與文件都需明講。
8. Cloud HTTP API
The route table below summarizes the contract. Executable schema and validation live in cloud/migrations/ and cloud/src/routes/; do not maintain a second copy of the schema here.
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":"2.2.0"}
Clerk(使用者)
GET /v1/me→{"userId","email","createdAt"}POST /v1/devices(Clerk + Sig(dev)){"name","platform":"ios"|"macos"|"linux"|"windows"}→{"device":{"deviceId","deviceKey","name","platform","createdAt"}}。以(owner, sign_pub)upsert;已撤銷的同一把 key →403 forbidden(需換 key)。POST /v1/devices/certificate(Clerk + Sig(dev))→{"certificate":{"payload","sig"}}:證明這把已註冊、未撤銷的 device key 屬於這個帳號,7 天有效(§4.1)。雲端沒設DEVICE_CERT_KEY→503 notConfigured。POST /v1/host/pairing-codes(Sig(host)){"link","expiresAt"}→{"code":"QRTX-4821","expiresAt"};GET /v1/pairing-codes/{code}(Clerk)→{"link"},只能用一次、10 分鐘。codync-host pair的短代碼。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/devices/sign-out(Clerk + Sig(dev))→{}:手機登出。設devices.signed_out_at(migration0006),對帳號的每台電腦送cloud.changed;不撤權。同一把 key 再POST /v1/devices(登回來)就清掉。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。成功後 DOcloud.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"}→{};成功後 DOcloud.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":"macos"|"linux"|"windows","device","version"}→{"computerId","owned":bool}。以 kid 推導 id;upsert(name/device/version/box_pub/updated_at)。同 IP 每分鐘最多 10 次新建(Workers Rate Limiting binding;平台不支援時先略過並在 README 註記)。Host 指向 private relay 時只在這個請求帶Codync-Relay-Token(官方 cloud 忽略它):私人中繼收新電腦必須 token 相符,不符回403 forbidden("This relay needs its relay token to add a new computer."),最多 32 台;已註冊的 key 不需要 token 就能 refresh。私人中繼的GET /v1/host/state永遠是空的,host 不拉它(不套用 grants、不處理 requests)。GET /v1/host/state→
grants 只含:grant active、device 未撤銷、device.owner == computer.owner。host 只把它當成「可續約/應刪除」的清單(§4.3)。{"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"}], "signedOutDevices":[{"deviceKey","signedOutAgo"}]}signedOutDevices是電腦所屬帳號裡登出的裝置(未撤銷)與登出多久了(ms,相對時間,兩邊時鐘不同步也沒關係),host 從收到回應的時間往回推,只刪掉它們在那之前登記的 push tickets(回應慢時寧可多刪一張剛登記的,手機下次連線會再送),不動裝置列:手機登回來後送來的新 ticket 可能比清掉標記的POST /v1/devices先到,要留著。POST /v1/host/access-requests/{id}/nonce{"nonce"}→{}(cloud/src/routes/host.ts;已設過 →409)POST /v1/host/grants/{grantId}/revoke{}→{}(host 在本機撤銷帳號來源裝置時同步 D1,revoked_reason='owner';失敗記錄並存入grant_revokes重試,本機撤銷已生效)POST /v1/host/access-requests/{id}/decision{"decision":"approve"|"deny"}→{"status","grantId"?}(cloud/src/routes/host.ts的原子更新;request 過期 →410 requestExpired;approve 要求device_nonce IS NOT NULL,否則409)POST /v1/host/unclaim{}→{}(在電腦上移出帳號;同DELETE /v1/computers/{id}的效果)
Routine webhook(公開):POST /v1/hooks/{computerId}/{routineId},§7.8。
Cloud assistant(MCP connector):POST /mcp、GET /.well-known/oauth-protected-resource[/mcp]、GET /.well-known/oauth-authorization-server,§7.9。
Relay:§7.1。Webhook:user.deleted → accounts status='deleted'、devices 撤銷、grants 撤銷(accountDeleted)、computers owner=NULL、DO block + changed。
9. Host integration
host/src/api/mod.rs dispatches inner methods to their method groups (bots.rs, host.rs, marketplace.rs, remote.rs) and devices.rs enforces caller permissions. Bearer HTTP/SSE is loopback-only; remote callers use the encrypted channel. host/src/remote/cloud.rs manages registration, claims, access state and grant revocation retries; host/src/remote/relay.rs manages the outgoing relay connection. Inspect these implementations for current method signatures and storage keys.
codync-host cloud reports cloud status; devices lists/revokes device access; access handles pending approval. reset-token rotates the local bearer credential, not remote device grants.
10. iOS Swift integration
CodyncKit/Client (apps/ios/Kit/) owns transport, crypto, identity and cloud API models. CodyncUI owns account/per-computer stores and presentation. The desktop app doesn't use the device channel; it reaches its own host and SSH computers over loopback. Consumers must retain account and computer scope when handling asynchronous responses, links and cached widget data. See file structure.
11. Apps and SSH
The iOS app (ClerkKit) and the desktop app (Clerk Frontend API) sign in to the same Clerk instance. Signing in is optional (optional sign-in); QR pairing works without the cloud for a computer in no account, and account access requires host-approved device access. The desktop app uses OpenSSH forwarding for SSH computers, not a mobile SSH gateway. See accounts and SSH.
12. Verification
12.1 Local integration
cloud/test/e2e/relay.e2e.ts exercises a real host with local Wrangler and a fake ACP agent. Run npm run e2e in cloud/ after building the host. The three language implementations also consume the shared vectors.
12.2 Deployed-device verification
Use the Cloudflare testing guide. Local tests do not establish live OAuth, deployed Worker, APNs or background behavior.
13. Acceptance criteria
Verify pairing and approval, same-computer direct/relay connectivity, encrypted chat and reconnect catch-up, mailbox cancellation/deduplication, revocation, account isolation, and separate APNs delivery. Record actual results and routes. These are acceptance targets, not claims that all scenarios have passed.
14. Environments and deployment
See environments and deployment and cloud setup. iOS Dev / dist:*:dev builds target development (dev-api.codync.dev); iOS / dist:*:main builds target production (api.codync.dev).
Implementation clarifications
The following implemented clarifications take precedence over the original contract wording above:
- Close code:host 送出
reject後自行挑選 WebSocket close code(RejectCode::close_code),不照 §表格逐一對應。 cloud_synced:relay 斷線時不清除;帳號裝置的 lease 最長 15 分鐘內自然失效。- Access request:host 無法完成的請求(例如缺 key、狀態不一致)自動 deny,不留在 pending。
- Grant 撤銷:失敗的撤銷記在 kv
grant_revokes,之後重試。 Identity::sign_request多一個authority參數(小寫 Host header,含非預設 port),簽名涵蓋它。- DO admission:規格未列的情況也可能回
403/429。 - vitest:
compatibilityDate固定2026-08-22。 - Kit relay 升級:遇
403重試最多 3 次。 - SAS nonce:host 每小時最多 5 個(kv
sas_nonces);每把 device key 同時只允許一個尚未 reveal 的請求。 - 直連
reject:明文的直連reject不結束連線競速:仍會嘗試 relay,已存的 computer 持續重試。 - Mailbox 重試:沿用同一個
clientNonce,但每次重新 seal。 - ACL:列表中
grant為 null 的已封鎖 dk 會被解除封鎖;被封鎖的 dk 仍可開 pairing socket。 - 帳號裝置 mailbox:第一次拉取 state 之前收到的 item 先保留、不 ack。
- SSH forward:確認本機 listener 屬於我們啟動的
ssh子行程才送出 host token:macOS/Linux 用lsof或/proc,Windows 用Get-NetTCPConnection。 - 取消 access request:iOS SAS sheet 有取消按鈕(
DELETE /v1/access-requests/{id})。
15. Limits and risks
- Account discovery relies on cloud-provided public keys; users must actually compare the commit/reveal six-digit approval code. QR pairing obtains host keys directly from the pairing payload.
- The cloud sees account/device records and routing metadata, connection times, sizes, frequency and mailbox identifiers. Channel content is encrypted. APNs has its own visible routing metadata.
- Copying
identity.jsoncreates competing connections for one computer identity; replacing host keys requires pairing again. - Revocation is enforced locally even when cloud synchronization fails; pending cloud revocations are retried.
- Direct
ws://still encrypts channel content, but exposes connection metadata to the local network. - Mailbox retention is bounded and is not cloud transcript storage. Phone-native SSH and team sharing are outside this contract. Screen media uses the separate short-lived TURN flow in Remote screen.