v0.126.0: a fetch failure is not a wrong recovery code (R-224)

A hub the agent could not reach was reported to the customer as a bad recovery
code. Measured live 2026-08-05 (CAMPAIGN-11 F3): hub firewalled off, a CORRECT
current code, and the customer told it did not open their package — in 0.0556s
against ~1.0s for a real unseal. No unseal was attempted.

The discriminator existed here and this boundary threw it away: recover.go
fails at four distinguishable points and the local-api handler had cases for
two, with a default answering 'the recovery code did not open the sealed
bundle, OR the bundle could not be fetched'.

escrow.ErrBundleFetch now joins the fetch leg and the handler routes it to 502
with its own words — the code was NOT used. 502 not 4xx: the request was not
bad, an upstream dependency failed. Four situations, four statuses: 502 fetch /
400 fetched-and-refused / 404 no bundle / 409 predates the field. The
controller classifies on the STATUS and never parses the sentence.

A GREEN TEST NAMED THIS DEFECT AND DID NOT PREVENT IT.
TestRecoverOffsiteRepoPassword_FetchErrorIsDistinct has said since v0.125.0
that the operator must not be sent to re-read their code because the hub was
unreachable — and passed throughout, because it asserted this package's error
STRING one layer below the merge, and a string is not something a caller can
branch on. Re-pointed at the sentinel, with a consequence-level twin asserting
the status.

Red-proofs: removing the %w join fails the sentinel test; deleting the handler
case makes fetch and wrong-code both answer 400 with the wrong-code sentence.

29 packages ok, vet clean, agent gates OK.

internal/escrow/recover.go

