@mentra/glasses-media 3.3.0-dev.864 → 3.3.0-dev.874

package/README.md

@@ -4,7 +4,7 @@ Native receivers, WHIP publishers and network helpers shared by the Mentra App.
 
 - Android: the existing `GlassesMediaSource`, local WHIP and WHEP receivers, scoped SoftAP networking, decoded I420/PCM delivery, and transport diagnostics moved here. The ACS session and raw outgoing streams remain in `acs-meeting`.
 - iOS: `DecodedGlassesMediaSource` delivers `CVPixelBuffer` video and interleaved PCM16. `LocalWhipIngestSource` answers the glasses' existing WHIP client; `WhepVideoSource` retains the cloud subscription path.
-- `GlassesHotspotNetwork` uses the same persistent `NEHotspotConfiguration` join as gallery transfers. Wi-Fi carries the glasses link; cellular carries the call. It verifies the joined SSID and the address of the one interface Network framework reports as Wi-Fi (not a fixed `en0`; a Mac can use `en1`), keeps that interface for loss checks and ACS binding, reports network loss, and retains a cancelled join until the uncancellable system callback has been cleaned up.
+- `GlassesHotspotNetwork` owns hotspot association for OTA, gallery transfers and media. iPhone uses persistent `NEHotspotConfiguration`; iOS-on-Mac uses public CoreWLAN in the app process and the standard Location permission needed to identify Wi-Fi networks. Wi-Fi carries the glasses link; cellular carries the call. The owner verifies the requested SSID and actual Wi-Fi interface address, retains that interface for loss checks and ACS binding, and serializes network writers across consumers. Cancellation retains custody until blocking native work and cleanup finish. Cleanup preserves a network the user joined afterward; a failed release rejects and retains ownership for a later cleanup attempt.
 
 The publisher owns its outgoing encoders, audio policy, and destination. Receivers do not open the phone microphone or play the glasses microphone locally. iOS uses a receive-only audio device to drive decoded PCM delivery without changing the app's audio session.
 
@@ -53,6 +53,18 @@ The iOS internet publisher posts its offer on the first server-reflexive candida
 
 Android temporarily lifts the cellular process pin while creating the local WHIP listener, then restores it before starting the outgoing publisher. Otherwise the listener inherits the cellular socket mark and cannot reply to the glasses. The outgoing audio callback supplies its own PCM frame clock: WebRTC's external-recording mode does not pace callbacks and reports zero captured bytes, so the callback fills the entire buffer and waits for the next frame interval without opening the phone microphone.
 
-An attempt-specific ID isolates late callbacks and glasses status. Reconnect tears down the glasses publisher, both phone peers and hotspot before rebuilding against the same provisioned input. Three retries bound consecutive failures; a minute of stable streaming renews the retry budget. Last-subscriber stop cancels startup/backoff, awaits native cleanup and disables the hotspot. Failed cleanup retains ownership and can be retried by stop. BLE-unreachable stop/hotspot commands are deferred until reconnection. ACS and managed streaming share a hotspot reservation. Native media queues keep running when the UI is backgrounded; Android holds a partial wake lock and uses the engine's background timers for retry/readiness.
+An attempt-specific ID isolates late callbacks and glasses status. Reconnect tears down the glasses publisher, both phone peers and hotspot before rebuilding against the same provisioned input. Three retries bound consecutive failures; a minute of stable streaming renews the retry budget. Last-subscriber stop cancels startup/backoff, awaits native cleanup and disables the hotspot. Failed cleanup retains ownership and can be retried by stop. BLE-unreachable stop/hotspot commands are deferred until reconnection. OTA, Gallery, ACS and managed streaming share one hotspot reservation before BLE AP changes or native association. OTA, Gallery and managed relay retain it until their owned cleanup completes. ACS still has an older retirement policy that releases its JavaScript reservation after reporting an unconfirmed stop; native association custody remains retained on failure. Consolidating that ACS retirement is a separate qualification gate. A refused OTA or Gallery caller makes no AP or association changes. Native media queues keep running when the UI is backgrounded; Android holds a partial wake lock and uses the engine's background timers for retry/readiness.
 
 Device qualification for this outgoing pipeline must include Android and iPhone: audio/video playback on the provisioned WHEP URL, mute/video-only capture, last-subscriber stop, cancellation at each setup step, cellular/hotspot/BLE loss and recovery, repeated starts, screen-off/background operation and a sustained thermal/audio-sync run. Unit tests and platform compilation cover lifecycle/format contracts; they do not establish those hardware results.
