# INTENT > **Layer: Staff.** ops-warden is a Staff repository under the NetKingdom > IT-security layer model (Taxonomy -> Tooling -> Engines -> Staff, layered by > determinism and by the kind of artifact each layer produces): > `net-kingdom/canon/standards/security-layer-model_v0.1.md`, owned by gate-house, > ratified as `gate-house/decisions/decisions.md` GH-DEC-2026-001. > > **The binding rule: Staff never touches Tooling directly. It acts only through > Engine APIs.** ops-warden holds no state another layer depends on at runtime and > renders no authorization decision — it consumes them from access-engine. > > **Declared exception (standard section 5).** `src/warden/vault.py` (`VaultCA`) is a > direct OpenBao client that performs a write, and `warden desk` shells `bao kv put` > for paste-once provisioning. Both are non-conformant. Intended owner: > **secrets-engine**; blocked on: no engine exposes an SSH certificate signing > surface; reviewed quarterly. `src/warden/taint.py` reads KV metadata only, declared > under the read-only observation allowance. `warden access --fetch/--exec/--wrap` > runs the owner's tool under **the caller's** identity and supplies no authority of > its own (`ADR-0002`). > > Assent, reasoning, and the amendment offered back to gate-house: > `history/2026-08-28-security-layer-model-assent.md` and `ADR-0010`. > 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.1` section 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 ""` / `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.1` section 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/canon/standards/security-layer-model_v0.1.md` (layers, section 5, section 8) - `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) ```text 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.