felhom-controller/REPORT.md

REPORT — v0.113.0: NAS verify-before-commit + page redesign + protocol-honest guidance

Date: 2026-07-11 · Version: controller v0.113.0 (from v0.112.0) · Pairs with: agent v0.81.0 + felhom.eu host-install v1.13.0 Spec: TASK — NAS verify-before-commit + page redesign + protocol-honest guidance Evidence base: felhom.eu/documentation/audits/SPIKE-nas-verify-2026-07-11.md (b57f6c1)

Confirmed baselines → shipped

Repo	Baseline (main)	Shipped commits	Version
felhom-agent	300f06722b (v0.80.0)	added9d	v0.81.0 — deployed on felhom-pve
felhom-controller	3db9126121 (v0.112.0)	bb8737a (orchestration) + a65dcff (UI) + this docs commit	v0.113.0 — live on 9201
felhom.eu	e80e14d6	27e2fb0	host-install v1.13.0 + feature doc

What shipped (files)

Agent (added9d) — internal/storage/netmount.go (NFS retry=0 + exported NetworkMountedAt/NetworkEndpointReachable), NEW internal/storage/netverify.go (ClassifyNetVerifyFailure, Q4-verbatim table), NEW internal/localapi/netverifyjob.go (in-memory single-slot detached verify + auto-rollback + GET /netstorage/verify-status), internal/localapi/netstorage.go (sync fast-fail: full validation + 2 s TCP pre-probe before ANY install; verify-job start), server.go (seams + route). No new sudoers grants — journal read is unprivileged via the systemd-journal group.

Controller (bb8737a + a65dcff) — internal/agentapi/client.go (verify fields, typed NetAddRefusedError, NetVerifyStatus), NEW internal/web/netprobe.go + netprobe_linux.go + netprobe_other.go (uid-1000 re-exec probe; --netprobe hidden mode in cmd/controller/main.go), NEW internal/web/netstorage_job.go (detached single-flight orchestration + §3.2 Hungarian map), netstorage_handlers.go (job-start add + status endpoint + orphan rows + netListFn seam), storage_handlers.go (route), templates/storage_network.html (full redesign).

felhom.eu (27e2fb0) — scripts/felhom-host-install.sh v1.13.0 (usermod -aG systemd-journal felhom-agent, idempotent; header/const drift v1.11.0-vs-1.12.0 fixed), NEW documentation/controller/network-storage-nas.md (authoritative feature doc).

Tests + companion red-proofs (all: mutation run → FAIL observed → reverted → suite green)

Test funcs added: agent storage +3 (netverify_test.go incl. the pure networkMountedIn table), agent localapi +5 (netverifyjob_test.go), controller web +9 (netstorage_job_test.go + storage_network_template_test.go).

