@push.rocks/smartmta 9.2.0 → 9.4.0

package/ts/mail/routing/classes.unified.email.server.ts

@@ -9,8 +9,10 @@ import {
 } from '../../security/index.js';
 import { DKIMCreator } from '../security/classes.dkimcreator.js';
 import type { IStorageManager } from '../interfaces.storage.js';
-import { RustSecurityBridge } from '../../security/classes.rustsecuritybridge.js';
+import { RustSecurityBridge, SmtpDeliveryError } from '../../security/classes.rustsecuritybridge.js';
 import type {
+  IOutboundAuthenticationCheck,
+  IOutboundAuthenticationHandle,
   IAuthRequestEvent,
   IEmailReceivedEvent,
   IEmailSecurityResult,
@@ -258,6 +260,12 @@ export interface IOutboundConnectionProxyContext {
   senderDomain?: string;
 }
 
+export interface IOutboundConnectionSourceEvidence {
+  sourceIp: string;
+  addressFamily: 'ipv4' | 'ipv6';
+}
+
+
 export interface IOutboundConnectionProxy {
   connectHost: string;
   connectPort: number;
@@ -265,6 +273,8 @@ export interface IOutboundConnectionProxy {
   /** Per-connection EHLO identity override (e.g. the selected egress edge's PTR hostname). */
   ehloHostname?: string;
   close?: () => Promise<void> | void;
+  /** Actual source identity observed after the proxied connection is established. */
+  sourceEvidence?: Promise<IOutboundConnectionSourceEvidence | null>;
 }
 
 export interface IOutboundTopologyIdentity {
@@ -334,6 +344,19 @@ export interface IUnifiedEmailServerOptions {
     recipientValidation?: boolean;
     /** Listener port that should use implicit TLS. Defaults to 465 when present. */
     securePort?: number;
+    /**
+     * Listener ports whose inbound transport is already encrypted by a trusted
+     * upstream TLS terminator (an edge proxy that terminates TLS and forwards
+     * the decrypted stream here). Sessions on these ports count as encrypted:
+     * AUTH is offered even though this process performed no handshake, and
+     * STARTTLS is not advertised.
+     *
+     * Only honoured together with `proxyProtocol.required` — the exact-peer
+     * PROXY check is what proves the connection came from the terminator.
+     * Startup fails when a listed port is not bound, is the implicit-TLS
+     * `securePort`, or PROXY protocol is not required.
+     */
+    tlsTerminatedPorts?: number[];
     /** Timeout for RCPT policy callbacks. Defaults to 5000 ms. */
     recipientValidationTimeoutMs?: number;
     /** Timeout for message acceptance callbacks. Defaults to 30000 ms. */
@@ -924,8 +947,28 @@ export class UnifiedEmailServer extends EventEmitter {
       senderDomain,
     });
 
+    const captureId = proxy?.sourceEvidence ? plugins.uuid.v4() : undefined;
+    const attachAuthenticationHandle = <T extends ISmtpSendResult | SmtpDeliveryError>(valueArg: T): T => {
+      if (!captureId || !proxy?.sourceEvidence) return valueArg;
+      const handle = this.createOutboundAuthenticationHandle({
+        captureId,
+        sourceEvidence: proxy.sourceEvidence,
+        heloDomain: proxy.ehloHostname || this.getOutboundHostname(),
+        receiverHostname: host,
+        envelopeFrom: email.from,
+        dkimDomain: dkim?.domain,
+        dkimSelector: dkim?.selector,
+      });
+      Object.defineProperty(valueArg, 'outboundAuthenticationHandle', {
+        value: handle,
+        enumerable: false,
+        configurable: true,
+      });
+      return valueArg;
+    };
+
     try {
-      return await this.rustBridge.sendOutboundEmail({
+      const result = await this.rustBridge.sendOutboundEmail({
         host,
         port,
         ...(proxy ? { connectHost: proxy.connectHost, connectPort: proxy.connectPort } : {}),
@@ -940,12 +983,99 @@ export class UnifiedEmailServer extends EventEmitter {
         maxPoolConnections: this.options.outbound?.maxConnections || 10,
         tlsOpportunistic,
         ...(proxy ? { disablePooling: true } : {}),
+        ...(captureId ? { outboundAuthenticationCaptureId: captureId } : {}),
       });
+      return attachAuthenticationHandle(result);
+    } catch (error) {
+      throw attachAuthenticationHandle(SmtpDeliveryError.from(error));
     } finally {
       await proxy?.close?.();
     }
   }
 
+  private createOutboundAuthenticationHandle(
+    optionsArg: {
+      captureId: string;
+      sourceEvidence: Promise<IOutboundConnectionSourceEvidence | null>;
+      heloDomain: string;
+      receiverHostname: string;
+      envelopeFrom: string;
+      dkimDomain?: string;
+      dkimSelector?: string;
+    },
+  ): IOutboundAuthenticationHandle {
+    const pending: IOutboundAuthenticationCheck = {
+      state: 'pending',
+      overall: 'indeterminate',
+      checkedAt: new Date().toISOString(),
+    };
+    const indeterminate = (errorArg: string): IOutboundAuthenticationCheck => ({
+      state: 'indeterminate',
+      overall: 'indeterminate',
+      checkedAt: new Date().toISOString(),
+      error: errorArg,
+    });
+    const result = (async (): Promise<IOutboundAuthenticationCheck> => {
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+      try {
+        const sourceEvidence = await new Promise<IOutboundConnectionSourceEvidence | null>((resolve, reject) => {
+          timeout = setTimeout(() => {
+            reject(new Error('Timed out waiting for the actual outbound source identity'));
+          }, 40_000);
+          timeout.unref?.();
+          optionsArg.sourceEvidence.then(resolve, reject);
+        });
+        if (!sourceEvidence) {
+          await this.rustBridge.discardCapturedOutboundEmail(optionsArg.captureId).catch(() => undefined);
+          return indeterminate('The outbound proxy did not provide source identity evidence');
+        }
+        const verification = await this.rustBridge.verifyCapturedOutboundEmail({
+          captureId: optionsArg.captureId,
+          ip: sourceEvidence.sourceIp,
+          heloDomain: optionsArg.heloDomain,
+          hostname: optionsArg.receiverHostname,
+          mailFrom: optionsArg.envelopeFrom,
+        });
+        if (verification.state !== 'completed' || !verification.result) {
+          return indeterminate(verification.error || 'The outbound authentication self-check was not completed');
+        }
+        const security = verification.result;
+        const dkimPass = !optionsArg.dkimDomain || security.dkim.some((resultArg) => (
+          resultArg.is_valid
+          && resultArg.domain?.toLowerCase() === optionsArg.dkimDomain?.toLowerCase()
+          && (!optionsArg.dkimSelector || resultArg.selector === optionsArg.dkimSelector)
+        ));
+        const spfPass = security.spf?.result.toLowerCase() === 'pass';
+        const dmarcPass = security.dmarc?.passed === true;
+        return {
+          state: 'completed',
+          overall: dkimPass && spfPass && dmarcPass ? 'pass' : 'fail',
+          checkedAt: new Date().toISOString(),
+          signedMessageSha256: verification.signedMessageSha256,
+          identity: {
+            sourceIp: sourceEvidence.sourceIp,
+            addressFamily: sourceEvidence.addressFamily,
+            heloDomain: optionsArg.heloDomain,
+            receiverHostname: optionsArg.receiverHostname,
+            envelopeFrom: optionsArg.envelopeFrom,
+            ...(optionsArg.dkimDomain ? { dkimDomain: optionsArg.dkimDomain } : {}),
+            ...(optionsArg.dkimSelector ? { dkimSelector: optionsArg.dkimSelector } : {}),
+          },
+          dkim: security.dkim,
+          spf: security.spf,
+          dmarc: security.dmarc,
+        };
+      } catch (error) {
+        await this.rustBridge.discardCapturedOutboundEmail(optionsArg.captureId).catch(() => undefined);
+        return indeterminate(getErrorMessage(error).slice(0, 512));
+      } finally {
+        if (timeout) clearTimeout(timeout);
+      }
+    })();
+    return { pending, result };
+  }
+
+
   /**
    * Start the unified email server
    */
@@ -1182,6 +1312,7 @@ export class UnifiedEmailServer extends EventEmitter {
       ? configuredSecurePort
       : (this.options.ports as number[]).find(p => p === 465);
     const smtpPorts = (this.options.ports as number[]).filter(p => p !== securePort);
+    const tlsTerminatedPorts = this.resolveTlsTerminatedPorts(smtpPorts, securePort);
 
     const started = await this.rustBridge.startSmtpServer({
       hostname: this.getAdvertisedHostname(),
@@ -1189,6 +1320,7 @@ export class UnifiedEmailServer extends EventEmitter {
       securePort: securePort,
       tlsCertPem,
       tlsKeyPem,
+      ...(tlsTerminatedPorts.length > 0 ? { tlsTerminatedPorts } : {}),
       maxMessageSize: this.options.maxMessageSize || 10 * 1024 * 1024,
       maxConnections: this.options.maxConnections || this.options.maxClients || 100,
       maxRecipients: 100,
@@ -1222,6 +1354,44 @@ export class UnifiedEmailServer extends EventEmitter {
     logger.log('info', `Rust SMTP server listening on ports: ${smtpPorts.join(', ')}${securePort ? ` + ${securePort} (TLS)` : ''}`);
   }
 
+  /**
+   * Validate and resolve the ports whose transport an upstream proxy already
+   * encrypted. Misconfiguration here would let a peer claim an encrypted
+   * channel and be offered AUTH in cleartext, so every case fails startup
+   * rather than degrading silently.
+   */
+  private resolveTlsTerminatedPorts(smtpPorts: number[], securePort: number | undefined): number[] {
+    const configured = this.options.smtp?.tlsTerminatedPorts;
+    if (!configured || configured.length === 0) return [];
+    if (!this.options.smtp?.proxyProtocol?.required) {
+      throw new Error(
+        'SMTP tlsTerminatedPorts requires smtp.proxyProtocol.required so the upstream TLS terminator is proven by the trusted-peer PROXY check',
+      );
+    }
+    if (!this.options.smtp.proxyProtocol.trustedIps?.length) {
+      throw new Error(
+        'SMTP tlsTerminatedPorts requires at least one smtp.proxyProtocol.trustedIps entry',
+      );
+    }
+    const resolved: number[] = [];
+    for (const port of configured) {
+      if (securePort !== undefined && port === securePort) {
+        throw new Error(
+          `SMTP tlsTerminatedPorts names port ${port}, which is already the implicit-TLS securePort terminated by this server`,
+        );
+      }
+      if (!smtpPorts.includes(port)) {
+        throw new Error(
+          `SMTP tlsTerminatedPorts names port ${port}, which is not one of the configured SMTP listener ports`,
+        );
+      }
+      if (!resolved.includes(port)) {
+        resolved.push(port);
+      }
+    }
+    return resolved;
+  }
+
   /** Whether the current options require SMTP AUTH support on the listener. */
   private isAuthConfigured(options: IUnifiedEmailServerOptions): boolean {
     return !!options.auth?.required
@@ -1452,10 +1622,18 @@ export class UnifiedEmailServer extends EventEmitter {
       text: '',
     });
     const session = sessionArg || this.buildPolicySession(currentRecipientContext);
-    const route = await this.emailRouter.evaluateRoutes({ email, session });
+    const matchedRoute = await this.emailRouter.evaluateRoutes({ email, session });
     const recipientDomain = this.getAddressDomain(context.rcptTo);
     const isLocalRecipient = !!recipientDomain && this.domainRegistry.isDomainRegistered(recipientDomain);
     const localDomain = isLocalRecipient ? recipientDomain! : null;
+    // A submission-permission route must never claim a recipient this server
+    // itself terminates: its transport is DNS-MX relay, which for such a
+    // recipient resolves straight back to this listener. Authentication grants
+    // permission to relay, it does not turn a local delivery into a remote one.
+    const route = matchedRoute
+      && this.isSubmissionPermissionRouteForLocalRecipient(matchedRoute, recipientDomain, isLocalRecipient)
+      ? null
+      : matchedRoute;
 
     if (route) {
       if (route.action.type === 'reject') {
@@ -1585,6 +1763,49 @@ export class UnifiedEmailServer extends EventEmitter {
     };
   }
 
+  /**
+   * Whether a matched route is a pure submission-permission route that must
+   * not claim a recipient whose inbound mail this server terminates.
+   *
+   * A route qualifies only when ALL of the following hold:
+   * - the recipient domain is registered here AND its inbound policy stores
+   *   mail locally, i.e. this server really is the destination. A domain
+   *   registered for outbound purposes only (`inboundPolicy` absent, or
+   *   `defaultAction: 'reject'` for send-only domains) keeps relaying, because
+   *   its real MX legitimately lives elsewhere;
+   * - the action is `process`, the only action whose transport is DNS-MX
+   *   relay. `store`, `deliver`, `forward` and `reject` all express a
+   *   deliberate disposition for the recipient and always win;
+   * - the route names no recipient scope. `match.recipients` is the only way a
+   *   route states which recipients it is for, and a pattern that matches every
+   *   address states nothing. Recipient-scoped `process` routes keep winning —
+   *   consumers use them for local addresses handled by their own acceptance
+   *   pipeline. Encoding recipient intent in `match.headers` is not supported
+   *   for this purpose.
+   */
+  private isSubmissionPermissionRouteForLocalRecipient(
+    route: IEmailRoute,
+    recipientDomain: string | undefined,
+    isLocalRecipient: boolean,
+  ): boolean {
+    if (!isLocalRecipient || !recipientDomain) return false;
+    if (route.action.type !== 'process') return false;
+    if (this.domainRegistry.getDomainConfig(recipientDomain)?.inboundPolicy?.defaultAction !== 'store') {
+      return false;
+    }
+    return !this.routeNamesRecipientScope(route.match.recipients);
+  }
+
+  /** Whether a recipient pattern list narrows the route to specific recipients. */
+  private routeNamesRecipientScope(patterns: string | string[] | undefined): boolean {
+    if (patterns === undefined) return false;
+    const patternArray = Array.isArray(patterns) ? patterns : [patterns];
+    return patternArray.some((pattern) => {
+      const normalized = String(pattern || '').trim().toLowerCase();
+      return normalized.length > 0 && normalized !== '*' && normalized !== '*@*';
+    });
+  }
+
   private getRejectionReasonForResolution(
     resolution: IRecipientPolicyResolution,
   ): TRecipientRejectionReason {
@@ -3321,6 +3542,16 @@ export class UnifiedEmailServer extends EventEmitter {
       (!this.options.ports ||
        JSON.stringify(options.ports) !== JSON.stringify(this.options.ports));
     const authEnabledBefore = this.isAuthConfigured(this.options);
+    // TLS material and the upstream-terminated port list are listener-level
+    // Rust configuration too. Without a restart a renewed certificate or a
+    // changed port list would be merged into options and silently never take
+    // effect on the running listener.
+    const tlsMaterialChanged = options.tls !== undefined
+      && (options.tls.certPem !== this.options.tls?.certPem
+        || options.tls.keyPem !== this.options.tls?.keyPem);
+    const tlsTerminatedPortsChanged = options.smtp !== undefined
+      && JSON.stringify(options.smtp.tlsTerminatedPorts ?? [])
+        !== JSON.stringify(this.options.smtp?.tlsTerminatedPorts ?? []);
 
     if (portsChanged) {
       this.stop().then(() => {
@@ -3361,15 +3592,16 @@ export class UnifiedEmailServer extends EventEmitter {
       // auth presence transitions (zero -> first account/user or reverse)
       // the running listener must be restarted for AUTH to take effect
       // without a full process restart.
-      if (
-        options.auth
-        && this.smtpListenerActive
-        && !this.smtpListenerShutdown
+      const listenerRestartReason = options.auth
         && this.isAuthConfigured(this.options) !== authEnabledBefore
-      ) {
-        this.scheduleSmtpListenerRestart(
-          `SMTP AUTH ${this.isAuthConfigured(this.options) ? 'enabled' : 'disabled'} by configuration update`,
-        );
+        ? `SMTP AUTH ${this.isAuthConfigured(this.options) ? 'enabled' : 'disabled'} by configuration update`
+        : tlsMaterialChanged
+          ? 'SMTP TLS material replaced by configuration update'
+          : tlsTerminatedPortsChanged
+            ? 'SMTP upstream-terminated port list changed by configuration update'
+            : undefined;
+      if (listenerRestartReason && this.smtpListenerActive && !this.smtpListenerShutdown) {
+        this.scheduleSmtpListenerRestart(listenerRestartReason);
       }
     }
   }

package/ts/security/classes.rustsecuritybridge.ts

@@ -242,6 +242,7 @@ export interface ISmtpDeliveryErrorDetails {
   recipients?: string[];
   recipientDomain?: string;
   recipientResults?: ISmtpRecipientResult[];
+  outboundAuthenticationHandle?: IOutboundAuthenticationHandle;
 }
 
 interface ISmtpRecipientResult {
@@ -259,6 +260,7 @@ export class SmtpDeliveryError extends Error implements ISmtpDeliveryErrorDetail
   public readonly recipients: string[];
   public readonly recipientDomain?: string;
   public readonly recipientResults: ISmtpRecipientResult[];
+  public readonly outboundAuthenticationHandle?: IOutboundAuthenticationHandle;
 
   constructor(details: ISmtpDeliveryErrorDetails, cause?: unknown) {
     const transactionLog = normalizeSmtpTranscript(details.transactionLog);
@@ -277,6 +279,7 @@ export class SmtpDeliveryError extends Error implements ISmtpDeliveryErrorDetail
     this.recipients = details.recipients || [];
     this.recipientDomain = details.recipientDomain;
     this.recipientResults = (details.recipientResults || []).map((result) => ({ ...result }));
+    this.outboundAuthenticationHandle = details.outboundAuthenticationHandle;
     if (cause !== undefined && !authFailure) {
       (this as Error & { cause?: unknown }).cause = cause;
     }
@@ -370,6 +373,31 @@ interface IOutboundEmail {
   }>;
 }
 
+export interface IOutboundAuthenticationCheck {
+  state: 'pending' | 'completed' | 'indeterminate' | 'not-evaluated';
+  overall: 'pass' | 'fail' | 'indeterminate';
+  checkedAt: string;
+  signedMessageSha256?: string;
+  error?: string;
+  identity?: {
+    sourceIp: string;
+    addressFamily: 'ipv4' | 'ipv6';
+    heloDomain: string;
+    receiverHostname: string;
+    envelopeFrom: string;
+    dkimDomain?: string;
+    dkimSelector?: string;
+  };
+  dkim?: IDkimVerificationResult[];
+  spf?: ISpfResult | null;
+  dmarc?: IDmarcResult | null;
+}
+
+export interface IOutboundAuthenticationHandle {
+  pending: IOutboundAuthenticationCheck;
+  result: Promise<IOutboundAuthenticationCheck>;
+}
+
 interface ISmtpSendResult {
   accepted: string[];
   rejected: string[];
@@ -378,6 +406,7 @@ interface ISmtpSendResult {
   response: string;
   envelope: { from: string; to: string[] };
   transactionLog: ISmtpTranscriptEntry[];
+  outboundAuthenticationHandle?: IOutboundAuthenticationHandle;
 }
 
 interface ISmtpSendOptions {
@@ -396,6 +425,14 @@ interface ISmtpSendOptions {
   maxPoolConnections?: number;
   tlsOpportunistic?: boolean;
   disablePooling?: boolean;
+  outboundAuthenticationCaptureId?: string;
+}
+
+interface IVerifyCapturedOutboundEmailResult {
+  state: 'completed' | 'indeterminate';
+  signedMessageSha256?: string;
+  error?: string;
+  result?: IEmailSecurityResult;
 }
 
 interface ISmtpSendRawOptions {
@@ -448,6 +485,8 @@ interface ISmtpServerConfig {
   securePort?: number;
   tlsCertPem?: string;
   tlsKeyPem?: string;
+  /** Ports whose transport a trusted upstream proxy already encrypted. */
+  tlsTerminatedPorts?: number[];
   additionalTlsCerts?: Array<{ domains: string[]; certPem: string; keyPem: string }>;
   maxMessageSize?: number;
   maxConnections?: number;
@@ -632,6 +671,20 @@ type TMailerCommands = {
     params: ISmtpSendRawOptions;
     result: ISmtpSendResult;
   };
+  verifyCapturedOutboundEmail: {
+    params: {
+      captureId: string;
+      ip: string;
+      heloDomain: string;
+      hostname: string;
+      mailFrom: string;
+    };
+    result: IVerifyCapturedOutboundEmailResult;
+  };
+  discardCapturedOutboundEmail: {
+    params: { captureId: string };
+    result: { discarded: boolean };
+  };
   verifySmtpConnection: {
     params: ISmtpVerifyOptions;
     result: ISmtpVerifyResult;
@@ -1187,6 +1240,7 @@ export class RustSecurityBridge extends EventEmitter {
     this.ensureRunning();
     try {
       const result = await this.bridge.sendCommand('sendRawEmail', opts);
+
       return {
         ...result,
         transactionLog: normalizeSmtpTranscript(result.transactionLog),
@@ -1196,6 +1250,22 @@ export class RustSecurityBridge extends EventEmitter {
     }
   }
 
+  public async verifyCapturedOutboundEmail(opts: {
+    captureId: string;
+    ip: string;
+    heloDomain: string;
+    hostname: string;
+    mailFrom: string;
+  }): Promise<IVerifyCapturedOutboundEmailResult> {
+    this.ensureRunning();
+    return this.bridge.sendCommand('verifyCapturedOutboundEmail', opts);
+  }
+
+  public async discardCapturedOutboundEmail(captureId: string): Promise<void> {
+    this.ensureRunning();
+    await this.bridge.sendCommand('discardCapturedOutboundEmail', { captureId });
+  }
+
   /** Verify connectivity to an SMTP server. */
   public async verifySmtpConnection(opts: ISmtpVerifyOptions): Promise<ISmtpVerifyResult> {
     this.ensureRunning();