@blamejs/core 0.8.42 → 0.8.49

package/lib/guard-html.js

@@ -1,120 +1,95 @@
 "use strict";
 /**
- * guard-html — HTML content-safety primitive (b.guardHtml).
+ * @module b.guardHtml
+ * @nav    Guards
+ * @title  Guard Html
  *
- * Threat catalog grounded in 2026 sanitizer research (DOMPurify CVE-
- * series, OWASP XSS / DOM-Clobbering / HTML5 Security cheat sheets,
- * PortSwigger / Sonar / trace37 mXSS write-ups, html5sec.org).
+ * @intro
+ *   HTML / XSS defense — DOM-clobbering, mXSS, and entity-encoding
+ *   bypasses. Tag and attribute allowlists; URL-scheme allowlist on
+ *   every URL-bearing attribute; bidi / control / zero-width
+ *   stripping. Threat catalog grounded in 2026 sanitizer research
+ *   (DOMPurify CVE series, OWASP XSS / DOM-Clobbering / HTML5
+ *   Security cheat sheets, PortSwigger / Sonar / trace37 mXSS
+ *   write-ups, html5sec.org).
  *
- *   var rv = b.guardHtml.validate(input, { profile: "strict" });
- *   var safe = b.guardHtml.sanitize(input, { profile: "balanced" });
- *   var html = b.guardHtml.escapeText("<oops>");           // &lt;oops&gt;
- *   var attr = b.guardHtml.escapeAttr('say "hi"');         // say &quot;hi&quot;
- *   var g = b.guardHtml.gate({ profile: "strict" });
+ *   Three profiles ship — `strict` / `balanced` / `permissive` —
+ *   plus four compliance postures (`hipaa` / `pci-dss` / `gdpr` /
+ *   `soc2`) that compose on top via the strictest-wins rule.
+ *   `b.guardHtml.gate(opts)` returns a guard descriptor that plugs
+ *   into `b.fileUpload.contentSafety` / `b.staticServe.contentSafety`
+ *   / `b.guardAll`.
+ *
+ *   Threat catalog covered:
+ *
+ *     1. Dangerous tags — script / style / link / meta / base /
+ *        iframe / object / embed / applet / form / input / button /
+ *        textarea / select / isindex / marquee / blink / layer /
+ *        ilayer / plaintext / listing / xmp / audio / video / source
+ *        / track / math / svg / template / noscript / noembed /
+ *        noframes / portal / dialog / keygen / menuitem / command /
+ *        frame / frameset.
+ *     2. on* event-handler attributes — every attribute matching
+ *        /^on[a-z]/ is denied unconditionally.
+ *     3. Form-override attributes — formaction / formmethod /
+ *        formenctype / formtarget / formnovalidate (CWE-1021).
+ *     4. Iframe inline-HTML — srcdoc on iframe always denied.
+ *     5. Custom-element registration — `is="..."` always denied.
+ *     6. CSP-bypass-shaped attributes — nonce / integrity /
+ *        crossorigin stripped from sanitized output.
+ *     7. URL scheme validation on URL-bearing attributes — href /
+ *        src / action / cite / longdesc / manifest / archive /
+ *        codebase / data / classid / code / profile / ping / dynsrc
+ *        / lowsrc / background / poster / icon / xlink:href.
+ *        Per-profile allowlist; denied schemes (always):
+ *        javascript / vbscript / livescript / mocha / data (outside
+ *        image context) / file / mhtml / jar / intent / view-source.
+ *     8. CSS-injection inside style="..." values — expression( (IE),
+ *        behavior: (IE), -moz-binding (Firefox legacy), javascript: /
+ *        vbscript: / livescript: inside url(), @import, @namespace.
+ *     9. DOM clobbering — id and name attributes whose values match
+ *        a well-known JS global (document / window / location /
+ *        cookie / __proto__ / constructor / ...) on clobber-prone
+ *        elements (form / input / button / a / img / iframe /
+ *        object / embed / select / textarea).
+ *    10. mXSS hint detection — namespace-context-shift parents
+ *        (svg / math), CDATA inside HTML mode, template content
+ *        fragments with entity-encoded payloads.
+ *    11. Unicode bidi (CVE-2021-42574 Trojan Source) inside text
+ *        and attribute values.
+ *    12. C0 control characters, null bytes, zero-width chars —
+ *        strip-or-reject per profile.
+ *    13. IE conditional comments — <!--[if ...]>...<![endif]-->
+ *        refused in strict, stripped in balanced.
+ *    14. <base href> / <base target> — silently redirects every
+ *        relative URL on the page; always denied.
+ *    15. <meta http-equiv> with refresh / Set-Cookie / X-XSS-
+ *        Protection — silent navigation + cookie injection.
+ *    16. ARIA spoofing — flagged for audit when role mismatches
+ *        the semantic tag.
+ *    17. Image-context data: URLs — sanitize allows data:image/png
+ *        / jpeg / gif / webp; svg+xml requires explicit opt-in.
+ *    18. Total-document size cap, per-attribute-value size cap,
+ *        max-tag-depth (anti-recursion), max-attribute-count-per-
+ *        tag.
  *
- * Threat catalog covered:
- *
- *   1. Dangerous tags — <script>, <style>, <link>, <meta>, <base>,
- *      <iframe>, <object>, <embed>, <applet>, <form>, <input>,
- *      <button>, <textarea>, <select>, <isindex>, <marquee>, <blink>,
- *      <layer>, <ilayer>, <plaintext>, <listing>, <xmp>, <audio>,
- *      <video>, <source>, <track>, <math>, <svg>, <template>,
- *      <noscript>, <noembed>, <noframes>, <portal>, <dialog>,
- *      <keygen>, <menuitem>, <command>, <frame>, <frameset>.
- *      Every match per profile triggers refuse OR sanitize-strip.
- *
- *   2. on* event-handler attributes — every attribute matching
- *      /^on[a-z]/ is denied unconditionally. Catches the entire HTML5
- *      event-handler family (onclick, onerror, onload, onmouseover,
- *      onbeforeunload, onpaste, onwheel, onpointerdown, ontoggle, ...)
- *      without requiring a manual allowlist that rots the moment the
- *      WHATWG specs a new event.
- *
- *   3. Form-override attributes — formaction / formmethod /
- *      formenctype / formtarget / formnovalidate on <button> / <input>
- *      override the parent form's submission target (CWE-1021); always
- *      denied.
- *
- *   4. Iframe inline-HTML — srcdoc on <iframe> ships executable HTML
- *      directly into the document; always denied.
- *
- *   5. Custom-element registration — `is="..."` attribute mutates the
- *      element class via document.createElement(..., { is }); always
- *      denied.
- *
- *   6. CSP-bypass-shaped attributes — nonce, integrity, crossorigin
- *      stripped from sanitized output (operator-controlled only).
- *
- *   7. URL scheme validation on URL-bearing attributes — href, src,
- *      action, cite, longdesc, manifest, archive, codebase, data,
- *      classid, code, profile, ping, dynsrc, lowsrc, background,
- *      poster, icon, xlink:href. Per-attribute scheme allowlist:
- *      strict → http / https / mailto / tel only;
- *      balanced → +data:image/* + ftp;
- *      permissive → +ftp / sftp / ws / wss.
- *      Denied schemes (always): javascript / vbscript / livescript /
- *      mocha / data (outside image context) / file / mhtml / jar /
- *      intent / view-source.
- *
- *   8. CSS-injection inside style="..." attribute values — denies
- *      expression( (IE), behavior: (IE), -moz-binding (Firefox legacy),
- *      javascript: / vbscript: / livescript: inside url(), @import,
- *      @charset / @namespace (CSS-source-map confusion).
- *
- *   9. DOM clobbering — id and name attributes whose values match a
- *      well-known JS global (document, window, location, cookie,
- *      __proto__, constructor, ...) on form / input / button / anchor /
- *      img / iframe elements. Catches the form-element + input-name
- *      payload + named-property-access exfil chain.
- *
- *  10. mXSS hint detection — common parser-mode-shift vectors:
- *      <svg><p>...</svg>, <math><p>...</math>, <noscript>...</noscript>
- *      with quote+entity confusion, CDATA inside HTML mode, <template>
- *      content fragment with entity-encoded payloads. Surfaced as
- *      "mxss-hint" issues; refused in strict, audited in balanced.
- *
- *  11. Unicode bidi (CVE-2021-42574 Trojan Source) inside text and
- *      attribute values — same codepoint catalog as guard-csv.
- *
- *  12. C0 control characters, null bytes, zero-width chars in input —
- *      strip-or-reject per profile.
- *
- *  13. IE conditional comments — <!--[if ...]>...<![endif]--> can carry
- *      executable script in the legacy IE rendering path; refused in
- *      strict, stripped in balanced.
- *
- *  14. <base href> / <base target> — silently redirects every relative
- *      URL on the page; always denied.
- *
- *  15. <meta http-equiv> with refresh / Set-Cookie / X-XSS-Protection
- *      values — silent navigation + cookie injection; always denied.
- *
- *  16. ARIA spoofing — `role="button"` on a non-button element with
- *      attached event handlers (caught upstream by the on* handler
- *      strip); flagged for audit when role mismatches semantic tag.
- *
- *  17. Image-context data: URLs — sanitize allows data:image/png ;
- *      data:image/jpeg ; data:image/gif ; data:image/webp ;
- *      data:image/svg+xml requires explicit opt-in (svg embed is its
- *      own threat surface).
- *
- *  18. Total-document size cap (anti-DoS), per-attribute-value size
- *      cap, max-tag-depth (prevents recursion-shape parsers from
- *      stack-blowing), max-attribute-count-per-tag.
- *
- * Threat-detection regex literals are composed PROGRAMMATICALLY from
- * numeric codepoint range tables (BIDI_RANGES / C0_CTRL_RANGES /
- * ZERO_WIDTH_RANGES). Source file never embeds the attack characters
- * themselves.
- *
- * Sanitize discipline: this module ships a token-level rewriter that
- * preserves the allowlisted tag set and strips the rest. For HOSTILE
- * sources, the documented correct response is validate + reject — not
- * sanitize. mXSS bypasses against any non-DOM sanitizer are a known
- * arms-race; the gate's "refuse" path is the one with strong invariants.
- * Operators with display-of-untrusted-html requirements should
- * additionally serve content under a strict CSP (default-src 'none' or
- * sandboxed iframe).
+ *   Threat-detection regex literals are composed PROGRAMMATICALLY
+ *   from numeric codepoint range tables (BIDI_RANGES /
+ *   C0_CTRL_RANGES / ZERO_WIDTH_RANGES). The source file never
+ *   embeds the attack characters themselves.
+ *
+ *   Sanitize discipline: this module ships a token-level rewriter
+ *   that preserves the allowlisted tag set and strips the rest.
+ *   For HOSTILE sources, the documented correct response is
+ *   validate + reject — not sanitize. mXSS bypasses against any
+ *   non-DOM sanitizer are a known arms-race; the gate's `refuse`
+ *   path is the one with strong invariants. Operators with
+ *   display-of-untrusted-html requirements should additionally
+ *   serve content under a strict CSP (default-src 'none' or
+ *   sandboxed iframe).
+ *
+ * @card
+ *   HTML / XSS defense — DOM-clobbering, mXSS, and entity-encoding bypasses.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -376,8 +351,25 @@ function _resolveOpts(opts) {
   });
 }
 
-// HTML entity escape — text-content context. Encodes & < > " ' so the
-// output is safe for embedding inside an element's text body.
+/**
+ * @primitive b.guardHtml.escapeText
+ * @signature b.guardHtml.escapeText(value)
+ * @since     0.7.6
+ * @related   b.guardHtml.escapeAttr, b.guardHtml.sanitize
+ *
+ * HTML entity-escape for text-content context. Encodes the five
+ * core characters `&` `<` `>` `"` `'` so the result is safe to
+ * embed inside an element's text body. `null` / `undefined` coerce
+ * to an empty string. Use this for plain interpolation of
+ * untrusted strings into rendered HTML.
+ *
+ * @example
+ *   var html = b.guardHtml.escapeText("<oops>");
+ *   // → "&lt;oops&gt;"
+ *
+ *   var blank = b.guardHtml.escapeText(null);
+ *   // → ""
+ */
 function escapeText(value) {
   var s = value == null ? "" : String(value);
   return s
@@ -388,8 +380,25 @@ function escapeText(value) {
     .replace(/'/g, "&#39;");
 }
 
-// HTML entity escape — attribute-value context. Same encoding plus
-// backtick (legacy IE attribute terminator) and = (unquoted-attr edge).
+/**
+ * @primitive b.guardHtml.escapeAttr
+ * @signature b.guardHtml.escapeAttr(value)
+ * @since     0.7.6
+ * @related   b.guardHtml.escapeText, b.guardHtml.sanitize
+ *
+ * HTML entity-escape for attribute-value context. Same five
+ * characters as `escapeText` plus backtick (legacy IE attribute
+ * terminator) and `=` (unquoted-attribute edge). Use this when
+ * interpolating an untrusted string between double-quoted attribute
+ * delimiters.
+ *
+ * @example
+ *   var attr = b.guardHtml.escapeAttr('say "hi"');
+ *   // → "say &quot;hi&quot;"
+ *
+ *   var ie = b.guardHtml.escapeAttr("a`b=c");
+ *   // → "a&#96;b&#61;c"
+ */
 function escapeAttr(value) {
   var s = value == null ? "" : String(value);
   return s
@@ -905,6 +914,53 @@ function _sanitize(input, opts) {
 
 // ---- Public surface ----
 
+/**
+ * @primitive b.guardHtml.validate
+ * @signature b.guardHtml.validate(input, opts?)
+ * @since     0.7.6
+ * @related   b.guardHtml.sanitize, b.guardHtml.gate
+ *
+ * Tokenize `input` (string or Buffer of HTML) and walk every
+ * element / attribute against the resolved profile. Returns
+ * `{ ok, issues }` where `issues` is an array of
+ * `{ kind, severity, ruleId, location, snippet }` records.
+ * Never modifies the input — call `sanitize` for that. Anti-DoS
+ * caps (`maxBytes` / `maxAttrValueBytes` / `maxTagDepth` /
+ * `maxAttrsPerTag`) are validated as positive finite integers;
+ * passing `Infinity` throws.
+ *
+ * @opts
+ *   profile:            string,   // "strict" | "balanced" | "permissive"
+ *   compliancePosture:  string,   // "hipaa" | "pci-dss" | "gdpr" | "soc2"
+ *   allowedTags:        Array<string>,
+ *   allowedAttrs:       Array<string>,
+ *   urlSchemes:         Array<string>,
+ *   allowImageData:     boolean,
+ *   allowComments:      boolean,
+ *   bidiPolicy:         string,   // "reject" | "strip" | "audit"
+ *   controlPolicy:      string,
+ *   nullBytePolicy:     string,
+ *   zeroWidthPolicy:    string,
+ *   cssPolicy:          string,
+ *   domClobberPolicy:   string,
+ *   mxssHintPolicy:     string,
+ *   maxBytes:           number,
+ *   maxAttrValueBytes:  number,
+ *   maxTagDepth:        number,
+ *   maxAttrsPerTag:     number,
+ *
+ * @example
+ *   var rv = b.guardHtml.validate("<p>hi</p><script>alert(1)</script>",
+ *                                 { profile: "strict" });
+ *   rv.ok;                   // → false
+ *   rv.issues[0].kind;       // → "dangerous-tag"
+ *   rv.issues[0].severity;   // → "critical"
+ *
+ *   var clean = b.guardHtml.validate("<p>just text</p>",
+ *                                    { profile: "strict" });
+ *   clean.ok;                // → true
+ *   clean.issues.length;     // → 0
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -914,6 +970,46 @@ function validate(input, opts) {
   return gateContract.runIssueValidator(input, opts, _detectIssues);
 }
 
+/**
+ * @primitive b.guardHtml.sanitize
+ * @signature b.guardHtml.sanitize(input, opts?)
+ * @since     0.7.6
+ * @related   b.guardHtml.validate, b.guardHtml.gate
+ *
+ * Token-level rewriter that drops every tag NOT in the resolved
+ * profile's `allowedTags`, every attribute NOT in `allowedAttrs`,
+ * every URL whose scheme falls outside the profile allowlist,
+ * every event-handler / form-override / clobbering attribute, and
+ * every body of a body-drop tag (script / style / template / svg
+ * / math / iframe / object / embed / applet). For HOSTILE
+ * sources, prefer `validate` + `refuse` — `sanitize` is best
+ * effort against the documented arms-race.
+ *
+ * @opts
+ *   profile:            string,   // "strict" | "balanced" | "permissive"
+ *   compliancePosture:  string,   // "hipaa" | "pci-dss" | "gdpr" | "soc2"
+ *   allowedTags:        Array<string>,
+ *   allowedAttrs:       Array<string>,
+ *   urlSchemes:         Array<string>,
+ *   allowImageData:     boolean,
+ *   allowComments:      boolean,
+ *   maxBytes:           number,
+ *   maxAttrValueBytes:  number,
+ *   maxTagDepth:        number,
+ *   maxAttrsPerTag:     number,
+ *
+ * @example
+ *   var clean = b.guardHtml.sanitize(
+ *     "<p>hi</p><script>alert(1)</script>",
+ *     { profile: "balanced" });
+ *   // → "<p>hi</p>"
+ *
+ *   // Event-handler attribute is stripped, text content preserved.
+ *   var stripped = b.guardHtml.sanitize(
+ *     '<a href="https://example.com" onclick="alert(1)">go</a>',
+ *     { profile: "balanced" });
+ *   // → '<a href="https://example.com">go</a>'
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   var text = typeof input === "string"
@@ -925,6 +1021,46 @@ function sanitize(input, opts) {
   return _sanitize(text, opts);
 }
 
+/**
+ * @primitive b.guardHtml.gate
+ * @signature b.guardHtml.gate(opts?)
+ * @since     0.7.6
+ * @related   b.guardHtml.validate, b.guardHtml.sanitize, b.guardAll
+ *
+ * Returns a guard descriptor that plugs into the framework's
+ * content-safety wiring (`b.fileUpload.contentSafety` /
+ * `b.staticServe.contentSafety` / `b.guardAll`). The descriptor's
+ * `inspect(ctx)` resolves to one of four actions: `serve` (no
+ * issues), `audit-only` (low-severity issues observed), `sanitize`
+ * (sanitized buffer attached when no policy is "reject"), or
+ * `refuse` (critical issue with at least one reject-policy active).
+ *
+ * @opts
+ *   name:               string,
+ *   profile:            string,   // "strict" | "balanced" | "permissive"
+ *   compliancePosture:  string,   // "hipaa" | "pci-dss" | "gdpr" | "soc2"
+ *   mode:               string,   // "enforce" | "observe"
+ *   allowedTags:        Array<string>,
+ *   allowedAttrs:       Array<string>,
+ *   urlSchemes:         Array<string>,
+ *   bidiPolicy:         string,
+ *   controlPolicy:      string,
+ *   cssPolicy:          string,
+ *   domClobberPolicy:   string,
+ *   mxssHintPolicy:     string,
+ *   maxBytes:           number,
+ *   maxRuntimeMs:       number,
+ *
+ * @example
+ *   var g = b.guardHtml.gate({ profile: "strict" });
+ *   g.name;   // → "guardHtml:strict"
+ *
+ *   // Refuse on tag-budget exceeded — strict profile rejects <script>.
+ *   var hostileBuf = Buffer.from("<p>hi</p><script>alert(1)</script>", "utf8");
+ *   var rv = await g.inspect({ bytes: hostileBuf, contentType: "text/html" });
+ *   rv.ok;       // → false
+ *   rv.action;   // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -960,12 +1096,70 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive b.guardHtml.buildProfile
+ * @signature b.guardHtml.buildProfile(opts)
+ * @since     0.7.6
+ * @related   b.guardHtml.compliancePosture, b.guardHtml.gate
+ *
+ * Resolve a named profile against `PROFILES` and return the merged
+ * options bag. Operators introspecting the active limits (without
+ * calling `validate` / `sanitize` / `gate`) call this. Throws
+ * `GuardHtmlError` with code `html.bad-profile` when the name
+ * doesn't appear in the profile catalog.
+ *
+ * @opts
+ *   profile:  string,   // "strict" | "balanced" | "permissive"
+ *
+ * @example
+ *   var resolved = b.guardHtml.buildProfile({ profile: "strict" });
+ *   resolved.maxBytes;        // → 2097152  (2 MiB)
+ *   resolved.maxAttrValueBytes; // → 8192  (8 KiB)
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive b.guardHtml.compliancePosture
+ * @signature b.guardHtml.compliancePosture(name)
+ * @since     0.7.6
+ * @related   b.guardHtml.buildProfile, b.guardHtml.gate
+ *
+ * Return the option overlay for a named compliance posture
+ * (`hipaa` / `pci-dss` / `gdpr` / `soc2`). Operators compose this
+ * over a base profile to harden the default per regulatory regime.
+ * Throws `GuardHtmlError` with code `html.bad-posture` on unknown
+ * names.
+ *
+ * @example
+ *   var hipaa = b.guardHtml.compliancePosture("hipaa");
+ *   hipaa.bidiPolicy;       // → "reject"
+ *   hipaa.cssPolicy;        // → "reject"
+ *   hipaa.mxssHintPolicy;   // → "reject"
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES, _err, "html");
 }
 
+/**
+ * @primitive b.guardHtml.loadRulePack
+ * @signature b.guardHtml.loadRulePack(pack)
+ * @since     0.7.6
+ * @related   b.guardHtml.gate, b.guardHtml.buildProfile
+ *
+ * Register an operator-supplied rule pack (a versioned bundle of
+ * extra tag / attribute / scheme overrides) into the guard's
+ * private store. Subsequent `gate` calls referencing the pack by
+ * its `id` overlay these rules on top of the resolved profile.
+ * Validates pack shape and throws `GuardHtmlError` on malformed
+ * input.
+ *
+ * @example
+ *   b.guardHtml.loadRulePack({
+ *     id:      "kb-2026-html",
+ *     version: "1.0.0",
+ *     extraDangerousTags: ["custom-element"],
+ *   });
+ */
 var _htmlRulePacks = gateContract.makeRulePackLoader(GuardHtmlError, "html");
 var loadRulePack = _htmlRulePacks.load;