@blamejs/core 0.8.43 → 0.8.50

package/lib/guard-pdf.js

@@ -1,31 +1,71 @@
 "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" });
+ * @module b.guardPdf
+ * @nav    Guards
+ * @title  Guard Pdf
+ *
+ * @intro
+ *   PDF content-safety guard — refuses RCE-class PDF features without
+ *   vendoring a parser. Operators bring their own PDF library
+ *   (pdf-lib, pdfjs-dist, vendored mupdf) and feed structural metadata
+ *   to the guard. `KIND="metadata"` — consumes `ctx.metadata` shape
+ *   `{ bytes?, hasJavaScript?, hasOpenAction?, hasEmbeddedFiles?,
+ *   hasLaunchAction?, isEncrypted?, pageCount?, embeddedFileCount?,
+ *   polyglotDetected? }`.
+ *
+ *   JavaScript exec refusal: `/JS` and `/JavaScript` annotations
+ *   trigger RCE in vulnerable readers (the Adobe / Foxit / nitro CVE
+ *   class). `metadata.hasJavaScript === true` is refused under every
+ *   profile (`javascriptPolicy: "reject"` in strict / balanced /
+ *   permissive). The framework refuses to negotiate on this — there
+ *   is no audit-only path for executable JavaScript inside a PDF.
+ *
+ *   Embedded files refusal: `/EmbeddedFile` entries may smuggle
+ *   executable payloads inside an otherwise-benign-looking PDF.
+ *   `strict` refuses any embedded file (`maxEmbeddedFileCount: 0`);
+ *   `balanced` audits up to 10; `permissive` audits up to 100.
+ *
+ *   OpenAction refusal: `/OpenAction` runs on document open. Standalone
+ *   it's a navigation hint; paired with JavaScript or LaunchAction it's
+ *   a drive-by trigger. `strict` refuses; `balanced` / `permissive`
+ *   audit. JavaScript / LaunchAction are refused independently so the
+ *   pairing can't slip through.
+ *
+ *   GoTo / Launch refusal: `/Launch` actions invoke an external
+ *   program (the historical "open this .exe attached to the PDF"
+ *   class). Refused under every profile (`launchActionPolicy:
+ *   "reject"`). The framework keeps the exec surface closed.
+ *
+ *   Stream / object caps: `maxPageCount` (strict 500, balanced 5 000,
+ *   permissive 50 000), `maxBytes` (strict 64 MiB, balanced 128 MiB,
+ *   permissive 512 MiB), `maxEmbeddedFileCount` (strict 0, balanced
+ *   10, permissive 100). Operator-supplied — the operator's parser
+ *   reports the structural counts; the guard refuses on excess.
+ *
+ *   Magic-byte check: `%PDF-` header (5 bytes `25 50 44 46 2D`).
+ *   Missing magic flagged under `strict` / `balanced` (the operator
+ *   may be feeding non-PDF bytes through the wrong gate).
+ *
+ *   Polyglot rejection: when the operator's parser flags the buffer
+ *   as polyglot (`polyglotDetected: true`), the guard refuses under
+ *   every profile (`polyglotPolicy: "reject"`).
+ *
+ *   Encrypted-PDF posture: many AV / sandbox tools can't scan
+ *   encrypted documents. `strict` refuses; `balanced` audits;
+ *   `permissive` allows.
+ *
+ *   Operator-feeds-metadata pattern: the gate trusts the metadata
+ *   object the operator's parser reports. The framework's no-deps
+ *   stance argues against shipping a vendored PDF parser; the
+ *   operator's parser is the ground truth and the guard enforces the
+ *   policy boundary.
+ *
+ *   Profiles `strict` / `balanced` / `permissive` and compliance
+ *   postures `hipaa` / `pci-dss` / `gdpr` / `soc2` overlay on the
+ *   profile baseline.
+ *
+ * @card
+ *   PDF content-safety guard — refuses RCE-class PDF features without vendoring a parser.
  */
 
 var lazyRequire = require("./lazy-require");
