@blamejs/core 0.7.106 → 0.8.0

package/lib/mail-arc-sign.js

@@ -0,0 +1,372 @@
+"use strict";
+/**
+ * b.mail.arc.sign — RFC 8617 ARC chain construction.
+ *
+ * Companion to b.mail.arc.verify (relay-side ARC chain validation).
+ * When a relay receives a message with optional prior ARC headers
+ * and is about to forward it, it signs and prepends three new
+ * headers per RFC 8617 §5.1:
+ *
+ *   - ARC-Authentication-Results (AAR) — relay's verification verdict
+ *     for SPF / DKIM / DMARC at this hop, formatted per RFC 8601.
+ *   - ARC-Message-Signature (AMS) — DKIM-style signature over the
+ *     message body + selected headers + the AAR.
+ *   - ARC-Seal (AS) — signature over the catenation of every prior
+ *     hop's three headers plus the current AAR + AMS, with cv= tag
+ *     reporting the upstream chain validation outcome.
+ *
+ * The operator's verification result lives in opts.authResults; the
+ * cv= self-attestation comes from opts.cv (typically the result.cv
+ * of a prior arc.verify() call: "none" at i=1, "pass" / "fail" at
+ * i>=2).
+ *
+ *   var signed = b.mail.arc.sign({
+ *     rfc822:        message,
+ *     instance:      i,                          // 1, 2, 3, ...
+ *     authservId:    "relay.example.com",
+ *     domain:        "relay.example.com",
+ *     selector:      "arc",
+ *     privateKey:    pem,
+ *     algorithm:     "rsa-sha256",
+ *     cv:            "none",                     // i=1: none; i>=2: pass / fail
+ *     authResults:   "spf=pass smtp.mailfrom=...",
+ *     headersToSign: ["From", "To", "Subject", "Date", "Message-ID"],
+ *     timestamp:     Math.floor(Date.now() / 1000),
+ *   });
+ *   // signed.aar, signed.ams, signed.as → strings
+ *   // signed.rfc822 → message with all three headers prepended
+ *
+ * Per RFC 8617:
+ *   - i=1: cv=none REQUIRED.
+ *   - i>=2: cv=pass | cv=fail; cv=none is invalid at i>=2.
+ *   - Once any hop's AS reports cv=fail, no downstream hop may sign
+ *     a cv=pass — the chain is permanently broken. Signers MUST
+ *     report cv=fail when forwarding such a chain.
+ *
+ * Per the framework's validation-tier policy: sign() throws on bad
+ * input (config-time entry-point). Audit emissions on every signed
+ * hop: `dkim.arc.signed`.
+ */
+
+var nodeCrypto = require("crypto");
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var safeBuffer = require("./safe-buffer");
+var { defineClass } = require("./framework-error");
+
+var MailAuthError = defineClass("MailAuthError", { alwaysPermanent: true });
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var ALLOWED_ALGORITHMS = ["rsa-sha256", "ed25519-sha256"];
+var ALLOWED_CV         = ["none", "pass", "fail"];
+var DEFAULT_HEADERS    = ["From", "To", "Subject", "Date", "Message-ID",
+                          "MIME-Version", "Content-Type"];
+
+function _splitHeadersBody(rfc822) {
+  var idx = rfc822.indexOf("\r\n\r\n");
+  if (idx === -1) {
+    var lfIdx = rfc822.indexOf("\n\n");
+    if (lfIdx === -1) {
+      throw new MailAuthError("arc-sign/bad-rfc822",
+        "rfc822 body has no header/body separator (CRLF-CRLF or LF-LF)");
+    }
+    return { headers: rfc822.substring(0, lfIdx), body: rfc822.substring(lfIdx + 2) };
+  }
+  return { headers: rfc822.substring(0, idx), body: rfc822.substring(idx + 4) };
+}
+
+function _parseHeaderBlock(headerBlock) {
+  // Returns array of { name, value } in source order. Folds CRLF+WSP
+  // continuations.
+  var lines = headerBlock.split(/\r?\n/);
+  var headers = [];
+  var current = null;
+  for (var i = 0; i < lines.length; i += 1) {
+    var line = lines[i];
+    if (line.length === 0) continue;
+    if (line.charAt(0) === " " || line.charAt(0) === "\t") {
+      if (current) current.value += "\r\n" + line;
+      continue;
+    }
+    var colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    if (current) headers.push(current);
+    current = {
+      name:  line.slice(0, colonIdx),
+      value: line.slice(colonIdx + 1).replace(/^[ \t]+/, ""),    // allow:duplicate-regex — RFC 5322 leading-WSP strip; identical to mail-auth/mail-dkim by spec
+    };
+  }
+  if (current) headers.push(current);
+  return headers;
+}
+
+function _canonRelaxedHeader(name, value) {
+  var unfolded = String(value).replace(/\r?\n[ \t]+/g, " ");                // allow:duplicate-regex allow:raw-byte-literal — DKIM/ARC RFC 6376 §3.4.2 unfolding
+  var trimmed = unfolded.replace(/[ \t]+/g, " ").replace(/^[ \t]+|[ \t]+$/g, "");  // allow:duplicate-regex allow:raw-byte-literal — DKIM/ARC RFC 6376 §3.4.2 WSP collapse
+  return name.toLowerCase() + ":" + trimmed + "\r\n";
+}
+
+function _canonRelaxedBody(body) {
+  // Relaxed body canon: collapse runs of WSP within lines, strip
+  // trailing WSP, remove all trailing empty lines, append single CRLF
+  // unless body is empty.
+  if (body.length === 0) return "";
+  var normalized = body.replace(/\r?\n/g, "\r\n");
+  var collapsed = normalized.replace(/[ \t]+/g, " ").replace(/[ \t]+\r\n/g, "\r\n");
+  collapsed = collapsed.replace(/(\r\n)+$/, "");
+  return collapsed + "\r\n";
+}
+
+function _bodyHashB64(body, algorithm) {
+  var hashAlgo = algorithm.indexOf("sha256") !== -1 ? "sha256" : "sha512";
+  var canonical = _canonRelaxedBody(body);
+  return nodeCrypto.createHash(hashAlgo).update(canonical).digest("base64");
+}
+
+function _arcExtractPriorHops(parsedHeaders) {
+  // Walk parsedHeaders; for each ARC-Authentication-Results /
+  // ARC-Message-Signature / ARC-Seal entry, extract instance via i=N
+  // and group by hop.
+  var hopMap = {};
+  for (var i = 0; i < parsedHeaders.length; i += 1) {
+    var h = parsedHeaders[i];
+    var lcName = h.name.toLowerCase();
+    if (lcName !== "arc-authentication-results" &&
+        lcName !== "arc-message-signature" &&
+        lcName !== "arc-seal") continue;
+    var iMatch = h.value.match(/(?:^|[;,\s])i=(\d+)/);                                  // allow:regex-no-length-cap — ARC header bounded by RFC 5322 §2.1.1
+    if (!iMatch) continue;
+    var instance = parseInt(iMatch[1], 10);
+    if (!hopMap[instance]) hopMap[instance] = { instance: instance };
+    hopMap[instance][lcName] = h.value;
+  }
+  var hops = [];
+  var keys = Object.keys(hopMap).sort(function (a, b) { return Number(a) - Number(b); });
+  for (var k = 0; k < keys.length; k += 1) hops.push(hopMap[keys[k]]);
+  return hops;
+}
+
+function sign(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "rfc822", "instance", "authservId", "domain", "selector",
+    "privateKey", "algorithm", "cv", "authResults",
+    "headersToSign", "timestamp", "audit",
+  ], "mail.arc.sign");
+
+  validateOpts.requireNonEmptyString(opts.rfc822, "sign: rfc822",
+    MailAuthError, "arc-sign/bad-input");
+  if (typeof opts.instance !== "number" || !isFinite(opts.instance) ||
+      opts.instance < 1 || opts.instance > 50 ||                                        // allow:raw-byte-literal — RFC 8617 §5 chain bound
+      Math.floor(opts.instance) !== opts.instance) {
+    throw new MailAuthError("arc-sign/bad-instance",
+      "sign: instance must be an integer in [1, 50] — got " + JSON.stringify(opts.instance));
+  }
+  validateOpts.requireNonEmptyString(opts.authservId,
+    "sign: authservId", MailAuthError, "arc-sign/bad-authserv");
+  validateOpts.requireNonEmptyString(opts.domain,
+    "sign: domain", MailAuthError, "arc-sign/bad-domain");
+  validateOpts.requireNonEmptyString(opts.selector,
+    "sign: selector", MailAuthError, "arc-sign/bad-selector");
+  if (!opts.privateKey || (typeof opts.privateKey !== "string" &&
+      typeof opts.privateKey !== "object")) {
+    throw new MailAuthError("arc-sign/missing-private-key",
+      "sign: privateKey is required (PEM string or crypto.KeyObject)");
+  }
+  var algorithm = opts.algorithm || "rsa-sha256";
+  if (ALLOWED_ALGORITHMS.indexOf(algorithm) === -1) {
+    throw new MailAuthError("arc-sign/bad-algorithm",
+      "sign: algorithm must be one of " + ALLOWED_ALGORITHMS.join(", "));
+  }
+  if (ALLOWED_CV.indexOf(opts.cv) === -1) {
+    throw new MailAuthError("arc-sign/bad-cv",
+      "sign: cv must be one of " + ALLOWED_CV.join(", ") + " — got " + JSON.stringify(opts.cv));
+  }
+  if (opts.instance === 1 && opts.cv !== "none") {
+    throw new MailAuthError("arc-sign/cv-rule",
+      "sign: i=1 requires cv=none (per RFC 8617 §5.1.1)");
+  }
+  if (opts.instance >= 2 && opts.cv === "none") {                                       // allow:raw-byte-literal — RFC 8617 chain rule
+    throw new MailAuthError("arc-sign/cv-rule",
+      "sign: i>=2 disallows cv=none — must be cv=pass or cv=fail (per RFC 8617 §5.1.1)");
+  }
+  validateOpts.requireNonEmptyString(opts.authResults, "sign: authResults",
+    MailAuthError, "arc-sign/bad-auth-results");
+  if (safeBuffer.hasCrlf(opts.authResults)) {
+    throw new MailAuthError("arc-sign/bad-auth-results",
+      "sign: authResults contains CR/LF (header injection refused)");
+  }
+  var headersToSign = opts.headersToSign || DEFAULT_HEADERS;
+  if (!Array.isArray(headersToSign) || headersToSign.length === 0) {
+    throw new MailAuthError("arc-sign/bad-headers",
+      "sign: headersToSign must be a non-empty array of header names");
+  }
+  for (var hi = 0; hi < headersToSign.length; hi += 1) {
+    if (typeof headersToSign[hi] !== "string" || headersToSign[hi].length === 0) {
+      throw new MailAuthError("arc-sign/bad-headers",
+        "sign: headersToSign[" + hi + "] must be a non-empty string");
+    }
+  }
+  var timestamp = (typeof opts.timestamp === "number" && opts.timestamp > 0)            // allow:numeric-opt-Infinity
+    ? Math.floor(opts.timestamp) : Math.floor(Date.now() / 1000);                       // allow:raw-byte-literal — Unix epoch seconds divisor
+  var auditOn = opts.audit !== false;
+
+  var keyObject;
+  try {
+    keyObject = (typeof opts.privateKey === "string" || Buffer.isBuffer(opts.privateKey))
+      ? nodeCrypto.createPrivateKey({ key: opts.privateKey, format: "pem" })
+      : opts.privateKey;
+  } catch (e) {
+    throw new MailAuthError("arc-sign/bad-private-key",
+      "sign: privateKey could not be parsed: " + ((e && e.message) || String(e)));
+  }
+
+  var split = _splitHeadersBody(opts.rfc822);
+  var parsedHeaders = _parseHeaderBlock(split.headers);
+  var priorHops = _arcExtractPriorHops(parsedHeaders);
+
+  // Validate prior chain's instance numbering: hops must be 1..N-1
+  // contiguous, where N is opts.instance.
+  for (var ph = 0; ph < priorHops.length; ph += 1) {
+    if (priorHops[ph].instance !== ph + 1) {
+      throw new MailAuthError("arc-sign/chain-broken",
+        "sign: prior chain has gap or mismatch — expected i=" + (ph + 1) +
+        " at slot " + ph + ", got i=" + priorHops[ph].instance);
+    }
+  }
+  if (priorHops.length !== opts.instance - 1) {
+    throw new MailAuthError("arc-sign/chain-broken",
+      "sign: prior chain has " + priorHops.length + " hops but instance=" +
+      opts.instance + " requires " + (opts.instance - 1) + " prior hops");
+  }
+
+  var bh = _bodyHashB64(split.body, algorithm);
+
+  // ----- AAR (ARC-Authentication-Results) -----
+  // RFC 8617 §4.1.1 — `i=N; <auth-result-string>`.
+  var aarValue = "i=" + opts.instance + "; " + opts.authservId + "; " + opts.authResults;
+
+  // ----- AMS (ARC-Message-Signature) -----
+  // Looks like DKIM-Signature with `i=N` tag added.
+  // Tags in canonical order: i, a, c, d, s, t, h, bh, b
+  var amsTags = [
+    "i=" + opts.instance,
+    "a=" + algorithm,
+    "c=relaxed/relaxed",
+    "d=" + opts.domain,
+    "s=" + opts.selector,
+    "t=" + timestamp,
+    "h=" + headersToSign.join(":"),
+    "bh=" + bh,
+  ];
+  amsTags.push("b=");
+  var amsUnsigned = amsTags.join("; ");
+
+  var canonHeaders = "";
+  var headerNamesLc = parsedHeaders.map(function (h) { return h.name.toLowerCase(); });
+  for (var j = 0; j < headersToSign.length; j += 1) {
+    var wantLc = headersToSign[j].toLowerCase();
+    var idx = -1;
+    for (var k = 0; k < headerNamesLc.length; k += 1) {
+      if (headerNamesLc[k] === wantLc) idx = k;
+    }
+    if (idx === -1) continue;
+    var h = parsedHeaders[idx];
+    canonHeaders += _canonRelaxedHeader(h.name, h.value);
+  }
+  // Per RFC 8617 §5.1 — include the AAR for the current hop in the
+  // AMS canonicalization stream when h= covers it. Per AMS spec, h=
+  // typically does NOT include the AAR (it's a *prior* hop's
+  // attestation), so the canonical input is (h-listed headers) +
+  // (AMS with empty b=).
+  var amsCanonInput = canonHeaders +
+    _canonRelaxedHeader("ARC-Message-Signature", amsUnsigned).replace(/\r\n$/, "");
+
+  var amsSignatureB64 = _signOne(amsCanonInput, keyObject, algorithm);
+  var amsValue = amsUnsigned.replace(/\bb=$/, "b=" + amsSignatureB64);
+
+  // ----- AS (ARC-Seal) -----
+  // Tags: i, a, t, cv, d, s, b
+  var asTags = [
+    "i=" + opts.instance,
+    "a=" + algorithm,
+    "t=" + timestamp,
+    "cv=" + opts.cv,
+    "d=" + opts.domain,
+    "s=" + opts.selector,
+  ];
+  asTags.push("b=");
+  var asUnsigned = asTags.join("; ");
+
+  // AS canonical input: every prior hop's AAR + AMS + AS in instance
+  // order, then current AAR + AMS, then current AS with empty b=.
+  var asCanonInput = "";
+  for (var p = 0; p < priorHops.length; p += 1) {
+    var hop = priorHops[p];
+    asCanonInput += _canonRelaxedHeader("ARC-Authentication-Results", hop["arc-authentication-results"]);
+    asCanonInput += _canonRelaxedHeader("ARC-Message-Signature",      hop["arc-message-signature"]);
+    asCanonInput += _canonRelaxedHeader("ARC-Seal",                   hop["arc-seal"]);
+  }
+  asCanonInput += _canonRelaxedHeader("ARC-Authentication-Results", aarValue);
+  asCanonInput += _canonRelaxedHeader("ARC-Message-Signature",      amsValue);
+  asCanonInput += _canonRelaxedHeader("ARC-Seal", asUnsigned).replace(/\r\n$/, "");
+
+  var asSignatureB64 = _signOne(asCanonInput, keyObject, algorithm);
+  var asValue = asUnsigned.replace(/\bb=$/, "b=" + asSignatureB64);
+
+  // Prepend headers in the RFC-recommended order: AS, AMS, AAR.
+  var prependedHeaders =
+    "ARC-Seal: " + asValue + "\r\n" +
+    "ARC-Message-Signature: " + amsValue + "\r\n" +
+    "ARC-Authentication-Results: " + aarValue + "\r\n";
+  var sealedRfc822 = prependedHeaders + opts.rfc822;
+
+  if (auditOn) {
+    try {
+      audit().safeEmit({
+        action:   "dkim.arc.signed",
+        outcome:  "success",
+        actor:    null,
+        metadata: {
+          instance:   opts.instance,
+          domain:     opts.domain,
+          selector:   opts.selector,
+          algorithm:  algorithm,
+          cv:         opts.cv,
+          priorHops:  priorHops.length,
+        },
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  return {
+    aar:    aarValue,
+    ams:    amsValue,
+    as:     asValue,
+    rfc822: sealedRfc822,
+    instance: opts.instance,
+    cv:     opts.cv,
+  };
+}
+
+function _signOne(canonInput, keyObject, algorithm) {
+  if (algorithm === "ed25519-sha256") {
+    // Ed25519 prehash variant — Node's `crypto.sign(null, msg, key)`
+    // accepts the message directly.
+    return nodeCrypto.sign(null, Buffer.from(canonInput, "utf8"), keyObject)
+      .toString("base64");
+  }
+  // RSA-SHA256 / default — createSign + update + sign.
+  var signer = nodeCrypto.createSign("RSA-SHA256");
+  signer.update(canonInput);
+  return signer.sign(keyObject).toString("base64");
+}
+
+module.exports = {
+  sign:           sign,
+  ALLOWED_CV:     ALLOWED_CV,
+  ALLOWED_ALGORITHMS: ALLOWED_ALGORITHMS,
+  DEFAULT_HEADERS: DEFAULT_HEADERS,
+  MailAuthError:  MailAuthError,
+};

package/lib/mail-auth.js

@@ -1106,6 +1106,8 @@ module.exports = {
   arc: Object.freeze({
     verify:        arcVerify,
     evaluate:      arcEvaluate,
+    sign:          require("./mail-arc-sign").sign,           // allow:inline-require — re-export from sibling module
+    ALLOWED_CV:    require("./mail-arc-sign").ALLOWED_CV,     // allow:inline-require — re-export from sibling module
   }),
   authResults: Object.freeze({
     emit:          authResultsEmit,

package/lib/middleware/ai-act-disclosure.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * ai-act-disclosure middleware — auto-inject the EU AI Act Article 50
+ * disclosure banner / meta tags into outgoing HTML responses.
+ *
+ *   var disclose = b.middleware.aiActDisclosure({
+ *     kind:         "ai-interaction",
+ *     deployerName: "myco",
+ *     policyUri:    "https://myco.example.com/ai-policy",
+ *   });
+ *   router.use(disclose);
+ *
+ * Two integration modes:
+ *
+ *   - "header"   (default) — adds the AI-Act-Notice + AI-Act-Article
+ *                            response headers. Cheapest; works for JSON
+ *                            APIs as well as HTML.
+ *
+ *   - "html"               — when the response Content-Type is HTML,
+ *                            injects a <div role="status" ...> banner
+ *                            immediately after the <body> tag plus a
+ *                            <meta> tag inside <head>. Skipped when
+ *                            response is already past headers OR not
+ *                            text/html.
+ *
+ * The middleware does NOT alter the response when:
+ *   - response status >= 400 (operator's error pages stay clean)
+ *   - response is a redirect (3xx)
+ *   - operator has set the X-Skip-AI-Act header on the request
+ *     (test fixtures, internal-traffic carve-out)
+ *   - per-request opt-out via res.locals.aiActSkip = true
+ *
+ * Audit emission: `compliance.aiact.disclosed` on every successful
+ * injection. Operators with high-volume traffic can disable via
+ * `audit: false`.
+ */
+
+var lazyRequire    = require("../lazy-require");
+var validateOpts   = require("../validate-opts");
+var requestHelpers = require("../request-helpers");
+
+var aiActMod  = lazyRequire(function () { return require("../compliance-ai-act"); });
+var audit     = lazyRequire(function () { return require("../audit"); });
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "kind", "deployerName", "policyUri", "mode",
+    "audit", "lang", "skipHeader",
+  ], "middleware.aiActDisclosure");
+
+  var mode = (opts.mode === "html") ? "html" : "header";
+  // Pre-validate kind via the transparency catalog.
+  var probe = aiActMod().transparency.banner({
+    kind: opts.kind || "ai-interaction",
+    lang: opts.lang || "en",
+  });
+  // probe throws if kind is bad — operator catches at boot.
+  void probe;
+
+  var auditOn    = opts.audit !== false;
+  var skipHeader = (typeof opts.skipHeader === "string" && opts.skipHeader.length > 0)
+    ? opts.skipHeader.toLowerCase()
+    : "x-skip-ai-act";
+
+  return function aiActDisclosureMiddleware(req, res, next) {
+    var headers = req.headers || {};
+    if (headers[skipHeader] != null) return next();
+
+    // Wrap response.writeHead so we can set headers + decide html mode.
+    var origWriteHead = res.writeHead;
+    var origEnd       = res.end;
+    var injected      = false;
+
+    res.writeHead = function (status, headersOrReason, headersMaybe) {
+      // Only inject for 2xx HTML or any 2xx for header mode.
+      if (typeof status !== "number" || status < 200 || status >= 300) {
+        return origWriteHead.apply(res, arguments);
+      }
+      if (res.locals && res.locals.aiActSkip === true) {
+        return origWriteHead.apply(res, arguments);
+      }
+      var article = _articleFor(opts.kind || "ai-interaction");
+      _setHeader(res, "AI-Act-Notice",  opts.kind || "ai-interaction");
+      _setHeader(res, "AI-Act-Article", article);
+      if (typeof opts.policyUri === "string" && opts.policyUri.length > 0) {
+        _setHeader(res, "AI-Act-Policy", opts.policyUri);
+      }
+      injected = true;
+      return origWriteHead.apply(res, arguments);
+    };
+
+    if (mode === "html") {
+      res.end = function (chunk, encoding) {
+        try {
+          var ctype = (res.getHeader && res.getHeader("Content-Type")) || "";
+          if (typeof ctype === "string" && ctype.indexOf("text/html") !== -1 &&
+              chunk && Buffer.isBuffer(chunk) === false &&
+              typeof chunk === "string") {
+            var bannerHtml = aiActMod().transparency.htmlBanner({
+              kind: opts.kind || "ai-interaction",
+              lang: opts.lang || "en",
+            });
+            // Inject after <body> if present, else prepend.
+            var bodyOpen = chunk.indexOf("<body");
+            if (bodyOpen !== -1) {
+              var afterTag = chunk.indexOf(">", bodyOpen);
+              if (afterTag !== -1) {
+                chunk = chunk.slice(0, afterTag + 1) + bannerHtml + chunk.slice(afterTag + 1);
+              }
+            } else {
+              chunk = bannerHtml + chunk;
+            }
+          }
+        } catch (_e) { /* injection best-effort */ }
+        return origEnd.apply(res, [chunk, encoding]);
+      };
+    }
+
+    if (auditOn) {
+      res.on("close", function () {
+        if (!injected) return;
+        try {
+          audit().safeEmit({
+            action:   "compliance.aiact.disclosed",
+            outcome:  "success",
+            actor:    {
+              clientIp: requestHelpers.clientIp(req),
+              path:     req.url || null,
+            },
+            metadata: {
+              kind:         opts.kind || "ai-interaction",
+              mode:         mode,
+              deployerName: opts.deployerName || null,
+            },
+          });
+        } catch (_e) { /* drop-silent */ }
+      });
+    }
+
+    return next();
+  };
+}
+
+function _articleFor(kind) {
+  switch (kind) {
+    case "ai-interaction":            return "Art. 50(1)";
+    case "ai-generated-content":      return "Art. 50(2)";
+    case "emotion-recognition":       return "Art. 50(3)";
+    case "biometric-categorisation":  return "Art. 50(3)";
+    case "deep-fake":                 return "Art. 50(4)";
+    case "ai-text-public-interest":   return "Art. 50(4)";
+    default:                          return null;
+  }
+}
+
+function _setHeader(res, name, value) {
+  if (typeof res.setHeader === "function") {
+    res.setHeader(name, value);
+    return;
+  }
+  res._headers = res._headers || {};
+  res._headers[name] = value;
+}
+
+module.exports = { create: create };

package/lib/middleware/asyncapi-serve.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * asyncapi-serve middleware — expose an AsyncAPI 3.0 document at a
+ * mount point.
+ *
+ *   var aapi = b.asyncapi.create({ ... });
+ *   ...add channels / operations / schemas / security...
+ *
+ *   router.use(b.middleware.asyncapiServe({
+ *     document:      aapi,
+ *     pathJson:      "/asyncapi.json",
+ *     pathYaml:      "/asyncapi.yaml",
+ *     pretty:        true,
+ *     accessControl: "public",
+ *   }));
+ *
+ * Behaviour matches openapiServe: GET / HEAD only, SHA3-512 ETag with
+ * conditional 304, configurable CORS gate, falls through on other
+ * paths / methods.
+ */
+
+var nodeCrypto    = require("crypto");
+var validateOpts  = require("../validate-opts");
+var lazyRequire   = require("../lazy-require");
+var { defineClass } = require("../framework-error");
+var AsyncApiError = defineClass("AsyncApiError", { alwaysPermanent: true });
+
+var openapiYaml   = lazyRequire(function () { return require("../openapi-yaml"); });
+var audit         = lazyRequire(function () { return require("../audit"); });
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "document", "pathJson", "pathYaml", "pretty",
+    "cacheControl", "accessControl", "audit",
+  ], "middleware.asyncapiServe");
+  if (!opts.document || typeof opts.document.toJson !== "function") {
+    throw new AsyncApiError("asyncapi/bad-document",
+      "asyncapiServe: document must be a builder created via b.asyncapi.create()");
+  }
+  var pathJson      = opts.pathJson || "/asyncapi.json";
+  var pathYaml      = opts.pathYaml || "/asyncapi.yaml";
+  var pretty        = opts.pretty === true ? 2 : 0;
+  var cacheControl  = (typeof opts.cacheControl === "string" && opts.cacheControl.length > 0)
+    ? opts.cacheControl : "public, max-age=300";
+  var accessControl = opts.accessControl || "public";
+  var auditOn       = opts.audit !== false;
+
+  if (typeof pathJson !== "string" || pathJson.charAt(0) !== "/") {
+    throw new AsyncApiError("asyncapi/bad-path",
+      "asyncapiServe: pathJson must start with '/'");
+  }
+  if (typeof pathYaml !== "string" || pathYaml.charAt(0) !== "/") {
+    throw new AsyncApiError("asyncapi/bad-path",
+      "asyncapiServe: pathYaml must start with '/'");
+  }
+
+  var cachedJsonStr  = null;
+  var cachedYamlStr  = null;
+  var cachedJsonEtag = null;
+  var cachedYamlEtag = null;
+
+  function _rebuild() {
+    var doc = opts.document.toJson();
+    cachedJsonStr  = JSON.stringify(doc, null, pretty);
+    cachedYamlStr  = openapiYaml().toYaml(doc);
+    cachedJsonEtag = '"' + nodeCrypto.createHash("sha3-512").update(cachedJsonStr).digest("base64url").slice(0, 24) + '"';
+    cachedYamlEtag = '"' + nodeCrypto.createHash("sha3-512").update(cachedYamlStr).digest("base64url").slice(0, 24) + '"';
+  }
+  _rebuild();
+
+  function _writeBody(req, res, body, etag, contentType) {
+    var requestEtag = (req.headers && req.headers["if-none-match"]) || null;
+    if (requestEtag && requestEtag === etag) {
+      res.writeHead(304, { "ETag": etag, "Cache-Control": cacheControl });           // allow:raw-byte-literal — HTTP 304
+      res.end();
+      return;
+    }
+    var headers = {
+      "Content-Type":   contentType,
+      "Content-Length": Buffer.byteLength(body),
+      "Cache-Control":  cacheControl,
+      "ETag":           etag,
+    };
+    if (accessControl === "public") {
+      headers["Access-Control-Allow-Origin"] = "*";
+    }
+    res.writeHead(200, headers);                                                     // allow:raw-byte-literal — HTTP 200
+    res.end(body);
+  }
+
+  var mw = function (req, res, next) {
+    if (typeof res.writeHead !== "function") return next();
+    var method = (req.method || "GET").toUpperCase();
+    if (method !== "GET" && method !== "HEAD") return next();
+    var pathname = req.pathname;
+    if (typeof pathname !== "string") {
+      var url = req.url || "";
+      var qIdx = url.indexOf("?");
+      pathname = qIdx === -1 ? url : url.slice(0, qIdx);
+    }
+    if (pathname === pathJson) {
+      _writeBody(req, res, cachedJsonStr, cachedJsonEtag, "application/json; charset=utf-8");
+      if (auditOn) {
+        try {
+          audit().safeEmit({
+            action:   "asyncapi.document.served",
+            outcome:  "success",
+            actor:    null,
+            metadata: { format: "json", path: pathname, bytes: cachedJsonStr.length },
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+      return;
+    }
+    if (pathname === pathYaml) {
+      _writeBody(req, res, cachedYamlStr, cachedYamlEtag, "application/yaml; charset=utf-8");
+      if (auditOn) {
+        try {
+          audit().safeEmit({
+            action:   "asyncapi.document.served",
+            outcome:  "success",
+            actor:    null,
+            metadata: { format: "yaml", path: pathname, bytes: cachedYamlStr.length },
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+      return;
+    }
+    return next();
+  };
+  mw.forceRebuild = _rebuild;
+  return mw;
+}
+
+module.exports = { create: create };