@blamejs/core 0.4.8 → 0.4.10

package/CHANGELOG.md

@@ -8,6 +8,13 @@ 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
+- **0.4.5** (2026-04-30) — canonical domain is blamejs.com (was blamejs.app everywhere)
+- **0.4.4** (2026-04-30) — document BLAMEJS_AUDIT_SIGNING_PASSPHRASE everywhere
+- **0.4.3** (2026-04-30) — b.ssrfGuard primitive (default-on in httpClient) + wiki posture auto-detect
 - **0.4.2** (2026-04-30) — npm keywords
 - **0.4.1** (2026-04-29) — wiki bot-guard skips /healthz so the post-publish smoke check passes
 - **0.4.0** (2026-04-29) — bench suite + drops the deprecated b.logger.createLogger

package/README.md

@@ -11,7 +11,7 @@ One install. One upgrade path. One place to look when something breaks — no bl
 The modern Node app is a 1,200-package supply-chain liability with no LTS calendar, no curator, and no accountability. Frameworks peer-depend their internals onto you and call it modularity. blamejs takes the opposite stance:
 
 - **Vendored standard library.** Auth, sessions, jobs, mail, storage, crypto, ORM, templating — bundled with the framework, not hunted on npm. Your `package.json` has one entry.
-- **Security as a default, not a config flag.** Post-quantum-aware crypto envelopes, sealed-by-default storage, server-rendered output, CSRF/origin/bot defenses wired in from line zero.
+- **Security as a default, not a config flag.** Post-quantum-aware crypto envelopes, sealed-by-default storage, server-rendered output, CSRF/origin/bot defenses, per-account brute-force lockout, all wired in from line zero.
 - **Server-rendering first.** HTML out of the box; client JS is opt-in islands, not the foundation.
 - **A real LTS calendar.** Major versions on a published cadence with documented deprecation windows. No silent semver-major surprises in transitive deps.
 

package/index.js

@@ -20,7 +20,7 @@
  *                 error-handler, body-parser, csp-nonce, compression,
  *                 health, api-encrypt), httpClient, websocket,
  *                 websocketChannels, nonceStore
- *   Auth:         auth.{password,totp,passkey,jwt,oauth}, authHeader
+ *   Auth:         auth.{password,totp,passkey,jwt,oauth,lockout}, authHeader
  *   Render:       template, render, staticServe, forms, errorPage
  *   App:          createApp, jobs, mail, mailBounce, scheduler,
  *                 appShutdown
@@ -93,6 +93,7 @@ var auth = {
   passkey:  require("./lib/auth/passkey"),
   jwt:      require("./lib/auth/jwt"),
   oauth:    require("./lib/auth/oauth"),
+  lockout:  require("./lib/auth/lockout"),
 };
 var template = require("./lib/template");
 var render = require("./lib/render");

package/lib/auth/lockout.js

