2d6bdae70b
Land the Vault ACL policies and an idempotent apply script. 18 policies:
service-{forgejo,woodpecker}, bot-{dev,review,gardener,architect,planner,
predictor,supervisor,vault,dev-qwen}, runner-{GITHUB,CODEBERG,CLAWHUB,
NPM,DOCKER_HUB}_TOKEN + runner-DEPLOY_KEY, and dispatcher.
tools/vault-apply-policies.sh diffs each file against the on-server
policy text before calling hvault_policy_apply, reporting created /
updated / unchanged per file. --dry-run prints planned names + SHA256
and makes no Vault calls.
vault/policies/AGENTS.md documents the naming convention (service-/
bot-/runner-/dispatcher), the KV path each policy grants, the rationale
for one-policy-per-runner-secret (AD-006 least-privilege at dispatch
time), and what lands in later S2.* issues (#880-#884).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3.4 KiB
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
- 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.
- Run
tools/vault-apply-policies.sh --dry-runto confirm the new basename appears in the planned-work list with the expected SHA. - Run
tools/vault-apply-policies.shagainst a Vault instance to create it; re-run to confirm it reportsunchanged. - The CI fmt + validate step lands in S2.6 (#884). Until then
vault policy fmt <file>locally is the fastest sanity check.
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. - CI policy fmt + validate + roles.yaml check. That's S2.6 (#884).