car_secrets/

lib.rs

//! Cross-platform secret store for Common Agent Runtime.
//!
//! Unifies OS-native secure storage across the three platforms CAR targets:
//!
//! - **macOS** — `/usr/bin/security` over Keychain Services
//! - **Windows** — Credential Manager (DPAPI)
//! - **Linux** — Secret Service (GNOME Keyring / KWallet / KeePassXC /
//!   anything else that speaks `org.freedesktop.secrets`)
//!
//! The API is intentionally small: `put`, `publish`, `get`, `delete`, `status`,
//! `list`. Callers choose a namespace (`service`) and a key (`account`); values
//! are UTF-8 strings. JSON helpers are provided for structured values.
//!
//! # Availability
//!
//! On headless Linux without a Secret Service daemon, `put`/`get`/`delete`
//! return [`SecretError::Unavailable`]. This is explicit: there is no silent
//! plaintext fallback. Callers should probe [`is_available`] before relying on
//! the store, or handle `Unavailable` with their own fallback.
//!
//! # Security boundary
//!
//! Secrets never enter CAR memory, state, or prompt context unless a caller
//! explicitly reads them and passes them into one of those systems. The store
//! treats a missing backend as a hard error so misconfigured environments are
//! loud, not silently insecure.

// The in-process keyring path is every platform except macOS. macOS routes
// every operation — reads, writes, status, deletes, and the availability
// probe — through `/usr/bin/security` instead, so nothing there opens an
// `Entry` (Parslee-ai/car#897).
#[cfg(not(target_os = "macos"))]
use keyring::Entry;
use serde::{Deserialize, Serialize};
use thiserror::Error;

pub mod secure_path;
pub use secure_path::{
    atomic_replace_private_file, create_private_file, create_private_file_with_failure_injector,
    ensure_private_dir, ensure_private_dir_with_failure_injector, harden_owner_only,
    harden_owner_only_fallible, harden_private_tree, open_private_append,
    open_private_append_with_failure_injector, open_private_read, open_private_truncate,
    revalidate_private_file, revalidate_private_path, PrivatePathDurabilityFailureInjector,
    PrivatePathDurabilityFailurePoint, PrivateTree, PrivateTreePolicy, PrivateTreeReport,
};

/// Default service (namespace) used when callers don't supply one.
///
/// `"car"` is the per-app namespace shared by every CAR component
/// (`car-cli`, `car-inference` model-key fallback, FFI bindings, WebSocket
/// `secret.*` methods). One shared bucket means `car secrets put OPENAI_API_KEY`
/// stores the same entry that `car-inference` reads at runtime — no namespace
/// translation in users' heads.
///
/// Pre-v0.5.2 this was `"car-runtime"`. The rename was a one-time UX change;
/// any keychain entries written before that date live under the old service
/// name and need to be migrated (or just `car secrets put` again).
pub const DEFAULT_SERVICE: &str = "car";

/// Daemon-owned connection credentials and proof metadata. The raw
/// [`SecretStore`] remains able to lease/delete these entries internally;
/// generic CLI/FFI/RPC wrappers must reject access to the root slots and any
/// platform-derived chunk entries.
pub const OPENROUTER_OAUTH_KEY: &str = "OPENROUTER_OAUTH_API_KEY";
pub const PARSLEE_ACCESS_TOKEN_KEY: &str = "PARSLEE_ACCESS_TOKEN";
pub const PARSLEE_REFRESH_TOKEN_KEY: &str = "PARSLEE_REFRESH_TOKEN";
pub const PARSLEE_EXPIRES_AT_KEY: &str = "PARSLEE_ACCESS_TOKEN_EXPIRES_AT";
pub const PARSLEE_API_BASE_KEY: &str = "PARSLEE_API_BASE";
pub const PARSLEE_ACCOUNTS_KEY: &str = "PARSLEE_ACCOUNTS";
pub const PARSLEE_TOKENS_PREFIX: &str = "PARSLEE_TOKENS_";
pub const PARSLEE_AUTH_GENERATION_KEY: &str = "PARSLEE_AUTH_GENERATION";
pub const PARSLEE_AUTH_COMPLETION_KEY: &str = "PARSLEE_AUTH_COMPLETION";
pub const PARSLEE_ACTIVE_ACCOUNT_ID_KEY: &str = "PARSLEE_ACTIVE_ACCOUNT_ID";
pub const PARSLEE_AUTH_STATE_V2_KEY: &str = "PARSLEE_AUTH_STATE_V2";

fn is_private_chunk_derivative(key: &str, root: &str) -> bool {
    key.strip_prefix(root)
        .is_some_and(|suffix| suffix.starts_with("#chunk"))
}

pub fn is_daemon_private_secret(service: &str, key: &str) -> bool {
    service == DEFAULT_SERVICE
        && (matches!(
            key,
            OPENROUTER_OAUTH_KEY
                | PARSLEE_ACCESS_TOKEN_KEY
                | PARSLEE_REFRESH_TOKEN_KEY
                | PARSLEE_EXPIRES_AT_KEY
                | PARSLEE_API_BASE_KEY
                | PARSLEE_ACCOUNTS_KEY
                | PARSLEE_AUTH_GENERATION_KEY
                | PARSLEE_AUTH_COMPLETION_KEY
                | PARSLEE_ACTIVE_ACCOUNT_ID_KEY
                | PARSLEE_AUTH_STATE_V2_KEY
        ) || key.starts_with(PARSLEE_TOKENS_PREFIX)
            || [
                OPENROUTER_OAUTH_KEY,
                PARSLEE_ACCESS_TOKEN_KEY,
                PARSLEE_REFRESH_TOKEN_KEY,
                PARSLEE_EXPIRES_AT_KEY,
                PARSLEE_API_BASE_KEY,
                PARSLEE_ACCOUNTS_KEY,
                PARSLEE_AUTH_GENERATION_KEY,
                PARSLEE_AUTH_COMPLETION_KEY,
                PARSLEE_ACTIVE_ACCOUNT_ID_KEY,
                PARSLEE_AUTH_STATE_V2_KEY,
            ]
            .iter()
            .any(|root| is_private_chunk_derivative(key, root)))
}

/// Resolve a raw key value for `env_var` from the standard CAR
/// sources, in priority order:
///
/// 1. **Process env var** — `std::env::var(env_var)`. Wins
///    everything (containers, CI, K8s pods, systemd units).
///    `~/.car/env` is loaded into the process env at server
///    startup, so file-based config flows through this path too.
/// 2. **OS keychain via [`SecretStore`]** — looked up under
///    [`DEFAULT_SERVICE`] = `"car"` with account = `env_var`.
///    Skipped silently when [`SecretStore::is_available`] is
///    false so we never wake pinentry on a locked desktop or
///    dial DBus on a headless Linux box.
/// 3. **Missing** — returns `None`.
///
/// This is the single source of truth for CAR's API-key
/// resolution. Every call site that wants "env first, then
/// keychain" should go through here so the priority can't drift
/// (`car-inference::key_pool`, `car-voice::elevenlabs_*`, and
/// any future remote backend land here, not on their own
/// re-implementation).
pub fn resolve_env_or_keychain(env_var: &str) -> Option<String> {
    if let Ok(v) = std::env::var(env_var) {
        if !v.is_empty() {
            return Some(v);
        }
    }
    let store = SecretStore::new();
    if !store.is_available() {
        return None;
    }
    let secret_ref = SecretRef::new(DEFAULT_SERVICE, env_var);
    match store.get(&secret_ref) {
        Ok(v) if !v.is_empty() => {
            tracing::debug!(env_var = %env_var, "resolved API key from OS keychain");
            Some(v)
        }
        Ok(_) => None, // empty value — treat as missing
        Err(SecretError::NotFound { .. }) => None,
        Err(e) => {
            tracing::warn!(env_var = %env_var, error = %e, "keychain lookup failed");
            None
        }
    }
}

/// Errors the secret store can produce.
#[derive(Debug, Error)]
pub enum SecretError {
    /// No OS backend is available (e.g. headless Linux with no Secret
    /// Service daemon, or a keychain that refused to unlock).
    #[error("secret store unavailable: {0}")]
    Unavailable(String),

    /// The requested entry does not exist.
    #[error("no entry for service={service:?} key={key:?}")]
    NotFound { service: String, key: String },

    /// The OS credential store refused access to an existing item.
    #[error("secret store access denied: {message}")]
    AccessDenied { message: String },

    /// The user dismissed the OS credential prompt without granting access.
    #[error("secret store access cancelled: {message}")]
    UserCancelled { message: String },

    /// The bounded OS credential helper did not complete before its deadline.
    #[error("secret store helper timed out during {operation}")]
    HelperTimedOut { operation: String },

    /// An OS-native error the store couldn't classify — usually surfaced
    /// verbatim from the underlying keychain API.
    #[error("secret store error: {0}")]
    Backend(String),

    /// A JSON helper was used but the stored value wasn't valid JSON.
    #[error("stored value is not valid JSON: {0}")]
    InvalidJson(String),
}

/// Status of an entry — no value data, safe to log.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SecretStatus {
    pub service: String,
    pub key: String,
    pub exists: bool,
}

/// Result of `SecretStore::availability` — `available` mirrors what
/// `is_available` returns, and `reason` carries the platform-specific
/// detail (e.g. "no Secret Service daemon", "keychain locked") so the
/// FFI surface can report an actionable message instead of a bare
/// boolean.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AvailabilityCheck {
    pub available: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
}

/// Process-lifetime counts of secret-store operation attempts.
///
/// This is deliberately aggregate-only: it contains no service, key,
/// credential identity, filesystem path, or secret value.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct SecretStoreActivity {
    pub get_attempts: u64,
    pub status_attempts: u64,
    pub availability_attempts: u64,
    pub write_attempts: u64,
    pub delete_attempts: u64,
}

static GET_ATTEMPTS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
static STATUS_ATTEMPTS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
static AVAILABILITY_ATTEMPTS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
static WRITE_ATTEMPTS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
static DELETE_ATTEMPTS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);

/// Snapshot the process-lifetime aggregate secret-store counters.
pub fn secret_store_activity() -> SecretStoreActivity {
    use std::sync::atomic::Ordering;

    SecretStoreActivity {
        get_attempts: GET_ATTEMPTS.load(Ordering::Relaxed),
        status_attempts: STATUS_ATTEMPTS.load(Ordering::Relaxed),
        availability_attempts: AVAILABILITY_ATTEMPTS.load(Ordering::Relaxed),
        write_attempts: WRITE_ATTEMPTS.load(Ordering::Relaxed),
        delete_attempts: DELETE_ATTEMPTS.load(Ordering::Relaxed),
    }
}

/// Logical handle for a secret — (service, key) pair.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct SecretRef {
    pub service: String,
    pub key: String,
}

impl SecretRef {
    pub fn new(service: impl Into<String>, key: impl Into<String>) -> Self {
        Self {
            service: service.into(),
            key: key.into(),
        }
    }

    pub fn with_default_service(key: impl Into<String>) -> Self {
        Self {
            service: DEFAULT_SERVICE.to_string(),
            key: key.into(),
        }
    }
}

/// Cross-platform secret store backed by the host OS keychain.
///
/// Stateless by design — it holds no cached secrets. Every call round-trips
/// to the OS. That makes concurrent usage safe and avoids any in-process
/// leak surface beyond the immediate call's return value.
#[derive(Debug, Default, Clone, Copy)]
pub struct SecretStore;

impl SecretStore {
    pub fn new() -> Self {
        Self
    }

    /// Store a UTF-8 secret under `(service, key)`. Replaces any existing
    /// value at the same ref.
    ///
    /// On macOS, writes via `/usr/bin/security add-generic-password -U -A`
    /// so the resulting item has a permissive ACL — readable by any
    /// binary the user runs. This is necessary because the legacy
    /// keychain's default ACL binds an item to the calling binary's
    /// code-signing hash, which changes on every cargo rebuild and
    /// silently revokes read access from later versions of the same
    /// CLI tool. (`/usr/bin/security` is Apple-signed with full
    /// keychain entitlements — the same path reads, status checks,
    /// and deletes use, and the same path users invoke manually.)
    ///
    /// Trade-off: the value transits argv during the spawn (visible to
    /// `ps` from the same user for ~milliseconds). Acceptable for the
    /// "single-user developer machine" threat model; any process that
    /// can see argv on this machine can also read the keychain
    /// directly via `security`. On other platforms, behavior is
    /// unchanged (keyring crate's native backend).
    pub fn put(&self, r: &SecretRef, value: &str) -> Result<(), SecretError> {
        WRITE_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        platform_put(self, r, value)
    }

    /// Publish one authoritative value without exposing a partially-published
    /// replacement to readers.
    ///
    /// This is deliberately separate from [`Self::put`]. Parslee auth stores
    /// its entire active credential transaction in one JSON record and uses
    /// this method as the commit point. macOS updates the existing Keychain item
    /// in place (no pre-delete gap), the debug file backend renames an
    /// owner-private staging file, and Windows stages a revision-tagged
    /// inactive chunk generation before committing the root sentinel last.
    /// Windows retains the prior generation for concurrent readers and uses
    /// deterministic A/B slots plus high-water manifests so crashes cannot
    /// grow Credential Manager entry cardinality without bound.
    ///
    /// Multiple publishers for the same ref must be serialized by the caller.
    /// Parslee auth does this with its coordinator lock; readers may run
    /// concurrently with a publisher.
    pub fn publish(&self, r: &SecretRef, value: &str) -> Result<(), SecretError> {
        WRITE_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        platform_publish(self, r, value)
    }

    /// Store a structured value serialized as JSON.
    pub fn put_json<T: Serialize>(&self, r: &SecretRef, value: &T) -> Result<(), SecretError> {
        let s = serde_json::to_string(value)
            .map_err(|e| SecretError::Backend(format!("serialize: {}", e)))?;
        self.put(r, &s)
    }

    /// Read a UTF-8 secret. Returns `NotFound` if no entry exists.
    ///
    /// On macOS, reads through `/usr/bin/security` first so repeated
    /// helper rebuilds do not churn Keychain prompts against each
    /// binary's CDHash. Backend/authorization failures are returned
    /// directly instead of falling back to an in-process read path that
    /// can trigger a second prompt.
    pub fn get(&self, r: &SecretRef) -> Result<String, SecretError> {
        GET_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        platform_get(self, r)
    }

    /// Read a structured value previously stored via `put_json`.
    pub fn get_json<T: for<'de> Deserialize<'de>>(&self, r: &SecretRef) -> Result<T, SecretError> {
        let raw = self.get(r)?;
        serde_json::from_str(&raw).map_err(|e| SecretError::InvalidJson(e.to_string()))
    }

    /// Delete an entry. Returns Ok even if the entry didn't exist — idempotent
    /// from the caller's perspective.
    ///
    /// On macOS, deletes through `/usr/bin/security` first so the
    /// Apple-signed helper, not the rebuilt caller binary, owns
    /// Keychain authorization.
    pub fn delete(&self, r: &SecretRef) -> Result<(), SecretError> {
        DELETE_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        platform_delete(self, r)
    }

    /// Existence check without returning the value. Safe to log.
    ///
    /// On macOS, checks status through `/usr/bin/security` first for
    /// the same CDHash-stable authorization behavior as `get`.
    pub fn status(&self, r: &SecretRef) -> Result<SecretStatus, SecretError> {
        STATUS_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        platform_status(self, r)
    }

    /// Reserved internal service name used for availability probing.
    /// Consumers must not write user secrets under this service. Kept
    /// in sync with `DEFAULT_SERVICE` ("car") so all CAR-owned
    /// keychain entries share the `car-` prefix and a future cleanup
    /// pass can sweep them with one wildcard.
    const PROBE_SERVICE: &'static str = "car-internal";
    const PROBE_KEY: &'static str = "__availability_probe__";

    /// Probe whether the OS secret store is reachable.
    ///
    /// Opens an Entry for an internal-only sentinel and attempts to read
    /// it. Returns `true` iff the backend responds with either a value or
    /// `NoEntry` — both mean the store is reachable; `PlatformFailure` /
    /// `NoStorageAccess` mean it isn't.
    ///
    /// # Side effects
    ///
    /// - On macOS the probe is an existence-only `/usr/bin/security`
    ///   call — no `-g`, so it reads no password bytes and cannot raise
    ///   an authorization dialog — and it inherits that helper's
    ///   deadline. A locked keychain can still make it wait, but it is
    ///   bounded and it names itself in the log while it waits.
    /// - On Linux it opens a DBus connection to Secret Service.
    /// - Performance: one round-trip to the OS store. Not cached.
    pub fn is_available(&self) -> bool {
        self.availability().available
    }

    /// Detailed availability probe. Same round-trip as `is_available`,
    /// but distinguishes "no backend at all" from a specific platform
    /// failure so the FFI surface can emit a `reason` matching the
    /// pattern used by the other v0.4 capability probes
    /// (`accountsList`, `calendarList`, etc.).
    pub fn availability(&self) -> AvailabilityCheck {
        AVAILABILITY_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        // Reason is only populated when `available == false`. Reachable
        // backends never carry a reason — callers can rely on
        // `available && reason.is_none()` for happy-path branching.
        // The opt-in file backend (test/headless redirect) is always
        // "available" — it is just the local filesystem.
        if file_backend_dir().is_some() {
            return AvailabilityCheck {
                available: true,
                reason: None,
            };
        }
        platform_availability(self)
    }

    /// Not compiled on macOS — and that gate is the regression barrier here,
    /// not a test. Every macOS operation goes through `/usr/bin/security`, so
    /// re-routing one of them back through the in-process keyring path would
    /// reach for `self.entry` and fail to compile. Worth stating because a
    /// test cannot cover it: the tests below inject a fake `SecurityCli`, so
    /// they exercise the helper and say nothing about which body
    /// `platform_availability` dispatches to.
    ///
    /// The gate is soft in exactly one way — a fully-qualified
    /// `keyring::Entry::new(...)` still compiles on macOS, because `keyring`
    /// is an unconditional dependency. That is a deliberate re-introduction,
    /// not a regression something could slip into.
    #[cfg(not(target_os = "macos"))]
    fn entry(&self, r: &SecretRef) -> Result<Entry, SecretError> {
        Entry::new(&r.service, &r.key).map_err(|e| classify(e, "entry"))
    }
}

// ---------------------------------------------------------------------------
// Platform-dispatched keychain operations.
//
// macOS: shell out to `/usr/bin/security` for reads, writes, status checks,
// deletes, and the availability probe. The Apple-signed helper keeps Keychain
// authorization stable across rebuilt CAR helper binaries whose CDHash
// changes. Writes also use `-A` so the item itself is not bound to one
// transient debug binary.
//
// Other platforms: pass through to keyring (its native backends behave
// correctly).
// ---------------------------------------------------------------------------

/// Test/headless redirect: when `CAR_SECRETS_FILE_DIR` names a directory, the
/// store is backed by plaintext files there instead of the OS keychain. This is
/// the SAME env-keyed-redirect idiom as `resolve_env_or_keychain`'s
/// process-env precedence — a no-op in production (the daemon never sets this
/// var), but it lets tests drive the real `put`/`get`/`delete` code path WITHOUT
/// the macOS keychain's interactive-authorization prompt (which cancels
/// unattended, `code=154`). Each secret lands at `<dir>/<service>.<key>`.
///
/// SECURITY: plaintext on disk — acceptable ONLY because this is opt-in via an
/// env var production never sets. The keychain remains the sole production
/// backing store.
///
/// Two hard guards make a production leak structurally impossible:
///
/// 1. **Release builds refuse it entirely.** The redirect is honored ONLY under
///    `cfg!(debug_assertions)` (debug/test builds). A RELEASE binary — which is
///    what production ships — returns `None` even when the env var is set, so a
///    stray `CAR_SECRETS_FILE_DIR` can never route real secrets to plaintext in
///    prod.
/// 2. **First engagement warns loudly.** The first time the redirect is honored
///    in a process, a one-time `tracing::warn!` fires so a misconfigured dev /
///    CI run is visible, not silent.
fn file_backend_dir() -> Option<std::path::PathBuf> {
    // Release builds (production) NEVER honor the redirect — secrets always go
    // to the OS keychain. The env var is a debug/test-only seam.
    if !cfg!(debug_assertions) {
        return None;
    }
    match std::env::var_os("CAR_SECRETS_FILE_DIR") {
        Some(d) if !d.is_empty() => {
            // One-time loud warning the first time the plaintext file backend
            // engages in this process.
            static WARNED: std::sync::Once = std::sync::Once::new();
            WARNED.call_once(|| {
                tracing::warn!(
                    "CAR_SECRETS_FILE_DIR set — secrets are PLAINTEXT ON DISK; \
                     test-only, never production"
                );
            });
            Some(std::path::PathBuf::from(d))
        }
        _ => None,
    }
}

