pitboard-core 0.15.0

//! Reading and writing credentials, both a tool's live one and Pitboard's parked ones.
//!
//! Which store holds what is decided by the tool and by the machine: a tool's own module
//! builds its live chain, and [`crate::host::Host`] says what this machine has. What is
//! here holds on every machine: the chain rules, and the stores that are only files.

mod file;
pub(crate) mod folder;
#[cfg(any(test, feature = "test-support"))]
pub(crate) mod memory;
// macOS parks in the login keychain; Linux in files, and Windows in files sealed to the account.
#[cfg(any(target_os = "linux", windows, test))]
pub(crate) mod vault;

pub(crate) use file::PlainFile;

use crate::context::Context;
use crate::service::Permit;

use serde_json::Value;
use std::path::PathBuf;

// `Keychain` occurs only where the machine has one, so callers need no checks of their own.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum Backend {
    #[cfg_attr(not(target_os = "macos"), allow(dead_code))]
    Keychain,
    File,
    // Files only this Windows account can open: Pitboard's parks there.
    #[cfg_attr(not(windows), allow(dead_code))]
    SealedFile,
    // Windows' store of generic credentials, where Claude Code keeps its login once its store
    // there is on (`windows_backend_choice`).
    CredentialManager,
    Absent,
    // A store Pitboard does not read: Claude Code's on Windows where a login sits in Credential
    // Manager though nothing Pitboard reads turns that store on.
    Unknown,
}

impl Backend {
    pub(crate) fn name(self) -> &'static str {
        match self {
            Backend::Keychain => "keychain",
            Backend::File => "file",
            Backend::SealedFile => "sealed_file",
            Backend::CredentialManager => "credential_manager",
            Backend::Absent => "absent",
            Backend::Unknown => "unknown",
        }
    }
}

// A store Pitboard does not read or write, such as Claude Code's on Windows where a login sits
// in Credential Manager that nothing turns on: every call answers `error`, which no caller takes
// for a store with nothing in it.
pub(crate) struct Refused {
    kind: Backend,
    error: Error,
}

impl Refused {
    pub(crate) fn new(kind: Backend, error: Error) -> Refused {
        Refused { kind, error }
    }

    fn refused<T>(&self) -> Result<T, Error> {
        Err(self.error.clone())
    }
}

impl RawStore for Refused {
    fn kind(&self) -> Backend {
        self.kind
    }

    fn contains(&self, _service: &str) -> Result<bool, Error> {
        self.refused()
    }

    fn read(&self, _service: &str) -> Result<Option<String>, Error> {
        self.refused()
    }

    fn write(&self, _: Permit, _service: &str, _contents: &str) -> Result<(), Error> {
        self.refused()
    }

    fn delete(&self, _: Permit, _service: &str) -> Result<(), Error> {
        self.refused()
    }

    fn list(&self) -> Result<Option<Vec<String>>, Error> {
        self.refused()
    }
}

/// Why a locked keychain stops Pitboard, and what to do, wherever a failure says why.
pub(crate) const LOCKED: &str = "the keychain is locked and cannot ask to be unlocked from \
                                 here; unlock it with `security unlock-keychain`, or run \
                                 Pitboard from a desktop session";

// `ERROR_NO_SUCH_LOGON_SESSION`: a network logon has no credential set (MC-net, measured over
// sshd on windows-2025).
const UNREACHABLE: &str = "Credential Manager cannot be reached from this logon, as in a sign-in \
                           over SSH with a key; run Pitboard from a desktop session";

pub(crate) fn locked(os: crate::host::Os) -> &'static str {
    match os {
        crate::host::Os::MacOs | crate::host::Os::Linux => LOCKED,
        crate::host::Os::Windows => UNREACHABLE,
    }
}

