@blamejs/core 0.7.4 → 0.7.19

package/lib/middleware/bearer-auth.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * bearer-auth middleware — extracts `Authorization: Bearer <token>`,
+ * runs an operator-supplied verifier, and attaches the result to
+ * `req.user`. Distinct from `attachUser` (which reads session cookies)
+ * — this is the API-token / JWT / OAuth-access-token path.
+ *
+ * Mount this for routes that accept bearer tokens. Operators that
+ * accept BOTH cookie sessions AND bearer tokens mount both: bearerAuth
+ * runs first; if no Bearer header, it calls next() so attachUser /
+ * requireAuth can take over. If a Bearer header IS present but invalid,
+ * bearerAuth rejects with 401 immediately (avoids the
+ * "is this a bearer or a cookie session?" collision in attach-user.js).
+ *
+ *   var bearer = b.middleware.bearerAuth({
+ *     verify: async function (token) {
+ *       // operator-supplied: return a user object or null/throw
+ *       var rec = await b.apiKey.verify(token);
+ *       return rec ? { id: rec.ownerId, scopes: rec.scopes } : null;
+ *     },
+ *     audit:        true,                  // default
+ *     scheme:       "Bearer",              // default; some ops use "Token"
+ *     errorMessage: "Bearer token required.",
+ *   });
+ *   router.use("/api", bearer);
+ *
+ * Verify result shape:
+ *   - object truthy → req.user = result; next()
+ *   - null / undefined / false → 401 (token invalid)
+ *   - throws an Error with .code === "auth-bearer/expired" → 401 + WWW-Authenticate
+ *
+ * Audit: `auth.bearer.success` on accept; `auth.bearer.failure` with
+ * reason on reject. Both carry actor context (clientIp, userAgent,
+ * route).
+ */
+
+var lazyRequire = require("../lazy-require");
+var requestHelpers = require("../request-helpers");
+var validateOpts = require("../validate-opts");
+var { AuthError } = require("../framework-error");
+
+var audit = lazyRequire(function () { return require("../audit"); });
+var observability = lazyRequire(function () { return require("../observability"); });
+
+function _writeUnauthorized(res, scheme, message, realm) {
+  if (res.headersSent) return;
+  var body = JSON.stringify({ error: message });
+  var challenge = scheme + (realm ? ' realm="' + realm + '"' : "");
+  res.writeHead(401, {                                                           // allow:raw-byte-literal — HTTP 401 status
+    "Content-Type":     "application/json; charset=utf-8",
+    "Content-Length":   Buffer.byteLength(body),
+    "WWW-Authenticate": challenge,
+  });
+  res.end(body);
+}
+
+function _extractToken(req, scheme) {
+  var h = req.headers && req.headers.authorization;
+  if (typeof h !== "string" || h.length === 0) return null;
+  var prefix = scheme + " ";
+  if (h.length <= prefix.length) return null;
+  if (h.slice(0, prefix.length).toLowerCase() !== prefix.toLowerCase()) return null;
+  var token = h.slice(prefix.length).trim();
+  return token.length > 0 ? token : null;
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "verify", "audit", "scheme", "errorMessage", "realm",
+    "tokenAttachKey", "userAttachKey",
+  ], "middleware.bearerAuth");
+
+  if (typeof opts.verify !== "function") {
+    throw new AuthError("auth-bearer/missing-verify",
+      "middleware.bearerAuth requires a verify(token) function — operators MUST supply " +
+      "the verification path (b.apiKey.verify / b.auth.jwt.verifyExternal / custom)");
+  }
+  var auditOn       = opts.audit !== false;
+  var scheme        = opts.scheme || "Bearer";
+  var errorMessage  = opts.errorMessage || "Bearer token required.";
+  var realm         = opts.realm || null;
+  var tokenAttach   = opts.tokenAttachKey || "bearerToken";
+  var userAttach    = opts.userAttachKey || "user";
+
+  function _emitAudit(action, outcome, req, reason) {
+    if (!auditOn) return;
+    try {
+      var actor = requestHelpers.extractActorContext(req);
+      audit().safeEmit({
+        action: action, outcome: outcome,
+        metadata: Object.assign({}, actor, {
+          route:  req.url,
+          method: req.method,
+          reason: reason || null,
+        }),
+      });
+    } catch (_e) { /* audit best-effort */ }
+  }
+
+  function _emitObs(metric, n, tags) {
+    try { observability().count(metric, n, tags || {}); }
+    catch (_e) { /* best-effort */ }
+  }
+
+  return async function bearerAuth(req, res, next) {
+    var token = _extractToken(req, scheme);
+    if (!token) {
+      // No Bearer header — fall through. Cookie-based session middleware
+      // running after this can attach a user via the cookie path.
+      return next();
+    }
+
+    var user;
+    try {
+      user = await opts.verify(token);
+    } catch (e) {
+      var code = (e && e.code) || "auth-bearer/verify-failed";
+      _emitAudit("auth.bearer.failure", "failure", req, code);
+      _emitObs("auth.bearer.rejected", 1, { reason: code });
+      // Per RFC 6750 §3 — `Bearer error="invalid_token"` is the
+      // standardized challenge for verifier-rejected tokens.
+      var challenge = scheme + ' error="invalid_token"' +
+        (realm ? ', realm="' + realm + '"' : "");
+      if (!res.headersSent) {
+        var body = JSON.stringify({ error: errorMessage });
+        res.writeHead(401, {                                                     // allow:raw-byte-literal — HTTP 401 status
+          "Content-Type":     "application/json; charset=utf-8",
+          "Content-Length":   Buffer.byteLength(body),
+          "WWW-Authenticate": challenge,
+        });
+        res.end(body);
+      }
+      return;
+    }
+
+    if (!user) {
+      _emitAudit("auth.bearer.failure", "failure", req, "verifier-returned-null");
+      _emitObs("auth.bearer.rejected", 1, { reason: "verifier-null" });
+      _writeUnauthorized(res, scheme, errorMessage, realm);
+      return;
+    }
+
+    req[tokenAttach] = token;
+    req[userAttach]  = user;
+    _emitAudit("auth.bearer.success", "success", req, null);
+    _emitObs("auth.bearer.accepted", 1, {});
+    next();
+  };
+}
+
+module.exports = { create: create };

