@blamejs/core 0.8.52 → 0.8.58

package/lib/mail-bounce.js

@@ -27,22 +27,28 @@
  *   `onBounce(event)` so the suppression list can be updated before
  *   the 200 response goes back.
  *
- *   Generic RFC 3464 DSN is intentionally NOT a built-in vendor —
- *   parsing arbitrary MTA reports needs a full email parser the
- *   framework does not vendor for this surface. Operators with raw
- *   DSN inflow supply `{ parser }` to plug a custom normalizer.
+ *   Generic RFC 3464 / RFC 3461 / RFC 6533 DSN is wired in as
+ *   `b.mailBounce.dsn.parse` / `b.mailBounce.dsn.build` — a parser for
+ *   raw multipart/report message/delivery-status MIME bounces (the
+ *   shape any spec-conforming MTA returns) and a generator that builds
+ *   the same shape for operators that need to issue bounces from their
+ *   own MTA. Operators with bespoke vendor inflow can still supply
+ *   `{ parser }` to plug a custom normalizer onto `parse` / `handler`.
  *
  * @card
  *   Inbound mail bounce-handler — parse the vendor's webhook DSN / complaint / delivery payload, normalize it into one event shape, classify hard vs soft bounces, and feed an operator-supplied suppression-list hook.
  */
 
+var crypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
+var mimeParse = require("./mime-parse");
 var numericBounds = require("./numeric-bounds");
 var audit = lazyRequire(function () { return require("./audit"); });
 var safeBuffer = require("./safe-buffer");
 var safeJson = require("./safe-json");
 var C = require("./constants");
 var requestHelpers = require("./request-helpers");
+var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
 var HTTP = requestHelpers.HTTP_STATUS;
@@ -558,6 +564,372 @@ function handler(opts) {
   };
 }
 
