diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..8ea5b9a --- /dev/null +++ b/INTENT.md @@ -0,0 +1,224 @@ +# INTENT + +> 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 them 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 + +**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 aims to become the **operational access desk** for the ops fleet: + +1. **Know** the NetKingdom security model — identity, authorization, secrets, + SSH access, tunnels, bootstrap custody, and tenant/platform boundaries. +2. **Route** workers to the correct subsystem for each credential type instead + of becoming a universal secret vending machine. +3. **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). +4. **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`. +5. **Audit** SSH signing operations and cert-side compliance so gatekeeping is + observable, not tribal knowledge. + +--- + +## NetKingdom Security Literacy + +ops-warden should be fluent in the platform architecture documented in +`net-kingdom` — especially: + +| Plane / component | Role in access | ops-warden relationship | +| --- | --- | --- | +| **key-cape / Keycloak** | Identity — who is the actor, MFA, IAM Profile claims | Instruct identity path; do not re-implement OIDC | +| **flex-auth + Topaz** | Authorization — may this actor perform this action | Future policy gate before SSH issuance; document integration | +| **OpenBao** | Runtime secrets — API keys, dynamic creds, leases, audit | Instruct secret custody paths; SSH engine is signing backend only | +| **ops-warden** | Operational SSH certificates — short-lived host access | **Own and issue** this lane | +| **ops-bridge** | 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 | +| **railiance-platform** | OpenBao/K8s/platform service deployment | Instruct production endpoints; do not deploy clusters | + +Canonical references: + +- `net-kingdom/docs/platform-identity-security-architecture.md` +- `net-kingdom/docs/responsibility-map.md` +- `wiki/AccessManagementDirective.md` (ops SSH actor model) + +--- + +## 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, signatures log +- `cert_command` contract and `ops-ssh-wrapper` automation surface +- Keeping ops-warden docs and patterns aligned with NetKingdom security evolution + +### ops-warden instructs but does not own + +| Need | Route to | +| --- | --- | +| OIDC login, MFA, human identity claims | key-cape / Keycloak (NetKingdom IAM Profile) | +| Policy decision — may actor X access resource Y | 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 successful SSH sign is auditable (`signatures.log`). Compliance checks +(scorecard) make cert-side policy violations visible before they become incidents. + +--- + +## Credential flow (target mental model) + +```text +Development worker needs access + | + v +ops-warden (steward / desk) + | + +-- SSH host / ops reachability? ----> warden sign / cert_command + | + +-- Runtime API / platform secret? --> OpenBao path (documented) + | + +-- Authorization required? ---------> flex-auth decision (future hook) + | + +-- Identity / MFA required? --------> key-cape / Keycloak path + | + +-- Tunnel only? --------------------> ops-bridge + cert_command +``` + +Today the **steward desk** is primarily documentation, runbooks, and the +implemented SSH CLI. Routing automation and policy-gated issuance are intentional +follow-ups, not current promises. + +--- + +## 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. + +--- + +## Non-goals + +- Universal credential broker for all secret types +- 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 +- 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 `history/2026-06-17-intent-scope-assessment.md` for the current SCOPE ↔ +INTENT gap analysis and `workplans/WARDEN-WP-0006-netkingdom-alignment-and-access-stewardship.md` +for the active execution plan. \ No newline at end of file diff --git a/README.md b/README.md index b0fee74..94d18cc 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,9 @@ SSH Certificate Authority and certificate lifecycle manager for the ops fleet. Signs short-lived certs for `adm` / `agt` / `atm` actors and exposes the `cert_command` interface consumed by `ops-bridge` and other tooling. -See `SCOPE.md` for boundaries and `wiki/AccessManagementDirective.md` for policy. +See `INTENT.md` for direction, `SCOPE.md` for current implementation, and +`wiki/AccessManagementDirective.md` for SSH policy. Gap analysis: +`history/2026-06-17-intent-scope-assessment.md`. ## Install @@ -54,6 +56,8 @@ uv run ruff check . ## Documentation +- `INTENT.md` — operational access steward mission (NetKingdom-aligned) +- `wiki/CredentialRouting.md` — *planned WP-0006* — which subsystem for each credential type - `wiki/OpsWardenConfig.md` — configuration reference - `wiki/CertCommandInterface.md` — `cert_command` contract for callers - `wiki/InterHubBootstrapAccessLane.md` — short-lived cert envelope for bootstrap tasks diff --git a/SCOPE.md b/SCOPE.md index 7d890fe..1b32492 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -3,111 +3,147 @@ > This file helps you quickly understand what this repository is about, > when it is relevant, and when it is not. > It is intentionally lightweight and may be incomplete. +> Aspirational direction lives in `INTENT.md`. --- ## One-liner -SSH Certificate Authority and credential issuance for the ops fleet — signs short-lived -certificates for `adm`/`agt`/`atm` actors; provides the `cert_command` interface consumed -by ops-bridge and other tooling. +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. --- ## Core Idea -Implements `wiki/AccessManagementDirective.md` §§1–5. Owns the CA key, actor identity -inventory, signing logic, and scorecard. Two backends: `local` (ssh-keygen, for labs / -offline use) and `vault` (OpenBao or other Vault-compatible SSH secrets engine API, for -production). Both expose the same CLI surface and the same `cert_command` interface — -callers never need to know which backend is in use. +**Today:** implements the SSH certificate lane from `wiki/AccessManagementDirective.md` +§§1–5 — CA signing, actor inventory, TTL policy, cert-side scorecard, and the +`cert_command` interface for ops-bridge. + +**Direction (INTENT):** become the custodian-domain desk that understands NetKingdom +identity, authorization, secrets, and SSH lanes — routing dev workers to key-cape, +flex-auth, OpenBao, ops-bridge, and railiance components instead of centralizing +all secrets here. + +Signing backends: `local` (ssh-keygen, labs) and `vault` (OpenBao or other +Vault-compatible SSH secrets engine API, production). --- ## In Scope -- Local CA backend (`ssh-keygen -s`) — fully functional without platform secrets access -- OpenBao / Vault-compatible SSH engine backend — production signing via HTTP API -- Actor identity registry (`inventory.yaml`) — maps actors to principals and TTL policy -- `cert_command` interface: `warden sign --pubkey ` → cert text on stdout -- TTL policy enforcement per `ActorType` (`adm` 48 h, `agt` 24 h, `atm` 8 h) -- Certificate status inspection (`warden status`) -- Stale-cert cleanup and scorecard checks (cert-side; see §5 of directive) -- `warden issue` — generate keypair + sign in one step (for `agt`/`atm` actors) -- `ops-ssh-wrapper` script — wraps SSH commands with automatic cert acquisition +### Implemented (SSH lane) + +- Local CA backend (`ssh-keygen -s`) +- OpenBao / Vault-compatible SSH engine backend +- Actor identity registry (`inventory.yaml`) +- `cert_command`: `warden sign --pubkey ` → cert on stdout +- TTL enforcement per `ActorType` (`adm` 48 h, `agt` 24 h, `atm` 8 h) +- `warden status`, cleanup, scorecard, signatures log +- `warden issue` and `ops-ssh-wrapper` +- 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 +- Keeping ops access patterns consistent with `net-kingdom` platform architecture + +### Planned (see workplan) + +- NetKingdom cross-links and responsibility-map alignment +- Credential routing runbook for dev workers +- Standard actor inventory patterns for agents and CI +- flex-auth policy hook design for gated SSH issuance +- Production OpenBao SSH engine operational checklist --- ## Out of Scope -- Tunnel lifecycle management → `ops-bridge` -- Host-side principal deployment (`/etc/ssh/auth_principals/`) → `railiance-infra` Ansible -- SSH key generation for human admins (self-service: `ssh-keygen`) -- OpenBao / Vault cluster setup, HA, or PKI secrets engine deployment -- Session recording, SIEM forwarding, audit log aggregation -- SSO / Teleport integration (trigger when §6.2 scale thresholds are hit) -- Host-side scorecard checks (password auth disabled, root login disabled) → `railiance-infra` +- **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 +- 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 a cert for any `adm`/`agt`/`atm` actor -- Checking cert validity or running the compliance scorecard -- `ops-bridge` needs a `cert_command` to be defined for a tunnel -- Adding a new actor to the principals inventory -- Bootstrapping the CA for a new environment -- Reaching a trusted execution host for attended Inter-Hub bootstrap work with - a short-lived agent certificate +- Issuing or refreshing an **SSH cert** for `adm`/`agt`/`atm` +- A dev worker needs to know **where to get credentials** in the NetKingdom stack +- `ops-bridge` needs a `cert_command` for a tunnel +- Adding actors to the principals inventory +- Inter-Hub or bootstrap tasks need a **short-lived agent SSH envelope** +- Checking cert-side compliance (scorecard) --- ## Not Relevant When -- Managing tunnel lifecycle (→ `ops-bridge`) -- Deploying SSH principal config to hosts (→ `railiance-infra`) -- All access is via static keys with no TTL (ops-bridge static key mode handles this) -- Human admins manually managing their own certificates +- 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 -- Status: shipped — WARDEN-WP-0001 through WARDEN-WP-0003 complete (v0.1.0) -- Implementation: full `warden` CLI with `local` and `vault` backends, inventory, - scorecard, cleanup, signatures log, and `ops-ssh-wrapper` -- Registry: `capability.security.ssh-certificate-issuance` published in - `registry/indexes/capabilities.yaml` (federation index live on Gitea raw URL) +- **SSH CLI:** shipped v0.1.0 (WARDEN-WP-0001–0003) +- **Docs:** OpenBao-first config (WARDEN-WP-0005), Inter-Hub bootstrap runbook +- **Registry:** `capability.security.ssh-certificate-issuance` published +- **INTENT:** defined 2026-06-17; stewardship layer largely **documentation-only** +- **Gap:** see `history/2026-06-17-intent-scope-assessment.md` --- -## How It Fits +## How It Fits (NetKingdom) -- Upstream: CA key (file or Vault); actor inventory in Git -- Downstream consumers: `ops-bridge` calls `warden sign` via `cert_command`; any other - tool needing short-lived SSH certs can use the same interface -- Often used with: `ops-bridge` (primary consumer), `railiance-infra` (host-side principal sync) +```text +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: CA key (local file or OpenBao SSH engine). Actor inventory in Git or +operator config. + +Downstream: `ops-bridge` (primary), kaizen agents, CI automations, human operators. --- ## Terminology -- `ActorType`: `adm` (human operator), `agt` (LLM agent), `atm` (deterministic automation) -- `cert_command`: shell command that a caller (e.g. ops-bridge) runs to obtain a cert -- `CertSpec`: signing request (actor name, pubkey path, TTL, principals) -- `CertRecord`: result of signing (identity, valid_before, cert_path, signed_at) -- `principals`: SSH roles embedded in the cert, matched against `/etc/ssh/auth_principals/%u` -- `inventory.yaml`: authoritative registry of actor → principals + TTL policy -- `LocalCA`: file-based CA backend using `ssh-keygen -s` -- `VaultCA`: OpenBao / Vault-compatible SSH engine backend (`backend: vault`) +- `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`) --- -## Related / Overlapping Repositories +## Related Repositories -- `ops-bridge` — primary consumer; calls `warden sign` via `cert_command` in tunnel config -- `railiance-infra` — owns host-side principal deployment and host-side scorecard checks -- `the-custodian/state-hub` — domain/workstream registry +| 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; future pre-sign policy gate | +| `key-cape` | Identity / IAM Profile lightweight mode | +| `state-hub` | Workstream registry | --- @@ -117,19 +153,22 @@ callers never need to know which backend is in use. 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; supports local CA (ssh-keygen) and OpenBao/Vault-compatible SSH engine backends. -keywords: [ssh, certificate, ca, credential, warden, ops-warden, pki, openbao, vault] + 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 -- Start with: `SCOPE.md` (this file), then `wiki/AccessManagementDirective.md` -- Config reference: `wiki/OpsWardenConfig.md` -- cert_command contract: `wiki/CertCommandInterface.md` -- Inter-Hub bootstrap access lane: `wiki/InterHubBootstrapAccessLane.md` -- Config files: `~/.config/warden/warden.yaml`, `~/.config/warden/inventory.yaml` -- State: `~/.local/state/warden/` (certs, generated keypairs) -- Entry point: `warden --help` -- Workplans: `workplans/` (active); `workplans/archived/` (finished) +| Read first | Purpose | +| --- | --- | +| `INTENT.md` | Why ops-warden exists and where it is going | +| `SCOPE.md` | What is implemented today (this file) | +| `history/2026-06-17-intent-scope-assessment.md` | INTENT ↔ SCOPE gaps | +| `wiki/AccessManagementDirective.md` | SSH actor model | +| `wiki/OpsWardenConfig.md` | warden.yaml and OpenBao | +| `wiki/CertCommandInterface.md` | cert_command contract | +| `wiki/InterHubBootstrapAccessLane.md` | Bootstrap SSH envelope | +| `net-kingdom/docs/platform-identity-security-architecture.md` | Platform security canon | \ No newline at end of file diff --git a/history/2026-06-17-intent-scope-assessment.md b/history/2026-06-17-intent-scope-assessment.md new file mode 100644 index 0000000..bbb26cd --- /dev/null +++ b/history/2026-06-17-intent-scope-assessment.md @@ -0,0 +1,172 @@ +# INTENT ↔ SCOPE State Assessment — ops-warden + +**Date:** 2026-06-17 +**Author:** codex +**Trigger:** INTENT.md established; SCOPE.md refreshed to reflect stewardship +mission alongside SSH CLI implementation. +**Follow-up workplan:** `workplans/WARDEN-WP-0006-netkingdom-alignment-and-access-stewardship.md` + +--- + +## 1. Executive summary + +ops-warden **ships a complete SSH CA CLI** (v0.1.0, 100 unit tests, OpenBao-first +docs, federation capability published). The new **INTENT** reframes the repo as an +**operational access steward** for the NetKingdom security model: knowledgeable +about platform credential lanes, routing workers to the right subsystems, keeping +guidance aligned — while **issuing only SSH certificates** directly. + +**Alignment:** strong on the **SSH implementation lane**; weak on the **stewardship +and NetKingdom integration** lane declared in INTENT. + +**Self-assessed vector (product):** `D4 / A3 / C2 / R2` + +| Dimension | Level | Rationale | +| --- | --- | --- | +| Discovery (D) | D4 | SSH lane well documented; stewardship/routing canon immature | +| Availability (A) | A3 | Installable CLI + cert_command; no desk API or policy gate | +| Completeness (C) | C2 | SSH core works; INTENT stewardship largely undelivered | +| Reliability (R) | R2 | Good test coverage; production OpenBao SSH path not verified end-to-end | + +--- + +## 2. Delivery snapshot + +| Area | State (2026-06-17) | +| --- | --- | +| SSH CLI | `warden sign/issue/status/scorecard/cleanup/log/inventory` | +| Backends | `local` + `vault` (OpenBao-compatible API) | +| Tests | 100 unit + integration marker suite | +| Wiki | AccessManagementDirective, OpsWardenConfig, CertCommandInterface, InterHubBootstrapAccessLane | +| Registry | `capability.security.ssh-certificate-issuance` (D4/A3/C3/R2 in entry) | +| INTENT.md | **New** — stewardship + NetKingdom literacy | +| NetKingdom cross-links | Minimal in SCOPE; responsibility-map still lists ops-warden out-of-scope | +| Credential routing runbook | **Missing** — no single “which subsystem?” guide in wiki | +| flex-auth pre-sign hook | **Not designed or implemented** | +| Production OpenBao SSH engine | Documented; live mount/roles unverified from this repo | +| Standard agent inventory templates | **Missing** — only example actors in docs | + +--- + +## 3. INTENT alignment + +### Aligned + +| INTENT expectation | SCOPE evidence | +| --- | --- | +| Issue short-lived SSH certs for adm/agt/atm | Full CLI, TTL policy, scorecard, signatures log | +| Stable cert_command for consumers | `wiki/CertCommandInterface.md`, ops-bridge integration contract | +| Do not store long-lived API secrets | Repo boundary, InterHub runbook, CUST-WP-0049 non-goals | +| OpenBao as production SSH signing backend | `wiki/OpsWardenConfig.md` (WP-0005) | +| Auditable SSH gatekeeping | `signatures.log`, scorecard checks | +| Actor attribution model | AccessManagementDirective alignment, ActorType enum | + +### Partial + +| INTENT expectation | Gap | +| --- | --- | +| Know NetKingdom security infrastructure | INTENT tables exist; no mirrored wiki summary or kept-in-sync process | +| Route workers to correct subsystem | Scattered across SCOPE/repo-boundary; no `wiki/CredentialRouting.md` | +| Keep guidance aligned with NetKingdom canon | No subscription to net-kingdom doc changes; responsibility-map outdated | +| Operational access desk for dev workers | CLI-only; no guided flow or agent-facing routing surface | +| flex-auth policy before SSH sign | Inventory allow-list only; no authorization integration | +| Observable stewardship | SSH audit yes; routing/alignment maintenance not tracked | + +### Not started (INTENT evolution) + +| INTENT expectation | Notes | +| --- | --- | +| NetKingdom responsibility-map recognition | ops-warden still “out of scope” in net-kingdom map | +| Platform architecture diagram includes ops-warden SSH path | Not in `platform-identity-security-architecture.md` | +| NK-WP-0009 SSH tutorial linkage | Planned in net-kingdom, not wired to ops-warden | +| Policy-gated issuance | Future phase; needs design doc | +| MCP/HTTP cert request for agents | Future; CLI sufficient for now | + +--- + +## 4. Success criteria scorecard (from INTENT.md) + +| Criterion | Verdict | +| --- | --- | +| Worker knows which subsystem for each credential type | **No** — no canonical routing runbook | +| SSH access short-lived, inventoried, audited | **Yes (tooling)** — production inventory discipline pending | +| ops-bridge integrates via cert_command | **Yes (contract)** — live tunnel matrix not verified here | +| NetKingdom evolution reflected in ops-warden docs | **Partial** — OpenBao done; no ongoing sync process | +| Non-SSH secrets stay out of ops-warden | **Yes** — boundaries documented | + +**Score: 2 yes, 2 partial, 1 no** + +--- + +## 5. Completeness and reliability + +### Completeness vs INTENT — **C2 (Partial)** + +The central SSH use case is implemented. The new stewardship mission — NetKingdom +literacy, routing, alignment maintenance — is **declared in INTENT and SCOPE but +not yet operationalized** in wiki, net-kingdom cross-links, or worker-facing runbooks. + +**Satisfied expectations:** + +- SSH certificate issuance end-to-end (local backend) +- cert_command contract +- OpenBao-first production documentation + +**Broken / missing expectations:** + +- No credential routing guide for dev workers +- No NetKingdom alignment workstream execution +- No flex-auth integration path + +**Out of scope (correctly excluded):** + +- OpenBao cluster operations +- flex-auth policy authoring +- Object-storage STS vending + +### Reliability vs INTENT — **R2 (Tolerable)** + +Strong unit tests and scorecard for cert-side checks. Production reliance on +OpenBao SSH engine and multi-worker inventory patterns not yet demonstrated. +Consumers must expect manual operator steps for non-SSH credentials. + +--- + +## 6. Open gaps (prioritized) + +| Prio | Gap | Suggested outcome | +| --- | --- | --- | +| P1 | Credential routing runbook | `wiki/CredentialRouting.md` — decision tree for workers | +| P1 | NetKingdom cross-link patch | PR/note in net-kingdom responsibility-map + platform doc SSH path | +| P2 | Standard inventory templates | `wiki/ActorInventoryPatterns.md` + example `inventory.yaml` seed | +| P2 | OpenBao SSH engine ops checklist | Verify/mount roles; link railiance-platform procedures | +| P3 | flex-auth pre-sign design | `wiki/PolicyGatedSigning.md` — design only, no code yet | +| P3 | Registry capability update | Reflect stewardship in capability entry summary | +| P4 | Agent-facing routing | Evaluate `warden guide` CLI or doc-only desk page | +| P4 | NK-WP-0009 coordination | Joint tutorial: short-lived SSH for agents | + +Captured in **WARDEN-WP-0006**. + +--- + +## 7. Recommendations + +1. **Execute WARDEN-WP-0006** in order: routing runbook → NetKingdom + cross-links → inventory templates → OpenBao ops checklist. +2. **Keep SSH CLI stable** — stewardship work is docs/alignment first; defer + flex-auth code until design is reviewed. +3. **Coordinate net-kingdom** — small responsibility-map update is a + dependency for INTENT success criterion #4. +4. **Re-assess after WP-0006** — target C3/C4 completeness if routing runbook + and NetKingdom links land. + +--- + +## 8. Document map + +| File | Role | +| --- | --- | +| `INTENT.md` | Aspirational steward + SSH authority mission | +| `SCOPE.md` | Current implementation and planned stewardship scope | +| This file | Gap analysis snapshot | +| `workplans/WARDEN-WP-0006-*.md` | Execution plan | \ No newline at end of file diff --git a/workplans/WARDEN-WP-0006-netkingdom-alignment-and-access-stewardship.md b/workplans/WARDEN-WP-0006-netkingdom-alignment-and-access-stewardship.md new file mode 100644 index 0000000..40c8b50 --- /dev/null +++ b/workplans/WARDEN-WP-0006-netkingdom-alignment-and-access-stewardship.md @@ -0,0 +1,197 @@ +--- +id: WARDEN-WP-0006 +type: workplan +title: "NetKingdom Alignment and Operational Access Stewardship" +domain: custodian +repo: ops-warden +status: ready +owner: codex +topic_slug: custodian +planning_priority: high +planning_order: 6 +created: "2026-06-17" +updated: "2026-06-17" +state_hub_workstream_id: "a5c9f24b-1ad4-46da-bc8e-b99897f8e302" +--- + +# WARDEN-WP-0006 — NetKingdom Alignment and Operational Access Stewardship + +**Scope:** Close gaps identified in `history/2026-06-17-intent-scope-assessment.md` +between INTENT (operational access steward for NetKingdom security) and SCOPE +(shipped SSH CLI only). Documentation and alignment first; code changes limited +to optional CLI ergonomics. + +**Out of scope:** flex-auth integration implementation, OpenBao cluster deploy, +universal credential broker, net-kingdom INTENT.md rewrite. + +**References:** + +- `INTENT.md`, `SCOPE.md`, `history/2026-06-17-intent-scope-assessment.md` +- `net-kingdom/docs/platform-identity-security-architecture.md` +- `net-kingdom/docs/responsibility-map.md` +- `NK-WP-0009` (SSH tutorial, net-kingdom) + +--- + +## Goal + +After this workplan, a development worker or agent can: + +1. Read ops-warden material and know **which NetKingdom subsystem** handles each + credential type. +2. Obtain **SSH certs** via documented actor patterns and production OpenBao path. +3. Find ops-warden recognized in **NetKingdom responsibility/platform** docs as + the operational SSH credential authority. + +--- + +## Tasks + +### T1 — Credential routing runbook + +```task +id: WARDEN-WP-0006-T01 +status: todo +priority: high +state_hub_task_id: "ffc6a0c2-4312-4584-be7a-c8411cb01899" +``` + +Create `wiki/CredentialRouting.md`: + +- Decision tree: SSH vs runtime secret vs identity vs authorization vs tunnel +- Per-subsystem links (OpenBao, flex-auth, key-cape, ops-bridge, railiance-infra) +- Explicit “do not ask ops-warden for API keys” examples +- Link from `SCOPE.md`, `INTENT.md`, `README.md` + +**Done when:** A worker with no prior context can route a credential request in +under two minutes using this page alone. + +### T2 — Actor inventory patterns + +```task +id: WARDEN-WP-0006-T02 +status: todo +priority: high +state_hub_task_id: "3816463d-7dfd-469d-9324-fd7880b50608" +``` + +Create `wiki/ActorInventoryPatterns.md` with standard patterns: + +- Tunnel agents (`agt-*-bridge`) +- Kaizen / codex agents (`agt-codex-*`) +- CI automations (`atm-*`) +- Human admins (`adm-*`) +- TTL and principal narrowing guidance + +Optional: `examples/inventory.seed.yaml` (non-secret, Git-safe template). + +**Done when:** Adding a new dev worker actor does not require inventing naming +from scratch. + +### T3 — NetKingdom cross-links (ops-warden side) + +```task +id: WARDEN-WP-0006-T03 +status: todo +priority: high +state_hub_task_id: "f158366a-5746-48b8-acce-472dce8f925e" +``` + +- Add `wiki/NetKingdomSecurityMap.md` — condensed literacy table from INTENT +- Update `registry/capabilities/capability.security.ssh-certificate-issuance.md` + summary to mention stewardship/routing +- Update `.claude/rules/repo-boundary.md` with NetKingdom routing table + +**Done when:** ops-warden docs stand alone for NetKingdom operational access +orientation without reading net-kingdom first (but link to canon). + +### T4 — NetKingdom canon patch (coordination) + +```task +id: WARDEN-WP-0006-T04 +status: todo +priority: medium +state_hub_task_id: "e40e4395-8f01-4f79-a539-d0de8e427321" +``` + +Coordinate updates in `net-kingdom` (separate commit/PR there): + +- `docs/responsibility-map.md` — move ops-warden from pure out-of-scope to + **operational SSH credential dependency** +- `docs/platform-identity-security-architecture.md` — add Operational SSH Path + (ops-warden → ops-bridge → hosts) + +**Done when:** NetKingdom canon names ops-warden’s lane; ops-warden wiki links +back to the updated sections. + +**Note:** Requires `net-kingdom` repo write access; may need `needs_human` if +blocked on review. + +### T5 — OpenBao SSH engine operational checklist + +```task +id: WARDEN-WP-0006-T05 +status: todo +priority: medium +state_hub_task_id: "a94e20a2-970b-4a0c-bd23-8510b841b938" +``` + +Create `wiki/OpenBaoSshEngineChecklist.md`: + +- Prerequisites (OpenBao initialized/unsealed per railiance-platform) +- Role creation commands (from OpsWardenConfig) +- Token policy expectations (no root token in warden workflows) +- Verification: `warden sign` against production endpoint +- Failure modes and fallback boundaries + +**Done when:** Operator can verify production SSH signing path without +reconstructing steps from multiple repos. + +### T6 — Policy-gated signing design (design only) + +```task +id: WARDEN-WP-0006-T06 +status: todo +priority: low +state_hub_task_id: "b10a4b4d-bfa1-4f49-b6a5-f339f1e6a2e1" +``` + +Create `wiki/PolicyGatedSigning.md`: + +- flex-auth decision before `warden sign` — proposed flow +- Claims needed from IAM Profile +- What stays inventory-based in v1 vs policy-based in v2 +- Explicit non-implementation in this workplan + +**Done when:** Reviewable design exists; no code dependency. + +### T7 — Re-assess INTENT ↔ SCOPE + +```task +id: WARDEN-WP-0006-T07 +status: todo +priority: medium +state_hub_task_id: "ef8b5c57-2343-4cfc-9fee-48db1e56f69a" +``` + +After T1–T5 complete: + +- Update `history/2026-06-17-intent-scope-assessment.md` or add + `history/YYYYMMDD-intent-scope-reassessment.md` +- Refresh SCOPE.md Current State and completeness notes +- Run `make fix-consistency REPO=ops-warden` + +**Done when:** Completeness target C3+ documented with evidence. + +--- + +## Acceptance Criteria + +- [ ] `wiki/CredentialRouting.md` exists and is linked from README/SCOPE +- [ ] `wiki/ActorInventoryPatterns.md` exists +- [ ] `wiki/NetKingdomSecurityMap.md` exists +- [ ] NetKingdom responsibility-map recognizes ops-warden SSH lane (T4) +- [ ] OpenBao SSH checklist documented (T5) +- [ ] Policy-gated signing design drafted (T6) +- [ ] INTENT ↔ SCOPE re-assessment recorded (T7) +- [ ] `reuse-surface validate --root .` passes if registry entry changed \ No newline at end of file