fn file_backend_path(dir: &std::path::Path, r: &SecretRef) -> std::path::PathBuf {
    // Sanitize path separators so a service/key never escapes the dir.
    let sanitize = |s: &str| s.replace(['/', '\\', '.'], "_");
    dir.join(format!("{}.{}", sanitize(&r.service), sanitize(&r.key)))
}

fn file_backend_put(dir: &std::path::Path, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    std::fs::create_dir_all(dir)
        .map_err(|e| SecretError::Backend(format!("file backend mkdir: {e}")))?;
    std::fs::write(file_backend_path(dir, r), value)
        .map_err(|e| SecretError::Backend(format!("file backend write: {e}")))
}

fn file_backend_publish(
    dir: &std::path::Path,
    r: &SecretRef,
    value: &str,
) -> Result<(), SecretError> {
    use std::io::Write;

    std::fs::create_dir_all(dir)
        .map_err(|e| SecretError::Backend(format!("file backend mkdir: {e}")))?;
    let destination = file_backend_path(dir, r);
    let nonce = publication_nonce();
    let staging = destination.with_extension(format!("stage-{nonce}"));
    let mut options = std::fs::OpenOptions::new();
    options.create_new(true).write(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        options.mode(0o600);
    }
    let mut file = options
        .open(&staging)
        .map_err(|e| SecretError::Backend(format!("file backend stage: {e}")))?;
    file.write_all(value.as_bytes())
        .and_then(|_| file.sync_all())
        .map_err(|e| SecretError::Backend(format!("file backend stage write: {e}")))?;
    drop(file);
    if let Err(error) = std::fs::rename(&staging, &destination) {
        let _ = std::fs::remove_file(&staging);
        return Err(SecretError::Backend(format!(
            "file backend publish rename: {error}"
        )));
    }
    Ok(())
}

/// Whether a `NotFound` from an operation under `dir` means "this entry is
/// absent" rather than "this store is unusable".
///
/// The two are the same errno on one platform and not on the other. With a
/// REGULAR FILE configured where the secrets directory should be, opening an
/// entry under it fails with `ENOTDIR` on unix — which is not `NotFound`, so it
/// surfaced as a backend error — but with `ERROR_PATH_NOT_FOUND` on Windows,
/// which Rust maps straight to `io::ErrorKind::NotFound`. The store then
/// answered "that secret does not exist" for a store it could not read at all.
///
/// The consequence was not cosmetic. `car_auth`'s credential resolution treats
/// `NotFound` as "no V2 record yet" and runs a legacy-migration sweep — five
/// further reads of the same broken store — instead of failing on the first one
/// and entering keychain cooldown (Parslee-ai/car#1014). `delete` reported
/// success on a store it never touched, and `status` reported `exists: false`
/// rather than admitting it could not tell.
///
/// The discriminator is whether the configured path is something OTHER than a
/// directory, and it is the same question on every platform.
///
/// Note the second arm: a directory that does not exist YET is not a broken
/// store. Only `put`/`publish` call `create_dir_all`, so on a first run — before
/// anything has been written — the path is legitimately absent, and a `get`
/// there means "no secret yet", exactly as it always has. Treating that as a
/// backend error would send `car_auth` into keychain cooldown on a fresh
/// install instead of reporting "not signed in".
fn file_backend_entry_is_merely_absent(dir: &std::path::Path) -> bool {
    match std::fs::metadata(dir) {
        Ok(metadata) => metadata.is_dir(),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
            // A genuinely absent directory is a normal first run, but Windows
            // also reports NotFound when an ancestor is a regular file. Walk to
            // the nearest existing ancestor and require it to be a directory;
            // any other metadata error means "could not inspect", not "absent".
            for ancestor in dir.ancestors().skip(1) {
                match std::fs::metadata(ancestor) {
                    Ok(metadata) => return metadata.is_dir(),
                    Err(ancestor_error)
                        if ancestor_error.kind() == std::io::ErrorKind::NotFound => {}
                    Err(_) => return false,
                }
            }
            false
        }
        Err(_) => false,
    }
}

fn file_backend_get(dir: &std::path::Path, r: &SecretRef) -> Result<String, SecretError> {
    match std::fs::read_to_string(file_backend_path(dir, r)) {
        Ok(v) => Ok(v),
        Err(e)
            if e.kind() == std::io::ErrorKind::NotFound
                && file_backend_entry_is_merely_absent(dir) =>
        {
            Err(SecretError::NotFound {
                service: r.service.clone(),
                key: r.key.clone(),
            })
        }
        Err(e) => Err(SecretError::Backend(format!("file backend read: {e}"))),
    }
}

fn file_backend_delete(dir: &std::path::Path, r: &SecretRef) -> Result<(), SecretError> {
    match std::fs::remove_file(file_backend_path(dir, r)) {
        Ok(()) => Ok(()),
        Err(e)
            if e.kind() == std::io::ErrorKind::NotFound
                && file_backend_entry_is_merely_absent(dir) =>
        {
            Ok(())
        }
        Err(e) => Err(SecretError::Backend(format!("file backend delete: {e}"))),
    }
}

fn file_backend_status(dir: &std::path::Path, r: &SecretRef) -> SecretStatus {
    SecretStatus {
        service: r.service.clone(),
        key: r.key.clone(),
        // `SecretStatus` has no error/unknown state. Keep the historical false
        // answer for both an absent entry and an unusable debug store; get/delete
        // carry the richer error distinction above.
        exists: file_backend_path(dir, r).exists(),
    }
}

#[cfg(target_os = "macos")]
fn platform_put(_store: &SecretStore, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_put(&dir, r, value);
    }
    mac_put_via_security_cli(&r.service, &r.key, value)
}

#[cfg(target_os = "macos")]
fn platform_publish(_store: &SecretStore, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_publish(&dir, r, value);
    }
    mac_publish_via_security_cli(&r.service, &r.key, value)
}

// --- Windows Credential Manager large-secret chunking ---------------------
//
// A single Windows credential's blob is capped well below the length of a
// Parslee JWT access token — writing one fails with `set_password ... longer
// than platform limit of 2560 chars`. macOS Keychain and Linux Secret Service
// have no such tight limit, so this never surfaced until CAR was exercised on
// real Windows hardware. The workaround, standard for this platform limit, is
// to split an oversized secret across N chunk entries and leave a sentinel
// under the real key that records the chunk count. Reads reassemble
// transparently, so every reader (car-auth, car-inference via car-auth) is
// unaffected. Backward compatible: a value stored as a single entry (no
// sentinel) is returned verbatim, and only Windows takes this path.

/// Sentinel written under the real key when a secret was chunked. The trailing
/// number is the chunk count. Distinctive enough that no real token/API key
/// collides with it.
#[cfg(any(not(target_os = "macos"), test))]
const CHUNK_SENTINEL: &str = "__car_secrets_chunked_v1__:";
#[cfg(any(target_os = "windows", test))]
const CHUNK_SENTINEL_V2: &str = "__car_secrets_chunked_v2__:";
#[cfg(any(target_os = "windows", test))]
const CHUNK_SENTINEL_V3: &str = "__car_secrets_chunked_v3__:";
#[cfg(any(target_os = "windows", test))]
const CHUNK_VALUE_V3: &str = "__car_secrets_chunk_v3__:";
/// UTF-16 length above which we chunk. Comfortably under the ~2560 platform cap
/// with headroom for the credential's other attributes.
#[cfg(any(not(target_os = "macos"), test))]
const CHUNK_THRESHOLD_UTF16: usize = 2000;
/// Characters per chunk. 1000 chars ≤ 2000 UTF-16 units even for all-BMP text.
#[cfg(any(not(target_os = "macos"), test))]
const CHUNK_CHARS: usize = 1000;
/// Hard ceiling for deterministic Windows chunk slots. Publication cardinality
/// is therefore bounded at two generations of at most this many chunks, even
/// when a process repeatedly crashes before swapping the root credential.
#[cfg(any(target_os = "windows", test))]
const WINDOWS_MAX_CHUNKS: usize = 1024;
#[cfg(any(target_os = "windows", test))]
const WINDOWS_READ_ATTEMPTS: usize = 4;

/// Derived ref for chunk `i` of a chunked secret.
#[cfg(not(target_os = "macos"))]
fn chunk_ref(r: &SecretRef, i: usize) -> SecretRef {
    SecretRef::new(r.service.clone(), format!("{}#chunk{}", r.key, i))
}

#[cfg(target_os = "windows")]
fn chunk_v2_ref(r: &SecretRef, nonce: &str, i: usize) -> SecretRef {
    SecretRef::new(r.service.clone(), format!("{}#chunkv2#{nonce}#{i}", r.key))
}

#[cfg(target_os = "windows")]
fn chunk_v3_ref(r: &SecretRef, generation: ChunkGeneration, i: usize) -> SecretRef {
    SecretRef::new(
        r.service.clone(),
        format!("{}#chunkv3#{}#{i}", r.key, generation.label()),
    )
}

#[cfg(target_os = "windows")]
fn chunk_v3_manifest_ref(r: &SecretRef, generation: ChunkGeneration) -> SecretRef {
    SecretRef::new(
        r.service.clone(),
        format!("{}#chunkv3#{}#manifest", r.key, generation.label()),
    )
}

#[cfg(target_os = "windows")]
fn chunk_v3_retired_v2_ref(r: &SecretRef) -> SecretRef {
    SecretRef::new(r.service.clone(), format!("{}#chunkv3#retired-v2", r.key))
}

/// Split a string into pieces of at most `n` chars, on char boundaries.
#[cfg(any(not(target_os = "macos"), test))]
fn split_on_chars(s: &str, n: usize) -> Vec<String> {
    let mut out = Vec::new();
    let mut cur = String::new();
    let mut count = 0usize;
    for ch in s.chars() {
        cur.push(ch);
        count += 1;
        if count == n {
            out.push(std::mem::take(&mut cur));
            count = 0;
        }
    }
    if !cur.is_empty() {
        out.push(cur);
    }
    out
}

fn publication_nonce() -> String {
    static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
    let sequence = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    let nanos = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|duration| duration.as_nanos())
        .unwrap_or_default();
    format!("{:x}-{:x}-{:x}", std::process::id(), nanos, sequence)
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
#[cfg(any(target_os = "windows", test))]
enum ChunkGeneration {
    A,
    B,
}

#[cfg(any(target_os = "windows", test))]
impl ChunkGeneration {
    fn label(self) -> &'static str {
        match self {
            Self::A => "a",
            Self::B => "b",
        }
    }

    fn inactive(self) -> Self {
        match self {
            Self::A => Self::B,
            Self::B => Self::A,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg(any(target_os = "windows", test))]
struct ChunkPublicationPlan {
    generation: ChunkGeneration,
    revision: String,
    chunks: Vec<String>,
    root: String,
}

#[cfg(any(target_os = "windows", test))]
fn chunk_publication_plan(
    value: &str,
    generation: ChunkGeneration,
    revision: &str,
) -> Result<ChunkPublicationPlan, SecretError> {
    if revision.is_empty() || revision.contains(':') {
        return Err(SecretError::Backend(
            "invalid Windows credential publication revision".to_string(),
        ));
    }
    let mut chunks = split_on_chars(value, CHUNK_CHARS);
    if chunks.is_empty() {
        chunks.push(String::new());
    }
    if chunks.len() > WINDOWS_MAX_CHUNKS {
        return Err(SecretError::Backend(format!(
            "Windows credential publication requires {} chunks; maximum is {WINDOWS_MAX_CHUNKS}",
            chunks.len()
        )));
    }
    Ok(ChunkPublicationPlan {
        generation,
        revision: revision.to_string(),
        root: format!(
            "{CHUNK_SENTINEL_V3}{}:{revision}:{}",
            generation.label(),
            chunks.len()
        ),
        chunks,
    })
}

#[cfg(any(target_os = "windows", test))]
fn encode_v3_chunk(revision: &str, value: &str) -> String {
    format!("{CHUNK_VALUE_V3}{revision}:{value}")
}

#[cfg(any(target_os = "windows", test))]
fn decode_v3_chunk<'a>(raw: &'a str, revision: &str) -> Result<&'a str, SecretError> {
    let payload = raw.strip_prefix(CHUNK_VALUE_V3).ok_or_else(|| {
        SecretError::Backend("invalid Windows v3 credential chunk metadata".to_string())
    })?;
    let (stored_revision, value) = payload.split_once(':').ok_or_else(|| {
        SecretError::Backend("invalid Windows v3 credential chunk metadata".to_string())
    })?;
    if stored_revision != revision {
        return Err(SecretError::Backend(
            "Windows credential chunk revision changed during read".to_string(),
        ));
    }
    Ok(value)
}

#[cfg(any(target_os = "windows", test))]
fn parse_v2_sentinel(raw: &str) -> Option<(&str, usize)> {
    let payload = raw.strip_prefix(CHUNK_SENTINEL_V2)?;
    let (nonce, count) = payload.rsplit_once(':')?;
    let count = count.parse::<usize>().ok()?;
    if nonce.is_empty() || count == 0 || count > WINDOWS_MAX_CHUNKS {
        return None;
    }
    Some((nonce, count))
}

#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg(any(target_os = "windows", test))]
enum WindowsRootLayout {
    Inline,
    LegacyV1 {
        count: usize,
    },
    LegacyV2 {
        nonce: String,
        count: usize,
    },
    V3 {
        generation: ChunkGeneration,
        revision: String,
        count: usize,
    },
}

#[cfg(any(target_os = "windows", test))]
fn windows_root_layout(raw: &str) -> Result<WindowsRootLayout, SecretError> {
    if let Some(payload) = raw.strip_prefix(CHUNK_SENTINEL_V3) {
        let (publication, count) = payload.rsplit_once(':').ok_or_else(|| {
            SecretError::Backend("invalid Windows v3 credential root metadata".to_string())
        })?;
        let (generation, revision) = publication.split_once(':').ok_or_else(|| {
            SecretError::Backend("invalid Windows v3 credential root metadata".to_string())
        })?;
        let generation = match generation {
            "a" => ChunkGeneration::A,
            "b" => ChunkGeneration::B,
            _ => {
                return Err(SecretError::Backend(
                    "invalid Windows v3 credential generation".to_string(),
                ))
            }
        };
        if revision.is_empty() {
            return Err(SecretError::Backend(
                "invalid Windows v3 credential publication revision".to_string(),
            ));
        }
        let count = count
            .parse::<usize>()
            .ok()
            .filter(|count| *count > 0 && *count <= WINDOWS_MAX_CHUNKS);
        return count
            .map(|count| WindowsRootLayout::V3 {
                generation,
                revision: revision.to_string(),
                count,
            })
            .ok_or_else(|| {
                SecretError::Backend("invalid Windows v3 credential chunk count".to_string())
            });
    }

    if raw.starts_with(CHUNK_SENTINEL_V2) {
        return parse_v2_sentinel(raw)
            .map(|(nonce, count)| WindowsRootLayout::LegacyV2 {
                nonce: nonce.to_string(),
                count,
            })
            .ok_or_else(|| {
                SecretError::Backend("invalid Windows v2 credential root metadata".to_string())
            });
    }

    if let Some(count) = raw.strip_prefix(CHUNK_SENTINEL) {
        return count
            .parse::<usize>()
            .ok()
            .filter(|count| *count > 0 && *count <= WINDOWS_MAX_CHUNKS)
            .map(|count| WindowsRootLayout::LegacyV1 { count })
            .ok_or_else(|| {
                SecretError::Backend("invalid Windows v1 credential chunk count".to_string())
            });
    }

    Ok(WindowsRootLayout::Inline)
}

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
#[cfg(any(target_os = "windows", test))]
enum WindowsCredentialSlot {
    Root,
    LegacyV1Chunk(usize),
    LegacyV2Chunk {
        nonce: String,
        index: usize,
    },
    V3Chunk {
        generation: ChunkGeneration,
        index: usize,
    },
    V3Manifest(ChunkGeneration),
    RetiredV2Manifest,
}

#[cfg(any(target_os = "windows", test))]
trait WindowsCredentialBackend {
    fn read(&mut self, slot: &WindowsCredentialSlot) -> Result<Option<String>, SecretError>;
    fn write(&mut self, slot: &WindowsCredentialSlot, value: &str) -> Result<(), SecretError>;
    fn delete(&mut self, slot: &WindowsCredentialSlot) -> Result<(), SecretError>;
}

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
#[cfg(any(target_os = "windows", test))]
struct WindowsCleanupReport {
    failures: usize,
}

#[cfg(any(target_os = "windows", test))]
fn cleanup_windows_slot(
    backend: &mut impl WindowsCredentialBackend,
    slot: WindowsCredentialSlot,
    report: &mut WindowsCleanupReport,
) {
    if backend.delete(&slot).is_err() {
        report.failures += 1;
    }
}

#[cfg(any(target_os = "windows", test))]
fn read_generation_manifest(
    backend: &mut impl WindowsCredentialBackend,
    generation: ChunkGeneration,
) -> Result<usize, SecretError> {
    let Some(raw) = backend.read(&WindowsCredentialSlot::V3Manifest(generation))? else {
        return Ok(0);
    };
    raw.parse::<usize>()
        .ok()
        .filter(|count| *count <= WINDOWS_MAX_CHUNKS)
        .ok_or_else(|| {
            SecretError::Backend("invalid Windows credential generation manifest".to_string())
        })
}

#[cfg(any(target_os = "windows", test))]
fn read_retired_v2_manifest(
    backend: &mut impl WindowsCredentialBackend,
) -> Result<Option<(String, usize)>, SecretError> {
    let Some(raw) = backend.read(&WindowsCredentialSlot::RetiredV2Manifest)? else {
        return Ok(None);
    };
    match windows_root_layout(&raw)? {
        WindowsRootLayout::LegacyV2 { nonce, count } => Ok(Some((nonce, count))),
        _ => Err(SecretError::Backend(
            "invalid retired Windows v2 credential manifest".to_string(),
        )),
    }
}

#[cfg(any(target_os = "windows", test))]
fn cleanup_retired_v2(
    backend: &mut impl WindowsCredentialBackend,
    nonce: &str,
    count: usize,
    report: &mut WindowsCleanupReport,
) {
    let failures_before = report.failures;
    for index in 0..count {
        cleanup_windows_slot(
            backend,
            WindowsCredentialSlot::LegacyV2Chunk {
                nonce: nonce.to_string(),
                index,
            },
            report,
        );
    }
    // Keep the deterministic manifest when any chunk cleanup failed so the
    // next publication/delete can resume the sweep without guessing a nonce.
    if report.failures == failures_before {
        cleanup_windows_slot(backend, WindowsCredentialSlot::RetiredV2Manifest, report);
    }
}

#[cfg(any(target_os = "windows", test))]
fn publish_windows_value(
    backend: &mut impl WindowsCredentialBackend,
    value: &str,
) -> Result<WindowsCleanupReport, SecretError> {
    let previous_root = backend.read(&WindowsCredentialSlot::Root)?;
    let previous_layout = previous_root
        .as_deref()
        .map(windows_root_layout)
        .transpose()?;
    let retired_v2_before = read_retired_v2_manifest(backend)?;
    let newly_retired_v2 = match previous_layout.as_ref() {
        Some(WindowsRootLayout::LegacyV2 { nonce, count }) => {
            let root = previous_root
                .as_deref()
                .expect("a parsed legacy root came from a present credential");
            backend.write(&WindowsCredentialSlot::RetiredV2Manifest, root)?;
            Some((nonce.clone(), *count))
        }
        _ => None,
    };
    let generation = match previous_layout {
        Some(WindowsRootLayout::V3 { generation, .. }) => generation.inactive(),
        _ => ChunkGeneration::A,
    };
    let plan = chunk_publication_plan(value, generation, &publication_nonce())?;

    // This non-secret high-water mark is persisted before any chunk mutation.
    // If the process dies while staging, the next writer knows exactly how far
    // it must sweep. Repeated crashes overwrite the same bounded slot set.
    let previous_bound = read_generation_manifest(backend, generation)?;
    let high_water = previous_bound.max(plan.chunks.len());
    backend.write(
        &WindowsCredentialSlot::V3Manifest(generation),
        &high_water.to_string(),
    )?;

    let mut staged = 0;
    for (index, chunk) in plan.chunks.iter().enumerate() {
        let slot = WindowsCredentialSlot::V3Chunk { generation, index };
        if let Err(error) = backend.write(&slot, &encode_v3_chunk(&plan.revision, chunk)) {
            let mut ignored_cleanup = WindowsCleanupReport::default();
            for staged_index in 0..staged {
                cleanup_windows_slot(
                    backend,
                    WindowsCredentialSlot::V3Chunk {
                        generation,
                        index: staged_index,
                    },
                    &mut ignored_cleanup,
                );
            }
            return Err(error);
        }
        staged += 1;
    }

    // The root write is the sole commit point. The previous active generation
    // is deliberately retained so a reader that captured its root can finish.
    if let Err(error) = backend.write(&WindowsCredentialSlot::Root, &plan.root) {
        let mut ignored_cleanup = WindowsCleanupReport::default();
        for staged_index in 0..staged {
            cleanup_windows_slot(
                backend,
                WindowsCredentialSlot::V3Chunk {
                    generation,
                    index: staged_index,
                },
                &mut ignored_cleanup,
            );
        }
        return Err(error);
    }

    let mut cleanup = WindowsCleanupReport::default();
    let tail_failures_before = cleanup.failures;
    for index in plan.chunks.len()..high_water {
        cleanup_windows_slot(
            backend,
            WindowsCredentialSlot::V3Chunk { generation, index },
            &mut cleanup,
        );
    }
    if cleanup.failures == tail_failures_before
        && backend
            .write(
                &WindowsCredentialSlot::V3Manifest(generation),
                &plan.chunks.len().to_string(),
            )
            .is_err()
    {
        cleanup.failures += 1;
    }

    // A v2 generation retired by this commit survives at least one full v3
    // publication. That lets a reader which captured the old nonce finish.
    // A later commit reclaims it through the deterministic manifest; failures
    // leave the manifest in place for the next recovery sweep.
    if let Some((nonce, count)) = retired_v2_before {
        if newly_retired_v2.as_ref() != Some(&(nonce.clone(), count)) {
            cleanup_retired_v2(backend, &nonce, count, &mut cleanup);
        }
    }

    Ok(cleanup)
}

