felhom-controller/REPORT.md

REPORT — R-193: the recovery screen (controller v0.200.0), 2026-08-05

A customer whose machine was rebuilt can now find out, and unlock their backups, without a command line. R-193's remaining half. No hub change; felhom.eu carries registers and docs only.

1. Baselines, and §3's five pieces

felhom-controller at be3c5fa7f6a1 / v0.199.0 — exact match, tree clean, HEAD == origin/main. felhom.eu at hub v0.96.0, unchanged. All five pieces of §3's table were where it said, at the cited landmarks: RunRecoveryCheck (:55), RecoverAndInstall (:140), offboxResetHandler (:245) with its confirm=1 gate and orphaned precondition, OffboxOrphaned (:244), and the per-app snapshot lookup (offbox_restore.go:84). No mechanism was invented.

Register: the highest ID was R-212 as stated, and still is — re-checked at the end for the second writer. This session mints R-213.

2. The one thing the task under-specified, and what I did about it

§8.1 says the page appears on the same two facts the box uses to declare needs_credential: a fresh data area (no repository password) and a hub-held package. Taken literally that is a window that closes by itself: WriteOffboxSecrets AUTO-GENERATES a repository password on re-apply — which is R-193's own orphaning mechanism — and since hub v0.96.0's credential self-heal the re-apply now happens unaided within ~15–30 minutes. The customer who logs in the next morning would never have seen the page.

So the predicate is the hub holds a package AND (no repository password OR the tier is orphaned). Shape (b) is the state a real rebuilt box is in, and it is also the state the shipped move-aside requires — which is what lets "I do not want the old data" reach the existing handler instead of needing a new one. Scenario B is unaffected: a healthy box has its own key and is not orphaned; a box that never had off-site backups fails the package condition. demo-felhom is in shape (b) right now, which is why validation 1 needed no arrangement at all.

3. Every Hungarian string, quoted for review as copy

The two MANDATORY sentences of §8.2 — both verified in the live rendered page:

A helyreállítási kódot senki nem tudja pótolni — sem a Felhom, sem az ügyfélszolgálat, sem az üzemeltető. Ez szándékos: így a mentéseidet rajtad kívül senki nem tudja megnyitni. Ha a kód elveszett, a korábbi mentések nem nyithatók meg többé.

Ha megadod a kódot, feloldjuk a mentéseid zárolását és megmutatjuk, mi van bennük — melyik alkalmazás, mikorról, mekkora. Ebben a lépésben semmit nem állítunk vissza és semmi nem változik. A visszaállítást utána, alkalmazásonként külön választhatod.

The situation, before any code:

Ezt a gépet újratelepítették. A korábbi, házon kívüli mentéseid megvannak — a Felhom központi rendszere őriz hozzájuk egy lezárt csomagot, amelyet <dátum> zártunk le. A csomagot csak a te helyreállítási kódoddal lehet kinyitni.

The form: Helyreállítási kód (tíz szó) · placeholder tíz szó, szóközökkel elválasztva · buttons Mentések feloldása / Most nem.

What "most nem" means:

A „Most nem" csak azt jelenti, hogy nem zavarunk vele többet a kezdőlapon. A mentéseid ettől megmaradnak, és ez az oldal a Biztonsági mentés → Távoli mentés oldalról bármikor újra elérhető.

A wrong code (quoted from the LIVE response):

A megadott helyreállítási kódot nem fogadtuk el. Ellenőrizd, hogy mind a tíz szót pontosan, szóközökkel elválasztva írtad be — a kis- és nagybetűk nem számítanak. Semmi nem változott, nyugodtan próbáld újra.

Refused (a different key is already present):

Ezen a gépen már van egy másik mentési kulcs. A régi előzmény visszanyitása felülírná azt, ezért nem hajtottuk végre. Vedd fel a kapcsolatot a Felhom ügyfélszolgálatával.

After the unlock:

Ezek a te mentéseid, a lent jelzett időpontokból. Nézd át, hogy tényleg azt találod-e itt, amire számítasz — semmit nem állítottunk vissza és semmi nem változott.

A mentéseid zárolása feloldva. Az alábbiakat találtuk a tárolóban — semmit nem állítottunk vissza.

Table headings: Alkalmazás · Legutóbbi mentés · Méret. Next step:

A visszaállítás alkalmazásonként történik, a Biztonsági mentés → Visszaállítás oldalon. Ott választhatod ki, melyik alkalmazás mit hozzon vissza.

An EMPTY store, stated plainly (§8.6):

A tároló megnyílt, de nincs benne egyetlen mentés sem. Ez azt jelenti, hogy a kulcs jó volt, de ehhez a géphez nem tartozik korábbi mentés. Ha korábban biztosan készültek mentések, keresd a Felhom ügyfélszolgálatát, mielőtt bármit tennél.

Unlocked but no coordinates yet (the pristine rebuilt shape, added after a test found the crash):

