ops-warden/INTENT.md

layer	role	pep_shaped	standard	standard_version	companion	declaration	pep_stance	assent
Staff	null	true	net-kingdom/canon/standards/security-layer-model_v0.7.md	0.7	net-kingdom/SECURITY-COMPANION.md	layer.yaml	pep-stance.yaml	docs/adr/ADR-0010

INTENT

ops-warden is Staff, and PEP-shaped. Declared here in its own voice, per security-layer-model_v0.7 §11 — a layer stated about a repository by another repository is not a declaration. The standard is accepted; its operative form is net-kingdom/SECURITY-COMPANION.md. ops-warden's assent is ADR-0010, and its reviews of v0.4, v0.6 and v0.7 are in history/.

Staff because ops-warden's core function is judgement, not computation: it decides which lane a need belongs to and stewards the paths through the estate's rules. Its artifacts are runbooks, routing decisions, workplans. PEP-shaped because issuing a certificate is a protected side effect — a shape, not a layer (§6.4). ops-warden renders no authorization decision and never will; it consumes them from access-engine.

The estate's front door for paths. The companion routes the whole estate here: "For how to get something done — which lane, which credential, which route — ask ops-warden. This document says what the rules are; ops-warden stewards the paths through them." That is a standing obligation, not a compliment: every rule gate-house writes needs a path someone can actually walk, and ops-warden owes the estate that path.

The declarations are files, not this note — prose cannot distinguish a declaration from a transcribed review (§11):

File	Declares	Enforced by
layer.yaml	every Tooling contact, mapped to a §5.1/§5.2/§5.3 shape, plus the non-Tooling clients so the check is total	scripts/check_layer_conformance.py, tests/test_layer_conformance.py
pep-stance.yaml	the unreachable-engine stance map (§6.4 obl. 3), total per zone	test asserts the published map equals the shipped default
tenancy.yaml	tenancy posture, and z1-operational zone membership	ADR-0009

Both are cited in the standard as the estate's reference forms (§11, §6.4, §13.1).

Two declared engine gaps (§5.3), tracked non-conformance and not conformance. VaultCA signs over a direct OpenBao client and warden desk shells bao kv put. Intended owner secrets-engine; blocked on no engine exposing an SSH-CA or attended-provisioning surface; reviewed quarterly; registered in statute §13. ops-warden keeps signing while the gap is open — refusing would remove production host access to close a documentation gap.

The agent principal (§3.4). ops-warden is operated by agents as well as people, and they share the layer but not the blast radius. No standing credential; tool use is a conduit or an engine API and there is no third route; tool availability is not permission, which is exactly what ADR-0004's read-boundary enforces; agent memory is not a state plane. Session semantics belong to glas-harness, not here.

Evidence (§9.6). ops-warden's audit trail is attributive, not load-bearing: no control branches on the presence of a signing record. Emission is deliberately non-atomic so an audit-store failure cannot remove production host access — a trade the standard sanctions, declared in wiki/AuditTrail.md, registered in §13. If any future control ever gates on this trail, that trade must be revisited before it ships.

This file captures why this repository exists, the direction it is moving toward, and the kind of system it is meant to become. It is intentionally aspirational and stable, not a description of current implementation. See SCOPE.md for what is implemented today.

---

One-liner

Operational access steward for the NetKingdom security model — knows the platform credential lanes, keeps workload posture conformance aligned, and issues short-lived SSH certificates where that lane belongs to ops-warden.

---

Why This Exists

Development workers — human operators, kaizen agents, CI automations, and custodian tooling — need safe, attributable access across an increasingly complex NetKingdom stack: identity, MFA, authorization, runtime secrets, SSH reachability, and tunnel transport.

That stack is easy to misuse:

• static SSH keys and pasted API tokens in chat or Git
• wrong subsystem chosen for a credential need (OpenBao vs warden vs key-cape)
• drift between NetKingdom architecture canon and what operators actually run
• ad hoc rediscovery of bootstrap and custody rules every time a worker needs access
• unclear security blockers because dev/test/prod posture and workload maturity are not named before someone asks for real credentials

ops-warden exists so operational access has a custodian-domain home that understands NetKingdom security infrastructure, routes workers to the right subsystem, keeps local guidance current, and directly operates only the SSH short-lived certificate lane it owns.

---

The Mission

Where we are going.

ops-warden issues short-lived SSH certificates and routes every other credential need to the subsystem that owns it. It is not a desk that wraps the platform; it owns one lane and points at the rest:

