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:

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):

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

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):

make install-all
make verify-memory

SSH-only install (no phase-memory):

make install

Manual equivalent:

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

Or run without installing:

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):

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:

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

Check out a specific release:

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

Quick start (local backend)

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

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

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/.