rtb-credentials¶

Secret-handling layer for CLI tools: the CredentialStore async trait, four built-in stores, a Resolver that walks the canonical precedence chain, and CredentialRef — the deserialise-only config shape tool authors embed in their typed configs.

Secrets cross every boundary as secrecy::SecretString: Debug replaces the value with SecretBox<str>([REDACTED]), and memory is zeroed on drop. The crate treats &str/String for a secret as a type error, not a style preference.

Part of the phpboyscout Rust toolkit; extracted from — and battle-tested by — rust-tool-base.

Where to start¶

Storage modes¶

Three storage modes are supported:

Resolver walks all three in order, plus an ecosystem-default env-var fallback (ANTHROPIC_API_KEY, GITHUB_TOKEN, …). The chain is fixed in code and cannot be reordered, disabled or extended:

1. cref.env → std::env::var(name).
2. cref.keychain → store.get(service, account).
3. cref.literal — refused via CredentialError::LiteralRefusedInCi when CI is exactly true.
4. cref.fallback_env → std::env::var(name).

First hit wins. Two details that catch people out: a refused literal stops the walk rather than falling through to fallback_env, and a keychain error that is not a clean "not found" aborts the whole resolution. Both are covered in the resolver reference.

Public API¶

use rtb_credentials::{CredentialRef, CredentialStore, KeyringStore, Resolver};
use std::sync::Arc;

#[derive(serde::Deserialize)]
struct MyCfg {
    anthropic: CredentialRef,
}

let cfg: MyCfg = /* ... */;

let store: Arc<dyn CredentialStore> = Arc::new(KeyringStore::new());
let resolver = Resolver::new(store);

let api_key = resolver.resolve(&cfg.anthropic).await?;
use secrecy::ExposeSecret;
request.header("authorization", format!("Bearer {}", api_key.expose_secret()));

Full API reference: docs.rs/rtb-credentials.

Platform behaviour and the keychain opt-in¶

On Linux the default keyring backend is kernel keyutils (keyring/linux-native) — pure Rust, no system deps, session-scoped persistence. This keeps builds hermetic: no libdbus-1-dev / pkg-config required.

Tools that need reboot-persistent Linux storage enable the linux-persistent Cargo feature, which extends keyring with the freedesktop Secret Service (D-Bus) backend. Building with it requires pkg-config and libdbus-1-dev on the host.

macOS Keychain and Windows Credential Manager store cross-session by default; no feature flag needed.

There is no feature that removes keychain support. keyring and its macOS, Windows and Linux keyutils backends are compiled into every build; the only feature this crate has, linux-persistent, adds a backend. A build that must provably contain no keychain code cannot get there by turning a feature off — it has to not depend on rtb-credentials. See Cargo features.

Security¶

• #![forbid(unsafe_code)] at the crate root.
• Every public fn that touches a secret takes or returns SecretString.
• Debug of a SecretString replaces the value with SecretBox<str>([REDACTED]).
• CredentialRef cannot be serialised, so a blanket "save the config struct" cannot write a resolved secret to disk.
• Literal-in-CI refusal is a policy check, not a technical one — it is trivially overridden by setting CI to anything other than true, and tools wanting stricter enforcement set CI=true themselves. See why literal secrets are refused in CI.

What the crate does not protect: once expose_secret() has been called the returned &str is an ordinary string and can be logged like any other. Catching secrets that have already escaped into free-form text is a separate job — see why every secret is a SecretString.

Why it is built this way¶

Each of these has a page that makes the argument in full:

• Why the precedence chain is ordered this way — why an environment variable beats a stored keychain entry, why there are two environment legs at opposite ends of the chain, and why the order cannot be configured.
• Why every secret is a SecretString — what the type prevents that a String does not, and why it can be deserialised but never serialised.
• Why literal secrets are refused in CI — what the refusal protects against, and why detection is one exact string rather than anything cleverer.
• Why Linux keychain storage is session-scoped by default — the build-hermeticity trade behind choosing kernel keyutils, and what linux-persistent actually buys.

What this crate does not do¶

Worth reading before you design around it. The full list is on what this crate does not do; the ones that catch people most often:

• The resolution order cannot be changed. No key, builder or feature reorders it.
• A literal plus a fallback fails in CI rather than using the fallback, even when the fallback variable is set.
• A keychain backend error aborts resolution instead of falling through to lower-precedence sources. Only a clean "not found" continues the chain.
• KeyringStore requires Tokio specifically — it panics on any other async runtime.
• No caching, expiry, rotation or validation. The crate retrieves a stored static secret and nothing more.

Further reading¶

The blog carries a curated route through this subject: Rust, and what survived the port collects everything written about it, ordered so you can start at the beginning rather than newest-first.