@@ -248,6 +288,57 @@ function _detectIssues(metadata, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardPdf.validate
+ * @signature  b.guardPdf.validate(input, opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardPdf.sanitize, b.guardPdf.gate, b.guardPdf.inspectMagic
+ *
+ * Inspect a PDF metadata bag `{ bytes?, hasJavaScript?, hasOpenAction?,
+ * hasLaunchAction?, hasEmbeddedFiles?, isEncrypted?, pageCount?,
+ * embeddedFileCount?, polyglotDetected? }` and return `{ ok, issues }`.
+ * Detected: `magic-missing` (no `%PDF-` header), `polyglot` (operator-
+ * flagged), `javascript-action` (RCE class — universally refused),
+ * `launch-action` (universally refused), `open-action` (drive-by
+ * class), `embedded-file` / `embedded-file-count`, `encrypted`,
+ * `page-count`, `pdf-cap`. Pure inspection — never mutates input or
+ * throws on hostile metadata.
+ *
+ * @opts
+ *   profile:           "strict"|"balanced"|"permissive",
+ *   compliancePosture: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   magicPolicy:             "reject"|"audit"|"allow",
+ *   javascriptPolicy:        "reject"|"audit"|"allow",   // strict refused — RCE class
+ *   openActionPolicy:        "reject"|"audit"|"allow",
+ *   launchActionPolicy:      "reject"|"audit"|"allow",   // strict refused — RCE class
+ *   embeddedFilePolicy:      "reject"|"audit"|"allow",
+ *   encryptedPolicy:         "reject"|"audit"|"allow",
+ *   polyglotPolicy:          "reject"|"audit"|"allow",
+ *   pageCountPolicy:         "reject"|"audit"|"allow",
+ *   embeddedFileCountPolicy: "reject"|"audit"|"allow",
+ *   maxPageCount:            number,    // strict 500, balanced 5000, permissive 50000
+ *   maxEmbeddedFileCount:    number,    // strict 0, balanced 10, permissive 100
+ *   maxBytes:                number,    // strict 64 MiB, balanced 128 MiB, permissive 512 MiB
+ *
+ * @example
+ *   var rv = b.guardPdf.validate({
+ *     bytes: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]),
+ *     hasJavaScript: true, pageCount: 1,
+ *   }, { profile: "strict" });
+ *   rv.ok;                                               // → false
+ *   rv.issues[0].kind;                                   // → "javascript-action"
+ *   rv.issues[0].severity;                               // → "critical"
+ *
+ *   // LaunchAction — universally refused.
+ *   var launch = b.guardPdf.validate({
+ *     bytes: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]),
+ *     hasLaunchAction: true,
+ *   }, { profile: "permissive" });
+ *   launch.issues.some(function (i) { return i.kind === "launch-action"; });
+ *   //                                                   → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -258,6 +349,35 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive b.guardPdf.sanitize
+ * @signature b.guardPdf.sanitize(input, opts)
+ * @since     0.7.13
+ * @status    stable
+ * @related   b.guardPdf.validate, b.guardPdf.gate
+ *
+ * Best-effort metadata pass-through. PDF byte sanitization
+ * (stripping JavaScript actions, embedded files, OpenActions) is
+ * the operator parser's responsibility — the guard cannot rewrite
+ * the byte stream without a vendored PDF library. `sanitize`
+ * validates the metadata against the active profile and re-throws
+ * `GuardPdfError` when any issue is `critical` or `high`. Returns
+ * the input unchanged when every issue is `warn` or below.
+ *
+ * @opts
+ *   profile:           "strict"|"balanced"|"permissive",
+ *   compliancePosture: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *
+ * @example
+ *   try {
+ *     b.guardPdf.sanitize({
+ *       bytes: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D]),
+ *       hasJavaScript: true,
+ *     }, { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                            // → "pdf.javascript-action"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (!input || typeof input !== "object") {
@@ -273,6 +393,39 @@ function sanitize(input, opts) {
   return input;
 }
 
+/**
+ * @primitive  b.guardPdf.gate
+ * @signature  b.guardPdf.gate(opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardPdf.validate, b.guardPdf.sanitize, b.fileUpload, b.staticServe
+ *
+ * Build a `b.gateContract` gate suitable for `b.fileUpload({ contentSafety:
+ * { "application/pdf": gate } })` or `b.staticServe`. Operators pass
+ * `ctx.metadata` (the parser's structural report) plus the original
+ * `bytes`. Action chain: `serve` (no issues) → `audit-only`
+ * (warn-only) → `refuse` (any critical / high). No `sanitize` action
+ * — PDF byte streams can't be rewritten without a vendored parser.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,
+ *   ...:        any validate opt
+ *
+ * @example
+ *   var pdfGate = b.guardPdf.gate({ profile: "strict" });
+ *
+ *   var verdict = await pdfGate.check({
+ *     metadata: {
+ *       bytes: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]),
+ *       hasJavaScript: true, pageCount: 1,
+ *     },
+ *   });
+ *   verdict.action;                                      // → "refuse"
+ *   verdict.issues[0].kind;                              // → "javascript-action"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -296,17 +449,88 @@ 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;
 
-// Operator helper: confirm bytes carry the PDF magic header.
+/**
+ * @primitive b.guardPdf.inspectMagic
+ * @signature b.guardPdf.inspectMagic(bytes)
+ * @since     0.7.13
+ * @status    stable
+ * @related   b.guardPdf.validate, b.guardPdf.gate
+ *
+ * Return `true` when `bytes` starts with the PDF magic header
+ * (`%PDF-`, the 5 bytes `25 50 44 46 2D`); `false` otherwise. Pure
+ * inspection — never mutates input or throws.
+ *
+ * @example
+ *   var pdfBytes = Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2D, 0x31, 0x2E, 0x37]);
+ *   b.guardPdf.inspectMagic(pdfBytes);                   // → true
+ *
+ *   b.guardPdf.inspectMagic(Buffer.from([0x00, 0x01, 0x02]));
+ *   //                                                   → false
+ */
 function inspectMagic(bytes) {
   return _hasPdfMagic(bytes);
 }

package/lib/guard-regex.js

@@ -1,26 +1,48 @@
 "use strict";
 /**
- * guard-regex — Regex pattern identifier-safety primitive
- * (b.guardRegex).
+ * @module b.guardRegex
+ * @nav    Guards
+ * @title  Guard Regex
  *
- * Validates user-supplied regex pattern strings for catastrophic-
- * backtracking (ReDoS) shapes BEFORE compilation. KIND="identifier" —
- * consumes ctx.identifier (or ctx.pattern).
+ * @intro
+ *   Regex-pattern content-safety guard — refuses user-supplied
+ *   pattern strings that exhibit catastrophic-backtracking (ReDoS)
+ *   shapes BEFORE the framework compiles them with `new RegExp(...)`.
+ *   Operator-untrusted patterns flow into search filters, allow-lists,
+ *   route matchers, and form validators; this primitive screens them
+ *   so a hostile input can't pin a CPU at 100% inside the regex
+ *   engine. KIND=`identifier`; the gate consumes `ctx.identifier`
+ *   (or `ctx.pattern`) and refuses on hostile shapes. Composes with
+ *   framework parsers (`b.safeJson` / `b.safeBuffer` / route helpers)
+ *   so any operator-fed pattern hits the guard first.
  *
- * 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.
+ *   Threat catalog: nested quantifiers (`(a+)+`, `(a*)+`, `(.+)+` —
+ *   the canonical ReDoS class, e.g. CVE-2024-21538 cross-spawn and
+ *   CVE-2022-25929 chartjs-adapter-luxon); alternation-with-
+ *   quantifier (`(a|b)+`, `(\d|\d{2})*`) where alternation overlap
+ *   amplifies search paths; quantifier-inside-lookaround
+ *   (`(?=.*+)`, `(?!a*)`) — catastrophic in some engines; bounded
+ *   repetition with a large upper bound (gated by
+ *   `maxBoundedRepeat`); per-pattern byte cap to defend against
+ *   parser-stage DoS; BIDI override / zero-width / C0 control /
+ *   null-byte universal refuse.
  *
- *   var rv = b.guardRegex.validate("(a+)+b", { profile: "strict" });
- *   var g  = b.guardRegex.gate({ profile: "strict" });
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`. Operators
+ *   select via `{ profile: "strict" }` or
+ *   `{ compliance: "hipaa" }`; postures overlay on top of the
+ *   profile baseline. Nested-quantifier rejection holds at every
+ *   profile — the catastrophic class is never an operator opt-in.
+ *
+ *   Pattern strings can't be repaired safely — `sanitize` either
+ *   passes through clean input or throws `GuardRegexError`; the
+ *   gate returns `serve` / `audit-only` / `refuse` (no `sanitize`
+ *   action). Detector regexes themselves are length-bounded by
+ *   `maxPatternBytes` so the screener can't be DoS'd by its own
+ *   inputs.
+ *
+ * @card
+ *   Regex-pattern content-safety guard — refuses user-supplied pattern strings that exhibit catastrophic-backtracking (ReDoS) shapes BEFORE the framework compiles them with `new RegExp(...)`.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -204,6 +226,45 @@ function _detectIssues(input, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardRegex.validate
+ * @signature  b.guardRegex.validate(input, opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardRegex.gate, b.guardRegex.sanitize
+ *
+ * Inspect a user-supplied regex pattern string and return an
+ * aggregated issue list. Pure inspection — never throws on hostile
+ * patterns; caller decides what to do with the issues. The `ok`
+ * flag is `true` only when zero `critical` / `high` issues fire.
+ * Throws `GuardRegexError("regex.bad-opt")` when a numeric opt is
+ * non-finite / negative (config-time mistake by the operator).
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   bidiPolicy:             "reject"|"audit"|"allow",
+ *   controlPolicy:          "reject"|"audit"|"allow",
+ *   nullBytePolicy:         "reject"|"audit"|"allow",
+ *   zeroWidthPolicy:        "reject"|"strip"|"audit"|"allow",
+ *   nestedQuantPolicy:      "reject"|"audit"|"allow",
+ *   alternationQuantPolicy: "reject"|"audit"|"allow",
+ *   boundedRepeatPolicy:    "reject"|"audit"|"allow",
+ *   lookaroundQuantPolicy:  "reject"|"audit"|"allow",
+ *   maxBoundedRepeat:       number,
+ *   maxPatternBytes:        number,
+ *   maxBytes:               number,
+ *   maxRuntimeMs:           number,
+ *
+ * @example
+ *   var clean = b.guardRegex.validate("^[a-z]+$", { profile: "strict" });
+ *   clean.ok;                                          // → true
+ *
+ *   var hostile = b.guardRegex.validate("(a+)+b", { profile: "strict" });
+ *   hostile.ok;                                        // → false
+ *   hostile.issues.some(function (i) { return i.kind === "nested-quantifier"; });  // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -212,6 +273,44 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardRegex.sanitize
+ * @signature  b.guardRegex.sanitize(input, opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardRegex.validate, b.guardRegex.gate
+ *
+ * Pass-through-or-throw. Regex patterns cannot be safely repaired
+ * (stripping a `+` from a quantifier silently changes match
+ * semantics); this primitive returns the input unchanged when no
+ * `critical` or `high` issue fires, otherwise throws
+ * `GuardRegexError` with the offending rule id (e.g.
+ * `regex.nested-quantifier`, `regex.lookaround-quantifier`,
+ * `regex.bounded-repeat-cap`). Operators that need a "best-effort
+ * cleanup" semantic should reject the input at the boundary
+ * instead.
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   nestedQuantPolicy:      "reject"|"audit"|"allow",
+ *   alternationQuantPolicy: "reject"|"audit"|"allow",
+ *   boundedRepeatPolicy:    "reject"|"audit"|"allow",
+ *   lookaroundQuantPolicy:  "reject"|"audit"|"allow",
+ *   maxBoundedRepeat:       number,
+ *   maxPatternBytes:        number,
+ *
+ * @example
+ *   var safe = b.guardRegex.sanitize("^[a-z]+$", { profile: "strict" });
+ *   safe;                                              // → "^[a-z]+$"
+ *
+ *   try {
+ *     b.guardRegex.sanitize("(a+)+b", { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                          // → "regex.nested-quantifier"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -227,6 +326,45 @@ function sanitize(input, opts) {
   return input;
 }
 
+/**
+ * @primitive  b.guardRegex.gate
+ * @signature  b.guardRegex.gate(opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardRegex.validate, b.guardRegex.sanitize
+ *
+ * Build a `b.gateContract` gate that screens `ctx.identifier` (or
+ * `ctx.pattern`) before any compilation step. Action chain:
+ * `serve` (no issues) → `audit-only` (warn-only) → `refuse` (any
+ * `critical` or `high`). No `sanitize` action — pattern strings
+ * cannot be repaired. Compose into framework parsers / form
+ * validators / route matchers so operator-fed patterns hit the
+ * guard before reaching `new RegExp()`.
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:                   string,    // override gate name in audit emissions
+ *   nestedQuantPolicy:      "reject"|"audit"|"allow",
+ *   alternationQuantPolicy: "reject"|"audit"|"allow",
+ *   boundedRepeatPolicy:    "reject"|"audit"|"allow",
+ *   lookaroundQuantPolicy:  "reject"|"audit"|"allow",
+ *   maxBoundedRepeat:       number,
+ *   maxPatternBytes:        number,
+ *
+ * @example
+ *   var gate = b.guardRegex.gate({ profile: "strict" });
+ *
+ *   gate({ identifier: "(a+)+b" }).then(function (rv) {
+ *     rv.ok;                                           // → false
+ *     rv.action;                                       // → "refuse"
+ *   });
+ *
+ *   gate({ identifier: "^[a-z]+$" }).then(function (rv) {
+ *     rv.action;                                       // → "serve"
+ *   });
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -252,14 +390,84 @@ 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");
 }
 
 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;
 
 module.exports = {