@blamejs/core 0.8.43 → 0.8.50

package/lib/guard-domain.js

@@ -1,55 +1,56 @@
 "use strict";
 /**
- * guard-domain — Domain-name identifier-safety primitive (b.guardDomain).
+ * @module b.guardDomain
+ * @nav    Guards
+ * @title  Guard Domain
  *
- * Validates user-supplied DNS names destined for allowlists, redirect
- * targets, webhook endpoints, email-domain extraction, and CORS origin
- * checks. KIND="identifier" — consumes ctx.identifier (or ctx.domain).
+ * @intro
+ *   Domain-name identifier-safety primitive (KIND="identifier").
+ *   Validates user-supplied DNS names destined for allowlists,
+ *   redirect targets, webhook endpoints, email-domain extraction,
+ *   and CORS origin checks. Consumes `ctx.identifier` (or
+ *   `ctx.domain`).
  *
- * Threat catalog grounded in current research:
- *   - RFC 1035 §2.3.4 length caps — 63 octets / label, 253 octets / FQDN.
- *   - RFC 952 / 1123 LDH rule — letters / digits / hyphens; no leading/
- *     trailing hyphen; no `--` at positions 3-4 except `xn--` prefix.
- *   - IDN homograph / mixed-script confusables (RFC 5891-5894 IDNA2008,
- *     UTS #39). Cyrillic / Greek / Cherokee characters mixed with Latin
- *     in a single label spoof a trusted domain.
- *   - BIDI / RTL override (CVE-2021-42574 Trojan Source) in label
- *     codepoints — reorders visual presentation of the domain in
- *     address bars / log lines / audit records.
- *   - Zero-width / format codepoints — split a visible label into two
- *     parsed labels or hide characters from the operator.
- *   - Punycode `xn--` malformation — bare prefix that fails decode,
- *     double-encoded `xn--xn--`, U-label/A-label round-trip mismatch.
- *   - Special-use domain names (RFC 6761) — `.localhost`, `.local`,
- *     `.invalid`, `.example`, `.test`, `.onion`, `.alt`, `.home.arpa`,
- *     `.internal`. Allowlisting these as user-supplied webhook targets
- *     routes traffic to loopback or LAN.
- *   - IPv4-as-domain confusion (RFC 3986 §3.2.2 + CVE-2021-22931) —
- *     dotted-decimal, octal, hex, and long-decimal IPv4 forms accepted
- *     by `inet_aton`-style parsers but compared as strings by allowlist
- *     matchers.
- *   - IPv6 bracket-literal — same risk class.
- *   - TLD-only / single-label — resolves via search-domain suffix to
- *     attacker-chosen FQDN on misconfigured stubs.
- *   - Wildcard `*.example.com` — valid in TLS SAN and DNS but never in
- *     a user-input identifier.
- *   - Underscore labels — valid only for service-discovery prefixes
- *     per RFC 8552, never as a hostname.
- *   - Trailing dot — FQDN distinguisher; some libraries strip,
- *     some compare; allowlist mismatch.
- *   - DGA heuristic — high-entropy single-label domains
- *     (Mirai/Conficker family C2 indicator).
+ *   IDN homograph defense: mixed-script confusables (RFC 5891-5894
+ *   IDNA2008, UTS #39) — Cyrillic / Greek / Cherokee letters mixed
+ *   with Latin in a single label spoof trusted domains. Strict
+ *   refuses; balanced/permissive audit. The script-allowlist is
+ *   operator-tunable via `opts.allowedScripts`. Punycode A-labels
+ *   (`xn--`) audit by default at balanced; bare `xn--` always
+ *   refuses.
  *
- *   var rv = b.guardDomain.validate("example.com", { profile: "strict" });
- *   var safe = b.guardDomain.sanitize("Example.Com.", { profile: "balanced" });
- *   var g = b.guardDomain.gate({ profile: "strict" });
+ *   Label-length caps per RFC 1035 §2.3.4: 63 octets per label, 253
+ *   octets per FQDN. UTF-8 byte counting (not codepoint count) — the
+ *   wire-form bound is what DNS resolvers enforce. RFC 952 / 1123
+ *   LDH grammar enforced for ASCII labels; double-hyphen at positions
+ *   3-4 without `xn--` prefix audits.
+ *
+ *   TLD allowlist + public-suffix awareness: RFC 6761 special-use
+ *   suffixes (`.localhost` / `.local` / `.invalid` / `.test` /
+ *   `.onion` / `.alt` / `.home.arpa` / `.internal`) refuse under
+ *   strict — letting these through as user-input webhook targets
+ *   routes traffic to loopback / mDNS / Tor / LAN. IPv4-as-domain
+ *   (dotted-decimal, octal, hex, long-decimal) and IPv6 bracket
+ *   literals refuse (CVE-2021-22931 DNS-rebinding class).
+ *   Single-label / TLD-only refuses under strict (search-domain
+ *   suffix on misconfigured stubs).
+ *
+ *   Public-suffix and full UTS #46 ToASCII / ToUnicode round-trip
+ *   ship behind operator-supplied callbacks (`opts.publicSuffixList`,
+ *   `opts.idnToAscii`) — defer-with-condition until an operator
+ *   surfaces a cookie-scope or email-domain canonicalization use case
+ *   that needs framework-vendored tables.
  *
- * Defer-with-condition: full UTS #46 ToASCII / ToUnicode round-trip and
- * Public-Suffix-List boundary enforcement ship behind operator-supplied
- * callbacks (`opts.idnToAscii`, `opts.publicSuffixList`). Re-open
- * conditions: an operator surfaces a use case for cookie-scope or
- * email-domain canonicalization that needs framework-vendored PSL /
- * UTS #46 tables.
+ *   BIDI / control / null-byte / zero-width are universal-refuse at
+ *   every profile (CVE-2021-42574 Trojan Source class). DGA heuristic
+ *   (Shannon entropy >= 3.8 bits/char on labels >= 12 chars) audits
+ *   under balanced, refuses under strict.
+ *
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`.
+ *
+ * @card
+ *   Domain-name identifier-safety primitive (KIND="identifier").
  */
 
 var codepointClass = require("./codepoint-class");
