@push.rocks/smartmta 5.3.3 → 6.0.1

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

@@ -10,7 +10,7 @@ import {
 import { DKIMCreator } from '../security/classes.dkimcreator.js';
 import { hasStorageManagerMethods, type IStorageManagerLike } from '../interfaces.storage.js';
 import { RustSecurityBridge } from '../../security/classes.rustsecuritybridge.js';
-import type { IEmailReceivedEvent, IAuthRequestEvent } from '../../security/classes.rustsecuritybridge.js';
+import type { IEmailReceivedEvent, IRcptToRequestEvent, IAuthRequestEvent, IScramCredentialRequestEvent } from '../../security/classes.rustsecuritybridge.js';
 import { EmailRouter } from './classes.email.router.js';
 import type { IEmailRoute, IEmailContext, IEmailDomainConfig } from './interfaces.js';
 import { Email } from '../core/classes.email.js';
@@ -44,6 +44,37 @@ export interface IExtendedSmtpSession extends ISmtpSession {
   matchedRoute?: IEmailRoute;
 }
 
+export interface ISmtpDecision {
+  accepted: boolean;
+  smtpCode?: number;
+  smtpMessage?: string;
+}
+
+export interface IRcptToPolicyContext {
+  sessionId: string;
+  mailFrom: string;
+  rcptTo: string;
+  acceptedRcptTo: string[];
+  remoteAddress: string;
+  clientHostname: string | null;
+  secure: boolean;
+  authenticated: boolean;
+  authenticatedUser: string | null;
+  abortSignal?: AbortSignal;
+}
+
+export interface IMessageAcceptanceContext {
+  email: Email;
+  rawMessage: Buffer;
+  session: IExtendedSmtpSession;
+  abortSignal?: AbortSignal;
+}
+
+export interface IMessageAcceptanceDecision extends ISmtpDecision {
+  /** Continue SmartMTA's built-in route processing after the consumer accepted responsibility. */
+  continueProcessing?: boolean;
+}
+
 /**
  * Options for the unified email server
  */
@@ -87,6 +118,27 @@ export interface IUnifiedEmailServerOptions {
   // Email routing rules
   routes: IEmailRoute[];
 
+  smtp?: {
+    /** Enable route/hook based RCPT TO validation before DATA. Defaults to true; set false only for fully trusted private listeners. */
+    recipientValidation?: boolean;
+    /** Timeout for RCPT policy callbacks. Defaults to 5000 ms. */
+    recipientValidationTimeoutMs?: number;
+    /** Timeout for message acceptance callbacks. Defaults to 30000 ms. */
+    messageAcceptanceTimeoutMs?: number;
+    /** Require trusted PROXY v1 from the backend proxy before SMTP greeting. */
+    proxyProtocol?: {
+      required?: boolean;
+      trustedIps?: string[];
+    };
+  };
+
+  hooks?: {
+    /** Async recipient policy hook, called before each RCPT TO is accepted. */
+    onRcptTo?: (context: IRcptToPolicyContext) => Promise<ISmtpDecision>;
+    /** Async message acceptance hook, called after DATA before the final SMTP response. */
+    onMessageData?: (context: IMessageAcceptanceContext) => Promise<IMessageAcceptanceDecision>;
+  };
+
   // Global defaults for all domains
   defaults?: {
     dnsMode?: 'forward' | 'internal-dns' | 'external-dns';
@@ -180,6 +232,11 @@ export class UnifiedEmailServer extends EventEmitter {
   // Extracted subsystems
   private actionExecutor: EmailActionExecutor;
   private dkimManager: DkimManager;
+  private bridgeStateChangeHandler?: (event: { oldState: string; newState: string }) => void;
+  private bridgeRcptToRequestHandler?: (data: IRcptToRequestEvent) => void;
+  private bridgeEmailReceivedHandler?: (data: IEmailReceivedEvent) => void;
+  private bridgeAuthRequestHandler?: (data: IAuthRequestEvent) => void;
+  private bridgeScramCredentialRequestHandler?: (data: IScramCredentialRequestEvent) => void;
 
   constructor(dcRouter: DcRouter, options: IUnifiedEmailServerOptions) {
     super();
@@ -360,6 +417,11 @@ export class UnifiedEmailServer extends EventEmitter {
       this.emit('started');
     } catch (error) {
       logger.log('error', `Failed to start UnifiedEmailServer: ${error.message}`);
+      try {
+        await this.stop();
+      } catch (cleanupError) {
+        logger.log('warn', `Error cleaning up failed start: ${(cleanupError as Error).message}`);
+      }
       throw error;
     }
   }
@@ -379,11 +441,13 @@ export class UnifiedEmailServer extends EventEmitter {
     }
     logger.log('info', 'Rust security bridge started — Rust is the primary security backend');
 
-    this.rustBridge.on('stateChange', ({ oldState, newState }: { oldState: string; newState: string }) => {
+    this.unregisterBridgeStateHandler();
+    this.bridgeStateChangeHandler = ({ oldState, newState }: { oldState: string; newState: string }) => {
       if (newState === 'failed') this.emit('bridgeFailed');
       else if (newState === 'restarting') this.emit('bridgeRestarting');
       else if (newState === 'running' && oldState === 'restarting') this.emit('bridgeRecovered');
-    });
+    };
+    this.rustBridge.on('stateChange', this.bridgeStateChangeHandler);
   }
 
   private async initializeDkimAndDns(): Promise<void> {
@@ -402,7 +466,28 @@ export class UnifiedEmailServer extends EventEmitter {
   }
 
   private registerBridgeEventHandlers(): void {
-    this.rustBridge.onEmailReceived(async (data) => {
+    this.unregisterBridgeEventHandlers();
+
+    this.bridgeRcptToRequestHandler = async (data) => {
+      try {
+        await this.handleRustRcptToRequest(data);
+      } catch (err) {
+        logger.log('error', `Error handling RCPT policy request from Rust SMTP: ${(err as Error).message}`);
+        try {
+          await this.rustBridge.sendRcptToResult({
+            correlationId: data.correlationId,
+            accepted: false,
+            smtpCode: 451,
+            smtpMessage: 'Recipient policy error',
+          });
+        } catch (sendErr) {
+          logger.log('warn', `Could not send RCPT policy rejection back to Rust: ${(sendErr as Error).message}`);
+        }
+      }
+    };
+    this.rustBridge.onRcptToRequest(this.bridgeRcptToRequestHandler);
+
+    this.bridgeEmailReceivedHandler = async (data) => {
       try {
         await this.handleRustEmailReceived(data);
       } catch (err) {
@@ -418,9 +503,10 @@ export class UnifiedEmailServer extends EventEmitter {
           logger.log('warn', `Could not send rejection back to Rust: ${(sendErr as Error).message}`);
         }
       }
-    });
+    };
+    this.rustBridge.onEmailReceived(this.bridgeEmailReceivedHandler);
 
-    this.rustBridge.onAuthRequest(async (data) => {
+    this.bridgeAuthRequestHandler = async (data) => {
       try {
         await this.handleRustAuthRequest(data);
       } catch (err) {
@@ -435,9 +521,10 @@ export class UnifiedEmailServer extends EventEmitter {
           logger.log('warn', `Could not send auth rejection back to Rust: ${(sendErr as Error).message}`);
         }
       }
-    });
+    };
+    this.rustBridge.onAuthRequest(this.bridgeAuthRequestHandler);
 
-    this.rustBridge.onScramCredentialRequest(async (data) => {
+    this.bridgeScramCredentialRequestHandler = async (data) => {
       try {
         await this.handleScramCredentialRequest(data);
       } catch (err) {
@@ -451,7 +538,34 @@ export class UnifiedEmailServer extends EventEmitter {
           logger.log('warn', `Could not send SCRAM credential rejection: ${(sendErr as Error).message}`);
         }
       }
-    });
+    };
+    this.rustBridge.onScramCredentialRequest(this.bridgeScramCredentialRequestHandler);
+  }
+
+  private unregisterBridgeStateHandler(): void {
+    if (this.bridgeStateChangeHandler) {
+      this.rustBridge.off('stateChange', this.bridgeStateChangeHandler);
+      this.bridgeStateChangeHandler = undefined;
+    }
+  }
+
+  private unregisterBridgeEventHandlers(): void {
+    if (this.bridgeRcptToRequestHandler) {
+      this.rustBridge.offRcptToRequest(this.bridgeRcptToRequestHandler);
+      this.bridgeRcptToRequestHandler = undefined;
+    }
+    if (this.bridgeEmailReceivedHandler) {
+      this.rustBridge.offEmailReceived(this.bridgeEmailReceivedHandler);
+      this.bridgeEmailReceivedHandler = undefined;
+    }
+    if (this.bridgeAuthRequestHandler) {
+      this.rustBridge.offAuthRequest(this.bridgeAuthRequestHandler);
+      this.bridgeAuthRequestHandler = undefined;
+    }
+    if (this.bridgeScramCredentialRequestHandler) {
+      this.rustBridge.offScramCredentialRequest(this.bridgeScramCredentialRequestHandler);
+      this.bridgeScramCredentialRequestHandler = undefined;
+    }
   }
 
   private async startSmtpServer(): Promise<void> {
@@ -486,7 +600,14 @@ export class UnifiedEmailServer extends EventEmitter {
       authEnabled: !!this.options.auth?.required || !!(this.options.auth?.users?.length),
       maxAuthFailures: 3,
       socketTimeoutSecs: this.options.socketTimeout ? Math.floor(this.options.socketTimeout / 1000) : 300,
-      processingTimeoutSecs: 30,
+      processingTimeoutSecs: this.options.hooks?.onMessageData
+        ? Math.ceil(this.getMessageAcceptanceTimeoutMs() / 1000) + 1
+        : 30,
+      recipientValidationEnabled: this.isRecipientValidationEnabled(),
+      recipientValidationTimeoutSecs: this.options.smtp?.recipientValidationTimeoutMs
+        ? Math.ceil(this.options.smtp.recipientValidationTimeoutMs / 1000)
+        : 5,
+      proxyProtocol: this.options.smtp?.proxyProtocol,
       rateLimits: this.options.rateLimits ? {
         maxConnectionsPerIp: this.options.rateLimits.global?.maxConnectionsPerIP || 50,
         maxMessagesPerSender: this.options.rateLimits.global?.maxMessagesPerMinute || 100,
@@ -520,8 +641,8 @@ export class UnifiedEmailServer extends EventEmitter {
       // Clear the servers array - servers will be garbage collected
       this.servers = [];
 
-      // Remove bridge state change listener and stop bridge
-      this.rustBridge.removeAllListeners('stateChange');
+      this.unregisterBridgeEventHandlers();
+      this.unregisterBridgeStateHandler();
       await this.rustBridge.stop();
 
       // Stop the delivery system
@@ -558,6 +679,170 @@ export class UnifiedEmailServer extends EventEmitter {
   // Rust SMTP server event handlers
   // -----------------------------------------------------------------------
 
+  private async handleRustRcptToRequest(data: IRcptToRequestEvent): Promise<void> {
+    const context: IRcptToPolicyContext = {
+      sessionId: data.sessionId,
+      mailFrom: data.mailFrom,
+      rcptTo: data.rcptTo,
+      acceptedRcptTo: data.acceptedRcptTo || [],
+      remoteAddress: data.remoteAddr,
+      clientHostname: data.clientHostname,
+      secure: data.secure,
+      authenticated: !!data.authenticatedUser,
+      authenticatedUser: data.authenticatedUser,
+    };
+
+    const hookDecision = this.options.hooks?.onRcptTo
+      ? await this.runHookWithTimeout(
+          this.getRecipientValidationTimeoutMs(),
+          'Recipient policy timeout',
+          (abortSignal) => this.options.hooks!.onRcptTo!({ ...context, abortSignal })
+        )
+      : await this.evaluateDefaultRcptToPolicy(context);
+    const decision = this.options.hooks?.onRcptTo
+      ? await this.enforceAcceptedRcptToRelayPolicy(context, hookDecision)
+      : hookDecision;
+
+    await this.rustBridge.sendRcptToResult({
+      correlationId: data.correlationId,
+      accepted: decision.accepted,
+      smtpCode: decision.smtpCode,
+      smtpMessage: decision.smtpMessage,
+    });
+  }
+
+  private async evaluateDefaultRcptToPolicy(context: IRcptToPolicyContext): Promise<ISmtpDecision> {
+    const currentRecipientContext = { ...context, acceptedRcptTo: [] };
+    const email = new Email({
+      from: context.mailFrom || '<>',
+      to: [context.rcptTo],
+      subject: '',
+      text: '',
+    });
+    const session = this.buildPolicySession(currentRecipientContext);
+    const route = await this.emailRouter.evaluateRoutes({ email, session });
+
+    if (!route) {
+      return { accepted: false, smtpCode: 550, smtpMessage: 'No route for recipient' };
+    }
+    if (route.action.type === 'reject') {
+      return {
+        accepted: false,
+        smtpCode: route.action.reject?.code || 550,
+        smtpMessage: route.action.reject?.message || 'Recipient rejected',
+      };
+    }
+
+    const recipientDomain = this.getAddressDomain(context.rcptTo);
+    const isLocalRecipient = !!recipientDomain && this.domainRegistry.isDomainRegistered(recipientDomain);
+    if (!isLocalRecipient && !route.action.allowRelay) {
+      return { accepted: false, smtpCode: 550, smtpMessage: 'Relay not permitted' };
+    }
+
+    return { accepted: true, smtpCode: 250, smtpMessage: 'OK' };
+  }
+
+  private async enforceAcceptedRcptToRelayPolicy(
+    context: IRcptToPolicyContext,
+    decision: ISmtpDecision
+  ): Promise<ISmtpDecision> {
+    if (!decision.accepted) {
+      return decision;
+    }
+
+    const recipientDomain = this.getAddressDomain(context.rcptTo);
+    const isLocalRecipient = !!recipientDomain && this.domainRegistry.isDomainRegistered(recipientDomain);
+    if (isLocalRecipient) {
+      return decision;
+    }
+
+    const currentRecipientContext = { ...context, acceptedRcptTo: [] };
+    const email = new Email({
+      from: context.mailFrom || '<>',
+      to: [context.rcptTo],
+      subject: '',
+      text: '',
+    });
+    const session = this.buildPolicySession(currentRecipientContext);
+    const route = await this.emailRouter.evaluateRoutes({ email, session });
+
+    if (route?.action.type !== 'reject' && route?.action.allowRelay) {
+      return decision;
+    }
+
+    return { accepted: false, smtpCode: 550, smtpMessage: 'Relay not permitted' };
+  }
+
+  private buildPolicySession(context: IRcptToPolicyContext): IExtendedSmtpSession {
+    const session: IExtendedSmtpSession = {
+      id: context.sessionId,
+      state: SmtpState.RCPT_TO,
+      mailFrom: context.mailFrom,
+      rcptTo: [...context.acceptedRcptTo, context.rcptTo],
+      emailData: '',
+      useTLS: context.secure,
+      connectionEnded: false,
+      remoteAddress: context.remoteAddress,
+      clientHostname: context.clientHostname || '',
+      secure: context.secure,
+      authenticated: context.authenticated,
+      envelope: {
+        mailFrom: { address: context.mailFrom, args: {} },
+        rcptTo: [...context.acceptedRcptTo, context.rcptTo].map(address => ({ address, args: {} })),
+      },
+    };
+    if (context.authenticatedUser) {
+      session.user = { username: context.authenticatedUser };
+    }
+    return session;
+  }
+
+  private getAddressDomain(address: string): string | undefined {
+    const match = address.trim().toLowerCase().match(/@([^>\s]+)>?$/);
+    return match?.[1];
+  }
+
+  private getRecipientValidationTimeoutMs(): number {
+    return this.options.smtp?.recipientValidationTimeoutMs || 5000;
+  }
+
+  private isRecipientValidationEnabled(): boolean {
+    return this.options.smtp?.recipientValidation !== false;
+  }
+
+  private getMessageAcceptanceTimeoutMs(): number {
+    return this.options.smtp?.messageAcceptanceTimeoutMs || 30000;
+  }
+
+  private async runHookWithTimeout<T>(
+    timeoutMs: number,
+    timeoutMessage: string,
+    hookRunner: (abortSignal: AbortSignal) => Promise<T>,
+    onTimeout?: () => void
+  ): Promise<T> {
+    const abortController = new AbortController();
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    const timeoutPromise = new Promise<never>((_resolve, reject) => {
+      timeoutHandle = setTimeout(() => {
+        abortController.abort();
+        onTimeout?.();
+        reject(new Error(timeoutMessage));
+      }, timeoutMs);
+    });
+
+    try {
+      return await Promise.race([
+        hookRunner(abortController.signal),
+        timeoutPromise,
+      ]);
+    } finally {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+      abortController.abort();
+    }
+  }
+
   /**
    * Handle an emailReceived event from the Rust SMTP server.
    */
@@ -572,12 +857,14 @@ export class UnifiedEmailServer extends EventEmitter {
       if (data.data.type === 'inline' && data.data.base64) {
         rawMessageBuffer = Buffer.from(data.data.base64, 'base64');
       } else if (data.data.type === 'file' && data.data.path) {
-        rawMessageBuffer = plugins.fs.readFileSync(data.data.path);
-        // Clean up temp file
         try {
-          plugins.fs.unlinkSync(data.data.path);
-        } catch {
-          // Ignore cleanup errors
+          rawMessageBuffer = plugins.fs.readFileSync(data.data.path);
+        } finally {
+          try {
+            plugins.fs.unlinkSync(data.data.path);
+          } catch {
+            // Ignore cleanup errors
+          }
         }
       } else {
         throw new Error('Invalid email data transport');
@@ -611,15 +898,70 @@ export class UnifiedEmailServer extends EventEmitter {
         (session as any)._precomputedSecurityResults = data.securityResults;
       }
 
-      // Process the email through the routing system
-      await this.processEmailByMode(rawMessageBuffer, session);
+      const email = await this.createEmailFromBuffer(rawMessageBuffer, session);
+      let acceptanceDecision: IMessageAcceptanceDecision | undefined;
+      if (this.options.hooks?.onMessageData) {
+        let hookContext: IMessageAcceptanceContext | undefined;
+        try {
+          acceptanceDecision = await this.runHookWithTimeout(
+            this.getMessageAcceptanceTimeoutMs(),
+            'Message acceptance timeout',
+            (abortSignal) => {
+              hookContext = {
+                email,
+                rawMessage: rawMessageBuffer,
+                session,
+                abortSignal,
+              };
+              return this.options.hooks!.onMessageData!(hookContext);
+            },
+            () => {
+              if (hookContext) {
+                hookContext.rawMessage = Buffer.alloc(0);
+                (hookContext as any).email = undefined;
+                (hookContext as any).session = undefined;
+              }
+            }
+          );
+        } catch (acceptanceError) {
+          logger.log('error', `Message acceptance hook failed: ${(acceptanceError as Error).message}`);
+          await this.rustBridge.sendEmailProcessingResult({
+            correlationId,
+            accepted: false,
+            smtpCode: 451,
+            smtpMessage: 'Message acceptance temporarily unavailable',
+          });
+          return;
+        }
+      }
+
+      if (acceptanceDecision && !acceptanceDecision.accepted) {
+        await this.rustBridge.sendEmailProcessingResult({
+          correlationId,
+          accepted: false,
+          smtpCode: acceptanceDecision.smtpCode || 451,
+          smtpMessage: acceptanceDecision.smtpMessage || 'Message not accepted',
+        });
+        return;
+      }
+
+      if (!acceptanceDecision || acceptanceDecision.continueProcessing) {
+        try {
+          await this.processEmailByMode(email, session);
+        } catch (processingError) {
+          if (!acceptanceDecision) {
+            throw processingError;
+          }
+          logger.log('error', `Post-acceptance processing failed: ${(processingError as Error).message}`);
+        }
+      }
 
       // Send acceptance back to Rust
       await this.rustBridge.sendEmailProcessingResult({
         correlationId,
         accepted: true,
         smtpCode: 250,
-        smtpMessage: '2.0.0 Message accepted for delivery',
+        smtpMessage: acceptanceDecision?.smtpMessage || '2.0.0 Message accepted for delivery',
       });
     } catch (err) {
       logger.log('error', `Failed to process email from Rust SMTP: ${(err as Error).message}`);
@@ -632,6 +974,80 @@ export class UnifiedEmailServer extends EventEmitter {
     }
   }
 
+  private async createEmailFromBuffer(emailData: Buffer, session: IExtendedSmtpSession): Promise<Email> {
+    try {
+      const parsed = await plugins.mailparser.simpleParser(emailData);
+      const envelopeRecipients = session.envelope.rcptTo.map(recipient => recipient.address);
+      const parsedTo = ((parsed.to as any)?.value || [])
+        .map((recipient: any) => recipient.address)
+        .filter(Boolean) as string[];
+      const parsedCc = ((parsed.cc as any)?.value || [])
+        .map((recipient: any) => recipient.address)
+        .filter(Boolean) as string[];
+      const parsedHeaders: Record<string, string> = {};
+      for (const [headerName, headerValue] of parsed.headers.entries()) {
+        if (this.isStandardParsedHeader(headerName)) {
+          continue;
+        }
+        parsedHeaders[headerName] = this.stringifyParsedHeaderValue(headerValue);
+      }
+      return new Email({
+        from: parsed.from?.value[0]?.address || session.envelope.mailFrom.address,
+        to: envelopeRecipients.length > 0
+          ? envelopeRecipients
+          : parsedTo,
+        cc: parsedCc,
+        bcc: [],
+        subject: parsed.subject || '',
+        text: parsed.text || '',
+        html: parsed.html || undefined,
+        headers: parsedHeaders,
+        attachments: parsed.attachments?.map(att => ({
+          filename: att.filename || '',
+          content: att.content,
+          contentType: att.contentType
+        })) || []
+      });
+    } catch (error) {
+      logger.log('error', `Error parsing email data: ${(error as Error).message}`);
+      throw new Error(`Error parsing email data: ${(error as Error).message}`);
+    }
+  }
+
+  private isStandardParsedHeader(headerName: string): boolean {
+    return new Set([
+      'from',
+      'to',
+      'cc',
+      'bcc',
+      'subject',
+      'date',
+      'message-id',
+      'return-path',
+      'reply-to',
+      'sender',
+      'mime-version',
+      'content-type',
+      'content-transfer-encoding',
+    ]).has(headerName.toLowerCase());
+  }
+
+  private stringifyParsedHeaderValue(headerValue: unknown): string {
+    if (Array.isArray(headerValue)) {
+      return headerValue.map(value => this.stringifyParsedHeaderValue(value)).join(', ');
+    }
+    if (headerValue instanceof Date) {
+      return headerValue.toUTCString();
+    }
+    if (typeof headerValue === 'string') {
+      return headerValue;
+    }
+    if (headerValue && typeof headerValue === 'object' && 'text' in headerValue) {
+      return String((headerValue as { text?: unknown }).text || '');
+    }
+    return headerValue === undefined || headerValue === null ? '' : String(headerValue);
+  }
+
   /**
    * Handle an authRequest event from the Rust SMTP server.
    */
@@ -803,25 +1219,7 @@ export class UnifiedEmailServer extends EventEmitter {
     // Convert Buffer to Email if needed
     let email: Email;
     if (Buffer.isBuffer(emailData)) {
-      // Parse the email data buffer into an Email object
-      try {
-        const parsed = await plugins.mailparser.simpleParser(emailData);
-        email = new Email({
-          from: parsed.from?.value[0]?.address || session.envelope.mailFrom.address,
-          to: session.envelope.rcptTo[0]?.address || '',
-          subject: parsed.subject || '',
-          text: parsed.text || '',
-          html: parsed.html || undefined,
-          attachments: parsed.attachments?.map(att => ({
-            filename: att.filename || '',
-            content: att.content,
-            contentType: att.contentType
-          })) || []
-        });
-      } catch (error) {
-        logger.log('error', `Error parsing email data: ${error.message}`);
-        throw new Error(`Error parsing email data: ${error.message}`);
-      }
+      email = await this.createEmailFromBuffer(emailData, session);
     } else {
       email = emailData;
     }

package/ts/mail/routing/interfaces.ts

@@ -45,6 +45,8 @@ export interface IEmailMatch {
 export interface IEmailAction {
   /** Type of action to perform */
   type: 'forward' | 'deliver' | 'reject' | 'process';
+  /** Explicitly permits this route to relay to non-local recipients. */
+  allowRelay?: boolean;
   
   /** Forward action configuration */
   forward?: {
@@ -199,4 +201,4 @@ export interface IEmailDomainConfig {
       recipientsPerMessage?: number;
     };
   };
-}
+}