/// Best-effort delete of any chunk entries `#chunk0..` for `r`, stopping at the
/// first that doesn't exist. Used before a rewrite and on delete so stale
/// chunks from a previous large value never linger.
#[cfg(not(target_os = "macos"))]
fn clear_chunks(store: &SecretStore, r: &SecretRef) {
    for i in 0..1024 {
        let cr = chunk_ref(r, i);
        let Ok(entry) = store.entry(&cr) else { break };
        match entry.delete_credential() {
            Ok(_) => {}
            Err(keyring::Error::NoEntry) => break,
            Err(_) => break,
        }
    }
}

#[cfg(any(target_os = "windows", test))]
fn read_windows_value(
    backend: &mut impl WindowsCredentialBackend,
) -> Result<Option<String>, SecretError> {
    for attempt in 0..WINDOWS_READ_ATTEMPTS {
        let Some(root) = backend.read(&WindowsCredentialSlot::Root)? else {
            return Ok(None);
        };
        let (slots, expected_revision) = match windows_root_layout(&root)? {
            WindowsRootLayout::Inline => return Ok(Some(root)),
            WindowsRootLayout::LegacyV1 { count } => (
                (0..count)
                    .map(WindowsCredentialSlot::LegacyV1Chunk)
                    .collect::<Vec<_>>(),
                None,
            ),
            WindowsRootLayout::LegacyV2 { nonce, count } => (
                (0..count)
                    .map(|index| WindowsCredentialSlot::LegacyV2Chunk {
                        nonce: nonce.clone(),
                        index,
                    })
                    .collect::<Vec<_>>(),
                None,
            ),
            WindowsRootLayout::V3 {
                generation,
                revision,
                count,
            } => (
                (0..count)
                    .map(|index| WindowsCredentialSlot::V3Chunk { generation, index })
                    .collect::<Vec<_>>(),
                Some(revision),
            ),
        };

        let mut value = String::new();
        let mut chunk_error = None;
        for slot in slots {
            match backend.read(&slot) {
                Ok(Some(chunk)) => {
                    if let Some(revision) = expected_revision.as_deref() {
                        match decode_v3_chunk(&chunk, revision) {
                            Ok(chunk) => value.push_str(chunk),
                            Err(error) => {
                                chunk_error = Some(error);
                                break;
                            }
                        }
                    } else {
                        value.push_str(&chunk);
                    }
                }
                Ok(None) => {
                    chunk_error = Some(SecretError::Backend(
                        "Windows credential publication is incomplete".to_string(),
                    ));
                    break;
                }
                Err(error) => {
                    chunk_error = Some(error);
                    break;
                }
            }
        }

        let root_after = backend.read(&WindowsCredentialSlot::Root);
        if matches!(&root_after, Ok(Some(current)) if current != &root) {
            if chunk_error.is_none() {
                // Every chunk carried the captured revision (or was a retained
                // legacy generation), so this complete old value is safe.
                return Ok(Some(value));
            }
            if attempt + 1 < WINDOWS_READ_ATTEMPTS {
                continue;
            }
            return Err(SecretError::Backend(
                "Windows credential root changed during every read attempt".to_string(),
            ));
        }
        if let Some(error) = chunk_error {
            return Err(error);
        }
        match root_after {
            Ok(Some(current)) if current == root => return Ok(Some(value)),
            Ok(_) if attempt + 1 < WINDOWS_READ_ATTEMPTS => continue,
            Ok(_) => {
                return Err(SecretError::Backend(
                    "Windows credential root changed during every read attempt".to_string(),
                ))
            }
            Err(error) => return Err(error),
        }
    }
    Err(SecretError::Backend(
        "Windows credential read retry limit reached".to_string(),
    ))
}

#[cfg(any(target_os = "windows", test))]
fn delete_windows_value(
    backend: &mut impl WindowsCredentialBackend,
) -> Result<WindowsCleanupReport, SecretError> {
    let root = backend.read(&WindowsCredentialSlot::Root)?;
    let layout = root.as_deref().map(windows_root_layout).transpose()?;
    let retired_v2 = read_retired_v2_manifest(backend)?;

    // Resolve every cleanup bound before deleting the root. A metadata/backend
    // error therefore leaves the only authoritative generation untouched.
    let mut generation_bounds = [
        (
            ChunkGeneration::A,
            read_generation_manifest(backend, ChunkGeneration::A)?,
        ),
        (
            ChunkGeneration::B,
            read_generation_manifest(backend, ChunkGeneration::B)?,
        ),
    ];
    if let Some(WindowsRootLayout::V3 {
        generation, count, ..
    }) = layout.as_ref()
    {
        let (_, bound) = generation_bounds
            .iter_mut()
            .find(|(candidate, _)| candidate == generation)
            .expect("both deterministic generations are present");
        *bound = (*bound).max(*count);
    }

    backend.delete(&WindowsCredentialSlot::Root)?;

    let mut cleanup = WindowsCleanupReport::default();
    for (generation, bound) in generation_bounds {
        let failures_before = cleanup.failures;
        for index in 0..bound {
            cleanup_windows_slot(
                backend,
                WindowsCredentialSlot::V3Chunk { generation, index },
                &mut cleanup,
            );
        }
        if cleanup.failures == failures_before {
            cleanup_windows_slot(
                backend,
                WindowsCredentialSlot::V3Manifest(generation),
                &mut cleanup,
            );
        }
    }
    match layout {
        Some(WindowsRootLayout::LegacyV1 { count }) => {
            for index in 0..count {
                cleanup_windows_slot(
                    backend,
                    WindowsCredentialSlot::LegacyV1Chunk(index),
                    &mut cleanup,
                );
            }
        }
        Some(WindowsRootLayout::LegacyV2 { nonce, count }) => {
            for index in 0..count {
                cleanup_windows_slot(
                    backend,
                    WindowsCredentialSlot::LegacyV2Chunk {
                        nonce: nonce.clone(),
                        index,
                    },
                    &mut cleanup,
                );
            }
        }
        _ => {}
    }
    if let Some((nonce, count)) = retired_v2 {
        cleanup_retired_v2(backend, &nonce, count, &mut cleanup);
    }
    Ok(cleanup)
}

#[cfg(not(target_os = "macos"))]
fn platform_put(store: &SecretStore, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_put(&dir, r, value);
    }
    // Windows-only: chunk an oversized secret. Runtime-gated so Linux Secret
    // Service (no size limit) keeps its exact single-entry behavior.
    if cfg!(windows) {
        // Always clear stale chunks first so a shrink (large → small) can't
        // leave orphans behind.
        clear_chunks(store, r);
        if value.encode_utf16().count() > CHUNK_THRESHOLD_UTF16 {
            let parts = split_on_chars(value, CHUNK_CHARS);
            for (i, part) in parts.iter().enumerate() {
                let cr = chunk_ref(r, i);
                store
                    .entry(&cr)?
                    .set_password(part)
                    .map_err(|e| classify(e, "set_password(chunk)"))?;
            }
            // The sentinel goes last so a reader never sees it before its
            // chunks exist.
            let sentinel = format!("{CHUNK_SENTINEL}{}", parts.len());
            return store
                .entry(r)?
                .set_password(&sentinel)
                .map_err(|e| classify(e, "set_password(sentinel)"));
        }
    }
    let entry = store.entry(r)?;
    entry
        .set_password(value)
        .map_err(|e| classify(e, "set_password"))
}

#[cfg(target_os = "windows")]
struct KeyringWindowsBackend<'a> {
    store: &'a SecretStore,
    root: &'a SecretRef,
}

#[cfg(target_os = "windows")]
impl KeyringWindowsBackend<'_> {
    fn secret_ref(&self, slot: &WindowsCredentialSlot) -> SecretRef {
        match slot {
            WindowsCredentialSlot::Root => self.root.clone(),
            WindowsCredentialSlot::LegacyV1Chunk(index) => chunk_ref(self.root, *index),
            WindowsCredentialSlot::LegacyV2Chunk { nonce, index } => {
                chunk_v2_ref(self.root, nonce, *index)
            }
            WindowsCredentialSlot::V3Chunk { generation, index } => {
                chunk_v3_ref(self.root, *generation, *index)
            }
            WindowsCredentialSlot::V3Manifest(generation) => {
                chunk_v3_manifest_ref(self.root, *generation)
            }
            WindowsCredentialSlot::RetiredV2Manifest => chunk_v3_retired_v2_ref(self.root),
        }
    }
}

#[cfg(target_os = "windows")]
impl WindowsCredentialBackend for KeyringWindowsBackend<'_> {
    fn read(&mut self, slot: &WindowsCredentialSlot) -> Result<Option<String>, SecretError> {
        match self.store.entry(&self.secret_ref(slot))?.get_password() {
            Ok(value) => Ok(Some(value)),
            Err(keyring::Error::NoEntry) => Ok(None),
            Err(error) => Err(classify(error, "get_password(windows-publish)")),
        }
    }

    fn write(&mut self, slot: &WindowsCredentialSlot, value: &str) -> Result<(), SecretError> {
        self.store
            .entry(&self.secret_ref(slot))?
            .set_password(value)
            .map_err(|error| classify(error, "set_password(windows-publish)"))
    }

    fn delete(&mut self, slot: &WindowsCredentialSlot) -> Result<(), SecretError> {
        match self
            .store
            .entry(&self.secret_ref(slot))?
            .delete_credential()
        {
            Ok(()) | Err(keyring::Error::NoEntry) => Ok(()),
            Err(error) => Err(classify(error, "delete_credential(windows-publish)")),
        }
    }
}

#[cfg(target_os = "windows")]
fn platform_publish(store: &SecretStore, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_publish(&dir, r, value);
    }
    let mut backend = KeyringWindowsBackend { store, root: r };
    let cleanup = publish_windows_value(&mut backend, value)?;
    if cleanup.failures > 0 {
        tracing::warn!(
            cleanup_failures = cleanup.failures,
            "Windows credential publication committed; bounded cleanup deferred"
        );
    }
    Ok(())
}

#[cfg(all(not(target_os = "macos"), not(target_os = "windows")))]
fn platform_publish(store: &SecretStore, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_publish(&dir, r, value);
    }
    store
        .entry(r)?
        .set_password(value)
        .map_err(|error| classify(error, "publish_password"))
}

#[cfg(target_os = "macos")]
fn platform_get(_store: &SecretStore, r: &SecretRef) -> Result<String, SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_get(&dir, r);
    }
    mac_get_via_security_cli(r)
}

#[cfg(target_os = "windows")]
fn platform_get(store: &SecretStore, r: &SecretRef) -> Result<String, SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_get(&dir, r);
    }
    let mut backend = KeyringWindowsBackend { store, root: r };
    match read_windows_value(&mut backend)? {
        Some(value) => Ok(value),
        None => Err(SecretError::NotFound {
            service: r.service.clone(),
            key: r.key.clone(),
        }),
    }
}

#[cfg(all(not(target_os = "macos"), not(target_os = "windows")))]
fn platform_get(store: &SecretStore, r: &SecretRef) -> Result<String, SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_get(&dir, r);
    }
    match store.entry(r)?.get_password() {
        Ok(value) => Ok(value),
        Err(keyring::Error::NoEntry) => Err(SecretError::NotFound {
            service: r.service.clone(),
            key: r.key.clone(),
        }),
        Err(error) => Err(classify(error, "get_password")),
    }
}

#[cfg(target_os = "macos")]
fn platform_delete(_store: &SecretStore, r: &SecretRef) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_delete(&dir, r);
    }
    mac_delete_via_security_cli(r)
}

#[cfg(target_os = "windows")]
fn platform_delete(store: &SecretStore, r: &SecretRef) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_delete(&dir, r);
    }
    let mut backend = KeyringWindowsBackend { store, root: r };
    let cleanup = delete_windows_value(&mut backend)?;
    if cleanup.failures > 0 {
        tracing::warn!(
            cleanup_failures = cleanup.failures,
            "Windows credential root deleted; bounded cleanup deferred"
        );
    }
    Ok(())
}

#[cfg(all(not(target_os = "macos"), not(target_os = "windows")))]
fn platform_delete(store: &SecretStore, r: &SecretRef) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_delete(&dir, r);
    }
    match store.entry(r)?.delete_credential() {
        Ok(_) | Err(keyring::Error::NoEntry) => Ok(()),
        Err(error) => Err(classify(error, "delete_credential")),
    }
}

#[cfg(target_os = "macos")]
fn platform_status(_store: &SecretStore, r: &SecretRef) -> Result<SecretStatus, SecretError> {
    if let Some(dir) = file_backend_dir() {
        return Ok(file_backend_status(&dir, r));
    }
    mac_status_via_security_cli(r)
}

#[cfg(not(target_os = "macos"))]
fn platform_status(store: &SecretStore, r: &SecretRef) -> Result<SecretStatus, SecretError> {
    if let Some(dir) = file_backend_dir() {
        return Ok(file_backend_status(&dir, r));
    }
    let entry = store.entry(r)?;
    let exists = match entry.get_password() {
        Ok(_) => true,
        Err(keyring::Error::NoEntry) => false,
        Err(other) => return Err(classify(other, "status")),
    };
    Ok(SecretStatus {
        service: r.service.clone(),
        key: r.key.clone(),
        exists,
    })
}

/// Reachability probe on macOS: the same Apple-signed helper every other
/// macOS operation uses.
///
/// This was the one keychain operation still going through the in-process
/// `keyring` crate, and it is the operation that runs *most*:
/// [`resolve_env_or_keychain`] calls [`SecretStore::is_available`] before
/// every single credential resolution, uncached, and a `car-inference`
/// catalog refresh resolves one credential per distinct provider. So the call
/// in front of every credential read was the call with no deadline, no log
/// line naming what it was blocked on, and authorization bound to the CAR
/// binary's own code-signing hash rather than to `/usr/bin/security`
/// (Parslee-ai/car#897).
///
/// Routing it through [`mac_exists_via_security_cli_with`] fixes all three at
/// once, and adds nothing new: that call is existence-only — **no `-g`**, so
/// it reads no password bytes and cannot raise an authorization dialog — and
/// it runs under `bounded_command_output`, so it is capped at the shared
/// deadline and emits [`keychain_prompt_notice`] naming
/// `car-internal/__availability_probe__` if it ever does block.
///
/// One deliberate semantic change against the non-macOS body: there, an
/// unclassified `keyring` error (`BadEncoding` and friends) reports
/// *available* so the caller can still try real ops. Here, a non-zero exit
/// that is not `SECURITY_ERR_SEC_ITEM_NOT_FOUND` reports *unavailable* with
/// the helper's own reason. That is the rule
/// [`mac_exists_via_security_cli_with`] already documents for status checks —
/// those exits are backend/authorization failures, not encoding oddities — so
/// the probe and the status check now agree instead of disagreeing.
#[cfg(target_os = "macos")]
fn platform_availability(_store: &SecretStore) -> AvailabilityCheck {
    mac_availability_via_security_cli_with(&SystemSecurityCli)
}

#[cfg(target_os = "macos")]
fn mac_availability_via_security_cli_with(cli: &impl SecurityCli) -> AvailabilityCheck {
    let probe = SecretRef::new(SecretStore::PROBE_SERVICE, SecretStore::PROBE_KEY);
    match mac_exists_via_security_cli_with(&probe, cli) {
        // Present or absent both mean the store answered, which is the only
        // thing the probe asks. Mirrors the `Ok(_) | Err(NoEntry)` arm below.
        Ok(_) => AvailabilityCheck {
            available: true,
            reason: None,
        },
        Err(error) => AvailabilityCheck {
            available: false,
            reason: Some(error.to_string()),
        },
    }
}

#[cfg(not(target_os = "macos"))]
fn platform_availability(store: &SecretStore) -> AvailabilityCheck {
    let probe = SecretRef::new(SecretStore::PROBE_SERVICE, SecretStore::PROBE_KEY);
    match store.entry(&probe) {
        Ok(entry) => match entry.get_password() {
            Ok(_) | Err(keyring::Error::NoEntry) => AvailabilityCheck {
                available: true,
                reason: None,
            },
            Err(keyring::Error::PlatformFailure(e)) => AvailabilityCheck {
                available: false,
                reason: Some(format!("platform failure: {e}")),
            },
            Err(keyring::Error::NoStorageAccess(e)) => AvailabilityCheck {
                available: false,
                reason: Some(format!("no storage access: {e}")),
            },
            // Other keyring errors (BadEncoding etc.) on the
            // probe key indicate the backend responded but
            // returned something unexpected. Treat as available
            // so the caller can still try real ops; the failure
            // mode shows up at the next put/get with proper
            // typed error.
            Err(_) => AvailabilityCheck {
                available: true,
                reason: None,
            },
        },
        Err(SecretError::Unavailable(reason)) => AvailabilityCheck {
            available: false,
            reason: Some(reason),
        },
        Err(other) => AvailabilityCheck {
            available: false,
            reason: Some(other.to_string()),
        },
    }
}

/// Shell-out write with the `-A` flag (any-app ACL).
///
/// `service`/`account` are passed as separate argv tokens so shell
/// metacharacters in either are inert. The value is the only argv slot
/// that's a secret; document the trade-off at the call site.
///
/// Always issues `delete-generic-password` first (best-effort, errors
/// ignored) so the subsequent `add-generic-password` creates a fresh
/// keychain item with a fresh ACL. Without the pre-delete,
/// `add-generic-password -U` would update the value in place but
/// preserve any existing CDHash-bound ACL from a previous binary —
/// causing the Apple-signed `/usr/bin/security` reader to be prompted
/// for authorization on every subsequent `-g` retrieval. The `-U` flag
/// is retained on `add` as a safety net for the (rare) case where
/// delete returned non-zero non-NotFound and the entry is somehow
/// still present.
#[cfg(target_os = "macos")]
fn mac_put_via_security_cli(service: &str, account: &str, value: &str) -> Result<(), SecretError> {
    mac_put_via_security_cli_with(service, account, value, &SystemSecurityCli)
}

#[cfg(target_os = "macos")]
fn mac_publish_via_security_cli(
    service: &str,
    account: &str,
    value: &str,
) -> Result<(), SecretError> {
    mac_publish_via_security_cli_with(service, account, value, &SystemSecurityCli)
}

#[cfg(target_os = "macos")]
fn mac_publish_via_security_cli_with(
    service: &str,
    account: &str,
    value: &str,
    cli: &impl SecurityCli,
) -> Result<(), SecretError> {
    let output = cli
        .output(&[
            "add-generic-password",
            "-U",
            "-A",
            "-s",
            service,
            "-a",
            account,
            "-w",
            value,
        ])
        .map_err(|e| security_cli_spawn_error("add-generic-password", e))?;
    if output.success {
        Ok(())
    } else {
        Err(security_cli_backend_error("add-generic-password", output))
    }
}