#[derive(Debug, Clone, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// The store could not be interrogated. Never treat this as "no credential".
    #[error("the credential store could not be read: {0}")]
    Unreadable(String),
    /// The keychain is locked and cannot ask to be unlocked from where this runs, as over
    /// SSH, or Credential Manager cannot be reached from this logon. Never "no credential"
    /// either, and nothing is wrong with what it holds.
    #[error("the credential store could not be read: {}", locked(crate::host::OS))]
    Locked,
    /// A write of a login kept in several items stopped partway, and what they hold cannot be
    /// read until a whole login is written over them. Never "no credential" either.
    #[error("the credential store could not be read: {0}")]
    Unfinished(String),
    /// A park sealed to this account is there but does not open in this logon: an
    /// administrator's password reset, a profile restored on another PC, or a logon without
    /// the user's key, as over SSH. `code` is `CryptUnprotectData`'s, where there was one.
    #[error("the sealed credential does not open in this logon: {detail}")]
    Sealed { code: Option<i32>, detail: String },
    #[error("the stored credential is not valid JSON: {0}")]
    Malformed(String),
    #[error("writing the credential failed: {0}")]
    Write(String),
    #[error("the credential did not survive the write: {0}")]
    NotDurable(String),
}

impl Error {
    pub fn code(&self) -> &'static str {
        match self {
            Error::Unreadable(_) | Error::Unfinished(_) => "credential_store_unreadable",
            Error::Locked => "credential_store_locked",
            Error::Sealed { .. } => "credential_sealed",
            Error::Malformed(_) => "credential_not_json",
            Error::Write(_) => "credential_write_failed",
            Error::NotDurable(_) => "credential_not_durable",
        }
    }

    /// A credential that is present but unreadable as JSON means Claude Code's format
    /// moved under us, which is a different answer from a write that simply failed.
    pub fn exit_code(&self) -> u8 {
        match self {
            Error::Malformed(_) => 3,
            _ => 1,
        }
    }
}

/// What writing a document costs a store that has a ceiling, and what happens above it.
///
/// One value rather than three questions. Asking separately meant hex-encoding the same
/// login three times per switch, and meant every caller knowing that only one platform has
/// a ceiling at all.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct Cost {
    /// Bytes this document needs of the store's cheapest route.
    pub(crate) needs: usize,
    /// Bytes that route has.
    pub(crate) limit: usize,
    /// Whether the store has another route above the ceiling, and is allowed to use it.
    pub(crate) second_route: bool,
}

impl Cost {
    /// Past the cheapest route.
    pub(crate) fn over(self) -> bool {
        self.needs > self.limit
    }

    /// Past it, and written the more visible way rather than refused.
    pub(crate) fn on_the_second_route(self) -> bool {
        self.over() && self.second_route
    }

    /// Past it with nothing left to try.
    pub(crate) fn refused(self) -> bool {
        self.over() && !self.second_route
    }
}

/// One credential store. `write` must read its result back and return `Ok` only if it
/// holds exactly what was written. Both changes take the [`Permit`] only the one gate
/// every change passes makes, so no login is written or deleted, in the keychain or in a
/// file, by a run that did not ask whether it may.
pub(crate) trait RawStore: Send + Sync {
    fn kind(&self) -> Backend;
    fn contains(&self, service: &str) -> Result<bool, Error>;
    fn read(&self, service: &str) -> Result<Option<String>, Error>;
    fn write(&self, permit: Permit, service: &str, contents: &str) -> Result<(), Error>;
    fn delete(&self, permit: Permit, service: &str) -> Result<(), Error>;

    /// Every name Pitboard put here, where the store can be asked. `None` where it cannot,
    /// which is what a store with no way to enumerate answers rather than an empty list:
    /// nothing found and nothing askable are different, and one of them means an item can
    /// be lost track of for good.
    fn list(&self) -> Result<Option<Vec<String>>, Error> {
        Ok(None)
    }

    /// What a write would cost against this store's ceiling. `None` where there is none,
    /// which is every store but the keychain and Credential Manager.
    fn cost(&self, _service: &str, _contents: &str) -> Option<Cost> {
        None
    }
}

fn vault(ctx: &Context) -> Box<dyn RawStore> {
    ctx.host().vault(ctx)
}

