@blamejs/blamejs-shop 0.3.41 → 0.3.43

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.43 (2026-05-31) — **Export orders for a date range as CSV or NDJSON, with scheduled exports.** There was no way to pull a bulk export of orders over a date range. A new Exports screen in the admin console previews how many orders and how much revenue a date range covers, then downloads them as a CSV or NDJSON file. The export can also be scheduled and managed as a queued job. Customer email addresses are exported only as a hash, never in the clear, and any field that could be interpreted as a spreadsheet formula is neutralized so an exported file can't run code when opened. This release also updates the vendored blamejs runtime to v0.14.16. **Added:** *Order export* — An Exports screen in the admin console exports orders over a chosen date range. It first shows a preview — the order count, revenue, and average order value for the range — then downloads the orders as a CSV or NDJSON file with a standard set of columns. Exports can also be queued as scheduled jobs and cancelled before they run. Customer email is exported as a hash rather than in the clear, and any cell that begins with a character a spreadsheet would treat as a formula is escaped, so an exported file can't execute anything when opened in Excel or Sheets. **Changed:** *Vendored blamejs runtime updated to v0.14.16* — The bundled blamejs runtime is updated to v0.14.16, which validates connection ports at configuration time — a malformed port (a non-integer or out-of-range value) is now rejected with a clear error at startup instead of silently falling back to a default. No operator action is required.
+
+- v0.3.42 (2026-05-31) — **The blog now pages through every post, and the byline shows the shop name.** The blog index showed only the 12 most recent posts with no way to reach the rest, so older posts were a dead end for anyone browsing — even though they stayed in the sitemap. The index now has previous/next pagination, so every published post is reachable. The post byline and the article's structured data now show the shop name instead of an internal author identifier, and a missing blog post or product page no longer returns a body on a HEAD request. **Fixed:** *Blog index pagination* — The blog index listed only the 12 most recent posts and offered no way to reach older ones from /blog. It now has previous/next pagination — the same control used on collection and search pages — so every published post is reachable, with the next link appearing only when there is genuinely another page. · *Blog byline shows the shop name, not an internal id* — The blog post byline and the article's structured data displayed the raw internal author identifier. They now show the shop name, so the public byline and the author Google reads from the structured data are meaningful rather than an internal id. · *Missing pages don't return a body on HEAD* — A missing blog post or product page returned a full page body even for a HEAD request. Those 404 responses now omit the body on HEAD, matching the other pages and the HTTP spec.
+
 - v0.3.41 (2026-05-31) — **The public product API no longer leaks internal error details, and bad order links return Not Found.** A server-side error on the public product API could include the raw internal error message — potentially database or query details — in its 500 response to anonymous callers. Those responses now return a generic message, with the real error recorded server-side only, matching how the admin side already behaves. Separately, opening an order or payment page with a malformed link now returns a clean Not Found instead of a server error. This release also updates the vendored blamejs runtime to v0.14.15. **Changed:** *Vendored blamejs runtime updated to v0.14.15* — The bundled blamejs runtime is updated to v0.14.15, which adds a recognized-purpose vocabulary to its consent ledger (with lawful-basis enforcement for regulated purposes) and a new privacy namespace for periodic third-party vendor-review attestations. These are additive, opt-in capabilities; existing behavior is unchanged and no operator action is required. **Fixed:** *Public product API hides internal error details* — When the public product API (the catalog endpoints) hit a server-side error, its 500 response could carry the raw internal error message — including database or constraint text — to any caller. It now returns a generic "something went wrong" message and records the real error server-side only, the same way the admin console already scrubs its errors. Validation errors still return their helpful 400 message unchanged. · *Malformed order and payment links return Not Found* — Opening an order confirmation or payment page with a malformed (non-identifier) link returned a server error instead of a Not Found. Both pages now return a clean 404 for a malformed or unknown link, matching the order reorder and cancel pages.
 
 - v0.3.40 (2026-05-31) — **Return shipping labels — operators issue one, customers download and track it.** After a return was approved there was no way to give the customer a shipping label or for them to follow the parcel back. Operators can now issue a return label on an approved return from the admin console — entering the carrier, tracking number, and the label link generated in their carrier account — and post tracking updates as the parcel moves. The customer sees the label on their return: they can open or print it, see the carrier and tracking number, and follow the scan history, with the return marked received once it arrives back. A customer can only see and download the label for their own return. **Added:** *Return shipping labels and tracking* — Opening a return in the account area now shows its detail, and once a label has been issued the customer can open or print the return label, see the carrier and tracking number, and follow the parcel's scan history — all scoped so a customer only ever sees their own return. On the operator side, an approved return gains an Issue return label form (carrier, service level, weight, the carrier label link, tracking number, and cost) and controls to mark the parcel shipped, in transit, delivered, or held with an exception; marking it delivered records the return as received. The label link is required to be a secure URL, and the customer download is served without exposing that link in the page.

package/lib/admin.js

@@ -503,6 +503,7 @@ function mount(router, deps) {
   var customerSegments = deps.customerSegments || null;  // per-customer segment-membership panel disabled when absent
   var orderTracking = deps.orderTracking || null;   // shipment/tracking panel disabled when absent
   var salesReports  = deps.salesReports  || null;   // /admin/reports degrades to an unconfigured notice when absent
+  var orderExport   = deps.orderExport   || null;   // /admin/exports (date-range CSV/NDJSON dump + scheduled-export queue) disabled when absent
   var printReceipts = deps.printReceipts || null;   // order receipt document disabled when absent
   var packingSlips  = deps.packingSlips  || null;   // order packing-slip document disabled when absent
   var pickLists      = deps.pickLists      || null;  // warehouse pick-list console disabled when absent
@@ -519,7 +520,7 @@ function mount(router, deps) {
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, orderExchanges: !!orderExchanges };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, orderExchanges: !!orderExchanges, orderExport: !!orderExport };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -6429,6 +6430,286 @@ function mount(router, deps) {
     });
   }
 
+  // ---- order export ---------------------------------------------------
+  //
+  // Bulk, date-range dump of the orders table to CSV / NDJSON, plus the
+  // queue of operator-filed scheduled-export jobs a background worker
+  // drains. Distinct from the per-order receipt CSV columns and the
+  // /admin/reports day-series ?format=csv (an aggregate, not the rows):
+  // this is the full row-level order set for offline analysis,
+  // accounting reconciliation, or a 3PL handoff.
+  //
+  // Surfaces (mounted only when the orderExport primitive is wired):
+  //   GET  /admin/exports                       — screen: range form +
+  //         summary preview (count + total) + the scheduled-export list +
+  //         a schedule-a-new-export form (bearer JSON returns the summary +
+  //         the export rows).
+  //   GET  /admin/exports/download?from=&to=&format=
+  //                                             — file response: streams
+  //         csvForRange / ndjsonForRange with the right content-type +
+  //         content-disposition. The primitive owns the CSV-injection
+  //         defense (a leading = / + / - / @ cell is prefixed with `'`),
+  //         so the route composes its output and never hand-rolls
+  //         serialization from raw order fields.
+  //   POST /admin/exports/schedule              — file a scheduled job.
+  //   POST /admin/exports/:id/cancel            — cancel a queued job.
+  //
+  // Range: from/to are calendar-date (YYYY-MM-DD) inputs from the browser,
+  // or raw epoch-ms for the JSON API. The window is half-open [from, to):
+  // the inclusive end day advances to the next UTC midnight so the chosen
+  // day is fully covered. An empty or inverted range is a config/entry-tier
+  // 400 (the operator corrects the typo), surfaced via _safeNotice.
+  if (orderExport) {
+    var EXPORT_FORMATS = orderExport.FORMATS || ["csv", "ndjson"];
+
+    // Resolve the export window from the query string into epoch-ms
+    // [from, to). Reuses the report screen's date helpers: the epoch-ms
+    // `from`/`to` pair wins for machine clients; the calendar-date
+    // `from-date`/`to-date` pair is what the browser date inputs submit
+    // (the `to-date` end day is inclusive, so step to the next UTC midnight).
+    // Both bounds are required — there is no implicit "last 30 days" default
+    // for a bulk dump, so a missing bound is a clean 400 rather than a
+    // surprise full-table export. Throws TypeError on a malformed/empty/
+    // inverted range; the orderExport primitive re-validates (non-negative
+    // integers, to >= from).
+    function _exportWindow(url) {
+      var from = _parseEpochMs(url && url.searchParams.get("from"), "from");
+      var to   = _parseEpochMs(url && url.searchParams.get("to"),   "to");
+      if (from == null) from = _parseDateParam(url && url.searchParams.get("from-date"), "from");
+      if (to == null) {
+        var toDate = _parseDateParam(url && url.searchParams.get("to-date"), "to");
+        if (toDate != null) to = toDate + b.constants.TIME.days(1);
+      }
+      if (from == null || to == null) {
+        throw new TypeError("admin: a from and a to date are both required for an export");
+      }
+      if (to <= from) {
+        throw new TypeError("admin: the to date must be after the from date");
+      }
+      return { from: from, to: to };
+    }
+
+    function _exportFormat(url) {
+      var f = (url && url.searchParams.get("format")) || "csv";
+      if (EXPORT_FORMATS.indexOf(f) === -1) {
+        throw new TypeError("admin: format must be one of " + EXPORT_FORMATS.join(", "));
+      }
+      return f;
+    }
+
+    // Stream the chosen format's async-iterable into the response body.
+    // csvForRange / ndjsonForRange yield the header (CSV) then one chunk
+    // per database batch; the route writes each batch to the socket as it
+    // is produced, so the process holds at most one batch in memory no
+    // matter how many orders the range covers (the resumable streamCursor
+    // / scheduled-export queue remains the path for an out-of-band dump).
+    // The primitive RFC-4180-quotes every CSV cell and neutralizes the
+    // spreadsheet-formula injection vector, so the route never touches the
+    // cell bytes.
+    async function _streamExport(res, win, format) {
+      var iter = format === "ndjson"
+        ? orderExport.ndjsonForRange({ from: win.from, to: win.to })
+        : orderExport.csvForRange({ from: win.from, to: win.to });
+      var contentType = format === "ndjson"
+        ? "application/x-ndjson; charset=utf-8"
+        : "text/csv; charset=utf-8";
+      var ext      = format === "ndjson" ? "ndjson" : "csv";
+      var fromDay  = _dateInputValue(win.from);
+      var toDay    = _dateInputValue(win.to - b.constants.TIME.days(1));
+      var filename = "orders-" + (fromDay || "start") + "-to-" + (toDay || "end") + "." + ext;
+      res.status(200);
+      if (res.setHeader) {
+        res.setHeader("content-type", contentType);
+        // The filename is built from validated epoch-ms date strings
+        // (digits + hyphens only), so it carries no quote/CRLF that could
+        // break out of the header — but keep it ASCII-safe regardless.
+        res.setHeader("content-disposition", "attachment; filename=\"" + filename.replace(/[^A-Za-z0-9._-]/g, "") + "\"");
+        res.setHeader("x-content-type-options", "nosniff");
+      }
+      // Write the header first, then one chunk per batch as the primitive
+      // yields it — bounded memory regardless of the order count. A
+      // response without an incremental write() (a JSON test stub) falls
+      // back to buffering the date-bounded window.
+      if (typeof res.write === "function" && typeof res.end === "function") {
+        for await (var chunk of iter) {
+          if (chunk) res.write(chunk);
+        }
+        res.end();
+      } else {
+        var body = "";
+        for await (var c2 of iter) body += c2;
+        if (res.end) res.end(body); else res.send(body);
+      }
+    }
+
+    router.get("/admin/exports", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        // A download link carries ?download=1 (+ from/to/format); the bearer
+        // API serves it as a file too so tooling can pull the dump directly.
+        if (url && url.searchParams.get("download")) {
+          var winD, fmtD;
+          try { winD = _exportWindow(url); fmtD = _exportFormat(url); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          return _streamExport(res, winD, fmtD);
+        }
+        // Summary preview for a chosen range (omitted when no range given).
+        var summary = null, win = null;
+        if ((url && url.searchParams.get("from")) || (url && url.searchParams.get("from-date"))) {
+          try { win = _exportWindow(url); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          summary = await orderExport.summaryForRange({ from: win.from, to: win.to });
+        }
+        var listing = await orderExport.listExports({ limit: 50 });
+        _json(res, 200, { summary: summary, range: win, exports: listing.rows || [] });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        // Download from the browser surface too (a link, not a fetch).
+        if (url && url.searchParams.get("download")) {
+          var win0, fmt0;
+          try { win0 = _exportWindow(url); fmt0 = _exportFormat(url); }
+          catch (e) {
+            var nd = _safeNotice(e, "export.download");
+            var rowsD = (await orderExport.listExports({ limit: 50 })).rows || [];
+            return _sendHtml(res, nd.status, renderAdminExports({
+              shop_name: deps.shop_name, nav_available: navAvailable, exports: rowsD,
+              formats: EXPORT_FORMATS, notice: nd.message.replace(/^admin:\s*/, ""),
+            }));
+          }
+          return _streamExport(res, win0, fmt0);
+        }
+        // Optional summary preview for a chosen range. A malformed/empty/
+        // inverted range re-renders the screen with a correction notice
+        // (config/entry tier) rather than 500-ing.
+        var summary = null, win = null, format = "csv", notice = null;
+        var hasRange = (url && url.searchParams.get("from-date")) || (url && url.searchParams.get("from"));
+        if (hasRange) {
+          try {
+            win = _exportWindow(url);
+            format = _exportFormat(url);
+            summary = await orderExport.summaryForRange({ from: win.from, to: win.to });
+          } catch (e) {
+            if (!(e instanceof TypeError)) throw e;
+            notice = _safeNotice(e, "export.summary").message.replace(/^admin:\s*/, "");
+            win = null; summary = null;
+          }
+        }
+        var rows = (await orderExport.listExports({ limit: 50 })).rows || [];
+        _sendHtml(res, 200, renderAdminExports({
+          shop_name: deps.shop_name, nav_available: navAvailable, exports: rows,
+          formats: EXPORT_FORMATS, summary: summary, range: win, format: format,
+          scheduled: url && url.searchParams.get("scheduled"),
+          cancelled: url && url.searchParams.get("cancelled"),
+          notice:    notice,
+        }));
+      },
+    ));
+
+    // The dedicated download route — a plain link target (and a bearer GET
+    // for tooling). Same file response on both surfaces.
+    router.get("/admin/exports/download", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var win, format;
+        try { win = _exportWindow(url); format = _exportFormat(url); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        return _streamExport(res, win, format);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var win, format;
+        try { win = _exportWindow(url); format = _exportFormat(url); }
+        catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          var n = _safeNotice(e, "export.download");
+          var rows = (await orderExport.listExports({ limit: 50 })).rows || [];
+          return _sendHtml(res, n.status, renderAdminExports({
+            shop_name: deps.shop_name, nav_available: navAvailable, exports: rows,
+            formats: EXPORT_FORMATS, notice: n.message.replace(/^admin:\s*/, ""),
+          }));
+        }
+        return _streamExport(res, win, format);
+      },
+    ));
+
+    // File a scheduled export job. Range + format are validated here (the
+    // same _exportWindow / _exportFormat shape the download uses); the
+    // primitive re-validates and persists a `queued` row a worker drains.
+    router.post("/admin/exports/schedule", _pageOrApi(false,
+      W("export.schedule", async function (req, res) {
+        var body = req.body || {};
+        var job = await orderExport.scheduleExport({
+          format: body.format,
+          from:   _strictNonNegIntField(body.from, "from"),
+          to:     _strictNonNegIntField(body.to,   "to"),
+        });
+        _json(res, 201, job);
+        return { id: job.id };
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        // The browser form submits calendar-date inputs; coerce to the
+        // epoch-ms [from, to) window the primitive expects.
+        try {
+          var win = _exportWindow(new URL("http://localhost/?" +
+            "from-date=" + encodeURIComponent(body["from-date"] || "") +
+            "&to-date=" + encodeURIComponent(body["to-date"] || "")));
+          var format = (body.format && EXPORT_FORMATS.indexOf(body.format) !== -1) ? body.format : null;
+          if (!format) throw new TypeError("admin: format must be one of " + EXPORT_FORMATS.join(", "));
+          await orderExport.scheduleExport({ format: format, from: win.from, to: win.to });
+        } catch (e) {
+          var n = _safeNotice(e, "export.schedule");
+          var rows = (await orderExport.listExports({ limit: 50 })).rows || [];
+          return _sendHtml(res, n.status, renderAdminExports({
+            shop_name: deps.shop_name, nav_available: navAvailable, exports: rows,
+            formats: EXPORT_FORMATS, notice: n.message.replace(/^admin:\s*/, ""),
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".export.schedule", outcome: "success" });
+        _redirect(res, "/admin/exports?scheduled=1");
+      },
+    ));
+
+    // Cancel a queued scheduled export. A malformed id is a 400; an unknown
+    // id (or a job past `queued`, which the FSM refuses) is surfaced as a
+    // correction notice on the browser path / a 4xx on the bearer path.
+    router.post("/admin/exports/:id/cancel", _pageOrApi(false,
+      W("export.cancel", async function (req, res) {
+        var row;
+        try { row = await orderExport.cancelExport(req.params.id); }
+        catch (e) {
+          // The FSM refuses a cancel once the job is running/terminal — a
+          // coded conflict (409), checked first. It is a plain Error with a
+          // .code, never a TypeError; the message is operator-safe (it names
+          // the refused transition, never storage internals).
+          if (e && e.code) return _problem(res, 409, "conflict", "That export can no longer be cancelled.");
+          // A syntactically valid id that names no job is a not-found
+          // TypeError — distinct from a malformed id — so map it to 404 (a
+          // malformed id stays a 400) and clients can tell the two apart.
+          if (e instanceof TypeError && / not found$/.test(String(e.message || ""))) {
+            return _problem(res, 404, "export-not-found");
+          }
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          throw e;
+        }
+        // cancelExport throws on a missing row, so a falsy return is purely
+        // defensive — keep the 404 in case the primitive ever returns null.
+        if (!row) return _problem(res, 404, "export-not-found");
+        _json(res, 200, row);
+        return { id: row.id };
+      }),
+      async function (req, res) {
+        var ok = false;
+        try { ok = !!(await orderExport.cancelExport(req.params.id)); }
+        catch (_e) { ok = false; }
+        if (!ok) return _redirect(res, "/admin/exports?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".export.cancel", outcome: "success", metadata: { id: req.params.id } });
+        _redirect(res, "/admin/exports?cancelled=1");
+      },
+    ));
+  }
+
   // ---- analytics ------------------------------------------------------
 
   var analytics = deps.analytics || null;
@@ -9277,6 +9558,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "inventory",    href: "/admin/inventory",    label: "Inventory" },
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
   { key: "reports",      href: "/admin/reports",      label: "Reports" },
+  { key: "exports",      href: "/admin/exports",      label: "Exports",      requires: "orderExport" },
   { key: "customers",    href: "/admin/customers",    label: "Customers",    requires: "customers" },
   { key: "segments",     href: "/admin/segments",     label: "Segments",     requires: "customerSegments" },
   { key: "returns",      href: "/admin/returns",      label: "Returns",      requires: "returns" },
@@ -9702,6 +9984,114 @@ function renderAdminReports(opts) {
   return _renderAdminShell(opts.shop_name, "Reports", body, "reports", opts.nav_available);
 }
 
+// Order-export screen. A date-range + format picker drives a summary
+// preview (order count + total for the chosen window) and the two download
+// links (CSV / NDJSON); below it the scheduled-export queue lists every
+// operator-filed job with a per-job cancel, and a schedule-a-new-export
+// form files one. `opts.summary` is null until the operator picks a range;
+// `opts.exports` is the scheduled-export rows.
+var EXPORT_STATUS_PILL = {
+  queued:    "pending",
+  running:   "fulfilling",
+  complete:  "paid",
+  failed:    "refunded",
+  cancelled: "cancelled",
+};
+function renderAdminExports(opts) {
+  opts = opts || {};
+  var exportsRows = opts.exports || [];
+  var formats     = opts.formats || ["csv", "ndjson"];
+  var summary     = opts.summary || null;
+  var range       = opts.range   || null;
+  var notice    = opts.notice    ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var scheduled = opts.scheduled ? "<div class=\"banner banner--ok\">Export scheduled.</div>" : "";
+  var cancelled = opts.cancelled ? "<div class=\"banner banner--ok\">Export cancelled.</div>" : "";
+
+  // The range form prefills with the chosen window (or blank). It GETs back
+  // to /admin/exports so the window lives in the URL (bookmarkable) and the
+  // summary preview re-renders; the two download links carry the same window
+  // + the format as a ?download=1 query.
+  var fromVal = range ? _dateInputValue(range.from) : "";
+  var toVal   = range ? _dateInputValue(range.to - b.constants.TIME.days(1)) : "";
+
+  var rangeForm =
+    "<form method=\"get\" action=\"/admin/exports\" class=\"order-filters\">" +
+      "<label class=\"form-field\"><span>From</span><input type=\"date\" name=\"from-date\" value=\"" + _htmlEscape(fromVal) + "\" required></label>" +
+      "<label class=\"form-field\"><span>To</span><input type=\"date\" name=\"to-date\" value=\"" + _htmlEscape(toVal) + "\" required></label>" +
+      "<button class=\"btn\" type=\"submit\">Preview range</button>" +
+    "</form>";
+
+  // Summary preview + download links (only once a valid range is chosen).
+  var previewBlock = "";
+  if (summary && range) {
+    // Pick a headline currency from the by_currency map (the busiest
+    // bucket); fall back to USD when the window is empty.
+    var curBuckets = Object.keys(summary.by_currency || {});
+    var headlineCur = curBuckets.length ? curBuckets[0] : "USD";
+    var qWin = "from=" + encodeURIComponent(String(range.from)) + "&to=" + encodeURIComponent(String(range.to));
+    var dlLinks = formats.map(function (f) {
+      return "<a class=\"btn btn--ghost\" href=\"/admin/exports/download?" + qWin + "&format=" + encodeURIComponent(f) + "\">Download " + _htmlEscape(f.toUpperCase()) + "</a>";
+    }).join("");
+    previewBlock =
+      "<section><h2>Range preview</h2>" +
+        "<p class=\"meta\">Window: " + _htmlEscape(_fmtDate(range.from)) + " → " + _htmlEscape(_fmtDate(range.to - b.constants.TIME.days(1))) + " (inclusive)</p>" +
+        "<div class=\"stat-grid\">" +
+          _statCard("Orders in range", String(summary.order_count)) +
+          _statCard("Revenue", pricing.format(summary.revenue_minor, headlineCur)) +
+          _statCard("Avg order value", pricing.format(summary.average_order_minor, headlineCur)) +
+        "</div>" +
+        "<div class=\"actions-row mt\">" + dlLinks + "</div>" +
+      "</section>";
+  }
+
+  // Scheduled-export queue table.
+  var jobRows = exportsRows.map(function (j) {
+    var pill = EXPORT_STATUS_PILL[j.status] || "pending";
+    var from = j.from_ts != null ? _fmtDate(j.from_ts) : "—";
+    var to   = j.to_ts   != null ? _fmtDate(j.to_ts)   : "—";
+    var rowCount = (j.row_count != null) ? String(j.row_count) : "—";
+    var enc = _htmlEscape(encodeURIComponent(j.id));
+    var cancelCell = j.status === "queued"
+      ? "<form method=\"post\" action=\"/admin/exports/" + enc + "/cancel\" class=\"form-inline\">" +
+          "<button class=\"btn btn--danger\" type=\"submit\">Cancel</button></form>"
+      : "<span class=\"meta\">—</span>";
+    return "<tr>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(String(j.format || "")) + "</code></td>" +
+      "<td>" + _htmlEscape(from) + " → " + _htmlEscape(to) + "</td>" +
+      "<td><span class=\"status-pill " + pill + "\">" + _htmlEscape(String(j.status || "")) + "</span></td>" +
+      "<td class=\"num\">" + _htmlEscape(rowCount) + "</td>" +
+      "<td>" + cancelCell + "</td>" +
+    "</tr>";
+  }).join("");
+  var jobTable = exportsRows.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Format</th><th scope=\"col\">Window</th><th scope=\"col\">Status</th><th scope=\"col\" class=\"num\">Rows</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + jobRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No scheduled exports yet.</p>";
+
+  var scheduleFmtOptions = formats.map(function (f) {
+    return "<option value=\"" + _htmlEscape(f) + "\">" + _htmlEscape(f.toUpperCase()) + "</option>";
+  }).join("");
+  var scheduleForm =
+    "<div class=\"panel mt mw-42\">" +
+      "<h3 class=\"subhead\">Schedule an export</h3>" +
+      "<p class=\"meta\">Queue a date-range dump for a background worker to produce. The job appears below as “queued” and can be cancelled until the worker claims it.</p>" +
+      "<form method=\"post\" action=\"/admin/exports/schedule\">" +
+        "<label class=\"form-field\"><span>From</span><input type=\"date\" name=\"from-date\" required></label>" +
+        "<label class=\"form-field\"><span>To</span><input type=\"date\" name=\"to-date\" required></label>" +
+        "<label class=\"form-field\"><span>Format</span><select name=\"format\">" + scheduleFmtOptions + "</select></label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Schedule export</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var body =
+    "<section><h2>Exports</h2>" + notice + scheduled + cancelled +
+      "<p class=\"meta\">Dump the full order set for a date range to CSV or NDJSON — for accounting, analysis, or a fulfilment-partner handoff. Customer email is pseudonymised in the output.</p>" +
+      rangeForm +
+    "</section>" +
+    previewBlock +
+    "<section><h2>Scheduled exports</h2>" + jobTable + scheduleForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Exports", body, "exports", opts.nav_available);
+}
+
 // A single shipping-label row for the standalone cross-order tables. Shows
 // carrier + service, tracking number, cost (via pricing.format from the
 // label's own minor units + currency), the broker it came from, its status

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.41",
+  "version": "0.3.43",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-1SIn6oAf1DjECbRfKENZasdKHJiywGdXR58wn0hsFGcdVHzUmvfgMkEz5ANIAZJ3",

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.15",
-      "tag": "v0.14.15",
+      "version": "0.14.16",
+      "tag": "v0.14.16",
       "license": "Apache-2.0",
       "author": "blamejs contributors",
       "source": "https://github.com/blamejs/blamejs",

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.16 (2026-05-31) — **Connection entry-point ports are validated at config time.** Six connection entry points previously read opts.port with a bare `|| <default>` fallback, silently coercing a string, negative, NaN, or out-of-range port instead of catching the operator's typo. A new b.validateOpts.optionalPort enforces the RFC 6335 §6 wire-valid range and is wired into b.mail.smtpTransport, b.ntpCheck.querySingle, b.networkDns.useDnsOverTls, b.networkNts (KE handshake / query / facade), b.redisClient.create, and createApp().listen — each now throws at construction with a clear message naming the bad value. The app.listen / createApp bind site opts into allowZero so port 0 (the legitimate ephemeral-bind sentinel) still works; the five outbound-connect sites require [1,65535]. **Added:** *`b.validateOpts.optionalPort`* — A config-time port validator: `optionalPort(value, label, errorClass, code, opts?)` returns an omitted (`undefined` / `null`) port unchanged, and otherwise requires an integer in the RFC 6335 §6 wire-valid range [1,65535] — rejecting a string, negative, NaN, Infinity, fractional, or out-of-range value. Pass `{ allowZero: true }` for a listen-bind site where port 0 is the OS ephemeral-bind sentinel. The thrown message reports the offending shape (so `Infinity` / `"443"` stay visible), and routes a caller-supplied typed framework error (or a plain Error when none is given), matching the existing `optionalPositiveFinite` family. **Changed:** *Connection entry points reject a malformed port at construction* — `b.mail.smtpTransport`, `b.ntpCheck.querySingle`, `b.networkDns.useDnsOverTls`, `b.networkNts.performKeHandshake` / `query` / `querySingle`, `b.redisClient.create`, and `createApp().listen` (plus the `createApp` constructor's default port) now validate `opts.port` and throw synchronously on a non-integer / out-of-range value rather than coercing it through `||` to a default. This is a behavior change for a caller that was passing a non-canonical port (e.g. the string `"587"` or a NaN) and relying on the silent fallback — pass an integer in [1,65535] instead (or `0` for an ephemeral `createApp().listen` bind). `b.ntpCheck` gains a typed `NtpCheckError` for this (it had no error class before). **Detectors:** *Connection entry points must compose the port validator* — A new check flags a lib connection entry point that reads `opts.port` / `opts.kePort` / `opts.ntpPort` with a `|| <default>` fallback without composing `b.validateOpts.optionalPort` (or the equivalent `numericBounds.isPositiveFiniteInt` + 65535 cap), so an unvalidated port read can't slip back in. **Migration:** *Pass an integer port to connection primitives* — If you were passing a non-integer or out-of-range `opts.port` to a mail / NTP / NTS / DNS-over-TLS / Redis transport or to `createApp().listen` and relying on the silent `|| default` fallback, that now throws at construction. Pass an integer in [1,65535]; for an ephemeral `createApp().listen` bind, pass `0` (still accepted).
+
 - v0.14.14 (2026-05-31) — **Recognized consent purposes with lawful-basis gating, and a new b.privacy namespace for annual EdTech vendor-review attestations.** Closes the student-data gap where an educational-only consent purpose and an annual third-party vendor-review report were described but never implemented. b.consent gains a recognized-purpose vocabulary: a purpose value matching a recognized key carries lawful-basis constraints that grant() enforces, and the named educational-only purpose (FERPA's school-official exception and California's SOPIPA) refuses a legitimate_interests lawful basis. The new b.privacy namespace ships vendorReview(), a builder for the dated, clause-by-clause annual EdTech third-party / processor review FERPA and SOPIPA expect a school or district to keep — it computes whether every required clause (no targeted advertising, no commercial profiling, no sale of student data, deletion on request, school-official designation, and so on) is attested, names the gaps, and stamps a 365-day re-review clock. Free-form consent purposes keep working unchanged, so the vocabulary is opt-in and additive. **Added:** *`b.consent` recognized-purpose vocabulary + lawful-basis gating* — `b.consent.recognizedPurpose(name)` looks up a recognized purpose and `b.consent.listPurposes()` enumerates them. When a `grant({ purpose })` value matches a recognized key, `grant()` enforces that purpose's lawful-basis constraints; the `educational-only` purpose forbids a `legitimate_interests` basis (FERPA 34 CFR 99.31(a)(1) school-official exception; California SOPIPA Cal. B&P 22584; FTC school-authorized COPPA consent 16 CFR 312.5(c)(10)) and marks the data commercial-use-prohibited. The commercial-use prohibition is an operator trust-boundary obligation — `isGranted()` does not re-derive it. Any purpose value NOT in the vocabulary stays free-form and unconstrained, so existing callers are unaffected; the hash-chain column set is unchanged, so `b.consent.verify()` over existing rows is unaffected. · *`b.privacy.vendorReview` — annual EdTech vendor-review attestation* — A new `b.privacy` namespace whose `vendorReview(opts)` builds the dated third-party / processor review a FERPA school-official arrangement and California SOPIPA expect for every vendor that touches student data. The operator supplies a boolean attestation per clause (educational-purpose-only, no-targeted-advertising, no-commercial-profiling, no-sale-of-student-data, security-safeguards, deletion-on-request, sub-processor-currency, breach-notification, school-official-designation, directory-information-handling); `vendorReview` validates the shape, computes whether every required clause is attested (`attested`) and which are not (`gaps`), and stamps `reviewedAt` plus a 365-day `nextReviewDueAt` re-review clock. `b.privacy.listVendorReviewClauses()` returns the clause set with citations. Operator-feeds-metadata: the frozen report is not framework-persisted — compose it into your retention / audit / export sink. A best-effort `privacy.vendor_review.recorded` audit event fires when an audit sink is wired. **Detectors:** *A gated consent purpose must go through `b.consent`* — A new check flags any lib code that mints a consent row with a hardcoded `educational-only` purpose literal without composing the recognized-purpose vocabulary — which would record the value while never enforcing its FERPA / SOPIPA lawful-basis constraint.
 
 - v0.14.13 (2026-05-31) — **Close advertised-but-missing surface: SRS1 chained forwarding, DCQL array-wildcard claim paths, and in-memory safe-archive extraction.** Three primitives advertised a capability in their documentation or card but refused or omitted it at runtime; this release implements each. b.mail.srs gains srs1Rewrite for the SRS1 double-forward (and multi-hop) case — previously the @intro described SRS1 and create() threw, pointing at a function that was never exported. b.safeArchive gains extractToMemory, the in-memory counterpart to extract for read-only / serverless filesystems — previously the card advertised in-memory extraction but the orchestrator required a destination directory. b.auth.oid4vp.matchDcql now honours a null claims-path segment as the array wildcard the OpenID4VP DCQL spec defines, rather than refusing it as unsupported while the card advertised DCQL. A stale version-pinned wording in a safe-archive error message is corrected. Every change is additive or message-only — no existing caller changes behaviour. **Added:** *`b.mail.srs` SRS1 chained forwarding — `srs1Rewrite`* — `b.mail.srs.create(...)` now returns `srs1Rewrite` alongside `rewrite` / `reverse`. `srs1Rewrite(srsAddress)` chains an already-SRS0 (or SRS1) envelope-from for a further forwarding hop: it keeps the original SRS0 body verbatim, prepends the SRS0 originator's domain, and binds the pair with this forwarder's own HMAC-SHA-256 tag — no new timestamp, no repeated original local-part — emitting `SRS1=tag=originator==<SRS0-body>@thisForwarder`. `reverse()` now detects an SRS1 address, verifies this hop's tag and forwarder-domain binding, and unwraps exactly one hop back to the originator's SRS0 so a multi-hop bounce routes straight to the forwarder that can recover the original sender. Typed failure modes: `srs/not-srs0` (input not SRS-encoded), `srs/malformed` (missing the `==` separator), `srs/bad-tag` (tampered), `srs/too-long` (chain exceeds the RFC 5321 256-octet path limit). Implements the Sender Rewriting Scheme SRS1 wire format; the second-hop SPF rationale is RFC 7208 §2.4. · *`b.safeArchive.extractToMemory` — in-memory safe extraction* — An async generator counterpart to `b.safeArchive.extract` for read-only / serverless filesystems: it resolves the source, sniffs the format, auto-unwraps recipient (`BAWRP`) / passphrase (`BAWPP`) envelopes, and dispatches to the zip / tar / tar.gz reader's in-memory `extractEntries()`, yielding `{ name, bytes, size }` per regular-file entry without ever writing to disk. It takes no `destination`. Every defense the disk path runs applies unchanged: the zip-bomb caps (entry-count / per-entry / total / expansion-ratio), the `b.guardArchive` metadata cascade (Zip-Slip / path-traversal / symlink-escape / encrypted-entry refusal, CVE-2025-3445 class), and the entry-type policy. The disk-only realpath-agreement check (CVE-2025-4517 PATH_MAX TOCTOU defense) is intentionally absent — there is no extraction root — so the archive-level name refusals carry containment. Trusted-stream sources are refused upfront (the adversarial-safe central-directory walk needs random access). gzip magic per RFC 1952 §2.3.1. **Fixed:** *OID4VP DCQL `null` claim-path segment now resolves the array wildcard* — `b.auth.oid4vp.matchDcql` previously threw `auth-oid4vp/null-path-segment-not-supported` for a `null` claims-path segment while the namespace card advertised DCQL — under-disclosing a legitimate presentation (CWE-863). Per OpenID4VP 1.0 §7.1.1 a `null` segment selects all elements of the array at that depth; the matcher now recurses over array elements with existence semantics (with DCQL value-matching applied to any selected leaf), composed to arbitrary depth. A `null` segment on a non-array node — like an integer index into a non-array, or a string key into an array — is a clean non-match, not a thrown error, because the matcher walks holder credential data rather than operator config. String and integer claim paths are byte-identical to before; only queries that previously threw now succeed or fail cleanly. · *safe-archive trusted-stream refusal message no longer cites a stale version* — The thrown `safe-archive/trusted-stream-unsupported` message and its comment claimed trusted-stream extraction was "deferred to v0.12.8 / when the v0.12.8 sequential extract path lands." That path shipped long ago — `b.archive.read.zip.fromTrustedStream` and the tar sequential mode exist — so the message now points at them as present capabilities and drops the version-pinned wording. The error code is unchanged. **Detectors:** *A primitive may not advertise a capability and then throw an unimplemented stub* — A new check flags a bare `not yet supported` / `operator demand TBD` / `not supported in v1` refusal in a lib throw string (comments excluded). A defer is only complete with a written re-open condition; the SRS1 and DCQL stubs that this release implements both carried this bare-defer shape, and the detector keeps it from re-entering. · *DCQL `null` path segments must recurse, never refuse* — A new check flags the `null path segment not supported` refusal shape in `lib/auth/oid4vp.js`, so the spec-mandated array wildcard cannot be re-stubbed. · *`extractToMemory` must stay disk-free* — A new check flags any `writeFileSync` / `renameSync` / `mkdirSync` / `createWriteStream` inside the `extractToMemory` generator body, so the read-only / serverless contract cannot regress into a disk write.

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

@@ -1,7 +1,7 @@
 {
   "version": 1,
-  "frameworkVersion": "0.14.14",
-  "createdAt": "2026-05-31T19:48:38.125Z",
+  "frameworkVersion": "0.14.16",
+  "createdAt": "2026-06-01T01:11:20.010Z",
   "exports": {
     "a2a": {
       "type": "object",
@@ -43286,6 +43286,10 @@
           "type": "primitive",
           "valueType": "number"
         },
+        "NtpCheckError": {
+          "type": "function",
+          "arity": 4
+        },
         "bootCheck": {
           "type": "function",
           "arity": 1

package/lib/vendor/blamejs/lib/app.js

@@ -93,6 +93,7 @@ var nodeFs = require("node:fs");
 var nodePath = require("node:path");
 var appShutdown = require("./app-shutdown");
 var audit = require("./audit");
+var validateOpts = require("./validate-opts");
 var C = require("./constants");
 var cluster = require("./cluster");
 var db = require("./db");
@@ -139,6 +140,9 @@ async function createApp(opts) {
   if (!opts.dataDir || typeof opts.dataDir !== "string") {
     throw new Error("createApp: opts.dataDir is required");
   }
+  // Constructor-time default port (used by listen() when listenOpts.port is
+  // omitted); allowZero for the ephemeral-bind sentinel.
+  validateOpts.optionalPort(opts.port, "createApp: opts.port", undefined, undefined, { allowZero: true });
   var dataDir = nodePath.resolve(opts.dataDir);
   if (!nodeFs.existsSync(dataDir)) {
     nodeFs.mkdirSync(dataDir, { recursive: true });
@@ -279,6 +283,10 @@ async function createApp(opts) {
 
   function listen(listenOpts) {
     listenOpts = listenOpts || {};
+    // Port 0 is the legitimate ephemeral-bind sentinel for a listen socket
+    // (RFC 6335 §6 / POSIX bind), so allowZero — but a non-integer / NaN /
+    // out-of-range port is an operator typo that must fail at boot.
+    validateOpts.optionalPort(listenOpts.port, "createApp.listen: listenOpts.port", undefined, undefined, { allowZero: true });
     var port = (listenOpts.port !== undefined) ? listenOpts.port
              : (opts.port !== undefined) ? opts.port
              : 0;

package/lib/vendor/blamejs/lib/mail.js

@@ -767,6 +767,7 @@ function smtpTransport(opts) {
       "dkimSigner must be an object with a .sign(rfc822) method " +
       "(see b.mail.dkim.create)", true);
   }
+  validateOpts.optionalPort(opts.port, "smtp transport: opts.port", MailError, "mail/smtp-misconfigured");
   var port = opts.port || 587;
   var useImplicitTLS = port === 465 || opts.implicitTls === true;
   var rejectUnauthorized = opts.rejectUnauthorized !== false;

package/lib/vendor/blamejs/lib/network-dns.js

@@ -253,6 +253,7 @@ function useDnsOverTls(opts) {
   opts = opts || {};
   validateOpts(opts, ["host", "port", "servername", "ca"], "dns.useDnsOverTls");
   validateOpts.requireNonEmptyString(opts.host, "dns.useDnsOverTls: host", DnsError, "dns/bad-dot-host");
+  validateOpts.optionalPort(opts.port, "dns.useDnsOverTls: opts.port", DnsError, "dns/bad-dot-port");
   if (opts.ca !== undefined && opts.ca !== null &&
       !Buffer.isBuffer(opts.ca) && typeof opts.ca !== "string" && !Array.isArray(opts.ca)) {
     throw new DnsError("dns/bad-dot-ca",

package/lib/vendor/blamejs/lib/network-nts.js

@@ -241,6 +241,7 @@ function performKeHandshake(opts) {
   opts = opts || {};
   validateOpts(opts, ["host", "port", "servername", "aead", "ca", "timeoutMs"], "nts.performKeHandshake");
   validateOpts.requireNonEmptyString(opts.host, "nts.performKeHandshake: host", NtsError, "nts/bad-host");
+  validateOpts.optionalPort(opts.port, "nts.performKeHandshake: opts.port", NtsError, "nts/bad-ke-port");
   var timeoutMs = opts.timeoutMs || C.TIME.seconds(10);
   return new Promise(function (resolve, reject) {
     var settled = false;
@@ -408,6 +409,7 @@ function _walkExtensions(msg, startOff) {
 function querySingle(opts) {
   opts = opts || {};
   validateOpts(opts, ["host", "port", "aeadId", "c2sKey", "s2cKey", "cookies", "timeoutMs"], "nts.querySingle");
+  validateOpts.optionalPort(opts.port, "nts.querySingle: opts.port", NtsError, "nts/bad-ntp-port");
   if (!Buffer.isBuffer(opts.c2sKey) || opts.c2sKey.length === 0) {
     throw new NtsError("nts/no-c2s-key", "nts.querySingle: c2sKey required (Buffer)");
   }
@@ -542,6 +544,8 @@ function querySingle(opts) {
 async function query(opts) {
   opts = opts || {};
   validateOpts(opts, ["host", "kePort", "ntpPort", "aead", "ca", "timeoutMs", "servername"], "nts.query");
+  validateOpts.optionalPort(opts.kePort, "nts.query: opts.kePort", NtsError, "nts/bad-ke-port");
+  validateOpts.optionalPort(opts.ntpPort, "nts.query: opts.ntpPort", NtsError, "nts/bad-ntp-port");
   var ke = await performKeHandshake({
     host:       opts.host,
     port:       opts.kePort,

package/lib/vendor/blamejs/lib/ntp-check.js

@@ -48,10 +48,16 @@ var dgram = require("node:dgram");
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 var safeAsync = require("./safe-async");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
 
 var audit = lazyRequire(function () { return require("./audit"); });
 var observability = lazyRequire(function () { return require("./observability"); });
 
+// Config-time misuse (a bad opts.port) throws a typed, permanent error so an
+// operator catches the typo at boot rather than as a Promise rejection.
+var NtpCheckError = defineClass("NtpCheckError", { alwaysPermanent: true });
+
 // NTP epoch: 1900-01-01. Unix epoch: 1970-01-01. Offset: 70 years incl. 17
 // leap days = 2,208,988,800 seconds.
 var NTP_TO_UNIX_OFFSET_SECONDS = 2208988800;
@@ -166,6 +172,7 @@ function _resetThresholdsForTest() {
  */
 function querySingle(server, opts) {
   opts = opts || {};
+  validateOpts.optionalPort(opts.port, "ntpCheck.querySingle: opts.port", NtpCheckError, "ntp/bad-port");
   var port = opts.port || DEFAULT_PORT;
   var timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
 
@@ -445,6 +452,7 @@ function monitor(opts) {
 
 module.exports = {
   querySingle:               querySingle,
+  NtpCheckError:             NtpCheckError,
   checkDrift:                checkDrift,
   bootCheck:                 bootCheck,
   monitor:                   monitor,

package/lib/vendor/blamejs/lib/redis-client.js

@@ -155,9 +155,17 @@ function _frameToValue(frame) {
 function create(opts) {
   opts = opts || {};
   validateOpts.requireNonEmptyString(opts.url, "redis.create: opts.url", RedisError, "BAD_OPTS");
+  // Validate an operator-supplied opts.port up front for a clear typo
+  // message (e.g. the string "6379" or a negative value).
+  validateOpts.optionalPort(opts.port, "redis.create: opts.port", RedisError, "BAD_OPTS");
   var parsed = _parseRedisUrl(opts.url);
   var host = opts.host || parsed.host;
   var port = opts.port || parsed.port;
+  // Re-validate the RESOLVED port. A url-supplied port (redis://h:0,
+  // redis://h:99999) is not range-checked by _parseRedisUrl, so without
+  // this an outbound connect could inherit a zero / out-of-range port that
+  // the opts.port guard above never sees.
+  validateOpts.optionalPort(port, "redis.create: resolved port (opts.port or url)", RedisError, "BAD_OPTS");
   var useTls = opts.tls !== undefined ? !!opts.tls : parsed.tls;
   var password = opts.password !== undefined ? opts.password : parsed.password;
   var username = opts.username !== undefined ? opts.username : parsed.username;

package/lib/vendor/blamejs/lib/validate-opts.js

@@ -27,6 +27,8 @@
  * a typed error wrap the call.
  */
 
+var numericBounds = require("./numeric-bounds");
+
 function _format(primitive, unknownKey, allowedKeys) {
   return primitive + ": unknown option '" + unknownKey + "'. " +
     "Allowed keys: " + allowedKeys.slice().sort().join(", ") + ".";
@@ -150,6 +152,26 @@ function optionalFunction(value, label, errorClass, code) {
   return value;
 }
 
+// optionalPort — a TCP/UDP port number must be an integer in the wire-valid
+// range (RFC 6335 §6). Outbound-connect sites require [1,65535]; pass
+// { allowZero: true } for a listen-bind site where port 0 is the legitimate
+// ephemeral-bind sentinel the OS replaces with a kernel-assigned port. Uses
+// numericBounds.shape() in the message so Infinity / NaN / "443" stay visible.
+function optionalPort(value, label, errorClass, code, opts) {
+  if (value === undefined || value === null) return value;
+  opts = opts || {};
+  var ok = opts.allowZero
+    ? (numericBounds.isNonNegativeFiniteInt(value) && value <= 65535)
+    : (numericBounds.isPositiveFiniteInt(value) && value <= 65535);
+  if (!ok) {
+    _throw(errorClass, code, (label || "opt") + " must be " +
+           (opts.allowZero ? "0 (ephemeral) or " : "") +
+           "an integer in [" + (opts.allowZero ? 0 : 1) + ",65535], got " + numericBounds.shape(value),
+           "validate-opts/bad-port");
+  }
+  return value;
+}
+
 // applyDefaults — resolve every key in DEFAULTS against opts. For each
 // key, the operator's value (if not undefined) wins; otherwise the
 // default is used. Returns a new plain object — NOT a frozen one, so
@@ -391,6 +413,7 @@ module.exports.optionalBoolean = optionalBoolean;
 module.exports.optionalPositiveInt = optionalPositiveInt;
 module.exports.optionalFiniteNonNegative = optionalFiniteNonNegative;
 module.exports.optionalPositiveFinite = optionalPositiveFinite;
+module.exports.optionalPort = optionalPort;
 module.exports.optionalFunction = optionalFunction;
 module.exports.optionalNonEmptyString = optionalNonEmptyString;
 module.exports.optionalNonEmptyStringArray = optionalNonEmptyStringArray;

package/lib/vendor/blamejs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.14.14",
+  "version": "0.14.16",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/lib/vendor/blamejs/release-notes/v0.14.16.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "../scripts/release-notes-schema.json",
+  "version": "0.14.16",
+  "date": "2026-05-31",
+  "headline": "Connection entry-point ports are validated at config time",
+  "summary": "Six connection entry points previously read opts.port with a bare `|| <default>` fallback, silently coercing a string, negative, NaN, or out-of-range port instead of catching the operator's typo. A new b.validateOpts.optionalPort enforces the RFC 6335 §6 wire-valid range and is wired into b.mail.smtpTransport, b.ntpCheck.querySingle, b.networkDns.useDnsOverTls, b.networkNts (KE handshake / query / facade), b.redisClient.create, and createApp().listen — each now throws at construction with a clear message naming the bad value. The app.listen / createApp bind site opts into allowZero so port 0 (the legitimate ephemeral-bind sentinel) still works; the five outbound-connect sites require [1,65535].",
+  "sections": [
+    {
+      "heading": "Added",
+      "items": [
+        {
+          "title": "`b.validateOpts.optionalPort`",
+          "body": "A config-time port validator: `optionalPort(value, label, errorClass, code, opts?)` returns an omitted (`undefined` / `null`) port unchanged, and otherwise requires an integer in the RFC 6335 §6 wire-valid range [1,65535] — rejecting a string, negative, NaN, Infinity, fractional, or out-of-range value. Pass `{ allowZero: true }` for a listen-bind site where port 0 is the OS ephemeral-bind sentinel. The thrown message reports the offending shape (so `Infinity` / `\"443\"` stay visible), and routes a caller-supplied typed framework error (or a plain Error when none is given), matching the existing `optionalPositiveFinite` family."
+        }
+      ]
+    },
+    {
+      "heading": "Changed",
+      "items": [
+        {
+          "title": "Connection entry points reject a malformed port at construction",
+          "body": "`b.mail.smtpTransport`, `b.ntpCheck.querySingle`, `b.networkDns.useDnsOverTls`, `b.networkNts.performKeHandshake` / `query` / `querySingle`, `b.redisClient.create`, and `createApp().listen` (plus the `createApp` constructor's default port) now validate `opts.port` and throw synchronously on a non-integer / out-of-range value rather than coercing it through `||` to a default. This is a behavior change for a caller that was passing a non-canonical port (e.g. the string `\"587\"` or a NaN) and relying on the silent fallback — pass an integer in [1,65535] instead (or `0` for an ephemeral `createApp().listen` bind). `b.ntpCheck` gains a typed `NtpCheckError` for this (it had no error class before)."
+        }
+      ]
+    },
+    {
+      "heading": "Detectors",
+      "items": [
+        {
+          "title": "Connection entry points must compose the port validator",
+          "body": "A new check flags a lib connection entry point that reads `opts.port` / `opts.kePort` / `opts.ntpPort` with a `|| <default>` fallback without composing `b.validateOpts.optionalPort` (or the equivalent `numericBounds.isPositiveFiniteInt` + 65535 cap), so an unvalidated port read can't slip back in."
+        }
+      ]
+    },
+    {
+      "heading": "Migration",
+      "items": [
+        {
+          "title": "Pass an integer port to connection primitives",
+          "body": "If you were passing a non-integer or out-of-range `opts.port` to a mail / NTP / NTS / DNS-over-TLS / Redis transport or to `createApp().listen` and relying on the silent `|| default` fallback, that now throws at construction. Pass an integer in [1,65535]; for an ephemeral `createApp().listen` bind, pass `0` (still accepted)."
+        }
+      ]
+    }
+  ]
+}

package/lib/vendor/blamejs/test/layer-0-primitives/codebase-patterns.test.js

@@ -2743,6 +2743,33 @@ async function testNoDuplicateCodeBlocks() {
       ],
       reason: "v0.12.42 — validateOpts-then-guard prelude shared by three builder-style functions: cert.create mints a certificate, mail-send-deliver.deliver sends a message, vc.present builds + signs a Verifiable Presentation. The common shingle is the `validateOpts(allowedKeys) + required-field / non-empty-array guards + typed-error throw` idiom; the bodies diverge entirely (X.509 minting / SMTP delivery / VC-JOSE-COSE presentation envelope). Same validate-then-guard family as the v0.12.29 / v0.12.33 / v0.12.40 clusters.",
     },
+    {
+      mode:  "family-subset",
+      files: [
+        "lib/api-key.js:_validateIssueOpts",
+        "lib/http-client-cache.js:create",
+        "lib/network-dns.js:useDnsOverTls",
+      ],
+      reason: "v0.14.15 — validateOpts config-validation prelude (validateOpts(allowedKeys) + requireNonEmptyString + the new optionalPort port-range guard + typed-error throw). api-key._validateIssueOpts validates an API-key issue spec; http-client-cache.create validates a cache config; network-dns.useDnsOverTls validates a DoT endpoint. Wiring validateOpts.optionalPort into the DoT site tipped its preamble past the 50-token shingle threshold against two unrelated config-time primitives. Bodies diverge entirely; the shared primitive IS validateOpts (already extracted) — coupling these specs would couple three unrelated standards on a syntactic accident. Verified coincidental (absent on clean main; the 3 functions are unrelated). Same validate-then-guard family as the v0.12.29 / v0.12.42 clusters.",
+    },
+    {
+      mode:  "family-subset",
+      files: [
+        "lib/agent-idempotency.js:_safeAudit",
+        "lib/agent-orchestrator.js:_safeAudit",
+        "lib/redis-client.js:_frameToValue",
+      ],
+      reason: "v0.14.15 — coincidental boilerplate shingle surfaced when the validateOpts.optionalPort wiring was added to redis-client.create: the file's token stream shifted enough that a 50-token window in redis-client.js clusters with the identical _safeAudit audit-emit wrappers in agent-idempotency / agent-orchestrator (a try/catch around audit().safeEmit). _safeAudit drop-silently emits an audit event; redis-client._frameToValue parses a RESP wire frame — entirely unrelated behaviour sharing only a generic guard/try-catch idiom. Verified absent on clean main; no shared logic to extract.",
+    },
+    {
+      mode:  "family-subset",
+      files: [
+        "lib/compliance-sanctions-fetcher.js:create",
+        "lib/network-nts.js:performKeHandshake",
+        "lib/web-push-vapid.js:buildVapidAuthHeader",
+      ],
+      reason: "v0.14.15 — validateOpts config-validation prelude again: network-nts.performKeHandshake gained the optionalPort port-range guard, tipping its preamble past the shingle threshold against compliance-sanctions-fetcher.create (sanctions-list fetch config) and web-push-vapid.buildVapidAuthHeader (VAPID JWT auth header build). Three unrelated specs (NTS-KE handshake / sanctions fetch / Web-Push VAPID) sharing only the validateOpts-then-guard idiom; the shared primitive is validateOpts. Verified coincidental (absent on clean main). Same family as the v0.12.29 / v0.12.42 clusters.",
+    },
     {
       mode:  "family-subset",
       files: [
@@ -6523,6 +6550,8 @@ var KNOWN_ANTIPATTERNS = [
 
   { id: "consent-purposes-null-proto", primitive: "the recognized-purpose map (PURPOSES) must be a null-prototype object so an operator-supplied free-form purpose colliding with an Object.prototype member (toString / constructor / __proto__) resolves to undefined, not the prototype value", scanScope: "lib", regex: /var PURPOSES\s*=\s*Object\.freeze\(/, requires: /Object\.create\(null\)/, allowlist: [], reason: "v0.14.14 Codex P2 on PR #295 (CWE-1321) — recognizedPurpose(name) + grant() index PURPOSES[purpose] with an operator-controlled value; a plain-prototype map returns Object.prototype.toString (truthy) for purpose \"toString\", breaking the null-for-free-form contract and entering grant()'s recognized branch for a value listPurposes() never exposes. PURPOSES is now Object.freeze(Object.assign(Object.create(null), {...})) so every unrecognized key resolves to undefined. Detector requires the null-prototype declaration so the lookup can't silently revert to a plain object." },
 
+  { id: "connect-entry-point-port-must-compose-optionalPort", primitive: "a connection entry point reading opts.port / opts.kePort / opts.ntpPort with a `|| <default>` fallback must first validate it via validateOpts.optionalPort (or, where a permanent typed error is needed, the equivalent numericBounds.isPositiveFiniteInt(opts.port) + 65535 cap) — an unvalidated opts.port || N silently accepts a string / negative / NaN / out-of-range port", scanScope: "lib", regex: /\bopts\.(?:port|kePort|ntpPort)\s*\|\|/, requires: /validateOpts\.optionalPort\(|isPositiveFiniteInt\(opts\.port\)/, allowlist: [], reason: "v0.14.15 — the connection entry points (mail.smtpTransport, ntpCheck.querySingle, dns.useDnsOverTls, nts.performKeHandshake / querySingle / query, redis.create) read opts.port || <default>, silently coercing a string / negative / NaN / >65535 port; rule §5 says config-time entry points THROW so the operator catches the typo at boot. Each now composes validateOpts.optionalPort (RFC 6335 §6 [1,65535]; allowZero for the app.listen ephemeral bind) — or, where a MailError-permanent typed error is needed, the same numericBounds.isPositiveFiniteInt + 65535 rule inline. The requires-companion clears a file once it validates; a new entry point reading opts.port || N without composing the validator trips the gate." },
+
   {
     // ROTATION-EPOCH ACCEPT (v0.14.x): a vault-key rotation (b.vault.rotate)
     // re-keys the local dataDir, which changes the SHA3-512 fingerprint of

package/lib/vendor/blamejs/test/layer-0-primitives/validate-opts-port.test.js

@@ -0,0 +1,70 @@
+"use strict";
+// b.validateOpts.optionalPort — RFC 6335 §6 port-range validator — plus the
+// representative connection entry-point wiring (ntpCheck.querySingle; the other
+// five sites compose the identical guard).
+
+var helpers     = require("../helpers");
+var b           = helpers.b;
+var check       = helpers.check;
+var redisClient = require("../../lib/redis-client");
+
+function _thrCode(fn) { try { fn(); return null; } catch (e) { return e.code || e.message; } }
+
+function run() {
+  var vo = b.validateOpts;
+  check("optionalPort is a function", typeof vo.optionalPort === "function");
+
+  // pass-through + valid ports
+  check("optionalPort(undefined) → undefined", vo.optionalPort(undefined) === undefined);
+  check("optionalPort(null) → null",           vo.optionalPort(null) === null);
+  check("optionalPort(443) → 443",             vo.optionalPort(443, "p") === 443);
+  check("optionalPort(1) accepted",            vo.optionalPort(1, "p") === 1);
+  check("optionalPort(65535) accepted",        vo.optionalPort(65535, "p") === 65535);
+
+  // 0 rejected by default, accepted with allowZero (ephemeral listen-bind)
+  check("optionalPort(0) throws by default",   _thrCode(function () { vo.optionalPort(0, "p"); }) !== null);
+  check("optionalPort(0, allowZero) → 0",      vo.optionalPort(0, "p", undefined, undefined, { allowZero: true }) === 0);
+
+  // out-of-range / non-integer / wrong-type all throw
+  [65536, -1, 0.5, "443", NaN, Infinity, "x", true, {}].forEach(function (bad, i) {
+    check("optionalPort rejects bad value #" + i + " (" + String(bad) + ")",
+          _thrCode(function () { vo.optionalPort(bad, "p"); }) !== null);
+  });
+  // 65536 is out of range even with allowZero
+  check("optionalPort(65536, allowZero) still throws",
+        _thrCode(function () { vo.optionalPort(65536, "p", undefined, undefined, { allowZero: true }); }) !== null);
+
+  // message carries numericBounds.shape() so Infinity / "443" stay visible
+  var msg = _thrCode(function () { vo.optionalPort(Infinity, "p"); });
+  check("optionalPort message shows the bad shape", typeof msg === "string" && /Infinity/.test(msg));
+
+  // typed-error class + code via a defineClass-built framework error
+  check("optionalPort routes a typed error class + code",
+        _thrCode(function () { vo.optionalPort(-1, "p", b.ntpCheck.NtpCheckError, "ntp/bad-port"); }) === "ntp/bad-port");
+
+  // plain Error when no errorClass is supplied
+  var plain = null;
+  try { vo.optionalPort(-1, "p"); } catch (e) { plain = e; }
+  check("optionalPort throws a plain Error with no errorClass", (plain instanceof Error) && !plain.code);
+
+  // representative entry-point wiring: ntpCheck.querySingle rejects a bad port
+  // synchronously (before the Promise) with a typed NtpCheckError.
+  check("b.ntpCheck.NtpCheckError is a constructor", typeof b.ntpCheck.NtpCheckError === "function");
+  check("ntpCheck.querySingle({port:-1}) throws ntp/bad-port",
+        _thrCode(function () { b.ntpCheck.querySingle("pool.ntp.org", { port: -1 }); }) === "ntp/bad-port");
+  check("ntpCheck.querySingle({port:70000}) throws ntp/bad-port",
+        _thrCode(function () { b.ntpCheck.querySingle("pool.ntp.org", { port: 70000 }); }) === "ntp/bad-port");
+
+  // A url-supplied connection port must be range-checked too — the opts.port
+  // guard alone misses a port resolved from the url, so redis://h:0 (parsed to
+  // port 0) would otherwise reach an outbound connect. create() is inert until
+  // .connect(), so a valid url throws nothing.
+  check("redis url-port 0 rejected at create (resolved-port guard)",
+        _thrCode(function () { redisClient.create({ url: "redis://localhost:0" }); }) !== null);
+  check("redis url-port out-of-range rejected at create",
+        _thrCode(function () { redisClient.create({ url: "redis://localhost:99999" }); }) !== null);
+  check("redis valid url-port accepted (no throw at create)",
+        _thrCode(function () { redisClient.create({ url: "redis://localhost:6379" }); }) === null);
+}
+
+module.exports = { run: run };

package/package.json

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