@blamejs/core 0.14.16 → 0.14.18

package/lib/render.js

@@ -82,17 +82,35 @@ var DEFAULT_DYNAMIC_CACHE_CONTROL = "private, no-cache, must-revalidate";
  * without losing Content-Type. Returns `undefined` — the response
  * is fully written by the time the call returns.
  *
+ * `opts.replacer` is forwarded to `JSON.stringify` (ECMA-262 §25.5.2,
+ * the second argument) so handlers can serialize values that have no
+ * native JSON form — `BigInt` (which otherwise throws), `Date` in a
+ * custom shape, `Map` / `Set`, or a redaction filter over secret-
+ * shaped keys — without pre-walking the body. Accepts the same
+ * function or property-name array `JSON.stringify` does; a non-
+ * function / non-array value is a config typo and throws.
+ *
  * @opts
- *   status:  200,   // numeric HTTP status (200/201/202/4xx/5xx)
- *   headers: {},    // merged over defaults; later wins
+ *   status:   200,                  // numeric HTTP status (200/201/202/4xx/5xx)
+ *   headers:  {},                   // merged over defaults; later wins
+ *   replacer: function|string[],    // JSON.stringify replacer (BigInt/Date/redaction)
  *
  * @example
  *   b.render.json(res, { ok: true, id: 42 }, { status: 201 });
  *   // → response: 201, application/json, body `{"ok":true,"id":42}`
