@push.rocks/smartmta 6.5.2 → 8.0.0

package/ts/mail/core/classes.bouncemanager.ts

@@ -1,11 +1,12 @@
 import * as plugins from '../../plugins.js';
-import * as paths from '../../paths.js';
 import { logger } from '../../logger.js';
-import { hasStorageManagerMethods, type IStorageManagerLike } from '../interfaces.storage.js';
+import type { IStorageManager } from '../interfaces.storage.js';
 import { SecurityLogger, SecurityLogLevel, SecurityEventType } from '../../security/index.js';
 import { RustSecurityBridge } from '../../security/classes.rustsecuritybridge.js';
 import { LRUCache } from 'lru-cache';
 import type { Email } from './classes.email.js';
+import { callObserverSafely } from '../delivery/functions.safe-observers.js';
+import { getErrorMessage } from '../../functions.errors.js';
 
 /**
  * Bounce types for categorizing the reasons for bounces
@@ -43,11 +44,17 @@ export enum BounceCategory {
   UNKNOWN = 'unknown'
 }
 
+// This cache only accelerates hot duplicate checks. Durable correctness always
+// comes from re-reading the processed marker by deterministic operation ID.
+const COMPLETED_OPERATION_CACHE_MAX = 10_000;
+const COMPLETED_OPERATION_CACHE_TTL = 24 * 60 * 60 * 1000;
+
 /**
  * Bounce data structure
  */
 export interface BounceRecord {
   id: string;
+  operationId?: string;
   originalEmailId?: string;
   recipient: string;
   sender: string;
@@ -108,13 +115,19 @@ export class BounceManager {
     expiresAt?: number; // undefined means permanent
   }> = new Map();
   
-  private storageManager?: IStorageManagerLike;
+  private storageManager?: IStorageManager;
+  private initializationPromise: Promise<void>;
+  private operationPromises = new Map<string, Promise<BounceRecord>>();
+  private completedOperations = new LRUCache<string, BounceRecord>({
+    max: COMPLETED_OPERATION_CACHE_MAX,
+    ttl: COMPLETED_OPERATION_CACHE_TTL,
+  });
   
   constructor(options?: {
     retryStrategy?: Partial<RetryStrategy>;
     maxCacheSize?: number;
     cacheTTL?: number;
-      storageManager?: IStorageManagerLike;
+      storageManager?: IStorageManager;
   }) {
     // Set retry strategy with defaults
     if (options?.retryStrategy) {
@@ -133,12 +146,11 @@ export class BounceManager {
     // Store storage manager reference
     this.storageManager = options?.storageManager;
     
-    // Load suppression list from storage
-    // Note: This is async but we can't await in constructor
-    // The suppression list will be loaded asynchronously
-    this.loadSuppressionList().catch(error => {
-      logger.log('error', `Failed to load suppression list on startup: ${error.message}`);
-    });
+    // Capture hydration so server startup can establish a real readiness barrier.
+    // A handled mirror prevents an unhandled rejection before initialize() is awaited.
+    const hydrationPromise = this.loadSuppressionList();
+    hydrationPromise.catch(() => undefined);
+    this.initializationPromise = hydrationPromise;
 
     // Start periodic cleanup of old bounce records (every 1 hour, removes records older than 7 days)
     this.cleanupInterval = setInterval(() => {
@@ -149,6 +161,11 @@ export class BounceManager {
       }
     }, 60 * 60 * 1000);
   }
+
+  /** Wait until the managed suppression state has been hydrated. */
+  public async initialize(): Promise<void> {
+    await this.initializationPromise;
+  }
   
   /**
    * Process a bounce notification
@@ -157,12 +174,19 @@ export class BounceManager {
    */
   public async processBounce(bounceData: Partial<BounceRecord>): Promise<BounceRecord> {
     try {
+      const recipient = bounceData.recipient?.trim();
+      if (!recipient) throw new Error('Bounce recipient is required');
+      const sender = bounceData.sender || '';
+      const domain = bounceData.domain || recipient.split('@')[1];
+      if (!domain) throw new Error('Bounce recipient domain is required');
+
       // Add required fields if missing
       const bounce: BounceRecord = {
         id: bounceData.id || plugins.uuid.v4(),
-        recipient: bounceData.recipient,
-        sender: bounceData.sender,
-        domain: bounceData.domain || bounceData.recipient.split('@')[1],
+        ...(bounceData.operationId ? { operationId: bounceData.operationId } : {}),
+        recipient,
+        sender,
+        domain,
         subject: bounceData.subject,
         bounceType: bounceData.bounceType || BounceType.UNKNOWN,
         bounceCategory: bounceData.bounceCategory || BounceCategory.UNKNOWN,
@@ -215,12 +239,17 @@ export class BounceManager {
           break;
       }
       
-      // Store the bounce record
+      // Persist every side effect before this deterministic record becomes
+      // the operation's completion checkpoint.
       bounce.processed = true;
-      this.bounceStore.push(bounce);
-      
-      // Update the bounce cache
-      this.updateBounceCache(bounce);
+      await this.saveBounceRecord(bounce);
+      if (!this.bounceStore.some((stored) => stored.id === bounce.id)) {
+        this.bounceStore.push(bounce);
+        this.updateBounceCache(bounce);
+      }
+      if (bounce.operationId) {
+        this.completedOperations.set(bounce.operationId, bounce);
+      }
       
       // Log the bounce
       logger.log(
@@ -234,7 +263,7 @@ export class BounceManager {
       );
       
       // Enhanced security logging
-      SecurityLogger.getInstance().logEvent({
+      await callObserverSafely('bounce security log', () => SecurityLogger.getInstance().logEvent({
         level: bounce.bounceCategory === BounceCategory.HARD 
           ? SecurityLogLevel.WARN 
           : SecurityLogLevel.INFO,
@@ -249,12 +278,13 @@ export class BounceManager {
           statusCode: bounce.statusCode
         },
         success: false
-      });
-      
+      }));
+
       return bounce;
     } catch (error) {
-      logger.log('error', `Error processing bounce: ${error.message}`, {
-        error: error.message,
+      const errorMessage = getErrorMessage(error);
+      logger.log('error', `Error processing bounce: ${errorMessage}`, {
+        error: errorMessage,
         bounceData
       });
       throw error;
@@ -272,14 +302,66 @@ export class BounceManager {
     recipient: string,
     smtpResponse: string,
     options: {
+      operationId?: string;
       sender?: string;
       originalEmailId?: string;
       statusCode?: string;
       headers?: Record<string, string>;
     } = {}
   ): Promise<BounceRecord> {
-    // Create bounce data from SMTP failure
-    const bounceData: Partial<BounceRecord> = {
+    const operationId = options.operationId;
+    if (!operationId) {
+      return this.processBounce({
+        recipient,
+        sender: options.sender || '',
+        domain: recipient.split('@')[1],
+        smtpResponse,
+        statusCode: options.statusCode,
+        headers: options.headers,
+        originalEmailId: options.originalEmailId,
+        timestamp: Date.now(),
+      });
+    }
+
+    const completed = this.completedOperations.get(operationId);
+    if (completed) return completed;
+    const active = this.operationPromises.get(operationId);
+    if (active) return active;
+
+    const operation = this.processSmtpFailureOperation(
+      operationId,
+      recipient,
+      smtpResponse,
+      options,
+    );
+    this.operationPromises.set(operationId, operation);
+    try {
+      return await operation;
+    } finally {
+      this.operationPromises.delete(operationId);
+    }
+  }
+
+  private async processSmtpFailureOperation(
+    operationId: string,
+    recipient: string,
+    smtpResponse: string,
+    options: {
+      sender?: string;
+      originalEmailId?: string;
+      statusCode?: string;
+      headers?: Record<string, string>;
+    },
+  ): Promise<BounceRecord> {
+    const stored = await this.readProcessedBounce(operationId);
+    if (stored) {
+      this.completedOperations.set(operationId, stored);
+      return stored;
+    }
+
+    return this.processBounce({
+      id: operationId,
+      operationId,
       recipient,
       sender: options.sender || '',
       domain: recipient.split('@')[1],
@@ -287,13 +369,23 @@ export class BounceManager {
       statusCode: options.statusCode,
       headers: options.headers,
       originalEmailId: options.originalEmailId,
-      timestamp: Date.now()
-    };
-    
-    // Process as a regular bounce
-    return this.processBounce(bounceData);
+      timestamp: Date.now(),
+    });
   }
-  
+
+  private async readProcessedBounce(operationId: string): Promise<BounceRecord | null> {
+    if (!this.storageManager) return null;
+    const serialized = await this.storageManager.get(
+      `/email/bounces/records/${operationId}.json`,
+    );
+    if (!serialized) return null;
+    const bounce = JSON.parse(serialized) as BounceRecord;
+    if (!bounce.processed || bounce.operationId !== operationId || bounce.id !== operationId) {
+      throw new Error(`Invalid processed bounce checkpoint for operation ${operationId}`);
+    }
+    return bounce;
+  }
+
   /**
    * Process a bounce notification email
    * @param bounceEmail The email containing bounce information
@@ -380,7 +472,7 @@ export class BounceManager {
       // Process as a regular bounce
       return this.processBounce(bounceData);
     } catch (error) {
-      logger.log('error', `Error processing bounce email: ${error.message}`);
+      logger.log('error', `Error processing bounce email: ${getErrorMessage(error)}`);
       return null;
     }
   }
@@ -390,14 +482,11 @@ export class BounceManager {
    * @param bounce The bounce record
    */
   private async handleHardBounce(bounce: BounceRecord): Promise<void> {
-    // Add to suppression list permanently (no expiry)
-    this.addToSuppressionList(bounce.recipient, `Hard bounce: ${bounce.bounceType}`, undefined);
-    
-    // Increment bounce count in cache
-    this.updateBounceCache(bounce);
-    
-    // Save to permanent storage
-    await this.saveBounceRecord(bounce);
+    await this.addToSuppressionListAndPersist(
+      bounce.recipient,
+      `Hard bounce: ${bounce.bounceType}`,
+      undefined,
+    );
     
     // Log hard bounce for monitoring
     logger.log('warn', `Hard bounce for ${bounce.recipient}: ${bounce.bounceType}`, {
@@ -412,8 +501,9 @@ export class BounceManager {
    * @param bounce The bounce record
    */
   private async handleSoftBounce(bounce: BounceRecord): Promise<void> {
+    const retryCount = bounce.retryCount ?? 0;
     // Check if we've exceeded max retries
-    if (bounce.retryCount >= this.retryStrategy.maxRetries) {
+    if (retryCount >= this.retryStrategy.maxRetries) {
       logger.log('warn', `Max retries exceeded for ${bounce.recipient}, treating as hard bounce`);
       
       // Convert to hard bounce after max retries
@@ -424,18 +514,17 @@ export class BounceManager {
     
     // Calculate next retry time with exponential backoff
     const delay = Math.min(
-      this.retryStrategy.initialDelay * Math.pow(this.retryStrategy.backoffFactor, bounce.retryCount),
+      this.retryStrategy.initialDelay * Math.pow(this.retryStrategy.backoffFactor, retryCount),
       this.retryStrategy.maxDelay
     );
     
-    bounce.retryCount++;
+    bounce.retryCount = retryCount + 1;
     bounce.nextRetryTime = Date.now() + delay;
     
-    // Add to suppression list temporarily (with expiry)
-    this.addToSuppressionList(
+    await this.addToSuppressionListAndPersist(
       bounce.recipient,
       `Soft bounce: ${bounce.bounceType}`,
-      bounce.nextRetryTime
+      bounce.nextRetryTime,
     );
     
     // Log the retry schedule
@@ -452,16 +541,37 @@ export class BounceManager {
    * @param reason Reason for suppression
    * @param expiresAt Expiration timestamp (undefined for permanent)
    */
-  public addToSuppressionList(
+  private setSuppressionListEntry(
     email: string,
     reason: string,
-    expiresAt?: number
+    expiresAt?: number,
   ): void {
     this.suppressionList.set(email.toLowerCase(), {
       reason,
       timestamp: Date.now(),
-      expiresAt
+      expiresAt,
     });
+  }
+
+  private async addToSuppressionListAndPersist(
+    email: string,
+    reason: string,
+    expiresAt?: number,
+  ): Promise<void> {
+    this.setSuppressionListEntry(email, reason, expiresAt);
+    await this.saveSuppressionList();
+    logger.log('info', `Added ${email} to suppression list`, {
+      reason,
+      expiresAt: expiresAt ? new Date(expiresAt).toISOString() : 'permanent',
+    });
+  }
+
+  public addToSuppressionList(
+    email: string,
+    reason: string,
+    expiresAt?: number
+  ): void {
+    this.setSuppressionListEntry(email, reason, expiresAt);
     
     // Save asynchronously without blocking
     this.saveSuppressionList().catch(error => {
@@ -546,120 +656,42 @@ export class BounceManager {
     return suppression;
   }
   
-  /**
-   * Save suppression list to disk
-   */
+  /** Save the suppression list through managed storage when durability is configured. */
   private async saveSuppressionList(): Promise<void> {
-    try {
-      const suppressionData = JSON.stringify(Array.from(this.suppressionList.entries()));
-      
-      if (hasStorageManagerMethods(this.storageManager, ['set'])) {
-        // Use storage manager
-        await this.storageManager.set('/email/bounces/suppression-list.json', suppressionData);
-      } else {
-        // Fall back to filesystem
-        await plugins.smartfs.file(
-          plugins.path.join(paths.dataDir, 'emails', 'suppression_list.json')
-        ).write(suppressionData);
-      }
-    } catch (error) {
-      logger.log('error', `Failed to save suppression list: ${error.message}`);
-    }
+    if (!this.storageManager) return;
+    const suppressionData = JSON.stringify(Array.from(this.suppressionList.entries()));
+    await this.storageManager.set('/email/bounces/suppression-list.json', suppressionData);
   }
-  
-  /**
-   * Load suppression list from disk
-   */
+
+  /** Load the suppression list from managed storage. */
   private async loadSuppressionList(): Promise<void> {
-    try {
-      let entries = null;
-      let needsMigration = false;
-      
-      if (hasStorageManagerMethods(this.storageManager, ['get'])) {
-        // Try to load from storage manager first
-        const suppressionData = await this.storageManager.get('/email/bounces/suppression-list.json');
-        
-        if (suppressionData) {
-          entries = JSON.parse(suppressionData);
-        } else {
-          // Check if data exists in filesystem and migrate
-          const suppressionPath = plugins.path.join(paths.dataDir, 'emails', 'suppression_list.json');
-          
-          if (plugins.fs.existsSync(suppressionPath)) {
-            const data = plugins.fs.readFileSync(suppressionPath, 'utf8');
-            entries = JSON.parse(data);
-            needsMigration = true;
-            
-            logger.log('info', 'Migrating suppression list from filesystem to StorageManager');
-          }
-        }
-      } else {
-        // No storage manager, use filesystem directly
-        const suppressionPath = plugins.path.join(paths.dataDir, 'emails', 'suppression_list.json');
-        
-        if (plugins.fs.existsSync(suppressionPath)) {
-          const data = plugins.fs.readFileSync(suppressionPath, 'utf8');
-          entries = JSON.parse(data);
-        }
-      }
-      
-      if (entries) {
-        this.suppressionList = new Map(entries);
-        
-        // Clean expired entries
-        const now = Date.now();
-        let expiredCount = 0;
-        
-        for (const [email, info] of this.suppressionList.entries()) {
-          if (info.expiresAt && now > info.expiresAt) {
-            this.suppressionList.delete(email);
-            expiredCount++;
-          }
-        }
-        
-        if (expiredCount > 0 || needsMigration) {
-          logger.log('info', `Cleaned ${expiredCount} expired entries from suppression list`);
-          await this.saveSuppressionList();
-        }
-        
-        logger.log('info', `Loaded ${this.suppressionList.size} entries from suppression list`);
+    if (!this.storageManager) return;
+    const suppressionData = await this.storageManager.get('/email/bounces/suppression-list.json');
+    if (!suppressionData) return;
+
+    const entries = JSON.parse(suppressionData);
+    this.suppressionList = new Map(entries);
+    const now = Date.now();
+    let expiredCount = 0;
+    for (const [email, info] of this.suppressionList.entries()) {
+      if (info.expiresAt && now > info.expiresAt) {
+        this.suppressionList.delete(email);
+        expiredCount++;
       }
-    } catch (error) {
-      logger.log('error', `Failed to load suppression list: ${error.message}`);
     }
+    if (expiredCount > 0) await this.saveSuppressionList();
+    logger.log('info', `Loaded ${this.suppressionList.size} suppression entries`);
   }
-  
-  /**
-   * Save bounce record to disk
-   * @param bounce Bounce record to save
-   */
-  private async saveBounceRecord(bounce: BounceRecord): Promise<void> {
-    try {
-      const bounceData = JSON.stringify(bounce, null, 2);
-      
-      if (hasStorageManagerMethods(this.storageManager, ['set'])) {
-        // Use storage manager
-        await this.storageManager.set(`/email/bounces/records/${bounce.id}.json`, bounceData);
-      } else {
-        // Fall back to filesystem
-        const bouncePath = plugins.path.join(
-          paths.dataDir,
-          'emails',
-          'bounces',
-          `${bounce.id}.json`
-        );
-        
-        // Ensure directory exists
-        const bounceDir = plugins.path.join(paths.dataDir, 'emails', 'bounces');
-        await plugins.smartfs.directory(bounceDir).recursive().create();
 
-        await plugins.smartfs.file(bouncePath).write(bounceData);
-      }
-    } catch (error) {
-      logger.log('error', `Failed to save bounce record: ${error.message}`);
-    }
+  /** Save one bounce record through managed storage when configured. */
+  private async saveBounceRecord(bounce: BounceRecord): Promise<void> {
+    if (!this.storageManager) return;
+    await this.storageManager.set(
+      `/email/bounces/records/${bounce.id}.json`,
+      JSON.stringify(bounce),
+    );
   }
-  
+
   /**
    * Update bounce cache with new bounce information
    * @param bounce Bounce record to update cache with
@@ -750,5 +782,6 @@ export class BounceManager {
       clearInterval(this.cleanupInterval);
       this.cleanupInterval = undefined;
     }
+    this.completedOperations.clear();
   }
 }

package/ts/mail/core/classes.email.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../../plugins.js';
-import { EmailValidator } from './classes.emailvalidator.js';
+import { EmailValidator, type IEmailValidationResult } from './classes.emailvalidator.js';
 
 export interface IAttachment {
   filename: string;
@@ -512,20 +512,25 @@ export class Email {
     recipients: Array<{ email: string; result: any }>;
     isValid: boolean;
   }> {
-    const result = {
+    const result: {
+      sender: { email: string; result: IEmailValidationResult | null };
+      recipients: Array<{ email: string; result: IEmailValidationResult }>;
+      isValid: boolean;
+    } = {
       sender: { email: this.from, result: null },
       recipients: [],
       isValid: true
     };
     
     // Validate sender
-    result.sender.result = await Email.emailValidator.validate(this.from, {
+    const senderResult = await Email.emailValidator.validate(this.from, {
       checkMx: options.checkMx !== false,
       checkDisposable: options.checkDisposable !== false
     });
+    result.sender.result = senderResult;
     
     // If sender fails validation, the whole email is considered invalid
-    if (!result.sender.result.isValid) {
+    if (!senderResult.isValid) {
       result.isValid = false;
     }
     
@@ -617,7 +622,7 @@ export class Email {
       const smartAttachment = new plugins.smartfile.SmartFile({
         path: attachment.filename,
         contentBuffer: attachment.content,
-        base: process.cwd(),
+        base: '.',
       });
       
       // Set content type if available
@@ -900,19 +905,20 @@ export class Email {
       return emails.filter(email => email && email.length > 0);
     };
     
-    // Convert TO recipients
-    if (smartmail.options.to?.length > 0) {
-      options.to = filterValidEmails(smartmail.options.to.map(extractEmail));
+    // Convert recipients from Smartmail's optional arrays.
+    const toRecipients = smartmail.options.to;
+    if (toRecipients && toRecipients.length > 0) {
+      options.to = filterValidEmails(toRecipients.map(extractEmail));
     }
     
-    // Convert CC recipients
-    if (smartmail.options.cc?.length > 0) {
-      options.cc = filterValidEmails(smartmail.options.cc.map(extractEmail));
+    const ccRecipients = smartmail.options.cc;
+    if (ccRecipients && ccRecipients.length > 0) {
+      options.cc = filterValidEmails(ccRecipients.map(extractEmail));
     }
     
-    // Convert BCC recipients
-    if (smartmail.options.bcc?.length > 0) {
-      options.bcc = filterValidEmails(smartmail.options.bcc.map(extractEmail));
+    const bccRecipients = smartmail.options.bcc;
+    if (bccRecipients && bccRecipients.length > 0) {
+      options.bcc = filterValidEmails(bccRecipients.map(extractEmail));
     }
     
     // Convert attachments (note: this handles the synchronous case only)

package/ts/mail/core/classes.emailvalidator.ts

@@ -1,18 +1,19 @@
 import * as plugins from '../../plugins.js';
 import { logger } from '../../logger.js';
 import { LRUCache } from 'lru-cache';
+import { getErrorMessage } from '../../functions.errors.js';
 
 export interface IEmailValidationResult {
   isValid: boolean;
   hasMx: boolean;
   hasSpamMarkings: boolean;
   score: number;
-  details?: {
-    formatValid?: boolean;
+  details: {
+    formatValid: boolean;
     mxRecords?: string[];
     disposable?: boolean;
     role?: boolean;
-    spamIndicators?: string[];
+    spamIndicators: string[];
     errorMessage?: string;
   };
 }
@@ -102,7 +103,7 @@ export class EmailValidator {
             result.details.errorMessage = 'Domain has no MX records';
           }
         } catch (error) {
-          logger.log('error', `Error checking MX records: ${error.message}`);
+          logger.log('error', `Error checking MX records: ${getErrorMessage(error)}`);
           result.details.errorMessage = 'Unable to check MX records';
         }
       }
@@ -160,7 +161,8 @@ export class EmailValidator {
       
       return result;
     } catch (error) {
-      logger.log('error', `Email validation error: ${error.message}`);
+      const errorMessage = getErrorMessage(error);
+      logger.log('error', `Email validation error: ${errorMessage}`);
       return {
         isValid: false,
         hasMx: false,
@@ -168,7 +170,7 @@ export class EmailValidator {
         score: 0,
         details: {
           formatValid: false,
-          errorMessage: `Validation error: ${error.message}`,
+          errorMessage: `Validation error: ${errorMessage}`,
           spamIndicators: ['Validation error']
         }
       };
@@ -198,7 +200,7 @@ export class EmailValidator {
       
       return records;
     } catch (error) {
-      logger.log('error', `Error fetching MX records for ${domain}: ${error.message}`);
+      logger.log('error', `Error fetching MX records for ${domain}: ${getErrorMessage(error)}`);
       return [];
     }
   }