@blamejs/blamejs-shop 0.4.83 → 0.4.85

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.85 (2026-06-22) — **Stock-transfer reconciliation credits the destination exactly once, even when retried after a mid-operation failure.** Fixes an inventory-integrity bug in stock-transfer reconciliation. Reconciling a received transfer credits each line's received quantity to the destination shelf and then records the line's discrepancy. If that discrepancy write failed partway through the transfer, reconciliation rolled its own state back so the operator could retry — but the retry credited the already-credited lines a second time, inflating the destination shelf with stock that was never received and could then be oversold. The destination credit is now keyed and idempotent: a retry recognizes a line it has already credited and skips it, so the shelf is credited exactly once no matter how many times reconciliation runs. The release adds one additive, backward-compatible database migration; apply pending migrations on upgrade. **Fixed:** *Stock-transfer reconciliation no longer double-credits the destination on retry* — Reconciling a received transfer credited each line to the destination shelf before stamping the line's discrepancy. A failure between those two steps rolled the transfer back to 'received' for a clean retry, but the retry re-credited every line whose discrepancy had not yet been stamped — including lines already credited on the failed attempt — minting phantom inventory at the destination. The per-line destination credit is now idempotent and keyed to the transfer and line, so re-running reconciliation after any partial failure credits each line exactly once; the discrepancy stamp is no longer load-bearing for correctness. **Migration:** *inventory_adjustments gains a nullable idempotency key* — Adds a nullable idempotency_key column to inventory_adjustments and a unique index over it, so a keyed stock credit records that it has already been applied and a retry that re-presents the key credits nothing. The column is NULL for every existing row and for plain stock adjustments, which already apply atomically; only keyed credits set it. The change is additive and backward-compatible — apply pending D1 migrations on upgrade.
+
+- v0.4.84 (2026-06-22) — **Payment idempotency and analytics cache keys now use the framework's canonical-JSON encoder.** Internal consistency change with no configuration to apply. The Stripe idempotency replay-protection hash and the subscription-analytics cache key each carried their own copy of a sorted-key JSON serializer; both now compose the framework's canonical-JSON encoder, so a single serializer — with one set of key-ordering, string-escaping, and number-format rules — backs every replay and cache hash. Idempotency replays issued across the upgrade keep working: a request hash written by the prior release is still recognized for the row's lifetime, so a payment retried across the upgrade boundary replays its cached response rather than being refused as a mismatch. Upgrade to pick it up. **Changed:** *Replay and cache hashes share one canonical-JSON encoder* — Payment idempotency-key replay protection and the subscription-analytics cache key now build their hashes with the framework's canonical-JSON encoder instead of a locally maintained serializer. The encoder emits object members in one stable key order, so two requests — or two analytics queries — that differ only in member order resolve to the same hash, and the order is now stable even for integer-like keys, which the previous serializer reordered. Idempotency rows written by the prior release are still matched for their lifetime, so a payment retried across the upgrade boundary replays its cached response and is never refused as a false mismatch; the compatibility path expires with those rows.
+
 - v0.4.83 (2026-06-22) — **Downloading a subject-access export now requires the customer-write grant, not just read access.** Closes an access-control gap on the data-subject-request surface. Downloading a fulfilled subject-access export streams the customer's full personal-data bundle, but the download route was gated as a plain read, so a read-only operator (a viewer with no customers-write grant) could pull the entire PII bundle. The download now gates on the customers-write capability — the same grant fulfilling, dispatching, and erasing a request already require — so a read-only viewer is refused on the verb and the denial is recorded in the operator audit log, on both the API and browser paths. No configuration changes; upgrade to pick it up. **Security:** *Subject-access export download requires customers-write* — The DSR export-download route streams a customer's full PII bundle, so it is a customers-write-class capability like fulfilling, dispatching, or erasing a request — not a read. It now gates on customers-write on both the bearer-API and cookie/browser paths, so a read-only viewer can no longer download the bundle; the refused attempt is chained through the operator audit log like the other DSR write denials. Viewing the DSR queue (a read) is unchanged.
 
 - v0.4.82 (2026-06-22) — **Return-authorization and shipping-label state transitions are exactly-once under concurrency.** Two fulfillment surfaces gain the atomic-claim discipline the refund path already uses. Approving, receiving, and rejecting a return authorization now gate the transition on the observed status inside the UPDATE, so two operators (or a double-clicked action) acting on the same return can no longer both apply — exactly one transition wins and the other is refused, instead of a read-then-write letting both pass last-write-wins. Likewise, recording a shipping label as purchased, voided, or used is now a single guarded claim, so two concurrent broker callbacks for the same label can't both record (which previously left conflicting tracking numbers and costs last-write-wins). The losing caller gets the same transition-refused error a sequential illegal transition already produced. No configuration changes; upgrade to pick them up. **Fixed:** *Return-authorization transitions are atomic claims* — returns approve, markReceived, and reject now fold the expected source status into the UPDATE (approve from pending, markReceived from approved, reject from pending or approved) and treat the row count as the claim signal, matching the refund path. Two concurrent transitions on the same return — two operators, or a double-submit — can no longer both write last-write-wins; exactly one wins and the loser is refused with the same transition-refused error, mapped to a 409. Sequential not-found and illegal-transition errors are unchanged. · *Shipping-label transitions are atomic claims* — shipping-labels markPurchased, voidLabel, and markUsed now gate on the observed status inside the UPDATE. Two concurrent broker callbacks marking the same pending label purchased (a worker-drain double-fire) can no longer both record, leaving conflicting tracking numbers and costs by last-write-wins — exactly one records and the other is refused. The void 30-day window and not-found / wrong-status refusals are unchanged.

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.83",
+  "version": "0.4.85",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",

