@blamejs/core 0.6.13 → 0.6.20

package/lib/network.js

@@ -0,0 +1,233 @@
+"use strict";
+
+var ntpCheck = require("./ntp-check");
+var nts      = require("./network-nts");
+var dns      = require("./network-dns");
+var proxy    = require("./network-proxy");
+var trust    = require("./network-tls");
+var heartbeat = require("./network-heartbeat");
+
+var validateOpts = require("./validate-opts");
+var lazyRequire = require("./lazy-require");
+var { defineClass } = require("./framework-error");
+
+var NetworkError = defineClass("NetworkError", { alwaysPermanent: true });
+
+var observability = lazyRequire(function () { return require("./observability"); });
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var SOCKET_DEFAULTS = {
+  noDelay:           true,
+  keepAlive:         true,
+  keepAliveInitialDelayMs: 0,
+};
+
+function _setSocketNoDelay(value) {
+  if (typeof value !== "boolean") {
+    throw new NetworkError("socket/bad-no-delay", "socket.setDefaultNoDelay: expected boolean, got " + typeof value);
+  }
+  SOCKET_DEFAULTS.noDelay = value;
+}
+
+function _setSocketKeepAlive(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["enable", "initialDelayMs"], "socket.setDefaultKeepAlive");
+  if (opts.enable !== undefined) {
+    if (typeof opts.enable !== "boolean") {
+      throw new NetworkError("socket/bad-keepalive", "socket.setDefaultKeepAlive: enable must be boolean");
+    }
+    SOCKET_DEFAULTS.keepAlive = opts.enable;
+  }
+  if (opts.initialDelayMs !== undefined) {
+    if (typeof opts.initialDelayMs !== "number" || !isFinite(opts.initialDelayMs) || opts.initialDelayMs < 0) {
+      throw new NetworkError("socket/bad-keepalive-delay", "socket.setDefaultKeepAlive: initialDelayMs must be non-negative finite number");
+    }
+    SOCKET_DEFAULTS.keepAliveInitialDelayMs = opts.initialDelayMs;
+  }
+}
+
+// SO_LINGER is intentionally NOT exposed: Node's net.Socket has no
+// public setLinger() method (the option is tracked at
+// nodejs/node#27293 / rejected for the public surface). Reaching into
+// socket._handle to call setLinger is an unstable internal API. The
+// closest operator-exposed semantic is socket.destroy() (RST = "abort
+// on close") vs socket.end() (graceful FIN). Operators needing true
+// SO_LINGER should use a native binding outside the framework. This
+// stub stays in the export with throw-on-call so a future Node release
+// that exposes setLinger can be wired without an API addition.
+function _setSocketLinger(_opts) {
+  throw new NetworkError("socket/linger-not-supported",
+    "socket.setDefaultLinger: SO_LINGER is not exposed by Node's public net.Socket API " +
+    "(see nodejs/node#27293). Use socket.destroy() (abort) vs socket.end() (graceful) " +
+    "to control close semantics, or a native binding if true SO_LINGER is required.");
+}
+
+function _socketDefaults() {
+  return {
+    noDelay:                 SOCKET_DEFAULTS.noDelay,
+    keepAlive:               SOCKET_DEFAULTS.keepAlive,
+    keepAliveInitialDelayMs: SOCKET_DEFAULTS.keepAliveInitialDelayMs,
+  };
+}
+
+function applyToSocket(socket) {
+  if (!socket) return socket;
+  try {
+    if (typeof socket.setNoDelay === "function") socket.setNoDelay(SOCKET_DEFAULTS.noDelay);
+    if (typeof socket.setKeepAlive === "function") {
+      socket.setKeepAlive(SOCKET_DEFAULTS.keepAlive, SOCKET_DEFAULTS.keepAliveInitialDelayMs || 0);
+    }
+  } catch (_e) {}
+  return socket;
+}
+
+var ntpFacade = {
+  querySingle:    ntpCheck.querySingle,
+  checkDrift:     ntpCheck.checkDrift,
+  bootCheck:      ntpCheck.bootCheck,
+  setThresholds:  ntpCheck.setThresholds,
+  getThresholds:  ntpCheck.getThresholds,
+  setServers:     function (list) {
+    if (!Array.isArray(list) || list.length === 0) {
+      throw new NetworkError("ntp/bad-servers", "ntp.setServers: expected non-empty array");
+    }
+    ntpFacade._defaultServers = list.slice();
+    _emitObs("network.ntp.servers.set", { count: list.length });
+  },
+  getServers:     function () {
+    return (ntpFacade._defaultServers || ntpCheck.DEFAULT_SERVERS).slice();
+  },
+  _defaultServers: null,
+  nts:            nts,
+};
+
+function bootFromEnv(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["env", "audit"], "network.bootFromEnv");
+  var env = opts.env || process.env;
+  var applied = { ntp: {}, dns: {}, proxy: false, tls: {}, heartbeat: 0, socket: {} };
+
+  if (env.BLAMEJS_NTP_SERVERS) {
+    var list = String(env.BLAMEJS_NTP_SERVERS).split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+    if (list.length > 0) { ntpFacade.setServers(list); applied.ntp.servers = list.length; }
+  }
+  var ntpTimeout = env.BLAMEJS_NTP_TIMEOUT_MS;
+  if (ntpTimeout) {
+    var t = parseInt(ntpTimeout, 10);
+    if (isFinite(t) && t > 0) { ntpFacade._defaultTimeoutMs = t; applied.ntp.timeoutMs = t; }
+  }
+  var ntpWarn = env.BLAMEJS_NTP_DRIFT_WARN_MS;
+  var ntpFatal = env.BLAMEJS_NTP_DRIFT_FATAL_MS;
+  if (ntpWarn || ntpFatal) {
+    var thr = {};
+    if (ntpWarn)  { thr.warnMs  = parseInt(ntpWarn, 10);  applied.ntp.warnMs  = thr.warnMs; }
+    if (ntpFatal) { thr.fatalMs = parseInt(ntpFatal, 10); applied.ntp.fatalMs = thr.fatalMs; }
+    ntpCheck.setThresholds(thr);
+  }
+
+  var dnsServers = env.BLAMEJS_DNS_SERVERS;
+  if (dnsServers) {
+    var dl = String(dnsServers).split(",").map(function (s) { return s.trim(); }).filter(Boolean);
+    if (dl.length > 0) { dns.setServers(dl); applied.dns.servers = dl.length; }
+  }
+  if (env.BLAMEJS_DNS_RESULT_ORDER)  { dns.setResultOrder(env.BLAMEJS_DNS_RESULT_ORDER); applied.dns.resultOrder = env.BLAMEJS_DNS_RESULT_ORDER; }
+  if (env.BLAMEJS_DNS_FAMILY)        { dns.setFamily(parseInt(env.BLAMEJS_DNS_FAMILY, 10)); applied.dns.family = parseInt(env.BLAMEJS_DNS_FAMILY, 10); }
+  if (env.BLAMEJS_DNS_LOOKUP_TIMEOUT_MS) { dns.setLookupTimeoutMs(parseInt(env.BLAMEJS_DNS_LOOKUP_TIMEOUT_MS, 10)); applied.dns.lookupTimeoutMs = parseInt(env.BLAMEJS_DNS_LOOKUP_TIMEOUT_MS, 10); }
+  if (env.BLAMEJS_DNS_CACHE_TTL_MS)      { dns.setCacheTtlMs(parseInt(env.BLAMEJS_DNS_CACHE_TTL_MS, 10)); applied.dns.cacheTtlMs = parseInt(env.BLAMEJS_DNS_CACHE_TTL_MS, 10); }
+  if (env.BLAMEJS_DOH_URL)               { dns.useDnsOverHttps({ url: env.BLAMEJS_DOH_URL }); applied.dns.doh = env.BLAMEJS_DOH_URL; }
+  else if (env.BLAMEJS_DOH_PROVIDER)     { dns.useDnsOverHttps({ provider: env.BLAMEJS_DOH_PROVIDER }); applied.dns.dohProvider = env.BLAMEJS_DOH_PROVIDER; }
+  if (env.BLAMEJS_DOT_HOST)              { dns.useDnsOverTls({ host: env.BLAMEJS_DOT_HOST, port: env.BLAMEJS_DOT_PORT ? parseInt(env.BLAMEJS_DOT_PORT, 10) : 853 }); applied.dns.dot = env.BLAMEJS_DOT_HOST; }
+
+  if (env.HTTP_PROXY || env.http_proxy || env.HTTPS_PROXY || env.https_proxy ||
+      env.NO_PROXY  || env.no_proxy  || env.ALL_PROXY    || env.all_proxy) {
+    applied.proxy = proxy.fromEnv(env);
+  }
+
+  if (env.BLAMEJS_EXTRA_CA_CERTS) {
+    trust.addCa(env.BLAMEJS_EXTRA_CA_CERTS, { label: "BLAMEJS_EXTRA_CA_CERTS" });
+    applied.tls.fileLoaded = env.BLAMEJS_EXTRA_CA_CERTS;
+  }
+  if (env.BLAMEJS_EXTRA_CA_CERTS_DIR) {
+    trust.addCaBundle(env.BLAMEJS_EXTRA_CA_CERTS_DIR, { label: "BLAMEJS_EXTRA_CA_CERTS_DIR" });
+    applied.tls.dirLoaded = env.BLAMEJS_EXTRA_CA_CERTS_DIR;
+  }
+  if (env.BLAMEJS_USE_SYSTEM_TRUST === "1" || env.BLAMEJS_USE_SYSTEM_TRUST === "true") {
+    trust.useSystemTrust(true);
+    applied.tls.systemTrust = true;
+  }
+
+  if (env.BLAMEJS_SOCKET_NO_DELAY)             _setSocketNoDelay(env.BLAMEJS_SOCKET_NO_DELAY === "1" || env.BLAMEJS_SOCKET_NO_DELAY === "true");
+  if (env.BLAMEJS_SOCKET_KEEPALIVE)            _setSocketKeepAlive({ enable: env.BLAMEJS_SOCKET_KEEPALIVE === "1" || env.BLAMEJS_SOCKET_KEEPALIVE === "true" });
+  if (env.BLAMEJS_SOCKET_KEEPALIVE_DELAY_MS)   _setSocketKeepAlive({ initialDelayMs: parseInt(env.BLAMEJS_SOCKET_KEEPALIVE_DELAY_MS, 10) });
+  applied.socket = _socketDefaults();
+
+  var auditOn = opts.audit !== false;
+  if (auditOn) {
+    var sink;
+    try { sink = audit(); } catch (_e) { sink = null; }
+    if (sink && typeof sink.safeEmit === "function") {
+      try {
+        sink.safeEmit({
+          action:   "network.boot.from_env",
+          outcome:  "success",
+          metadata: applied,
+        });
+      } catch (_e) {}
+    }
+  }
+  _emitObs("network.boot.from_env", { source: "env" });
+  return applied;
+}
+
+function snapshot() {
+  return {
+    ntp: {
+      servers:     ntpFacade.getServers(),
+      thresholds:  ntpCheck.getThresholds(),
+    },
+    dns: dns._stateForTest(),
+    proxy: proxy.snapshot(),
+    tls:  {
+      systemTrust: trust.isSystemTrustEnabled(),
+      caCount:     trust.getTrustStore().length,
+    },
+    heartbeat: heartbeat.statuses(),
+    socket: _socketDefaults(),
+  };
+}
+
+function _emitObs(name, fields) {
+  try { observability().emit(name, fields || {}); } catch (_e) {}
+}
+
+function _resetForTest() {
+  ntpFacade._defaultServers = null;
+  ntpFacade._defaultTimeoutMs = null;
+  if (typeof ntpCheck._resetThresholdsForTest === "function") ntpCheck._resetThresholdsForTest();
+  dns._resetForTest();
+  proxy._resetForTest();
+  trust._resetForTest();
+  heartbeat._resetForTest();
+  SOCKET_DEFAULTS.noDelay = true;
+  SOCKET_DEFAULTS.keepAlive = true;
+  SOCKET_DEFAULTS.keepAliveInitialDelayMs = 0;
+}
+
+module.exports = {
+  ntp:        ntpFacade,
+  dns:        dns,
+  proxy:      proxy,
+  tls:        trust,
+  heartbeat:  heartbeat,
+  socket: {
+    setDefaultNoDelay:   _setSocketNoDelay,
+    setDefaultKeepAlive: _setSocketKeepAlive,
+    setDefaultLinger:    _setSocketLinger,
+    defaults:            _socketDefaults,
+    applyToSocket:       applyToSocket,
+  },
+  bootFromEnv:    bootFromEnv,
+  snapshot:       snapshot,
+  NetworkError:   NetworkError,
+  _resetForTest:  _resetForTest,
+};