@@ -0,0 +1,446 @@
+"use strict";
+/**
+ * b.auth.lockout — per-key failed-attempt tracking with exponential
+ * backoff lockout windows and admin/unlock.
+ *
+ * Operators compose this around any "X attempts to do Y" surface where
+ * online brute force is the threat — login by password, login by TOTP,
+ * passkey verification, password-reset code entry, etc. Each operator-
+ * named instance keeps its own counter namespace, so login attempts and
+ * TOTP attempts decay and lock independently.
+ *
+ * State storage is a b.cache instance the operator passes in. Memory
+ * backend → per-process counters. Cluster backend → shared across nodes.
+ * The cache TTL keeps the state self-cleaning — no separate sweep.
+ *
+ *   var loginLock = b.auth.lockout.create({
+ *     namespace: "login",
+ *     cache:     b.cache.create({ namespace: "auth.lockout.login", backend: "cluster" }),
+ *     audit:     b.audit,
+ *   });
+ *
+ *   // Pre-check before doing argon2 verify (saves ~250ms when locked)
+ *   var state = await loginLock.check(req.body.email);
+ *   if (state.locked) return res.status(429).json({ lockedUntil: state.lockedUntil });
+ *
+ *   var ok = await b.auth.password.verify(stored, req.body.password);
+ *   if (!ok) {
+ *     var verdict = await loginLock.recordFailure(req.body.email, { req });
+ *     return res.status(401).json({
+ *       attemptsRemaining: Math.max(0, MAX - verdict.attempts),
+ *       lockedUntil:       verdict.lockedUntil,
+ *     });
+ *   }
+ *   await loginLock.recordSuccess(req.body.email, { req });
+ *   // ... session.create
+ *
+ *   // Admin-driven unlock — emits auth.lockout.unlock with the admin
+ *   // operator's 5 W's via extractActorContext({ req }).
+ *   await loginLock.unlock(targetUserId, { req, reason: "support ticket #4471" });
+ *
+ * Default backoff ladder (each subsequent lockout in a window-of-windows
+ * stays longer to make sustained attacks expensive):
+ *
+ *   1st lockout → C.TIME.minutes(1)
+ *   2nd         → C.TIME.minutes(5)
+ *   3rd         → C.TIME.minutes(15)
+ *   4th         → C.TIME.hours(1)
+ *   5th and later → C.TIME.hours(6)
+ *
+ * Failures outside `windowMs` decay (counter resets on the next failure).
+ * Successful auth clears the counter and any active lockout entirely so
+ * a legitimate user who finally remembers their password isn't penalised
+ * for the prior streak.
+ *
+ * Backend-error posture: if the cache backend throws on get/set/del —
+ * Redis down, cluster DB unreachable — the lockout fails OPEN, not
+ * closed. The framework's job is to slow brute force, not to lock
+ * operators out of their own admin account because the cache went
+ * away. Backend errors emit `auth.lockout.cache_error` observability
+ * so ops dashboards see the issue.
+ *
+ * Operator surface returned by create():
+ *
+ *   recordFailure(key, opts?)  → { locked, attempts, lockedUntil? }
+ *   recordSuccess(key, opts?)  → void                   (clears counter)
+ *   check(key)                 → { locked, attempts, lockedUntil? }
+ *                                                       (read-only)
+ *   unlock(key, opts?)         → boolean                (admin unlock)
+ *   attempts(key)              → number
+ *   close()                    → void                   (no-op; cache is
+ *                                                       operator-owned)
+ *
+ * Audit events (when `audit: b.audit` passed):
+ *
+ *   auth.lockout.failure   — every recordFailure. Default ON.
+ *   auth.lockout.engaged   — lockout transition. Default ON.
+ *   auth.lockout.unlock    — admin unlock. Default ON.
+ *   auth.lockout.success   — recordSuccess. Default OFF (opt in via
+ *                            auditSuccess: true for raw request-log mode).
+ */
+
+var C = require("../constants");
+var lazyRequire = require("../lazy-require");
+var requestHelpers = require("../request-helpers");
+var validateOpts = require("../validate-opts");
+var { LockoutError } = require("../framework-error");
+
+var observability = lazyRequire(function () { return require("../observability"); });
+
+var _err = LockoutError.factory;
+
+var DEFAULTS = Object.freeze({
+  maxAttempts:     5,
+  windowMs:        C.TIME.minutes(15),
+  lockoutDurations: Object.freeze([
+    C.TIME.minutes(1),
+    C.TIME.minutes(5),
+    C.TIME.minutes(15),
+    C.TIME.hours(1),
+    C.TIME.hours(6),
+  ]),
+  auditFailures: true,
+  auditEngaged:  true,
+  auditUnlock:   true,
+  auditSuccess:  false,
+});
+
+var ALLOWED_OPTS = [
+  "namespace", "cache", "maxAttempts", "windowMs", "lockoutDurations",
+  "audit", "auditFailures", "auditEngaged", "auditSuccess", "auditUnlock",
+  "observability", "clock",
+];
+
+function _requireString(name, val) {
+  if (typeof val !== "string" || val.length === 0) {
+    throw _err("BAD_OPT", name + ": expected non-empty string, got " +
+               typeof val + " " + JSON.stringify(val));
+  }
+}
+
+function _requirePositiveInt(name, val) {
+  if (typeof val !== "number" || !isFinite(val) || val < 1 || Math.floor(val) !== val) {
+    throw _err("BAD_OPT", name + ": expected positive integer, got " +
+               typeof val + " " + JSON.stringify(val));
+  }
+}
+
+function _requireNonNegFinite(name, val) {
+  if (typeof val !== "number" || !isFinite(val) || val < 0) {
+    throw _err("BAD_OPT", name + ": expected non-negative finite number, got " +
+               typeof val + " " + JSON.stringify(val));
+  }
+}
+
+function _requireKey(key) {
+  if (typeof key !== "string" || key.length === 0) {
+    throw _err("BAD_KEY", "key must be a non-empty string, got " +
+               typeof key + " " + JSON.stringify(key));
+  }
+}
+
+function _resolveDuration(durations, lockNumber) {
+  if (typeof durations === "function") {
+    var v = durations(lockNumber);
+    if (typeof v !== "number" || !isFinite(v) || v < 0) {
+      throw _err("BAD_LOCKOUT_DURATION",
+        "lockoutDurations(" + lockNumber + ") must return a non-negative finite number, got " +
+        typeof v + " " + JSON.stringify(v));
+    }
+    return v;
+  }
+  // Array — clamp to last entry so deeper lockouts stay at the longest.
+  var idx = Math.min(lockNumber - 1, durations.length - 1);
+  return durations[idx];
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ALLOWED_OPTS, "auth.lockout");
+
+  if (!opts.cache || typeof opts.cache !== "object" ||
+      typeof opts.cache.get !== "function" ||
+      typeof opts.cache.set !== "function" ||
+      typeof opts.cache.del !== "function") {
+    throw _err("BAD_OPT", "auth.lockout.create: opts.cache must be a b.cache " +
+               "instance (or shape with get/set/del). Pass b.cache.create({...}).");
+  }
+  _requireString("namespace", opts.namespace);
+
+  var maxAttempts = opts.maxAttempts !== undefined ? opts.maxAttempts : DEFAULTS.maxAttempts;
+  _requirePositiveInt("maxAttempts", maxAttempts);
+
+  var windowMs = opts.windowMs !== undefined ? opts.windowMs : DEFAULTS.windowMs;
+  _requireNonNegFinite("windowMs", windowMs);
+
+  var lockoutDurations = opts.lockoutDurations !== undefined
+                            ? opts.lockoutDurations : DEFAULTS.lockoutDurations;
+  if (typeof lockoutDurations !== "function") {
+    if (!Array.isArray(lockoutDurations) || lockoutDurations.length === 0) {
+      throw _err("BAD_OPT", "lockoutDurations must be a non-empty array of ms or a function(lockNumber)→ms");
+    }
+    for (var i = 0; i < lockoutDurations.length; i++) {
+      _requireNonNegFinite("lockoutDurations[" + i + "]", lockoutDurations[i]);
+    }
+  }
+
+  if (opts.audit !== undefined && opts.audit !== null) {
+    if (typeof opts.audit !== "object" || typeof opts.audit.safeEmit !== "function") {
+      throw _err("BAD_OPT", "auth.lockout.create: audit must be a b.audit-shaped object (safeEmit fn)");
+    }
+  }
+  if (opts.observability !== undefined && opts.observability !== null) {
+    if (typeof opts.observability !== "object" || typeof opts.observability.event !== "function") {
+      throw _err("BAD_OPT", "auth.lockout.create: observability must be b.observability-shaped (event fn)");
+    }
+  }
+  if (opts.clock !== undefined && typeof opts.clock !== "function") {
+    throw _err("BAD_OPT", "auth.lockout.create: clock must be a function or undefined");
+  }
+
+  var cache         = opts.cache;
+  var namespace     = opts.namespace;
+  var auditInst     = opts.audit || null;
+  var obsInst       = opts.observability || null;
+  var clock         = opts.clock || Date.now;
+  var auditFailures = opts.auditFailures !== undefined ? !!opts.auditFailures : DEFAULTS.auditFailures;
+  var auditEngaged  = opts.auditEngaged  !== undefined ? !!opts.auditEngaged  : DEFAULTS.auditEngaged;
+  var auditSuccess  = opts.auditSuccess  !== undefined ? !!opts.auditSuccess  : DEFAULTS.auditSuccess;
+  var auditUnlock   = opts.auditUnlock   !== undefined ? !!opts.auditUnlock   : DEFAULTS.auditUnlock;
+
+  function _scopedKey(key) { return namespace + ":" + key; }
+
+  function _emitObs(name, labels) {
+    var sink = obsInst || _safeGlobalObs();
+    if (!sink) return;
+    try { sink.event(name, 1, labels); } catch (_e) { /* observability is best-effort */ }
+  }
+
+  // Fall back to the framework's global observability registry when the
+  // operator didn't pass their own. event() is a no-op when no registry
+  // is wired, so this is zero-cost in apps without observability.
+  function _safeGlobalObs() {
+    try { return observability(); } catch (_e) { return null; }
+  }
+
+  function _emitAudit(action, key, outcome, metadata, req) {
+    if (!auditInst) return;
+    try {
+      var event = {
+        action:   action,
+        outcome:  outcome,
+        resource: { kind: "auth.lockout", id: namespace + ":" + key },
+        metadata: metadata || {},
+      };
+      if (req) event.actor = requestHelpers.extractActorContext(req);
+      auditInst.safeEmit(event);
+    } catch (_e) { /* audit best-effort */ }
+  }
+
+  async function _readState(key) {
+    try {
+      var raw = await cache.get(_scopedKey(key));
+      return raw || null;
+    } catch (_e) {
+      _emitObs("auth.lockout.cache_error", { namespace: namespace, op: "get" });
+      return null;
+    }
+  }
+
+  async function _writeState(key, state, ttlMs) {
+    try {
+      await cache.set(_scopedKey(key), state, { ttlMs: ttlMs });
+    } catch (_e) {
+      _emitObs("auth.lockout.cache_error", { namespace: namespace, op: "set" });
+    }
+  }
+
+  async function _deleteState(key) {
+    try {
+      await cache.del(_scopedKey(key));
+    } catch (_e) {
+      _emitObs("auth.lockout.cache_error", { namespace: namespace, op: "del" });
+    }
+  }
+
+  function _verdictFromState(state, now) {
+    if (!state) return { locked: false, attempts: 0 };
+    if (state.lockedUntil && state.lockedUntil > now) {
+      return {
+        locked:      true,
+        attempts:    state.attempts || 0,
+        lockedUntil: state.lockedUntil,
+      };
+    }
+    return { locked: false, attempts: state.attempts || 0 };
+  }
+
+  // ---- Public surface ----
+
+  async function recordFailure(key, callOpts) {
+    _requireKey(key);
+    callOpts = callOpts || {};
+    var now = clock();
+    var state = await _readState(key);
+
+    // If currently locked, the lockout itself counts — don't accumulate
+    // additional attempts during the cooldown. The caller saw locked=true
+    // from check() OR from a prior failure; this branch handles a caller
+    // that calls recordFailure() on a locked account anyway (e.g. they
+    // skipped check()).
+    if (state && state.lockedUntil && state.lockedUntil > now) {
+      _emitObs("auth.lockout.failure_during_lock", { namespace: namespace });
+      if (auditFailures) {
+        _emitAudit("auth.lockout.failure", key, "denied",
+          { duringLock: true, attempts: state.attempts || 0,
+            lockNumber: state.lockNumber || 0,
+            lockedUntil: state.lockedUntil,
+            reason: callOpts.reason || null },
+          callOpts.req);
+      }
+      return {
+        locked:      true,
+        attempts:    state.attempts || 0,
+        lockedUntil: state.lockedUntil,
+      };
+    }
+
+    // Window decay: failures older than windowMs reset the counter.
+    // Lock-number persists across decay windows so an attacker who
+    // sleeps off a lockout doesn't get a fresh ladder rung.
+    if (state && state.lastFailureAt && (now - state.lastFailureAt) > windowMs) {
+      state = {
+        attempts:       0,
+        lockNumber:     state.lockNumber || 0,
+        firstFailureAt: null,
+        lastFailureAt:  null,
+        lockedUntil:    null,
+      };
+    }
+
+    var attempts   = (state && state.attempts) || 0;
+    var lockNumber = (state && state.lockNumber) || 0;
+    attempts += 1;
+
+    var lockedUntil = null;
+    var newLock = false;
+    if (attempts >= maxAttempts) {
+      lockNumber += 1;
+      var dur = _resolveDuration(lockoutDurations, lockNumber);
+      lockedUntil = now + dur;
+      newLock = true;
+      attempts = 0;  // counter resets — the lockout window IS the punishment
+    }
+
+    var newState = {
+      attempts:       attempts,
+      lockNumber:     lockNumber,
+      firstFailureAt: (state && state.firstFailureAt) || now,
+      lastFailureAt:  now,
+      lockedUntil:    lockedUntil,
+    };
+
+    // TTL: keep the state alive long enough that a follower-up failure
+    // after the window/lockout expires still finds the lockNumber. The
+    // longer of (windowMs after last failure) or (lockedUntil + windowMs).
+    var ttlMs = lockedUntil ? (lockedUntil - now + windowMs) : windowMs;
+    await _writeState(key, newState, ttlMs);
+
+    _emitObs("auth.lockout.failure", { namespace: namespace });
+    if (auditFailures) {
+      _emitAudit("auth.lockout.failure", key, "failure",
+        { attempts: newState.attempts, lockNumber: lockNumber,
+          reason: callOpts.reason || null },
+        callOpts.req);
+    }
+
+    if (newLock) {
+      _emitObs("auth.lockout.engaged", {
+        namespace:  namespace,
+        lockNumber: String(lockNumber),
+      });
+      if (auditEngaged) {
+        _emitAudit("auth.lockout.engaged", key, "denied",
+          { lockNumber: lockNumber, lockedUntil: lockedUntil,
+            durationMs: lockedUntil - now,
+            reason: callOpts.reason || null },
+          callOpts.req);
+      }
+      return { locked: true, attempts: 0, lockedUntil: lockedUntil };
+    }
+
+    return { locked: false, attempts: attempts };
+  }
+
+  async function recordSuccess(key, callOpts) {
+    _requireKey(key);
+    callOpts = callOpts || {};
+    var state = await _readState(key);
+    var hadCounter = !!(state && (state.attempts > 0 || state.lockedUntil));
+    if (state) await _deleteState(key);
+    _emitObs("auth.lockout.success", { namespace: namespace });
+    if (auditSuccess) {
+      _emitAudit("auth.lockout.success", key, "success",
+        { attemptsCleared: (state && state.attempts) || 0,
+          hadCounter:      hadCounter },
+        callOpts.req);
+    }
+  }
+
+  async function check(key) {
+    _requireKey(key);
+    var state = await _readState(key);
+    return _verdictFromState(state, clock());
+  }
+
+  async function unlock(key, callOpts) {
+    _requireKey(key);
+    callOpts = callOpts || {};
+    var state = await _readState(key);
+    var now = clock();
+    var hadLock = !!(state && (
+      (state.lockedUntil && state.lockedUntil > now) ||
+      (state.attempts || 0) > 0
+    ));
+    if (state) await _deleteState(key);
+    _emitObs("auth.lockout.unlock", { namespace: namespace });
+    if (auditUnlock) {
+      _emitAudit("auth.lockout.unlock", key, "success",
+        { hadLock:           hadLock,
+          priorAttempts:    (state && state.attempts) || 0,
+          priorLockedUntil: (state && state.lockedUntil) || null,
+          priorLockNumber:  (state && state.lockNumber) || 0,
+          reason:           callOpts.reason || null },
+        callOpts.req);
+    }
+    return hadLock;
+  }
+
+  async function attempts(key) {
+    _requireKey(key);
+    var state = await _readState(key);
+    return (state && state.attempts) || 0;
+  }
+
+  async function close() {
+    // The cache is operator-owned; lockout doesn't close it. Provided
+    // for API symmetry with other primitives (cache.close, notify.close,
+    // etc.) so operator shutdown code can call close() uniformly.
+  }
+
+  return {
+    recordFailure: recordFailure,
+    recordSuccess: recordSuccess,
+    check:         check,
+    unlock:        unlock,
+    attempts:      attempts,
+    close:         close,
+    namespace:     namespace,
+  };
+}
+
+module.exports = {
+  create:       create,
+  LockoutError: LockoutError,
+  DEFAULTS:     DEFAULTS,
+};

