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