@blamejs/core 0.4.9 → 0.4.11

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.10** (2026-04-30) — bodyParser multipart: fileFilter + per-field maxBytes/mimeTypes
+- **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/cache.js

@@ -7,10 +7,13 @@
  *     backend:     "memory",
  *     ttlMs:       C.TIME.minutes(5),
  *     maxEntries:  10000,
- *     audit:       b.audit,           // optional
+ *     maxBytes:    C.BYTES.mib(100),                 // memory backend only
+ *     sizeOf:      function (v) { return v.byteLength; },  // optional override
+ *     slidingTtl:  true,                              // bump expiresAt on hit
+ *     audit:       b.audit,                           // optional
  *   });
  *
- *   await cache.set("u-42", record);
+ *   await cache.set("u-42", record, { ttlMs: C.TIME.minutes(10), tags: ["user:42", "session"] });
  *   var hit = await cache.get("u-42");
  *
  *   // Memoize / read-through:
@@ -18,15 +21,21 @@
  *     return db.users.findOne({ _id: "u-42" });
  *   });
  *
+ *   // Bulk invalidate (memory backend):
+ *   await cache.invalidateTag("user:42");          // purges every entry tagged user:42
+ *
  * Surface (returned by create):
  *
  *   get(key)                  → value | undefined
- *   set(key, value, opts?)    → void                  (opts: { ttlMs })
+ *   set(key, value, opts?)    → void                  (opts: { ttlMs, tags })
  *   del(key)                  → boolean (existed)
  *   has(key)                  → boolean (does NOT bump LRU recency)
  *   clear(opts?)              → number (purged)        (opts: { req, context })
  *   size()                    → number
+ *   bytes()                   → number (memory backend only — total stored bytes)
  *   wrap(key, fn, opts?)      → fn's return value      (opts: { ttlMs, singleFlight })
+ *   invalidateTag(tag, opts?) → number (purged)        (opts: { req, context })
+ *   getTags(key)              → string[] | null
  *   close()                   → void
  *
  * Backends:
@@ -59,14 +68,26 @@
  *     would drown at any reasonable QPS)
  *
  * The cache supports single-flight wrap (concurrent calls collapse),
- * stale-while-revalidate, LRU eviction on the memory backend, a shared
- * cluster backend, and a custom-backend escape hatch.
+ * stale-while-revalidate, LRU + bytes eviction on the memory backend,
+ * sliding TTL on hit, tag-based bulk invalidation (memory backend), a
+ * shared cluster backend, and a custom-backend escape hatch.
+ *
+ * What is NOT in the box:
  *
- * Distributed pubsub invalidation, tag-based invalidation, and
- * compression for the cluster backend are not built in — the cluster
- * backend is always-fresh-by-shared-table, memory caches go
- * stale-on-other-nodes by design, and read-through is what `wrap()`
- * is for.
+ *   - Tag invalidation on the cluster backend — invalidating tagged
+ *     entries across cluster nodes ties to a future distributed-pubsub
+ *     slice. invalidateTag against a cluster-backend cache throws
+ *     NOT_SUPPORTED today; operators wanting cluster-scope tag wipe
+ *     run their own DELETE against _blamejs_cache.
+ *   - maxBytes on the cluster backend — per-row size accounting against
+ *     a shared table would mean an aggregate query on every set. The
+ *     operator controls cluster-table size with their own pruning if
+ *     bytes pressure surfaces.
+ *   - Per-entry exact slidingTtl on the cluster backend — sliding works
+ *     on cluster but extends by the cache's defaultTtlMs (we don't
+ *     store per-row ttl). Operators with mixed-TTL writes wanting
+ *     strict per-entry sliding use the memory backend or extend at
+ *     the application layer.
  */
 
 var clusterStorage = require("./cluster-storage");
@@ -84,8 +105,10 @@ var DEFAULTS = Object.freeze({
   backend:                 "memory",
   ttlMs:                   C.TIME.minutes(5),
   maxEntries:              10000,
+  maxBytes:                Infinity,
   sweepIntervalMs:         C.TIME.minutes(1),
   staleWhileRevalidate:    false,
+  slidingTtl:              false,
   auditFailures:           true,
   auditClear:              true,
 });
