@blamejs/core 0.13.11 → 0.13.13

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.13 (2026-05-27) — **Archive extraction-path verification now refuses Windows reserved names, NTFS data streams, and trailing-dot/space per segment.** b.guardFilename.verifyExtractionPath (the per-entry gate b.archive.read.zip.extract / b.safeArchive run on every extracted file) checked traversal, absolute paths, drive-letter and UNC prefixes, null bytes, PATH_MAX overflow, and realpath containment — but not the per-segment Windows write-target hazards the disk validate / sanitize paths already reject. An archive entry named CON, NUL.txt, subdir/LPT1, file.txt:hidden, or secret.txt. stayed inside the extraction root, so the containment and realpath checks passed it, yet on Windows it would resolve to a device, write a hidden NTFS stream, or (after Windows strips the trailing dot/space) overwrite a sibling file. These are now refused: any path segment that collides with a Windows reserved device name, uses NTFS alternate-data-stream syntax (name:stream), or carries a trailing dot or leading/trailing whitespace. The checks are platform-unconditional — a verifier running on Linux still refuses names that are only dangerous on the Windows host that ultimately extracts the archive — with a per-check opt-out (reservedNamePolicy / adsPolicy / leadingTrailingPolicy: "allow") for Linux-only targets. **Security:** *`verifyExtractionPath` refuses per-segment Windows extraction hazards (reserved names / NTFS ADS / trailing dot-space)* — Closes a within-root write-target-redirection gap: an extracted entry could stay inside the destination yet, on Windows, resolve to a device (`CON` / `NUL` / `COM1` / `LPT1`), write a hidden alternate data stream (`file.txt:payload`), or overwrite a sibling after Windows strips a trailing dot/space (`config.`). The verification gate now rejects all three per path segment. Refusal is platform-unconditional (the verifier may run on a different OS than the extractor); set `reservedNamePolicy` / `adsPolicy` / `leadingTrailingPolicy` to `"allow"` to opt a check out on a Linux-only target. Single-entry, name-only residuals — 8.3 short-name aliasing, case-insensitive cross-entry collisions, and archive symlink/hardlink entry-target validation — remain the extract orchestrator's responsibility (it owns the case-folded seen-set and the link-target gate).
+
+- v0.13.12 (2026-05-27) — **Inbound MX listener now runs the connection-level gate cascade it documented — HELO identity, DNS blocklist, and greylisting.** b.mail.server.mx.create documented helo / rbl / greylist gate options, but the listener never invoked them — an operator who wired them got silent acceptance of mail those gates would have rejected. They are now wired into the live SMTP state machine: the HELO-identity gate evaluates at HELO/EHLO and refuses a spoofed or malformed identity with 550; the DNS-blocklist gate evaluates the connecting IP once per connection and refuses a listed source with 554; the greylisting gate defers a first-seen (ip, sender, recipient) tuple with a 450 tempfail so legitimate senders retry and pass. Each gate is skipped when the operator doesn't wire it. Because these gates do DNS and store lookups, the per-connection command pump was reworked to process commands asynchronously and strictly in arrival order, so pipelined commands (RFC 2920) cannot overtake a gate still resolving and the existing SMTP-smuggling and STARTTLS-stripping defenses are unchanged. The message-authentication gate (SPF/DKIM/DMARC alignment via b.guardEnvelope) needs the inbound SPF + DKIM verification results as inputs; that inbound-auth pipeline lands as a follow-up, and the documentation no longer implies that gate is active today. **Added:** *HELO-identity / RBL / greylist gates wired into `b.mail.server.mx`* — When wired, `opts.helo` (FCrDNS / HELO-shape / self-name checks) refuses a bad HELO identity at HELO/EHLO with 550; `opts.rbl` refuses a connecting IP found on a DNS blocklist with 554 (evaluated once per connection); `opts.greylist` defers a first-seen (ip, sender, recipient) tuple with 450 4.7.1. Their verdicts surface on the `rcpt_to` event (`rblListed`, `greylist`) and the `helo` event (`heloVerdict`), with dedicated `helo_gate_refused` / `rbl_refused` / `greylist_deferred` audit events. A gate the operator doesn't supply is skipped, never synthesized. **Changed:** *MX command pump processes commands asynchronously and in arrival order* — Gate evaluation involves DNS and store lookups, so the per-connection command pump now awaits each command before the next. Pipelined commands are serialized so a gate resolving cannot let a later command answer ahead of an earlier one; reply ordering, the bare-LF SMTP-smuggling refusal, and the STARTTLS-stripping defense are unchanged. No change to the listener's external behaviour when no gates are wired. **Deprecated:** *SPF/DKIM/DMARC-alignment gate documentation corrected to match what is active* — The `envelope` (SPF/DKIM/DMARC alignment) and `dmarc` gate options were documented as wireable but require inbound SPF + DKIM verification results the listener does not yet produce. They are removed from the documented option set until the inbound-authentication pipeline (composing `b.mail.spf` + `b.mail.dmarc` + DKIM verification) lands; run those checks on the delivered message via the agent handoff in the meantime.
+
 - v0.13.11 (2026-05-27) — **Test-suite reliability: replaced fixed-delay waits in the rate-limiter and scheduler suites with condition polling.** No runtime behaviour changes. The rate-limiter, scheduler, and websocket-channel test suites waited for asynchronous work to settle by draining a fixed number of event-loop ticks before asserting. Under heavily parallel CI that budget was occasionally too short, so an assertion read state before the async work (a cluster-backend counter update, a scheduler tick-claim) had landed — an intermittent failure unrelated to the code under test. Those waits now poll the observable condition (helpers.waitUntil) and exit as soon as it holds, with a generous upper bound, so they pass quickly on fast machines and reliably under load. A build gate is added so the fixed-tick-drain shape cannot be reintroduced. **Fixed:** *Flaky fixed-budget waits in the rate-limiter / scheduler / sandbox test suites made contention-tolerant* — The rate-limit-cluster and scheduler-exactly-once suites drained a fixed count of event-loop ticks before asserting on asynchronously-updated state; under contended CI the budget could expire before the work settled, producing intermittent failures. They now wait on the actual observable condition (a written response, a settled counter). The sandbox suite's success-path cases gave the worker a 5 s execution budget that cold worker-thread startup under heavily parallel Windows CI could just exceed; those are raised to the framework's 10 s ceiling. Affects test code only — no change to shipped framework behaviour. The unused tick-drain helper in the websocket-channel suite was removed. **Detectors:** *Build gate rejects the fixed-tick-drain wait shape in tests* — A new test-suite lint rule flags the counted microtask/tick-drain idiom (reassigning a promise to its own `.then()` in a loop to wait a fixed number of ticks), the sibling of the existing fixed-`setTimeout`-sleep rule. A single event-loop yield is unaffected; only the drain-as-wait shape is rejected, directing the wait to condition polling instead.
 
 - v0.13.10 (2026-05-27) — **Documented-but-inert options wired up, a non-existent CVE reference removed, and a silent iCalendar cap-bypass fixed.** A sweep for places where a documented option or citation did not match what the code does. The most operator-relevant fix: b.calendar.fromIcal documented a safeIcalOpts option that forwards parser caps (byte size, RRULE limits, nesting depth) to b.safeIcal.parse, but the value was never forwarded — so an operator who set tight caps through it got the default profile instead, silently. That is corrected; the nested options now reach the parser. b.archive.read.zip documented an AbortSignal option that was never honored; it now aborts the read at the entry boundary. b.auth.fal documented a bearerOnly alias that had no effect; it now forces the no-proof-of-possession path and refuses the contradictory combination of bearerOnly:true with a holder-of-key binding. Separately, the auth verification paths cited CVE-2026-23993 (13 places) for the "reject an unknown alg before key lookup" guard — that CVE id does not exist (the registry has no record of it); the citation is replaced with the weakness class (CWE-347 / CWE-757) and the real, verifiable neighboring CVEs. The circuit-breaker error-code note that promised a rename "in v0.10" is corrected to the actual plan (v1.0), and the build gate that catches overdue version promises now also catches two-part version numbers. **Changed:** *`b.auth.fal` `bearerOnly` is now a real alias and refuses contradictions* — `bearerOnly: true` now forces the no-proof-of-possession path (equivalent to `hokBinding: null`), as documented. Passing `bearerOnly: true` together with a non-null `hokBinding` is a contradictory assurance request and is now refused at the call rather than silently resolved one way. **Fixed:** *`b.calendar.fromIcal` now forwards `safeIcalOpts` to the parser* — The documented `safeIcalOpts` option (parser caps: max bytes, RRULE COUNT/BYxxx limits, nesting depth) was not being passed to `b.safeIcal.parse` — when supplied under the documented nested key it was silently ignored and the parser ran with its default profile. Both forms now reach the parser: the documented nested `{ safeIcalOpts: { ... } }` and the top-level `{ profile, ... }` that earlier releases accepted, with the nested form winning on conflict. No caller regresses. · *`b.archive.read.zip` honors the documented `signal` (AbortSignal)* — The `signal` option was documented but never read. A large or slow archive read can now be aborted cooperatively — the reader checks the signal at each entry boundary (`inspect`, `entries`, `extractEntries`, `extract`) and rejects with an `archive-read/aborted` error. · *Removed a non-existent CVE reference from the JWT/JWE verification paths* — The "reject an unknown/unsupported `alg` before any key lookup" guard in `b.auth.jwt.verifyExternal`, `b.auth.oauth.verifyIdToken`, `b.auth.oid4vci`, and `b.auth.sd-jwt-vc` cited a CVE id that the registry has no record of. The behaviour is unchanged; the citation is now the weakness class it defends (CWE-347 improper signature verification / CWE-757 algorithm downgrade) alongside the real, verifiable alg-confusion / JWE-bypass CVEs already cited beside it. **Detectors:** *Overdue-version-promise gate now catches two-part version numbers* — The build gate that flags a deferral whose promised landing version has already shipped previously matched only three-part versions (`vN.N.N`); a two-part promise (`vN.N`) slipped past it. It now matches both. The `b.circuitBreaker` `CIRCUIT_OPEN` error-code note that pointed at a passed version is corrected to its actual plan (rename at v1.0, with a deprecation warning a minor ahead).

