@flowdular/sdk 0.2.4 → 0.3.0

package/packages/server/src/mail/contracts.ts

@@ -0,0 +1,251 @@
+/* The one outbound mail contract of the platform. A module never selects an
+   SMTP, a transactional-email service or a provider SDK: it receives this port
+   on the server context and hands it a bounded message. */
+
+export const MAIL_ADAPTERS = ['none', 'development', 'smtp'] as const;
+
+export type MailAdapterId = (typeof MAIL_ADAPTERS)[number];
+
+/**
+ * Hard message bounds. None of them is configurable: they are the contract a
+ * sender codes against, and the ceiling on what one message can cost.
+ */
+export const MAIL_LIMITS = {
+	recipients: 16,
+	address: 320,
+	subject: 200,
+	text: 64 * 1_024,
+	html: 256 * 1_024,
+	headers: 16,
+	headerName: 64,
+	/** The line length RFC 5322 allows without folding. */
+	headerValue: 998,
+	locale: 16,
+} as const;
+
+export type MailErrorCode =
+	/** No transport is composed; the message was not queued anywhere. */
+	| 'MAIL_NOT_CONFIGURED'
+	/** The message broke a bound or carried something a header could not. */
+	| 'MAIL_MESSAGE_REJECTED'
+	/** The transport refused it. The relay's own words never travel with it. */
+	| 'MAIL_DELIVERY_FAILED';
+
+export class MailError extends Error {
+	readonly code: MailErrorCode;
+
+	constructor(code: MailErrorCode, message: string) {
+		super(message);
+		this.name = 'MailError';
+		this.code = code;
+	}
+}
+
+export interface MailMessage {
+	readonly to: string | readonly string[];
+	readonly subject: string;
+	readonly text: string;
+	readonly html?: string;
+	/** BCP 47 tag of the rendered body; travels as Content-Language. */
+	readonly locale?: string;
+	/** Extra headers, names restricted and values single line. */
+	readonly headers?: Readonly<Record<string, string>>;
+}
+
+/** A message as the port accepted it: bounds checked, recipients deduplicated. */
+export interface AcceptedMailMessage {
+	readonly to: readonly string[];
+	readonly subject: string;
+	readonly text: string;
+	readonly html: string | null;
+	readonly locale: string | null;
+	readonly headers: Readonly<Record<string, string>>;
+}
+
+export interface DeliveredMail extends AcceptedMailMessage {
+	readonly sentAt: number;
+}
+
+export interface MailPort {
+	readonly adapter: MailAdapterId;
+	/**
+	 * False for the `none` adapter. A sender reads it to decide whether a feature
+	 * that needs mail is available at all, instead of provoking a refusal.
+	 */
+	readonly configured: boolean;
+	/**
+	 * Rejects with a `MailError`. Nothing about the relay, the credentials or the
+	 * remote banner reaches the caller.
+	 */
+	send(message: MailMessage): Promise<void>;
+	/**
+	 * The development adapter's evidence, oldest first and capped. Always empty
+	 * for the other adapters, so a test reads one place whatever is composed.
+	 */
+	readonly outbox: readonly DeliveredMail[];
+}
+
+const EMPTY_HEADERS: Readonly<Record<string, string>> = Object.freeze({});
+export const NO_MAIL: readonly DeliveredMail[] = Object.freeze([]);
+
+const ADDRESS_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const HEADER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+const LOCALE_PATTERN = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/;
+/* RFC 5322 specials. Unquoted, any of them makes a parser read a second
+   address, or an address the sender never named, out of the display name. */
+const DISPLAY_NAME_SPECIALS = /[",;:<>@]/;
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/;
+
+/* Everything the envelope owns. A sender that could set one of these could
+   redirect the message or rewrite what the recipient sees it as. */
+const RESERVED_HEADERS: ReadonlySet<string> = new Set([
+	'bcc',
+	'cc',
+	'content-language',
+	'content-transfer-encoding',
+	'content-type',
+	'date',
+	'from',
+	'message-id',
+	'mime-version',
+	'received',
+	'reply-to',
+	'return-path',
+	'sender',
+	'subject',
+	'to',
+]);
+
+function reject(message: string): MailError {
+	return new MailError('MAIL_MESSAGE_REJECTED', message);
+}
+
+/** Refuses anything that is not a single deliverable address. */
+export function mailAddress(value: string, field: string): string {
+	const address = value.trim();
+	if (address.length > MAIL_LIMITS.address || !ADDRESS_PATTERN.test(address)) {
+		throw reject(`${field} is not deliverable.`);
+	}
+	return address;
+}
+
+/**
+ * `Name <address>` or a bare address, on one line. A sender carrying CR or LF
+ * would append its own headers to every message the transport sends.
+ */
+export function mailSender(value: string, variable: string): string {
+	const sender = value.trim();
+	if (CONTROL_CHARACTER.test(sender)) {
+		throw reject(`${variable} must be a single line.`);
+	}
+	const named = /^(.*)<([^<>]*)>$/.exec(sender);
+	if (!named) {
+		mailAddressOrThrow(sender, variable);
+		return sender;
+	}
+	const name = named[1]?.trim() ?? '';
+	if (name.length > 128 || DISPLAY_NAME_SPECIALS.test(name)) {
+		throw reject(`${variable} has an unsupported display name.`);
+	}
+	mailAddressOrThrow((named[2] ?? '').trim(), variable);
+	return sender;
+}
+
+function mailAddressOrThrow(address: string, variable: string): void {
+	if (address.length > MAIL_LIMITS.address || !ADDRESS_PATTERN.test(address)) {
+		throw reject(`${variable} must be an address or "Name <address>".`);
+	}
+}
+
+function acceptedRecipients(to: MailMessage['to']): readonly string[] {
+	const list = typeof to === 'string' ? [to] : to;
+	if (list.length === 0) throw reject('A message must name a recipient.');
+	if (list.length > MAIL_LIMITS.recipients) {
+		throw reject(
+			`A message must name at most ${MAIL_LIMITS.recipients} recipients.`,
+		);
+	}
+	/* Deduplicated so one address cannot be billed, rate limited or reported
+	   twice by naming it repeatedly. */
+	return [...new Set(list.map((entry) => mailAddress(entry, 'A recipient')))];
+}
+
+function acceptedHeaders(
+	headers: MailMessage['headers'],
+	locale: string | null,
+): Readonly<Record<string, string>> {
+	const entries = headers ? Object.entries(headers) : [];
+	if (entries.length === 0 && locale === null) return EMPTY_HEADERS;
+	if (entries.length > MAIL_LIMITS.headers) {
+		throw reject(
+			`A message must carry at most ${MAIL_LIMITS.headers} headers.`,
+		);
+	}
+	const accepted: Record<string, string> = {};
+	for (const [name, value] of entries) {
+		const key = name.trim().toLowerCase();
+		if (key.length > MAIL_LIMITS.headerName || !HEADER_NAME_PATTERN.test(key)) {
+			throw reject(`The header name ${JSON.stringify(name)} is not allowed.`);
+		}
+		if (RESERVED_HEADERS.has(key)) {
+			throw reject(`The header ${key} is owned by the transport.`);
+		}
+		if (
+			typeof value !== 'string' ||
+			value.length > MAIL_LIMITS.headerValue ||
+			CONTROL_CHARACTER.test(value)
+		) {
+			throw reject(`The header ${key} must carry one line of text.`);
+		}
+		accepted[key] = value;
+	}
+	if (locale !== null) accepted['content-language'] = locale;
+	return Object.freeze(accepted);
+}
+
+/**
+ * The single gate every adapter runs before it touches a transport. It is what
+ * makes "no header injection" a property of the port rather than of each
+ * sender: a subject, an address or a header value carrying CR or LF is refused
+ * here, once.
+ */
+export function acceptMailMessage(message: MailMessage): AcceptedMailMessage {
+	const to = acceptedRecipients(message.to);
+	const subject = message.subject.trim();
+	if (subject.length === 0 || subject.length > MAIL_LIMITS.subject) {
+		throw reject(
+			`A subject must be 1 to ${MAIL_LIMITS.subject} characters long.`,
+		);
+	}
+	if (CONTROL_CHARACTER.test(subject)) {
+		throw reject('A subject must be a single line.');
+	}
+	const textBytes = Buffer.byteLength(message.text, 'utf8');
+	if (message.text.length === 0 || textBytes > MAIL_LIMITS.text) {
+		throw reject(`A text body must be 1 to ${MAIL_LIMITS.text} bytes long.`);
+	}
+	if (
+		message.html !== undefined &&
+		Buffer.byteLength(message.html, 'utf8') > MAIL_LIMITS.html
+	) {
+		throw reject(
+			`An HTML body must be at most ${MAIL_LIMITS.html} bytes long.`,
+		);
+	}
+	const locale = message.locale?.trim() ?? '';
+	if (
+		locale !== '' &&
+		(locale.length > MAIL_LIMITS.locale || !LOCALE_PATTERN.test(locale))
+	) {
+		throw reject('A locale must be a BCP 47 language tag.');
+	}
+	const resolvedLocale = locale === '' ? null : locale;
+	return {
+		to,
+		subject,
+		text: message.text,
+		html: message.html ?? null,
+		locale: resolvedLocale,
+		headers: acceptedHeaders(message.headers, resolvedLocale),
+	};
+}

package/packages/server/src/mail/index.ts

@@ -0,0 +1,31 @@
+export {
+	acceptMailMessage,
+	mailAddress,
+	mailSender,
+	MailError,
+	MAIL_ADAPTERS,
+	MAIL_LIMITS,
+	NO_MAIL,
+} from './contracts.ts';
+export type {
+	AcceptedMailMessage,
+	DeliveredMail,
+	MailAdapterId,
+	MailErrorCode,
+	MailMessage,
+	MailPort,
+} from './contracts.ts';
+export { mailConfigFromEnvironment } from './config.ts';
+export type { MailConfig, MailVariableNames } from './config.ts';
+export { createMailPort, DEVELOPMENT_OUTBOX_LIMIT } from './port.ts';
+export type { MailPortOptions } from './port.ts';
+export { createSmtpMailAdapter, SmtpMailAdapter } from './smtp.ts';
+export type {
+	SmtpMailAdapterOptions,
+	SmtpMessage,
+	SmtpTransport,
+	SmtpTransportFactory,
+	SmtpTransportOptions,
+} from './smtp.ts';
+export { renderMailTemplate, MAIL_TEMPLATE_LIMITS } from './template.ts';
+export type { MailTemplate, RenderedMailTemplate } from './template.ts';

package/packages/server/src/mail/port.ts

@@ -0,0 +1,101 @@
+import type { MailConfig } from './config.ts';
+import {
+	acceptMailMessage,
+	MailError,
+	NO_MAIL,
+	type DeliveredMail,
+	type MailMessage,
+	type MailPort,
+} from './contracts.ts';
+import { createSmtpMailAdapter, type SmtpTransportFactory } from './smtp.ts';
+
+/**
+ * What the development outbox keeps. It exists for a test and a local run, so
+ * it is a ring: a long dev session sends messages forever and must not grow the
+ * process by one retained body per message.
+ */
+export const DEVELOPMENT_OUTBOX_LIMIT = 100;
+
+export interface MailPortOptions {
+	/**
+	 * Opens an SMTP connection. The platform composition passes nodemailer's;
+	 * this package declares the interface and depends on no mail client.
+	 */
+	readonly createSmtpTransport?: SmtpTransportFactory;
+	readonly now?: () => number;
+}
+
+class DevelopmentMailPort implements MailPort {
+	readonly adapter = 'development' as const;
+	readonly configured = true;
+	readonly #messages: DeliveredMail[] = [];
+	readonly #now: () => number;
+
+	constructor(now: () => number) {
+		this.#now = now;
+	}
+
+	get outbox(): readonly DeliveredMail[] {
+		return this.#messages;
+	}
+
+	async send(message: MailMessage): Promise<void> {
+		/* Local-only evidence for tests and the dev composition. It is in memory
+		   on purpose, never exposed over HTTP and never written to a log. */
+		this.#messages.push({ ...acceptMailMessage(message), sentAt: this.#now() });
+		if (this.#messages.length > DEVELOPMENT_OUTBOX_LIMIT) {
+			this.#messages.splice(
+				0,
+				this.#messages.length - DEVELOPMENT_OUTBOX_LIMIT,
+			);
+		}
+	}
+}
+
+const UNCONFIGURED: MailPort = Object.freeze({
+	adapter: 'none' as const,
+	configured: false,
+	outbox: NO_MAIL,
+	/* Refused before the message is even inspected, so the code a sender sees is
+	   the same for every message: this deployment has no transport. */
+	send: async (): Promise<void> => {
+		throw new MailError(
+			'MAIL_NOT_CONFIGURED',
+			'No mail transport is configured for this deployment.',
+		);
+	},
+});
+
+/**
+ * The platform's outbound mail. `none` refuses every message with a stable
+ * code, `development` collects them in memory and is refused in production by
+ * the configuration reader, `smtp` hands them to a deployment-owned relay.
+ */
+export function createMailPort(
+	config: MailConfig,
+	options: MailPortOptions = {},
+): MailPort {
+	if (config.adapter === 'none') return UNCONFIGURED;
+	if (config.adapter === 'development') {
+		return new DevelopmentMailPort(options.now ?? Date.now);
+	}
+	if (!options.createSmtpTransport) {
+		throw new Error(
+			`${config.variables.transport}=smtp needs an SMTP transport factory from the composition.`,
+		);
+	}
+	const adapter = createSmtpMailAdapter({
+		url: config.smtp.url,
+		from: config.from,
+		rejectUnauthorized: config.smtp.rejectUnauthorized,
+		requireTLS: config.smtp.requireTLS,
+		createTransport: options.createSmtpTransport,
+		variables: { url: config.variables.url, from: config.variables.from },
+	});
+	return {
+		adapter: 'smtp',
+		configured: true,
+		outbox: NO_MAIL,
+		send: (message) => adapter.send(message),
+	};
+}

