@blamejs/core 0.14.4 → 0.14.6

package/lib/middleware/cors.js

@@ -55,6 +55,7 @@ var audit = lazyRequire(function () { return require("../audit"); });
 var requestHelpers = require("../request-helpers");
 var safeUrl = require("../safe-url");
 var validateOpts = require("../validate-opts");
+var denyResponse = require("./deny-response").denyResponse;
 var { defineClass } = require("../framework-error");
 
 // CORS audit events use the proxy-aware client IP only when the
@@ -185,6 +186,8 @@ function _isSameOrigin(req, originHeader, configuredSiteOrigins, trustProxy, str
  *     refuseUnknown:    boolean,    // default true
  *     strictNullOrigin: boolean,    // default true
  *     trustProxy:       boolean|number,
+ *     onDeny:           function(req, res, info): void,  // own every refusal; info = { status, reason, origin, header? }
+ *     problemDetails:   boolean,    // default false — emit RFC 9457 application/problem+json instead of text/plain
  *   }
  *
  * @example
@@ -202,7 +205,7 @@ function create(opts) {
   validateOpts(opts, [
     "origins", "siteOrigin", "methods", "headers", "exposeHeaders",
     "credentials", "maxAgeSeconds", "refuseUnknown", "trustProxy",
-    "strictNullOrigin", "allowPrivateNetwork",
+    "strictNullOrigin", "allowPrivateNetwork", "onDeny", "problemDetails",
   ], "middleware.cors");
   var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
     ? opts.trustProxy : false;
@@ -269,6 +272,22 @@ function create(opts) {
   // header). Operators with a no-referrer page producing legitimate
   // Origin: null on same-origin POSTs flip to false explicitly.
   var strictNullOrigin = opts.strictNullOrigin !== false;
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
+
+  function _refuse(req, res, reason, body, ext) {
+    denyResponse(req, res, {
+      onDeny:        onDeny,
+      problem:       problemMode,
+      status:        requestHelpers.HTTP_STATUS.FORBIDDEN,
+      info:          Object.assign({ status: 403, reason: reason }, ext || {}),
+      problemCode:   "cors-refused",
+      problemTitle:  "Forbidden",
+      problemDetail: body,
+      contentType:   "text/plain",
+      body:          body,
+    });
+  }
 
   return function cors(req, res, next) {
     var origin = req.headers && req.headers.origin;
@@ -302,9 +321,8 @@ function create(opts) {
             requestId: req.requestId,
           });
         } catch (_e) { /* audit best-effort */ }
-        if (typeof res.writeHead === "function") {
-          res.writeHead(requestHelpers.HTTP_STATUS.FORBIDDEN, { "Content-Type": "text/plain" });
-          res.end("CORS: origin not allowed");
+        if (typeof res.writeHead === "function" || onDeny) {
+          _refuse(req, res, "origin-not-allowed", "CORS: origin not allowed", { origin: origin });
           return;
         }
       }
@@ -333,10 +351,9 @@ function create(opts) {
           var asked = requestHelpers.parseListHeader(requestedHdrs, { lowercase: true });
           for (var ah = 0; ah < asked.length; ah++) {
             if (allowedHeadersSet.indexOf(asked[ah]) === -1) {
-              if (typeof res.writeHead === "function") {
-                res.writeHead(requestHelpers.HTTP_STATUS.FORBIDDEN, { "Content-Type": "text/plain" });
-                res.end("CORS: requested header '" + asked[ah] + "' not in allow-list");
-              }
+              _refuse(req, res, "requested-header-not-allowed",
+                "CORS: requested header '" + asked[ah] + "' not in allow-list",
+                { origin: origin, header: asked[ah] });
               return;
             }
           }
@@ -357,10 +374,9 @@ function create(opts) {
             res.setHeader("Access-Control-Allow-Private-Network", "true");
           }
         } else {
-          if (typeof res.writeHead === "function") {
-            res.writeHead(requestHelpers.HTTP_STATUS.FORBIDDEN, { "Content-Type": "text/plain" });
-            res.end("CORS: Private Network Access not permitted (set allowPrivateNetwork:true with audited reason to opt in)");
-          }
+          _refuse(req, res, "private-network-not-permitted",
+            "CORS: Private Network Access not permitted (set allowPrivateNetwork:true with audited reason to opt in)",
+            { origin: origin });
           return;
         }
       }

