@blamejs/core 0.7.42 → 0.7.44

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.44** (2026-05-05) — `b.guardUuid` — UUID identifier-safety primitive (KIND="identifier"). Validates user-supplied UUID strings per RFC 9562 (May 2024, obsoletes RFC 4122). Threat catalog: shape malformation across the four canonical forms (hyphenated 8-4-4-4-12, hyphenless 32-hex, Microsoft GUID braces `{…}`, `urn:uuid:` prefix); RFC 9562 §4.2 unassigned version digits (only 1-8 are defined); non-RFC 4122 variant bits (only the `10xx` high-bits family is the canonical UUID variant); nil UUID §5.9 / max UUID §5.10 sentinel-leak refuse; format policy enforcement (strict default = `hyphenated-only`); BIDI / zero-width / control / null-byte universal refuse via `lib/codepoint-class.js`. `sanitize` returns canonical lowercase hyphenated form (strips braces / urn prefix). Profiles: `strict` (hyphenated-only, refuse all sentinels and non-canonical forms), `balanced` (accept any form, audit sentinels), `permissive` (universal-refuse class still refused). Postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Auto-registers into `b.guardAll` as a STANDALONE_GUARD; the adaptive integration harness picks it up automatically via the KIND="identifier" dispatcher.
+
+- **0.7.43** (2026-05-05) — `b.guardDomain` — 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. Threat catalog: RFC 1035 §2.3.4 length caps (63 octets per label, 253 octets per FQDN), RFC 952 / 1123 LDH-rule violations (no leading/trailing hyphen, no `--` at positions 3-4 except `xn--`), IDN homograph mixed-script confusables (Latin / Cyrillic / Greek / Cherokee / Armenian / Han / Hiragana / Katakana / Hangul / Arabic / Hebrew range tables), BIDI / zero-width / control / null universal refuse via `lib/codepoint-class.js` (CVE-2021-42574 Trojan Source class), Punycode A-label malformation (bare `xn--`, double-encoded), RFC 6761 special-use suffix matching (`.localhost` / `.local` / `.invalid` / `.test` / `.onion` / `.alt` / `.home.arpa` / `.internal`), IPv4-as-domain confusion (CVE-2021-22931 — dotted-decimal / octal / hex / long-decimal forms), IPv6 bracket-literal, single-label / TLD-only refuse, wildcard `*` label refuse at every profile, RFC 8552 underscore-service-label policy, DGA Shannon-entropy heuristic for high-entropy long single labels (Mirai / Conficker C2 shape). Profiles: `strict` (Latin-only scripts, refuse-on-everything), `balanced` (audit Punycode, allow major international scripts, audit DGA), `permissive` (universal-refuse class still refused; everything else audit / allow). Compliance postures: `hipaa` / `pci-dss` / `soc2` strict overlay; `gdpr` balanced overlay. Auto-registers into `b.guardAll` as a STANDALONE_GUARD; the adaptive integration harness at `test/layer-5-integration/guard-host-integration.test.js` picks it up automatically. 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 are documented in the wiki page.
+
 - **0.7.42** (2026-05-05) — gitleaks allowlist for v0.7.28 CHANGELOG doc-snippet false-positive. The v0.7.28 release-notes entry for `b.crypto.encryptMlkem768X25519` includes a JS-object-literal code example with a `privateKey: mlkemPrivateKey` field; gitleaks' default `generic-api-key` rule fires on the high-entropy content adjacent to the `privateKey:` token, blocking every release-tag CI run since v0.7.38. Allowlisted by commit + fingerprint per the same pattern as the existing `74e627e` entry — surgical suppression of the documented false positive, no broader rule weakening. Working-tree-only or rule-disabling alternatives were rejected: gitleaks' `git`-history scan is the stricter gate (catches secrets that landed and were later removed) and the documented snippet contains no real secret.
 
 - **0.7.41** (2026-05-05) — wiki primitive-validator BACKLOG sweep: 50 of 101 entries pruned. Audited every entry in `examples/wiki/test/validate-primitive-sections.js`'s `UNDOCUMENTED_BACKLOG` map against the actual wiki page bodies; primitives that already have signature-form headings (`b.X.Y(...)`) discovered by the validator no longer need a BACKLOG entry suppressing them. Removed entries: `consent`, `websocketChannels`, `ssrfGuard`, `htmlBalance`, `csv`, `uuid`, `time`, `mailBounce`, `archive`, `breakGlass`, `forms`, `render`, `errorPage`, `cluster`, `safeBuffer`, `safeSql`, `safeUrl`, `retry`, `fileType`, `scheduler`, `jobs`, `backup`, `restore`, `i18n`, `cache`, `crypto`, `createApp`, `fileUpload`, `mtlsCa`, `pqcGate`, `pqcAgent`, `permissions`, `apiKey`, `webhook`, `notify`, `credentialHash`, `queue`, plus the 11-guard family (`guardEmail` through `guardAll`). The remaining 51 entries fall into three real classes: namespace-level entries with method-only headings (vault primitives, audit chain, etc.), pages structured around backend-builder patterns instead of flat methods (`objectStore`, `backupBundle`, etc.), and internal helpers that aren't part of the operator surface (`cli`, `boot`, `dev`, `protocolDispatcher`). The shrunk BACKLOG narrows the gap operators see between "covered by the parent's wiki page" and "actually drift waiting to be fixed."

package/index.js

@@ -110,6 +110,8 @@ var guardYaml = require("./lib/guard-yaml");
 var guardXml = require("./lib/guard-xml");
 var guardMarkdown = require("./lib/guard-markdown");
 var guardEmail = require("./lib/guard-email");
+var guardDomain = require("./lib/guard-domain");
+var guardUuid = require("./lib/guard-uuid");
 var guardAll = require("./lib/guard-all");
 var ssrfGuard = require("./lib/ssrf-guard");
 var authHeader = require("./lib/auth-header");
