@blamejs/core 0.10.14 → 0.11.0

package/lib/mail-deploy.js

@@ -46,11 +46,19 @@
  */
 
 var nodeCrypto = require("node:crypto");
+var zlib = require("node:zlib");
+var lazyRequire = require("./lazy-require");
 var validateOpts = require("./validate-opts");
 var numericBounds = require("./numeric-bounds");
+var C = require("./constants");
+var safeJson = require("./safe-json");
+var safeBuffer = require("./safe-buffer");
+var guardJson = lazyRequire(function () { return require("./guard-json"); });
+var audit = lazyRequire(function () { return require("./audit"); });
 var { defineClass } = require("./framework-error");
 
 var MailDeployError = defineClass("MailDeployError", { alwaysPermanent: true });
+var TlsRptParseError = defineClass("TlsRptParseError", { alwaysPermanent: true });
 
 // RFC 8461 §3.2 MTA-STS policy field allowlist. Field values typed +
 // bounded — operator supplies them; we never echo arbitrary bytes
@@ -483,10 +491,629 @@ function autoDiscoverXml(opts) {
     "</Autodiscover>\n";
 }
 
+// ---- TLS-RPT receiver (RFC 8460) ----
+//
+// Inbound aggregate-report ingest for operators who publish
+// `rua=https://reports.example.com/tlsrpt` on `_smtp._tls.<domain>`.
+// Reporters POST `application/tlsrpt+json` (raw) or
+// `application/tlsrpt+gzip` (gzip-wrapped JSON) per RFC 8460 §5.4
+// + §6.4-6.5 IANA media-type registrations.
+//
+// v1 scope (this slice):
+//   - `parseTlsRptReport(bytes, opts?)` — pure parser + §4.4 schema
+//     validator. Caps decompressed size (default 32 MiB), compressed
+//     size (default 4 MiB), and compression ratio (default 50:1) to
+//     defend CVE-2025-0725 / generic decompression-amplification.
+//   - `tlsRptIngestHttp({...})` — (req, res) factory returning an
+//     RFC 8460 §5.4-compliant handler (201 on accept / 400 on bad
+//     JSON / 413 on size / 415 on bad media-type / 405 on non-POST).
+//   - `tlsRptReportSchema()` — schema descriptor for operator
+//     dashboards.
+//
+// Deferred from v1 (each with documented condition):
+//   - `mailto:` ingest via b.mail.server.mx. Defer condition: no
+//     operator demand has surfaced; HTTPS POST is the de-facto
+//     deployment shape for TLS-RPT today (reporters with `rua=mailto:`
+//     ingest are a long tail). Operators wanting mailto: ingest
+//     compose b.mail.server.mx today + call `parseTlsRptReport` on
+//     the extracted body part themselves. Reopens when an operator
+//     surfaces concrete demand AND the mail.server.mx surface stays
+//     stable across the upcoming UTA-draft revisions.
+//   - Brotli decompression. Defer condition: no fielded reporter
+//     uses `Content-Encoding: br` for TLS-RPT today; the IANA
+//     media-type registry (RFC 8460 §6.4) only registers +json and
+//     +gzip. Operators behind a brotli-encoding proxy decode at the
+//     proxy layer. Reopens when at least one fielded reporter ships
+//     brotli or the in-progress UTA-draft requires it.
+
+// Hard caps — defensive against CVE-2025-0725 (libcurl/zlib
+// integer overflow), CVE-2024-zlib decompression amplification, and
+// the §5.2 community ceiling (receivers commonly cap at 10 MiB).
+var TLSRPT_MAX_COMPRESSED_BYTES   = C.BYTES.mib(4);                                                   // allow:raw-byte-literal — 4 MiB compressed cap per §5.2 community practice
+var TLSRPT_MAX_DECOMPRESSED_BYTES = C.BYTES.mib(32);                                                  // allow:raw-byte-literal — 32 MiB decompressed cap (operators override via opts)
+var TLSRPT_MAX_RATIO              = 50;                                                               // allow:raw-byte-literal — 50:1 compression ratio refusal
+var TLSRPT_MAX_POLICIES           = 1000;                                                             // allow:raw-byte-literal allow:raw-time-literal — RFC 8460 §4.4 policy-cardinality cap
+var TLSRPT_MAX_FAILURE_DETAILS    = 10000;                                                            // allow:raw-byte-literal — per-policy failure-details cap
+var TLSRPT_GZIP_MAGIC_0           = 0x1f;                                                             // allow:raw-byte-literal — RFC 1952 gzip magic byte 0
+var TLSRPT_GZIP_MAGIC_1           = 0x8b;                                                             // allow:raw-byte-literal — RFC 1952 gzip magic byte 1
+
+// Valid RFC 8460 §4.4 result-type values for `failure-details[].result-type`.
+var TLSRPT_RESULT_TYPES = Object.freeze({
+  "starttls-not-supported":       1,
+  "certificate-host-mismatch":    1,
+  "certificate-expired":          1,
+  "certificate-not-trusted":      1,
+  "validation-failure":           1,
+  "tlsa-invalid":                 1,
+  "dnssec-invalid":               1,
+  "dane-required":                1,
+  "sts-policy-fetch-error":       1,
+  "sts-policy-invalid":           1,
+  "sts-webpki-invalid":           1,
+});
+
+// Valid RFC 8460 §4.4 policy-type values.
+var TLSRPT_POLICY_TYPES = Object.freeze({
+  sts: 1, tlsa: 1, "no-policy-found": 1,
+});
+
+/**
+ * @primitive  b.mail.deploy.parseTlsRptReport
+ * @signature  b.mail.deploy.parseTlsRptReport(input, opts?)
+ * @since      0.10.15
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.mail.deploy.tlsRptIngestHttp, b.mail.deploy.tlsRptReportSchema
+ *
+ * Parse + validate an RFC 8460 TLS-RPT aggregate report. Accepts:
+ *   - Raw `application/tlsrpt+json` bytes (Buffer or string).
+ *   - `application/tlsrpt+gzip` bytes (gzip magic auto-detected via
+ *     `0x1f 0x8b` per RFC 1952, or routed when `opts.contentType`
+ *     names a gzip media-type).
+ *
+ * Refusal posture:
+ *   - Compressed payload > `opts.maxCompressedBytes` (default 4 MiB)
+ *     → `mail-tlsrpt/oversize-compressed`.
+ *   - Decompressed payload > `opts.maxDecompressedBytes` (default
+ *     32 MiB) → `mail-tlsrpt/gunzip-bomb`.
+ *   - Compression ratio > `opts.maxRatio` (default 50:1) →
+ *     `mail-tlsrpt/ratio-bomb`.
+ *   - Malformed gzip → `mail-tlsrpt/gunzip-failed`.
+ *   - Routes through `b.guardJson.parse` for proto-pollution / depth
+ *     / key-count defenses before the §4.4 schema walk.
+ *   - Missing REQUIRED §4.4 fields → `mail-tlsrpt/bad-schema`.
+ *   - `policies` MUST be an array (RFC 8460 §4.4 erratum, even for
+ *     single-policy reports).
+ *
+ * @opts
+ *   contentType:           string,    // optional — hint for gzip routing
+ *   maxCompressedBytes:    number,    // default TLSRPT_MAX_COMPRESSED_BYTES (4 MiB)
+ *   maxDecompressedBytes:  number,    // default TLSRPT_MAX_DECOMPRESSED_BYTES (32 MiB)
+ *   maxRatio:              number,    // default 50 (compressed:decompressed cap)
+ *
+ * @example
+ *   var report = b.mail.deploy.parseTlsRptReport(reqBody, {
+ *     contentType: req.headers["content-type"],
+ *   });
+ *   // → { organization-name, date-range: {start, end}, contact-info,
+ *   //     report-id, policies: [{ policy-type, policy-domain, ... }] }
+ */
+function parseTlsRptReport(input, opts) {
+  opts = opts || {};
+  var bytes;
+  if (Buffer.isBuffer(input)) bytes = input;
+  else if (typeof input === "string") bytes = Buffer.from(input, "utf8");
+  else {
+    throw new TlsRptParseError("mail-tlsrpt/bad-input",
+      "parseTlsRptReport: input must be a Buffer or string");
+  }
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["maxCompressedBytes", "maxDecompressedBytes", "maxRatio"],
+    "parseTlsRptReport", TlsRptParseError, "mail-tlsrpt/bad-opts");
+  var maxCompressed   = opts.maxCompressedBytes   || TLSRPT_MAX_COMPRESSED_BYTES;
+  var maxDecompressed = opts.maxDecompressedBytes || TLSRPT_MAX_DECOMPRESSED_BYTES;
+  var maxRatio        = opts.maxRatio             || TLSRPT_MAX_RATIO;
+  if (bytes.length > maxCompressed) {
+    throw new TlsRptParseError("mail-tlsrpt/oversize-compressed",
+      "parseTlsRptReport: compressed payload " + bytes.length +
+      " bytes exceeds maxCompressedBytes=" + maxCompressed);
+  }
+
+  // gzip auto-detect — magic 0x1f 0x8b per RFC 1952. Routes through
+  // the same defensive shape as DMARC RUA (lib/mail-auth.js): bound
+  // decompression at the cap, surface bomb-vs-malformed as distinct
+  // typed errors so audit / alert wiring can react differently.
+  var contentType = (opts.contentType || "").toLowerCase();
+  var compressedLen = bytes.length;
+  var looksGzip = bytes.length >= 2 && bytes[0] === TLSRPT_GZIP_MAGIC_0 && bytes[1] === TLSRPT_GZIP_MAGIC_1;
+  var wasCompressed = false;
+  if (contentType.indexOf("gzip") !== -1 || looksGzip) {
+    wasCompressed = true;
+    try { bytes = zlib.gunzipSync(bytes, { maxOutputLength: maxDecompressed }); }
+    catch (e) {
+      var msg = (e && e.message) || String(e);
+      var isBomb = (e && (e.code === "ERR_BUFFER_TOO_LARGE" || e.code === "ERR_OUT_OF_RANGE")) ||
+                   /output length|max(?:imum)?\s+output|exceeds?/i.test(msg);
+      if (isBomb) {
+        throw new TlsRptParseError("mail-tlsrpt/gunzip-bomb",
+          "parseTlsRptReport: gunzip output exceeded " + maxDecompressed +
+          " bytes (decompression amplification — refused per CVE-2025-0725 class)");
+      }
+      throw new TlsRptParseError("mail-tlsrpt/gunzip-failed",
+        "parseTlsRptReport: gunzip failed: " + msg);
+    }
+    if (compressedLen > 0 && bytes.length / compressedLen > maxRatio) {
+      throw new TlsRptParseError("mail-tlsrpt/ratio-bomb",
+        "parseTlsRptReport: decompression ratio " +
+        Math.round(bytes.length / compressedLen) + ":1 exceeds maxRatio=" +
+        maxRatio + ":1 (decompression amplification — refused)");
+    }
+  }
+
+  // Route through b.guardJson — proto-pollution / depth / key-count
+  // defenses on every untrusted-JSON parse path (closes v0.10.14
+  // detector class for untrusted-json-without-guardjson).
+  var raw;
+  try {
+    raw = guardJson().parse(bytes.toString("utf8"), {
+      maxBytes:  maxDecompressed,
+      maxDepth:  32,                                                                                  // allow:raw-byte-literal — JSON depth cap
+      maxKeys:   1000,                                                                                // allow:raw-byte-literal — top-level key cap
+    });
+  } catch (_e) {
+    // Fall back to b.safeJson.parse if guardJson isn't available (in
+    // certain bootstrap paths). Both refuse __proto__ / depth-bombs.
+    try { raw = safeJson.parse(bytes.toString("utf8")); }
+    catch (e2) {
+      throw new TlsRptParseError("mail-tlsrpt/bad-json",
+        "parseTlsRptReport: JSON parse failed: " + ((e2 && e2.message) || String(e2)));
+    }
+  }
+
+  return _validateTlsRptReport(raw, { wasCompressed: wasCompressed });
+}
+
+function _validateTlsRptReport(raw, ctx) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new TlsRptParseError("mail-tlsrpt/bad-schema",
+      "parseTlsRptReport: top-level must be a JSON object");
+  }
+  // RFC 8460 §4.4 REQUIRED fields.
+  var orgName = raw["organization-name"];
+  var contact = raw["contact-info"];
+  var reportId = raw["report-id"];
+  var dateRange = raw["date-range"];
+  var policies = raw["policies"];
+  if (typeof orgName  !== "string" || orgName.length === 0) {
+    throw new TlsRptParseError("mail-tlsrpt/bad-schema",
+      "parseTlsRptReport: missing required string 'organization-name'");
+  }
+  if (typeof contact !== "string" || contact.length === 0) {
+    throw new TlsRptParseError("mail-tlsrpt/bad-schema",
+      "parseTlsRptReport: missing required string 'contact-info'");
+  }
+  if (typeof reportId !== "string" || reportId.length === 0) {
+    throw new TlsRptParseError("mail-tlsrpt/bad-schema",
+      "parseTlsRptReport: missing required string 'report-id'");
+  }
+  if (!dateRange || typeof dateRange !== "object" ||
+      typeof dateRange["start-datetime"] !== "string" ||
+      typeof dateRange["end-datetime"]   !== "string") {
+    throw new TlsRptParseError("mail-tlsrpt/bad-schema",
+      "parseTlsRptReport: 'date-range' must have string start-datetime + end-datetime");
+  }
+  // RFC 8460 §4.4 erratum — `policies` MUST be an array even for a
+  // single-policy report. Some legacy implementations emit a bare
+  // object; we refuse to normalize so the operator catches the
+  // upstream non-conformance.
+  if (!Array.isArray(policies)) {
+    throw new TlsRptParseError("mail-tlsrpt/bad-schema",
+      "parseTlsRptReport: 'policies' must be an array (RFC 8460 §4.4 erratum); single-policy reports still use [policy] form");
+  }
+  if (policies.length === 0) {
+    throw new TlsRptParseError("mail-tlsrpt/bad-schema",
+      "parseTlsRptReport: 'policies' must be a non-empty array");
+  }
+  if (policies.length > TLSRPT_MAX_POLICIES) {
+    throw new TlsRptParseError("mail-tlsrpt/too-many-policies",
+      "parseTlsRptReport: report has " + policies.length +
+      " policies (cap " + TLSRPT_MAX_POLICIES + ")");
+  }
+  // Codex P2 (v0.10.15) — validate summary counts as finite non-negative
+  // integers before summing. `Number(...) || 0` would accept
+  // `Infinity` (from JSON literal `1e309` or string "Infinity"),
+  // negative values, and arbitrary strings (coerced to NaN→0). Each
+  // is operator-untrusted input on an audit-emitted path.
+  var totalSuccess = 0, totalFailure = 0;
+  for (var i = 0; i < policies.length; i += 1) {
+    _validatePolicy(policies[i], i);
+    var summary = policies[i]["summary"];
+    if (summary && typeof summary === "object") {
+      var sRaw = summary["total-successful-session-count"];
+      var fRaw = summary["total-failure-session-count"];
+      if (sRaw !== undefined) {
+        if (typeof sRaw !== "number" || !isFinite(sRaw) || sRaw < 0 || Math.floor(sRaw) !== sRaw) {
+          throw new TlsRptParseError("mail-tlsrpt/bad-summary",
+            "parseTlsRptReport: policies[" + i + "].summary.total-successful-session-count must be a finite non-negative integer");
+        }
+        totalSuccess += sRaw;
+      }
+      if (fRaw !== undefined) {
+        if (typeof fRaw !== "number" || !isFinite(fRaw) || fRaw < 0 || Math.floor(fRaw) !== fRaw) {
+          throw new TlsRptParseError("mail-tlsrpt/bad-summary",
+            "parseTlsRptReport: policies[" + i + "].summary.total-failure-session-count must be a finite non-negative integer");
+        }
+        totalFailure += fRaw;
+      }
+    }
+  }
+  // Return a normalized shape — preserve every operator-readable
+  // field, plus add framework-attached metadata (sessionTotals,
+  // wasCompressed) that doesn't conflict with the RFC schema.
+  return {
+    "organization-name": orgName,
+    "contact-info":      contact,
+    "report-id":         reportId,
+    "date-range":        {
+      "start-datetime":  dateRange["start-datetime"],
+      "end-datetime":    dateRange["end-datetime"],
+    },
+    "policies":          policies,
+    sessionTotals:       {
+      success:           totalSuccess,
+      failure:           totalFailure,
+    },
+    wasCompressed:       ctx.wasCompressed === true,
+  };
+}
+
+function _validatePolicy(p, idx) {
+  if (!p || typeof p !== "object") {
+    throw new TlsRptParseError("mail-tlsrpt/bad-policy",
+      "parseTlsRptReport: policies[" + idx + "] must be an object");
+  }
+  var policy = p["policy"];
+  if (!policy || typeof policy !== "object") {
+    throw new TlsRptParseError("mail-tlsrpt/bad-policy",
+      "parseTlsRptReport: policies[" + idx + "].policy missing");
+  }
+  var pType = policy["policy-type"];
+  if (!TLSRPT_POLICY_TYPES[pType]) {
+    throw new TlsRptParseError("mail-tlsrpt/bad-policy",
+      "parseTlsRptReport: policies[" + idx + "].policy.policy-type '" + pType +
+      "' not in {sts, tlsa, no-policy-found}");
+  }
+  if (typeof policy["policy-domain"] !== "string" || policy["policy-domain"].length === 0) {
+    throw new TlsRptParseError("mail-tlsrpt/bad-policy",
+      "parseTlsRptReport: policies[" + idx + "].policy.policy-domain missing");
+  }
+  // policy-string is optional for no-policy-found, REQUIRED otherwise.
+  // We don't enforce — operators may receive partial reports from
+  // legacy reporters; we surface the field as-is.
+  var failureDetails = p["failure-details"];
+  if (failureDetails !== undefined) {
+    if (!Array.isArray(failureDetails)) {
+      throw new TlsRptParseError("mail-tlsrpt/bad-policy",
+        "parseTlsRptReport: policies[" + idx + "].failure-details must be an array");
+    }
+    if (failureDetails.length > TLSRPT_MAX_FAILURE_DETAILS) {
+      throw new TlsRptParseError("mail-tlsrpt/too-many-failures",
+        "parseTlsRptReport: policies[" + idx + "] has " + failureDetails.length +
+        " failure-details (cap " + TLSRPT_MAX_FAILURE_DETAILS + ")");
+    }
+    for (var k = 0; k < failureDetails.length; k += 1) {
+      var fd = failureDetails[k];
+      if (!fd || typeof fd !== "object") {
+        throw new TlsRptParseError("mail-tlsrpt/bad-failure-detail",
+          "parseTlsRptReport: policies[" + idx + "].failure-details[" + k + "] must be an object");
+      }
+      if (typeof fd["result-type"] === "string" && !TLSRPT_RESULT_TYPES[fd["result-type"]]) {
+        // Unknown result-type — surface as audit metadata but don't
+        // refuse; RFC 8460 §4.4 result-type registry can grow over
+        // time and we shouldn't break on new IANA entries.
+      }
+    }
+  }
+}
+
+/**
+ * @primitive  b.mail.deploy.tlsRptReportSchema
+ * @signature  b.mail.deploy.tlsRptReportSchema()
+ * @since      0.10.15
+ * @status     stable
+ * @related    b.mail.deploy.parseTlsRptReport
+ *
+ * Returns a structured RFC 8460 §4.4 schema descriptor — operator
+ * dashboards consume this to render report shape consistently.
+ * The descriptor names every required + optional field with type +
+ * cardinality + brief description. Pure function; safe to cache.
+ *
+ * @example
+ *   var schema = b.mail.deploy.tlsRptReportSchema();
+ *   schema.required.indexOf("report-id") !== -1;  // → true
+ */
+function tlsRptReportSchema() {
+  return {
+    rfc: "RFC 8460 §4.4",
+    required: [
+      "organization-name", "contact-info", "report-id", "date-range", "policies",
+    ],
+    fields: {
+      "organization-name":   { type: "string",  required: true,  description: "Reporter organisation display name." },
+      "contact-info":         { type: "string",  required: true,  description: "Email / URI for reporter contact." },
+      "report-id":            { type: "string",  required: true,  description: "Reporter-issued unique report identifier (RFC 5322 msg-id shape)." },
+      "date-range":           { type: "object",  required: true,  description: "Window the report covers; { start-datetime, end-datetime } in RFC 3339 form." },
+      "policies":             { type: "array",   required: true,  description: "Array of policy evaluations (RFC 8460 §4.4 erratum — always array, even for single-policy reports)." },
+    },
+    policyFields: {
+      "policy":               { type: "object",  required: true,  description: "{ policy-type, policy-string, policy-domain, mx-host }." },
+      "summary":              { type: "object",  required: false, description: "{ total-successful-session-count, total-failure-session-count }." },
+      "failure-details":      { type: "array",   required: false, description: "Per-failure details (result-type, sending-mta-ip, etc.)." },
+    },
+    policyTypes:  Object.keys(TLSRPT_POLICY_TYPES),
+    resultTypes:  Object.keys(TLSRPT_RESULT_TYPES),
+  };
+}
+
+/**
+ * @primitive  b.mail.deploy.tlsRptIngestHttp
+ * @signature  b.mail.deploy.tlsRptIngestHttp(opts)
+ * @since      0.10.15
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.mail.deploy.parseTlsRptReport, b.mail.deploy.tlsRptReportSchema
+ *
+ * Returns an `(req, res)` request handler mounted at the operator's
+ * `rua=https://<host>/<path>` endpoint. Implements the receive-side
+ * of RFC 8460 §5.4:
+ *
+ *   - POST only — non-POST returns 405 with Allow: POST.
+ *   - Accepts `application/tlsrpt+json` and `application/tlsrpt+gzip`
+ *     (RFC 8460 §6.4-6.5 IANA media types). 415 on others.
+ *   - Body size cap (default 4 MiB compressed) — 413 on exceed.
+ *   - Routes the bytes through `parseTlsRptReport`. 400 on parse
+ *     failure (with `Error-Type:` header naming the typed error
+ *     code). 201 on accept.
+ *   - Calls `opts.onAccept(report, req)` after successful parse.
+ *     Operator's hook decides storage (most operators journal +
+ *     emit a metric); the framework does NOT persist by default.
+ *   - Emits a `mail.tlsrpt.ingest_http` audit event with
+ *     posture-aware payload (organization-name, report-id,
+ *     policy-domain set, session totals).
+ *
+ * Authentication discipline (Codex P2 v0.10.15):
+ *   - `trustedReporters` is a CONTENT-SIDE soft filter — it compares
+ *     the reporter's self-declared `organization-name` field (the
+ *     report body, operator-untrusted) against the operator's
+ *     allowlist. A hostile sender can forge any `organization-name`
+ *     string to bypass it. This option is ADVISORY: a tripwire that
+ *     surfaces unexpected reporter-name strings in audit, not an
+ *     authentication boundary.
+ *   - For real authentication, supply `opts.authenticate(req)` — the
+ *     hook fires BEFORE parsing the body and returns truthy / falsy
+ *     (or a Promise). False / falsy refuses with 401 + the
+ *     `mail-tlsrpt/unauthenticated` audit code. Operators wire this
+ *     to their mTLS-peer-cert / IP-allowlist / signed-header /
+ *     reverse-proxy auth boundary. The framework intentionally does
+ *     NOT couple to any specific auth scheme.
+ *
+ * @opts
+ *   authenticate:            Function,  // (req) → boolean | Promise<boolean>; SHA real auth boundary
+ *   trustedReporters:        string[],  // ADVISORY content filter on report.organization-name (operator-untrusted field)
+ *   maxCompressedBytes:      number,    // default 4 MiB
+ *   maxDecompressedBytes:    number,    // default 32 MiB
+ *   maxRatio:                number,    // default 50
+ *   onAccept:                Function,  // (report, req) → void | Promise
+ *   onRefuse:                Function,  // (errCode, errMessage, req) → void
+ *   audit:                   object,    // optional b.audit handle (default: framework audit)
+ *
+ * @example
+ *   app.post("/tlsrpt", b.mail.deploy.tlsRptIngestHttp({
+ *     onAccept: function (report) {
+ *       b.journal.append({ kind: "tlsrpt", report: report });
+ *     },
+ *   }));
+ */
+function tlsRptIngestHttp(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["authenticate", "trustedReporters", "maxCompressedBytes",
+                       "maxDecompressedBytes", "maxRatio", "onAccept", "onRefuse",
+                       "audit", "compliance"],
+    "mail.deploy.tlsRptIngestHttp");
+  validateOpts.optionalFunction(opts.authenticate, "tlsRptIngestHttp: opts.authenticate",
+    MailDeployError, "mail-tlsrpt/bad-opts");
+  if (opts.trustedReporters !== undefined &&
+      (!Array.isArray(opts.trustedReporters) ||
+       opts.trustedReporters.some(function (s) { return typeof s !== "string"; }))) {
+    throw new MailDeployError("mail-tlsrpt/bad-opts",
+      "tlsRptIngestHttp: opts.trustedReporters must be an array of strings");
+  }
+  var authenticate = typeof opts.authenticate === "function" ? opts.authenticate : null;
+  var trusted = opts.trustedReporters
+    ? Object.freeze(opts.trustedReporters.reduce(function (a, s) { a[s] = 1; return a; }, {}))
+    : null;
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxCompressedBytes, "maxCompressedBytes", MailDeployError, "mail-tlsrpt/bad-opts");
+  var maxCompressed = opts.maxCompressedBytes || TLSRPT_MAX_COMPRESSED_BYTES;
+  // Cache the other caps so the per-request parser call sees them.
+  var parseOpts = {
+    maxCompressedBytes:   maxCompressed,
+    maxDecompressedBytes: opts.maxDecompressedBytes,
+    maxRatio:             opts.maxRatio,
+  };
+  var onAccept = typeof opts.onAccept === "function" ? opts.onAccept : null;
+  var onRefuse = typeof opts.onRefuse === "function" ? opts.onRefuse : null;
+
+  return function tlsRptHandler(req, res) {
+    if (req.method !== "POST") {
+      res.writeHead(405, { "Allow": "POST", "Content-Type": "text/plain" });                          // allow:raw-byte-literal allow:raw-time-literal — RFC 8460 §5.4 status code
+      res.end("RFC 8460 §5.4 requires POST\n");
+      return;
+    }
+    var ct = (req.headers["content-type"] || "").toLowerCase();
+    var ctRoot = ct.split(";")[0].trim();
+    if (ctRoot !== "application/tlsrpt+json" && ctRoot !== "application/tlsrpt+gzip") {
+      _safeAuditEmit(opts.audit, "mail.tlsrpt.ingest_http", "denied", {
+        reason: "bad-content-type", contentType: ctRoot,
+      });
+      if (onRefuse) try { onRefuse("mail-tlsrpt/bad-content-type", "unexpected content-type " + ctRoot, req); }
+      catch (_e) { /* drop-silent */ }
+      res.writeHead(415, { "Content-Type": "text/plain", "Accept": "application/tlsrpt+json, application/tlsrpt+gzip" });   // allow:raw-byte-literal allow:raw-time-literal — RFC 8460 §5.4 status code
+      res.end("RFC 8460 §6.4-6.5 media types required\n");
+      return;
+    }
+    // Codex P2 (v0.10.15) — real-authentication boundary BEFORE body
+    // collection. The operator-supplied `authenticate(req)` hook
+    // routes to mTLS peer-cert / IP-allowlist / signed-header /
+    // reverse-proxy header inspection. Sync-or-async; falsy → 401.
+    if (authenticate) {
+      var authPromise;
+      try { authPromise = Promise.resolve(authenticate(req)); }
+      catch (e) { authPromise = Promise.reject(e); }
+      authPromise.then(function (ok) {
+        if (!ok) {
+          _safeAuditEmit(opts.audit, "mail.tlsrpt.ingest_http", "denied", { reason: "unauthenticated" });
+          if (onRefuse) try { onRefuse("mail-tlsrpt/unauthenticated", "authenticate(req) returned falsy", req); }
+          catch (_e) { /* drop-silent */ }
+          res.writeHead(401, { "Content-Type": "text/plain", "Error-Type": "mail-tlsrpt/unauthenticated" });   // allow:raw-byte-literal allow:raw-time-literal — RFC 8460 §5.4 status code
+          res.end("authentication required\n");
+          return;
+        }
+        _collectAndProcess();
+      }, function (err) {
+        _safeAuditEmit(opts.audit, "mail.tlsrpt.ingest_http", "denied", {
+          reason: "auth-error", message: (err && err.message) || String(err),
+        });
+        if (onRefuse) try { onRefuse("mail-tlsrpt/auth-error", (err && err.message) || String(err), req); }
+        catch (_e) { /* drop-silent */ }
+        res.writeHead(500, { "Content-Type": "text/plain", "Error-Type": "mail-tlsrpt/auth-error" });   // allow:raw-byte-literal allow:raw-time-literal — RFC 8460 §5.4 status code
+        res.end("authenticate hook threw\n");
+      });
+      return;
+    }
+    _collectAndProcess();
+
+    function _collectAndProcess() {
+    var collector = safeBuffer.boundedChunkCollector({
+      maxBytes:   maxCompressed,
+      errorClass: MailDeployError,
+      sizeCode:   "mail-tlsrpt/oversize-compressed",
+    });
+    var aborted = false;
+    req.on("data", function (chunk) {
+      if (aborted) return;
+      try { collector.push(chunk); }
+      catch (e) {
+        aborted = true;
+        try { req.destroy(); } catch (_e) { /* best-effort */ }
+        _safeAuditEmit(opts.audit, "mail.tlsrpt.ingest_http", "denied", {
+          reason: "oversize-compressed", bytes: collector.bytesCollected(), cap: maxCompressed,
+        });
+        if (onRefuse) try { onRefuse("mail-tlsrpt/oversize-compressed", "body exceeded " + maxCompressed + " bytes", req); }
+        catch (_e) { /* drop-silent */ }
+        if (!res.headersSent) {
+          res.writeHead(413, { "Content-Type": "text/plain" });                                       // allow:raw-byte-literal allow:raw-time-literal — RFC 8460 §5.4 status code
+          res.end("RFC 8460 §5.4 — body exceeds " + maxCompressed + " bytes\n");
+        }
+        void e;   // _e shadowed by lower scope; mark intent
+      }
+    });
+    req.on("end", function () {
+      if (aborted) return;
+      var report;
+      try {
+        report = parseTlsRptReport(collector.result(), Object.assign({
+          contentType: ctRoot,
+        }, parseOpts));
+      } catch (e) {
+        var code = (e && e.code) || "mail-tlsrpt/unknown";
+        _safeAuditEmit(opts.audit, "mail.tlsrpt.ingest_http", "denied", {
+          reason: code, message: (e && e.message) || String(e),
+        });
+        if (onRefuse) try { onRefuse(code, (e && e.message) || String(e), req); }
+        catch (_e) { /* drop-silent */ }
+        var status = code === "mail-tlsrpt/oversize-compressed" ? 413
+                  : code === "mail-tlsrpt/gunzip-bomb"           ? 413
+                  : code === "mail-tlsrpt/ratio-bomb"             ? 413
+                  : code === "mail-tlsrpt/bad-content-type"       ? 415
+                  : 400;                                                                              // allow:raw-byte-literal allow:raw-time-literal — RFC 8460 §5.4 status code
+        res.writeHead(status, { "Content-Type": "text/plain", "Error-Type": code });
+        res.end("RFC 8460 §5.4 — refused: " + code + "\n");
+        return;
+      }
+      if (trusted && !trusted[report["organization-name"]]) {
+        _safeAuditEmit(opts.audit, "mail.tlsrpt.ingest_http", "denied", {
+          reason: "untrusted-reporter", reporter: report["organization-name"],
+        });
+        if (onRefuse) try { onRefuse("mail-tlsrpt/untrusted-reporter",
+          "reporter '" + report["organization-name"] + "' not in trustedReporters", req); }
+        catch (_e) { /* drop-silent */ }
+        res.writeHead(403, { "Content-Type": "text/plain", "Error-Type": "mail-tlsrpt/untrusted-reporter" });   // allow:raw-byte-literal allow:raw-time-literal — RFC 8460 §5.4 status code
+        res.end("RFC 8460 §5.3-class: untrusted reporter\n");
+        return;
+      }
+      var policyDomains = report.policies.map(function (p) {
+        return p && p.policy && p.policy["policy-domain"];
+      }).filter(Boolean);
+      _safeAuditEmit(opts.audit, "mail.tlsrpt.ingest_http", "success", {
+        reporter:         report["organization-name"],
+        reportId:         report["report-id"],
+        policyDomains:    policyDomains,
+        sessionTotals:    report.sessionTotals,
+        policyCount:      report.policies.length,
+        wasCompressed:    report.wasCompressed,
+      });
+      if (onAccept) {
+        try {
+          var ret = onAccept(report, req);
+          if (ret && typeof ret.then === "function") {
+            ret.then(function () {
+              if (!res.headersSent) {
+                res.writeHead(201, { "Content-Type": "text/plain" });                                 // allow:raw-byte-literal allow:raw-time-literal — RFC 8460 §5.4 status code
+                res.end("RFC 8460 §5.4 — accepted\n");
+              }
+            }, function (_e) {
+              if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "text/plain" });                                 // allow:raw-byte-literal — internal-error status
+                res.end("internal error processing report\n");
+              }
+            });
+            return;
+          }
+        } catch (_e) { /* fall through to 201 — operator hook is best-effort */ }
+      }
+      res.writeHead(201, { "Content-Type": "text/plain" });                                           // allow:raw-byte-literal allow:raw-time-literal — RFC 8460 §5.4 status code
+      res.end("RFC 8460 §5.4 — accepted\n");
+    });
+    req.on("error", function () {
+      if (aborted) return;
+      aborted = true;
+      _safeAuditEmit(opts.audit, "mail.tlsrpt.ingest_http", "denied", { reason: "req-error" });
+      if (!res.headersSent) {
+        res.writeHead(400, { "Content-Type": "text/plain" });                                         // allow:raw-byte-literal allow:raw-time-literal — RFC 8460 §5.4 status code
+        res.end("malformed request\n");
+      }
+    });
+    }   // end _collectAndProcess
+  };
+}
+
+function _safeAuditEmit(handle, action, outcome, metadata) {
+  try {
+    var a = handle || audit();
+    if (a && typeof a.safeEmit === "function") {
+      a.safeEmit({ action: action, outcome: outcome, actor: {}, metadata: metadata });
+    }
+  } catch (_e) { /* drop-silent — audit failure must not block ingest */ }
+}
+
 module.exports = {
-  mtaStsPublish:    mtaStsPublish,
-  danePublish:      danePublish,
-  autoConfigXml:    autoConfigXml,
-  autoDiscoverXml:  autoDiscoverXml,
-  MailDeployError:  MailDeployError,
+  mtaStsPublish:       mtaStsPublish,
+  danePublish:         danePublish,
+  autoConfigXml:       autoConfigXml,
+  autoDiscoverXml:     autoDiscoverXml,
+  parseTlsRptReport:   parseTlsRptReport,
+  tlsRptReportSchema:  tlsRptReportSchema,
+  tlsRptIngestHttp:    tlsRptIngestHttp,
+  MailDeployError:     MailDeployError,
+  TlsRptParseError:    TlsRptParseError,
 };