generated from coulomb/repo-seed
tegwick
9514ad914e
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.
63 lines
2.1 KiB
Markdown
63 lines
2.1 KiB
Markdown
## 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 <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 |