+// ---- Generic RFC 3464 / RFC 3461 / RFC 6533 DSN ----
+//
+// A delivery status notification is a multipart/report MIME body:
+//
+//   Content-Type: multipart/report;
+//                 report-type=delivery-status;
+//                 boundary="boundary-string"
+//
+//   --boundary-string
+//   Content-Type: text/plain; charset=us-ascii
+//
+//   <human-readable description of the failure>
+//
+//   --boundary-string
+//   Content-Type: message/delivery-status
+//
+//   Reporting-MTA: dns; mta.example.com
+//   Arrival-Date: Mon, 28 Apr 2026 12:00:00 +0000
+//
+//   Original-Recipient: rfc822;user@example.com
+//   Final-Recipient: rfc822;user@example.com
+//   Action: failed
+//   Status: 5.1.1
+//   Remote-MTA: dns; mx.example.com
+//   Diagnostic-Code: smtp; 550 5.1.1 No such user
+//
+//   --boundary-string
+//   Content-Type: message/rfc822
+//
+//   <original message headers + body>
+//
+//   --boundary-string--
+//
+// RFC 3461 adds the SMTP NOTIFY=SUCCESS,FAILURE,DELAY and RET=FULL,HDRS
+// extensions — they're carried inside the SMTP envelope, but the DSN
+// the framework generates / parses ends up reflecting that operator
+// choice via the `originalMessage` decision (full body vs headers
+// only) and the per-recipient `Action` field (delivered / failed /
+// delayed / relayed / expanded).
+//
+// RFC 6533 (SMTPUTF8 / EAI) extends the address-type tag from rfc822
+// to utf-8 so internationalized mailbox names ride through. The
+// parser accepts both; the generator picks utf-8 when the recipient
+// contains non-ASCII bytes.
+
+// Per-message DSN fields (RFC 3464 §2.2). Listed for validation +
+// canonical-case re-emission.
+var DSN_PER_MESSAGE_FIELDS = {
+  "original-envelope-id":  "Original-Envelope-Id",
+  "reporting-mta":         "Reporting-MTA",
+  "dsn-gateway":           "DSN-Gateway",
+  "received-from-mta":     "Received-From-MTA",
+  "arrival-date":          "Arrival-Date",
+};
+
+// Per-recipient DSN fields (RFC 3464 §2.3).
+var DSN_PER_RECIPIENT_FIELDS = {
+  "original-recipient":    "Original-Recipient",
+  "final-recipient":       "Final-Recipient",
+  "action":                "Action",
+  "status":                "Status",
+  "remote-mta":            "Remote-MTA",
+  "diagnostic-code":       "Diagnostic-Code",
+  "last-attempt-date":     "Last-Attempt-Date",
+  "final-log-id":          "Final-Log-ID",
+  "will-retry-until":      "Will-Retry-Until",
+};
+
+// Action token allowlist — RFC 3464 §2.3.3.
+var DSN_ACTIONS = {
+  "failed":     true,
+  "delayed":    true,
+  "delivered":  true,
+  "relayed":    true,
+  "expanded":   true,
+};
+
+// Body cap for the DSN parser. The parser walks the raw bytes once;
+// any payload above 1 MiB is pathological — no spec-conforming DSN
+// approaches that, and uncapped parsing would let a hostile peer pin
+// CPU on regex backtracking inside the header decoder.
+var DSN_MAX_BYTES = C.BYTES.mib(1);
+
+function _parseDeliveryStatusBody(body) {
+  // RFC 3464 §2.1 — message/delivery-status is per-message field group
+  // followed by ONE OR MORE per-recipient groups, each separated by an
+  // empty line.
+  var groups = body.split(/\r?\n\r?\n/).map(function (g) { return g.trim(); }).filter(Boolean);
+  if (groups.length === 0) return { perMessage: {}, perRecipients: [] };
+  var perMessage = {};
+  var msgHeaders = mimeParse.parseHeaderBlock(groups[0]);
+  for (var i = 0; i < msgHeaders.length; i += 1) {
+    perMessage[msgHeaders[i].name.toLowerCase()] = msgHeaders[i].value;
+  }
+  var perRecipients = [];
+  for (var g = 1; g < groups.length; g += 1) {
+    var headers = mimeParse.parseHeaderBlock(groups[g]);
+    if (headers.length === 0) continue;
+    var rec = {};
+    for (var k = 0; k < headers.length; k += 1) {
+      rec[headers[k].name.toLowerCase()] = headers[k].value;
+    }
+    perRecipients.push(rec);
+  }
+  return { perMessage: perMessage, perRecipients: perRecipients };
+}
+
+function _actionToSubType(action) {
+  // RFC 3464 §2.3.3 actions map onto the framework's bounce-shape
+  // vocabulary. failed -> hard, delayed -> soft. delivered / relayed /
+  // expanded come back as type=delivery; the parser swallows those
+  // before this lookup runs.
+  var a = (action || "").toLowerCase();
+  if (a === "failed")   return "hard";
+  if (a === "delayed")  return "soft";
+  return "unknown";
+}
+
+function _parseDsn(rawMessage) {
+  if (typeof rawMessage !== "string" || rawMessage.length === 0) {
+    throw _err("bounce/dsn-parse-failed",
+      "mailBounce.dsn.parse: rawMessage must be a non-empty string");
+  }
+  // Hot-path body cap. Above this limit the parser stops trying to
+  // interpret the bytes — pathological inputs become a typed error
+  // rather than a regex-backtrack hang.
+  if (rawMessage.length > DSN_MAX_BYTES) {
+    throw _err("bounce/dsn-parse-failed",
+      "mailBounce.dsn.parse: message exceeds " + DSN_MAX_BYTES + " bytes");
+  }
+
+  var top = mimeParse.splitHeadersAndBody(rawMessage);
+  var ctRaw = mimeParse.findHeader(top.headers, "Content-Type");
+  if (!ctRaw) {
+    throw _err("bounce/dsn-malformed",
+      "mailBounce.dsn.parse: missing top-level Content-Type");
+  }
+  var ct = mimeParse.parseContentType(ctRaw);
+  if (ct.type !== "multipart/report") {
+    throw _err("bounce/dsn-malformed",
+      "mailBounce.dsn.parse: top-level Content-Type must be multipart/report; got " + ct.type);
+  }
+  if (ct.params["report-type"] && ct.params["report-type"].toLowerCase() !== "delivery-status") {
+    throw _err("bounce/dsn-malformed",
+      "mailBounce.dsn.parse: report-type must be delivery-status; got " + ct.params["report-type"]);
+  }
+  var boundary = ct.params.boundary;
+  if (!boundary) {
+    throw _err("bounce/dsn-malformed",
+      "mailBounce.dsn.parse: multipart/report missing boundary parameter");
+  }
+
+  var parts = mimeParse.splitMimeParts(top.body, boundary);
+  if (parts.length < 2) {
+    throw _err("bounce/dsn-malformed",
+      "mailBounce.dsn.parse: multipart/report needs at least 2 parts (text + delivery-status); got " + parts.length);
+  }
+
+  // Find the message/delivery-status part.
+  var statusBody = null;
+  var humanText  = null;
+  var originalMessage = null;
+  for (var i = 0; i < parts.length; i += 1) {
+    var partSplit = mimeParse.splitHeadersAndBody(parts[i].replace(/^\r?\n/, ""));
+    var partCtRaw = mimeParse.findHeader(partSplit.headers, "Content-Type") || "text/plain";
+    var partCt = mimeParse.parseContentType(partCtRaw);
+    if (partCt.type === "message/delivery-status") {
+      statusBody = partSplit.body;
+    } else if (partCt.type === "text/plain" && humanText === null) {
+      humanText = partSplit.body;
+    } else if (partCt.type === "message/rfc822" || partCt.type === "text/rfc822-headers") {
+      originalMessage = partSplit.body;
+    }
+  }
+
+  if (statusBody === null) {
+    throw _err("bounce/dsn-malformed",
+      "mailBounce.dsn.parse: no message/delivery-status part found");
+  }
+
+  var status = _parseDeliveryStatusBody(statusBody);
+  if (status.perRecipients.length === 0) {
+    throw _err("bounce/dsn-malformed",
+      "mailBounce.dsn.parse: message/delivery-status has no per-recipient groups");
+  }
+
+  // First recipient drives the normalized event (matches the SES /
+  // postmark convention; multi-recipient DSNs are exposed via
+  // event.raw.allRecipients for operators that need fan-out).
+  var recip = status.perRecipients[0];
+  var action = (recip["action"] || "").toLowerCase();
+  var finalRecipient = mimeParse.stripAddressType(recip["final-recipient"]) ||
+                       mimeParse.stripAddressType(recip["original-recipient"]);
+  if (!finalRecipient) {
+    throw _err("bounce/dsn-malformed",
+      "mailBounce.dsn.parse: per-recipient group missing Final-Recipient");
+  }
+  if (action && !DSN_ACTIONS[action]) {
+    throw _err("bounce/dsn-malformed",
+      "mailBounce.dsn.parse: Action token '" + action + "' is not RFC 3464 §2.3.3");
+  }
+
+  var type, subType;
+  if (action === "delivered" || action === "relayed" || action === "expanded") {
+    type = "delivery"; subType = null;
+  } else {
+    type = "bounce"; subType = _actionToSubType(action);
+  }
+
+  var diagnosticCode = recip["diagnostic-code"] || null;
+  // RFC 3464 §2.3.6 — Diagnostic-Code is `diagnostic-type;
+  // diagnostic`. Most are `smtp; <reply>` — strip the type prefix to
+  // surface the human-readable reason in audit metadata.
+  var reason = diagnosticCode ? mimeParse.stripAddressType(diagnosticCode) : null;
+  if (!reason && humanText) {
+    // Fall back to the human-readable section when the spec'd
+    // Diagnostic-Code field is absent (legacy MTAs).
+    reason = humanText.trim().split(/\r?\n/).slice(0, 5).join(" ").slice(0, 500) || null;
+  }
+
+  var arrivalDate = status.perMessage["arrival-date"];
+  var messageId = mimeParse.findHeader(top.headers, "Message-ID") || null;
+
+  return {
+    vendor:    "rfc3464",
+    type:      type,
+    subType:   subType,
+    recipient: finalRecipient,
+    messageId: messageId,
+    reason:    reason,
+    timestamp: arrivalDate || new Date().toISOString(),
+    raw: {
+      perMessage:      status.perMessage,
+      allRecipients:   status.perRecipients,
+      humanText:       humanText,
+      originalMessage: originalMessage,
+      // Status code (per RFC 3463 — class.subject.detail) is one of the
+      // most useful operator fields; surface it on raw so policy code
+      // can branch without re-parsing.
+      status:          recip["status"] || null,
+      action:          action || null,
+      diagnosticCode:  diagnosticCode,
+    },
+  };
+}
+
+function _foldFieldValue(name, value) {
+  // RFC 5322 §2.2.3 — long lines fold at WSP. Keep it simple: emit
+  // `Name: value` and let downstream MTAs handle further folding.
+  return name + ": " + value + "\r\n";
+}
+
+function _generateBoundary() {
+  return "blamejs-dsn-" + crypto.generateToken(C.BYTES.bytes(12));
+}
+
+function _buildDsn(opts) {
+  validateOpts.requireObject(opts, "mailBounce.dsn.build", MailBounceError, "bounce/dsn-malformed");
+  validateOpts.requireNonEmptyString(opts.finalRecipient,
+    "mailBounce.dsn.build: opts.finalRecipient", MailBounceError, "bounce/dsn-malformed");
+  var action = String(opts.action || "failed").toLowerCase();
+  if (!DSN_ACTIONS[action]) {
+    throw _err("bounce/dsn-malformed",
+      "mailBounce.dsn.build: opts.action must be one of " +
+      Object.keys(DSN_ACTIONS).join(" / ") + "; got '" + action + "'");
+  }
+  if (typeof opts.status !== "string" || !/^\d\.\d{1,3}\.\d{1,3}$/.test(opts.status)) {
+    throw _err("bounce/dsn-malformed",
+      "mailBounce.dsn.build: opts.status must match RFC 3463 class.subject.detail; got '" +
+      String(opts.status) + "'");
+  }
+
+  var reportingMta   = opts.reportingMta || "dns; localhost";
+  var arrivalDate    = opts.arrivalDate  || new Date().toUTCString();
+  var originalMessage = opts.originalMessage || null;
+  var diagnosticCode = opts.diagnosticCode || null;
+  var remoteMta      = opts.remoteMta || null;
+  var humanText      = opts.humanText || (
+    "This is the mail system at " + reportingMta + ".\r\n\r\n" +
+    "Your message could not be delivered to:\r\n\r\n" +
+    "  " + opts.finalRecipient + "\r\n\r\n" +
+    (diagnosticCode ? "The remote server reported: " + diagnosticCode + "\r\n" : ""));
+
+  var recipType = mimeParse.addressType(opts.finalRecipient);
+  var origRecipType = opts.originalRecipient ? mimeParse.addressType(opts.originalRecipient) : recipType;
+
+  var boundary = _generateBoundary();
+  var lines = [];
+  lines.push("MIME-Version: 1.0");
+  lines.push('Content-Type: multipart/report; report-type=delivery-status; boundary="' + boundary + '"');
+  if (opts.from)    lines.push("From: " + opts.from);
+  if (opts.to)      lines.push("To: " + opts.to);
+  if (opts.subject) lines.push("Subject: " + opts.subject);
+  if (opts.messageId) lines.push("Message-ID: " + opts.messageId);
+  lines.push("");
+
+  // Part 1 - human-readable description.
+  lines.push("--" + boundary);
+  lines.push("Content-Type: text/plain; charset=utf-8");
+  lines.push("Content-Transfer-Encoding: 8bit");
+  lines.push("");
+  lines.push(humanText);
+  lines.push("");
+
+  // Part 2 - message/delivery-status.
+  lines.push("--" + boundary);
+  lines.push("Content-Type: message/delivery-status");
+  lines.push("");
+  // Per-message group.
+  var perMessage = "";
+  perMessage += _foldFieldValue("Reporting-MTA", reportingMta);
+  perMessage += _foldFieldValue("Arrival-Date", arrivalDate);
+  if (opts.originalEnvelopeId) {
+    perMessage += _foldFieldValue("Original-Envelope-Id", opts.originalEnvelopeId);
+  }
+  lines.push(perMessage.replace(/\r\n$/, ""));
+  lines.push("");
+  // Per-recipient group.
+  var perRecip = "";
+  if (opts.originalRecipient) {
+    perRecip += _foldFieldValue("Original-Recipient",
+      origRecipType + ";" + opts.originalRecipient);
+  }
+  perRecip += _foldFieldValue("Final-Recipient",
+    recipType + ";" + opts.finalRecipient);
+  perRecip += _foldFieldValue("Action", action);
+  perRecip += _foldFieldValue("Status", opts.status);
+  if (remoteMta) {
+    perRecip += _foldFieldValue("Remote-MTA", remoteMta);
+  }
+  if (diagnosticCode) {
+    perRecip += _foldFieldValue("Diagnostic-Code", diagnosticCode);
+  }
+  if (opts.lastAttemptDate) {
+    perRecip += _foldFieldValue("Last-Attempt-Date", opts.lastAttemptDate);
+  }
+  if (opts.willRetryUntil) {
+    perRecip += _foldFieldValue("Will-Retry-Until", opts.willRetryUntil);
+  }
+  lines.push(perRecip.replace(/\r\n$/, ""));
+  lines.push("");
+
+  // Part 3 (optional) - original message or just headers per RFC 3461
+  // RET= choice. The framework picks the part-type from the
+  // originalMessage shape: if `{ headersOnly: true, headers: "..." }`
+  // is supplied, emit text/rfc822-headers; if a plain string is
+  // supplied, emit message/rfc822 with the full body.
+  if (originalMessage) {
+    lines.push("--" + boundary);
+    if (typeof originalMessage === "object" && originalMessage.headersOnly) {
+      lines.push("Content-Type: text/rfc822-headers");
+      lines.push("");
+      lines.push(originalMessage.headers || "");
+    } else {
+      lines.push("Content-Type: message/rfc822");
+      lines.push("");
+      lines.push(typeof originalMessage === "string" ? originalMessage : "");
+    }
+    lines.push("");
+  }
+
+  lines.push("--" + boundary + "--");
+  lines.push("");
+  return lines.join("\r\n");
+}
+
 module.exports = {
   parse:           parse,
   handler:         handler,
@@ -570,4 +942,14 @@ module.exports = {
     ses:      _parseSes,
     resend:   _parseResend,
   },
+  // Generic RFC 3464 / RFC 3461 / RFC 6533 DSN parser + generator.
+  dsn: {
+    parse: _parseDsn,
+    build: _buildDsn,
+    // Tables surfaced for tests + advanced operator code (e.g. operators
+    // building DSN-shaped reports against a custom action vocabulary).
+    PER_MESSAGE_FIELDS:   DSN_PER_MESSAGE_FIELDS,
+    PER_RECIPIENT_FIELDS: DSN_PER_RECIPIENT_FIELDS,
+    ACTIONS:              DSN_ACTIONS,
+  },
 };