@blamejs/core 0.15.29 → 0.15.31

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.15.x
 
+- v0.15.31 (2026-06-26) — **Internal test-suite hardening only — the published library's runtime behavior and public API are unchanged (source-comment marker text aside).** The codebase-patterns guard suite gains a gate that retires a renamed suppression-marker token: once a suppression class is re-verified and renamed, its old token cannot be silently re-registered, so a later suppression has to be re-examined under the new name instead of inheriting a stale approval. Eight suppression classes were re-verified and renamed to descriptive tokens this release, and their in-source marker comments were updated to match. No runtime code, public API, or wire format changed. **Detectors:** *Re-verification gate retires a renamed suppression-marker token* — A new guard refuses to re-register a retired suppression-marker token, and the orphan check points a stale marker at its current name. When a suppression class is re-verified, it is renamed to a descriptive token and the old name is recorded as retired, so the old approval cannot be quietly resurrected — a future suppression must be re-examined and re-stamped under the new name. This is test-suite tooling; no shipped framework behavior changed.
+
+- v0.15.30 (2026-06-26) — **Importing the webhook module for inbound signature verification no longer pulls the Node HTTP client (or its `node:http` / `node:https` / `node:http2` chain), so `b.webhook.verify` runs in a Worker / edge runtime when the module is imported directly.** lib/webhook and its delivery store eagerly required the outbound HTTP client at module load — directly, and transitively through the persistence-backed dispatcher — so importing the webhook module threw in a Cloudflare Workers / edge runtime that has no node:http / node:net / node:tls, even though b.webhook.verify needs only HMAC-SHA-256 and a timing-safe compare. The HTTP client and the SQL-backed dispatcher are now resolved lazily, only on the outbound send / dispatch paths; importing the module for inbound verification loads no Node networking module. Verified by asserting no networking builtin appears in process.moduleLoadList on the verify path. The framework's aggregate entry point still initializes the networking stack eagerly, so the edge verify path is the webhook module imported directly rather than the aggregate b namespace. **Fixed:** *Inbound webhook verification loads without the Node networking stack (Worker / edge runtime)* — The webhook module and its dispatcher delivery store required the outbound HTTP client (node:http / node:https / node:http2) at module load, so importing the module threw in a runtime without those builtins — even though b.webhook.verify is HMAC-SHA-256 plus a timing-safe compare and the dispatcher (SQL-backed persistence) is only needed for outbound delivery. The HTTP client and the dispatcher are now resolved lazily, on the outbound send / dispatch paths only; the inbound verify path loads no Node networking module. An edge handler that imports the webhook module directly can pre-verify an inbound Stripe webhook signature with the primitive's hardening (Stripe-Signature size cap, v1-hex anti-DoS cap, minimum-tolerance floor, optional atomic replay store) instead of hand-rolling the t=/v1= parse, tolerance window, and timing-safe compare. The framework's aggregate entry still loads the networking stack eagerly; import the webhook module directly for the edge verify path.
+
 - v0.15.29 (2026-06-25) — **JSON parsing of operator and untrusted input is routed through `b.safeJson` everywhere, so a `"__proto__"` member is stripped and the parse is size-bounded — `b.openapi.parse`, `b.asyncapi.parse`, and `b.sandbox.run` were using a raw `JSON.parse`.** b.openapi.parse and b.asyncapi.parse parsed an operator-supplied document string with a raw JSON.parse, which re-creates a "__proto__" member as an own key and imposes no size bound; b.sandbox.run parsed the untrusted sandboxed code's serialized result the same way (proto member kept, depth unbounded). All three now route through b.safeJson, which strips the prototype-pollution keys and applies the depth / key / size caps. A new b.safeJson.parseStringOrObject primitive captures the recurring "accept a document as a JSON string OR a pre-built object" shape (a string is parsed safely, an object passes through) that openapi and asyncapi had each hand-rolled, with each consumer's typed error class and a generous document size cap passed as data. Valid input parses identically to before; a malicious or oversized document is now defused rather than accepted. **Added:** *b.safeJson.parseStringOrObject(input, opts?)* — Accepts either a JSON string — parsed through b.safeJson.parse, so the prototype-pollution-key strip and depth / key / size caps apply — or an already-decoded plain object (returned unchanged). For the recurring "operator hands me a document as a JSON string or a pre-built object" surface (b.openapi / b.asyncapi). The consumer's typed error class, error codes, label, and size cap are passed as options, so a raw JSON.parse on operator input cannot be hand-rolled per consumer. **Security:** *Operator and untrusted JSON parses strip __proto__ and bound size (no raw JSON.parse)* — A raw JSON.parse keeps a "__proto__" object member as an own key (a prototype-pollution gadget for any downstream merge) and parses unbounded input. b.openapi.parse and b.asyncapi.parse used it on operator document strings, and b.sandbox.run used it on the untrusted sandboxed code's JSON-serialized result. All now route through b.safeJson — the prototype-pollution keys are stripped and the depth / key / size caps apply (a 16 MiB document cap for openapi/asyncapi, the existing result-bytes cap for the sandbox). Internal JSON parses (the sealed DSR store payloads, the VEX canonical re-format) route through the same primitive too, so the guarantee cannot be bypassed one call site at a time. Valid input is unaffected; a "__proto__"-laden or oversized payload is defused.
 
 - v0.15.28 (2026-06-25) — **`b.network.dns` and `b.network.tls` errors now carry a usable terminal-vs-transient signal on `err.permanent`, so a caller's retry loop re-attempts only the failures a retry can fix.** DnsError was declared always-transient and NetworkTlsError always-permanent, so a consumer driving its own retry loop got the wrong signal in both directions: it would retry a permanent DNS failure (a bad host, bad options, an unsupported query, an NXDOMAIN-style no-result, or a caller-shape/config error such as an unconfigured transport or an invalid resolver list) forever, and it would refuse to retry a transient TLS-over-network failure (an ECH connection failure, a handshake timeout, DNS momentarily unavailable). err.permanent now reflects each error's actual transience, derived from its code and failing closed (an unknown code is permanent, so a hopeless target is not retried indefinitely): for DnsError only a failed network round-trip (a lookup timeout, a resolve/reverse query that failed on the wire, a failed DoH/DoT exchange, a DDR discovery that found nothing) is transient — config, input, and environment errors raised before any network work are permanent; for NetworkTlsError only the network-layer ECH failures are transient. TlsTrustError remains always-permanent by design — a trust-verification failure (bad CA, fingerprint mismatch, OCSP not-good, CT violation, an unreachable OCSP responder) must never be silently retried past the trust decision. **Fixed:** *DnsError / NetworkTlsError expose a correct terminal/transient signal; TlsTrustError stays terminal* — b.network.dns's DnsError was always-transient and b.network.tls's NetworkTlsError always-permanent, so err.permanent misled a consumer's retry loop in both directions — retrying a permanent DNS error (bad host / options / unsupported type / no-result) indefinitely, and never retrying a transient TLS network error (ECH connect failure, handshake timeout, DNS unavailable). err.permanent now reflects each error's actual transience by code and fails closed (unknown codes are permanent): DnsError is transient only for a failed network round-trip (dns/lookup-timeout, dns/resolve-failed, dns/reverse-failed, dns/doh-failed, dns/dot-failed, dns/dot-handshake-failed, dns/ddr-not-discovered, dns/system-failed), and permanent otherwise — including the caller-shape / environment errors raised before any network work (dns/transport-unavailable for an unconfigured transport, dns/dnr-no-resolvers for an empty/invalid resolver list, dns/setservers-failed for an invalid address, dns/no-system-resolvers when none are configured). NetworkTlsError is transient only for the network-layer ECH failures (tls/ech-connect-failed, tls/ech-timeout, tls/ech-dns-unavailable), permanent otherwise. TlsTrustError remains always-permanent so a trust-verification failure is never silently retried.

package/lib/compliance.js

@@ -443,7 +443,7 @@ function set(posture) {
   // guaranteed). Pure signal — no behavior change.
   var REGULATED = ["hipaa", "pci-dss", "sox", "gdpr", "soc2", "fda-21cfr11"];
   if (REGULATED.indexOf(posture) !== -1) {
-    var tz = process.env.TZ;                                                                  // allow:raw-process-env — bootstrap signal, no operator-supplied default needed
+    var tz = process.env.TZ;                                                                  // allow:raw-process-env-bootstrap — bootstrap signal, no operator-supplied default needed
     if (typeof tz === "string" && tz !== "UTC" && tz !== "Etc/UTC") {
       _emitAudit("compliance.posture.tz_warning",
         { posture: posture, tz: tz, recommendation: "Set TZ=UTC under regulated postures so audit timestamps align with regulator expectations." },

package/lib/db-file-lifecycle.js

@@ -288,7 +288,7 @@ function fileLifecycle(opts) {
         "fileLifecycle.startFlushTimer: timer already running — call stop() first");
     }
     var interval = sopts.intervalMs || flushIntervalMs;
-    encTimer = setInterval(function () {                                                          // allow:timer-no-unref — .unref() called immediately below; timer doesn't pin the event loop
+    encTimer = setInterval(function () {                                                          // allow:timer-no-unref-unrefed-below — .unref() called immediately below; timer doesn't pin the event loop
       try { flushNow(db); }
       catch (e) {
         _emitAudit("flush_failed", "failure", {

package/lib/guard-list-id.js

@@ -242,7 +242,7 @@ function validate(headerValue, opts) {
   // so a `localhost.` label-suffix is already refused at the segment-
   // shape level (an empty trailing segment fails the dot-atom-text
   // grammar). No trailing-dot bypass surface here.
-  var isLocalScopeTld = lastLabel === "localhost" || lastLabel === "local" || lastLabel === "lan"; // allow:hostname-compare-trailing-dot — see comment above; List-Id parts already split on `.` so trailing-dot label is empty and refused upstream
+  var isLocalScopeTld = lastLabel === "localhost" || lastLabel === "local" || lastLabel === "lan"; // allow:hostname-compare-trailing-dot-pre-split-refused — see comment above; List-Id parts already split on `.` so trailing-dot label is empty and refused upstream
   if (caps.requireFqdn) {
     if (parts.length < 3 && !isLocalScopeTld) {                                                          // FQDN requires ≥ 3 labels for non-local-scope namespace
       return _refuse("list-id has < 3 labels for non-local-scope namespace (FQDN required under '" +

package/lib/log.js

@@ -589,7 +589,7 @@ function _escapeC0Controls(s) {
 // runs before safeEnv on the boot path; safeEnv requires log, so log
 // can't go through safeEnv to read its own level.
 function _bootMinLevel() {
-  // allow:raw-process-env — see header comment above
+  // allow:raw-process-env-bootstrap — see header comment above
   var raw = process.env.BLAMEJS_BOOT_LOG_LEVEL || process.env.LOG_LEVEL || "info";
   return Object.prototype.hasOwnProperty.call(LEVELS, raw) ? LEVELS[raw] : LEVELS.info;
 }

package/lib/mail-crypto-pgp.js

@@ -563,7 +563,7 @@ function sign(opts) {
   // signed-part bytes plus the armored signature.
   // MIME-boundary uniqueness only (not a security token); operator
   // key/cert material flows through createSign/verify, not this path.
-  // allow:raw-randombytes-token — boundary string, not auth credential
+  // allow:raw-randombytes-token-mime-boundary — boundary string, not auth credential
   var boundary = "blamejs-pgp-" + nodeCrypto.randomBytes(12).toString("hex");
   // The OpenPGP signature covers the signed-part bytes exactly, so the
   // multipart/signed wrapper is assembled as a Buffer — a JS-string round

package/lib/middleware/span-http-server.js

@@ -72,7 +72,7 @@ function _scheme(req) {
   // client used (forwarded), NOT a Secure/HSTS/origin trust decision. Routing
   // through trustedProtocol would drop the forwarded scheme from spans behind a
   // proxy (less accurate telemetry) for no security gain.
-  // allow:raw-xfp — telemetry label, not a trust sink (see above).
+  // allow:raw-xfp-telemetry-only — telemetry label, not a trust sink (see above).
   var x = req.headers && (req.headers["x-forwarded-proto"] || "");
   if (typeof x === "string" && x.length > 0) {
     var first = x.split(",")[0].trim().toLowerCase();
@@ -82,7 +82,7 @@ function _scheme(req) {
 }
 
 function _serverAddress(req) {
-  // allow:raw-xfp — display-only: server.address span attribute (telemetry),
+  // allow:raw-xfp-telemetry-only — display-only: server.address span attribute (telemetry),
   // not an authority trust decision. Same rationale as _scheme above.
   var hostHeader = req.headers && (req.headers["x-forwarded-host"] || req.headers.host);
   if (typeof hostHeader === "string" && hostHeader.length > 0) {

package/lib/static.js

@@ -1409,7 +1409,7 @@ function create(opts) {
     // pre-allocate a closure for every served byte. Tracked for extraction.
     var idleTimer = null;
     function resetIdleTimer() {
-      if (idleTimer) clearTimeout(idleTimer); // allow:handrolled-debounce — file-stream idle deadline
+      if (idleTimer) clearTimeout(idleTimer); // allow:handrolled-debounce-stream-idle — file-stream idle deadline
       idleTimer = setTimeout(function () {
         try { fileStream.destroy(_err("IDLE_TIMEOUT", "client idle for " + maxIdleMs + "ms")); }
         catch (_) { /* stream already torn down */ }
@@ -1420,7 +1420,7 @@ function create(opts) {
 
     // Cancellation propagation: when the client disconnects mid-stream.
     function onClientClose() {
-      try { fileStream.destroy(); } catch (_) { /* allow:silent-catch — stream already torn down */ }
+      try { fileStream.destroy(); } catch (_) { /* allow:silent-catch-stream-teardown — stream already torn down */ }
       releaseSlot();
       if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
     }
@@ -1442,7 +1442,7 @@ function create(opts) {
           error: e && e.message,
         }, actorCtx));
       }
-      try { res.destroy(e); } catch (_) { /* allow:silent-catch — response already torn down */ }
+      try { res.destroy(e); } catch (_) { /* allow:silent-catch-stream-teardown — response already torn down */ }
       releaseSlot();
       if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
     });

package/lib/vendor-data.js

@@ -113,7 +113,7 @@ function _timingSafeHexEqual(a, b) {
   // length now guarantees equal byte length.
   var ba = Buffer.from(a, "utf8");
   var bb = Buffer.from(b, "utf8");
-  return nodeCrypto.timingSafeEqual(ba, bb);                                    // allow:raw-timing-safe-equal — hex + length pre-check above guarantees same-length ASCII inputs; b.crypto wrapper would be circular at boot
+  return nodeCrypto.timingSafeEqual(ba, bb);                                    // allow:raw-timing-safe-equal-boot-prechecked — hex + length pre-check above guarantees same-length ASCII inputs; b.crypto wrapper would be circular at boot
 }
 
 // KNOWN_VENDOR_DATA — the canonical list of vendored data names. Each

package/lib/watcher.js

@@ -528,7 +528,7 @@ function create(opts) {
       throw new WatcherError("watcher/start-failed",
         "watcher.create: initial poll walk failed: " + ((e && e.message) || String(e)));
     }
-    pollTimer = setInterval(_pollTick, pollIntervalMs);                                            // allow:timer-no-unref — .unref() called immediately below; timer doesn't pin the event loop
+    pollTimer = setInterval(_pollTick, pollIntervalMs);                                            // allow:timer-no-unref-unrefed-below — .unref() called immediately below; timer doesn't pin the event loop
     if (typeof pollTimer.unref === "function") pollTimer.unref();
   } else {
     try {

package/lib/webhook-dispatcher.js

@@ -26,7 +26,6 @@ var safeSql = require("./safe-sql");
 var safeUrl = require("./safe-url");
 var safeJson = require("./safe-json");
 var bCrypto = require("./crypto");
-var httpClient = require("./http-client");
 var frameworkSchema = require("./framework-schema");
 var validateOpts = require("./validate-opts");
 var lazyRequire = require("./lazy-require");
@@ -44,6 +43,11 @@ var vault = lazyRequire(function () { return require("./vault"); });
 var ssrfGuard = lazyRequire(function () { return require("./ssrf-guard"); });
 var audit = lazyRequire(function () { return require("./audit"); });
 var observability = lazyRequire(function () { return require("./observability"); });
+// Lazy — http-client pulls in node:http / node:https / node:http2; only the
+// default delivery transport touches it. Keeping it lazy keeps b.webhook (which
+// re-exports this module) free of the Node networking chain on its inbound
+// verify path, so b.webhook.verify stays loadable in a Worker / edge runtime.
+var httpClient = lazyRequire(function () { return require("./http-client"); });
 
 var _err = WebhookDispatcherError.factory;
 
@@ -223,7 +227,7 @@ function dispatcher(opts) {
   // Default transport: a real signed POST through the framework http client.
   // Injectable so a test (or a non-HTTP transport) substitutes its own.
   var httpRequest = opts.httpRequest || function (url, body, headers) {
-    return httpClient.request({
+    return httpClient().request({
       method:           "POST",
       url:              url,
       headers:          headers,

package/lib/webhook.js

@@ -50,7 +50,6 @@
 var nodeCrypto = require("node:crypto");
 var numericBounds = require("./numeric-bounds");
 var bCrypto = require("./crypto");
-var httpClient = require("./http-client");
 var safeBuffer = require("./safe-buffer");
 var safeUrl = require("./safe-url");
 var retryHelper = require("./retry");
@@ -60,12 +59,20 @@ var numericChecks = require("./numeric-checks");
 var requestHelpers = require("./request-helpers");
 // Lazy — ssrf-guard pulls in the DNS/network stack; only touched on send().
 var ssrfGuard = lazyRequire(function () { return require("./ssrf-guard"); });
+// Lazy — http-client pulls in node:http / node:https / node:http2; only the
+// outbound send() path touches it. Keeping it lazy lets b.webhook.verify (HMAC
+// + timing-safe compare only) load in a Worker / edge runtime with no Node
+// networking module available.
+var httpClient = lazyRequire(function () { return require("./http-client"); });
 var validateOpts = require("./validate-opts");
 var { WebhookError } = require("./framework-error");
 // b.webhook.dispatcher — durable signed-webhook delivery store. Lives in its
-// own module (distinct domain: persistence) and lazyRequires this file back,
-// so this top-level require is cycle-safe.
-var webhookDispatcher = require("./webhook-dispatcher");
+// own module (distinct domain: persistence) and pulls the SQL stack (and so
+// node:fs). Lazy — only resolved when b.webhook.dispatcher is accessed — so
+// importing the webhook module for the inbound verify path stays free of the
+// persistence/networking stack and loads in a Worker / edge runtime. The
+// module lazyRequires this file back, so the cycle stays deferred on both ends.
+var webhookDispatcher = lazyRequire(function () { return require("./webhook-dispatcher"); });
 
 var observability = lazyRequire(function () { return require("./observability"); });
 
@@ -472,7 +479,7 @@ function signer(opts) {
     } catch (_e) { hostLabel = ""; }
     try {
       var res = await retryHelper.withRetry(function () {
-        return httpClient.request(requestOpts);
+        return httpClient().request(requestOpts);
       }, retryOpts);
       var statusCode = (res && (res.statusCode || res.status)) || 0;
       _emitEvent("webhook.send", 1, {
@@ -1011,7 +1018,14 @@ module.exports = {
   // v0.11.25 — Stripe-shaped inbound HMAC-SHA-256 verifier + signer.
   verify:         verify,
   sign:           sign,
-  // Durable signed-webhook delivery store (sign + persist + deliver + retry +
-  // dead-letter + operator replay). Defined in lib/webhook-dispatcher.js.
-  dispatcher:     webhookDispatcher.dispatcher,
 };
+
+// Durable signed-webhook delivery store (sign + persist + deliver + retry +
+// dead-letter + operator replay). Defined in lib/webhook-dispatcher.js, which
+// pulls the SQL/persistence stack — exposed as a lazy getter so requiring the
+// webhook module for the inbound verify path doesn't load it (edge-safe).
+Object.defineProperty(module.exports, "dispatcher", {
+  enumerable:   true,
+  configurable: true,
+  get: function () { return webhookDispatcher().dispatcher; },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.15.29",
+  "version": "0.15.31",
   "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:9d6b0acf-4b88-47bc-b14b-ba2342410a0e",
+  "serialNumber": "urn:uuid:4097a213-458e-41ee-81c8-2db35819839f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-26T09:20:08.812Z",
+    "timestamp": "2026-06-26T19:40:07.451Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.15.29",
+      "bom-ref": "@blamejs/core@0.15.31",
       "type": "application",
       "name": "blamejs",
-      "version": "0.15.29",
+      "version": "0.15.31",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.15.29",
+      "purl": "pkg:npm/%40blamejs/core@0.15.31",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.15.29",
+      "ref": "@blamejs/core@0.15.31",
       "dependsOn": []
     }
   ]