#[cfg(target_os = "macos")]
fn mac_put_via_security_cli_with(
    service: &str,
    account: &str,
    value: &str,
    cli: &impl SecurityCli,
) -> Result<(), SecretError> {
    // Best-effort delete: clears any pre-existing item so the add below
    // installs a brand-new ACL via `-A`. Failures (including NotFound) are
    // ignored — the add path handles the residual-item case via `-U`.
    let _ = cli.output(&["delete-generic-password", "-s", service, "-a", account]);

    let output = cli
        .output(&[
            "add-generic-password",
            "-U", // safety net if the pre-delete didn't actually remove the item
            "-A", // permissive ACL — any app can read
            "-s",
            service,
            "-a",
            account,
            "-w",
            value,
        ])
        .map_err(|e| security_cli_spawn_error("add-generic-password", e))?;
    if output.success {
        return Ok(());
    }
    Err(security_cli_backend_error("add-generic-password", output))
}

#[cfg(target_os = "macos")]
const SECURITY_ERR_SEC_ITEM_NOT_FOUND: i32 = 44;

#[cfg(target_os = "macos")]
#[derive(Debug)]
struct SecurityCliOutput {
    success: bool,
    code: Option<i32>,
    stdout: Vec<u8>,
    stderr: Vec<u8>,
    /// Whether *this* call is the one macOS drew a keychain dialog for.
    ///
    /// The signal already existed inside `bounded_command_output` (it is what
    /// extends the deadline); it just was not surfaced. It is the evidence that
    /// an item's ACL is bound to a binary that no longer matches — which is the
    /// condition `mac_repair_item_acl_with` exists to end.
    ///
    /// Narrower than "a dialog was on screen": see
    /// [`dialog_is_evidence_for_this_read`]. `SecurityAgent` is machine-wide, so
    /// a bare sighting is not attributable to this read, and acting on an
    /// unattributable one rewrites a healthy credential.
    prompted: bool,
    /// Whether CAR killed the helper after its bounded deadline.
    timed_out: bool,
}

#[cfg(target_os = "macos")]
trait SecurityCli {
    fn output(&self, args: &[&str]) -> std::io::Result<SecurityCliOutput>;
}

#[cfg(target_os = "macos")]
struct SystemSecurityCli;

#[cfg(target_os = "macos")]
impl SecurityCli for SystemSecurityCli {
    fn output(&self, args: &[&str]) -> std::io::Result<SecurityCliOutput> {
        let mut command = std::process::Command::new("/usr/bin/security");
        command.args(args);
        if let Some(keychain_path) = selected_keychain_path()? {
            command.arg(keychain_path);
        }
        let run = bounded_command_output(&mut command, SECURITY_CLI_TIMEOUT, &describe_item(args))?;
        Ok(SecurityCliOutput {
            success: run.output.status.success(),
            code: run.output.status.code(),
            stdout: run.output.stdout,
            stderr: run.output.stderr,
            prompted: run.prompted,
            timed_out: run.timed_out,
        })
    }
}

#[cfg(target_os = "macos")]
const KEYCHAIN_PATH_ENV: &str = "CAR_KEYCHAIN_PATH";

#[cfg(target_os = "macos")]
const KEYCHAIN_PROOF_ROOT_ENV: &str = "CAR_KEYCHAIN_PROOF_ROOT";

/// Resolve the optional release-proof Keychain selector. Production behavior
/// is unchanged when `CAR_KEYCHAIN_PATH` is absent.
#[cfg(target_os = "macos")]
fn selected_keychain_path() -> std::io::Result<Option<std::path::PathBuf>> {
    let Some(path) = std::env::var_os(KEYCHAIN_PATH_ENV).filter(|value| !value.is_empty()) else {
        return Ok(None);
    };
    let proof_root = std::env::var_os(KEYCHAIN_PROOF_ROOT_ENV)
        .filter(|value| !value.is_empty())
        .ok_or_else(|| {
            std::io::Error::new(
                std::io::ErrorKind::InvalidInput,
                format!("{KEYCHAIN_PATH_ENV} requires {KEYCHAIN_PROOF_ROOT_ENV}"),
            )
        })?;
    validate_keychain_path(
        std::path::Path::new(&path),
        std::path::Path::new(&proof_root),
    )
    .map(Some)
}

#[cfg(target_os = "macos")]
fn validate_keychain_path(
    path: &std::path::Path,
    proof_root: &std::path::Path,
) -> std::io::Result<std::path::PathBuf> {
    use std::os::unix::fs::{MetadataExt, PermissionsExt};

    if !path.is_absolute() || !proof_root.is_absolute() {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidInput,
            "isolated Keychain path and proof root must be absolute",
        ));
    }

    let expected_uid = current_effective_uid();
    let root_metadata = std::fs::symlink_metadata(proof_root)?;
    if root_metadata.file_type().is_symlink()
        || !root_metadata.is_dir()
        || root_metadata.uid() != expected_uid
        || root_metadata.permissions().mode() & 0o077 != 0
    {
        return Err(std::io::Error::new(
            std::io::ErrorKind::PermissionDenied,
            "Keychain proof root must be an owner-private, non-symlink directory owned by the current user",
        ));
    }

    let path_metadata = std::fs::symlink_metadata(path)?;
    if path_metadata.file_type().is_symlink()
        || !path_metadata.is_file()
        || path_metadata.uid() != expected_uid
        || path_metadata.permissions().mode() & 0o077 != 0
    {
        return Err(std::io::Error::new(
            std::io::ErrorKind::PermissionDenied,
            "isolated Keychain must be an owner-private, non-symlink regular file owned by the current user",
        ));
    }

    let canonical_root = std::fs::canonicalize(proof_root)?;
    let canonical_path = std::fs::canonicalize(path)?;
    if !canonical_path.starts_with(&canonical_root) || canonical_path == canonical_root {
        return Err(std::io::Error::new(
            std::io::ErrorKind::PermissionDenied,
            "isolated Keychain must be canonically contained by its proof root",
        ));
    }
    Ok(canonical_path)
}

#[cfg(target_os = "macos")]
fn current_effective_uid() -> u32 {
    unsafe extern "C" {
        fn geteuid() -> u32;
    }
    // SAFETY: `geteuid` takes no arguments and has no preconditions.
    unsafe { geteuid() }
}

#[cfg(target_os = "macos")]
const SECURITY_CLI_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(15);

/// Deadline used instead of [`SECURITY_CLI_TIMEOUT`] while macOS is showing a
/// keychain dialog. Generous on purpose: it is a bound on *human* response, not
/// on a hung process, and the cost of being too tight is that the credential
/// becomes permanently unreachable (see `bounded_command_output`).
#[cfg(target_os = "macos")]
const SECURITY_CLI_INTERACTIVE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(180);

/// Is macOS currently drawing a keychain prompt?
///
/// `SecurityAgent` is the process that renders the unlock / "allow access"
/// dialogs. Its presence is the difference between "the helper is hung" and
/// "the helper is waiting for the user" — a distinction the bare deadline
/// cannot make, and getting it wrong kills the dialog mid-typing.
///
/// Deliberately fail-CLOSED to the short deadline: if this cannot be
/// determined, treat the helper as non-interactive, so a lookup failure can
/// never extend a genuinely hung child to three minutes.
#[cfg(target_os = "macos")]
fn security_agent_is_prompting() -> bool {
    std::process::Command::new("/usr/bin/pgrep")
        .arg("-x")
        .arg("SecurityAgent")
        .stdout(std::process::Stdio::null())
        .stderr(std::process::Stdio::null())
        .status()
        .map(|s| s.success())
        .unwrap_or(false)
}

/// How long a `security` call must still be running, with a dialog on screen,
/// before that dialog counts as evidence that *this* call is the one being
/// authorized.
///
/// `SecurityAgent` is machine-wide. It is up whenever anything on the Mac is
/// asking for authorization — an installer, a `sudo` GUI prompt, a browser
/// saving a password, or a *different* CAR process blocked on its own keychain
/// dialog. None of those say anything about the item this call is reading.
///
/// The duration is what makes the sighting attributable: a `security
/// find-generic-password -g` that nobody has to authorize returns in tens of
/// milliseconds (the v0.47.0 notes derive ~14ms per credential probe), and this
/// loop has already broken out on `try_wait` long before the
/// threshold. A call that genuinely drew a dialog is still running, because it
/// is blocked until a human answers.
///
/// Duration, rather than "SecurityAgent was absent at spawn and appeared
/// later": during the prompt storm this exists to cure, a dialog is *already*
/// up when the next read spawns, so a transition rule would go blind exactly
/// when it matters most.
///
/// **This is a heuristic with real margins, not a proof.** Half a second is
/// ~35× that derived per-probe cost, but a cold first read on a busy machine can be
/// far slower than that, so a false positive is still reachable — it is rarer,
/// not impossible. In the other direction the margin is thinner: a dialog has
/// to render (~100-200ms) and a human has to react (~250ms), so a very fast
/// repeat-click could finish inside 500ms and go unattributed. The asymmetry
/// says which way to lean, and it is why the threshold sits nearer the human
/// end than the middle: a missed repair costs one more dialog on the next read,
/// which repairs then; a false one rewrites a healthy credential and spends the
/// one repair attempt this process is allowed per item (see
/// `acl_repair_attempted`), so the stale item that prompts later never gets
/// fixed at all.
///
/// Known residual: a **locked** login keychain blocks every read past the
/// threshold, so an unlock dialog is attributed like an authorization one and
/// the repair fires on a healthy item. Unlocking is not an ACL condition and
/// this rule does not distinguish it; the cost is one needless rewrite plus
/// that item's repair attempt.
#[cfg(target_os = "macos")]
const PROMPT_EVIDENCE_MIN: std::time::Duration = std::time::Duration::from_millis(500);

/// Does a dialog seen at `elapsed` into a still-running call belong to *this*
/// call?
///
/// Split out from the poll loop so the rule is testable without a real keychain
/// or a real dialog. See [`PROMPT_EVIDENCE_MIN`] for why both terms are needed.
#[cfg(target_os = "macos")]
fn dialog_is_evidence_for_this_read(dialog_on_screen: bool, elapsed: std::time::Duration) -> bool {
    dialog_on_screen && elapsed >= PROMPT_EVIDENCE_MIN
}

/// A finished helper run, plus whether the dialog macOS drew was this run's.
#[cfg(target_os = "macos")]
#[derive(Debug)]
struct BoundedRun {
    output: std::process::Output,
    prompted: bool,
    timed_out: bool,
}

/// Name the keychain item a `security` invocation is acting on, for the notice
/// below. `service/account` when both are present, else whichever is, else the
/// subcommand.
///
/// **Which item** is the datum that turns a repeat-prompt report into a
/// diagnosis, and it is the one thing the log never carried: the macOS dialog
/// names the item, but reading it requires being at the screen when it appears.
/// The reported scenario is precisely the one where nobody is — an operator
/// stepped away and came back to a stack of ~18 prompts, by which point the
/// only question that matters ("which item keeps asking?") is unanswerable
/// (Parslee-ai/car#897).
///
/// Reads only `-s`/`-a`, which are a service name and an account name. The
/// secret itself arrives on the child's stdout and is never touched here.
#[cfg(target_os = "macos")]
fn describe_item(args: &[&str]) -> String {
    let flag = |name: &str| {
        args.iter()
            .position(|a| *a == name)
            .and_then(|i| args.get(i + 1))
            .copied()
    };
    match (flag("-s"), flag("-a")) {
        (Some(service), Some(account)) => format!("{service}/{account}"),
        (Some(service), None) => service.to_string(),
        (None, Some(account)) => account.to_string(),
        // Not an item-scoped call (`unlock-keychain`, `list-keychains`, …).
        // Naming the subcommand still beats naming nothing.
        (None, None) => args.first().copied().unwrap_or("security").to_string(),
    }
}

/// The line emitted the moment a keychain dialog is attributed to this read.
///
/// Split out so a test can assert the wording without a real dialog, and so the
/// promptly-emitted notice and the on-expiry message stay coherent — they
/// describe the same condition three minutes apart and must not drift into
/// giving different remedies.
#[cfg(target_os = "macos")]
fn keychain_prompt_notice(item: &str) -> String {
    format!(
        "waiting on a macOS keychain prompt for \"{item}\" (up to {}s) — CAR is not \
         hung. Click \"Always Allow\" on the dialog (it may be behind another \
         window), or grant the \"car\" service access in Keychain Access.",
        SECURITY_CLI_INTERACTIVE_TIMEOUT.as_secs()
    )
}

#[cfg(target_os = "macos")]
fn bounded_command_output(
    command: &mut std::process::Command,
    timeout: std::time::Duration,
    item: &str,
) -> std::io::Result<BoundedRun> {
    bounded_command_output_with(command, timeout, security_agent_is_prompting, || {
        // `tracing`, not `eprintln!`, and it reaches both audiences that matter
        // here: `car-cli` installs a stderr `fmt` layer defaulting to `info`
        // (`car_telemetry::init_tracing`), so a person at a terminal sees the
        // line; and a daemon blocked the same way gets it in its log, which is
        // the second half of what Parslee-ai/car#878 asked for — and the only
        // channel that survives an operator who has walked away (#897).
        tracing::warn!("{}", keychain_prompt_notice(item));
    })
}

/// `bounded_command_output` with the dialog probe and the notice sink injected.
///
/// The probe is a parameter so a test can hold "a dialog is on screen" true for
/// the whole run. Without that, every assertion about attribution is decided by
/// whether the machine running the tests happens to have an authorization
/// dialog up — which on CI it never does, so the test would pass whatever the
/// attribution rule said, including no rule at all.
///
/// `on_waiting_for_user` is injected for the same reason one step further on:
/// the property worth testing is that it fires **exactly once** per blocked
/// read, and a counter is the only honest way to assert that.
#[cfg(target_os = "macos")]
fn bounded_command_output_with(
    command: &mut std::process::Command,
    timeout: std::time::Duration,
    dialog_probe: impl Fn() -> bool,
    on_waiting_for_user: impl Fn(),
) -> std::io::Result<BoundedRun> {
    use std::io::Read;
    use std::process::Stdio;
    use std::time::Instant;

    command.stdout(Stdio::piped()).stderr(Stdio::piped());
    let mut child = command.spawn()?;
    let stdout = child
        .stdout
        .take()
        .ok_or_else(|| std::io::Error::other("keychain helper stdout was not piped"))?;
    let stderr = child
        .stderr
        .take()
        .ok_or_else(|| std::io::Error::other("keychain helper stderr was not piped"))?;
    let stdout_reader = std::thread::spawn(move || {
        let mut bytes = Vec::new();
        let mut stdout = stdout;
        stdout.read_to_end(&mut bytes)?;
        Ok::<_, std::io::Error>(bytes)
    });
    let stderr_reader = std::thread::spawn(move || {
        let mut bytes = Vec::new();
        let mut stderr = stderr;
        stderr.read_to_end(&mut bytes)?;
        Ok::<_, std::io::Error>(bytes)
    });
    let started = Instant::now();
    // Sticky: once a dialog is attributed to this run it stays attributed, and
    // SecurityAgent exits as soon as the user answers.
    let mut prompted = false;
    let (status, timed_out) = loop {
        if let Some(status) = child.try_wait()? {
            break (status, false);
        }
        // The deadline exists to bound a HUNG helper. A helper waiting on the
        // user is not hung, and killing it there is actively harmful: macOS
        // shows the unlock/authorize dialog, the person starts typing, the
        // deadline fires, and the dialog is torn down before the unlock can
        // commit. The next request opens a fresh dialog, so entering the
        // correct password over and over never succeeds — the timeout makes the
        // prompt UNSATISFIABLE rather than merely noisy. Nobody reliably finds a
        // window, types a password and submits inside 15s, let alone repeatedly.
        //
        // So while SecurityAgent (the process that draws those dialogs) is up,
        // extend to `SECURITY_CLI_INTERACTIVE_TIMEOUT`. A genuinely hung helper
        // has no dialog and still dies at the short deadline.
        let dialog_on_screen = dialog_probe();
        // Extending the deadline on any sighting is the right call — waiting
        // longer is cheap and reversible, and the cost of being wrong the other
        // way is a torn-down dialog nobody can satisfy.
        //
        // Treating that same sighting as proof that THIS read is the one being
        // authorized is not cheap: it sends the value through
        // `mac_repair_item_acl_with`, which delete-then-adds the item. On a
        // healthy credential that is a pointless rewrite, and on the Parslee
        // auth record it reopens the delete→add window `publish` exists to
        // avoid — a concurrent reader landing in it sees no credential and
        // reports a spurious sign-out mid token-refresh. It also spends the one
        // repair attempt allowed per item per process on the wrong item.
        //
        // The two conditions differ in what they need to be true, so they get
        // different evidence. See `dialog_is_evidence_for_this_read`.
        if !prompted && dialog_is_evidence_for_this_read(dialog_on_screen, started.elapsed()) {
            prompted = true;
            // Say so NOW, not on expiry (Parslee-ai/car#878). Everything needed
            // to explain the wait is true at this instant, and the on-expiry
            // message below only prints if the user waits out the full 180s —
            // so an operator who kills the "hung" command at two minutes, or a
            // wrapper/CI step with a shorter timeout, never saw it at all. That
            // is the reported experience exactly: three runs killed, three
            // fresh dialogs raised, and the explanation the code was ready to
            // give never reached anyone.
            //
            // Fires on the ATTRIBUTED predicate rather than a bare sighting.
            // `SecurityAgent` is machine-wide (Parslee-ai/car#897), so a bare
            // sighting can belong to another process's dialog; requiring that
            // this read has also been blocked for `PROMPT_EVIDENCE_MIN` keeps
            // the notice off fast reads that merely coincided with someone
            // else's prompt. Reusing `prompted` as the latch is deliberate —
            // one blocked read, one line, and no second piece of state that
            // could disagree with it.
            on_waiting_for_user();
        }
        let deadline = if dialog_on_screen {
            SECURITY_CLI_INTERACTIVE_TIMEOUT
        } else {
            timeout
        };
        if started.elapsed() >= deadline {
            let _ = child.kill();
            break (child.wait()?, true);
        }
        std::thread::sleep(std::time::Duration::from_millis(10));
    };
    let join_reader = |reader: std::thread::JoinHandle<std::io::Result<Vec<u8>>>,
                       stream: &str|
     -> std::io::Result<Vec<u8>> {
        reader.join().map_err(|_| {
            std::io::Error::other(format!("keychain helper {stream} reader panicked"))
        })?
    };
    let stdout = join_reader(stdout_reader, "stdout")?;
    let mut stderr = join_reader(stderr_reader, "stderr")?;
    if timed_out {
        // Name the cause. `security` blocks here when macOS is showing a
        // keychain authorization dialog, so the deadline is nearly always "a
        // prompt nobody clicked" rather than a hung helper. Without saying so,
        // this surfaces to the user as `no inference backend is available` —
        // which points at models and accounts, i.e. everywhere except the
        // dialog actually waiting on screen.
        stderr.extend_from_slice(
            format!(
                "\nCAR killed the keychain helper after {}ms. This usually means a macOS \
                 keychain prompt is open and waiting: click \"Always Allow\" (or grant access \
                 to the \"car\" service in Keychain Access). Until it is answered, CAR cannot \
                 read your saved credentials and will report that no account is signed in.",
                timeout.as_millis()
            )
            .as_bytes(),
        );
    }
    Ok(BoundedRun {
        output: std::process::Output {
            status,
            stdout,
            stderr,
        },
        prompted,
        timed_out,
    })
}

/// Primary macOS value read:
/// `/usr/bin/security find-generic-password -s SVC -a KEY -g`.
/// `-g` prints the password metadata line to stderr and preserves the
/// password bytes as hex when the value contains non-printable UTF-8
/// bytes. Service/key are passed as separate argv values, never
/// interpolated into a shell, so there's no injection surface even if a
/// key contains shell metacharacters.
#[cfg(target_os = "macos")]
fn mac_get_via_security_cli(r: &SecretRef) -> Result<String, SecretError> {
    mac_get_via_security_cli_with(r, &SystemSecurityCli)
}

/// Opt out of the ACL repair below: `CAR_KEYCHAIN_NO_ACL_REPAIR=1`.
///
/// An escape hatch rather than a setting. Repair rewrites a keychain item, and
/// an operator who does not want CAR touching their keychain — a shared machine,
/// a managed item, an audit — deserves a way to say so without giving up
/// credential reads entirely.
#[cfg(target_os = "macos")]
const ACL_REPAIR_OPT_OUT_ENV: &str = "CAR_KEYCHAIN_NO_ACL_REPAIR";