@@ -121,51 +122,10 @@ function _looksLikeIpv4Permissive(s) {
 // IPv6 bracket-literal.
 var IPV6_BRACKET_RE = /^\[[0-9a-fA-F:.]+\]$/;
 
-// IDN script-range tables for mixed-script confusable detection. Same
-// pattern guard-email uses; codepoints are numeric, never literal in
-// source.
-var SCRIPT_RANGES = {
-  latin:    [[0x0041, 0x005A], [0x0061, 0x007A],
-             [0x00C0, 0x024F], [0x1E00, 0x1EFF]],                                // allow:raw-byte-literal — Unicode script ranges
-  cyrillic: [[0x0400, 0x04FF], [0x0500, 0x052F]],                                // allow:raw-byte-literal — Unicode Cyrillic + Cyrillic Supplement
-  greek:    [[0x0370, 0x03FF], [0x1F00, 0x1FFF]],                                // allow:raw-byte-literal — Unicode Greek + Greek Extended
-  armenian: [[0x0530, 0x058F]],                                                  // allow:raw-byte-literal — Unicode Armenian
-  cherokee: [[0x13A0, 0x13FF], [0xAB70, 0xABBF]],                                // allow:raw-byte-literal — Unicode Cherokee + Cherokee Supplement
-  han:      [[0x4E00, 0x9FFF]],                                                  // allow:raw-byte-literal — CJK Unified Ideographs
-  hiragana: [[0x3040, 0x309F]],                                                  // allow:raw-byte-literal — Hiragana
-  katakana: [[0x30A0, 0x30FF]],                                                  // allow:raw-byte-literal — Katakana
-  hangul:   [[0xAC00, 0xD7AF]],                                                  // allow:raw-byte-literal — Hangul Syllables
-  arabic:   [[0x0600, 0x06FF]],                                                  // allow:raw-byte-literal — Arabic
-  hebrew:   [[0x0590, 0x05FF]],                                                  // allow:raw-byte-literal — Hebrew
-};
-
-function _scriptFor(cp) {
-  var keys = Object.keys(SCRIPT_RANGES);
-  for (var i = 0; i < keys.length; i += 1) {
-    var ranges = SCRIPT_RANGES[keys[i]];
-    for (var j = 0; j < ranges.length; j += 1) {
-      if (cp >= ranges[j][0] && cp <= ranges[j][1]) return keys[i];
-    }
-  }
-  return null;
-}
-
-function _detectMixedScripts(label, allowedScripts) {
-  var seen = {};
-  for (var i = 0; i < label.length; i += 1) {
-    var script = _scriptFor(label.charCodeAt(i));
-    if (script === null) continue;
-    seen[script] = true;
-  }
-  var scripts = Object.keys(seen);
-  if (scripts.length <= 1) return null;
-  if (!allowedScripts) return scripts;
-  var disallowed = [];
-  for (var k = 0; k < scripts.length; k += 1) {
-    if (allowedScripts.indexOf(scripts[k]) === -1) disallowed.push(scripts[k]);
-  }
-  return disallowed.length > 0 ? scripts : null;
-}
+// IDN script-range tables for mixed-script confusable detection live
+// in codepoint-class — every guard-* family member + safe-url shares
+// the same catalog so adding a script is a single edit.
+var _detectMixedScripts = codepointClass.detectMixedScripts;
 
 // RFC 6761 special-use domains + IETF reserved. Lowercase, no trailing
 // dot. Match by suffix — `_acme-challenge.app.localhost` → `.localhost`.
@@ -595,6 +555,52 @@ function _detectIssues(input, opts) {
   return issues;
 }
 
+/**
+ * @primitive  b.guardDomain.validate
+ * @signature  b.guardDomain.validate(input, opts?)
+ * @since      0.7.41
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardDomain.sanitize, b.guardDomain.gate
+ *
+ * Inspect a domain-name string and return `{ ok, issues, summary }`.
+ * Each issue carries `{ kind, severity, ruleId, snippet }` with
+ * severity in `"warn"|"high"|"critical"`. Detected: domain/label
+ * length cap (RFC 1035 §2.3.4), LDH violation, IDN A-label
+ * malformation, mixed-script homograph, special-use suffix (RFC
+ * 6761), IPv4-as-domain (every parser-permissive form), IPv6
+ * bracket-literal, single-label / TLD-only, wildcard label,
+ * underscore label, trailing dot, DGA-shape entropy, BIDI / control
+ * / null-byte / zero-width codepoints. Pure inspection.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   ldhPolicy:           "reject"|"audit"|"allow",
+ *   punycodePolicy:      "reject"|"audit"|"allow",
+ *   mixedScriptPolicy:   "reject"|"audit"|"allow",
+ *   specialUsePolicy:    "reject"|"audit"|"allow",
+ *   ipLiteralPolicy:     "reject"|"audit"|"allow",
+ *   wildcardPolicy:      "reject"|"audit"|"allow",
+ *   singleLabelPolicy:   "reject"|"audit"|"allow",
+ *   underscorePolicy:    "reject"|"audit"|"allow",
+ *   dgaPolicy:           "reject"|"audit"|"allow",
+ *   trailingDotPolicy:   "normalize"|"audit"|"reject",
+ *   allowedScripts:      string[]|null,
+ *   dgaEntropyThreshold: number,
+ *   dgaMinLabelLen:      number,
+ *   maxLabelOctets:      number,    // default 63 (RFC 1035 §2.3.4)
+ *   maxDomainOctets:     number,    // default 253 (RFC 1035 §2.3.4)
+ *   maxBytes:            number,    // total input byte cap
+ *
+ * @example
+ *   var rv = b.guardDomain.validate("192.168.1.1", { profile: "strict" });
+ *   rv.ok;                                             // → false
+ *   rv.issues.some(function (i) { return i.kind === "ipv4-as-domain"; });   // → true
+ *
+ *   var ok = b.guardDomain.validate("example.com", { profile: "strict" });
+ *   ok.ok;                                             // → true
+ */
 function validate(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -611,6 +617,30 @@ function validate(input, opts) {
   return gateContract.aggregateIssues(_detectIssues(input, opts));
 }
 
+/**
+ * @primitive  b.guardDomain.sanitize
+ * @signature  b.guardDomain.sanitize(input, opts?)
+ * @since      0.7.41
+ * @status     stable
+ * @related    b.guardDomain.validate, b.guardDomain.gate
+ *
+ * Normalize a domain-name string when no critical/high issues fire.
+ * Throws `GuardDomainError` on any high/critical refusal (homograph
+ * mix, IPv4-as-domain, special-use suffix, BIDI, malformed Punycode).
+ * Safe transforms applied otherwise: ASCII lowercasing, trailing-dot
+ * strip. Refuses to canonicalize Unicode labels — operators wanting
+ * IDN ToASCII supply `opts.idnToAscii` so the framework doesn't
+ * silently rewrite a label the operator's allowlist would treat as
+ * different.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *
+ * @example
+ *   var safe = b.guardDomain.sanitize("Example.Com.", { profile: "balanced" });
+ *   safe;                                              // → "example.com"
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -630,6 +660,31 @@ function sanitize(input, opts) {
   return out;
 }
 
+/**
+ * @primitive  b.guardDomain.gate
+ * @signature  b.guardDomain.gate(opts?)
+ * @since      0.7.41
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardDomain.validate, b.guardDomain.sanitize
+ *
+ * Build a `b.gateContract` gate that consumes `ctx.identifier` (or
+ * `ctx.domain`) and dispatches `serve` (no input or clean) →
+ * `audit-only` (warn-only issues) → `refuse` (any critical or high
+ * issue). No `sanitize` action — domain canonicalization is
+ * caller-driven via `b.guardDomain.sanitize` so an allowlist gate
+ * never silently rewrites the operator's stored allowlist key.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,    // gate identity for audit / observability
+ *
+ * @example
+ *   var domGate = b.guardDomain.gate({ profile: "strict" });
+ *   var verdict = await domGate.check({ identifier: "myhost.localhost" });
+ *   verdict.action;                                    // → "refuse"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -655,14 +710,81 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive  b.guardDomain.buildProfile
+ * @signature  b.guardDomain.buildProfile(opts)
+ * @since      0.7.41
+ * @status     stable
+ * @related    b.guardDomain.gate, b.guardDomain.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.
+ *
+ * @opts
+ *   extends: string|string[],   // base profile name(s) to compose
+ *
+ * @example
+ *   var custom = b.guardDomain.buildProfile({
+ *     extends: "balanced",
+ *     allowedScripts: ["latin"],
+ *     punycodePolicy: "reject",
+ *   });
+ *   custom.punycodePolicy;                             // → "reject"
+ *   custom.bidiPolicy;                                 // → "reject"
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardDomain.compliancePosture
+ * @signature  b.guardDomain.compliancePosture(name)
+ * @since      0.7.41
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardDomain.gate, b.guardDomain.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
+ * `GuardDomainError("domain.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardDomain.compliancePosture("hipaa");
+ *   posture.specialUsePolicy;                          // → "reject"
+ *   posture.forensicSnippetBytes;                      // → 256
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
     _err, "domain");
 }
 
 var _domainRulePacks = gateContract.makeRulePackLoader(GuardDomainError, "domain");
+/**
+ * @primitive  b.guardDomain.loadRulePack
+ * @signature  b.guardDomain.loadRulePack(pack)
+ * @since      0.7.41
+ * @status     stable
+ * @related    b.guardDomain.gate
+ *
+ * Register an operator-supplied rule pack with the guard-domain
+ * 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 `GuardDomainError("domain.bad-opt")` when `pack`
+ * is missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardDomain.loadRulePack({
+ *     id: "tenant-corp-only",
+ *     rules: [
+ *       { id: "tenant-suffix", severity: "high",
+ *         detect: function (d) { return !/\.example\.com$/i.test(d); },
+ *         reason: "tenant policy: only example.com suffixes permitted" },
+ *     ],
+ *   });
+ *   pack.id;                                           // → "tenant-corp-only"
+ */
 var loadRulePack = _domainRulePacks.load;
 
 module.exports = {

package/lib/guard-email.js

@@ -1,35 +1,38 @@
 "use strict";
 /**
- * guard-email — Email content-safety primitive (b.guardEmail).
+ * @module b.guardEmail
+ * @nav    Guards
+ * @title  Guard Email
  *
- * Threat catalog grounded in current research:
- *   - SMTP smuggling (CVE-2023-51764 Postfix; CVE-2023-51765 Sendmail;
- *     CVE-2023-51766 Exim; CVE-2026-32178 .NET System.Net.Mail) —
- *     embedded SMTP verbs after bare-CR / bare-LF / dot-stuffing
- *     manipulation lets an attacker inject a second message in the
- *     same SMTP session with a forged envelope.
- *   - CRLF header injection — `\r\n` inside any header field value
- *     splits the header section and lets the attacker forge `From:`,
- *     `Bcc:`, or smuggle a body.
- *   - IDN homograph spoofing — mixed-script Unicode in the domain part
- *     (Cyrillic а / Greek α / Armenian / Cherokee letters that look
- *     like Latin lowercase). Most filters miss confusables.
- *   - Display-name spoofing — `"support@apple.com" <attacker@evil>` —
- *     the rendered name impersonates a trusted address while the
- *     envelope routes elsewhere.
- *   - Bare IP literal addresses — `user@[1.2.3.4]` / `user@[IPv6:...]`.
- *   - Comment syntax in addresses — `(comment)` per RFC 5322 — most
- *     receivers reject; senders that accept it are a smuggling vector.
- *   - RFC 5321 / 5322 length caps — local-part 64; domain 255; total
- *     address 320; per-line 998.
- *   - Multiple @ characters / multiple addresses in a single field.
- *   - Bidi / null / control / zero-width chars in addresses + headers.
- *   - BOM injection at the start of a header.
+ * @intro
+ *   RFC 822 / 5322 single-address validator + RFC 5322 message gate
+ *   with header-injection defense, EAI / SMTPUTF8 support, label
+ *   length caps, IP-literal denial, and sub-address handling.
  *
- *   var rv = b.guardEmail.validateAddress(addr, { profile: "strict" });
- *   var rv = b.guardEmail.validateMessage(rfc822, { profile: "strict" });
- *   var safe = b.guardEmail.sanitize(input, { profile: "balanced" });
- *   var g = b.guardEmail.gate({ profile: "strict" });
+ *   Two entry shapes:
+ *     - `validateAddress(addr, opts)` — single mailbox (RFC 5321
+ *       atext@DNS-domain). Caps RFC 5321 §4.5.3.1 local-part 64 /
+ *       domain 255 / address 320. Flags multi-`@`, IP literals,
+ *       Punycode, mixed-script confusables, and codepoint-class
+ *       threats (BIDI / control / null / zero-width).
+ *     - `validateMessage(rfc822, opts)` — full RFC 5322 message.
+ *       Splits header section, unfolds folded headers, walks every
+ *       single-line header for embedded CR/LF, drives address checks
+ *       on `From` / `To` / `Cc` / `Bcc` / `Reply-To` / `Sender` /
+ *       `Return-Path`, and scans the message body for SMTP-smuggling
+ *       (bare-CR / bare-LF / `\r?\n.\r?\nMAIL FROM:` class —
+ *       CVE-2023-51764 / 51765 / 51766) plus RFC 5322 §2.1.1 line cap.
+ *
+ *   Profiles ship in pairs:
+ *     - `strict` / `balanced` / `permissive` — operator scope.
+ *     - `hipaa` / `pci-dss` / `gdpr` / `soc2` — compliance posture.
+ *
+ *   Header injection, SMTP smuggling, multi-`@`, and null-byte are
+ *   `reject` at every profile — universally exploitable, no
+ *   sanitization is safe.
+ *
+ * @card
+ *   RFC 822 / 5322 single-address validator + RFC 5322 message gate with header-injection defense, EAI / SMTPUTF8 support, label length caps, IP-literal denial, and sub-address handling.
  */
 
 var codepointClass = require("./codepoint-class");
@@ -423,6 +426,50 @@ function _detectAddressIssues(input, opts) {
   return issues;
 }
 
+/**
+ * @primitive b.guardEmail.validateAddress
+ * @signature b.guardEmail.validateAddress(input, opts)
+ * @since     0.7.17
+ * @status    stable
+ * @related   b.guardEmail.validateMessage, b.guardEmail.gate, b.guardEmail.sanitize
+ *
+ * Validate a single email address against RFC 5321 atext@DNS-domain
+ * shape with the active profile's policies. Returns `{ ok, issues }`;
+ * `issues[]` carries `kind` / `severity` / `ruleId` / `snippet` for
+ * every detector that fired. Never throws on input — bad shapes
+ * surface as `bad-input` issues so the caller can route on them.
+ *
+ * Detectors run in order: total-address cap, multi-`@` count,
+ * RFC 5322 comment syntax, IP literal `[...]`, local-part / domain
+ * caps, Punycode (`xn--`) labels, mixed-script confusables (Latin /
+ * Cyrillic / Greek / Armenian / Cherokee), strict-ASCII regex shape,
+ * and codepoint-class threats (BIDI / null / control / zero-width).
+ *
+ * @opts
+ *   profile:                 "strict" | "balanced" | "permissive",
+ *   compliancePosture:       "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   multiAtPolicy:           "reject" | "audit" | "allow",
+ *   ipLiteralPolicy:         "reject" | "audit" | "allow",
+ *   addressCommentPolicy:    "reject" | "audit" | "allow",
+ *   punycodePolicy:          "reject" | "audit" | "allow",
+ *   mixedScriptPolicy:       "reject" | "audit" | "allow",
+ *   allowedScripts:          string[] | null,
+ *   maxLocalPartBytes:       number,
+ *   maxDomainBytes:          number,
+ *   maxAddressBytes:         number,
+ *
+ * @example
+ *   var guardEmail = require("./lib/guard-email");
+ *   var rv = guardEmail.validateAddress("alice@example.com",
+ *     { profile: "strict" });
+ *   rv.ok;                  // → true
+ *   rv.issues.length;       // → 0
+ *
+ *   var bad = guardEmail.validateAddress("user@[10.0.0.1]",
+ *     { profile: "strict" });
+ *   bad.ok;                 // → false
+ *   bad.issues[0].kind;     // → "ip-literal"
+ */
 function validateAddress(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -633,6 +680,53 @@ function _checkAddressHeaderValue(value, opts, headerName) {
   return issues;
 }
 
+/**
+ * @primitive b.guardEmail.validateMessage
+ * @signature b.guardEmail.validateMessage(input, opts)
+ * @since     0.7.17
+ * @status    stable
+ * @related   b.guardEmail.validateAddress, b.guardEmail.gate, b.guardEmail.sanitize
+ *
+ * Validate a complete RFC 5322 message (headers + body) against the
+ * active profile. Splits the header section, unfolds folded
+ * continuation lines, walks every single-line header for embedded
+ * CR/LF (header-injection class), and runs `validateAddress` on each
+ * envelope under address-bearing headers (`From` / `To` / `Cc` /
+ * `Bcc` / `Reply-To` / `Sender` / `Return-Path`). Body is scanned
+ * for SMTP-smuggling vectors (bare CR / bare LF / smuggled
+ * `MAIL FROM:` after a bare line ending — CVE-2023-51764 / 51765 /
+ * 51766 class). Caps RFC 5322 §2.1.1 998-byte line, configurable
+ * header count, and total `maxBytes`.
+ *
+ * @opts
+ *   profile:                       "strict" | "balanced" | "permissive",
+ *   compliancePosture:             "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   crlfHeaderInjectionPolicy:     "reject" | "audit" | "allow",
+ *   smtpSmugglingPolicy:           "reject" | "audit" | "allow",
+ *   bareCrPolicy:                  "reject" | "audit" | "allow",
+ *   bareLfPolicy:                  "reject" | "audit" | "allow",
+ *   displayNameSpoofPolicy:        "reject" | "audit" | "allow",
+ *   bomPolicy:                     "reject" | "audit" | "strip" | "allow",
+ *   maxHeaderLineBytes:            number,
+ *   maxHeaders:                    number,
+ *   maxBytes:                      number,
+ *
+ * @example
+ *   var guardEmail = require("./lib/guard-email");
+ *   var msg = "From: alice@example.com\r\n" +
+ *             "To: bob@example.com\r\n" +
+ *             "Subject: hello\r\n" +
+ *             "Date: Mon, 5 May 2026 10:00:00 +0000\r\n\r\n" +
+ *             "Hello.\r\n";
+ *   var rv = guardEmail.validateMessage(msg, { profile: "strict" });
+ *   rv.ok;                  // → true
+ *
+ *   // Header injection: a CRLF inside the From value forges a Bcc.
+ *   var bad = "From: alice@example.com\r\nBcc: leak@evil\r\n" +
+ *             "To: bob@example.com\r\nSubject: hi\r\n\r\nbody\r\n";
+ *   var injected = guardEmail.validateMessage(bad, { profile: "strict" });
+ *   injected.ok;            // → true (well-formed; injected-line is its own header)
+ */
 function validateMessage(input, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -649,7 +743,33 @@ function validateMessage(input, opts) {
   return gateContract.aggregateIssues(_detectMessageIssues(input, opts));
 }
 
-// validate(input, opts) — auto-detect single address vs full message.
+/**
+ * @primitive b.guardEmail.validate
+ * @signature b.guardEmail.validate(input, opts)
+ * @since     0.7.17
+ * @status    stable
+ * @related   b.guardEmail.validateAddress, b.guardEmail.validateMessage
+ *
+ * Auto-routing entry: a string with no newline AND no `:` is treated
+ * as a single address (delegates to `validateAddress`); otherwise the
+ * input is treated as a full RFC 5322 message (delegates to
+ * `validateMessage`). Operators who want a fixed shape — never the
+ * heuristic — call the specific entry directly.
+ *
+ * @opts
+ *   profile:           "strict" | "balanced" | "permissive",
+ *   compliancePosture: "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   var guardEmail = require("./lib/guard-email");
+ *   guardEmail.validate("alice@example.com",
+ *     { profile: "strict" }).ok;          // → true
+ *
+ *   var msg = "From: a@example.com\r\nTo: b@example.com\r\n" +
+ *             "Subject: x\r\nDate: Mon, 5 May 2026 10:00:00 +0000\r\n\r\nhi\r\n";
+ *   guardEmail.validate(msg,
+ *     { profile: "strict" }).ok;          // → true
+ */
 function validate(input, opts) {
   if (typeof input === "string" && input.indexOf("\n") === -1 &&
       input.indexOf(":") === -1) {
@@ -658,6 +778,44 @@ function validate(input, opts) {
   return validateMessage(input, opts);
 }
 
+/**
+ * @primitive b.guardEmail.sanitize
+ * @signature b.guardEmail.sanitize(input, opts)
+ * @since     0.7.17
+ * @status    stable
+ * @related   b.guardEmail.validate, b.guardEmail.gate
+ *
+ * Best-effort sanitize for email content. THROWS on critical-severity
+ * issues (SMTP smuggling / CRLF header injection / multi-`@` /
+ * mixed-script confusable / null byte) — these have no safe
+ * sanitization. Lower-severity codepoint-class threats (BIDI / zero-
+ * width / control / BOM) are stripped per the active profile. Never
+ * silently drops a smuggling vector: the caller either gets
+ * sanitized text or a thrown `GuardEmailError`.
+ *
+ * @opts
+ *   profile:               "strict" | "balanced" | "permissive",
+ *   compliancePosture:     "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   bidiPolicy:            "reject" | "audit" | "strip" | "allow",
+ *   controlPolicy:         "reject" | "audit" | "strip" | "allow",
+ *   zeroWidthPolicy:       "reject" | "audit" | "strip" | "allow",
+ *
+ * @example
+ *   var guardEmail = require("./lib/guard-email");
+ *   // CRLF in the From value is a header-injection vector — sanitize
+ *   // refuses rather than silently dropping the bytes.
+ *   var hostile = "From: alice@example.com\rBcc: leak@evil\r\n" +
+ *                 "To: bob@example.com\r\nSubject: hi\r\n\r\nbody\r\n";
+ *   var threw = false;
+ *   try { guardEmail.sanitize(hostile, { profile: "strict" }); }
+ *   catch (e) { threw = (e.code || "").indexOf("email.") === 0; }
+ *   threw;                      // → true
+ *
+ *   // Benign input with a stray BIDI override is stripped under balanced.
+ *   var clean = guardEmail.sanitize("hello world",
+ *     { profile: "balanced" });
+ *   clean;                      // → "hello world"
+ */
 function sanitize(input, opts) {
   opts = _resolveOpts(opts);
   if (typeof input !== "string") {
@@ -675,6 +833,35 @@ function sanitize(input, opts) {
   return codepointClass.applyCharStripPolicies(input, opts);
 }
 
+/**
+ * @primitive b.guardEmail.gate
+ * @signature b.guardEmail.gate(opts)
+ * @since     0.7.17
+ * @status    stable
+ * @related   b.guardEmail.validateMessage, b.guardEmail.sanitize, b.guardAll.gate
+ *
+ * Build a guard gate function compatible with the `b.guardAll` family
+ * dispatch. The returned async gate accepts a request-shaped context,
+ * runs `validateMessage` against the extracted bytes, and returns
+ * `{ ok, action, issues? }` where `action` is `serve` (no issues),
+ * `audit-only` (warn-level), or `refuse` (high / critical severity).
+ *
+ * @opts
+ *   profile:               "strict" | "balanced" | "permissive",
+ *   compliancePosture:     "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   name:                  string,   // gate identifier surfaced in audit metadata
+ *
+ * @example
+ *   var guardEmail = require("./lib/guard-email");
+ *   var g = guardEmail.gate({ profile: "strict" });
+ *   typeof g;               // → "function"
+ *
+ *   var msg = "From: alice@example.com\r\nTo: bob@example.com\r\n" +
+ *             "Subject: hi\r\nDate: Mon, 5 May 2026 10:00:00 +0000\r\n\r\nbody\r\n";
+ *   g({ body: Buffer.from(msg, "utf8") }).then(function (rv) {
+ *     rv.action;            // → "serve"
+ *   });
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -700,6 +887,26 @@ function gate(opts) {
 
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive b.guardEmail.compliancePosture
+ * @signature b.guardEmail.compliancePosture(name)
+ * @since     0.7.17
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.guardEmail.gate, b.guardEmail.validateMessage
+ *
+ * Look up a compliance posture by name and return its frozen opts
+ * bundle. Throws `GuardEmailError` (`email.unknown-posture`) for
+ * names outside `hipaa` / `pci-dss` / `gdpr` / `soc2`. The returned
+ * opts can be merged into a `gate()` / `validateMessage()` call to
+ * apply the posture's defaults (forensic-snippet length included).
+ *
+ * @example
+ *   var guardEmail = require("./lib/guard-email");
+ *   var posture = guardEmail.compliancePosture("hipaa");
+ *   posture.bareCrPolicy;             // → "reject"
+ *   posture.forensicSnippetBytes;     // → 256
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES, _err, "email");
 }