package/lib/middleware/body-parser.js

@@ -241,6 +241,68 @@ function _hasBody(req) {
   return false;
 }
 
+// HTTP request-smuggling defense per RFC 9112 §6.1 — covers the
+// CVE-2022-31394 / CVE-2024-27316 / CL.TE / TE.CL / TE.TE class.
+// Returns null on clean; { status, code, message } on smuggling-shaped
+// request that the caller MUST reject with 400 + Connection: close.
+function _detectSmuggling(req) {
+  var headers = req.headers || {};
+  var cl = headers["content-length"];
+  var te = headers["transfer-encoding"];
+
+  // 1. Both Content-Length AND Transfer-Encoding present — RFC 9112
+  //    §6.1 says receiver MUST reject; the dual presence is the canonical
+  //    CL.TE / TE.CL smuggling shape.
+  if (typeof cl === "string" && cl.length > 0 &&
+      typeof te === "string" && te.length > 0) {
+    return {
+      status: HTTP_STATUS.BAD_REQUEST, code: "smuggling/te-cl-conflict",
+      message: "request has both Content-Length and Transfer-Encoding " +
+               "headers (RFC 9112 §6.1 — request-smuggling vector)",
+    };
+  }
+
+  // 2. Multiple Content-Length values. Node's http parser collapses
+  //    duplicate headers into a comma-separated string — `cl.indexOf(",")`
+  //    catches it.
+  if (typeof cl === "string" && cl.indexOf(",") !== -1) {
+    return {
+      status: HTTP_STATUS.BAD_REQUEST, code: "smuggling/multiple-content-length",
+      message: "request has multiple Content-Length values (RFC 9112 §6.1)",
+    };
+  }
+
+  // 3. Transfer-Encoding present — final coding MUST be `chunked`
+  //    (RFC 9112 §6.1). Anything else is a smuggling vector or
+  //    server-side decode error.
+  if (typeof te === "string" && te.length > 0) {
+    var tokens = te.toLowerCase().split(",").map(function (t) { return t.trim(); });
+    var last = tokens[tokens.length - 1];
+    if (last !== "chunked") {
+      return {
+        status: HTTP_STATUS.BAD_REQUEST, code: "smuggling/te-not-chunked",
+        message: "request has Transfer-Encoding but final coding is not " +
+                 "`chunked` (RFC 9112 §6.1 requires chunked be last)",
+      };
+    }
+    // 4. Duplicate `chunked` token (TE: chunked, chunked) — explicitly
+    //    forbidden by RFC 9112 §6.1.
+    var chunkedCount = 0;
+    for (var i = 0; i < tokens.length; i += 1) {
+      if (tokens[i] === "chunked") chunkedCount += 1;
+    }
+    if (chunkedCount > 1) {
+      return {
+        status: HTTP_STATUS.BAD_REQUEST, code: "smuggling/duplicate-chunked",
+        message: "Transfer-Encoding lists `chunked` more than once " +
+                 "(RFC 9112 §6.1 — TE.TE smuggling vector)",
+      };
+    }
+  }
+
+  return null;
+}
+
 function _writeError(res, status, message, code) {
   if (res.headersSent) return;
   var body = JSON.stringify({ error: message, code: code });
@@ -955,6 +1017,23 @@ function create(opts) {
   var keepRawBody     = !!opts.keepRawBody;
 
   return async function bodyParser(req, res, next) {
+    // RFC 9112 §6.1 request-smuggling defense — runs BEFORE _hasBody
+    // so the smuggling shape is rejected even if the request would
+    // otherwise short-circuit as no-body. Reject with 400 +
+    // Connection: close so the upstream proxy doesn't reuse the socket.
+    var smug = _detectSmuggling(req);
+    if (smug) {
+      if (!res.headersSent) {
+        var smugBody = JSON.stringify({ error: smug.message, code: smug.code });
+        res.writeHead(smug.status, {
+          "Content-Type":   "application/json; charset=utf-8",
+          "Content-Length": Buffer.byteLength(smugBody),
+          "Connection":     "close",
+        });
+        res.end(smugBody);
+      }
+      return;
+    }
     if (!_hasBody(req)) return next();
     if (req.body !== undefined) return next(); // already parsed by an earlier middleware
 

package/lib/middleware/index.js

@@ -18,6 +18,7 @@
  */
 var apiEncrypt = require("./api-encrypt");
 var attachUser = require("./attach-user");
+var bearerAuth = require("./bearer-auth");
 var bodyParser = require("./body-parser");
 var botGuard = require("./bot-guard");
 var compression = require("./compression");
@@ -43,6 +44,7 @@ module.exports = {
   cors:             cors.create,
   rateLimit:        rateLimit.create,
   attachUser:       attachUser.create,
+  bearerAuth:       bearerAuth.create,
   requireAuth:      requireAuth.create,
   csrfProtect:      csrfProtect.create,
   bodyParser:       bodyParser.create,
@@ -64,6 +66,7 @@ module.exports = {
     cors:             cors,
     rateLimit:        rateLimit,
     attachUser:       attachUser,
+    bearerAuth:       bearerAuth,
     requireAuth:      requireAuth,
     csrfProtect:      csrfProtect,
     bodyParser:       bodyParser,

package/lib/numeric-bounds.js

@@ -82,10 +82,30 @@ function requireNonNegativeFiniteIntIfPresent(value, label, errorClass, code) {
   return value;
 }
 
+// requireAllPositiveFiniteIntIfPresent — batch validator. Walk each
+// opt-name in the list; for any that is present in opts, require it to
+// be a positive finite integer (otherwise throw via errorClass with the
+// shared code). Used by primitives whose entry points have a 3-6
+// numeric opts that all share the same shape constraint, so the inline
+// call sequence doesn't repeat per primitive.
+//
+//   nb.requireAllPositiveFiniteIntIfPresent(opts,
+//     ["maxBytes", "maxAttrValueBytes", "maxTagDepth", "maxAttrsPerTag"],
+//     "guardHtml.validate", GuardHtmlError, "html.bad-opt");
+function requireAllPositiveFiniteIntIfPresent(opts, names, labelPrefix, errorClass, code) {
+  if (!opts || !Array.isArray(names)) return;
+  for (var i = 0; i < names.length; i += 1) {
+    var n = names[i];
+    requirePositiveFiniteIntIfPresent(opts[n],
+      (labelPrefix || "") + ": " + n, errorClass, code);
+  }
+}
+
 module.exports = {
   shape:                                  shape,
   isPositiveFiniteInt:                    isPositiveFiniteInt,
   isNonNegativeFiniteInt:                 isNonNegativeFiniteInt,
   requirePositiveFiniteIntIfPresent:      requirePositiveFiniteIntIfPresent,
   requireNonNegativeFiniteIntIfPresent:   requireNonNegativeFiniteIntIfPresent,
+  requireAllPositiveFiniteIntIfPresent:   requireAllPositiveFiniteIntIfPresent,
 };

package/lib/session.js

@@ -54,6 +54,23 @@ var DEFAULT_TTL_MS = C.TIME.days(7);
 // expiresAt away from epoch overflow + database-int boundary issues.
 var MAX_TTL_MS     = C.TIME.days(3650);   // ~10 years
 
+// Idle + absolute timeout defaults per OWASP ASVS 5.0 §3.3 + NIST
+// SP 800-63B-4. expiresAt is the operator-set window; idle/absolute
+// are independent enforcement floors that shorten the effective
+// session lifetime even when the operator picked a long ttlMs.
+//
+//  - idle: session expires N ms after the last verify() / touch().
+//          Default 30 minutes — short enough to defeat session-token
+//          theft via short-lived foothold; long enough that a user
+//          reading a long article doesn't get logged out.
+//  - absolute: session always expires at most N ms after creation,
+//          regardless of activity. Default 12 hours — re-auth at
+//          least once per shift even on a continuously-active
+//          session. Repeated touch() with extendBy cannot push past
+//          this ceiling.
+var DEFAULT_IDLE_TIMEOUT_MS     = C.TIME.minutes(30);
+var DEFAULT_ABSOLUTE_TIMEOUT_MS = C.TIME.hours(12);
+
 function _validateTtl(ttl, where) {
   if (typeof ttl !== "number" || !isFinite(ttl) || ttl <= 0) {
     throw _err("INVALID_ARG",
@@ -197,15 +214,55 @@ async function verify(token, verifyOpts) {
     [sidHash]
   );
   if (!row) return null;
-  if (Number(row.expiresAt) < Date.now()) {
-    // Expired — clean up and return null. Cleanup is leader-only;
-    // verify is anywhere, so a follower observing an expired row
-    // skips the cleanup (next leader-side call will purge it).
+  var nowMs = Date.now();
+  if (Number(row.expiresAt) < nowMs) {
+    // Expired (operator-set ttl) — clean up and return null. Cleanup
+    // is leader-only; verify is anywhere, so a follower observing an
+    // expired row skips the cleanup (next leader-side call purges it).
     if (cluster.isLeader()) {
       try { await _deleteBySidHash(sidHash); } catch (_e) { /* best-effort */ }
     }
     return null;
   }
+
+  // Idle + absolute timeout enforcement (OWASP ASVS 5.0 §3.3 / NIST
+  // SP 800-63B-4). These shorten the effective lifetime even when the
+  // operator picked a long ttlMs. Defaults: idle 30m, absolute 12h.
+  // Operator opt-out by passing 0 (disables that timeout).
+  var idleMs = verifyOpts.idleTimeoutMs !== undefined
+    ? verifyOpts.idleTimeoutMs : DEFAULT_IDLE_TIMEOUT_MS;
+  var absMs = verifyOpts.absoluteTimeoutMs !== undefined
+    ? verifyOpts.absoluteTimeoutMs : DEFAULT_ABSOLUTE_TIMEOUT_MS;
+  if (idleMs > 0) {
+    var lastActivity = Number(row.lastActivity);
+    if ((nowMs - lastActivity) > idleMs) {
+      try {
+        audit.safeEmit({
+          action: "auth.session.expired_idle", outcome: "warning",
+          metadata: { idleMs: nowMs - lastActivity, threshold: idleMs },
+        });
+      } catch (_ignored) { /* audit best-effort */ }
+      if (cluster.isLeader()) {
+        try { await _deleteBySidHash(sidHash); } catch (_e) { /* best-effort */ }
+      }
+      return null;
+    }
+  }
+  if (absMs > 0) {
+    var createdAt = Number(row.createdAt);
+    if ((nowMs - createdAt) > absMs) {
+      try {
+        audit.safeEmit({
+          action: "auth.session.expired_absolute", outcome: "warning",
+          metadata: { ageMs: nowMs - createdAt, threshold: absMs },
+        });
+      } catch (_ignored) { /* audit best-effort */ }
+      if (cluster.isLeader()) {
+        try { await _deleteBySidHash(sidHash); } catch (_e) { /* best-effort */ }
+      }
+      return null;
+    }
+  }
   // Unseal sealed columns (userId, data) using the cryptoField pipeline
   // so we return cleartext to the caller — same shape as the previous
   // db().from(...).first() path delivered.

package/lib/static.js

@@ -36,6 +36,7 @@ var fsp = require("node:fs/promises");
 var nodeCrypto = require("node:crypto");
 var path = require("node:path");
 var C = require("./constants");
+var gateContract = require("./gate-contract");
 var lazyRequire = require("./lazy-require");
 var numericBounds = require("./numeric-bounds");
 var requestHelpers = require("./request-helpers");
@@ -47,6 +48,11 @@ var { StaticServeError } = require("./framework-error");
 // observability is ready.
 var observability = lazyRequire(function () { return require("./observability"); });
 
+// guard-* family is wired on by default; lazy-loaded to avoid eager
+// import cycles. Operators opt out via contentSafety: null (audited).
+var guardAll = lazyRequire(function () { return require("./guard-all"); });
+var guardFilename = lazyRequire(function () { return require("./guard-filename"); });
+
 var _err = StaticServeError.factory;
 
 var HTTP = requestHelpers.HTTP_STATUS;
@@ -159,6 +165,39 @@ function _resolveSafe(root, requestedPath) {
   var rootResolved = path.resolve(root);
   if (resolved !== rootResolved &&
       !resolved.startsWith(rootResolved + path.sep)) return null;
+
+  // Symlink-escape defense — the lexical resolve above only sees the
+  // requested path tokens; a symlink anywhere along `resolved` can
+  // still point outside `rootResolved` on disk. realpath every node
+  // (only when it exists; missing files are routed through the
+  // standard 404 path by the caller).
+  try {
+    var real = fs.realpathSync(resolved);
+    var rootReal = fs.realpathSync(rootResolved);
+    if (real !== rootReal && !real.startsWith(rootReal + path.sep)) return null;
+    resolved = real;
+  } catch (_e) {
+    // Path doesn't exist (or is denied) — fall through with the lexical
+    // resolution so the caller's stat() returns the natural ENOENT and
+    // 404s. realpath failures from non-existence are NOT a smuggling
+    // signal.
+  }
+
+  // Filename safety — the basename gates against path-traversal /
+  // null-byte / NTFS ADS / UNC / RTLO bidi / overlong UTF-8 / Windows
+  // reserved device names. Uses balanced profile + explicit
+  // shellExecExtPolicy: "allow" because static-serve serves operator-
+  // deposited disk content: shell-exec extensions (.exe / .bin / .so /
+  // legitimate `<name>.<hash>.js` bundler output) are valid here. The
+  // other balanced checks still reject the traversal + smuggling
+  // surface the user surfaced.
+  var fname = path.basename(resolved);
+  var rv = guardFilename().validate(fname, {
+    profile:             "balanced",
+    shellExecExtPolicy:  "allow",
+  });
+  if (!rv.ok) return null;
+
   return resolved;
 }
 
@@ -236,10 +275,8 @@ function _validateCreateOpts(opts) {
     "staticServe.create: indexFile", StaticServeError, "BAD_OPT");
   numericBounds.requireNonNegativeFiniteIntIfPresent(opts.defaultMaxAge,
     "staticServe.create: defaultMaxAge", StaticServeError, "BAD_OPT");
-  if (opts.contentTypes !== undefined && opts.contentTypes !== null &&
-      (typeof opts.contentTypes !== "object" || Array.isArray(opts.contentTypes))) {
-    throw _err("BAD_OPT", "staticServe.create: contentTypes must be a plain object");
-  }
+  validateOpts.optionalPlainObject(opts.contentTypes,
+    "staticServe.create: contentTypes", StaticServeError, "BAD_OPT");
   validateOpts.optionalObjectWithMethod(opts.permissions, "check",
     "staticServe.create: permissions", StaticServeError, "BAD_OPT",
     "must be a b.permissions instance (check fn)");
@@ -266,6 +303,29 @@ function _validateCreateOpts(opts) {
   validateOpts.auditShape(opts.audit, "staticServe.create", StaticServeError);
   validateOpts.observabilityShape(opts.observability, "staticServe.create", StaticServeError);
   validateOpts.optionalFunction(opts.onServe, "staticServe.create: onServe", StaticServeError);
+  // contentSafety — extension-keyed gate map. 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,
+      "staticServe.create: contentSafety", StaticServeError, "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",
+          "staticServe.create: contentSafety[" + JSON.stringify(ext) +
+          "] must be a gate (b.guardCsv.gate / b.guardHtml.gate / etc.)");
+      }
+    }
+  }
   validateOpts.optionalBoolean(opts.acceptRanges, "staticServe.create: acceptRanges", StaticServeError);
   validateOpts.optionalBoolean(opts.auditSuccess, "staticServe.create: auditSuccess", StaticServeError);
   validateOpts.optionalBoolean(opts.auditFailures, "staticServe.create: auditFailures", StaticServeError);
@@ -393,6 +453,7 @@ function create(opts) {
     "acceptRanges", "auditSuccess", "auditFailures",
     "maxBytesPerActorPerWindowMs", "maxBytesAllActorsPerWindowMs",
     "bandwidthWindowMs", "maxConcurrentDownloadsPerActor", "maxIdleMs",
+    "contentSafety", "contentSafetyDisabledReason",
   ], "staticServe.create");
   _validateCreateOpts(opts);
   var cfg = validateOpts.applyDefaults(opts, DEFAULTS);
@@ -408,6 +469,37 @@ function create(opts) {
   var retention       = opts.retention || null;
   var revokeStore     = opts.revokeStore || null;
   var allowedFileTypes = Array.isArray(opts.allowedFileTypes) ? opts.allowedFileTypes.slice() : [];
+  // 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. Operators who
+    // serve 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:   "staticServe.contentSafety.disabled",
+          actor:    {},
+          outcome:  "success",
+          metadata: {
+            reason: opts.contentSafetyDisabledReason || "operator-explicit-opt-out",
+          },
+        });
+      } catch (_e) { /* audit best-effort */ }
+    }
+    contentSafety = null;
+  } else {
+    contentSafety = opts.contentSafety;
+  }
   var onServe         = opts.onServe || null;
   var audit           = opts.audit || null;
   var auditSuccess    = cfg.auditSuccess;
@@ -573,6 +665,68 @@ function create(opts) {
       }
     }
 
