@push.rocks/smartmta 9.3.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 {
@@ -937,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 } : {}),
@@ -953,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
    */

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 {
@@ -634,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;
@@ -1189,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),
@@ -1198,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();