@blamejs/core 0.14.27 → 0.15.0

package/lib/guard-pdf.js

@@ -384,12 +384,7 @@ function sanitize(input, opts) {
     throw _err("pdf.bad-input", "sanitize requires metadata object");
   }
   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 || "pdf.refused",
-        "guardPdf.sanitize: " + issues[i].snippet);
-    }
-  }
+  gateContract.throwOnRefusalSeverity(issues, { errorClass: GuardPdfError, codePrefix: "pdf" });
   return input;
 }
 
@@ -449,69 +444,11 @@ function gate(opts) {
     });
 }
 
-/**
- * @primitive b.guardPdf.buildProfile
- * @signature b.guardPdf.buildProfile(opts)
- * @since     0.7.13
- * @status    stable
- * @related   b.guardPdf.compliancePosture, b.guardPdf.gate
- *
- * Resolve a named profile against the guard's PROFILES catalog and
- * return the merged options bag. Throws
- * `GuardPdfError("pdf.bad-profile")` on unknown name.
- *
- * @opts
- *   profile: "strict"|"balanced"|"permissive",
- *
- * @example
- *   var resolved = b.guardPdf.buildProfile({ profile: "strict" });
- *   resolved.javascriptPolicy;                           // → "reject"
- *   resolved.maxPageCount;                               // → 500
- */
-var buildProfile = gateContract.makeProfileBuilder(PROFILES);
-
-/**
- * @primitive  b.guardPdf.compliancePosture
- * @signature  b.guardPdf.compliancePosture(name)
- * @since      0.7.13
- * @status     stable
- * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardPdf.gate, b.guardPdf.buildProfile
- *
- * Return the option overlay for a named compliance posture
- * (`"hipaa"` / `"pci-dss"` / `"gdpr"` / `"soc2"`). Throws
- * `GuardPdfError("pdf.bad-posture")` on unknown name.
- *
- * @example
- *   var posture = b.guardPdf.compliancePosture("hipaa");
- *   posture.javascriptPolicy;                            // → "reject"
- *   posture.forensicSnippetBytes;                        // → 512
- */
-function compliancePosture(name) {
-  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
-    _err, "pdf");
-}
-
-var _pdfRulePacks = gateContract.makeRulePackLoader(GuardPdfError, "pdf");
-/**
- * @primitive b.guardPdf.loadRulePack
- * @signature b.guardPdf.loadRulePack(pack)
- * @since     0.7.13
- * @status    stable
- * @related   b.guardPdf.gate
- *
- * Register an operator-supplied rule pack with the guard-pdf
- * registry. Throws `GuardPdfError("pdf.bad-opt")` when `pack` is
- * missing or `pack.id` is not a non-empty string.
- *
- * @example
- *   var pack = b.guardPdf.loadRulePack({
- *     id: "kb-2026-pdf",
- *     extraMaxPageCount: 200,
- *   });
- *   pack.id;                                             // → "kb-2026-pdf"
- */
-var loadRulePack = _pdfRulePacks.load;
+// buildProfile / compliancePosture / loadRulePack are assembled by
+// gateContract.defineGuard below (makeProfileBuilder(PROFILES) /
+// lookupCompliancePosture(_, COMPLIANCE_POSTURES) / makeRulePackLoader).
+// Their wiki sections render from the single-sourced @abiTemplate blocks
+// in gate-contract.js, instantiated per guard by the page generator.
 
 /**
  * @primitive b.guardPdf.inspectMagic
@@ -535,35 +472,42 @@ function inspectMagic(bytes) {
   return _hasPdfMagic(bytes);
 }
 
-module.exports = {
-  // ---- guard-* family registry exports ----
-  NAME:                "pdf",
-  KIND:                "metadata",
-  INTEGRATION_FIXTURES: Object.freeze({
-    kind:              "metadata",
-    benignBytes:       Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]), // %PDF-1.7
-    hostileBytes:      Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]),
-    benignMetadata: {
-      bytes: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]),
-      hasJavaScript: false, hasOpenAction: false, hasLaunchAction: false,
-      hasEmbeddedFiles: false, isEncrypted: false, pageCount: 1,
-    },
-    hostileMetadata: {
-      bytes: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]),
-      // Hostile: JavaScript action — universal refuse (RCE class).
-      hasJavaScript: true,
-    },
-  }),
-  // ---- primitive surface ----
-  validate:            validate,
-  sanitize:            sanitize,
-  gate:                gate,
-  inspectMagic:        inspectMagic,
-  buildProfile:        buildProfile,
-  compliancePosture:   compliancePosture,
-  loadRulePack:        loadRulePack,
-  PROFILES:            PROFILES,
-  DEFAULTS:            DEFAULTS,
-  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
-  GuardPdfError:       GuardPdfError,
-};
+// ---- adaptive integration-test fixtures (consumed by layer-5 host harness) ----
+var INTEGRATION_FIXTURES = Object.freeze({
+  kind:              "metadata",
+  benignBytes:       Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]), // %PDF-1.7
+  hostileBytes:      Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]),
+  benignMetadata: {
+    bytes: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]),
+    hasJavaScript: false, hasOpenAction: false, hasLaunchAction: false,
+    hasEmbeddedFiles: false, isEncrypted: false, pageCount: 1,
+  },
+  hostileMetadata: {
+    bytes: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]),
+    // Hostile: JavaScript action — universal refuse (RCE class).
+    hasJavaScript: true,
+  },
+});
+
+// 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 / gate) and the pdf extra (inspectMagic)
+// passed through verbatim. KIND="metadata" is a custom kind, so the bespoke
+// `gate` (operator-feeds-metadata ctx.metadata reader) is REQUIRED and
+// carries the JavaScript / launch-action / embedded-file chain unchanged.
+module.exports = gateContract.defineGuard({
+  name:        "pdf",
+  kind:        "metadata",
+  errorClass:  GuardPdfError,
+  profiles:    PROFILES,
+  defaults:    DEFAULTS,
+  postures:    COMPLIANCE_POSTURES,
+  integrationFixtures: INTEGRATION_FIXTURES,
+  validate:    validate,
+  sanitize:    sanitize,
+  gate:        gate,
+  extra: {
+    inspectMagic: inspectMagic,
+  },
+});

package/lib/guard-pop3-command.js

@@ -74,11 +74,16 @@
  */
 
 var { defineClass } = require("./framework-error");
