@blamejs/core 0.7.4 → 0.7.19

package/lib/auth/password.js

@@ -583,12 +583,46 @@ function needsRehash(stored, opts) {
   }
 }
 
+// OWASP 2026 Argon2id minimum floor — operator audit visibility.
+// Any deploy MUST satisfy m >= 19 MiB, t >= 2, p >= 1. params() exposes
+// the active defaults so an operator audit (or compliance scan) can
+// verify the floor without parsing PHC strings out of the database.
+//
+// Argon2 expresses memoryCost in KiB. C.BYTES.kib(19) returns 19456,
+// which argon2 reads as 19456 KiB = 19 MiB — the same shape as the
+// active DEFAULT_PARAMS.memoryCost (C.BYTES.kib(64) = 65536 KiB = 64
+// MiB). timeCost + parallelism are unitless argon2 parameters.
+var OWASP_FLOOR_2026 = Object.freeze({
+  memoryCostKib: C.BYTES.kib(19),
+  timeCost:      2,
+  parallelism:   1,
+});
+
+function params() {
+  // Active framework defaults plus the OWASP 2026 floor for comparison.
+  var active = {
+    memoryCostKib: DEFAULT_PARAMS.memoryCost,
+    timeCost:      DEFAULT_PARAMS.timeCost,
+    parallelism:   DEFAULT_PARAMS.parallelism,
+  };
+  return {
+    algorithm:     "argon2id",
+    active:        active,
+    owaspFloor:    OWASP_FLOOR_2026,
+    meetsFloor:    active.memoryCostKib >= OWASP_FLOOR_2026.memoryCostKib &&
+                   active.timeCost      >= OWASP_FLOOR_2026.timeCost &&
+                   active.parallelism   >= OWASP_FLOOR_2026.parallelism,
+  };
+}
+
 module.exports = {
   hash:             hash,
   verify:           verify,
   needsRehash:      needsRehash,
   policy:           policy,
+  params:           params,
   DEFAULT_PARAMS:   DEFAULT_PARAMS,
   DEFAULT_POLICY:   DEFAULT_POLICY,
   POLICY_PROFILES:  POLICY_PROFILES,
+  OWASP_FLOOR_2026: OWASP_FLOOR_2026,
 };

