@volter/world-core 3.0.164 → 3.0.166

package/dist/src/smtp-server.js

@@ -0,0 +1,160 @@
+/** A connection's bytes framed as SMTP frames them, each piece posted to the pack's front (`smtpFront`) through its
+ *  fetch with the session the connection carries: commands are lines ended by CRLF; after a 354, the message's lines up
+ *  to the lone dot, their leading dot removed; after a 334, one line of AUTH response. Pipelined commands are answered
+ *  in order. */
+export function smtpStream(fetch, bridge) {
+    return (sink, peer) => {
+        const encoder = new TextEncoder();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let session = bridge.fresh();
+        let mode = 'command';
+        let data = [];
+        let closed = false;
+        let chain = Promise.resolve();
+        const post = async (body) => {
+            if (closed)
+                return;
+            let a;
+            try {
+                const res = await fetch(new Request('http://smtp.wire/', { method: 'POST', headers: { 'content-type': 'application/json', [bridge.header]: bridge.key(), 'x-forwarded-for': peer }, body: JSON.stringify({ session, ...body }) }));
+                a = res.ok ? (await res.json()) : bridge.failure(session);
+                if (!Array.isArray(a.replies) || !a.session || !['command', 'data', 'auth'].includes(a.mode))
+                    a = bridge.failure(session);
+            }
+            catch {
+                a = bridge.failure(session);
+            }
+            session = a.session;
+            mode = a.mode;
+            sink.write(encoder.encode(a.replies.map((r) => `${r}\r\n`).join('')));
+            if (a.close) {
+                closed = true;
+                sink.end();
+            }
+        };
+        const line = async (text) => {
+            if (mode === 'data') {
+                if (text === '.') {
+                    const message = data.join('\r\n') + (data.length ? '\r\n' : '');
+                    data = [];
+                    mode = 'command';
+                    await post({ data: message });
+                    return;
+                }
+                data.push(text.startsWith('.') ? text.slice(1) : text);
+                return;
+            }
+            if (mode === 'auth') {
+                await post({ response: text });
+                return;
+            }
+            await post({ line: decoder.decode(Uint8Array.from(text, (c) => c.charCodeAt(0))) });
+        };
+        const pump = () => {
+            let at;
+            while ((at = buffer.indexOf('\r\n')) >= 0) {
+                const text = buffer.slice(0, at);
+                buffer = buffer.slice(at + 2);
+                chain = chain.then(() => line(text));
+            }
+        };
+        chain = chain.then(() => post({ open: true }));
+        return {
+            data(chunk) { if (closed)
+                return; buffer += Array.from(chunk, (b) => String.fromCharCode(b)).join(''); pump(); },
+            settled: () => chain,
+            close() { closed = true; },
+        };
+    };
+}
+/** The pack's front (its `around`): a request the stream signed with the pack's key is a piece of a connection, answered
+ *  by the pack's server; any other request is the pack's own (its doors and screens). */
+export async function smtpFront(ctx, next, bridge, server) {
+    const request = ctx.call.request;
+    if (!request.headers.has(bridge.header))
+        return next();
+    if (request.headers.get(bridge.header) !== bridge.key())
+        return new Response('not the server\'s wire', { status: 403 });
+    const w = (ctx.body ?? {});
+    const s = w.session ?? bridge.fresh();
+    if (w.open)
+        return Response.json(await server.open());
+    if (w.data !== undefined)
+        return Response.json(await server.data(s, w.data));
+    if (w.response !== undefined && server.response)
+        return Response.json(await server.response(s, w.response));
+    return Response.json(await server.command(s, String(w.line ?? '')));
+}
+/** A command's verb (upper-cased) and its argument. */
+export function smtpCommand(line) {
+    const [verb = '', ...rest] = line.split(' ');
+    return { verb: verb.toUpperCase(), arg: rest.join(' ') };
+}
+/** The session machine's word on a command from where a session stands (the manifest's states): a refusal's reply, or
+ *  undefined to go on. */
+export function smtpOrder(ctx, machine, stage, op, to) {
+    const refusal = ctx.legal(machine, 'stage', op, stage, to);
+    return refusal ? `${refusal.status} ${String(refusal.code)} ${refusal.message}` : undefined;
+}
+/** EHLO's multi-line 250 reply: the server's name, then each keyword. */
+// source: RFC 5321 §4.1.1.1 "ehlo-ok-rsp"
+export const smtpEhlo = (keywords) => keywords.map((k, i) => `250${i === keywords.length - 1 ? ' ' : '-'}${k}`);
+/** An address in angle brackets (`<a@b>`, `<>` for the null sender), or undefined when it is not one. */
+function smtpAddress(arg) {
+    const m = /^<([^<>\s]*)>$/.exec(arg.trim());
+    if (!m)
+        return undefined;
+    const a = m[1];
+    if (a === '')
+        return '';
+    return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(a) ? a : undefined;
+}
+/** An address's domain, lower-cased. */
+export const smtpDomain = (address) => address.slice(address.lastIndexOf('@') + 1).toLowerCase();
+/** MAIL's argument: the sender and its SIZE, BODY and SMTPUTF8 parameters, or why it is refused (the pack words it). */
+// source: RFC 5321 §4.1.1.2 "MAIL FROM:<reverse-path> [SP <mail-parameters> ] <CRLF>"
+export function smtpMailFrom(arg) {
+    const m = /^FROM:\s*(<[^>]*>)((?:\s+\S+)*)\s*$/i.exec(arg);
+    if (!m)
+        return { refused: 'syntax' };
+    const from = smtpAddress(m[1]);
+    if (from === undefined)
+        return { refused: 'sender' };
+    let size;
+    let smtputf8 = false;
+    for (const parameter of m[2].trim().split(/\s+/).filter(Boolean)) {
+        const [k = '', v] = parameter.split('=');
+        if (k.toUpperCase() === 'SIZE') {
+            if (!/^\d+$/.test(v ?? ''))
+                return { refused: 'size' };
+            size = Number(v);
+        }
+        else if (k.toUpperCase() === 'BODY' && ['7BIT', '8BITMIME'].includes((v ?? '').toUpperCase()))
+            continue;
+        else if (k.toUpperCase() === 'SMTPUTF8' && v === undefined)
+            smtputf8 = true;
+        else
+            return { refused: 'parameter', parameter };
+    }
+    return { from, ...(size !== undefined ? { size } : {}), smtputf8 };
+}
+/** RCPT's argument: the recipient, or why it is refused (the pack words it). */
+// source: RFC 5321 §4.1.1.3 "RCPT TO:<forward-path> [ SP <rcpt-parameters> ] <CRLF>"
+export function smtpRcptTo(arg) {
+    const m = /^TO:\s*(<[^>]*>)(?:\s+\S+)*\s*$/i.exec(arg);
+    if (!m)
+        return { refused: 'syntax' };
+    // source: RFC 5321 §4.1.1.11 "command, it will return code 555."
+    if (/^TO:\s*<[^>]*>\s+\S/i.test(arg))
+        return { refused: 'parameter', parameter: arg.slice(arg.indexOf('>') + 1).trim() };
+    const to = smtpAddress(m[1]);
+    return to ? { to } : { refused: 'recipient' };
+}
+/** A transaction's state cleared, the greeting kept (RSET, a new EHLO, the end of DATA): the session's `stage`,
+ *  `greeted` and an empty `rcpt`, with whatever of the session the pack keeps across transactions (`kept`). */
+// source: RFC 5321 §4.1.1.5 "This command specifies that the current mail transaction will be aborted."
+export function smtpCleared(s, stage, kept) {
+    const greeted = stage === 'helo' || stage === 'ehlo' ? stage : s.greeted;
+    return { ...kept, stage, rcpt: [], ...(greeted ? { greeted } : {}) };
+}

