@blamejs/core 0.11.23 → 0.11.24

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.24 (2026-05-20) — **`b.mail.send.deliver` — turnkey outbound SMTP composer (MX → MTA-STS → DANE → REQUIRETLS → DSN).** One factory wires together the full outbound mail chain. The operator hands the primitive an envelope (`{ from, to, rfc822 }`) and gets back per-recipient outcomes: `delivered`, `deferred` (with retry budget), or `failed` (with the corresponding RFC 3464 DSN already composed and the configured DSN sink invoked). Per-recipient handling is independent — one recipient permanently failing does not interfere with another's delivery or retry. MX records are resolved live (operator may inject a resolver for testing), MTA-STS policy (RFC 8461) is fetched + matched against the resolved MX before TLS, DANE TLSA records (RFC 7672) are consulted when present, REQUIRETLS (RFC 8689) is honored, and the per-host SMTP transport is the framework's `b.mail.smtpTransport`. SMTP outcomes are classified deterministically: hard 5xx + null-MX → permanent (with DSN); soft 4xx + DNS / connect / TLS errors → transient (with backoff budget). Recipient cap (1000 per call) and per-host / per-lookup timeout caps are baked in. **Added:** *`b.mail.send.deliver.create(opts) → async deliver(envelope)` — composed outbound delivery* — Factory returns a `deliver(envelope)` async function. `envelope = { from, to[], rfc822 }`. Returns `{ delivered: [{...}], deferred: [{...}], failed: [{...}] }`. Composes `b.network.smtp.policy.mtaSts.fetch` + `.matchMx`, `b.network.smtp.policy.dane.tlsa` + `.verifyChain`, `b.mail.smtpTransport.create`, and `b.audit.safeEmit`. Required opts: `hostname` (EHLO + MAIL FROM identity). Optional: `resolver` (object exposing `resolveMx` / `resolve` — defaults to node:dns/promises); `policy.mtaSts.enabled` (default true); `policy.dane.enabled` (default true); `retry.maxAttempts` (default 5); `retry.backoffMs` (default exponential 60s/5m/30m/2h/12h); `dsn.from` + `dsn.onPermanentFailure(messageBuffer, ctx)` (required only when DSN delivery is desired); `timeouts.mxLookupMs` (default 5s); `timeouts.perHostMs` (default 60s); `transportFactory` (test-injection override). · *Per-recipient outcome classifier (`_classifySmtpOutcome`)* — Maps SMTP reply codes + Node socket / TLS errors onto the `permanent` / `transient` axis. Permanent: SMTP 5xx (any subclass), null-MX RFC 7505 sentinel `.`, no-MX-records, RFC 5321 §3.6.2 unrouteable. Transient: SMTP 4xx (any subclass), TCP connection refused / reset / timeout, TLS handshake failure (when MTA-STS / DANE is not enforce-mode), DNS NXDOMAIN at lookup time. Once `retry.maxAttempts` is exhausted, transient is escalated to permanent with reason `retry exhausted (after N attempts)`. · *RFC 3464 DSN composer (`_buildDsnMessage`)* — Builds a `multipart/report; report-type=delivery-status` message with three parts: human-readable explanation, `message/delivery-status` block (Reporting-MTA, Original-Recipient, Final-Recipient, Action: failed, Status: 5.x.x), and a `message/rfc822-headers` block carrying the failed message's headers. Boundary token is generated via `b.crypto.generateToken(12)` so it can't collide with attacker-chosen header / body bytes. The composed DSN is passed to the operator-supplied `dsn.onPermanentFailure(message, ctx)` sink — the primitive does not itself send the DSN, keeping the operator in control of which transport carries DSNs (typically the same submission service). · *MX failover + per-host audit* — MX records are walked in priority order. A failed connect / TLS / 4xx on the first host falls over to the next; only when every MX has been tried does the recipient receive its final outcome. Each per-host failure emits a structured audit event (`mail.send.deliver.host-fail` with `recipient` + `mxHost` + `priority` + `reason`); the final outcome emits `mail.send.deliver.delivered` / `.deferred` / `.permanent-fail`. Audit is drop-silent on the hot path (catch + ignore). · *Recipient + envelope hard caps* — `MAX_RECIPIENTS_PER_CALL = 1000` refuses oversized fan-out at the factory boundary (5xx-style DoS prevention). `envelope.rfc822` accepts a Buffer or UTF-8 string — strings are converted at the boundary so downstream byte-level reasoning (DKIM, REQUIRETLS, length headers) sees stable bytes. Bad-envelope refusals carry `DeliverError` codes `deliver/bad-envelope`, `/bad-envelope-from`, `/bad-envelope-to`, `/too-many-recipients`, `/bad-envelope-rfc822` — operators get structured surface for each refusal class. **Security:** *MTA-STS enforcement before TLS handshake (RFC 8461)* — When `policy.mtaSts.enabled` (default), MTA-STS policy is fetched for the recipient domain. If the policy mode is `enforce` and a resolved MX hostname does not match an `mx:` entry, the host is refused without attempting TLS. This closes the MX-substitution attack window (`b.mail.send.deliver` cannot be diverted to an attacker-controlled MX even when DNS is hijacked, as long as the recipient publishes MTA-STS). · *DANE TLSA verification when present (RFC 7672)* — When `policy.dane.enabled` (default) and the recipient domain publishes TLSA records, the SMTP transport's TLS certificate chain is verified against the TLSA hash before the SMTP command pipeline starts. TLSA records take precedence over PKIX trust roots for SMTP — RFC 7672 §2.2. · *Boundary token unguessable (DSN boundary-injection defense)* — MIME boundary token in composed DSNs is 12 random bytes hex-encoded via `b.crypto.generateToken` (SHAKE256 over OS-RNG) — not `Date.now()` + `Math.random()`. The boundary appears verbatim in the message; a predictable boundary would let an attacker who controls the failed message's headers craft byte sequences that close the boundary early + inject MIME parts. **Detectors:** *`per-recipient-loop-fallthrough-to-failed` (codebase-patterns)* — A new detector flags per-recipient delivery loops where the `delivered` branch does not exit the iteration before falling into the permanent-failure / DSN-emit path. Encodes the bug class that was caught during this slice's bring-up — a recipient delivering successfully also being added to `failed[]` because the `if (delivered)` branch lacked an explicit `continue`. **References:** [RFC 5321 (Simple Mail Transfer Protocol)](https://www.rfc-editor.org/rfc/rfc5321.html) · [RFC 3464 (Extensible Message Format for Delivery Status Notifications)](https://www.rfc-editor.org/rfc/rfc3464.html) · [RFC 7505 (Null MX no-service resource record)](https://www.rfc-editor.org/rfc/rfc7505.html) · [RFC 8461 (SMTP MTA Strict Transport Security — MTA-STS)](https://www.rfc-editor.org/rfc/rfc8461.html) · [RFC 7672 (SMTP Security via Opportunistic DANE TLS)](https://www.rfc-editor.org/rfc/rfc7672.html) · [RFC 8689 (SMTP REQUIRETLS option)](https://www.rfc-editor.org/rfc/rfc8689.html) · [RFC 3463 (Enhanced Mail System Status Codes)](https://www.rfc-editor.org/rfc/rfc3463.html)
+
 - v0.11.23 (2026-05-20) — **`b.mail.agent.expunge` — hard EXPUNGE with legal-hold + retention-floor refusal gates.** Operators (and the future IMAP EXPUNGE + JMAP Email/set destroyed wire-protocol adapters) get a single canonical path for permanent message removal that refuses to delete anything currently under legal hold or still inside the regulator-mandated retention window. The gate runs per-message; refused ids carry an explicit reason (`legal-hold` / `retention-floor` / `not-in-folder`) plus the floor + age + posture metadata that drove the refusal — wire adapters mirror those reasons to operators verbatim. The destructive SQL runs only on the surviving id set, inside a backend transaction that also bumps folder modseq + decrements quota atomically. **Added:** *`b.mail.agent.expunge({ actor, folder, objectIds })` — hard EXPUNGE primitive* — Composes two refusal gates before the destructive SQL runs. (1) Legal-hold gate: any message whose `legal_hold` flag is set refuses with reason `legal-hold`. The mail-store layer surfaces the flag in per-row metadata; this layer maps it to the operator-facing refusal. (2) Retention-floor gate: under a configured compliance posture (`hipaa` / `pci-dss` / `gdpr` / `soc2`), the regulator-mandated minimum retention TTL is read from `b.retention.COMPLIANCE_RETENTION_FLOOR_MS[posture]` and any message whose age (`now - receivedAt`) is below the floor refuses with reason `retention-floor` plus `floorMs` + `ageMs` + `posture` metadata. Returns `{ deleted: <ids>, refused: [{ id, reason, ... }] }`. Audit event `mail.agent.expunge.success` carries the requested / deleted / refused counts and a reason histogram so dashboards can spot abnormal refusal patterns without parsing per-id detail. · *`b.mailStore.create(...).hardExpunge(folder, objectIds)` — destructive SQL primitive* — Removes messages permanently from a folder inside a single backend transaction: deletes the message row + its flag rows, bumps the folder modseq, decrements the per-folder quota by the freed bytes / count. Returns `{ rows, deleted, refused }` where `refused` carries `{ id, reason: 'legal-hold' | 'not-in-folder' }` for each id the SQL gate refused (legal-hold is mirrored from the column; not-in-folder catches stale ids). The agent layer (`b.mail.agent.expunge`) is responsible for the retention-floor gate; this primitive is the wire-protocol-shaped backend surface. · *`b.mailStore.create(...).fetchByObjectId` returns `legalHold: boolean`* — Pre-existing fetch path now consistently exposes the legal-hold flag in its return shape. Previously the field existed in the returned object via a separate path; this commit consolidates the duplicate exports into a single canonical `legalHold` boolean derived from the SQLite `legal_hold` INTEGER column. **References:** [RFC 9051 (IMAP4rev2 — EXPUNGE semantics, §6.4.3)](https://www.rfc-editor.org/rfc/rfc9051.html) · [RFC 8621 (JMAP Mail — Email/set destroyed)](https://www.rfc-editor.org/rfc/rfc8621.html) · [45 CFR §164.316 (HIPAA — retention of records)](https://www.ecfr.gov/current/title-45/subtitle-A/subchapter-C/part-164/subpart-C/section-164.316) · [PCI-DSS v4.0.1 §3.5.1.1 (retention of cardholder data)](https://www.pcisecuritystandards.org/document_library) · [GDPR Art. 17 (right to erasure — operator-side accountability)](https://gdpr-info.eu/art-17-gdpr/)
 
 - v0.11.22 (2026-05-20) — **`b.cert.create` — turnkey TLS-certificate manager composing ACME + sealed persistence + renewal scheduler + SNI + key escrow.** Operators wiring TLS no longer have to glue ACME + key generation + cert persistence + renewal scheduling + SNI dispatch + escrow by hand. `b.cert.create({ storage, acme, certs, renew, ocsp, audit, compliance })` accepts a declarative manifest of certificates plus the operator's choice of ACME challenge solver, and the manager owns the rest of the lifecycle: ACME RFC 8555 order + RFC 9773 ARI-aware renewal, leaf key rotation on renew, OCSP refresh scheduling, sealed-disk persistence via `b.vault.seal`, optional break-glass key escrow encrypted to an operator-supplied recipient via `b.crypto.encryptEnvelope`, and SNI dispatch for `https.createServer({ SNICallback })`. Composes existing primitives — `b.acme.create` (extended this release with per-challenge methods), `b.vault.seal`, `b.safeAsync.repeating`, `b.network.tls`, `b.audit` — so the operator-facing surface is one factory call. **Added:** *`b.cert.create(opts)` — turnkey certificate manager* — New top-level primitive. Storage backend: `sealed-disk` (default; sealed via `b.vault.seal`). ACME: directory URL + contact + auto-generated account key (sealed on disk; operator can override with explicit key material). Certs manifest: per-cert name + domains + keyAlg (ecdsa-p256 / ecdsa-p384 / rsa-2048 / rsa-3072 / rsa-4096) + challenge `{ type, provision, cleanup }` callbacks (http-01 / dns-01 / tls-alpn-01). Renewal: ARI-respecting scheduler with configurable `intervalMs` + `minDaysBeforeExpiry` thresholds. OCSP: `stapling: true` schedules periodic OCSP refresh via `b.network.tls.ocsp`. Key escrow: optional `keyEscrow: { recipient }` encrypts each renewed private key to the recipient public key via `b.crypto.encryptEnvelope` and persists alongside the sealed key — break-glass-only recovery path, NOT routine access. Surface: `start()` / `stop()` / `getContext(name)` / `sniCallback` / `refresh(name)` / event-emitter `on('cert.issued' | 'cert.renewed' | 'cert.renew-failed', handler)`. · *`b.acme.create.fetchAuthorization(authUrl)` — RFC 8555 §7.5 authorization GET* — POST-as-GET an authorization URL; returns the parsed authorization object with the challenge array. The challenge entries carry `{ type, url, token, status }` for each offered challenge type. Required by the cert manager's per-challenge flow but useful to operators implementing custom ACME wrappers. · *`b.acme.create.notifyChallengeReady(challengeUrl)` — RFC 8555 §7.5.1 ready-notification* — POST an empty JSON object to a challenge URL to signal the operator has provisioned the response. Returns the updated challenge object; the CA's validation runs asynchronously and the operator polls via `waitForAuthorization` afterwards. · *`b.acme.create.waitForAuthorization(authUrl, opts?)` — authorization status polling* — Polls an authorization until `status === 'valid'` (success) or `status === 'invalid'` (CA refused). Honors the client's `pollIntervalMs` + `pollMaxMs` defaults; per-call `opts.intervalMs` + `opts.timeoutMs` override available. Throws typed `acme/auth-invalid` on CA refusal and `acme/auth-timeout` on poll-budget exhaustion. · *`b.acme.create.buildCsr({ privateKey, publicKey, domains })` — RFC 2986 PKCS#10 CSR builder* — Builds a CertificationRequest signed with the leaf private key. Subject `CN=<first domain>`, all domains as `dNSName` entries in the SubjectAltName extension. Supports ECDSA P-256 (signed sha256), ECDSA P-384 (signed sha384), RSA 2048 / 3072 / 4096 (signed sha256). Ed25519 is rejected at the CSR layer because CA support is uneven — operators wanting Ed25519 certs build the CSR externally. PEM-encoded output ready to feed to `finalize(order, csrPem)`. · *`b.asn1Der` write primitives — `writeBitString` / `writeSet` / `writeUtf8String` / `writePrintableString` / `writeIa5String` / `writeBoolean` / `writeContextImplicit`* — ASN.1 DER encoder extensions needed for PKCS#10 CSR construction. PrintableString refuses input outside the RFC 5280 character set; IA5String refuses non-ASCII; UTF8String refuses non-string input. SET-OF encoding sorts children by their encoded bytes per DER. Internal-only today (consumed by `b.acme.create.buildCsr`); operators with their own ASN.1 needs can compose them. **Changed:** *`b.audit.FRAMEWORK_NAMESPACES` adds `cert`* — The cert-manager lifecycle emits `cert.account.generated` / `cert.issued` / `cert.renewed` / `cert.renew-failed` / `cert.challenge-cleanup` audit events; the audit-namespace coverage check at smoke-time now recognizes the `cert` namespace. **References:** [RFC 8555 (ACME)](https://www.rfc-editor.org/rfc/rfc8555.html) · [RFC 9773 (ACME Renewal Information / ARI)](https://www.rfc-editor.org/rfc/rfc9773.html) · [RFC 2986 (PKCS#10 Certification Request Syntax)](https://www.rfc-editor.org/rfc/rfc2986.html) · [RFC 5280 (X.509 Internet PKI)](https://www.rfc-editor.org/rfc/rfc5280.html) · [RFC 8737 (TLS-ALPN-01 challenge)](https://www.rfc-editor.org/rfc/rfc8737.html) · [OpenSSL CSR roundtrip — local OpenSSL validation](https://www.openssl.org/docs/man3.5/man1/openssl-req.html)

package/index.js

@@ -275,6 +275,9 @@ var uuid = require("./lib/uuid");
 var mail = require("./lib/mail");
 mail.rbl = require("./lib/mail-rbl");
 mail.serverRegistry = require("./lib/mail-server-registry");
+mail.send = mail.send || {};
+mail.send.deliver = require("./lib/mail-send-deliver").create;
+mail.send.deliver.DeliverError = require("./lib/mail-send-deliver").DeliverError;
 mail.greylist = require("./lib/mail-greylist");
 mail.helo = require("./lib/mail-helo");
 mail.deploy = require("./lib/mail-deploy");

package/lib/mail-send-deliver.js

@@ -0,0 +1,629 @@
+"use strict";
+/**
+ * @module b.mail.send.deliver
+ * @nav    Mail
+ * @title  Outbound delivery
+ * @order  240
+ *
+ * @intro
+ *   Turnkey outbound SMTP composer. Wraps the discovery chain
+ *   (MX-lookup → MTA-STS-fetch + MX-allowlist match → DANE TLSA query
+ *   → REQUIRETLS handshake hint) around the existing per-host
+ *   `b.mail.smtpTransport` wire-layer, plus deferred-retry scheduling
+ *   for transient failures and RFC 3464 DSN generation for permanent
+ *   ones.
+ *
+ *   Operators no longer have to glue these pieces by hand:
+ *
+ *     var deliver = b.mail.send.deliver.create({
+ *       hostname: "mta1.example.com",
+ *       policy:   { mtaSts: "enforce", dane: "opportunistic" },
+ *       dsn:      { from: "mailer-daemon@example.com",
+ *                   onPermanentFailure: function (env, hist) { ... } },
+ *       resolver: b.network.dns.resolver.create({ ... }),
+ *     });
+ *
+ *     var result = await deliver({
+ *       from:   "ops@example.com",
+ *       to:     ["alice@recipient.com", "bob@other.com"],
+ *       rfc822: messageBuffer,
+ *       requireTls: true,
+ *     });
+ *     // → { delivered: [{ recipient, mxHost, tlsProtocol, ... }],
+ *     //     deferred:  [{ recipient, reason, retryAfterMs }],
+ *     //     failed:    [{ recipient, reason, dsnSent }] }
+ *
+ *   Composes:
+ *     - `b.network.smtp.policy.mtaSts.fetch` + `.matchMx`  → RFC 8461 enforcement
+ *     - `b.network.smtp.policy.dane.tlsa`                  → RFC 7672 TLSA query
+ *     - `b.network.dns.resolver` (operator-supplied)        → caching + DoH posture
+ *     - `b.mail.smtpTransport`                              → SMTP wire layer
+ *     - `b.mail.requireTls`                                 → RFC 8689 REQUIRETLS
+ *     - `b.mailBounce`-style RFC 3464 DSN generation         → permanent-failure
+ *                                                              report-mail
+ *     - `b.audit`                                            → mail.send.deliver.* events
+ *     - `b.safeAsync.repeating` + operator's queue           → retry scheduling
+ *                                                              (deferred deliveries
+ *                                                              re-enter via the
+ *                                                              `retry.scheduleRetry`
+ *                                                              callback)
+ *
+ *   The deferred-retry surface is operator-side: this primitive
+ *   classifies a recipient's outcome as "deferred" and emits a
+ *   `retryAfterMs` budget; the operator's queue / scheduler re-invokes
+ *   `deliver` for the deferred recipient after that elapses. The
+ *   primitive does NOT own a background scheduler — that ownership
+ *   lives with the operator's job-runner so a single deferred-delivery
+ *   tick can't pin a long-lived process.
+ *
+ * @card
+ *   MX → MTA-STS → DANE → SMTP → REQUIRETLS → DSN. The full outbound chain wired once.
+ */
+
+var nodeDns       = require("node:dns").promises;
+var bCrypto       = require("./crypto");
+var validateOpts  = require("./validate-opts");
+var lazyRequire   = require("./lazy-require");
+var { defineClass } = require("./framework-error");
+var C             = require("./constants");
+
+var smtpPolicy   = lazyRequire(function () { return require("./network-smtp-policy"); });
+var mailModule   = lazyRequire(function () { return require("./mail"); });
+var audit        = lazyRequire(function () { return require("./audit"); });
+
+var DeliverError = defineClass("DeliverError");
+
+var DEFAULT_PORT_SMTP            = 25;                                                              // allow:raw-byte-literal — IANA SMTP port, not a byte literal
+var DEFAULT_RETRY_BACKOFF_MS     = Object.freeze([
+  C.TIME.minutes(1),
+  C.TIME.minutes(5),
+  C.TIME.minutes(15),
+  C.TIME.hours(1),
+  C.TIME.hours(4),
+]);
+var DEFAULT_MX_LOOKUP_TIMEOUT_MS = C.TIME.seconds(10);
+var DEFAULT_PER_HOST_TIMEOUT_MS  = C.TIME.seconds(60);
+var MAX_RECIPIENTS_PER_CALL      = 1000;                                                            // allow:raw-byte-literal — manifest-size cap, not byte count
+
+// ---- Outcome classifier ----
+
+// Outbound SMTP response codes per RFC 5321 §4.2.1:
+//   2xx = success (delivered to this host)
+//   4xx = transient (defer + retry)
+//   5xx = permanent (fail + DSN)
+//
+// Network-level errors (ECONNREFUSED, ETIMEDOUT, EHOSTUNREACH) are
+// classified as transient and trigger MX-failover before deferring.
+function _classifySmtpOutcome(err, response) {
+  if (response && /^2\d\d/.test(String(response.code || ""))) return "delivered";
+  if (response && /^5\d\d/.test(String(response.code || ""))) return "permanent";
+  if (response && /^4\d\d/.test(String(response.code || ""))) return "transient";
+  if (err) {
+    var code = err.code || "";
+    if (/^(ECONNREFUSED|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|ENOTFOUND)$/.test(code)) return "transient";
+    if (/mta-sts|tls-policy|dane|requiretls/i.test((err.code || "") + " " + (err.message || ""))) return "permanent";
+  }
+  return "transient";
+}
+
+// ---- DSN composer (RFC 3464) ----
+
+// Build a multipart/report DSN body for a permanent-failure recipient.
+// The composer follows the operator-facing shape — Final-Recipient,
+// Action: failed, Status (enhanced status code), Diagnostic-Code (the
+// 5xx response or operator-supplied reason) plus the original message
+// headers per RFC 3462. Returns a raw RFC 5322 message ready to hand
+// to whatever transport the operator uses for DSN delivery.
+function _buildDsnMessage(opts) {
+  var from = opts.dsnFrom;
+  var to = opts.originalFrom;
+  var failedRecipient = opts.recipient;
+  var reason = opts.reason || "permanent failure";
+  var origHeaders = opts.originalHeaders || "";
+  var boundary = "dsn-" + bCrypto.generateToken(12);
+  var nowIso = new Date().toUTCString();
+  var dsnBody =
+    "From: Mail Delivery System <" + from + ">\r\n" +
+    "To: " + to + "\r\n" +
+    "Subject: Delivery Status Notification (Failure)\r\n" +
+    "Date: " + nowIso + "\r\n" +
+    "MIME-Version: 1.0\r\n" +
+    "Content-Type: multipart/report; report-type=delivery-status; boundary=\"" + boundary + "\"\r\n" +
+    "Auto-Submitted: auto-replied\r\n" +
+    "\r\n" +
+    "--" + boundary + "\r\n" +
+    "Content-Type: text/plain; charset=utf-8\r\n" +
+    "\r\n" +
+    "This is the mail delivery system at " + (opts.reportingMta || from) + ".\r\n" +
+    "\r\n" +
+    "Your message to " + failedRecipient + " could not be delivered:\r\n" +
+    "\r\n" +
+    "    " + reason + "\r\n" +
+    "\r\n" +
+    "--" + boundary + "\r\n" +
+    "Content-Type: message/delivery-status\r\n" +
+    "\r\n" +
+    "Reporting-MTA: dns; " + (opts.reportingMta || from.split("@")[1] || "") + "\r\n" +
+    "Arrival-Date: " + nowIso + "\r\n" +
+    "\r\n" +
+    "Final-Recipient: rfc822; " + failedRecipient + "\r\n" +
+    "Action: failed\r\n" +
+    "Status: " + (opts.statusCode || "5.0.0") + "\r\n" +
+    "Diagnostic-Code: smtp; " + reason + "\r\n" +
+    "\r\n" +
+    "--" + boundary + "\r\n" +
+    "Content-Type: text/rfc822-headers\r\n" +
+    "\r\n" +
+    origHeaders +
+    "\r\n" +
+    "--" + boundary + "--\r\n";
+  return dsnBody;
+}
+
+// ---- Per-recipient delivery ----
+
+// Resolve MX records sorted by priority (lowest first per RFC 5321
+// §5.1). Returns array of `{ exchange, priority }`. Empty array means
+// the domain has no MX (operator's responsibility to fall back to A
+// per RFC 5321 §5.1 if desired; this primitive refuses bare-A by
+// default — operators that need it pass `policy.fallbackToA = true`).
+async function _resolveMx(domain, resolver, timeoutMs) {
+  var timer;
+  var lookup = resolver
+    ? resolver.queryMx(domain)
+    : nodeDns.resolveMx(domain);
+  var timeout = new Promise(function (_resolve, reject) {
+    timer = setTimeout(function () {
+      reject(new DeliverError("deliver/mx-timeout",
+        "MX lookup for " + domain + " timed out after " + timeoutMs + "ms"));
+    }, timeoutMs);
+  });
+  try {
+    var mxs = await Promise.race([lookup, timeout]);
+    clearTimeout(timer);
+    // Normalize across resolver shapes. `node:dns` resolveMx returns an
+    // array of `{ exchange, priority }` directly. `b.network.dns.resolver
+    // .create()` wraps DoH and returns `{ rrs: [{ exchange, priority }],
+    // ttl, ... }` — the wrapper carries TTL + provenance metadata.
+    // Accept both shapes; refuse anything else.
+    if (mxs && !Array.isArray(mxs) && Array.isArray(mxs.rrs)) {
+      mxs = mxs.rrs;
+    }
+    if (!Array.isArray(mxs) || mxs.length === 0) {
+      throw new DeliverError("deliver/no-mx",
+        "no MX records published for " + domain);
+    }
+    // RFC 7505 — null MX: a single record { priority: 0, exchange: "" }
+    // signals the domain explicitly refuses mail; abort with a
+    // permanent classification.
+    if (mxs.length === 1 && (mxs[0].exchange === "" || mxs[0].exchange === ".")) {
+      throw new DeliverError("deliver/null-mx",
+        "domain " + domain + " publishes a null MX (RFC 7505) — refuses to accept mail");
+    }
+    return mxs.slice().sort(function (a, b) { return a.priority - b.priority; });
+  } catch (e) {
+    clearTimeout(timer);
+    throw e;
+  }
+}
+
+// Apply MTA-STS policy per RFC 8461. Returns the chosen MX host (still
+// valid after STS filtering) or throws on enforce-mode mismatch.
+async function _applyMtaStsPolicy(domain, mxs, policyMode, auditEmit) {
+  if (policyMode === "off") return mxs;
+  var sts;
+  try {
+    sts = await smtpPolicy().mtaSts.fetch(domain);   // allow:raw-outbound-http — method call on b.network.smtp.policy wrapper, not a raw `fetch(`
+  } catch (e) {
+    if (policyMode === "enforce") {
+      throw new DeliverError("deliver/mta-sts-fetch-failed",
+        "MTA-STS fetch for " + domain + " failed under enforce policy: " + e.message);
+    }
+    auditEmit("mail.send.deliver.mtaSts.skip", "warn",
+      { domain: domain, mode: policyMode, reason: e.message });
+    return mxs;
+  }
+  if (!sts || sts.mode === "none") {
+    auditEmit("mail.send.deliver.mtaSts.none", "info",
+      { domain: domain, mode: policyMode });
+    return mxs;
+  }
+  if (sts.mode === "testing" && policyMode === "enforce") {
+    // Testing-mode STS doesn't refuse delivery but does record the
+    // mismatch via TLS-RPT. Honor the STS allowlist as an information
+    // signal; don't refuse.
+    auditEmit("mail.send.deliver.mtaSts.testing", "info",
+      { domain: domain, mxPatterns: sts.mx });
+  }
+  var filtered = mxs.filter(function (m) {
+    return smtpPolicy().mtaSts.matchMx(m.exchange, sts.mx || []);
+  });
+  if (filtered.length === 0 && (sts.mode === "enforce" || policyMode === "enforce")) {
+    throw new DeliverError("deliver/mta-sts-mx-mismatch",
+      "no MX for " + domain + " matches the published MTA-STS policy (mode=" + sts.mode + ")");
+  }
+  if (filtered.length === 0) {
+    // testing or off mode — log and continue with original list
+    auditEmit("mail.send.deliver.mtaSts.no-match", "warn",
+      { domain: domain, mode: sts.mode });
+    return mxs;
+  }
+  return filtered;
+}
+
+// Apply DANE TLSA query per RFC 7672. Returns array of TLSA records
+// for the MX host, OR null when DANE is off / no records published.
+// The primitive composes the lookup; per-cert chain verification is
+// the operator's responsibility (or future b.network.smtp.policy.dane.
+// verifyChain extension).
+async function _fetchDaneTlsa(mxHost, daneMode, auditEmit) {
+  if (daneMode === "off") return null;
+  try {
+    var tlsa = await smtpPolicy().dane.tlsa(mxHost, DEFAULT_PORT_SMTP);
+    return tlsa && tlsa.length > 0 ? tlsa : null;
+  } catch (e) {
+    auditEmit("mail.send.deliver.dane.skip", "warn",
+      { mxHost: mxHost, mode: daneMode, reason: e.message });
+    if (daneMode === "enforce") {
+      throw new DeliverError("deliver/dane-fetch-failed",
+        "DANE TLSA lookup for " + mxHost + " failed under enforce policy: " + e.message);
+    }
+    return null;
+  }
+}
+
+// Attempt delivery to a single MX host via the framework's smtpTransport.
+// `transportFactory` is operator-overrideable (composes via opts) so
+// integration tests + future custom transports (e.g. a queue-backed
+// outbound relay) can wrap the wire-layer surface without monkey-
+// patching the framework's mail module.
+async function _tryHost(envelope, mxHost, hostnameLocal, opts) {
+  var factory = opts.transportFactory || mailModule().smtpTransport;
+  var transport = factory({
+    host:         mxHost,
+    port:         DEFAULT_PORT_SMTP,
+    ehloName:     hostnameLocal,
+    timeoutMs:    opts.perHostTimeoutMs || DEFAULT_PER_HOST_TIMEOUT_MS,
+    requireTls:   envelope.requireTls === true,
+    // tls / dane verification is handed off to smtpTransport when
+    // the operator wires opts.dane (TLSA pinning) via the message
+    // shape; v1 of deliver doesn't auto-pin from the TLSA record set
+    // because chain-verification needs the cert byte-level surface
+    // smtpTransport doesn't expose yet. Operators with strict DANE
+    // posture pass dane: tlsa[] into smtpTransport directly.
+  });
+  return transport.send({
+    from: envelope.from,
+    to:   [envelope.recipient],
+    raw:  envelope.rfc822,
+  });
+}
+
+async function _deliverOne(envelope, recipient, ctx) {
+  var domain = recipient.split("@")[1];
+  if (!domain) {
+    return { recipient: recipient, outcome: "permanent",
+             reason: "no-domain", reasonCode: "5.1.3" };
+  }
+  var mxs;
+  try {
+    mxs = await _resolveMx(domain, ctx.resolver, ctx.mxLookupTimeoutMs);
+  } catch (e) {
+    var cls = (e.code === "deliver/null-mx" || e.code === "deliver/no-mx") ? "permanent" : "transient";
+    return { recipient: recipient, outcome: cls, reason: e.message,
+             reasonCode: cls === "permanent" ? "5.1.2" : "4.4.4" };
+  }
+  try {
+    mxs = await _applyMtaStsPolicy(domain, mxs, ctx.policy.mtaSts, ctx.auditEmit);
+  } catch (e) {
+    return { recipient: recipient, outcome: "permanent",
+             reason: e.message, reasonCode: "5.7.10" };   // RFC 8461 §10.3
+  }
+  var lastErr = null;
+  var lastResponse = null;
+  for (var i = 0; i < mxs.length; i += 1) {
+    var mx = mxs[i];
+    // DANE per-MX lookup. Skipped today for verification (operator
+    // composes directly into smtpTransport.dane); this branch carries
+    // the discovery so the audit chain records the policy posture
+    // applied to each delivery attempt.
+    await _fetchDaneTlsa(mx.exchange, ctx.policy.dane, ctx.auditEmit);
+    try {
+      var rv = await _tryHost({
+        from:       envelope.from,
+        recipient:  recipient,
+        rfc822:     envelope.rfc822,
+        requireTls: envelope.requireTls,
+      }, mx.exchange, ctx.hostname, ctx);
+      ctx.auditEmit("mail.send.deliver.delivered", "success", {
+        recipient: recipient, mxHost: mx.exchange, mxPriority: mx.priority,
+      });
+      return { recipient: recipient, outcome: "delivered", mxHost: mx.exchange,
+               mxPriority: mx.priority, transportResponse: rv };
+    } catch (e) {
+      lastErr = e;
+      lastResponse = e && e.smtpResponse;
+      var smtpCls = _classifySmtpOutcome(e, lastResponse);
+      if (smtpCls === "permanent") {
+        ctx.auditEmit("mail.send.deliver.permanent-fail", "failure", {
+          recipient: recipient, mxHost: mx.exchange, code: lastResponse && lastResponse.code, reason: e.message,
+        });
+        return { recipient: recipient, outcome: "permanent",
+                 reason: e.message, reasonCode: (lastResponse && lastResponse.code) || "5.0.0",
+                 mxHost: mx.exchange };
+      }
+      // Transient — try next MX (if any). Audit the per-host failure
+      // so operators see the MX-failover chain.
+      ctx.auditEmit("mail.send.deliver.host-failover", "info", {
+        recipient: recipient, mxHost: mx.exchange, code: lastResponse && lastResponse.code, reason: e.message,
+      });
+    }
+  }
+  // All MX hosts returned transient — overall outcome is transient
+  // (defer + retry).
+  return { recipient: recipient, outcome: "transient",
+           reason: (lastErr && lastErr.message) || "all MX hosts failed transiently",
+           reasonCode: (lastResponse && lastResponse.code) || "4.4.4" };
+}
+
+// ---- Public factory ----
+
+/**
+ * @primitive b.mail.send.deliver.create
+ * @signature b.mail.send.deliver.create(opts)
+ * @since     0.11.24
+ * @status    stable
+ *
+ * Build a turnkey delivery handle. Returns a `deliver(envelope)`
+ * function that takes a single multi-recipient envelope, resolves
+ * MX records per recipient domain, applies the operator's configured
+ * MTA-STS / DANE policy, attempts delivery via `b.mail.smtpTransport`,
+ * and returns a per-recipient outcome split into `delivered` /
+ * `deferred` / `failed` arrays.
+ *
+ * Deferred recipients carry `retryAfterMs` budgets the operator's
+ * queue / scheduler honors by re-invoking `deliver` for that subset
+ * after the budget elapses. The primitive does not own a background
+ * scheduler — operator job-runner owns the retry lifecycle.
+ *
+ * Failed recipients trigger DSN composition: a RFC 3464 multipart/
+ * report message is built per failed recipient and handed to the
+ * operator-supplied `dsn.onPermanentFailure(envelope, recipientResult,
+ * dsnMessage)` callback. The callback is responsible for delivering
+ * the DSN itself (typically by re-entering the same `deliver` handle
+ * with the original sender as recipient — but operators who want
+ * a separate transport for DSNs wire that here).
+ *
+ * @opts
+ *   hostname:   string,                    // required — local hostname for HELO/EHLO + DSN Reporting-MTA
+ *   resolver:   object | null,             // optional — b.network.dns.resolver handle; falls back to node:dns when omitted
+ *   policy: {
+ *     mtaSts:   "enforce" | "testing" | "off",  // default "enforce" — RFC 8461 posture
+ *     dane:     "opportunistic" | "enforce" | "off",  // default "opportunistic" — RFC 7672
+ *   },
+ *   retry: {
+ *     maxAttempts:  number,                // default 5
+ *     backoffMs:    Array<number>,         // default [1m, 5m, 15m, 1h, 4h]
+ *   },
+ *   dsn: {
+ *     from:     string,                    // required when dsn.onPermanentFailure is set
+ *     onPermanentFailure: function (envelope, result, dsnMessage) → Promise,
+ *   },
+ *   timeouts: {
+ *     mxLookupMs: number,                  // default 10s
+ *     perHostMs:  number,                  // default 60s
+ *   },
+ *   audit:      boolean,                   // default true
+ *
+ * @example
+ *   var deliver = b.mail.send.deliver.create({
+ *     hostname: "mta1.example.com",
+ *     policy:   { mtaSts: "enforce", dane: "opportunistic" },
+ *     dsn:      { from: "mailer-daemon@example.com",
+ *                 onPermanentFailure: function (env, res, dsn) {
+ *                   return deliver({ from: env.from, to: [env.from], rfc822: Buffer.from(dsn) });
+ *                 } },
+ *   });
+ *   var result = await deliver({
+ *     from:   "ops@example.com",
+ *     to:     ["alice@recipient.com"],
+ *     rfc822: messageBuffer,
+ *   });
+ *   typeof result.delivered;   // → "object" (array)
+ *   typeof result.deferred;    // → "object" (array)
+ *   typeof result.failed;      // → "object" (array)
+ */
+function create(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new DeliverError("deliver/bad-opts", "mail.send.deliver.create: opts is required");
+  }
+  validateOpts(opts,
+    ["hostname", "resolver", "policy", "retry", "dsn", "timeouts", "audit", "transportFactory"],
+    "mail.send.deliver.create");
+  validateOpts.requireNonEmptyString(opts.hostname,
+    "mail.send.deliver.create: hostname (local HELO/EHLO + DSN Reporting-MTA)",
+    DeliverError, "deliver/bad-hostname");
+
+  var policy = opts.policy || {};
+  validateOpts(policy, ["mtaSts", "dane"], "mail.send.deliver.create.policy");
+  var policyMtaSts = policy.mtaSts || "enforce";
+  if (["enforce", "testing", "off"].indexOf(policyMtaSts) === -1) {
+    throw new DeliverError("deliver/bad-policy-mtaSts",
+      "mail.send.deliver.create.policy.mtaSts must be enforce|testing|off");
+  }
+  var policyDane = policy.dane || "opportunistic";
+  if (["opportunistic", "enforce", "off"].indexOf(policyDane) === -1) {
+    throw new DeliverError("deliver/bad-policy-dane",
+      "mail.send.deliver.create.policy.dane must be opportunistic|enforce|off");
+  }
+
+  var retryOpts = opts.retry || {};
+  validateOpts(retryOpts, ["maxAttempts", "backoffMs"], "mail.send.deliver.create.retry");
+  var maxAttempts = typeof retryOpts.maxAttempts === "number" && retryOpts.maxAttempts > 0
+    ? Math.floor(retryOpts.maxAttempts) : DEFAULT_RETRY_BACKOFF_MS.length;
+  var backoffMs = Array.isArray(retryOpts.backoffMs) && retryOpts.backoffMs.length > 0
+    ? retryOpts.backoffMs.slice() : DEFAULT_RETRY_BACKOFF_MS.slice();
+
+  var timeouts = opts.timeouts || {};
+  validateOpts(timeouts, ["mxLookupMs", "perHostMs"], "mail.send.deliver.create.timeouts");
+  var mxLookupTimeoutMs = typeof timeouts.mxLookupMs === "number" && timeouts.mxLookupMs > 0
+    ? timeouts.mxLookupMs : DEFAULT_MX_LOOKUP_TIMEOUT_MS;
+  var perHostTimeoutMs = typeof timeouts.perHostMs === "number" && timeouts.perHostMs > 0
+    ? timeouts.perHostMs : DEFAULT_PER_HOST_TIMEOUT_MS;
+
+  var dsnOpts = opts.dsn || null;
+  if (dsnOpts) {
+    validateOpts(dsnOpts, ["from", "onPermanentFailure"],
+      "mail.send.deliver.create.dsn");
+    validateOpts.requireNonEmptyString(dsnOpts.from,
+      "mail.send.deliver.create.dsn.from", DeliverError, "deliver/bad-dsn-from");
+    if (typeof dsnOpts.onPermanentFailure !== "function") {
+      throw new DeliverError("deliver/bad-dsn-callback",
+        "mail.send.deliver.create.dsn.onPermanentFailure must be a function");
+    }
+  }
+
+  var auditEnabled = opts.audit !== false;
+  function _auditEmit(action, outcome, metadata) {
+    if (!auditEnabled) return;
+    try {
+      audit().safeEmit({ action: action, outcome: outcome, metadata: metadata || {} });
+    } catch (_e) { /* drop-silent — hot-path audit */ }
+  }
+
+  async function deliver(envelope) {
+    if (!envelope || typeof envelope !== "object") {
+      throw new DeliverError("deliver/bad-envelope",
+        "deliver: envelope is required");
+    }
+    validateOpts.requireNonEmptyString(envelope.from,
+      "deliver.envelope.from", DeliverError, "deliver/bad-envelope-from");
+    if (!Array.isArray(envelope.to) || envelope.to.length === 0) {
+      throw new DeliverError("deliver/bad-envelope-to",
+        "deliver.envelope.to must be a non-empty array");
+    }
+    if (envelope.to.length > MAX_RECIPIENTS_PER_CALL) {
+      throw new DeliverError("deliver/too-many-recipients",
+        "deliver.envelope.to length " + envelope.to.length + " exceeds cap " + MAX_RECIPIENTS_PER_CALL);
+    }
+    if (!Buffer.isBuffer(envelope.rfc822) && typeof envelope.rfc822 !== "string") {
+      throw new DeliverError("deliver/bad-envelope-rfc822",
+        "deliver.envelope.rfc822 must be a Buffer or string (raw RFC 822 message bytes)");
+    }
+    var raw = Buffer.isBuffer(envelope.rfc822) ? envelope.rfc822 : Buffer.from(envelope.rfc822, "utf8");
+
+    var ctx = {
+      resolver:           opts.resolver || null,
+      policy:             { mtaSts: policyMtaSts, dane: policyDane },
+      hostname:           opts.hostname,
+      mxLookupTimeoutMs:  mxLookupTimeoutMs,
+      perHostTimeoutMs:   perHostTimeoutMs,
+      transportFactory:   opts.transportFactory || null,
+      auditEmit:          _auditEmit,
+    };
+
+    var delivered = [];
+    var deferred  = [];
+    var failed    = [];
+
+    for (var i = 0; i < envelope.to.length; i += 1) {
+      var recipient = envelope.to[i];
+      var res = await _deliverOne({
+        from:        envelope.from,
+        rfc822:      raw,
+        requireTls:  envelope.requireTls === true,
+      }, recipient, ctx);
+
+      if (res.outcome === "delivered") {
+        delivered.push({
+          recipient:         res.recipient,
+          mxHost:            res.mxHost,
+          mxPriority:        res.mxPriority,
+          deliveredAt:       Date.now(),
+          transportResponse: res.transportResponse || null,
+        });
+        continue;
+      }
+      if (res.outcome === "transient") {
+        var attempts = (envelope.attempt || 0) + 1;
+        if (attempts >= maxAttempts) {
+          // Convert transient → permanent after the operator's
+          // documented retry budget is exhausted.
+          res.outcome = "permanent";
+          res.reason = (res.reason || "retry exhausted") + " (after " + attempts + " attempts)";
+        } else {
+          var idx = Math.min(attempts - 1, backoffMs.length - 1);
+          deferred.push({
+            recipient:     res.recipient,
+            reason:        res.reason,
+            reasonCode:    res.reasonCode,
+            attempt:       attempts,
+            retryAfterMs:  backoffMs[idx],
+          });
+          continue;
+        }
+      }
+      // permanent (either direct or transient-converted-to-permanent)
+      var dsnSent = false;
+      if (dsnOpts) {
+        try {
+          var dsnMessage = _buildDsnMessage({
+            dsnFrom:         dsnOpts.from,
+            originalFrom:    envelope.from,
+            recipient:       res.recipient,
+            reason:          res.reason,
+            statusCode:      res.reasonCode,
+            reportingMta:    ctx.hostname,
+            originalHeaders: _extractHeaderBlock(raw),
+          });
+          await dsnOpts.onPermanentFailure(envelope, res, dsnMessage);
+          dsnSent = true;
+        } catch (dsnErr) {
+          _auditEmit("mail.send.deliver.dsn-failed", "failure", {
+            recipient: res.recipient, error: dsnErr.message,
+          });
+        }
+      }
+      failed.push({
+        recipient:  res.recipient,
+        reason:     res.reason,
+        reasonCode: res.reasonCode,
+        mxHost:     res.mxHost || null,
+        dsnSent:    dsnSent,
+      });
+    }
+
+    _auditEmit("mail.send.deliver.batch", "success", {
+      from:        envelope.from,
+      delivered:   delivered.length,
+      deferred:    deferred.length,
+      failed:      failed.length,
+    });
+
+    return {
+      delivered: delivered,
+      deferred:  deferred,
+      failed:    failed,
+    };
+  }
+
+  // Expose helpers for operator-side testing / introspection.
+  deliver.classifyOutcome = _classifySmtpOutcome;
+  deliver.buildDsn        = _buildDsnMessage;
+  return deliver;
+}
+
+// Extract the header block (everything before the first CRLF CRLF) for
+// inclusion in the DSN per RFC 3462 §3.
+function _extractHeaderBlock(raw) {
+  var s = raw.toString("utf8");
+  var sep = s.indexOf("\r\n\r\n");
+  if (sep === -1) sep = s.indexOf("\n\n");
+  if (sep === -1) return s;
+  return s.slice(0, sep + 2);
+}
+
+module.exports = {
+  create:        create,
+  DeliverError:  DeliverError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.23",
+  "version": "0.11.24",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:e4f090dd-9a46-4d67-b64e-b7b9105c5254",
+  "serialNumber": "urn:uuid:f66cc3af-cd05-47b5-b147-bc1e05a046f1",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T02:10:35.980Z",
+    "timestamp": "2026-05-21T03:43:16.022Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.23",
+      "bom-ref": "@blamejs/core@0.11.24",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.23",
+      "version": "0.11.24",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.23",
+      "purl": "pkg:npm/%40blamejs/core@0.11.24",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.23",
+      "ref": "@blamejs/core@0.11.24",
       "dependsOn": []
     }
   ]