package/lib/codepoint-class.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * codepoint-class — shared codepoint-table threat catalog and regex
+ * compiler for the guard-* family.
+ *
+ * Threat detectors that need to match Unicode bidi overrides, C0
+ * control characters, zero-width / invisible chars, etc. compose
+ * regex character classes from numeric codepoint range tables here
+ * instead of embedding the attack characters directly in their
+ * source files. Centralizing the tables means:
+ *
+ *   - Source files in lib/guard-* stay pure ASCII (zero
+ *     irregular-whitespace lint findings, no eslint-disable comments
+ *     for this category).
+ *   - Adding / removing a codepoint from the catalog is a single
+ *     edit; every guard picks up the change.
+ *   - The detector composes the way an attacker would compose the
+ *     payload (programmatic codepoint emission, not literal typing).
+ *
+ * Surface:
+ *
+ *   hex4(cp)              -> "\\uXXXX" escape for a single codepoint
+ *   charClass(ranges)     -> regex character class body for a range
+ *                            table (e.g. [0x200E, [0x202A,0x202E]])
+ *   fromCp(cp)            -> String.fromCharCode shorthand
+ *   ranges()              -> { BIDI_RANGES, C0_CTRL_RANGES,
+ *                              ZERO_WIDTH_RANGES }
+ *   compiled()            -> { BIDI_RE, BIDI_RE_G, C0_CTRL_RE,
+ *                              C0_CTRL_RE_G, ZERO_WIDTH_RE, ZW_RE_G,
+ *                              NULL_RE_G, NULL_BYTE, BOM_CHAR }
+ *
+ * The compiled() exports are RegExp instances built from the
+ * codepoint tables at module load. Consumers grab them once at boot.
+ *
+ * Codepoint tables:
+ *
+ *   BIDI_RANGES — Unicode bidi-override family (CVE-2021-42574
+ *     Trojan Source). LRM U+200E / RLM U+200F / ALM U+061C / LRE
+ *     U+202A / RLE U+202B / PDF U+202C / LRO U+202D / RLO U+202E /
+ *     LRI U+2066 / RLI U+2067 / FSI U+2068 / PDI U+2069.
+ *
+ *   C0_CTRL_RANGES — C0 control characters minus tab (U+09) / lf
+ *     (U+0A) / cr (U+0D) — those are dialect-shaped chars that
+ *     parsers handle separately. Everything else (U+00, U+01-U+08,
+ *     U+0B-U+0C, U+0E-U+1F) flagged as control-byte injection.
+ *
+ *   ZERO_WIDTH_RANGES — invisible-formatting / zero-width chars
+ *     attackers use to hide payloads:
+ *     SHY  U+00AD  ZWSP U+200B  ZWNJ U+200C  ZWJ  U+200D
+ *     WJ   U+2060  BOM  U+FEFF
+ */
+
+var HEX_RADIX = 16;                                                 // allow:raw-byte-literal — base-16 radix, not byte size
+
+function hex4(cp) {
+  var s = cp.toString(HEX_RADIX).toUpperCase();
+  while (s.length < 4) s = "0" + s;
+  return "\\u" + s;
+}
+function charClass(rangeList) {
+  return rangeList.map(function (r) {
+    return Array.isArray(r) ? hex4(r[0]) + "-" + hex4(r[1]) : hex4(r);
+  }).join("");
+}
+function fromCp(cp) { return String.fromCharCode(cp); }
+
+var BIDI_RANGES       = [0x200E, 0x200F, 0x061C, [0x202A, 0x202E], [0x2066, 0x2069]];
+var C0_CTRL_RANGES    = [[0x0000, 0x0008], 0x000B, 0x000C, [0x000E, 0x001F]];
+var ZERO_WIDTH_RANGES = [0x00AD, [0x200B, 0x200D], 0x2060, 0xFEFF];
+
+// allow:dynamic-regex — codepoints from BIDI_RANGES literal table
+var BIDI_RE       = new RegExp("[" + charClass(BIDI_RANGES) + "]");
+// allow:dynamic-regex — codepoints from BIDI_RANGES literal table
+var BIDI_RE_G     = new RegExp("[" + charClass(BIDI_RANGES) + "]", "g");
+// allow:dynamic-regex — codepoints from C0_CTRL_RANGES literal table
+var C0_CTRL_RE    = new RegExp("[" + charClass(C0_CTRL_RANGES) + "]");
+// allow:dynamic-regex — codepoints from C0_CTRL_RANGES literal table
+var C0_CTRL_RE_G  = new RegExp("[" + charClass(C0_CTRL_RANGES) + "]", "g");
+// allow:dynamic-regex — codepoints from ZERO_WIDTH_RANGES literal table
+var ZERO_WIDTH_RE = new RegExp("[" + charClass(ZERO_WIDTH_RANGES) + "]");
+// allow:dynamic-regex — codepoints from ZERO_WIDTH_RANGES literal table
+var ZW_RE_G       = new RegExp("[" + charClass(ZERO_WIDTH_RANGES) + "]", "g");
+// allow:dynamic-regex — single literal codepoint U+0000
+var NULL_RE_G     = new RegExp(hex4(0x0000), "g");
+
+var NULL_BYTE = fromCp(0x0000);
+var BOM_CHAR  = fromCp(0xFEFF);
+
+// detectCharThreats — returns an array of issue objects for character-
+// class threats (bidi / null / C0-control) per the opts policy. Emits
+// at most one issue per class. Used by guard-* primitives' detection
+// pass instead of repeating the per-class match-and-push block.
+//
+// Issue shape mirrors guard-* convention:
+//   { kind, severity, ruleId, location, snippet }
+//
+//   issues.push.apply(issues,
+//     codepointClass.detectCharThreats(text, opts, "html"));
+function detectCharThreats(text, opts, codePrefix) {
+  var issues = [];
+  if (typeof text !== "string") return issues;
+  if (opts && opts.bidiPolicy !== "allow") {
+    var bidiMatch = text.match(BIDI_RE);
+    if (bidiMatch) {
+      issues.push({
+        kind: "bidi-override", severity: "critical",
+        ruleId: codePrefix + ".bidi",
+        location: bidiMatch.index,
+        snippet: "Unicode bidi override (CVE-2021-42574 Trojan Source)",
+      });
+    }
+  }
+  if (opts && opts.nullBytePolicy !== "allow") {
+    var nullIdx = text.indexOf(NULL_BYTE);
+    if (nullIdx >= 0) {
+      issues.push({
+        kind: "null-byte", severity: "critical",
+        ruleId: codePrefix + ".null-byte",
+        location: nullIdx,
+        snippet: "null byte at byte " + nullIdx,
+      });
+    }
+  }
+  if (opts && opts.controlPolicy !== "allow") {
+    var ctrlMatch = text.match(C0_CTRL_RE);
+    if (ctrlMatch) {
+      issues.push({
+        kind: "control-char", severity: "high",
+        ruleId: codePrefix + ".control",
+        location: ctrlMatch.index,
+        snippet: "C0 control char U+" + ctrlMatch[0].charCodeAt(0).toString(HEX_RADIX),
+      });
+    }
+  }
+  return issues;
+}
+
+// assertNoCharThreats — throws an instance of errorFactory(code, msg)
+// when the text contains a class that's set to "reject" in opts.
+// Opt-name vocabulary: bidiPolicy / nullBytePolicy / controlPolicy
+// (the standard guard-* family naming; older guard-csv uses different
+// names and keeps its inline checks).
+function assertNoCharThreats(text, opts, errorFactory, codePrefix) {
+  if (typeof text !== "string") return;
+  if (opts && opts.bidiPolicy === "reject" && BIDI_RE.test(text)) {           // allow:regex-no-length-cap — caller bounds length before invoking
+    throw errorFactory(codePrefix + ".bidi",
+      "input contains Unicode bidi override (CVE-2021-42574)");
+  }
+  if (opts && opts.nullBytePolicy === "reject" && text.indexOf(NULL_BYTE) !== -1) {
+    throw errorFactory(codePrefix + ".null-byte",
+      "input contains null byte");
+  }
+  if (opts && opts.controlPolicy === "reject" && C0_CTRL_RE.test(text)) {     // allow:regex-no-length-cap — caller bounds length before invoking
+    throw errorFactory(codePrefix + ".control",
+      "input contains C0 control character");
+  }
+}
+
+// applyCharStripPolicies — given a text and a policy object, apply
+// strip-mode replacements for each character-class threat. Reads:
+//   opts.bidiPolicy === "strip"      -> strip BIDI overrides
+//   opts.controlPolicy === "strip"   -> strip C0 controls
+//   opts.nullBytePolicy === "strip"  -> strip null bytes
+//   opts.zeroWidthPolicy === "strip" -> strip zero-widths
+// Returns the cleaned string. Used by every guard's sanitize path so
+// each one doesn't reinvent the same sequence of replace() calls.
+function applyCharStripPolicies(text, opts) {
+  if (typeof text !== "string") return text;
+  var out = text;
+  if (opts && opts.bidiPolicy === "strip")      out = out.replace(BIDI_RE_G, "");
+  if (opts && opts.controlPolicy === "strip")   out = out.replace(C0_CTRL_RE_G, "");
+  if (opts && opts.nullBytePolicy === "strip")  out = out.replace(NULL_RE_G, "");
+  if (opts && opts.zeroWidthPolicy === "strip") out = out.replace(ZW_RE_G, "");
+  return out;
+}
+
+module.exports = {
+  hex4:              hex4,
+  charClass:         charClass,
+  fromCp:            fromCp,
+  BIDI_RANGES:       BIDI_RANGES,
+  C0_CTRL_RANGES:    C0_CTRL_RANGES,
+  ZERO_WIDTH_RANGES: ZERO_WIDTH_RANGES,
+  BIDI_RE:           BIDI_RE,
+  BIDI_RE_G:         BIDI_RE_G,
+  C0_CTRL_RE:        C0_CTRL_RE,
+  C0_CTRL_RE_G:      C0_CTRL_RE_G,
+  ZERO_WIDTH_RE:     ZERO_WIDTH_RE,
+  ZW_RE_G:           ZW_RE_G,
+  NULL_RE_G:         NULL_RE_G,
+  NULL_BYTE:         NULL_BYTE,
+  BOM_CHAR:          BOM_CHAR,
+  applyCharStripPolicies: applyCharStripPolicies,
+  assertNoCharThreats:    assertNoCharThreats,
+  detectCharThreats:      detectCharThreats,
+};

