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.

Git remotes are HTTPS-only. URLs containing user information, passwords, queries, or fragments are rejected. server_id and application_id are opaque 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.

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.