@blamejs/blamejs-shop 0.4.20 → 0.4.22

package/lib/security-middleware.js

@@ -58,11 +58,19 @@ var _vendoredSecurityHeaders = require("./vendor/blamejs/lib/middleware/security
 
 var C = b.constants;
 
-// Payment webhooks are server-to-server POSTs from Stripe / PayPal:
-// cross-site by nature, unthrottleable by a per-IP human budget, and
-// already authenticated by an HMAC signature the edge + container both
-// verify. They are exempt from BOTH the rate limiters and fetch-metadata.
-var WEBHOOK_PATHS = ["/api/webhooks/stripe", "/api/webhooks/paypal"];
+// Server-to-server webhooks: cross-site by nature, unthrottleable by a
+// per-IP human budget, and each authenticated by its own gate the handler
+// verifies first thing — an HMAC signature (Stripe / PayPal) or a per-
+// endpoint signing secret (the ESP bounce / complaint intake). They are
+// exempt from the rate limiters, fetch-metadata, and the double-submit CSRF
+// token (a third-party POST carries no session cookie or token). The
+// `/api/` prefix also lands them in the vendored bot-guard's onlyForHtml
+// skip, so the secret / signature gate is the deciding check.
+var WEBHOOK_PATHS = [
+  "/api/webhooks/stripe",
+  "/api/webhooks/paypal",
+  "/api/webhooks/mail-bounce",
+];
 
 // Liveness / readiness probe — the container's Docker HEALTHCHECK hits
 // this on a fixed cadence; never rate-limit it or a slow cold start

package/lib/store-credit.js

@@ -67,6 +67,14 @@ var C = b.constants;
 var KINDS   = ["credit", "debit", "expire"];
 var SOURCES = ["refund", "goodwill", "promotional", "manual", "loyalty_redemption"];
 
+// Reserved source_ref stamped on every expire row the scheduled sweep
+// writes. `cleanupExpired` keys its "already swept" idempotency on this
+// marker SO THAT operator-initiated `expire()` rows (which carry the
+// operator's own reason) don't masquerade as prior sweep output and
+// suppress a legitimate expiry. The marker is short + control-byte-free
+// so it passes `_sourceRef` validation when written.
+var SWEEP_SOURCE_REF = "scheduled-expiry-sweep";
+
 var MAX_SOURCE_REF_LEN = 128;
 // source_ref / reason are short correlation handles. Refuse all
 // control bytes (including CR/LF and tab) — log-injection cover has
@@ -488,20 +496,25 @@ function create(opts) {
       var now = _epochMs(input.now, "now");
       if (now == null) now = _now();
 
-      // Walk every credit row whose deadline has passed. For each,
-      // check whether a later `expire` row has already offset it —
-      // if so, skip (idempotent re-run produces no duplicates).
-      // Otherwise write an offsetting expire row capped at the
-      // wallet's current balance.
+      // Walk every credit row whose deadline has passed. For each
+      // customer, expire the still-unburned portion of their expired
+      // credit, capped at the wallet's current balance.
       //
-      // The "already offset" check is per-customer rather than
-      // per-credit-row because expire rows have no parent pointer
-      // at the schema level. We sum the customer's expired-credit
-      // amounts (kind=credit AND expires_at <= now) and the
-      // customer's burn-expire amounts (kind=expire) — the delta
-      // is the still-unburned expiring credit for that customer.
-      // When the delta is zero, the sweep is a no-op for that
-      // customer.
+      // The "already swept" check is per-customer rather than
+      // per-credit-row because expire rows have no parent pointer at
+      // the schema level. The idempotency key is the SWEEP's OWN prior
+      // output — expire rows stamped with `SWEEP_SOURCE_REF` — NOT
+      // every expire row. Counting all expire rows here was the bug:
+      // an operator-initiated `expire()` (a clawback, a goodwill burn)
+      // or any non-sweep expire would be subtracted from the expired-
+      // credit total, shrinking `pendingBurn` and leaving genuinely
+      // expired credit un-swept. Operator expires + debits already
+      // reduced the BALANCE; the `min(pendingBurn, balance)` cap below
+      // is what keeps the sweep from over-burning when the wallet was
+      // partly drained — so they must not also be netted out of the
+      // expired pool, or the reduction is double-counted. When the
+      // unburned remainder is zero, the sweep is a no-op for that
+      // customer (idempotent re-run produces no duplicates).
       var expiredByCustomer = (await query(
         "SELECT customer_id, SUM(amount_minor) AS total " +
         "FROM store_credit_ledger " +
@@ -519,16 +532,15 @@ function create(opts) {
         var burnRow = (await query(
           "SELECT COALESCE(SUM(amount_minor), 0) AS total " +
           "FROM store_credit_ledger " +
-          "WHERE customer_id = ?1 AND kind = 'expire'",
-          [customerId],
+          "WHERE customer_id = ?1 AND kind = 'expire' AND source_ref = ?2",
+          [customerId, SWEEP_SOURCE_REF],
         )).rows[0];
         var alreadyBurned = burnRow ? burnRow.total : 0;
         var pendingBurn   = expiredTotal - alreadyBurned;
 
         if (pendingBurn <= 0) {
-          // Already fully offset by prior expire rows (or by
-          // debits that drained the wallet below the expired
-          // amount — see cap below). Idempotent skip.
+          // The sweep already burned this customer's expired credit on
+          // a prior run. Idempotent skip.
           continue;
         }
 
@@ -548,7 +560,7 @@ function create(opts) {
         }
         var ts    = _resolveOccurredAt(now, latest.occurred_at);
         var after = latest.balance - toBurn;
-        var id    = await _writeRow(customerId, "expire", toBurn, null, "scheduled-expiry-sweep", null, after, null, ts);
+        var id    = await _writeRow(customerId, "expire", toBurn, null, SWEEP_SOURCE_REF, null, after, null, ts);
         processed.push({
           id:                  id,
           customer_id:         customerId,

package/lib/storefront.js

@@ -5795,6 +5795,21 @@ function _subscriptionControlState(sub) {
   return "active";
 }
 
+// Stripe statuses that wind a subscription down for good. A subscription
+// the customer cancelled at Stripe (or that lapsed unpaid) syncs to one
+// of these via the `customer.subscription.*` webhook, which writes
+// `status` but NOT the local `cancelled_at`. Without checking the synced
+// status, a Stripe-cancelled subscription whose local control-state is
+// still "active" would render live pause / skip / quantity / frequency
+// controls that mutate a row Stripe no longer bills — a customer would
+// "pause" or "change the quantity" of a subscription that's already
+// dead. So the self-manage controls are gated on the synced status: a
+// terminally-wound-down subscription shows its state, not live controls.
+var TERMINAL_SUB_STATUSES = ["canceled", "incomplete_expired", "unpaid"];
+function _subscriptionSelfManageable(sub) {
+  return TERMINAL_SUB_STATUSES.indexOf(sub.status) === -1;
+}
+
 // The 90-day reactivation grace mirrors subscriptionControls.REACTIVATE_
 // GRACE_MS. A cancelled row is reactivatable from the storefront while
 // the cancellation is inside that window; past it, the primitive refuses
@@ -5841,6 +5856,13 @@ var SUBSCRIPTION_ERR = {
   frequency:   "Choose a valid delivery frequency.",
   state:       "That change isn't available for this subscription right now.",
   grace:       "This subscription was cancelled too long ago to reactivate. Start a new one instead.",
+  // Stripe doesn't let an active subscription's billing cadence change in
+  // place; the customer cancels + re-subscribes on a plan with the
+  // cadence they want.
+  freq_locked: "Delivery frequency can't be changed on this subscription. Cancel it and start a new one on the cadence you want.",
+  // A Stripe-side quantity push failed; the local quantity was NOT
+  // changed, so the customer sees the unchanged value and can retry.
+  processor:   "We couldn't update your subscription with the payment processor. Nothing changed — please try again.",
 };
 function _subscriptionErrorCopy(code) {
   if (code == null) return null;
@@ -5853,14 +5875,23 @@ function _subscriptionErrorCopy(code) {
 // payment handle wired — the list renders read-only with a note, since
 // cancel composes Stripe. `opts.self_manage` adds the pause / resume /
 // skip / change-quantity / change-frequency / reactivate controls (wired
-// only when the subscriptionControls primitive is available). Empty state
-// points at the catalog (creation is a separate Stripe-subscription-
-// checkout surface, not built here).
+// only when the subscriptionControls primitive is available).
+// `opts.stripe_backed` is true when those controls can reach Stripe — it
+// suppresses the change-frequency form on a Stripe-backed row (the
+// billing interval is immutable at Stripe) and gates the whole control
+// block on the synced status so a Stripe-cancelled subscription shows its
+// state, not live controls. Empty state points at the catalog (creation
+// is a separate Stripe-subscription-checkout surface, not built here).
 function renderAccountSubscriptions(opts) {
   var esc = b.template.escapeHtml;
   var subs = opts.subscriptions || [];
   var canCancel = opts.can_cancel !== false;
   var selfManage = opts.self_manage === true;
+  // True when the controls can actually reach Stripe (retrieve+update
+  // wired). Only then is a row's billing cadence processor-locked and the
+  // frequency control suppressed; a local-only controls instance keeps
+  // offering it even on a Stripe-shaped row.
+  var stripeAware = opts.stripe_backed === true;
   var rowsHtml = "";
   for (var i = 0; i < subs.length; i += 1) {
     var s = subs[i];
@@ -5920,11 +5951,22 @@ function renderAccountSubscriptions(opts) {
     // cancel (a second server-rendered screen, no inline confirm()); the
     // reversible controls post directly. Quantity / frequency take input
     // validated server-side.
+    //
+    // The active + paused control sets are additionally gated on the
+    // SYNCED Stripe status: a subscription Stripe has wound down
+    // (canceled / incomplete_expired / unpaid via webhook) but whose
+    // LOCAL control-state still reads "active"/"paused" must NOT offer
+    // pause / skip / quantity / frequency / resume — those would mutate a
+    // row Stripe no longer bills. The cancelled-within-grace REACTIVATE
+    // path is intentionally NOT gated this way: a Stripe-canceled status
+    // is the normal state of a row the customer is reactivating, and
+    // reactivate is the recovery action for exactly that case.
     var manageControls = "";
+    var liveManageable = _subscriptionSelfManageable(s);
     if (selfManage) {
       var actId = esc(s.id);
       var ctrls = "";
-      if (controlState === "active") {
+      if (controlState === "active" && liveManageable) {
         ctrls +=
           "<a class=\"btn-ghost btn-ghost--sm\" href=\"/account/subscriptions/" + actId + "/pause\">Pause</a>";
         ctrls +=
@@ -5939,15 +5981,26 @@ function renderAccountSubscriptions(opts) {
             "</label>" +
             "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Update quantity</button>" +
           "</form>";
-        ctrls +=
-          "<form class=\"subscription-card__control subscription-card__control--freq\" method=\"post\" action=\"/account/subscriptions/" + actId + "/frequency\">" +
-            "<label class=\"form-field form-field--inline\">" +
-              "<span class=\"form-field__label\">Frequency</span>" +
-              "<select name=\"frequency\" required>" + _frequencyOptions(s.frequency || null) + "</select>" +
-            "</label>" +
-            "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Update frequency</button>" +
-          "</form>";
-      } else if (controlState === "paused") {
+        // The frequency control only renders for a shop-local (non-
+        // Stripe) subscription. A Stripe-backed subscription's billing
+        // cadence is fixed by its Stripe Price (interval is immutable),
+        // so there's nothing for this form to change — offering it would
+        // be a button that always errors. `stripeAware` is set only when
+        // the controls can reach Stripe; combined with the row's
+        // `stripe_subscription_id` it identifies a genuinely Stripe-
+        // backed row.
+        var stripeBacked = stripeAware && s.stripe_subscription_id != null && String(s.stripe_subscription_id).length > 0;
+        if (!stripeBacked) {
+          ctrls +=
+            "<form class=\"subscription-card__control subscription-card__control--freq\" method=\"post\" action=\"/account/subscriptions/" + actId + "/frequency\">" +
+              "<label class=\"form-field form-field--inline\">" +
+                "<span class=\"form-field__label\">Frequency</span>" +
+                "<select name=\"frequency\" required>" + _frequencyOptions(s.frequency || null) + "</select>" +
+              "</label>" +
+              "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Update frequency</button>" +
+            "</form>";
+        }
+      } else if (controlState === "paused" && liveManageable) {
         ctrls +=
           "<form class=\"subscription-card__control\" method=\"post\" action=\"/account/subscriptions/" + actId + "/resume\">" +
             "<button type=\"submit\" class=\"btn-primary btn-primary--sm\">Resume</button>" +
@@ -17487,6 +17540,11 @@ function mount(router, deps) {
           subscriptions: rows,
           can_cancel:    subsCanCancel,
           self_manage:   !!subControls,
+          // The frequency control is suppressed for Stripe-backed rows
+          // ONLY when the controls can actually reach Stripe (a payment
+          // handle with retrieve + update was wired) — otherwise the
+          // controls are local-only and the cadence is still editable.
+          stripe_backed: !!(subControls && subControls.stripeBacked),
           notice:        notice,
           error:         _subscriptionErrorCopy(errKind),
           shop_name:     shopName,
@@ -17513,6 +17571,7 @@ function mount(router, deps) {
           if (e && e.code === "SUBSCRIPTION_REACTIVATE_GRACE_EXPIRED") return "grace";
           if (e && e.code === "SUBSCRIPTION_STATE_REFUSED")            return "state";
           if (e && e.code === "SUBSCRIPTION_NOT_FOUND")                return "state";
+          if (e && e.code === "SUBSCRIPTION_FREQUENCY_IMMUTABLE")      return "freq_locked";
           if (e instanceof TypeError)                                   return "state";
           return null;
         }
@@ -17522,13 +17581,32 @@ function mount(router, deps) {
           return res.end ? res.end() : res.send("");
         }
 
+        // Resolve an owned subscription AND refuse the self-manage action
+        // when the synced Stripe status is terminal (canceled /
+        // incomplete_expired / unpaid). The display gates the controls on
+        // the same status, but the backend validates independently — a
+        // forged POST to a wound-down subscription's pause / skip /
+        // quantity / frequency endpoint bounces to the list with the
+        // generic state error rather than mutating a row Stripe no longer
+        // bills. Returns null (after redirecting) when ownership fails or
+        // the status is terminal; the caller bails on null.
+        async function _ownedManageableSubscription(req, res, auth) {
+          var sub = await _ownedSubscription(req, res, auth);
+          if (!sub) return null;
+          if (!_subscriptionSelfManageable(sub)) {
+            _redirect(res, "?error=state");
+            return null;
+          }
+          return sub;
+        }
+
         // Pause is confirm-gated (GET → POST), mirroring cancel — a
         // deliberate, reversible hold. The confirm page only renders for a
         // currently-active subscription; a paused/cancelled row bounces
         // back to the list.
         router.get("/account/subscriptions/:id/pause", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           if (_subscriptionControlState(sub) !== "active") return _redirect(res, "");
           if (sub.plan_id != null) {
             try { sub.plan = await subscriptions.plans.get(sub.plan_id); }
@@ -17544,7 +17622,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/pause", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.pause({ subscription_id: sub.id, reason: "customer self-service pause", actor: SELF_ACTOR });
           } catch (e) {
@@ -17556,7 +17634,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/resume", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.resume({ subscription_id: sub.id, reason: "customer self-service resume", actor: SELF_ACTOR });
           } catch (e) {
@@ -17568,7 +17646,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/skip", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.skipNext({ subscription_id: sub.id, count: 1, reason: "customer self-service skip", actor: SELF_ACTOR });
           } catch (e) {
@@ -17580,7 +17658,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/quantity", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           // Backend validates: a non-positive / non-integer / missing value
           // is a client error → bounce with the quantity error code rather
           // than handing garbage to the primitive (which would throw a
@@ -17591,6 +17669,14 @@ function mount(router, deps) {
             await subControls.changeQuantity({ subscription_id: sub.id, new_quantity: qty, reason: "customer self-service quantity change", actor: SELF_ACTOR });
           } catch (e) {
             if (e instanceof TypeError) return _redirect(res, "?error=quantity");
+            // A Stripe-side push failure (no billable item, or the
+            // processor rejected/timed out the update) left the local
+            // quantity unchanged. Surface a clean "nothing changed, retry"
+            // notice instead of 500-ing — the customer's row still shows
+            // the old quantity, which is the truth.
+            if (e && (e.code === "SUBSCRIPTION_STRIPE_NO_ITEM" || e.code === "SUBSCRIPTION_STRIPE_PUSH_FAILED")) {
+              return _redirect(res, "?error=processor");
+            }
             var code = _controlError(e); if (code == null) throw e;
             return _redirect(res, "?error=" + code);
           }
@@ -17599,7 +17685,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/frequency", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           // Backend validates: reject anything outside the allowed cadence
           // enum before composing the primitive.
           var freq = String((req.body || {}).frequency || "");
@@ -17616,6 +17702,11 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/reactivate", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
+          // Reactivate is the recovery path for a cancelled subscription,
+          // so it is NOT gated on the terminal-status guard (a Stripe-
+          // canceled status is the normal state of a row being
+          // reactivated). The primitive enforces the cancelled-state +
+          // grace-window FSM.
           var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.reactivate({ subscription_id: sub.id, reason: "customer self-service reactivate", actor: SELF_ACTOR });
@@ -19902,7 +19993,22 @@ function mount(router, deps) {
 
     router.post("/unsubscribe", async function (req, res) {
       var body = req.body || {};
-      var token = typeof body.token === "string" ? body.token : "";
+      // RFC 8058 one-click: the mail client POSTs to the EXACT URL in the
+      // List-Unsubscribe header — token in the `?token=` query string —
+      // with a `List-Unsubscribe=One-Click` form body and NOTHING else
+      // (no token of its own). So the URL token is authoritative; the
+      // body `token` is only the fallback the on-page confirm form POSTs
+      // from its hidden field. Reading body.token alone (the prior shape)
+      // meant a native one-click POST carried no token -> "not-found" ->
+      // the recipient was never unsubscribed. Parse the token off req.url
+      // (the router only populates req.query when a route declares a query
+      // validator), then fall back to the confirm-form body field.
+      var urlToken = "";
+      try {
+        var u = req.url ? new URL(req.url, "http://localhost") : null;
+        if (u) urlToken = u.searchParams.get("token") || "";
+      } catch (_eUrl) { urlToken = ""; }
+      var token = urlToken || (typeof body.token === "string" ? body.token : "");
       var cartCount = 0;
       try { cartCount = await _cartCountForReq(req); } catch (_e) { /* drop-silent — empty cart fallback */ }
       var outcome;
@@ -19910,6 +20016,9 @@ function mount(router, deps) {
         // `consumeUnsubscribeToken` returns a structured result (it does
         // not throw on a bad/missing token — it returns `{ ok:false,
         // error:"not-found" }`). An empty token is handled the same way.
+        // It is single-use, so the one-click POST and a later confirm-form
+        // POST of the same token are idempotent (the second reads
+        // "already" — still a success page, no error).
         var result = await deps.newsletter.consumeUnsubscribeToken(token);
         outcome = _unsubscribeOutcome(result);
       } catch (e) {

package/lib/subscription-controls.js

@@ -242,6 +242,77 @@ function create(opts) {
   if (!subscriptionsHandle || typeof subscriptionsHandle.get !== "function") {
     throw new TypeError("subscriptionControls.create: opts.subscriptions handle required");
   }
+  // Optional payment handle (the shared Stripe adapter). When wired,
+  // quantity changes on a Stripe-backed subscription are pushed to
+  // Stripe BEFORE the local row is touched, so the row the shop shows
+  // and the quantity Stripe actually bills never diverge. Without it
+  // (a deploy with no payment processor, or a non-Stripe row), the
+  // controls stay local-only. The handle must expose
+  // `subscriptions.retrieve(id)` + `subscriptions.update(id, body)`.
+  var payment = opts.payment || null;
+  var hasStripe = !!(payment && payment.subscriptions &&
+    typeof payment.subscriptions.update === "function" &&
+    typeof payment.subscriptions.retrieve === "function");
+
+  // A row is Stripe-backed when the processor adapter is wired AND the
+  // row carries the upstream subscription id the webhook + billing
+  // mirror key on. Rows without one are shop-local (e.g. a manually
+  // seeded subscription on a deploy that never reached Stripe) and the
+  // controls mutate only local columns for them.
+  function _isStripeBacked(row) {
+    return hasStripe && row && typeof row.stripe_subscription_id === "string" && row.stripe_subscription_id.length > 0;
+  }
+
+  // Push a new line quantity to Stripe for a Stripe-backed subscription.
+  // Stripe models quantity on the subscription ITEM, not the
+  // subscription, so we retrieve the live subscription to find its
+  // (single) item id, then update that item's quantity. Every
+  // subscription this shop creates binds exactly one price
+  // (`items: [{ price }]`), so the first item is authoritative; if a
+  // subscription somehow carries no item we surface a structured error
+  // rather than silently writing a local-only change that diverges from
+  // Stripe. The idempotency key folds in the subscription id + target
+  // quantity so a retried call is a safe no-op at Stripe.
+  async function _pushQuantityToStripe(stripeSubscriptionId, newQuantity) {
+    var live;
+    try {
+      live = await payment.subscriptions.retrieve(stripeSubscriptionId);
+    } catch (e) {
+      var rErr = new Error(
+        "subscriptionControls.changeQuantity: could not reach Stripe to update the subscription — " + (e && e.message || e),
+      );
+      rErr.code = "SUBSCRIPTION_STRIPE_PUSH_FAILED";
+      rErr.cause = e;
+      throw rErr;
+    }
+    var items = live && live.items && Array.isArray(live.items.data) ? live.items.data : [];
+    if (!items.length || !items[0] || !items[0].id) {
+      var noItem = new Error(
+        "subscriptionControls.changeQuantity: Stripe subscription " + stripeSubscriptionId + " has no billable item to update",
+      );
+      noItem.code = "SUBSCRIPTION_STRIPE_NO_ITEM";
+      throw noItem;
+    }
+    var idemKey = "subctl:qty:" + stripeSubscriptionId + ":" + newQuantity;
+    try {
+      return await payment.subscriptions.update(
+        stripeSubscriptionId,
+        { items: [{ id: items[0].id, quantity: newQuantity }] },
+        idemKey,
+      );
+    } catch (e2) {
+      // The processor rejected or failed the quantity update. Wrap it in
+      // a stable code so the route can surface a "nothing changed, retry"
+      // notice; the local row is still untouched (this runs before the
+      // local write).
+      var uErr = new Error(
+        "subscriptionControls.changeQuantity: Stripe rejected the quantity update — " + (e2 && e2.message || e2),
+      );
+      uErr.code = "SUBSCRIPTION_STRIPE_PUSH_FAILED";
+      uErr.cause = e2;
+      throw uErr;
+    }
+  }
 
   // Fetch the raw subscription row + bound plan in one round-trip,
   // returning `null` if either is absent. The plan lookup feeds the
@@ -317,6 +388,14 @@ function create(opts) {
     MAX_SKIP_COUNT:     MAX_SKIP_COUNT,
     MAX_QUANTITY:       MAX_QUANTITY,
     REACTIVATE_GRACE_MS: REACTIVATE_GRACE_MS,
+    // True when this instance can push changes to Stripe (a payment
+    // handle with retrieve + update was wired). Callers use it to decide
+    // whether a row with a stripe_subscription_id is genuinely Stripe-
+    // backed — a frequency change is refused (immutable interval) and a
+    // quantity change round-trips Stripe. Without it, the controls are
+    // local-only even for a Stripe-shaped row, so the storefront keeps
+    // offering the frequency control.
+    stripeBacked:       hasStripe,
 
     pause: async function (input) {
       if (!input || typeof input !== "object") {
@@ -462,6 +541,18 @@ function create(opts) {
         throw cErr;
       }
 
+      // Stripe-backed: push the new quantity to Stripe BEFORE the local
+      // write. If the processor rejects the update, we throw and leave
+      // the local row untouched — the customer sees an honest error and
+      // the shop's `quantity` column never diverges from what Stripe
+      // actually bills (the divergence this control surface previously
+      // produced, writing a local "Quantity updated." while Stripe kept
+      // charging the old quantity). The local write only lands after the
+      // Stripe update succeeds.
+      if (_isStripeBacked(row)) {
+        await _pushQuantityToStripe(row.stripe_subscription_id, newQuantity);
+      }
+
       var before = _snapshot(row);
       var ts = _now();
       await query(
@@ -495,6 +586,28 @@ function create(opts) {
         throw cErr;
       }
 
+      // Stripe-backed: refuse. A Stripe Price's `recurring.interval` is
+      // IMMUTABLE — you cannot re-cadence an existing price, only swap
+      // the subscription item to a DIFFERENT price with the desired
+      // interval. This shop binds each subscription to a single
+      // `stripe_price_id` from its plan and carries no catalog of
+      // per-frequency prices to swap between, so the billing interval
+      // simply isn't expressible here. Writing the local `frequency`
+      // column anyway would tell the customer "Delivery frequency
+      // updated" while Stripe kept invoicing on the original cadence —
+      // exactly the divergence this surface must not create. Refuse with
+      // honest copy; the customer cancels + re-subscribes on a plan with
+      // the cadence they want. (A non-Stripe row falls through to the
+      // local-only recompute below — the shop's own cadence view.)
+      if (_isStripeBacked(row)) {
+        var fErr = new Error(
+          "subscriptionControls.changeFrequency: delivery frequency can't be changed on this subscription — " +
+          "cancel and start a new subscription on a plan with the cadence you want",
+        );
+        fErr.code = "SUBSCRIPTION_FREQUENCY_IMMUTABLE";
+        throw fErr;
+      }
+
       // next_billing_at is recomputed off the row's current cycle
       // anchor — `current_period_start` (Stripe-mirrored) if present,
       // otherwise the current next_billing_at, otherwise now. One