Module sanctuary_keychain 

OS-keychain-held pepper for the Sanctuary vault (T1.2 — optional second factor).

When a vault is keychain-wrapped, its PBKDF2 input is peppered with a 32-byte secret held in the platform keychain (Windows Credential Manager / macOS Keychain / Linux Secret Service). Disk + a guessed or weak PIN alone can then no longer open the vault — the machine’s keychain is also required.

Recovery model (why this is opt-in / off by default). Losing the keychain entry — OS reinstall, moving to a new machine, credential-store reset — makes the vault unopenable unless the one-time recovery code (the hex pepper handed back when wrapping is enabled) is supplied. Enabling wrapping is therefore a deliberate, recovery-aware choice; the default vault is unwrapped and unchanged.

This module owns only the keychain I/O. The pepper-mixing itself lives in the vault layer (qualia-client-core::wellfair::sanctuary_vault) and is hermetically testable without touching the real OS keychain.

Functions

delete_pepper

Remove the pepper for vault_id (idempotent — a missing entry is not an error).

generate_pepper

Generate a fresh 32-byte pepper from the OS CSPRNG.

get_pepper

Read the pepper for vault_id. Ok(None) means no entry exists on this device (the caller then falls back to the recovery code).

store_pepper

Store (or overwrite) the pepper for vault_id in the OS keychain.