disinto/vault/policies/AGENTS.md

vault/policies/ — Agent Instructions

HashiCorp Vault ACL policies for the disinto factory. One .hcl file per policy; the basename (minus .hcl) is the Vault policy name applied to it. Synced into Vault by tools/vault-apply-policies.sh (idempotent — see the script header for the contract).

This directory is part of the Nomad+Vault migration (Step 2) — see issues #879–#884. Policies attach to Nomad jobs via workload identity in S2.4; this PR only lands the files + apply script.

Naming convention

Prefix	Audience	KV scope
service-<name>.hcl	Long-running platform services (forgejo, woodpecker)	kv/data/disinto/shared/<name>/*
bot-<name>.hcl	Per-agent jobs (dev, review, gardener, …)	kv/data/disinto/bots/<name>/* + shared forge URL
runner-<TOKEN>.hcl	Per-secret policy for vault-runner ephemeral dispatch	exactly one kv/data/disinto/runner/<TOKEN> path
dispatcher.hcl	Long-running edge dispatcher	kv/data/disinto/runner/* + kv/data/disinto/shared/ops-repo/*

The KV mount name kv/ is the convention this migration uses (mounted as KV v2). Vault addresses KV v2 data at kv/data/<path> and metadata at kv/metadata/<path> — policies that need list always target the metadata path; reads target data.

Policy → KV path summary

Policy	Reads
service-forgejo	kv/data/disinto/shared/forgejo/*
service-woodpecker	kv/data/disinto/shared/woodpecker/*
bot-<role> (dev, review, gardener, architect, planner, predictor, supervisor, vault, dev-qwen)	kv/data/disinto/bots/<role>/* + kv/data/disinto/shared/forge/*
runner-<TOKEN> (GITHUB_TOKEN, CODEBERG_TOKEN, CLAWHUB_TOKEN, DEPLOY_KEY, NPM_TOKEN, DOCKER_HUB_TOKEN)	kv/data/disinto/runner/<TOKEN> (exactly one)
dispatcher	kv/data/disinto/runner/* + kv/data/disinto/shared/ops-repo/*

Why one policy per runner secret

vault-runner (Step 5) reads each action TOML's secrets = [...] list and composes only those runner-<NAME> policies onto the per-dispatch ephemeral token. Wildcards or batched policies would hand the runner more secrets than the action declared — defeats AD-006 (least-privilege per external action). Adding a new declarable secret = adding one new runner-<NAME>.hcl here + extending the SECRETS allow-list in vault-action validation.

Adding a new policy

1. Drop a file matching one of the four naming patterns above. Use an existing file in the same family as the template — comment header, capability list, and KV path layout should match the family.
2. Run vault policy fmt -write <file> to ensure consistent formatting.
3. Run vault policy validate <file> locally to check syntax + semantics.
4. Run tools/vault-apply-policies.sh --dry-run to confirm the new basename appears in the planned-work list with the expected SHA.
5. Run tools/vault-apply-policies.sh against a Vault instance to create it; re-run to confirm it reports unchanged.

Policy lifecycle

Adding a new policy is a three-step process:

1. Add policy HCL — Drop a file in vault/policies/ matching one of the naming patterns. Run vault policy fmt <file> locally to ensure consistent formatting.
2. Update roles.yaml — Add a JWT auth role in vault/roles.yaml that references the new policy name (basename without .hcl).
3. Attach to Nomad job — In S2.4, add the policy to a jobspec's template { vault { policies = ["<policy-name>"] } } stanza.

CI enforces:

• vault policy fmt -check — all .hcl files must be formatted
• vault policy validate — syntax + semantic check (no unknown stanzas, valid capabilities)
• roles.yaml validator — each role must reference a policy that exists in vault/policies/
• secret-scan gate — no literal secrets in policy files (rare but dangerous copy-paste mistake)

Common failure modes

Symptom	Cause	Fix
vault policy fmt -check fails	HCL not formatted (wrong indentation, trailing spaces)	Run vault policy fmt -write <file>
vault policy validate fails	Unknown stanza, invalid capability, missing required field	Check Vault docs; valid capabilities: read, list, create, update, delete, sudo
roles.yaml validator fails	Policy name in role doesn't match any .hcl basename	Ensure policy name = filename without .hcl
secret-scan fails	Literal secret value embedded (e.g., token = "abc123...")	Use env var reference ($TOKEN) or sops/age-encrypted secret

What this directory does NOT own

• Attaching policies to Nomad jobs. That's S2.4 (#882) via the jobspec template { vault { policies = […] } } stanza.
• Enabling JWT auth + Nomad workload identity roles. That's S2.3 (#881).
• Writing the secret values themselves. That's S2.2 (#880) via tools/vault-import.sh.