+    // Content-safety gate — operator-supplied per-extension gate
+    // (b.guardCsv.gate / b.guardHtml.gate / etc.). Reads the file once
+    // up to maxRuntimeMs and routes the bytes through the gate's
+    // check() before serving. The gate's decision is honored:
+    //   - serve     → continue with the original bytes
+    //   - sanitize  → continue with decision.sanitized
+    //   - refuse    → 415 / opaque to clients
+    //   - audit-only / warn → continue (gate emits to audit)
+    var gateBytesOverride = null;
+    if (contentSafety) {
+      var ext = path.extname(absPath).toLowerCase();
+      var safetyGate = contentSafety[ext];
+      if (safetyGate && typeof safetyGate.check === "function") {
+        var gateBuf;
+        try { gateBuf = await fsp.readFile(absPath); }
+        catch (_e) {
+          stats.failures += 1;
+          return _writeError(res, HTTP.INTERNAL_SERVER_ERROR,
+            "read_failed", "Internal Server Error");
+        }
+        var gateDecision;
+        try {
+          gateDecision = await safetyGate.check({
+            bytes:       gateBuf,
+            contentType: _contentTypeFor(absPath, contentTypes),
+            filename:    path.basename(absPath),
+            actor:       actorCtx,
+            route:       urlPath,
+            direction:   "outbound",
+            req:         req,
+          });
+        } catch (gateErr) {
+          stats.failures += 1;
+          _emitObs("staticServe.content_safety_threw", 1, { route: urlPath });
+          if (auditFailures) {
+            emitAudit("staticServe.serve.failure", Object.assign({
+              outcome: "failure", reason: "content_safety_threw", resource: urlPath,
+              error: gateErr && gateErr.message,
+            }, actorCtx));
+          }
+          return _writeError(res, HTTP.INTERNAL_SERVER_ERROR,
+            "content_safety_threw", "Internal Server Error");
+        }
+        if (!gateDecision.ok || gateDecision.action === "refuse") {
+          stats.failures += 1;
+          _emitObs("staticServe.content_safety_refused", 1, { route: urlPath });
+          if (auditFailures) {
+            emitAudit("staticServe.serve.failure", Object.assign({
+              outcome: "failure", reason: "content_safety_refused",
+              resource: urlPath, ext: ext,
+              issues: gateContract.summarizeIssues(gateDecision.issues),
+            }, actorCtx));
+          }
+          return _writeError(res, HTTP.UNSUPPORTED_MEDIA_TYPE,
+            "content_safety_refused", "Unsupported Media Type");
+        }
+        if (gateDecision.action === "sanitize" && gateDecision.sanitized) {
+          gateBytesOverride = gateDecision.sanitized;
+        }
+      }
+    }
+
     var cacheControl = _cacheControlFor(urlPath);
 
     var headersIn = req.headers || {};