+
+### Incoming OTA server and outgoing media clients
+
+Hotspot association verifies the glasses SSID and the Wi-Fi interface/address for
+both uses. Gallery and relay clients also wait for outgoing Local Network access
+by connecting to the glasses HTTP endpoint. OTA selects `incoming-server`: it
+serves already downloaded artifacts to connections initiated by the glasses, and
+its own listener must become ready before the app sends the OTA manifest URL.
+It does not depend on the Gallery HTTP server being available. Apple TN3179 lists
+accepting incoming TCP as an operation that does not require Local Network
+permission. This does not change outgoing Gallery/relay consent or the shared
+network ownership and teardown rules.

package/index.d.ts

@@ -0,0 +1,11 @@
+/** Shared native association owner for the local glasses hotspot. */
+export const glassesHotspot: {
+  join(
+    id: string,
+    ssid: string,
+    password: string,
+    gateway?: string,
+    purpose?: "outgoing-client" | "incoming-server",
+  ): Promise<string>
+  leave(id: string): Promise<void>
+}

package/index.js

@@ -1 +1,10 @@
 // Native library. Media stays in native code; publishers consume decoded frames and PCM.
+
+// Load only when this transport is requested. Importing the package does not
+// start a native session or require Expo's application entry point.
+const native = () => require("expo-modules-core").requireNativeModule("MentraGlassesMediaRelay")
+export const glassesHotspot = Object.freeze({
+  join: (id, ssid, password, gateway, purpose = "outgoing-client") =>
+    native().joinLocalHotspot(id, ssid, password, gateway ?? null, purpose),
+  leave: (id) => native().leaveLocalHotspot(id),
+})

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

@@ -0,0 +1,5 @@
+/// The traffic needed after joining the verified glasses Wi-Fi network.
+public enum HotspotAccessPurpose: String {
+    case outgoingClient = "outgoing-client"
+    case incomingServer = "incoming-server"
+}

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

@@ -0,0 +1,22 @@
+import Foundation
+
+/// One process-wide writer across OTA, gallery and native media sessions.
+/// Callers release only after native association and owned cleanup have ended.
+final class HotspotNetworkOwnership {
+    static let shared = HotspotNetworkOwnership()
+    private let lock = NSLock()
+    private var owner: UUID?
+
+    func acquire() -> UUID? {
+        lock.lock(); defer { lock.unlock() }
+        guard owner == nil else { return nil }
+        let token = UUID()
+        owner = token
+        return token
+    }
+
+    func release(_ token: UUID) {
+        lock.lock(); defer { lock.unlock() }
+        if owner == token { owner = nil }
+    }
+}

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

