ops-warden/wiki/ActorInventoryPatterns.md

# Actor Inventory Patterns

Date: 2026-06-17

Standard naming and TTL patterns for `~/.config/warden/inventory.yaml` (or
Git-tracked inventory in your environment). Actor names **must** use the prefix
matching `ActorType`: `adm-`, `agt-`, `atm-`.

See `wiki/AccessManagementDirective.md` for policy background and
`examples/inventory.seed.yaml` for a copy-paste template.

---

## Naming convention

```text
<type>-<scope>-<purpose>[-<instance>]
```

| Segment | Meaning |
| --- | --- |
| `type` | `adm` \| `agt` \| `atm` |
| `scope` | team, repo, or environment slug (`codex`, `state-hub`, `ci`) |
| `purpose` | narrow function (`bridge`, `bootstrap`, `backup`) |
| `instance` | optional disambiguator (`railiance01`) |

**Examples:** `agt-state-hub-bridge`, `agt-codex-interhub-bootstrap`, `atm-nightly-backup`.

---

## Pattern catalog

### Tunnel agents (`agt`)

Used by ops-bridge `cert_command` for SSH tunnels.

```yaml
agt-state-hub-bridge:
  type: agt
  principals: [agt-task-bridge]
  ttl_hours: 24
  description: "ops-bridge tunnel to state-hub backend"
```

- One actor per tunnel identity (match `ssh_user` / `actor` in `tunnels.yaml`).
- Principal should match host `auth_principals` entry deployed by railiance-infra.
- TTL default 24 h; shorten for high-risk paths.

### Kaizen / Codex agents (`agt`)

Attended or semi-attended agent work on trusted hosts.

```yaml
agt-codex-interhub-bootstrap:
  type: agt
  principals: [agt-interhub-bootstrap]
  ttl_hours: 2
  description: "Short-lived agent access for Inter-Hub bootstrap execution"
```

### Supervised interactive agent account (`agt-custodian`)

CUST-WP-0073-T02 / WARDEN-WP-0045. One principal for the dedicated host account
`custodian-agt` on Railiance01, shared by the Codex, Claude Code and Grok Build
harnesses running in the isolated workstation WSL distro `custodian-agents`.

```yaml
agt-custodian:
  type: agt
  principals: [agt-custodian]
  ttl_hours: 12
  max_ttl_hours: 12          # --ttl cannot raise it to the 24 h agt maximum
  extensions: [permit-pty]   # clears agent/port/X11 forwarding and user-rc
```

- **TTL 12 h.** Between the attended bootstrap profile (2 h) and the agt type
  maximum (24 h): one supervised working session, so a leaked cert expires by the
  next day and every new session needs a fresh supervisor issuance. The profile
  ceiling (`max_ttl_hours`) stops a `--ttl` override from lengthening it.
- **Extensions.** `permit-pty` only — interactive harness shells need a pty.
  Agent, port and X11 forwarding and `~/.ssh/rc` are not granted (`-O clear`
  locally; explicit `extensions` map on the Vault role, which must allow
  `permit-pty`).
- **No `source-address`.** The workstation egress IP is not stable (residential
  dynamic address, WSL NAT), so a pinned address would break issuance silently.
  Revisit if agent traffic moves to a fixed egress (VPN or bastion).
- **No self-issuance.** The supervisor (Bernd) signs from the operator account
  with `warden sign agt-custodian --pubkey <agent-key>.pub > <agent-key>-cert.pub`
  and places the cert into the `custodian-agents` distro. That distro gets no
  warden config, CA key, Vault token or `warden-sign` lane credential, so the
  signing path is not reachable from the agent account.
- Host mapping (`AuthorizedPrincipalsFile` for `custodian-agt`) is owned by
  railiance-infra.

- Prefer **1–2 h TTL** for bootstrap; never multi-day agent certs.
- Principal narrower than general ops access (`agt-interhub-bootstrap` not `agt-ops-full`).
- Remove or disable actor when lane is retired.
- See `wiki/InterHubBootstrapAccessLane.md`.

### Human operators (`adm`)

```yaml
adm-bernd:
  type: adm
  principals: [adm-full]
  ttl_hours: 48
  description: "Human operator — interactive shell when policy allows"
```

- Humans bring their own keypair (`ssh-keygen`); warden signs pubkey only.
- Use separate actors per person, not shared `adm-shared`.
- Principals may be narrowed (`adm-readonly`) where railiance-infra supports it.

### CI / cron automations (`atm`)

```yaml
atm-backup-daily:
  type: atm
  principals: [atm-backup-daily]
  ttl_hours: 8
  description: "Nightly backup automation — force-command on host"
```

- Lowest TTL practical (≤ 8 h per directive max).
- Principal tied to single force-command on host.
- Prefer `warden issue` only in secured CI secret store contexts.

---

## TTL guidance

| Type | Default max (warden) | Typical attended | Typical automation |
| --- | --- | --- | --- |
| `adm` | 48 h | 24–48 h | N/A |
| `agt` | 24 h | 1–4 h bootstrap | 8–24 h supervised |
| `atm` | 8 h | N/A | 1–8 h |

`warden sign` **rejects** TTL above type maximum (WARDEN-WP-0002).

---

## Principal narrowing

1. One principal per automation purpose — avoid `agt-ops-admin`.
2. Match host-side `auth_principals` exactly — coordinate with railiance-infra before add.
3. Document `description` field for audit and scorecard reviews.
4. Use `hosts:` section in inventory for reference (not enforced by warden).

---

## Adding a new worker

```bash
warden inventory add agt-myrepo-ci \
  --type agt \
  --principal agt-myrepo-ci \
  --ttl 4 \
  --description "CI deploy actor for myrepo"
warden inventory list
warden sign agt-myrepo-ci --pubkey /path/to/ci.pub
```

Copy patterns from `examples/inventory.seed.yaml` before inventing new names.

---

## Anti-patterns

| Do not | Why |
| --- | --- |
| Reuse `adm` actor for agents | Breaks attribution; use `agt-*` |
| Store private keys in inventory YAML | Inventory is registry only — keys live in secure paths |
| 72 h `agt` cert for convenience | Violates TTL policy and directive |
| One `agt-ops` for all tunnels | Cannot revoke or audit per tunnel |
| Put API keys in inventory | Route to OpenBao — `wiki/CredentialRouting.md` |