From 9514ad914e8a53abde6bdc6d24c29d081bd1b95c Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 17 Jun 2026 07:33:49 +0200 Subject: [PATCH] WARDEN-WP-0004: repo hygiene and hub sync MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update SCOPE and README to reflect the shipped warden CLI, fill agent rules for stack/architecture/boundary, archive finished workplans 0001–0003, and register WP-0004 in State Hub. --- .claude/rules/architecture.md | 61 +++++++++++- .claude/rules/repo-boundary.md | 17 +++- .claude/rules/stack-and-commands.md | 32 +++++-- README.md | 65 ++++++++++++- SCOPE.md | 9 +- ...ARDEN-WP-0004-repo-hygiene-and-hub-sync.md | 93 +++++++++++++++++++ ...-WARDEN-WP-0001-initial-implementation.md} | 2 +- ...N-WP-0002-correctness-and-completeness.md} | 2 +- ...RDEN-WP-0003-test-coverage-and-quality.md} | 2 +- 9 files changed, 260 insertions(+), 23 deletions(-) create mode 100644 workplans/WARDEN-WP-0004-repo-hygiene-and-hub-sync.md rename workplans/{WARDEN-WP-0001-initial-implementation.md => archived/260515-WARDEN-WP-0001-initial-implementation.md} (99%) rename workplans/{WARDEN-WP-0002-correctness-and-completeness.md => archived/260515-WARDEN-WP-0002-correctness-and-completeness.md} (99%) rename workplans/{WARDEN-WP-0003-test-coverage-and-quality.md => archived/260515-WARDEN-WP-0003-test-coverage-and-quality.md} (99%) diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md index 7c2a645..bb1748e 100644 --- a/.claude/rules/architecture.md +++ b/.claude/rules/architecture.md @@ -1,8 +1,63 @@ ## Architecture - +ops-warden owns **credential issuance only** — CA signing, actor inventory, TTL +policy, and cert-side compliance checks. It does not manage tunnels, host SSH +config, or long-lived API keys. + +### Module layout + +``` +src/warden/ +├── cli.py # Typer commands: sign, issue, status, scorecard, cleanup, log, inventory +├── models.py # ActorType, CertSpec, CertRecord, TTL policy +├── config.py # ~/.config/warden/warden.yaml loader +├── ca.py # LocalCA (ssh-keygen -s), CABackend base, signatures log, eviction +├── vault.py # VaultCA — Vault/OpenBao SSH secrets engine API +├── inventory.py # inventory.yaml load/save +├── scorecard.py # §5 cert-side compliance checks +└── scripts/ + └── ops_ssh_wrapper.py # WARDEN_ACTOR + ssh-add + exec wrapper +``` + +### Backend selection + +Config key `backend: local | vault` selects the CA implementation. Both expose the +same CLI and `cert_command` contract — callers (principally `ops-bridge`) never +branch on backend. + +### Signing flow + +``` +warden sign --pubkey + → load_config() + load_inventory() + → validate actor name prefix (adm-/agt-/atm-) + → enforce_ttl() against ActorType max + → CABackend.sign(CertSpec) + → evict previous cert for actor + → sign (ssh-keygen -s or Vault API) + → write cert to state_dir (mode 600) + → append signatures.log (JSONL) + → cert text on stdout (cert_command contract) +``` + +### External integrations + +| Integration | Role | +|-------------|------| +| `ssh-keygen` | Local CA signing and cert metadata parsing | +| Vault/OpenBao SSH engine | Production signing via HTTP API (`vault.py`) | +| `ops-bridge` | Primary consumer of `warden sign` via `cert_command` | +| `railiance-infra` | Host-side `/etc/ssh/auth_principals/` deployment (out of scope here) | + +### cert_command contract + +``` +warden sign --pubkey +``` + +Writes signed certificate to stdout. Non-zero exit on failure. Documented in +`wiki/CertCommandInterface.md`. ## Quick Reference -`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference +`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference \ No newline at end of file diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md index aca5f69..8b0715e 100644 --- a/.claude/rules/repo-boundary.md +++ b/.claude/rules/repo-boundary.md @@ -2,7 +2,16 @@ This repo owns **ops-warden** only. It does not own: - +| Concern | Owner | +|---------|-------| +| Tunnel lifecycle, `cert_command` wiring in tunnels | `ops-bridge` | +| Host SSH principal files, force-command wrappers | `railiance-infra` | +| Vault/OpenBao cluster deployment and unseal ceremony | `railiance-platform` | +| Inter-Hub operator API keys, provider API keys (e.g. OpenRouter) | OpenBao / operator secret store | +| State Hub service code and consistency tooling | `state-hub` | +| Workstream coordination across custodian domain | `the-custodian` | +| Human admin SSH key generation | self-service (`ssh-keygen`) | + +ops-warden issues **short-lived SSH certificates** only. It is not a general +secrets manager and must not store long-lived API keys in Git, State Hub, or +workplans. \ No newline at end of file diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index dc53ac6..a41d038 100644 --- a/.claude/rules/stack-and-commands.md +++ b/.claude/rules/stack-and-commands.md @@ -1,19 +1,35 @@ ## Stack - -- **Language:** -- **Key deps:** +- **Language:** Python 3.11+ +- **CLI:** Typer + Rich +- **Key deps:** pyyaml, httpx (Vault/OpenBao API); ssh-keygen subprocess (local CA) +- **Packaging:** hatchling + uv ## Dev Commands ```bash -# TODO: Fill in the standard commands for this repo - # Install dependencies +uv sync -# Run tests +# Run unit tests (integration tests excluded by default) +uv run pytest -# Lint / type check +# Run real ssh-keygen integration tests +uv run pytest -m integration -# Build / package (if applicable) +# Lint +uv run ruff check . + +# Install CLI locally +uv tool install . + +# CLI help +warden --help +ops-ssh-wrapper --help # after install ``` + +Config and state paths: + +- `~/.config/warden/warden.yaml` — backend selection (`local` | `vault`) +- `~/.config/warden/inventory.yaml` — actor registry +- `~/.local/state/warden/` — certs, keys, `signatures.log` \ No newline at end of file diff --git a/README.md b/README.md index fcd7b8f..b0fee74 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,64 @@ -# repo-seed +# ops-warden -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +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. + +## Install + +```bash +uv sync +uv tool install . +``` + +Or run without installing: + +```bash +uv run warden --help +``` + +## Quick start (local backend) + +```bash +# One-time: generate a CA key (keep mode 600, never commit) +ssh-keygen -t ed25519 -f ~/.ssh/ops-ca-user -C "Ops SSH User CA" -N "" + +# Configure warden (~/.config/warden/warden.yaml) — see wiki/OpsWardenConfig.md +warden inventory add agt-example --type agt --principal agt-example +warden sign agt-example --pubkey ~/.ssh/id_ed25519.pub +warden status agt-example +warden scorecard +``` + +Production uses the `vault` backend against OpenBao or HashiCorp Vault (Vault-compatible +SSH secrets engine API). See `wiki/OpsWardenConfig.md`. + +## Development + +```bash +uv sync +uv run pytest # unit tests (integration excluded) +uv run pytest -m integration # requires ssh-keygen in PATH +uv run ruff check . +``` + +## Key paths + +| Path | Purpose | +|------|---------| +| `~/.config/warden/warden.yaml` | Backend and CA/Vault settings | +| `~/.config/warden/inventory.yaml` | Actor → principals registry | +| `~/.local/state/warden/` | Signed certs, keys, `signatures.log` | + +## Documentation + +- `wiki/OpsWardenConfig.md` — configuration reference +- `wiki/CertCommandInterface.md` — `cert_command` contract for callers +- `wiki/InterHubBootstrapAccessLane.md` — short-lived cert envelope for bootstrap tasks + +## Workplans + +Active and proposed work lives in `workplans/`. Finished plans are archived under +`workplans/archived/`. \ No newline at end of file diff --git a/SCOPE.md b/SCOPE.md index 9b6dfbe..4377d2d 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -73,8 +73,11 @@ backend is in use. ## Current State -- Status: planned — WARDEN-WP-0001 not yet started -- Implementation: scaffolding only (models, config, CA, inventory, scorecard, CLI stubs) +- 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` +- Active maintenance: WARDEN-WP-0004 (repo hygiene); follow-ups tracked separately + for OpenBao doc alignment and capability registry publish --- @@ -129,4 +132,4 @@ keywords: [ssh, certificate, ca, credential, warden, ops-warden, pki, vault] - Config files: `~/.config/warden/warden.yaml`, `~/.config/warden/inventory.yaml` - State: `~/.local/state/warden/` (certs, generated keypairs) - Entry point: `warden --help` -- Workplan: `workplans/WARDEN-WP-0001-initial-implementation.md` +- Workplans: `workplans/` (active); `workplans/archived/` (finished) diff --git a/workplans/WARDEN-WP-0004-repo-hygiene-and-hub-sync.md b/workplans/WARDEN-WP-0004-repo-hygiene-and-hub-sync.md new file mode 100644 index 0000000..93cedf8 --- /dev/null +++ b/workplans/WARDEN-WP-0004-repo-hygiene-and-hub-sync.md @@ -0,0 +1,93 @@ +--- +id: WARDEN-WP-0004 +type: workplan +title: "OpsWarden Repo Hygiene and Hub Sync" +domain: custodian +repo: ops-warden +status: finished +owner: codex +topic_slug: custodian +created: "2026-06-17" +updated: "2026-06-17" +state_hub_workstream_id: "3c4b6e68-550a-4fc6-a804-95f1f68936c3" +--- + +# WARDEN-WP-0004 — Repo Hygiene and Hub Sync + +**Scope:** Bring repo orientation docs and agent rules in line with the shipped +`warden` CLI (WARDEN-WP-0001 through 0003 complete). Archive finished workplans +and sync State Hub. + +**Out of scope:** OpenBao doc alignment (WARDEN-WP-0005), capability registry +publish, task-status canon migration in AGENTS.md. + +--- + +## Goal + +After this workplan, a new agent session can orient from accurate local files +without reading stale "planned / scaffolding only" language, and State Hub +reflects archived workplan status. + +--- + +## Tasks + +### T1 — Update orientation docs + +```task +id: WARDEN-WP-0004-T01 +status: done +priority: high +state_hub_task_id: "f9d3926c-8637-411c-a477-2960b754704c" +``` + +- [x] `SCOPE.md` Current State reflects shipped CLI (v0.1.0, workplans 0001–0003 done) +- [x] `README.md` replaces repo-seed template with install, config, and dev commands + +### T2 — Fill agent rules + +```task +id: WARDEN-WP-0004-T02 +status: done +priority: medium +state_hub_task_id: "86c764a5-62fc-45fe-a8d2-332d6554a976" +``` + +- [x] `.claude/rules/stack-and-commands.md` — stack and `uv` dev commands +- [x] `.claude/rules/architecture.md` — module layout and data flow +- [x] `.claude/rules/repo-boundary.md` — adjacent repo ownership + +### T3 — Archive finished workplans + +```task +id: WARDEN-WP-0004-T03 +status: done +priority: medium +state_hub_task_id: "d3e54e63-ce98-4632-bc08-0e2667f19f12" +``` + +- [x] Move WARDEN-WP-0001/0002/0003 to `workplans/archived/` with date prefix +- [x] Set frontmatter `status: archived` on moved files + +### T4 — Sync State Hub + +```task +id: WARDEN-WP-0004-T04 +status: done +priority: medium +state_hub_task_id: "51729695-262f-4fe4-9c38-f99ee046d32a" +``` + +- [x] Run `make fix-consistency REPO=ops-warden` from state-hub +- [x] Verify `.custodian-brief.md` reflects archived workstreams + +--- + +## Acceptance Criteria + +- [x] `SCOPE.md` no longer says "planned" or "scaffolding only" +- [x] `README.md` documents `uv sync`, `uv run pytest`, and `warden --help` +- [x] Agent rules have no empty TODO blocks for stack, architecture, or boundary +- [x] Only WARDEN-WP-0004 remains in `workplans/` root (archived plans moved) +- [x] `make fix-consistency REPO=ops-warden` completes without error \ No newline at end of file diff --git a/workplans/WARDEN-WP-0001-initial-implementation.md b/workplans/archived/260515-WARDEN-WP-0001-initial-implementation.md similarity index 99% rename from workplans/WARDEN-WP-0001-initial-implementation.md rename to workplans/archived/260515-WARDEN-WP-0001-initial-implementation.md index 1761cea..0329a60 100644 --- a/workplans/WARDEN-WP-0001-initial-implementation.md +++ b/workplans/archived/260515-WARDEN-WP-0001-initial-implementation.md @@ -4,7 +4,7 @@ type: workplan title: "OpsWarden Initial Implementation" domain: custodian repo: ops-warden -status: done +status: archived owner: Bernd topic_slug: custodian created: "2026-03-28" diff --git a/workplans/WARDEN-WP-0002-correctness-and-completeness.md b/workplans/archived/260515-WARDEN-WP-0002-correctness-and-completeness.md similarity index 99% rename from workplans/WARDEN-WP-0002-correctness-and-completeness.md rename to workplans/archived/260515-WARDEN-WP-0002-correctness-and-completeness.md index 5b45277..294628b 100644 --- a/workplans/WARDEN-WP-0002-correctness-and-completeness.md +++ b/workplans/archived/260515-WARDEN-WP-0002-correctness-and-completeness.md @@ -4,7 +4,7 @@ type: workplan title: "OpsWarden Correctness and Operational Completeness" domain: custodian repo: ops-warden -status: done +status: archived owner: Bernd topic_slug: custodian planning_priority: high diff --git a/workplans/WARDEN-WP-0003-test-coverage-and-quality.md b/workplans/archived/260515-WARDEN-WP-0003-test-coverage-and-quality.md similarity index 99% rename from workplans/WARDEN-WP-0003-test-coverage-and-quality.md rename to workplans/archived/260515-WARDEN-WP-0003-test-coverage-and-quality.md index 54e65d5..3022cd3 100644 --- a/workplans/WARDEN-WP-0003-test-coverage-and-quality.md +++ b/workplans/archived/260515-WARDEN-WP-0003-test-coverage-and-quality.md @@ -4,7 +4,7 @@ type: workplan title: "OpsWarden Test Coverage and Code Quality" domain: custodian repo: ops-warden -status: done +status: archived owner: Bernd topic_slug: custodian planning_priority: medium