chore(ops): add nightly backup verification scripts

* feat(sca): handle 3ds checkout end to end with qr poll and race fix

* fix(sca): drop unused pollOrderStatusCmd helper

.github/workflows/ci.yml

@@ -8,9 +8,9 @@ jobs:
   check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-go@v5
+      - uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
 
@@ -30,6 +30,7 @@ jobs:
           fi
 
       - name: Lint
+        if: ${{ !env.ACT }}
         uses: golangci/golangci-lint-action@v7
         with:
           version: v2.4.0

.github/workflows/deploy.yml

@@ -8,10 +8,10 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
         with:
-          go-version: '1.23'
+          go-version-file: go.mod
       - name: Run tests
         run: go test ./...
       - name: Deploy to server

.gitignore

@@ -5,6 +5,9 @@
 .env.example
 .env.prod
 
+docs/sca-psd2-compliance.md
+accept-a-payment/
+
 
 FULFILLMENT.md
 .tmp-gocache/
@@ -111,3 +114,6 @@ ROADMAP.md
 
 *.bak
 terminalshop.prod.*
+
+# Backup verification config (real values; example file is committed)
+scripts/backups/config.env

api/handlers/cards.go

@@ -7,7 +7,7 @@ import (
 	"fmt"
 	"net/http"
 	"strconv"
-	"sync"
+	"time"
 
 	"github.com/go-chi/chi/v5"
 	"github.com/stripe/stripe-go/v78"
@@ -24,35 +24,43 @@ import (
 	stripeSession "github.com/stripe/stripe-go/v78/checkout/session"
 )
 
-// payRedirects maps short tokens to full Stripe checkout URLs.
-var (
-	payRedirects   = map[string]string{}
-	payRedirectsMu sync.Mutex
-)
+const RedirectTTL = 10 * time.Minute
 
-func storeRedirect(stripeURL string) (string, error) {
+func storeRedirect(stripeURL, purpose string) (string, error) {
 	b := make([]byte, 16)
 	if _, err := rand.Read(b); err != nil {
 		return "", err
 	}
 	token := hex.EncodeToString(b)
-	payRedirectsMu.Lock()
-	payRedirects[token] = stripeURL
-	payRedirectsMu.Unlock()
+	now := time.Now()
+	rec := models.PayRedirect{
+		Token:     token,
+		URL:       stripeURL,
+		Purpose:   purpose,
+		CreatedAt: now,
+		ExpiresAt: now.Add(RedirectTTL),
+	}
+	if err := database.GetDB().Create(&rec).Error; err != nil {
+		return "", err
+	}
 	return token, nil
 }
 
 // PayRedirect resolves a short token and redirects to the Stripe checkout URL.
 func PayRedirect(w http.ResponseWriter, r *http.Request) {
 	token := chi.URLParam(r, "token")
-	payRedirectsMu.Lock()
-	url, ok := payRedirects[token]
-	payRedirectsMu.Unlock()
-	if !ok {
+	db := database.GetDB().WithContext(r.Context())
+	var rec models.PayRedirect
+	if err := db.Where("token = ?", token).First(&rec).Error; err != nil {
 		http.NotFound(w, r)
 		return
 	}
-	http.Redirect(w, r, url, http.StatusFound)
+	if time.Now().After(rec.ExpiresAt) {
+		db.Where("token = ?", rec.Token).Delete(&models.PayRedirect{})
+		http.NotFound(w, r)
+		return
+	}
+	http.Redirect(w, r, rec.URL, http.StatusFound)
 }
 
 // CardHandler handles saved payment method CRUD.
@@ -168,7 +176,7 @@ func (h *CardHandler) CollectCard(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	token, err := storeRedirect(sess.URL)
+	token, err := storeRedirect(sess.URL, models.RedirectPurposeAddCard)
 	if err != nil {
 		utils.RespondError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "failed to generate redirect token", nil)
 		return

api/handlers/cart.go

@@ -23,12 +23,14 @@ import (
 )
 
 type CartHandler struct {
-	stripeKey string
+	stripeKey     string
+	appURL        string
+	maxOrderCents int
 }
 
 // NewCartHandler creates a new cart handler with the Stripe secret key
-func NewCartHandler(stripeSecretKey string) *CartHandler {
-	return &CartHandler{stripeKey: stripeSecretKey}
+func NewCartHandler(stripeSecretKey, appURL string, maxOrderCents int) *CartHandler {
+	return &CartHandler{stripeKey: stripeSecretKey, appURL: appURL, maxOrderCents: maxOrderCents}
 }
 
 // getOrCreateCart finds the users cart or creates one.
@@ -353,6 +355,17 @@ func (h *CartHandler) ConvertCart(w http.ResponseWriter, r *http.Request) {
 
 	total := subtotal + cart.ShippingCost
 
+	if h.maxOrderCents > 0 && total > h.maxOrderCents {
+		middleware.RecordCartConversion("validation_over_limit")
+		utils.RespondError(w, http.StatusBadRequest, "CART_OVER_LIMIT",
+			fmt.Sprintf("order total must be at most $%.2f", float64(h.maxOrderCents)/100),
+			map[string]interface{}{
+				"total_cents": total,
+				"limit_cents": h.maxOrderCents,
+			})
+		return
+	}
+
 	if total < 50 {
 		middleware.RecordCartConversion("validation_min_amount")
 		utils.RespondError(w, http.StatusBadRequest, "VALIDATION_ERROR", "order total must be at least $0.50", nil)
@@ -391,16 +404,15 @@ func (h *CartHandler) ConvertCart(w http.ResponseWriter, r *http.Request) {
 	// Charge the card. The idempotency key is tied to the order ID so retries
 	// never produce a double charge.
 	piParams := &stripe.PaymentIntentParams{
-		Amount:        stripe.Int64(int64(total)),
-		Currency:      stripe.String(string(stripe.CurrencyUSD)),
-		Customer:      stripe.String(user.StripeCustomerID),
-		PaymentMethod: stripe.String(paymentMethodID),
-		AutomaticPaymentMethods: &stripe.PaymentIntentAutomaticPaymentMethodsParams{
-			Enabled:        stripe.Bool(true),
-			AllowRedirects: stripe.String("never"),
-		},
-		Confirm:     stripe.Bool(true),
-		Description: stripe.String(fmt.Sprintf("terminal.shop order #%d", order.ID)),
+		Amount:             stripe.Int64(int64(total)),
+		Currency:           stripe.String(string(stripe.CurrencyUSD)),
+		Customer:           stripe.String(user.StripeCustomerID),
+		PaymentMethod:      stripe.String(paymentMethodID),
+		OffSession:         stripe.Bool(true),
+		PaymentMethodTypes: stripe.StringSlice([]string{"card"}),
+		ReturnURL:          stripe.String(h.appURL + "/post-3ds"),
+		Confirm:            stripe.Bool(true),
+		Description:        stripe.String(fmt.Sprintf("terminal.shop order #%d", order.ID)),
 		Shipping: &stripe.ShippingDetailsParams{
 			Name: stripe.String(address.Name),
 			Address: &stripe.AddressParams{
@@ -423,13 +435,17 @@ func (h *CartHandler) ConvertCart(w http.ResponseWriter, r *http.Request) {
 	stripeDur := time.Since(stripeStart).Seconds()
 	if err != nil {
 		middleware.ObserveStripeRequest("payment_intent_create", "error", stripeDur)
-		db.Model(&order).Update("status", models.OrderStatusFailed)
 		if stripeErr, ok := err.(*stripe.Error); ok {
+			if stripeErr.Code == stripe.ErrorCodeAuthenticationRequired && stripeErr.PaymentIntent != nil {
+				h.respondRequiresAction(w, &order, paymentMethodID, stripeErr.PaymentIntent)
+				return
+			}
+			db.Model(&order).Update("status", models.OrderStatusFailed)
 			switch stripeErr.Type {
 			case stripe.ErrorTypeCard:
 				middleware.RecordCartConversion("card_declined")
 				audit.OrderFailed(userID, order.ID, total, stripeErr.Msg)
-				utils.RespondError(w, http.StatusPaymentRequired, "CARD_DECLINED", stripeErr.Msg, nil)
+				utils.RespondError(w, http.StatusPaymentRequired, mapStripeCardErrCode(stripeErr.Code), stripeErr.Msg, nil)
 			case stripe.ErrorTypeInvalidRequest:
 				middleware.RecordCartConversion("stripe_invalid_request")
 				audit.OrderFailed(userID, order.ID, total, stripeErr.Msg)
@@ -441,6 +457,7 @@ func (h *CartHandler) ConvertCart(w http.ResponseWriter, r *http.Request) {
 			}
 			return
 		}
+		db.Model(&order).Update("status", models.OrderStatusFailed)
 		middleware.RecordCartConversion("stripe_error")
 		audit.OrderFailed(userID, order.ID, total, err.Error())
 		utils.RespondError(w, http.StatusInternalServerError, "PAYMENT_FAILED", "payment failed", nil)
@@ -448,6 +465,11 @@ func (h *CartHandler) ConvertCart(w http.ResponseWriter, r *http.Request) {
 	}
 	middleware.ObserveStripeRequest("payment_intent_create", "success", stripeDur)
 
+	if pi.Status == stripe.PaymentIntentStatusRequiresAction {
+		h.respondRequiresAction(w, &order, paymentMethodID, pi)
+		return
+	}
+
 	// Commit payment ID and clear cart in a single transaction.
 	txErr := db.Transaction(func(tx *gorm.DB) error {
 		order.StripePaymentID = pi.ID
@@ -489,3 +511,95 @@ func (h *CartHandler) ConvertCart(w http.ResponseWriter, r *http.Request) {
 		"order": order,
 	})
 }
+
+// respondRequiresAction handles a PaymentIntent that needs 3DS auth
+// The order stays pending. the webhook flips it to paid once the customer
+// completes the bank-hosted challenge, the tui polls /api/v1/orders/{id}/status
+func (h *CartHandler) respondRequiresAction(w http.ResponseWriter, order *models.Order, paymentMethodID string, pi *stripe.PaymentIntent) {
+	db := database.GetDB()
+
+	// After an off-session authentication_required decline, the PI sits in
+	// status=requires_payment_method with payment_method detached. Re-confirm
+	// on-session with the same PM so Stripe pushes the PI into requires_action
+	// and populates next_action.redirect_to_url with the 3DS challenge URL.
+	if pi.NextAction == nil || pi.NextAction.RedirectToURL == nil || pi.NextAction.RedirectToURL.URL == "" {
+		confirmed, cerr := paymentintent.Confirm(pi.ID, &stripe.PaymentIntentConfirmParams{
+			PaymentMethod: stripe.String(paymentMethodID),
+			OffSession:    stripe.Bool(false),
+			ReturnURL:     stripe.String(h.appURL + "/post-3ds"),
+		})
+		if cerr == nil && confirmed != nil {
+			pi = confirmed
+		}
+	}
+
+	if pi.NextAction == nil || pi.NextAction.RedirectToURL == nil || pi.NextAction.RedirectToURL.URL == "" {
+		middleware.RecordCartConversion("sca_missing_next_action")
+		db.Model(order).Update("status", models.OrderStatusFailed)
+		audit.OrderFailed(order.UserID, order.ID, order.Total, "stripe returned requires_action without redirect url")
+		utils.RespondError(w, http.StatusBadGateway, "PAYMENT_FAILED", "stripe did not return a 3ds url", nil)
+		return
+	}
+
+	// Persist the paymentIntent id AND reset status to pending. The
+	// payment_intent.payment_failed webhook from the initial off-session decline
+	// often arrives before this response and flips the order to failed —
+	// override it back so the 3DS-in-flight order shows the correct state.
+	if err := db.Model(order).Updates(map[string]any{
+		"stripe_payment_id": pi.ID,
+		"status":            models.OrderStatusPending,
+	}).Error; err != nil {
+		utils.RespondError(w, http.StatusInternalServerError, "DATABASE_ERROR", "failed to save payment id", nil)
+		return
+	}
+
+	token, err := storeRedirect(pi.NextAction.RedirectToURL.URL, models.RedirectPurposeCheckout3DS)
+	if err != nil {
+		utils.RespondError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "failed to allocate redirect token", nil)
+		return
+	}
+
+	middleware.RecordCartConversion("requires_action")
+	audit.OrderRequiresAction(order.UserID, order.ID, pi.ID)
+
+	utils.RespondSuccess(w, http.StatusAccepted, map[string]any{
+		"order_id":          order.ID,
+		"payment_intent_id": pi.ID,
+		"status":            "requires_action",
+		"redirect_token":    token,
+		"redirect_url":      fmt.Sprintf("%s/pay/%s", h.appURL, token),
+	})
+}
+
+func mapStripeCardErrCode(code stripe.ErrorCode) string {
+	switch code {
+	case stripe.ErrorCodeAuthenticationRequired:
+		return "AUTHENTICATION_REQUIRED"
+	case "authentication_not_supported":
+		return "AUTHENTICATION_NOT_SUPPORTED"
+	case "card_declined", "":
+		return "CARD_DECLINED"
+	case "expired_card":
+		return "CARD_EXPIRED"
+	case "incorrect_cvc":
+		return "CARD_CVC_FAILED"
+	case "insufficient_funds":
+		return "CARD_INSUFFICIENT_FUNDS"
+	case "processing_error":
+		return "CARD_PROCESSING_ERROR"
+	}
+	return "CARD_DECLINED"
+}
+
+//nolint:unused // wired into Convert cart later
+func appURLForHandler(r *http.Request) string {
+	scheme := "http"
+	if r.TLS != nil || r.Header.Get("X-Forwarded-Proto") == "https" {
+		scheme = "https"
+	}
+	host := r.Host
+	if fh := r.Header.Get("X-Forwarded-Host"); fh != "" {
+		host = fh
+	}
+	return fmt.Sprintf("%s://%s", scheme, host)
+}

api/handlers/cart_test.go

@@ -65,7 +65,7 @@ func TestGetCartEmpty(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	req := authRequest("GET", "/api/v1/cart", nil, user.ID)
 	w := httptest.NewRecorder()
@@ -104,7 +104,7 @@ func TestSetItemAndGetCart(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	// Add item (CoffeeID=1, Quantity=2)
 	body, _ := json.Marshal(map[string]interface{}{
@@ -160,7 +160,7 @@ func TestSetItemUpdateQuantity(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	// Add item
 	body, _ := json.Marshal(map[string]interface{}{"coffee_id": 1, "quantity": 2})
@@ -205,7 +205,7 @@ func TestSetItemRemove(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	// Add item
 	body, _ := json.Marshal(map[string]interface{}{"coffee_id": 1, "quantity": 3})
@@ -244,7 +244,7 @@ func TestSetItemInvalidProduct(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	body, _ := json.Marshal(map[string]interface{}{"coffee_id": 999, "quantity": 1})
 	req := authRequest("PUT", "/api/v1/cart/item", body, user.ID)
@@ -261,7 +261,7 @@ func TestSetItemMissingCoffeeID(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	body, _ := json.Marshal(map[string]interface{}{"quantity": 1})
 	req := authRequest("PUT", "/api/v1/cart/item", body, user.ID)
@@ -278,7 +278,7 @@ func TestClearCart(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	// Add two items
 	for _, coffeeID := range []uint{1, 2} {
@@ -334,7 +334,7 @@ func TestSetAddress(t *testing.T) {
 	}
 	db.Create(&addr)
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	body, _ := json.Marshal(map[string]interface{}{"address_id": addr.ID})
 	req := authRequest("PUT", "/api/v1/cart/address", body, user.ID)
@@ -388,7 +388,7 @@ func TestSetAddressWrongUser(t *testing.T) {
 	}
 	db.Create(&addr)
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	body, _ := json.Marshal(map[string]interface{}{"address_id": addr.ID})
 	req := authRequest("PUT", "/api/v1/cart/address", body, user.ID)
@@ -416,7 +416,7 @@ func TestSetCard(t *testing.T) {
 	}
 	db.Create(&card)
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	body, _ := json.Marshal(map[string]interface{}{"card_id": card.ID})
 	req := authRequest("PUT", "/api/v1/cart/card", body, user.ID)
@@ -468,7 +468,7 @@ func TestSetCardWrongUser(t *testing.T) {
 	}
 	db.Create(&card)
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	body, _ := json.Marshal(map[string]interface{}{"card_id": card.ID})
 	req := authRequest("PUT", "/api/v1/cart/card", body, user.ID)
@@ -485,7 +485,7 @@ func TestConvertCartMissingAddress(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	// Add item but no address or card
 	body, _ := json.Marshal(map[string]interface{}{"coffee_id": 1, "quantity": 1})
@@ -508,7 +508,7 @@ func TestConvertCartMissingCard(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 	db := database.GetDB()
 
 	// Add item and address
@@ -539,7 +539,7 @@ func TestConvertCartEmpty(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	// Empty cart convert
 	req := authRequest("POST", "/api/v1/cart/convert", nil, user.ID)
@@ -556,7 +556,7 @@ func TestMultipleItems(t *testing.T) {
 	defer func() { _ = os.Remove(testDB) }()
 	defer database.ResetForTesting()
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 
 	// Add three different items
 	for i := uint(1); i <= 3; i++ {
@@ -605,7 +605,7 @@ func TestCartIsolation(t *testing.T) {
 	}
 	db.Create(&user2)
 
-	handler := NewCartHandler("")
+	handler := NewCartHandler("", "", 0)
 	r := chi.NewRouter()
 	r.Put("/cart/item", handler.SetItem)
 	r.Get("/cart", handler.GetCart)
@@ -664,3 +664,103 @@ func TestCartIsolation(t *testing.T) {
 		t.Errorf("User 2 expected coffee_id 2, got %d", resp.Data.Cart.Items[0].CoffeeID)
 	}
 }
+
+func TestConvertCartLimit(t *testing.T) {
+	cases := []struct {
+		name          string
+		capCents      int
+		quantity      int
+		expectOverCap bool
+	}{
+		{"over cap rejects", 20000, 41, true},   // $205
+		{"at cap accepts", 20000, 40, false},    // $200 boundary
+		{"under cap accepts", 20000, 39, false}, // $195
+		{"zero cap disables", 0, 1000, false},   // explicit off-switch
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			testDB, user := setupCartTestDB(t)
+			defer func() { _ = os.Remove(testDB) }()
+			defer database.ResetForTesting()
+
+			db := database.GetDB()
+			user.StripeCustomerID = "cus_test_overlimit"
+			if err := db.Save(&user).Error; err != nil {
+				t.Fatalf("saved user: %v", err)
+			}
+
+			addr := models.Address{
+				UserID: user.ID, Name: "Test", Street: "1 Main St",
+				City: "PDX", State: "OR", Zip: "97201", Country: "US",
+			}
+			if err := db.Create(&addr).Error; err != nil {
+				t.Fatalf("seed address: %v", err)
+			}
+
+			card := models.Card{
+				UserID: user.ID, StripePaymentID: "pm_test_overlimit",
+				Last4: "4242", Brand: "Visa", ExpMonth: 12, ExpYear: 2030,
+			}
+			if err := db.Create(&card).Error; err != nil {
+				t.Fatalf("seed card: %v", err)
+			}
+
+			handler := NewCartHandler("", "", tc.capCents)
+
+			body, _ := json.Marshal(map[string]interface{}{"coffee_id": 4, "quantity": tc.quantity})
+			req := authRequest("PUT", "/api/v1/cart/item", body, user.ID)
+			w := httptest.NewRecorder()
+			handler.SetItem(w, req)
+			if w.Code != http.StatusOK {
+				t.Fatalf("SetItem: %d %s", w.Code, w.Body.String())
+			}
+
+			// set address
+			body, _ = json.Marshal(map[string]interface{}{"address_id": addr.ID})
+			req = authRequest("PUT", "/api/v1/cart/address", body, user.ID)
+			w = httptest.NewRecorder()
+			handler.SetAddress(w, req)
+			if w.Code != http.StatusOK {
+				t.Fatalf("SetAddress: %d %s", w.Code, w.Body.String())
+			}
+
+			// set card
+			body, _ = json.Marshal(map[string]interface{}{"card_id": card.ID})
+			req = authRequest("PUT", "/api/v1/cart/card", body, user.ID)
+			w = httptest.NewRecorder()
+			handler.SetCard(w, req)
+			if w.Code != http.StatusOK {
+				t.Fatalf("SetCard: %d %s", w.Code, w.Body.String())
+			}
+
+			// Convert
+			req = authRequest("POST", "/api/v1/cart/convert", nil, user.ID)
+			w = httptest.NewRecorder()
+			handler.ConvertCart(w, req)
+
+			var resp struct {
+				Success bool `json:"success"`
+				Error   struct {
+					Code    string                 `json:"code"`
+					Message string                 `json:"message"`
+					Details map[string]interface{} `json:"details"`
+				} `json:"error"`
+			}
+			_ = json.NewDecoder(w.Body).Decode(&resp)
+
+			isOverCap := w.Code == http.StatusBadRequest && resp.Error.Code == "CART_OVER_LIMIT"
+			if isOverCap != tc.expectOverCap {
+				t.Fatalf("expectOverCap=%v got code=%d errCode=%q msg=%q", tc.expectOverCap, w.Code, resp.Error.Code, resp.Error.Message)
+			}
+			if tc.expectOverCap {
+				if got, _ := resp.Error.Details["limit_cents"].(float64); int(got) != tc.capCents {
+					t.Errorf("limit_cents in details: want %d, got %v", tc.capCents, resp.Error.Details["limit_cents"])
+				}
+				if got, _ := resp.Error.Details["total_cents"].(float64); int(got) != tc.quantity*500 {
+					t.Errorf("total_cents in details: want %d, got %v", tc.quantity*500, resp.Error.Details["total_cents"])
+				}
+			}
+		})
+	}
+}

api/handlers/orders.go

@@ -2,9 +2,12 @@ package handlers
 
 import (
 	"encoding/json"
+	"fmt"
+	"log/slog"
 	"net/http"
 	"os"
 	"strconv"
+	"strings"
 	"time"
 
 	"terminalShop/pkg/bring"
@@ -31,6 +34,16 @@ type OrderHandler struct {
 	bringCustomerNumber string
 }
 
+type refundRequestPayload struct {
+	Reason  string `json:"reason"`
+	Message string `json:"message"`
+}
+
+// refundRequestCooldown is the minimum interval between customer-initiated
+// refund requests for the same order. Prevents accidental double-clicks and
+// repeated submissions from spamming the operator's Slack channel.
+const refundRequestCooldown = 15 * time.Minute
+
 func NewOrderHandler(stripeSecretKey, bringAPIUID, bringAPIKey, bringCustomerNumber string) *OrderHandler {
 	return &OrderHandler{
 		stripeKey:           stripeSecretKey,
@@ -40,6 +53,83 @@ func NewOrderHandler(stripeSecretKey, bringAPIUID, bringAPIKey, bringCustomerNum
 	}
 }
 
+// CreateRefundRequest posts a customer refund request into the order's Slack
+// thread. It does not issue a Stripe refund.
+func (h *OrderHandler) CreateRefundRequest(w http.ResponseWriter, r *http.Request) {
+	db := database.GetDB().WithContext(r.Context())
+	userID := middleware.UserIDFromContext(r.Context())
+
+	idStr := chi.URLParam(r, "id")
+	id, err := strconv.ParseUint(idStr, 10, 32)
+	if err != nil {
+		utils.RespondError(w, http.StatusBadRequest, "INVALID_ID", "invalid order id", nil)
+		return
+	}
+
+	var req refundRequestPayload
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		utils.RespondError(w, http.StatusBadRequest, "INVALID_JSON", "invalid request body", nil)
+		return
+	}
+
+	req.Reason = strings.TrimSpace(req.Reason)
+	req.Message = strings.TrimSpace(req.Message)
+
+	if !models.IsValidRefundReason(req.Reason) {
+		utils.RespondError(w, http.StatusBadRequest, "INVALID_REASON", "invalid refund reason", nil)
+		return
+	}
+	if req.Reason == models.RefundRequestReasonOther && req.Message == "" {
+		utils.RespondError(w, http.StatusBadRequest, "MESSAGE_REQUIRED", "message is required when reason is other", nil)
+		return
+	}
+
+	var order models.Order
+	if err := db.Preload("User").Where("id = ? AND user_id = ?", id, userID).First(&order).Error; err != nil {
+		utils.RespondError(w, http.StatusNotFound, "ORDER_NOT_FOUND", "order not found", nil)
+		return
+	}
+	if !order.CanRequestRefund() {
+		utils.RespondError(w, http.StatusBadRequest, "INVALID_STATE",
+			"only paid, shipped, or delivered orders can request refunds", nil)
+		return
+	}
+
+	if order.LastRefundRequestAt != nil {
+		elapsed := time.Since(*order.LastRefundRequestAt)
+		if elapsed < refundRequestCooldown {
+			retryAfter := int((refundRequestCooldown - elapsed).Seconds()) + 1
+			w.Header().Set("Retry-After", strconv.Itoa(retryAfter))
+			utils.RespondError(w, http.StatusTooManyRequests, "RATE_LIMITED",
+				fmt.Sprintf("another refund request was submitted recently; try again in %d min", retryAfter/60+1),
+				nil)
+			return
+		}
+	}
+
+	text := fmt.Sprintf(":money_with_wings: *Refund request* — %s\n*From:* %s <%s>\n*Total:* $%.2f",
+		req.Reason, order.User.Name, order.User.Email, order.TotalInDollars())
+	if req.Message != "" {
+		quoted := "> " + strings.ReplaceAll(req.Message, "\n", "\n> ")
+		text += "\n\n" + quoted
+	}
+
+	if err := notify.SlackPostToOrderThreadBroadcast(order.ID, text); err != nil {
+		utils.RespondError(w, http.StatusBadGateway, "SLACK_ERROR", "failed to send refund request", nil)
+		return
+	}
+
+	// Record the timestamp after a successful Slack post so a Slack outage
+	// doesn't consume the user's cooldown — they can retry immediately.
+	if err := db.Model(&order).Update("last_refund_request_at", time.Now()).Error; err != nil {
+		slog.Warn("refund request: failed to record timestamp", "order_id", order.ID, "error", err)
+	}
+
+	utils.RespondSuccess(w, http.StatusOK, map[string]any{
+		"status": "sent",
+	})
+}
+
 func (h *OrderHandler) GetOrders(w http.ResponseWriter, r *http.Request) {
 	db := database.GetDB().WithContext(r.Context())
 	userID := middleware.UserIDFromContext(r.Context())
@@ -50,11 +140,34 @@ func (h *OrderHandler) GetOrders(w http.ResponseWriter, r *http.Request) {
 		Preload("Events", func(tx *gorm.DB) *gorm.DB { return tx.Order("created_at ASC") }).
 		Order("created_at desc").Find(&orders)
 
-	utils.RespondSuccess(w, http.StatusOK, map[string]interface{}{
+	utils.RespondSuccess(w, http.StatusOK, map[string]any{
 		"orders": orders,
 	})
 }
 
+func (h *OrderHandler) GetOrderStatus(w http.ResponseWriter, r *http.Request) {
+	db := database.GetDB().WithContext(r.Context())
+	userID := middleware.UserIDFromContext(r.Context())
+
+	idStr := chi.URLParam(r, "id")
+	id, err := strconv.ParseUint(idStr, 10, 32)
+	if err != nil {
+		utils.RespondError(w, http.StatusBadRequest, "INVALID_ID", "invalid order id", nil)
+		return
+	}
+
+	var order models.Order
+	if err := db.Where("id = ? AND user_id = ?", id, userID).First(&order).Error; err != nil {
+		utils.RespondError(w, http.StatusNotFound, "ORDER_NOT_FOUND", "order not found", nil)
+		return
+	}
+
+	utils.RespondSuccess(w, http.StatusOK, map[string]any{
+		"id":     order.ID,
+		"status": string(order.Status),
+	})
+}
+
 // RefundOrder issues a full refund for an order via Stripe and marks it as
 // refunded. Only orders in paid or shipped status can be refunded.
 func (h *OrderHandler) RefundOrder(w http.ResponseWriter, r *http.Request) {

api/handlers/orders_test.go

@@ -0,0 +1,170 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"terminalShop/pkg/database"
+	"terminalShop/pkg/models"
+)
+
+func setupOrderTestDB(t *testing.T) models.User {
+	t.Helper()
+	testDB := filepath.Join(t.TempDir(), "orders.db")
+	database.ResetForTesting()
+	t.Cleanup(database.ResetForTesting)
+
+	db, err := database.Connect(testDB)
+	if err != nil {
+		t.Fatalf("failed to connect to test database: %v", err)
+	}
+	if err := database.Migrate(db); err != nil {
+		t.Fatalf("failed to migrate: %v", err)
+	}
+	if err := database.Seed(db); err != nil {
+		t.Fatalf("failed to seed: %v", err)
+	}
+
+	user := models.User{
+		SSHKeyFingerprint: "SHA256:ordertestfingerprint",
+		SSHPublicKey:      "ssh-ed25519 AAAA ordertestkey",
+		Name:              "Order Test User",
+		Email:             "orders@example.com",
+	}
+	if err := db.Create(&user).Error; err != nil {
+		t.Fatalf("failed to create test user: %v", err)
+	}
+
+	return user
+}
+
+func orderRequest(method, url string, body []byte, userID uint, orderID string) *http.Request {
+	req := authRequest(method, url, body, userID)
+	routeCtx := chi.NewRouteContext()
+	routeCtx.URLParams.Add("id", orderID)
+	return req.WithContext(contextWithRoute(req.Context(), routeCtx))
+}
+
+func contextWithRoute(ctx context.Context, routeCtx *chi.Context) context.Context {
+	return context.WithValue(ctx, chi.RouteCtxKey, routeCtx)
+}
+
+func TestCreateRefundRequestRequiresMessageForOther(t *testing.T) {
+	user := setupOrderTestDB(t)
+
+	handler := NewOrderHandler("", "", "", "")
+	body := []byte(`{"reason":"Other","message":"   "}`)
+	req := orderRequest("POST", "/api/v1/orders/1/refund-request", body, user.ID, "1")
+	w := httptest.NewRecorder()
+
+	handler.CreateRefundRequest(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected status 400, got %d", w.Code)
+	}
+
+	var resp struct {
+		Error struct {
+			Code string `json:"code"`
+		} `json:"error"`
+	}
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+	if resp.Error.Code != "MESSAGE_REQUIRED" {
+		t.Errorf("expected MESSAGE_REQUIRED, got %q", resp.Error.Code)
+	}
+}
+
+func TestCreateRefundRequestRejectsInvalidOrderState(t *testing.T) {
+	user := setupOrderTestDB(t)
+
+	db := database.GetDB()
+	order := models.Order{
+		UserID:       user.ID,
+		CardID:       1,
+		Status:       models.OrderStatusFailed,
+		Subtotal:     100,
+		ShippingCost: 0,
+		Total:        100,
+	}
+	if err := db.Create(&order).Error; err != nil {
+		t.Fatalf("failed to create order: %v", err)
+	}
+
+	handler := NewOrderHandler("", "", "", "")
+	body := []byte(`{"reason":"Quality issue","message":""}`)
+	req := orderRequest("POST", "/api/v1/orders/1/refund-request", body, user.ID, fmt.Sprintf("%d", order.ID))
+	w := httptest.NewRecorder()
+
+	handler.CreateRefundRequest(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected status 400, got %d", w.Code)
+	}
+
+	var resp struct {
+		Error struct {
+			Code string `json:"code"`
+		} `json:"error"`
+	}
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+	if resp.Error.Code != "INVALID_STATE" {
+		t.Errorf("expected INVALID_STATE, got %q", resp.Error.Code)
+	}
+}
+
+func TestCreateRefundRequestEnforcesCooldown(t *testing.T) {
+	user := setupOrderTestDB(t)
+
+	db := database.GetDB()
+	recent := time.Now().Add(-1 * time.Minute)
+	order := models.Order{
+		UserID:              user.ID,
+		CardID:              1,
+		Status:              models.OrderStatusPaid,
+		Subtotal:            100,
+		ShippingCost:        0,
+		Total:               100,
+		LastRefundRequestAt: &recent,
+	}
+	if err := db.Create(&order).Error; err != nil {
+		t.Fatalf("failed to create order: %v", err)
+	}
+
+	handler := NewOrderHandler("", "", "", "")
+	body := []byte(`{"reason":"Quality issue","message":""}`)
+	req := orderRequest("POST", "/api/v1/orders/1/refund-request", body, user.ID, fmt.Sprintf("%d", order.ID))
+	w := httptest.NewRecorder()
+
+	handler.CreateRefundRequest(w, req)
+
+	if w.Code != http.StatusTooManyRequests {
+		t.Fatalf("expected status 429, got %d", w.Code)
+	}
+	if got := w.Header().Get("Retry-After"); got == "" {
+		t.Errorf("expected Retry-After header, got empty")
+	}
+
+	var resp struct {
+		Error struct {
+			Code string `json:"code"`
+		} `json:"error"`
+	}
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+	if resp.Error.Code != "RATE_LIMITED" {
+		t.Errorf("expected RATE_LIMITED, got %q", resp.Error.Code)
+	}
+}

api/handlers/slack.go

@@ -130,7 +130,7 @@ func (h *SlackHandler) handleBuyLabel(orderIDStr string, p slackInteractivePaylo
 
 	resp, err := h.httpClient.Do(req)
 	if err != nil {
-		notify.SlackPostToOrderThread(orderID, fmt.Sprintf(":x: Label purchase failed: %v", err))
+		_ = notify.SlackPostToOrderThread(orderID, fmt.Sprintf(":x: Label purchase failed: %v", err))
 		return
 	}
 	defer func() { _ = resp.Body.Close() }()
@@ -151,7 +151,7 @@ func (h *SlackHandler) handleBuyLabel(orderIDStr string, p slackInteractivePaylo
 	_ = json.Unmarshal(bodyBytes, &result)
 
 	if resp.StatusCode >= 300 {
-		notify.SlackPostToOrderThread(orderID, fmt.Sprintf(":x: Label purchase failed: `%s` %s", result.Error.Code, result.Error.Message))
+		_ = notify.SlackPostToOrderThread(orderID, fmt.Sprintf(":x: Label purchase failed: `%s` %s", result.Error.Code, result.Error.Message))
 		return
 	}
 
@@ -173,7 +173,7 @@ func (h *SlackHandler) handleMarkStatus(orderIDStr string, p slackInteractivePay
 		return
 	}
 	if order.TrackingNumber == "" {
-		notify.SlackPostToOrderThread(orderID, ":x: Cannot mark status, the order has no tracking number yet.")
+		_ = notify.SlackPostToOrderThread(orderID, ":x: Cannot mark status, the order has no tracking number yet.")
 		return
 	}
 
@@ -198,12 +198,12 @@ func (h *SlackHandler) handleMarkStatus(orderIDStr string, p slackInteractivePay
 
 	resp, err := h.httpClient.Do(req)
 	if err != nil {
-		notify.SlackPostToOrderThread(orderID, fmt.Sprintf(":x: Mark %s failed: %v", status, err))
+		_ = notify.SlackPostToOrderThread(orderID, fmt.Sprintf(":x: Mark %s failed: %v", status, err))
 		return
 	}
 	defer func() { _ = resp.Body.Close() }()
 	if resp.StatusCode >= 300 {
-		notify.SlackPostToOrderThread(orderID, fmt.Sprintf(":x: Mark %s failed (HTTP %d)", status, resp.StatusCode))
+		_ = notify.SlackPostToOrderThread(orderID, fmt.Sprintf(":x: Mark %s failed (HTTP %d)", status, resp.StatusCode))
 		return
 	}
 

api/handlers/webhook.go

@@ -167,6 +167,16 @@ func (h *WebhookHandler) handlePaymentIntentFailed(ctx context.Context, event st
 		return
 	}
 
+	// authentication_required is recoverable — the cart handler re-confirms the
+	// PI on-session and the customer completes 3DS via redirect. Marking the
+	// order failed here would race with the recovery path and surface a
+	// momentarily-broken state in the TUI.
+	if pi.LastPaymentError != nil && string(pi.LastPaymentError.Code) == "authentication_required" {
+		webhookLog().Info("ignoring authentication_required payment_failed; handled via 3ds redirect",
+			"order_id", orderIDStr, "pi", pi.ID)
+		return
+	}
+
 	db := database.GetDB().WithContext(ctx)
 	if err := db.Model(&models.Order{}).Where("id = ? AND status = ?", orderIDStr, models.OrderStatusPending).
 		Update("status", models.OrderStatusFailed).Error; err != nil {
@@ -373,7 +383,9 @@ func (h *WebhookHandler) HandleShippo(w http.ResponseWriter, r *http.Request) {
 
 	if previousTrackingStatus != newStatus {
 		audit.TrackingUpdated(order.ID, order.Carrier, payload.Data.TrackingNumber, string(newStatus))
-		go notify.SlackPostToOrderThread(order.ID, formatTrackingUpdate(newStatus, payload.Data.TrackingStatus.StatusDetails))
+		go func() {
+			_ = notify.SlackPostToOrderThread(order.ID, formatTrackingUpdate(newStatus, payload.Data.TrackingStatus.StatusDetails))
+		}()
 	}
 	if deliveredTransition {
 		audit.OrderDelivered(order.ID, payload.Data.TrackingNumber)

api/main.go

@@ -71,7 +71,7 @@ func main() {
 	jwtManager := auth.NewJWTManager(cfg.JWTSecret, 30*time.Minute)
 
 	// Setup routes
-	router := routes.SetupRoutes(version, cfg.StripeSecretKey, cfg.StripeWebhookSecret, jwtManager, cfg.AuthFingerprintKey, cfg.ShippoAPIKey, cfg.BringAPIUID, cfg.BringAPIKey, cfg.BringCustomerNumber, cfg.ShippoWebhookSecret, cfg.AppURL, cfg.SlackSigningSecret, cfg.AdminAPIKey, cfg.APIPort)
+	router := routes.SetupRoutes(version, cfg.StripeSecretKey, cfg.StripeWebhookSecret, jwtManager, cfg.AuthFingerprintKey, cfg.ShippoAPIKey, cfg.BringAPIUID, cfg.BringAPIKey, cfg.BringCustomerNumber, cfg.ShippoWebhookSecret, cfg.AppURL, cfg.SlackSigningSecret, cfg.AdminAPIKey, cfg.APIPort, cfg.MaxOrderCents)
 
 	// Create HTTP server
 	server := &http.Server{

api/routes/routes.go

@@ -29,6 +29,7 @@ func SetupRoutes(
 	slackSigningSecret string,
 	adminAPIKey string,
 	apiPort string,
+	maxOrderCents int,
 ) *chi.Mux {
 	r := chi.NewRouter()
 
@@ -46,7 +47,7 @@ func SetupRoutes(
 	healthHandler := handlers.NewHealthHandler(version)
 	productHandler := handlers.NewProductHandler()
 	authHandler := handlers.NewAuthHandler(jwtManager, authFingerprintKey)
-	cartHandler := handlers.NewCartHandler(stripeSecretKey)
+	cartHandler := handlers.NewCartHandler(stripeSecretKey, appURL, maxOrderCents)
 	cardHandler := handlers.NewCardHandler(stripeSecretKey, appURL)
 	orderHandler := handlers.NewOrderHandler(stripeSecretKey, bringAPIUID, bringAPIKey, bringCustomerNumber)
 	addressHandler := handlers.NewAddressHandler(shippoAPIKey, bringAPIUID, bringAPIKey)
@@ -61,6 +62,10 @@ func SetupRoutes(
 		w.Header().Set("Content-Type", "text/html")
 		_, _ = w.Write([]byte(`<!DOCTYPE html><html><body style="font-family:monospace;text-align:center;padding:4rem"><h2>Card added.</h2><p>You can close this tab.</p></body></html>`))
 	})
+	r.Get("/post-3ds", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		_, _ = w.Write([]byte(`<!DOCTYPE html><html><body style="font-family:monospace;text-align:center;padding:4rem"><h2>Authentication complete.</h2><p>Return to your terminal.</p></body></html>`))
+	})
 	r.Handle("/metrics", middleware.MetricsHandler())
 
 	r.Route("/api/v1", func(r chi.Router) {
@@ -126,6 +131,8 @@ func SetupRoutes(
 
 			// Orders
 			r.Get("/orders", orderHandler.GetOrders)
+			r.Get("/orders/{id}/status", orderHandler.GetOrderStatus)
+			r.Post("/orders/{id}/refund-request", orderHandler.CreateRefundRequest)
 			r.Post("/orders/{id}/refund", orderHandler.RefundOrder)
 
 			// Addresses

pkg/api/client.go

@@ -56,7 +56,6 @@ type TokenResponse struct {
 }
 
 func (c *Client) GetOrCreateToken(fingerprint, pubKeyStr, clientSecret string) (string, models.PublicUser, error) {
-
 	url := fmt.Sprintf("%s/api/v1/auth/token", c.BaseURL)
 
 	reqBody := TokenRequest{
@@ -281,14 +280,31 @@ type CardResponse struct {
 }
 
 // ConvertCartResponse represents the cart conversion (checkout) API response.
+// 200 carries Order populated; 202 (requires_action / 3DS) carries the
+// redirect fields and OrderID instead.
 type ConvertCartResponse struct {
 	Success bool `json:"success"`
 	Data    struct {
-		Order models.Order `json:"order"`
+		Order           *models.Order `json:"order,omitempty"`
+		OrderID         uint          `json:"order_id,omitempty"`
+		PaymentIntentID string        `json:"payment_intent_id,omitempty"`
+		Status          string        `json:"status,omitempty"`
+		RedirectToken   string        `json:"redirect_token,omitempty"`
+		RedirectURL     string        `json:"redirect_url,omitempty"`
 	} `json:"data"`
 	Error *APIError `json:"error,omitempty"`
 }
 
+// CheckoutOutcome is the unified result of ConvertCart. RequiresAction=true
+// means the customer needs to complete 3DS at RedirectURL; poll
+// GetOrderStatus(OrderID) until the webhook flips the order to paid or failed.
+type CheckoutOutcome struct {
+	Order          *models.Order
+	OrderID        uint
+	RequiresAction bool
+	RedirectURL    string
+}
+
 // GetCart fetches the user's current cart.
 func (c *Client) GetCart() (*CartData, error) {
 	url := fmt.Sprintf("%s/api/v1/cart", c.BaseURL)
@@ -468,7 +484,9 @@ func (c *Client) ClearCart() error {
 }
 
 // ConvertCart converts the cart into an order, charging the saved card.
-func (c *Client) ConvertCart() (*models.Order, error) {
+// Returns a CheckoutOutcome that either carries the completed Order or
+// indicates the customer must complete 3DS authentication via RedirectURL.
+func (c *Client) ConvertCart() (*CheckoutOutcome, error) {
 	url := fmt.Sprintf("%s/api/v1/cart/convert", c.BaseURL)
 
 	req, err := http.NewRequest("POST", url, nil)
@@ -494,7 +512,55 @@ func (c *Client) ConvertCart() (*models.Order, error) {
 		return nil, fmt.Errorf("failed to convert cart")
 	}
 
-	return &convertResp.Data.Order, nil
+	if convertResp.Data.Status == "requires_action" {
+		return &CheckoutOutcome{
+			OrderID:        convertResp.Data.OrderID,
+			RequiresAction: true,
+			RedirectURL:    convertResp.Data.RedirectURL,
+		}, nil
+	}
+
+	if convertResp.Data.Order == nil {
+		return nil, fmt.Errorf("malformed convert response: missing order")
+	}
+	return &CheckoutOutcome{
+		Order:   convertResp.Data.Order,
+		OrderID: convertResp.Data.Order.ID,
+	}, nil
+}
+
+type OrderStatusResponse struct {
+	Success bool `json:"success"`
+	Data    struct {
+		ID     uint   `json:"id"`
+		Status string `json:"status"`
+	} `json:"data"`
+	Error *APIError `json:"error,omitempty"`
+}
+
+func (c *Client) GetOrderStatus(id uint) (string, error) {
+	url := fmt.Sprintf("%s/api/v1/orders/%d/status", c.BaseURL, id)
+	req, err := http.NewRequest("GET", url, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+	resp, err := c.doRequest(req)
+	if err != nil {
+		return "", fmt.Errorf("failed to fetch order status: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	var sResp OrderStatusResponse
+	if err := json.NewDecoder(resp.Body).Decode(&sResp); err != nil {
+		return "", fmt.Errorf("failed to decode order status response: %w", err)
+	}
+	if !sResp.Success {
+		if sResp.Error != nil {
+			return "", fmt.Errorf("%s: %s", sResp.Error.Code, sResp.Error.Message)
+		}
+		return "", fmt.Errorf("failed to fetch order status")
+	}
+	return sResp.Data.Status, nil
 }
 
 // GetCards fetches all saved cards for the user.
@@ -636,6 +702,20 @@ type OrderResponse struct {
 	Error *APIError `json:"error,omitempty"`
 }
 
+// RefundRequest is the customer-facing refund request payload.
+type RefundRequest struct {
+	Reason  string `json:"reason"`
+	Message string `json:"message"`
+}
+
+type refundRequestResponse struct {
+	Success bool `json:"success"`
+	Data    struct {
+		Status string `json:"status"`
+	} `json:"data"`
+	Error *APIError `json:"error,omitempty"`
+}
+
 func (c *Client) GetOrders() ([]models.Order, error) {
 	url := fmt.Sprintf("%s/api/v1/orders", c.BaseURL)
 
@@ -664,6 +744,42 @@ func (c *Client) GetOrders() ([]models.Order, error) {
 	return ordersResp.Data.Orders, nil
 }
 
+// CreateRefundRequest posts a refund request for an order.
+func (c *Client) CreateRefundRequest(orderID uint, params RefundRequest) error {
+	url := fmt.Sprintf("%s/api/v1/orders/%d/refund-request", c.BaseURL, orderID)
+
+	jsonData, err := json.Marshal(params)
+	if err != nil {
+		return fmt.Errorf("failed to marshal refund request: %w", err)
+	}
+
+	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
+	if err != nil {
+		return fmt.Errorf("failed to create refund request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.doRequest(req)
+	if err != nil {
+		return fmt.Errorf("failed to send refund request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	var refundResp refundRequestResponse
+	if err := json.NewDecoder(resp.Body).Decode(&refundResp); err != nil {
+		return fmt.Errorf("failed to decode refund response: %w", err)
+	}
+
+	if !refundResp.Success {
+		if refundResp.Error != nil {
+			return fmt.Errorf("%s: %s", refundResp.Error.Code, refundResp.Error.Message)
+		}
+		return fmt.Errorf("failed to send refund request")
+	}
+
+	return nil
+}
+
 // The Addresses API response
 type AddressResponse struct {
 	Success bool `json:"success"`

pkg/audit/audit.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"log/slog"
+
 	"terminalShop/pkg/models"
 
 	"gorm.io/gorm"
@@ -21,6 +22,7 @@ const (
 	eventOrderPaid              eventType = "order_paid"
 	eventOrderShipped           eventType = "order_shipped"
 	eventOrderFailed            eventType = "order_failed"
+	eventOrderRequiresAction    eventType = "order_requires_action"
 	eventOrderRefunded          eventType = "order_refunded"
 	eventPaymentCritical        eventType = "payment_critical"
 	eventLabelPurchased         eventType = "label_purchased"
@@ -298,3 +300,15 @@ func attrsToMap(a []any) map[string]any {
 	}
 	return m
 }
+
+//nolint:unused // called from ConvertCart in the next update
+func OrderRequiresAction(userID, orderID uint, paymentIntentID string) {
+	e := event{
+		Event:    eventOrderRequiresAction,
+		UserID:   userID,
+		OrderID:  orderID,
+		StripeID: paymentIntentID,
+	}
+	slog.Info("audit", e.attrs()...)
+	persist(orderID, eventOrderRequiresAction, e)
+}

pkg/config/config.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"net/url"
 	"os"
+	"strconv"
 	"strings"
 
 	"github.com/joho/godotenv"
@@ -30,6 +31,7 @@ type Config struct {
 	ShippoWebhookSecret string
 	SlackSigningSecret  string
 	AdminAPIKey         string
+	MaxOrderCents       int
 }
 
 // Load reads configuration from environment variables and validates required secrets.
@@ -66,6 +68,7 @@ func Load() (*Config, error) {
 		ShippoWebhookSecret: os.Getenv("SHIPPO_WEBHOOK_SECRET"),
 		SlackSigningSecret:  os.Getenv("SLACK_SIGNING_SECRET"),
 		AdminAPIKey:         os.Getenv("ADMIN_API_KEY"),
+		MaxOrderCents:       loadMaxOrderCents(),
 	}
 
 	if err := cfg.validate(); err != nil {
@@ -130,3 +133,20 @@ func getEnvOrDefault(key, defaultValue string) string {
 	}
 	return defaultValue
 }
+
+// loadMaxOrderCents reads MAX_ORDER_CENTS. Default $200. Explicit 0 disables
+// the cap. Garbage or negative values fall back to the default with a warning
+// so an operator typo cannot silently disable a fraud control.
+func loadMaxOrderCents() int {
+	const defaultCap = 20000
+	raw := os.Getenv("MAX_ORDER_CENTS")
+	if raw == "" {
+		return defaultCap
+	}
+	n, err := strconv.Atoi(raw)
+	if err != nil || n < 0 {
+		fmt.Printf("WARNING: MAX_ORDER_CENTS=%q invalid, falling back to default %d\n", raw, defaultCap)
+		return defaultCap
+	}
+	return n
+}

pkg/config/config_test.go

@@ -0,0 +1,34 @@
+package config
+
+import (
+	"testing"
+)
+
+func TestLoadMaxOrderCents(t *testing.T) {
+	cases := []struct {
+		name string
+		env  string // "" means unset
+		want int
+	}{
+		{"unset uses default", "", 20000},
+		{"explicit zero disables", "0", 0},
+		{"valid override", "50000", 50000},
+		{"negative falls back to default", "-1", 20000},
+		{"garbage falls back to default", "two hundred", 20000},
+		{"empty after trim falls back to default", "", 20000},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if tc.env == "" {
+				t.Setenv("MAX_ORDER_CENTS", "")
+			} else {
+				t.Setenv("MAX_ORDER_CENTS", tc.env)
+			}
+			got := loadMaxOrderCents()
+			if got != tc.want {
+				t.Errorf("loadMaxOrderCents() = %d, want %d", got, tc.want)
+			}
+		})
+	}
+}

pkg/database/migrate.go

@@ -3,6 +3,7 @@ package database
 import (
 	"fmt"
 	"log"
+
 	"terminalShop/pkg/models"
 
 	"gorm.io/gorm"
@@ -24,6 +25,7 @@ func Migrate(db *gorm.DB) error {
 		&models.OrderItem{}, // Line items within orders
 		&models.Address{},   // Saved addresses
 		&models.OrderEvent{},
+		&models.PayRedirect{}, // short-token -> stripe url store (10 min TTL)
 	); err != nil {
 		return fmt.Errorf("migration failed: %w", err)
 	}

pkg/models/order.go

@@ -66,6 +66,10 @@ type Order struct {
 	// Slack parent message ts for this order's thread (NULL if Slack notify disabled).
 	SlackThreadTS *string `gorm:"size:64" json:"-"`
 
+	// LastRefundRequestAt timestamps the most recent customer-initiated refund
+	// request for this order. Used to rate-limit repeat submissions.
+	LastRefundRequestAt *time.Time `json:"-"`
+
 	CreatedAt time.Time      `json:"created_at"`
 	UpdatedAt time.Time      `json:"updated_at"`
 	DeletedAt gorm.DeletedAt `gorm:"index" json:"-"` // GORM soft-delete sentinel
@@ -113,3 +117,35 @@ func (o *Order) TotalInDollars() float64 {
 func (o *Order) IsActive() bool {
 	return o.Status == OrderStatusPaid || o.Status == OrderStatusShipped
 }
+
+// RefundRequestReasons is the canonical list of customer-facing refund reasons
+// accepted by both the API and the TUI.
+var RefundRequestReasons = []string{
+	"Wrong item received",
+	"Item damaged in transit",
+	"Item never arrived",
+	"Quality issue",
+	"Other",
+}
+
+// RefundRequestReasonOther is the sentinel reason that requires a free-form message.
+const RefundRequestReasonOther = "Other"
+
+// IsValidRefundReason reports whether r is one of the accepted refund reasons.
+func IsValidRefundReason(r string) bool {
+	for _, reason := range RefundRequestReasons {
+		if reason == r {
+			return true
+		}
+	}
+	return false
+}
+
+// CanRequestRefund reports whether a customer is allowed to request a refund
+// for this order. Paid, shipped, and delivered orders qualify; everything else
+// is either still unpaid or already in a terminal state.
+func (o *Order) CanRequestRefund() bool {
+	return o.Status == OrderStatusPaid ||
+		o.Status == OrderStatusShipped ||
+		o.Status == OrderStatusDelivered
+}

pkg/models/order_display.go

@@ -11,10 +11,27 @@ const (
 	DisplayKindBrand   DisplayKind = "brand"   // shipped / in transit
 	DisplayKindSuccess DisplayKind = "success" // delivered
 	DisplayKindError   DisplayKind = "error"   // cancelled, failed, refunded
-	DisplayKindWarning DisplayKind = "warning" // refund pending, delivery issue
+	DisplayKindWarning DisplayKind = "warning" // delivery issue, returned
+	DisplayKindRefund  DisplayKind = "refund"  // refund requested, awaiting review
 )
 
+// refundPending reports whether the order has an open customer refund request
+// that has not yet been resolved by a terminal status change.
+func (order *Order) refundPending() bool {
+	if order.LastRefundRequestAt == nil {
+		return false
+	}
+	switch order.Status {
+	case OrderStatusRefunded, OrderStatusCancelled, OrderStatusFailed:
+		return false
+	}
+	return true
+}
+
 func (order *Order) DisplayState() string {
+	if order.refundPending() {
+		return "Refund Requested"
+	}
 	switch order.Status {
 	case OrderStatusPending:
 		return "Awaiting payment"
@@ -54,6 +71,9 @@ func (order *Order) DisplayState() string {
 }
 
 func (order *Order) DisplayKind() DisplayKind {
+	if order.refundPending() {
+		return DisplayKindRefund
+	}
 	switch order.Status {
 	case OrderStatusPending:
 		return DisplayKindNeutral

pkg/models/order_display_test.go

@@ -1,8 +1,12 @@
 package models
 
-import "testing"
+import (
+	"testing"
+	"time"
+)
 
 func TestOrderDisplayState(t *testing.T) {
+	now := time.Now()
 	tests := []struct {
 		name  string
 		order Order
@@ -23,6 +27,10 @@ func TestOrderDisplayState(t *testing.T) {
 		{"cancelled", Order{Status: OrderStatusCancelled}, "Cancelled", DisplayKindError},
 		{"refunded", Order{Status: OrderStatusRefunded}, "Refunded", DisplayKindError},
 		{"failed", Order{Status: OrderStatusFailed}, "Payment failed", DisplayKindError},
+		{"paid with open refund request", Order{Status: OrderStatusPaid, LastRefundRequestAt: &now}, "Refund Requested", DisplayKindRefund},
+		{"delivered with open refund request", Order{Status: OrderStatusDelivered, LastRefundRequestAt: &now}, "Refund Requested", DisplayKindRefund},
+		{"refunded order ignores prior request", Order{Status: OrderStatusRefunded, LastRefundRequestAt: &now}, "Refunded", DisplayKindError},
+		{"cancelled order ignores prior request", Order{Status: OrderStatusCancelled, LastRefundRequestAt: &now}, "Cancelled", DisplayKindError},
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {

pkg/models/pay_redirect.go

@@ -0,0 +1,23 @@
+package models
+
+import "time"
+
+// PayRedirect maps a short token to a stripe hosted url with a TTL.
+// survives api restarts so a customer mid-3Ds authentication still
+// lands on the bank-hosted challenge page after a deploy or crash
+type PayRedirect struct {
+	Token     string    `gorm:"primaryKey;size:64" json:"token"`
+	URL       string    `gorm:"type:text;not null" json:"url"`
+	Purpose   string    `gorm:"size:32;not null" json:"purpose"`
+	CreatedAt time.Time `json:"created_at"`
+	ExpiresAt time.Time `gorm:"index" json:"expires_at"`
+}
+
+const (
+	RedirectPurposeCheckout3DS = "checkout_3ds"
+	RedirectPurposeAddCard     = "add_card"
+)
+
+func (PayRedirect) TableName() string {
+	return "pay_redirects"
+}

pkg/notify/slack.go

@@ -188,29 +188,49 @@ func SlackUnpinOrder(orderID uint) {
 }
 
 // SlackPostToOrderThread posts a plain-text reply inside the order's thread.
-// Looks up the thread ts from the database. Silent no-op if the order has no
-// saved thread (Slack was disabled when it was created, or post failed earlier).
-func SlackPostToOrderThread(orderID uint, text string) {
+// It looks up the thread ts from the database and returns an error when the
+// reply cannot be posted.
+func SlackPostToOrderThread(orderID uint, text string) error {
+	return slackPostToOrderThread(orderID, text, false)
+}
+
+// SlackPostToOrderThreadBroadcast posts a thread reply that is also surfaced
+// to the channel (reply_broadcast=true) so channel members get a normal
+// notification. Use for messages that need immediate operator attention.
+func SlackPostToOrderThreadBroadcast(orderID uint, text string) error {
+	return slackPostToOrderThread(orderID, text, true)
+}
+
+func slackPostToOrderThread(orderID uint, text string, broadcast bool) error {
 	token := os.Getenv("SLACK_BOT_TOKEN")
 	channel := os.Getenv("SLACK_CHANNEL")
 	if token == "" || channel == "" {
-		return
+		return fmt.Errorf("slack is not configured")
 	}
 
 	var order models.Order
 	if err := database.GetDB().Select("id", "slack_thread_ts").Where("id = ?", orderID).First(&order).Error; err != nil {
 		slog.Warn("failed to look up order for thread post", "order_id", orderID, "error", err)
-		return
+		return fmt.Errorf("failed to look up order thread: %w", err)
 	}
 	if order.SlackThreadTS == nil || *order.SlackThreadTS == "" {
-		return
+		return fmt.Errorf("order has no slack thread")
 	}
 
-	_, _ = postSlackMessage(token, map[string]any{
+	payload := map[string]any{
 		"channel":   channel,
 		"thread_ts": *order.SlackThreadTS,
 		"text":      text,
-	})
+	}
+	if broadcast {
+		payload["reply_broadcast"] = true
+	}
+
+	if _, ok := postSlackMessage(token, payload); !ok {
+		slog.Warn("failed to post slack thread reply", "order_id", orderID)
+		return fmt.Errorf("failed to post slack thread reply")
+	}
+	return nil
 }
 
 func SlackPostLabelPurchased(orderID uint, labelURL string, costCents int) {

pkg/tui/account.go

@@ -288,6 +288,13 @@ func (m Model) AccountUpdate(msg tea.Msg) (Model, tea.Cmd) {
 		m.account.detailViewport, cmd = m.account.detailViewport.Update(msg)
 		return m, cmd
 
+	case "r":
+		if m.account.orderViewState == 2 {
+			if order, ok := m.selectedRefundableOrder(); ok {
+				return m.OpenRefundComposer(order.ID)
+			}
+		}
+
 	case "x", "d":
 		if m.account.addressListFocused && m.account.addressDeleting == nil && m.account.addressCursor < len(m.SavedAddresses) {
 			m.account.addressDeleting = &m.account.addressCursor
@@ -339,11 +346,15 @@ func (m Model) AccountUpdate(msg tea.Msg) (Model, tea.Cmd) {
 					m.account.orderYOffset = m.account.detailViewport.YOffset()
 					m.account.orderViewState = 2
 					m.account.detailViewport.GotoTop()
-					m.footer = []footerCommand{
+					footer := []footerCommand{
 						{key: "esc", value: "back"},
 						{key: "s", value: "shop"},
 						{key: "q", value: "quit"},
 					}
+					if _, ok := m.selectedRefundableOrder(); ok {
+						footer = append([]footerCommand{{key: "r", value: "refund"}}, footer...)
+					}
+					m.footer = footer
 				}
 			}
 		case "addresses":

pkg/tui/account_orders.go

@@ -37,6 +37,21 @@ func (m Model) HistoryOrders() []models.Order {
 	return out
 }
 
+// selectedRefundableOrder returns the order under the cursor in the active
+// order-detail view, paired with ok=true, when the user is allowed to file a
+// refund request for it. Returns (zero, false) otherwise.
+func (m Model) selectedRefundableOrder() (models.Order, bool) {
+	orders := m.currentOrderList()
+	if m.account.orderCursor < 0 || m.account.orderCursor >= len(orders) {
+		return models.Order{}, false
+	}
+	order := orders[m.account.orderCursor]
+	if !order.CanRequestRefund() {
+		return models.Order{}, false
+	}
+	return order, true
+}
+
 func (m Model) currentOrderList() []models.Order {
 	if m.account.cursor < 0 || m.account.cursor >= len(models.AccountMenuItems) {
 		return nil
@@ -241,7 +256,11 @@ func (m Model) buildOrderDetailView(order models.Order, _ int) string {
 	b.WriteString("\n\n")
 
 	// Footer hint
-	b.WriteString(dimStyle.Render("esc: back to orders"))
+	if order.CanRequestRefund() {
+		b.WriteString(dimStyle.Render("r: refund  esc: back to orders"))
+	} else {
+		b.WriteString(dimStyle.Render("esc: back to orders"))
+	}
 
 	return b.String()
 }
@@ -259,10 +278,9 @@ func (m Model) displayStyle(k models.DisplayKind) lipgloss.Style {
 	case models.DisplayKindError:
 		return m.theme.TextError()
 	case models.DisplayKindWarning:
-		// !TODO add refunds and change this
-		// No warning color in theme yet, reuse loading pink as visual flag
-		// for now
 		return m.theme.TextLoading()
+	case models.DisplayKindRefund:
+		return m.theme.TextBrand()
 	}
 	return m.theme.TextHighlight()
 }

pkg/tui/confirmation.go

@@ -3,7 +3,9 @@ package tui
 import (
 	"fmt"
 	"strings"
+
 	"terminalShop/pkg/models"
+	"terminalShop/pkg/tui/qrfefe"
 
 	"charm.land/bubbles/v2/viewport"
 	tea "charm.land/bubbletea/v2"
@@ -168,6 +170,18 @@ func (m Model) ReviewView() string {
 	if m.CheckingOut {
 		return m.theme.TextAccent().Bold(true).Padding(1).Render("  submitting order...")
 	}
+	if m.review.authFailed {
+		content := m.theme.TextError().Bold(true).Padding(1).Render("authentication failed — press esc to try again")
+		return lipgloss.Place(
+			m.widthContainer,
+			lipgloss.Height(content),
+			lipgloss.Center, lipgloss.Center,
+			content,
+		)
+	}
+	if m.review.requiresAction {
+		return m.renderRequiresActionView()
+	}
 	if m.review.success {
 		content := m.theme.TextSuccess().Bold(true).Padding(1).Render("order placed successfully!")
 		return lipgloss.Place(
@@ -186,18 +200,52 @@ func (m Model) ReviewView() string {
 	)
 }
 
+// renderRequiresActionView shows a QR for the 3DS challenge URL while the TUI
+// polls the order status. Mirrors the add-card QR layout in payment_form.go.
+func (m Model) renderRequiresActionView() string {
+	base := m.theme.TextLabel()
+	accent := m.theme.TextHighlight()
+	header := m.theme.TextAccent().Bold(true).Render("your bank wants to verify this charge")
+
+	if m.review.redirectURL == "" {
+		return base.Render("  waiting for authentication link...")
+	}
+
+	qr, qrSize, err := qrfefe.Generate(m.review.redirectURL)
+	if err != nil || qrSize > m.widthContent {
+		body := header + "\n\n" +
+			base.Render("open this url on your phone to authenticate:") + "\n\n" +
+			accent.Render(m.review.redirectURL) + "\n\n" +
+			base.Render("waiting for completion...")
+		return lipgloss.Place(m.widthContainer, lipgloss.Height(body), lipgloss.Center, lipgloss.Center, body)
+	}
+
+	// Same gotcha as payment_form.go: lipgloss layout helpers corrupt qrfefe ANSI.
+	return qr +
+		header + "\n" +
+		base.Render("scan or visit to complete authentication") + "\n" +
+		accent.Render(m.review.redirectURL) + "\n\n" +
+		base.Render("waiting for completion...")
+}
+
 func (m Model) ReviewUpdate(msg tea.Msg) (Model, tea.Cmd) {
 	switch msg := msg.(type) {
 	case CheckoutResultMsg:
 		m.CheckingOut = false
 		if msg.Err != nil {
 			m = m.SwitchPage(paymentPage)
-			m.error = &VisibleError{message: fmt.Sprintf("checkout failed: %v", msg.Err)}
+			m.error = &VisibleError{message: friendlyCheckoutError(msg.Err)}
 			m.review.cardJustAdded = false
 			m.payment.view = 0
 			m.payment.form = nil
 			return m, nil
 		}
+		if msg.RequiresAction {
+			m.review.requiresAction = true
+			m.review.redirectURL = msg.RedirectURL
+			m.review.orderID = msg.OrderID
+			return m, m.schedulePollOrderStatus(msg.OrderID)
+		}
 		m.Cart = make(map[uint]*models.CartItem)
 		m.cart.cursor = 0
 		m.ShippingInfo = nil
@@ -205,10 +253,57 @@ func (m Model) ReviewUpdate(msg tea.Msg) (Model, tea.Cmd) {
 		m.review.success = true
 		return m, nil
 
+	case OrderStatusMsg:
+		if !m.review.requiresAction || msg.OrderID != m.review.orderID {
+			return m, nil
+		}
+		if msg.Err != nil {
+			// Transient — keep polling.
+			return m, m.schedulePollOrderStatus(msg.OrderID)
+		}
+		switch msg.Status {
+		case "paid", "shipped", "delivered":
+			m.Cart = make(map[uint]*models.CartItem)
+			m.cart.cursor = 0
+			m.ShippingInfo = nil
+			m.OrdersLoaded = false
+			m.review.requiresAction = false
+			m.review.redirectURL = ""
+			m.review.success = true
+			return m, nil
+		case "failed", "cancelled":
+			m.review.requiresAction = false
+			m.review.redirectURL = ""
+			m.review.authFailed = true
+			return m, nil
+		default:
+			return m, m.schedulePollOrderStatus(msg.OrderID)
+		}
+
 	case tea.KeyMsg:
 		if m.CheckingOut {
 			return m, nil
 		}
+		if m.review.authFailed {
+			if msg.String() == "esc" || msg.String() == "enter" {
+				m.review.authFailed = false
+				m = m.SwitchPage(paymentPage)
+				m.payment.view = 0
+				m.payment.form = nil
+				return m, nil
+			}
+			return m, nil
+		}
+		if m.review.requiresAction {
+			if msg.String() == "esc" {
+				m.review.requiresAction = false
+				m.review.redirectURL = ""
+				m = m.SwitchPage(paymentPage)
+				m.payment.view = 0
+				return m, nil
+			}
+			return m, nil
+		}
 		if m.review.success {
 			m.review.success = false
 			m.review.cardJustAdded = false
@@ -234,3 +329,26 @@ func (m Model) ReviewUpdate(msg tea.Msg) (Model, tea.Cmd) {
 	}
 	return m, nil
 }
+
+func friendlyCheckoutError(raw error) string {
+	s := raw.Error()
+	switch {
+	case strings.Contains(s, "CART_OVER_LIMIT"):
+		return "order total is over the per-order limit. remove items and try again."
+	case strings.Contains(s, "AUTHENTICATION_REQUIRED"):
+		return "your bank wants to verify this charge, authentication step coming soon."
+	case strings.Contains(s, "AUTHENTICATION_NOT_SUPPORTED"):
+		return "this card doesn't support online authentication. Try another card"
+	case strings.Contains(s, "CARD_EXPIRED"):
+		return "card expired. Add a new card and try again"
+	case strings.Contains(s, "CARD_CVC_FAILED"):
+		return "card cvc incorrect. Check the back of the card and try again"
+	case strings.Contains(s, "CARD_INSUFFICIENT_FUNDS"):
+		return "insufficient funds on this card"
+	case strings.Contains(s, "CARD_PROCESSING_ERROR"):
+		return "card processing error. Try again in a moment"
+	case strings.Contains(s, "CARD_DECLINED"):
+		return "card declined"
+	}
+	return "checkout failed, try again."
+}

pkg/tui/model.go

@@ -64,6 +64,11 @@ type VisibleError struct {
 	message string
 }
 
+// VisibleNotice is a typed success message displayed to the user as a banner.
+type VisibleNotice struct {
+	message string
+}
+
 type Model struct {
 	// User authentication
 	User               *models.User
@@ -110,6 +115,7 @@ type Model struct {
 
 	Loading   bool // true when fetching data from API
 	error     *VisibleError
+	notice    *VisibleNotice
 	APIClient *api.Client
 
 	// Rendering
@@ -128,6 +134,7 @@ type Model struct {
 	shipping shippingState
 	payment  paymentState
 	account  accountState
+	refund   refundState
 	review   reviewState
 	confirm  confirmState
 
@@ -195,6 +202,15 @@ type reviewState struct {
 	cardJustAdded    bool
 	cardWasDuplicate bool
 	success          bool
+
+	// 3DS / SCA flow: when the backend returns 202 requires_action,
+	// requiresAction is true and redirectURL is the Stripe-hosted challenge
+	// page. The TUI shows a QR and polls GetOrderStatus(orderID) until the
+	// order flips to paid or failed.
+	requiresAction bool
+	redirectURL    string
+	orderID        uint
+	authFailed     bool
 }
 
 type confirmState struct {
@@ -217,6 +233,7 @@ func (m Model) SwitchPage(p page) Model {
 	m.currentPage = p
 	m.switched = true
 	m.error = nil
+	m.notice = nil
 	return m
 }
 
@@ -410,8 +427,18 @@ func (m Model) Init() tea.Cmd {
 }
 
 type CheckoutResultMsg struct {
+	OrderID        uint
+	Total          int
+	RequiresAction bool
+	RedirectURL    string
+	Err            error
+}
+
+// OrderStatusMsg carries the result of a poll against /orders/{id}/status.
+// Emitted on the 2s tick while waiting for 3DS authentication to complete.
+type OrderStatusMsg struct {
 	OrderID uint
-	Total   int
+	Status  string
 	Err     error
 }
 
@@ -623,15 +650,38 @@ func (m Model) checkoutWithSavedCard() tea.Cmd {
 		}
 
 		// 3. Convert the cart to an order
-		order, err := m.APIClient.ConvertCart()
+		outcome, err := m.APIClient.ConvertCart()
 		if err != nil {
 			return CheckoutResultMsg{Err: err}
 		}
 
-		return CheckoutResultMsg{OrderID: order.ID, Total: order.Total}
+		if outcome.RequiresAction {
+			return CheckoutResultMsg{
+				OrderID:        outcome.OrderID,
+				RequiresAction: true,
+				RedirectURL:    outcome.RedirectURL,
+			}
+		}
+
+		return CheckoutResultMsg{OrderID: outcome.Order.ID, Total: outcome.Order.Total}
 	}
 }
 
+// schedulePollOrderStatus sleeps 2s then polls /orders/{id}/status. Used while
+// waiting for the customer to complete 3DS authentication.
+func (m Model) schedulePollOrderStatus(orderID uint) tea.Cmd {
+	return tea.Tick(2*time.Second, func(time.Time) tea.Msg {
+		if m.APIClient == nil {
+			return OrderStatusMsg{OrderID: orderID, Err: fmt.Errorf("api client unavailable")}
+		}
+		status, err := m.APIClient.GetOrderStatus(orderID)
+		if err != nil {
+			return OrderStatusMsg{OrderID: orderID, Err: err}
+		}
+		return OrderStatusMsg{OrderID: orderID, Status: status}
+	})
+}
+
 func (m Model) syncCartItemCmd(coffeeID uint, quantity int) (Model, tea.Cmd) {
 	if m.APIClient == nil || m.User == nil {
 		return m, nil

pkg/tui/refund.go

@@ -0,0 +1,395 @@
+package tui
+
+import (
+	"fmt"
+	"strings"
+
+	"charm.land/bubbles/v2/textarea"
+	tea "charm.land/bubbletea/v2"
+	"charm.land/huh/v2"
+	"charm.land/lipgloss/v2"
+
+	"terminalShop/pkg/api"
+	"terminalShop/pkg/models"
+)
+
+// Refund composer layout constants.
+const (
+	refundMinTextareaRows = 5
+	refundMaxTextareaRows = 10
+	// chrome above the textarea inside the modal (title, label, padding, footer).
+	refundModalChrome   = 12
+	refundModalMaxWidth = 58
+	refundModalMinWidth = 24
+	// horizontal chrome the modal subtracts from m.widthContent.
+	refundModalHGutter = 6
+	// inner padding around the textarea inside the modal body.
+	refundTextareaHPad = 4
+)
+
+// Nerd-font glyphs used in the refund composer. Requires a Nerd Font in the
+// SSH client terminal; renders as tofu otherwise.
+const (
+	refundIconUndo    = "\uf0e2" // nf-fa-undo
+	refundIconTag     = "\uf02b" // nf-oct-tag
+	refundIconComment = "\uf41f" // nf-oct-comment
+	refundIconKey     = "\uf11c" // nf-fa-keyboard_o
+)
+
+// refundFocus identifies which field in the refund composer has keyboard focus.
+type refundFocus int
+
+const (
+	refundFocusReason refundFocus = iota
+	refundFocusMessage
+	refundFocusCount
+)
+
+type refundState struct {
+	open       bool
+	orderID    uint
+	gen        uint64 // bumped each open so late async results from a prior session are ignored
+	reason     string
+	form       *huh.Form
+	textarea   textarea.Model
+	focusIdx   refundFocus
+	submitting bool
+	err        string
+	reasonErr  string
+	messageErr string
+}
+
+type refundRequestMsg struct {
+	OrderID uint
+	Gen     uint64
+	Err     error
+}
+
+// OpenRefundComposer opens the refund request composer for an order.
+func (m Model) OpenRefundComposer(orderID uint) (Model, tea.Cmd) {
+	state := refundState{
+		open:    true,
+		orderID: orderID,
+		gen:     m.refund.gen + 1,
+	}
+	state.textarea = m.newRefundTextarea()
+	state.form = m.buildRefundForm(&state)
+	m.refund = state
+	return m, m.refund.form.Init()
+}
+
+// RefundUpdate handles all input and async results while the refund composer is open.
+func (m Model) RefundUpdate(msg tea.Msg) (Model, tea.Cmd) {
+	state := &m.refund
+	if !state.open {
+		return m, nil
+	}
+
+	switch msg := msg.(type) {
+	case refundRequestMsg:
+		if msg.Gen != state.gen || msg.OrderID != state.orderID {
+			return m, nil
+		}
+		state.submitting = false
+		if msg.Err != nil {
+			state.err = fmt.Sprintf("failed to send refund request: %v", msg.Err)
+			return m, nil
+		}
+		gen := state.gen
+		m.refund = refundState{gen: gen}
+		m.notice = &VisibleNotice{message: "Refund request sent"}
+		return m, nil
+
+	case tea.WindowSizeMsg:
+		state.form = m.buildRefundForm(state)
+		m.resizeRefundTextarea(state)
+		return m, nil
+
+	case tea.KeyMsg:
+		if state.submitting {
+			return m, nil
+		}
+		switch msg.String() {
+		case "esc":
+			gen := state.gen
+			m.refund = refundState{gen: gen}
+			return m, nil
+		case "ctrl+s":
+			return m, m.submitRefundRequest(state)
+		case "tab", "shift+tab":
+			return m, m.setRefundFocus(state, (state.focusIdx+1)%refundFocusCount)
+		}
+	}
+
+	if state.focusIdx == refundFocusReason {
+		state.err = ""
+		state.reasonErr = ""
+		form, cmd := state.form.Update(msg)
+		if f, ok := form.(*huh.Form); ok {
+			state.form = f
+		}
+		if state.form.State == huh.StateCompleted {
+			state.form = m.buildRefundForm(state)
+			return m, m.setRefundFocus(state, refundFocusMessage)
+		}
+		return m, cmd
+	}
+
+	if _, ok := msg.(tea.KeyMsg); ok {
+		state.err = ""
+		state.messageErr = ""
+	}
+	ta, cmd := state.textarea.Update(msg)
+	state.textarea = ta
+	return m, cmd
+}
+
+func (m Model) buildRefundForm(state *refundState) *huh.Form {
+	options := make([]huh.Option[string], 0, len(models.RefundRequestReasons))
+	for _, reason := range models.RefundRequestReasons {
+		options = append(options, huh.NewOption(reason, reason))
+	}
+
+	return huh.NewForm(
+		huh.NewGroup(
+			huh.NewSelect[string]().
+				Title("Reason").
+				Key("reason").
+				Options(options...).
+				Value(&state.reason).
+				Height(len(models.RefundRequestReasons) + 1),
+		),
+	).
+		WithShowErrors(false).
+		WithShowHelp(false).
+		WithTheme(m.theme.Form()).
+		WithLayout(huh.LayoutStack).
+		WithWidth(m.refundContentWidth())
+}
+
+func (m Model) newRefundTextarea() textarea.Model {
+	ta := textarea.New()
+	ta.Prompt = ""
+	ta.Placeholder = "Describe the issue"
+	ta.ShowLineNumbers = true
+	ta.CharLimit = 65536
+	ta.DynamicHeight = false
+	ta.SetHeight(m.refundTextareaHeight())
+	ta.SetWidth(m.refundTextareaWidth())
+
+	base := lipgloss.NewStyle()
+	// Cursor-line uses a darker grey than theme.Border() so the active line
+	// reads as a subtle wash, not a bright bar competing with the highlight.
+	cursorLineBG := lipgloss.Color("236")
+	ta.SetStyles(textarea.Styles{
+		Focused: textarea.StyleState{
+			Base:             base,
+			Text:             base.Foreground(m.theme.Accent()),
+			LineNumber:       base.Foreground(m.theme.Dim()),
+			CursorLine:       base.Background(cursorLineBG).Foreground(m.theme.Accent()),
+			CursorLineNumber: base.Foreground(m.theme.Body()),
+			Placeholder:      base.Foreground(m.theme.Dim()),
+			EndOfBuffer:      base.Foreground(m.theme.Dim()),
+		},
+		Blurred: textarea.StyleState{
+			Base:             base,
+			Text:             base.Foreground(m.theme.Body()),
+			LineNumber:       base.Foreground(m.theme.Dim()),
+			CursorLine:       base.Foreground(m.theme.Background()),
+			CursorLineNumber: base.Foreground(m.theme.Dim()),
+			Placeholder:      base.Foreground(m.theme.Dim()),
+			EndOfBuffer:      base.Foreground(m.theme.Dim()),
+		},
+		Cursor: textarea.CursorStyle{
+			Color: m.theme.Highlight(),
+			Shape: tea.CursorBlock,
+			Blink: true,
+		},
+	})
+	return ta
+}
+
+func (m Model) resizeRefundTextarea(state *refundState) {
+	state.textarea.SetHeight(m.refundTextareaHeight())
+	state.textarea.SetWidth(m.refundTextareaWidth())
+}
+
+func (m Model) setRefundFocus(state *refundState, focusIdx refundFocus) tea.Cmd {
+	state.focusIdx = focusIdx
+	if focusIdx == refundFocusReason {
+		state.textarea.Blur()
+		state.form = m.buildRefundForm(state)
+		return state.form.Init()
+	}
+	return state.textarea.Focus()
+}
+
+func (m Model) submitRefundRequest(state *refundState) tea.Cmd {
+	state.err = ""
+	state.reasonErr = ""
+	state.messageErr = ""
+
+	reason := strings.TrimSpace(state.reason)
+	message := strings.TrimSpace(state.textarea.Value())
+
+	if reason == "" {
+		state.reasonErr = "select a refund reason"
+		return nil
+	}
+
+	if reason == models.RefundRequestReasonOther && message == "" {
+		state.messageErr = "message is required when reason is other"
+		return nil
+	}
+
+	state.submitting = true
+	return m.createRefundRequestCmd(state.orderID, state.gen, reason, message)
+}
+
+func (m Model) createRefundRequestCmd(orderID uint, gen uint64, reason string, message string) tea.Cmd {
+	return func() tea.Msg {
+		if m.APIClient == nil || m.User == nil {
+			return refundRequestMsg{OrderID: orderID, Gen: gen, Err: fmt.Errorf("not authenticated")}
+		}
+		err := m.APIClient.CreateRefundRequest(orderID, api.RefundRequest{
+			Reason:  reason,
+			Message: message,
+		})
+		return refundRequestMsg{OrderID: orderID, Gen: gen, Err: err}
+	}
+}
+
+// RenderRefundOverlay renders the refund composer as a centered modal.
+// The modal has no border or background fill — only padding for breathing
+// room. lipgloss.Place handles centering against the container.
+func (m Model) RenderRefundOverlay() string {
+	state := &m.refund
+	contentWidth := m.refundContentWidth()
+
+	titleText := fmt.Sprintf("%s  Refund request — Order #%d", refundIconUndo, state.orderID)
+	title := m.theme.TextAccent().
+		Bold(true).
+		Width(contentWidth).
+		Border(lipgloss.NormalBorder(), false, false, true, false).
+		BorderForeground(m.theme.Highlight()).
+		Render(titleText)
+
+	body := lipgloss.JoinVertical(
+		lipgloss.Left,
+		title,
+		"",
+		m.renderRefundReason(state),
+		"",
+		m.renderRefundTextarea(state),
+		"",
+		m.renderRefundFooter(state),
+	)
+
+	modal := lipgloss.NewStyle().
+		Padding(1, 2).
+		Render(body)
+
+	return lipgloss.Place(m.widthContainer, m.heightContainer, lipgloss.Center, lipgloss.Center, modal)
+}
+
+func (m Model) renderRefundReason(state *refundState) string {
+	if state.focusIdx == 0 && state.form != nil {
+		out := state.form.View()
+		if state.reasonErr != "" {
+			out += "\n" + m.theme.TextError().Render(state.reasonErr)
+		}
+		return out
+	}
+
+	value := state.reason
+	if value == "" {
+		value = "Select a reason"
+	}
+
+	label := m.theme.TextLabel().Render(refundIconTag + "  Reason")
+	selected := m.theme.TextAccent().
+		Border(lipgloss.HiddenBorder()).
+		PaddingLeft(1).
+		Width(m.refundContentWidth()).
+		Render(value)
+
+	out := lipgloss.JoinVertical(lipgloss.Left, label, selected)
+	if state.reasonErr != "" {
+		out += "\n" + m.theme.TextError().Render(state.reasonErr)
+	}
+	return out
+}
+
+func (m Model) renderRefundTextarea(state *refundState) string {
+	label := "Message (optional)"
+	placeholder := "Describe the issue"
+	if state.reason == models.RefundRequestReasonOther {
+		label = "Message (required)"
+		placeholder = "Describe the issue..."
+	}
+	state.textarea.Placeholder = placeholder
+
+	border := m.theme.Border()
+	if state.focusIdx == refundFocusMessage {
+		border = m.theme.Highlight()
+	}
+
+	wrapper := lipgloss.NewStyle().
+		Border(lipgloss.ThickBorder()).
+		BorderForeground(border)
+
+	contentWidth := m.refundContentWidth()
+	state.textarea.SetWidth(contentWidth - wrapper.GetHorizontalFrameSize())
+	state.textarea.SetHeight(m.refundTextareaHeight())
+
+	textareaBox := wrapper.Render(state.textarea.View())
+
+	counter := m.theme.TextDim().
+		Width(contentWidth).
+		Align(lipgloss.Right).
+		Render(fmt.Sprintf("%d chars", state.textarea.Length()))
+
+	out := lipgloss.JoinVertical(
+		lipgloss.Left,
+		m.theme.TextLabel().Render(refundIconComment+"  "+label),
+		textareaBox,
+		counter,
+	)
+	if state.messageErr != "" {
+		out += "\n" + m.theme.TextError().Render(state.messageErr)
+	}
+	return out
+}
+
+func (m Model) renderRefundFooter(state *refundState) string {
+	if state.submitting {
+		return m.theme.TextAccent().Render("sending refund request...")
+	}
+	if state.err != "" {
+		return m.theme.TextError().Render(state.err)
+	}
+	key := m.theme.TextHighlight().Bold(true)
+	sep := m.theme.TextDim().Render("  ·  ")
+	dim := m.theme.TextDim()
+	return dim.Render(refundIconKey+"  ") +
+		key.Render("tab") + dim.Render(" next") + sep +
+		key.Render("shift+tab") + dim.Render(" prev") + sep +
+		key.Render("ctrl+s") + dim.Render(" submit") + sep +
+		key.Render("esc") + dim.Render(" cancel")
+}
+
+func (m Model) refundContentWidth() int {
+	width := min(m.widthContent-refundModalHGutter, refundModalMaxWidth)
+	if width < refundModalMinWidth {
+		width = max(1, m.widthContent-refundTextareaHPad)
+	}
+	return width
+}
+
+func (m Model) refundTextareaWidth() int {
+	return max(1, m.refundContentWidth()-refundTextareaHPad)
+}
+
+func (m Model) refundTextareaHeight() int {
+	return max(refundMinTextareaRows, min(refundMaxTextareaRows, m.heightContainer-refundModalChrome))
+}

pkg/tui/update.go

@@ -2,11 +2,12 @@ package tui
 
 import (
 	"fmt"
-	"terminalShop/pkg/api"
-	"terminalShop/pkg/models"
 	"time"
 
 	tea "charm.land/bubbletea/v2"
+
+	"terminalShop/pkg/api"
+	"terminalShop/pkg/models"
 )
 
 func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
@@ -36,6 +37,10 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			if m.payment.form != nil {
 				m.payment.form.form = m.buildPaymentForm(m.payment.form)
 			}
+			if m.refund.open {
+				m.refund.form = m.buildRefundForm(&m.refund)
+				m.resizeRefundTextarea(&m.refund)
+			}
 		}
 		return m, nil
 	}
@@ -51,9 +56,15 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	switch msg := msg.(type) {
 	case VisibleError:
 		m.error = &msg
+		m.notice = nil
+		return m, nil
+	case VisibleNotice:
+		m.notice = &msg
+		m.error = nil
 		return m, nil
 	case error:
 		m.error = &VisibleError{message: msg.Error()}
+		m.notice = nil
 		if m.currentPage == shopPage || m.currentPage == cartPage {
 			return m, m.fetchCartCmd
 		}
@@ -167,9 +178,14 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		if m.shipping.form != nil || m.payment.form != nil {
 			break
 		}
-		// Dismiss error banner with ESC
-		if msg.String() == "esc" && m.error != nil {
+		// Refund overlay owns input when open; dispatched below before page handlers.
+		if m.refund.open {
+			break
+		}
+		// Dismiss banners with ESC.
+		if msg.String() == "esc" && (m.error != nil || m.notice != nil) {
 			m.error = nil
+			m.notice = nil
 			return m, nil
 		}
 		// Global navigation
@@ -192,6 +208,12 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		}
 		// non-globals. fall through to page dispatch below
 	}
+
+	// Refund overlay intercepts all input after global handling.
+	if m.refund.open {
+		return m.RefundUpdate(msg)
+	}
+
 	// Page-specifics
 	switch m.currentPage {
 	case shopPage:

pkg/tui/views.go

@@ -82,8 +82,16 @@ func (m Model) renderString() string {
 		content = loadingStyle.Render("Loading products from API...")
 	} else if m.error != nil {
 		errorStyle := m.theme.PanelError().Padding(0, 1).MarginBottom(1)
+		// soft-wrap long messages instead of clipping.
+		if m.widthContent > 4 {
+			errorStyle = errorStyle.Width(m.widthContent - 4)
+		}
 		errorBanner := errorStyle.Render(m.error.message)
 		content = errorBanner + "\n" + m.buildPageContent(availableContentHeight)
+	} else if m.notice != nil {
+		noticeStyle := m.theme.TextSuccess().Border(lipgloss.NormalBorder()).BorderForeground(m.theme.Success()).Padding(0, 1).MarginBottom(1)
+		noticeBanner := noticeStyle.Render(m.notice.message)
+		content = noticeBanner + "\n" + m.buildPageContent(availableContentHeight)
 	} else {
 		content = m.buildPageContent(availableContentHeight)
 	}
@@ -115,6 +123,10 @@ func (m Model) renderString() string {
 		MaxHeight(m.heightContainer).
 		Render(child)
 
+	if m.refund.open {
+		constrained = m.RenderRefundOverlay()
+	}
+
 	// Center the entire container in the terminal viewport
 	return lipgloss.Place(
 		m.viewportWidth,

scripts/backups/01-log-tail.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Show last 20 lines of the cron log + its mtime. Cheapest "did it run" check.
+set -euo pipefail
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+source "$SCRIPT_DIR/lib.sh"
+
+print_header "Backup log: mtime + last 20 lines"
+spinner_start "fetching log from $SSH_HOST..."
+ssh "$SSH_HOST" "
+  sudo stat -c 'Last modified: %y' '$BACKUP_LOG'
+  echo; sudo tail -20 '$BACKUP_LOG'
+"
+spinner_stop

scripts/backups/02-snapshots.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# List every restic snapshot with timestamps and tags.
+set -euo pipefail
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+source "$SCRIPT_DIR/lib.sh"
+
+print_header "All restic snapshots"
+spinner_start "querying restic via SFTP..."
+ssh "$SSH_HOST" "
+  export RESTIC_PASSWORD_FILE='$RESTIC_PASSWORD_FILE'
+  export RESTIC_REPOSITORY='$RESTIC_REPO'
+  sudo -E restic -o sftp.args='-i $RESTIC_SSH_KEY' snapshots
+"
+spinner_stop

scripts/backups/03-check.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# restic repo integrity check.
+#   ./03-check.sh         metadata only (~5s)
+#   ./03-check.sh --deep  + 10% data-pack re-read (~30s)
+set -euo pipefail
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+source "$SCRIPT_DIR/lib.sh"
+
+EXTRA=""
+if [ "${1:-}" = "--deep" ]; then
+  EXTRA="--read-data-subset=10%"
+fi
+
+print_header "restic check ${EXTRA:-(metadata only)}"
+spinner_start "running restic check on $SSH_HOST..."
+ssh "$SSH_HOST" "
+  export RESTIC_PASSWORD_FILE='$RESTIC_PASSWORD_FILE'
+  export RESTIC_REPOSITORY='$RESTIC_REPO'
+  sudo -E restic -o sftp.args='-i $RESTIC_SSH_KEY' check $EXTRA
+"
+spinner_stop

scripts/backups/04-restore-verify.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Restore the latest snapshot to /tmp on the remote box, then:
+#   - PRAGMA integrity_check on the restored DB
+#   - row-count diff vs the live DB
+# Cleans up /tmp dir at the end.
+set -euo pipefail
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+source "$SCRIPT_DIR/lib.sh"
+
+print_header "Restore latest snapshot and verify SQLite"
+spinner_start "restoring latest snapshot to /tmp on $SSH_HOST..."
+
+ssh "$SSH_HOST" \
+  "PWFILE='$RESTIC_PASSWORD_FILE' \
+   REPO='$RESTIC_REPO' \
+   KEY='$RESTIC_SSH_KEY' \
+   LIVE='$LIVE_DB' \
+   bash -s" <<'REMOTE'
+set -e
+DIR=/tmp/tshop-restore-test
+sudo rm -rf "$DIR" && sudo mkdir -p "$DIR"
+
+sudo -E RESTIC_PASSWORD_FILE="$PWFILE" RESTIC_REPOSITORY="$REPO" \
+  restic -o sftp.args="-i $KEY" restore latest --target "$DIR"
+
+DB=$(sudo find "$DIR" -name 'terminalshop.db' | head -1)
+if [ -z "$DB" ]; then
+  echo 'restored DB not found' >&2
+  exit 1
+fi
+
+echo
+echo '--- restored file ---'
+sudo stat -c '%y  %s bytes  %n' "$DB"
+
+echo
+echo '--- PRAGMA integrity_check ---'
+sudo sqlite3 "$DB" 'PRAGMA integrity_check;'
+
+echo
+echo '--- PRAGMA quick_check ---'
+sudo sqlite3 "$DB" 'PRAGMA quick_check;'
+
+echo
+echo '--- restored vs live row counts ---'
+printf '%-22s %10s %10s\n' table restored live
+for t in $(sudo sqlite3 "$DB" 'SELECT name FROM sqlite_master WHERE type="table";'); do
+  r=$(sudo sqlite3 "$DB" "SELECT COUNT(*) FROM \"$t\";")
+  l=$(sudo sqlite3 "$LIVE" "SELECT COUNT(*) FROM \"$t\";" 2>/dev/null || echo 'n/a')
+  printf '%-22s %10s %10s\n' "$t" "$r" "$l"
+done
+
+sudo rm -rf "$DIR"
+echo
+echo 'OK'
+REMOTE
+spinner_stop

scripts/backups/05-freshness.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Print latest snapshot age. Exit 0 if fresh, 1 if older than STALE_HOURS.
+set -euo pipefail
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+source "$SCRIPT_DIR/lib.sh"
+
+print_header "Latest snapshot freshness"
+
+spinner_start "querying latest snapshot..."
+LATEST=$(ssh "$SSH_HOST" "
+  export RESTIC_PASSWORD_FILE='$RESTIC_PASSWORD_FILE'
+  export RESTIC_REPOSITORY='$RESTIC_REPO'
+  sudo -E restic -o sftp.args='-i $RESTIC_SSH_KEY' snapshots --json
+" | jq -r 'max_by(.time) | .time')
+spinner_stop
+
+if [ -z "$LATEST" ] || [ "$LATEST" = "null" ]; then
+  echo "ERROR: could not parse latest snapshot time" >&2
+  exit 2
+fi
+
+NOW=$(date -u +%s)
+# GNU date (Linux) first, then BSD date (macOS) as fallback.
+if THEN=$(date -u -d "$LATEST" +%s 2>/dev/null); then
+  :
+else
+  CLEAN=$(echo "$LATEST" | sed 's/\.[0-9]*Z$/Z/')
+  THEN=$(date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$CLEAN" +%s)
+fi
+
+AGE_HRS=$(( (NOW - THEN) / 3600 ))
+echo "Latest snapshot: $LATEST"
+echo "Age:             ${AGE_HRS}h"
+echo "Threshold:       ${STALE_HOURS}h"
+
+if [ "$AGE_HRS" -lt "$STALE_HOURS" ]; then
+  print_ok "snapshot within freshness window"
+else
+  print_fail "STALE — investigate"
+  exit 1
+fi

scripts/backups/06-lfs-direct.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Independent filesystem check on lfs-remote. No restic, no password needed.
+# Proves the repo dir exists, files are present, recent uploads landed,
+# and the backup partition has room.
+set -euo pipefail
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+source "$SCRIPT_DIR/lib.sh"
+
+print_header "lfs-remote filesystem-level repo check"
+spinner_start "inspecting $LFS_HOST filesystem..."
+
+ssh "$LFS_HOST" "
+set -e
+REPO='$LFS_REPO_PATH'
+WARN_PCT=$LFS_DISK_WARN_PCT
+
+if [ ! -d \"\$REPO\" ]; then
+  echo 'ERROR: repo dir missing on lfs' >&2
+  exit 1
+fi
+
+echo '--- snapshot pointer count (one file per restic snapshot) ---'
+COUNT=\$(find \"\$REPO/snapshots\" -type f 2>/dev/null | wc -l)
+echo \"snapshots/: \$COUNT files\"
+
+echo
+echo '--- repo size on disk ---'
+du -sh \"\$REPO\"
+
+echo
+echo '--- recent uploads (files newer than 48h) ---'
+RECENT=\$(find \"\$REPO\" -type f -mtime -2 2>/dev/null | wc -l)
+echo \"files added in last 48h: \$RECENT\"
+if [ \"\$RECENT\" -eq 0 ]; then
+  echo 'WARN: no new files in last 48h' >&2
+fi
+
+echo
+echo '--- most recent snapshot pointer ---'
+LATEST=\$(ls -t \"\$REPO/snapshots\"/* 2>/dev/null | head -1)
+if [ -n \"\$LATEST\" ]; then
+  stat -c '%y  %n' \"\$LATEST\"
+else
+  echo 'WARN: no snapshot files found' >&2
+fi
+
+echo
+echo '--- disk usage ---'
+df -h \"\$REPO\"
+USED=\$(df --output=pcent \"\$REPO\" 2>/dev/null | tail -1 | tr -dc 0-9)
+if [ -n \"\$USED\" ] && [ \"\$USED\" -gt \"\$WARN_PCT\" ]; then
+  echo \"FAIL: backup partition \${USED}% full (threshold \${WARN_PCT}%)\" >&2
+  exit 1
+fi
+
+echo
+echo 'OK'
+"
+spinner_stop

scripts/backups/07-lfs-restic-check.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Independent restic check from the lfs-remote side. Reads repo via a
+# LOCAL filesystem path (not SFTP), so it proves the data is parseable
+# without any involvement from the prod box at restic level.
+#
+# Needs:
+#   - restic installed on lfs-remote (see scratchpkg port at /usr/ports/main/restic)
+#   - SSH access to both prod (to fetch the repo password) and lfs
+set -euo pipefail
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+source "$SCRIPT_DIR/lib.sh"
+
+print_header "lfs-remote restic check (independent vantage point)"
+
+# Precondition: restic must be on lfs.
+if ! ssh "$LFS_HOST" 'command -v restic >/dev/null 2>&1'; then
+  echo 'ERROR: restic not in PATH on lfs-remote' >&2
+  echo "Install via scratchpkg, then re-run." >&2
+  exit 2
+fi
+
+# Pull restic password from prod (needs sudo on prod).
+spinner_start "fetching restic password from $SSH_HOST..."
+PW=$(ssh "$SSH_HOST" "sudo cat '$RESTIC_PASSWORD_FILE'")
+spinner_stop
+if [ -z "$PW" ]; then
+  echo 'ERROR: could not read restic password from prod' >&2
+  exit 2
+fi
+
+# Run restic against the LOCAL repo path on lfs. Password fed via stdin
+# so it never lands in argv or a file on lfs.
+spinner_start "running restic check from $LFS_HOST..."
+ssh "$LFS_HOST" "restic -r '$LFS_REPO_PATH' --password-file=/dev/stdin check" <<<"$PW"
+spinner_stop
+
+echo
+print_ok "lfs-side restic check passed"

scripts/backups/check-all.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# Master runner. Executes every backup check in sequence.
+#   ./check-all.sh              stop on first failure; interactive menu when TTY
+#   ./check-all.sh --keep-going keep running after failures (no menu)
+#   ./check-all.sh --deep       use --deep on 03-check.sh
+#
+# When stdin and stdout are TTYs, a failed step opens a drill-down menu:
+#   [r]etry  [l]og  [u]nlock  [s]kip  [q]uit
+# Non-TTY (cron / piped) skips the menu and behaves like the old runner.
+set -uo pipefail
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+KEEP_GOING=0
+DEEP=0
+for arg in "$@"; do
+  case "$arg" in
+    --keep-going) KEEP_GOING=1 ;;
+    --deep)       DEEP=1 ;;
+    -h|--help)
+      echo "Usage: $0 [--keep-going] [--deep]"
+      echo "  --keep-going  don't stop on first failure, suppress interactive menu"
+      echo "  --deep        pass --deep to 03-check.sh (10% data re-read)"
+      exit 0
+      ;;
+    *)
+      echo "unknown flag: $arg" >&2
+      exit 2
+      ;;
+  esac
+done
+
+# Pull in config + color helpers (also gives us SSH_HOST + restic env for unlock).
+source "$SCRIPT_DIR/lib.sh"
+
+declare -a STEP_NAMES=()
+declare -a STEP_STATUS=()   # OK | FAIL
+FAIL=0
+
+prompt_after_fail() {
+  # returns 0=skip, 1=quit, 2=retry
+  local script="$1"
+  while :; do
+    printf '\n%sNext?%s [r]etry  [l]og  [u]nlock  [s]kip  [q]uit > ' "$C_BOLD" "$C_RESET"
+    local choice
+    read -r choice
+    case "$choice" in
+      r|R) return 2 ;;
+      l|L) "$SCRIPT_DIR/01-log-tail.sh"; echo ;;
+      u|U)
+        echo
+        ssh "$SSH_HOST" "
+          export RESTIC_PASSWORD_FILE='$RESTIC_PASSWORD_FILE'
+          export RESTIC_REPOSITORY='$RESTIC_REPO'
+          sudo -E restic -o sftp.args='-i $RESTIC_SSH_KEY' unlock
+        "
+        echo
+        ;;
+      s|S) return 0 ;;
+      q|Q) return 1 ;;
+      "")  ;;
+      *)   printf 'unknown: %s\n' "$choice" ;;
+    esac
+  done
+}
+
+run_step() {
+  local script="$1"; shift
+  echo
+  printf '%s########## %s %s ##########%s\n' "$C_CYAN$C_BOLD" "$script" "$*" "$C_RESET"
+
+  local attempts=0
+  while :; do
+    attempts=$((attempts + 1))
+    if "$SCRIPT_DIR/$script" "$@"; then
+      STEP_NAMES+=("$script")
+      STEP_STATUS+=("OK")
+      return 0
+    fi
+
+    printf '%sFAILED:%s %s\n' "$C_RED$C_BOLD" "$C_RESET" "$script" >&2
+
+    if [ -t 0 ] && [ -t 1 ] && [ "$KEEP_GOING" -eq 0 ]; then
+      prompt_after_fail "$script"
+      case "$?" in
+        0) STEP_NAMES+=("$script"); STEP_STATUS+=("FAIL"); FAIL=$((FAIL + 1)); return 0 ;;
+        1) STEP_NAMES+=("$script"); STEP_STATUS+=("FAIL"); FAIL=$((FAIL + 1)); print_summary; exit 1 ;;
+        2) echo
+           printf '%s>>>>>> retry %s (attempt %d) <<<<<<%s\n' "$C_CYAN$C_BOLD" "$script" $((attempts + 1)) "$C_RESET"
+           continue ;;
+      esac
+    fi
+
+    # non-interactive path
+    STEP_NAMES+=("$script")
+    STEP_STATUS+=("FAIL")
+    FAIL=$((FAIL + 1))
+    if [ "$KEEP_GOING" -eq 0 ]; then
+      print_summary
+      exit 1
+    fi
+    return 0
+  done
+}
+
+print_summary() {
+  echo
+  printf '%s===============================================%s\n' "$C_CYAN$C_BOLD" "$C_RESET"
+  printf '   %-28s %s\n' "Script" "Result"
+  printf '   %-28s %s\n' "----------------------------" "--------"
+  local i
+  for i in "${!STEP_NAMES[@]}"; do
+    local name="${STEP_NAMES[$i]}"
+    local status="${STEP_STATUS[$i]}"
+    local color sym
+    case "$status" in
+      OK)   color="$C_GREEN"; sym="✓ OK"   ;;
+      FAIL) color="$C_RED"  ; sym="✗ FAIL" ;;
+    esac
+    printf '   %-28s %s%s%s\n' "$name" "$color" "$sym" "$C_RESET"
+  done
+  printf '%s===============================================%s\n' "$C_CYAN$C_BOLD" "$C_RESET"
+  if [ "$FAIL" -eq 0 ]; then
+    printf '%sAll checks passed.%s\n' "$C_GREEN$C_BOLD" "$C_RESET"
+  else
+    printf '%s%d check(s) failed.%s\n' "$C_RED$C_BOLD" "$FAIL" "$C_RESET"
+  fi
+}
+
+run_step 01-log-tail.sh
+run_step 02-snapshots.sh
+if [ "$DEEP" -eq 1 ]; then run_step 03-check.sh --deep; else run_step 03-check.sh; fi
+run_step 04-restore-verify.sh
+run_step 05-freshness.sh
+run_step 06-lfs-direct.sh
+run_step 07-lfs-restic-check.sh
+
+print_summary
+[ "$FAIL" -eq 0 ] || exit 1

scripts/backups/config.env.example

@@ -0,0 +1,28 @@
+# Backup verification config.
+# Copy to config.env (gitignored) and fill in your real values.
+#
+#   cp config.env.example config.env
+#   $EDITOR config.env
+
+# SSH alias for the prod box (resolved via ~/.ssh/config).
+SSH_HOST="ubuntu-helsinki"
+
+# Restic repository URL. Format: sftp:HOST:PATH
+# HOST is the Tailscale name of the backup target box.
+RESTIC_REPO="sftp:YOUR_TAILNET_HOST.ts.net:/root/backups/tshop"
+
+# Paths on the REMOTE prod box (not your laptop).
+RESTIC_PASSWORD_FILE="/root/.restic-password"
+RESTIC_SSH_KEY="/root/.ssh/tshop-backup"
+BACKUP_LOG="/var/log/backup-tshop.log"
+LIVE_DB="/root/terminalShop/data/terminalshop.db"
+
+# Freshness alert threshold (hours). 24h cron + 4h slop = 28.
+STALE_HOURS="28"
+
+# lfs-remote = the box that RECEIVES the backups.
+# Used by 06-lfs-direct.sh and 07-lfs-restic-check.sh for out-of-band checks.
+LFS_HOST="lfs-remote"
+LFS_REPO_PATH="/root/backups/tshop"
+# 06 fails if the backup partition is more full than this percent.
+LFS_DISK_WARN_PCT="80"

scripts/backups/lib.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Shared loader for the backup verification scripts.
+# Each script should: source "$SCRIPT_DIR/lib.sh"
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+if [ ! -f "$SCRIPT_DIR/config.env" ]; then
+  echo "ERROR: $SCRIPT_DIR/config.env missing." >&2
+  echo "Run: cp $SCRIPT_DIR/config.env.example $SCRIPT_DIR/config.env" >&2
+  exit 1
+fi
+
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/config.env"
+
+# ANSI colors. Emit only when stdout is a TTY and NO_COLOR is unset.
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+  C_RED=$'\033[1;31m'
+  C_GREEN=$'\033[1;32m'
+  C_YELLOW=$'\033[1;33m'
+  C_BLUE=$'\033[1;34m'
+  C_CYAN=$'\033[1;36m'
+  C_BOLD=$'\033[1m'
+  C_RESET=$'\033[0m'
+else
+  C_RED=""; C_GREEN=""; C_YELLOW=""; C_BLUE=""; C_CYAN=""; C_BOLD=""; C_RESET=""
+fi
+
+print_header() { printf '\n%s=== %s ===%s\n' "$C_CYAN" "$1" "$C_RESET"; }
+print_ok()     { printf '%sOK%s%s\n'    "$C_GREEN"  "$C_RESET" "${1:+ — $1}"; }
+print_fail()   { printf '%sFAIL%s%s\n'  "$C_RED"    "$C_RESET" "${1:+ — $1}" >&2; }
+print_warn()   { printf '%sWARN%s%s\n'  "$C_YELLOW" "$C_RESET" "${1:+ — $1}" >&2; }
+print_info()   { printf '%s%s%s\n'      "$C_BLUE"   "$1"       "$C_RESET"; }
+
+# Spinner: shows a rotating braille char while a foreground command runs.
+# Use as a pair around the silent/blocking call:
+#   spinner_start "fetching log..."
+#   ssh ...
+#   spinner_stop
+# Auto-skips when stdout isn't a TTY (cron / piped). Real output from the
+# wrapped command will visually overwrite the spinner — by design.
+SPINNER_PID=""
+spinner_start() {
+  [ -t 1 ] && [ -z "${NO_COLOR:-}" ] || return 0
+  local msg="${1:-working}"
+  (
+    trap 'exit 0' TERM
+    local chars=('⠋' '⠙' '⠹' '⠸' '⠼' '⠴' '⠦' '⠧' '⠇' '⠏')
+    local i=0
+    while :; do
+      i=$(( (i + 1) % ${#chars[@]} ))
+      printf '\r%s%s%s %s' "$C_CYAN" "${chars[$i]}" "$C_RESET" "$msg"
+      sleep 0.08
+    done
+  ) &
+  SPINNER_PID=$!
+  disown "$SPINNER_PID" 2>/dev/null || true
+}
+spinner_stop() {
+  [ -n "$SPINNER_PID" ] || return 0
+  kill "$SPINNER_PID" 2>/dev/null || true
+  wait "$SPINNER_PID" 2>/dev/null || true
+  printf '\r\033[K'
+  SPINNER_PID=""
+}