+ *
+ *   b.render.json(res, { total: 9007199254740993n }, {
+ *     replacer: function (k, v) { return typeof v === "bigint" ? v.toString() : v; },
+ *   });
+ *   // → body `{"total":"9007199254740993"}`
  */
 function json(res, body, opts) {
   opts = opts || {};
-  var encoded = JSON.stringify(body);
+  if (opts.replacer !== undefined && opts.replacer !== null &&
+      typeof opts.replacer !== "function" && !Array.isArray(opts.replacer)) {
+    throw new TypeError("render.json: opts.replacer must be a function or an array of keys");
+  }
+  var encoded = JSON.stringify(body, opts.replacer);
   var headers = _mergedHeaders({
     "Content-Type":   "application/json; charset=utf-8",
     "Content-Length": Buffer.byteLength(encoded, "utf8"),

package/lib/router.js

@@ -112,13 +112,20 @@ function _validateRouteSpec(spec, method, pattern) {
   }
 }
 
-function _writeValidationError(res, where, errors) {
+function _writeValidationError(req, res, where, errors) {
   if (res.writableEnded || res.headersSent) return;
-  var body = JSON.stringify({
+  var payload = {
     error: "validation",
     where: where,
     issues: errors,
-  });
+  };
+  var body = JSON.stringify(payload);
+  // Seal the body when an encrypted session is active; pre-session paths
+  // (Bearer auth, handshake reject, replay refusal) lack the encoder and
+  // stay plaintext. An encryption failure falls back to the plaintext body.
+  if (req && typeof req.apiEncryptEncode === "function") {
+    try { body = JSON.stringify(req.apiEncryptEncode(payload)); } catch (_e) { /* plaintext body kept */ }
+  }
   res.writeHead(HTTP_STATUS.BAD_REQUEST, {
     "Content-Type":   "application/json; charset=utf-8",
     "Content-Length": Buffer.byteLength(body),
@@ -131,17 +138,17 @@ function _makeSchemaValidator(spec) {
   return function schemaValidator(req, res, next) {
     if (spec.params && req.params !== undefined) {
       var pp = spec.params.safeParse(req.params);
-      if (!pp.ok) return _writeValidationError(res, "params", pp.errors);
+      if (!pp.ok) return _writeValidationError(req, res, "params", pp.errors);
       req.params = pp.value;
     }
     if (spec.query && req.query !== undefined) {
       var qq = spec.query.safeParse(req.query);
-      if (!qq.ok) return _writeValidationError(res, "query", qq.errors);
+      if (!qq.ok) return _writeValidationError(req, res, "query", qq.errors);
       req.query = qq.value;
     }
     if (spec.body && req.body !== undefined) {
       var bb = spec.body.safeParse(req.body);
-      if (!bb.ok) return _writeValidationError(res, "body", bb.errors);
+      if (!bb.ok) return _writeValidationError(req, res, "body", bb.errors);
       req.body = bb.value;
     }
     next();

package/lib/safe-buffer.js

@@ -321,6 +321,60 @@ function boundedChunkCollector(opts) {
   };
 }
 
+/**
+ * @primitive b.safeBuffer.collectStream
+ * @signature b.safeBuffer.collectStream(stream, opts)
+ * @since     0.14.18
+ * @related   b.safeBuffer.boundedChunkCollector, b.safeBuffer.toBuffer
+ *
+ * Read a Node Readable (an `http.IncomingMessage` request body, a file
+ * stream, an upstream response) fully into one Buffer with the byte cap
+ * enforced at every chunk — the streaming sibling of
+ * `boundedChunkCollector`. `boundedChunkCollector` is a push-based
+ * collector object; `collectStream` is the pump around it, so callers
+ * compose the stream case instead of reaching for a `(stream, opts)`
+ * overload that does not exist.
+ *
+ * Resolves with the concatenated Buffer when the stream ends. Rejects
+ * (and destroys the stream) the moment a chunk would overflow
+ * `maxBytes`, so a hostile sender cannot force unbounded buffering. A
+ * bad `maxBytes` (missing / non-finite / `Infinity`) rejects rather than
+ * throwing synchronously.
+ *
+ * @opts
+ *   maxBytes:    number,     // REQUIRED positive finite int; total byte cap
+ *   errorClass:  Function,   // caller Error subclass for the too-large reject
+ *   sizeCode:    string,     // default "buffer/too-large"
+ *   sizeMessage: string,     // override the too-large message
+ *
+ * @example
+ *   var body = await b.safeBuffer.collectStream(req, { maxBytes: 65536 });
+ *   var json = b.safeJson.parse(body.toString("utf8"));
+ *   // → the parsed request body, never more than 64 KiB buffered
+ */
+function collectStream(stream, opts) {
+  return new Promise(function (resolve, reject) {
+    var collector;
+    try { collector = boundedChunkCollector(opts || {}); }
+    catch (e) { reject(e); return; }
+    var done = false;
+    function fail(e) {
+      if (done) return;
+      done = true;
+      try { if (stream && typeof stream.destroy === "function") stream.destroy(); }
+      catch (_e) { /* socket already closed */ }
+      reject(e);
+    }
+    stream.on("data", function (chunk) {
+      if (done) return;
+      try { collector.push(chunk); }
+      catch (e) { fail(e); }
+    });
+    stream.on("end", function () { if (!done) { done = true; resolve(collector.result()); } });
+    stream.on("error", fail);
+  });
+}
+
 /**
  * @primitive b.safeBuffer.secureZero
  * @signature b.safeBuffer.secureZero(buf)
@@ -552,6 +606,7 @@ module.exports = {
   normalizeText:         normalizeText,
   toBuffer:              toBuffer,
   boundedChunkCollector: boundedChunkCollector,
+  collectStream: collectStream,
   secureZero:            secureZero,
   isHex:                 isHex,
   hasCrlf:               hasCrlf,

package/lib/sse.js

@@ -287,7 +287,7 @@ function create(req, res, opts) {
     _writeRaw(":" + text + "\n\n");
   }
 
-  function close() {
+  function close(cause) {
     if (closed) return;
     closed = true;
     if (heartbeatTimer) {
@@ -296,10 +296,12 @@ function create(req, res, opts) {
     }
     try { res.end(); } catch (_e) { /* already destroyed */ }
     if (auditOn) {
+      var closeMeta = { lastEventId: lastEventId };
+      if (cause) closeMeta.reason = cause.reason || "fault";
       audit.safeEmit({
         action:   "sse.channel_closed",
-        outcome:  "success",
-        metadata: { lastEventId: lastEventId },
+        outcome:  cause ? "failure" : "success",
+        metadata: closeMeta,
       });
     }
   }
@@ -308,7 +310,7 @@ function create(req, res, opts) {
   // the heartbeat timer.
   if (typeof res.on === "function") {
     res.on("close",  close);
-    res.on("error",  function (_e) { close(); });
+    res.on("error",  function (_e) { close({ reason: "stream-error" }); });
     res.on("finish", function () { closed = true; if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; } });
   }
 
@@ -325,7 +327,7 @@ function create(req, res, opts) {
     heartbeatTimer = setInterval(function () {
       if (closed) return;
       try { _writeRaw(":keepalive\n\n"); }
-      catch (_e) { close(); }
+      catch (_e) { close({ reason: "heartbeat-write-failed" }); }
     }, heartbeatMs).unref();
   }
 

package/lib/static.js

@@ -6,7 +6,8 @@
  * quotas (cluster-shared via b.cache), Range support (RFC 7233 single-range),
  * the full conditional-request set (If-None-Match / If-Match /
  * If-Modified-Since / If-Unmodified-Since), MIME allowlist with magic-byte
- * verification (composes b.fileType), per-request operator hook, idle-stream
+ * verification (composes b.fileType), per-request operator hooks (onServe
+ * on the success path, onError on every refusal path), idle-stream
  * timeout, cancellation propagation, force-revoke, and compliance-retention
  * gating.
  *
@@ -16,6 +17,12 @@
  *   var mw = serve.middleware;                       // (req, res, next)
  *   await b.staticServe.integrity(absFilePath);      // SRI helper (SHA-384)
  *
+ *   // onError mirrors onServe for the refusal paths (403 / 404 / 415 /
+ *   // 412 / 416 / 429 / 451 / 500): it receives
+ *   // { req, res, urlPath, absPath, status, code, actor } AFTER the
+ *   // refusal response is written. Observability-only — a throw is
+ *   // swallowed so a broken hook can't tear down the socket.
+ *
  * Backwards compatible: every existing opt (root, mountPath,
  * hashedPathPattern, indexFile, defaultMaxAge, contentTypes) keeps its
  * original meaning. New opts (permissions, cache, audit, observability,
@@ -450,6 +457,7 @@ function _validateCreateOpts(opts) {
   validateOpts.auditShape(opts.audit, "staticServe.create", StaticServeError);
   validateOpts.observabilityShape(opts.observability, "staticServe.create", StaticServeError);
   validateOpts.optionalFunction(opts.onServe, "staticServe.create: onServe", StaticServeError);
+  validateOpts.optionalFunction(opts.onError, "staticServe.create: onError", StaticServeError);
   // contentSafety — extension-keyed gate map. Default behaviour: when
   // undefined, the framework wires b.guardAll.byExtension({ profile:
   // "strict" }) automatically so every shipped guard is ON by default.
@@ -604,7 +612,7 @@ function create(opts) {
     "root", "mountPath", "hashedPathPattern",
     "indexFile", "defaultMaxAge", "contentTypes",
     "permissions", "cache", "fileType", "retention", "revokeStore",
-    "allowedFileTypes", "audit", "observability", "onServe",
+    "allowedFileTypes", "audit", "observability", "onServe", "onError",
     "acceptRanges", "auditSuccess", "auditFailures",
     "maxBytesPerActorPerWindowMs", "maxBytesAllActorsPerWindowMs",
     "bandwidthWindowMs", "maxConcurrentDownloadsPerActor", "maxIdleMs",
@@ -657,6 +665,7 @@ function create(opts) {
     contentSafety = opts.contentSafety;
   }
   var onServe         = opts.onServe || null;
+  var onError         = opts.onError || null;
   var audit           = opts.audit || null;
   var auditSuccess    = cfg.auditSuccess;
   var auditFailures   = cfg.auditFailures;
@@ -756,6 +765,26 @@ function create(opts) {
     var actorCtx = requestHelpers.extractActorContext(req);
     var actorKey = _actorKeyFromContext(actorCtx);
 
+    // Request-scoped error writer. Wraps the module-level _writeError so
+    // every refusal path (403 / 404 / 415 / 412 / 416 / 429 / 451 / 500)
+    // also invokes the operator's onError hook — the success-path mirror
+    // of onServe. The signature matches _writeError exactly; the `code`
+    // argument routes through to the hook so operators can branch on the
+    // refusal reason. The hook is observability-only: it runs AFTER the
+    // response is written and a throw is swallowed so a broken sink can't
+    // turn a 4xx into a torn-down socket.
+    function writeErr(r, status, code, message, headers) {
+      _writeError(r, status, code, message, headers);
+      if (onError) {
+        try {
+          onError({
+            req: req, res: r, urlPath: urlPath, absPath: absPath,
+            status: status, code: code, actor: actorCtx,
+          });
+        } catch (_he) { /* hook best-effort */ }
+      }
+    }
+
     // Permission gate (403)
     var perm = await _checkPermission(req);
     if (!perm.ok) {
@@ -766,7 +795,7 @@ function create(opts) {
           outcome: "failure", reason: "permission_denied", resource: urlPath,
         }, actorCtx));
       }
-      return _writeError(res, HTTP.FORBIDDEN, "permission_denied",
+      return writeErr(res, HTTP.FORBIDDEN, "permission_denied",
         "Forbidden");
     }
 
@@ -788,7 +817,7 @@ function create(opts) {
           outcome: "failure", reason: "revoked", resource: urlPath,
         }, actorCtx));
       }
-      return _writeError(res, HTTP.NOT_FOUND, "not_found", "Not Found");
+      return writeErr(res, HTTP.NOT_FOUND, "not_found", "Not Found");
     }
 
     // Compliance retention (451)
@@ -800,7 +829,7 @@ function create(opts) {
           outcome: "failure", reason: "retention_blocked", resource: urlPath,
         }, actorCtx));
       }
