fix: review round 6 — P0 deposit charge, idempotency rotation, dev-safety guard, 2FA/webhook hardening

Sixth fresh-eyes review pass (5 agents: goal, QA, code-quality, security,
context-mining). QA FAILED the deposit-required new-card flow; the P0 root
cause was backend + frontend, now fixed. All 20 packages green.

P0 money-safety:
- Deposit-required bookings now actually charge the deposit on new-card
  payment. Two-part fix: (1) CreateBookingHandler re-reads the
  trigger-maintained total_amount/total_duration_minutes from the DB after the
  booking_services insert (the INSERT..RETURNING row predates the recalc
  trigger, so TotalAmount serialized as 0 and DepositPaid computed TRUE on an
  unpaid booking — the frontend gate trusted deposit_paid:true, never charged,
  and confirmed the booking with zero payment rows); (2) BookingFlow.svelte
  gates the confirmation view on depositPaid and guards against re-creating a
  booking on retry. Regression test
  TestBookings_Create_DepositPaidFalseOnUnpaidBooking.

Payments (idempotency + money):
- deriveBookingPaymentIdempotencyKey: no-client-key fallback now advances a
  sequence for repeatable types (partial) and rotates past refunded completed
  rows, so refund-then-repay and equal-amount partials diverge onto distinct
  keys; an un-refunded completed row keeps its key (double-charge protection
  holds). Dedup hits on refunded rows now 409, never stale success.
- chargeFailureStatus default is 503 (ambiguous), never 402; table test.
- Flaky TestBookingPayment_FullPayment_SplitsIntoDepositAndBalance fixed
  (ORDER BY payment_type).
- resolveChargeSource: orphaned card-on-file disabled via DeleteCardOnFile
  when SaveCardForUser fails (best-effort, redacted log); retry path preserved.

Square client:
- Dev builds HARD-FAIL (panic) on SQUARE_ENVIRONMENT=production without
  SQUARE_ALLOW_REAL_API=1; sandbox routes with a loud banner.
- Mock fault-injection FailAfterCommit (commit-then-5xx) exercises the exact
  lost-response same-key retry; SimulateCardTokenUsed; 45-char idempotency-key
  cap parity; SquareEnvironment/SquareLocationID shared env helpers used by
  the sweep (env contract no longer comment-only).
- listRefunds truncation now errors (money-sensitive reconcile retries
  instead of over-refunding); getCardsOnFile truncation loudly logged.

Webhooks + 2FA:
- square-environment header checked fail-closed (403) when configured env is
  production/sandbox; dispatch DB work bounded by 30s timeout contexts.
- 2FA codes HMAC-SHA256 pepper'd (TWO_FACTOR_PEPPER) with legacy-hash
  migration + upgrade-on-verify; disable-flow mint cooldown (1/min, 429) caps
  the brute-force loop; in-lockout records never LRU-evicted.

Repo hygiene:
- env-docs CI gate green again (FRONTEND_ORIGIN + SQUARE_ALLOW_REAL_API +
  TWO_FACTOR_PEPPER documented; Vite DEV built-in allowlisted).
- Dead square_deposits schema dropped; obsidian/README/legal-page drift fixed
  (consumeradvice.scot signposting, CORS allowlist, p11 R3/P13, T1).
- 2FA disable residual documented; P6 email/SMS delivery and P12 sandbox
  smoke test remain the pre-go-live gates.

Verification: go test -tags test,dev -count=1 -parallel 8 ./... (20/20 ok),
go build ./... + -tags dev, go vet clean, svelte-check 0 errors, env-docs
gate OK, live deposit-required flow re-verified end-to-end (deposit £11
charged, square_payment_id recorded).

backend/internal/square/square_http_client_test.go

@@ -736,10 +736,11 @@ func TestListRefundsHTTP_Pagination(t *testing.T) {
 		}
 	})
 
-	t.Run("page_guard_returns_partial_results", func(t *testing.T) {
-		// The 20-page guard must not discard what was already collected: it
-		// logs a truncation warning and returns the partial results instead
-		// of failing the reconcile with an error.
+	t.Run("page_guard_errors_instead_of_partial", func(t *testing.T) {
+		// The 20-page guard must ERROR rather than return partial results: a
+		// refund in the truncated tail would otherwise look like "no COMPLETED
+		// refund exists", letting the reconcile mark rows failed and over-refund.
+		// The reconcile caller treats any error as "leave rows pending, retry".
 		calls := 0
 		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			calls++
@@ -750,14 +751,17 @@ func TestListRefundsHTTP_Pagination(t *testing.T) {
 
 		hc := &httpClient{baseURL: srv.URL, token: "t", http: srv.Client()}
 		refunds, err := listRefundsHTTPWithClient(context.Background(), "pay_partial", time.Now(), hc)
-		if err != nil {
-			t.Fatalf("expected partial results (nil error), got %v", err)
+		if err == nil {
+			t.Fatalf("expected a truncation error after 20 pages, got %d partial refunds with nil error", len(refunds))
+		}
+		if !strings.Contains(err.Error(), "exceeded 20 pages") {
+			t.Errorf("expected error to name the 20-page guard, got %v", err)
 		}
 		if calls != 20 {
 			t.Errorf("expected exactly 20 HTTP calls before guard, got %d", calls)
 		}
-		if len(refunds) != 20 {
-			t.Errorf("expected 20 refunds collected across pages (one per page), got %d", len(refunds))
+		if len(refunds) != 0 {
+			t.Errorf("expected no partial results on truncation error, got %d", len(refunds))
 		}
 	})
 }
@@ -909,6 +913,33 @@ func TestGetCardsOnFileHTTP_ReferenceIDFilter(t *testing.T) {
 	}
 }
 
+// TestGetCardsOnFileHTTP_PageGuard_ReturnsPartial verifies the 20-page guard
+// keeps returning partial results (nil error) for card listing, unlike
+// listRefunds which errors: GetCardsOnFile has no money-sensitive caller, and
+// erroring would break a "show my cards" feature for a user with >500 saved
+// cards. The truncation is surfaced in the log, not by an error.
+func TestGetCardsOnFileHTTP_PageGuard_ReturnsPartial(t *testing.T) {
+	calls := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		calls++
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"cards":[{"id":"ccof_t","card_brand":"VISA","last_4":"4242","exp_month":12,"exp_year":2030,"fingerprint":"fp_t","reference_id":"user_big","enabled":true,"version":1,"created_at":"2026-07-31T00:00:00Z"}],"cursor":"next"}`))
+	}))
+	defer srv.Close()
+
+	hc := &httpClient{baseURL: srv.URL, token: "t", http: srv.Client()}
+	cards, err := getCardsOnFileHTTPWithClient(context.Background(), "user_big", hc)
+	if err != nil {
+		t.Fatalf("expected partial cards with nil error, got %v", err)
+	}
+	if calls != 20 {
+		t.Errorf("expected exactly 20 HTTP calls before guard, got %d", calls)
+	}
+	if len(cards) != 20 {
+		t.Errorf("expected 20 cards collected across pages (one per page), got %d", len(cards))
+	}
+}
+
 // TestCreateCheckoutHTTP_TipSettings verifies AllowTipping is emitted as
 // checkout.device_options.tip_settings.allow_tipping (Square's wire shape for
 // enabling terminal tips) and omitted entirely when not set.