A kulcs visszakerült. A gép még most kapcsolódik újra a házon kívüli tárhelyhez — a mentéseid listája néhány perc múlva jelenik meg a Biztonsági mentés oldalon.

The exceptional path — first mention, then the SECOND confirmation:

Ha a helyreállítási kódod véglegesen elveszett, és tudomásul veszed, hogy a korábbi mentések így nem nyithatók meg többé: nem kérem vissza a korábbi adatokat.

Biztosan nem kéred vissza a korábbi mentéseket? Ha megerősíted: • a korábbi mentéseket félretesszük — nem töröljük; • a helyreállítási kód nélkül többé nem lesznek megnyithatók; • a gép új, üres mentési tárolót kezd, és mostantól oda ment; • ez az oldal többé nem jelenik meg. Ha csak most nincs kéznél a kódod, válaszd inkább a „Most nem" lehetőséget.

Button: Igen, félretehetitek a korábbi mentéseket / Mégsem.

The permanent entry point in the backups area:

A korábbi, házon kívüli mentéseid visszaszerezhetők. Ezt a gépet újratelepítették, és a Felhom központi rendszere őriz hozzá egy lezárt csomagot. A helyreállítási kódoddal feloldhatod a korábbi mentéseidet, és megnézheted, mi van bennük. → Adatok visszaszerzése

4. §8.4 — repeated failures: LOG LOCALLY, DO NOT ALERT. The reasoning.

No lockout, as instructed. On repeated failures I chose to log locally and raise no operator signal, and the reasoning is:

• The realistic generator of repeated failures is the owner mistyping a ten-word phrase, which is the single most likely event on this page. An alert there is noise on every real recovery.
• The threat it would guard against — someone guessing R — is not credible: a 10-word EFF phrase is ~129 bits, and an attacker who could reach this page already holds the household password.
• Silence is not total: every failure writes a [WARN] [web] recovery: unlock failed: … line carrying the agent's step and no code, so it reaches the debug ring and any operator log pull. A box being probed is visible; it just does not page anyone.

The deliberate residual: a slow, patient prober produces only ring entries nobody reads unprompted. That is accepted, and stated here rather than left implied.

5. Files created / modified

File	Change
internal/backup/offbox_recovery_cli.go	new RecoverInstallCore + its three outcomes; RecoverAndInstall reduced to a wrapper (exit codes and printed lines unchanged)
internal/backup/offbox_inventory.go	new — the read-only listing, the explicit empty case, ErrNoOffsiteTarget, HumanizeBytes
internal/backup/offbox.go	new OffsiteRecoveryOffer (the two-shape predicate)
internal/settings/settings.go	new RecoveryNoticePostponed + accessors
internal/report/escrow_confirm.go	new SealedAt() — the ACK's escrow created_at
internal/web/recovery_handlers.go	new — the page, unlock, postpone, the seams
internal/web/templates/recovery.html	new — the full page
internal/web/{server,handlers,funcmap}.go, templates/backups_remote.html	routes, the landing-page interception, the permanent entry point, humanBytes
cmd/controller/main.go	wires SetEscrowSealedAt
internal/web/recovery_test.go, recovery_wiring_test.go	new — Scenarios A–H + three AST seam tests

Commits on main: 636c51e (implementation) · 62b85ec (CHANGELOG). Deployed: gitea.dooplex.hu/admin/felhom-controller:0.200.0 on demo-felhom 9201 and demo-hp 9201.

6. Tests and red-proofs

Green gate: go build ./... && go vet ./... && go test ./... — full suite rc=0; controller_gates.py --fast — all eight OK.

Scenario	Test	Result	Red-proof — what was mutated	Outcome
A	TestRecovery_A_PageAppearsForARebuiltBox	PASS	—	—
B	TestRecovery_B_DoesNotAppearForAnyoneElse (3 sub-cases)	PASS	dropped the hub-package condition from OffsiteRecoveryOffer	FAILED — "a box that never had off-site backups was offered a recovery screen for data it never had"
C	TestRecovery_C_UnlockOpensAndLists + …EmptyStoreSaysSo	PASS	—	—
D	TestRecovery_D_WrongCodeFailsClosedAndIsKind	PASS	—	—
E	TestRecovery_E_PostponeKeepsTheEntryPoint	PASS	bound the backups-page entry point to recoveryInterrupts instead of recoveryOffer	FAILED — "the backups page no longer offers the route… a customer who clicked past it once has lost the way to their own data"
F	TestRecovery_F_SetAsideNeedsTwoConfirmations	PASS	removed the ConfirmSetAside gate in the template	FAILED — "the set-aside form is on the FIRST view — one click would set the customer's history aside"
G	TestRecovery_G_PageAndCLIShareOneCore + TestRecoveryHandlerDrivesTheSharedCore	PASS	gave the handler its own inline fetch→compare→install	FAILED — "recoveryUnlockHandler does NOT call backup.RecoverInstallCore"
H	TestRecovery_H_CodeLeavesNoTrace	PASS	(carries its own positive control)	—
I	TestCLIWrapperDrivesTheSharedCore, TestRecoveryRoutesAreWired	PASS	—	—

