IronStorage/docs/configuration.md

Configuration

IronStorage uses one small TOML file. Pass an explicit file with --config PATH; otherwise the CLI loads ironstorage/config.toml below the native per-user configuration directory:

• Linux and other Unix systems: $XDG_CONFIG_HOME, when it is absolute, or $HOME/.config;
• macOS: $HOME/Library/Application Support;
• Windows: %APPDATA%.

An explicit relative configuration path is resolved from the process current directory. Relative vault and key_material paths inside the file are resolved from the directory containing the resolved configuration file. Absolute paths remain absolute. . and .. components are normalized lexically; ~ is not expanded. The vault may be absent before init, but an existing vault must be a directory. Exported key material must already exist as a regular file or directory.

vault = "../vault"
default_key = "0123456789ABCDEF0123456789ABCDEF01234567"
key_material = "keys"

# An array avoids shell interpretation. A quoted command string is also
# accepted and split without launching a shell.
editor = ["code", "--wait"]

# Optional; upstream pass defaults to 45 seconds. Values are limited to 1..300.
clipboard_timeout_seconds = 45

# Optional; interactive frontends default to a two-minute inactivity lease.
[security]
inactivity_timeout_seconds = 120
biometric_unlock_enabled = false

# Optional iPhone appearance: "system", "light", or "dark".
[ui]
mobile_appearance = "system"

[git]
user_name = "Alice Example"
user_email = "alice@example.test"

[[git.remotes]]
name = "origin"
url = "https://git.example.test/alice/password-store.git"
server_id = "personal-git"
application_id = "ironstorage-cli"

default_key is the required identity that the embedded OpenPGP layer resolves against the exported key material. It may be a full fingerprint, key ID, or exact user ID; ambiguity and key capability checks happen in the key resolver.

Editor selection is deterministic: TOML, $VISUAL, $EDITOR, then vim. Commands are split into an executable and argument vector and are never passed through a shell. Only the CLI edit adapter may eventually launch this configured editor.

git.user_name and git.user_email set the author for commits created by IronStorage. Both must be present together and cannot contain line breaks or angle brackets. The built-in IronStorage identity is used when both are absent.

HTTPS remote URLs containing user information, passwords, queries, or fragments are rejected. server_id and application_id are opaque HTTPS-only references used to retrieve credentials from the operating-system secret store; duplicate names and duplicate reference pairs are errors. The HTTPS account name is stored inside the protected credential record, not in TOML. OpenPGP passphrases are addressed by the resolved primary fingerprint.

SSH remotes use either ssh://[user@]host[:port]/path or scp-like [user@]host:path syntax and omit the HTTPS credential fields. They select exactly one private-key file or one already-running SSH-agent identity:

[[git.remotes]]
name = "origin"
url = "git@git.example.test:alice/password-store.git"
ssh_identity_file = "keys/id_ed25519"
ssh_known_hosts_file = "known_hosts"

Relative paths are resolved against config.toml. If ssh_known_hosts_file is omitted, ~/.ssh/known_hosts is used. Agent authentication replaces ssh_identity_file with an exact SHA-256 fingerprint and may name a socket explicitly:

ssh_agent_fingerprint = "SHA256:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU"
ssh_agent_socket = "/run/user/1000/ssh-agent.socket"

Private-key passphrases are stored by fingerprint in the operating-system secret store and never appear in TOML. IronStorage does not read OpenSSH configuration, try additional keys, prompt for passwords or keyboard-interactive authentication, launch an agent, or invoke proxy/helper commands. In builds with the ssh feature, the same configuration drives branch discovery, clone, fetch, and pull over the embedded upload-pack channel; push and full pull-then-push synchronization use the matching embedded receive-pack channel.

The typed endpoint model is always available so an SSH remote remains readable through the Rust API even when the binary was built without SSH. Such a build returns a typed unsupported-transport error before connection or repository mutation. The optional storage ssh feature contains russh 0.63.1 and Tokio; russh default features are disabled and the Ring backend plus RSA key support are selected explicitly.

For SSH, URI paths are absolute, scp-like paths without a leading slash are relative to the remote account, and ~/~user paths retain tilde-expansion semantics. Bracketed IPv6 and explicit URI ports are accepted. Host names are IDNA-normalized, repository paths may contain Unicode, and usernames are restricted to ASCII letters, digits, ., _, and -. Empty paths, control bytes, credentials, queries, fragments, ambiguous unbracketed IPv6 or colon paths, leading-option paths, local paths, URL rewrites, separate push URLs, helper transports, and unknown schemes fail closed.

Server identity is checked before authentication against the configured known-hosts file. Exact, hashed, and non-default-port host entries are supported. Unknown keys return their host, algorithm, and SHA-256 fingerprint for explicit confirmation; confirming appends the key atomically. A changed key is a hard failure and is never replaced by that confirmation API.

clipboard_timeout_seconds controls the native clipboard presentation lease. It defaults to 45 seconds for upstream pass compatibility and must be between 1 and 300 seconds. The CLI remains alive for the lease so Linux can serve its selection and every platform can restore or clear the value reliably without a background helper process.

security.inactivity_timeout_seconds controls the shared authentication lease used by interactive frontends. It defaults to 120 seconds and accepts values from 1 second through 24 hours. The storage crate owns deadline calculation and relock; frontends report only genuine input events as user activity. Repaints, timers, background refresh, and Git work never extend the lease.

security.biometric_unlock_enabled records only whether biometric unlock is enabled; the GPG passphrase remains in protected system storage. ui.mobile_appearance is shared, secret-free iPhone presentation state and defaults to the system appearance.

Passwords, passphrases, tokens, credentials, private keys, and other secret values are forbidden in TOML. Unknown fields are rejected. Parse errors never echo the source line or value, so an accidentally supplied secret is not repeated in diagnostics.