# 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.

```toml
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

[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.

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.