@@ -19,10 +19,27 @@ import (
 // keeps that property: it takes R as an argument, passes it straight through, and holds no copy.
 // Callers must clear their own reference (the `R = ""` discipline in cmd/felhom-agent).
 //
-// The errors below are DISTINCT on purpose. "no blob", "wrong code" and "the blob predates the field"
-// are three different situations for the operator and only one of them is a fault.
+// The errors below are DISTINCT on purpose. "could not fetch", "no blob", "wrong code" and "the blob
+// predates the field" are FOUR different situations for the operator and only one of them is a fault.
+//
+// ⚠ THERE WERE THREE, AND THE FOURTH WAS THE DEFECT (R-224, 2026-08-06). This comment said "three"
+// and named "no blob", "wrong code" and "predates the field" — while a FAILED FETCH was wrapped as an
+// anonymous error and fell through the caller's `default` branch into the wrong-code message. So a
+// hub that could not be reached was reported to the customer as a bad recovery code.
+//
+// Measured live on 2026-08-05 (CAMPAIGN-11 F3): with the hub REJECTed at the appliance's firewall and
+// a CORRECT current recovery code, the customer was told the code did not open their package — in
+// 0.0556 s, when a real unseal costs ~1 s of scrypt. The agent's own log carried the truth the whole
+// time (`escrow: fetching the sealed bundle: hub: transport error: … no route to host`) and the HTTP
+// boundary threw it away.
+//
+// The discriminator therefore has to be a VALUE, not a log line — that is what ErrBundleFetch is.
 
 var (
+	// ErrBundleFetch — the sealed bundle could not be FETCHED (the hub refused, was unreachable, or
+	// the transport failed). **The recovery code was never used**, so nothing about it is known and
+	// nothing may be said about it. Wraps the underlying cause for the operator log; carries no secret.
+	ErrBundleFetch = errors.New("escrow: the sealed bundle could not be fetched")
 	// ErrNoEscrowBlob — the hub holds no sealed bundle for this host. Not a fault: no ceremony has run.
 	ErrNoEscrowBlob = errors.New("escrow: the hub holds no sealed identity bundle for this host (no ceremony has run)")
 	// ErrNoResticPassword — the bundle opened, but carries no repository password. Real and expected
@@ -58,7 +75,11 @@ func (r OffsiteKeyRecoverer) RecoverOffsiteRepoPassword(ctx context.Context, rec
 	}
 	blob, present, err := r.Fetch(ctx)
 	if err != nil {
-		return "", fmt.Errorf("escrow: fetching the sealed bundle: %w", err) // carries no secret
+		// R-224: joined with ErrBundleFetch so the caller can classify by VALUE. The cause stays
+		// wrapped for the operator log; neither carries a secret. Before this, the fetch failure was
+		// an anonymous error and the local-api handler's `default` branch reported it to the customer
+		// as a wrong recovery code.
+		return "", fmt.Errorf("%w: %w", ErrBundleFetch, err)
 	}
 	if !present || len(blob) == 0 {
 		return "", ErrNoEscrowBlob

internal/escrow/recover_test.go

@@ -175,15 +175,93 @@ func TestRecoverOffsiteRepoPassword_RLeavesNoTrace(t *testing.T) {
 
 // A fetch failure surfaces as a fetch failure, not as a wrong-code error — the operator must not be
 // sent to re-read their recovery code because the hub was unreachable.
+//
+// ⚠ THIS TEST WAS GREEN THROUGHOUT THE DEFECT IT DESCRIBES (R-224, 2026-08-06). Its sentence is
+// exactly right and it did not prevent anything, for two reasons worth keeping:
+//
+//  1. **It asserted the MECHANISM, one layer below the consequence.** It checked this package's error
+//     STRING. The merge happened one layer up, in the local-api handler's `default` branch, which
+//     answered a fetch failure with "the recovery code did not open the sealed bundle". The customer
+//     never sees this string; they see that one. The project's own rule — prefer the test that asserts
+//     the CONSEQUENCE (does the customer get blamed?) over the one that asserts the MECHANISM (is the
+//     error distinct here?) — names this case precisely.
+//  2. **It asserted on TEXT.** `strings.Contains(err.Error(), …)` cannot be consumed by a caller, so
+//     it pinned something no production code could branch on. The distinction it checked was real and
+//     unusable.
+//
+// It now asserts the SENTINEL, which is what the handler branches on, and its consequence-level twin
+// lives in `internal/localapi/escrow_recover_class_test.go` where the status is asserted.
 func TestRecoverOffsiteRepoPassword_FetchErrorIsDistinct(t *testing.T) {
 	rec := OffsiteKeyRecoverer{Fetch: func(context.Context) ([]byte, bool, error) {
 		return nil, false, errors.New("hub: connection refused")
 	}}
 	_, err := rec.RecoverOffsiteRepoPassword(context.Background(), testR)
-	if err == nil || !strings.Contains(err.Error(), "fetching the sealed bundle") {
-		t.Fatalf("a fetch failure must say so, got %v", err)
+	if err == nil || !errors.Is(err, ErrBundleFetch) {
+		t.Fatalf("a fetch failure must classify as ErrBundleFetch, got %v", err)
 	}
 	if errors.Is(err, ErrNoEscrowBlob) || errors.Is(err, ErrNoResticPassword) {
 		t.Fatal("a transport failure must not masquerade as a content verdict")
 	}
 }
+
+// ── R-224 — A FAILED FETCH IS NOT A WRONG CODE ──────────────────────────────────────────────────
+//
+// CAMPAIGN-11 F3 measured the consequence of these two being indistinguishable: with the hub
+// firewalled off and a CORRECT current recovery code, the customer was told the code did not open
+// their package, in 0.0556 s — no unseal was attempted at all.
+//
+// The pair below is the whole point. Asserting only the first would pass with a `return ErrBundleFetch`
+// stuck on every error path, which is the same defect pointing the other way.
+func TestRecoverOffsiteRepoPassword_FetchFailureIsClassifiedAsFetch(t *testing.T) {
+	boom := errors.New("hub: transport error: dial tcp 37.191.56.193:443: connect: no route to host")
+	r := OffsiteKeyRecoverer{Fetch: func(context.Context) ([]byte, bool, error) { return nil, false, boom }}
+
+	_, err := r.RecoverOffsiteRepoPassword(context.Background(), testR)
+	if err == nil {
+		t.Fatal("a failing fetch must return an error")
+	}
+	// RED-PROOF: drop the `%w: %w` join in RecoverOffsiteRepoPassword (return the bare wrapped cause,
+	// as it was before R-224) → this FAILS, and the local-api handler falls back to the wrong-code
+	// message exactly as it did on 2026-08-05.
+	if !errors.Is(err, ErrBundleFetch) {
+		t.Fatalf("a failed fetch must classify as ErrBundleFetch, got %v", err)
+	}
+	// The underlying cause survives for the operator log.
+	if !errors.Is(err, boom) {
+		t.Fatalf("the fetch cause must stay wrapped for the operator, got %v", err)
+	}
+	// And it must NOT be mistaken for either of the bundle-content situations.
+	if errors.Is(err, ErrNoEscrowBlob) || errors.Is(err, ErrNoResticPassword) {
+		t.Fatalf("a transport failure is neither of the bundle-content errors: %v", err)
+	}
+}
+
+// The other half: a genuinely wrong code must NOT classify as a fetch failure, or the fix trades one
+// misattribution for its mirror image and the customer is told the hub is down when they mistyped.
+func TestRecoverOffsiteRepoPassword_WrongCodeIsNotAFetchFailure(t *testing.T) {
+	ensureAge(t)
+	blob := sealBundle(t, IdentityBundle{ResticRepoPassword: "0123456789abcdef"}, testR)
+	r := OffsiteKeyRecoverer{Fetch: fetcherFor(blob)}
+
+	_, err := r.RecoverOffsiteRepoPassword(context.Background(),
+		"wrong horse battery staple sedative anaconda wobbly kingdom placard yodel")
+	if err == nil {
+		t.Fatal("a wrong recovery code must fail closed")
+	}
+	if errors.Is(err, ErrBundleFetch) {
+		t.Fatalf("a wrong code must NOT classify as a fetch failure, got %v", err)
+	}
+}
+
+// A clean "the hub holds nothing" keeps its own identity too — it is not a fetch failure, and the
+// customer must not be told the hub was unreachable when it answered perfectly well.
+func TestRecoverOffsiteRepoPassword_AbsentBlobIsNotAFetchFailure(t *testing.T) {
+	r := OffsiteKeyRecoverer{Fetch: func(context.Context) ([]byte, bool, error) { return nil, false, nil }}
+	_, err := r.RecoverOffsiteRepoPassword(context.Background(), testR)
+	if !errors.Is(err, ErrNoEscrowBlob) {
+		t.Fatalf("an absent blob must stay ErrNoEscrowBlob, got %v", err)
+	}
+	if errors.Is(err, ErrBundleFetch) {
+		t.Fatalf("an absent blob is not a fetch FAILURE, got %v", err)
+	}
+}

internal/localapi/escrow_recover.go

@@ -75,6 +75,26 @@ func (s *Server) handleRecoverOffsitePassword(w http.ResponseWriter, r *http.Req
 	if err != nil {
 		// Each situation gets its own status and its own words. None of them names a secret.
 		switch {
+		// ── R-224 (2026-08-06) — THE FETCH FAILURE IS NOT A WRONG CODE. ────────────────────────
+		//
+		// This case did not exist, and its absence is the defect. A failed fetch fell through to the
+		// `default` below and was answered with "the recovery code did not open the sealed bundle" —
+		// so a hub that could not be reached was reported to the customer as a bad recovery code, on
+		// the one screen whose whole purpose is to be believed about their backups.
+		//
+		// Measured live 2026-08-05 (CAMPAIGN-11 F3 and F4): a CORRECT current code returned that
+		// message in 0.0556 s with the hub firewalled off, and in 0.0299 s with this agent stopped —
+		// against ~1.0 s for a genuine unseal. No unseal was attempted in either case.
+		//
+		// 502 rather than 400: 4xx says "your request was bad", and the request was not bad — an
+		// upstream dependency failed. The status is the machine-readable half; the controller
+		// classifies on it and must never parse this sentence.
+		//
+		// ⚠ THE CODE WAS NOT USED. Nothing may be said about it — not that it was wrong, and not
+		// that it was right.
+		case errors.Is(err, escrow.ErrBundleFetch):
+			s.logger.Warn("local-api: offsite key recovery: the sealed bundle could not be FETCHED — the recovery code was never used", "vmid", vmid, "err", err)
+			writeErr(w, http.StatusBadGateway, "the sealed recovery bundle could not be fetched from the hub — the recovery code was NOT used and nothing was written")
 		case errors.Is(err, escrow.ErrNoEscrowBlob):
 			s.logger.Warn("local-api: offsite key recovery: the hub holds no sealed bundle for this host", "vmid", vmid)
 			writeErr(w, http.StatusNotFound, "the hub holds no sealed recovery bundle for this host — no escrow ceremony has run")
@@ -82,9 +102,11 @@ func (s *Server) handleRecoverOffsitePassword(w http.ResponseWriter, r *http.Req
 			s.logger.Warn("local-api: offsite key recovery: the bundle opened but predates the repository-password field", "vmid", vmid)
 			writeErr(w, http.StatusConflict, "the recovery code opened the bundle, but it carries NO offsite repository password (sealed before that field existed; it cannot be retro-fitted)")
 		default:
-			// Includes the fail-closed wrong-code case. The agent log records the STEP, never the code.
-			s.logger.Warn("local-api: offsite key recovery FAILED (wrong recovery code, or the blob could not be fetched)", "vmid", vmid, "err", err)
-			writeErr(w, http.StatusBadRequest, "the recovery code did not open the sealed bundle, or the bundle could not be fetched — nothing was written")
+			// The fail-closed WRONG-CODE case, and only it: the bundle was fetched and `age -d`
+			// refused it. Every other situation above has its own status. The agent log records the
+			// STEP, never the code.
+			s.logger.Warn("local-api: offsite key recovery: the fetched bundle did not open with the supplied recovery code", "vmid", vmid, "err", err)
+			writeErr(w, http.StatusBadRequest, "the recovery code did not open the sealed bundle — nothing was written")
 		}
 		return
 	}

internal/localapi/escrow_recover_class_test.go

@@ -0,0 +1,99 @@
+package localapi
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"gitea.dooplex.hu/admin/felhom-agent/internal/escrow"
+)
+
+// R-224 — THE STATUS IS THE DISCRIMINATOR, and this test asserts the CONSEQUENCE (what the HTTP
+// boundary answers) rather than the mechanism (that the sentinel exists).
+//
+// The controller one trust tier down classifies on the STATUS and must never parse the sentence. So
+// the contract this pins is: four distinguishable situations, four distinct statuses, and the
+// wrong-code message reachable ONLY from a real refusal.
+//
+// Before R-224 the first and last rows both answered 400 with the same sentence — which is how
+// CAMPAIGN-11 F3 told a customer holding a CORRECT code that it did not open their package.
+
+type fakeRecoverer struct{ err error }
+
+func (f fakeRecoverer) RecoverOffsiteRepoPassword(context.Context, string) (string, error) {
+	if f.err != nil {
+		return "", f.err
+	}
+	return "0123456789abcdef0123456789abcdef", nil
+}
+
+func TestRecoverOffsitePassword_EachSituationGetsItsOwnStatus(t *testing.T) {
+	cases := []struct {
+		name       string
+		err        error
+		wantStatus int
+		// mustNotSay guards the specific misattribution each status exists to prevent.
+		mustNotSay []string
+	}{
+		{
+			name:       "fetch failed — the code was NEVER used",
+			err:        errors.Join(escrow.ErrBundleFetch, errors.New("hub: transport error: no route to host")),
+			wantStatus: 502,
+			mustNotSay: []string{"did not open"},
+		},
+		{
+			name:       "wrong code — the bundle WAS fetched and refused it",
+			err:        errors.New("escrow: the recovery code did not unwrap the identity escrow"),
+			wantStatus: 400,
+			mustNotSay: []string{"could not be fetched"},
+		},
+		{
+			name:       "the hub holds no bundle",
+			err:        escrow.ErrNoEscrowBlob,
+			wantStatus: 404,
+			mustNotSay: []string{"did not open"},
+		},
+		{
+			name:       "the bundle predates the repository-password field",
+			err:        escrow.ErrNoResticPassword,
+			wantStatus: 409,
+			mustNotSay: []string{"could not be fetched"},
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			srv := newTestServerS(t, &fakeGuests{}, &fakeBackups{}, &fakeStore{}, nil)
+			srv.escrowRecovery = fakeRecoverer{err: tc.err}
+			w := do(t, srv.Handler(), "POST", "/escrow/recover-offsite-password", "A",
+				`{"vmid":8200,"recovery_code":"correct horse battery staple sedative anaconda wobbly kingdom placard yodel"}`)
+			if w.Code != tc.wantStatus {
+				t.Fatalf("status: got %d, want %d — body=%s", w.Code, tc.wantStatus, w.Body.String())
+			}
+			for _, phrase := range tc.mustNotSay {
+				if strings.Contains(w.Body.String(), phrase) {
+					t.Fatalf("the %d answer must not say %q — body=%s", tc.wantStatus, phrase, w.Body.String())
+				}
+			}
+		})
+	}
+}
+
+// The pair that matters most, stated as its own assertion so a regression cannot hide inside a table:
+// a fetch failure and a wrong code must never answer with the SAME status. Collapsing them is the
+// whole of R-224.
+func TestRecoverOffsitePassword_FetchFailureAndWrongCodeDiffer(t *testing.T) {
+	status := func(err error) int {
+		srv := newTestServerS(t, &fakeGuests{}, &fakeBackups{}, &fakeStore{}, nil)
+		srv.escrowRecovery = fakeRecoverer{err: err}
+		return do(t, srv.Handler(), "POST", "/escrow/recover-offsite-password", "A",
+			`{"vmid":8200,"recovery_code":"correct horse battery staple sedative anaconda wobbly kingdom placard yodel"}`).Code
+	}
+	fetch := status(errors.Join(escrow.ErrBundleFetch, errors.New("no route to host")))
+	wrong := status(errors.New("escrow: the recovery code did not unwrap the identity escrow"))
+	// RED-PROOF: delete the ErrBundleFetch case from handleRecoverOffsitePassword → both become 400
+	// → this FAILS. That is the exact pre-R-224 code, and the exact defect CAMPAIGN-11 measured.
+	if fetch == wrong {
+		t.Fatalf("a failed fetch and a wrong code must not share a status (both %d)", fetch)
+	}
+}