@blamejs/core 0.8.43 → 0.8.49

package/lib/guard-yaml.js

@@ -1,59 +1,68 @@
 "use strict";
 /**
- * guard-yaml — YAML content-safety primitive (b.guardYaml).
+ * @module b.guardYaml
+ * @nav    Guards
+ * @title  Guard Yaml
  *
- * Threat catalog grounded in current research (multiple 2025-2026
- * deserialization + DoS CVEs in popular YAML libraries):
- *   - CVE-2026-24009 Docling / PyYAML unsafe load → RCE
- *   - CVE-2026-27807 MarkUs YAML alias billion-laughs DoS
- *   - CVE-2025-68664 LangChain deserialization → RCE
- *   - CVE-2025-61301 / CVE-2025-61303 YAML library DoS family
- *     ("Laughter in the Wild" study across 14 libraries / 10 languages)
- *   - CVE-2022-1471 SnakeYAML constructor RCE
- *   - CVE-2020-1747 / CVE-2020-14343 PyYAML FullLoader RCE chain
- *   - CVE-2017-18342 PyYAML python/object/apply RCE
+ * @intro
+ *   YAML content-safety guard — defends against the type-coercion,
+ *   deserialization, and DoS catalog operators face when accepting
+ *   YAML sourced from user input. All detection runs at the SOURCE
+ *   level: the operator's downstream parser may be PyYAML, SnakeYAML,
+ *   js-yaml, libyaml, or another implementation, and the guard
+ *   refuses hostile inputs before any parser sees them.
  *
- *   var rv = b.guardYaml.validate(input, { profile: "strict" });
- *   var safe = b.guardYaml.parse(input, { profile: "strict" });
- *   var g = b.guardYaml.gate({ profile: "strict" });
+ *   Tag-injection RCE defense: language-specific deserialization tag
+ *   prefixes (`!!python/` / `!!java.` / `!!ruby/` / `!!perl/` /
+ *   `!!js/` / `!!cs/` / `!!net/` / `!!system.`) plus the `!!apply` /
+ *   `!!new` / `!!eval` / `!!exec` family are refused regardless of
+ *   profile under strict. CVE coverage: CVE-2026-24009 Docling/PyYAML
+ *   unsafe load, CVE-2025-68664 LangChain deserialization, CVE-2022-
+ *   1471 SnakeYAML constructor RCE, CVE-2020-1747 / CVE-2020-14343
+ *   PyYAML FullLoader, CVE-2017-18342 python/object/apply.
  *
- * Threat catalog covered (all source-level — operator's downstream
- * parser may be pyyaml/snakeyaml/js-yaml; the guard refuses hostile
- * sources before any parser sees them):
+ *   YAML 1.1 vs 1.2 type-coercion attacks: PyYAML and libyaml still
+ *   default to YAML 1.1 in 2026, which treats unquoted `no` / `yes`
+ *   / `y` / `n` / `on` / `off` as booleans (the "Norway problem" —
+ *   country code "NO" parses as false), and `0777`-shaped numerics
+ *   parse as octal. These shapes are flagged at the source so
+ *   operators can refuse silently coerced values.
  *
- *   1. Tag-injection RCE — language-specific deserialization tags
- *      with prefixes !!python/ / !!java. / !!ruby/ / !!perl/ / !!js/
- *      / !!cs/ / !!net/ / !!system. and the !!apply / !!new family.
- *      Refused regardless of profile under strict.
+ *   Anchor-bomb (billion laughs) detection: `&anchor` declares,
+ *   `*alias` references, recursive aliasing amplifies a small input
+ *   into GiB on parse. Caps via `maxAnchors` + `maxAliasDepth` +
+ *   `maxNodes`, plus an explicit alias-amplification ratio
+ *   (aliases / anchors >= 8 fires `alias-explosion`) catches the
+ *   exponential expansion shape independent of absolute counts.
+ *   CVE-2026-27807 MarkUs / CVE-2025-61301 / CVE-2025-61303 ("Laughter
+ *   in the Wild" — 14 libraries / 10 languages) exemplify the family.
  *
- *   2. Anchor / alias recursion (billion laughs) — &anchor declares,
- *      *alias references. Recursive aliasing amplifies a small input
- *      into GiB on parse. Caps via maxAnchors + maxAliasDepth + total
- *      node count.
+ *   Custom-tag exec surface: local `!Foo` and global `!!Bar` user
+ *   tags suggest a non-safe parser is downstream even when the tag
+ *   isn't on the language-specific deserialization denylist. Flagged
+ *   per profile.
  *
- *   3. Multi-document streams — operators expecting a single doc
- *      silently get the first one and ignore the rest, which can mask
- *      hostile content.
+ *   Merge-key chain DoS: `<<: *anchor` invokes the YAML 1.1 merge-
+ *   key spec; chains of merge keys against deeply nested anchors are
+ *   an additional anchor-chain expansion vector.
  *
- *   4. Norway problem — YAML 1.1 (still default in pyyaml + libyaml
- *      in 2026) treats unquoted no/yes/y/n/on/off as booleans. Country
- *      code "NO" → false.
+ *   Multi-document streams: operators expecting a single doc silently
+ *   receive only the first one and ignore the rest — hostile content
+ *   in subsequent docs slips past validation that ran on the first.
+ *   The guard refuses `multiDocPolicy === "reject"` and caps via
+ *   `maxDocuments`.
  *
- *   5. Leading-zero octals — 0777 parses as octal 511 in YAML 1.1.
+ *   Duplicate-key smuggling, BOM placement, and bidi / null / control
+ *   / zero-width character threats route through the same shared
+ *   detector backing the guard-json / guard-csv families.
  *
- *   6. Duplicate keys — YAML 1.2 SHOULD-unique; parsers silently
- *      last-wins, same threat shape as JSON duplicate-key smuggling.
+ *   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. Local + custom user tags — even when not language-specific,
- *      surface that suggests a non-safe parser is downstream.
- *
- *   8. Merge-key chain depth (<<: *anchor) — anchor-chain DoS.
- *
- *   9. Bidi / null / control / zero-width chars in scalar values.
- *
- *  10. Anti-DoS caps — total document size, total node count, max
- *      anchors, max alias depth, max document count, max scalar
- *      length, max depth.
+ * @card
+ *   YAML content-safety guard — defends against the type-coercion, deserialization, and DoS catalog operators face when accepting YAML sourced from user input.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -433,6 +442,60 @@ function _detectDuplicateKeysYaml(text) {
 
 // ---- Public surface ----
 
+/**
+ * @primitive  b.guardYaml.validate
+ * @signature  b.guardYaml.validate(input, opts?)
+ * @since      0.7.14
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardYaml.parse, b.guardYaml.gate
+ *
+ * Inspect `input` (string of YAML source) for the full guard-yaml
+ * threat catalog without committing to a parsed value. Returns
+ * `{ ok, issues, severities }` where `issues` is the aggregated
+ * detector output — every dangerous-tag prefix, custom-tag use,
+ * anchor / alias amplification, multi-document split, Norway-
+ * problem implicit boolean, leading-zero octal, merge-key chain,
+ * duplicate-key smuggle, codepoint-class threat, and parse failure
+ * is reported with `kind` / `severity` / `ruleId` / `snippet`.
+ * Profile-driven (`strict` / `balanced` / `permissive`) and posture-
+ * driven (`hipaa` / `pci-dss` / `gdpr` / `soc2`).
+ *
+ * Detection runs at the source level so the operator's downstream
+ * parser (PyYAML / SnakeYAML / js-yaml / libyaml) need not be
+ * consulted to identify hostile shapes. A final pass tries the safe-
+ * yaml parser and surfaces parse failure as a critical issue.
+ *
+ * @opts
+ *   profile:             "strict"|"balanced"|"permissive",
+ *   compliance:          "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   tagPolicy:           "reject"|"audit"|"allow",
+ *   aliasPolicy:         "reject"|"audit"|"allow",
+ *   multiDocPolicy:      "reject"|"audit"|"allow",
+ *   norwayPolicy:        "reject"|"audit"|"allow",
+ *   leadingZeroPolicy:   "reject"|"audit"|"allow",
+ *   duplicateKeyPolicy:  "reject"|"audit"|"allow",
+ *   mergeKeyPolicy:      "reject"|"audit"|"allow",
+ *   bidiPolicy:          "reject"|"strip"|"audit"|"allow",
+ *   controlPolicy:       "reject"|"strip"|"allow",
+ *   nullBytePolicy:      "reject"|"strip"|"allow",
+ *   zeroWidthPolicy:     "reject"|"strip"|"audit"|"allow",
+ *   safeCoreTagsAllowed: boolean,
+ *   maxBytes:            number,    // total source byte cap
+ *   maxDepth:            number,    // recursion depth cap
+ *   maxAnchors:          number,    // anchor declaration cap
+ *   maxAliasDepth:       number,    // alias-chain depth cap
+ *   maxDocuments:        number,    // multi-document doc count cap
+ *   maxNodes:            number,    // total node count cap
+ *   maxScalarLength:     number,    // per-scalar length cap
+ *
+ * @example
+ *   var rv = b.guardYaml.validate("!!python/object/new:cls\nargs: [x]\n", {
+ *     profile: "strict",
+ *   });
+ *   rv.ok;                                              // → false
+ *   rv.issues.some(function (i) { return i.kind === "dangerous-tag"; });  // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -449,6 +512,41 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardYaml.parse
+ * @signature  b.guardYaml.parse(input, opts?)
+ * @since      0.7.14
+ * @status     stable
+ * @related    b.guardYaml.validate, b.guardYaml.gate
+ *
+ * Parse `input` (string of YAML source) into a JavaScript value
+ * after the guard-yaml threat catalog clears. Runs the full
+ * validate-shape detector, throws `GuardYamlError` on the first
+ * critical issue (dangerous tag, alias-explosion, multi-document
+ * under reject, parse failure, etc.), then routes through the safe-
+ * yaml parser with the configured `maxBytes` / `maxDepth` /
+ * `maxNodes` caps.
+ *
+ * The throw-on-critical pre-flight is what distinguishes guarded
+ * parse from a raw yaml-library `load()`: the operator's downstream
+ * code never sees deserialization-tag instantiation, billion-laughs
+ * expansion, or duplicate-key smuggling because the source is
+ * refused before the parser runs.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   tagPolicy:    "reject"|"audit"|"allow",
+ *   aliasPolicy:  "reject"|"audit"|"allow",
+ *   maxBytes:     number, maxDepth: number, maxNodes: number,
+ *
+ * @example
+ *   var safe = b.guardYaml.parse("name: alice\nage: 30\n", {
+ *     profile: "strict",
+ *   });
+ *   safe.name;                                          // → "alice"
+ *   safe.age;                                           // → 30
+ */
 function parse(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -468,6 +566,35 @@ function parse(input, opts) {
   });
 }
 
