coulomb/ops-mason
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(mason): scoped, named OpenBao sessions instead of borrowing yours

Browse source 
Handing an agent an operator session gives it everything you have, for
as long as you have it, and every action lands in the audit log as you.

scripts/bao-session.sh grant <task> mints a separate token into
~/.claude-bao-token — your ~/.vault-token is untouched and the two
revoke independently. 45 minutes, max one hour, display_name
claude-<task> so an audited action is attributable to a piece of work.

policies/ops-mason-build.hcl is what makes the scope real. It allows the
phase-2 survey (sys/mounts, sys/auth, policy list), policy and auth-role
creation, KV metadata reads, and short-lived test tokens for positive
and negative capability checks. It denies every read of */data/* on
platform, operators and secret.

That denial is the point: SCOPE.md says ops-mason never touches secret
values, and until now that was a promise kept by whoever was driving.
An explicit deny outranks any grant, including one added to this policy
later by mistake. The one time the line was crossed is recorded in
plans/state-hub-forge-derivation-read.md §8; under this policy it would
have been refused rather than recorded.

sys/mounts/* is deliberately absent — enabling a mount is a
railiance-platform act, and a grant that needed it should be recognised
as a broader thing rather than folded in here.

Also fixes the WSL2 login trap: bao login's browser launch fails under
gio, so the script prints the URL plainly instead of appearing to hang.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 3377672@bnt-lap001
Assistant-Session: 15463ccf-238f-4e13-b163-93aa25c6d166
This commit is contained in:
tegwick 2026-08-28 11:04:26 +02:00
parent 4c0ada21ca
commit f90644e8c0
3 changed files with 268 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

50
AGENTS.md
View file

@ -187,3 +187,53 @@ To create a new workplan:
1. Write the file following the format above
2. Run `statehub fix-consistency` locally; ask the operator only if the CLI or
State Hub API is unavailable.
## OpenBao Access — how to grant a session, and what it authorises
ops-mason builds in OpenBao, so it needs a session. Do not hand it your own
operator session: that gives everything you have, for as long as you have it,
and every action lands in the audit log as you.
```bash
./scripts/bao-session.sh status # what session exists, if any
./scripts/bao-session.sh login # refresh YOUR operator session (OIDC)
./scripts/bao-session.sh grant <task> # mint a scoped token for Claude
./scripts/bao-session.sh revoke # end it immediately
```
`grant` mints a **separate** token into `~/.claude-bao-token` — your own
`~/.vault-token` is untouched, and the two revoke independently. The agent uses
it as `BAO_TOKEN=$(cat ~/.claude-bao-token) bao <cmd>`.
### What the grant authorises
Policy `ops-mason-build` (`policies/ops-mason-build.hcl`), 45 minutes, max one
hour, named `claude-<task>`:
| Allowed | Denied |
|---|---|
| read `sys/mounts`, `sys/auth`, policy list — the phase-2 survey | **every read of `*/data/*`** on `platform`, `operators`, `secret` |
| create/update policies under `sys/policies/acl/*` | enabling or tuning mounts (`sys/mounts/*`) — a railiance-platform act |
| create/update `auth/kubernetes/role/*`, `auth/approle/role/*` | anything not listed |
| read KV **metadata** — versions and timestamps, enough to confirm a delivery landed | KV **values** |
| mint and revoke short-lived test tokens, check capabilities | |
The denial is the point. `SCOPE.md` says ops-mason never touches secret values;
this makes OpenBao enforce it rather than leaving it to whoever is driving. An
explicit `deny` outranks any grant, including one added to this policy later by
mistake.
### Choosing the task name
`grant <task>` sets `display_name=claude-<task>`, so the audit log attributes an
action to a piece of work rather than to a person. Use the workplan task where
there is one — `grant MASON-WP-0003-T02` — otherwise something a reader would
recognise later.
### When a broader grant is genuinely needed
Enabling a mount, reading a value, or touching another subsystem's paths is out
of `ops-mason-build` on purpose. Do not widen the policy to get past a refusal.
Either the act belongs to another repo, or it needs its own named policy and its
own decision — the way `operators/` did.