@emailcheck/email-validator-js 4.0.0-beta.1 → 4.0.0-beta.2

package/README.md

@@ -1485,6 +1485,41 @@ const parsed = parseSmtpError('552 5.2.2 mailbox over quota');
 
 The four flags are orthogonal — a single message can fire multiple. See `__tests__/0112-smtp-error-parser.test.ts` for the full classification matrix.
 
+### Refining a coarse reason via the RFC 3463 enhanced status
+
+`verifyMailboxSMTP` returns a coarse `error` reason (`not_found` / `over_quota` / `temporary_failure` / `ambiguous` / …) that's stable across MX implementations. When the MX includes an enhanced status code (RFC 3463) — e.g. `5.1.1` for "user unknown" vs. `5.7.1` for "policy block" — pipe both through `refineReasonByEnhancedStatus` to get a more specific reason:
+
+```typescript
+import { refineReasonByEnhancedStatus, verifyMailboxSMTP } from '@emailcheck/email-validator-js';
+
+const { smtpResult } = await verifyMailboxSMTP({
+  local: 'alice', domain: 'example.com', mxRecords: ['mx.example.com'],
+});
+const refined = refineReasonByEnhancedStatus(smtpResult.error, smtpResult.enhancedStatus);
+// e.g. 'mailbox_does_not_exist' instead of 'not_found' when the MX returned 550 5.1.1
+```
+
+Mapping (codes not in the table return the original reason unchanged):
+
+| DSN code  | Refined reason                       |
+| --------- | ------------------------------------ |
+| `5.1.1`   | `mailbox_does_not_exist`             |
+| `5.1.2`   | `bad_destination_system`             |
+| `5.1.3`   | `bad_destination_address`            |
+| `5.1.6`   | `mailbox_moved`                      |
+| `5.1.10`  | `recipient_address_has_null_mx`      |
+| `5.2.0`   | `mailbox_status_other`               |
+| `5.2.1`   | `mailbox_disabled`                   |
+| `5.2.2`   | `mailbox_full`                       |
+| `5.2.3`   | `message_too_long`                   |
+| `5.2.4`   | `mailing_list_expansion_problem`     |
+| `4.4.1`   | `no_answer_from_host`                |
+| `4.4.2`   | `bad_connection`                     |
+| `5.7.0`   | `security_other`                     |
+| `5.7.1`   | `delivery_not_authorized`            |
+| `5.7.25`  | `no_reverse_dns`                     |
+| `5.7.26`  | `multiple_authentication_failures`   |
+
 ## 📊 Performance & Caching
 
 The library includes intelligent caching to improve performance:

package/dist/cli/index.js

@@ -318,6 +318,7 @@ var SMTPStep = /* @__PURE__ */ ((SMTPStep2) => {
   SMTPStep2["greeting"] = "GREETING";
   SMTPStep2["ehlo"] = "EHLO";
   SMTPStep2["helo"] = "HELO";
+  SMTPStep2["startTls"] = "STARTTLS";
   SMTPStep2["mailFrom"] = "MAIL_FROM";
   SMTPStep2["rcptTo"] = "RCPT_TO";
   return SMTPStep2;
@@ -1081,7 +1082,8 @@ async function verifyMailboxSMTP(params) {
     sequence,
     log,
     catchAllProbeLocal: options.catchAllProbeLocal,
-    pipelining: options.pipelining ?? "auto"
+    pipelining: options.pipelining ?? "auto",
+    startTls: options.startTls ?? "auto"
   };
   const verdictCache = cache ? getCacheStore(cache, "smtp") : null;
   const verdictKey = `${primaryMx}:${local}@${domain}`;
@@ -1204,10 +1206,21 @@ class SMTPProbeConnection {
     this.buffer = "";
     this.resolved = false;
     this.currentStepIndex = 0;
+    /** True between sending STARTTLS and the TLS handshake completing. */
+    this.tlsUpgrading = false;
+    /**
+     * True when we sent the second EHLO after a successful STARTTLS upgrade.
+     * The EHLO response arrives while `currentStepIndex` is still on `startTls`
+     * — this flag tells the dispatcher to advance past startTls when the
+     * post-upgrade EHLO returns 250, instead of treating it as a STARTTLS
+     * acknowledgement.
+     */
+    this.postUpgradeReEhlo = false;
     this.transcript = [];
     this.commands = [];
     // ── EHLO capability advertisement ────────────────────────────────────────
     this.supportsPipelining = false;
+    this.supportsStartTls = false;
     this.dualPhase = "idle";
     this.realOutcome = "pending";
     this.probeOutcome = "pending";
@@ -1229,7 +1242,7 @@ class SMTPProbeConnection {
         this.processLine(line);
       }
     };
-    const defaultSteps = [SMTPStep.greeting, SMTPStep.ehlo, SMTPStep.mailFrom, SMTPStep.rcptTo];
+    const defaultSteps = [SMTPStep.greeting, SMTPStep.ehlo, SMTPStep.startTls, SMTPStep.mailFrom, SMTPStep.rcptTo];
     this.steps = [...p.sequence?.steps ?? defaultSteps];
     this.isTLS = PORT_TLS[p.port] === true;
     const servername = isIPAddress(p.mxHost) ? void 0 : p.mxHost;
@@ -1249,7 +1262,8 @@ class SMTPProbeConnection {
         this.connect();
         this.armConnectionTimer();
       } catch (error) {
-        this.finish(null, `connect_throw:${error instanceof Error ? error.message : "unknown"}`);
+        this.p.log(`connect threw: ${error instanceof Error ? error.message : "unknown"}`);
+        this.finish(null, "connection_error");
       }
     });
   }