-      return _writeError(res, HTTP.UNAVAILABLE_FOR_LEGAL_REASONS,
+      return writeErr(res, HTTP.UNAVAILABLE_FOR_LEGAL_REASONS,
         "retention_blocked", "Unavailable For Legal Reasons");
     }
 
@@ -820,7 +849,7 @@ function create(opts) {
             detectedMime: mimeCheck.detected || null,
           }, actorCtx));
         }
-        return _writeError(res, HTTP.UNSUPPORTED_MEDIA_TYPE,
+        return writeErr(res, HTTP.UNSUPPORTED_MEDIA_TYPE,
           "mime_rejected", "Unsupported Media Type");
       }
     }
@@ -861,7 +890,7 @@ function create(opts) {
         catch (_e) {
           stats.failures += 1;
           if (gateHandle) { try { await gateHandle.close(); } catch (_ce) { /* close best-effort */ } }
-          return _writeError(res, HTTP.INTERNAL_SERVER_ERROR,
+          return writeErr(res, HTTP.INTERNAL_SERVER_ERROR,
             "read_failed", "Internal Server Error");
         }
         try { await gateHandle.close(); } catch (_ce) { /* close best-effort */ }
@@ -885,7 +914,7 @@ function create(opts) {
               error: gateErr && gateErr.message,
             }, actorCtx));
           }
