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

Charter ops-mason: builder of NetKingdom security infrastructure

Browse source 
INTENT.md establishes the four-phase process (construction plan ->
review/optimize -> executive summary -> build), grounded in ops-warden's
own charter: ops-warden explicitly disclaims being a builder/provisioner
("owns no secret store and vends nothing", routes provisioning
elsewhere) and states its own design principle that "the founder is
escalated to, never tasked with mechanics" -- ops-mason's executive
summary gate is that principle applied to the provisioning side, turning
today's ad hoc founder Red-lane bao commands into a reviewed, repeatable
process.

MASON-WP-0001 stands up the four phases and exercises the whole
pipeline on real, already-waiting demand: the rein-openweights OpenBao
AppRole that glas-harness/GLAS-WP-0002-T02 is blocked on.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-07-27 00:21:25 +02:00
parent c9608a4b93
commit dff106073b
4 changed files with 320 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.gitignore vendored Normal file
View file

@ -0,0 +1,5 @@
.venv/
__pycache__/
*.pyc
*.egg-info/
.pytest_cache/

196
INTENT.md Normal file
View file

@ -0,0 +1,196 @@
# INTENT
> This file captures **why this repository exists**, the **direction it is
> moving toward**, and the **kind of system it is meant to become**. It is
> intentionally aspirational and stable, not a description of current
> implementation.
---
## One-liner
**The builder of NetKingdom security infrastructure — creates, changes,
maintains, and tears down access routes, credentials, tokens, and policies
so that ops-warden always has something real to route to.**
---
## Why this exists
ops-warden is deliberately narrow: it issues short-lived SSH certificates and
**routes** every other credential need to the subsystem that owns it — it
"owns no secret store and vends nothing" (`ops-warden/wiki/AccessRouting.md`).
That's the right shape for a front door, but it leaves a real gap: **something
has to actually build the AppRole, the policy, the KV secret path, the
catalog entry** that ops-warden then points workers at. Today that gap is
filled ad hoc — a founder spends "~10 minutes" hand-running `bao write`
commands per new lane (see `binky-control/integrations/executor-worker-secrets.md`
for a representative example: a new AppRole, a new policy, delivered
role_id/secret_id files, a catalog entry, repeated by hand every time a new
consumer needs a credential).
ops-mason exists to turn that ad hoc founder mechanic into a **reviewed,
repeatable construction process** — so new security infrastructure gets
built consistently, against what already exists, with a human decision point
before anything is actually applied, instead of bespoke one-off provisioning
every time.
---
## The Mission
ops-mason **builds** NetKingdom security infrastructure — OpenBao AppRoles,
policies, KV secret paths, and their ops-warden catalog entries — as defined
by architecture documents (`net-kingdom`) and by real consumer demand (a
repo/workload that needs a credential lane). It does not decide *whether*
access should exist — that's an architecture or founder decision — it
figures out *how* to build what's already been decided on, and does the
build once approved.
### The four-phase process
1. **Construction plan.** Given an access demand (a consumer, a credential
type, a scope) and the concept behind it, draft what needs to be created,
changed, or torn down to satisfy it — respecting, extending, or compacting
existing structure rather than defaulting to "create something new" every
time. Check first: does an existing policy/path/lane already cover this
(the way `rein-aharness`'s mail-triage reuses the existing
`llm-connect-provider-secrets` lane instead of getting its own)? Does
satisfying this demand let two existing near-duplicate lanes be merged
instead of adding a third?
2. **Review and optimize.** Check the draft plan against what's already
provisioned (no redundant policies, no orphaned roles), consistency with
existing naming/TTL/scoping conventions, and ease of use for the
consumer. This is a self-review pass before a human ever sees the plan —
the plan that reaches phase 3 should already be the best version of
itself, not a first draft.
3. **Executive summary — the decision gate.** Render what the plan actually
grants: which roles get which access, to what, for how long, blast radius
if the credential leaks, and what it costs to reverse. This is the one
mandatory human checkpoint, and it exists for exactly the reason
ops-warden's own design principle names: *"the founder is escalated to,
never tasked with mechanics"* — ops-mason does the mechanical work in
phases 1, 2, and 4; phase 3 is the founder's one decision, made in policy
terms (approve, reject, or send back to phase 1 with feedback), not asked
to review raw `bao` commands.
4. **Build.** Once approved, execute the plan — create/modify/tear down the
AppRole, policy, secret path, and catalog entry. Not before phase 3
approval, ever, for anything that grants or widens access. (Tear-down of
something already flagged for removal, or a dry-run/plan-only mode, does
not require the same gate — see Design Principles.)
---
## Responsibility boundary
### ops-mason owns
- Drafting and executing construction plans for new/changed/retired OpenBao
AppRoles, policies, and KV secret paths
- Consistency review against existing NetKingdom credential structure —
reuse over duplication, compaction over sprawl
- The executive-summary format that makes a plan decidable at a glance
- Registering what it builds into ops-warden's routing catalog
(`registry/routing/catalog.yaml`) so the lane is discoverable the moment
it exists
- Its own audit trail of what it built, when, and under which approved plan
### ops-mason does not own
| Need | Owner | ops-mason's relationship |
|---|---|---|
| Whether access *should* exist at all | Architecture docs / founder | ops-mason builds what's decided, does not decide policy from nothing |
| Runtime authorization ("may actor X do Y") | flex-auth | ops-mason provisions the policy; flex-auth evaluates it at runtime |
| Identity, MFA, human auth | key-cape / Keycloak | Out of scope entirely |
| Routing consumers to the right lane | ops-warden | ops-mason feeds ops-warden's catalog; does not replace `warden access`/`warden route` |
| SSH certificate issuance | ops-warden | Untouched — ops-mason works in OpenBao AppRole/policy/KV space, not the SSH CA lane |
| OpenBao cluster init/unseal, platform deploy | railiance-platform | Out of scope — ops-mason operates within an already-running OpenBao |
| Holding or logging secret values | Nobody, ever | Same invariant as ops-warden: values live in OpenBao and process env only |
**ops-mason is not a second secrets manager and not a policy-decision engine.**
It is the construction crew for a foundation ops-warden and every credential
consumer stands on.
---
## Design principles
1. **Reuse before creation.** Every construction plan's first move is
checking whether existing structure already covers the demand. New
infrastructure is the fallback, not the default.
2. **Compaction is in scope, not just addition.** ops-mason may propose
merging or retiring redundant lanes as part of a construction plan, not
only adding new ones.
3. **One mandatory human gate, not a gate on everything.** Anything that
grants or widens access stops at the phase-3 executive summary. Read-only
plan drafts, dry runs, and tear-down of something already approved for
removal do not need to re-litigate the same decision.
4. **Mechanics stay with the agent; decisions stay with the founder.**
Directly extends ops-warden's own principle 7. The executive summary is
written so the founder never has to read a `bao` command to make the
call.
5. **Nothing built is invisible.** Every successful build registers a
catalog entry in ops-warden's routing registry in the same action —
there is no such thing as infrastructure ops-mason built that ops-warden
doesn't know how to route to.
6. **Posture-aware, like ops-warden.** The organization is in build phase
(one founder-operator, pre-revenue) — construction plans should reflect
current posture (see `ops-warden/wiki/WorkloadSecurityPosture.md`) and
tighten as posture graduates, not assume production-tier rigor on day one
or dev-tier looseness forever.
---
## Relationship to the rest of NetKingdom
```text
net-kingdom — owns the canonical security architecture
|
v
ops-mason — builds the infrastructure that architecture calls for
| (AppRoles, policies, KV paths, catalog entries)
v
ops-warden — routes consumers to what ops-mason built
|
v
OpenBao / flex-auth / key-cape — hold custody, evaluate policy, verify identity
```
NetKingdom defines what the security model should look like. ops-mason
builds the concrete lanes that satisfy it. ops-warden is the front door that
points consumers at those lanes once built. Confusing ops-mason's builder
role with ops-warden's router role — or with OpenBao's custody role —
recreates exactly the "wrong subsystem for the credential need" confusion
ops-warden itself exists to prevent.
---
## Non-goals
- Being a second OpenBao, a second ops-warden, or a policy-decision engine
- Deciding, unprompted, that new access should exist — that's an
architecture/founder call, ops-mason builds what's already decided
- Applying anything that grants or widens access without a phase-3 approved
plan
- Storing secret values anywhere but OpenBao / process env
- Owning OpenBao cluster lifecycle, flex-auth runtime, or key-cape identity
---
## Success criteria
ops-mason is succeeding when:
1. A new credential lane can go from "a consumer needs this" to "built,
catalogued, and routable via ops-warden" without a founder hand-running
`bao` commands.
2. Every construction plan is checked against existing structure before it's
proposed — duplicate/near-duplicate lanes are the exception, not routine.
3. The founder's only touchpoint is the phase-3 decision, made in plain
terms (who gets what, for how long, what it costs to undo) — never asked
to review raw provisioning mechanics.
4. Every ops-mason build has a matching ops-warden catalog entry the moment
it lands — no undocumented lanes.
5. Tearing down access is as routine and reviewed a process as creating it —
sprawl doesn't accumulate because removal is just as supported as
construction.

