@blamejs/core 0.4.9 → 0.4.10

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.9** (2026-04-30) — Origin-Agent-Cluster + DNS-Prefetch-Control headers; b.auth.lockout primitive
 - **0.4.8** (2026-04-30) — wiki SEO surface: per-page OG / Twitter / JSON-LD + sitemap.xml + robots.txt
 - **0.4.7** (2026-04-30) — audit-fix the welcome page's "what's in the box" table
 - **0.4.6** (2026-04-30) — wiki gets the brand-flare on every page + substantive content additions

package/lib/middleware/body-parser.js

@@ -15,6 +15,8 @@
  *   multipart/form-data                    → req.body = { field: value }
  *                                            req.files = [{ field, filename,
  *                                            mimeType, path, size, hash }]
+ *                                            req.filesRejected = [{ field,
+ *                                            filename, mimeType, code, message }]
  *
  * Multipart parses incrementally — file parts stream to a tmp dir
  * rather than buffering in memory. Per-file + total-request size caps
@@ -42,6 +44,33 @@
  *       fieldCount:   100,
  *       fieldSize:    1024 * 1024,
  *       mimeAllowlist: ["image/jpeg", "image/png", "application/pdf"], // null = any
+ *
+ *       // Per-part predicate. Runs after sanitization + MIME checks but
+ *       // BEFORE the tmp file opens. Rejected parts are SKIPPED — the body
+ *       // bytes are consumed (we still must scan past them to find the
+ *       // next boundary) but never written to disk; the part metadata
+ *       // lands in req.filesRejected. Surviving files appear in req.files
+ *       // as usual. Sync only — async filtering goes in the route handler.
+ *       fileFilter: function (part) {
+ *         // part = { field, filename, mimeType, partHeaders }
+ *         // return true / undefined → accept
+ *         // return false → reject silently (entry in req.filesRejected)
+ *         // return { reject: true, code, message } → reject with custom info
+ *         return part.field === "avatar" && part.mimeType.startsWith("image/");
+ *       },
+ *
+ *       // Per-field overrides. maxBytes overrides global fileSize for file
+ *       // parts and fieldSize for text parts. mimeTypes overrides the
+ *       // global mimeAllowlist for the named field; other fields still
+ *       // use the global list.
+ *       fields: {
+ *         avatar:   { maxBytes: 2 * 1024 * 1024, mimeTypes: ["image/jpeg", "image/png"] },
+ *         document: { maxBytes: 25 * 1024 * 1024 },
+ *       },
+ *
+ *       // When wired, fileFilter rejections emit body-parser.multipart.file_rejected
+ *       // on the audit chain with the field, filename, mime, and reason.
+ *       audit: b.audit,
  *     },
  *     // Stash the raw bytes for webhook-signature paths that need to
  *     // verify the wire bytes rather than the parsed shape.
@@ -128,6 +157,9 @@ var DEFAULTS = Object.freeze({
     fieldCount:    100,
     fieldSize:     C.BYTES.mib(1),
     mimeAllowlist: null,
+    fileFilter:    null,             // fn({ field, filename, mimeType, partHeaders }) → bool | { reject, code, message }
+    fields:        null,             // per-field overrides: { name: { maxBytes?, mimeTypes? } }
+    audit:         null,             // when wired, file-rejection emits an audit event
     contentTypes:  ["multipart/form-data"],
   },
 });
