feat(ui): guide macOS users to grant Full Disk Access when files are denied

[pmaxhogan]

The Full Disk Access onboarding surface for macOS TCC denials.

Stacked on #201 (base is feat/macos-apfs-wiring), which is itself stacked on #196. Rebase onto main once those land.

It also depends on #195 at runtime, but shares no lines with it. #195 is what makes the executor emit local.permission_denied; this PR is the UI that reacts to that code. The banner keys off the code as a plain string in entry.eventType, so nothing here needs #195 to compile or to pass tests - but the banner stays inert until #195 merges. I deliberately did NOT add the errors.local.permission_denied i18n entry, because #195 adds exactly that key and duplicating it would guarantee a conflict. All new strings live under a new fdaBanner namespace.

Why a banner at all

A TCC denial is invisible from the user's side: the backup "succeeds", certain files just never appear in Drive. The activity row alone does not tell anyone what to do about it. So the UI has to name the problem and point at the fix.

Detection

A root-mounted FdaBanner subscribes to activity:new (the ToastHost pattern, so a denial during a background cycle is not missed because the user was on another tab) and latches on the first row whose eventType is local.permission_denied.

No per-cycle bookkeeping: a denial is PERMANENT until the user acts, unlike a lock, so "has this ever happened" is the right question. Gating on backup_done would have been wrong twice over - failed ops suppress that row, and it is emitted per source rather than per cycle.

Dedupe

Since a denial is permanent, the same file emits one warn row EVERY cycle, forever. The banner counts DISTINCT files rather than rows, so a file denied across fifty cycles is reported once. Kept entirely in the display layer - the executor's emission and the activity store are untouched, so the raw rows stay available for diagnostics.

The deep link, and the trap under it

Button opens the FDA pane directly with:

x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles

Verified on this macOS 26.6 (25G72, arm64) machine, three ways:

• Opening it lands on a window titled exactly Full Disk Access.
• Control: the same URL with a bogus anchor (?Privacy_BogusAnchorXYZ) lands on Privacy & Security instead - so the anchor is genuinely load-bearing and the result is not a false positive.
• Real-world case: with System Settings already open on a different pane (Microphone), the deep link still navigates to Full Disk Access rather than no-opping.

opener:default would have blocked this. Its scope only permits mailto:, tel:, http://, https://, so openUrl with a custom scheme throws at runtime while every mocked test still passes. src-tauri/capabilities/default.json now carries an explicit scoped entry:

{ "identifier": "opener:allow-open-url", "allow": [{ "url": "x-apple.systempreferences:*" }] }

Verified end to end: the entry is present in the generated src-tauri/gen/schemas/capabilities.json, and glob::Pattern::new("x-apple.systempreferences:*") (the same glob crate the opener plugin matches with) returns true for the exact target URL and false for file:///etc/passwd, https://evil.example, and x-apple.systemprefsX:y - so the scope admits the pane and nothing else.

The unsigned-binary caveat (real, recurring)

macOS binds a TCC grant to the binary's code signature (cdhash), not its path. Driven's V1 builds are unsigned, so every update is a different program as far as TCC is concerned, and a working grant can silently stop applying - the app still shows in the Full Disk Access list with its switch on while being denied. This is stated in one line in the banner copy and explained with the remove-and-re-add fix in the README.

Docs

• README: a new "macOS: Full Disk Access (privacy protection)" section (what TCC blocks, the 3-step grant, the unsigned-binary invalidation and its fix) and a "What locked-file backup covers on macOS (and what it does not)" section with a table splitting local.file_locked (fix: APFS snapshot toggle) from local.permission_denied (fix: FDA, nothing else).
• DESIGN s5.3.3: the onboarding design - trigger, dedupe rationale, the deep link and its capability-scope requirement, why dismissal is per-session, and the unsigned-binary caveat.
• I did NOT touch SPEC's error-code list; fix(core): classify macOS locked and permission-denied opens into the skip-and-report path #195 owns that entry.

Accuracy point held throughout: APFS snapshots do NOT bypass TCC. A snapshot mount preserves the original's ownership and is itself TCC-gated, and the -o noowners bypass was CVE-2020-9771 - patched, and now an EDR-flagged signature Driven deliberately does not emit. Nothing in these docs implies snapshots substitute for FDA; the README table makes the split explicit.

Judgment calls

