@blamejs/core 0.14.25 → 0.14.27

package/lib/observability.js

@@ -55,6 +55,14 @@ var safeBuffer = lazyRequire(function () { return require("./safe-buffer"); });
 var tracing = lazyRequire(function () { return require("./tracing"); });
 var metrics = lazyRequire(function () { return require("./metrics"); });
 
+// redact is the framework's central PII/secret scrubber. Lazy-loaded so
+// the require graph stays acyclic at boot (redact lazy-pulls audit, which
+// pulls observability back). Composed by the default telemetry redactor
+// below so span/metric attribute VALUES are scrubbed before the OTLP
+// exporter serializes them — CWE-532 (insertion of sensitive information
+// into a telemetry/log egress sink).
+var redact = lazyRequire(function () { return require("./redact"); });
+
 // Operator-installed tap handler — wired via setTap(). When non-null,
 // every observability event/tap dispatch routes here in addition to
 // the framework's metrics module. Used by b.otelExport.create() so an
@@ -62,6 +70,26 @@ var metrics = lazyRequire(function () { return require("./metrics"); });
 // emits internally.
 var _externalTap = null;
 
+// Telemetry-attribute redactor seam. Span / metric attribute VALUES are
+// a first-class egress surface: a span attribute holding a user email,
+// bearer token, or vault-sealed ciphertext is shipped verbatim to the
+// OTLP collector unless it is scrubbed at the assembly boundary, the same
+// way log-stream redacts every record before any sink sees it. Defaults
+// ON — the default redactor composes b.redact.redact, passing the
+// attribute key as the parent-key context so both field-name rules
+// (authorization / token / session / password) and value-shape detectors
+// (JWT / PEM / credit-card / SSN / connection-string) fire. CWE-532.
+//
+// The redactor is (value, key) → redactedValue. The exporter calls it for
+// every attribute value; a thrown redactor drops the attribute rather
+// than leaking it (the exporter enforces fail-toward-dropping), so a
+// misbehaving custom redactor can never widen the egress surface.
+function _defaultTelemetryRedactor(value, key) {
+  return redact().redact(value, { parentKey: typeof key === "string" ? key : null });
+}
+
+var _telemetryRedactor = _defaultTelemetryRedactor;
+
 function _safeMetricsTap(name, value, labels) {
   try { metrics().tap(name, value, labels); }
   catch (_e) { /* boot-order tolerance — metrics may not be loaded */ }
@@ -106,6 +134,63 @@ function setTap(handler) {
   _externalTap = handler;
 }
 
+/**
+ * @primitive b.observability.setRedactor
+ * @signature b.observability.setRedactor(redactor)
+ * @since     0.14.27
+ * @related   b.observability.getRedactor, b.redact.redact
+ *
+ * Override the redactor applied to every span / metric attribute VALUE
+ * before the OTLP exporter serializes it onto the wire. Telemetry is a
+ * first-class egress sink: an attribute holding a user email, bearer
+ * token, or secret would otherwise reach the collector in plaintext
+ * (CWE-532). Redaction is ON by default — the default redactor composes
+ * `b.redact.redact` and fires both field-name and value-shape rules; this
+ * setter only lets an operator swap in a stricter or domain-specific
+ * scrubber.
+ *
+ * The redactor is `redactor(value, key)` and returns the value to export.
+ * It runs on the export hot path, so a throw is caught and the attribute
+ * is dropped (never exported raw) — a redactor that throws can only
+ * shrink the egress surface, never widen it. Pass `null` to restore the
+ * default `b.redact.redact`-backed redactor.
+ *
+ * @example
+ *   b.observability.setRedactor(function (value, key) {
+ *     if (key === "enduser.id") return "[REDACTED]";
+ *     return b.redact.redact(value, { parentKey: key });
+ *   });
+ *   b.observability.setRedactor(null);   // restore the default
+ */
+function setRedactor(redactor) {
+  if (redactor !== null && typeof redactor !== "function") {
+    throw new TypeError("observability.setRedactor: redactor must be a function or null, got " +
+      typeof redactor);
+  }
+  _telemetryRedactor = redactor === null ? _defaultTelemetryRedactor : redactor;
+}
+
+/**
+ * @primitive b.observability.getRedactor
+ * @signature b.observability.getRedactor()
+ * @since     0.14.27
+ * @related   b.observability.setRedactor, b.redact.redact
+ *
+ * Return the redactor currently applied to span / metric attribute
+ * values on the OTLP egress path. The OTLP exporter calls this to scrub
+ * every attribute value before serialization; operators rarely need it
+ * directly. When no override has been installed it returns the default
+ * `b.redact.redact`-backed redactor.
+ *
+ * @example
+ *   var redactor = b.observability.getRedactor();
+ *   redactor("Bearer eyJabc.eyJdef.sig", "authorization");
+ *   // → "[REDACTED]"   (field-name rule on the "authorization" key)
+ */
+function getRedactor() {
+  return _telemetryRedactor;
+}
+
 /**
  * @primitive b.observability.tap
  * @signature b.observability.tap(name, attrs, fn)
@@ -750,6 +835,8 @@ module.exports = {
   safeEvent:     safeEvent,
   timed:         timed,
   setTap:        setTap,
+  setRedactor:   setRedactor,
+  getRedactor:   getRedactor,
   SEMCONV:       SEMCONV,
   traceContext:  traceContext,
   baggage:       baggage,

package/lib/otel-export.js

@@ -42,6 +42,7 @@
 var C = require("./constants");
 var canonicalJson = require("./canonical-json");
 var httpClient = require("./http-client");
+var observability = require("./observability");
 var safeAsync = require("./safe-async");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
@@ -64,6 +65,28 @@ var MAX_RESPONSE_BYTES = C.BYTES.mib(1);
 // receiving backend handles the running sum.
 var TEMPORALITY_DELTA = 1;
 
+// Run a single attribute value through the active telemetry redactor.
+// Telemetry is a first-class EGRESS sink — an attribute value holding a
+// user email, bearer token, or vault-sealed ciphertext would otherwise
+// be serialized verbatim onto the OTLP wire (CWE-532: insertion of
+// sensitive information into an externally-shipped sink). The redactor is
+// resolved per-call from b.observability so an operator-installed
+// override (setRedactor) takes effect without re-creating the exporter.
+//
+// Drop-silent by design: this runs on the export hot path, where a throw
+// from the redactor must never crash the request that produced the span.
+// On a throw we DROP the attribute (signalled by the `_DROP` sentinel)
+// rather than fall through to the raw value — failing toward dropping,
+// not leaking.
+var _DROP = {};
+function _redactAttrValue(key, value) {
+  try {
+    return observability.getRedactor()(value, key);
+  } catch (_e) {
+    return _DROP;   // redactor threw — drop the attribute, never export raw
+  }
+}
+
 // ---- attribute encoding ----
 // OTLP attributes are KeyValue with typed `value` fields:
 //   { key, value: { stringValue | intValue | doubleValue | boolValue } }
@@ -72,7 +95,8 @@ function _attrsToOtlp(attrs) {
   var out = [];
   for (var k in attrs) {
     if (!Object.prototype.hasOwnProperty.call(attrs, k)) continue;
-    var v = attrs[k];
+    var v = _redactAttrValue(k, attrs[k]);
+    if (v === _DROP) continue;                // redactor threw — drop, don't leak
     var kv;
     if (typeof v === "string")  kv = { stringValue: v };
     else if (typeof v === "number") {

package/lib/parsers/safe-xml.js

@@ -13,10 +13,18 @@
  *   - Processing instructions referencing external resources
  *   - Unbounded recursion / element count / attribute count
  *   - CDATA sections of arbitrary length
+ *   - Prototype pollution: an element or attribute named __proto__,
+ *     constructor, or prototype landing as a key in the result tree
+ *     (CWE-1321 / OWASP prototype-pollution)
  *
  * This parser closes all of them by default. DOCTYPE, external entities,
  * and processing instructions other than '<?xml ?>' are REJECTED — apps
- * that need them are using the wrong parser.
+ * that need them are using the wrong parser. Element and attribute names
+ * equal to __proto__ / constructor / prototype are REJECTED with
+ * xml/forbidden-name so they can never collide with an inherited member
+ * or reassign an accumulator's prototype; the result tree and every
+ * nested object it contains have a null prototype, so a consumer reading
+ * an absent key sees undefined rather than an inherited Object member.
  *
  * Output: a plain JS object. Element with attributes + children:
  *   <root id="x"><child>text</child></root>
@@ -75,6 +83,18 @@ var ABSOLUTE_MAX_ATTRIBUTES = 1_000;
 // XML built-in entities (the ONLY entities allowed)
 var BUILT_IN_ENTITIES = { lt: "<", gt: ">", amp: "&", quot: "\"", apos: "'" };
 
+// Names that must never become a key in the result tree. A plain object
+// inherits these from Object.prototype; an element/attribute named after
+// one of them would otherwise collide with the inherited member (a
+// consumer sees a function/object instead of undefined) or — for a
+// computed-member write of an object value — reassign the accumulator's
+// prototype (CWE-1321 / OWASP prototype-pollution). The accumulators are
+// built with a null prototype, and these names are rejected outright so
+// the result is always a clean key→value map. Mirrors the
+// __proto__/constructor/prototype rejection the toml / yaml / ini
+// parsers in this family already apply.
+var FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
 function _validateAndCap(name, value, defaultValue, ceiling) {
   if (value === undefined) return defaultValue;
   if (!numericBounds.isPositiveFiniteInt(value)) {
@@ -178,7 +198,12 @@ function parse(input, opts) {
       } else break;
     }
     if (pos === start) throw _err("expected name", "xml/bad-name");
-    return input.substring(start, pos);
+    var parsed = input.substring(start, pos);
+    if (FORBIDDEN_KEYS.has(parsed)) {
+      throw _err("element/attribute name '" + parsed +
+        "' is reserved (prototype-pollution defense)", "xml/forbidden-name");
+    }
+    return parsed;
   }
 
   // Parse an attribute value (single- or double-quoted)
@@ -267,7 +292,12 @@ function parse(input, opts) {
 
     expectChar("<");
     var name = parseName();
-    var attrs = {};
+    // Null-prototype accumulator keyed by attacker-influenced attribute
+    // names — no inherited Object member can shadow a missing key, and the
+    // duplicate-attribute check below can't be fooled by an inherited
+    // function (CWE-1321). Forbidden names are already rejected in
+    // parseName.
+    var attrs = Object.create(null);
     var attrCount = 0;
 
     while (pos < len) {
@@ -351,10 +381,15 @@ function parse(input, opts) {
       // Pure-text element → string
       return _make(name, textParts.join("").trim() === "" ? textParts.join("") : textParts.join(""));
     }
-    // Mixed / attributed element → object
-    var obj = {};
+    // Mixed / attributed element → object. Both accumulators carry a null
+    // prototype: `grouped` is keyed by attacker-influenced child element
+    // names and `obj` receives them via Object.assign, so neither may
+    // expose an inherited Object member or be prototype-poisoned by a
+    // computed-member write (CWE-1321). Forbidden child names were already
+    // rejected in parseName.
+    var obj = Object.create(null);
     if (hasAttrs) obj["@attrs"] = attrs;
-    var grouped = {};
+    var grouped = Object.create(null);
     for (var i = 0; i < elementChildren.length; i++) {
       var childWrap = elementChildren[i].value;
       var childName = Object.keys(childWrap)[0];
@@ -374,7 +409,12 @@ function parse(input, opts) {
   }
 
   function _make(name, value) {
-    var out = {};
+    // Null-prototype wrapper keyed by the element name (parser-controlled,
+    // attacker-influenced). `out[name] = value` with a forbidden name
+    // would otherwise reassign the wrapper's prototype when value is an
+    // object; the name is already rejected in parseName and the null
+    // prototype removes the inherited-member surface entirely (CWE-1321).
+    var out = Object.create(null);
     out[name] = value;
     return out;
   }

package/lib/queue-local.js

@@ -70,6 +70,22 @@ var DEFAULT_TABLE = "_blamejs_jobs";
 // (queue-local → vault → db → audit → cluster) tolerates the late bind.
 var vault = lazyRequire(function () { return require("./vault"); });
 
+// Self-register the _blamejs_jobs sealed-column declaration with
+// cryptoField so payload + lastError seal at rest even when db.init never
+// ran in this process. cryptoField.sealRow is a SILENT pass-through for an
+// unregistered table — a standalone redis/sqs queue node (no db.init) would
+// otherwise write job payloads (webhook bodies, credentials, PII) in
+// cleartext. db.init registers the same shape from its FRAMEWORK_SCHEMA;
+// registerTable is idempotent, and probing getSchema (rather than a module
+// boolean) keeps this reset-safe — db._resetForTest() clears the cryptoField
+// registry between tests, and a boolean cache would then leave seal a no-op.
+function _ensureSealTable() {
+  if (cryptoField.getSchema(SEAL_TABLE)) return;
+  cryptoField.registerTable(SEAL_TABLE, {
+    sealedFields: ["payload", "lastError"],
+  });
+}
+
 // Column order kept as a constant so the placeholders + values lists
 // stay in sync. Mirrors db.js's FRAMEWORK_SCHEMA for _blamejs_jobs.
 var JOB_COLS = [
@@ -583,4 +599,10 @@ function create(config) {
   };
 }
 
-module.exports = { create: create };
+module.exports = {
+  create:           create,
+  // Idempotent, reset-safe self-registration of the _blamejs_jobs sealed-
+  // column declaration. queue.init calls this so seal-at-rest engages on a
+  // standalone queue node that never ran db.init.
+  _ensureSealTable: _ensureSealTable,
+};

package/lib/queue.js

@@ -152,6 +152,13 @@ function init(opts) {
     throw _err("INVALID_CONFIG", "queue.init({ backends }) is required", true);
   }
 
+  // Self-register the _blamejs_jobs sealed-column declaration so payload +
+  // lastError seal at rest even when this process never ran db.init (a
+  // standalone redis/sqs queue node). cryptoField.sealRow silently passes
+  // through for an unregistered table, so without this a queue node would
+  // write job payloads to Redis/SQS in cleartext. Idempotent + reset-safe.
+  localProto._ensureSealTable();
+
   backends = {};
   // IIFE per-iteration so each backend's wrappers close over its own
   // raw / breaker / cfg. With `var` (function-scoped) those bindings

package/lib/redact.js

@@ -309,6 +309,7 @@ function _redact(value, depth, maxDepth, marker, parentKey) {
 function _resetForTest() {
   sensitiveFieldsSet = new Set(SENSITIVE_FIELDS);
   customDetectors = [];
+  outboundInstallCount = 0;
 }
 
 // ---- Classifier presets (for outbound DLP) ----
@@ -625,6 +626,14 @@ function classifyDefaults(opts) {
 
 var OUTBOUND_INSTALL_REGISTRY = new WeakMap();
 
+// Count of primitive instances currently wrapped by an outbound-DLP
+// interceptor. A WeakMap can't be enumerated, so this counter is the
+// cheap "is anything installed?" signal b.compliance.set reads to decide
+// whether to warn that a DLP-floor posture was pinned without wiring.
+// Incremented per primitive on install, decremented on uninstall; never
+// negative.
+var outboundInstallCount = 0;
+
 function _emitDlp(action, outcome, metadata) {
   try {
     audit().safeEmit({
@@ -740,15 +749,15 @@ function installOutboundDlp(opts) {
 
   if (opts.httpClient) {
     var u1 = _installHttpClient(opts.httpClient, classifier, opts);
-    if (u1) { uninstallers.push(u1); installed.httpClient = true; }
+    if (u1) { uninstallers.push(u1); installed.httpClient = true; outboundInstallCount += 1; }
   }
   if (opts.mail) {
     var u2 = _installMail(opts.mail, classifier, opts);
-    if (u2) { uninstallers.push(u2); installed.mail = true; }
+    if (u2) { uninstallers.push(u2); installed.mail = true; outboundInstallCount += 1; }
   }
   if (opts.webhook) {
     var u3 = _installWebhook(opts.webhook, classifier, opts);
-    if (u3) { uninstallers.push(u3); installed.webhook = true; }
+    if (u3) { uninstallers.push(u3); installed.webhook = true; outboundInstallCount += 1; }
   }
 
   _emitDlp("dlp.outbound.installed", "success", {
@@ -761,12 +770,37 @@ function installOutboundDlp(opts) {
     uninstall:  function () {
       while (uninstallers.length > 0) {
         var fn = uninstallers.pop();
-        try { fn(); } catch (_e) { /* best-effort */ }
+        try { fn(); if (outboundInstallCount > 0) outboundInstallCount -= 1; }
+        catch (_e) { /* best-effort */ }
       }
     },
   };
 }
 
