Module secrets 

At-rest encryption of secrets in config.toml (GAP-009 / R-SECRETS-DEFAULT).

Primary-key resolution order (32 bytes), 0.5.1:

1. CLI flags (--secrets-key-file, --use-keyring, --allow-plaintext-secrets)
2. Env (deprecated): SSH_CLI_SECRETS_KEY, SSH_CLI_SECRETS_KEY_FILE, SSH_CLI_USE_KEYRING
3. OS keyring when enabled (service=ssh-cli, user=secrets-primary-key; legacy read alias)
4. XDG secrets.key file (next to config.toml), auto-created on first write

Opt-out: --allow-plaintext-secrets or deprecated SSH_CLI_ALLOW_PLAINTEXT_SECRETS=1.

With a key: serialization writes sshcli-enc:v1:<base64(nonce||ciphertext)>.

Never log or return the key or plaintext in public errors.

Structs

SecretsStatus

Secrets mode report (no sensitive material).

Enums

KeySource

Primary-key source (without exposing material).

Constants

ENC_PREFIX

Prefix for encrypted blobs in TOML.

KEY_FILE_NAME

File name of the primary key in the config directory.

Functions

auto_key_created

Returns true if a key was auto-created (non-consuming).

deserialize_secret

Deserializes from TOML: decrypts sshcli-enc:v1: blobs; otherwise returns as-is.

ensure_key_for_write

Ensures a key for write: loads existing or auto-creates secrets.key (unless plaintext opt-out).

generate_hex_key

Generates 32 random bytes as 64 hex chars.

init_primary_key

Initializes primary-key in XDG file or keyring. Never prints the key.

is_encrypted_blob

True if the string is already an encrypted blob.

load_primary_key

Resolves primary key and source (does not auto-create).

plaintext_allowed

True if plaintext opt-out is active (CLI flag first, then deprecated env).

secrets_config_dir

Config directory used for secrets.key (override > SSH_CLI_HOME > XDG).

secrets_key_path

Canonical path of the local primary-key file.

secrets_status

Current status (without loading material into logs).

serialize_secret

Serializes a secret for TOML: encrypts if a key exists (or is auto-created); otherwise plaintext.

set_config_dir

Sets the config directory used to resolve secrets.key (one-shot; called from dispatch).

set_runtime_flags

Applies one-shot CLI flags for secrets resolution (GAP-AUD-006).

take_auto_key_created

Returns true once if a key was auto-created since the last flag reset (consume).

write_key_file

Writes hex key to file with 0o600 (when supported).

write_key_to_keyring

Stores primary-key (hex) in the OS keyring. Does not print the key.