docs(WP-0010): sharpen mission to "issue SSH, route the rest" + pointer catalog

Implements WARDEN-WP-0010 (charter + pointer catalog). ops-warden issues
short-lived SSH certificates and routes every other credential need to the
subsystem that owns it — no desk metaphor, one execution lane.

- wiki/AccessRouting.md: role/boundary, issue-vs-route matrix, anti-patterns
- registry/routing/catalog.yaml: machine-readable pointer layer (6 active + 1
  draft). No-double-source rule enforced structurally — authored steps/cert_command
  only on the warden_executes:true SSH entry; every wiki_ref anchor resolves
- wiki/CredentialRouting.md: catalog-keyed index + no-duplicate-interfaces note
- INTENT/SCOPE/AGENTS/repo-boundary/capability: aligned to the new framing;
  SCOPE notes A3 -> A4 lands with WP-0011 warden route CLI
- WP-0011/0012 + WP-0010: state_hub id writeback; WP-0010 marked done

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-18 20:44:53 +02:00
parent b9c8eadcfd
commit ffc2722006
12 changed files with 338 additions and 46 deletions

89
wiki/AccessRouting.md Normal file
View File

@@ -0,0 +1,89 @@
# Access Routing — what ops-warden answers
Date: 2026-06-18
ops-warden **issues short-lived SSH certificates** and **routes every other
credential need to the subsystem that owns it.** This page states that role
plainly so it cannot be misread as a desk that wraps the platform.
- **What ops-warden executes:** the SSH certificate lane only (`warden sign`,
`cert_command`, `ops-ssh-wrapper`).
- **What ops-warden answers:** *where* a credential need belongs and *who owns it*
pointing at the owner's docs, never restating their procedure.
- **What ops-warden never does:** vend API keys, log you in, decide policy, open
tunnels, or deploy hosts.
For the worker-facing decision tree see `CredentialRouting.md`; for component
literacy see `NetKingdomSecurityMap.md`. This page is the steward's statement of
**role and boundary**.
---
## Issue vs route
| Need | Subsystem | ops-warden role | Who acts |
| --- | --- | --- | --- |
| SSH cert for host/ops access (`adm`/`agt`/`atm`) | **ops-warden** | **Issue** (`warden sign`) | ops-warden signs; worker uses cert |
| API key / DB cred / dynamic lease | OpenBao | Route — point at path | Worker calls OpenBao |
| "May I perform action X?" | flex-auth (+ Topaz PDP) | Route — point at policy | Worker/PEP calls flex-auth |
| Login / OIDC token / MFA | key-cape / Keycloak | Route — point at IAM Profile | Worker authenticates |
| Object-storage STS / S3 creds | net-kingdom + flex-auth + OpenBao | Route — point at vending path | Worker follows NK-WP-0007 |
| SSH tunnel / port forward | ops-bridge | Route — supply `cert_command` | ops-bridge opens tunnel |
| Host principal / force-command | railiance-infra | Route — point at Ansible | infra deploys host |
| OpenBao cluster init / unseal | railiance-platform | Route — point at ceremony | platform operates |
Only the first row is something ops-warden **executes**. Every other row is a
**pointer**: ops-warden names the owner and the doc, and the worker acts on the
owning system directly.
---
## Anti-patterns (not coming to ops-warden)
These commands do **not** exist and will **not** be added — they belong to other
subsystems. If you find yourself wanting one, you are on the wrong desk:
| Tempting command | Why it's wrong | Right path |
| --- | --- | --- |
| `warden secret` / `warden bao` | ops-warden does not store or vend secrets | OpenBao |
| `warden login` | ops-warden does not establish identity | key-cape / Keycloak |
| `warden policy` | ops-warden does not decide authorization | flex-auth |
| `warden tunnel` | ops-warden does not manage transport | ops-bridge |
ops-warden authors step-by-step procedure for exactly one lane — SSH issuance —
because it owns it. For everything else it carries a **pointer**, not a fork of
the owner's runbook. See the no-double-source rule in
`workplans/WARDEN-WP-0010-access-routing-charter.md`.
---
## Audience notes
- **Human operators** read this page and `CredentialRouting.md` to choose the
right subsystem, then follow that subsystem's own docs.
- **Agents / CI** will read the machine-readable routing catalog
(`registry/routing/catalog.yaml`, surfaced via `warden route` — WARDEN-WP-0011)
so routing does not have to be re-derived from wiki prose each session.
- **Same truth, two shapes:** humans read the wiki; agents read the catalog. The
catalog references wiki sections by anchor so the two cannot drift apart.
---
## How this stays aligned
NetKingdom security architecture is canonical in `net-kingdom`. ops-warden tracks
it: when canon changes, the wiki section is updated and the catalog pointer
(`wiki_ref` + `canon_ref`) follows. ops-warden never overrides canon and never
silently forks it.
Report drift via a custodian workplan or a State Hub message to `ops-warden`.
---
## See also
- `CredentialRouting.md` — worker decision tree and routing table
- `NetKingdomSecurityMap.md` — component literacy
- `INTENT.md` — steward mission ("issue SSH, route the rest")
- `workplans/WARDEN-WP-0010-access-routing-charter.md` — charter + no-double-source rule
- `net-kingdom/docs/platform-identity-security-architecture.md` — platform canon

View File

@@ -70,6 +70,28 @@ stop if you landed on "NEVER ops-warden" for non-SSH secrets.
---
## Routing catalog index
These needs are also carried in the machine-readable pointer catalog
(`registry/routing/catalog.yaml`, surfaced via `warden route` — WARDEN-WP-0011).
The catalog is a **pointer layer**: it names the owner and links the doc, it does
not restate the owner's procedure. Only the SSH row is something ops-warden
executes.
| Catalog `id` | What ops-warden answers | What the worker does next |
| --- | --- | --- |
| `ssh-cert-host-access` | **Issues** the cert (`warden sign`) | Use the cert / wire it into `cert_command` |
| `openbao-api-key` | "OpenBao owns this — here is the path" | Call OpenBao on the owning system |
| `flex-auth-policy-check` | "flex-auth decides — here is the policy doc" | Query flex-auth / embed the PEP |
| `key-cape-oidc-login` | "key-cape / Keycloak owns identity" | Authenticate via IAM Profile |
| `ops-bridge-tunnel` | "ops-bridge owns transport — supply a `cert_command`" | Open the tunnel with ops-bridge |
| `railiance-infra-principals` | "railiance-infra deploys host principals" | Run the infra Ansible |
ops-warden answers *where + who*; the worker acts on the owning system. ops-warden
never performs the non-SSH step on the worker's behalf.
---
## Examples — do NOT ask ops-warden
| Request | Correct path |
@@ -80,6 +102,12 @@ stop if you landed on "NEVER ops-warden" for non-SSH secrets.
| "S3 credentials for artifact upload" | NK-WP-0007 / artifact-store consumer path |
| "JWT for my app" | key-cape / Keycloak IAM Profile |
**No duplicate interfaces.** Commands like `warden secret`, `warden login`,
`warden policy`, or `warden tunnel` do not exist and will not be added — each
belongs to another subsystem. The canonical anti-pattern table lives in
`wiki/AccessRouting.md#anti-patterns-not-coming-to-ops-warden`; it is not
restated here.
---
## Examples — ops-warden IS correct
@@ -134,6 +162,7 @@ Report drift via custodian workplan or State Hub message to `ops-warden`.
## See also
- `INTENT.md` — steward mission
- `wiki/AccessRouting.md` — what ops-warden issues vs routes (role and boundary)
- `wiki/NetKingdomSecurityMap.md` — component literacy
- `wiki/ActorInventoryPatterns.md` — actor naming
- `wiki/OpenBaoSshEngineChecklist.md` — production SSH signing verify

View File

@@ -96,6 +96,7 @@ and automation work — not platform-admin equivalents on hosts.
## See also
- `INTENT.md`
- `wiki/AccessRouting.md` — issue-vs-route role and boundary
- `wiki/CredentialRouting.md`
- `wiki/PolicyGatedSigning.md` (future flex-auth hook)
- `net-kingdom/docs/platform-identity-security-architecture.md`