# SPIKE — pool-scoped ACL for the FelhomAgent token (2026-07-01)

> **STATUS: IMPLEMENTED** in agent **v0.53.0** (`RestoreLXCOptions.Pool` / `reconcile.DefaultPool`, both
> restore sites) + host-install script **v1.6.0** (3-role scoped ACL, `--rescope-acl`, uninstall
> cleanup). The demo host felhom-pve was live-migrated (agent stopped → `--rescope-acl` → agent v0.53.0
> → start) and ALL residual gates passed under the scoped token: **PBS backup+restore (residual #1)**
> and **restore-test into pool (residual #2)** both succeed; blast-radius 403 confirmed on out-of-pool
> guests + ungranted storage. See the felhom.eu + felhom-agent REPORTs.

**Class:** SPIKE (empirical validation; no product code). **Repos read:** felhom-agent `33e3443` (v0.52.0,
read-only). **Host:** felhom-pve (192.168.0.162, node `demo-felhom`, PVE 9.2.2, **single-node**).
**Verdict: PASS** — the agent's 16 privileges CAN be scoped from `/` to `/pool/felhom` +
`/storage/<targets>` (+`Pool.Allocate`) without breaking the provision/backup/guest flow, and the scoped
token is provably contained to the pool. One caveat for 3b: the Datastore scope must include **all**
agent-touched storages (notably the offsite `felhom-pbs`), not just `local`/`local-lvm`.

The live `FelhomAgent` role / `felhom-agent@pve` token / its `/` ACL / guest 9201 were **never touched**;
all testing used a throwaway `felhom-spike@pve!spike` token + granular `FelhomSpike*` roles + scratch
vmid 9300, all removed at the end. Live agent verified healthy afterwards.

---

## 1. Confirmed real storage names (felhom-pve)

From the live agent config + `pvesm`:

| Role in the flow | Storage | Notes |
|---|---|---|
| **archive** (golden read source) | `local` | golden = `local:backup/vzdump-lxc-9100-2026_06_27-11_42_51.tar.zst` |
| **restore** (rootfs write target) | `local-lvm` | `backup.restore_storage` |
| **dump** (local backup write) | `local` | `backup.local_backup_target` |
| **offsite dump** (default DR target) | `felhom-pbs` | PBS, 2009/9239 GiB used — actively used; **agent writes here** |
| enrolled drives | `felhom-usb`, `felhom-flash` | dir storages; agent enumerates (Audit); not vzdump targets today |

**Finding:** archive and local-dump are the SAME storage (`local`). The full set of storages the agent
touches is **5**, not 2 — see §7 for the 3b implication.

## 2. Privilege-use map — empirical column (object path PROVEN sufficient)

All ops run **as the spike token** (`Authorization: PVEAPIToken=felhom-spike@pve!spike=…`) against
`https://127.0.0.1:8006/api2/json`. "Proven-sufficient path" = where the grant actually satisfied PVE.

| Agent op | Endpoint | Priv | Proven-sufficient object | Test |
|---|---|---|---|---|
| RestoreLXC (**+pool**) | POST `/nodes/{n}/lxc` restore=1 pool=felhom | VM.Allocate + Pool.Allocate | **`/pool/felhom`** | T1 ✅ 200 |
| " (disks) | " | Datastore.AllocateSpace | `/storage/local-lvm` | T1 ✅ |
| " (archive read) | " | Datastore.Audit/read | `/storage/local` | T1 ✅ |
| task status/log | GET `/nodes/{n}/tasks/{upid}/{status,log}` | Sys.Audit | **`/`** | T2 ✅ 200 (`stopped OK`) |
| SetConfig | PUT `…/config` | VM.Config.{Disk,CPU,Memory,Network,Options} | `/pool/felhom` | T3 ✅ |
| ResizeLXC | PUT `…/resize` | VM.Config.Disk | `/pool/felhom` | T3 ✅ |
| Snapshot / Delete | POST/DELETE `…/snapshot[/{s}]` | VM.Snapshot | `/pool/felhom` | T3 ✅ |
| RollbackSnapshot | POST `…/snapshot/{s}/rollback` | VM.Snapshot.Rollback | `/pool/felhom` | T3 ✅ |
| Start / Stop | POST `…/status/{start,stop}` | VM.PowerMgmt | `/pool/felhom` | T3 ✅ (stop 200 once running) |
| guest reads | GET `…/status/current`,`…/config`,`…/snapshot` | VM.Audit | `/pool/felhom` | T3 ✅ |
| Vzdump | POST `/nodes/{n}/vzdump` | VM.Backup + Datastore.AllocateSpace | guest `/pool/felhom` + `/storage/local` | T4 ✅ (`OK`) |
| DestroyLXC | DELETE `/nodes/{n}/lxc/{id}` purge=1 | VM.Allocate + Datastore.Allocate | `/pool/felhom` + `/storage/*` | T6 ✅ (`OK`) |
| Version | GET `/version` | (auth only) | — | T5 ✅ |
| ListNodes / NodeStatus | GET `/nodes`,`/nodes/{n}/status` | Sys.Audit | `/` | T5 ✅ |
| ListLXC | GET `/nodes/{n}/lxc` | VM.Audit | `/pool/felhom` (returns **filtered** list) | T5 ✅ (only pool guests) |
| ListStorage / NodeStorage | GET `/storage`,`/nodes/{n}/storage` | Datastore.Audit | `/storage/<s>` (returns **filtered** list) | T5 ✅ (**no box-wide grant needed**) |
| StorageContent | GET `/nodes/{n}/storage/{s}/content` | Datastore.Audit | `/storage/<s>` | T5 ✅ |

## 3. CRUX verdict (T1) — create-into-pool WORKS at `/pool/felhom`

`POST /nodes/demo-felhom/lxc` with `restore=1, vmid=9300 (brand-new), ostemplate=<golden>,
storage=local-lvm, pool=felhom` **→ HTTP 200** + `UPID:…:vzrestore:9300:felhom-spike@pve!spike:`.

A fresh, not-yet-existing vmid CAN be allocated **into** the pool with `VM.Allocate` + `Pool.Allocate`
granted only at `/pool/felhom` — **no** `VM.Allocate` at `/vms` or `/` was needed. This is the load-bearing
result: the intended design works, no fallback (the §3 fallbacks a/b/c were not needed). The restore then
ran to `stopped OK` and the guest was a pool member (visible only to the scoped token).

## 4. Recommended final ACL layout for 3b-impl

**Mechanism finding:** `pveum acl modify <path> -role <r>` grants the **whole role** at that path — you
cannot split one role's privileges across paths. So 3b needs **≥2 roles** (a scoped set + a tiny
box-wide read role), not the single `/`-applied role of today.

Recommended (validated except the felhom-pbs write grant — see §7):

```
# Role A — guest-scoped (applied at /pool/felhom, to BOTH user and token):
pveum role add FelhomAgentGuest -privs "VM.Allocate VM.Audit VM.Config.Disk VM.Config.CPU \
  VM.Config.Memory VM.Config.Network VM.Config.Options VM.PowerMgmt VM.Snapshot \
  VM.Snapshot.Rollback VM.Backup Pool.Allocate"
pveum acl modify /pool/felhom -user felhom-agent@pve            -role FelhomAgentGuest
pveum acl modify /pool/felhom -token 'felhom-agent@pve!agent'   -role FelhomAgentGuest

# Role B — storage write (applied at EACH agent-touched storage):
pveum role add FelhomAgentStore -privs "Datastore.Allocate Datastore.AllocateSpace Datastore.Audit"
for S in local local-lvm felhom-pbs ; do   # + felhom-usb/felhom-flash IF the agent ever vzdumps to them
  pveum acl modify /storage/$S -user felhom-agent@pve          -role FelhomAgentStore
  pveum acl modify /storage/$S -token 'felhom-agent@pve!agent' -role FelhomAgentStore
done

# Role C — box-wide reads (applied at /):
pveum role add FelhomAgentBase -privs "Sys.Audit SDN.Use"
pveum acl modify / -user felhom-agent@pve            -role FelhomAgentBase
pveum acl modify / -token 'felhom-agent@pve!agent'   -role FelhomAgentBase
```

Notes proven empirically:
- **`Datastore.Audit` does NOT need to be box-wide** — `GET /storage` returned a *filtered* 2-item list
  under the per-storage grants (200, showed only `local`+`local-lvm`). Keeping it per-storage is enough
  for the agent's ListStorage/NodeStorage/StorageContent.
- **Privsep intersection:** grant each role to BOTH the user AND the token (as the live install already
  does at `/`), else the token's effective perms are empty.
- Alternative if dynamic drive enrollment makes per-storage brittle: put **`Datastore.Audit` at `/`**
  (read-only, harmless) and keep only `Datastore.Allocate`/`AllocateSpace` per-storage. Not required by
  the tested flow; a robustness option.

## 5. Blast-radius proof (T7) — the scoped token CANNOT reach out-of-pool guests

Against guests NOT in the `felhom` pool, as the spike token:

```
GET  /nodes/demo-felhom/lxc/9001/config          -> 403  Permission check failed (/vms/9001, VM.Audit)
GET  /nodes/demo-felhom/lxc/9001/status/current  -> 403  Permission check failed (/vms/9001, VM.Audit)
PUT  /nodes/demo-felhom/lxc/9001/config          -> 403  Permission check failed (/vms/9001, VM.Config.Disk|VM.Config.CPU|…)
POST /nodes/demo-felhom/lxc/9100/status/start    -> 403  Permission check failed (/vms/9100, VM.PowerMgmt)
```

PVE checks `VM.*` against `/vms/<vmid>` and resolves the `/pool/felhom` grant **only for pool members**;
non-members get no grant → 403. Exactly the containment 3b wants. (Guest **9201** IS reachable by the
scoped token because 3a already adopted it into the `felhom` pool — expected and correct: pool membership
= managed.)

## 6. Per-test results (T1–T7)

| Test | Op | Result |
|---|---|---|
| **T1** | restore-into-pool (fresh vmid 9300, pool=felhom) | ✅ **200** + UPID (CRUX passes at `/pool/felhom`) |
| **T2** | task status + log read (own UPID) | ✅ 200 (`stopped OK`), log 200 |
| **T3** | config, resize, snapshot+rollback+delete, start, stop, reads | ✅ all 200 (stop=500 only when called mid-start; 200 once running → runtime, not auth) |
| **T4** | vzdump 9300 → `local` | ✅ 200 + task `OK` |
| **T5** | /version,/nodes,/nodes/{n}/status,/storage,/nodes/{n}/storage,{s}/content,/nodes/{n}/lxc | ✅ all 200; /storage + /lxc return **filtered** lists |
| **T6** | destroy 9300 (purge) | ✅ 200 + task `OK`, guest gone |
| **T7** | out-of-pool guest ops (9001, 9100) | ✅ **403** (contained) |

**No ACL widening was needed** — the proposed layout passed the entire flow on the first pass (for the
`local`/`local-lvm` storage set).

## 7. 3b-impl scope preview

**Agent (`felhom-agent`):**
- `RestoreLXCOptions` gains a `Pool string` field; `RestoreLXC` sets `v.Set("pool", opts.Pool)` when
  non-empty (mutate.go). Thread `Pool` through `BringUpSpec` → `runSelftestProvision`/`RunBringUp` so the
  provision restore lands in `felhom`. (Restore-into-pool is proven; this is the only new API param.)
- No other agent op needs change — all steady-state ops already target the guest, which is in the pool.

**Script (`felhom-host-install.sh` step_token, L~793 the two `/` grants):**
- Replace `PVE_PRIVS` broad-at-`/` grant with the 3-role layout of §4 (Guest@/pool/felhom,
  Store@each `/storage/<s>`, Base@/). Add `Pool.Allocate` (only in the Guest role).
- Storage list must be **`local local-lvm felhom-pbs`** at minimum (the offsite PBS default is a write
  target) — a plain `local`/`local-lvm` scope WOULD break the agent's offsite backup.
- `--uninstall` ACL removal (Spec 1 step 5) must delete the new scoped grants (3 roles × {user,token} ×
  their paths) instead of the two `/` grants, and delete the 3 roles (after their ACLs).
- `--adopt-pool` (3a) already puts existing guests in the pool → a retrofitted box's guest becomes
  reachable by the scoped token automatically once 3b ships.

## 8. NOT validated by this spike — 3b-impl / follow-up must verify

- **`felhom-pbs` (offsite) backup under a Store grant on `/storage/felhom-pbs`.** T4 validated vzdump to
  `local` only. Since PBS is the DEFAULT DR target, 3b-impl must include `/storage/felhom-pbs` in the
  Store scope AND validate a PBS backup + PBS verify + a restore-from-PBS under the scoped token before
  shipping. (High confidence it works — same Datastore.AllocateSpace mechanism — but unproven here.)
- **Drive storages** (`felhom-usb`/`felhom-flash`): the agent enumerates them (Datastore.Audit) and
  bind-mounts their data host-side (not a Datastore priv). If any future path vzdumps to a drive, that
  storage needs a Store grant. Dynamic drive enrollment may favor the "Datastore.Audit at `/`" variant.
- **Multi-node cluster:** felhom-pve is single-node. Pools + ACLs are cluster-wide in PVE, but 3b-impl
  must verify on the colleague's box (if a cluster) that a restore targeting a specific node with a
  `/pool/felhom` grant behaves identically (node is in the URL, not the ACL path — expected fine).
- **restore-test flow** (`--selftest=restore-test`) under scope: uses the 9990xx scratch band, which is
  NOT in `felhom` pool → its restore/destroy would 403 under the scoped token. **3b must either add the
  restore-test scratch guests to the pool, or grant the scratch-band a scope.** (Flagged — this is a real
  gap the core provision flow didn't exercise.)

## 9. Cleanup confirmation

All throwaway objects removed and verified: **0** spike ACL entries, **0** `FelhomSpike*` roles, **0**
`felhom-spike` users, scratch guest 9300 destroyed, its scratch vzdump freed, `/root/.spike-token`
deleted. Live state intact: `felhom-agent` **active**, `--selftest=read` **OK** (sees all 5 storages +
guests), `FelhomAgent` role present, guest **9201 running** and still the sole `felhom` pool member. The
spike token secret was never written to any committed file.