package/lib/inventory-locations.js

@@ -79,6 +79,7 @@ var CODE_RE      = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 var SKU_RE       = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 var NAME_RE      = /^[\S\s]{1,128}$/;
 var MAX_REASON   = 256;
+var MAX_IDEMPOTENCY_KEY = 256;
 var MAX_LINES    = 1000;
 var TYPES        = Object.freeze(["warehouse", "retail", "dropship"]);
 var STRATEGIES   = Object.freeze([
@@ -674,6 +675,91 @@ function create(opts) {
       return { sku: input.sku, location_code: input.location_code, quantity: nextQty, delta: input.delta };
     },
 
+    // Idempotent keyed credit. For a positive credit that is one step of a
+    // larger non-transactional flow (e.g. stock-transfer reconciliation),
+    // adjustStock alone is not safe to retry: a crash between the stock upsert
+    // and the next step lets a re-run credit the shelf a SECOND time, minting
+    // phantom inventory. creditOnce makes a retry safe by making the audit
+    // row's idempotency_key the claim: the first call with a given key inserts
+    // the row (winning the claim) and applies the credit; any later call with
+    // the same key finds it present and is a no-op. A credit never breaches the
+    // zero/holds floor, so this path is positive-delta only.
+    //
+    // Why claim-first rather than a single atomic write: the truly atomic form
+    // would be an AFTER INSERT trigger crediting the shelf in the same INSERT,
+    // but `wrangler d1 migrations apply` ships each statement to the D1 HTTP
+    // API without its trailing `;`, and D1 rejects a trigger body that way
+    // ("incomplete input"), so a trigger cannot be applied through the project's
+    // migration tool. Claim-first is therefore the design. D1 has no
+    // interactive transactions, so a single-statement gap is unavoidable; the
+    // claim (audit row) is written BEFORE the stock upsert and the compensating
+    // delete below covers the upsert throwing. The only residual is the host
+    // process dying (a container crash / deploy roll — this runs in the
+    // persistent container, not a per-request isolate) between the two
+    // statements: the key is durable but the stock was not credited, so a retry
+    // no-ops and the shelf is UNDER-credited until an operator recount, never
+    // double-credited. Under-credit is the safe direction (a recoverable
+    // shortfall, not oversellable phantom stock) and matches every other
+    // claim-first transition in the codebase.
+    creditOnce: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("inventory-locations.creditOnce: input object required");
+      }
+      _sku(input.sku);
+      _code(input.location_code, "location_code");
+      _int(input.delta, "delta");
+      if (input.delta <= 0) {
+        throw new TypeError("inventory-locations.creditOnce: delta must be a positive credit");
+      }
+      var key = input.idempotency_key;
+      if (typeof key !== "string" || !key.length || key.length > MAX_IDEMPOTENCY_KEY) {
+        throw new TypeError("inventory-locations.creditOnce: idempotency_key must be a non-empty string ≤ " +
+          MAX_IDEMPOTENCY_KEY + " chars");
+      }
+      var loc = await _getLocationRow(input.location_code);
+      if (!loc) {
+        throw new TypeError("inventory-locations.creditOnce: location_code " +
+          JSON.stringify(input.location_code) + " not found");
+      }
+      var ts = _now();
+      // Claim: insert the keyed audit row. ON CONFLICT DO NOTHING means a
+      // replay (same key) lands zero rows and the credit is skipped entirely.
+      var claim = await query(
+        "INSERT INTO inventory_adjustments " +
+        "(id, sku, location_code, delta, reason, occurred_at, idempotency_key) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7) ON CONFLICT(idempotency_key) DO NOTHING",
+        [b.uuid.v7(), input.sku, input.location_code, input.delta, _reason(input.reason), ts, key],
+      );
+      var changes = claim && (claim.rowCount != null ? claim.rowCount
+        : (claim.meta && claim.meta.changes != null ? claim.meta.changes : claim.changes));
+      if (Number(changes || 0) === 0) {
+        var existing = await _getStockRow(input.sku, input.location_code);
+        return {
+          sku: input.sku, location_code: input.location_code,
+          quantity: existing ? existing.quantity : 0, delta: 0, applied: false,
+        };
+      }
+      // Won the claim — apply the credit. If the upsert fails, roll the claim
+      // back so a retry re-attempts rather than stranding the credit at zero.
+      try {
+        await query(
+          "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) " +
+          "VALUES (?1, ?2, ?3, ?4) " +
+          "ON CONFLICT(sku, location_code) DO UPDATE SET " +
+          "quantity = quantity + ?3, updated_at = ?4",
+          [input.sku, input.location_code, input.delta, ts],
+        );
+      } catch (e) {
+        await query("DELETE FROM inventory_adjustments WHERE idempotency_key = ?1", [key]);
+        throw e;
+      }
+      var creditedRow = await _getStockRow(input.sku, input.location_code);
+      return {
+        sku: input.sku, location_code: input.location_code,
+        quantity: creditedRow ? creditedRow.quantity : 0, delta: input.delta, applied: true,
+      };
+    },
+
     // Atomic two-row move. Reads the source quantity; if
     // insufficient, refuses the whole transfer before mutating
     // anything (no money created, no row half-committed). Writes

