@upyo/smtp 0.5.0-dev.86 → 0.5.0

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createFailedReceipt } from "@upyo/core";
 import { Socket } from "node:net";
 import { TLSSocket, connect } from "node:tls";
 import { Buffer } from "node:buffer";
@@ -30,15 +31,344 @@ function createSmtpConfig(config) {
 	};
 }
 
+//#endregion
+//#region src/oauth2.ts
+/**
+* An error thrown when SMTP authentication fails, including OAuth 2.0 token
+* acquisition and SASL exchange failures.
+*
+* @since 0.5.0
+*/
+var SmtpAuthError = class extends Error {
+	/**
+	* Creates a new {@link SmtpAuthError}.
+	* @param message A human-readable description of the failure.
+	*/
+	constructor(message) {
+		super(message);
+		this.name = "SmtpAuthError";
+	}
+};
+/**
+* Encodes a string as Base64 in a cross-runtime, UTF-8-safe manner.
+*
+* Unlike calling `btoa()` directly, this first encodes the input as UTF-8 so
+* that non-ASCII characters (e.g., in an internationalized address) do not
+* throw.
+*
+* @param input The string to encode.
+* @returns The Base64-encoded representation of the UTF-8 bytes of `input`.
+*/
+function toBase64(input) {
+	const bytes = new TextEncoder().encode(input);
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary);
+}
+/**
+* Builds the SASL `XOAUTH2` initial client response for SMTP authentication.
+*
+* The unencoded payload follows Google's XOAUTH2 format
+* (`user=<user>^Aauth=Bearer <token>^A^A`, where `^A` is the `0x01` control
+* character) and is returned Base64-encoded, ready to be sent as the argument
+* of `AUTH XOAUTH2`.
+*
+* @param user The user (email address) to authenticate as.
+* @param accessToken The OAuth 2.0 access token.
+* @returns The Base64-encoded XOAUTH2 initial client response.
+* @since 0.5.0
+*/
+function formatXoauth2(user, accessToken) {
+	return toBase64(`user=${user}\x01auth=Bearer ${accessToken}\x01\x01`);
+}
+/**
+* Builds the SASL `OAUTHBEARER` initial client response for SMTP
+* authentication, as defined by [RFC 7628].
+*
+* The unencoded payload is
+* `n,a=<user>,^A[host=<host>^A][port=<port>^A]auth=Bearer <token>^A^A`
+* (where `^A` is the `0x01` control character) and is returned Base64-encoded,
+* ready to be sent as the argument of `AUTH OAUTHBEARER`.
+*
+* [RFC 7628]: https://www.rfc-editor.org/rfc/rfc7628
+*
+* @param user The user (email address) to authenticate as.
+* @param accessToken The OAuth 2.0 access token.
+* @param host The server host to include as the `host` key/value, if any.
+* @param port The server port to include as the `port` key/value, if any.
+* @returns The Base64-encoded OAUTHBEARER initial client response.
+* @since 0.5.0
+*/
+function formatOauthbearer(user, accessToken, host, port) {
+	let response = `n,a=${escapeSaslName(user)},\x01`;
+	if (host != null) response += `host=${host}\x01`;
+	if (port != null) response += `port=${port}\x01`;
+	response += `auth=Bearer ${accessToken}\x01\x01`;
+	return toBase64(response);
+}
+/**
+* Escapes a SASL name (GS2 `authzid`) per RFC 5801, encoding `,` as `=2C` and
+* `=` as `=3D` so that identities containing those characters do not corrupt
+* the GS2 header.
+*
+* @param name The SASL name to escape.
+* @returns The escaped SASL name.
+*/
+function escapeSaslName(name) {
+	return name.replace(/=/g, "=3D").replace(/,/g, "=2C");
+}
+/**
+* Chooses an OAuth 2.0 SASL mechanism based on the mechanisms advertised by the
+* server in its `AUTH` capability line.
+*
+* `XOAUTH2` is preferred when available (it is the de-facto standard supported
+* by Gmail and Outlook); otherwise `OAUTHBEARER` is used when advertised.  When
+* neither is advertised, `xoauth2` is returned as a best-effort default.
+*
+* @param capabilities The capability lines parsed from the server's EHLO
+*                     response.
+* @returns The selected mechanism, either `"xoauth2"` or `"oauthbearer"`.
+* @since 0.5.0
+*/
+function selectOAuth2Mechanism(capabilities) {
+	const authLine = capabilities.find((cap) => cap.toUpperCase().startsWith("AUTH"));
+	const mechanisms = authLine == null ? [] : authLine.toUpperCase().replace(/=/g, " ").split(/\s+/).slice(1);
+	if (mechanisms.includes("XOAUTH2")) return "xoauth2";
+	if (mechanisms.includes("OAUTHBEARER")) return "oauthbearer";
+	return "xoauth2";
+}
+/**
+* Validates that an OAuth 2.0 token endpoint is safe to send client credentials
+* to, requiring HTTPS except for loopback addresses (for local testing).
+*
+* @param endpoint The token endpoint URL to validate.
+* @throws {TypeError} If the URL is malformed or uses an insecure scheme.
+*/
+function assertSecureTokenEndpoint(endpoint) {
+	let url;
+	try {
+		url = new URL(endpoint);
+	} catch {
+		throw new TypeError(`Invalid OAuth 2.0 token endpoint URL: ${endpoint}`);
+	}
+	if (url.protocol === "https:") return;
+	const isLoopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
+	if (url.protocol === "http:" && isLoopback) return;
+	throw new TypeError("OAuth 2.0 token endpoint must use HTTPS to protect client credentials: " + endpoint);
+}
+/**
+* The number of milliseconds before a cached access token's expiry at which it
+* is considered stale and eligible for refresh.
+*/
+const REFRESH_SAFETY_MARGIN_MS = 6e4;
+/**
+* The default access token lifetime (in seconds) assumed when the token
+* endpoint omits `expires_in`.
+*/
+const DEFAULT_EXPIRES_IN = 3600;
+/**
+* How long to wait for the token endpoint before aborting the request, so a
+* stalled endpoint cannot block authentication indefinitely.
+*/
+const TOKEN_REQUEST_TIMEOUT_MS = 6e4;
+/** Maximum number of response-body characters to include in error messages. */
+const MAX_ERROR_BODY_LENGTH = 500;
+/**
+* Truncates a token-endpoint response body so an oversized payload (e.g. a
+* large proxy/CDN error page) does not bloat error messages and logs.
+*
+* @param text The response body text.
+* @returns The text, truncated with an ellipsis if it exceeds the limit.
+*/
+function truncateErrorBody(text) {
+	return text.length > MAX_ERROR_BODY_LENGTH ? `${text.slice(0, MAX_ERROR_BODY_LENGTH)}…` : text;
+}
+/**
+* Mirrors a promise but rejects early if the given abort signal fires, without
+* cancelling the underlying promise.  This lets a single waiter abort its own
+* wait on a shared operation without affecting other waiters.
+*
+* @param promise The promise to await.
+* @param signal An optional abort signal that rejects the returned promise.
+* @returns A promise that settles with `promise`, or rejects when `signal`
+*          aborts.
+*/
+function abortable(promise, signal) {
+	if (signal == null) return promise;
+	return new Promise((resolve, reject) => {
+		const abortReason = () => signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+		const onAbort = () => reject(abortReason());
+		if (signal.aborted) reject(abortReason());
+		else signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+	});
+}
+/**
+* Acquires and caches OAuth 2.0 access tokens for SMTP authentication.
+*
+* Depending on the {@link SmtpOAuth2Auth} configuration, the manager either
+* returns a static token, invokes a provider callback on every request, or
+* exchanges a refresh token for an access token at the configured token
+* endpoint and caches it until shortly before it expires.  A single manager is
+* shared across all pooled connections of a transport so that the refresh-token
+* exchange happens at most once per token lifetime.
+*
+* @since 0.5.0
+*/
+var OAuth2TokenManager = class {
+	auth;
+	fetchFn;
+	cached;
+	pending;
+	/**
+	* Creates a new {@link OAuth2TokenManager}.
+	*
+	* @param auth The OAuth 2.0 authentication configuration.
+	* @param fetchFn The `fetch` implementation to use for the refresh-token
+	*                exchange.  Defaults to the global `fetch`; primarily
+	*                overridden in tests.
+	* @throws {TypeError} If a refresh-token configuration has an insecure
+	*                     (non-HTTPS) token endpoint.
+	*/
+	constructor(auth, fetchFn = fetch) {
+		if ("refreshToken" in auth) assertSecureTokenEndpoint(auth.tokenEndpoint);
+		this.auth = auth;
+		this.fetchFn = fetchFn;
+	}
+	/**
+	* Returns a valid OAuth 2.0 access token, acquiring or refreshing it as
+	* needed.
+	*
+	* @param signal An optional {@link AbortSignal} to cancel token acquisition.
+	* @returns The current access token.
+	* @throws {SmtpAuthError} If a refresh-token exchange fails or returns an
+	*                         unexpected response.
+	*/
+	async getAccessToken(signal) {
+		signal?.throwIfAborted();
+		const auth = this.auth;
+		if ("accessToken" in auth) return typeof auth.accessToken === "function" ? await auth.accessToken(signal) : auth.accessToken;
+		const cached = this.cached;
+		if (cached != null && cached.expiresAt > Date.now()) return cached.accessToken;
+		this.pending ??= this.refresh(auth).then((result) => {
+			const lifetimeMs = result.expiresIn * 1e3;
+			const safetyMargin = Math.min(REFRESH_SAFETY_MARGIN_MS, lifetimeMs / 2);
+			this.cached = {
+				accessToken: result.accessToken,
+				expiresAt: Date.now() + lifetimeMs - safetyMargin
+			};
+			return result;
+		}).finally(() => {
+			this.pending = void 0;
+		});
+		const { accessToken } = await abortable(this.pending, signal);
+		return accessToken;
+	}
+	/**
+	* Exchanges the configured refresh token for a fresh access token.
+	*
+	* The request deliberately runs without a caller-specific abort signal; it is
+	* shared across concurrent callers, each of which applies its own
+	* cancellation separately (see {@link getAccessToken}).
+	*
+	* @param auth The refresh-token authentication configuration.
+	* @returns The new access token and its lifetime in seconds.
+	* @throws {SmtpAuthError} If the request fails or the response is invalid.
+	*/
+	async refresh(auth) {
+		const body = new URLSearchParams({
+			grant_type: "refresh_token",
+			client_id: auth.clientId,
+			refresh_token: auth.refreshToken
+		});
+		if (auth.clientSecret != null) body.set("client_secret", auth.clientSecret);
+		if (auth.scope != null) body.set("scope", auth.scope);
+		const controller = new AbortController();
+		const timeout = setTimeout(() => {
+			controller.abort(/* @__PURE__ */ new Error("OAuth 2.0 token request timed out"));
+		}, TOKEN_REQUEST_TIMEOUT_MS);
+		let response;
+		let text;
+		const fetchFn = this.fetchFn;
+		try {
+			response = await fetchFn(auth.tokenEndpoint, {
+				method: "POST",
+				headers: {
+					"content-type": "application/x-www-form-urlencoded",
+					"accept": "application/json"
+				},
+				body,
+				signal: controller.signal
+			});
+			text = await response.text();
+		} catch (cause) {
+			throw new SmtpAuthError(`Failed to request an OAuth 2.0 access token from ${auth.tokenEndpoint}: ${cause instanceof Error ? cause.message : String(cause)}`);
+		} finally {
+			clearTimeout(timeout);
+		}
+		const safeText = truncateErrorBody(text);
+		if (!response.ok) throw new SmtpAuthError(`OAuth 2.0 token endpoint responded with HTTP ${response.status}: ${safeText}`);
+		let json;
+		try {
+			json = JSON.parse(text);
+		} catch {
+			throw new SmtpAuthError(`OAuth 2.0 token endpoint returned a non-JSON response: ${safeText}`);
+		}
+		if (typeof json !== "object" || json == null || typeof json.access_token !== "string") throw new SmtpAuthError(`OAuth 2.0 token endpoint response did not include an access_token: ${safeText}`);
+		const record = json;
+		const rawExpiresIn = record.expires_in;
+		let parsedExpiresIn;
+		if (typeof rawExpiresIn === "number") parsedExpiresIn = rawExpiresIn;
+		else if (typeof rawExpiresIn === "string" && rawExpiresIn.trim() !== "") parsedExpiresIn = Number(rawExpiresIn);
+		else parsedExpiresIn = NaN;
+		const expiresIn = Number.isFinite(parsedExpiresIn) && parsedExpiresIn >= 0 ? parsedExpiresIn : DEFAULT_EXPIRES_IN;
+		return {
+			accessToken: record.access_token,
+			expiresIn
+		};
+	}
+};
+
 //#endregion
 //#region src/smtp-connection.ts