@@ -734,6 +888,32 @@ function create(opts) {
       return;
     }
 
+    // Sanitized override path — content-safety gate replaced the
+    // bytes; emit them directly without re-reading the file. Bypasses
+    // range / idle-timer machinery (the override is already in memory
+    // and Range over a sanitized variant doesn't have a useful
+    // contract — sanitization changes byte offsets).
+    if (gateBytesOverride) {
+      var overrideHeaders = Object.assign({}, headers, {
+        "Content-Length": gateBytesOverride.length,
+      });
+      delete overrideHeaders["Content-Range"];
+      res.writeHead(HTTP.OK, overrideHeaders);
+      res.end(gateBytesOverride);
+      stats.requestsServed += 1;
+      stats.bytesServed += gateBytesOverride.length;
+      _emitObs("staticServe.requests_served", 1, { route: urlPath, method: "GET", sanitized: true });
+      _emitObs("staticServe.bytes_served", gateBytesOverride.length, { route: urlPath, sanitized: true });
+      if (auditSuccess) {
+        emitAudit("staticServe.serve.success", Object.assign({
+          outcome: "success", resource: urlPath, method: "GET",
+          size: gateBytesOverride.length, contentType: overrideHeaders["Content-Type"],
+          sanitized: true,
+        }, actorCtx));
+      }
+      return;
+    }
+
     res.writeHead(status, headers);
 
     // Acquire concurrency slot (released on stream end / error / abort).

