@sandsoftwaresolutions/mail-kit 0.0.0-stage → 0.1.1

package/dist/message.cjs

@@ -0,0 +1,194 @@
+"use strict";
+const { randomBytes } = require("node:crypto");
+
+const { encodeWords, formatAddress, formatAddressList, parseAddress, parseAddressList } = require("./address.cjs");
+const { MailError } = require("./errors.cjs");
+const { htmlToText } = require("./text.cjs");
+
+const RESERVED = new Set(["from", "to", "cc", "bcc", "subject", "date", "message-id", "mime-version", "content-type", "content-transfer-encoding", "reply-to", "sender", "return-path"]);
+const MAX_RECIPIENTS = 50;
+
+const fail = (message, code = "invalid_message") => new MailError(message, { code });
+
+/** Quoted-printable (RFC 2045) of a text: lines of at most 76 characters, CRLF line breaks. */
+function quotedPrintable(text) {
+  const bytes = Buffer.from(String(text).replace(/\r\n?|\n/g, "\n"), "utf8");
+  const lines = [];
+  let line = "";
+  let tokens = [];
+  const flush = () => {
+    if (tokens.length) {
+      const last = tokens[tokens.length - 1];
+      if (last === " " || last === "\t") tokens[tokens.length - 1] = "=" + last.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0");
+    }
+    let width = 0;
+    line = "";
+    for (const t of tokens) {
+      if (width + t.length > 75) {
+        lines.push(line + "=");
+        line = "";
+        width = 0;
+      }
+      line += t;
+      width += t.length;
+    }
+    lines.push(line);
+    tokens = [];
+  };
+  for (const b of bytes) {
+    if (b === 10) flush();
+    else if ((b >= 33 && b <= 126 && b !== 61) || b === 32 || b === 9) tokens.push(String.fromCharCode(b));
+    else tokens.push("=" + b.toString(16).toUpperCase().padStart(2, "0"));
+  }
+  flush();
+  return lines.join("\r\n");
+}
+
+const base64Lines = (buffer) => (buffer.toString("base64").match(/.{1,76}/g) ?? []).join("\r\n");
+const boundary = () => `=_ss_${randomBytes(12).toString("hex")}`;
+const needsEncoding = (name) => !/^[\x20-\x7e]*$/.test(name);
+const quote = (value) => `"${value.replace(/(["\\])/g, "\\$1")}"`;
+
+const extended = (name) => `UTF-8''${encodeURIComponent(name).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)}`;
+// ASCII names are plain quoted parameters; others use RFC 2231 (`name*=UTF-8''...`), which Gmail, Outlook, Apple Mail and Thunderbird read.
+const param = (key, name) => (needsEncoding(name) ? `${key}*=${extended(name)}` : `${key}=${quote(name)}`);
+
+function textPart(contentType, body) {
+  return `Content-Type: ${contentType}; charset=utf-8\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\n${quotedPrintable(body)}\r\n`;
+}
+
+function multipart(type, parts) {
+  const b = boundary();
+  return { header: `Content-Type: multipart/${type}; boundary="${b}"`, body: `${parts.map((p) => `--${b}\r\n${p}`).join("")}--${b}--\r\n` };
+}
+
+// A child part is a string that starts with its own headers (it is already a full MIME entity).
+const entity = (m) => `${m.header}\r\n\r\n${m.body}`;
+
+function attachmentPart(a) {
+  const disposition = a.cid ? "inline" : "attachment";
+  return (
+    `Content-Type: ${a.contentType}; ${param("name", a.filename)}\r\n` +
+    `Content-Transfer-Encoding: base64\r\n` +
+    `Content-Disposition: ${disposition}; ${param("filename", a.filename)}\r\n` +
+    (a.cid ? `Content-ID: <${a.cid}>\r\n` : "") +
+    `\r\n${base64Lines(a.content)}\r\n`
+  );
+}
+
+function checkHeaderValue(name, value) {
+  if (typeof value !== "string" || /[\r\n\0]/.test(value)) throw fail(`Header ${name} must be a single line of text`, "invalid_header");
+}
+
+function normalizeAttachment(a, index) {
+  if (!a || typeof a !== "object") throw fail(`attachments[${index}] must be an object`);
+  const content = typeof a.content === "string" ? Buffer.from(a.content, a.encoding === "base64" ? "base64" : "utf8") : a.content;
+  if (!Buffer.isBuffer(content) && !(content instanceof Uint8Array)) throw fail(`attachments[${index}].content must be a Buffer or string`);
+  const filename = String(a.filename ?? "").replace(/[\r\n\0/\\]/g, "_").trim();
+  if (!filename) throw fail(`attachments[${index}].filename is required`);
+  const contentType = String(a.contentType ?? "application/octet-stream");
+  if (!/^[\w.+-]+\/[\w.+-]+$/.test(contentType)) throw fail(`attachments[${index}].contentType is not valid`);
+  const cid = a.cid === undefined ? undefined : String(a.cid);
+  if (cid !== undefined && !/^[\w.@+-]{1,200}$/.test(cid)) throw fail(`attachments[${index}].cid is not valid`);
+  return { filename, content: Buffer.from(content), contentType, cid };
+}
+
+/**
+ * Checks and normalizes a message. The result has everything a transport needs, and `raw` (a Buffer with the
+ * complete RFC 5322 message) is built on first use.
+ */
+function prepareMessage(input, defaults = {}) {
+  if (!input || typeof input !== "object") throw fail("A message must be an object");
+  const merged = { ...defaults, ...input, headers: { ...defaults.headers, ...input.headers } };
+  const from = parseAddress(merged.from ?? (() => { throw fail("from is required", "missing_from"); })());
+  const to = parseAddressList(merged.to);
+  const cc = parseAddressList(merged.cc);
+  const bcc = parseAddressList(merged.bcc);
+  const replyTo = parseAddressList(merged.replyTo);
+  const unique = new Map();
+  for (const a of [...to, ...cc, ...bcc]) if (!unique.has(a.address.toLowerCase())) unique.set(a.address.toLowerCase(), a.address);
+  const total = new Set(unique.values());
+  if (!total.size) throw fail("At least one recipient (to, cc or bcc) is required", "no_recipients");
+  if (total.size > (merged.maxRecipients ?? MAX_RECIPIENTS)) throw fail(`Too many recipients (${total.size}); send in smaller batches or raise maxRecipients`, "too_many_recipients");
+
+  const subject = String(merged.subject ?? "").replace(/[\t ]+/g, " ").trim();
+  if (!subject) throw fail("subject is required", "missing_subject");
+  if (/[\r\n\0]/.test(subject)) throw fail("subject may not contain line breaks", "invalid_header");
+
+  let html = merged.html === undefined ? undefined : String(merged.html);
+  let text = merged.text === undefined ? undefined : String(merged.text);
+  if (html === undefined && text === undefined) throw fail("Give the message a text or html body", "empty_body");
+  if (text === undefined) text = htmlToText(html);
+
+  const attachments = (merged.attachments ?? []).map(normalizeAttachment);
+  const headers = {};
+  for (const [name, value] of Object.entries(merged.headers)) {
+    if (value === undefined || value === null) continue;
+    if (!/^[A-Za-z0-9-]{1,60}$/.test(name)) throw fail(`Header name not allowed: ${name.slice(0, 40)}`, "invalid_header");
+    if (RESERVED.has(name.toLowerCase())) throw fail(`Set ${name} with its own option, not in headers`, "invalid_header");
+    checkHeaderValue(name, String(value));
+    headers[name] = String(value);
+  }
+  if (merged.autoSubmitted !== false && !Object.keys(headers).some((n) => n.toLowerCase() === "auto-submitted")) headers["Auto-Submitted"] = "auto-generated";
+  if (merged.unsubscribe) {
+    const { url, mailto } = merged.unsubscribe;
+    const items = [];
+    if (url) {
+      if (!/^https:\/\/[^\s<>]+$/.test(url)) throw fail("unsubscribe.url must be an https URL", "invalid_header");
+      items.push(`<${url}>`);
+      headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
+    }
+    if (mailto) items.push(`<mailto:${parseAddress(mailto).address}>`);
+    if (!items.length) throw fail("unsubscribe needs a url or mailto", "invalid_header");
+    headers["List-Unsubscribe"] = items.join(", ");
+  }
+
+  const messageId = merged.messageId ?? `<${randomBytes(16).toString("hex")}@${from.address.split("@")[1]}>`;
+  if (!/^<[^<>\s@]+@[^<>\s@]+>$/.test(messageId)) throw fail("messageId must look like <id@domain>", "invalid_header");
+  const date = merged.date instanceof Date ? merged.date : new Date();
+  const envelopeFrom = merged.envelopeFrom ? parseAddress(merged.envelopeFrom).address : from.address;
+  const envelopeTo = [...total];
+
+  const message = {
+    from, to, cc, bcc, replyTo, subject, html, text, headers, attachments, messageId, date,
+    envelope: { from: envelopeFrom, to: envelopeTo },
+  };
+  let raw;
+  Object.defineProperty(message, "raw", { enumerable: false, get: () => (raw ??= buildRaw(message)) });
+  return message;
+}
+
+function buildRaw(m) {
+  const head = [];
+  head.push(`From: ${formatAddress(m.from)}`);
+  if (m.to.length) head.push(`To: ${formatAddressList(m.to)}`);
+  if (m.cc.length) head.push(`Cc: ${formatAddressList(m.cc)}`);
+  if (m.replyTo.length) head.push(`Reply-To: ${formatAddressList(m.replyTo)}`);
+  head.push(`Subject: ${encodeWords(m.subject)}`);
+  head.push(`Date: ${m.date.toUTCString().replace("GMT", "+0000")}`);
+  head.push(`Message-ID: ${m.messageId}`);
+  head.push("MIME-Version: 1.0");
+  for (const [name, value] of Object.entries(m.headers)) head.push(`${name}: ${encodeWords(value)}`);
+
+  const inline = m.attachments.filter((a) => a.cid);
+  const regular = m.attachments.filter((a) => !a.cid);
+  let body;
+  if (m.html === undefined) body = { header: null, text: m.text };
+  else {
+    const htmlEntity = inline.length
+      ? multipart("related", [textPart("text/html", m.html), ...inline.map(attachmentPart)])
+      : null;
+    const htmlPart = htmlEntity ? entity(htmlEntity) + "\r\n" : textPart("text/html", m.html);
+    body = multipart("alternative", [textPart("text/plain", m.text), htmlPart]);
+  }
+  let top;
+  if (regular.length) {
+    const first = body.header ? entity(body) + "\r\n" : textPart("text/plain", m.text);
+    top = multipart("mixed", [first, ...regular.map(attachmentPart)]);
+  } else if (body.header) top = body;
+  else top = { header: "Content-Type: text/plain; charset=utf-8\r\nContent-Transfer-Encoding: quoted-printable", body: `${quotedPrintable(m.text)}\r\n` };
+  return Buffer.from(`${head.join("\r\n")}\r\n${top.header}\r\n\r\n${top.body}`, "latin1");
+}
+
+exports.quotedPrintable = quotedPrintable;
+exports.prepareMessage = prepareMessage;

