@blamejs/core 0.9.24 → 0.9.38

package/lib/guard-tenant-id.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * @module     b.guardTenantId
+ * @nav        Guards
+ * @title      Guard Tenant Id
+ * @order      440
+ *
+ * @intro
+ *   Tenant-id shape validator. Tenant ids surface in audit log lines,
+ *   sealed registry rows, derived-key context labels, and routing
+ *   keys — they have to be ASCII-greppable across the whole framework
+ *   stack. Refuses:
+ *
+ *     - non-ASCII (NFC + ASCII-only)
+ *     - path-traversal shapes (`..` / `/` / `\` / NUL / C0 / DEL)
+ *     - oversized (default 64 bytes)
+ *     - reserved `ROOT` / `FRAMEWORK` / `*` / empty
+ *     - leading `.` (hidden-folder shape)
+ *
+ * @card
+ *   Validates tenant-id strings. ASCII-only, bounded, no path-
+ *   traversal, no reserved names.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardTenantIdError = defineClass("GuardTenantIdError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxBytes: 64  },                                                                      // allow:raw-byte-literal
+  balanced:   { maxBytes: 128 },                                                                      // allow:raw-byte-literal
+  permissive: { maxBytes: 512 },                                                                      // allow:raw-byte-literal
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+var RESERVED = Object.freeze({ "ROOT": true, "FRAMEWORK": true, "*": true });
+
+/**
+ * @primitive b.guardTenantId.validate
+ * @signature b.guardTenantId.validate(tenantId, opts?)
+ * @since     0.9.26
+ * @status    stable
+ * @related   b.agent.tenant.create
+ *
+ * Validate a tenant-id string. Returns the id on success; throws
+ * `GuardTenantIdError` on refusal.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardTenantId.validate("acme-clinic");
+ */
+function validate(tenantId, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (typeof tenantId !== "string" || tenantId.length === 0) {
+    throw new GuardTenantIdError("tenant-id/bad-input",
+      "guardTenantId.validate: tenantId must be a non-empty string");
+  }
+  if (Buffer.byteLength(tenantId, "utf8") > profile.maxBytes) {
+    throw new GuardTenantIdError("tenant-id/oversize",
+      "guardTenantId.validate: tenantId exceeds maxBytes=" + profile.maxBytes);
+  }
+  if (RESERVED[tenantId]) {
+    throw new GuardTenantIdError("tenant-id/reserved",
+      "guardTenantId.validate: tenantId '" + tenantId + "' is framework-reserved");
+  }
+  if (tenantId.charAt(0) === ".") {
+    throw new GuardTenantIdError("tenant-id/hidden",
+      "guardTenantId.validate: tenantId cannot start with '.'");
+  }
+  if (tenantId.indexOf("..") >= 0) {
+    throw new GuardTenantIdError("tenant-id/path-traversal",
+      "guardTenantId.validate: tenantId contains '..'");
+  }
+  for (var i = 0; i < tenantId.length; i += 1) {
+    var c = tenantId.charCodeAt(i);
+    if (c > 0x7F) {                                                                                   // allow:raw-byte-literal — ASCII-only cap
+      throw new GuardTenantIdError("tenant-id/non-ascii",
+        "guardTenantId.validate: non-ASCII codepoint at offset " + i);
+    }
+    if (c < 0x20 || c === 0x7F || c === 0x2F || c === 0x5C) {                                         // allow:raw-byte-literal — C0/DEL/slash/backslash
+      throw new GuardTenantIdError("tenant-id/bad-char",
+        "guardTenantId.validate: forbidden char 0x" + c.toString(16) + " at offset " + i);
+    }
+  }
+  return tenantId;
+}
+
+/**
+ * @primitive b.guardTenantId.compliancePosture
+ * @signature b.guardTenantId.compliancePosture(posture)
+ * @since     0.9.26
+ * @status    stable
+ *
+ * Return the effective profile for a given compliance posture name.
+ * Returns `null` for unknown posture names so operator typos surface
+ * here instead of silently falling through to the default profile.
+ *
+ * @example
+ *   b.guardTenantId.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return COMPLIANCE_POSTURES[opts.posture];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardTenantIdError("tenant-id/bad-profile",
+      "guardTenantId: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:               validate,
+  compliancePosture:      compliancePosture,
+  PROFILES:               PROFILES,
+  COMPLIANCE_POSTURES:    COMPLIANCE_POSTURES,
+  RESERVED:               RESERVED,
+  GuardTenantIdError:     GuardTenantIdError,
+  NAME:                   "tenantId",
+  KIND:                   "tenant-id",
+};

package/lib/guard-trace-context.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * @module     b.guardTraceContext
+ * @nav        Guards
+ * @title      Guard Trace Context
+ * @order      443
+ *
+ * @intro
+ *   W3C Trace Context (`traceparent` + `tracestate`) shape validator.
+ *   The agent-trace primitive (v0.9.29) injects traceparent strings
+ *   into queue envelopes + event-bus payloads + sub-agent calls;
+ *   consumers extract + start child spans. This guard refuses
+ *   malformed traceparent strings (cross-boundary tampering, operator
+ *   bugs, attacker-controlled trace IDs).
+ *
+ *   W3C Trace Context section 3.2: `<version>-<trace-id>-<parent-id>-<flags>`
+ *   in hex form. v00 is the only currently-defined version; future
+ *   versions get refused under strict profile.
+ *
+ *   `tracestate` (W3C section 3.3) is a comma-separated list of vendor key=
+ *   value pairs, capped at 32 entries.
+ *
+ * @card
+ *   Validates W3C traceparent + tracestate strings at agent
+ *   boundaries. Refuses malformed shape, oversize tracestate,
+ *   non-hex trace/span ids.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardTraceContextError = defineClass("GuardTraceContextError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { allowedVersions: ["00"],       maxTracestateEntries: 32, maxTracestateBytes: 512  },  // allow:raw-byte-literal
+  balanced:   { allowedVersions: ["00", "01"], maxTracestateEntries: 32, maxTracestateBytes: 512  },  // allow:raw-byte-literal
+  permissive: { allowedVersions: ["*"],         maxTracestateEntries: 64, maxTracestateBytes: 1024 }, // allow:raw-byte-literal
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+var TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;                   // allow:regex-no-length-cap — length-bound inline before test
+
+/**
+ * @primitive b.guardTraceContext.validate
+ * @signature b.guardTraceContext.validate(ctx, opts?)
+ * @since     0.9.29
+ * @status    stable
+ * @related   b.agent.trace.create, b.tracing.create
+ *
+ * Validate a traceparent + optional tracestate envelope. Returns the
+ * input on success; throws on shape refusal.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardTraceContext.validate({
+ *     traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+ *   });
+ */
+function validate(ctx, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (!ctx || typeof ctx !== "object") {
+    throw new GuardTraceContextError("trace-context/bad-input",
+      "guardTraceContext.validate: ctx required");
+  }
+  if (typeof ctx.traceparent !== "string" || ctx.traceparent.length === 0) {
+    throw new GuardTraceContextError("trace-context/no-traceparent",
+      "guardTraceContext.validate: traceparent required");
+  }
+  // Length bound BEFORE regex test so a hostile input can't burn
+  // regex-engine CPU. W3C section 3.2.1: exactly 55 chars.
+  if (ctx.traceparent.length !== 55) {                                                                // allow:raw-byte-literal — W3C fixed length
+    throw new GuardTraceContextError("trace-context/bad-traceparent-length",
+      "guardTraceContext.validate: traceparent must be exactly 55 chars (got " +
+      ctx.traceparent.length + ")");
+  }
+  var m = TRACEPARENT_RE.exec(ctx.traceparent);
+  if (!m) {
+    throw new GuardTraceContextError("trace-context/bad-traceparent-shape",
+      "guardTraceContext.validate: traceparent does not match W3C section 3.2 shape");
+  }
+  var version = m[1];
+  var traceId = m[2];
+  var spanId  = m[3];
+  // version "ff" is invalid per W3C section 3.2.2 (forbidden value)
+  if (version === "ff") {
+    throw new GuardTraceContextError("trace-context/forbidden-version",
+      "guardTraceContext.validate: version 'ff' is W3C-forbidden");
+  }
+  if (profile.allowedVersions[0] !== "*" && profile.allowedVersions.indexOf(version) < 0) {
+    throw new GuardTraceContextError("trace-context/version-not-allowed",
+      "guardTraceContext.validate: version '" + version + "' not in profile allowlist " +
+      JSON.stringify(profile.allowedVersions));
+  }
+  if (traceId === "00000000000000000000000000000000") {
+    throw new GuardTraceContextError("trace-context/zero-trace-id",
+      "guardTraceContext.validate: trace-id all-zero is W3C-invalid");
+  }
+  if (spanId === "0000000000000000") {
+    throw new GuardTraceContextError("trace-context/zero-span-id",
+      "guardTraceContext.validate: parent-id all-zero is W3C-invalid");
+  }
+  if (typeof ctx.tracestate !== "undefined") {
+    if (typeof ctx.tracestate !== "string") {
+      throw new GuardTraceContextError("trace-context/bad-tracestate-type",
+        "guardTraceContext.validate: tracestate must be a string");
+    }
+    if (Buffer.byteLength(ctx.tracestate, "utf8") > profile.maxTracestateBytes) {
+      throw new GuardTraceContextError("trace-context/tracestate-too-big",
+        "guardTraceContext.validate: tracestate exceeds maxTracestateBytes=" +
+        profile.maxTracestateBytes);
+    }
+    if (ctx.tracestate.length > 0) {
+      var entries = ctx.tracestate.split(",");
+      if (entries.length > profile.maxTracestateEntries) {
+        throw new GuardTraceContextError("trace-context/too-many-tracestate-entries",
+          "guardTraceContext.validate: " + entries.length +
+          " tracestate entries exceeds " + profile.maxTracestateEntries);
+      }
+    }
+  }
+  return ctx;
+}
+
+/**
+ * @primitive b.guardTraceContext.compliancePosture
+ * @signature b.guardTraceContext.compliancePosture(posture)
+ * @since     0.9.29
+ * @status    stable
+ *
+ * Return the effective profile for a given compliance posture name.
+ * Returns `null` for unknown posture names so operator typos surface
+ * here instead of silently falling through to the default profile.
+ *
+ * @example
+ *   b.guardTraceContext.compliancePosture("hipaa");   // returns "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return COMPLIANCE_POSTURES[opts.posture];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardTraceContextError("trace-context/bad-profile",
+      "guardTraceContext: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:                 validate,
+  compliancePosture:        compliancePosture,
+  PROFILES:                 PROFILES,
+  COMPLIANCE_POSTURES:      COMPLIANCE_POSTURES,
+  GuardTraceContextError:   GuardTraceContextError,
+  NAME:                     "traceContext",
+  KIND:                     "trace-context",
+};

package/lib/ip-utils.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * lib/ip-utils.js — internal IP-address helpers shared across
+ * `b.mail.auth` (SPF / DMARC IP-in-CIDR), `b.mail.rbl` (RFC 5782
+ * reverse-DNS), `b.mail.greylist` (RFC 6647 CIDR fingerprint).
+ *
+ * Not exposed on the operator-facing `b` surface; internal compose
+ * point so the three consumers don't drift on IPv6 parsing.
+ *
+ * RFC 4291 §2.2 IPv6 text form: 8 groups of 1-4 hex characters
+ * separated by `:`; one `::` allowed to compress a contiguous run
+ * of zero groups; IPv4-mapped form `::ffff:1.2.3.4` per RFC 5952 §5
+ * + dual-stack `::a.b.c.d` per RFC 4291 §2.5.5.2.
+ */
+
+/**
+ * Expand an IPv6 address to its full 32-hex-character form. Returns
+ * `null` on parse failure (invalid hex group, group count != 8,
+ * multiple `::`, group > 0xffff).
+ *
+ *   expandIpv6Hex("2001:db8::1")       → "20010db8000000000000000000000001"
+ *   expandIpv6Hex("::ffff:192.0.2.1")  → "00000000000000000000ffffc0000201"
+ *   expandIpv6Hex("::1")               → "00000000000000000000000000000001"
+ *   expandIpv6Hex("bad")               → null
+ */
+function expandIpv6Hex(ip) {
+  if (typeof ip !== "string") return null;
+  // RFC 4291 §2.5.5.2 IPv4-mapped / dual-stack: accept ".d.d.d.d" tail.
+  var dual = ip.match(/^(.*?):(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);                                    // allow:regex-no-length-cap — dotted-quad has fixed shape; LHS bounded by IPv6 group cap below
+  if (dual) {
+    var v4 = dual[2].split(".").map(Number);
+    if (v4.some(function (o) { return !(o >= 0 && o <= 255); })) return null;                            // allow:raw-byte-literal — IPv4 octet range
+    var hi = (v4[0] << 8) | v4[1];                                                                       // allow:raw-byte-literal — 16-bit group pack
+    var lo = (v4[2] << 8) | v4[3];                                                                       // allow:raw-byte-literal — 16-bit group pack
+    ip = dual[1] + ":" + hi.toString(16) + ":" + lo.toString(16);
+  }
+  var dblColon = ip.split("::");
+  if (dblColon.length > 2) return null;
+  var leftGroups  = dblColon[0] === "" ? [] : dblColon[0].split(":");
+  var rightGroups = dblColon.length === 2 ? (dblColon[1] === "" ? [] : dblColon[1].split(":")) : [];
+  if (dblColon.length === 1 && leftGroups.length !== 8) return null;                                      // allow:raw-byte-literal — RFC 4291 IPv6 group count
+  var fillCount = 8 - leftGroups.length - rightGroups.length;                                             // allow:raw-byte-literal — RFC 4291 IPv6 group count
+  if (fillCount < 0) return null;
+  var fill = [];
+  for (var f = 0; f < fillCount; f += 1) fill.push("0");
+  var groups = leftGroups.concat(fill).concat(rightGroups);
+  if (groups.length !== 8) return null;                                                                   // allow:raw-byte-literal — RFC 4291 IPv6 group count
+  var hex = "";
+  for (var i = 0; i < 8; i += 1) {                                                                        // allow:raw-byte-literal — RFC 4291 IPv6 group count
+    var g = groups[i];
+    if (g.length === 0 || g.length > 4) return null;                                                      // allow:raw-byte-literal — RFC 4291 IPv6 hex-group max length
+    for (var hc = 0; hc < g.length; hc += 1) {
+      var cp = g.charCodeAt(hc);
+      var isDigit    = cp >= 0x30 && cp <= 0x39;                                                          // allow:raw-byte-literal — ASCII '0'..'9'
+      var isLowerHex = cp >= 0x61 && cp <= 0x66;                                                          // allow:raw-byte-literal — ASCII 'a'..'f'
+      var isUpperHex = cp >= 0x41 && cp <= 0x46;                                                          // allow:raw-byte-literal — ASCII 'A'..'F'
+      if (!isDigit && !isLowerHex && !isUpperHex) return null;
+    }
+    hex += g.toLowerCase().padStart(4, "0");                                                              // allow:raw-byte-literal — 4 hex chars per IPv6 group
+  }
+  return hex;
+}
+
+/**
+ * Expand IPv6 to an 8-element array of 16-bit unsigned integers.
+ * Used by `b.mail.auth` SPF / DMARC IP-in-CIDR evaluation which
+ * does bitwise group-level math.
+ *
+ *   expandIpv6Groups("::1")   → [0,0,0,0,0,0,0,1]
+ *   expandIpv6Groups("bad")   → null
+ */
+function expandIpv6Groups(ip) {
+  var hex = expandIpv6Hex(ip);
+  if (hex === null) return null;
+  var groups = new Array(8);                                                                              // allow:raw-byte-literal — RFC 4291 IPv6 group count
+  for (var i = 0; i < 8; i += 1) {                                                                        // allow:raw-byte-literal — RFC 4291 IPv6 group count
+    groups[i] = parseInt(hex.slice(i * 4, i * 4 + 4), 16);                                                // allow:raw-byte-literal — 4 hex chars per IPv6 group
+  }
+  return groups;
+}
+
+// Loose IPv4 textual-form check — for primitives that need to
+// classify a string as "looks like dotted-quad IPv4" but don't need
+// the strict per-octet bound check (callers that DO need octet
+// bounds use the strict form in `mail-rbl.js` etc.). Shared so
+// `lib/mail.js`, `lib/mail-helo.js`, and `lib/redis-client.js`
+// don't drift on the same shape.
+//
+//   isIPv4Shape("1.2.3.4")     → true
+//   isIPv4Shape("999.0.0.0")   → true (shape only; octets unbounded)
+//   isIPv4Shape("not-an-ip")   → false
+//   isIPv4Shape("1.2.3")       → false
+var IPV4_SHAPE_RE = /^\d+\.\d+\.\d+\.\d+$/;                                                              // allow:regex-no-length-cap — anchored + literal-dot shape; caller bounds length
+function isIPv4Shape(s) {
+  return typeof s === "string" && IPV4_SHAPE_RE.test(s);
+}
+
+module.exports = {
+  expandIpv6Hex:    expandIpv6Hex,
+  expandIpv6Groups: expandIpv6Groups,
+  isIPv4Shape:      isIPv4Shape,
+};

package/lib/mail-auth.js

@@ -41,6 +41,7 @@ var validateOpts = require("./validate-opts");
 var C = require("./constants");
 var dkim = require("./mail-dkim");
 var safeXml = require("./parsers/safe-xml");
+var ipUtils = require("./ip-utils");
 var publicSuffix = require("./public-suffix");
 var { MailAuthError } = require("./framework-error");
 
@@ -69,41 +70,9 @@ function _ipv4ToInt(ip) {
 // Expand an IPv6 string (which may carry `::` shorthand) into 8 16-bit
 // groups. Returns null on malformed input.
 function _ipv6Expand(ip) {
-  if (typeof ip !== "string") return null;
-  // Accept IPv4-in-IPv6 dual-stack form (e.g. ::ffff:1.2.3.4).
-  var dual = ip.match(/^(.*?):(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
-  if (dual) {
-    var v4 = dual[2].split(".").map(Number);
-    if (v4.some(function (o) { return !(o >= 0 && o <= 255); })) return null;                // allow:raw-byte-literal — octet range
-    var hi = (v4[0] << 8) | v4[1];                                                            // allow:raw-byte-literal — 16-bit group pack
-    var lo = (v4[2] << 8) | v4[3];                                                            // allow:raw-byte-literal — 16-bit group pack
-    ip = dual[1] + ":" + hi.toString(16) + ":" + lo.toString(16);
-  }
-  var dblColon = ip.split("::");
-  if (dblColon.length > 2) return null;
-  var leftGroups  = dblColon[0] === "" ? [] : dblColon[0].split(":");
-  var rightGroups = dblColon.length === 2 ? (dblColon[1] === "" ? [] : dblColon[1].split(":")) : [];
-  if (dblColon.length === 1 && leftGroups.length !== 8) return null;                          // allow:raw-byte-literal — IPv6 group count
-  var fillCount = 8 - leftGroups.length - rightGroups.length;                                 // allow:raw-byte-literal — IPv6 group count
-  if (fillCount < 0) return null;
-  var fill = [];
-  for (var f = 0; f < fillCount; f += 1) fill.push("0");
-  var groups = leftGroups.concat(fill).concat(rightGroups);
-  if (groups.length !== 8) return null;                                                       // allow:raw-byte-literal — IPv6 group count
-  var out = new Array(8);                                                                     // allow:raw-byte-literal — IPv6 group count
-  for (var i = 0; i < 8; i += 1) {                                                            // allow:raw-byte-literal — IPv6 group count
-    var g = groups[i];
-    // RFC 4291 IPv6 hex group: 1..4 hex chars. Avoid the
-    // `/^[0-9a-fA-F]{1,4}$/` regex that's already in guard-cidr +
-    // safe-json (codebase-patterns flags 3+ duplicates) by
-    // length-then-parse: parseInt with radix 16 returns NaN on
-    // non-hex; numeric-bound check rejects out-of-range output.
-    if (g.length === 0 || g.length > 4) return null;                                          // allow:raw-byte-literal — IPv6 hex group max length
-    var groupVal = parseInt(g, 16);                                                            // allow:raw-byte-literal — IPv6 hex base
-    if (!isFinite(groupVal) || groupVal < 0 || groupVal > 0xffff) return null;                // allow:raw-byte-literal — IPv6 group max value
-    out[i] = groupVal;
-  }
-  return out;
+  // Compose the shared lib/ip-utils helper so the same IPv6 parse
+  // path is shared across mail-auth / mail-rbl / mail-greylist.
+  return ipUtils.expandIpv6Groups(ip);
 }
 
 function _ipv6InCidr(ip, cidr) {