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.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
Merge in-progress work from the main tree
leepokaiaa00363b09ca
diff --cc CLAUDE.mdindex f7b1bfed,0320d0d0..c4fc7376--- a/CLAUDE.md+++ b/CLAUDE.md@@@ -19,12 -19,13 +19,14 @@@ Bot-based remote for coding agents: per- UI principle: buttons an icon can express are icon-only (with tooltip / accessibility label); text only where an icon would be ambiguous (approval choices).- `host/` — **codync-host** (Rust, macOS + Linux). Detects installed harnesses (`backends.rs`: login-shell PATH + known dirs) and the ACP registry (`registry.rs`, cached in `~/.codync/registry.json`, binaries under `~/.codync/agents`). Drives agents over **ACP** (JSON-RPC on stdio, hand-rolled in `acp.rs`, updates kept as `serde_json::Value` so new adapter variants never break parsing). One actor per bot (`bot.rs`) owns the agent process + session and maps `session/update` onto transcript entries.- **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*.+ - Bot collaboration: built-in `team` MCP (`team.rs`) lists visible bots and asks one for a reply through its actor queue. Requests are separate turns, cycle-checked and cancellable; native subagents stay with the harness. See [docs/bot-collaboration.md](docs/bot-collaboration.md).+ - **Context & memory** (Grok Bot's design): frozen instruction snapshot per session + compaction epoch (Claude gets it as a system prompt), profile edits as update blocks, per-bot memory files written by a keeper agent, busy-time messages folded into one turn, interrupted turns resumed: [docs/context-and-memory.md](docs/context-and-memory.md).- **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 --cc Codync.xcodeproj/project.pbxprojindex 5d07faa4,ffc4f35f..e06ca775--- a/Codync.xcodeproj/project.pbxproj+++ b/Codync.xcodeproj/project.pbxproj@@@ -22,19 -20,15 +22,21 @@@484455D97513F09142D21D0D /* Capture.swift in Sources */ = {isa = PBXBuildFile; fileRef = CE4D28E8291EEB43E17B11FA /* Capture.swift */; };48DAAA1384E5B8D0BA27C895 /* SwiftUI.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 1E47C60032C326157E0386B8 /* SwiftUI.framework */; };498C81B8C82557C85F912238 /* HostLink.swift in Sources */ = {isa = PBXBuildFile; fileRef = 75CAC64DDC41D4A222A12DDE /* HostLink.swift */; };+ 4ACFCBCDB8253091EF9D8D1A /* ComputerStatus.swift in Sources */ = {isa = PBXBuildFile; fileRef = C0C143ED8FF93F6BBD82F942 /* ComputerStatus.swift */; };513F59BF65DED5379AB950A1 /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = D2C705F063CD20F5B3036BD4 /* Assets.xcassets */; };+ 52AEBEAEADB347DA7E3CDC40 /* WidgetPreviews.swift in Sources */ = {isa = PBXBuildFile; fileRef = 744DB8C27E27A424EA8E1549 /* WidgetPreviews.swift */; };52CF04B855C6AAEC47B75B8F /* CodyncKit in Frameworks */ = {isa = PBXBuildFile; productRef = 1285DDFA0390A76ECDAAD6C0 /* CodyncKit */; };5F9AE9B8E7FF66F194162BDC /* ScreenHelper.swift in Sources */ = {isa = PBXBuildFile; fileRef = AB932B6C1849B8DF7CF7C2E3 /* ScreenHelper.swift */; };- 6A15821964A5EE5AEBB0C420 /* ClerkConfig.plist in Resources */ = {isa = PBXBuildFile; fileRef = 19D41F16A62FEF37BE0AD1FC /* ClerkConfig.plist */; };+ 72A907055F1AAEF8F10EAD72 /* NotificationService.appex in Embed Foundation Extensions */ = {isa = PBXBuildFile; fileRef = 7B7E845BA1B8696B266CF578 /* NotificationService.appex */; settings = {ATTRIBUTES = (RemoveHeadersOnCopy, ); }; };+ 76E73EDD79B063940B5D8B8E /* ComputersView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 57DFD81025893713D631B5D7 /* ComputersView.swift */; };826FEDA23997E436D632E579 /* PrivacyInfo.xcprivacy in Resources */ = {isa = PBXBuildFile; fileRef = 4CFB70DD8757C90695CDA211 /* PrivacyInfo.xcprivacy */; };8AC8D90C21B92480E2809758 /* AccountSession.swift in Sources */ = {isa = PBXBuildFile; fileRef = E4B8EAB09016D328195FE2AD /* AccountSession.swift */; };+ 8BB3FC79EB798CE4347E6FD3 /* CodyncKit in Frameworks */ = {isa = PBXBuildFile; productRef = 50F314172CC2AD1C5CDC916A /* CodyncKit */; };8CD641A45F144BF41D703D2A /* CodyncMacApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = 2969919CCC8BC89F277C43A6 /* CodyncMacApp.swift */; };+ 9593C1951D727D36D6B8C0E9 /* ComputerStatus.swift in Sources */ = {isa = PBXBuildFile; fileRef = C0C143ED8FF93F6BBD82F942 /* ComputerStatus.swift */; };+ 9D0736B9670D57132AFBB34E /* NotificationService.swift in Sources */ = {isa = PBXBuildFile; fileRef = 9C60BD13E7283ECB7A1AE4D3 /* NotificationService.swift */; };+ 9FE9864DA43399578A892992 /* AccountConfig.plist in Resources */ = {isa = PBXBuildFile; fileRef = D5252F097812608BF90F7647 /* AccountConfig.plist */; };+ A12D125989D2EA1AC5308218 /* WidgetGalleryView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0E8563C243AB130DFA063CAD /* WidgetGalleryView.swift */; };AA601649E43A5AF73DCF5B5E /* WebRTC in Frameworks */ = {isa = PBXBuildFile; productRef = 2D9748E611692583AFC5A152 /* WebRTC */; };ACCB28F3DB9C89108B7911E3 /* Input.swift in Sources */ = {isa = PBXBuildFile; fileRef = 842DA106CA15E3810C3C9461 /* Input.swift */; };AFC0CD8BD1FA61F810C96057 /* com.pokai.Codync.screen.plist in CopyFiles */ = {isa = PBXBuildFile; fileRef = 895BB6C2EB8986266EB4159A /* com.pokai.Codync.screen.plist */; };@@@ -120,8 -106,8 +122,9 @@@/* Begin PBXFileReference section */00F135A0B168269BD6C2A199 /* CodyncWidgets.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CodyncWidgets.swift; sourceTree = "<group>"; };+ 0E789EF9DE58D45EDE33F76D /* NotificationService.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = NotificationService.entitlements; sourceTree = "<group>"; };+ 0E8563C243AB130DFA063CAD /* WidgetGalleryView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WidgetGalleryView.swift; sourceTree = "<group>"; };- 19D41F16A62FEF37BE0AD1FC /* ClerkConfig.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist; path = ClerkConfig.plist; sourceTree = "<group>"; };+ 1233BBE848155CA9E177A7E2 /* AccessRequestView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AccessRequestView.swift; sourceTree = "<group>"; };1E47C60032C326157E0386B8 /* SwiftUI.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = SwiftUI.framework; path = System/Library/Frameworks/SwiftUI.framework; sourceTree = SDKROOT; };1F16B11B2920E9D05621AFE7 /* ViewingBadge.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ViewingBadge.swift; sourceTree = "<group>"; };22F1B304BD18E48C91FC73E3 /* Widgets.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = Widgets.entitlements; sourceTree = "<group>"; };diff --cc apps/ios/App/CodyncApp.swiftindex 3fea8103,32bb6b12..39042bba--- a/apps/ios/App/CodyncApp.swift+++ b/apps/ios/App/CodyncApp.swift@@@ -9,21 -9,26 +9,26 @@@ import WidgetKistruct CodyncApp: App {@UIApplicationDelegateAdaptor(AppDelegate.self) private var delegate@State private var app = AppStore.shared- private var model: BotStore { app.model }@Environment(\.scenePhase) private var scenePhase- @State private var tab = AppTab.bots+ @AppStorage("onboardingCompleted") private var onboardingCompleted = falsevar body: some Scene {WindowGroup {- RootView(tab: $tab)+ RootView().id(app.contextID)- .environment(model)+ .environment(app)+ .environment(app.accounts).environment(app.account).tint(Palette.accent)- .sheet(isPresented: Bindable(app.account).showSwitcher) {+ .sheet(isPresented: Binding(+ get: { onboardingCompleted && app.account.showSwitcher },+ set: { app.account.showSwitcher = $0 }+ )) {NavigationStack { AccountSwitcherView() }+ .environment(app)+ .environment(app.accounts).environment(app.account)- .environment(model)+ .tint(Palette.accent)}.onChange(of: app.account.userID, initial: true) { _, userID inapp.switchAccount(to: userID)@@@ -91,112 -101,35 +96,115 @@@ final class AppStoreLiveActivities.shared.endAll()SharedStore.activeAccountID = userIDstorage.bots = []- storage.usage = nilcontextID = storage.id- model = Self.makeStore(storage)+ tab = .bots+ showComputers = false+ marketplace = nil+ (accounts, cloud) = Self.makeAccounts(storage, session: account)BotsWidgetFeed.reset()WidgetCenter.shared.reloadAllTimelines()- model.setActive(true)}- private static func makeStore(_ storage: SharedStore.Context) -> BotStore {- let store = BotStore(pairing: storage.pairing, clientKind: "ios", persistsPairing: true, storage: storage)- store.onPaired = { PushRegistrar.shared.syncDevice(with: $0) }- store.onBotUpdated = { bot in LiveActivities.shared.update(bot: bot) }- store.onRosterChanged = { roster in+ /// Signing out forgets this account on this iPhone: its device keys, computers and caches (spec §3.2).+ func signOut() async {+ guard let userID = account.userID else { return }+ await account.signOut()+ guard account.userID != userID, !account.accounts.contains(where: { $0.id == userID }) else { return }+ // Retire its stores first: a retiring store saves its cache one last time.+ switchAccount(to: account.userID)+ SharedStore.Context(accountID: userID).erase()+ }++ func pair(_ pairing: Pairing) async throws -> Computer {+ let computer = try await accounts.pair(pairing, deviceName: UIDevice.current.name, platform: "ios")+ Task { _ = await PushRegistrar.shared.requestAuthorization() }+ return computer+ }++ func open(_ url: URL) {+ if url.scheme == "com.pokai.Codync.ios" {+ Task { await account.handle(url) }+ return+ }+ switch url.host() {+ case "pair":+ // Scanned with the Camera app: pair right away.+ let accounts = accounts+ Task {+ do { _ = try await pair(try Pairing.parse(url)) } catch { accounts.lastError = error.localizedDescription }+ }+ case "bot":+ guard let ref = storage.reference(from: url), accounts.store(for: ref.computerId) != nil else { return }+ tab = .bots+ accounts.selection = ref+ case "plugins":+ accounts.selection = nil+ tab = .bots+ marketplace = currentStore?.computer.id+ case "usage":+ tab = .usage+ case "computers":+ accounts.selection = nil+ tab = .bots+ showComputers = true+ case "screen":+ currentStore?.screenRequest = ScreenRequest()+ default:+ break+ }+ }++ private static func makeAccounts(_ storage: SharedStore.Context, session: AccountSession) -> (AccountStore, CloudClient?) {+ let identity = storage.accountID == nil ? nil : try? DeviceIdentity.load(context: storage)+ let cloud = session.cloudClient(for: storage.accountID, identity: identity)+ let accounts = AccountStore(storage: storage, clientKind: "ios", cloud: cloud)+ accounts.onConnected = { store in+ PushRegistrar.shared.syncDevice(with: store)+ store.onUsageChanged = { _, _ in WidgetCenter.shared.reloadTimelines(ofKind: "CodyncUsage") }+ }- accounts.onBotUpdated = { [weak accounts] ref, bot in- guard let accounts else { return }- LiveActivities.shared.update(ref, bot: bot)- BotsWidgetFeed.update(accounts.roster, storage: storage)++ accounts.onBotUpdated = { ref, bot in LiveActivities.shared.update(ref, bot: bot) }++ accounts.onRosterChanged = { roster in+ BotsWidgetFeed.update(roster, storage: storage)+ if roster.isEmpty {+ LiveActivities.shared.endAll()+ WidgetCenter.shared.reloadAllTimelines()+ }}- store.onSent = { [weak store] bot in- guard let store else { return }- LiveActivities.shared.start(for: bot, model: store)+ accounts.onSent = { [weak accounts] ref, bot in+ guard let store = accounts?.store(for: ref.computerId) else { return }+ LiveActivities.shared.start(ref, bot: bot, store: store)+ }+ if let cloud {+ // Signed in: make this iPhone known to the account, then list its computers.+ Task { [weak accounts] in+ do {+ try await cloud.registerDevice(name: UIDevice.current.name, platform: "ios")+ } catch {+ accounts?.lastError = error.localizedDescription+ }+ await accounts?.refreshCloud()+ }}- store.onUsageChanged = { usage in- storage.usage = usage- WidgetCenter.shared.reloadAllTimelines()+ return (accounts, cloud)+ }++ /// Takes back this iPhone's account access to a computer (its grant), and forgets the computer here.+ /// Also the way out when an earlier install was approved but this one never checked the code.+ func revokeAccess(_ id: ComputerID) async {+ guard let cloud else { return }+ let accounts = accounts+ do {+ let identity = try DeviceIdentity.load(context: accounts.storage)+ if let device = try await cloud.devices().first(where: { $0.deviceKey == identity.publicKey }) {+ for grant in try await cloud.grants(id) where grant.deviceId == device.deviceId {+ try await cloud.revokeGrant(id, grantId: grant.grantId)+ }+ }+ accounts.forget(id)+ await accounts.refreshCloud()+ } catch {+ accounts.lastError = error.localizedDescription}- BotsWidgetFeed.update(store.roster, storage: storage)- return store}}@@@ -238,15 -171,34 +246,36 @@@ final class AppDelegate: NSObject, UIAp/// something the widget shows changes (who is working / needs you / unread).@MainActorenum BotsWidgetFeed {- private static var shown = ""+ private struct Snapshot: Equatable {++ let computerId: ComputerID+ let id: String+ let name: String+ let shape: String+ let color: String+ let status: String+ let activity: String+ let message: String?+ let lastAt: Int64+- init(_ bot: Bot) {++ init(_ bot: Bot, computerId: ComputerID) {++ self.computerId = computerId+ id = bot.id; name = bot.name; shape = bot.avatarShape; color = bot.avatarColor+ status = bot.status; activity = bot.activity; message = bot.lastMessage; lastAt = bot.lastAt+ }+ }+ private static var shown: [Snapshot]?+ private static var scope: String?- static func reset() { shown = "" }+ static func reset() { shown = nil; scope = nil }- static func update(_ roster: [Bot], storage: SharedStore.Context) {+ static func update(_ roster: [RosterItem], storage: SharedStore.Context) {+ guard storage.id == SharedStore.activeContext.id else { return }- storage.bots = roster- let currentScope = storage.id + ":" + SharedStore.Context.digest(storage.pairing?.token ?? "unpaired")- let signature = roster.filter { !$0.hidden }.map(Snapshot.init)+ storage.bots = roster.map { BotSnapshot(computerId: $0.ref.computerId, bot: $0.bot) }- let signature = roster.map { "\($0.ref.computerId)/\($0.bot.id):\($0.bot.status):\($0.bot.unread)" }.joined(separator: ",")- guard signature != shown else { return }++ let currentScope = storage.id++ let signature = roster.filter { !$0.bot.hidden }.map { Snapshot($0.bot, computerId: $0.ref.computerId) }+ guard signature != shown || scope != currentScope else { return }shown = signature+ scope = currentScopeWidgetCenter.shared.reloadTimelines(ofKind: "CodyncBots")}}diff --cc apps/ios/Views/AccessRequestView.swiftindex 8b346c47,00000000..64a1a82fmode 100644,000000..100644--- a/apps/ios/Views/AccessRequestView.swift+++ b/apps/ios/Views/AccessRequestView.swift@@@ -1,116 -1,0 +1,125 @@@+import CodyncKit+import CodyncUI+import SwiftUI++/// Asking a computer in the account for access (spec §4.2 B): once both sides committed,+/// the same 6-digit code shows here and on the computer. The user approves there only if they match.+struct AccessRequestView: View {+ let computer: CloudComputer+ @Environment(AccountStore.self) private var accounts+ @Environment(\.dismiss) private var dismiss+ @State private var error: String?+ /// A code was shown: when it goes away without an approval, the request is over (denied or expired).+ @State private var sawTicket: Bool++ init(computer: CloudComputer, pending: Bool) {+ self.computer = computer+ _sawTicket = State(initialValue: pending)+ }++ private var ticket: AccessTicket? { accounts.pendingAccess[computer.computerId] }+ private var approved: Bool { accounts.store(for: computer.computerId) != nil }++ var body: some View {+ VStack(spacing: 24) {+ ComputerBadge(Computer(id: computer.computerId, name: computer.name, signKey: computer.signKey, device: computer.device), size: 64)+ .padding(.top, 32)++ if approved {+ Label("\(computer.name) approved this iPhone", systemImage: "checkmark.circle.fill")+ .font(.headline)+ .foregroundStyle(Palette.added)+ } else if let ticket {+ VStack(spacing: 10) {+ Text("Check the code on \(computer.name)")+ .font(.headline)+ .foregroundStyle(Palette.text)+ Text(spaced(ticket.code))+ .font(.system(size: 52, weight: .semibold, design: .monospaced))+ .foregroundStyle(Palette.text)+ .textSelection(.enabled)+ .accessibilityLabel("Code \(ticket.code.map(String.init).joined(separator: " "))")+ Text("Approve only if the computer shows exactly this code. If it doesn't, deny it there: someone may be trying to get in.")+ .font(.subheadline)+ .foregroundStyle(Palette.secondary)+ .multilineTextAlignment(.center)+ }+ HStack(spacing: 8) {+ ProgressView()+ Text("Waiting for approval…").foregroundStyle(Palette.secondary)++ Button("Cancel request", systemImage: "xmark.circle.fill") {++ Task {++ await accounts.cancelAccess(computer.computerId)++ dismiss()++ }++ }++ .labelStyle(.iconOnly)++ .foregroundStyle(Palette.tertiary)++ .help("Cancel request")+ }+ .font(.subheadline)+ } else if let error {+ Text(error)+ .foregroundStyle(Palette.danger)+ .multilineTextAlignment(.center)+ Button("Try again") { self.error = nil }+ .buttonStyle(.bordered)+ } else if sawTicket {+ Text(accounts.lastError ?? "\(computer.name) didn't approve this request.")+ .foregroundStyle(Palette.secondary)+ .multilineTextAlignment(.center)+ Button("Ask again") {+ accounts.lastError = nil+ sawTicket = false+ }+ .buttonStyle(.bordered)+ } else {+ VStack(spacing: 10) {+ ProgressView()+ Text(computer.isOnline ? "Asking \(computer.name)…" : "\(computer.name) is offline. Turn it on to continue.")+ .font(.subheadline)+ .foregroundStyle(Palette.secondary)+ .multilineTextAlignment(.center)+ }+ .task { await request() }+ }+ Spacer()+ }+ .padding(24)+ .frame(maxWidth: .infinity)+ .background(Palette.background)+ .navigationTitle("Access")+ .navigationBarTitleDisplayMode(.inline)+ .toolbar {+ ToolbarItem(placement: .cancellationAction) {+ // Closing keeps waiting in the background; the computer shows up once approved.+ Button("Close", systemImage: "xmark") { dismiss() }.labelStyle(.iconOnly)+ }+ }+ .onChange(of: ticket?.requestId) { _, id in if id != nil { sawTicket = true } }+ .onChange(of: approved) { _, done in+ guard done else { return }+ Task {+ try? await Task.sleep(for: .seconds(1))+ dismiss()+ }+ }+ }++ /// Runs until the computer answered with its nonce; closing the sheet cancels it.+ private func request() async {+ do {+ _ = try await accounts.requestAccess(computer.computerId)+ } catch is CancellationError {+ return+ } catch {+ guard !Task.isCancelled else { return }+ self.error = error.localizedDescription+ }+ }++ private func spaced(_ code: String) -> String {+ guard code.count == 6 else { return code }+ return "\(code.prefix(3)) \(code.suffix(3))"+ }+}diff --cc apps/ios/Views/PairingView.swiftindex c05c8494,c2aaf7cc..3d863eb3--- a/apps/ios/Views/PairingView.swift+++ b/apps/ios/Views/PairingView.swift@@@ -5,11 -5,11 +5,12 @@@ import VisionKi/// First run: explain the model, then pair with a computer running codync-host.struct PairingView: View {+ var introductory = true- /// Set when adding another computer from the profile sheet; shows a close button.+ /// Set when adding another computer from the computers sheet; shows a close button.var onDone: (() -> Void)?- @Environment(BotStore.self) private var model+ @Environment(AppStore.self) private var app@State private var scanning = false+ @State private var pairing = false@State private var pasted = ""@State private var error: String?@State private var tailscaleOn = Tailscale.isConnecteddiff --cc apps/ios/Views/RootView.swiftindex dc241737,8bd4a492..005832ec--- a/apps/ios/Views/RootView.swift+++ b/apps/ios/Views/RootView.swift@@@ -1,24 -1,28 +1,27 @@@import CodyncKitimport CodyncUIimport SwiftUI--enum AppTab: Hashable { case bots, usage }+import WidgetKitstruct RootView: View {- @Environment(BotStore.self) private var model- @Binding var tab: AppTab+ @Environment(AppStore.self) private var app+ @Environment(AccountStore.self) private var accounts+ @AppStorage("onboardingCompleted") private var onboardingCompleted = false/// The open bot, as a NavigationStack path.- private var path: Binding<[String]> {- Binding(get: { model.selection.map { [$0] } ?? [] }, set: { model.selection = $0.last })+ private var path: Binding<[BotReference]> {+ Binding(get: { accounts.selection.map { [$0] } ?? [] }, set: { accounts.selection = $0.last })}var body: some View {Group {- if model.pairing == nil {+ if accounts.computers.isEmpty && accounts.cloudComputers.isEmpty {NavigationStack {- PairingView()+ PairingView(introductory: !onboardingCompleted).toolbar {- ToolbarItem(placement: .topBarLeading) { AccountSwitcherButton() }+ if onboardingCompleted {+ ToolbarItem(placement: .topBarLeading) { AccountSwitcherButton() }+ }}}} else {@@@ -41,111 -45,15 +44,116 @@@}}.background(Palette.background)- .onChange(of: model.pairing != nil, initial: true) { _, paired in++ .onChange(of: accounts.computers.isEmpty, initial: true) { _, empty in+ // Existing installations have already completed setup. Keep this+ // device-level milestone across account changes and unpairing.- if paired { onboardingCompleted = true }++ if !empty { onboardingCompleted = true }++ }+ .alert("Something went wrong", isPresented: errorShown) {+ Button("OK", role: .cancel) {}+ } message: {+ Text(errorMessage ?? "")+ }+ .fullScreenCover(item: screenTarget) { target in+ if let store = accounts.store(for: target.computerId) {+ ScreenView(watching: target.request.watching)+ .environment(store)+ }+ }+ .sheet(isPresented: Bindable(app).showComputers) {+ NavigationStack { SettingsView() }+ }+ .sheet(isPresented: Binding(get: { app.marketplace != nil }, set: { if !$0 { app.marketplace = nil } })) {+ if let store = app.marketplace.flatMap(accounts.store(for:)) {+ NavigationStack {+ MarketplaceView { app.marketplace = nil }+ }+ .environment(store)+ }+ }+ }++ // MARK: one place for every computer's errors and screen requests++ private var errorMessage: String? {+ accounts.lastError ?? accounts.computers.lazy.compactMap { accounts.store(for: $0.id)?.lastError }.first+ }++ private var errorShown: Binding<Bool> {+ Binding(get: { errorMessage != nil }, set: { shown in+ guard !shown else { return }+ accounts.lastError = nil+ for computer in accounts.computers { accounts.store(for: computer.id)?.lastError = nil }+ })+ }++ private struct ScreenTarget: Identifiable {+ let computerId: ComputerID+ let request: ScreenRequest+ var id: String { "\(computerId)/\(request.id)" }+ }++ /// Any computer's "open the screen" request (thread toolbar, computers list, `codync://screen`).+ private var screenTarget: Binding<ScreenTarget?> {+ Binding(get: {+ accounts.computers.lazy.compactMap { c in+ accounts.store(for: c.id)?.screenRequest.map { ScreenTarget(computerId: c.id, request: $0) }+ }.first+ }, set: { target in+ guard target == nil else { return }+ for computer in accounts.computers { accounts.store(for: computer.id)?.screenRequest = nil }+ })+ }+}++/// A conversation, talking to the computer the bot lives on.+private struct ChatScreen: View {+ let ref: BotReference+ @Environment(AccountStore.self) private var accounts++ var body: some View {+ if let store = accounts.store(for: ref.computerId) {+ ThreadView(botId: ref.botId)+ .environment(store)+ } else {+ ContentUnavailableView("This computer was removed", systemImage: "desktopcomputer.trianglebadge.exclamationmark")}- .storeErrorAlert(model)- .fullScreenCover(item: Bindable(model).screenRequest) { request in- ScreenView(watching: request.watching)- .environment(model)+ }+}++/// Usage for one computer at a time: the last active one, which the Usage widget shows too.+private struct UsageTab: View {+ @Environment(AppStore.self) private var app+ @Environment(AccountStore.self) private var accounts+ /// Picked here; also becomes the computer the Usage widget shows.+ @State private var picked: ComputerID?++ var body: some View {+ if let store = picked.flatMap(accounts.store(for:)) ?? app.currentStore {+ UsageView()+ .environment(store)+ .toolbar {+ if accounts.computers.count > 1 {+ ToolbarItem(placement: .topBarTrailing) {+ Menu {+ Picker("Computer", selection: Binding(get: { store.computer.id }, set: { id in+ picked = id+ accounts.storage.lastComputerId = id+ WidgetCenter.shared.reloadTimelines(ofKind: "CodyncUsage")+ })) {+ ForEach(accounts.computers) { Text($0.name).tag($0.id) }+ }+ } label: {+ ComputerBadge(store.computer, size: 28)+ }+ .accessibilityLabel("Computer: \(store.computer.name)")+ }+ }+ }+ .id(store.computer.id)+ } else {+ ContentUnavailableView("No computer yet", systemImage: "chart.bar",+ description: Text("Usage shows up once a computer is connected."))}}}diff --cc apps/ios/Views/SettingsView.swiftindex 4ade06b0,0e89b41b..edca6028--- a/apps/ios/Views/SettingsView.swift+++ b/apps/ios/Views/SettingsView.swift@@@ -96,17 -101,13 +101,17 @@@ struct SettingsView: ViewButton("Close", systemImage: "xmark") { dismiss() }.labelStyle(.iconOnly)}}+ .refreshable { await accounts.refreshCloud() }+ .task { await accounts.refreshCloud() }.sheet(isPresented: $addingComputer) {- PairingView { addingComputer = false }+ PairingView(introductory: false) { addingComputer = false }}+ .sheet(item: $access) { target in+ NavigationStack { AccessRequestView(computer: target.computer, pending: accounts.pendingAccess[target.id] != nil) }+ }.confirmationDialog("Remove \(confirmForget?.name ?? "computer")?", isPresented: Binding(get: { confirmForget != nil }, set: { if !$0 { confirmForget = nil } }), titleVisibility: .visible) {Button("Remove", role: .destructive) {- if let c = confirmForget { model.forget(c) }- if model.pairing == nil { dismiss() }+ if let c = confirmForget { accounts.forget(c.id) }}} message: {Text("Its bots and conversations stay on that computer. You can pair again any time.")diff --cc apps/ios/Views/WidgetGalleryView.swiftindex 00000000,ee06eb43..c6fd0acbmode 000000,100644..100644--- a/apps/ios/Views/WidgetGalleryView.swift+++ b/apps/ios/Views/WidgetGalleryView.swift@@@ -1,0 -1,196 +1,196 @@@+ import CodyncKit+ import CodyncUI+ import SwiftUI+ import WidgetKit++ /// The installed widgets and these previews share their rendering components.+ struct WidgetGalleryView: View {- @Environment(BotStore.self) private var model++ @Environment(AccountStore.self) private var accounts+ @Environment(\.scenePhase) private var scenePhase+ @Environment(\.dynamicTypeSize) private var typeSize+ @State private var kind = "usage"+ @State private var providerID = "claude"+ @State private var hasWidget: Bool?+ @State private var widgetCheckFailed = false++ private var provider: UsageProvider? { Usage.widgetPreview.providers.first { $0.id == providerID } }++ var body: some View {+ ScrollView {+ VStack(alignment: .leading, spacing: 24) {+ HStack(spacing: 14) {+ CharacterAvatar(shape: "hex", color: "gray", size: 42)+ .frame(width: 58, height: 58)+ .background(Palette.bubbleUser, in: RoundedRectangle(cornerRadius: 16))+ VStack(alignment: .leading, spacing: 4) {+ Text("Codync, at a glance.")+ .font(.title3.weight(.semibold)).tracking(-0.4)+ Text("Your bots and usage, right on your Home Screen.")+ .font(.footnote).foregroundStyle(Palette.secondary)+ }+ }+ .padding(16)+ .frame(maxWidth: .infinity, alignment: .leading)+ .background(Palette.surface, in: RoundedRectangle(cornerRadius: 22))++ VStack(alignment: .leading, spacing: 9) {+ sectionLabel("Get set up")+ VStack(spacing: 0) {- setupRow("Connect a computer", complete: model.pairing != nil)++ setupRow("Connect a computer", complete: !accounts.computers.isEmpty)+ Divider().padding(.leading, 42)+ setupRow("Add a Codync widget", complete: hasWidget == true,+ status: hasWidget == nil ? (widgetCheckFailed ? "Unable to check" : "Checking") : nil)+ }+ .background(Palette.surface, in: RoundedRectangle(cornerRadius: 18))+ if widgetCheckFailed {+ VStack(alignment: .leading, spacing: 6) {+ Text("Couldn't check your widgets. You can still add one using the steps below.")+ .foregroundStyle(Palette.secondary)+ Button("Check again") { checkWidgets() }+ }+ .font(.caption)+ } else {+ Text(hasWidget == nil ? "Checking your widgets…" : "Steps check themselves as you finish them.")+ .font(.caption2).foregroundStyle(Palette.tertiary)+ }+ }++ VStack(alignment: .leading, spacing: 14) {+ HStack {+ sectionLabel("Choose your widget")+ Spacer()+ Text("Sample data").font(.caption2).foregroundStyle(Palette.secondary)+ }+ if typeSize.isAccessibilitySize {+ kindPicker.pickerStyle(.menu)+ if kind == "usage" { providerPicker.pickerStyle(.menu) }+ } else {+ kindPicker.pickerStyle(.segmented)+ if kind == "usage" {+ providerPicker.pickerStyle(.segmented)+ }+ }+ VStack(spacing: 18) {+ preview(wide: true)+ .frame(height: 158)+ ViewThatFits(in: .horizontal) {+ HStack(alignment: .center, spacing: 18) {+ preview(wide: false).frame(width: 158, height: 158)+ previewDescription.frame(minWidth: 100)+ }+ VStack(alignment: .leading, spacing: 12) {+ preview(wide: false).frame(width: 158, height: 158)+ previewDescription+ }+ }+ }+ .padding(14)+ .background(Palette.bubbleAgent, in: RoundedRectangle(cornerRadius: 26))+ }++ guide(number: "01", title: "Add the widget", icon: "plus.square.on.square",+ detail: "Touch and hold your Home Screen. Tap Edit, then Add Widget. Search for Codync and choose Bots or Provider usage.")+ guide(number: "02", title: "Make it yours", icon: "slider.horizontal.3",+ detail: "Touch and hold Provider usage, then tap Edit Widget to choose Claude or Codex. Widgets follow the account selected in Codync.")+ guide(number: "03", title: "On your Lock Screen", icon: "lock",+ detail: "Touch and hold your Lock Screen. Tap Customize, choose the Lock Screen, then tap the widget area. Select Codync to add Bots or Usage limits.")+ Text("Widgets show the last reported state. Open Codync for live updates and approvals.")+ .font(.caption).foregroundStyle(Palette.secondary)+ }+ .padding(18)+ .frame(maxWidth: 560)+ .frame(maxWidth: .infinity)+ }+ .background(Palette.background)+ .navigationTitle("Widgets")+ .navigationBarTitleDisplayMode(.inline)+ .task { checkWidgets() }+ .onChange(of: scenePhase) { _, phase in if phase == .active { checkWidgets() } }+ }++ private var kindPicker: some View {+ Picker("Widget", selection: $kind) {+ Text("Provider usage").tag("usage")+ Text("Bots").tag("bots")+ }+ }++ private var providerPicker: some View {+ Picker("Provider", selection: $providerID) {+ Text("Claude").tag("claude")+ Text("Codex").tag("codex")+ }+ }++ private var previewDescription: some View {+ VStack(alignment: .leading, spacing: 6) {+ Text("Small & medium").font(.subheadline.weight(.medium))+ Text(kind == "usage" ? "Small shows the tightest limit. Medium shows both windows." : "See who needs you and who's still working.")+ .font(.caption).foregroundStyle(Palette.secondary)+ }+ .frame(maxWidth: .infinity, alignment: .leading)+ }++ @ViewBuilder private func preview(wide: Bool) -> some View {+ Group {+ if kind == "usage", let provider {+ ProviderWidgetCard(provider: provider, layout: wide ? .medium : .small)+ } else {+ BotsWidgetCard(bots: Bot.widgetPreview, wide: wide)+ }+ }+ .padding(14)+ .background(Palette.surface, in: RoundedRectangle(cornerRadius: 22))+ .accessibilityElement(children: .contain)+ .accessibilityLabel(wide ? "Medium widget preview" : "Small widget preview")+ }++ private func sectionLabel(_ title: String) -> some View {+ Text(title).font(.caption.weight(.medium)).foregroundStyle(Palette.secondary)+ .accessibilityAddTraits(.isHeader)+ }++ private func setupRow(_ title: String, complete: Bool, status: String? = nil) -> some View {+ HStack(spacing: 10) {+ Image(systemName: complete ? "checkmark.circle.fill" : "circle")+ .foregroundStyle(complete ? Palette.added : Palette.tertiary)+ .font(.system(size: 15))+ Text(title).font(.footnote).foregroundStyle(complete ? Palette.secondary : Palette.text)+ Spacer()+ }+ .padding(14)+ .accessibilityElement(children: .ignore)+ .accessibilityLabel(title)+ .accessibilityValue(status ?? (complete ? "Complete" : "Not complete"))+ }++ private func guide(number: String, title: String, icon: String, detail: String) -> some View {+ VStack(alignment: .leading, spacing: 12) {+ sectionLabel(title)+ HStack(alignment: .top, spacing: 14) {+ VStack(spacing: 8) {+ Image(systemName: icon).font(.system(size: 24, weight: .light))+ Text(number).font(.system(size: 10, weight: .medium, design: .monospaced))+ .foregroundStyle(Palette.tertiary)+ }+ .frame(width: 42)+ Text(detail).font(.footnote).foregroundStyle(Palette.secondary)+ .fixedSize(horizontal: false, vertical: true)+ }+ .padding(18)+ .frame(maxWidth: .infinity, alignment: .leading)+ .background(Palette.surface, in: RoundedRectangle(cornerRadius: 20))+ }+ }++ private func checkWidgets() {+ widgetCheckFailed = false+ WidgetCenter.shared.getCurrentConfigurations { result in+ let installed = (try? result.get())?.contains { $0.kind.hasPrefix("Codync") }+ Task { @MainActor in+ hasWidget = installed+ widgetCheckFailed = installed == nil+ }+ }+ }+ }diff --cc apps/ios/Widgets/CodyncWidgets.swiftindex a3febe2b,7e585b49..81c3fa85--- a/apps/ios/Widgets/CodyncWidgets.swift+++ b/apps/ios/Widgets/CodyncWidgets.swift@@@ -16,47 -16,28 +16,38 @@@ struct CodyncWidgets: WidgetBundle// MARK: - Bots at a glance- /// A bot on one of the account's computers; bot IDs are only unique per computer.- struct WidgetBot: Identifiable {- let bot: Bot- let link: URL?- let id: String-- init(_ snapshot: BotSnapshot, storage: SharedStore.Context?) {- bot = snapshot.bot- link = storage?.botURL(BotReference(accountId: storage?.accountID, computerId: snapshot.computerId, botId: snapshot.bot.id))- id = "\(snapshot.computerId)/\(snapshot.bot.id)"- }- }-struct BotsEntry: TimelineEntry {let date: Date- let bots: [WidgetBot]+ let bots: [Bot]let paired: Bool+ var links: [String: URL] = [:]+- /// The app's snapshot of every computer's bots in the selected account.- static func current(preview: Bool = false) -> BotsEntry {++ /// The app's snapshot of every computer's bots in the selected account. Bot IDs are only++ /// unique per computer, so each copy is re-keyed `<computerId>/<botId>` for the cards and links.++ static var current: BotsEntry {+ let storage = SharedStore.activeContext- let bots = storage.bots.map { WidgetBot($0, storage: storage) }- if bots.isEmpty && preview { return .sample }- return BotsEntry(date: .now, bots: bots, paired: !storage.computers.isEmpty)- }-- static var sample: BotsEntry {- BotsEntry(date: .now, bots: Bot.samples.map { WidgetBot(BotSnapshot(computerId: "sample", bot: $0), storage: nil) }, paired: true)++ var bots: [Bot] = []++ var links: [String: URL] = [:]++ for snapshot in storage.bots {++ var bot = snapshot.bot++ bot.id = "\(snapshot.computerId)/\(snapshot.bot.id)"++ links[bot.id] = storage.botURL(BotReference(accountId: storage.accountID, computerId: snapshot.computerId, botId: snapshot.bot.id))++ bots.append(bot)++ }++ return BotsEntry(date: .now, bots: bots, paired: !storage.computers.isEmpty, links: links)+ }}struct BotsTimeline: TimelineProvider {- func placeholder(in context: Context) -> BotsEntry { .sample }+ func placeholder(in context: Context) -> BotsEntry { BotsEntry(date: .now, bots: Bot.widgetPreview, paired: true) }func getSnapshot(in context: Context, completion: @escaping (BotsEntry) -> Void) {- completion(.current(preview: context.isPreview))- let storage = SharedStore.activeContext- completion(BotsEntry(date: .now, bots: context.isPreview ? Bot.widgetPreview : storage.bots,- paired: context.isPreview || storage.pairing != nil))++ completion(context.isPreview ? placeholder(in: context) : .current)}/// The app writes the roster and reloads this widget when a bot's state changes.func getTimeline(in context: Context, completion: @escaping (Timeline<BotsEntry>) -> Void) {- completion(Timeline(entries: [.current()], policy: .never))- let storage = SharedStore.activeContext- let entry = BotsEntry(date: .now, bots: storage.bots, paired: storage.pairing != nil,- links: Dictionary(storage.bots.map { ($0.id, storage.botURL($0.id)) }, uniquingKeysWith: { a, _ in a }))- completion(Timeline(entries: [entry], policy: .never))++ completion(Timeline(entries: [.current], policy: .never))}}@@@ -222,7 -152,7 +162,7 @@@ struct UsageTimeline: AppIntentTimeline}func snapshot(for configuration: UsageIntent, in context: Context) async -> UsageEntry {- UsageEntry(date: .now, usage: Self.cached ?? .sample)- UsageEntry(date: .now, usage: context.isPreview ? .widgetPreview : (SharedStore.usage ?? Usage()))++ UsageEntry(date: .now, usage: context.isPreview ? .widgetPreview : (Self.cached ?? Usage()))}/// Refreshes every 30 minutes, or right after the next limit resets if that's sooner.@@@ -231,32 -161,26 +171,37 @@@}static func timeline() async -> Timeline<UsageEntry> {- let fetched = await fetch()+ let storage = SharedStore.activeContext- let computer = storage.pairing?.token++ let computer = storage.lastComputerId+ let fetched = await fetch(storage: storage)- guard SharedStore.activeContext.id == storage.id, storage.pairing?.token == computer else {++ // The app switched account or computer meanwhile: redraw from the new one shortly.++ guard SharedStore.activeContext.id == storage.id, storage.lastComputerId == computer else {+ return Timeline(entries: [UsageEntry(date: .now, usage: Usage())], policy: .after(.now + 5))+ }- let usage = fetched ?? storage.usage ?? Usage()+ let usage = fetched ?? cached ?? Usage()let nextReset = usage.providers.flatMap(\.windows).compactMap(\.resetDate).filter { $0 > .now }.min()var next = Date.now + (fetched == nil ? 5 * 60 : 30 * 60)if let nextReset, nextReset + 1 < next { next = max(nextReset + 1, .now + 5 * 60) }return Timeline(entries: [UsageEntry(date: .now, usage: usage)], policy: .after(next))}- /// Asks the paired host directly (works over Tailscale), falling back to the app's cache.- /// `refresh` makes the host re-read the limits first instead of answering from its cache.+ /// The last active computer's usage, as the app last saw it.+ static var cached: Usage? {+ let storage = SharedStore.activeContext+ return storage.lastComputerId.flatMap { storage.usage[$0] }+ }++ /// Asks the last active computer directly or through the relay, one call, then disconnects;+ /// nil falls back to the app's cache. `refresh` makes the host re-read the limits first.- static func fetch(refresh: Bool = false) async -> Usage? {- let storage = SharedStore.activeContext+ static func fetch(refresh: Bool = false, storage: SharedStore.Context = SharedStore.activeContext) async -> Usage? {- guard let pairing = storage.orderedPairing, let client = await HostClient.resolve(pairing),- let usage = try? await client.usage(refresh: refresh),- SharedStore.activeContext.id == storage.id, storage.pairing?.token == pairing.token else { return nil }- storage.usage = usage+ // Keys exist once a computer is saved; the widget never creates them.+ guard let id = storage.lastComputerId, let computer = storage.computers.first(where: { $0.id == id }),+ let identity = try? DeviceIdentity.load(context: storage),+ let transport = try? await HostConnector.connect(computer, identity: identity) else { return nil }+ let usage = try? await HostClient(transport: transport).usage(refresh: refresh)+ await transport.shutdown()- guard let usage else { return nil }++ guard let usage, SharedStore.activeContext.id == storage.id, storage.lastComputerId == id else { return nil }+ storage.usage[id] = usagereturn usage}}@@@ -403,7 -323,7 +344,7 @@@ struct ProviderUsageTimeline: AppIntent}func snapshot(for configuration: ProviderUsageIntent, in context: Context) async -> ProviderUsageEntry {- let usage = UsageTimeline.cached.flatMap { $0.providers.isEmpty ? nil : $0 } ?? .preview- let usage = context.isPreview ? .widgetPreview : (SharedStore.usage ?? Usage())++ let usage = context.isPreview ? .widgetPreview : (UsageTimeline.cached ?? Usage())return ProviderUsageEntry(date: .now, usage: usage, provider: configuration.provider)}diff --cc apps/macos/Views/ComputersView.swiftindex 44234137,00000000..f53b6c6fmode 100644,000000..100644--- a/apps/macos/Views/ComputersView.swift+++ b/apps/macos/Views/ComputersView.swift@@@ -1,601 -1,0 +1,608 @@@+import AppKit+import CodyncKit+import CodyncUI+import SwiftUI+import UniformTypeIdentifiers++/// A computer's name over its bots in the sidebar, with how it's reached.+struct ComputerHeader: View {+ let store: BotStore+ let ssh: Bool++ var body: some View {+ HStack(spacing: 6) {+ ComputerBadge(store.computer, size: 16)+ Text(store.hostName).font(.system(size: 11, weight: .semibold)).lineLimit(1)+ RouteLabel(store: store, ssh: ssh)+ Spacer()+ if store.connection != .online {+ Text(store.statusText).font(.system(size: 11)).foregroundStyle(store.isOffline ? Palette.warning : Palette.tertiary)+ }+ }+ .foregroundStyle(Palette.secondary)+ .padding(.horizontal, 8)+ .padding(.top, 10)+ .padding(.bottom, 2)+ .accessibilityElement(children: .combine)+ .accessibilityAddTraits(.isHeader)+ }+}++/// How this Mac reaches a computer: itself, an SSH tunnel, direct LAN or the encrypted relay.+struct RouteLabel: View {+ let store: BotStore+ let ssh: Bool++ var body: some View {+ if ssh {+ Image(systemName: "terminal").help("Over SSH").accessibilityLabel("Over SSH")+ } else if store.connection == .online {+ RouteIcon(route: store.hostRoute).help(store.hostRoute == .relay ? "Through the encrypted relay" : "Direct connection")+ }+ }+}++// MARK: - Approval++/// A device asks for access through the account (spec §4.2 B). The code is the only thing+/// that tells a real request from a cloud swapping keys, so it's big and Approve is never the default.+struct ApprovalSheet: View {+ let approval: Approval+ @Environment(HostController.self) private var host+ @State private var busy = false+ @State private var error: String?++ private var request: AccessRequest { approval.request }++ var body: some View {+ VStack(spacing: 16) {+ HStack {+ Spacer()+ IconButton("Decide later", systemImage: "xmark") { host.deferApproval(approval) }+ }+ Image(systemName: request.platform == "macos" ? "laptopcomputer" : "iphone")+ .font(.system(size: 40, weight: .light))+ .foregroundStyle(Palette.secondary)+ .accessibilityHidden(true)+ VStack(spacing: 4) {+ Text("\(request.deviceName) wants to use \(approval.store.hostName)")+ .font(.title3.weight(.semibold))+ .multilineTextAlignment(.center)+ if let email = request.email {+ Text("Signed in as \(email)").font(.callout).foregroundStyle(Palette.secondary)+ }+ }+ if let code = request.code {+ Text(Self.spaced(code))+ .font(.system(size: 48, weight: .semibold, design: .monospaced))+ .foregroundStyle(Palette.text)+ .textSelection(.enabled)+ .accessibilityLabel("Code \(code.map(String.init).joined(separator: " "))")+ Text("Approve only if \(request.deviceName) shows exactly this code. If it doesn't, deny: someone may be trying to get in.")+ .font(.callout)+ .foregroundStyle(Palette.secondary)+ .multilineTextAlignment(.center)+ .fixedSize(horizontal: false, vertical: true)+ } else {+ ProgressView().controlSize(.small)+ Text("Waiting for \(request.deviceName) to show its code…")+ .font(.callout)+ .foregroundStyle(Palette.secondary)+ }+ if let error {+ Text(error).font(.caption).foregroundStyle(Palette.danger).multilineTextAlignment(.center)+ }+ HStack(spacing: 12) {+ Button("Deny", role: .destructive) { decide(false) }+ .disabled(busy)+ Button("Approve") { decide(true) }+ .buttonStyle(.borderedProminent)+ .tint(Palette.accentFill)+ .disabled(busy || request.code == nil)+ }+ .controlSize(.large)+ }+ .padding(24)+ .frame(width: 420)+ }++ private func decide(_ approve: Bool) {+ busy = true+ Task {+ defer { busy = false }+ do {+ try await host.decide(approval, approve: approve)+ // The host's accessRequests event removes it; don't wait for that to close.+ host.deferApproval(approval)+ } catch {+ self.error = error.localizedDescription+ }+ }+ }++ private static func spaced(_ code: String) -> String {+ code.count == 6 ? "\(code.prefix(3)) \(code.suffix(3))" : code+ }+}++// MARK: - Computers & devices++/// Computers this Mac manages (itself and SSH), with their account, relay and authorized devices;+/// SSH profiles; and the account's other computers.+struct ComputersView: View {+ let close: () -> Void+ @Environment(HostController.self) private var host+ @Environment(AccountSession.self) private var account+ @State private var editingSSH: SSHProfile?++ var body: some View {+ VStack(spacing: 0) {+ HStack {+ Text("Computers & devices").font(.title2.bold())+ Spacer()+ Button("Done", action: close).keyboardShortcut(.cancelAction)+ }+ .padding(20)+ ScrollView {+ VStack(alignment: .leading, spacing: 22) {+ ForEach(host.managedStores, id: \.computer.id) { store in+ ManagedComputerCard(store: store, ssh: host.isSSH(store.computer.id))+ }+ sshSection+ accountSection+ }+ .padding(.horizontal, 20)+ .padding(.bottom, 20)+ }+ }+ .background(Palette.background)+ .sheet(item: $editingSSH) { profile in+ SSHProfileEditor(profile: profile, isNew: !host.ssh.profiles.contains { $0.id == profile.id }) { editingSSH = nil }+ }+ }++ private var sshSection: some View {+ VStack(alignment: .leading, spacing: 8) {+ HStack {+ SectionTitle("Over SSH")+ Spacer()+ IconButton("Add SSH computer", systemImage: "plus") {+ editingSSH = SSHProfile(host: "", name: "")+ }+ }+ if host.ssh.profiles.isEmpty {+ Text("Run bots on another computer you reach with SSH. It needs codync-host installed; your SSH keys stay on this Mac.")+ .font(.callout)+ .foregroundStyle(Palette.secondary)+ .fixedSize(horizontal: false, vertical: true)+ }+ ForEach(host.ssh.profiles) { profile in+ SSHRow(profile: profile) { editingSSH = profile }+ }+ }+ }++ @ViewBuilder private var accountSection: some View {+ let managed = Set(host.managedStores.map(\.computer.id))+ let reached = host.accounts.computers.filter { !managed.contains($0.id) }+ let others = host.accounts.cloudComputers.filter { c in !managed.contains(c.id) && !reached.contains { $0.id == c.id } }+ VStack(alignment: .leading, spacing: 8) {+ HStack {+ SectionTitle("In your account")+ Spacer()+ if account.isSignedIn {+ IconButton("Refresh", systemImage: "arrow.clockwise") { Task { await host.accounts.refreshCloud() } }+ }+ }+ if !account.isSignedIn {+ Text("Sign in to reach the other computers in your account from this Mac.")+ .font(.callout).foregroundStyle(Palette.secondary)+ } else if reached.isEmpty && others.isEmpty {+ Text("No other computers in your account yet.").font(.callout).foregroundStyle(Palette.secondary)+ }+ ForEach(reached) { computer in+ if let store = host.accounts.store(for: computer.id) {+ HStack(spacing: 10) {+ ComputerBadge(store.computer, size: 22)+ VStack(alignment: .leading, spacing: 1) {+ Text(store.hostName).font(.callout.weight(.medium))+ Text(store.statusText).font(.caption).foregroundStyle(Palette.secondary)+ }+ RouteLabel(store: store, ssh: false).foregroundStyle(Palette.tertiary)+ Spacer()+ IconButton("Remove from this Mac", systemImage: "minus.circle") { host.accounts.forget(computer.id) }+ }+ .card()+ }+ }+ ForEach(others) { computer in+ AccountComputerRow(computer: computer)+ }+ }+ }+}++private struct SectionTitle: View {+ let title: String+ init(_ title: String) { self.title = title }+ var body: some View {+ Text(title).font(.headline).foregroundStyle(Palette.text).accessibilityAddTraits(.isHeader)+ }+}++/// An account computer this Mac isn't authorized on: ask, then compare the code shown there.+private struct AccountComputerRow: View {+ let computer: CloudComputer+ @Environment(HostController.self) private var host+ @State private var busy = false++ var body: some View {+ let ticket = host.accounts.pendingAccess[computer.id]+ VStack(alignment: .leading, spacing: 8) {+ HStack(spacing: 10) {+ ComputerBadge(Computer(id: computer.id, name: computer.name, signKey: computer.signKey, device: computer.device), size: 22)+ VStack(alignment: .leading, spacing: 1) {+ Text(computer.name).font(.callout.weight(.medium))+ Text(computer.isOnline ? "Online" : "Offline").font(.caption).foregroundStyle(Palette.secondary)+ }+ Spacer()+ if ticket == nil {+ Button(busy ? "Asking…" : "Ask for access") {+ busy = true+ Task {+ defer { busy = false }+ do { _ = try await host.accounts.requestAccess(computer.id) } catch {+ host.accounts.lastError = error.localizedDescription+ }+ }+ }+ .disabled(busy)+ }+ }+ if let ticket {+ HStack(spacing: 12) {+ Text(ticket.code.count == 6 ? "\(ticket.code.prefix(3)) \(ticket.code.suffix(3))" : ticket.code)+ .font(.system(size: 26, weight: .semibold, design: .monospaced))+ .accessibilityLabel("Code \(ticket.code.map(String.init).joined(separator: " "))")+ Text("Approve on \(computer.name) only if it shows this code.")+ .font(.callout).foregroundStyle(Palette.secondary)+ .fixedSize(horizontal: false, vertical: true)++ Spacer()++ Button("Cancel request", systemImage: "xmark.circle") {++ Task { await host.accounts.cancelAccess(computer.id) }++ }++ .labelStyle(.iconOnly)++ .buttonStyle(.borderless)++ .help("Cancel request")+ }+ }+ }+ .card()+ }+}++/// This Mac or an SSH computer: relay, account membership, pairing and authorized devices.+private struct ManagedComputerCard: View {+ let store: BotStore+ let ssh: Bool+ @Environment(HostController.self) private var host+ @Environment(AccountSession.self) private var account+ @State private var devices: [AuthorizedDevice]?+ @State private var busy = false+ @State private var showPairing = false+ @State private var confirmRevoke: AuthorizedDevice?+ @State private var confirmUnclaim = false++ private var cloud: CloudStatus? { store.cloud }++ var body: some View {+ VStack(alignment: .leading, spacing: 12) {+ HStack(spacing: 10) {+ ComputerBadge(store.computer, size: 26)+ VStack(alignment: .leading, spacing: 1) {+ Text(store.hostName).font(.headline)+ Text(ssh ? "Over SSH · \(store.statusText)" : "This Mac · \(store.statusText)")+ .font(.caption).foregroundStyle(Palette.secondary)+ }+ Spacer()+ IconButton("Pair iPhone", systemImage: "qrcode", selected: showPairing) { showPairing.toggle() }+ .disabled(store.connection != .online)+ .popover(isPresented: $showPairing, arrowEdge: .bottom) {+ PairingPanel(store: store).frame(width: 300)+ }+ }++ Toggle(isOn: Binding(get: { cloud?.enabled ?? false }, set: { on in run { await host.setCloud(store, enabled: on) } })) {+ VStack(alignment: .leading, spacing: 1) {+ Text("Reach from anywhere")+ Text(cloudLine).font(.caption).foregroundStyle(cloud?.lastError == nil ? Palette.secondary : Palette.warning)+ }+ }+ .toggleStyle(.switch)+ .disabled(busy || store.connection != .online)++ accountLine++ VStack(alignment: .leading, spacing: 6) {+ Text("Devices that can use \(store.hostName)").font(.subheadline.weight(.semibold))+ if let devices {+ if devices.isEmpty {+ Text("None yet. Pair an iPhone, or approve one from your account.").font(.caption).foregroundStyle(Palette.secondary)+ }+ ForEach(devices) { device in deviceRow(device) }+ } else {+ ProgressView().controlSize(.small)+ }+ }+ }+ .card()+ .task(id: "\(store.computer.id)/\(store.connection == .online)/\(store.accessRequests.count)") { await loadDevices() }+ .confirmationDialog("Revoke \(confirmRevoke?.name ?? "device")?", isPresented: Binding(+ get: { confirmRevoke != nil }, set: { if !$0 { confirmRevoke = nil } }+ ), titleVisibility: .visible) {+ if let device = confirmRevoke {+ Button("Revoke access", role: .destructive) {+ run {+ do { try await store.client?.revokeDevice(device.key) } catch { host.accounts.lastError = error.localizedDescription }+ await loadDevices()+ }+ }+ }+ } message: {+ Text("It disconnects right away and has to pair or ask again.")+ }+ .confirmationDialog("Remove \(store.hostName) from the account?", isPresented: $confirmUnclaim, titleVisibility: .visible) {+ Button("Remove from account", role: .destructive) { run { await host.unclaim(store) } }+ } message: {+ Text("Devices that were approved through the account lose access. Devices paired with a QR code keep it.")+ }+ }++ private var cloudLine: String {+ guard let cloud, cloud.enabled else { return "Off: only devices on the same network reach it." }+ if let error = cloud.lastError { return error }+ return cloud.connected == true ? "Connected to the encrypted relay." : "Connecting to the relay…"+ }++ @ViewBuilder private var accountLine: some View {+ HStack(spacing: 8) {+ if let owner = cloud?.owner {+ Image(systemName: "person.crop.circle.badge.checkmark").foregroundStyle(Palette.secondary).accessibilityHidden(true)+ Text(owner.userId == account.userID ? "In your account" : "In \(owner.email ?? "another") account")+ .font(.callout)+ Spacer()+ Button("Remove from account") { confirmUnclaim = true }+ .disabled(busy || store.connection != .online)+ } else {+ Image(systemName: "person.crop.circle.badge.plus").foregroundStyle(Palette.secondary).accessibilityHidden(true)+ Text(account.isSignedIn ? "Not in your account" : "Sign in to add it to your account").font(.callout)+ Spacer()+ if account.isSignedIn {+ Button(busy ? "Adding…" : "Add to account") { run { await host.claim(store) } }+ .disabled(busy || store.connection != .online)+ }+ }+ }+ }++ private func deviceRow(_ device: AuthorizedDevice) -> some View {+ HStack(spacing: 8) {+ Image(systemName: device.platform == "macos" ? "laptopcomputer" : "iphone")+ .frame(width: 18)+ .foregroundStyle(Palette.secondary)+ .accessibilityHidden(true)+ VStack(alignment: .leading, spacing: 1) {+ Text(device.name).font(.callout)+ Text(detail(device)).font(.caption).foregroundStyle(Palette.tertiary)+ }+ Spacer()+ IconButton("Revoke access", systemImage: "xmark.circle") { confirmRevoke = device }+ }+ .accessibilityElement(children: .combine)+ }++ private func detail(_ device: AuthorizedDevice) -> String {+ var parts = [device.source == "account" ? "Approved through the account" : "Paired with a QR code"]+ if device.connected == true {+ parts.append("connected")+ } else if let seen = device.lastSeenAt {+ parts.append("seen \(RelativeTime.day(Date(milliseconds: seen)))")+ }+ return parts.joined(separator: " · ")+ }++ private func loadDevices() async {+ guard let client = store.client, store.connection == .online else { return }+ devices = (try? await client.devices()) ?? devices+ }++ private func run(_ work: @escaping @MainActor () async -> Void) {+ busy = true+ Task {+ await work()+ busy = false+ }+ }+}++// MARK: - SSH++private struct SSHRow: View {+ let profile: SSHProfile+ let edit: () -> Void+ @Environment(HostController.self) private var host++ var body: some View {+ let status = host.ssh.status(of: profile.id)+ VStack(alignment: .leading, spacing: 8) {+ HStack(spacing: 10) {+ Image(systemName: "terminal").frame(width: 22).foregroundStyle(Palette.secondary).accessibilityHidden(true)+ VStack(alignment: .leading, spacing: 1) {+ Text(profile.name.isEmpty ? profile.host : profile.name).font(.callout.weight(.medium))+ Text(line(status)).font(.caption).foregroundStyle(isProblem(status) ? Palette.warning : Palette.secondary)+ .fixedSize(horizontal: false, vertical: true)+ }+ Spacer()+ switch status {+ case .connected, .connecting, .retrying:+ IconButton("Disconnect", systemImage: "stop.circle") { host.ssh.disconnect(profile.id) }+ default:+ IconButton("Connect", systemImage: "arrow.clockwise") { host.ssh.connect(profile.id) }+ }+ IconButton("Edit", systemImage: "pencil", action: edit)+ IconButton("Remove", systemImage: "trash") { host.ssh.remove(profile.id) }+ }+ if case let .confirmHostKey(name, fingerprints, _) = status {+ VStack(alignment: .leading, spacing: 6) {+ Text("First connection to \(name). Check that its host key fingerprint matches what the computer's owner sees (`ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`).")+ .font(.caption).foregroundStyle(Palette.secondary)+ .fixedSize(horizontal: false, vertical: true)+ ForEach(fingerprints, id: \.self) { Text($0).font(.caption.monospaced()).textSelection(.enabled) }+ HStack {+ Button("Trust and connect") { host.ssh.trustHostKey(profile.id) }+ Button("Cancel") { host.ssh.disconnect(profile.id) }+ }+ .controlSize(.small)+ }+ }+ if status == .notInstalled {+ HStack(spacing: 6) {+ Text(SSH.installCommand)+ .font(.caption.monospaced())+ .textSelection(.enabled)+ .padding(6)+ .frame(maxWidth: .infinity, alignment: .leading)+ .background(Palette.codeBackground, in: RoundedRectangle(cornerRadius: 6))+ IconButton("Copy install command", systemImage: "doc.on.doc") {+ NSPasteboard.general.clearContents()+ NSPasteboard.general.setString(SSH.installCommand, forType: .string)+ }+ }+ }+ }+ .card()+ }++ private func line(_ status: SSHComputers.Status) -> String {+ let target = [profile.user.map { "\($0)@" } ?? "", profile.host, profile.port.map { ":\($0)" } ?? ""].joined()+ switch status {+ case .idle: return "\(target) · Not connected"+ case let .connecting(step): return step+ case .confirmHostKey: return "\(target) · Confirm the host key"+ case .connected: return "\(target) · Connected"+ case let .retrying(message): return "\(message) Retrying…"+ case let .failed(message): return message+ case .notInstalled: return "codync-host isn't installed on \(profile.host). Install it there:"+ }+ }++ private func isProblem(_ status: SSHComputers.Status) -> Bool {+ switch status {+ case .retrying, .failed, .notInstalled: true+ default: false+ }+ }+}++/// Add or change an SSH computer. Only fields ssh takes as separate arguments; nothing goes through a shell.+private struct SSHProfileEditor: View {+ @State var profile: SSHProfile+ let isNew: Bool+ let close: () -> Void+ @Environment(HostController.self) private var host+ @State private var port = ""+ @State private var remotePort = ""+ @State private var user = ""+ @State private var chooseKey = false+ @State private var problem: String?++ init(profile: SSHProfile, isNew: Bool, close: @escaping () -> Void) {+ _profile = State(initialValue: profile)+ self.isNew = isNew+ self.close = close+ _port = State(initialValue: profile.port.map(String.init) ?? "")+ _remotePort = State(initialValue: String(profile.remotePort))+ _user = State(initialValue: profile.user ?? "")+ }++ var body: some View {+ VStack(alignment: .leading, spacing: 16) {+ Text(isNew ? "Add SSH computer" : "Edit SSH computer").font(.title3.bold())+ Form {+ TextField("Name", text: $profile.name, prompt: Text("Optional"))+ TextField("Host", text: $profile.host, prompt: Text("SSH alias or hostname"))+ TextField("User", text: $user, prompt: Text("From SSH config"))+ TextField("SSH port", text: $port, prompt: Text("From SSH config"))+ HStack {+ Text("Key")+ Spacer()+ Text(profile.identityFile.map { URL(filePath: $0).lastPathComponent } ?? "ssh-agent / SSH config")+ .foregroundStyle(Palette.secondary)+ IconButton("Choose key file", systemImage: "key") { chooseKey = true }+ if profile.identityFile != nil {+ IconButton("Use ssh-agent", systemImage: "xmark.circle") { profile.identityFile = nil }+ }+ }+ TextField("Codync port", text: $remotePort)+ }+ .formStyle(.grouped)+ Text("Codync opens an SSH tunnel to codync-host on that computer's loopback. It uses your SSH config and ssh-agent; agent forwarding stays off.")+ .font(.caption).foregroundStyle(Palette.secondary)+ .fixedSize(horizontal: false, vertical: true)+ if let problem {+ Text(problem).font(.caption).foregroundStyle(Palette.danger)+ }+ HStack {+ Spacer()+ Button("Cancel", action: close).keyboardShortcut(.cancelAction)+ Button(isNew ? "Add" : "Save", action: save).keyboardShortcut(.defaultAction)+ }+ }+ .padding(20)+ .frame(width: 460)+ .fileImporter(isPresented: $chooseKey, allowedContentTypes: [.item]) { result in+ if case let .success(url) = result { profile.identityFile = url.path }+ }+ }++ private func save() {+ var p = profile+ p.host = p.host.trimmingCharacters(in: .whitespaces)+ p.name = p.name.trimmingCharacters(in: .whitespaces)+ let u = user.trimmingCharacters(in: .whitespaces)+ p.user = u.isEmpty ? nil : u+ let portText = port.trimmingCharacters(in: .whitespaces)+ if portText.isEmpty {+ p.port = nil+ } else if let n = Int(portText) {+ p.port = n+ } else {+ problem = "The SSH port must be a number."+ return+ }+ guard let remote = Int(remotePort.trimmingCharacters(in: .whitespaces)) else {+ problem = "The Codync port must be a number."+ return+ }+ p.remotePort = remote+ if !isNew, let old = host.ssh.profiles.first(where: { $0.id == p.id }), old.host != p.host || old.port != p.port {+ // A different address may be a different computer: learn its identity again.+ p.computerId = nil+ }+ if let problem = SSH.validate(p) {+ self.problem = problem+ return+ }+ if isNew { host.ssh.add(p) } else { host.ssh.update(p) }+ close()+ }+}++private extension View {+ func card() -> some View {+ padding(12)+ .frame(maxWidth: .infinity, alignment: .leading)+ .background(Palette.surface, in: RoundedRectangle(cornerRadius: 12, style: .continuous))+ .overlay(RoundedRectangle(cornerRadius: 12, style: .continuous).strokeBorder(Palette.border, lineWidth: 0.5))+ }+}diff --cc cloud/test/e2e/relay.e2e.tsindex 6d1d426d,00000000..b589c280mode 100644,000000..100644--- a/cloud/test/e2e/relay.e2e.ts+++ b/cloud/test/e2e/relay.e2e.ts@@@ -1,293 -1,0 +1,296 @@@+// Cross-track integration test (spec §12.1): the real codync-host against `wrangler dev`, driven by a+// fake phone. Run with `npm run e2e` after `cargo build` in host/ (or set CODYNC_HOST_BIN).+//+// Steps: local D1 + wrangler dev with a test Clerk key → host with CODYNC_CLOUD_URL → QR pairing over the+// relay → chat through the relay → mailbox while the host is down → account claim + SAS access request →+// cloud revocation → injected grant ignored → direct /channel and loopback-only bearer token.+- import { type ChildProcess, spawn, spawnSync } from "node:child_process";++import { type ChildProcess, execFile, spawn, spawnSync } from "node:child_process";+import { generateKeyPairSync } from "node:crypto";+import { mkdtempSync, readFileSync, rmSync } from "node:fs";+import { createServer } from "node:net";+import { networkInterfaces, tmpdir } from "node:os";+import { join } from "node:path";+import { fileURLToPath } from "node:url";+import * as ref from "../ref.ts";+import { Channel, FakePhone, parsePairing, waitFor, type Json, type PairingInfo, type Wire } from "./phone.ts";++const CLOUD_DIR = fileURLToPath(new URL("../..", import.meta.url));+const ROOT = join(CLOUD_DIR, "..");+const HOST_BIN = process.env.CODYNC_HOST_BIN ?? join(ROOT, "host/target/debug/codync-host");+const FAKE_AGENT = join(ROOT, "host/tests/fake_agent.py");+const CLOUD_PORT = Number(process.env.CODYNC_E2E_CLOUD_PORT ?? 8787);+const CLOUD = `http://127.0.0.1:${CLOUD_PORT}`;+const ISSUER = "https://clerk.test.local"; // [env.dev] CLERK_ISSUER+const WRANGLER = join(CLOUD_DIR, "node_modules/.bin/wrangler");++const tmp = mkdtempSync(join(tmpdir(), "codync-e2e-"));+const persist = join(tmp, "wrangler");+const home = join(tmp, "home");+const children: ChildProcess[] = [];++function step(name: string) {+ console.log(`\n▶ ${name}`);+}++function check(cond: unknown, what: string): asserts cond {+ if (!cond) throw new Error(`check failed: ${what}`);+ console.log(` ✓ ${what}`);+}++async function freePort(): Promise<number> {+ return new Promise((resolve) => {+ const s = createServer();+ s.listen(0, "127.0.0.1", () => {+ const port = (s.address() as { port: number }).port;+ s.close(() => resolve(port));+ });+ });+}++function run(cmd: string, args: string[], env: Record<string, string> = {}): ChildProcess {+ const child = spawn(cmd, args, { cwd: CLOUD_DIR, env: { ...process.env, ...env }, stdio: ["ignore", "pipe", "pipe"] });+ const tag = cmd.split("/").pop();+ child.stdout?.on("data", (d) => process.env.E2E_VERBOSE && process.stdout.write(`[${tag}] ${d}`));+ child.stderr?.on("data", (d) => process.env.E2E_VERBOSE && process.stderr.write(`[${tag}] ${d}`));+ children.push(child);+ return child;+}++async function stop(child: ChildProcess) {+ if (child.exitCode !== null || child.signalCode) return;+ const exited = new Promise((r) => child.once("exit", r));+ child.kill("SIGTERM");+ await Promise.race([exited, new Promise((r) => setTimeout(r, 5000))]);+ if (child.exitCode === null && !child.signalCode) child.kill("SIGKILL");+}+- function d1(sql: string): Json[] {- const r = spawnSync(WRANGLER, ["d1", "execute", "codync-dev", "--local", "--env", "dev", "--persist-to", persist, "--json", "--command", sql], {- cwd: CLOUD_DIR,- encoding: "utf8",- });- if (r.status !== 0) throw new Error(`d1 failed: ${r.stderr}`);- return (JSON.parse(r.stdout) as { results: Json[] }[])[0]?.results ?? [];++/// Async on purpose: a blocking spawn stalls the event loop past wrangler's keep-alive timeout, and++/// the next `fetch` then reuses a socket the server already closed (ECONNRESET).++function d1(sql: string): Promise<Json[]> {++ const args = ["d1", "execute", "codync-dev", "--local", "--env", "dev", "--persist-to", persist, "--json", "--command", sql];++ return new Promise((resolve, reject) =>++ execFile(WRANGLER, args, { cwd: CLOUD_DIR, encoding: "utf8" }, (err, stdout, stderr) => {++ if (err) return reject(new Error(`d1 failed: ${stderr}`));++ resolve((JSON.parse(stdout) as { results: Json[] }[])[0]?.results ?? []);++ }),++ );+}++// ---- Clerk test tokens ----++const { publicKey, privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });+// @clerk/backend strips PEM armor itself; a single line survives `--var`.+const jwtKey = publicKey+ .export({ type: "spki", format: "pem" })+ .toString()+ .replace(/-----[A-Z ]+-----|\s/g, "");++async function clerkToken(sub: string): Promise<string> {+ const key = await crypto.subtle.importKey("jwk", privateKey.export({ format: "jwk" }), { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, [+ "sign",+ ]);+ const now = Math.floor(Date.now() / 1000);+ const part = (v: unknown) => ref.b64url(ref.enc.encode(JSON.stringify(v)));+ const head = `${part({ alg: "RS256", typ: "JWT" })}.${part({ iss: ISSUER, sub, sid: `sess_${sub}`, iat: now - 5, nbf: now - 5, exp: now + 3600, email: `${sub}@example.com` })}`;+ return `${head}.${ref.b64url(new Uint8Array(await crypto.subtle.sign("RSASSA-PKCS1-v1_5", key, ref.enc.encode(head))))}`;+}++async function cloud(method: string, path: string, o: { token?: string; key?: ref.SignKey; body?: unknown } = {}): Promise<{ status: number; body: Json }> {+ const bytes = o.body === undefined ? new Uint8Array() : ref.enc.encode(JSON.stringify(o.body));+ const headers: Record<string, string> = {};+ if (o.token) headers.Authorization = `Bearer ${o.token}`;+ if (o.body !== undefined) headers["Content-Type"] = "application/json";+ if (o.key) headers["Codync-Sig"] = ref.signRequest(o.key, { method, authority: `127.0.0.1:${CLOUD_PORT}`, pathAndQuery: path, body: bytes });+ const res = await fetch(CLOUD + path, { method, headers, body: bytes.length ? bytes : undefined });+ return { status: res.status, body: await res.json() };+}++// ---- the host ----++let hostPort = 0;+let host: ChildProcess | undefined;++async function startHost() {+ hostPort ||= await freePort();+ // 0.0.0.0 so step 7 can prove a non-loopback bearer token is refused.+ host = run(HOST_BIN, ["serve", "--bind", "0.0.0.0", "--port", String(hostPort)], { CODYNC_HOME: home, CODYNC_CLOUD_URL: CLOUD });+ await waitFor("host /health", () => fetch(`http://127.0.0.1:${hostPort}/health`).then((r) => r.ok || undefined).catch(() => undefined), 30_000);+}++async function loopback(method: string, body: unknown = {}): Promise<Json> {+ const token = readFileSync(join(home, "token"), "utf8").trim();+ const res = await fetch(`http://127.0.0.1:${hostPort}/api/${method}`, {+ method: "POST",+ headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },+ body: JSON.stringify(body),+ });+ const v = await res.json();+ if (!res.ok) throw new Error(`${method} → ${res.status} ${JSON.stringify(v)}`);+ return v;+}++/** The relay refused the upgrade (the socket never opened). */+const refused = (wire: Wire) => wire.opened.then(+ () => false,+ () => true,+);+- const computerOnline = (id: string) => d1(`SELECT online FROM computers WHERE id = '${id}'`)[0]?.online === 1 || undefined;++const computerOnline = async (id: string) => (await d1(`SELECT online FROM computers WHERE id = '${id}'`))[0]?.online === 1 || undefined;++// ---- scenario ----++async function main() {+ step("1. local D1 + wrangler dev");+ const migrate = spawnSync(WRANGLER, ["d1", "migrations", "apply", "codync-dev", "--local", "--env", "dev", "--persist-to", persist], {+ cwd: CLOUD_DIR,+ encoding: "utf8",+ env: { ...process.env, CI: "1" },+ });+ if (migrate.status !== 0) throw new Error(`migrations failed: ${migrate.stderr}`);+ run(WRANGLER, ["dev", "--env", "dev", "--ip", "127.0.0.1", "--port", String(CLOUD_PORT), "--persist-to", persist, "--var", `CLERK_JWT_KEY:${jwtKey}`]);+ await waitFor("cloud /v1/health", () => fetch(`${CLOUD}/v1/health`).then((r) => r.ok || undefined).catch(() => undefined), 60_000);++ step("2–3. host registers and comes online");+ await startHost();+ const health = await (await fetch(`http://127.0.0.1:${hostPort}/health`)).json();+ const computerId = health.computerId as string;+ check(/^[A-Za-z0-9_-]{22}$/.test(computerId), "host reports a computerId");- await waitFor("computer row", () => d1(`SELECT id FROM computers WHERE id = '${computerId}'`).length > 0 || undefined);++ await waitFor("computer row", async () => (await d1(`SELECT id FROM computers WHERE id = '${computerId}'`)).length > 0 || undefined);+ await waitFor("DO presence online", () => computerOnline(computerId), 20_000);+ check(true, "D1 row exists and the DO marked it online");++ step("4. QR pairing over the relay, then chat");+ const pairing: PairingInfo = parsePairing((await loopback("pairing")).pairingUrl);+ check(pairing.computerId === computerId && pairing.cloud === CLOUD, "pairing link names this computer and cloud");+ const phone = new FakePhone();+ const paired = await phone.pair(pairing);+ check(paired.computerId === computerId, "pair answered, link closed with 4100");+ // 6c: the normal reconnect is not a pairing socket, so it isn't capped at 16 messages.+ let ch = await phone.relay(CLOUD, computerId, pairing.signKey);+ const hello = await ch.call("hello", {});+ check(hello.computerId === computerId && hello.boxKey === ref.b64url(pairing.boxKey), "inner hello returns computerId and boxKey");+ for (let i = 0; i < 20; i++) await ch.call("sync", { since: 0 });+ check(true, "more than 16 messages on the regular link");++ const bot = (await ch.call("createBot", { name: "Tester", backend: "custom", command: `python3 '${FAKE_AGENT}'`, cwd: tmp, permission: "ask" })).bot.id;+ ch.subscribe("events", { since: 0, client: "ios" });+ await ch.call("send", { botId: bot, text: "go", clientNonce: "e2e-1" });+ const card = await waitFor("permission card", () =>+ ch.events.find((e) => e.type === "entry" && e.entry.kind === "permission" && e.entry.data.status === "pending"),+ );+ await ch.call("respondPermission", { entryId: card.entry.id, optionId: "allow" });+ await waitFor("final reply", () => ch.events.find((e) => e.type === "entry" && e.entry.kind === "agent" && e.entry.data.final === true), 20_000);+ check(true, "agent reply arrived through the relay");++ step("5. mailbox while the host is down");+ await stop(host!);+ await ch.wire.next((m) => m.t === "presence" && m.online === false, "presence offline");+ check(true, "device saw presence online:false");+ phone.mailboxPut(ch.wire, pairing, bot, "queued hello", "e2e-mbox-1");+ check((await ch.wire.next((m) => m.t === "mbox.ok", "mbox.ok")).nonce === "e2e-mbox-1", "queued");+ phone.mailboxPut(ch.wire, pairing, bot, "never mind", "e2e-mbox-2");+ await ch.wire.next((m) => m.t === "mbox.ok", "mbox.ok 2");+ ch.wire.send({ t: "mbox.cancel", nonce: "e2e-mbox-2" });+ check((await ch.wire.next((m) => m.t === "mbox.cancelled", "cancelled")).nonce === "e2e-mbox-2", "second one cancelled");+ await startHost();+ const delivered = await ch.wire.next((m) => m.t === "mbox.delivered", "mbox.delivered", 30_000);+ check(delivered.nonce === "e2e-mbox-1", "delivered after the host came back");+ // Every presence online:true means a fresh handshake on the same socket (§7.2).+ ch = await Channel.open(ch.wire, phone.key, pairing.signKey, { relay: true });+ const history = await waitFor("mailbox entry", async () => {+ const h = await ch.call("history", { botId: bot });+ return h.entries.some((e: Json) => e.data?.clientNonce === "e2e-mbox-1") ? h : undefined;+ });+ check(!history.entries.some((e: Json) => e.data?.clientNonce === "e2e-mbox-2"), "the cancelled message never ran");++ step("6. account: claim, access request with SAS, revocation");+ const userId = "user_e2e";+ const token = await clerkToken(userId);+ const claim = await cloud("POST", "/v1/claims", { token });+ const signed = await loopback("claimSign", { claimId: claim.body.claimId, nonce: claim.body.nonce, userId });+ const done = await cloud("POST", `/v1/claims/${claim.body.claimId}/complete`, { token, body: signed });+ check(done.status === 200 && done.body.computer.computerId === computerId, "computer claimed");+ await waitFor("host sees its owner", async () => (await loopback("cloudStatus")).owner?.userId === userId || undefined);++ const phone2 = new FakePhone();+ check((await cloud("POST", "/v1/devices", { token, key: phone2.key, body: { name: "Phone 2", platform: "ios" } })).status === 200, "phone 2 registered");+ const listed = (await cloud("GET", "/v1/computers", { token, key: phone2.key })).body.computers[0];+ check(listed.access === "none", "phone 2 has no access yet");+ const nD = ref.random(32);+ const req = await cloud("POST", `/v1/computers/${computerId}/access-requests`, {+ token,+ key: phone2.key,+ body: { commit: ref.b64url(ref.sasCommit(phone2.key.pub, nD)) },+ });+ const requestId = req.body.requestId as string;+ const hostNonce = await waitFor("host nonce", async () => (await cloud("GET", `/v1/access-requests/${requestId}`, { token })).body.hostNonce);+ check((await cloud("POST", `/v1/access-requests/${requestId}/reveal`, { token, key: phone2.key, body: { nonce: ref.b64url(nD) } })).status === 200, "revealed");+ const sas = ref.sasCode(ref.unb64url(listed.signKey), phone2.key.pub, nD, ref.unb64url(hostNonce));+ const shown = await waitFor("SAS on the computer", async () =>+ (await loopback("accessRequests")).requests.find((r: Json) => r.requestId === requestId && r.code),+ );+ check(shown.code === sas, `the computer shows the phone's SAS (${sas})`);+ await loopback("decideAccessRequest", { requestId, approve: true });+ const approved = await waitFor("approved", async () => {+ const r = (await cloud("GET", `/v1/access-requests/${requestId}`, { token })).body;+ return r.status === "approved" ? r : undefined;+ });+ const ch2 = await phone2.relay(CLOUD, computerId, ref.unb64url(listed.signKey));+ check((await ch2.call("hello", {})).computerId === computerId, "phone 2 connected through the relay");++ const started = Date.now();+ await cloud("DELETE", `/v1/computers/${computerId}/grants/${approved.grantId}`, { token });+ const code = await ch2.wire.closed(5000);+ check(code === 4003 && Date.now() - started < 1000, `revoked socket closed with 4003 within 1 s (${Date.now() - started} ms)`);+ check(await refused(phone2.relayWire(CLOUD, computerId)), "phone 2 can't reconnect");+ await stop(host!);+ await startHost();+ await waitFor("host back online", () => computerOnline(computerId), 20_000);+ check(await refused(phone2.relayWire(CLOUD, computerId)), "still refused after the host reconnects");++ step("6b. a grant injected into D1 is ignored by the host");+ const phone3 = new FakePhone();+ await cloud("POST", "/v1/devices", { token, key: phone3.key, body: { name: "Intruder", platform: "ios" } });+ const r3 = await cloud("POST", `/v1/computers/${computerId}/access-requests`, { token, key: phone3.key, body: { commit: ref.b64url(ref.random(32)) } });- const dev3 = d1(`SELECT id FROM devices WHERE sign_pub = '${phone3.dk}'`)[0].id;- d1(`INSERT INTO grants(id, computer_id, device_id, scopes, status, created_at) VALUES ('grt_injected', '${computerId}', '${dev3}', '["control","screen"]', 'active', ${Date.now()})`);++ const dev3 = (await d1(`SELECT id FROM devices WHERE sign_pub = '${phone3.dk}'`))[0].id;++ await d1(`INSERT INTO grants(id, computer_id, device_id, scopes, status, created_at) VALUES ('grt_injected', '${computerId}', '${dev3}', '["control","screen"]', 'active', ${Date.now()})`);+ await cloud("DELETE", `/v1/access-requests/${r3.body.requestId}`, { token }); // → cloud.changed → state pull+ await new Promise((r) => setTimeout(r, 2000));+ const devices = (await loopback("devices")).devices as Json[];+ check(!devices.some((d) => d.key === phone3.dk), "host's device table doesn't contain the injected key");+ check(await refused(phone3.relayWire(CLOUD, computerId)), "the injected key can't open a relay socket (not in the ACL)");++ step("7. direct /channel and loopback-only bearer token");+ const direct = await phone.direct(`http://127.0.0.1:${hostPort}`, pairing.signKey);+ check((await direct.call("hello", {})).computerId === computerId, "direct handshake and hello");+ const lan = Object.values(networkInterfaces())+ .flat()+ .find((i) => i && i.family === "IPv4" && !i.internal)?.address;+ if (lan) {+ const token = readFileSync(join(home, "token"), "utf8").trim();+ const res = await fetch(`http://${lan}:${hostPort}/api/hello`, { method: "POST", headers: { Authorization: `Bearer ${token}` }, body: "{}" });+ check(res.status === 401, `bearer token from ${lan} → 401`);+ } else {+ console.log(" (skipped: no non-loopback IPv4 interface)");+ }++ console.log("\nE2E passed");+}++async function cleanup() {+ await Promise.all(children.map(stop));+ rmSync(tmp, { recursive: true, force: true });+}++try {+ if (spawnSync(HOST_BIN, ["--version"]).error) {+ throw new Error(`codync-host not found at ${HOST_BIN}; run \`cargo build\` in host/ or set CODYNC_HOST_BIN`);+ }+ await main();+ await cleanup();+} catch (e) {+ console.error(`\nE2E failed: ${e instanceof Error ? e.stack : e}`);+ await cleanup();+ process.exit(1);+}diff --cc docs/clerk-macos.mdindex a4a81cd7,6a45cb40..48525386--- a/docs/clerk-macos.md+++ b/docs/clerk-macos.md@@@ -85,24 -81,16 +85,38 @@@ Verify with two real Google accounts: acheck each account's pairings, sign out just one, and verify the other remains.A simulator build verifies compilation, not the Dashboard settings or OAuth flow.-### Local verification on 2026-09-25+## Mac: computers, approvals and SSH++The Mac keeps one `AccountStore` per account context too (`HostController`). This Mac's+host and SSH computers are attached over loopback and follow into whichever account is+active; the account's other computers are reached over the encrypted channel with the+Mac's own device key. Log out erases the account's keys and caches, as on iPhone.++**Computers & devices** (account menu) shows, for this Mac and each SSH computer:+*Reach from anywhere* (`setCloud`, using the app's `cloudURL` when the host has none),+*Add to account* (claim: `POST /v1/claims` → loopback `claimSign` → complete) and+*Remove from account* (`unclaim`), a pairing QR, and the authorized devices with revoke.+A device asking for access raises the menu bar dot and opens the approval sheet with the+6-digit code; Approve stays disabled until the device revealed its code.++SSH computers use the system OpenSSH (`apps/macos/App/SSHTunnel.swift`): `ssh -G` to+resolve the target, `ssh-keygen -F` against `~/.ssh/known_hosts` and+`~/.codync/ssh_known_hosts`, a fingerprint confirmation on first contact (no proxy),+`codync-host info --json` for the identity and loopback token, then+`ssh -N -L 127.0.0.1:<free port>:127.0.0.1:<remote port>` with keepalive and backoff.+A changed host key or a different computer ID blocks the connection. Debug builds run+`SSH.selfCheck()` at launch (argv, `ssh -G` parsing, validation).++++## Local verification on 2026-09-25++ - iOS Simulator build succeeded with normal simulator signing. Do not use+ `CODE_SIGNING_ALLOWED=NO` for a Clerk runtime smoke test: an unsigned simulator+ installation failed Keychain initialization with OSStatus -34018.+ - The app launches, the top-left Accounts sheet opens, and its Computers & settings+ destination navigates successfully in iPhone 17 Pro / iOS 26.5 Simulator.-- `swift test --package-path kit`: 9 tests passed, including account storage- separation, legacy pairing preservation, and rejecting another account or- computer's old widget link.++- `swift test --package-path kit` passed. Account storage separation and rejecting++ another account's or computer's widget link are now covered by++ `PairingStorageTests` (per-context computers, usage and deep links).+ - Real Google login, two-account switching, and Clerk Dashboard configuration still+ need end-to-end verification with test accounts. No cloud ownership implementation+ or Cloudflare deployment was performed in this change.diff --cc docs/cloudflare-account-device-plan.mdindex 397f305a,ffb1e978..6c1724d7--- a/docs/cloudflare-account-device-plan.md+++ b/docs/cloudflare-account-device-plan.md@@@ -1,16 -1,14 +1,22 @@@# Codync 帳號、裝置管理與 Cloudflare 架構計畫日期:2026-09-25- 狀態:規劃文件;尚未實作或部署。文中的時間、容量與保留期限是建議產品設定,不是服務商限制。+ 狀態:雲端、逐裝置授權與 SSH 為規劃,尚未部署;手機帳號入口與本機資料分區已實作,詳見補充計畫的落地範圍。文中的時間、容量與保留期限是建議產品設定,不是服務商限制。++ ## 執行分工(2026-09-25 更新)++ Cloudflare API、D1、裝置目錄、雲端授權/撤權與中繼由 Claude Code 接續實作。本次 Codex 修改範圍是手機帳號入口、共享 Clerk session wrapper、本機帳號分區與計畫文件;未建立或部署 `cloud/`,也未修改既有 `relay/`。++ 前後端整合時以已驗證的 Clerk user ID 作帳號關聯;不要把目前手機的配對資料分區誤認為已完成後端 ownership。新增 API 後應接到 `CloudClient`/account store,而非重新複製一套登入流程。+> **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 的遠端連線。diff --cc docs/remote-relay-spec.mdindex aff219ef,00000000..cf82e54dmode 100644,000000..100644--- a/docs/remote-relay-spec.md+++ b/docs/remote-relay-spec.md@@@ -1,1134 -1,0 +1,1154 @@@+# 遠端連線實作規格: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) |++| loopback 專用 | `setScreenEnabled`, `pairing`, `computerCall`, `teamCall`, `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 確認)。++---+++## 實作差異(已接受)++++實作與上文不同、經確認保留的行為:++++- **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**:以 `lsof` 確認本機 listener 屬於我們啟動的 `ssh`。++- **取消 access request**:iOS SAS sheet 與 Mac computers 視窗都有取消按鈕(`DELETE /v1/access-requests/{id}`)。+++## 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 --cc docs/structure.mdindex 829ff03d,b0a544f7..2192fd54--- a/docs/structure.md+++ b/docs/structure.md@@@ -1,14 -1,12 +1,16 @@@# 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/```- Remote access ([spec](remote-relay-spec.md)): host `identity.rs` (keys) · `crypto.rs` (wire crypto) · `devices.rs` (authorized devices, `Caller`) · `channel.rs` (E2E channel, direct or relayed) · `relay.rs` (relay socket) · `cloud.rs` (cloud HTTP client, access requests). Kit `Client/`: `RelayCrypto`, `DeviceIdentity`, `Pairing`, `HostTransport`, `ChannelTransport`, `HostConnector`, `CloudClient`; models `Computer`, `Cloud`; `CodyncUI/Store/AccountStore`. Apps: `apps/shared/ComputerStatus.swift`, iOS `AccessRequestView`, Mac `SSHTunnel` + `ComputersView`. Cloud: `cloud/src/{index,auth,api,relay}.ts`.++Remote access ([spec](remote-relay-spec.md)): host `identity.rs` (keys) · `crypto.rs` (wire crypto) · `devices.rs` (authorized devices, `Caller`) · `channel.rs` (E2E channel, direct or relayed) · `relay.rs` (relay socket) · `cloud.rs` (cloud HTTP client, access requests). Kit `Client/`: `RelayCrypto`, `DeviceIdentity`, `Pairing`, `HostTransport`, `ChannelTransport`, `HostConnector`, `CloudClient`; models `Computer`, `Cloud`; `CodyncUI/Store/AccountStore`. Apps: `apps/shared/{AccountSession,ComputerStatus}.swift`, iOS `AccessRequestView` + `AccountSwitcherView` + `NotificationService/` (decrypts pushes), Mac `App/{HostController,SSHTunnel}.swift` + `Views/ComputersView.swift`. Cloud (`cloud/`, Worker + Durable Objects): `src/{index,auth,api,relay}.ts`, `migrations/` (D1), `test/` (vitest; `test/e2e/` against a live host).++++Bot memory & teams ([context-and-memory](context-and-memory.md), [bot-collaboration](bot-collaboration.md)): host `memory.rs`, `context.rs`, `team.rs` (+ `tests/team_e2e.rs`); kit `CodyncUI/Bots/MemoryView.swift`. Widgets ([design](mobile-widgets-design.md)): shared cards in `CodyncKit/Design/WidgetCards.swift`, iOS `Widgets/WidgetPreviews.swift` + `Views/WidgetGalleryView.swift`.+- 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).- Files follow their language: Swift `UpperCamelCase.swift` named after the file's main type; Rust/TS `snake_case.rs` / `kebab-case.ts`.- One main type per file. Small private helpers of that type stay in it; a file of several small siblings takes the plural role (`ChatRows.swift`, `UsageViews.swift`, `Dialogs.swift`).diff --cc host/src/api.rsindex 1cf20ad0,7bc694b2..01e66332--- a/host/src/api.rs+++ b/host/src/api.rs@@@ -164,10 -105,9 +164,11 @@@ fn str_arg<'a>(b: &'a Value, k: &str) -b[k].as_str().ok_or_else(|| anyhow!("`{k}` is required"))}-pub async fn dispatch(hub: &Arc<Hub>, method: &str, b: Value) -> Result<Value> {+/// Runs one API method for `caller` (permissions per spec §6.6).+pub async fn dispatch(hub: &Arc<Hub>, caller: &Caller, method: &str, b: Value) -> Result<Value> {+ crate::devices::permit(caller, method)?;Ok(match method {+ "teamCall" => crate::team::call(hub, str_arg(&b, "botId")?, str_arg(&b, "name")?, &b["arguments"]).await?,"hello" => {let port = hub.port;json!({diff --cc host/src/devices.rsindex 07cab5ae,00000000..9c70a2e9mode 100644,000000..100644--- a/host/src/devices.rs+++ b/host/src/devices.rs@@@ -1,255 -1,0 +1,256 @@@+//! Who is calling and what they may do (spec §4.1, §4.3, §6.6): the caller kinds,+//! per-method permissions, the device authorization check and QR pairing codes.+//! The authorized-device table itself lives in `store`.++use crate::crypto;+use crate::hub::Hub;+use crate::store::{Device, DeviceSource, Scope, now_ms};+use serde::Serialize;+use std::sync::atomic::Ordering;+use std::time::{Duration, Instant};++pub enum Caller {+ /// This computer's own apps and helpers: loopback + the bearer token.+ Local,+ /// An authorized device over an E2E channel.+ Device { key: String, scopes: Vec<Scope> },+ /// A channel opened to redeem a pairing code; may only call `pair`.+ Pairing { key: String },+}++impl Caller {+ /// The key push and Live Activity tickets are bound to.+ pub fn device_key(&self) -> &str {+ match self {+ Self::Local => "local",+ Self::Device { key, .. } | Self::Pairing { key } => key,+ }+ }+}++/// Methods only this computer may call.+const LOCAL_ONLY: &[&str] = &[+ "setScreenEnabled",+ "pairing",+ "computerCall",++ "teamCall",+ "claimSign",+ "unclaim",+ "devices",+ "revokeDevice",+ "accessRequests",+ "decideAccessRequest",+ "cloudStatus",+ "setCloud",+];+const SCREEN: &[&str] = &["screenOffer", "screenClose", "screenTakeover"];++/// A method the caller isn't allowed to call (403).+#[derive(Debug)]+pub struct Forbidden;++impl std::fmt::Display for Forbidden {+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ f.write_str("This can only be done at the computer itself.")+ }+}++impl std::error::Error for Forbidden {}++pub fn permit(caller: &Caller, method: &str) -> Result<(), Forbidden> {+ let ok = match caller {+ Caller::Local => method != "pair",+ Caller::Pairing { .. } => false,+ Caller::Device { scopes, .. } => {+ let needs = if SCREEN.contains(&method) { Scope::Screen } else { Scope::Control };+ !LOCAL_ONLY.contains(&method) && method != "pair" && scopes.contains(&needs)+ }+ };+ if ok { Ok(()) } else { Err(Forbidden) }+}++/// Why a channel refuses a device (`reject.code`).+#[derive(Serialize, Clone, Copy, Debug, PartialEq, Eq)]+#[serde(rename_all = "camelCase")]+pub enum RejectCode {+ Unauthorized,+ Revoked,+ LeaseExpired,+ BadSignature,+ UnsupportedVersion,+ PairingClosed,+ RateLimited,+}++impl RejectCode {+ /// The WebSocket close code sent after the `reject`.+ pub fn close_code(self) -> u16 {+ match self {+ Self::Revoked => 4003,+ Self::RateLimited => 4008,+ Self::UnsupportedVersion => 4400,+ Self::PairingClosed => 4410,+ Self::Unauthorized | Self::LeaseExpired | Self::BadSignature => 4001,+ }+ }++ pub fn message(self) -> &'static str {+ match self {+ Self::Unauthorized => "This device isn't allowed on this computer. Pair it again.",+ Self::Revoked => "This device's access was removed on the computer.",+ Self::LeaseExpired => "The computer can't confirm this device's access right now. Try again shortly.",+ Self::BadSignature => "The device's signature didn't check out.",+ Self::UnsupportedVersion => "Update Codync to connect to this computer.",+ Self::PairingClosed => "Pairing isn't open. Show a new code on the computer.",+ Self::RateLimited => "Too many pairing attempts. Wait a minute and try again.",+ }+ }+}++/// Whether `key` may use a channel right now (§4.3): a local device always, an account+/// device only while its lease runs and the cloud state was applied on this connection.+pub fn authorize(hub: &Hub, key: &str) -> Result<Device, RejectCode> {+ let d = hub.store.device(key).ok_or(RejectCode::Unauthorized)?;+ if d.source == DeviceSource::Account+ && (!hub.cloud_synced.load(Ordering::Acquire) || d.lease_until.is_none_or(|t| t <= now_ms()))+ {+ return Err(RejectCode::LeaseExpired);+ }+ Ok(d)+}++// MARK: pairing codes++const CODE_TTL_MS: i64 = 10 * 60 * 1000;+const MAX_CODES: usize = 5;+const PER_SOURCE_PER_MINUTE: usize = 3;+const TOTAL_PER_MINUTE: usize = 10;++struct PairingCode {+ code: [u8; 16],+ expires_at: i64,+}++/// One-time QR codes (memory only) and the attempt limits that guard them.+#[derive(Default)]+pub struct Pairing {+ codes: Vec<PairingCode>,+ attempts: Vec<(String, Instant)>,+}++/// A code just issued, for the QR.+pub struct Issued {+ pub code: String,+ pub expires_at: i64,+}++impl Pairing {+ fn prune(&mut self, now: i64) {+ self.codes.retain(|c| c.expires_at > now);+ }++ /// A new code; the oldest is dropped beyond five.+ pub fn issue(&mut self) -> Issued {+ let now = now_ms();+ self.prune(now);+ if self.codes.len() >= MAX_CODES {+ self.codes.remove(0);+ }+ let code = crypto::random::<16>();+ let expires_at = now + CODE_TTL_MS;+ self.codes.push(PairingCode { code, expires_at });+ Issued { code: crypto::b64(&code), expires_at }+ }++ /// The live codes as ACL offers: `(offerId, expiresAt)`.+ pub fn offers(&mut self) -> Vec<(String, i64)> {+ self.prune(now_ms());+ self.codes.iter().map(|c| (crypto::offer_id(&c.code), c.expires_at)).collect()+ }++ /// Whether any code is still unused and unexpired.+ pub fn open(&mut self) -> bool {+ self.prune(now_ms());+ !self.codes.is_empty()+ }++ /// Counts a `pair` attempt from `source` (peer IP or relay link); false when over the limit.+ pub fn attempt(&mut self, source: &str) -> bool {+ let now = Instant::now();+ self.attempts.retain(|(_, t)| now.duration_since(*t) < Duration::from_secs(60));+ let from_source = self.attempts.iter().filter(|(s, _)| s == source).count();+ if from_source >= PER_SOURCE_PER_MINUTE || self.attempts.len() >= TOTAL_PER_MINUTE {+ return false;+ }+ self.attempts.push((source.to_owned(), now));+ true+ }++ /// Uses up `code` if it is valid (constant-time over every live code).+ pub fn redeem(&mut self, code: &str) -> bool {+ self.prune(now_ms());+ let Ok(given) = crypto::unb64_n::<16>(code) else { return false };+ let mut found = None;+ for (i, c) in self.codes.iter().enumerate() {+ if crypto::ct_eq(&c.code, &given) {+ found = Some(i);+ }+ }+ found.map(|i| self.codes.remove(i)).is_some()+ }+}++#[cfg(test)]+mod tests {+ #![allow(clippy::unwrap_used)]+ use super::*;++ #[test]+ fn method_permissions_follow_the_caller() {+ let both = Caller::Device { key: "k".into(), scopes: vec![Scope::Control, Scope::Screen] };+ let control = Caller::Device { key: "k".into(), scopes: vec![Scope::Control] };+ for m in LOCAL_ONLY {+ assert!(permit(&Caller::Local, m).is_ok());+ assert!(permit(&both, m).is_err(), "{m} is loopback only");+ }+ assert!(permit(&both, "send").is_ok());+ assert!(permit(&both, "screenOffer").is_ok());+ assert!(permit(&control, "screenOffer").is_err(), "screen needs the screen scope");+ assert!(permit(&control, "screenStatus").is_ok(), "status is control");+ assert!(permit(&Caller::Device { key: "k".into(), scopes: vec![] }, "hello").is_err());+ assert!(permit(&both, "pair").is_err(), "pair only on a pairing channel");+ assert!(permit(&Caller::Pairing { key: "k".into() }, "hello").is_err());+ assert_eq!(both.device_key(), "k");+ assert_eq!(Caller::Local.device_key(), "local");+ }++ #[test]+ fn codes_are_single_use_and_capped() {+ let mut p = Pairing::default();+ assert!(!p.open());+ let first = p.issue();+ assert!(p.open());+ let offer = crypto::offer_id(&crypto::unb64_n(&first.code).unwrap());+ assert_eq!(p.offers(), [(offer, first.expires_at)]);+ assert!(!p.redeem("CAgICAgICAgICAgICAgICA"));+ assert!(p.redeem(&first.code));+ assert!(!p.redeem(&first.code), "single use");+ assert!(!p.open());++ let codes: Vec<Issued> = (0..6).map(|_| p.issue()).collect();+ assert!(!p.redeem(&codes[0].code), "the oldest of six is dropped");+ assert!(p.redeem(&codes[5].code));++ p.codes[0].expires_at = now_ms() - 1;+ assert!(!p.redeem(&codes[1].code), "expired");+ }++ #[test]+ fn attempts_are_limited_per_source_and_in_total() {+ let mut p = Pairing::default();+ assert!((0..3).all(|_| p.attempt("1.2.3.4")));+ assert!(!p.attempt("1.2.3.4"));+ assert!((0..7).all(|i| p.attempt(&format!("link{i}"))));+ assert!(!p.attempt("fresh"), "ten per minute across the host");+ }+}diff --cc host/src/hub.rsindex 04fc9a5e,d5933254..769dbd2a--- a/host/src/hub.rs+++ b/host/src/hub.rs@@@ -36,10 -34,9 +36,11 @@@ pub struct Runtime}pub struct Hub {+ pub team: crate::team::Requests,pub store: Store,pub host_id: String,+ pub identity: Identity,+ /// Loopback-only bearer token for this computer's own apps and helpers.pub token: String,pub port: u16,pub events: broadcast::Sender<Value>,@@@ -70,9 -59,9 +71,10 @@@ impl Hublet (events, _) = broadcast::channel(1024);let screen = Arc::new(Screen::new(Screen::load_enabled(&store), events.clone()));Arc::new(Self {+ team: crate::team::Requests::default(),store,host_id,+ identity,token,port,events,diff --cc host/src/main.rsindex f98188e8,4f0ca933..3d8e4898--- a/host/src/main.rs+++ b/host/src/main.rs@@@ -5,17 -5,13 +5,19 @@@ mod apimod auth;mod backends;mod bot;+mod channel;+mod cloud;+ mod context;+mod crypto;+mod devices;mod hub;+mod identity;mod market;mod mcp;+ mod memory;mod push;mod registry;+mod relay;mod screen;mod service;mod store;@@@ -154,26 -117,15 +157,33 @@@ enum Sub},}+#[derive(Subcommand)]+enum DevicesAction {+ /// Show every allowed device (the default).+ List,+ /// Remove a device's access; it disconnects at once.+ Revoke { key: String },+}++#[derive(Subcommand)]+enum AccessAction {+ /// Show pending requests with the code each device shows (the default).+ List,+ /// Approve a request, by its id or by the 6-digit code shown on the device.+ Approve { request: String },+ /// Deny a request.+ Deny { request: String },+}+#[derive(Subcommand)]enum McpServer {+ /// Discover and ask the user's other bots for help.+ Team {+ #[arg(long)]+ bot: String,+ #[arg(long, default_value_t = service::DEFAULT_PORT)]+ port: u16,+ },/// See and operate this computer's desktop.Computer {#[arg(long)]@@@ -316,10 -248,11 +326,11 @@@ async fn main() -> Result<()>Sub::ResetToken => {let (store, _, _) = open_store()?;rotate_token(&store)?;- println!("Token rotated. Restart the host and pair your phone again.");+ println!("Token rotated. Restart the host so local helpers pick it up.");Ok(())}- Sub::Mcp { server: McpServer::Computer { bot, port } } => mcp::serve(bot, port).await,+ Sub::Mcp { server: McpServer::Computer { bot, port } } => mcp::serve(bot, port, mcp::Server::Computer).await,+ Sub::Mcp { server: McpServer::Team { bot, port } } => mcp::serve(bot, port, mcp::Server::Team).await,Sub::Tui { url, token, port } => {tui::run(url.unwrap_or_else(|| format!("http://127.0.0.1:{port}")), token).await}diff --cc host/src/team.rsindex 00000000,78def9af..b9554808mode 000000,100644..100644--- a/host/src/team.rs+++ b/host/src/team.rs@@@ -1,0 -1,533 +1,554 @@@+ //! Small, host-local bot delegation. The recipient uses its own ACP session;+ //! native subagents remain the harness's responsibility.++ use crate::LockExt;+ use crate::bot::Cmd;+ use crate::hub::{BotStatus, Hub};+ use crate::store::{BotConfig, EntryKind};+ use anyhow::{Result, anyhow, bail};+ use serde::Serialize;+ use serde_json::{Value, json};+ use std::collections::{HashMap, HashSet};+ use std::sync::{Arc, Mutex};+ use std::time::Duration;+ use tokio::sync::{oneshot, watch};++ pub const ASK_TIMEOUT: Duration = Duration::from_secs(600);+ const MAX_MESSAGE_BYTES: usize = 32_000;++ pub const INSTRUCTIONS: &str = "Use list_bots to find the user's other Codync bots. \+ Use ask_bot when the user requests another bot's help or its specialty is useful. \+ Provide a self-contained request: the recipient has its own conversation, working directory, \+ tools and permissions, not your context. It returns its final reply to you. \+ Coordinate file ownership before asking for edits in a shared project. \+ Do not ask a bot that is waiting for you. Native subagents are managed by your own harness; \+ these tools are for collaborating with the user's existing bots.";++ pub fn tools() -> Value {+ json!([+ {+ "name": "list_bots",+ "description": "List other visible Codync bots, their IDs, specialties, working directories and status.",+ "inputSchema": {"type": "object", "properties": {}},+ "annotations": {"readOnlyHint": true},+ },+ {+ "name": "ask_bot",+ "description": "Ask an existing Codync bot to do a bounded task and wait for its final reply (up to 10 minutes, including queue time). It may use tools and modify files under its own permissions. Does not share your conversation or change its working directory. Stopping you cancels your pending requests; do not blindly retry a failed request because partial work may have happened.",+ "inputSchema": {+ "type": "object",+ "properties": {+ "botId": {"type": "string", "description": "Recipient ID from list_bots."},+ "message": {"type": "string", "description": "Task, relevant context, file paths and expected result."},+ },+ "required": ["botId", "message"],+ },+ "annotations": {"readOnlyHint": false, "idempotentHint": false},+ }+ ])+ }++ struct Request {+ from: String,+ to: String,+ cancel: watch::Sender<bool>,+ }++ /// The wait graph includes queued requests, not only running recipients.+ /// Reserving an edge and checking for cycles happen under the same lock.+ #[derive(Default)]+ pub struct Requests(Mutex<RequestState>);++ #[derive(Default)]+ struct RequestState {+ pending: HashMap<String, Request>,+ active: HashSet<String>,+ }++ impl Requests {+ fn begin(&self, id: &str, from: &str, to: &str) -> Result<watch::Receiver<bool>> {+ let mut state = self.0.locked();+ if !state.active.contains(from) {+ bail!("the requesting bot is no longer working");+ }+ let requests = &mut state.pending;+ if from == to {+ bail!("a bot cannot ask itself");+ }+ if requests.len() >= 64 {+ bail!("too many pending bot requests");+ }+ if requests.values().any(|r| r.from == from && r.to == to) {+ bail!("already waiting for this bot");+ }+ let mut pending = vec![to];+ let mut seen = HashSet::new();+ while let Some(bot) = pending.pop() {+ if bot == from {+ bail!("this request would make bots wait for each other; finish the current request first");+ }+ if seen.insert(bot) {+ pending.extend(requests.values().filter(|r| r.from == bot).map(|r| r.to.as_str()));+ }+ }+ let (cancel, rx) = watch::channel(false);+ requests.insert(id.to_owned(), Request { from: from.to_owned(), to: to.to_owned(), cancel });+ Ok(rx)+ }++ pub fn cancel_from(&self, bot: &str) {+ let mut state = self.0.locked();+ state.active.remove(bot);+ for request in state.pending.values().filter(|r| r.from == bot) {+ request.cancel.send_replace(true);+ }+ }++ pub fn start_turn(&self, bot: &str) {+ self.0.locked().active.insert(bot.to_owned());+ }++ pub fn cancel_bot(&self, bot: &str) {+ let mut state = self.0.locked();+ state.active.remove(bot);+ for request in state.pending.values().filter(|r| r.from == bot || r.to == bot) {+ request.cancel.send_replace(true);+ }+ }+ }++ /// Sent through the recipient's normal actor queue, but never merged with user+ /// messages or another request. Only this turn can resolve its reply channel.+ pub struct Ask {+ pub id: String,+ pub entry_id: String,+ pub prompt: String,+ pub reply: oneshot::Sender<Result<String>>,+ }++ #[derive(Clone, Copy, Serialize)]+ #[serde(rename_all = "lowercase")]+ enum Status {+ Completed,+ Failed,+ Cancelled,+ }++ struct Pending {+ hub: Arc<Hub>,+ id: String,+ target: String,+ entries: Vec<String>,+ finished: bool,+ }++ impl Pending {+ fn finish(&mut self, status: Status, detail: &str) {+ for id in &self.entries {+ if let Some(mut e) = self.hub.store.entry(id) {+ e.data["status"] = json!(status);+ let heading = e.data["heading"].as_str().unwrap_or("Bot request");+ e.data["text"] = format!("{heading}\n{detail}").into();+ if !matches!(status, Status::Completed) {+ e.data["style"] = "error".into();+ }+ self.hub.set_entry(id, &e.data);+ }+ }+ self.finished = true;+ }+ }++ impl Drop for Pending {+ fn drop(&mut self) {+ if !self.finished {+ self.finish(Status::Cancelled, "Request cancelled. Partial work may have happened.");+ }+ self.hub.team.0.locked().pending.remove(&self.id);+ // Targeted cancellation never clears unrelated user messages or turns.+ let _ = self.hub.send_cmd(&self.target, Cmd::CancelAsk { id: self.id.clone() });+ }+ }++ fn visible_bot(hub: &Hub, id: &str) -> Result<BotConfig> {+ hub.store+ .bot(id)?+ .filter(|r| !r.deleted && !r.config.hidden)+ .map(|r| r.config)+ .ok_or_else(|| anyhow!("unknown or hidden bot"))+ }++ pub async fn call(hub: &Arc<Hub>, from: &str, name: &str, args: &Value) -> Result<Value> {+ let source = visible_bot(hub, from)?;+ match name {+ "list_bots" => {+ let bots: Vec<Value> = hub+ .store+ .bots()?+ .into_iter()+ .filter(|b| !b.deleted && !b.config.hidden && b.config.id != from)+ .map(|b| {+ json!({+ "id": b.config.id, "name": b.config.name, "description": b.config.description,+ "backend": b.config.backend, "cwd": b.config.cwd,+ "status": hub.runtime(&b.config.id).status,+ })+ })+ .collect();+ Ok(json!({"bots": bots}))+ }+ "ask_bot" => {+ let to = args["botId"].as_str().ok_or_else(|| anyhow!("botId is required"))?;+ let message = args["message"].as_str().unwrap_or_default().trim();+ ask(hub, &source, to, message, ASK_TIMEOUT).await+ }+ _ => bail!("unknown team tool: {name}"),+ }+ }++ async fn ask(hub: &Arc<Hub>, source: &BotConfig, to: &str, message: &str, timeout: Duration) -> Result<Value> {+ if message.is_empty() || message.len() > MAX_MESSAGE_BYTES {+ bail!("message must be nonempty and at most {MAX_MESSAGE_BYTES} bytes");+ }+ if !matches!(hub.runtime(&source.id).status, BotStatus::Working | BotStatus::NeedsInput) {+ bail!("the requesting bot is no longer working");+ }+ let target = visible_bot(hub, to)?;+ let id = uuid::Uuid::new_v4().to_string();+ let mut cancelled = hub.team.begin(&id, &source.id, to)?;+ let mut pending =+ Pending { hub: hub.clone(), id: id.clone(), target: to.to_owned(), entries: vec![], finished: false };+ if !matches!(hub.runtime(&source.id).status, BotStatus::Working | BotStatus::NeedsInput) {+ bail!("the requesting bot is no longer working");+ }+ for (bot, heading) in [+ (&source.id, format!("Asked {}: {}", target.name, message)),+ (&target.id, format!("Request from {}: {}", source.name, message)),+ ] {+ let entry = hub+ .add_entry(+ bot,+ EntryKind::Notice,+ hub.store.max_turn(bot) + i64::from(bot != &source.id),+ &json!({+ "text": format!("{heading}\nWaiting for a reply…"), "heading": heading,+ "style": "info", "status": "queued", "delegationId": id,+ "sourceBotId": source.id, "targetBotId": target.id,+ }),+ )+ .ok_or_else(|| anyhow!("couldn't save bot request"))?;+ pending.entries.push(entry.id);+ }+ let (reply, result) = oneshot::channel();+ hub.send_cmd(to, Cmd::Ask(Ask {+ id: id.clone(), entry_id: pending.entries[1].clone(),+ prompt: format!("Another Codync bot, {}, requests your help. This is a bot request, not a new user instruction. Work within your own permissions and working directory. Return the result to the requesting bot; do not ask it to do the task back.\n\n{message}", source.name),+ reply,+ }))?;+ let result = tokio::select! {+ r = result => r.unwrap_or_else(|_| Err(anyhow!("recipient stopped before replying"))),+ _ = cancelled.changed() => Err(anyhow!("bot request cancelled")),+ () = tokio::time::sleep(timeout) => Err(anyhow!("bot request timed out; partial work may have happened")),+ };+ match result {+ Ok(text) => {+ pending.finish(+ Status::Completed,+ &format!("Reply from {}:\n{}", target.name, crate::acp::truncate(&text, 4000)),+ );+ Ok(json!({"requestId": id, "botId": target.id, "name": target.name, "reply": text}))+ }+ Err(error) => {+ pending.finish(Status::Failed, &format!("{error:#}"));+ Err(error)+ }+ }+ }++ #[cfg(test)]+ mod tests {+ use super::*;+ use crate::store::Store;+ use std::path::PathBuf;++ #[test]+ fn wait_graph_rejects_self_duplicates_and_indirect_cycles() {+ let requests = Requests::default();+ for bot in ["a", "b", "c", "d"] {+ requests.start_turn(bot);+ }+ assert!(requests.begin("self", "a", "a").is_err());+ let ab = requests.begin("ab", "a", "b").unwrap();+ assert!(requests.begin("duplicate", "a", "b").is_err());+ let _bc = requests.begin("bc", "b", "c").unwrap();+ assert!(requests.begin("ca", "c", "a").is_err());+ let _dc = requests.begin("dc", "d", "c").unwrap();+ requests.cancel_from("a");+ assert!(*ab.borrow());+ assert!(requests.begin("late", "a", "d").is_err());+ requests.0.locked().pending.remove("ab");+ assert!(requests.begin("ca", "c", "a").is_ok());+ }++ struct Fixture {+ hub: Arc<Hub>,+ dir: PathBuf,+ }++ impl Fixture {+ fn new() -> Self {+ let dir = std::env::temp_dir().join(format!("codync-team-{}", uuid::Uuid::new_v4()));+ std::fs::create_dir_all(&dir).unwrap();+ let store = Store::open(&dir.join("test.db")).unwrap();+ let agent = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/team_agent.py");+ for id in ["a", "b", "c"] {+ let cwd = dir.join(id);+ std::fs::create_dir_all(&cwd).unwrap();+ let cfg: BotConfig = serde_json::from_value(json!({+ "id": id, "name": id, "backend": "fixture", "cwd": cwd,+ "command": format!("python3 -u '{}'", agent.display().to_string().replace('\'', "'\\''")),+ "notify": false,+ }))+ .unwrap();+ store.save_bot(&cfg).unwrap();+ }- let hub = Hub::new(store, "test-host".into(), "test-token".into(), 19222);++ let hub = Hub::new(++ store,++ "test-host".into(),++ crate::identity::Identity::load_or_create(&dir).unwrap(),++ "test-token".into(),++ 19222,++ );+ hub.start().unwrap();+ hub.set_runtime("a", |r| r.status = BotStatus::Working);+ hub.team.start_turn("a");+ Self { hub, dir }+ }++ fn request(&self, message: &str) -> tokio::task::JoinHandle<Result<Value>> {+ let hub = self.hub.clone();+ let message = message.to_owned();+ tokio::spawn(async move {+ crate::api::dispatch(+ &hub,++ &crate::devices::Caller::Local,+ "teamCall",+ json!({+ "botId": "a", "name": "ask_bot", "arguments": {"botId": "b", "message": message},+ }),+ )+ .await+ })+ }++ async fn until(&self, condition: impl Fn() -> bool) {+ tokio::time::timeout(Duration::from_secs(5), async {+ while !condition() {+ tokio::time::sleep(Duration::from_millis(10)).await;+ }+ })+ .await+ .expect("fixture condition timed out");+ }++ fn prompts(&self) -> Vec<String> {+ std::fs::read_to_string(self.dir.join("b/prompts.jsonl"))+ .unwrap_or_default()+ .lines()+ .map(|l| serde_json::from_str(l).unwrap())+ .collect()+ }++ async fn shutdown(self) {+ self.hub.shutdown().await;+ std::fs::remove_dir_all(self.dir).unwrap();+ }+ }++ #[tokio::test]+ async fn delegation_roundtrip_keeps_queued_user_messages_separate() {+ let f = Fixture::new();+ let request = f.request("BLOCK review these changes");+ f.until(|| f.prompts().len() == 1).await;- let sent = crate::api::dispatch(&f.hub, "send", json!({"botId": "b", "text": "thanks"})).await.unwrap();++ let sent = crate::api::dispatch(++ &f.hub,++ &crate::devices::Caller::Local,++ "send",++ json!({"botId": "b", "text": "thanks"}),++ )++ .await++ .unwrap();+ let request_entry = f+ .hub+ .store+ .history("b", i64::MAX, 100)+ .unwrap()+ .into_iter()+ .find(|e| e.data["delegationId"].is_string())+ .unwrap();+ assert!(request_entry.data["text"].as_str().unwrap().contains("Request from a"));+ assert!(f.hub.store.kv_get("turn.inflight.b").is_none_or(|v| v.is_empty()));+ std::fs::write(f.dir.join("b/release"), "").unwrap();+ let result = request.await.unwrap().unwrap();+ assert_eq!(result["reply"], "reply: BLOCK review these changes");+ f.until(|| f.prompts().len() == 2 && f.hub.runtime("b").status == BotStatus::Idle).await;+ assert_eq!(f.prompts()[1], "thanks");+ assert_eq!(f.hub.store.entry(sent["entry"]["id"].as_str().unwrap()).unwrap().data["status"], "sent");+ assert_eq!(f.hub.store.entry(&request_entry.id).unwrap().data["status"], "completed");+ assert!(f.hub.team.0.locked().pending.is_empty());+ let servers: Value = serde_json::from_slice(&std::fs::read(f.dir.join("b/servers.json")).unwrap()).unwrap();+ assert!(servers.as_array().unwrap().iter().any(|s| s["name"] == "team"));+ f.shutdown().await;+ }++ #[tokio::test]+ async fn permission_cards_still_require_the_recipients_approval() {+ let f = Fixture::new();+ let request = f.request("PERMISSION inspect the project");+ f.until(|| f.hub.runtime("b").status == BotStatus::NeedsInput).await;+ assert!(!request.is_finished());+ let cycle = call(&f.hub, "b", "ask_bot", &json!({"botId": "a", "message": "help me back"})).await;+ assert!(cycle.unwrap_err().to_string().contains("wait for each other"));+ let card =+ f.hub.store.history("b", i64::MAX, 100).unwrap().into_iter().find(|e| e.kind == "permission").unwrap();- crate::api::dispatch(&f.hub, "respondPermission", json!({"entryId": card.id, "optionId": "allow"}))- .await- .unwrap();++ crate::api::dispatch(++ &f.hub,++ &crate::devices::Caller::Local,++ "respondPermission",++ json!({"entryId": card.id, "optionId": "allow"}),++ )++ .await++ .unwrap();+ assert!(request.await.unwrap().is_ok());+ f.shutdown().await;+ }++ #[tokio::test]+ async fn stopping_requester_cancels_only_its_delegation() {+ let f = Fixture::new();+ let request = f.request("BLOCK waiting for cancellation");+ f.until(|| f.prompts().len() == 1).await;- crate::api::dispatch(&f.hub, "send", json!({"botId": "b", "text": "thanks"})).await.unwrap();++ crate::api::dispatch(&f.hub, &crate::devices::Caller::Local, "send", json!({"botId": "b", "text": "thanks"}))++ .await++ .unwrap();+ f.hub.send_cmd("a", Cmd::Stop).unwrap();+ assert!(request.await.unwrap().unwrap_err().to_string().contains("cancelled"));+ f.until(|| f.prompts().len() == 2 && f.hub.runtime("b").status == BotStatus::Idle).await;+ assert_eq!(f.prompts()[1], "thanks");+ assert!(f.hub.team.0.locked().pending.is_empty());+ f.shutdown().await;+ }++ #[tokio::test]+ async fn timeout_and_recipient_errors_release_waiters() {+ let f = Fixture::new();+ for message in ["FAIL requested failure", "EMPTY no text"] {+ assert!(f.request(message).await.unwrap().is_err());+ assert!(f.hub.team.0.locked().pending.is_empty());+ }+ let source = visible_bot(&f.hub, "a").unwrap();+ let error = ask(&f.hub, &source, "b", "BLOCK timed request", Duration::from_millis(100)).await.unwrap_err();+ assert!(error.to_string().contains("timed out"));+ f.until(|| f.hub.runtime("b").status == BotStatus::Idle).await;+ assert!(f.hub.team.0.locked().pending.is_empty());+ assert!(f.request("after timeout").await.unwrap().is_ok());+ f.shutdown().await;+ }++ #[tokio::test]+ async fn invalid_hidden_and_deleted_targets_never_start() {+ let f = Fixture::new();+ let mut hidden = visible_bot(&f.hub, "c").unwrap();+ hidden.hidden = true;+ f.hub.store.save_bot(&hidden).unwrap();+ let list = call(&f.hub, "a", "list_bots", &json!({})).await.unwrap();+ assert_eq!(list["bots"].as_array().unwrap().len(), 1);+ assert_eq!(list["bots"][0]["id"], "b");+ for target in ["a", "c", "missing"] {+ assert!(call(&f.hub, "a", "ask_bot", &json!({"botId": target, "message": "do work"})).await.is_err());+ }+ assert!(f.request(" ").await.unwrap().is_err());+ f.hub.delete_bot("b").unwrap();+ assert!(f.request("deleted").await.unwrap().is_err());+ assert!(f.prompts().is_empty());+ f.shutdown().await;+ }++ #[tokio::test]+ async fn queued_requests_are_not_merged_and_cancelled_requests_never_execute() {+ let f = Fixture::new();+ f.hub.set_runtime("c", |r| r.status = BotStatus::Working);+ f.hub.team.start_turn("c");+ let first = f.request("BLOCK first request");+ f.until(|| f.prompts().len() == 1).await;+ let hub = f.hub.clone();+ let second = tokio::spawn(async move {+ call(&hub, "c", "ask_bot", &json!({"botId": "b", "message": "second request"})).await+ });+ f.until(|| f.hub.team.0.locked().pending.len() == 2).await;+ assert_eq!(f.prompts().len(), 1);+ std::fs::write(f.dir.join("b/release"), "").unwrap();+ assert_eq!(first.await.unwrap().unwrap()["reply"], "reply: BLOCK first request");+ assert_eq!(second.await.unwrap().unwrap()["reply"], "reply: second request");+ assert_eq!(f.prompts().len(), 2);++ std::fs::remove_file(f.dir.join("b/release")).unwrap();+ let third = f.request("BLOCK third request");+ f.until(|| f.prompts().len() == 3).await;+ let source = visible_bot(&f.hub, "c").unwrap();+ let error = ask(&f.hub, &source, "b", "must never run", Duration::from_millis(30)).await.unwrap_err();+ assert!(error.to_string().contains("timed out"));+ std::fs::write(f.dir.join("b/release"), "").unwrap();+ assert!(third.await.unwrap().is_ok());+ f.until(|| f.hub.runtime("b").status == BotStatus::Idle).await;+ assert_eq!(f.prompts().len(), 3);+ f.shutdown().await;+ }++ #[tokio::test]+ async fn recipient_startup_failure_and_deletion_finish_the_request() {+ let f = Fixture::new();+ f.hub.update_bot(&json!({"id": "b", "command": "/codync-nonexistent-test-agent"})).unwrap();+ assert!(f.request("start failure").await.unwrap().unwrap_err().to_string().contains("couldn't start"));+ assert!(f.hub.team.0.locked().pending.is_empty());+ let agent = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/team_agent.py");+ f.hub.update_bot(&json!({"id": "b", "command": format!("python3 -u '{}'", agent.display())})).unwrap();+ let request = f.request("BLOCK delete while working");+ f.until(|| f.prompts().len() == 1).await;+ f.hub.delete_bot("b").unwrap();+ assert!(request.await.unwrap().is_err());+ assert!(f.hub.team.0.locked().pending.is_empty());+ f.shutdown().await;+ }++ #[test]+ fn restart_marks_requests_interrupted_without_replaying_them() {+ let store = Store::open(std::path::Path::new(":memory:")).unwrap();+ let pending = store+ .insert_entry(+ "b",+ EntryKind::Notice,+ 1,+ &json!({+ "delegationId": "d", "status": "sent", "heading": "Request from a",+ }),+ )+ .unwrap();+ let complete = store+ .insert_entry(+ "a",+ EntryKind::Notice,+ 1,+ &json!({+ "delegationId": "done", "status": "completed",+ }),+ )+ .unwrap();+ store.expire_pending().unwrap();+ let interrupted = store.entry(&pending.id).unwrap();+ assert_eq!(interrupted.data["status"], "failed");+ assert!(interrupted.data["text"].as_str().unwrap().contains("Interrupted by host restart"));+ assert_eq!(store.entry(&complete.id).unwrap().data["status"], "completed");+ assert!(interrupted.rev > pending.rev);+ }+ }diff --cc kit/Sources/CodyncUI/Store/AccountStore.swiftindex 60d6f210,00000000..80760c1fmode 100644,000000..100644--- a/kit/Sources/CodyncUI/Store/AccountStore.swift+++ b/kit/Sources/CodyncUI/Store/AccountStore.swift@@@ -1,259 -1,0 +1,281 @@@+import CodyncKit+import Foundation+import Observation++/// One bot across an account context's computers, for lists that mix them.+public struct RosterItem: Identifiable, Sendable {+ public var ref: BotReference+ public var bot: Bot+ public var computer: Computer+ public var id: BotReference { ref }+}++/// Account → computers → bots: one `BotStore` per computer this context can reach+/// (QR-paired, approved through the account, or attached over loopback / SSH on the Mac),+/// plus the account's computers from the cloud that this device can still ask access to.+@MainActor+@Observable+public final class AccountStore {+ public let storage: SharedStore.Context+ public var accountId: String? { storage.accountID }+ /// Attached (loopback) computers first, then the saved ones.+ public private(set) var computers: [Computer] = []+ public private(set) var stores: [ComputerID: BotStore] = [:]+ /// Everything in the account, including computers this device isn't authorized on yet.+ public private(set) var cloudComputers: [CloudComputer] = []+ /// Access requests waiting for approval on the computer, with the SAS to show.+ public private(set) var pendingAccess: [ComputerID: AccessTicket] = [:]+ public var lastError: String?+ public var selection: BotReference? {+ didSet { if let id = selection?.computerId, !retired { storage.lastComputerId = id } }+ }++ public var onBotUpdated: (@MainActor (BotReference, Bot) -> Void)?+ public var onConnected: (@MainActor (BotStore) -> Void)?+ public var onSent: (@MainActor (BotReference, Bot) -> Void)?++ /// The combined roster changed: a bot came, changed or went, or a computer did.++ public var onRosterChanged: (@MainActor ([RosterItem]) -> Void)?++ private let clientKind: String+ private let cloud: CloudClient?+ private let makeStore: @MainActor (Computer, BotStore.Route) -> BotStore+ /// Persisted in the context (channel route).+ private var saved: [Computer]+ /// This session only: the Mac's own host and SSH tunnels.+ private var attached: [Computer] = []+ private var accessPolls: [ComputerID: Task<Void, Never>] = [:]+ private var isActive = true+ private var retired = false++ public convenience init(storage: SharedStore.Context, clientKind: String, cloud: CloudClient?) {+ self.init(storage: storage, clientKind: clientKind, cloud: cloud) { computer, route in+ BotStore(computer: computer, route: route, clientKind: clientKind, storage: storage)+ }+ }++ init(storage: SharedStore.Context, clientKind: String, cloud: CloudClient?,+ makeStore: @escaping @MainActor (Computer, BotStore.Route) -> BotStore) {+ self.storage = storage+ self.clientKind = clientKind+ self.cloud = cloud+ self.makeStore = makeStore+ saved = storage.computers.filter(\.isConsistent)+ for computer in saved { open(computer, route: .channel) }+ refreshList()+ }++ // MARK: derived++ /// Every computer's visible bots, pinned first, then most recent activity.+ public var roster: [RosterItem] {+ computers.flatMap { computer -> [RosterItem] in+ guard let store = stores[computer.id] else { return [] }+ return store.roster.map {+ RosterItem(ref: BotReference(accountId: accountId, computerId: computer.id, botId: $0.id), bot: $0, computer: store.computer)+ }+ }+ .sorted {+ if $0.bot.pinned != $1.bot.pinned { return $0.bot.pinned }+ return $0.bot.lastAt > $1.bot.lastAt+ }+ }++ public func store(for id: ComputerID) -> BotStore? { stores[id] }++ // MARK: computers++ /// QR pairing (§4.1); the computer is saved in this context and connected.+ public func pair(_ pairing: Pairing, deviceName: String, platform: String) async throws -> Computer {+ let identity = try DeviceIdentity.load(context: storage)+ var computer = try await HostConnector.pair(pairing, identity: identity, deviceName: deviceName, platform: platform)+ guard !retired else { throw CancellationError() }+ computer.color = saved.first { $0.id == computer.id }?.color+ save(computer)+ if !attached.contains(where: { $0.id == computer.id }) { open(computer, route: .channel) }+ return computer+ }++ /// The Mac's own host or an SSH tunnel: not saved, it lasts until `detach`.+ public func attach(_ computer: Computer, route: BotStore.Route) {+ guard !retired else { return }+ attached.removeAll { $0.id == computer.id }+ attached.append(computer)+ open(computer, route: route)+ refreshList()+ }++ /// Ends an attachment; a saved computer with the same ID goes back to the channel.+ public func detach(_ id: ComputerID) {+ attached.removeAll { $0.id == id }+ close(id)+ if let computer = saved.first(where: { $0.id == id }), !retired { open(computer, route: .channel) }+ refreshList()+ }++ public func forget(_ id: ComputerID) {+ attached.removeAll { $0.id == id }+ saved.removeAll { $0.id == id }+ persist()+ close(id)+ accessPolls.removeValue(forKey: id)?.cancel()+ pendingAccess[id] = nil+ if selection?.computerId == id { selection = nil }+ refreshList()+ }++ public func setColor(_ id: ComputerID, _ color: String) {+ if let i = saved.firstIndex(where: { $0.id == id }) {+ saved[i].color = color+ persist()+ }+ if let i = attached.firstIndex(where: { $0.id == id }) { attached[i].color = color }+ stores[id]?.updateComputer { $0.color = color }+ refreshList()+ }++ // MARK: account (§4.2 B)++ public func refreshCloud() async {+ guard let cloud, !retired else { return }+ do {+ let list = try await cloud.computers()+ guard !retired else { return }+ cloudComputers = list+ } catch {+ lastError = error.localizedDescription+ }+ }++ /// Starts an access request; the returned `code` must match the one the computer shows.+ /// Approval is then picked up in the background and the computer joins `stores`.+ public func requestAccess(_ id: ComputerID) async throws -> AccessTicket {+ guard let cloud, let target = cloudComputers.first(where: { $0.computerId == id }) else {+ throw CloudError(status: 404, code: "notFound", message: "That computer isn't in your account.")+ }+ let ticket = try await cloud.requestAccess(id, signKey: target.signKey)+ guard !retired else { throw CancellationError() }+ pendingAccess[id] = ticket+ accessPolls[id]?.cancel()+ accessPolls[id] = Task { [weak self] in await self?.awaitApproval(ticket, target: target, cloud: cloud) }+ return ticket+ }+++ /// Withdraws a pending access request; the computer drops it from its approval list.++ public func cancelAccess(_ id: ComputerID) async {++ guard let ticket = pendingAccess[id] else { return }++ accessPolls.removeValue(forKey: id)?.cancel()++ pendingAccess[id] = nil++ do {++ try await cloud?.cancelAccess(ticket.requestId)++ } catch {++ lastError = error.localizedDescription++ }++ }+++ private func awaitApproval(_ ticket: AccessTicket, target: CloudComputer, cloud: CloudClient) async {+ while !Task.isCancelled, !retired {+ try? await Task.sleep(for: .seconds(2))+ guard !Task.isCancelled, !retired else { return }+ guard let status = try? await cloud.accessStatus(ticket.requestId) else { continue }+ guard !retired, pendingAccess[ticket.computerId]?.requestId == ticket.requestId else { return }+ switch status.status {+ case .pending:+ continue+ case .approved:+ pendingAccess[ticket.computerId] = nil+ // Pin the key the SAS was computed with; the first hello brings its mailbox key and addresses.+ let computer = Computer(id: ticket.computerId, name: target.name, signKey: ticket.signKey,+ cloud: cloud.baseURL, device: target.device)+ save(computer)+ if !attached.contains(where: { $0.id == computer.id }) { open(computer, route: .channel) }+ await refreshCloud()+ return+ case .denied, .expired, .cancelled:+ pendingAccess[ticket.computerId] = nil+ lastError = status.status == .denied ? "\(target.name) declined the request." : "The request expired. Ask again."+ return+ }+ }+ }++ // MARK: lifecycle++ public func setActive(_ active: Bool) {+ guard !retired else { return }+ isActive = active+ for store in stores.values { store.setActive(active) }+ }++ /// Account switched or signed out: nothing from here writes into storage or calls back anymore.+ public func retire() {+ retired = true+ for store in stores.values { store.retire() }+ for poll in accessPolls.values { poll.cancel() }+ accessPolls = [:]+ onBotUpdated = nil+ onConnected = nil+ onSent = nil++ onRosterChanged = nil+ selection = nil+ }++ // MARK: plumbing++ private func open(_ computer: Computer, route: BotStore.Route) {+ close(computer.id)+ let store = makeStore(computer, route)+ let id = computer.id+ store.onBotUpdated = { [weak self] bot in+ guard let self, !self.retired else { return }+ self.onBotUpdated?(BotReference(accountId: self.accountId, computerId: id, botId: bot.id), bot)+ }+ store.onSent = { [weak self] bot in+ guard let self, !self.retired else { return }+ self.onSent?(BotReference(accountId: self.accountId, computerId: id, botId: bot.id), bot)+ }+ store.onConnected = { [weak self] store in+ guard let self, !self.retired else { return }+ self.onConnected?(store)+ }+ store.onComputerChanged = { [weak self] computer in self?.computerChanged(computer) }++ store.onRosterChanged = { [weak self] in self?.rosterChanged() }+ stores[id] = store+ if isActive { store.setActive(true) }+ }++ private func close(_ id: ComputerID) {+ stores.removeValue(forKey: id)?.retire()+ }++ private func computerChanged(_ computer: Computer) {+ guard !retired else { return }+ if let i = saved.firstIndex(where: { $0.id == computer.id }), stores[computer.id]?.route == .channel {+ saved[i] = computer+ persist()+ }+ if let i = attached.firstIndex(where: { $0.id == computer.id }) { attached[i] = computer }+ refreshList()+ }++ private func save(_ computer: Computer) {+ saved.removeAll { $0.id == computer.id }+ saved.insert(computer, at: 0)+ persist()+ refreshList()+ }++ private func persist() {+ guard !retired else { return }+ storage.computers = saved+ }++ private func refreshList() {+ computers = attached + saved.filter { c in !attached.contains { $0.id == c.id } }++ rosterChanged()++ }++++ private func rosterChanged() {++ guard !retired else { return }++ onRosterChanged?(roster)+ }+}diff --cc kit/Sources/CodyncUI/Store/BotStore.swiftindex 1e272095,8a5e6cbc..8f810e44--- a/kit/Sources/CodyncUI/Store/BotStore.swift+++ b/kit/Sources/CodyncUI/Store/BotStore.swift@@@ -69,13 -51,11 +69,15 @@@ public final class BotStorepublic var screenRequest: ScreenRequest?// Platform hooks (push registration, Live Activities, widgets).- public var onPaired: (@MainActor (BotStore) -> Void)?+ /// Each time the channel (or loopback) becomes ready.+ public var onConnected: (@MainActor (BotStore) -> Void)?public var onBotUpdated: (@MainActor (Bot) -> Void)?- public var onRosterChanged: (@MainActor ([Bot]) -> Void)?- public var onUsageChanged: (@MainActor (Usage) -> Void)?+ public var onUsageChanged: (@MainActor (ComputerID, Usage) -> Void)?public var onSent: (@MainActor (Bot) -> Void)?++ /// A bot appeared, changed or went away.++ var onRosterChanged: (@MainActor () -> Void)?+ /// The computer's addresses or keys changed (merged from its `hello`); persist it.+ var onComputerChanged: (@MainActor (Computer) -> Void)?/// `ios` clients suppress pushes while connected; others don't.private let clientKind: String@@@ -158,7 -164,10 +160,9 @@@private func resetMirror() {bots = [:]- entries = [:]+ entries = entries.mapValues { $0.filter { $0.id.hasPrefix("local-") } }.filter { !$0.value.isEmpty }+ selection = nil- setUsage(Usage())- onRosterChanged?([])++ onRosterChanged?()rev = 0hostId = nilhistoryComplete = []@@@ -174,11 -183,11 +178,12 @@@setActive(false)retired = truesaveTask?.cancel()- onPaired = nil+ onConnected = nilonBotUpdated = nil- onRosterChanged = nilonUsageChanged = nilonSent = nil++ onRosterChanged = nil+ onComputerChanged = nilclient = nilselection = nilscreenRequest = nil@@@ -373,10 -286,13 +378,13 @@@bots[bot.id] = botbump(bot.rev)onBotUpdated?(bot)- onRosterChanged?(roster)++ onRosterChanged?()case let .botDeleted(id, r):bots[id] = nilentries[id] = nilbump(r)+ if selection == id { selection = nil }- onRosterChanged?(roster)++ onRosterChanged?()case let .entry(e):upsert(e)bump(e.rev)@@@ -674,8 -498,11 +682,8 @@@}public func refreshUsage() async {- guard let client else { return }- if let u = try? await client.usage(refresh: true) { setUsage(u) }- guard !retired, let client, let token = pairing?.token else { return }- if let u = try? await client.usage(refresh: true),- !retired, !Task.isCancelled, pairing?.token == token {- setUsage(u)- }++ guard !retired, let client else { return }++ if let u = try? await client.usage(refresh: true), !Task.isCancelled { setUsage(u) }}public func loadOlder(_ botId: String) async {