@blamejs/core 0.8.43 → 0.8.49

package/lib/guard-uuid.js

@@ -1,38 +1,36 @@
 "use strict";
 /**
- * guard-uuid — UUID identifier-safety primitive (b.guardUuid).
+ * @module b.guardUuid
+ * @nav    Guards
+ * @title  Guard Uuid
  *
- * Validates user-supplied UUID strings per RFC 9562 (May 2024,
- * obsoletes RFC 4122). KIND="identifier" — consumes ctx.identifier
- * (or ctx.uuid).
+ * @intro
+ *   UUID identifier-safety guard. Validates user-supplied UUID
+ *   strings per RFC 9562 (May 2024 — obsoletes RFC 4122) and
+ *   refuses non-RFC shapes that downstream parsers routinely
+ *   misinterpret. KIND="identifier" — the gate consumes
+ *   `ctx.identifier` (or `ctx.uuid`).
  *
- * Threat catalog:
- *   - Wrong length / shape — UUIDs are 36 chars with hyphens, 32 hex
- *     without, or 38 with Microsoft GUID braces; anything else is
- *     malformed and a downstream parser may diverge.
- *   - Wrong character class — non-hex characters anywhere.
- *   - Invalid version field (RFC 9562 §4.2) — versions 1-8 are
- *     defined; 0 and 9-F are reserved/unassigned and indicate
- *     hand-rolled or attacker-shaped IDs.
- *   - Variant bits (RFC 9562 §4.1) — only 10xx (RFC 4122/9562
- *     variant) is the canonical UUID variant; other variants
- *     (NCS-reserved 0xxx, Microsoft-reserved 110x, future-reserved
- *     111x) often indicate non-UUID payloads coerced into the slot.
- *   - Nil UUID (RFC 9562 §5.9 — all zeros) — usually represents
- *     "no UUID set"; passing through can mask a missing-key bug.
- *   - Max UUID (RFC 9562 §5.10 — all FF) — sentinel value with the
- *     same semantic risk as nil.
- *   - urn:uuid: prefix (RFC 4122 §3) — when not requested by the
- *     caller, can disguise a UUID inside a URN-shape parser.
- *   - Microsoft GUID braces `{...}` — disguise a UUID inside a
- *     COM-style serialization parser.
- *   - BIDI / zero-width / control / null-byte — universal-refuse.
+ *   Threat catalog: wrong length / shape (canonical 36-char
+ *   hyphenated, 32-char hyphenless, 38-char braced, or
+ *   `urn:uuid:` prefixed — anything else is malformed); wrong
+ *   character class (non-hex anywhere); invalid version field
+ *   (RFC 9562 §4.2 defines 1-8; 0 and 9-F are reserved /
+ *   unassigned and indicate hand-rolled or attacker-shaped IDs);
+ *   variant bits (RFC 9562 §4.1 — only 10xx is the canonical
+ *   variant; NCS-reserved 0xxx, Microsoft 110x, future 111x often
+ *   indicate non-UUID payloads coerced into the slot); nil UUID
+ *   (§5.9 all zeros — usually "no UUID set", masks missing-key
+ *   bugs when passed through); max UUID (§5.10 all FF — sentinel
+ *   with the same semantic risk as nil); `urn:uuid:` prefix
+ *   smuggling; Microsoft GUID braces `{...}` smuggling;
+ *   BIDI / zero-width / C0-control / null-byte universal-refuse.
  *
- *   var rv = b.guardUuid.validate("550e8400-e29b-41d4-a716-446655440000",
- *                                 { profile: "strict" });
- *   var safe = b.guardUuid.sanitize("urn:uuid:550E8400-...",
- *                                   { profile: "balanced" });
- *   var g = b.guardUuid.gate({ profile: "strict" });
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`.
+ *
+ * @card
+ *   UUID identifier-safety guard.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -292,6 +290,46 @@ function _detectIssues(input, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardUuid.validate
+ * @signature  b.guardUuid.validate(input, opts?)
+ * @since      0.7.44
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardUuid.sanitize, b.guardUuid.gate, b.uuid.v4, b.uuid.v7
+ *
+ * Inspect a UUID string against the resolved profile and return
+ * `{ ok, issues }`. Each issue carries `kind` / `severity`
+ * (`critical` | `high` | `medium` | `low`) / `ruleId` / `snippet`.
+ * Non-string input returns a single `uuid.bad-input` issue rather
+ * than throwing — callers that prefer an exception use
+ * `b.guardUuid.sanitize`.
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   bidiPolicy:             "reject"|"strip"|"audit"|"allow",
+ *   controlPolicy:          "reject"|"strip"|"allow",
+ *   nullBytePolicy:         "reject"|"strip"|"allow",
+ *   zeroWidthPolicy:        "reject"|"strip"|"allow",
+ *   formatPolicy:           "hyphenated"|"hyphenless"|"braced"|"urn"|"hyphenated-only"|"any",
+ *   versionPolicy:          "reject-unassigned"|"audit"|"allow",
+ *   variantPolicy:          "reject-non-rfc"|"audit"|"allow",
+ *   nilPolicy:              "reject"|"audit"|"allow",
+ *   maxPolicy:              "reject"|"audit"|"allow",
+ *   urnPolicy:              "reject"|"audit"|"allow",
+ *   maxBytes:               number,
+ *
+ * @example
+ *   var rv = b.guardUuid.validate("550e8400-e29b-41d4-a716-446655440000",
+ *                                 { profile: "strict" });
+ *   rv.ok;                                             // → true
+ *
+ *   var bad = b.guardUuid.validate("00000000-0000-0000-0000-000000000000",
+ *                                  { profile: "strict" });
+ *   bad.ok;                                            // → false
+ *   bad.issues[0].ruleId;                              // → "uuid.nil"
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -308,6 +346,36 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardUuid.sanitize
+ * @signature  b.guardUuid.sanitize(input, opts?)
+ * @since      0.7.44
+ * @status     stable
+ * @related    b.guardUuid.validate, b.guardUuid.gate
+ *
+ * Normalize a UUID to canonical hyphenated lowercase form. Strips
+ * Microsoft GUID braces `{...}` and the `urn:uuid:` prefix. Throws
+ * `GuardUuidError` when any `critical` or `high` issue fires
+ * (nil / max sentinel under reject, unassigned version, non-RFC
+ * variant). Use `validate` to inspect issues without throwing.
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ...:                    same shape as b.guardUuid.validate opts,
+ *
+ * @example
+ *   var safe = b.guardUuid.sanitize("urn:uuid:550E8400-E29B-41D4-A716-446655440000",
+ *                                   { profile: "balanced" });
+ *   safe;                                              // → "550e8400-e29b-41d4-a716-446655440000"
+ *
+ *   try {
+ *     b.guardUuid.sanitize("ffffffff-ffff-ffff-ffff-ffffffffffff",
+ *                          { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                          // → "uuid.max"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -330,6 +398,35 @@ function sanitize(input, opts) {
          hex.slice(20);                                                          // allow:raw-byte-literal — UUID hex slice positions
 }
 
+/**
+ * @primitive  b.guardUuid.gate
+ * @signature  b.guardUuid.gate(opts?)
+ * @since      0.7.44
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardUuid.validate, b.guardUuid.sanitize, b.guardAll.gate
+ *
+ * Build an async gate `(ctx) -> { ok, action, issues }` consumable
+ * by `b.guardAll`, ID validators, and any host that handles
+ * UUID-shaped tokens. The gate reads `ctx.identifier` (or
+ * `ctx.uuid`), runs `validate`, and maps severity to action: zero
+ * issues `serve`; only low/medium `audit-only`; any high/critical
+ * `refuse`.
+ *
+ * @opts
+ *   name:                   string,    // gate label for audit / observability
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ...:                    same shape as b.guardUuid.validate opts,
+ *
+ * @example
+ *   var g = b.guardUuid.gate({ profile: "strict" });
+ *   var rv = await g({ identifier: "550e8400-e29b-41d4-a716-446655440000" });
+ *   rv.action;                                         // → "serve"
+ *
+ *   var bad = await g({ identifier: "{550e8400-e29b-41d4-a716-446655440000}" });
+ *   bad.action;                                        // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -353,14 +450,76 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardUuid.buildProfile
+ * @signature  b.guardUuid.buildProfile(opts)
+ * @since      0.7.44
+ * @status     stable
+ * @related    b.guardUuid.gate, b.guardUuid.compliancePosture
+ *
+ * Compose a derived profile from one or more named bases plus
+ * inline overrides. `opts.extends` is a profile name or array of
+ * names (later entries shadow earlier ones); inline keys win last.
+ *
+ * @opts
+ *   extends: string|string[],   // base profile name(s) to compose
+ *   ...:     any guard-uuid key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardUuid.buildProfile({
+ *     extends: "balanced",
+ *     formatPolicy: "hyphenated-only",
+ *     nilPolicy: "audit",
+ *   });
+ *   custom.formatPolicy;                               // → "hyphenated-only"
+ *   custom.nilPolicy;                                  // → "audit"
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardUuid.compliancePosture
+ * @signature  b.guardUuid.compliancePosture(name)
+ * @since      0.7.44
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardUuid.gate, b.guardUuid.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
+ * `GuardUuidError("uuid.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardUuid.compliancePosture("hipaa");
+ *   posture.nilPolicy;                                 // → "reject"
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "uuid");
 }
 
 var _uuidRulePacks = gateContract.makeRulePackLoader(GuardUuidError, "uuid");
+/**
+ * @primitive  b.guardUuid.loadRulePack
+ * @signature  b.guardUuid.loadRulePack(pack)
+ * @since      0.7.44
+ * @status     stable
+ * @related    b.guardUuid.gate
+ *
+ * Register an operator-supplied rule pack with the guard-uuid
+ * 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`. Throws
+ * `GuardUuidError("uuid.bad-opt")` when `pack` is missing or
+ * `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardUuid.loadRulePack({
+ *     id: "v7-only",
+ *     allowedVersions: [7],
+ *   });
+ *   pack.id;                                           // → "v7-only"
+ */
 var loadRulePack = _uuidRulePacks.load;
 
 module.exports = {

package/lib/guard-xml.js

@@ -1,45 +1,70 @@
 "use strict";
 /**
- * guard-xml — XML content-safety primitive (b.guardXml).
+ * @module b.guardXml
+ * @nav    Guards
+ * @title  Guard Xml
  *
- * Threat catalog grounded in current research (XXE remains active in
- * 2025-2026 despite 20+ years of awareness):
- *   - CVE-2026-24400 AssertJ XXE via toXmlDocument default parser
- *   - CVE-2025-3225 sitemap parser XXE
- *   - CVE-2024-1455 LangChain XXE
- *   - CVE-2024-25062 libxml2 use-after-free with DTD + XInclude
- *   - CVE-2024-56171 libxml2 schema use-after-free
- *   - CVE-2025-24928 libxml2 stack overflow on DTD validation
- *   - CVE-2025-32415 libxml2 schema heap under-read
- *   - CVE-2025-27113 libxml2 NULL deref in pattern.c
- *   - CVE-2024-8176 libexpat stack overflow (recursive entity expansion)
+ * @intro
+ *   XML content-safety guard — defends against the XXE / billion-
+ *   laughs / external-entity / XSLT-exec catalog that has remained
+ *   active for 20+ years and continues to ship CVEs through 2025-
+ *   2026. XML attack surface centers on the DOCTYPE subset, where
+ *   entity declarations and external references convert a benign-
+ *   looking XML document into a file-disclosure / SSRF / RCE / DoS
+ *   primitive depending on the parser.
  *
- *   var rv = b.guardXml.validate(input, { profile: "strict" });
- *   var safe = b.guardXml.sanitize(input, { profile: "balanced" });
- *   var g = b.guardXml.gate({ profile: "strict" });
+ *   XXE / external entity (XML External Entity) defense:
+ *   `<!ENTITY xxe SYSTEM "file:///etc/passwd">` and `SYSTEM` /
+ *   `PUBLIC` identifiers pointing at `file://` / `http://` /
+ *   `https://` / `ftp://` / `gopher://` / `jar://` / `netdoc://`
+ *   are refused regardless of profile. CVE-2026-24400 AssertJ
+ *   `toXmlDocument` default parser, CVE-2025-3225 sitemap parser,
+ *   CVE-2024-1455 LangChain XXE, and CVE-2024-25062 libxml2 UAF
+ *   with DTD + XInclude all fit this shape.
  *
- * Threat catalog covered:
+ *   Billion-laughs / entity-expansion DoS: `<!ENTITY lol "lol">` +
+ *   `<!ENTITY lol2 "&lol;&lol;...">` recursive declarations expand
+ *   exponentially when the parser dereferences. Refused via the
+ *   blanket `<!ENTITY>` rule; parameter entities (`<!ENTITY %>`
+ *   prefix) get an additional out-of-band exfil tag. CVE-2024-8176
+ *   libexpat stack overflow on recursive entity expansion +
+ *   CVE-2025-24928 libxml2 stack overflow on DTD validation track
+ *   the family.
  *
- *   1. DOCTYPE declarations — refuse unconditionally regardless of
- *      profile. Catches billion-laughs entity expansion + external
- *      entity loading (XXE) + SYSTEM identifier exfil.
- *   2. <!ENTITY> declarations including parameter entities (% prefix).
- *   3. External entities — file:// / http:// / SYSTEM identifiers in
- *      DOCTYPE subset.
- *   4. XInclude — <xi:include href="..."/> remote inclusion.
- *   5. xsi:schemaLocation / xsi:noNamespaceSchemaLocation — operator-
- *      controlled schema fetch.
- *   6. Processing instructions — <?xml-stylesheet ...?> CSS injection
- *      vector.
- *   7. CDATA sections — often used to hide payloads from naive
- *      scanners.
- *   8. XML signature wrapping (xmldsig) — surface that requires
- *      careful operator handling; flagged as audit.
- *   9. Bidi / null / control / zero-width chars in element text +
- *      attribute values.
- *  10. Anti-DoS caps — total document size, max element count, max
- *      attribute count per element, max depth, max attribute value
- *      length.
+ *   DTD external-entity refusal: every `<!DOCTYPE>` declaration is
+ *   refused unconditionally — there is no safe DTD subset that
+ *   defenders can enumerate against the parser-quirk landscape, so
+ *   the only stable posture is to reject the surface entirely.
+ *
+ *   XSLT / processing-instruction exec defense: `<?xml-stylesheet
+ *   href="...">` and other `<?PI ?>` shapes can route the document
+ *   through an XSLT processor with `document()` / `xsl:include` /
+ *   `xsl:import` — full file-disclosure + SSRF surface. Flagged
+ *   under balanced; refused under strict (after the standard
+ *   `<?xml ... ?>` declaration is stripped).
+ *
+ *   XInclude (`<xi:include href="...">`) and `xsi:schemaLocation` /
+ *   `xsi:noNamespaceSchemaLocation` are operator-controlled fetch
+ *   surfaces; XML signature elements (`xmldsig`) require operator
+ *   defense against signature-wrapping attacks. CDATA sections
+ *   often hide payloads from naive scanners.
+ *
+ *   Anti-DoS caps: total document size (`maxBytes`), nesting depth
+ *   (`maxDepth`), element count (`maxElements`), attribute count per
+ *   element (`maxAttrsPerElement`), and attribute value length
+ *   (`maxAttrValueBytes`).
+ *
+ *   Bidi / null / control / zero-width character threats route
+ *   through the shared lib/codepoint-class detector.
+ *
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`. Even under
+ *   `permissive`, DOCTYPE / ENTITY / external-entity refusal stays
+ *   on — the billion-laughs and XXE classes have no safe permissive
+ *   posture.
+ *
+ * @card
+ *   XML content-safety guard — defends against the XXE / billion- laughs / external-entity / XSLT-exec catalog that has remained active for 20+ years and continues to ship CVEs through 2025- 2026.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -299,6 +324,59 @@ function _detectIssues(input, opts) {
 
 // ---- Public surface ----
 
+/**
+ * @primitive  b.guardXml.validate
+ * @signature  b.guardXml.validate(input, opts?)
+ * @since      0.7.15
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardXml.sanitize, b.guardXml.gate
+ *
+ * Inspect `input` (string of XML source) for the full guard-xml
+ * threat catalog without invoking a parser. Returns
+ * `{ ok, issues, severities }` where `issues` enumerates every
+ * DOCTYPE declaration, `<!ENTITY>` definition (including parameter
+ * entities), SYSTEM/PUBLIC external-entity reference, XInclude
+ * directive, xsi:schemaLocation hint, processing instruction (after
+ * the standard `<?xml ?>` declaration), CDATA section, XML signature
+ * element, and codepoint-class threat. Element / depth caps are
+ * estimated via tag-count + nesting heuristics — strict-mode rejects
+ * exceeding the configured caps without requiring a full parse.
+ *
+ * Profile-driven (`strict` / `balanced` / `permissive`) and posture-
+ * driven (`hipaa` / `pci-dss` / `gdpr` / `soc2`). Note that
+ * DOCTYPE / `<!ENTITY>` / external-entity refusal stays on under
+ * every profile — there is no safe permissive posture for the XXE
+ * + billion-laughs class.
+ *
+ * @opts
+ *   profile:               "strict"|"balanced"|"permissive",
+ *   compliance:            "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   doctypePolicy:         "reject"|"audit"|"allow",
+ *   entityPolicy:          "reject"|"audit"|"allow",
+ *   externalEntityPolicy:  "reject"|"audit"|"allow",
+ *   xincludePolicy:        "reject"|"audit"|"allow",
+ *   schemaLocationPolicy:  "reject"|"audit"|"allow",
+ *   processingInstrPolicy: "reject"|"audit"|"allow",
+ *   cdataPolicy:           "reject"|"audit"|"allow",
+ *   xmlDsigPolicy:         "audit"|"allow",
+ *   bidiPolicy:            "reject"|"strip"|"audit"|"allow",
+ *   controlPolicy:         "reject"|"strip"|"allow",
+ *   nullBytePolicy:        "reject"|"strip"|"allow",
+ *   zeroWidthPolicy:       "reject"|"strip"|"audit"|"allow",
+ *   maxBytes:              number,    // total source byte cap
+ *   maxDepth:              number,    // estimated nesting depth cap
+ *   maxElements:           number,    // total open-tag count cap
+ *   maxAttrsPerElement:    number,    // attribute count cap per element
+ *   maxAttrValueBytes:     number,    // per-attr-value length cap
+ *
+ * @example
+ *   var hostile = '<?xml version="1.0"?>\n' +
+ *                 '<!DOCTYPE r [<!ENTITY xx "yy">]>\n<r/>';
+ *   var rv = b.guardXml.validate(hostile, { profile: "strict" });
+ *   rv.ok;                                              // → false
+ *   rv.issues.some(function (i) { return i.kind === "doctype"; });  // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -315,6 +393,44 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardXml.sanitize
+ * @signature  b.guardXml.sanitize(input, opts?)
+ * @since      0.7.15
+ * @status     stable
+ * @related    b.guardXml.validate, b.guardXml.gate
+ *
+ * Best-effort cleanup of `input` (string of XML source): strips
+ * codepoint-class threats per policy (BOM, bidi when
+ * `bidiPolicy: "strip"`, C0 controls when `controlPolicy: "strip"`,
+ * null bytes when `nullBytePolicy: "strip"`, zero-width characters
+ * when `zeroWidthPolicy: "strip"`). Throws `GuardXmlError` on any
+ * critical issue — DOCTYPE / `<!ENTITY>` / external-entity / param-
+ * entity shapes have no safe sanitization (the only correct response
+ * is refusal). The error code matches the triggering rule
+ * (`xml.doctype`, `xml.entity`, `xml.external-entity`, etc.).
+ *
+ * Sanitize is intentionally narrow: it cleans the character-class
+ * surface but never rewrites structural XML. Use `b.guardXml.gate`
+ * for the full sanitize-or-refuse action chain inside a request
+ * pipeline.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   bidiPolicy:      "reject"|"strip"|"audit"|"allow",
+ *   controlPolicy:   "reject"|"strip"|"allow",
+ *   nullBytePolicy:  "reject"|"strip"|"allow",
+ *   zeroWidthPolicy: "reject"|"strip"|"audit"|"allow",
+ *
+ * @example
+ *   // Build hostile input programmatically so the source stays ASCII.
+ *   var ZWSP = String.fromCharCode(0x200B);
+ *   var clean = b.guardXml.sanitize("<root>hello" + ZWSP + "</root>", {
+ *     profile: "balanced",
+ *   });
+ *   clean.indexOf(ZWSP) === -1;                         // → true
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -334,6 +450,43 @@ function sanitize(input, opts) {
   return codepointClass.applyCharStripPolicies(input, opts);
 }
 
+/**
+ * @primitive  b.guardXml.gate
+ * @signature  b.guardXml.gate(opts?)
+ * @since      0.7.15
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardXml.validate, b.guardXml.sanitize, b.staticServe.create, b.fileUpload.create
+ *
+ * Build a `b.gateContract` gate suitable for plugging into
+ * `b.staticServe({ contentSafety: { ".xml": gate } })`,
+ * `b.fileUpload({ contentSafety: { "application/xml": 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 when DOCTYPE /
+ * ENTITY / external-entity policies are not `reject`, which strips
+ * codepoint-class threats only) → `refuse` (any of those structural
+ * policies is reject and a critical issue fired, or sanitize threw).
+ *
+ * Under strict and balanced both, DOCTYPE / ENTITY / external-entity
+ * are reject — so the gate jumps from `audit-only` straight to
+ * `refuse` for the XXE / billion-laughs class. Permissive allows
+ * downgrading XInclude / schemaLocation / PI / CDATA to `audit`,
+ * but never DOCTYPE / ENTITY / external-entity.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,    // gate identity for audit / observability
+ *
+ * @example
+ *   var xmlGate = b.guardXml.gate({ profile: "strict" });
+ *   var hostile = Buffer.from(
+ *     '<?xml version="1.0"?>\n<!DOCTYPE r [<!ENTITY a "b">]>\n<r/>',
+ *     "utf8");
+ *   var verdict = await xmlGate.check({ bytes: hostile });
+ *   verdict.action;                                     // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -365,13 +518,83 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardXml.buildProfile
+ * @signature  b.guardXml.buildProfile(opts)
+ * @since      0.7.15
+ * @status     stable
+ * @related    b.guardXml.gate, b.guardXml.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-xml key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardXml.buildProfile({
+ *     extends: "balanced",
+ *     cdataPolicy: "reject",
+ *     maxElements: 4096,
+ *   });
+ *   custom.cdataPolicy;                                 // → "reject"
+ *   custom.maxElements;                                 // → 4096
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardXml.compliancePosture
+ * @signature  b.guardXml.compliancePosture(name)
+ * @since      0.7.15
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardXml.gate, b.guardXml.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
+ * `GuardXmlError("xml.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardXml.compliancePosture("hipaa");
+ *   posture.doctypePolicy;                              // → "reject"
+ *   posture.forensicSnippetBytes;                       // → 256
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES, _err, "xml");
 }
 
 var _xmlRulePacks = gateContract.makeRulePackLoader(GuardXmlError, "xml");
+/**
+ * @primitive  b.guardXml.loadRulePack
+ * @signature  b.guardXml.loadRulePack(pack)
+ * @since      0.7.15
+ * @status     stable
+ * @related    b.guardXml.gate
+ *
+ * Register an operator-supplied rule pack with the guard-xml
+ * 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 `GuardXmlError("xml.bad-opt")` when `pack` is
+ * missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardXml.loadRulePack({
+ *     id: "soap-envelope",
+ *     rules: [
+ *       { id: "must-have-envelope", severity: "high",
+ *         detect: function (text) { return text.indexOf("<soap:Envelope") === -1; },
+ *         reason: "SOAP request missing soap:Envelope root" },
+ *     ],
+ *   });
+ *   pack.id;                                            // → "soap-envelope"
+ */
 var loadRulePack = _xmlRulePacks.load;
 
 module.exports = {