@blamejs/blamejs-shop 0.4.27 → 0.4.29

package/lib/payment.js

@@ -438,12 +438,43 @@ async function _runIdempotent(state, operation, key, requestObj, doCall) {
     ? result._stripeRawText
     : JSON.stringify(result);
 
-  await query(
+  // Atomic claim: two concurrent same-key calls both miss the lookup above
+  // and both reach here — ON CONFLICT DO NOTHING lets exactly one cache its
+  // response while the loser defers to the winner's row instead of dying on
+  // the PRIMARY KEY violation. Never OR REPLACE / DO UPDATE: the loser must
+  // not overwrite the winner's cached response, and a same-key racer with a
+  // DIFFERENT body must still hit the collision refusal below.
+  var ins = await query(
     "INSERT INTO payment_idempotency " +
     "(idempotency_key, operation, request_hash, response_status, response_body, created_at, expires_at) " +
-    "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
+    "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7) " +
+    "ON CONFLICT(idempotency_key) DO NOTHING",
     [key, operation, requestHash, status, rawText, now, now + IDEMPOTENCY_TTL_MS],
   );
+  var changes = ins && (ins.rowCount != null ? ins.rowCount
+    : (ins.meta && ins.meta.changes != null ? ins.meta.changes : ins.changes));
+  if (Number(changes || 0) === 0) {
+    // A concurrent call claimed the key first. Replay its cached row —
+    // unless our request body differs, which is the same collision the
+    // up-front check refuses.
+    var winner = (await query(
+      "SELECT request_hash, response_status, response_body " +
+      "FROM payment_idempotency WHERE idempotency_key = ?1 LIMIT 1",
+      [key],
+    )).rows[0];
+    if (winner && winner.request_hash !== requestHash) {
+      throw new TypeError("payment: idempotency_key collision (different inputs)");
+    }
+    if (winner) {
+      var winnerReplay = null;
+      try { winnerReplay = JSON.parse(winner.response_body); } catch (_e) { winnerReplay = { _raw: winner.response_body }; }
+      Object.defineProperty(winnerReplay, "_stripeStatus", { value: Number(winner.response_status), enumerable: false });
+      Object.defineProperty(winnerReplay, "_replayed",     { value: true,                            enumerable: false });
+      return winnerReplay;
+    }
+    // Conflicted but the row vanished (TTL purge between the two
+    // statements) — fall through: our own result is still the outcome.
+  }
 
   return result;
 }
@@ -784,6 +815,32 @@ function _minorToDecimalString(minor, currency) {
   return (neg ? "-" : "") + s.slice(0, s.length - dec) + "." + s.slice(s.length - dec);
 }
 
+// Inverse of _minorToDecimalString: parse a PayPal decimal amount string
+// (e.g. webhook `resource.amount.value`) into exact integer minor units,
+// using the same zero-decimal currency table. STRICT — money parsed off an
+// inbound webhook decides refund accounting, so a malformed shape throws a
+// TypeError rather than guessing (the caller maps that to a 5xx so the
+// processor re-delivers; a guessed amount would silently mis-credit). Pure
+// digit-string arithmetic — the value never passes through a float.
+function _decimalToMinor(value, currency) {
+  if (typeof currency !== "string" || !/^[A-Z]{3}$/.test(currency)) {
+    throw new TypeError("payment: decimal amount currency must be a 3-letter uppercase ISO 4217 code");
+  }
+  if (typeof value !== "string" || !/^\d{1,15}(\.\d{1,2})?$/.test(value)) {
+    throw new TypeError("payment: decimal amount must be a plain non-negative decimal string (got " + JSON.stringify(value) + ")");
+  }
+  var dec   = PAYPAL_ZERO_DECIMAL[currency] ? 0 : 2;
+  var parts = value.split(".");
+  var frac  = parts[1] || "";
+  if (frac.length > dec) {
+    // More fractional digits than the currency carries (e.g. "100.50" JPY)
+    // is a garbled amount, not a roundable one — refuse, never round money.
+    throw new TypeError("payment: decimal amount " + JSON.stringify(value) + " has more fractional digits than " + currency + " allows");
+  }
+  while (frac.length < dec) frac += "0";
+  return parseInt(parts[0] + frac, 10);
+}
+
 function _headerCI(headers, name) {
   if (!headers) return undefined;
   if (headers[name] != null) return headers[name];
@@ -833,7 +890,13 @@ async function _paypalToken(opts, state) {
   return state.token;
 }
 
-async function _paypalCall(opts, state, method, path, bodyObj, requestId) {
+// `breaker` selects which circuit the dial rides — every payment call rides
+// the adapter's main `opts._breaker`; the webhook-verification dial rides its
+// own (see verifyWebhook) so attacker-shaped verification traffic can't trip
+// the circuit live checkouts depend on. The token exchange inside always
+// rides the main breaker: its failures are credential/PayPal-health signals,
+// not attacker-controllable per-request outcomes.
+async function _paypalCall(opts, state, method, path, bodyObj, requestId, breaker) {
   var token = await _paypalToken(opts, state);
   var headers = {
     "authorization": "Bearer " + token,
@@ -855,7 +918,7 @@ async function _paypalCall(opts, state, method, path, bodyObj, requestId) {
   // same id rides every retry attempt within one call). A keyless write
   // rides the breaker but not the retry.
   var idempotent = method === "GET" || !!requestId;
-  var json = await _dial(opts._breaker, idempotent, async function () {
+  var json = await _dial(breaker === undefined ? opts._breaker : breaker, idempotent, async function () {
     var res = await httpClient.request({
       method:       method,
       url:          _paypalApiBase(opts) + path,
@@ -898,6 +961,17 @@ function paypal(opts) {
   if (opts._breaker === undefined) {
     opts._breaker = opts.breaker === false ? null : _makeBreaker("psp-paypal");
   }
+  // SEPARATE breaker for the webhook-verification dial. The verify call's
+  // failure rate is attacker-influenceable: any header-complete spam POST to
+  // the (necessarily unauthenticated) webhook route triggers a
+  // verify-webhook-signature dial whose 4xx counts as a breaker failure —
+  // five consecutive spam posts would otherwise open the SAME circuit live
+  // checkout's createOrder/captureOrder ride and fast-fail real payments for
+  // the cooldown window. Verification failures say nothing about PayPal's
+  // health as a payments peer, so they account against their own circuit.
+  if (opts._verifyBreaker === undefined) {
+    opts._verifyBreaker = opts.breaker === false ? null : _makeBreaker("psp-paypal-verify");
+  }
 
   var state = {
     query:          opts.query || null,
@@ -923,8 +997,11 @@ function paypal(opts) {
     name: "paypal",
 
     // The per-adapter circuit breaker (or null when disabled). Same
-    // operator-dashboard surface as the Stripe adapter's.
-    breaker: opts._breaker,
+    // operator-dashboard surface as the Stripe adapter's. `verifyBreaker`
+    // is the webhook-verification dial's own circuit — kept separate so
+    // spam against the webhook route can't open the payment circuit.
+    breaker:       opts._breaker,
+    verifyBreaker: opts._verifyBreaker,
 
     // Create an Orders-v2 order (intent CAPTURE). The returned `id` is the
     // PayPal order id the buyer approves; `captureOrder` finalizes it.
@@ -1020,7 +1097,10 @@ function paypal(opts) {
         webhook_event:     event,
       };
       var res;
-      try { res = await _paypalCall(opts, state, "POST", "/v1/notifications/verify-webhook-signature", verifyBody, null); }
+      // Rides the verify-only breaker (opts._verifyBreaker), never the main
+      // payment circuit — see the factory comment: verification traffic is
+      // attacker-shaped and must not be able to fast-fail live checkouts.
+      try { res = await _paypalCall(opts, state, "POST", "/v1/notifications/verify-webhook-signature", verifyBody, null, opts._verifyBreaker); }
       catch (e) { return { ok: false, reason: "verify-call-failed", error: e && e.message }; }
       if (res && res.verification_status === "SUCCESS") return { ok: true, event: event };
       return { ok: false, reason: "verification-status-" + ((res && res.verification_status) || "unknown") };
@@ -1036,14 +1116,40 @@ function create(opts) {
   throw new TypeError("payment.create: unknown adapter " + JSON.stringify(opts.adapter) + " — 'stripe' and 'paypal' are supported");
 }
 
+// Boot-time PayPal configuration lint, called by the server entry point so
+// an incomplete env surfaces in the boot log instead of as a silent feature
+// gap. Returns an array of operator-actionable warning strings (empty when
+// nothing is wrong). Pure read of the supplied env map — never throws, never
+// changes behavior: webhook verification stays MANDATORY and fails closed
+// whether or not the operator saw the warning.
+function paypalConfigWarnings(env) {
+  env = env && typeof env === "object" ? env : {};
+  var warnings = [];
+  if (env.PAYPAL_CLIENT_ID && env.PAYPAL_SECRET && !env.PAYPAL_WEBHOOK_ID) {
+    warnings.push(
+      "PAYPAL_WEBHOOK_ID is not set: PayPal checkout is configured, but every " +
+      "/api/webhooks/paypal delivery will be refused (verification fails closed " +
+      "without the webhook id), so out-of-band captures and refunds will not " +
+      "reach the order ledger. Set PAYPAL_WEBHOOK_ID to the webhook id from the " +
+      "PayPal developer dashboard.");
+  }
+  return warnings;
+}
+
 module.exports = {
   create:                    create,
   stripe:                    stripe,
   paypal:                    paypal,
+  paypalConfigWarnings:      paypalConfigWarnings,
   STRIPE_WEBHOOK_TOLERANCE:  STRIPE_WEBHOOK_TOLERANCE,
   IDEMPOTENCY_TTL_MS:        IDEMPOTENCY_TTL_MS,
   // Exposed for tests + Worker to share form-encoding shape.
   _formEncode:               _formEncode,
   _verifyWebhook:            _verifyWebhook,
   _canonicalHash:            _canonicalHash,
+  // Exposed for the checkout webhook mirror + admin refund normalization —
+  // exact decimal-string ↔ minor-unit conversion sharing one zero-decimal
+  // currency table.
+  _decimalToMinor:           _decimalToMinor,
+  _minorToDecimalString:     _minorToDecimalString,
 };

package/lib/refund-automation.js

@@ -342,6 +342,11 @@ function create(opts) {
   var refundPolicyHandle  = opts.refundPolicy        || null;
   var returnsHandle       = opts.returns             || null;
   var paymentHandle       = opts.payment             || null;
+  // PayPal adapter — PayPal-captured orders refund against their CAPTURE id
+  // through this handle (executeAutoRefund routes by the request's
+  // `provider`). Absent, PayPal-provider requests are refused with a clear
+  // error instead of dialing Stripe with a PayPal id.
+  var paypalHandle        = opts.paypal              || null;
   var riskProfileHandle   = opts.customerRiskProfile || null;
 
   // Per-factory monotonic clock. Two decisions written against the
@@ -664,6 +669,28 @@ function create(opts) {
       }
       paymentIntent = input.payment_intent;
     }
+    // Which provider captured the order's charge — routes the refund dial.
+    // 'stripe' (default — the original surface) refunds the payment_intent
+    // through the `payment` handle; 'paypal' refunds the CAPTURE
+    // (`paypal_capture_id`, never the PayPal order id) through the `paypal`
+    // handle, with the amount named in `currency`. Validated up front so a
+    // request can never reach the wrong provider's API.
+    var provider = input.provider == null ? "stripe" : input.provider;
+    if (provider !== "stripe" && provider !== "paypal") {
+      throw new TypeError("refundAutomation.executeAutoRefund: provider must be 'stripe' or 'paypal'");
+    }
+    var paypalCaptureId = null;
+    var paypalCurrency  = null;
+    if (provider === "paypal") {
+      if (typeof input.paypal_capture_id !== "string" || !input.paypal_capture_id.length) {
+        throw new TypeError("refundAutomation.executeAutoRefund: paypal_capture_id required when provider is 'paypal'");
+      }
+      if (typeof input.currency !== "string" || !CURRENCY_RE.test(input.currency)) {
+        throw new TypeError("refundAutomation.executeAutoRefund: currency (ISO 4217 alpha) required when provider is 'paypal'");
+      }
+      paypalCaptureId = input.paypal_capture_id;
+      paypalCurrency  = input.currency;
+    }
 
     var verdict = await evaluateForRefundRequest({
       order_id:             orderId,
@@ -685,20 +712,36 @@ function create(opts) {
       [id, orderId, customerId, verdict.applied_rule, amount, reason, ts],
     );
 
-    // Compose payment.refund when wired. The handle's exact shape
-    // mirrors the framework's payment primitive (`{ payment_intent,
-    // amount_minor, reason, metadata }`). Absent a handle the
-    // primitive still records the decision so the operator can
-    // drive the actual refund out-of-band.
+    // Compose the provider refund when the matching handle is wired,
+    // routed by `provider`. Absent the matching handle the primitive still
+    // records the decision so the operator can drive the actual refund
+    // out-of-band — EXCEPT a PayPal request with no PayPal handle, which is
+    // refused up front (falling through to the Stripe handle would dial
+    // Stripe with PayPal identifiers). The decision row above is already
+    // written either way, mirroring the decision-before-payment ordering.
     var paymentResult = null;
-    if (paymentHandle && typeof paymentHandle.refund === "function") {
+    if (provider === "paypal") {
+      if (paypalHandle && typeof paypalHandle.refund === "function") {
+        // Each auto-refund decision is its own refund — the decision id as
+        // the idempotency key keeps a retry of THIS decision deduplicated at
+        // PayPal (the adapter folds it into the PayPal-Request-Id) while two
+        // distinct decisions on the same capture stay distinct refunds.
+        paymentResult = await paypalHandle.refund({
+          capture_id:   paypalCaptureId,
+          amount_minor: amount,
+          currency:     paypalCurrency,
+        }, "auto-refund:" + id);
+      } else if (paymentHandle) {
+        throw new TypeError("refundAutomation.executeAutoRefund: provider is 'paypal' but no paypal handle is wired — refusing to refund PayPal identifiers through the Stripe handle");
+      }
+    } else if (paymentHandle && typeof paymentHandle.refund === "function") {
       var refundInput = {
         amount_minor: amount,
         reason:       reason,
         metadata:     { order_id: orderId, customer_id: customerId, applied_rule: verdict.applied_rule },
       };
       if (paymentIntent != null) refundInput.payment_intent = paymentIntent;
-      paymentResult = await paymentHandle.refund(refundInput);
+      paymentResult = await paymentHandle.refund(refundInput, "auto-refund:" + id);
     }
 
     return {

package/lib/security-middleware.js

@@ -77,6 +77,14 @@ var WEBHOOK_PATHS = [
 // could wedge the health signal.
 var HEALTH_PATH = "/_/health";
 
+// Per-client-IP budget on POST /api/webhooks/paypal (see the limiter in
+// mountRouteGuards). Generous against PayPal's real delivery cadence —
+// redelivery is ~25 attempts per event spread over days, so even a
+// post-downtime backlog flush of distinct events sits far under this —
+// while bounding how many verify-webhook-signature dials a spammer can
+// force per minute.
+var PAYPAL_WEBHOOK_BUDGET_PER_MINUTE = 120;
+
 // Worker→container internal endpoints — machine-to-machine POSTs over
 // the Cloudflare service binding (cron ticks + the InventoryLock DO's
 // low-stock event), each authenticated FIRST thing in its handler by a
@@ -745,6 +753,36 @@ function mountRouteGuards(r) {
       return clientKey(req) + "|" + (req.pathname || req.url || "/");
     },
   });
+  // --- PayPal webhook per-IP budget -----------------------------------
+  //
+  // The webhook paths are exempt from the global + tight limiters above
+  // (a processor's server-to-server POST is unthrottleable by a human
+  // budget), but /api/webhooks/paypal is uniquely expensive to probe:
+  // verification is a server-to-server dial to PayPal's
+  // verify-webhook-signature API, so every header-complete spam POST costs
+  // an outbound request. The adapter's verify dial rides its own circuit
+  // (never the payment circuit — lib/payment.js), so spam can't fast-fail
+  // checkouts; this budget bounds the outbound dial volume itself. Sized
+  // for PayPal's real delivery shape: legitimate redelivery after downtime
+  // is ~25 attempts per event spread over days, so even a backlog flush of
+  // many distinct events sits far under this per-minute ceiling — and a
+  // clipped delivery is never lost: the limiter answers 429, PayPal treats
+  // any non-2xx as retry-later and redelivers. Stripe's webhook keeps no
+  // budget — its verification is a local HMAC (no dial to amplify).
+  var PAYPAL_WEBHOOK_PATH = "/api/webhooks/paypal";
+  var paypalWebhookLimiter = b.middleware.rateLimit({
+    backend:   "memory",
+    algorithm: "fixed-window",
+    max:       PAYPAL_WEBHOOK_BUDGET_PER_MINUTE,
+    windowMs:  C.TIME.minutes(1),
+    keyFn:     clientKey,
+  });
+  r.use(function paypalWebhookRateGuard(req, res, next) {
+    var pathname = req.pathname || req.url || "/";
+    if (pathname !== PAYPAL_WEBHOOK_PATH) return next();
+    return paypalWebhookLimiter(req, res, next);
+  });
+
   r.use(function tightRateGuard(req, res, next) {
     var pathname = req.pathname || req.url || "/";
     // Never throttle the webhook or health paths.
@@ -781,6 +819,7 @@ module.exports = {
   CSP_HOSTS:            CSP_HOSTS,
   WEBHOOK_PATHS:        WEBHOOK_PATHS,
   HEALTH_PATH:          HEALTH_PATH,
+  PAYPAL_WEBHOOK_BUDGET_PER_MINUTE: PAYPAL_WEBHOOK_BUDGET_PER_MINUTE,
   TIGHT_PREFIXES:       TIGHT_PREFIXES,
   EDGE_POST_PATHS:      EDGE_POST_PATHS,
   PUBLIC_WELL_KNOWN_PATHS: PUBLIC_WELL_KNOWN_PATHS,

package/lib/store-credit.js

@@ -146,16 +146,17 @@ function create(opts) {
     query = function (sql, params) { return b.externalDb.query(sql, params); };
   }
 
-  // O(1) current-balance read: the latest row by `occurred_at DESC`
-  // holds `balance_after_minor` as the denormalized snapshot. No SUM
+  // O(1) current-balance read: the latest row by `occurred_at DESC, id
+  // DESC` holds `balance_after_minor` as the denormalized snapshot. No SUM
   // aggregation at read time. Falls through to 0 when no rows exist
-  // (a customer that has never had a ledger row has zero credit).
-  // Returns both the snapshot and the occurred_at so the write path
-  // can guarantee strict monotonicity (see `_resolveOccurredAt`).
+  // (a customer that has never had a ledger row has zero credit). The id
+  // tie-break keeps any legacy same-millisecond rows deterministic; new
+  // writes can't tie — _writeRowAtomic computes a strictly-monotonic
+  // per-customer occurred_at inside the INSERT itself.
   async function _readLatest(customerId) {
     var r = await query(
       "SELECT balance_after_minor, occurred_at FROM store_credit_ledger " +
-      "WHERE customer_id = ?1 ORDER BY occurred_at DESC LIMIT 1",
+      "WHERE customer_id = ?1 ORDER BY occurred_at DESC, id DESC LIMIT 1",
       [customerId],
     );
     if (!r.rows.length) return { balance: 0, occurred_at: null };
@@ -167,27 +168,62 @@ function create(opts) {
     return latest.balance;
   }
 
-  // Two writes against the same customer in the same millisecond
-  // would tie on `occurred_at` and make the "latest row" ambiguous.
-  // Bump the requested timestamp to `prior + 1` when it would
-  // collide (or land older than the prior row, which an
-  // out-of-order operator write could trigger). The result is a
-  // strictly-monotonic per-customer `occurred_at` sequence.
-  function _resolveOccurredAt(requestedTs, latestTs) {
-    if (latestTs == null) return requestedTs;
-    if (requestedTs > latestTs) return requestedTs;
-    return latestTs + 1;
-  }
-
-  async function _writeRow(customerId, kind, amountMinor, source, sourceRef, orderId, balanceAfter, expiresAt, ts) {
+  // Single-statement guarded write — the concurrency spine of the wallet.
+  // The live balance AND the strictly-monotonic per-customer occurred_at
+  // are computed by correlated subqueries INSIDE the INSERT, so two
+  // concurrent writes can never base off the same stale snapshot: the
+  // statements serialize at the database and the second sees the first's
+  // row. (A JS-side read-then-write here double-fulfilled concurrent
+  // debits and silently dropped one of two same-millisecond credits.)
+  // `kind` selects the guard + arithmetic:
+  //   credit — balance_after = live + amount, no balance gate (the in-SQL
+  //            occurred_at is what closes the same-millisecond tie);
+  //   debit  — balance_after = live - amount, gated on live >= amount
+  //            (zero rows = insufficient, or lost the race — same refusal);
+  //   expire — burns MIN(amount, live), gated on live > 0 (zero rows =
+  //            wallet already empty; callers degrade gracefully — by
+  //            design, never a throw).
+  // Returns the written row's resolved values, or null when the guard
+  // refused the write.
+  async function _writeRowAtomic(kind, customerId, amount, source, sourceRef, orderId, expiresAt, requestedTs) {
     var id = b.uuid.v7();
-    await query(
+    var balSub = "COALESCE((SELECT balance_after_minor FROM store_credit_ledger " +
+                 "WHERE customer_id = ?2 ORDER BY occurred_at DESC, id DESC LIMIT 1), 0)";
+    var tsSub  = "COALESCE((SELECT occurred_at FROM store_credit_ledger " +
+                 "WHERE customer_id = ?2 ORDER BY occurred_at DESC, id DESC LIMIT 1), 0)";
+    var tsExpr = "CASE WHEN ?8 > " + tsSub + " THEN ?8 ELSE " + tsSub + " + 1 END";
+    var amountExpr, afterExpr, guard;
+    if (kind === "credit") {
+      amountExpr = "?3";
+      afterExpr  = balSub + " + ?3";
+      guard      = "1";
+    } else if (kind === "debit") {
+      amountExpr = "?3";
+      afterExpr  = balSub + " - ?3";
+      guard      = balSub + " >= ?3";
+    } else {            // expire — burn MIN(amount, live balance)
+      amountExpr = "CASE WHEN " + balSub + " < ?3 THEN " + balSub + " ELSE ?3 END";
+      afterExpr  = "CASE WHEN " + balSub + " < ?3 THEN 0 ELSE " + balSub + " - ?3 END";
+      guard      = balSub + " > 0";
+    }
+    var res = await query(
       "INSERT INTO store_credit_ledger " +
       "(id, customer_id, kind, amount_minor, source, source_ref, order_id, balance_after_minor, expires_at, occurred_at) " +
-      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)",
-      [id, customerId, kind, amountMinor, source, sourceRef, orderId, balanceAfter, expiresAt, ts],
+      "SELECT ?1, ?2, ?9, " + amountExpr + ", ?4, ?5, ?6, " + afterExpr + ", ?7, " + tsExpr + " " +
+      "WHERE " + guard,
+      [id, customerId, amount, source, sourceRef, orderId, expiresAt, requestedTs, kind],
     );
-    return id;
+    if (Number(res.rowCount || 0) === 0) return null;
+    var row = (await query(
+      "SELECT amount_minor, balance_after_minor, occurred_at FROM store_credit_ledger WHERE id = ?1",
+      [id],
+    )).rows[0];
+    return {
+      id:                  id,
+      amount_minor:        row.amount_minor,
+      balance_after_minor: row.balance_after_minor,
+      occurred_at:         row.occurred_at,
+    };
   }
 
   return {
@@ -206,21 +242,18 @@ function create(opts) {
       var requested  = _epochMs(input.occurred_at, "occurred_at");
       if (requested == null) requested = _now();
 
-      var latest = await _readLatest(customerId);
-      var ts     = _resolveOccurredAt(requested, latest.occurred_at);
-      var after  = latest.balance + amount;
-      var id = await _writeRow(customerId, "credit", amount, source, sourceRef, null, after, expiresAt, ts);
+      var w = await _writeRowAtomic("credit", customerId, amount, source, sourceRef, null, expiresAt, requested);
 
       return {
-        id:                  id,
+        id:                  w.id,
         customer_id:         customerId,
         kind:                "credit",
         amount_minor:        amount,
         source:              source,
         source_ref:          sourceRef,
         expires_at:          expiresAt,
-        balance_after_minor: after,
-        occurred_at:         ts,
+        balance_after_minor: w.balance_after_minor,
+        occurred_at:         w.occurred_at,
       };
     },
 
@@ -234,24 +267,24 @@ function create(opts) {
       var requested  = _epochMs(input.occurred_at, "occurred_at");
       if (requested == null) requested = _now();
 
-      var latest = await _readLatest(customerId);
-      if (amount > latest.balance) {
+      // The balance gate lives INSIDE the insert — a refused write covers
+      // both "always insufficient" and "a concurrent debit drained it
+      // first", with no window between check and write.
+      var w = await _writeRowAtomic("debit", customerId, amount, null, null, orderId, null, requested);
+      if (!w) {
         var insufficient = new Error("storeCredit.debit: amount exceeds available balance");
         insufficient.code = "STORE_CREDIT_INSUFFICIENT_BALANCE";
         throw insufficient;
       }
-      var ts    = _resolveOccurredAt(requested, latest.occurred_at);
-      var after = latest.balance - amount;
-      var id = await _writeRow(customerId, "debit", amount, null, null, orderId, after, null, ts);
 
       return {
-        id:                  id,
+        id:                  w.id,
         customer_id:         customerId,
         kind:                "debit",
         amount_minor:        amount,
         order_id:            orderId,
-        balance_after_minor: after,
-        occurred_at:         ts,
+        balance_after_minor: w.balance_after_minor,
+        occurred_at:         w.occurred_at,
       };
     },
 
@@ -272,18 +305,15 @@ function create(opts) {
       var requested = _epochMs(input.occurred_at, "occurred_at");
       if (requested == null) requested = _now();
 
-      var latest = await _readLatest(customerId);
-      // Expire caps at the current balance — operators running a
-      // scheduled sweep over computed "expiring before X" amounts
-      // should degrade gracefully rather than refusing when an
-      // interim debit has already drained the wallet.
-      var toBurn = amount > latest.balance ? latest.balance : amount;
-      if (toBurn === 0) {
-        // No-op write: persisting a zero-amount row would violate
-        // the CHECK(amount_minor > 0) constraint. Surface a
-        // structured refusal so the caller can distinguish "already
-        // empty" from "actually burned N". A no-op expire is a
-        // valid outcome of a bulk sweep — don't throw.
+      // Expire caps at the current balance INSIDE the insert — operators
+      // running a scheduled sweep over computed "expiring before X"
+      // amounts degrade gracefully rather than refusing when an interim
+      // debit has already drained the wallet. A refused write (wallet
+      // already at zero) is the structured no-op below, never a throw —
+      // by design: a no-op expire is a valid outcome of a bulk sweep,
+      // and a zero-amount row would violate CHECK(amount_minor > 0).
+      var w = await _writeRowAtomic("expire", customerId, amount, null, reason, null, null, requested);
+      if (!w) {
         return {
           id:                  null,
           customer_id:         customerId,
@@ -291,24 +321,21 @@ function create(opts) {
           amount_minor:        0,
           requested_minor:     amount,
           reason:              reason,
-          balance_after_minor: latest.balance,
+          balance_after_minor: await _currentBalance(customerId),
           occurred_at:         requested,
           noop:                true,
         };
       }
-      var ts    = _resolveOccurredAt(requested, latest.occurred_at);
-      var after = latest.balance - toBurn;
-      var id = await _writeRow(customerId, "expire", toBurn, null, reason, null, after, null, ts);
 
       return {
-        id:                  id,
+        id:                  w.id,
         customer_id:         customerId,
         kind:                "expire",
-        amount_minor:        toBurn,
+        amount_minor:        w.amount_minor,
         requested_minor:     amount,
         reason:              reason,
-        balance_after_minor: after,
-        occurred_at:         ts,
+        balance_after_minor: w.balance_after_minor,
+        occurred_at:         w.occurred_at,
         noop:                false,
       };
     },
@@ -585,29 +612,22 @@ function create(opts) {
           continue;
         }
 
-        var latest = await _readLatest(customerId);
-        // Cap the burn at the wallet's current balance.
-        // Debits between the credit and the sweep may have spent
-        // the expired amount already; we never drive the balance
-        // negative. The expired credits were "first-out" from the
-        // operator's POV — but the schema doesn't track FIFO at
-        // row-level, so cap by current balance and let the audit
-        // trail reflect what was actually burned.
-        var toBurn = pendingBurn > latest.balance ? latest.balance : pendingBurn;
-        if (toBurn <= 0) {
-          // Wallet already empty — record nothing (no CHECK > 0
-          // violation). Operator can reconcile via history.
-          continue;
-        }
-        var ts    = _resolveOccurredAt(now, latest.occurred_at);
-        var after = latest.balance - toBurn;
-        var id    = await _writeRow(customerId, "expire", toBurn, null, SWEEP_SOURCE_REF, null, after, null, ts);
+        // The burn caps at the wallet's current balance INSIDE the
+        // guarded insert. Debits between the credit and the sweep may
+        // have spent the expired amount already; the write never drives
+        // the balance negative, and a wallet already at zero refuses the
+        // write entirely (no CHECK > 0 violation; operator reconciles
+        // via history). The expired credits were "first-out" from the
+        // operator's POV — the schema doesn't track FIFO at row level,
+        // so the audit trail reflects what was actually burned.
+        var w = await _writeRowAtomic("expire", customerId, pendingBurn, null, SWEEP_SOURCE_REF, null, null, now);
+        if (!w) continue;
         processed.push({
-          id:                  id,
+          id:                  w.id,
           customer_id:         customerId,
-          amount_minor:        toBurn,
-          balance_after_minor: after,
-          occurred_at:         ts,
+          amount_minor:        w.amount_minor,
+          balance_after_minor: w.balance_after_minor,
+          occurred_at:         w.occurred_at,
         });
       }
       return { processed: processed, swept_at: now };

package/lib/storefront.js

@@ -14864,7 +14864,7 @@ function mount(router, deps) {
         // the buyer must lower a quantity or drop a line; nothing was
         // charged and any holds placed mid-confirm were already released.
         if (code.indexOf("GIFTCARD_") === 0 || code.indexOf("LOYALTY_") === 0 ||
-            code === "INSUFFICIENT_STOCK") {
+            code === "INSUFFICIENT_STOCK" || code === "AUTO_DISCOUNT_EXHAUSTED") {
           try {
             var coLines = await _repriceCartLines(await deps.cart.listLines(c.id));
             if (coLines.length) {
@@ -14976,6 +14976,10 @@ function mount(router, deps) {
             selected_shipping_id: body.selected_shipping_id || defaultShipId || "std",
             customer:             { email: body.email, name: body.name },
             gift_card_code:       body.gift_card_code || undefined,
+            // Loyalty points the signed-in shopper asked to spend — same
+            // parse + credit handling as the card-form confirm, so both
+            // payment buttons honor identical credits.
+            loyalty_redeem_points: _parseRedeemPoints(body.loyalty_redeem_points),
             codes:                ppCodes.length ? ppCodes : undefined,
             idempotency_key:      "paypal:" + c.id + ":" + b.uuid.v7(),
             return_url:           body.return_url || undefined,
@@ -14991,7 +14995,10 @@ function mount(router, deps) {
           return _json(200, { id: created.paypal_order_id, order_id: created.order.id });
         } catch (e) {
           var ecode = (e && typeof e.code === "string") ? e.code : "";
-          var gcErr = ecode.indexOf("GIFTCARD_") === 0;
+          // Customer-correctable credit errors (bad gift-card code,
+          // insufficient loyalty balance, points on a guest cart) are 400s
+          // whose message the button surfaces inline.
+          var gcErr = ecode.indexOf("GIFTCARD_") === 0 || ecode.indexOf("LOYALTY_") === 0 || ecode === "AUTO_DISCOUNT_EXHAUSTED";
           // Out-of-stock is a 409 (conflict) carrying the friendly per-line
           // message so the PayPal button surfaces it; nothing was charged
           // and the mid-confirm holds were already released.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.4.27",
+  "version": "0.4.29",
   "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": {