@@ -0,0 +1,161 @@
+import CoreLocation
+import Foundation
+import ObjectiveC
+
+/// Blocking public CoreWLAN calls are isolated here; the existing hotspot owner
+/// retains custody until they return, even after cancellation or a timeout.
+final class MacHotspotAssociation {
+    private let lock = NSLock()
+    private var cancelled = false
+    private var interface: MacWifiInterface?
+    private var joinedSSID: String?
+    private let makeInterface: () throws -> MacWifiInterface
+
+    init(makeInterface: @escaping () throws -> MacWifiInterface = { try PublicCoreWlanInterface() }) {
+        self.makeInterface = makeInterface
+    }
+
+    func associate(ssid: String, password: String) throws -> String {
+        try checkCurrent()
+        let interface = try makeInterface()
+        self.interface = interface
+        if try interface.currentSSID() != ssid {
+            let network = try interface.network(ssid: ssid)
+            try checkCurrent()
+            // Record the intended association before this blocking call. A late
+            // successful join still belongs to us and must be cleaned up.
+            joinedSSID = ssid
+            try interface.associate(network: network, password: password)
+        }
+        try checkCurrent()
+        guard try interface.currentSSID() == ssid else {
+            throw LocalMediaError("Mac Wi-Fi did not associate with the requested glasses hotspot")
+        }
+        return try interface.name()
+    }
+
+    func cancel() {
+        lock.lock(); cancelled = true; lock.unlock()
+    }
+
+    /// Run on the same worker as association, after its blocking call returns.
+    /// A connection the user replaced must never be disconnected by our cleanup.
+    func leave() throws {
+        if let joinedSSID {
+            if try interface?.currentSSID() == joinedSSID {
+                interface?.disassociate()
+                guard try interface?.currentSSID() != joinedSSID else {
+                    throw LocalMediaError("Mac Wi-Fi has not released the glasses hotspot")
+                }
+            }
+        }
+        interface = nil
+        joinedSSID = nil
+    }
+
+    func currentSSID() throws -> String? {
+        try interface?.currentSSID()
+    }
+
+    private func checkCurrent() throws {
+        lock.lock(); let stopped = cancelled; lock.unlock()
+        if stopped { throw CancellationError() }
+    }
+}
+
+protocol MacWifiInterface: AnyObject {
+    func name() throws -> String
+    func currentSSID() throws -> String?
+    func network(ssid: String) throws -> NSObject
+    func associate(network: NSObject, password: String) throws
+    func disassociate()
+}
+
+enum MacWifiInvocation {
+    // Objective-C NSError** parameters use autoreleasing writeback. Strong
+    // pointer storage would over-release errors when the native pool drains.
+    typealias Scan = @convention(c) (AnyObject, Selector, NSData, AutoreleasingUnsafeMutablePointer<NSError?>) -> Unmanaged<NSSet>?
+    typealias Associate = @convention(c) (AnyObject, Selector, AnyObject, NSString, AutoreleasingUnsafeMutablePointer<NSError?>) -> Bool
+}
+
+/// CoreWLAN is a public macOS framework. Foundation loads it only in the Mac
+/// process; Apple dyld permits macOS frameworks in iOS-on-Mac. The checked
+/// Objective-C signatures below are the public CWInterface SDK declarations.
+private final class PublicCoreWlanInterface: MacWifiInterface {
+    private let bundle: Bundle
+    private let interface: NSObject
+    private typealias Disassociate = @convention(c) (AnyObject, Selector) -> Void
+
+    init() throws {
+        guard let bundle = Bundle(path: "/System/Library/Frameworks/CoreWLAN.framework") else {
+            throw LocalMediaError("Mac Wi-Fi framework is unavailable")
+        }
+        do { try bundle.loadAndReturnError() }
+        catch { throw Self.failure("framework loading", error as NSError) }
+        guard let clientClass = NSClassFromString("CWWiFiClient") as? NSObject.Type,
+              clientClass.responds(to: NSSelectorFromString("sharedWiFiClient")),
+              let client = clientClass.perform(NSSelectorFromString("sharedWiFiClient"))?.takeUnretainedValue() as? NSObject,
+              client.responds(to: NSSelectorFromString("interface")),
+              let interface = client.perform(NSSelectorFromString("interface"))?.takeUnretainedValue() as? NSObject
+        else { throw LocalMediaError("Mac Wi-Fi interface is unavailable") }
+        for method in ["interfaceName", "ssidData", "scanForNetworksWithSSID:error:", "associateToNetwork:password:error:", "disassociate"] {
+            guard interface.responds(to: NSSelectorFromString(method)) else {
+                throw LocalMediaError("Mac Wi-Fi interface does not support hotspot association")
+            }
+        }
+        self.interface = interface
+        self.bundle = bundle
+    }
+
+    func name() throws -> String {
+        guard let name = interface.perform(NSSelectorFromString("interfaceName"))?.takeUnretainedValue() as? String,
+              !name.isEmpty else { throw LocalMediaError("Mac Wi-Fi interface has no identity") }
+        return name
+    }
+
+    func currentSSID() throws -> String? {
+        let authorization = CLLocationManager.authorizationStatus()
+        guard MacHotspotAuthorization.isAuthorized(authorization) else {
+            throw LocalMediaError("Location access is required to verify the current Mac Wi-Fi network")
+        }
+        guard let data = interface.perform(NSSelectorFromString("ssidData"))?.takeUnretainedValue() as? Data else { return nil }
+        return String(data: data, encoding: .utf8)
+    }
+
+    func network(ssid: String) throws -> NSObject {
+        let selector = NSSelectorFromString("scanForNetworksWithSSID:error:")
+        let invoke = unsafeBitCast(interface.method(for: selector), to: MacWifiInvocation.Scan.self)
+        var error: NSError?
+        guard let networks = invoke(interface, selector, NSData(data: Data(ssid.utf8)), &error)?.takeUnretainedValue() else {
+            throw Self.failure("scan", error)
+        }
+        // A directed scan can include unrelated networks. Match the requested
+        // SSID bytes without reading or logging BSSID or other scan identities.
+        for case let network as NSObject in networks {
+            guard network.responds(to: NSSelectorFromString("ssidData")),
+                  let data = network.perform(NSSelectorFromString("ssidData"))?.takeUnretainedValue() as? Data,
+                  data == Data(ssid.utf8) else { continue }
+            return network
+        }
+        throw LocalMediaError("The requested glasses hotspot was not found by Mac Wi-Fi")
+    }
+
+    func associate(network: NSObject, password: String) throws {
+        let selector = NSSelectorFromString("associateToNetwork:password:error:")
+        let invoke = unsafeBitCast(interface.method(for: selector), to: MacWifiInvocation.Associate.self)
+        var error: NSError?
+        guard invoke(interface, selector, network, password as NSString, &error) else { throw Self.failure("association", error) }
+    }
+
+    func disassociate() {
+        let selector = NSSelectorFromString("disassociate")
+        let invoke = unsafeBitCast(interface.method(for: selector), to: Disassociate.self)
+        invoke(interface, selector)
+    }
+
+    private static func failure(_ operation: String, _ error: NSError?) -> Error {
+        let domain = error?.domain ?? "unavailable"
+        let safeDomain = domain.range(of: "^[A-Za-z0-9_.-]{1,128}$", options: .regularExpression) == nil ? "unavailable" : domain
+        return LocalMediaError("Mac Wi-Fi \(operation) failed (\(safeDomain), \(error?.code ?? -1))")
+    }
+}

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

