@dvai-bridge/ios 4.0.0

package/ios/Sources/DVAIBridge/Offload/OffloadRuntime.swift

@@ -0,0 +1,98 @@
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+
+/// Bundles together the iOS-native offload state for one running
+/// `DVAIBridge` instance: discovery, advertiser, capability cache,
+/// pairing store + policy. Created on `start()` when
+/// `OffloadConfig.enabled == true`; torn down on `stop()`.
+@available(iOS 14.0, macOS 11.0, *)
+public actor OffloadRuntime {
+    public let config: OffloadConfig
+    public let supportDirectory: URL
+    public let deviceIDStore: DeviceIDStore
+    public let capabilityCache: CapabilityCache
+    public let pairingStore: PairingStore
+    public let pairingPolicy: PairingPolicy
+    public let discovery: NWBrowserDiscovery
+    public let advertiser: NWAdvertiser
+    private var started = false
+
+    public init(config: OffloadConfig, supportDirectory: URL? = nil) throws {
+        self.config = config
+        self.supportDirectory = try supportDirectory ?? DVAIBridgeSupportDirectory.resolve()
+        self.deviceIDStore = DeviceIDStore(directory: self.supportDirectory)
+        self.capabilityCache = CapabilityCache(directory: self.supportDirectory)
+        self.pairingStore = PairingStore(directory: self.supportDirectory)
+        self.pairingPolicy = PairingPolicy(
+            store: pairingStore,
+            expireAfterDays: config.expireAfterDays
+        )
+        self.discovery = NWBrowserDiscovery()
+        self.advertiser = NWAdvertiser()
+    }
+
+    /// Bring up the discovery + advertiser. Idempotent.
+    /// `boundServer` provides the port + version we advertise.
+    public func start(boundServer: BoundServer, libraryVersion: String) async throws {
+        guard !started else { return }
+        started = true
+
+        if config.discoverLAN {
+            let deviceId = try deviceIDStore.get()
+            // Configure self-filtering BEFORE starting the browser
+            // so the very first peerUp event from our own
+            // advertisement is dropped (race-free).
+            await discovery.setSelfDeviceId(deviceId)
+            // Defensive: drop any stale self-pairing that an earlier
+            // build may have persisted before the self-filter
+            // existed. A pairing keyed by our own deviceId would
+            // otherwise let `decideRoute`'s paired-peer fallback
+            // route requests back to us in an infinite loop.
+            try? await pairingStore.remove(deviceId)
+            await discovery.start()
+            let deviceName = await Self.resolveDeviceName()
+            try await advertiser.start(
+                NWAdvertiser.Advertisement(
+                    deviceId: deviceId,
+                    deviceName: deviceName,
+                    dvaiVersion: libraryVersion,
+                    port: boundServer.port,
+                    secure: false,
+                    loadedModels: boundServer.modelId.isEmpty ? [] : [boundServer.modelId],
+                    capability: [:]
+                )
+            )
+        }
+    }
+
+    /// Tear down. Idempotent.
+    public func stop() async {
+        guard started else { return }
+        started = false
+        await discovery.stop()
+        await advertiser.stop()
+        await pairingPolicy.shutdown()
+    }
+
+    public func isRunning() -> Bool { started }
+
+    /// Surface the pairing-request stream. Called by
+    /// `DVAIBridge.shared.pairingRequests`.
+    public nonisolated func pairingRequestStream() -> AsyncStream<PairingRequest> {
+        pairingPolicy.requestStream
+    }
+
+    public nonisolated func discoveryEventStream() -> AsyncStream<NWBrowserDiscovery.Event> {
+        discovery.events
+    }
+
+    private static func resolveDeviceName() async -> String {
+        #if canImport(UIKit) && !os(macOS)
+        return await MainActor.run { UIDevice.current.name }
+        #else
+        return ProcessInfo.processInfo.hostName
+        #endif
+    }
+}

package/ios/Sources/DVAIBridge/Pairing/Pairing.swift

