generated from coulomb/repo-seed
WARDEN-WP-0004: repo hygiene and hub sync
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.
This commit is contained in:
@@ -1,8 +1,63 @@
|
||||
## Architecture
|
||||
|
||||
<!-- TODO: Describe the key design decisions and component structure.
|
||||
Key modules, data flows, external integrations, state machines, etc. -->
|
||||
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 <actor> --pubkey <path>
|
||||
→ 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 <actor-name> --pubkey <path>
|
||||
```
|
||||
|
||||
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
|
||||
@@ -2,7 +2,16 @@
|
||||
|
||||
This repo owns **ops-warden** only. It does not own:
|
||||
|
||||
<!-- TODO: List what belongs in adjacent repos, e.g.:
|
||||
- SSH key management → railiance-infra/
|
||||
- State hub code → state-hub/
|
||||
-->
|
||||
| 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.
|
||||
@@ -1,19 +1,35 @@
|
||||
## Stack
|
||||
|
||||
<!-- TODO: Fill in language, frameworks, and key dependencies -->
|
||||
- **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`
|
||||
65
README.md
65
README.md
@@ -1,3 +1,64 @@
|
||||
# repo-seed
|
||||
# ops-warden
|
||||
|
||||
A git repository template to bootstrap coulomb projects from.
|
||||
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/`.
|
||||
9
SCOPE.md
9
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)
|
||||
|
||||
93
workplans/WARDEN-WP-0004-repo-hygiene-and-hub-sync.md
Normal file
93
workplans/WARDEN-WP-0004-repo-hygiene-and-hub-sync.md
Normal file
@@ -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
|
||||
@@ -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"
|
||||
@@ -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
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user