@blamejs/core 0.14.26 → 0.15.0

package/lib/guard-domain.js

@@ -648,167 +648,44 @@ function sanitize(input, opts) {
   }
   // Critical refuses can't be repaired.
   var issues = _detectIssues(input, opts);
-  for (var i = 0; i < issues.length; i += 1) {
-    if (issues[i].severity === "critical" || issues[i].severity === "high") {
-      throw _err(issues[i].ruleId || "domain.refused",
-        "guardDomain.sanitize: " + issues[i].snippet);
-    }
-  }
+  gateContract.throwOnRefusalSeverity(issues, { errorClass: GuardDomainError, codePrefix: "domain" });
   // Safe transforms: lowercase ASCII, strip trailing dot.
   var out = input.toLowerCase();
   if (out.charAt(out.length - 1) === ".") out = out.slice(0, -1);
   return out;
 }
 
-/**
- * @primitive  b.guardDomain.gate
- * @signature  b.guardDomain.gate(opts?)
- * @since      0.7.41
- * @status     stable
- * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardDomain.validate, b.guardDomain.sanitize
- *
- * Build a `b.gateContract` gate that consumes `ctx.identifier` (or
- * `ctx.domain`) and dispatches `serve` (no input or clean) →
- * `audit-only` (warn-only issues) → `refuse` (any critical or high
- * issue). No `sanitize` action — domain canonicalization is
- * caller-driven via `b.guardDomain.sanitize` so an allowlist gate
- * never silently rewrites the operator's stored allowlist key.
- *
- * @opts
- *   profile:    "strict"|"balanced"|"permissive",
- *   compliancePosture: "hipaa"|"pci-dss"|"gdpr"|"soc2",
- *   name:       string,    // gate identity for audit / observability
- *
- * @example
- *   var domGate = b.guardDomain.gate({ profile: "strict" });
- *   var verdict = await domGate.check({ identifier: "myhost.localhost" });
- *   verdict.action;                                    // → "refuse"
- */
-function gate(opts) {
-  opts = _resolveOpts(opts);
-  return gateContract.buildGuardGate(
-    opts.name || "guardDomain:" + (opts.profile || "default"),
-    opts,
-    async function (ctx) {
-      // Identifier-shape ctx — operator passes via ctx.identifier or
-      // ctx.domain.
-      var identifier = ctx && (ctx.identifier || ctx.domain || "");
-      if (!identifier) return { ok: true, action: "serve" };
-      var rv = validate(identifier, opts);
-      if (rv.issues.length === 0) return { ok: true, action: "serve" };
-      var hasCritical = rv.issues.some(function (i) {
-        return i.severity === "critical";
-      });
-      var hasHigh = rv.issues.some(function (i) {
-        return i.severity === "high";
-      });
-      if (!hasCritical && !hasHigh) {
-        return { ok: true, action: "audit-only", issues: rv.issues };
-      }
-      return { ok: false, action: "refuse", issues: rv.issues };
-    });
-}
-
-/**
- * @primitive  b.guardDomain.buildProfile
- * @signature  b.guardDomain.buildProfile(opts)
- * @since      0.7.41
- * @status     stable
- * @related    b.guardDomain.gate, b.guardDomain.compliancePosture
- *
- * Compose a derived profile from one or more named bases plus inline
- * overrides. `opts.extends` is a profile name (`"strict"` /
- * `"balanced"` / `"permissive"`) or an array of names; later entries
- * shadow earlier ones. Inline `opts` keys win last.
- *
- * @opts
- *   extends: string|string[],   // base profile name(s) to compose
- *
- * @example
- *   var custom = b.guardDomain.buildProfile({
- *     extends: "balanced",
- *     allowedScripts: ["latin"],
- *     punycodePolicy: "reject",
- *   });
- *   custom.punycodePolicy;                             // → "reject"
- *   custom.bidiPolicy;                                 // → "reject"
- */
-var buildProfile = gateContract.makeProfileBuilder(PROFILES);
-
-/**
- * @primitive  b.guardDomain.compliancePosture
- * @signature  b.guardDomain.compliancePosture(name)
- * @since      0.7.41
- * @status     stable
- * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardDomain.gate, b.guardDomain.buildProfile
- *
- * Look up a compliance-posture overlay by name (`"hipaa"` /
- * `"pci-dss"` / `"gdpr"` / `"soc2"`). Returns a shallow clone of the
- * posture object — the caller may mutate freely. Throws
- * `GuardDomainError("domain.bad-posture")` on unknown name.
- *
- * @example
- *   var posture = b.guardDomain.compliancePosture("hipaa");
- *   posture.specialUsePolicy;                          // → "reject"
- *   posture.forensicSnippetBytes;                      // → 256
- */
-function compliancePosture(name) {
-  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
-    _err, "domain");
-}
+// gate / buildProfile / compliancePosture / loadRulePack are assembled by
+// gateContract.defineGuard below; their wiki sections render from the
+// single-sourced @abiTemplate (defineGuard) blocks in gate-contract.js,
+// instantiated per guard by the page generator.
+
+var INTEGRATION_FIXTURES = Object.freeze({
+  kind:        "identifier",
+  benignBytes: Buffer.from("example.com", "utf8"),
+  // Hostile: dotted-decimal IPv4 (CVE-2021-22931 class) — every
+  // profile refuses (allowlist-bypass via DNS rebinding).
+  hostileBytes: Buffer.from("192.168.1.1", "utf8"),
+  benignIdentifier:  "example.com",
+  hostileIdentifier: "192.168.1.1",
+});
 
