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

package/dist/index.js

@@ -4,6 +4,7 @@ var tinyLru = require('tiny-lru');
 var psl = require('psl');
 var stringSimilarityJs = require('string-similarity-js');
 var node_dns = require('node:dns');
+var node_crypto = require('node:crypto');
 var net$1 = require('node:net');
 var tls = require('node:tls');
 
@@ -680,9 +681,9 @@ function parseCompositeNamePart(part) {
         cleaned = pureAlpha;
         confidence = 0.6;
       } else {
-        const baseMatch2 = part.match(/^([a-zA-Z]+)\d*$/);
-        if (baseMatch2) {
-          cleaned = baseMatch2[1];
+        const baseMatch = part.match(/^([a-zA-Z]+)\d*$/);
+        if (baseMatch) {
+          cleaned = baseMatch[1];
           confidence = 0.75;
         } else {
           cleaned = part;
@@ -696,9 +697,7 @@ function parseCompositeNamePart(part) {
       confidence = Math.min(1, confidence + 0.2);
     }
   }
-  const baseMatch = part.match(/^([a-zA-Z]+[a-zA-Z0-9]*?)\d*$/);
-  const base = baseMatch ? baseMatch[1] : part;
-  return { base, hasNumbers, cleaned, confidence };
+  return { hasNumbers, cleaned, confidence };
 }
 function isLikelyName(str, allowNumbers = false, allowSingleLetter = false) {
   if (!str)
@@ -989,6 +988,9 @@ function parseDsn(reply) {
     return null;
   return { class: Number(match[1]), subject: Number(match[2]), detail: Number(match[3]) };
 }
+function dsnToString(dsn) {
+  return `${dsn.class}.${dsn.subject}.${dsn.detail}`;
+}
 function isPolicyBlock(reply) {
   const dsn = parseDsn(reply);
   return (dsn === null || dsn === void 0 ? void 0 : dsn.class) === 5 && (dsn === null || dsn === void 0 ? void 0 : dsn.subject) === 7;
@@ -1009,8 +1011,11 @@ function isInvalidMailboxError(reply) {
     return false;
   return true;
 }
+function defaultProbeLocal() {
+  return `${node_crypto.randomBytes(8).toString("hex")}-noexist`;
+}
 async function verifyMailboxSMTP(params) {
-  var _a, _b, _c, _d, _e, _f, _g;
+  var _a, _b, _c, _d, _e, _f, _g, _h;
   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);
@@ -1023,16 +1028,29 @@ async function verifyMailboxSMTP(params) {
   const cache = options.cache;
   const log = debug ? (...args) => console.log("[SMTP]", ...args) : () => {
   };
-  const mxHost = mxRecords[0];
-  if (!mxHost) {
+  const startedAtMs = Date.now();
+  const primaryMx = mxRecords[0];
+  if (!primaryMx) {
     log("No MX records found");
-    return { smtpResult: failureResult("No MX records found"), cached: false, port: 0, portCached: false };
+    const metrics2 = makeMetrics([], 0, 0, void 0, startedAtMs);
+    return { smtpResult: failureResult("no_mx_records", metrics2), cached: false, port: 0, portCached: false };
   }
-  log(`Verifying ${local}@${domain} via ${mxHost}`);
+  log(`Verifying ${local}@${domain} via ${primaryMx} (mx count=${mxRecords.length})`);
   const transcript = [];
   const commands = [];
+  const probeOptions = {
+    local,
+    domain,
+    timeout,
+    tlsConfig,
+    hostname,
+    sequence,
+    log,
+    catchAllProbeLocal: options.catchAllProbeLocal,
+    pipelining: (_h = options.pipelining) !== null && _h !== void 0 ? _h : "auto"
+  };
   const verdictCache = cache ? getCacheStore(cache, "smtp") : null;
-  const verdictKey = `${mxHost}:${local}@${domain}`;
+  const verdictKey = `${primaryMx}:${local}@${domain}`;
   if (verdictCache) {
     const cachedResult = await safeCacheGet(verdictCache, verdictKey);
     if (cachedResult) {
@@ -1041,81 +1059,99 @@ async function verifyMailboxSMTP(params) {
     }
   }
   const portCache = cache ? getCacheStore(cache, "smtpPort") : null;
-  if (portCache) {
-    const cachedPort = await safeCacheGet(portCache, mxHost);
-    if (cachedPort) {
-      log(`Using cached port: ${cachedPort}`);
-      const probe = await runProbe({
-        mxHost,
-        port: cachedPort,
-        local,
-        domain,
-        timeout,
-        tlsConfig,
-        hostname,
-        sequence,
-        log
-      });
-      collectTranscript(transcript, commands, probe, cachedPort);
-      const smtpResult = toSmtpVerificationResult(probe.result, captureTranscript ? { transcript, commands } : void 0);
-      await safeCacheSet(verdictCache, verdictKey, smtpResult);
-      return { smtpResult, cached: false, port: cachedPort, portCached: true };
-    }
-  }
-  for (const port of ports) {
-    log(`Testing port ${port}`);
-    const probe = await runProbe({ mxHost, port, local, domain, timeout, tlsConfig, hostname, sequence, log });
-    collectTranscript(transcript, commands, probe, port);
-    const smtpResult = toSmtpVerificationResult(probe.result, captureTranscript ? { transcript, commands } : void 0);
-    await safeCacheSet(verdictCache, verdictKey, smtpResult);
-    if (probe.result !== null) {
-      await safeCacheSet(portCache, mxHost, port);
-      return { smtpResult, cached: false, port, portCached: false };
+  const cachedPort = portCache ? await safeCacheGet(portCache, primaryMx) : null;
+  const mxHostsTried = [];
+  let mxAttempts = 0;
+  let portAttempts = 0;
+  let lastReason = "all_attempts_failed";
+  let lastEnhancedStatus;
+  let lastResponseCode;
+  for (const mxHost of mxRecords) {
+    mxHostsTried.push(mxHost);
+    mxAttempts++;
+    const portsForThisMx = mxHost === primaryMx && cachedPort ? [cachedPort, ...ports.filter((p) => p !== cachedPort)] : ports;
+    for (const port of portsForThisMx) {
+      portAttempts++;
+      log(`Testing ${mxHost}:${port}`);
+      const probe = await runProbe({ ...probeOptions, mxHost, port });
+      collectTranscript(transcript, commands, probe, mxHost, port);
+      lastReason = probe.reason;
+      if (probe.enhancedStatus !== void 0)
+        lastEnhancedStatus = probe.enhancedStatus;
+      if (probe.responseCode !== void 0)
+        lastResponseCode = probe.responseCode;
+      if (probe.result !== null) {
+        const metrics2 = makeMetrics(mxHostsTried, mxAttempts, portAttempts, mxHost, startedAtMs);
+        const smtpResult2 = toSmtpVerificationResult(probe, {
+          transcript: captureTranscript ? transcript : void 0,
+          commands: captureTranscript ? commands : void 0,
+          metrics: metrics2
+        });
+        await safeCacheSet(verdictCache, verdictKey, smtpResult2);
+        if (mxHost === primaryMx)
+          await safeCacheSet(portCache, primaryMx, port);
+        return { smtpResult: smtpResult2, cached: false, port, portCached: cachedPort === port };
+      }
     }
   }
-  log("All ports failed");
+  log(`All MX\xD7port attempts failed (mx=${mxAttempts}, port=${portAttempts})`);
+  const metrics = makeMetrics(mxHostsTried, mxAttempts, portAttempts, void 0, startedAtMs);
+  const smtpResult = {
+    ...failureResult(lastReason, metrics),
+    ...lastEnhancedStatus !== void 0 ? { enhancedStatus: lastEnhancedStatus } : {},
+    ...lastResponseCode !== void 0 ? { responseCode: lastResponseCode } : {},
+    ...captureTranscript ? { transcript: [...transcript], commands: [...commands] } : {}
+  };
+  return { smtpResult, cached: false, port: 0, portCached: false };
+}
+function makeMetrics(mxHostsTried, mxAttempts, portAttempts, mxHostUsed, startedAtMs) {
   return {
-    smtpResult: {
-      ...failureResult("All SMTP connection attempts failed"),
-      ...captureTranscript ? { transcript: [...transcript], commands: [...commands] } : {}
-    },
-    cached: false,
-    port: 0,
-    portCached: false
+    mxAttempts,
+    portAttempts,
+    mxHostsTried: [...mxHostsTried],
+    ...mxHostUsed !== void 0 ? { mxHostUsed } : {},
+    totalDurationMs: Date.now() - startedAtMs
   };
 }
-function collectTranscript(transcript, commands, probe, port) {
+function collectTranscript(transcript, commands, probe, mxHost, port) {
+  const prefix = `${mxHost}:${port}`;
   for (const line of probe.transcript)
-    transcript.push(`${port}|s| ${line}`);
+    transcript.push(`${prefix}|s| ${line}`);
   for (const cmd of probe.commands)
-    commands.push(`${port}|c| ${cmd}`);
+    commands.push(`${prefix}|c| ${cmd}`);
 }
-function failureResult(error) {
+function failureResult(reason, metrics) {
   return {
     canConnectSmtp: false,
     hasFullInbox: false,
     isCatchAll: false,
     isDeliverable: false,
     isDisabled: false,
-    error,
-    providerUsed: exports.EmailProvider.everythingElse,
-    checkedAt: Date.now()
+    error: reason,
+    checkedAt: Date.now(),
+    metrics
   };
 }
-function toSmtpVerificationResult(result, capture) {
-  const base = {
+function toSmtpVerificationResult(probe, extras) {
+  var _a;
+  const result = probe.result;
+  const out = {
     canConnectSmtp: result !== null,
-    hasFullInbox: false,
-    isCatchAll: false,
+    hasFullInbox: probe.reason === "over_quota",
+    isCatchAll: (_a = probe.isCatchAll) !== null && _a !== void 0 ? _a : false,
     isDeliverable: result === true,
     isDisabled: result === false,
-    error: result === true ? void 0 : result === null ? "ambiguous" : "not_found",
-    providerUsed: exports.EmailProvider.everythingElse,
-    checkedAt: Date.now()
+    error: result === true ? void 0 : probe.reason,
+    checkedAt: Date.now(),
+    metrics: extras.metrics,
+    ...probe.enhancedStatus !== void 0 ? { enhancedStatus: probe.enhancedStatus } : {},
+    ...probe.responseCode !== void 0 ? { responseCode: probe.responseCode } : {}
   };
-  if (!capture)
-    return base;
-  return { ...base, transcript: [...capture.transcript], commands: [...capture.commands] };
+  if (extras.transcript)
+    out.transcript = [...extras.transcript];
+  if (extras.commands)
+    out.commands = [...extras.commands];
+  return out;
 }
 async function safeCacheGet(store, key) {
   if (!store)
@@ -1147,6 +1183,12 @@ class SMTPProbeConnection {
     this.currentStepIndex = 0;
     this.transcript = [];
     this.commands = [];
+    this.supportsPipelining = false;
+    this.dualPhase = "idle";
+    this.realOutcome = "pending";
+    this.probeOutcome = "pending";
+    this.dualPipelined = false;
+    this.pendingDecision = null;
     this.onData = (data) => {
       if (this.resolved)
         return;
@@ -1170,6 +1212,7 @@ class SMTPProbeConnection {
       minVersion: "TLSv1.2",
       ...typeof p.tlsConfig === "object" ? p.tlsConfig : {}
     };
+    this.probeLocal = p.catchAllProbeLocal ? p.catchAllProbeLocal(p.local, p.domain) : defaultProbeLocal();
   }
   run() {
     return new Promise((resolve) => {
@@ -1230,6 +1273,7 @@ class SMTPProbeConnection {
     switch (step) {
       case exports.SMTPStep.greeting:
         return;
+      // server-driven; nothing to send
       case exports.SMTPStep.ehlo:
         this.send(`EHLO ${this.p.hostname}`);
         return;
@@ -1242,39 +1286,87 @@ class SMTPProbeConnection {
         return;
       }
       case exports.SMTPStep.rcptTo:
-        this.send(`RCPT TO:<${this.p.local}@${this.p.domain}>`);
+        this.executeEnvelope();
         return;
     }
   }
+  /**
+   * Send the dual-probe envelope (real RCPT + probe RCPT + RSET). Pipelined
+   * when the MX advertised PIPELINING (or `pipelining: 'force'`); sequential
+   * otherwise.
+   */
+  executeEnvelope() {
+    var _a;
+    const wantsPipelining = this.p.pipelining === "force" || this.p.pipelining === "auto" && this.supportsPipelining;
+    const realCmd = `RCPT TO:<${this.p.local}@${this.p.domain}>`;
+    if (wantsPipelining) {
+      this.dualPipelined = true;
+      const probeCmd = `RCPT TO:<${this.probeLocal}@${this.p.domain}>`;
+      const rsetCmd = "RSET";
+      this.commands.push(realCmd, probeCmd, rsetCmd);
+      this.p.log(`\u2192 ${realCmd}`);
+      this.p.log(`\u2192 ${probeCmd}`);
+      this.p.log(`\u2192 ${rsetCmd}`);
+      (_a = this.socket) === null || _a === void 0 ? void 0 : _a.write(`${realCmd}\r
+${probeCmd}\r
+${rsetCmd}\r
+`);
+      this.dualPhase = "rcpt_real";
+      return;
+    }
+    this.dualPipelined = false;
+    this.send(realCmd);
+    this.dualPhase = "rcpt_real";
+  }
   processLine(line) {
     if (this.resolved)
       return;
     this.transcript.push(line);
     this.p.log(`\u2190 ${line}`);
-    if (isHighVolume(line)) {
-      this.finish(true, "high_volume");
-      return;
-    }
-    if (isOverQuota(line)) {
-      this.finish(false, "over_quota");
-      return;
+    const codeStr = line.slice(0, 3);
+    const numericCode = /^\d{3}$/.test(codeStr) ? parseInt(codeStr, 10) : null;
+    if (numericCode !== null)
+      this.lastResponseCode = numericCode;
+    const dsn = parseDsn(line);
+    if (dsn)
+      this.lastEnhancedStatus = dsnToString(dsn);
+    if (this.dualPhase === "idle" || this.dualPhase === "rcpt_real") {
+      if (isHighVolume(line)) {
+        this.finish(true, "high_volume");
+        return;
+      }
+      if (isOverQuota(line)) {
+        this.isCatchAllFlag = false;
+        this.finish(false, "over_quota");
+        return;
+      }
+      if (isInvalidMailboxError(line)) {
+        this.isCatchAllFlag = false;
+        this.finish(false, "not_found");
+        return;
+      }
     }
-    if (isInvalidMailboxError(line)) {
-      this.finish(false, "not_found");
+    if (MULTILINE_RE.test(line)) {
+      const step = this.steps[this.currentStepIndex];
+      if ((step === exports.SMTPStep.ehlo || step === exports.SMTPStep.helo) && line.startsWith("250-")) {
+        const upper = line.toUpperCase();
+        if (upper.includes("PIPELINING"))
+          this.supportsPipelining = true;
+      }
       return;
     }
-    if (MULTILINE_RE.test(line))
-      return;
-    const code = line.slice(0, 3);
-    const numericCode = /^\d{3}$/.test(code) ? parseInt(code, 10) : null;
     if (numericCode === null) {
       this.finish(null, "unrecognized_response");
       return;
     }
-    this.dispatch(numericCode);
+    this.dispatch(numericCode, line);
   }
-  dispatch(code) {
+  dispatch(code, line) {
     const step = this.steps[this.currentStepIndex];
+    if (this.dualPhase !== "idle" && step === exports.SMTPStep.rcptTo) {
+      this.handleEnvelopeReply(code, line);
+      return;
+    }
     switch (step) {
       case exports.SMTPStep.greeting:
         if (code === 220)
@@ -1301,17 +1393,93 @@ class SMTPProbeConnection {
           this.finish(null, "mail_from_rejected");
         return;
       case exports.SMTPStep.rcptTo:
-        if (code === 250 || code === 251)
-          this.finish(true, "valid");
-        else if (code === 552 || code === 452)
-          this.finish(false, "over_quota");
-        else if (code >= 400 && code < 500)
-          this.finish(null, "temporary_failure");
-        else
-          this.finish(null, "ambiguous");
+        this.handleEnvelopeReply(code, line);
         return;
     }
   }
+  /**
+   * Dual-probe / pipelined-envelope reply router. Demuxes server replies for
+   * the three queued commands (real RCPT, probe RCPT, RSET) and resolves
+   * with the catch-all-aware verdict.
+   */
+  handleEnvelopeReply(code, line) {
+    if (this.dualPhase === "rcpt_real") {
+      this.realOutcome = classifyRcpt(code);
+      if (code === 552 || code === 452 || isOverQuota(line)) {
+        this.isCatchAllFlag = false;
+        if (this.dualPipelined) {
+          this.pendingDecision = { result: false, reason: "over_quota" };
+          this.dualPhase = "rcpt_probe";
+          return;
+        }
+        this.finish(false, "over_quota");
+        return;
+      }
+      if (this.realOutcome === "soft_reject") {
+        if (this.dualPipelined) {
+          this.pendingDecision = { result: null, reason: "temporary_failure" };
+          this.dualPhase = "rcpt_probe";
+          return;
+        }
+        this.finish(null, "temporary_failure");
+        return;
+      }
+      if (this.realOutcome === "hard_reject") {
+        const reason = isInvalidMailboxError(line) ? "not_found" : "ambiguous";
+        const result = reason === "not_found" ? false : null;
+        this.isCatchAllFlag = false;
+        if (this.dualPipelined) {
+          this.pendingDecision = { result, reason };
+          this.dualPhase = "rcpt_probe";
+          return;
+        }
+        this.finish(result, reason);
+        return;
+      }
+      if (this.dualPipelined) {
+        this.dualPhase = "rcpt_probe";
+      } else {
+        this.send(`RCPT TO:<${this.probeLocal}@${this.p.domain}>`);
+        this.dualPhase = "rcpt_probe";
+      }
+      return;
+    }
+    if (this.dualPhase === "rcpt_probe") {
+      this.probeOutcome = classifyRcpt(code);
+      if (this.dualPipelined) {
+        this.dualPhase = "rset";
+      } else {
+        this.send("RSET");
+        this.dualPhase = "rset";
+      }
+      return;
+    }
+    if (this.dualPhase === "rset") {
+      if (this.pendingDecision) {
+        this.finish(this.pendingDecision.result, this.pendingDecision.reason);
+        return;
+      }
+      this.decideDualProbe();
+      return;
+    }
+  }
+  /** Final decision after both RCPT outcomes are known. Catch-all only when both 250. */
+  decideDualProbe() {
+    if (this.realOutcome === "accept" && this.probeOutcome === "accept") {
+      this.isCatchAllFlag = true;
+      this.finish(true, "valid");
+    } else if (this.realOutcome === "accept") {
+      this.isCatchAllFlag = false;
+      this.finish(true, "valid");
+    } else if (this.realOutcome === "hard_reject") {
+      this.isCatchAllFlag = false;
+      this.finish(false, "not_found");
+    } else if (this.realOutcome === "soft_reject") {
+      this.finish(null, "temporary_failure");
+    } else {
+      this.finish(null, "ambiguous");
+    }
+  }
   finish(result, reason) {
     var _a, _b, _c;
     if (this.resolved)
@@ -1335,9 +1503,24 @@ class SMTPProbeConnection {
       return (_a2 = this.socket) === null || _a2 === void 0 ? void 0 : _a2.destroy();
     }, QUIT_DRAIN_MS);
     (_c = drain.unref) === null || _c === void 0 ? void 0 : _c.call(drain);
-    this.resolveFn({ result, transcript: this.transcript, commands: this.commands });
+    this.resolveFn({
+      result,
+      reason,
+      ...this.lastEnhancedStatus !== void 0 ? { enhancedStatus: this.lastEnhancedStatus } : {},
+      ...this.lastResponseCode !== void 0 ? { responseCode: this.lastResponseCode } : {},
+      ...this.isCatchAllFlag !== void 0 ? { isCatchAll: this.isCatchAllFlag } : {},
+      transcript: this.transcript,
+      commands: this.commands
+    });
   }
 }
+function classifyRcpt(code) {
+  if (code === 250 || code === 251)
+    return "accept";
+  if (code >= 400 && code < 500)
+    return "soft_reject";
+  return "hard_reject";
+}
 
 class ArrayTranscriptCollector {
   constructor() {
@@ -2010,12 +2193,11 @@ async function verifyEmail(params) {
   const skipMx = ((_f = params.skipMxForDisposable) !== null && _f !== void 0 ? _f : false) && result.isDisposable;
   const skipWhois = ((_g = params.skipDomainWhoisForDisposable) !== null && _g !== void 0 ? _g : false) && result.isDisposable;
   await runWhoisChecks(domain, params, result, skipWhois, log, collector);
-  if (((_h = params.verifyMx) !== null && _h !== void 0 ? _h : true) || ((_j = params.verifySmtp) !== null && _j !== void 0 ? _j : false)) {
-    if (skipMx) {
-      log(`[verifyEmail] skipping MX/SMTP for disposable: ${params.emailAddress}`);
-    } else {
-      await runMxAndSmtp(local, domain, params, result, log, collector);
-    }
+  const wantsMxOrSmtp = ((_h = params.verifyMx) !== null && _h !== void 0 ? _h : true) || ((_j = params.verifySmtp) !== null && _j !== void 0 ? _j : false);
+  if (wantsMxOrSmtp && skipMx) {
+    log(`[verifyEmail] skipping MX/SMTP for disposable: ${params.emailAddress}`);
+  } else if (wantsMxOrSmtp) {
+    await runMxAndSmtp(local, domain, params, result, log, collector);
   }
   result.metadata.verificationTime = Date.now() - startTime;
   if (captureTranscript)