@blamejs/core 0.7.1 → 0.7.18

package/lib/middleware/csrf-protect.js

@@ -1,316 +1,316 @@
-"use strict";
-/**
- * csrf-protect — middleware that issues CSRF tokens to safe-method
- * requests AND rejects state-changing requests whose submitted token
- * doesn't match.
- *
- * Mount AFTER attachUser (when using session-stored tokens) and AFTER
- * bodyParser (when reading the token from a form field). Safe methods
- * (GET / HEAD / OPTIONS) pass through; the gate fires on POST / PUT /
- * DELETE / PATCH (configurable via opts.methods).
- *
- * Token storage — pick ONE:
- *
- *   A. Cookie-stored ("double-submit cookie", default)
- *      opts.cookie = true | { name, sameSite, secure, path, httpOnly }
- *
- *      The middleware reads the token from the configured cookie. On
- *      safe-method requests with no token cookie, it generates one and
- *      sets the cookie on the response. The same value is exposed on
- *      `req.csrfToken` for templates to render into a hidden form field.
- *      State-changing requests verify the submitted token matches the
- *      cookie value. SameSite=Lax (default) blocks cross-site form
- *      POSTs from carrying the cookie.
- *
- *      httpOnly defaults to FALSE — JavaScript needs to read it for AJAX
- *      requests. Operators relying solely on server-rendered forms can
- *      flip it to true.
- *
- *   B. Operator-supplied tokenLookup (session-stored, etc.)
- *      opts.tokenLookup = (req) => string|null
- *
- *      The middleware calls tokenLookup(req) to fetch the expected
- *      token. Use this when CSRF tokens live in your session store
- *      (e.g. req.session.data.csrfToken). Issuance + req.csrfToken
- *      exposure are the operator's responsibility in this mode.
- *
- * If neither is supplied, the middleware throws at create() —
- * config-time validation, no silent passthrough.
- *
- * Submitted-token sources tried in order on state-changing requests:
- *   1. Header `X-CSRF-Token` (or opts.headerName)
- *   2. Body field `_csrf` (or opts.fieldName) — requires bodyParser
- *      mounted before csrfProtect
- *
- * On mismatch:
- *   - Audit emit (auth.csrf.denied) with method + path + IP + reason
- *   - 403 application/json: { error: "CSRF token mismatch." }
- *   - next() NOT called
- *
- * Full options:
- *   {
- *     cookie:      true | {                  EITHER this...
- *       name:      auto: "__Host-csrf" over HTTPS, "csrf" over HTTP.
- *                  Operators with a custom name override here; the framework
- *                  validates that __Host-* names carry path="/" and Secure.
- *       sameSite:  "Lax" | "Strict" | "None",
- *       secure:    auto-detected from request scheme,
- *       path:      "/",
- *       httpOnly:  false,
- *     },
- *     tokenLookup: (req) => string|null      ...OR this
- *
- *     fieldName:   "_csrf"                   form-body field name
- *     headerName:  "X-CSRF-Token"            header name
- *     methods:     ["POST", "PUT", "DELETE", "PATCH"]
- *     audit:        true
- *   }
- */
-var lazyRequire = require("../lazy-require");
-var forms = require("../forms");
-var requestHelpers = require("../request-helpers");
-var validateOpts = require("../validate-opts");
-var audit = lazyRequire(function () { return require("../audit"); });
-
-var DEFAULT_FIELD_NAME    = "_csrf";
-var DEFAULT_HEADER_NAME   = "X-CSRF-Token";
-var DEFAULT_METHODS       = Object.freeze(["POST", "PUT", "DELETE", "PATCH"]);
-
-// Default cookie name uses the RFC 6265bis __Host- prefix when the request
-// is over HTTPS. The prefix forces browsers to refuse the cookie unless
-// it carries Secure + Path=/ + no Domain attribute — closing the
-// "malicious sibling subdomain sets a cookie on the parent domain to
-// subvert double-submit verification" attack class. On plain HTTP (dev),
-// browsers reject __Host- entirely, so we fall back to the bare name.
-var DEFAULT_COOKIE_NAME_SECURE   = "__Host-csrf";
-var DEFAULT_COOKIE_NAME_INSECURE = "csrf";
-
-function _parseCookieHeader(header) {
-  // Minimal cookie-header parser — RFC 6265 §5.2 form. Ignores attributes,
-  // just splits the name=value pairs. Keys that appear multiple times
-  // resolve to the FIRST occurrence (browsers send pairs left-to-right
-  // by registration order; the first is the most-specific path).
-  var out = {};
-  if (typeof header !== "string" || header.length === 0) return out;
-  var parts = header.split(/;\s*/);
-  for (var i = 0; i < parts.length; i++) {
-    var p = parts[i];
-    var eq = p.indexOf("=");
-    if (eq === -1) continue;
-    var k = p.slice(0, eq).trim();
-    if (k.length === 0 || Object.prototype.hasOwnProperty.call(out, k)) continue;
-    var v = p.slice(eq + 1).trim();
-    if (v.length >= 2 && v.charCodeAt(0) === 0x22 && v.charCodeAt(v.length - 1) === 0x22) {
-      v = v.slice(1, -1);
-    }
-    out[k] = v;
-  }
-  return out;
-}
-
-// `_isHttps` defers to `requestHelpers.requestProtocol` so the
-// per-middleware `trustProxy` opt gates whether X-Forwarded-Proto is
-// consulted. Without trustProxy, an attacker could otherwise forge
-// the header to force the Secure cookie attribute (and inversely,
-// suppress it) on direct-to-server connections.
-function _isHttpsFor(trustProxy) {
-  return function (req) {
-    return requestHelpers.requestProtocol(req, { trustProxy: trustProxy }) === "https";
-  };
-}
-
-function _formatSetCookie(name, value, opts) {
-  var parts = [name + "=" + value];
-  parts.push("Path=" + (opts.path || "/"));
-  parts.push("SameSite=" + (opts.sameSite || "Lax"));
-  if (opts.httpOnly) parts.push("HttpOnly");
-  if (opts.secure)   parts.push("Secure");
-  if (opts.maxAge != null) parts.push("Max-Age=" + opts.maxAge);
-  return parts.join("; ");
-}
-
-function _appendSetCookie(res, value) {
-  // Don't clobber other Set-Cookie headers the route may have already
-  // queued (login session cookie, etc.). Use res.appendHeader when
-  // available; else array-merge manually.
-  if (typeof res.appendHeader === "function") {
-    res.appendHeader("Set-Cookie", value);
-    return;
-  }
-  var existing = typeof res.getHeader === "function" ? res.getHeader("Set-Cookie") : undefined;
-  if (existing == null) {
-    res.setHeader("Set-Cookie", value);
-  } else if (Array.isArray(existing)) {
-    res.setHeader("Set-Cookie", existing.concat(value));
-  } else {
-    res.setHeader("Set-Cookie", [existing, value]);
-  }
-}
-
-// csrf-protect does NOT buffer or parse the request body itself.
-// Operators who use form-urlencoded POSTs MUST register
-// `b.middleware.bodyParser()` before csrf-protect so that
-// `req.body[fieldName]` is populated. Header-token submissions
-// (X-CSRF-Token) work without bodyParser. The body-parser primitive
-// owns size caps, content-type dispatch, and prototype-pollution
-// defense; csrf-protect just reads the validated value.
-
-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 create(opts) {
-  opts = opts || {};
-
-  validateOpts(opts, [
-    "cookie", "tokenLookup", "fieldName", "headerName", "methods", "audit",
-    "trustProxy",
-  ], "middleware.csrfProtect");
-  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
-    ? opts.trustProxy : false;
-  var _isHttps = _isHttpsFor(trustProxy);
-
-  // Throw at create() — exactly one issuance source allowed.
-  var hasCookie = opts.cookie != null && opts.cookie !== false;
-  var hasLookup = typeof opts.tokenLookup === "function";
-  if (hasCookie && hasLookup) {
-    throw new Error("middleware.csrfProtect: opts.cookie and opts.tokenLookup are " +
-      "mutually exclusive — pick one (cookie = double-submit, tokenLookup = session-stored)");
-  }
-  if (!hasCookie && !hasLookup) {
-    throw new Error("middleware.csrfProtect: opts.cookie or opts.tokenLookup is required");
-  }
-
-  var fieldName  = opts.fieldName  || DEFAULT_FIELD_NAME;
-  var headerName = (opts.headerName || DEFAULT_HEADER_NAME).toLowerCase();
-  var methods    = (opts.methods || DEFAULT_METHODS).map(function (m) { return m.toUpperCase(); });
-  var auditOn    = opts.audit !== false;
-
-  // Cookie issuance config (only when opts.cookie is set).
-  var cookieCfg = null;
-  if (hasCookie) {
-    var raw = opts.cookie === true ? {} : opts.cookie;
-    if (typeof raw !== "object") {
-      throw new Error("middleware.csrfProtect: opts.cookie must be true or an object");
-    }
-    cookieCfg = {
-      // name: explicit operator override wins; otherwise auto-resolved
-      // per-request based on whether the cookie is being issued Secure.
-      name:     raw.name || null,
-      sameSite: raw.sameSite || "Lax",
-      // secure: undefined means auto-detect from request scheme; explicit
-      // true/false overrides.
-      secure:   raw.secure,
-      path:     raw.path     || "/",
-      httpOnly: !!raw.httpOnly,
-      maxAge:   raw.maxAge != null ? raw.maxAge : null,
-    };
-    if (["Lax", "Strict", "None"].indexOf(cookieCfg.sameSite) === -1) {
-      throw new Error("middleware.csrfProtect: opts.cookie.sameSite must be Lax|Strict|None");
-    }
-    // __Host- prefix safety: if operator picks a __Host- name, the
-    // Path/Domain/Secure constraints must be compatible. Path must be "/",
-    // no Domain (we never set one), Secure resolved per-request. Catch
-    // operator-side typos (e.g. __Host-csrf with a custom path) at boot.
-    if (cookieCfg.name && /^__Host-/.test(cookieCfg.name)) {
-      if (cookieCfg.path !== "/") {
-        throw new Error("middleware.csrfProtect: __Host-* cookie name requires path='/'");
-      }
-      if (cookieCfg.secure === false) {
-        throw new Error("middleware.csrfProtect: __Host-* cookie name requires secure (cannot be explicit false)");
-      }
-    }
-  }
-
-  // Resolve the cookie name for a specific request — operator override
-  // wins; otherwise __Host-csrf when the cookie will be Secure, plain
-  // csrf when over HTTP (browsers reject __Host- without Secure).
-  function _resolveCookieName(req) {
-    if (cookieCfg.name) return cookieCfg.name;
-    var willBeSecure = cookieCfg.secure == null ? _isHttps(req) : !!cookieCfg.secure;
-    return willBeSecure ? DEFAULT_COOKIE_NAME_SECURE : DEFAULT_COOKIE_NAME_INSECURE;
-  }
-
-  function _emitDenied(req, reason) {
-    if (!auditOn) return;
-    audit().safeEmit({
-      action:   "auth.csrf.denied",
-      outcome:  "denied",
-      actor:    requestHelpers.extractActorContext(req),
-      reason:   reason,
-      metadata: { method: req.method, path: (req.url || "").split("?")[0] },
-    });
-  }
-
-  // Issuance path (cookie mode): on safe-method requests with no cookie,
-  // generate a token and queue it for the response. Always populate
-  // req.csrfToken so templates have something to render.
-  function _issueIfNeeded(req, res) {
-    if (!cookieCfg) return null;
-    var cookieName = _resolveCookieName(req);
-    var cookies = _parseCookieHeader(req.headers && req.headers.cookie);
-    var existing = cookies[cookieName];
-    if (existing && /^[a-f0-9]{2,}$/.test(existing)) {
-      req.csrfToken = existing;
-      return existing;
-    }
-    var fresh = forms.generateCsrfToken();
-    var setCookie = _formatSetCookie(cookieName, fresh, {
-      path:     cookieCfg.path,
-      sameSite: cookieCfg.sameSite,
-      secure:   cookieCfg.secure == null ? _isHttps(req) : !!cookieCfg.secure,
-      httpOnly: cookieCfg.httpOnly,
-      maxAge:   cookieCfg.maxAge,
-    });
-    _appendSetCookie(res, setCookie);
-    req.csrfToken = fresh;
-    return fresh;
-  }
-
-  return function csrfProtect(req, res, next) {
-    // Issue/refresh the token on EVERY request (safe + state-changing)
-    // when running in cookie mode — templates rendered after a POST
-    // (e.g. error response) still need req.csrfToken populated.
-    var expected = _issueIfNeeded(req, res);
-
-    if (methods.indexOf(req.method) === -1) return next();
-
-    if (!cookieCfg) {
-      // Session-stored mode — operator's tokenLookup is the source.
-      expected = opts.tokenLookup(req);
-    }
-    if (!expected) {
-      _emitDenied(req, cookieCfg ? "no token cookie issued yet" : "no expected token in session");
-      return _writeReject(res, "CSRF token mismatch.");
-    }
-
-    // Header path first — covers JSON / AJAX / multipart cases.
-    var submitted = req.headers && req.headers[headerName];
-    if (typeof submitted !== "string" || submitted.length === 0) {
-      // Fall back to body field if bodyParser already populated req.body.
-      // Operators with form-urlencoded POSTs are expected to register
-      // bodyParser before csrf-protect; body buffering / parsing lives
-      // in bodyParser, not here.
-      if (req.body && typeof req.body === "object") {
-        var v = req.body[fieldName];
-        if (typeof v === "string") submitted = v;
-      }
-    }
-
-    if (!forms.verifyCsrfToken(submitted || "", expected)) {
-      _emitDenied(req, "submitted token does not match expected");
-      return _writeReject(res, "CSRF token mismatch.");
-    }
-
-    return next();
-  };
-}
-
-module.exports = { create: create };
+"use strict";
+/**
+ * csrf-protect — middleware that issues CSRF tokens to safe-method
+ * requests AND rejects state-changing requests whose submitted token
+ * doesn't match.
+ *
+ * Mount AFTER attachUser (when using session-stored tokens) and AFTER
+ * bodyParser (when reading the token from a form field). Safe methods
+ * (GET / HEAD / OPTIONS) pass through; the gate fires on POST / PUT /
+ * DELETE / PATCH (configurable via opts.methods).
+ *
+ * Token storage — pick ONE:
+ *
+ *   A. Cookie-stored ("double-submit cookie", default)
+ *      opts.cookie = true | { name, sameSite, secure, path, httpOnly }
+ *
+ *      The middleware reads the token from the configured cookie. On
+ *      safe-method requests with no token cookie, it generates one and
+ *      sets the cookie on the response. The same value is exposed on
+ *      `req.csrfToken` for templates to render into a hidden form field.
+ *      State-changing requests verify the submitted token matches the
+ *      cookie value. SameSite=Lax (default) blocks cross-site form
+ *      POSTs from carrying the cookie.
+ *
+ *      httpOnly defaults to FALSE — JavaScript needs to read it for AJAX
+ *      requests. Operators relying solely on server-rendered forms can
+ *      flip it to true.
+ *
+ *   B. Operator-supplied tokenLookup (session-stored, etc.)
+ *      opts.tokenLookup = (req) => string|null
+ *
+ *      The middleware calls tokenLookup(req) to fetch the expected
+ *      token. Use this when CSRF tokens live in your session store
+ *      (e.g. req.session.data.csrfToken). Issuance + req.csrfToken
+ *      exposure are the operator's responsibility in this mode.
+ *
+ * If neither is supplied, the middleware throws at create() —
+ * config-time validation, no silent passthrough.
+ *
+ * Submitted-token sources tried in order on state-changing requests:
+ *   1. Header `X-CSRF-Token` (or opts.headerName)
+ *   2. Body field `_csrf` (or opts.fieldName) — requires bodyParser
+ *      mounted before csrfProtect
+ *
+ * On mismatch:
+ *   - Audit emit (auth.csrf.denied) with method + path + IP + reason
+ *   - 403 application/json: { error: "CSRF token mismatch." }
+ *   - next() NOT called
+ *
+ * Full options:
+ *   {
+ *     cookie:      true | {                  EITHER this...
+ *       name:      auto: "__Host-csrf" over HTTPS, "csrf" over HTTP.
+ *                  Operators with a custom name override here; the framework
+ *                  validates that __Host-* names carry path="/" and Secure.
+ *       sameSite:  "Lax" | "Strict" | "None",
+ *       secure:    auto-detected from request scheme,
+ *       path:      "/",
+ *       httpOnly:  false,
+ *     },
+ *     tokenLookup: (req) => string|null      ...OR this
+ *
+ *     fieldName:   "_csrf"                   form-body field name
+ *     headerName:  "X-CSRF-Token"            header name
+ *     methods:     ["POST", "PUT", "DELETE", "PATCH"]
+ *     audit:        true
+ *   }
+ */
+var lazyRequire = require("../lazy-require");
+var forms = require("../forms");
+var requestHelpers = require("../request-helpers");
+var validateOpts = require("../validate-opts");
+var audit = lazyRequire(function () { return require("../audit"); });
+
+var DEFAULT_FIELD_NAME    = "_csrf";
+var DEFAULT_HEADER_NAME   = "X-CSRF-Token";
+var DEFAULT_METHODS       = Object.freeze(["POST", "PUT", "DELETE", "PATCH"]);
+
+// Default cookie name uses the RFC 6265bis __Host- prefix when the request
+// is over HTTPS. The prefix forces browsers to refuse the cookie unless
+// it carries Secure + Path=/ + no Domain attribute — closing the
+// "malicious sibling subdomain sets a cookie on the parent domain to
+// subvert double-submit verification" attack class. On plain HTTP (dev),
+// browsers reject __Host- entirely, so we fall back to the bare name.
+var DEFAULT_COOKIE_NAME_SECURE   = "__Host-csrf";
+var DEFAULT_COOKIE_NAME_INSECURE = "csrf";
+
+function _parseCookieHeader(header) {
+  // Minimal cookie-header parser — RFC 6265 §5.2 form. Ignores attributes,
+  // just splits the name=value pairs. Keys that appear multiple times
+  // resolve to the FIRST occurrence (browsers send pairs left-to-right
+  // by registration order; the first is the most-specific path).
+  var out = {};
+  if (typeof header !== "string" || header.length === 0) return out;
+  var parts = header.split(/;\s*/);
+  for (var i = 0; i < parts.length; i++) {
+    var p = parts[i];
+    var eq = p.indexOf("=");
+    if (eq === -1) continue;
+    var k = p.slice(0, eq).trim();
+    if (k.length === 0 || Object.prototype.hasOwnProperty.call(out, k)) continue;
+    var v = p.slice(eq + 1).trim();
+    if (v.length >= 2 && v.charCodeAt(0) === 0x22 && v.charCodeAt(v.length - 1) === 0x22) {
+      v = v.slice(1, -1);
+    }
+    out[k] = v;
+  }
+  return out;
+}
+
+// `_isHttps` defers to `requestHelpers.requestProtocol` so the
+// per-middleware `trustProxy` opt gates whether X-Forwarded-Proto is
+// consulted. Without trustProxy, an attacker could otherwise forge
+// the header to force the Secure cookie attribute (and inversely,
+// suppress it) on direct-to-server connections.
+function _isHttpsFor(trustProxy) {
+  return function (req) {
+    return requestHelpers.requestProtocol(req, { trustProxy: trustProxy }) === "https";
+  };
+}
+
+function _formatSetCookie(name, value, opts) {
+  var parts = [name + "=" + value];
+  parts.push("Path=" + (opts.path || "/"));
+  parts.push("SameSite=" + (opts.sameSite || "Lax"));
+  if (opts.httpOnly) parts.push("HttpOnly");
+  if (opts.secure)   parts.push("Secure");
+  if (opts.maxAge != null) parts.push("Max-Age=" + opts.maxAge);
+  return parts.join("; ");
+}
+
+function _appendSetCookie(res, value) {
+  // Don't clobber other Set-Cookie headers the route may have already
+  // queued (login session cookie, etc.). Use res.appendHeader when
+  // available; else array-merge manually.
+  if (typeof res.appendHeader === "function") {
+    res.appendHeader("Set-Cookie", value);
+    return;
+  }
+  var existing = typeof res.getHeader === "function" ? res.getHeader("Set-Cookie") : undefined;
+  if (existing == null) {
+    res.setHeader("Set-Cookie", value);
+  } else if (Array.isArray(existing)) {
+    res.setHeader("Set-Cookie", existing.concat(value));
+  } else {
+    res.setHeader("Set-Cookie", [existing, value]);
+  }
+}
+
+// csrf-protect does NOT buffer or parse the request body itself.
+// Operators who use form-urlencoded POSTs MUST register
+// `b.middleware.bodyParser()` before csrf-protect so that
+// `req.body[fieldName]` is populated. Header-token submissions
+// (X-CSRF-Token) work without bodyParser. The body-parser primitive
+// owns size caps, content-type dispatch, and prototype-pollution
+// defense; csrf-protect just reads the validated value.
+
+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 create(opts) {
+  opts = opts || {};
+
+  validateOpts(opts, [
+    "cookie", "tokenLookup", "fieldName", "headerName", "methods", "audit",
+    "trustProxy",
+  ], "middleware.csrfProtect");
+  var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
+    ? opts.trustProxy : false;
+  var _isHttps = _isHttpsFor(trustProxy);
+
+  // Throw at create() — exactly one issuance source allowed.
+  var hasCookie = opts.cookie != null && opts.cookie !== false;
+  var hasLookup = typeof opts.tokenLookup === "function";
+  if (hasCookie && hasLookup) {
+    throw new Error("middleware.csrfProtect: opts.cookie and opts.tokenLookup are " +
+      "mutually exclusive — pick one (cookie = double-submit, tokenLookup = session-stored)");
+  }
+  if (!hasCookie && !hasLookup) {
+    throw new Error("middleware.csrfProtect: opts.cookie or opts.tokenLookup is required");
+  }
+
+  var fieldName  = opts.fieldName  || DEFAULT_FIELD_NAME;
+  var headerName = (opts.headerName || DEFAULT_HEADER_NAME).toLowerCase();
+  var methods    = (opts.methods || DEFAULT_METHODS).map(function (m) { return m.toUpperCase(); });
+  var auditOn    = opts.audit !== false;
+
+  // Cookie issuance config (only when opts.cookie is set).
+  var cookieCfg = null;
+  if (hasCookie) {
+    var raw = opts.cookie === true ? {} : opts.cookie;
+    if (typeof raw !== "object") {
+      throw new Error("middleware.csrfProtect: opts.cookie must be true or an object");
+    }
+    cookieCfg = {
+      // name: explicit operator override wins; otherwise auto-resolved
+      // per-request based on whether the cookie is being issued Secure.
+      name:     raw.name || null,
+      sameSite: raw.sameSite || "Lax",
+      // secure: undefined means auto-detect from request scheme; explicit
+      // true/false overrides.
+      secure:   raw.secure,
+      path:     raw.path     || "/",
+      httpOnly: !!raw.httpOnly,
+      maxAge:   raw.maxAge != null ? raw.maxAge : null,
+    };
+    if (["Lax", "Strict", "None"].indexOf(cookieCfg.sameSite) === -1) {
+      throw new Error("middleware.csrfProtect: opts.cookie.sameSite must be Lax|Strict|None");
+    }
+    // __Host- prefix safety: if operator picks a __Host- name, the
+    // Path/Domain/Secure constraints must be compatible. Path must be "/",
+    // no Domain (we never set one), Secure resolved per-request. Catch
+    // operator-side typos (e.g. __Host-csrf with a custom path) at boot.
+    if (cookieCfg.name && /^__Host-/.test(cookieCfg.name)) {
+      if (cookieCfg.path !== "/") {
+        throw new Error("middleware.csrfProtect: __Host-* cookie name requires path='/'");
+      }
+      if (cookieCfg.secure === false) {
+        throw new Error("middleware.csrfProtect: __Host-* cookie name requires secure (cannot be explicit false)");
+      }
+    }
+  }
+
+  // Resolve the cookie name for a specific request — operator override
+  // wins; otherwise __Host-csrf when the cookie will be Secure, plain
+  // csrf when over HTTP (browsers reject __Host- without Secure).
+  function _resolveCookieName(req) {
+    if (cookieCfg.name) return cookieCfg.name;
+    var willBeSecure = cookieCfg.secure == null ? _isHttps(req) : !!cookieCfg.secure;
+    return willBeSecure ? DEFAULT_COOKIE_NAME_SECURE : DEFAULT_COOKIE_NAME_INSECURE;
+  }
+
+  function _emitDenied(req, reason) {
+    if (!auditOn) return;
+    audit().safeEmit({
+      action:   "auth.csrf.denied",
+      outcome:  "denied",
+      actor:    requestHelpers.extractActorContext(req),
+      reason:   reason,
+      metadata: { method: req.method, path: (req.url || "").split("?")[0] },
+    });
+  }
+
+  // Issuance path (cookie mode): on safe-method requests with no cookie,
+  // generate a token and queue it for the response. Always populate
+  // req.csrfToken so templates have something to render.
+  function _issueIfNeeded(req, res) {
+    if (!cookieCfg) return null;
+    var cookieName = _resolveCookieName(req);
+    var cookies = _parseCookieHeader(req.headers && req.headers.cookie);
+    var existing = cookies[cookieName];
+    if (existing && /^[a-f0-9]{2,}$/.test(existing)) {
+      req.csrfToken = existing;
+      return existing;
+    }
+    var fresh = forms.generateCsrfToken();
+    var setCookie = _formatSetCookie(cookieName, fresh, {
+      path:     cookieCfg.path,
+      sameSite: cookieCfg.sameSite,
+      secure:   cookieCfg.secure == null ? _isHttps(req) : !!cookieCfg.secure,
+      httpOnly: cookieCfg.httpOnly,
+      maxAge:   cookieCfg.maxAge,
+    });
+    _appendSetCookie(res, setCookie);
+    req.csrfToken = fresh;
+    return fresh;
+  }
+
+  return function csrfProtect(req, res, next) {
+    // Issue/refresh the token on EVERY request (safe + state-changing)
+    // when running in cookie mode — templates rendered after a POST
+    // (e.g. error response) still need req.csrfToken populated.
+    var expected = _issueIfNeeded(req, res);
+
+    if (methods.indexOf(req.method) === -1) return next();
+
+    if (!cookieCfg) {
+      // Session-stored mode — operator's tokenLookup is the source.
+      expected = opts.tokenLookup(req);
+    }
+    if (!expected) {
+      _emitDenied(req, cookieCfg ? "no token cookie issued yet" : "no expected token in session");
+      return _writeReject(res, "CSRF token mismatch.");
+    }
+
+    // Header path first — covers JSON / AJAX / multipart cases.
+    var submitted = req.headers && req.headers[headerName];
+    if (typeof submitted !== "string" || submitted.length === 0) {
+      // Fall back to body field if bodyParser already populated req.body.
+      // Operators with form-urlencoded POSTs are expected to register
+      // bodyParser before csrf-protect; body buffering / parsing lives
+      // in bodyParser, not here.
+      if (req.body && typeof req.body === "object") {
+        var v = req.body[fieldName];
+        if (typeof v === "string") submitted = v;
+      }
+    }
+
+    if (!forms.verifyCsrfToken(submitted || "", expected)) {
+      _emitDenied(req, "submitted token does not match expected");
+      return _writeReject(res, "CSRF token mismatch.");
+    }
+
+    return next();
+  };
+}
+
+module.exports = { create: create };