/// Only "not found" means absent. A permission error or a loop in the path says nothing about
/// what is there, and reading it as empty would tell the user to sign in again.
fn exists(path: &std::path::Path) -> Result<bool, Error> {
    path.try_exists()
        .map_err(|e| Error::Unreadable(format!("cannot look for {}: {e}", path.display())))
}

/// Where parked logins live when there is no keychain to put them in: one file each, in
/// Pitboard's own directory. Named here rather than in the backend so `doctor` can look at
/// what is actually on the disk without the two spellings drifting apart.
pub(crate) fn vault_dir(ctx: &Context) -> PathBuf {
    crate::home::dir(ctx).join("vault")
}

/// One tool's live credential chain, in the order that tool reads it.
///
/// Built by that tool's own module. Which backends can hold a login, and in what order, is
/// a fact about the tool: Claude Code looks in the keychain and then in a plaintext file it
/// demotes to, while Codex and Gemini have one file and nothing behind it.
pub(crate) struct Live {
    backends: Box<[Box<dyn RawStore>]>,
    takes_over: bool,
}

impl Live {
    pub(crate) fn of(backends: Vec<Box<dyn RawStore>>) -> Live {
        assert!(
            !backends.is_empty(),
            "a live chain with no backends can hold nothing"
        );
        Live {
            backends: backends.into_boxed_slice(),
            takes_over: false,
        }
    }

    // A chain whose first backend takes every write, and whose others lose the login where the
    // first held none before it: Claude Code's Credential Manager on Windows (`credman_migration`).
    pub(crate) fn taken_over_by_the_first(backends: Vec<Box<dyn RawStore>>) -> Live {
        Live {
            takes_over: true,
            ..Live::of(backends)
        }
    }

    fn refs(&self) -> Vec<&dyn RawStore> {
        self.backends.iter().map(Box::as_ref).collect()
    }
}

/// Which backend in `chain` holds `service`. The chain is a parameter so tests can pass
/// backends that fail on demand.
fn resolve_in<'a>(
    chain: &[&'a dyn RawStore],
    service: &str,
) -> Result<Option<&'a dyn RawStore>, Error> {
    for backend in chain {
        if backend.contains(service)? {
            return Ok(Some(*backend));
        }
    }
    Ok(None)
}

fn write_in(
    chain: &[&dyn RawStore],
    permit: Permit,
    service: &str,
    contents: &str,
) -> Result<(), Error> {
    let backend = resolve_in(chain, service)?.unwrap_or(chain[0]);
    backend.write(permit, service, contents)
}

// As Claude Code's fallback wrapper writes on Windows: the first backend whatever holds the
// login, then the rest deleted where the first held none, a failure to delete ignored as it
// ignores one. A failed first write moves nothing to the rest.
fn take_over_in(
    chain: &[&dyn RawStore],
    permit: Permit,
    service: &str,
    contents: &str,
) -> Result<(), Error> {
    let held = chain[0].contains(service)?;
    chain[0].write(permit, service, contents)?;
    crate::fault::point("store.taken_over");
    if !held {
        for rest in &chain[1..] {
            let _ = rest.delete(permit, service);
        }
    }
    Ok(())
}

fn with_live<T>(live: &Live, run: impl FnOnce(&[&dyn RawStore]) -> T) -> T {
    run(&live.refs())
}

/// Which backend holds a credential, or `Absent`.
///
/// Settled in 2.1.278, which the earlier note here left open. Claude Code builds its live
/// chain as keychain-with-plaintext-fallback and the successor backend ("storageV5", gated
/// on `tengu_hover_rest`) does not change that: it replaces what backs the fallback half,
/// and only for a caller that hands a backend in. An ordinary `claude` hands none in, so
/// the fallback stays `<storage dir>/.credentials.json` and the keychain stays first. The
/// order below is therefore the order Claude Code reads in, not a guess.
///
/// One divergence, on purpose. Claude Code demotes to the plaintext file when a keychain
/// write fails for good, and deletes the keychain item when it does; from 2.1.281 a locked
/// keychain whose item the process has seen is not failing for good. Pitboard never
/// demotes: see the note on `write_in`.
pub(crate) fn resolve(live: &Live, service: &str) -> Result<Backend, Error> {
    with_live(live, |chain| {
        Ok(resolve_in(chain, service)?.map_or(Backend::Absent, RawStore::kind))
    })
}

/// The nearest backend after the one in `chain` holding `service` that holds it too, by its
/// own look. The chain is a parameter so tests can pass backends that fail on demand.
fn behind_in<'a>(
    chain: &[&'a dyn RawStore],
    service: &str,
) -> Result<Option<&'a dyn RawStore>, Error> {
    let mut in_use = false;
    for backend in chain {
        if !in_use {
            in_use = backend.contains(service)?;
        } else if backend.contains(service)? {
            return Ok(Some(*backend));
        }
    }
    Ok(None)
}

/// The backend after the one holding the login in use that holds something under `service`
/// too, a login or not: what a reader that cannot reach that backend signs in with instead,
/// and what no write to it reaches. A backend is behind wherever its own look says it is
/// there, so a file is behind holding `{}`, nothing at all, or what cannot be read, as a file
/// that is not text or that this user may not read: reading it then gives the error. `None`
/// where the login in use is in the last backend, or nowhere.
pub(crate) fn behind<'a>(live: &'a Live, service: &str) -> Result<Option<&'a dyn RawStore>, Error> {
    behind_in(&live.refs(), service)
}

/// The backend in `live` holding `service`, the one a read takes it from.
pub(crate) fn holder<'a>(live: &'a Live, service: &str) -> Result<Option<&'a dyn RawStore>, Error> {
    resolve_in(&live.refs(), service)
}

/// The backend in `live` of the kind [`Backend::name`] calls `kind`.
pub(crate) fn of_kind<'a>(live: &'a Live, kind: &str) -> Option<&'a dyn RawStore> {
    live.refs()
        .into_iter()
        .find(|backend| backend.kind().name() == kind)
}

pub(crate) fn read_raw(live: &Live, service: &str) -> Result<Option<String>, Error> {
    with_live(live, |chain| match resolve_in(chain, service)? {
        Some(backend) => backend.read(service),
        None => Ok(None),
    })
}

pub(crate) fn read(live: &Live, service: &str) -> Result<Option<Value>, Error> {
    match read_raw(live, service)? {
        None => Ok(None),
        Some(raw) => serde_json::from_str(&raw)
            .map(Some)
            .map_err(|e| Error::Malformed(e.to_string())),
    }
}

/// Write the live credential where it already lives. A failed keychain write is never
/// answered by writing the plaintext file: that demotion is Claude Code's to make, and
/// making it here would move the user's token somewhere weaker without saying so.
pub(crate) fn write_raw(
    live: &Live,
    permit: Permit,
    service: &str,
    contents: &str,
) -> Result<(), Error> {
    with_live(live, |chain| {
        if live.takes_over {
            take_over_in(chain, permit, service, contents)
        } else {
            write_in(chain, permit, service, contents)
        }
    })
}

#[cfg_attr(not(feature = "test-support"), allow(unreachable_pub))]
pub fn vault_read(ctx: &Context, service: &str) -> Result<Option<String>, Error> {
    vault(ctx).read(service)
}

pub(crate) fn vault_write(
    ctx: &Context,
    permit: Permit,
    service: &str,
    contents: &str,
) -> Result<(), Error> {
    vault(ctx).write(permit, service, contents)
}

/// What writing `contents` into the vault would cost against its ceiling, where it has one.
pub(crate) fn vault_cost(ctx: &Context, service: &str, contents: &str) -> Option<Cost> {
    vault(ctx).cost(service, contents)
}

pub(crate) fn vault_delete(ctx: &Context, permit: Permit, service: &str) -> Result<(), Error> {
    vault(ctx).delete(permit, service)
}

/// Every parked login on this machine, asked of the store rather than read out of
/// Pitboard's own index. `None` where the store cannot be enumerated.
pub(crate) fn vault_list(ctx: &Context) -> Result<Option<Vec<String>>, Error> {
    vault(ctx).list()
}

/// Whether another `PITBOARD_HOME` could have parked a login where this one parks its own.
pub(crate) fn vault_is_shared(ctx: &Context) -> bool {
    ctx.host().vault_is_shared()
}

pub(crate) fn vault_kind(ctx: &Context) -> Backend {
    vault(ctx).kind()
}

/// What writing the live credential would cost, asked of the backend that would take the
/// write. A login living in the fallback file has no ceiling, and used to be told it had
/// the keychain's.
pub(crate) fn cost(live: &Live, service: &str, contents: &str) -> Option<Cost> {
    with_live(live, |chain| {
        let first = (!live.takes_over).then(|| resolve_in(chain, service).ok().flatten());
        first.flatten().unwrap_or(chain[0]).cost(service, contents)
    })
}

/// A handle for comparing and logging tokens without the secret leaving this process.
pub(crate) fn fingerprint(secret: &str) -> String {
    use sha2::{Digest, Sha256};
    hex::encode(&Sha256::digest(secret.as_bytes())[..8])
}

#[cfg(test)]
#[allow(
    clippy::disallowed_methods,
    reason = "a test sets up its scratch files as a person or a tool would"
)]
mod tests {
    use super::memory::{Fault, MemoryStore};
    use super::*;
    use std::sync::Arc;

    /// Breaking a real keychain on demand is neither safe nor deterministic, so the chain
    /// rules are proved against stores that fail when they are told to. The same stores are
    /// what the engine's own tests drive, through `Context::with_memory_stores`.
    fn store(kind: Backend) -> Arc<MemoryStore> {
        MemoryStore::of(kind)
    }

    fn holding(kind: Backend, service: &str, value: &str) -> Arc<MemoryStore> {
        let s = store(kind);
        s.plant(service, value);
        s
    }

    /// What the next backend after the one in use holds is what a reader that cannot reach
    /// that one gets instead. Nothing is behind a login that is in the last backend, or in
    /// none.
    #[test]
    fn what_is_behind_the_login_in_use_is_the_next_backend_that_holds_it() {
        let keychain = store(Backend::Keychain);
        let between = store(Backend::File);
        let plaintext = store(Backend::File);
        let chain: [&dyn RawStore; 3] = [&keychain, &between, &plaintext];
        let held = |chain: &[&dyn RawStore]| -> Option<String> {
            behind_in(chain, "svc")
                .unwrap()
                .map(|behind| behind.read("svc").unwrap().expect("there"))
        };
        assert_eq!(held(&chain), None);

        plaintext.plant("svc", "left");
        assert_eq!(
            held(&chain),
            None,
            "the file is the login when the keychain holds none"
        );

        keychain.plant("svc", "in use");
        assert_eq!(held(&chain).as_deref(), Some("left"));
        between.plant("svc", "nearer");
        assert_eq!(held(&chain).as_deref(), Some("nearer"));

        keychain.fault("svc", Fault::Locked);
        assert!(
            matches!(behind_in(&chain, "svc"), Err(Error::Locked)),
            "which backend is in use cannot be told, so neither can what is behind it"
        );
    }

