@mentra/glasses-media 3.2.1 → 3.3.0-beta.1001

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,81 +4,65 @@ 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")
     private var ssid: String?
     private var lastHotspotSSID: String?
-    private var localAddress: 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 monitor: NWPathMonitor?
+    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 localAccess: LocalNetworkAccessRequest?
-    #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 {
-                #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)
-                        }
-                    }
-                }
+                self.authorizeMacAssociation(ssid: ssid, passphrase: passphrase, generation: gen)
             } else {
                 self.applyConfiguration(ssid: ssid, passphrase: passphrase, generation: gen)
             }
@@ -87,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.
@@ -96,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) }
@@ -106,6 +94,24 @@ public final class GlassesHotspotNetwork {
         }
     }
 
+    /// The verified hotspot address while its own Wi-Fi interface still holds it; nil after
+    /// loss, leave or an address change. Never falls back to another interface.
+    public func verifiedAddress(completion: @escaping (String?) -> Void) {
+        queue.async {
+            guard let binding = self.binding, !self.cancelled, self.isBindingIntact(binding) else { completion(nil); return }
+            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) }
+        }
+    }
+
     public func info(completion: @escaping ([String: Any]) -> Void) {
         queue.async {
             var value: [String: Any] = ["available": self.localAddress != nil]
@@ -124,7 +130,7 @@ public final class GlassesHotspotNetwork {
             let parameters = NWParameters.tcp
             if ProcessInfo.processInfo.isiOSAppOnMac {
                 // The Mac route probe rejects the Wi-Fi type constraint on an otherwise
-                // usable en0 route. Restrict this connection to the verified source IP.
+                // usable hotspot route. Restrict this connection to the verified source IP.
                 parameters.requiredLocalEndpoint = .hostPort(host: NWEndpoint.Host(address), port: .any)
             } else {
                 parameters.requiredInterfaceType = .wifi
@@ -188,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
@@ -221,34 +293,93 @@ public final class GlassesHotspotNetwork {
         NEHotspotNetwork.fetchCurrent { [weak self] network in
             self?.queue.async {
                 guard let self, gen == self.generation, !self.cancelled else { return }
-                if network?.ssid == ssid, let address = Self.wifiAddress(),
-                   self.gatewayAddress.map({ LocalMediaPolicy.isHotspotClientAddress(address, gateway: $0) }) ?? true
-                {
-                    self.localAddress = address
-                    self.startMonitor(generation: gen)
-                    self.waitForLocalAccess(address: address, generation: gen)
+                // 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.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 {
                     let association = network == nil ? "unavailable" : (network?.ssid == ssid ? "matched" : "different")
-                    let address = Self.wifiAddress() ?? "none"
-                    self.finishJoin(.failure(LocalMediaError("Glasses hotspot has no verified Wi-Fi address (SSID=\(association), Wi-Fi IPv4=\(address))")))
+                    self.finishJoin(.failure(LocalMediaError("Glasses hotspot has no verified Wi-Fi address (SSID=\(association), \(self.wifiDiagnostic()))")))
                     self.finishLeave()
                 }
             }
         }
     }
 
-    private func startMonitor(generation gen: Int) {
-        let monitor = NWPathMonitor(requiredInterfaceType: .wifi)
-        self.monitor = monitor
-        monitor.pathUpdateHandler = { [weak self] _ in
-            guard let self, gen == generation, !self.cancelled else { return }
-            // This AP intentionally has no internet. Loss of its default internet path is not
-            // loss of the local link; use the actual interface address instead.
-            if Self.wifiAddress() != localAddress { onLost?("Glasses hotspot connection was lost") }
+    /// iOS can omit an internet-less Wi-Fi from its default path, and iOS-on-Mac has rejected
+    /// a Wi-Fi type constraint on a usable hotspot route. Both paths' interface types feed one
+    /// session identity (HotspotWifiIdentity): a positive Wi-Fi report outlives later omission
+    /// only while the same interface stays attached; contrary reports and replacement fail closed.
+    /// A phone that starts on cellular never gets a report; HotspotInterfacePolicy then uses
+    /// the hotspot client address as the evidence.
+    private func startInterfaceMonitors(generation gen: Int) {
+        interfaceMonitors.forEach { $0.cancel() }
+        let monitors = [NWPathMonitor(requiredInterfaceType: .wifi), NWPathMonitor()]
+        interfaceMonitors = monitors
+        wifiIdentity = HotspotWifiIdentity()
+        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)
+                })
+                // 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) {
+                    self.onLost?("Glasses hotspot connection was lost")
+                }
+            }
+            monitor.start(queue: queue)
+        }
+    }
+
+    /// 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 {
+        let snapshot = Self.interfaceSnapshot()
+        wifiIdentity.observe(snapshot)
+        return snapshot
+    }
+
+    private func selectBinding() -> HotspotInterfaceBinding? {
+        HotspotInterfacePolicy.select(snapshot: observeInterfaces(), identity: wifiIdentity, gateway: gatewayAddress)
+    }
+
+    private func isBindingIntact(_ binding: HotspotInterfaceBinding) -> Bool {
+        let snapshot = observeInterfaces()
+        return HotspotInterfacePolicy.isIntact(binding, snapshot: snapshot, identity: wifiIdentity)
+    }
+
+    private func bind(_ selected: HotspotInterfaceBinding) {
+        let evidence = wifiIdentity.trusted[selected.interface] == selected.index ? "wifi_report" : "hotspot_client"
+        wifiIdentity.adopt(selected)
+        binding = selected
+        logger.info("HOTSPOT_JOIN address_verified interface=\(selected.interface, privacy: .public) evidence=\(evidence, privacy: .public)")
+    }
+
+    /// Interface names and their IPv4 addresses only; never credentials or SSIDs.
+    private func wifiDiagnostic() -> String {
+        let snapshot = observeInterfaces()
+        let wifi = Set(wifiIdentity.trusted.keys)
+        let addresses = snapshot.addresses.filter { wifi.contains($0.name) }.map { "\($0.name)=\($0.ipv4)" }
+        let other = snapshot.addresses.filter { !wifi.contains($0.name) && LocalMediaPolicy.isPrivate($0.ipv4) }
+            .map { "\($0.name)\(snapshot.ethernetLinks.contains($0.name) ? "" : "(non-ethernet)")=\($0.ipv4)" }
+        return "Wi-Fi interfaces=\(wifi.isEmpty ? "none" : wifi.sorted().joined(separator: ",")), " +
+            "Wi-Fi IPv4=\(addresses.isEmpty ? "none" : addresses.sorted().joined(separator: ",")), " +
+            "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)
         }