@@ -0,0 +1,125 @@
+import Foundation
+
+/// A "pairing" is an authenticated trust relationship between two
+/// devices, established once via the handshake flow then reused for
+/// all subsequent offload requests via HMAC-signed headers. Mirrors
+/// the TS shape in `packages/dvai-bridge-core/src/pairing/types.ts`.
+public struct Pairing: Sendable, Equatable, Codable, Hashable {
+    public enum Via: String, Sendable, Codable, Hashable {
+        case lanHandshake = "lan-handshake"
+        case rendezvousQR = "rendezvous-qr"
+    }
+
+    /// Stable per-install device ID of the peer.
+    public let peerDeviceId: String
+    /// Friendly name for the user UI.
+    public let peerDeviceName: String
+    /// Shared 256-bit pairing key (base64-url encoded). Used for HMAC.
+    public let pairingKey: String
+    /// When the pairing was first established (unix ms).
+    public let pairedAt: Int64
+    /// Last time this pairing was used (unix ms).
+    public var lastUsedAt: Int64
+    /// Pairing source — informational.
+    public let via: Via
+    /// v3.2.1 — last-known peer baseUrl. Captured at pairing time
+    /// so the OffloadProxy can route to a paired peer even when it
+    /// isn't currently in the mDNS discovery list (e.g. the desktop
+    /// Hub on macOS, where Node's `multicast-dns` lib can't
+    /// advertise through mDNSResponder). Optional for back-compat —
+    /// pairings persisted by earlier builds decode with `nil` here.
+    public var baseUrl: String?
+
+    public init(
+        peerDeviceId: String,
+        peerDeviceName: String,
+        pairingKey: String,
+        pairedAt: Int64 = Int64(Date().timeIntervalSince1970 * 1000),
+        lastUsedAt: Int64 = Int64(Date().timeIntervalSince1970 * 1000),
+        via: Via = .lanHandshake,
+        baseUrl: String? = nil
+    ) {
+        self.peerDeviceId = peerDeviceId
+        self.peerDeviceName = peerDeviceName
+        self.pairingKey = pairingKey
+        self.pairedAt = pairedAt
+        self.lastUsedAt = lastUsedAt
+        self.via = via
+        self.baseUrl = baseUrl
+    }
+}
+
+/// Surfaced to the host app as an item in the
+/// `DVAIBridge.shared.pairingRequests()` AsyncStream. The host app
+/// decides approve/deny, then calls `respond(approved:)`.
+///
+/// If the host doesn't call `respond(approved:)` within the policy's
+/// timeout, the request defaults to deny — see `PairingPolicy`.
+public final class PairingRequest: @unchecked Sendable {
+    public let peerDeviceId: String
+    public let peerDeviceName: String
+    public let via: Pairing.Via
+
+    private let lock = NSLock()
+    private var responded = false
+    private var pendingValue: Bool?
+    /// Continuation used by the policy to await the host's respond.
+    /// Lazily set when `awaitResponse()` is called the first time.
+    private var awaitContinuation: CheckedContinuation<Bool, Never>?
+
+    public init(
+        peerDeviceId: String,
+        peerDeviceName: String,
+        via: Pairing.Via
+    ) {
+        self.peerDeviceId = peerDeviceId
+        self.peerDeviceName = peerDeviceName
+        self.via = via
+    }
+
+    /// Host-app entry point. Approve or deny the pairing.
+    public func respond(approved: Bool) {
+        lock.lock()
+        if responded {
+            lock.unlock()
+            return
+        }
+        responded = true
+        if let cont = awaitContinuation {
+            awaitContinuation = nil
+            lock.unlock()
+            cont.resume(returning: approved)
+        } else {
+            // No one's awaiting yet — store the value for whoever
+            // calls awaitResponse() next.
+            pendingValue = approved
+            lock.unlock()
+        }
+    }
+
+    /// Internal — used by `PairingPolicy` to await the host response.
+    /// Resumes when `respond(approved:)` is called or returns `false`
+    /// when `cancelWithDeny()` is called.
+    internal func awaitResponse() async -> Bool {
+        return await withCheckedContinuation { (cont: CheckedContinuation<Bool, Never>) in
+            lock.lock()
+            if let stored = pendingValue {
+                pendingValue = nil
+                lock.unlock()
+                cont.resume(returning: stored)
+            } else if responded {
+                lock.unlock()
+                cont.resume(returning: false)
+            } else {
+                awaitContinuation = cont
+                lock.unlock()
+            }
+        }
+    }
+
+    /// Internal — fast-path deny used by the policy on timeout / stream
+    /// teardown / drop.
+    internal func cancelWithDeny() {
+        respond(approved: false)
+    }
+}

