ops-warden/SCOPE.md

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 for the NetKingdom security model — issues short-lived SSH certificates for adm/agt/atm actors, documents how to obtain other credential types from the right platform subsystems, and keeps ops access guidance aligned with NetKingdom canon.

---

Where we are (2026-06-24)

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).

Policy gate is shipped on the caller side (WP-0007) with production registry and smoke evidence (WP-0009 archived). flex-auth published the ssh-certificate policy package (FLEX-WP-0006). policy.enabled remains false in production until flex-auth is deployed to a reachable URL (flex-auth FLEX-WP-0007).

INTENT alignment: SSH issuance mission met in production. Remaining distance is integration breadth (ops-bridge cert_command on live tunnels), flex-auth runtime deployment (not ops-warden code), and operator hygiene.

Issue vs route

ops-warden executes exactly one lane and points at the owner for the rest.

Need	Subsystem	ops-warden role
SSH cert for host/ops access (adm/agt/atm)	ops-warden	Issue (warden sign)
API key / DB cred / dynamic lease	OpenBao	Route — point at path
"May I perform action X?"	flex-auth	Route — point at policy
Login / OIDC / MFA	key-cape / Keycloak	Route — point at IAM Profile
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).

Gap analysis: history/2026-06-24-intent-scope-gap-analysis.md (current); 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	Partial — contract yes; tunnels still static-key
NetKingdom evolution reflected in docs	Met
Non-SSH secrets stay out of ops-warden	Met

Maturity vector: D5 / A4 / C4 / R3 (Discovery / Availability / Completeness / Reliability)

Dimension	Level	Meaning today
D5	Discovery	Routing wiki + security map + pointer catalog + NK canon cross-links
A4	Availability	CLI + warden route + opt-in policy gate + agent --json lookup
C4	Completeness	SSH lane prod-verified; policy gate + registry smoke shipped; prod flip waits flex-auth deploy
R3	Reliability	Live OpenBao sign evidence on Railiance

---

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
• Opt-in flex-auth policy gate (policy.enabled, policy_decision_id in log)
• 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 issue and ops-ssh-wrapper (local backend; vault uses sign-only)
• Runbooks for OpenBao config and Inter-Hub bootstrap SSH envelope

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

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	Opt-in flex-auth policy gate (policy.enabled)
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-0013	Production integration closeout — cert_command playbook, token hygiene, principals drift

Active / ready

WP	Status	Focus
WP-0012	active	Routing scenario playbooks (catalog + wiki expansion)

Known gaps (not ops-warden workplans)

Gap	Owner	Notes
flex-auth production runtime + registry deploy	flex-auth	FLEX-WP-0007 — unblocks policy.enabled: true
Vault-backed policy gate joint smoke	flex-auth + operator	Needs valid scoped VAULT_TOKEN
ops-bridge cert_command on live tunnels	ops-bridge	Playbook shipped (wiki/playbooks/ops-bridge-tunnel-cert.md); pilot pending
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

---

Out of Scope

• Issuing non-SSH secrets (API keys, DB creds, S3 STS, Inter-Hub keys) → OpenBao with flex-auth policy where required; ops-warden documents paths only
• Identity / OIDC / MFA → key-cape, Keycloak
• Authorization policy decisions → flex-auth
• flex-auth runtime deployment → flex-auth (FLEX-WP-0007)
• 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

---

Relevant When

• Issuing or refreshing an SSH cert for adm/agt/atm
• 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

---

Not Relevant When

• Storing or vending API keys or runtime secrets (→ OpenBao)
• 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). policy.enabled: false until flex-auth reachable (FLEX-WP-0007)
• Active work: WP-0012 (routing playbooks — T2/T3 done)
• Integration docs: cert_command migration, token hygiene, principals drift (wiki/playbooks/)
• Latest assessment: history/2026-06-24-intent-scope-gap-analysis.md

---

How It Fits (NetKingdom)

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 only

---

Related Repositories

Repo	Relationship
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; policy package shipped (FLEX-WP-0006); runtime deploy FLEX-WP-0007
key-cape	Identity / IAM Profile lightweight mode
state-hub	Workstream registry

---

Provided Capabilities

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]

---

Getting Oriented

Read first	Purpose
INTENT.md	Why ops-warden exists and where it is going
SCOPE.md	What is implemented today (this file)
wiki/AccessRouting.md	What ops-warden issues vs routes (role and boundary)
wiki/CredentialRouting.md	Which subsystem for each credential need
registry/routing/catalog.yaml	Machine-readable routing pointer catalog
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/CertCommandInterface.md	cert_command contract
history/2026-06-24-intent-scope-gap-analysis.md	Current gap analysis + WP-0013
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