agent-inbox 0.2.2 → 0.2.4

package/src/mail/smtp-transport.ts

@@ -0,0 +1,589 @@
+/**
+ * Self-hosted SMTP MailTransport — the lightweight default backend.
+ *
+ * Inbound:  `smtp-server` listener. On DATA end the message is parsed, auth-
+ *           verified, attachments are stored, and the inbound handler is awaited
+ *           BEFORE the SMTP 250 is returned (commit-before-ACK). A handler throw
+ *           returns a 4xx/5xx so the peer MTA retries.
+ * Outbound: `nodemailer` (smarthost relay; direct-MX is future). SMTP responses
+ *           map to delivered/transient/permanent.
+ *
+ * smtp-server / nodemailer / mailparser / mailauth are OPTIONAL peer deps,
+ * loaded via dynamic import (mirrors src/map/map-client.ts). The transport
+ * throws a clear error from start()/send() if they are not installed.
+ *
+ * The pure classification/parsing helpers are exported for unit testing without
+ * the libraries or real sockets.
+ */
+
+import { ulid } from "ulid";
+import type {
+  MailTransport,
+  MailCapabilities,
+  MailTransportState,
+  MailHealth,
+  OutboundMail,
+  MailSendResult,
+  InboundMail,
+  InboundHandler,
+  InboundAuthResults,
+  InboundBounce,
+  AttachmentStore,
+} from "./types.js";
+
+export interface SmtpTransportOptions {
+  /** Inbound listener port (default 25). */
+  listenPort?: number;
+  /** Inbound bind host (default "0.0.0.0"). */
+  listenHost?: string;
+  /** Outbound smarthost relay. Required for sending in this phase. */
+  relay?: {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth?: { user: string; pass: string };
+  };
+  /** DKIM signing for outbound. */
+  dkim?: { domainName: string; keySelector: string; privateKey: string };
+  /** Max accepted inbound size, bytes (default 25 MiB). */
+  maxMessageBytes?: number;
+  /** Where to persist inbound attachment bytes. */
+  attachmentStore?: AttachmentStore;
+}
+
+const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+
+// Minimal structural stubs for the optional libs (avoid hard type deps).
+type SmtpServerLike = {
+  listen(port: number, host: string, cb: () => void): void;
+  close(cb: () => void): void;
+};
+type NodemailerLike = {
+  createTransport(opts: unknown): {
+    sendMail(msg: unknown): Promise<{ messageId?: string; response?: string }>;
+  };
+};
+
+export class SmtpTransport implements MailTransport {
+  readonly capabilities: MailCapabilities;
+  private _state: MailTransportState = "stopped";
+  private handler?: InboundHandler;
+  private server?: SmtpServerLike;
+  private mailer?: ReturnType<NodemailerLike["createTransport"]>;
+  /** Best-effort in-process idempotency for delivered sends (bounded). */
+  private delivered = new Set<string>();
+  private static readonly MAX_DELIVERED = 50_000;
+
+  constructor(private opts: SmtpTransportOptions) {
+    this.capabilities = {
+      outbound: opts.relay ? "relay" : "mx",
+      signsDkim: !!opts.dkim,
+      verifiesInboundAuth: true,
+      inbound: "listener",
+      maxMessageBytes: opts.maxMessageBytes ?? DEFAULT_MAX_BYTES,
+    };
+  }
+
+  get state(): MailTransportState {
+    return this._state;
+  }
+
+  onReceive(handler: InboundHandler): void {
+    this.handler = handler;
+  }
+
+  async health(): Promise<MailHealth> {
+    return { state: this._state };
+  }
+
+  async start(): Promise<void> {
+    if (this._state === "ready") return;
+    this._state = "starting";
+
+    const { SMTPServer } = await loadSmtpServer();
+    const maxBytes = this.capabilities.maxMessageBytes;
+
+    const server = new SMTPServer({
+      authOptional: true,
+      // TLS is expected to be terminated upstream (tunnel/relay) for the
+      // lightweight default; don't advertise the built-in self-signed cert.
+      hideSTARTTLS: true,
+      size: maxBytes,
+      onData: (
+        stream: NodeJS.ReadableStream & { sizeExceeded?: boolean },
+        session: SmtpSession,
+        callback: (err?: Error | null) => void
+      ) => {
+        // Guard the SMTP callback so it can fire at most once — smtp-server
+        // corrupts its protocol state if the data callback is invoked twice.
+        let acked = false;
+        const ack = (err?: Error | null) => {
+          if (acked) return;
+          acked = true;
+          callback(err);
+        };
+        this.onData(stream, session, ack).catch((err) => ack(err));
+      },
+    });
+
+    await new Promise<void>((resolve) => {
+      this.server = server as unknown as SmtpServerLike;
+      this.server.listen(
+        this.opts.listenPort ?? 25,
+        this.opts.listenHost ?? "0.0.0.0",
+        () => resolve()
+      );
+    });
+
+    this._state = "ready";
+  }
+
+  async stop(): Promise<void> {
+    this._state = "stopping";
+    if (this.server) {
+      await new Promise<void>((resolve) => this.server!.close(() => resolve()));
+      this.server = undefined;
+    }
+    this._state = "stopped";
+  }
+
+  async send(envelope: OutboundMail): Promise<MailSendResult> {
+    if (this._state !== "ready") {
+      throw new Error(`send() called while transport state is "${this._state}"`);
+    }
+    if (this.delivered.has(envelope.idempotencyKey)) {
+      return {
+        disposition: "delivered",
+        remoteMessageId: envelope.headers.messageId,
+        detail: "idempotent replay",
+      };
+    }
+    if (!this.opts.relay) {
+      throw new Error(
+        "SmtpTransport.send requires a relay; direct-MX is not yet implemented"
+      );
+    }
+
+    const mailer = await this.getMailer();
+    try {
+      const info = await mailer.sendMail(toNodemailerMessage(envelope, this.opts.dkim));
+      this.rememberDelivered(envelope.idempotencyKey);
+      return {
+        disposition: "delivered",
+        remoteMessageId: info.messageId ?? envelope.headers.messageId,
+        detail: info.response,
+      };
+    } catch (err) {
+      return smtpErrorToResult(err);
+    }
+  }
+
+  /** Record a delivered idempotency key, evicting the oldest when over cap. */
+  private rememberDelivered(key: string): void {
+    if (this.delivered.size >= SmtpTransport.MAX_DELIVERED) {
+      const oldest = this.delivered.values().next().value;
+      if (oldest !== undefined) this.delivered.delete(oldest);
+    }
+    this.delivered.add(key);
+  }
+
+  // -- inbound DATA handling ----------------------------------------------
+
+  private async onData(
+    stream: NodeJS.ReadableStream & { sizeExceeded?: boolean },
+    session: SmtpSession,
+    callback: (err?: Error | null) => void
+  ): Promise<void> {
+    const { simpleParser } = await loadMailparser();
+    const chunks: Buffer[] = [];
+    for await (const chunk of stream) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const raw = Buffer.concat(chunks);
+
+    if (stream.sizeExceeded) {
+      // Permanent: message too large.
+      callback(Object.assign(new Error("Message exceeds size limit"), { responseCode: 552 }));
+      return;
+    }
+
+    const parsed = await simpleParser(raw);
+    const auth = await this.verifyAuth(raw, session).catch(() => undefined);
+    const attachments = await this.storeAttachments(parsed);
+
+    const mailFrom = session.envelope?.mailFrom;
+    const mail = parsedToInboundMail(parsed, {
+      envelopeFrom: mailFrom ? mailFrom.address : "",
+      envelopeTo: (session.envelope?.rcptTo ?? []).map((r) => r.address),
+      remote: { ip: session.remoteAddress, reverseDns: session.clientHostname },
+      authResults: auth,
+      attachments,
+      sizeBytes: raw.length,
+    });
+
+    if (!this.handler) {
+      // No handler registered — refuse so the peer retries later.
+      callback(Object.assign(new Error("Not ready"), { responseCode: 451 }));
+      return;
+    }
+
+    try {
+      await this.handler(mail); // commit happens here
+      callback(); // ACK 250 only after the handler resolves
+    } catch (err) {
+      // NACK — transient by default so the sender retries.
+      callback(Object.assign(err instanceof Error ? err : new Error(String(err)), {
+        responseCode: 451,
+      }));
+    }
+  }
+
+  private async verifyAuth(
+    raw: Buffer,
+    session: SmtpSession
+  ): Promise<InboundAuthResults | undefined> {
+    const mailauth = await loadMailauth().catch(() => undefined);
+    if (!mailauth) return undefined;
+    const mailFrom = session.envelope?.mailFrom;
+    const res = await mailauth.authenticate(raw, {
+      ip: session.remoteAddress,
+      helo: session.hostNameAppearsAs,
+      sender: mailFrom ? mailFrom.address : undefined,
+    });
+    return mailauthToResults(res);
+  }
+
+  private async storeAttachments(parsed: ParsedMail): Promise<InboundMail["attachments"]> {
+    const store = this.opts.attachmentStore;
+    if (!store || !parsed.attachments?.length) return undefined;
+    const out: NonNullable<InboundMail["attachments"]> = [];
+    for (const a of parsed.attachments) {
+      const ref = await store.put(a.content, {
+        contentType: a.contentType,
+        filename: a.filename,
+      });
+      out.push({
+        filename: a.filename,
+        contentType: a.contentType,
+        contentId: a.cid,
+        contentRef: ref,
+        sizeBytes: a.size,
+      });
+    }
+    return out;
+  }
+
+  private async getMailer() {
+    if (this.mailer) return this.mailer;
+    const nodemailer = await loadNodemailer();
+    const secure = this.opts.relay!.secure ?? false;
+    this.mailer = nodemailer.createTransport({
+      host: this.opts.relay!.host,
+      port: this.opts.relay!.port,
+      secure,
+      // Plaintext relay (TLS terminated upstream): don't attempt a STARTTLS
+      // upgrade against a server that isn't offering a trusted cert.
+      ignoreTLS: !secure,
+      auth: this.opts.relay!.auth,
+    });
+    return this.mailer;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for unit tests)
+// ---------------------------------------------------------------------------
+
+interface SmtpSession {
+  remoteAddress?: string;
+  clientHostname?: string;
+  hostNameAppearsAs?: string;
+  envelope?: {
+    mailFrom?: { address: string } | false;
+    rcptTo?: Array<{ address: string }>;
+  };
+}
+
+interface ParsedAddress {
+  value: Array<{ address?: string; name?: string }>;
+}
+interface ParsedMail {
+  from?: ParsedAddress;
+  to?: ParsedAddress;
+  cc?: ParsedAddress;
+  subject?: string;
+  text?: string;
+  html?: string | false;
+  messageId?: string;
+  inReplyTo?: string;
+  references?: string | string[];
+  headers?: Map<string, unknown>;
+  date?: Date;
+  attachments?: Array<{
+    content: Buffer;
+    contentType: string;
+    filename?: string;
+    cid?: string;
+    size: number;
+  }>;
+}
+
+/** Map a nodemailer/SMTP send error to a classified result. */
+export function smtpErrorToResult(err: unknown): MailSendResult {
+  const e = err as { responseCode?: number; message?: string; response?: string };
+  const code = e?.responseCode;
+  if (typeof code === "number") {
+    if (code >= 500) {
+      return { disposition: "permanent", code, detail: e.response ?? e.message };
+    }
+    if (code >= 400) {
+      return { disposition: "transient", code, detail: e.response ?? e.message };
+    }
+  }
+  // No SMTP code (DNS/connection error) — transient, worth retrying.
+  return { disposition: "transient", detail: e?.message ?? "send failed" };
+}
+
+/** Build an InboundMail from mailparser output + session/transport context. */
+export function parsedToInboundMail(
+  parsed: ParsedMail,
+  ctx: {
+    envelopeFrom: string;
+    envelopeTo: string[];
+    remote?: { ip?: string; reverseDns?: string };
+    authResults?: InboundAuthResults;
+    attachments?: InboundMail["attachments"];
+    sizeBytes: number;
+  }
+): InboundMail {
+  const addrs = (a: ParsedAddress | undefined) =>
+    (a?.value ?? [])
+      .filter((v) => v.address)
+      .map((v) => ({ address: v.address!, name: v.name }));
+
+  const refs = parsed.references
+    ? Array.isArray(parsed.references)
+      ? parsed.references
+      : parsed.references.split(/\s+/).filter(Boolean)
+    : undefined;
+
+  const raw: Record<string, string | string[]> = {};
+  if (parsed.headers) {
+    for (const [k, v] of parsed.headers.entries()) {
+      raw[k.toLowerCase()] = typeof v === "string" ? v : String(v);
+    }
+  }
+
+  return {
+    envelopeFrom: ctx.envelopeFrom,
+    envelopeTo: ctx.envelopeTo,
+    from: addrs(parsed.from)[0] ?? { address: ctx.envelopeFrom },
+    to: addrs(parsed.to),
+    cc: addrs(parsed.cc),
+    subject: parsed.subject,
+    text: parsed.text,
+    html: typeof parsed.html === "string" ? parsed.html : undefined,
+    headers: {
+      messageId: parsed.messageId,
+      inReplyTo: parsed.inReplyTo,
+      references: refs,
+      raw,
+    },
+    attachments: ctx.attachments,
+    authResults: ctx.authResults,
+    remote: ctx.remote,
+    bounce: parseDsnFromParsed(parsed),
+    sizeBytes: ctx.sizeBytes,
+    receivedAt: (parsed.date ?? new Date()).toISOString(),
+  };
+}
+
+/**
+ * Detect and parse an RFC 3464 delivery-status notification (bounce) from
+ * mailparser output. A DSN is `multipart/report; report-type=delivery-status`,
+ * with a `message/delivery-status` part carrying per-recipient Action/Status/
+ * Diagnostic-Code, and usually a returned-message part bearing the original
+ * Message-ID. Returns undefined for ordinary mail.
+ */
+export function parseDsnFromParsed(parsed: ParsedMail): InboundBounce | undefined {
+  const contentType = headerString(parsed.headers, "content-type").toLowerCase();
+  // A real RFC 3464 DSN is multipart/report at the TOP level. Detecting on a
+  // delivery-status part alone would misclassify an ordinary email that merely
+  // *carries* a forwarded/attached bounce (top-level multipart/mixed) — a very
+  // common support-inbox scenario. Require the top-level report content-type.
+  const isReport =
+    contentType.includes("multipart/report") ||
+    contentType.includes("report-type=delivery-status");
+  if (!isReport) return undefined;
+
+  // The per-recipient delivery-status fields live in a `message/delivery-status`
+  // MIME part — but mailparser only surfaces that as an attachment when it
+  // carries `Content-Disposition: attachment`. The common Postfix/Gmail form
+  // omits that, and mailparser folds the block into the text body instead. So
+  // read from the attachment when present, else fall back to the parsed text.
+  const statusPart = (parsed.attachments ?? []).find((a) =>
+    a.contentType?.toLowerCase().includes("delivery-status")
+  );
+  const statusText = statusPart
+    ? statusPart.content.toString("utf8")
+    : parsed.text ?? "";
+
+  const field = (re: RegExp, text: string): string | undefined => {
+    const m = text.match(re);
+    return m ? m[1].trim() : undefined;
+  };
+
+  const actionRaw = field(/^Action:\s*([^\r\n]+)/im, statusText)?.toLowerCase();
+  const status = field(/^Status:\s*([0-9.]+)/im, statusText);
+  const diagnostic = field(/^Diagnostic-Code:\s*([^\r\n]+)/im, statusText);
+  const recipient =
+    addrFromField(field(/^Final-Recipient:\s*([^\r\n]+)/im, statusText)) ??
+    addrFromField(field(/^Original-Recipient:\s*([^\r\n]+)/im, statusText));
+
+  // The original Message-ID may appear in the returned message part (surfaced as
+  // an attachment) or be folded into the text (text/rfc822-headers form), or as
+  // an Original-Envelope-Id / X-Original-Message-ID field.
+  const rfc822 = (parsed.attachments ?? []).find((a) =>
+    a.contentType?.toLowerCase().includes("rfc822")
+  );
+  const originalMessageId =
+    (rfc822 &&
+      field(/^Message-ID:\s*(<[^>\r\n]+>)/im, rfc822.content.toString("utf8"))) ??
+    field(/^(?:X-Original-Message-ID|Original-Envelope-Id):\s*(<[^>\r\n]+>)/im, statusText) ??
+    field(/^Message-ID:\s*(<[^>\r\n]+>)/im, statusText) ??
+    undefined;
+
+  // If nothing actionable parsed out, this isn't a usable DSN — don't synthesize
+  // a meaningless bounce.
+  if (!actionRaw && !status && !recipient && !originalMessageId && !diagnostic) {
+    return undefined;
+  }
+
+  // Map Action / Status to our coarse disposition.
+  let action: InboundBounce["action"] = "failed";
+  if (actionRaw === "delayed" || status?.startsWith("4")) action = "delayed";
+  else if (actionRaw === "delivered" || actionRaw === "relayed" || actionRaw === "expanded")
+    action = "delivered";
+
+  return { action, recipient: recipient ?? "", status, originalMessageId, diagnostic };
+}
+
+function headerString(
+  headers: Map<string, unknown> | undefined,
+  key: string
+): string {
+  if (!headers) return "";
+  const v = headers.get(key);
+  if (typeof v === "string") return v;
+  if (v && typeof v === "object" && "value" in v) {
+    return String((v as { value: unknown }).value);
+  }
+  return v ? String(v) : "";
+}
+
+/** Extract the address from a DSN recipient field like "rfc822; user@host". */
+function addrFromField(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const semi = value.indexOf(";");
+  return (semi === -1 ? value : value.slice(semi + 1)).trim() || undefined;
+}
+
+/** Convert an OutboundMail to a nodemailer message object. */
+export function toNodemailerMessage(
+  env: OutboundMail,
+  dkim?: SmtpTransportOptions["dkim"]
+): Record<string, unknown> {
+  const addr = (a: { address: string; name?: string }) =>
+    a.name ? { name: a.name, address: a.address } : a.address;
+  return {
+    messageId: env.headers.messageId,
+    inReplyTo: env.headers.inReplyTo,
+    references: env.headers.references,
+    from: addr(env.from),
+    to: env.to.map(addr),
+    cc: env.cc?.map(addr),
+    bcc: env.bcc?.map(addr),
+    subject: env.subject,
+    text: env.text,
+    html: env.html,
+    attachments: env.attachments?.map((a) => ({
+      filename: a.filename,
+      contentType: a.contentType,
+      cid: a.contentId,
+    })),
+    ...(dkim ? { dkim } : {}),
+  };
+}
+
+interface MailauthResult {
+  spf?: { status?: { result?: string } };
+  dkim?: { results?: Array<{ status?: { result?: string } }> };
+  dmarc?: { status?: { result?: string } };
+}
+
+/** Normalize a mailauth authenticate() result into InboundAuthResults. */
+export function mailauthToResults(res: MailauthResult): InboundAuthResults {
+  const spf = (res.spf?.status?.result ?? "none").toLowerCase();
+  const dkim = (res.dkim?.results?.[0]?.status?.result ?? "none").toLowerCase();
+  const dmarc = (res.dmarc?.status?.result ?? "none").toLowerCase();
+  const spfVal: InboundAuthResults["spf"] =
+    spf === "pass" || spf === "fail" || spf === "softfail" || spf === "neutral"
+      ? (spf as InboundAuthResults["spf"])
+      : "none";
+  return {
+    spf: spfVal,
+    dkim: dkim === "pass" ? "pass" : dkim === "fail" ? "fail" : "none",
+    dmarc: dmarc === "pass" ? "pass" : dmarc === "fail" ? "fail" : "none",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Optional dynamic imports
+// ---------------------------------------------------------------------------
+
+async function dynImport<T>(spec: string): Promise<T> {
+  // Variable specifier keeps TypeScript from resolving the optional peer dep at
+  // compile time, while Node/the bundler resolves it at runtime.
+  return (await import(/* @vite-ignore */ spec)) as T;
+}
+
+async function loadSmtpServer(): Promise<{ SMTPServer: new (opts: unknown) => unknown }> {
+  try {
+    return await dynImport("smtp-server");
+  } catch {
+    throw new Error(
+      'SmtpTransport requires the optional "smtp-server" package. Install it to enable inbound mail.'
+    );
+  }
+}
+
+async function loadNodemailer(): Promise<NodemailerLike> {
+  try {
+    const mod = await dynImport<{ default?: NodemailerLike } & NodemailerLike>(
+      "nodemailer"
+    );
+    return mod.default ?? mod;
+  } catch {
+    throw new Error(
+      'SmtpTransport requires the optional "nodemailer" package. Install it to enable outbound mail.'
+    );
+  }
+}
+
+async function loadMailparser(): Promise<{
+  simpleParser: (input: Buffer) => Promise<ParsedMail>;
+}> {
+  try {
+    return await dynImport("mailparser");
+  } catch {
+    throw new Error(
+      'SmtpTransport requires the optional "mailparser" package. Install it to parse inbound mail.'
+    );
+  }
+}
+
+async function loadMailauth(): Promise<{
+  authenticate: (raw: Buffer, opts: unknown) => Promise<MailauthResult>;
+}> {
+  return await dynImport("mailauth");
+}