1. Know the NetKingdom security model — identity, authorization, secrets, SSH access, tunnels, bootstrap custody, and tenant/platform boundaries.
2. Route, and assist. Point workers to the correct subsystem for each credential type instead of becoming a universal secret vending machine — through the wiki and a machine-readable routing catalog that points at the owner's docs rather than restating them. Beyond pointing, assist: the warden access front door renders the exact auth method, path, and command for any need and — for exec_capable lanes — proxies the fetch as the caller (a transparent, policy-gated, audited conduit that holds, caches, and logs nothing). For owner-native exec lanes (secrets-engine exec, railiance-platform credential exec) ops-warden routes to the owner's front door — it does not mint tokens or run the owner's tool itself. This is the assist layer, not a universal broker: custody stays in OpenBao / secrets-engine / the platform broker; authorization in flex-auth.
3. Steward workload security posture conformance. Author the ops-security slice for environment posture (dev/test/prod) and workload maturity (M0-M3), then ship descriptors and read-only checks that identify whether a secret-flow blocker is real, owner-routed, or removable with a contract double. Runtime enforcement remains flex-auth; custody remains OpenBao.
4. Align runbooks, wiki, inventory patterns, and scorecard checks with NetKingdom canon as the platform evolves (OpenBao-first, flex-auth policy, key-cape IAM Profile, railiance deployment layers).
5. Issue short-lived SSH certificates for adm / agt / atm actors when host or ops reachability requires the SSH lane — via warden sign, cert_command, and ops-ssh-wrapper. This is the only lane ops-warden executes with its own authority.
6. Audit every ops-warden action — SSH signs, access proxy handoffs, worker coordination ticks — in one metadata-only trail (warden activity) so gatekeeping is observable, not tribal knowledge.

---

Lane routing — who owns which need

This is a runbook, not doctrine. Security doctrine, the authority model, and the security curriculum are gate-house's (security-layer-model_v0.7 §8). ops-warden references them and does not restate them. What follows is lane stewardship: which subsystem owns which need, and what ops-warden does about it.

The machine-readable form is registry/routing/catalog.yaml, and the executable form is warden plan "<need>" / warden route find. Prefer either over this table — it is orientation, and the catalog is the source of truth (ADR-0001).

Component	Layer	Owns	ops-warden relationship
gate-house	Staff	Security doctrine, invariants, authority ceilings, authority context, conformance review, curriculum	Route doctrine and authority-model questions here. Not policy decisions — those go to access-engine
access-engine (flex-auth)	Engine	The policy decision — whether an actor may act. The only decision point in NetKingdom	Consume decisions; caller-side pre-sign gate. ops-warden never renders or caches one
key-cape / Keycloak	Tooling	Identity — who the actor is, MFA, IAM Profile claims	Instruct the identity path; do not re-implement OIDC
OpenBao	Tooling	Runtime secrets — API keys, dynamic creds, leases, audit	Instruct custody paths; proxy reads as the caller when exec_capable. Direct client use is the declared exception above
secrets-engine	Engine	Credential abstraction, custody, lifecycle; owner-native exec	Route provisioned exec lanes (e.g. npm publish). Intended owner of the SSH-CA surface
tenant-engine	Engine	Tenant/client secret custody and front door	Route tenant lanes once fronted; current tenant proxies are interim (section 9)
user-engine	Engine	Users, accounts, memberships	No ops-warden lane today; route rather than absorb
zone-engine	Engine	Zone identity and membership	Consume compiled membership; ops-warden declares z1-operational (ADR-0009)
railiance-platform (broker)	—	Scoped lease grants (credential exec)	Route warden-sign token needs; ops-warden does not mint OpenBao tokens
ops-mason	Staff	Building and tearing down access routes and perimeters	Peer lane owner; same lane/rule demarcation applies
ops-warden	Staff	Operational access lanes — short-lived SSH certificates, routing, stewardship, runbooks	Own and issue the SSH lane
ops-bridge	Staff	Tunnel transport — consumes certs via cert_command	Primary consumer; document integration
railiance-infra	—	Host principals, force-command, SSH hardening	Instruct host-side deployment; do not own Ansible
kings-guard	Staff	Adaptive defence, observation, containment; publishes posture	Posture may reduce authority, never manufacture it

Access lane versus access rule

Normative, per security-layer-model_v0.7 §8 and assented to in ADR-0010:

• access lane — ops-warden and ops-mason. How a worker reaches a host.
• access rule — access-engine. Whether they may.

ops-warden owns the route and never the decision. A question about whether an actor may do something is not an ops-warden question, however it arrives.

Canonical references:

