@mentra/glasses-media 3.2.1-dev.314 → 3.3.0-beta.1000

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

@@ -0,0 +1,204 @@
+import Foundation
+
+/// The frame-agnostic half of `DecodedFrameTap`: sink ownership, failure isolation and metrics.
+///
+/// The call owns the decoder; a preview sink is a guest. `offer` never lets a thrown error reach
+/// the decoder thread, and with no sink attached and telemetry off it costs one uncontended lock
+/// around a single reference load (Swift has no portable atomics for iOS 15).
+/// Swift runtime traps (force-unwraps, bounds failures) are process failures and cannot be caught
+/// here; the preview prevents them by validating geometry before touching memory.
+public final class DecodedFrameTapCore<Frame> {
+    /// A snapshot of decoder-thread observations, drained by the reader.
+    public struct Metrics {
+        public let framesOffered: Int
+        public let framesWithSink: Int
+        public let offerTotalNs: Int64
+        public let offerMaxNs: Int64
+        public let cadenceSamples: Int
+        public let cadenceTotalNs: Int64
+        public let cadenceMaxNs: Int64
+        public let sinkExceptions: Int
+        /// Frames the ACS sender accepted, recorded at its call sites after `offer`.
+        public let acsFramesSent: Int
+
+        /// Mean time inside `offer` over every timed frame, with or without a sink.
+        public var offerMeanUs: Double {
+            framesOffered > 0 ? Double(offerTotalNs) / Double(framesOffered) / 1000.0 : 0
+        }
+
+        public var offerMaxUs: Double { Double(offerMaxNs) / 1000.0 }
+
+        public var cadenceMeanMs: Double {
+            cadenceSamples > 0 ? Double(cadenceTotalNs) / Double(cadenceSamples) / 1_000_000.0 : 0
+        }
+
+        public var cadenceMaxMs: Double { Double(cadenceMaxNs) / 1_000_000.0 }
+    }
+
+    private final class State {
+        let sink: ((Frame) throws -> Void)?
+        let onSinkError: ((Error) -> Void)?
+        init(sink: ((Frame) throws -> Void)?, onSinkError: ((Error) -> Void)?) {
+            self.sink = sink
+            self.onSinkError = onSinkError
+        }
+    }
+
+    private let stateLock = NSLock()
+    /// Replaced wholesale, never mutated, so `offer` reads one reference under a short lock.
+    private var state: State?
+    private var generation: UInt64 = 0
+    private var sink: ((Frame) throws -> Void)?
+    private var onSinkError: ((Error) -> Void)?
+    public private(set) var telemetryEnabled = false
+
+    private let metricsLock = NSLock()
+    private var framesOffered = 0
+    private var framesWithSink = 0
+    private var offerTotalNs: Int64 = 0
+    private var offerMaxNs: Int64 = 0
+    private var cadenceSamples = 0
+    private var cadenceTotalNs: Int64 = 0
+    private var cadenceMaxNs: Int64 = 0
+    private var sinkExceptions = 0
+    private var acsFramesSent = 0
+    private var lastOfferAtNs: Int64 = 0
+
+    private let clock: () -> Int64
+
+    public init(clock: @escaping () -> Int64 = { Int64(DispatchTime.now().uptimeNanoseconds) }) {
+        self.clock = clock
+    }
+
+    /// Install the sink and return the generation that owns it. `onSinkError` runs on the decoder
+    /// thread after a thrown error has been caught and counted; it must only schedule work.
+    @discardableResult
+    public func attach(_ sink: @escaping (Frame) throws -> Void, onSinkError: ((Error) -> Void)? = nil) -> UInt64 {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        generation &+= 1
+        self.sink = sink
+        self.onSinkError = onSinkError
+        publishLocked()
+        return generation
+    }
+
+    /// Remove the sink only if it is still the one `generation` installed.
+    @discardableResult
+    public func detach(generation: UInt64) -> Bool {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        guard generation == self.generation, sink != nil else { return false }
+        sink = nil
+        onSinkError = nil
+        publishLocked()
+        return true
+    }
+
+    public func isCurrent(generation: UInt64) -> Bool {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return generation == self.generation && sink != nil
+    }
+
+    public var hasSink: Bool {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return sink != nil
+    }
+
+    /// Collect cadence and offer cost even with no sink, so preview off/on can be compared.
+    public func setTelemetryEnabled(_ enabled: Bool) {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        telemetryEnabled = enabled
+        publishLocked()
+    }
+
+    private func publishLocked() {
+        let wasCollecting = state != nil
+        state = (sink == nil && !telemetryEnabled) ? nil : State(sink: sink, onSinkError: onSinkError)
+        if !wasCollecting, state != nil {
+            // The first gap after collection resumes would span the whole idle period.
+            metricsLock.lock()
+            lastOfferAtNs = 0
+            metricsLock.unlock()
+        }
+    }
+
+    /// Read and clear the accumulated observations. Called about once a second by the reporter.
+    public func drainMetrics() -> Metrics {
+        metricsLock.lock()
+        defer { metricsLock.unlock() }
+        let snapshot = Metrics(
+            framesOffered: framesOffered,
+            framesWithSink: framesWithSink,
+            offerTotalNs: offerTotalNs,
+            offerMaxNs: offerMaxNs,
+            cadenceSamples: cadenceSamples,
+            cadenceTotalNs: cadenceTotalNs,
+            cadenceMaxNs: cadenceMaxNs,
+            sinkExceptions: sinkExceptions,
+            acsFramesSent: acsFramesSent
+        )
+        framesOffered = 0
+        framesWithSink = 0
+        offerTotalNs = 0
+        offerMaxNs = 0
+        cadenceSamples = 0
+        cadenceTotalNs = 0
+        cadenceMaxNs = 0
+        sinkExceptions = 0
+        acsFramesSent = 0
+        return snapshot
+    }
+
+    /// The ACS sender accepted a frame. Counted under the same gate as `offer`.
+    public func recordAcsSend() {
+        stateLock.lock()
+        let collecting = state != nil
+        stateLock.unlock()
+        guard collecting else { return }
+        metricsLock.lock()
+        acsFramesSent += 1
+        metricsLock.unlock()
+    }
+
+    /// Called on the decoder thread, immediately before the frame goes to ACS.
+    public func offer(_ frame: Frame) {
+        stateLock.lock()
+        let current = state
+        stateLock.unlock()
+        guard let current else { return }
+
+        let started = clock()
+        var failure: Error?
+        if let sink = current.sink {
+            do {
+                try sink(frame)
+            } catch {
+                failure = error
+            }
+        }
+        let elapsed = clock() - started
+
+        metricsLock.lock()
+        framesOffered += 1
+        if lastOfferAtNs > 0 {
+            let gap = started - lastOfferAtNs
+            cadenceSamples += 1
+            cadenceTotalNs += gap
+            if gap > cadenceMaxNs { cadenceMaxNs = gap }
+        }
+        lastOfferAtNs = started
+        offerTotalNs += elapsed
+        if elapsed > offerMaxNs { offerMaxNs = elapsed }
+        if current.sink != nil { framesWithSink += 1 }
+        if failure != nil { sinkExceptions += 1 }
+        metricsLock.unlock()
+
+        if let failure {
+            current.onSinkError?(failure)
+        }
+    }
+}

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/HotspotInterfacePolicy.swift

