@upyo/smtp 0.6.0-dev.265 → 0.6.0-dev.269

package/README.md

@@ -60,6 +60,7 @@ const transport = new SmtpTransport({
   host: "smtp.example.com",
   port: 587,
   secure: false,
+  requireTls: true,
   auth: {
     user: "username",
     pass: "password",
@@ -106,6 +107,7 @@ Configuration options
 | `host`              | `string`         |               | SMTP server hostname             |
 | `port`              | `number`         | `587`         | SMTP server port                 |
 | `secure`            | `boolean`        | `true`        | Use TLS/SSL connection           |
+| `requireTls`        | `boolean`        | `false`       | Require a STARTTLS upgrade       |
 | `auth`              | `SmtpAuth`       |               | Authentication configuration     |
 | `tls`               | `SmtpTlsOptions` |               | TLS configuration                |
 | `connectionTimeout` | `number`         | `60000`       | Connection timeout (ms)          |
@@ -115,6 +117,12 @@ Configuration options
 | `poolSize`          | `number`         | `5`           | Maximum pool connections         |
 | `dkim`              | `DkimConfig`     |               | DKIM signing configuration       |
 
+Set `requireTls: true` with `secure: false` to issue `STARTTLS` even when the
+server does not advertise it and fail delivery unless the upgrade succeeds.
+Regardless of this option, SMTP authentication to non-loopback hosts requires
+either an implicit TLS connection or a successful STARTTLS upgrade.  Cleartext
+authentication to loopback hosts remains available for local development.
+
 ### `SmtpAuth`
 
 `SmtpAuth` is a discriminated union of three strategies.

package/dist/index.cjs

@@ -43,6 +43,7 @@ function createSmtpConfig(config) {
 		host: config.host,
 		port: config.port ?? 587,
 		secure: config.secure ?? true,
+		requireTls: config.requireTls ?? false,
 		auth: config.auth,
 		tls: config.tls,
 		connectionTimeout: config.connectionTimeout ?? 6e4,
@@ -374,14 +375,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;
@@ -565,8 +644,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":
@@ -1454,7 +1533,7 @@ var SmtpTransport = class {
 		signal?.throwIfAborted();
 		await connection.ehlo(signal);
 		signal?.throwIfAborted();
-		if (!this.config.secure && connection.capabilities.some((cap) => cap.toUpperCase().startsWith("STARTTLS"))) {
+		if (connection.config.secure === false && (connection.config.requireTls === true || connection.capabilities.some((cap) => cap.toUpperCase().startsWith("STARTTLS")))) {
 			await connection.starttls(signal);
 			signal?.throwIfAborted();
 			await connection.ehlo(signal);
@@ -1463,7 +1542,7 @@ var SmtpTransport = class {
 		await connection.authenticate(signal);
 	}
 	async returnConnection(connection) {
-		if (!this.config.pool) {
+		if (!connection.config.pool) {
 			await connection.quit();
 			return;
 		}

package/dist/index.d.cts

@@ -140,6 +140,15 @@ interface SmtpConfig {
    * @default true
    */
   readonly secure?: boolean;
+  /**
+   * Whether to require a successful STARTTLS upgrade for connections that do
+   * not use implicit TLS.  When enabled, the client issues `STARTTLS` even if
+   * the server does not advertise the capability and fails the connection if
+   * the upgrade does not succeed.
+   * @default false
+   * @since 0.6.0
+   */
+  readonly requireTls?: boolean;
   /**
    * Authentication configuration for the SMTP server.
    */

package/dist/index.d.ts

@@ -140,6 +140,15 @@ interface SmtpConfig {
    * @default true
    */
   readonly secure?: boolean;
+  /**
+   * Whether to require a successful STARTTLS upgrade for connections that do
+   * not use implicit TLS.  When enabled, the client issues `STARTTLS` even if
+   * the server does not advertise the capability and fails the connection if
+   * the upgrade does not succeed.
+   * @default false
+   * @since 0.6.0
+   */
+  readonly requireTls?: boolean;
   /**
    * Authentication configuration for the SMTP server.
    */

package/dist/index.js

@@ -20,6 +20,7 @@ function createSmtpConfig(config) {
 		host: config.host,
 		port: config.port ?? 587,
 		secure: config.secure ?? true,
+		requireTls: config.requireTls ?? false,
 		auth: config.auth,
 		tls: config.tls,
 		connectionTimeout: config.connectionTimeout ?? 6e4,
@@ -351,14 +352,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;
@@ -542,8 +621,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":
@@ -1431,7 +1510,7 @@ var SmtpTransport = class {
 		signal?.throwIfAborted();
 		await connection.ehlo(signal);
 		signal?.throwIfAborted();
-		if (!this.config.secure && connection.capabilities.some((cap) => cap.toUpperCase().startsWith("STARTTLS"))) {
+		if (connection.config.secure === false && (connection.config.requireTls === true || connection.capabilities.some((cap) => cap.toUpperCase().startsWith("STARTTLS")))) {
 			await connection.starttls(signal);
 			signal?.throwIfAborted();
 			await connection.ehlo(signal);
@@ -1440,7 +1519,7 @@ var SmtpTransport = class {
 		await connection.authenticate(signal);
 	}
 	async returnConnection(connection) {
-		if (!this.config.pool) {
+		if (!connection.config.pool) {
 			await connection.quit();
 			return;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/smtp",
-  "version": "0.6.0-dev.265",
+  "version": "0.6.0-dev.269",
   "description": "SMTP transport for Upyo email library",
   "keywords": [
     "email",
@@ -53,7 +53,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@upyo/core": "0.6.0-dev.265+77f3e71a"
+    "@upyo/core": "0.6.0-dev.269+e9149444"
   },
   "devDependencies": {
     "tsdown": "^0.12.7",