package/lib/csv.js

@@ -10,7 +10,7 @@
  *     // returns array of arrays
  *
  *   var out = b.csv.stringify(rows);
- *     // RFC 4180 + Excel-formula-injection prevention by default
+ *     // RFC 4180 quoting + anti-DoS bounds. NO threat-catalog handling.
  *
  * Defaults:
  *   parse:
@@ -24,20 +24,22 @@
  *     onBadRow:      "throw"           "skip" tolerates short/long rows
  *
  *   stringify:
- *     header:                  true (or array of explicit columns)
- *     delimiter:               ","
- *     quote:                   '"'
- *     eol:                     "\r\n"  RFC 4180; "\n" via opt
- *     alwaysQuote:             false   only quote when needed
- *     preventFormulaInjection: true    prefix '=' / '+' / '-' / '@' / TAB / CR
- *                                       cells with "'" so Excel doesn't
- *                                       execute them when the CSV is opened
- *     formulaPrefixChars:      ["=","+","-","@","\t","\r"]
+ *     header:        true (or array of explicit columns)
+ *     delimiter:     ","
+ *     quote:         '"'
+ *     eol:           "\r\n"            RFC 4180; "\n" via opt
+ *     alwaysQuote:   false             only quote when needed
  *
- * SECURITY: stringify defends against CSV-injection (Excel/Sheets execute
- * cells starting with "=" / "+" / "-" / "@" / TAB / CR as formulas).
- * Operator-controlled cells stay safe; user-supplied cells get the leading
- * single-quote so the formula engine sees a literal string.
+ * SCOPE: this module is for trusted-source-only emission. It performs RFC
+ * 4180 quote/delimiter escaping but does NOT defend against the broader
+ * CSV-injection threat catalog (Excel/Sheets formula triggers, Unicode
+ * bidi overrides, dangerous-function denylist, homoglyphs, control-byte
+ * injection, BOM mid-stream, dialect ambiguity, CSV-bombs). Any path
+ * that emits or accepts user-supplied cells MUST route through
+ * `b.guardCsv` — its `serialize` / `validate` / `sanitize` / `gate`
+ * surface handles every documented threat with a single profile choice
+ * (strict / balanced / permissive / email-attachment) or compliance
+ * posture (hipaa / pci-dss / gdpr / soc2-cc7).
  *
  * Throws CsvError (FrameworkError, permanent) on shape violations.
  */
