@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/guard-filename.js

@@ -0,0 +1,956 @@
+"use strict";
+/**
+ * @module b.guardFilename
+ * @nav    Guards
+ * @title  Guard Filename
+ *
+ * @intro
+ *   Filename content-safety primitive (KIND="filename"). Validates
+ *   user-supplied filenames before they reach disk, network paths,
+ *   or Content-Disposition headers. Standalone primitive — does NOT
+ *   register into `b.guardAll`'s content-type-routed dispatch (no
+ *   canonical mime / ext); operators wire it directly via
+ *   `b.fileUpload({ filenameSafety: gate })` and similar host opts.
+ *
+ *   Path-traversal defense: `..` / `../` / `..\\`, percent-encoded
+ *   `%2e%2e`, double-encoded `%252e%252e`, and UTF-8 overlong
+ *   sequences `0xC0 0xAE` (for `.`) and `0xC0 0xAF` (for `/`) ALWAYS
+ *   throw — no profile downgrades the refusal. Threat catalog
+ *   grounded in OWASP Path Traversal + WSTG file-inclusion testing
+ *   guides; CWE-22 / 23 / 35 / 73 / 78 / 434 / 36; PortSwigger
+ *   File-path-traversal series (null-byte bypass + extension
+ *   validation); Memento-RTLO + RTL-Spiegel filename-spoofing
+ *   reports (CVE-2021-42574 in filename context); Kevin Boone
+ *   overlong UTF-8 write-up.
+ *
+ *   Universal-throw security floor: null-byte truncation
+ *   (`file.txt\x00.exe`), NTFS alternate data streams
+ *   (`file.txt:hidden.exe`), UNC paths (`\\server\share\file` and
+ *   `//host/share/file`), and overlong UTF-8 byte sequences ALL
+ *   throw `GuardFilenameError` regardless of profile — there is no
+ *   sanitize-action that repairs these classes. Windows reserved
+ *   device names (CON / PRN / AUX / NUL / COM1-9 / LPT1-9 / CLOCK$
+ *   / CONFIG$) refuse under strict and balanced (even with
+ *   extensions — `CON.txt` collides with the device).
+ *
+ *   Unicode hygiene: BIDI / RTLO refuses at every profile (Memento-
+ *   RTLO `Photo01By‮gpj.SCR` displays as `Photo01ByRCS.jpg` while
+ *   the OS opens `.SCR`). Zero-width and invisible-formatting strip
+ *   under balanced/permissive, refuse under strict. Homoglyph
+ *   (Cyrillic / Greek / fullwidth Latin mixed with ASCII letters)
+ *   refuses under strict, audits under balanced/permissive.
+ *
+ *   Extension policy: operator-supplied `extensionAllowlist`
+ *   catches double-extension bypass (`file.jpg.exe` lands at the
+ *   last `.exe` and refuses). Shell-shortcut / executable extensions
+ *   (`.lnk` / `.url` / `.desktop` / `.scr` / `.bat` / `.cmd` /
+ *   `.com` / `.pif` / `.vbs` / `.js` / `.jse` / `.wsf` / `.wsh` /
+ *   `.ps1` / `.psm1` / `.app` / `.deb` / `.rpm` / `.msi` and the
+ *   broader native-binary family) refuse under strict, audit under
+ *   balanced/permissive.
+ *
+ *   Length caps: 64 bytes (strict), 255 bytes (balanced/permissive).
+ *   Path separators in the leaf refuse under strict/balanced;
+ *   permissive opts in to multi-component paths via
+ *   `pathSeparatorsPolicy: "audit"` and `maxComponents > 1`.
+ *
+ *   Profiles: `strict` / `balanced` / `permissive`. Compliance
+ *   postures: `hipaa` / `pci-dss` / `gdpr` / `soc2`. Threat-detection
+ *   regex literals composed programmatically from numeric codepoint
+ *   range tables (`lib/codepoint-class`); source file never embeds
+ *   attack characters.
+ *
+ * @card
+ *   Filename content-safety primitive (KIND="filename").
+ */
+
+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 { GuardFilenameError } = require("./framework-error");
+
+var observability = lazyRequire(function () { return require("./observability"); });
+void observability;
+
+var _err = GuardFilenameError.factory;
+
+// Reserved characters that must not appear in a filename leaf.
+//   Windows: < > : " / \ | ? *
+//   Unix:    /
+//   Both:    null and C0 controls (handled separately via codepoint-class)
+var RESERVED_CHARS_RE = /[<>:"/\\|?*]/;
+
+// Windows reserved device names (case-insensitive). Match either the
+// bare name or `<name>.<anything>`.
+var WIN_RESERVED_NAMES = Object.freeze([
+  "CON", "PRN", "AUX", "NUL",
+  "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
+  "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
+  "CLOCK$", "CONFIG$",
+]);
+
+// Path-traversal indicators (anchored matches on raw and percent-decoded
+// forms).
+var PATH_TRAVERSAL_RE = /(^|[/\\])\.\.($|[/\\])/;
+var PERCENT_ENCODED_TRAVERSAL_RE = /%2e%2e|%252e%252e|%c0%ae|%c0%af/i;
+var URL_ENCODED_SLASH_RE = /%2f|%5c|%c0%af|%c1%9c/i;
+
+// Shell-shortcut / executable extension family — refused under strict,
+// audited under balanced/permissive.
+var SHELL_EXEC_EXTS = Object.freeze([
+  ".lnk", ".url", ".desktop", ".scr", ".bat", ".cmd", ".com", ".pif",
+  ".vbs", ".vbe", ".js", ".jse", ".wsf", ".wsh", ".ps1", ".psm1",
+  ".app", ".deb", ".rpm", ".msi", ".dmg", ".pkg", ".bin", ".sh",
+  ".exe", ".dll", ".so", ".dylib", ".jar", ".class",
+  ".reg", ".cpl", ".inf", ".hta", ".chm", ".scf",
+]);
+
+var HEX_RADIX = 16;                                                 // allow:raw-byte-literal — base-16 radix, not byte size
+
+// Visual-confusable letter ranges that homoglyph against ASCII —
+// Cyrillic / Greek / fullwidth Latin. Only flagged when mixed with
+// ASCII letters in the same filename.
+var HOMOGLYPH_RANGES = [[0x0400, 0x04FF], [0x0370, 0x03FF], [0xFF21, 0xFF5A]];
+var HOMOGLYPH_RE = new RegExp("[" + codepointClass.charClass(HOMOGLYPH_RANGES) + "]"); // allow:dynamic-regex — codepoints from HOMOGLYPH_RANGES literal table
+
+// ---- Profile presets ----
+
+var PROFILES = Object.freeze({
+  "strict": {
+    bidiPolicy:           "reject",
+    controlPolicy:        "reject",
+    nullBytePolicy:       "reject",
+    zeroWidthPolicy:      "reject",
+    homoglyphPolicy:      "reject",
+    traversalPolicy:      "reject",
+    reservedCharPolicy:   "reject",
+    reservedNamePolicy:   "reject",
+    adsPolicy:            "reject",
+    leadingTrailingPolicy: "reject",
+    shellExecExtPolicy:   "reject",
+    pathSeparatorsPolicy: "reject",         // forbid path components, leaf-name only
+    unicodeNormalization: "NFC",
+    requireAscii:         true,
+    extensionAllowlist:   null,             // null = any single extension
+    requireSingleDot:     true,             // ".tar.gz" not allowed
+    maxBytes:             64,               // allow:raw-byte-literal — leaf-name byte cap, not byte size
+    maxComponents:        1,                // allow:raw-byte-literal — single leaf only, not bytes
+  },
+  "balanced": {
+    bidiPolicy:           "reject",
+    controlPolicy:        "reject",
+    nullBytePolicy:       "reject",
+    zeroWidthPolicy:      "strip",
+    homoglyphPolicy:      "audit",
+    traversalPolicy:      "reject",
+    reservedCharPolicy:   "reject",
+    reservedNamePolicy:   "reject",
+    adsPolicy:            "reject",
+    leadingTrailingPolicy: "strip",
+    shellExecExtPolicy:   "audit",
+    pathSeparatorsPolicy: "reject",
+    unicodeNormalization: "NFC",
+    requireAscii:         false,
+    extensionAllowlist:   null,
+    requireSingleDot:     false,            // ".tar.gz" allowed
+    maxBytes:             255,              // allow:raw-byte-literal — POSIX max-component, not byte size
+    maxComponents:        1,                // allow:raw-byte-literal — single leaf only, not bytes
+  },
+  "permissive": {
+    bidiPolicy:           "reject",
+    controlPolicy:        "strip",
+    nullBytePolicy:       "reject",
+    zeroWidthPolicy:      "strip",
+    homoglyphPolicy:      "audit",
+    traversalPolicy:      "reject",
+    reservedCharPolicy:   "strip",
+    reservedNamePolicy:   "audit",          // operator may want to accept on non-Windows targets
+    adsPolicy:            "reject",
+    leadingTrailingPolicy: "strip",
+    shellExecExtPolicy:   "audit",
+    pathSeparatorsPolicy: "audit",          // operator opts in to multi-component paths
+    unicodeNormalization: "NFC",
+    requireAscii:         false,
+    extensionAllowlist:   null,
+    requireSingleDot:     false,
+    maxBytes:             255,              // allow:raw-byte-literal — POSIX max-component, not byte size
+    maxComponents:        16,               // allow:raw-byte-literal — multi-component path cap, not bytes
+  },
+});
+
+var DEFAULTS = Object.freeze(Object.assign({}, PROFILES["strict"], {
+  mode:          "enforce",
+  maxRuntimeMs:  C.TIME.seconds(5),
+}));
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  "hipaa": {
+    bidiPolicy: "reject", controlPolicy: "reject", nullBytePolicy: "reject",
+    zeroWidthPolicy: "reject", homoglyphPolicy: "reject",
+    traversalPolicy: "reject", reservedCharPolicy: "reject",
+    reservedNamePolicy: "reject", adsPolicy: "reject",
+    leadingTrailingPolicy: "reject", shellExecExtPolicy: "reject",
+    pathSeparatorsPolicy: "reject",
+    requireAscii: true,
+    forensicSnippetBytes: C.BYTES.bytes(256),
+  },
+  "pci-dss": {
+    bidiPolicy: "reject", controlPolicy: "reject", nullBytePolicy: "reject",
+    zeroWidthPolicy: "reject", homoglyphPolicy: "reject",
+    traversalPolicy: "reject", reservedCharPolicy: "reject",
+    reservedNamePolicy: "reject", adsPolicy: "reject",
+    leadingTrailingPolicy: "reject", shellExecExtPolicy: "reject",
+    pathSeparatorsPolicy: "reject",
+    requireAscii: true,
+    forensicSnippetBytes: C.BYTES.bytes(256),
+  },
+  "gdpr": {
+    bidiPolicy: "strip", controlPolicy: "strip", nullBytePolicy: "reject",
+    zeroWidthPolicy: "strip",
+    traversalPolicy: "reject", reservedCharPolicy: "reject",
+    leadingTrailingPolicy: "strip",
+    forensicSnippetBytes: C.BYTES.bytes(128),
+  },
+  "soc2": {
+    bidiPolicy: "reject", controlPolicy: "reject", nullBytePolicy: "reject",
+    zeroWidthPolicy: "reject", traversalPolicy: "reject",
+    reservedCharPolicy: "reject", reservedNamePolicy: "reject",
+    adsPolicy: "reject", shellExecExtPolicy: "reject",
+    pathSeparatorsPolicy: "reject",
+    forensicSnippetBytes: C.BYTES.bytes(512),
+  },
+});
+
+// ---- Helpers ----
+
+function _resolveOpts(opts) {
+  return gateContract.resolveProfileAndPosture(opts, {
+    profiles:           PROFILES,
+    compliancePostures: COMPLIANCE_POSTURES,
+    defaults:           DEFAULTS,
+    errorClass:         GuardFilenameError,
+    errCodePrefix:      "filename",
+  });
+}
+
+function _normalizeNFC(s) {
+  try { return s.normalize ? s.normalize("NFC") : s; }
+  catch (_e) { return s; }
+}
+
+function _isWinReserved(name) {
+  // Reserved-name check applies to the base (without extension) AND to
+  // the entire leaf — both `CON` and `CON.txt` collide with the device.
+  var upper = name.toUpperCase();
+  for (var i = 0; i < WIN_RESERVED_NAMES.length; i += 1) {
+    var r = WIN_RESERVED_NAMES[i];
+    if (upper === r) return true;
+    if (upper.indexOf(r + ".") === 0) return true;
+  }
+  return false;
+}
+
+function _hasOverlongUtf8(buf) {
+  // Buffer-level scan for non-shortest UTF-8 sequences — `0xC0 0xXX`
+  // and `0xC1 0xXX` are always invalid (would encode ASCII via 2 bytes
+  // instead of 1), and `0xE0 0x80-9F` / `0xF0 0x80-8F` are 3/4-byte
+  // overlongs. Reject the whole class.
+  if (!Buffer.isBuffer(buf)) return false;
+  for (var i = 0; i < buf.length - 1; i += 1) {
+    var b0 = buf[i];
+    if (b0 === 0xC0 || b0 === 0xC1) return true;
+    if (b0 === 0xE0 && buf[i + 1] >= 0x80 && buf[i + 1] <= 0x9F) return true;
+    if (b0 === 0xF0 && buf[i + 1] >= 0x80 && buf[i + 1] <= 0x8F) return true;
+  }
+  return false;
+}
+
+function _splitExt(name) {
+  var idx = name.lastIndexOf(".");
+  if (idx <= 0) return { base: name, ext: "" };
+  return { base: name.slice(0, idx), ext: name.slice(idx) };
+}
+
+function _stripLeadingTrailing(s) {
+  return s.replace(/^[\s.]+|[\s.]+$/g, "");
+}
+
+// ---- Detection pass ----
+
+function _detectIssues(input, opts) {
+  var issues = [];
+
+  // Buffer-level checks BEFORE utf8 conversion (overlong encoding
+  // would be invisible after toString).
+  if (Buffer.isBuffer(input)) {
+    if (_hasOverlongUtf8(input)) {
+      issues.push({
+        kind: "overlong-utf8", severity: "critical",
+        ruleId: "filename.overlong-utf8",
+        snippet: "non-shortest-form UTF-8 sequence in filename bytes (RFC 3629 §3 prohibits)",
+      });
+    }
+  }
+
+  var name = typeof input === "string"
+    ? input
+    : (Buffer.isBuffer(input) ? input.toString("utf8") : "");
+
+  if (name.length === 0) {
+    issues.push({
+      kind: "empty", severity: "critical", ruleId: "filename.empty",
+      snippet: "filename is empty",
+    });
+    return issues;
+  }
+
+  // 1. Bidi / null / control / zero-width via shared codepoint class.
+  issues.push.apply(issues, codepointClass.detectCharThreats(name, opts, "filename"));
+  if (opts.zeroWidthPolicy !== "allow" && opts.zeroWidthPolicy !== "strip") {
+    var zwMatch = name.match(codepointClass.ZERO_WIDTH_RE);
+    if (zwMatch) {
+      issues.push({
+        kind: "zero-width", severity: "high", ruleId: "filename.zero-width",
+        location: zwMatch.index,
+        snippet: "zero-width / invisible-formatting char U+" +
+                 zwMatch[0].charCodeAt(0).toString(HEX_RADIX),
+      });
+    }
+  }
+
+  // 2. Path traversal — raw + percent-encoded forms. `name` is bounded
+  // by the maxBytes check at the end of this function (issues are
+  // reported all-at-once; an oversized name still gets traversal-shape
+  // detection so operators see the full failure surface).
+  if (opts.traversalPolicy !== "allow") {
+    if (PATH_TRAVERSAL_RE.test(name) || /^\.\.$/.test(name) || name === "..") {  // allow:regex-no-length-cap — operator-supplied filename, length checked separately
+      issues.push({
+        kind: "path-traversal", severity: "critical",
+        ruleId: "filename.traversal",
+        snippet: ".. component (CWE-22 / CWE-23)",
+      });
+    }
+    if (PERCENT_ENCODED_TRAVERSAL_RE.test(name)) {                              // allow:regex-no-length-cap — operator-supplied filename, length checked separately
+      issues.push({
+        kind: "path-traversal-encoded", severity: "critical",
+        ruleId: "filename.traversal-encoded",
+        snippet: "percent-encoded path-traversal sequence detected",
+      });
+    }
+    if (URL_ENCODED_SLASH_RE.test(name)) {                                      // allow:regex-no-length-cap — operator-supplied filename, length checked separately
+      issues.push({
+        kind: "url-encoded-separator", severity: "high",
+        ruleId: "filename.url-encoded-separator",
+        snippet: "percent-encoded path separator",
+      });
+    }
+  }
+
+  // 3. Path separators in leaf — pathSeparatorsPolicy controls.
+  if (opts.pathSeparatorsPolicy !== "allow" && opts.pathSeparatorsPolicy !== "audit") {
+    if (name.indexOf("/") !== -1 || name.indexOf("\\") !== -1) {
+      issues.push({
+        kind: "path-separator-in-leaf", severity: "high",
+        ruleId: "filename.path-separator",
+        snippet: "filename leaf contains a path separator (/ or \\)",
+      });
+    }
+  }
+
+  // 4. UNC paths — `\\server\share\...` or `//server/share/...`
+  if (/^\\\\|^\/\//.test(name)) {
+    issues.push({
+      kind: "unc-path", severity: "critical",
+      ruleId: "filename.unc",
+      snippet: "UNC network path (\\\\server\\share)",
+    });
+  }
+
+  // 5. Reserved characters — < > : " | ? * (slashes handled separately).
+  if (opts.reservedCharPolicy !== "allow") {
+    var resMatch = name.match(/[<>:"|?*]/);
+    if (resMatch) {
+      issues.push({
+        kind: "reserved-char", severity: "high",
+        ruleId: "filename.reserved-char",
+        location: resMatch.index,
+        snippet: "reserved character " + JSON.stringify(resMatch[0]) +
+                 " (Windows file system)",
+      });
+    }
+  }
+
+  // 6. NTFS alternate data streams — `name:stream`.
+  if (opts.adsPolicy !== "allow") {
+    if (/:[^:\\/]+$/.test(name) && name.charAt(0) !== "/") {
+      // Only flag when there's a `:` followed by stream-name characters
+      // and we're NOT at the start (relative path indicator).
+      issues.push({
+        kind: "ntfs-ads", severity: "critical",
+        ruleId: "filename.ntfs-ads",
+        snippet: "NTFS alternate data stream syntax (name:stream)",
+      });
+    }
+  }
+
+  // 7. Windows reserved device names.
+  if (opts.reservedNamePolicy !== "allow") {
+    if (_isWinReserved(name)) {
+      issues.push({
+        kind: "reserved-name", severity: "critical",
+        ruleId: "filename.reserved-name",
+        snippet: "filename collides with Windows reserved device name",
+      });
+    }
+  }
+
+  // 8. Leading / trailing whitespace + trailing dots — Windows strips them.
+  if (opts.leadingTrailingPolicy !== "allow") {
+    if (/^\s|\s$|\.$/.test(name)) {
+      issues.push({
+        kind: "leading-trailing-strip", severity: "high",
+        ruleId: "filename.leading-trailing",
+        snippet: "leading/trailing whitespace or trailing dot (Windows silently strips)",
+      });
+    }
+  }
+
+  // 9. Single-dot leaf-names.
+  if (name === "." || name === "..") {
+    issues.push({
+      kind: "dot-leaf", severity: "critical", ruleId: "filename.dot-leaf",
+      snippet: "filename is " + JSON.stringify(name),
+    });
+  }
+
+  // 10. Homoglyph-with-ASCII mix.
+  if (opts.homoglyphPolicy !== "allow" && /[A-Za-z]/.test(name)) {
+    var hMatch = name.match(HOMOGLYPH_RE);
+    if (hMatch) {
+      issues.push({
+        kind: "homoglyph", severity: opts.homoglyphPolicy === "reject" ? "critical" : "warn",
+        ruleId: "filename.homoglyph",
+        location: hMatch.index,
+        snippet: "homoglyph U+" + hMatch[0].charCodeAt(0).toString(HEX_RADIX) +
+                 " mixed with ASCII letters in filename",
+      });
+    }
+  }
+
+  // 11. ASCII-only requirement.
+  if (opts.requireAscii) {
+    var nonAscii = name.match(/[^\x20-\x7E]/);
+    if (nonAscii) {
+      issues.push({
+        kind: "non-ascii", severity: "high",
+        ruleId: "filename.non-ascii",
+        location: nonAscii.index,
+        snippet: "non-ASCII character (profile requires ASCII-only)",
+      });
+    }
+  }
+
+  // 12. Length cap.
+  var byteLen = Buffer.byteLength(name, "utf8");
+  if (byteLen > opts.maxBytes) {
+    issues.push({
+      kind: "too-long", severity: "high", ruleId: "filename.length",
+      snippet: "filename " + byteLen + " bytes exceeds maxBytes " + opts.maxBytes,
+    });
+  }
+
+  // 13. Multi-dot when requireSingleDot.
+  if (opts.requireSingleDot) {
+    var dotCount = (name.match(/\./g) || []).length;
+    if (dotCount > 1) {
+      issues.push({
+        kind: "multiple-dots", severity: "high", ruleId: "filename.multiple-dots",
+        snippet: "filename has " + dotCount + " dots (profile requires single)",
+      });
+    }
+  }
+
+  // 14. Extension allowlist.
+  if (Array.isArray(opts.extensionAllowlist) && opts.extensionAllowlist.length > 0) {
+    var split = _splitExt(name);
+    var ext = split.ext.toLowerCase();
+    var allowed = opts.extensionAllowlist.map(function (e) { return e.toLowerCase(); });
+    if (!ext || allowed.indexOf(ext) === -1) {
+      issues.push({
+        kind: "ext-not-allowlisted", severity: "critical",
+        ruleId: "filename.ext-allowlist",
+        snippet: "extension " + JSON.stringify(ext || "") +
+                 " not in allowlist " + JSON.stringify(allowed),
+      });
+    }
+  }
+
+  // 15. Shell-shortcut / executable extensions.
+  if (opts.shellExecExtPolicy !== "allow") {
+    var splitX = _splitExt(name);
+    var extX = splitX.ext.toLowerCase();
+    if (extX && SHELL_EXEC_EXTS.indexOf(extX) !== -1) {
+      issues.push({
+        kind: "shell-exec-ext",
+        severity: opts.shellExecExtPolicy === "reject" ? "critical" : "warn",
+        ruleId: "filename.shell-exec-ext",
+        snippet: "shell-shortcut / executable extension " + JSON.stringify(extX),
+      });
+    }
+    // Double-extension: name has two dots and inner is a "harmless"
+    // disguise extension while outer is an executable.
+    var dotIndices = [];
+    for (var di = 0; di < name.length; di += 1) {
+      if (name.charAt(di) === ".") dotIndices.push(di);
+    }
+    if (dotIndices.length >= 2) {
+      var lastExt = name.slice(dotIndices[dotIndices.length - 1]).toLowerCase();
+      if (SHELL_EXEC_EXTS.indexOf(lastExt) !== -1) {
+        issues.push({
+          kind: "double-extension", severity: "critical",
+          ruleId: "filename.double-extension",
+          snippet: "double-extension with executable last segment " + JSON.stringify(lastExt),
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+// ---- Sanitize pass ----
+
+function _sanitize(input, opts) {
+  var name = typeof input === "string"
+    ? input
+    : (Buffer.isBuffer(input) ? input.toString("utf8") : "");
+  if (name.length === 0) {
+    throw _err("filename.empty", "sanitize requires non-empty filename");
+  }
+  if (Buffer.isBuffer(input) && _hasOverlongUtf8(input)) {
+    throw _err("filename.overlong-utf8", "filename has overlong UTF-8 sequence — cannot sanitize");
+  }
+
+  // Codepoint-class reject + strip via shared helpers.
+  codepointClass.assertNoCharThreats(name, opts, _err, "filename");
+  name = codepointClass.applyCharStripPolicies(name, opts);
+
+  // Unicode normalize before further checks.
+  if (opts.unicodeNormalization === "NFC") name = _normalizeNFC(name);
+
+  // Reject path traversal even in sanitize — there's no safe sanitization.
+  if (opts.traversalPolicy === "reject") {
+    // allow:regex-no-length-cap — operator-supplied filename; sanitize caller threw on length above
+    if (PATH_TRAVERSAL_RE.test(name) || PERCENT_ENCODED_TRAVERSAL_RE.test(name) ||
+        name === "." || name === "..") {
+      throw _err("filename.traversal", "filename contains path-traversal sequence");
+    }
+  }
+  if (/^\\\\|^\/\//.test(name)) {
+    throw _err("filename.unc", "UNC path syntax");
+  }
+
+  // Strip leading/trailing whitespace and trailing dots if policy says so.
+  if (opts.leadingTrailingPolicy === "strip") {
+    name = _stripLeadingTrailing(name);
+  } else if (opts.leadingTrailingPolicy === "reject" &&
+             /^\s|\s$|\.$/.test(name)) {
+    throw _err("filename.leading-trailing",
+      "filename has leading/trailing whitespace or trailing dot");
+  }
+
+  // Strip reserved chars when policy says strip.
+  if (opts.reservedCharPolicy === "strip") {
+    name = name.replace(RESERVED_CHARS_RE, "_");                            // allow:dynamic-regex — RESERVED_CHARS_RE is a compile-time literal
+    name = name.replace(/[<>:"|?*]/g, "_");
+  } else if (opts.reservedCharPolicy === "reject") {
+    if (/[<>:"|?*]/.test(name)) {
+      throw _err("filename.reserved-char", "filename contains reserved character");
+    }
+    if (opts.pathSeparatorsPolicy === "reject" &&
+        (name.indexOf("/") !== -1 || name.indexOf("\\") !== -1)) {
+      throw _err("filename.path-separator", "filename leaf contains path separator");
+    }
+  }
+
+  // Reserved-name check — append underscore prefix to disambiguate.
+  if (opts.reservedNamePolicy !== "allow" && _isWinReserved(name)) {
+    if (opts.reservedNamePolicy === "reject") {
+      throw _err("filename.reserved-name",
+        "filename collides with Windows reserved device name");
+    }
+    name = "_" + name;
+  }
+
+  // ADS detection.
+  if (opts.adsPolicy === "reject" && /:[^:\\/]+$/.test(name)) {
+    throw _err("filename.ntfs-ads", "filename contains NTFS alternate data stream syntax");
+  }
+
+  // Length cap.
+  if (Buffer.byteLength(name, "utf8") > opts.maxBytes) {
+    throw _err("filename.length", "filename exceeds maxBytes " + opts.maxBytes);
+  }
+
+  if (name.length === 0) {
+    throw _err("filename.empty", "sanitize produced empty filename");
+  }
+  return name;
+}
+
+// ---- Public surface ----
+
+/**
+ * @primitive  b.guardFilename.validate
+ * @signature  b.guardFilename.validate(input, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardFilename.sanitize, b.guardFilename.gate
+ *
+ * Inspect a filename (string or Buffer) and return
+ * `{ ok, issues, summary }`. Each issue carries
+ * `{ kind, severity, ruleId, location, snippet }` with severity in
+ * `"warn"|"high"|"critical"`. Detected: path-traversal raw and
+ * percent-encoded, null-byte truncation, NTFS ADS, UNC path,
+ * overlong UTF-8, Windows reserved-name, reserved character,
+ * leading/trailing whitespace + trailing dot, BIDI / control /
+ * zero-width / homoglyph, non-ASCII (when `requireAscii`), length
+ * cap, multi-dot violation, extension allowlist miss, double-
+ * extension with executable last segment, shell-shortcut extension.
+ * Pure inspection — never throws.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   bidiPolicy:           "reject"|"strip"|"allow",
+ *   controlPolicy:        "reject"|"strip"|"allow",
+ *   nullBytePolicy:       "reject",                       // always reject
+ *   zeroWidthPolicy:      "reject"|"strip"|"allow",
+ *   homoglyphPolicy:      "reject"|"audit"|"allow",
+ *   traversalPolicy:      "reject",                       // always reject
+ *   reservedCharPolicy:   "reject"|"strip"|"allow",
+ *   reservedNamePolicy:   "reject"|"audit"|"allow",
+ *   adsPolicy:            "reject",                       // always reject
+ *   leadingTrailingPolicy: "reject"|"strip"|"allow",
+ *   shellExecExtPolicy:   "reject"|"audit"|"allow",
+ *   pathSeparatorsPolicy: "reject"|"audit"|"allow",
+ *   unicodeNormalization: "NFC"|null,
+ *   requireAscii:         boolean,
+ *   extensionAllowlist:   string[]|null,
+ *   requireSingleDot:     boolean,
+ *   maxBytes:             number,    // leaf-name byte cap
+ *   maxComponents:        number,    // path-component count
+ *
+ * @example
+ *   var rv = b.guardFilename.validate("../etc/passwd", { profile: "strict" });
+ *   rv.ok;                                             // → false
+ *   rv.issues.some(function (i) { return i.kind === "path-traversal"; });   // → true
+ *
+ *   var ok = b.guardFilename.validate("report-2026-Q1.txt", { profile: "strict" });
+ *   ok.ok;                                             // → true
+ */
+function validate(input, opts) {
+  opts = _resolveOpts(opts);
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["maxBytes", "maxComponents"],
+    "guardFilename.validate", GuardFilenameError, "filename.bad-opt");
+
+  var bad = gateContract.badInputResultIfNotStringOrBuffer(input);
+  if (bad) return bad;
+  return gateContract.aggregateIssues(_detectIssues(input, opts));
+}
+
+function _sanitizeStripMode(input, opts) {
+  // mode: "strip" — operator-friendly Content-Disposition path. C0 control
+  // chars (CR / LF / etc., excluding NUL — null-byte truncation is never
+  // sanitizable) and bidi-override codepoints are replaced with "_". The
+  // security floor still applies: path traversal, null-byte, NTFS ADS,
+  // UNC, and overlong UTF-8 throw at every profile level.
+  if (Buffer.isBuffer(input) && _hasOverlongUtf8(input)) {
+    throw _err("filename.overlong-utf8", "filename has overlong UTF-8 sequence — cannot sanitize");
+  }
+  var name = typeof input === "string"
+    ? input
+    : (Buffer.isBuffer(input) ? input.toString("utf8") : "");
+  if (name.length === 0) {
+    throw _err("filename.empty", "sanitize requires non-empty filename");
+  }
+  if (name.indexOf("\0") !== -1) {
+    throw _err("filename.null-byte", "filename contains null byte — null-byte truncation is never sanitizable");
+  }
+  // Replace control chars + bidi codepoints with "_". Zero-width is
+  // also stripped (visible-name spoofing has no value if the bytes
+  // round-trip silently). CR (U+0D) / LF (U+0A) are NOT in the shared
+  // C0 table (they're dialect-shaped chars elsewhere) but they're the
+  // exact chars that enable Content-Disposition response splitting,
+  // which is the primary use case for strip mode — replace explicitly.
+  // allow:dynamic-regex — replace-character class composed at construction
+  name = name.replace(/[\r\n\t\v\f]/g, "_");
+  name = name.replace(codepointClass.C0_CTRL_RE_G, "_");
+  name = name.replace(codepointClass.BIDI_RE_G, "_");
+  name = name.replace(codepointClass.ZW_RE_G, "_");
+  if (opts.unicodeNormalization === "NFC") name = _normalizeNFC(name);
+
+  // Security floor — never sanitizable.
+  // allow:regex-no-length-cap — operator-supplied filename; length validated below
+  if (PATH_TRAVERSAL_RE.test(name) || PERCENT_ENCODED_TRAVERSAL_RE.test(name) ||
+      name === "." || name === "..") {
+    throw _err("filename.traversal", "filename contains path-traversal sequence");
+  }
+  if (/^\\\\|^\/\//.test(name)) {
+    throw _err("filename.unc", "UNC path syntax");
+  }
+  if (/:[^:\\/]+$/.test(name) && name.charAt(0) !== "/") {
+    throw _err("filename.ntfs-ads", "filename contains NTFS alternate data stream syntax");
+  }
+  if (Buffer.byteLength(name, "utf8") > opts.maxBytes) {
+    throw _err("filename.length", "filename exceeds maxBytes " + opts.maxBytes);
+  }
+  if (name.length === 0) {
+    throw _err("filename.empty", "sanitize produced empty filename");
+  }
+  return name;
+}
+
+/**
+ * @primitive  b.guardFilename.sanitize
+ * @signature  b.guardFilename.sanitize(input, opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.guardFilename.validate, b.guardFilename.gate
+ *
+ * Best-effort cleanup of a filename. Two modes: `"enforce"` (default;
+ * applies the profile's strip/reject policies and throws on
+ * unsanitizable refusals) and `"strip"` (operator-friendly
+ * Content-Disposition path — replaces control / bidi / zero-width
+ * codepoints with `_` and applies a security floor).
+ *
+ * The security floor ALWAYS throws regardless of mode/profile:
+ * path-traversal raw and percent-encoded, null-byte, NTFS alternate
+ * data streams, UNC paths, overlong UTF-8 sequences, and post-strip
+ * length-cap violation. These classes are unrepairable — silently
+ * fixing them would mask the attack signal an audit log needs.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   mode:       "enforce"|"strip",
+ *   audit:      { safeEmit: function },     // optional sink for strip mode
+ *   unicodeNormalization: "NFC"|null,
+ *   maxBytes:   number,
+ *
+ * @example
+ *   var safe = b.guardFilename.sanitize("My File.txt", { profile: "balanced" });
+ *   safe;                                              // → "My File.txt"
+ *
+ *   // Path traversal ALWAYS throws — never sanitizable.
+ *   try {
+ *     b.guardFilename.sanitize("../etc/passwd", { profile: "permissive" });
+ *   } catch (e) {
+ *     e.code;                                          // → "filename.traversal"
+ *   }
+ */
+function sanitize(input, opts) {
+  var rawMode = opts && opts.mode;
+  opts = _resolveOpts(opts);
+  if (typeof input !== "string" && !Buffer.isBuffer(input)) {
+    throw _err("filename.bad-input", "sanitize requires string or Buffer input");
+  }
+  if (rawMode === "strip") {
+    var stripped = _sanitizeStripMode(input, opts);
+    if (opts.audit && typeof opts.audit.safeEmit === "function") {
+      try {
+        opts.audit.safeEmit({
+          action:   "guardfilename.sanitize.stripped",
+          outcome:  "success",
+          metadata: {
+            originalLength:  Buffer.byteLength(
+              typeof input === "string" ? input : input.toString("utf8"), "utf8"),
+            sanitizedLength: Buffer.byteLength(stripped, "utf8"),
+          },
+        });
+      } catch (_e) { /* drop-silent — audit sinks must never crash the producer */ }
+    }
+    return stripped;
+  }
+  return _sanitize(input, opts);
+}
+
+/**
+ * @primitive  b.guardFilename.gate
+ * @signature  b.guardFilename.gate(opts?)
+ * @since      0.7.5
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardFilename.validate, b.guardFilename.sanitize, b.fileUpload.create
+ *
+ * Build a `b.gateContract` gate that consumes `ctx.filename` (or
+ * `ctx.name`). Action chain: `serve` (no filename or clean) →
+ * `audit-only` (warn-only issues) → `sanitize` (critical/high but
+ * every reject-policy off — strip-eligible classes only) → `refuse`
+ * (any reject-policy active or sanitize fails). Path-traversal /
+ * null-byte / NTFS-ADS / UNC / overlong-UTF-8 always cause `refuse`
+ * — there is no `sanitize` action for those classes.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,    // gate identity for audit / observability
+ *
+ * @example
+ *   var fnGate = b.guardFilename.gate({ profile: "strict" });
+ *   var verdict = await fnGate.check({ filename: "../etc/passwd" });
+ *   verdict.action;                                    // → "refuse"
+ *
+ *   var ok = await fnGate.check({ filename: "report.txt" });
+ *   ok.action;                                         // → "serve"
+ */
+function gate(opts) {
+  opts = _resolveOpts(opts);
+  return gateContract.buildGuardGate(
+    opts.name || "guardFilename:" + (opts.profile || "default"),
+    opts,
+    async function (ctx) {
+      // Filename-shape ctx — operator passes filename via ctx.filename.
+      var name = ctx && (ctx.filename || ctx.name || "");
+      if (!name) return { ok: true, action: "serve" };
+      var rv = validate(name, opts);
+      if (rv.issues.length === 0) return { ok: true, action: "serve" };
+      var hasCritical = rv.issues.some(function (i) {
+        return i.severity === "critical" || i.severity === "high";
+      });
+      if (!hasCritical) return { ok: true, action: "audit-only", issues: rv.issues };
+
+      // Sanitize-eligibility — every reject-policy must be off.
+      var canSanitize = opts.bidiPolicy !== "reject" &&
+                        opts.controlPolicy !== "reject" &&
+                        opts.nullBytePolicy !== "reject" &&
+                        opts.traversalPolicy !== "reject" &&
+                        opts.reservedCharPolicy !== "reject" &&
+                        opts.reservedNamePolicy !== "reject" &&
+                        opts.adsPolicy !== "reject" &&
+                        opts.pathSeparatorsPolicy !== "reject" &&
+                        opts.leadingTrailingPolicy !== "reject";
+      if (canSanitize) {
+        try {
+          var clean = sanitize(name, opts);
+          return {
+            ok: true, action: "sanitize",
+            sanitizedFilename: clean,
+            issues: rv.issues,
+          };
+        } catch (_e) { /* fall through */ }
+      }
+      return { ok: false, action: "refuse", issues: rv.issues };
+    });
+}
+
+/**
+ * @primitive  b.guardFilename.buildProfile
+ * @signature  b.guardFilename.buildProfile(opts)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.guardFilename.gate, b.guardFilename.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.guardFilename.buildProfile({
+ *     extends: "balanced",
+ *     extensionAllowlist: [".pdf", ".png", ".jpg"],
+ *   });
+ *   custom.extensionAllowlist.length;                  // → 3
+ *   custom.traversalPolicy;                            // → "reject"
+ */
+var buildProfile = gateContract.makeProfileBuilder(PROFILES);
+
+/**
+ * @primitive  b.guardFilename.compliancePosture
+ * @signature  b.guardFilename.compliancePosture(name)
+ * @since      0.7.5
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardFilename.gate, b.guardFilename.buildProfile
+ *
+ * Look up a compliance-posture overlay by name (`"hipaa"` /
+ * `"pci-dss"` / `"gdpr"` / `"soc2"`). Returns the posture object —
+ * the caller may mutate freely. Throws
+ * `GuardFilenameError("filename.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardFilename.compliancePosture("hipaa");
+ *   posture.requireAscii;                              // → true
+ *   posture.shellExecExtPolicy;                        // → "reject"
+ */
+function compliancePosture(name) {
+  return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES, _err, "filename");
+}
+
+var _filenameRulePacks = gateContract.makeRulePackLoader(GuardFilenameError, "filename");
+/**
+ * @primitive  b.guardFilename.loadRulePack
+ * @signature  b.guardFilename.loadRulePack(pack)
+ * @since      0.7.5
+ * @status     stable
+ * @related    b.guardFilename.gate
+ *
+ * Register an operator-supplied rule pack with the guard-filename
+ * 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 `GuardFilenameError("filename.bad-opt")` when
+ * `pack` is missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardFilename.loadRulePack({
+ *     id: "tenant-uploads-policy",
+ *     rules: [
+ *       { id: "tenant-prefix", severity: "high",
+ *         detect: function (n) { return n.indexOf("tenant_") !== 0; },
+ *         reason: "tenant policy: filenames must be tenant_-prefixed" },
+ *     ],
+ *   });
+ *   pack.id;                                           // → "tenant-uploads-policy"
+ */
+var loadRulePack = _filenameRulePacks.load;
+
+module.exports = {
+  // ---- guard-* family identity ----
+  // Filename is a different axis from content-bytes (operators
+  // typically apply both: guardFilename on the upload's name, plus
+  // guardCsv / guardHtml / guardSvg / etc. on the body). guard-filename
+  // is therefore a STANDALONE primitive — it does NOT register into
+  // b.guardAll's content-type-routed dispatch (no canonical mime / ext
+  // per the registry contract). Operators wire it directly via
+  // b.fileUpload({ filenameSafety: gate }) and similar host opts.
+  NAME:                "filename",
+  KIND:                "filename",                                                // filename-string guard (consumes ctx.filename)
+  INTEGRATION_FIXTURES: Object.freeze({
+    kind:            "filename",
+    benignFilename:  "report-2026-Q1.txt",
+    // Hostile: path-traversal in filename (CWE-22 class).
+    hostileFilename: "../etc/passwd",
+  }),
+  // ---- primitive surface ----
+  validate:            validate,
+  sanitize:            sanitize,
+  gate:                gate,
+  buildProfile:        buildProfile,
+  compliancePosture:   compliancePosture,
+  loadRulePack:        loadRulePack,
+  PROFILES:            PROFILES,
+  DEFAULTS:            DEFAULTS,
+  COMPLIANCE_POSTURES: COMPLIANCE_POSTURES,
+  WIN_RESERVED_NAMES:  WIN_RESERVED_NAMES,
+  SHELL_EXEC_EXTS:     SHELL_EXEC_EXTS,
+  GuardFilenameError:  GuardFilenameError,
+};