@@ -251,6 +253,8 @@ module.exports = {
   guardXml:         guardXml,
   guardMarkdown:    guardMarkdown,
   guardEmail:       guardEmail,
+  guardDomain:      guardDomain,
+  guardUuid:        guardUuid,
   guardAll:         guardAll,
   ssrfGuard:        ssrfGuard,
   authHeader:       authHeader,

package/lib/framework-error.js

@@ -249,6 +249,21 @@ var GuardMarkdownError    = defineClass("GuardMarkdownError",    { alwaysPermane
 // in addresses, bidi/null/control chars in headers + addresses, header-
 // folding smuggling, BOM injection. alwaysPermanent.
 var GuardEmailError       = defineClass("GuardEmailError",       { alwaysPermanent: true });
+// GuardDomainError covers domain-name identifier violations: RFC 1035
+// length-cap overflow, RFC 952/1123 LDH-rule violations, IDN homograph /
+// mixed-script confusables, BIDI / zero-width / control-byte injection,
+// Punycode malformation, RFC 6761 special-use domains, IPv4-as-domain
+// confusion (CVE-2021-22931), IPv6 bracket literals, single-label / TLD-
+// only strings, wildcard labels, RFC 8552 underscore-label misuse, DGA
+// high-entropy labels. alwaysPermanent.
+var GuardDomainError      = defineClass("GuardDomainError",      { alwaysPermanent: true });
+// GuardUuidError covers UUID identifier violations: shape malformation
+// (non-canonical / non-hex), RFC 9562 §4.2 unassigned version digits,
+// non-RFC 4122 variant bits, nil UUID (§5.9) / max UUID (§5.10) sentinel
+// leakage, urn:uuid: + Microsoft GUID braces forms outside the operator's
+// declared formatPolicy, BIDI / zero-width / control-byte / null-byte
+// universal refuse. alwaysPermanent.
+var GuardUuidError        = defineClass("GuardUuidError",        { alwaysPermanent: true });
 // DoraError covers DORA Article 17 incident-reporting workflow errors
 // (classification refusal, report-shape validation, ESA-template
 // generation, audit-chain integration). Permanent — these are
@@ -308,6 +323,8 @@ module.exports = {
   GuardXmlError:          GuardXmlError,
   GuardMarkdownError:     GuardMarkdownError,
   GuardEmailError:        GuardEmailError,
+  GuardDomainError:       GuardDomainError,
+  GuardUuidError:         GuardUuidError,
   DoraError:              DoraError,
   ComplianceError:        ComplianceError,
   SmtpPolicyError:        SmtpPolicyError,

package/lib/guard-all.js

@@ -89,6 +89,8 @@ var GUARDS = [
 // adaptive integration harness iterates `allGuards()` to pick them up.
 var STANDALONE_GUARDS = [
   require("./guard-filename"),
+  require("./guard-domain"),
+  require("./guard-uuid"),
 ];
 
 // Framework-wide profile + posture vocabulary that every guard MUST

package/lib/guard-domain.js

@@ -0,0 +1,692 @@
+"use strict";
+/**
+ * guard-domain — Domain-name identifier-safety primitive (b.guardDomain).
+ *
+ * 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).
+ *
+ * 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).
+ *
+ *   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" });
+ *
+ * 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.
+ */
+
+var codepointClass = require("./codepoint-class");
+var lazyRequire = require("./lazy-require");
+var gateContract = require("./gate-contract");
+var C = require("./constants");
+var numericBounds = require("./numeric-bounds");
+var { GuardDomainError } = require("./framework-error");
+
+var observability = lazyRequire(function () { return require("./observability"); });
+void observability;
+
+var _err = GuardDomainError.factory;
+
+// ---- RFC 1035 §2.3.4 length caps ----
+
+var LIMIT_LABEL_OCTETS = 63;                                                     // allow:raw-byte-literal — RFC 1035 §2.3.4
+var LIMIT_DOMAIN_OCTETS = 253;                                                   // allow:raw-byte-literal — RFC 1035 §2.3.4 (255 wire minus length prefixes)
+
+// ---- Static patterns (built from explicit codepoint tables) ----
+
+// LDH label — letters / digits / hyphens, with leading-and-trailing
+// hyphen rejection enforced separately. Length checked separately.
+var LDH_LABEL_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+
+// Service-prefix label per RFC 8552 — `_dmarc`, `_acme-challenge`, …
+var SERVICE_LABEL_RE = /^_[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+
+// Punycode A-label prefix.
+var PUNYCODE_LABEL_RE = /^xn--/i;
+
+// Bare `xn--` with no payload after — malformed A-label.
+var BARE_XN_RE = /^xn--$/i;
+
+// Wildcard label — `*` alone in any label position.
+var WILDCARD_LABEL_RE = /^\*$/;
+
+// IPv4 decimal-dotted form.
+var IPV4_DOTTED_RE = /^(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:\.(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3}$/;
+
+// Looser IPv4 detection — every dot-segment is a numeric form
+// (decimal, octal with leading 0, or hex with 0x prefix), or the whole
+// input is a long-decimal / long-hex (no dots). Catches the parser-
+// permissive forms `0177.0.0.1` (octal), `0xC0.0xA8.0x01.0x01` (hex),
+// `3232235777` (long-decimal), `0xC0A80101` (long-hex).
+//
+// Detection requires at least one digit AND that every dot-segment is a
+// number, so labels like `a.b` (purely alphabetic) don't false-positive
+// as IPv4 even though their codepoints overlap the hex alphabet.
+var IPV4_NUMERIC_SEGMENT_RE = /^(?:0[xX][0-9a-fA-F]+|[0-9]+)$/;
+function _looksLikeIpv4Permissive(s) {
+  if (!/[0-9]/.test(s)) return false;
+  if (IPV4_NUMERIC_SEGMENT_RE.test(s)) {
+    // Long-decimal / long-hex without dots, e.g. `3232235777`.
+    return s.length > 0 && !/^[0-9]+$/.test(s) ? true :
+           // Pure long-decimal — at least 8 digits to count as IPv4
+           // representation, otherwise it's a port-shaped number.
+           s.length >= 8;                                                        // allow:raw-byte-literal — minimum digits to recognize long-decimal IPv4
+  }
+  if (s.indexOf(".") === -1) return false;
+  var parts = s.split(".");
+  if (parts.length !== 4) return false;
+  for (var i = 0; i < parts.length; i += 1) {
+    if (!IPV4_NUMERIC_SEGMENT_RE.test(parts[i])) return false;
+  }
+  return true;
+}
+
+// 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;
+}
+
+// RFC 6761 special-use domains + IETF reserved. Lowercase, no trailing
+// dot. Match by suffix — `_acme-challenge.app.localhost` → `.localhost`.
+//
+// Excluded deliberately: `example.com` / `example.net` / `example.org`.
+// Those are documentation-reserved but legitimately appear in test
+// fixtures and SSO redirect-URI examples; refusing them at strict
+// trips operators on benign inputs. A future `documentation-reserved`
+// posture can flag them as warn-only when operators ask.
+var SPECIAL_USE_DOMAINS = Object.freeze([
+  "localhost",
+  "local",            // RFC 6762 mDNS
+  "invalid",
+  "test",
+  "onion",            // RFC 7686
+  "alt",              // RFC 9476
+  "home.arpa",        // RFC 8375
+  "internal",         // ICANN reserved 2024
+]);
+
+function _matchesSpecialUse(name) {
+  var lower = name.toLowerCase().replace(/\.$/, "");
+  for (var i = 0; i < SPECIAL_USE_DOMAINS.length; i += 1) {
+    var su = SPECIAL_USE_DOMAINS[i];
+    if (lower === su || lower.endsWith("." + su)) return su;
+  }
+  return null;
+}
+
+// Shannon entropy in bits per character over a-z0-9 alphabet, used as
+// a DGA heuristic. Returns 0 for trivial inputs.
+function _shannonEntropy(s) {
+  if (!s || s.length < 2) return 0;
+  var counts = Object.create(null);
+  for (var i = 0; i < s.length; i += 1) {
+    var c = s.charAt(i).toLowerCase();
+    counts[c] = (counts[c] || 0) + 1;
+  }
+  var len = s.length;
+  var h = 0;
+  var keys = Object.keys(counts);
+  for (var k = 0; k < keys.length; k += 1) {
+    var p = counts[keys[k]] / len;
+    h -= p * Math.log2(p);
+  }
+  return h;
+}
+
+// ---- Profile presets ----
+
+var PROFILES = Object.freeze({
+  "strict": {
+    bidiPolicy:           "reject",
+    controlPolicy:        "reject",
+    nullBytePolicy:       "reject",
+    zeroWidthPolicy:      "reject",
+    ldhPolicy:            "reject",
+    underscorePolicy:     "reject",                                              // strict refuses service labels too
+    punycodePolicy:       "reject",
+    mixedScriptPolicy:    "reject",
+    specialUsePolicy:     "reject",
+    ipLiteralPolicy:      "reject",
+    wildcardPolicy:       "reject",
+    singleLabelPolicy:    "reject",
+    trailingDotPolicy:    "normalize",
+    dgaPolicy:            "reject",
+    allowedScripts:       ["latin"],
+    dgaEntropyThreshold:  3.8,                                                   // allow:raw-byte-literal — Shannon entropy bits/char threshold (DGA heuristic)
+    dgaMinLabelLen:       12,                                                    // allow:raw-byte-literal — DGA heuristic floor
+    maxLabelOctets:       LIMIT_LABEL_OCTETS,
+    maxDomainOctets:      LIMIT_DOMAIN_OCTETS,
+    maxBytes:             C.BYTES.bytes(2048),
+    maxRuntimeMs:         C.TIME.seconds(2),
+  },
+  "balanced": {
+    bidiPolicy:           "reject",
+    controlPolicy:        "reject",
+    nullBytePolicy:       "reject",
+    zeroWidthPolicy:      "reject",
+    ldhPolicy:            "reject",
+    underscorePolicy:     "reject",
+    punycodePolicy:       "audit",
+    mixedScriptPolicy:    "reject",
+    specialUsePolicy:     "reject",
+    ipLiteralPolicy:      "reject",
+    wildcardPolicy:       "reject",
+    singleLabelPolicy:    "reject",
+    trailingDotPolicy:    "normalize",
+    dgaPolicy:            "audit",
+    allowedScripts:       ["latin", "cyrillic", "greek", "han", "hiragana",
+                           "katakana", "hangul"],
+    dgaEntropyThreshold:  3.8,                                                   // allow:raw-byte-literal — Shannon entropy bits/char threshold (DGA heuristic)
+    dgaMinLabelLen:       12,                                                    // allow:raw-byte-literal — DGA heuristic floor
+    maxLabelOctets:       LIMIT_LABEL_OCTETS,
+    maxDomainOctets:      LIMIT_DOMAIN_OCTETS,
+    maxBytes:             C.BYTES.bytes(2048),
+    maxRuntimeMs:         C.TIME.seconds(2),
+  },
+  "permissive": {
+    bidiPolicy:           "reject",                                              // BIDI refused at every profile — universal forgery
+    controlPolicy:        "reject",                                              // control bytes refused at every profile
+    nullBytePolicy:       "reject",                                              // null refused at every profile
+    zeroWidthPolicy:      "reject",                                              // zero-width refused at every profile — invisible label-segmentation
+    ldhPolicy:            "audit",
+    underscorePolicy:     "allow",                                               // service labels permitted in permissive
+    punycodePolicy:       "allow",
+    mixedScriptPolicy:    "audit",
+    specialUsePolicy:     "audit",
+    ipLiteralPolicy:      "allow",
+    wildcardPolicy:       "reject",                                              // wildcard refused at every profile — never user-input
+    singleLabelPolicy:    "audit",
+    trailingDotPolicy:    "normalize",
+    dgaPolicy:            "allow",
+    allowedScripts:       null,
+    dgaEntropyThreshold:  3.8,                                                   // allow:raw-byte-literal — Shannon entropy bits/char threshold (DGA heuristic)
+    dgaMinLabelLen:       12,                                                    // allow:raw-byte-literal — DGA heuristic floor
+    maxLabelOctets:       LIMIT_LABEL_OCTETS,
+    maxDomainOctets:      LIMIT_DOMAIN_OCTETS,
+    maxBytes:             C.BYTES.bytes(2048),
+    maxRuntimeMs:         C.TIME.seconds(2),
+  },
+});
+
+var DEFAULTS = Object.freeze(Object.assign({}, PROFILES["strict"], {
+  mode: "enforce",
+}));
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  "hipaa":   Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(256),
+  }),
+  "pci-dss": Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(256),
+  }),
+  "gdpr":    Object.assign({}, PROFILES["balanced"], {
+    forensicSnippetBytes: C.BYTES.bytes(128),
+  }),
+  "soc2":    Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(512),
+  }),
+});
+
+function _resolveOpts(opts) {
+  return gateContract.resolveProfileAndPosture(opts, {
+    profiles:           PROFILES,
+    compliancePostures: COMPLIANCE_POSTURES,
+    defaults:           DEFAULTS,
+    errorClass:         GuardDomainError,
+    errCodePrefix:      "domain",
+  });
+}
+
+// ---- Detection ----
+
+function _detectIssues(input, opts) {
+  var issues = [];
+  if (typeof input !== "string") {
+    return [{ kind: "bad-input", severity: "high",
+              ruleId: "domain.bad-input",
+              snippet: "domain is not a string" }];
+  }
+
+  // Total-length cap (UTF-8 byte count, not codepoint count, per RFC 1035).
+  var byteLen = Buffer.byteLength(input, "utf8");
+  if (byteLen > opts.maxDomainOctets) {
+    issues.push({
+      kind: "domain-cap", severity: "high",
+      ruleId: "domain.domain-cap",
+      snippet: "domain " + byteLen + " octets exceeds " +
+               opts.maxDomainOctets + " (RFC 1035 §2.3.4)",
+    });
+    return issues;                                                               // size cap is structural — abort further checks
+  }
+
+  // Codepoint-class threats (BIDI / control / null / zero-width). These
+  // are universal-refuse — running them first lets the more specific
+  // structural checks operate on a sanitized-or-refused input.
+  var charThreats = codepointClass.detectCharThreats(input, opts, "domain");
+  for (var ci = 0; ci < charThreats.length; ci += 1) issues.push(charThreats[ci]);
+
+  // Trailing-dot — FQDN distinguisher. Normalize for downstream checks
+  // but record as audit if operator wants to know.
+  var hadTrailingDot = input.charAt(input.length - 1) === ".";
+  var name = hadTrailingDot ? input.slice(0, -1) : input;
+
+  // Empty string after trim.
+  if (name.length === 0) {
+    issues.push({
+      kind: "empty", severity: "high",
+      ruleId: "domain.empty",
+      snippet: "domain is empty",
+    });
+    return issues;
+  }
+
+  // Bracketed IPv6 literal.
+  if (IPV6_BRACKET_RE.test(name)) {
+    if (opts.ipLiteralPolicy !== "allow") {
+      issues.push({
+        kind: "ipv6-literal",
+        severity: opts.ipLiteralPolicy === "reject" ? "high" : "warn",
+        ruleId: "domain.ipv6-literal",
+        snippet: "input is an IPv6 bracket literal — bypasses DNS-name " +
+                 "validation; pass through opts.allowIp if intended",
+      });
+    }
+    return issues;
+  }
+
+  // IPv4 detection — strict dotted-decimal AND loose (octal/hex/long).
+  if (IPV4_DOTTED_RE.test(name) || _looksLikeIpv4Permissive(name)) {
+    if (opts.ipLiteralPolicy !== "allow") {
+      issues.push({
+        kind: "ipv4-as-domain",
+        severity: opts.ipLiteralPolicy === "reject" ? "high" : "warn",
+        ruleId: "domain.ipv4-as-domain",
+        snippet: "input parses as IPv4 (CVE-2021-22931 class) — " +
+                 "DNS-rebinding risk against allowlist matchers",
+      });
+      // Don't continue to label parsing — IPv4-shaped strings would
+      // collide with single-label / LDH errors and confuse the operator.
+      return issues;
+    }
+  }
+
+  // RFC 6761 special-use suffix.
+  var su = _matchesSpecialUse(name);
+  if (su && opts.specialUsePolicy !== "allow") {
+    issues.push({
+      kind: "special-use",
+      severity: opts.specialUsePolicy === "reject" ? "high" : "warn",
+      ruleId: "domain.special-use",
+      snippet: "domain matches RFC 6761 / IETF reserved suffix `." + su + "` " +
+               "— would route to loopback / mDNS / Tor / LAN",
+    });
+  }
+
+  // Label split + per-label structural checks.
+  var labels = name.split(".");
+
+  // Single-label / TLD-only.
+  if (labels.length < 2) {
+    if (opts.singleLabelPolicy !== "allow") {
+      issues.push({
+        kind: "single-label",
+        severity: opts.singleLabelPolicy === "reject" ? "high" : "warn",
+        ruleId: "domain.single-label",
+        snippet: "single-label / TLD-only domain — risks search-domain " +
+                 "suffixing on misconfigured stub resolvers",
+      });
+    }
+  }
+
+  for (var li = 0; li < labels.length; li += 1) {
+    var label = labels[li];
+
+    // Empty label (e.g. `foo..bar` or leading `.foo`).
+    if (label.length === 0) {
+      issues.push({
+        kind: "empty-label", severity: "high",
+        ruleId: "domain.empty-label",
+        snippet: "label " + (li + 1) + " is empty (consecutive or " +
+                 "leading dots)",
+      });
+      continue;
+    }
+
+    var labelBytes = Buffer.byteLength(label, "utf8");
+    if (labelBytes > opts.maxLabelOctets) {
+      issues.push({
+        kind: "label-cap", severity: "high",
+        ruleId: "domain.label-cap",
+        snippet: "label " + (li + 1) + " is " + labelBytes +
+                 " octets, exceeds " + opts.maxLabelOctets +
+                 " (RFC 1035 §2.3.4)",
+      });
+      continue;                                                                  // label-cap masks downstream rule failures
+    }
+
+    // Wildcard `*`.
+    if (WILDCARD_LABEL_RE.test(label)) {                                         // allow:regex-no-length-cap — label bounded by maxLabelOctets above
+      if (opts.wildcardPolicy !== "allow") {
+        issues.push({
+          kind: "wildcard", severity: "high",
+          ruleId: "domain.wildcard",
+          snippet: "wildcard label `*` — valid in TLS SAN / DNS RR but " +
+                   "never in a user-input identifier",
+        });
+      }
+      continue;
+    }
+
+    // Service-prefix label (RFC 8552). Underscore allowed only if
+    // operator opts in.
+    if (label.charAt(0) === "_") {
+      if (SERVICE_LABEL_RE.test(label)) {                                        // allow:regex-no-length-cap — label bounded by maxLabelOctets above
+        if (opts.underscorePolicy !== "allow") {
+          issues.push({
+            kind: "underscore-label",
+            severity: opts.underscorePolicy === "reject" ? "high" : "warn",
+            ruleId: "domain.underscore-label",
+            snippet: "label " + (li + 1) + " starts with `_` (RFC 8552 " +
+                     "service label) — never valid as a hostname",
+          });
+        }
+      } else {
+        issues.push({
+          kind: "underscore-malformed", severity: "high",
+          ruleId: "domain.underscore-malformed",
+          snippet: "label " + (li + 1) + " starts with `_` but doesn't " +
+                   "match the service-label grammar",
+        });
+      }
+      continue;
+    }
+
+    // Punycode A-label.
+    if (PUNYCODE_LABEL_RE.test(label)) {                                         // allow:regex-no-length-cap — label bounded by maxLabelOctets above
+      if (BARE_XN_RE.test(label)) {                                              // allow:regex-no-length-cap — label bounded by maxLabelOctets above
+        issues.push({
+          kind: "punycode-bare", severity: "high",
+          ruleId: "domain.punycode-bare",
+          snippet: "label " + (li + 1) + " is bare `xn--` with no " +
+                   "Punycode payload",
+        });
+        continue;
+      }
+      if (opts.punycodePolicy !== "allow") {
+        issues.push({
+          kind: "punycode-label",
+          severity: opts.punycodePolicy === "reject" ? "high" : "warn",
+          ruleId: "domain.punycode-label",
+          snippet: "label " + (li + 1) + " is an IDN A-label (`xn--`) — " +
+                   "homograph-spoofing class without round-trip validation",
+        });
+      }
+      // ASCII LDH check still applies.
+      if (!LDH_LABEL_RE.test(label) && opts.ldhPolicy !== "allow") {             // allow:regex-no-length-cap — label bounded by maxLabelOctets above
+        issues.push({
+          kind: "ldh-violation", severity: "high",
+          ruleId: "domain.ldh-violation",
+          snippet: "label " + (li + 1) + " (Punycode form) violates LDH " +
+                   "rule (RFC 952 / 1123 §2.1)",
+        });
+      }
+      continue;
+    }
+
+    // ASCII LDH or Unicode label.
+    var allAscii = true;
+    for (var ai = 0; ai < label.length; ai += 1) {
+      if (label.charCodeAt(ai) > 0x7F) { allAscii = false; break; }              // allow:raw-byte-literal — ASCII boundary codepoint
+    }
+
+    if (allAscii) {
+      if (!LDH_LABEL_RE.test(label) && opts.ldhPolicy !== "allow") {             // allow:regex-no-length-cap — label bounded by maxLabelOctets above
+        issues.push({
+          kind: "ldh-violation",
+          severity: opts.ldhPolicy === "reject" ? "high" : "warn",
+          ruleId: "domain.ldh-violation",
+          snippet: "label " + (li + 1) + " " + JSON.stringify(label) +
+                   " violates LDH rule (RFC 952 / 1123 §2.1)",
+        });
+      }
+      // Position-3-4 double-hyphen check excluding the `xn--` prefix.
+      if (label.length >= 4 && label.charAt(2) === "-" &&
+          label.charAt(3) === "-" && !PUNYCODE_LABEL_RE.test(label)) {
+        issues.push({
+          kind: "double-hyphen", severity: "warn",
+          ruleId: "domain.double-hyphen",
+          snippet: "label " + (li + 1) + " has `--` at positions 3-4 " +
+                   "without the `xn--` IDN prefix",
+        });
+      }
+    } else {
+      // Unicode label — flag mixed-script confusables and strict-LDH
+      // operators that didn't opt into IDN.
+      if (opts.punycodePolicy !== "allow") {
+        // Operator wants Punycode-only; reject raw Unicode labels.
+        issues.push({
+          kind: "raw-unicode-label",
+          severity: opts.punycodePolicy === "reject" ? "high" : "warn",
+          ruleId: "domain.raw-unicode-label",
+          snippet: "label " + (li + 1) + " contains raw Unicode " +
+                   "(non-ASCII) — IDN labels must be Punycode-encoded " +
+                   "(`xn--…`) for transport-safe comparison",
+        });
+      }
+      var mixed = _detectMixedScripts(label, opts.allowedScripts);
+      if (mixed && opts.mixedScriptPolicy !== "allow") {
+        issues.push({
+          kind: "mixed-script",
+          severity: opts.mixedScriptPolicy === "reject" ? "critical" : "high",
+          ruleId: "domain.mixed-script",
+          snippet: "label " + (li + 1) + " mixes scripts (" +
+                   mixed.join(", ") + ") — IDN homograph spoofing class",
+        });
+      }
+    }
+
+    // DGA entropy heuristic — high-entropy long single label is C2-shape.
+    if (label.length >= opts.dgaMinLabelLen && opts.dgaPolicy !== "allow") {
+      var h = _shannonEntropy(label);
+      if (h >= opts.dgaEntropyThreshold) {
+        issues.push({
+          kind: "dga-entropy",
+          severity: opts.dgaPolicy === "reject" ? "high" : "warn",
+          ruleId: "domain.dga-entropy",
+          snippet: "label " + (li + 1) + " has Shannon entropy " +
+                   h.toFixed(2) + " bits/char (>= " +
+                   opts.dgaEntropyThreshold + ") — C2 / DGA shape",
+        });
+      }
+    }
+  }
+
+  // Trailing-dot audit signal (after structural checks, before return).
+  if (hadTrailingDot && opts.trailingDotPolicy === "audit") {
+    issues.push({
+      kind: "trailing-dot", severity: "warn",
+      ruleId: "domain.trailing-dot",
+      snippet: "input had trailing dot (FQDN-marker) — normalize/strip " +
+               "before allowlist comparison",
+    });
+  }
+
+  return issues;
+}
+
+function validate(input, opts) {
+  opts = _resolveOpts(opts);
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["maxLabelOctets", "maxDomainOctets", "maxBytes", "dgaMinLabelLen"],
+    "guardDomain.validate", GuardDomainError, "domain.bad-opt");
+  if (typeof input !== "string") {
+    return {
+      ok: false,
+      issues: [{ kind: "bad-input", severity: "high",
+                 ruleId: "domain.bad-input",
+                 snippet: "domain is not a string" }],
+    };
+  }
+  return gateContract.aggregateIssues(_detectIssues(input, opts));
+}
+
+function sanitize(input, opts) {
+  opts = _resolveOpts(opts);
+  if (typeof input !== "string") {
+    throw _err("domain.bad-input", "sanitize requires string input");
+  }
+  // Critical refuses can't be repaired.
+  var issues = _detectIssues(input, opts);
+  for (var i = 0; i < issues.length; i += 1) {
+    if (issues[i].severity === "critical" || issues[i].severity === "high") {
+      throw _err(issues[i].ruleId || "domain.refused",
+        "guardDomain.sanitize: " + issues[i].snippet);
+    }
+  }
+  // Safe transforms: lowercase ASCII, strip trailing dot.
+  var out = input.toLowerCase();
+  if (out.charAt(out.length - 1) === ".") out = out.slice(0, -1);
+  return out;
+}
+
+function gate(opts) {
+  opts = _resolveOpts(opts);
+  return gateContract.buildGuardGate(
+    opts.name || "guardDomain:" + (opts.profile || "default"),
+    opts,
+    async function (ctx) {
+      // Identifier-shape ctx — operator passes via ctx.identifier or
+      // ctx.domain.
+      var identifier = ctx && (ctx.identifier || ctx.domain || "");
+      if (!identifier) return { ok: true, action: "serve" };
+      var rv = validate(identifier, opts);
+      if (rv.issues.length === 0) return { ok: true, action: "serve" };
+      var hasCritical = rv.issues.some(function (i) {
+        return i.severity === "critical";
+      });
+      var hasHigh = rv.issues.some(function (i) {
+        return i.severity === "high";
+      });
+      if (!hasCritical && !hasHigh) {
+        return { ok: true, action: "audit-only", issues: rv.issues };
+      }
+      return { ok: false, action: "refuse", issues: rv.issues };
+    });
+}
+
+var buildProfile = gateContract.makeProfileBuilder(PROFILES);
+
+function compliancePosture(name) {
+  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
+    _err, "domain");
+}
+
+var _domainRulePacks = gateContract.makeRulePackLoader(GuardDomainError, "domain");
+var loadRulePack = _domainRulePacks.load;
+
+module.exports = {
+  // ---- guard-* family registry exports ----
+  NAME:                "domain",
+  KIND:                "identifier",
+  INTEGRATION_FIXTURES: Object.freeze({
+    kind:        "identifier",
+    benignBytes: Buffer.from("example.com", "utf8"),
+    // Hostile: dotted-decimal IPv4 (CVE-2021-22931 class) — every
+    // profile refuses (allowlist-bypass via DNS rebinding).
+    hostileBytes: Buffer.from("192.168.1.1", "utf8"),
+    benignIdentifier:  "example.com",
+    hostileIdentifier: "192.168.1.1",
+  }),
+  // ---- primitive surface ----
+  validate:            validate,
+  sanitize:            sanitize,
+  gate:                gate,
+  buildProfile:        buildProfile,
+  compliancePosture:   compliancePosture,
+  loadRulePack:        loadRulePack,
+  PROFILES:            PROFILES,
+  DEFAULTS:            DEFAULTS,
+  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
+  GuardDomainError:    GuardDomainError,
+};