package/lib/payment.js

@@ -364,28 +364,73 @@ async function _stripeCall(opts, method, path, params, idempotencyKey) {
 // through b.crypto.namespaceHash (SHA3-512). Arrays preserve order
 // (their order is semantically meaningful — `items[]` in a Stripe
 // subscription is an ordered list of line items).
-function _canonicalise(v) {
+// Drop undefined object members recursively. Idempotency treats an undefined
+// member as omitted — two requests that differ only by an explicit `undefined`
+// must hash the same — and the vendored canonical primitive would otherwise
+// emit `undefined` as `null` (b.safeJson.canonical throws outright). Array
+// order is preserved (an `items[]` list is semantically ordered). This is a
+// SEMANTIC pre-filter only; the canonical sort + escaping + number format is
+// delegated to the canonical-JSON primitive below, not hand-rolled.
+function _dropUndefinedMembers(v) {
   if (v === null || typeof v !== "object") return v;
   if (Array.isArray(v)) {
     var out = [];
-    for (var i = 0; i < v.length; i += 1) out.push(_canonicalise(v[i]));
+    for (var i = 0; i < v.length; i += 1) out.push(_dropUndefinedMembers(v[i]));
     return out;
   }
-  var keys = Object.keys(v).sort();
+  var keys = Object.keys(v);
   var obj  = {};
   for (var k = 0; k < keys.length; k += 1) {
     var val = v[keys[k]];
     if (val === undefined) continue;
-    obj[keys[k]] = _canonicalise(val);
+    obj[keys[k]] = _dropUndefinedMembers(val);
   }
   return obj;
 }
 
 function _canonicalHash(obj) {
-  var canonical = JSON.stringify(_canonicalise(obj == null ? {} : obj));
+  // Compose the vendored canonical-JSON primitive (RFC-8785-style sorted-key
+  // emission) for deterministic bytes, replacing the hand-rolled key sort.
+  var canonical = b.canonicalJson.stringify(_dropUndefinedMembers(obj == null ? {} : obj));
   return b.crypto.namespaceHash(IDEMPOTENCY_NAMESPACE, canonical);
 }
 
+// Pre-primitive request-hash encoding, retained ONLY to recognise idempotency
+// rows that an earlier release wrote with the hand-rolled canonicaliser. The
+// request_hash column is persisted and compared on replay, so without this a
+// same-key retry issued across the upgrade boundary would be refused as a
+// false collision until the row's 1-day TTL elapsed. New rows always store the
+// primitive-composed _canonicalHash; this fallback is compare-only and is safe
+// to delete once a full IDEMPOTENCY_TTL_MS has elapsed after deploy (by then
+// every legacy-encoded row has expired).
+function _legacyCanonicalise(v) {
+  if (v === null || typeof v !== "object") return v;
+  if (Array.isArray(v)) {
+    var out = [];
+    for (var i = 0; i < v.length; i += 1) out.push(_legacyCanonicalise(v[i]));
+    return out;
+  }
+  var keys = Object.keys(v).sort();
+  var obj  = {};
+  for (var k = 0; k < keys.length; k += 1) {
+    var val = v[keys[k]];
+    if (val === undefined) continue;
+    obj[keys[k]] = _legacyCanonicalise(val);
+  }
+  return obj;
+}
+
+function _legacyCanonicalHash(obj) {
+  return b.crypto.namespaceHash(IDEMPOTENCY_NAMESPACE, JSON.stringify(_legacyCanonicalise(obj == null ? {} : obj)));
+}
+
+// A stored request_hash matches when it equals the current primitive-composed
+// hash OR (transition fallback) the legacy encoding's hash for the same body.
+function _requestHashMatches(storedHash, requestObj) {
+  if (storedHash === _canonicalHash(requestObj)) return true;
+  return storedHash === _legacyCanonicalHash(requestObj);
+}
+
 function _assertIdempotencyKey(k) {
   if (typeof k !== "string" || k.length < 8 || k.length > 255) {
     throw new TypeError("payment: idempotency_key must be a string between 8 and 255 characters");
@@ -418,7 +463,7 @@ async function _runIdempotent(state, operation, key, requestObj, doCall) {
   )).rows[0];
 
   if (existing) {
-    if (existing.request_hash !== requestHash) {
+    if (!_requestHashMatches(existing.request_hash, requestObj)) {
       // Same key, different body — refuse. Stripe itself would reject
       // this on its own idempotency cache, but we surface a typed
       // application error so the caller doesn't have to ship the
@@ -462,7 +507,7 @@ async function _runIdempotent(state, operation, key, requestObj, doCall) {
       "FROM payment_idempotency WHERE idempotency_key = ?1 LIMIT 1",
       [key],
     )).rows[0];
-    if (winner && winner.request_hash !== requestHash) {
+    if (winner && !_requestHashMatches(winner.request_hash, requestObj)) {
       throw new TypeError("payment: idempotency_key collision (different inputs)");
     }
     if (winner) {
@@ -1147,6 +1192,7 @@ module.exports = {
   _formEncode:               _formEncode,
   _verifyWebhook:            _verifyWebhook,
   _canonicalHash:            _canonicalHash,
+  _legacyCanonicalHash:      _legacyCanonicalHash,
   // Exposed for the checkout webhook mirror + admin refund normalization —
   // exact decimal-string ↔ minor-unit conversion sharing one zero-decimal
   // currency table.

package/lib/stock-transfers.js

@@ -261,15 +261,18 @@ function _now() { return Date.now(); }
 function create(opts) {
   opts = opts || {};
   // The inventoryLocations primitive is the sole owner of
-  // `inventory_stock` mutations. This primitive composes its
-  // adjustStock verb to debit origin / credit destination — refusing
-  // to wire one through fails loud at boot rather than at first call.
+  // `inventory_stock` mutations. This primitive composes its adjustStock
+  // verb to debit origin and its creditOnce verb to credit the destination
+  // idempotently during reconcile — refusing to wire one through fails loud
+  // at boot rather than at first call (a stub missing creditOnce would
+  // otherwise boot fine and only break mid-reconcile, after the status claim).
   if (!opts.inventoryLocations ||
       typeof opts.inventoryLocations.adjustStock !== "function" ||
+      typeof opts.inventoryLocations.creditOnce !== "function" ||
       typeof opts.inventoryLocations.getLocation !== "function" ||
       typeof opts.inventoryLocations.stockForSku !== "function") {
     throw new TypeError("stock-transfers.create: opts.inventoryLocations with " +
-      "adjustStock + getLocation + stockForSku is required");
+      "adjustStock + creditOnce + getLocation + stockForSku is required");
   }
   var locations = opts.inventoryLocations;
   var query = opts.query;
@@ -669,25 +672,29 @@ function create(opts) {
           " is no longer received (already reconciled by a concurrent call) — refusing to double-credit");
       }
       var discrepancies = [];
-      // Credit the destination one line at a time. The claim above flipped the
-      // status, so a concurrent call can't reach this loop for the same
-      // transfer. Each line is skipped once its discrepancy column is stamped,
-      // so a retry (after the compensation below rolls the claim back) re-credits
-      // ONLY the lines that hadn't landed yet — no double-credit on the lines
-      // that already succeeded. If any line throws, the terminal claim is rolled
-      // back to 'received' so the transfer stays eligible for another reconcile
-      // that finishes the remaining credits, rather than stranding it.
+      // Credit the destination one line at a time. The status claim above
+      // serializes concurrent reconciles, but the exactly-once guarantee on the
+      // destination credit is the KEYED credit itself: creditOnce stamps a
+      // per-line idempotency key (stock-transfer:reconcile:<transfer>:<line>),
+      // so even if a line is credited and the loop then throws BEFORE the
+      // discrepancy column is stamped — rolling the status claim back to
+      // 'received' and re-enabling a full re-run — the re-credit finds the key
+      // present and is a no-op. The discrepancy skip-guard is a redundant
+      // fast-path, not the safety gate. If any line throws, the terminal claim
+      // is rolled back so the transfer stays eligible for another reconcile that
+      // finishes the remaining credits rather than stranding it.
       try {
         for (var i = 0; i < transfer.lines.length; i += 1) {
           var line = transfer.lines[i];
-          if (line.discrepancy != null) continue;   // already credited on a prior attempt
+          if (line.discrepancy != null) continue;   // already credited + stamped on a prior attempt
           var rx   = line.quantity_received == null ? 0 : line.quantity_received;
           if (rx > 0) {
-            await locations.adjustStock({
+            await locations.creditOnce({
               sku: line.sku,
               location_code: transfer.to_location,
               delta: rx,
               reason: "stock-transfer:reconcile:" + id,
+              idempotency_key: "stock-transfer:reconcile:" + id + ":" + line.id,
             });
           }
           var diff = line.quantity_shipped - rx;

package/lib/subscription-analytics.js

@@ -316,24 +316,10 @@ function _churnKind(value) {
 
 // ---- canonical JSON for cache keys -------------------------------------
 //
-// Two cache lookups with the same arguments in a different key order
-// must hit the same row. JSON.stringify isn't order-stable across
-// engines, so the primitive sorts keys before hashing.
-
-function _canonicalJson(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) {
-    var parts = [];
-    for (var i = 0; i < value.length; i += 1) parts.push(_canonicalJson(value[i]));
-    return "[" + parts.join(",") + "]";
-  }
-  var keys = Object.keys(value).sort();
-  var pairs = [];
-  for (var k = 0; k < keys.length; k += 1) {
-    pairs.push(JSON.stringify(keys[k]) + ":" + _canonicalJson(value[keys[k]]));
-  }
-  return "{" + pairs.join(",") + "}";
-}
+// Two cache lookups with the same arguments in a different key order must
+// hit the same row. JSON.stringify isn't order-stable across engines, so the
+// cache key is built from the vendored canonical-JSON primitive, which emits
+// members in sorted-key order before hashing.
 
 // ---- cadence normalization ---------------------------------------------
 //
@@ -410,7 +396,7 @@ function create(opts) {
   // ---- cache helpers --------------------------------------------------
 
   function _cacheKey(scope, args) {
-    return b.crypto.namespaceHash(CACHE_NAMESPACE, _canonicalJson(args || {}));
+    return b.crypto.namespaceHash(CACHE_NAMESPACE, b.canonicalJson.stringify(args || {}));
   }
 
   async function _cacheRead(scope, args, periodFrom, periodTo, ttlMs) {

package/package.json

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