Initial Commit

2026-03-28 00:45:43 +00:00
parent a436a7569d
commit 5ae6b988aa
23 changed files with 2400 additions and 0 deletions
--- a/wiki/OpsWardenConfig.md
+++ b/wiki/OpsWardenConfig.md
@@ -0,0 +1,147 @@
+# OpsWarden Configuration Reference
+
+Config file: `~/.config/warden/warden.yaml` (override with `WARDEN_CONFIG` env var)
+
+---
+
+## Local Backend (lab / non-Vault)
+
+```yaml
+# Backend selection. "local" uses ssh-keygen -s with a CA key on disk.
+backend: local
+
+# Path to the CA private key. Keep this file mode 600 and never commit it.
+ca_key: ~/.ssh/ops-ca-user
+
+# Path to the principals inventory (default shown).
+inventory_path: ~/.config/warden/inventory.yaml
+
+# Where to store signed certs and generated keypairs (default shown).
+state_dir: ~/.local/state/warden
+```
+
+### Bootstrapping the local CA key
+
+```bash
+# Generate CA keypair once (offline, secure location)
+ssh-keygen -t ed25519 -f ~/.ssh/ops-ca-user -C "Ops SSH User CA (2026)" -N ""
+chmod 600 ~/.ssh/ops-ca-user
+chmod 644 ~/.ssh/ops-ca-user.pub
+
+# Distribute ops-ca-user.pub to every host:
+#   TrustedUserCAKeys /etc/ssh/ca/ca_user.pub  (in sshd_config)
+# See railiance-infra bootstrap-ssh-ca.yml playbook.
+```
+
+---
+
+## Vault Backend (production)
+
+```yaml
+backend: vault
+
+vault:
+  # Vault server address.
+  addr: https://vault.example.com
+
+  # Vault SSH secrets engine mount path (default: ssh).
+  mount: ssh
+
+  # Map from ActorType to Vault signing role name.
+  role_map:
+    adm: adm-role
+    agt: agt-role
+    atm: atm-role
+
+  # Environment variable holding the Vault token (default: VAULT_TOKEN).
+  token_env: VAULT_TOKEN
+
+inventory_path: ~/.config/warden/inventory.yaml
+state_dir: ~/.local/state/warden
+```
+
+### Vault setup snippet
+
+```bash
+vault secrets enable ssh
+vault write ssh/roles/agt-role \
+    key_type=ca \
+    allowed_users="*" \
+    allow_user_certificates=true \
+    default_user="agt" \
+    ttl=24h max_ttl=24h
+
+export VAULT_TOKEN=$(vault token create -field=token)
+```
+
+---
+
+## Principals Inventory (`inventory.yaml`)
+
+```yaml
+actors:
+  # Actor name must carry the prefix matching its type:
+  #   adm-*  for adm, agt-*  for agt, atm-*  for atm
+  agt-state-hub-bridge:
+    type: agt
+    # Principals embedded in the cert; matched against /etc/ssh/auth_principals/%u
+    principals:
+      - agt-task-bridge
+    # Certificate TTL in hours. Defaults: adm=48, agt=24, atm=8
+    ttl_hours: 24
+    description: "ops-bridge tunnel agent for state-hub"
+
+  adm-bernd:
+    type: adm
+    principals:
+      - adm-full
+    ttl_hours: 48
+
+  atm-backup-daily:
+    type: atm
+    principals:
+      - atm-backup-daily
+    ttl_hours: 8
+    description: "nightly backup automation"
+
+hosts:
+  # Optional: documents which principals are allowed on each host.
+  # Not enforced by warden; used for reference and future tooling.
+  coulombcore:
+    allowed_principals:
+      agt:
+        - agt-task-bridge
+      atm:
+        - atm-backup-daily
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `WARDEN_CONFIG` | `~/.config/warden/warden.yaml` | Config file path |
+| `VAULT_TOKEN` | — | Vault token (vault backend only; env var name is configurable) |
+
+---
+
+## cert_command integration with ops-bridge
+
+Add `cert_command` to a tunnel in `~/.config/bridge/tunnels.yaml`:
+
+```yaml
+tunnels:
+  state-hub-coulombcore:
+    host: coulombcore
+    remote_port: 8001
+    local_port: 8000
+    ssh_user: agt-state-hub-bridge
+    ssh_key: ~/.ssh/agt-state-hub-bridge_ed25519
+    actor: agt-state-hub-bridge
+    cert_command: "warden sign agt-state-hub-bridge --pubkey ~/.ssh/agt-state-hub-bridge_ed25519.pub"
+```
+
+`ops-bridge` runs `cert_command` before each SSH launch, captures stdout as the cert,
+and passes it alongside the private key via `ssh -i <key> -i <cert>`.
+See `wiki/CertCommandInterface.md` for the full contract.