@@ -446,6 +478,7 @@ async function _parseMultipart(req, opts, ctParams) {
 
   var fields = {};
   var files = [];
+  var filesRejected = [];
   var totalRead = 0;
   var fileCount = 0;
   var fieldCount = 0;
@@ -455,6 +488,9 @@ async function _parseMultipart(req, opts, ctParams) {
   var fieldLimit = opts.fieldCount;
   var fieldSize = opts.fieldSize;
   var mimeAllowlist = Array.isArray(opts.mimeAllowlist) ? opts.mimeAllowlist : null;
+  var fileFilter   = typeof opts.fileFilter === "function" ? opts.fileFilter : null;
+  var perField     = (opts.fields && typeof opts.fields === "object") ? opts.fields : null;
+  var auditInst    = (opts.audit && typeof opts.audit.safeEmit === "function") ? opts.audit : null;
 
   var state = MP_INITIAL;
   var pending = Buffer.alloc(0);
@@ -467,6 +503,10 @@ async function _parseMultipart(req, opts, ctParams) {
   var currentSize = 0;
   var currentHash = null;
   var currentBuf = null; // for fields (in-memory accumulator)
+  var currentDiscarded = false; // true when fileFilter rejected the part — body bytes are
+                                // still consumed (we have to read past them to find the next
+                                // boundary) but never written to disk.
+  var currentEffectiveLimit = 0; // per-field-or-global cap; recomputed at part start.
 
   function _resetCurrent() {
     currentHeaders = null;
@@ -478,6 +518,28 @@ async function _parseMultipart(req, opts, ctParams) {
     currentSize = 0;
     currentHash = null;
     currentBuf = null;
+    currentDiscarded = false;
+    currentEffectiveLimit = 0;
+  }
+
+  function _emitRejection(field, filename, mimeType, code, message) {
+    filesRejected.push({
+      field:    field,
+      filename: filename,
+      mimeType: mimeType,
+      code:     code,
+      message:  message || null,
+    });
+    if (auditInst) {
+      try {
+        auditInst.safeEmit({
+          action:   "body-parser.multipart.file_rejected",
+          outcome:  "denied",
+          resource: { kind: "multipart.file", id: field + (filename ? ":" + filename : "") },
+          metadata: { field: field, filename: filename, mimeType: mimeType, code: code, message: message || null },
+        });
+      } catch (_e) { /* audit best-effort */ }
+    }
   }
 
   function _cleanup() {
@@ -527,7 +589,7 @@ async function _parseMultipart(req, opts, ctParams) {
             if (pending.length < 2) return;
             if (pending[0] === 0x2d && pending[1] === 0x2d) { // "--"
               state = MP_DONE;
-              done(null, { fields: fields, files: files });
+              done(null, { fields: fields, files: files, filesRejected: filesRejected });
               return;
             }
             if (pending[0] === 0x0d && pending[1] === 0x0a) { // "\r\n"
@@ -581,7 +643,20 @@ async function _parseMultipart(req, opts, ctParams) {
                 return;
               }
               currentMime = currentHeaders["content-type"] || "application/octet-stream";
-              if (mimeAllowlist && mimeAllowlist.indexOf(currentMime) === -1) {
+              // Per-field MIME allowlist takes precedence over the global one
+              // for this field; global applies to fields without an entry.
+              var fieldRule = perField ? perField[currentField] : null;
+              var perFieldMime = (fieldRule && Array.isArray(fieldRule.mimeTypes))
+                                    ? fieldRule.mimeTypes : null;
+              if (perFieldMime) {
+                if (perFieldMime.indexOf(currentMime) === -1) {
+                  done(new BodyParserError("body-parser/multipart-mime-not-allowed",
+                    "multipart file '" + currentField + "' MIME '" + currentMime +
+                    "' is not on the per-field allowlist",
+                    true, 415));
+                  return;
+                }
+              } else if (mimeAllowlist && mimeAllowlist.indexOf(currentMime) === -1) {
                 done(new BodyParserError("body-parser/multipart-mime-not-allowed",
                   "multipart file MIME '" + currentMime + "' is not on the allowlist",
                   true, 415));
@@ -594,6 +669,43 @@ async function _parseMultipart(req, opts, ctParams) {
                   true, 413));
                 return;
               }
+              // Per-field cap overrides global fileSize for this field.
+              currentEffectiveLimit = (fieldRule && typeof fieldRule.maxBytes === "number")
+                                          ? fieldRule.maxBytes : fileSize;
+
+              // fileFilter runs AFTER sanitize + MIME checks but BEFORE the
+              // tmp file opens. Synchronous so the parser can decide between
+              // disk-write and discard-bytes without buffering the part.
+              if (fileFilter) {
+                var filterVerdict;
+                try {
+                  filterVerdict = fileFilter({
+                    field:       currentField,
+                    filename:    currentFilename,
+                    mimeType:    currentMime,
+                    partHeaders: currentHeaders,
+                  });
+                } catch (e) {
+                  done(new BodyParserError("body-parser/multipart-file-filter-throw",
+                    "fileFilter threw: " + ((e && e.message) || String(e)),
+                    true, 500));
+                  return;
+                }
+                if (filterVerdict === false ||
+                    (filterVerdict && typeof filterVerdict === "object" && filterVerdict.reject)) {
+                  var rejCode    = (filterVerdict && filterVerdict.code)    || "fileFilter";
+                  var rejMessage = (filterVerdict && filterVerdict.message) || null;
+                  _emitRejection(currentField, currentFilename, currentMime, rejCode, rejMessage);
+                  // Read past the body bytes (we still must find the next
+                  // boundary) but never open a tmp file or push to req.files.
+                  currentDiscarded = true;
+                  fileCount--; // doesn't count toward the limit since it didn't land
+                  currentSize = 0;
+                  state = MP_BODY;
+                  continue;
+                }
+              }
+
               // Generate the tmp path — never derived from the
               // operator-supplied filename.
               var unique = nodeCrypto.randomBytes(16).toString("hex");
@@ -616,6 +728,10 @@ async function _parseMultipart(req, opts, ctParams) {
                   true, 413));
                 return;
               }
+              // Per-field cap overrides global fieldSize for text parts too.
+              var textFieldRule = perField ? perField[currentField] : null;
+              currentEffectiveLimit = (textFieldRule && typeof textFieldRule.maxBytes === "number")
+                                          ? textFieldRule.maxBytes : fieldSize;
               currentBuf = [];
               currentSize = 0;
             }
@@ -640,12 +756,27 @@ async function _parseMultipart(req, opts, ctParams) {
             }
             if (emitLen > 0) {
               var bodyChunk = pending.slice(0, emitLen);
-              if (currentFd !== null) {
+              if (currentDiscarded) {
+                // fileFilter rejected this part — read past the bytes to find
+                // the next boundary but never write to disk. totalSize still
+                // applies as a per-request DoS guard.
+                totalRead += bodyChunk.length;
+                if (totalRead > totalSize) {
+                  done(new BodyParserError("body-parser/multipart-total-too-large",
+                    "multipart total request size exceeds totalSize (" + totalSize + ")",
+                    true, 413));
+                  return;
+                }
+              } else if (currentFd !== null) {
                 // File part — write to disk.
                 currentSize += bodyChunk.length;
-                if (currentSize > fileSize) {
+                if (currentSize > currentEffectiveLimit) {
+                  var perFieldFile = (perField && perField[currentField] &&
+                                      typeof perField[currentField].maxBytes === "number");
                   done(new BodyParserError("body-parser/multipart-file-too-large",
-                    "multipart file '" + currentField + "' exceeds fileSize (" + fileSize + ")",
+                    "multipart file '" + currentField + "' exceeds " +
+                    (perFieldFile ? "per-field maxBytes" : "fileSize") +
+                    " (" + currentEffectiveLimit + ")",
                     true, 413));
                   return;
                 }
@@ -669,11 +800,15 @@ async function _parseMultipart(req, opts, ctParams) {
                 }
                 currentHash.update(bodyChunk);
               } else {
-                // Field part — buffer in memory up to fieldSize.
+                // Field part — buffer in memory up to per-field-or-global cap.
                 currentSize += bodyChunk.length;
-                if (currentSize > fieldSize) {
+                if (currentSize > currentEffectiveLimit) {
+                  var perFieldText = (perField && perField[currentField] &&
+                                      typeof perField[currentField].maxBytes === "number");
                   done(new BodyParserError("body-parser/multipart-field-too-large",
-                    "multipart field '" + currentField + "' exceeds fieldSize (" + fieldSize + ")",
+                    "multipart field '" + currentField + "' exceeds " +
+                    (perFieldText ? "per-field maxBytes" : "fieldSize") +
+                    " (" + currentEffectiveLimit + ")",
                     true, 413));
                   return;
                 }
@@ -692,7 +827,10 @@ async function _parseMultipart(req, opts, ctParams) {
             // Consume the boundary delimiter; transition to AFTER_BD.
             pending = pending.slice(boundaryDelimBuf.length);
             // Finalize the current part.
-            if (currentFd !== null) {
+            if (currentDiscarded) {
+              // fileFilter rejected — already recorded in filesRejected; no
+              // tmp file was opened, nothing to clean up here.
+            } else if (currentFd !== null) {
               try { fs.closeSync(currentFd); } catch (_e) {}
               currentFd = null;
               files.push({
@@ -723,6 +861,8 @@ async function _parseMultipart(req, opts, ctParams) {
             currentSize = 0;
             currentHash = null;
             currentBuf = null;
+            currentDiscarded = false;
+            currentEffectiveLimit = 0;
             state = MP_AFTER_BD;
             continue;
           }
@@ -804,6 +944,7 @@ function create(opts) {
         var mpResult = await _parseMultipart(req, multipartOpts, ct.params);
         req.body = mpResult.fields;
         req.files = mpResult.files;
+        req.filesRejected = mpResult.filesRejected || [];
         // Cleanup tmp files when the response finishes / closes / errors,
         // regardless of whether the handler returned cleanly. Operators
         // who want to KEEP a file move it elsewhere inside the handler.

package/package.json

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