Skip to content

Better guides for helpers and system extensions - #1

Merged
fcjr merged 4 commits into
mainfrom
helper-guides
Nov 16, 2026
Merged

fcjr merged 4 commits into
mainfrom
helper-guides

Conversation

@fcjr

@fcjr fcjr commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Four changes that came out of wiring PermissionGuide into an app whose Endpoint Security system extension, not the app, needs Full Disk Access. One commit each.

Changes

Full Disk Access reads .unknown when SIP is off. The check opens TCC.db, which only Full Disk Access can open. On a Mac with System Integrity Protection disabled (seen on macOS 27.2), an app that was never granted anything opens it fine, so status, request and the probe all said granted. currentStatus now returns .unknown there, which gives the guide its Done button and stops the probe from being launched for it. Detection is csr_check(CSR_ALLOW_UNRESTRICTED_FS), a libSystem SPI, weak-imported like the responsibility call the probe already uses.

isGranted can be async. A helper's permissions are usually read over IPC, and the synchronous closure forced callers to cache the last answer. The manager now awaits each call and makes one at a time. Synchronous closures still compile unchanged.

named: and icon: for the bundle being granted. The panel took both from the dragged bundle, so a .systemextension showed a generic icon and its file name.

alreadyListed: for privacy panes. macOS adds some helpers to a privacy list itself, switched off. The guide still said "Drag this icon". With alreadyListed: true it highlights the list, shows no drag source or ghost, and says to turn on the switch.

await permissions.request(
    .fullDiskAccess,
    dragging: monitor.embeddedURL()!,
    named: "Example",
    icon: NSApp.applicationIconImage,
    alreadyListed: true,
    isGranted: { await monitor.hasFullDiskAccess() }
)

All three new parameters default to today's behaviour.

Testing

  • swift build, swift test (6 new tests) and both example packages build.
  • New tests cover the mode and instruction text for each permission kind, the name and icon fallback, an async check that already passes, and the SIP wiring.
  • Not exercised on screen: the switch-on guide over a real privacy pane. The sidecar text moved into Mode.instructions(subject:), and the existing drag, extension and background-item strings are unchanged, but someone should run the demo before merging.
  • Not confirmed: that macOS lists an Endpoint Security extension in Full Disk Access by itself after es_new_client fails. That is what other ES products document. If it doesn't, alreadyListed is still correct for the helpers that do get listed.

fcjr added 4 commits November 15, 2026 20:38
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.
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.
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.
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.
@fcjr
fcjr merged commit 596bb29 into main Nov 16, 2026
1 check passed
@fcjr
fcjr deleted the helper-guides branch November 16, 2026 01:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant