rtb_credentials/lib.rs
1//! OS-keychain-backed credential store, with precedence-aware
2//! resolution via [`Resolver`].
3//!
4//! # Precedence
5//!
6//! Downstream tools declare credentials via [`CredentialRef`] and
7//! call [`Resolver::resolve`] to fetch the underlying secret. The
8//! canonical chain is `env > keychain > literal > fallback_env`:
9//!
10//! 1. **Environment variable** — `cref.env` points at the var name.
11//! 2. **OS keychain** — `cref.keychain` holds service/account.
12//! 3. **Literal** — `cref.literal` is the secret itself. Rejected
13//! under `CI=true` to avoid secrets landing in CI logs.
14//! 4. **Fallback env** — `cref.fallback_env` is an
15//! ecosystem-default (`ANTHROPIC_API_KEY`, etc.).
16//!
17//! # Secrets never cross untyped boundaries
18//!
19//! Every public function that touches a secret uses
20//! [`secrecy::SecretString`]: `Debug` renders `[REDACTED]`; memory is
21//! zeroed on drop.
22//!
23//! # Backends
24//!
25//! [`KeyringStore`] uses the platform's own credential store, chosen at
26//! compile time for the target:
27//!
28//! | Platform | Backend | Persistence |
29//! | :--- | :--- | :--- |
30//! | macOS | Keychain | Cross-session |
31//! | Windows | Credential Manager | Cross-session |
32//! | Linux and other Unix | freedesktop Secret Service (D-Bus) | Cross-session |
33//!
34//! The Secret Service needs a D-Bus session bus and a running provider
35//! such as GNOME Keyring or KDE Wallet; without them every keychain call
36//! returns [`CredentialError::Keychain`]. The client library, libdbus,
37//! is compiled from source and linked statically, so the build host
38//! needs a C compiler for the target but no D-Bus packages. The
39//! `linux-persistent` feature is retained for compatibility and has no
40//! effect.
41//!
42//! See the [rtb-credentials v0.1 spec](https://gitlab.com/phpboyscout/rust-tool-base/-/wikis/specs/0005-rtb-credentials-v0.1)
43//! for the authoritative contract.
44
45#![forbid(unsafe_code)]
46
47pub mod bearing;
48pub mod error;
49pub mod reference;
50pub mod resolver;
51pub mod store;
52
53pub use bearing::CredentialBearing;
54pub use error::CredentialError;
55pub use reference::{CredentialRef, KeychainRef};
56pub use resolver::{ResolutionOutcome, ResolutionSource, Resolver};
57pub use secrecy::{ExposeSecret, SecretString};
58pub use store::{CredentialStore, EnvStore, KeyringStore, LiteralStore, MemoryStore};