package/dist/src/smtp.d.ts

@@ -1,16 +1,34 @@
-/** Where a mail goes: the SMTP host and port, and the sender. */
-export type SmtpRoute = {
-    host: string;
-    port: number;
+import type { TwinStream } from './twin-fetch.js';
+/** 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;
-};
-/** One mail: its recipient, subject and HTML body. */
-export type Mail = {
-    to: 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;
+};
+/** 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;
 };
-/** 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 declare function sendMail(route: SmtpRoute, mail: Mail, headers?: Record<string, string>): Promise<void>;
+/** The mail servers this process answers itself, consulted before the instance's; returns those set before, which the
+ *  caller puts back. */
+export declare function setInProcessMailServers(servers: ReadonlyArray<InProcessMailServer>): ReadonlyArray<InProcessMailServer>;
+/** Hand one mail to each recipient's mailbox provider; every recipient's reply, in the order given. */
+export declare function sendMail(mail: Mail): Promise<MailReply[]>;
+export {};

package/dist/src/smtp.js

@@ -1,73 +1,242 @@
-// 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';
+let inProcessMailServers = [];
+/** 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) {
+    const previous = inProcessMailServers;
+    inProcessMailServers = servers;
+    return previous;
+}
+/** A connection to a server's listener. */
+async function socketWire(server) {
+    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((_, 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((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) {
+    let deliver;
+    let held = '';
+    let end;
+    const failed = new Promise((_, 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 {
-    socket;
+    wire;
     buffer = '';
     waiting = [];
-    constructor(socket) {
-        this.socket = socket;
-        socket.setEncoding('utf8');
-        socket.on('data', (chunk) => {
+    arrived = [];
+    constructor(wire) {
+        this.wire = wire;
+        wire.onData((chunk) => {
             this.buffer += chunk;
             let end;
             // 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() { return new Promise((resolve) => this.waiting.push(resolve)); }
-    async command(line, expect) {
+    reply() {
+        const held = this.arrived.shift();
+        return held ? Promise.resolve(held) : new Promise((resolve) => this.waiting.push(resolve));
+    }
+    send(data) {
         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;
-/** 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, mail, headers = {}) {
-    const [{ connect }, { worldEgressRefusal }] = await Promise.all([
-        import('node:net'),
-        import('../network-policy.cjs'),
-    ]);
-    // 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);
+/** RFC 6761's names, for which DNS answers no such domain. */
+const RESERVED = /(^|\.)(test|example|invalid|localhost)$/;
+const domainOf = (address) => address.slice(address.lastIndexOf('@') + 1).toLowerCase().replace(/\.$/, '');
+/** 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) {
+    const local = inProcessMailServers.find((server) => server.receives(domain));
+    if (local)
+        return local;
+    const { packFacts } = await import('../pack-facts.cjs');
+    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;
+    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 ?? {}) };
+    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, to) {
+    let text;
+    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, mail, recipients) {
+    const replies = new Map();
+    // a server whose connection cannot be opened answers every recipient a temporary failure (451), as a refused connect
+    let 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((_, reject) => { socket.once('error', reject); socket.once('close', () => reject(new Error('SMTP connection closed'))); });
-    failed.catch(() => { });
-    const step = (p) => Promise.race([p, failed]);
-    await step(new Promise((resolve) => { socket.once('connect', () => resolve()); }));
+    const step = (p) => Promise.race([p, wire.failed]);
+    const all = (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 = [];
+        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() { 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) {
+    const byDomain = new Map();
+    for (const to of mail.to)
+        byDomain.set(domainOf(to), [...(byDomain.get(domainOf(to)) ?? []), to]);
+    const replies = new Map();
+    for (const [domain, recipients] of byDomain) {
+        let server;
+        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));
 }