/// Refs this process has already tried to repair.
///
/// At most one attempt per ref per process. If a repair does not take, the next
/// read would prompt again and re-attempt forever — turning one bad dialog into
/// an endless pair of them. One attempt, then let it be.
#[cfg(target_os = "macos")]
fn acl_repair_attempted() -> &'static std::sync::Mutex<std::collections::HashSet<(String, String)>>
{
    static ATTEMPTED: std::sync::OnceLock<
        std::sync::Mutex<std::collections::HashSet<(String, String)>>,
    > = std::sync::OnceLock::new();
    ATTEMPTED.get_or_init(|| std::sync::Mutex::new(std::collections::HashSet::new()))
}

/// Rewrite an item so its ACL stops being bound to a binary that no longer
/// matches.
///
/// ## Why this exists
///
/// The legacy keychain binds an item to the **code-signing hash** of whatever
/// wrote it. That hash changes on every release and every rebuild, so an item
/// written by an older CAR is unreadable-without-asking by a newer one, forever:
/// macOS prompts on every single read. Writes have passed `-A` (permissive ACL)
/// since #142 (v0.5.2) and have pre-deleted first — so the flag lands on a
/// genuine *create*, since `-U` on an existing item ignores it — since v0.18.0.
/// Both only help items written *after* them; nothing ever repaired the ones
/// already on disk, so anyone who signed in before v0.41.0 kept being prompted
/// with no way out except signing out and back in.
///
/// A successful read that had to prompt is proof of exactly that condition, and
/// it hands us the value. So repair it in place: one dialog, then silence.
///
/// ## Why it cannot lose the credential
///
/// Repair is delete-then-add, which has a window where the item does not exist.
/// Losing a credential here would be far worse than the prompt it cures, so:
///
/// - it runs **only** with a non-empty value already in hand;
/// - after writing it **reads back** and compares, and if that does not match it
///   re-adds once more;
/// - every failure path is swallowed. The caller's read already succeeded, and a
///   failed repair must never turn a working read into an error.
#[cfg(target_os = "macos")]
fn mac_repair_item_acl_with(r: &SecretRef, value: &str, cli: &impl SecurityCli) {
    if value.is_empty() {
        return;
    }
    if std::env::var(ACL_REPAIR_OPT_OUT_ENV).is_ok_and(|v| v == "1") {
        return;
    }
    {
        let mut attempted = match acl_repair_attempted().lock() {
            Ok(guard) => guard,
            Err(poisoned) => poisoned.into_inner(),
        };
        if !attempted.insert((r.service.clone(), r.key.clone())) {
            return;
        }
    }

    if mac_put_via_security_cli_with(&r.service, &r.key, value, cli).is_err() {
        // The add failed. If the pre-delete had already landed the item is now
        // gone, so put the value back rather than leaving the user signed out.
        let _ = mac_put_via_security_cli_with(&r.service, &r.key, value, cli);
        return;
    }

    // Verify rather than assume. A silent mismatch here would mean we replaced a
    // working credential with something else.
    let restored = matches!(
        mac_get_via_security_cli_raw(r, cli),
        Ok(ref got) if got == value
    );
    if !restored {
        let _ = mac_put_via_security_cli_with(&r.service, &r.key, value, cli);
    }
}

/// The read itself, with no repair attached. Split out so the repair path can
/// verify its own work without recursing back into it.
#[cfg(target_os = "macos")]
fn mac_get_via_security_cli_raw(
    r: &SecretRef,
    cli: &impl SecurityCli,
) -> Result<String, SecretError> {
    let output = cli
        .output(&[
            "find-generic-password",
            "-s",
            &r.service,
            "-a",
            &r.key,
            "-g",
        ])
        .map_err(|e| security_cli_spawn_error("find-generic-password", e))?;
    if !output.success {
        return security_cli_not_found_or_backend("find-generic-password", r, output);
    }
    mac_parse_security_cli_password(&output)
}

#[cfg(target_os = "macos")]
fn mac_get_via_security_cli_with(
    r: &SecretRef,
    cli: &impl SecurityCli,
) -> Result<String, SecretError> {
    let output = cli
        .output(&[
            "find-generic-password",
            "-s",
            &r.service,
            "-a",
            &r.key,
            "-g",
        ])
        .map_err(|e| security_cli_spawn_error("find-generic-password", e))?;
    if !output.success {
        return security_cli_not_found_or_backend("find-generic-password", r, output);
    }
    let prompted = output.prompted;
    let value = mac_parse_security_cli_password(&output)?;
    // A read that had to ask is the evidence of a stale, hash-bound ACL. Repair
    // it now, while the value is in hand, so the next read is silent.
    if prompted {
        mac_repair_item_acl_with(r, &value, cli);
    }
    Ok(value)
}

#[cfg(target_os = "macos")]
fn mac_parse_security_cli_password(output: &SecurityCliOutput) -> Result<String, SecretError> {
    let line = mac_security_cli_text(&output.stderr, "stderr")?
        .lines()
        .find(|line| line.starts_with("password:"))
        .or_else(|| {
            mac_security_cli_text(&output.stdout, "stdout")
                .ok()
                .and_then(|stdout| stdout.lines().find(|line| line.starts_with("password:")))
        })
        .ok_or_else(|| {
            SecretError::Backend(
                "/usr/bin/security find-generic-password -g did not print a password line"
                    .to_string(),
            )
        })?;

    let payload = line
        .strip_prefix("password:")
        .expect("password line prefix was checked")
        .trim_start();

    if payload.is_empty() {
        return Ok(String::new());
    }

    let bytes = if let Some(hex_and_preview) = payload.strip_prefix("0x") {
        mac_decode_security_cli_hex_password(hex_and_preview)?
    } else {
        mac_decode_security_cli_quoted_password(payload)?
    };

    String::from_utf8(bytes).map_err(|e| {
        SecretError::Backend(format!(
            "/usr/bin/security find-generic-password password was not valid utf-8: {}",
            e
        ))
    })
}

#[cfg(target_os = "macos")]
fn mac_security_cli_text<'a>(bytes: &'a [u8], stream: &str) -> Result<&'a str, SecretError> {
    std::str::from_utf8(bytes).map_err(|e| {
        SecretError::Backend(format!(
            "/usr/bin/security find-generic-password {stream} was not valid utf-8: {e}"
        ))
    })
}

#[cfg(target_os = "macos")]
fn mac_decode_security_cli_hex_password(hex_and_preview: &str) -> Result<Vec<u8>, SecretError> {
    let hex: String = hex_and_preview
        .chars()
        .take_while(|c| c.is_ascii_hexdigit())
        .collect();
    if hex.is_empty() || !hex.len().is_multiple_of(2) {
        return Err(SecretError::Backend(format!(
            "/usr/bin/security find-generic-password printed invalid password hex: {hex:?}"
        )));
    }

    (0..hex.len())
        .step_by(2)
        .map(|i| {
            u8::from_str_radix(&hex[i..i + 2], 16).map_err(|e| {
                SecretError::Backend(format!(
                    "/usr/bin/security find-generic-password printed invalid password hex: {e}"
                ))
            })
        })
        .collect()
}

#[cfg(target_os = "macos")]
fn mac_decode_security_cli_quoted_password(payload: &str) -> Result<Vec<u8>, SecretError> {
    let quoted = payload.strip_prefix('"').and_then(|s| s.strip_suffix('"'));
    match quoted {
        Some(value) => Ok(value.as_bytes().to_vec()),
        None => Err(SecretError::Backend(
            "/usr/bin/security find-generic-password printed an unrecognized password line"
                .to_string(),
        )),
    }
}

#[cfg(target_os = "macos")]
fn mac_status_via_security_cli(r: &SecretRef) -> Result<SecretStatus, SecretError> {
    mac_status_via_security_cli_with(r, &SystemSecurityCli)
}

#[cfg(target_os = "macos")]
fn mac_status_via_security_cli_with(
    r: &SecretRef,
    cli: &impl SecurityCli,
) -> Result<SecretStatus, SecretError> {
    let exists = mac_exists_via_security_cli_with(r, cli)?;
    Ok(SecretStatus {
        service: r.service.clone(),
        key: r.key.clone(),
        exists,
    })
}

/// Existence-only shell-out: `security find-generic-password -s SVC -a KEY`
/// (no `-w`). Exit 0 means found, exit 44 means absent. Other non-zero
/// exits are backend/authorization errors and must not fall through to
/// an in-process API that can prompt again under the caller binary's CDHash.
#[cfg(target_os = "macos")]
fn mac_exists_via_security_cli_with(
    r: &SecretRef,
    cli: &impl SecurityCli,
) -> Result<bool, SecretError> {
    let output = cli
        .output(&["find-generic-password", "-s", &r.service, "-a", &r.key])
        .map_err(|e| security_cli_spawn_error("find-generic-password", e))?;
    if output.success {
        return Ok(true);
    }
    if output.code == Some(SECURITY_ERR_SEC_ITEM_NOT_FOUND) {
        return Ok(false);
    }
    Err(security_cli_backend_error("find-generic-password", output))
}

#[cfg(target_os = "macos")]
fn mac_delete_via_security_cli(r: &SecretRef) -> Result<(), SecretError> {
    mac_delete_via_security_cli_with(r, &SystemSecurityCli)
}

/// Primary macOS delete. Treats "no such item" as success to preserve
/// the public idempotent delete contract.
#[cfg(target_os = "macos")]
fn mac_delete_via_security_cli_with(
    r: &SecretRef,
    cli: &impl SecurityCli,
) -> Result<(), SecretError> {
    let output = cli
        .output(&["delete-generic-password", "-s", &r.service, "-a", &r.key])
        .map_err(|e| security_cli_spawn_error("delete-generic-password", e))?;
    if output.success || output.code == Some(SECURITY_ERR_SEC_ITEM_NOT_FOUND) {
        return Ok(());
    }
    Err(security_cli_backend_error(
        "delete-generic-password",
        output,
    ))
}

#[cfg(target_os = "macos")]
fn security_cli_not_found_or_backend<T>(
    command: &str,
    r: &SecretRef,
    output: SecurityCliOutput,
) -> Result<T, SecretError> {
    if output.code == Some(SECURITY_ERR_SEC_ITEM_NOT_FOUND) {
        return Err(SecretError::NotFound {
            service: r.service.clone(),
            key: r.key.clone(),
        });
    }
    Err(security_cli_backend_error(command, output))
}

#[cfg(target_os = "macos")]
fn security_cli_spawn_error(command: &str, e: std::io::Error) -> SecretError {
    SecretError::Backend(format!("/usr/bin/security {command} spawn: {e}"))
}

#[cfg(target_os = "macos")]
fn security_cli_backend_error(command: &str, output: SecurityCliOutput) -> SecretError {
    let stderr = String::from_utf8_lossy(&output.stderr);
    if output.timed_out {
        return classify_helper_timeout(command);
    }
    let code = output.code.unwrap_or(-1);
    match classify_security_error(code, stderr.trim()) {
        SecretError::Backend(_) => SecretError::Backend(format!(
            "/usr/bin/security {command} failed: code={code} {}",
            stderr.trim()
        )),
        typed => typed,
    }
}

#[cfg(target_os = "macos")]
fn classify_security_error(code: i32, detail: &str) -> SecretError {
    let normalized = detail.to_ascii_lowercase();
    if code == -128 || (code == 128 && normalized.contains("cancel")) {
        return SecretError::UserCancelled {
            message: detail.to_string(),
        };
    }
    if code == -25293
        || code == 51
        || normalized.contains("authorization denied")
        || normalized.contains("auth denied")
        || normalized.contains("interaction is not allowed")
    {
        return SecretError::AccessDenied {
            message: detail.to_string(),
        };
    }
    SecretError::Backend(format!("macOS security error: code={code} {detail}"))
}

#[cfg(target_os = "macos")]
fn classify_helper_timeout(operation: &str) -> SecretError {
    SecretError::HelperTimedOut {
        operation: operation.to_string(),
    }
}

/// Map keyring crate errors into our typed error set.
///
/// Not compiled on macOS: nothing there reaches the keyring crate, so there
/// are no keyring errors to classify. The macOS equivalents are
/// `security_cli_backend_error` and `security_cli_not_found_or_backend`.
#[cfg(not(target_os = "macos"))]
fn classify(e: keyring::Error, op: &str) -> SecretError {
    use keyring::Error as K;
    match e {
        K::NoEntry => SecretError::NotFound {
            service: String::new(),
            key: String::new(),
        },
        K::PlatformFailure(inner) => SecretError::Unavailable(format!("{}: {}", op, inner)),
        K::NoStorageAccess(inner) => SecretError::Unavailable(format!("{}: {}", op, inner)),
        K::BadEncoding(_) => SecretError::Backend(format!("{}: value encoding", op)),
        other => SecretError::Backend(format!("{}: {}", op, other)),
    }
}

#[cfg(test)]
mod chunk_tests {
    use super::*;
    use std::collections::BTreeMap;

    #[test]
    fn split_on_chars_covers_boundaries() {
        assert_eq!(split_on_chars("", 3), Vec::<String>::new());
        assert_eq!(split_on_chars("abc", 3), vec!["abc"]);
        assert_eq!(split_on_chars("abcd", 3), vec!["abc", "d"]);
        assert_eq!(split_on_chars("abcdef", 2), vec!["ab", "cd", "ef"]);
        // Reassembly is lossless for a value well past the Windows blob cap.
        let big: String = "x".repeat(4000);
        let joined: String = split_on_chars(&big, CHUNK_CHARS).concat();
        assert_eq!(joined, big);
    }

    #[test]
    fn sentinel_round_trips_the_chunk_count() {
        let n = split_on_chars(&"y".repeat(3300), CHUNK_CHARS).len();
        let sentinel = format!("{CHUNK_SENTINEL}{n}");
        let parsed = sentinel
            .strip_prefix(CHUNK_SENTINEL)
            .and_then(|s| s.parse::<usize>().ok());
        assert_eq!(parsed, Some(4)); // 3300 / 1000 -> 4 chunks
                                     // A real (non-chunked) value is never mistaken for a sentinel.
        assert!("eyJhbGciOi.reallongjwt"
            .strip_prefix(CHUNK_SENTINEL)
            .is_none());
    }

    #[test]
    fn threshold_leaves_small_values_inline() {
        // A value at/under the threshold must NOT be chunked (single entry,
        // backward compatible with pre-existing secrets).
        assert!("short-api-key".encode_utf16().count() <= CHUNK_THRESHOLD_UTF16);
        assert!("z".repeat(2001).encode_utf16().count() > CHUNK_THRESHOLD_UTF16);
    }

    #[derive(Debug, Clone)]
    struct FailureRule {
        slot: WindowsCredentialSlot,
        matches_to_skip: usize,
    }

    #[derive(Debug, Clone, Default)]
    struct MemoryWindowsBackend {
        entries: BTreeMap<WindowsCredentialSlot, String>,
        mutation_calls: usize,
        crash_after_mutation: Option<usize>,
        fail_write: Option<FailureRule>,
        fail_delete: Option<FailureRule>,
    }

    impl MemoryWindowsBackend {
        fn after_mutation(&mut self) {
            self.mutation_calls += 1;
            if self.crash_after_mutation == Some(self.mutation_calls) {
                panic!("injected Windows credential process crash");
            }
        }

        fn should_fail(rule: &mut Option<FailureRule>, slot: &WindowsCredentialSlot) -> bool {
            let Some(candidate) = rule.as_mut() else {
                return false;
            };
            if &candidate.slot != slot {
                return false;
            }
            if candidate.matches_to_skip > 0 {
                candidate.matches_to_skip -= 1;
                return false;
            }
            *rule = None;
            true
        }

        fn reset_faults(&mut self) {
            self.mutation_calls = 0;
            self.crash_after_mutation = None;
            self.fail_write = None;
            self.fail_delete = None;
        }

        fn root(&self) -> String {
            self.entries
                .get(&WindowsCredentialSlot::Root)
                .expect("root credential")
                .clone()
        }
    }

    impl WindowsCredentialBackend for MemoryWindowsBackend {
        fn read(&mut self, slot: &WindowsCredentialSlot) -> Result<Option<String>, SecretError> {
            Ok(self.entries.get(slot).cloned())
        }

        fn write(&mut self, slot: &WindowsCredentialSlot, value: &str) -> Result<(), SecretError> {
            if Self::should_fail(&mut self.fail_write, slot) {
                return Err(SecretError::Backend(
                    "injected Windows credential write failure".to_string(),
                ));
            }
            self.entries.insert(slot.clone(), value.to_string());
            self.after_mutation();
            Ok(())
        }

        fn delete(&mut self, slot: &WindowsCredentialSlot) -> Result<(), SecretError> {
            if Self::should_fail(&mut self.fail_delete, slot) {
                return Err(SecretError::Backend(
                    "injected Windows credential cleanup failure".to_string(),
                ));
            }
            self.entries.remove(slot);
            self.after_mutation();
            Ok(())
        }
    }

    fn publish(backend: &mut MemoryWindowsBackend, value: &str) -> WindowsCleanupReport {
        publish_windows_value(backend, value).expect("publication")
    }

    fn read(backend: &mut impl WindowsCredentialBackend) -> String {
        read_windows_value(backend)
            .expect("read succeeds")
            .expect("root exists")
    }

    fn legacy_v2(value: &str, nonce: &str) -> MemoryWindowsBackend {
        let mut backend = MemoryWindowsBackend::default();
        let chunks = split_on_chars(value, CHUNK_CHARS);
        backend.entries.insert(
            WindowsCredentialSlot::Root,
            format!("{CHUNK_SENTINEL_V2}{nonce}:{}", chunks.len()),
        );
        for (index, chunk) in chunks.into_iter().enumerate() {
            backend.entries.insert(
                WindowsCredentialSlot::LegacyV2Chunk {
                    nonce: nonce.to_string(),
                    index,
                },
                chunk,
            );
        }
        backend
    }

    fn assert_backend_error(error: SecretError, needle: &str) {
        match error {
            SecretError::Backend(message) => assert!(message.contains(needle), "{message}"),
            other => panic!("expected backend error, got {other:?}"),
        }
    }

    #[test]
    fn v3_publication_uses_revisioned_dual_generation_roots() {
        let value = "v".repeat(3300);
        let plan = chunk_publication_plan(&value, ChunkGeneration::B, "revision-7").unwrap();

        assert_eq!(plan.generation, ChunkGeneration::B);
        assert_eq!(plan.chunks.concat(), value);
        assert_eq!(
            windows_root_layout(&plan.root).unwrap(),
            WindowsRootLayout::V3 {
                generation: ChunkGeneration::B,
                revision: "revision-7".to_string(),
                count: 4,
            }
        );
        assert!(
            plan.chunks
                .iter()
                .all(|chunk| chunk.encode_utf16().count() <= CHUNK_CHARS),
            "every staged credential must remain below the platform cap"
        );
    }

    #[test]
    fn reader_capturing_old_root_finishes_after_writer_swaps_root() {
        let old = "old-".repeat(900);
        let new = "new-".repeat(900);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);