@@ -0,0 +1,59 @@
+import CoreLocation
+import Foundation
+
+/// CoreWLAN requires Location authorization to identify the requested network.
+/// Use the app's existing system permission, with no separate connection screen.
+final class MacHotspotAuthorization: NSObject, CLLocationManagerDelegate {
+    private var manager: CLLocationManager?
+    private var completion: ((Result<Void, Error>) -> Void)?
+    private var finished = false
+
+    func start(completion: @escaping (Result<Void, Error>) -> Void) {
+        DispatchQueue.main.async {
+            guard !self.finished else { completion(.failure(CancellationError())); return }
+            self.completion = completion
+            let manager = CLLocationManager()
+            self.manager = manager
+            manager.delegate = self
+            self.handle(manager.authorizationStatus)
+            if manager.authorizationStatus == .notDetermined { manager.requestWhenInUseAuthorization() }
+        }
+    }
+
+    func cancel() {
+        DispatchQueue.main.async { self.finish(.failure(CancellationError())) }
+    }
+
+    func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
+        handle(manager.authorizationStatus)
+    }
+
+    static func isAuthorized(_ status: CLAuthorizationStatus) -> Bool {
+        if status == .authorizedAlways { return true }
+        #if !os(macOS)
+            if status == .authorizedWhenInUse { return true }
+        #endif
+        return false
+    }
+
+    private func handle(_ status: CLAuthorizationStatus) {
+        if Self.isAuthorized(status) { finish(.success(())); return }
+        switch status {
+        case .denied, .restricted:
+            finish(.failure(LocalMediaError("Location access is required to identify the glasses hotspot on Mac")))
+        case .notDetermined: break
+        default:
+            finish(.failure(LocalMediaError("Mac hotspot Location authorization is unavailable")))
+        }
+    }
+
+    private func finish(_ result: Result<Void, Error>) {
+        guard !finished else { return }
+        finished = true
+        manager?.delegate = nil
+        manager = nil
+        let reply = completion
+        completion = nil
+        reply?(result)
+    }
+}

package/ios/GlassesHotspotNetwork.swift

@@ -4,7 +4,7 @@ import Network
 import NetworkExtension
 import OSLog
 
