coulomb/ops-warden
4
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions
ops-warden/SCOPE.md
tegwick a70f559d40
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 3s
Details
Apply GH-DEC-2026-017: INTENT.md governs, the sidecar is derived, no version 
Verified against gate-house's own committed files before editing, not the inbox
message: GH-DEC-2026-017 in decisions/decisions.md at gate-house@def0af2,
amendments A9-A13 in docs/amendments/v0.8-section-11-declaration-amendments.md,
and sections 3, 4 and 11 of net-kingdom's security-layer-model_v0.8.md. The
ruling and docs/layer-declaration-precedence.md's secondary account agreed.

INTENT.md's frontmatter is the declaration; layer.yaml is a derived artifact,
now marked derived: true / derived_from: INTENT.md, and it does not govern.

standard_version is removed from BOTH forms. The ruling's general form is that a
layer declaration must not carry a standard version, and INTENT.md is the
declaration, so removing it from the sidecar alone would have left the field in
the only file that actually declares. INTENT.md's version-pinned `standard:`
path is de-versioned for the same reason: a pinned path reads as a validity
condition. The version ops-warden assented at stays with the assent, ADR-0010.

NO LAYER VALUE IS CHANGED. INTENT.md still says Staff and layer.yaml still says
staff. Section 3's vocabulary is closed, four tokens, and case-insensitive: the
two forms were never in disagreement about a layer, and the ruling asked nobody
to re-spell anything. The comment marking the divergence is rewritten from
"unruled, do not touch" to "ruled, folding case is the checker's job".