20
README.md
View file

@ -1,3 +1,21 @@
# ops-mason
The agent responsible to create, change, maintain and tear down access routes with new credentials, tokens, policies, etc inside net-kingdom. Ops-mason is responsible to build the security infrastructure as required and defined by architecture documents as a base for ops-warden..
The builder of NetKingdom security infrastructure — creates, changes,
maintains, and tears down access routes, credentials, tokens, and policies
so that ops-warden always has something real to route to.
- Why and boundaries: [INTENT.md](INTENT.md)
- Current work: [workplans/](workplans/)
## The four-phase process
1. **Construction plan** — given an access demand, draft what needs
building, respecting/extending/compacting existing structure first.
2. **Review and optimize** — self-review the plan against what already
exists, for consistency and ease of use.
3. **Executive summary** — the one mandatory human decision gate: render
who gets what access, for how long, and what it costs to reverse.
4. **Build** — once approved, execute the plan.
See `INTENT.md` for the full responsibility boundary against ops-warden,
OpenBao, flex-auth, and key-cape.

100
workplans/MASON-WP-0001-foundation.md Normal file
View file

@ -0,0 +1,100 @@
---
id: MASON-WP-0001
title: "Foundation: the four-phase construction process, exercised on a real demand"
status: proposed
---
First workplan for ops-mason. Stands up the four phases described in
`INTENT.md` — construction plan, review/optimize, executive summary,
build — and exercises the whole pipeline on one real, already-waiting
piece of demand: the `rein-openweights` OpenBao AppRole
(`glas-harness/workplans/GLAS-WP-0002-T02`, currently blocked on exactly
the mechanic this repo exists to formalize). That task is not busywork
invented for this workplan — it's real backlog this pipeline unblocks
the moment phase 4 lands.
## Task: Construction-plan format
Design the artifact phase 1 produces: demand description (consumer,
credential type, scope requested), an existing-structure survey (what
`bao policy list`/`bao auth list`/`bao secrets list`/ops-warden's
`registry/routing/catalog.yaml` already cover, and whether any of it
already satisfies the demand), and the proposed changes (create/modify/
tear-down, each with a stated reuse-vs-new rationale). Document in
`docs/construction-plan-format.md`. Plain, versioned markdown/YAML —
not a database — so a plan can be reviewed in a diff and stored next to
the workplan that requested it.
```task
id: MASON-WP-0001-T01
status: todo
priority: high
```
## Task: Review/optimize pass
A self-check phase 2 runs over a draft plan before it's shown to
anyone: flag likely-redundant new policies/roles against what already
exists, naming/TTL/scoping convention drift against established lanes
(e.g. the `agent-harness-binky-mail` shape:
`token_ttl=15m`, `token_max_ttl=30m`, bounded `token_num_uses`), and
note any compaction opportunity (two existing lanes that could merge).
This can start as a checklist a human/agent runs manually against a
draft plan — doesn't need to be automated tooling on day one.
```task
id: MASON-WP-0001-T02
status: todo
priority: high
```
## Task: Executive-summary format
Design the phase 3 artifact: a short, decidable rendering of a reviewed
plan — who/what gets access to what, for how long, blast radius if the
credential leaks, and what it costs to reverse. This is the only
mandatory human checkpoint (`INTENT.md` design principle 3/4) — it must
be readable without knowing `bao` syntax. Document in
`docs/executive-summary-format.md`, with the rein-openweights AppRole
plan (task T05) as the worked example.
```task
id: MASON-WP-0001-T03
status: todo
priority: medium
```
## Task: Build executor
Phase 4: given an **approved** construction plan (explicit approval
marker set after the executive summary was reviewed), execute it against
OpenBao — policy write, AppRole creation, KV secret path creation,
role_id/secret_id delivery to the consuming host, and a matching
ops-warden catalog entry in the same action (`INTENT.md` principle 5 —
nothing built stays invisible to ops-warden). Must refuse to run against
an unapproved or missing-approval-marker plan — this is the one place a
bug is a real security incident, not a bad UX. Start narrow: implement
only the operations the first real plan (T05) needs, not a general
OpenBao automation framework.
```task
id: MASON-WP-0001-T04
status: todo
priority: high
```
## Task: First real build — rein-openweights OpenBao AppRole
Run the whole pipeline for real: construction plan for
Option B from `glas-harness/workplans/GLAS-WP-0002-T02` (dedicated
`rein-openweights` AppRole + KV secret at `reins/rein-openweights/openrouter`,
mirroring `agent-harness-binky-mail`'s shape) → review/optimize → executive
summary → founder approval → build. Once built, notify
`glas-harness`/`rein-openweights` so `GLAS-WP-0002-T02`'s live OpenBao
verification can proceed.
```task
id: MASON-WP-0001-T05
status: todo
priority: high
```