@push.rocks/smartmta 7.0.0 → 8.0.1

package/ts/index.ts

@@ -5,4 +5,7 @@ export { baseLogger, logger } from './logger.js';
 
 export const smartMtaCapabilities = Object.freeze({
   selectorCorrectDkimSigning: true,
+  callerManagedDkimKeys: true,
+  structuredSmtpTransactions: true,
+  typedDeliveryFailures: true,
 } as const);

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

@@ -5,6 +5,8 @@ import { SecurityLogger, SecurityLogLevel, SecurityEventType } from '../../secur
 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
@@ -42,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,6 +116,12 @@ export class BounceManager {
   }> = new Map();
   
   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>;
@@ -132,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(() => {
@@ -148,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
@@ -156,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,
@@ -214,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(
@@ -233,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,
@@ -248,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;
@@ -271,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],
@@ -286,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
@@ -379,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;
     }
   }
@@ -389,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}`, {
@@ -411,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
@@ -423,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
@@ -451,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 => {
@@ -671,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;
     }
     
@@ -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 [];
     }
   }