@blamejs/core 0.5.6 → 0.5.8

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- **0.5.7** (2026-04-30) — defensive validation + queue closure capture + audit context
+- **0.5.6** (2026-04-30) — break-glass: trustProxy honored, cache require hoisted
 - **0.5.5** (2026-04-30) — strict default CSP + IPv6 special-range expansion
 - **0.5.4** (2026-04-30) — close SSRF DNS-rebinding window with pinned outbound DNS
 - **0.5.3** (2026-04-30) — security cleanup: trustProxy primitive + Vary merge + HSTS gate

package/index.js

@@ -106,6 +106,7 @@ var forms = require("./lib/forms");
 var app = require("./lib/app");
 var jobs = require("./lib/jobs");
 var breakGlass = require("./lib/break-glass");
+var uuid = require("./lib/uuid");
 var mail = require("./lib/mail");
 var mailBounce = require("./lib/mail-bounce");
 var websocketChannels = require("./lib/websocket-channels");
@@ -208,6 +209,7 @@ module.exports = {
   createApp:        app.createApp,
   jobs:             jobs,
   breakGlass:       breakGlass,
+  uuid:             uuid,
   mail:             mail,
   mailBounce:       mailBounce,
   websocketChannels: websocketChannels,

package/lib/auth/jwt.js

@@ -243,6 +243,19 @@ async function verify(token, opts) {
 
   // Time-based claim validation
   var nowSec = Math.floor((opts.now || Date.now()) / 1000);
+  if (opts.clockToleranceSec !== undefined && opts.clockToleranceSec !== null) {
+    if (typeof opts.clockToleranceSec !== "number" ||
+        !isFinite(opts.clockToleranceSec) ||
+        opts.clockToleranceSec < 0) {
+      // Tier-A: a negative tolerance over-tightens the window (legit
+      // tokens get rejected as expired or not-yet-valid). A non-finite
+      // value would NaN-poison the comparison. Catch both at config
+      // time rather than producing surprise rejections in production.
+      throw new AuthError("auth-jwt/bad-clock-tolerance",
+        "verify: clockToleranceSec must be a non-negative finite number, got " +
+        JSON.stringify(opts.clockToleranceSec));
+    }
+  }
   var tol = typeof opts.clockToleranceSec === "number" ? opts.clockToleranceSec : 0;
   var p = decoded.payload;
   if (typeof p.exp === "number" && p.exp + tol < nowSec) {

package/lib/break-glass.js

@@ -776,12 +776,23 @@ function _reasonForAudit(reason, mode) {
 
 // ---- Use a grant ----
 
-async function unsealRow(grantHandle, table, rowId) {
+async function unsealRow(grantHandle, table, rowId, opts) {
   _requireInit();
   if (!grantHandle || typeof grantHandle !== "object" || typeof grantHandle.id !== "string") {
     throw new BreakGlassError("breakglass/bad-grant-opts",
       "unsealRow: grant handle is required (returned from b.breakGlass.grant())");
   }
+  // Optional opts.req lets the caller thread the originating request
+  // into per-row audit emits so the 5 W's (ip / userAgent / sessionId /
+  // requestId / method / route) populate alongside the grant's actor
+  // userId. Backward-compatible — calls without opts continue to work
+  // and simply audit with userId-only actor.
+  opts = opts || {};
+  function _actorFor(grantRow) {
+    return requestHelpers.extractActorContext(opts.req, {
+      userId: grantRow.issuedToActorId,
+    });
+  }
   if (typeof table !== "string" || table.length === 0) {
     throw new BreakGlassError("breakglass/bad-grant-opts",
       "unsealRow: table must be a non-empty string");
@@ -806,7 +817,7 @@ async function unsealRow(grantHandle, table, rowId) {
     audit.safeEmit({
       action:   "breakglass.unsealrow",
       outcome:  "denied",
-      actor:    { userId: grantRow.issuedToActorId },
+      actor:    _actorFor(grantRow),
       reason:   "grant-table-mismatch",
       metadata: { grantId: grantRow._id, expectedTable: grantRow.scopeTable, gotTable: table, rowId: String(rowId) },
     });
@@ -827,7 +838,7 @@ async function unsealRow(grantHandle, table, rowId) {
     audit.safeEmit({
       action:   "breakglass.grant.expired",
       outcome:  "success",
-      actor:    { userId: grantRow.issuedToActorId },
+      actor:    _actorFor(grantRow),
       metadata: { grantId: grantRow._id, table: table, rowsConsumed: Number(grantRow.rowsConsumed) },
     });
     throw new BreakGlassError("breakglass/grant-expired",
@@ -840,7 +851,7 @@ async function unsealRow(grantHandle, table, rowId) {
     audit.safeEmit({
       action:   "breakglass.grant.exhausted",
       outcome:  "success",
-      actor:    { userId: grantRow.issuedToActorId },
+      actor:    _actorFor(grantRow),
       metadata: { grantId: grantRow._id, table: table, rowsConsumed: Number(grantRow.rowsConsumed) },
     });
     throw new BreakGlassError("breakglass/grant-exhausted",
@@ -932,7 +943,7 @@ async function unsealRow(grantHandle, table, rowId) {
   audit.safeEmit({
     action:    "breakglass.unsealrow",
     outcome:   "success",
-    actor:     { userId: grantRow.issuedToActorId },
+    actor:     _actorFor(grantRow),
     reason:    reasonForAudit.cleartext,
     metadata:  {
       grantId:        grantRow._id,

package/lib/cookies.js

@@ -151,7 +151,17 @@ function serialize(name, value, attrs) {
     parts.push("Expires=" + d.toUTCString());
   }
   if (attrs.domain) {
-    parts.push("Domain=" + _scrubAttr(String(attrs.domain)));
+    var dom = _scrubAttr(String(attrs.domain));
+    // RFC 6265 §4.1.2.3 + §5.1.3: Domain attribute is a host name.
+    // A leading "." is tolerated by browsers (legacy form). Anything
+    // else (URLs, paths, spaces, scheme prefixes) makes browsers
+    // either ignore the cookie or apply it inconsistently.
+    if (!/^\.?[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/i.test(dom)) {
+      throw new CookieError("cookies/invalid-attr",
+        "cookie attr domain must be a valid host name " +
+        "(letters/digits/dots/hyphens, optional leading dot), got " + JSON.stringify(dom));
+    }
+    parts.push("Domain=" + dom);
   }
   if (attrs.path !== undefined && attrs.path !== null) {
     parts.push("Path=" + _scrubAttr(String(attrs.path)));

package/lib/error-page.js

@@ -39,6 +39,7 @@
  */
 
 var lazyRequire = require("./lazy-require");
+var requestHelpers = require("./request-helpers");
 var template = require("./template");
 var audit = lazyRequire(function () { return require("./audit"); });
 
@@ -280,6 +281,10 @@ function create(opts) {
   var auditAction = typeof opts.auditAction === "string" && opts.auditAction.length > 0
     ? opts.auditAction
     : "request.error";
+  // Same proxy-trust boundary as the rest of the framework — without
+  // trustProxy, X-Forwarded-For is ignored as attacker-forgeable.
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
   // defaultFormat:
   //   "auto"  (default) — negotiate via Accept header
   //   "json"           — always JSON (API-style middleware default)
@@ -355,12 +360,16 @@ function create(opts) {
         audit().emit({
           action:   auditAction,
           outcome:  info.status >= 500 ? "failure" : "denied",
-          actor:    {
-            ip:        req && req.headers && req.headers["x-forwarded-for"] ||
-                       (req && req.socket && req.socket.remoteAddress),
-            userAgent: req && req.headers && req.headers["user-agent"],
-            sessionId: req && req.session && req.session.sid,
-          },
+          actor:    requestHelpers.extractActorContext(req, {
+            // Honor the framework's trustProxy boundary — extractActorContext
+            // reads from req.socket.remoteAddress, but we want X-Forwarded-For
+            // resolution gated by the operator's opt.
+            ip:        requestHelpers.clientIp(req, { trustProxy: trustProxy }),
+            // sessionId from session.sid for back-compat with the
+            // pre-extractActorContext shape (extractActorContext also
+            // checks session.id; passing both via override is safe).
+            sessionId: req && req.session && (req.session.sid || req.session.id),
+          }),
           metadata: {
             status:    info.status,
             code:      info.code,

package/lib/middleware/cors.js

@@ -174,7 +174,13 @@ function create(opts) {
   }
 
   var methods = (opts.methods || ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]).join(", ");
-  var headers = (opts.headers || ["Content-Type", "Authorization", "X-Request-Id"]).join(", ");
+  var headersList = (opts.headers || ["Content-Type", "Authorization", "X-Request-Id"]).slice();
+  var headers = headersList.join(", ");
+  // Pre-compute the lowercase allowlist once at create() time so the
+  // preflight path doesn't re-derive it per-request from the joined
+  // string. Avoids coupling allow-list validation to the wire-format
+  // serialization.
+  var allowedHeadersSet = headersList.map(function (h) { return String(h).trim().toLowerCase(); });
   var exposeHeaders = (opts.exposeHeaders || ["X-Request-Id"]).join(", ");
   var credentials = !!opts.credentials;
   var maxAge = String(opts.maxAgeSeconds || 600);
@@ -230,10 +236,9 @@ function create(opts) {
       if (refuseUnknown) {
         var requestedHdrs = req.headers["access-control-request-headers"];
         if (requestedHdrs) {
-          var allowedSet = headers.toLowerCase().split(",").map(function (s) { return s.trim(); });
           var asked = String(requestedHdrs).toLowerCase().split(",").map(function (s) { return s.trim(); }).filter(Boolean);
           for (var ah = 0; ah < asked.length; ah++) {
-            if (allowedSet.indexOf(asked[ah]) === -1) {
+            if (allowedHeadersSet.indexOf(asked[ah]) === -1) {
               if (typeof res.writeHead === "function") {
                 res.writeHead(403, { "Content-Type": "text/plain" });
                 res.end("CORS: requested header '" + asked[ah] + "' not in allow-list");

package/lib/middleware/rate-limit.js

@@ -240,6 +240,14 @@ function create(opts) {
   var bodyOnLimit = opts.bodyOnLimit !== undefined ? opts.bodyOnLimit : "Too Many Requests";
   var emitHeaders = opts.header !== false;
   var skipPaths = opts.skipPaths || [];
+  // Tier-A: each entry must be a string prefix or a RegExp. Anything
+  // else would crash _shouldSkip with TypeError on the first request.
+  for (var sp = 0; sp < skipPaths.length; sp++) {
+    if (typeof skipPaths[sp] !== "string" && !(skipPaths[sp] instanceof RegExp)) {
+      throw new Error("middleware.rateLimit: skipPaths[" + sp +
+        "] must be a string prefix or RegExp, got " + typeof skipPaths[sp]);
+    }
+  }
   var scope = opts.scope || "global";
 
   var backend = _resolveBackend(opts);

package/lib/pagination.js

@@ -214,6 +214,15 @@ async function cursor(query, opts) {
   }
   var limit     = _resolveLimit(opts);
   var orderBy   = typeof opts.orderBy === "string" && opts.orderBy.length > 0 ? opts.orderBy : "_id";
+  // Tier-A on orderBy — the value is interpolated into a raw SQL fragment
+  // for the keyset where-clause. Restrict to identifier-safe characters
+  // so a careless caller piping `req.query.orderBy` through doesn't
+  // create an SQL-injection vector.
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(orderBy)) {
+    throw new PaginationError("pagination/bad-orderby",
+      "cursor: orderBy must match /^[A-Za-z_][A-Za-z0-9_]*$/ (identifier-safe), got " +
+      JSON.stringify(orderBy));
+  }
   var direction = (opts.direction === "desc") ? "desc" : "asc";
 
   // Decode incoming cursor (if any) and override direction from cursor.
@@ -332,6 +341,13 @@ async function offset(query, opts) {
   var page = parseInt(opts.page, 10);
   if (isNaN(page) || page < 1) page = 1;
   var orderBy = typeof opts.orderBy === "string" && opts.orderBy.length > 0 ? opts.orderBy : "_id";
+  // Same Tier-A on offset() as cursor() — orderBy passes through to the
+  // db Query; identifier-safe-only to prevent SQL injection.
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(orderBy)) {
+    throw new PaginationError("pagination/bad-orderby",
+      "offset: orderBy must match /^[A-Za-z_][A-Za-z0-9_]*$/ (identifier-safe), got " +
+      JSON.stringify(orderBy));
+  }
   var direction = (opts.direction === "desc") ? "desc" : "asc";
 
   // Count gives total — required for totalPages calculation. Cheap on

package/lib/queue.js

@@ -70,7 +70,12 @@ function init(opts) {
   }
 
   backends = {};
-  for (var name in opts.backends) {
+  // IIFE per-iteration so each backend's wrappers close over its own
+  // raw / breaker / cfg. With `var` (function-scoped) those bindings
+  // would otherwise be shared across iterations and every wrapper
+  // would end up using the LAST backend's breaker + retry config —
+  // multi-backend isolation broken without a single error surfacing.
+  Object.keys(opts.backends).forEach(function (name) {
     var cfg = opts.backends[name];
     var proto = dispatcher.resolve(cfg.protocol);
     var raw = proto.create(cfg);
@@ -114,7 +119,7 @@ function init(opts) {
       dlqRetry:      raw.dlqRetry ? wrapWithRetry(raw.dlqRetry) : null,
       dlqSize:       raw.dlqSize ? wrapWithRetry(raw.dlqSize) : null,
     };
-  }
+  });
 
   defaultBackend = opts.defaultBackend || Object.keys(backends)[0];
 

package/lib/uuid.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * uuid — RFC 4122 v4 (random) + RFC 9562 v7 (time-ordered).
+ *
+ * Two flavors:
+ *
+ *   b.uuid.v4()           — fully random 128-bit UUID. Standard, portable,
+ *                           the default choice when ordering doesn't matter.
+ *
+ *   b.uuid.v7()           — Unix-millisecond timestamp prefix + 74 random
+ *                           bits. Time-ordered (sorts by creation time even
+ *                           lexicographically), ideal as a database PK
+ *                           because B-tree inserts stay near the right edge
+ *                           — no random scattering across the index.
+ *
+ *   b.uuid.parse(str)     — { ok, version, bytes }. Validates the canonical
+ *                           8-4-4-4-12 hex form and the version + variant
+ *                           bits. Returns ok:false (no throw) on bad input.
+ *
+ *   b.uuid.isValid(str)   — boolean shorthand. No version/variant check
+ *                           beyond shape — operators who care use parse().
+ *
+ * All entropy comes from `b.crypto.generateBytes`, which routes through
+ * `node:crypto.randomBytes` — same source as `crypto.randomUUID()`.
+ *
+ * Why ship v7 ourselves? Native `crypto.randomUUID()` only emits v4.
+ * v7 is the modern recommendation for any UUID landing in a sortable
+ * column (jobs queue, audit chain extensions, anything where insertion
+ * order matters for index locality).
+ */
+var { generateBytes } = require("./crypto");
+
+// Canonical UUID layout: 8-4-4-4-12 hex digits, version nibble at byte
+// 6 high-nibble, variant bits at byte 8 high two bits (must be 10).
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+// Loose form for `isValid` shape-only check — accepts any version 1-8 and
+// any variant top-2-bit value. Operators wanting strict version+variant
+// gating use `parse()`.
+var UUID_LOOSE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function _bytesToString(bytes) {
+  var hex = bytes.toString("hex");
+  return hex.slice(0, 8) + "-" +
+         hex.slice(8, 12) + "-" +
+         hex.slice(12, 16) + "-" +
+         hex.slice(16, 20) + "-" +
+         hex.slice(20, 32);
+}
+
+function v4() {
+  var b = generateBytes(16);
+  // version = 4 (0100): high nibble of byte 6
+  b[6] = (b[6] & 0x0f) | 0x40;
+  // variant = RFC 4122 (10xx): top two bits of byte 8
+  b[8] = (b[8] & 0x3f) | 0x80;
+  return _bytesToString(b);
+}
+
+function v7(opts) {
+  // RFC 9562 §5.7 layout:
+  //   bytes 0-5  : 48-bit big-endian Unix timestamp in milliseconds
+  //   bytes 6-7  : version nibble (7) + 12 bits random_a
+  //   bytes 8-15 : variant bits + 62 bits random_b
+  var ms = (opts && typeof opts.now === "number") ? opts.now : Date.now();
+  var b = generateBytes(16);
+  // 48-bit ms timestamp (big-endian) into bytes 0-5
+  // ms can exceed 2^32 (we're in 2026, ms is ~1.78e12), so use Math + bit ops carefully
+  var msHi = Math.floor(ms / 0x100000000);    // top 16 bits live in low 16 of msHi
+  var msLo = ms >>> 0;                        // bottom 32 bits unsigned
+  b[0] = (msHi >> 8) & 0xff;
+  b[1] = msHi & 0xff;
+  b[2] = (msLo >>> 24) & 0xff;
+  b[3] = (msLo >>> 16) & 0xff;
+  b[4] = (msLo >>> 8) & 0xff;
+  b[5] = msLo & 0xff;
+  // version = 7 (0111) in high nibble of byte 6, random_a in low nibble + byte 7
+  b[6] = (b[6] & 0x0f) | 0x70;
+  // variant = RFC 4122 (10xx) in top two bits of byte 8
+  b[8] = (b[8] & 0x3f) | 0x80;
+  return _bytesToString(b);
+}
+
+function parse(str) {
+  if (typeof str !== "string") return { ok: false, reason: "not-a-string" };
+  if (!UUID_RE.test(str))      return { ok: false, reason: "malformed" };
+  var hex = str.replace(/-/g, "");
+  var bytes = Buffer.from(hex, "hex");
+  // Version is the high nibble of byte 6.
+  var version = (bytes[6] >> 4) & 0x0f;
+  // Variant: top two bits of byte 8 must be 10 for RFC 4122 / 9562.
+  var variant = (bytes[8] >> 6) & 0x03;
+  if (variant !== 0b10) return { ok: false, reason: "bad-variant" };
+  return { ok: true, version: version, bytes: bytes };
+}
+
+function isValid(str) {
+  return typeof str === "string" && UUID_LOOSE_RE.test(str);
+}
+
+module.exports = {
+  v4:      v4,
+  v7:      v7,
+  parse:   parse,
+  isValid: isValid,
+};

package/package.json

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