mailifier 0.1.0

package/dist/smtp.js

@@ -0,0 +1,251 @@
+/**
+ * The SMTP handshake a paid verification service runs, from a host of yours.
+ *
+ * MX lookup → connect on 25 → EHLO → MAIL FROM → RCPT TO <the address> → QUIT. The
+ * server's answer to RCPT is the verdict: 250 accepted, 5xx no such user, 4xx "ask
+ * later" (greylisting). A second RCPT to a random local part tells catch-all domains
+ * apart from real acceptance. No DATA, so nothing is ever delivered.
+ *
+ * Honest limits: a catch-all domain (most Microsoft 365 tenants) says yes to anything,
+ * so the verdict is `catch_all`, not `valid`; an MX that will not talk to us is `risky`,
+ * never `invalid`. Both are what the paid services return too. Etiquette: one
+ * connection per MX at a time, a gap between probes, a HELO name whose forward and
+ * reverse DNS match, and MAIL FROM at that same name so a curious postmaster can look
+ * us up. Most clouds close outbound port 25 by default, so this usually runs on one host
+ * that can, with everything else asking that host over HTTP (`client.ts`, `server.ts`).
+ */
+import { randomBytes } from "node:crypto";
+import { createConnection } from "node:net";
+import { resolve as dohResolve } from "./dns.js";
+export const SMTP_PORT = 25;
+const CRLF = "\r\n";
+const DEFAULT_TIMEOUT_MS = 12_000;
+const MAX_MX_TRIED = 3;
+class SmtpReply extends Error {
+    code;
+    text;
+    constructor(code, text) {
+        super(`${code} ${text}`);
+        this.code = code;
+        this.text = text;
+        this.name = "SmtpReply";
+    }
+}
+const replyCode = (reply) => Number.parseInt(reply.slice(0, 3), 10);
+/**
+ * "No such user" in the words the big hosts use when the enhanced code is not 5.1.x:
+ * Microsoft 365 says "5.4.1 Recipient address rejected: Access denied", consumer
+ * Outlook "5.5.0 mailbox unavailable".
+ */
+const REJECTED_USER = /user unknown|no such user|does not exist|unknown user|recipient rejected|recipient address rejected|invalid recipient|no mailbox|mailbox not found|mailbox unavailable|address rejected/i;
+const replyClass = (code) => Math.floor(code / 100);
+/** RFC 3463 enhanced code carried in the text, e.g. "5.1.1". */
+const enhanced = (reply) => /\b([245])\.(\d{1,3})\.(\d{1,3})\b/.exec(reply);
+/**
+ * MX hosts in priority order (lowest number first), falling back to the domain's own A
+ * record when there is none, as mail does. Empty = nothing to connect to.
+ */
+export async function mailHosts(domain, resolver) {
+    const mx = (await resolver(domain, "MX"))
+        .map((rr) => {
+        const [priority, host] = rr.trim().split(/\s+/);
+        return { priority: Number(priority), host: (host ?? "").replace(/\.$/, "").toLowerCase() };
+    })
+        .filter((r) => r.host !== "" && r.host !== ".")
+        .sort((a, b) => a.priority - b.priority);
+    if (mx.length > 0)
+        return [...new Set(mx.map((r) => r.host))];
+    const a = await resolver(domain, "A");
+    return a.length > 0 ? [domain] : [];
+}
+/** Talk to one MX about one address. Throws SmtpReply for a refusal before RCPT, or a socket error. */
+async function converse(conv, email, opts, transcript) {
+    const step = async (line) => {
+        if (line !== null)
+            await conv.write(line);
+        const reply = await conv.read();
+        const code = replyCode(reply);
+        transcript.push({ sent: line, code, reply: reply.slice(0, 200) });
+        return { code, reply };
+    };
+    const expect = async (line, ok) => {
+        const r = await step(line);
+        if (r.code !== ok)
+            throw new SmtpReply(r.code, r.reply);
+        return r;
+    };
+    await expect(null, 220);
+    await expect(`EHLO ${opts.helo}`, 250);
+    await expect(`MAIL FROM:<${opts.mailFrom}>`, 250);
+    const rcpt = await step(`RCPT TO:<${email}>`);
+    let randomAccepted = null;
+    if (replyClass(rcpt.code) === 2) {
+        const domain = email.slice(email.lastIndexOf("@") + 1);
+        const probe = await step(`RCPT TO:<${opts.random()}@${domain}>`);
+        randomAccepted = replyClass(probe.code) === 2;
+    }
+    try {
+        await conv.write("QUIT");
+    }
+    catch {
+        // Already said what we needed.
+    }
+    conv.close();
+    return { code: rcpt.code, reply: rcpt.reply, randomAccepted };
+}
+/** Read the RCPT answer as a verdict. */
+function readRcpt(code, reply, randomAccepted) {
+    const klass = replyClass(code);
+    if (klass === 2) {
+        return randomAccepted
+            ? { result: "catch_all", reason: "catch_all" }
+            : { result: "valid", reason: "accepted" };
+    }
+    const enh = enhanced(reply);
+    if (klass === 5) {
+        // 5.1.x = bad mailbox/address: the definitive "no such user". Other 5xx (5.7.x
+        // policy, 554 blocked, 552 quota) say something about us or the box, not the address.
+        if (enh?.[2] === "1" || REJECTED_USER.test(reply))
+            return { result: "invalid", reason: "rejected" };
+        return { result: "risky", reason: "blocked" };
+    }
+    return { result: "risky", reason: "greylisted" };
+}
+/**
+ * Probe one address: the first MX that will talk decides. An MX that refuses us
+ * before RCPT (policy 5xx at EHLO/MAIL FROM) or cannot be reached is skipped for the
+ * next; when every one does, the verdict is risky, with the reason.
+ */
+export async function probeMailbox(email, opts) {
+    const resolver = opts.resolver ?? ((n, t) => dohResolve(n, t));
+    const dial = opts.dial ?? dialTcp;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const conv = {
+        helo: opts.helo,
+        mailFrom: opts.mailFrom ?? `postmaster@${opts.helo}`,
+        random: opts.random ?? (() => `wren-${randomBytes(6).toString("hex")}`),
+    };
+    const domain = email.slice(email.lastIndexOf("@") + 1).toLowerCase();
+    const hosts = await mailHosts(domain, resolver);
+    const transcript = [];
+    if (hosts.length === 0)
+        return { result: "invalid", reason: "no_mx", mx: null, code: null, transcript };
+    let lastReason = "unreachable";
+    for (const host of hosts.slice(0, MAX_MX_TRIED)) {
+        let session;
+        try {
+            session = await dial(host, SMTP_PORT, timeoutMs);
+        }
+        catch (err) {
+            transcript.push({ sent: null, code: 0, reply: `connect ${host}: ${errorName(err)}` });
+            lastReason = "unreachable";
+            continue;
+        }
+        try {
+            const { code, reply, randomAccepted } = await converse(session, email, conv, transcript);
+            return { ...readRcpt(code, reply, randomAccepted), mx: host, code, transcript };
+        }
+        catch (err) {
+            session.close();
+            if (err instanceof SmtpReply) {
+                // A greeting or envelope refusal: about us, not the address. Try the next MX.
+                lastReason = replyClass(err.code) === 4 ? "greylisted" : "blocked";
+                continue;
+            }
+            transcript.push({ sent: null, code: 0, reply: `${host}: ${errorName(err)}` });
+            lastReason = "unreachable";
+        }
+    }
+    return { result: "risky", reason: lastReason, mx: null, code: null, transcript };
+}
+const errorName = (err) => err instanceof Error
+    ? `${err.name}${err.code ? ` ${err.code}` : ""}`
+    : String(err);
+/** The real thing: a TCP socket read line by line, multi-line replies joined. */
+export const dialTcp = (host, port, timeoutMs) => new Promise((resolveConn, reject) => {
+    const socket = createConnection({ host, port });
+    let buffer = "";
+    let waiting = null;
+    const fail = (err) => {
+        if (waiting) {
+            waiting.reject(err);
+            waiting = null;
+        }
+        else
+            reject(err);
+        socket.destroy();
+    };
+    socket.setTimeout(timeoutMs, () => fail(Object.assign(new Error("smtp timeout"), { code: "ETIMEDOUT" })));
+    socket.on("error", fail);
+    socket.on("close", () => fail(Object.assign(new Error("closed"), { code: "ECONNRESET" })));
+    const pump = () => {
+        // A reply is complete when its last line has a space after the code ("250 ok"),
+        // continuation lines use a dash ("250-SIZE").
+        const lines = buffer.split(CRLF);
+        const end = lines.findIndex((l) => /^\d{3} /.test(l) || (l.length > 0 && /^\d{3}$/.test(l)));
+        if (end < 0 || !waiting)
+            return;
+        const reply = lines.slice(0, end + 1).join("\n");
+        buffer = lines.slice(end + 1).join(CRLF);
+        const w = waiting;
+        waiting = null;
+        w.resolve(reply);
+    };
+    socket.on("data", (chunk) => {
+        buffer += chunk.toString("latin1");
+        pump();
+    });
+    socket.once("connect", () => resolveConn({
+        read: () => new Promise((res, rej) => {
+            waiting = { resolve: res, reject: rej };
+            pump();
+        }),
+        write: (line) => new Promise((res, rej) => socket.write(`${line}${CRLF}`, (err) => (err ? rej(err) : res()))),
+        close: () => {
+            socket.removeAllListeners("close");
+            socket.end();
+            socket.destroy();
+        },
+    }));
+});
+/**
+ * The probe over `probeMailbox`, serialising per MX host with a gap between them: one
+ * conversation at a time with any given server, because we are a guest there.
+ */
+export class SmtpProbe {
+    opts;
+    name = "smtp";
+    lastByHost = new Map();
+    gapMs;
+    sleep;
+    constructor(opts) {
+        this.opts = opts;
+        this.gapMs = opts.perHostGapMs ?? 1_500;
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    }
+    async verify(email) {
+        const domain = email.slice(email.lastIndexOf("@") + 1).toLowerCase();
+        const resolver = this.opts.resolver ?? ((n, t) => dohResolve(n, t));
+        // The queue key is the primary MX: what we are actually about to knock on.
+        const key = (await mailHosts(domain, resolver))[0] ?? domain;
+        const previous = this.lastByHost.get(key) ?? Promise.resolve();
+        const turn = previous.then(async () => {
+            const outcome = await probeMailbox(email, { ...this.opts, resolver });
+            await this.sleep(this.gapMs);
+            return outcome;
+        });
+        this.lastByHost.set(key, turn.then(() => undefined, () => undefined));
+        const outcome = await turn;
+        return {
+            result: outcome.result,
+            raw: {
+                reason: outcome.reason,
+                mx: outcome.mx,
+                code: outcome.code,
+                helo: this.opts.helo,
+                transcript: outcome.transcript,
+            },
+        };
+    }
+}
+//# sourceMappingURL=smtp.js.map

