@blamejs/core 0.7.100 → 0.7.101

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **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.
 
 - **0.7.99** (2026-05-06) — `b.db.integrityCheck()` + `b.db.integrityMonitor({ intervalMs, ... })` — periodic SQLite corruption detection. **`b.db.integrityCheck()`** runs `PRAGMA integrity_check` against the live database and returns `"ok"` on a healthy database, or an array of corruption description strings on damage. Operators wire this into `/healthz` handlers or one-off CLI checks. **`b.db.integrityMonitor({ intervalMs, onCorruption })`** runs the check on a schedule (24h default), emits `system.db.integrity_ok` / `system.db.integrity_corrupt` audit events, and fires the `db.integrity_check_ok` / `db.integrity_check_corrupt` observability counters. Optional `onCorruption(issues)` operator hook fires on every corrupt-result so operators can wire pager alerts. The previous boot-time-only integrity check (added in v0.7.79) continues to run unchanged at db.init; the monitor is for long-running deployments where filesystem-level corruption can develop after boot. Returns a handle with `.stop()` for graceful shutdown.

package/lib/observability.js

@@ -312,11 +312,87 @@ var SEMCONV = Object.freeze({
   K8S_DEPLOYMENT_NAME:            "k8s.deployment.name",
 });
 
+// W3C Trace Context — parse / build the `traceparent` HTTP header
+// per https://www.w3.org/TR/trace-context-1/. Operators wiring
+// distributed tracing across services use these to propagate the
+// trace ID across an outbound HTTP call without a vendored OTel SDK.
+//
+// Format: `<version>-<trace-id>-<parent-id>-<trace-flags>`
+//   version:     2 hex chars; "00" for v1
+//   trace-id:    32 hex chars (128 bits); MUST be all-zero-rejected
+//   parent-id:   16 hex chars (64 bits); MUST be all-zero-rejected
+//   trace-flags: 2 hex chars; bit 0 = sampled
+var _TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+var _ALL_ZERO_TRACE = "00000000000000000000000000000000";
+var _ALL_ZERO_PARENT = "0000000000000000";
+
+var _HEX_RADIX = 16;                                                               // allow:raw-byte-literal — Number.parseInt radix
+var _TRACE_FLAG_SAMPLED = 0x01;                                                    // W3C Trace Context §3.2.2.5 sampled bit
+var _TRACE_ID_BYTES = 16;                                                          // allow:raw-byte-literal — W3C Trace Context §3.2.2.3 (16 bytes)
+var _PARENT_ID_BYTES = 8;                                                          // allow:raw-byte-literal — W3C Trace Context §3.2.2.4 (8 bytes)
+var _FLAGS_HEX_LEN = 2;                                                            // allow:raw-byte-literal — W3C Trace Context flags are 1 byte = 2 hex chars
+
+function _parseTraceparent(headerValue) {
+  if (typeof headerValue !== "string" || headerValue.length === 0) return null;
+  var s = headerValue.trim().toLowerCase();
+  var m = s.match(_TRACEPARENT_RE);
+  if (!m) return null;
+  if (m[2] === _ALL_ZERO_TRACE) return null;     // §3.2.2.3 — trace-id MUST NOT be zero
+  if (m[3] === _ALL_ZERO_PARENT) return null;    // §3.2.2.4 — parent-id MUST NOT be zero
+  var flagsByte = parseInt(m[4], _HEX_RADIX);
+  return {
+    version:  m[1],
+    traceId:  m[2],
+    parentId: m[3],
+    flags:    m[4],
+    sampled:  (flagsByte & _TRACE_FLAG_SAMPLED) === _TRACE_FLAG_SAMPLED,
+  };
+}
+
+function _buildTraceparent(opts) {
+  if (!opts || typeof opts !== "object" || Array.isArray(opts)) {
+    throw new TypeError("traceContext.build: opts must be a plain object");
+  }
+  var traceId = opts.traceId;
+  var parentId = opts.parentId;
+  if (typeof traceId !== "string" || !/^[0-9a-f]{32}$/.test(traceId) || traceId === _ALL_ZERO_TRACE) {
+    throw new TypeError("traceContext.build: traceId must be 32 lowercase hex chars (non-zero)");
+  }
+  if (typeof parentId !== "string" || !/^[0-9a-f]{16}$/.test(parentId) || parentId === _ALL_ZERO_PARENT) {
+    throw new TypeError("traceContext.build: parentId must be 16 lowercase hex chars (non-zero)");
+  }
+  var flagsByte = (opts.sampled ? _TRACE_FLAG_SAMPLED : 0);
+  var flags = flagsByte.toString(_HEX_RADIX).padStart(_FLAGS_HEX_LEN, "0");
+  return "00-" + traceId + "-" + parentId + "-" + flags;
+}
+
+var _nodeCryptoForTrace = require("crypto");
+
+function _newTraceId() {
+  var hex = _nodeCryptoForTrace.randomBytes(_TRACE_ID_BYTES).toString("hex");
+  // Zero-trace-id is forbidden per spec; in the astronomically unlikely
+  // case rand returned all-zero, retry once.
+  return hex === _ALL_ZERO_TRACE ? _nodeCryptoForTrace.randomBytes(_TRACE_ID_BYTES).toString("hex") : hex;
+}
+
+function _newParentId() {
+  var hex = _nodeCryptoForTrace.randomBytes(_PARENT_ID_BYTES).toString("hex");
+  return hex === _ALL_ZERO_PARENT ? _nodeCryptoForTrace.randomBytes(_PARENT_ID_BYTES).toString("hex") : hex;
+}
+
+var traceContext = {
+  parse:        _parseTraceparent,
+  build:        _buildTraceparent,
+  newTraceId:   _newTraceId,
+  newParentId:  _newParentId,
+};
+
 module.exports = {
-  tap:        tap,
-  event:      event,
-  safeEvent:  safeEvent,
-  timed:      timed,
-  setTap:     setTap,
-  SEMCONV:    SEMCONV,
+  tap:           tap,
+  event:         event,
+  safeEvent:     safeEvent,
+  timed:         timed,
+  setTap:        setTap,
+  SEMCONV:       SEMCONV,
+  traceContext:  traceContext,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.100",
+  "version": "0.7.101",
   "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:41d841af-2890-4424-89ab-7b411b784c39",
+  "serialNumber": "urn:uuid:a1fc9374-766f-4ee8-8a57-d02b5e754ce5",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T09:26:08.410Z",
+    "timestamp": "2026-05-06T09:42:14.464Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.100",
+      "bom-ref": "@blamejs/core@0.7.101",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.100",
+      "version": "0.7.101",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.100",
+      "purl": "pkg:npm/%40blamejs/core@0.7.101",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.100",
+      "ref": "@blamejs/core@0.7.101",
       "dependsOn": []
     }
   ]