mxprobe-core 0.1.0 → 0.2.1

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,MAAM,UAAU,WAAW,CAAI,OAAmB,EAAE,KAAa,EAAE,EAAU;IAC3E,IAAI,KAAiC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QAC/C,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,KAAK,qBAAqB,EAAE,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxF,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,SAAS,CAAC,GAAY;IACpC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;QAC7D,MAAM,IAAI,GAAI,GAA0B,CAAC,IAAI,CAAC;QAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;IAC5C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC"}

package/dist/verifier.d.ts

@@ -0,0 +1,26 @@
+import { type ResolvedOptions, type VerifierOptions } from "./options.ts";
+import type { Action, Summary, Verdict, VerifyResult } from "./types.ts";
+export declare const ACTIONS: Readonly<Record<Verdict, Action>>;
+export declare const VERDICTS: readonly Verdict[];
+export interface VerifierState {
+    /** True once a probe proved that port 25 is blocked (with autoDisableSmtp). */
+    smtpDown: boolean;
+    smtpDownWhy: string | null;
+}
+export interface Verifier {
+    verify(email: string): Promise<VerifyResult>;
+    verifyBatch(emails: readonly string[]): Promise<VerifyResult[]>;
+    readonly state: VerifierState;
+    readonly options: ResolvedOptions;
+}
+/**
+ * A verifier with shared limits. The hosted API keeps one for its lifetime so
+ * the SMTP concurrency cap holds across requests; the CLI makes one per run.
+ */
+export declare function createVerifier(opts?: VerifierOptions): Verifier;
+/** One-shot helpers. Each call gets its own limits. */
+export declare function verify(email: string, opts?: VerifierOptions): Promise<VerifyResult>;
+export declare function verifyBatch(emails: readonly string[], opts?: VerifierOptions): Promise<VerifyResult[]>;
+/** Summary counts for a batch: { send, hold, kill, total }. */
+export declare function summarize(results: readonly Pick<VerifyResult, "action">[]): Summary;
+//# sourceMappingURL=verifier.d.ts.map

package/dist/verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../src/verifier.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkB,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAE1F,OAAO,KAAK,EAAE,MAAM,EAAU,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGjF,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAA6D,CAAC;AACpH,eAAO,MAAM,QAAQ,EAAE,SAAS,OAAO,EAA0C,CAAC;AAyClF,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7C,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAChE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAcD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,eAAoB,GAAG,QAAQ,CAyCnE;AAED,uDAAuD;AACvD,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CAEvF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAE1G;AAED,+DAA+D;AAC/D,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,EAAE,GAAG,OAAO,CAInF"}

package/dist/verifier.js

