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

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export { isFreeEmail } from './is-free-email';
 export { isSpamEmail } from './is-spam-email';
 export { isSpamName } from './is-spam-name';
 export { cleanNameForAlgorithm, defaultNameDetectionMethod, detectName, detectNameForAlgorithm, detectNameFromEmail, } from './name-detector';
+export { refineReasonByEnhancedStatus } from './refine-reason';
 export { type ParsedSmtpError, parseSmtpError } from './smtp-error-parser';
 export { ArrayTranscriptCollector, NULL_COLLECTOR, type TranscriptCollector, } from './transcript';
 export * from './types';

package/dist/index.esm.js

@@ -175,6 +175,7 @@ var SMTPStep;
   SMTPStep2["greeting"] = "GREETING";
   SMTPStep2["ehlo"] = "EHLO";
   SMTPStep2["helo"] = "HELO";
+  SMTPStep2["startTls"] = "STARTTLS";
   SMTPStep2["mailFrom"] = "MAIL_FROM";
   SMTPStep2["rcptTo"] = "RCPT_TO";
 })(SMTPStep || (SMTPStep = {}));
@@ -993,7 +994,7 @@ function defaultProbeLocal() {
   return `${randomBytes(8).toString("hex")}-noexist`;
 }
 async function verifyMailboxSMTP(params) {
-  var _a, _b, _c, _d, _e, _f, _g, _h;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _j;
   const { local, domain, options = {} } = params;
   const mxRecords = (_a = params.mxRecords) !== null && _a !== void 0 ? _a : [];
   const ports = ((_b = options.ports) !== null && _b !== void 0 ? _b : DEFAULT_PORTS).filter((port) => Number.isInteger(port) && port > 0 && port < 65536);
@@ -1025,7 +1026,8 @@ async function verifyMailboxSMTP(params) {
     sequence,
     log,
     catchAllProbeLocal: options.catchAllProbeLocal,
-    pipelining: (_h = options.pipelining) !== null && _h !== void 0 ? _h : "auto"
+    pipelining: (_h = options.pipelining) !== null && _h !== void 0 ? _h : "auto",
+    startTls: (_j = options.startTls) !== null && _j !== void 0 ? _j : "auto"
   };
   const verdictCache = cache ? getCacheStore(cache, "smtp") : null;
   const verdictKey = `${primaryMx}:${local}@${domain}`;
@@ -1159,9 +1161,12 @@ class SMTPProbeConnection {
     this.buffer = "";
     this.resolved = false;
     this.currentStepIndex = 0;
+    this.tlsUpgrading = false;
+    this.postUpgradeReEhlo = false;
     this.transcript = [];
     this.commands = [];
     this.supportsPipelining = false;
+    this.supportsStartTls = false;
     this.dualPhase = "idle";
     this.realOutcome = "pending";
     this.probeOutcome = "pending";
@@ -1179,7 +1184,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 = [...(_b = (_a = p.sequence) === null || _a === void 0 ? void 0 : _a.steps) !== null && _b !== void 0 ? _b : defaultSteps];
     this.isTLS = PORT_TLS[p.port] === true;
     const servername = isIPAddress(p.mxHost) ? void 0 : p.mxHost;
@@ -1199,7 +1204,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");
       }
     });
   }
@@ -1258,6 +1264,9 @@ class SMTPProbeConnection {
       case SMTPStep.helo:
         this.send(`HELO ${this.p.hostname}`);
         return;
+      case SMTPStep.startTls:
+        this.executeStartTls();
+        return;
       case SMTPStep.mailFrom: {
         const from = (_b = (_a = this.p.sequence) === null || _a === void 0 ? void 0 : _a.from) !== null && _b !== void 0 ? _b : `<${this.p.local}@${this.p.domain}>`;
         this.send(`MAIL FROM:${from}`);
@@ -1268,6 +1277,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.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
@@ -1326,10 +1402,13 @@ ${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;
     }
@@ -1364,6 +1443,21 @@ ${rsetCmd}\r
         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();
@@ -2525,6 +2619,36 @@ function isSpamName(name) {
   return true;
 }
 
+const REFINEMENT_TABLE = {
+  // X.1.x — addressing
+  "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",
+  // X.2.x — mailbox status
+  "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",
+  // X.4.x — network / routing
+  "4.4.1": "no_answer_from_host",
+  "4.4.2": "bad_connection",
+  // X.7.x — security / policy
+  "5.7.0": "security_other",
+  "5.7.1": "delivery_not_authorized",
+  "5.7.25": "no_reverse_dns",
+  "5.7.26": "multiple_authentication_failures"
+};
+function refineReasonByEnhancedStatus(reason, enhancedStatus) {
+  var _a;
+  const base = reason !== null && reason !== void 0 ? reason : "unknown";
+  if (!enhancedStatus)
+    return base;
+  return (_a = REFINEMENT_TABLE[enhancedStatus]) !== null && _a !== void 0 ? _a : base;
+}
+
 const NETWORK_ERROR_PATTERNS = [
   "etimedout",
   "econnrefused",
@@ -2628,5 +2752,5 @@ function parseSmtpError(errorMessage) {
   return { isDisabled, hasFullInbox, isCatchAll, isInvalid };
 }
 
-export { ArrayTranscriptCollector, DEFAULT_CACHE_OPTIONS, EmailProvider, LRUAdapter, NULL_COLLECTOR, RedisAdapter, SMTPStep, VerificationErrorCode, cleanNameForAlgorithm, clearDefaultCache, commonEmailDomains, defaultDomainSuggestionMethod, defaultNameDetectionMethod, detectName, detectNameForAlgorithm, detectNameFromEmail, domainPorts, getCacheStore, getDefaultCache, getDomainAge, getDomainRegistrationStatus, getDomainSimilarity, isCommonDomain, isDisposableEmail, isFreeEmail, isSpamEmail, isSpamName, isValidEmail, isValidEmailDomain, parseSmtpError, suggestDomain, suggestEmailDomain, verifyEmail, verifyEmailBatch };
+export { ArrayTranscriptCollector, DEFAULT_CACHE_OPTIONS, EmailProvider, LRUAdapter, NULL_COLLECTOR, RedisAdapter, SMTPStep, VerificationErrorCode, cleanNameForAlgorithm, clearDefaultCache, commonEmailDomains, defaultDomainSuggestionMethod, defaultNameDetectionMethod, detectName, detectNameForAlgorithm, detectNameFromEmail, domainPorts, getCacheStore, getDefaultCache, getDomainAge, getDomainRegistrationStatus, getDomainSimilarity, isCommonDomain, isDisposableEmail, isFreeEmail, isSpamEmail, isSpamName, isValidEmail, isValidEmailDomain, parseSmtpError, refineReasonByEnhancedStatus, suggestDomain, suggestEmailDomain, verifyEmail, verifyEmailBatch };
 //# sourceMappingURL=index.esm.js.map