Module credentials 

Secure credential storage module

Provides secure storage for access tokens using:

• Primary: System keyring (Secret Service on Linux, Keychain on macOS)
• Fallback: AES-256-GCM encrypted file when keyring unavailable

The fallback is obfuscation at rest, not a secret: its key sits in a file beside the ciphertext, so anyone who can read one can read the other. It exists so headless systems keep working, and the keyring remains the only place a token is actually protected.

The key used to be derived from the hostname, $USER and a hardcoded salt. That was no more secret — those are readable by anyone who can read the file — and it was unstable: renaming the machine, or launching from a context where $USER is unset, changed the key and made every stored token undecryptable. load_credentials_file treats a failed decrypt as “no stored credentials”, so that surfaced as being silently signed out rather than as an error. The key is now random and persisted, and the old derivation is kept only to migrate a file written before this change.

TRACES: UR-012 | IR-014

Structs

CredentialStore

Credential storage manager

Enums

CredentialError

Error types for credential operations

CredentialResult

Result of a credential storage operation

Constants

CREDENTIALS_FILENAME 🔒

KEY_FILENAME 🔒

Key file for the encrypted-file fallback, beside the credentials it opens.

SERVICE_NAME 🔒

Functions

decrypt_with 🔒

Decrypt encrypted with key.

encrypt_with 🔒

Encrypt plaintext with key, prepending a fresh random nonce.

load_or_create_key 🔒

Load the fallback encryption key, creating it on first use.

restrict_to_owner 🔒

Make a key file owner-readable only. Best effort — a filesystem without Unix permissions is not a reason to fail.