@@ -59,14 +61,12 @@ var DEFAULTS_PARSE = {
 };
 
 var DEFAULTS_STRINGIFY = {
-  header:                  true,
-  delimiter:               ",",
-  quote:                   "\"",
-  eol:                     "\r\n",
-  alwaysQuote:             false,
-  preventFormulaInjection: true,
-  formulaPrefixChars:      ["=", "+", "-", "@", "\t", "\r"],
-  columns:                 null,
+  header:       true,
+  delimiter:    ",",
+  quote:        "\"",
+  eol:          "\r\n",
+  alwaysQuote:  false,
+  columns:      null,
 };
 
 function _validateDelim(name, value) {
@@ -88,12 +88,9 @@ function parse(input, opts) {
   // Infinity / NaN bypass the corresponding caps and let a hostile
   // multi-megabyte CSV (or a single hostile row / single hostile field)
   // through unbounded.
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxBytes,
-    "csv.parse: maxBytes", CsvError, "csv/bad-opt");
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxRows,
-    "csv.parse: maxRows", CsvError, "csv/bad-opt");
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxFieldBytes,
-    "csv.parse: maxFieldBytes", CsvError, "csv/bad-opt");
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["maxBytes", "maxRows", "maxFieldBytes"],
+    "csv.parse", CsvError, "csv/bad-opt");
 
   var s;
   if (typeof input === "string") s = input;
