Skip to content

Permissions matrix

Who can run which vault command. Each row is a command and each column a role; yes means murk runs it, no means it refuses and leaves the vault file unchanged, and conflict (merge driver only) means it stops with a merge conflict, so git commits nothing. An allowed read shows only the values that role can read, and an allowed write never gives anyone read access to a value that the command doesn’t name. tests/auth_matrix.rs checks every cell against the real binary.

The rows run against one fixture vault:

  • SHARED: shared with everyone. The override owner also has a private (--group me) value for it.
  • OPS: held by the group ops.
  • PRIV: only the override owner’s private value.
  • AGENT_OK: shared with everyone, and the scope of the agent grants.
  • Every key carries the tag agents, which the agent policy allows.
  • spare is a recipient in ops that commands act on. idle is a group with no secrets, whose members are the owner and the group member. X is a key that isn’t on the vault yet.

A cell marked with a number was decided where the policy left it open; the notes below the table give the reason. A cell marked current records what murk does today on a question that is still open; see Under review.

  • owner: created the vault with murk init; a member of group ops.
  • member: an ordinary recipient in no group.
  • group member: a recipient in group ops.
  • group non-member: a recipient outside group ops.
  • override owner: a recipient with personal (--group me) values: an override of SHARED and all of PRIV.
  • grant: an agent grant key scoped to AGENT_OK, with MURK_AGENT unset.
  • grant + MURK_AGENT: the same grant key with MURK_AGENT=1.
  • expired grant: a grant key for AGENT_OK past its TTL.
  • revoked: a recipient removed with circle revoke (no rotation).
  • outsider: a key that was never on the vault.