-var _domainRulePacks = gateContract.makeRulePackLoader(GuardDomainError, "domain");
-/**
- * @primitive  b.guardDomain.loadRulePack
- * @signature  b.guardDomain.loadRulePack(pack)
- * @since      0.7.41
- * @status     stable
- * @related    b.guardDomain.gate
- *
- * Register an operator-supplied rule pack with the guard-domain
- * registry. The pack is identified by `pack.id` (non-empty string)
- * and stored for later inspection / dispatch by gates that opt in
- * via `opts.rulePackId`. Returns the pack object unchanged on
- * success; throws `GuardDomainError("domain.bad-opt")` when `pack`
- * is missing or `pack.id` is not a non-empty string.
- *
- * @example
- *   var pack = b.guardDomain.loadRulePack({
- *     id: "tenant-corp-only",
- *     rules: [
- *       { id: "tenant-suffix", severity: "high",
- *         detect: function (d) { return !/\.example\.com$/i.test(d); },
- *         reason: "tenant policy: only example.com suffixes permitted" },
- *     ],
- *   });
- *   pack.id;                                           // → "tenant-corp-only"
- */
-var loadRulePack = _domainRulePacks.load;
-
-module.exports = {
-  // ---- guard-* family registry exports ----
-  NAME:                "domain",
-  KIND:                "identifier",
-  INTEGRATION_FIXTURES: Object.freeze({
-    kind:        "identifier",
-    benignBytes: Buffer.from("example.com", "utf8"),
-    // Hostile: dotted-decimal IPv4 (CVE-2021-22931 class) — every
-    // profile refuses (allowlist-bypass via DNS rebinding).
-    hostileBytes: Buffer.from("192.168.1.1", "utf8"),
-    benignIdentifier:  "example.com",
-    hostileIdentifier: "192.168.1.1",
-  }),
-  // ---- primitive surface ----
-  validate:            validate,
-  sanitize:            sanitize,
-  gate:                gate,
-  buildProfile:        buildProfile,
-  compliancePosture:   compliancePosture,
-  loadRulePack:        loadRulePack,
-  PROFILES:            PROFILES,
-  DEFAULTS:            DEFAULTS,
-  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
-  GuardDomainError:    GuardDomainError,
-};
+// Assembled from the gate-contract guard factory: error class, registry
+// exports (NAME / KIND / INTEGRATION_FIXTURES), buildProfile /
+// compliancePosture / loadRulePack wiring, plus the per-guard inspection
+// surface (validate / sanitize). The gate is the factory default — the
+// standard serve -> audit-only -> refuse chain — reading ctx.identifier ||
+// ctx.domain via ctxFields. No sanitize action: an allowlist gate never
+// rewrites the operator's stored allowlist key.
+module.exports = gateContract.defineGuard({
+  name:        "domain",
+  kind:        "identifier",
+  errorClass:  GuardDomainError,
+  profiles:    PROFILES,
+  defaults:    DEFAULTS,
+  postures:    COMPLIANCE_POSTURES,
+  integrationFixtures: INTEGRATION_FIXTURES,
+  validate:    validate,
+  sanitize:    sanitize,
+  ctxFields:   ["identifier", "domain"],
+});