package/lib/framework-error.js

@@ -161,6 +161,11 @@ var NotifyError           = defineClass("NotifyError",           { alwaysPermane
 // (NaN clock, non-fn predicate, path-traversal tempDir prefix) and
 // waitFor timeouts are programming bugs at test-write time.
 var TestingError          = defineClass("TestingError",          { alwaysPermanent: true });
+// LockoutError is alwaysPermanent: misconfig at create() and bad keys at
+// recordFailure/recordSuccess/check/unlock are programming bugs. The
+// "account is currently locked" condition is NOT an error — recordFailure
+// returns { locked: true, lockedUntil } so the caller decides the response.
+var LockoutError          = defineClass("LockoutError",          { alwaysPermanent: true });
 
 module.exports = {
   FrameworkError:         FrameworkError,
@@ -186,4 +191,5 @@ module.exports = {
   I18nError:              I18nError,
   NotifyError:            NotifyError,
   TestingError:           TestingError,
+  LockoutError:           LockoutError,
 };

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/lib/middleware/security-headers.js

@@ -12,6 +12,8 @@
  *   Cross-Origin-Opener-Policy: same-origin
  *   Cross-Origin-Embedder-Policy: require-corp   (off by default — breaks images from CDNs)
  *   Cross-Origin-Resource-Policy: same-origin
+ *   Origin-Agent-Cluster: ?1        — origin-keyed agent cluster; extra process isolation
+ *   X-DNS-Prefetch-Control: off     — don't pre-resolve DNS for off-page links
  *   Content-Security-Policy          — operator-supplied; framework provides a safe default that
  *                                       only allows same-origin and prevents inline scripts
  *
@@ -21,13 +23,15 @@
  *
  * Options:
  *   {
- *     hsts:           '<value>' or false to disable
- *     contentTypeOptions: 'nosniff' or false
- *     frameOptions:   'DENY' | 'SAMEORIGIN' or false
- *     referrerPolicy: '<value>' or false
- *     permissionsPolicy: '<value>' or false
- *     coop / coep / corp: '<value>' or false
- *     csp:            '<full CSP string>' or false to disable
+ *     hsts:                 '<value>' or false to disable
+ *     contentTypeOptions:   'nosniff' or false
+ *     frameOptions:         'DENY' | 'SAMEORIGIN' or false
+ *     referrerPolicy:       '<value>' or false
+ *     permissionsPolicy:    '<value>' or false
+ *     coop / coep / corp:   '<value>' or false
+ *     originAgentCluster:   '?1' (default) or '?0' or false
+ *     dnsPrefetchControl:   'off' (default) or 'on' or false
+ *     csp:                  '<full CSP string>' or false to disable
  *   }
  */
 
@@ -57,7 +61,8 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "hsts", "contentTypeOptions", "frameOptions", "referrerPolicy",
-    "permissionsPolicy", "coop", "coep", "corp", "csp",
+    "permissionsPolicy", "coop", "coep", "corp",
+    "originAgentCluster", "dnsPrefetchControl", "csp",
   ], "middleware.securityHeaders");
   var hsts = opts.hsts === undefined ? "max-age=63072000; includeSubDomains; preload" : opts.hsts;
   var ctOpts = opts.contentTypeOptions === undefined ? "nosniff" : opts.contentTypeOptions;
@@ -67,6 +72,8 @@ function create(opts) {
   var coop  = opts.coop === undefined ? "same-origin" : opts.coop;
   var coep  = opts.coep === undefined ? false : opts.coep;
   var corp  = opts.corp === undefined ? "same-origin" : opts.corp;
+  var oac   = opts.originAgentCluster === undefined ? "?1" : opts.originAgentCluster;
+  var dpc   = opts.dnsPrefetchControl === undefined ? "off" : opts.dnsPrefetchControl;
   var csp   = opts.csp === undefined ? DEFAULT_CSP : opts.csp;
 
   return function securityHeaders(req, res, next) {
@@ -79,6 +86,8 @@ function create(opts) {
     if (coop)       res.setHeader("Cross-Origin-Opener-Policy", coop);
     if (coep)       res.setHeader("Cross-Origin-Embedder-Policy", coep);
     if (corp)       res.setHeader("Cross-Origin-Resource-Policy", corp);
+    if (oac)        res.setHeader("Origin-Agent-Cluster", oac);
+    if (dpc)        res.setHeader("X-DNS-Prefetch-Control", dpc);
     if (csp)        res.setHeader("Content-Security-Policy", csp);
     next();
   };

package/package.json

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