@blamejs/core 0.8.43 → 0.8.50

package/lib/guard-jwt.js

@@ -1,36 +1,74 @@
 "use strict";
 /**
- * guard-jwt — JWT identifier-safety primitive (b.guardJwt).
+ * @module b.guardJwt
+ * @nav    Guards
+ * @title  Guard Jwt
  *
- * Validates user-supplied JWT compact-serialization strings against
- * the canonical CVE-class refuse list before hand-off to a verifier.
- * KIND="identifier" — consumes ctx.identifier (or ctx.token).
+ * @intro
+ *   JWT identifier-safety guard — validates user-supplied JWT
+ *   compact-serialization strings against the canonical CVE-class
+ *   refuse list BEFORE hand-off to a signature verifier. KIND is
+ *   `identifier`; the gate consumes `ctx.identifier` (or
+ *   `ctx.token` / `ctx.jwt`). Pair with `b.auth.jwt.verifyExternal`
+ *   for cryptographic verification — this layer is the shape /
+ *   header / claims contract that runs before any HMAC or signature
+ *   work.
  *
- * Threat catalog:
- *   - Shape malformation — not 3 dot-separated base64url segments
- *     (RFC 7515 §3 / RFC 7519 §3 compact serialization).
- *   - alg=none — RFC 7518 §3.6 explicit "no signature" — universally
- *     refused; the canonical alg-confusion CVE class
- *     (CVE-2015-9235 jsonwebtoken; CVE-2018-0114 java-jwt).
- *   - alg algorithm-confusion — operator's verifier may treat HS256
- *     with an RSA public key as HMAC, allowing forgery; flag any
- *     unexpected alg.
- *   - kid path traversal — kid header used by some operators to
- *     resolve key files; `..` / `/` / null-byte in kid would escape
- *     the keystore directory.
- *   - typ confusion — typ != "jwt" / "JWT" / "JWS" indicates a non-
- *     JWT token coerced into the slot.
- *   - Oversized header / payload / signature — defense against
- *     decompression bombs and parser DoS.
- *   - exp / nbf / iat sanity — exp in the past, nbf in the far
- *     future, iat way in the future all indicate replay or clock-
- *     skew issues.
- *   - Unknown crit fields — RFC 7515 §4.1.11 — operator MUST refuse
- *     tokens carrying crit headers it doesn't understand.
- *   - BIDI / null / control / zero-width universal refuse.
+ *   Algorithm-confusion defense: `alg=none` is universally refused
+ *   at every profile (RFC 7518 §3.6 explicit-no-signature, the
+ *   canonical CVE-2015-9235 jsonwebtoken / CVE-2018-0114 java-jwt
+ *   class). The operator-supplied `allowedAlgs` allowlist defaults
+ *   to the framework's PQC-first set (ML-DSA-87 / ML-DSA-65 /
+ *   ML-DSA-44 / SLH-DSA-SHAKE-256{f,s} / SLH-DSA-SHA2-256{f,s} /
+ *   EdDSA / ES* / RS* / PS*) so HS256-against-RSA-public-key
+ *   forgery is blocked before the verifier sees the token.
  *
- *   var rv = b.guardJwt.validate(jwtString, { profile: "strict" });
- *   var g  = b.guardJwt.gate({ profile: "strict" });
+ *   `kid` path-traversal defense: the gate refuses any header `kid`
+ *   that contains `..`, `/`, `\`, or percent-encoded variants —
+ *   operators that resolve `kid` to a filesystem path can't escape
+ *   the keystore directory. The standalone `b.guardJwt.kidSafe(kid)`
+ *   helper throws on the same indicators and is the contract every
+ *   `keyResolver` implementation must enforce before reading a key
+ *   file.
+ *
+ *   Bounded shape: header / payload / signature segments each have
+ *   their own byte cap (`maxHeaderBytes` / `maxPayloadBytes` /
+ *   `maxSignatureBytes`) and the total token is bounded by
+ *   `maxBytes`. Decompression-bomb-shaped tokens fail at the cap
+ *   check before any base64url decode. Header JSON is parsed
+ *   through `b.safeJson.parse({ rejectProto: true })` so prototype
+ *   pollution can't ride a forged header.
+ *
+ *   Claim sanity: `exp` in the past, `nbf` more than
+ *   `nbfFutureSlackMs` in the future, and `iat` more than
+ *   `iatFutureSlackMs` in the future all surface as issues —
+ *   replay / clock-skew detection that doesn't require pulling in
+ *   a verifier. Required-claims (`iss` / `exp` / `iat` at strict;
+ *   `iss` / `exp` at balanced) are enforced before the verifier
+ *   so missing-claim refusals fail fast.
+ *
+ *   `typ` confusion: any `typ` outside `jwt` / `jws` / `at+jwt` /
+ *   `id_token` flags as suspect — non-JWT tokens coerced into a
+ *   JWT slot are refused under strict, audited under balanced.
+ *
+ *   `crit` discipline: RFC 7515 §4.1.11 mandates refusing tokens
+ *   that carry `crit` headers the verifier doesn't understand. The
+ *   gate's `knownCrit` allowlist is empty by default — every
+ *   `crit` field is unknown unless the operator opts a name in.
+ *
+ *   Audience verification is the operator's responsibility (the
+ *   verifier handles it); the guard's required-claims list ensures
+ *   the operator can't forget to populate `aud` in their verifier
+ *   config because the claim must be present at validate time.
+ *
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`. BIDI / null /
+ *   control / zero-width universal-refuse applies on the raw input
+ *   string at every profile so trojan-source codepoints can't ride
+ *   inside a base64url segment.
+ *
+ * @card
+ *   JWT identifier-safety guard — validates user-supplied JWT compact-serialization strings against the canonical CVE-class refuse list BEFORE hand-off to a signature verifier.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -393,6 +431,64 @@ function _detectIssues(input, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardJwt.validate
+ * @signature  b.guardJwt.validate(input, opts?)
+ * @since      0.7.49
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardJwt.sanitize, b.guardJwt.gate, b.auth.jwt.verifyExternal
+ *
+ * Apply the full guard-jwt threat catalog to a JWT compact-
+ * serialization string. Returns `{ ok, issues, refusal? }` per
+ * `gateContract.aggregateIssues`. Detected classes include
+ * `alg-none` (always critical), `kid-traversal` (always critical),
+ * `alg-not-allowed`, `typ-confusion`, `crit-unknown`, `exp-past`,
+ * `nbf-far-future`, `iat-far-future`, `claim-missing`, plus the
+ * shape (`jwt-shape`) / segment-cap (`header-cap` / `payload-cap`
+ * / `signature-cap`) / total-cap (`jwt-cap`) / codepoint-class
+ * issues. Header JSON is decoded through
+ * `b.safeJson.parse({ rejectProto: true })` so prototype-pollution
+ * keys are refused before any policy check runs. Operator-supplied
+ * opts are bounds-checked; bad opts throw
+ * `GuardJwtError("jwt.bad-opt")`.
+ *
+ * @opts
+ *   profile:              "strict"|"balanced"|"permissive",
+ *   compliance:           "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   allowedAlgs:          string[],
+ *   requiredClaims:       string[],
+ *   knownCrit:            string[],
+ *   algNonePolicy:        "reject"|"audit"|"allow",
+ *   algAllowlistPolicy:   "reject"|"audit"|"allow",
+ *   kidTraversalPolicy:   "reject"|"audit"|"allow",
+ *   typConfusionPolicy:   "reject"|"audit"|"allow",
+ *   expSanityPolicy:      "reject"|"audit"|"allow",
+ *   nbfSanityPolicy:      "reject"|"audit"|"allow",
+ *   iatSanityPolicy:      "reject"|"audit"|"allow",
+ *   critUnknownPolicy:    "reject"|"audit"|"allow",
+ *   nbfFutureSlackMs:     number,
+ *   iatFutureSlackMs:     number,
+ *   maxHeaderBytes:       number,
+ *   maxPayloadBytes:      number,
+ *   maxSignatureBytes:    number,
+ *   maxBytes:             number,
+ *
+ * @example
+ *   var algNoneToken =
+ *     "eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0." +
+ *     "eyJzdWIiOiJhdHRhY2tlciJ9.";
+ *   var rv = b.guardJwt.validate(algNoneToken, { profile: "strict" });
+ *   rv.ok;                                              // → false
+ *   rv.issues[0].ruleId;                                // → "jwt.alg-none"
+ *
+ *   var benign =
+ *     "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9." +
+ *     "eyJpc3MiOiJleGFtcGxlIiwiZXhwIjo5OTk5OTk5OTk5LCJpYXQiOjE3MDAwMDAwMDB9." +
+ *     "sig";
+ *   var ok = b.guardJwt.validate(benign, { profile: "strict" });
+ *   ok.ok;                                              // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -410,6 +506,36 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardJwt.sanitize
+ * @signature  b.guardJwt.sanitize(input, opts?)
+ * @since      0.7.49
+ * @status     stable
+ * @related    b.guardJwt.validate, b.guardJwt.gate
+ *
+ * Pass-through-or-throw form of `validate`. JWT compact
+ * serialization can't be repaired (every byte feeds the signature)
+ * so sanitize either returns the input unchanged when the issue
+ * list contains no `critical` / `high` entries, or throws
+ * `GuardJwtError` carrying the offending `ruleId`. Use this when
+ * the caller wants a single try/catch boundary instead of an
+ * issue-list switch.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ...:        every guardJwt.validate opt is honored,
+ *
+ * @example
+ *   var algNoneToken =
+ *     "eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0." +
+ *     "eyJzdWIiOiJhdHRhY2tlciJ9.";
+ *   try {
+ *     b.guardJwt.sanitize(algNoneToken, { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                           // → "jwt.alg-none"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -427,6 +553,39 @@ function sanitize(input, opts) {
   return input;
 }
 
+/**
+ * @primitive  b.guardJwt.gate
+ * @signature  b.guardJwt.gate(opts?)
+ * @since      0.7.49
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardJwt.validate, b.guardJwt.sanitize, b.middleware.bearerAuth
+ *
+ * Build a `gateContract.buildGuardGate`-shaped gate that pulls
+ * `ctx.identifier` (or `ctx.token` / `ctx.jwt`) and dispatches to
+ * `validate`. Returns `{ ok: true, action: "serve" }` when the
+ * issue list is empty, `{ ok: true, action: "audit-only", issues }`
+ * when only low-severity issues fire, and `{ ok: false, action:
+ * "refuse", issues }` on any `critical` / `high` issue. Compose
+ * into auth pipelines via `b.middleware.bearerAuth` so every
+ * bearer token is shape-checked before signature verification.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,            // gate label for audit trails
+ *   ...:        every guardJwt.validate opt is honored,
+ *
+ * @example
+ *   var jwtGate = b.guardJwt.gate({ profile: "strict" });
+ *   var rv = await jwtGate.run({
+ *     identifier:
+ *       "eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0." +
+ *       "eyJzdWIiOiJhdHRhY2tlciJ9.",
+ *   });
+ *   rv.action;                                          // → "refuse"
+ *   rv.issues[0].ruleId;                                // → "jwt.alg-none"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -450,18 +609,113 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardJwt.buildProfile
+ * @signature  b.guardJwt.buildProfile(opts)
+ * @since      0.7.49
+ * @status     stable
+ * @related    b.guardJwt.gate, b.guardJwt.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, and inline `opts` keys win last.
+ * Operators stage profile overlays here so the final shape is
+ * traceable to a baseline rather than a hand-typed dictionary.
+ *
+ * @opts
+ *   extends: string|string[],   // base profile name(s) to compose
+ *   ...:     any guardJwt key,  // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardJwt.buildProfile({
+ *     extends: "balanced",
+ *     algAllowlistPolicy: "reject",
+ *     allowedAlgs: ["ES256", "EdDSA"],
+ *   });
+ *   custom.algAllowlistPolicy;                          // → "reject"
+ *   custom.allowedAlgs.indexOf("ES256");                // → 0
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardJwt.compliancePosture
+ * @signature  b.guardJwt.compliancePosture(name)
+ * @since      0.7.49
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardJwt.gate, b.guardJwt.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
+ * `GuardJwtError("jwt.bad-posture")` on unknown name. Postures
+ * extend the strict profile (or balanced for `gdpr`) with a
+ * `forensicSnippetBytes` cap appropriate to the regime.
+ *
+ * @example
+ *   var posture = b.guardJwt.compliancePosture("hipaa");
+ *   posture.algNonePolicy;                              // → "reject"
+ *   posture.forensicSnippetBytes;                       // → 256
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "jwt");
 }
 
 var _jwtRulePacks = gateContract.makeRulePackLoader(GuardJwtError, "jwt");
+/**
+ * @primitive  b.guardJwt.loadRulePack
+ * @signature  b.guardJwt.loadRulePack(pack)
+ * @since      0.7.49
+ * @status     stable
+ * @related    b.guardJwt.gate
+ *
+ * Register an operator-supplied rule pack with the guard-jwt
+ * 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 `GuardJwtError("jwt.bad-opt")`
+ * when `pack` is missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardJwt.loadRulePack({
+ *     id: "tenant-issuer-pin",
+ *     rules: [
+ *       { id: "iss-pin", severity: "high",
+ *         detect: function (claims) { return claims.iss !== "https://idp.example/"; },
+ *         reason: "tenant pins iss to a single IdP" },
+ *     ],
+ *   });
+ *   pack.id;                                            // → "tenant-issuer-pin"
+ */
 var loadRulePack = _jwtRulePacks.load;
 
