@upyo/smtp 0.5.0-dev.120 → 0.5.0-dev.128

package/README.md

@@ -22,6 +22,7 @@ Features
  -  TLS/SSL support
  -  Connection pooling
  -  Multiple authentication methods
+ -  OAuth 2.0 authentication (SASL XOAUTH2 and OAUTHBEARER)
  -  HTML and plain text email support
  -  File attachments (regular and inline)
  -  Multiple recipients (To, CC, BCC)
@@ -116,12 +117,46 @@ Configuration options
 
 ### `SmtpAuth`
 
+`SmtpAuth` is a discriminated union of three strategies.
+
+Username/password (`SmtpUserPassAuth`), discriminated by `pass`:
+
 | Option   | Type                               | Default   | Description |
 | -------- | ---------------------------------- | --------- | ----------- |
 | `user`   | `string`                           |           | Username    |
 | `pass`   | `string`                           |           | Password    |
 | `method` | `"plain" \| "login" \| "cram-md5"` | `"plain"` | Auth method |
 
+OAuth 2.0 access token (`SmtpOAuth2TokenAuth`), discriminated by `accessToken`:
+
+| Option        | Type                            | Default     | Description                                 |
+| ------------- | ------------------------------- | ----------- | ------------------------------------------- |
+| `user`        | `string`                        |             | User (email address)                        |
+| `accessToken` | `string \| OAuth2TokenProvider` |             | Access token, or a callback returning one   |
+| `method`      | `"xoauth2" \| "oauthbearer"`    | `"xoauth2"` | SASL mechanism (auto-detected when omitted) |
+
+OAuth 2.0 refresh-token flow (`SmtpOAuth2RefreshAuth`), discriminated by
+`refreshToken`:
+
+| Option          | Type                         | Default     | Description                                 |
+| --------------- | ---------------------------- | ----------- | ------------------------------------------- |
+| `user`          | `string`                     |             | User (email address)                        |
+| `clientId`      | `string`                     |             | OAuth 2.0 client identifier                 |
+| `clientSecret`  | `string`                     |             | OAuth 2.0 client secret (optional)          |
+| `refreshToken`  | `string`                     |             | OAuth 2.0 refresh token                     |
+| `tokenEndpoint` | `string`                     |             | Token endpoint URL                          |
+| `scope`         | `string`                     |             | Space-delimited scopes (optional)           |
+| `method`        | `"xoauth2" \| "oauthbearer"` | `"xoauth2"` | SASL mechanism (auto-detected when omitted) |
+
+The access token may be a static string or a callback (`OAuth2TokenProvider`)
+that returns a fresh token on demand—use the callback to integrate an OAuth
+client such as `google-auth-library` or `msal-node`.  With the refresh-token
+flow the transport runs the `refresh_token` grant itself, caching the access
+token across pooled connections.  See the
+[OAuth 2.0 authentication guide][oauth-guide] for details.
+
+[oauth-guide]: https://upyo.org/transports/smtp#oauth-2-0-authentication
+
 
 DKIM signing
 ------------
@@ -197,3 +232,40 @@ console.log(received[0].data); // Raw email content
 
 await server.stop();
 ~~~~
+
+### OAuth 2.0 end-to-end tests
+
+The OAuth 2.0 end-to-end tests run against a real provider (e.g. Gmail or
+Outlook) and are skipped unless the following environment variables are set:
+
+| Variable                | Description                            |
+| ----------------------- | -------------------------------------- |
+| `SMTP_OAUTH2_HOST`      | SMTP host (e.g. `smtp.gmail.com`)      |
+| `SMTP_OAUTH2_PORT`      | SMTP port (default `587`)              |
+| `SMTP_OAUTH2_SECURE`    | `true` for implicit TLS                |
+| `SMTP_OAUTH2_USER`      | User (email address)                   |
+| `SMTP_OAUTH2_MECHANISM` | `xoauth2` or `oauthbearer` (optional)  |
+| `SMTP_OAUTH2_FROM`      | Envelope sender (defaults to the user) |
+| `SMTP_OAUTH2_TO`        | Recipient (defaults to the user)       |
+
+Provide a token source as either a static access token:
+
+| Variable                   | Description        |
+| -------------------------- | ------------------ |
+| `SMTP_OAUTH2_ACCESS_TOKEN` | OAuth access token |
+
+or the refresh-token flow:
+
+| Variable                     | Description                       |
+| ---------------------------- | --------------------------------- |
+| `SMTP_OAUTH2_CLIENT_ID`      | OAuth client identifier           |
+| `SMTP_OAUTH2_CLIENT_SECRET`  | OAuth client secret (optional)    |
+| `SMTP_OAUTH2_REFRESH_TOKEN`  | OAuth refresh token               |
+| `SMTP_OAUTH2_TOKEN_ENDPOINT` | Token endpoint URL                |
+| `SMTP_OAUTH2_SCOPE`          | Space-delimited scopes (optional) |
+
+A Gmail access token can be minted with [google-auth-library], and an Outlook
+one with [msal-node].
+
+[google-auth-library]: https://github.com/googleapis/google-auth-library-nodejs
+[msal-node]: https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-node

