@blamejs/core 0.6.13 → 0.6.21

package/lib/parsers/index.js

@@ -42,19 +42,33 @@
  *           opted in. Dev-tooling — production secrets should still
  *           come through the operator's secrets-management; this is
  *           the local-development convenience.
- *   ini  — Windows .ini files (rare today; lower priority)
+ *   ini  — INI / .gitconfig / systemd-unit / php.ini / tox.ini parser.
+ *           Sections (incl. [parent.child] / [parent "child"] nesting),
+ *           ; or # comments (inline + leading), single + double quoting
+ *           with \n / \t / \\ / \" / \' escapes, boolean coercion
+ *           (true/false/yes/no/on/off), decimal + hex integers + floats.
+ *           Prototype-pollution defense (__proto__/constructor/prototype
+ *           rejected); duplicate-key policy throws by default
+ *           (onDuplicate: "first"|"last" opts in to silent
+ *           shadowing); section + per-section key + value-bytes
+ *           caps configurable via opts.
  *
  * Public API:
  *   parsers.xml.parse(input, opts?)              → object
+ *   parsers.ini.parse(input, opts?)              → object
+ *   parsers.toml.parse(input, opts?)             → object
+ *   parsers.yaml.parse(input, opts?)             → object
+ *   parsers.env.load(filepath, opts?)            → { values, diff }
  *
  * (CSV moved to top-level `b.csv` in v0.5.17 — same surface unified.)
  *
  * Error types: each parser exports its own *SafeError class with .code
- * matching the format (xml/..., toml/...).
+ * matching the format (xml/..., toml/..., ini/..., yaml/..., env/...).
  */
 module.exports = {
   xml:  require("./safe-xml"),
   toml: require("./safe-toml"),
   yaml: require("./safe-yaml"),
   env:  require("./safe-env"),
+  ini:  require("./safe-ini"),
 };

package/lib/parsers/safe-ini.js