Command owner member group member group non-member override owner grant grant + MURK_AGENT expired grant revoked outsider
get SHARED yes yes yes yes yes no no no no no
get OPS yes no yes no no no no no no no
get PRIV no no no no yes no no no no no
get AGENT_OK yes yes yes yes yes yes yes no no no
export yes yes yes yes yes yes (1) yes (1) no no no
exec -- env yes yes yes yes yes yes (1) yes (1) no no no
agent exec --only AGENT_OK -- env no (2) no (2) no (2) no (2) no (2) yes yes no no no
agent exec --only SHARED -- env no (2) no (2) no (2) no (2) no (2) no no no no no
agent exec --allow-operator-key --only SHARED -- env yes yes yes yes yes no no no no no
mcp (murk_get AGENT_OK) no (3) no (3) no (3) no (3) no (3) no (3) yes no no no
diff --show-values yes yes yes yes yes no (4) no (4) no no no
verify yes yes yes yes yes yes (5) yes (5) no no no
scan yes yes yes yes yes yes (1) yes (1) no no no
ls yes yes yes yes yes yes (6) yes (6) yes (6) yes (6) yes (6)
info yes yes yes yes yes yes (6) yes (6) yes (6) yes (6) yes (6)
circle yes yes yes yes yes yes (6) yes (6) yes (6) yes (6) yes (6)
policy show yes yes yes yes yes yes (6) yes (6) yes (6) yes (6) yes (6)
rotate --list --json yes yes yes yes yes yes (7) yes (7) no (7) no (7) no (7)
skeleton -o FILE yes yes yes yes yes yes (6) yes (6) yes (6) yes (6) yes (6)
agent plan -o FILE yes yes yes yes yes yes (6) yes (6) yes (6) yes (6) yes (6)
group ls yes yes yes yes yes yes (5) yes (5) no no no
agent ls yes yes yes yes yes yes (5) yes (5) no no no
add NEW yes yes yes yes yes no no no no no
add NEW --group everyone yes yes yes yes yes no no no no no
add NEW --group ops yes no yes no no no no no no no
add NEW --group me yes yes yes yes yes no no no no no
add SHARED yes yes yes yes yes no no no no no
add OPS yes no yes no no no no no no no
add OPS --group me yes yes yes yes yes no no no no no
add PRIV no (8) no (8) no (8) no (8) yes no no no no no
add OPS --group everyone yes no yes no no no no no no no
generate NEW yes yes yes yes yes no no no no no
generate OPS yes no yes no no no no no no no
rm SHARED yes yes yes yes yes no no no no no
rm OPS yes no (9) yes no (9) no (9) no no no no no
describe SHARED yes yes yes yes yes no no no no no
describe OPS yes no (10) yes no (10) no (10) no no no no no
import FILE (new keys) yes yes yes yes yes no no no no no
import --force FILE (OPS) yes no yes no no no no no no no
edit SHARED yes yes yes yes yes no no no no no
edit AGENT_OK (in the grant's scope) yes yes yes yes yes no no no no no
edit OPS --group ops yes no yes no no no no no no no
rotate SHARED --generate yes yes yes yes yes no no no no no
rotate AGENT_OK --generate (in the grant's scope) yes yes yes yes yes no no no no no
rotate PRIV --generate no (8) no (8) no (8) no (8) yes no no no no no
rotate OPS --generate yes no yes no no no no no no no
rotate --all (piped values) no (11) no (11) no (11) no (11) no (11) no no no no no
rotate --all --values-from FILE (shared keys) yes yes yes yes yes no no no no no
rotate OPS --values-from FILE yes no yes no no no no no no no
circle authorize X yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
circle authorize X --group ops yes no yes no no no no no no no
circle revoke owner (the creator) no (12) yes (current) yes (current) yes (current) yes (current) no no no no no
circle revoke spare yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
circle revoke spare --rotate (piped values) yes (current) no (11) yes (current) no (11) no (11) no no no no no
circle revoke spare --rotate --values-from FILE yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
group create NEWG yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
group add ops --member member yes no yes no no no no no no no
group rm ops --member spare yes no yes no no no no no no no
group rm idle (delete) yes no yes no no no no no no no
policy set --allow-tag other yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
policy clear yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
agent grant --only SHARED yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
agent init --only AGENT_OK yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
agent revoke bot yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
agent revoke bot --rotate (piped value) yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
agent connect claude --only AGENT_OK yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
agent disconnect claude --rotate --name bot yes (current) yes (current) yes (current) yes (current) yes (current) no no no no no
merge-driver BASE OURS THEIRS yes yes yes yes yes no no no conflict (13) conflict (13)
  1. a read bounded to the grant’s scope, the same as export.
  2. agent exec is for agent grant keys; a recipient’s own key needs --allow-operator-key, an explicit operator decision (docs/ai-agents.md: rules).
  3. murk mcp serves only a grant key in agent context (docs/ai-agents.md: serving secrets over MCP).
  4. a grant can’t read the meta, so it can’t verify the git revision diff compares against, and nothing unverified is shown.
  5. a grant is not a meta recipient, so these commands run but reveal no recipient names, groups or other grants, and no value outside its scope (THREAT_MODEL: agent grants).
  6. reads only the plaintext header and schema, which are public by design (SPEC: header is public, values are private).
  7. rotate --list loads and verifies the vault before trusting its rotation schedule, so it needs a key that can load the vault (SPEC: header reads).
  8. the key holds only another recipient’s personal value: there is no tier the caller could keep, and murk never picks a wider one.
  9. deleting a group value is the most destructive overwrite, so a non-member can’t do it.
  10. only a group member can change a group key, its schema included, as with rm.
  11. piped values are matched by position, so a batch that would skip a value the caller can’t rotate (another group’s value, or another recipient’s override) refuses before writing.
  12. revoking your own key would lock the writer out mid-command, so murk asks another recipient to do it.
  13. a key that can’t read both sides’ meta can’t rebuild the integrity metadata, so the driver reports a conflict and git keeps the merge out of history.

The cells marked current show what murk does today, not a settled rule. Whether every recipient should be able to run these commands is an open product question. The test checks today’s behaviour so that any change is deliberate: if murk gains an admin role, these cells change in the table.

How it works today: murk has no admin role. Every recipient except agent grants can add and remove recipients, manage groups, set the policy and mint grants. Group-only and personal values stay protected from recipients outside the group. Changes are attributable through vault signatures (keys that cannot sign, such as hardware keys, rely on signed git commits).

Every row runs on Linux, macOS and Windows except edit SHARED and edit AGENT_OK (in the grant's scope) and edit OPS --group ops, which run on Linux and macOS only: the test drives $EDITOR with an sh script, which murk runs through sh only on Unix.

  • init: creates a vault and key; on an existing vault it only reports whether your key is a recipient and never rewrites the vault, whoever runs it.
  • env: writes .envrc, not the vault.
  • doctor: reads repo files and the public schema with no key.
  • recover / restore: work on the key, not the vault.
  • setup-merge-driver / completion: configure git and the shell.
  • authorize / revoke: hidden aliases of circle authorize / circle revoke, which share their code.
  • Node and Python bindings: need a native build and run under Node or Python, outside cargo test, so this matrix can’t drive them; their own suites cover grant and policy checks.