support age plugin identities for hardware-backed keys

Cargo.toml

@@ -23,7 +23,7 @@ name = "murk"
 path = "src/main.rs"
 
 [dependencies]
-age = { version = "0.11.2", features = ["ssh"] }
+age = { version = "0.11.2", features = ["ssh", "plugin", "cli-common"] }
 ureq = "3"
 base64 = "0.22.1"
 bech32 = "0.11.1"

README.md

@@ -251,12 +251,47 @@ See [SPEC.md](SPEC.md) for the full specification.
 
 **Key storage** — your secret key lives in `~/.config/murk/keys/` with `chmod 600` permissions, outside your repository. The `.env` file in your project contains only a `MURK_KEY_FILE` reference to this path, not the key itself. Similar to SSH keys in `~/.ssh`, but murk also exposes secrets via `export` and `exec` into subprocess environments. If a machine is compromised, rotate your key and re-authorize with a new one.
 
+**Hardware-backed keys** — for stronger protection, point `MURK_KEY_FILE` at an age plugin identity file (YubiKey, Apple Secure Enclave, FIDO2, etc.) so the private key lives in hardware and never exists as bytes on disk. See [hardware identities](#hardware-identities) below.
+
 **Access control is advisory** — any authorized recipient can decrypt all shared secrets. Per-key access metadata in the schema is cosmetic and not enforced cryptographically. If a recipient has `MURK_KEY` and is in the recipient list, they can read everything in the shared layer. Use scoped secrets (motes) for values that should stay private to one recipient.
 
 See [THREAT_MODEL.md](THREAT_MODEL.md) for the full threat model.
 
 **AI agents** — if you're using murk with AI coding agents, see [docs/ai-agents.md](docs/ai-agents.md) for safe patterns.
 
+## Hardware identities
+
+By default `murk init` generates a raw age key and stores it under `~/.config/murk/keys/`. That's fine for development, but the key lives on disk as plaintext — anyone with read access to the file can decrypt everything.
+
+For production use, point `MURK_KEY_FILE` at an [age plugin identity file](https://github.com/FiloSottile/age#plugins) so the private key lives in tamper-resistant hardware and only consents to decrypt with a physical action (touch, Touch ID, PIN):
+
+| Hardware | Plugin |
+| --- | --- |
+| YubiKey, Nitrokey, any PIV-capable smart card | [`age-plugin-yubikey`](https://github.com/str4d/age-plugin-yubikey) |
+| Apple Secure Enclave (Touch ID) | [`age-plugin-se`](https://github.com/remko/age-plugin-se) |
+| Any FIDO2 security key | [`age-plugin-fido2-hmac`](https://github.com/olastor/age-plugin-fido2-hmac) |
+| OpenPGP Card | [`age-plugin-openpgp-card`](https://crates.io/crates/age-plugin-openpgp-card) |
+
+Example setup with a YubiKey:
+
+```bash
+# Install the plugin, then generate an identity bound to the YubiKey
+brew install age-plugin-yubikey
+age-plugin-yubikey --generate > ~/.config/murk/yubikey.txt
+
+# Point murk at the identity file
+echo 'export MURK_KEY_FILE=~/.config/murk/yubikey.txt' >> .env
+
+# Authorize the YubiKey's public key on your vault
+murk authorize $(grep 'public key' ~/.config/murk/yubikey.txt | awk '{print $NF}')
+```
+
+The identity file contains a `# public key: age1yubikey1...` header followed by an `AGE-PLUGIN-YUBIKEY-1...` pointer. murk reads the pubkey from the header (no plugin call needed for scoped secret lookup) and invokes the plugin only when actually decrypting — at which point the YubiKey prompts you to tap it.
+
+**No BIP39 recovery for hardware identities.** The whole point of hardware-backed keys is that the raw key bytes never leave the device, so there are no bytes to encode as a recovery phrase. Instead, enroll a second hardware device at setup and add both pubkeys as recipients (`murk authorize <backup-pubkey>`) — if you lose one, the backup still decrypts.
+
+**`MURK_KEY` vs `MURK_KEY_FILE`.** Setting `MURK_KEY` to a raw `AGE-SECRET-KEY-1...` string in `.env` works, but the key is then plaintext on disk. Prefer `MURK_KEY_FILE` pointing at either a file under `~/.config/murk/keys/` (convenience) or a hardware-backed plugin identity file (strongly recommended for production).
+
 ## License
 
 MIT OR Apache-2.0

SPEC.md

@@ -35,12 +35,25 @@ Existing secrets tools are either too complex (SOPS, Vault), tied to a runtime (
 
 | Variable       | Required | Description                                             |
 | -------------- | -------- | ------------------------------------------------------- |
-| `MURK_KEY`     | No       | Your age private key. Inline alternative to `MURK_KEY_FILE`. Takes priority if both are set. |
-| `MURK_KEY_FILE`| Yes      | Path to a file containing your age private key. Set by `murk init`. |
+| `MURK_KEY`     | No       | Raw age private key (`AGE-SECRET-KEY-1...`). Dev-mode convenience — the key is plaintext on disk. |
+| `MURK_KEY_FILE`| Yes      | Path to a private key file. Set by `murk init`. May be a raw age key, an SSH PEM key, or an age plugin identity file with a `# public key: age1...` header. |
 | `MURK_VAULT`   | No       | Vault filename. Defaults to `.murk`.                    |
 
 Your identity is your key. murk derives your public key from `MURK_KEY` or `MURK_KEY_FILE` to determine which scoped secrets are yours and to identify you in the recipient list.
 
+### Hardware-backed identities
+
+When `MURK_KEY_FILE` points at an age plugin identity file, murk uses the hardware-backed key without ever seeing the raw bytes. The file format is:
+
+```
+# public key: age1yubikey1qwt50d05nh5vutpdzmlg5wn80xq5negm8cn9ss4xswuaalgb5wh5ug3pcs3
+AGE-PLUGIN-YUBIKEY-1Q9WFTQQVZN3FASCJ3N9WEHUMFCYMCQSA2F8YVRMMGY6N76C6DMC6A8FTMP
+```
+
+The `# public key:` header is required — murk reads it to determine the recipient without spawning the plugin. The `AGE-PLUGIN-<NAME>-1...` line is the opaque pointer the plugin binary understands. On decrypt, murk invokes `age-plugin-<name>` (which must be on `$PATH`) and the plugin may prompt the user for physical consent (touch, PIN). Plugin identities have no BIP39 recovery phrase; `murk recover` errors on them. Back up a second hardware device as a vault recipient instead.
+
+Setting `MURK_KEY` (the inline env var) to an `AGE-PLUGIN-...` string is rejected — bare plugin identities don't carry the recipient pubkey, so murk can't resolve scoped secrets without spawning the plugin. Use a file path via `MURK_KEY_FILE`.
+
 ### Key storage
 
 `murk init` writes the secret key to `~/.config/murk/keys/<vault-hash>` (chmod 600) and writes a `MURK_KEY_FILE` reference to `.env`: