Files

tegwick ac2efa1262 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:07:13 +02:00

5.5 KiB

Raw Blame History

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.

Routing lookup CLI (`warden route`)

Agents and operators query the pointer catalog directly instead of re-deriving routing from wiki prose. The command group is read-only — it never calls OpenBao, flex-auth, key-cape, or any other subsystem, and never returns secret material.

warden route list [--json] [--all] [--tag <keyword>]   # active-only unless --all
warden route show <id> [--json]                         # owner + pointers; SSH adds steps
warden route find "<free text need>" [--json] [--all]   # rank by keyword overlap

Agent-oriented examples:

# "I need an API key" — find the owner, get a pointer, act there yourself
warden route find "openrouter api key" --json
warden route show openbao-api-key --json
#   → {"warden_executes": false, "next_action": "next action on `railiance-platform` — see `wiki/CredentialRouting.md#routing-table`"}

# The one lane ops-warden executes: SSH. `show` appends the authored steps + cert pattern.
warden route show ssh-cert-host-access --json
#   → {"warden_executes": true, "cert_command": "warden sign <actor> --pubkey <path>", "steps": [...]}

show on a routed (non-SSH) need always ends with "next action on <owner_repo> — see <wiki_ref>" and never implies ops-warden performed anything. Draft scenarios (owner path not yet shipped) are hidden unless --all.

Audience notes

Human operators read this page and CredentialRouting.md to choose the right subsystem, then follow that subsystem's own docs.
Agents / CI read the machine-readable routing catalog (registry/routing/catalog.yaml) via warden route (above) 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 — a test (tests/test_routing.py) fails CI if any wiki_ref anchor stops resolving.

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.

5.5 KiB Raw Blame History