Skip to main content

Module keychain

leviath_sys

Module keychain 

Source
Expand description

The OS credential store: macOS Keychain, Windows Credential Manager, and the Secret Service on other Unixes.

This is the only place in the workspace that talks to a platform credential store. Callers work in terms of an account string and get plain Result<_, String> back; which OS facility answers, and whether one exists at all, is entirely this module’s problem.

§Platforms without a credential store

There are two separate ways this can be unavailable, and both are ordinary rather than exceptional:

  1. Not built in. The keychain feature is on by default but can be turned off - for a target the keyring crate does not support, or for a minimal build that should not link platform credential libraries at all. With it off, is_supported is false and every operation returns a plain “not supported in this build” error.
  2. Built in, but nothing to talk to. A headless Linux box with no Secret Service running, a locked keychain, a container, an SSH session with no session keyring. The code is present, the platform simply has no store.

Neither is treated as a crash or a panic, and neither is silently swallowed. Leviath’s default credential backend is its own 0600 files precisely because these situations are common; the keychain is opt-in, so an unavailable one costs a clear error at startup and nothing else.

§Why the split into raw_* and interpret_*

The functions that touch the OS are deliberately branch-free delegation, and every decision about what a result means lives in a pure function beside them. That is what makes this module testable: no CI runner has an unlocked login keychain, and a test that reached a developer’s real one would raise an OS authorization prompt and hang. Tests install an in-memory store as the process default and drive this same code, unchanged, all the way down.

Functions§

delete
Remove account, reporting whether anything was actually removed.
get
The secret stored for account, or None when there is none.
is_supported
Whether this build can talk to an OS credential store at all.
probe
Check that a usable credential store exists, without storing anything.
set
Store secret under account, replacing anything already there.