2026-03-28 00:45:43 +00:00
# SCOPE
> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
2026-06-17 08:20:32 +02:00
> Aspirational direction lives in `INTENT.md`.
2026-03-28 00:45:43 +00:00
---
## One-liner
2026-06-27 21:02:46 +02:00
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.
2026-03-28 00:45:43 +00:00
---
2026-08-22 15:36:37 +02:00
## Where we are (2026-08-22)
2026-06-18 01:36:23 +02:00
2026-06-18 20:44:53 +02:00
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
2026-06-24 12:44:32 +02:00
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).
2026-06-27 18:22:09 +02:00
**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.
2026-07-01 23:27:14 +02:00
**Owner-native exec lanes** are documented in the catalog (WP-0017–
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.
2026-06-27 19:30:30 +02:00
**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).
2026-06-27 18:22:09 +02:00
2026-08-22 15:36:37 +02:00
**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` .
2026-06-18 01:36:23 +02:00
2026-06-27 20:33:32 +02:00
**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.
2026-08-11 11:11:01 +02:00
**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
2026-08-22 15:36:37 +02:00
cutover, flex-auth publishing the zone-aware pre-sign stance package,
2026-08-11 11:11:01 +02:00
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).
2026-06-18 01:36:23 +02:00
Align INTENT and SCOPE to layer model v0.7; assess gaps; open WARDEN-WP-0034
The standard is accepted at v0.7, with SECURITY-COMPANION.md v0.2 as its
operative form. Four ops-warden findings were adopted between v0.4 and v0.7 —
§9.1's two marks, §5's Tooling scope rule, §6.4 obligation 1's second limb, and
§13.1's existence — and both ops-warden declaration artifacts are now cited in
the text as the estate's reference forms.
INTENT.md gains frontmatter (layer: Staff, pep_shaped: true) because §11 requires
a machine-readable declaration and prose cannot distinguish a declaration from a
transcribed review. The note now covers the agent principal (§3.4), the PEP
shape, the attributive evidence position, and the role the companion assigns:
the estate is told to ask ops-warden which lane, which credential, which route.
SCOPE.md records what is actually shipped against v0.7 and the honest conformance
state — declared gap, which is tracked non-conformance, not conformance.
The assessment checked every obligation against shipped code rather than intent.
Three gaps survive:
- §9.7.2 requires a PEP to state one revocation visibility deadline. Ours is
unstated, and the honest value is uncomfortable: the cert TTL, up to 48h. A
cert outlives revocation of the decision that authorized it — no CRL, no KRL
distribution. That is a design property never written down, which is exactly
what §9.7.2 exists to force into the open.
- §3.4 rule 1 forbids standing credentials and requires issued, attributable
authority. ADR-0004's boundary keys on WARDEN_AGENT_ID, which an agent sets
about itself. key-cape now issues a real coding-agent identity, so the
ops-warden half can stop being advisory.
- §9.6 cadence remains undeclared. Attributive, so SHOULD not MUST, but silence
through two reviews is the one outcome that is not defensible.
WARDEN-WP-0034 addresses all three, plus the discoverability gap the companion
creates and two items to route rather than absorb.
402 tests pass, ruff clean.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YWBMovyFoy9RRrfL7zKvPJ
Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 4014535@bnt-lap001
Assistant-Session: d0036016-73e8-4da1-8e47-563e3ab39a3c
2026-08-29 14:50:55 +02:00
### 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 | 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` .
2026-06-18 20:44:53 +02:00
### Issue vs route
2026-06-27 18:22:09 +02:00
ops-warden executes exactly one lane with its own authority and routes/assists the rest.
2026-06-18 20:44:53 +02:00
| Need | Subsystem | ops-warden role |
| --- | --- | --- |
| SSH cert for host/ops access (`adm` /`agt` /`atm` ) | **ops-warden** | **Issue** (`warden sign` ) |
2026-07-01 23:27:14 +02:00
| Scoped `VAULT_TOKEN` for warden-sign / policy-gate smoke | railiance-platform credential broker | Route — owner-native `credential exec` ; ops-warden does not mint |
2026-06-27 18:22:09 +02:00
| API key / DB cred / dynamic lease | OpenBao | Assist — route; proxy as caller only for `exec_capable` lanes |
2026-07-01 23:27:14 +02:00
| Provisioned secret-exec (e.g. npm publish) | secrets-engine (+ OpenBao custody) | Route — primary `secrets-engine exec` ; `warden access` as fallback |
2026-06-27 18:22:09 +02:00
| "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` |
2026-06-18 20:44:53 +02:00
| 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).
2026-08-11 11:11:01 +02:00
**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.
2026-07-01 23:27:14 +02:00
Gap analysis: `history/2026-07-01-intent-scope-gap-analysis.md` (current);
`history/2026-06-24-intent-scope-gap-analysis.md` (prior);
2026-06-24 12:44:32 +02:00
`history/2026-06-18-post-wp0008-intent-scope-reassessment.md` (SSH lane);
`history/2026-06-18-access-routing-intent-shift-assessment.md` (routing charter).
2026-06-18 01:36:23 +02:00
---
## INTENT gap snapshot
| INTENT success criterion | Status |
| --- | --- |
| Worker knows which subsystem for each credential type | Met |
| SSH short-lived, inventoried, audited | Met (production) |
2026-06-27 19:50:28 +02:00
| 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 |
2026-06-18 01:36:23 +02:00
| NetKingdom evolution reflected in docs | Met |
| Non-SSH secrets stay out of ops-warden | Met |
2026-06-27 19:30:30 +02:00
| Workload posture / maturity model for secret-flow blockers | Met — two-axis standard + descriptors + conformance checker + dev doubles (WP-0015) |
2026-08-15 20:54:58 +02:00
| 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) |
2026-06-18 01:36:23 +02:00
2026-08-15 20:54:58 +02:00
**Maturity vector:** `D5 / A5 / C5 / R4` (Discovery / Availability / Completeness / Reliability)
2026-06-18 01:36:23 +02:00
| Dimension | Level | Meaning today |
| --- | --- | --- |
2026-06-18 20:44:53 +02:00
| D5 | Discovery | Routing wiki + security map + pointer catalog + NK canon cross-links |
2026-06-27 20:33:32 +02:00
| A5 | Availability | CLI + `warden route` + `warden access` advisory & proxy front door + `warden policy` + opt-in policy gate + agent `--json` |
2026-08-15 20:54:58 +02:00
| 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) |
2026-07-01 23:27:14 +02:00
| R4 | Reliability | Live OpenBao sign + credential-broker policy-gate smoke evidence on Railiance (2026-07-01) |
2026-06-18 01:36:23 +02:00
---
Lift ops-warden's binding rules into owned ADRs
Five rules that governed this repo lived in wiki prose, a workplan, and a
comment at the top of catalog.yaml. All were followed; none was addressable.
A reader outside ops-warden could not cite one, could not tell whether it was
current, and — the point of this change — could not tell whether it was ours
to change or someone else's that we merely obey.
ADR-0001 The routing catalog is a pointer layer, never a second copy
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
Each carries owner: ops-warden, which is the load-bearing field. It says we
follow the rule AND we are responsible for changing it — by superseding ADR,
never an in-place edit. The failure this prevents runs both ways: a rule we own
mistaken for inherited canon never gets fixed, because we wait for an owner who
does not exist; inherited canon mistaken for ours gets quietly bent, and the
drift is invisible until it breaks a repo that trusted the canonical version.
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 into docs/adr/. Copying them would recreate exactly the
second-source-of-truth failure ADR-0001 exists to prevent. architecture.md also
now flags the three-digit/four-digit ADR-001 vs ADR-0001 collision, which is
itself an ours-versus-inherited confusion waiting to happen.
Publication verified rather than assumed: all five render through policy-nexus
tools/render.py, and owner reaches the reader in three places — the page eyebrow
(render.py:346), the index Owner column (build_site.py:123,137), and the
publication manifest. build_site.py:179 makes title/status/owner required, so
ownership cannot be dropped on the way out. policy-nexus publishes and never
writes back; docs/adr/ stays the source of truth.
Documentation adapted: SCOPE.md gains a Governing rules section and an orientation
entry; .claude/rules/architecture.md replaced its stub with the ADR index, the
owned-versus-inherited rule, and ADR-over-wiki precedence; finding-routing.md's
ADR-gap section closed; catalog.yaml's no-double-source header now cites ADR-0001
rather than the originating workplan.
uv run pytest -q → 338 passed, 4 deselected.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-18 13:35:13 +02:00
## 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 |
2026-08-22 15:36:37 +02:00
| `ADR-0006` | Superseded: enforcement is zone-scoped, never a global flag |
2026-08-19 23:44:58 +02:00
| `ADR-0007` | Build-stage permissiveness stops at credential disclosure; every lane carries an explicit `risk` grade |
2026-08-21 08:36:42 +02:00
| `ADR-0008` | A lane's risk grade covers every field its path discloses, not just the field it is named after |
2026-08-22 15:36:37 +02:00
| `ADR-0009` | Adopt security-zones v0.1 and compile explicit workload membership; PEP failure mode is per zone |
Align INTENT and SCOPE to layer model v0.7; assess gaps; open WARDEN-WP-0034
The standard is accepted at v0.7, with SECURITY-COMPANION.md v0.2 as its
operative form. Four ops-warden findings were adopted between v0.4 and v0.7 —
§9.1's two marks, §5's Tooling scope rule, §6.4 obligation 1's second limb, and
§13.1's existence — and both ops-warden declaration artifacts are now cited in
the text as the estate's reference forms.
INTENT.md gains frontmatter (layer: Staff, pep_shaped: true) because §11 requires
a machine-readable declaration and prose cannot distinguish a declaration from a
transcribed review. The note now covers the agent principal (§3.4), the PEP
shape, the attributive evidence position, and the role the companion assigns:
the estate is told to ask ops-warden which lane, which credential, which route.
SCOPE.md records what is actually shipped against v0.7 and the honest conformance
state — declared gap, which is tracked non-conformance, not conformance.
The assessment checked every obligation against shipped code rather than intent.
Three gaps survive:
- §9.7.2 requires a PEP to state one revocation visibility deadline. Ours is
unstated, and the honest value is uncomfortable: the cert TTL, up to 48h. A
cert outlives revocation of the decision that authorized it — no CRL, no KRL
distribution. That is a design property never written down, which is exactly
what §9.7.2 exists to force into the open.
- §3.4 rule 1 forbids standing credentials and requires issued, attributable
authority. ADR-0004's boundary keys on WARDEN_AGENT_ID, which an agent sets
about itself. key-cape now issues a real coding-agent identity, so the
ops-warden half can stop being advisory.
- §9.6 cadence remains undeclared. Attributive, so SHOULD not MUST, but silence
through two reviews is the one outcome that is not defensible.
WARDEN-WP-0034 addresses all three, plus the discoverability gap the companion
creates and two items to route rather than absorb.
402 tests pass, ruff clean.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YWBMovyFoy9RRrfL7zKvPJ
Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 4014535@bnt-lap001
Assistant-Session: d0036016-73e8-4da1-8e47-563e3ab39a3c
2026-08-29 14:50:55 +02:00
| `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 |
Lift ops-warden's binding rules into owned ADRs
Five rules that governed this repo lived in wiki prose, a workplan, and a
comment at the top of catalog.yaml. All were followed; none was addressable.
A reader outside ops-warden could not cite one, could not tell whether it was
current, and — the point of this change — could not tell whether it was ours
to change or someone else's that we merely obey.
ADR-0001 The routing catalog is a pointer layer, never a second copy
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
Each carries owner: ops-warden, which is the load-bearing field. It says we
follow the rule AND we are responsible for changing it — by superseding ADR,
never an in-place edit. The failure this prevents runs both ways: a rule we own
mistaken for inherited canon never gets fixed, because we wait for an owner who
does not exist; inherited canon mistaken for ours gets quietly bent, and the
drift is invisible until it breaks a repo that trusted the canonical version.
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 into docs/adr/. Copying them would recreate exactly the
second-source-of-truth failure ADR-0001 exists to prevent. architecture.md also
now flags the three-digit/four-digit ADR-001 vs ADR-0001 collision, which is
itself an ours-versus-inherited confusion waiting to happen.
Publication verified rather than assumed: all five render through policy-nexus
tools/render.py, and owner reaches the reader in three places — the page eyebrow
(render.py:346), the index Owner column (build_site.py:123,137), and the
publication manifest. build_site.py:179 makes title/status/owner required, so
ownership cannot be dropped on the way out. policy-nexus publishes and never
writes back; docs/adr/ stays the source of truth.
Documentation adapted: SCOPE.md gains a Governing rules section and an orientation
entry; .claude/rules/architecture.md replaced its stub with the ADR index, the
owned-versus-inherited rule, and ADR-over-wiki precedence; finding-routing.md's
ADR-gap section closed; catalog.yaml's no-double-source header now cites ADR-0001
rather than the originating workplan.
uv run pytest -q → 338 passed, 4 deselected.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-18 13:35:13 +02:00
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.
---
2026-03-28 00:45:43 +00:00
## Core Idea
2026-06-17 08:20:32 +02:00
**Today:** implements the SSH certificate lane from `wiki/AccessManagementDirective.md`
2026-06-24 12:44:32 +02:00
§§1–
flex-auth pre-sign gate, and the `cert_command` interface for ops-bridge. Production
path uses OpenBao SSH engine (`backend: vault` ).
2026-06-17 08:20:32 +02:00
2026-06-18 20:44:53 +02:00
**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.
2026-03-28 00:45:43 +00:00
---
## In Scope
2026-06-17 08:20:32 +02:00
### Implemented (SSH lane)
- Local CA backend (`ssh-keygen -s` )
2026-06-18 01:36:23 +02:00
- OpenBao / Vault-compatible SSH engine backend (**production-verified**)
2026-06-17 08:20:32 +02:00
- 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
2026-08-22 15:36:37 +02:00
- Zone-aware flex-auth policy gate (`policy_decision_id` , zone, failure mode, and
outcome in the signing audit; no repo-wide enable switch)
2026-06-24 12:44:32 +02:00
- 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` )
feat(WP-0011): warden route lookup CLI over the pointer catalog
Add a read-only `warden route` command group (list/show/find) that reads
registry/routing/catalog.yaml and tells a worker which subsystem owns a need
and which wiki/canon doc to follow. ops-warden still executes exactly one lane
(SSH); routed entries return a pointer and never call any subsystem.
- src/warden/routing/: models.py + catalog.py loader; enforces the
no-double-source rule (non-SSH entries with steps/cert_command fail validation),
dup-id and schema checks.
- route list (active-only unless --all, --tag), route show (SSH appends steps +
cert pattern; routed ends with "next action on <owner> — see <wiki_ref>"),
route find (keyword ranking, --json).
- tests/test_routing.py: load/validation, find ranking, CLI JSON shapes, plus a
drift guard (every wiki_ref anchor resolves; every entry has a reviewed date).
- Docs: wiki/AccessRouting.md CLI section, README quick reference, SCOPE A3 -> A4.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-18 21:03:24 +02:00
- `warden route` lookup CLI (`list` /`show` /`find` , `--json` ) over the pointer catalog
2026-06-27 17:35:57 +02:00
- `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
2026-06-18 01:36:23 +02:00
- `warden issue` and `ops-ssh-wrapper` (local backend; vault uses sign-only)
2026-06-27 19:50:28 +02:00
- ops-bridge cert_command readiness gate (`scripts/check_tunnel_cert_readiness.py` ,
WP-0016) — read-only preflight + opt-in offline contract smoke
feat(WARDEN-WP-0020): T4 scheduling tick + T5 SCOPE — worker complete
T4 — scripts/worker-tick.sh: scheduled tick for the conservative worker. flock concurrency
guard; short-lived kubectl port-forward to llm-connect (or LLM_CONNECT_URL, or rule-brain
fallback). Ships disabled; header documents the cron entry. Schedules the conservative tier
only (never auto-send).
T5 — SCOPE records `warden worker` as an implemented capability: conservative triage
default, full-auto opt-in, llm-connect brain, the four guardrails, schedulable tick.
WARDEN-WP-0020 finished: the autonomous coordination worker — T1 scaffold, T2 llm-connect
brain, T3 guarded executor, conservative tier (Option A), T4 scheduling, T5 docs. 245 tests,
lint clean.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-30 00:41:04 +02:00
- 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,
feat(WARDEN-WP-0021): T3-T5 — visibility, approve loop, runbook (scheduled worker complete)
T4 (review→send loop): conservative tick persists structured drafts to
state_dir/worker-drafts.json; `warden worker drafts` lists them, `warden worker approve
<id> [--body …]` sends the reviewed draft as the reply + marks read + drops it. Escalated
plans persist no draft. Live-verified end-to-end.
T3 (visibility): `warden worker status` (pending drafts, triage count, last digest, timer
state); best-effort notify-send nudge in the tick when drafts are pending.
T5: wiki/playbooks/scheduled-worker.md (enable/disable, the approve loop, failure modes,
conservative-only posture) + SCOPE note.
WARDEN-WP-0021 finished: the conservative worker now runs on a systemd --user timer
(enabled, every 15 min), triages new inbox messages into drafts you approve with one
command, degrades gracefully, and stops with one command. 249 tests, lint clean.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-30 15:24:10 +02:00
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` )
2026-06-17 08:20:32 +02:00
- Runbooks for OpenBao config and Inter-Hub bootstrap SSH envelope
2026-07-01 23:27:14 +02:00
- **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`
2026-07-01 23:32:38 +02:00
(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` )
2026-08-11 11:11:01 +02:00
- **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
2026-06-17 08:20:32 +02:00
### 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
2026-06-24 12:44:32 +02:00
- Routing pointer catalog (`registry/routing/catalog.yaml` )
2026-06-17 08:20:32 +02:00
- Keeping ops access patterns consistent with `net-kingdom` platform architecture
2026-06-27 19:30:30 +02:00
- 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
2026-06-17 08:20:32 +02:00
2026-06-24 12:44:32 +02:00
### Shipped workplans (archived)
2026-06-17 08:20:32 +02:00
2026-06-18 01:36:23 +02:00
| WP | Focus |
| --- | --- |
2026-06-24 12:44:32 +02:00
| WP-0001–
2026-06-18 01:36:23 +02:00
| WP-0006 | Credential routing, security map, inventory patterns, OpenBao checklist |
2026-08-22 15:36:37 +02:00
| WP-0007 | Original opt-in flex-auth policy gate (global switch retired by WP-0032) |
2026-06-18 01:36:23 +02:00
| WP-0008 | Production sign verification, stewardship closeout, archive hygiene |
2026-06-24 12:44:32 +02:00
| 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 |
2026-06-27 19:30:30 +02:00
| WP-0012 | Routing scenario playbooks (catalog + wiki expansion) |
2026-06-24 12:44:32 +02:00
| WP-0013 | Production integration closeout — cert_command playbook, token hygiene, principals drift |
2026-06-27 19:30:30 +02:00
| WP-0014 | Operator access assist — `warden access` advisory + proxy front door |
| WP-0015 | Workload security posture — two-axis standard, descriptors, conformance checker, dev doubles |
2026-06-27 20:33:32 +02:00
| WP-0016 | ops-bridge cert_command pilot — readiness gate (`check_tunnel_cert_readiness.py` ) + handoff |
2026-06-17 08:22:45 +02:00
2026-07-01 23:32:38 +02:00
### Recently shipped (July 2026)
2026-06-17 23:34:13 +02:00
2026-07-01 23:32:38 +02:00
| WP | Focus |
| --- | --- |
2026-08-11 11:11:01 +02:00
| 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) |
2026-07-01 23:32:38 +02:00
| WP-0022 | Unified audit trail + `warden activity` |
| WP-0023 | INTENT–
2026-08-11 11:11:01 +02:00
| 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 |
| --- | --- | --- |
2026-08-22 20:36:49 +02:00
| WP-0027 | `active` | Break-glass design/rehearsal activated narrowly on T02; mass rotation and policy-manifest reconcile remain deferred |
2026-08-22 15:36:37 +02:00
| WP-0032 | `finished` | Security zones adopted — global switch retired, explicit workload references compiled, and owner policy live |
2026-08-11 11:11:01 +02:00
| WP-0030 | `proposed` | Delegation register — record intended owner + blocker on every interim lane, `warden route gaps` , promotion gate |
2026-07-01 23:27:14 +02:00
Remaining production distance is also in other repos' lanes (see Known gaps).
2026-06-17 23:34:13 +02:00
2026-06-24 12:44:32 +02:00
### Known gaps (not ops-warden workplans)
2026-06-18 01:28:49 +02:00
2026-06-18 01:36:23 +02:00
| Gap | Owner | Notes |
| --- | --- | --- |
2026-06-27 19:50:28 +02:00
| ops-bridge `cert_command` on live tunnels | ops-bridge | Playbook + readiness gate shipped (WP-0016); pilot cutover handed off, awaiting ops-bridge |
2026-06-24 12:44:32 +02:00
| Principals sync warden ↔ railiance-infra | ops-warden + infra | `scripts/check_principals_drift.py` — operator runs periodically |
2026-06-18 01:36:23 +02:00
| NK-WP-0009 joint SSH tutorial | net-kingdom | Parallel coordination track |
2026-06-27 19:30:30 +02:00
| WP-0015 canon landing (generic `WorkloadMaturityLevel` + M0-M3 requirements) | net-kingdom + info-tech-canon | ops-warden drafted + offered (coordination msgs); owner-driven landing |
2026-08-11 11:11:01 +02:00
| 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 |
2026-06-18 01:28:49 +02:00
2026-03-28 00:45:43 +00:00
---
## Out of Scope
2026-07-01 23:27:14 +02:00
- **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
2026-06-17 08:20:32 +02:00
- Identity / OIDC / MFA → key-cape, Keycloak
- Authorization policy decisions → flex-auth
2026-06-27 18:22:09 +02:00
- flex-auth runtime deployment and secret-flow lattice enforcement → flex-auth
(`FLEX-WP-0007` and follow-ups)
2026-06-17 08:20:32 +02:00
- 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
2026-08-11 11:11:01 +02:00
- **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)
2026-03-28 00:45:43 +00:00
---
## Relevant When
2026-06-17 08:20:32 +02:00
- Issuing or refreshing an **SSH cert** for `adm` /`agt` /`atm`
2026-07-01 23:27:14 +02:00
- 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)
2026-06-17 08:20:32 +02:00
- A dev worker needs to know **where to get credentials** in the NetKingdom stack
2026-06-24 12:44:32 +02:00
- An agent needs ** `warden route find` ** instead of re-deriving routing from wiki prose
2026-06-17 08:20:32 +02:00
- `ops-bridge` needs a `cert_command` for a tunnel
2026-06-24 12:44:32 +02:00
- Adding actors to the principals inventory (regenerate flex-auth registry snapshot)
2026-06-17 08:20:32 +02:00
- Inter-Hub or bootstrap tasks need a **short-lived agent SSH envelope**
- Checking cert-side compliance (scorecard)
2026-06-24 12:44:32 +02:00
- Enabling or testing the opt-in flex-auth policy gate
2026-06-27 18:22:09 +02:00
- Classifying whether a credential blocker is a dev/test double, owner-routed prod
gate, or maturity/posture violation
2026-03-28 00:45:43 +00:00
---
## Not Relevant When
2026-07-01 23:27:14 +02:00
- Storing or vending **API keys, OpenBao tokens, or runtime secrets** (→ OpenBao /
railiance-platform broker / secrets-engine)
2026-06-17 08:20:32 +02:00
- 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)
2026-03-28 00:45:43 +00:00
---
## Current State
2026-06-18 01:36:23 +02:00
- **SSH CLI:** v0.1.0 — local + OpenBao backends
- **Production sign:** verified 2026-06-18 (`history/2026-06-17-openbao-production-verify.md` )
2026-06-24 12:44:32 +02:00
- **Access routing:** WP-0010 + WP-0011 shipped (`warden route` , pointer catalog)
- **Policy gate:** caller shipped (WP-0007); registry + smoke complete (WP-0009 archived).
ADR-0006: enforcement is zone-scoped; defer the policy.enabled flip
flex-auth enforced its ops-warden pin (FLEX-WP-0016 T03) and the gate verified
clean against it: readiness exits 0, decision:f3f7c88f9585582a, anonymous
/v1/check now 401. Everything needed to set policy.enabled: true was in place.
It stays false, by decision. policy.enabled is a single repo-wide boolean, and
with fail_closed: true it makes flex-auth a hard dependency of every warden
sign — including the certs the ops-bridge tunnels depend on, one of which
carries the policy call itself. Uniform enforcement across an estate being
actively rebuilt hardens the access needed to perform the rebuild.
The repo already refuses one-dimensional posture: WP-0015 shipped environment
and maturity axes, WP-0029 added organization_posture. A global flag ignores all
three. ADR-0006 records that enforcement belongs to a zone, and binds future
work — a zone-blind enforcement flag is out of order, not merely unwise.
WARDEN-WP-0032 drafts the zone model, leading with the ownership question:
whether this is ops-warden's to own or NetKingdom canon to consume (ADR-0005).
WP-0031 is finished with T05 cancelled and resuming as WP-0032-T05.
Also replaces the hand-run kubectl port-forward with a managed ops-bridge
tunnel, flex-auth-ops-warden-railiance01 (-L 19090:10.43.1.165:8080).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-19 20:31:28 +02:00
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**
2026-08-22 15:36:37 +02:00
(`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` .
2026-06-27 19:30:30 +02:00
- **Workload posture:** WP-0015 shipped (standard, descriptors, `warden policy` ,
conformance checker, dev doubles); canon landing owner-driven
2026-06-27 20:33:32 +02:00
- **ops-bridge cert_command:** WP-0016 shipped to pilot-ready (readiness gate +
offline contract smoke + handoff); live cutover is ops-bridge's
2026-07-01 23:27:14 +02:00
- **Access front door:** WP-0017 discoverability + WP-0018 first concrete secret lane
2026-06-29 17:41:49 +02:00
(`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
2026-07-01 23:27:14 +02:00
- **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
2026-07-01 23:32:38 +02:00
- **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`
2026-08-11 11:11:01 +02:00
- **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
2026-08-15 20:54:58 +02:00
- **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)
2026-07-01 23:27:14 +02:00
- **Integration docs:** cert_command migration, token hygiene (broker-first), principals
drift (`wiki/playbooks/` )
2026-08-11 11:11:01 +02:00
- **Latest assessment:** `history/2026-08-11-delegation-surface-assessment.md`
- **Latest workplans:** WP-0029 (policy front door) shipped July 2026; WP-0030
2026-08-15 20:54:58 +02:00
(delegation register) shipped August 2026
2026-03-28 00:45:43 +00:00
---
2026-06-17 08:20:32 +02:00
## 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
```
2026-06-18 01:36:23 +02:00
Upstream: OpenBao SSH engine (production) or local CA (labs). Actor inventory in
2026-06-24 12:44:32 +02:00
operator config or Git-tracked patterns. flex-auth registry snapshot derived from
inventory when policy gate is enabled.
2026-03-28 00:45:43 +00:00
2026-06-17 08:20:32 +02:00
Downstream: `ops-bridge` (primary), kaizen agents, CI automations, human operators.
2026-03-28 00:45:43 +00:00
---
## Terminology
2026-06-17 08:20:32 +02:00
- `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` )
2026-06-27 18:22:09 +02:00
- 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
2026-03-28 00:45:43 +00:00
---
2026-06-17 08:20:32 +02:00
## Related Repositories
2026-03-28 00:45:43 +00:00
2026-06-17 08:20:32 +02:00
| Repo | Relationship |
| --- | --- |
Align INTENT and SCOPE to layer model v0.7; assess gaps; open WARDEN-WP-0034
The standard is accepted at v0.7, with SECURITY-COMPANION.md v0.2 as its
operative form. Four ops-warden findings were adopted between v0.4 and v0.7 —
§9.1's two marks, §5's Tooling scope rule, §6.4 obligation 1's second limb, and
§13.1's existence — and both ops-warden declaration artifacts are now cited in
the text as the estate's reference forms.
INTENT.md gains frontmatter (layer: Staff, pep_shaped: true) because §11 requires
a machine-readable declaration and prose cannot distinguish a declaration from a
transcribed review. The note now covers the agent principal (§3.4), the PEP
shape, the attributive evidence position, and the role the companion assigns:
the estate is told to ask ops-warden which lane, which credential, which route.
SCOPE.md records what is actually shipped against v0.7 and the honest conformance
state — declared gap, which is tracked non-conformance, not conformance.
The assessment checked every obligation against shipped code rather than intent.
Three gaps survive:
- §9.7.2 requires a PEP to state one revocation visibility deadline. Ours is
unstated, and the honest value is uncomfortable: the cert TTL, up to 48h. A
cert outlives revocation of the decision that authorized it — no CRL, no KRL
distribution. That is a design property never written down, which is exactly
what §9.7.2 exists to force into the open.
- §3.4 rule 1 forbids standing credentials and requires issued, attributable
authority. ADR-0004's boundary keys on WARDEN_AGENT_ID, which an agent sets
about itself. key-cape now issues a real coding-agent identity, so the
ops-warden half can stop being advisory.
- §9.6 cadence remains undeclared. Attributive, so SHOULD not MUST, but silence
through two reviews is the one outcome that is not defensible.
WARDEN-WP-0034 addresses all three, plus the discoverability gap the companion
creates and two items to route rather than absorb.
402 tests pass, ruff clean.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YWBMovyFoy9RRrfL7zKvPJ
Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 4014535@bnt-lap001
Assistant-Session: d0036016-73e8-4da1-8e47-563e3ab39a3c
2026-08-29 14:50:55 +02:00
| `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` ) |
2026-06-17 08:20:32 +02:00
| `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 |
2026-08-28 21:47:44 +02:00
| `flex-auth` | Authorization — ruled name `access-engine` ; the only policy decision point. Policy package shipped (FLEX-WP-0006); runtime deploy FLEX-WP-0007 |
2026-06-17 08:20:32 +02:00
| `key-cape` | Identity / IAM Profile lightweight mode |
2026-08-11 11:11:01 +02:00
| `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 |
2026-08-19 21:20:34 +02:00
| `zone-engine` | Owns the security zone model and exception lifecycle (`ADR-0006` ); ops-warden is its first consumer |
2026-07-08 16:41:15 +02:00
| `state-hub` | Workplan registry |
2026-03-28 00:45:43 +00:00
---
## Provided Capabilities
```capability
type: security
title: SSH certificate issuance
description: Issues short-lived CA-signed SSH certificates for adm/agt/atm actors via a
2026-06-17 08:20:32 +02:00
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]
2026-03-28 00:45:43 +00:00
```
2026-06-27 21:02:46 +02:00
```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
2026-07-01 23:27:14 +02:00
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]
2026-06-27 21:02:46 +02:00
```
2026-03-28 00:45:43 +00:00
---
## Getting Oriented
2026-06-17 08:20:32 +02:00
| Read first | Purpose |
| --- | --- |
| `INTENT.md` | Why ops-warden exists and where it is going |
| `SCOPE.md` | What is implemented today (this file) |
Lift ops-warden's binding rules into owned ADRs
Five rules that governed this repo lived in wiki prose, a workplan, and a
comment at the top of catalog.yaml. All were followed; none was addressable.
A reader outside ops-warden could not cite one, could not tell whether it was
current, and — the point of this change — could not tell whether it was ours
to change or someone else's that we merely obey.
ADR-0001 The routing catalog is a pointer layer, never a second copy
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
Each carries owner: ops-warden, which is the load-bearing field. It says we
follow the rule AND we are responsible for changing it — by superseding ADR,
never an in-place edit. The failure this prevents runs both ways: a rule we own
mistaken for inherited canon never gets fixed, because we wait for an owner who
does not exist; inherited canon mistaken for ours gets quietly bent, and the
drift is invisible until it breaks a repo that trusted the canonical version.
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 into docs/adr/. Copying them would recreate exactly the
second-source-of-truth failure ADR-0001 exists to prevent. architecture.md also
now flags the three-digit/four-digit ADR-001 vs ADR-0001 collision, which is
itself an ours-versus-inherited confusion waiting to happen.
Publication verified rather than assumed: all five render through policy-nexus
tools/render.py, and owner reaches the reader in three places — the page eyebrow
(render.py:346), the index Owner column (build_site.py:123,137), and the
publication manifest. build_site.py:179 makes title/status/owner required, so
ownership cannot be dropped on the way out. policy-nexus publishes and never
writes back; docs/adr/ stays the source of truth.
Documentation adapted: SCOPE.md gains a Governing rules section and an orientation
entry; .claude/rules/architecture.md replaced its stub with the ADR index, the
owned-versus-inherited rule, and ADR-over-wiki precedence; finding-routing.md's
ADR-gap section closed; catalog.yaml's no-double-source header now cites ADR-0001
rather than the originating workplan.
uv run pytest -q → 338 passed, 4 deselected.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-18 13:35:13 +02:00
| `docs/adr/README.md` | **The rules ops-warden owns** — and how to tell ours from inherited canon |
2026-06-27 17:35:57 +02:00
| `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 |
2026-06-17 08:22:45 +02:00
| `wiki/CredentialRouting.md` | Which subsystem for each credential need |
2026-06-27 18:22:09 +02:00
| `wiki/WorkloadSecurityPosture.md` | Secret-store posture, workload maturity, and blocker triage |
2026-06-18 20:44:53 +02:00
| `registry/routing/catalog.yaml` | Machine-readable routing pointer catalog |
Align INTENT and SCOPE to layer model v0.7; assess gaps; open WARDEN-WP-0034
The standard is accepted at v0.7, with SECURITY-COMPANION.md v0.2 as its
operative form. Four ops-warden findings were adopted between v0.4 and v0.7 —
§9.1's two marks, §5's Tooling scope rule, §6.4 obligation 1's second limb, and
§13.1's existence — and both ops-warden declaration artifacts are now cited in
the text as the estate's reference forms.
INTENT.md gains frontmatter (layer: Staff, pep_shaped: true) because §11 requires
a machine-readable declaration and prose cannot distinguish a declaration from a
transcribed review. The note now covers the agent principal (§3.4), the PEP
shape, the attributive evidence position, and the role the companion assigns:
the estate is told to ask ops-warden which lane, which credential, which route.
SCOPE.md records what is actually shipped against v0.7 and the honest conformance
state — declared gap, which is tracked non-conformance, not conformance.
The assessment checked every obligation against shipped code rather than intent.
Three gaps survive:
- §9.7.2 requires a PEP to state one revocation visibility deadline. Ours is
unstated, and the honest value is uncomfortable: the cert TTL, up to 48h. A
cert outlives revocation of the decision that authorized it — no CRL, no KRL
distribution. That is a design property never written down, which is exactly
what §9.7.2 exists to force into the open.
- §3.4 rule 1 forbids standing credentials and requires issued, attributable
authority. ADR-0004's boundary keys on WARDEN_AGENT_ID, which an agent sets
about itself. key-cape now issues a real coding-agent identity, so the
ops-warden half can stop being advisory.
- §9.6 cadence remains undeclared. Attributive, so SHOULD not MUST, but silence
through two reviews is the one outcome that is not defensible.
WARDEN-WP-0034 addresses all three, plus the discoverability gap the companion
creates and two items to route rather than absorb.
402 tests pass, ruff clean.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YWBMovyFoy9RRrfL7zKvPJ
Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 4014535@bnt-lap001
Assistant-Session: d0036016-73e8-4da1-8e47-563e3ab39a3c
2026-08-29 14:50:55 +02:00
| `net-kingdom/SECURITY-COMPANION.md` | **The estate's operative security rules — start here** |
| `layer.yaml` | Layer declaration: every Tooling contact and its §5 shape |
| `pep-stance.yaml` | Unreachable-engine stance map (§6.4); equals shipped behaviour by test |
2026-08-19 22:20:44 +02:00
| `tenancy.yaml` | Declared tenancy posture (`I1 A1 E0 P n/a R n/a V0` ) and why each axis sits where it does |
2026-06-17 08:22:45 +02:00
| `wiki/NetKingdomSecurityMap.md` | Platform security component map |
2026-06-17 23:51:12 +02:00
| `examples/warden.production.example.yaml` | Production warden.yaml template |
2026-06-24 12:44:32 +02:00
| `wiki/PolicyGatedSigning.md` | flex-auth opt-in gate + registry rollout |
2026-06-17 08:20:32 +02:00
| `wiki/AccessManagementDirective.md` | SSH actor model |
| `wiki/OpsWardenConfig.md` | warden.yaml and OpenBao |
2026-07-01 23:27:14 +02:00
| `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 |
2026-07-01 23:32:38 +02:00
| `wiki/AuditTrail.md` | Unified metadata-only audit + `warden activity` |
| `wiki/playbooks/catalog-lane-promotion.md` | draft → active catalog promotion checklist |
2026-06-17 08:20:32 +02:00
| `wiki/CertCommandInterface.md` | cert_command contract |
2026-08-11 11:11:01 +02:00
| `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 |
2026-07-01 23:27:14 +02:00
| `workplans/WARDEN-WP-0023-intent-scope-alignment-closeout.md` | Alignment closeout plan |
| `history/2026-06-24-intent-scope-gap-analysis.md` | Prior gap analysis |
2026-06-27 18:22:09 +02:00
| `history/2026-06-27-workload-security-posture-charter.md` | WP-0015 posture/conformance charter |
2026-06-24 12:44:32 +02:00
| `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 |
2026-06-27 18:22:09 +02:00
| `net-kingdom/docs/platform-identity-security-architecture.md` | Platform security canon |
