diff --git a/Sources/PermissionGuide/Permission.swift b/Sources/PermissionGuide/Permission.swift index 5b218da..710ec5b 100644 --- a/Sources/PermissionGuide/Permission.swift +++ b/Sources/PermissionGuide/Permission.swift @@ -84,7 +84,9 @@ public enum Permission: Hashable, Sendable { switch self { case .fullDiskAccess: // Opens files only Full Disk Access can (see PermissionGuideProbe.c). May keep - // failing until the app relaunches. + // failing until the app relaunches. With System Integrity Protection off those + // files open for every process, so the check says nothing. + if permissionguide_filesystem_protection_disabled() { return .unknown } return permissionguide_full_disk_access() ? .granted : .notGranted case .screenRecording: // May keep reporting false until the app relaunches. @@ -117,7 +119,8 @@ extension Permission: Identifiable { public enum PermissionStatus: Sendable { case granted case notGranted - /// macOS offers no way to check this permission. + /// The permission can't be checked: macOS has no API for it, or (Full Disk Access) + /// System Integrity Protection is off. case unknown } diff --git a/Sources/PermissionGuide/PermissionManager.swift b/Sources/PermissionGuide/PermissionManager.swift index dfe0804..f70f359 100644 --- a/Sources/PermissionGuide/PermissionManager.swift +++ b/Sources/PermissionGuide/PermissionManager.swift @@ -32,7 +32,9 @@ public final class PermissionManager { @ObservationIgnored private let guide = SettingsGuide() @ObservationIgnored private var continuation: CheckedContinuation? - @ObservationIgnored private var pendingCheck: (@MainActor () -> Bool)? + @ObservationIgnored private var pendingCheck: (@MainActor () async -> Bool)? + /// The `pendingCheck` call in flight, if any. + @ObservationIgnored private var pendingCheckTask: Task? @ObservationIgnored private var extensionQueries: Set = [] @ObservationIgnored private var lastExtensionQuery = Date.distantPast /// Grants a fresh process has seen that this one can't until it relaunches. @@ -105,9 +107,13 @@ public final class PermissionManager { public func request( _ permission: Permission, dragging appURL: URL = Bundle.main.bundleURL, + named name: String? = nil, + icon: NSImage? = nil, + alreadyListed: Bool = false, tint: NSColor = .controlAccentColor, - isGranted: (@MainActor () -> Bool)? = nil + isGranted: (@MainActor () async -> Bool)? = nil ) async -> PermissionResult { + let subject = SettingsGuide.Subject(url: appURL, name: name, icon: icon) if case .backgroundItem(let plist) = permission { let service = SMAppService.daemon(plistName: plist) if service.status == .notRegistered || service.status == .notFound { @@ -116,10 +122,10 @@ public final class PermissionManager { if service.status != .requiresApproval { return .failed(error) } } } - return await guide(to: permission, dragging: appURL, tint: tint, isGranted: isGranted) + return await guide(to: permission, dragging: appURL, named: name, icon: icon, alreadyListed: alreadyListed, tint: tint, isGranted: isGranted) } guard case .systemExtension(let ext) = permission else { - return await guide(to: permission, dragging: appURL, tint: tint, isGranted: isGranted) + return await guide(to: permission, dragging: appURL, named: name, icon: icon, alreadyListed: alreadyListed, tint: tint, isGranted: isGranted) } if status(of: permission) == .granted { return .granted } @@ -128,7 +134,7 @@ public final class PermissionManager { guard let self, self.pending == permission else { return } switch event { case .needsUserApproval: - self.showGuide(for: permission, appURL: appURL, tint: tint, isGranted: isGranted) + self.showGuide(for: permission, subject: subject, alreadyListed: alreadyListed, tint: tint, canCheck: isGranted != nil) case .activated: self.set(.granted, for: permission) self.finish(.granted) @@ -144,26 +150,39 @@ public final class PermissionManager { /// Opens System Settings at the permission's pane and walks the user through it, /// without requesting anything from macOS. /// - /// For a privacy pane, the user drags `appURL` into the highlighted list. For a system - /// extension, the user turns on its switch; use this when your app submits its own + /// For a privacy pane, the user drags `appURL` into the highlighted list, or turns on + /// its switch there when `alreadyListed`. For a system extension, the user turns on + /// its switch; use this when your app submits its own /// `OSSystemExtensionRequest` and gets `requestNeedsUserApproval`. /// /// - Parameters: /// - appURL: The bundle the user drags into System Settings. Pass a helper's URL when /// a helper, not the main app, is the process that needs the permission. + /// - name: What the guide calls that bundle. Defaults to its name in Finder, which + /// for a system extension is its file name. + /// - icon: The icon the guide shows for it. Defaults to the bundle's own, which is a + /// generic one for a helper that ships without an icon. + /// - alreadyListed: Whether the privacy pane's list already holds the bundle, + /// switched off, so the user turns on its switch instead of dragging it in. macOS + /// lists some helpers itself once they ask for access, such as an Endpoint + /// Security extension in Full Disk Access. /// - tint: Color of the highlight and sidecar border. /// - isGranted: How to tell the permission was granted, for when the default check - /// can't see it (such as a helper's permissions). When neither this nor macOS can - /// report status, the sidecar shows a Done button instead. + /// can't see it (such as a helper's permissions). It can be `async`, to ask the + /// helper over IPC, and is called again once the last call has returned. When + /// neither this nor macOS can report status, the sidecar shows a Done button instead. /// - Returns: How the guide ended. See `PermissionResult`. @discardableResult public func guide( to permission: Permission, dragging appURL: URL = Bundle.main.bundleURL, + named name: String? = nil, + icon: NSImage? = nil, + alreadyListed: Bool = false, tint: NSColor = .controlAccentColor, - isGranted: (@MainActor () -> Bool)? = nil + isGranted: (@MainActor () async -> Bool)? = nil ) async -> PermissionResult { - if let isGranted, isGranted() { return .granted } + if let isGranted, await isGranted() { return .granted } let isOwnApp = isGranted == nil && appURL == Bundle.main.bundleURL if isOwnApp, status(of: permission) == .granted { return .granted } // Granted earlier, but this process can't see it until it relaunches. @@ -173,7 +192,8 @@ public final class PermissionManager { } begin(permission, isGranted: isGranted) - showGuide(for: permission, appURL: appURL, tint: tint, isGranted: isGranted) + let subject = SettingsGuide.Subject(url: appURL, name: name, icon: icon) + showGuide(for: permission, subject: subject, alreadyListed: alreadyListed, tint: tint, canCheck: isGranted != nil) return await waitForGrant() } @@ -182,21 +202,18 @@ public final class PermissionManager { finish(.cancelled) } - private func begin(_ permission: Permission, isGranted: (@MainActor () -> Bool)?) { + private func begin(_ permission: Permission, isGranted: (@MainActor () async -> Bool)?) { finish(.cancelled, activate: false) pending = permission pendingCheck = isGranted } - private func showGuide(for permission: Permission, appURL: URL, tint: NSColor, isGranted: (@MainActor () -> Bool)?) { - let isOwnApp = appURL == Bundle.main.bundleURL - let canVerify = isGranted != nil || (isOwnApp && status(of: permission) != .unknown) - let mode: SettingsGuide.Mode = switch permission { - case .systemExtension, .backgroundItem: .toggle(permission, confirmManually: !canVerify) - default: .drag(permission, confirmManually: !canVerify) - } + private func showGuide(for permission: Permission, subject: SettingsGuide.Subject, alreadyListed: Bool, tint: NSColor, canCheck: Bool) { + let isOwnApp = subject.url == Bundle.main.bundleURL + let canVerify = canCheck || (isOwnApp && status(of: permission) != .unknown) + let mode = SettingsGuide.Mode(permission, alreadyListed: alreadyListed, confirmManually: !canVerify) SystemSettings.open(permission.settingsURL) - guide.start(mode, appURL: appURL, tint: tint, relaunch: relaunchChoice) + guide.start(mode, subject: subject, tint: tint, relaunch: relaunchChoice) } private func waitForGrant() async -> PermissionResult { @@ -211,15 +228,36 @@ public final class PermissionManager { if statuses[permission] != status { statuses[permission] = status } } - private func isPendingGranted(_ permission: Permission) -> Bool { - pendingCheck?() ?? (status(of: permission) == .granted) + private func isPendingGranted(_ permission: Permission) async -> Bool { + if let pendingCheck { return await pendingCheck() } + return status(of: permission) == .granted } /// Finishes the request once its permission is granted, unless System Settings' /// "Quit & Reopen" alert is up (or likely about to be): the guide stays to walk the /// user through it, and finishes when it closes (`relaunchDeferred`). private func checkPending() { - guard let pending, isPendingGranted(pending) else { + guard let pending else { + probedGrantSince = nil + return + } + guard let pendingCheck else { + pendingChecked(pending, granted: status(of: pending) == .granted) + return + } + // One call at a time: an IPC round trip can outlast a poll. + guard pendingCheckTask == nil else { return } + pendingCheckTask = Task { + let granted = await pendingCheck() + // Cancelled when the request it was checking for finished. + guard !Task.isCancelled else { return } + pendingCheckTask = nil + pendingChecked(pending, granted: granted) + } + } + + private func pendingChecked(_ pending: Permission, granted: Bool) { + guard granted else { probedGrantSince = nil return } @@ -243,7 +281,9 @@ public final class PermissionManager { guard pending == permission, !isTerminating else { return } await probe(force: true)?.value guard pending == permission, !isTerminating else { return } - if isPendingGranted(permission) { + let granted = await isPendingGranted(permission) + guard pending == permission, !isTerminating else { return } + if granted { finish(.granted) } else if pendingCheck != nil || status(of: permission) != .unknown { // It didn't go through after all (the user switched it back off), so @@ -315,6 +355,8 @@ public final class PermissionManager { guide.stop() pending = nil pendingCheck = nil + pendingCheckTask?.cancel() + pendingCheckTask = nil probedGrantSince = nil continuation?.resume(returning: result) continuation = nil diff --git a/Sources/PermissionGuide/SettingsGuide.swift b/Sources/PermissionGuide/SettingsGuide.swift index 14cfd2b..df8b97b 100644 --- a/Sources/PermissionGuide/SettingsGuide.swift +++ b/Sources/PermissionGuide/SettingsGuide.swift @@ -7,9 +7,19 @@ final class SettingsGuide { /// Drag the app into a privacy pane's list. `confirmManually` adds a Done button /// for when the grant can't be detected. case drag(Permission, confirmManually: Bool) - /// Switch on a system extension. + /// Turn on a switch: a system extension's, a background item's, or the one beside + /// an app a privacy pane already lists. case toggle(Permission, confirmManually: Bool) + init(_ permission: Permission, alreadyListed: Bool, confirmManually: Bool) { + self = switch permission { + case .systemExtension, .backgroundItem: .toggle(permission, confirmManually: confirmManually) + default: alreadyListed + ? .toggle(permission, confirmManually: confirmManually) + : .drag(permission, confirmManually: confirmManually) + } + } + var permission: Permission { switch self { case .drag(let p, _), .toggle(let p, _): p @@ -21,6 +31,42 @@ final class SettingsGuide { case .drag(_, let c), .toggle(_, let c): c } } + + /// Whether the switch is in a sheet over the pane rather than in the pane's list. + var targetIsInSheet: Bool { + switch self { + case .toggle(.systemExtension, _), .toggle(.backgroundItem, _): true + case .drag, .toggle: false + } + } + + /// The sidecar's instructions, where `subject` is what the guide calls the bundle. + func instructions(subject: String) -> (title: String, message: String) { + let name = permission.displayName + return switch self { + case .drag: + ("Grant \(name)", "Drag this icon into the highlighted list in System Settings.") + case .toggle(.backgroundItem, _): + ("Allow in the Background", "Turn on the switch next to \(subject) under Allow in the Background.") + case .toggle(.systemExtension(let ext), _): + ("Allow \(ext.category.displayName)", "Turn on the switch next to \(name) in System Settings.") + case .toggle: + ("Grant \(name)", "Turn on the switch next to \(subject) in the highlighted list in System Settings.") + } + } + } + + /// The bundle being granted, and what the guide calls and draws it as. + struct Subject { + var url: URL + var name: String? + var icon: NSImage? + + var displayName: String { + name ?? FileManager.default.displayName(atPath: url.path).replacingOccurrences(of: ".app", with: "") + } + + var displayIcon: NSImage { icon ?? NSWorkspace.shared.icon(forFile: url.path) } } var onCancel: (() -> Void)? @@ -53,34 +99,18 @@ final class SettingsGuide { prompts.resume() } - func start(_ mode: Mode, appURL: URL, tint: NSColor, relaunch: RelaunchChoice) { + func start(_ mode: Mode, subject: Subject, tint: NSColor, relaunch: RelaunchChoice) { stop() self.mode = mode self.relaunch = relaunch - appName = FileManager.default.displayName(atPath: appURL.path).replacingOccurrences(of: ".app", with: "") - let icon = NSWorkspace.shared.icon(forFile: appURL.path) - let name = mode.permission.displayName - - let sidecar: SidecarPanel - switch mode { - case .drag(_, let confirmManually): - sidecar = SidecarPanel( - title: "Grant \(name)", - message: "Drag this icon into the highlighted list in System Settings.", - icon: icon, dragURL: appURL, showsDone: confirmManually, tint: tint) - case .toggle(.backgroundItem, let confirmManually): - sidecar = SidecarPanel( - title: "Allow in the Background", - message: "Turn on the switch next to \(appName) under Allow in the Background.", - icon: icon, dragURL: nil, showsDone: confirmManually, tint: tint) - case .toggle(let permission, let confirmManually): - let kind = if case .systemExtension(let ext) = permission { ext.category.displayName } else { name } - sidecar = SidecarPanel( - title: "Allow \(kind)", - message: "Turn on the switch next to \(name) in System Settings.", - icon: icon, dragURL: nil, showsDone: confirmManually, tint: tint) - } - instructions = (sidecar.instructionTitle, sidecar.instructionMessage) + appName = subject.displayName + let appURL = subject.url + let icon = subject.displayIcon + instructions = mode.instructions(subject: appName) + let dragURL: URL? = if case .drag = mode { appURL } else { nil } + let sidecar = SidecarPanel( + title: instructions.title, message: instructions.message, + icon: icon, dragURL: dragURL, showsDone: mode.confirmManually, tint: tint) sidecar.onCancel = { [weak self] in self?.onCancel?() } sidecar.onDone = { [weak self] in self?.onDone?() } sidecar.iconView.onDragChanged = { [weak self] dragging in @@ -152,7 +182,7 @@ final class SettingsGuide { let showsHighlight = switch phase { case .prompt: true case .afterAuthentication, .granted: false - case .instructions: if case .toggle = mode { sheet != nil } else { sheet == nil } + case .instructions: mode.targetIsInSheet ? sheet != nil : sheet == nil } let showsGhost = showsHighlight && prompt == nil && !isDragging // Right after authenticating, keep the last text until the next prompt shows. diff --git a/Sources/PermissionGuide/SidecarPanel.swift b/Sources/PermissionGuide/SidecarPanel.swift index 677e42c..d0512b9 100644 --- a/Sources/PermissionGuide/SidecarPanel.swift +++ b/Sources/PermissionGuide/SidecarPanel.swift @@ -84,9 +84,6 @@ final class SidecarPanel: NSPanel { setContentSize(size) } - var instructionTitle: String { titleLabel.stringValue } - var instructionMessage: String { hint.stringValue } - /// Replaces the instructions, keeping the panel's top edge in place. func show(title: String, message: String) { titleLabel.stringValue = title diff --git a/Sources/PermissionGuideProbe/PermissionGuideProbe.c b/Sources/PermissionGuideProbe/PermissionGuideProbe.c index a0ee241..de214f6 100644 --- a/Sources/PermissionGuideProbe/PermissionGuideProbe.c +++ b/Sources/PermissionGuideProbe/PermissionGuideProbe.c @@ -2,6 +2,7 @@ #include #include #include +#include #include #include #include @@ -20,6 +21,10 @@ extern char **environ; // process, so TCC checks the app's grants afresh instead of inheriting the parent's. int responsibility_spawnattrs_setdisclaim(posix_spawnattr_t *attrs, int disclaim) __attribute__((weak_import)); +// libSystem SPI: 0 when the running system allows what `mask` names. +int csr_check(uint32_t mask) __attribute__((weak_import)); +#define PK_CSR_ALLOW_UNRESTRICTED_FS (1 << 1) + static bool pk_probe_ran = false; bool permissionguide_probe_linked(void) { return pk_probe_ran; } @@ -47,6 +52,10 @@ bool permissionguide_full_disk_access(void) { return false; } +bool permissionguide_filesystem_protection_disabled(void) { + return csr_check != NULL && csr_check(PK_CSR_ALLOW_UNRESTRICTED_FS) == 0; +} + static bool pk_granted(const char *name) { if (strcmp(name, "fullDiskAccess") == 0) return permissionguide_full_disk_access(); if (strcmp(name, "screenRecording") == 0) return CGPreflightScreenCaptureAccess(); diff --git a/Sources/PermissionGuideProbe/include/PermissionGuideProbe.h b/Sources/PermissionGuideProbe/include/PermissionGuideProbe.h index 6d600bb..0b21812 100644 --- a/Sources/PermissionGuideProbe/include/PermissionGuideProbe.h +++ b/Sources/PermissionGuideProbe/include/PermissionGuideProbe.h @@ -20,6 +20,11 @@ bool permissionguide_probe_linked(void); /// Never prompts and is safe on any thread. May keep reading false until the app relaunches. bool permissionguide_full_disk_access(void); +/// Whether System Integrity Protection's filesystem protection is off. The files +/// `permissionguide_full_disk_access` opens are then readable by every process, so it +/// reads true whether or not Full Disk Access was granted. +bool permissionguide_filesystem_protection_disabled(void); + /// Launches `executable` as a probe with `PERMISSIONGUIDE_PROBE_ENV` set to `value`, as its /// own responsible process so TCC checks the app's grants as a fresh launch would. Blocks /// until it exits; kills it after `timeout` seconds. The exit status, or -1 when it didn't diff --git a/Tests/PermissionGuideTests/PermissionGuideTests.swift b/Tests/PermissionGuideTests/PermissionGuideTests.swift index 64f74ee..eeec110 100644 --- a/Tests/PermissionGuideTests/PermissionGuideTests.swift +++ b/Tests/PermissionGuideTests/PermissionGuideTests.swift @@ -171,6 +171,73 @@ private let password = SystemSettings.Prompt.authentication(NSRect(x: 200, y: 15 } } +@Suite struct StatusTests { + /// With System Integrity Protection off, the files the check opens are readable + /// without Full Disk Access, so "granted" would be wrong on every such Mac. + @Test func fullDiskAccessIsUnknownWithoutFilesystemProtection() { + let unprotected = permissionguide_filesystem_protection_disabled() + #expect((Permission.fullDiskAccess.currentStatus == .unknown) == unprotected) + } +} + +@Suite @MainActor struct ManagerTests { + @Test func anAsyncCheckThatAlreadyPassesSkipsTheGuide() async { + let manager = PermissionManager(permissions: []) + let result = await manager.guide(to: .accessibility, isGranted: { + await Task.yield() + return true + }) + #expect(result.isGranted) + #expect(manager.pending == nil) + } +} + +@Suite @MainActor struct GuideSubjectTests { + private let helper = URL(filePath: "/Applications/Sample.app/Contents/Library/SystemExtensions/com.example.sample.monitor.systemextension") + + @Test func aBundleIsNamedAfterItsFile() { + #expect(SettingsGuide.Subject(url: URL(filePath: "/Applications/Sample.app")).displayName == "Sample") + #expect(SettingsGuide.Subject(url: helper).displayName == "com.example.sample.monitor.systemextension") + } + + @Test func aGivenNameAndIconReplaceTheBundlesOwn() { + let icon = NSImage(size: NSSize(width: 8, height: 8)) + let subject = SettingsGuide.Subject(url: helper, name: "Sample", icon: icon) + #expect(subject.displayName == "Sample") + #expect(subject.displayIcon === icon) + } +} + +@Suite @MainActor struct GuideModeTests { + private let ext = SystemExtension(identifier: "com.example.sample.tunnel", category: .networkExtension, displayName: "Sample VPN") + + @Test func aPrivacyPaneIsADragUnlessTheListAlreadyHoldsTheApp() { + let drag = SettingsGuide.Mode(.fullDiskAccess, alreadyListed: false, confirmManually: false) + guard case .drag = drag else { Issue.record("expected a drag"); return } + #expect(drag.instructions(subject: "Sample").message.contains("Drag this icon")) + + let toggle = SettingsGuide.Mode(.fullDiskAccess, alreadyListed: true, confirmManually: false) + guard case .toggle = toggle else { Issue.record("expected a toggle"); return } + #expect(toggle.instructions(subject: "Sample").title == "Grant Full Disk Access") + #expect(toggle.instructions(subject: "Sample").message == "Turn on the switch next to Sample in the highlighted list in System Settings.") + #expect(!toggle.targetIsInSheet, "the switch is in the pane's list, not in a sheet over it") + } + + @Test func extensionsAndBackgroundItemsAreSwitchesEitherWay() { + for listed in [false, true] { + let mode = SettingsGuide.Mode(.systemExtension(ext), alreadyListed: listed, confirmManually: false) + #expect(mode.targetIsInSheet) + #expect(mode.instructions(subject: "Sample").title == "Allow Network Extension") + #expect(mode.instructions(subject: "Sample").message == "Turn on the switch next to Sample VPN in System Settings.") + + let background = SettingsGuide.Mode(.backgroundItem(daemonPlist: "com.example.daemon.plist"), alreadyListed: listed, confirmManually: true) + #expect(background.targetIsInSheet) + #expect(background.confirmManually) + #expect(background.instructions(subject: "Sample").message == "Turn on the switch next to Sample under Allow in the Background.") + } + } +} + @Suite struct SystemExtensionSetupTests { private static let networkEntitlement = "com.apple.developer.networking.networkextension" diff --git a/docs/guide.md b/docs/guide.md index 75269e1..1068a14 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -7,7 +7,7 @@ how the guide finds windows and prompts see [how-it-works.md](how-it-works.md). | Permission | Pane | Status check | | --- | --- | --- | -| `.fullDiskAccess` | Full Disk Access | ✓ (may need a relaunch) | +| `.fullDiskAccess` | Full Disk Access | ✓ (may need a relaunch; not with SIP off) | | `.screenRecording` | Screen & System Audio Recording | ✓ (may need a relaunch) | | `.accessibility` | Accessibility | ✓ | | `.inputMonitoring` | Input Monitoring | ✓ (may need a relaunch) | @@ -65,13 +65,18 @@ by themselves. switch permissions.status(of: .fullDiskAccess) { case .granted: … case .notGranted: … -case .unknown: … // macOS can't report it (Developer Tools, App Management) +case .unknown: … // can't be checked (Developer Tools, App Management) } permissions.statuses // [Permission: PermissionStatus] for every tracked permission permissions.pending // the permission whose guide is showing, if any ``` +Full Disk Access also reads `.unknown` on a Mac with System Integrity Protection turned +off. The check opens files that only Full Disk Access can open, and with SIP off every +process can open them. The guide shows a Done button there, as it does for the +permissions macOS can't report. + Checking never shows a system prompt. ## Request a permission @@ -104,6 +109,9 @@ Options: await permissions.request( .screenRecording, dragging: helperURL, // bundle to drag in; defaults to your app + named: "Recorder", // what the guide calls it; defaults to its Finder name + icon: recorderIcon, // defaults to the bundle's own icon + alreadyListed: true, // the list has it; switch it on instead of dragging tint: .systemPurple, // highlight and panel color isGranted: { helper.canRecord } // custom check, for when the default can't see it ) @@ -184,9 +192,47 @@ await permissions.request( ) ``` +`isGranted` can be `async`, so it can wait for the helper's answer: + +```swift +isGranted: { await helper.hasFullDiskAccess() } +``` + +PermissionGuide calls it once before showing the guide and then on every poll, waiting +for each call to return before making the next. + Without `isGranted`, the panel shows a Done button, because PermissionGuide can't tell when the helper has been granted. +The panel shows the helper's own icon and Finder name. A helper with no icon gets a +generic one, and a system extension's name is its file name +(`com.example.app.monitor.systemextension`). Pass `named:` and `icon:` to show something +the user recognises: + +```swift +await permissions.request( + .fullDiskAccess, + dragging: helperURL, + named: "Example", + icon: NSApp.applicationIconImage, + isGranted: { await helper.hasFullDiskAccess() } +) +``` + +macOS adds some helpers to a privacy list by itself, switched off, once they ask for +access. There is nothing to drag then, so pass `alreadyListed: true` and the guide +highlights the list and tells the user to turn on the helper's switch: + +```swift +await permissions.request( + .fullDiskAccess, + dragging: helperURL, + named: "Example", + alreadyListed: true, + isGranted: { await helper.hasFullDiskAccess() } +) +``` + ## System extensions Describe each extension your app embeds, and track it like any other permission: @@ -257,9 +303,10 @@ func requestNeedsUserApproval(_ request: OSSystemExtensionRequest) { A VPN also has to save its configuration (`NETunnelProviderManager.saveToPreferences`), which shows a separate "Add VPN Configurations" alert that PermissionGuide doesn't guide. -Endpoint Security clients usually also need `.fullDiskAccess`, granted to the extension. -Pass the extension's URL (`vpn.embeddedURL()`) as `dragging:` along with an `isGranted:` -check. +Endpoint Security clients usually also need `.fullDiskAccess`, granted to the extension +and not to your app. Pass the extension's URL (`monitor.embeddedURL()`) as `dragging:` +along with an `isGranted:` check that asks the extension, and `named:` and `icon:` so the +panel shows your app instead of the extension's file name. See [Helpers](#helpers). ## Background items @@ -286,8 +333,8 @@ many items sit above it. The app has to be signed (Developer ID) for macOS to re | `status(of:)`, `statuses` | Current status: `.granted`, `.notGranted` or `.unknown` | | `pending` | The permission whose guide is showing | | `needsRelaunch(_:)` | Granted, but the app must relaunch to use it | -| `request(_:dragging:tint:isGranted:)` | Guides the user; installs system extensions and registers background items first | -| `guide(to:dragging:tint:isGranted:)` | Guides the user without requesting anything | +| `request(_:dragging:named:icon:alreadyListed:tint:isGranted:)` | Guides the user; installs system extensions and registers background items first | +| `guide(to:dragging:named:icon:alreadyListed:tint:isGranted:)` | Guides the user without requesting anything | | `cancel()` | Closes the guide; the pending call returns `.cancelled` | | `refresh()` | Re-checks status now | | `Permission.displayName`, `.settingsURL` | Pane name and deep link | diff --git a/llms.txt b/llms.txt index 02619ec..4d8198c 100644 --- a/llms.txt +++ b/llms.txt @@ -47,7 +47,7 @@ import PermissionGuide permissions.status(of: .accessibility) // .granted, .notGranted, or .unknown ``` -`.unknown` means macOS has no API to check it (Developer Tools, App Management). Treat it as "ask the user", and the guide shows a Done button for those. +`.unknown` means it can't be checked: macOS has no API for it (Developer Tools, App Management), or it is Full Disk Access on a Mac with System Integrity Protection off, where the check would pass for every process. Treat it as "ask the user", and the guide shows a Done button for those. 3. Request from a user action, such as a button. Handle all four results. @@ -81,8 +81,8 @@ You are done when the app builds, the screen shows each tracked permission's sta | `PermissionManager(permissions:pollInterval:)` | Tracks the permissions you list. Defaults to `Permission.privacyPermissions`, polled every 0.75 s. | | `status(of:)`, `statuses` | Current status. Observable. | | `pending` | The permission whose guide is showing, if any. | -| `request(_:dragging:tint:isGranted:)` | Runs the guide. Installs a system extension or registers a background item first. | -| `guide(to:dragging:tint:isGranted:)` | Runs the guide without requesting anything. For apps that submit their own `OSSystemExtensionRequest`. | +| `request(_:dragging:named:icon:alreadyListed:tint:isGranted:)` | Runs the guide. Installs a system extension or registers a background item first. | +| `guide(to:dragging:named:icon:alreadyListed:tint:isGranted:)` | Runs the guide without requesting anything. For apps that submit their own `OSSystemExtensionRequest`. | | `cancel()` | Closes the guide. The pending call returns `.cancelled`. | | `refresh()` | Re-checks now. | | `needsRelaunch(_:)` | Granted, but this process has to restart to use it. | @@ -93,7 +93,7 @@ You are done when the app builds, the screen shows each tracked permission's sta ## Cases that need more than the defaults -A helper process needs the permission. Pass the helper's bundle to drag and a check that can see the helper's permissions, such as an IPC call. Without `isGranted` the guide shows a Done button. +A helper process needs the permission. Pass the helper's bundle to drag and a check that can see the helper's permissions, such as an IPC call. `isGranted` can be `async`. Without it the guide shows a Done button. The panel shows the helper's own icon and Finder name; pass `named:` and `icon:` when those are generic, as they are for a system extension. If macOS already lists the helper in the pane, switched off, pass `alreadyListed: true` and the guide points at its switch instead of asking for a drag. ```swift await permissions.request(