@blamejs/core 0.7.99 → 0.7.101

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - **0.7.98** (2026-05-06) — `b.ntpCheck.monitor({ intervalMs, ... })` — periodic clock-drift monitor that runs `checkDrift` on a schedule and emits audit + observability events on threshold crossings. Returns a handle with `.stop()` for graceful shutdown. Audit emissions: `system.ntp.checked` (every check), `system.ntp.drift_warn` (drift exceeds warn threshold), `system.ntp.drift_fatal` (drift exceeds fatal threshold), `system.ntp.unreachable` (every server in the list failed to respond). Observability event: `ntp.drift_ms` gauge on every successful check, labeled with the responding server. Optional `onDrift(result)` operator hook fires on every warning/fatal check so operators can wire pager / Slack notifications. The previous boot-time-only `b.ntpCheck.bootCheck` continues to run unchanged at db.init; the monitor is for long-running deployments where clock-drift can develop after boot (container with no RTC sync, ntpd stopped after boot, etc.). Closes the v0.7.79 audit-batch slice for continuous time integrity.

package/lib/network-tls.js

@@ -9,6 +9,7 @@ var C = require("./constants");
 var safeBuffer = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
 var lazyRequire = require("./lazy-require");
+var safeAsync = require("./safe-async");
 var { defineClass } = require("./framework-error");
 
 var TlsTrustError = defineClass("TlsTrustError", { alwaysPermanent: true });
@@ -248,6 +249,82 @@ function expiringSoon(windowMs) {
   });
 }
 
+// expiryMonitor — periodic check that emits audit + observability
+// events when any CA in the trust store falls inside the expiry
+// window. Returns a handle with .stop() for graceful shutdown.
+//
+//   var mon = b.network.tls.expiryMonitor({
+//     intervalMs:   C.TIME.hours(6),
+//     windowMs:     C.TIME.days(30),
+//     onExpiring:   function (rows) { /* operator hook — alerts */ },
+//   });
+//   ...
+//   mon.stop();
+//
+// Audit emissions:
+//   network.tls.ca.expiry_check  — every check, reports total + expiring count
+//   network.tls.ca.expiring      — when expiringSoon(windowMs) > 0
+//
+// Observability event: network.tls.ca.expiring counter labeled with
+// the count.
+function expiryMonitor(opts) {
+  opts = opts || {};
+  var intervalMs = opts.intervalMs;
+  var windowMs   = opts.windowMs;
+  var auditOn    = opts.audit !== false;
+  if (typeof intervalMs !== "number" || !isFinite(intervalMs) || intervalMs <= 0) {
+    throw new TlsTrustError("tls/bad-interval",
+      "tls.expiryMonitor: intervalMs must be a positive finite number");
+  }
+  if (typeof windowMs !== "number" || !isFinite(windowMs) || windowMs <= 0) {
+    throw new TlsTrustError("tls/bad-window",
+      "tls.expiryMonitor: windowMs must be a positive finite number");
+  }
+
+  function _tick() {
+    var rows;
+    try { rows = expiringSoon(windowMs); }
+    catch (_e) { return; }
+    if (auditOn) {
+      try {
+        audit().safeEmit({
+          action:  "network.tls.ca.expiry_check",
+          outcome: rows.length > 0 ? "warn" : "ok",
+          metadata: { total: STATE.cas.length, expiring: rows.length, windowMs: windowMs },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+    if (rows.length > 0) {
+      try { observability().safeEvent("network.tls.ca.expiring", rows.length, {}); }
+      catch (_e) { /* drop-silent */ }
+      if (auditOn) {
+        try {
+          audit().safeEmit({
+            action:  "network.tls.ca.expiring",
+            outcome: "warn",
+            metadata: {
+              count:   rows.length,
+              labels:  rows.map(function (r) { return r.label; }),
+              earliestValidTo: rows.reduce(function (acc, r) {
+                var ms = r.validTo ? Date.parse(r.validTo) : Infinity;
+                return ms < acc ? ms : acc;
+              }, Infinity),
+            },
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+      if (typeof opts.onExpiring === "function") {
+        try { opts.onExpiring(rows); } catch (_e) { /* operator hook */ }
+      }
+    }
+  }
+
+  var handle = safeAsync.repeating(_tick, intervalMs, { name: "tls-expiry-monitor" });
+  return {
+    stop: function () { if (handle) { handle.stop(); handle = null; } },
+  };
+}
+
 function captureBaselineFingerprints() {
   STATE.baselineFingerprints = STATE.cas.map(function (e) { return e.meta.fingerprint256; });
 }
@@ -1557,6 +1634,7 @@ module.exports = {
   clearAll:            clearAll,
   purgeExpired:        purgeExpired,
   expiringSoon:        expiringSoon,
+  expiryMonitor:       expiryMonitor,
   useSystemTrust:      useSystemTrust,
   isSystemTrustEnabled: isSystemTrustEnabled,
   getTrustStore:       getTrustStore,

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.99",
+  "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:a1c08980-f218-4272-8ccc-742e21f943c1",
+  "serialNumber": "urn:uuid:a1fc9374-766f-4ee8-8a57-d02b5e754ce5",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T09:14:16.202Z",
+    "timestamp": "2026-05-06T09:42:14.464Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.99",
+      "bom-ref": "@blamejs/core@0.7.101",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.99",
+      "version": "0.7.101",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.99",
+      "purl": "pkg:npm/%40blamejs/core@0.7.101",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.99",
+      "ref": "@blamejs/core@0.7.101",
       "dependsOn": []
     }
   ]