package/dist/index.cjs

@@ -53,15 +53,334 @@ 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().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 onAbort = () => reject(signal.reason);
+		if (signal.aborted) reject(signal.reason);
+		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 - REFRESH_SAFETY_MARGIN_MS > Date.now()) return cached.accessToken;
+		this.pending ??= this.refresh(auth).then((result) => {
+			this.cached = {
+				accessToken: result.accessToken,
+				expiresAt: Date.now() + result.expiresIn * 1e3
+			};
+			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;
+		try {
+			response = await this.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;
+		let expiresIn = DEFAULT_EXPIRES_IN;
+		if (typeof record.expires_in === "number") expiresIn = record.expires_in;
+		else if (typeof record.expires_in === "string") {
+			const parsed = Number.parseInt(record.expires_in, 10);
+			if (Number.isFinite(parsed)) expiresIn = parsed;
+		}
+		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;
+/**
+* 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");
@@ -231,29 +550,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 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":
+					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);
@@ -261,6 +595,67 @@ 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}`);
@@ -282,11 +677,14 @@ var SmtpConnection = class {
 		return match ? match[1] : `smtp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
 	}
 	async quit() {
-		if (!this.socket) return;
-		try {
+		const socket = this.socket;
+		if (!socket) return;
+		if (socket.writable) try {
 			await this.sendCommand("QUIT");
 		} catch {}
-		this.socket.destroy();
+		try {
+			socket.destroy();
+		} catch {}
 		this.socket = null;
 		this.authenticated = false;
 		this.capabilities = [];
@@ -297,6 +695,20 @@ var SmtpConnection = class {
 		if (response.code !== 250) throw new Error(`RESET failed: ${response.message}`);
 	}
 };
+/**
+* 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.
+*
+* @param message The challenge text from the server's 334 response.
+* @returns A human-readable description of the failure.
+*/
+function decodeOAuth2Challenge(message) {
+	try {
+		return atob(message.trim());
+	} catch {
+		return message;
+	}
+}
 
 //#endregion
 //#region src/dkim/canonicalize.ts
@@ -794,6 +1206,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,
@@ -802,6 +1221,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.
@@ -831,8 +1252,9 @@ var SmtpTransport = class {
 	*/
 	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();
@@ -843,7 +1265,8 @@ var SmtpTransport = class {
 				messageId
 			};
 		} catch (error) {
-			await this.discardConnection(connection);
+			if (connection != null) await this.discardConnection(connection);
+			options?.signal?.throwIfAborted();
 			return {
 				successful: false,
 				errorMessages: [error instanceof Error ? error.message : String(error)]
@@ -880,7 +1303,21 @@ var SmtpTransport = class {
 	*/
 	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 {
+					successful: false,
+					errorMessages: [errorMessage]
+				};
+			}
+			return;
+		}
 		let connectionValid = true;
 		try {
 			const isAsyncIterable = Symbol.asyncIterator in messages;
@@ -902,6 +1339,7 @@ var SmtpTransport = class {
 						messageId
 					};
 				} catch (error) {
+					options?.signal?.throwIfAborted();
 					connectionValid = false;
 					yield {
 						successful: false,
@@ -927,6 +1365,7 @@ var SmtpTransport = class {
 						messageId
 					};
 				} catch (error) {
+					options?.signal?.throwIfAborted();
 					connectionValid = false;
 					yield {
 						successful: false,
@@ -944,8 +1383,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) {
@@ -1021,4 +1465,5 @@ var SmtpTransport = class {
 };
 
 //#endregion
+exports.SmtpAuthError = SmtpAuthError;
 exports.SmtpTransport = SmtpTransport;