@mentra/glasses-media 3.2.1-dev.293 → 3.2.1-dev.295

package/ios/CoreKit/Sources/GlassesMediaCore/LocalMediaPolicy.swift

@@ -39,6 +39,14 @@ public enum LocalMediaPolicy {
         return bytes[3] > 0 && bytes[3] < 255
     }
 
+    /// A Mac may join through its host network controls. Reuse that connection only
+    /// after both its SSID and DHCP address match the hotspot advertised over BLE.
+    public static func canReuseHotspot(requestedSSID: String, currentSSID: String?, address: String?, gateway: String?) -> Bool {
+        guard !requestedSSID.isEmpty, requestedSSID == currentSSID,
+              let address, let gateway else { return false }
+        return isHotspotClientAddress(address, gateway: gateway)
+    }
+
     /// Keep only concrete host candidates on the local link. Never rewrite a cellular socket's
     /// advertised address: a candidate must already belong to the interface it claims.
     public static func localSdp(_ sdp: String, address: String, answer: Bool) throws -> String {

package/ios/CoreKit/Sources/GlassesMediaCore/LocalNetworkAccessRequest.swift

@@ -0,0 +1,134 @@
+import Foundation
+import Network
+
+protocol LocalNetworkAccessConnection: AnyObject {
+    var onState: ((NWConnection.State, NWPath.UnsatisfiedReason?) -> Void)? { get set }
+    func start(queue: DispatchQueue)
+    func cancel()
+}
+
+/// Wait for permission to use the verified local route before starting timed media work.
+/// Connect to the glasses' existing gallery HTTP endpoint to prove local access (TN3179).
+/// Network.framework retries when access is granted. A denied path can also mean that the
+/// alert is still open, so it must not be treated as a terminal error or given a media timeout.
+/// Ordinary connection setup has a 30-second budget, paused while permission is required.
+public final class LocalNetworkAccessRequest {
+    private let queue: DispatchQueue
+    private let connection: LocalNetworkAccessConnection
+    private let now: () -> TimeInterval
+    private let scheduleTimeout: (TimeInterval, DispatchWorkItem) -> Void
+    private var remainingConnectivityTime: TimeInterval = 30
+    private var timeoutDeadline: TimeInterval?
+    private var timeoutWork: DispatchWorkItem?
+    private var completion: ((Result<Void, Error>) -> Void)?
+    private var waiting: (() -> Void)?
+    private var finished = false
+    private var reportedPermission = false
+
+    public convenience init(localAddress: String, gateway: String, queue: DispatchQueue) {
+        self.init(connection: LocalNetworkPermissionConnection(localAddress: localAddress, gateway: gateway), queue: queue)
+    }
+
+    init(connection: LocalNetworkAccessConnection, queue: DispatchQueue,
+         now: @escaping () -> TimeInterval = { ProcessInfo.processInfo.systemUptime },
+         scheduleTimeout: ((TimeInterval, DispatchWorkItem) -> Void)? = nil)
+    {
+        self.connection = connection
+        self.queue = queue
+        self.now = now
+        self.scheduleTimeout = scheduleTimeout ?? { delay, work in queue.asyncAfter(deadline: .now() + delay, execute: work) }
+    }
+
+    public func start(onPermissionRequired: @escaping () -> Void, completion: @escaping (Result<Void, Error>) -> Void) {
+        queue.async {
+            guard !self.finished, self.completion == nil else { return }
+            self.completion = completion
+            self.waiting = onPermissionRequired
+            self.connection.onState = { [weak self] state, reason in
+                guard let self, !self.finished else { return }
+                switch state {
+                case .ready: self.finish(.success(()))
+                case .waiting where reason == .localNetworkDenied:
+                    self.pauseConnectivityTimeout()
+                    if !self.reportedPermission {
+                        self.reportedPermission = true
+                        self.waiting?()
+                    }
+                // Waiting errors are nonfatal; NWConnection retries when its path recovers.
+                // A nil path is not proof of denied permission, but must not fail immediately.
+                case .setup, .preparing, .waiting: self.resumeConnectivityTimeout()
+                case let .failed(error): self.finish(.failure(error))
+                case .cancelled: self.finish(.failure(CancellationError()))
+                @unknown default: break
+                }
+            }
+            self.resumeConnectivityTimeout()
+            self.connection.start(queue: self.queue)
+        }
+    }
+
+    public func cancel() {
+        queue.async { self.finish(.failure(CancellationError())) }
+    }
+
+    private func resumeConnectivityTimeout() {
+        guard timeoutDeadline == nil else { return }
+        let deadline = now() + remainingConnectivityTime
+        timeoutDeadline = deadline
+        let work = DispatchWorkItem { [weak self] in
+            guard let self, self.timeoutDeadline == deadline else { return }
+            self.finish(.failure(LocalMediaError("Local connection to the glasses timed out")))
+        }
+        timeoutWork = work
+        scheduleTimeout(remainingConnectivityTime, work)
+    }
+
+    private func pauseConnectivityTimeout() {
+        if let deadline = timeoutDeadline { remainingConnectivityTime = max(0, deadline - now()) }
+        timeoutDeadline = nil
+        timeoutWork?.cancel()
+        timeoutWork = nil
+    }
+
+    private func finish(_ result: Result<Void, Error>) {
+        guard !finished else { return }
+        finished = true
+        pauseConnectivityTimeout()
+        connection.onState = nil
+        connection.cancel()
+        let reply = completion
+        completion = nil
+        waiting = nil
+        reply?(result)
+    }
+}
+
+private final class LocalNetworkPermissionConnection: LocalNetworkAccessConnection {
+    var onState: ((NWConnection.State, NWPath.UnsatisfiedReason?) -> Void)?
+    private let connection: NWConnection
+
+    init(localAddress: String, gateway: String) {
+        let parameters = NWParameters.tcp
+        parameters.requiredLocalEndpoint = .hostPort(host: NWEndpoint.Host(localAddress), port: .any)
+        connection = NWConnection(host: NWEndpoint.Host(gateway), port: 8089, using: parameters)
+    }
+
+    func start(queue: DispatchQueue) {
+        connection.stateUpdateHandler = { [weak self] state in
+            guard let self else { return }
+            onState?(state, connection.currentPath?.unsatisfiedReason)
+        }
+        // The path reason can arrive after a waiting update with no currentPath yet.
+        connection.pathUpdateHandler = { [weak self] path in
+            guard let self else { return }
+            onState?(connection.state, path.unsatisfiedReason)
+        }
+        connection.start(queue: queue)
+    }
+
+    func cancel() {
+        connection.stateUpdateHandler = nil
+        connection.pathUpdateHandler = nil
+        connection.cancel()
+    }
+}

package/ios/CoreKit/Sources/GlassesMediaCore/MacE2EHotspotLease.swift

@@ -0,0 +1,20 @@
+#if MENTRA_E2E
+    import Foundation
+
+    /// Test-build dependency input, not a production network discovery mechanism.
+    /// The Mac harness owns association and verifies the USB fixture, gateway MAC,
+    /// DHCP address, local health and Ethernet before launching this process.
+    public struct MacE2EHotspotLease: Decodable {
+        public let ssid: String
+        public let gateway: String
+        public let address: String
+        public let issuedAt: TimeInterval
+
+        public func matches(ssid: String, gateway: String?, address: String?, now: TimeInterval) -> Bool {
+            let age = now - issuedAt
+            return age >= 0 && age <= 300 && self.gateway == gateway && self.address == address &&
+                LocalMediaPolicy.canReuseHotspot(requestedSSID: ssid, currentSSID: self.ssid,
+                                                 address: address, gateway: gateway)
+        }
+    }
+#endif

package/ios/GlassesHotspotNetwork.swift

@@ -14,11 +14,17 @@ public final class GlassesHotspotNetwork {
     private var gatewayAddress: String?
     private var generation = 0
     private var applying = false
+    private var ownsConfiguration = false
     private var cancelled = false
     private var joinReply: ((Result<String, Error>) -> Void)?
     private var leaveReplies: [() -> Void] = []
     private var monitor: NWPathMonitor?
+    private var localAccess: LocalNetworkAccessRequest?
+    #if MENTRA_E2E
+        private var testLeaseConsumed = false
+    #endif
     public var onLost: ((String) -> Void)?
+    public var onPermissionRequired: (() -> Void)?
     public init() {}
 
     public func join(ssid: String, passphrase: String, gateway: String? = nil, completion: @escaping (Result<String, Error>) -> Void) {
@@ -33,15 +39,58 @@ public final class GlassesHotspotNetwork {
             self.lastHotspotSSID = ssid
             self.gatewayAddress = gateway
             self.cancelled = false
+            self.applying = false
+            self.ownsConfiguration = false
             self.joinReply = completion
-            self.applyConfiguration(ssid: ssid, passphrase: passphrase, generation: gen)
+            if ProcessInfo.processInfo.isiOSAppOnMac {
+                #if MENTRA_E2E
+                    if let raw = ProcessInfo.processInfo.environment["MENTRA_E2E_PREJOINED_HOTSPOT"] {
+                        let address = Self.wifiAddress()
+                        guard !self.testLeaseConsumed,
+                              let lease = try? JSONDecoder().decode(MacE2EHotspotLease.self, from: Data(raw.utf8)),
+                              lease.matches(ssid: ssid, gateway: gateway, address: address, now: Date().timeIntervalSince1970),
+                              let address
+                        else {
+                            self.finishJoin(.failure(LocalMediaError("Mac E2E network lease is invalid, expired or already consumed")))
+                            self.finishLeave()
+                            return
+                        }
+                        self.testLeaseConsumed = true
+                        self.localAddress = address
+                        self.logger.notice("HOTSPOT_JOIN test_harness_connection native_association_untested")
+                        self.startMonitor(generation: gen)
+                        self.waitForLocalAccess(address: address, generation: gen)
+                        return
+                    }
+                #endif
+                NEHotspotNetwork.fetchCurrent { network in
+                    self.queue.async {
+                        guard gen == self.generation, !self.cancelled else { return }
+                        let address = Self.wifiAddress()
+                        if let address, LocalMediaPolicy.canReuseHotspot(requestedSSID: ssid, currentSSID: network?.ssid,
+                                                                         address: address, gateway: gateway)
+                        {
+                            self.localAddress = address
+                            self.logger.info("HOTSPOT_JOIN reuse_verified_macos_connection")
+                            self.startMonitor(generation: gen)
+                            self.waitForLocalAccess(address: address, generation: gen)
+                        } else {
+                            self.applyConfiguration(ssid: ssid, passphrase: passphrase, generation: gen)
+                        }
+                    }
+                }
+            } else {
+                self.applyConfiguration(ssid: ssid, passphrase: passphrase, generation: gen)
+            }
             self.queue.asyncAfter(deadline: .now() + 60) {
-                guard gen == self.generation, self.joinReply != nil else { return }
+                // Once associated, the user may still be reading the Local Network alert.
+                // Its response time is not a hotspot association timeout.
+                guard gen == self.generation, self.joinReply != nil, self.localAccess == nil else { return }
                 self.cancelled = true
                 self.finishJoin(.failure(LocalMediaError("Hotspot join timed out")))
                 // apply() cannot be cancelled. Retain the reservation until its callback and remove the
                 // late configuration before another call is permitted to acquire the network.
-                NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid)
+                if self.ownsConfiguration { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
                 if !self.applying { self.finishLeave() }
             }
         }
@@ -52,7 +101,7 @@ public final class GlassesHotspotNetwork {
             self.cancelled = true
             self.leaveReplies.append(completion)
             self.finishJoin(.failure(LocalMediaError("Hotspot join cancelled")))
-            if let ssid = self.ssid { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
+            if let ssid = self.ssid, self.ownsConfiguration { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
             if !self.applying { self.finishLeave() }
         }
     }
@@ -143,6 +192,7 @@ public final class GlassesHotspotNetwork {
         let config = NEHotspotConfiguration(ssid: ssid, passphrase: passphrase, isWEP: false)
         config.joinOnce = false
         applying = true
+        ownsConfiguration = true
         logger.info("HOTSPOT_JOIN apply_start ios_on_mac=\(ProcessInfo.processInfo.isiOSAppOnMac)")
         NEHotspotConfigurationManager.shared.apply(config) { error in
             self.queue.async {
@@ -176,7 +226,7 @@ public final class GlassesHotspotNetwork {
                 {
                     self.localAddress = address
                     self.startMonitor(generation: gen)
-                    self.finishJoin(.success(address))
+                    self.waitForLocalAccess(address: address, generation: gen)
                 } else if remaining > 0 {
                     self.queue.asyncAfter(deadline: .now() + 0.5) { self.waitForAddress(ssid: ssid, generation: gen, remaining: remaining - 1) }
                 } else {
@@ -201,6 +251,27 @@ public final class GlassesHotspotNetwork {
         monitor.start(queue: queue)
     }
 
+    private func waitForLocalAccess(address: String, generation gen: Int) {
+        let gateway = gatewayAddress ?? address.split(separator: ".").prefix(3).joined(separator: ".") + ".1"
+        let request = LocalNetworkAccessRequest(localAddress: address, gateway: gateway, queue: queue)
+        localAccess = request
+        request.start(onPermissionRequired: { [weak self] in
+            guard let self, gen == generation, !cancelled else { return }
+            NSLog("GLASSES-MEDIA local_network_permission=waiting")
+            onPermissionRequired?()
+        }) { [weak self] result in
+            guard let self, gen == generation, !cancelled else { return }
+            switch result {
+            case .success:
+                NSLog("GLASSES-MEDIA local_network_permission=ready")
+                finishJoin(.success(address))
+            case let .failure(error):
+                finishJoin(.failure(error))
+                finishLeave()
+            }
+        }
+    }
+
     private func finishJoin(_ result: Result<String, Error>) {
         let reply = joinReply
         joinReply = nil
@@ -209,8 +280,10 @@ public final class GlassesHotspotNetwork {
 
     private func finishLeave() {
         generation += 1
+        localAccess?.cancel(); localAccess = nil
         monitor?.cancel(); monitor = nil
-        if let ssid { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
+        if let ssid, ownsConfiguration { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
+        ownsConfiguration = false
         ssid = nil
         localAddress = nil
         gatewayAddress = nil

package/ios/GlassesMediaRelayModule.swift

@@ -74,6 +74,12 @@ private final class ManagedRelaySession {
     {
         ready = completion
         hotspot.onLost = { reason in onState("failed", reason) }
+        hotspot.onPermissionRequired = { [weak self] in
+            self?.queue.async {
+                guard let self, !self.stopped else { return }
+                onState("permission_required", "Allow Local Network access to connect to your glasses. If you previously denied access, enable it in Settings, or cancel to return home.")
+            }
+        }
         hotspot.join(ssid: ssid, passphrase: password, gateway: gateway) { result in
             self.queue.async {
                 guard !self.stopped else { return }
@@ -117,6 +123,7 @@ private final class ManagedRelaySession {
         stopped = true
         finish(.failure(LocalMediaError("Relay cancelled")))
         hotspot.onLost = nil
+        hotspot.onPermissionRequired = nil
         let group = DispatchGroup()
         if let receiver {
             group.enter(); receiver.stop { group.leave() }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/glasses-media",
-  "version": "3.2.1-dev.293",
+  "version": "3.2.1-dev.295",
   "description": "Shared native glasses media receivers and local network transport",
   "license": "MIT",
   "author": "Mentra Community",