@@ -0,0 +1,113 @@
+// The driver: syntax, then the DNS tier, then (with `smtp`) the probe, with
+// shared concurrency limits and the "port 25 is blocked" switch.
+import { parseAddress } from "./address.js";
+import { checkDomain } from "./dns.js";
+import { resolveOptions } from "./options.js";
+import { PORT_BLOCKED, probeMailbox } from "./smtp.js";
+import { errorMessage } from "./util.js";
+export const ACTIONS = Object.freeze({ OK: "send", WEAK: "hold", DEAD: "kill" });
+export const VERDICTS = Object.freeze(["OK", "WEAK", "DEAD"]);
+const RANK = { OK: 0, WEAK: 1, DEAD: 2 };
+function makeSemaphore(n) {
+    let active = 0;
+    const queue = [];
+    const next = () => {
+        if (active >= n)
+            return;
+        const run = queue.shift();
+        if (!run)
+            return;
+        active++;
+        run();
+    };
+    return (fn) => new Promise((res, rej) => {
+        queue.push(() => fn()
+            .then(res, rej)
+            .finally(() => {
+            active--;
+            next();
+        }));
+        next();
+    });
+}
+function result(email, verdict, reason, checks) {
+    return {
+        email,
+        action: ACTIONS[verdict],
+        verdict,
+        reason,
+        checks: { syntax: true, mx: null, smtp: "skipped", catch_all: null, ...checks },
+    };
+}
+// Try the primary MX, then the secondary when the primary cannot be reached at all.
+async function probeWithFallback(email, domain, mxHosts, o) {
+    let last = null;
+    for (const { host, ip } of mxHosts) {
+        const probe = await probeMailbox(email, domain, host, { ...o, connectHost: ip ?? host });
+        if (probe.smtp !== "unreachable")
+            return probe;
+        last = probe;
+        if (probe.connectError !== undefined && PORT_BLOCKED.has(probe.connectError))
+            return probe;
+    }
+    return last ?? { verdict: "WEAK", reason: "no MX host to probe", smtp: "unreachable", catchAll: null };
+}
+/**
+ * A verifier with shared limits. The hosted API keeps one for its lifetime so
+ * the SMTP concurrency cap holds across requests; the CLI makes one per run.
+ */
+export function createVerifier(opts = {}) {
+    const o = resolveOptions(opts);
+    const state = { smtpDown: false, smtpDownWhy: null };
+    const dnsLimit = makeSemaphore(o.dnsConcurrency);
+    const smtpLimit = makeSemaphore(o.smtpConcurrency);
+    async function verify(raw) {
+        const parsed = parseAddress(raw);
+        if (parsed.error !== undefined)
+            return result(parsed.email, "DEAD", parsed.error, { syntax: false });
+        const { email, domain } = parsed;
+        try {
+            const d = await dnsLimit(() => checkDomain(domain, o));
+            if (d.verdict === "DEAD")
+                return result(email, "DEAD", d.reason, { mx: null });
+            if (!o.smtp) {
+                const note = d.verdict === "OK" ? "; mailbox not probed" : "";
+                return result(email, d.verdict, `${d.reason}${note}`, { mx: d.mx });
+            }
+            if (state.smtpDown) {
+                return result(email, d.verdict, `${d.reason}; SMTP tier off for this run (${state.smtpDownWhy})`, { mx: d.mx, smtp: "unreachable" });
+            }
+            const probe = await smtpLimit(() => probeWithFallback(email, domain, d.mxHosts, o));
+            if (probe.connectError !== undefined && o.autoDisableSmtp && PORT_BLOCKED.has(probe.connectError)) {
+                state.smtpDown = true;
+                state.smtpDownWhy = `${probe.connectError} on ${d.mx}:${o.port}`;
+                return result(email, d.verdict, `${d.reason}; SMTP tier off for this run (${probe.connectError})`, { mx: d.mx, smtp: "unreachable" });
+            }
+            const verdict = RANK[probe.verdict] >= RANK[d.verdict] ? probe.verdict : d.verdict;
+            const reason = d.verdict === "WEAK" && probe.verdict === "OK" ? `${probe.reason}; ${d.reason}` : probe.reason;
+            return result(email, verdict, reason, { mx: d.mx, smtp: probe.smtp, catch_all: probe.catchAll });
+        }
+        catch (err) {
+            return result(email, "WEAK", `check did not finish (${errorMessage(err)})`, {});
+        }
+    }
+    function verifyBatch(emails) {
+        return Promise.all(emails.map((e) => verify(e)));
+    }
+    return { verify, verifyBatch, state, options: o };
+}
+/** One-shot helpers. Each call gets its own limits. */
+export function verify(email, opts = {}) {
+    return createVerifier(opts).verify(email);
+}
+export function verifyBatch(emails, opts = {}) {
+    return createVerifier(opts).verifyBatch(emails);
+}
+/** Summary counts for a batch: { send, hold, kill, total }. */
+export function summarize(results) {
+    const s = { send: 0, hold: 0, kill: 0, total: results.length };
+    for (const r of results)
+        s[r.action]++;
+    return s;
+}
+//# sourceMappingURL=verifier.js.map

package/dist/verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.js","sourceRoot":"","sources":["../src/verifier.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "mxprobe-core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "The MX Probe engine: DNS tier, SMTP probe and the send / hold / kill verdict contract. Zero dependencies.",
   "license": "MIT",
   "type": "module",
-  "main": "./src/index.mjs",
+  "main": "./dist/index.js",
   "exports": {
-    ".": "./src/index.mjs"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
     "src",
     "README.md"
   ],
