@blamejs/core 0.14.5 → 0.14.7

package/lib/middleware/rate-limit.js

@@ -62,6 +62,7 @@ var requestHelpers = require("../request-helpers");
 var safeAsync = require("../safe-async");
 var validateOpts = require("../validate-opts");
 var clusterStorage = require("../cluster-storage");
+var denyResponse = require("./deny-response").denyResponse;
 
 var audit  = lazyRequire(function () { return require("../audit"); });
 var logger = lazyRequire(function () { return require("../log").boot("rate-limit"); });
@@ -363,6 +364,8 @@ function _resolveBackend(opts) {
  *     keyFn:           function(req): string,
  *     statusOnLimit:   number,           // default 429
  *     bodyOnLimit:     string,           // default "Too Many Requests"
+ *     onDeny:          function(req, res, info): void,  // own the refusal response; info = { status, reason, limit, remaining, retryAfter, key }
+ *     problemDetails:  boolean,          // default false — emit RFC 9457 application/problem+json instead of text/plain
  *     header:          boolean,          // default true
  *     headerPrefix:    string,           // default "X-RateLimit-" — builds <prefix>Limit / <prefix>Remaining (e.g. "RateLimit-" for the IETF draft names)
  *     skipPaths:       Array<string|RegExp>,
@@ -391,7 +394,8 @@ function _resolveBackend(opts) {
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
-    "keyFn", "statusOnLimit", "bodyOnLimit", "header", "headerPrefix", "skipPaths", "scope",
+    "keyFn", "statusOnLimit", "bodyOnLimit", "onDeny", "problemDetails",
+    "header", "headerPrefix", "skipPaths", "scope",
     "backend", "trustProxy", "algorithm",
     // memory backend (token-bucket)
     "burst", "refillPerSecond",
@@ -404,6 +408,8 @@ function create(opts) {
   var keyFn = opts.keyFn || _clientIp;
   var statusOnLimit = opts.statusOnLimit || 429;
   var bodyOnLimit = opts.bodyOnLimit !== undefined ? opts.bodyOnLimit : "Too Many Requests";
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
   var emitHeaders = opts.header !== false;
   // headerPrefix (default "X-RateLimit-") builds the limit/remaining header
   // names as <prefix>Limit / <prefix>Remaining. The X-RateLimit-* family is a
@@ -455,10 +461,21 @@ function create(opts) {
         requestId: req.requestId,
       });
     } catch (_e) { /* audit best-effort */ }
-    if (typeof res.writeHead === "function") {
-      res.writeHead(statusOnLimit, { "Content-Type": "text/plain" });
-      res.end(bodyOnLimit);
-    }
+    var retryAfter = verdict.retryAfter > 0 ? verdict.retryAfter : null;
+    denyResponse(req, res, {
+      onDeny:        onDeny,
+      problem:       problemMode,
+      status:        statusOnLimit,
+      info:          { status: statusOnLimit, reason: "rate-limit-exceeded",
+        limit: verdict.limit, remaining: verdict.remaining,
+        retryAfter: verdict.retryAfter, key: k },
+      problemCode:   "rate-limit-exceeded",
+      problemTitle:  "Too Many Requests",
+      problemDetail: "Request rate limit exceeded; retry after the indicated interval.",
+      problemExt:    retryAfter !== null ? { retryAfter: retryAfter } : null,
+      contentType:   "text/plain",
+      body:          bodyOnLimit,
+    });
   }
 
   var middleware = function rateLimit(req, res, next) {

package/lib/middleware/require-aal.js

@@ -21,12 +21,13 @@
 var lazyRequire = require("../lazy-require");
 var requestHelpers = require("../request-helpers");
 var validateOpts = require("../validate-opts");
+var denyResponse = require("./deny-response").denyResponse;
 var { AuthError } = require("../framework-error");
 
 var aal = lazyRequire(function () { return require("../auth/aal"); });
 var audit = lazyRequire(function () { return require("../audit"); });
 
-function _writeUnauthorized(res, requiredBand, actualBand, realm) {
+function _writeUnauthorized(req, res, requiredBand, actualBand, realm, onDeny, problemMode) {
   if (res.headersSent) return;
   var body = JSON.stringify({
     error:             "step_up_required",
@@ -36,14 +37,24 @@ function _writeUnauthorized(res, requiredBand, actualBand, realm) {
   });
   var realmStr = realm ? ' realm="' + realm + '"' : "";
   var challenge = "AAL-StepUp" + realmStr + ', required="' + requiredBand + '"';
-  res.writeHead(401, {                                                             // HTTP 401 status
-    "Content-Type":     "application/json; charset=utf-8",
-    "Content-Length":   Buffer.byteLength(body),
-    "WWW-Authenticate": challenge,
-    // RFC 9111 §5.2.2.5 — auth-gated 401 must not be cached.
-    "Cache-Control":    "no-store",
+  denyResponse(req, res, {
+    onDeny:        onDeny,
+    problem:       problemMode,
+    status:        401,                                                            // HTTP 401 status
+    info:          { status: 401, reason: "step_up_required",
+      required_aal: requiredBand, actual_aal: actualBand || null },
+    problemCode:   "step-up-required",
+    problemTitle:  "Step-Up Authentication Required",
+    problemDetail: "AAL " + requiredBand + " is required for this resource.",
+    problemExt:    { required_aal: requiredBand, actual_aal: actualBand || null },
+    headers:       {
+      "WWW-Authenticate": challenge,
+      // RFC 9111 §5.2.2.5 — auth-gated 401 must not be cached.
+      "Cache-Control":    "no-store",
+    },
+    contentType:   "application/json; charset=utf-8",
+    body:          body,
   });
-  res.end(body);
 }
 
 /**
@@ -68,6 +79,8 @@ function _writeUnauthorized(res, requiredBand, actualBand, realm) {
  *     getAal:  function(req): string,
  *     realm:   string,
  *     audit:   boolean,                // default true
+ *     onDeny:  function(req, res, info): void,  // own the 401; info = { status, reason, required_aal, actual_aal }
+ *     problemDetails: boolean,         // default false — emit RFC 9457 application/problem+json instead of the default JSON envelope
  *   }
  *
  * @example
@@ -78,7 +91,7 @@ function _writeUnauthorized(res, requiredBand, actualBand, realm) {
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
-    "minimum", "getAal", "audit", "realm",
+    "minimum", "getAal", "audit", "realm", "onDeny", "problemDetails",
   ], "middleware.requireAal");
 
   var minimum = opts.minimum;
@@ -92,6 +105,8 @@ function create(opts) {
 
   var auditOn = opts.audit !== false;
   var realm = (typeof opts.realm === "string" && opts.realm.length > 0) ? opts.realm : null;
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
 
   return function requireAalMiddleware(req, res, next) {
     var actual = null;
@@ -116,7 +131,7 @@ function create(opts) {
           });
         } catch (_ignored) { /* drop-silent */ }
       }
-      return _writeUnauthorized(res, minimum, actual, realm);
+      return _writeUnauthorized(req, res, minimum, actual, realm, onDeny, problemMode);
     }
 
     if (auditOn) {

package/lib/middleware/require-auth.js

@@ -39,6 +39,7 @@
 var lazyRequire = require("../lazy-require");
 var requestHelpers = require("../request-helpers");
 var validateOpts = require("../validate-opts");
+var denyResponse = require("./deny-response").denyResponse;
 var audit = lazyRequire(function () { return require("../audit"); });
 
 function _defaultPrefersJson(req) {
@@ -72,6 +73,8 @@ function _defaultPrefersJson(req) {
  *     prefersJson:  function(req): boolean,
  *     errorMessage: string,                            // default "Authentication required."
  *     audit:        boolean,                           // default true
+ *     onDeny:       function(req, res, info): void,    // own any refusal shape; info = { status, reason, redirectTo }
+ *     problemDetails: boolean,                         // default false — emit RFC 9457 application/problem+json for the 401 (redirect path unaffected)
  *   }
  *
  * @example
@@ -83,7 +86,7 @@ function _defaultPrefersJson(req) {
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
-    "redirectTo", "prefersJson", "errorMessage", "audit",
+    "redirectTo", "prefersJson", "errorMessage", "audit", "onDeny", "problemDetails",
   ], "middleware.requireAuth");
   var redirectTo  = opts.redirectTo  || null;
   var prefersJson = typeof opts.prefersJson === "function"
@@ -91,6 +94,8 @@ function create(opts) {
     : _defaultPrefersJson;
   var msg     = opts.errorMessage || "Authentication required.";
   var auditOn = opts.audit !== false;
+  var onDeny  = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
 
   return function requireAuth(req, res, next) {
     if (req.user) return next();
@@ -107,6 +112,18 @@ function create(opts) {
       } catch (_e) { /* audit best-effort */ }
     }
 
+    // Operator hook owns ANY refusal shape (json / redirect / text)
+    // before the default content-negotiation runs.
+    if (onDeny) {
+      try {
+        var returned = onDeny(req, res, { status: 401, reason: "no-authenticated-user", redirectTo: redirectTo });
+        if (res.writableEnded) return returned;
+      } catch (_e) {
+        if (res.writableEnded) return;
+        // fall through to default
+      }
+    }
+
     // RFC 9111 §5.2.2.5 — auth-gated paths SHOULD emit
     // Cache-Control: no-store so a shared cache (or browser
     // back-button cache) can't replay a 401 / redirect / payload
@@ -115,27 +132,26 @@ function create(opts) {
     // cache directive, leaving the operator to set it themselves;
     // forgetting it under a CDN that respects Cache-Control was
     // a routine misconfiguration.
-    if (prefersJson(req)) {
-      if (typeof res.writeHead === "function") {
-        res.writeHead(requestHelpers.HTTP_STATUS.UNAUTHORIZED,
-          { "Content-Type": "application/json", "Cache-Control": "no-store" });
-        res.end(JSON.stringify({ error: msg }));
-      }
-      return;
-    }
-    if (redirectTo) {
-      if (typeof res.writeHead === "function") {
+    var wantsJson = prefersJson(req);
+    if (!wantsJson && redirectTo) {
+      if (!res.writableEnded && typeof res.writeHead === "function") {
         // 302 Found — RFC 7231 §6.4.3. Not in HTTP_STATUS table.
         res.writeHead(302, { "Location": redirectTo, "Cache-Control": "no-store" });
         res.end();
       }
       return;
     }
-    if (typeof res.writeHead === "function") {
-      res.writeHead(requestHelpers.HTTP_STATUS.UNAUTHORIZED,
-        { "Content-Type": "text/plain", "Cache-Control": "no-store" });
-      res.end(msg);
-    }
+    denyResponse(req, res, {
+      problem:       problemMode,
+      status:        requestHelpers.HTTP_STATUS.UNAUTHORIZED,
+      info:          { status: 401, reason: "no-authenticated-user" },
+      problemCode:   "authentication-required",
+      problemTitle:  "Unauthorized",
+      problemDetail: msg,
+      headers:       { "Cache-Control": "no-store" },
+      contentType:   wantsJson ? "application/json" : "text/plain",
+      body:          wantsJson ? JSON.stringify({ error: msg }) : msg,
+    });
   };
 }
 

package/lib/middleware/require-bound-key.js

@@ -51,6 +51,7 @@
 var defineClass = require("../framework-error").defineClass;
 var lazyRequire = require("../lazy-require");
 var validateOpts = require("../validate-opts");
+var denyResponse = require("./deny-response").denyResponse;
 
 var bCrypto = lazyRequire(function () { return require("../crypto"); });
 var audit  = lazyRequire(function () { return require("../audit"); });
@@ -98,6 +99,8 @@ function _timingSafeStringEqual(a, b) {
  *     errorMessage:            string,
  *     auditAction:             string,
  *     audit:                   object,
+ *     onDeny:                  function(req, res, info): void,  // own the refusal; info = { status, reason, ...metadata }
+ *     problemDetails:          boolean,   // default false — emit RFC 9457 application/problem+json instead of the default JSON envelope
  *   }
  *
  * @example
@@ -116,7 +119,7 @@ function create(opts) {
   validateOpts(opts, [
     "resolver", "requiredScopes", "getBoundField",
     "audit", "auditAction", "errorMessage",
-    "tolerateMissingPeerCert",
+    "tolerateMissingPeerCert", "onDeny", "problemDetails",
   ], "middleware.requireBoundKey");
 
   if (typeof opts.resolver !== "function") {
@@ -150,6 +153,8 @@ function create(opts) {
   // even when peerCertFingerprints is set on the registered key.
   // Production deployments leave this at default false.
   var tolerateMissingPeerCert = !!opts.tolerateMissingPeerCert;
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
 
   function _emitAudit(outcome, metadata) {
     if (!auditOn) return;
@@ -162,30 +167,56 @@ function create(opts) {
     } catch (_e) { /* drop-silent */ }
   }
 
-  function _refuse(res, status, reason, metadata) {
+  // RFC 6750 §3 — the Bearer challenge carries an error code that
+  // matches the failure: 401 with no token presented omits the code
+  // entirely; an unknown / revoked token is `invalid_token`; a 403
+  // missing-scope is `insufficient_scope`; a malformed bound-field
+  // request is `invalid_request`. Server-side failures (500 / 503)
+  // are not authentication challenges, so they advertise the scheme
+  // without an (incorrect) auth-error code.
+  function _bearerChallenge(status, reason) {
+    if (status === 401) {
+      if (reason === "no-bearer-token") return 'Bearer realm="api"';
+      return 'Bearer realm="api", error="invalid_token"';
+    }
+    if (status === 403) return 'Bearer realm="api", error="insufficient_scope"';
+    if (status === 400) return 'Bearer realm="api", error="invalid_request"';   // HTTP 400
+    return 'Bearer realm="api"';
+  }
+
+  function _refuse(req, res, status, reason, metadata) {
     _emitAudit("denied", Object.assign({ reason: reason }, metadata || {}));
-    if (res.writableEnded || typeof res.writeHead !== "function") return;
-    res.writeHead(status, {
-      "Content-Type":     "application/json; charset=utf-8",
-      "WWW-Authenticate": 'Bearer realm="api", error="invalid_request"',
-      "Cache-Control":    "no-store",
+    denyResponse(req, res, {
+      onDeny:        onDeny,
+      problem:       problemMode,
+      status:        status,
+      info:          Object.assign({ status: status, reason: reason }, metadata || {}),
+      problemCode:   "bound-key-refused",
+      problemTitle:  errorMessage,
+      problemDetail: "API key authentication failed: " + reason + ".",
+      problemExt:    { reason: reason },
+      headers:       {
+        "WWW-Authenticate": _bearerChallenge(status, reason),
+        "Cache-Control":    "no-store",
+      },
+      contentType:   "application/json; charset=utf-8",
+      body:          JSON.stringify({ error: errorMessage, reason: reason }),
     });
-    res.end(JSON.stringify({ error: errorMessage, reason: reason }));
   }
 
   return async function requireBoundKeyMiddleware(req, res, next) {
     var apiKey = _parseBearer(req);
-    if (!apiKey) return _refuse(res, 401, "no-bearer-token", {});
+    if (!apiKey) return _refuse(req, res, 401, "no-bearer-token", {});
 
     var record;
     try { record = await resolver(apiKey); }
     catch (e) {
-      return _refuse(res, 503, "resolver-unavailable", {
+      return _refuse(req, res, 503, "resolver-unavailable", {
         error: (e && e.message) || String(e),
       });
     }
     if (!record || typeof record !== "object") {
-      return _refuse(res, 401, "key-unknown-or-revoked", {});
+      return _refuse(req, res, 401, "key-unknown-or-revoked", {});
     }
 
     // Required-scope check — operator-supplied requiredScopes must be
@@ -193,7 +224,7 @@ function create(opts) {
     var keyScopes = Array.isArray(record.scopes) ? record.scopes : [];
     for (var rsi = 0; rsi < requiredScopes.length; rsi++) {
       if (keyScopes.indexOf(requiredScopes[rsi]) === -1) {
-        return _refuse(res, 403, "missing-scope", {
+        return _refuse(req, res, 403, "missing-scope", {
           requiredScope: requiredScopes[rsi], keyId: record.id || null,
         });
       }
@@ -208,25 +239,25 @@ function create(opts) {
       var fieldName = registeredKeys[bfi];
       var getter = getBoundField[fieldName];
       if (!getter) {
-        return _refuse(res, 500, "bound-field-no-getter", {
+        return _refuse(req, res, 500, "bound-field-no-getter", {
           field: fieldName, keyId: record.id || null,
         });
       }
       var presented;
       try { presented = getter(req); }
       catch (e) {
-        return _refuse(res, 400, "bound-field-getter-threw", {                            // HTTP 400
+        return _refuse(req, res, 400, "bound-field-getter-threw", {                            // HTTP 400
           field: fieldName, error: (e && e.message) || String(e),
         });
       }
       if (typeof presented !== "string" || presented.length === 0) {
-        return _refuse(res, 400, "bound-field-missing", {                                 // HTTP 400
+        return _refuse(req, res, 400, "bound-field-missing", {                                 // HTTP 400
           field: fieldName, keyId: record.id || null,
         });
       }
       var expected = String(registered[fieldName]);
       if (!_timingSafeStringEqual(presented, expected)) {
-        return _refuse(res, 403, "bound-field-mismatch", {
+        return _refuse(req, res, 403, "bound-field-mismatch", {
           field: fieldName, keyId: record.id || null,
         });
       }
@@ -252,7 +283,7 @@ function create(opts) {
           // Audited bypass for dev fixtures.
           _emitAudit("denied", { reason: "peer-cert-bypass-tolerated", keyId: record.id });
         } else {
-          return _refuse(res, 401, "peer-cert-required", {
+          return _refuse(req, res, 401, "peer-cert-required", {
             keyId: record.id || null,
           });
         }
@@ -262,7 +293,7 @@ function create(opts) {
         // because it does the same constant-time hex/colon comparison
         // we want for an allow-list. A future refactor can rename to
         // isCertFingerprintInSet — semantically identical.
-        return _refuse(res, 403, "peer-cert-not-pinned", {
+        return _refuse(req, res, 403, "peer-cert-not-pinned", {
           fingerprint: fpColon, keyId: record.id || null,
         });
       }

package/lib/middleware/require-content-type.js

@@ -18,6 +18,7 @@
  */
 
 var lazyRequire = require("../lazy-require");
+var denyResponse = require("./deny-response").denyResponse;
 var { defineClass } = require("../framework-error");
 
 var RequireContentTypeError = defineClass("RequireContentTypeError", { alwaysPermanent: true });
@@ -58,8 +59,10 @@ function _normalizeAllowed(types) {
  *
  * @opts
  *   {
- *     methods: string[],   // override default ["POST", "PUT", "PATCH"]
- *     audit:   boolean,    // default true
+ *     methods:        string[],   // override default ["POST", "PUT", "PATCH"]
+ *     audit:          boolean,    // default true
+ *     onDeny:         function(req, res, info): void,  // own the 415; info = { status, reason, contentType, accepted }
+ *     problemDetails: boolean,    // default false — emit RFC 9457 application/problem+json instead of text/plain
  *   }
  *
  * @example
@@ -82,6 +85,8 @@ function create(allowed, opts) {
                   ? opts.methods.map(function (m) { return m.toUpperCase(); })
                   : DEFAULT_BODY_METHODS.slice();
   var auditOn = opts.audit !== false;
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
 
   return function requireContentTypeMiddleware(req, res, next) {
     var m = (req.method || "").toUpperCase();
@@ -90,13 +95,19 @@ function create(allowed, opts) {
     var bare = (typeof ct === "string" ? ct.split(";")[0].trim().toLowerCase() : "");
     if (bare.length > 0 && normalized.indexOf(bare) !== -1) return next();
     if (!res.headersSent) {
-      var body = "Unsupported Media Type";
-      res.writeHead(415, {                                                       // HTTP 415 status
-        "Accept":         normalized.join(", "),
-        "Content-Type":   "text/plain; charset=utf-8",
-        "Content-Length": Buffer.byteLength(body),
+      denyResponse(req, res, {
+        onDeny:        onDeny,
+        problem:       problemMode,
+        status:        415,
+        info:          { status: 415, reason: "unsupported-media-type",
+          contentType: bare || null, accepted: normalized },
+        problemCode:   "unsupported-media-type",
+        problemTitle:  "Unsupported Media Type",
+        problemDetail: "The request Content-Type is not accepted on this resource.",
+        headers:       { "Accept": normalized.join(", ") },
+        contentType:   "text/plain; charset=utf-8",
+        body:          "Unsupported Media Type",
       });
-      res.end(body);
     }
     if (auditOn) {
       try {

package/lib/middleware/require-methods.js

@@ -16,6 +16,7 @@
  */
 
 var lazyRequire = require("../lazy-require");
+var denyResponse = require("./deny-response").denyResponse;
 var { defineClass } = require("../framework-error");
 
 var RequireMethodsError = defineClass("RequireMethodsError", { alwaysPermanent: true });
@@ -38,7 +39,9 @@ var observability = lazyRequire(function () { return require("../observability")
  *
  * @opts
  *   {
- *     audit: boolean,   // default true
+ *     audit:          boolean,   // default true
+ *     onDeny:         function(req, res, info): void,  // own the 405; info = { status, reason, method, allowed }
+ *     problemDetails: boolean,   // default false — emit RFC 9457 application/problem+json instead of text/plain
  *   }
  *
  * @example
@@ -69,18 +72,25 @@ function create(allowed, opts) {
   var allowHeader = normalized.join(", ");
   opts = opts || {};
   var auditOn = opts.audit !== false;
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
 
   return function requireMethodsMiddleware(req, res, next) {
     var m = (req.method || "").toUpperCase();
     if (normalized.indexOf(m) !== -1) return next();
     if (!res.headersSent) {
-      var body = "Method Not Allowed";
-      res.writeHead(405, {                                                       // HTTP 405 status
-        "Allow":          allowHeader,
-        "Content-Type":   "text/plain; charset=utf-8",
-        "Content-Length": Buffer.byteLength(body),
+      denyResponse(req, res, {
+        onDeny:        onDeny,
+        problem:       problemMode,
+        status:        405,
+        info:          { status: 405, reason: "method-not-allowed", method: m, allowed: normalized },
+        problemCode:   "method-not-allowed",
+        problemTitle:  "Method Not Allowed",
+        problemDetail: "The " + m + " method is not allowed on this resource.",
+        headers:       { "Allow": allowHeader },
+        contentType:   "text/plain; charset=utf-8",
+        body:          "Method Not Allowed",
       });
-      res.end(body);
     }
     if (auditOn) {
       try {

package/lib/middleware/require-mtls.js

@@ -48,6 +48,7 @@
 var defineClass = require("../framework-error").defineClass;
 var lazyRequire = require("../lazy-require");
 var validateOpts = require("../validate-opts");
+var denyResponse = require("./deny-response").denyResponse;
 
 var bCrypto = lazyRequire(function () { return require("../crypto"); });
 var audit  = lazyRequire(function () { return require("../audit"); });
@@ -84,6 +85,8 @@ function _normalizeFingerprintEntry(entry) {
  *     fingerprintAllowList: string[],
  *     denyList:             string[],
  *     onAuthenticated:      function(req, res, next): void,
+ *     onDeny:               function(req, res, info): void,  // own the refusal (mirrors onAuthenticated); info = { status, reason, ...metadata }
+ *     problemDetails:       boolean,        // default false — emit RFC 9457 application/problem+json instead of the default JSON envelope
  *     auditAction:          string,
  *     errorMessage:         string,
  *     audit:                object,
@@ -100,7 +103,7 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "fingerprintAllowList", "denyList",
-    "onAuthenticated", "audit",
+    "onAuthenticated", "onDeny", "problemDetails", "audit",
     "auditAction", "errorMessage",
   ], "middleware.requireMtls");
 
@@ -109,6 +112,8 @@ function create(opts) {
   var denyList = Array.isArray(opts.denyList)
     ? opts.denyList.map(_normalizeFingerprintEntry) : [];
   var onAuthenticated = typeof opts.onAuthenticated === "function" ? opts.onAuthenticated : null;
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
   var auditOn  = opts.audit !== false;
   var actionBase = typeof opts.auditAction === "string" && opts.auditAction.length > 0
     ? opts.auditAction : "mtls.required";
@@ -126,16 +131,24 @@ function create(opts) {
     } catch (_e) { /* drop-silent — audit is best-effort, never blocks the request */ }
   }
 
-  function _refuse(res, reason, metadata) {
+  function _refuse(req, res, reason, metadata) {
     _emit("denied", Object.assign({ reason: reason }, metadata || {}));
-    if (typeof res.writeHead === "function") {
-      res.writeHead(401, {
-        "Content-Type":     "application/json; charset=utf-8",
+    denyResponse(req, res, {
+      onDeny:        onDeny,
+      problem:       problemMode,
+      status:        401,
+      info:          Object.assign({ status: 401, reason: reason }, metadata || {}),
+      problemCode:   "client-certificate-required",
+      problemTitle:  "Unauthorized",
+      problemDetail: errorMessage,
+      problemExt:    { reason: reason },
+      headers:       {
         "WWW-Authenticate": "Mutual",
         "Cache-Control":    "no-store",
-      });
-      res.end(JSON.stringify({ error: errorMessage, reason: reason }));
-    }
+      },
+      contentType:   "application/json; charset=utf-8",
+      body:          JSON.stringify({ error: errorMessage, reason: reason }),
+    });
   }
 
   return function requireMtlsMiddleware(req, res, next) {
@@ -158,10 +171,10 @@ function create(opts) {
 
     if (!authorized) {
       var authzError = (sock && sock.authorizationError) || "no-peer-cert";
-      return _refuse(res, "tls-unauthorized", { authorizationError: String(authzError) });
+      return _refuse(req, res, "tls-unauthorized", { authorizationError: String(authzError) });
     }
     if (!peerCert || !peerCert.raw) {
-      return _refuse(res, "no-peer-cert", {});
+      return _refuse(req, res, "no-peer-cert", {});
     }
 
     // Compute fingerprint via the framework's SHA3-512 helper. Buffer
@@ -171,17 +184,17 @@ function create(opts) {
     try {
       fp = bCrypto().hashCertFingerprint(peerCert.raw);
     } catch (e) {
-      return _refuse(res, "fingerprint-failed", { error: (e && e.message) || String(e) });
+      return _refuse(req, res, "fingerprint-failed", { error: (e && e.message) || String(e) });
     }
 
     if (denyList.length > 0 && bCrypto().isCertRevoked(peerCert.raw, denyList)) {
-      return _refuse(res, "fingerprint-on-deny-list", {
+      return _refuse(req, res, "fingerprint-on-deny-list", {
         fingerprint: fp.colon,
         subject:     (peerCert.subject && peerCert.subject.CN) || null,
       });
     }
     if (allowList && allowList.length > 0 && !bCrypto().isCertRevoked(peerCert.raw, allowList)) {
-      return _refuse(res, "fingerprint-not-allowed", {
+      return _refuse(req, res, "fingerprint-not-allowed", {
         fingerprint: fp.colon,
         subject:     (peerCert.subject && peerCert.subject.CN) || null,
       });
@@ -199,7 +212,7 @@ function create(opts) {
     if (onAuthenticated) {
       try { return onAuthenticated(req, res, next); }
       catch (e) {
-        return _refuse(res, "on-authenticated-threw", { error: (e && e.message) || String(e) });
+        return _refuse(req, res, "on-authenticated-threw", { error: (e && e.message) || String(e) });
       }
     }
     return next();

package/lib/network-dns-resolver.js

@@ -126,7 +126,7 @@ var DEFAULT_MAX_TTL_MS    = C.TIME.hours(24);
 var DEFAULT_MIN_TTL_MS    = C.TIME.seconds(60);
 var DEFAULT_STALE_WINDOW  = C.TIME.hours(6);
 var DEFAULT_PROFILE       = "strict";
-// BUG-1 / MAIL-26 — CWE-400/770. Bound the cache so a hostile peer
+// CWE-400/770. Bound the cache so a hostile peer
 // that can drive query-name selection (e.g. inbound SMTP forwarding
 // DKIM `s=` / `d=` tag-controlled lookups) cannot inflate the Map to
 // OOM. Default 5000 entries: a parsed-response object ~100 bytes ×
@@ -216,7 +216,7 @@ function create(opts) {
 
   var cache = new Map();                  // key → { response, parsed, ttl, expiresAt, staleUntil }
 
-  // CWE-400/770 / BUG-1 — LRU eviction on insert when the cache is at
+  // CWE-400/770. LRU eviction on insert when the cache is at
   // capacity. v8 Map preserves insertion order; oldest key is the
   // first entry returned by Map.keys().next().
   function _evictIfFull() {

package/lib/network-dns.js

@@ -39,8 +39,7 @@ var STATE = {
   // Default-on secure DNS (DoH via Cloudflare) when neither doh nor dot
   // is operator-configured AND no opt-out env var is set. Operators
   // who explicitly want the system resolver call useSystemResolver()
-  // or set BLAMEJS_DNS_TRANSPORT=system. Default-on per Core Rule §3
-  // ("security defaults are not opt-in").
+  // or set BLAMEJS_DNS_TRANSPORT=system. Default-on (security defaults are not opt-in).
   systemResolver: false,
 };
 

package/lib/network-tls.js

@@ -1136,7 +1136,6 @@ function evaluateOcspResponse(ocspDer, opts) {
     // length inputs but fast-paths on length mismatch; not security-
     // critical here (the OCSP response is CA-signed and signature
     // already verified) but matches the project discipline.
-    // (Audit 2026-05-11.)
     if (!bCrypto.timingSafeEqual(parsed.basic.nonce, opts.expectedNonce)) {
       return { ok: false, status: parsed.status, signatureValid: true,
                errors: ["OCSP nonce mismatch — possible replay or wrong responder"] };