@midsummer-ai/sdk 0.0.0-stage → 0.1.0-next.1305

package/email/contract.d.mts

@@ -0,0 +1,11 @@
+import { Email } from "./index.mjs";
+//#region src/email/contract.d.ts
+declare const CONTRACT_DOMAIN = "mail.acme.dev";
+declare const CONTRACT_SUPPRESSED = "suppressed@example.com";
+interface ContractCase {
+  readonly name: string;
+  run(email: Email): Promise<void>;
+}
+declare const emailContract: ReadonlyArray<ContractCase>;
+//#endregion
+export { CONTRACT_DOMAIN, CONTRACT_SUPPRESSED, ContractCase, emailContract };

package/email/contract.mjs

@@ -0,0 +1,99 @@
+import { EmailError } from "./index.mjs";
+//#region src/email/contract.ts
+/**
+* Email's contract: what every engine promises, as cases any test runner can run. The Stand-in runs
+* them in this package; the real Capability runs the same cases against a Project set up with the
+* fixture: `mail.acme.dev` a verified Sending domain, and `suppressed@example.com` suppressed.
+*
+*   for (const c of emailContract) test(c.name, () => c.run(email(standIn({ domains: [CONTRACT_DOMAIN], suppressed: [CONTRACT_SUPPRESSED] }))))
+*/
+const CONTRACT_DOMAIN = "mail.acme.dev";
+const CONTRACT_SUPPRESSED = "suppressed@example.com";
+const emailContract = [
+	{
+		name: "a Message from a verified Sending domain is sent, and the same key sends it once",
+		async run(email) {
+			const message = {
+				from: "Acme <hi@mail.acme.dev>",
+				to: "ada@example.com",
+				subject: "Welcome",
+				text: "Hello",
+				key: "welcome-ada"
+			};
+			const first = await email.send(message);
+			equal(first.state, "sent", "the state");
+			equal(first.suppressed, [], "the suppressed");
+			equal((await email.send(message)).id, first.id, "the id of the same key sent again");
+			if ((await email.send({
+				...message,
+				key: "welcome-ada-2"
+			})).id === first.id) throw new Error("another key answered the first Message");
+		}
+	},
+	{
+		name: "a Message from an address off a verified Sending domain is refused as unverified",
+		async run(email) {
+			await refuses(() => email.send({
+				from: "hi@acme.dev",
+				to: "ada@example.com",
+				subject: "Hi",
+				text: "Hello"
+			}), "unverified");
+		}
+	},
+	{
+		name: "a suppressed recipient is left out and named; a Message with nobody left is suppressed",
+		async run(email) {
+			const some = await email.send({
+				from: "hi@mail.acme.dev",
+				to: ["Suppressed@example.com", "ada@example.com"],
+				subject: "Hi",
+				text: "Hello"
+			});
+			equal(some.state, "sent", "the state with someone left");
+			equal(some.suppressed, ["suppressed@example.com"], "the suppressed");
+			equal((await email.send({
+				from: "hi@mail.acme.dev",
+				to: "suppressed@example.com",
+				subject: "Hi",
+				text: "Hello"
+			})).state, "suppressed", "the state with nobody left");
+		}
+	},
+	{
+		name: "a Message that is not one is refused as invalid before it is sent",
+		async run(email) {
+			await refuses(() => email.send({
+				from: "hi@mail.acme.dev",
+				to: "not an address",
+				subject: "Hi",
+				text: "Hello"
+			}), "invalid");
+			await refuses(() => email.send({
+				from: "hi@mail.acme.dev",
+				to: [],
+				subject: "Hi",
+				text: "Hello"
+			}), "invalid");
+			await refuses(() => email.send({
+				from: "hi@mail.acme.dev",
+				to: "ada@example.com",
+				subject: "Hi"
+			}), "invalid");
+		}
+	}
+];
+function equal(actual, expected, what) {
+	if (JSON.stringify(actual) !== JSON.stringify(expected)) throw new Error(`${what}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+}
+async function refuses(call, code) {
+	try {
+		await call();
+	} catch (error) {
+		if (error instanceof EmailError && error.code === code) return;
+		throw new Error(`expected ${code}, got ${error instanceof Error ? error.message : String(error)}`);
+	}
+	throw new Error(`expected ${code}, but it was sent`);
+}
+//#endregion
+export { CONTRACT_DOMAIN, CONTRACT_SUPPRESSED, emailContract };

package/email/index.d.mts

@@ -0,0 +1,74 @@
+//#region src/email/index.d.ts
+/**
+ * Email from a Project's code: Messages sent from its verified Sending domains.
+ *
+ *   const mail = email(client("https://api.<site>", { key }))   // an Email key, from `midsummer email key create`
+ *   const sent = await mail.send({ from: "Acme <hi@mail.acme.dev>", to: "ada@example.com", subject: "Welcome", text: "Hello", key: "welcome-ada" })
+ *
+ * `engine` is where Messages go: the Stand-in (`@midsummer-ai/sdk/email/stand-in`) for `midsummer dev`,
+ * or the real Capability through `@midsummer-ai/sdk/email/client`. Every engine is held to the cases in
+ * `@midsummer-ai/sdk/email/contract`.
+ *
+ * Addresses and the Message's shape are checked here, before anything leaves the caller. Reuse a
+ * Message's `key` to retry while the original Message is retained for thirty days. After that
+ * Message is purged, the same key can send another Message. A suppressed recipient (one that bounced
+ * or complained) is left out and named in `suppressed`; a Message with nobody left is `suppressed`.
+ * Every failure is an `EmailError`, whose `code` tells you which kind.
+ *
+ * Delivery events reach a Project's webhooks signed; `verifyWebhook` checks a delivery.
+ */
+type EmailErrorCode = "invalid" | "unverified" | "forbidden" | "unavailable";
+declare class EmailError extends Error {
+  readonly code: EmailErrorCode;
+  constructor(code: EmailErrorCode, message: string);
+}
+/** An address is `ada@example.com` or `Ada <ada@example.com>`. */
+interface OutgoingMessage {
+  readonly from: string;
+  readonly to: string | ReadonlyArray<string>;
+  readonly cc?: ReadonlyArray<string>;
+  readonly bcc?: ReadonlyArray<string>;
+  readonly replyTo?: string;
+  readonly subject: string;
+  readonly text?: string;
+  readonly html?: string;
+  /**
+   * Reuse the key to retry while the original Message is retained for thirty days. After that
+   * Message is purged, the same key can send another Message.
+   */
+  readonly key?: string;
+}
+/** A Message as the engine took it: `to` always a list. */
+interface CheckedMessage extends Omit<OutgoingMessage, "to"> {
+  readonly to: ReadonlyArray<string>;
+}
+interface SentMessage {
+  readonly id: string;
+  /** `queued` while the send is still under way; `failed` when it was refused, with `error`. */
+  readonly state: "sent" | "queued" | "suppressed" | "failed";
+  readonly suppressed: ReadonlyArray<string>;
+  readonly error?: string;
+}
+/** Where Messages go: the Seam under `email()`. The Stand-in and the real Capability are its Adapters. */
+interface EmailEngine {
+  send(message: CheckedMessage): Promise<SentMessage>;
+}
+interface Email {
+  send(message: OutgoingMessage): Promise<SentMessage>;
+}
+/** The bare address of `Ada <ada@acme.dev>` or `ada@acme.dev`, lowercase; `invalid` when it is none. */
+declare function addressOf(value: string): string;
+/** At most this many recipients, to, cc and bcc together. */
+declare const MAX_RECIPIENTS = 50;
+declare function email(engine: EmailEngine): Email;
+/**
+ * Whether a webhook delivery is genuine: its `Midsummer-Signature` header (`t=<ms>,v1=<hex>`) is the
+ * HMAC-SHA256 of `<t>.<body>` under the webhook's secret, made within `toleranceMs` (five minutes) of
+ * `now`. Pass the body exactly as it arrived. Deliveries are at least once: dedupe by `Midsummer-Event-Id`.
+ */
+declare function verifyWebhook(secret: string, signature: string | null, body: string, options?: {
+  readonly now?: number;
+  readonly toleranceMs?: number;
+}): Promise<boolean>;
+//#endregion
+export { CheckedMessage, Email, EmailEngine, EmailError, EmailErrorCode, MAX_RECIPIENTS, OutgoingMessage, SentMessage, addressOf, email, verifyWebhook };

package/email/index.mjs

@@ -0,0 +1,59 @@
+//#region src/email/index.ts
+var EmailError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "EmailError";
+	}
+};
+const ADDRESS = /^[^\s@<>()",;:]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+/** The bare address of `Ada <ada@acme.dev>` or `ada@acme.dev`, lowercase; `invalid` when it is none. */
+function addressOf(value) {
+	const bare = (/<([^<>]+)>\s*$/.exec(value)?.[1] ?? value).trim().toLowerCase();
+	if (!ADDRESS.test(bare) || bare.length > 254) throw new EmailError("invalid", `${value} is not an email address`);
+	return bare;
+}
+/** At most this many recipients, to, cc and bcc together. */
+const MAX_RECIPIENTS = 50;
+function email(engine) {
+	return { async send(message) {
+		const to = typeof message.to === "string" ? [message.to] : [...message.to];
+		if (!to.length) throw new EmailError("invalid", "a Message needs someone to send to");
+		const all = [
+			message.from,
+			...to,
+			...message.cc ?? [],
+			...message.bcc ?? [],
+			...message.replyTo ? [message.replyTo] : []
+		];
+		all.forEach(addressOf);
+		if (all.length - 1 - (message.replyTo ? 1 : 0) > 50) throw new EmailError("invalid", `a Message goes to at most 50 recipients`);
+		if (!message.subject.trim()) throw new EmailError("invalid", "a Message needs a subject");
+		if (message.text === void 0 && message.html === void 0) throw new EmailError("invalid", "a Message needs text or html");
+		return engine.send({
+			...message,
+			to
+		});
+	} };
+}
+const encoder = new TextEncoder();
+/**
+* Whether a webhook delivery is genuine: its `Midsummer-Signature` header (`t=<ms>,v1=<hex>`) is the
+* HMAC-SHA256 of `<t>.<body>` under the webhook's secret, made within `toleranceMs` (five minutes) of
+* `now`. Pass the body exactly as it arrived. Deliveries are at least once: dedupe by `Midsummer-Event-Id`.
+*/
+async function verifyWebhook(secret, signature, body, options = {}) {
+	const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(signature ?? "");
+	if (!match) return false;
+	const at = Number(match[1]);
+	if (Math.abs((options.now ?? Date.now()) - at) > (options.toleranceMs ?? 3e5)) return false;
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["verify"]);
+	const given = new Uint8Array(match[2].match(/../g).map((pair) => parseInt(pair, 16)));
+	return crypto.subtle.verify("HMAC", key, given, encoder.encode(`${at}.${body}`));
+}
+//#endregion
+export { EmailError, MAX_RECIPIENTS, addressOf, email, verifyWebhook };

package/email/smtp.d.mts

@@ -0,0 +1,22 @@
+import { CheckedMessage, SentMessage } from "./index.mjs";
+//#region src/email/smtp.d.ts
+/** A `send` that hands each message to Email at `origin` (the API's), with the client's key. */
+declare function relayTo(origin: string, options?: {
+  readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
+}): (key: string, message: CheckedMessage) => Promise<SentMessage>;
+declare function serveSmtp(options: {
+  readonly port: number;
+  readonly hostname?: string;
+  /** The name it greets with. */
+  readonly name?: string;
+  readonly send: (key: string, message: CheckedMessage) => Promise<SentMessage>;
+  readonly tls?: {
+    readonly key: string;
+    readonly cert: string;
+  };
+}): Promise<{
+  readonly port: number;
+  close(): Promise<void>;
+}>;
+//#endregion
+export { relayTo, serveSmtp };

package/email/smtp.mjs

@@ -0,0 +1,296 @@
+import { EmailError, email } from "./index.mjs";
+import { client } from "./client.mjs";
+import { createServer } from "node:net";
+import { createServer as createServer$1 } from "node:tls";
+//#region src/email/smtp.ts
+/**
+* Email for clients that speak only SMTP: a relay that takes mail by SMTP, signed in with an Email key
+* as the password (username `midsummer`), and sends each message through Email's wire, as the SDK's
+* client does. It keeps nothing, so any number of them can run anywhere that can reach the API.
+*
+*   const relay = await serveSmtp({ port: 587, send: relayTo("https://api.<site>"), tls: { key, cert } })
+*
+* It speaks EHLO, AUTH PLAIN and LOGIN, MAIL, RCPT, DATA, RSET, NOOP and QUIT. With `tls` every
+* connection is TLS from its first byte (implicit TLS, as on port 465); without it, AUTH is taken only
+* from this computer, so a key never crosses a network in the clear. The message's `To` and `Cc`
+* recipients that the envelope names are its to and cc, and the envelope's others its bcc (a message
+* naming none of them goes to each blind recipient alone); its `Message-ID` is the Message's key, so a client sending it again sends it once. Its text and HTML
+* parts are read from plain, multipart, quoted-printable and base64 bodies.
+*
+* Email's refusals come back as SMTP replies: an unknown key `535`, a sender off a verified Sending
+* domain `550`, anything not a Message `554`, and Email out of reach `451`, which a client tries again.
+*/
+/** At most this many bytes of message. */
+const MAX_BYTES = 2e6;
+/** A `send` that hands each message to Email at `origin` (the API's), with the client's key. */
+function relayTo(origin, options = {}) {
+	return (key, message) => email(client(origin, {
+		key,
+		...options.fetch ? { fetch: options.fetch } : {}
+	})).send(message);
+}
+async function serveSmtp(options) {
+	const name = options.name ?? "midsummer";
+	const handle = (socket) => session(socket, {
+		name,
+		send: options.send,
+		secure: Boolean(options.tls)
+	});
+	const server = options.tls ? createServer$1({
+		key: options.tls.key,
+		cert: options.tls.cert
+	}, handle) : createServer(handle);
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(options.port, options.hostname ?? "127.0.0.1", () => resolve());
+	});
+	const address = server.address();
+	return {
+		port: typeof address === "object" && address ? address.port : options.port,
+		close: () => new Promise((resolve) => server.close(() => resolve()))
+	};
+}
+/** Whether a connection is from this computer, where a key may cross without TLS. */
+const local = (socket) => [
+	"127.0.0.1",
+	"::1",
+	"::ffff:127.0.0.1"
+].includes(socket.remoteAddress ?? "");
+function session(socket, options) {
+	let buffer = Buffer.alloc(0);
+	let key;
+	let from;
+	let recipients = [];
+	let data;
+	let size = 0;
+	let login;
+	let user = "";
+	let busy = Promise.resolve();
+	const reply = (line) => {
+		socket.write(`${line}\r\n`);
+	};
+	const reset = () => {
+		from = void 0;
+		recipients = [];
+		data = void 0;
+		size = 0;
+	};
+	reply(`220 ${options.name} ESMTP ready`);
+	const signIn = (user, password) => {
+		if (user !== "midsummer" || !password) return reply("535 5.7.8 Sign in as midsummer with an Email key as the password.");
+		key = password;
+		reply("235 2.7.0 Signed in.");
+	};
+	async function finish(raw) {
+		try {
+			const all = [];
+			for (const message of parse(raw, from, recipients)) all.push(await options.send(key, message));
+			const failed = all.find((sent) => sent.state === "failed");
+			const suppressed = all.flatMap((sent) => sent.suppressed);
+			reply(failed ? `554 5.6.0 ${failed.error ?? "The Message was refused."}` : `250 2.0.0 ${all.map((sent) => `${sent.id} ${sent.state}`).join(", ")}${suppressed.length ? `, suppressed ${suppressed.join(" ")}` : ""}`);
+		} catch (error) {
+			const text = error instanceof Error ? error.message.replace(/[\r\n]+/g, " ") : "The Message was refused.";
+			if (!(error instanceof EmailError)) reply(`451 4.3.0 ${text}`);
+			else reply(`${{
+				forbidden: "535 5.7.8",
+				unverified: "550 5.7.1",
+				invalid: "554 5.6.0",
+				unavailable: "451 4.3.0"
+			}[error.code]} ${text}`);
+		}
+		reset();
+	}
+	async function command(line) {
+		if (data) {
+			if (line === ".") {
+				const raw = Buffer.concat(data);
+				data = void 0;
+				if (size > MAX_BYTES) {
+					reset();
+					return reply(`552 5.3.4 A message is at most ${MAX_BYTES} bytes.`);
+				}
+				return finish(raw);
+			}
+			const content = Buffer.from(`${line.startsWith(".") ? line.slice(1) : line}\r\n`, "latin1");
+			size += content.length;
+			if (size <= MAX_BYTES) data.push(content);
+			return;
+		}
+		if (login) {
+			const value = Buffer.from(line, "base64").toString("utf8");
+			if (login === "plain") {
+				login = void 0;
+				const [, user = "", password = ""] = value.split("\0");
+				return signIn(user, password);
+			}
+			if (login === "user") {
+				login = "pass";
+				user = value;
+				return reply("334 UGFzc3dvcmQ6");
+			}
+			login = void 0;
+			return signIn(user, value);
+		}
+		const [verb = "", ...rest] = line.split(" ");
+		const argument = rest.join(" ");
+		switch (verb.toUpperCase()) {
+			case "EHLO": return reply([
+				`250-${options.name}`,
+				...options.secure || local(socket) ? ["250-AUTH PLAIN LOGIN"] : [],
+				`250-SIZE ${MAX_BYTES}`,
+				"250-8BITMIME",
+				"250 SMTPUTF8"
+			].join("\r\n"));
+			case "HELO": return reply(`250 ${options.name}`);
+			case "AUTH": {
+				if (!options.secure && !local(socket)) return reply("538 5.7.11 Sign in only over TLS.");
+				const [mechanism = "", initial] = argument.split(" ");
+				if (mechanism.toUpperCase() === "PLAIN") {
+					if (initial) {
+						const [, user = "", password = ""] = Buffer.from(initial, "base64").toString("utf8").split("\0");
+						return signIn(user, password);
+					}
+					login = "plain";
+					return reply("334 ");
+				}
+				if (mechanism.toUpperCase() === "LOGIN") {
+					login = "user";
+					return reply("334 VXNlcm5hbWU6");
+				}
+				return reply("504 5.5.4 Use AUTH PLAIN or LOGIN.");
+			}
+			case "MAIL": {
+				if (!key) return reply("530 5.7.0 Sign in first, with an Email key.");
+				const address = /^FROM:\s*<([^>]*)>/i.exec(argument)?.[1];
+				if (address === void 0) return reply("501 5.5.4 Say MAIL FROM:<address>.");
+				reset();
+				from = address;
+				return reply("250 2.1.0 OK");
+			}
+			case "RCPT": {
+				if (from === void 0) return reply("503 5.5.1 Say MAIL FROM first.");
+				const address = /^TO:\s*<([^>]+)>/i.exec(argument)?.[1];
+				if (!address) return reply("501 5.5.4 Say RCPT TO:<address>.");
+				if (recipients.length >= 50) return reply(`452 4.5.3 At most 50 recipients.`);
+				recipients.push(address);
+				return reply("250 2.1.5 OK");
+			}
+			case "DATA":
+				if (!recipients.length) return reply("503 5.5.1 Say RCPT TO first.");
+				data = [];
+				return reply("354 End the message with a line holding only a dot.");
+			case "RSET":
+				reset();
+				return reply("250 2.0.0 OK");
+			case "NOOP": return reply("250 2.0.0 OK");
+			case "QUIT":
+				reply("221 2.0.0 Bye");
+				socket.end();
+				return;
+			default: return reply("502 5.5.2 Not a command here.");
+		}
+	}
+	socket.on("data", (chunk) => {
+		buffer = Buffer.concat([buffer, chunk]);
+		for (let end = buffer.indexOf("\n"); end >= 0; end = buffer.indexOf("\n")) {
+			const line = buffer.subarray(0, end).toString("latin1").replace(/\r$/, "");
+			buffer = buffer.subarray(end + 1);
+			busy = busy.then(() => command(line)).catch(() => {
+				socket.destroy();
+			});
+		}
+	});
+	socket.on("error", () => socket.destroy());
+}
+/** A header's value with its encoded words (RFC 2047) decoded. */
+function words(value) {
+	return value.replace(/=\?([^?]+)\?([BbQq])\?([^?]*)\?=\s*(?==\?)?/g, (_, charset, encoding, text) => {
+		return decode(encoding.toUpperCase() === "B" ? Buffer.from(text, "base64") : Buffer.from(text.replace(/_/g, " ").replace(/=([0-9A-Fa-f]{2})/g, (_m, h) => String.fromCharCode(parseInt(h, 16))), "latin1"), charset);
+	});
+}
+function decode(bytes, charset = "utf-8") {
+	try {
+		return new TextDecoder(charset).decode(bytes);
+	} catch {
+		return new TextDecoder().decode(bytes);
+	}
+}
+/** A part's headers, unfolded and keyed lowercase, and its body's bytes. */
+function split(raw) {
+	const text = raw.toString("latin1");
+	const at = text.search(/\r?\n\r?\n/);
+	const head = at < 0 ? text : text.slice(0, at);
+	const body = at < 0 ? "" : text.slice(at).replace(/^\r?\n\r?\n/, "");
+	const headers = /* @__PURE__ */ new Map();
+	for (const line of head.replace(/\r?\n[ \t]+/g, " ").split(/\r?\n/)) {
+		const colon = line.indexOf(":");
+		if (colon > 0) headers.set(line.slice(0, colon).trim().toLowerCase(), line.slice(colon + 1).trim());
+	}
+	return {
+		headers,
+		body: Buffer.from(body, "latin1")
+	};
+}
+/** A parameter of a header such as Content-Type: `boundary`, `charset`. */
+const parameter = (header, name) => new RegExp(`;\\s*${name}="?([^";]+)"?`, "i").exec(header)?.[1];
+/** The text and HTML of a part, by its content type, through multiparts. */
+function bodies(headers, body, found) {
+	const type = headers.get("content-type") ?? "text/plain";
+	if (/^multipart\//i.test(type)) {
+		const boundary = parameter(type, "boundary");
+		if (!boundary) return;
+		for (const piece of body.toString("latin1").split(`--${boundary}`).slice(1)) {
+			if (piece.startsWith("--")) break;
+			const part = split(Buffer.from(piece.replace(/^\r?\n/, ""), "latin1"));
+			bodies(part.headers, part.body, found);
+		}
+		return;
+	}
+	const encoding = (headers.get("content-transfer-encoding") ?? "7bit").toLowerCase();
+	const content = decode(encoding === "base64" ? Buffer.from(body.toString("latin1").replace(/\s+/g, ""), "base64") : encoding === "quoted-printable" ? Buffer.from(body.toString("latin1").replace(/=\r?\n/g, "").replace(/=([0-9A-Fa-f]{2})/g, (_, h) => String.fromCharCode(parseInt(h, 16))), "latin1") : body, parameter(type, "charset")).replace(/\r\n$/, "");
+	if (/^text\/html/i.test(type)) found.html ??= content;
+	else if (/^text\/plain/i.test(type)) found.text ??= content;
+}
+/** The addresses of a header such as To: `Ada <ada@example.com>, grace@example.com`. */
+function addresses(value) {
+	if (!value) return [];
+	return (value.match(/(?:"[^"]*"|<[^>]*>|[^,])+/g) ?? []).map((item) => (/<([^>]+)>/.exec(item)?.[1] ?? item).trim().toLowerCase()).filter(Boolean);
+}
+/**
+* A message as Email takes it, from what the client sent and its envelope. The envelope's recipients
+* its `To` and `Cc` name are its to and cc, and the rest its bcc. A Message has someone in to, so one
+* whose headers name nobody of the envelope (every recipient blind) goes as one Message per recipient,
+* each to that recipient alone, so none sees another's address; with only Cc named, those are its to.
+*/
+function parse(raw, envelope, recipients) {
+	const { headers, body } = split(raw);
+	const found = {};
+	bodies(headers, body, found);
+	const bare = [...new Set(recipients.map((address) => address.toLowerCase()))];
+	const named = (header) => addresses(headers.get(header)).filter((address) => bare.includes(address));
+	const to = named("to"), cc = named("cc").filter((address) => !to.includes(address));
+	const bcc = bare.filter((address) => !to.includes(address) && !cc.includes(address));
+	const replyTo = headers.get("reply-to");
+	const id = headers.get("message-id");
+	const common = {
+		from: words(headers.get("from") ?? envelope),
+		...replyTo ? { replyTo: words(replyTo) } : {},
+		subject: words(headers.get("subject") ?? "") || "(no subject)",
+		...found.text !== void 0 ? { text: found.text } : {},
+		...found.html !== void 0 ? { html: found.html } : {}
+	};
+	if (!to.length && !cc.length) return bcc.map((address) => ({
+		...common,
+		to: [address],
+		...id ? { key: `smtp:${id}:${address}` } : {}
+	}));
+	return [{
+		...common,
+		to: to.length ? to : cc,
+		...to.length && cc.length ? { cc } : {},
+		...bcc.length ? { bcc } : {},
+		...id ? { key: `smtp:${id}` } : {}
+	}];
+}
+//#endregion
+export { relayTo, serveSmtp };

package/email/stand-in.d.mts

@@ -0,0 +1,13 @@
+import { CheckedMessage, EmailEngine } from "./index.mjs";
+//#region src/email/stand-in.d.ts
+declare function standIn(options: {
+  readonly domains: ReadonlyArray<string>;
+  readonly suppressed?: ReadonlyArray<string>;
+}): EmailEngine & {
+  readonly sent: ReadonlyArray<CheckedMessage & {
+    readonly id: string;
+  }>;
+  suppress(address: string): void;
+};
+//#endregion
+export { standIn };

package/email/stand-in.mjs

@@ -0,0 +1,51 @@
+import { EmailError, addressOf } from "./index.mjs";
+//#region src/email/stand-in.ts
+/**
+* Email's Stand-in: the Capability's behaviour in memory, for `midsummer dev` and tests. It sends
+* nothing anywhere; what it would send is kept in `sent`. It passes the contract
+* (`@midsummer-ai/sdk/email/contract`) except durability and delivery.
+*
+*   const engine = standIn({ domains: ["mail.acme.dev"] })
+*   await email(engine).send({ from: "hi@mail.acme.dev", to: "ada@example.com", subject: "Hi", text: "Hello" })
+*   engine.sent   // what was sent
+*
+* `domains` are the verified Sending domains; `suppressed` the addresses no longer sent to.
+*/
+function standIn(options) {
+	const domains = new Set(options.domains.map((name) => name.toLowerCase()));
+	const suppressed = new Set((options.suppressed ?? []).map(addressOf));
+	const sent = [];
+	const byKey = /* @__PURE__ */ new Map();
+	let count = 0;
+	return {
+		sent,
+		suppress: (address) => {
+			suppressed.add(addressOf(address));
+		},
+		async send(message) {
+			const from = addressOf(message.from);
+			if (!domains.has(from.slice(from.indexOf("@") + 1))) throw new EmailError("unverified", `${from} is not on a verified Sending domain`);
+			const earlier = message.key !== void 0 ? byKey.get(message.key) : void 0;
+			if (earlier) return earlier;
+			const recipients = [...new Set([
+				...message.to,
+				...message.cc ?? [],
+				...message.bcc ?? []
+			].map(addressOf))];
+			const left = recipients.filter((address) => !suppressed.has(address));
+			const answer = {
+				id: `msg_${++count}`,
+				state: left.length ? "sent" : "suppressed",
+				suppressed: recipients.filter((address) => suppressed.has(address))
+			};
+			if (left.length) sent.push({
+				...message,
+				id: answer.id
+			});
+			if (message.key !== void 0) byKey.set(message.key, answer);
+			return answer;
+		}
+	};
+}
+//#endregion
+export { standIn };