@@ -30,8 +35,15 @@
     "ai-agent",
     "mcp"
   ],
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "^7.0.2"
+  },
+  "types": "./dist/index.d.ts",
   "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "test:live": "MXPROBE_LIVE=1 node --test test/*.live.mjs"
+    "build": "tsc -b",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "node --test test/*.test.ts",
+    "test:live": "MXPROBE_LIVE=1 node --test test/*.live.ts"
   }
 }

package/src/address.ts

@@ -0,0 +1,29 @@
+export interface ParsedAddress {
+  /** The address with the domain lowercased and the trailing dot removed. */
+  email: string;
+  local: string;
+  domain: string;
+  error?: undefined;
+}
+
+export interface AddressError {
+  email: string;
+  error: string;
+  local?: undefined;
+  domain?: undefined;
+}
+
+export type ParseResult = ParsedAddress | AddressError;
+
+/** Split an address into local part and domain, or return { email, error }. */
+export function parseAddress(raw: unknown): ParseResult {
+  const email = String(raw ?? "").trim();
+  const m = email.match(/^([^\s@]+)@([^\s@]+\.[^\s@]+)$/);
+  if (!m || m[1] === undefined || m[2] === undefined) return { email, error: "not an email address" };
+  const local = m[1];
+  const domain = m[2].toLowerCase().replace(/\.$/, "");
+  if (local.length > 64 || domain.length > 253 || /\.\./.test(domain) || /[^a-z0-9.-]/.test(domain)) {
+    return { email, error: "malformed address" };
+  }
+  return { email: `${local}@${domain}`, local, domain };
+}

package/src/api.ts

@@ -0,0 +1,45 @@
+// The hosted API's wire types. The server returns them, the `mxprobe` client
+// expects them. Types only: nothing here runs.
+import type { Summary, VerifyResult } from "./types.ts";
+
+/** Every error response: { error, message } plus route-specific extras. */
+export interface ApiErrorBody {
+  error: string;
+  message: string;
+  retry_after_seconds?: number;
+  credits_left?: number;
+  needed?: number;
+  checkout_hint?: string;
+  max?: number;
+}
+
+export interface SignupResponse {
+  api_key: string;
+  email: string;
+  credits: number;
+  mailed: boolean;
+  message: string;
+}
+
+export interface VerifyResponse {
+  results: VerifyResult[];
+  summary: Summary;
+  credits_used: number;
+  credits_left: number;
+}
+
+export interface BalanceResponse {
+  email: string;
+  credits: number;
+  checks_total: number;
+  created_at: string;
+}
+
+export interface CheckoutResponse {
+  url: string;
+  credits: number;
+  amount_usd: number;
+  packs: number;
+  session_id: string;
+  message: string;
+}

package/src/dns.ts

