@blamejs/blamejs-shop 0.4.19 → 0.4.20

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.20 (2026-06-06) — **Payment integrity: refunds, gift-card balances, and checkout submission are race-proof, and abandoned checkouts return gift-card funds.** A money-path hardening release. Concurrent refund clicks on the same return can no longer reach the payment provider twice. A gift card that part-paid a checkout gets its balance back when the order is cancelled, fails payment, or is reaped as stale. Double-submitting checkout can no longer create two charges and two orders. Return requests are refused server-side on orders that aren't in a returnable state, the refund confirmation screen shows the currency the provider will actually refund, and a buy-online-pickup-in-store order now reaches its delivered state when picked up. **Fixed:** *A return can only be refunded once, even under concurrent requests* — Two simultaneous refund requests for the same approved return could both pass the status check and both reach the payment provider, each with a fresh idempotency key — a double refund. The refund now claims the return atomically before the provider is called (the second request answers 409), the provider call uses a key derived from the return itself so even a retry collapses into the same refund, and a provider failure releases the claim so the refund can be retried. · *Gift-card funds come back when a part-paid checkout dies* — When a gift card partially covered a checkout and the order was then cancelled, failed payment, or sat abandoned until reaped, the card's debit was never returned — the balance was permanently gone. Redemptions are now reversed on those order transitions: the card balance is restored (a fully drained card is reactivated), the reversal is idempotent, and it rides the same order lifecycle that releases inventory holds. · *Double-submitting checkout creates one charge and one order* — Two concurrent checkout submissions could both pass the cart-status read and each create a payment intent and an order. The cart is now claimed atomically as the single gate — the second submission is redirected back to the cart — and the payment-provider idempotency key is derived from the cart, so even a duplicate that slipped through would collapse into one charge on the provider's side. A failure before the order exists releases the claim so the customer can retry. · *Return requests are validated server-side* — The return-request form and its submission are now refused on orders that are not in a returnable state — a refunded, cancelled, or unpaid order answers with a clear message instead of opening a return that could feed a second refund downstream. Previously only the button's visibility enforced this. · *A failed gift-card settlement no longer strands a completed payment* — If recording a gift card's redemption failed after the payment had already succeeded and the order existed, the checkout aborted mid-way — leaving a paid order with a cart that never converted. The settlement step now completes the order regardless and surfaces the failure for follow-up instead of stranding the purchase. · *The refund confirmation shows the currency the provider refunds* — The confirmation screen displayed the return's approved currency, but the provider refunds in the original charge's currency. The screen now reads the same source the refund uses. · *Pickup orders reach their delivered state* — Marking a pickup order as picked up drove an order transition that was only legal for shipped orders, and the failure was silently swallowed — the pickup schedule said picked up while the order stayed in its paid state. The order lifecycle now has a pickup-completion transition, so a picked-up order genuinely lands in delivered and downstream reporting sees it.
+
 - v0.4.19 (2026-06-06) — **Wishlist alerts fire once per event instead of repeating daily, stale digests catch up with a single email, and webhook delivery stops throttling itself.** A set of notification and delivery fixes. Back-in-stock and price-drop wishlist alerts now fire only when something actually changes — a steadily in-stock item no longer re-alerts every day. A wishlist digest whose schedule fell behind sends one catch-up email instead of one per minute until current. Outbound webhook delivery no longer counts its own rate-limit refusals against the limit (which kept the throttle tripped once hit), retrying an exhausted delivery no longer duplicates its dead-letter record, and the blog RSS feed renders correctly when a post title or body contains dollar-sign sequences. **Fixed:** *Back-in-stock and price-drop alerts fire on the change, not the state* — The wishlist alert sweep evaluated the current state of each item, so anything in stock re-alerted every wishlister on every sweep — the daily dedupe window just made the flood daily. Alerts now track the last-observed state per customer and item: back-in-stock fires only on an out-of-stock-to-in-stock transition, price-drop only when the price falls below the level already alerted, and a recovered price re-arms the alert. A steadily in-stock item never re-fires. The weekly cap and dedupe are also enforced atomically, so two overlapping sweeps can't double-send past the cap. · *A stale digest enrollment catches up with one email* — A wishlist digest whose next-send time had fallen far behind advanced one period per scheduler tick and sent an email each time — a subscriber could receive dozens of digests in an hour while the schedule caught up. Catching up now snaps the schedule to the present and sends at most one digest. · *Webhook delivery rate limiting no longer feeds on its own refusals* — The outbound webhook rate-limit gate counted its own refusal records toward the limit, so once an endpoint tripped the throttle it could stay tripped indefinitely, and every suppressed attempt persisted another row. Refusals are no longer counted by the gate and collapse to a single record per endpoint per window. · *Retrying an exhausted webhook delivery is idempotent* — Manually retrying a delivery that had already exhausted its attempts inserted a fresh dead-letter record on every click. Retry of an exhausted or already-delivered delivery now answers as a clean no-op, and the dead-letter table enforces one record per delivery. · *The RSS feed renders posts containing dollar-sign sequences* — The feed assembled items with a plain string replacement, which gives `$` sequences special meaning — a post title or body containing a dollar sign followed by a backtick or ampersand could corrupt the entire feed XML. The feed now uses the same literal splice the page renderers use. The feed's author field also no longer exposes an internal identifier; it carries the shop name, matching the blog pages.
 
 - v0.4.18 (2026-06-06) — **Staff accounts: per-operator credentials with owner, manager, and viewer roles — the shared admin key becomes break-glass.** The admin console gains multi-operator support. Create staff accounts at the new Operators screen, each with its own password and optional API key, and assign a least-privilege role: owner (everything, including operator management), manager (catalog, orders, customers, marketing), or viewer (read-only). Role enforcement happens at the admin write layer on every state-changing request — a viewer is refused the write itself, not just the menu link. The shared ADMIN_API_KEY keeps working as the bootstrap and break-glass owner credential, so upgrading can never lock a store out; once staff accounts exist, treat it like a recovery key. **Added:** *Operators console with per-operator credentials* — `/admin/operators` creates and disables staff accounts. Each operator gets their own password (Argon2id) and optionally a personal API key for the JSON surface, shown once at creation. The screen lists who created each operator and when; disabling one takes effect on their very next request — the signed-in session re-reads the live account row, so there is no revocation lag. · *Owner / manager / viewer roles, enforced on the write itself* — Every admin mutation passes a single permission gate keyed to the action being performed: owner holds every permission including operator management and settings; manager covers catalog, orders, customers, and marketing; viewer holds none — every POST, PUT, and DELETE is refused with a 403, regardless of how the request arrives (browser form or bearer JSON). Read screens remain available to any authenticated operator. Role-denied attempts are recorded in the audit chain alongside every operator-management action. · *Bootstrap and break-glass: the shared key still works* — `ADMIN_API_KEY` resolves to the owner role exactly as before — a store with no operator rows behaves identically to the previous release, and the first staff account is created while signed in with the shared key. Unknown sign-in attempts burn a real password verification against a fixed dummy hash, so response timing does not reveal whether an account exists.