package/lib/ntp-check.js

@@ -36,6 +36,43 @@ var DEFAULT_SERVERS = ["pool.ntp.org", "time.cloudflare.com"];
 var DEFAULT_PORT    = 123;
 var DEFAULT_TIMEOUT_MS = 3000;
 
+var DEFAULT_DRIFT_WARN_MS  = C.TIME.minutes(5);
+var DEFAULT_DRIFT_FATAL_MS = C.TIME.hours(1);
+
+var thresholds = {
+  warnMs:  DEFAULT_DRIFT_WARN_MS,
+  fatalMs: DEFAULT_DRIFT_FATAL_MS,
+};
+
+function setThresholds(opts) {
+  opts = opts || {};
+  if (opts.warnMs !== undefined) {
+    if (typeof opts.warnMs !== "number" || !isFinite(opts.warnMs) || opts.warnMs < 0) {
+      throw new TypeError("ntpCheck.setThresholds: warnMs must be non-negative finite number, got " + JSON.stringify(opts.warnMs));
+    }
+    thresholds.warnMs = opts.warnMs;
+  }
+  if (opts.fatalMs !== undefined) {
+    if (typeof opts.fatalMs !== "number" || !isFinite(opts.fatalMs) || opts.fatalMs < 0) {
+      throw new TypeError("ntpCheck.setThresholds: fatalMs must be non-negative finite number, got " + JSON.stringify(opts.fatalMs));
+    }
+    thresholds.fatalMs = opts.fatalMs;
+  }
+  if (thresholds.warnMs > thresholds.fatalMs && thresholds.fatalMs > 0) {
+    throw new RangeError("ntpCheck.setThresholds: warnMs (" + thresholds.warnMs +
+      ") must be <= fatalMs (" + thresholds.fatalMs + ")");
+  }
+}
+
+function getThresholds() {
+  return { warnMs: thresholds.warnMs, fatalMs: thresholds.fatalMs };
+}
+
+function _resetThresholdsForTest() {
+  thresholds.warnMs  = DEFAULT_DRIFT_WARN_MS;
+  thresholds.fatalMs = DEFAULT_DRIFT_FATAL_MS;
+}
+
 /**
  * Query an NTP server once. Resolves with { driftMs, serverTimeMs } or
  * rejects with { code, message } where code is one of:
@@ -142,22 +179,26 @@ async function bootCheck(opts) {
   }
   var absMs = Math.abs(result.driftMs);
   var driftStr = (result.driftMs >= 0 ? "+" : "") + result.driftMs + "ms";
-  if (absMs >= C.TIME.hours(1)) {
+  var fatalMs = (opts && typeof opts.driftFatalMs === "number") ? opts.driftFatalMs : thresholds.fatalMs;
+  var warnMs  = (opts && typeof opts.driftWarnMs  === "number") ? opts.driftWarnMs  : thresholds.warnMs;
+  if (fatalMs > 0 && absMs >= fatalMs) {
     return {
       ok:       false,
       severity: "fatal",
       driftMs:  result.driftMs,
       server:   result.server,
-      message:  "clock drift " + driftStr + " from " + result.server + " (>= 1 hour) — refuse to boot",
+      message:  "clock drift " + driftStr + " from " + result.server +
+                " (>= " + fatalMs + "ms) — refuse to boot",
     };
   }
-  if (absMs >= C.TIME.minutes(5)) {
+  if (warnMs > 0 && absMs >= warnMs) {
     return {
       ok:       true,
       severity: "warning",
       driftMs:  result.driftMs,
       server:   result.server,
-      message:  "clock drift " + driftStr + " from " + result.server + " (>= 5 minutes) — investigate",
+      message:  "clock drift " + driftStr + " from " + result.server +
+                " (>= " + warnMs + "ms) — investigate",
     };
   }
   return {
@@ -173,6 +214,11 @@ module.exports = {
   querySingle:               querySingle,
   checkDrift:                checkDrift,
   bootCheck:                 bootCheck,
+  setThresholds:             setThresholds,
+  getThresholds:             getThresholds,
   DEFAULT_SERVERS:           DEFAULT_SERVERS,
+  DEFAULT_DRIFT_WARN_MS:     DEFAULT_DRIFT_WARN_MS,
+  DEFAULT_DRIFT_FATAL_MS:    DEFAULT_DRIFT_FATAL_MS,
   NTP_TO_UNIX_OFFSET_SECONDS: NTP_TO_UNIX_OFFSET_SECONDS,
+  _resetThresholdsForTest:   _resetThresholdsForTest,
 };

package/lib/object-store/azure-blob.js

@@ -400,49 +400,23 @@ function create(config) {
   function presignedUploadUrl(opts)   { return _presign("PUT", "cw", opts); }
   function presignedDownloadUrl(opts) { return _presign("GET", "r",  opts); }
 
-  // Azure SAS doesn't support an equivalent of S3 / GCS POST policy
-  // with a content-length-range constraint. The SAS spec carries
-  // permissions / start / expiry / IP / protocol / resource-content-
-  // headers but no body-size cap — Azure validates the upload at the
-  // service level only via the operator's optional Block Blob size
-  // limit applied at storage-account or container scope, not via the
-  // SAS token itself.
+  // Azure SAS has no equivalent of S3 / GCS POST policy with a
+  // content-length-range constraint — the SAS spec carries permissions
+  // / start / expiry / IP / protocol / resource-content-headers but
+  // no body-size cap. Returning a PUT URL under the POST-policy name
+  // would be a silent shape mismatch (operators wiring an HTML form
+  // expecting multipart fields get a PUT URL with no fields), so the
+  // azure-blob backend refuses cleanly.
   //
-  // Rather than throw NOT_SUPPORTED, this returns the same SAS PUT
-  // shape as presignedUploadUrl with an `enforcement: 'client-only'`
-  // marker so operators making cross-vendor decisions know the
-  // body-size guard is advisory on Azure and must be enforced on the
-  // client side or via a server-side post-upload check.
-  //
-  // For strict server-side body-size enforcement on Azure, the
-  // canonical pattern is: SAS-authorize the upload, then have the
-  // operator's app issue a HEAD on the resulting blob and delete +
-  // 4xx the requester if Content-Length > opts.maxBytes.
-  function presignedUploadPolicy(opts) {
-    opts = opts || {};
-    if (typeof opts.maxBytes !== "number" || !Number.isFinite(opts.maxBytes) ||
-        opts.maxBytes <= 0) {
-      throw _err("INVALID_MAX_BYTES",
-        "presignedUploadPolicy: maxBytes (positive number of bytes) is required " +
-        "(advisory on Azure — see docstring for server-side enforcement)", true);
-    }
-    var underlying = _presign("PUT", "cw", opts);
-    return {
-      url:           underlying.url,
-      method:        "PUT",
-      // SAS uploads are PUT, not multipart POST — there are no form
-      // fields. Operators uploading attach the body directly to the
-      // returned URL with the headers in `headers`.
-      fields:        null,
-      headers:       underlying.headers,
-      expiresAt:     underlying.expiresAt,
-      maxBytes:      opts.maxBytes,
-      enforcement:   "client-only",
-      enforcementNote:
-        "Azure SAS does not natively cap upload size. Operators needing " +
-        "strict size enforcement must HEAD the blob post-upload and reject " +
-        "if Content-Length exceeds maxBytes.",
-    };
+  // For strict server-side body-size enforcement on Azure: use
+  // presignedUploadUrl + a server-side post-upload HEAD that deletes
+  // and 4xxs the requester if Content-Length > limit.
+  function presignedUploadPolicy(_opts) {
+    throw _err("PRESIGN_NOT_SUPPORTED",
+      "azure-blob backend does not support presigned upload policies — " +
+      "Azure SAS has no body-size cap. Use presignedUploadUrl + a server-side " +
+      "HEAD-and-delete check, or switch to an S3 / GCS-compatible backend.",
+      true);
   }
 
   return {

package/lib/permissions.js

@@ -117,7 +117,8 @@ function _validateScopePattern(scope, ctx) {
 
 function _normalizeRoleEntry(name, entry) {
   if (Array.isArray(entry)) {
-    return { extends: [], permissions: entry.slice(), dbRole: null };
+    return { extends: [], permissions: entry.slice(), dbRole: null,
+      requireMfa: false, mfaWindowMs: null };
   }
   if (entry && typeof entry === "object") {
     var ext = entry.extends || [];
@@ -146,9 +147,19 @@ function _normalizeRoleEntry(name, entry) {
       }
       dbRole = entry.dbRole;
     }
-    return { extends: ext.slice(), permissions: perms.slice(), dbRole: dbRole };
+    var requireMfa = entry.requireMfa === true;
+    var mfaWindowMs = null;
+    if (entry.mfaWindowMs !== undefined && entry.mfaWindowMs !== null) {
+      if (typeof entry.mfaWindowMs !== "number" || !isFinite(entry.mfaWindowMs) || entry.mfaWindowMs <= 0) {
+        throw _err("BAD_ROLE",
+          "role '" + name + "': mfaWindowMs must be a positive finite number");
+      }
+      mfaWindowMs = entry.mfaWindowMs;
+    }
+    return { extends: ext.slice(), permissions: perms.slice(), dbRole: dbRole,
+      requireMfa: requireMfa, mfaWindowMs: mfaWindowMs };
   }
-  throw _err("BAD_ROLE", "role '" + name + "' must be an array of scopes or { extends?, permissions, dbRole? }");
+  throw _err("BAD_ROLE", "role '" + name + "' must be an array of scopes or { extends?, permissions, dbRole?, requireMfa?, mfaWindowMs? }");
 }
 
 function _validateRoles(roles) {
@@ -279,6 +290,33 @@ function create(opts) {
   var missingActorStatus = opts.missingActorStatus || DEFAULTS.missingActorStatus;
   var responder = opts.responder || _defaultResponder;
 
+  // ABAC predicate registry. Each entry: scope-string → async predicate
+  // function (actor, context) → boolean. The middleware evaluates the
+  // predicate AFTER the RBAC scope check passes — so a route protected
+  // by `perms.require("orders.read")` first checks the actor has the
+  // orders:read scope, then (if the scope has a policy registered)
+  // evaluates the predicate with the actor + a per-request context
+  // built by the route's `context` middleware opt. ABAC + RBAC stack
+  // — a route needs to pass BOTH layers when both are configured.
+  var policies = {};
+
+  function policy(scope, predicate) {
+    _validateScopePattern(scope, "permissions.policy");
+    if (typeof predicate !== "function") {
+      throw _err("BAD_OPT", "permissions.policy: predicate must be a function (actor, context) -> bool");
+    }
+    if (policies[scope]) {
+      throw _err("DUPLICATE_POLICY", "permissions.policy: '" + scope + "' is already registered");
+    }
+    policies[scope] = predicate;
+  }
+
+  function _findPolicy(requestedScope) {
+    // Exact match wins; no wildcard expansion (a wildcard policy
+    // gating arbitrary scopes is too easy to misconfigure).
+    return policies[requestedScope] || null;
+  }
+
   function _auditEmit(action, info) {
     if (!audit) return;
     if (info && info.outcome === "success" && !auditSuccess) return;
@@ -332,7 +370,7 @@ function create(opts) {
 
   // Middleware factory. `mode` is "single" | "all" | "any"; `requested`
   // is the scope or scope list. Throw at registration time on bad shape.
-  function _middleware(mode, requested) {
+  function _middleware(mode, requested, mwOpts) {
     if (mode === "single") {
       _validateScopePattern(requested, "permissions.require");
     } else {
@@ -345,7 +383,31 @@ function create(opts) {
       }
     }
 
-    return function permissionsMiddleware(req, res, next) {
+    // Per-route MFA enforcement opts: { requireMfa, mfaWindowMs }.
+    // When set, the middleware blocks unless the actor's mfaAuthenticated
+    // flag is truthy AND (when mfaWindowMs is set) actor.mfaAt is fresher
+    // than (now - mfaWindowMs). The actor signal is operator-set: after
+    // a successful TOTP / passkey step-up, the route handler stamps
+    // req.user.mfaAuthenticated = true and req.user.mfaAt = Date.now().
+    mwOpts = mwOpts || {};
+    var routeRequireMfa  = mwOpts.requireMfa === true;
+    var routeMfaWindowMs = null;
+    if (mwOpts.mfaWindowMs !== undefined && mwOpts.mfaWindowMs !== null) {
+      if (typeof mwOpts.mfaWindowMs !== "number" || !isFinite(mwOpts.mfaWindowMs) || mwOpts.mfaWindowMs <= 0) {
+        throw _err("BAD_OPT", "permissions middleware: mfaWindowMs must be a positive finite number");
+      }
+      routeMfaWindowMs = mwOpts.mfaWindowMs;
+    }
+    // ABAC context provider — operator-supplied function (req)→object.
+    // The function runs once per request, AFTER scope/MFA pass, BEFORE
+    // the policy predicate. Whatever it returns is passed to the
+    // policy as `context`. Async functions are awaited.
+    var contextProvider = mwOpts.context;
+    if (contextProvider !== undefined && typeof contextProvider !== "function") {
+      throw _err("BAD_OPT", "permissions middleware: context must be a function (req) -> object");
+    }
+
+    return async function permissionsMiddleware(req, res, next) {
       var actor = resolver(req);
       if (!actor) {
         // Diagnostic: the most common cause of a null actor is that
@@ -392,13 +454,164 @@ function create(opts) {
         });
       }
 
+      // MFA enforcement gate. Two sources of "this needs MFA":
+      //   1. Per-route opt: perms.require("scope", { requireMfa: true })
+      //   2. Per-role flag: a role spec with requireMfa:true that
+      //      contributes to satisfying the requested scope
+      // Either source enabling MFA forces the gate. mfaWindowMs (per-route
+      // OR per-role, route wins on conflict) bounds freshness — without
+      // it, ANY past MFA stamp counts (which is too permissive for high-
+      // value routes; operators set a window like C.TIME.minutes(15)).
+      var enforceMfa = routeRequireMfa;
+      var enforceWindowMs = routeMfaWindowMs;
+      if (!enforceMfa) {
+        // Walk the actor's roles and check whether any role with
+        // requireMfa=true contributes a permission that matches the
+        // requested scope. If so, MFA is required regardless of the
+        // route-level opt.
+        var actorRoles = Array.isArray(actor.roles) ? actor.roles : [];
+        for (var ri = 0; ri < actorRoles.length; ri++) {
+          var rname = actorRoles[ri];
+          if (typeof rname !== "string") continue;
+          var rspec = roleTable[rname];
+          if (!rspec || !rspec.requireMfa) continue;
+          // Cheap match: if the role grants any scope that satisfies the
+          // requested scope (single mode) or any of the requested
+          // (all/any modes), MFA is required for this route.
+          var visited = new Set();
+          var roleScopes = [];
+          _expandOne(rname, roleTable, visited, roleScopes);
+          var roleMatches = false;
+          var requestedList = mode === "single" ? [requested] : requested;
+          outer: for (var rj = 0; rj < roleScopes.length; rj++) {
+            for (var rk = 0; rk < requestedList.length; rk++) {
+              if (match(roleScopes[rj], requestedList[rk])) {
+                roleMatches = true; break outer;
+              }
+            }
+          }
+          if (roleMatches) {
+            enforceMfa = true;
+            if (enforceWindowMs === null && rspec.mfaWindowMs !== null) {
+              enforceWindowMs = rspec.mfaWindowMs;
+            }
+          }
+        }
+      }
+
+      if (enforceMfa) {
+        var mfaOk = actor.mfaAuthenticated === true;
+        if (mfaOk && enforceWindowMs !== null) {
+          var mfaAt = typeof actor.mfaAt === "number" ? actor.mfaAt : 0;
+          if (Date.now() - mfaAt > enforceWindowMs) {
+            mfaOk = false;
+          }
+        }
+        if (!mfaOk) {
+          _emitEvent("permissions.mfa_required", 1,
+            { requested: _labelize(requested), mode: mode });
+          _auditEmit("permissions.mfa.required", {
+            actor:    _actorAuditShape(actor, req),
+            resource: { kind: "permission", id: _labelize(requested) },
+            outcome:  "denied",
+            reason:   "mfa-required",
+            metadata: { mode: mode, windowMs: enforceWindowMs },
+          });
+          return responder(req, res, denyStatus, {
+            error:     "mfa_required",
+            status:    denyStatus,
+            requested: _labelize(requested),
+          });
+        }
+      }
+
+      // ABAC layer fires for every requested scope that has a
+      // registered policy predicate. Single-mode evaluates the one
+      // scope; requireAll evaluates each scope's policy (every must
+      // pass); requireAny evaluates only the policies on scopes the
+      // actor's RBAC layer satisfied (so a failing policy on a scope
+      // the actor doesn't even hold doesn't leak the policy's
+      // existence). Each predicate failure short-circuits with a
+      // policy.deny audit row naming the failing scope.
+      var policyTargets = [];
+      if (mode === "single" && _findPolicy(requested)) {
+        policyTargets.push(requested);
+      } else if (mode === "all" || mode === "any") {
+        for (var pi = 0; pi < requested.length; pi++) {
+          if (_findPolicy(requested[pi])) {
+            if (mode === "any" && !check(actor, requested[pi])) continue;
+            policyTargets.push(requested[pi]);
+          }
+        }
+      }
+      if (policyTargets.length > 0) {
+        var policyContext = null;
+        if (contextProvider) {
+          try {
+            policyContext = await contextProvider(req);
+          } catch (e) {
+            _emitEvent("permissions.policy_context_error", 1,
+              { requested: _labelize(requested) });
+            _auditEmit("permissions.policy.error", {
+              actor:    _actorAuditShape(actor, req),
+              resource: { kind: "permission", id: _labelize(requested) },
+              outcome:  "failure",
+              reason:   "context-provider-threw",
+              metadata: { error: (e && e.message) || String(e), mode: mode },
+            });
+            return responder(req, res, denyStatus, {
+              error:     "policy_context_error",
+              status:    denyStatus,
+              requested: _labelize(requested),
+            });
+          }
+        }
+        for (var pti = 0; pti < policyTargets.length; pti++) {
+          var thisScope = policyTargets[pti];
+          var pred = _findPolicy(thisScope);
+          var verdict;
+          try {
+            verdict = await pred(actor, policyContext);
+          } catch (e2) {
+            _emitEvent("permissions.policy_error", 1, { requested: thisScope });
+            _auditEmit("permissions.policy.error", {
+              actor:    _actorAuditShape(actor, req),
+              resource: { kind: "permission", id: thisScope },
+              outcome:  "failure",
+              reason:   "predicate-threw",
+              metadata: { error: (e2 && e2.message) || String(e2), mode: mode },
+            });
+            return responder(req, res, denyStatus, {
+              error:     "policy_error",
+              status:    denyStatus,
+              requested: thisScope,
+            });
+          }
+          if (verdict !== true) {
+            _emitEvent("permissions.policy_denied", 1, { requested: thisScope });
+            _auditEmit("permissions.policy.deny", {
+              actor:    _actorAuditShape(actor, req),
+              resource: { kind: "permission", id: thisScope },
+              outcome:  "failure",
+              reason:   "policy-predicate-returned-falsy",
+              metadata: { mode: mode, scopeIndex: pti },
+            });
+            return responder(req, res, denyStatus, {
+              error:     "policy_denied",
+              status:    denyStatus,
+              requested: thisScope,
+            });
+          }
+        }
+      }
+
       _emitEvent("permissions.check", 1,
         { outcome: "success", mode: mode });
       _auditEmit("permissions.check.success", {
         actor:    _actorAuditShape(actor, req),
         resource: { kind: "permission", id: _labelize(requested) },
         outcome:  "success",
-        metadata: { mode: mode },
+        metadata: { mode: mode, mfaEnforced: enforceMfa },
       });
       next();
     };
@@ -443,9 +656,10 @@ function create(opts) {
   }
 
   return {
-    require:    function (scope)  { return _middleware("single", scope); },
-    requireAll: function (scopes) { return _middleware("all",    scopes); },
-    requireAny: function (scopes) { return _middleware("any",    scopes); },
+    require:    function (scope, mwOpts)  { return _middleware("single", scope,  mwOpts); },
+    requireAll: function (scopes, mwOpts) { return _middleware("all",    scopes, mwOpts); },
+    requireAny: function (scopes, mwOpts) { return _middleware("any",    scopes, mwOpts); },
+    policy:     policy,
     check:      check,
     checkAll:   checkAll,
     checkAny:   checkAny,