+/**
+* The maximum length of an SMTP command line, including the terminating CRLF,
+* as specified by RFC 5321 §4.5.3.1.4.
+*/
+const MAX_COMMAND_LINE_LENGTH = 512;
+/** The length of the CRLF terminator appended to every command. */
+const CRLF_LENGTH = 2;
+/**
+* How long, in milliseconds, to wait for the graceful `QUIT` to flush during
+* teardown before giving up, so an unresponsive server cannot block shutdown
+* for the full socket timeout.
+*/
+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).
+*
+* @param host The host to check.
+* @returns `true` if the host is a loopback address.
+*/
+function isLoopbackHost(host) {
+	return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+}
 var SmtpConnection = class {
 	socket = null;
 	config;
 	authenticated = false;
 	capabilities = [];
-	constructor(config) {
+	tokenManager;
+	constructor(config, tokenManager) {
 		this.config = createSmtpConfig(config);
+		this.tokenManager = tokenManager ?? null;
 	}
 	connect(signal) {
 		if (this.socket) throw new Error("Connection already established");
@@ -208,29 +538,44 @@ var SmtpConnection = class {
 		});
 	}
 	async authenticate(signal) {
-		if (!this.config.auth) return;
+		const auth = this.config.auth;
+		if (!auth) return;
 		if (this.authenticated) return;
-		const authMethod = this.config.auth.method ?? "plain";
-		if (!this.capabilities.some((cap) => cap.toUpperCase().startsWith("AUTH"))) throw new Error("Server does not support authentication");
-		switch (authMethod) {
-			case "plain":
-				await this.authPlain(signal);
-				break;
-			case "login":
-				await this.authLogin(signal);
-				break;
-			default: throw new Error(`Unsupported authentication method: ${authMethod}`);
+		if (!this.capabilities.some((cap) => cap.toUpperCase().startsWith("AUTH"))) throw new SmtpAuthError("Server does not support authentication.");
+		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":
+					await this.authXoauth2(auth, signal);
+					break;
+				case "oauthbearer":
+					await this.authOauthbearer(auth, signal);
+					break;
+				default: throw new SmtpAuthError(`Unsupported authentication method: ${mechanism}`);
+			}
+		} else {
+			const method = auth.method ?? "plain";
+			switch (method) {
+				case "plain":
+					await this.authPlain(auth, signal);
+					break;
+				case "login":
+					await this.authLogin(auth, signal);
+					break;
+				default: throw new Error(`Unsupported authentication method: ${method}`);
+			}
 		}
 		this.authenticated = true;
 	}