package/lib/admin.js

@@ -4622,26 +4622,60 @@ function mount(router, deps) {
       function (id, body) { return returns.markReceived(id, { operator_notes: body.operator_notes || undefined }); },
     ));
 
-    // Issue the provider refund for an RMA (when a captured intent exists),
-    // then record the RMA refund. The provider call runs FIRST — only if it
-    // succeeds does the RMA move to refunded — so the queue never marks a
-    // return refunded with the customer never paid back. The refund amount
-    // is the RMA's approved refund_amount_minor (set at approve time);
-    // absent one, the provider issues a full refund of the intent.
+    // Issue the provider refund for an RMA (when a captured intent exists).
+    //
+    // Two guards stop a concurrent double-click / two-operator race from
+    // refunding the customer twice:
+    //
+    //   1. The RMA is CLAIMED atomically (received → refunded) BEFORE the
+    //      provider call. returns.refund's conditional UPDATE matches the
+    //      row for exactly one racer; the loser gets RMA_TRANSITION_REFUSED
+    //      (mapped to 409) and never reaches the provider. The claim runs
+    //      first so a winner holds the row while money moves.
+    //   2. The Stripe idempotency key is DETERMINISTIC in the return id
+    //      ("rma-refund:<rma.id>") — no per-request uuid. Even if a logic
+    //      regression let two calls reach the provider, Stripe collapses
+    //      them onto one Refund (same key → same result), so the customer is
+    //      never paid back twice. The deterministic key is also stable
+    //      across an operator retry of the SAME refund.
+    //
+    // On a provider failure the claim is RELEASED (refunded → received) so a
+    // retry can run — the RMA never strands in `refunded` with no money
+    // moved. The refund amount is the RMA's approved refund_amount_minor
+    // (set at approve time); absent one, the provider issues a full refund
+    // of the intent IN THE ORDER'S CHARGE CURRENCY (a Stripe refund against a
+    // PaymentIntent has no currency of its own — it always returns the
+    // charge currency, which is order2.currency).
     async function _rmaProviderRefund(rma, order2, body) {
-      var idem = "rma-refund:" + rma.id + ":" + (body.idempotency_suffix || b.uuid.v7());
-      var refund = await payment.refund({
-        payment_intent: order2.payment_intent_id,
-        amount_minor:   (rma.refund_amount_minor != null && rma.refund_amount_minor > 0) ? rma.refund_amount_minor : undefined,
-        reason:         "requested_by_customer",
-        metadata:       { order_id: order2.id, rma_id: rma.id, rma_code: rma.rma_code || "" },
-      }, idem);
-      var updated = await returns.refund(rma.id, {
+      // Claim the RMA first. A lost claim (RMA_TRANSITION_REFUSED) bubbles
+      // to the route, which maps it to 409 via _returnsClientError — the
+      // loser of a concurrent refund never touches the provider. The note
+      // stamped at claim time is the operator's own text when supplied, else
+      // a stable marker; the live provider refund id is on the audit row +
+      // the JSON response, so it stays reconcilable without a second write.
+      var claimed = await returns.refund(rma.id, {
         operator_notes: (body.operator_notes && body.operator_notes.length)
           ? body.operator_notes
-          : ("provider refund " + refund.id),
+          : "provider refund issued",
       });
-      return { refund: refund, rma: updated };
+      var idem = "rma-refund:" + rma.id;
+      var refund;
+      try {
+        refund = await payment.refund({
+          payment_intent: order2.payment_intent_id,
+          amount_minor:   (rma.refund_amount_minor != null && rma.refund_amount_minor > 0) ? rma.refund_amount_minor : undefined,
+          reason:         "requested_by_customer",
+          metadata:       { order_id: order2.id, rma_id: rma.id, rma_code: rma.rma_code || "" },
+        }, idem);
+      } catch (e) {
+        // Provider call failed — release the claim so the operator can retry
+        // a transient failure. A release failure can't be recovered here, so
+        // surface the original provider error (the operator-actionable one).
+        try { await returns.releaseRefundClaim(rma.id); }
+        catch (_releaseErr) { /* drop-silent — the original provider error below is the actionable one */ }
+        throw e;
+      }
+      return { refund: refund, rma: claimed };
     }
 
     // Browser confirmation interstitial for a provider-backed RMA refund —
@@ -4665,9 +4699,17 @@ function mount(router, deps) {
           // record-only form handles it.
           return _redirect(res, "/admin/returns/" + enc + "?err=1");
         }
+        // Format the confirm amount in the ORDER'S CHARGE CURRENCY, not the
+        // RMA's approved refund_currency. A Stripe refund against a captured
+        // PaymentIntent carries no currency of its own — it always settles in
+        // the charge currency. The two differ on a multi-currency shop (an
+        // RMA approved with the default USD currency against a EUR order), and
+        // showing the RMA currency would promise the operator a different
+        // figure than the provider actually refunds.
+        var refundCcy = rmaCtx.order.currency;
         var amount = (rma.refund_amount_minor != null && rma.refund_amount_minor > 0)
-          ? pricing.format(rma.refund_amount_minor, rma.refund_currency || "USD")
-          : pricing.format(rmaCtx.order.grand_total_minor, rmaCtx.order.currency);
+          ? pricing.format(rma.refund_amount_minor, refundCcy)
+          : pricing.format(rmaCtx.order.grand_total_minor, refundCcy);
         _sendHtml(res, 200, renderAdminConfirm({
           shop_name: deps.shop_name, nav_available: navAvailable, active: "returns",
           heading: "Refund return " + _htmlEscape(rma.rma_code || rma.id.slice(0, 8)) + "?",

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.19",
+  "version": "0.4.20",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-6k53cvkRrxMgmeStLIoLjVXZQHqIJgTmv1Izd8TYhh1HOC4POgE6GCvx1bsalyEP",

package/lib/cart.js

@@ -354,6 +354,50 @@ function create(opts) {
       return (await query("SELECT * FROM carts WHERE id = ?1", [cartId])).rows[0];
     },
 
+    // Atomically claim an ACTIVE cart for checkout. The `AND status =
+    // 'active'` predicate is the serialization point: on D1 a single UPDATE
+    // is atomic, so when two concurrent POST /checkout requests race the same
+    // cart (a double-click, two tabs) exactly ONE flips it to 'converted' and
+    // matches the row; the other matches zero rows and loses. The winner runs
+    // the (single) charge + order; the loser is told the checkout is already
+    // in progress and never creates a second PaymentIntent or order.
+    //
+    // Returns `{ claimed: true, cart }` for the winner, `{ claimed: false,
+    // cart }` for the loser (cart is the post-claim row so the caller can
+    // redirect to its order), or `{ claimed: false, cart: null }` when the
+    // cart id doesn't exist at all. A non-active cart (already converted /
+    // abandoned) loses the claim — the existing checkout owns it.
+    claimForCheckout: async function (cartId) {
+      _uuid(cartId, "cart_id");
+      var ts = _now();
+      var r = await query(
+        "UPDATE carts SET status = 'converted', updated_at = ?1 WHERE id = ?2 AND status = 'active'",
+        [ts, cartId],
+      );
+      var cart = (await query("SELECT * FROM carts WHERE id = ?1", [cartId])).rows[0] || null;
+      return { claimed: Number(r.rowCount || 0) === 1, cart: cart };
+    },
+
+    // Release a checkout claim back to 'active' so the buyer can retry. The
+    // checkout flow claims the cart (claimForCheckout) BEFORE the charge so a
+    // concurrent racer is locked out; if the charge / order creation then
+    // throws BEFORE the order exists, the claimer releases the cart so the
+    // shopper isn't stranded on a permanently-'converted' cart with no order
+    // to show. Atomic + self-targeting: `AND status = 'converted'` makes a
+    // double-release a no-op, and only the claimer (which set 'converted')
+    // ever calls this, so it can't resurrect a cart a DIFFERENT completed
+    // checkout legitimately converted. Returns true when the cart was
+    // released, false when there was nothing to release.
+    releaseCheckoutClaim: async function (cartId) {
+      _uuid(cartId, "cart_id");
+      var ts = _now();
+      var r = await query(
+        "UPDATE carts SET status = 'active', updated_at = ?1 WHERE id = ?2 AND status = 'converted'",
+        [ts, cartId],
+      );
+      return Number(r.rowCount || 0) === 1;
+    },
+
     // ---- abandoned-cart visibility (operator dashboard) ---------------
     //
     // A cart is "abandoned" for dashboard purposes when it is still

package/lib/checkout.js

@@ -413,6 +413,15 @@ function create(deps) {
   // the order id. Called once per order, immediately after the order
   // row exists, so a card is never burned for an order that failed to
   // create.
+  //
+  // The ledger debit is BEST-EFFORT: the card row's balance (decremented by
+  // redeem above) is the authoritative spendable balance, and the ledger is
+  // the audit trail. A ledger write failure (e.g. an unmigrated ledger table,
+  // or a ledger view that lags the card row) must not throw out of the
+  // post-create redeem path and strand the already-created order + its live
+  // PaymentIntent. The card-row debit already happened; the ledger row is
+  // reconcilable from the redemption record. Same posture the admin issue
+  // route takes when seeding the opening credit.
   async function _redeemGiftCard(resolved, orderId) {
     var redemption = await giftcards.redeem({
       code:         resolved.code_plain,
@@ -420,15 +429,58 @@ function create(deps) {
       amount_minor: resolved.applied_minor,
     });
     if (giftCardLedger) {
-      await giftCardLedger.debit({
-        gift_card_id: resolved.card.id,
-        order_id:     orderId,
-        amount_minor: resolved.applied_minor,
-      });
+      try {
+        await giftCardLedger.debit({
+          gift_card_id: resolved.card.id,
+          order_id:     orderId,
+          amount_minor: resolved.applied_minor,
+        });
+      } catch (ledgerErr) {
+        // Surface for reconciliation, but never let the audit-row write undo
+        // a card debit that already landed or strand the placed order.
+        try {
+          b.audit.safeEmit({
+            action:   "checkout.giftcard.ledger_debit.error",
+            outcome:  "failure",
+            metadata: {
+              gift_card_id: resolved.card.id,
+              order_id:     orderId,
+              amount_minor: resolved.applied_minor,
+              message:      (ledgerErr && ledgerErr.message) || String(ledgerErr),
+            },
+          });
+        } catch (_auditErr) { /* drop-silent — the redemption record is the durable trail */ }
+      }
     }
     return redemption;
   }
 
+  // Run a post-create credit redemption (gift-card / loyalty burn) so a
+  // failure can NEVER strand the already-created order + its live
+  // PaymentIntent. The order row and the PaymentIntent exist by the time
+  // this runs, and the buyer will pay the credit-reduced amount — so a
+  // throw out of the redeem (a card that raced to zero, a transient DB
+  // error) must not bubble up and leave the cart un-converted with an
+  // orphaned charge. The failure is captured to the audit sink for operator
+  // reconciliation (the credit reduced the charge but the debit didn't
+  // land, so the operator settles the card / points by hand) and the flow
+  // continues. `fn` returns the redeem promise (or null when there's no
+  // credit of that kind to burn).
+  async function _settleCreditPostCreate(kind, orderId, fn) {
+    try {
+      return await fn();
+    } catch (e) {
+      try {
+        b.audit.safeEmit({
+          action:   "checkout." + kind + ".redeem.error",
+          outcome:  "failure",
+          metadata: { order_id: orderId, message: (e && e.message) || String(e) },
+        });
+      } catch (_auditErr) { /* drop-silent — never let the audit write mask the original failure */ }
+      return null;
+    }
+  }
+
   // Resolve an optional loyalty points credit against a priced quote.
   // `points` is the number of points the customer asked to spend;
   // `customerId` is the signed-in customer's UUID (a guest cart has
@@ -693,14 +745,23 @@ function create(deps) {
 
   // Compose a quote from a cart + ship-to + (optional) selected
   // shipping service. Pure read — no DB writes.
-  async function _buildQuote(input) {
+  async function _buildQuote(input, qOpts) {
     if (!input || typeof input !== "object") throw new TypeError("checkout.quote: input required");
     _uuid(input.cart_id, "cart_id");
     _shipTo(input.ship_to);
+    qOpts = qOpts || {};
 
     var c = await cart.get(input.cart_id);
     if (!c)                       throw new TypeError("checkout: cart " + input.cart_id + " not found");
-    if (c.status !== "active")    throw new TypeError("checkout: cart status is " + c.status + ", cannot quote");
+    // A live preview (quote) requires the cart to be active. confirm() claims
+    // the cart to 'converted' BEFORE building the quote (the single-charge
+    // gate against a double-submit), so on that path the claimed status is
+    // permitted via qOpts.allowClaimed — the cart confirm is settling IS
+    // 'converted', and rejecting it here would break the very flow that owns
+    // the conversion.
+    if (c.status !== "active" && !(qOpts.allowClaimed && c.status === "converted")) {
+      throw new TypeError("checkout: cart status is " + c.status + ", cannot quote");
+    }
     var rawLines = await cart.listLines(c.id);
     if (rawLines.length === 0)    throw new TypeError("checkout: cart is empty");
     // Reapply the active quantity-break for each line at confirm time —
@@ -816,43 +877,84 @@ function create(deps) {
         throw new TypeError("checkout: customer.name — Enter a name of 120 characters or fewer.");
       }
       if (!input.selected_shipping_id) throw new TypeError("checkout.confirm: selected_shipping_id required");
-      var idempotencyKey = input.idempotency_key;
-      if (typeof idempotencyKey !== "string" || idempotencyKey.length < 8) {
-        throw new TypeError("checkout.confirm: idempotency_key (≥8 chars) required");
-      }
 
-      var quote = await _buildQuote(input);
-      if (!quote.selected_shipping) {
-        // _buildQuote already threw above, but defense in depth.
-        throw new TypeError("checkout.confirm: selected_shipping resolution returned null");
-      }
-      if (quote.totals.grand_total_minor <= 0) {
-        throw new TypeError("checkout.confirm: grand_total_minor must be > 0 (zero-total orders use a separate freebie flow)");
+      // Atomic single-charge gate against a double-submit. Two concurrent
+      // POST /checkout requests for the same cart (a double-click, two tabs,
+      // a retried form post) must NOT each create a PaymentIntent + order.
+      // claimForCheckout flips the cart 'active' → 'converted' in one atomic
+      // UPDATE; exactly one racer matches the row and proceeds, the other
+      // loses the claim and is told the checkout is already in progress —
+      // never a second charge. A non-active cart (already converting /
+      // converted / abandoned) loses for the same reason. The claim runs
+      // BEFORE the PaymentIntent so the loser can't slip a charge in.
+      var claim = await cart.claimForCheckout(input.cart_id);
+      if (!claim.cart) throw new TypeError("checkout: cart " + input.cart_id + " not found");
+      if (!claim.claimed) {
+        // Lost the claim — another checkout for this cart is in flight or
+        // already completed. Surface a typed signal so the storefront can
+        // redirect to the in-progress order rather than starting a second.
+        var inProgress = new Error("checkout: a checkout is already in progress for this cart");
+        inProgress.code = "CHECKOUT_IN_PROGRESS";
+        throw inProgress;
       }
 
-      // Reserve stock for every shippable, non-exempt line BEFORE any
-      // charge. Insufficient stock throws a coded INSUFFICIENT_STOCK error
-      // here (no PaymentIntent, no order) which the storefront re-renders
-      // inline. The holds placed here ride into the pending order and are
-      // converted to a real shelf debit on the paid transition (or released
-      // when the order is cancelled / expires). Everything AFTER this point
-      // runs inside a guard that releases the holds if a later step throws
-      // before the order is committed, so a refused gift-card / payment
-      // error never strands held stock.
-      var stockHolds = await _placeStockHolds(quote.lines);
-      // Conditional rollback: the catch releases the placed holds ONLY when
-      // no pending order was created. Once createFromCart succeeds, the
-      // order row OWNS those holds — releasing them here would double-free
-      // (the paid decrement / cancel release, or the stale-pending reaper,
-      // settles them once the order exists), and a floored blanket release
-      // could even eat a CONCURRENT shopper's hold on the same SKU. The
-      // context object is mutated inside _confirmAfterHolds the instant the
-      // order is created.
+      // The cart is claimed ('converted'); from here a throw BEFORE the order
+      // is created must RELEASE the claim ('converted' → 'active') so the
+      // shopper can retry. Once the order exists the claim is permanent (the
+      // order owns the conversion) — the reaper / cancel edge handles an
+      // abandoned pending order, not a re-openable cart. rollbackCtx, shared
+      // with _confirmAfterHolds, flips orderCreated true the instant the order
+      // row exists so neither the stock-hold release nor the claim release
+      // fires once the order owns them.
       var rollbackCtx = { orderCreated: false };
       try {
-        return await this._confirmAfterHolds(input, quote, email, stockHolds, rollbackCtx);
+        // Deterministic Stripe idempotency key, derived from the claimed
+        // cart. One cart = one checkout (the claim guarantees it), so even if
+        // a double-fire reached the provider, Stripe collapses both onto the
+        // same PaymentIntent (same key → same intent). The caller-supplied
+        // idempotency_key is ignored for the provider call — the cart claim
+        // is the authoritative single-charge identity — but still accepted on
+        // the input for backward compatibility / the record-only paths.
+        var idempotencyKey = "checkout:" + input.cart_id;
+
+        var quote = await _buildQuote(input, { allowClaimed: true });
+        if (!quote.selected_shipping) {
+          // _buildQuote already threw above, but defense in depth.
+          throw new TypeError("checkout.confirm: selected_shipping resolution returned null");
+        }
+        if (quote.totals.grand_total_minor <= 0) {
+          throw new TypeError("checkout.confirm: grand_total_minor must be > 0 (zero-total orders use a separate freebie flow)");
+        }
+
+        // Reserve stock for every shippable, non-exempt line BEFORE any
+        // charge. Insufficient stock throws a coded INSUFFICIENT_STOCK error
+        // here (no PaymentIntent, no order) which the storefront re-renders
+        // inline. The holds placed here ride into the pending order and are
+        // converted to a real shelf debit on the paid transition (or released
+        // when the order is cancelled / expires).
+        var stockHolds = await _placeStockHolds(quote.lines);
+        // Stash the placed holds on rollbackCtx so the single catch below can
+        // release them when a later step throws before the order is created.
+        rollbackCtx.stockHolds = stockHolds;
+        return await this._confirmAfterHolds(input, quote, email, stockHolds, rollbackCtx, idempotencyKey);
       } catch (e) {
-        if (!rollbackCtx.orderCreated) await _releaseStockHolds(stockHolds);
+        // Only roll back when no pending order was created. Once
+        // createFromCart succeeds the order OWNS the holds + the conversion —
+        // releasing the holds would double-free (the paid decrement / cancel
+        // release, or the stale-pending reaper, settles them) and could eat a
+        // concurrent shopper's hold on the same SKU, and re-opening the cart
+        // would orphan the order. A throw before the order exists releases
+        // both the placed holds AND the checkout claim so the shopper can
+        // retry on the same cart. Both releases are atomic + self-targeting,
+        // so neither can disturb a genuinely completed checkout.
+        if (!rollbackCtx.orderCreated) {
+          if (rollbackCtx.stockHolds) {
+            try { await _releaseStockHolds(rollbackCtx.stockHolds); }
+            catch (_holdErr) { /* drop-silent — claim release below + original error are the actionable parts */ }
+          }
+          try { await cart.releaseCheckoutClaim(input.cart_id); }
+          catch (_releaseErr) { /* drop-silent — the original error below is the actionable one */ }
+        }
         throw e;
       }
     },
@@ -867,10 +969,16 @@ function create(deps) {
     // mutable flag the catch reads: set `orderCreated` true the moment a
     // pending order exists so a LATER throw doesn't release holds the order
     // now owns.
-    _confirmAfterHolds: async function (input, quote, email, stockHolds, rollbackCtx) {
-      // Already validated in confirm() above; re-read here since the PI
-      // creation moved into this split-out body.
-      var idempotencyKey = input.idempotency_key;
+    _confirmAfterHolds: async function (input, quote, email, stockHolds, rollbackCtx, idempotencyKey) {
+      // The Stripe idempotency key is derived deterministically from the
+      // claimed cart by confirm() (one cart = one checkout), so a double-fire
+      // collapses onto a single PaymentIntent on Stripe's side. Defended for
+      // a direct call: fall back to the input key.
+      if (typeof idempotencyKey !== "string" || idempotencyKey.length < 8) {
+        idempotencyKey = (typeof input.idempotency_key === "string" && input.idempotency_key.length >= 8)
+          ? input.idempotency_key
+          : ("checkout:" + input.cart_id);
+      }
       // Resolve an optional gift-card credit BEFORE any charge so a bad
       // code fails the checkout without touching Stripe. The credit
       // reduces the amount due; the order still records the full grand
@@ -940,8 +1048,16 @@ function create(deps) {
         // The pending order now owns the holds — a throw from here on must
         // NOT blanket-release them (see the conditional rollback in confirm).
         if (rollbackCtx) rollbackCtx.orderCreated = true;
-        if (gc) await _redeemGiftCard(gc, paidOrder.id);
-        if (loy) await _redeemLoyalty(loy, loyaltyCustomerId, paidOrder.id);
+        // Same settlement posture as the PaymentIntent branch below: the
+        // order exists and the credits priced it, so a redeem failure here
+        // must not strand the cart un-converted — it is captured and
+        // reconciled, never propagated.
+        await _settleCreditPostCreate("giftcard", paidOrder.id, function () {
+          return gc ? _redeemGiftCard(gc, paidOrder.id) : null;
+        });
+        await _settleCreditPostCreate("loyalty", paidOrder.id, function () {
+          return loy ? _redeemLoyalty(loy, loyaltyCustomerId, paidOrder.id) : null;
+        });
         // Best-effort: record the auto-discount redemptions against the
         // placed order. Runs post-commit so a recording failure can't
         // reverse an order that's already paid.
@@ -1003,11 +1119,20 @@ function create(deps) {
       if (rollbackCtx) rollbackCtx.orderCreated = true;
 
       // Burn the gift-card + loyalty credits against the created order.
-      // Runs after the order row exists so a failed order never spends
-      // either credit; each redeem decrement is its own double-spend
-      // guard.
-      if (gc) await _redeemGiftCard(gc, createdOrder.id);
-      if (loy) await _redeemLoyalty(loy, loyaltyCustomerId, createdOrder.id);
+      // POST-COMMIT: the order row + its PaymentIntent already exist, so a
+      // redeem failure must NOT throw out of confirm — that would leave the
+      // cart un-converted (still `active`) while a live, charge-able
+      // PaymentIntent and order sit orphaned, and the conditional rollback
+      // above no longer fires (orderCreated is set). Each redeem is captured
+      // and reconciled instead (see _settleCreditPostCreate): the order is
+      // valid and the buyer pays the credit-reduced amount; a failed debit is
+      // surfaced for the operator to reconcile, never a stranded cart.
+      await _settleCreditPostCreate("giftcard", createdOrder.id, function () {
+        return gc ? _redeemGiftCard(gc, createdOrder.id) : null;
+      });
+      await _settleCreditPostCreate("loyalty", createdOrder.id, function () {
+        return loy ? _redeemLoyalty(loy, loyaltyCustomerId, createdOrder.id) : null;
+      });
       // Best-effort: record the auto-discount redemptions against the
       // placed order. Runs post-commit so a recording failure can't
       // reverse or fail an order whose PaymentIntent already exists.
@@ -1256,7 +1381,12 @@ function create(deps) {
           lines:               ppLines,
         });
         ppOrderCreated = true;
-        await _redeemGiftCard(gc, paidOrder.id);
+        // Same settlement posture as the Stripe branches: the order exists,
+        // so a redeem failure is captured and reconciled, never allowed to
+        // strand the cart un-converted.
+        await _settleCreditPostCreate("giftcard", paidOrder.id, function () {
+          return _redeemGiftCard(gc, paidOrder.id);
+        });
         await cart.setStatus(quote.cart_id, "converted");
         var settled = await order.transition(paidOrder.id, "mark_paid", { reason: "gift_card:full" });
         return { order: settled, paypal_order_id: null, status: "PAID_BY_GIFT_CARD", gift_card: { applied_minor: gc.applied_minor, amount_due_minor: 0 } };
@@ -1285,7 +1415,14 @@ function create(deps) {
         lines:               ppLines,
       });
       ppOrderCreated = true;
-      if (gc) await _redeemGiftCard(gc, createdOrder.id);
+      // Post-commit gift-card burn — captured, never stranding. The order row
+      // + the PayPal order already exist; a redeem throw must not bubble to
+      // the outer catch (which re-throws and would leave the cart active with
+      // an orphaned PayPal order). The buyer pays the credit-reduced PayPal
+      // amount; a failed debit is surfaced for reconciliation.
+      await _settleCreditPostCreate("giftcard", createdOrder.id, function () {
+        return gc ? _redeemGiftCard(gc, createdOrder.id) : null;
+      });
       await cart.setStatus(quote.cart_id, "converted");
       return { order: createdOrder, paypal_order_id: ppOrder.id, status: ppOrder.status, gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: amountDue } : null };
       } catch (e) {

package/lib/click-and-collect.js

@@ -574,24 +574,39 @@ function create(opts) {
         [input.picked_up_at, sigHash, proofKind, now, orderId],
       );
 
-      // Drive the parent order FSM to delivered. The transition is
-      // guarded — an already-delivered order surfaces as
-      // `fsm/illegal-transition` and we swallow it so a double
-      // markPickedUp (idempotent at the schedule layer) doesn't
-      // spuriously fail at the order layer. Other refusal codes
-      // surface to the caller.
+      // Drive the parent order FSM to `delivered` so the order really
+      // reaches its terminal state when the goods leave the store.
+      //
+      // A pickup order is normally `paid` (or `fulfilling`, if the picker
+      // started staging) when the customer collects — for which the order
+      // FSM's BOPIS edge `mark_picked_up` goes straight to `delivered` (an
+      // in-store collection has no carrier ship leg). If the operator
+      // already shipped the order through the standard flow, `mark_picked_up`
+      // is illegal from `shipped`, so we fall back to the standard
+      // `mark_delivered` edge. If BOTH are illegal the order is already
+      // `delivered` (or otherwise terminal) — a double markPickedUp is
+      // idempotent at the schedule layer, so the order-layer no-op is
+      // expected and swallowed. Any non-FSM-refusal error still surfaces.
+      var pickupMeta = {
+        reason:   "click_and_collect_picked_up",
+        metadata: {
+          location_code: schedule.location_code,
+          picked_up_at:  input.picked_up_at,
+        },
+      };
       if (orderPrim) {
         try {
-          await orderPrim.transition(orderId, "mark_delivered", {
-            reason:   "click_and_collect_picked_up",
-            metadata: {
-              location_code: schedule.location_code,
-              picked_up_at:  input.picked_up_at,
-            },
-          });
+          await orderPrim.transition(orderId, "mark_picked_up", pickupMeta);
         } catch (e) {
-          var code = e && e.code;
-          if (code !== "fsm/illegal-transition") throw e;
+          if ((e && e.code) !== "fsm/illegal-transition") throw e;
+          // Not legal from the order's current state — try the standard
+          // ship→deliver edge (operator already shipped it), then treat an
+          // already-terminal order as the idempotent no-op it is.
+          try {
+            await orderPrim.transition(orderId, "mark_delivered", pickupMeta);
+          } catch (e2) {
+            if ((e2 && e2.code) !== "fsm/illegal-transition") throw e2;
+          }
         }
       }
       return await _getScheduleByOrder(orderId);

package/lib/giftcards.js

@@ -346,6 +346,66 @@ function create(opts) {
       };
     },
 
+    // Credit a card's spend back when the order that redeemed it never
+    // completed (abandoned / cancelled / refunded). `redeem` debited the
+    // card row's balance at checkout; if the order dies, that money must
+    // return to the card or the customer's balance is silently gone.
+    //
+    // Keyed on the ORDER id — the order FSM drives this on its cancel /
+    // refund edges (the same transitions that release inventory holds), so
+    // reversal is transition-driven, not a separate operator action. Every
+    // unreversed redemption against the order is restored.
+    //
+    // Idempotent + concurrency-safe: each redemption is claimed with
+    // `WHERE id = ? AND reversed_at IS NULL` and the rowCount checked, so a
+    // double-fire (the stale-order reaper racing a payment-failed webhook,
+    // or a re-delivered cancel) credits the balance back exactly once. The
+    // balance restore is itself bounded by the card's issued_minor CHECK, so
+    // it can never push the card above its original face value. A card that
+    // had drained to `redeemed` is reactivated since it now carries balance
+    // again. Returns the list of reversed redemptions (empty when there was
+    // nothing to reverse — an order that used no gift card, or one already
+    // fully reversed).
+    reverseRedemption: async function (orderId) {
+      _uuid(orderId, "order_id");
+      var rows = (await query(
+        "SELECT id, giftcard_id, amount_minor FROM giftcard_redemptions " +
+        "WHERE order_id = ?1 AND reversed_at IS NULL",
+        [orderId],
+      )).rows;
+      var reversed = [];
+      for (var i = 0; i < rows.length; i += 1) {
+        var red = rows[i];
+        var ts = _now();
+        // Claim the redemption first — the unreversed predicate is the
+        // serialization point so two concurrent reversals can't both credit.
+        var claim = await query(
+          "UPDATE giftcard_redemptions SET reversed_at = ?1 WHERE id = ?2 AND reversed_at IS NULL",
+          [ts, red.id],
+        );
+        if (Number(claim.rowCount || 0) === 0) continue;   // lost the claim
+        // Restore the spendable balance on the card row. Capped at the card's
+        // issued_minor by the schema CHECK; the amount restored is exactly
+        // what this redemption debited, so it can't exceed the face value.
+        // Reactivate a card that had drained to `redeemed` — it carries
+        // balance again. A `voided`/`expired` card stays in its terminal
+        // status (the balance is restored on the row for reconciliation, but
+        // a voided/expired card isn't spendable regardless).
+        await query(
+          "UPDATE giftcards SET balance_minor = balance_minor + ?1, " +
+          "status = CASE WHEN status = 'redeemed' THEN 'active' ELSE status END, " +
+          "updated_at = ?2 WHERE id = ?3",
+          [red.amount_minor, ts, red.giftcard_id],
+        );
+        reversed.push({
+          redemption_id: red.id,
+          gift_card_id:  red.giftcard_id,
+          amount_minor:  red.amount_minor,
+        });
+      }
+      return reversed;
+    },
+
     "void": async function (id, opts2) {
       opts2 = opts2 || {};
       _uuid(id, "giftcard id");

package/lib/order.js

@@ -58,6 +58,25 @@ var ORDER_TRANSITIONS = Object.freeze([
   { from: "delivered",  to: "refunded",   on: "refund",            label: "Refund" },
 ]);
 
+// Pickup (BOPIS) edges. An in-store collection has no carrier ship leg:
+// the goods sit on the hold shelf and the customer walks in. So a pickup
+// order goes straight from `paid` (or `fulfilling`, if the picker started
+// staging) to `delivered` on a single `mark_picked_up` event — driving it
+// through mark_shipped would record a carrier handoff that never happened.
+// These edges are kept OUT of ORDER_TRANSITIONS (and therefore out of
+// transitionsFrom) so the operator order-detail page doesn't sprout a
+// "mark picked up" button on every paid order — the click-and-collect
+// primitive fires the event when the front-counter operator captures the
+// pickup. They ARE merged into the FSM definition below so the transition
+// is legal: previously markPickedUp tried `mark_delivered` from `paid`,
+// which the FSM refused (delivered is only reachable from shipped) and the
+// caller swallowed — leaving the pickup schedule `picked_up` while the
+// parent order stayed stuck at paid/fulfilling.
+var PICKUP_TRANSITIONS = Object.freeze([
+  { from: "paid",       to: "delivered",  on: "mark_picked_up" },
+  { from: "fulfilling", to: "delivered",  on: "mark_picked_up" },
+]);
+
 function _getOrderFsm() {
   if (_orderFsm) return _orderFsm;
   // b.fsm emits audit events under the 'fsm' namespace —
@@ -76,7 +95,7 @@ function _getOrderFsm() {
       refunded:   {},
       cancelled:  {},
     },
-    transitions: ORDER_TRANSITIONS.map(function (t) {
+    transitions: ORDER_TRANSITIONS.concat(PICKUP_TRANSITIONS).map(function (t) {
       return { from: t.from, to: t.to, on: t.on };
     }),
   });
@@ -217,6 +236,28 @@ function create(opts) {
   // settlement failures still surface to the audit sink (b.audit.safeEmit
   // below), just not the durable error feed.
   var errorLog = opts.errorLog || null;
+  // Optional gift-card handle — when present, the order FSM credits a
+  // gift-card spend back when the order dies without completing. A checkout
+  // that partially covers payment with a gift card debits the card's balance
+  // at confirm; if the order is then cancelled (the stale-pending reaper, an
+  // explicit cancel) or refunded (a payment-failed / refund webhook), that
+  // debit must return to the card or the customer's balance is silently
+  // burned. This mirrors the inventory-hold release: it's transition-driven
+  // on the same cancel / refund edges, runs synchronously before the
+  // fire-and-forget fan-outs, and is idempotent (reverseRedemption claims
+  // each redemption with an unreversed predicate) so a re-delivered webhook
+  // can't double-credit. Opt-in like the other handles; absent it, an
+  // unwired deploy (or a test with no gift cards) runs unchanged.
+  var giftCards = opts.giftCards || null;
+  if (giftCards && typeof giftCards.reverseRedemption !== "function") {
+    throw new TypeError("order.create: opts.giftCards must expose a reverseRedemption(order_id) method");
+  }
+  // Optional gift-card ledger handle — when present alongside giftCards, a
+  // reversal also writes a refund_to_giftcard credit so the append-only
+  // ledger history records the money returning to the card (the card row's
+  // balance is authoritative; the ledger is the audit trail surfaced in the
+  // admin console).
+  var giftCardLedger = opts.giftCardLedger || null;
   // Pagination cursors for listForCustomer are HMAC-tagged via
   // b.pagination so an operator can't hand-craft one to skip past a
   // hidden order or replay across deployments. The secret defaults
@@ -273,6 +314,60 @@ function create(opts) {
     }
   }
 
+  // Credit back any gift-card spend on an order that died without
+  // completing — the cancel / refund edge releasing the customer's money,
+  // mirroring how _settleSku releases an inventory hold. reverseRedemption
+  // is idempotent (each redemption claimed with an unreversed predicate), so
+  // a re-delivered webhook or the reaper racing the cancel can't double-
+  // credit. For each restored redemption a refund_to_giftcard ledger credit
+  // is written when the ledger is wired so the audit trail records the money
+  // returning.
+  //
+  // drop-silent-with-capture — same discipline as _settleSku: the cancel /
+  // refund has already persisted and the webhook driving it MUST return 2xx,
+  // so a reversal failure is caught, NOT re-thrown, and surfaced loudly (an
+  // `order.giftcard.reversal.error` audit event plus, when the error-log
+  // handle is wired, a durable /admin/errors row) for manual reconciliation.
+  async function _settleGiftCards(orderId) {
+    if (!giftCards) return;
+    try {
+      var reversed = await giftCards.reverseRedemption(orderId);
+      if (giftCardLedger && typeof giftCardLedger.credit === "function") {
+        for (var i = 0; i < reversed.length; i += 1) {
+          var rev = reversed[i];
+          try {
+            // allow:money-binding-currency-without-catalog-check — this is a REVERSAL credit of an existing redemption: it replays the exact amount already debited from an already-issued card (whose currency was ISO-4217-validated at giftcards.issue time). No currency is supplied or chosen here — the ledger credit carries no currency field; it inherits the card's. There is no new currency surface to catalog-check.
+            await giftCardLedger.credit({
+              gift_card_id: rev.gift_card_id,
+              amount_minor: rev.amount_minor,
+              source:       "refund_to_giftcard",
+              source_ref:   orderId,
+            });
+          } catch (_ledgerErr) { /* drop-silent — the card-row balance restore above is authoritative; the ledger credit is the audit trail */ }
+        }
+      }
+    } catch (e) {
+      var message = "order.giftcard-reversal failed — order=" + orderId + ": " + (e && e.message || e);
+      try {
+        b.audit.safeEmit({
+          action:   "order.giftcard.reversal.error",
+          outcome:  "failure",
+          metadata: { order_id: orderId, message: (e && e.message) || String(e) },
+        });
+      } catch (_auditErr) { /* drop-silent — the capture below is the durable record */ }
+      if (errorLog && typeof errorLog.captureServerError === "function") {
+        try {
+          await errorLog.captureServerError({
+            route:   "/order/" + orderId + "/giftcard-reversal",
+            method:  "POST",
+            status:  500,
+            message: message,
+          });
+        } catch (_logErr) { /* drop-silent — never let the error-feed write mask the original failure */ }
+      }
+    }
+  }
+
   return {
     TERMINAL_STATES: TERMINAL_STATES,
 
@@ -477,6 +572,21 @@ function create(opts) {
           }
         }
       }
+      // Gift-card settlement — SYNCHRONOUS, alongside the inventory release.
+      // An order that reaches a terminal state WITHOUT completing the sale
+      // (cancelled — pending-abandon or post-paid; refunded — payment failed
+      // or a refund issued) must return any gift-card spend to the card.
+      // Unlike inventory (where a refund deliberately doesn't auto-restock a
+      // physical good), the gift-card credit is the customer's own money, so
+      // it's released on every death edge. reverseRedemption is idempotent,
+      // so a re-delivered webhook or the reaper racing a cancel credits back
+      // exactly once. Drop-silent-with-capture (see _settleGiftCards): the
+      // transition has already persisted and the webhook must return 2xx, so
+      // a reversal failure surfaces loudly for reconciliation rather than
+      // 500ing the request.
+      if (result.to === "cancelled" || result.to === "refunded") {
+        await _settleGiftCards(orderId);
+      }
       // Fan-out to merchant webhook subscribers is fire-and-forget. The
       // transition has already persisted; the request must not wait on
       // outbound HTTP, or a slow / unreachable endpoint would block the

package/lib/returns.js

@@ -376,21 +376,61 @@ function create(opts) {
       var refundedAt    = _epochOrNull(input.refunded_at, "refunded_at");
       var operatorNotes = _boundedString(input.operator_notes, "operator_notes", MAX_NOTE_LEN);
 
-      var current = await this._currentStatus(rmaId);
-      _assertTransition(current, "refund");
-
       var ts = _now();
       var rfAt = refundedAt == null ? ts : refundedAt;
-      await query(
+      // Atomic claim: the `AND status = 'received'` predicate is the
+      // serialization point. Two concurrent refund POSTs (an operator
+      // double-click, two operators on the same RMA) both read 'received'
+      // up the stack, but on D1 a single UPDATE is atomic — exactly one
+      // matches the row and writes 'refunded'; the loser matches zero rows
+      // and is refused. Without this the read-then-write let both pass and
+      // both moved the RMA to refunded (and, on the provider-backed path,
+      // both issued a refund). A zero-row result distinguishes "already
+      // refunded / not received" — surfaced as RMA_TRANSITION_REFUSED so
+      // the request layer maps it to 409, the same shape the prior
+      // _assertTransition refusal produced.
+      var upd = await query(
         "UPDATE return_authorizations SET status = 'refunded', " +
         "refunded_at = ?1, " +
         "operator_notes = CASE WHEN ?2 = '' THEN operator_notes ELSE ?2 END, " +
-        "updated_at = ?3 WHERE id = ?4",
+        "updated_at = ?3 WHERE id = ?4 AND status = 'received'",
         [rfAt, operatorNotes, ts, rmaId],
       );
+      if (Number(upd.rowCount || 0) === 0) {
+        // Either the RMA doesn't exist or it isn't in 'received'. Read the
+        // current status to surface the right typed refusal (RMA_NOT_FOUND
+        // vs RMA_TRANSITION_REFUSED) so the caller's mapping is unchanged.
+        var current = await this._currentStatus(rmaId);
+        _assertTransition(current, "refund");
+        // _assertTransition throws for any non-'received' state; reaching
+        // here means the RMA was 'received' a moment ago but a concurrent
+        // claim won the row first. Refuse with the transition-refused shape.
+        var raced = new Error("returns: refund already claimed for rma " + rmaId);
+        raced.code = "RMA_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await this.get(rmaId);
     },
 
+    // Revert a refund claim back to 'received'. The provider-backed refund
+    // flow claims the RMA (refund() above) BEFORE moving money so a
+    // concurrent racer is locked out; if the provider call then fails, the
+    // caller releases the claim so a retry can run. Atomic + self-targeting:
+    // the `AND status = 'refunded'` predicate makes a double-release (or a
+    // release of an RMA a webhook already advanced) a no-op, never an
+    // underflow. Returns true when the claim was released, false when there
+    // was nothing to release.
+    releaseRefundClaim: async function (rmaId) {
+      _uuid(rmaId, "rma id");
+      var ts = _now();
+      var upd = await query(
+        "UPDATE return_authorizations SET status = 'received', refunded_at = NULL, " +
+        "updated_at = ?1 WHERE id = ?2 AND status = 'refunded'",
+        [ts, rmaId],
+      );
+      return Number(upd.rowCount || 0) === 1;
+    },
+
     reject: async function (rmaId, input) {
       _uuid(rmaId, "rma id");
       if (!input || typeof input !== "object") {

package/lib/storefront.js

@@ -13999,6 +13999,16 @@ function mount(router, deps) {
         // fat-fingered value re-prompts rather than 500-ing checkout.
         var code = (e && typeof e.code === "string") ? e.code : "";
         var msg = (e && e.message) || "checkout failed";
+        // Lost the single-charge claim: another POST for this cart (a double-
+        // click / second tab) is already converting it. The winner created
+        // (or is creating) the one order; bounce this loser to the cart so it
+        // can't start a second checkout. The winner's redirect carries the
+        // shopper to /pay or /orders — this branch just refuses the duplicate.
+        if (code === "CHECKOUT_IN_PROGRESS") {
+          res.status(303);
+          res.setHeader && res.setHeader("location", "/cart");
+          return res.end ? res.end() : res.send("");
+        }
         // A coded gift-card / loyalty / out-of-stock error is something the
         // shopper can fix in place — re-render the checkout form with the
         // message inline (preserving the cart + their prefilled fields where
@@ -17968,6 +17978,18 @@ function mount(router, deps) {
         var auth = _returnsAuth(req, res); if (!auth) return;
         var order = await _ownedOrder(req, res, auth); if (!order) return;
         var cartCount = await _cartCountForReq(req);
+        // An ineligible order (unpaid, cancelled, or already refunded) never
+        // gets the open-return form — the same window the return button is
+        // gated on. Without this the form renders on, say, a refunded order
+        // and the POST below would mint an RMA the operator could then refund
+        // a SECOND time through the provider.
+        if (!_orderEligibleForReturn(order.status)) {
+          return _send(res, 400, renderReturnForm({
+            order: order, lines: order.lines || [],
+            notice: "This order isn't eligible for a return.",
+            shop_name: shopName, cart_count: cartCount,
+          }));
+        }
         _send(res, 200, renderReturnForm({ order: order, lines: order.lines || [], shop_name: shopName, cart_count: cartCount }));
       });
 
@@ -17976,6 +17998,21 @@ function mount(router, deps) {
         var order = await _ownedOrder(req, res, auth); if (!order) return;
         var body = req.body || {};
         var cartCount = await _cartCountForReq(req);
+        // Server-side eligibility gate — the load-bearing check. A return is
+        // only openable while the goods are in the customer's hands and paid
+        // for (paid / fulfilling / shipped / delivered); an unpaid pending
+        // order, a cancelled one, or an already-refunded one is refused. The
+        // form/button gate on the same predicate, but a forged direct POST —
+        // or an order that changed state between the GET and this POST — must
+        // not slip an RMA onto an ineligible order (which would enable a
+        // second provider refund downstream).
+        if (!_orderEligibleForReturn(order.status)) {
+          return _send(res, 400, renderReturnForm({
+            order: order, lines: order.lines || [],
+            notice: "This order isn't eligible for a return.",
+            shop_name: shopName, cart_count: cartCount,
+          }));
+        }
         // Build the return lines from the order's own lines (authoritative
         // sku/qty), keyed by the checkboxes the customer ticked — never
         // trust a client-supplied sku.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {