@blamejs/core 0.7.101 → 0.7.102

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.102** (2026-05-06) — `b.middleware.tracePropagate({ generateIfMissing, ... })` — middleware that consumes the inbound `traceparent` header per W3C Trace Context and stamps `req.trace = { traceId, parentId, sampled, hadUpstream }` for downstream handlers + propagation into outbound HTTP calls. `generateIfMissing: true` (default) synthesises a fresh trace when the inbound header is missing/malformed and stamps `hadUpstream: false`. `auditOnMissing: true` emits `system.trace.synthesised` audit events on every locally-originated trace. `setResponseHeader: true` echoes the resolved traceparent on the response (useful when the framework is the back-end of an L7 router that wants to log it). Composes with `b.observability.traceContext` (v0.7.101) for outbound propagation: downstream handlers read `req.trace.traceId` and pass it to `traceContext.build({ traceId: req.trace.traceId, parentId: traceContext.newParentId(), sampled: req.trace.sampled })` for the `traceparent` header on upstream calls.
+
 - **0.7.101** (2026-05-06) — `b.observability.traceContext` — W3C Trace Context (https://www.w3.org/TR/trace-context-1/) parser + builder. **`traceContext.parse(headerValue)`** consumes a `traceparent` HTTP header value (`00-<32hex traceId>-<16hex parentId>-<2hex flags>`) and returns `{ version, traceId, parentId, flags, sampled }` or null on malformed input. Enforces the §3.2.2.3 / §3.2.2.4 all-zero-rejection rule (zero trace-id and zero parent-id are explicitly forbidden by spec). **`traceContext.build({ traceId, parentId, sampled })`** produces a v1 `traceparent` header value; throws on bad input shape. **`traceContext.newTraceId()` / `newParentId()`** generate fresh randomized 128-bit / 64-bit hex strings (with the all-zero retry path the spec requires). Operators wiring distributed tracing across services use these to propagate trace IDs across an outbound HTTP call without a vendored OTel SDK — pair with the SEMCONV constants from v0.7.95 to build OTel-aligned spans on top.
 
 - **0.7.100** (2026-05-06) — `b.network.tls.expiryMonitor({ intervalMs, windowMs, onExpiring })` — periodic CA-trust-store expiry monitor. Runs `expiringSoon(windowMs)` on a schedule; emits `network.tls.ca.expiry_check` audit event on every check (with `expiring` count + `total` CA count), `network.tls.ca.expiring` audit event when any CA falls inside the window, and the matching `network.tls.ca.expiring` observability counter. Optional `onExpiring(rows)` operator hook fires on every check that surfaces expiring CAs so operators can wire pager / Slack alerts. Audit metadata captures the expiring CA labels + the earliest `validTo` timestamp so dashboards can compute "days until first expiry" without re-querying. Returns a handle with `.stop()` for graceful shutdown. Closes the v0.7.26 OCSP/CT batch's continuous-trust-monitoring follow-up.

package/lib/middleware/index.js

@@ -46,6 +46,7 @@ var requireMethods = require("./require-methods");
 var securityHeaders = require("./security-headers");
 var securityTxt = require("./security-txt");
 var sse = require("./sse");
+var tracePropagate = require("./trace-propagate");
 var tusUpload = require("./tus-upload");
 var webAppManifest = require("./web-app-manifest");
 
@@ -80,6 +81,7 @@ module.exports = {
   dpop:             dpop.create,
   hostAllowlist:    hostAllowlist.create,
   networkAllowlist: networkAllowlist.create,
+  tracePropagate:   tracePropagate.create,
   tusUpload:        tusUpload.create,
   webAppManifest:   webAppManifest.create,
 
@@ -112,6 +114,7 @@ module.exports = {
     dpop:             dpop,
     hostAllowlist:    hostAllowlist,
     networkAllowlist: networkAllowlist,
+    tracePropagate:   tracePropagate,
     tusUpload:        tusUpload,
     webAppManifest:   webAppManifest,
   },

package/lib/middleware/trace-propagate.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * trace-propagate middleware — consumes the inbound `traceparent`
+ * header per W3C Trace Context (https://www.w3.org/TR/trace-context-1/)
+ * and stamps `req.trace = { traceId, parentId, sampled, hadUpstream }`
+ * for downstream handlers + propagation into outbound HTTP calls.
+ *
+ *   router.use(b.middleware.tracePropagate({
+ *     generateIfMissing: true,   // default — synthesise when absent
+ *     auditOnMissing:    true,   // emit `system.trace.synthesised` event
+ *     setResponseHeader: true,   // echo the resolved traceparent on res
+ *   }));
+ *
+ *   app.get("/widgets", function (req, res) {
+ *     // req.trace.traceId is the canonical id for this request
+ *     b.observability.event("widgets.request", 1, {
+ *       [b.observability.SEMCONV.HTTP_REQUEST_METHOD]: req.method,
+ *     });
+ *     // Propagate to an upstream call:
+ *     fetch(upstreamUrl, {
+ *       headers: {
+ *         traceparent: b.observability.traceContext.build({
+ *           traceId:  req.trace.traceId,
+ *           parentId: b.observability.traceContext.newParentId(),
+ *           sampled:  req.trace.sampled,
+ *         }),
+ *       },
+ *     });
+ *   });
+ *
+ * On bad / missing inbound traceparent:
+ *   - generateIfMissing: true (default) → synthesise a fresh trace,
+ *     stamp `hadUpstream: false` so downstream code knows this trace
+ *     was originated locally
+ *   - generateIfMissing: false → leave `req.trace = null`; downstream
+ *     code that depends on a trace MUST handle the null case
+ */
+
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+var { defineClass } = require("../framework-error");
+
+var TracePropagateError = defineClass("TracePropagateError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("../observability"); });
+var audit = lazyRequire(function () { return require("../audit"); });
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "generateIfMissing", "auditOnMissing",
+    "setResponseHeader", "audit",
+  ], "middleware.tracePropagate");
+
+  var generateIfMissing = opts.generateIfMissing !== false;     // default true
+  var auditOnMissing    = opts.auditOnMissing === true;         // default false (every request that doesn't carry a trace is noisy)
+  var setResponseHeader = opts.setResponseHeader === true;      // default false
+  var auditOn           = opts.audit !== false;
+
+  return function tracePropagateMiddleware(req, res, next) {
+    var tc = observability().traceContext;
+    var inbound = req.headers && req.headers.traceparent;
+    var parsed = (typeof inbound === "string") ? tc.parse(inbound) : null;
+    if (parsed) {
+      req.trace = {
+        traceId:     parsed.traceId,
+        parentId:    parsed.parentId,
+        sampled:     parsed.sampled,
+        hadUpstream: true,
+      };
+    } else if (generateIfMissing) {
+      req.trace = {
+        traceId:     tc.newTraceId(),
+        parentId:    tc.newParentId(),
+        sampled:     true,
+        hadUpstream: false,
+      };
+      if (auditOnMissing && auditOn) {
+        try {
+          audit().safeEmit({
+            action:   "system.trace.synthesised",
+            outcome:  "ok",
+            metadata: { route: req.url || "/", traceId: req.trace.traceId },
+          });
+        } catch (_e) { /* drop-silent — observability sink */ }
+      }
+    } else {
+      req.trace = null;
+    }
+
+    if (setResponseHeader && req.trace && !res.headersSent) {
+      try {
+        res.setHeader("traceparent", tc.build({
+          traceId:  req.trace.traceId,
+          parentId: req.trace.parentId,
+          sampled:  req.trace.sampled,
+        }));
+      } catch (_e) { /* drop-silent — header set best-effort */ }
+    }
+    return next();
+  };
+}
+
+module.exports = {
+  create:               create,
+  TracePropagateError:  TracePropagateError,
+};

package/package.json

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

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:a1fc9374-766f-4ee8-8a57-d02b5e754ce5",
+  "serialNumber": "urn:uuid:4b25a892-26de-481b-9c07-1e2612710dd0",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T09:42:14.464Z",
+    "timestamp": "2026-05-06T09:52:45.058Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.101",
+      "bom-ref": "@blamejs/core@0.7.102",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.101",
+      "version": "0.7.102",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.101",
+      "purl": "pkg:npm/%40blamejs/core@0.7.102",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.101",
+      "ref": "@blamejs/core@0.7.102",
       "dependsOn": []
     }
   ]