@@ -1302,6 +1316,9 @@ class SMTPProbeConnection {
       case SMTPStep.helo:
         this.send(`HELO ${this.p.hostname}`);
         return;
+      case SMTPStep.startTls:
+        this.executeStartTls();
+        return;
       case SMTPStep.mailFrom: {
         const from = this.p.sequence?.from ?? `<${this.p.local}@${this.p.domain}>`;
         this.send(`MAIL FROM:${from}`);
@@ -1312,6 +1329,73 @@ class SMTPProbeConnection {
         return;
     }
   }
+  /**
+   * Conditional STARTTLS upgrade. Skipped (advances to next step) when:
+   *   - already TLS (implicit-TLS port like 465 or already-upgraded)
+   *   - `startTls === 'never'`
+   *   - `startTls === 'auto'` AND the MX didn't advertise STARTTLS in EHLO
+   *
+   * Sends `STARTTLS` and waits for 220 when:
+   *   - `startTls === 'force'` (regardless of advertisement)
+   *   - `startTls === 'auto'` AND the MX advertised it
+   *
+   * On 220, `tls.connect()` wraps the existing socket. After the handshake
+   * we re-EHLO (mandatory per RFC 3207 §4.2 — pre-TLS state must be
+   * discarded) before continuing to MAIL FROM.
+   */
+  executeStartTls() {
+    const mode = this.p.startTls;
+    const wantsUpgrade = !this.isTLS && mode !== "never" && (mode === "force" || mode === "auto" && this.supportsStartTls);
+    if (!wantsUpgrade) {
+      this.nextStep();
+      return;
+    }
+    this.send("STARTTLS");
+  }
+  /**
+   * Wrap the plaintext socket with TLS in place. Called after the server
+   * answers our STARTTLS with 220. Detaches the plaintext-socket listeners
+   * (TLS owns the underlying transport now), re-installs them on the wrapped
+   * socket, resets EHLO-derived capabilities, and re-issues EHLO once the
+   * handshake completes (RFC 3207 §4.2 mandates re-EHLO after upgrade —
+   * pre-TLS state must be discarded).
+   */
+  upgradeToTls() {
+    const plainSocket = this.socket;
+    if (!plainSocket) {
+      this.finish(null, "tls_upgrade_failed");
+      return;
+    }
+    const detach = plainSocket.removeAllListeners;
+    if (typeof detach === "function") {
+      detach.call(plainSocket, "data");
+      detach.call(plainSocket, "error");
+      detach.call(plainSocket, "close");
+      detach.call(plainSocket, "timeout");
+    }
+    try {
+      plainSocket.setTimeout(0);
+    } catch {
+    }
+    this.tlsUpgrading = true;
+    const servername = isIPAddress(this.p.mxHost) ? void 0 : this.p.mxHost;
+    const tlsSocket = tls__namespace.connect({ ...this.tlsOptions, socket: plainSocket, servername }, () => {
+      this.tlsUpgrading = false;
+      this.isTLS = true;
+      this.buffer = "";
+      this.supportsStartTls = false;
+      this.supportsPipelining = false;
+      this.postUpgradeReEhlo = true;
+      this.send(`EHLO ${this.p.hostname}`);
+    });
+    this.socket = tlsSocket;
+    this.socket.on("data", this.onData);
+    this.socket.on("error", () => {
+      this.finish(null, this.tlsUpgrading ? "tls_handshake_failed" : "connection_error");
+    });
+    this.socket.on("close", () => this.finish(null, "connection_closed"));
+    this.socket.setTimeout(this.p.timeout, () => this.finish(null, "socket_timeout"));
+  }
   /**
    * Send the dual-probe envelope (real RCPT + probe RCPT + RSET). Pipelined
    * when the MX advertised PIPELINING (or `pipelining: 'force'`); sequential
@@ -1366,9 +1450,11 @@ ${rsetCmd}\r
     }
     if (MULTILINE_RE.test(line)) {
       const step = this.steps[this.currentStepIndex];
-      if ((step === SMTPStep.ehlo || step === SMTPStep.helo) && line.startsWith("250-")) {
+      const isEhloLike = step === SMTPStep.ehlo || step === SMTPStep.helo || step === SMTPStep.startTls && this.postUpgradeReEhlo;
+      if (isEhloLike && line.startsWith("250-")) {
         const upper = line.toUpperCase();
         if (upper.includes("PIPELINING")) this.supportsPipelining = true;
+        if (upper.includes("STARTTLS")) this.supportsStartTls = true;
       }
       return;
     }
@@ -1397,6 +1483,19 @@ ${rsetCmd}\r
         if (code === 250) this.nextStep();
         else this.finish(null, "helo_failed");
         return;
+      case SMTPStep.startTls:
+        if (this.postUpgradeReEhlo) {
+          this.postUpgradeReEhlo = false;
+          if (code === 250) this.nextStep();
+          else this.finish(null, "ehlo_failed");
+          return;
+        }
+        if (code === 220) {
+          this.upgradeToTls();
+        } else {
+          this.finish(null, "tls_upgrade_failed");
+        }
+        return;
       case SMTPStep.mailFrom:
         if (code === 250) this.nextStep();
         else this.finish(null, "mail_from_rejected");