@blamejs/core 0.8.42 → 0.8.49

package/lib/guard-filename.js

@@ -1,88 +1,67 @@
 "use strict";
 /**
- * guard-filename — filename content-safety primitive (b.guardFilename).
+ * @module b.guardFilename
+ * @nav    Guards
+ * @title  Guard Filename
  *
- * Threat catalog grounded in current research: OWASP Path Traversal +
- * WSTG file-inclusion testing guides; CWE-22 / CWE-23 / CWE-35 / CWE-73
- * / CWE-78 / CWE-434 / CWE-36; PortSwigger File-path-traversal series
- * (null-byte bypass + extension validation); Memento-RTLO + RTL-Spiegel
- * file-name spoofing reports (CVE-2021-42574 in filename context); Kevin
- * Boone overlong UTF-8 sequence write-up.
+ * @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.
  *
- *   var rv = b.guardFilename.validate("../etc/passwd", { profile: "strict" });
- *   var safe = b.guardFilename.sanitize("My File‮.txt", { profile: "balanced" });
- *   var g = b.guardFilename.gate({ profile: "strict" });
- *
- * Threat catalog covered:
- *
- *   1. Path traversal — `..`, `../`, `..\\`, percent-encoded `%2e%2e`,
- *      double-encoded `%252e%252e`, UTF-8 overlong `0xC0 0xAE` for `.`
- *      and `0xC0 0xAF` for `/`. Refused regardless of profile.
- *
- *   2. Null-byte truncation — `file.txt\x00.exe` — string ends at null
- *      in C-shaped APIs while validation sees `.txt`. Refused.
- *
- *   3. Windows reserved device names — CON / PRN / AUX / NUL / COM1-9 /
- *      LPT1-9 / CLOCK$ — even with extensions (CON.txt is reserved).
- *      Case-insensitive match. Refused.
- *
- *   4. NTFS alternate data streams — `file.txt:hidden.exe`. Colon is
- *      the ADS separator on NTFS. Refused.
- *
- *   5. Leading/trailing whitespace + trailing dots — Windows strips
- *      them silently, so `secret.txt ` and `secret.txt.` save as
- *      `secret.txt`. Refused under strict, stripped under balanced.
- *
- *   6. Unicode bidi / RTLO — CVE-2021-42574 in filename context. The
- *      Memento-RTLO toolkit weaponizes this: `Photo01By‮gpj.SCR`
- *      displays as `Photo01ByRCS.jpg` while the OS opens `.SCR`.
- *      Refused regardless of profile.
- *
- *   7. Zero-width / invisible-formatting chars — used to hide the real
- *      extension between the visible name and what the OS sees.
- *
- *   8. Homoglyph chars — Cyrillic / Greek / fullwidth Latin mixed with
- *      ASCII letters in a single name. Operator-decided severity per
- *      profile.
+ *   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.
  *
- *   9. Path separators inside a leaf-name — `file/with/slashes` and
- *      `\\` variants. Reserved-character check.
+ *   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).
  *
- *  10. Reserved characters — Windows: `< > : " / \ | ? *` plus the C0
- *      controls and DEL. Refused under strict / balanced; permissive
- *      strips and re-checks length.
+ *   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.
  *
- *  11. UNC paths — `\\server\share\file` syntax. Refused (network-path
- *      resolution is outside the local-file scope).
+ *   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.
  *
- *  12. Length caps — Windows MAX_PATH 260, NTFS 32767, ext4 255 bytes
- *      per component. Default leaf cap 255 bytes; total-path cap 260.
+ *   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`.
  *
- *  13. Empty / dot components — `..//.//file` after normalization. The
- *      validator surfaces these as path-traversal-shape issues.
+ *   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.
  *
- *  14. Single-dot leaf — name === "." or ".." refused.
- *
- *  15. Allowlist mode — operators can pass `extensionAllowlist:
- *      [".png", ".jpg", ".pdf"]` to require a single allowed extension.
- *      The validator catches double-extension bypass: `file.jpg.exe`
- *      lands at the last dot's extension `.exe` and is refused.
- *
- *  16. Shell-shortcut extensions — `.lnk`, `.url`, `.desktop`, `.scr`,
- *      `.bat`, `.cmd`, `.com`, `.pif`, `.vbs`, `.js`, `.jse`, `.wsf`,
- *      `.wsh`, `.ps1`, `.psm1`, `.app`, `.deb`, `.rpm`, `.msi`. Refused
- *      under strict; balanced/permissive emit a warn-level audit issue.
- *
- *  17. UTF-8 overlong encoding — bytes that decode to ASCII separators
- *      via non-shortest-form encoding (Unicode standard prohibits, but
- *      legacy decoders accept them).
- *
- *  18. Anti-DoS caps — total filename byte length, total component
- *      count when the operator allows path-shape (default: leaf only).
- *
- * 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");
@@ -623,6 +602,56 @@ function _sanitize(input, opts) {
 
 // ---- 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,
@@ -634,14 +663,151 @@ function validate(input, opts) {
   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(
@@ -682,13 +848,79 @@ function gate(opts) {
     });
 }
 
+/**
+ * @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 = {