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

A TCC denial is invisible from the user's side: the backup "succeeds",
some files just never reach Drive. Add a root-mounted dismissible banner
that latches on the first local.permission_denied activity row, counts
DISTINCT files (a denial is permanent, so the same file is re-reported
every cycle, unbounded), and offers a one-click deep link to the Full
Disk Access pane.

The deep link needs an explicit opener capability scope: opener:default
only permits mailto/tel/http/https, so a custom scheme would throw at
runtime while every mocked test still passed.

Document in README and DESIGN s5.3.3 that APFS snapshots do NOT bypass
TCC, and that an unsigned binary's TCC grant can silently invalidate on
update because macOS binds the grant to the code signature.

Author: pmaxhogan

README.md

@@ -169,6 +169,61 @@ macOS will refuse to open an unsigned app on a double-click. Either:
   xattr -dr com.apple.quarantine "/Applications/Driven.app"
   ```
 
+#### macOS: Full Disk Access (privacy protection)
+
+macOS TCC ("Transparency, Consent, and Control", the privacy layer) blocks every
+app from reading certain locations no matter what the file permissions say -
+Mail, Messages, Safari data, Photos, and parts of `~/Library`. When Driven hits
+one of these it does not fail the backup: it skips that file, reports it as
+`local.permission_denied` in the activity log, and retries it next cycle. The
+rest of the source backs up normally.
+
+To back those files up, grant Driven Full Disk Access:
+
+1. Open System Settings > Privacy & Security > Full Disk Access. Driven's
+   in-app banner has a button that opens this pane directly; from a terminal
+   the equivalent is:
+
+   ```sh
+   open 'x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles'
+   ```
+
+2. Add Driven with the `+` button (or drag `Driven.app` in) and switch it on.
+3. Quit and reopen Driven. A TCC grant only applies to a newly launched
+   process, so the running app will keep skipping until you restart it.
+
+**A grant can silently stop working after an update, because Driven is
+unsigned.** macOS ties a Full Disk Access grant to the binary's code signature
+(its cdhash), not to its path or name. Driven's V1 builds are not signed with a
+Developer ID, so as far as TCC is concerned each new build is a *different*
+program. After you install an update the grant may quietly stop applying and the
+`local.permission_denied` skips come back, even though Driven still appears in
+the Full Disk Access list with its switch on. The fix is to remove the stale
+Driven entry from that list, re-add the new app, and relaunch. This is a
+consequence of the missing code signature rather than a bug, and it goes away
+once macOS code signing lands (see the caveat below).
+
+#### What locked-file backup covers on macOS (and what it does not)
+
+Two different problems are easy to confuse here, and only one of them has a
+snapshot-based fix:
+
+| Situation | Reported as | Fix |
+|-----------|-------------|-----|
+| The file is held open / busy - a live database, a VM disk, a mail store | `local.file_locked` | Turn on "Back up locked files using an APFS snapshot" in Settings > Rules |
+| macOS privacy protection denies the read | `local.permission_denied` | Grant Full Disk Access (above). Nothing else works. |
+
+The APFS snapshot option mounts a read-only APFS local snapshot through a small
+helper that gets administrator access once per session, so Driven can read a
+file that is busy while the app itself stays un-elevated.
+
+It does **not** read around a TCC denial. A snapshot mount preserves the
+original file's ownership and the mounted tree is itself subject to TCC. The old
+`-o noowners` trick that did bypass this was CVE-2020-9771, fixed by Apple years
+ago, and is now a pattern endpoint-security tools flag - Driven deliberately
+does not use it. So a TCC-denied file needs Full Disk Access, and no snapshot
+setting substitutes for it.
+
 #### macOS auto-updater caveat (V1)
 
 Because the macOS build is not signed with a Developer ID in V1, the in-app

design/DESIGN.md

@@ -736,6 +736,61 @@ patched, and now an EDR-flagged signature we deliberately do not emit. A
 `local.permission_denied` file needs Full Disk Access; no snapshot setting
 substitutes for it.
 
+#### 5.3.3 Full Disk Access onboarding (macOS)
+
+The remedy s5.3.2 cannot provide. A `local.permission_denied` skip means TCC
+refused the read, and the ONLY fix is the user granting Driven Full Disk
+Access. So the UI has to ask, and has to ask well: the failure is silent
+from the user's point of view (the backup "succeeds", some files just never
+appear), and the error text alone does not tell them where to go.
+
+**Trigger.** A root-mounted banner subscribes to the `activity:new` stream
+and latches on the first row whose `event_type` is `local.permission_denied`.
+It is root-mounted (the `ToastHost` pattern) rather than living on a single
+view, so a denial during a background cycle is not missed just because the
+user happens to be on another tab. There is deliberately no per-cycle
+bookkeeping: a denial is PERMANENT until the user acts, unlike a lock, so
+"has this ever happened" is the right question and a sticky latch is the
+right shape. Gating on the `backup_done` row would have been wrong twice
+over - failed ops suppress it, and it is emitted per source, not per cycle.
+
+**Deduplication.** Because a denial is permanent, the same file produces one
+warn row EVERY cycle, forever - an unbounded stream. The banner therefore
+counts DISTINCT files, not rows, so a file denied across fifty cycles is
+reported once. This aggregation lives purely in the display layer; neither
+the executor's emission nor the activity store changes, so the raw rows stay
+available for diagnostics.
+
+**The deep link.** The banner's primary action opens the Full Disk Access
+pane directly via
+`x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles`.
+Two things make this work and both are load-bearing: the anchor is
+version-sensitive (a wrong or stale one silently lands the user on the
+generic Privacy & Security list, which is why it is verified against a
+control rather than assumed), and the custom scheme must be added to the
+opener plugin's capability scope - `opener:default` only permits
+`mailto:`/`tel:`/`http`/`https`, so without an explicit
+`opener:allow-open-url` scope entry the button would throw at runtime while
+every mocked test still passed.
+
+**Dismissal is per-session, on purpose.** The banner is dismissible, but the
+dismissal is in-memory and does not persist across restarts (matching the
+one existing dismissible-banner precedent, the updater's). That is the
+correct semantic here rather than a shortcut: the underlying condition is
+unresolved until FDA is granted, so permanently silencing it would hide a
+real, ongoing data-coverage gap. Once the grant is in place the denials stop
+and the banner stops appearing on its own.
+
+**The unsigned-binary caveat is part of the copy, not a footnote.** macOS
+binds a TCC grant to the binary's code signature (its 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 previously working grant can silently stop
+applying - the app still appears in the Full Disk Access list, switch on,
+while being denied. This is a recurring, confusing support case rather than
+a hypothetical, so the banner states it in one line and the README explains
+the remove-and-re-add fix in full. It resolves itself when macOS code
+signing lands.
+
 ### 5.4 Upload pipeline
 
 Per-account:

src-tauri/capabilities/default.json

@@ -9,6 +9,10 @@
     "dialog:default",
     "updater:default",
     "process:default",
-    "opener:default"
+    "opener:default",
+    {
+      "identifier": "opener:allow-open-url",
+      "allow": [{ "url": "x-apple.systempreferences:*" }]
+    }
   ]
 }

ui/src/App.vue

@@ -3,6 +3,7 @@ import { onMounted } from "vue";
 import { useRoute } from "vue-router";
 import { useI18n } from "vue-i18n";
 
+import FdaBanner from "./components/FdaBanner.vue";
 import GlobalProgressBar from "./components/GlobalProgressBar.vue";
 import PausedBanner from "./components/PausedBanner.vue";
 import ToastHost from "./components/ToastHost.vue";
@@ -134,6 +135,11 @@ const NAV_LINK_ACTIVE = "text-teal-700 dark:text-teal-300 font-semibold";
     <header class="sticky top-0 z-30 bg-zinc-50 dark:bg-zinc-950" data-testid="app-header">
       <GlobalProgressBar />
       <PausedBanner />
+      <!-- macOS TCC (DESIGN s5.3.2): shown only once a read has actually been
+           refused, so it costs nothing on Windows/Linux. Lives in the sticky
+           header - and therefore mounts for the app's whole lifetime - so it
+           cannot miss the `activity:new` denial it subscribes to. -->
+      <FdaBanner />
       <nav
         class="flex flex-wrap items-center gap-x-6 gap-y-2 border-b border-zinc-200 bg-white px-6 py-3 text-sm dark:border-zinc-800 dark:bg-zinc-900"
         :aria-label="t('nav.primary')"

ui/src/__tests__/app-shell.test.ts

@@ -171,8 +171,9 @@ describe("App shell", () => {
     // progress store's TWO sync events (status_changed for the phase,
     // source_progress for the moving counters) + the pause event registered +
     // the two ToastHost subscriptions (status_changed for "Backup started",
-    // activity:new for the backup_done row behind "Backup complete").
-    expect(listenMock).toHaveBeenCalledTimes(8);
+    // activity:new for the backup_done row behind "Backup complete") + the
+    // FdaBanner's own activity:new subscription (the macOS TCC denial row).
+    expect(listenMock).toHaveBeenCalledTimes(9);
     expect(invokeMock).toHaveBeenCalledWith("get_pending_update_info", undefined);
     expect(invokeMock).toHaveBeenCalledWith("get_sync_status", undefined);
     expect(invokeMock).toHaveBeenCalledWith("get_pause_state", undefined);