• net-kingdom/SECURITY-COMPANION.md — the operative form; start here
• net-kingdom/canon/standards/security-layer-model_v0.7.md (accepted; §5 shapes, §6.4 PEP, §8 vocabulary)
• net-kingdom/docs/platform-identity-security-architecture.md
• net-kingdom/docs/responsibility-map.md
• wiki/AccessManagementDirective.md (ops SSH actor model)
• .claude/rules/credential-routing.md (agent-facing runbook — stays inline by design)

---

Responsibility Boundary

ops-warden owns

• NetKingdom-aligned operational SSH access guidance and stewardship
• SSH certificate issuance for registered adm / agt / atm actors
• Actor inventory, TTL/principal policy, cert-side scorecard, unified audit trail
• cert_command contract and ops-ssh-wrapper automation surface
• Keeping ops-warden docs and patterns aligned with NetKingdom security evolution
• Workload Security Posture standard, conformance descriptors/checks, and dev-tier contract-double guidance for secret-flow readiness
• Coordination worker stewardship — triage ops-warden's State Hub inbox with conservative defaults (draft-only unless --full-auto)

ops-warden instructs but does not own

Need	Route to
OIDC login, MFA, human identity claims	key-cape / Keycloak (NetKingdom IAM Profile)
Security doctrine, invariants, authority model	gate-house
Policy decision — may actor X access resource Y	access-engine (flex-auth)
API keys, provider secrets, DB creds, object-storage STS	OpenBao (+ flex-auth policy where required)
Inter-Hub operator keys, LLM provider credentials	OpenBao or approved operator secret store
Tunnel lifecycle, port forwarding	ops-bridge
/etc/ssh/auth_principals/, host hardening	railiance-infra
OpenBao cluster init/unseal, platform deploy	railiance-platform

ops-warden is not a general secrets manager. It may document how workers obtain non-SSH credentials; it must not store long-lived secrets in Git, State Hub, workplans, logs, or chat.

---

Design Principles

1. Right lane, right subsystem

Every credential request should land in the subsystem NetKingdom designed for it. ops-warden optimizes for correct routing as much as for fast issuance.

2. Short-lived by default (SSH lane)

Operational SSH access uses CA-signed certificates with TTL and principals — never unbounded static keys in worker workflows.

3. Align with canon, reduce drift

When NetKingdom security architecture changes (e.g. OpenBao standardization, new bootstrap lanes), ops-warden updates its wiki, SCOPE, and runbooks so dev workers do not reconstruct decisions from stale chat history.

4. Attributable actors

Humans, agents, and automations are distinct actor types (adm / agt / atm) with naming, TTL, and principal conventions — matching the Access Management Directive and NetKingdom agent-operating model.

5. Implement narrowly, guide broadly

Implement only what belongs in the SSH certificate lane. Guide across the full NetKingdom security surface through documentation, scorecard checks, inventory patterns, and future policy-integration hooks.

6. Observable gatekeeping

Every ops-warden action appends metadata-only audit events; warden activity answers what happened recently in one command. Compliance checks (scorecard) make cert-side policy violations visible before they become incidents.

7. The founder is escalated to, never tasked with mechanics

(added 2026-07-18, founder directive — see WARDEN-WP-0029)

Workers and agents ask ops-warden what a credential need requires — never the founder directly. ops-warden answers three questions, in policy terms:

1. Can this be done autonomously under current policy and posture? → do it / route it, unattended.
2. Does policy require a founder decision or identity act (OIDC login, Red-lane approval)? → escalate exactly that act, nothing more.
3. Is the need unroutable? → name the missing lane and propose it (CCR), instead of improvising file drops or UI instructions.

Raw mechanics — "paste this PAT into /tmp", "click through the forgejo admin UI" — are anti-patterns: they leak credentials into CLI history and file artefacts and burn founder attention on work a lane should do. When founder interaction is required, prefer a purpose-built interaction surface (local web approval page rendering the exact action) over CLI/file handoffs.

8. Posture-aware: the organization is in build phase

Policy answers depend on lifecycle posture. The organization currently runs in build phase: one founder-operator, pre-revenue, velocity prioritized — pragmatic provisioning (workstation OIDC, per-repo deploy keys, advisory policy gates) is deliberately acceptable where audit and custody invariants hold (values only in OpenBao/process env; metadata-only trails). ops-warden must know the current posture, state it in its answers, and tighten defaults when the posture graduates (first customer data, first non-founder operator, production tier). Posture is declared configuration, not tribal knowledge.

9. Cover gaps, but never silently own them

(added 2026-08-11, founder directive — see WARDEN-WP-0030)

ops-warden works with, and never replaces or duplicates, secrets-engine, tenant-engine, user-engine and the other NetKingdom security components.