package/README.md

@@ -169,7 +169,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Mail (outbound)** — multipart + attachments + DKIM + calendar invites; bounce intake (`b.mail`, `b.mailBounce`)
 - **Mail (outbound delivery)** — turnkey MX-lookup → MTA-STS-fetch → DANE-TLSA → REQUIRETLS handshake → SMTP wire layer → RFC 3464 DSN-on-permanent-failure → deferred-retry scheduling, all wired once (`b.mail.send.deliver`)
 - **Mail (inbound auth)** — SPF / DMARC / ARC verify + ARC chain signing for relays (`b.mail.spf`, `b.mail.dmarc`, `b.mail.arc`)
-- **Mail server listeners** — RFC 5321 MX inbound (`b.mail.server.mx`), RFC 6409 submission with SASL + identity-binding (`b.mail.server.submission`), RFC 9051 IMAP4rev2 with CONDSTORE / QRESYNC / NOTIFY / METADATA / CATENATE (`b.mail.server.imap`), RFC 8620 + RFC 8621 JMAP Core + Mail over HTTP/SSE/WebSocket (`b.mail.server.jmap`), POP3 (`b.mail.server.pop3`), ManageSieve (`b.mail.server.managesieve`)
+- **Mail server listeners** — RFC 5321 MX inbound with connection-level gate cascade (HELO identity / DNS blocklist / greylisting) (`b.mail.server.mx`), RFC 6409 submission with SASL + identity-binding (`b.mail.server.submission`), RFC 9051 IMAP4rev2 with CONDSTORE / QRESYNC / NOTIFY / METADATA / CATENATE (`b.mail.server.imap`), RFC 8620 + RFC 8621 JMAP Core + Mail over HTTP/SSE/WebSocket (`b.mail.server.jmap`), POP3 (`b.mail.server.pop3`), ManageSieve (`b.mail.server.managesieve`)
 - **JMAP EmailSubmission reference** — composes `b.mail.send.deliver` to land the RFC 8621 §7.5 surface end-to-end (`b.mail.server.jmap.emailSubmissionSetHandler`)
 - **Mail crypto** — PQC-first S/MIME via CMS (`b.mail.crypto.cms`) + OpenPGP encrypt/decrypt + WKD key discovery with IDN-homograph defense (`b.mail.crypto.pgp`)
 - **Mail-stack agent** — multi-threaded worker pool + queue dispatch + sealed mail-store backed by SQLite FTS5 (`b.mail.agent`, `b.mailStore`)