-// Operator helper — `kidSafe(kid)` throws on traversal indicators.
-// Documented as the contract for keyResolver implementations.
+/**
+ * @primitive  b.guardJwt.kidSafe
+ * @signature  b.guardJwt.kidSafe(kid)
+ * @since      0.7.49
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardJwt.validate, b.auth.jwt.verifyExternal
+ *
+ * Throw on any `kid` value that contains path-traversal indicators
+ * (`..`, `/`, `\`, percent-encoded variants) or non-printable
+ * control bytes. Returns the input unchanged on success. This is
+ * the contract every operator `keyResolver` MUST run before
+ * resolving `kid` to a filesystem path or KMS key handle —
+ * without it, a forged token's `kid` can escape the keystore
+ * directory.
+ *
+ * @example
+ *   b.guardJwt.kidSafe("tenant-1-2026-05");             // → "tenant-1-2026-05"
+ *
+ *   try {
+ *     b.guardJwt.kidSafe("../../etc/passwd");
+ *   } catch (e) {
+ *     e.code;                                           // → "jwt.kid-traversal"
+ *   }
+ */
 function kidSafe(kid) {
   if (typeof kid !== "string" || kid.length === 0) {
     throw _err("jwt.kid-empty", "kid must be a non-empty string");

package/lib/guard-markdown.js

@@ -1,30 +1,41 @@
 "use strict";
 /**
- * guard-markdown — Markdown content-safety primitive (b.guardMarkdown).
+ * @module b.guardMarkdown
+ * @nav    Guards
+ * @title  Guard Markdown
  *
- * Threat catalog grounded in current research:
- *   - CVE-2026-30838 — CommonMark DisallowedRawHtml whitespace-tag bypass
- *     (`<script\n>` / `<script\t>` evades naive `<script>` matchers; the
- *     browser still treats the tag as a script element).
- *   - CVE-2025-9540 — Markup Markdown stored XSS via link with javascript:.
- *   - CVE-2025-7969 — markdown-it ReDoS class.
- *   - CVE-2025-6493 — CodeMirror Markdown Mode catastrophic backtracking.
- *   - CVE-2025-24981 — MDC Markdown XSS via unsanitized autolinks.
- *   - CVE-2026-33500 — AVideo Parsedown link XSS via inlineLink/inlineUrlTag
- *     bypass (ParsedownSafeWithLinks didn't override link emitters).
- *   - GHSA-gwjh-c548-f787 — NuGetGallery autolink XSS.
- *   - Joplin GHSA-hff8-hjwv-j9q7 — RCE via untrusted markdown link.
+ * @intro
+ *   CommonMark validator + sanitizer for user-supplied markdown.
+ *   Refuses raw HTML by default, applies a URL-scheme allowlist on
+ *   inline links / autolinks / images / reference defs, and caps
+ *   image dimensions and structural depth to defang renderer DoS.
+ *   KIND="content" — the gate consumes `ctx.bytes` /
+ *   `ctx.bodyText`.
  *
- * The primitive is a SOURCE-LEVEL gate: it inspects raw markdown text
- * BEFORE any downstream renderer (marked / markdown-it / commonmark /
- * remark / parsedown) sees it. Source-level discipline matters because
- * the most dangerous shapes — `__proto__` in JSON, `<script\n>` in
- * markdown — exploit specific parser internals; sanitizing on the
- * post-parse tree is too late.
+ *   The primitive is a SOURCE-LEVEL gate: it inspects raw markdown
+ *   text BEFORE any downstream renderer (marked / markdown-it /
+ *   commonmark / remark / parsedown) sees it. Source-level
+ *   discipline matters because the most dangerous shapes —
+ *   `__proto__` in JSON, `<script\n>` in markdown — exploit
+ *   specific parser internals; sanitizing on the post-parse tree
+ *   is too late.
  *
- *   var rv = b.guardMarkdown.validate(input, { profile: "strict" });
- *   var safe = b.guardMarkdown.sanitize(input, { profile: "balanced" });
- *   var g = b.guardMarkdown.gate({ profile: "strict" });
+ *   Threat catalog grounded in current CVE research:
+ *   CVE-2026-30838 (CommonMark DisallowedRawHtml whitespace-tag
+ *   bypass — `<script\n>` / `<script\t>` evades naive `<script>`
+ *   matchers); CVE-2025-9540 (Markup Markdown stored XSS via
+ *   `javascript:` link); CVE-2025-7969 (markdown-it ReDoS class);
+ *   CVE-2025-6493 (CodeMirror Markdown Mode catastrophic
+ *   backtracking); CVE-2025-24981 (MDC autolink XSS);
+ *   CVE-2026-33500 (AVideo Parsedown inlineLink/inlineUrlTag
+ *   bypass); GHSA-gwjh-c548-f787 (NuGetGallery autolink XSS);
+ *   Joplin GHSA-hff8-hjwv-j9q7 (RCE via untrusted markdown link).
+ *
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`.
+ *
+ * @card
+ *   CommonMark validator + sanitizer for user-supplied markdown.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -477,6 +488,55 @@ function _detectIssues(input, opts) {
 
 // ---- Public surface ----
 
+/**
+ * @primitive  b.guardMarkdown.validate
+ * @signature  b.guardMarkdown.validate(input, opts?)
+ * @since      0.7.16
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardMarkdown.sanitize, b.guardMarkdown.gate
+ *
+ * Inspect raw markdown source 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 `markdown.bad-input` issue
+ * rather than throwing — callers that prefer an exception use
+ * `b.guardMarkdown.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",
+ *   dangerousTagPolicy:     "reject"|"strip"|"audit"|"allow",
+ *   dangerousSchemePolicy:  "reject"|"strip"|"audit"|"allow",
+ *   imageSchemePolicy:      "reject"|"strip"|"audit"|"allow",
+ *   autolinkSchemePolicy:   "reject"|"strip"|"audit"|"allow",
+ *   referenceLinkPolicy:    "reject"|"strip"|"audit"|"allow",
+ *   codeFenceLangPolicy:    "reject"|"strip"|"audit"|"allow",
+ *   doctypePolicy:          "reject"|"strip"|"audit"|"allow",
+ *   schemeAllowlist:        string[],   // default ["http","https","mailto"]
+ *   maxBytes:               number,
+ *   maxLines:               number,
+ *   maxLinks:               number,
+ *   maxImages:              number,
+ *   maxAutolinks:           number,
+ *   maxRefDefs:             number,
+ *   maxListDepth:           number,
+ *   maxBlockquoteDepth:     number,
+ *
+ * @example
+ *   var rv = b.guardMarkdown.validate("# hello\n\n[link](https://example.com)",
+ *                                     { profile: "strict" });
+ *   rv.ok;                                             // → true
+ *
+ *   var bad = b.guardMarkdown.validate("[click](javascript:alert(1))",
+ *                                      { profile: "strict" });
+ *   bad.ok;                                            // → false
+ *   bad.issues[0].ruleId;                              // → "markdown.dangerous-scheme"
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -493,6 +553,36 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardMarkdown.sanitize
+ * @signature  b.guardMarkdown.sanitize(input, opts?)
+ * @since      0.7.16
+ * @status     stable
+ * @related    b.guardMarkdown.validate, b.guardMarkdown.gate
+ *
+ * Strip BIDI / zero-width / control / null-byte codepoints under
+ * their resolved policies and return the cleaned markdown source.
+ * Throws `GuardMarkdownError` when any `critical` issue fires
+ * (raw `<script>`, `javascript:` link, doctype injection). Use
+ * `validate` to inspect issues without throwing.
+ *
+ * @opts
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ...:                    same shape as b.guardMarkdown.validate opts,
+ *
+ * @example
+ *   var clean = b.guardMarkdown.sanitize("hello\u200Bworld",
+ *                                        { profile: "balanced" });
+ *   clean;                                             // → "helloworld"
+ *
+ *   try {
+ *     b.guardMarkdown.sanitize("<script>alert(1)</script>",
+ *                              { profile: "strict" });
+ *   } catch (e) {
+ *     e.code;                                          // → "markdown.dangerous-tag"
+ *   }
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -508,6 +598,36 @@ function sanitize(input, opts) {
   return codepointClass.applyCharStripPolicies(input, opts);
 }
 
+/**
+ * @primitive  b.guardMarkdown.gate
+ * @signature  b.guardMarkdown.gate(opts?)
+ * @since      0.7.16
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardMarkdown.validate, b.guardMarkdown.sanitize, b.guardAll.gate, b.staticServe.create
+ *
+ * Build an async gate `(ctx) -> { ok, action, issues }` consumable
+ * by `b.guardAll`, `b.staticServe`, `b.fileUpload`, and any host
+ * that ingests user-supplied markdown. The gate decodes
+ * `ctx.bytes` / `ctx.bodyText`, runs `validate`, and maps
+ * severity to action: zero issues `serve`; only low/medium
+ * `audit-only`; sanitizable issues `sanitize` (returning the
+ * cleaned bytes); any unfixable critical `refuse`.
+ *
+ * @opts
+ *   name:                   string,    // gate label for audit / observability
+ *   profile:                "strict"|"balanced"|"permissive",
+ *   compliance:             "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ...:                    same shape as b.guardMarkdown.validate opts,
+ *
+ * @example
+ *   var g = b.guardMarkdown.gate({ profile: "strict" });
+ *   var rv = await g({ bytes: Buffer.from("# hello\n", "utf8") });
+ *   rv.action;                                         // → "serve"
+ *
+ *   var bad = await g({ bytes: Buffer.from("[x](javascript:1)", "utf8") });
+ *   bad.action;                                        // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -547,13 +667,75 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardMarkdown.buildProfile
+ * @signature  b.guardMarkdown.buildProfile(opts)
+ * @since      0.7.16
+ * @status     stable
+ * @related    b.guardMarkdown.gate, b.guardMarkdown.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-markdown key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardMarkdown.buildProfile({
+ *     extends: "balanced",
+ *     dangerousTagPolicy: "strip",
+ *     schemeAllowlist: ["http", "https"],
+ *   });
+ *   custom.dangerousTagPolicy;                         // → "strip"
+ *   custom.schemeAllowlist.indexOf("mailto");          // → -1
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardMarkdown.compliancePosture
+ * @signature  b.guardMarkdown.compliancePosture(name)
+ * @since      0.7.16
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardMarkdown.gate, b.guardMarkdown.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
+ * `GuardMarkdownError("markdown.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardMarkdown.compliancePosture("hipaa");
+ *   posture.dangerousTagPolicy;                        // → "reject"
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES, _err, "markdown");
 }
 
 var _markdownRulePacks = gateContract.makeRulePackLoader(GuardMarkdownError, "markdown");
+/**
+ * @primitive  b.guardMarkdown.loadRulePack
+ * @signature  b.guardMarkdown.loadRulePack(pack)
+ * @since      0.7.16
+ * @status     stable
+ * @related    b.guardMarkdown.gate
+ *
+ * Register an operator-supplied rule pack with the guard-markdown
+ * 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
+ * `GuardMarkdownError("markdown.bad-opt")` when `pack` is missing
+ * or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardMarkdown.loadRulePack({
+ *     id: "wiki-internal",
+ *     extraSchemeAllowlist: ["wiki"],
+ *   });
+ *   pack.id;                                           // → "wiki-internal"
+ */
 var loadRulePack = _markdownRulePacks.load;
 
 module.exports = {