package/lib/middleware/csrf-protect.js

@@ -70,6 +70,7 @@ var lazyRequire = require("../lazy-require");
 var forms = require("../forms");
 var requestHelpers = require("../request-helpers");
 var validateOpts = require("../validate-opts");
+var denyResponse = require("./deny-response").denyResponse;
 var audit = lazyRequire(function () { return require("../audit"); });
 
 var DEFAULT_FIELD_NAME    = "_csrf";
@@ -218,15 +219,18 @@ function _checkOriginAllowed(req, allowedOrigins, isHttpsFn, requireOrigin) {
   return null;
 }
 
-function _writeReject(res, message) {
-  if (typeof res.writeHead === "function") {
-    var body = JSON.stringify({ error: message });
-    res.writeHead(requestHelpers.HTTP_STATUS.FORBIDDEN, {
-      "Content-Type":   "application/json; charset=utf-8",
-      "Content-Length": Buffer.byteLength(body),
-    });
-    res.end(body);
-  }
+function _writeReject(req, res, message, reason, onDeny, problemMode) {
+  denyResponse(req, res, {
+    onDeny:        onDeny,
+    problem:       problemMode,
+    status:        requestHelpers.HTTP_STATUS.FORBIDDEN,
+    info:          { status: 403, reason: reason },
+    problemCode:   "csrf-refused",
+    problemTitle:  "Forbidden",
+    problemDetail: message,
+    contentType:   "application/json; charset=utf-8",
+    body:          JSON.stringify({ error: message }),
+  });
 }
 
 /**
@@ -262,6 +266,8 @@ function _writeReject(res, message) {
  *     trustProxy:             boolean|number,
  *     audit:                  boolean,
  *     skipStateless:          boolean,   // default false — skip validation for Authorization-header / cookieless (not-CSRF-able) requests
+ *     onDeny:                 function(req, res, info): void,  // own the 403; info = { status, reason }
+ *     problemDetails:         boolean,   // default false — emit RFC 9457 application/problem+json instead of the default JSON envelope
  *   }
  *
  * @example
@@ -279,8 +285,10 @@ function create(opts) {
   validateOpts(opts, [
     "cookie", "tokenLookup", "fieldName", "headerName", "methods", "audit",
     "trustProxy", "checkOrigin", "allowedOrigins", "requireJsonContentType",
-    "requireOrigin", "skipStateless",
+    "requireOrigin", "skipStateless", "onDeny", "problemDetails",
   ], "middleware.csrfProtect");
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
   var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
     ? opts.trustProxy : false;
   var _isHttps = _isHttpsFor(trustProxy);
@@ -477,7 +485,7 @@ function create(opts) {
       var bare = (typeof ct === "string" ? ct.split(";")[0].trim().toLowerCase() : "");
       if (bare !== "application/json") {
         _emitDenied(req, "non-JSON content-type: " + (bare || "<absent>"));
-        return _writeReject(res, "CSRF: state-changing requests require Content-Type: application/json.");
+        return _writeReject(req, res, "CSRF: state-changing requests require Content-Type: application/json.", "content-type-required", onDeny, problemMode);
       }
     }
 
@@ -489,7 +497,7 @@ function create(opts) {
       var originReason = _checkOriginAllowed(req, allowedOrigins, _isHttps, requireOriginOpt);
       if (originReason !== null) {
         _emitDenied(req, "origin/referer: " + originReason);
-        return _writeReject(res, "CSRF cross-origin request refused.");
+        return _writeReject(req, res, "CSRF cross-origin request refused.", "cross-origin-refused", onDeny, problemMode);
       }
     }
 
@@ -499,7 +507,7 @@ function create(opts) {
     }
     if (!expected) {
       _emitDenied(req, cookieCfg ? "no token cookie issued yet" : "no expected token in session");
-      return _writeReject(res, "CSRF token mismatch.");
+      return _writeReject(req, res, "CSRF token mismatch.", "token-mismatch", onDeny, problemMode);
     }
 
     // Header path first — covers JSON / AJAX / multipart cases.
@@ -517,7 +525,7 @@ function create(opts) {
 
     if (!forms.verifyCsrfToken(submitted || "", expected)) {
       _emitDenied(req, "submitted token does not match expected");
-      return _writeReject(res, "CSRF token mismatch.");
+      return _writeReject(req, res, "CSRF token mismatch.", "token-mismatch", onDeny, problemMode);
     }
 
     return next();

package/lib/middleware/daily-byte-quota.js

@@ -41,6 +41,7 @@ var defineClass = require("../framework-error").defineClass;
 var lazyRequire = require("../lazy-require");
 var networkByteQuota = require("../network-byte-quota");
 var validateOpts = require("../validate-opts");
+var denyResponse = require("./deny-response").denyResponse;
 
 var audit = lazyRequire(function () { return require("../audit"); });
 var observability = lazyRequire(function () { return require("../observability"); });
@@ -76,7 +77,9 @@ function _defaultGetKey(req) {
  *     bytesPerDay: number,                            // required, positive, finite
  *     getKey:      function(req): string|null,        // default: req client IP
  *     cache:       object,                            // null = in-memory single-node
- *     onExceeded:  function(req, res, info): void,
+ *     onDeny:      function(req, res, info): void,    // own the 429; info = { status, reason, quota, total, retryAfterSec }
+ *     onExceeded:  function(req, res, info): void,    // legacy alias for onDeny
+ *     problemDetails: boolean,                        // default false — emit RFC 9457 application/problem+json instead of the default JSON envelope
  *     skipPaths:   string[],
  *     now:         function(): number,
  *     audit:       boolean,                           // default true
@@ -94,7 +97,7 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "bytesPerDay", "cache", "getKey", "audit",
-    "onExceeded", "skipPaths", "now",
+    "onDeny", "onExceeded", "problemDetails", "skipPaths", "now",
   ], "middleware.dailyByteQuota");
 
   if (typeof opts.bytesPerDay !== "number" || !isFinite(opts.bytesPerDay) || opts.bytesPerDay <= 0) {
@@ -105,7 +108,11 @@ function create(opts) {
   var bytesPerDay = opts.bytesPerDay;
   var getKey = typeof opts.getKey === "function" ? opts.getKey : _defaultGetKey;
   var auditOn = opts.audit !== false;
-  var onExceeded = typeof opts.onExceeded === "function" ? opts.onExceeded : null;
+  // onDeny is the canonical hook across the deny-path middleware
+  // family; onExceeded is the original name kept working as an alias.
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny
+    : (typeof opts.onExceeded === "function" ? opts.onExceeded : null);
+  var problemMode = opts.problemDetails === true;
   var skipPaths = Array.isArray(opts.skipPaths) ? opts.skipPaths.slice() : [];
   var now = typeof opts.now === "function" ? opts.now : function () { return Date.now(); };
 
@@ -169,22 +176,29 @@ function create(opts) {
       _emitMetric("refused", 1, { reason: "quota-exceeded" });
       _emitAudit("refused", "denied", { key: key, total: total, quota: bytesPerDay });
       var info = {
+        status:          429,
+        reason:          "quota-exceeded",
         quota:           bytesPerDay,
         total:           total,
         retryAfterSec:   Math.ceil(C.TIME.hours(1) / C.TIME.seconds(1)),
       };
-      if (onExceeded) {
-        try { return onExceeded(req, res, info); }
-        catch (e) { _emitAudit("on_exceeded_threw", "failure", { error: (e && e.message) || String(e) }); }
-      }
-      if (!res.writableEnded) {
-        res.writeHead(429, {
-          "Content-Type":  "application/json; charset=utf-8",
+      denyResponse(req, res, {
+        onDeny:        onDeny,
+        problem:       problemMode,
+        status:        429,
+        info:          info,
+        problemCode:   "daily-byte-quota-exceeded",
+        problemTitle:  "Too Many Requests",
+        problemDetail: "Daily byte quota exceeded; retry after the indicated interval.",
+        problemExt:    { quota: bytesPerDay, total: total, retryAfter: info.retryAfterSec },
+        headers:       {
           "Retry-After":   String(info.retryAfterSec),
           "Cache-Control": "no-store",
-        });
-        res.end(JSON.stringify({ error: "quota-exceeded", quota: bytesPerDay, total: total }));
-      }
+        },
+        contentType:   "application/json; charset=utf-8",
+        body:          JSON.stringify({ error: "quota-exceeded", quota: bytesPerDay, total: total }),
+        onThrow:       function (e) { _emitAudit("on_exceeded_threw", "failure", { error: (e && e.message) || String(e) }); },
+      });
       return;
     }
 

package/lib/middleware/deny-response.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Shared deny-path response writer for the request-lifecycle
+ * middlewares that refuse a request (401 / 403 / 405 / 415 / 429 /
+ * 451 / misdirected-request). Every deny-path middleware routes its
+ * refusal through `denyResponse` so a consumer gets one uniform way
+ * to shape it, instead of each middleware hardcoding its own body +
+ * Content-Type.
+ *
+ * Three resolution modes, checked in order:
+ *
+ *   1. `onDeny(req, res, info)` operator hook — when supplied, the
+ *      consumer owns the response. `info` carries the machine
+ *      `status` / `reason` plus the middleware-specific fields. The
+ *      hook is wrapped so a throw is audited (via `ctx.onThrow`) and
+ *      then falls through to the default write rather than crashing
+ *      the request that triggered the refusal. A hook that returns
+ *      without writing also falls through — the response can never
+ *      hang on a no-op hook.
+ *
+ *   2. `problem: true` — emit RFC 9457 `application/problem+json` by
+ *      composing `b.problemDetails`. The middleware supplies the
+ *      `type` / `title` / `detail` and any extension members; the
+ *      deny-path response headers (`Allow` / `WWW-Authenticate` /
+ *      `Retry-After` / `Accept`) are merged onto the problem
+ *      response so content negotiation does not drop them.
+ *
+ *   3. Default — the middleware's existing body + Content-Type. No
+ *      behavior change when neither knob is set.
+ *
+ * This is an internal helper (no public `b.*` surface); the consumer
+ * contract is the `onDeny` / `problemDetails` opts documented on each
+ * middleware that composes it.
+ */
+
+var problemDetails = require("../problem-details");
+
+function _isFn(x) { return typeof x === "function"; }
+
+function _mergeInto(target, extra) {
+  if (!extra || typeof extra !== "object") return target;
+  var keys = Object.keys(extra);
+  for (var i = 0; i < keys.length; i += 1) {
+    target[keys[i]] = extra[keys[i]];
+  }
+  return target;
+}
+
+/**
+ * Resolve a deny-path refusal through the uniform hook / problem+json
+ * / default chain. Returns whatever the `onDeny` hook returns when it
+ * owns the response, otherwise `undefined`.
+ *
+ * ctx fields:
+ *   onDeny:        function (req, res, info) | null  — operator hook
+ *   problem:       boolean   — emit application/problem+json
+ *   status:        number    — HTTP status (100..599)
+ *   info:          object    — passed verbatim to onDeny; also seeds
+ *                              the problem document (status / reason)
+ *   problemType:   string?   — RFC 9457 `type` (URI reference); when
+ *                              absent, built from `problemCode`
+ *   problemCode:   string?   — type-URI suffix; resolves to
+ *                              `<problemDetails base>/<code>` (the same
+ *                              `<base>/<code>` convention as fromError)
+ *   problemTitle:  string?   — RFC 9457 `title`
+ *   problemDetail: string?   — RFC 9457 `detail`
+ *   problemExt:    object?   — extra problem members (reserved names
+ *                              dropped); siblings per RFC 9457 §3.2
+ *   headers:       object?   — extra response headers (Allow /
+ *                              WWW-Authenticate / Retry-After / Accept
+ *                              / Cache-Control)
+ *   contentType:   string    — default-mode Content-Type
+ *   body:          string|Buffer — default-mode body
+ *   onThrow:       function (err) ? — audit sink when onDeny throws
+ */
+function denyResponse(req, res, ctx) {
+  var info = (ctx.info && typeof ctx.info === "object") ? ctx.info : {};
+
+  if (_isFn(ctx.onDeny)) {
+    try {
+      var returned = ctx.onDeny(req, res, info);
+      if (res.writableEnded) return returned;
+      // Hook ran but did not write — fall through to the default so
+      // the response can never hang on a no-op hook.
+    } catch (e) {
+      if (_isFn(ctx.onThrow)) {
+        try { ctx.onThrow(e); } catch (_e) { /* drop-silent */ }
+      }
+      if (res.writableEnded) return undefined;
+      // Hook threw before writing — fall through to the default.
+    }
+  }
+
+  if (res.writableEnded || !_isFn(res.writeHead)) return undefined;
+
+  var extra = (ctx.headers && typeof ctx.headers === "object") ? ctx.headers : null;
+
+  if (ctx.problem) {
+    var fields = { status: ctx.status };
+    if (ctx.problemType)   fields.type   = ctx.problemType;
+    if (ctx.problemTitle)  fields.title  = ctx.problemTitle;
+    if (ctx.problemDetail) fields.detail = ctx.problemDetail;
+    if (ctx.problemExt && typeof ctx.problemExt === "object") {
+      var ek = Object.keys(ctx.problemExt);
+      for (var i = 0; i < ek.length; i += 1) {
+        if (problemDetails.RESERVED_FIELDS.indexOf(ek[i]) === -1) {
+          fields[ek[i]] = ctx.problemExt[ek[i]];
+        }
+      }
+    }
+    var problem;
+    try {
+      problem = problemDetails.create(fields);
+    } catch (_e) {
+      // A bad extension shape (prototype-pollution key, out-of-range
+      // status) must not turn a refusal into a 500 — degrade to the
+      // bare status document.
+      problem = problemDetails.create({ status: ctx.status });
+    }
+    // Set the deny-path headers before respond() so content
+    // negotiation does not lose Allow / WWW-Authenticate / Retry-After.
+    if (extra) {
+      var hk = Object.keys(extra);
+      for (var h = 0; h < hk.length; h += 1) {
+        res.setHeader(hk[h], extra[hk[h]]);
+      }
+    }
+    problemDetails.respond(res, problem);
+    return undefined;
+  }
+
+  var head = _mergeInto({ "Content-Type": ctx.contentType }, extra);
+  res.writeHead(ctx.status, head);
+  res.end((ctx.body === undefined || ctx.body === null) ? "" : ctx.body);
+  return undefined;
+}
+
+module.exports = {
+  denyResponse: denyResponse,
+};

package/lib/middleware/dpop.js

@@ -40,6 +40,7 @@ var bCrypto = require("../crypto");
 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 dpop = lazyRequire(function () { return require("../auth/dpop"); });
@@ -49,20 +50,28 @@ var audit = lazyRequire(function () { return require("../audit"); });
 // of entropy after base64url, far above the spec's "unpredictable" bar).
 var DPOP_NONCE_BYTES = C.BYTES.bytes(24);
 
-function _writeUnauthorized(res, errorCode, description, freshNonce) {
-  if (res.headersSent) return;
+function _writeUnauthorized(req, res, errorCode, description, freshNonce, onDeny, problemMode) {
   var body = JSON.stringify({ error: errorCode, error_description: description });
   // RFC 9449 §7 — error code is invalid_dpop_proof OR use_dpop_nonce.
   var challenge = 'DPoP error="' + errorCode + '", error_description="' +
                   description.replace(/"/g, "'") + '"';
-  var headers = {                                                                  // HTTP 401 status
-    "Content-Type":     "application/json; charset=utf-8",
-    "Content-Length":   Buffer.byteLength(body),
+  var headers = {
     "WWW-Authenticate": challenge,
   };
   if (freshNonce) headers["DPoP-Nonce"] = freshNonce;
-  res.writeHead(401, headers);
-  res.end(body);
+  denyResponse(req, res, {
+    onDeny:        onDeny,
+    problem:       problemMode,
+    status:        401,                                                            // HTTP 401 status
+    info:          { status: 401, reason: errorCode, error_description: description },
+    problemCode:   "dpop-" + errorCode.replace(/_/g, "-"),
+    problemTitle:  "Unauthorized",
+    problemDetail: description,
+    problemExt:    { error: errorCode, error_description: description },
+    headers:       headers,
+    contentType:   "application/json; charset=utf-8",
+    body:          body,
+  });
 }
 
 // RFC 9449 §8 — server-issued DPoP-Nonce challenge. The framework
@@ -201,6 +210,8 @@ function _reconstructHtu(req, mopts) {
  *     nonceRotateSec: number,
  *     requireNonce:   boolean,
  *     audit:          boolean,                      // default true
+ *     onDeny:         function(req, res, info): void,  // own the 401; info = { status, reason, error_description }
+ *     problemDetails: boolean,                      // default false — emit RFC 9457 application/problem+json instead of the default JSON envelope
  *   }
  *
  * @example
@@ -220,9 +231,11 @@ function create(opts) {
     // v0.9.4 — opt-in trust gate for X-Forwarded-Proto/Host when
     // reconstructing htu. Default off (audit 2026-05-11); operators
     // with a confirmed-trusted front proxy set this to `true`.
-    "trustForwardedHeaders",
+    "trustForwardedHeaders", "onDeny", "problemDetails",
   ], "middleware.dpop");
 
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
   var auditOn = opts.audit !== false;
   var algorithms = opts.algorithms;
   var iatWindowSec = opts.iatWindowSec;
@@ -265,14 +278,14 @@ function create(opts) {
   var middleware = async function dpopMiddleware(req, res, next) {
     var proofHeader = req.headers && req.headers.dpop;
     if (typeof proofHeader !== "string" || proofHeader.length === 0) {
-      return _writeUnauthorized(res,
+      return _writeUnauthorized(req, res,
         nonceMgr ? "use_dpop_nonce" : "invalid_dpop_proof",
-        "DPoP header required", _freshNonce());
+        "DPoP header required", _freshNonce(), onDeny, problemMode);
     }
     // RFC 9449 §4.1 — only ONE DPoP header value per request.
     if (Array.isArray(proofHeader)) {
-      return _writeUnauthorized(res, "invalid_dpop_proof",
-        "multiple DPoP headers are not allowed");
+      return _writeUnauthorized(req, res, "invalid_dpop_proof",
+        "multiple DPoP headers are not allowed", null, onDeny, problemMode);
     }
     // AUTH-15 — RFC 9449 §4.1 single-value invariant. node:http
     // collapses repeated headers into a comma-joined string when the
@@ -283,13 +296,13 @@ function create(opts) {
     // verify() call below would only see the first one, leaving the
     // second unprocessed).
     if (proofHeader.indexOf(",") !== -1) {
-      return _writeUnauthorized(res, "invalid_dpop_proof",
-        "multiple DPoP proofs in one header value are not allowed");
+      return _writeUnauthorized(req, res, "invalid_dpop_proof",
+        "multiple DPoP proofs in one header value are not allowed", null, onDeny, problemMode);
     }
 
     var htu = (typeof opts.getHtu === "function" ? opts.getHtu(req) : _reconstructHtu(req, opts));
     if (!htu) {
-      return _writeUnauthorized(res, "invalid_dpop_proof", "could not reconstruct htu");
+      return _writeUnauthorized(req, res, "invalid_dpop_proof", "could not reconstruct htu", null, onDeny, problemMode);
     }
     var htm = (req.method || "").toUpperCase();
 
@@ -340,9 +353,9 @@ function create(opts) {
       if (e && (e.code === "auth-dpop/missing-nonce" || e.code === "auth-dpop/nonce-mismatch")) {
         errorCode = "use_dpop_nonce";
       }
-      return _writeUnauthorized(res, errorCode,
+      return _writeUnauthorized(req, res, errorCode,
         (e && e.message) || "DPoP proof verification failed",
-        _freshNonce());
+        _freshNonce(), onDeny, problemMode);
     }
 
     // Server-managed nonce check — payload MUST carry a recognized
@@ -360,8 +373,8 @@ function create(opts) {
             });
           } catch (_ignored) { /* drop-silent */ }
         }
-        return _writeUnauthorized(res, "use_dpop_nonce",
-          "DPoP-Nonce required (server-managed challenge)", _freshNonce());
+        return _writeUnauthorized(req, res, "use_dpop_nonce",
+          "DPoP-Nonce required (server-managed challenge)", _freshNonce(), onDeny, problemMode);
       }
     }
 

package/lib/middleware/fetch-metadata.js

@@ -36,20 +36,25 @@
 var requestHelpers = require("../request-helpers");
 var validateOpts = require("../validate-opts");
 var lazyRequire = require("../lazy-require");
+var denyResponse = require("./deny-response").denyResponse;
 
 var audit = lazyRequire(function () { return require("../audit"); });
 var observability = lazyRequire(function () { return require("../observability"); });
 
 var DEFAULT_METHODS = Object.freeze(["POST", "PUT", "DELETE", "PATCH"]);
 
-function _writeReject(res, message) {
-  if (res.headersSent) return;
-  var body = JSON.stringify({ error: message });
-  res.writeHead(requestHelpers.HTTP_STATUS.FORBIDDEN, {
-    "Content-Type":   "application/json; charset=utf-8",
-    "Content-Length": Buffer.byteLength(body),
+function _writeReject(req, res, message, reason, onDeny, problemMode) {
+  denyResponse(req, res, {
+    onDeny:        onDeny,
+    problem:       problemMode,
+    status:        requestHelpers.HTTP_STATUS.FORBIDDEN,
+    info:          { status: 403, reason: reason },
+    problemCode:   "fetch-metadata-refused",
+    problemTitle:  "Forbidden",
+    problemDetail: message,
+    contentType:   "application/json; charset=utf-8",
+    body:          JSON.stringify({ error: message }),
   });
-  res.end(body);
 }
 
 /**
@@ -79,6 +84,8 @@ function _writeReject(res, message) {
  *     allowedNavigate: boolean,    // default true
  *     methods:         string[],   // default POST/PUT/DELETE/PATCH
  *     audit:           boolean,    // default true
+ *     onDeny:          function(req, res, info): void,  // own the 403; info = { status, reason }
+ *     problemDetails:  boolean,    // default false — emit RFC 9457 application/problem+json instead of the default JSON envelope
  *   }
  *
  * @example
@@ -95,9 +102,11 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "allowSameSite", "allowCrossSite", "allowMissing",
-    "allowedDest", "allowedNavigate", "methods", "audit",
+    "allowedDest", "allowedNavigate", "methods", "audit", "onDeny", "problemDetails",
   ], "middleware.fetchMetadata");
 
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
   var allowSameSite   = opts.allowSameSite !== false;
   var allowCrossSite  = opts.allowCrossSite === true;
   var allowMissing    = opts.allowMissing !== false;
@@ -135,7 +144,7 @@ function create(opts) {
       // Defer to other auth/CSRF layers per allowMissing.
       if (!allowMissing) {
         _emitDenied(req, "fetch-metadata-missing");
-        return _writeReject(res, "Fetch-metadata required.");
+        return _writeReject(req, res, "Fetch-metadata required.", "fetch-metadata-missing", onDeny, problemMode);
       }
       return next();
     }
@@ -144,7 +153,7 @@ function create(opts) {
     if (site === "none") {
       if (allowedNavigate) return next();
       _emitDenied(req, "navigate-disallowed");
-      return _writeReject(res, "Direct navigation not allowed for this method.");
+      return _writeReject(req, res, "Direct navigation not allowed for this method.", "navigation-not-allowed", onDeny, problemMode);
     }
 
     if (site === "same-origin") return next();
@@ -152,7 +161,7 @@ function create(opts) {
     if (site === "same-site") {
       if (allowSameSite) return next();
       _emitDenied(req, "same-site-disallowed");
-      return _writeReject(res, "Same-site request not allowed.");
+      return _writeReject(req, res, "Same-site request not allowed.", "same-site-not-allowed", onDeny, problemMode);
     }
 
     // cross-site
@@ -164,7 +173,7 @@ function create(opts) {
                      ", dest=" + (dest || "?") + ")");
     try { observability().count("auth.fetch_metadata.cross_site_refused", 1, {}); }
     catch (_e) { /* best-effort */ }
-    return _writeReject(res, "Cross-site request refused.");
+    return _writeReject(req, res, "Cross-site request refused.", "cross-site-refused", onDeny, problemMode);
   };
 }