felhom.eu/REPORT.md

felhom.eu — task reports

Overwrite this file with a summary of the most recent task only (uniform with the other repos; not cumulative). The cumulative hub history lives in hub/CHANGELOG.md; the scripts history lives in scripts/CHANGELOG.md.

---

REPORT — pool-scoped token ACL (3-role) + --rescope-acl retrofit (host-install v1.6.0)

Date: 2026-07-01 · Repo: felhom.eu (scripts/ + documentation/)

Colleague-safety batch #4 phase b (script half; agent half = v0.53.0). Moves the agent token's dangerous privileges off / to /pool/felhom + /storage/<targets>, so on a shared box the token can only touch Felhom's own guests + storages. Implements documentation/audits/SPIKE-pool-scoped-acl-2026-07-01.md (PASS) and live-migrated the demo host.

1. Baseline → target

script v1.5.0 @ 554845b → v1.6.0. Paired with agent v0.53.0 (separate repo).

2. Files changed + commits

• scripts/felhom-host-install.sh (v1.5.0 → v1.6.0), scripts/CHANGELOG.md — commit 741f322.
• documentation/audits/SPIKE-pool-scoped-acl-2026-07-01.md — status → IMPLEMENTED (this commit).
• REPORT.md — this file.

3. What shipped

• 3-role scoped ACL (step_token rewrite): FelhomAgentGuest (VM.*+Pool.Allocate)@/pool/felhom, FelhomAgentStore (Datastore.*)@each PVE_STORAGES (default local local-lvm felhom-pbs; --acl-storages overrides), FelhomAgentBase (Sys.Audit SDN.Use)@/ — each to BOTH user + token. Pool ensured before the grants; the pre-3b broad / grant+role removed if present.
• --rescope-acl retrofit mode (add-before-remove; supervised). --uninstall removes both the scoped and the old shapes. Post-provision pool_add_guest dropped (agent restore --pool owns it).
• bash -n + shellcheck clean (0 new warnings; the 2 pre-existing SC2015 in step_verify unchanged).

4. Tests → §7

#	Scenario	Result
T-A	fresh install (dry-run)	✅ pool-before-token; 3 roles created once; scoped grants incl. /storage/felhom-pbs (transcript)
T-E	--rescope-acl (dry-run + LIVE)	✅ dry-run shows add-scoped→remove-old; live-run on felhom-pve applied it
T-F	--uninstall (dry-run)	✅ removes old-shape FelhomAgent grant+role (scoped tolerated-absent), pool not-empty skip
T-B/C/D	provision-into-pool / PBS / restore-test under scope	✅ live (see §6)
T-D-neg	blast-radius	✅ live 403 on non-pool guests + ungranted storage

5. Served script version

curl -fsSL https://felhom.eu/scripts/felhom-host-install.sh | grep SCRIPT_VERSION → 1.6.0.

6. Supervised swap on felhom-pve — executed + ALL gates PASS

stop felhom-agent → --rescope-acl --vmid 9201 (added the 3 scoped roles+grants; removed the old broad FelhomAgent / grant+role) → deploy agent v0.53.0 → start. Then, all under the scoped token: selftest=read OK (now sees only the pool guest + 3 scoped storages); provision-into-pool of scratch 9300 (boot+running, in pool); PBS backup→felhom-pbs + restore-from-PBS→9301 (both 200/OK — residual #1); restore-test scratch into pool (pass — residual #2); blast-radius 403 on non-pool guests 9001/9100 + ungranted storage felhom-usb; 9201 running + controller healthy + hub link OK. All scratch cleaned up; .bak-0.52.0 rollback binary retained; pool = [9201]. Details in felhom-agent/REPORT.md.

7. REQUIRED operator follow-up (fresh installs)

The served hub artifact manifest still advertises agent 0.52.0. A fresh v1.6.0 install (scoped ACL) is only correct with agent ≥ v0.53.0 (restore --pool) — with 0.52.0 the guest restores OUTSIDE the pool and the scoped token 403s on it. An operator must set the manifest to agent 0.53.0 / sha 9d1ef8298dcc5090936afa1b88f1612c0b5f03a62548ebbe0989d34d6622aa61 in the hub UI (dropdown, auto-sha — hub v0.29.0). Agent 0.53.0 is already published to Gitea. The demo swap didn't depend on this (binary deployed directly).

8. NOT yet live-validated — awaiting supervised run

• The colleague's-box migration (single-node; a later supervised repeat of §6 once the manifest serves 0.53.0).

9. Observations

• Multi-node: pools + ACLs are cluster-wide in PVE; felhom-pve is single-node so the restore-targets-a- node behaviour under a /pool/felhom grant is unverified on a cluster (node is in the URL, not the ACL path — expected fine; verify on the colleague's box if it's a cluster).
• Colleague-safety batch is now COMPLETE through #4 (uninstall, CPU/mem cap, pool-default, pool-scoped ACL).