Vault format
A .murk file is a single JSON document. Every field is plaintext except the encrypted values, the per-grant agents blobs and one encrypted meta blob. This page walks through the structure conceptually. See SPEC.md on GitHub for the exact field-by-field schema.
The plaintext header
Section titled “The plaintext header”version:MAJOR.MINORorMAJOR.MINOR.PATCHin decimal with no leading zeros, with major2or3. murk writes3.0. It rejects any other major version on load and accepts newer minor versions. A2.xvault still loads and becomes3.0on its next save. murk 0.13 and older refuse a3.xvault as an unsupported version.created,vault_name,repo: descriptive metadata about the vault. In a3.xvault the MAC and the signature cover them.vault_id,generation(optional): the vault’s identity and a save counter.vault_idis 32 lowercase hex characters, random for a vault made bymurk init. A vault written by 0.13 has none, and the first 0.14 save derives one from itscreatedtimestamp and name, so teammates who upgrade separately agree on it.generationgoes up on every save. Both are covered by the MAC and the signature, and each machine checks them against its trust pin, so another vault’s file or an older revision is refused. Two vaults copied from one 0.13 vault share an id, so for them only the counter check applies. They are omitted when unset. See Trusting a signer.recipients: the list of authorized public keys (age, SSH, or hardware-plugin), and nothing else. No names or emails live here. See Recipients & signatures for where those go and why.schema: one entry per key name, with adescriptionand optionalexampleandtags, plus optional lifecycle fields (created,updated,rotation_interval_days,expires_at,revoked_at) thatmurk doctorandmurk rotate --listuse to flag overdue or expiring credentials. This is public and readable without a key: it’s whatmurk infoandmurk lsshow. Without a key nothing checks it, so those commands print awarn unverified headerline. Key names must be valid shell identifiers.policy(optional): an agent allow-tag list. It lives in the plaintext header, at the same trust level as the recipient list, specifically so it’s readable without a key. See Grants.sig(optional): the signature over the rest of the file: the signer, the signed-view version, and a base64 Ed25519 signature. It covers every other field, the encrypted meta included, and makes tampering by a repo-writer attributable. It is omitted when the last writer couldn’t sign. Vaults written before 3.0 carried a view-1 signature inside the meta instead.
Encrypted secret values
Section titled “Encrypted secret values”Each key in secrets carries up to three ciphertext fields, one age blob per tier:
shared: encrypted to every recipient except agent grants (theeveryonegroup). Empty ("") when the secret has no shared value, because its base tier is a named group or it has only private values.scoped: a map of recipient pubkey → ciphertext, one entry per recipient with a private value (--group me). The field kept its old name for compatibility with vaults written before the tier was renamed. Each agent grant also has its entries here.grouped: a map of group name → ciphertext, for secrets whose base tier is a named group rather thaneveryone.
A secret has at most one base tier: shared or a single grouped entry. Assigning it to a named group drops any existing shared value. A secret can also have only a private value, with an empty shared and no grouped entry. A private value overrides the base value on export. Because age determines readability from the ciphertext’s recipients, a non-member of a group can’t decrypt its grouped entry. There’s no separate access check.
A top-level agents map (optional) maps each grant pubkey to an age blob encrypted to that grant only. The blob holds the grant’s own record: its name, scope, issue and expiry times, issuer, and the signer keys it trusts (its anchors, plain recipient keys). It holds no values and nothing else from the meta. It is omitted when the vault has no grants.
The encrypted meta blob
Section titled “The encrypted meta blob”meta is a single age blob, encrypted to every recipient except agent grants, holding everything that shouldn’t be visible in the plaintext header:
recipients: the only place public keys are mapped to display names.groups: group name → member pubkeys, kept out of the header so org structure (who’s in which group) doesn’t leak to a non-recipient.grants: the agent grant registry (ephemeral pubkey, scope, TTL, issuer, trusted-signer anchors), kept out of the header so grant names, TTLs and issuers don’t leak. The agent’s pubkey is still a plaintext recipient, and itsscopedentries on the secrets show which secrets it can read. See Grants.mac/mac_key: the keyed integrity hash covering the vault’s contents, including the header identity fields (vault_name,repo,created,vault_idandgeneration), and the key used to compute it.signers(age keys only): the signer registry, mapping each age signer’s recipient to the base64 Ed25519 verifying key it signs with. That key can’t be computed from theage1...recipient, so the writer records it on every save, and a loader believes an entry only as Recipients & signatures describes.ssh-ed25519keys are never listed: the recipient string is the verifying key.github_pins: GitHub username to the SHA-256 fingerprints of the keys fetched when you authorizedgithub:USER, used to detect changed keys.
The mechanics of the MAC and signatures (what they protect against and what they don’t) are covered in Recipients & signatures.
The signature
Section titled “The signature”sig is a top-level field, outside the meta, so the file alone can be verified. It holds the signer’s pubkey, the signed-view version (2) and an Ed25519 signature over the whole file with sig left out: every header field, the agents and secrets ciphertexts, and the meta ciphertext. It is omitted when the last writer’s identity can’t sign.
Validation on load
Section titled “Validation on load”A .murk file arrives through git, so murk treats it as untrusted input. Before it uses a vault, murk rejects files over 64 MiB and checks every field against an allowlist: the version, RFC 3339 timestamps, key and group names, public keys, base64 ciphertexts, and free text without control characters. After it decrypts meta, it checks the meta fields the same way. The first failure rejects the whole vault, and the error names the field. murk runs the same checks before it writes a vault. SPEC.md lists the rules.
Illustrative skeleton
Section titled “Illustrative skeleton”{ "version": "3.0", "created": "2026-01-01T00:00:00Z", "vault_name": ".murk", "vault_id": "0123456789abcdef0123456789abcdef", "generation": 12, "recipients": ["age1abc...", "age1xyz..."], "schema": { "DATABASE_URL": { "description": "postgres connection string" } }, "policy": { "agent_allow_tags": ["agents"] }, "secrets": { "DATABASE_URL": { "shared": "<age ciphertext>", "scoped": { "age1xyz...": "<age ciphertext>" } } }, "meta": "<age ciphertext: recipients, groups, grants, mac, signers, github_pins>", "sig": { "signer": "age1abc...", "v": 2, "sig": "<base64 Ed25519 signature>" }}All ciphertext is base64-encoded age output. policy, agents, scoped and grouped appear only when the vault uses them. murk writes the newest MAC version on every save, so an older vault upgrades on its next write. The bytes change on every save, because murk generates a fresh mac_key and re-encrypts the meta.