-          return _writeError(res, HTTP.INTERNAL_SERVER_ERROR,
+          return writeErr(res, HTTP.INTERNAL_SERVER_ERROR,
             "content_safety_threw", "Internal Server Error");
         }
         if (!gateDecision.ok || gateDecision.action === "refuse") {
@@ -898,7 +927,7 @@ function create(opts) {
               issues: gateContract.summarizeIssues(gateDecision.issues),
             }, actorCtx));
           }
-          return _writeError(res, HTTP.UNSUPPORTED_MEDIA_TYPE,
+          return writeErr(res, HTTP.UNSUPPORTED_MEDIA_TYPE,
             "content_safety_refused", "Unsupported Media Type");
         }
         if (gateDecision.action === "sanitize" && gateDecision.sanitized) {
@@ -929,7 +958,7 @@ function create(opts) {
     if (ifMatch && ifMatch !== "*" && ifMatch !== meta.etag) {
       stats.failures += 1;
       _emitObs("staticServe.precondition_failed", 1, { route: urlPath, header: "if-match" });
-      return _writeError(res, HTTP.PRECONDITION_FAILED || 412,
+      return writeErr(res, HTTP.PRECONDITION_FAILED || 412,
         "precondition_failed", "Precondition Failed");
     }
 
@@ -956,7 +985,7 @@ function create(opts) {
       if (isFinite(ius) && Math.floor(meta.mtimeMs / C.TIME.seconds(1)) > Math.floor(ius / C.TIME.seconds(1))) {
         stats.failures += 1;
         _emitObs("staticServe.precondition_failed", 1, { route: urlPath, header: "if-unmodified-since" });
-        return _writeError(res, HTTP.PRECONDITION_FAILED,
+        return writeErr(res, HTTP.PRECONDITION_FAILED,
           "precondition_failed", "Precondition Failed");
       }
     }
@@ -970,19 +999,19 @@ function create(opts) {
         if (range && (range.malformed || range.multi)) {
           stats.failures += 1;
           _emitObs("staticServe.range_invalid", 1, { route: urlPath });
-          return _writeError(res, HTTP.RANGE_NOT_SATISFIABLE, "range_not_satisfiable",
+          return writeErr(res, HTTP.RANGE_NOT_SATISFIABLE, "range_not_satisfiable",
             "Range Not Satisfiable", { "Content-Range": "bytes */" + meta.size });
         }
         if (range && range.unsatisfiable) {
           stats.failures += 1;
           _emitObs("staticServe.range_invalid", 1, { route: urlPath });
-          return _writeError(res, HTTP.RANGE_NOT_SATISFIABLE, "range_not_satisfiable",
+          return writeErr(res, HTTP.RANGE_NOT_SATISFIABLE, "range_not_satisfiable",
             "Range Not Satisfiable", { "Content-Range": "bytes */" + meta.size });
         }
         if (range && cfg.maxRangeBytes !== Infinity && range.length > cfg.maxRangeBytes) {
           stats.failures += 1;
           _emitObs("staticServe.range_too_large", 1, { route: urlPath });
-          return _writeError(res, HTTP.RANGE_NOT_SATISFIABLE, "range_too_large",
+          return writeErr(res, HTTP.RANGE_NOT_SATISFIABLE, "range_too_large",
             "Range Not Satisfiable", { "Content-Range": "bytes */" + meta.size });
         }
         if (range) {
@@ -1005,7 +1034,7 @@ function create(opts) {
           current: concCheck.current, cap: concCheck.cap,
         }, actorCtx));
       }
-      return _writeError(res, HTTP.TOO_MANY_REQUESTS,
+      return writeErr(res, HTTP.TOO_MANY_REQUESTS,
         "concurrency_cap", "Too Many Requests",
         { "Retry-After": "5" });
     }
@@ -1021,7 +1050,7 @@ function create(opts) {
           scope: bwCheck.scope, used: bwCheck.used, cap: bwCheck.cap,
         }, actorCtx));
       }
-      return _writeError(res, HTTP.TOO_MANY_REQUESTS,
+      return writeErr(res, HTTP.TOO_MANY_REQUESTS,
         "bandwidth_quota", "Too Many Requests",
         { "Retry-After": String(bwCheck.retryAfter) });
     }
@@ -1077,7 +1106,7 @@ function create(opts) {
             error: e && e.message,
           }, actorCtx));
         }