• Dismissal is per-session (in-memory), not persisted. localStorage/sessionStorage appear zero times in ui/src, and the only dismissible-banner precedent (stores/updater.ts) is an in-memory Pinia ref, so this matches it. It is also the better semantic: the condition is unresolved until FDA is granted, so permanently silencing it would hide an ongoing data-coverage gap. Once granted, the denials stop and the banner stops on its own. A persisted flag would have meant a new settings-schema field, and this stack already adds one.
• No platform check. local.permission_denied can only be emitted on macOS, so the banner is inherently mac-only - the same way the VSS banner derives purely from backend state rather than sniffing the userAgent.
• Live events only, no backfill query. The banner is root-mounted for the app's whole lifetime, so it catches every denial while running; a denial from a previous run resurfaces on the next cycle. Adding a startup query_activity backfill would show it a little sooner and is an easy follow-up, but it is not needed for correctness.

Gates

• pnpm --dir ui lint, test:unit, build, format:check - all green
• SQLX_OFFLINE=true cargo test --workspace, cargo clippy --workspace --all-targets -- -D warnings, cargo fmt --all -- --check - all green
• New FdaBanner.vue has a vitest mount test (coverage gate), covering hidden-by-default, show-on-denial, ignore-other-codes, dedupe, multi-file count, the exact deep-link URL string, dismissal stickiness, and the unsigned-binary note.

Not verified

The in-app path is not exercised end to end. cargo tauri dev never passes --config, so there is no dev bundle with the sidecar, and the UI tests mock @tauri-apps/plugin-opener - they prove the button calls openUrl with the right string, not that the call succeeds inside a running Driven. What IS verified is each link in that chain independently: the URL against real System Settings with a control, the capability entry in the generated ACL, and the glob match against the shipped pattern.

---

Note on CI: ci.yml, coverage.yml and friends are declared on: pull_request: branches: [main], so a PR whose base is a feature branch gets NO checks beyond the PR-title gate. That is why every gate in this description was run locally on this machine and reported verbatim rather than pointed at a green CI run. Retargeting this PR to main after the parent PRs merge will trigger the real matrix.

---

Update: #195 merged to main (08d2864) while this was being written. That is the PR that makes the executor emit local.permission_denied, so once this stack is rebased onto main the banner is live rather than inert. Nothing here needs changing - this PR still shares no lines with #195, and deliberately does not define the errors.local.permission_denied i18n key that #195 already added.

Cross-checked the predicate against merged main, since a wrong literal would make this banner silent dead code that no gate in this repo would catch:

