Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatSync/Sources/SyncTransport.swift3// Description: Where encrypted sync batches travel: a shared folder (iCloud Drive, any folder) or a trusted Mac running Local Chat. Transports only ever see ciphertext.4import Foundation5import LocalChatCore67public enum SyncError: LocalizedError, Sendable, Equatable {8 case notConfigured9 case wrongPassphrase10 case tampered(String)11 case unsupportedVersion(Int)12 case metadataConflict13 case transport(String)14 case unauthorized15 case insecureURL16 case alreadySyncing17 public var errorDescription: String? {18 switch self {19 case .notConfigured: "Sync is not set up on this device."20 case .wrongPassphrase: "The sync passphrase does not match the one used by your other devices."21 case .tampered(let id): "A sync batch (\(id)) is damaged or was modified; it was ignored."22 case .unsupportedVersion(let v): "This sync data was written by a newer version of Local Chat (format \(v))."23 case .metadataConflict: "Another device set up sync at the same time. Try again."24 case .transport(let m): "Sync could not reach its storage: \(m)"25 case .unauthorized: "The sync node refused the API key."26 case .insecureURL: "Plain HTTP is only allowed for a Mac on your private network. Use https."27 case .alreadySyncing: "A sync is already running."28 }29 }30}3132public struct SyncBatchRef: Codable, Sendable, Hashable {33 public var id: String34 public var cursor: String? // position after this batch, when the transport has an order (the relay); nil for folders35 public init(id: String, cursor: String? = nil) { self.id = id; self.cursor = cursor }36}3738public protocol SyncTransport: Sendable {39 /// Shared, non-secret setup data (salt, iterations, key verifier). Nil when no device has set sync up yet.40 func fetchMetadata() async throws -> Data?41 /// Stores the metadata only if none exists; throws `SyncError.metadataConflict` when different metadata is already there.42 func storeMetadata(_ data: Data) async throws43 /// Batches after `cursor` (a transport without an order returns all of them; the engine skips what it already applied).44 func listBatches(after cursor: String?) async throws -> [SyncBatchRef]45 func fetchBatch(_ id: String) async throws -> Data46 func uploadBatch(id: String, data: Data) async throws47}4849enum BatchID {50 static func isValid(_ id: String) -> Bool {51 !id.isEmpty && id.count <= 128 && !id.hasPrefix(".") && id.unicodeScalars.allSatisfy {52 ($0.value >= 48 && $0.value <= 57) || ($0.value >= 65 && $0.value <= 90) || ($0.value >= 97 && $0.value <= 122) || $0 == "-" || $0 == "_" || $0 == "."53 }54 }55}5657/// One file per batch in a folder the user chose. Works with iCloud Drive or any synchronized / shared folder.58/// Batches are never pruned here: delete the folder to reset sync.59public struct FolderSyncTransport: SyncTransport {60 public let folder: URL61 static let metaName = "localchat-sync.meta.json", ext = "lcbatch"62 public init(folder: URL) { self.folder = folder }6364 private func coordinated<T: Sendable>(_ url: URL, writing: Bool, _ body: @Sendable (URL) throws -> T) throws -> T {65 var coordinationError: NSError?; var result: Result<T, Error>?66 let coordinator = NSFileCoordinator()67 let run: (URL) -> Void = { actual in result = Result { try body(actual) } }68 if writing { coordinator.coordinate(writingItemAt: url, options: .forReplacing, error: &coordinationError, byAccessor: run) }69 else { coordinator.coordinate(readingItemAt: url, options: [], error: &coordinationError, byAccessor: run) }70 if let coordinationError { throw SyncError.transport(coordinationError.localizedDescription) }71 guard let result else { throw SyncError.transport("file coordination did not run") }72 do { return try result.get() } catch let e as SyncError { throw e } catch { throw SyncError.transport(error.localizedDescription) }73 }7475 private func ensureFolder() throws {76 do { try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true) }77 catch { throw SyncError.transport(error.localizedDescription) }78 }7980 public func fetchMetadata() async throws -> Data? {81 let url = folder.appendingPathComponent(Self.metaName)82 guard FileManager.default.fileExists(atPath: url.path) else { return nil }83 return try coordinated(url, writing: false) { try Data(contentsOf: $0) }84 }8586 public func storeMetadata(_ data: Data) async throws {87 try ensureFolder()88 let url = folder.appendingPathComponent(Self.metaName)89 try coordinated(url, writing: true) { actual in90 if let existing = try? Data(contentsOf: actual) {91 if existing == data { return }92 throw SyncError.metadataConflict93 }94 try data.write(to: actual, options: .atomic)95 }96 }9798 public func listBatches(after cursor: String?) async throws -> [SyncBatchRef] {99 guard FileManager.default.fileExists(atPath: folder.path) else { return [] }100 let names: [String]101 do { names = try FileManager.default.contentsOfDirectory(atPath: folder.path) } catch { throw SyncError.transport(error.localizedDescription) }102 return names.filter { $0.hasSuffix("." + Self.ext) }.map { String($0.dropLast(Self.ext.count + 1)) }.filter(BatchID.isValid).sorted().map { SyncBatchRef(id: $0) }103 }104105 public func fetchBatch(_ id: String) async throws -> Data {106 guard BatchID.isValid(id) else { throw SyncError.transport("invalid batch id") }107 return try coordinated(folder.appendingPathComponent("\(id).\(Self.ext)"), writing: false) { try Data(contentsOf: $0) }108 }109110 public func uploadBatch(id: String, data: Data) async throws {111 guard BatchID.isValid(id) else { throw SyncError.transport("invalid batch id") }112 try ensureFolder()113 try coordinated(folder.appendingPathComponent("\(id).\(Self.ext)"), writing: true) { try data.write(to: $0, options: .atomic) }114 }115}116117/// HTTP transport to the sync relay of a trusted Mac running Local Chat (its Local API server, authenticated with an API key).118public struct NodeSyncTransport: SyncTransport {119 public let baseURL: URL // server root, e.g. http://studio.local:8765120 let apiKey: String121 let session: URLSession122123 public init(baseURL: URL, apiKey: String, allowInsecureHTTP: Bool = false, session: URLSession? = nil) throws {124 var root = baseURL125 if root.path.hasSuffix("/v1") || root.path.hasSuffix("/v1/") { root = root.deletingLastPathComponent() }126 guard let scheme = root.scheme?.lowercased(), let host = root.host, scheme == "https" || scheme == "http" else { throw SyncError.insecureURL }127 if scheme == "http" && !allowInsecureHTTP && !Self.isPrivateHost(host) { throw SyncError.insecureURL }128 self.baseURL = root; self.apiKey = apiKey129 if let session { self.session = session } else {130 let config = URLSessionConfiguration.ephemeral; config.timeoutIntervalForRequest = 30; config.httpCookieStorage = nil131 self.session = URLSession(configuration: config)132 }133 }134135 /// Loopback, .local names, RFC 1918, link-local, CGNAT (Tailscale) and IPv6 unique-local / link-local hosts.136 public static func isPrivateHost(_ host: String) -> Bool {137 let h = host.lowercased().trimmingCharacters(in: CharacterSet(charactersIn: "[]"))138 if h == "localhost" || h.hasSuffix(".local") || h.hasSuffix(".localhost") || h == "::1" { return true }139 let parts = h.split(separator: ".").compactMap { UInt8($0) }140 if parts.count == 4, h.split(separator: ".").count == 4 {141 return parts[0] == 10 || parts[0] == 127 || (parts[0] == 192 && parts[1] == 168) || (parts[0] == 172 && (16...31).contains(parts[1]))142 || (parts[0] == 169 && parts[1] == 254) || (parts[0] == 100 && (64...127).contains(parts[1]))143 }144 return h.hasPrefix("fc") || h.hasPrefix("fd") || h.hasPrefix("fe80:")145 }146147 private func send(_ method: String, _ path: String, query: [URLQueryItem] = [], body: Data? = nil) async throws -> (Int, Data) {148 var components = URLComponents(url: baseURL.appendingPathComponent("lc/v1/sync/" + path), resolvingAgainstBaseURL: false)149 if !query.isEmpty { components?.queryItems = query }150 guard let url = components?.url else { throw SyncError.transport("invalid URL") }151 var request = URLRequest(url: url); request.httpMethod = method; request.httpBody = body152 request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")153 if body != nil { request.setValue("application/octet-stream", forHTTPHeaderField: "Content-Type") }154 do {155 let (data, response) = try await session.data(for: request)156 let status = (response as? HTTPURLResponse)?.statusCode ?? 0157 if status == 401 || status == 403 { throw SyncError.unauthorized }158 return (status, data)159 } catch let e as SyncError { throw e } catch { throw SyncError.transport(error.localizedDescription) }160 }161162 public func fetchMetadata() async throws -> Data? {163 let (status, data) = try await send("GET", "meta")164 if status == 404 { return nil }165 guard status == 200 else { throw SyncError.transport("HTTP \(status)") }166 return data167 }168 public func storeMetadata(_ data: Data) async throws {169 let (status, _) = try await send("PUT", "meta", body: data)170 if status == 409 { throw SyncError.metadataConflict }171 guard (200..<300).contains(status) else { throw SyncError.transport("HTTP \(status)") }172 }173 public func listBatches(after cursor: String?) async throws -> [SyncBatchRef] {174 let (status, data) = try await send("GET", "batches", query: cursor.map { [URLQueryItem(name: "after", value: $0)] } ?? [])175 guard status == 200 else { throw SyncError.transport("HTTP \(status)") }176 guard let list = try? JSONDecoder().decode(SyncRelay.Listing.self, from: data) else { throw SyncError.transport("unexpected answer from the node") }177 return list.batches.map { SyncBatchRef(id: $0.id, cursor: String($0.cursor)) }178 }179 public func fetchBatch(_ id: String) async throws -> Data {180 guard BatchID.isValid(id) else { throw SyncError.transport("invalid batch id") }181 let (status, data) = try await send("GET", "batches/\(id)")182 guard status == 200 else { throw SyncError.transport("HTTP \(status)") }183 return data184 }185 public func uploadBatch(id: String, data: Data) async throws {186 guard BatchID.isValid(id) else { throw SyncError.transport("invalid batch id") }187 let (status, _) = try await send("PUT", "batches/\(id)", body: data)188 guard (200..<300).contains(status) else { throw SyncError.transport("HTTP \(status)") }189 }190}191192/// Server side of `NodeSyncTransport`: stores opaque encrypted batches under /lc/v1/sync/. It never has the key.193/// Authentication is done by the Local API server before requests reach this handler.194public actor SyncRelay: HTTPRouteHandler {195 public struct Limits: Sendable {196 public var maxBatchBytes = 8 * 1_048_576197 public var maxTotalBytes: Int64 = 512 * 1_048_576198 public var maxBatches = 20_000199 public init() {}200 }201 struct Entry: Codable, Sendable { var id: String; var cursor: Int64; var size: Int }202 struct Listing: Codable, Sendable { var batches: [Entry]; var cursor: Int64 }203204 public static let prefix = "/lc/v1/sync/"205 let directory: URL206 let limits: Limits207 private var entries: [Entry] = [] // ascending cursor208 private var nextCursor: Int64 = 1209 private var loaded = false210211 public init(directory: URL, limits: Limits = Limits()) { self.directory = directory; self.limits = limits }212213 private func file(_ e: Entry) -> URL { directory.appendingPathComponent(String(format: "%012lld-%@.batch", e.cursor, e.id)) }214 private var metaURL: URL { directory.appendingPathComponent("meta.json") }215216 private func load() {217 guard !loaded else { return }218 loaded = true219 try? FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)220 for name in ((try? FileManager.default.contentsOfDirectory(atPath: directory.path)) ?? []) where name.hasSuffix(".batch") {221 let stem = String(name.dropLast(6))222 guard let dash = stem.firstIndex(of: "-"), let cursor = Int64(stem[..<dash]) else { continue }223 let id = String(stem[stem.index(after: dash)...])224 let size = ((try? FileManager.default.attributesOfItem(atPath: directory.appendingPathComponent(name).path))?[.size] as? Int) ?? 0225 entries.append(Entry(id: id, cursor: cursor, size: size))226 }227 entries.sort { $0.cursor < $1.cursor }228 // the counter survives pruning and restarts229 let saved = (try? String(contentsOf: directory.appendingPathComponent("cursor"), encoding: .utf8)).flatMap { Int64($0.trimmingCharacters(in: .whitespacesAndNewlines)) } ?? 0230 nextCursor = max(saved, entries.last?.cursor ?? 0) + 1231 }232233 private func prune() {234 var total = entries.reduce(Int64(0)) { $0 + Int64($1.size) }235 while entries.count > 1, entries.count > limits.maxBatches || total > limits.maxTotalBytes {236 let old = entries.removeFirst(); total -= Int64(old.size)237 try? FileManager.default.removeItem(at: file(old))238 }239 }240241 public var batchCount: Int { load(); return entries.count }242243 public func handle(_ request: HTTPRequestMessage) async -> HTTPResponseMessage? {244 guard request.path.hasPrefix(Self.prefix) else { return nil }245 load()246 let rest = String(request.path.dropFirst(Self.prefix.count))247 switch (request.method, rest) {248 case ("GET", "meta"):249 guard let data = try? Data(contentsOf: metaURL) else { return .error(404, "Sync is not set up on this node.") }250 return HTTPResponseMessage(status: 200, headers: ["Content-Type": "application/json"], body: data)251 case ("PUT", "meta"):252 guard !request.body.isEmpty, request.body.count <= 4096 else { return .error(400, "Invalid metadata.") }253 if let existing = try? Data(contentsOf: metaURL) {254 return existing == request.body ? HTTPResponseMessage(status: 200) : .error(409, "Sync metadata already exists.")255 }256 guard (try? request.body.write(to: metaURL, options: .atomic)) != nil else { return .error(500, "Could not store the metadata.", type: "server_error") }257 return HTTPResponseMessage(status: 201)258 case ("GET", "batches"):259 let after = request.query["after"].flatMap { Int64($0) } ?? 0260 let page = Array(entries.filter { $0.cursor > after }.prefix(500))261 return .json(Listing(batches: page, cursor: page.last?.cursor ?? max(after, nextCursor - 1)))262 default:263 guard rest.hasPrefix("batches/") else { return .error(404, "Unknown sync route.") }264 let id = String(rest.dropFirst("batches/".count))265 guard BatchID.isValid(id) else { return .error(400, "Invalid batch id.") }266 if request.method == "GET" {267 guard let entry = entries.first(where: { $0.id == id }), let data = try? Data(contentsOf: file(entry)) else { return .error(404, "Unknown batch.") }268 return HTTPResponseMessage(status: 200, headers: ["Content-Type": "application/octet-stream"], body: data)269 }270 guard request.method == "PUT" else { return .error(405, "Method not allowed.") }271 guard !request.body.isEmpty, request.body.count <= limits.maxBatchBytes else { return .error(413, "The batch is empty or too large.") }272 if let existing = entries.firstIndex(where: { $0.id == id }) {273 // a retried upload: same id keeps its position274 guard (try? request.body.write(to: file(entries[existing]), options: .atomic)) != nil else { return .error(500, "Could not store the batch.", type: "server_error") }275 entries[existing].size = request.body.count276 return .json(["cursor": entries[existing].cursor], status: 200)277 }278 let entry = Entry(id: id, cursor: nextCursor, size: request.body.count)279 guard (try? request.body.write(to: file(entry), options: .atomic)) != nil else { return .error(500, "Could not store the batch.", type: "server_error") }280 try? String(nextCursor).write(to: directory.appendingPathComponent("cursor"), atomically: true, encoding: .utf8)281 nextCursor += 1; entries.append(entry); prune()282 return .json(["cursor": entry.cursor], status: 201)283 }284 }285}286