package/dist/smtp.js.map

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

package/dist/verdict.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What a mailbox check can say, and the one interface every way of asking implements.
+ *
+ * Four answers, and the honest thing is that only two of them are facts:
+ *   valid      the mail server accepted the address; that server says the mailbox is there
+ *   invalid    the mail server refused it by name ("no such user"), or the domain takes no mail
+ *   catch_all  the domain accepts everything, so acceptance says nothing about this address
+ *   risky      nobody would tell us: greylisting, a refused connection, a policy block
+ *
+ * `raw` is the evidence behind the answer (which MX, which reply code, the transcript),
+ * kept so a verdict can be argued with later. It never holds a credential.
+ */
+export declare const MAILBOX_RESULTS: readonly ["valid", "invalid", "risky", "catch_all"];
+export type MailboxResult = (typeof MAILBOX_RESULTS)[number];
+export interface Verdict {
+    result: MailboxResult;
+    raw: Record<string, unknown>;
+}
+/**
+ * A way of asking whether a mailbox exists. `SmtpProbe` dials the mail server itself;
+ * `RemoteProbe` asks another host that can. Callers depend on this, not on either one.
+ *
+ * Deliberately not here: whether a verdict may be trusted, and whether it costs money.
+ * Those are the caller's policy about a probe, not something a probe knows about itself.
+ */
+export interface MailboxProbe {
+    readonly name: string;
+    verify(email: string): Promise<Verdict>;
+}