check_layer_conformance.py would have rejected the conforming declaration this
ruling produces -- it listed standard_version as a required key. It now reads
INTENT.md as the governing form, ASCII-folds before comparing, validates both
values against the closed four-token vocabulary (Taxonomy included; omitting it
is the defect A9 records against the estate's other validator), requires the
derived marking, rejects a returning standard_version in either file, and
reports a post-fold disagreement between the forms as a finding rather than
resolving it away by precedence.

The test asserts the fold, not equality. An equality assertion here would be
this repository quietly performing the re-spelling the ruling declined to order;
the fold still fails on a real layer divergence.

pep-stance.yaml is untouched. A stance map is not a layer declaration, and the
sidecar schema beyond the derived marking and the version is explicitly not
ruled.

layer.yaml is the form seven repositories copied, so the adopter change set is
written out in wiki/playbooks/netkingdom-layer-declaration.md -- including the
trap that an adopter which also copied the checker turns a conforming
declaration into MALFORMED exit 2 by removing the field alone. No other
repository is edited here.

Still open: where the removed version lives. A12 says the derived conformance
record "already MUST" carry it; ops-warden has a re-runnable checker that emits
nothing durable. Asked of gate-house in message 4220413a, unanswered, and left
open rather than answered by choosing. Nothing above depends on it.

Carries WARDEN-WP-0034-T06 to done.

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

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 63291@bnt-lap001
Assistant-Session: 8bd77868-ca68-4f49-bb1e-d539ecc0d703
2026-09-21 02:38:55 +02:00

536 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# SCOPE
> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> Aspirational direction lives in `INTENT.md`.
---
## One-liner
Operational access steward and **front door** for the NetKingdom security model — issues
short-lived SSH certificates for `adm`/`agt`/`atm` actors, and for every other credential
need is the operator front door (`warden access`): routes to the owning subsystem and, for
`exec_capable` lanes (OpenBao reads, key-cape login), **proxies the fetch as the caller**
without taking custody. Also stewards workload security posture conformance and keeps ops
access guidance aligned with NetKingdom canon.
---
## Where we are (2026-08-22)
ops-warden **issues short-lived SSH certificates and routes every other credential
need to the subsystem that owns it.** SSH signing is **production-verified** on
Railiance OpenBao (`warden sign` against `https://bao.coulomb.social`, host CA trust
deployed).
**Access routing** is shipped: `wiki/AccessRouting.md`, credential routing wiki,
NetKingdom security map, machine-readable pointer catalog
(`registry/routing/catalog.yaml`, WP-0010), and `warden route` lookup CLI
(`list`/`show`/`find`, `--json`, WP-0011).
**Operator access assist** is shipped (WP-0014): `warden access` gives advisory
handoffs for every catalog need and can proxy `exec_capable` lanes as the caller,
without taking custody of values.
**Owner-native exec lanes** are documented in the catalog (WP-0017–0019 plus
cross-repo stewardship): provisioned secret-exec routes to **secrets-engine**
(`whynot-design-npm-publish`, production-exercised); scoped OpenBao tokens for
ops-warden signing route to the **railiance-platform credential broker**
(`ops-warden-warden-sign-token`, RAILIANCE-WP-0005 T08, live 2026-07-01). ops-warden
points at the owner's front door — it does not mint OpenBao tokens or run
`credential.py` itself.
**Workload security posture** is shipped (WP-0015, all tasks done): dev/test/prod
environment posture, M0-M3 workload maturity, the secret-flow lattice, and blocker
triage language (T1); machine-readable descriptors + `warden policy list|show` (T2);
the read-only conformance checker `scripts/check_secret_posture_conformance.py` (T3);
and the dev-tier contract-double library `warden.doubles` (T4). Canon landing in
net-kingdom / info-tech-canon is owner-driven (tracked via coordination messages, T5).
**The policy gate is zone-aware.** The caller-identity path is production proven
and the flex-auth pin enforces caller authentication. WP-0032 adopted
`security-zones_v0.1`: the repo-wide `policy.enabled` and `policy.fail_closed`
settings are retired, target workload membership compiles into flex-auth resource
attributes, and ops-warden selects dependency failure behavior from the target
zone. Unknown membership is explicit and uses the versioned build profile.
Ops-warden itself declares `z1-operational` in `tenancy.yaml`.
**ops-bridge cert_command pilot** is shipped to pilot-ready (WP-0016): a read-only
readiness gate (`scripts/check_tunnel_cert_readiness.py`) plus an opt-in offline
contract smoke (`--sign-smoke`); the playbook leads with the gate and the pilot
(`agt-state-hub-bridge`) is handed to ops-bridge. The live tunnel cutover is
ops-bridge's to execute.
**Credential hygiene and the policy front door** shipped through July 2026:
disclosure hygiene and rotation guidance (WP-0026 — `warden taint`,
`warden rotate-guide`, agent read-boundary on high-risk lanes), the tenant secret
custody pattern (WP-0028, first lane binky company email IMAP), experiential memory
across worker/agent sessions (WP-0024), the Forgejo admin PAT lane (WP-0025), and the
posture-aware policy front door (WP-0029 — `warden plan`, `warden desk`, declared
`organization_posture: build` as a third axis). WP-0027 (tamper-resistant governance,
mass rotation/lockdown) is drafted and sits in `backlog`.
**Delegation register** is the open question (WP-0030, proposed). ops-warden fronts
11 catalog lanes as a caller-identity proxy with no record of which component *should*
own that front door. The primitive to delegate exists and is proven
(`exec_owner`/`exec_command` — secrets-engine for npm publish, the credential broker
for warden-sign) but is used by 2 of 24 lanes. See
`history/2026-08-11-delegation-surface-assessment.md`.
**INTENT alignment:** SSH issuance mission met in production. All ops-warden workplans
through WP-0029 are finished except WP-0027 (`backlog`) and WP-0030 (`proposed`).
Remaining distance is in other repos' lanes: ops-bridge running the cert_command pilot
cutover, flex-auth publishing the zone-aware pre-sign stance package,
the owner-driven WP-0015 canon landing, and — newly named — the missing owner front
doors that keep ops-warden holding interim lanes (secrets-engine, tenant-engine).
### Layer-model conformance (v0.7, accepted)
ops-warden declares **Staff**, **PEP-shaped**, in `INTENT.md` frontmatter and in its
own voice — `security-layer-model_v0.7` §11. Shipped declaration artifacts, both
cited in the standard as the estate's reference forms:
| Artifact | Declares | Status |
| --- | --- | --- |
| `layer.yaml` | 5 Tooling contacts mapped to §5.1/§5.2/§5.3 shapes + non-Tooling clients so the check is total; **derived** from `INTENT.md`, which governs (`GH-DEC-2026-017`) | shipped; named reference form (§11) |
| `pep-stance.yaml` | unreachable-engine stance map, total per zone | shipped; registered in statute §13.1 (§6.4 obl. 3) |
| `scripts/check_layer_conformance.py` | every direct Tooling client maps to a declared shape | shipped; CI-enforced |
| `tests/test_layer_conformance.py` | the §5.2 no-authority property, and published stance map **equals** shipped default | shipped, 11 tests |
Conformance state under §11: **declared gap** — tracked non-conformance, not
conformance. Two §5.3 contacts (`VaultCA` signing write, `warden desk` `bao kv put`),
intended owner `secrets-engine`, registered in statute §13.
Four ops-warden findings have been adopted into the standard: §9.1's two marks
(`pending` vs `declared-gap`), §5's Tooling scope rule, §6.4 obligation 1's second
limb, and §13.1's existence. Reviews: `history/2026-08-29-layer-model-v04-review.md`,
`-v06-review.md`, `-v07-scope-intent-assessment.md`.
### Issue vs route
ops-warden executes exactly one lane with its own authority and routes/assists the rest.
| Need | Subsystem | ops-warden role |
| --- | --- | --- |
| SSH cert for host/ops access (`adm`/`agt`/`atm`) | **ops-warden** | **Issue** (`warden sign`) |
| Scoped `VAULT_TOKEN` for warden-sign / policy-gate smoke | railiance-platform credential broker | Route — owner-native `credential exec`; ops-warden does not mint |
| API key / DB cred / dynamic lease | OpenBao | Assist — route; proxy as caller only for `exec_capable` lanes |
| Provisioned secret-exec (e.g. npm publish) | secrets-engine (+ OpenBao custody) | Route — primary `secrets-engine exec`; `warden access` as fallback |
| "May I perform action X?" | flex-auth | Route — point at policy; consume decisions where configured |
| Login / OIDC / MFA | key-cape / Keycloak | Assist — route; proxy `login` lane when `exec_capable` |
| SSH tunnel / port forward | ops-bridge | Route — supply `cert_command` |
| Host principal deployment | railiance-infra | Route — point at Ansible |
Full role and boundary: `wiki/AccessRouting.md`. The catalog is a **pointer layer** —
it never restates an owner's procedure (authored `steps` exist only for the SSH lane).
**Interim by default.** SSH issuance is the only lane ops-warden owns permanently.
Where it proxies or assists, it is covering a need no component fronts yet — a
legitimate service, but a *tracked gap*, retired to the owner once their front door
exists (INTENT §9). Recording that intent per lane is WP-0030; today only
`whynot-design-npm-publish` and `ops-warden-warden-sign-token` carry it.
Gap analysis: `history/2026-07-01-intent-scope-gap-analysis.md` (current);
`history/2026-06-24-intent-scope-gap-analysis.md` (prior);
`history/2026-06-18-post-wp0008-intent-scope-reassessment.md` (SSH lane);
`history/2026-06-18-access-routing-intent-shift-assessment.md` (routing charter).
---
## INTENT gap snapshot
| INTENT success criterion | Status |
| --- | --- |
| Worker knows which subsystem for each credential type | Met |
| SSH short-lived, inventoried, audited | Met (production) |
| ops-bridge integrates via stable `cert_command` | **Pilot-ready** — contract + readiness gate (`check_tunnel_cert_readiness.py`, WP-0016) shipped; live cutover handed to ops-bridge |
| NetKingdom evolution reflected in docs | Met |
| Non-SSH secrets stay out of ops-warden | Met |
| Workload posture / maturity model for secret-flow blockers | Met — two-axis standard + descriptors + conformance checker + dev doubles (WP-0015) |
| Every execution position explicitly permanent or interim with a named owner | **Met** — every catalog entry carries `delegation:`; `warden route gaps` lists the interim set (WP-0030) |
**Maturity vector:** `D5 / A5 / C5 / R4` (Discovery / Availability / Completeness / Reliability)
| Dimension | Level | Meaning today |
| --- | --- | --- |
| D5 | Discovery | Routing wiki + security map + pointer catalog + NK canon cross-links |
| A5 | Availability | CLI + `warden route` + `warden access` advisory & proxy front door + `warden policy` + opt-in policy gate + agent `--json` |
| C5 | Completeness | All ops-warden lanes shipped — SSH (prod), routing, access assist, posture conformance, cert_command pilot gate, disclosure hygiene, tenant custody, policy front door, delegation register (WP-0030) |
| R4 | Reliability | Live OpenBao sign + credential-broker policy-gate smoke evidence on Railiance (2026-07-01) |
---
## Governing rules (ours)
The decisions that bind this repo are ADRs in `docs/adr/`, each `owner: ops-warden` —
meaning we follow them *and* we are the ones who may change them. Changing one is a
superseding ADR, never an in-place edit.
| ADR | Rule |
| --- | --- |
| `ADR-0001` | The routing catalog is a pointer layer, never a second copy of an owner's procedure (CI-enforced) |
| `ADR-0002` | ops-warden is a transparent conduit, never a secret broker |
| `ADR-0003` | Cover gaps, but never silently own them |
| `ADR-0004` | High-risk lanes refuse raw value streaming to agent sessions |
| `ADR-0005` | Implement one lane narrowly, route everything else |
| `ADR-0006` | Superseded: enforcement is zone-scoped, never a global flag |
| `ADR-0007` | Build-stage permissiveness stops at credential disclosure; every lane carries an explicit `risk` grade |
| `ADR-0008` | A lane's risk grade covers every field its path discloses, not just the field it is named after |
| `ADR-0009` | Adopt security-zones v0.1 and compile explicit workload membership; PEP failure mode is per zone |
| `ADR-0010` | ops-warden is Staff and PEP-shaped — it owns access lanes, never access rules; the direct OpenBao client is a declared engine gap, not an exemption |
Rules we follow but do not own — NetKingdom canon, the IAM profile, the
credential-management standard, the-custodian's ADR-001 workplan convention — are
cited, never copied here. Publishable through `policy-nexus`, which carries `owner`
into the published page and index.
---
## Core Idea
**Today:** implements the SSH certificate lane from `wiki/AccessManagementDirective.md`
§§1–5 — CA signing, actor inventory, TTL policy, cert-side scorecard, optional
flex-auth pre-sign gate, and the `cert_command` interface for ops-bridge. Production
path uses OpenBao SSH engine (`backend: vault`).
**Direction (INTENT):** issue short-lived SSH certificates and route dev workers to
key-cape, flex-auth, OpenBao, ops-bridge, and railiance components for everything
else — implementing only the SSH certificate lane directly, pointing at the owner
for the rest.
---
## In Scope
### Implemented (SSH lane)
- Local CA backend (`ssh-keygen -s`)
- OpenBao / Vault-compatible SSH engine backend (**production-verified**)
- Actor identity registry (`inventory.yaml`)
- `cert_command`: `warden sign <actor> --pubkey <path>` → cert on stdout
- TTL enforcement per `ActorType` (`adm` 48 h, `agt` 24 h, `atm` 8 h)
- `warden status`, cleanup, scorecard, signatures log
- Zone-aware flex-auth policy gate (`policy_decision_id`, zone, failure mode, and
outcome in the signing audit; no repo-wide enable switch)
- Production flex-auth registry builder (`scripts/build_flex_auth_registry.py`,
`registry/flex-auth/production_registry_snapshot.json`)
- Policy gate smoke runner (`scripts/policy_gate_production_smoke.sh`)
- `warden route` lookup CLI (`list`/`show`/`find`, `--json`) over the pointer catalog
- `warden access` operator front door (WP-0014): advisory handoff for any need, and a
transparent, policy-gated, audited **proxy** (`--fetch`/`--exec`) for `exec_capable`
lanes (OpenBao secret reads, key-cape login) — caller identity, value never held
- `warden issue` and `ops-ssh-wrapper` (local backend; vault uses sign-only)
- ops-bridge cert_command readiness gate (`scripts/check_tunnel_cert_readiness.py`,
WP-0016) — read-only preflight + opt-in offline contract smoke
- Coordination worker (`warden worker`, WP-0020) — autonomous triage of ops-warden's
State Hub inbox via llm-connect. **Conservative by default** (triage + drafted replies,
sends nothing); `--full-auto` opt-in. Four guardrails (fixed charter, action allowlist,
no-secret invariant, dry-run/audit) enforced regardless of the brain. **Scheduled**
(WP-0021) via a `systemd --user` timer (`scripts/install-worker-timer.sh`); review loop
`warden worker drafts | approve <id>` + `worker status`; one-command kill switch
(`wiki/playbooks/scheduled-worker.md`)
- Runbooks for OpenBao config and Inter-Hub bootstrap SSH envelope
- **warden-sign token routing** (RAILIANCE-WP-0005 T08): catalog id
`ops-warden-warden-sign-token` and playbook
`wiki/playbooks/ops-warden-warden-sign-token.md` — routes `VAULT_TOKEN` needs to
`railiance-platform/scripts/credential.py exec --grant ops-warden/warden-sign`
(preferred over manual `export VAULT_TOKEN`); `warden sign` emits broker hint when
token env is unset (WP-0023)
- **Unified audit trail** (WP-0022): append-only `audit.jsonl`, secret-material guard,
instrumentation on sign/access/worker paths, `warden activity` CLI merging legacy
logs + optional State Hub notes (`wiki/AuditTrail.md`)
- **Experiential memory** (WP-0024, `src/warden/memory.py`) — recorded outcomes feed
routing and coordination; no secret values, guardrail allowlist unchanged
- **Disclosure hygiene** (WP-0026): `warden taint <catalog-id>` (KV `custom_metadata`,
no data read), `warden rotate-guide`, safe fetch transports (`--out` / `--exec` /
`--wrap`) with refusal to stream to non-terminal stdout, and the agent read-boundary
on `risk: high` lanes (exit 7 when `WARDEN_AGENT_ID` is set)
- **Tenant secret custody** (WP-0028): tenant vs `platform/workloads/...` path
convention, policy/CCR/catalog ownership, first lane `binky-company-email-imap`
- **Policy front door** (WP-0029): `warden plan "<need>" [--json]` returning
`autonomous` / `founder_required` (typed act) / `unroutable` (CCR stub);
`warden desk` loopback founder surface (approve, OIDC login, paste-once provision
straight into OpenBao); `organization_posture: build` as posture axis C; catalog
freshness reporting on `warden route list` and in plan JSON
### Stewardship (documentation and alignment)
- NetKingdom security routing guidance — which subsystem owns which credential type
- Wiki and config references aligned with OpenBao-first platform standard
- Capability registry entry for SSH certificate issuance
- Routing pointer catalog (`registry/routing/catalog.yaml`)
- Keeping ops access patterns consistent with `net-kingdom` platform architecture
- Workload Security Posture standard (`wiki/WorkloadSecurityPosture.md`),
machine-readable posture descriptors (`registry/policy/security-posture.yaml`),
the read-only conformance checker, and the dev-tier contract-double library
### Shipped workplans (archived)
| WP | Focus |
| --- | --- |
| WP-0001–0005 | Initial CLI, quality, hygiene, OpenBao docs, hub sync |
| WP-0006 | Credential routing, security map, inventory patterns, OpenBao checklist |
| WP-0007 | Original opt-in flex-auth policy gate (global switch retired by WP-0032) |
| WP-0008 | Production sign verification, stewardship closeout, archive hygiene |
| WP-0009 | flex-auth registry + policy smoke; pickup brief for FLEX-WP-0007 |
| WP-0010 | Access routing charter + pointer catalog |
| WP-0011 | `warden route` lookup CLI |
| WP-0012 | Routing scenario playbooks (catalog + wiki expansion) |
| WP-0013 | Production integration closeout — cert_command playbook, token hygiene, principals drift |
| WP-0014 | Operator access assist — `warden access` advisory + proxy front door |
| WP-0015 | Workload security posture — two-axis standard, descriptors, conformance checker, dev doubles |
| WP-0016 | ops-bridge cert_command pilot — readiness gate (`check_tunnel_cert_readiness.py`) + handoff |
### Recently shipped (July 2026)
| WP | Focus |
| --- | --- |
| WP-0017 | Access front-door discoverability |
| WP-0018 | `whynot-design-npm-publish` — first concrete secret lane (production-exercised) |
| WP-0019 | Route provisioned secret-exec lanes to secrets-engine (`exec_owner` pattern) |
| WP-0020 | Coordination worker (`warden worker`) |
| WP-0021 | Scheduled worker tick (systemd --user timer, kill switch) |
| WP-0022 | Unified audit trail + `warden activity` |
| WP-0023 | INTENT–SCOPE alignment closeout |
| WP-0024 | Experiential memory across worker/agent sessions (`src/warden/memory.py`) |
| WP-0025 | Forgejo admin PAT OpenBao lane (CCR-2026-0006) |
| WP-0026 | Credential disclosure hygiene — `warden taint`, `warden rotate-guide`, agent read-boundary, safe fetch transports |
| WP-0028 | Tenant secret custody pattern — tenant vs platform paths; first lane binky company email IMAP |
| WP-0029 | Policy front door — `warden plan`, `warden desk`, `organization_posture: build` third axis |
### Open ops-warden work
| WP | Status | Focus |
| --- | --- | --- |
| WP-0027 | `active` | Break-glass design/rehearsal activated narrowly on T02; mass rotation and policy-manifest reconcile remain deferred |
| WP-0032 | `finished` | Security zones adopted — global switch retired, explicit workload references compiled, and owner policy live |
| WP-0030 | `proposed` | Delegation register — record intended owner + blocker on every interim lane, `warden route gaps`, promotion gate |
Remaining production distance is also in other repos' lanes (see Known gaps).
### Known gaps (not ops-warden workplans)
| Gap | Owner | Notes |
| --- | --- | --- |
| ops-bridge `cert_command` on live tunnels | ops-bridge | Playbook + readiness gate shipped (WP-0016); pilot cutover handed off, awaiting ops-bridge |
| Principals sync warden ↔ railiance-infra | ops-warden + infra | `scripts/check_principals_drift.py` — operator runs periodically |
| NK-WP-0009 joint SSH tutorial | net-kingdom | Parallel coordination track |
| WP-0015 canon landing (generic `WorkloadMaturityLevel` + M0-M3 requirements) | net-kingdom + info-tech-canon | ops-warden drafted + offered (coordination msgs); owner-driven landing |
| Owner front doors for workload secret lanes | secrets-engine | 6 lanes proxied by ops-warden that `secrets-engine exec` could front, as WP-0019 did for npm publish |
| Owner front door for tenant secret lanes | tenant-engine | WP-0028 defined the custody pattern; 3 tenant lanes still fronted by ops-warden proxy |
---
## Out of Scope
- **Issuing or custodying** non-SSH secrets (API keys, DB creds, OpenBao tokens,
S3 STS, Inter-Hub keys) → OpenBao / railiance-platform credential broker /
secrets-engine with flex-auth policy where required; ops-warden documents paths,
routes to owner-native exec front doors, and may proxy caller-authenticated
`exec_capable` lanes only
- Identity / OIDC / MFA → key-cape, Keycloak
- Authorization policy decisions → flex-auth
- flex-auth runtime deployment and secret-flow lattice enforcement → flex-auth
(`FLEX-WP-0007` and follow-ups)
- Tunnel lifecycle → `ops-bridge`
- Host principal deployment → `railiance-infra`
- OpenBao / Vault cluster deployment → `railiance-platform`
- Human admin SSH key generation (self-service `ssh-keygen`)
- Session recording, SIEM, SSO / Teleport at scale
- **Permanently owning another component's lane.** Covering an unfilled gap is in
scope and expected; keeping it once secrets-engine / tenant-engine / user-engine
can front it — or holding it without recording that it is interim — is not (INTENT §9)
---
## Relevant When
- Issuing or refreshing an **SSH cert** for `adm`/`agt`/`atm`
- A worker needs a **scoped `VAULT_TOKEN`** for production `warden sign` or the
flex-auth policy-gate smoke — route to `ops-warden-warden-sign-token`, then run
`credential exec` in `railiance-platform` (no manual token paste)
- A dev worker needs to know **where to get credentials** in the NetKingdom stack
- An agent needs **`warden route find`** instead of re-deriving routing from wiki prose
- `ops-bridge` needs a `cert_command` for a tunnel
- Adding actors to the principals inventory (regenerate flex-auth registry snapshot)
- Inter-Hub or bootstrap tasks need a **short-lived agent SSH envelope**
- Checking cert-side compliance (scorecard)
- Enabling or testing the opt-in flex-auth policy gate
- Classifying whether a credential blocker is a dev/test double, owner-routed prod
gate, or maturity/posture violation
---
## Not Relevant When
- Storing or vending **API keys, OpenBao tokens, or runtime secrets** (→ OpenBao /
railiance-platform broker / secrets-engine)
- Policy decisions on resource access (→ flex-auth)
- Managing tunnels without SSH cert issuance (→ ops-bridge)
- Static-key-only legacy access (ops-bridge static key mode)
---
## Current State
- **SSH CLI:** v0.1.0 — local + OpenBao backends
- **Production sign:** verified 2026-06-18 (`history/2026-06-17-openbao-production-verify.md`)
- **Access routing:** WP-0010 + WP-0011 shipped (`warden route`, pointer catalog)
- **Policy gate:** caller shipped (WP-0007); registry + smoke complete (WP-0009 archived).
WP-0031 shipped the calling identity and flex-auth's pin now runs
`callerAuth.mode: enforce` (FLEX-WP-0016) — the gate is **ready and verified**
(`decision:f3f7c88f9585582a`, anonymous `/v1/check` -> 401). WP-0032 and
`ADR-0009` retired the global switch: the compiled target workload selects the
zone, flex-auth owns stance, and ops-warden applies the zone's PEP failure mode.
Re-check caller identity with `scripts/check_policy_caller_identity.py`.
- **Workload posture:** WP-0015 shipped (standard, descriptors, `warden policy`,
conformance checker, dev doubles); canon landing owner-driven
- **ops-bridge cert_command:** WP-0016 shipped to pilot-ready (readiness gate +
offline contract smoke + handoff); live cutover is ops-bridge's
- **Access front door:** WP-0017 discoverability + WP-0018 first concrete secret lane
(`whynot-design-npm-publish`), **production-exercised** — whynot-design published
`@whynot/design@0.4.0` through the conduit. WP-0019 routes provisioned secret-exec
lanes to **secrets-engine** (`secrets-engine exec`), proxy as transparent fallback
- **warden-sign broker routing:** catalog `ops-warden-warden-sign-token` +
`wiki/playbooks/ops-warden-warden-sign-token.md` (RAILIANCE-WP-0005 T08) — live
`make credential-exec-ops-warden-smoke` proven 2026-07-01; manual `export VAULT_TOKEN`
documented as fallback only
- **Audit + activity:** WP-0022 shipped — `warden activity`, `wiki/AuditTrail.md`
- **INTENT closeout:** WP-0023 shipped — INTENT refresh, production flip/cutover
checklists, catalog promotion cadence, broker hint on missing `VAULT_TOKEN`
- **Disclosure hygiene:** WP-0026 shipped — `warden taint`, `warden rotate-guide`,
safe fetch transports (`--out`/`--exec`/`--wrap`), agent read-boundary on `risk: high`
lanes (`wiki/playbooks/agent-read-boundary.md`)
- **Tenant custody:** WP-0028 shipped — tenant vs platform path convention; first lane
`binky-company-email-imap`. Front door is still an ops-warden proxy (tenant-engine gap)
- **Policy front door:** WP-0029 shipped — `warden plan "<need>"` (autonomous /
founder_required / unroutable), `warden desk` founder interaction surface, declared
`organization_posture: build` as a third posture axis, catalog freshness reporting
- **Delegation:** 27 catalog lanes carry `delegation:` (WP-0030). SSH is
`permanent`; owner-fronted lanes are `native`; interim proxies name
`intended_owner` + `blocked_on`. Query: `warden route gaps`.
- **Active work:** WP-0027 (`backlog`); remaining production distance is other
repos' lanes (and retiring interim covers as those owners ship front doors)
- **Integration docs:** cert_command migration, token hygiene (broker-first), principals
drift (`wiki/playbooks/`)
- **Latest assessment:** `history/2026-08-11-delegation-surface-assessment.md`
- **Latest workplans:** WP-0029 (policy front door) shipped July 2026; WP-0030
(delegation register) shipped August 2026
---
## How It Fits (NetKingdom)
```text
key-cape / Keycloak identity claims
→ flex-auth authorization decisions
→ OpenBao runtime secrets & dynamic credentials
→ ops-warden SSH certs + operational access guidance
→ ops-bridge tunnel transport (cert_command consumer)
→ railiance-* deployment and host enforcement
```
Upstream: OpenBao SSH engine (production) or local CA (labs). Actor inventory in
operator config or Git-tracked patterns. flex-auth registry snapshot derived from
inventory when policy gate is enabled.
Downstream: `ops-bridge` (primary), kaizen agents, CI automations, human operators.
---
## Terminology
- `ActorType`: `adm` | `agt` | `atm`
- `cert_command`: shell command returning a cert on stdout
- `inventory.yaml`: actor → principals + TTL registry
- `LocalCA` / `VaultCA`: signing backends (`backend: local` | `vault`)
- Pointer catalog: `registry/routing/catalog.yaml` — subsystem ownership lookup plus
secret-free `warden access` handoff metadata
- Workload Security Posture: env posture (`dev/test/prod`) plus maturity (`M0-M3`)
used to decide whether a secret may flow to a workload
---
## Related Repositories
| Repo | Relationship |
| --- | --- |
| `gate-house` | Owns the security layer model, doctrine, invariants, authority context, and conformance review. ops-warden routes doctrine questions there, and the companion routes the estate's *path* questions back to ops-warden (`ADR-0010`) |
| `net-kingdom` | Canonical security architecture; ops-warden aligns to it |
| `ops-bridge` | Primary cert_command consumer |
| `railiance-infra` | Host-side SSH principals and hardening |
| `railiance-platform` | OpenBao deployment and platform secrets |
| `flex-auth` | Authorization — ruled name `access-engine`; the only policy decision point. Policy package shipped (FLEX-WP-0006); runtime deploy FLEX-WP-0007 |
| `key-cape` | Identity / IAM Profile lightweight mode |
| `secrets-engine` | Owner-native secret-exec front door (`secrets-engine exec/route`); ops-warden routes provisioned secret lanes to it (WP-0019) and holds 6 more as interim proxies pending its front doors |
| `tenant-engine` | Intended owner of tenant/client secret front doors; ops-warden holds 3 tenant lanes as interim proxies (WP-0028 pattern, WP-0030 register) |
| `user-engine` | End-user identity/account lifecycle; no ops-warden lane today — route rather than absorb |
| `zone-engine` | Owns the security zone model and exception lifecycle (`ADR-0006`); ops-warden is its first consumer |
| `state-hub` | Workplan registry |
---
## Provided Capabilities
```capability
type: security
title: SSH certificate issuance
description: Issues short-lived CA-signed SSH certificates for adm/agt/atm actors via a
pluggable cert_command interface; documents NetKingdom operational access routing;
supports local CA and OpenBao/Vault-compatible SSH engine backends.
keywords: [ssh, certificate, ca, credential, warden, ops-warden, pki, openbao, vault, netkingdom]
```
```capability
type: security
title: Operator access front door (caller-identity fetch proxy)
description: warden access is the operator front door for any NetKingdom credential need.
It renders the owner, auth method, path, and policy status, and for exec_capable lanes
(OpenBao secret reads, key-cape OIDC login) proxies the fetch as the caller — running
the owner's tool with the caller's identity and streaming the value to them. For
owner-native lanes (secrets-engine exec, railiance-platform credential broker) it routes
to the owner's front door instead of proxying. ops-warden takes no custody — transparent
conduit, not a broker. Use this to discover how to obtain an API key, DB credential,
npm token, warden-sign lease, or login — not a State Hub message.
keywords: [access, credential, secret, npm, token, api-key, openbao, key-cape, login, proxy, fetch, exec, warden-access, front-door, routing, warden-sign, vault_token, credential-broker]
```
---
## Getting Oriented
| Read first | Purpose |
| --- | --- |
| `INTENT.md` | Why ops-warden exists and where it is going |
| `SCOPE.md` | What is implemented today (this file) |
| `docs/adr/README.md` | **The rules ops-warden owns** — and how to tell ours from inherited canon |
| `wiki/AccessRouting.md` | What ops-warden issues vs routes vs assists (role and boundary) |
| `wiki/OperatorAccessAssist.md` | `warden access` front door + conduit-vs-broker boundary + guardrails |
| `wiki/CredentialRouting.md` | Which subsystem for each credential need |
| `wiki/WorkloadSecurityPosture.md` | Secret-store posture, workload maturity, and blocker triage |
| `registry/routing/catalog.yaml` | Machine-readable routing pointer catalog |
| `net-kingdom/SECURITY-COMPANION.md` | **The estate's operative security rules — start here** |
| `layer.yaml` | Derived layer declaration: every Tooling contact and its §5 shape (`INTENT.md` frontmatter governs) |
| `pep-stance.yaml` | Unreachable-engine stance map (§6.4); equals shipped behaviour by test |
| `tenancy.yaml` | Declared tenancy posture (`I1 A1 E0 P n/a R n/a V0`) and why each axis sits where it does |
| `wiki/NetKingdomSecurityMap.md` | Platform security component map |
| `examples/warden.production.example.yaml` | Production warden.yaml template |
| `wiki/PolicyGatedSigning.md` | flex-auth opt-in gate + registry rollout |
| `wiki/AccessManagementDirective.md` | SSH actor model |
| `wiki/OpsWardenConfig.md` | warden.yaml and OpenBao |
| `wiki/playbooks/ops-warden-warden-sign-token.md` | Scoped `VAULT_TOKEN` via credential broker (preferred path) |
| `wiki/playbooks/operator-openbao-token-hygiene.md` | Manual token fallback and hygiene rules |
| `wiki/AuditTrail.md` | Unified metadata-only audit + `warden activity` |
| `wiki/playbooks/catalog-lane-promotion.md` | draft → active catalog promotion checklist |
| `wiki/CertCommandInterface.md` | cert_command contract |
| `history/2026-08-11-delegation-surface-assessment.md` | Current assessment — where ops-warden covers gaps and who should own them |
| `workplans/WARDEN-WP-0030-delegation-register.md` | Delegation register plan (proposed) |
| `history/2026-07-01-intent-scope-gap-analysis.md` | Prior INTENT↔SCOPE gap analysis |
| `workplans/WARDEN-WP-0023-intent-scope-alignment-closeout.md` | Alignment closeout plan |
| `history/2026-06-24-intent-scope-gap-analysis.md` | Prior gap analysis |
| `history/2026-06-27-workload-security-posture-charter.md` | WP-0015 posture/conformance charter |
| `history/2026-06-18-post-wp0008-intent-scope-reassessment.md` | SSH lane gap analysis |
| `history/2026-06-18-access-routing-intent-shift-assessment.md` | Routing charter decision |
| `history/2026-06-23-flex-auth-policy-gate-production-smoke.md` | Policy gate smoke evidence |
| `net-kingdom/docs/platform-identity-security-architecture.md` | Platform security canon |
Reference in a new issue View git blame Copy permalink