package/lib/guard-filename.js

@@ -91,6 +91,20 @@ var WIN_RESERVED_NAMES = Object.freeze([
   "CLOCK$", "CONFIG$",
 ]);
 
+// Windows folds the superscript digits U+00B9 / U+00B2 / U+00B3 to
+// 1 / 2 / 3 when matching COM/LPT device names, so a superscript-digit
+// form resolves to the same device. Built from numeric codepoints so
+// the source stays pure-ASCII (guard-family rule).
+var _SUPERSCRIPT_DIGIT_MAP = (function () {
+  var m = {};
+  m[String.fromCharCode(0xB9)] = "1";
+  m[String.fromCharCode(0xB2)] = "2";
+  m[String.fromCharCode(0xB3)] = "3";
+  return m;
+})();
+var _SUPERSCRIPT_DIGIT_RE = new RegExp("[" + String.fromCharCode(0xB9, 0xB2, 0xB3) + "]", "g"); // allow:dynamic-regex — superscript-digit codepoints from a numeric table
+
+
 // Path-traversal indicators (anchored matches on raw and percent-decoded
 // forms).
 var PATH_TRAVERSAL_RE = /(^|[/\\])\.\.($|[/\\])/;
@@ -243,7 +257,16 @@ function _normalizeNFC(s) {
 function _isWinReserved(name) {
   // Reserved-name check applies to the base (without extension) AND to
   // the entire leaf — both `CON` and `CON.txt` collide with the device.
-  var upper = name.toUpperCase();
+  // Windows normalizes the superscript digits U+00B9 / U+00B2 / U+00B3
+  // to 1 / 2 / 3 when matching COM/LPT device names, so those superscript
+  // forms resolve to the same devices as COM1 / LPT3; fold them to ASCII
+  // before comparison so the spoofed forms are caught too. (Source stays
+  // pure-ASCII per the guard-family rule — the codepoints are escaped.)
+  // Fold COM/LPT superscript-digit spoofs to ASCII before matching
+  // (Windows treats them as the device). See _SUPERSCRIPT_DIGIT_* below.
+  var upper = name.toUpperCase().replace(_SUPERSCRIPT_DIGIT_RE, function (ch) {
+    return _SUPERSCRIPT_DIGIT_MAP[ch] || ch;
+  });
   for (var i = 0; i < WIN_RESERVED_NAMES.length; i += 1) {
     var r = WIN_RESERVED_NAMES[i];
     if (upper === r) return true;
@@ -952,6 +975,29 @@ var PATH_MAX_BYTES = 4096;
  * resolved absolute path on success; throws `GuardFilenameError` on
  * any refusal.
  *
+ * Per-segment Windows-extraction hazards are refused too — these are
+ * within-root write-target redirections / collisions that the
+ * containment + realpath checks structurally cannot see, so they need
+ * a name-level check the disk `validate` / `sanitize` paths already
+ * carry: a Windows reserved device name (`CON` / `NUL` / `COM1` / …,
+ * which resolves to the device), NTFS alternate-data-stream syntax
+ * (`name:stream`, which writes a hidden stream of the base file), and a
+ * trailing dot / leading-or-trailing whitespace (`secret.txt.`, which
+ * Windows strips so the entry overwrites an existing sibling). The
+ * checks are platform-unconditional — the verifier may run on Linux
+ * while extraction happens on Windows — and each has an opt-out for
+ * Linux-only targets (`reservedNamePolicy` / `adsPolicy` /
+ * `leadingTrailingPolicy: "allow"`), mirroring `validate`.
+ *
+ * Out of this primitive's scope (single-entry, name-only): 8.3 short-name
+ * aliasing (`PROGRA~1`), case-insensitive cross-entry collision
+ * (`Readme.txt` vs `README.TXT` on a case-preserving FS), and archive
+ * symlink/hardlink ENTRY-target validation. The first two are cross-entry
+ * properties and the third needs the entry's declared link target, which
+ * this function never sees — they belong to the extract orchestrator
+ * (`b.archive.read.zip.extract` / `b.safeArchive`), which owns the
+ * case-folded seen-set and the link-target gate.
+ *
  * Companion to `b.guardArchive.checkExtractionPath` (the string-only
  * portable gate the guard-archive primitive keeps fs-free for use as
  * a posture cascade member). `verifyExtractionPath` deliberately
@@ -964,8 +1010,13 @@ var PATH_MAX_BYTES = 4096;
  * Operators rolling their own extract loop call it per entry.
  *
  * @opts
- *   followSymlinks:  boolean,       // default false — symlink in the
+ *   followSymlinks:       boolean,  // default false — symlink in the
  *                                   //   resolved path refuses unless set
+ *   reservedNamePolicy:   string,   // "allow" opts out of the Windows
+ *                                   //   reserved-device-name segment check
+ *   adsPolicy:            string,   // "allow" opts out of the NTFS-ADS check
+ *   leadingTrailingPolicy: string,  // "allow" opts out of the trailing-dot /
+ *                                   //   leading-or-trailing-whitespace check
  *
  * @example
  *   var resolved = b.guardFilename.verifyExtractionPath(
@@ -1023,19 +1074,53 @@ function verifyExtractionPath(entryName, extractionRoot, opts) {
     throw new GuardFilenameError("filename.extraction-unc",
       "verifyExtractionPath: entryName starts with a UNC prefix");
   }
-  // `..` segment refuses — walk path components.
+  // `..` segment refuses — walk path components. The same walk also
+  // refuses per-segment Windows-extraction hazards the disk `validate`
+  // / `sanitize` paths already catch but that string-containment +
+  // realpath agreement cannot see, because they're WITHIN-root
+  // collisions / write-target redirections rather than boundary
+  // escapes. These checks are platform-UNCONDITIONAL: the verifier may
+  // run on Linux while the archive is extracted on Windows, so a name
+  // that's only dangerous on Windows must still be refused here.
+  // Operators on a Linux-only target opt out per check, mirroring
+  // `validate`'s policy vocabulary.
   var segs = normalized.split("/");
   for (var si = 0; si < segs.length; si += 1) {
-    if (segs[si] === ".." || segs[si] === "..\\" || segs[si] === "..%2f" || segs[si] === "..%5c") {
+    var seg = segs[si];
+    if (seg === ".." || seg === "..\\" || seg === "..%2f" || seg === "..%5c") {
       throw new GuardFilenameError("filename.extraction-traversal",
         "verifyExtractionPath: entryName contains .. segment");
     }
     // URL-encoded variants — explicit refusal so operators don't
     // need to percent-decode before passing the entry name in.
-    if (/%2e%2e/i.test(segs[si]) || /%c0%ae/i.test(segs[si])) {
+    if (/%2e%2e/i.test(seg) || /%c0%ae/i.test(seg)) {
       throw new GuardFilenameError("filename.extraction-traversal-encoded",
         "verifyExtractionPath: entryName contains encoded .. segment");
     }
+    if (seg === "" || seg === ".") continue;   // separators / current-dir — nothing to name-check
+    // Windows reserved device name (CON / NUL / COM1 / LPT1 / …): on
+    // Windows the segment resolves to the device, redirecting the write.
+    if (opts.reservedNamePolicy !== "allow" && _isWinReserved(seg)) {
+      throw new GuardFilenameError("filename.extraction-reserved-name",
+        "verifyExtractionPath: entryName segment " + JSON.stringify(seg) +
+        " collides with a Windows reserved device name");
+    }
+    // NTFS alternate data stream (name:stream): on Windows the write
+    // lands on a hidden stream of the base file, not a normal file.
+    if (opts.adsPolicy !== "allow" && /:[^:\\/]+$/.test(seg)) {
+      throw new GuardFilenameError("filename.extraction-ntfs-ads",
+        "verifyExtractionPath: entryName segment " + JSON.stringify(seg) +
+        " uses NTFS alternate-data-stream syntax (name:stream)");
+    }
+    // Trailing dot / leading-or-trailing whitespace: Windows silently
+    // strips these, so `secret.txt.` or `secret.txt ` collides with an
+    // existing sibling — an in-root overwrite the containment check
+    // cannot see.
+    if (opts.leadingTrailingPolicy !== "allow" && /^\s|\s$|\.$/.test(seg)) {
+      throw new GuardFilenameError("filename.extraction-leading-trailing",
+        "verifyExtractionPath: entryName segment " + JSON.stringify(seg) +
+        " has leading/trailing whitespace or a trailing dot (Windows strips it)");
+    }
   }
   // Resolve the destination path against the root via path.resolve
   // (string-level computation; no fs hits).

package/lib/mail-server-mx.js

@@ -67,9 +67,11 @@
  *
  *   - `mail.server.mx.connect`           — IP, TLS state, FCrDNS hostname
  *   - `mail.server.mx.helo`              — HELO greeting, helo-gate verdict
- *   - `mail.server.mx.mail_from`         — sender, SPF verdict, alignment verdict
- *   - `mail.server.mx.rcpt_to`           — recipient, RBL verdict, greylist verdict
- *   - `mail.server.mx.data_accepted`     — message size, DKIM verdict, DMARC verdict
+ *   - `mail.server.mx.helo_gate_refused` — HELO identity refused (gate action)
+ *   - `mail.server.mx.mail_from`         — sender address
+ *   - `mail.server.mx.rcpt_to`           — recipient, rblListed flag, greylist action
+ *   - `mail.server.mx.rbl_refused`       — connecting IP on a DNS blocklist (zones)
+ *   - `mail.server.mx.greylist_deferred` — (ip, from, rcpt) first-seen 450 deferral
  *   - `mail.server.mx.data_refused`      — refusal reason + SMTP code (5xx vs 4xx)
  *   - `mail.server.mx.delivered`         — agent.handoff ack
  *   - `mail.server.mx.tls_handshake_failed` — handshake error
@@ -100,19 +102,30 @@
  *
  *   Every gate is a primitive that already exists. The MX slice is a
  *   state-machine + wire-protocol coordinator — no new crypto, no
- *   new parsing, no new RFC-layer primitives. If a gate isn't ready
- *   (e.g. operator hasn't wired `b.mail.auth.dmarc`), the listener
- *   skips that phase with an audit note rather than synthesizing a
- *   verdict.
+ *   new parsing, no new RFC-layer primitives. When the operator
+ *   doesn't wire a gate (e.g. omits `opts.greylist`), the listener
+ *   skips that phase rather than synthesizing a verdict.
+ *
+ *   Connection-level gates are wired into the live state machine:
+ *   `opts.helo` (HELO identity) evaluates at HELO/EHLO; `opts.rbl`
+ *   (connecting-IP DNS blocklist, evaluated once per connection) and
+ *   `opts.greylist` ((ip, from, rcpt) first-seen deferral) evaluate at
+ *   RCPT TO and surface their verdicts on the `rcpt_to` event. The
+ *   message-authentication gates (`b.guardEnvelope` SPF/DKIM/DMARC
+ *   alignment) require the inbound SPF + DKIM verification results as
+ *   inputs; that inbound-auth pipeline composes `b.mail.spf` +
+ *   `b.mail.dmarc` + DKIM verification and lands as a follow-up, at
+ *   which point the DATA-phase envelope/DMARC gate wires in. Until
+ *   then operators run those checks on the delivered message via the
+ *   agent handoff.
  *
  * @card
  *   Inbound SMTP / MX listener. RFC 5321 state machine with SMTP-
  *   smuggling defense baked into the wire-protocol layer (RFC 5321
  *   §2.3.8 + CVE-2023-51764 / 51765 / 51766), open-relay refusal by
  *   default, STARTTLS-stripping defense (CVE-2021-38371), and the
- *   framework's mail-gate cascade (HELO / RBL / greylist /
- *   guardEnvelope / DMARC / safeMime / guardEmail) running at the
- *   appropriate phase.
+ *   connection-level gate cascade (HELO identity / RBL / greylist)
+ *   running at the appropriate phase.
  */
 
 var net   = require("node:net");
@@ -149,6 +162,7 @@ var REPLY_221_BYE                = "221";
 var REPLY_250_OK                 = "250";
 var REPLY_354_START_INPUT        = "354";
 var REPLY_421_SERVICE_NOT_AVAIL  = "421";                                                             // allow:raw-byte-literal — SMTP transient code
+var REPLY_450_MAILBOX_BUSY       = "450";                                                             // allow:raw-byte-literal — SMTP transient code (greylist tempfail)
 var REPLY_451_LOCAL_ERROR        = "451";                                                             // allow:raw-byte-literal — SMTP transient code
 var REPLY_452_INSUFFICIENT_STG   = "452";                                                             // allow:raw-byte-literal — SMTP transient code
 var REPLY_500_SYNTAX             = "500";                                                             // allow:raw-byte-literal — SMTP permanent code
@@ -177,11 +191,9 @@ var RE_SIZE      = /SIZE=(\d+)/i;
  * @opts
  *   tlsContext:        TlsContext,      // required — b.network.tls.context() output (no implicit plaintext)
  *   greeting:          string,          // default "blamejs ESMTP" — HELO/EHLO 220-line banner
- *   helo:              b.mail.helo,     // optional gate
- *   rbl:               b.mail.rbl,      // optional gate
- *   greylist:          b.mail.greylist, // optional gate
- *   envelope:          b.guardEnvelope, // optional gate (SPF/DKIM alignment)
- *   dmarc:             b.mail.auth.dmarc,  // optional gate
+ *   helo:              b.mail.helo,            // optional gate — HELO identity (FCrDNS / shape / self-name)
+ *   rbl:               b.mail.rbl.create(…),   // optional gate — DNS blocklist on the connecting IP
+ *   greylist:          b.mail.greylist.create(…), // optional gate — defer first-seen (ip, from, rcpt)
  *   agent:             b.mail.agent,    // optional delivery handoff
  *   relayAllowedFor:   [{ cidr, scope }],  // operator-explicit relay allowlist; default [] = MX-only
  *   localDomains:      [string],        // RCPT TO local-domain allowlist (refuse non-local with 550 5.7.1)
@@ -199,7 +211,6 @@ var RE_SIZE      = /SIZE=(\d+)/i;
  *     helo:         b.mail.helo,
  *     rbl:          b.mail.rbl.create({ providers: ["zen.spamhaus.org"] }),
  *     greylist:     b.mail.greylist.create({ store: greylistStore }),
- *     envelope:     b.guardEnvelope,
  *     agent:        b.mail.agent.create({ store: mailStore }),
  *     localDomains: ["example.com"],
  *   });
@@ -367,6 +378,15 @@ function create(opts) {
     var lineBuffer = Buffer.alloc(0);
     var bodyCollector = null;
     var inDataBody = false;
+    // Async command pump: gates (HELO / RBL / greylist / envelope /
+    // DMARC) may await DNS or a store, so command handling is async.
+    // `pumpChain` FIFO-serializes per-chunk processing so a gate
+    // resolving cannot let a later pipelined command (RFC 2920) jump
+    // ahead of an earlier one — reply ordering + the per-command
+    // smuggling defenses stay intact. `connClosed` short-circuits any
+    // chunk queued before a teardown.
+    var pumpChain = Promise.resolve();
+    var connClosed = false;
 
     socket.setTimeout(idleTimeoutMs);
     socket.on("timeout", function () {
@@ -382,6 +402,7 @@ function create(opts) {
     });
 
     socket.on("close", function () {
+      connClosed = true;
       connections.delete(socket);
     });
 
@@ -395,20 +416,35 @@ function create(opts) {
     // 220 banner — RFC 5321 §3.1.
     _writeReply(socket, REPLY_220_READY, greeting + " ready");
 
-    socket.on("data", function (chunk) {
-      try { _ingestBytes(state, socket, chunk); }
-      catch (err) {
+    // Feed a chunk into the per-connection command pump. Chains each
+    // chunk behind the previous one's full (async) processing so command
+    // handlers + their gates run strictly in arrival order. Used by BOTH
+    // the plaintext `socket.on("data")` path AND the post-STARTTLS
+    // TLSSocket onData path — otherwise gate awaits on the upgraded
+    // socket would overlap later TLS chunks (the default strict/balanced
+    // profiles require STARTTLS before MAIL, so the gates run there) and
+    // async gate rejections would go unhandled instead of producing the
+    // 421 path. `activeSock` is whichever socket is current (plaintext or
+    // TLS) so the 421/close lands on the right transport.
+    function _feedChunk(activeSock, chunk) {
+      pumpChain = pumpChain.then(function () {
+        if (connClosed) return undefined;
+        return _ingestBytes(state, activeSock, chunk);
+      }).catch(function (err) {
+        if (connClosed) return;
         _emit("mail.server.mx.handler_threw",
           { connectionId: state.id, error: (err && err.message) || String(err) },
           "failure");
-        try { _writeReply(socket, REPLY_421_SERVICE_NOT_AVAIL, "4.3.0 Server error"); }
+        try { _writeReply(activeSock, REPLY_421_SERVICE_NOT_AVAIL, "4.3.0 Server error"); }
         catch (_e) { /* socket already gone */ }
-        _closeConnection(socket);
-      }
-    });
+        _closeConnection(activeSock);
+      });
+    }
+
+    socket.on("data", function (chunk) { _feedChunk(socket, chunk); });
 
     // ---- Byte-level ingestion --------------------------------------------
-    function _ingestBytes(state, socket, chunk) {
+    async function _ingestBytes(state, socket, chunk) {
       if (inDataBody) {
         // DATA body — accumulate via boundedChunkCollector, watch for
         // canonical "\r\n.\r\n" terminator only. Bare-LF dot terminator
@@ -444,9 +480,9 @@ function create(opts) {
         var endIdx = safeSmtp.findDotTerminator(collected);
         if (endIdx !== -1) {
           var body = collected.subarray(0, endIdx);
-          _finalizeDataBody(state, socket, body);
           inDataBody = false;
           bodyCollector = null;
+          await _finalizeDataBody(state, socket, body);
         }
         return;
       }
@@ -464,12 +500,13 @@ function create(opts) {
       while ((crlf = lineBuffer.indexOf(crlfNeedle)) !== -1) {
         var line = lineBuffer.subarray(0, crlf).toString("utf8");
         lineBuffer = lineBuffer.subarray(crlf + 2);
-        _handleCommand(state, socket, line);
+        await _handleCommand(state, socket, line);
         if (inDataBody) return;
+        if (connClosed) return;
       }
     }
 
-    function _handleCommand(state, socket, line) {
+    async function _handleCommand(state, socket, line) {
       // Per-line guard — refuse bare LF / NUL / C0 / DEL / oversize
       // BEFORE state-machine dispatch.
       try {
@@ -494,16 +531,16 @@ function create(opts) {
       switch (verb) {
         case "EHLO":
         case "HELO":
-          _handleEhlo(state, socket, line, verb);
+          await _handleEhlo(state, socket, line, verb);
           return;
         case "STARTTLS":
           _handleStartTls(state, socket);
           return;
         case "MAIL":
-          _handleMailFrom(state, socket, line);
+          await _handleMailFrom(state, socket, line);
           return;
         case "RCPT":
-          _handleRcptTo(state, socket, line);
+          await _handleRcptTo(state, socket, line);
           return;
         case "DATA":
           _handleData(state, socket);
@@ -531,7 +568,7 @@ function create(opts) {
     }
 
     // ---- EHLO / HELO ------------------------------------------------------
-    function _handleEhlo(state, socket, line, verb) {
+    async function _handleEhlo(state, socket, line, verb) {
       var helo = line.slice(verb.length).trim();
       if (!helo) {
         _writeReply(socket, REPLY_501_BAD_ARGS, "5.5.4 " + verb + " requires a domain argument");
@@ -552,6 +589,25 @@ function create(opts) {
           return;
         }
       }
+      // Operator HELO-identity gate (b.mail.helo) — FCrDNS / HELO-shape /
+      // self-name spoofing checks. Composed when the operator wires
+      // `opts.helo`; skipped silently otherwise (no synthesized verdict).
+      // Hard-reject actions (reject-shape / match-self-refused /
+      // literal-mismatch) refuse the connection; "accept" and the
+      // advisory "soft-*" actions pass (the soft verdict rides the event).
+      if (opts.helo && typeof opts.helo.evaluate === "function") {
+        var heloGate = await opts.helo.evaluate(
+          { claimedName: helo, ip: state.remoteAddress, tls: state.tls }, {});
+        state.heloVerdict = heloGate && heloGate.action;
+        if (heloGate && heloGate.action && heloGate.action !== "accept" &&
+            heloGate.action.indexOf("soft") !== 0) {
+          _emit("mail.server.mx.helo_gate_refused",
+            { connectionId: state.id, helo: helo, action: heloGate.action }, "denied");
+          _writeReply(socket, REPLY_550_MAILBOX_UNAVAIL,
+            "5.7.1 " + verb + " identity refused (" + heloGate.action + ")");
+          return;
+        }
+      }
       state.helo  = helo;
       state.stage = "ehlo";
       // Multi-line 250 capabilities advertisement per RFC 5321 §4.1.1.1.
@@ -572,7 +628,8 @@ function create(opts) {
         _writeReply(socket, REPLY_250_OK, greeting + " greets " + helo);
       }
       _emit("mail.server.mx.helo",
-        { connectionId: state.id, verb: verb, helo: helo, tls: state.tls });
+        { connectionId: state.id, verb: verb, helo: helo, tls: state.tls,
+          heloVerdict: state.heloVerdict || null });
     }
 
     // ---- STARTTLS ---------------------------------------------------------
@@ -604,13 +661,11 @@ function create(opts) {
           state.helo  = null;
         },
         onData: function (tlsSocket, chunk) {
-          try { _ingestBytes(state, tlsSocket, chunk); }
-          catch (err) {
-            _emit("mail.server.mx.handler_threw",
-              { connectionId: state.id, error: (err && err.message) || String(err) },
-              "failure");
-            _closeConnection(tlsSocket);
-          }
+          // Route the upgraded socket through the SAME serialized pump as
+          // the plaintext path — post-STARTTLS is where the gates run in
+          // the default strict/balanced profiles, so it MUST be serialized
+          // and its async rejections MUST hit the 421 path.
+          _feedChunk(tlsSocket, chunk);
         },
         onError: function (err) {
           _emit("mail.server.mx.tls_handshake_failed",
@@ -626,7 +681,7 @@ function create(opts) {
     }
 
     // ---- MAIL FROM --------------------------------------------------------
-    function _handleMailFrom(state, socket, line) {
+    async function _handleMailFrom(state, socket, line) {
       if (!state.tls && _requiresStartTls()) {
         _writeReply(socket, REPLY_530_AUTH_REQUIRED, "5.7.0 Must issue a STARTTLS command first");
         return;
@@ -677,7 +732,7 @@ function create(opts) {
     }
 
     // ---- RCPT TO ----------------------------------------------------------
-    function _handleRcptTo(state, socket, line) {
+    async function _handleRcptTo(state, socket, line) {
       if (state.stage !== "rcpt") {
         _writeReply(socket, REPLY_503_BAD_SEQUENCE, "5.5.1 MAIL FROM first");
         return;
@@ -740,9 +795,49 @@ function create(opts) {
           return;
         }
       }
+      // RBL gate (b.mail.rbl) — DNS blocklist check on the connecting
+      // IP. The verdict is per-connection, so it's evaluated once and
+      // cached on state; a listed IP refuses with 554. Skipped silently
+      // when opts.rbl isn't wired.
+      if (opts.rbl && typeof opts.rbl.query === "function") {
+        if (state.rblVerdict === undefined) {
+          state.rblVerdict = await opts.rbl.query(state.remoteAddress);
+        }
+        if (state.rblVerdict && Array.isArray(state.rblVerdict.listed) &&
+            state.rblVerdict.listed.length > 0) {
+          _trackRefusedRcpt(state, rcpt, "rbl-listed");
+          _emit("mail.server.mx.rbl_refused",
+            { connectionId: state.id, remoteAddress: state.remoteAddress,
+              zones: state.rblVerdict.listed.map(function (l) { return l.zone; }) }, "denied");
+          _writeReply(socket, REPLY_554_TRANSACTION_FAILED,
+            "5.7.1 Connecting IP is on a DNS blocklist");
+          return;
+        }
+      }
+      // Greylist gate (b.mail.greylist) — defer first sight of an
+      // (ip, mailFrom, rcpt) tuple with a 450 tempfail; legitimate
+      // senders retry and pass. "defer" → 450; "accept" → continue.
+      // Skipped silently when opts.greylist isn't wired.
+      var greyVerdict = null;
+      if (opts.greylist && typeof opts.greylist.check === "function") {
+        greyVerdict = await opts.greylist.check(
+          { ip: state.remoteAddress, mailFrom: state.mailFrom || "", rcptTo: rcpt });
+        if (greyVerdict && greyVerdict.action === "defer") {
+          _emit("mail.server.mx.greylist_deferred",
+            { connectionId: state.id, remoteAddress: state.remoteAddress,
+              mailFrom: state.mailFrom, rcptTo: rcpt,
+              reason: greyVerdict.reason }, "denied");
+          _writeReply(socket, REPLY_450_MAILBOX_BUSY,
+            "4.7.1 Greylisted — please retry shortly");
+          return;
+        }
+      }
       state.rcpts.push(rcpt);
       _emit("mail.server.mx.rcpt_to",
-        { connectionId: state.id, rcptTo: rcpt, rcptCount: state.rcpts.length });
+        { connectionId: state.id, rcptTo: rcpt, rcptCount: state.rcpts.length,
+          rblListed: !!(state.rblVerdict && Array.isArray(state.rblVerdict.listed) &&
+            state.rblVerdict.listed.length > 0),
+          greylist: greyVerdict ? greyVerdict.action : null });
       _writeReply(socket, REPLY_250_OK, "2.1.5 Recipient OK");
     }
 
@@ -764,7 +859,7 @@ function create(opts) {
       });
     }
 
-    function _finalizeDataBody(state, socket, body) {
+    async function _finalizeDataBody(state, socket, body) {
       // body is the raw bytes BEFORE dot-stuffing reversal. RFC 5321
       // §4.5.2 — a single leading "." is doubled on the wire; undo.
       var dedotted = safeSmtp.dotUnstuff(body);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.11",
+  "version": "0.13.13",
   "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:072ab39e-e89f-4967-a9fc-8a2a28ec13b8",
+  "serialNumber": "urn:uuid:b3c8f3dc-4ada-41d3-9b05-66ce6774c125",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-27T09:56:05.887Z",
+    "timestamp": "2026-05-27T12:37:28.862Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.11",
+      "bom-ref": "@blamejs/core@0.13.13",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.11",
+      "version": "0.13.13",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.11",
+      "purl": "pkg:npm/%40blamejs/core@0.13.13",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.11",
+      "ref": "@blamejs/core@0.13.13",
       "dependsOn": []
     }
   ]