@blamejs/core 0.7.51 → 0.7.61

package/lib/guard-pdf.js

@@ -0,0 +1,345 @@
+"use strict";
+/**
+ * guard-pdf — PDF identifier-safety primitive (b.guardPdf).
+ *
+ * Validates PDF inputs without vendoring a full parser. Operators
+ * bring their own PDF library (pdf-lib, pdfjs-dist, vendored mupdf)
+ * and feed structural metadata to the guard for policy enforcement.
+ * KIND="metadata" — consumes `ctx.metadata` shape: `{ bytes?,
+ * hasJavaScript?, hasOpenAction?, hasEmbeddedFiles?, hasLaunchAction?,
+ * isEncrypted?, pageCount?, embeddedFileCount? }`.
+ *
+ * Threat catalog:
+ *   - Magic-byte missing or wrong — `%PDF-` header check.
+ *   - JavaScript action — `/JS` / `/JavaScript` annotation triggers
+ *     RCE in vulnerable readers (CVE class — Adobe / Foxit / nitro).
+ *   - OpenAction trigger — `/OpenAction` runs on document open;
+ *     when paired with JavaScript or LaunchAction it's a drive-by.
+ *   - LaunchAction — `/Launch` action invokes external program;
+ *     refused at every profile.
+ *   - Embedded files — `/EmbeddedFile` may carry executable payloads.
+ *   - Encrypted PDF refuse — many AV / sandbox tools can't scan;
+ *     operators may want to refuse encrypted PDFs.
+ *   - Oversized — bytes / page count / embedded-file count.
+ *   - Polyglot — buffer carries non-PDF magic-byte signatures
+ *     (operator-supplied via `polyglotDetected: true`).
+ *
+ *   var rv = b.guardPdf.validate(metadata, { profile: "strict" });
+ *   var g  = b.guardPdf.gate({ profile: "strict" });
+ */
+
+var lazyRequire = require("./lazy-require");
+var gateContract = require("./gate-contract");
+var C = require("./constants");
+var numericBounds = require("./numeric-bounds");
+var { GuardPdfError } = require("./framework-error");
+
+var observability = lazyRequire(function () { return require("./observability"); });
+void observability;
+
+var _err = GuardPdfError.factory;
+
+// PDF magic bytes — `%PDF-` (5 bytes).
+var PDF_MAGIC = [0x25, 0x50, 0x44, 0x46, 0x2D];
+
+// ---- Profile presets ----
+
+var PROFILES = Object.freeze({
+  "strict": {
+    magicPolicy:              "reject",
+    javascriptPolicy:          "reject",
+    openActionPolicy:          "reject",
+    launchActionPolicy:        "reject",
+    embeddedFilePolicy:        "reject",
+    encryptedPolicy:           "reject",
+    polyglotPolicy:            "reject",
+    pageCountPolicy:           "reject",
+    embeddedFileCountPolicy:   "reject",
+    maxPageCount:              500,                                              // allow:raw-byte-literal — page-count ceiling
+    maxEmbeddedFileCount:      0,                                                // allow:raw-byte-literal — strict refuses any embedded file
+    maxBytes:                  C.BYTES.mib(64),
+    maxRuntimeMs:              C.TIME.seconds(5),
+  },
+  "balanced": {
+    magicPolicy:              "reject",
+    javascriptPolicy:          "reject",                                         // RCE class — refused at every profile
+    openActionPolicy:          "audit",
+    launchActionPolicy:        "reject",                                         // RCE class — refused at every profile
+    embeddedFilePolicy:        "audit",
+    encryptedPolicy:           "audit",
+    polyglotPolicy:            "reject",                                         // polyglot refused at every profile
+    pageCountPolicy:           "audit",
+    embeddedFileCountPolicy:   "audit",
+    maxPageCount:              5000,                                             // allow:raw-byte-literal — page-count ceiling
+    maxEmbeddedFileCount:      10,                                               // allow:raw-byte-literal — embedded file ceiling
+    maxBytes:                  C.BYTES.mib(128),
+    maxRuntimeMs:              C.TIME.seconds(5),
+  },
+  "permissive": {
+    magicPolicy:              "audit",
+    javascriptPolicy:          "reject",                                          // RCE class — refused at every profile
+    openActionPolicy:          "audit",
+    launchActionPolicy:        "reject",                                          // RCE class — refused at every profile
+    embeddedFilePolicy:        "audit",
+    encryptedPolicy:           "allow",
+    polyglotPolicy:            "reject",                                          // polyglot refused at every profile
+    pageCountPolicy:           "audit",
+    embeddedFileCountPolicy:   "audit",
+    maxPageCount:              50000,                                            // allow:raw-byte-literal — page-count ceiling
+    maxEmbeddedFileCount:      100,                                              // allow:raw-byte-literal — embedded file ceiling
+    maxBytes:                  C.BYTES.mib(512),
+    maxRuntimeMs:              C.TIME.seconds(5),
+  },
+});
+
+var DEFAULTS = Object.freeze(Object.assign({}, PROFILES["strict"], {
+  mode: "enforce",
+}));
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  "hipaa":   Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(512),
+  }),
+  "pci-dss": Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(512),
+  }),
+  "gdpr":    Object.assign({}, PROFILES["balanced"], {
+    forensicSnippetBytes: C.BYTES.bytes(256),
+  }),
+  "soc2":    Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(1024),
+  }),
+});
+
+function _resolveOpts(opts) {
+  return gateContract.resolveProfileAndPosture(opts, {
+    profiles:           PROFILES,
+    compliancePostures: COMPLIANCE_POSTURES,
+    defaults:           DEFAULTS,
+    errorClass:         GuardPdfError,
+    errCodePrefix:      "pdf",
+  });
+}
+
+function _hasPdfMagic(buf) {
+  if (!buf || typeof buf.length !== "number" || buf.length < PDF_MAGIC.length) {
+    return false;
+  }
+  for (var i = 0; i < PDF_MAGIC.length; i += 1) {
+    if (buf[i] !== PDF_MAGIC[i]) return false;
+  }
+  return true;
+}
+
+function _detectIssues(metadata, opts) {
+  var issues = [];
+  if (!metadata || typeof metadata !== "object") {
+    return [{ kind: "bad-input", severity: "high",
+              ruleId: "pdf.bad-input",
+              snippet: "pdf metadata is not an object" }];
+  }
+
+  var bytes = metadata.bytes;
+  if (bytes && typeof bytes.length === "number" && bytes.length > opts.maxBytes) {
+    return [{ kind: "pdf-cap", severity: "high",
+              ruleId: "pdf.pdf-cap",
+              snippet: "pdf bytes exceed maxBytes " + opts.maxBytes }];
+  }
+
+  // Magic check.
+  if (bytes && opts.magicPolicy !== "allow" && !_hasPdfMagic(bytes)) {
+    issues.push({
+      kind: "magic-missing",
+      severity: opts.magicPolicy === "reject" ? "high" : "warn",
+      ruleId: "pdf.magic-missing",
+      snippet: "buffer does not start with `%PDF-` magic bytes",
+    });
+  }
+
+  // Polyglot — operator-supplied flag.
+  if (metadata.polyglotDetected === true && opts.polyglotPolicy !== "allow") {
+    issues.push({
+      kind: "polyglot", severity: "critical",
+      ruleId: "pdf.polyglot",
+      snippet: "operator metadata flags this PDF as polyglot — refused " +
+               "(buffer carries non-PDF magic-byte signatures)",
+    });
+  }
+
+  // JavaScript action — RCE class.
+  if (metadata.hasJavaScript === true && opts.javascriptPolicy !== "allow") {
+    issues.push({
+      kind: "javascript-action", severity: "critical",
+      ruleId: "pdf.javascript-action",
+      snippet: "PDF carries `/JS` / `/JavaScript` action — RCE class " +
+               "in vulnerable readers (Adobe / Foxit / nitro CVEs)",
+    });
+  }
+
+  // LaunchAction — universally refused.
+  if (metadata.hasLaunchAction === true &&
+      opts.launchActionPolicy !== "allow") {
+    issues.push({
+      kind: "launch-action", severity: "critical",
+      ruleId: "pdf.launch-action",
+      snippet: "PDF carries `/Launch` action — invokes external program",
+    });
+  }
+
+  // OpenAction — runs on document open.
+  if (metadata.hasOpenAction === true &&
+      opts.openActionPolicy !== "allow") {
+    issues.push({
+      kind: "open-action",
+      severity: opts.openActionPolicy === "reject" ? "high" : "warn",
+      ruleId: "pdf.open-action",
+      snippet: "PDF carries `/OpenAction` — runs on document open " +
+               "(drive-by class when paired with JavaScript / Launch)",
+    });
+  }
+
+  // Embedded files.
+  if (metadata.hasEmbeddedFiles === true &&
+      opts.embeddedFilePolicy !== "allow") {
+    issues.push({
+      kind: "embedded-file",
+      severity: opts.embeddedFilePolicy === "reject" ? "high" : "warn",
+      ruleId: "pdf.embedded-file",
+      snippet: "PDF carries embedded files — may smuggle executable " +
+               "payloads",
+    });
+  }
+  if (typeof metadata.embeddedFileCount === "number" &&
+      opts.embeddedFileCountPolicy !== "allow" &&
+      metadata.embeddedFileCount > opts.maxEmbeddedFileCount) {
+    issues.push({
+      kind: "embedded-file-count",
+      severity: opts.embeddedFileCountPolicy === "reject" ? "high" : "warn",
+      ruleId: "pdf.embedded-file-count",
+      snippet: "embedded-file count " + metadata.embeddedFileCount +
+               " exceeds maxEmbeddedFileCount " + opts.maxEmbeddedFileCount,
+    });
+  }
+
+  // Encrypted.
+  if (metadata.isEncrypted === true && opts.encryptedPolicy !== "allow") {
+    issues.push({
+      kind: "encrypted",
+      severity: opts.encryptedPolicy === "reject" ? "high" : "warn",
+      ruleId: "pdf.encrypted",
+      snippet: "PDF is encrypted — many AV / sandbox tools can't scan " +
+               "encrypted documents",
+    });
+  }
+
+  // Page count.
+  if (typeof metadata.pageCount === "number" &&
+      opts.pageCountPolicy !== "allow" &&
+      metadata.pageCount > opts.maxPageCount) {
+    issues.push({
+      kind: "page-count",
+      severity: opts.pageCountPolicy === "reject" ? "high" : "warn",
+      ruleId: "pdf.page-count",
+      snippet: "page count " + metadata.pageCount + " exceeds " +
+               "maxPageCount " + opts.maxPageCount,
+    });
+  }
+
+  return issues;
+}
+
+function validate(input, opts) {
+  opts = _resolveOpts(opts);
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["maxBytes", "maxPageCount"],
+    "guardPdf.validate", GuardPdfError, "pdf.bad-opt");
+  // maxEmbeddedFileCount allows 0 (strict refuses all embedded files);
+  // skip the positive-finite check.
+  return gateContract.aggregateIssues(_detectIssues(input, opts));
+}
+
+function sanitize(input, opts) {
+  opts = _resolveOpts(opts);
+  if (!input || typeof input !== "object") {
+    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);
+    }
+  }
+  return input;
+}
+
+function gate(opts) {
+  opts = _resolveOpts(opts);
+  return gateContract.buildGuardGate(
+    opts.name || "guardPdf:" + (opts.profile || "default"),
+    opts,
+    async function (ctx) {
+      var meta = ctx && (ctx.metadata || ctx.pdfMetadata);
+      if (!meta) return { ok: true, action: "serve" };
+      var rv = validate(meta, 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 };
+    });
+}
+
+var buildProfile = gateContract.makeProfileBuilder(PROFILES);
+
+function compliancePosture(name) {
+  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
+    _err, "pdf");
+}
+
+var _pdfRulePacks = gateContract.makeRulePackLoader(GuardPdfError, "pdf");
+var loadRulePack = _pdfRulePacks.load;
+
+// Operator helper: confirm bytes carry the PDF magic header.
+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,
+};