• crates/driven-core/src/types.rs on main: ErrorCode::LocalPermissionDenied => "local.permission_denied" (and the matching from_code arm).
• crates/driven-core/tests/e2e_fake.rs on main (fix(core): classify macOS locked and permission-denied opens into the skip-and-report path #195's own e2e): queries event_types: vec!["local.permission_denied".to_string()] and asserts exactly one warn row for the one unreadable file.

So the activity row's event_type is exactly the string this banner matches on.

Merge-conflict warning for whoever resolves this one: ui/src/__tests__/app-shell.test.ts contains a single-line change, expect(listenMock).toHaveBeenCalledTimes(8) -> (9), because mounting FdaBanner at the app root adds one listen registration. That number is an arithmetic invariant, not a preference. If another PR also adds a root-level subscription and touches the same line, the resolution must be the SUM of both additions, not either side's value. Picking one side would silently lose a subscription's worth of coverage while still passing.

---

Rebased onto the re-cut #201 (which is now based on main)

Re-cut and re-applied rather than rebased through #196's squash-merge. Retarget this to main once #201 lands.

#195 is on main now, so the local.permission_denied rows this banner keys off are really emitted - the banner is live, not inert. Still shares no lines with #195 and still does not define the errors.local.permission_denied key that #195 owns.

The app-shell.test.ts listener count is still correct arithmetic after the rebase: main is at 8, this PR is at 9 (+1 for FdaBanner). Main's exclusion-preview listener fix (#206) did not add a root-level App.vue subscription, so no adjustment was needed. The merge-conflict warning above still applies.

Added: a user-facing note that this feature is inert on a stock install

While verifying #201's sidecar work I found that #196's broker refuses to serve when the helper's directory is writable by the client uid - and every DMG drag-install produces exactly that, including into /Applications (measured across 7 real apps on macOS 26.6; only pkg/App-Store installs are root:wheel). Confirmed by running the real broker binary from a user-owned directory and getting its refusal.

Since the README is where a user would look, the "What locked-file backup covers on macOS" section now carries a blockquote saying plainly that the APFS snapshot setting does not work from a drag-installed .app, why (the helper cannot authenticate a caller who could plant a binary beside it), and that fixing it needs a .pkg-style install that leaves the bundle root-owned. It also says this is a deliberate safety property, not a bug - so nobody "fixes" it by weakening the check.

This does not affect the FDA banner itself, which is about TCC denials and works regardless of install layout.

Gates re-run after the rebase

UI: lint 0 errors, 549 tests / 44 files, build clean, format:check clean. Rust: cargo test --workspace 41 suites / exit 0, clippy -D warnings clean, cargo fmt --all --check clean.

---

Correction: the README note about drag-installs was wrong and has been rewritten

The blockquote this PR previously added said locked-file backup is inert on a drag-installed .app and framed the helper's refusal as a deliberate safety property. #211 downgraded that check from fatal to advisory, so that is no longer true. I have replaced the blockquote rather than deleted it, because the situation is still worth one honest paragraph for users - just not the one I wrote.

The replacement says, in user-facing language:

• One defence-in-depth check is weaker on a normal install. The helper confirms that whatever talks to it sits next to it in the same folder, which only proves much if you could not write to that folder yourself - and dragging an app out of a .dmg makes you the owner of its contents (true even into /Applications; only .pkg/App Store installs land root-owned). So the check is advisory there and the helper records a DEGRADED line in its own log.
• Locked-file backup still works. The checks carrying the real weight are unaffected: the helper only talks to your own user account, only mounts volumes Driven listed at launch, and only makes read-only mounts preserving original file ownership.
• Someone defeating the folder check would already have to be running as you, and would gain a read-only copy of files they could already read.
• A .pkg install would restore full strength - an improvement, not a prerequisite.

No scare framing, and no claim that it does not matter at all.

None of this affects the FDA banner itself, which is about TCC denials and behaves identically regardless of install layout.

Gates after the rebase and rewrite

UI: lint 0 errors, 549 tests / 44 files, build clean, format:check clean. Rust: cargo test --workspace 41 suites / exit 0, clippy -D warnings clean, cargo fmt --all --check clean. The app-shell.test.ts listener count is still main+1 (8 -> 9); the merge-conflict note above still applies.

---

Rebased, and reconciled with #209's docs refresh

#209 landed a README section, "macOS Full Disk Access (separate from Gatekeeper)", that overlaps what this PR was adding. Rather than carry a near-duplicate section, I dropped my version and edited #209's in place. The net diff is now much smaller and the README has one FDA section instead of two.

What changed in #209's section:

• "There is currently no in-app guided flow for granting Full Disk Access - that is planned for a future release" was the sentence this PR falsifies. Replaced with the real flow: the banner appears on the first refused read, has a button that opens the pane directly, and is dismissible. Plus the three grant steps, including "quit and reopen Driven" (a grant only applies to a newly launched process, which is the step people miss).
• Added the unsigned-binary caveat, which docs: refresh the docs for the 2.5.0 feature set #209's section does not cover: macOS binds the grant to the binary's cdhash, Driven is unsigned, so an update can silently invalidate a working grant while the app still appears in the list with its switch on. Fix is remove-and-re-add.
• Kept docs: refresh the docs for the 2.5.0 feature set #209's "a locked-file snapshot is not a substitute for Full Disk Access" paragraph and did not duplicate it. It is well written and already carries the CVE-2020-9771 history.

Flipped the roadmap bullet. #209 left a DRAFT - do not uncomment until the corresponding PR merges block containing "Guided Full Disk Access onboarding for macOS ... (#205, unmerged.)" - which is this PR. It is now a live feature bullet and the draft entry is gone, so the README is accurate the moment this merges. The remaining draft bullets (S3, local destination, scrub, restore drill, rclone importer) are untouched, and the comment wrapper stays for them.

Gates

UI: lint 0 errors, 559 tests / 45 files, build clean, format:check clean. Rust: cargo test --workspace --exclude driven-backend 43 suites / exit 0, clippy -D warnings clean, cargo fmt --all --check clean.

The exclusion is not this branch's doing - see the note on #201: #200's new driven-backend crate has two keychain tests that block on an invisible macOS SecurityAgent prompt on this machine. They pass in CI, and neither of these PRs touches that crate.

---

Rebased onto the re-cut #201, which now sits on main with #211, #207 and #209

Still needs retargeting to main once #201 lands.

Gates re-run, now WITHOUT the --exclude driven-backend workaround

#207 fixed the keyring mock, so the full suite runs again:

• SQLX_OFFLINE=true cargo test --workspace - 48 suites, exit 0, no exclusions
• pgrep SecurityAgent empty throughout - no keychain prompt raised
• clippy -D warnings clean, cargo fmt --all --check clean
• UI: lint 0 errors, 566 tests / 45 files, build clean, format:check clean

The app-shell.test.ts listener count remains main + 1 for FdaBanner; the merge-conflict note earlier in this description still applies.