package/dist/verdict.js

@@ -0,0 +1,14 @@
+/**
+ * What a mailbox check can say, and the one interface every way of asking implements.
+ *
+ * Four answers, and the honest thing is that only two of them are facts:
+ *   valid      the mail server accepted the address; that server says the mailbox is there
+ *   invalid    the mail server refused it by name ("no such user"), or the domain takes no mail
+ *   catch_all  the domain accepts everything, so acceptance says nothing about this address
+ *   risky      nobody would tell us: greylisting, a refused connection, a policy block
+ *
+ * `raw` is the evidence behind the answer (which MX, which reply code, the transcript),
+ * kept so a verdict can be argued with later. It never holds a credential.
+ */
+export const MAILBOX_RESULTS = ["valid", "invalid", "risky", "catch_all"];
+//# sourceMappingURL=verdict.js.map

package/dist/verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.js","sourceRoot":"","sources":["../src/verdict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,CAAU,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "mailifier",
+  "version": "0.1.0",
+  "packageManager": "pnpm@9.15.0",
+  "description": "Ask a mail server whether an address exists, over SMTP, without sending anything.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "mailifier": "./dist/main.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "node scripts/clean.mjs && tsc -p tsconfig.build.json",
+    "bundle": "node scripts/bundle.mjs",
+    "prepare": "pnpm build && pnpm bundle",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run src",
+    "lint": "biome check .",
+    "prepublishOnly": "pnpm lint && pnpm typecheck && pnpm test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.14",
+    "@types/node": "22.20.3",
+    "esbuild": "0.28.2",
+    "tsx": "4.23.13",
+    "typescript": "5.9.3",
+    "vitest": "5.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wrenautomation/mailifier.git"
+  },
+  "homepage": "https://github.com/wrenautomation/mailifier#readme",
+  "bugs": {
+    "url": "https://github.com/wrenautomation/mailifier/issues"
+  },
+  "keywords": [
+    "email",
+    "verification",
+    "smtp",
+    "mailbox",
+    "deliverability",
+    "bounce",
+    "mx",
+    "rcpt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}