pmaxhogan
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 55 additions & 0 deletions b/‎CONTRIBUTING.md‎
Lines changed: 55 additions & 0 deletions
diff --git a/‎Cargo.lock‎
Lines changed: 7 additions & 3 deletions b/‎Cargo.lock‎
Lines changed: 7 additions & 3 deletions
diff --git a/‎README.md‎
Lines changed: 35 additions & 0 deletions b/‎README.md‎
Lines changed: 35 additions & 0 deletions
diff --git a/‎crates/driven-backend/Cargo.toml‎
Lines changed: 8 additions & 11 deletions b/‎crates/driven-backend/Cargo.toml‎
Lines changed: 8 additions & 11 deletions
diff --git a/‎crates/driven-backend/src/lib.rs‎
Lines changed: 25 additions & 55 deletions b/‎crates/driven-backend/src/lib.rs‎
Lines changed: 25 additions & 55 deletions
diff --git a/‎crates/driven-crypto/Cargo.toml‎
Lines changed: 10 additions & 0 deletions b/‎crates/driven-crypto/Cargo.toml‎
Lines changed: 10 additions & 0 deletions
@@ -105,6 +105,61 @@ example real-Google-Drive end-to-end tests with no credentials, or VSS /
 elevation tests without admin). A clean run is all-pass plus those honest skips,
 not a hidden failure.
 
+### The test suite is isolated from your OS keychain
+
+`cargo test --workspace` must never touch your real login keychain, and it
+does not. Any test that can reach a keychain entry - Driven stores the account
+master key under `dev.maxhogan.driven`, the Google secrets under
+`driven.google.refresh_token` / `driven.google.client_creds`, and S3 key pairs
+under `driven.s3.credentials` - starts with:
+
+```rust
+let Some(_guard) = driven_test_fixtures::keychain::isolated() else {
+    return; // could not isolate; skip rather than write to a real keychain
+};
+```
+
+`isolated()` installs `keyring-core`'s in-memory mock as the process-global
+default credential store, proves it is the effective store before the test is
+allowed to store anything, and returns `None` (so the test skips honestly) if it
+cannot. Add that line to any new test that reaches the keychain, and add
+`driven-test-fixtures` to your crate's `[dev-dependencies]` if it is not there
+yet. Every crate that owns a keychain call site - `driven-crypto`,
+`driven-drive`, `driven-s3`, `driven-backend`, `src-tauri` - already has the
+wiring and a
+`the_test_suite_is_isolated_from_the_os_keychain` guard test, so if the
+mechanism ever breaks (a `keyring` upgrade, say) those fail loudly instead of
+the suite quietly starting to write for real.
+
+**Why this matters more on macOS.** macOS ties a keychain ACL to the identity
+of the binary that was granted access, and every `cargo test` rebuild produces a
+binary with a new identity. So a single test that reaches the real keychain
+raises a modal "allow ... to access ..." prompt on *every* rebuild - clicking
+"Always Allow" does not help, because the next build is a different app - and
+the run blocks on the dialog until you answer it. (The same mechanism means
+released builds re-prompt users on every update; see the macOS notes in the
+README.) Ordering is load-bearing here: `keyring` 4.x's `Entry::new` installs
+the platform-native store on its *first* call and overwrites whatever default is
+already set, so installing the mock without first burning that latch is silently
+undone. `crates/driven-test-fixtures/src/keychain.rs` documents the sequence -
+use the helper rather than re-deriving it.
+
+If you ran the suite before this isolation landed, you may have leftover
+test-only items in your login keychain. Remove them with:
+
+```sh
+security delete-generic-password -s "driven.google.refresh_token" -a "acct-with-token"
+security delete-generic-password -s "driven.google.client_creds"  -a "acct-byo"
+security delete-generic-password -s "driven.s3.credentials"       -a "acct-s3-round-trip"
+security delete-generic-password -s "driven.s3.credentials"       -a "acct-a"
+security delete-generic-password -s "driven.s3.credentials"       -a "acct-b"
+security delete-generic-password -s "driven.s3.credentials"       -a "acct-s3-delete"
+security delete-generic-password -s "driven.s3.credentials"       -a "acct-control-chars"
+```
+
+A `security: ... could not be found in the keychain` for any of these just means
+that one never leaked on your machine.
+
 ## Coverage gate
 
 The `coverage` workflow (`.github/workflows/coverage.yml`) measures line
 
