popertots/Crussell
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: review-loop hardening — identical-body replay, 2FA gates, webhook at-least-once, GDPR scrub

Browse Source 
Follow-up to the comprehensive payment-system review. Fixes the issues the
review found in the initial integration, plus the rough edges it introduced.

Money-safety:
- Replay-by-key now replays the FULL original request verbatim from a stored
  square_request_snapshot, so a retained idempotency key returns the original
  payment instead of IDEMPOTENCY_KEY_REUSED (previously the row sat pending
  forever). IDEMPOTENCY_KEY_REUSED remains ambiguous (never proof of no charge).
- Dev mock mirrors real Square for unknown-key replays: ccof: saved-card
  sources are charged and rescued; spent cnon: nonces surface
  ErrReplayKeyNotRetained. (Fixes dev/prod parity divergence.)
- Webhook dedup row committed AFTER dispatch (at-least-once); FAILED till sales
  claw back gift-card funding; event-type strings match Square's real catalog.
- Expired-gift-card cancellation refunds set creditFailed (never a phantom
  'completed' refund); cancellation refunds lock all payment rows ascending.
- Sweep never rescue-completes a gift-card purchase without delivering the card.
- Tip no-client-key fallback is a deterministic count-based key under the
  booking advisory lock (retry-safe, distinct tips don't collapse).
- M-cap subtracts completed refunds, clamped to [0, total].

2FA (PSD2 SCA stand-in) for online saved-card payments:
- Full feature: status/setup/verify/disable endpoints, gating helper wired into
  all 7 saved-card charge paths (incl. BuyGiftCard + admin saved-card), account
  admin-tab settings UI, frontend gating across all payment surfaces.
- Enforcement is FAIL-CLOSED: on unless REQUIRE_2FA=false or an explicit
  mock/dev SQUARE_ENVIRONMENT; startup warning when off in a non-dev env.
- Verify is brute-force hardened (5-attempt lockout, timing-safe compare);
  plaintext codes only logged when enforcement is off (dev).
- GDPR: anonymize_user also scrubs 2FA columns and staff notes.

Infra/docs:
- nginx: /api/ response cache removed (cross-user disclosure); port 80
  redirects to HTTPS (localhost/RFC1918 exempt, end-anchored regexes); HSTS;
  separate webhook rate-limit zone.
- Schema: users 2FA columns; payments/till_sales square_source_id +
  square_request_snapshot.
- Legal docs: gift-card cooling-off, international-transfers section, tips
  policy; Gap Backlog P3 webhooks marked done; stale counts/wording corrected.
- Flaky test race fixed (t.Parallel + global mock mutation); suite 26/26
  packages green, 2,142 tests, svelte-check clean.
This commit is contained in:
popertots
2026-08-22 00:34:49 +01:00
parent 4b28e93710
commit e9b0f0f2a7
50 changed files with 4223 additions and 413 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/handlers/webhooks/square.go
+301 -92
View File
@@ -4,8 +4,10 @@ import (
"context"
"crypto/hmac"
"crypto/sha256"
"database/sql"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
"io"
"log"
@@ -14,6 +16,8 @@ import (
"sync"
"crussell/db"
"github.com/jackc/pgx/v5"
)
type SquareWebhookEvent struct {
@@ -144,70 +148,79 @@ func HandleSquareWebhook(w http.ResponseWriter, r *http.Request) {
return
}
// Dedup BEFORE dispatch: a correctly signed replay of a handled event must
// not re-enter the handlers (which will mutate state once wired). The
// in-memory fast-path drops recent replays without a DB round-trip; the
// square_webhook_events INSERT ... ON CONFLICT DO NOTHING is the source of
// truth — 0 rows affected means the event was already handled (persisted
// from before a restart, or a concurrent duplicate) and dispatch is
// skipped. Returns 200 to acknowledge delivery without processing.
//
// ORDERING NOTE: the dedup row is committed before dispatch. If the process
// crashes between the insert and dispatch, the event is dropped (Square's
// retry is 200-skipped). This is acceptable while dispatch is log-only;
// when handlers mutate state, switch to dispatch-then-record or make
// dispatch idempotent.
if event.EventID != "" {
if squareWebhookEventsSeen.has(event.EventID) {
log.Printf("[SQUARE-WEBHOOK] Duplicate event_id %s; skipping (already processed)", event.EventID)
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte("ok"))
return
}
if db.Conn == nil {
log.Printf("[SQUARE-WEBHOOK] DB unavailable — rejecting event_id %s (fail-closed)", event.EventID)
http.Error(w, "webhook processing unavailable", http.StatusServiceUnavailable)
return
}
tag, err := db.Conn.Exec(r.Context(),
"INSERT INTO square_webhook_events (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING", event.EventID)
if err != nil {
// Fail closed: without a successful dedup write we cannot prove this
// event hasn't been handled before, so reject and let Square retry
// later. event_id is not PII, so logging it is safe.
log.Printf("[SQUARE-WEBHOOK] Failed to record event_id %s (dedup write failed): %v", event.EventID, err)
http.Error(w, "webhook processing unavailable", http.StatusServiceUnavailable)
return
}
// Record in the fast-path cache only after the DB write succeeds, so a
// failed write never leaves a stale entry that would drop a retry.
squareWebhookEventsSeen.register(event.EventID)
if tag.RowsAffected() == 0 {
log.Printf("[SQUARE-WEBHOOK] Duplicate event_id %s; skipping (already processed)", event.EventID)
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte("ok"))
return
}
// Fast-path dedup: a correctly signed replay of a recently handled event is
// dropped in memory without a DB round-trip. The persistent source of truth
// is the square_webhook_events row committed AFTER dispatch below, so this
// cache never hides an event whose dedup row is not yet persisted — a crash
// before that commit simply replays the event, which the idempotent handlers
// absorb.
if squareWebhookEventsSeen.has(event.EventID) {
log.Printf("[SQUARE-WEBHOOK] Duplicate event_id %s; skipping (already processed)", event.EventID)
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte("ok"))
return
}
if db.Conn == nil {
log.Printf("[SQUARE-WEBHOOK] DB unavailable — rejecting event_id %s (fail-closed)", event.EventID)
http.Error(w, "webhook processing unavailable", http.StatusServiceUnavailable)
return
}
log.Printf("[SQUARE-WEBHOOK] Received event: %s", event.Type)
// Dispatch FIRST, then commit the dedup row. The handlers mutate state, so a
// dedup row committed before dispatch would permanently drop the event on a
// crash between the insert and the dispatch (Square's retry would be
// 200-skipped, and dispute.created has no sweep fallback). Committing after
// a successful dispatch keeps delivery at-least-once: on any dispatch error
// NO dedup row is written and we return 5xx so Square retries. The handlers
// are idempotent (status='pending'-guarded UPDATEs keyed on the Square id),
// so a retry — or two retries dispatching concurrently — applies each state
// change at most once and is otherwise a no-op.
var dispatchErr error
switch event.Type {
case "payment.updated", "payment.created", "payment.completed":
handlePaymentUpdated(event.Data)
case "refund.updated", "refund.created", "refund.completed", "refund.failed":
handleRefundUpdated(event.Data)
case "payment.updated", "payment.created":
dispatchErr = handlePaymentUpdated(event.Data)
case "refund.updated", "refund.created":
dispatchErr = handleRefundUpdated(event.Data)
case "dispute.created":
handleDisputeCreated(event.Data)
dispatchErr = handleDisputeCreated(event.Data)
case "dispute.state.updated":
handleDisputeStateUpdated(event.Data)
case "dispute.evidence.submitted", "dispute.evidence.created", "dispute.evidence.removed", "dispute.evidence.deleted":
handleDisputeEvidence(event.Data)
dispatchErr = handleDisputeStateUpdated(event.Data)
case "dispute.evidence.created", "dispute.evidence.deleted":
dispatchErr = handleDisputeEvidence(event.Data)
case "terminal.checkout.created", "terminal.checkout.updated":
handleTerminalCheckout(event.Data)
dispatchErr = handleTerminalCheckout(event.Data)
default:
log.Printf("[SQUARE-WEBHOOK] Unknown event type: %s", event.Type)
}
if dispatchErr != nil {
log.Printf("[SQUARE-WEBHOOK] Event %s (%s) dispatch failed: %v — NOT recording dedup row; Square will retry", event.Type, event.EventID, dispatchErr)
http.Error(w, "webhook processing failed", http.StatusServiceUnavailable)
return
}
// Commit the dedup row AFTER successful dispatch. Fail closed on a write
// error: without a persisted row we cannot prove the event was handled, so
// reject and let Square retry (the retry re-dispatches idempotently and
// retries the insert). event_id is not PII, so logging it is safe.
tag, err := db.Conn.Exec(r.Context(),
"INSERT INTO square_webhook_events (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING", event.EventID)
if err != nil {
log.Printf("[SQUARE-WEBHOOK] Failed to record event_id %s (dedup write failed): %v", event.EventID, err)
http.Error(w, "webhook processing unavailable", http.StatusServiceUnavailable)
return
}
// Record in the fast-path cache only after the DB write succeeds, so a
// failed write never leaves a stale entry that would drop a retry.
squareWebhookEventsSeen.register(event.EventID)
if tag.RowsAffected() == 0 {
// A concurrent duplicate delivery already committed this event's row.
log.Printf("[SQUARE-WEBHOOK] Duplicate event_id %s; acknowledging (already processed)", event.EventID)
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte("ok"))
return
}
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte("ok"))
@@ -416,42 +429,45 @@ func insertCriticalPaymentNotification(bookingID string) {
// markPaymentFailed flips a payment to 'failed' after a lost dispute — the
// money was charged back, so the row must not read as collected. 'refunded'
// rows are left alone (the money was returned by refund, not charged back).
func markPaymentFailed(paymentID string) {
func markPaymentFailed(paymentID string) error {
if paymentID == "" {
return
return nil
}
_, err := db.Conn.Exec(context.Background(),
"UPDATE payments SET status = 'failed', updated_at = NOW() WHERE id = $1 AND status IN ('pending', 'completed')",
paymentID)
if err != nil {
log.Printf("[SQUARE-WEBHOOK] Failed to mark payment %s failed after lost dispute: %v", paymentID, err)
return err
}
return nil
}
// handlePaymentUpdated reconciles a Square Payment state change against the
// local payments row (real-time counterpart to the stale-pending sweep). The
// Square id is logged, never the payload (PII). Idempotent: the UPDATE is a
// no-op when the local status already matches, and event_id dedup prevents
// re-entry at the handler level.
func handlePaymentUpdated(data json.RawMessage) {
// re-entry at the handler level. A non-nil error means dispatch failed and the
// caller must NOT commit the dedup row (Square retries).
func handlePaymentUpdated(data json.RawMessage) error {
var env squareWebhookData
if err := json.Unmarshal(data, &env); err != nil {
log.Printf("[SQUARE-WEBHOOK] payment.updated received (payload length=%d)", len(data))
return
return nil
}
if env.ID == "" {
log.Printf("[SQUARE-WEBHOOK] payment.updated received (payload length=%d)", len(data))
return
return nil
}
var payment squarePaymentPayload
if !parseSquareObject(env.Object, "payment", &payment) || payment.ID == "" || payment.Status == "" {
log.Printf("[SQUARE-WEBHOOK] payment.updated received (data.id=%s)", env.ID)
return
return nil
}
localStatus, terminal := squarePaymentStatusToLocal(payment.Status)
if !terminal {
log.Printf("[SQUARE-WEBHOOK] payment.updated: square payment %s status %q is non-terminal — no local state change", payment.ID, payment.Status)
return
return nil
}
// Only 'pending' rows are candidates for a terminal transition — the same
// conservative rule the stale-pending sweeps use. A webhook for an already
@@ -463,47 +479,231 @@ func handlePaymentUpdated(data json.RawMessage) {
localStatus, payment.ID)
if err != nil {
log.Printf("[SQUARE-WEBHOOK] Failed to update payment %s to status %s: %v", payment.ID, localStatus, err)
return
return err
}
if tag.RowsAffected() > 0 {
log.Printf("[SQUARE-WEBHOOK] payment.updated: square payment %s → local status %s", payment.ID, localStatus)
}
// A Square charge can also map to a till_sales row (online gift-card
// purchase, retail at the till) — reconcile those too. Same pending-only
// guard: never revert a terminal till-sale status.
// guard: never revert a terminal till-sale status. A definitively failed
// charge (Square FAILED/CANCELED) claws back the gift-card funding those
// pending sales added, exactly like the stale-pending sweep
// (handlers/payments/sweep.go); an ambiguous status never reaches here.
if localStatus == "failed" {
return clawbackFailedTillSales(payment.ID)
}
tsTag, err := db.Conn.Exec(context.Background(),
`UPDATE till_sales SET status = $1, updated_at = NOW() WHERE square_payment_id = $2 AND status = 'pending'`,
localStatus, payment.ID)
if err != nil {
log.Printf("[SQUARE-WEBHOOK] Failed to reconcile till_sales for square payment %s: %v", payment.ID, err)
return
return err
}
if tsTag.RowsAffected() > 0 {
log.Printf("[SQUARE-WEBHOOK] payment.updated: reconciled %d till_sale(s) for square payment %s → status %s", tsTag.RowsAffected(), payment.ID, localStatus)
}
return nil
}
// errTillSaleNotPending mirrors the sweep's claim-first guard: the gating
// UPDATE matched zero rows, so the sale is no longer 'pending' and its gift
// card must be left untouched (a sale already resolved by a concurrent
// completion/clawback is not ours to revert).
var errTillSaleNotPending = errors.New("till sale is not pending")
// clawbackFailedTillSales reverts the gift-card funding of every still-pending
// till sale funded by a Square charge that is DEFINITIVELY failed (Square
// FAILED/CANCELED — never ambiguous). It mirrors the stale-pending sweep's
// clawbackTillSaleFunding + revertGiftCardFunding (handlers/payments/sweep.go,
// till.go): each sale is claimed with a status='pending' guard so an
// already-resolved row is skipped without error, and the failed mark + funding
// revert commit atomically. A non-nil error means a DB failure left a pending
// sale's funding unreverted — the caller rejects the webhook so Square retries
// the clawback (the sweep is the eventual backstop).
func clawbackFailedTillSales(squarePaymentID string) error {
rows, err := db.Conn.Query(context.Background(), `
SELECT ts.id, ts.item_type, ts.item_id, ts.total_amount, gc.redeemed_by,
(ts.created_at = gc.created_at) AS is_create
FROM till_sales ts
LEFT JOIN gift_cards gc ON gc.id = ts.item_id
WHERE ts.square_payment_id = $1 AND ts.status = 'pending'
`, squarePaymentID)
if err != nil {
log.Printf("[SQUARE-WEBHOOK] Failed to read pending till_sales for funding clawback (square payment %s): %v", squarePaymentID, err)
return err
}
defer rows.Close()
for rows.Next() {
var (
saleID string
itemType string
itemID sql.NullString
totalAmount float64
redeemedBy sql.NullString
isCreate *bool
)
if err := rows.Scan(&saleID, &itemType, &itemID, &totalAmount, &redeemedBy, &isCreate); err != nil {
log.Printf("[SQUARE-WEBHOOK] Failed to scan pending till_sale for funding clawback (square payment %s): %v", squarePaymentID, err)
return err
}
if err := clawbackOneTillSale(saleID, itemType, itemID, totalAmount, redeemedBy, isCreate); err != nil {
return err
}
}
return rows.Err()
}
// clawbackOneTillSale resolves one pending till sale of a definitively failed
// charge. A gift-card sale has its funding reverted atomically with the failed
// mark; a sale with no gift card (future retail product / orphaned item) is
// only marked failed. An already-resolved sale is skipped, not an error.
func clawbackOneTillSale(saleID, itemType string, itemID sql.NullString, totalAmount float64, redeemedBy sql.NullString, isCreate *bool) error {
if itemType != "gift_card" || !itemID.Valid || itemID.String == "" || isCreate == nil {
// No gift card to claw back — mark the sale failed without touching
// any card (mirrors the sweep's non-gift-card branch).
tag, err := db.Conn.Exec(context.Background(), `
UPDATE till_sales SET status = 'failed', updated_at = NOW()
WHERE id = $1 AND status = 'pending'
`, saleID)
if err != nil {
log.Printf("[SQUARE-WEBHOOK] Failed to mark till sale %s failed: %v", saleID, err)
return err
}
if tag.RowsAffected() > 0 {
log.Printf("[SQUARE-WEBHOOK] payment.updated: marked till sale %s failed (no gift card to claw back)", saleID)
}
return nil
}
action := "topup"
if *isCreate {
action = "create"
}
var redeem *string
if redeemedBy.Valid && redeemedBy.String != "" {
redeem = &redeemedBy.String
}
if err := revertTillSaleGiftCardFunding(action, itemID.String, totalAmount, redeem, saleID); err != nil {
if errors.Is(err, errTillSaleNotPending) {
log.Printf("[SQUARE-WEBHOOK] Till sale %s was already resolved (not pending) — skipping funding clawback", saleID)
return nil
}
log.Printf("CRITICAL: [SQUARE-WEBHOOK] failed to claw back gift card %s funding for failed till sale %s: %v — MANUAL RECONCILIATION REQUIRED: gift card may still be funded", itemID.String, saleID, err)
return err
}
return nil
}
// revertTillSaleGiftCardFunding undoes the gift-card funding of a till sale
// whose charge definitively failed, in the SAME transaction as the failed mark
// (claim-first): a created card is deleted (with its purchase transaction) and
// any immediate redeem-to-account credit reversed; a topped-up card has the
// amount subtracted back out and its top-up transaction removed. SQL mirrors
// handlers/payments/till.go revertGiftCardFunding.
func revertTillSaleGiftCardFunding(action, giftCardID string, amount float64, redeemToUserID *string, tillSaleID string) error {
tx, err := db.Conn.Begin(context.Background())
if err != nil {
return fmt.Errorf("failed to begin clawback transaction: %w", err)
}
defer func() {
if err := tx.Rollback(context.Background()); err != nil && !errors.Is(err, pgx.ErrTxClosed) {
log.Printf("[SQUARE-WEBHOOK] failed to rollback gift-card clawback transaction: %v", err)
}
}()
// Claim the sale first: the row lock serializes against a concurrent
// completion UPDATE; a zero-row claim means the funding is not ours.
tag, err := tx.Exec(context.Background(), `
UPDATE till_sales SET status = 'failed', updated_at = NOW()
WHERE id = $1 AND status = 'pending'`, tillSaleID)
if err != nil {
return fmt.Errorf("failed to claim till sale for clawback: %w", err)
}
if tag.RowsAffected() == 0 {
return errTillSaleNotPending
}
if action == "create" {
// A newly created card's transactions are scoped to THIS sale's
// funding (reference_type='till_sale' AND reference_id=sale id) — never
// a wholesale delete, which would destroy the value of a different
// idempotency-keyed top-up sale that funded the same card before this
// create resolved. Then remove the card itself.
if _, err := tx.Exec(context.Background(), `DELETE FROM gift_card_transactions WHERE gift_card_id = $1 AND reference_type = 'till_sale' AND reference_id = $2`, giftCardID, tillSaleID); err != nil {
return fmt.Errorf("failed to delete gift card transaction: %w", err)
}
if _, err := tx.Exec(context.Background(), `DELETE FROM gift_cards WHERE id = $1`, giftCardID); err != nil {
return fmt.Errorf("failed to delete gift card: %w", err)
}
// If the card was immediately redeemed to a user balance in this
// request, reverse that credit (guarded so it can never go negative).
if redeemToUserID != nil && *redeemToUserID != "" {
bTag, bErr := tx.Exec(context.Background(), `
UPDATE user_giftcard_balances
SET balance = user_giftcard_balances.balance - $1, updated_at = NOW()
WHERE user_id = $2 AND balance >= $1
`, amount, *redeemToUserID)
if bErr != nil {
return fmt.Errorf("failed to reverse redeemed gift card balance: %w", bErr)
}
if bTag.RowsAffected() == 0 {
log.Printf("CRITICAL: [SQUARE-WEBHOOK] ... MANUAL RECONCILIATION REQUIRED: create-with-redeem clawback for gift card %s could not fully reverse the £%.2f balance credited to user %s (balance < amount)", giftCardID, amount, *redeemToUserID)
}
}
} else {
// Top-up: subtract the amount back out of the card. The guard keeps
// amount_remaining from ever going negative in the pathological case
// where some of the top-up was already spent before the charge failed.
tag, err := tx.Exec(context.Background(), `
UPDATE gift_cards
SET total_funds_added = total_funds_added - $1,
amount_remaining = amount_remaining - $1
WHERE id = $2 AND amount_remaining >= $1
`, amount, giftCardID)
if err != nil {
return fmt.Errorf("failed to reverse gift card top-up: %w", err)
}
if tag.RowsAffected() == 0 {
log.Printf("CRITICAL: [SQUARE-WEBHOOK] ... MANUAL RECONCILIATION REQUIRED: top-up %v on gift card %s could not be fully reversed (amount_remaining < top-up)", amount, giftCardID)
}
// Remove only this request's top-up transaction (reference_id = till
// sale) so prior sales' accounting on the same card is untouched.
if _, err := tx.Exec(context.Background(), `
DELETE FROM gift_card_transactions
WHERE gift_card_id = $1 AND reference_type = 'till_sale' AND reference_id = $2
`, giftCardID, tillSaleID); err != nil {
return fmt.Errorf("failed to delete gift card top-up transaction: %w", err)
}
}
if err := tx.Commit(context.Background()); err != nil {
return fmt.Errorf("failed to commit clawback transaction: %w", err)
}
return nil
}
// handleRefundUpdated reconciles a Square Refund state change against the local
// refunds row. Idempotent (status-guarded UPDATE + event_id dedup).
func handleRefundUpdated(data json.RawMessage) {
// refunds row. Idempotent (status-guarded UPDATE + event_id dedup). A non-nil
// error means dispatch failed and the caller must NOT commit the dedup row.
func handleRefundUpdated(data json.RawMessage) error {
var env squareWebhookData
if err := json.Unmarshal(data, &env); err != nil {
log.Printf("[SQUARE-WEBHOOK] refund.updated received (payload length=%d)", len(data))
return
return nil
}
if env.ID == "" {
log.Printf("[SQUARE-WEBHOOK] refund.updated received (payload length=%d)", len(data))
return
return nil
}
var refund squareRefundPayload
if !parseSquareObject(env.Object, "refund", &refund) || refund.ID == "" || refund.Status == "" {
log.Printf("[SQUARE-WEBHOOK] refund.updated received (data.id=%s)", env.ID)
return
return nil
}
localStatus, terminal := squareRefundStatusToLocal(refund.Status)
if !terminal {
log.Printf("[SQUARE-WEBHOOK] refund.updated: square refund %s status %q is non-terminal — no local state change", refund.ID, refund.Status)
return
return nil
}
// COMPLETED may promote any non-completed row (incl. a sweep-failed refund
// Square later shows complete) — the over-refund guard counts completed
@@ -520,17 +720,18 @@ func handleRefundUpdated(data json.RawMessage) {
tag, err := db.Conn.Exec(context.Background(), upd, refund.ID)
if err != nil {
log.Printf("[SQUARE-WEBHOOK] Failed to update refund %s to status %s: %v", refund.ID, localStatus, err)
return
return err
}
if tag.RowsAffected() > 0 {
log.Printf("[SQUARE-WEBHOOK] refund.updated: square refund %s → local status %s", refund.ID, localStatus)
}
return nil
}
// truncateDisputeReason caps a Square dispute reason at the disputes.reason
// VARCHAR(192) column width. An over-long reason would fail the INSERT — and
// because the event_id dedup row commits BEFORE dispatch, a failed insert
// silently drops the dispute (money-at-risk with no record).
// VARCHAR(192) column width. An over-long reason would fail the disputes
// INSERT; the handler treats that as a dispatch error (no dedup row, 5xx), so
// Square would retry forever — truncating lets the event succeed instead.
func truncateDisputeReason(reason string) string {
if len(reason) > 192 {
return reason[:192]
@@ -541,17 +742,18 @@ func truncateDisputeReason(reason string) string {
// handleDisputeCreated records a newly opened dispute: inserts the disputes row
// and surfaces a critical_payment_log admin notification so the owner sees the
// chargeback in-app. Idempotent via ON CONFLICT (square_dispute_id) DO NOTHING
// plus the event_id dedup.
func handleDisputeCreated(data json.RawMessage) {
// plus the event_id dedup. A non-nil error means dispatch failed (no dedup row
// committed — Square retries).
func handleDisputeCreated(data json.RawMessage) error {
var env squareWebhookData
if err := json.Unmarshal(data, &env); err != nil {
log.Printf("[SQUARE-WEBHOOK] dispute.created received (payload length=%d)", len(data))
return
return nil
}
var dispute squareDisputePayload
if !parseSquareObject(env.Object, "dispute", &dispute) || dispute.ID == "" {
log.Printf("[SQUARE-WEBHOOK] dispute.created received (data.id=%s)", env.ID)
return
return nil
}
squarePaymentID := ""
if dispute.DisputedPayment != nil {
@@ -560,7 +762,7 @@ func handleDisputeCreated(data json.RawMessage) {
paymentID, bookingID, paymentFound := findPaymentBySquareID(squarePaymentID)
if !paymentFound {
log.Printf("[SQUARE-WEBHOOK] dispute.created: no local payment for square payment %q — dispute %s not recorded", squarePaymentID, dispute.ID)
return
return nil
}
amount := squareMoneyToAmount(dispute.AmountMoney)
tag, err := db.Conn.Exec(context.Background(), `
@@ -570,27 +772,29 @@ func handleDisputeCreated(data json.RawMessage) {
`, dispute.ID, paymentID, amount, truncateDisputeReason(dispute.Reason))
if err != nil {
log.Printf("[SQUARE-WEBHOOK] Failed to insert dispute %s: %v", dispute.ID, err)
return
return err
}
_ = tag
insertCriticalPaymentNotification(bookingID)
log.Printf("[SQUARE-WEBHOOK] CRITICAL: dispute %s created (amount %s, reason %q) for square payment %s — admin notified", dispute.ID, amount, dispute.Reason, squarePaymentID)
return nil
}
// handleDisputeStateUpdated applies a Square dispute state change to the local
// disputes row (upsert — a state.updated may arrive before the created event),
// and on a terminal loss marks the payment failed + raises CRITICAL. Won is
// logged only. Idempotent: the upsert converges to the same row.
func handleDisputeStateUpdated(data json.RawMessage) {
// logged only. Idempotent: the upsert converges to the same row. A non-nil
// error means dispatch failed (no dedup row committed — Square retries).
func handleDisputeStateUpdated(data json.RawMessage) error {
var env squareWebhookData
if err := json.Unmarshal(data, &env); err != nil {
log.Printf("[SQUARE-WEBHOOK] dispute.state.updated received (payload length=%d)", len(data))
return
return nil
}
var dispute squareDisputePayload
if !parseSquareObject(env.Object, "dispute", &dispute) || dispute.ID == "" {
log.Printf("[SQUARE-WEBHOOK] dispute.state.updated received (data.id=%s)", env.ID)
return
return nil
}
localStatus := squareDisputeStateToLocal(dispute.State)
amount := squareMoneyToAmount(dispute.AmountMoney)
@@ -605,7 +809,7 @@ func handleDisputeStateUpdated(data json.RawMessage) {
paymentID, bookingID = findPaymentByDisputeID(dispute.ID)
if paymentID == "" {
log.Printf("[SQUARE-WEBHOOK] dispute.state.updated: no local payment for dispute %s (square payment %q) — cannot record state %s", dispute.ID, squarePaymentID, dispute.State)
return
return nil
}
}
@@ -618,12 +822,14 @@ func handleDisputeStateUpdated(data json.RawMessage) {
`, dispute.ID, paymentID, localStatus, amount, truncateDisputeReason(dispute.Reason))
if err != nil {
log.Printf("[SQUARE-WEBHOOK] Failed to update dispute %s to state %s: %v", dispute.ID, dispute.State, err)
return
return err
}
switch localStatus {
case "lost":
markPaymentFailed(paymentID)
if err := markPaymentFailed(paymentID); err != nil {
return err
}
insertCriticalPaymentNotification(bookingID)
log.Printf("[SQUARE-WEBHOOK] CRITICAL: dispute %s LOST — payment %s marked failed; admin notified", dispute.ID, paymentID)
case "won":
@@ -631,32 +837,35 @@ func handleDisputeStateUpdated(data json.RawMessage) {
default:
log.Printf("[SQUARE-WEBHOOK] dispute %s state → %s (status %s)", dispute.ID, dispute.State, localStatus)
}
return nil
}
// handleDisputeEvidence logs evidence submissions/removals. Evidence does not
// change the dispute's local status, so it is informational only.
func handleDisputeEvidence(data json.RawMessage) {
func handleDisputeEvidence(data json.RawMessage) error {
var env squareWebhookData
if err := json.Unmarshal(data, &env); err != nil {
log.Printf("[SQUARE-WEBHOOK] dispute evidence event received (payload length=%d)", len(data))
return
return nil
}
var dispute squareDisputePayload
if !parseSquareObject(env.Object, "dispute", &dispute) || dispute.ID == "" {
log.Printf("[SQUARE-WEBHOOK] dispute evidence event received (data.id=%s)", env.ID)
return
return nil
}
log.Printf("[SQUARE-WEBHOOK] dispute evidence event for dispute %s (state %s)", dispute.ID, dispute.State)
return nil
}
// handleTerminalCheckout logs terminal checkout lifecycle events. Terminal
// checkout state is owned by the poll/sweep handlers (handlers/payments/),
// which fetch the authoritative status from Square — no state mutation here.
func handleTerminalCheckout(data json.RawMessage) {
func handleTerminalCheckout(data json.RawMessage) error {
var env squareWebhookData
if err := json.Unmarshal(data, &env); err != nil {
log.Printf("[SQUARE-WEBHOOK] terminal.checkout event received (payload length=%d)", len(data))
return
return nil
}
log.Printf("[SQUARE-WEBHOOK] terminal.checkout event received (data.id=%s)", env.ID)
return nil
}
backend/handlers/webhooks/webhooks_dispatch_error_test.go
+83
View File
@@ -0,0 +1,83 @@
//go:build test
package webhooks
// Regression test for the at-least-once webhook delivery contract: a dispatch
// error must NOT commit the dedup row, so Square's retry is not swallowed.
import (
"encoding/json"
"net/http"
"testing"
)
// TestHandleSquareWebhook_DispatchError_NoDedup_RetryReDispatches verifies the
// handler's dispatch-first/commit-dedup-after order: when the dispatch handler
// errors (here the disputes INSERT fails because the amount overflows
// NUMERIC(10,2)), the handler returns 503 and records NO dedup row — so a
// replayed delivery (Square's retry) is re-dispatched, not 200-skipped. Before
// the at-least-once ordering this invariant silently dropped events on any
// transient dispatch failure.
func TestHandleSquareWebhook_DispatchError_NoDedup_RetryReDispatches(t *testing.T) {
const squarePaymentID = "sqp_dispatch_err"
_ = createWebhookTestPayment(t, squarePaymentID, "completed")
// amount_money.amount = 9,999,999,999,999,999 pence → £99,999,999,999,999.99,
// far beyond disputes.amount NUMERIC(10,2) — the INSERT fails.
overflowEvent := SquareWebhookEvent{
Type: "dispute.created",
EventID: "evt_dispatch_err_1",
CreatedAt: "2025-01-01T00:00:00Z",
Data: json.RawMessage(`{
"type": "dispute",
"id": "dts_dispatch_err_1",
"object": {
"dispute": {
"id": "dts_dispatch_err_1",
"state": "UNDER_REVIEW",
"amount_money": {"amount": 9999999999999999, "currency": "GBP"},
"reason": "OVERFLOW",
"disputed_payment": {"payment_id": "` + squarePaymentID + `"}
}
}
}`),
}
w1 := deliverWebhook(t, overflowEvent)
if w1.Code != http.StatusServiceUnavailable {
t.Fatalf("expected 503 on dispatch error, got %d: %s", w1.Code, w1.Body.String())
}
if n := countWebhookEvents(t, overflowEvent.EventID); n != 0 {
t.Fatalf("expected NO dedup row after a dispatch error (Square must retry), got %d", n)
}
// Square retries with a well-formed payload under the SAME event_id.
retryEvent := SquareWebhookEvent{
Type: "dispute.created",
EventID: "evt_dispatch_err_1",
CreatedAt: "2025-01-01T00:00:00Z",
Data: json.RawMessage(`{
"type": "dispute",
"id": "dts_dispatch_err_1",
"object": {
"dispute": {
"id": "dts_dispatch_err_1",
"state": "UNDER_REVIEW",
"amount_money": {"amount": 1234, "currency": "GBP"},
"reason": "NO_KNOWLEDGE",
"disputed_payment": {"payment_id": "` + squarePaymentID + `"}
}
}
}`),
}
w2 := deliverWebhook(t, retryEvent)
if w2.Code != http.StatusOK {
t.Fatalf("expected retry 200, got %d: %s", w2.Code, w2.Body.String())
}
if got := getDisputeStatus(t, "dts_dispatch_err_1"); got != "open" {
t.Errorf("expected retried dispute to be recorded with status 'open', got %q", got)
}
if n := countWebhookEvents(t, retryEvent.EventID); n != 1 {
t.Errorf("expected exactly 1 dedup row after the successful retry, got %d", n)
}
}
backend/handlers/webhooks/webhooks_state_test.go
+152
View File
@@ -11,6 +11,7 @@ import (
"testing"
"crussell/db"
"crussell/testutils/fixtures"
)
// =============================================================================
@@ -99,6 +100,157 @@ func deliverWebhook(t *testing.T, event SquareWebhookEvent) *httptest.ResponseRe
return makeWebhookRequest(body, sig, context.Background())
}
// createWebhookTestGiftCardAndSale seeds a pending gift-card till sale tied to
// a Square payment id and returns the sale id and gift card id. When
// cardCreatedAt == saleCreatedAt the sale created the card (is_create → action
// 'create'); otherwise the card pre-exists (action 'topup'). cardAmount is the
// card's starting total_funds_added/amount_remaining.
func createWebhookTestGiftCardAndSale(t *testing.T, squarePaymentID, cardCreatedAt, saleCreatedAt string, cardAmount float64) (saleID, giftCardID string) {
t.Helper()
adminID, err := fixtures.CreateTestAdminUser(db.Conn)
if err != nil {
t.Fatalf("failed to create admin user: %v", err)
}
if err := db.Conn.QueryRow(context.Background(), `
INSERT INTO gift_cards (total_funds_added, amount_remaining, created_by, is_inventory, voucher_type_at_purchase, created_at)
VALUES ($1, $1, $2, FALSE, 'SPV', $3::timestamptz)
RETURNING id
`, cardAmount, adminID, cardCreatedAt).Scan(&giftCardID); err != nil {
t.Fatalf("failed to create gift card: %v", err)
}
if err := db.Conn.QueryRow(context.Background(), `
INSERT INTO till_sales (item_type, item_id, description, quantity, unit_price, total_amount,
payment_method, status, square_payment_id, created_by, created_at, updated_at)
VALUES ('gift_card', $1, 'webhook clawback test', 1, 40.00, 40.00, 'online_square', 'pending',
$2, $3, $4::timestamptz, NOW())
RETURNING id
`, giftCardID, squarePaymentID, adminID, saleCreatedAt).Scan(&saleID); err != nil {
t.Fatalf("failed to create pending till sale: %v", err)
}
return saleID, giftCardID
}
// deliverPaymentUpdatedFailed dispatches a payment.updated webhook carrying a
// definitively FAILED Square status for the given Square payment id.
func deliverPaymentUpdatedFailed(t *testing.T, squarePaymentID string) *httptest.ResponseRecorder {
t.Helper()
event := SquareWebhookEvent{
Type: "payment.updated",
EventID: "evt_" + squarePaymentID,
CreatedAt: "2025-01-01T00:00:00Z",
Data: json.RawMessage(`{
"type": "payment",
"id": "` + squarePaymentID + `",
"object": {
"payment": {
"id": "` + squarePaymentID + `",
"status": "FAILED"
}
}
}`),
}
return deliverWebhook(t, event)
}
func getTillSaleStatus(t *testing.T, id string) string {
t.Helper()
var status string
if err := db.Conn.QueryRow(context.Background(),
"SELECT status FROM till_sales WHERE id = $1", id).Scan(&status); err != nil {
t.Fatalf("failed to read till_sales status: %v", err)
}
return status
}
func getGiftCardFunding(t *testing.T, id string) (totalFundsAdded, amountRemaining float64) {
t.Helper()
if err := db.Conn.QueryRow(context.Background(),
"SELECT total_funds_added, amount_remaining FROM gift_cards WHERE id = $1", id).Scan(&totalFundsAdded, &amountRemaining); err != nil {
t.Fatalf("failed to read gift card funding: %v", err)
}
return totalFundsAdded, amountRemaining
}
// =============================================================================
// Till-sale gift-card clawback — payment.updated FAILED/CANCELED
// =============================================================================
// TestWebhook_PaymentUpdated_Failed_ClawsBackCreatedCard verifies that a
// definitively-failed Square charge (FAILED) claws back the gift-card funding
// of a pending till sale that CREATED the card: the card and its purchase
// transaction are deleted and the sale is marked failed, exactly as the sweep
// does.
func TestWebhook_PaymentUpdated_Failed_ClawsBackCreatedCard(t *testing.T) {
const squarePaymentID = "sqp_clawback_create"
const cardCreatedAt = "2025-01-01T00:00:00Z"
saleID, giftCardID := createWebhookTestGiftCardAndSale(t, squarePaymentID, cardCreatedAt, cardCreatedAt, 40.00)
w := deliverPaymentUpdatedFailed(t, squarePaymentID)
if w.Code != http.StatusOK {
t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
}
if got := getTillSaleStatus(t, saleID); got != "failed" {
t.Errorf("expected till sale 'failed', got %q", got)
}
if exists := giftCardExists(t, giftCardID); exists {
t.Error("expected created gift card to be deleted by the clawback")
}
}
// TestWebhook_PaymentUpdated_Failed_ClawsBackTopup verifies the top-up
// clawback for a pre-existing card: the sale's funding is subtracted back out
// of the card and the sale is marked failed.
func TestWebhook_PaymentUpdated_Failed_ClawsBackTopup(t *testing.T) {
const squarePaymentID = "sqp_clawback_topup"
saleID, giftCardID := createWebhookTestGiftCardAndSale(t, squarePaymentID, "2025-01-01T00:00:00Z", "2025-01-02T00:00:00Z", 60.00)
w := deliverPaymentUpdatedFailed(t, squarePaymentID)
if w.Code != http.StatusOK {
t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
}
if got := getTillSaleStatus(t, saleID); got != "failed" {
t.Errorf("expected till sale 'failed', got %q", got)
}
total, remaining := getGiftCardFunding(t, giftCardID)
if total != 20.00 || remaining != 20.00 {
t.Errorf("expected top-up clawback to leave £20.00 on the card, got total=%v remaining=%v", total, remaining)
}
}
// TestWebhook_PaymentUpdated_Failed_AlreadyResolved_Skipped verifies the
// clawback skips without error when the till sale is already resolved (not
// pending): the webhook still acknowledges 200 and leaves the terminal state
// untouched.
func TestWebhook_PaymentUpdated_Failed_AlreadyResolved_Skipped(t *testing.T) {
const squarePaymentID = "sqp_clawback_resolved"
saleID, giftCardID := createWebhookTestGiftCardAndSale(t, squarePaymentID, "2025-01-01T00:00:00Z", "2025-01-01T00:00:00Z", 40.00)
if _, err := db.Conn.Exec(context.Background(),
"UPDATE till_sales SET status = 'completed', updated_at = NOW() WHERE id = $1", saleID); err != nil {
t.Fatalf("failed to resolve till sale: %v", err)
}
w := deliverPaymentUpdatedFailed(t, squarePaymentID)
if w.Code != http.StatusOK {
t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
}
if got := getTillSaleStatus(t, saleID); got != "completed" {
t.Errorf("expected resolved till sale to stay 'completed', got %q", got)
}
if total, remaining := getGiftCardFunding(t, giftCardID); total != 40.00 || remaining != 40.00 {
t.Errorf("expected gift card untouched when the sale is already resolved, got total=%v remaining=%v", total, remaining)
}
}
func giftCardExists(t *testing.T, id string) bool {
t.Helper()
var n int
if err := db.Conn.QueryRow(context.Background(),
"SELECT COUNT(*) FROM gift_cards WHERE id = $1", id).Scan(&n); err != nil {
t.Fatalf("failed to count gift cards: %v", err)
}
return n > 0
}
// =============================================================================
// Dispute handling — dispute.created
// =============================================================================
backend/handlers/webhooks/webhooks_test.go
+6 -3
View File
@@ -499,7 +499,10 @@ func TestHandleSquareWebhook_DedupDispatchOnce(t *testing.T) {
// TestHandleSquareWebhook_DedupPersistsAcrossRestart simulates a restart: the
// event was handled by a previous process whose in-memory cache is gone, but
// the dedup row survived in the DB — the replayed delivery must be skipped.
// the dedup row survived in the DB. The dedup row now commits AFTER dispatch
// (at-least-once delivery), so a replayed delivery is re-dispatched — the
// idempotent status-guarded handlers are a no-op the second time — and is
// acknowledged 200 without duplicating the persisted dedup row.
func TestHandleSquareWebhook_DedupPersistsAcrossRestart(t *testing.T) {
event := SquareWebhookEvent{
Type: "payment.updated",
@@ -527,8 +530,8 @@ func TestHandleSquareWebhook_DedupPersistsAcrossRestart(t *testing.T) {
if w.Body.String() != "ok" {
t.Errorf("expected body 'ok', got %q", w.Body.String())
}
if out := buf.String(); strings.Contains(out, "Received event: payment.updated") {
t.Errorf("expected replayed event to skip dispatch, got:\n%s", out)
if out := buf.String(); !strings.Contains(out, "Received event: payment.updated") {
t.Errorf("expected replayed event to be re-dispatched (at-least-once), got:\n%s", out)
}
if n := countWebhookEvents(t, event.EventID); n != 1 {
t.Errorf("expected still exactly 1 dedup row, got %d", n)