It may nonetheless cover a need that no component systematically provides yet — that is a legitimate service, and the warden access proxy makes it cheap. The danger is precisely that cheapness: an absorbed need looks permanent, stops registering as a missing capability, and quietly turns a routing layer into a second secrets broker.

So every execution position other than SSH issuance is interim by default:

• record the component that should own the front door, and what is missing
• treat the cover as a tracked gap, not as ownership
• delegate the moment that component ships its front door, keeping the proxy only as a fallback (exec_owner / exec_command — the WP-0019 pattern)

A gap ops-warden covers silently is worse than a gap it refuses, because the refusal is visible and the cover is not. Filling the gap properly — with the owner's governance, custody, and policy — is the goal; ops-warden holding the lane is the temporary means.

---

Credential flow (target mental model)

Development worker needs access
        |
        v
ops-warden (issue SSH; route / assist the rest)
        |
        +-- SSH host / ops reachability? --------> warden sign / cert_command
        |       (OpenBao SSH engine; scoped token via credential broker)
        |
        +-- Owner-native secret exec? -----------> secrets-engine exec
        |       (e.g. npm publish) or railiance-platform credential exec
        |
        +-- Generic API / DB / provider secret? -> OpenBao path
        |       (warden access proxies as caller when exec_capable)
        |
        +-- Authorization required? ------------> flex-auth decision
        |       (caller-side gate on sign + access when policy.enabled)
        |
        +-- Identity / MFA required? -------------> key-cape / Keycloak path
        |
        +-- Tunnel only? ------------------------> ops-bridge + cert_command

The steward role spans documentation, runbooks, the SSH CLI, the machine-readable routing catalog with warden route lookup, policy-gated issuance, workload posture conformance, the coordination worker, unified audit (warden activity), and — since WARDEN-WP-0014 — the warden access assist layer that advises, routes owner-native exec lanes, and (for generic exec_capable lanes) proxies fetches as the caller without holding the value.

---

Relationship to NetKingdom

NetKingdom owns the canonical security architecture and meta-orchestration across orchestrated repos. ops-warden is a custodian-domain execution repo for one security lane plus operational guidance.

• NetKingdom defines what the platform security model is
• ops-warden keeps operational SSH access and worker routing aligned with it
• Railiance repos deploy what NetKingdom and component repos specify

ops-warden should appear in NetKingdom responsibility and pattern material as the operational SSH credential authority, not as a replacement for OpenBao or flex-auth.

---

Success criteria

ops-warden is succeeding when:

1. A dev worker can determine which subsystem to use for a credential need without guessing or pasting secrets into agent sessions.
2. SSH access for agents and operators is short-lived, inventoried, and audited.
3. ops-bridge and other consumers integrate via stable cert_command without backend-specific branching.
4. NetKingdom security evolution (OpenBao, IAM Profile, bootstrap lanes) is reflected in ops-warden docs within the same maintenance cycle.
5. Non-SSH secrets remain out of ops-warden storage — only documented paths.
6. Security blockers can be classified by environment posture, workload maturity, owner route, and non-secret evidence instead of by vague credential risk.
7. Every ops-warden execution position is explicitly permanent (SSH issuance) or explicitly interim with a named intended owner and blocker — so gaps ops-warden covers stay visible as gaps and can be handed back.

---

Non-goals

• Universal credential broker for all secret types
• Runtime enforcement of the workload secret-flow lattice (flex-auth owns that)
• Replacing OpenBao, flex-auth, key-cape, or railiance deployment ownership
• Storing Inter-Hub, LLM provider, or other long-lived API keys
• Host-side SSH configuration deployment
• Duplicating or restating another subsystem's procedure — routing material points at the owner's docs; it does not fork them
• Permanently owning a lane that belongs to another component — covering an unfilled gap is acceptable and expected; keeping it after the owner can front it, or holding it without recording that it is interim, is not (§9)
• SSO / Teleport at scale (trigger per Access Management Directive §6.2)

---

Evolution notes

The repository shipped the SSH CA CLI first (WARDEN-WP-0001–0003). The stewardship and NetKingdom-alignment mission is the next stratum — docs, routing canon, inventory standards, production OpenBao SSH engine alignment, flex-auth integration design, and NetKingdom cross-links — without collapsing platform boundaries.

See wiki/CredentialRouting.md for worker-facing routing, wiki/WorkloadSecurityPosture.md for the posture/maturity conformance model, wiki/NetKingdomSecurityMap.md for component literacy, wiki/AuditTrail.md for the unified activity log, history/2026-07-01-intent-scope-gap-analysis.md for the latest gap analysis, history/2026-06-18-post-wp0008-intent-scope-reassessment.md for the SSH lane reassessment, and archived workplans WP-0006–0008 for stewardship and production closeout execution.