+/**
+ * @primitive  b.guardYaml.gate
+ * @signature  b.guardYaml.gate(opts?)
+ * @since      0.7.14
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardYaml.validate, b.guardYaml.parse, b.staticServe.create, b.fileUpload.create
+ *
+ * Build a `b.gateContract` gate suitable for plugging into
+ * `b.staticServe({ contentSafety: { ".yaml": gate } })`,
+ * `b.fileUpload({ contentSafety: { "application/yaml": gate } })`,
+ * or any host primitive that consumes the gate-contract shape.
+ * Action chain on validation: `serve` (no issues) → `audit-only`
+ * (warn-only issues) → `refuse` (any high/critical issue). YAML
+ * sanitize is intentionally not offered — there's no safe re-emit
+ * for tag-injection / alias-explosion shapes; the only correct
+ * response is refusal.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,    // gate identity for audit / observability
+ *
+ * @example
+ *   var yamlGate = b.guardYaml.gate({ profile: "strict" });
+ *   var hostile = Buffer.from("!!python/object/new:cls\nargs: [x]\n", "utf8");
+ *   var verdict = await yamlGate.check({ bytes: hostile });
+ *   verdict.action;                                     // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -486,13 +613,83 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardYaml.buildProfile
+ * @signature  b.guardYaml.buildProfile(opts)
+ * @since      0.7.14
+ * @status     stable
+ * @related    b.guardYaml.gate, b.guardYaml.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-yaml key, // inline override of resolved keys
+ *
+ * @example
+ *   var custom = b.guardYaml.buildProfile({
+ *     extends: "balanced",
+ *     tagPolicy: "reject",
+ *     maxAnchors: 8,
+ *   });
+ *   custom.tagPolicy;                                   // → "reject"
+ *   custom.maxAnchors;                                  // → 8
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardYaml.compliancePosture
+ * @signature  b.guardYaml.compliancePosture(name)
+ * @since      0.7.14
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardYaml.gate, b.guardYaml.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
+ * `GuardYamlError("yaml.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardYaml.compliancePosture("hipaa");
+ *   posture.tagPolicy;                                  // → "reject"
+ *   posture.forensicSnippetBytes;                       // → 256
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES, _err, "yaml");
 }
 
 var _yamlRulePacks = gateContract.makeRulePackLoader(GuardYamlError, "yaml");
+/**
+ * @primitive  b.guardYaml.loadRulePack
+ * @signature  b.guardYaml.loadRulePack(pack)
+ * @since      0.7.14
+ * @status     stable
+ * @related    b.guardYaml.gate
+ *
+ * Register an operator-supplied rule pack with the guard-yaml
+ * 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 `GuardYamlError("yaml.bad-opt")` when `pack` is
+ * missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardYaml.loadRulePack({
+ *     id: "deploy-keys",
+ *     rules: [
+ *       { id: "no-image-latest", severity: "high",
+ *         detect: function (text) { return /image:\s*\S+:latest\b/.test(text); },
+ *         reason: "deployment YAML must pin image tag (no :latest)" },
+ *     ],
+ *   });
+ *   pack.id;                                            // → "deploy-keys"
+ */
 var loadRulePack = _yamlRulePacks.load;
 
 module.exports = {

package/lib/honeytoken.js

@@ -1,36 +1,33 @@
 "use strict";
 /**
- * b.honeytoken — canary credential framework. Generates decoy values
- * (fake api-key shapes, fake admin URLs, fake DB row references) that
- * are NEVER handed to a real client; their presence in a request,
- * log, or DB lookup means an attacker found something they shouldn't
- * have. The framework registers each token at issuance and refuses
- * silently in production but always emits a `honeytoken.tripped`
- * audit row on any positive lookup.
+ * @module b.honeytoken
+ * @nav    Identity
+ * @title  Honeytoken
  *
- *   var honey = b.honeytoken.create({ audit: b.audit });
+ * @intro
+ *   Framework-seeded canary records that trigger an audit alert on
+ *   read; integrates with sealed columns. The framework generates
+ *   decoy values (fake api-key shapes, fake admin URLs, fake DB row
+ *   references) that are NEVER handed to a real client. Their
+ *   presence in a request, log, or DB lookup means an attacker
+ *   reached something they shouldn't have. Every positive lookup
+ *   emits a `honeytoken.tripped` audit row with the observing
+ *   actor's 5 W's so a SOC operator can pivot directly to the
+ *   compromise.
  *
- *   var token = honey.issue({
- *     kind:     "apiKey",
- *     metadata: { plantedAt: "GET /admin/keys/404", linkedTo: "u_42" },
- *   });
- *   // → { value: "bk_canary_8f3a7b2e0c…", id: "ht_<hex>" }
- *
- *   if (honey.lookup(req.headers["x-api-key"])) {
- *     // attacker is using the canary; tripped event already audited
- *     return res.status(403).end();
- *   }
+ *   Canary value shapes (`kind`):
+ *     - `"apiKey"`  — `bk_canary_<hex>` (mirrors b.apiKey shape)
+ *     - `"session"` — `bks_canary_<hex>` (mirrors b.session shape)
+ *     - `"url"`     — `/admin/canary-<hex>` (planted as a clickable link)
+ *     - `"rowId"`   — `ht_canary_<hex>` (planted as a fake foreign key)
  *
- * Canary value shapes (`kind`):
- *   - "apiKey"   → `bk_canary_<32 hex>` (matches b.apiKey shape)
- *   - "session"  → `bks_canary_<48 hex>` (matches b.session shape)
- *   - "url"      → `/admin/canary-<32 hex>` (planted as a clickable link)
- *   - "rowId"    → `ht_canary_<32 hex>` (planted as a fake foreign key)
+ *   Audit shape:
+ *     - `honeytoken.issued`  — outcome=success; metadata { id, kind }
+ *     - `honeytoken.tripped` — outcome=failure; metadata { id, kind,
+ *       metadata, observedAt, observedActor }
  *
- * Audit shape:
- *   - `honeytoken.issued` — outcome=success; metadata: { id, kind }
- *   - `honeytoken.tripped` — outcome=failure; metadata: { id, kind,
- *     metadata, observedAt, observedActor }
+ * @card
+ *   Framework-seeded canary records that trigger an audit alert on read; integrates with sealed columns.
  */
 
 var crypto = require("./crypto");
@@ -49,6 +46,45 @@ var KINDS = Object.freeze({
   rowId:   function () { return "ht_canary_"  + crypto.generateToken(16); },     // allow:raw-byte-literal — 16-byte canary entropy
 });
 
+/**
+ * @primitive b.honeytoken.create
+ * @signature b.honeytoken.create(opts)
+ * @since     0.8.40
+ * @status    stable
+ * @compliance soc2, nis2, dora
+ * @related   b.audit, b.apiKey.create, b.session
+ *
+ * Build an in-process honeytoken registry. Returns a handle exposing
+ * `issue(spec)` to mint a canary, `lookup(value, observedActor?)` to
+ * test an incoming value (audit-emits `honeytoken.tripped` on hit),
+ * `revoke(id)` to retire a canary, and `size()` for diagnostics. The
+ * registry is per-process — operators running multiple workers wire
+ * a shared b.audit sink and reconcile alerts at the audit layer
+ * rather than sharing the registry across nodes (a canary's value
+ * is what's planted in the trap, not what's known to the framework).
+ *
+ * @opts
+ *   audit:  b.audit,   // audit sink for issued / tripped events (optional, recommended)
+ *
+ * @example
+ *   var honey = b.honeytoken.create({ audit: b.audit });
+ *
+ *   var canary = honey.issue({
+ *     kind:     "apiKey",
+ *     metadata: { plantedAt: "GET /admin/keys/list", linkedTo: "user-42" },
+ *   });
+ *   // → { id: "ht_<hex>", value: "bk_canary_<hex>" }
+ *
+ *   // Plant the canary value somewhere an attacker who's escalated
+ *   // privileges might find it (a fake row in an admin listing, a
+ *   // dummy env-var leaked into a traceback page, etc.).
+ *
+ *   // On every incoming credential, check for canary use:
+ *   if (honey.lookup(req.headers["x-api-key"], { ip: req.ip })) {
+ *     // tripped — audit already emitted; respond as if invalid.
+ *     return res.writeHead(403).end();
+ *   }
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, ["audit"], "honeytoken.create");

package/lib/html-balance.js

@@ -1,4 +1,35 @@
 "use strict";
+/**
+ * @module b.htmlBalance
+ * @nav    Tools
+ * @title  HTML Balance
+ *
+ * @intro
+ *   HTML tag-balance verification. Walks an HTML fragment and refuses
+ *   unbalanced container tags, orphan close tags, mismatched-name
+ *   close tags, void-element close tags, unterminated comments, and
+ *   unterminated raw-text elements (`<script>` / `<style>` / `<title>`
+ *   / `<textarea>`). Returns `null` when balanced; otherwise an issue
+ *   object with `code`, `message`, `line`, and `column` so operators
+ *   can surface "you forgot to close this tag at line N" feedback at
+ *   save time.
+ *
+ *   Intent is operator-side structural feedback, not security
+ *   validation. Attribute syntax, custom-element / shadow-DOM
+ *   namespaces, script/style content semantics, and XSS-class checks
+ *   are all out of scope here — the security pass is `b.guardHtml`,
+ *   composed by `b.htmlBalance.checkSafe` for operators wanting both
+ *   gates in one call.
+ *
+ *   Void elements (`<br>`, `<img>`, `<input>`, …) are recognised and
+ *   never expected to close. Self-closing slash forms (`<foo />`)
+ *   are honoured. Raw-text elements skip their content entirely so
+ *   `<script>` bodies containing literal `<` / `</` aren't mis-read
+ *   as markup.
+ *
+ * @card
+ *   HTML tag-balance verification.
+ */
 /**
  * html-balance — minimal HTML structural sanity check.
  *
@@ -45,6 +76,28 @@ function _posToLineColumn(src, pos) {
   return { line: line, column: col };
 }
 
+/**
+ * @primitive b.htmlBalance.check
+ * @signature b.htmlBalance.check(html)
+ * @since     0.1.0
+ * @related   b.htmlBalance.checkSafe, b.guardHtml
+ *
+ * Returns `null` when `html` is balanced; otherwise an issue object
+ * `{ code, message, line, column }`. Issue codes: `html/unterminated-comment`,
+ * `html/unterminated-tag`, `html/orphan-close`, `html/mismatched-close`,
+ * `html/void-close`, `html/unclosed-raw-text`, `html/unclosed-tag`.
+ * Non-string inputs and the empty string return `null` (nothing to
+ * balance). Self-closing slash forms and HTML5 void elements are
+ * recognised; raw-text elements skip their bodies so `<script>` JS
+ * containing `<` characters doesn't mis-balance.
+ *
+ * @example
+ *   b.htmlBalance.check("<div><p>hello</p></div>");
+ *   // → null
+ *
+ *   var issue = b.htmlBalance.check("<div><p>hello</div>");
+ *   // → { code: "html/mismatched-close", message: "</div> at line 1 col 14 does not match open <p> at line 1 col 6", line: 1, column: 14 }
+ */
 function check(html) {
   if (typeof html !== "string" || html.length === 0) return null;
   var stack = [];   // [{ tag, openPos }]
@@ -242,6 +295,36 @@ function check(html) {
 var lazyRequire = require("./lazy-require");
 var _guardHtml = lazyRequire(function () { return require("./guard-html"); });
 
+/**
+ * @primitive b.htmlBalance.checkSafe
+ * @signature b.htmlBalance.checkSafe(html, opts?)
+ * @since     0.7.7
+ * @related   b.htmlBalance.check, b.guardHtml
+ *
+ * Composes `check()` (cheap structural well-formedness) with
+ * `b.guardHtml.gate({ profile })` (security-class checks against the
+ * strict / balanced / permissive vocabulary plus an optional
+ * compliance posture). Returns `{ balanceIssue, guardIssues, ok }`
+ * so callers can distinguish a structural problem from a content-
+ * safety reject and decide which path to surface to the operator.
+ *
+ * `opts.contentSafety` mirrors the same shape as `b.fileUpload({
+ * contentSafety })` and `b.staticServe({ contentSafety })` so a
+ * single `{ profile, posture }` value flows across the stack
+ * unchanged.
+ *
+ * @opts
+ *   profile:        "strict" | "balanced" | "permissive",
+ *   posture:        string,                                    // compliance posture name; e.g. "hipaa", "pci-dss"
+ *   contentSafety:  { profile, posture },                      // shared shape with b.fileUpload / b.staticServe
+ *
+ * @example
+ *   var rv = b.htmlBalance.checkSafe("<div onclick=\"x()\">hi</div>", { profile: "strict" });
+ *   // → { balanceIssue: null, guardIssues: [{ kind: "event-handler-attribute", ... }], ok: false }
+ *
+ *   b.htmlBalance.checkSafe("<p>hello</p>", { profile: "strict" });
+ *   // → { balanceIssue: null, guardIssues: [], ok: true }
+ */
 function checkSafe(html, opts) {
   opts = opts || {};
   var balanceIssue = check(html);