        let mut reader = InterleavingReader::new(backend, vec![new.as_str()]);
        assert_eq!(read(&mut reader), old);
        assert_eq!(read(&mut reader.inner), new);
    }

    #[test]
    fn reader_detects_generation_aba_and_retries_latest_root() {
        let old = "old-".repeat(900);
        let middle = "mid-".repeat(1100);
        let latest = "latest-".repeat(700);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);

        let mut reader = InterleavingReader::new(backend, vec![middle.as_str(), latest.as_str()]);
        assert_eq!(read(&mut reader), latest);
        assert!(reader.root_reads >= 4, "the ABA path must consume a retry");
    }

    #[test]
    fn legacy_nonce_chunks_survive_the_first_v3_root_swap_then_recover() {
        let old = "legacy-".repeat(700);
        let replacement = "replacement-".repeat(500);
        let followup = "followup-".repeat(500);
        let backend = legacy_v2(&old, "legacy-nonce");

        let mut reader = InterleavingReader::new(backend, vec![replacement.as_str()]);
        assert_eq!(read(&mut reader), old);
        assert!(reader
            .inner
            .entries
            .contains_key(&WindowsCredentialSlot::RetiredV2Manifest));
        assert!(reader
            .inner
            .entries
            .contains_key(&WindowsCredentialSlot::LegacyV2Chunk {
                nonce: "legacy-nonce".to_string(),
                index: 0,
            }));

        publish(&mut reader.inner, &followup);
        assert!(!reader
            .inner
            .entries
            .contains_key(&WindowsCredentialSlot::RetiredV2Manifest));
        assert!(!reader.inner.entries.keys().any(|slot| matches!(
            slot,
            WindowsCredentialSlot::LegacyV2Chunk { nonce, .. } if nonce == "legacy-nonce"
        )));
    }

    #[test]
    fn crash_after_every_publish_mutation_preserves_a_readable_generation() {
        let old = "old-".repeat(1200);
        let current = "current-".repeat(900);
        let replacement = "replacement-".repeat(300);
        let mut base = MemoryWindowsBackend::default();
        publish(&mut base, &old);
        publish(&mut base, &current);
        base.reset_faults();

        let mut successful = base.clone();
        publish(&mut successful, &replacement);
        let mutation_count = successful.mutation_calls;
        assert!(mutation_count >= 7, "exercise stage, commit, and cleanup");

        for crash_after in 1..=mutation_count {
            let mut crashed = base.clone();
            crashed.crash_after_mutation = Some(crash_after);
            let unwind = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                let _ = publish_windows_value(&mut crashed, &replacement);
            }));
            assert!(unwind.is_err(), "mutation {crash_after} must crash");
            crashed.reset_faults();

            let observed = read(&mut crashed);
            assert!(
                observed == current || observed == replacement,
                "crash {crash_after} exposed neither committed generation"
            );

            publish(&mut crashed, &replacement);
            publish(&mut crashed, "recovery-pass");
            publish(&mut crashed, &replacement);
            assert_eq!(read(&mut crashed), replacement);
            assert!(
                crashed.entries.len() <= 20,
                "crash {crash_after} leaked unbounded entries: {:?}",
                crashed.entries.keys().collect::<Vec<_>>()
            );
        }
    }

    #[test]
    fn repeated_precommit_crashes_have_bounded_cardinality_and_recover_cleanup() {
        let old = "old-".repeat(900);
        let attempted = "attempted-".repeat(900);
        let recovered = "ok-".repeat(600);
        let attempted_chunks = split_on_chars(&attempted, CHUNK_CHARS).len();
        let old_chunks = split_on_chars(&old, CHUNK_CHARS).len();
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);

        for crash_index in 0..64 {
            backend.reset_faults();
            backend.crash_after_mutation = Some(1 + crash_index % attempted_chunks);
            let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                let _ = publish_windows_value(&mut backend, &attempted);
            }));
            assert!(
                backend.entries.len() <= 1 + 2 + old_chunks + attempted_chunks,
                "attempt {crash_index} grew deterministic storage"
            );
        }

        backend.reset_faults();
        publish(&mut backend, &recovered);
        assert_eq!(read(&mut backend), recovered);
        let recovered_chunks = split_on_chars(&recovered, CHUNK_CHARS).len();
        assert!(!backend.entries.keys().any(|slot| matches!(
            slot,
            WindowsCredentialSlot::V3Chunk {
                generation: ChunkGeneration::B,
                index,
            } if *index >= recovered_chunks
        )));
        assert_eq!(
            backend
                .entries
                .get(&WindowsCredentialSlot::V3Manifest(ChunkGeneration::B)),
            Some(&recovered_chunks.to_string())
        );
    }

    #[test]
    fn staging_and_root_failures_leave_the_only_good_generation_readable() {
        let old = "old-".repeat(900);
        let replacement = "replacement-".repeat(500);
        for failed_slot in [
            WindowsCredentialSlot::V3Chunk {
                generation: ChunkGeneration::B,
                index: 1,
            },
            WindowsCredentialSlot::Root,
        ] {
            let mut backend = MemoryWindowsBackend::default();
            publish(&mut backend, &old);
            backend.fail_write = Some(FailureRule {
                slot: failed_slot,
                matches_to_skip: 0,
            });

            let error = publish_windows_value(&mut backend, &replacement).unwrap_err();
            assert_backend_error(error, "injected");
            assert_eq!(read(&mut backend), old);
        }
    }

    #[test]
    fn postcommit_cleanup_errors_report_deferred_success_and_recover_later() {
        let old = "old-".repeat(1400);
        let current = "current-".repeat(900);
        let replacement = "replacement-".repeat(200);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);
        publish(&mut backend, &current);
        backend.fail_delete = Some(FailureRule {
            slot: WindowsCredentialSlot::V3Chunk {
                generation: ChunkGeneration::A,
                index: 4,
            },
            matches_to_skip: 0,
        });

        let cleanup = publish_windows_value(&mut backend, &replacement).unwrap();
        assert_eq!(cleanup.failures, 1);
        assert_eq!(read(&mut backend), replacement);
        assert_eq!(
            backend
                .entries
                .get(&WindowsCredentialSlot::V3Manifest(ChunkGeneration::A)),
            Some(&split_on_chars(&old, CHUNK_CHARS).len().to_string()),
            "failed cleanup keeps the crash high-water for a later sweep"
        );

        publish(&mut backend, "rotate-once");
        publish(&mut backend, &replacement);
        assert!(!backend.entries.keys().any(|slot| matches!(
            slot,
            WindowsCredentialSlot::V3Chunk {
                generation: ChunkGeneration::A,
                index,
            } if *index >= split_on_chars(&replacement, CHUNK_CHARS).len()
        )));
    }

    #[test]
    fn postcommit_manifest_shrink_failure_keeps_recovery_high_water() {
        let old = "old-".repeat(1400);
        let current = "current-".repeat(900);
        let replacement = "replacement-".repeat(200);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);
        publish(&mut backend, &current);
        backend.fail_write = Some(FailureRule {
            slot: WindowsCredentialSlot::V3Manifest(ChunkGeneration::A),
            matches_to_skip: 1,
        });

        let cleanup = publish_windows_value(&mut backend, &replacement).unwrap();
        assert_eq!(cleanup.failures, 1);
        assert_eq!(read(&mut backend), replacement);
        assert_eq!(
            backend
                .entries
                .get(&WindowsCredentialSlot::V3Manifest(ChunkGeneration::A)),
            Some(&split_on_chars(&old, CHUNK_CHARS).len().to_string())
        );
    }

    #[test]
    fn delete_cleanup_failure_retains_manifest_for_idempotent_recovery() {
        let value = "secret-".repeat(700);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &value);
        backend.fail_delete = Some(FailureRule {
            slot: WindowsCredentialSlot::V3Chunk {
                generation: ChunkGeneration::A,
                index: 0,
            },
            matches_to_skip: 0,
        });

        let cleanup = delete_windows_value(&mut backend).unwrap();
        assert_eq!(cleanup.failures, 1);
        assert!(!backend.entries.contains_key(&WindowsCredentialSlot::Root));
        assert!(backend
            .entries
            .contains_key(&WindowsCredentialSlot::V3Manifest(ChunkGeneration::A)));

        backend.reset_faults();
        assert_eq!(delete_windows_value(&mut backend).unwrap().failures, 0);
        assert!(backend.entries.is_empty());
    }

    #[test]
    fn corrupt_cleanup_metadata_fails_before_root_or_chunks_are_deleted() {
        let old = "old-".repeat(900);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);
        let root_before = backend.root();
        backend.entries.insert(
            WindowsCredentialSlot::V3Manifest(ChunkGeneration::B),
            "not-a-count".to_string(),
        );

        let error = publish_windows_value(&mut backend, "replacement").unwrap_err();
        assert_backend_error(error, "manifest");
        assert_eq!(backend.root(), root_before);
        assert_eq!(read(&mut backend), old);

        let error = delete_windows_value(&mut backend).unwrap_err();
        assert_backend_error(error, "manifest");
        assert_eq!(backend.root(), root_before);
        assert_eq!(read(&mut backend), old);
    }

    #[test]
    fn reader_retry_is_bounded_when_root_never_stabilizes() {
        let value_a = "a".repeat(2500);
        let value_b = "b".repeat(2500);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &value_a);
        let root_a = backend.root();
        publish(&mut backend, &value_b);
        let root_b = backend.root();
        backend.entries.remove(&WindowsCredentialSlot::V3Chunk {
            generation: ChunkGeneration::A,
            index: 0,
        });
        let mut churning = AlternatingRootBackend {
            inner: backend,
            roots: [root_a, root_b],
            root_reads: 0,
        };

        let error = read_windows_value(&mut churning).unwrap_err();
        assert_backend_error(error, "changed during every read attempt");
        assert_eq!(churning.root_reads, WINDOWS_READ_ATTEMPTS * 2);
    }

    struct InterleavingReader<'a> {
        inner: MemoryWindowsBackend,
        publications: Vec<&'a str>,
        root_reads: usize,
    }

    impl<'a> InterleavingReader<'a> {
        fn new(inner: MemoryWindowsBackend, publications: Vec<&'a str>) -> Self {
            Self {
                inner,
                publications,
                root_reads: 0,
            }
        }
    }

    impl WindowsCredentialBackend for InterleavingReader<'_> {
        fn read(&mut self, slot: &WindowsCredentialSlot) -> Result<Option<String>, SecretError> {
            let captured = self.inner.read(slot)?;
            if slot == &WindowsCredentialSlot::Root && self.root_reads == 0 {
                for value in self.publications.drain(..) {
                    publish_windows_value(&mut self.inner, value)?;
                }
            }
            if slot == &WindowsCredentialSlot::Root {
                self.root_reads += 1;
            }
            Ok(captured)
        }

        fn write(&mut self, slot: &WindowsCredentialSlot, value: &str) -> Result<(), SecretError> {
            self.inner.write(slot, value)
        }

        fn delete(&mut self, slot: &WindowsCredentialSlot) -> Result<(), SecretError> {
            self.inner.delete(slot)
        }
    }

    struct AlternatingRootBackend {
        inner: MemoryWindowsBackend,
        roots: [String; 2],
        root_reads: usize,
    }

    impl WindowsCredentialBackend for AlternatingRootBackend {
        fn read(&mut self, slot: &WindowsCredentialSlot) -> Result<Option<String>, SecretError> {
            if slot == &WindowsCredentialSlot::Root {
                let root = self.roots[self.root_reads % self.roots.len()].clone();
                self.root_reads += 1;
                return Ok(Some(root));
            }
            self.inner.read(slot)
        }

        fn write(&mut self, slot: &WindowsCredentialSlot, value: &str) -> Result<(), SecretError> {
            self.inner.write(slot, value)
        }

        fn delete(&mut self, slot: &WindowsCredentialSlot) -> Result<(), SecretError> {
            self.inner.delete(slot)
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde::{Deserialize, Serialize};

    /// An unusable store must not answer "that secret is absent".
    ///
    /// These three take no env lock: they call the file-backend helpers with an
    /// explicit `dir`, so they touch no process-global state.
    ///
    /// The distinction is invisible on unix, where an entry under a regular file
    /// fails with `ENOTDIR`, and load-bearing on Windows, where the same open
    /// returns `ERROR_PATH_NOT_FOUND` and Rust maps it to `NotFound`. Asserting
    /// it here keeps both platforms honest without needing a Windows runner to
    /// notice the regression.
    #[test]
    fn a_store_that_is_not_a_directory_is_a_backend_error_not_a_missing_secret() {
        let parent = tempfile::tempdir().unwrap();
        let not_a_dir = parent.path().join("blocked");
        std::fs::write(&not_a_dir, b"a regular file where the store should be").unwrap();
        let reference = SecretRef::with_default_service("SOME_KEY");

        assert!(
            !file_backend_entry_is_merely_absent(&not_a_dir),
            "the platform-neutral discriminator must reject a regular-file store root"
        );

        match file_backend_get(&not_a_dir, &reference) {
            Err(SecretError::Backend(_)) => {}
            other => panic!("unusable store must report a backend error, got {other:?}"),
        }
        match file_backend_delete(&not_a_dir, &reference) {
            Err(SecretError::Backend(_)) => {}
            other => panic!("unusable store must not report a successful delete, got {other:?}"),
        }
        assert!(
            !file_backend_status(&not_a_dir, &reference).exists,
            "status on an unusable store must not claim knowledge of the entry"
        );
    }

    /// A store directory that has not been created yet is a first run, not a
    /// broken store: only `put`/`publish` create it.
    #[test]
    fn a_store_directory_that_does_not_exist_yet_is_still_not_found() {
        let parent = tempfile::tempdir().unwrap();
        let never_created = parent.path().join("not-created-yet");
        assert!(!never_created.exists());
        assert!(
            file_backend_entry_is_merely_absent(&never_created),
            "a missing directory beneath an existing directory is a normal first run"
        );
        let reference = SecretRef::with_default_service("SOME_KEY");

        match file_backend_get(&never_created, &reference) {
            Err(SecretError::NotFound { .. }) => {}
            other => panic!("a first-run store has no secrets, it is not broken: {other:?}"),
        }
        assert!(
            file_backend_delete(&never_created, &reference).is_ok(),
            "deleting from a store that was never written is a no-op success"
        );
        assert!(!file_backend_status(&never_created, &reference).exists);
    }

    #[test]
    fn a_missing_entry_in_a_real_directory_is_still_not_found() {
        let dir = tempfile::tempdir().unwrap();
        let reference = SecretRef::with_default_service("ABSENT_KEY");

        match file_backend_get(dir.path(), &reference) {
            Err(SecretError::NotFound { .. }) => {}
            other => panic!("an absent entry in a usable store is NotFound, got {other:?}"),
        }
        assert!(
            file_backend_delete(dir.path(), &reference).is_ok(),
            "deleting an absent entry from a usable store is a no-op success"
        );
        assert!(!file_backend_status(dir.path(), &reference).exists);
    }

    /// Process-wide serialization lock for every test that touches the secret
    /// store. `CAR_SECRETS_FILE_DIR` is a process-global env var: the file-
    /// backend test sets it, and every other test reads it (via
    /// `file_backend_dir()` inside `is_available`/`put`/`get`). Without this
    /// lock the file-backend test could flip the global redirect while a
    /// keychain test is mid-flight, routing it to a temp dir that then gets
    /// removed — a real, observed flake. Every test below acquires this guard
    /// first, so the store backend is stable for the duration of each test.
    /// `unwrap_or_else(into_inner)` keeps the suite running if one test panics
    /// while holding it.
    static STORE_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());

    fn lock_store() -> std::sync::MutexGuard<'static, ()> {
        STORE_LOCK.lock().unwrap_or_else(|e| e.into_inner())
    }

    // Tests use a unique service name per run to avoid colliding with any
    // real credentials a developer has in their keychain. On headless Linux
    // CI without a Secret Service daemon, these will return Unavailable; we
    // skip in that case rather than fake success.
    fn test_service() -> String {
        format!(
            "car-secrets-tests-{}-{}",
            std::process::id(),
            // Nanos since startup — good enough to isolate tests running
            // in parallel inside one process.
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos())
                .unwrap_or(0)
        )
    }

    fn skip_if_unavailable() -> bool {
        !SecretStore::new().is_available()
    }

    /// S2 — the opt-in file backend is honored in a debug/test build, drives a
    /// real `put`/`get`/`delete` round-trip through the plaintext file path, and
    /// `availability` still reports healthy (it's just the local filesystem).
    ///
    /// `cargo test` builds with `debug_assertions` on, so `file_backend_dir()`
    /// honors `CAR_SECRETS_FILE_DIR` here. A RELEASE binary returns `None` from
    /// `file_backend_dir()` regardless — production can never reach this path.
    ///
    /// The env var is process-global; this test sets it, runs, then removes it.
    /// It must be the only test in this module that mutates the env var. (The
    /// other tests use the keychain with unique service names and do not read
    /// this var.)
    /// A `MakeWriter` that appends every emitted log line into a shared buffer
    /// so the test can assert the one-time file-backend warning actually fired.
    #[derive(Clone)]
    struct BufWriter(std::sync::Arc<std::sync::Mutex<Vec<u8>>>);

    impl std::io::Write for BufWriter {
        fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
            self.0.lock().unwrap().extend_from_slice(buf);
            Ok(buf.len())
        }
        fn flush(&mut self) -> std::io::Result<()> {
            Ok(())
        }
    }

    impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for BufWriter {
        type Writer = BufWriter;
        fn make_writer(&'a self) -> Self::Writer {
            self.clone()
        }
    }

    #[test]
    fn file_backend_roundtrip_and_warn_under_debug() {
        const CHILD: &str = "CAR_TEST_FILE_BACKEND_WARNING_CHILD";
        if std::env::var_os(CHILD).is_none() {
            let output =
                std::process::Command::new(std::env::current_exe().expect("test executable"))
                    .args([
                        "--exact",
                        "tests::file_backend_roundtrip_and_warn_under_debug",
                        "--nocapture",
                    ])
                    .env(CHILD, "1")
                    .env_remove("CAR_SECRETS_FILE_DIR")
                    .env_remove("CAR_TEST_PRECONSUME_FILE_BACKEND_WARNING")
                    .env_remove("CAR_KEYCHAIN_PROOF_ROOT")
                    .env_remove("CAR_KEYCHAIN_PATH")
                    .output()
                    .expect("spawn isolated file-backend warning test");
            assert!(
                output.status.success(),
                "isolated file-backend warning test failed\nstdout:\n{}\nstderr:\n{}",
                String::from_utf8_lossy(&output.stdout),
                String::from_utf8_lossy(&output.stderr),
            );
            return;
        }

        // Test hook for the isolation regression: model another parallel test
        // engaging the process-wide file backend before this test installs its
        // tracing subscriber.
        if std::env::var_os("CAR_TEST_PRECONSUME_FILE_BACKEND_WARNING").is_some() {
            let _ = file_backend_dir();
        }
        // Hold the store lock for the WHOLE test: while the global redirect env
        // var is set, no parallel keychain test may run.
        let _guard = lock_store();
        // Sanity: this whole seam only exists in debug builds. The asserted
        // value is a compile-time constant on purpose — it documents the
        // debug-build dependency, so silence the constant-assertion lint.
        #[allow(clippy::assertions_on_constants)]
        {
            assert!(
                cfg!(debug_assertions),
                "the crate test suite runs in debug; the file backend depends on it"
            );
        }

        let dir = std::env::temp_dir().join(format!(
            "car-secrets-filebackend-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos())
                .unwrap_or(0)
        ));
        std::fs::create_dir_all(&dir).unwrap();
        std::env::set_var("CAR_SECRETS_FILE_DIR", &dir);

        // Capture logs so we can assert the one-time warning fires the first
        // time the redirect engages in this process.
        let buf = std::sync::Arc::new(std::sync::Mutex::new(Vec::<u8>::new()));
        let subscriber = tracing_subscriber::fmt()
            .with_writer(BufWriter(buf.clone()))
            .with_max_level(tracing::Level::WARN)
            .finish();
        tracing::subscriber::with_default(subscriber, || {
            // The redirect is honored (Some) — and fires the one-time warn the
            // first time it engages in this process.
            assert_eq!(
                file_backend_dir().as_deref(),
                Some(dir.as_path()),
                "CAR_SECRETS_FILE_DIR must be honored under debug_assertions"
            );
        });
        let logged = String::from_utf8(buf.lock().unwrap().clone()).unwrap();
        assert!(
            logged.contains("PLAINTEXT ON DISK"),
            "the file backend must emit the one-time PLAINTEXT warning, got logs: {logged:?}"
        );

        let store = SecretStore::new();
        // availability_check still reports healthy on the file backend.
        let check = store.availability();
        assert!(check.available, "file backend must report available");
        assert!(check.reason.is_none());

        // Real put/get/delete round-trip through the plaintext file path.
        let r = SecretRef::new("svc", "key");
        store.put(&r, "xoxb-plaintext-value").unwrap();
        assert_eq!(store.get(&r).unwrap(), "xoxb-plaintext-value");
        // The value really is plaintext on disk (the documented trade-off).
        let on_disk = std::fs::read_to_string(file_backend_path(&dir, &r)).unwrap();
        assert_eq!(on_disk, "xoxb-plaintext-value");
        store.delete(&r).unwrap();
        match store.get(&r) {
            Err(SecretError::NotFound { .. }) => {}
            other => panic!("expected NotFound after delete, got {other:?}"),
        }

        // The reserved-slot guard lives in generic wrappers, not SecretStore:
        // Daemon-owned code must still be able to lease and delete every exact
        // internal slot directly even though generic wrappers reject them.
        for key in [
            OPENROUTER_OAUTH_KEY,
            PARSLEE_ACCESS_TOKEN_KEY,
            PARSLEE_REFRESH_TOKEN_KEY,
            PARSLEE_EXPIRES_AT_KEY,
            PARSLEE_API_BASE_KEY,
            PARSLEE_ACCOUNTS_KEY,
            "PARSLEE_TOKENS_account-1",
            PARSLEE_AUTH_GENERATION_KEY,
            PARSLEE_AUTH_COMPLETION_KEY,
            PARSLEE_ACTIVE_ACCOUNT_ID_KEY,
            PARSLEE_AUTH_STATE_V2_KEY,
        ] {
            let private = SecretRef::new(DEFAULT_SERVICE, key);
            assert!(is_daemon_private_secret(&private.service, &private.key));
            store.put(&private, "internal-test-value").unwrap();
            assert_eq!(store.get(&private).unwrap(), "internal-test-value");
            store.delete(&private).unwrap();
            assert!(matches!(
                store.get(&private),
                Err(SecretError::NotFound { .. })
            ));
        }

        // Restore process state so no parallel/later test inherits the redirect.
        std::env::remove_var("CAR_SECRETS_FILE_DIR");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn every_parslee_auth_slot_is_private_to_the_dedicated_auth_surface() {
        for key in [
            PARSLEE_ACCESS_TOKEN_KEY,
            PARSLEE_REFRESH_TOKEN_KEY,
            PARSLEE_EXPIRES_AT_KEY,
            PARSLEE_API_BASE_KEY,
            PARSLEE_ACCOUNTS_KEY,
            "PARSLEE_TOKENS_account-1",
            PARSLEE_ACTIVE_ACCOUNT_ID_KEY,
            PARSLEE_AUTH_GENERATION_KEY,
            PARSLEE_AUTH_COMPLETION_KEY,
            PARSLEE_AUTH_STATE_V2_KEY,
        ] {
            assert!(
                is_daemon_private_secret(DEFAULT_SERVICE, key),
                "{key} must be unreachable through generic secret surfaces"
            );
            assert!(
                !is_daemon_private_secret("other-service", key),
                "reservation must remain scoped to the CAR service"
            );
        }

        assert!(!is_daemon_private_secret(
            DEFAULT_SERVICE,
            "OPENROUTER_API_KEY"
        ));
        for key in [
            format!("{PARSLEE_AUTH_STATE_V2_KEY}#chunk0"),
            format!("{PARSLEE_AUTH_STATE_V2_KEY}#chunkv2#nonce-1#0"),
            format!("{OPENROUTER_OAUTH_KEY}#chunk17"),
            format!("{OPENROUTER_OAUTH_KEY}#chunkv2#nonce-2#3"),
        ] {
            assert!(
                is_daemon_private_secret(DEFAULT_SERVICE, &key),
                "{key} is derived from a daemon-private root"
            );
            assert!(!is_daemon_private_secret("other-service", &key));
        }
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn bounded_command_output_large_helper() {
        if std::env::var_os("CAR_SECURITY_OUTPUT_HELPER").is_none() {
            return;
        }
        use std::io::Write;
        let payload = vec![b'x'; 128 * 1024];
        std::io::stdout().write_all(&payload).unwrap();
        std::io::stdout().flush().unwrap();
        std::io::stderr().write_all(&payload).unwrap();
        std::io::stderr().flush().unwrap();
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn bounded_command_output_drains_large_stdout_and_stderr() {
        let mut command = std::process::Command::new(std::env::current_exe().unwrap());
        command
            .args([
                "--exact",
                "tests::bounded_command_output_large_helper",
                "--nocapture",
            ])
            .env("CAR_SECURITY_OUTPUT_HELPER", "1");

        let output =
            bounded_command_output(&mut command, std::time::Duration::from_secs(5), "test")
                .unwrap();

        assert!(output.output.status.success(), "{output:?}");
        assert!(output.output.stdout.len() >= 128 * 1024);
        assert!(output.output.stderr.len() >= 128 * 1024);
    }

    #[cfg(target_os = "macos")]
    pub(super) struct FakeSecurityCli {
        outputs: std::cell::RefCell<std::collections::VecDeque<std::io::Result<SecurityCliOutput>>>,
        calls: std::cell::RefCell<Vec<Vec<String>>>,
    }

    #[cfg(target_os = "macos")]
    impl FakeSecurityCli {
        pub(super) fn new(outputs: Vec<std::io::Result<SecurityCliOutput>>) -> Self {
            Self {
                outputs: std::cell::RefCell::new(outputs.into()),
                calls: std::cell::RefCell::new(Vec::new()),
            }
        }

        pub(super) fn calls(&self) -> Vec<Vec<String>> {
            self.calls.borrow().clone()
        }
    }

    #[cfg(target_os = "macos")]
    impl SecurityCli for FakeSecurityCli {
        fn output(&self, args: &[&str]) -> std::io::Result<SecurityCliOutput> {
            self.calls
                .borrow_mut()
                .push(args.iter().map(|arg| (*arg).to_string()).collect());
            self.outputs
                .borrow_mut()
                .pop_front()
                .expect("missing fake security output")
        }
    }

    #[cfg(target_os = "macos")]
    pub(super) fn security_output(
        code: i32,
        stdout: impl Into<Vec<u8>>,
        stderr: impl Into<Vec<u8>>,
    ) -> std::io::Result<SecurityCliOutput> {
        Ok(SecurityCliOutput {
            success: code == 0,
            code: Some(code),
            stdout: stdout.into(),
            stderr: stderr.into(),
            prompted: false,
            timed_out: false,
        })
    }

    /// A successful read that macOS had to draw a dialog for — the evidence of
    /// a stale, hash-bound ACL.
    #[cfg(target_os = "macos")]
    pub(super) fn security_output_prompted(
        code: i32,
        stdout: impl Into<Vec<u8>>,
        stderr: impl Into<Vec<u8>>,
    ) -> std::io::Result<SecurityCliOutput> {
        let mut out = security_output(code, stdout, stderr)?;
        out.prompted = true;
        Ok(out)
    }

    #[cfg(target_os = "macos")]
    fn args(values: &[&str]) -> Vec<String> {
        values.iter().map(|value| (*value).to_string()).collect()
    }

    /// The probe runs in front of every credential resolution, so the argv it
    /// sends is the whole point: existence-only, through the Apple-signed
    /// helper, never the in-process keyring path (Parslee-ai/car#897).
    #[cfg(target_os = "macos")]
    #[test]
    fn availability_probe_goes_through_the_security_helper() {
        let cli = FakeSecurityCli::new(vec![security_output(0, "", "")]);
        let check = mac_availability_via_security_cli_with(&cli);

        assert!(check.available);
        assert_eq!(
            cli.calls(),
            vec![args(&[
                "find-generic-password",
                "-s",
                "car-internal",
                "-a",
                "__availability_probe__",
            ])]
        );
        // `-g` is what makes macOS ask for authorization. A probe that runs
        // before every credential read must never be able to raise a dialog,
        // so its absence is asserted rather than left to the argv comparison.
        assert!(
            !cli.calls()[0].iter().any(|arg| arg == "-g"),
            "availability probe must not read password bytes: {:?}",
            cli.calls()[0]
        );
    }

    /// An absent probe item is the normal case — nothing ever writes it. It
    /// still proves the store answered, exactly as `Err(NoEntry)` does off
    /// macOS.
    #[cfg(target_os = "macos")]
    #[test]
    fn availability_probe_absent_item_is_still_reachable() {
        let cli = FakeSecurityCli::new(vec![security_output(
            SECURITY_ERR_SEC_ITEM_NOT_FOUND,
            "",
            "",
        )]);
        let check = mac_availability_via_security_cli_with(&cli);

        assert!(check.available);
        assert!(check.reason.is_none(), "{:?}", check.reason);
    }

    /// A non-zero exit that is not "no such item" is a backend/authorization
    /// failure, and the caller gets the helper's own words for it rather than
    /// a bare `false`.
    #[cfg(target_os = "macos")]
    #[test]
    fn availability_probe_backend_error_reports_unavailable() {
        let cli = FakeSecurityCli::new(vec![security_output(
            51,
            "",
            "security: SecKeychainSearchCopyNext: User interaction is not allowed.",
        )]);
        let check = mac_availability_via_security_cli_with(&cli);

        assert!(!check.available);
        let reason = check.reason.expect("unavailable must carry a reason");
        assert!(
            reason.contains("User interaction is not allowed"),
            "reason should carry the helper's stderr, got {reason:?}"
        );
    }

    /// The property that makes a blocked probe recoverable from `~/.car/logs`
    /// by an operator who was not at the screen (Parslee-ai/car#878, #897):
    /// the notice names the item, and the probe's argv is item-scoped so it
    /// gets a real name instead of a bare subcommand.
    #[cfg(target_os = "macos")]
    #[test]
    fn availability_probe_names_itself_in_the_prompt_notice() {
        let cli = FakeSecurityCli::new(vec![security_output(
            SECURITY_ERR_SEC_ITEM_NOT_FOUND,
            "",
            "",
        )]);
        let _ = mac_availability_via_security_cli_with(&cli);

        // Derived from the argv the probe ACTUALLY sent, never a hand-typed
        // copy of it. `describe_item` falls back to naming the bare subcommand
        // when a call is not item-scoped, so asserting a literal here would
        // pass even if the probe stopped carrying `-s`/`-a` — which is exactly
        // the regression that would put an unnameable item back in the log.
        let sent = cli.calls().remove(0);
        let sent: Vec<&str> = sent.iter().map(String::as_str).collect();
        let item = describe_item(&sent);

        assert_eq!(item, "car-internal/__availability_probe__");
        assert!(
            keychain_prompt_notice(&item).contains(&item),
            "notice must name the blocking item: {}",
            keychain_prompt_notice(&item)
        );
    }

    #[cfg(target_os = "macos")]
    fn assert_access_denied_contains(err: SecretError, expected: &str) {
        match err {
            SecretError::AccessDenied { message } => assert!(
                message.contains(expected),
                "expected access-denied error to contain {expected:?}, got {message:?}"
            ),
            other => panic!("expected AccessDenied, got {:?}", other),
        }
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_security_errors_are_typed_for_recovery() {
        assert!(matches!(
            classify_security_error(-128, "user canceled"),
            SecretError::UserCancelled { .. }
        ));
        assert!(matches!(
            classify_security_error(-25293, "authorization denied"),
            SecretError::AccessDenied { .. }
        ));
        assert!(matches!(
            classify_helper_timeout("car/PARSLEE_AUTH_STATE_V2"),
            SecretError::HelperTimedOut { .. }
        ));

        let mut timed_out = security_output(9, b"", b"helper killed").unwrap();
        timed_out.timed_out = true;
        let cli = FakeSecurityCli::new(vec![Ok(timed_out)]);
        let secret = SecretRef::new("svc", "key");
        assert!(matches!(
            mac_get_via_security_cli_with(&secret, &cli),
            Err(SecretError::HelperTimedOut { .. })
        ));
    }

    #[cfg(target_os = "macos")]
    struct IsolatedKeychainFixture {
        _temp: tempfile::TempDir,
        proof_root: std::path::PathBuf,
        valid_path: std::path::PathBuf,
        symlink_path: std::path::PathBuf,
        outside_path: std::path::PathBuf,
        public_path: std::path::PathBuf,
        directory_path: std::path::PathBuf,
        public_root: std::path::PathBuf,
    }

    #[cfg(target_os = "macos")]
    impl IsolatedKeychainFixture {
        fn new() -> Self {
            use std::os::unix::fs::{symlink, PermissionsExt};

            let temp = tempfile::tempdir().unwrap();
            let proof_root = temp.path().join("proof");
            std::fs::create_dir(&proof_root).unwrap();
            std::fs::set_permissions(&proof_root, std::fs::Permissions::from_mode(0o700)).unwrap();

            let valid_path = proof_root.join("valid.keychain-db");
            std::fs::write(&valid_path, b"keychain fixture").unwrap();
            std::fs::set_permissions(&valid_path, std::fs::Permissions::from_mode(0o600)).unwrap();

            let symlink_path = proof_root.join("linked.keychain-db");
            symlink(&valid_path, &symlink_path).unwrap();

            let outside_path = temp.path().join("outside.keychain-db");
            std::fs::write(&outside_path, b"outside fixture").unwrap();
            std::fs::set_permissions(&outside_path, std::fs::Permissions::from_mode(0o600))
                .unwrap();

            let public_path = proof_root.join("public.keychain-db");
            std::fs::write(&public_path, b"public fixture").unwrap();
            std::fs::set_permissions(&public_path, std::fs::Permissions::from_mode(0o644)).unwrap();

            let directory_path = proof_root.join("directory.keychain-db");
            std::fs::create_dir(&directory_path).unwrap();

            let public_root = temp.path().join("public-proof");
            std::fs::create_dir(&public_root).unwrap();
            std::fs::set_permissions(&public_root, std::fs::Permissions::from_mode(0o755)).unwrap();

            Self {
                _temp: temp,
                proof_root,
                valid_path,
                symlink_path,
                outside_path,
                public_path,
                directory_path,
                public_root,
            }
        }

        fn proof_root(&self) -> &std::path::Path {
            &self.proof_root
        }

        fn valid_path(&self) -> &std::path::Path {
            &self.valid_path
        }

        fn symlink_path(&self) -> &std::path::Path {
            &self.symlink_path
        }

        fn outside_path(&self) -> &std::path::Path {
            &self.outside_path
        }

        fn public_path(&self) -> &std::path::Path {
            &self.public_path
        }

        fn directory_path(&self) -> &std::path::Path {
            &self.directory_path
        }

        fn public_root(&self) -> &std::path::Path {
            &self.public_root
        }
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn isolated_keychain_must_be_absolute_private_regular_owned_and_under_proof_root() {
        let fixture = IsolatedKeychainFixture::new();
        assert!(validate_keychain_path(fixture.valid_path(), fixture.proof_root()).is_ok());
        assert!(validate_keychain_path(
            std::path::Path::new("relative.keychain-db"),
            fixture.proof_root()
        )
        .is_err());
        assert!(validate_keychain_path(fixture.symlink_path(), fixture.proof_root()).is_err());
        assert!(validate_keychain_path(fixture.outside_path(), fixture.proof_root()).is_err());
        assert!(validate_keychain_path(fixture.public_path(), fixture.proof_root()).is_err());
        assert!(validate_keychain_path(fixture.directory_path(), fixture.proof_root()).is_err());
        assert!(validate_keychain_path(fixture.valid_path(), fixture.public_root()).is_err());
    }

    #[test]
    fn secret_store_activity_counts_only_aggregate_public_operation_attempts() {
        let _guard = lock_store();
        let dir = tempfile::tempdir().unwrap();
        std::env::set_var("CAR_SECRETS_FILE_DIR", dir.path());
        let before = secret_store_activity();
        let store = SecretStore::new();
        let secret = SecretRef::new("activity-test", "credential");

        assert!(store.availability().available);
        store.put(&secret, "sensitive-value").unwrap();
        let _ = store.get(&secret).unwrap();
        let _ = store.status(&secret).unwrap();
        store.publish(&secret, "replacement-value").unwrap();
        store.delete(&secret).unwrap();

        let after = secret_store_activity();
        assert_eq!(after.get_attempts - before.get_attempts, 1);
        assert_eq!(after.status_attempts - before.status_attempts, 1);
        assert_eq!(
            after.availability_attempts - before.availability_attempts,
            1
        );
        assert_eq!(after.write_attempts - before.write_attempts, 2);
        assert_eq!(after.delete_attempts - before.delete_attempts, 1);

        let encoded = serde_json::to_string(&after).unwrap();
        assert!(!encoded.contains("activity-test"));
        assert!(!encoded.contains("credential"));
        assert!(!encoded.contains("sensitive-value"));
        assert!(!encoded.contains(dir.path().to_string_lossy().as_ref()));
        std::env::remove_var("CAR_SECRETS_FILE_DIR");
    }

    #[test]
    fn roundtrip_string() {
        let _guard = lock_store();
        if skip_if_unavailable() {
            eprintln!("skipping: no secret store backend available");
            return;
        }
        let store = SecretStore::new();
        let svc = test_service();
        let r = SecretRef::new(&svc, "roundtrip");
        store.put(&r, "hello world").unwrap();
        assert_eq!(store.get(&r).unwrap(), "hello world");
        assert!(store.status(&r).unwrap().exists);
        store.delete(&r).unwrap();
        assert!(!store.status(&r).unwrap().exists);
    }

    #[test]
    fn roundtrip_string_with_trailing_newline() {
        let _guard = lock_store();
        if skip_if_unavailable() {
            eprintln!("skipping: no secret store backend available");
            return;
        }
        let store = SecretStore::new();
        let svc = test_service();
        let r = SecretRef::new(&svc, "roundtrip-newline");
        let value = "abc\n";
        store.put(&r, value).unwrap();
        assert_eq!(store.get(&r).unwrap(), value);
        store.delete(&r).unwrap();
    }

    #[test]
    fn get_missing_returns_not_found() {
        let _guard = lock_store();
        if skip_if_unavailable() {
            return;
        }
        let store = SecretStore::new();
        let r = SecretRef::new(test_service(), "never_written");
        match store.get(&r) {
            Err(SecretError::NotFound { .. }) => (),
            other => panic!("expected NotFound, got {:?}", other),
        }
    }

    #[test]
    fn delete_missing_is_idempotent() {
        let _guard = lock_store();
        if skip_if_unavailable() {
            return;
        }
        let store = SecretStore::new();
        let r = SecretRef::new(test_service(), "missing");
        // Two deletes in a row should both succeed.
        store.delete(&r).unwrap();
        store.delete(&r).unwrap();
    }

    #[test]
    fn json_roundtrip() {
        let _guard = lock_store();
        if skip_if_unavailable() {
            return;
        }
        #[derive(Serialize, Deserialize, PartialEq, Debug)]
        struct Session {
            cookies: Vec<String>,
            expires_at: i64,
        }
        let store = SecretStore::new();
        let svc = test_service();
        let r = SecretRef::new(&svc, "session");
        let s = Session {
            cookies: vec!["a=1".into(), "b=2".into()],
            expires_at: 1_700_000_000,
        };
        store.put_json(&r, &s).unwrap();
        let back: Session = store.get_json(&r).unwrap();
        assert_eq!(back, s);
        store.delete(&r).unwrap();
    }

    #[test]
    fn status_no_leak() {
        let _guard = lock_store();
        if skip_if_unavailable() {
            return;
        }
        let store = SecretStore::new();
        let r = SecretRef::new(test_service(), "status");
        store.put(&r, "secret-payload").unwrap();
        let st = store.status(&r).unwrap();
        // Status intentionally does not carry the value.
        let encoded = serde_json::to_string(&st).unwrap();
        assert!(!encoded.contains("secret-payload"));
        store.delete(&r).unwrap();
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_get_uses_security_cli_and_maps_success() {
        let cli = FakeSecurityCli::new(vec![security_output(
            0,
            b"keychain: \"/Users/example/Library/Keychains/login.keychain-db\"\n",
            b"password: \"secret\"\n",
        )]);
        let r = SecretRef::new("svc", "key");

        assert_eq!(mac_get_via_security_cli_with(&r, &cli).unwrap(), "secret");
        assert_eq!(
            cli.calls(),
            vec![args(&[
                "find-generic-password",
                "-s",
                "svc",
                "-a",
                "key",
                "-g"
            ])]
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_get_decodes_hex_password_output_with_trailing_newline() {
        let cli = FakeSecurityCli::new(vec![security_output(
            0,
            b"keychain: \"/Users/example/Library/Keychains/login.keychain-db\"\n",
            b"password: 0x6162630A  \"abc\\012\"\n",
        )]);
        let r = SecretRef::new("svc", "key");

        assert_eq!(mac_get_via_security_cli_with(&r, &cli).unwrap(), "abc\n");
        assert_eq!(
            cli.calls(),
            vec![args(&[
                "find-generic-password",
                "-s",
                "svc",
                "-a",
                "key",
                "-g"
            ])]
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_get_maps_not_found_and_access_denied_without_fallback() {
        let r = SecretRef::new("svc", "missing");
        let cli = FakeSecurityCli::new(vec![security_output(
            SECURITY_ERR_SEC_ITEM_NOT_FOUND,
            b"",
            b"The specified item could not be found in the keychain.\n",
        )]);

        match mac_get_via_security_cli_with(&r, &cli) {
            Err(SecretError::NotFound { service, key }) => {
                assert_eq!(service, "svc");
                assert_eq!(key, "missing");
            }
            other => panic!("expected NotFound, got {:?}", other),
        }
        assert_eq!(cli.calls().len(), 1);

        let cli = FakeSecurityCli::new(vec![security_output(
            51,
            b"",
            b"User interaction is not allowed.\n",
        )]);
        let err = mac_get_via_security_cli_with(&r, &cli).unwrap_err();
        assert_access_denied_contains(err, "User interaction is not allowed.");
        assert_eq!(cli.calls().len(), 1);
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_status_uses_security_cli_and_maps_results() {
        let r = SecretRef::new("svc", "key");
        let cli = FakeSecurityCli::new(vec![security_output(0, b"", b"")]);

        let status = mac_status_via_security_cli_with(&r, &cli).unwrap();
        assert!(status.exists);
        assert_eq!(
            cli.calls(),
            vec![args(&["find-generic-password", "-s", "svc", "-a", "key"])]
        );

        let cli = FakeSecurityCli::new(vec![security_output(
            SECURITY_ERR_SEC_ITEM_NOT_FOUND,
            b"",
            b"The specified item could not be found in the keychain.\n",
        )]);
        assert!(!mac_status_via_security_cli_with(&r, &cli).unwrap().exists);

        let cli = FakeSecurityCli::new(vec![security_output(128, b"", b"auth denied\n")]);
        let err = mac_status_via_security_cli_with(&r, &cli).unwrap_err();
        assert_access_denied_contains(err, "auth denied");
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_put_pre_deletes_then_adds_so_acl_is_fresh() {
        // Regression for the "3 prompts on car-server startup" bug. Before
        // this fix `mac_put_via_security_cli` issued only
        // `add-generic-password -U -A`, which updates the value but
        // preserves any pre-existing ACL — so items first written by an
        // older binary stayed CDHash-bound forever and `find-generic-password -g`
        // prompted on every read. The fix: best-effort delete first, then add.
        let cli = FakeSecurityCli::new(vec![
            // Pre-delete returns NotFound — that's fine, ignored.
            security_output(
                SECURITY_ERR_SEC_ITEM_NOT_FOUND,
                b"",
                b"The specified item could not be found in the keychain.\n",
            ),
            // Add succeeds.
            security_output(0, b"", b""),
        ]);

        mac_put_via_security_cli_with("svc", "key", "secret", &cli).unwrap();

        assert_eq!(
            cli.calls(),
            vec![
                args(&["delete-generic-password", "-s", "svc", "-a", "key"]),
                args(&[
                    "add-generic-password",
                    "-U",
                    "-A",
                    "-s",
                    "svc",
                    "-a",
                    "key",
                    "-w",
                    "secret",
                ]),
            ]
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_put_ignores_pre_delete_failure_and_still_adds() {
        // If the pre-delete shells back a non-NotFound non-zero (e.g.
        // transient backend error), we still attempt the add — `-U` is the
        // safety net that lets us update the value even if the old item is
        // somehow still around.
        let cli = FakeSecurityCli::new(vec![
            security_output(128, b"", b"some weird backend error\n"),
            security_output(0, b"", b""),
        ]);

        mac_put_via_security_cli_with("svc", "key", "secret", &cli).unwrap();

        assert_eq!(cli.calls().len(), 2);
        assert_eq!(
            cli.calls()[1],
            args(&[
                "add-generic-password",
                "-U",
                "-A",
                "-s",
                "svc",
                "-a",
                "key",
                "-w",
                "secret",
            ])
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_put_surfaces_add_failure_as_access_denied() {
        let cli = FakeSecurityCli::new(vec![
            security_output(0, b"", b""),
            security_output(51, b"", b"User interaction is not allowed.\n"),
        ]);

        let err = mac_put_via_security_cli_with("svc", "key", "secret", &cli).unwrap_err();
        assert_access_denied_contains(err, "User interaction is not allowed.");
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_publish_updates_in_place_without_a_pre_delete_gap() {
        let cli = FakeSecurityCli::new(vec![security_output(0, b"", b"")]);

        mac_publish_via_security_cli_with("svc", "key", "secret", &cli).unwrap();

        assert_eq!(
            cli.calls(),
            vec![args(&[
                "add-generic-password",
                "-U",
                "-A",
                "-s",
                "svc",
                "-a",
                "key",
                "-w",
                "secret",
            ])]
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_security_child_is_killed_and_reaped_at_its_deadline() {
        let mut command = std::process::Command::new("/bin/sh");
        command.args(["-c", "sleep 5"]);
        let started = std::time::Instant::now();

        let output =
            bounded_command_output(&mut command, std::time::Duration::from_millis(40), "test")
                .unwrap();

        assert!(!output.output.status.success());
        assert!(
            started.elapsed() < std::time::Duration::from_secs(1),
            "bounded helper must not wait for the child command's natural exit"
        );
        let stderr = String::from_utf8_lossy(&output.output.stderr);
        assert!(stderr.contains("CAR killed the keychain helper"));
        // The deadline is nearly always an unanswered macOS keychain dialog.
        // Saying only "helper killed" sends the user looking at models and
        // accounts, because that is what the downstream error mentions
        // ("no inference backend is available") — the one thing it never named
        // was the prompt sitting on screen.
        assert!(
            stderr.contains("keychain prompt"),
            "the timeout must name a pending keychain prompt as the likely cause"
        );
        assert!(
            stderr.contains("Always Allow"),
            "the timeout must tell the user what action clears it"
        );
    }

    /// A hung helper with NO dialog on screen must still die at the short
    /// deadline. This is the half that keeps the extension honest: if
    /// `security_agent_is_prompting()` were ever wrong in the permissive
    /// direction, a genuinely stuck child would block for three minutes.
    ///
    /// The interactive half cannot be unit-tested without a real SecurityAgent,
    /// so `security_agent_is_prompting` fails CLOSED — any error determining it
    /// yields the short deadline, never the long one.
    #[cfg(target_os = "macos")]
    #[test]
    fn a_hung_helper_with_no_dialog_still_dies_at_the_short_deadline() {
        // Nothing here opens a keychain dialog, so the deadline must be the
        // short one regardless of what else is running on the machine.
        assert!(
            SECURITY_CLI_INTERACTIVE_TIMEOUT > SECURITY_CLI_TIMEOUT,
            "the interactive allowance must be longer than the hang deadline"
        );
        assert!(
            SECURITY_CLI_INTERACTIVE_TIMEOUT >= std::time::Duration::from_secs(60),
            "a human needs to find a window, type a password and submit — 15s \
             is why entering the correct password repeatedly never worked"
        );

        let mut command = std::process::Command::new("/bin/sh");
        command.args(["-c", "sleep 5"]);
        let started = std::time::Instant::now();
        let output =
            bounded_command_output(&mut command, std::time::Duration::from_millis(40), "test")
                .unwrap();
        assert!(!output.output.status.success());
        assert!(
            started.elapsed() < std::time::Duration::from_secs(1),
            "a helper with no dialog must not inherit the interactive allowance"
        );
    }

    /// A dialog belonging to something else must not be read as proof that
    /// *this* read was authorized.
    ///
    /// `SecurityAgent` is machine-wide, so the bare sighting is true whenever
    /// anything on the Mac is asking for authorization — including another CAR
    /// process blocked on its own prompt, which is exactly the state a
    /// prompt storm puts the machine in. Acting on it there sends every healthy
    /// item in every concurrently-running process through a delete-then-add
    /// rewrite, at the worst possible moment.
    #[cfg(target_os = "macos")]
    #[test]
    fn a_dialog_is_not_attributed_to_a_read_that_did_not_wait_for_it() {
        let instant = std::time::Duration::from_millis(0);
        let quick = std::time::Duration::from_millis(20);

        assert!(
            !dialog_is_evidence_for_this_read(true, instant),
            "a dialog already on screen at spawn belongs to whatever opened it"
        );
        assert!(
            !dialog_is_evidence_for_this_read(true, quick),
            "a read that returned in 20ms was never blocked on a human"
        );
        assert!(
            !dialog_is_evidence_for_this_read(false, std::time::Duration::from_secs(60)),
            "no dialog is no evidence, however long the helper took"
        );
        assert!(
            dialog_is_evidence_for_this_read(true, PROMPT_EVIDENCE_MIN),
            "a call still blocked with a dialog up is the one being authorized"
        );
    }

    /// The threshold has to sit in the gap between the two populations it
    /// separates, and stay well clear of the deadline that ends the call.
    #[cfg(target_os = "macos")]
    #[test]
    fn the_prompt_evidence_threshold_sits_between_a_silent_read_and_a_human() {
        assert!(
            PROMPT_EVIDENCE_MIN >= std::time::Duration::from_millis(200),
            "must be an order of magnitude above a silent `security -g` read, \
             which returns in tens of milliseconds"
        );
        assert!(
            PROMPT_EVIDENCE_MIN <= std::time::Duration::from_secs(2),
            "must stay below the fastest a human can answer a dialog, or a real \
             stale-ACL read never gets repaired and prompts forever"
        );
        assert!(
            PROMPT_EVIDENCE_MIN < SECURITY_CLI_TIMEOUT,
            "a prompted read must be attributable before any deadline can end it"
        );
    }

    /// End-to-end over the real poll loop, with a dialog held on screen for the
    /// whole run: a helper that exits in milliseconds must still come back
    /// unattributed.
    ///
    /// The probe is injected precisely so this cannot pass by accident. Probing
    /// the real `SecurityAgent` would make the assertion depend on whether the
    /// machine happens to have a dialog up — false on every CI runner, which
    /// would let the test pass with no attribution rule at all.
    #[cfg(target_os = "macos")]
    #[test]
    fn a_fast_helper_is_not_attributed_a_dialog_that_is_on_screen_throughout() {
        let mut command = std::process::Command::new("/bin/echo");
        command.arg("hi");
        let notices = std::sync::atomic::AtomicUsize::new(0);
        let run = bounded_command_output_with(
            &mut command,
            SECURITY_CLI_TIMEOUT,
            || true,
            || {
                notices.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
            },
        )
        .unwrap();
        assert!(run.output.status.success());
        assert!(
            !run.prompted,
            "a helper that exited in milliseconds was not the one being authorized, \
             however many dialogs the machine is showing"
        );
        assert_eq!(
            notices.load(std::sync::atomic::Ordering::Relaxed),
            0,
            "and it must not tell the user to go answer a dialog it never waited on \
             (Parslee-ai/car#878 rides on the same attribution rule as #897)"
        );
    }

    /// The other half: a helper that really is blocked past the threshold with a
    /// dialog up *is* attributed one. Without this, the rule could satisfy the
    /// test above by never attributing anything.
    #[cfg(target_os = "macos")]
    #[test]
    fn a_helper_still_blocked_past_the_threshold_is_attributed_the_dialog() {
        // Exits on its own well after PROMPT_EVIDENCE_MIN, so the run ends by
        // natural exit rather than by a deadline — the deadline is extended to
        // the interactive allowance while the probe says a dialog is up.
        let mut command = std::process::Command::new("/bin/sh");
        command.args(["-c", "sleep 1"]);
        let notices = std::sync::atomic::AtomicUsize::new(0);
        let run = bounded_command_output_with(
            &mut command,
            SECURITY_CLI_TIMEOUT,
            || true,
            || {
                notices.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
            },
        )
        .unwrap();
        assert!(run.output.status.success(), "the child must exit naturally");
        assert!(
            run.prompted,
            "a call still running past PROMPT_EVIDENCE_MIN with a dialog up is \
             the call that dialog belongs to"
        );
        // Parslee-ai/car#878: exactly one line, and it arrived while the read
        // was still blocked rather than on expiry — this child exits naturally
        // at ~1s, so the run never reaches a deadline and the on-timeout
        // message is never appended. Only the prompt notice can have fired.
        //
        // ONE, not one-per-poll: the loop ticks every 10ms, so a notice keyed
        // on the condition rather than on the transition would emit ~50 lines
        // here and bury the daemon log it is supposed to make readable.
        assert_eq!(
            notices.load(std::sync::atomic::Ordering::Relaxed),
            1,
            "a blocked read must explain itself exactly once, promptly"
        );
    }

    /// The notice and the on-expiry message describe the same condition three
    /// minutes apart, so they must not drift into giving different remedies.
    #[cfg(target_os = "macos")]
    #[test]
    fn the_prompt_notice_names_the_wait_and_both_remedies() {
        let notice = keychain_prompt_notice("car/parslee_access_token");
        assert!(
            notice.contains("car/parslee_access_token"),
            "must name WHICH item is being asked for — the operator who walked away \
             and came back to a stack of prompts cannot read the dialog after the \
             fact, and the log is the only record (Parslee-ai/car#897): {notice}"
        );
        assert!(
            notice.contains(&SECURITY_CLI_INTERACTIVE_TIMEOUT.as_secs().to_string()),
            "must state how long CAR will wait, or it reads as an indefinite hang: {notice}"
        );
        assert!(
            notice.contains("Always Allow"),
            "must name the one click that also prevents the NEXT prompt: {notice}"
        );
        assert!(
            notice.contains("Keychain Access"),
            "must name the remedy for someone who already dismissed the dialog: {notice}"
        );
        assert!(
            notice.contains("not hung"),
            "the reported failure was reading the silence as a hang and killing it: {notice}"
        );
    }

    /// The item label is built from the `security` argv, so it has to survive
    /// every shape that argv takes — including the calls that name no item.
    #[cfg(target_os = "macos")]
    #[test]
    fn describe_item_names_the_keychain_item_from_the_argv() {
        assert_eq!(
            describe_item(&["find-generic-password", "-s", "car", "-a", "token", "-w"]),
            "car/token"
        );
        assert_eq!(
            describe_item(&["delete-generic-password", "-s", "car"]),
            "car"
        );
        assert_eq!(
            describe_item(&["find-generic-password", "-a", "token"]),
            "token"
        );
        // Not item-scoped: naming the subcommand still beats naming nothing.
        assert_eq!(describe_item(&["unlock-keychain"]), "unlock-keychain");
        assert_eq!(describe_item(&[]), "security");
        // A flag in final position has no value after it — must not panic.
        assert_eq!(
            describe_item(&["find-generic-password", "-s"]),
            "find-generic-password"
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_delete_uses_security_cli_and_maps_results() {
        let r = SecretRef::new("svc", "key");
        let cli = FakeSecurityCli::new(vec![security_output(0, b"", b"")]);

        mac_delete_via_security_cli_with(&r, &cli).unwrap();
        assert_eq!(
            cli.calls(),
            vec![args(&["delete-generic-password", "-s", "svc", "-a", "key"])]
        );

        let cli = FakeSecurityCli::new(vec![security_output(
            SECURITY_ERR_SEC_ITEM_NOT_FOUND,
            b"",
            b"The specified item could not be found in the keychain.\n",
        )]);
        mac_delete_via_security_cli_with(&r, &cli).unwrap();

        let cli = FakeSecurityCli::new(vec![security_output(128, b"", b"auth denied\n")]);
        let err = mac_delete_via_security_cli_with(&r, &cli).unwrap_err();
        assert_access_denied_contains(err, "auth denied");
    }
}

#[cfg(all(test, target_os = "macos"))]
mod acl_repair_tests {
    use super::tests::*;
    use super::*;

    fn pw(value: &str) -> Vec<u8> {
        format!("password: \"{value}\"\n").into_bytes()
    }

    /// A ref unique to each test. The "attempted once per process" set is
    /// process-global by design, so tests sharing a key race for the single
    /// allowed attempt and whichever loses sees no repair at all.
    fn r(test: &str) -> SecretRef {
        SecretRef::new("ai.parslee.car".to_string(), format!("oauth-{test}"))
    }

    fn verb(call: &[String]) -> &str {
        call.first().map(|s| s.as_str()).unwrap_or("")
    }

    /// The whole point: a read that had to prompt rewrites the item so the next
    /// read does not. Anyone who signed in before v0.41.0 was otherwise
    /// prompted forever, because #689 fixed only writes.
    #[test]
    fn a_prompted_read_repairs_the_acl() {
        let cli = FakeSecurityCli::new(vec![
            security_output_prompted(0, Vec::new(), pw("tok")), // the read
            security_output(0, Vec::new(), Vec::new()),         // delete
            security_output(0, Vec::new(), Vec::new()),         // add -A
            security_output(0, Vec::new(), pw("tok")),          // verify
        ]);
        assert_eq!(
            mac_get_via_security_cli_with(&r("repairs"), &cli).unwrap(),
            "tok"
        );
        let calls = cli.calls();
        let verbs: Vec<&str> = calls.iter().map(|c| verb(c)).collect();
        assert_eq!(
            verbs,
            vec![
                "find-generic-password",
                "delete-generic-password",
                "add-generic-password",
                "find-generic-password"
            ]
        );
        let add = cli
            .calls()
            .into_iter()
            .find(|c| verb(c) == "add-generic-password")
            .unwrap();
        assert!(
            add.contains(&"-A".to_string()),
            "must write a permissive ACL: {add:?}"
        );
    }

    /// A silent read is already fine. Rewriting it would be a pointless
    /// keychain mutation on every single read.
    #[test]
    fn a_silent_read_is_left_alone() {
        let cli = FakeSecurityCli::new(vec![security_output(0, Vec::new(), pw("tok"))]);
        assert_eq!(
            mac_get_via_security_cli_with(&r("silent"), &cli).unwrap(),
            "tok"
        );
        assert_eq!(cli.calls().len(), 1, "no repair for an unprompted read");
    }

    /// If the add fails after the pre-delete already removed the item, the
    /// credential is GONE. Putting it back matters more than the ACL does.
    #[test]
    fn a_failed_add_puts_the_credential_back() {
        let cli = FakeSecurityCli::new(vec![
            security_output_prompted(0, Vec::new(), pw("tok")),
            security_output(0, Vec::new(), Vec::new()), // delete ok
            security_output(1, Vec::new(), b"boom".to_vec()), // add FAILS
            security_output(0, Vec::new(), Vec::new()), // rescue delete
            security_output(0, Vec::new(), Vec::new()), // rescue add
        ]);
        assert_eq!(
            mac_get_via_security_cli_with(&r("failed-add"), &cli).unwrap(),
            "tok"
        );
        let adds: Vec<Vec<String>> = cli
            .calls()
            .into_iter()
            .filter(|c| verb(c) == "add-generic-password")
            .collect();
        assert_eq!(
            adds.len(),
            2,
            "the value must be re-added after a failed add"
        );
        assert!(
            adds[1].contains(&"tok".to_string()),
            "and with the ORIGINAL value"
        );
    }

    /// The write reported success but the item does not read back as the value
    /// we had. Never leave a credential replaced by something else.
    #[test]
    fn a_mismatched_readback_rewrites_the_original_value() {
        let cli = FakeSecurityCli::new(vec![
            security_output_prompted(0, Vec::new(), pw("tok")),
            security_output(0, Vec::new(), Vec::new()), // delete
            security_output(0, Vec::new(), Vec::new()), // add "succeeds"
            security_output(0, Vec::new(), pw("WRONG")), // verify -> mismatch
            security_output(0, Vec::new(), Vec::new()), // rescue delete
            security_output(0, Vec::new(), Vec::new()), // rescue add
        ]);
        assert_eq!(
            mac_get_via_security_cli_with(&r("mismatch"), &cli).unwrap(),
            "tok"
        );
        let adds: Vec<Vec<String>> = cli
            .calls()
            .into_iter()
            .filter(|c| verb(c) == "add-generic-password")
            .collect();
        assert_eq!(adds.len(), 2, "a mismatch must be corrected");
        assert!(adds[1].contains(&"tok".to_string()));
    }

    /// One attempt per ref per process. If repair does not take, retrying on
    /// every read turns one bad dialog into an endless pair of them.
    #[test]
    fn repair_is_attempted_at_most_once_per_process() {
        let cli = FakeSecurityCli::new(vec![
            security_output_prompted(0, Vec::new(), pw("tok")),
            security_output(0, Vec::new(), Vec::new()),
            security_output(0, Vec::new(), Vec::new()),
            security_output(0, Vec::new(), pw("tok")),
            security_output_prompted(0, Vec::new(), pw("tok")), // second read, still prompts
        ]);
        assert_eq!(
            mac_get_via_security_cli_with(&r("once"), &cli).unwrap(),
            "tok"
        );
        let after_first = cli.calls().len();
        assert_eq!(
            mac_get_via_security_cli_with(&r("once"), &cli).unwrap(),
            "tok"
        );
        assert_eq!(
            cli.calls().len(),
            after_first + 1,
            "the second prompted read must not repair again"
        );
    }

    /// A read that legitimately returns empty must not be written back — that
    /// would overwrite the item with nothing.
    #[test]
    fn an_empty_value_is_never_written_back() {
        let cli = FakeSecurityCli::new(vec![security_output_prompted(
            0,
            Vec::new(),
            b"password: \n".to_vec(),
        )]);
        assert_eq!(
            mac_get_via_security_cli_with(&r("empty"), &cli).unwrap(),
            ""
        );
        assert_eq!(cli.calls().len(), 1, "no repair for an empty value");
    }

    /// A failed repair must never turn a working read into an error.
    #[test]
    fn repair_failure_does_not_fail_the_read() {
        let cli = FakeSecurityCli::new(vec![
            security_output_prompted(0, Vec::new(), pw("tok")),
            security_output(1, Vec::new(), b"nope".to_vec()),
            security_output(1, Vec::new(), b"nope".to_vec()),
            security_output(1, Vec::new(), b"nope".to_vec()),
            security_output(1, Vec::new(), b"nope".to_vec()),
        ]);
        assert_eq!(
            mac_get_via_security_cli_with(&r("failure"), &cli).unwrap(),
            "tok",
            "the caller's read succeeded; repair is best-effort"
        );
    }
}