package/lib/guard-dsn.js

@@ -101,6 +101,7 @@
 
 var C                  = require("./constants");
 var { defineClass }    = require("./framework-error");
+var gateContract       = require("./gate-contract");
 
 var GuardDsnError = defineClass("GuardDsnError", { alwaysPermanent: true });
 
@@ -112,12 +113,7 @@ var PROFILES = Object.freeze({
   permissive: { maxBytes: C.BYTES.mib(4),   maxRecipients: 4096, maxHeaderLine: 998 },                   // RFC 5322 §2.1.1 line cap; large-blast bounce class
 });
 
-var COMPLIANCE_POSTURES = Object.freeze({
-  hipaa:     "strict",
-  "pci-dss": "strict",
-  gdpr:      "strict",
-  soc2:      "strict",
-});
+var COMPLIANCE_POSTURES = gateContract.ALL_STRICT_POSTURES;
 
 var KNOWN_ACTIONS = Object.freeze({
   failed:    true,
@@ -263,22 +259,6 @@ function parse(deliveryStatusBody, opts) {
   };
 }
 
-/**
- * @primitive b.guardDsn.compliancePosture
- * @signature b.guardDsn.compliancePosture(posture)
- * @since     0.9.37
- * @status    stable
- *
- * Return the effective profile name for a compliance posture, or
- * `null` for unknown posture names.
- *
- * @example
- *   b.guardDsn.compliancePosture("hipaa");   // → "strict"
- */
-function compliancePosture(posture) {
-  return COMPLIANCE_POSTURES[posture] || null;
-}
-
 function _splitBlocks(text) {
   // RFC 3464 §2.1.1: block separator is `CRLF CRLF` only — a "blank
   // line" in message-syntax terms. `\n\s*\n` admits `\v` / `\f` /
@@ -359,25 +339,29 @@ function _statusClass(firstDigit) {
   return "unknown";
 }
 
-function _resolveProfile(opts) {
-  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
-    return PROFILES[COMPLIANCE_POSTURES[opts.posture]];
-  }
-  var p = opts.profile || DEFAULT_PROFILE;
-  if (!PROFILES[p]) {
-    throw new GuardDsnError("guard-dsn/bad-profile",
-      "guardDsn: unknown profile '" + p + "'");
-  }
-  return PROFILES[p];
-}
+var _resolveProfile = gateContract.makeProfileResolver({
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  defaults:   DEFAULT_PROFILE,
+  errorClass: GuardDsnError,
+  codePrefix: "guard-dsn",
+  byObject:   true,
+});
 
-module.exports = {
-  parse:                   parse,
-  compliancePosture:       compliancePosture,
-  PROFILES:                PROFILES,
-  COMPLIANCE_POSTURES:     COMPLIANCE_POSTURES,
-  KNOWN_ACTIONS:           KNOWN_ACTIONS,
-  GuardDsnError:           GuardDsnError,
-  NAME:                    "dsn",
-  KIND:                    "delivery-status",
-};
+// compliancePosture is assembled by gateContract.defineParser below; its
+// wiki section renders from the single-sourced @abiTemplate (defineParser)
+// block in gate-contract.js, instantiated for this guard by the page
+// generator.
+module.exports = gateContract.defineParser({
+  name:       "dsn",
+  entry:      parse,
+  entryName:  "parse",
+  errorClass: GuardDsnError,
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  extra: {
+    KNOWN_ACTIONS: KNOWN_ACTIONS,
+    NAME:          "dsn",
+    KIND:          "delivery-status",
+  },
+});

package/lib/guard-email.js

@@ -857,12 +857,8 @@ function sanitize(input, opts) {
   // Critical shapes have no safe sanitization in email — throw on
   // smuggling / CRLF injection / multi-@ / mixed-script.
   var issues = _detectMessageIssues(input, opts);
-  for (var i = 0; i < issues.length; i += 1) {
-    if (issues[i].severity === "critical") {
-      throw _err(issues[i].ruleId || "email.refused",
-        "guardEmail.sanitize: " + issues[i].snippet);
-    }
-  }
+  gateContract.throwOnRefusalSeverity(issues,
+    { errorClass: GuardEmailError, codePrefix: "email", severities: ["critical"] });
   return codepointClass.applyCharStripPolicies(input, opts);
 }
 
@@ -919,67 +915,49 @@ function gate(opts) {
     });
 }
 