@@ -0,0 +1,155 @@
+import Foundation
+
+/// One IPv4 address row reported by `getifaddrs`.
+public struct HotspotInterfaceAddress: Equatable {
+    public let name: String
+    public let isUp: Bool
+    public let ipv4: String
+
+    public init(name: String, isUp: Bool, ipv4: String) {
+        self.name = name
+        self.isUp = isUp
+        self.ipv4 = ipv4
+    }
+}
+
+/// One `getifaddrs` sample: every attached interface's kernel index (its `AF_LINK` row, present
+/// with or without an IPv4 address) and every IPv4 address row.
+public struct HotspotInterfaceSnapshot: Equatable {
+    public let links: [String: Int]
+    public let addresses: [HotspotInterfaceAddress]
+    /// Attached interfaces whose `AF_LINK` type is `IFT_ETHER`. Apple platforms report Wi-Fi and
+    /// wired Ethernet this way; cellular, VPN tunnel and loopback links have other types.
+    public let ethernetLinks: Set<String>
+
+    public init(links: [String: Int], addresses: [HotspotInterfaceAddress], ethernetLinks: Set<String> = []) {
+        self.links = links
+        self.addresses = addresses
+        self.ethernetLinks = ethernetLinks
+    }
+}
+
+/// Network framework's type for one interface on one evaluated path.
+public struct HotspotInterfaceReport: Equatable {
+    public let name: String
+    public let index: Int
+    public let isWifi: Bool
+
+    public init(name: String, index: Int, isWifi: Bool) {
+        self.name = name
+        self.index = index
+        self.isWifi = isWifi
+    }
+}
+
+/// The Wi-Fi interface carrying the glasses hotspot and the DHCP address it held when verified.
+public struct HotspotInterfaceBinding: Hashable {
+    public let interface: String
+    public let index: Int
+    public let address: String
+
+    public init(interface: String, index: Int, address: String) {
+        self.interface = interface
+        self.index = index
+        self.address = address
+    }
+}
+
+/// Wi-Fi identity learned during one hotspot session. Create a new value for every join.
+///
+/// A path's interface list describes routes, not hardware: after Wi-Fi moves to an AP without
+/// internet, both the default and the Wi-Fi-constrained path can omit it. An interface's type
+/// does not change while it stays attached, so a positive Wi-Fi report is kept for the same
+/// name and kernel index until that interface is detached or replaced. Omission from a later
+/// report is not evidence. Any non-Wi-Fi report for a name rejects it for the rest of the session.
+public struct HotspotWifiIdentity: Equatable {
+    public private(set) var trusted: [String: Int] = [:]
+    public private(set) var rejected: Set<String> = []
+    /// Trusted names later seen detached or replaced. A fresh report may trust the name again
+    /// for discovery, but an address verified before the change stays lost.
+    public private(set) var detached: Set<String> = []
+
+    public init() {}
+
+    public mutating func observe(_ reports: [HotspotInterfaceReport]) {
+        for report in reports where !report.isWifi {
+            rejected.insert(report.name)
+            trusted[report.name] = nil
+        }
+        for report in reports where report.isWifi && !report.name.isEmpty && report.index > 0 && !rejected.contains(report.name) {
+            // A new index means a different interface took the name; only this report vouches for it.
+            if let index = trusted[report.name], index != report.index { detached.insert(report.name) }
+            trusted[report.name] = report.index
+        }
+    }
+
+    /// Forget an interface that is no longer attached, or whose name now has another index.
+    /// Only a new positive report can re-establish it.
+    public mutating func observe(_ snapshot: HotspotInterfaceSnapshot) {
+        for (name, index) in trusted where snapshot.links[name] != index {
+            trusted[name] = nil
+            detached.insert(name)
+        }
+    }
+
+    /// Pin a binding chosen from hotspot client evidence (see `HotspotInterfacePolicy.select`)
+    /// as this session's Wi-Fi interface. It then ends exactly like a reported one.
+    public mutating func adopt(_ binding: HotspotInterfaceBinding) {
+        guard !rejected.contains(binding.interface), !detached.contains(binding.interface) else { return }
+        trusted[binding.interface] = binding.index
+    }
+}
+
+/// Wi-Fi is not always `en0`: a Mac can have built-in Ethernet on `en0` and Wi-Fi on `en1`.
+/// Identify the hotspot link by interface type and address, never by name or by the first
+/// private address, and keep that exact interface for the rest of the session.
+public enum HotspotInterfacePolicy {
+    /// The unique up IPv4 address, on an interface this session trusts as Wi-Fi and that is still
+    /// attached with the same index, that can be the hotspot client. With a BLE-reported gateway
+    /// it must be a valid client on that gateway's /24. Missing or ambiguous candidates return nil.
+    ///
+    /// A phone on cellular has no Wi-Fi path when the join starts, and after association iOS
+    /// leaves the internet-less glasses AP out of both paths, so no Wi-Fi report ever arrives.
+    /// Only when the session has no trusted Wi-Fi interface, the hotspot client address is the
+    /// evidence instead: the unique valid client of the BLE gateway's /24 on an attached
+    /// Ethernet-type link that no path has reported as non-Wi-Fi. Callers bind it only after the
+    /// glasses SSID matched, then require a connection from it to reach the gateway, and must
+    /// `adopt` it so the session pins that interface.
+    public static func select(snapshot: HotspotInterfaceSnapshot, identity: HotspotWifiIdentity,
+                              gateway: String?) -> HotspotInterfaceBinding?
+    {
+        if !identity.trusted.isEmpty {
+            return unique(snapshot, gateway: gateway) { identity.trusted[$0] }
+        }
+        guard let gateway else { return nil }
+        return unique(snapshot, gateway: gateway) { name in
+            guard snapshot.ethernetLinks.contains(name), !identity.rejected.contains(name),
+                  !identity.detached.contains(name) else { return nil }
+            return snapshot.links[name]
+        }
+    }
+
+    private static func unique(_ snapshot: HotspotInterfaceSnapshot, gateway: String?,
+                               index eligibleIndex: (String) -> Int?) -> HotspotInterfaceBinding?
+    {
+        let bindings = Set(snapshot.addresses.compactMap { row -> HotspotInterfaceBinding? in
+            guard let index = eligibleIndex(row.name), snapshot.links[row.name] == index,
+                  row.isUp, LocalMediaPolicy.isPrivate(row.ipv4) else { return nil }
+            if let gateway, !LocalMediaPolicy.isHotspotClientAddress(row.ipv4, gateway: gateway) { return nil }
+            return HotspotInterfaceBinding(interface: row.name, index: index, address: row.ipv4)
+        })
+        return bindings.count == 1 ? bindings.first : nil
+    }
+
+    /// A verified link remains usable only while the same attached interface is up with the same
+    /// address. Later path reports may omit it. Another interface acquiring that address, a
+    /// detach or replacement under the same name, or a non-Wi-Fi report ends it for the session.
+    /// Pass an identity that has already observed `snapshot`.
+    public static func isIntact(_ binding: HotspotInterfaceBinding, snapshot: HotspotInterfaceSnapshot,
+                                identity: HotspotWifiIdentity) -> Bool
+    {
+        guard identity.trusted[binding.interface] == binding.index, !identity.detached.contains(binding.interface),
+              snapshot.links[binding.interface] == binding.index else { return false }
+        return snapshot.addresses.contains { $0.name == binding.interface && $0.isUp && $0.ipv4 == binding.address }
+    }
+}

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

@@ -0,0 +1,23 @@
+import Foundation
+
+/// Explicit bridge facts; never forward native userInfo or arbitrary NSError descriptions.
+public struct HotspotJoinFailure {
+    public let code: String
+    public let message: String
+
+    public init(_ error: Error) {
+        if error is CancellationError || (error as? LocalMediaError)?.message == "Hotspot join cancelled" {
+            code = "ERR_HOTSPOT_CANCELLED"
+            message = "Hotspot join cancelled"
+        } else if let local = error as? LocalMediaError {
+            code = "ERR_HOTSPOT_JOIN"
+            // These messages are authored by the owned hotspot implementation, not NSError.
+            message = String(local.message.filter { !$0.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains) }.prefix(512))
+        } else {
+            code = "ERR_HOTSPOT_NATIVE"
+            let native = error as NSError
+            let domain = native.domain.range(of: "^[A-Za-z0-9_.-]{1,128}$", options: .regularExpression) == nil ? "unavailable" : native.domain
+            message = "Hotspot join failed (\(domain), \(native.code))"
+        }
+    }
+}

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)
+    }
+}