-/// Same persistent hotspot join as gallery (`joinOnce=false`). Only local traffic uses Wi-Fi.
+/// Shared hotspot association owner. Only local glasses traffic uses Wi-Fi.
 public final class GlassesHotspotNetwork {
     private let logger = Logger(subsystem: "com.mentra.glassesmedia", category: "hotspot")
     private let queue = DispatchQueue(label: "com.mentra.glassesmedia.hotspot")
@@ -12,81 +12,57 @@ public final class GlassesHotspotNetwork {
     private var lastHotspotSSID: String?
     /// The verified Wi-Fi interface and DHCP address. Every later check uses this exact pair.
     private var binding: HotspotInterfaceBinding?
+    private var accessPurpose: HotspotAccessPurpose = .outgoingClient
     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 leaveReplies: [(Result<Void, Error>) -> Void] = []
     private var interfaceMonitors: [NWPathMonitor] = []
     /// Wi-Fi identity learned since this join started; replaced on every join and cleared on leave.
     private var wifiIdentity = HotspotWifiIdentity()
-    private var monitorsReported: [Bool] = []
-    private var interfaceReportsReady: (() -> Void)?
     private var localAccess: LocalNetworkAccessRequest?
-    private var localAddress: String? { binding?.address }
-    #if MENTRA_E2E
-        private var testLeaseConsumed = false
-    #endif
+    private var localAddress: String? {
+        binding?.address
+    }
+
+    private let macWorker = DispatchQueue(label: "com.mentra.glassesmedia.mac-wifi")
+    private var macAssociation: MacHotspotAssociation?
+    private var macAuthorization: MacHotspotAuthorization?
+    private var ownershipToken: UUID?
+    private var finishingLeave = false
     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) {
+    public func join(ssid: String, passphrase: String, gateway: String? = nil, purpose: HotspotAccessPurpose = .outgoingClient, completion: @escaping (Result<String, Error>) -> Void) {
         queue.async {
             guard self.ssid == nil, !self.applying else { completion(.failure(LocalMediaError("Previous hotspot session has not finished cleaning up"))); return }
             if let gateway, !LocalMediaPolicy.isPrivate(gateway) {
                 completion(.failure(LocalMediaError("The glasses reported an invalid hotspot gateway"))); return
             }
+            if ProcessInfo.processInfo.isiOSAppOnMac, gateway == nil {
+                completion(.failure(LocalMediaError("The glasses did not report their hotspot gateway"))); return
+            }
+            guard let token = HotspotNetworkOwnership.shared.acquire() else {
+                completion(.failure(LocalMediaError("The glasses hotspot is already in use"))); return
+            }
+            self.ownershipToken = token
             self.generation += 1
             let gen = self.generation
             self.ssid = ssid
             self.lastHotspotSSID = ssid
             self.gatewayAddress = gateway
+            self.accessPurpose = purpose
             self.cancelled = false
             self.applying = false
             self.ownsConfiguration = false
             self.joinReply = completion
             self.startInterfaceMonitors(generation: gen)
             if ProcessInfo.processInfo.isiOSAppOnMac {
-                // Reuse is decided once, so it needs the interface types first.
-                self.awaitInterfaceReports(generation: gen) {
-                    #if MENTRA_E2E
-                        if let raw = ProcessInfo.processInfo.environment["MENTRA_E2E_PREJOINED_HOTSPOT"] {
-                            let selected = self.selectBinding()
-                            guard !self.testLeaseConsumed,
-                                  let lease = try? JSONDecoder().decode(MacE2EHotspotLease.self, from: Data(raw.utf8)),
-                                  lease.matches(ssid: ssid, gateway: gateway, address: selected?.address, now: Date().timeIntervalSince1970),
-                                  let selected
-                            else {
-                                self.finishJoin(.failure(LocalMediaError("Mac E2E network lease is invalid, expired or already consumed")))
-                                self.finishLeave()
-                                return
-                            }
-                            self.testLeaseConsumed = true
-                            self.bind(selected)
-                            self.logger.notice("HOTSPOT_JOIN test_harness_connection native_association_untested")
-                            self.waitForLocalAccess(address: selected.address, generation: gen)
-                            return
-                        }
-                    #endif
-                    NEHotspotNetwork.fetchCurrent { network in
-                        self.queue.async {
-                            guard gen == self.generation, !self.cancelled else { return }
-                            let selected = self.selectBinding()
-                            if let selected, LocalMediaPolicy.canReuseHotspot(requestedSSID: ssid, currentSSID: network?.ssid,
-                                                                              address: selected.address, gateway: gateway)
-                            {
-                                self.bind(selected)
-                                self.logger.info("HOTSPOT_JOIN reuse_verified_macos_connection")
-                                self.waitForLocalAccess(address: selected.address, generation: gen)
-                            } else {
-                                self.applyConfiguration(ssid: ssid, passphrase: passphrase, generation: gen)
-                            }
-                        }
-                    }
-                }
+                self.authorizeMacAssociation(ssid: ssid, passphrase: passphrase, generation: gen)
             } else {
                 self.applyConfiguration(ssid: ssid, passphrase: passphrase, generation: gen)
             }
@@ -95,6 +71,8 @@ public final class GlassesHotspotNetwork {
                 // 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.macAssociation?.cancel()
+                self.macAuthorization?.cancel()
                 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.
@@ -104,9 +82,11 @@ public final class GlassesHotspotNetwork {
         }
     }
 
-    public func leave(completion: @escaping () -> Void) {
+    public func leave(completion: @escaping (Result<Void, Error>) -> Void) {
         queue.async {
             self.cancelled = true
+            self.macAssociation?.cancel()
+            self.macAuthorization?.cancel()
             self.leaveReplies.append(completion)
             self.finishJoin(.failure(LocalMediaError("Hotspot join cancelled")))
             if let ssid = self.ssid, self.ownsConfiguration { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
@@ -119,7 +99,16 @@ public final class GlassesHotspotNetwork {
     public func verifiedAddress(completion: @escaping (String?) -> Void) {
         queue.async {
             guard let binding = self.binding, !self.cancelled, self.isBindingIntact(binding) else { completion(nil); return }
-            completion(binding.address)
+            if let association = self.macAssociation {
+                let ssid = self.ssid
+                let gen = self.generation
+                self.macWorker.async {
+                    let matched = (try? association.currentSSID()) == ssid
+                    self.queue.async {
+                        completion(gen == self.generation && !self.cancelled && matched && self.isBindingIntact(binding) ? binding.address : nil)
+                    }
+                }
+            } else { completion(binding.address) }
         }
     }
 
@@ -205,6 +194,72 @@ public final class GlassesHotspotNetwork {
         }
     }
 
+    private func authorizeMacAssociation(ssid: String, passphrase: String, generation gen: Int) {
+        let authorization = MacHotspotAuthorization()
+        macAuthorization = authorization
+        authorization.start { result in
+            self.queue.async {
+                guard gen == self.generation, !self.cancelled else { return }
+                self.macAuthorization = nil
+                switch result {
+                case .success: self.applyMacAssociation(ssid: ssid, passphrase: passphrase, generation: gen)
+                case let .failure(error):
+                    self.finishJoin(.failure(error)); self.finishLeave()
+                }
+            }
+        }
+    }
+
+    private func applyMacAssociation(ssid: String, passphrase: String, generation gen: Int) {
+        let association = MacHotspotAssociation()
+        macAssociation = association
+        applying = true
+        macWorker.async {
+            let result = Result { try association.associate(ssid: ssid, password: passphrase) }
+            self.queue.async {
+                guard gen == self.generation else { return }
+                self.applying = false
+                if self.cancelled { self.finishLeave(); return }
+                switch result {
+                case let .success(name):
+                    let index = Int(if_nametoindex(name))
+                    guard index > 0 else {
+                        self.finishJoin(.failure(LocalMediaError("Mac Wi-Fi interface disappeared during association")))
+                        self.finishLeave(); return
+                    }
+                    self.wifiIdentity.observe([HotspotInterfaceReport(name: name, index: index, isWifi: true)])
+                    self.waitForMacAddress(ssid: ssid, association: association, generation: gen, remaining: 60)
+                case let .failure(error):
+                    self.finishJoin(.failure(error)); self.finishLeave()
+                }
+            }
+        }
+    }
+
+    private func waitForMacAddress(ssid: String, association: MacHotspotAssociation, generation gen: Int, remaining: Int) {
+        guard gen == generation, !cancelled else { return }
+        macWorker.async {
+            let membership = Result { try association.currentSSID() == ssid }
+            self.queue.async {
+                guard gen == self.generation, !self.cancelled else { return }
+                if case let .failure(error) = membership {
+                    self.finishJoin(.failure(error)); self.finishLeave(); return
+                }
+                if (try? membership.get()) == true, let selected = self.selectBinding() {
+                    self.bind(selected)
+                    self.finishAssociation(address: selected.address, generation: gen)
+                } else if remaining > 0 {
+                    self.queue.asyncAfter(deadline: .now() + 0.5) {
+                        self.waitForMacAddress(ssid: ssid, association: association, generation: gen, remaining: remaining - 1)
+                    }
+                } else {
+                    self.finishJoin(.failure(LocalMediaError("Mac Wi-Fi has no verified glasses hotspot address")))
+                    self.finishLeave()
+                }
+            }
+        }
+    }
+
     private func applyConfiguration(ssid: String, passphrase: String, generation gen: Int) {
         let config = NEHotspotConfiguration(ssid: ssid, passphrase: passphrase, isWEP: false)
         config.joinOnce = false
@@ -241,7 +296,7 @@ public final class GlassesHotspotNetwork {
                 // The selection applies the BLE gateway's client check when one was reported.
                 if network?.ssid == ssid, let selected = self.selectBinding() {
                     self.bind(selected)
-                    self.waitForLocalAccess(address: selected.address, generation: gen)
+                    self.finishAssociation(address: selected.address, generation: gen)
                 } else if remaining > 0 {
                     self.queue.asyncAfter(deadline: .now() + 0.5) { self.waitForAddress(ssid: ssid, generation: gen, remaining: remaining - 1) }
                 } else {
@@ -264,15 +319,12 @@ public final class GlassesHotspotNetwork {
         let monitors = [NWPathMonitor(requiredInterfaceType: .wifi), NWPathMonitor()]
         interfaceMonitors = monitors
         wifiIdentity = HotspotWifiIdentity()
-        monitorsReported = Array(repeating: false, count: monitors.count)
-        for (index, monitor) in monitors.enumerated() {
+        for monitor in monitors {
             monitor.pathUpdateHandler = { [weak self] path in
                 guard let self, gen == self.generation else { return }
                 self.wifiIdentity.observe(path.availableInterfaces.map {
                     HotspotInterfaceReport(name: $0.name, index: $0.index, isWifi: $0.type == .wifi)
                 })
-                self.monitorsReported[index] = true
-                if !self.monitorsReported.contains(false) { self.fireInterfaceReportsReady() }
                 // This AP intentionally has no internet. Loss of its default internet path is not
                 // loss of the local link; check the verified interface and address instead.
                 if let binding = self.binding, !self.cancelled, !self.isBindingIntact(binding) {
@@ -283,25 +335,6 @@ public final class GlassesHotspotNetwork {
         }
     }
 
-    /// Continue once every monitor has reported, or after a short bound with whatever arrived.
-    private func awaitInterfaceReports(generation gen: Int, then proceed: @escaping () -> Void) {
-        interfaceReportsReady = { [weak self] in
-            guard let self, gen == self.generation, !self.cancelled else { return }
-            proceed()
-        }
-        if !monitorsReported.contains(false) { fireInterfaceReportsReady(); return }
-        queue.asyncAfter(deadline: .now() + 2) { [weak self] in
-            guard let self, gen == self.generation else { return }
-            self.fireInterfaceReportsReady()
-        }
-    }
-
-    private func fireInterfaceReportsReady() {
-        let ready = interfaceReportsReady
-        interfaceReportsReady = nil
-        ready?()
-    }
-
     /// Every check samples interfaces first, so a detach or replacement between path updates
     /// is recorded in the session identity before it is used.
     private func observeInterfaces() -> HotspotInterfaceSnapshot {
@@ -338,6 +371,17 @@ public final class GlassesHotspotNetwork {
             "other private IPv4=\(other.isEmpty ? "none" : other.sorted().joined(separator: ","))"
     }
 
+    private func finishAssociation(address: String, generation gen: Int) {
+        // OTA serves incoming TCP. Its native listener proves server readiness; dialing
+        // the glasses' unrelated Gallery server would add a client permission dependency.
+        // TN3179: accepting incoming TCP does not require Local Network access.
+        if accessPurpose == .incomingServer {
+            finishJoin(.success(address))
+        } else {
+            waitForLocalAccess(address: address, generation: gen)
+        }
+    }
+
     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)
@@ -366,21 +410,50 @@ public final class GlassesHotspotNetwork {
     }
 
     private func finishLeave() {
+        guard !finishingLeave else { return }
+        finishingLeave = true
+        if let association = macAssociation {
+            association.cancel()
+            // This queue is also the association queue: cleanup cannot overtake
+            // a blocking scan/join, and process-wide ownership remains held.
+            macWorker.async {
+                let result = Result { try association.leave() }
+                self.queue.async {
+                    switch result {
+                    case .success:
+                        self.macAssociation = nil
+                        self.completeLeave()
+                    case let .failure(error):
+                        // Retain the owner when we cannot prove which association
+                        // cleanup would disconnect. A later leave can retry safely.
+                        self.finishingLeave = false
+                        let replies = self.leaveReplies
+                        self.leaveReplies.removeAll()
+                        replies.forEach { $0(.failure(error)) }
+                    }
+                }
+            }
+        } else { completeLeave() }
+    }
+
+    private func completeLeave() {
         generation += 1
+        macAuthorization?.cancel(); macAuthorization = nil
         localAccess?.cancel(); localAccess = nil
         interfaceMonitors.forEach { $0.cancel() }
         interfaceMonitors = []
         wifiIdentity = HotspotWifiIdentity()
-        monitorsReported = []
-        interfaceReportsReady = nil
         if let ssid, ownsConfiguration { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
         ownsConfiguration = false
         ssid = nil
         binding = nil
         gatewayAddress = nil
+        finishingLeave = false
+        if let token = ownershipToken { HotspotNetworkOwnership.shared.release(token) }
+        ownershipToken = nil
         let replies = leaveReplies
         leaveReplies.removeAll()
-        replies.forEach { $0() }
+        replies.forEach { $0(.success(())) }
     }
 
     /// Every attached interface's kernel index and link type (its AF_LINK row) and every IPv4

package/ios/GlassesMedia.podspec

@@ -14,7 +14,7 @@ Pod::Spec.new do |s|
   s.dependency 'ExpoModulesCore'
   # Keep in sync with the iOS-only @livekit/react-native-webrtc podspec patch.
   s.dependency 'WebRTC-SDK', '144.7559.15'
-  s.frameworks = 'AVFoundation', 'CoreMedia', 'CoreVideo', 'Network', 'NetworkExtension'
+  s.frameworks = 'AVFoundation', 'CoreMedia', 'CoreVideo', 'CoreLocation', 'Network', 'NetworkExtension'
   s.source_files = '*.{swift,h,m,mm}', 'CoreKit/Sources/GlassesMediaCore/*.swift'
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
 end

package/ios/GlassesMediaRelayModule.swift

@@ -4,11 +4,47 @@ import Foundation
 public final class GlassesMediaRelayModule: Module {
     private let queue = DispatchQueue(label: "com.mentra.glassesmedia.relay")
     private var session: ManagedRelaySession?
+    private let localHotspot = GlassesHotspotNetwork()
+    private var localHotspotOwner: String?
 
     public func definition() -> ModuleDefinition {
         Name("MentraGlassesMediaRelay")
         Events("onRelayState")
 
+        AsyncFunction("joinLocalHotspot") { (id: String, ssid: String, password: String, gateway: String?, purpose: String, promise: Promise) in
+            self.queue.async {
+                guard self.localHotspotOwner == nil else {
+                    promise.reject(LocalMediaError("Previous hotspot session has not been released")); return
+                }
+                guard let accessPurpose = HotspotAccessPurpose(rawValue: purpose) else {
+                    promise.reject(LocalMediaError("Invalid hotspot access purpose")); return
+                }
+                self.localHotspotOwner = id
+                self.localHotspot.join(ssid: ssid, passphrase: password, gateway: gateway, purpose: accessPurpose) { result in
+                    switch result {
+                    case let .success(address): promise.resolve(address)
+                    case let .failure(error): promise.reject(error)
+                    }
+                }
+            }
+        }
+
+        AsyncFunction("leaveLocalHotspot") { (id: String, promise: Promise) in
+            self.queue.async {
+                guard self.localHotspotOwner == id else { promise.resolve(nil); return }
+                self.localHotspot.leave { result in
+                    self.queue.async {
+                        switch result {
+                        case .success:
+                            if self.localHotspotOwner == id { self.localHotspotOwner = nil }
+                            promise.resolve(nil)
+                        case let .failure(error): promise.reject(error)
+                        }
+                    }
+                }
+            }
+        }
+
         AsyncFunction("prepare") { (options: [String: Any], promise: Promise) in
             guard let id = options["attemptId"] as? String,
                   let ingest = options["ingestUrl"] as? String, let url = URL(string: ingest), url.scheme == "https",
@@ -38,16 +74,23 @@ public final class GlassesMediaRelayModule: Module {
         AsyncFunction("stop") { (id: String, promise: Promise) in
             self.queue.async {
                 guard let session = self.session, session.id == id else { promise.resolve(nil); return }
-                session.stop {
-                    if self.session === session { self.session = nil }
-                    promise.resolve(nil)
+                session.stop { result in
+                    switch result {
+                    case .success:
+                        if self.session === session { self.session = nil }
+                        promise.resolve(nil)
+                    case let .failure(error): promise.reject(error)
+                    }
                 }
             }
         }
 
         OnDestroy {
             self.queue.async {
-                self.session?.stop { self.session = nil }
+                self.session?.stop { result in
+                    if case .success = result { self.session = nil }
+                }
+                self.localHotspot.leave { _ in }
             }
         }
     }
@@ -62,7 +105,7 @@ private final class ManagedRelaySession {
     private var publisher: PhoneWhipPublisher?
     private var stopped = false
     private var stopFinished = false
-    private var stopReplies: [() -> Void] = []
+    private var stopReplies: [(Result<Void, Error>) -> Void] = []
     private var ready: ((Result<String, Error>) -> Void)?
 
     init(id: String, queue: DispatchQueue) {
@@ -116,10 +159,11 @@ private final class ManagedRelaySession {
         let callback = ready; ready = nil; callback?(result)
     }
 
-    func stop(completion: @escaping () -> Void) {
-        if stopFinished { completion(); return }
+    func stop(completion: @escaping (Result<Void, Error>) -> Void) {
+        if stopFinished { completion(.success(())); return }
+        let stopping = !stopReplies.isEmpty
         stopReplies.append(completion)
-        guard !stopped else { return }
+        guard !stopping else { return }
         stopped = true
         finish(.failure(LocalMediaError("Relay cancelled")))
         hotspot.onLost = nil
@@ -131,10 +175,14 @@ private final class ManagedRelaySession {
         if let publisher {
             group.enter(); publisher.stop { group.leave() }
         }
-        group.enter(); hotspot.leave { group.leave() }
+        var cleanupResult: Result<Void, Error> = .success(())
+        group.enter(); hotspot.leave { result in
+            self.queue.async { cleanupResult = result; group.leave() }
+        }
         group.notify(queue: queue) {
-            self.receiver = nil; self.publisher = nil; self.stopFinished = true
-            let replies = self.stopReplies; self.stopReplies.removeAll(); replies.forEach { $0() }
+            self.receiver = nil; self.publisher = nil
+            if case .success = cleanupResult { self.stopFinished = true }
+            let replies = self.stopReplies; self.stopReplies.removeAll(); replies.forEach { $0(cleanupResult) }
         }
     }
 }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@mentra/glasses-media",
-  "version": "3.3.0-dev.864",
+  "version": "3.3.0-dev.874",
   "description": "Shared native glasses media receivers and local network transport",
   "license": "MIT",
   "author": "Mentra Community",
   "homepage": "https://github.com/Mentra-Community/MentraOS",
   "main": "index.js",
+  "types": "index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Mentra-Community/MentraOS.git",
@@ -14,8 +15,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "peerDependencies": {
+    "expo-modules-core": "~55.0.25"
+  },
   "files": [
     "index.js",
+    "index.d.ts",
     "expo-module.config.json",
     "android/build.gradle",
     "android/src/main",

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

@@ -1,20 +0,0 @@
-#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