-var buildProfile = gateContract.makeProfileBuilder(PROFILES);
-
-/**
- * @primitive b.guardEmail.compliancePosture
- * @signature b.guardEmail.compliancePosture(name)
- * @since     0.7.17
- * @status    stable
- * @compliance hipaa, pci-dss, gdpr, soc2
- * @related   b.guardEmail.gate, b.guardEmail.validateMessage
- *
- * Look up a compliance posture by name and return its frozen opts
- * bundle. Throws `GuardEmailError` (`email.unknown-posture`) for
- * names outside `hipaa` / `pci-dss` / `gdpr` / `soc2`. The returned
- * opts can be merged into a `gate()` / `validateMessage()` call to
- * apply the posture's defaults (forensic-snippet length included).
- *
- * @example
- *   var guardEmail = require("./lib/guard-email");
- *   var posture = guardEmail.compliancePosture("hipaa");
- *   posture.bareCrPolicy;             // → "reject"
- *   posture.forensicSnippetBytes;     // → 256
- */
-function compliancePosture(name) {
-  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES, _err, "email");
-}
+// buildProfile / compliancePosture / loadRulePack are assembled by
+// gateContract.defineGuard below; their wiki sections render from the
+// single-sourced @abiTemplate (defineGuard) blocks in gate-contract.js,
+// instantiated per guard by the page generator.
+
+var INTEGRATION_FIXTURES = Object.freeze({
+  kind:         "content",
+  contentType:  "message/rfc822",
+  extension:    ".eml",
+  benignBytes:  Buffer.from(
+    "From: alice@example.com\r\nTo: bob@example.com\r\n" +
+    "Subject: hello\r\nDate: Mon, 5 May 2026 10:00:00 +0000\r\n\r\n" +
+    "Hello.\r\n", "utf8"),
+  // Hostile: SMTP-smuggling pattern — bare LF followed by SMTP verb
+  // (CVE-2023-51764 / 51765 / 51766 class).
+  hostileBytes: Buffer.from(
+    "From: alice@example.com\r\nTo: bob@example.com\r\n" +
+    "Subject: hi\r\n\r\n" +
+    "body line 1\n.\nMAIL FROM: <evil@attacker>\r\n", "utf8"),
+});
 