package/lib/validate-opts.js

@@ -266,6 +266,26 @@ function optionalObjectWithMethod(value, method, label, errorClass, code, descri
   return value;
 }
 
+// optionalPlainObject — required-shape validator for optional opts that
+// accept a plain object (not array, not null when undefined-meaning-absent
+// is intended). Replaces the recurring `if (X !== undefined && X !== null)
+// { if (typeof X !== "object" || Array.isArray(X)) throw }` cascade
+// shared by api-key (metadata), db-declare-view, db-declare-row-policy,
+// and static.js (contentSafety).
+//
+// undefined / null → returns the value unchanged (caller can default).
+// non-object OR array → throws via errorClass with the operator-facing
+// description (e.g. "metadata must be a plain object or null").
+function optionalPlainObject(value, label, errorClass, code, description) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    _throw(errorClass, code, (label || "opt") + " " +
+           (description || "must be a plain object or null"),
+           "validate-opts/bad-plain-object");
+  }
+  return value;
+}
+
 // makeAuditEmitter — closure factory parallel to safeAsync.makeDropCallback.
 // Replaces the per-file `function _emit(action, info) { if (!audit) return;
 // try { audit.safeEmit(Object.assign({ action: action }, info || {})); }
@@ -312,6 +332,7 @@ module.exports.optionalFunction = optionalFunction;
 module.exports.optionalNonEmptyString = optionalNonEmptyString;
 module.exports.optionalNonEmptyStringArray = optionalNonEmptyStringArray;
 module.exports.optionalObjectWithMethod = optionalObjectWithMethod;
+module.exports.optionalPlainObject = optionalPlainObject;
 module.exports.requireNonEmptyString = requireNonEmptyString;
 module.exports.observabilityShape = observabilityShape;
 module.exports.requireObject = requireObject;

package/package.json

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