@push.rocks/smartmta 8.0.0 → 8.1.0

package/ts/mail/delivery/classes.delivery.system.ts

@@ -10,6 +10,7 @@ import {
   UnifiedDeliveryQueue,
   type IQueueItem,
   type IRecipientPermanentFailure,
+  type IBounceOperation,
 } from './classes.delivery.queue.js';
 import { Email } from '../core/classes.email.js';
 import type { UnifiedEmailServer } from '../routing/classes.unified.email.server.js';
@@ -41,6 +42,17 @@ export interface IDeliveryHandler {
   deliver(item: IQueueItem): Promise<any>;
 }
 
+export interface IDeliveryFailureNotice {
+  itemId: string;
+  operation: Readonly<IBounceOperation>;
+  sender: string;
+  headers: Readonly<Record<string, string>>;
+}
+
+export interface IDeliveryFailureHandler {
+  processDeliveryFailure(notice: IDeliveryFailureNotice): Promise<void>;
+}
+
 /**
  * Delivery options
  */
@@ -71,7 +83,9 @@ export interface IMultiModeDeliveryOptions {
   bounceHandler?: {
     processSmtpFailure: (recipient: string, smtpResponse: string, options: any) => Promise<any>;
   };
-  
+  /** Durable, idempotent terminal-delivery notice consumer. */
+  deliveryFailureHandler?: IDeliveryFailureHandler;
+
   // Event hooks
   onDeliveryStart?: (item: IQueueItem) => Promise<void>;
   onDeliverySuccess?: (item: IQueueItem, result: any) => Promise<void>;
@@ -112,9 +126,10 @@ export interface IDeliveryStats {
  */
 type TResolvedMultiModeDeliveryOptions = Omit<
   Required<IMultiModeDeliveryOptions>,
-  'bounceHandler'
+  'bounceHandler' | 'deliveryFailureHandler'
 > & {
   bounceHandler?: NonNullable<IMultiModeDeliveryOptions['bounceHandler']>;
+  deliveryFailureHandler: IDeliveryFailureHandler;
 };
 
 export class MultiModeDeliverySystem extends EventEmitter {
@@ -165,6 +180,12 @@ export class MultiModeDeliverySystem extends EventEmitter {
       perPatternRateLimit: options.perPatternRateLimit || {},
       processBounces: options.processBounces !== false, // Default to true
       bounceHandler: options.bounceHandler,
+      deliveryFailureHandler: options.deliveryFailureHandler || {
+        processDeliveryFailure: async (notice) => {
+          logger.log('warn', `Terminal delivery failure persisted for ${notice.operation.recipient}`);
+          await emitSafely(this, 'deliveryFailureNotice', notice);
+        },
+      },
       onDeliveryStart: options.onDeliveryStart || (async () => {}),
       onDeliverySuccess: options.onDeliverySuccess || (async () => {}),
       onDeliveryFailed: options.onDeliveryFailed || (async () => {})
@@ -313,34 +334,68 @@ export class MultiModeDeliverySystem extends EventEmitter {
   }
 
   /**
-   * Drain durable bounce work with one in-process flight. Custom handlers
+   * Drain durable failure work with one in-process flight. Custom handlers
    * receive operationId and must use it for their own idempotency.
    */
   public async drainBounceOutbox(): Promise<void> {
     if (this.bounceDrainPromise) return this.bounceDrainPromise;
     const drain = (async () => {
-      if (!this.options.processBounces || !this.options.bounceHandler) return;
-      for (const { itemId, operation } of this.queue.listPendingBounceOperations()) {
+      if (this.options.processBounces && this.options.bounceHandler) {
+        for (const { itemId, operation } of this.queue.listPendingBounceOperations()) {
+          const item = this.queue.getItem(itemId);
+          if (!item) continue;
+          const email = item.processingResult as Email;
+          try {
+            await this.options.bounceHandler.processSmtpFailure(
+              operation.recipient,
+              operation.smtpResponse,
+              {
+                operationId: operation.operationId,
+                sender: email.from,
+                originalEmailId: item.id,
+                headers: email.headers,
+                statusCode: String(operation.smtpCode),
+              },
+            );
+            await this.queue.markBounceOperationCompleted(itemId, operation.operationId);
+          } catch (error) {
+            logger.log(
+              'error',
+              `Bounce operation ${operation.operationId} failed: ${(error as Error).message}`,
+            );
+            try {
+              await this.queue.markBounceOperationFailed(
+                itemId,
+                operation.operationId,
+                (error as Error).message,
+              );
+            } catch (checkpointError) {
+              logger.log(
+                'error',
+                `Could not checkpoint failed bounce operation ${operation.operationId}: ${(checkpointError as Error).message}`,
+              );
+            }
+          }
+        }
+      }
+
+      for (const { itemId, operation } of this.queue.listPendingDeliveryFailureOperations()) {
         const item = this.queue.getItem(itemId);
         if (!item) continue;
         const email = item.processingResult as Email;
+        const notice: IDeliveryFailureNotice = {
+          itemId,
+          operation,
+          sender: email.from,
+          headers: { ...email.headers },
+        };
         try {
-          await this.options.bounceHandler.processSmtpFailure(
-            operation.recipient,
-            operation.smtpResponse,
-            {
-              operationId: operation.operationId,
-              sender: email.from,
-              originalEmailId: item.id,
-              headers: email.headers,
-              statusCode: String(operation.smtpCode),
-            },
-          );
+          await this.options.deliveryFailureHandler.processDeliveryFailure(notice);
           await this.queue.markBounceOperationCompleted(itemId, operation.operationId);
         } catch (error) {
           logger.log(
             'error',
-            `Bounce operation ${operation.operationId} failed: ${(error as Error).message}`,
+            `Delivery-failure operation ${operation.operationId} failed: ${(error as Error).message}`,
           );
           try {
             await this.queue.markBounceOperationFailed(
@@ -351,7 +406,7 @@ export class MultiModeDeliverySystem extends EventEmitter {
           } catch (checkpointError) {
             logger.log(
               'error',
-              `Could not checkpoint failed bounce operation ${operation.operationId}: ${(checkpointError as Error).message}`,
+              `Could not checkpoint failed delivery-failure operation ${operation.operationId}: ${(checkpointError as Error).message}`,
             );
           }
         }
@@ -619,6 +674,12 @@ export class MultiModeDeliverySystem extends EventEmitter {
 
       const transition = await this.queue.markFailedWithTransition(item.id, deliveryError.message, {
         retryable: deliveryError.retryable,
+        terminalFailure: {
+          failureClass: deliveryError.errorType.startsWith('self_mx_')
+            ? 'localTopology'
+            : 'transport',
+          ...(deliveryError.smtpCode !== undefined ? { smtpCode: deliveryError.smtpCode } : {}),
+        },
       });
       if (this.running) void this.drainBounceOutbox();
       if (!transition.updated) return;
@@ -832,6 +893,9 @@ export class MultiModeDeliverySystem extends EventEmitter {
       && typeof failure.smtpCode === 'number'
       && failure.smtpCode >= 500
     ));
+    const allLocalTopologyFailures = normalized.every((failure) => (
+      failure.errorType.startsWith('self_mx_')
+    ));
     const selected = normalized.find((failure) => failure.retryable)
       || normalized[normalized.length - 1];
     const smtpCode = allPermanentRecipientRejections
@@ -839,7 +903,11 @@ export class MultiModeDeliverySystem extends EventEmitter {
       : selected.smtpCode;
     return new SmtpDeliveryError({
       message: normalized.map((failure) => failure.message).join('; '),
-      errorType: allPermanentRecipientRejections ? 'protocol' : 'smtp_aggregate',
+      errorType: allPermanentRecipientRejections
+        ? 'protocol'
+        : allLocalTopologyFailures
+          ? selected.errorType
+          : 'smtp_aggregate',
       retryable,
       ...(smtpCode !== undefined ? { smtpCode } : {}),
       phase: allPermanentRecipientRejections ? 'rcpt_to' : selected.phase,
@@ -903,37 +971,65 @@ export class MultiModeDeliverySystem extends EventEmitter {
 
     for (const [domain, recipients] of domainGroups) {
       const allMxHosts = await this.resolveMxForDomain(domain);
+      let recipientsForMx = [...recipients];
+      const domainFailures: SmtpDeliveryError[] = [];
+      const acceptedForDomain: string[] = [];
+      const mxHosts: typeof allMxHosts = [];
+
+      // RFC 5321 §5.3.6: skip local MX identities but continue to non-local
+      // backup MX hosts. Proxy connection targets are intentionally absent
+      // from this identity check.
+      for (const mx of allMxHosts) {
+        const identity = await this.emailServer.resolveSelfMxIdentity(mx.exchange);
+        if (!identity.isSelf && !identity.indeterminate) {
+          mxHosts.push(mx);
+          continue;
+        }
 
-      // RFC 5321 §5.3.6: never relay to an MX that is this server itself —
-      // that is a mail loop (observed live: a managed domain whose MX record
-      // points at our own mail hostname re-enters the inbound pipeline).
-      const mxHosts = allMxHosts.filter(mx => !this.emailServer!.isSelfHostname(mx.exchange));
-      if (mxHosts.length === 0) {
-        const selfMx = allMxHosts.map(mx => mx.exchange).join(', ');
+        const startedAt = new Date();
+        const retryable = identity.source !== 'explicit';
+        const errorType = identity.indeterminate
+          ? 'self_mx_dns_indeterminate'
+          : identity.source === 'explicit'
+            ? 'self_mx_config'
+            : 'self_mx_loop';
+        const reason = identity.indeterminate
+          ? 'could not be safely classified against current DNS and listener topology'
+          : identity.source === 'explicit'
+            ? 'exactly matches a configured listener identity'
+            : 'resolves to the current listener topology';
+        const evidence = identity.evidence.length > 0
+          ? ` (${identity.evidence.join('; ')})`
+          : '';
         const loopError = new SmtpDeliveryError({
-          message: `MX for ${domain} (${selfMx || 'none'}) points back at this server — refusing self-delivery to avoid a mail loop`,
-          errorType: 'config',
-          retryable: false,
+          message: identity.indeterminate
+            ? `MX ${mx.exchange} for ${domain} ${reason}${evidence}`
+            : `MX ${mx.exchange} for ${domain} points back at this server because it ${reason}${evidence}`,
+          errorType,
+          retryable,
           phase: 'connect',
-          transactionLog: [],
+          transactionLog: [{
+            timestampMs: Date.now(),
+            phase: 'connect',
+            direction: 'system',
+            text: `Skipped ${mx.exchange}: ${reason}`,
+          }],
           recipients,
           recipientDomain: domain,
         });
-        unresolvedFailures.push(loopError);
-        unresolvedRecipients.push(...recipients);
-        results.push({
-          domain,
-          success: false,
-          error: loopError.message,
+        await this.persistSmtpAttempt({
+          item,
+          targetHost: mx.exchange,
+          targetPort: 25,
+          recipientDomain: domain,
+          recipients,
+          startedAt,
+          error: loopError,
         });
-        logger.log('error', `MTA: refusing self-delivery for ${domain} — MX (${selfMx}) is this server's own hostname (mail loop)`);
-        continue;
+        domainFailures.push(loopError);
+        logger.log(retryable ? 'warn' : 'error', `MTA: skipped MX ${mx.exchange} for ${domain}: ${loopError.message}`);
       }
 
-      let recipientsForMx = [...recipients];
-      const domainFailures: SmtpDeliveryError[] = [];
-      const acceptedForDomain: string[] = [];
-
       for (const mx of mxHosts) {
         if (recipientsForMx.length === 0) break;
         const startedAt = new Date();

package/ts/mail/delivery/index.ts

@@ -1,4 +1,5 @@
 // Email delivery components
+export * from './interfaces.js';
 export * from './classes.delivery.queue.js';
 export * from './classes.delivery.system.js';
 export { DeliveryStatus } from './classes.delivery.system.js';

package/ts/mail/index.ts

@@ -2,6 +2,7 @@
 export * from './interfaces.storage.js';
 export * from './routing/index.js';
 export * from './security/index.js';
+export type { ISmtpTransactionAttempt } from './delivery/interfaces.js';
 
 // Make the core and delivery modules accessible
 import * as Core from './core/index.js';

package/ts/mail/routing/classes.domain.registry.ts

@@ -1,5 +1,6 @@
 import type { IEmailDomainConfig } from './interfaces.js';
 import { logger } from '../../logger.js';
+import { assertValidInboundPolicy } from './functions.routing.validation.js';
 
 /**
  * Registry for email domain configurations
@@ -30,6 +31,9 @@ export class DomainRegistry {
     
     // Process and store domain configurations
     for (const config of domainConfigs) {
+      if (config.inboundPolicy) {
+        assertValidInboundPolicy(config.inboundPolicy, config.domain);
+      }
       const processedConfig = this.applyDefaults(config);
       this.domains.set(config.domain.toLowerCase(), processedConfig);
       logger.log('info', `Registered domain: ${config.domain} with DNS mode: ${processedConfig.dnsMode}`);

package/ts/mail/routing/classes.email.action.executor.ts

@@ -72,6 +72,10 @@ export class EmailActionExecutor {
       case 'deliver':
         await this.handleDeliverAction(action, email, context);
         break;
+      case 'store':
+        throw new Error(
+          'Store actions require raw SMTP context and an awaited hooks.onAcceptEnvelope handler',
+        );
       case 'reject':
         await this.handleRejectAction(action, email, context);
         break;

package/ts/mail/routing/classes.email.router.ts

@@ -4,6 +4,7 @@ import type { IStorageManager } from '../interfaces.storage.js';
 import type { IEmailRoute, IEmailMatch, IEmailAction, IEmailContext } from './interfaces.js';
 import type { Email } from '../core/classes.email.js';
 import { getErrorMessage } from '../../functions.errors.js';
+import { assertValidRetentionDays } from './functions.routing.validation.js';
 
 /**
  * Email router that evaluates routes and determines actions
@@ -25,6 +26,7 @@ export class EmailRouter extends EventEmitter {
     persistChanges?: boolean;
   }) {
     super();
+    this.validateRoutes(routes);
     this.routes = this.sortRoutesByPriority(routes);
     this.storageManager = options?.storageManager;
     this.persistChanges = options?.persistChanges ?? !!this.storageManager;
@@ -41,6 +43,32 @@ export class EmailRouter extends EventEmitter {
   public async initialize(): Promise<void> {
     await this.initializationPromise;
   }
+
+  private validateRoute(route: IEmailRoute): void {
+    if (!route?.name || !route.match || !route.action) {
+      throw new Error('Invalid route: missing required fields');
+    }
+
+    if (route.action.type !== 'store') {
+      return;
+    }
+    if (!route.action.store) {
+      throw new Error(`Store route ${route.name} requires store configuration`);
+    }
+    assertValidRetentionDays(
+      route.action.store.retentionDays,
+      `Store route ${route.name}`,
+    );
+  }
+
+  private validateRoutes(routes: IEmailRoute[]): void {
+    if (!Array.isArray(routes)) {
+      throw new Error('Invalid routes: expected an array');
+    }
+    for (const route of routes) {
+      this.validateRoute(route);
+    }
+  }
   
   /**
    * Sort routes by priority (higher priority first)
@@ -69,6 +97,7 @@ export class EmailRouter extends EventEmitter {
    * @param persist Whether to persist changes (defaults to persistChanges setting)
    */
   public async updateRoutes(routes: IEmailRoute[], persist?: boolean): Promise<void> {
+    this.validateRoutes(routes);
     this.routes = this.sortRoutesByPriority(routes);
     this.clearCache();
     this.emit('routesUpdated', this.routes);
@@ -409,11 +438,7 @@ export class EmailRouter extends EventEmitter {
     
     try {
       // Validate all routes before saving
-      for (const route of this.routes) {
-        if (!route.name || !route.match || !route.action) {
-          throw new Error(`Invalid route: ${JSON.stringify(route)}`);
-        }
-      }
+      this.validateRoutes(this.routes);
       
       const routesData = JSON.stringify(this.routes, null, 2);
       await this.storageManager.set('/email/routes/config.json', routesData);
@@ -447,13 +472,7 @@ export class EmailRouter extends EventEmitter {
       
       const loadedRoutes = JSON.parse(routesData) as IEmailRoute[];
       
-      // Validate loaded routes
-      for (const route of loadedRoutes) {
-        if (!route.name || !route.match || !route.action) {
-          console.warn(`Skipping invalid route: ${JSON.stringify(route)}`);
-          continue;
-        }
-      }
+      this.validateRoutes(loadedRoutes);
       
       if (options?.replace) {
         // Replace all routes
@@ -491,10 +510,7 @@ export class EmailRouter extends EventEmitter {
    * @param persist Whether to persist changes
    */
   public async addRoute(route: IEmailRoute, persist?: boolean): Promise<void> {
-    // Validate route
-    if (!route.name || !route.match || !route.action) {
-      throw new Error('Invalid route: missing required fields');
-    }
+    this.validateRoute(route);
     
     // Check if route already exists
     const existingIndex = this.routes.findIndex(r => r.name === route.name);
@@ -547,10 +563,7 @@ export class EmailRouter extends EventEmitter {
    * @param persist Whether to persist changes
    */
   public async updateRoute(name: string, route: IEmailRoute, persist?: boolean): Promise<void> {
-    // Validate route
-    if (!route.name || !route.match || !route.action) {
-      throw new Error('Invalid route: missing required fields');
-    }
+    this.validateRoute(route);
     
     const index = this.routes.findIndex(r => r.name === name);