-        return _writeError(res, HTTP.INTERNAL_SERVER_ERROR, "onServe_threw",
+        return writeErr(res, HTTP.INTERNAL_SERVER_ERROR, "onServe_threw",
           "Internal Server Error");
       }
     }

package/lib/uri-template.js

@@ -29,6 +29,7 @@
  */
 
 var { defineClass } = require("./framework-error");
+var codepointClass = require("./codepoint-class");
 
 var UriTemplateError = defineClass("UriTemplateError", { alwaysPermanent: true });
 
@@ -59,7 +60,8 @@ function _pctEncode(str, allowReserved) {
     var ch = str.charAt(i);
     // Preserve existing percent-encoded triplets when the reserved set is
     // allowed (operators "+" and "#").
-    if (allowReserved && ch === "%" && /^[0-9A-Fa-f]{2}$/.test(str.substr(i + 1, 2))) {
+    // allow:regex-no-length-cap — the substr is a fixed 2-char window
+    if (allowReserved && ch === "%" && codepointClass.HEX_PAIR_RE.test(str.substr(i + 1, 2))) {
       out += str.substr(i, 3); i += 2; continue;
     }
     if (UNRESERVED.test(ch) || (allowReserved && RESERVED.test(ch))) { out += ch; continue; }

package/package.json

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

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:44556dbf-5411-4644-ab81-5f0571d5e036",
+  "serialNumber": "urn:uuid:b96f0679-8967-43f9-b412-aa598ea52508",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-01T02:09:53.597Z",
+    "timestamp": "2026-06-02T15:25:35.604Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.14.16",
+      "bom-ref": "@blamejs/core@0.14.18",
       "type": "application",
       "name": "blamejs",
-      "version": "0.14.16",
+      "version": "0.14.18",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.14.16",
+      "purl": "pkg:npm/%40blamejs/core@0.14.18",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.14.16",
+      "ref": "@blamejs/core@0.14.18",
       "dependsOn": []
     }
   ]