@blamejs/core 0.7.64 → 0.7.74

package/lib/mail.js

@@ -71,7 +71,9 @@ var httpClient = lazyRequire(function () { return require("./http-client"); });
 var guardEmail = lazyRequire(function () { return require("./guard-email"); });
 var mailDkim = require("./mail-dkim");
 var mailAuth = require("./mail-auth");
+var mailUnsubscribe = require("./mail-unsubscribe");
 var net = lazyRequire(function () { return require("net"); });
+var nodeUrl = require("url");
 var tls = lazyRequire(function () { return require("tls"); });
 var safeJson = require("./safe-json");
 var safeSchema = require("./safe-schema");
@@ -100,9 +102,86 @@ var EMAIL_RE = safeSchema.EMAIL_RE;
 // test so a megabyte-long input can't exhaust the regex engine.
 var EMAIL_MAX_LEN = 254;
 
+// EAI / SMTPUTF8 — RFC 6531/6532/6533 internationalized email. Detect
+// non-ASCII content; convert IDN domains to Punycode (RFC 3492) for the
+// ASCII path, leave them in Unicode where the peer announces SMTPUTF8.
+
+// Match any code point outside ASCII (U+0080 and above). Used to
+// detect EAI / SMTPUTF8-required content in an address or subject.
+// eslint-disable-next-line no-control-regex
+var NON_ASCII_RE = /[^\x00-\x7f]/;
+
+function _isAscii(s) {
+  if (typeof s !== "string" || s.length > EMAIL_MAX_LEN) return false;     // bound BEFORE regex test
+  return !NON_ASCII_RE.test(s);
+}
+
+// IDN domain encode — domain MUST be the part after '@'. Returns the
+// Punycode-encoded ASCII domain, OR null if the input isn't a valid
+// IDN-encodable domain.
+function toAscii(domain) {
+  if (typeof domain !== "string" || domain.length === 0) return null;
+  var ascii;
+  try { ascii = nodeUrl.domainToASCII(domain); }
+  catch (_e) { return null; }
+  if (typeof ascii !== "string" || ascii.length === 0) return null;
+  return ascii;
+}
+
+function toUnicode(domain) {
+  if (typeof domain !== "string" || domain.length === 0) return null;
+  try { return nodeUrl.domainToUnicode(domain); }
+  catch (_e) { return null; }
+}
+
 function _isValidEmail(addr) {
-  return typeof addr === "string" && addr.length > 0 &&
-    addr.length <= EMAIL_MAX_LEN && EMAIL_RE.test(addr);
+  if (typeof addr !== "string" || addr.length === 0 || addr.length > EMAIL_MAX_LEN) {
+    return false;
+  }
+  // Pure ASCII — fast path through the existing regex (length bounded above).
+  if (_isAscii(addr)) return EMAIL_RE.test(addr);                          // bound: addr.length <= EMAIL_MAX_LEN
+  // EAI path — split at last '@', convert domain to Punycode, then test
+  // ASCII-only the assembled local@ascii-domain. The local part can be
+  // Unicode under RFC 6531 §3.3 — we accept it without further regex
+  // gating beyond the existing CRLF/NUL refusals upstream.
+  var atIdx = addr.lastIndexOf("@");
+  if (atIdx <= 0 || atIdx === addr.length - 1) return false;
+  var local = addr.slice(0, atIdx);
+  var domain = addr.slice(atIdx + 1);
+  var ascii = toAscii(domain);
+  if (!ascii) return false;
+  // Re-test the ASCII-converted domain against the existing email regex
+  // to refuse junk like "..invalid" that domainToASCII rubber-stamps
+  // (Node's WHATWG-URL implementation is permissive on dotted-empty
+  // labels). Substitute a placeholder local part so the regex sees an
+  // ASCII-only shape; the actual local part may legitimately be Unicode
+  // under RFC 6531 §3.3 and is enforced separately below.
+  if (ascii.length > EMAIL_MAX_LEN - 2) return false;                      // bound BEFORE regex test
+  if (!EMAIL_RE.test("x@" + ascii)) return false;
+  // Local part must not contain CRLF / NUL (header injection / SMTP
+  // smuggling). Other Unicode is fine per RFC 6531.
+  if (/[\r\n\0]/.test(local)) return false;
+  // Length cap also applies to the ASCII-equivalent so a long IDN
+  // domain that punycodes to >254 ASCII bytes is refused.
+  if ((local.length + 1 + ascii.length) > EMAIL_MAX_LEN) return false;
+  return true;
+}
+
+// Does this message require SMTPUTF8 on the wire?  RFC 6531 §3.2 — true
+// when any of from / to / cc / bcc / subject / mailbox-display-name
+// contains non-ASCII octets.
+function _messageRequiresSmtpUtf8(message) {
+  if (!message) return false;
+  if (!_isAscii(String(message.from || ""))) return true;
+  if (!_isAscii(String(message.subject || ""))) return true;
+  var lists = [message.to, message.cc, message.bcc];
+  for (var li = 0; li < lists.length; li += 1) {
+    var arr = Array.isArray(lists[li]) ? lists[li] : (lists[li] ? [lists[li]] : []);
+    for (var i = 0; i < arr.length; i += 1) {
+      if (!_isAscii(String(arr[i]))) return true;
+    }
+  }
+  return false;
 }
 
 function _normalizeRecipientList(value, label) {
@@ -511,11 +590,21 @@ var SMTP_STEP_DATA       = 0x7;
 var SMTP_STEP_BODY       = 0x8;
 var SMTP_STEP_STARTTLS   = 0xA;
 
+function _smtpUtf8Suffix(requiresSmtpUtf8, peerSupportsSmtpUtf8) {
+  // RFC 6531 §3.4 — when SMTPUTF8 is advertised by the peer AND the
+  // message requires it, append " SMTPUTF8" to MAIL FROM to opt this
+  // transaction into the EAI extension. Pure-ASCII messages don't add
+  // it (some peers reject the keyword on legacy mailboxes).
+  return (requiresSmtpUtf8 && peerSupportsSmtpUtf8) ? " SMTPUTF8" : "";
+}
+
 function _smtpSend(message, cfg) {
   return new Promise(function (resolve, reject) {
     var socket;
     var step = SMTP_STEP_GREETING;
     var buffer = "";
+    var ehloLines = [];                  // RFC 5321 §4.1.1.1 — EHLO extension lines
+    var peerSupportsSmtpUtf8 = false;    // RFC 6531 — set from EHLO response
     var upgradedToTLS = false;
     var settled = false;
     var rcptIndex = 0;
@@ -525,6 +614,7 @@ function _smtpSend(message, cfg) {
     var ccList   = _toArray(message.cc).map(_extractAddr);
     var bccList  = _toArray(message.bcc).map(_extractAddr);
     var rcpts    = toList.concat(ccList, bccList);
+    var requiresSmtpUtf8 = _messageRequiresSmtpUtf8(message);
     var dataMessage = _buildRfc822(message);
     if (cfg.dkimSigner) {
       try { dataMessage = cfg.dkimSigner.sign(dataMessage); }
@@ -582,6 +672,13 @@ function _smtpSend(message, cfg) {
         var line = lines[i];
         if (!line) continue;
         var code = parseInt(line.slice(0, 3), 10);
+        // EHLO continuation lines (250-X) carry extension names. We
+        // capture them so the dispatcher can branch on SMTPUTF8 / 8BITMIME
+        // / STARTTLS support before MAIL FROM is sent.
+        if (step === SMTP_STEP_EHLO_RESP) {
+          var keyword = line.slice(4).split(" ")[0].toUpperCase();
+          if (keyword) ehloLines.push(keyword);
+        }
         if (line[3] === "-") continue; // continuation line
         try { handleResponse(code); }
         catch (e) { fail(e.message || String(e)); return; }
@@ -615,9 +712,19 @@ function _smtpSend(message, cfg) {
       }
       else if (step === SMTP_STEP_EHLO_RESP) {
         if (code < 200 || code >= 300) { fail("ehlo-rejected (code " + code + ")"); return; }
+        // Snapshot extensions advertised on the wire for downstream use.
+        peerSupportsSmtpUtf8 = ehloLines.indexOf("SMTPUTF8") !== -1;
+        // RFC 6531 §3.2 — if the message requires SMTPUTF8 and the
+        // peer does not advertise it, refuse hard rather than emit a
+        // mangled wire (server might still accept but headers/local
+        // parts would silently corrupt downstream).
+        if (requiresSmtpUtf8 && !peerSupportsSmtpUtf8) {
+          fail("eai-required-not-supported: message has non-ASCII content but peer does not advertise SMTPUTF8");
+          return;
+        }
         if (!cfg.useImplicitTLS && !upgradedToTLS) { send("STARTTLS"); step = SMTP_STEP_STARTTLS; }
         else if (cfg.user) { send("AUTH LOGIN"); step = SMTP_STEP_AUTH_USER; }
-        else { send("MAIL FROM:<" + fromAddr + ">"); step = SMTP_STEP_MAIL_FROM; }
+        else { send("MAIL FROM:<" + fromAddr + ">" + _smtpUtf8Suffix(requiresSmtpUtf8, peerSupportsSmtpUtf8)); step = SMTP_STEP_MAIL_FROM; }
       }
       else if (step === SMTP_STEP_STARTTLS) {
         if (code !== 220) { fail("starttls-rejected (code " + code + ")"); return; }
@@ -644,7 +751,7 @@ function _smtpSend(message, cfg) {
       }
       else if (step === SMTP_STEP_AUTH_FINAL) {
         if (code !== 235) { fail("auth-failed (code " + code + ")"); return; }
-        send("MAIL FROM:<" + fromAddr + ">"); step = SMTP_STEP_MAIL_FROM;
+        send("MAIL FROM:<" + fromAddr + ">" + _smtpUtf8Suffix(requiresSmtpUtf8, peerSupportsSmtpUtf8)); step = SMTP_STEP_MAIL_FROM;
       }
       else if (step === SMTP_STEP_MAIL_FROM) {
         if (code < 200 || code >= 300) { fail("mail-from-rejected (code " + code + ")"); return; }
@@ -921,6 +1028,16 @@ function create(opts) {
 
   async function send(message) {
     var merged = _mergeMessage(defaults, message);
+    // RFC 8058 / RFC 2369 List-Unsubscribe support: when the operator
+    // passes `unsubscribe: { url, mailto, oneClick }`, expand into the
+    // header pair and merge into the message headers. Lets bulk
+    // senders comply with the Gmail / Yahoo / Microsoft bulk-sender
+    // mandate without hand-rolling the header byte sequence.
+    if (merged.unsubscribe && typeof merged.unsubscribe === "object") {
+      var unsubHeaders = mailUnsubscribe.buildHeaders(merged.unsubscribe);
+      merged.headers = Object.assign({}, merged.headers || {}, unsubHeaders);
+      delete merged.unsubscribe;
+    }
     _validateMessage(merged);
 
     var t0 = Date.now();
@@ -963,8 +1080,16 @@ function create(opts) {
 }
 
 module.exports = {
-  create:     create,
-  MailError:  MailError,
+  create:      create,
+  MailError:   MailError,
+  unsubscribe: mailUnsubscribe,
+  // RFC 3492 Punycode IDN domain encode/decode (b.mail.toAscii /
+  // toUnicode). Wraps node:url.domainToASCII / domainToUnicode so
+  // operators have one obvious place to reach for IDN handling. Used
+  // internally by send() to convert IDN domain parts before the
+  // pre-SMTPUTF8 ASCII regex check.
+  toAscii:    toAscii,
+  toUnicode:  toUnicode,
   // DKIM-Signature header generation for outbound mail (rsa-sha256
   // default, ed25519-sha256 opt-in). Wire it into the smtp transport
   // via opts.dkimSigner. See lib/mail-dkim.js for the full surface.
@@ -973,9 +1098,10 @@ module.exports = {
   // DMARC (RFC 7489), ARC (RFC 8617). Outbound DKIM signing lives in
   // .dkim above; per-hop DKIM verification is deferred (composes with
   // the existing canonicalization helpers in lib/mail-dkim.js).
-  spf:        mailAuth.spf,
-  dmarc:      mailAuth.dmarc,
-  arc:        mailAuth.arc,
+  spf:         mailAuth.spf,
+  dmarc:       mailAuth.dmarc,
+  arc:         mailAuth.arc,
+  authResults: mailAuth.authResults,
   // Test-only export: lets unit tests inspect the wire format without
   // standing up a TLS-capable SMTP fixture. Operators don't call this.
   _buildRfc822ForTest: _buildRfc822,

package/lib/middleware/dpop.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * dpop middleware — RFC 9449 Demonstrating Proof of Possession.
+ *
+ * Verifies the `DPoP` header on inbound requests, attaches the result
+ * to `req.dpop = { header, payload, jkt }` for downstream handlers, and
+ * rejects with 401 + `WWW-Authenticate: DPoP` on any failure.
+ *
+ *   var dpop = b.middleware.dpop({
+ *     replayStore:    b.nonceStore.create({ backend: "memory" }),
+ *     algorithms:     ["ES256", "EdDSA", "ML-DSA-87"],
+ *     iatWindowSec:   60,
+ *     getAccessToken: function (req) {
+ *       // optional — extract Bearer token to bind ath
+ *       var h = req.headers.authorization || "";
+ *       return h.toLowerCase().startsWith("bearer ") ? h.slice(7) : null;
+ *     },
+ *     getNonce: async function (req) {
+ *       // optional — server-issued challenge (RFC 9449 §8); return null
+ *       // to skip nonce enforcement
+ *       return null;
+ *     },
+ *     audit: true,
+ *   });
+ *   router.use("/api", dpop);
+ *
+ * On success:
+ *   - req.dpop = { header, payload, jkt }
+ *   - downstream handlers can compare req.dpop.jkt to the cnf claim
+ *     of the access token to enforce key-bound bearer semantics
+ *
+ * On failure:
+ *   - 401 with WWW-Authenticate: DPoP error="invalid_dpop_proof",
+ *     error_description="<reason>"
+ *   - audit.bearer.failure event when audit: true (default)
+ */
+
+var lazyRequire = require("../lazy-require");
+var requestHelpers = require("../request-helpers");
+var validateOpts = require("../validate-opts");
+var { AuthError } = require("../framework-error");
+
+var dpop = lazyRequire(function () { return require("../auth/dpop"); });
+var audit = lazyRequire(function () { return require("../audit"); });
+
+function _writeUnauthorized(res, errorCode, description) {
+  if (res.headersSent) return;
+  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, "'") + '"';
+  res.writeHead(401, {                                                             // allow:raw-byte-literal — HTTP 401 status
+    "Content-Type":     "application/json; charset=utf-8",
+    "Content-Length":   Buffer.byteLength(body),
+    "WWW-Authenticate": challenge,
+  });
+  res.end(body);
+}
+
+function _reconstructHtu(req) {
+  // The proof's htu is the request URI WITHOUT query/fragment. Behind
+  // a reverse proxy the operator may need to override via opts.htu /
+  // opts.getHtu — defaults read X-Forwarded-* if present.
+  var proto = req.headers["x-forwarded-proto"] || (req.socket && req.socket.encrypted ? "https" : "http");
+  var host = req.headers["x-forwarded-host"] || req.headers.host;
+  if (!host) return null;
+  var path = req.url || "/";
+  var qIdx = path.indexOf("?");
+  if (qIdx !== -1) path = path.slice(0, qIdx);
+  var hIdx = path.indexOf("#");
+  if (hIdx !== -1) path = path.slice(0, hIdx);
+  return proto + "://" + host + path;
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "replayStore", "algorithms", "iatWindowSec",
+    "getAccessToken", "getNonce", "getHtu", "audit",
+  ], "middleware.dpop");
+
+  var auditOn = opts.audit !== false;
+  var algorithms = opts.algorithms;
+  var iatWindowSec = opts.iatWindowSec;
+  var replayStore = opts.replayStore;
+
+  validateOpts.optionalFunction(opts.getAccessToken,
+    "middleware.dpop: getAccessToken", AuthError, "auth-dpop/bad-opt");
+  validateOpts.optionalFunction(opts.getNonce,
+    "middleware.dpop: getNonce", AuthError, "auth-dpop/bad-opt");
+  validateOpts.optionalFunction(opts.getHtu,
+    "middleware.dpop: getHtu", AuthError, "auth-dpop/bad-opt");
+
+  return async function dpopMiddleware(req, res, next) {
+    var proofHeader = req.headers && req.headers.dpop;
+    if (typeof proofHeader !== "string" || proofHeader.length === 0) {
+      return _writeUnauthorized(res, "invalid_dpop_proof", "DPoP header required");
+    }
+    // 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");
+    }
+
+    var htu = (typeof opts.getHtu === "function" ? opts.getHtu(req) : _reconstructHtu(req));
+    if (!htu) {
+      return _writeUnauthorized(res, "invalid_dpop_proof", "could not reconstruct htu");
+    }
+    var htm = (req.method || "").toUpperCase();
+
+    var accessToken = null;
+    if (typeof opts.getAccessToken === "function") {
+      try { accessToken = await opts.getAccessToken(req); }
+      catch (_e) { accessToken = null; }
+    }
+    var nonce = null;
+    if (typeof opts.getNonce === "function") {
+      try { nonce = await opts.getNonce(req); }
+      catch (_e) { nonce = null; }
+    }
+
+    var verifyOpts = { htm: htm, htu: htu };
+    if (algorithms) verifyOpts.algorithms = algorithms;
+    if (iatWindowSec !== undefined) verifyOpts.iatWindowSec = iatWindowSec;
+    if (accessToken) verifyOpts.accessToken = accessToken;
+    if (nonce) verifyOpts.nonce = nonce;
+    if (replayStore) verifyOpts.replayStore = replayStore;
+
+    var result;
+    try { result = await dpop().verify(proofHeader, verifyOpts); }
+    catch (e) {
+      if (auditOn) {
+        try {
+          audit().safeEmit({
+            action:  "auth.bearer.failure",
+            actor:   { clientIp: requestHelpers.clientIp(req) },
+            outcome: "fail",
+            metadata: {
+              method: "dpop",
+              reason: (e && e.code) || "verify-failed",
+              route:  req.url,
+            },
+          });
+        } catch (_ignored) { /* drop-silent — observability sink failure */ }
+      }
+      var errorCode = "invalid_dpop_proof";
+      // RFC 9449 §8 — when nonce is missing/invalid the server SHOULD use
+      // use_dpop_nonce to signal the client to retry with a new nonce.
+      if (e && (e.code === "auth-dpop/missing-nonce" || e.code === "auth-dpop/nonce-mismatch")) {
+        errorCode = "use_dpop_nonce";
+      }
+      return _writeUnauthorized(res, errorCode,
+        (e && e.message) || "DPoP proof verification failed");
+    }
+
+    req.dpop = result;
+    if (auditOn) {
+      try {
+        audit().safeEmit({
+          action:  "auth.bearer.success",
+          actor:   { clientIp: requestHelpers.clientIp(req) },
+          outcome: "ok",
+          metadata: { method: "dpop", jkt: result.jkt, route: req.url },
+        });
+      } catch (_ignored) { /* drop-silent */ }
+    }
+    return next();
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/lib/middleware/gpc.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * b.middleware.gpc — Sec-GPC (Global Privacy Control) middleware.
+ *
+ * Reads the `Sec-GPC: 1` request header (W3C Privacy Sandbox / IETF
+ * draft-doty-gpc-header) and, when present, sets `req.gpcOptOut =
+ * true` for downstream consumers. Optionally records the opt-out
+ * via `b.consent` (when wired) so the operator's data-flow primitives
+ * can refuse `sale`/`share`/`targeted-ads`/`profiling` purposes for
+ * this session.
+ *
+ * Echoes a `Sec-GPC-Status: honored` response header per the
+ * California Privacy Protection Agency's recommended posture so the
+ * client UA can confirm honoring (and so audits show the
+ * acknowledgement).
+ *
+ * Compliance context — Sec-GPC is **legally required** by:
+ *   - California (CCPA / CPRA) — effective Jan 1 2024
+ *   - Colorado, Connecticut, Texas, Oregon, Delaware, Montana, Iowa,
+ *     Nebraska, New Hampshire, New Jersey, Maryland, Minnesota — effective
+ *     dates vary; most by Jan 1 2026
+ *
+ * Operators handling US user traffic without honoring Sec-GPC face
+ * regulator-action exposure (CPPA fines up to $7,500 per intentional
+ * violation). The framework's posture is to honor by default; operators
+ * who legitimately don't process the listed purposes still emit the
+ * acknowledgement header so audits trace correctly.
+ *
+ *   var gpc = b.middleware.gpc({
+ *     audit:   b.audit,
+ *     consent: b.consent,           // optional — auto-records purpose-withdrawal
+ *     mode:    "enforce",            // "enforce" | "audit-only"
+ *   });
+ *   app.use(gpc);
+ *
+ *   app.get("/api/data", function (req, res) {
+ *     if (req.gpcOptOut) {
+ *       // Don't serve targeted ads, don't share with data brokers, etc.
+ *     }
+ *   });
+ */
+
+var lazyRequire = require("../lazy-require");
+
+var observability = lazyRequire(function () { return require("../observability"); });
+void observability;
+
+// Purposes the operator must NOT process when Sec-GPC: 1 is set, per
+// CCPA/CPRA + the multi-state cohort. Operators consuming `req.gpcOptOut`
+// gate these specific purposes.
+var GPC_OPTOUT_PURPOSES = Object.freeze([
+  "sale",
+  "share",
+  "targeted-ads",
+  "cross-context-behavioral-advertising",
+  "profiling",
+]);
+
+function _emitAudit(audit, action, outcome, metadata) {
+  if (!audit || typeof audit.safeEmit !== "function") return;
+  try {
+    audit.safeEmit({
+      action:   action,
+      actor:    metadata.actor || { kind: "framework", id: "middleware/gpc" },
+      outcome:  outcome,
+      metadata: metadata,
+    });
+  } catch (_e) { /* drop-silent */ }
+}
+
+function create(opts) {
+  opts = opts || {};
+  var mode = opts.mode || "enforce";
+  var audit = opts.audit || null;
+  var consentApi = opts.consent || null;
+  var statusHeader = opts.statusHeader !== false;
+
+  return function gpcMiddleware(req, res, next) {
+    var rawHeader = (req.headers && req.headers["sec-gpc"]) || "";
+    var optOut = rawHeader === "1";
+    req.gpcOptOut = optOut;
+
+    if (optOut) {
+      // Stamp the acknowledgement header so the UA + auditors see we
+      // honored.
+      if (statusHeader && typeof res.setHeader === "function") {
+        res.setHeader("Sec-GPC-Status", mode === "audit-only" ? "audit-only" : "honored");
+      }
+
+      // Optional integration with b.consent — record purpose
+      // withdrawal so downstream consumers see the GPC signal as a
+      // structured opt-out.
+      if (consentApi && typeof consentApi.recordOptOut === "function") {
+        try {
+          consentApi.recordOptOut({
+            req:       req,
+            purposes:  GPC_OPTOUT_PURPOSES,
+            source:    "sec-gpc",
+            mode:      mode,
+          });
+        } catch (e) {
+          _emitAudit(audit, "middleware.gpc.consent-error", "audit", {
+            error: (e && e.message) || String(e),
+          });
+        }
+      }
+
+      _emitAudit(audit, "middleware.gpc.opt-out-honored", "success", {
+        mode:     mode,
+        purposes: GPC_OPTOUT_PURPOSES.slice(),
+      });
+    }
+    return next();
+  };
+}
+
+module.exports = {
+  create:                create,
+  GPC_OPTOUT_PURPOSES:   GPC_OPTOUT_PURPOSES,
+};

package/lib/middleware/index.js

@@ -27,14 +27,17 @@ var cors = require("./cors");
 var cspNonce = require("./csp-nonce");
 var csrfProtect = require("./csrf-protect");
 var dbRoleFor = require("./db-role-for");
+var dpop = require("./dpop");
 var errorHandler = require("./error-handler");
 var fetchMetadata = require("./fetch-metadata");
+var gpc = require("./gpc");
 var headers = require("./headers");
 var health = require("./health");
 var networkAllowlist = require("./network-allowlist");
 var rateLimit = require("./rate-limit");
 var requestId = require("./request-id");
 var requestLog = require("./request-log");
+var requireAal = require("./require-aal");
 var requireAuth = require("./require-auth");
 var securityHeaders = require("./security-headers");
 var sse = require("./sse");
@@ -48,9 +51,11 @@ module.exports = {
   rateLimit:        rateLimit.create,
   attachUser:       attachUser.create,
   bearerAuth:       bearerAuth.create,
+  requireAal:       requireAal.create,
   requireAuth:      requireAuth.create,
   csrfProtect:      csrfProtect.create,
   fetchMetadata:    fetchMetadata.create,
+  gpc:              gpc.create,
   headers:          headers.create,
   bodyParser:       bodyParser.create,
   health:           health.create,
@@ -61,6 +66,7 @@ module.exports = {
   requestLog:       requestLog.create,
   apiEncrypt:       apiEncrypt,
   dbRoleFor:        dbRoleFor.create,
+  dpop:             dpop.create,
   networkAllowlist: networkAllowlist.create,
 
   // Module exports for advanced use (constants, raw factory access)
@@ -73,6 +79,7 @@ module.exports = {
     rateLimit:        rateLimit,
     attachUser:       attachUser,
     bearerAuth:       bearerAuth,
+    requireAal:       requireAal,
     requireAuth:      requireAuth,
     csrfProtect:      csrfProtect,
     fetchMetadata:    fetchMetadata,
@@ -84,6 +91,7 @@ module.exports = {
     requestLog:       requestLog,
     apiEncrypt:       apiEncrypt,
     dbRoleFor:        dbRoleFor,
+    dpop:             dpop,
     networkAllowlist: networkAllowlist,
   },
 };

package/lib/middleware/require-aal.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * require-aal middleware — gate routes by NIST SP 800-63-4 AAL band.
+ *
+ *   var stepUp = b.middleware.requireAal({ minimum: "AAL2" });
+ *   router.use("/admin", stepUp);
+ *
+ * Reads the AAL band from `req.user.aal` by default. Operators with a
+ * different shape pass `getAal(req)` returning the band string.
+ *
+ * On failure the middleware writes 401 with
+ * `WWW-Authenticate: AAL-StepUp realm="<X>", required="<minimum>"`
+ * — the bespoke scheme name signals to the operator's frontend that a
+ * step-up flow should be triggered (re-prompt for TOTP / passkey).
+ *
+ * Audit:
+ *   auth.aal.granted — request passed (carries the actual band)
+ *   auth.aal.denied  — request below the required minimum
+ */
+
+var lazyRequire = require("../lazy-require");
+var requestHelpers = require("../request-helpers");
+var validateOpts = require("../validate-opts");
+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) {
+  if (res.headersSent) return;
+  var body = JSON.stringify({
+    error:             "step_up_required",
+    error_description: "AAL " + requiredBand + " is required for this resource",
+    required_aal:      requiredBand,
+    actual_aal:        actualBand || null,
+  });
+  var realmStr = realm ? ' realm="' + realm + '"' : "";
+  var challenge = "AAL-StepUp" + realmStr + ', required="' + requiredBand + '"';
+  res.writeHead(401, {                                                             // allow:raw-byte-literal — HTTP 401 status
+    "Content-Type":     "application/json; charset=utf-8",
+    "Content-Length":   Buffer.byteLength(body),
+    "WWW-Authenticate": challenge,
+  });
+  res.end(body);
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "minimum", "getAal", "audit", "realm",
+  ], "middleware.requireAal");
+
+  var minimum = opts.minimum;
+  if (!aal().isValidBand(minimum)) {
+    throw new AuthError("auth-aal/bad-minimum",
+      "middleware.requireAal: opts.minimum must be one of " +
+      aal().BANDS.join(", ") + " (got " + JSON.stringify(minimum) + ")");
+  }
+  validateOpts.optionalFunction(opts.getAal,
+    "middleware.requireAal: getAal", AuthError, "auth-aal/bad-opt");
+
+  var auditOn = opts.audit !== false;
+  var realm = (typeof opts.realm === "string" && opts.realm.length > 0) ? opts.realm : null;
+
+  return function requireAalMiddleware(req, res, next) {
+    var actual = null;
+    if (typeof opts.getAal === "function") {
+      try { actual = opts.getAal(req); } catch (_e) { actual = null; }
+    } else if (req.user && typeof req.user.aal === "string") {
+      actual = req.user.aal;
+    }
+
+    if (!aal().meets(actual, minimum)) {
+      if (auditOn) {
+        try {
+          audit().safeEmit({
+            action:  "auth.aal.denied",
+            actor:   { clientIp: requestHelpers.clientIp(req), userId: req.user && req.user.id },
+            outcome: "fail",
+            metadata: {
+              required: minimum,
+              actual:   actual || null,
+              route:    req.url,
+            },
+          });
+        } catch (_ignored) { /* drop-silent */ }
+      }
+      return _writeUnauthorized(res, minimum, actual, realm);
+    }
+
+    if (auditOn) {
+      try {
+        audit().safeEmit({
+          action:  "auth.aal.granted",
+          actor:   { clientIp: requestHelpers.clientIp(req), userId: req.user && req.user.id },
+          outcome: "ok",
+          metadata: { aal: actual, required: minimum, route: req.url },
+        });
+      } catch (_ignored) { /* drop-silent */ }
+    }
+    return next();
+  };
+}
+
+module.exports = {
+  create: create,
+};