@volter/world-core 3.0.164 → 3.0.166

package/src/smtp.ts

@@ -1,77 +1,223 @@
-// A vendor's mail to a person, sent over SMTP (plain, no authentication) to the host the vendor's settings name — in a
-// World, the World's mail twin — as the vendor's own mailer sends it (GoTrue's confirmation and magic links). A handler
-// reaches it as `ctx.mail`. The World's egress rule is applied before the socket opens: a sealed World or one with a
-// network policy refuses a host outside it; a local World with neither lets a configured outside host be reached, as it
-// lets the application reach one. The socket is opened only when a mail is sent (nothing at import).
+// A vendor's mail handed to each recipient's mailbox provider (ADR 0032 §3), as a real relay or a real Resend hands mail
+// to the server of the recipient's domain. A handler reaches it as `ctx.mail`. The recipient's domain decides the server:
+// the World's twin whose descriptor names that domain (its host rules) and opens an SMTP side port (`sidePorts`, scheme
+// `smtp`), at the listener this boot recorded for it (`sides.<name>` in the instance file), or, for a twin this process
+// answers itself (a journey walk's companion, `setInProcessMailServers`), on its byte-stream door in process, as
+// vendorFetch reaches an in-process twin (vendor-call.ts). A domain no twin names is
+// refused here, never sent out of the World: a reserved name (RFC 6761: `.test`, `.example`, `.invalid`, `.localhost`) as
+// RFC 5321's non-existent domain, any other as a destination the World cannot route to. Every recipient gets its own
+// reply; nothing throws for a refusal. The socket is opened only when a mail is sent (nothing at import).
+import { twinOrigins, vendorsOfHost } from '../vendor-hosts.cjs';
+import type { TwinStream } from './twin-fetch.ts';
 
-/** Where a mail goes: the SMTP host and port, and the sender. */
-export type SmtpRoute = { host: string; port: number; from: string; senderName?: string };
-/** One mail: its recipient, subject and HTML body. */
-export type Mail = { to: string; subject: string; html: string };
+/** One mail, from its sender to its recipients: the sender's own message bytes, or a vendor's HTML mail the kernel
+ *  composes (GoTrue's links). */
+export type Mail = { from: string; to: string[] } & (
+  | { raw: Uint8Array | string }
+  | { senderName?: string; subject: string; html: string; headers?: Record<string, string> }
+);
+/** One recipient's answer: the receiving server's reply to its `RCPT`, or to the message when it accepted the
+ *  recipient; or the kernel's own refusal when no server receives the recipient's domain. */
+export type MailReply = { to: string; code: number; reply: string };
 
-type Socket = import('node:net').Socket;
+type Reply = { code: number; text: string };
 
