@blamejs/blamejs-shop 0.4.128 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,10 @@ Pre-1.0 the surface is intentionally evolving — every release may
 change something operators depend on. Read each entry before
 upgrading across more than a few patches at a time.
 
+## v0.5.x
+
+- v0.5.0 (2026-06-27) — **Affiliate commissions gain a tamper-evident hash chain, joining the gift-card, store-credit, and loyalty ledgers.** The affiliate-commission ledger was the last money ledger without tamper-evidence. Each commission is now linked into a per-affiliate SHA3-512 hash chain: a row names its predecessor, a uniqueness fence allows exactly one child per chain tip (so concurrent commissions for the same affiliate serialize instead of forking), and editing a commission's money fields or deleting a row from the middle breaks the linkage. Unlike the append-only gift-card / store-credit / loyalty ledgers, an affiliate commission walks a pending → paid → voided payout lifecycle in place, so the chain hashes only the immutable money facts — order, affiliate, order total, commission, currency, and time — and leaves the lifecycle columns out, meaning a legitimate payout or void never breaks the chain while an inflated amount or a removed row still does. A new `affiliates.verifyChain(affiliateId)` recomputes an affiliate's chain end to end and reports the first divergence, and accepts a trusted anchor (row count + head hash from an earlier snapshot) to also catch a truncation that deletes the most-recent commissions. Migration 0238 adds the chain columns + fence; commissions recorded before it are tolerated as an unverifiable legacy prefix, and the chain anchors fresh from the first commission recorded afterward. **Added:** *Affiliate commissions are a verifiable, fork-proof per-affiliate hash chain* — Recording a commission now links it into the affiliate's SHA3-512 hash chain — `row_hash = SHA3-512(prev_hash || canonical-json(immutable fields))` — under a `UNIQUE(affiliate_id, prev_hash)` parent fence, so a commission derived from a stale tip collides and retries instead of forking the chain, and concurrent commissions for one affiliate serialize. Because a commission's status, paid-at, payout reference, and void reason are stamped in place over its lifetime, only the immutable money facts are hashed, so a `pending → paid → voided` transition leaves the chain valid while tampering with the order total or commission amount, or deleting a commission, is detected. `affiliates.verifyChain(affiliateId)` walks the chain and reports the first break; pass `{ anchor: { count, head } }` to also rule out a tail truncation. Commissions written before this release are tolerated as an unverifiable legacy prefix and the chain anchors fresh from the next one — no backfill required. Migration 0238 adds the columns and the fence.
+
 ## v0.4.x
 
 - v0.4.128 (2026-06-27) — **Email sign-in links are now rate-limited per recipient, bounding inbox-flood and token-minting abuse.** The email magic-link sign-in — the no-passkey backup on the login screen — minted a new single-use sign-in token and sent an email on every POST for a registered address, bounded only by the per-IP request limiter. An attacker submitting a victim's address from many IP addresses could therefore flood that inbox with sign-in links and mint an unbounded number of valid single-use tokens. The route now applies a per-recipient cooldown: at most one sign-in link (and one minted token) per registered address per minute. The cooldown runs after the unchanged, enumeration-safe confirmation response, so a registered and an unregistered address stay indistinguishable by the reply; a transient lookup failure falls through to sending, keeping availability ahead of the rate cap. **Fixed:** *Email sign-in links are rate-limited per recipient* — Requesting an email sign-in link minted a single-use portal token and sent a message every time it was submitted for a registered address, with only the per-IP limiter in front of it — which a distributed sender (many IPs, one victim address) sails past. The request now checks whether a sign-in link was already minted for that account within the last minute and, if so, sends nothing further. The check runs on the request's background path, after the identical confirmation response is returned, so it does not reintroduce an account-existence oracle (a registered and an unregistered address still get the same reply at the same speed); an address with no account still triggers no mint or send at all. A transient failure of the cooldown lookup falls through to sending, so a degraded datastore can't lock legitimate shoppers out of signing in.

package/SECURITY.md