-	async authPlain(signal) {
-		const { user, pass } = this.config.auth;
+	async authPlain(auth, signal) {
+		const { user, pass } = auth;
 		const credentials = btoa(`\0${user}\0${pass}`);
 		const response = await this.sendCommand(`AUTH PLAIN ${credentials}`, signal);
 		if (response.code !== 235) throw new Error(`Authentication failed: ${response.message}`);
 	}
-	async authLogin(signal) {
-		const { user, pass } = this.config.auth;
+	async authLogin(auth, signal) {
+		const { user, pass } = auth;
 		let response = await this.sendCommand("AUTH LOGIN", signal);
 		if (response.code !== 334) throw new Error(`AUTH LOGIN failed: ${response.message}`);
 		response = await this.sendCommand(btoa(user), signal);
@@ -238,19 +583,80 @@ var SmtpConnection = class {
 		response = await this.sendCommand(btoa(pass), signal);
 		if (response.code !== 235) throw new Error(`Password authentication failed: ${response.message}`);
 	}
+	/**
+	* Resolves an OAuth 2.0 access token via the connection's token manager,
+	* creating a standalone manager from the auth config if none was injected.
+	*/
+	async getOAuth2Token(auth, signal) {
+		this.tokenManager ??= new OAuth2TokenManager(auth);
+		return await this.tokenManager.getAccessToken(signal);
+	}
+	async authXoauth2(auth, signal) {
+		const token = await this.getOAuth2Token(auth, signal);
+		const initialResponse = formatXoauth2(auth.user, token);
+		const response = await this.sendSaslAuth("XOAUTH2", initialResponse, signal);
+		await this.finishOAuth2(response, "XOAUTH2", "", signal);
+	}
+	async authOauthbearer(auth, signal) {
+		const token = await this.getOAuth2Token(auth, signal);
+		const initialResponse = formatOauthbearer(auth.user, token, this.config.host, this.config.port);
+		const response = await this.sendSaslAuth("OAUTHBEARER", initialResponse, signal);
+		await this.finishOAuth2(response, "OAUTHBEARER", "AQ==", signal);
+	}
+	/**
+	* Sends a SASL `AUTH` command with its Base64 initial response.
+	*
+	* When the resulting command line would exceed the SMTP command-line length
+	* limit (e.g. a long Outlook JWT access token), RFC 4954 requires the client
+	* to omit the initial response and send it on its own line after the server's
+	* `334` challenge.  This method transparently falls back to that two-step
+	* form, since some servers reject the over-long single-line command outright.
+	*
+	* @param mechanism The SASL mechanism name (e.g. `XOAUTH2`).
+	* @param initialResponse The Base64-encoded initial client response.
+	* @param signal An optional {@link AbortSignal}.
+	* @returns The server's response to the initial response.
+	*/
+	async sendSaslAuth(mechanism, initialResponse, signal) {
+		const inlineCommand = `AUTH ${mechanism} ${initialResponse}`;
+		if (inlineCommand.length + CRLF_LENGTH <= MAX_COMMAND_LINE_LENGTH) return await this.sendCommand(inlineCommand, signal);
+		const challenge = await this.sendCommand(`AUTH ${mechanism}`, signal);
+		if (challenge.code !== 334) return challenge;
+		return await this.sendCommand(initialResponse, signal);
+	}
+	/**
+	* Interprets the server's reply to an OAuth SASL initial response, draining
+	* the failure challenge continuation when authentication is rejected.
+	*
+	* @throws {SmtpAuthError} If authentication did not succeed.
+	*/
+	async finishOAuth2(response, mechanism, continuation, signal) {
+		if (response.code === 235) return;
+		if (response.code === 334) {
+			let finalMessage = "";
+			try {
+				const final = await this.sendCommand(continuation, signal);
+				finalMessage = ` (${final.message})`;
+			} catch {
+				signal?.throwIfAborted();
+			}
+			throw new SmtpAuthError(`${mechanism} authentication failed: ${decodeOAuth2Challenge(response.message)}${finalMessage}`);
+		}
+		throw new SmtpAuthError(`${mechanism} authentication failed: ${response.message}`);
+	}
 	async sendMessage(message, signal) {
 		const mailResponse = await this.sendCommand(`MAIL FROM:<${message.envelope.from}>`, signal);
-		if (mailResponse.code !== 250) throw new Error(`MAIL FROM failed: ${mailResponse.message}`);
+		if (mailResponse.code !== 250) throw new SmtpResponseError(`MAIL FROM failed: ${mailResponse.message}`, mailResponse.code, "MAIL FROM", mailResponse.message);
 		for (const recipient of message.envelope.to) {
 			signal?.throwIfAborted();
 			const rcptResponse = await this.sendCommand(`RCPT TO:<${recipient}>`, signal);
-			if (rcptResponse.code !== 250) throw new Error(`RCPT TO failed for ${recipient}: ${rcptResponse.message}`);
+			if (rcptResponse.code !== 250) throw new SmtpResponseError(`RCPT TO failed for ${recipient}: ${rcptResponse.message}`, rcptResponse.code, "RCPT TO", rcptResponse.message);
 		}
 		const dataResponse = await this.sendCommand("DATA", signal);
-		if (dataResponse.code !== 354) throw new Error(`DATA failed: ${dataResponse.message}`);
+		if (dataResponse.code !== 354) throw new SmtpResponseError(`DATA failed: ${dataResponse.message}`, dataResponse.code, "DATA", dataResponse.message);
 		const content = message.raw.replace(/\n\./g, "\n..");
 		const finalResponse = await this.sendCommand(`${content}\r\n.`, signal);
-		if (finalResponse.code !== 250) throw new Error(`Message send failed: ${finalResponse.message}`);
+		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;
 	}
@@ -259,11 +665,27 @@ var SmtpConnection = class {
 		return match ? match[1] : `smtp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
 	}
 	async quit() {
-		if (!this.socket) return;
+		const socket = this.socket;
+		if (!socket) return;
+		if (socket.writable) await new Promise((resolve) => {
+			const done = () => {
+				clearTimeout(timer);
+				socket.off("error", done);
+				socket.off("close", done);
+				resolve();
+			};
+			const timer = setTimeout(done, QUIT_TIMEOUT_MS);
+			socket.once("error", done);
+			socket.once("close", done);
+			try {
+				socket.write("QUIT\r\n", done);
+			} catch {
+				done();
+			}
+		});
 		try {
-			await this.sendCommand("QUIT");
+			socket.destroy();
 		} catch {}
-		this.socket.destroy();
 		this.socket = null;
 		this.authenticated = false;
 		this.capabilities = [];
@@ -274,6 +696,59 @@ var SmtpConnection = class {
 		if (response.code !== 250) throw new Error(`RESET failed: ${response.message}`);
 	}
 };
+/**
+* Error thrown when an SMTP command receives an unsuccessful server reply.
+*
+* @since 0.5.0
+*/
+var SmtpResponseError = class extends Error {
+	/**
+	* The numeric SMTP reply code returned by the server.
+	*/
+	code;
+	/**
+	* The SMTP command that produced the reply.
+	*/
+	command;
+	/**
+	* The textual SMTP reply returned by the server.
+	*/
+	response;
+	/**
+	* Creates an SMTP response error.
+	*
+	* @param message Human-readable error message.
+	* @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.
+	*/
+	constructor(message, code, command, response) {
+		super(message);
+		this.name = "SmtpResponseError";
+		this.code = code;
+		this.command = command;
+		this.response = response;
+	}
+};
+/**
+* Decodes the Base64 JSON error challenge a server sends after a failed OAuth
+* SASL exchange, falling back to the raw message when it is not valid Base64.
+*
+* The bytes are decoded as UTF-8 (via `TextDecoder`) so non-ASCII challenge
+* messages are not corrupted, unlike decoding `atob`'s Latin-1 output directly.
+*
+* @param message The challenge text from the server's 334 response.
+* @returns A human-readable description of the failure.
+*/
+function decodeOAuth2Challenge(message) {
+	try {
+		const binary = atob(message.trim());
+		const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+		return new TextDecoder().decode(bytes);
+	} catch {
+		return message;
+	}
+}
 
 //#endregion
 //#region src/dkim/canonicalize.ts
@@ -761,6 +1236,7 @@ function encodeBase64(data) {
 * ```
 */
 var SmtpTransport = class {
+	id = "smtp";
 	/**
 	* The SMTP configuration used by this transport.
 	*/
@@ -771,6 +1247,13 @@ var SmtpTransport = class {
 	poolSize;
 	connectionPool = [];
 	/**
+	* A token manager shared across all pooled connections, present only when the
+	* configured authentication uses OAuth 2.0.  Sharing it ensures the
+	* refresh-token exchange happens at most once per token lifetime instead of
+	* once per connection.
+	*/
+	tokenManager;
+	/**
 	* Creates a new SMTP transport instance.
 	*
 	* @param config SMTP configuration including server details, authentication,
@@ -779,6 +1262,8 @@ var SmtpTransport = class {
 	constructor(config) {
 		this.config = config;
 		this.poolSize = config.poolSize ?? 5;
+		const auth = config.auth;
+		this.tokenManager = auth != null && ("accessToken" in auth || "refreshToken" in auth) ? new OAuth2TokenManager(auth) : void 0;
 	}
 	/**
 	* Sends a single email message via SMTP.
@@ -805,11 +1290,14 @@ var SmtpTransport = class {
 	*                cancellation.
 	* @returns A promise that resolves to a receipt indicating success or
 	*          failure.
+	* @throws {DOMException} If the operation is aborted through
+	*                        `options.signal`.
 	*/
 	async send(message, options) {
 		options?.signal?.throwIfAborted();
-		const connection = await this.getConnection(options?.signal);
+		let connection;
 		try {
+			connection = await this.getConnection(options?.signal);
 			options?.signal?.throwIfAborted();
 			const smtpMessage = await convertMessage(message, this.config.dkim);
 			options?.signal?.throwIfAborted();
@@ -817,14 +1305,13 @@ var SmtpTransport = class {
 			await this.returnConnection(connection);
 			return {
 				successful: true,
-				messageId
+				messageId,
+				provider: "smtp"
 			};
 		} catch (error) {
-			await this.discardConnection(connection);
-			return {
-				successful: false,
-				errorMessages: [error instanceof Error ? error.message : String(error)]
-			};
+			if (connection != null) await this.discardConnection(connection);
+			options?.signal?.throwIfAborted();
+			return createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 		}
 	}
 	/**
@@ -854,20 +1341,30 @@ var SmtpTransport = class {
 	* @param options Optional transport options including `AbortSignal` for
 	*                cancellation.
 	* @returns An async iterable of receipts, one for each message.
+	* @throws {DOMException} If the operation is aborted through
+	*                        `options.signal`.
 	*/
 	async *sendMany(messages, options) {
 		options?.signal?.throwIfAborted();
-		const connection = await this.getConnection(options?.signal);
+		let connection;
+		try {
+			connection = await this.getConnection(options?.signal);
+		} catch (error) {
+			options?.signal?.throwIfAborted();
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			for await (const _ of messages) {
+				options?.signal?.throwIfAborted();
+				yield createSmtpFailure(errorMessage, error);
+			}
+			return;
+		}
 		let connectionValid = true;
 		try {
 			const isAsyncIterable = Symbol.asyncIterator in messages;
 			if (isAsyncIterable) for await (const message of messages) {
 				options?.signal?.throwIfAborted();
 				if (!connectionValid) {
-					yield {
-						successful: false,
-						errorMessages: ["Connection is no longer valid"]
-					};
+					yield createSmtpFailure("Connection is no longer valid");
 					continue;
 				}
 				try {
@@ -876,23 +1373,19 @@ var SmtpTransport = class {
 					const messageId = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
 						successful: true,
-						messageId
+						messageId,
+						provider: "smtp"
 					};
 				} catch (error) {
+					options?.signal?.throwIfAborted();
 					connectionValid = false;
-					yield {
-						successful: false,
-						errorMessages: [error instanceof Error ? error.message : String(error)]
-					};
+					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 				}
 			}
 			else for (const message of messages) {
 				options?.signal?.throwIfAborted();
 				if (!connectionValid) {
-					yield {
-						successful: false,
-						errorMessages: ["Connection is no longer valid"]
-					};
+					yield createSmtpFailure("Connection is no longer valid");
 					continue;
 				}
 				try {
@@ -901,14 +1394,13 @@ var SmtpTransport = class {
 					const messageId = await connection.sendMessage(smtpMessage, options?.signal);
 					yield {
 						successful: true,
-						messageId
+						messageId,
+						provider: "smtp"
 					};
 				} catch (error) {
+					options?.signal?.throwIfAborted();
 					connectionValid = false;
-					yield {
-						successful: false,
-						errorMessages: [error instanceof Error ? error.message : String(error)]
-					};
+					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 				}
 			}
 			if (connectionValid) await this.returnConnection(connection);
@@ -921,8 +1413,13 @@ var SmtpTransport = class {
 	async getConnection(signal) {
 		signal?.throwIfAborted();
 		if (this.connectionPool.length > 0) return this.connectionPool.pop();
-		const connection = new SmtpConnection(this.config);
-		await this.connectAndSetup(connection, signal);
+		const connection = new SmtpConnection(this.config, this.tokenManager);
+		try {
+			await this.connectAndSetup(connection, signal);
+		} catch (error) {
+			await this.discardConnection(connection);
+			throw error;
+		}
 		return connection;
 	}
 	async connectAndSetup(connection, signal) {
@@ -996,6 +1493,40 @@ var SmtpTransport = class {
 		await this.closeAllConnections();
 	}
 };
+function createSmtpFailure(message, error) {
+	if (error instanceof SmtpResponseError) {
+		const classification = classifySmtpReply(error.code);
+		return createFailedReceipt(message, {
+			provider: "smtp",
+			code: `smtp.${error.code}`,
+			category: classification.category,
+			retryable: classification.retryable,
+			attempts: 1,
+			providerDetails: {
+				command: error.command,
+				response: error.response
+			}
+		});
+	}
+	return createFailedReceipt(message, {
+		provider: "smtp",
+		attempts: 1
+	});
+}
+function classifySmtpReply(code) {
+	if (code >= 400 && code < 500) return {
+		category: "service-unavailable",
+		retryable: true
+	};
+	if (code >= 500 && code < 600) return {
+		category: "rejected",
+		retryable: false
+	};
+	return {
+		category: "unknown",
+		retryable: false
+	};
+}
 
 //#endregion
-export { SmtpTransport };
+export { SmtpAuthError, SmtpTransport };