ops-warden/README.md

# ops-warden

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 `INTENT.md` for direction, `SCOPE.md` for current implementation, and
`wiki/AccessManagementDirective.md` for SSH policy. ops-warden issues SSH certs
and routes every other credential need to its owner — see `wiki/AccessRouting.md`.
Latest gap analysis: `history/2026-06-17-post-wp0007-reassessment.md`.

## Get the source (Forgejo)

Canonical repo: `https://forgejo.coulomb.social/coulomb/ops-warden`  
Releases: `https://forgejo.coulomb.social/coulomb/ops-warden/releases`

**HTTPS clone:**

```bash
git clone https://forgejo.coulomb.social/coulomb/ops-warden.git ~/ops-warden
cd ~/ops-warden
```

**SSH clone** (recommended for push/pull; add to `~/.ssh/config` if missing):

```sshconfig
Host forgejo-remote
    HostName 92.205.62.239
    Port 30022
    User git
    IdentityFile ~/.ssh/id_gitea
    StrictHostKeyChecking accept-new
```

```bash
git clone forgejo-remote:coulomb/ops-warden.git ~/ops-warden
cd ~/ops-warden
```

Legacy Gitea remotes (`gitea-remote`, `gitea.coulomb.social`) still work during
migration; new checkouts should use Forgejo.

## Install

From a Forgejo checkout:

**Recommended** (warden + experiential memory for route/worker/agent sessions):

```bash
make install-all
make verify-memory
```

SSH-only install (no phase-memory):

```bash
make install
```

Manual equivalent:

```bash
uv sync
uv tool install . --with-editable ../phase-memory --force
```

Or run without installing:

```bash
uv run warden --help
```

phase-memory must be a sibling checkout at `../phase-memory` by default, or set
`PHASE_MEMORY_REPO` when running make. Opt out of memory at runtime with
`WARDEN_MEMORY=0`.

### Upgrade after a release

When a new tag is published on Forgejo (e.g. `v0.1.2`):

```bash
cd ~/ops-warden
git fetch --tags origin
git pull --ff-only
make install-all
warden route list   # sanity check the installed CLI
```

If `warden` still behaves like an older build (same version string but missing
recent subcommands or fixes), clear the cached wheel and reinstall:

```bash
uv cache clean ops-warden
uv tool install . --with-editable ../phase-memory --reinstall --force
```

Check out a specific release:

```bash
git fetch --tags origin
git checkout v0.1.2
make install-all
```

## 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). Template: `examples/warden.production.example.yaml`.
See `wiki/OpsWardenConfig.md` and `wiki/OpenBaoSshEngineChecklist.md`.

## Routing lookup (`warden route`)

ops-warden issues SSH certs and **routes** every other credential need to its
owner. The `route` command group is a read-only lookup over the pointer catalog
(`registry/routing/catalog.yaml`) — it never calls another subsystem or returns
secrets.

```bash
warden route list [--all] [--json]                    # scenarios (active-only unless --all)
warden route list --stale [--stale-days 90] [--all]   # past review cadence
warden route show <id> [--json]                       # owner + wiki/canon pointers; SSH adds steps
warden route find "issue an api key"                  # rank scenarios by keyword overlap
```

Full role and examples: `wiki/AccessRouting.md`.

## Development

```bash
make install-all
make test
make lint
uv run pytest -m integration   # requires ssh-keygen in PATH
```

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

- `INTENT.md` — operational access steward mission (NetKingdom-aligned)
- `wiki/CredentialRouting.md` — which subsystem for each credential type
- `wiki/NetKingdomSecurityMap.md` — platform security component map
- `wiki/ActorInventoryPatterns.md` — standard adm/agt/atm actor patterns
- `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/`.