@@ -118,6 +141,29 @@ function _validateMaxEntries(value) {
   }
 }
 
+function _validateMaxBytes(value) {
+  if (value === Infinity) return;
+  if (!_isFiniteNonNegative(value) || value < 1) {
+    throw _err("BAD_OPT", "cache.create: maxBytes must be a positive finite number or Infinity, got " +
+      JSON.stringify(value));
+  }
+}
+
+// Default sizeOf — best-effort byte estimate. Operators with structured
+// values (large objects, custom classes) should pass their own sizeOf
+// for accuracy.
+function _defaultSizeOf(value) {
+  if (value === null || value === undefined) return 0;
+  if (Buffer.isBuffer(value)) return value.length;
+  if (typeof value === "string") return Buffer.byteLength(value, "utf8");
+  if (typeof value === "number" || typeof value === "boolean") return 8;
+  // Fallback: round-trip through JSON. Cost is real; documented in the
+  // DEFAULTS docstring so operators with hot-path size accounting know
+  // to supply their own sizeOf.
+  try { return Buffer.byteLength(JSON.stringify(value), "utf8"); }
+  catch (_e) { return 0; }
+}
+
 function _validateBackendObject(backend) {
   var required = ["get", "set", "del", "clear", "size", "close"];
   if (typeof backend !== "object" || backend === null) {
@@ -156,6 +202,13 @@ function _validateCreateOpts(opts) {
   }
   if (opts.ttlMs !== undefined) _validateTtl("cache.create: ttlMs", opts.ttlMs);
   if (opts.maxEntries !== undefined) _validateMaxEntries(opts.maxEntries);
+  if (opts.maxBytes !== undefined) _validateMaxBytes(opts.maxBytes);
+  if (opts.sizeOf !== undefined && typeof opts.sizeOf !== "function") {
+    throw _err("BAD_OPT", "cache.create: sizeOf must be a function (value) → bytes");
+  }
+  if (opts.slidingTtl !== undefined && typeof opts.slidingTtl !== "boolean") {
+    throw _err("BAD_OPT", "cache.create: slidingTtl must be a boolean");
+  }
   if (opts.sweepIntervalMs !== undefined) {
     if (!_isFiniteNonNegative(opts.sweepIntervalMs) || opts.sweepIntervalMs < 1000) {
       throw _err("BAD_OPT", "cache.create: sweepIntervalMs must be a finite number ≥ 1000ms, got " +
@@ -199,24 +252,54 @@ function _validateKey(key, ctx) {
 // re-inserting a key on hit moves it to the most-recent position).
 
 function _memoryBackend(cfg) {
-  var entries = new Map();    // key → { value, expiresAt }
+  var entries = new Map();         // key → { value, expiresAt, ttlMs, bytes, tags }
   var maxEntries = cfg.maxEntries;
-  var clock = cfg.clock;
-  var emitObs = cfg.emitObs;
-  var namespace = cfg.namespace;
+  var maxBytes   = cfg.maxBytes;
+  var sizeOf     = cfg.sizeOf;
+  var slidingTtl = cfg.slidingTtl;
+  var clock      = cfg.clock;
+  var emitObs    = cfg.emitObs;
+  var namespace  = cfg.namespace;
   var sweepTimer = null;
+  var totalBytes = 0;
+
+  // tag → Set<key>. Bidirectional with entry.tags for fast invalidate.
+  var tagIndex = new Map();
 
   function _isExpired(entry, now) {
     return entry.expiresAt !== Infinity && entry.expiresAt <= now;
   }
 
-  function _evictOldestIfFull() {
-    if (maxEntries === Infinity) return;
-    while (entries.size > maxEntries) {
+  function _untrack(key, entry) {
+    if (!entry) return;
+    totalBytes -= entry.bytes || 0;
+    if (totalBytes < 0) totalBytes = 0;
+    if (entry.tags && entry.tags.length > 0) {
+      for (var i = 0; i < entry.tags.length; i++) {
+        var s = tagIndex.get(entry.tags[i]);
+        if (s) {
+          s.delete(key);
+          if (s.size === 0) tagIndex.delete(entry.tags[i]);
+        }
+      }
+    }
+  }
+
+  function _evictByCounts() {
+    while (maxEntries !== Infinity && entries.size > maxEntries) {
       var oldest = entries.keys().next().value;
+      var e = entries.get(oldest);
+      _untrack(oldest, e);
       entries.delete(oldest);
       emitObs("cache.eviction.size", { namespace: namespace });
     }
+    while (maxBytes !== Infinity && totalBytes > maxBytes && entries.size > 0) {
+      var oldestB = entries.keys().next().value;
+      var eb = entries.get(oldestB);
+      _untrack(oldestB, eb);
+      entries.delete(oldestB);
+      emitObs("cache.eviction.bytes", { namespace: namespace });
+    }
   }
 
   async function get(key) {
@@ -224,32 +307,63 @@ function _memoryBackend(cfg) {
     var entry = entries.get(key);
     if (!entry) return undefined;
     if (_isExpired(entry, now)) {
+      _untrack(key, entry);
       entries.delete(key);
       emitObs("cache.eviction.expired", { namespace: namespace });
       return undefined;
     }
+    // Sliding TTL: extend lifetime on each successful read by the
+    // entry's original ttlMs. Infinity stays Infinity.
+    if (slidingTtl && entry.ttlMs !== Infinity && typeof entry.ttlMs === "number") {
+      entry.expiresAt = now + entry.ttlMs;
+    }
     // LRU recency bump: re-insert moves to the most-recent slot.
     entries.delete(key);
     entries.set(key, entry);
     return entry.value;
   }
 
-  async function set(key, value, expiresAt) {
-    // Existing key replacement: delete first so re-insert lands at the
-    // most-recent position (LRU on overwrite).
-    entries.delete(key);
-    entries.set(key, { value: value, expiresAt: expiresAt });
-    _evictOldestIfFull();
+  async function set(key, value, expiresAt, meta) {
+    // Existing key replacement: untrack first to rebalance bytes + tags.
+    var prior = entries.get(key);
+    if (prior) {
+      _untrack(key, prior);
+      entries.delete(key);
+    }
+    var bytes = sizeOf(value) || 0;
+    var ttlMs = meta && typeof meta.ttlMs === "number" ? meta.ttlMs : null;
+    var tags  = (meta && Array.isArray(meta.tags)) ? meta.tags.slice() : null;
+    entries.set(key, {
+      value:     value,
+      expiresAt: expiresAt,
+      ttlMs:     ttlMs,
+      bytes:     bytes,
+      tags:      tags,
+    });
+    totalBytes += bytes;
+    if (tags && tags.length > 0) {
+      for (var i = 0; i < tags.length; i++) {
+        var s = tagIndex.get(tags[i]);
+        if (!s) { s = new Set(); tagIndex.set(tags[i], s); }
+        s.add(key);
+      }
+    }
+    _evictByCounts();
   }
 
   async function del(key) {
-    return entries.delete(key);
+    var entry = entries.get(key);
+    if (!entry) return false;
+    _untrack(key, entry);
+    entries.delete(key);
+    return true;
   }
 
   async function has(key) {
     var entry = entries.get(key);
     if (!entry) return false;
     if (_isExpired(entry, clock())) {
+      _untrack(key, entry);
       entries.delete(key);
       emitObs("cache.eviction.expired", { namespace: namespace });
       return false;
@@ -260,6 +374,8 @@ function _memoryBackend(cfg) {
   async function clear() {
     var n = entries.size;
     entries.clear();
+    tagIndex.clear();
+    totalBytes = 0;
     return n;
   }
 
@@ -273,19 +389,45 @@ function _memoryBackend(cfg) {
     return live;
   }
 
+  async function invalidateTag(tag) {
+    var keys = tagIndex.get(tag);
+    if (!keys || keys.size === 0) return 0;
+    var purged = 0;
+    var toDelete = Array.from(keys);
+    for (var i = 0; i < toDelete.length; i++) {
+      var k = toDelete[i];
+      var entry = entries.get(k);
+      if (entry) {
+        _untrack(k, entry);
+        entries.delete(k);
+        purged++;
+      }
+    }
+    return purged;
+  }
+
+  async function getTags(key) {
+    var entry = entries.get(key);
+    if (!entry) return null;
+    return entry.tags ? entry.tags.slice() : [];
+  }
+
+  async function bytes() {
+    return totalBytes;
+  }
+
   function _sweep() {
     var now = clock();
     var purged = 0;
     for (var k of Array.from(entries.keys())) {
       var e = entries.get(k);
       if (_isExpired(e, now)) {
+        _untrack(k, e);
         entries.delete(k);
         purged++;
       }
     }
     if (purged > 0) {
-      // Single observability event per sweep cycle is enough — operators
-      // see "purge happened with N evictions" via labels in dashboards.
       for (var i = 0; i < purged; i++) emitObs("cache.eviction.expired", { namespace: namespace });
     }
   }
@@ -299,20 +441,25 @@ function _memoryBackend(cfg) {
   async function close() {
     if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
     entries.clear();
+    tagIndex.clear();
+    totalBytes = 0;
   }
 
   return {
-    name:         "memory",
-    get:          get,
-    set:          set,
-    del:          del,
-    has:          has,
-    clear:        clear,
-    size:         size,
-    close:        close,
-    _startSweep:  _startSweep,
+    name:           "memory",
+    get:            get,
+    set:            set,
+    del:            del,
+    has:            has,
+    clear:          clear,
+    size:           size,
+    bytes:          bytes,
+    invalidateTag:  invalidateTag,
+    getTags:        getTags,
+    close:          close,
+    _startSweep:    _startSweep,
     // Test hook: raw entries map for state inspection
-    _entries:     entries,
+    _entries:       entries,
   };
 }
 
@@ -321,9 +468,11 @@ function _memoryBackend(cfg) {
 // value serialization. UPSERT via ON CONFLICT for atomic set.
 
 function _clusterBackend(cfg) {
-  var namespace = cfg.namespace;
-  var clock = cfg.clock;
-  var emitObs = cfg.emitObs;
+  var namespace      = cfg.namespace;
+  var clock          = cfg.clock;
+  var emitObs        = cfg.emitObs;
+  var slidingTtl     = cfg.slidingTtl;
+  var defaultTtlMs   = cfg.defaultTtlMs;
 
   // Composite cluster key. Namespace was validated to not contain ":"
   // at create time, so the split is unambiguous.
@@ -348,6 +497,18 @@ function _clusterBackend(cfg) {
       emitObs("cache.eviction.expired", { namespace: namespace });
       return undefined;
     }
+    // Sliding TTL on cluster: extend by the cache's defaultTtlMs (we don't
+    // store per-row ttl). Operators with mixed-TTL writes wanting strict
+    // per-entry sliding use the memory backend or extend at app layer.
+    // Fire-and-forget — best-effort lifetime extension.
+    if (slidingTtl && defaultTtlMs !== Infinity && typeof defaultTtlMs === "number") {
+      var newExpires = now + defaultTtlMs;
+      clusterStorage.execute(
+        "UPDATE _blamejs_cache SET expiresAt = ?, updatedAt = ? " +
+        "WHERE cacheKey = ? AND expiresAt > ?",
+        [newExpires, now, _composedKey(key), now]
+      ).catch(function () { /* best-effort */ });
+    }
     try { return JSON.parse(row.valueJson); }
     catch (_e) { return undefined; }
   }
@@ -451,7 +612,10 @@ function _customBackend(operatorBackend, cfg) {
   return {
     name:         "custom",
     get:          function (key) { return operatorBackend.get(key); },
-    set:          function (key, value, expiresAt) { return operatorBackend.set(key, value, expiresAt); },
+    set:          function (key, value, expiresAt, meta) {
+      // Older 3-arg backends remain compatible — meta is opt-in.
+      return operatorBackend.set(key, value, expiresAt, meta);
+    },
     del:          function (key) { return operatorBackend.del(key); },
     has:          function (key) {
       // Optional has() — fall back to get-and-coerce if operator didn't
@@ -461,6 +625,18 @@ function _customBackend(operatorBackend, cfg) {
     },
     clear:        function () { return operatorBackend.clear(); },
     size:         function () { return operatorBackend.size(); },
+    bytes:        function () {
+      if (typeof operatorBackend.bytes === "function") return operatorBackend.bytes();
+      return Promise.resolve(0);
+    },
+    invalidateTag: function (tag) {
+      if (typeof operatorBackend.invalidateTag === "function") return operatorBackend.invalidateTag(tag);
+      return Promise.resolve(0);
+    },
+    getTags: function (key) {
+      if (typeof operatorBackend.getTags === "function") return operatorBackend.getTags(key);
+      return Promise.resolve(null);
+    },
     close:        function () { return operatorBackend.close(); },
     _startSweep:  function () { /* operator backend manages its own sweep */ },
   };
@@ -471,8 +647,8 @@ function _customBackend(operatorBackend, cfg) {
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
-    "namespace", "backend", "ttlMs", "maxEntries",
-    "sweepIntervalMs", "staleWhileRevalidate",
+    "namespace", "backend", "ttlMs", "maxEntries", "maxBytes", "sizeOf",
+    "sweepIntervalMs", "staleWhileRevalidate", "slidingTtl",
     "auditFailures", "auditClear",
     "audit", "observability", "clock",
   ], "cache");
@@ -482,8 +658,11 @@ function create(opts) {
   var backendKind      = opts.backend || DEFAULTS.backend;
   var defaultTtlMs     = (opts.ttlMs            === undefined) ? DEFAULTS.ttlMs            : opts.ttlMs;
   var maxEntries       = (opts.maxEntries       === undefined) ? DEFAULTS.maxEntries       : opts.maxEntries;
+  var maxBytes         = (opts.maxBytes         === undefined) ? DEFAULTS.maxBytes         : opts.maxBytes;
+  var sizeOf           = (typeof opts.sizeOf === "function") ? opts.sizeOf : _defaultSizeOf;
   var sweepIntervalMs  = (opts.sweepIntervalMs  === undefined) ? DEFAULTS.sweepIntervalMs  : opts.sweepIntervalMs;
   var staleRevalidate  = (opts.staleWhileRevalidate === undefined) ? DEFAULTS.staleWhileRevalidate : opts.staleWhileRevalidate;
+  var slidingTtl       = (opts.slidingTtl       === undefined) ? DEFAULTS.slidingTtl       : opts.slidingTtl;
   var auditFailures    = (opts.auditFailures    === undefined) ? DEFAULTS.auditFailures    : opts.auditFailures;
   var auditClear       = (opts.auditClear       === undefined) ? DEFAULTS.auditClear       : opts.auditClear;
   var audit            = opts.audit || null;
@@ -528,11 +707,15 @@ function create(opts) {
 
   // Resolve backend
   var cfg = {
-    namespace:    namespace,
-    maxEntries:   maxEntries,
-    clock:        clock,
-    emitObs:      emitObs,
-    _sweepTimer:  null,
+    namespace:     namespace,
+    maxEntries:    maxEntries,
+    maxBytes:      maxBytes,
+    sizeOf:        sizeOf,
+    slidingTtl:    slidingTtl,
+    defaultTtlMs:  defaultTtlMs,
+    clock:         clock,
+    emitObs:       emitObs,
+    _sweepTimer:   null,
   };
   var backend;
   if (backendKind === "memory") {
@@ -598,7 +781,15 @@ function create(opts) {
     var ttlMs = _resolveTtl(callerOpts, "set");
     if (ttlMs === 0) return;    // 0 means "do not cache"
     var expiresAt = (ttlMs === Infinity) ? Infinity : (clock() + ttlMs);
-    try { await backend.set(key, value, expiresAt); }
+    var tags = (callerOpts && Array.isArray(callerOpts.tags)) ? callerOpts.tags : null;
+    if (tags) {
+      for (var i = 0; i < tags.length; i++) {
+        if (typeof tags[i] !== "string" || tags[i].length === 0) {
+          throw _err("BAD_OPT", "cache.set: tags must be an array of non-empty strings");
+        }
+      }
+    }
+    try { await backend.set(key, value, expiresAt, { ttlMs: ttlMs, tags: tags }); }
     catch (e) {
       emitObs("cache.backend.failed", { namespace: namespace, op: "set" });
       _backendFailedAudit("set", e);
@@ -670,6 +861,66 @@ function create(opts) {
     }
   }
 
+  async function bytes() {
+    _ensureOpen("bytes");
+    try {
+      if (typeof backend.bytes !== "function") return 0;
+      return await backend.bytes();
+    } catch (e) {
+      emitObs("cache.backend.failed", { namespace: namespace, op: "bytes" });
+      _backendFailedAudit("bytes", e);
+      throw e;
+    }
+  }
+
+  async function invalidateTag(tag, callerOpts) {
+    _ensureOpen("invalidateTag");
+    if (typeof tag !== "string" || tag.length === 0) {
+      throw _err("BAD_OPT", "cache.invalidateTag: tag must be a non-empty string");
+    }
+    if (typeof backend.invalidateTag !== "function") {
+      throw _err("NOT_SUPPORTED",
+        "cache.invalidateTag: backend '" + (backend.name || "custom") +
+        "' does not support tag invalidation. Tags are memory-backend only " +
+        "in this release; the cluster backend gains tag support alongside " +
+        "the distributed-invalidation slice.");
+    }
+    var purged;
+    try { purged = await backend.invalidateTag(tag); }
+    catch (e) {
+      emitObs("cache.backend.failed", { namespace: namespace, op: "invalidateTag" });
+      _backendFailedAudit("invalidateTag", e);
+      throw e;
+    }
+    emitObs("cache.tag.invalidated", { namespace: namespace, tag: tag });
+    if (auditClear && purged > 0) {
+      emitAudit("cache.tag.invalidated", {
+        actor:    _actor(callerOpts),
+        resource: { kind: "cache.tag", id: namespace + ":" + tag },
+        outcome:  "success",
+        metadata: { tag: tag, itemCount: purged },
+      });
+    }
+    // Drop in-flight wrap promises whose key WOULD have just been
+    // invalidated. We don't track per-key tags inflight, so a coarse
+    // drop matches clear()'s safer-than-stale posture.
+    inflight.clear();
+    swrInflight.clear();
+    return purged;
+  }
+
+  async function getTags(key) {
+    _ensureOpen("getTags");
+    _validateKey(key, "cache.getTags");
+    if (typeof backend.getTags !== "function") return null;
+    try { return await backend.getTags(key); }
+    catch (e) {
+      emitObs("cache.backend.failed", { namespace: namespace, op: "getTags" });
+      _backendFailedAudit("getTags", e);
+      throw e;
+    }
+  }
+
   function _backgroundRefresh(key, fn, ttlMs) {
     if (swrInflight.has(key)) return;     // already refreshing
     var p = (async function () {
@@ -710,7 +961,7 @@ function create(opts) {
     }
     // Backend write — failure surfaces via observability + audit but
     // doesn't bubble (caller already has the computed value).
-    backend.set(key, value, expiresAt).catch(function (e) {
+    backend.set(key, value, expiresAt, { ttlMs: ttlMs }).catch(function (e) {
       emitObs("cache.backend.failed", { namespace: namespace, op: "set" });
       _backendFailedAudit("set", e);
     });
@@ -765,7 +1016,7 @@ function create(opts) {
           _writeWithSwr(key, computed, ttlMs);
         } else {
           var expiresAt = (ttlMs === Infinity) ? Infinity : (clock() + ttlMs);
-          try { await backend.set(key, computed, expiresAt); }
+          try { await backend.set(key, computed, expiresAt, { ttlMs: ttlMs }); }
           catch (e) {
             emitObs("cache.backend.failed", { namespace: namespace, op: "set" });
             _backendFailedAudit("set", e);
@@ -803,7 +1054,10 @@ function create(opts) {
     has:                    has,
     clear:                  clear,
     size:                   size,
+    bytes:                  bytes,
     wrap:                   wrap,
+    invalidateTag:          invalidateTag,
+    getTags:                getTags,
     close:                  close,
     namespace:              namespace,
     // Test hooks

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.11",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",