Skip to content

The agent that grows with you

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.md
index 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 detected
password 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 it
yourself. On a cloud browser backend the vendor's browser sees the page like any
other. The origin binding is the guard against filling on the wrong site, not
against 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`.
+