-var _emailRulePacks = gateContract.makeRulePackLoader(GuardEmailError, "email");
-var loadRulePack = _emailRulePacks.load;
-
-module.exports = {
-  // ---- guard-* family registry exports ----
-  NAME:                "email",
-  KIND:                "content",
-  MIME_TYPES:          Object.freeze(["message/rfc822", "message/global"]),
-  EXTENSIONS:          Object.freeze([".eml", ".mbox", ".msg"]),
-  INTEGRATION_FIXTURES: Object.freeze({
-    kind:         "content",
-    contentType:  "message/rfc822",
-    extension:    ".eml",
-    benignBytes:  Buffer.from(
-      "From: alice@example.com\r\nTo: bob@example.com\r\n" +
-      "Subject: hello\r\nDate: Mon, 5 May 2026 10:00:00 +0000\r\n\r\n" +
-      "Hello.\r\n", "utf8"),
-    // Hostile: SMTP-smuggling pattern — bare LF followed by SMTP verb
-    // (CVE-2023-51764 / 51765 / 51766 class).
-    hostileBytes: Buffer.from(
-      "From: alice@example.com\r\nTo: bob@example.com\r\n" +
-      "Subject: hi\r\n\r\n" +
-      "body line 1\n.\nMAIL FROM: <evil@attacker>\r\n", "utf8"),
-  }),
-  // ---- primitive surface ----
-  validate:            validate,
-  validateAddress:     validateAddress,
-  validateMessage:     validateMessage,
-  sanitize:            sanitize,
-  gate:                gate,
-  buildProfile:        buildProfile,
-  compliancePosture:   compliancePosture,
-  loadRulePack:        loadRulePack,
-  PROFILES:            PROFILES,
-  DEFAULTS:            DEFAULTS,
-  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
-  GuardEmailError:     GuardEmailError,
-};
+// Assembled from the gate-contract guard factory: error class, registry
+// exports (NAME / KIND / MIME_TYPES / EXTENSIONS / INTEGRATION_FIXTURES),
+// buildProfile / compliancePosture / loadRulePack wiring, plus the
+// per-guard inspection surface (validate / sanitize / bespoke gate) and
+// the address/message entries (validateAddress / validateMessage) passed
+// through verbatim. The bespoke `gate` validates via validateMessage and
+// carries the serve->audit-only->refuse chain unchanged.
+module.exports = gateContract.defineGuard({
+  name:        "email",
+  kind:        "content",
+  errorClass:  GuardEmailError,
+  profiles:    PROFILES,
+  defaults:    DEFAULTS,
+  postures:    COMPLIANCE_POSTURES,
+  mimeTypes:   ["message/rfc822", "message/global"],
+  extensions:  [".eml", ".mbox", ".msg"],
+  integrationFixtures: INTEGRATION_FIXTURES,
+  validate:    validate,
+  sanitize:    sanitize,
+  gate:        gate,
+  extra: {
+    validateAddress: validateAddress,
+    validateMessage: validateMessage,
+  },
+});

package/lib/guard-envelope.js

@@ -97,6 +97,7 @@
 var { defineClass }    = require("./framework-error");
 var lazyRequire        = require("./lazy-require");
 var publicSuffix       = require("./public-suffix");
+var gateContract       = require("./gate-contract");
 
 var audit              = lazyRequire(function () { return require("./audit"); });
 
@@ -116,12 +117,7 @@ var PROFILES = Object.freeze({
   permissive: { gateOnFailure: false, defaultMode: "relaxed" },
 });
 