package/packages/server/src/mail/smtp.ts

@@ -0,0 +1,191 @@
+import {
+	acceptMailMessage,
+	MailError,
+	mailSender,
+	type AcceptedMailMessage,
+	type MailMessage,
+} from './contracts.ts';
+
+/* A deployment-owned SMTP relay behind the port. The only supported
+   configuration source is the process environment, so every validation error
+   names the variable an operator has to fix. */
+
+const CONNECTION_TIMEOUT_MS = 10_000;
+
+export interface SmtpTransportOptions {
+	readonly host: string;
+	readonly port: number;
+	readonly secure: boolean;
+	readonly auth?: { readonly user: string; readonly pass: string };
+	/** STARTTLS or nothing; set only on the cleartext scheme, which needs it. */
+	readonly requireTLS?: boolean;
+	readonly tls: { readonly rejectUnauthorized: boolean };
+	readonly connectionTimeout: number;
+	readonly greetingTimeout: number;
+}
+
+export interface SmtpMessage {
+	readonly from: string;
+	readonly to: string;
+	readonly subject: string;
+	readonly text: string;
+	readonly html: string;
+	readonly headers?: Readonly<Record<string, string>>;
+}
+
+/** The nodemailer surface this adapter uses, so tests need no socket. */
+export interface SmtpTransport {
+	sendMail(message: SmtpMessage): Promise<unknown>;
+}
+
+export type SmtpTransportFactory = (
+	options: SmtpTransportOptions,
+) => SmtpTransport | Promise<SmtpTransport>;
+
+export interface SmtpMailAdapterOptions {
+	/** `smtp://` or `smtps://`, credentials included. Never logged. */
+	readonly url: string;
+	/** `Name <addr>` or `addr`. */
+	readonly from: string;
+	readonly rejectUnauthorized?: boolean;
+	/** Refuse a cleartext `smtp://` session that offers no STARTTLS. Default true. */
+	readonly requireTLS?: boolean;
+	/**
+	 * Opens the relay connection. Required: the SMTP client is a dependency of
+	 * whoever composes the port, never of this package, so the server layer
+	 * carries no transitive mail library.
+	 */
+	readonly createTransport: SmtpTransportFactory;
+	/** Variables the refusals name; a deployment may still use retired ones. */
+	readonly variables?: { readonly url: string; readonly from: string };
+}
+
+const DEFAULT_VARIABLES = {
+	url: 'FD_MAIL_SMTP_URL',
+	from: 'FD_MAIL_FROM',
+} as const;
+
+function smtpTransportOptions(
+	url: string,
+	rejectUnauthorized: boolean,
+	requireTLS: boolean,
+	variable: string,
+): SmtpTransportOptions {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		/* The thrown value never carries the URL: it holds the relay password. */
+		throw new Error(`${variable} must be a valid URL.`);
+	}
+	if (parsed.protocol !== 'smtp:' && parsed.protocol !== 'smtps:') {
+		throw new Error(`${variable} must use smtp:// or smtps://.`);
+	}
+	if (!parsed.hostname) {
+		throw new Error(`${variable} must name a host.`);
+	}
+	const secure = parsed.protocol === 'smtps:';
+	let user: string;
+	let pass: string;
+	try {
+		user = decodeURIComponent(parsed.username);
+		pass = decodeURIComponent(parsed.password);
+	} catch {
+		/* A stray percent is a URIError naming neither the variable nor the fix,
+		   and the value it carries is the relay password. */
+		throw new Error(`${variable} credentials must be percent-encoded.`);
+	}
+	return {
+		host: parsed.hostname,
+		port: parsed.port ? Number(parsed.port) : secure ? 465 : 587,
+		secure,
+		...(user ? { auth: { user, pass } } : {}),
+		/* Without it nodemailer sends over a plain socket whenever the relay
+		   omits STARTTLS or a downgrade strips it, and the credentials and the
+		   single-use links in the message go with it. */
+		...(secure ? {} : { requireTLS }),
+		tls: { rejectUnauthorized },
+		connectionTimeout: CONNECTION_TIMEOUT_MS,
+		greetingTimeout: CONNECTION_TIMEOUT_MS,
+	};
+}
+
+/**
+ * Sends accepted messages through one relay. The connection is opened on the
+ * first message and reused; it is not pooled, so a socket lives only for the
+ * message it carries and disposal has nothing to release.
+ */
+export class SmtpMailAdapter {
+	readonly #from: string;
+	readonly #options: SmtpTransportOptions;
+	readonly #createTransport: SmtpTransportFactory;
+	#transport: Promise<SmtpTransport> | undefined;
+
+	constructor(options: SmtpMailAdapterOptions) {
+		const variables = options.variables ?? DEFAULT_VARIABLES;
+		this.#from = mailSender(options.from, variables.from);
+		this.#options = smtpTransportOptions(
+			options.url,
+			options.rejectUnauthorized ?? true,
+			options.requireTLS ?? true,
+			variables.url,
+		);
+		this.#createTransport = options.createTransport;
+	}
+
+	async send(message: MailMessage): Promise<void> {
+		await this.deliver(acceptMailMessage(message));
+	}
+
+	/** The accepted form, for a sender that already ran the port's gate. */
+	async deliver(message: AcceptedMailMessage): Promise<void> {
+		let transport: SmtpTransport;
+		try {
+			transport = await this.#open();
+		} catch {
+			/* A factory rejection carries the relay host and the options it was
+			   handed, the credentials among them; only the code travels. */
+			throw new MailError(
+				'MAIL_DELIVERY_FAILED',
+				'The mail transport could not be opened.',
+			);
+		}
+		try {
+			await transport.sendMail({
+				from: this.#from,
+				to: message.to.join(', '),
+				subject: message.subject,
+				text: message.text,
+				html: message.html ?? '',
+				...(Object.keys(message.headers).length === 0
+					? {}
+					: { headers: message.headers }),
+			});
+		} catch {
+			/* An SMTP rejection quotes the envelope and the server banner, and a
+			   connection error carries the relay host. Neither reaches the caller
+			   and neither is logged here: the sender owns what it records. */
+			throw new MailError(
+				'MAIL_DELIVERY_FAILED',
+				'The mail transport refused the message.',
+			);
+		}
+	}
+
+	#open(): Promise<SmtpTransport> {
+		if (this.#transport) return this.#transport;
+		const opening = Promise.resolve(this.#createTransport(this.#options));
+		this.#transport = opening;
+		/* A failed transport must not poison every later delivery. */
+		void opening.catch(() => {
+			if (this.#transport === opening) this.#transport = undefined;
+		});
+		return opening;
+	}
+}
+
+export function createSmtpMailAdapter(
+	options: SmtpMailAdapterOptions,
+): SmtpMailAdapter {
+	return new SmtpMailAdapter(options);
+}

package/packages/server/src/mail/template.ts

@@ -0,0 +1,105 @@
+import { MAIL_LIMITS, MailError } from './contracts.ts';
+
+/* A mail template is a sender's own text with named holes in it. It is not a
+   general template language on purpose: one pass, no expressions, no includes,
+   no recursion, so what a value contains can never become markup or another
+   placeholder. */
+
+export interface MailTemplate {
+	readonly subject: string;
+	readonly text: string;
+	readonly html?: string;
+	/** BCP 47 tag of this wording; the rendered message carries it. */
+	readonly locale?: string;
+}
+
+export interface RenderedMailTemplate {
+	readonly subject: string;
+	readonly text: string;
+	readonly html?: string;
+	readonly locale?: string;
+}
+
+/** Bounds of one rendering; the rendered message is bounded again by the port. */
+export const MAIL_TEMPLATE_LIMITS = {
+	values: 32,
+	valueLength: 4_096,
+} as const;
+
+const PLACEHOLDER = /\{\{\s*([A-Za-z0-9_]{1,32})\s*\}\}/g;
+
+function escapeHtml(value: string): string {
+	return value
+		.replaceAll('&', '&')
+		.replaceAll('<', '&lt;')
+		.replaceAll('>', '&gt;')
+		.replaceAll('"', '&quot;')
+		.replaceAll("'", '&#39;');
+}
+
+function reject(message: string): MailError {
+	return new MailError('MAIL_MESSAGE_REJECTED', message);
+}
+
+function substitute(
+	source: string,
+	values: Readonly<Record<string, string>>,
+	escape: boolean,
+): string {
+	/* One pass over the source: a value that itself looks like a placeholder is
+	   written out, never rendered again. */
+	return source.replaceAll(PLACEHOLDER, (_match, name: string) => {
+		/* Own keys only: a hole named after something on Object.prototype, such as
+		   {{constructor}}, is an unknown value like any other. */
+		if (!Object.hasOwn(values, name)) {
+			throw reject(`The mail template names the unknown value ${name}.`);
+		}
+		const value = values[name]!;
+		return escape ? escapeHtml(value) : value;
+	});
+}
+
+/**
+ * Fills `{{ name }}` holes in a template. Values reach the text parts as they
+ * are and the HTML part escaped, so a display name or a workspace title can
+ * never open a tag or an attribute in the rendered message.
+ */
+export function renderMailTemplate(
+	template: MailTemplate,
+	values: Readonly<Record<string, string>> = {},
+): RenderedMailTemplate {
+	const entries = Object.entries(values);
+	if (entries.length > MAIL_TEMPLATE_LIMITS.values) {
+		throw reject(
+			`A template takes at most ${MAIL_TEMPLATE_LIMITS.values} values.`,
+		);
+	}
+	for (const [name, value] of entries) {
+		if (typeof value !== 'string') {
+			throw reject(`The template value ${name} must be text.`);
+		}
+		if (value.length > MAIL_TEMPLATE_LIMITS.valueLength) {
+			throw reject(
+				`The template value ${name} must be at most ${MAIL_TEMPLATE_LIMITS.valueLength} characters long.`,
+			);
+		}
+	}
+	if (
+		template.subject.length > MAIL_LIMITS.subject ||
+		Buffer.byteLength(template.text, 'utf8') > MAIL_LIMITS.text ||
+		(template.html !== undefined &&
+			Buffer.byteLength(template.html, 'utf8') > MAIL_LIMITS.html)
+	) {
+		throw reject('The mail template is larger than a message may be.');
+	}
+	const html =
+		template.html === undefined
+			? undefined
+			: substitute(template.html, values, true);
+	return {
+		subject: substitute(template.subject, values, false),
+		text: substitute(template.text, values, false),
+		...(html === undefined ? {} : { html }),
+		...(template.locale === undefined ? {} : { locale: template.locale }),
+	};
+}