package/ios/Sources/DVAIBridge/Pairing/PairingHandshake.swift

@@ -0,0 +1,141 @@
+import Foundation
+import CryptoKit
+
+/// Pairing-handshake primitives: HMAC-SHA256 signing of offload
+/// requests + helpers to compose the canonical signed message. Mirrors
+/// `packages/dvai-bridge-core/src/pairing/handshake.ts` byte-for-byte
+/// so signatures round-trip between iOS and other peers (Node, Android,
+/// browser).
+///
+/// All keys / nonces / signatures are encoded in URL-safe base64
+/// without padding — same as the TS side's `encodeBase64Url`.
+public enum PairingHandshake {
+
+    // MARK: - Public API
+
+    /// Generate a fresh 256-bit pairing key (base64-url, no padding).
+    public static func generatePairingKey() -> String {
+        var bytes = [UInt8](repeating: 0, count: 32)
+        _ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
+        return base64UrlEncode(Data(bytes))
+    }
+
+    /// Generate a fresh nonce for a handshake request (16 bytes).
+    public static func generateNonce() -> String {
+        var bytes = [UInt8](repeating: 0, count: 16)
+        _ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
+        return base64UrlEncode(Data(bytes))
+    }
+
+    /// HMAC-SHA256(pairingKey, message) → base64-url encoded.
+    public static func signHmac(pairingKey: String, message: String) throws -> String {
+        let keyData = try decodeBase64Url(pairingKey)
+        let key = SymmetricKey(data: keyData)
+        let messageData = Data(message.utf8)
+        let mac = HMAC<SHA256>.authenticationCode(for: messageData, using: key)
+        return base64UrlEncode(Data(mac))
+    }
+
+    /// Constant-time-ish HMAC verify. Returns true on match.
+    public static func verifyHmac(
+        pairingKey: String,
+        message: String,
+        signature: String
+    ) throws -> Bool {
+        let expected = try signHmac(pairingKey: pairingKey, message: message)
+        return constantTimeEquals(expected, signature)
+    }
+
+    /// Compose the canonical message that gets HMAC-signed for a
+    /// peer-to-peer offload request. Mirrors
+    /// `composeSignedMessage` in handshake.ts:
+    ///
+    ///     `${nonce}\n${METHOD}\n${path}\n${bodyHash}`
+    ///
+    /// where bodyHash is the hex-encoded SHA-256 of the request body
+    /// bytes (or all-zero hex for empty body).
+    public static func composeSignedMessage(
+        nonce: String,
+        method: String,
+        path: String,
+        body: String?
+    ) -> String {
+        let bodyHash: String
+        if let body = body, !body.isEmpty {
+            bodyHash = sha256Hex(body)
+        } else {
+            bodyHash = String(repeating: "0", count: 64)
+        }
+        return "\(nonce)\n\(method.uppercased())\n\(path)\n\(bodyHash)"
+    }
+
+    /// Hex-encoded SHA-256 of the input string. Public for tests.
+    public static func sha256Hex(_ input: String) -> String {
+        let digest = SHA256.hash(data: Data(input.utf8))
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    // MARK: - Base64-url helpers
+
+    /// URL-safe base64 encode without padding. Public for tests.
+    public static func base64UrlEncode(_ data: Data) -> String {
+        let b64 = data.base64EncodedString()
+        return b64
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+    }
+
+    /// Decode URL-safe base64 (with or without padding). Public for tests.
+    public static func decodeBase64Url(_ s: String) throws -> Data {
+        var b64 = s
+            .replacingOccurrences(of: "-", with: "+")
+            .replacingOccurrences(of: "_", with: "/")
+        let padding = (4 - (b64.count % 4)) % 4
+        b64 += String(repeating: "=", count: padding)
+        guard let data = Data(base64Encoded: b64) else {
+            throw DVAIBridgeError.configurationInvalid(reason: "invalid base64-url string")
+        }
+        return data
+    }
+
+    private static func constantTimeEquals(_ a: String, _ b: String) -> Bool {
+        let aBytes = Array(a.utf8)
+        let bBytes = Array(b.utf8)
+        if aBytes.count != bBytes.count { return false }
+        var diff: UInt8 = 0
+        for i in 0..<aBytes.count {
+            diff |= aBytes[i] ^ bBytes[i]
+        }
+        return diff == 0
+    }
+}
+
+/// HandshakeRequest body the offload-source POSTs to the target's
+/// `/v1/dvai/handshake` endpoint. Matches the TS shape.
+public struct HandshakeRequest: Sendable, Equatable, Codable {
+    public let originDeviceId: String
+    public let originDeviceName: String
+    public let originVersion: String
+    public let nonce: String
+
+    public init(originDeviceId: String, originDeviceName: String, originVersion: String, nonce: String) {
+        self.originDeviceId = originDeviceId
+        self.originDeviceName = originDeviceName
+        self.originVersion = originVersion
+        self.nonce = nonce
+    }
+}
+
+/// HandshakeResponse the target returns. Matches the TS shape.
+public struct HandshakeResponse: Sendable, Equatable, Codable {
+    public let approved: Bool
+    public let pairingKey: String?
+    public let reason: String?
+
+    public init(approved: Bool, pairingKey: String? = nil, reason: String? = nil) {
+        self.approved = approved
+        self.pairingKey = pairingKey
+        self.reason = reason
+    }
+}

package/ios/Sources/DVAIBridge/Pairing/PairingPolicy.swift

@@ -0,0 +1,162 @@
+import Foundation
+
+/// Coordinates the host-app's pairing-request UI with the persistent
+/// `PairingStore`. Mirrors `packages/dvai-bridge-core/src/pairing/policy.ts`.
+///
+/// The host app consumes the request stream via
+/// `DVAIBridge.shared.pairingRequests`. If nothing is consuming the
+/// stream when a request comes in, the policy denies — same safe
+/// fallback as the JS side's default-deny.
+public actor PairingPolicy {
+    /// Default time the policy waits for the host app to respond to a
+    /// `PairingRequest` before defaulting to deny. 30 seconds is the
+    /// same magnitude as a typical OS permission prompt — long enough
+    /// for the user to read + decide, short enough that an unattended
+    /// device doesn't leak approval to a malicious peer.
+    public static let defaultResponseTimeoutSeconds: Double = 30
+
+    private let store: PairingStore
+    private let expireAfterDays: Int
+    private let responseTimeoutSeconds: Double
+    private let continuation: AsyncStream<PairingRequest>.Continuation
+    /// AsyncStream of pairing requests. Lifecycle-bound to this policy
+    /// instance; finishes when `shutdown()` is called.
+    public nonisolated let requestStream: AsyncStream<PairingRequest>
+
+    public init(
+        store: PairingStore,
+        expireAfterDays: Int = 30,
+        responseTimeoutSeconds: Double = PairingPolicy.defaultResponseTimeoutSeconds
+    ) {
+        self.store = store
+        self.expireAfterDays = expireAfterDays
+        self.responseTimeoutSeconds = responseTimeoutSeconds
+        var savedContinuation: AsyncStream<PairingRequest>.Continuation!
+        self.requestStream = AsyncStream<PairingRequest> { c in
+            savedContinuation = c
+        }
+        self.continuation = savedContinuation
+    }
+
+    /// Snapshot of every persisted pairing (active or expired).
+    /// Used by the OffloadProxy's paired-peer fallback to consider
+    /// pairings whose peers aren't currently in mDNS discovery.
+    public func listPairings() async -> [Pairing] {
+        await store.list()
+    }
+
+    /// Active (non-expired) pairing for this peer, or nil.
+    public func getActive(peerDeviceId: String) async -> Pairing? {
+        guard let existing = await store.get(peerDeviceId) else { return nil }
+        let ttlMs = Int64(expireAfterDays) * 24 * 60 * 60 * 1000
+        let nowMs = Int64(Date().timeIntervalSince1970 * 1000)
+        if nowMs - existing.lastUsedAt > ttlMs {
+            try? await store.remove(peerDeviceId)
+            return nil
+        }
+        return existing
+    }
+
+    /// Process an incoming pairing request. If we already have an
+    /// active pairing for this peer, reuse it (and bump lastUsedAt).
+    /// Otherwise yield a `PairingRequest` to the host-app stream and
+    /// await their decision.
+    public func approveOrFetch(
+        peerDeviceId: String,
+        peerDeviceName: String,
+        via: Pairing.Via
+    ) async throws -> Pairing {
+        if var existing = await getActive(peerDeviceId: peerDeviceId) {
+            existing.lastUsedAt = Int64(Date().timeIntervalSince1970 * 1000)
+            try await store.set(existing)
+            return existing
+        }
+
+        let approved = await requestApproval(
+            peerDeviceId: peerDeviceId,
+            peerDeviceName: peerDeviceName,
+            via: via
+        )
+        if !approved {
+            throw DVAIBridgeError.configurationInvalid(
+                reason: "[DVAI/pairing] denied: peer \(peerDeviceId) (\(peerDeviceName))"
+            )
+        }
+
+        let nowMs = Int64(Date().timeIntervalSince1970 * 1000)
+        let pairing = Pairing(
+            peerDeviceId: peerDeviceId,
+            peerDeviceName: peerDeviceName,
+            pairingKey: PairingHandshake.generatePairingKey(),
+            pairedAt: nowMs,
+            lastUsedAt: nowMs,
+            via: via
+        )
+        try await store.set(pairing)
+        return pairing
+    }
+
+    /// Bump lastUsedAt for an existing pairing.
+    public func touch(peerDeviceId: String) async throws {
+        guard var existing = await store.get(peerDeviceId) else { return }
+        existing.lastUsedAt = Int64(Date().timeIntervalSince1970 * 1000)
+        try await store.set(existing)
+    }
+
+    public func revoke(peerDeviceId: String) async throws {
+        try await store.remove(peerDeviceId)
+    }
+
+    /// Tear down the request stream. Called on `DVAIBridge.shared.stop()`.
+    public func shutdown() {
+        continuation.finish()
+    }
+
+    /// Surface a request to the host app and await their respond(:)
+    /// call. If the host doesn't respond within
+    /// `responseTimeoutSeconds`, the request defaults to deny — same
+    /// safe fallback as the JS side when no `onPairingRequest` callback
+    /// is supplied.
+    private func requestApproval(
+        peerDeviceId: String,
+        peerDeviceName: String,
+        via: Pairing.Via
+    ) async -> Bool {
+        // Race the host-app response against a timeout.
+        return await withTaskGroup(of: Bool.self, returning: Bool.self) { group in
+            let req = PairingRequest(
+                peerDeviceId: peerDeviceId,
+                peerDeviceName: peerDeviceName,
+                via: via
+            )
+            let yieldResult = continuation.yield(req)
+            switch yieldResult {
+            case .enqueued:
+                break
+            case .terminated, .dropped:
+                // Stream is gone or buffer dropped the value — deny.
+                req.cancelWithDeny()
+                return false
+            @unknown default:
+                req.cancelWithDeny()
+                return false
+            }
+            // Consumer task: await the host's respond() call.
+            group.addTask {
+                await req.awaitResponse()
+            }
+            // Timeout task: if host hasn't responded in time, deny.
+            let timeoutSeconds = self.responseTimeoutSeconds
+            group.addTask {
+                let nanos = UInt64(timeoutSeconds * 1_000_000_000)
+                try? await Task.sleep(nanoseconds: nanos)
+                req.cancelWithDeny()
+                return false
+            }
+            // First completion wins.
+            let first = await group.next() ?? false
+            group.cancelAll()
+            return first
+        }
+    }
+}

package/ios/Sources/DVAIBridge/Pairing/PairingStore.swift

@@ -0,0 +1,65 @@
+import Foundation
+
+/// JSON-file-backed pairing store under
+/// `Application Support/dvai-bridge/pairings.json`. Mirrors the TS-side
+/// `NodeFsPairingStore` in `packages/dvai-bridge-core/src/pairing/store.ts`.
+public actor PairingStore {
+    private let fileURL: URL
+    private var cache: [String: Pairing]?
+
+    public init(directory: URL) {
+        self.fileURL = directory.appendingPathComponent("pairings.json", isDirectory: false)
+    }
+
+    public func get(_ peerDeviceId: String) async -> Pairing? {
+        let map = await load()
+        return map[peerDeviceId]
+    }
+
+    public func set(_ pairing: Pairing) async throws {
+        var map = await load()
+        map[pairing.peerDeviceId] = pairing
+        cache = map
+        try await save()
+    }
+
+    public func list() async -> [Pairing] {
+        let map = await load()
+        return Array(map.values)
+    }
+
+    public func remove(_ peerDeviceId: String) async throws {
+        var map = await load()
+        map.removeValue(forKey: peerDeviceId)
+        cache = map
+        try await save()
+    }
+
+    public func clear() async throws {
+        cache = [:]
+        try await save()
+    }
+
+    private func load() async -> [String: Pairing] {
+        if let cache = cache { return cache }
+        if let data = try? Data(contentsOf: fileURL),
+           let decoded = try? JSONDecoder().decode([String: Pairing].self, from: data) {
+            cache = decoded
+            return decoded
+        }
+        cache = [:]
+        return [:]
+    }
+
+    private func save() async throws {
+        guard let cache = cache else { return }
+        try FileManager.default.createDirectory(
+            at: fileURL.deletingLastPathComponent(),
+            withIntermediateDirectories: true
+        )
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        let data = try encoder.encode(cache)
+        try data.write(to: fileURL, options: .atomic)
+    }
+}

package/ios/Sources/DVAIBridge/ProgressEvent.swift

@@ -0,0 +1,34 @@
+import Foundation
+
+/// Lifecycle progress event emitted during start(), downloadModel(), and
+/// related long-running operations. Mirrors the existing TS / Capacitor
+/// `ProgressEvent` shape so the iOS SDK reads identically to the JS API.
+public struct ProgressEvent: Sendable, Equatable, Codable {
+    public enum Phase: String, Sendable, Codable {
+        case download
+        case verify
+        case load
+        case ready
+        case error
+    }
+
+    public let phase: Phase
+    public let bytesReceived: Int64?
+    public let bytesTotal: Int64?
+    public let percent: Double?
+    public let message: String?
+
+    public init(
+        phase: Phase,
+        bytesReceived: Int64? = nil,
+        bytesTotal: Int64? = nil,
+        percent: Double? = nil,
+        message: String? = nil
+    ) {
+        self.phase = phase
+        self.bytesReceived = bytesReceived
+        self.bytesTotal = bytesTotal
+        self.percent = percent
+        self.message = message
+    }
+}