From 4e247b065d890e90effba77d320ffe045f6329d2 Mon Sep 17 00:00:00 2001 From: "Frank Chiarulli Jr." Date: Sun, 15 Nov 2026 20:38:58 -0500 Subject: [PATCH 1/4] Report Full Disk Access as unknown when SIP is off The check opens files only Full Disk Access can open. With System Integrity Protection's filesystem protection off, every process can open them, so the status, request and the probe all read granted for an app that was never granted anything. --- Sources/PermissionGuide/Permission.swift | 7 +++++-- Sources/PermissionGuideProbe/PermissionGuideProbe.c | 9 +++++++++ .../PermissionGuideProbe/include/PermissionGuideProbe.h | 5 +++++ Tests/PermissionGuideTests/PermissionGuideTests.swift | 9 +++++++++ docs/guide.md | 9 +++++++-- llms.txt | 2 +- 6 files changed, 36 insertions(+), 5 deletions(-) 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/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..06c04da 100644 --- a/Tests/PermissionGuideTests/PermissionGuideTests.swift +++ b/Tests/PermissionGuideTests/PermissionGuideTests.swift @@ -171,6 +171,15 @@ 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 struct SystemExtensionSetupTests { private static let networkEntitlement = "com.apple.developer.networking.networkextension" diff --git a/docs/guide.md b/docs/guide.md index 75269e1..29b6470 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 diff --git a/llms.txt b/llms.txt index 02619ec..08c0331 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. From c45c3d21847ad9f3adab64ab7ba559d8b1f39c7b Mon Sep 17 00:00:00 2001 From: "Frank Chiarulli Jr." Date: Sun, 15 Nov 2026 20:39:17 -0500 Subject: [PATCH 2/4] Let isGranted be async A helper's permissions are usually read over IPC, which forced callers to cache the last answer for a synchronous closure. The check now awaits each call and makes one at a time. Synchronous closures still work. --- .../PermissionGuide/PermissionManager.swift | 52 ++++++++++++++----- .../PermissionGuideTests.swift | 12 +++++ docs/guide.md | 9 ++++ llms.txt | 2 +- 4 files changed, 62 insertions(+), 13 deletions(-) diff --git a/Sources/PermissionGuide/PermissionManager.swift b/Sources/PermissionGuide/PermissionManager.swift index dfe0804..6a78102 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. @@ -106,7 +108,7 @@ public final class PermissionManager { _ permission: Permission, dragging appURL: URL = Bundle.main.bundleURL, tint: NSColor = .controlAccentColor, - isGranted: (@MainActor () -> Bool)? = nil + isGranted: (@MainActor () async -> Bool)? = nil ) async -> PermissionResult { if case .backgroundItem(let plist) = permission { let service = SMAppService.daemon(plistName: plist) @@ -153,17 +155,18 @@ public final class PermissionManager { /// a helper, not the main app, is the process that needs the permission. /// - 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, 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. @@ -182,13 +185,13 @@ 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)?) { + private func showGuide(for permission: Permission, appURL: URL, tint: NSColor, isGranted: (@MainActor () async -> Bool)?) { let isOwnApp = appURL == Bundle.main.bundleURL let canVerify = isGranted != nil || (isOwnApp && status(of: permission) != .unknown) let mode: SettingsGuide.Mode = switch permission { @@ -211,15 +214,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 +267,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 +341,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/Tests/PermissionGuideTests/PermissionGuideTests.swift b/Tests/PermissionGuideTests/PermissionGuideTests.swift index 06c04da..b9d430f 100644 --- a/Tests/PermissionGuideTests/PermissionGuideTests.swift +++ b/Tests/PermissionGuideTests/PermissionGuideTests.swift @@ -180,6 +180,18 @@ private let password = SystemSettings.Prompt.authentication(NSRect(x: 200, y: 15 } } +@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 struct SystemExtensionSetupTests { private static let networkEntitlement = "com.apple.developer.networking.networkextension" diff --git a/docs/guide.md b/docs/guide.md index 29b6470..390e70e 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -189,6 +189,15 @@ 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. diff --git a/llms.txt b/llms.txt index 08c0331..f5f970a 100644 --- a/llms.txt +++ b/llms.txt @@ -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. ```swift await permissions.request( From f616eb179af9a58e027f1923eba8a3d0dc647baa Mon Sep 17 00:00:00 2001 From: "Frank Chiarulli Jr." Date: Sun, 15 Nov 2026 20:40:22 -0500 Subject: [PATCH 3/4] Let the guide show a name and icon for a helper The panel took both from the bundle being dragged. A helper without an icon got a generic one, and a system extension was named after its file, such as com.example.app.monitor.systemextension. --- .../PermissionGuide/PermissionManager.swift | 26 +++++++++++++------ Sources/PermissionGuide/SettingsGuide.swift | 20 +++++++++++--- .../PermissionGuideTests.swift | 16 ++++++++++++ docs/guide.md | 21 +++++++++++++-- llms.txt | 6 ++--- 5 files changed, 73 insertions(+), 16 deletions(-) diff --git a/Sources/PermissionGuide/PermissionManager.swift b/Sources/PermissionGuide/PermissionManager.swift index 6a78102..3347eeb 100644 --- a/Sources/PermissionGuide/PermissionManager.swift +++ b/Sources/PermissionGuide/PermissionManager.swift @@ -107,9 +107,12 @@ public final class PermissionManager { public func request( _ permission: Permission, dragging appURL: URL = Bundle.main.bundleURL, + named name: String? = nil, + icon: NSImage? = nil, tint: NSColor = .controlAccentColor, 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 { @@ -118,10 +121,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, 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, tint: tint, isGranted: isGranted) } if status(of: permission) == .granted { return .granted } @@ -130,7 +133,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, tint: tint, canCheck: isGranted != nil) case .activated: self.set(.granted, for: permission) self.finish(.granted) @@ -153,6 +156,10 @@ public final class PermissionManager { /// - 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. /// - 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). It can be `async`, to ask the @@ -163,6 +170,8 @@ public final class PermissionManager { public func guide( to permission: Permission, dragging appURL: URL = Bundle.main.bundleURL, + named name: String? = nil, + icon: NSImage? = nil, tint: NSColor = .controlAccentColor, isGranted: (@MainActor () async -> Bool)? = nil ) async -> PermissionResult { @@ -176,7 +185,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, tint: tint, canCheck: isGranted != nil) return await waitForGrant() } @@ -191,15 +201,15 @@ public final class PermissionManager { pendingCheck = isGranted } - private func showGuide(for permission: Permission, appURL: URL, tint: NSColor, isGranted: (@MainActor () async -> Bool)?) { - let isOwnApp = appURL == Bundle.main.bundleURL - let canVerify = isGranted != nil || (isOwnApp && status(of: permission) != .unknown) + private func showGuide(for permission: Permission, subject: SettingsGuide.Subject, tint: NSColor, canCheck: Bool) { + let isOwnApp = subject.url == Bundle.main.bundleURL + let canVerify = canCheck || (isOwnApp && status(of: permission) != .unknown) let mode: SettingsGuide.Mode = switch permission { case .systemExtension, .backgroundItem: .toggle(permission, confirmManually: !canVerify) default: .drag(permission, 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 { diff --git a/Sources/PermissionGuide/SettingsGuide.swift b/Sources/PermissionGuide/SettingsGuide.swift index 14cfd2b..1ed5b42 100644 --- a/Sources/PermissionGuide/SettingsGuide.swift +++ b/Sources/PermissionGuide/SettingsGuide.swift @@ -23,6 +23,19 @@ final class SettingsGuide { } } + /// 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)? var onDone: (() -> Void)? /// The "Quit & Reopen" alert closed and the app is still running: the user clicked @@ -53,12 +66,13 @@ 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) + appName = subject.displayName + let appURL = subject.url + let icon = subject.displayIcon let name = mode.permission.displayName let sidecar: SidecarPanel diff --git a/Tests/PermissionGuideTests/PermissionGuideTests.swift b/Tests/PermissionGuideTests/PermissionGuideTests.swift index b9d430f..8fd3e95 100644 --- a/Tests/PermissionGuideTests/PermissionGuideTests.swift +++ b/Tests/PermissionGuideTests/PermissionGuideTests.swift @@ -192,6 +192,22 @@ private let password = SystemSettings.Prompt.authentication(NSRect(x: 200, y: 15 } } +@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 struct SystemExtensionSetupTests { private static let networkEntitlement = "com.apple.developer.networking.networkextension" diff --git a/docs/guide.md b/docs/guide.md index 390e70e..445b1ac 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -109,6 +109,8 @@ 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 tint: .systemPurple, // highlight and panel color isGranted: { helper.canRecord } // custom check, for when the default can't see it ) @@ -201,6 +203,21 @@ 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() } +) +``` + ## System extensions Describe each extension your app embeds, and track it like any other permission: @@ -300,8 +317,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:tint:isGranted:)` | Guides the user; installs system extensions and registers background items first | +| `guide(to:dragging:named:icon: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 f5f970a..5fcd12d 100644 --- a/llms.txt +++ b/llms.txt @@ -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:tint:isGranted:)` | Runs the guide. Installs a system extension or registers a background item first. | +| `guide(to:dragging:named:icon: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. `isGranted` can be `async`. Without it 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. ```swift await permissions.request( From 284101daaae6380bfcd517fb41938701bea3cfbc Mon Sep 17 00:00:00 2001 From: "Frank Chiarulli Jr." Date: Sun, 15 Nov 2026 20:40:43 -0500 Subject: [PATCH 4/4] Guide the user to a switch when a privacy pane already lists the app macOS adds some helpers to a privacy list itself, switched off, once they ask for access. The guide still said to drag an icon in. With alreadyListed it highlights the list and points at the switch. --- .../PermissionGuide/PermissionManager.swift | 26 ++++---- Sources/PermissionGuide/SettingsGuide.swift | 64 ++++++++++++------- Sources/PermissionGuide/SidecarPanel.swift | 3 - .../PermissionGuideTests.swift | 30 +++++++++ docs/guide.md | 26 ++++++-- llms.txt | 6 +- 6 files changed, 109 insertions(+), 46 deletions(-) diff --git a/Sources/PermissionGuide/PermissionManager.swift b/Sources/PermissionGuide/PermissionManager.swift index 3347eeb..f70f359 100644 --- a/Sources/PermissionGuide/PermissionManager.swift +++ b/Sources/PermissionGuide/PermissionManager.swift @@ -109,6 +109,7 @@ public final class PermissionManager { dragging appURL: URL = Bundle.main.bundleURL, named name: String? = nil, icon: NSImage? = nil, + alreadyListed: Bool = false, tint: NSColor = .controlAccentColor, isGranted: (@MainActor () async -> Bool)? = nil ) async -> PermissionResult { @@ -121,10 +122,10 @@ public final class PermissionManager { if service.status != .requiresApproval { return .failed(error) } } } - return await guide(to: permission, dragging: appURL, named: name, icon: icon, 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, named: name, icon: icon, 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 } @@ -133,7 +134,7 @@ public final class PermissionManager { guard let self, self.pending == permission else { return } switch event { case .needsUserApproval: - self.showGuide(for: permission, subject: subject, tint: tint, canCheck: isGranted != nil) + self.showGuide(for: permission, subject: subject, alreadyListed: alreadyListed, tint: tint, canCheck: isGranted != nil) case .activated: self.set(.granted, for: permission) self.finish(.granted) @@ -149,8 +150,9 @@ 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: @@ -160,6 +162,10 @@ public final class PermissionManager { /// 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). It can be `async`, to ask the @@ -172,6 +178,7 @@ public final class PermissionManager { dragging appURL: URL = Bundle.main.bundleURL, named name: String? = nil, icon: NSImage? = nil, + alreadyListed: Bool = false, tint: NSColor = .controlAccentColor, isGranted: (@MainActor () async -> Bool)? = nil ) async -> PermissionResult { @@ -186,7 +193,7 @@ public final class PermissionManager { begin(permission, isGranted: isGranted) let subject = SettingsGuide.Subject(url: appURL, name: name, icon: icon) - showGuide(for: permission, subject: subject, tint: tint, canCheck: isGranted != nil) + showGuide(for: permission, subject: subject, alreadyListed: alreadyListed, tint: tint, canCheck: isGranted != nil) return await waitForGrant() } @@ -201,13 +208,10 @@ public final class PermissionManager { pendingCheck = isGranted } - private func showGuide(for permission: Permission, subject: SettingsGuide.Subject, tint: NSColor, canCheck: Bool) { + 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 = switch permission { - case .systemExtension, .backgroundItem: .toggle(permission, confirmManually: !canVerify) - default: .drag(permission, confirmManually: !canVerify) - } + let mode = SettingsGuide.Mode(permission, alreadyListed: alreadyListed, confirmManually: !canVerify) SystemSettings.open(permission.settingsURL) guide.start(mode, subject: subject, tint: tint, relaunch: relaunchChoice) } diff --git a/Sources/PermissionGuide/SettingsGuide.swift b/Sources/PermissionGuide/SettingsGuide.swift index 1ed5b42..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,29 @@ 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. @@ -73,28 +106,11 @@ final class SettingsGuide { appName = subject.displayName let appURL = subject.url let icon = subject.displayIcon - 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) + 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 @@ -166,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/Tests/PermissionGuideTests/PermissionGuideTests.swift b/Tests/PermissionGuideTests/PermissionGuideTests.swift index 8fd3e95..eeec110 100644 --- a/Tests/PermissionGuideTests/PermissionGuideTests.swift +++ b/Tests/PermissionGuideTests/PermissionGuideTests.swift @@ -208,6 +208,36 @@ private let password = SystemSettings.Prompt.authentication(NSRect(x: 200, y: 15 } } +@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 445b1ac..1068a14 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -111,6 +111,7 @@ await permissions.request( 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 ) @@ -218,6 +219,20 @@ await permissions.request( ) ``` +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: @@ -288,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 @@ -317,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:named:icon:tint:isGranted:)` | Guides the user; installs system extensions and registers background items first | -| `guide(to:dragging:named:icon: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 5fcd12d..4d8198c 100644 --- a/llms.txt +++ b/llms.txt @@ -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:named:icon:tint:isGranted:)` | Runs the guide. Installs a system extension or registers a background item first. | -| `guide(to:dragging:named:icon: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. `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. +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(