package/lib/guard-regex.js

@@ -0,0 +1,287 @@
+"use strict";
+/**
+ * guard-regex — Regex pattern identifier-safety primitive
+ * (b.guardRegex).
+ *
+ * Validates user-supplied regex pattern strings for catastrophic-
+ * backtracking (ReDoS) shapes BEFORE compilation. KIND="identifier" —
+ * consumes ctx.identifier (or ctx.pattern).
+ *
+ * Threat catalog:
+ *   - Nested quantifiers — `(a+)+`, `(a*)+`, `(.+)+`. The classic
+ *     ReDoS shape. CVE-2024-21538 (cross-spawn) and CVE-2022-25929
+ *     (chartjs-adapter-luxon) are recent prominent examples.
+ *   - Quantifier-after-grouped-quantifier — `(a|b)+\w*` style strings.
+ *   - Alternation overlap with quantifier — `(\d|\d{2})*`.
+ *   - Bounded quantifiers with very large counts — operator-tunable
+ *     via maxBoundedRepeat.
+ *   - Excessive pattern length — defense against parser DoS.
+ *   - Lookbehind / lookahead with quantifiers inside.
+ *   - BIDI / null / control / zero-width universal refuse.
+ *
+ *   var rv = b.guardRegex.validate("(a+)+b", { profile: "strict" });
+ *   var g  = b.guardRegex.gate({ profile: "strict" });
+ */
+
+var codepointClass = require("./codepoint-class");
+var lazyRequire = require("./lazy-require");
+var gateContract = require("./gate-contract");
+var C = require("./constants");
+var numericBounds = require("./numeric-bounds");
+var { GuardRegexError } = require("./framework-error");
+
+var observability = lazyRequire(function () { return require("./observability"); });
+void observability;
+
+var _err = GuardRegexError.factory;
+
+// Nested-quantifier detector: `(group)+`-style followed by another
+// quantifier or repetition that operates on the grouped match.
+var NESTED_QUANT_RE = /\([^()]*[*+?][^()]*\)\s*[*+?{]/;
+
+// Alternation-with-quantifier — `(a|b|...)+`, `(a|b)*`.
+var ALTERNATION_QUANT_RE = /\([^()]*\|[^()]*\)\s*[*+]/;
+
+// Bounded repetition — captures the upper bound when present.
+var BOUNDED_REPEAT_RE = /\{(\d+)(?:,(\d*))?\}/g;
+
+// Lookaround with internal quantifier — `(?=.*+)`, `(?!a*)`.
+var LOOKAROUND_QUANT_RE = /\(\?[=!<][^()]*[*+]/;
+
+// ---- Profile presets ----
+
+var PROFILES = Object.freeze({
+  "strict": {
+    bidiPolicy:               "reject",
+    controlPolicy:             "reject",
+    nullBytePolicy:            "reject",
+    zeroWidthPolicy:           "reject",
+    nestedQuantPolicy:         "reject",
+    alternationQuantPolicy:    "reject",
+    boundedRepeatPolicy:       "reject",
+    lookaroundQuantPolicy:     "reject",
+    maxBoundedRepeat:          100,                                              // allow:raw-byte-literal — bounded repeat ceiling
+    maxPatternBytes:           C.BYTES.kib(1),
+    maxBytes:                  C.BYTES.kib(1),
+    maxRuntimeMs:              C.TIME.seconds(2),
+  },
+  "balanced": {
+    bidiPolicy:               "reject",
+    controlPolicy:             "reject",
+    nullBytePolicy:            "reject",
+    zeroWidthPolicy:           "reject",
+    nestedQuantPolicy:         "reject",
+    alternationQuantPolicy:    "audit",
+    boundedRepeatPolicy:       "audit",
+    lookaroundQuantPolicy:     "audit",
+    maxBoundedRepeat:          1000,                                             // allow:raw-byte-literal — bounded repeat ceiling
+    maxPatternBytes:           C.BYTES.kib(2),
+    maxBytes:                  C.BYTES.kib(2),
+    maxRuntimeMs:              C.TIME.seconds(2),
+  },
+  "permissive": {
+    bidiPolicy:               "reject",                                          // BIDI refused at every profile
+    controlPolicy:             "reject",                                          // controls refused at every profile
+    nullBytePolicy:            "reject",                                          // null refused at every profile
+    zeroWidthPolicy:           "reject",                                          // zero-width refused at every profile
+    nestedQuantPolicy:         "reject",                                          // canonical ReDoS class refused at every profile
+    alternationQuantPolicy:    "allow",
+    boundedRepeatPolicy:       "audit",
+    lookaroundQuantPolicy:     "audit",
+    maxBoundedRepeat:          10000,                                            // allow:raw-byte-literal — bounded repeat ceiling
+    maxPatternBytes:           C.BYTES.kib(8),
+    maxBytes:                  C.BYTES.kib(8),
+    maxRuntimeMs:              C.TIME.seconds(2),
+  },
+});
+
+var DEFAULTS = Object.freeze(Object.assign({}, PROFILES["strict"], {
+  mode: "enforce",
+}));
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  "hipaa":   Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(256),
+  }),
+  "pci-dss": Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(256),
+  }),
+  "gdpr":    Object.assign({}, PROFILES["balanced"], {
+    forensicSnippetBytes: C.BYTES.bytes(128),
+  }),
+  "soc2":    Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(512),
+  }),
+});
+
+function _resolveOpts(opts) {
+  return gateContract.resolveProfileAndPosture(opts, {
+    profiles:           PROFILES,
+    compliancePostures: COMPLIANCE_POSTURES,
+    defaults:           DEFAULTS,
+    errorClass:         GuardRegexError,
+    errCodePrefix:      "regex",
+  });
+}
+
+function _detectIssues(input, opts) {
+  var issues = [];
+  if (typeof input !== "string") {
+    return [{ kind: "bad-input", severity: "high",
+              ruleId: "regex.bad-input",
+              snippet: "regex pattern is not a string" }];
+  }
+  if (input.length === 0) {
+    return [{ kind: "empty", severity: "high",
+              ruleId: "regex.empty",
+              snippet: "regex pattern is empty" }];
+  }
+  if (Buffer.byteLength(input, "utf8") > opts.maxPatternBytes) {
+    return [{ kind: "pattern-cap", severity: "high",
+              ruleId: "regex.pattern-cap",
+              snippet: "regex pattern exceeds maxPatternBytes " +
+                       opts.maxPatternBytes }];
+  }
+
+  var charThreats = codepointClass.detectCharThreats(input, opts, "regex");
+  for (var ci = 0; ci < charThreats.length; ci += 1) issues.push(charThreats[ci]);
+
+  if (opts.nestedQuantPolicy !== "allow" && NESTED_QUANT_RE.test(input)) {       // allow:regex-no-length-cap — input bounded by maxPatternBytes
+    issues.push({
+      kind: "nested-quantifier", severity: "critical",
+      ruleId: "regex.nested-quantifier",
+      snippet: "pattern contains nested-quantifier shape (e.g. " +
+               "`(a+)+`) — canonical ReDoS catastrophic-backtracking " +
+               "class (CVE-2024-21538 cross-spawn / CVE-2022-25929)",
+    });
+  }
+
+  if (opts.alternationQuantPolicy !== "allow" &&
+      ALTERNATION_QUANT_RE.test(input)) {                                        // allow:regex-no-length-cap — input bounded by maxPatternBytes
+    issues.push({
+      kind: "alternation-quantifier",
+      severity: opts.alternationQuantPolicy === "reject" ? "high" : "warn",
+      ruleId: "regex.alternation-quantifier",
+      snippet: "pattern contains alternation-with-quantifier shape " +
+               "(e.g. `(a|b)+`) — alternation overlap may amplify " +
+               "search paths",
+    });
+  }
+
+  if (opts.lookaroundQuantPolicy !== "allow" &&
+      LOOKAROUND_QUANT_RE.test(input)) {                                         // allow:regex-no-length-cap — input bounded by maxPatternBytes
+    issues.push({
+      kind: "lookaround-quantifier",
+      severity: opts.lookaroundQuantPolicy === "reject" ? "high" : "warn",
+      ruleId: "regex.lookaround-quantifier",
+      snippet: "pattern contains quantifier inside lookaround " +
+               "(`(?=.*+)`) — catastrophic in some engines",
+    });
+  }
+
+  if (opts.boundedRepeatPolicy !== "allow") {
+    BOUNDED_REPEAT_RE.lastIndex = 0;
+    var match;
+    while ((match = BOUNDED_REPEAT_RE.exec(input)) !== null) {                   // allow:regex-no-length-cap — input bounded by maxPatternBytes
+      var lower = parseInt(match[1], 10);                                        // allow:raw-byte-literal — base-10 radix
+      var upper = match[2] === undefined ? lower :
+                  match[2] === "" ? Infinity : parseInt(match[2], 10);           // allow:raw-byte-literal — base-10 radix
+      var ceiling = (upper === Infinity || upper > lower) ? upper : lower;
+      if (ceiling > opts.maxBoundedRepeat) {
+        issues.push({
+          kind: "bounded-repeat-cap",
+          severity: opts.boundedRepeatPolicy === "reject" ? "high" : "warn",
+          ruleId: "regex.bounded-repeat-cap",
+          snippet: "bounded-repeat `" + match[0] + "` upper bound " +
+                   (ceiling === Infinity ? "unbounded" : ceiling) +
+                   " exceeds maxBoundedRepeat " + opts.maxBoundedRepeat,
+        });
+        break;
+      }
+    }
+  }
+
+  return issues;
+}
+
+function validate(input, opts) {
+  opts = _resolveOpts(opts);
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["maxBytes", "maxPatternBytes", "maxBoundedRepeat"],
+    "guardRegex.validate", GuardRegexError, "regex.bad-opt");
+  return gateContract.aggregateIssues(_detectIssues(input, opts));
+}
+
+function sanitize(input, opts) {
+  opts = _resolveOpts(opts);
+  if (typeof input !== "string") {
+    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);
+    }
+  }
+  return input;
+}
+
+function gate(opts) {
+  opts = _resolveOpts(opts);
+  return gateContract.buildGuardGate(
+    opts.name || "guardRegex:" + (opts.profile || "default"),
+    opts,
+    async function (ctx) {
+      var pattern = ctx && (ctx.identifier || ctx.pattern);
+      if (pattern === undefined || pattern === null) {
+        return { ok: true, action: "serve" };
+      }
+      var rv = validate(pattern, 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 };
+    });
+}
+
+var buildProfile = gateContract.makeProfileBuilder(PROFILES);
+
+function compliancePosture(name) {
+  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
+    _err, "regex");
+}
+
+var _regexRulePacks = gateContract.makeRulePackLoader(GuardRegexError, "regex");
+var loadRulePack = _regexRulePacks.load;
+
+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,
+};