@@ -239,16 +236,8 @@ function stringify(rows, opts) {
       "stringify: rows must be arrays or plain objects");
   }
 
-  var prefixSet = Object.create(null);
-  for (var pi = 0; pi < opts.formulaPrefixChars.length; pi++) {
-    prefixSet[opts.formulaPrefixChars[pi]] = true;
-  }
-
   function escapeCell(value) {
     var str = value == null ? "" : String(value);
-    if (opts.preventFormulaInjection && str.length > 0 && prefixSet[str.charAt(0)]) {
-      str = "'" + str;
-    }
     var needsQuote = opts.alwaysQuote ||
       str.indexOf(opts.delimiter) !== -1 ||
       str.indexOf(opts.quote) !== -1 ||

package/lib/db-declare-view.js

@@ -158,11 +158,10 @@ function _validateOpts(opts) {
   }
 
   var hashColumns = {};
+  validateOpts.optionalPlainObject(opts.hashColumns, "hashColumns",
+    DeclareViewError, "declare-view/bad-type",
+    "must be an object { aliasOrHashCol: srcCol }");
   if (opts.hashColumns !== undefined && opts.hashColumns !== null) {
-    if (typeof opts.hashColumns !== "object" || Array.isArray(opts.hashColumns)) {
-      throw _err("declare-view/bad-type",
-        "hashColumns must be an object { aliasOrHashCol: srcCol }");
-    }
     for (var hc in opts.hashColumns) {
       if (!Object.prototype.hasOwnProperty.call(opts.hashColumns, hc)) continue;
       _validateIdent("hashColumns key '" + hc + "'", hc);

package/lib/file-upload.js

@@ -155,6 +155,8 @@ var stream = require("node:stream");
 var atomicFile = require("./atomic-file");
 var C = require("./constants");
 var crypto = require("./crypto");
+var gateContract = require("./gate-contract");
+var lazyRequire = require("./lazy-require");
 var numericBounds = require("./numeric-bounds");
 var requestHelpers = require("./request-helpers");
 var safeBuffer = require("./safe-buffer");
@@ -162,6 +164,12 @@ var safeJson = require("./safe-json");
 var validateOpts = require("./validate-opts");
 var { FileUploadError } = require("./framework-error");
 
+// guard-* family is wired on by default; lazy-loaded to avoid eager
+// import cycles (guards consume framework primitives that may not be
+// resolved at file-upload load-time).
+var guardAll      = lazyRequire(function () { return require("./guard-all"); });
+var guardFilename = lazyRequire(function () { return require("./guard-filename"); });
+
 var _err = FileUploadError.factory;
 
 var DEFAULTS = Object.freeze({
@@ -213,16 +221,10 @@ function _validateCreateOpts(opts) {
   }
   validateOpts.optionalFunction(opts.onFinalize, "fileUpload.create: onFinalize", FileUploadError);
   validateOpts.optionalFunction(opts.onChunk, "fileUpload.create: onChunk", FileUploadError);
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxFileBytes,
-    "fileUpload.create: maxFileBytes", FileUploadError, "BAD_OPT");
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxChunkBytes,
-    "fileUpload.create: maxChunkBytes", FileUploadError, "BAD_OPT");
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxStreamReassemblyBytes,
-    "fileUpload.create: maxStreamReassemblyBytes", FileUploadError, "BAD_OPT");
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxStagingBytes,
-    "fileUpload.create: maxStagingBytes", FileUploadError, "BAD_OPT");
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxActiveUploadsPerActor,
-    "fileUpload.create: maxActiveUploadsPerActor", FileUploadError, "BAD_OPT");
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["maxFileBytes", "maxChunkBytes", "maxStreamReassemblyBytes",
+     "maxStagingBytes", "maxActiveUploadsPerActor"],
+    "fileUpload.create", FileUploadError, "BAD_OPT");
   numericBounds.requireNonNegativeFiniteIntIfPresent(opts.incompleteTtlMs,
     "fileUpload.create: incompleteTtlMs", FileUploadError, "BAD_OPT");
   numericBounds.requireNonNegativeFiniteIntIfPresent(opts.maxIdleMs,
@@ -247,6 +249,37 @@ function _validateCreateOpts(opts) {
   validateOpts.optionalObjectWithMethod(opts.permissions, "check",
     "fileUpload.create: permissions", FileUploadError, "BAD_OPT",
     "must be a b.permissions instance (check fn)");
+  // contentSafety — extension-keyed gate map for per-extension content
+  // validation. Default behaviour: when undefined, the framework wires
+  // b.guardAll.byExtension({ profile: "strict" }) automatically so every
+  // shipped guard is ON by default. Explicit opt-out: contentSafety:
+  // null (audited at create() time so a security review can reconstruct
+  // which deploys disabled the default-on protection).
+  // Example: contentSafety: { ".csv": b.guardCsv.gate({ profile: "strict" }) }
+  if (opts.contentSafety !== undefined && opts.contentSafety !== null) {
+    validateOpts.optionalPlainObject(opts.contentSafety,
+      "fileUpload.create: contentSafety", FileUploadError, "BAD_OPT",
+      "must be a plain { ext: gate } object, null to opt out, or " +
+      "undefined for the default-on b.guardAll wiring");
+    var safetyKeys = Object.keys(opts.contentSafety);
+    for (var sk = 0; sk < safetyKeys.length; sk++) {
+      var ext = safetyKeys[sk];
+      var g = opts.contentSafety[ext];
+      if (!g || typeof g.check !== "function") {
+        throw _err("BAD_OPT",
+          "fileUpload.create: contentSafety[" + JSON.stringify(ext) +
+          "] must be a gate (b.guardCsv.gate / b.guardHtml.gate / etc.)");
+      }
+    }
+  }
+  // filenameSafety — single gate for filename validation. Default: on.
+  // Operator opts out with filenameSafety: null (audited).
+  if (opts.filenameSafety !== undefined && opts.filenameSafety !== null) {
+    validateOpts.optionalObjectWithMethod(opts.filenameSafety, "check",
+      "fileUpload.create: filenameSafety", FileUploadError, "BAD_OPT",
+      "must be a gate (b.guardFilename.gate(...)), null to opt out, or " +
+      "undefined for the default-on wiring");
+  }
 }
 
 function create(opts) {
@@ -257,6 +290,74 @@ function create(opts) {
   var onChunk                 = opts.onChunk || null;
   var fileType                = opts.fileType || null;
   var permissions             = opts.permissions || null;
+  // ---- Default-on safety wiring ----
+  // contentSafety: undefined → wire b.guardAll.byExtension({ profile: "strict" })
+  // contentSafety: null      → explicit opt-out, audit row emitted
+  // contentSafety: { ... }   → use operator-supplied map
+  var contentSafety;
+  if (opts.contentSafety === undefined) {
+    // Strict profile is the security-correct default — every shipped
+    // guard's full threat catalog refused, including dangerous tags
+    // (script / style / iframe), event handlers, dangerous URL
+    // schemes, formula injection, DOCTYPE / SVGZ / animation-href
+    // hijack. Operators who need a broader content vocabulary opt up
+    // explicitly via contentSafety: b.guardAll.byExtension({
+    // profile: "balanced" | "permissive" }).
+    contentSafety = guardAll().byExtension({
+      profile:       "strict",
+      audit:         opts.audit,
+      observability: opts.observability,
+    });
+  } else if (opts.contentSafety === null) {
+    if (opts.audit && typeof opts.audit.safeEmit === "function") {
+      try {
+        opts.audit.safeEmit({
+          action:   "fileUpload.contentSafety.disabled",
+          actor:    {},
+          outcome:  "success",
+          metadata: {
+            reason: opts.contentSafetyDisabledReason || "operator-explicit-opt-out",
+          },
+        });
+      } catch (_e) { /* audit best-effort */ }
+    }
+    contentSafety = null;
+  } else {
+    contentSafety = opts.contentSafety;
+  }
+  // filenameSafety: undefined → b.guardFilename.gate({ profile: "strict" })
+  // filenameSafety: null      → explicit opt-out, audit row emitted
+  // filenameSafety: gate      → use operator-supplied gate
+  var filenameSafety;
+  if (opts.filenameSafety === undefined) {
+    // Strict filename profile: ASCII-only, single-dot, 64-byte leaf
+    // cap, refuses every shell-exec extension (.exe / .bat / .vbs /
+    // .ps1 / .lnk / .scr / .dll / .so / .dmg / .msi / etc.). Operators
+    // accepting Unicode filenames or executable-extension artifacts
+    // opt up explicitly via filenameSafety: b.guardFilename.gate({
+    // profile: "balanced" | "permissive" }).
+    filenameSafety = guardFilename().gate({
+      profile:       "strict",
+      audit:         opts.audit,
+      observability: opts.observability,
+    });
+  } else if (opts.filenameSafety === null) {
+    if (opts.audit && typeof opts.audit.safeEmit === "function") {
+      try {
+        opts.audit.safeEmit({
+          action:   "fileUpload.filenameSafety.disabled",
+          actor:    {},
+          outcome:  "success",
+          metadata: {
+            reason: opts.filenameSafetyDisabledReason || "operator-explicit-opt-out",
+          },
+        });
+      } catch (_e) { /* audit best-effort */ }
+    }
+    filenameSafety = null;
+  } else {
+    filenameSafety = opts.filenameSafety;
+  }
   var maxFileBytes            = cfg.maxFileBytes;
   var maxChunkBytes           = cfg.maxChunkBytes;
   var maxStreamReassemblyBytes = cfg.maxStreamReassemblyBytes;
@@ -756,6 +857,108 @@ function create(opts) {
       throw e;
     }
 
+    // Content-safety gate — operator-supplied per-extension gate
+    // (b.guardCsv.gate / b.guardHtml.gate / etc.). Routes the assembled
+    // body through the gate's check() before handing to onFinalize. The
+    // decision is honored:
+    //   - serve     → continue with the original buffer
+    //   - sanitize  → continue with decision.sanitized (operator's
+    //                  onFinalize sees the cleaned bytes)
+    //   - refuse    → throw FileUploadError; operator route surfaces the
+    //                  rejection to the client
+    // filenameSafety — single gate that validates the filename string
+    // (path traversal / null-byte / Windows reserved names / NTFS ADS /
+    // RTLO bidi / overlong UTF-8 / shell-exec / double-extension).
+    // Runs BEFORE contentSafety because a refused filename obviates
+    // the need to validate the body.
+    var filename = (meta.metadata && meta.metadata.filename) || uploadId;
+    if (filenameSafety && typeof filenameSafety.check === "function") {
+      var fnDecision;
+      try {
+        fnDecision = await filenameSafety.check({
+          filename:  filename,
+          actor:     actor,
+          direction: "inbound",
+          metadata:  meta.metadata,
+        });
+      } catch (fnErr) {
+        _emitObs("fileUpload.filename_safety_threw", 1);
+        _emitAudit("fileUpload.finalize_failure", {
+          actor:    requestHelpers.extractActorContext(actor),
+          outcome:  "failure", reason: "filename-safety-threw",
+          metadata: { uploadId: uploadId, error: fnErr && fnErr.message },
+        });
+        throw _err("FILENAME_SAFETY_THREW",
+          "fileUpload.finalize: filenameSafety gate threw: " + (fnErr && fnErr.message));
+      }
+      if (!fnDecision.ok || fnDecision.action === "refuse") {
+        _emitObs("fileUpload.filename_safety_refused", 1);
+        _emitAudit("fileUpload.finalize_failure", {
+          actor:    requestHelpers.extractActorContext(actor),
+          outcome:  "failure", reason: "filename-safety-refused",
+          metadata: {
+            uploadId: uploadId, filename: filename,
+            issues: gateContract.summarizeIssues(fnDecision.issues),
+          },
+        });
+        throw _err("FILENAME_SAFETY_REFUSED",
+          "fileUpload.finalize: filenameSafety refused " + JSON.stringify(filename) +
+          ": " + gateContract.summarizeIssues(fnDecision.issues));
+      }
+      // sanitize: replace metadata.filename with the sanitized form so
+      // downstream code sees the cleaned name.
+      if (fnDecision.action === "sanitize" && fnDecision.sanitizedFilename) {
+        meta.metadata = Object.assign({}, meta.metadata || {},
+          { filename: fnDecision.sanitizedFilename });
+        filename = fnDecision.sanitizedFilename;
+      }
+    }
+    if (contentSafety) {
+      var safetyExt = path.extname(filename).toLowerCase();
+      var safetyGate = contentSafety[safetyExt];
+      if (safetyGate && typeof safetyGate.check === "function" && bodyBuffer) {
+        var safetyDecision;
+        try {
+          safetyDecision = await safetyGate.check({
+            bytes:    bodyBuffer,
+            filename: filename,
+            actor:    actor,
+            direction: "inbound",
+            metadata: meta.metadata,
+          });
+        } catch (gateErr) {
+          _emitObs("fileUpload.content_safety_threw", 1);
+          _emitAudit("fileUpload.finalize_failure", {
+            actor:    requestHelpers.extractActorContext(actor),
+            outcome:  "failure", reason: "content-safety-threw",
+            metadata: { uploadId: uploadId, error: gateErr && gateErr.message },
+          });
+          throw _err("CONTENT_SAFETY_THREW",
+            "fileUpload.finalize: contentSafety gate threw: " + (gateErr && gateErr.message));
+        }
+        if (!safetyDecision.ok || safetyDecision.action === "refuse") {
+          _emitObs("fileUpload.content_safety_refused", 1, { ext: safetyExt });
+          _emitAudit("fileUpload.finalize_failure", {
+            actor:    requestHelpers.extractActorContext(actor),
+            outcome:  "failure", reason: "content-safety-refused",
+            metadata: {
+              uploadId: uploadId, ext: safetyExt,
+              issues: gateContract.summarizeIssues(safetyDecision.issues),
+            },
+          });
+          throw _err("CONTENT_SAFETY_REFUSED",
+            "fileUpload.finalize: contentSafety gate refused upload (" +
+            (safetyDecision.issues || []).map(function (i) { return i.kind; }).join(", ") + ")");
+        }
+        if (safetyDecision.action === "sanitize" && safetyDecision.sanitized) {
+          // Replace the body buffer with the sanitized variant.
+          bodyBuffer = safetyDecision.sanitized;
+          // Clear the streaming alias if present — sanitized fits in memory.
+          bodyStream = null;
+        }
+      }
+    }
+
     // Hand to operator's onFinalize.
     var rv;
     try {