    /// Claude Code tells a file behind the keychain by a look at it, not by reading it
    /// (`fallback_file_pins_session_login`), so neither does this. A file that is there and
    /// cannot be read is behind, with why it cannot be read, and not a chain that cannot be
    /// told. A real file, since what a look and a read each say of one is the point.
    #[test]
    fn a_file_that_cannot_be_read_is_still_behind() {
        let dir = std::env::temp_dir().join(format!(
            "pitboard-store-behind-{}-{:?}",
            std::process::id(),
            std::thread::current().id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        let path = dir.join(".credentials.json");
        std::fs::write(&path, [0xff, 0xfe, 0x00]).unwrap();
        let keychain = holding(Backend::Keychain, "svc", "in use");
        let file = PlainFile::at(path);
        let chain: [&dyn RawStore; 2] = [&keychain, &file];

        let behind = behind_in(&chain, "svc")
            .expect("which backend is in use is told")
            .expect("the file is behind")
            .read("svc");
        let _ = std::fs::remove_dir_all(&dir);
        assert!(matches!(behind, Err(Error::Unreadable(_))), "{behind:?}");
    }

    #[test]
    fn a_failed_keychain_write_never_falls_through_to_the_plaintext_file() {
        let keychain = holding(Backend::Keychain, "svc", "before");
        keychain.fault("svc", Fault::FailWrite("told to".into()));
        let plaintext = store(Backend::File);
        let chain: [&dyn RawStore; 2] = [&keychain, &plaintext];

        let result = write_in(&chain, Permit::for_a_test(), "svc", "after");

        assert!(matches!(result, Err(Error::Write(_))));
        assert_eq!(
            plaintext.read("svc").unwrap(),
            None,
            "demoting the credential to a plaintext file is Claude Code's decision, not ours"
        );
        assert_eq!(keychain.read("svc").unwrap().as_deref(), Some("before"));
    }

    // Claude Code's wrapper on Windows (`credman_migration`): the first store takes the write,
    // and a login it did not hold before leaves the file.
    #[test]
    fn a_chain_taken_over_writes_the_first_and_empties_the_rest_only_where_it_held_nothing() {
        let first = store(Backend::CredentialManager);
        let file = holding(Backend::File, "svc", "in the file");
        let live = |first: &Arc<MemoryStore>, file: &Arc<MemoryStore>| {
            Live::taken_over_by_the_first(vec![
                Box::new(Arc::clone(first)),
                Box::new(Arc::clone(file)),
            ])
        };
        write_raw(&live(&first, &file), Permit::for_a_test(), "svc", "moved").unwrap();
        assert_eq!(first.peek("svc").as_deref(), Some("moved"));
        assert_eq!(
            file.peek("svc"),
            None,
            "a login the first held none of leaves the file"
        );

        file.plant("svc", "left behind");
        write_raw(&live(&first, &file), Permit::for_a_test(), "svc", "again").unwrap();
        assert_eq!(first.peek("svc").as_deref(), Some("again"));
        assert_eq!(
            file.peek("svc").as_deref(),
            Some("left behind"),
            "Claude Code deletes no file behind a store that held a login"
        );

        let first = store(Backend::CredentialManager);
        first.fault("svc", Fault::FailWrite("unreachable".into()));
        first.takes_on_stdin(2560);
        let file = holding(Backend::File, "svc", "in the file");
        assert!(matches!(
            write_raw(&live(&first, &file), Permit::for_a_test(), "svc", "lost"),
            Err(Error::Write(_))
        ));
        assert_eq!(
            file.peek("svc").as_deref(),
            Some("in the file"),
            "a failed write moves nothing into the file and takes nothing out of it"
        );
        assert_eq!(
            cost(&live(&first, &file), "svc", "x"),
            Some(Cost {
                needs: 1,
                limit: 2560,
                second_route: true
            }),
            "the first store's ceiling, while the file holds the login"
        );
    }

    #[test]
    fn a_write_that_does_not_read_back_is_reported_rather_than_believed() {
        let keychain = holding(Backend::Keychain, "svc", "before");
        keychain.fault("svc", Fault::CorruptWrite("something else".into()));
        let chain: [&dyn RawStore; 1] = [&keychain];
        assert!(matches!(
            write_in(&chain, Permit::for_a_test(), "svc", "after"),
            Err(Error::NotDurable(_))
        ));
    }

    #[test]
    fn a_credential_already_in_the_file_backend_stays_there() {
        let keychain = store(Backend::Keychain);
        let plaintext = holding(Backend::File, "svc", "before");
        let chain: [&dyn RawStore; 2] = [&keychain, &plaintext];

        write_in(&chain, Permit::for_a_test(), "svc", "after").unwrap();

        assert_eq!(plaintext.read("svc").unwrap().as_deref(), Some("after"));
        assert_eq!(
            keychain.read("svc").unwrap(),
            None,
            "a credential must not be promoted behind Claude Code's back either"
        );
    }

    #[test]
    fn an_absent_credential_is_written_to_the_preferred_backend() {
        let keychain = store(Backend::Keychain);
        let plaintext = store(Backend::File);
        let chain: [&dyn RawStore; 2] = [&keychain, &plaintext];

        write_in(&chain, Permit::for_a_test(), "svc", "fresh").unwrap();

        assert_eq!(keychain.read("svc").unwrap().as_deref(), Some("fresh"));
        assert_eq!(plaintext.read("svc").unwrap(), None);
    }

    #[test]
    fn an_unreadable_backend_aborts_instead_of_looking_further_down_the_chain() {
        struct Broken;
        impl RawStore for Broken {
            fn kind(&self) -> Backend {
                Backend::Keychain
            }
            fn contains(&self, _: &str) -> Result<bool, Error> {
                Err(Error::Unreadable("security exited 1".into()))
            }
            fn read(&self, _: &str) -> Result<Option<String>, Error> {
                unreachable!()
            }
            fn write(&self, _: Permit, _: &str, _: &str) -> Result<(), Error> {
                unreachable!()
            }
            fn delete(&self, _: Permit, _: &str) -> Result<(), Error> {
                unreachable!()
            }
        }
        let plaintext = store(Backend::File);
        let chain: [&dyn RawStore; 2] = [&Broken, &plaintext];

        assert!(matches!(
            write_in(&chain, Permit::for_a_test(), "svc", "x"),
            Err(Error::Unreadable(_))
        ));
        assert_eq!(
            plaintext.read("svc").unwrap(),
            None,
            "could-not-tell must never be read as nothing-there"
        );
    }

    /// A store Pitboard does not read answers every call as one that cannot be read, saying
    /// why, and never as one with nothing in it; a chain of it alone resolves to that, never to
    /// absent.
    #[test]
    fn a_store_refused_cannot_be_read() {
        let store = Refused::new(Backend::Unknown, Error::Unreadable("not built yet".into()));
        let unreadable = |answer: Result<String, Error>| match answer {
            Err(Error::Unreadable(why)) => assert_eq!(why, "not built yet"),
            other => panic!("{other:?}"),
        };
        let permit = Permit::for_a_test();
        assert_eq!(store.kind(), Backend::Unknown);
        unreadable(store.contains("svc").map(|c| c.to_string()));
        unreadable(store.read("svc").map(|r| format!("{r:?}")));
        unreadable(store.write(permit, "svc", "x").map(|()| String::new()));
        unreadable(store.delete(permit, "svc").map(|()| String::new()));
        unreadable(store.list().map(|l| format!("{l:?}")));
        assert_eq!(store.cost("svc", "x"), None);
        let live = Live::of(vec![Box::new(Refused::new(
            Backend::Unknown,
            Error::Unreadable("not built yet".into()),
        ))]);
        unreadable(resolve(&live, "svc").map(|b| b.name().to_string()));
    }

    // Credential Manager out of a network logon's reach is no keychain locked (MC-net).
    #[test]
    fn a_store_out_of_reach_says_so_in_each_systems_words() {
        use crate::host::Os;
        assert_eq!(Error::Locked.code(), "credential_store_locked");
        assert_eq!(locked(Os::MacOs), LOCKED);
        assert_eq!(locked(Os::Linux), LOCKED);
        assert!(
            locked(Os::Windows).starts_with("Credential Manager cannot be reached from this logon")
        );
        assert!(!locked(Os::Windows).contains("keychain"));
    }

    #[test]
    fn fingerprints_are_short_stable_and_not_the_secret() {
        let fp = fingerprint("sk-ant-example");
        assert_eq!(fp.len(), 16);
        assert_eq!(fp, fingerprint("sk-ant-example"));
        assert_ne!(fp, fingerprint("sk-ant-example2"));
        assert!(!fp.contains("sk-ant"));
    }
}