package/dist/preview.cjs

@@ -0,0 +1,15 @@
+"use strict";
+const { escapeHtml } = require("./text.cjs");
+
+/**
+ * One HTML page that shows a mail the way you want to review it: subject, the rendered mail (narrow and wide) and
+ * the plain-text version. Write it to a file and open it in a browser: `writeFileSync("mail.html", preview(mail))`.
+ */
+function preview(mail) {
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Preview: ${escapeHtml(mail.subject)}</title>
+<style>body{font:15px system-ui,sans-serif;margin:0;padding:24px;background:#e7eaee;color:#1f2933}h1{font-size:18px;margin:0 0 4px}.meta{color:#6b7785;margin:0 0 20px}.row{display:flex;gap:20px;flex-wrap:wrap;align-items:flex-start}iframe{border:0;background:#fff;box-shadow:0 1px 4px #0003;height:760px}pre{background:#fff;padding:16px;white-space:pre-wrap;max-width:560px;box-shadow:0 1px 4px #0003}</style></head><body>
+<h1>${escapeHtml(mail.subject)}</h1><p class="meta">HTML (wide and phone width) and the text version</p>
+<div class="row"><iframe style="width:680px" srcdoc="${escapeHtml(mail.html ?? "")}"></iframe><iframe style="width:380px" srcdoc="${escapeHtml(mail.html ?? "")}"></iframe><pre>${escapeHtml(mail.text)}</pre></div></body></html>`;
+}
+
+exports.preview = preview;

package/dist/smtp.cjs

@@ -0,0 +1,278 @@
+"use strict";
+const { hostname } = require("node:os");
+const { connect: netConnect } = require("node:net");
+const { connect: tlsConnect } = require("node:tls");
+
+const { MailError } = require("./errors.cjs");
+const { prepareMessage } = require("./message.cjs");
+
+const LOOPBACK = /^(localhost|127\.\d+\.\d+\.\d+|::1)$/;
+
+const networkError = (error, stage) => {
+  const code = error?.code;
+  if (code === "ERR_TLS_CERT_ALTNAME_INVALID" || /certificate|self.signed|unable to verify/i.test(error?.message ?? "")) {
+    return new MailError(`The mail server's certificate was refused: ${error.message}`, { code: "tls_failed", cause: error });
+  }
+  if (stage === "sent") {
+    return new MailError("The connection broke after the message was sent; it may or may not have been delivered", { code: "delivery_unknown", cause: error });
+  }
+  return new MailError(`Could not talk to the mail server (${code ?? error?.message ?? "error"})`, { code: "connection_failed", retryable: true, cause: error });
+};
+
+class Connection {
+  constructor(socket, timeoutMs) {
+    this.timeoutMs = timeoutMs;
+    this.stage = "connect";
+    this.bind(socket);
+  }
+
+  bind(socket) {
+    this.socket = socket;
+    this.buffer = "";
+    this.lines = [];
+    this.queue = [];
+    this.waiter = null;
+    this.failure = null;
+    socket.setTimeout(this.timeoutMs);
+    socket.on("data", (chunk) => this.onData(chunk));
+    socket.on("error", (error) => this.fail(networkError(error, this.stage)));
+    socket.on("close", () => this.fail(networkError(Object.assign(new Error("connection closed"), { code: "ECONNRESET" }), this.stage)));
+    socket.on("timeout", () => this.fail(this.stage === "sent"
+      ? new MailError("The mail server did not answer after the message was sent; it may or may not have been delivered", { code: "delivery_unknown" })
+      : new MailError("The mail server did not answer in time", { code: "timeout", retryable: true })));
+  }
+
+  onData(chunk) {
+    this.buffer += chunk.toString("latin1");
+    let index;
+    while ((index = this.buffer.indexOf("\n")) >= 0) {
+      const line = this.buffer.slice(0, index).replace(/\r$/, "");
+      this.buffer = this.buffer.slice(index + 1);
+      this.lines.push(line);
+      const match = /^(\d{3})([ -]?)/.exec(line);
+      if (!match) continue;
+      if (match[2] !== "-") {
+        this.queue.push({ code: Number(match[1]), lines: this.lines.map((l) => l.slice(4)), text: this.lines.map((l) => l.slice(4)).join("\n") });
+        this.lines = [];
+        this.flush();
+      }
+    }
+  }
+
+  flush() {
+    if (this.waiter && this.queue.length) {
+      const { resolve } = this.waiter;
+      this.waiter = null;
+      resolve(this.queue.shift());
+    }
+  }
+
+  fail(error) {
+    if (this.failure) return;
+    this.failure = error;
+    if (this.waiter) {
+      const { reject } = this.waiter;
+      this.waiter = null;
+      reject(error);
+    }
+  }
+
+  reply() {
+    if (this.queue.length) return Promise.resolve(this.queue.shift());
+    if (this.failure) return Promise.reject(this.failure);
+    return new Promise((resolve, reject) => (this.waiter = { resolve, reject }));
+  }
+
+  write(data) {
+    if (this.failure) return;
+    this.socket.write(data, "latin1");
+  }
+
+  async command(line, expect) {
+    this.write(`${line}\r\n`);
+    const reply = await this.reply();
+    if (expect && !expect.includes(reply.code)) throw replyError(reply, line.split(" ")[0]);
+    return reply;
+  }
+
+  destroy() {
+    this.socket.destroy();
+  }
+}
+
+function replyError(reply, command) {
+  const transient = reply.code >= 400 && reply.code < 500;
+  const auth = reply.code === 535 || reply.code === 534 || reply.code === 530 || reply.code === 454 || command === "AUTH";
+  const code = auth ? "auth_failed" : command === "RCPT" ? "recipient_rejected" : command === "MAIL" ? "sender_rejected" : transient ? "temporary_failure" : "rejected";
+  return new MailError(`Mail server answered ${reply.code} to ${command}: ${reply.text.slice(0, 200)}`, {
+    code,
+    retryable: transient && !auth,
+    responseCode: reply.code,
+    response: reply.text.slice(0, 500),
+  });
+}
+
+function parseCapabilities(reply) {
+  const caps = new Map();
+  for (const line of reply.lines.slice(1)) {
+    const [name, ...rest] = line.trim().split(/\s+/);
+    caps.set(name.toUpperCase(), rest.join(" "));
+  }
+  return caps;
+}
+
+function openSocket(o) {
+  return new Promise((resolve, reject) => {
+    const socket =
+      o.security === "tls"
+        ? tlsConnect({ host: o.host, port: o.port, servername: o.tls.servername ?? (LOOPBACK.test(o.host) ? undefined : o.host), ...o.tls })
+        : netConnect({ host: o.host, port: o.port });
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(new MailError(`Could not connect to ${o.host}:${o.port} in time`, { code: "timeout", retryable: true }));
+    }, o.timeoutMs);
+    socket.once(o.security === "tls" ? "secureConnect" : "connect", () => {
+      clearTimeout(timer);
+      socket.removeListener("error", onError);
+      resolve(socket);
+    });
+    const onError = (error) => {
+      clearTimeout(timer);
+      reject(networkError(error, "connect"));
+    };
+    socket.once("error", onError);
+  });
+}
+
+function upgrade(connection, o) {
+  return new Promise((resolve, reject) => {
+    const plain = connection.socket;
+    plain.removeAllListeners();
+    plain.setTimeout(0);
+    plain.on("error", () => {});
+    const secure = tlsConnect({ socket: plain, servername: o.tls.servername ?? (LOOPBACK.test(o.host) ? undefined : o.host), ...o.tls });
+    secure.once("secureConnect", () => resolve(secure));
+    secure.once("error", (error) => reject(networkError(error, "connect")));
+  });
+}
+
+async function openSession(o) {
+  const socket = await openSocket(o);
+  const c = new Connection(socket, o.timeoutMs);
+  try {
+    const hello = await c.reply();
+    if (hello.code !== 220) throw replyError(hello, "CONNECT");
+    let ehlo = await c.command(`EHLO ${o.clientName}`);
+    if (ehlo.code >= 500) ehlo = await c.command(`HELO ${o.clientName}`, [250]);
+    let caps = parseCapabilities(ehlo);
+    let secureNow = o.security === "tls";
+    if (o.security === "starttls") {
+      if (!caps.has("STARTTLS")) throw new MailError("The mail server does not offer STARTTLS, so the connection would not be encrypted. Use security: \"none\" only if you really want that.", { code: "tls_unavailable" });
+      await c.command("STARTTLS", [220]);
+      c.bind(await upgrade(c, o));
+      secureNow = true;
+      ehlo = await c.command(`EHLO ${o.clientName}`, [250]);
+      caps = parseCapabilities(ehlo);
+    }
+    if (o.user !== undefined) {
+      if (!secureNow && !o.allowInsecureAuth) throw new MailError("Refusing to send the password over an unencrypted connection", { code: "tls_unavailable" });
+      await authenticate(c, caps, o);
+    }
+    return { c, caps };
+  } catch (error) {
+    c.destroy();
+    throw error;
+  }
+}
+
+async function authenticate(c, caps, o) {
+  const offered = (caps.get("AUTH") ?? "").toUpperCase().split(/\s+/);
+  const b64 = (s) => Buffer.from(s, "utf8").toString("base64");
+  if (offered.includes("PLAIN")) {
+    await c.command(`AUTH PLAIN ${b64(`\0${o.user}\0${o.pass}`)}`, [235]);
+  } else if (offered.includes("LOGIN")) {
+    await c.command("AUTH LOGIN", [334]);
+    await c.command(b64(o.user), [334]);
+    await c.command(b64(o.pass), [235]);
+  } else {
+    throw new MailError(`The mail server offers no login method this package supports (it offers: ${offered.join(" ") || "none"})`, { code: "auth_failed" });
+  }
+}
+
+const dotStuff = (raw) => {
+  const text = raw.toString("latin1").replace(/(^|\r\n)\./g, "$1..");
+  return text.endsWith("\r\n") ? text : `${text}\r\n`;
+};
+
+/**
+ * Sends through any SMTP server (Zoho, Gmail, your own). Encrypted by default: port 465 uses TLS right away,
+ * other ports must offer STARTTLS or the send is refused. No dependencies.
+ */
+function smtpTransport(options = {}) {
+  const port = options.port ?? (options.security === "tls" ? 465 : 587);
+  const security = options.security ?? (port === 465 ? "tls" : "starttls");
+  if (!options.host || typeof options.host !== "string") throw new MailError("smtpTransport needs a host", { code: "invalid_config" });
+  if (!["tls", "starttls", "none"].includes(security)) throw new MailError('security must be "tls", "starttls" or "none"', { code: "invalid_config" });
+  if ((options.user === undefined) !== (options.pass === undefined)) throw new MailError("Give both user and pass, or neither", { code: "invalid_config" });
+  if (security === "none" && options.user !== undefined && !options.allowInsecureAuth) {
+    throw new MailError('A login over security: "none" would send the password unencrypted; set allowInsecureAuth: true to allow it', { code: "invalid_config" });
+  }
+  const o = {
+    host: options.host,
+    port,
+    security,
+    user: options.user,
+    pass: options.pass,
+    allowInsecureAuth: options.allowInsecureAuth === true,
+    timeoutMs: options.timeoutMs ?? 20_000,
+    clientName: String(options.clientName ?? (hostname().replace(/[^A-Za-z0-9.-]/g, "") || "localhost")),
+    tls: { ...options.tls },
+  };
+
+  const withSession = async (work) => {
+    const session = await openSession(o);
+    try {
+      return await work(session);
+    } finally {
+      session.c.write("QUIT\r\n");
+      setTimeout(() => session.c.destroy(), 200).unref();
+    }
+  };
+
+  return {
+    name: "smtp",
+    /** Opens a connection, encrypts it and logs in, then closes. Use it at startup to catch wrong settings early. */
+    verify: () => withSession(async () => true),
+    async send(input) {
+      const message = input.raw ? input : prepareMessage(input);
+      const raw = message.raw;
+      return withSession(async ({ c, caps }) => {
+        const limit = Number(caps.get("SIZE"));
+        if (limit > 0 && raw.length > limit) throw new MailError(`The message is ${raw.length} bytes; the server accepts at most ${limit}`, { code: "too_large" });
+        await c.command(`MAIL FROM:<${message.envelope.from}>`, [250]);
+        const accepted = [];
+        const rejected = [];
+        let lastError;
+        for (const to of message.envelope.to) {
+          const reply = await c.command(`RCPT TO:<${to}>`);
+          if (reply.code === 250 || reply.code === 251) accepted.push(to);
+          else {
+            rejected.push(to);
+            lastError = replyError(reply, "RCPT");
+          }
+        }
+        if (!accepted.length) throw lastError;
+        await c.command("DATA", [354]);
+        c.stage = "sent";
+        c.write(`${dotStuff(raw)}.\r\n`);
+        const done = await c.reply();
+        c.stage = "done";
+        if (done.code !== 250) throw replyError(done, "DATA");
+        const queued = /queued as ([\w.@-]+)|\bid[ =:]+([\w.@-]+)/i.exec(done.text);
+        return { id: queued?.[1] ?? queued?.[2] ?? message.messageId, messageId: message.messageId, accepted, rejected, response: done.text.slice(0, 500) };
+      });
+    },
+  };
+}
+
+exports.smtpTransport = smtpTransport;