## 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