fix: adversarial review round — replay-rescue double-charge, discount credit, 2FA/per-IP limits, snapshot encryption, refund reconciliation, VAT, frontend parity, tests+docs

Addresses the adversarial fresh-eyes audit (findings A1-A20) plus review-round fixes:
- CRITICAL A1: replay-by-key rescue cross-checks replayed CreatedAt; ccof blind-fail leaves pending with CRITICAL + notification instead of clawing back
- A2/A3/A4: till idempotency key restored to unconditional hash; tip rejected in CreateBookingPayment; campaign discount now reduces the charged amount (deposit credit)
- A5: admin notifications on blind-fail, manual-refund re-arm, cap-stranded charge-group, webhook FAILED/REJECTED refunds
- A6/A10: BuyGiftCard idempotency user-scoped; gift-card slot scan advances past failed rows
- A7/A14/A15: 2FA user+IP limiter, SNAPSHOT_ENC_KEY startup validation, accurate pepper/log-delivery docs
- A8/A9: snapshot encryption on all write+reuse sites; MPV->SPV effective voucher type (single VAT point)
- A11/A12/A13/A16: amount-aware refund reconciliation; completed-booking refund re-validation; till retry dedup; PaymentWasRefunded on SquareClient interface
- A17/A18/A19/A20: CI runs npm test; confirm_overflow_tip frontend dialog; unknown-event admin notification; mock token redaction
- M7 ConfirmOverflowTip, M9 snapshot encryption, C1 discount ordering regression test
- Frontend vitest framework (41 tests), backend coverage for fixed functions, docs corrected (2,269 tests, SUPPORT_EMAIL tokens, resolution status)

All 25 backend packages pass; frontend 41/41; build + env-docs green.

frontend/src/lib/square/square.ts

@@ -55,6 +55,64 @@ export function isNonceStale(
 export const PAYMENT_AMBIGUOUS_STATUS = 503;
 export const PAYMENT_DEFINITIVE_STATUS = 402;
 
+/**
+ * True when a definitive (402) charge failure on a SAVED CARD should be
+ * surfaced as a card-issuer verification problem rather than a plain decline.
+ * The backend sets customer_details.customer_initiated=true on saved-card
+ * (ccof) charges and classifies issuer-verification rejections — Square's
+ * CARD_DECLINED_VERIFICATION_REQUIRED and friends — as definitive 402s, but the
+ * response body is the generic "Payment failed" text with no distinguishing
+ * code. Saved cards skip the client-side tokenizeWithVerification SCA step, so
+ * a 402 on the saved-card path means the issuer still requires verification:
+ * retrying the same saved card can never succeed, and the buyer must pay with
+ * a freshly tokenized card or re-add theirs. New-card (cnon) charges carry
+ * their own SCA verification token, so they are never classified this way.
+ */
+export function isSavedCardVerificationRequired(status: number, usedSavedCard: boolean): boolean {
+	return usedSavedCard && status === PAYMENT_DEFINITIVE_STATUS;
+}
+
+/** User-facing guidance for a saved-card charge the issuer requires
+ * verification to complete. Retrying the same saved card is pointless — the
+ * buyer must pay with a new card or re-add their card. */
+export const SAVED_CARD_VERIFICATION_MESSAGE =
+	'Your card issuer requires verification. Please pay with a new card or re-add your card.';
+
+/**
+ * Error code the booking-payment endpoint (POST /api/bookings/{id}/payment)
+ * returns with a 400 when a payment would exceed the booking's remaining
+ * balance BEFORE the appointment has started. buildSplitRecords records any
+ * overflow beyond the booking total as a tip — but a tip is gratuity for
+ * service already rendered, so the backend refuses to silently convert an
+ * unconfirmed pre-start overpayment into a tip (see CreateBookingPayment).
+ * The frontend must surface a Confirm/Cancel prompt and resend the SAME
+ * request with `confirm_overflow_tip: true` on confirm. This fires mainly on
+ * stale booking data (multi-tab, admin-changed totals, refunds that reopened
+ * capacity), so the response body carries no amount — the caller computes the
+ * overflow as `req.Amount - remainingCents` from its booking data.
+ */
+export const OVERFLOW_TIP_CONFIRMATION_REQUIRED_CODE = 'overflow_tip_confirmation_required';
+
+/**
+ * True when an API error body is the backend's overflow-tip confirmation guard
+ * (a 400 JSON body of the form `{"error": "...", "code":
+ * "overflow_tip_confirmation_required"}`). The shared error-parsing helper
+ * (`extractErrorMessage`) surfaces only the human-readable message text, not
+ * the machine-readable `code` field, so this checks the raw response body
+ * directly. Returns false for any non-JSON body or any other error.
+ */
+export function isOverflowTipConfirmationRequired(errorText: string): boolean {
+	const trimmed = errorText.trim();
+	if (!trimmed) return false;
+	try {
+		const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+		return parsed?.code === OVERFLOW_TIP_CONFIRMATION_REQUIRED_CODE;
+	} catch {
+		// Not JSON — cannot be the overflow guard
+		return false;
+	}
+}
+
 /** True when a payment submission response is an ambiguous failure (503) that
  * must be retried with the SAME idempotency key so the backend resumes the
  * pending record. */