The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
docs(vault): key storage, migration, threat model and plugin isolation
Tekniumebbe67e878e0
diff --git a/website/docs/user-guide/features/credential-vault.md b/website/docs/user-guide/features/credential-vault.mdindex 4802f698d2e..5887db8a64d 100644--- a/website/docs/user-guide/features/credential-vault.md+++ b/website/docs/user-guide/features/credential-vault.md@@ -83,12 +83,58 @@ cannot spend. Address fills need no confirmation.- **Desktop → Settings → Passwords & Logins**: everything saved, the detectedpassword managers with Unlock/Lock, Add, Remove.- **CLI**: `hermes vault list`, `hermes vault add`, `hermes vault rm <handle>`,- `hermes vault sources`.+ `hermes vault sources`, `hermes vault key`.-Items live encrypted under `~/.hermes/vault/` (Fernet key + vault file, both-`0600`), scoped to the profile. Labels, site origins and login identifiers are-visible metadata; passwords and card values never leave the vault except into-the page.+Items live encrypted under `~/.hermes/vault/`, scoped to the profile. Labels,+site origins and login identifiers are visible metadata; passwords and card+values never leave the vault except into the page.++## Where the vault key is kept++By default the encryption key sits in `~/.hermes/vault/vault.key` (`0600`),+next to the encrypted `vault.json.enc`. You can keep it in your operating+system's keychain instead (macOS Keychain, Windows Credential Manager, the+Secret Service / KWallet on Linux):++```bash+hermes vault key # where the key is now, and whether a keychain is reachable+hermes vault key migrate --to keychain # move it (installs the small `keychain` feature if needed)+hermes vault key migrate --to file # move it back+```++The move writes the key to the keychain, checks that the keychain copy decrypts+your vault, and only then deletes `vault.key`, so an interrupted move leaves a+working vault and running the command again finishes it. It also sets+`vault.key_storage`, which decides where a **new** vault's key goes:++```yaml+vault:+ key_storage: file # default; or: keychain+```++With `keychain` and no reachable keychain (a headless Linux server, an SSH+session without a desktop keyring), a new vault's key goes to `vault.key` as+before, with a warning in the log. Each profile gets its own keychain entry,+named in `~/.hermes/vault/vault.keyref` (which holds no secret). A cloned or+renamed profile switches to an entry of its own the first time it opens its+vault, and never deletes the entry it was copied from.++What changes in keychain mode:++- **Backups and copies hold the vault without its key.** `hermes backup`, a+ synced or copied `~/.hermes`, or a disk image no longer carries everything+ needed to open the vault. Before moving a profile to another machine, run+ `hermes vault key migrate --to file`.+- **The keychain may ask.** macOS can ask whether Hermes may use the entry+ (for example after an update replaces Hermes' Python), and a locked Linux+ keyring asks to be unlocked. Cron jobs that run while you are logged out+ cannot read the key, so their local logins fail with a clear error.+- **A lost entry means lost items.** If the keychain entry is deleted, the+ vault cannot be opened and Hermes says so instead of creating a new key over+ it. Restore the entry from a keychain backup, or delete `vault.json.enc` to+ start over.++That is why keychain storage is opt-in rather than the default.## Headless sessions@@ -121,3 +167,28 @@ site, that site (and any script it runs) has it, exactly as when you type ityourself. On a cloud browser backend the vendor's browser sees the page like anyother. The origin binding is the guard against filling on the wrong site, notagainst a compromised right one.++### Who can get at the vault++| Who | `vault.key` file (default) | Keychain storage |+|---|---|---|+| Other users on this computer (not administrators) | Blocked: both files are `0600` | Blocked |+| Someone with a backup, sync copy or image of `~/.hermes` | Can decrypt: key and vault travel together | Gets ciphertext only |+| Someone with the powered-off disk and no full-disk encryption | Can decrypt | Needs your login keychain password |+| A program running as you, or a plugin running inside Hermes | Can decrypt | Can still ask the keychain, or call the vault code directly |+| An administrator / root, or malware with your privileges | Can decrypt | Can decrypt |++Password-manager session tokens (1Password, Bitwarden) stay in Hermes' memory+only, are dropped after 30 idle minutes or on Lock, and are handed only to the+single `op`/`bw` command that needs them, never to Hermes' own environment, the+terminal tool or any other child process. They are kept out of reach of a plain+import, which stops casual access by other code in the process, but not a+plugin determined to read Hermes' memory.++Plugins are the boundary that matters: a third-party plugin that runs inside+the Hermes process can do anything Hermes can, including filling a saved login.+If you save logins and install plugins you have not reviewed, run them out of+process with [`plugins.isolation: host`](plugins.md#running-plugins-out-of-process-pluginsisolation).+A plugin host still runs as your user and can read files you can read, so for+a hard boundary give it a sandbox with `plugins.host.launcher`.+