+/** A mail server this process answers itself (a journey walk's companion over the walk's own World): its SMTP side
+ *  port's byte-stream door (`create<Name>TwinStream`), for the domains `receives` names (its host rules). */
+type InProcessMailServer = { vendor: string; receives: (domain: string) => boolean; stream: TwinStream };
+let inProcessMailServers: ReadonlyArray<InProcessMailServer> = [];
+
+/** The mail servers this process answers itself, consulted before the instance's; returns those set before, which the
+ *  caller puts back. */
+export function setInProcessMailServers(servers: ReadonlyArray<InProcessMailServer>): ReadonlyArray<InProcessMailServer> {
+  const previous = inProcessMailServers;
+  inProcessMailServers = servers;
+  return previous;
+}
+
+/** One connection to a server: bytes out, text in (latin1, one char per byte), and its end. */
+type Wire = { label: string; write(data: string): void; onData(fn: (chunk: string) => void): void; ready: Promise<void>; failed: Promise<never>; close(): void };
+
+/** A connection to a server's listener. */
+async function socketWire(server: { host: string; port: number }): Promise<Wire> {
+  const { connect } = await import('node:net');
+  const socket = connect(server.port, server.host);
+  socket.setEncoding('latin1');
+  socket.setTimeout(SMTP_TIMEOUT_MS, () => socket.destroy(new Error(`no answer in ${SMTP_TIMEOUT_MS} ms`)));
+  const failed = new Promise<never>((_, reject) => { socket.once('error', reject); socket.once('close', () => reject(new Error('connection closed'))); });
+  failed.catch(() => {});
+  return {
+    label: `${server.host}:${server.port}`, failed, close: () => socket.destroy(),
+    ready: new Promise<void>((resolve) => { socket.once('connect', () => resolve()); }),
+    write: (data) => { socket.write(Buffer.from(data, 'latin1')); },
+    onData: (fn) => { socket.on('data', fn); },
+  };
+}
+
+/** A connection to a server this process answers itself: its byte-stream door, handed the bytes as a listener would. */
+function streamWire(server: InProcessMailServer): Wire {
+  let deliver: ((chunk: string) => void) | undefined;
+  let held = '';
+  let end!: (error: Error) => void;
+  const failed = new Promise<never>((_, reject) => { end = reject; });
+  failed.catch(() => {});
+  // the door is opened before the timer starts, so a door that throws as it opens leaves nothing behind
+  const connection = server.stream({
+    write: (bytes) => { const text = Buffer.from(bytes).toString('latin1'); if (deliver) deliver(text); else held += text; },
+    end: () => end(new Error('connection closed')),
+  }, '127.0.0.1');
+  const timer = setTimeout(() => end(new Error(`no answer in ${SMTP_TIMEOUT_MS} ms`)), SMTP_TIMEOUT_MS);
+  return {
+    label: `${server.vendor} (in process)`, failed, ready: Promise.resolve(),
+    close: () => { clearTimeout(timer); connection.close(); },
+    write: (data) => connection.data(new Uint8Array(Buffer.from(data, 'latin1'))),
+    onData: (fn) => { deliver = fn; if (held) { const text = held; held = ''; fn(text); } },
+  };
+}
+
+/** The client's side of one connection. It owns every reply the server sends from the moment it reads the wire: a reply
+ *  that arrives before anything awaits it (a greeting a server sends as it opens) is kept, in order, for the next read. */
 class SmtpSession {
   private buffer = '';
-  private waiting: Array<(line: string) => void> = [];
-  constructor(private readonly socket: Socket) {
-    socket.setEncoding('utf8');
-    socket.on('data', (chunk: string) => {
+  private waiting: Array<(reply: Reply) => void> = [];
+  private arrived: Reply[] = [];
+  constructor(private readonly wire: Wire) {
+    wire.onData((chunk: string) => {
       this.buffer += chunk;
       let end: number;
       // a reply is complete at a line whose code is followed by a space (multi-line replies use a dash)
-      while ((end = this.buffer.search(/^\d{3} .*\r?\n/m)) >= 0) {
+      while ((end = this.buffer.search(/^\d{3}(?: .*)?\r?\n/m)) >= 0) {
         const lineEnd = this.buffer.indexOf('\n', end);
-        const reply = this.buffer.slice(0, lineEnd + 1);
+        const text = this.buffer.slice(0, lineEnd + 1).trim();
         this.buffer = this.buffer.slice(lineEnd + 1);
-        this.waiting.shift()?.(reply.trim().split(/\r?\n/).pop()!);
+        const reply = { code: Number(text.split(/\r?\n/).pop()!.slice(0, 3)), text: text.split(/\r?\n/).join('\n') };
+        const reader = this.waiting.shift();
+        if (reader) reader(reply); else this.arrived.push(reply);
       }
     });
   }
-  reply(): Promise<string> { return new Promise((resolve) => this.waiting.push(resolve)); }
-  async command(line: string, expect: number): Promise<void> {
+  reply(): Promise<Reply> {
+    const held = this.arrived.shift();
+    return held ? Promise.resolve(held) : new Promise((resolve) => this.waiting.push(resolve));
+  }
+  send(data: string): Promise<Reply> {
     const next = this.reply();
-    this.socket.write(`${line}\r\n`);
-    const reply = await next;
-    if (!reply.startsWith(String(expect))) throw new Error(`SMTP ${line.split(' ')[0]}: ${reply}`);
+    this.wire.write(data);
+    return next;
   }
 }
 
-/** How long a mail may take, connect to QUIT (a host that never answers must not hold the request open). */
+/** How long one server may take, connect to QUIT (a twin that never answers must not hold the request open). */
 const SMTP_TIMEOUT_MS = 10_000;
+/** RFC 6761's names, for which DNS answers no such domain. */
+const RESERVED = /(^|\.)(test|example|invalid|localhost)$/;
+
+const domainOf = (address: string): string => address.slice(address.lastIndexOf('@') + 1).toLowerCase().replace(/\.$/, '');
 
-/** Send one mail. Throws when it cannot be delivered (refused by the World's egress rule, unreachable, or refused by the
- *  server), so the vendor answers its own mailer failure. */
-export async function sendMail(route: SmtpRoute, mail: Mail, headers: Record<string, string> = {}): Promise<void> {
-  const [{ connect }, { worldEgressRefusal }] = await Promise.all([
-    import('node:net'),
-    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string, env?: NodeJS.ProcessEnv, method?: string) => string | null }>,
-  ]);
-  // sending mail is a write: an external relay needs a `writes` grant
-  const refusal = worldEgressRefusal(`http://${route.host}:${route.port}/`, process.env, 'SMTP');
-  if (refusal !== null) throw new Error(refusal);
-  const socket = connect(route.port, route.host);
-  socket.setTimeout(SMTP_TIMEOUT_MS, () => socket.destroy(new Error(`SMTP ${route.host}:${route.port}: no answer in ${SMTP_TIMEOUT_MS} ms`)));
-  const session = new SmtpSession(socket);
+/** The SMTP server of the World's twin that receives mail for `domain`, if one runs: one this process answers itself,
+ *  else the listener the instance records. */
+async function mailServerOf(domain: string): Promise<InProcessMailServer | { host: string; port: number } | undefined> {
+  const local = inProcessMailServers.find((server) => server.receives(domain));
+  if (local) return local;
+  const { packFacts } = await import('../pack-facts.cjs') as { packFacts: () => { packs: Record<string, { sidePorts?: Array<{ name: string; scheme?: string }> }> } };
+  const packs = packFacts().packs;
+  const receiving = vendorsOfHost(domain).flatMap((vendor) => {
+    const side = packs[vendor]?.sidePorts?.find((s) => s.scheme === 'smtp');
+    return side ? [{ vendor, side: side.name }] : [];
+  });
+  if (!receiving.length) return undefined;
+  const file = process.env.VOLTER_WORLD_INSTANCE;
+  if (!file) return undefined;
+  let instance: { env?: Record<string, string>; services?: Record<string, { url?: string; sides?: Record<string, { url: string }> }> };
+  try {
+    const { readFile } = await import('node:fs/promises');
+    instance = JSON.parse(await readFile(file, 'utf8'));
+  } catch { return undefined; }
+  const twins = { ...twinOrigins(process.env), ...twinOrigins(instance.env ?? {}) } as Record<string, string>;
+  for (const { vendor, side } of receiving) {
+    const origin = twins[vendor];
+    const service = origin === undefined ? undefined : Object.values(instance.services ?? {}).find((s) => s.url?.replace(/\/$/, '') === origin);
+    const at = service?.sides?.[side]?.url;
+    if (at) { const url = new URL(at); return { host: url.hostname, port: Number(url.port) }; }
+  }
+  return undefined;
+}
+
+/** The message's bytes as SMTP carries them after DATA: CRLF line ends, leading dots doubled, ended by `.`. */
+function dataOf(mail: Mail, to: string[]): string {
+  let text: string;
+  if ('raw' in mail) text = typeof mail.raw === 'string' ? Buffer.from(mail.raw, 'utf8').toString('latin1') : Buffer.from(mail.raw).toString('latin1');
+  else {
+    const from = mail.senderName ? `"${mail.senderName.replace(/"/g, '')}" <${mail.from}>` : mail.from;
+    text = Buffer.from([
+      `From: ${from}`, `To: ${to.join(', ')}`, `Subject: ${mail.subject}`, 'MIME-Version: 1.0', 'Content-Type: text/html; charset=utf-8',
+      ...Object.entries(mail.headers ?? {}).map(([k, v]) => `${k}: ${v}`), '', mail.html,
+    ].join('\r\n'), 'utf8').toString('latin1');
+  }
+  text = text.replace(/\r?\n/g, '\r\n');
+  if (!text.endsWith('\r\n')) text += '\r\n';
+  return `${text.replace(/(^|\r\n)\./g, '$1..')}.\r\n`;
+}
+
+/** One SMTP transaction with one server, for the recipients at its domains. */
+async function transfer(server: InProcessMailServer | { host: string; port: number }, mail: Mail, recipients: string[]): Promise<MailReply[]> {
+  const replies = new Map<string, Reply>();
+  // a server whose connection cannot be opened answers every recipient a temporary failure (451), as a refused connect
+  let wire: Wire;
+  try { wire = 'stream' in server ? streamWire(server) : await socketWire(server); }
+  catch (error) {
+    const label = 'stream' in server ? `${server.vendor} (in process)` : `${server.host}:${server.port}`;
+    return recipients.map((to) => ({ to, code: 451, reply: `451 4.4.1 ${label}: ${error instanceof Error ? error.message : String(error)}` }));
+  }
+  const session = new SmtpSession(wire);
   const greeting = session.reply();
-  const failed = new Promise<never>((_, reject) => { socket.once('error', reject); socket.once('close', () => reject(new Error('SMTP connection closed'))); });
-  failed.catch(() => {});
-  const step = <T>(p: Promise<T>): Promise<T> => Promise.race([p, failed]);
-  await step(new Promise<void>((resolve) => { socket.once('connect', () => resolve()); }));
+  const step = <T>(p: Promise<T>): Promise<T> => Promise.race([p, wire.failed]);
+  const all = (reply: Reply) => { for (const to of recipients) if (!replies.has(to)) replies.set(to, reply); };
   try {
-    if (!(await step(greeting)).startsWith('220')) throw new Error('SMTP: no greeting');
-    await step(session.command(`EHLO ${route.from.split('@')[1] ?? 'localhost'}`, 250));
-    await step(session.command(`MAIL FROM:<${route.from}>`, 250));
-    await step(session.command(`RCPT TO:<${mail.to}>`, 250));
-    await step(session.command('DATA', 354));
-    const from = route.senderName ? `"${route.senderName.replace(/"/g, '')}" <${route.from}>` : route.from;
-    const lines = [
-      `From: ${from}`, `To: ${mail.to}`, `Subject: ${mail.subject}`, 'MIME-Version: 1.0', 'Content-Type: text/html; charset=utf-8',
-      ...Object.entries(headers).map(([k, v]) => `${k}: ${v}`), '', ...mail.html.split(/\r?\n/).map((l) => (l.startsWith('.') ? `.${l}` : l)),
-    ];
-    await step(session.command(`${lines.join('\r\n')}\r\n.`, 250));
-    await step(session.command('QUIT', 221)).catch(() => {});
+    await step(wire.ready);
+    const hello = await step(greeting);
+    if (hello.code !== 220) { all(hello); return finish(); }
+    const ehlo = await step(session.send(`EHLO ${domainOf(mail.from) || 'localhost'}\r\n`));
+    if (ehlo.code !== 250) { all(ehlo); return finish(); }
+    const data = dataOf(mail, recipients);
+    // 8-bit bytes go only to a server that takes them (RFC 6152)
+    const eightBit = /[\x80-\xff]/.test(data) && /^250[ -]8BITMIME\b/im.test(ehlo.text) ? ' BODY=8BITMIME' : '';
+    const from = await step(session.send(`MAIL FROM:<${mail.from}>${eightBit}\r\n`));
+    if (from.code !== 250) { all(from); return finish(); }
+    const accepted: string[] = [];
+    for (const to of recipients) {
+      const rcpt = await step(session.send(`RCPT TO:<${to}>\r\n`));
+      if (rcpt.code === 250 || rcpt.code === 251) accepted.push(to); else replies.set(to, rcpt);
+    }
+    if (accepted.length) {
+      const ready = await step(session.send('DATA\r\n'));
+      all(ready.code === 354 ? await step(session.send(data)) : ready);
+    }
+    await step(session.send('QUIT\r\n')).catch(() => {});
+  } catch (error) {
+    all({ code: 451, text: `451 4.4.1 ${wire.label}: ${error instanceof Error ? error.message : String(error)}` });
   } finally {
-    socket.destroy();
+    wire.close();
+  }
+  return finish();
+  function finish(): MailReply[] { return recipients.map((to) => ({ to, code: replies.get(to)!.code, reply: replies.get(to)!.text })); }
+}
+
+/** Hand one mail to each recipient's mailbox provider; every recipient's reply, in the order given. */
+export async function sendMail(mail: Mail): Promise<MailReply[]> {
+  const byDomain = new Map<string, string[]>();
+  for (const to of mail.to) byDomain.set(domainOf(to), [...(byDomain.get(domainOf(to)) ?? []), to]);
+  const replies = new Map<string, MailReply>();
+  for (const [domain, recipients] of byDomain) {
+    let server: Awaited<ReturnType<typeof mailServerOf>>;
+    try { server = await mailServerOf(domain); }
+    catch (error) { for (const to of recipients) replies.set(to, { to, code: 451, reply: `451 4.4.1 ${domain}: ${error instanceof Error ? error.message : String(error)}` }); continue; }
+    const answered = server
+      ? await transfer(server, mail, recipients)
+      : recipients.map((to) => RESERVED.test(domain)
+        ? { to, code: 550, reply: `550 5.1.2 ${domain}: no such domain (a reserved name, RFC 6761)` }
+        : { to, code: 550, reply: `550 5.4.4 ${domain}: no twin in this World receives its mail` });
+    for (const reply of answered) replies.set(reply.to, reply);
   }
+  return mail.to.map((to) => replies.get(to)!);
 }