@@ -319,17 +319,22 @@ node -e "
   (success / failure / denied) and paginated. Opening the log is itself
   recorded (an `audit.read` row), so reviewing the audit trail leaves
   its own forensic mark.
-- **The gift-card, store-credit, and loyalty ledgers are hash-chained,
-  fork-proof, and verifiable.** Every ledger entry — credits, debits, and
-  expirations alike — links to its predecessor through a SHA3-512 chain,
-  keyed per card (gift cards) or per customer (store credit, loyalty), so
-  editing a row or deleting one from the middle breaks the linkage. A
-  uniqueness fence (one child per chain tip) makes concurrent writes
-  serialize rather than fork the chain, and each loyalty / gift-card /
-  store-credit balance change is written in that same single guarded row,
-  so a points or balance mutation is exactly-once even on a backend without
-  interactive transactions. `giftCardLedger.verifyChain(cardId)` /
-  `storeCredit.verifyChain(customerId)` / `loyalty.verifyChain(customerId)`
+- **The gift-card, store-credit, loyalty, and affiliate-commission ledgers
+  are hash-chained, fork-proof, and verifiable.** Every ledger entry — credits,
+  debits, and expirations alike — links to its predecessor through a SHA3-512
+  chain, keyed per card (gift cards), per customer (store credit, loyalty), or
+  per affiliate (commissions), so editing a row or deleting one from the middle
+  breaks the linkage. A uniqueness fence (one child per chain tip) makes
+  concurrent writes serialize rather than fork the chain, and each loyalty /
+  gift-card / store-credit balance change is written in that same single guarded
+  row, so a points or balance mutation is exactly-once even on a backend without
+  interactive transactions. The affiliate-commission chain hashes only the
+  immutable money facts (order, affiliate, totals, currency, time), so a
+  commission walking its pending → paid → voided payout lifecycle never breaks
+  the chain while inflating an amount or deleting a row still does.
+  `giftCardLedger.verifyChain(cardId)` /
+  `storeCredit.verifyChain(customerId)` / `loyalty.verifyChain(customerId)` /
+  `affiliates.verifyChain(affiliateId)`
   recompute a ledger's chain end to end and report the first divergence — run them whenever a balance is
   disputed; pass a trusted anchor (a row count + head hash from an earlier
   snapshot) to also catch a truncation that deletes the most-recent rows,

package/lib/affiliates.js