-var COMPLIANCE_POSTURES = Object.freeze({
-  hipaa:     "strict",
-  "pci-dss": "strict",
-  gdpr:      "strict",
-  soc2:      "strict",
-});
+var COMPLIANCE_POSTURES = gateContract.ALL_STRICT_POSTURES;
 
 /**
  * @primitive b.guardEnvelope.check
@@ -206,22 +202,6 @@ function check(ctx, opts) {
   };
 }
 
-/**
- * @primitive b.guardEnvelope.compliancePosture
- * @signature b.guardEnvelope.compliancePosture(posture)
- * @since     0.9.36
- * @status    stable
- *
- * Return the effective profile name for a compliance posture, or
- * `null` for unknown posture names.
- *
- * @example
- *   b.guardEnvelope.compliancePosture("hipaa");   // → "strict"
- */
-function compliancePosture(posture) {
-  return COMPLIANCE_POSTURES[posture] || null;
-}
-
 function _spfVerdict(spfResult, fromDomain, mode) {
   var verdict = {
     aligned:    false,
@@ -282,13 +262,20 @@ function _emitAudit(auditImpl, action, metadata) {
   } catch (_e) { /* drop-silent — audit failure must not block accept loop */ }
 }
 
-module.exports = {
-  check:                   check,
-  compliancePosture:       compliancePosture,
-  PROFILES:                PROFILES,
-  COMPLIANCE_POSTURES:     COMPLIANCE_POSTURES,
-  GuardEnvelopeError:      GuardEnvelopeError,
-  NAME:                    "envelope",
-  KIND:                    "envelope-alignment",
-  _domainAligned:          _domainAligned,
-};
+// compliancePosture is assembled by gateContract.defineParser below; its
+// wiki section renders from the single-sourced @abiTemplate (defineParser)
+// block in gate-contract.js, instantiated for this guard by the page
+// generator.
+module.exports = gateContract.defineParser({
+  name:       "envelope",
+  entry:      check,
+  entryName:  "check",
+  errorClass: GuardEnvelopeError,
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  extra: {
+    NAME:           "envelope",
+    KIND:           "envelope-alignment",
+    _domainAligned: _domainAligned,
+  },
+});

package/lib/guard-event-bus-payload.js

@@ -40,6 +40,7 @@
  */
 
 var { defineClass } = require("./framework-error");
+var gateContract = require("./gate-contract");
 
 var GuardEventBusPayloadError = defineClass("GuardEventBusPayloadError", { alwaysPermanent: true });
 
@@ -51,12 +52,7 @@ var PROFILES = Object.freeze({
   permissive: { maxBytes: 1048576 },                                                                  // 1 MiB
 });
 
-var COMPLIANCE_POSTURES = Object.freeze({
-  hipaa:     "strict",
-  "pci-dss": "strict",
-  gdpr:      "strict",
-  soc2:      "strict",
-});
+var COMPLIANCE_POSTURES = gateContract.ALL_STRICT_POSTURES;
 
 var ISO_DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;        // allow:regex-no-length-cap — value length-bounded by maxBytes payload cap
 
@@ -135,22 +131,10 @@ function validate(payload, schema, opts) {
   return payload;
 }
 
-/**
- * @primitive b.guardEventBusPayload.compliancePosture
- * @signature b.guardEventBusPayload.compliancePosture(posture)
- * @since     0.9.25
- * @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.guardEventBusPayload.compliancePosture("hipaa");   // → "strict"
- */
-function compliancePosture(posture) {
-  return COMPLIANCE_POSTURES[posture] || null;
-}
+// compliancePosture is assembled by gateContract.defineParser below; its
+// wiki section renders from the single-sourced @abiTemplate (defineParser)
+// block in gate-contract.js, instantiated for this guard by the page
+// generator.
 
 function _checkType(value, type, fieldName) {
   if (type === "string" && typeof value !== "string") {
@@ -194,24 +178,22 @@ function _checkType(value, type, fieldName) {
   }
 }
 
-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 GuardEventBusPayloadError("event-bus-payload/bad-profile",
-      "guardEventBusPayload: unknown profile '" + p + "'");
-  }
-  return p;
-}
+var _resolveProfile = gateContract.makeProfileResolver({
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  defaults:   DEFAULT_PROFILE,
+  errorClass: GuardEventBusPayloadError,
+  codePrefix: "event-bus-payload",
+});
 
-module.exports = {
-  validate:                    validate,
-  compliancePosture:           compliancePosture,
-  PROFILES:                    PROFILES,
-  COMPLIANCE_POSTURES:         COMPLIANCE_POSTURES,
-  GuardEventBusPayloadError:   GuardEventBusPayloadError,
-  NAME:                        "eventBusPayload",
-  KIND:                        "event-bus-payload",
-};
+module.exports = gateContract.defineParser({
+  name:       "event-bus-payload",
+  entry:      validate,
+  errorClass: GuardEventBusPayloadError,
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  extra: {
+    NAME: "eventBusPayload",
+    KIND: "event-bus-payload",
+  },
+});