diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e1736e9 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +.venv/ +__pycache__/ +*.pyc +*.egg-info/ +.pytest_cache/ diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..8ba6387 --- /dev/null +++ b/INTENT.md @@ -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. diff --git a/README.md b/README.md index 8a22e7c..bcf8189 100644 --- a/README.md +++ b/README.md @@ -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.. \ No newline at end of file +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. diff --git a/workplans/MASON-WP-0001-foundation.md b/workplans/MASON-WP-0001-foundation.md new file mode 100644 index 0000000..2c5a162 --- /dev/null +++ b/workplans/MASON-WP-0001-foundation.md @@ -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 +```