+var gateContract = require("./gate-contract");
 
 var GuardPop3CommandError = defineClass("GuardPop3CommandError", { alwaysPermanent: true });
 
 var DEFAULT_PROFILE = "strict";
 
+// COMPLIANCE_POSTURES is referenced by validate() below (posture → profile
+// name) and re-exported through defineParser; declared up top so validate
+// can read it before the module-exports assembly at the foot of the file.
+
 var PROFILES = Object.freeze({
   strict: {
     maxLineBytes:       255,                                                                         // RFC 2449 §4 cap
@@ -103,12 +108,7 @@ var PROFILES = Object.freeze({
   },
 });
 
-var COMPLIANCE_POSTURES = Object.freeze({
-  hipaa:     "strict",
-  "pci-dss": "strict",
-  gdpr:      "strict",
-  soc2:      "strict",
-});
+var COMPLIANCE_POSTURES = gateContract.ALL_STRICT_POSTURES;
 
 // POP3 verbs per RFC 1939 §6 + RFC 2449 §5 + RFC 2595 §4 + RFC 5034.
 var KNOWN_VERBS = Object.freeze({
@@ -290,28 +290,18 @@ function validate(line, opts) {
   return { verb: verb, args: args };
 }
 
-/**
- * @primitive b.guardPop3Command.compliancePosture
- * @signature b.guardPop3Command.compliancePosture(posture)
- * @since     0.9.52
- * @status    stable
- *
- * Return the effective profile for a compliance posture, or `null`
- * for unknown names.
- *
- * @example
- *   b.guardPop3Command.compliancePosture("hipaa");   // → "strict"
- */
-function compliancePosture(posture) {
-  return COMPLIANCE_POSTURES[posture] || null;
-}
-
-module.exports = {
-  validate:                 validate,
-  compliancePosture:        compliancePosture,
-  PROFILES:                 PROFILES,
-  COMPLIANCE_POSTURES:      COMPLIANCE_POSTURES,
-  KNOWN_VERBS:              KNOWN_VERBS,
-  ZERO_ARG_VERBS:           ZERO_ARG_VERBS,
-  GuardPop3CommandError:    GuardPop3CommandError,
-};
+// 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:       "pop3-command",
+  entry:      validate,
+  errorClass: GuardPop3CommandError,
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  extra: {
+    KNOWN_VERBS:    KNOWN_VERBS,
+    ZERO_ARG_VERBS: ZERO_ARG_VERBS,
+  },
+});

package/lib/guard-posture-chain.js

@@ -26,6 +26,7 @@
  */
 
 var { defineClass } = require("./framework-error");
+var gateContract = require("./gate-contract");
 
 var GuardPostureChainError = defineClass("GuardPostureChainError", { alwaysPermanent: true });
 
@@ -37,11 +38,14 @@ var PROFILES = Object.freeze({
   permissive: { maxHops: 128, maxHopBytes: 256, maxRegimes: 64 },
 });
 
-var COMPLIANCE_POSTURES = Object.freeze({
-  hipaa:     "strict",
-  "pci-dss": "strict",
-  gdpr:      "strict",
-  soc2:      "strict",
+var COMPLIANCE_POSTURES = gateContract.ALL_STRICT_POSTURES;
+
+var _resolveProfile = gateContract.makeProfileResolver({
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  defaults:   DEFAULT_PROFILE,
+  errorClass: GuardPostureChainError,
+  codePrefix: "posture-chain",
 });
 
 /**
@@ -161,41 +165,19 @@ function validate(envelope, opts) {
   return envelope;
 }
 
-/**
- * @primitive b.guardPostureChain.compliancePosture
- * @signature b.guardPostureChain.compliancePosture(posture)
- * @since     0.9.28
- * @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.guardPostureChain.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 GuardPostureChainError("posture-chain/bad-profile",
-      "guardPostureChain: unknown profile '" + p + "'");
-  }
-  return p;
-}
+// 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 = {
-  validate:                  validate,
-  compliancePosture:         compliancePosture,
-  PROFILES:                  PROFILES,
-  COMPLIANCE_POSTURES:       COMPLIANCE_POSTURES,
-  GuardPostureChainError:    GuardPostureChainError,
-  NAME:                      "postureChain",
-  KIND:                      "posture-chain",
-};
+module.exports = gateContract.defineParser({
+  name:       "posture-chain",
+  entry:      validate,
+  errorClass: GuardPostureChainError,
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  extra: {
+    NAME: "postureChain",
+    KIND: "posture-chain",
+  },
+});

package/lib/guard-regex.js

@@ -450,12 +450,9 @@ function sanitize(input, opts) {
     throw _err("regex.bad-input", "sanitize requires string input");
   }
   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 || "regex.refused",
-        "guardRegex.sanitize: " + issues[i].snippet);
-    }
-  }
+  gateContract.throwOnRefusalSeverity(issues, {
+    errorClass: GuardRegexError, codePrefix: "regex",
+  });
   return input;
 }
 
@@ -527,106 +524,35 @@ function gate(opts) {
     });
 }
 
-/**
- * @primitive  b.guardRegex.buildProfile
- * @signature  b.guardRegex.buildProfile(opts)
- * @since      0.7.13
- * @status     stable
- * @related    b.guardRegex.gate, b.guardRegex.compliancePosture
- *
- * Compose a derived guardRegex 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. Used to keep operator-defined profiles traceable to a
- * baseline rather than re-typing every key.
- *
- * @opts
- *   extends: string|string[],   // base profile name(s) to compose
- *   ...:     any guardRegex key, // inline override of resolved keys
- *
- * @example
- *   var custom = b.guardRegex.buildProfile({
- *     extends: "balanced",
- *     maxBoundedRepeat: 50,
- *     boundedRepeatPolicy: "reject",
- *   });
- *   custom.maxBoundedRepeat;                           // → 50
- *   custom.nestedQuantPolicy;                          // → "reject"
- */
-var buildProfile = gateContract.makeProfileBuilder(PROFILES);
-
-/**
- * @primitive  b.guardRegex.compliancePosture
- * @signature  b.guardRegex.compliancePosture(name)
- * @since      0.7.13
- * @status     stable
- * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardRegex.gate, b.guardRegex.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
- * `GuardRegexError("regex.bad-posture")` on unknown name.
- *
- * @example
- *   var posture = b.guardRegex.compliancePosture("hipaa");
- *   posture.nestedQuantPolicy;                         // → "reject"
- *   posture.forensicSnippetBytes;                      // → 256
- */
-function compliancePosture(name) {
-  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
-    _err, "regex");
-}
+// buildProfile / compliancePosture / loadRulePack are assembled by
+// gateContract.defineGuard below (makeProfileBuilder(PROFILES) /
+// lookupCompliancePosture(_, COMPLIANCE_POSTURES) / makeRulePackLoader).
+// Their wiki sections render from the single-sourced @abiTemplate blocks
+// in gate-contract.js, instantiated per guard by the page generator.
 
-var _regexRulePacks = gateContract.makeRulePackLoader(GuardRegexError, "regex");
-/**
- * @primitive  b.guardRegex.loadRulePack
- * @signature  b.guardRegex.loadRulePack(pack)
- * @since      0.7.13
- * @status     stable
- * @related    b.guardRegex.gate
- *
- * Register an operator-supplied rule pack with the guardRegex
- * 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 `GuardRegexError("regex.bad-opt")` when `pack`
- * is missing or `pack.id` is not a non-empty string.
- *
- * @example
- *   var pack = b.guardRegex.loadRulePack({
- *     id: "no-empty-alternation",
- *     rules: [
- *       { id: "empty-alt", severity: "high",
- *         detect: function (pattern) { return /\(\|/.test(pattern); },
- *         reason: "alternation with empty branch" },
- *     ],
- *   });
- *   pack.id;                                           // → "no-empty-alternation"
- */
-var loadRulePack = _regexRulePacks.load;
+// ---- adaptive integration-test fixtures (consumed by layer-5 host harness) ----
+var INTEGRATION_FIXTURES = Object.freeze({
+  kind:              "identifier",
+  benignBytes:       Buffer.from("^[a-z]+$", "utf8"),
+  hostileBytes:      Buffer.from("(a+)+b", "utf8"),
+  benignIdentifier:  "^[a-z]+$",
+  hostileIdentifier: "(a+)+b",
+});
 
-module.exports = {
-  // ---- guard-* family registry exports ----
-  NAME:                "regex",
-  KIND:                "identifier",
-  INTEGRATION_FIXTURES: Object.freeze({
-    kind:              "identifier",
-    benignBytes:       Buffer.from("^[a-z]+$", "utf8"),
-    hostileBytes:      Buffer.from("(a+)+b", "utf8"),
-    benignIdentifier:  "^[a-z]+$",
-    hostileIdentifier: "(a+)+b",
-  }),
-  // ---- primitive surface ----
-  validate:            validate,
-  sanitize:            sanitize,
-  gate:                gate,
-  buildProfile:        buildProfile,
-  compliancePosture:   compliancePosture,
-  loadRulePack:        loadRulePack,
-  PROFILES:            PROFILES,
-  DEFAULTS:            DEFAULTS,
-  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
-  GuardRegexError:     GuardRegexError,
-};
+// 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 / gate). The bespoke `gate` carries
+// guardRegex's ctx.identifier || ctx.pattern dispatch unchanged.
+module.exports = gateContract.defineGuard({
+  name:        "regex",
+  kind:        "identifier",
+  errorClass:  GuardRegexError,
+  profiles:    PROFILES,
+  defaults:    DEFAULTS,
+  postures:    COMPLIANCE_POSTURES,
+  integrationFixtures: INTEGRATION_FIXTURES,
+  validate:    validate,
+  sanitize:    sanitize,
+  gate:        gate,
+});

package/lib/guard-saga-config.js

@@ -16,6 +16,7 @@
  */
 
 var { defineClass } = require("./framework-error");
+var gateContract = require("./gate-contract");
 
 var GuardSagaConfigError = defineClass("GuardSagaConfigError", { alwaysPermanent: true });
 
@@ -27,11 +28,14 @@ var PROFILES = Object.freeze({
   permissive: { maxSteps: 512,  maxNameBytes: 256 },
 });
 
-var COMPLIANCE_POSTURES = Object.freeze({
-  hipaa:     "strict",
-  "pci-dss": "strict",
-  gdpr:      "strict",
-  soc2:      "strict",
+var COMPLIANCE_POSTURES = gateContract.ALL_STRICT_POSTURES;
+
+var _resolveProfile = gateContract.makeProfileResolver({
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  defaults:   DEFAULT_PROFILE,
+  errorClass: GuardSagaConfigError,
+  codePrefix: "saga-config",
 });
 
 /**
@@ -117,41 +121,19 @@ function validate(config, opts) {
   return config;
 }
 
-/**
- * @primitive b.guardSagaConfig.compliancePosture
- * @signature b.guardSagaConfig.compliancePosture(posture)
- * @since     0.9.27
- * @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.guardSagaConfig.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 GuardSagaConfigError("saga-config/bad-profile",
-      "guardSagaConfig: unknown profile '" + p + "'");
-  }
-  return p;
-}
+// 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 = {
-  validate:                 validate,
-  compliancePosture:        compliancePosture,
-  PROFILES:                 PROFILES,
-  COMPLIANCE_POSTURES:      COMPLIANCE_POSTURES,
-  GuardSagaConfigError:     GuardSagaConfigError,
-  NAME:                     "sagaConfig",
-  KIND:                     "saga-config",
-};
+module.exports = gateContract.defineParser({
+  name:       "saga-config",
+  entry:      validate,
+  errorClass: GuardSagaConfigError,
+  profiles:   PROFILES,
+  postures:   COMPLIANCE_POSTURES,
+  extra: {
+    NAME: "sagaConfig",
+    KIND: "saga-config",
+  },
+});