#	Test	Red-proof mutant	Observed failure (verbatim core)
A1	TestMountOptions_NFSRetry0_SMBWithout (+ NFS rendering test)	reverted retry=0	NFS options missing retry=0 (Q4-vi): "vers=4.1,...,_netdev"
A2	TestClassifyNetVerifyFailure (Q4-verbatim table incl. merged nfs_export + empty-journal degradation)	exit-code classifier (return mount_failed — everything is rc=32)	every non-generic row: = "mount_failed", want "unreachable"/... — an exit-code mutant cannot split smb_auth/smb_share
A3	TestNetVerify_MountFailed_RollsBackAndClassifies (+ journal-unavailable sibling)	rollback call dropped	RemoveNetworkMount not called for the failed install: removed=[] + creds file must be removed
A4	TestNetVerify_TruthTable (§8: ReadDir-ok+unmounted=FAIL; EACCES+mounted=OK)	readability-based verdict (terr == nil)	BOTH rows failed: a readable-but-unmounted path must FAIL verify, got done / unreadable-but-mounted must PASS, got failed
A5	TestNetVerify_UnreachablePreProbe_InstallsNothing	pre-probe skipped	unreachable add: got 200 want 502 (the install would have run)
A6	TestNetVerify_SingleFlight_AndNoJobShape	running-check dropped	second add while verifying: got 200 want 409
C1	TestNetAdd_HappyPath_RegisterOnlyAfterProbe	register moved BEFORE the probe	phase = failed (category=register_failed detail=... already registered) + C2's must NOT be registered (got 1 paths)
C2	TestNetAdd_ProbeFail_RollsBackNotRegistered	rollback dropped	probe-fail must roll the agent install back: removes=[]
C3	TestNetAdd_AgentVerifyFailed_MappedMessage	(kill-surface shared with C4's mutant)	asserts the EXACT §3.2 merged nfs_export string + probe-not-run + no controller double-remove
C4	TestNetAdd_VerifyLost_RollsBack	none treated as success	probe must not run when the verify was lost
C5	TestNetProbeChild (ok / unwritable→2→not_writable / nonce-tamper→3→probe_io / cleanup-fail→4=OK+warn)	— (pure child body + verdict table; Credential wiring live-validated in Scenario C)	—
C6	TestNetAdd_SingleFlight	acquire check dropped	second add: got 200 want 409
C7	TestNetStorage_OrphanRow	orphan sweep disabled (registry-only filter)	items = 1, want 2 (registered + orphan)
C8	TestStorageNetworkTemplate_CanonicalClasses (renders through the PRODUCTION template tree)	form-input reintroduced	rendered page still contains the banned pattern "form-input"

Green gates: agent go build && go vet && go test ./... PASS (one hit of the KNOWN TestGenerateRecoveryCode wordlist flake — clean on re-run, pre-documented); controller full suite PASS; template_id_gate.py + emoji_gate.py green.

Deployed + verified

• Agent v0.81.0 on felhom-pve: .bak-0.80.0 kept; usermod -aG systemd-journal felhom-agent applied BEFORE restart; felhom-agent --version → 0.81.0; id felhom-agent → groups=990(felhom-agent),999(systemd-journal); journal shows a clean start (enrolled drive bound under shared parent, local-api listening, hub desired-state gen 10, no capability degradation).
• Controller v0.113.0 on 9201 (golden/bootstrap mechanism): docker ps → gitea.dooplex.hu/admin/felhom-controller:0.113.0 Up (healthy).

Live validation (anti-F9: the exact endpoint the UI invokes)

Method: curl from inside guest 9201 to the controller container (http://172.17.0.2:8080 + Host: felhom.demo-felhom.eu — the dashboard is host-routed; the demo has no password so auth/CSRF do not apply) — POST /api/storage/netstorage/add + status-poll, the byte-identical server pipeline behind the UI; the residual is client-side rendering only. Sim NAS = isolated /srv/nas-spike3/* on DooPlex (.bak-nasspike3 backups; pre-counts exports=2, smb_sections=6; NO iptables — the unreachable case used the ping+neigh-verified-unused 192.168.0.199). Throwaway users spike3b (uid 1060) + spike3smb; passwords never committed.

Scenario	Result	Key evidence
A bogus export on a reachable server (THE bug)	PASS — failed in 4 s, category nfs_export, the exact merged Hungarian message, the REAL journal in detail (reason given by server: No such file or directory — the unprivileged journal read works), list EMPTY, zero spike3 units left on felhom-pve — the "Készenlét forever" behavior is dead
B SMB wrong password / wrong share	PASS — smb_auth („Hibás SMB felhasználónév vagy jelszó.") vs smb_share (distinct message), both 4 s, creds file gone after each, no units
C squash trap (anonuid=1000, NO all_squash — mounts fine)	PASS — agent verify passed → uid-1000 probe refused → not_writable with the Route-A message incl. the computed 101000; full rollback (no units/mounts/registration); no probe file left on the export
D happy paths	PASS — d1 (NFS anonuid=101000), d2 (NFS Route A, alien uid 1060), d3 (SMB plain user, no force user): all done in 4 s, registered Schedulable, health ok. d2 production proof: the installed unit carries retry=0; a uid-1000 write shows guest-view 65534:65534 and lands server-side 1060:1060
E unreachable IP	PASS — failed in 2.0 s (the agent's sync TCP pre-probe), category unreachable, message names the IP, nothing installed
G single-flight	unit-proven (A6 + C6); not re-proven live — the 4 s happy windows make a live race impractical

Teardown verified: d1/d2/d3 removed via the real remove endpoint (list empty); 180 restored from .bak-nasspike3 (post-counts exports=2, smb_sections=6, 0 spike3 exports, both users deleted, scratch gone); felhom-pve: 0 spike3 mounts/units/creds, mountpoint dirs removed, systemctl reset-failed cleared the residual failed-unit listings; guest 9201: 0 spike3 mounts, controller healthy.

NOT yet live-validated

• Guest-restart trigger survival (Q1c follow-up — needs a restart window; no guest restart allowed).
• Synology/QNAP appliance pass (virtual-dsm) — the sim-vs-real caveat stands.
• Peti rollout: floor bump + his usermod -aG systemd-journal felhom-agent step — when the NAS feature reaches him. STOP honored: no publish train (agent 0.81.0 NOT published to Gitea, Day-0 manifest untouched), Peti's box untouched, guest 9201 never restarted.
• Scenario F live (agent restart mid-verify) — covered by unit tests A6/C4 + the orphan surface (C7); a live kill inside a 4 s verify window is impractical.

Observations (documented, NOT acted on)

• The demo host had NO pre-existing nas-media unit (the spike-era shares were fully torn down) — nothing predating retry=0 exists; the "don't rewrite installed units" rule was moot in practice.
• RemoveNetworkMount leaves the EMPTY mountpoint dir under /mnt/felhom-drives/ and does not reset-failed a failed mount unit's residual state (the unit FILES are removed; a not-found failed listing lingers until reset-failed/reboot). Cosmetic; cleaned by hand this run.
• Pre-existing (since 2026-07-08, unrelated to this task): lanresolver: cannot list provisioned guests: permission denied — /var/lib/felhom-agent/guests is root-0700 while the agent runs non-root.
• host-install header/SCRIPT_VERSION drift (v1.11.0 vs 1.12.0): the v1.12.0 bump had shipped with no changelog entry and no header sync; both fixed at v1.13.0.
• The controller container publishes NO ports (bridge-only, traefik-fronted): in-guest API testing needs the container IP + Host: header — the "POST to in-guest 127.0.0.1:8080" note in older session memory is stale.