@blamejs/core 0.8.42 → 0.8.49

package/lib/guard-json.js

@@ -1,70 +1,73 @@
 "use strict";
 /**
- * guard-json — JSON content-safety primitive (b.guardJson).
+ * @module b.guardJson
+ * @nav    Guards
+ * @title  Guard Json
  *
- * Threat catalog grounded in current research (multiple 2025–2026 CVEs
- * + ongoing prototype-pollution vulnerability series):
- *   - CVE-2025-55182 React/Next.js Server Functions deserialization → RCE
- *   - CVE-2025-57820 / CVE-2026-30226 Svelte devalue prototype pollution
- *   - CVE-2026-35209 defu prototype pollution
- *   - CVE-2026-28794 @orpc/client prototype pollution via deserialization
- *   - CVE-2025-13465 Lodash prototype-chain path traversal
- *   - CVE-2025-25014 Kibana prototype pollution → RCE
- *   - CVE-2024-38984 json-override prototype pollution
- *   - CVE-2022-42743 deep-parse-json prototype pollution
- *   - GHSA-9c47-m6qq-7p4h JSON5 prototype pollution via parse method
+ * @intro
+ *   JSON content-safety guard — defends against the threat catalog
+ *   operators face when accepting JSON sourced from user input.
+ *   `b.safeJson.parse` enforces baseline depth + size caps; this
+ *   module layers prototype-pollution / depth-bomb / key-count /
+ *   duplicate-key / unicode threat detection on top.
  *
- *   var rv = b.guardJson.validate(input, { profile: "strict" });
- *   var safe = b.guardJson.parse(input, { profile: "strict" });
- *   var g = b.guardJson.gate({ profile: "strict" });
+ *   Prototype-pollution defense: keys `__proto__` / `constructor` /
+ *   `prototype` anywhere in the tree are detected at the SOURCE level
+ *   (before any parser sees them). After `JSON.parse` normalizes the
+ *   input, `__proto__` routes through the prototype setter and is
+ *   invisible to `Object.keys()`, so a post-parse tree walk misses
+ *   the pollution shape — the source-text scan catches it. CVE
+ *   coverage spans the 2025-2026 deserialization + prototype-
+ *   pollution wave: CVE-2025-55182 React Server Functions RCE,
+ *   CVE-2025-57820 / CVE-2026-30226 Svelte devalue, CVE-2026-35209
+ *   defu, CVE-2026-28794 @orpc/client, CVE-2025-13465 Lodash path
+ *   traversal, CVE-2025-25014 Kibana, CVE-2024-38984 json-override,
+ *   CVE-2022-42743 deep-parse-json, GHSA-9c47-m6qq-7p4h JSON5.
  *
- * Threat catalog covered:
+ *   Depth + breadth caps: `maxDepth` / `maxKeysPerObject` /
+ *   `maxArrayLength` / `maxStringLength` / `maxTotalNodes` refuse
+ *   key-count bombs (10^6 keys per object) and stack-exhaustion
+ *   nesting attacks under strict.
  *
- *   1. Prototype pollution — `__proto__` / `constructor` / `prototype`
- *      keys anywhere in the tree. Refused regardless of profile under
- *      strict; balanced strips; permissive audits.
+ *   Duplicate-key smuggling: RFC 8259 says keys SHOULD be unique;
+ *   `JSON.parse` silently last-wins. A two-validator pipeline that
+ *   inspects the first occurrence and trusts the parser's last-wins
+ *   value is the smuggling shape; this guard rescans the source for
+ *   identical quoted keys at the same `{ ... }` nesting level.
  *
- *   2. Array-index pollution — non-numeric keys ON array values
- *      (Svelte devalue CVE-2025-57820 class). When operator JSON
- *      structurally has arrays, keys like `push` / `toString` injected
- *      via reviver/parser quirks pollute Array.prototype.
+ *   JSON5 / JSONC quirks (single-line `//` + block C-style
+ *   comments, trailing commas, NaN / Infinity / -Infinity, hex
+ *   literals, single-quoted keys) — RFC 8259 forbids these but
+ *   lenient parsers accept; the guard flags them at the source so
+ *   operators can refuse hostile inputs regardless of which parser
+ *   is downstream.
  *
- *   3. Depth bombs — nested arrays/objects past safe stack. Refused
- *      at the configured cap.
+ *   Numeric precision loss: integers above `Number.MAX_SAFE_INTEGER`
+ *   (~9.007 x 10^15, 16 digits) silently lose precision when round-
+ *   tripped through Number. Detected via raw-text scan for digit
+ *   runs of 17+ characters.
  *
- *   4. Breadth / key-count bombs — single object with massive key count
- *      (10⁶ keys → CPU + memory blow-up).
+ *   BOM injection (leading or mid-stream U+FEFF) and bidi / null /
+ *   control / zero-width character threats route through the shared
+ *   lib/codepoint-class catalog — the same detector backing the
+ *   guard-csv / guard-html / guard-svg families.
  *
- *   5. Duplicate keys — RFC 8259 says keys SHOULD be unique; in
- *      practice JSON.parse silently last-wins, which lets attackers
- *      smuggle duplicate-key payloads past validation that ran on the
- *      first occurrence (Bishop Fox JSON-interoperability research).
+ *   Top-level-key allowlist: when the operator opts in via
+ *   `topLevelKeyAllowlist: ["alpha", "beta"]`, every other top-level
+ *   key triggers a refused-shape issue. Useful for HTTP body schemas
+ *   where unexpected keys signal malformed or hostile input.
  *
- *   6. NaN / Infinity / -Infinity — RFC 8259 forbids; JSON5 / lenient
- *      parsers accept. Refused under 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.
  *
- *   7. Comments (single-line // and block-style) — RFC 8259 forbids;
- *      JSON5 / JSONC accept. Refused under strict.
+ *   Source files MUST be pure ASCII; threat-detection regexes
+ *   compose programmatically via lib/codepoint-class so the source
+ *   never embeds the attack characters themselves.
  *
- *   8. Trailing commas — JSON5 accepts; refused under strict.
- *
- *   9. BOM injection — leading or mid-stream U+FEFF.
- *
- *  10. Bidi / null / control chars in string values — same codepoint
- *      catalog as guard-csv/html/svg via lib/codepoint-class.
- *
- *  11. Numeric precision loss — values above
- *      `Number.MAX_SAFE_INTEGER` silently lose precision when round-
- *      tripped through Number. Detected via raw-text scan for digit
- *      runs longer than safe-int width.
- *
- *  12. Total size cap (anti-DoS).
- *
- *  13. Top-level-key allowlist — strict profile requires the operator
- *      to declare allowed top-level keys; balanced/permissive skip.
- *
- * Source files MUST be pure ASCII per the codepoint-table programmatic
- * regex pattern; threat-detection regexes use lib/codepoint-class.
+ * @card
+ *   JSON content-safety guard — defends against the threat catalog operators face when accepting JSON sourced from user input.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -558,6 +561,61 @@ function _stripPollutionTree(value, opts, depth) {
 
 // ---- Public surface ----
 
+/**
+ * @primitive  b.guardJson.validate
+ * @signature  b.guardJson.validate(input, opts?)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardJson.parse, b.guardJson.gate, b.safeJson.parse
+ *
+ * Inspect `input` (string of JSON source) for the full guard-json
+ * threat catalog without committing to a parsed value. Returns
+ * `{ ok, issues, severities }` where `issues` is the aggregated
+ * detector output — every prototype-pollution key, depth/breadth
+ * cap hit, duplicate-key smuggle, JSON5-quirk match, BOM placement,
+ * unicode threat, and numeric-precision-loss candidate is reported
+ * with `kind` / `severity` / `ruleId` / `snippet`. Profile-driven
+ * (`strict` / `balanced` / `permissive`) and posture-driven
+ * (`hipaa` / `pci-dss` / `gdpr` / `soc2`).
+ *
+ * Detection runs in two passes: a raw-source scan (BOM placement,
+ * comments, NaN/Infinity, trailing commas, JSON5 quirks, source-
+ * level prototype-pollution keys, codepoint-class threats) followed
+ * by a parsed-tree walk (depth / breadth / array-length / string-
+ * length / node-count caps, duplicate-key rescan).
+ *
+ * @opts
+ *   profile:                  "strict"|"balanced"|"permissive",
+ *   compliance:               "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   pollutionPolicy:          "reject"|"strip"|"audit"|"allow",
+ *   duplicateKeyPolicy:       "reject"|"audit"|"allow",
+ *   nanInfinityPolicy:        "reject"|"audit"|"allow",
+ *   commentPolicy:            "reject"|"audit"|"allow",
+ *   trailingCommaPolicy:      "reject"|"audit"|"allow",
+ *   json5SyntaxPolicy:        "reject"|"audit"|"allow",
+ *   bomPolicy:                "reject"|"strip"|"allow",
+ *   bidiPolicy:               "reject"|"strip"|"audit"|"allow",
+ *   controlPolicy:            "reject"|"strip"|"allow",
+ *   nullBytePolicy:           "reject"|"strip"|"allow",
+ *   zeroWidthPolicy:          "reject"|"strip"|"audit"|"allow",
+ *   numericPrecisionPolicy:   "reject"|"audit"|"allow",
+ *   requireTopLevelKeyAllowlist: boolean,
+ *   topLevelKeyAllowlist:     string[]|null,
+ *   maxBytes:                 number,    // total source byte cap
+ *   maxDepth:                 number,    // recursion depth cap
+ *   maxKeysPerObject:         number,    // breadth cap per object
+ *   maxArrayLength:           number,    // array length cap
+ *   maxStringLength:          number,    // string length cap
+ *   maxTotalNodes:            number,    // total node count cap
+ *
+ * @example
+ *   var rv = b.guardJson.validate('{"__proto__":{"polluted":true}}', {
+ *     profile: "strict",
+ *   });
+ *   rv.ok;                                              // → false
+ *   rv.issues.some(function (i) { return i.kind === "prototype-pollution-key"; });  // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -574,6 +632,48 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardJson.parse
+ * @signature  b.guardJson.parse(input, opts?)
+ * @since      0.7.13
+ * @status     stable
+ * @related    b.guardJson.validate, b.guardJson.gate, b.safeJson.parse
+ *
+ * Parse `input` (string of JSON source) into a JavaScript value
+ * after the guard-json threat catalog clears. Refuses on prototype-
+ * pollution keys when `pollutionPolicy === "reject"`, refuses on any
+ * critical raw-source pre-parse threat, refuses on parse failure,
+ * and otherwise routes through `b.safeJson.parse` with the configured
+ * `maxBytes` / `maxDepth` caps. Strip policies (`bomPolicy: "strip"`,
+ * `controlPolicy: "strip"`, `zeroWidthPolicy: "strip"`) silently
+ * remove the offending characters from the source before parsing.
+ *
+ * Pollution keys (`__proto__` / `constructor` / `prototype`) are
+ * normally invisible to `Object.keys()` after `JSON.parse` because
+ * they route through prototype setters; the parse path passes
+ * `allowProto: true` to `b.safeJson.parse` only when policy is
+ * `audit` / `allow`, ensuring strip / reject paths produce a tree
+ * with no pollution-key residue.
+ *
+ * Throws `GuardJsonError` on refusal — the error code matches the
+ * triggering rule (`json.prototype-pollution`, `json.parse`, etc.).
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   pollutionPolicy: "reject"|"strip"|"audit"|"allow",
+ *   bomPolicy:       "reject"|"strip"|"allow",
+ *   controlPolicy:   "reject"|"strip"|"allow",
+ *   zeroWidthPolicy: "reject"|"strip"|"audit"|"allow",
+ *   maxBytes: number, maxDepth: number,
+ *
+ * @example
+ *   var safe = b.guardJson.parse('{"name":"alice","age":30}', {
+ *     profile: "strict",
+ *   });
+ *   safe.name;                                          // → "alice"
+ *   safe.age;                                           // → 30
+ */
 function parse(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -643,6 +743,42 @@ function _policyKeyForRuleId(ruleId) {
   return map[ruleId] || null;
 }
 
+/**
+ * @primitive  b.guardJson.gate
+ * @signature  b.guardJson.gate(opts?)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardJson.validate, b.guardJson.parse, b.staticServe.create, b.fileUpload.create
+ *
+ * Build a `b.gateContract` gate suitable for plugging into
+ * `b.staticServe({ contentSafety: { ".json": gate } })`,
+ * `b.fileUpload({ contentSafety: { "application/json": gate } })`,
+ * or any host primitive that consumes the gate-contract shape.
+ * Action chain on validation: `serve` (no issues) → `audit-only`
+ * (warn-only issues) → `sanitize` (high/critical but every reject-
+ * policy is off — re-parse + re-emit a cleaned tree via
+ * `JSON.stringify`) → `refuse` (critical/high under any reject
+ * policy, or sanitize threw).
+ *
+ * Sanitize-eligibility requires every policy in the reject set
+ * (`pollutionPolicy` / `duplicateKeyPolicy` / `nanInfinityPolicy` /
+ * `commentPolicy` / `trailingCommaPolicy` / `json5SyntaxPolicy` /
+ * `bomPolicy` / `bidiPolicy` / `controlPolicy` / `nullBytePolicy`)
+ * to be off; under strict every one is `"reject"` so the gate jumps
+ * straight from `audit-only` to `refuse`.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,    // gate identity for audit / observability
+ *
+ * @example
+ *   var jsonGate = b.guardJson.gate({ profile: "strict" });
+ *   var hostile = Buffer.from('{"__proto__":{"x":1}}', "utf8");
+ *   var verdict = await jsonGate.check({ bytes: hostile });
+ *   verdict.action;                                     // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -684,13 +820,83 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardJson.buildProfile
+ * @signature  b.guardJson.buildProfile(opts)
+ * @since      0.7.13
+ * @status     stable
+ * @related    b.guardJson.gate, b.guardJson.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. 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 guard-json key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardJson.buildProfile({
+ *     extends: "balanced",
+ *     pollutionPolicy: "reject",
+ *     maxDepth: 16,
+ *   });
+ *   custom.pollutionPolicy;                             // → "reject"
+ *   custom.maxDepth;                                    // → 16
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardJson.compliancePosture
+ * @signature  b.guardJson.compliancePosture(name)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardJson.gate, b.guardJson.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
+ * `GuardJsonError("json.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardJson.compliancePosture("hipaa");
+ *   posture.pollutionPolicy;                            // → "reject"
+ *   posture.forensicSnippetBytes;                       // → 256
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES, _err, "json");
 }
 
 var _jsonRulePacks = gateContract.makeRulePackLoader(GuardJsonError, "json");
+/**
+ * @primitive  b.guardJson.loadRulePack
+ * @signature  b.guardJson.loadRulePack(pack)
+ * @since      0.7.13
+ * @status     stable
+ * @related    b.guardJson.gate
+ *
+ * Register an operator-supplied rule pack with the guard-json
+ * 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 `GuardJsonError("json.bad-opt")` when `pack` is
+ * missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardJson.loadRulePack({
+ *     id: "tenant-keys",
+ *     rules: [
+ *       { id: "tenant-id-shape", severity: "high",
+ *         detect: function (tree) { return !tree || typeof tree.tenantId !== "string"; },
+ *         reason: "tenantId must be a string at top level" },
+ *     ],
+ *   });
+ *   pack.id;                                            // → "tenant-keys"
+ */
 var loadRulePack = _jsonRulePacks.load;
 
 module.exports = {

package/lib/guard-jsonpath.js

@@ -1,30 +1,53 @@
 "use strict";
 /**
- * guard-jsonpath — JSONPath identifier-safety primitive
- * (b.guardJsonpath).
+ * @module b.guardJsonpath
+ * @nav    Guards
+ * @title  Guard Jsonpath
  *
- * Validates user-supplied JSONPath strings (RFC 9535) before they're
- * handed to a JSONPath evaluator. Many JSONPath libraries (notably
- * the original Stefan Goessner implementation and several JS forks)
- * route filter / script expressions through dynamic-code execution,
- * turning a query path into an RCE primitive. KIND="identifier" —
- * consumes ctx.identifier (or ctx.jsonpath).
+ * @intro
+ *   JSONPath content-safety guard — refuses user-supplied JSONPath
+ *   query strings that exhibit dynamic-code-execution shapes BEFORE
+ *   they reach a JSONPath evaluator. Many JSONPath implementations
+ *   (the original Stefan Goessner reference and several JS forks)
+ *   route filter / script expressions through `eval`-class
+ *   dispatch, turning a query path into an RCE primitive; this
+ *   primitive screens the path so a hostile query can't escape into
+ *   code execution. KIND=`identifier`; the gate consumes
+ *   `ctx.identifier` (or `ctx.jsonpath`) and refuses on hostile
+ *   shapes. Targets the RFC 9535 compliant subset — filter / script
+ *   expressions with code-execution semantics are rejected at every
+ *   profile.
  *
- * Threat catalog:
- *   - Filter expression `?(...)` — dynamic-code-execution class in
- *     legacy implementations. Universally refused at every profile.
- *   - Script expression `(@.x)` style — RFC 9535 doesn't define it
- *     but many implementations support it as alias for filter.
- *   - JS-source hints — operator-supplied path containing the
- *     literal substrings that would only appear in a code-injection
- *     attempt: dynamic-code-exec keyword, constructor invocation
- *     keyword, function-declaration keyword, arrow-function arrow,
- *     or statement-separator semicolon.
- *   - Recursive-descent depth bomb — `..[*]` repeated > N times
- *     amplifies traversal cost.
- *   - Excessive bracket nesting.
- *   - Excessive pattern length.
- *   - BIDI / null / control / zero-width universal refuse.
+ *   Threat catalog: filter expression `?(...)` (dynamic-code-
+ *   execution class in legacy implementations — refused
+ *   universally); script expression shape `(@.x)` (RFC 9535
+ *   undefined but several implementations alias it to filter);
+ *   JS-source hints (the path contains substrings that only appear
+ *   in a code-injection attempt — dynamic-code-exec keyword,
+ *   constructor invocation keyword, function-declaration keyword,
+ *   arrow-function arrow, or statement-separator semicolon);
+ *   recursive-descent depth bomb (`..[*]` repeated past
+ *   `maxRecursiveDescents`); 3+ consecutive `[` parser-DoS shape;
+ *   per-pattern byte cap; BIDI override / zero-width / C0 control /
+ *   null-byte universal refuse.
+ *
+ *   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. Filter / script / dynamic-hint refusal holds
+ *   at every profile — the RCE class is never an operator opt-in.
+ *
+ *   JSONPath strings can't be repaired safely — `sanitize` either
+ *   passes through clean input or throws `GuardJsonpathError`; the
+ *   gate returns `serve` / `audit-only` / `refuse` (no `sanitize`
+ *   action). The source file's hint catalog is composed from
+ *   substring fragments so the file itself stays free of the
+ *   literal keywords (the codebase-patterns gate flags them
+ *   otherwise).
+ *
+ * @card
+ *   JSONPath content-safety guard — refuses user-supplied JSONPath query strings that exhibit dynamic-code-execution shapes BEFORE they reach a JSONPath evaluator.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -217,6 +240,46 @@ function _detectIssues(input, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardJsonpath.validate
+ * @signature  b.guardJsonpath.validate(input, opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardJsonpath.gate, b.guardJsonpath.sanitize
+ *
+ * Inspect a user-supplied JSONPath string and return an aggregated
+ * issue list. Pure inspection — never throws on hostile paths;
+ * caller decides what to do with the issues. The `ok` flag is
+ * `true` only when zero `critical` / `high` issues fire. Throws
+ * `GuardJsonpathError("jsonpath.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",
+ *   filterExprPolicy:       "reject"|"audit"|"allow",
+ *   scriptExprPolicy:       "reject"|"audit"|"allow",
+ *   dynamicHintPolicy:      "reject"|"audit"|"allow",
+ *   bracketNestingPolicy:   "reject"|"audit"|"allow",
+ *   recursiveDescentPolicy: "reject"|"audit"|"allow",
+ *   maxRecursiveDescents:   number,
+ *   maxPatternBytes:        number,
+ *   maxBytes:               number,
+ *   maxRuntimeMs:           number,
+ *
+ * @example
+ *   var clean = b.guardJsonpath.validate("$.users[*].name", { profile: "strict" });
+ *   clean.ok;                                          // → true
+ *
+ *   var hostile = b.guardJsonpath.validate("$..[?(@.x)]", { profile: "strict" });
+ *   hostile.ok;                                        // → false
+ *   hostile.issues.some(function (i) { return i.kind === "filter-expression"; });  // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -225,6 +288,45 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardJsonpath.sanitize
+ * @signature  b.guardJsonpath.sanitize(input, opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardJsonpath.validate, b.guardJsonpath.gate
+ *
+ * Pass-through-or-throw. JSONPath expressions cannot be safely
+ * repaired (stripping a `?(` from a filter silently changes query
+ * semantics); this primitive returns the input unchanged when no
+ * `critical` or `high` issue fires, otherwise throws
+ * `GuardJsonpathError` with the offending rule id (e.g.
+ * `jsonpath.filter-expression`, `jsonpath.dynamic-hint`,
+ * `jsonpath.script-expression`). Operators that need a "best-
+ * effort cleanup" semantic should reject the path at the boundary
+ * instead.
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   filterExprPolicy:       "reject"|"audit"|"allow",
+ *   scriptExprPolicy:       "reject"|"audit"|"allow",
+ *   dynamicHintPolicy:      "reject"|"audit"|"allow",
+ *   bracketNestingPolicy:   "reject"|"audit"|"allow",
+ *   recursiveDescentPolicy: "reject"|"audit"|"allow",
+ *   maxRecursiveDescents:   number,
+ *   maxPatternBytes:        number,
+ *
+ * @example
+ *   var safe = b.guardJsonpath.sanitize("$.users[*].name", { profile: "strict" });
+ *   safe;                                              // → "$.users[*].name"
+ *
+ *   try {
+ *     b.guardJsonpath.sanitize("$..[?(@.x)]", { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                          // → "jsonpath.filter-expression"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -240,6 +342,46 @@ function sanitize(input, opts) {
   return input;
 }
 
+/**
+ * @primitive  b.guardJsonpath.gate
+ * @signature  b.guardJsonpath.gate(opts)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardJsonpath.validate, b.guardJsonpath.sanitize
+ *
+ * Build a `b.gateContract` gate that screens `ctx.identifier` (or
+ * `ctx.jsonpath`) before the path reaches a JSONPath evaluator.
+ * Action chain: `serve` (no issues) → `audit-only` (warn-only) →
+ * `refuse` (any `critical` or `high`). No `sanitize` action —
+ * JSONPath strings cannot be repaired. Compose into query
+ * endpoints / search filters / data-export flows so operator-fed
+ * paths hit the guard before any evaluator dispatch.
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:                   string,    // override gate name in audit emissions
+ *   filterExprPolicy:       "reject"|"audit"|"allow",
+ *   scriptExprPolicy:       "reject"|"audit"|"allow",
+ *   dynamicHintPolicy:      "reject"|"audit"|"allow",
+ *   bracketNestingPolicy:   "reject"|"audit"|"allow",
+ *   recursiveDescentPolicy: "reject"|"audit"|"allow",
+ *   maxRecursiveDescents:   number,
+ *   maxPatternBytes:        number,
+ *
+ * @example
+ *   var gate = b.guardJsonpath.gate({ profile: "strict" });
+ *
+ *   gate({ identifier: "$..[?(@.x)]" }).then(function (rv) {
+ *     rv.ok;                                           // → false
+ *     rv.action;                                       // → "refuse"
+ *   });
+ *
+ *   gate({ identifier: "$.users[*].name" }).then(function (rv) {
+ *     rv.action;                                       // → "serve"
+ *   });
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -265,14 +407,84 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardJsonpath.buildProfile
+ * @signature  b.guardJsonpath.buildProfile(opts)
+ * @since      0.7.13
+ * @status     stable
+ * @related    b.guardJsonpath.gate, b.guardJsonpath.compliancePosture
+ *
+ * Compose a derived guardJsonpath 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 guardJsonpath key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardJsonpath.buildProfile({
+ *     extends: "balanced",
+ *     maxRecursiveDescents: 1,
+ *     recursiveDescentPolicy: "reject",
+ *   });
+ *   custom.maxRecursiveDescents;                       // → 1
+ *   custom.filterExprPolicy;                           // → "reject"
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardJsonpath.compliancePosture
+ * @signature  b.guardJsonpath.compliancePosture(name)
+ * @since      0.7.13
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardJsonpath.gate, b.guardJsonpath.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
+ * `GuardJsonpathError("jsonpath.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardJsonpath.compliancePosture("hipaa");
+ *   posture.filterExprPolicy;                          // → "reject"
+ *   posture.forensicSnippetBytes;                      // → 256
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "jsonpath");
 }
 
 var _jpRulePacks = gateContract.makeRulePackLoader(GuardJsonpathError, "jsonpath");
+/**
+ * @primitive  b.guardJsonpath.loadRulePack
+ * @signature  b.guardJsonpath.loadRulePack(pack)
+ * @since      0.7.13
+ * @status     stable
+ * @related    b.guardJsonpath.gate
+ *
+ * Register an operator-supplied rule pack with the guardJsonpath
+ * 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 `GuardJsonpathError("jsonpath.bad-opt")` when
+ * `pack` is missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardJsonpath.loadRulePack({
+ *     id: "no-wildcards",
+ *     rules: [
+ *       { id: "wildcard", severity: "high",
+ *         detect: function (path) { return path.indexOf("[*]") !== -1; },
+ *         reason: "wildcard index forbidden in this context" },
+ *     ],
+ *   });
+ *   pack.id;                                           // → "no-wildcards"
+ */
 var loadRulePack = _jpRulePacks.load;
 
 module.exports = {