@blamejs/core 0.7.4 → 0.7.18

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 {