@push.rocks/smartmta 7.0.0 → 8.0.1

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

@@ -1,6 +1,7 @@
 import * as plugins from '../../plugins.js';
 import { EventEmitter } from 'events';
 import { logger } from '../../logger.js';
+import { getErrorMessage } from '../../functions.errors.js';
 import {
   SecurityLogger,
   SecurityLogLevel,
@@ -24,6 +25,7 @@ import { SmtpState } from '../delivery/interfaces.js';
 import type { EmailProcessingMode, ISmtpSession as IBaseSmtpSession } from '../delivery/interfaces.js';
 import { EmailActionExecutor } from './classes.email.action.executor.js';
 import { DkimManager } from './classes.dkim.manager.js';
+import { callObserverSafely, emitSafely } from '../delivery/functions.safe-observers.js';
 
 
 /** External DcRouter interface shape used by UnifiedEmailServer */
@@ -104,6 +106,8 @@ export interface IUnifiedEmailServerOptions {
   domains: IEmailDomainConfig[];  // Domain configurations
   banner?: string;
   debug?: boolean;
+  /** Automatic for standalone use; caller-managed keeps DNS/key ownership with the embedding app. */
+  dkimKeyProvisioning?: 'automatic' | 'caller-managed';
   useSocketHandler?: boolean;  // Use socket-handler mode instead of port listening
   /** Persist router changes back into storage when a storage manager is available. */
   persistRoutes?: boolean;
@@ -329,7 +333,16 @@ export class UnifiedEmailServer extends EventEmitter {
       concurrentDeliveries: 10,
       processBounces: true,
       bounceHandler: {
-        processSmtpFailure: this.processSmtpFailure.bind(this)
+        processSmtpFailure: async (recipient, smtpResponse, failureOptions) => {
+          const processed = await this.processSmtpFailure(
+            recipient,
+            smtpResponse,
+            failureOptions,
+          );
+          if (!processed) {
+            throw new Error(`SMTP bounce operation failed for ${recipient}`);
+          }
+        },
       },
       onDeliverySuccess: async (_item, _result) => {
         // Delivery success recorded via delivery system
@@ -346,8 +359,14 @@ export class UnifiedEmailServer extends EventEmitter {
     });
 
     // Initialize DKIM manager
-    this.dkimManager = new DkimManager(this.dkimCreator, this.domainRegistry, dcRouter, this.rustBridge);
-    this.dnsManager = new DnsManager(this.dcRouter);
+    this.dkimManager = new DkimManager(
+      this.dkimCreator,
+      this.domainRegistry,
+      dcRouter,
+      this.rustBridge,
+      options.dkimKeyProvisioning || 'automatic',
+    );
+    this.dnsManager = new DnsManager(this.dcRouter, undefined, options.dkimKeyProvisioning || 'automatic');
 
     // Initialize statistics
     this.stats = {
@@ -406,18 +425,24 @@ export class UnifiedEmailServer extends EventEmitter {
     tlsOpportunistic?: boolean;
   }): Promise<ISmtpSendResult> {
     // Build DKIM config if domain has keys
-    let dkim: { domain: string; selector: string; privateKey: string } | undefined;
+    let dkim: {
+      domain: string;
+      selector: string;
+      privateKey: string;
+      keyType: 'rsa' | 'ed25519';
+    } | undefined;
     if (options?.dkimDomain) {
-      try {
-        const selector = options.dkimSelector || 'default';
-        const { privateKey } = await this.dkimCreator.readDKIMKeysForSelector(
-          options.dkimDomain,
-          selector,
-        );
-        dkim = { domain: options.dkimDomain, selector, privateKey };
-      } catch (err) {
-        logger.log('warn', `Failed to read DKIM keys for ${options.dkimDomain}: ${(err as Error).message}`);
-      }
+      const selector = options.dkimSelector || 'default';
+      const material = await this.dkimCreator.readValidatedDKIMKeysForSelector(
+        options.dkimDomain,
+        selector,
+      );
+      dkim = {
+        domain: options.dkimDomain,
+        selector,
+        privateKey: material.privateKey,
+        keyType: material.keyType,
+      };
     }
 
     // Serialize the Email to the outbound format
@@ -476,13 +501,14 @@ export class UnifiedEmailServer extends EventEmitter {
       await this.startDeliveryPipeline();
       await this.startRustBridge();
       await this.initializeDkimAndDns();
+      await this.startDeliveryProcessing();
       this.registerBridgeEventHandlers();
       await this.startSmtpServer();
       this.startDnsValidation();
       logger.log('info', 'UnifiedEmailServer started successfully');
-      this.emit('started');
+      await emitSafely(this, 'started');
     } catch (error) {
-      logger.log('error', `Failed to start UnifiedEmailServer: ${error.message}`);
+      logger.log('error', `Failed to start UnifiedEmailServer: ${getErrorMessage(error)}`);
       try {
         await this.stop();
       } catch (cleanupError) {
@@ -493,10 +519,19 @@ export class UnifiedEmailServer extends EventEmitter {
   }
 
   private async startDeliveryPipeline(): Promise<void> {
-    await this.deliveryQueue.initialize();
+    await Promise.all([
+      this.bounceManager.initialize(),
+      this.emailRouter.initialize(),
+    ]);
+    logger.log('info', 'Managed email routing and suppression state initialized');
+
+    await this.deliveryQueue.initialize({ startProcessing: false });
     logger.log('info', 'Email delivery queue initialized');
+  }
 
+  private async startDeliveryProcessing(): Promise<void> {
     await this.deliverySystem.start();
+    this.deliveryQueue.resume();
     logger.log('info', 'Email delivery system started');
   }
 
@@ -509,9 +544,9 @@ export class UnifiedEmailServer extends EventEmitter {
 
     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');
+      if (newState === 'failed') void emitSafely(this, 'bridgeFailed');
+      else if (newState === 'restarting') void emitSafely(this, 'bridgeRestarting');
+      else if (newState === 'running' && oldState === 'restarting') void emitSafely(this, 'bridgeRecovered');
     };
     this.rustBridge.on('stateChange', this.bridgeStateChangeHandler);
   }
@@ -520,6 +555,15 @@ export class UnifiedEmailServer extends EventEmitter {
     await this.dkimManager.setupDkimForDomains();
     logger.log('info', 'DKIM configuration completed for all domains');
 
+    if (this.options.dkimKeyProvisioning === 'caller-managed') {
+      // Caller-managed mode validates only exact-selector key material. SmartMTA
+      // must not register DNS handlers, generate DNS records, rotate keys, or
+      // mutate any /email/dns/* or /email/dkim/* managed state.
+      this.applyDomainRateLimits();
+      logger.log('info', 'Caller-managed DKIM readiness validated without provisioning');
+      return;
+    }
+
     if (!this.localDnsProvisioned) {
       await this.dnsManager.provisionLocalDnsRecords(
         this.domainRegistry.getAllConfigs(),
@@ -767,9 +811,9 @@ export class UnifiedEmailServer extends EventEmitter {
       }
 
       logger.log('info', 'UnifiedEmailServer stopped successfully');
-      this.emit('stopped');
+      await emitSafely(this, 'stopped');
     } catch (error) {
-      logger.log('error', `Error stopping UnifiedEmailServer: ${error.message}`);
+      logger.log('error', `Error stopping UnifiedEmailServer: ${getErrorMessage(error)}`);
       throw error;
     }
   }
@@ -1567,18 +1611,12 @@ export class UnifiedEmailServer extends EventEmitter {
         }
       }
 
-      // Sign with DKIM if configured
-      if (mode === 'mta' && route?.action.options?.mtaOptions?.dkimSign) {
-        const domain = email.from.split('@')[1];
-        await this.dkimManager.handleDkimSigning(email, domain, route.action.options.mtaOptions.dkimOptions?.keySelector || 'default');
-      }
-
       const id = await this.deliveryQueue.enqueue(email, mode, route);
 
       logger.log('info', `Email queued with ID: ${id}`);
       return id;
     } catch (error) {
-      logger.log('error', `Failed to send email: ${error.message}`);
+      logger.log('error', `Failed to send email: ${getErrorMessage(error)}`);
       throw error;
     }
   }
@@ -1599,9 +1637,9 @@ export class UnifiedEmailServer extends EventEmitter {
           bounceCategory: bounceRecord.bounceCategory
         });
 
-        this.emit('bounceProcessed', bounceRecord);
+        await emitSafely(this, 'bounceProcessed', bounceRecord);
 
-        SecurityLogger.getInstance().logEvent({
+        await callObserverSafely('bounce security log', () => SecurityLogger.getInstance().logEvent({
           level: SecurityLogLevel.INFO,
           type: SecurityEventType.EMAIL_VALIDATION,
           message: `Bounce notification processed for recipient`,
@@ -1612,7 +1650,7 @@ export class UnifiedEmailServer extends EventEmitter {
             bounceCategory: bounceRecord.bounceCategory
           },
           success: true
-        });
+        }));
 
         return true;
       } else {
@@ -1620,15 +1658,16 @@ export class UnifiedEmailServer extends EventEmitter {
         return false;
       }
     } catch (error) {
-      logger.log('error', `Error processing bounce notification: ${error.message}`);
+      const errorMessage = getErrorMessage(error);
+      logger.log('error', `Error processing bounce notification: ${errorMessage}`);
 
-      SecurityLogger.getInstance().logEvent({
+      await callObserverSafely('bounce failure security log', () => SecurityLogger.getInstance().logEvent({
         level: SecurityLogLevel.ERROR,
         type: SecurityEventType.EMAIL_VALIDATION,
         message: 'Failed to process bounce notification',
-        details: { error: error.message, subject: bounceEmail.subject },
+        details: { error: errorMessage, subject: bounceEmail.subject },
         success: false
-      });
+      }));
 
       return false;
     }
@@ -1637,7 +1676,13 @@ export class UnifiedEmailServer extends EventEmitter {
   public async processSmtpFailure(
     recipient: string,
     smtpResponse: string,
-    options: { sender?: string; originalEmailId?: string; statusCode?: string; headers?: Record<string, string> } = {}
+    options: {
+      operationId?: string;
+      sender?: string;
+      originalEmailId?: string;
+      statusCode?: string;
+      headers?: Record<string, string>;
+    } = {}
   ): Promise<boolean> {
     logger.log('info', `Processing SMTP failure for ${recipient}: ${smtpResponse}`);
 
@@ -1648,9 +1693,9 @@ export class UnifiedEmailServer extends EventEmitter {
         bounceType: bounceRecord.bounceType
       });
 
-      this.emit('bounceProcessed', bounceRecord);
+      await emitSafely(this, 'bounceProcessed', bounceRecord);
 
-      SecurityLogger.getInstance().logEvent({
+      await callObserverSafely('SMTP failure security log', () => SecurityLogger.getInstance().logEvent({
         level: SecurityLogLevel.INFO,
         type: SecurityEventType.EMAIL_VALIDATION,
         message: `SMTP failure processed for recipient`,
@@ -1662,19 +1707,20 @@ export class UnifiedEmailServer extends EventEmitter {
           smtpResponse
         },
         success: true
-      });
+      }));
 
       return true;
     } catch (error) {
-      logger.log('error', `Error processing SMTP failure: ${error.message}`);
+      const errorMessage = getErrorMessage(error);
+      logger.log('error', `Error processing SMTP failure: ${errorMessage}`);
 
-      SecurityLogger.getInstance().logEvent({
+      await callObserverSafely('SMTP failure security log', () => SecurityLogger.getInstance().logEvent({
         level: SecurityLogLevel.ERROR,
         type: SecurityEventType.EMAIL_VALIDATION,
         message: 'Failed to process SMTP failure',
-        details: { recipient, smtpResponse, error: error.message },
+        details: { recipient, smtpResponse, error: errorMessage },
         success: false
-      });
+      }));
 
       return false;
     }

package/ts/mail/security/classes.dkimcreator.ts

@@ -14,6 +14,14 @@ export interface IDkimKeyMetadata {
   keySize: number;
 }
 
+export type TDkimKeyType = 'rsa' | 'ed25519';
+
+export interface IDkimSigningMaterial {
+  privateKey: string;
+  publicKey: string;
+  keyType: TDkimKeyType;
+}
+
 export class DKIMCreator {
   constructor(private readonly storageManager: IStorageManager) {}
 
@@ -86,6 +94,44 @@ export class DKIMCreator {
     return { privateKey, publicKey };
   }
 
+  public async readValidatedDKIMKeysForSelector(
+    domain: string,
+    selector: string,
+  ): Promise<IDkimSigningMaterial> {
+    const keys = await this.readDKIMKeysForSelector(domain, selector);
+    let privateKeyObject: plugins.crypto.KeyObject;
+    let publicKeyObject: plugins.crypto.KeyObject;
+    try {
+      privateKeyObject = plugins.crypto.createPrivateKey(keys.privateKey);
+      publicKeyObject = plugins.crypto.createPublicKey(keys.publicKey);
+    } catch (error) {
+      throw new Error(
+        `Invalid DKIM key material for domain ${domain} with selector ${selector}: ${(error as Error).message}`,
+      );
+    }
+
+    const keyType = privateKeyObject.asymmetricKeyType;
+    if (keyType !== 'rsa' && keyType !== 'ed25519') {
+      throw new Error(
+        `Unsupported DKIM key type for domain ${domain} with selector ${selector}: ${keyType || 'unknown'}`,
+      );
+    }
+    if (publicKeyObject.asymmetricKeyType !== keyType) {
+      throw new Error(`DKIM public/private key type mismatch for domain ${domain} with selector ${selector}`);
+    }
+
+    const derivedPublicKey = plugins.crypto.createPublicKey(keys.privateKey).export({
+      type: 'spki',
+      format: 'der',
+    }) as Buffer;
+    const suppliedPublicKey = publicKeyObject.export({ type: 'spki', format: 'der' }) as Buffer;
+    if (!derivedPublicKey.equals(suppliedPublicKey)) {
+      throw new Error(`DKIM public/private key mismatch for domain ${domain} with selector ${selector}`);
+    }
+
+    return { ...keys, keyType };
+  }
+
   public async createDKIMKeys(
     keySize = 2048,
   ): Promise<{ privateKey: string; publicKey: string }> {
@@ -186,20 +232,17 @@ export class DKIMCreator {
     domain: string,
     selector: string,
   ): Promise<plugins.tsclass.network.IDnsRecord> {
-    const keys = await this.readDKIMKeysForSelector(domain, selector);
-    const keyContents = keys.publicKey
+    const material = await this.readValidatedDKIMKeysForSelector(domain, selector);
+    const keyContents = material.publicKey
       .replace('-----BEGIN PUBLIC KEY-----', '')
       .replace('-----END PUBLIC KEY-----', '')
       .replace(/\s/g, '');
-    const keyAlgo = keys.privateKey.includes('ED25519') || keys.publicKey.length < 200
-      ? 'ed25519'
-      : 'rsa';
 
     return {
       name: `${selector}._domainkey.${domain}`,
       type: 'TXT',
-      dnsSecEnabled: null,
-      value: `v=DKIM1; h=sha256; k=${keyAlgo}; p=${keyContents}`,
+      dnsSecEnabled: false,
+      value: `v=DKIM1; h=sha256; k=${material.keyType}; p=${keyContents}`,
     };
   }
 

package/ts/mail/security/classes.spfverifier.ts

@@ -1,4 +1,5 @@
 import { logger } from '../../logger.js';
+import { getErrorMessage } from '../../functions.errors.js';
 
 /**
  * SPF result qualifiers
@@ -116,9 +117,10 @@ export class SpfVerifier {
 
       return spfRecord;
     } catch (error) {
-      logger.log('error', `Error parsing SPF record: ${error.message}`, {
+      const errorMessage = getErrorMessage(error);
+      logger.log('error', `Error parsing SPF record: ${errorMessage}`, {
         record,
-        error: error.message
+        error: errorMessage
       });
       return null;
     }

package/ts/security/classes.contentscanner.ts

@@ -5,6 +5,8 @@ import type { IAttachment } from '../mail/core/classes.email.js';
 import { SecurityLogger, SecurityLogLevel, SecurityEventType } from './classes.securitylogger.js';
 import { RustSecurityBridge } from './classes.rustsecuritybridge.js';
 import { LRUCache } from 'lru-cache';
+import { getErrorMessage, getErrorStack } from '../functions.errors.js';
+import { callObserverSafely } from '../mail/delivery/functions.safe-observers.js';
 
 /**
  * Scan result information
@@ -179,9 +181,10 @@ export class ContentScanner {
 
       return result;
     } catch (error) {
-      logger.log('error', `Error scanning email: ${error.message}`, {
+      const errorMessage = getErrorMessage(error);
+      logger.log('error', `Error scanning email: ${errorMessage}`, {
         messageId: email.getMessageId(),
-        error: error.stack
+        error: getErrorStack(error)
       });
 
       // Return a safe default with error indication
@@ -191,7 +194,7 @@ export class ContentScanner {
         scannedElements: ['error'],
         timestamp: Date.now(),
         threatType: 'scan_error',
-        threatDetails: `Scan error: ${error.message}`
+        threatDetails: `Scan error: ${errorMessage}`
       };
     }
   }
@@ -300,7 +303,7 @@ export class ContentScanner {
         .replace(/[\x00-\x09\x0B-\x1F\x7F-\x9F]/g, '') // Remove control chars
         .replace(/\uFFFD/g, ''); // Remove replacement char
     } catch (error) {
-      logger.log('warn', `Error extracting text from buffer: ${error.message}`);
+      logger.log('warn', `Error extracting text from buffer: ${getErrorMessage(error)}`);
       return '';
     }
   }
@@ -340,7 +343,7 @@ export class ContentScanner {
    * @param result The scan result
    */
   private logHighThreatFound(email: Email, result: IScanResult): void {
-    SecurityLogger.getInstance().logEvent({
+    void callObserverSafely('content scan security log', () => SecurityLogger.getInstance().logEvent({
       level: SecurityLogLevel.ERROR,
       type: SecurityEventType.MALWARE,
       message: `High threat content detected in email from ${email.from} to ${email.to.join(', ')}`,
@@ -353,8 +356,8 @@ export class ContentScanner {
         subject: email.subject
       },
       success: false,
-      domain: email.getFromDomain()
-    });
+      domain: email.getFromDomain() || undefined
+    }));
   }
   
   /**
@@ -363,7 +366,7 @@ export class ContentScanner {
    * @param result The scan result
    */
   private logThreatFound(email: Email, result: IScanResult): void {
-    SecurityLogger.getInstance().logEvent({
+    void callObserverSafely('content scan security log', () => SecurityLogger.getInstance().logEvent({
       level: SecurityLogLevel.WARN,
       type: SecurityEventType.SPAM,
       message: `Suspicious content detected in email from ${email.from} to ${email.to.join(', ')}`,
@@ -376,8 +379,8 @@ export class ContentScanner {
         subject: email.subject
       },
       success: false,
-      domain: email.getFromDomain()
-    });
+      domain: email.getFromDomain() || undefined
+    }));
   }
   
   /**
@@ -396,4 +399,4 @@ export class ContentScanner {
       return 'high';
     }
   }
-}
+}

package/ts/security/classes.ipreputationchecker.ts

@@ -1,8 +1,10 @@
 import { logger } from '../logger.js';
+import { getErrorMessage, getErrorStack } from '../functions.errors.js';
 import type { IStorageManager } from '../mail/interfaces.storage.js';
 import { SecurityLogger, SecurityLogLevel, SecurityEventType } from './classes.securitylogger.js';
 import { RustSecurityBridge } from './classes.rustsecuritybridge.js';
 import { LRUCache } from 'lru-cache';
+import { callObserverSafely } from '../mail/delivery/functions.safe-observers.js';
 
 /**
  * Reputation check result information
@@ -66,6 +68,7 @@ export class IPReputationChecker {
   private reputationCache: LRUCache<string, IReputationResult>;
   private options: Required<IIPReputationOptions>;
   private storageManager?: IStorageManager;
+  private initializationPromise: Promise<void>;
 
   private static readonly DEFAULT_OPTIONS: Required<IIPReputationOptions> = {
     maxCacheSize: 10000,
@@ -92,11 +95,16 @@ export class IPReputationChecker {
       ttl: this.options.cacheTTL,
     });
 
-    if (this.options.persistCache) {
-      this.loadCache().catch(error => {
-        logger.log('error', `Failed to load IP reputation cache during initialization: ${error.message}`);
-      });
-    }
+    const hydrationPromise = this.options.persistCache
+      ? this.loadCache()
+      : Promise.resolve();
+    hydrationPromise.catch(() => undefined);
+    this.initializationPromise = hydrationPromise;
+  }
+
+  /** Wait until the managed reputation cache has been hydrated. */
+  public async initialize(): Promise<void> {
+    await this.initializationPromise;
   }
 
   public static getInstance(options: IIPReputationOptions = {}, storageManager?: IStorageManager): IPReputationChecker {
@@ -111,6 +119,8 @@ export class IPReputationChecker {
    */
   public async checkReputation(ip: string): Promise<IReputationResult> {
     try {
+      await this.initialize();
+
       if (!this.isValidIPAddress(ip)) {
         logger.log('warn', `Invalid IP address format: ${ip}`);
         return this.createErrorResult(ip, 'Invalid IP address format');
@@ -153,11 +163,12 @@ export class IPReputationChecker {
       this.logReputationCheck(ip, result);
       return result;
     } catch (error) {
-      logger.log('error', `Error checking IP reputation for ${ip}: ${error.message}`, {
+      const errorMessage = getErrorMessage(error);
+      logger.log('error', `Error checking IP reputation for ${ip}: ${errorMessage}`, {
         ip,
-        stack: error.stack
+        stack: getErrorStack(error)
       });
-      const errorResult = this.createErrorResult(ip, error.message);
+      const errorResult = this.createErrorResult(ip, errorMessage);
       // Cache error results to avoid repeated failing lookups
       this.reputationCache.set(ip, errorResult);
       return errorResult;
@@ -187,7 +198,7 @@ export class IPReputationChecker {
       logLevel = SecurityLogLevel.WARN;
     }
 
-    SecurityLogger.getInstance().logEvent({
+    void callObserverSafely('IP reputation security log', () => SecurityLogger.getInstance().logEvent({
       level: logLevel,
       type: SecurityEventType.IP_REPUTATION,
       message: `IP reputation check ${result.isSpam ? 'flagged spam' : 'completed'} for ${ip}`,
@@ -202,7 +213,7 @@ export class IPReputationChecker {
         blacklists: result.blacklists
       },
       success: !result.isSpam
-    });
+    }));
   }
 
   private async saveCache(): Promise<void> {