@@ -336,6 +336,56 @@ function _normalizeEmail(input) {
 
 function _now() { return Date.now(); }
 
+// ---- commission tamper-evidence chain -----------------------------------
+
+// SHA3-512 hex width + the all-zero genesis anchor every affiliate's chain
+// links its first commission off.
+var SHA3_512_HEX_LEN = 128;
+var ZERO_HASH        = "0".repeat(SHA3_512_HEX_LEN);
+
+// The IMMUTABLE money facts a commission row's hash attests. The lifecycle
+// columns (status / paid_at / voided_at / payout_reference / void_reason) are
+// deliberately EXCLUDED — they are stamped in place as a commission walks
+// pending -> paid -> voided, and hashing them would break the chain on every
+// legitimate payout. Only the facts that must never change after the
+// commission is recorded are bound.
+function _commissionHashFields(row) {
+  return {
+    id:                row.id,
+    order_id:          row.order_id,
+    affiliate_id:      row.affiliate_id,
+    order_total_minor: Number(row.order_total_minor),
+    commission_minor:  Number(row.commission_minor),
+    currency:          row.currency,
+    occurred_at:       Number(row.occurred_at),
+  };
+}
+
+// row_hash = SHA3-512(prev_hash-bytes || canonical-json(immutable fields)),
+// the same construction the gift-card / store-credit / loyalty ledgers use
+// (b.auditChain.canonicalize is the RFC 8785 sorted-key walker).
+function _commissionRowHash(prevHash, fields) {
+  var canonical = b.auditChain.canonicalize(fields, ["prev_hash", "row_hash"]);
+  var preimage  = Buffer.concat([
+    Buffer.from(prevHash, "hex"),
+    Buffer.from(canonical, "utf8"),
+  ]);
+  return b.crypto.sha3Hash(preimage);
+}
+
+// How many times recordCommissionEvent re-derives the chain tip when the
+// parent fence refuses its INSERT (a competing commission for the SAME
+// affiliate landed first). Each fence round lets exactly one racing writer
+// win, so a burst of N concurrent commissions for one affiliate needs up to N
+// rounds — the cap is the max same-affiliate fan-in that fully succeeds, so it
+// is sized for the PER-AFFILIATE chain: unlike a gift-card chain (one
+// customer's wallet), an affiliate's chain aggregates order completions across
+// every customer they referred, so a large affiliate during a campaign spike
+// can drive many near-simultaneous commissions. 256 covers that with wide
+// margin; AFFILIATE_COMMISSION_CONTENTION (thrown past the cap) is a retryable
+// signal, never silent loss — the caller may re-invoke for that order.
+var COMMISSION_CHAIN_ATTEMPTS = 256;
+
 // ---- code generation + canonicalization ---------------------------------
 
 function _generateCode() {
@@ -446,6 +496,28 @@ function create(opts) {
     return r.rows[0] || null;
   }
 
+  // The affiliate's current chain tip — the highest-chain_index commission's
+  // row_hash (the next commission links off it as its prev_hash) plus that
+  // chain_index. Ordering by chain_index (not occurred_at) keeps the read order
+  // equal to the prev_hash linkage WITHOUT touching the operator's timestamp.
+  // The `(chain_index IS NULL) ASC` key prefers any chained row over a legacy
+  // NULL row, so once the chain has anchored the tip is always a hashed row; an
+  // affiliate with only legacy pre-chain rows (NULL chain_index / NULL row_hash)
+  // anchors fresh from genesis (ZERO_HASH, index -1 so the first child is 0).
+  async function _readCommissionTip(affiliateId) {
+    var r = await query(
+      "SELECT row_hash, chain_index FROM affiliate_commissions WHERE affiliate_id = ?1 " +
+      "ORDER BY (chain_index IS NULL) ASC, chain_index DESC, id DESC LIMIT 1",
+      [affiliateId],
+    );
+    if (!r.rows.length) return { row_hash: ZERO_HASH, chain_index: -1 };
+    var row = r.rows[0];
+    if (row.chain_index == null || row.row_hash == null) {
+      return { row_hash: ZERO_HASH, chain_index: -1 };
+    }
+    return { row_hash: row.row_hash, chain_index: Number(row.chain_index) };
+  }
+
   // Inserting an affiliate row. Code generation retries on UNIQUE
   // violation up to a small bound; on the 32^8 space the chance of
   // running out is vanishingly low, but the retry keeps the boot
@@ -818,32 +890,56 @@ function create(opts) {
         aff.commission_kind, Number(aff.commission_value), orderTotal
       );
 
-      var id = b.uuid.v7();
-      try {
-        await query(
-          "INSERT INTO affiliate_commissions " +
-          "(id, order_id, affiliate_id, order_total_minor, commission_minor, " +
-          " currency, status, occurred_at, paid_at, voided_at, payout_reference, void_reason) " +
-          "VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'pending', ?7, NULL, NULL, NULL, NULL)",
-          [id, orderId, affiliateId, orderTotal, commissionMinor, currency, occurredAt],
-        );
-      } catch (e) {
-        // Concurrent recordCommissionEvent for the same (order_id,
-        // affiliate_id): the pre-read above missed a racing insert, so this
-        // writer loses on the UNIQUE constraint. Matching on the error MESSAGE
-        // is unreliable — the production D1 service-binding redacts the SQLite
-        // "UNIQUE constraint failed" text to a generic "HTTP 500" — so converge
-        // message-agnostically: re-read, and if the row now exists the failure
-        // was the duplicate, so return it (idempotent). If no row exists the
-        // insert failed for some other reason, so re-throw.
-        var raced = await query(
-          "SELECT * FROM affiliate_commissions WHERE order_id = ?1 AND affiliate_id = ?2",
-          [orderId, affiliateId],
-        );
-        if (raced.rows.length) return raced.rows[0];
-        throw e;
+      // Append to the affiliate's tamper-evidence chain under the parent fence
+      // (UNIQUE(affiliate_id, prev_hash), migration 0238): the row links off the
+      // affiliate's current tip, and a write derived from a STALE tip collides
+      // instead of forking the chain — so we re-read the tip and retry. Two
+      // UNIQUE constraints can refuse this INSERT, and the production D1
+      // service-binding redacts the SQLite "UNIQUE constraint failed" text to a
+      // generic "HTTP 500", so converge MESSAGE-AGNOSTICALLY: (1) re-read by
+      // (order_id, affiliate_id) — if a row now exists, this was the idempotency
+      // duplicate, return it; (2) else re-read the chain tip — if it advanced
+      // past the parent we tried to chain off, a competing commission for this
+      // affiliate claimed our slot, so retry; (3) else the insert failed for an
+      // unrelated reason, re-throw.
+      for (var attempt = 0; attempt < COMMISSION_CHAIN_ATTEMPTS; attempt += 1) {
+        var tip        = await _readCommissionTip(affiliateId);
+        var prevHash   = tip.row_hash;
+        var chainIndex = tip.chain_index + 1;
+        var id = b.uuid.v7();
+        var rowHash = _commissionRowHash(prevHash, {
+          id:                id,
+          order_id:          orderId,
+          affiliate_id:      affiliateId,
+          order_total_minor: orderTotal,
+          commission_minor:  commissionMinor,
+          currency:          currency,
+          occurred_at:       occurredAt,
+        });
+        try {
+          await query(
+            "INSERT INTO affiliate_commissions " +
+            "(id, order_id, affiliate_id, order_total_minor, commission_minor, " +
+            " currency, status, occurred_at, paid_at, voided_at, payout_reference, void_reason, " +
+            " prev_hash, row_hash, chain_index) " +
+            "VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'pending', ?7, NULL, NULL, NULL, NULL, ?8, ?9, ?10)",
+            [id, orderId, affiliateId, orderTotal, commissionMinor, currency, occurredAt, prevHash, rowHash, chainIndex],
+          );
+          return await _getCommissionRaw(id);
+        } catch (e) {
+          var raced = await query(
+            "SELECT * FROM affiliate_commissions WHERE order_id = ?1 AND affiliate_id = ?2",
+            [orderId, affiliateId],
+          );
+          if (raced.rows.length) return raced.rows[0];
+          var newTip = await _readCommissionTip(affiliateId);
+          if (newTip.row_hash !== prevHash) continue;
+          throw e;
+        }
       }
-      return await _getCommissionRaw(id);
+      var contention = new Error("affiliates.recordCommissionEvent: persistent commission-chain contention — retry the write");
+      contention.code = "AFFILIATE_COMMISSION_CONTENTION";
+      throw contention;
     },
 
     commissionsForAffiliate: async function (listOpts) {
@@ -1004,6 +1100,110 @@ function create(opts) {
       return await _getCommissionRaw(id);
     },
 
+    // Recompute one affiliate's commission hash chain and flag the first
+    // divergence — the tamper-evidence READ side of the chain recordCommission-
+    // Event maintains. Walks the affiliate's rows in (occurred_at, id) order
+    // over the IMMUTABLE money fields only (lifecycle columns are not hashed, so
+    // a paid/voided transition is not a break). Rows from before the chain
+    // existed (NULL row_hash) are tolerated as an unverifiable legacy PREFIX and
+    // counted, but once a hashed row appears every later row must link — an
+    // unhashed row after the anchor, a prev_hash that doesn't name its parent,
+    // or a row_hash that doesn't recompute is a break. A populated ledger that
+    // never anchors (every row NULL-hashed — what a full rewrite leaves behind)
+    // fails as unanchored; only a genuinely empty ledger passes with no anchor.
+    // An optional trusted anchor { count, head } rules out a tail truncation.
+    // O(n) per affiliate; operator-audit use, not hot-path.
+    verifyChain: async function (affiliateId, opts) {
+      var aff = _uuid(affiliateId, "affiliate_id");
+      opts = opts || {};
+      var anchor = null;
+      if (opts.anchor != null) {
+        if (typeof opts.anchor !== "object"
+            || typeof opts.anchor.count !== "number" || !Number.isInteger(opts.anchor.count) || opts.anchor.count < 1
+            || typeof opts.anchor.head !== "string" || opts.anchor.head.length !== SHA3_512_HEX_LEN) {
+          throw new TypeError("affiliates.verifyChain: anchor must be { count: positive integer, head: " + SHA3_512_HEX_LEN + "-hex-char string }");
+        }
+        anchor = opts.anchor;
+      }
+      // Walk in chain order: the legacy NULL-chain_index prefix first (sorted by
+      // id for a stable count), then the hashed chain by chain_index. This is
+      // the prev_hash linkage order independent of occurred_at, so a backdated
+      // commission verifies in its chain position, not its timestamp position.
+      var rows = (await query(
+        "SELECT * FROM affiliate_commissions WHERE affiliate_id = ?1 " +
+        "ORDER BY (chain_index IS NULL) DESC, chain_index ASC, id ASC",
+        [aff],
+      )).rows;
+      var legacyPrefix = 0;
+      var anchored = false;
+      var prevHash = ZERO_HASH;
+      for (var i = 0; i < rows.length; i += 1) {
+        var row = rows[i];
+        if (!anchored && row.row_hash == null) { legacyPrefix += 1; continue; }
+        anchored = true;
+        var breakBase = {
+          ok:            false,
+          rows_verified: i - legacyPrefix,
+          legacy_prefix: legacyPrefix,
+          break_at:      i,
+          break_row_id:  row.id,
+        };
+        if (row.row_hash == null) {
+          return Object.assign(breakBase, { reason: "unhashed row after chain anchor" });
+        }
+        if (row.prev_hash !== prevHash) {
+          return Object.assign(breakBase, { reason: "prev_hash mismatch", expected: prevHash, actual: row.prev_hash });
+        }
+        var computed = _commissionRowHash(prevHash, _commissionHashFields(row));
+        if (computed !== row.row_hash) {
+          return Object.assign(breakBase, { reason: "row_hash mismatch", expected: computed, actual: row.row_hash });
+        }
+        prevHash = row.row_hash;
+      }
+      if (!anchored && rows.length > 0) {
+        return {
+          ok:            false,
+          rows_verified: 0,
+          legacy_prefix: legacyPrefix,
+          break_at:      0,
+          break_row_id:  rows[0].id,
+          reason:        "unanchored chain (no hashed row in a populated ledger)",
+        };
+      }
+      if (anchor) {
+        if (rows.length < anchor.count) {
+          return {
+            ok:             false,
+            rows_verified:  rows.length - legacyPrefix,
+            legacy_prefix:  legacyPrefix,
+            anchor_checked: true,
+            reason:         "row count below anchor (possible tail truncation)",
+            expected_count: anchor.count,
+            actual_count:   rows.length,
+          };
+        }
+        var anchorRow = rows[anchor.count - 1];
+        if (!anchorRow || anchorRow.row_hash !== anchor.head) {
+          return {
+            ok:             false,
+            rows_verified:  rows.length - legacyPrefix,
+            legacy_prefix:  legacyPrefix,
+            anchor_checked: true,
+            reason:         "anchor row hash mismatch (possible tail truncation or divergence)",
+            expected:       anchor.head,
+            actual:         anchorRow ? anchorRow.row_hash : null,
+          };
+        }
+      }
+      return {
+        ok:             true,
+        rows_verified:  rows.length - legacyPrefix,
+        legacy_prefix:  legacyPrefix,
+        head:           prevHash,
+        anchor_checked: !!anchor,
+      };
+    },
+
     // Operator dashboard — which affiliates are owed at least
     // `min_payout_minor` as of `as_of`. Returns one row per affiliate
     // whose sum-of-pending commissions (occurred_at <= as_of) meets

package/lib/asset-manifest.json

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

package/package.json

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