+/**
+ * @primitive b.redact.isOutboundDlpInstalled
+ * @signature b.redact.isOutboundDlpInstalled()
+ * @since     0.14.27
+ * @compliance hipaa, pci-dss, gdpr, soc2, fapi2
+ * @related   b.redact.installForPosture, b.redact.installOutboundDlp
+ *
+ * Returns `true` when at least one primitive instance (httpClient /
+ * mail / webhook) currently carries an outbound-DLP interceptor.
+ * `b.compliance.set` reads this to decide whether to emit the one-time
+ * `compliance.posture.outbound_dlp_unwired` warning when a posture whose
+ * floor implies outbound DLP is pinned without any wiring. Read-only.
+ *
+ * @example
+ *   b.redact.isOutboundDlpInstalled();   // → false
+ *   var dlp = b.redact.installForPosture("hipaa", { httpClient: myHttp });
+ *   b.redact.isOutboundDlpInstalled();   // → true
+ *   dlp.uninstall();
+ *   b.redact.isOutboundDlpInstalled();   // → false
+ */
+function isOutboundDlpInstalled() {
+  return outboundInstallCount > 0;
+}
+
 function _resolvePosturePatterns(name) {
   var n = String(name).toLowerCase();
   if (n === "pci-dss" || n === "pci") {
@@ -779,6 +813,15 @@ function _resolvePosturePatterns(name) {
     return ["pan", "credit-card", "iban", "pem", "aws-access-key", "jwt", "api-key-shape"];
   }
   if (n === "soc2" || n === "gdpr") {
+    // Known fidelity collapse: soc2 and gdpr share one outbound-DLP
+    // pattern set here. They are distinct regimes — GDPR's special-
+    // category personal data (Art. 9) is broader than the SOC 2 Trust
+    // Services criteria this preset targets — but the built-in
+    // value-shape detectors don't yet distinguish them, so the same
+    // pattern list backs both. Operators needing GDPR-specific shapes
+    // pass an explicit classifier (classifyDefaults) rather than the
+    // posture preset. This is intentional, not an accidental alias —
+    // documented so it isn't mistaken for per-regime handling.
     return ["ssn", "ein", "pem", "ssh-private", "aws-access-key", "api-key-shape"];
   }
   throw new DlpError("redact-dlp/unknown-posture",
@@ -959,9 +1002,12 @@ function _summarizeHit(h) {
   return { label: h.label, action: h.action, where: h.where };
 }
 
-// Posture-coordinated install — a thin wrapper used by b.compliance.set
-// to wire DLP automatically when the posture is set. Operators using
-// b.compliance can rely on this; direct callers use installOutboundDlp.
+// Posture-coordinated install — the operator passes the primitive
+// instances to wire (httpClient / mail / webhook); the posture name
+// selects the default classifier. b.compliance.set does NOT call this:
+// it holds no httpClient / mail / webhook handles, so it cannot install
+// outbound interceptors. Operators wire DLP explicitly by calling this
+// (or installOutboundDlp) with their own primitive instances.
 /**
  * @primitive b.redact.installForPosture
  * @signature b.redact.installForPosture(posture, primitives)
@@ -970,10 +1016,20 @@ function _summarizeHit(h) {
  * @compliance hipaa, pci-dss, gdpr, soc2, fapi2
  * @related   b.redact.installOutboundDlp, b.redact.classifyDefaults
  *
- * Posture-coordinated install — a thin wrapper used by
- * `b.compliance.set` so picking a posture also wires outbound DLP
- * automatically. Direct callers usually want `installOutboundDlp`
- * because it accepts the full hook surface.
+ * Posture-coordinated install — picks the default classifier for
+ * `posture` and wraps the operator-supplied `primitives.httpClient` /
+ * `.mail` / `.webhook` so every outbound payload runs through it. A
+ * thin convenience over `installOutboundDlp`; direct callers usually
+ * want `installOutboundDlp` because it accepts the full hook surface.
+ *
+ * The operator MUST call this with the primitive instances — pinning a
+ * posture via `b.compliance.set` does NOT auto-install outbound DLP,
+ * because the compliance coordinator holds no httpClient / mail /
+ * webhook handles. When a posture whose floor implies outbound DLP
+ * (hipaa / pci-dss / gdpr / soc2 / fapi-2.0) is pinned without this
+ * call, `b.compliance.set` emits a one-time
+ * `compliance.posture.outbound_dlp_unwired` audit warning so the gap is
+ * grep-able in the audit chain.
  *
  * @example
  *   var dlp = b.redact.installForPosture("hipaa", {
@@ -999,6 +1055,7 @@ module.exports = {
   classifyDefaults:      classifyDefaults,
   installOutboundDlp:    installOutboundDlp,
   installForPosture:     installForPosture,
+  isOutboundDlpInstalled: isOutboundDlpInstalled,
   CLASSIFIER_PATTERNS:   CLASSIFIER_PATTERNS,
   MARKER:                DEFAULT_MARKER,
   SENSITIVE_FIELDS:      SENSITIVE_FIELDS,