@@ -272,6 +272,41 @@ unmounts. It works without Time Machine being set up.
 > would already have to be running as you, and would gain a read-only copy of
 > files they could already read. Installing from a `.pkg` would restore the
 > check to full strength; it is an improvement, not a prerequisite.
+#### macOS re-prompts for keychain access after every update
+
+macOS ties a permission grant to the *identity* of the binary that was granted
+it. Driven's macOS build carries no Developer ID signature - the Mach-O is only
+ad-hoc (linker) signed, which gives it no stable
+[designated requirement](https://developer.apple.com/library/archive/technotes/tn2206/_index.html),
+so its code-directory hash changes with every build. A Developer ID signature
+would let the OS recognise version 2.4 and version 2.5 as the same app; without
+one, it cannot.
+
+The practical consequence, once per update:
+
+- **Keychain.** Every credential Driven holds lives in your login keychain: the
+  account master key (service `dev.maxhogan.driven`), the Google refresh token
+  (`driven.google.refresh_token`), your BYO OAuth client credentials
+  (`driven.google.client_creds`), and any S3 key pair
+  (`driven.s3.credentials`). "Always Allow" records the *specific* build you
+  allowed, so after an update macOS asks again. Apple's own description of the
+  dialog is "This dialog appears if you recently updated your system software or
+  the app, or if the app has been modified". Click **Always Allow** once after
+  each update and Driven picks up where it left off. If you deny it, Driven does
+  not quietly fall back to storing your files unencrypted - an encrypted source
+  whose master key it cannot read fails closed and reports `crypto.key_missing`
+  in the activity log.
+- **Full Disk Access.** The same identity check applies to macOS's privacy
+  layer, so a previously granted Full Disk Access can stop taking effect after
+  an update even though Driven still appears (checked) in the list. If backups
+  of protected folders start failing with permission errors right after an
+  update, remove Driven from System Settings > Privacy & Security > Full Disk
+  Access with the "-" button and re-add it with "+". Driven's in-app Full Disk
+  Access banner says the same thing when it detects denied files.
+
+Both go away for good with a Developer ID signature; there is no partial
+workaround that makes an ad-hoc-signed build's grants survive an update. This
+is tracked with the other signing work below.
 
 #### macOS auto-updater caveat
 
 
@@ -24,16 +24,13 @@ anyhow.workspace = true
 tracing.workspace = true
 
 [dev-dependencies]
-# `keyring` 4.x is a thin wrapper over `keyring-core`, whose `mock` module is an
-# IN-MEMORY credential store installable as the process default. That makes the
-# keychain-backed paths (the factory's Drive arm, the BYO client-creds
-# resolution) coverable by real tests instead of being untestable on a headless
-# CI box with no OS keychain - the constraint `driven-drive`'s `token_store`
-# module documents and had to work around. Dev-only: production always uses the
-# real per-OS store.
-keyring-core = "1"
-# The facade production uses. The test helper needs it to burn keyring 4.x's
-# one-shot platform-store latch before the in-memory mock can stick.
-keyring.workspace = true
+# `driven_test_fixtures::keychain::isolated()` installs (and PROVES) an
+# in-memory credential store as the process default, so the keychain-backed
+# paths here - the factory's Drive arm, the BYO client-creds resolution - are
+# covered by real tests that never reach an OS keychain: neither the
+# developer's login keychain (which on macOS re-prompts on every rebuild) nor a
+# headless CI box's absent one. Dev-only: production always uses the real
+# per-OS store.
+driven-test-fixtures = { path = "../driven-test-fixtures" }
 # The local-folder tests need a throwaway destination directory.
 tempfile = "3"
@@ -420,63 +420,19 @@ pub fn resolve_account_oauth_creds(account_id: &str) -> (String, String) {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use std::sync::{Mutex, OnceLock};
 
-    /// Install `keyring-core`'s IN-MEMORY store as the process default, so the
-    /// keychain-backed paths run for real without touching (or requiring) an OS
-    /// keychain.
+    /// Isolate this test from the OS keychain, so the keychain-backed paths run
+    /// for real against an in-memory store without touching (or requiring) a
+    /// real one. Returns `None` when isolation could not be established, in
+    /// which case the caller MUST skip - see
+    /// [`driven_test_fixtures::keychain`] for why writing for real is not an
+    /// acceptable fallback (on macOS it blocks the run on a modal prompt).
     ///
-    /// Returns `None` when the mock could not be made the EFFECTIVE store, in
-    /// which case the caller MUST skip - the alternative is writing test
-    /// secrets into the developer's real login keychain, which on macOS also
-    /// blocks the run on a modal permission prompt.
-    ///
-    /// ## Ordering is load-bearing
-    ///
-    /// `keyring` 4.x's `Entry::new` installs the PLATFORM-NATIVE store on its
-    /// FIRST call, overwriting whatever default is already set (see
-    /// `keyring-4.1.5/src/v1.rs`, the `SET_CREDENTIAL_STORE` latch). Installing
-    /// the mock first is therefore silently undone by the first real `Entry`,
-    /// and every "mock" write lands in the OS keychain instead. So this burns
-    /// that latch first with a throwaway `Entry` (constructing one performs no
-    /// credential I/O), THEN installs the mock, and finally PROVES the mock is
-    /// in effect with a sentinel round trip before any test stores a secret.
-    fn keychain() -> Option<std::sync::MutexGuard<'static, ()>> {
-        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
-        static ACTIVE: OnceLock<bool> = OnceLock::new();
-        let guard = LOCK
-            .get_or_init(|| Mutex::new(()))
-            .lock()
-            .unwrap_or_else(|e| e.into_inner());
-        let active = *ACTIVE.get_or_init(|| {
-            // 1. Burn keyring's one-shot platform-store latch. Its error on a
-            //    headless box (no secret service) is expected and ignored.
-            let _ = keyring::Entry::new("driven.test.keyring-latch", "latch");
-            // 2. Now the mock sticks.
-            match keyring_core::mock::Store::new() {
-                Ok(store) => keyring_core::set_default_store(store),
-                Err(_) => return false,
-            }
-            // 3. Prove it, through the same `keyring` facade production uses.
-            let sentinel = match keyring::Entry::new("driven.test.sentinel", "probe") {
-                Ok(e) => e,
-                Err(_) => return false,
-            };
-            if sentinel.set_password("mock-is-active").is_err() {
-                return false;
-            }
-            let ok = sentinel.get_password().ok().as_deref() == Some("mock-is-active");
-            let _ = sentinel.delete_credential();
-            ok
-        });
-        if !active {
-            eprintln!(
-                "skipping the keychain test: the in-memory keyring store is not the effective \
-                 default, and this test will not write to a real OS keychain"
-            );
-            return None;
-        }
-        Some(guard)
+    /// The returned guard also serializes these tests: the default credential
+    /// store is process-global, so they key their entries by a unique account
+    /// id and take turns.
+    fn keychain() -> Option<driven_test_fixtures::keychain::KeychainGuard> {
+        driven_test_fixtures::keychain::isolated()
     }
 
     /// Env vars are process-global too; `env_oauth_creds` reads them, so the
@@ -492,6 +448,20 @@ mod tests {
         }
     }
 
+    #[test]
+    fn the_test_suite_is_isolated_from_the_os_keychain() {
+        // The guard for this whole crate: if the isolation mechanism ever stops
+        // working (a `keyring` upgrade changing how the default store is
+        // installed, say), fail HERE and loudly rather than letting the
+        // keychain tests below silently skip - or, worse, start writing into a
+        // real login keychain, which is exactly what happened when the mock was
+        // installed BEFORE `keyring` had claimed the default store.
+        assert!(
+            driven_test_fixtures::keychain::is_isolated(),
+            "the in-memory keyring store must be the effective default store"
+        );
+    }
+
     #[test]
     fn descriptors_cover_every_kind_in_picker_order() {
         let d = descriptors();
 
@@ -42,3 +42,13 @@ md5 = { workspace = true }
 # directly via `RngCore`/`TryRngCore`, so the two `rand_core` major versions
 # never need to match.
 rand = "0.10"
+
+[dev-dependencies]
+# `driven_test_fixtures::keychain::isolated()` binds keyring to an in-memory
+# mock store, so the [`Keystore`] round-trip tests exercise the real API
+# without touching a developer's login keychain (which on macOS re-prompts on
+# every rebuild) or needing one at all on headless CI. The dependency edge is a
+# cycle - driven-test-fixtures depends on driven-core, which depends on this
+# crate - which cargo permits precisely because it is dev-only and so cannot
+# appear in a shipped build.
+driven-test-fixtures = { path = "../driven-test-fixtures" }