Scenario E's assertion was STRENGTHENED mid-session because the first version asserted only recoveryOffer(), which the mutation did not touch — it would have passed against the very defect it names. It now asserts the rendered backups page contains href="/recovery", and only then did the mutation fail. That is the red-proof-that-passes trap, caught and closed rather than reported as green.

Two real defects the tests caught before shipping:

1. An UNCLAIMED (legacy-open) box would have been shown the page. RequireAuth passes a password-less box through, so ServeHTTP's interception fired for an unauthenticated visitor. Fixed by an explicit authEnabled() check in recoveryOffer.
2. The inventory nil-dereferenced when no off-site target was configured — exactly the pristine rebuilt shape. Now a named error with its own honest customer message.

7. Live validation (endpoint-level; claude-in-chrome is not available on DooPlex)

#	What	Observable
1	The page rendered on a genuinely stranded box — no arrangement needed	demo-felhom 9201 is really in shape (b) (orphaned=True, status=error, snapshots=0). GET /launcher → 302 Location: /recovery; GET /recovery → 200 with the code form; both MANDATORY sentences present in the rendered bytes (transported base64 so the ssh→pct chain could not mangle an accented assertion).
2	A healthy box shows no page	demo-hp 9201 (orphaned=False, status=ok, 6 snapshots, image 0.200.0): GET /launcher → no redirect, and the backups page carries 0 occurrences of href="/recovery".
3	A wrong code is refused, nothing written, no lockout	Three consecutive wrong codes → 200 each time, the form still present each time, the Hungarian above rendered, 0 occurrences of age: / passphrase / unseal in the page, and the offbox/ directory listing byte-identical before and after. The controller log shows the failure came from the AGENT (POST /escrow/recover-offsite-password: HTTP 400: the recovery code did not open the sealed bundle), i.e. the whole chain — handler → agent → hub fetch → age KDF — ran live.
4	The correct code unlocking + the listing	NOT RUN LIVE, and it cannot be here. No recovery code was kept for demo-felhom's orphaned history (RECON-offsite-dr-chain-2026-08-04.md §12.3: "no recovery code was kept"), and demo-hp's drill code is operator-held out of band. It rests on TestRecovery_C_UnlockOpensAndLists (install + listing + "restores nothing"), …EmptyStoreSaysSo, and TestRecovery_G_PageAndCLIShareOneCore (installed → unchanged on re-run).
5	The code persists nowhere — with the positive control	0 hits in every file under the data volume, 0 in the container log, 0 in the debug ring. The positive control earned its keep: the first sweep ran against the CONTAINER path, which does not exist in the guest, so its "0 hits" proved nothing — the planted copy was NOT found, which exposed the mis-aimed sweep. Re-run against the real path: plant found (1), removed (0), and the real sweeps stayed at 0.

Teardown: nothing was arranged, so nothing needed reversing — demo-felhom is exactly as found (recovery_notice_postponed unset, offbox enabled, repo_state=orphaned, repository password present). Helper scripts removed from both guests.

8. Registers

• R-193 → CLOSED (credential half v0.199.0/hub v0.96.0; the screen v0.200.0), with the two operator rulings recorded and the shape-(b) reasoning stated.
• R-213 → NEW: putting files back in place, with the live-versus-backup comparison named as its requirement. Deliberately not started.
• R-202 stays open, untouched.
• The register's highest ID was R-212 on arrival and still is — re-checked for the second writer.

9. The capability-map row as it now reads

All four drill interventions closed and the customer is now offered the recovery. The old "needs someone who knows to look" qualifier is gone. What remains, stated narrowly: (1) the final unlock has never been driven with a correct code through the page; (2) putting files back is deliberately not part of this (→ R-213); (3) the journey has not been re-walked end to end since these fixes — one more drill is what is owed.

10. CI and hooks

CI green by head_sha for both pushes. --no-verify was NOT used; every push ran the pre-push gate, including the workspace-root assertion added yesterday.

11. Observations — noticed, NOT acted on

• The postpone flag is never cleared. If a box leaves and re-enters the stranded state, a customer who once chose „most nem" will not be interrupted again. The entry point still shows, so the route is intact; clearing it on a transition is a judgement call I did not make unasked.
• /backup/offbox/reset redirects to /backups/remote, not back to the recovery page. Correct — the situation has ended — but the customer lands on a page whose recovery banner has just disappeared, with no explicit "done" message. Worth a copy pass with the put-back work.
• RunRecoveryCheck was left alone, as instructed, so it still contains its own fetch+compare. It is compare-only and writes nothing, so it cannot diverge dangerously — but it is now the ONE recovery path not routed through RecoverInstallCore.