feat(ios): 中继通道 P4/P5——端点抽象、信封、传输、配对与分层错误
- InstanceEndpoint 取代 Instance.origin（旧数据 init(from:) 读成 .direct， 写盘只输出 endpoint；dedupKey 直通用 origin、中继用 relay:<nodeID>） - RelayWire：Swift 侧重算 contracts/test-vectors.json（CanonicalJSON 手写解析器， 因为 Foundation 的解码器会抹掉'拼写'，而 intent 摘要定义的正是拼写） - NodeTransport 抽象 + DirectTransport / RelayTransport / NodeTransportRouter； DirectTransport 是薄适配，直通路径行为不变 - RelayTransport：信封构造、签名、加密、验签、解密；响应验签失败即丢弃， 四类以上失败各有独立 UpstreamError 分支与用户文案 - DeviceIdentity（沙盒文件 0600，配对时由节点分配 deviceID）、RelayPairing、配对 sheet - 卡片通道徽标 + freshness 副标题；危险写 intent 在发送瞬间生成 - scripts/export-app-routes.swift 生成 vendored 路由表，AppRoutesContractTests 反向守卫 - 测试 78→92：向量互算、迁移（字面量旧 JSON）、配对四类失败、路由器、 传输往返与各类拒绝路径
This commit is contained in:
chick
@@ -1,18 +1,19 @@
|
||||
import Foundation
|
||||
|
||||
public struct DeviceService: Sendable {
|
||||
private let client: any SimAdminClientProtocol
|
||||
private let sessions: InstanceSessionStore
|
||||
private let credentials: (any CredentialStore)?
|
||||
private let transport: any NodeTransport
|
||||
|
||||
public init(transport: any NodeTransport) {
|
||||
self.transport = transport
|
||||
}
|
||||
|
||||
/// Direct-mode construction, kept for the existing call sites and tests.
|
||||
public init(
|
||||
client: any SimAdminClientProtocol,
|
||||
sessions: InstanceSessionStore,
|
||||
credentials: (any CredentialStore)? = nil
|
||||
) {
|
||||
self.client = client
|
||||
self.sessions = sessions
|
||||
self.credentials = credentials
|
||||
self.init(transport: DirectTransport(client: client, sessions: sessions, credentials: credentials))
|
||||
}
|
||||
|
||||
public func snapshot(_ instance: Instance) async throws -> DeviceSnapshot {
|
||||
@@ -76,30 +77,7 @@ public struct DeviceService: Sendable {
|
||||
}
|
||||
|
||||
private func request(_ route: UpstreamRoute, _ instance: Instance) async throws -> UpstreamResponse {
|
||||
var cookie = await sessions.cookie(for: instance.id, origin: instance.origin)
|
||||
do {
|
||||
return try await client.send(route, baseURL: instance.origin, cookie: cookie)
|
||||
} catch UpstreamError.unauthorized, UpstreamError.forbidden {
|
||||
cookie = try await login(instance)
|
||||
return try await client.send(route, baseURL: instance.origin, cookie: cookie)
|
||||
}
|
||||
}
|
||||
|
||||
private func login(_ instance: Instance) async throws -> String {
|
||||
guard let credentials,
|
||||
let password = try credentials.get(instanceID: instance.id),
|
||||
!password.isEmpty
|
||||
else {
|
||||
throw DeviceServiceError.unauthorized
|
||||
}
|
||||
let sessionService = InstanceSessionService(store: sessions, client: client)
|
||||
let result = try await sessionService.login(instance, password: password)
|
||||
guard result.authenticated,
|
||||
let cookie = await sessionService.cookie(for: instance)
|
||||
else {
|
||||
throw DeviceServiceError.unauthorized
|
||||
}
|
||||
return cookie
|
||||
try await transport.send(route, instanceID: instance.id, endpoint: instance.endpoint)
|
||||
}
|
||||
|
||||
static func dataObject(_ data: Data) throws -> [String: Any] {
|
||||
|
||||
@@ -22,8 +22,10 @@ final class DeviceViewModel: ObservableObject {
|
||||
errorMessage = nil
|
||||
do {
|
||||
snapshot = try await service.snapshot(instance)
|
||||
} catch DeviceServiceError.unauthorized {
|
||||
} catch DeviceServiceError.unauthorized, UpstreamError.unauthorized {
|
||||
errorMessage = "需要实例密码登录后才能读取设备数据。"
|
||||
} catch let error as UpstreamError {
|
||||
errorMessage = ErrorMessage.describe(error, nodeName: instance.name)
|
||||
} catch {
|
||||
errorMessage = "节点无响应，请确认地址可访问、设备已开机且端口未被拦截。"
|
||||
}
|
||||
|
||||
@@ -93,9 +93,9 @@ struct InstanceDetailView: View {
|
||||
AICard {
|
||||
VStack(alignment: .leading, spacing: 12) {
|
||||
AISectionTitle("本机保存的配置", systemImage: "slider.horizontal.3")
|
||||
AIKeyValueRow("地址", value: model.instance.origin.absoluteString, monospaced: true)
|
||||
AIKeyValueRow("地址", value: model.instance.endpoint.displayAddress, monospaced: true)
|
||||
AIKeyValueRow("标签", value: model.instance.tags.isEmpty ? "无" : model.instance.tags.joined(separator: "、"))
|
||||
AIKeyValueRow("访问凭据", value: model.instance.credentialConfigured ? "已保存" : "未设置")
|
||||
AIKeyValueRow("访问凭据", value: model.instance.credentialConfigured ? model.instance.endpoint.credentialDescription : "未设置")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -112,7 +112,7 @@ struct InstanceDetailView: View {
|
||||
.font(.system(size: 13, weight: .semibold))
|
||||
.foregroundStyle(AITheme.muted)
|
||||
.accessibilityHidden(true)
|
||||
Text(model.instance.origin.absoluteString)
|
||||
Text(model.instance.endpoint.displayAddress)
|
||||
.font(.footnote.weight(.medium))
|
||||
.monospacedDigit()
|
||||
.foregroundStyle(AITheme.ink)
|
||||
|
||||
@@ -5,6 +5,8 @@ struct FleetView: View {
|
||||
@State private var showsDeleteDialog = false
|
||||
@State private var editingInstance: Instance?
|
||||
@State private var isSummaryCollapsed = true
|
||||
@State private var showingPairing = false
|
||||
@StateObject private var pairingModel: RelayPairingViewModel
|
||||
init(model: FleetViewModel? = nil) {
|
||||
// StateObject 的 wrappedValue 是 autoclosure，在 init 里改它会写到另一个实例上，
|
||||
// 所以调试开关必须先落到这个具体的 model 对象。
|
||||
@@ -32,6 +34,11 @@ struct FleetView: View {
|
||||
}
|
||||
#endif
|
||||
_model = StateObject(wrappedValue: target)
|
||||
// 配对视图模型与列表共用同一个仓库，否则配对成功后列表看不到新节点。
|
||||
_pairingModel = StateObject(wrappedValue: RelayPairingViewModel(
|
||||
repository: DefaultContainer.makeInstanceRepository(),
|
||||
identities: DefaultContainer.deviceIdentities
|
||||
))
|
||||
}
|
||||
|
||||
var body: some View {
|
||||
@@ -134,6 +141,11 @@ struct FleetView: View {
|
||||
}
|
||||
.disabled(model.visibleRows.isEmpty)
|
||||
|
||||
AIIconButton("配对中继节点", systemImage: "link.badge.plus") {
|
||||
showingPairing = true
|
||||
}
|
||||
.disabled(model.isLoading)
|
||||
|
||||
AIIconButton("添加实例", systemImage: "plus") {
|
||||
model.showingForm = true
|
||||
}
|
||||
@@ -150,6 +162,9 @@ struct FleetView: View {
|
||||
instance: editingInstance
|
||||
)
|
||||
}
|
||||
.sheet(isPresented: $showingPairing) {
|
||||
RelayPairingView(model: pairingModel, fleet: model)
|
||||
}
|
||||
.onChange(of: model.showingForm) { showing in
|
||||
if !showing {
|
||||
editingInstance = nil
|
||||
@@ -839,11 +854,20 @@ private extension FleetView {
|
||||
tint: statusColor(row.status)
|
||||
)
|
||||
}
|
||||
Text(row.instance.origin.absoluteString)
|
||||
.font(.caption)
|
||||
.foregroundStyle(AITheme.muted)
|
||||
.lineLimit(1)
|
||||
.truncationMode(.middle)
|
||||
HStack(spacing: 6) {
|
||||
Text(row.instance.endpoint.displayAddress)
|
||||
.font(.caption)
|
||||
.foregroundStyle(AITheme.muted)
|
||||
.lineLimit(1)
|
||||
.truncationMode(.middle)
|
||||
// 通道徽标：没有它，"这台为什么慢"无法回答。
|
||||
channelBadge(row.channel)
|
||||
if !row.testing, row.freshness != .fresh {
|
||||
Text(row.freshness.label)
|
||||
.font(.caption2)
|
||||
.foregroundStyle(AITheme.muted)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 四条量表把"要不要担心这台"变成一次扫视：信号、延迟、CPU、内存。
|
||||
@@ -1039,16 +1063,35 @@ private extension FleetView {
|
||||
}
|
||||
|
||||
/// 只解释"为什么不是正常状态"。在线节点的细节交给指标栅格，上游原词（online 之类）不外泄。
|
||||
/// 通道徽标是刻意低调的：它解释延迟来源，不是需要用户处理的状态。
|
||||
private func channelBadge(_ channel: InstanceChannel) -> some View {
|
||||
Text(channel.label)
|
||||
.font(.caption2.weight(.semibold))
|
||||
.foregroundStyle(AITheme.muted)
|
||||
.padding(.horizontal, 6)
|
||||
.padding(.vertical, 1)
|
||||
.background(AITheme.canvas, in: Capsule())
|
||||
.overlay(Capsule().stroke(AITheme.line, lineWidth: 1))
|
||||
.accessibilityLabel(channel == .relay ? "经由中继" : "内网直通")
|
||||
}
|
||||
|
||||
private func statusLine(_ row: FleetViewModel.Row) -> String? {
|
||||
if row.testing { return "正在读取运行信息" }
|
||||
switch row.status {
|
||||
case .online:
|
||||
return nil
|
||||
case .degraded:
|
||||
// 中继模式下"部分接口不可用"可能有具体得多的原因，优先给能照做的说法。
|
||||
if let error = row.probeError {
|
||||
return ErrorMessage.describe(error, nodeName: row.instance.name)
|
||||
}
|
||||
return "部分接口不可用，可在详情查看失败接口"
|
||||
case .authRequired:
|
||||
return "节点开启了访问密码，进入详情登录"
|
||||
case .offline:
|
||||
if let error = row.probeError {
|
||||
return ErrorMessage.describe(error, nodeName: row.instance.name)
|
||||
}
|
||||
return "节点不可达，最后结果已过期"
|
||||
case .unknown:
|
||||
return "尚未检测"
|
||||
|
||||
@@ -29,6 +29,19 @@ final class FleetViewModel: ObservableObject {
|
||||
var uptimeSeconds: Double?
|
||||
var chainValues: DeviceLinkState?
|
||||
var testing: Bool
|
||||
/// Why the last probe ended where it did, for the detail text.
|
||||
var probeError: UpstreamError?
|
||||
/// When the last probe finished. The list shows how old a reading is, which in relay mode is
|
||||
/// the difference between "online" meaning now and meaning forty seconds ago.
|
||||
var checkedAt: Date?
|
||||
|
||||
/// Which path this node is reached by. The badge exists because without it "this one is
|
||||
/// slow" has no answer that a user can act on.
|
||||
var channel: InstanceChannel { instance.endpoint.channel }
|
||||
|
||||
var freshness: SnapshotFreshness {
|
||||
testing ? .unknown : SnapshotFreshness.classify(age: checkedAt.map { Date().timeIntervalSince($0) })
|
||||
}
|
||||
|
||||
var storageUsageRatio: Double? {
|
||||
guard let total = totalStorageBytes, let available = availableStorageBytes, total > 0 else {
|
||||
@@ -143,7 +156,7 @@ final class FleetViewModel: ObservableObject {
|
||||
expectedRevision: original.instance.configRevision,
|
||||
InstancePatch(
|
||||
name: input.name,
|
||||
origin: input.origin,
|
||||
endpoint: input.endpoint,
|
||||
tags: input.tags,
|
||||
password: input.password
|
||||
)
|
||||
@@ -215,6 +228,8 @@ final class FleetViewModel: ObservableObject {
|
||||
) {
|
||||
guard let index = rows.firstIndex(where: { $0.id == id }) else { return }
|
||||
rows[index].status = result?.status ?? .unknown
|
||||
rows[index].probeError = result?.error
|
||||
rows[index].checkedAt = result?.checkedAt
|
||||
if let summary {
|
||||
rows[index].deviceName = summary.deviceName
|
||||
rows[index].phoneNumber = summary.phoneNumber
|
||||
@@ -260,7 +275,7 @@ final class FleetViewModel: ObservableObject {
|
||||
guard !searchText.isEmpty else { return true }
|
||||
let haystacks: [String] = [
|
||||
row.instance.name,
|
||||
row.instance.origin.absoluteString,
|
||||
row.instance.endpoint.displayAddress,
|
||||
row.instance.tags.joined(separator: " "),
|
||||
row.operatorName ?? "",
|
||||
row.phoneNumber ?? "",
|
||||
|
||||
@@ -16,13 +16,18 @@ struct InstanceFormView: View {
|
||||
self.model = model
|
||||
self.instance = instance
|
||||
_name = State(initialValue: instance?.name ?? "")
|
||||
_originText = State(initialValue: instance?.origin.absoluteString ?? "")
|
||||
_originText = State(initialValue: instance?.endpoint.displayAddress ?? "")
|
||||
_tags = State(initialValue: instance?.tags ?? [])
|
||||
}
|
||||
|
||||
/// A relay instance is edited by name and tags only. Its address is not a URL the user typed —
|
||||
/// it is a pairing, and letting the form rewrite it would either drop the node's keys or produce
|
||||
/// an endpoint that fails validation. Re-pairing is the way to change it.
|
||||
private var isRelay: Bool { instance?.endpoint.isRelay == true }
|
||||
|
||||
private var canSave: Bool {
|
||||
!name.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
|
||||
&& !originText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
|
||||
&& (isRelay || !originText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
|
||||
}
|
||||
|
||||
var body: some View {
|
||||
@@ -32,16 +37,29 @@ struct InstanceFormView: View {
|
||||
AICard {
|
||||
VStack(alignment: .leading, spacing: 14) {
|
||||
field("名称", text: $name, placeholder: "Home Node")
|
||||
field("地址", text: $originText, placeholder: "http://192.168.1.10:3000")
|
||||
if isRelay {
|
||||
relayChannelRow
|
||||
} else {
|
||||
field("地址", text: $originText, placeholder: "http://192.168.1.10:3000")
|
||||
}
|
||||
tagEditor
|
||||
field(
|
||||
"实例密码",
|
||||
text: $password,
|
||||
placeholder: instance == nil ? "可选，仅保存在本机" : "留空则不修改密码",
|
||||
secure: true
|
||||
)
|
||||
if !isRelay {
|
||||
field(
|
||||
"实例密码",
|
||||
text: $password,
|
||||
placeholder: instance == nil ? "可选，仅保存在本机" : "留空则不修改密码",
|
||||
secure: true
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
if isRelay {
|
||||
AIStatusBanner(
|
||||
"中继节点的密码保存在节点 agent 上，手机不持有；更换中继需要重新配对。",
|
||||
tint: AITheme.muted,
|
||||
systemImage: "lock.shield"
|
||||
)
|
||||
}
|
||||
if let validationMessage {
|
||||
AIStatusBanner(
|
||||
validationMessage, tint: AITheme.danger, systemImage: "exclamationmark.triangle")
|
||||
@@ -81,6 +99,28 @@ struct InstanceFormView: View {
|
||||
}
|
||||
}
|
||||
|
||||
/// The relay channel is read-only here, but it must still be visible: without it the form shows
|
||||
/// a node with no address at all, which reads as missing data rather than as a different mode.
|
||||
private var relayChannelRow: some View {
|
||||
VStack(alignment: .leading, spacing: 6) {
|
||||
AIFieldLabel("通道")
|
||||
HStack(spacing: 8) {
|
||||
Text("中继")
|
||||
.font(.caption.weight(.semibold))
|
||||
.foregroundStyle(AITheme.muted)
|
||||
.padding(.horizontal, 8)
|
||||
.padding(.vertical, 3)
|
||||
.background(AITheme.canvas, in: Capsule())
|
||||
Text(originText.isEmpty ? "已配对节点" : originText)
|
||||
.font(.footnote)
|
||||
.foregroundStyle(AITheme.ink)
|
||||
.lineLimit(1)
|
||||
.truncationMode(.middle)
|
||||
}
|
||||
}
|
||||
.accessibilityElement(children: .combine)
|
||||
}
|
||||
|
||||
private var tagEditor: some View {
|
||||
VStack(alignment: .leading, spacing: 6) {
|
||||
AIFieldLabel("标签")
|
||||
@@ -128,9 +168,12 @@ struct InstanceFormView: View {
|
||||
isSaving = false
|
||||
return
|
||||
}
|
||||
// An existing relay instance keeps its endpoint: the address field only edits a direct
|
||||
// origin, and rewriting a pairing into a direct one here would silently drop the node's keys.
|
||||
let endpoint = instance?.endpoint.isRelay == true ? instance!.endpoint : InstanceEndpoint.direct(origin)
|
||||
let input = InstanceInput(
|
||||
name: normalizedName,
|
||||
origin: origin,
|
||||
endpoint: endpoint,
|
||||
tags: tags,
|
||||
password: password.isEmpty ? nil : password
|
||||
)
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
import SwiftUI
|
||||
|
||||
/// Pairs this phone with a node over the LAN.
|
||||
///
|
||||
/// The flow needs the phone to be inside the network, which is why it is a separate sheet rather
|
||||
/// than part of the instance form: the address here is the node's LAN address, not the relay's, and
|
||||
/// the password is the node's own — the one fact the pairing flow leans on.
|
||||
struct RelayPairingView: View {
|
||||
@Environment(\.dismiss) private var dismiss
|
||||
@ObservedObject var model: RelayPairingViewModel
|
||||
@ObservedObject var fleet: FleetViewModel
|
||||
|
||||
var body: some View {
|
||||
NavigationStack {
|
||||
ScrollView {
|
||||
VStack(spacing: 12) {
|
||||
AICard {
|
||||
VStack(alignment: .leading, spacing: 14) {
|
||||
field("节点内网地址", text: $model.host, placeholder: "192.168.1.10")
|
||||
field("节点访问密码", text: $model.password, placeholder: "SimAdmin 密码", secure: true)
|
||||
field("显示名称", text: $model.name, placeholder: "可留空，默认使用节点 ID")
|
||||
VStack(alignment: .leading, spacing: 6) {
|
||||
AIFieldLabel("标签")
|
||||
TagEditorView(tags: $model.tags, suggestions: fleet.allTags)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
AIStatusBanner(
|
||||
"配对需要手机与节点在同一内网。节点上先运行一次 msa-agent --pair，配对成功后它的管理端口会自动关闭。",
|
||||
tint: AITheme.muted,
|
||||
systemImage: "wifi"
|
||||
)
|
||||
|
||||
if let message = model.errorMessage {
|
||||
AIStatusBanner(message, tint: AITheme.danger, systemImage: "exclamationmark.triangle")
|
||||
}
|
||||
if case .done(let nodeID) = model.stage {
|
||||
AIStatusBanner(
|
||||
"配对完成，节点 \(nodeID) 已加入列表。",
|
||||
tint: AITheme.success,
|
||||
systemImage: "checkmark.circle"
|
||||
)
|
||||
}
|
||||
}
|
||||
.padding(16)
|
||||
.padding(.bottom, 8)
|
||||
}
|
||||
.background(AITheme.canvas.ignoresSafeArea())
|
||||
.navigationTitle("配对中继节点")
|
||||
#if os(iOS)
|
||||
.navigationBarTitleDisplayMode(.inline)
|
||||
.scrollDismissesKeyboard(.interactively)
|
||||
#endif
|
||||
.aiBottomActionBar {
|
||||
AIActionRow {
|
||||
Button(model.isDone ? "完成" : "取消") {
|
||||
if model.isDone {
|
||||
Task { await fleet.refresh() }
|
||||
}
|
||||
dismiss()
|
||||
}
|
||||
.buttonStyle(AIButtonStyle(kind: .secondary, size: .regular, fillsWidth: true))
|
||||
|
||||
if !model.isDone {
|
||||
Button {
|
||||
Task { await model.pair() }
|
||||
} label: {
|
||||
HStack(spacing: 8) {
|
||||
if model.stage == .pairing {
|
||||
ProgressView().controlSize(.small)
|
||||
}
|
||||
Text(model.stage == .pairing ? "配对中" : "开始配对")
|
||||
}
|
||||
}
|
||||
.buttonStyle(AIButtonStyle(kind: .primary, size: .regular, fillsWidth: true))
|
||||
.disabled(!model.canSubmit)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private func field(
|
||||
_ label: String,
|
||||
text: Binding<String>,
|
||||
placeholder: String,
|
||||
secure: Bool = false
|
||||
) -> some View {
|
||||
VStack(alignment: .leading, spacing: 6) {
|
||||
AIFieldLabel(label)
|
||||
if secure {
|
||||
SecureField(placeholder, text: text)
|
||||
.textFieldStyle(.plain)
|
||||
.font(.body)
|
||||
.padding(.horizontal, 12)
|
||||
.padding(.vertical, 10)
|
||||
.background(AITheme.control, in: RoundedRectangle(cornerRadius: 10, style: .continuous))
|
||||
} else {
|
||||
TextField(placeholder, text: text)
|
||||
.textFieldStyle(.plain)
|
||||
.font(.body)
|
||||
#if os(iOS)
|
||||
.keyboardType(.URL)
|
||||
.textInputAutocapitalization(.never)
|
||||
.autocorrectionDisabled()
|
||||
#endif
|
||||
.padding(.horizontal, 12)
|
||||
.padding(.vertical, 10)
|
||||
.background(AITheme.control, in: RoundedRectangle(cornerRadius: 10, style: .continuous))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,106 @@
|
||||
import CryptoKit
|
||||
import Foundation
|
||||
import SwiftUI
|
||||
|
||||
/// Drives the pairing sheet: collect the node's LAN address and password, run the pairing exchange,
|
||||
/// and hand the result to the repository as a new instance.
|
||||
///
|
||||
/// The pairing window on the node closes after one success, so a failure here is not merely "try
|
||||
/// again later": it may mean the window is shut and the operator has to re-open it on the node. The
|
||||
/// error text says which of the two happened, because the two call for different actions.
|
||||
@MainActor
|
||||
final class RelayPairingViewModel: ObservableObject {
|
||||
enum Stage: Equatable {
|
||||
case idle
|
||||
case pairing
|
||||
case done(nodeID: String)
|
||||
}
|
||||
|
||||
@Published var host = ""
|
||||
@Published var password = ""
|
||||
@Published var name = ""
|
||||
@Published var tags: [String] = []
|
||||
@Published var stage: Stage = .idle
|
||||
@Published var errorMessage: String?
|
||||
|
||||
private let pairing: RelayPairing
|
||||
private let identities: FileDeviceIdentityStore
|
||||
private let repository: any InstanceRepository
|
||||
|
||||
init(
|
||||
repository: any InstanceRepository,
|
||||
identities: FileDeviceIdentityStore,
|
||||
pairing: RelayPairing = RelayPairing()
|
||||
) {
|
||||
self.repository = repository
|
||||
self.identities = identities
|
||||
self.pairing = pairing
|
||||
}
|
||||
|
||||
var canSubmit: Bool {
|
||||
!host.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
|
||||
&& !password.isEmpty
|
||||
&& stage != .pairing
|
||||
}
|
||||
|
||||
var isDone: Bool {
|
||||
if case .done = stage { return true }
|
||||
return false
|
||||
}
|
||||
|
||||
func pair() async {
|
||||
guard canSubmit else { return }
|
||||
errorMessage = nil
|
||||
stage = .pairing
|
||||
let trimmedHost = host.trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
let displayName = name.trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
do {
|
||||
// The identity is created on first use: the phone needs keys before it can pair, but it
|
||||
// cannot know its device id until the node assigns one.
|
||||
let identity = try identities.loadOrCreate()
|
||||
let result = try await pairing.pair(
|
||||
host: trimmedHost,
|
||||
password: password,
|
||||
deviceName: displayName.isEmpty ? trimmedHost : displayName,
|
||||
identity: identity
|
||||
)
|
||||
// The id the node assigned has to be recorded before any request is sent, because it is
|
||||
// signed into every envelope and the node verifies it against its own device list.
|
||||
_ = try identities.assignDeviceID(result.deviceID)
|
||||
let instance = try await repository.create(InstanceInput(
|
||||
name: displayName.isEmpty ? (result.endpoint.nodeName ?? result.endpoint.nodeID) : displayName,
|
||||
endpoint: .relay(result.endpoint),
|
||||
tags: tags
|
||||
))
|
||||
_ = instance
|
||||
stage = .done(nodeID: result.endpoint.nodeID)
|
||||
password = ""
|
||||
} catch let failure as RelayPairing.Failure {
|
||||
stage = .idle
|
||||
errorMessage = Self.describe(failure, host: trimmedHost)
|
||||
} catch let error as RepositoryError {
|
||||
stage = .idle
|
||||
errorMessage = error == .duplicateOrigin
|
||||
? "该节点已经在中继列表中，无需重复配对。"
|
||||
: "配对成功但保存失败，请重试。"
|
||||
} catch {
|
||||
stage = .idle
|
||||
errorMessage = "配对失败：\(error)"
|
||||
}
|
||||
}
|
||||
|
||||
/// The pairing failure vocabulary is small and each case has one obvious next step, so the text
|
||||
/// states the step rather than the condition.
|
||||
static func describe(_ failure: RelayPairing.Failure, host: String) -> String {
|
||||
switch failure {
|
||||
case .rejected:
|
||||
return "节点密码不正确。请确认使用的是该节点 SimAdmin 的访问密码。"
|
||||
case .windowClosed:
|
||||
return "节点上的配对窗口已关闭。请在节点上重新运行一次配对（msa-agent --pair）后重试。"
|
||||
case .unreachable:
|
||||
return "无法连接 \(host):3001。请确认手机与节点在同一内网，且节点上已启动配对。"
|
||||
case .malformedResponse:
|
||||
return "节点返回的内容不是有效的配对响应。请确认节点上运行的是本方案的 agent。"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -19,21 +19,25 @@ public struct LogCenterService: Sendable {
|
||||
var diagnostic: InstanceDiagnostic?
|
||||
}
|
||||
|
||||
private let client: any SimAdminClientProtocol
|
||||
private let sessions: InstanceSessionStore
|
||||
private let credentials: (any CredentialStore)?
|
||||
private let transport: any NodeTransport
|
||||
private let store: any LogStore
|
||||
|
||||
public init(transport: any NodeTransport, store: any LogStore) {
|
||||
self.transport = transport
|
||||
self.store = store
|
||||
}
|
||||
|
||||
/// Direct-mode construction, kept for the existing call sites and tests.
|
||||
public init(
|
||||
client: any SimAdminClientProtocol,
|
||||
sessions: InstanceSessionStore,
|
||||
credentials: (any CredentialStore)? = nil,
|
||||
store: any LogStore
|
||||
) {
|
||||
self.client = client
|
||||
self.sessions = sessions
|
||||
self.credentials = credentials
|
||||
self.store = store
|
||||
self.init(
|
||||
transport: DirectTransport(client: client, sessions: sessions, credentials: credentials),
|
||||
store: store
|
||||
)
|
||||
}
|
||||
|
||||
public func refresh(_ instances: [Instance]) async throws -> LogSnapshot {
|
||||
@@ -115,7 +119,11 @@ public struct LogCenterService: Sendable {
|
||||
private func probe(_ instance: Instance) async -> ProbeOutcome {
|
||||
let startedAt = Date()
|
||||
do {
|
||||
let response = try await client.send(.health, baseURL: instance.origin, cookie: nil)
|
||||
let response = try await transport.send(
|
||||
.health,
|
||||
instanceID: instance.id,
|
||||
endpoint: instance.endpoint
|
||||
)
|
||||
let duration = elapsed(startedAt)
|
||||
let root = (try? JSONSerialization.jsonObject(with: response.data)) as? [String: Any] ?? [:]
|
||||
return ProbeOutcome(
|
||||
@@ -207,7 +215,7 @@ public struct LogCenterService: Sendable {
|
||||
return InstanceDiagnostic(
|
||||
id: instance.id,
|
||||
name: instance.name,
|
||||
origin: instance.origin.absoluteString,
|
||||
origin: instance.endpoint.displayAddress,
|
||||
tags: instance.tags,
|
||||
state: probe.status,
|
||||
healthStatus: Self.healthLabel(probe),
|
||||
@@ -226,30 +234,7 @@ public struct LogCenterService: Sendable {
|
||||
}
|
||||
|
||||
private func request(_ route: UpstreamRoute, _ instance: Instance) async throws -> UpstreamResponse {
|
||||
var cookie = await sessions.cookie(for: instance.id, origin: instance.origin)
|
||||
do {
|
||||
return try await client.send(route, baseURL: instance.origin, cookie: cookie)
|
||||
} catch UpstreamError.unauthorized, UpstreamError.forbidden {
|
||||
cookie = try await login(instance)
|
||||
return try await client.send(route, baseURL: instance.origin, cookie: cookie)
|
||||
}
|
||||
}
|
||||
|
||||
private func login(_ instance: Instance) async throws -> String {
|
||||
guard let credentials,
|
||||
let password = try credentials.get(instanceID: instance.id),
|
||||
!password.isEmpty
|
||||
else {
|
||||
throw UpstreamError.unauthorized
|
||||
}
|
||||
let service = InstanceSessionService(store: sessions, client: client)
|
||||
let result = try await service.login(instance, password: password)
|
||||
guard result.authenticated,
|
||||
let cookie = await sessions.cookie(for: instance.id, origin: instance.origin)
|
||||
else {
|
||||
throw UpstreamError.unauthorized
|
||||
}
|
||||
return cookie
|
||||
try await transport.send(route, instanceID: instance.id, endpoint: instance.endpoint)
|
||||
}
|
||||
|
||||
private func elapsed(_ startedAt: Date) -> Int {
|
||||
|
||||
@@ -7,18 +7,19 @@ public enum MessageServiceError: Error, Equatable {
|
||||
}
|
||||
|
||||
public struct MessageService: Sendable {
|
||||
private let client: any SimAdminClientProtocol
|
||||
private let sessions: InstanceSessionStore
|
||||
private let credentials: (any CredentialStore)?
|
||||
private let transport: any NodeTransport
|
||||
|
||||
public init(transport: any NodeTransport) {
|
||||
self.transport = transport
|
||||
}
|
||||
|
||||
/// Direct-mode construction, kept for the existing call sites and tests.
|
||||
public init(
|
||||
client: any SimAdminClientProtocol,
|
||||
sessions: InstanceSessionStore,
|
||||
credentials: (any CredentialStore)? = nil
|
||||
) {
|
||||
self.client = client
|
||||
self.sessions = sessions
|
||||
self.credentials = credentials
|
||||
self.init(transport: DirectTransport(client: client, sessions: sessions, credentials: credentials))
|
||||
}
|
||||
|
||||
public func messages(
|
||||
@@ -75,30 +76,7 @@ public struct MessageService: Sendable {
|
||||
}
|
||||
|
||||
private func request(_ route: UpstreamRoute, _ instance: Instance) async throws -> UpstreamResponse {
|
||||
var cookie = await sessions.cookie(for: instance.id, origin: instance.origin)
|
||||
do {
|
||||
return try await client.send(route, baseURL: instance.origin, cookie: cookie)
|
||||
} catch UpstreamError.unauthorized, UpstreamError.forbidden {
|
||||
cookie = try await login(instance)
|
||||
return try await client.send(route, baseURL: instance.origin, cookie: cookie)
|
||||
}
|
||||
}
|
||||
|
||||
private func login(_ instance: Instance) async throws -> String {
|
||||
guard let credentials,
|
||||
let password = try credentials.get(instanceID: instance.id),
|
||||
!password.isEmpty
|
||||
else {
|
||||
throw MessageServiceError.unauthorized
|
||||
}
|
||||
let sessions = InstanceSessionService(store: sessions, client: client)
|
||||
let result = try await sessions.login(instance, password: password)
|
||||
guard result.authenticated,
|
||||
let cookie = await sessions.cookie(for: instance)
|
||||
else {
|
||||
throw MessageServiceError.unauthorized
|
||||
}
|
||||
return cookie
|
||||
try await transport.send(route, instanceID: instance.id, endpoint: instance.endpoint)
|
||||
}
|
||||
|
||||
static func parsePage(_ response: UpstreamResponse, _ instance: Instance) throws -> MessagePage {
|
||||
|
||||
@@ -60,8 +60,12 @@ final class MessagesViewModel: ObservableObject {
|
||||
}
|
||||
let page = try await service.messages(loaded, limit: 100)
|
||||
rows = page.messages
|
||||
} catch MessageServiceError.unauthorized {
|
||||
} catch MessageServiceError.unauthorized, UpstreamError.unauthorized {
|
||||
errorMessage = "节点需要访问密码，请在编辑节点中填写后重试。"
|
||||
} catch let error as UpstreamError {
|
||||
// 中继模式下失败原因有四类以上，各自对应不同处理动作；
|
||||
// 统一兜底文案会把"重试即可"和"需要重新配对"说成同一件事。
|
||||
errorMessage = ErrorMessage.describe(error, nodeName: selectedInstance?.name ?? "节点")
|
||||
} catch {
|
||||
errorMessage = "所有节点都没有返回消息，可能节点离线或未开启短信接口。"
|
||||
}
|
||||
|
||||
@@ -11,13 +11,39 @@ public enum RepositoryError: Error, Equatable, Sendable {
|
||||
public struct Instance: Codable, Equatable, Identifiable, Sendable {
|
||||
public let id: UUID
|
||||
public var name: String
|
||||
public var origin: URL
|
||||
/// Where this node is reached from. Direct on the local network, or through a relay.
|
||||
///
|
||||
/// This replaced a non-optional `origin: URL`. The migration in `init(from:)` reads the old
|
||||
/// shape so an existing node list upgrades without being reported as duplicate, and every write
|
||||
/// emits only the new shape.
|
||||
public var endpoint: InstanceEndpoint
|
||||
public var tags: [String]
|
||||
public var credentialConfigured: Bool
|
||||
public var configRevision: Int
|
||||
public let createdAt: Date
|
||||
public var updatedAt: Date
|
||||
|
||||
public init(
|
||||
id: UUID,
|
||||
name: String,
|
||||
endpoint: InstanceEndpoint,
|
||||
tags: [String] = [],
|
||||
credentialConfigured: Bool = false,
|
||||
configRevision: Int = 1,
|
||||
createdAt: Date,
|
||||
updatedAt: Date
|
||||
) {
|
||||
self.id = id
|
||||
self.name = name
|
||||
self.endpoint = endpoint
|
||||
self.tags = tags
|
||||
self.credentialConfigured = credentialConfigured
|
||||
self.configRevision = configRevision
|
||||
self.createdAt = createdAt
|
||||
self.updatedAt = updatedAt
|
||||
}
|
||||
|
||||
/// Convenience for the direct case, which is what most call sites mean.
|
||||
public init(
|
||||
id: UUID,
|
||||
name: String,
|
||||
@@ -28,50 +54,113 @@ public struct Instance: Codable, Equatable, Identifiable, Sendable {
|
||||
createdAt: Date,
|
||||
updatedAt: Date
|
||||
) {
|
||||
self.id = id
|
||||
self.name = name
|
||||
self.origin = origin
|
||||
self.tags = tags
|
||||
self.credentialConfigured = credentialConfigured
|
||||
self.configRevision = configRevision
|
||||
self.createdAt = createdAt
|
||||
self.updatedAt = updatedAt
|
||||
self.init(
|
||||
id: id,
|
||||
name: name,
|
||||
endpoint: .direct(origin),
|
||||
tags: tags,
|
||||
credentialConfigured: credentialConfigured,
|
||||
configRevision: configRevision,
|
||||
createdAt: createdAt,
|
||||
updatedAt: updatedAt
|
||||
)
|
||||
}
|
||||
|
||||
/// The direct origin, when this instance has one.
|
||||
public var origin: URL? { endpoint.directOrigin }
|
||||
|
||||
public var isRelay: Bool { endpoint.isRelay }
|
||||
|
||||
private enum CodingKeys: String, CodingKey {
|
||||
case id, name, endpoint, origin, tags, credentialConfigured, configRevision, createdAt, updatedAt
|
||||
}
|
||||
|
||||
/// Decodes the new shape, falling back to the pre-relay `origin` field.
|
||||
///
|
||||
/// The fallback is what makes the upgrade invisible: an app that dropped support for the old key
|
||||
/// would fail to decode the whole store and lose every node. Note that `origin` is decoded
|
||||
/// leniently as a string and parsed here rather than decoded as a `URL`, because the encoder
|
||||
/// that wrote it may have produced a spelling `URL` will not round-trip from a bare string in
|
||||
/// every case.
|
||||
public init(from decoder: Decoder) throws {
|
||||
let container = try decoder.container(keyedBy: CodingKeys.self)
|
||||
id = try container.decode(UUID.self, forKey: .id)
|
||||
name = try container.decode(String.self, forKey: .name)
|
||||
if let endpoint = try container.decodeIfPresent(InstanceEndpoint.self, forKey: .endpoint) {
|
||||
self.endpoint = endpoint
|
||||
} else if let origin = try container.decodeIfPresent(URL.self, forKey: .origin) {
|
||||
self.endpoint = .direct(origin)
|
||||
} else {
|
||||
throw DecodingError.keyNotFound(
|
||||
CodingKeys.endpoint,
|
||||
DecodingError.Context(
|
||||
codingPath: container.codingPath,
|
||||
debugDescription: "an instance must carry either endpoint or the legacy origin"
|
||||
)
|
||||
)
|
||||
}
|
||||
tags = try container.decodeIfPresent([String].self, forKey: .tags) ?? []
|
||||
credentialConfigured = try container.decodeIfPresent(Bool.self, forKey: .credentialConfigured) ?? false
|
||||
configRevision = try container.decodeIfPresent(Int.self, forKey: .configRevision) ?? 1
|
||||
createdAt = try container.decode(Date.self, forKey: .createdAt)
|
||||
updatedAt = try container.decode(Date.self, forKey: .updatedAt)
|
||||
}
|
||||
|
||||
public func encode(to encoder: Encoder) throws {
|
||||
var container = encoder.container(keyedBy: CodingKeys.self)
|
||||
try container.encode(id, forKey: .id)
|
||||
try container.encode(name, forKey: .name)
|
||||
try container.encode(endpoint, forKey: .endpoint)
|
||||
try container.encode(tags, forKey: .tags)
|
||||
try container.encode(credentialConfigured, forKey: .credentialConfigured)
|
||||
try container.encode(configRevision, forKey: .configRevision)
|
||||
try container.encode(createdAt, forKey: .createdAt)
|
||||
try container.encode(updatedAt, forKey: .updatedAt)
|
||||
}
|
||||
}
|
||||
|
||||
public struct InstanceInput: Sendable {
|
||||
public var name: String
|
||||
public var origin: URL
|
||||
public var endpoint: InstanceEndpoint
|
||||
public var tags: [String]
|
||||
public var password: String?
|
||||
|
||||
public init(
|
||||
name: String,
|
||||
endpoint: InstanceEndpoint,
|
||||
tags: [String] = [],
|
||||
password: String? = nil
|
||||
) {
|
||||
self.name = name
|
||||
self.endpoint = endpoint
|
||||
self.tags = tags
|
||||
self.password = password
|
||||
}
|
||||
|
||||
public init(
|
||||
name: String,
|
||||
origin: URL,
|
||||
tags: [String] = [],
|
||||
password: String? = nil
|
||||
) {
|
||||
self.name = name
|
||||
self.origin = origin
|
||||
self.tags = tags
|
||||
self.password = password
|
||||
self.init(name: name, endpoint: .direct(origin), tags: tags, password: password)
|
||||
}
|
||||
}
|
||||
|
||||
public struct InstancePatch: Sendable {
|
||||
public var name: String?
|
||||
public var origin: URL?
|
||||
public var endpoint: InstanceEndpoint?
|
||||
public var tags: [String]?
|
||||
public var password: String?
|
||||
|
||||
public init(
|
||||
name: String? = nil,
|
||||
origin: URL? = nil,
|
||||
endpoint: InstanceEndpoint? = nil,
|
||||
tags: [String]? = nil,
|
||||
password: String? = nil
|
||||
) {
|
||||
self.name = name
|
||||
self.origin = origin
|
||||
self.endpoint = endpoint
|
||||
self.tags = tags
|
||||
self.password = password
|
||||
}
|
||||
|
||||
@@ -95,7 +95,7 @@ enum AppTab: Hashable {
|
||||
let repository = FileInstanceRepository(location: DefaultContainer.documentFileURL("instances.json"))
|
||||
guard let listed = try? await repository.list(InstanceQuery()), listed.isEmpty == false else { return }
|
||||
// 截图验证优先看可达节点（3000），否则详情页全是空态，看不出真实排版。
|
||||
target = listed.first { $0.origin.port == 3000 } ?? listed[0]
|
||||
target = listed.first { $0.endpoint.directOrigin?.port == 3000 } ?? listed[0]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -29,7 +29,7 @@ public struct FileInstanceRepository: InstanceRepository {
|
||||
!search.isEmpty {
|
||||
instances = instances.filter {
|
||||
$0.name.localizedCaseInsensitiveContains(search)
|
||||
|| $0.origin.absoluteString.localizedCaseInsensitiveContains(search)
|
||||
|| $0.endpoint.displayAddress.localizedCaseInsensitiveContains(search)
|
||||
}
|
||||
}
|
||||
if let tags = query.tags, !tags.isEmpty {
|
||||
@@ -48,15 +48,15 @@ public struct FileInstanceRepository: InstanceRepository {
|
||||
guard !input.name.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
|
||||
throw RepositoryError.invalidOrigin
|
||||
}
|
||||
let origin = try Self.normalizedOrigin(input.origin)
|
||||
guard !store.instances.contains(where: { $0.origin == origin }) else {
|
||||
let endpoint = try Self.normalized(input.endpoint)
|
||||
guard !store.instances.contains(where: { $0.endpoint.dedupKey == endpoint.dedupKey }) else {
|
||||
throw RepositoryError.duplicateOrigin
|
||||
}
|
||||
let now = Date()
|
||||
let instance = Instance(
|
||||
id: UUID(),
|
||||
name: input.name.trimmingCharacters(in: .whitespacesAndNewlines),
|
||||
origin: origin,
|
||||
endpoint: endpoint,
|
||||
tags: Self.normalizedTags(input.tags),
|
||||
credentialConfigured: !(input.password ?? "").isEmpty,
|
||||
createdAt: now,
|
||||
@@ -82,12 +82,14 @@ public struct FileInstanceRepository: InstanceRepository {
|
||||
guard !normalized.isEmpty else { throw RepositoryError.invalidOrigin }
|
||||
instance.name = normalized
|
||||
}
|
||||
if let origin = patch.origin {
|
||||
let normalized = try Self.normalizedOrigin(origin)
|
||||
guard !store.instances.contains(where: { $0.id != id && $0.origin == normalized }) else {
|
||||
if let endpoint = patch.endpoint {
|
||||
let normalized = try Self.normalized(endpoint)
|
||||
guard !store.instances.contains(where: {
|
||||
$0.id != id && $0.endpoint.dedupKey == normalized.dedupKey
|
||||
}) else {
|
||||
throw RepositoryError.duplicateOrigin
|
||||
}
|
||||
instance.origin = normalized
|
||||
instance.endpoint = normalized
|
||||
}
|
||||
if let tags = patch.tags {
|
||||
instance.tags = Self.normalizedTags(tags)
|
||||
@@ -150,6 +152,39 @@ public struct FileInstanceRepository: InstanceRepository {
|
||||
}
|
||||
}
|
||||
|
||||
private static func normalized(_ endpoint: InstanceEndpoint) throws -> InstanceEndpoint {
|
||||
switch endpoint {
|
||||
case .direct(let url):
|
||||
return .direct(try normalizedOrigin(url))
|
||||
case .relay(let relay):
|
||||
// A relay endpoint is validated on its own terms: https, a parseable node id, and the
|
||||
// exact key sizes the envelope format requires. A half-configured relay entry that
|
||||
// reached the transport would fail as an unreadable response rather than as "this
|
||||
// pairing is incomplete".
|
||||
guard relay.relayBaseURL.scheme == "https",
|
||||
relay.relayBaseURL.host?.isEmpty == false,
|
||||
relay.relayBaseURL.path.isEmpty || relay.relayBaseURL.path == "/"
|
||||
else {
|
||||
throw RepositoryError.invalidOrigin
|
||||
}
|
||||
guard relay.nodeID.hasPrefix("nd_"), relay.nodeID.count >= 11 else {
|
||||
throw RepositoryError.invalidOrigin
|
||||
}
|
||||
guard relay.agentSigningKey.count == RelayWire.keyBytes,
|
||||
relay.agentKxKey.count == RelayWire.keyBytes,
|
||||
relay.deviceToken.count >= 16,
|
||||
relay.deviceID.hasPrefix("ap_")
|
||||
else {
|
||||
throw RepositoryError.invalidOrigin
|
||||
}
|
||||
var normalized = relay
|
||||
normalized.relayBaseURL = URL(string: relay.relayBaseURL.absoluteString.trimmingCharacters(
|
||||
in: CharacterSet(charactersIn: "/")
|
||||
)) ?? relay.relayBaseURL
|
||||
return .relay(normalized)
|
||||
}
|
||||
}
|
||||
|
||||
private static func normalizedOrigin(_ url: URL) throws -> URL {
|
||||
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
|
||||
components.scheme == "http" || components.scheme == "https",
|
||||
|
||||
@@ -0,0 +1,348 @@
|
||||
import Foundation
|
||||
|
||||
/// The canonical JSON form this protocol hashes.
|
||||
///
|
||||
/// This is a hand-written parser rather than `JSONSerialization`, and the reason is not preference:
|
||||
/// the canonical form is defined over the *spelling* of the input, and every Foundation decoder
|
||||
/// erases spelling before the caller sees anything. `1.0` and `1` both arrive as `NSNumber(1)`;
|
||||
/// a lone surrogate is either rejected outright or silently repaired depending on the framework
|
||||
/// version. Trying to recover the original text from a decoded tree is how two languages end up
|
||||
/// hashing different bytes for the same body, which surfaces as an intent mismatch the phone
|
||||
/// reports as "confirmation failed" with no way to tell which side was wrong.
|
||||
///
|
||||
/// The rules, which the Go agent and the Node reference implementation implement identically, are
|
||||
/// documented in `agent/internal/wire/json.go`. The short version: keys sorted by UTF-8 bytes,
|
||||
/// no insignificant whitespace, integers only in canonical spelling, strings escaped as `\" \\ \n
|
||||
/// \r \t \b \f`, `\u00XX` for other control characters, literal UTF-8 for everything else, and a
|
||||
/// lone surrogate escape is an error rather than a replacement character.
|
||||
public enum CanonicalJSON {
|
||||
public enum Failure: Error, Equatable {
|
||||
case invalidJSON
|
||||
case trailingData
|
||||
case nonCanonicalNumber(String)
|
||||
case loneSurrogate(UInt32)
|
||||
case unsupportedValue
|
||||
}
|
||||
|
||||
/// Canonicalises a JSON document. An empty or whitespace-only body canonicalises to no bytes at
|
||||
/// all, not to the four characters `null`, so "no body" and "empty body" cannot be confused.
|
||||
public static func canonicalize(_ text: String) throws -> Data {
|
||||
let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
|
||||
guard !trimmed.isEmpty else { return Data() }
|
||||
var parser = Parser(Array(trimmed.unicodeScalars))
|
||||
let value = try parser.parseValue()
|
||||
parser.skipWhitespace()
|
||||
guard parser.isAtEnd else { throw Failure.trailingData }
|
||||
var out = Data()
|
||||
try serialize(value, into: &out)
|
||||
return out
|
||||
}
|
||||
|
||||
/// Canonicalises raw body bytes, which is what the intent digest needs.
|
||||
public static func canonicalize(_ data: Data) throws -> Data {
|
||||
guard let text = String(data: data, encoding: .utf8) else { throw Failure.invalidJSON }
|
||||
return try canonicalize(text)
|
||||
}
|
||||
|
||||
// MARK: - Value tree
|
||||
|
||||
indirect enum Value {
|
||||
case null
|
||||
case bool(Bool)
|
||||
case integer(String)
|
||||
case string(String)
|
||||
case array([Value])
|
||||
case object([(key: String, value: Value)])
|
||||
}
|
||||
|
||||
// MARK: - Serialisation
|
||||
|
||||
static func serialize(_ value: Value, into out: inout Data) throws {
|
||||
switch value {
|
||||
case .null:
|
||||
out.append(contentsOf: Array("null".utf8))
|
||||
case .bool(let flag):
|
||||
out.append(contentsOf: Array((flag ? "true" : "false").utf8))
|
||||
case .integer(let literal):
|
||||
out.append(contentsOf: Array(literal.utf8))
|
||||
case .string(let text):
|
||||
escape(text, into: &out)
|
||||
case .array(let items):
|
||||
out.append(UInt8(ascii: "["))
|
||||
for (index, item) in items.enumerated() {
|
||||
if index > 0 { out.append(UInt8(ascii: ",")) }
|
||||
try serialize(item, into: &out)
|
||||
}
|
||||
out.append(UInt8(ascii: "]"))
|
||||
case .object(let members):
|
||||
// UTF-8 byte order, which is what the Go agent's sort.Strings produces. Two shortcuts
|
||||
// are wrong here and both look right on ASCII: Swift's default String `<` uses Unicode
|
||||
// collation (so "é" sorts before "z"), and Foundation's `.sortedKeys` does the same.
|
||||
let sorted = members.sorted { Array($0.key.utf8).lexicographicallyPrecedes(Array($1.key.utf8)) }
|
||||
out.append(UInt8(ascii: "{"))
|
||||
for (index, member) in sorted.enumerated() {
|
||||
if index > 0 { out.append(UInt8(ascii: ",")) }
|
||||
escape(member.key, into: &out)
|
||||
out.append(UInt8(ascii: ":"))
|
||||
try serialize(member.value, into: &out)
|
||||
}
|
||||
out.append(UInt8(ascii: "}"))
|
||||
}
|
||||
}
|
||||
|
||||
/// Writes a JSON string literal in the canonical spelling.
|
||||
///
|
||||
/// The two rules worth stating: control characters below 0x20 use the short forms JSON names
|
||||
/// where they exist and `\u00XX` otherwise (matching Go's encoder with HTML escaping off), and
|
||||
/// everything else — including U+2028, U+2029, DEL and astral characters — is emitted as
|
||||
/// literal UTF-8. Go's encoder escapes U+2028/U+2029 even with HTML escaping disabled, which is
|
||||
/// why the Go side had to grow its own writer too; the vectors pin the literal form.
|
||||
static func escape(_ text: String, into out: inout Data) {
|
||||
out.append(UInt8(ascii: "\""))
|
||||
for scalar in text.unicodeScalars {
|
||||
switch scalar {
|
||||
case "\"":
|
||||
out.append(contentsOf: Array("\\\"".utf8))
|
||||
case "\\":
|
||||
out.append(contentsOf: Array("\\\\".utf8))
|
||||
case "\n":
|
||||
out.append(contentsOf: Array("\\n".utf8))
|
||||
case "\r":
|
||||
out.append(contentsOf: Array("\\r".utf8))
|
||||
case "\t":
|
||||
out.append(contentsOf: Array("\\t".utf8))
|
||||
case Unicode.Scalar(0x08):
|
||||
out.append(contentsOf: Array("\\b".utf8))
|
||||
case Unicode.Scalar(0x0C):
|
||||
out.append(contentsOf: Array("\\f".utf8))
|
||||
default:
|
||||
if scalar.value < 0x20 {
|
||||
let hex = String(format: "%04x", scalar.value)
|
||||
out.append(contentsOf: Array("\\u\(hex)".utf8))
|
||||
} else {
|
||||
out.append(contentsOf: Array(String(scalar).utf8))
|
||||
}
|
||||
}
|
||||
}
|
||||
out.append(UInt8(ascii: "\""))
|
||||
}
|
||||
|
||||
// MARK: - Parser
|
||||
|
||||
struct Parser {
|
||||
private let scalars: [Unicode.Scalar]
|
||||
private var index = 0
|
||||
|
||||
init(_ scalars: [Unicode.Scalar]) {
|
||||
self.scalars = scalars
|
||||
}
|
||||
|
||||
var isAtEnd: Bool { index >= scalars.count }
|
||||
|
||||
mutating func skipWhitespace() {
|
||||
while index < scalars.count, isSpace(scalars[index]) { index += 1 }
|
||||
}
|
||||
|
||||
private func isSpace(_ scalar: Unicode.Scalar) -> Bool {
|
||||
scalar == " " || scalar == "\t" || scalar == "\n" || scalar == "\r"
|
||||
}
|
||||
|
||||
private func peek() -> Unicode.Scalar? {
|
||||
index < scalars.count ? scalars[index] : nil
|
||||
}
|
||||
|
||||
private mutating func expect(_ scalar: Unicode.Scalar) throws {
|
||||
guard peek() == scalar else { throw Failure.invalidJSON }
|
||||
index += 1
|
||||
}
|
||||
|
||||
mutating func parseValue() throws -> Value {
|
||||
skipWhitespace()
|
||||
guard let scalar = peek() else { throw Failure.invalidJSON }
|
||||
switch scalar {
|
||||
case "{": return try parseObject()
|
||||
case "[": return try parseArray()
|
||||
case "\"": return .string(try parseString())
|
||||
case "t":
|
||||
try expectWord("true")
|
||||
return .bool(true)
|
||||
case "f":
|
||||
try expectWord("false")
|
||||
return .bool(false)
|
||||
case "n":
|
||||
try expectWord("null")
|
||||
return .null
|
||||
default:
|
||||
return .integer(try parseNumber())
|
||||
}
|
||||
}
|
||||
|
||||
private mutating func expectWord(_ word: String) throws {
|
||||
for scalar in word.unicodeScalars {
|
||||
try expect(scalar)
|
||||
}
|
||||
}
|
||||
|
||||
private mutating func parseObject() throws -> Value {
|
||||
try expect("{")
|
||||
var members: [(key: String, value: Value)] = []
|
||||
skipWhitespace()
|
||||
if peek() == "}" {
|
||||
index += 1
|
||||
return .object(members)
|
||||
}
|
||||
while true {
|
||||
skipWhitespace()
|
||||
let key = try parseString()
|
||||
skipWhitespace()
|
||||
try expect(":")
|
||||
let value = try parseValue()
|
||||
// A repeated key takes the last occurrence, which is what Go's decoder and
|
||||
// JSON.parse both do. Refusing here would make the phone stricter than the agent
|
||||
// that recomputes the intent digest, and the two disagreeing about a body is the
|
||||
// failure this whole file exists to prevent.
|
||||
if let existing = members.firstIndex(where: { $0.key == key }) {
|
||||
members[existing] = (key, value)
|
||||
} else {
|
||||
members.append((key, value))
|
||||
}
|
||||
skipWhitespace()
|
||||
if peek() == "," {
|
||||
index += 1
|
||||
continue
|
||||
}
|
||||
try expect("}")
|
||||
return .object(members)
|
||||
}
|
||||
}
|
||||
|
||||
private mutating func parseArray() throws -> Value {
|
||||
try expect("[")
|
||||
var items: [Value] = []
|
||||
skipWhitespace()
|
||||
if peek() == "]" {
|
||||
index += 1
|
||||
return .array(items)
|
||||
}
|
||||
while true {
|
||||
items.append(try parseValue())
|
||||
skipWhitespace()
|
||||
if peek() == "," {
|
||||
index += 1
|
||||
continue
|
||||
}
|
||||
try expect("]")
|
||||
return .array(items)
|
||||
}
|
||||
}
|
||||
|
||||
/// Parses a string, resolving escapes.
|
||||
///
|
||||
/// A `\uXXXX` escape in the surrogate range must be correctly paired. A lone surrogate is
|
||||
/// an error here for the same reason it is in Go and Node: the three frameworks disagree
|
||||
/// about what to do with one, so the only rule all three can share is to accept none.
|
||||
private mutating func parseString() throws -> String {
|
||||
try expect("\"")
|
||||
var output = String.UnicodeScalarView()
|
||||
while true {
|
||||
guard let scalar = peek() else { throw Failure.invalidJSON }
|
||||
index += 1
|
||||
switch scalar {
|
||||
case "\"":
|
||||
return String(output)
|
||||
case "\\":
|
||||
output.append(try parseEscape())
|
||||
default:
|
||||
if scalar.value < 0x20 { throw Failure.invalidJSON }
|
||||
output.append(scalar)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private mutating func parseEscape() throws -> Unicode.Scalar {
|
||||
guard let scalar = peek() else { throw Failure.invalidJSON }
|
||||
index += 1
|
||||
switch scalar {
|
||||
case "\"": return "\""
|
||||
case "\\": return "\\"
|
||||
case "/": return "/"
|
||||
case "b": return Unicode.Scalar(0x08)
|
||||
case "f": return Unicode.Scalar(0x0C)
|
||||
case "n": return "\n"
|
||||
case "r": return "\r"
|
||||
case "t": return "\t"
|
||||
case "u":
|
||||
let high = try parseHex4()
|
||||
if high >= 0xD800, high <= 0xDBFF {
|
||||
guard peek() == "\\" else { throw Failure.loneSurrogate(high) }
|
||||
index += 1
|
||||
guard peek() == "u" else { throw Failure.loneSurrogate(high) }
|
||||
index += 1
|
||||
let low = try parseHex4()
|
||||
guard low >= 0xDC00, low <= 0xDFFF else { throw Failure.loneSurrogate(high) }
|
||||
let combined = 0x10000 + ((high - 0xD800) << 10) + (low - 0xDC00)
|
||||
guard let scalar = Unicode.Scalar(combined) else { throw Failure.loneSurrogate(high) }
|
||||
return scalar
|
||||
}
|
||||
guard high < 0xDC00 || high > 0xDFFF else { throw Failure.loneSurrogate(high) }
|
||||
guard let scalar = Unicode.Scalar(high) else { throw Failure.loneSurrogate(high) }
|
||||
return scalar
|
||||
default:
|
||||
throw Failure.invalidJSON
|
||||
}
|
||||
}
|
||||
|
||||
private mutating func parseHex4() throws -> UInt32 {
|
||||
var value: UInt32 = 0
|
||||
for _ in 0..<4 {
|
||||
guard let scalar = peek(), let digit = hexDigit(scalar) else { throw Failure.invalidJSON }
|
||||
index += 1
|
||||
value = value << 4 | digit
|
||||
}
|
||||
return value
|
||||
}
|
||||
|
||||
private func hexDigit(_ scalar: Unicode.Scalar) -> UInt32? {
|
||||
switch scalar {
|
||||
case "0"..."9": return scalar.value - 0x30
|
||||
case "a"..."f": return scalar.value - 0x61 + 10
|
||||
case "A"..."F": return scalar.value - 0x41 + 10
|
||||
default: return nil
|
||||
}
|
||||
}
|
||||
|
||||
/// Parses an integer in the one spelling this protocol hashes.
|
||||
///
|
||||
/// The literal is kept as text rather than converted to a number, so what gets hashed is
|
||||
/// what the phone sent. `1.0`, `1e3`, `+1`, `.5`, `01` and `-0` are all rejected: each of
|
||||
/// them is the same number as some accepted spelling, and "which spelling did the phone
|
||||
/// hash" is not a question this protocol leaves open.
|
||||
private mutating func parseNumber() throws -> String {
|
||||
var literal = ""
|
||||
if peek() == "-" {
|
||||
literal.append("-")
|
||||
index += 1
|
||||
}
|
||||
guard let first = peek(), first >= "0", first <= "9" else {
|
||||
throw Failure.invalidJSON
|
||||
}
|
||||
if first == "0" {
|
||||
literal.append("0")
|
||||
index += 1
|
||||
if let next = peek(), next >= "0", next <= "9" {
|
||||
throw Failure.nonCanonicalNumber(literal + String(next))
|
||||
}
|
||||
} else {
|
||||
while let next = peek(), next >= "0", next <= "9" {
|
||||
literal.append(Character(next))
|
||||
index += 1
|
||||
}
|
||||
}
|
||||
if let next = peek(), next == "." || next == "e" || next == "E" || next == "+" {
|
||||
throw Failure.nonCanonicalNumber(literal + String(next))
|
||||
}
|
||||
if literal == "-0" { throw Failure.nonCanonicalNumber(literal) }
|
||||
return literal
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,146 @@
|
||||
import CryptoKit
|
||||
import Foundation
|
||||
|
||||
/// The phone's long-term relay identity: one Ed25519 signing key and one X25519 key-agreement key,
|
||||
/// generated once and stored in the app sandbox.
|
||||
///
|
||||
/// The sandbox file rather than the keychain is a deliberate, recorded decision (design §6.4): the
|
||||
/// established convention in this app is that node credentials live in a sandbox file, and the
|
||||
/// Secure Enclave alternative conflicts with the TrollStore signing flow this build uses. The cost
|
||||
/// is real and stated plainly: on a jailbroken device the file can be read, which yields the ability
|
||||
/// to sign requests as this phone. It does not yield a node password, because the phone never holds
|
||||
/// one in relay mode.
|
||||
///
|
||||
/// The device id is minted by the *node* at pairing time, not here: the node's config is the
|
||||
/// authority for which device ids exist, and a phone that chose its own id could collide with an
|
||||
/// existing pairing.
|
||||
public struct DeviceIdentity: Sendable {
|
||||
public let deviceID: String
|
||||
public let signingKey: Curve25519.Signing.PrivateKey
|
||||
public let agreementKey: Curve25519.KeyAgreement.PrivateKey
|
||||
|
||||
public var signingPublicKey: Data { signingKey.publicKey.rawRepresentation }
|
||||
public var agreementPublicKey: Data { agreementKey.publicKey.rawRepresentation }
|
||||
|
||||
public init(
|
||||
deviceID: String,
|
||||
signingKey: Curve25519.Signing.PrivateKey,
|
||||
agreementKey: Curve25519.KeyAgreement.PrivateKey
|
||||
) {
|
||||
self.deviceID = deviceID
|
||||
self.signingKey = signingKey
|
||||
self.agreementKey = agreementKey
|
||||
}
|
||||
}
|
||||
|
||||
/// Generates and persists the device identity.
|
||||
///
|
||||
/// The file is written atomically with `completeFileProtection`, the same treatment the credential
|
||||
/// store uses, so a locked device's backup does not carry the private key in the clear.
|
||||
public struct FileDeviceIdentityStore: Sendable {
|
||||
private struct FileModel: Codable {
|
||||
var deviceID: String
|
||||
var signingKey: Data
|
||||
var agreementKey: Data
|
||||
/// Bumped when the storage shape changes, so a future migration can tell old files apart
|
||||
/// rather than guessing from missing fields.
|
||||
var schemaVersion: Int
|
||||
}
|
||||
|
||||
private let location: URL
|
||||
private let lock = NSLock()
|
||||
|
||||
public init(location: URL) {
|
||||
self.location = location
|
||||
}
|
||||
|
||||
/// Loads the identity, creating one on first use.
|
||||
///
|
||||
/// The `deviceID` is a placeholder until the node assigns a real one at pairing: the phone needs
|
||||
/// keys before it can pair, but it cannot know its id before the node decides. A pairing request
|
||||
/// sends the public halves and receives the id, which is then stored here.
|
||||
public func loadOrCreate() throws -> DeviceIdentity {
|
||||
try lock.withLock {
|
||||
if let model = read(), let identity = try? identity(from: model) {
|
||||
return identity
|
||||
}
|
||||
let identity = DeviceIdentity(
|
||||
deviceID: "",
|
||||
signingKey: Curve25519.Signing.PrivateKey(),
|
||||
agreementKey: Curve25519.KeyAgreement.PrivateKey()
|
||||
)
|
||||
try write(identity)
|
||||
return identity
|
||||
}
|
||||
}
|
||||
|
||||
/// Records the id the node assigned. The keys are unchanged: the node verified the public halves
|
||||
/// it was given, and regenerating them would invalidate the pairing it just wrote.
|
||||
public func assignDeviceID(_ deviceID: String) throws -> DeviceIdentity {
|
||||
try lock.withLock {
|
||||
let current = try loadOrCreateLocked()
|
||||
let updated = DeviceIdentity(
|
||||
deviceID: deviceID,
|
||||
signingKey: current.signingKey,
|
||||
agreementKey: current.agreementKey
|
||||
)
|
||||
try write(updated)
|
||||
return updated
|
||||
}
|
||||
}
|
||||
|
||||
public func reset() throws {
|
||||
try lock.withLock {
|
||||
try? FileManager.default.removeItem(at: location)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Internals
|
||||
|
||||
/// `loadOrCreate` is not reentrant with the lock, so the locked body lives here.
|
||||
private func loadOrCreateLocked() throws -> DeviceIdentity {
|
||||
if let model = read(), let identity = try? identity(from: model) {
|
||||
return identity
|
||||
}
|
||||
let identity = DeviceIdentity(
|
||||
deviceID: "",
|
||||
signingKey: Curve25519.Signing.PrivateKey(),
|
||||
agreementKey: Curve25519.KeyAgreement.PrivateKey()
|
||||
)
|
||||
try write(identity)
|
||||
return identity
|
||||
}
|
||||
|
||||
private func identity(from model: FileModel) throws -> DeviceIdentity {
|
||||
DeviceIdentity(
|
||||
deviceID: model.deviceID,
|
||||
signingKey: try Curve25519.Signing.PrivateKey(rawRepresentation: model.signingKey),
|
||||
agreementKey: try Curve25519.KeyAgreement.PrivateKey(rawRepresentation: model.agreementKey)
|
||||
)
|
||||
}
|
||||
|
||||
private func read() -> FileModel? {
|
||||
guard let data = try? Data(contentsOf: location) else { return nil }
|
||||
return try? JSONDecoder().decode(FileModel.self, from: data)
|
||||
}
|
||||
|
||||
private func write(_ identity: DeviceIdentity) throws {
|
||||
let model = FileModel(
|
||||
deviceID: identity.deviceID,
|
||||
signingKey: identity.signingKey.rawRepresentation,
|
||||
agreementKey: identity.agreementKey.rawRepresentation,
|
||||
schemaVersion: 1
|
||||
)
|
||||
let encoder = JSONEncoder()
|
||||
encoder.outputFormatting = [.sortedKeys]
|
||||
try FileManager.default.createDirectory(
|
||||
at: location.deletingLastPathComponent(),
|
||||
withIntermediateDirectories: true
|
||||
)
|
||||
try encoder.encode(model).write(to: location, options: [.atomic, .completeFileProtection])
|
||||
try FileManager.default.setAttributes(
|
||||
[.posixPermissions: 0o600],
|
||||
ofItemAtPath: location.path
|
||||
)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,279 @@
|
||||
import Foundation
|
||||
|
||||
/// How a node is reached, as a value the list can badge.
|
||||
public enum InstanceChannel: String, CaseIterable, Sendable {
|
||||
case direct
|
||||
case relay
|
||||
|
||||
public var label: String {
|
||||
switch self {
|
||||
case .direct: return "直通"
|
||||
case .relay: return "中继"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public extension InstanceEndpoint {
|
||||
var channel: InstanceChannel {
|
||||
switch self {
|
||||
case .direct: return .direct
|
||||
case .relay: return .relay
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// How the app reaches a node.
|
||||
///
|
||||
/// This exists rather than an optional `relayNodeID` field on `Instance` because `origin` currently
|
||||
/// carries three separate responsibilities — the request target, the duplicate-detection key, and
|
||||
/// the cookie binding domain — and in relay mode all three have to be re-homed. An optional field
|
||||
/// would leave two of them quietly pointing at an address that does not exist on a relay node.
|
||||
public enum InstanceEndpoint: Equatable, Sendable {
|
||||
/// The node is reachable directly on the local network. This is the original behaviour and its
|
||||
/// code path is unchanged.
|
||||
case direct(URL)
|
||||
/// The node is reached through a relay, with the agent on the node holding the session against
|
||||
/// the local SimAdmin. No node password is stored on the phone in this mode.
|
||||
case relay(RelayEndpoint)
|
||||
}
|
||||
|
||||
public struct RelayEndpoint: Equatable, Sendable {
|
||||
/// The relay's base URL, https. The only outbound destination in relay mode.
|
||||
public var relayBaseURL: URL
|
||||
/// The node this endpoint reaches, as the relay and the agent both name it.
|
||||
public var nodeID: String
|
||||
/// `K_agent_sign` public half, Ed25519, 32 bytes. Every response is verified against it.
|
||||
public var agentSigningKey: Data
|
||||
/// `K_agent_kx` public half, X25519, 32 bytes. Requests are encrypted to it.
|
||||
public var agentKxKey: Data
|
||||
/// The bearer the relay expects from this phone. It authorises nothing on the node: the node's
|
||||
/// authorisation comes from the signature the phone produces with its own private key.
|
||||
///
|
||||
/// A `String` rather than `Data`, which the design sketch drew: the relay compares the token as
|
||||
/// an opaque bearer value, so what has to survive the round trip is the exact text the node
|
||||
/// minted. Holding it as bytes invites a hex-encode on the way out, which sends a different
|
||||
/// string than the one the agent registered and fails as "unknown device" with nothing to see.
|
||||
public var deviceToken: String
|
||||
/// The device id the node knows this phone by, and which the phone signs into every request.
|
||||
public var deviceID: String
|
||||
/// The node's display name at pairing time, used only when the user has not renamed it.
|
||||
public var nodeName: String?
|
||||
|
||||
public init(
|
||||
relayBaseURL: URL,
|
||||
nodeID: String,
|
||||
agentSigningKey: Data,
|
||||
agentKxKey: Data,
|
||||
deviceToken: String,
|
||||
deviceID: String,
|
||||
nodeName: String? = nil
|
||||
) {
|
||||
self.relayBaseURL = relayBaseURL
|
||||
self.nodeID = nodeID
|
||||
self.agentSigningKey = agentSigningKey
|
||||
self.agentKxKey = agentKxKey
|
||||
self.deviceToken = deviceToken
|
||||
self.deviceID = deviceID
|
||||
self.nodeName = nodeName
|
||||
}
|
||||
}
|
||||
|
||||
public extension InstanceEndpoint {
|
||||
/// The direct origin, or nil in relay mode.
|
||||
///
|
||||
/// Callers that need "the address to dial directly" get nil rather than a substituted value, so
|
||||
/// a relay instance cannot accidentally be handed to a code path that would dial a LAN address
|
||||
/// that is not there.
|
||||
var directOrigin: URL? {
|
||||
if case .direct(let url) = self { return url }
|
||||
return nil
|
||||
}
|
||||
|
||||
var relay: RelayEndpoint? {
|
||||
if case .relay(let endpoint) = self { return endpoint }
|
||||
return nil
|
||||
}
|
||||
|
||||
var isRelay: Bool { relay != nil }
|
||||
|
||||
/// The identity used for duplicate detection.
|
||||
///
|
||||
/// Direct endpoints keep using the normalised origin so an existing node list upgrades without
|
||||
/// suddenly reporting duplicates; relay endpoints use the node id, because two phones paired to
|
||||
/// the same node are two different instances and one phone paired to two nodes is not.
|
||||
var dedupKey: String {
|
||||
switch self {
|
||||
case .direct(let url):
|
||||
return url.absoluteString
|
||||
case .relay(let endpoint):
|
||||
return "relay:\(endpoint.nodeID)"
|
||||
}
|
||||
}
|
||||
|
||||
/// What the user sees as "where this node is".
|
||||
var displayAddress: String {
|
||||
switch self {
|
||||
case .direct(let url):
|
||||
return url.absoluteString
|
||||
case .relay(let endpoint):
|
||||
return "\(endpoint.relayBaseURL.host ?? "relay") · \(endpoint.nodeID)"
|
||||
}
|
||||
}
|
||||
|
||||
/// Whether the phone holds a node password for this instance.
|
||||
///
|
||||
/// The two modes mean different things and must not share a string: directly it means "this
|
||||
/// phone has the node's password", through a relay it means "the node's agent has its own
|
||||
/// credential". Showing the first wording in relay mode would tell the user their password is
|
||||
/// on the phone when it deliberately is not.
|
||||
var credentialDescription: String {
|
||||
switch self {
|
||||
case .direct:
|
||||
return "已保存本机密码"
|
||||
case .relay:
|
||||
return "由节点 agent 保存凭据"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Codable
|
||||
|
||||
extension InstanceEndpoint: Codable {
|
||||
private enum CodingKeys: String, CodingKey { case kind, url, relay }
|
||||
private enum Kind: String, Codable { case direct, relay }
|
||||
|
||||
public init(from decoder: Decoder) throws {
|
||||
let container = try decoder.container(keyedBy: CodingKeys.self)
|
||||
switch try container.decode(Kind.self, forKey: .kind) {
|
||||
case .direct:
|
||||
self = .direct(try container.decode(URL.self, forKey: .url))
|
||||
case .relay:
|
||||
self = .relay(try container.decode(RelayEndpoint.self, forKey: .relay))
|
||||
}
|
||||
}
|
||||
|
||||
public func encode(to encoder: Encoder) throws {
|
||||
var container = encoder.container(keyedBy: CodingKeys.self)
|
||||
switch self {
|
||||
case .direct(let url):
|
||||
try container.encode(Kind.direct, forKey: .kind)
|
||||
try container.encode(url, forKey: .url)
|
||||
case .relay(let endpoint):
|
||||
try container.encode(Kind.relay, forKey: .kind)
|
||||
try container.encode(endpoint, forKey: .relay)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension RelayEndpoint: Codable {
|
||||
private enum CodingKeys: String, CodingKey {
|
||||
case relayBaseURL, nodeID, agentSigningKey, agentKxKey, deviceToken, deviceID, nodeName
|
||||
}
|
||||
|
||||
public init(from decoder: Decoder) throws {
|
||||
let container = try decoder.container(keyedBy: CodingKeys.self)
|
||||
relayBaseURL = try container.decode(URL.self, forKey: .relayBaseURL)
|
||||
nodeID = try container.decode(String.self, forKey: .nodeID)
|
||||
agentSigningKey = try container.decode(Data.self, forKey: .agentSigningKey)
|
||||
agentKxKey = try container.decode(Data.self, forKey: .agentKxKey)
|
||||
deviceToken = try container.decode(String.self, forKey: .deviceToken)
|
||||
deviceID = try container.decode(String.self, forKey: .deviceID)
|
||||
nodeName = try container.decodeIfPresent(String.self, forKey: .nodeName)
|
||||
guard agentSigningKey.count == RelayWire.keyBytes, agentKxKey.count == RelayWire.keyBytes else {
|
||||
throw DecodingError.dataCorruptedError(
|
||||
forKey: .agentSigningKey,
|
||||
in: container,
|
||||
debugDescription: "agent key material must be 32 raw bytes"
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
public func encode(to encoder: Encoder) throws {
|
||||
var container = encoder.container(keyedBy: CodingKeys.self)
|
||||
try container.encode(relayBaseURL, forKey: .relayBaseURL)
|
||||
try container.encode(nodeID, forKey: .nodeID)
|
||||
try container.encode(agentSigningKey, forKey: .agentSigningKey)
|
||||
try container.encode(agentKxKey, forKey: .agentKxKey)
|
||||
try container.encode(deviceToken, forKey: .deviceToken)
|
||||
try container.encode(deviceID, forKey: .deviceID)
|
||||
try container.encodeIfPresent(nodeName, forKey: .nodeName)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Relay error vocabulary
|
||||
|
||||
/// Every code the relay can return, mirroring `relay/src/errors.js`.
|
||||
///
|
||||
/// The console's `ProblemDetails.code` is an unconstrained string in the OpenAPI document, so this
|
||||
/// is a new vocabulary rather than a reuse of an existing one. It has to be enumerated in one place
|
||||
/// in the first version, because three implementations writing their own strings is exactly how
|
||||
/// cross-tier debugging stops working: the phone shows a code, the relay logs a code, and nobody can
|
||||
/// match them.
|
||||
public enum RelayErrorCode: String, CaseIterable, Sendable {
|
||||
case unauthorized = "relay_unauthorized"
|
||||
case nodeUnknown = "relay_node_unknown"
|
||||
case agentOffline = "relay_agent_offline"
|
||||
case mailboxFull = "relay_mailbox_full"
|
||||
case agentTimeout = "relay_agent_timeout"
|
||||
case badEnvelope = "relay_bad_envelope"
|
||||
case payloadTooLarge = "relay_payload_too_large"
|
||||
case rateLimited = "relay_rate_limited"
|
||||
case internalError = "relay_internal"
|
||||
case sessionExpired = "relay_session_expired"
|
||||
case badChallenge = "relay_bad_challenge"
|
||||
}
|
||||
|
||||
/// The agent's own classification, carried inside the ciphertext as `InnerResponse.outcome`.
|
||||
///
|
||||
/// Separate from `RelayErrorCode` because the two arrive through different channels and mean
|
||||
/// different things: a relay code is "the relay could not deliver this", an agent outcome is "the
|
||||
/// node received it and refused it". Collapsing them into one enum would lose the distinction the
|
||||
/// user needs, which is whether retrying can help.
|
||||
public enum AgentOutcome: String, CaseIterable, Sendable {
|
||||
case ok
|
||||
case badEnvelope = "bad_envelope"
|
||||
case badSignature = "bad_signature"
|
||||
case unknownDevice = "unknown_device"
|
||||
case expired
|
||||
case replay
|
||||
case policyDenied = "policy_denied"
|
||||
case confirmationMissing = "confirmation_missing"
|
||||
case confirmationMismatch = "confirmation_mismatch"
|
||||
case rateLimited = "rate_limited"
|
||||
case payloadTooLarge = "payload_too_large"
|
||||
case upstreamError = "upstream_error"
|
||||
case nodeAuthFailed = "node_auth_failed"
|
||||
}
|
||||
|
||||
/// Freshness of a snapshot, mirroring `FRESHNESS_STATUSES` in `packages/contracts/src/instances.ts`.
|
||||
///
|
||||
/// The four values are the existing vocabulary rather than new names. Without it a relay instance
|
||||
/// cannot express that its "online" reading is forty seconds old, which in a two-hop architecture is
|
||||
/// a substantive misstatement rather than a cosmetic one.
|
||||
public enum SnapshotFreshness: String, CaseIterable, Sendable {
|
||||
case fresh
|
||||
case stale
|
||||
case expired
|
||||
case unknown
|
||||
|
||||
/// Thresholds, chosen to line up with what the UI already implies: a direct probe is fresh for
|
||||
/// as long as a user would call the screen current, and anything past the relay's own request
|
||||
/// deadline is expired rather than merely old.
|
||||
public static func classify(age: TimeInterval?) -> SnapshotFreshness {
|
||||
guard let age, age >= 0 else { return .unknown }
|
||||
switch age {
|
||||
case ..<15: return .fresh
|
||||
case ..<90: return .stale
|
||||
default: return .expired
|
||||
}
|
||||
}
|
||||
|
||||
public var label: String {
|
||||
switch self {
|
||||
case .fresh: return "刚刚"
|
||||
case .stale: return "稍旧"
|
||||
case .expired: return "已过期"
|
||||
case .unknown: return "未知"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,125 @@
|
||||
import CryptoKit
|
||||
import Foundation
|
||||
|
||||
/// The phone's half of the pairing flow (design §7).
|
||||
///
|
||||
/// It works over the LAN, because at pairing time the phone is necessarily already inside the
|
||||
/// network — that is the fact the whole flow leans on, and it is what lets the shared secret be the
|
||||
/// node's own password instead of a QR code or a second credential to manage.
|
||||
///
|
||||
/// The node's agent serves this on a temporary management port that closes itself after one
|
||||
/// successful pairing, so a phone that cannot reach the node has to be paired again from the node
|
||||
/// rather than from anywhere else.
|
||||
public struct RelayPairing: Sendable {
|
||||
/// What the node returns on success.
|
||||
public struct Result: Equatable, Sendable {
|
||||
public let endpoint: RelayEndpoint
|
||||
/// The device id the node assigned. It is the node's choice, not the phone's: the node's
|
||||
/// config is the authority for which device ids exist.
|
||||
public let deviceID: String
|
||||
}
|
||||
|
||||
public enum Failure: Error, Equatable {
|
||||
/// The shared secret did not match. Distinct from a transport failure because the remedy is
|
||||
/// different: retype the password rather than check the network.
|
||||
case rejected
|
||||
/// The pairing window is closed — already used, or too many failed attempts.
|
||||
case windowClosed
|
||||
case unreachable
|
||||
case malformedResponse
|
||||
}
|
||||
|
||||
private let session: URLSession
|
||||
private let port: Int
|
||||
private let maximumBytes: Int
|
||||
|
||||
public init(session: URLSession = .shared, port: Int = 3001, maximumBytes: Int = 16 << 10) {
|
||||
self.session = session
|
||||
self.port = port
|
||||
self.maximumBytes = maximumBytes
|
||||
}
|
||||
|
||||
/// Pairs this phone with the node at `host`.
|
||||
///
|
||||
/// `host` is the node's LAN address as the user already typed it for direct mode, which is why
|
||||
/// the port is a separate parameter: the pairing window is not on the SimAdmin port.
|
||||
public func pair(
|
||||
host: String,
|
||||
password: String,
|
||||
deviceName: String,
|
||||
identity: DeviceIdentity
|
||||
) async throws -> Result {
|
||||
guard let url = URL(string: "http://\(host):\(port)/provision") else {
|
||||
throw Failure.unreachable
|
||||
}
|
||||
// The device name is informational on the node's side, and the two public keys are the whole
|
||||
// point: the node stores the signing key and returns its own, which becomes the phone's
|
||||
// trust anchor for every later response.
|
||||
let body: [String: String] = [
|
||||
"password": password,
|
||||
"appSignPub": identity.signingPublicKey.base64EncodedString(),
|
||||
"appKxPub": identity.agreementPublicKey.base64EncodedString(),
|
||||
"deviceName": deviceName,
|
||||
]
|
||||
var request = URLRequest(url: url, timeoutInterval: 15)
|
||||
request.httpMethod = "POST"
|
||||
request.setValue("application/json", forHTTPHeaderField: "content-type")
|
||||
request.setValue("application/json", forHTTPHeaderField: "accept")
|
||||
request.httpBody = try? JSONSerialization.data(withJSONObject: body)
|
||||
|
||||
let data: Data
|
||||
let response: URLResponse
|
||||
do {
|
||||
(data, response) = try await session.data(for: request)
|
||||
} catch {
|
||||
throw Failure.unreachable
|
||||
}
|
||||
guard let http = response as? HTTPURLResponse else { throw Failure.malformedResponse }
|
||||
switch http.statusCode {
|
||||
case 200:
|
||||
break
|
||||
case 401:
|
||||
throw Failure.rejected
|
||||
case 410:
|
||||
throw Failure.windowClosed
|
||||
default:
|
||||
throw Failure.malformedResponse
|
||||
}
|
||||
guard data.count <= maximumBytes,
|
||||
let root = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
|
||||
let nodeID = root["nodeID"] as? String,
|
||||
let appID = root["appID"] as? String,
|
||||
let relayURLText = root["relayURL"] as? String,
|
||||
let relayURL = URL(string: relayURLText),
|
||||
relayURL.scheme == "https",
|
||||
let signKey = Self.key(root["agentSignPub"] as? String),
|
||||
let kxKey = Self.key(root["agentKxPub"] as? String),
|
||||
let token = root["deviceToken"] as? String,
|
||||
!token.isEmpty
|
||||
else {
|
||||
throw Failure.malformedResponse
|
||||
}
|
||||
return Result(
|
||||
endpoint: RelayEndpoint(
|
||||
relayBaseURL: relayURL,
|
||||
nodeID: nodeID,
|
||||
agentSigningKey: signKey,
|
||||
agentKxKey: kxKey,
|
||||
deviceToken: token,
|
||||
deviceID: appID,
|
||||
nodeName: deviceName
|
||||
),
|
||||
deviceID: appID
|
||||
)
|
||||
}
|
||||
|
||||
/// A key the node published must be exactly 32 bytes. A short one would be accepted by the
|
||||
/// decoder and then fail as an unreadable response, which reads to the user as "the node is
|
||||
/// broken" rather than "this pairing is wrong".
|
||||
private static func key(_ text: String?) -> Data? {
|
||||
guard let text, let data = Data(base64Encoded: text), data.count == RelayWire.keyBytes else {
|
||||
return nil
|
||||
}
|
||||
return data
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,366 @@
|
||||
import CryptoKit
|
||||
import Foundation
|
||||
|
||||
/// What the app needs in order to reach a node, in either mode.
|
||||
///
|
||||
/// The abstraction exists so services stop taking a `baseURL` and a `cookie`: in relay mode there is
|
||||
/// no base URL to dial and no cookie, and a service that kept asking for one would be asking a
|
||||
/// question with no answer.
|
||||
///
|
||||
/// `instanceID` is part of the signature even though the design sketch showed only the endpoint,
|
||||
/// because the direct path scopes its cookie by `(instanceID, origin)` and losing that would let two
|
||||
/// instances pointed at the same node share a session. It is the one piece of the sketch that could
|
||||
/// not survive contact with the existing session store.
|
||||
public protocol NodeTransport: Sendable {
|
||||
func send(
|
||||
_ route: UpstreamRoute,
|
||||
instanceID: UUID,
|
||||
endpoint: InstanceEndpoint
|
||||
) async throws -> UpstreamResponse
|
||||
}
|
||||
|
||||
/// Picks the transport for an endpoint.
|
||||
///
|
||||
/// Services depend on this rather than on either concrete transport, so adding a mode later is a
|
||||
/// change in one place instead of in every feature that talks to a node.
|
||||
public struct NodeTransportRouter: NodeTransport {
|
||||
private let direct: any NodeTransport
|
||||
private let relay: any NodeTransport
|
||||
|
||||
public init(direct: any NodeTransport, relay: any NodeTransport) {
|
||||
self.direct = direct
|
||||
self.relay = relay
|
||||
}
|
||||
|
||||
public func send(
|
||||
_ route: UpstreamRoute,
|
||||
instanceID: UUID,
|
||||
endpoint: InstanceEndpoint
|
||||
) async throws -> UpstreamResponse {
|
||||
switch endpoint {
|
||||
case .direct:
|
||||
return try await direct.send(route, instanceID: instanceID, endpoint: endpoint)
|
||||
case .relay:
|
||||
return try await relay.send(route, instanceID: instanceID, endpoint: endpoint)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The existing direct path, unchanged.
|
||||
///
|
||||
/// It is a thin adapter rather than a rewrite: the code path that reaches a node on the local network
|
||||
/// today is the one users already depend on, and a refactor that changed its behaviour would be a
|
||||
/// regression disguised as tidying.
|
||||
public struct DirectTransport: NodeTransport {
|
||||
private let client: any SimAdminClientProtocol
|
||||
private let sessions: InstanceSessionStore
|
||||
private let credentials: (any CredentialStore)?
|
||||
|
||||
public init(
|
||||
client: any SimAdminClientProtocol,
|
||||
sessions: InstanceSessionStore,
|
||||
credentials: (any CredentialStore)? = nil
|
||||
) {
|
||||
self.client = client
|
||||
self.sessions = sessions
|
||||
self.credentials = credentials
|
||||
}
|
||||
|
||||
public func send(
|
||||
_ route: UpstreamRoute,
|
||||
instanceID: UUID,
|
||||
endpoint: InstanceEndpoint
|
||||
) async throws -> UpstreamResponse {
|
||||
guard let origin = endpoint.directOrigin else {
|
||||
// Reaching here means a relay instance was handed to the direct path, which is a wiring
|
||||
// bug rather than a network condition: fail loudly instead of dialing nothing.
|
||||
throw UpstreamError.invalidRequest
|
||||
}
|
||||
var cookie = await sessions.cookie(for: instanceID, origin: origin)
|
||||
do {
|
||||
return try await client.send(route, baseURL: origin, cookie: cookie)
|
||||
} catch UpstreamError.unauthorized, UpstreamError.forbidden {
|
||||
// A node whose login endpoints are unreachable (an old build, or one with protection
|
||||
// off) must not turn every read into a failed login attempt; the retry below is what
|
||||
// makes the second call happen only when credentials actually exist.
|
||||
guard let credentials, let password = try credentials.get(instanceID: instanceID),
|
||||
!password.isEmpty
|
||||
else {
|
||||
throw UpstreamError.unauthorized
|
||||
}
|
||||
let service = InstanceSessionService(store: sessions, client: client)
|
||||
let instance = Instance(
|
||||
id: instanceID,
|
||||
name: "",
|
||||
endpoint: endpoint,
|
||||
createdAt: Date(),
|
||||
updatedAt: Date()
|
||||
)
|
||||
let result = try await service.login(instance, password: password)
|
||||
guard result.authenticated else { throw UpstreamError.unauthorized }
|
||||
cookie = await sessions.cookie(for: instanceID, origin: origin)
|
||||
return try await client.send(route, baseURL: origin, cookie: cookie)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The relay path: build an envelope, sign it, encrypt it, post it, then verify and decrypt the
|
||||
/// answer.
|
||||
///
|
||||
/// It never touches a cookie and never sees a node password. The node's agent holds that credential
|
||||
/// and logs in to its own loopback SimAdmin, which is what makes "the phone has no node password"
|
||||
/// true rather than merely stated.
|
||||
public struct RelayTransport: NodeTransport {
|
||||
/// Resolved per send rather than held, so a transport built before pairing still uses the keys
|
||||
/// the node actually paired with. Holding a copy would mean a pairing done after the transport
|
||||
/// was constructed signs with keys the node has never seen.
|
||||
private let identity: @Sendable () throws -> DeviceIdentity
|
||||
private let session: URLSession
|
||||
private let maximumBytes: Int
|
||||
private let now: @Sendable () -> Date
|
||||
|
||||
public init(
|
||||
identity: @escaping @Sendable () throws -> DeviceIdentity,
|
||||
session: URLSession = .shared,
|
||||
maximumBytes: Int = 262_144,
|
||||
now: @escaping @Sendable () -> Date = { Date() }
|
||||
) {
|
||||
self.identity = identity
|
||||
self.session = session
|
||||
self.maximumBytes = maximumBytes
|
||||
self.now = now
|
||||
}
|
||||
|
||||
public init(
|
||||
identity: DeviceIdentity,
|
||||
session: URLSession = .shared,
|
||||
maximumBytes: Int = 262_144,
|
||||
now: @escaping @Sendable () -> Date = { Date() }
|
||||
) {
|
||||
self.init(identity: { identity }, session: session, maximumBytes: maximumBytes, now: now)
|
||||
}
|
||||
|
||||
public func send(
|
||||
_ route: UpstreamRoute,
|
||||
instanceID: UUID,
|
||||
endpoint: InstanceEndpoint
|
||||
) async throws -> UpstreamResponse {
|
||||
guard let relay = endpoint.relay else { throw UpstreamError.invalidRequest }
|
||||
guard relay.relayBaseURL.scheme == "https" else {
|
||||
// Plain HTTP to a relay would make the endpoint-to-endpoint encryption decorative: a
|
||||
// third party could substitute a different ciphertext, and nothing above would notice.
|
||||
throw UpstreamError.invalidRequest
|
||||
}
|
||||
guard let requestBody = try? Self.encode(route: route) else {
|
||||
throw UpstreamError.invalidRequest
|
||||
}
|
||||
_ = instanceID
|
||||
guard let identity = try? identity() else {
|
||||
throw UpstreamError.invalidRequest
|
||||
}
|
||||
|
||||
// The ephemeral key pair is per request and its private half is kept only until the answer
|
||||
// is decrypted. The response is encrypted to this key, so the two directions never share a
|
||||
// secret and the phone's long-term X25519 key is not needed to read an answer.
|
||||
let ephemeral = Curve25519.KeyAgreement.PrivateKey()
|
||||
let requestID = UUID().uuidString.lowercased()
|
||||
let timestamp = UInt64(now().timeIntervalSince1970)
|
||||
|
||||
let shared = try RelayWire.sharedSecret(
|
||||
privateKey: ephemeral,
|
||||
peerPublic: relay.agentKxKey
|
||||
)
|
||||
let (key, iv) = try RelayWire.deriveKey(
|
||||
shared: shared,
|
||||
nodeID: relay.nodeID,
|
||||
requestID: requestID,
|
||||
response: false
|
||||
)
|
||||
let sealed = try RelayWire.seal(requestBody, key: key, iv: iv)
|
||||
|
||||
var envelope = RelayWire.Envelope(
|
||||
node: relay.nodeID,
|
||||
req: requestID,
|
||||
app: relay.deviceID,
|
||||
ts: timestamp,
|
||||
ek: ephemeral.publicKey.rawRepresentation,
|
||||
p: sealed
|
||||
)
|
||||
try RelayWire.signRequest(&envelope, privateKey: identity.signingKey)
|
||||
|
||||
let answer = try await post(envelope, relay: relay)
|
||||
return try decrypt(answer, relay: relay, requestID: requestID, ephemeral: ephemeral)
|
||||
}
|
||||
|
||||
// MARK: - Inner request
|
||||
|
||||
/// Builds the inner payload. The path is the route's own path, query string included, so the
|
||||
/// agent never assembles one from parts and there is no traversal surface from the relay.
|
||||
///
|
||||
/// A dangerous write carries an intent computed here, from the exact bytes about to be sent. The
|
||||
/// agent recomputes it and refuses a mismatch, so a relay cannot edit the recipient of an SMS in
|
||||
/// flight and keep the confirmation valid. The intent is produced at the moment the user's
|
||||
/// gesture is already behind us — this method is only called for a request the UI has decided to
|
||||
/// make — which is what gives it any meaning at all.
|
||||
static func encode(route: UpstreamRoute) throws -> Data {
|
||||
let body = route.body
|
||||
var inner = RelayWire.InnerRequest(m: route.method, p: route.path, body: body)
|
||||
if route.requiresConfirmation {
|
||||
inner.intent = try RelayWire.intentDigest(
|
||||
method: route.method,
|
||||
path: route.path,
|
||||
body: body
|
||||
)
|
||||
}
|
||||
let encoder = JSONEncoder()
|
||||
encoder.outputFormatting = [.sortedKeys]
|
||||
return try encoder.encode(inner)
|
||||
}
|
||||
|
||||
// MARK: - HTTP
|
||||
|
||||
private func post(_ envelope: RelayWire.Envelope, relay: RelayEndpoint) async throws -> RelayWire.Envelope {
|
||||
guard let url = URL(string: relay.relayBaseURL.absoluteString + "/v1/request") else {
|
||||
throw UpstreamError.invalidRequest
|
||||
}
|
||||
var request = URLRequest(url: url, timeoutInterval: 45)
|
||||
request.httpMethod = "POST"
|
||||
request.setValue("application/json", forHTTPHeaderField: "content-type")
|
||||
request.setValue("application/json", forHTTPHeaderField: "accept")
|
||||
request.setValue("Bearer \(relay.deviceToken)", forHTTPHeaderField: "authorization")
|
||||
request.httpBody = try JSONEncoder().encode(envelope)
|
||||
|
||||
let data: Data
|
||||
let response: URLResponse
|
||||
do {
|
||||
(data, response) = try await session.data(for: request)
|
||||
} catch let error as URLError where error.code == .timedOut {
|
||||
throw UpstreamError.relayTimeout
|
||||
} catch {
|
||||
throw UpstreamError.relayUnreachable
|
||||
}
|
||||
guard let http = response as? HTTPURLResponse, data.count <= maximumBytes else {
|
||||
throw UpstreamError.invalidResponse
|
||||
}
|
||||
if http.statusCode != 200 {
|
||||
throw Self.problem(from: data, status: http.statusCode)
|
||||
}
|
||||
guard let envelope = try? JSONDecoder().decode(RelayWire.Envelope.self, from: data) else {
|
||||
throw UpstreamError.invalidResponse
|
||||
}
|
||||
return envelope
|
||||
}
|
||||
|
||||
/// Maps a relay ProblemDetails document to a typed error.
|
||||
///
|
||||
/// The four classes the design calls for are kept apart on purpose: "the relay is unreachable",
|
||||
/// "the agent is offline", "the envelope was refused" and "the node returned an error" lead to
|
||||
/// four different user actions, and folding them into one "request failed" is what makes relay
|
||||
/// problems unactionable.
|
||||
static func problem(from data: Data, status: Int) -> UpstreamError {
|
||||
let code = (try? JSONSerialization.jsonObject(with: data) as? [String: Any])
|
||||
.flatMap { $0?["code"] as? String }
|
||||
.flatMap(RelayErrorCode.init(rawValue:))
|
||||
switch code {
|
||||
case .unauthorized:
|
||||
// The relay rejected this phone's bearer. Nothing the node can do about it, and retrying
|
||||
// with the same token will fail the same way.
|
||||
return .relayRejectedDevice
|
||||
case .nodeUnknown:
|
||||
return .relayNodeUnknown
|
||||
case .agentOffline:
|
||||
return .agentOffline
|
||||
case .mailboxFull:
|
||||
return .nodeBusy
|
||||
case .agentTimeout:
|
||||
return .agentTimeout
|
||||
case .badEnvelope:
|
||||
return .relayBadEnvelope
|
||||
case .payloadTooLarge:
|
||||
return .payloadTooLarge
|
||||
case .rateLimited:
|
||||
return .relayRateLimited
|
||||
case .sessionExpired, .badChallenge:
|
||||
return .agentOffline
|
||||
case .internalError, .none:
|
||||
return status >= 500 ? .relayUnreachable : .invalidResponse
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Response
|
||||
|
||||
private func decrypt(
|
||||
_ envelope: RelayWire.Envelope,
|
||||
relay: RelayEndpoint,
|
||||
requestID: String,
|
||||
ephemeral: Curve25519.KeyAgreement.PrivateKey
|
||||
) throws -> UpstreamResponse {
|
||||
guard envelope.req == requestID, envelope.node == relay.nodeID else {
|
||||
// The relay answered a different question. Since the signature covers both fields, a
|
||||
// mismatch here means the answer was not produced for this request at all.
|
||||
throw UpstreamError.relayResponseMismatch
|
||||
}
|
||||
let signingKey: Curve25519.Signing.PublicKey
|
||||
do {
|
||||
signingKey = try Curve25519.Signing.PublicKey(rawRepresentation: relay.agentSigningKey)
|
||||
} catch {
|
||||
throw UpstreamError.relayResponseUnverifiable
|
||||
}
|
||||
do {
|
||||
try RelayWire.verifyResponse(envelope, publicKey: signingKey)
|
||||
} catch {
|
||||
// An answer the node did not sign is not an answer. This is the check that makes the
|
||||
// relay's inability to forge responses a fact rather than a claim.
|
||||
throw UpstreamError.relayResponseUnverifiable
|
||||
}
|
||||
let shared = try RelayWire.sharedSecret(privateKey: ephemeral, peerPublic: envelope.ek)
|
||||
let (key, iv) = try RelayWire.deriveKey(
|
||||
shared: shared,
|
||||
nodeID: relay.nodeID,
|
||||
requestID: requestID,
|
||||
response: true
|
||||
)
|
||||
let plaintext: Data
|
||||
do {
|
||||
plaintext = try RelayWire.open(envelope.p, key: key, iv: iv)
|
||||
} catch {
|
||||
throw UpstreamError.relayResponseUnverifiable
|
||||
}
|
||||
guard let inner = try? JSONDecoder().decode(RelayWire.InnerResponse.self, from: plaintext) else {
|
||||
throw UpstreamError.invalidResponse
|
||||
}
|
||||
|
||||
let outcome = inner.outcome.flatMap(AgentOutcome.init(rawValue:))
|
||||
switch outcome {
|
||||
case .ok, .none:
|
||||
return UpstreamResponse(status: inner.status, data: inner.body ?? Data())
|
||||
case .nodeAuthFailed:
|
||||
// Nothing the phone can do: the node's agent is misconfigured. Distinguished from an
|
||||
// upstream error because the remedy is on the node, not in the app.
|
||||
throw UpstreamError.nodeAuthFailed
|
||||
case .policyDenied, .unknownDevice:
|
||||
throw UpstreamError.relayPolicyDenied
|
||||
case .confirmationMissing, .confirmationMismatch:
|
||||
throw UpstreamError.confirmationRejected
|
||||
case .expired, .replay:
|
||||
// The envelope was stale or already used. Both are clock or retry problems, and both
|
||||
// resolve by re-issuing the request with a fresh id and timestamp.
|
||||
throw UpstreamError.envelopeExpired
|
||||
case .rateLimited:
|
||||
throw UpstreamError.nodeRateLimited
|
||||
case .payloadTooLarge:
|
||||
throw UpstreamError.payloadTooLarge
|
||||
case .badEnvelope, .badSignature:
|
||||
throw UpstreamError.envelopeRejected
|
||||
case .upstreamError:
|
||||
// The node answered, but its local SimAdmin did not. The status is still useful: it is
|
||||
// the only branch where a 4xx/5xx from the node reaches the caller.
|
||||
return UpstreamResponse(status: inner.status, data: inner.body ?? Data())
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension Data {
|
||||
/// Lowercase hex, which is the spelling the relay's bearer-token comparison expects.
|
||||
var hexString: String { map { String(format: "%02x", $0) }.joined() }
|
||||
}
|
||||
@@ -0,0 +1,380 @@
|
||||
import CryptoKit
|
||||
import Foundation
|
||||
|
||||
/// The relay envelope: what is signed, what is encrypted, and in what order.
|
||||
///
|
||||
/// This is the third implementation of a format that Go and Node already implement, and the three
|
||||
/// share no code on purpose. `contracts/test-vectors.json` is recomputed here by `RelayWireTests`,
|
||||
/// so a byte-level disagreement shows up as a failing test rather than as a signature failure in
|
||||
/// the field — where the only symptom is "the node refused the request" with no way to tell which
|
||||
/// of the three encoders drifted.
|
||||
///
|
||||
/// The relay is not trusted, so signing and encryption are separate concerns: Ed25519 covers a
|
||||
/// canonical byte encoding of the routing fields plus the ciphertext, which stops a compromised
|
||||
/// relay from retargeting a request at another node or swapping a response between two in-flight
|
||||
/// requests. AES-256-GCM then carries the payload under keys from an ephemeral X25519 exchange.
|
||||
public enum RelayWire {
|
||||
public static let version: UInt64 = 1
|
||||
public static let suite = "X25519-ED25519-AES256GCM-HKDFSHA256"
|
||||
|
||||
static let domainRequest = "msa-relay-v1-req"
|
||||
static let domainResponse = "msa-relay-v1-resp"
|
||||
private static let label = "msa-relay-v1"
|
||||
|
||||
public static let keyBytes = 32
|
||||
public static let ivBytes = 12
|
||||
public static let tagBytes = 16
|
||||
|
||||
public enum Failure: Error, Equatable {
|
||||
case unsupportedVersion(UInt64)
|
||||
case unsupportedSuite(String)
|
||||
case badKeyLength(field: String, got: Int)
|
||||
case missingIdentityField
|
||||
case signatureDoesNotVerify
|
||||
case ciphertextFailedToAuthenticate
|
||||
case peerKeyUnusable
|
||||
case invalidResponseBody
|
||||
}
|
||||
|
||||
// MARK: - Envelope
|
||||
|
||||
/// The outer, relay-visible structure. The relay routes on `node` and correlates on `req`, and
|
||||
/// can read nothing else: `ek` is a public key, `p` is ciphertext, and `s` covers everything.
|
||||
public struct Envelope: Codable, Equatable, Sendable {
|
||||
public var v: UInt64
|
||||
public var node: String
|
||||
public var req: String
|
||||
/// The paired device id. Present on requests only: it is signed, so the relay cannot
|
||||
/// relabel one phone's traffic as another's, and the agent uses it to pick the key to
|
||||
/// verify against.
|
||||
public var app: String?
|
||||
public var ts: UInt64
|
||||
/// X25519 public key: the phone's per-request ephemeral on a request, the agent's
|
||||
/// per-response ephemeral on a response.
|
||||
public var ek: Data
|
||||
public var alg: String
|
||||
/// AES-256-GCM ciphertext with the 16-byte tag appended.
|
||||
public var p: Data
|
||||
public var s: Data?
|
||||
|
||||
public init(
|
||||
v: UInt64 = RelayWire.version,
|
||||
node: String,
|
||||
req: String,
|
||||
app: String? = nil,
|
||||
ts: UInt64,
|
||||
ek: Data,
|
||||
alg: String = RelayWire.suite,
|
||||
p: Data,
|
||||
s: Data? = nil
|
||||
) {
|
||||
self.v = v
|
||||
self.node = node
|
||||
self.req = req
|
||||
self.app = app
|
||||
self.ts = ts
|
||||
self.ek = ek
|
||||
self.alg = alg
|
||||
self.p = p
|
||||
self.s = s
|
||||
}
|
||||
|
||||
/// The wire form is base64 for the byte fields, and the key set is fixed: the relay parses
|
||||
/// these same names, and the Go agent's struct tags are the authority for them.
|
||||
private enum CodingKeys: String, CodingKey {
|
||||
case v, node, req, app, ts, ek, alg, p, s
|
||||
}
|
||||
|
||||
public init(from decoder: Decoder) throws {
|
||||
let container = try decoder.container(keyedBy: CodingKeys.self)
|
||||
v = try container.decode(UInt64.self, forKey: .v)
|
||||
node = try container.decode(String.self, forKey: .node)
|
||||
req = try container.decode(String.self, forKey: .req)
|
||||
app = try container.decodeIfPresent(String.self, forKey: .app)
|
||||
ts = try container.decode(UInt64.self, forKey: .ts)
|
||||
alg = try container.decode(String.self, forKey: .alg)
|
||||
ek = try Self.decodeBase64(container.decode(String.self, forKey: .ek), field: "ek")
|
||||
p = try Self.decodeBase64(container.decode(String.self, forKey: .p), field: "p")
|
||||
let signature = try container.decodeIfPresent(String.self, forKey: .s) ?? ""
|
||||
s = signature.isEmpty ? nil : try Self.decodeBase64(signature, field: "s")
|
||||
}
|
||||
|
||||
public func encode(to encoder: Encoder) throws {
|
||||
var container = encoder.container(keyedBy: CodingKeys.self)
|
||||
try container.encode(v, forKey: .v)
|
||||
try container.encode(node, forKey: .node)
|
||||
try container.encode(req, forKey: .req)
|
||||
try container.encodeIfPresent(app, forKey: .app)
|
||||
try container.encode(ts, forKey: .ts)
|
||||
try container.encode(ek.base64EncodedString(), forKey: .ek)
|
||||
try container.encode(alg, forKey: .alg)
|
||||
try container.encode(p.base64EncodedString(), forKey: .p)
|
||||
if let s {
|
||||
try container.encode(s.base64EncodedString(), forKey: .s)
|
||||
}
|
||||
}
|
||||
|
||||
/// Strict base64: Go's decoder silently accepts some non-canonical forms, and a signature
|
||||
/// must be computed over exactly the bytes the sender used, so a lenient decode here would
|
||||
/// turn a malformed envelope into a valid-looking one.
|
||||
private static func decodeBase64(_ value: String, field: String) throws -> Data {
|
||||
guard let data = Data(base64Encoded: value, options: []) else {
|
||||
throw Failure.invalidResponseBody
|
||||
}
|
||||
return data
|
||||
}
|
||||
}
|
||||
|
||||
/// The decrypted request payload.
|
||||
public struct InnerRequest: Codable, Equatable, Sendable {
|
||||
/// Upstream method. The agent matches it against its policy before dialing anything.
|
||||
public var m: String
|
||||
/// Upstream path, already carrying any query string. The agent forwards it verbatim and
|
||||
/// never assembles one from parts, so there is no path-traversal surface from the relay.
|
||||
public var p: String
|
||||
/// sha256 over the method, path and canonical body, produced by an explicit user gesture.
|
||||
/// Mandatory for every entry in the agent's `dangerous` list and absent for reads.
|
||||
public var intent: Data?
|
||||
/// Raw upstream body, forwarded unchanged. Kept as bytes so the agent never re-serialises
|
||||
/// JSON and thereby never changes what the intent was computed over.
|
||||
public var body: Data?
|
||||
|
||||
public init(m: String, p: String, intent: Data? = nil, body: Data? = nil) {
|
||||
self.m = m
|
||||
self.p = p
|
||||
self.intent = intent
|
||||
self.body = body
|
||||
}
|
||||
|
||||
private enum CodingKeys: String, CodingKey { case m, p, intent, body }
|
||||
|
||||
public init(from decoder: Decoder) throws {
|
||||
let container = try decoder.container(keyedBy: CodingKeys.self)
|
||||
m = try container.decode(String.self, forKey: .m)
|
||||
p = try container.decode(String.self, forKey: .p)
|
||||
intent = try container.decodeIfPresent(Data.self, forKey: .intent)
|
||||
body = try container.decodeIfPresent(Data.self, forKey: .body)
|
||||
}
|
||||
|
||||
public func encode(to encoder: Encoder) throws {
|
||||
var container = encoder.container(keyedBy: CodingKeys.self)
|
||||
try container.encode(m, forKey: .m)
|
||||
try container.encode(p, forKey: .p)
|
||||
if let intent { try container.encode(intent, forKey: .intent) }
|
||||
if let body { try container.encode(body, forKey: .body) }
|
||||
}
|
||||
}
|
||||
|
||||
/// The decrypted response payload. Status lives inside the ciphertext so the relay cannot
|
||||
/// rewrite a failure into a success.
|
||||
public struct InnerResponse: Codable, Equatable, Sendable {
|
||||
public var status: Int
|
||||
/// The agent's own classification of what happened. Inside the ciphertext for the same
|
||||
/// reason as `status`: the relay is not entitled to know why a command failed, and the
|
||||
/// phone needs to tell the user what to do about it.
|
||||
public var outcome: String?
|
||||
public var body: Data?
|
||||
|
||||
public init(status: Int, outcome: String? = nil, body: Data? = nil) {
|
||||
self.status = status
|
||||
self.outcome = outcome
|
||||
self.body = body
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Canonical bytes
|
||||
|
||||
/// The signing input, which is not JSON.
|
||||
///
|
||||
/// Fixed field order, each field prefixed with its length as uint32be. The two integers carry
|
||||
/// an explicit `00000008` length too — Go's `writeUint64` delegates to `writeBytes`, so a
|
||||
/// version that emitted them bare would produce a byte string that looks identical in a hex
|
||||
/// dump's payload region and still fails to verify.
|
||||
///
|
||||
/// `ek` and `p` contribute their raw decoded bytes, never their base64 text, so a relay cannot
|
||||
/// re-encode them differently.
|
||||
public static func canonical(_ envelope: Envelope, response: Bool) throws -> Data {
|
||||
guard envelope.v == version else { throw Failure.unsupportedVersion(envelope.v) }
|
||||
guard envelope.alg == suite else { throw Failure.unsupportedSuite(envelope.alg) }
|
||||
guard !envelope.node.trimmed.isEmpty, !envelope.req.trimmed.isEmpty else {
|
||||
throw Failure.missingIdentityField
|
||||
}
|
||||
guard envelope.ek.count == keyBytes else {
|
||||
throw Failure.badKeyLength(field: "ek", got: envelope.ek.count)
|
||||
}
|
||||
if !response {
|
||||
guard let app = envelope.app, !app.trimmed.isEmpty else { throw Failure.missingIdentityField }
|
||||
}
|
||||
|
||||
var out = Data()
|
||||
out.append(contentsOf: Array((response ? domainResponse : domainRequest).utf8))
|
||||
out.append(0)
|
||||
appendLengthPrefixed(&out, uint64be(envelope.v))
|
||||
appendLengthPrefixed(&out, Data(envelope.node.utf8))
|
||||
appendLengthPrefixed(&out, Data(envelope.req.utf8))
|
||||
if !response, let app = envelope.app {
|
||||
appendLengthPrefixed(&out, Data(app.utf8))
|
||||
}
|
||||
appendLengthPrefixed(&out, uint64be(envelope.ts))
|
||||
appendLengthPrefixed(&out, envelope.ek)
|
||||
appendLengthPrefixed(&out, envelope.p)
|
||||
return out
|
||||
}
|
||||
|
||||
private static func appendLengthPrefixed(_ out: inout Data, _ value: Data) {
|
||||
var length = UInt32(value.count).bigEndian
|
||||
withUnsafeBytes(of: &length) { out.append(contentsOf: $0) }
|
||||
out.append(value)
|
||||
}
|
||||
|
||||
private static func uint64be(_ value: UInt64) -> Data {
|
||||
var big = value.bigEndian
|
||||
return withUnsafeBytes(of: &big) { Data($0) }
|
||||
}
|
||||
|
||||
// MARK: - Signing
|
||||
|
||||
public static func signRequest(_ envelope: inout Envelope, privateKey: Curve25519.Signing.PrivateKey) throws {
|
||||
envelope.s = try privateKey.signature(for: canonical(envelope, response: false))
|
||||
}
|
||||
|
||||
public static func verifyRequest(_ envelope: Envelope, publicKey: Curve25519.Signing.PublicKey) throws {
|
||||
try verify(envelope, publicKey: publicKey, response: false)
|
||||
}
|
||||
|
||||
public static func verifyResponse(_ envelope: Envelope, publicKey: Curve25519.Signing.PublicKey) throws {
|
||||
try verify(envelope, publicKey: publicKey, response: true)
|
||||
}
|
||||
|
||||
private static func verify(
|
||||
_ envelope: Envelope,
|
||||
publicKey: Curve25519.Signing.PublicKey,
|
||||
response: Bool
|
||||
) throws {
|
||||
let canonicalBytes = try canonical(envelope, response: response)
|
||||
guard let signature = envelope.s, signature.count == 64 else {
|
||||
throw Failure.signatureDoesNotVerify
|
||||
}
|
||||
guard publicKey.isValidSignature(signature, for: canonicalBytes) else {
|
||||
throw Failure.signatureDoesNotVerify
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Key agreement and AEAD
|
||||
|
||||
/// HKDF-SHA256, extract then expand.
|
||||
public static func hkdf(secret: Data, salt: Data, info: Data, length: Int) throws -> Data {
|
||||
guard length > 0, length <= 255 * SHA256.byteCount else {
|
||||
throw Failure.badKeyLength(field: "hkdf", got: length)
|
||||
}
|
||||
let key = HKDF<SHA256>.deriveKey(
|
||||
inputKeyMaterial: SymmetricKey(data: secret),
|
||||
salt: salt,
|
||||
info: info,
|
||||
outputByteCount: length
|
||||
)
|
||||
return key.withUnsafeBytes { Data($0) }
|
||||
}
|
||||
|
||||
/// X25519, rejecting the all-zero output that a peer key chosen to force a known shared secret
|
||||
/// would produce.
|
||||
public static func sharedSecret(
|
||||
privateKey: Curve25519.KeyAgreement.PrivateKey,
|
||||
peerPublic: Data
|
||||
) throws -> Data {
|
||||
guard peerPublic.count == keyBytes else {
|
||||
throw Failure.badKeyLength(field: "peerPublic", got: peerPublic.count)
|
||||
}
|
||||
guard let publicKey = try? Curve25519.KeyAgreement.PublicKey(rawRepresentation: peerPublic) else {
|
||||
throw Failure.peerKeyUnusable
|
||||
}
|
||||
do {
|
||||
let secret = try privateKey.sharedSecretFromKeyAgreement(with: publicKey)
|
||||
return secret.withUnsafeBytes { Data($0) }
|
||||
} catch {
|
||||
throw Failure.peerKeyUnusable
|
||||
}
|
||||
}
|
||||
|
||||
/// The AEAD key and IV for one direction of one request.
|
||||
///
|
||||
/// The salt binds the node id, so a shared secret that somehow repeats across nodes still
|
||||
/// yields different keys. The IV is derived from the request id and the direction rather than
|
||||
/// being a fixed zero block: a fixed IV is only safe while every message uses a fresh key, and
|
||||
/// that invariant is exactly what a later "reuse the session key for a batch" optimisation
|
||||
/// would quietly break.
|
||||
public static func deriveKey(
|
||||
shared: Data,
|
||||
nodeID: String,
|
||||
requestID: String,
|
||||
response: Bool
|
||||
) throws -> (key: SymmetricKey, iv: Data) {
|
||||
guard shared.count == keyBytes else {
|
||||
throw Failure.badKeyLength(field: "shared", got: shared.count)
|
||||
}
|
||||
let salt = Data("\(label):\(nodeID):\(requestID)".utf8)
|
||||
let keyBytes = try hkdf(
|
||||
secret: shared,
|
||||
salt: salt,
|
||||
info: Data((response ? "\(label)-resp" : "\(label)-req").utf8),
|
||||
length: self.keyBytes
|
||||
)
|
||||
let iv = try hkdf(
|
||||
secret: shared,
|
||||
salt: Data(requestID.utf8),
|
||||
info: Data((response ? "iv-resp" : "iv-req").utf8),
|
||||
length: ivBytes
|
||||
)
|
||||
return (SymmetricKey(data: keyBytes), iv)
|
||||
}
|
||||
|
||||
/// Encrypts with AES-256-GCM. The tag is appended to the ciphertext, matching Node's
|
||||
/// `cipher.getAuthTag()` concatenation and Go's `gcm.Seal`.
|
||||
public static func seal(_ plaintext: Data, key: SymmetricKey, iv: Data) throws -> Data {
|
||||
guard iv.count == ivBytes else { throw Failure.badKeyLength(field: "iv", got: iv.count) }
|
||||
let nonce = try AES.GCM.Nonce(data: iv)
|
||||
let box = try AES.GCM.seal(plaintext, using: key, nonce: nonce)
|
||||
return box.ciphertext + box.tag
|
||||
}
|
||||
|
||||
/// Decrypts and authenticates. A failure is terminal for the request, not a retry: a wrong
|
||||
/// key, a torn payload and a forged payload are indistinguishable here, and all three mean do
|
||||
/// not act.
|
||||
public static func open(_ ciphertext: Data, key: SymmetricKey, iv: Data) throws -> Data {
|
||||
guard iv.count == ivBytes else { throw Failure.badKeyLength(field: "iv", got: iv.count) }
|
||||
guard ciphertext.count >= tagBytes else { throw Failure.ciphertextFailedToAuthenticate }
|
||||
let nonce = try AES.GCM.Nonce(data: iv)
|
||||
let body = ciphertext.prefix(ciphertext.count - tagBytes)
|
||||
let tag = ciphertext.suffix(tagBytes)
|
||||
let box = try AES.GCM.SealedBox(nonce: nonce, ciphertext: body, tag: tag)
|
||||
do {
|
||||
return try AES.GCM.open(box, using: key)
|
||||
} catch {
|
||||
throw Failure.ciphertextFailedToAuthenticate
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Confirmation intent
|
||||
|
||||
/// sha256(method | path | canonical body): the value a phone sends to prove a human confirmed
|
||||
/// this exact write.
|
||||
///
|
||||
/// The agent recomputes it from the request it is about to forward, so a relay cannot edit the
|
||||
/// recipient of an SMS in flight and keep the confirmation valid. The body is canonicalised
|
||||
/// the same way the web console does it, which is why `CanonicalJSON` exists as a shared,
|
||||
/// test-vectored implementation rather than a call to `JSONSerialization`.
|
||||
public static func intentDigest(method: String, path: String, body: Data?) throws -> Data {
|
||||
let canonicalBody = try CanonicalJSON.canonicalize(body ?? Data())
|
||||
var input = Data()
|
||||
input.append(contentsOf: Array(method.trimmingCharacters(in: .whitespaces).uppercased().utf8))
|
||||
input.append(UInt8(ascii: "|"))
|
||||
input.append(contentsOf: Array(path.utf8))
|
||||
input.append(UInt8(ascii: "|"))
|
||||
input.append(canonicalBody)
|
||||
return Data(SHA256.hash(data: input))
|
||||
}
|
||||
}
|
||||
|
||||
private extension String {
|
||||
var trimmed: String { trimmingCharacters(in: .whitespacesAndNewlines) }
|
||||
}
|
||||
@@ -28,29 +28,54 @@ public struct ConnectionResult: Equatable, Sendable {
|
||||
public let status: ConnectionStatus
|
||||
public let requestLatencyMilliseconds: Int?
|
||||
public let checkedAt: Date
|
||||
/// Why the probe ended where it did.
|
||||
///
|
||||
/// Kept alongside the status rather than folded into it because the status vocabulary is five
|
||||
/// values and the failure vocabulary is much larger: in relay mode "the relay is unreachable",
|
||||
/// "the agent is offline", "the envelope was refused" and "the node returned an error" are four
|
||||
/// different user actions, and a single `.offline` cannot say which one happened.
|
||||
public let error: UpstreamError?
|
||||
|
||||
public init(
|
||||
status: ConnectionStatus,
|
||||
requestLatencyMilliseconds: Int? = nil,
|
||||
checkedAt: Date
|
||||
checkedAt: Date,
|
||||
error: UpstreamError? = nil
|
||||
) {
|
||||
self.status = status
|
||||
self.requestLatencyMilliseconds = requestLatencyMilliseconds
|
||||
self.checkedAt = checkedAt
|
||||
self.error = error
|
||||
}
|
||||
|
||||
/// How old this reading is, for the freshness vocabulary. A relay reading is inherently older
|
||||
/// than a direct one, and saying so is the difference between "online" meaning now and meaning
|
||||
/// forty seconds ago.
|
||||
public var freshness: SnapshotFreshness {
|
||||
SnapshotFreshness.classify(age: Date().timeIntervalSince(checkedAt))
|
||||
}
|
||||
}
|
||||
|
||||
public struct ConnectionProbe: Sendable {
|
||||
private let client: any SimAdminClientProtocol
|
||||
private let transport: any NodeTransport
|
||||
|
||||
public init(transport: any NodeTransport) {
|
||||
self.transport = transport
|
||||
}
|
||||
|
||||
/// Direct-mode construction, kept for the existing call sites and tests.
|
||||
public init(client: any SimAdminClientProtocol) {
|
||||
self.client = client
|
||||
self.init(transport: DirectTransport(client: client, sessions: InstanceSessionStore()))
|
||||
}
|
||||
|
||||
public func test(_ instance: Instance) async throws -> ConnectionResult {
|
||||
let startedAt = DispatchTime.now()
|
||||
do {
|
||||
let response = try await client.send(.health, baseURL: instance.origin, cookie: nil)
|
||||
let response = try await transport.send(
|
||||
.health,
|
||||
instanceID: instance.id,
|
||||
endpoint: instance.endpoint
|
||||
)
|
||||
let latency = Self.elapsedMilliseconds(since: startedAt)
|
||||
if response.status == 401 || response.status == 403 {
|
||||
return ConnectionResult(
|
||||
@@ -66,26 +91,42 @@ public struct ConnectionProbe: Sendable {
|
||||
)
|
||||
} catch {
|
||||
let latency = Self.elapsedMilliseconds(since: startedAt)
|
||||
switch error {
|
||||
case UpstreamError.unauthorized:
|
||||
return ConnectionResult(
|
||||
status: .authRequired,
|
||||
requestLatencyMilliseconds: latency,
|
||||
checkedAt: Date()
|
||||
)
|
||||
case UpstreamError.timeout, is URLError:
|
||||
return ConnectionResult(
|
||||
status: .offline,
|
||||
requestLatencyMilliseconds: latency,
|
||||
checkedAt: Date()
|
||||
)
|
||||
default:
|
||||
return ConnectionResult(
|
||||
status: .degraded,
|
||||
requestLatencyMilliseconds: latency,
|
||||
checkedAt: Date()
|
||||
)
|
||||
}
|
||||
let upstream = error as? UpstreamError
|
||||
return ConnectionResult(
|
||||
status: Self.status(for: upstream, error: error),
|
||||
requestLatencyMilliseconds: latency,
|
||||
checkedAt: Date(),
|
||||
error: upstream
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/// Maps a failure onto the five-value status vocabulary the list already uses, while the typed
|
||||
/// error travels alongside it for the detail view.
|
||||
///
|
||||
/// The relay-mode cases are mapped rather than collapsed: an offline agent is a node problem the
|
||||
/// user waits out, a rejected envelope is a pairing problem that will never fix itself, and an
|
||||
/// unreachable relay is neither.
|
||||
static func status(for upstream: UpstreamError?, error: Error) -> ConnectionStatus {
|
||||
switch upstream {
|
||||
case .unauthorized:
|
||||
return .authRequired
|
||||
case .timeout, .relayTimeout, .relayUnreachable, .agentOffline, .agentTimeout, .nodeBusy:
|
||||
return .offline
|
||||
case .relayRejectedDevice, .relayNodeUnknown:
|
||||
// The pairing is gone: retrying cannot help, and the user has to pair again.
|
||||
return .offline
|
||||
case .relayPolicyDenied, .confirmationRejected, .envelopeRejected,
|
||||
.envelopeExpired, .relayResponseUnverifiable, .relayResponseMismatch,
|
||||
.relayBadEnvelope, .nodeAuthFailed, .payloadTooLarge:
|
||||
return .degraded
|
||||
case .relayRateLimited, .nodeRateLimited:
|
||||
return .degraded
|
||||
case .invalidRequest, .notSupported, .transportFailed, .invalidResponse, .forbidden:
|
||||
return .degraded
|
||||
case .none:
|
||||
if error is URLError { return .offline }
|
||||
return .degraded
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -9,22 +9,49 @@ enum DefaultContainer {
|
||||
location: documentFileURL("log-center.json")
|
||||
)
|
||||
|
||||
/// The phone's relay identity, shared by every relay transport.
|
||||
///
|
||||
/// It is loaded once rather than per transport: the key pair must be the same one the node
|
||||
/// paired with, and a second load that regenerated it would silently invalidate every pairing.
|
||||
static let deviceIdentities = FileDeviceIdentityStore(
|
||||
location: documentFileURL("device-identity.json")
|
||||
)
|
||||
|
||||
static func documentFileURL(_ name: String) -> URL {
|
||||
let directory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
|
||||
return directory.appendingPathComponent(name)
|
||||
}
|
||||
|
||||
static func makeInstanceRepository() -> FileInstanceRepository {
|
||||
FileInstanceRepository(location: documentFileURL("instances.json"))
|
||||
}
|
||||
|
||||
/// The transport pair every feature service uses: direct on the LAN, relay through the agent.
|
||||
///
|
||||
/// The relay side reads the identity file per request rather than holding a copy: pairing can
|
||||
/// happen after a transport is built, and a held copy would sign with keys the node has never
|
||||
/// seen, which fails as an unreadable request with no useful cause.
|
||||
private static func makeTransport(
|
||||
client: any SimAdminClientProtocol,
|
||||
sessions: InstanceSessionStore
|
||||
) -> NodeTransportRouter {
|
||||
let identities = deviceIdentities
|
||||
return NodeTransportRouter(
|
||||
direct: DirectTransport(client: client, sessions: sessions, credentials: credentials),
|
||||
relay: RelayTransport(identity: { try identities.loadOrCreate() })
|
||||
)
|
||||
}
|
||||
|
||||
@MainActor
|
||||
static func makeFleetModel() -> FleetViewModel {
|
||||
purgeLegacyGrouping()
|
||||
let sessions = InstanceSessionStore()
|
||||
return FleetViewModel(
|
||||
repository: FileInstanceRepository(location: documentFileURL("instances.json")),
|
||||
probe: ConnectionProbe(client: SimAdminClient()),
|
||||
repository: makeInstanceRepository(),
|
||||
probe: ConnectionProbe(transport: makeTransport(client: SimAdminClient(), sessions: sessions)),
|
||||
credentials: credentials,
|
||||
deviceService: DeviceService(
|
||||
client: SimAdminClient(),
|
||||
sessions: InstanceSessionStore(),
|
||||
credentials: credentials
|
||||
transport: makeTransport(client: SimAdminClient(), sessions: sessions)
|
||||
)
|
||||
)
|
||||
}
|
||||
@@ -37,12 +64,11 @@ enum DefaultContainer {
|
||||
|
||||
@MainActor
|
||||
static func makeMessagesModel() -> MessagesViewModel {
|
||||
MessagesViewModel(
|
||||
repository: FileInstanceRepository(location: documentFileURL("instances.json")),
|
||||
let sessions = InstanceSessionStore()
|
||||
return MessagesViewModel(
|
||||
repository: makeInstanceRepository(),
|
||||
service: MessageService(
|
||||
client: SimAdminClient(),
|
||||
sessions: InstanceSessionStore(),
|
||||
credentials: credentials
|
||||
transport: makeTransport(client: SimAdminClient(), sessions: sessions)
|
||||
)
|
||||
)
|
||||
}
|
||||
@@ -50,12 +76,11 @@ enum DefaultContainer {
|
||||
@MainActor
|
||||
static func makeLogsModel(autoRefreshOnAppear: Bool = true) -> LogsViewModel {
|
||||
let store = logStore
|
||||
let sessions = InstanceSessionStore()
|
||||
return LogsViewModel(
|
||||
repository: FileInstanceRepository(location: documentFileURL("instances.json")),
|
||||
repository: makeInstanceRepository(),
|
||||
service: LogCenterService(
|
||||
client: SimAdminClient(),
|
||||
sessions: InstanceSessionStore(),
|
||||
credentials: credentials,
|
||||
transport: makeTransport(client: SimAdminClient(), sessions: sessions),
|
||||
store: store
|
||||
),
|
||||
store: store,
|
||||
@@ -70,14 +95,15 @@ enum DefaultContainer {
|
||||
|
||||
@MainActor
|
||||
static func makeDeviceModel(instance: Instance) -> DeviceViewModel {
|
||||
DeviceViewModel(
|
||||
let sessions = InstanceSessionStore()
|
||||
return DeviceViewModel(
|
||||
instance: instance,
|
||||
service: DeviceService(
|
||||
client: SimAdminClient(),
|
||||
sessions: InstanceSessionStore(),
|
||||
credentials: credentials
|
||||
transport: makeTransport(client: SimAdminClient(), sessions: sessions)
|
||||
),
|
||||
probe: ConnectionProbe(client: SimAdminClient())
|
||||
probe: ConnectionProbe(
|
||||
transport: makeTransport(client: SimAdminClient(), sessions: sessions)
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -21,15 +21,23 @@ public struct InstanceSessionService: Sendable {
|
||||
self.client = client
|
||||
}
|
||||
|
||||
/// Logs in directly and stores the session cookie.
|
||||
///
|
||||
/// Only meaningful in direct mode: a relay instance has no origin to dial and no cookie to keep,
|
||||
/// because the node's agent holds that session itself. Passing one here returns the explicit
|
||||
/// unauthenticated state rather than dialing something arbitrary.
|
||||
public func login(_ instance: Instance, password: String) async throws -> SessionMetadata {
|
||||
guard let origin = instance.endpoint.directOrigin else {
|
||||
return SessionMetadata(instanceID: instance.id, authenticated: false, checkedAt: Date())
|
||||
}
|
||||
do {
|
||||
let response = try await client.send(
|
||||
.authLogin(password: password),
|
||||
baseURL: instance.origin,
|
||||
baseURL: origin,
|
||||
cookie: nil
|
||||
)
|
||||
if let cookie = Self.sessionCookie(response.setCookie) {
|
||||
await store.set(instance.id, origin: instance.origin, cookie: cookie)
|
||||
await store.set(instance.id, origin: origin, cookie: cookie)
|
||||
return SessionMetadata(instanceID: instance.id, authenticated: true, checkedAt: Date())
|
||||
}
|
||||
} catch {
|
||||
@@ -40,15 +48,19 @@ public struct InstanceSessionService: Sendable {
|
||||
}
|
||||
|
||||
public func logout(_ instance: Instance) async throws -> SessionMetadata {
|
||||
if let cookie = await store.cookie(for: instance.id, origin: instance.origin) {
|
||||
_ = try? await client.send(.authLogout, baseURL: instance.origin, cookie: cookie)
|
||||
guard let origin = instance.endpoint.directOrigin else {
|
||||
return SessionMetadata(instanceID: instance.id, authenticated: false, checkedAt: Date())
|
||||
}
|
||||
if let cookie = await store.cookie(for: instance.id, origin: origin) {
|
||||
_ = try? await client.send(.authLogout, baseURL: origin, cookie: cookie)
|
||||
}
|
||||
await store.clear(instance.id)
|
||||
return SessionMetadata(instanceID: instance.id, authenticated: false, checkedAt: Date())
|
||||
}
|
||||
|
||||
public func cookie(for instance: Instance) async -> String? {
|
||||
await store.cookie(for: instance.id, origin: instance.origin)
|
||||
guard let origin = instance.endpoint.directOrigin else { return nil }
|
||||
return await store.cookie(for: instance.id, origin: origin)
|
||||
}
|
||||
|
||||
static func sessionCookie(_ header: String?) -> String? {
|
||||
|
||||
@@ -1,4 +1,63 @@
|
||||
import Foundation
|
||||
|
||||
/// User-facing text for every failure the app can produce.
|
||||
///
|
||||
/// The relay work is what forced this out of `ConnectionProbe`: with one hop there was one thing
|
||||
/// that could go wrong, and "请求失败" was an acceptable summary. With two hops there are four
|
||||
/// distinct situations that call for four different actions, and a message that cannot tell them
|
||||
/// apart is the difference between a five-second fix and a support thread.
|
||||
public enum ErrorMessage {
|
||||
public static let network = "暂时无法连接实例，请稍后重试。"
|
||||
public static let unauthorized = "实例登录状态已失效，请重新登录。"
|
||||
|
||||
// MARK: - Relay mode
|
||||
|
||||
/// Describes a relay-mode failure in terms of what the user should do next.
|
||||
public static func describe(_ error: UpstreamError, nodeName: String) -> String {
|
||||
switch error {
|
||||
case .relayUnreachable:
|
||||
return "无法连接中继服务器。请检查网络，或确认中继是否在运行。"
|
||||
case .relayTimeout:
|
||||
return "中继响应超时。稍后重试；如果反复出现，请检查中继负载。"
|
||||
case .relayRejectedDevice:
|
||||
return "中继已不再接受这台设备的凭据，需要在节点上重新配对。"
|
||||
case .relayNodeUnknown:
|
||||
return "中继不认识节点 \(nodeName)。可能节点已离线并被移出，或这台手机未与该节点配对。"
|
||||
case .agentOffline:
|
||||
return "节点 \(nodeName) 的 agent 当前未连接到中继。等它上线后重试。"
|
||||
case .nodeBusy:
|
||||
return "节点 \(nodeName) 正在处理其它请求，稍后重试。"
|
||||
case .agentTimeout:
|
||||
// The one message that must not invite a blind retry: the node may have executed it.
|
||||
return "节点 \(nodeName) 未在时限内应答。该操作可能已经执行，请先确认结果再决定是否重试。"
|
||||
case .relayBadEnvelope:
|
||||
return "中继拒绝了发往节点 \(nodeName) 的请求信封。这通常意味着两端版本不一致。"
|
||||
case .relayRateLimited:
|
||||
return "对节点 \(nodeName) 的请求过于频繁，已被中继限流。稍后再试。"
|
||||
case .relayPolicyDenied:
|
||||
return "节点 \(nodeName) 的 agent 不允许该操作。该路径不在它的授权范围内。"
|
||||
case .confirmationRejected:
|
||||
return "节点 \(nodeName) 拒绝了这次确认：确认信息与请求不匹配，操作未执行。请重新发起。"
|
||||
case .envelopeExpired:
|
||||
return "对节点 \(nodeName) 的请求已过期或重复。请重新发起；如果反复出现，请检查手机与节点的时钟。"
|
||||
case .nodeRateLimited:
|
||||
return "节点 \(nodeName) 限制了危险写操作频率，稍后再试。"
|
||||
case .nodeAuthFailed:
|
||||
return "节点 \(nodeName) 的 agent 无法登录本机 SimAdmin。需要在节点上修正 agent 的密码配置。"
|
||||
case .payloadTooLarge:
|
||||
return "请求内容超过节点 \(nodeName) 允许的大小。"
|
||||
case .relayResponseUnverifiable:
|
||||
return "节点 \(nodeName) 的应答未通过签名校验，已丢弃。这可能是中继被篡改或密钥不匹配。"
|
||||
case .relayResponseMismatch:
|
||||
return "中继返回了与请求不匹配的应答，已丢弃。"
|
||||
case .envelopeRejected:
|
||||
return "节点 \(nodeName) 拒绝了该请求的签名或格式。可能需要在节点上重新配对。"
|
||||
case .unauthorized:
|
||||
return unauthorized
|
||||
case .timeout, .transportFailed:
|
||||
return network
|
||||
default:
|
||||
return "请求失败：\(error)"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -62,6 +62,21 @@ public enum UpstreamRoute: Hashable, Sendable {
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
||||
/// Whether the node's agent will demand a confirmation intent for this route.
|
||||
///
|
||||
/// This is the app's copy of `policy.dangerous` in `contracts/agent-policy.json`, and the two
|
||||
/// are asserted equal by the relay repository's policy test. It is a copy rather than a shared
|
||||
/// file because the app cannot read the relay's repository at build time; the test is what
|
||||
/// keeps it from drifting.
|
||||
public var requiresConfirmation: Bool {
|
||||
switch self {
|
||||
case .smsSend, .smsBatchDelete:
|
||||
return true
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public enum UpstreamError: Error, Equatable {
|
||||
@@ -72,4 +87,46 @@ public enum UpstreamError: Error, Equatable {
|
||||
case timeout
|
||||
case transportFailed
|
||||
case invalidResponse
|
||||
|
||||
// Relay-mode failures. These are deliberately separate cases rather than a reuse of
|
||||
// transportFailed: in relay mode the user has four genuinely different situations to tell
|
||||
// apart, and a single "请求失败" for all of them is what makes a two-hop architecture
|
||||
// impossible to operate.
|
||||
/// The relay could not be reached at all.
|
||||
case relayUnreachable
|
||||
/// The relay took too long to answer.
|
||||
case relayTimeout
|
||||
/// The relay rejected this phone's bearer token: the pairing is no longer valid there.
|
||||
case relayRejectedDevice
|
||||
/// The relay does not know this node, or this phone is not paired to it.
|
||||
case relayNodeUnknown
|
||||
/// The node's agent is not connected to the relay.
|
||||
case agentOffline
|
||||
/// The node is connected but already has the maximum number of requests in flight.
|
||||
case nodeBusy
|
||||
/// The node accepted the request but did not answer within the relay's deadline. It may or may
|
||||
/// not have executed it, which is why the message must not invite a blind retry.
|
||||
case agentTimeout
|
||||
/// The relay refused the envelope before delivering it.
|
||||
case relayBadEnvelope
|
||||
/// The relay is rate limiting this phone.
|
||||
case relayRateLimited
|
||||
/// The node's agent rejected the request: not on its allowlist, or the device is not paired.
|
||||
case relayPolicyDenied
|
||||
/// The node received the request and the confirmation intent did not match.
|
||||
case confirmationRejected
|
||||
/// The envelope was outside the node's freshness window, or its id had already been used.
|
||||
case envelopeExpired
|
||||
/// The node's own rate limit refused a dangerous write.
|
||||
case nodeRateLimited
|
||||
/// The node's agent could not authenticate to its local SimAdmin.
|
||||
case nodeAuthFailed
|
||||
/// The request body exceeded the node's limit.
|
||||
case payloadTooLarge
|
||||
/// The node signed nothing, or the answer was not for this request.
|
||||
case relayResponseUnverifiable
|
||||
/// The relay answered about a different request or node.
|
||||
case relayResponseMismatch
|
||||
/// The node refused the envelope's signature or shape.
|
||||
case envelopeRejected
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user