ajo-kit-mail 0.1.0

package/src/seal.ts

@@ -0,0 +1,242 @@
+import { randomUUID } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+import { Refused, type RefusalCode } from './errors'
+
+/** One mailbox: a bare address, optionally with a display name. */
+export interface Address {
+	readonly address: string
+	readonly name?: string
+}
+
+/** A mailbox written as a bare address or as a named pair. */
+export type Recipient = string | Address
+
+/** What an application asks the package to deliver. */
+export interface Message {
+	/** Exactly one recipient. Credential mail must not fan out. */
+	to: Recipient
+	subject: string
+	text: string
+	html?: string
+	/** Overrides the configured sender for this message only. */
+	from?: Recipient
+	replyTo?: Recipient
+	/** Short label for logs and events: 'reset', 'verify', 'invite'. Default 'mail'. */
+	kind?: string
+	/** Idempotency key forwarded to providers that accept one. Never deduplicated locally. */
+	key?: string
+	/** Hard deadline. Nothing is ever attempted past it: pass the credential's own expiry. */
+	expires?: Date | number
+}
+
+declare const sealed: unique symbol
+
+/**
+ * Validated, frozen message. Only seal() constructs one, so a Transport is
+ * structurally incapable of receiving unvalidated input.
+ */
+export interface Envelope {
+	readonly id: string
+	readonly kind: string
+	readonly from: Address
+	readonly to: Address
+	readonly replyTo?: Address
+	readonly subject: string
+	readonly text: string
+	readonly html?: string
+	readonly key?: string
+	/** Absolute epoch-ms deadline for this attempt. */
+	readonly deadline: number
+	/** Aborts at deadline. Transports must honour it. */
+	readonly signal: AbortSignal
+}
+
+/** An envelope that crossed the package's sole validation boundary. */
+export type Sealed = Readonly<Envelope> & { readonly [sealed]: 'ajo-kit-mail' }
+
+/** Validation limits and sender identity. Pure data; a test builds one inline. */
+export interface Policy {
+	from: Recipient
+	replyTo?: Recipient
+	/** Milliseconds for one attempt. Default 10_000. */
+	timeout?: number
+	/** Maximum text + html bytes. Default and hard maximum 262_144. */
+	limit?: number
+}
+
+// C0 + DEL, written with escapes on purpose: a literal control byte is invisible
+// in a diff and this is the regex that stops header injection.
+const CONTROL = /[\u0000-\u001f\u007f]/
+const ADDRESS = /^(?=.{3,254}$)[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i
+const NAME = /^[^"<>,;:\\\u0000-\u001f\u007f]{1,128}$/
+const KEY = /^[A-Za-z0-9._:-]{1,128}$/
+const KIND = /^[a-z][a-z0-9-]{0,31}$/
+const ADDRESS_BYTES = 254
+const SUBJECT_BYTES = 255
+const NAME_BYTES = 128
+const KEY_BYTES = 128
+const KIND_BYTES = 32
+const BODY_BYTES = 262_144
+const TIMEOUT = 10_000
+const WORD_BYTES = 45
+
+const bytes = (value: string) => Buffer.byteLength(value, 'utf8')
+const refusal = (code: RefusalCode): never => {
+	throw new Refused(code)
+}
+
+const mailbox = (recipient: Recipient, code: 'invalid-sender' | 'invalid-recipient'): Address => {
+	const address = typeof recipient === 'string' ? recipient : recipient?.address
+	const name = typeof recipient === 'string' ? undefined : recipient?.name
+
+	if (typeof address !== 'string') refusal(code)
+	if (CONTROL.test(address) || !ADDRESS.test(address) || bytes(address) > ADDRESS_BYTES) {
+		refusal(code)
+	}
+	if (name !== undefined) {
+		if (
+			typeof name !== 'string'
+			|| CONTROL.test(name)
+			|| !NAME.test(name)
+			|| bytes(name) > NAME_BYTES
+		) {
+			refusal('invalid-name')
+		}
+	}
+
+	return Object.freeze({
+		address,
+		...(name !== undefined && { name }),
+	})
+}
+
+const duration = (value: number | undefined) => {
+	const timeout = value ?? TIMEOUT
+	if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 2_147_483_647) {
+		refusal('invalid-config')
+	}
+	return timeout
+}
+
+const bodyLimit = (value: number | undefined) => {
+	const limit = value ?? BODY_BYTES
+	if (!Number.isSafeInteger(limit) || limit <= 0 || limit > BODY_BYTES) refusal('invalid-config')
+	return limit
+}
+
+const expiry = (value: Date | number | undefined) => {
+	if (value === undefined) return Infinity
+	const time = value instanceof Date ? value.getTime() : value
+	return typeof time === 'number' && Number.isFinite(time) ? time : refusal('expired')
+}
+
+/** Validates once, on the way in. Every later stage consumes only the result. */
+export function seal(message: Message, policy: Policy): Sealed {
+	if (!message || typeof message !== 'object' || !policy || typeof policy !== 'object') {
+		refusal('invalid-config')
+	}
+
+	const toRecipient = message.to
+	const subject = message.subject
+	const text = message.text
+	const html = message.html
+	const fromRecipient = message.from
+	const messageReply = message.replyTo
+	const rawKind = message.kind
+	const key = message.key
+	const expires = message.expires
+	const policyFrom = policy.from
+	const policyReply = policy.replyTo
+	const policyTimeout = policy.timeout
+	const policyLimit = policy.limit
+	const now = Date.now()
+	const deadline = Math.min(now + duration(policyTimeout), expiry(expires))
+	const limit = bodyLimit(policyLimit)
+	const from = mailbox(fromRecipient ?? policyFrom, 'invalid-sender')
+	const to = mailbox(toRecipient, 'invalid-recipient')
+	const replyRecipient = messageReply ?? policyReply
+	const replyTo = replyRecipient === undefined
+		? undefined
+		: mailbox(replyRecipient, 'invalid-recipient')
+	const kind = rawKind ?? 'mail'
+
+	if (
+		typeof subject !== 'string'
+		|| !subject
+		|| CONTROL.test(subject)
+		|| bytes(subject) > SUBJECT_BYTES
+	) {
+		refusal('invalid-subject')
+	}
+	if (
+		typeof kind !== 'string'
+		|| CONTROL.test(kind)
+		|| !KIND.test(kind)
+		|| bytes(kind) > KIND_BYTES
+	) {
+		refusal('invalid-kind')
+	}
+	if (
+		key !== undefined
+		&& (
+			typeof key !== 'string'
+			|| CONTROL.test(key)
+			|| !KEY.test(key)
+			|| bytes(key) > KEY_BYTES
+		)
+	) {
+		refusal('invalid-key')
+	}
+	if (
+		typeof text !== 'string'
+		|| (html !== undefined && typeof html !== 'string')
+		|| (!text && !html)
+	) {
+		refusal('empty-body')
+	}
+	if (bytes(text) + bytes(html ?? '') > limit) refusal('too-large')
+	if (deadline <= Date.now()) refusal('expired')
+
+	const signal = AbortSignal.timeout(Math.max(0, Math.ceil(deadline - Date.now())))
+	return Object.freeze({
+		id: randomUUID(),
+		kind,
+		from,
+		to,
+		...(replyTo && { replyTo }),
+		subject,
+		text,
+		...(html !== undefined && { html }),
+		...(key !== undefined && { key }),
+		deadline,
+		signal,
+	}) as Sealed
+}
+
+/** Returns the recipient domain, the only address part safe for logs. */
+export function domain(address: string): string {
+	return address.slice(address.lastIndexOf('@') + 1).toLowerCase()
+}
+
+/** Encodes and folds a value into RFC 2047 encoded-words of at most 75 characters. */
+export function encode(value: string): string {
+	const chunks: string[] = []
+	let chunk = ''
+	let size = 0
+
+	for (const character of value) {
+		const width = bytes(character)
+		if (size + width > WORD_BYTES && chunk) {
+			chunks.push(chunk)
+			chunk = ''
+			size = 0
+		}
+		chunk += character
+		size += width
+	}
+	chunks.push(chunk)
+
+	return chunks
+		.map(part => `=?UTF-8?B?${Buffer.from(part, 'utf8').toString('base64')}?=`)
+		.join('\r\n ')
+}

package/src/smtp.ts

@@ -0,0 +1,315 @@
+import { isIP, Socket } from 'node:net'
+import { connect as connectTls } from 'node:tls'
+import { createTransport } from 'nodemailer'
+import { Refused, Undelivered } from './errors'
+import type { Receipt, Transport } from './index'
+import type { Sealed } from './seal'
+
+/**
+ * Discrete credential fields on purpose. There is no `url` option: a
+ * smtp://user:pass@host string leaks into config dumps, error text and issue
+ * trackers far more casually than a `pass` field does.
+ *
+ * There is no `insecure` flag, no `requireTls: false`, no NODE_TLS_REJECT_UNAUTHORIZED
+ * accommodation. STARTTLS is required, the certificate is verified, the floor is
+ * TLS 1.2, and none of that is configurable. Local development uses capture().
+ */
+export interface SmtpOptions {
+	host: string
+	/** Default 587. Use 465 with implicit: true. */
+	port?: number
+	/** Implicit TLS from the first byte (465). Default false: plaintext connect + required STARTTLS. */
+	implicit?: boolean
+	user?: string
+	pass?: string
+	/** EHLO name. Defaults to the sender's domain, so the host name never leaves the box. */
+	name?: string
+}
+
+interface Configuration {
+	readonly host: string
+	readonly port: number
+	readonly implicit: boolean
+	readonly user?: string
+	readonly pass?: string
+	readonly name?: string
+}
+
+const CONTROL = /[\u0000-\u001f\u007f]/
+const VERIFY_TIMEOUT = 10_000
+
+type SocketOptions = {
+	readonly connection: Socket
+	readonly secured?: boolean
+}
+
+type SocketCallback = (error: Error | null, options?: SocketOptions) => void
+
+const configuration = (options: SmtpOptions): Configuration => {
+	if (!options || typeof options !== 'object') throw new Refused('invalid-config')
+
+	const host = options.host
+	const port = options.port ?? 587
+	const implicit = options.implicit ?? false
+	const user = options.user
+	const pass = options.pass
+	const name = options.name
+
+	if (
+		typeof host !== 'string'
+		|| !host
+		|| host !== host.trim()
+		|| host.length > 253
+		|| CONTROL.test(host)
+		|| /\s/.test(host)
+		|| !Number.isInteger(port)
+		|| port < 1
+		|| port > 65_535
+		|| typeof implicit !== 'boolean'
+		|| (user !== undefined && (typeof user !== 'string' || !user))
+		|| (pass !== undefined && (typeof pass !== 'string' || !pass))
+		|| (user === undefined) !== (pass === undefined)
+		|| (
+			name !== undefined
+			&& (
+				typeof name !== 'string'
+				|| !name
+				|| name !== name.trim()
+				|| name.length > 253
+				|| CONTROL.test(name)
+				|| /\s/.test(name)
+			)
+		)
+	) {
+		throw new Refused('invalid-config')
+	}
+
+	return Object.freeze({
+		host,
+		port,
+		implicit,
+		...(user !== undefined && { user, pass }),
+		...(name !== undefined && { name }),
+	})
+}
+
+const connector = (
+	config: Configuration,
+	own: (socket: Socket) => void,
+) =>
+	(_options: unknown, callback: SocketCallback) => {
+		let settled = false
+		let socket: Socket
+		const finish = (error: Error | null, options?: SocketOptions) => {
+			if (settled) return
+			settled = true
+			callback(error, options)
+		}
+
+		if (config.implicit) {
+			socket = connectTls({
+				host: config.host,
+				port: config.port,
+				...(isIP(config.host) === 0 && { servername: config.host }),
+				rejectUnauthorized: true,
+				minVersion: 'TLSv1.2',
+			}, () => finish(null, {
+				connection: socket,
+				secured: true,
+			}))
+		} else {
+			socket = new Socket()
+			socket.connect(config.port, config.host, () => finish(null, {
+				connection: socket,
+			}))
+		}
+
+		own(socket)
+		socket.on('error', () => {
+			if (!settled) {
+				finish(Object.assign(new Error('SMTP connection failed'), {
+					code: config.implicit ? 'ETLS' : 'ESOCKET',
+				}))
+			}
+		})
+	}
+
+const settings = (
+	config: Configuration,
+	name: string,
+	timeout: number,
+	own: (socket: Socket) => void,
+) => ({
+	host: config.host,
+	port: config.port,
+	secure: config.implicit,
+	pool: false,
+	requireTLS: !config.implicit,
+	ignoreTLS: false,
+	opportunisticTLS: false,
+	name,
+	...(config.user !== undefined && {
+		auth: {
+			user: config.user,
+			pass: config.pass!,
+		},
+	}),
+	connectionTimeout: timeout,
+	greetingTimeout: timeout,
+	socketTimeout: timeout,
+	dnsTimeout: timeout,
+	tls: {
+		rejectUnauthorized: true,
+		minVersion: 'TLSv1.2' as const,
+	},
+	disableFileAccess: true,
+	disableUrlAccess: true,
+	logger: false,
+	debug: false,
+	transactionLog: false,
+	getSocket: connector(config, own),
+})
+
+const remaining = (deadline: number) => {
+	const value = Math.ceil(deadline - Date.now())
+	return value > 0 ? Math.min(value, 2_147_483_647) : 0
+}
+
+const bounded = <T>(work: Promise<T>, signal: AbortSignal, close: () => void) =>
+	new Promise<T>((resolve, reject) => {
+		const stop = () => {
+			close()
+			reject(new Undelivered('timeout', true))
+		}
+
+		if (signal.aborted) return stop()
+
+		signal.addEventListener('abort', stop, { once: true })
+		work.then(
+			value => {
+				signal.removeEventListener('abort', stop)
+				resolve(value)
+			},
+			error => {
+				signal.removeEventListener('abort', stop)
+				reject(error)
+			},
+		)
+	})
+
+/** SMTP reply-code mapping. Note the parentheses: this is where a precedence bug hides. */
+const reply = (error: unknown): Undelivered => {
+	const value = (error ?? {}) as {
+		code?: unknown
+		command?: unknown
+		responseCode?: unknown
+	}
+	const code = typeof value.code === 'string' ? value.code : ''
+	const command = typeof value.command === 'string' ? value.command : ''
+	const status = typeof value.responseCode === 'number' ? value.responseCode : undefined
+	const hint = status === undefined ? undefined : `smtp ${status}`
+
+	if (code === 'EAUTH' || status === 530 || status === 535) return new Undelivered('auth', false, hint)
+	if (code === 'ETLS' || code.startsWith('ERR_TLS') || code.includes('CERT')) {
+		return new Undelivered('tls', false)
+	}
+	if (code === 'ESOCKET' && command === 'CONN') return new Undelivered('tls', false)
+	if (code === 'ETIMEDOUT' || (code === 'ECONNECTION' && status === undefined)) {
+		return new Undelivered('timeout', true)
+	}
+	if (status !== undefined && status >= 400 && status < 500) {
+		return new Undelivered('throttled', true, hint)
+	}
+	if (status !== undefined && status >= 500) return new Undelivered('rejected', false, hint)
+	if (code) return new Undelivered('connection', true)
+
+	return new Undelivered('unknown', false)
+}
+
+/**
+ * Creates a one-connection-per-message SMTP transport with mandatory verified
+ * TLS, deadline-derived socket timeouts and sanitized failure classifications.
+ */
+export function smtp(options: SmtpOptions): Transport {
+	const config = configuration(options)
+
+	const send = async (mail: Sealed): Promise<Receipt | void> => {
+		const timeout = remaining(mail.deadline)
+		if (!timeout) throw new Undelivered('timeout', true)
+
+		let mailer: ReturnType<typeof createTransport> | undefined
+		let socket: Socket | undefined
+		let closed = false
+		const own = (value: Socket) => {
+			socket = value
+			if (closed) value.destroy()
+		}
+		const close = () => {
+			if (closed) return
+			closed = true
+			socket?.destroy()
+			mailer?.close()
+		}
+
+		try {
+			const name = config.name ?? mail.from.address.slice(mail.from.address.lastIndexOf('@') + 1)
+			mailer = createTransport(settings(config, name, timeout, own))
+			const result = await bounded<{ messageId?: unknown }>(mailer.sendMail({
+				from: mail.from,
+				to: mail.to,
+				...(mail.replyTo && { replyTo: mail.replyTo }),
+				subject: mail.subject,
+				text: mail.text,
+				...(mail.html !== undefined && { html: mail.html }),
+				envelope: {
+					from: mail.from.address,
+					to: [mail.to.address],
+				},
+				disableFileAccess: true,
+				disableUrlAccess: true,
+			}) as Promise<{ messageId?: unknown }>, mail.signal, close)
+
+			return typeof result.messageId === 'string' && result.messageId
+				? { id: result.messageId }
+				: undefined
+		} catch (error) {
+			if (error instanceof Undelivered) throw error
+			throw reply(error)
+		} finally {
+			close()
+		}
+	}
+
+	const verify = async (signal: AbortSignal): Promise<void> => {
+		if (signal.aborted) throw new Undelivered('timeout', true)
+
+		let mailer: ReturnType<typeof createTransport> | undefined
+		let socket: Socket | undefined
+		let closed = false
+		const own = (value: Socket) => {
+			socket = value
+			if (closed) value.destroy()
+		}
+		const close = () => {
+			if (closed) return
+			closed = true
+			socket?.destroy()
+			mailer?.close()
+		}
+
+		try {
+			mailer = createTransport(settings(config, config.name ?? config.host, VERIFY_TIMEOUT, own))
+			await bounded(mailer.verify(), signal, close)
+		} catch (error) {
+			if (error instanceof Undelivered) throw error
+			throw reply(error)
+		} finally {
+			close()
+		}
+	}
+
+	return Object.assign(send, {
+		label: 'smtp',
+		verify,
+	})
+}