-        monitor.start(queue: queue)
     }
 
     private func waitForLocalAccess(address: String, generation gen: Int) {
@@ -279,34 +410,84 @@ 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
-        monitor?.cancel(); monitor = nil
+        interfaceMonitors.forEach { $0.cancel() }
+        interfaceMonitors = []
+        wifiIdentity = HotspotWifiIdentity()
         if let ssid, ownsConfiguration { NEHotspotConfigurationManager.shared.removeConfiguration(forSSID: ssid) }
         ownsConfiguration = false
         ssid = nil
-        localAddress = 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(())) }
     }
 
-    public static func wifiAddress() -> String? {
+    /// Every attached interface's kernel index and link type (its AF_LINK row) and every IPv4
+    /// address with its interface name and up state. Selection belongs to HotspotInterfacePolicy;
+    /// an interface name alone never identifies Wi-Fi. A failed read yields an empty sample, which
+    /// fails closed.
+    static func interfaceSnapshot() -> HotspotInterfaceSnapshot {
         var interfaces: UnsafeMutablePointer<ifaddrs>?
-        guard getifaddrs(&interfaces) == 0 else { return nil }
+        guard getifaddrs(&interfaces) == 0 else { return HotspotInterfaceSnapshot(links: [:], addresses: []) }
         defer { freeifaddrs(interfaces) }
+        var links: [String: Int] = [:]
+        var ethernetLinks: Set<String> = []
+        var rows: [HotspotInterfaceAddress] = []
         var cursor = interfaces
         while let item = cursor {
             defer { cursor = item.pointee.ifa_next }
             let value = item.pointee
-            guard String(cString: value.ifa_name) == "en0", value.ifa_flags & UInt32(IFF_UP) != 0,
-                  let address = value.ifa_addr, address.pointee.sa_family == UInt8(AF_INET) else { continue }
+            guard let address = value.ifa_addr else { continue }
+            let name = String(cString: value.ifa_name)
+            if address.pointee.sa_family == UInt8(AF_LINK) {
+                let (index, type) = address.withMemoryRebound(to: sockaddr_dl.self, capacity: 1) {
+                    (Int($0.pointee.sdl_index), Int32($0.pointee.sdl_type))
+                }
+                if index > 0 {
+                    links[name] = index
+                    if type == IFT_ETHER { ethernetLinks.insert(name) }
+                }
+                continue
+            }
+            guard address.pointee.sa_family == UInt8(AF_INET) else { continue }
             var host = [CChar](repeating: 0, count: Int(NI_MAXHOST))
             guard getnameinfo(address, socklen_t(address.pointee.sa_len), &host, socklen_t(host.count), nil, 0, NI_NUMERICHOST) == 0 else { continue }
-            let ip = String(cString: host)
-            if LocalMediaPolicy.isPrivate(ip) { return ip }
+            rows.append(HotspotInterfaceAddress(name: name, isUp: value.ifa_flags & UInt32(IFF_UP) != 0, ipv4: String(cString: host)))
         }
-        return nil
+        return HotspotInterfaceSnapshot(links: links, addresses: rows, ethernetLinks: ethernetLinks)
     }
 }