@upyo/smtp 0.5.1 → 0.5.3

package/README.md

@@ -115,6 +115,12 @@ Configuration options
 | `poolSize`          | `number`         | `5`           | Maximum pool connections         |
 | `dkim`              | `DkimConfig`     |               | DKIM signing configuration       |
 
+For non-loopback hosts, SMTP authentication requires either an implicit TLS
+connection (`secure: true`) or a successful STARTTLS upgrade (`secure: false`).
+If the server does not advertise STARTTLS, delivery returns a failed receipt
+without transmitting passwords or OAuth 2.0 access tokens.  Cleartext
+authentication to loopback hosts remains available for local development.
+
 ### `SmtpAuth`
 
 `SmtpAuth` is a discriminated union of three strategies.

package/dist/index.cjs

@@ -374,14 +374,92 @@ const CRLF_LENGTH = 2;
 */
 const QUIT_TIMEOUT_MS = 5e3;
 /**
-* Whether a host refers to the local loopback interface, for which cleartext
-* OAuth 2.0 authentication is permitted (e.g. local testing and development).
+* Parse an IPv4 address into its four octets.
 *
-* @param host The host to check.
-* @returns `true` if the host is a loopback address.
+* @param address The IPv4 address to parse.
+* @returns The parsed octets, or `null` if the address is invalid.
+*/
+function parseIpv4Address(address) {
+	const octets = address.split(".");
+	if (octets.length !== 4 || !octets.every((octet) => /^(?:0|[1-9]\d{0,2})$/.test(octet) && Number(octet) <= 255)) return null;
+	return octets.map(Number);
+}
+/**
+* Parse an IPv6 address into its eight 16-bit groups.
+*
+* @param address The IPv6 address to parse.
+* @returns The parsed groups, or `null` if the address is invalid.
+*/
+function parseIpv6Address(address) {
+	const compressionParts = address.split("::");
+	if (compressionParts.length > 2) return null;
+	function parseGroups(part) {
+		if (part === "") return [];
+		const tokens = part.split(":");
+		const groups = [];
+		for (const [index, token] of tokens.entries()) if (token.includes(".")) {
+			if (index !== tokens.length - 1) return null;
+			const octets = parseIpv4Address(token);
+			if (octets == null) return null;
+			groups.push(octets[0] << 8 | octets[1], octets[2] << 8 | octets[3]);
+		} else if (/^[0-9a-f]{1,4}$/.test(token)) groups.push(Number.parseInt(token, 16));
+		else return null;
+		return groups;
+	}
+	const left = parseGroups(compressionParts[0]);
+	const right = parseGroups(compressionParts[1] ?? "");
+	if (left == null || right == null) return null;
+	if (compressionParts.length === 1) return left.length === 8 ? left : null;
+	const omittedGroups = 8 - left.length - right.length;
+	if (omittedGroups < 1) return null;
+	return [
+		...left,
+		...Array.from({ length: omittedGroups }, () => 0),
+		...right
+	];
+}
+/**
+* Whether an IP address refers to the local loopback interface.
+*
+* @param address The IPv4 or IPv6 address to check.
+* @returns `true` if the address is a loopback address.
+*/
+function isLoopbackAddress(address) {
+	let normalized = address.toLowerCase();
+	if (normalized.startsWith("[") && normalized.endsWith("]")) normalized = normalized.slice(1, -1);
+	const zoneIndex = normalized.indexOf("%");
+	if (zoneIndex >= 0) normalized = normalized.slice(0, zoneIndex);
+	const ipv4Octets = parseIpv4Address(normalized);
+	if (ipv4Octets != null) return ipv4Octets[0] === 127;
+	const ipv6Groups = parseIpv6Address(normalized);
+	if (ipv6Groups == null) return false;
+	return ipv6Groups.slice(0, 7).every((group) => group === 0) && ipv6Groups[7] === 1 || ipv6Groups.slice(0, 5).every((group) => group === 0) && ipv6Groups[5] === 65535 && ipv6Groups[6] >> 8 === 127;
+}
+/**
+* Whether a configured host name or address represents a loopback endpoint.
+*
+* This is a fallback for sockets that do not expose their connected peer
+* address.  A connected peer address takes precedence so a misleading host
+* name cannot bypass the TLS requirement.
+*
+* @param host The configured SMTP host.
+* @returns `true` if the host represents a loopback endpoint.
 */
 function isLoopbackHost(host) {
-	return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+	const normalized = host.toLowerCase().replace(/\.$/, "");
+	return normalized === "localhost" || normalized.endsWith(".localhost") || isLoopbackAddress(normalized);
+}
+/**
+* Whether the SMTP connection is local enough to permit cleartext
+* authentication during development.
+*
+* @param socket The connected SMTP socket, if available.
+* @param host The configured SMTP host.
+* @returns `true` if the connected peer or fallback host is loopback.
+*/
+function isLoopbackConnection(socket, host) {
+	const remoteAddress = socket?.remoteAddress;
+	return remoteAddress == null ? isLoopbackHost(host) : isLoopbackAddress(remoteAddress);
 }
 var SmtpConnection = class {
 	socket = null;
@@ -514,6 +592,12 @@ var SmtpConnection = class {
 	}
 	async ehlo(signal) {
 		const response = await this.sendCommand(`EHLO ${this.config.localName}`, signal);
+		if (response.code === 500 || response.code === 502) {
+			const heloResponse = await this.sendCommand(`HELO ${this.config.localName}`, signal);
+			if (heloResponse.code !== 250) throw new Error(`HELO failed: ${heloResponse.message}`);
+			this.capabilities = [];
+			return;
+		}
 		if (response.code !== 250) throw new Error(`EHLO failed: ${response.message}`);
 		this.capabilities = response.raw.split("\r\n").filter((line) => line.startsWith("250-") || line.startsWith("250 ")).map((line) => line.substring(4)).filter((line) => line.length > 0);
 	}
@@ -565,8 +649,8 @@ var SmtpConnection = class {
 		if (!auth) return;
 		if (this.authenticated) return;
 		if (!this.capabilities.some((cap) => cap.toUpperCase().startsWith("AUTH"))) throw new SmtpAuthError("Server does not support authentication.");
+		if (!(this.socket instanceof node_tls.TLSSocket) && !isLoopbackConnection(this.socket, this.config.host)) throw new SmtpAuthError("SMTP authentication requires a TLS-secured connection to protect credentials; use `secure: true` or STARTTLS.");
 		if ("accessToken" in auth || "refreshToken" in auth) {
-			if (!(this.socket instanceof node_tls.TLSSocket) && !isLoopbackHost(this.config.host)) throw new SmtpAuthError("OAuth 2.0 authentication requires a TLS-secured connection to protect the access token; use `secure: true` or STARTTLS.");
 			const mechanism = auth.method ?? selectOAuth2Mechanism(this.capabilities);
 			switch (mechanism) {
 				case "xoauth2":
@@ -670,10 +754,22 @@ var SmtpConnection = class {
 	async sendMessage(message, signal) {
 		const mailResponse = await this.sendCommand(`MAIL FROM:<${message.envelope.from}>`, signal);
 		if (mailResponse.code !== 250) throw new SmtpResponseError(`MAIL FROM failed: ${mailResponse.message}`, mailResponse.code, "MAIL FROM", mailResponse.message);
+		const rejectedRecipients = [];
 		for (const recipient of message.envelope.to) {
 			signal?.throwIfAborted();
 			const rcptResponse = await this.sendCommand(`RCPT TO:<${recipient}>`, signal);
-			if (rcptResponse.code !== 250) throw new SmtpResponseError(`RCPT TO failed for ${recipient}: ${rcptResponse.message}`, rcptResponse.code, "RCPT TO", rcptResponse.message);
+			if (rcptResponse.code === 421) throw new SmtpResponseError(`RCPT TO failed for ${recipient}: ${rcptResponse.message}`, rcptResponse.code, "RCPT TO", rcptResponse.message);
+			if (rcptResponse.code !== 250 && rcptResponse.code !== 251) rejectedRecipients.push({
+				recipient,
+				code: rcptResponse.code,
+				response: rcptResponse.message,
+				retryable: rcptResponse.code >= 400 && rcptResponse.code < 500
+			});
+		}
+		if (rejectedRecipients.length > 0 && rejectedRecipients.length === message.envelope.to.length) {
+			const rejection = rejectedRecipients.find((item) => item.retryable) ?? rejectedRecipients[0];
+			const details = rejectedRecipients.map((item) => `${item.recipient}: ${item.code} ${item.response}`).join("; ");
+			throw new SmtpResponseError(`RCPT TO failed for every recipient: ${details}`, rejection.code, "RCPT TO", rejection.response, rejectedRecipients);
 		}
 		const dataResponse = await this.sendCommand("DATA", signal);
 		if (dataResponse.code !== 354) throw new SmtpResponseError(`DATA failed: ${dataResponse.message}`, dataResponse.code, "DATA", dataResponse.message);
@@ -681,7 +777,10 @@ var SmtpConnection = class {
 		const finalResponse = await this.sendCommand(`${content}\r\n.`, signal);
 		if (finalResponse.code !== 250) throw new SmtpResponseError(`Message send failed: ${finalResponse.message}`, finalResponse.code, "DATA_END", finalResponse.message);
 		const messageId = this.extractMessageId(finalResponse.message);
-		return messageId;
+		return {
+			messageId,
+			rejectedRecipients
+		};
 	}
 	extractMessageId(response) {
 		const match = response.match(/(?:Message-ID:|id=)[\s<]*([^>\s]+)/i);
@@ -737,6 +836,8 @@ var SmtpResponseError = class extends Error {
 	* The textual SMTP reply returned by the server.
 	*/
 	response;
+	/** Recipient-level failures collected for an unsuccessful transaction. */
+	rejectedRecipients;
 	/**
 	* Creates an SMTP response error.
 	*
@@ -744,13 +845,16 @@ var SmtpResponseError = class extends Error {
 	* @param code The numeric SMTP reply code.
 	* @param command The SMTP command that produced the reply.
 	* @param response The textual SMTP reply returned by the server.
+	* @param rejectedRecipients Recipient-level failures collected for the
+	*                           transaction.
 	*/
-	constructor(message, code, command, response) {
+	constructor(message, code, command, response, rejectedRecipients) {
 		super(message);
 		this.name = "SmtpResponseError";
 		this.code = code;
 		this.command = command;
 		this.response = response;
+		this.rejectedRecipients = rejectedRecipients;
 	}
 };
 /**
@@ -1052,6 +1156,15 @@ function arrayBufferToBase64(buffer) {
 
 //#endregion
 //#region src/message-converter.ts
+/**
+* Converts a message to its SMTP envelope and wire representation.
+*
+* @param message The message to convert.
+* @param dkimConfig Optional DKIM signing configuration.
+* @returns The converted SMTP message.
+* @throws {RangeError} If a header contains a token that cannot be folded
+* within the RFC 5322 hard line-length limit.
+*/
 async function convertMessage(message, dkimConfig) {
 	const envelope = {
 		from: message.sender.address,
@@ -1083,11 +1196,11 @@ async function buildRawMessage(message) {
 	const hasHtml = "html" in message.content;
 	const hasText = "text" in message.content;
 	const isMultipart = hasAttachments || hasHtml && hasText;
-	lines.push(`From: ${encodeAddress(message.sender)}`);
-	lines.push(`To: ${message.recipients.map(encodeAddress).join(", ")}`);
-	if (message.ccRecipients.length > 0) lines.push(`Cc: ${message.ccRecipients.map(encodeAddress).join(", ")}`);
-	if (message.replyRecipients.length > 0) lines.push(`Reply-To: ${message.replyRecipients.map(encodeAddress).join(", ")}`);
-	lines.push(`Subject: ${encodeHeaderValue(message.subject)}`);
+	lines.push(foldHeader("From", encodeAddress(message.sender)));
+	lines.push(foldHeader("To", message.recipients.map(encodeAddress).join(", ")));
+	if (message.ccRecipients.length > 0) lines.push(foldHeader("Cc", message.ccRecipients.map(encodeAddress).join(", ")));
+	if (message.replyRecipients.length > 0) lines.push(foldHeader("Reply-To", message.replyRecipients.map(encodeAddress).join(", ")));
+	lines.push(foldHeader("Subject", encodeHeaderValue(message.subject, true)));
 	lines.push(`Date: ${(/* @__PURE__ */ new Date()).toUTCString()}`);
 	lines.push(`Message-ID: <${generateMessageId()}>`);
 	if (message.priority !== "normal") {
@@ -1095,7 +1208,7 @@ async function buildRawMessage(message) {
 		lines.push(`X-Priority: ${priorityValue}`);
 		lines.push(`X-MSMail-Priority: ${message.priority === "high" ? "High" : "Low"}`);
 	}
-	for (const [key, value] of message.headers) lines.push(`${key}: ${encodeHeaderValue(value)}`);
+	for (const [key, value] of message.headers) lines.push(foldHeader(key, encodeHeaderValue(value)));
 	lines.push("MIME-Version: 1.0");
 	if (isMultipart) {
 		lines.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
@@ -1134,12 +1247,12 @@ async function buildRawMessage(message) {
 		for (const attachment of message.attachments) {
 			lines.push("");
 			lines.push(`--${boundary}`);
-			lines.push(`Content-Type: ${attachment.contentType}; name="${attachment.filename}"`);
+			lines.push(foldHeader("Content-Type", `${attachment.contentType}; ${encodeMimeParameter("name", attachment.filename)}`));
 			lines.push("Content-Transfer-Encoding: base64");
 			if (attachment.inline) {
-				lines.push(`Content-Disposition: inline; filename="${attachment.filename}"`);
+				lines.push(foldHeader("Content-Disposition", `inline; ${encodeMimeParameter("filename", attachment.filename)}`));
 				lines.push(`Content-ID: <${attachment.contentId}>`);
-			} else lines.push(`Content-Disposition: attachment; filename="${attachment.filename}"`);
+			} else lines.push(foldHeader("Content-Disposition", `attachment; ${encodeMimeParameter("filename", attachment.filename)}`));
 			lines.push("");
 			lines.push(encodeBase64(await attachment.content));
 		}
@@ -1168,32 +1281,85 @@ function generateMessageId() {
 }
 function encodeAddress(address) {
 	if (address.name == null) return address.address;
-	const encodedDisplayName = encodeHeaderValue(address.name);
+	const encodedDisplayName = encodeHeaderValue(address.name, true);
 	return `${encodedDisplayName} <${address.address}>`;
 }
-function encodeHeaderValue(value) {
-	if (!/^[\x20-\x7E]*$/.test(value)) {
-		const utf8Bytes = new TextEncoder().encode(value);
-		const base64 = node_buffer.Buffer.from(utf8Bytes).toString("base64");
+function encodeHeaderValue(value, encodeLongAsciiWords = false) {
+	const hasLongWord = value.split(/\s+/).some((word) => word.length > 60);
+	if (!/^[\x20-\x7E]*$/.test(value) || encodeLongAsciiWords && hasLongWord) {
+		const encodeWord = (text) => {
+			const utf8Bytes = new TextEncoder().encode(text);
+			const base64 = node_buffer.Buffer.from(utf8Bytes).toString("base64");
+			return `=?UTF-8?B?${base64}?=`;
+		};
 		const maxEncodedLength = 75;
-		const encodedWord = `=?UTF-8?B?${base64}?=`;
+		const encodedWord = encodeWord(value);
 		if (encodedWord.length <= maxEncodedLength) return encodedWord;
 		const words = [];
-		let currentBase64 = "";
-		for (let i = 0; i < base64.length; i += 4) {
-			const chunk = base64.slice(i, i + 4);
-			const testWord = `=?UTF-8?B?${currentBase64}${chunk}?=`;
-			if (testWord.length <= maxEncodedLength) currentBase64 += chunk;
+		let currentText = "";
+		for (const character of value) {
+			const candidate = currentText + character;
+			if (encodeWord(candidate).length <= maxEncodedLength) currentText = candidate;
 			else {
-				if (currentBase64) words.push(`=?UTF-8?B?${currentBase64}?=`);
-				currentBase64 = chunk;
+				if (currentText.length > 0) words.push(encodeWord(currentText));
+				currentText = character;
 			}
 		}
-		if (currentBase64) words.push(`=?UTF-8?B?${currentBase64}?=`);
+		if (currentText.length > 0) words.push(encodeWord(currentText));
 		return words.join(" ");
 	}
 	return value;
 }
+function encodeMimeParameter(name, value) {
+	const escapedValue = value.replace(/[\\"]/g, "\\$&");
+	const quotedParameter = `${name}="${escapedValue}"`;
+	if (/^[\x20-\x7E]*$/.test(value) && quotedParameter.length <= 60) return quotedParameter;
+	const encodedBytes = Array.from(new TextEncoder().encode(value), (byte) => {
+		const character = String.fromCharCode(byte);
+		return /^[A-Za-z0-9!#$&+.^_`|~-]$/.test(character) ? character : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+	});
+	const segments = [];
+	let segment = "";
+	for (const encodedByte of encodedBytes) {
+		if (segment.length + encodedByte.length > 45) {
+			segments.push(segment);
+			segment = "";
+		}
+		segment += encodedByte;
+	}
+	if (segment.length > 0 || segments.length === 0) segments.push(segment);
+	return segments.map((part, index) => `${name}*${index}*=${index === 0 ? "UTF-8''" : ""}${part}`).join("; ");
+}
+function foldHeader(name, value) {
+	const recommendedLineLength = 78;
+	const lines = [];
+	let prefix = `${name}: `;
+	let remaining = value;
+	while (prefix.length + remaining.length > recommendedLineLength) {
+		const availableLength = recommendedLineLength - prefix.length;
+		let breakIndex = -1;
+		for (let index = Math.min(availableLength, remaining.length - 1); index >= 0; index--) if (remaining[index] === " " || remaining[index] === "	") {
+			breakIndex = index;
+			break;
+		}
+		if (breakIndex < 0) {
+			for (let index = Math.max(availableLength + 1, 0); index < remaining.length; index++) if (remaining[index] === " " || remaining[index] === "	") {
+				breakIndex = index;
+				break;
+			}
+		}
+		if (breakIndex < 0) break;
+		let whitespaceEnd = breakIndex + 1;
+		while (whitespaceEnd < remaining.length && (remaining[whitespaceEnd] === " " || remaining[whitespaceEnd] === "	")) whitespaceEnd++;
+		if (whitespaceEnd === remaining.length) break;
+		lines.push(prefix + remaining.slice(0, breakIndex));
+		prefix = remaining.slice(breakIndex, whitespaceEnd);
+		remaining = remaining.slice(whitespaceEnd);
+	}
+	lines.push(prefix + remaining);
+	if (lines.some((line) => line.length > 998)) throw new RangeError(`Header field ${name} contains a token too long to fold.`);
+	return lines.join("\r\n");
+}
 function encodeQuotedPrintable(text) {
 	const utf8Bytes = new TextEncoder().encode(text);
 	let result = "";
@@ -1324,12 +1490,13 @@ var SmtpTransport = class {
 			options?.signal?.throwIfAborted();
 			const smtpMessage = await convertMessage(message, this.config.dkim);
 			options?.signal?.throwIfAborted();
-			const messageId = await connection.sendMessage(smtpMessage, options?.signal);
+			const result = await connection.sendMessage(smtpMessage, options?.signal);
 			await this.returnConnection(connection);
 			return {
 				successful: true,
-				messageId,
-				provider: "smtp"
+				messageId: result.messageId,
+				provider: "smtp",
+				rejectedRecipients: result.rejectedRecipients
 			};
 		} catch (error) {
 			if (connection != null) await this.discardConnection(connection);
@@ -1393,11 +1560,12 @@ var SmtpTransport = class {
 				try {
 					const smtpMessage = await convertMessage(message, this.config.dkim);
 					options?.signal?.throwIfAborted();
-					const messageId = await connection.sendMessage(smtpMessage, options?.signal);
+					const result = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
 						successful: true,
-						messageId,
-						provider: "smtp"
+						messageId: result.messageId,
+						provider: "smtp",
+						rejectedRecipients: result.rejectedRecipients
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
@@ -1414,11 +1582,12 @@ var SmtpTransport = class {
 				try {
 					const smtpMessage = await convertMessage(message, this.config.dkim);
 					options?.signal?.throwIfAborted();
-					const messageId = await connection.sendMessage(smtpMessage, options?.signal);
+					const result = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
 						successful: true,
-						messageId,
-						provider: "smtp"
+						messageId: result.messageId,
+						provider: "smtp",
+						rejectedRecipients: result.rejectedRecipients
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
@@ -1527,7 +1696,8 @@ function createSmtpFailure(message, error) {
 			attempts: 1,
 			providerDetails: {
 				command: error.command,
-				response: error.response
+				response: error.response,
+				rejectedRecipients: error.rejectedRecipients
 			}
 		});
 	}

package/dist/index.d.cts

@@ -408,6 +408,41 @@ interface SmtpTlsOptions {
  * used internally by the SMTP transport implementation.
  */
 //#endregion
+//#region src/smtp-receipt.d.ts
+/**
+ * An SMTP envelope recipient that the server rejected during an otherwise
+ * successful delivery.
+ *
+ * @since 0.5.3
+ */
+interface SmtpRejectedRecipient {
+  /** The rejected recipient address. */
+  readonly recipient: string;
+  /** The three-digit SMTP reply code. */
+  readonly code: number;
+  /** The SMTP server's reply text. */
+  readonly response: string;
+  /** Whether retrying delivery to this recipient may succeed. */
+  readonly retryable: boolean;
+}
+/**
+ * A receipt returned by {@link SmtpTransport}.
+ *
+ * Successful receipts list any recipients rejected before the message was
+ * delivered to the remaining accepted recipients.  Callers can retry delivery
+ * to entries marked as retryable without redelivering to accepted recipients.
+ *
+ * @since 0.5.3
+ */
+type SmtpReceipt = (Extract<Receipt<"smtp">, {
+  readonly successful: true;
+}> & {
+  /** Recipients excluded from an otherwise successful delivery. */
+  readonly rejectedRecipients: readonly SmtpRejectedRecipient[];
+}) | Extract<Receipt<"smtp">, {
+  readonly successful: false;
+}>;
+//#endregion
 //#region src/smtp-transport.d.ts
 /**
  * SMTP transport implementation for sending emails via SMTP protocol.
@@ -495,7 +530,7 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * @throws {DOMException} If the operation is aborted through
    *                        `options.signal`.
    */
-  send(message: Message, options?: TransportOptions): Promise<Receipt<"smtp">>;
+  send(message: Message, options?: TransportOptions): Promise<SmtpReceipt>;
   /**
    * Sends multiple email messages efficiently using a single SMTP connection.
    *
@@ -526,7 +561,7 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * @throws {DOMException} If the operation is aborted through
    *                        `options.signal`.
    */
-  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<"smtp">>;
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<SmtpReceipt>;
   private getConnection;
   private connectAndSetup;
   private returnConnection;
@@ -591,4 +626,4 @@ declare class SmtpAuthError extends Error {
  */
 
 //#endregion
-export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpTlsOptions, SmtpTransport, SmtpUserPassAuth };
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpReceipt, SmtpRejectedRecipient, SmtpTlsOptions, SmtpTransport, SmtpUserPassAuth };

package/dist/index.d.ts

@@ -408,6 +408,41 @@ interface SmtpTlsOptions {
  * used internally by the SMTP transport implementation.
  */
 //#endregion
+//#region src/smtp-receipt.d.ts
+/**
+ * An SMTP envelope recipient that the server rejected during an otherwise
+ * successful delivery.
+ *
+ * @since 0.5.3
+ */
+interface SmtpRejectedRecipient {
+  /** The rejected recipient address. */
+  readonly recipient: string;
+  /** The three-digit SMTP reply code. */
+  readonly code: number;
+  /** The SMTP server's reply text. */
+  readonly response: string;
+  /** Whether retrying delivery to this recipient may succeed. */
+  readonly retryable: boolean;
+}
+/**
+ * A receipt returned by {@link SmtpTransport}.
+ *
+ * Successful receipts list any recipients rejected before the message was
+ * delivered to the remaining accepted recipients.  Callers can retry delivery
+ * to entries marked as retryable without redelivering to accepted recipients.
+ *
+ * @since 0.5.3
+ */
+type SmtpReceipt = (Extract<Receipt<"smtp">, {
+  readonly successful: true;
+}> & {
+  /** Recipients excluded from an otherwise successful delivery. */
+  readonly rejectedRecipients: readonly SmtpRejectedRecipient[];
+}) | Extract<Receipt<"smtp">, {
+  readonly successful: false;
+}>;
+//#endregion
 //#region src/smtp-transport.d.ts
 /**
  * SMTP transport implementation for sending emails via SMTP protocol.
@@ -495,7 +530,7 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * @throws {DOMException} If the operation is aborted through
    *                        `options.signal`.
    */
-  send(message: Message, options?: TransportOptions): Promise<Receipt<"smtp">>;
+  send(message: Message, options?: TransportOptions): Promise<SmtpReceipt>;
   /**
    * Sends multiple email messages efficiently using a single SMTP connection.
    *
@@ -526,7 +561,7 @@ declare class SmtpTransport implements Transport<"smtp">, AsyncDisposable {
    * @throws {DOMException} If the operation is aborted through
    *                        `options.signal`.
    */
-  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<"smtp">>;
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<SmtpReceipt>;
   private getConnection;
   private connectAndSetup;
   private returnConnection;
@@ -591,4 +626,4 @@ declare class SmtpAuthError extends Error {
  */
 
 //#endregion
-export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpTlsOptions, SmtpTransport, SmtpUserPassAuth };
+export { DkimAlgorithm, DkimCanonicalization, DkimConfig, DkimSignature, DkimSigningFailureAction, OAuth2TokenProvider, SmtpAuth, SmtpAuthError, SmtpConfig, SmtpOAuth2Auth, SmtpOAuth2RefreshAuth, SmtpOAuth2TokenAuth, SmtpReceipt, SmtpRejectedRecipient, SmtpTlsOptions, SmtpTransport, SmtpUserPassAuth };

package/dist/index.js

@@ -351,14 +351,92 @@ const CRLF_LENGTH = 2;
 */
 const QUIT_TIMEOUT_MS = 5e3;
 /**
-* Whether a host refers to the local loopback interface, for which cleartext
-* OAuth 2.0 authentication is permitted (e.g. local testing and development).
+* Parse an IPv4 address into its four octets.
 *
-* @param host The host to check.
-* @returns `true` if the host is a loopback address.
+* @param address The IPv4 address to parse.
+* @returns The parsed octets, or `null` if the address is invalid.
+*/
+function parseIpv4Address(address) {
+	const octets = address.split(".");
+	if (octets.length !== 4 || !octets.every((octet) => /^(?:0|[1-9]\d{0,2})$/.test(octet) && Number(octet) <= 255)) return null;
+	return octets.map(Number);
+}
+/**
+* Parse an IPv6 address into its eight 16-bit groups.
+*
+* @param address The IPv6 address to parse.
+* @returns The parsed groups, or `null` if the address is invalid.
+*/
+function parseIpv6Address(address) {
+	const compressionParts = address.split("::");
+	if (compressionParts.length > 2) return null;
+	function parseGroups(part) {
+		if (part === "") return [];
+		const tokens = part.split(":");
+		const groups = [];
+		for (const [index, token] of tokens.entries()) if (token.includes(".")) {
+			if (index !== tokens.length - 1) return null;
+			const octets = parseIpv4Address(token);
+			if (octets == null) return null;
+			groups.push(octets[0] << 8 | octets[1], octets[2] << 8 | octets[3]);
+		} else if (/^[0-9a-f]{1,4}$/.test(token)) groups.push(Number.parseInt(token, 16));
+		else return null;
+		return groups;
+	}
+	const left = parseGroups(compressionParts[0]);
+	const right = parseGroups(compressionParts[1] ?? "");
+	if (left == null || right == null) return null;
+	if (compressionParts.length === 1) return left.length === 8 ? left : null;
+	const omittedGroups = 8 - left.length - right.length;
+	if (omittedGroups < 1) return null;
+	return [
+		...left,
+		...Array.from({ length: omittedGroups }, () => 0),
+		...right
+	];
+}
+/**
+* Whether an IP address refers to the local loopback interface.
+*
+* @param address The IPv4 or IPv6 address to check.
+* @returns `true` if the address is a loopback address.
+*/
+function isLoopbackAddress(address) {
+	let normalized = address.toLowerCase();
+	if (normalized.startsWith("[") && normalized.endsWith("]")) normalized = normalized.slice(1, -1);
+	const zoneIndex = normalized.indexOf("%");
+	if (zoneIndex >= 0) normalized = normalized.slice(0, zoneIndex);
+	const ipv4Octets = parseIpv4Address(normalized);
+	if (ipv4Octets != null) return ipv4Octets[0] === 127;
+	const ipv6Groups = parseIpv6Address(normalized);
+	if (ipv6Groups == null) return false;
+	return ipv6Groups.slice(0, 7).every((group) => group === 0) && ipv6Groups[7] === 1 || ipv6Groups.slice(0, 5).every((group) => group === 0) && ipv6Groups[5] === 65535 && ipv6Groups[6] >> 8 === 127;
+}
+/**
+* Whether a configured host name or address represents a loopback endpoint.
+*
+* This is a fallback for sockets that do not expose their connected peer
+* address.  A connected peer address takes precedence so a misleading host
+* name cannot bypass the TLS requirement.
+*
+* @param host The configured SMTP host.
+* @returns `true` if the host represents a loopback endpoint.
 */
 function isLoopbackHost(host) {
-	return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+	const normalized = host.toLowerCase().replace(/\.$/, "");
+	return normalized === "localhost" || normalized.endsWith(".localhost") || isLoopbackAddress(normalized);
+}
+/**
+* Whether the SMTP connection is local enough to permit cleartext
+* authentication during development.
+*
+* @param socket The connected SMTP socket, if available.
+* @param host The configured SMTP host.
+* @returns `true` if the connected peer or fallback host is loopback.
+*/
+function isLoopbackConnection(socket, host) {
+	const remoteAddress = socket?.remoteAddress;
+	return remoteAddress == null ? isLoopbackHost(host) : isLoopbackAddress(remoteAddress);
 }
 var SmtpConnection = class {
 	socket = null;
@@ -491,6 +569,12 @@ var SmtpConnection = class {
 	}
 	async ehlo(signal) {
 		const response = await this.sendCommand(`EHLO ${this.config.localName}`, signal);
+		if (response.code === 500 || response.code === 502) {
+			const heloResponse = await this.sendCommand(`HELO ${this.config.localName}`, signal);
+			if (heloResponse.code !== 250) throw new Error(`HELO failed: ${heloResponse.message}`);
+			this.capabilities = [];
+			return;
+		}
 		if (response.code !== 250) throw new Error(`EHLO failed: ${response.message}`);
 		this.capabilities = response.raw.split("\r\n").filter((line) => line.startsWith("250-") || line.startsWith("250 ")).map((line) => line.substring(4)).filter((line) => line.length > 0);
 	}
@@ -542,8 +626,8 @@ var SmtpConnection = class {
 		if (!auth) return;
 		if (this.authenticated) return;
 		if (!this.capabilities.some((cap) => cap.toUpperCase().startsWith("AUTH"))) throw new SmtpAuthError("Server does not support authentication.");
+		if (!(this.socket instanceof TLSSocket) && !isLoopbackConnection(this.socket, this.config.host)) throw new SmtpAuthError("SMTP authentication requires a TLS-secured connection to protect credentials; use `secure: true` or STARTTLS.");
 		if ("accessToken" in auth || "refreshToken" in auth) {
-			if (!(this.socket instanceof TLSSocket) && !isLoopbackHost(this.config.host)) throw new SmtpAuthError("OAuth 2.0 authentication requires a TLS-secured connection to protect the access token; use `secure: true` or STARTTLS.");
 			const mechanism = auth.method ?? selectOAuth2Mechanism(this.capabilities);
 			switch (mechanism) {
 				case "xoauth2":
@@ -647,10 +731,22 @@ var SmtpConnection = class {
 	async sendMessage(message, signal) {
 		const mailResponse = await this.sendCommand(`MAIL FROM:<${message.envelope.from}>`, signal);
 		if (mailResponse.code !== 250) throw new SmtpResponseError(`MAIL FROM failed: ${mailResponse.message}`, mailResponse.code, "MAIL FROM", mailResponse.message);
+		const rejectedRecipients = [];
 		for (const recipient of message.envelope.to) {
 			signal?.throwIfAborted();
 			const rcptResponse = await this.sendCommand(`RCPT TO:<${recipient}>`, signal);
-			if (rcptResponse.code !== 250) throw new SmtpResponseError(`RCPT TO failed for ${recipient}: ${rcptResponse.message}`, rcptResponse.code, "RCPT TO", rcptResponse.message);
+			if (rcptResponse.code === 421) throw new SmtpResponseError(`RCPT TO failed for ${recipient}: ${rcptResponse.message}`, rcptResponse.code, "RCPT TO", rcptResponse.message);
+			if (rcptResponse.code !== 250 && rcptResponse.code !== 251) rejectedRecipients.push({
+				recipient,
+				code: rcptResponse.code,
+				response: rcptResponse.message,
+				retryable: rcptResponse.code >= 400 && rcptResponse.code < 500
+			});
+		}
+		if (rejectedRecipients.length > 0 && rejectedRecipients.length === message.envelope.to.length) {
+			const rejection = rejectedRecipients.find((item) => item.retryable) ?? rejectedRecipients[0];
+			const details = rejectedRecipients.map((item) => `${item.recipient}: ${item.code} ${item.response}`).join("; ");
+			throw new SmtpResponseError(`RCPT TO failed for every recipient: ${details}`, rejection.code, "RCPT TO", rejection.response, rejectedRecipients);
 		}
 		const dataResponse = await this.sendCommand("DATA", signal);
 		if (dataResponse.code !== 354) throw new SmtpResponseError(`DATA failed: ${dataResponse.message}`, dataResponse.code, "DATA", dataResponse.message);
@@ -658,7 +754,10 @@ var SmtpConnection = class {
 		const finalResponse = await this.sendCommand(`${content}\r\n.`, signal);
 		if (finalResponse.code !== 250) throw new SmtpResponseError(`Message send failed: ${finalResponse.message}`, finalResponse.code, "DATA_END", finalResponse.message);
 		const messageId = this.extractMessageId(finalResponse.message);
-		return messageId;
+		return {
+			messageId,
+			rejectedRecipients
+		};
 	}
 	extractMessageId(response) {
 		const match = response.match(/(?:Message-ID:|id=)[\s<]*([^>\s]+)/i);
@@ -714,6 +813,8 @@ var SmtpResponseError = class extends Error {
 	* The textual SMTP reply returned by the server.
 	*/
 	response;
+	/** Recipient-level failures collected for an unsuccessful transaction. */
+	rejectedRecipients;
 	/**
 	* Creates an SMTP response error.
 	*
@@ -721,13 +822,16 @@ var SmtpResponseError = class extends Error {
 	* @param code The numeric SMTP reply code.
 	* @param command The SMTP command that produced the reply.
 	* @param response The textual SMTP reply returned by the server.
+	* @param rejectedRecipients Recipient-level failures collected for the
+	*                           transaction.
 	*/
-	constructor(message, code, command, response) {
+	constructor(message, code, command, response, rejectedRecipients) {
 		super(message);
 		this.name = "SmtpResponseError";
 		this.code = code;
 		this.command = command;
 		this.response = response;
+		this.rejectedRecipients = rejectedRecipients;
 	}
 };
 /**
@@ -1029,6 +1133,15 @@ function arrayBufferToBase64(buffer) {
 
 //#endregion
 //#region src/message-converter.ts
+/**
+* Converts a message to its SMTP envelope and wire representation.
+*
+* @param message The message to convert.
+* @param dkimConfig Optional DKIM signing configuration.
+* @returns The converted SMTP message.
+* @throws {RangeError} If a header contains a token that cannot be folded
+* within the RFC 5322 hard line-length limit.
+*/
 async function convertMessage(message, dkimConfig) {
 	const envelope = {
 		from: message.sender.address,
@@ -1060,11 +1173,11 @@ async function buildRawMessage(message) {
 	const hasHtml = "html" in message.content;
 	const hasText = "text" in message.content;
 	const isMultipart = hasAttachments || hasHtml && hasText;
-	lines.push(`From: ${encodeAddress(message.sender)}`);
-	lines.push(`To: ${message.recipients.map(encodeAddress).join(", ")}`);
-	if (message.ccRecipients.length > 0) lines.push(`Cc: ${message.ccRecipients.map(encodeAddress).join(", ")}`);
-	if (message.replyRecipients.length > 0) lines.push(`Reply-To: ${message.replyRecipients.map(encodeAddress).join(", ")}`);
-	lines.push(`Subject: ${encodeHeaderValue(message.subject)}`);
+	lines.push(foldHeader("From", encodeAddress(message.sender)));
+	lines.push(foldHeader("To", message.recipients.map(encodeAddress).join(", ")));
+	if (message.ccRecipients.length > 0) lines.push(foldHeader("Cc", message.ccRecipients.map(encodeAddress).join(", ")));
+	if (message.replyRecipients.length > 0) lines.push(foldHeader("Reply-To", message.replyRecipients.map(encodeAddress).join(", ")));
+	lines.push(foldHeader("Subject", encodeHeaderValue(message.subject, true)));
 	lines.push(`Date: ${(/* @__PURE__ */ new Date()).toUTCString()}`);
 	lines.push(`Message-ID: <${generateMessageId()}>`);
 	if (message.priority !== "normal") {
@@ -1072,7 +1185,7 @@ async function buildRawMessage(message) {
 		lines.push(`X-Priority: ${priorityValue}`);
 		lines.push(`X-MSMail-Priority: ${message.priority === "high" ? "High" : "Low"}`);
 	}
-	for (const [key, value] of message.headers) lines.push(`${key}: ${encodeHeaderValue(value)}`);
+	for (const [key, value] of message.headers) lines.push(foldHeader(key, encodeHeaderValue(value)));
 	lines.push("MIME-Version: 1.0");
 	if (isMultipart) {
 		lines.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
@@ -1111,12 +1224,12 @@ async function buildRawMessage(message) {
 		for (const attachment of message.attachments) {
 			lines.push("");
 			lines.push(`--${boundary}`);
-			lines.push(`Content-Type: ${attachment.contentType}; name="${attachment.filename}"`);
+			lines.push(foldHeader("Content-Type", `${attachment.contentType}; ${encodeMimeParameter("name", attachment.filename)}`));
 			lines.push("Content-Transfer-Encoding: base64");
 			if (attachment.inline) {
-				lines.push(`Content-Disposition: inline; filename="${attachment.filename}"`);
+				lines.push(foldHeader("Content-Disposition", `inline; ${encodeMimeParameter("filename", attachment.filename)}`));
 				lines.push(`Content-ID: <${attachment.contentId}>`);
-			} else lines.push(`Content-Disposition: attachment; filename="${attachment.filename}"`);
+			} else lines.push(foldHeader("Content-Disposition", `attachment; ${encodeMimeParameter("filename", attachment.filename)}`));
 			lines.push("");
 			lines.push(encodeBase64(await attachment.content));
 		}
@@ -1145,32 +1258,85 @@ function generateMessageId() {
 }
 function encodeAddress(address) {
 	if (address.name == null) return address.address;
-	const encodedDisplayName = encodeHeaderValue(address.name);
+	const encodedDisplayName = encodeHeaderValue(address.name, true);
 	return `${encodedDisplayName} <${address.address}>`;
 }
-function encodeHeaderValue(value) {
-	if (!/^[\x20-\x7E]*$/.test(value)) {
-		const utf8Bytes = new TextEncoder().encode(value);
-		const base64 = Buffer.from(utf8Bytes).toString("base64");
+function encodeHeaderValue(value, encodeLongAsciiWords = false) {
+	const hasLongWord = value.split(/\s+/).some((word) => word.length > 60);
+	if (!/^[\x20-\x7E]*$/.test(value) || encodeLongAsciiWords && hasLongWord) {
+		const encodeWord = (text) => {
+			const utf8Bytes = new TextEncoder().encode(text);
+			const base64 = Buffer.from(utf8Bytes).toString("base64");
+			return `=?UTF-8?B?${base64}?=`;
+		};
 		const maxEncodedLength = 75;
-		const encodedWord = `=?UTF-8?B?${base64}?=`;
+		const encodedWord = encodeWord(value);
 		if (encodedWord.length <= maxEncodedLength) return encodedWord;
 		const words = [];
-		let currentBase64 = "";
-		for (let i = 0; i < base64.length; i += 4) {
-			const chunk = base64.slice(i, i + 4);
-			const testWord = `=?UTF-8?B?${currentBase64}${chunk}?=`;
-			if (testWord.length <= maxEncodedLength) currentBase64 += chunk;
+		let currentText = "";
+		for (const character of value) {
+			const candidate = currentText + character;
+			if (encodeWord(candidate).length <= maxEncodedLength) currentText = candidate;
 			else {
-				if (currentBase64) words.push(`=?UTF-8?B?${currentBase64}?=`);
-				currentBase64 = chunk;
+				if (currentText.length > 0) words.push(encodeWord(currentText));
+				currentText = character;
 			}
 		}
-		if (currentBase64) words.push(`=?UTF-8?B?${currentBase64}?=`);
+		if (currentText.length > 0) words.push(encodeWord(currentText));
 		return words.join(" ");
 	}
 	return value;
 }
+function encodeMimeParameter(name, value) {
+	const escapedValue = value.replace(/[\\"]/g, "\\$&");
+	const quotedParameter = `${name}="${escapedValue}"`;
+	if (/^[\x20-\x7E]*$/.test(value) && quotedParameter.length <= 60) return quotedParameter;
+	const encodedBytes = Array.from(new TextEncoder().encode(value), (byte) => {
+		const character = String.fromCharCode(byte);
+		return /^[A-Za-z0-9!#$&+.^_`|~-]$/.test(character) ? character : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+	});
+	const segments = [];
+	let segment = "";
+	for (const encodedByte of encodedBytes) {
+		if (segment.length + encodedByte.length > 45) {
+			segments.push(segment);
+			segment = "";
+		}
+		segment += encodedByte;
+	}
+	if (segment.length > 0 || segments.length === 0) segments.push(segment);
+	return segments.map((part, index) => `${name}*${index}*=${index === 0 ? "UTF-8''" : ""}${part}`).join("; ");
+}
+function foldHeader(name, value) {
+	const recommendedLineLength = 78;
+	const lines = [];
+	let prefix = `${name}: `;
+	let remaining = value;
+	while (prefix.length + remaining.length > recommendedLineLength) {
+		const availableLength = recommendedLineLength - prefix.length;
+		let breakIndex = -1;
+		for (let index = Math.min(availableLength, remaining.length - 1); index >= 0; index--) if (remaining[index] === " " || remaining[index] === "	") {
+			breakIndex = index;
+			break;
+		}
+		if (breakIndex < 0) {
+			for (let index = Math.max(availableLength + 1, 0); index < remaining.length; index++) if (remaining[index] === " " || remaining[index] === "	") {
+				breakIndex = index;
+				break;
+			}
+		}
+		if (breakIndex < 0) break;
+		let whitespaceEnd = breakIndex + 1;
+		while (whitespaceEnd < remaining.length && (remaining[whitespaceEnd] === " " || remaining[whitespaceEnd] === "	")) whitespaceEnd++;
+		if (whitespaceEnd === remaining.length) break;
+		lines.push(prefix + remaining.slice(0, breakIndex));
+		prefix = remaining.slice(breakIndex, whitespaceEnd);
+		remaining = remaining.slice(whitespaceEnd);
+	}
+	lines.push(prefix + remaining);
+	if (lines.some((line) => line.length > 998)) throw new RangeError(`Header field ${name} contains a token too long to fold.`);
+	return lines.join("\r\n");
+}
 function encodeQuotedPrintable(text) {
 	const utf8Bytes = new TextEncoder().encode(text);
 	let result = "";
@@ -1301,12 +1467,13 @@ var SmtpTransport = class {
 			options?.signal?.throwIfAborted();
 			const smtpMessage = await convertMessage(message, this.config.dkim);
 			options?.signal?.throwIfAborted();
-			const messageId = await connection.sendMessage(smtpMessage, options?.signal);
+			const result = await connection.sendMessage(smtpMessage, options?.signal);
 			await this.returnConnection(connection);
 			return {
 				successful: true,
-				messageId,
-				provider: "smtp"
+				messageId: result.messageId,
+				provider: "smtp",
+				rejectedRecipients: result.rejectedRecipients
 			};
 		} catch (error) {
 			if (connection != null) await this.discardConnection(connection);
@@ -1370,11 +1537,12 @@ var SmtpTransport = class {
 				try {
 					const smtpMessage = await convertMessage(message, this.config.dkim);
 					options?.signal?.throwIfAborted();
-					const messageId = await connection.sendMessage(smtpMessage, options?.signal);
+					const result = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
 						successful: true,
-						messageId,
-						provider: "smtp"
+						messageId: result.messageId,
+						provider: "smtp",
+						rejectedRecipients: result.rejectedRecipients
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
@@ -1391,11 +1559,12 @@ var SmtpTransport = class {
 				try {
 					const smtpMessage = await convertMessage(message, this.config.dkim);
 					options?.signal?.throwIfAborted();
-					const messageId = await connection.sendMessage(smtpMessage, options?.signal);
+					const result = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
 						successful: true,
-						messageId,
-						provider: "smtp"
+						messageId: result.messageId,
+						provider: "smtp",
+						rejectedRecipients: result.rejectedRecipients
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
@@ -1504,7 +1673,8 @@ function createSmtpFailure(message, error) {
 			attempts: 1,
 			providerDetails: {
 				command: error.command,
-				response: error.response
+				response: error.response,
+				rejectedRecipients: error.rejectedRecipients
 			}
 		});
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/smtp",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "SMTP transport for Upyo email library",
   "keywords": [
     "email",
@@ -53,7 +53,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@upyo/core": "0.5.1"
+    "@upyo/core": "0.5.3"
   },
   "devDependencies": {
     "tsdown": "^0.12.7",