@@ -0,0 +1,273 @@
+"use strict";
+/**
+ * INI parser — same security defaults as the framework's other parsers.
+ *
+ * INI is the Windows config-file format (also used by systemd unit
+ * files, .gitconfig, php.ini, tox.ini, and a long tail of operator
+ * tooling). The format has no formal spec — we implement the
+ * widely-compatible subset:
+ *
+ *   - Sections:        [section-name]                     -> object key
+ *   - Subsections:     [parent.child] / [parent "child"]  -> nested object
+ *   - Key-value:       key = value  /  key: value
+ *   - Comments:        ; or # at the start of a line, or after a value
+ *   - Quoted values:   "double" / 'single' (escapes: \\ \" \' \n \t)
+ *   - Booleans:        true/false/yes/no/on/off (case-insensitive)
+ *   - Numbers:         decimal integers + floats; hex (0xABCD)
+ *
+ * Security defaults:
+ *   - maxBytes:        1 MiB (operator override via opts.maxBytes)
+ *   - maxSections:     500 (depth + breadth limit)
+ *   - maxKeysPerSection: 1000
+ *   - maxValueBytes:   64 KiB
+ *   - prototype-pollution: keys named __proto__, constructor, prototype
+ *     are rejected (would otherwise let an attacker poison Object.prototype
+ *     when a downstream consumer uses bracket access)
+ *   - Duplicate-key policy: opts.onDuplicate = "throw" (default) | "first" | "last".
+ *     Silent overwrite (the bare-INI default) is OFF — operators almost
+ *     never want a config error to silently shadow earlier values.
+ *
+ * Public API:
+ *   parsers.ini.parse(input, opts?)   -> object
+ *   parsers.ini.IniSafeError          (with .code matching ini/...)
+ *
+ * Validation tier: A (config-time throw) — every malformed input
+ * surfaces at parse time, never silently coerces to a usable shape.
+ */
+
+var { defineClass } = require("../framework-error");
+
+var IniSafeError = defineClass("IniSafeError", { alwaysPermanent: true });
+
+var DEFAULT_MAX_BYTES         = 1024 * 1024;
+var DEFAULT_MAX_SECTIONS      = 500;
+var DEFAULT_MAX_KEYS_SECTION  = 1000;
+var DEFAULT_MAX_VALUE_BYTES   = 64 * 1024;
+
+var FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+var TRUE_VALUES  = new Set(["true", "yes", "on"]);
+var FALSE_VALUES = new Set(["false", "no", "off"]);
+
+function _err(code, message) { return new IniSafeError(code, message); }
+
+function _stripComment(line) {
+  var inSingle = false, inDouble = false, escape = false;
+  for (var i = 0; i < line.length; i++) {
+    var c = line.charAt(i);
+    if (escape) { escape = false; continue; }
+    if (c === "\\" && (inSingle || inDouble)) { escape = true; continue; }
+    if (c === "\"" && !inSingle) { inDouble = !inDouble; continue; }
+    if (c === "'"  && !inDouble) { inSingle = !inSingle; continue; }
+    if (!inSingle && !inDouble && (c === ";" || c === "#")) {
+      if (i === 0 || /\s/.test(line.charAt(i - 1))) {
+        return line.slice(0, i);
+      }
+    }
+  }
+  return line;
+}
+
+function _unquote(raw) {
+  var s = raw.trim();
+  if (s.length === 0) return s;
+  var first = s.charAt(0), last = s.charAt(s.length - 1);
+  if ((first === "\"" && last === "\"") || (first === "'" && last === "'")) {
+    if (s.length < 2) {
+      throw _err("ini/bad-quote", "unbalanced quote in value: " + JSON.stringify(s));
+    }
+    var inner = s.slice(1, -1);
+    var out = "";
+    var i = 0;
+    while (i < inner.length) {
+      var c = inner.charAt(i);
+      if (c === "\\" && i + 1 < inner.length) {
+        var next = inner.charAt(i + 1);
+        if (next === "\\")      out += "\\";
+        else if (next === "n")  out += "\n";
+        else if (next === "t")  out += "\t";
+        else if (next === "r")  out += "\r";
+        else if (next === "\"") out += "\"";
+        else if (next === "'")  out += "'";
+        else throw _err("ini/bad-escape", "unknown escape sequence \\" + next);
+        i += 2;
+      } else {
+        out += c;
+        i += 1;
+      }
+    }
+    return out;
+  }
+  return s;
+}
+
+function _coerceValue(raw) {
+  if (raw.length === 0) return raw;
+  var first = raw.charAt(0);
+  if (first === "\"" || first === "'") return _unquote(raw);
+  var lower = raw.toLowerCase();
+  if (TRUE_VALUES.has(lower))  return true;
+  if (FALSE_VALUES.has(lower)) return false;
+  if (/^0x[0-9a-f]+$/i.test(raw)) {
+    var hex = parseInt(raw, 16);
+    if (!Number.isSafeInteger(hex)) {
+      throw _err("ini/value-out-of-range", "hex integer exceeds safe-integer range: " + raw);
+    }
+    return hex;
+  }
+  if (/^-?\d+$/.test(raw)) {
+    var n = Number(raw);
+    if (!Number.isSafeInteger(n)) {
+      throw _err("ini/value-out-of-range", "integer exceeds safe-integer range: " + raw);
+    }
+    return n;
+  }
+  if (/^-?\d+\.\d+([eE][+-]?\d+)?$/.test(raw) || /^-?\d+[eE][+-]?\d+$/.test(raw)) {
+    return Number(raw);
+  }
+  return _unquote(raw);
+}
+
+function _validateKey(name) {
+  if (FORBIDDEN_KEYS.has(name)) {
+    throw _err("ini/forbidden-key", "key '" + name + "' is reserved (prototype pollution defense)");
+  }
+}
+
+function _ensureSection(root, sectionPath) {
+  if (sectionPath.length === 0) return root;
+  var node = root;
+  for (var i = 0; i < sectionPath.length; i++) {
+    var seg = sectionPath[i];
+    _validateKey(seg);
+    if (Object.prototype.hasOwnProperty.call(node, seg)) {
+      var existing = node[seg];
+      if (typeof existing !== "object" || existing === null || Array.isArray(existing)) {
+        throw _err("ini/section-conflict",
+          "section path [" + sectionPath.join(".") + "] collides with existing scalar at '" + seg + "'");
+      }
+      node = existing;
+    } else {
+      var child = {};
+      node[seg] = child;
+      node = child;
+    }
+  }
+  return node;
+}
+
+function _parseSectionHeader(line) {
+  var inner = line.slice(1, line.lastIndexOf("]")).trim();
+  if (inner.length === 0) {
+    throw _err("ini/empty-section", "section header [] has no name");
+  }
+  var quotedMatch = /^([A-Za-z0-9._-]+)\s+"([^"\\]*(?:\\.[^"\\]*)*)"$/.exec(inner);
+  if (quotedMatch) {
+    return [quotedMatch[1], quotedMatch[2]];
+  }
+  var parts = inner.split(".");
+  for (var i = 0; i < parts.length; i++) {
+    if (parts[i].length === 0) {
+      throw _err("ini/bad-section", "section name has empty segment: " + JSON.stringify(inner));
+    }
+    if (!/^[A-Za-z0-9_-]+$/.test(parts[i])) {
+      throw _err("ini/bad-section",
+        "section segment must match [A-Za-z0-9_-]+ (got " + JSON.stringify(parts[i]) + ")");
+    }
+  }
+  return parts;
+}
+
+function parse(input, opts) {
+  opts = opts || {};
+  var maxBytes        = opts.maxBytes        || DEFAULT_MAX_BYTES;
+  var maxSections     = opts.maxSections     || DEFAULT_MAX_SECTIONS;
+  var maxKeysPerSect  = opts.maxKeysPerSection || DEFAULT_MAX_KEYS_SECTION;
+  var maxValueBytes   = opts.maxValueBytes   || DEFAULT_MAX_VALUE_BYTES;
+  var onDuplicate     = opts.onDuplicate     || "throw";
+
+  if (typeof input !== "string") {
+    throw _err("ini/bad-input", "ini.parse: input must be a string, got " + typeof input);
+  }
+  if (Buffer.byteLength(input, "utf8") > maxBytes) {
+    throw _err("ini/too-large",
+      "ini.parse: input exceeds " + maxBytes + " bytes");
+  }
+  if (onDuplicate !== "throw" && onDuplicate !== "first" && onDuplicate !== "last") {
+    throw _err("ini/bad-opt",
+      "ini.parse: onDuplicate must be 'throw' | 'first' | 'last', got " + JSON.stringify(onDuplicate));
+  }
+
+  var root = {};
+  var currentSectionPath = [];
+  var currentSection = root;
+  var sectionCount = 0;
+  var keysInCurrentSection = 0;
+
+  var lines = input.split(/\r?\n/);
+  for (var li = 0; li < lines.length; li++) {
+    var raw = lines[li];
+    var stripped = _stripComment(raw).trim();
+    if (stripped.length === 0) continue;
+
+    if (stripped.charAt(0) === "[") {
+      if (stripped.charAt(stripped.length - 1) !== "]") {
+        throw _err("ini/bad-section", "section header at line " + (li + 1) + " missing closing ']'");
+      }
+      sectionCount += 1;
+      if (sectionCount > maxSections) {
+        throw _err("ini/too-many-sections",
+          "ini.parse: section count exceeds " + maxSections);
+      }
+      currentSectionPath = _parseSectionHeader(stripped);
+      currentSection = _ensureSection(root, currentSectionPath);
+      keysInCurrentSection = 0;
+      continue;
+    }
+
+    var eqIdx = stripped.indexOf("=");
+    var coIdx = stripped.indexOf(":");
+    var sepIdx;
+    if (eqIdx === -1) sepIdx = coIdx;
+    else if (coIdx === -1) sepIdx = eqIdx;
+    else sepIdx = Math.min(eqIdx, coIdx);
+    if (sepIdx === -1) {
+      throw _err("ini/bad-line",
+        "line " + (li + 1) + " is neither blank nor key=value: " + JSON.stringify(stripped));
+    }
+
+    var key = stripped.slice(0, sepIdx).trim();
+    var valueRaw = stripped.slice(sepIdx + 1).trim();
+    if (key.length === 0) {
+      throw _err("ini/empty-key", "line " + (li + 1) + " has empty key");
+    }
+    _validateKey(key);
+    if (Buffer.byteLength(valueRaw, "utf8") > maxValueBytes) {
+      throw _err("ini/value-too-large",
+        "line " + (li + 1) + " value exceeds " + maxValueBytes + " bytes");
+    }
+    keysInCurrentSection += 1;
+    if (keysInCurrentSection > maxKeysPerSect) {
+      throw _err("ini/too-many-keys",
+        "section [" + currentSectionPath.join(".") + "] exceeds " + maxKeysPerSect + " keys");
+    }
+    var value = _coerceValue(valueRaw);
+
+    if (Object.prototype.hasOwnProperty.call(currentSection, key)) {
+      if (onDuplicate === "throw") {
+        throw _err("ini/duplicate-key",
+          "section [" + currentSectionPath.join(".") + "] redefines key '" + key + "' " +
+          "(opt onDuplicate:'first' or 'last' to allow)");
+      }
+      if (onDuplicate === "first") continue;
+    }
+    currentSection[key] = value;
+  }
+
+  return root;
+}
+
+module.exports = {
+  parse:        parse,
+  IniSafeError: IniSafeError,
+};

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,

package/lib/pqc-agent.js

@@ -31,6 +31,7 @@
 var https = require("node:https");
 var http  = require("node:http");
 var C = require("./constants");
+var networkTls = require("./network-tls");
 
 // Defaults for connection pooling. These ARE overridable via opts —
 // only the cryptographic posture (ecdhCurve / minVersion) is locked.
@@ -45,12 +46,11 @@ var DEFAULT_OPTS = {
 function _buildAgentOpts(opts) {
   opts = opts || {};
   var merged = Object.assign({}, DEFAULT_OPTS, opts);
-  // Cryptographic posture cannot be relaxed via opts. Even if the
-  // operator passes ecdhCurve: 'P-256' or minVersion: 'TLSv1.2', the
-  // framework defaults win. This is deliberate: the primitive's whole
-  // value is that you can't accidentally ship a downgraded agent.
   merged.ecdhCurve  = C.TLS_GROUP_CURVE_STR;
   merged.minVersion = "TLSv1.3";
+  if (networkTls && typeof networkTls.applyToContext === "function") {
+    merged = networkTls.applyToContext({ base: merged });
+  }
   return merged;
 }