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//! Platform-native backends are selected at compile time via the
26//! `keyring` crate's feature flags:
27//!
28//! | Platform | Default backend | Persistence |
29//! | :--- | :--- | :--- |
30//! | macOS | Keychain (`apple-native`) | Cross-session |
31//! | Windows | Credential Manager (`windows-native`) | Cross-session |
32//! | Linux | Kernel keyutils (`linux-native`) | **Session-scoped** |
33//!
34//! On Linux the default is session-scoped because enabling the
35//! freedesktop Secret Service backend pulls in `libdbus-sys`, which
36//! requires `pkg-config` + `libdbus-1-dev` on the build host.
37//! Downstream tools that need reboot-persistent Linux storage enable
38//! the `credentials-linux-persistent` feature on `rtb` (or
39//! `linux-persistent` on `rtb-credentials` directly).
40//!
41//! See `docs/development/specs/2026-04-22-rtb-credentials-v0.1.md`
42//! for the authoritative contract.
43
44#![forbid(unsafe_code)]
45
46pub mod bearing;
47pub mod error;
48pub mod reference;
49pub mod resolver;
50pub mod store;
51
52pub use bearing::CredentialBearing;
53pub use error::CredentialError;
54pub use reference::{CredentialRef, KeychainRef};
55pub use resolver::{ResolutionOutcome, ResolutionSource, Resolver};
56pub use secrecy::{ExposeSecret, SecretString};
57pub use store::{CredentialStore, EnvStore, KeyringStore, LiteralStore, MemoryStore};