@blamejs/blamejs-shop 0.3.35 → 0.3.36

package/lib/storefront.js

@@ -3462,6 +3462,206 @@ function renderReturns(opts) {
   });
 }
 
+// Customer-facing reasons for an exchange. The values mirror the
+// order-exchanges module's REASONS allow-list; the backend validates the
+// submitted value against its own list, so a forged value is refused
+// there. (No-longer-needed isn't an exchange reason — that's a return.)
+var EXCHANGE_REASONS = [
+  ["defective", "Defective / doesn't work"],
+  ["wrong-item", "Wrong item received"],
+  ["wrong-size", "Wrong size"],
+  ["wrong-colour", "Wrong colour"],
+  ["damaged-in-transit", "Damaged in transit"],
+  ["not-as-described", "Not as described"],
+  ["other", "Other"],
+];
+
+// Customer-facing phrasing for an exchange's FSM status. The module's
+// enum (pending / approved / shipped / delivered / received / closed /
+// rejected) is operator vocabulary; these read for the shopper.
+var EXCHANGE_STATUS_LABELS = {
+  pending:   "Requested",
+  approved:  "Approved",
+  shipped:   "Replacement shipped",
+  delivered: "Replacement delivered",
+  received:  "Return received",
+  closed:    "Completed",
+  rejected:  "Declined",
+};
+
+function _exchangeStatusBadge(status) {
+  var esc = b.template.escapeHtml;
+  var label = EXCHANGE_STATUS_LABELS[status] || status;
+  return "<span class=\"return-status return-status--" + esc(String(status)) + "\">" +
+    esc(String(label)) + "</span>";
+}
+
+// Customer-facing exchange-request form for one owned order. `opts.lines`
+// is the order's order_lines, each decorated with `replacement_options`
+// (the sibling variants of that line's product the shopper can swap to).
+// `opts.notice` is an optional error bounced back from a failed POST.
+// Reuses the returns-form layout classes — no new CSS.
+function renderExchangeForm(opts) {
+  var esc = b.template.escapeHtml;
+  var order = opts.order;
+  var lines = opts.lines || [];
+  var lineRows = "";
+  for (var i = 0; i < lines.length; i += 1) {
+    var l = lines[i];
+    var maxQty = Number(l.qty) || 1;
+    var replOpts = (l.replacement_options || []).map(function (o) {
+      return "<option value=\"" + esc(String(o.id)) + "\">" + esc(String(o.label)) + "</option>";
+    }).join("");
+    // A line with no resolvable sibling variants can't be exchanged for a
+    // different option — offer a same-SKU swap (replace a defective unit)
+    // so the line is never silently undisplayable.
+    var replaceField = replOpts
+      ? "<label class=\"return-line__qty\">Swap for " +
+          "<select name=\"replacement_" + esc(l.id) + "\">" + replOpts + "</select>" +
+        "</label>"
+      : "<p class=\"return-line__of\">Same item, replacement unit.</p>";
+    lineRows +=
+      "<li class=\"return-line\">" +
+        "<label class=\"return-line__pick\">" +
+          "<input type=\"radio\" name=\"line_id\" value=\"" + esc(l.id) + "\"" + (i === 0 ? " checked" : "") + ">" +
+          "<span class=\"return-line__sku\"><code>" + esc(l.sku) + "</code></span>" +
+        "</label>" +
+        "<label class=\"return-line__qty\">Qty to exchange " +
+          "<input type=\"number\" name=\"qty_" + esc(l.id) + "\" value=\"1\" min=\"1\" max=\"" + maxQty + "\">" +
+          " <span class=\"return-line__of\">of " + maxQty + "</span>" +
+        "</label>" +
+        replaceField +
+      "</li>";
+  }
+  var reasonOpts = EXCHANGE_REASONS.map(function (r) {
+    return "<option value=\"" + esc(r[0]) + "\">" + esc(r[1]) + "</option>";
+  }).join("");
+  var notice = opts.notice
+    ? "<p class=\"form-notice form-notice--error\" role=\"alert\">" + esc(String(opts.notice)) + "</p>"
+    : "";
+  var body =
+    "<section class=\"return-form-page\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li><a href=\"/account/exchanges\">Exchanges</a></li>" +
+        "<li aria-current=\"page\">Request an exchange</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"return-form-page__title\">Request an exchange</h1>" +
+      "<p class=\"return-form-page__order\">Order <code>" + esc(order.id) + "</code></p>" +
+      notice +
+      "<form class=\"return-form form-stack\" method=\"post\" action=\"/account/orders/" + esc(order.id) + "/exchange\">" +
+        "<fieldset class=\"return-form__lines\"><legend>Which item?</legend>" +
+          "<ul class=\"return-line-list\">" + lineRows + "</ul>" +
+        "</fieldset>" +
+        "<label class=\"form-field\"><span class=\"form-field__label\">Reason</span>" +
+          "<select name=\"reason\" required>" + reasonOpts + "</select></label>" +
+        "<button type=\"submit\" class=\"btn-primary\">Request exchange</button>" +
+      "</form>" +
+    "</section>";
+  return _wrap({
+    title:      "Request an exchange",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
+// The signed-in customer's exchange list. `opts.exchanges` is the
+// ownership-scoped set (already filtered to this customer's orders); each
+// links to its status detail.
+function renderExchanges(opts) {
+  var esc = b.template.escapeHtml;
+  var exchanges = opts.exchanges || [];
+  var rowsHtml = "";
+  for (var i = 0; i < exchanges.length; i += 1) {
+    var x = exchanges[i];
+    var date = x.created_at ? new Date(Number(x.created_at)).toISOString().slice(0, 10) : "";
+    rowsHtml +=
+      "<li class=\"return-card\">" +
+        "<div class=\"return-card__head\">" +
+          "<a class=\"return-card__rma\" href=\"/account/exchanges/" + esc(String(x.id)) + "\"><code>" + esc(String(x.id).slice(0, 8)) + "</code></a>" +
+          _exchangeStatusBadge(x.status) +
+        "</div>" +
+        "<p class=\"return-card__meta\">" +
+          esc(String(x.return_sku || "")) + " &rarr; " + esc(String(x.replacement_sku || "")) +
+          (date ? " &middot; <time datetime=\"" + esc(date) + "\">" + esc(date) + "</time>" : "") +
+        "</p>" +
+        (x.status === "rejected" && x.reject_reason ? "<p class=\"return-card__reject\">" + esc(String(x.reject_reason)) + "</p>" : "") +
+      "</li>";
+  }
+  var inner = rowsHtml
+    ? "<ul class=\"return-list\">" + rowsHtml + "</ul>"
+    : "<div class=\"account-empty\">" +
+        "<p class=\"account-empty__lede\">No exchanges yet. Start one from an order in your account.</p>" +
+        "<a class=\"btn-secondary\" href=\"/account/orders\">View your orders &rarr;</a>" +
+      "</div>";
+  var notice = opts.requested
+    ? "<p class=\"form-notice form-notice--ok\" role=\"status\">Exchange request received — we'll review it and email you next steps.</p>"
+    : "";
+  var body =
+    "<section class=\"account-returns\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li aria-current=\"page\">Exchanges</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"account-returns__title\">Exchanges</h1>" +
+      notice +
+      inner +
+    "</section>";
+  return _wrap({
+    title:      "Exchanges",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
+// One exchange's status detail. Ownership-scoped (the route only renders
+// this for an exchange whose parent order belongs to the session
+// customer). Surfaces the swap, the reason, the live status, the
+// rejection reason (if declined), and the outbound tracking number once
+// the replacement has shipped.
+function renderExchangeDetail(opts) {
+  var esc = b.template.escapeHtml;
+  var x = opts.exchange;
+  var date = x.created_at ? new Date(Number(x.created_at)).toISOString().slice(0, 10) : "";
+  var rows = "";
+  function _row(label, value) {
+    return "<p class=\"return-card__meta\"><span class=\"form-field__label\">" + esc(label) + "</span> " +
+      (value ? esc(String(value)) : "&mdash;") + "</p>";
+  }
+  rows += _row("Item returned", x.return_sku + " ×" + x.return_qty);
+  rows += _row("Replacement", x.replacement_sku + " ×" + x.replacement_qty);
+  rows += _row("Reason", x.reason);
+  if (date) rows += _row("Requested", date);
+  if (x.status === "rejected" && x.reject_reason) rows += _row("Why it was declined", x.reject_reason);
+  if (x.tracking_number) {
+    rows += _row("Replacement tracking", x.carrier ? (x.carrier + " · " + x.tracking_number) : x.tracking_number);
+  }
+  var body =
+    "<section class=\"account-returns\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li><a href=\"/account/exchanges\">Exchanges</a></li>" +
+        "<li aria-current=\"page\">" + esc(String(x.id).slice(0, 8)) + "</li>" +
+      "</ol></nav>" +
+      "<div class=\"return-card__head\">" +
+        "<h1 class=\"account-returns__title\">Exchange <code>" + esc(String(x.id).slice(0, 8)) + "</code></h1>" +
+        _exchangeStatusBadge(x.status) +
+      "</div>" +
+      "<div class=\"return-card\">" + rows + "</div>" +
+    "</section>";
+  return _wrap({
+    title:      "Exchange " + String(x.id).slice(0, 8),
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 // Support ticket — the categories a shopper can pick when raising one,
 // and the human label for each. The values mirror the support-tickets
 // module's ALLOWED_CATEGORIES; the backend validates the submitted value
@@ -5255,6 +5455,17 @@ function _orderEligibleForReturn(status) {
     status === "shipped" || status === "delivered";
 }
 
+// An exchange (swap the item for a different size / colour / unit at the
+// same value) is offered on the same window as a return: a paid (or
+// further-along) order, never a still-pending (unpaid) one nor the
+// terminal off-ramps (cancelled / refunded). The customer ships the
+// original back AND receives a replacement — no refund — so the window
+// matches the goods being in the customer's hands.
+function _orderEligibleForExchange(status) {
+  return status === "paid" || status === "fulfilling" ||
+    status === "shipped" || status === "delivered";
+}
+
 // Reorder is offered for any order that represents a real purchase the
 // customer might want to repeat — paid through delivered, plus the
 // terminal refunded/cancelled states (a cancelled or refunded order is a
@@ -5378,6 +5589,10 @@ function _orderActionsBlock(o) {
     btns.push(
       "<a class=\"btn-secondary order-action\" href=\"/account/orders/" + esc(String(o.id)) + "/return\">Request a return</a>");
   }
+  if (_orderEligibleForExchange(o.status)) {
+    btns.push(
+      "<a class=\"btn-secondary order-action\" href=\"/account/orders/" + esc(String(o.id)) + "/exchange\">Request an exchange</a>");
+  }
   if (_orderEligibleForCancel(o.status)) {
     btns.push(
       "<form class=\"order-action\" method=\"post\" action=\"/orders/" + esc(String(o.id)) + "/cancel\">" +
@@ -6641,6 +6856,7 @@ var ACCOUNT_DASH_PAGE =
   "      <a class=\"btn-secondary\" href=\"/account/recently-viewed\">Recently viewed</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/addresses\">Addresses</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/returns\">Returns</a>\n" +
+  "      <a class=\"btn-secondary\" href=\"/account/exchanges\">Exchanges</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/support\">Support</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/loyalty\">Rewards</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/credit\">Store credit</a>\n" +
@@ -11769,6 +11985,240 @@ function mount(router, deps) {
       });
     }
 
+    // Self-serve exchanges — a customer requests a same-value item SWAP
+    // (different size / colour / unit) against one of their own orders and
+    // tracks its status; operators action it via the admin /admin/exchanges
+    // queue. Distinct from returns (which end in a refund): an exchange
+    // ships the original back AND a replacement out, no money refunded.
+    //
+    // Ownership / IDOR: an order_exchanges row carries `order_id` but NOT
+    // `customer_id` — the customer→order linkage lives on the order. So
+    // every per-exchange / per-order route here loads the parent order and
+    // refuses (clean 404) unless `order.customer_id === auth.customer_id`,
+    // exactly like the returns + support gates. The exchange primitive
+    // moves a row by id alone, so the route owns the ownership decision.
+    if (deps.orderExchanges && deps.order) {
+      function _exchangeAuth(req, res) {
+        var auth;
+        try { auth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") { _serviceUnavailable(res, "auth not configured"); return null; }
+          throw e;
+        }
+        if (!auth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          res.end ? res.end() : res.send("");
+          return null;
+        }
+        return auth;
+      }
+
+      // Load the order named in :order_id and confirm it belongs to the
+      // signed-in customer. A malformed id (guardUuid TypeError), a missing
+      // order, or someone else's order all return 404 — never a 500, never
+      // a leak. This is the ownership gate the request form + POST funnel
+      // through.
+      async function _ownedOrderForExchange(req, res, auth) {
+        var order;
+        try { order = await deps.order.get(req.params && req.params.order_id); }
+        catch (e) {
+          if (e instanceof TypeError) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+          throw e;
+        }
+        if (!order || order.customer_id !== auth.customer_id) {
+          _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+          return null;
+        }
+        return order;
+      }
+
+      // Load the exchange named in :id, then load its parent order and
+      // confirm THAT order belongs to the signed-in customer. The exchange
+      // row has no customer_id, so ownership is asserted transitively
+      // through the order. A malformed id (TypeError), an unknown exchange,
+      // an exchange whose order is gone, or an exchange owned by someone
+      // else ALL return 404 — never a 500, never a cross-customer reveal.
+      async function _ownedExchange(req, res, auth) {
+        var exchange;
+        try { exchange = await deps.orderExchanges.getExchange(req.params && req.params.id); }
+        catch (e) {
+          if (e instanceof TypeError) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+          throw e;
+        }
+        if (!exchange) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+        var order;
+        try { order = await deps.order.get(exchange.order_id); }
+        catch (e) {
+          if (e instanceof TypeError) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+          throw e;
+        }
+        if (!order || order.customer_id !== auth.customer_id) {
+          _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+          return null;
+        }
+        return exchange;
+      }
+
+      // Resolve the sibling variants a line's product can be swapped to:
+      // every active variant of the same product, labelled by its option
+      // values (falling back to the SKU). Best-effort — absent the catalog
+      // handle (or a read failure) the line offers a same-SKU swap.
+      async function _replacementOptions(line) {
+        if (!deps.catalog || !line || !line.variant_id) return [];
+        try {
+          var v = await deps.catalog.variants.get(line.variant_id);
+          if (!v) return [];
+          var siblings = await deps.catalog.variants.listForProduct(v.product_id);
+          return (siblings || []).map(function (s) {
+            var optLabel = s.options
+              ? Object.keys(s.options).map(function (k) { return s.options[k]; }).join(" / ")
+              : "";
+            var label = (optLabel ? optLabel + " — " : "") + s.sku;
+            return { id: s.id, sku: s.sku, label: label };
+          });
+        } catch (_e) { return []; }
+      }
+
+      // The customer's own exchange list, scoped to their orders. The
+      // primitive resolves the customer→order linkage through the injected
+      // order handle, so a foreign order's exchange never appears here.
+      router.get("/account/exchanges", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var exchanges = [];
+        try { exchanges = await deps.orderExchanges.exchangesForCustomer(auth.customer_id, { limit: 100 }); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; exchanges = []; }
+        var cartCount = await _cartCountForReq(req);
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _send(res, 200, renderExchanges({
+          exchanges:  exchanges,
+          requested:  url && url.searchParams.get("ok") === "1",
+          shop_name:  shopName,
+          cart_count: cartCount,
+        }));
+      });
+
+      // One exchange's status detail. Ownership-scoped through the parent
+      // order (foreign / unknown → 404).
+      router.get("/account/exchanges/:id", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var exchange = await _ownedExchange(req, res, auth); if (!exchange) return;
+        var cartCount = await _cartCountForReq(req);
+        _send(res, 200, renderExchangeDetail({ exchange: exchange, shop_name: shopName, cart_count: cartCount }));
+      });
+
+      // The exchange-request form for one of the customer's own orders,
+      // gated on the same eligibility window as a return.
+      router.get("/account/orders/:order_id/exchange", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var order = await _ownedOrderForExchange(req, res, auth); if (!order) return;
+        var cartCount = await _cartCountForReq(req);
+        if (!_orderEligibleForExchange(order.status)) {
+          return _send(res, 400, renderExchangeForm({
+            order: order, lines: [], notice: "This order isn't eligible for an exchange.",
+            shop_name: shopName, cart_count: cartCount,
+          }));
+        }
+        var lines = [];
+        var orderLines = order.lines || [];
+        for (var i = 0; i < orderLines.length; i += 1) {
+          var ol = orderLines[i];
+          lines.push(Object.assign({}, ol, { replacement_options: await _replacementOptions(ol) }));
+        }
+        _send(res, 200, renderExchangeForm({ order: order, lines: lines, shop_name: shopName, cart_count: cartCount }));
+      });
+
+      router.post("/account/orders/:order_id/exchange", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var order = await _ownedOrderForExchange(req, res, auth); if (!order) return;
+        var body = req.body || {};
+        var cartCount = await _cartCountForReq(req);
+
+        // Re-decorate the lines so a failed POST re-renders the same form
+        // (with the replacement pickers intact) rather than a bare page.
+        async function _decoratedLines() {
+          var out = [];
+          var ols = order.lines || [];
+          for (var i = 0; i < ols.length; i += 1) {
+            out.push(Object.assign({}, ols[i], { replacement_options: await _replacementOptions(ols[i]) }));
+          }
+          return out;
+        }
+        function _badForm(notice, status) {
+          return _decoratedLines().then(function (lines) {
+            return _send(res, status || 400, renderExchangeForm({
+              order: order, lines: lines, notice: notice,
+              shop_name: shopName, cart_count: cartCount,
+            }));
+          });
+        }
+
+        if (!_orderEligibleForExchange(order.status)) {
+          return _badForm("This order isn't eligible for an exchange.");
+        }
+
+        // Resolve the picked line from the order's OWN lines (authoritative
+        // sku/qty) — never trust a client-supplied sku. The radio carries
+        // the order_line id.
+        var orderLines = order.lines || [];
+        var picked = null;
+        for (var i = 0; i < orderLines.length; i += 1) {
+          if (orderLines[i].id === body.line_id) { picked = orderLines[i]; break; }
+        }
+        if (!picked) return _badForm("Pick the item you'd like to exchange.");
+
+        var wantedQty = parseInt(body["qty_" + picked.id], 10);
+        var maxQty = Number(picked.qty) || 1;
+        var qty = Number.isFinite(wantedQty) && wantedQty >= 1 && wantedQty <= maxQty ? wantedQty : maxQty;
+
+        // The replacement variant: the chosen sibling variant of the same
+        // product. The select carries the variant id; resolve it back to a
+        // sku through the catalog (never trust a client sku). Absent a
+        // selection (a same-SKU swap — replace a defective unit) the
+        // replacement defaults to the line's own sku/variant.
+        var replacementSku = picked.sku;
+        var replacementVariantId = picked.variant_id;
+        var chosen = body["replacement_" + picked.id];
+        if (chosen && deps.catalog) {
+          // The replacement MUST be one of the sibling variants offered for
+          // the purchased line's product. Validate the chosen id against the
+          // same option set the form was built from (_replacementOptions) —
+          // resolving it through a bare variants.get would accept ANY catalog
+          // variant, letting a forged replacement_<id> swap a cheap item for
+          // any variant in the catalog. The option carries the catalog-
+          // resolved sku/id, so a client sku is never trusted.
+          var options = await _replacementOptions(picked);
+          var match = null;
+          for (var oi = 0; oi < options.length; oi += 1) {
+            if (options[oi].id === chosen) { match = options[oi]; break; }
+          }
+          if (!match) return _badForm("That replacement variant isn't available — pick another.");
+          replacementSku = match.sku;
+          replacementVariantId = match.id;
+        }
+
+        try {
+          await deps.orderExchanges.requestExchange({
+            order_id:               order.id,
+            line_id:                picked.id,
+            return_sku:             picked.sku,
+            return_qty:             qty,
+            replacement_sku:        replacementSku,
+            replacement_variant_id: replacementVariantId,
+            replacement_qty:        qty,
+            reason:                 body.reason,
+          });
+        } catch (e) {
+          if (e instanceof TypeError) {
+            return _badForm((e && e.message || "").replace(/^order-exchanges[.:]\s*/, "") || "Please check your exchange request.");
+          }
+          throw e;
+        }
+        res.status(303);
+        res.setHeader && res.setHeader("location", "/account/exchanges?ok=1");
+        return res.end ? res.end() : res.send("");
+      });
+    }
+
     // Support tickets — the signed-in customer raises a ticket, lists
     // their own, reads a thread, and replies. EVERY route is login-gated
     // AND scoped to the session customer's id: the support primitive

package/lib/vendor/MANIFEST.json

@@ -3,8 +3,8 @@
   "_about": "blamejs.shop vendors a single framework — blamejs — which itself bundles every server-side crypto/identity dependency. The transitive packages blamejs ships are surfaced in its own MANIFEST.json at lib/vendor/blamejs/lib/vendor/MANIFEST.json — Trivy / Grype rely on that nested data for CVE attribution.",
   "packages": {
     "blamejs": {
-      "version": "0.14.9",
-      "tag": "v0.14.9",
+      "version": "0.14.10",
+      "tag": "v0.14.10",
       "license": "Apache-2.0",
       "author": "blamejs contributors",
       "source": "https://github.com/blamejs/blamejs",
@@ -13,7 +13,7 @@
         "server": "lib/vendor/blamejs/"
       },
       "bundler": "shallow git clone of release tag from github.com/blamejs/blamejs",
-      "bundledAt": "2026-05-30"
+      "bundledAt": "2026-05-31"
     }
   }
 }

package/lib/vendor/blamejs/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.14.x
 
+- v0.14.10 (2026-05-31) — **Full-text-search token hashes move to a keyed MAC; existing mail-store search indexes rebuild automatically on upgrade.** The mail-store full-text-search index hashed its tokens with a hand-rolled salted-SHA3 derived hash. It now routes through the framework's sealed-column hashing primitive in keyed mode (HMAC-SHAKE256 off the per-deployment MAC key), so a search-index token hash is unforgeable and un-correlatable across deployments without that key — the same posture the sealed-column lookup hashes already use. Because the keyed hash changes the stored token values, a mail-store opened after upgrade detects its index as old-format and rebuilds it once from the sealed message rows. The rebuild runs under a format marker: the index is marked `rebuilding` before it is cleared and only marked current after every row is re-hashed inside an explicit transaction, and search falls back to its cursor path (rather than returning partial hits) whenever the marker is not current — so an interrupted rebuild leaves the old index intact and queryable and retries on the next open, never serving a half-built index. A new `b.cryptoField.computeNamespacedHash` primitive backs the keyed hashing for callers that hash outside the registered-column path. **Added:** *`b.cryptoField.computeNamespacedHash`* — A mode-aware namespaced hash for indexed-lookup callers that hash a value outside the registered-column derived-hash path. `computeNamespacedHash(ns, value, { mode, truncateBytes })` routes through the same engine as `computeDerived` — `salted-sha3` (default) or the keyed `hmac-shake256` — with optional hex truncation. The mail-store full-text index is the first consumer. **Changed:** *Mail-store full-text index rehashes to a keyed MAC on upgrade* — The full-text-search token hash now uses `b.cryptoField.computeNamespacedHash` in `hmac-shake256` mode instead of a hand-rolled salted-SHA3. The first time a store is opened after upgrade, its index is detected as old-format and rebuilt once from the sealed message rows; subsequent opens are no-ops. Search is unaffected once the rebuild completes. The rebuild requires the vault to be initialized and fails closed (a clear error) at construction if it is not, rather than leaving a stale searchable index. **Security:** *Keyed, un-correlatable full-text-search token hashes* — A search-index token hash is now a keyed MAC over a per-deployment key, not a static-salted digest — it cannot be forged or correlated across deployments without that key, closing the low-entropy-token correlation gap on the search index. The index remains unrecoverable from a database dump alone, as before. **Detectors:** *Hand-rolled lookup-hash check covers the split form* — The check that requires sealed-column lookup hashes to compose the framework primitive now also catches the across-lines hand-roll (`var salt = getDerivedHashSalt(); var hex = salt.toString(...); sha3(hex + ns + value)`), not only the single-expression form, so the bypass that the mail-store index used can't reappear. **Migration:** *Automatic, one-time full-text index rebuild* — No operator action is required: the rebuild runs automatically and idempotently on first open after upgrade, atomically and crash-safe (an interrupted rebuild keeps the old index and retries). The only requirement is that the vault is initialized before the mail-store is constructed. One caveat for shared stores: do not run a pre-upgrade and post-upgrade node against the same backend file concurrently across this format change — the old node would write old-format hashes the new node cannot match. Roll the deployment fully across the upgrade. This re-open condition is lifted once all nodes are on 0.14.10 or later.
+
 - v0.14.9 (2026-05-30) — **Corrects EU AI Act doc paths that named an uncallable namespace, plus source-comment hygiene and two new codebase checks.** A documentation fix and internal hygiene. The `@primitive` / `@signature` / `@example` blocks for the EU AI Act fundamental-rights-impact-assessment and GPAI training-data-summary helpers advertised `b.complianceAiAct.*`, which is undefined — the callable path is `b.compliance.aiAct.*` — so an operator copying the documented call got `undefined is not a function`. The documented paths now match the real surface. Alongside that: a duplicate parser entry in a doc block is removed, version stamps embedded in section-divider comments are stripped, and two codebase checks are added — one that fails the build when a `@primitive` block documents a wholly-unresolvable namespace (the gap that hid the AI Act paths), and one that flags a version stamp left inside a section divider. No exported API, error code, wire format, or runtime behaviour changes. **Changed:** *Source-comment hygiene* — Removed a duplicate `env` entry from the parsers `@module` doc block, and stripped internal version stamps (`vX.Y.Z`) from `// ---- ... ----` section-divider comments across several files, keeping the descriptive label. Comment-only; no behaviour change. **Fixed:** *EU AI Act helper documentation named an uncallable path* — `b.compliance.aiAct.fundamentalRightsImpactAssessment` and `b.compliance.aiAct.gpai.trainingDataSummary` were documented as `b.complianceAiAct.*` in their `@primitive` / `@signature` / `@example` blocks (and one returned reference string). `b.complianceAiAct` is undefined, so the documented call failed; the documented paths now match the callable surface. **Detectors:** *`@primitive` reachability covers wrong-namespace paths* — The reachability check previously only flagged a missing leaf on a resolved namespace; a `@primitive` whose entire dotted prefix is unresolvable (the shape that hid the AI Act doc paths) was silently skipped. It now walks each prefix segment and fails the build on any unresolvable one, while preserving the factory-instance-shorthand exemption. · *Version-stamp-in-divider check* — A new check flags a version stamp (`vX.Y.Z`) left immediately after a section divider's dashes (`// ---- vX.Y.Z ...`) — internal release vocabulary that does not belong in shipped source comments — without matching legitimate `@since` tags or prose version references.
 
 - v0.14.8 (2026-05-30) — **Source-comment and codebase-check hygiene, plus a new require-block alignment check; no API or behaviour changes.** Internal lint and comment cleanup with no operator-facing surface change. Several codebase-check comments and one stub helper name that described behaviour the check no longer has are corrected; an unused lint-suppression class and a set of stale duplicate-cluster qualifiers (functions that were since renamed or extracted) are pruned or re-pointed. Fifty-nine `// allow:` markers that named the byte-size or time-literal check on values those checks no longer flag are removed, and twenty self-negating rationales on markers the time check genuinely fires on are rewritten to say why the value coincidentally matches. A new codebase check holds top-of-file require blocks to consistent `=` column alignment, with the files that currently carry drift listed as a migration allowlist. No exported API, error code, wire format, or runtime behaviour changes. **Changed:** *Lint-suppression and codebase-check comment cleanup* — Corrected codebase-check comments that overstated their check's scope (a duplicate-code threshold described as three files when the advisory threshold is two, a narrowed byte-literal check carrying its pre-narrowing description, and a deferred-scan helper named as though it enforced a guarantee it does not yet provide). Removed an unused lint-suppression class and its one dead in-code marker, and pruned or re-pointed stale duplicate-cluster qualifiers that named functions since renamed or extracted into shared helpers. Removed fifty-nine `// allow:` markers that suppressed nothing, and rewrote twenty self-negating marker rationales (which read "not seconds" while sitting on a value the time check fires on) to explain the coincidental match. Source-comment and test hygiene only. **Detectors:** *Require-block `=` alignment check* — A new codebase check flags a top-of-file require block that mixes its `=` column alignment — a fittable line whose `=` drifts off the column the rest of the block shares. Compact single-space blocks are exempt (only blocks that declare alignment intent are checked), as are destructures and long names physically too wide to reach the column, and blank- or comment-separated tiers align independently. The files that currently carry such drift are an explicit migration allowlist, reflowed over time; new code is held to the rule.

package/lib/vendor/blamejs/api-snapshot.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
-  "frameworkVersion": "0.14.9",
-  "createdAt": "2026-05-31T03:42:29.026Z",
+  "frameworkVersion": "0.14.10",
+  "createdAt": "2026-05-31T10:40:06.680Z",
   "exports": {
     "a2a": {
       "type": "object",
@@ -14132,6 +14132,10 @@
           "type": "function",
           "arity": 3
         },
+        "computeNamespacedHash": {
+          "type": "function",
+          "arity": 3
+        },
         "declareColumnResidency": {
           "type": "function",
           "arity": 2
@@ -40497,6 +40501,14 @@
                 }
               }
             },
+            "FTS_FORMAT_VERSION": {
+              "type": "primitive",
+              "valueType": "number"
+            },
+            "FTS_HASH_BYTES": {
+              "type": "primitive",
+              "valueType": "number"
+            },
             "MAX_TOKENS_PER_FIELD": {
               "type": "primitive",
               "valueType": "number"

package/lib/vendor/blamejs/lib/crypto-field.js

@@ -235,6 +235,74 @@ function _computeDerivedHash(spec, tableMode, ns, normalized) {
   return sha3Hash(vault.getDerivedHashSalt().toString("hex") + ns + normalized);
 }
 
+/**
+ * @primitive b.cryptoField.computeNamespacedHash
+ * @signature b.cryptoField.computeNamespacedHash(ns, value, opts?)
+ * @since     0.14.10
+ * @compliance gdpr, hipaa
+ * @related   b.cryptoField.computeDerived, b.cryptoField.lookupHash
+ *
+ * Computes a namespaced indexed-lookup digest of `value` for a
+ * pseudo-field that is NOT backed by a registered derived-hash column
+ * (e.g. the sealed-token FTS index in `b.mailStore.fts`). The caller
+ * supplies the full namespace string directly — there is no schema
+ * lookup — so the same keyed/salted hash machinery that protects
+ * registered derived hashes also covers ad-hoc indexed tokens. This is
+ * the canonical entry point: hand-rolling
+ * `sha3Hash(vault.getDerivedHashSalt() + ns + value)` at a call site
+ * bypasses the keyed-MAC mode (`hmac-shake256` off
+ * `vault.getDerivedHashMacKey`) and the per-deployment salt policy.
+ *
+ * `opts.mode` selects the digest:
+ *   - `"salted-sha3"` (default): SHA3-512 over `<salt-hex> + ns + value`
+ *     (deterministic per deployment; byte-identical to the legacy
+ *     hand-rolled scheme).
+ *   - `"hmac-shake256"`: SHAKE256(`<vault MAC key> || ns + value`) — a
+ *     keyed MAC so an attacker who recovers the salt alone cannot
+ *     correlate two low-entropy plaintexts.
+ *
+ * `opts.truncateBytes` truncates the hex digest to that many BYTES
+ * (the hex string is sliced to `truncateBytes * 2` characters). Throws
+ * (config-time / entry-point tier) on an unknown `mode` or a
+ * non-positive-integer `truncateBytes` so an operator catches the typo
+ * at boot rather than silently indexing under a malformed digest.
+ *
+ * @opts
+ *   mode:          string,   // "salted-sha3" (default) | "hmac-shake256"
+ *   truncateBytes: number,   // optional; positive integer byte width to slice to
+ *
+ * @example
+ *   var ns = "bj-mail_messages-body:fts:";
+ *   var h = b.cryptoField.computeNamespacedHash(ns, "kubernetes", {
+ *     mode: "hmac-shake256", truncateBytes: 8
+ *   });
+ *   /^[0-9a-f]{16}$/.test(h);   // → true
+ *
+ *   // Default mode is byte-identical to the legacy salted-sha3 hash.
+ *   b.cryptoField.computeNamespacedHash(ns, "kubernetes").length;   // → 128
+ */
+function computeNamespacedHash(ns, value, opts) {
+  opts = opts || {};
+  var mode = opts.mode || "salted-sha3";
+  if (mode !== "salted-sha3" && mode !== "hmac-shake256") {
+    throw new Error("computeNamespacedHash: opts.mode must be 'salted-sha3' " +
+      "(default) or 'hmac-shake256', got " + JSON.stringify(mode));
+  }
+  var truncateBytes = opts.truncateBytes;
+  if (truncateBytes !== undefined) {
+    if (typeof truncateBytes !== "number" || !isFinite(truncateBytes) ||
+        truncateBytes <= 0 || Math.floor(truncateBytes) !== truncateBytes) {
+      throw new Error("computeNamespacedHash: opts.truncateBytes must be a " +
+        "positive integer (bytes), got " + JSON.stringify(truncateBytes));
+    }
+  }
+  var hex = _computeDerivedHash({ mode: mode }, mode, ns, String(value));
+  if (truncateBytes !== undefined) {
+    return hex.slice(0, truncateBytes * 2);
+  }
+  return hex;
+}
+
 /**
  * @primitive b.cryptoField.getSchema
  * @signature b.cryptoField.getSchema(table)
@@ -1046,6 +1114,7 @@ module.exports = {
   applyPosture:     applyPosture,
   getActivePosture: getActivePosture,
   computeDerived:   computeDerived,
+  computeNamespacedHash: computeNamespacedHash,
   lookupHash:       lookupHash,
   clearForTest:     clearForTest,
   declareColumnResidency: declareColumnResidency,