package/lib/guard-uuid.js

@@ -0,0 +1,389 @@
+"use strict";
+/**
+ * guard-uuid — UUID identifier-safety primitive (b.guardUuid).
+ *
+ * Validates user-supplied UUID strings per RFC 9562 (May 2024,
+ * obsoletes RFC 4122). KIND="identifier" — consumes ctx.identifier
+ * (or ctx.uuid).
+ *
+ * Threat catalog:
+ *   - Wrong length / shape — UUIDs are 36 chars with hyphens, 32 hex
+ *     without, or 38 with Microsoft GUID braces; anything else is
+ *     malformed and a downstream parser may diverge.
+ *   - Wrong character class — non-hex characters anywhere.
+ *   - Invalid version field (RFC 9562 §4.2) — versions 1-8 are
+ *     defined; 0 and 9-F are reserved/unassigned and indicate
+ *     hand-rolled or attacker-shaped IDs.
+ *   - Variant bits (RFC 9562 §4.1) — only 10xx (RFC 4122/9562
+ *     variant) is the canonical UUID variant; other variants
+ *     (NCS-reserved 0xxx, Microsoft-reserved 110x, future-reserved
+ *     111x) often indicate non-UUID payloads coerced into the slot.
+ *   - Nil UUID (RFC 9562 §5.9 — all zeros) — usually represents
+ *     "no UUID set"; passing through can mask a missing-key bug.
+ *   - Max UUID (RFC 9562 §5.10 — all FF) — sentinel value with the
+ *     same semantic risk as nil.
+ *   - urn:uuid: prefix (RFC 4122 §3) — when not requested by the
+ *     caller, can disguise a UUID inside a URN-shape parser.
+ *   - Microsoft GUID braces `{...}` — disguise a UUID inside a
+ *     COM-style serialization parser.
+ *   - BIDI / zero-width / control / null-byte — universal-refuse.
+ *
+ *   var rv = b.guardUuid.validate("550e8400-e29b-41d4-a716-446655440000",
+ *                                 { profile: "strict" });
+ *   var safe = b.guardUuid.sanitize("urn:uuid:550E8400-...",
+ *                                   { profile: "balanced" });
+ *   var g = b.guardUuid.gate({ profile: "strict" });
+ */
+
+var codepointClass = require("./codepoint-class");
+var lazyRequire = require("./lazy-require");
+var gateContract = require("./gate-contract");
+var C = require("./constants");
+var numericBounds = require("./numeric-bounds");
+var { GuardUuidError } = require("./framework-error");
+
+var observability = lazyRequire(function () { return require("./observability"); });
+void observability;
+
+var _err = GuardUuidError.factory;
+
+// ---- Static patterns ----
+
+// Canonical RFC 9562 form: 8-4-4-4-12 hex chars with dashes.
+var UUID_HYPHENATED_RE = /^([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})$/i;
+
+// Hyphenless 32-hex form (some serializers strip the hyphens).
+var UUID_HYPHENLESS_RE = /^[0-9a-f]{32}$/i;
+
+// Microsoft GUID-with-braces form.
+var UUID_BRACED_RE = /^\{([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})\}$/i;
+
+// urn:uuid: prefix form.
+var UUID_URN_RE = /^urn:uuid:([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})$/i;
+
+var NIL_HEX = "00000000000000000000000000000000";
+var MAX_HEX = "ffffffffffffffffffffffffffffffff";
+
+// ---- Profile presets ----
+
+var PROFILES = Object.freeze({
+  "strict": {
+    bidiPolicy:        "reject",
+    controlPolicy:     "reject",
+    nullBytePolicy:    "reject",
+    zeroWidthPolicy:   "reject",
+    formatPolicy:      "hyphenated-only",   // hyphenated | hyphenless | braced | urn | hyphenated-only | any
+    versionPolicy:     "reject-unassigned", // reject-unassigned | audit | allow
+    variantPolicy:     "reject-non-rfc",    // reject-non-rfc | audit | allow
+    nilPolicy:         "reject",
+    maxPolicy:         "reject",
+    urnPolicy:         "reject",
+    bracedPolicy:      "reject",
+    allowedVersions:   [1, 2, 3, 4, 5, 6, 7, 8],                                 // allow:raw-byte-literal — UUID version digits
+    maxBytes:          C.BYTES.bytes(64),
+    maxRuntimeMs:      C.TIME.seconds(2),
+  },
+  "balanced": {
+    bidiPolicy:        "reject",
+    controlPolicy:     "reject",
+    nullBytePolicy:    "reject",
+    zeroWidthPolicy:   "reject",
+    formatPolicy:      "any",
+    versionPolicy:     "reject-unassigned",
+    variantPolicy:     "audit",
+    nilPolicy:         "audit",
+    maxPolicy:         "audit",
+    urnPolicy:         "audit",
+    bracedPolicy:      "audit",
+    allowedVersions:   [1, 2, 3, 4, 5, 6, 7, 8],                                 // allow:raw-byte-literal — UUID version digits
+    maxBytes:          C.BYTES.bytes(64),
+    maxRuntimeMs:      C.TIME.seconds(2),
+  },
+  "permissive": {
+    bidiPolicy:        "reject",                                                 // BIDI refused at every profile
+    controlPolicy:     "reject",                                                 // controls refused at every profile
+    nullBytePolicy:    "reject",                                                 // null refused at every profile
+    zeroWidthPolicy:   "reject",                                                 // zero-width refused at every profile
+    formatPolicy:      "any",
+    versionPolicy:     "audit",
+    variantPolicy:     "allow",
+    nilPolicy:         "allow",
+    maxPolicy:         "allow",
+    urnPolicy:         "allow",
+    bracedPolicy:      "allow",
+    allowedVersions:   null,                                                     // any version
+    maxBytes:          C.BYTES.bytes(64),
+    maxRuntimeMs:      C.TIME.seconds(2),
+  },
+});
+
+var DEFAULTS = Object.freeze(Object.assign({}, PROFILES["strict"], {
+  mode: "enforce",
+}));
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  "hipaa":   Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(128),
+  }),
+  "pci-dss": Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(128),
+  }),
+  "gdpr":    Object.assign({}, PROFILES["balanced"], {
+    forensicSnippetBytes: C.BYTES.bytes(64),
+  }),
+  "soc2":    Object.assign({}, PROFILES["strict"], {
+    forensicSnippetBytes: C.BYTES.bytes(256),
+  }),
+});
+
+function _resolveOpts(opts) {
+  return gateContract.resolveProfileAndPosture(opts, {
+    profiles:           PROFILES,
+    compliancePostures: COMPLIANCE_POSTURES,
+    defaults:           DEFAULTS,
+    errorClass:         GuardUuidError,
+    errCodePrefix:      "uuid",
+  });
+}
+
+function _classifyForm(input) {
+  if (UUID_URN_RE.test(input)) return "urn";                                     // allow:regex-no-length-cap — input bounded by maxBytes
+  if (UUID_BRACED_RE.test(input)) return "braced";                               // allow:regex-no-length-cap — input bounded by maxBytes
+  if (UUID_HYPHENATED_RE.test(input)) return "hyphenated";                       // allow:regex-no-length-cap — input bounded by maxBytes
+  if (UUID_HYPHENLESS_RE.test(input)) return "hyphenless";                       // allow:regex-no-length-cap — input bounded by maxBytes
+  return null;
+}
+
+function _toCanonicalHex(input, form) {
+  // Strips dashes / braces / urn prefix, returns 32-char lowercase hex.
+  var s = input.toLowerCase();
+  if (form === "urn")     s = s.slice("urn:uuid:".length);                       // allow:raw-byte-literal — string-length offset
+  if (form === "braced")  s = s.slice(1, -1);                                    // allow:raw-byte-literal — string-length offset
+  return s.replace(/-/g, "");
+}
+
+function _detectIssues(input, opts) {
+  var issues = [];
+  if (typeof input !== "string") {
+    return [{ kind: "bad-input", severity: "high",
+              ruleId: "uuid.bad-input",
+              snippet: "uuid is not a string" }];
+  }
+  if (input.length === 0) {
+    return [{ kind: "empty", severity: "high",
+              ruleId: "uuid.empty",
+              snippet: "uuid is empty" }];
+  }
+  if (Buffer.byteLength(input, "utf8") > opts.maxBytes) {
+    return [{ kind: "uuid-cap", severity: "high",
+              ruleId: "uuid.uuid-cap",
+              snippet: "uuid input exceeds maxBytes " + opts.maxBytes }];
+  }
+
+  // Codepoint-class threats (universal refuse — runs first).
+  var charThreats = codepointClass.detectCharThreats(input, opts, "uuid");
+  for (var ci = 0; ci < charThreats.length; ci += 1) issues.push(charThreats[ci]);
+
+  // Format classification.
+  var form = _classifyForm(input);
+  if (form === null) {
+    issues.push({
+      kind: "uuid-shape", severity: "high",
+      ruleId: "uuid.uuid-shape",
+      snippet: "input does not match any RFC 9562 UUID form " +
+               "(hyphenated / hyphenless / braced / urn:uuid:)",
+    });
+    return issues;
+  }
+
+  // Format-policy enforcement.
+  var formatPolicy = opts.formatPolicy;
+  var formAllowed = (
+    formatPolicy === "any" ||
+    formatPolicy === form ||
+    (formatPolicy === "hyphenated-only" && form === "hyphenated")
+  );
+  if (!formAllowed) {
+    issues.push({
+      kind: "uuid-form-disallowed",
+      severity: "high",
+      ruleId: "uuid.uuid-form-disallowed",
+      snippet: "uuid form `" + form + "` not permitted by formatPolicy `" +
+               formatPolicy + "`",
+    });
+  }
+  if (form === "urn" && opts.urnPolicy !== "allow") {
+    issues.push({
+      kind: "urn-prefix",
+      severity: opts.urnPolicy === "reject" ? "high" : "warn",
+      ruleId: "uuid.urn-prefix",
+      snippet: "uuid carries `urn:uuid:` prefix — would be processed " +
+               "by URN-shape parsers downstream",
+    });
+  }
+  if (form === "braced" && opts.bracedPolicy !== "allow") {
+    issues.push({
+      kind: "braced",
+      severity: opts.bracedPolicy === "reject" ? "high" : "warn",
+      ruleId: "uuid.braced",
+      snippet: "uuid uses Microsoft GUID braces `{...}` — non-canonical",
+    });
+  }
+
+  var hex = _toCanonicalHex(input, form);
+
+  // Nil / Max sentinel checks.
+  if (hex === NIL_HEX && opts.nilPolicy !== "allow") {
+    issues.push({
+      kind: "nil-uuid",
+      severity: opts.nilPolicy === "reject" ? "high" : "warn",
+      ruleId: "uuid.nil-uuid",
+      snippet: "uuid is the nil UUID (RFC 9562 §5.9) — sentinel often " +
+               "indicates missing-key bug",
+    });
+  }
+  if (hex === MAX_HEX && opts.maxPolicy !== "allow") {
+    issues.push({
+      kind: "max-uuid",
+      severity: opts.maxPolicy === "reject" ? "high" : "warn",
+      ruleId: "uuid.max-uuid",
+      snippet: "uuid is the max UUID (RFC 9562 §5.10) — sentinel often " +
+               "indicates missing-key bug",
+    });
+  }
+
+  // Version + variant inspection (skip for nil / max — those bypass the
+  // version-bits check by definition).
+  if (hex !== NIL_HEX && hex !== MAX_HEX) {
+    var versionDigit = parseInt(hex.charAt(12), 16);                             // allow:raw-byte-literal — hex digit position 12
+    var variantNibble = parseInt(hex.charAt(16), 16);                            // allow:raw-byte-literal — hex digit position 16
+
+    if (opts.versionPolicy !== "allow") {
+      var allowed = opts.allowedVersions;
+      var versionOk = !allowed || allowed.indexOf(versionDigit) !== -1;
+      if (!versionOk) {
+        issues.push({
+          kind: "version-unassigned",
+          severity: opts.versionPolicy === "reject-unassigned" ? "high" : "warn",
+          ruleId: "uuid.version-unassigned",
+          snippet: "uuid version digit " + versionDigit + " not in " +
+                   "allowedVersions " + JSON.stringify(allowed) +
+                   " (RFC 9562 §4.2 defines 1-8)",
+        });
+      }
+    }
+
+    if (opts.variantPolicy !== "allow") {
+      // RFC 4122 / 9562 variant: high two bits of the variant nibble are
+      // 10xx (i.e. nibble in 8/9/a/b).
+      var isRfcVariant = (variantNibble & 0xC) === 0x8;                          // allow:raw-byte-literal — variant-bit mask
+      if (!isRfcVariant) {
+        issues.push({
+          kind: "variant-non-rfc",
+          severity: opts.variantPolicy === "reject-non-rfc" ? "high" : "warn",
+          ruleId: "uuid.variant-non-rfc",
+          snippet: "uuid variant nibble `" + hex.charAt(16) + "` is not " +    // allow:raw-byte-literal — hex digit position 16
+                   "the RFC 4122 / 9562 variant (10xx — nibble 8-b)",
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+function validate(input, opts) {
+  opts = _resolveOpts(opts);
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["maxBytes"],
+    "guardUuid.validate", GuardUuidError, "uuid.bad-opt");
+  if (typeof input !== "string") {
+    return {
+      ok: false,
+      issues: [{ kind: "bad-input", severity: "high",
+                 ruleId: "uuid.bad-input",
+                 snippet: "uuid is not a string" }],
+    };
+  }
+  return gateContract.aggregateIssues(_detectIssues(input, opts));
+}
+
+function sanitize(input, opts) {
+  opts = _resolveOpts(opts);
+  if (typeof input !== "string") {
+    throw _err("uuid.bad-input", "sanitize requires string input");
+  }
+  var issues = _detectIssues(input, opts);
+  for (var i = 0; i < issues.length; i += 1) {
+    if (issues[i].severity === "critical" || issues[i].severity === "high") {
+      throw _err(issues[i].ruleId || "uuid.refused",
+        "guardUuid.sanitize: " + issues[i].snippet);
+    }
+  }
+  // Safe transforms: lowercase + strip braces / urn prefix → canonical
+  // hyphenated form.
+  var form = _classifyForm(input);
+  if (!form) return input;
+  var hex = _toCanonicalHex(input, form);
+  return hex.slice(0, 8) + "-" + hex.slice(8, 12) + "-" +                        // allow:raw-byte-literal — UUID hex slice positions
+         hex.slice(12, 16) + "-" + hex.slice(16, 20) + "-" +                     // allow:raw-byte-literal — UUID hex slice positions
+         hex.slice(20);                                                          // allow:raw-byte-literal — UUID hex slice positions
+}
+
+function gate(opts) {
+  opts = _resolveOpts(opts);
+  return gateContract.buildGuardGate(
+    opts.name || "guardUuid:" + (opts.profile || "default"),
+    opts,
+    async function (ctx) {
+      var identifier = ctx && (ctx.identifier || ctx.uuid || "");
+      if (!identifier) return { ok: true, action: "serve" };
+      var rv = validate(identifier, opts);
+      if (rv.issues.length === 0) return { ok: true, action: "serve" };
+      var hasCritical = rv.issues.some(function (i) {
+        return i.severity === "critical";
+      });
+      var hasHigh = rv.issues.some(function (i) {
+        return i.severity === "high";
+      });
+      if (!hasCritical && !hasHigh) {
+        return { ok: true, action: "audit-only", issues: rv.issues };
+      }
+      return { ok: false, action: "refuse", issues: rv.issues };
+    });
+}
+
+var buildProfile = gateContract.makeProfileBuilder(PROFILES);
+
+function compliancePosture(name) {
+  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES,
+    _err, "uuid");
+}
+
+var _uuidRulePacks = gateContract.makeRulePackLoader(GuardUuidError, "uuid");
+var loadRulePack = _uuidRulePacks.load;
+
+module.exports = {
+  // ---- guard-* family registry exports ----
+  NAME:                "uuid",
+  KIND:                "identifier",
+  INTEGRATION_FIXTURES: Object.freeze({
+    kind:              "identifier",
+    benignBytes:       Buffer.from("550e8400-e29b-41d4-a716-446655440000", "utf8"),
+    hostileBytes:      Buffer.from("00000000-0000-0000-0000-000000000000", "utf8"),
+    benignIdentifier:  "550e8400-e29b-41d4-a716-446655440000",
+    // Hostile: nil UUID — refused at strict (sentinel-leak class).
+    hostileIdentifier: "00000000-0000-0000-0000-000000000000",
+  }),
+  // ---- primitive surface ----
+  validate:            validate,
+  sanitize:            sanitize,
+  gate:                gate,
+  buildProfile:        buildProfile,
+  compliancePosture:   compliancePosture,
+  loadRulePack:        loadRulePack,
+  PROFILES:            PROFILES,
+  DEFAULTS:            DEFAULTS,
+  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
+  GuardUuidError:      GuardUuidError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.42",
+  "version": "0.7.44",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:bc5e4436-ca0f-43ac-a77d-f32a765eb230",
+  "serialNumber": "urn:uuid:2273cc28-4cb1-4b48-8b09-c33dd95383b2",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-05T20:27:13.830Z",
+    "timestamp": "2026-05-05T21:06:13.872Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.42",
+      "bom-ref": "@blamejs/core@0.7.44",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.42",
+      "version": "0.7.44",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.42",
+      "purl": "pkg:npm/%40blamejs/core@0.7.44",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.42",
+      "ref": "@blamejs/core@0.7.44",
       "dependsOn": []
     }
   ]