@@ -0,0 +1,118 @@
+// Tier 1: DNS. Free and local. Finds domains that cannot receive mail: no MX
+// and a web host behind the A record, a null MX, an MX that does not resolve,
+// a domain that does not exist, a parking host as MX.
+import { resolveOptions, type VerifierOptions } from "./options.ts";
+import type { MxRecord, Resolver, Verdict } from "./types.ts";
+import { errorCode, errorMessage, withTimeout } from "./util.ts";
+
+// MX hosts that forward rather than hold mail. They bounce when the forward
+// target is dead, and some refuse relays outright.
+const FORWARDER_MX: readonly RegExp[] = [
+  /registrar-servers\.com$/i, // Namecheap eforward1..5
+  /improvmx\.com$/i,
+  /forwardemail\.net$/i,
+  /mx\.cloudflare\.net$/i, // Cloudflare Email Routing route1..3
+  /fwd\d*\.porkbun\.com$/i,
+  /mailforward\./i,
+  /forwardmx\./i,
+];
+
+// Hosts that serve web pages, not mail. An MX pointing here times out.
+const WEBHOST_MX: readonly RegExp[] = [/pixie\.porkbun\.com$/i, /parkingcrew\./i, /sedoparking\./i, /bodis\./i, /above\.com$/i];
+
+export interface MxHost {
+  host: string;
+  /** Resolved for the primary; null for the secondary, which is resolved on demand. */
+  ip: string | null;
+}
+
+export interface DomainCheck {
+  verdict: Verdict;
+  reason: string;
+  /** The primary MX host name, or null when the domain is DEAD. */
+  mx: string | null;
+  /** The hosts to try in order. Empty when DEAD. */
+  mxHosts: MxHost[];
+}
+
+interface Addresses {
+  v4: string[];
+  v6: string[];
+  all: string[];
+}
+
+const isNullMx = (mx: readonly MxRecord[]): boolean => mx.length === 1 && mx[0]?.exchange === "" && mx[0]?.priority === 0;
+
+async function lookupAny(resolver: Resolver, host: string): Promise<Addresses> {
+  const [v4, v6] = await Promise.all([resolver.resolve4(host).catch(() => [] as string[]), resolver.resolve6(host).catch(() => [] as string[])]);
+  return { v4, v6, all: [...v4, ...v6] };
+}
+
+async function reverseName(resolver: Resolver, ip: string, ms: number): Promise<string | null> {
+  try {
+    const names = await withTimeout(resolver.reverse(ip), "reverse", ms);
+    return names[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Name the web host behind an A record from its IP and reverse name. */
+export function labelWebHost(ip: string, ptr: string | null): string {
+  const p = (ptr ?? "").toLowerCase();
+  if (ip === "75.2.60.5" || ip === "99.83.190.102" || p.includes("netlify")) return "Netlify";
+  if (ip.startsWith("76.76.21.") || ip.startsWith("216.198.79.") || p.includes("vercel")) return "Vercel";
+  if (ip.startsWith("104.21.") || ip.startsWith("172.67.") || ip.startsWith("188.114.9") || p.includes("cloudflare")) return "Cloudflare";
+  if (p.includes("amazonaws") || p.includes("awsglobalaccelerator")) return "AWS";
+  if (p.includes("github")) return "GitHub Pages";
+  if (p.includes("squarespace") || p.includes("wixdns") || p.includes("webflow")) return "site builder";
+  return ptr ?? "unknown host";
+}
+
+const dead = (reason: string): DomainCheck => ({ verdict: "DEAD", reason, mx: null, mxHosts: [] });
+
+/**
+ * The DNS tier for one domain. Returns the verdict, the primary MX host name
+ * (null when the domain is DEAD) and the sorted list of hosts to try.
+ */
+export async function checkDomain(domain: string, opts: VerifierOptions = {}): Promise<DomainCheck> {
+  const o = resolveOptions(opts);
+  const { resolver } = o;
+  let mx: MxRecord[];
+  try {
+    mx = await withTimeout(resolver.resolveMx(domain), "MX", o.dnsTimeoutMs);
+  } catch (err) {
+    const code = errorCode(err) ?? "";
+    if (code === "ENOTFOUND") return dead("domain does not exist (NXDOMAIN)");
+    if (code !== "ENODATA" && !/timed out/.test(errorMessage(err))) return dead(`MX lookup failed (${code || errorMessage(err)})`);
+    mx = [];
+  }
+
+  if (mx.length === 0) {
+    const ips = await withTimeout(lookupAny(resolver, domain), "A/AAAA", o.dnsTimeoutMs);
+    const ip = ips.all[0];
+    if (ip === undefined) return dead("no MX and no A/AAAA record");
+    const host = labelWebHost(ip, await reverseName(resolver, ip, o.dnsTimeoutMs));
+    return dead(`no MX record; mail falls back to the A record ${ip} (${host}), which does not take mail`);
+  }
+
+  if (isNullMx(mx)) return dead("null MX (RFC 7505): the domain accepts no mail");
+
+  const sorted = [...mx].sort((x, y) => x.priority - y.priority).map((r) => r.exchange.replace(/\.$/, "").toLowerCase());
+  const primary = sorted[0] as string;
+  const secondary = sorted[1];
+
+  if (WEBHOST_MX.some((re) => re.test(primary))) return dead(`MX ${primary} is a web or parking host, not a mail server`);
+
+  const primaryIps = await withTimeout(lookupAny(resolver, primary), "MX host", o.dnsTimeoutMs);
+  const primaryIp = primaryIps.v4[0] ?? primaryIps.v6[0];
+  if (primaryIp === undefined) return dead(`MX host ${primary} does not resolve`);
+
+  const mxHosts: MxHost[] = [{ host: primary, ip: primaryIp }];
+  if (secondary !== undefined && secondary !== primary) mxHosts.push({ host: secondary, ip: null });
+
+  if (FORWARDER_MX.some((re) => re.test(primary))) {
+    return { verdict: "WEAK", reason: `MX ${primary} is a forwarder; it bounces when the forward target is dead`, mx: primary, mxHosts };
+  }
+  return { verdict: "OK", reason: `MX ${primary}`, mx: primary, mxHosts };
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// MX Probe engine. Zero dependencies, Node 20+.
+//
+// Two tiers, run in order:
+//   1. DNS. Free and local. Finds domains that cannot receive mail: no MX and
+//      a web host behind the A record, a null MX, an MX that does not resolve,
+//      a domain that does not exist, a parking host as MX.
+//   2. SMTP probe. Connects to the MX on port 25, says EHLO and MAIL FROM,
+//      asks RCPT TO for the address and for a random local part (the catch-all
+//      test), then QUITs. No message is ever sent. Needs outbound port 25.
+//
+// The verdict contract, the same in the CLI, the MCP server and the API:
+//   { email, action, verdict, reason, checks: { syntax, mx, smtp, catch_all } }
+//   action  = send | hold | kill
+//   verdict = OK   | WEAK | DEAD
+//   `hold` never becomes `kill` on a refusal, a greylist or a catch-all. Only
+//   a 5xx that names the mailbox kills.
+
+import { createRequire } from "node:module";
+
+/** The package version, read from package.json so a bump is one edit there. */
+export const VERSION: string = (createRequire(import.meta.url)("../package.json") as { version: string }).version;
+
+export { parseAddress, type AddressError, type ParsedAddress, type ParseResult } from "./address.ts";
+export { checkDomain, labelWebHost, type DomainCheck, type MxHost } from "./dns.ts";
+export { DEFAULTS, resolveOptions, type ResolvedOptions, type VerifierOptions } from "./options.ts";
+export { probeMailbox, PORT_BLOCKED, type ProbeOptions, type ProbeResult, type ProbeSmtp } from "./smtp.ts";
+export { ACTIONS, VERDICTS, createVerifier, summarize, verify, verifyBatch, type Verifier, type VerifierState } from "./verifier.ts";
+export { errorMessage } from "./util.ts";
+export type { Action, Checks, MxRecord, Resolver, SmtpCheck, Summary, Verdict, VerifyResult } from "./types.ts";
+export type { ApiErrorBody, BalanceResponse, CheckoutResponse, SignupResponse, VerifyResponse } from "./api.ts";

package/src/options.ts

@@ -0,0 +1,51 @@
+import { promises as dnsPromises } from "node:dns";
+import type { Resolver } from "./types.ts";
+
+export interface VerifierOptions {
+  /** Run the SMTP probe after the DNS tier. Needs outbound port 25. */
+  smtp?: boolean;
+  dnsTimeoutMs?: number;
+  smtpTimeoutMs?: number;
+  smtpConcurrency?: number;
+  dnsConcurrency?: number;
+  /** The name given in EHLO. Its reverse DNS should match the probing IP. */
+  helo?: string;
+  /** The MAIL FROM address. */
+  from?: string;
+  port?: number;
+  /** Connect here instead of the MX host, for tests against a local server. */
+  hostOverride?: string | null;
+  /**
+   * When true, an ECONNREFUSED / EHOSTUNREACH / ENETUNREACH on a probe turns
+   * the SMTP tier off for the rest of the run: the network blocks port 25.
+   * The hosted API sets this to false because its port is proven by a health
+   * check, and one refusing MX must not switch the tier off for everyone.
+   */
+  autoDisableSmtp?: boolean;
+  resolver?: Resolver;
+}
+
+export type ResolvedOptions = Required<VerifierOptions>;
+
+export const DEFAULTS: Readonly<ResolvedOptions> = Object.freeze({
+  smtp: false,
+  dnsTimeoutMs: 8000,
+  smtpTimeoutMs: 12000,
+  smtpConcurrency: 3,
+  dnsConcurrency: 20,
+  helo: "probe.mxprobe.dev",
+  from: "probe@mxprobe.dev",
+  port: 25,
+  hostOverride: null,
+  autoDisableSmtp: true,
+  resolver: dnsPromises,
+});
+
+/** Defaults under the caller's options. An explicit `undefined` keeps the default. */
+export function resolveOptions(opts: VerifierOptions = {}): ResolvedOptions {
+  const out: Record<string, unknown> = { ...DEFAULTS };
+  for (const [key, value] of Object.entries(opts)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out as ResolvedOptions;
+}

package/src/smtp.ts

@@ -0,0 +1,172 @@
+// Tier 2: the SMTP probe. Connects to the MX on port 25, says EHLO and MAIL
+// FROM, asks RCPT TO for the address and for a random local part (the
+// catch-all test), then QUITs. No message is ever sent. Needs outbound port 25.
+import net from "node:net";
+import { randomBytes } from "node:crypto";
+import { resolveOptions, type VerifierOptions } from "./options.ts";
+import type { SmtpCheck, Verdict } from "./types.ts";
+import { errorCode, errorMessage, withTimeout } from "./util.ts";
+
+// Reply text that means "this mailbox does not exist", as opposed to "we do
+// not like you" (5.7.x) or "not now" (4xx).
+const NO_SUCH_MAILBOX =
+  /5\.1\.[0136]\b|5\.4\.1\b|user unknown|unknown user|does not exist|doesn't exist|no such (user|recipient|mailbox)|not found|not exist|no mailbox|invalid recipient|recipient rejected|recipient address rejected|unrouteable|unknown recipient|not our customer|mailbox unavailable|address rejected|invalid mailbox|unknown address/i;
+
+/** Connect errors that mean the network blocks port 25, not that one MX is down. */
+export const PORT_BLOCKED: ReadonlySet<string> = new Set(["ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH"]);
+
+export type ProbeSmtp = Exclude<SmtpCheck, "skipped">;
+
+export interface ProbeResult {
+  verdict: Verdict;
+  reason: string;
+  smtp: ProbeSmtp;
+  catchAll: boolean | null;
+  /** The connect error code when smtp is `unreachable`. */
+  connectError?: string;
+}
+
+export interface ProbeOptions extends VerifierOptions {
+  /** Connect to this address (the resolved MX IP) while naming mxHost in the reason. */
+  connectHost?: string;
+}
+
+interface Reply {
+  code: number;
+  /** All lines of a multi-line reply, joined with " | ". */
+  text: string;
+}
+
+interface SmtpSession {
+  read(): Promise<Reply>;
+  send(cmd: string): Promise<Reply>;
+  close(): void;
+}
+
+interface Waiter {
+  resolve(reply: Reply): void;
+  reject(err: Error): void;
+}
+
+const codedError = (message: string, code: string): NodeJS.ErrnoException => Object.assign(new Error(message), { code });
+
+// A line-oriented SMTP client: connect, then read() a reply or send(cmd) and
+// read its reply. Multi-line replies (250-... 250 ...) come back as one.
+function connectSmtp(host: string, port: number, timeoutMs: number): Promise<SmtpSession> {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ host, port });
+    socket.setEncoding("utf8");
+    socket.setTimeout(timeoutMs);
+    let buffer = "";
+    let lines: string[] = [];
+    const queued: Reply[] = [];
+    let waiter: Waiter | null = null;
+    let dead: Error | null = null;
+    let connected = false;
+
+    const fail = (err: Error): void => {
+      dead = dead ?? err;
+      if (waiter) {
+        const w = waiter;
+        waiter = null;
+        w.reject(err);
+      }
+      if (!connected) reject(err);
+      socket.destroy();
+    };
+    socket.on("timeout", () => fail(codedError("SMTP timeout", "ETIMEDOUT")));
+    socket.on("error", fail);
+    socket.on("close", () => fail(codedError("connection closed", "ECLOSED")));
+    socket.on("data", (chunk: string) => {
+      buffer += chunk;
+      let idx: number;
+      while ((idx = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, idx).replace(/\r$/, "");
+        buffer = buffer.slice(idx + 1);
+        lines.push(line);
+        if (/^\d{3}( |$)/.test(line)) {
+          const reply: Reply = { code: Number(line.slice(0, 3)), text: lines.join(" | ") };
+          lines = [];
+          if (waiter) {
+            const w = waiter;
+            waiter = null;
+            w.resolve(reply);
+          } else {
+            queued.push(reply);
+          }
+        }
+      }
+    });
+    const read = (): Promise<Reply> =>
+      new Promise((res, rej) => {
+        const next = queued.shift();
+        if (next) return res(next);
+        if (dead) return rej(dead);
+        waiter = { resolve: res, reject: rej };
+      });
+    const send = (cmd: string): Promise<Reply> => {
+      if (dead) return Promise.reject(dead);
+      socket.write(`${cmd}\r\n`);
+      return read();
+    };
+    socket.once("connect", () => {
+      connected = true;
+      resolve({ read, send, close: () => socket.destroy() });
+    });
+  });
+}
+
+const firstLine = (reply: Reply): string => reply.text.split(" | ")[0] ?? "";
+const refused = (reason: string): ProbeResult => ({ verdict: "WEAK", reason, smtp: "refused", catchAll: null });
+const deferred = (reason: string): ProbeResult => ({ verdict: "WEAK", reason, smtp: "deferred", catchAll: null });
+
+/**
+ * Probe one mailbox on one MX. `smtp` is accepted | rejected | refused |
+ * deferred | unreachable | dropped. Never sends DATA.
+ */
+export async function probeMailbox(email: string, domain: string, mxHost: string, opts: ProbeOptions = {}): Promise<ProbeResult> {
+  const o = resolveOptions(opts);
+  const target = o.hostOverride ?? opts.connectHost ?? mxHost;
+  let s: SmtpSession;
+  try {
+    s = await withTimeout(connectSmtp(target, o.port, o.smtpTimeoutMs), "connect", o.smtpTimeoutMs);
+  } catch (err) {
+    const code = errorCode(err) ?? "EUNKNOWN";
+    return { verdict: "WEAK", reason: `cannot connect to ${mxHost}:${o.port} (${code})`, smtp: "unreachable", catchAll: null, connectError: code };
+  }
+  try {
+    const banner = await s.read();
+    if (banner.code !== 220) return refused(`${mxHost} greeted with ${firstLine(banner)}`);
+    let r = await s.send(`EHLO ${o.helo}`);
+    if (r.code !== 250) {
+      r = await s.send(`HELO ${o.helo}`);
+      if (r.code !== 250) return refused(`${mxHost} refused HELO (${firstLine(r)})`);
+    }
+    r = await s.send(`MAIL FROM:<${o.from}>`);
+    if (r.code !== 250) {
+      return r.code >= 500 ? refused(`${mxHost} refused the sender (${firstLine(r)})`) : deferred(`${mxHost} deferred the sender (${firstLine(r)})`);
+    }
+    r = await s.send(`RCPT TO:<${email}>`);
+    let result: ProbeResult;
+    if (r.code === 250 || r.code === 251) {
+      const random = `${randomBytes(6).toString("hex")}-probe@${domain}`;
+      const c = await s.send(`RCPT TO:<${random}>`);
+      result =
+        c.code === 250 || c.code === 251
+          ? { verdict: "WEAK", reason: `${domain} is catch-all: ${mxHost} accepts any local part, so the mailbox cannot be proven`, smtp: "accepted", catchAll: true }
+          : { verdict: "OK", reason: `mailbox accepted by ${mxHost}`, smtp: "accepted", catchAll: false };
+    } else if (r.code >= 500 && NO_SUCH_MAILBOX.test(r.text)) {
+      result = { verdict: "DEAD", reason: `${mxHost} says the mailbox does not exist (${firstLine(r)})`, smtp: "rejected", catchAll: null };
+    } else if (r.code >= 500) {
+      result = refused(`${mxHost} refused the probe, not the mailbox (${firstLine(r)})`);
+    } else {
+      result = deferred(`${mxHost} deferred (${firstLine(r)})`);
+    }
+    await s.send("QUIT").catch(() => {});
+    return result;
+  } catch (err) {
+    return { verdict: "WEAK", reason: `${mxHost} dropped the session (${errorCode(err) ?? errorMessage(err)})`, smtp: "dropped", catchAll: null };
+  } finally {
+    s.close();
+  }
+}