@push.rocks/smartmta 7.0.0 → 8.0.0

package/ts/mail/delivery/classes.unified.rate.limiter.ts

@@ -2,6 +2,7 @@ import * as plugins from '../../plugins.js';
 import { EventEmitter } from 'node:events';
 import { logger } from '../../logger.js';
 import { SecurityLogger, SecurityLogLevel, SecurityEventType } from '../../security/index.js';
+import { callObserverSafely, emitSafely } from './functions.safe-observers.js';
 
 /**
  * Interface for rate limit configuration
@@ -759,7 +760,7 @@ export class UnifiedRateLimiter extends EventEmitter {
       
       logger.log('warn', `IP ${ip} blocked due to excessive errors (${counter.errors}/${limit})`);
       
-      SecurityLogger.getInstance().logEvent({
+      void callObserverSafely('rate-limit security log', () => SecurityLogger.getInstance().logEvent({
         level: SecurityLogLevel.WARN,
         type: SecurityEventType.RATE_LIMITING,
         message: 'IP blocked due to excessive errors',
@@ -769,7 +770,7 @@ export class UnifiedRateLimiter extends EventEmitter {
           limit
         },
         success: false
-      });
+      }));
       
       return true;
     }
@@ -840,7 +841,7 @@ export class UnifiedRateLimiter extends EventEmitter {
       
       logger.log('warn', `IP ${ip} blocked due to excessive authentication failures (${counter.authFailures}/${limit})`);
       
-      SecurityLogger.getInstance().logEvent({
+      void callObserverSafely('rate-limit security log', () => SecurityLogger.getInstance().logEvent({
         level: SecurityLogLevel.WARN,
         type: SecurityEventType.AUTHENTICATION,
         message: 'IP blocked due to excessive authentication failures',
@@ -850,7 +851,7 @@ export class UnifiedRateLimiter extends EventEmitter {
           limit
         },
         success: false
-      });
+      }));
       
       return true;
     }
@@ -888,7 +889,7 @@ export class UnifiedRateLimiter extends EventEmitter {
     this.stats.currentlyBlocked++;
     
     // Emit event
-    this.emit('ipBlocked', {
+    void emitSafely(this, 'ipBlocked', {
       ip,
       expiry,
       duration: duration || this.config.global.blockDuration
@@ -916,7 +917,7 @@ export class UnifiedRateLimiter extends EventEmitter {
     }
     
     // Emit event
-    this.emit('ipUnblocked', { ip });
+    void emitSafely(this, 'ipUnblocked', { ip });
     
     logger.log('info', `IP ${ip} unblocked`);
   }
@@ -977,7 +978,7 @@ export class UnifiedRateLimiter extends EventEmitter {
     this.stats.activeCounters = this.counters.size + this.patternCounters.size + this.ipCounters.size;
     
     // Emit statistics update
-    this.emit('statsUpdated', this.stats);
+    void emitSafely(this, 'statsUpdated', this.stats);
   }
   
   /**
@@ -1064,4 +1065,4 @@ export class UnifiedRateLimiter extends EventEmitter {
   public getDomainLimits(domain: string): IRateLimitConfig | undefined {
     return this.config.domains?.[domain];
   }
-}
+}

package/ts/mail/delivery/functions.safe-observers.ts

@@ -0,0 +1,45 @@
+import { EventEmitter } from 'node:events';
+
+import { logger } from '../../logger.js';
+import { getErrorMessage } from '../../functions.errors.js';
+
+function logObserverFailure(message: string): void {
+  try {
+    logger.log('error', message);
+  } catch {
+    // Logging is an observer too. It must not affect the primary operation.
+  }
+}
+
+/**
+ * Notify every EventEmitter observer without allowing observer failures to
+ * change the operation that produced the notification. rawListeners() keeps
+ * EventEmitter's once wrapper semantics intact when invoked with the emitter
+ * as its receiver.
+ */
+export async function emitSafely(
+  emitter: EventEmitter,
+  eventName: string | symbol,
+  ...args: unknown[]
+): Promise<void> {
+  for (const rawListener of emitter.rawListeners(eventName)) {
+    try {
+      await Reflect.apply(rawListener, emitter, args);
+    } catch (error) {
+      logObserverFailure(`Observer for ${String(eventName)} failed: ${getErrorMessage(error)}`);
+    }
+  }
+}
+
+/** Run a callback observer with the same failure isolation as emitter events. */
+export async function callObserverSafely(
+  observerName: string,
+  observer: (...args: any[]) => unknown,
+  ...args: unknown[]
+): Promise<void> {
+  try {
+    await observer(...args);
+  } catch (error) {
+    logObserverFailure(`${observerName} observer failed: ${getErrorMessage(error)}`);
+  }
+}

package/ts/mail/delivery/interfaces.ts

@@ -2,6 +2,33 @@
  * SMTP and email delivery interface definitions
  */
 
+import type {
+  ISmtpRecipientResult,
+  ISmtpTranscriptEntry,
+  TSmtpDeliveryPhase,
+} from '../../security/classes.rustsecuritybridge.js';
+
+export interface ISmtpTransactionAttempt {
+  id: string;
+  queueItemId: string;
+  queueAttempt: number;
+  targetHost: string;
+  targetPort: number;
+  recipientDomain?: string;
+  recipients: string[];
+  startedAt: string;
+  completedAt: string;
+  durationMs: number;
+  outcome: 'succeeded' | 'failed';
+  retryable: boolean;
+  errorType?: string;
+  smtpCode?: number;
+  recipientResults?: ISmtpRecipientResult[];
+  failurePhase?: TSmtpDeliveryPhase;
+  error?: string;
+  transcript: ISmtpTranscriptEntry[];
+}
+
 /**
  * SMTP session state enumeration
  */
@@ -164,4 +191,3 @@ export interface ISmtpAuth {
    */
   password: string;
 }
-

package/ts/mail/routing/classes.dkim.manager.ts

@@ -1,9 +1,12 @@
 import { logger } from '../../logger.js';
+import { getErrorMessage } from '../../functions.errors.js';
 import { DKIMCreator } from '../security/classes.dkimcreator.js';
 import type { IStorageManager } from '../interfaces.storage.js';
 import { DomainRegistry } from './classes.domain.registry.js';
-import { RustSecurityBridge } from '../../security/classes.rustsecuritybridge.js';
 import { Email } from '../core/classes.email.js';
+import { RustSecurityBridge } from '../../security/classes.rustsecuritybridge.js';
+
+type TDkimKeyProvisioning = 'automatic' | 'caller-managed';
 
 /** External DcRouter interface shape used by DkimManager */
 interface DcRouter {
@@ -16,13 +19,30 @@ interface DcRouter {
  */
 export class DkimManager {
   private dkimKeys: Map<string, string> = new Map();
+  private dkimCreator: DKIMCreator;
+  private domainRegistry: DomainRegistry;
+  private dcRouter: DcRouter;
+  private rustBridge?: RustSecurityBridge;
+  private keyProvisioning: TDkimKeyProvisioning;
 
+  /** v7-compatible constructor shape: the fourth argument remains the Rust bridge. */
   constructor(
-    private dkimCreator: DKIMCreator,
-    private domainRegistry: DomainRegistry,
-    private dcRouter: DcRouter,
-    private rustBridge: RustSecurityBridge,
-  ) {}
+    dkimCreator: DKIMCreator,
+    domainRegistry: DomainRegistry,
+    dcRouter: DcRouter,
+    rustBridgeOrProvisioning?: RustSecurityBridge | TDkimKeyProvisioning,
+    keyProvisioning: TDkimKeyProvisioning = 'automatic',
+  ) {
+    this.dkimCreator = dkimCreator;
+    this.domainRegistry = domainRegistry;
+    this.dcRouter = dcRouter;
+    if (typeof rustBridgeOrProvisioning === 'string') {
+      this.keyProvisioning = rustBridgeOrProvisioning;
+    } else {
+      this.rustBridge = rustBridgeOrProvisioning;
+      this.keyProvisioning = keyProvisioning;
+    }
+  }
 
   async setupDkimForDomains(): Promise<void> {
     const domainConfigs = this.domainRegistry.getAllConfigs();
@@ -36,35 +56,43 @@ export class DkimManager {
       const domain = domainConfig.domain;
       const selector = domainConfig.dkim?.selector || 'default';
 
+      let keyPair: { privateKey: string; publicKey: string };
       try {
-        let keyPair: { privateKey: string; publicKey: string };
-
         try {
-          keyPair = selector === 'default'
-            ? await this.dkimCreator.readDKIMKeys(domain)
-            : await this.dkimCreator.readDKIMKeysForSelector(domain, selector);
+          keyPair = await this.dkimCreator.readValidatedDKIMKeysForSelector(domain, selector);
           logger.log('info', `Using existing DKIM keys for domain: ${domain}`);
-        } catch {
-          await this.dkimCreator.handleDKIMKeysForSelector(
+        } catch (error) {
+          if (this.keyProvisioning === 'caller-managed') {
+            throw new Error(
+              `Caller-managed DKIM readiness failed for ${domain} (selector: ${selector}): ${(error as Error).message}`,
+            );
+          }
+          await this.dkimCreator.createAndStoreDKIMKeysForSelector(
             domain,
             selector,
             domainConfig.dkim?.keySize || 2048,
           );
-          keyPair = selector === 'default'
-            ? await this.dkimCreator.readDKIMKeys(domain)
-            : await this.dkimCreator.readDKIMKeysForSelector(domain, selector);
+          keyPair = await this.dkimCreator.readValidatedDKIMKeysForSelector(domain, selector);
           logger.log('info', `Generated new DKIM keys for domain: ${domain}`);
         }
-
-        this.dkimKeys.set(domain, keyPair.privateKey);
-        logger.log('info', `DKIM keys loaded for domain: ${domain} with selector: ${selector}`);
       } catch (error) {
-        logger.log('error', `Failed to set up DKIM for domain ${domain}: ${error.message}`);
+        logger.log('error', `Failed to set up DKIM for domain ${domain}: ${getErrorMessage(error)}`);
+        if (this.keyProvisioning === 'caller-managed') {
+          throw error;
+        }
+        continue;
       }
+
+      this.dkimKeys.set(domain, keyPair.privateKey);
+      logger.log('info', `DKIM keys loaded for domain: ${domain} with selector: ${selector}`);
     }
   }
 
   async checkAndRotateDkimKeys(): Promise<void> {
+    if (this.keyProvisioning === 'caller-managed') {
+      logger.log('debug', 'Skipping automatic DKIM rotation for caller-managed keys');
+      return;
+    }
     const domainConfigs = this.domainRegistry.getAllConfigs();
 
     for (const domainConfig of domainConfigs) {
@@ -131,36 +159,33 @@ export class DkimManager {
           logger.log('debug', `DKIM keys for ${domain} are up to date`);
         }
       } catch (error) {
-        logger.log('error', `Failed to check/rotate DKIM keys for ${domain}: ${error.message}`);
+        logger.log('error', `Failed to check/rotate DKIM keys for ${domain}: ${getErrorMessage(error)}`);
       }
     }
   }
 
-  async handleDkimSigning(email: Email, domain: string, selector: string): Promise<void> {
+  /** v7 compatibility: explicit callers may still request eager DKIM signing. */
+  public async handleDkimSigning(email: Email, domain: string, selector: string): Promise<void> {
     try {
-      await this.dkimCreator.handleDKIMKeysForSelector(domain, selector);
-      const { privateKey } = selector === 'default'
-        ? await this.dkimCreator.readDKIMKeys(domain)
-        : await this.dkimCreator.readDKIMKeysForSelector(domain, selector);
-      const rawEmail = email.toRFC822String();
-
-      // Detect key type from PEM header
-      const keyType = privateKey.includes('ED25519') ? 'ed25519' : 'rsa';
-
-      const signResult = await this.rustBridge.signDkim({
-        rawMessage: rawEmail,
+      if (this.keyProvisioning === 'automatic') {
+        await this.dkimCreator.handleDKIMKeysForSelector(domain, selector);
+      }
+      const material = await this.dkimCreator.readValidatedDKIMKeysForSelector(domain, selector);
+      const rustBridge = this.rustBridge || RustSecurityBridge.getInstance();
+      const signResult = await rustBridge.signDkim({
+        rawMessage: email.toRFC822String(),
         domain,
         selector,
-        privateKey,
-        keyType,
+        privateKey: material.privateKey,
+        keyType: material.keyType,
       });
-
       if (signResult.header) {
         email.addHeader('DKIM-Signature', signResult.header);
         logger.log('info', `Successfully added DKIM signature for ${domain}`);
       }
     } catch (error) {
-      logger.log('error', `Failed to sign email with DKIM: ${error.message}`);
+      logger.log('error', `Failed to sign email with DKIM: ${(error as Error).message}`);
+      if (this.keyProvisioning === 'caller-managed') throw error;
     }
   }
 

package/ts/mail/routing/classes.dns.manager.ts

@@ -1,7 +1,9 @@
 import * as plugins from '../../plugins.js';
 import type { IEmailDomainConfig } from './interfaces.js';
 import type { IStorageManager } from '../interfaces.storage.js';
+import type { DKIMCreator } from '../security/classes.dkimcreator.js';
 import { logger } from '../../logger.js';
+import { getErrorMessage } from '../../functions.errors.js';
 /** External DcRouter interface shape used by DnsManager */
 interface IDcRouterLike {
   storageManager: IStorageManager;
@@ -53,16 +55,19 @@ export class DnsManager {
   private storageManager: IStorageManager;
   private resolverFactory: () => IDnsResolver;
   private activeResolvers = new Set<IDnsResolver>();
+  private keyProvisioning: 'automatic' | 'caller-managed';
   private activeValidation?: IDnsValidationRun;
   private validationRunId = 0;
   
   constructor(
     dcRouter: IDcRouterLike,
-    resolverFactory: () => IDnsResolver = () => new plugins.dns.promises.Resolver()
+    resolverFactory: () => IDnsResolver = () => new plugins.dns.promises.Resolver(),
+    keyProvisioning: 'automatic' | 'caller-managed' = 'automatic',
   ) {
     this.dcRouter = dcRouter;
     this.storageManager = dcRouter.storageManager;
     this.resolverFactory = resolverFactory;
+    this.keyProvisioning = keyProvisioning;
   }
   
   /**
@@ -125,9 +130,10 @@ export class DnsManager {
       logger.log('info', `DNS validation skipped for forward mode domain: ${config.domain}`);
     }
     
-    // DKIM keys are still generated for consistency
     result.warnings.push(
-      `Domain "${config.domain}" uses forward mode. DKIM keys will be generated but signing only happens if email is processed.`
+      this.keyProvisioning === 'automatic'
+        ? `Domain "${config.domain}" uses forward mode. DKIM keys will be generated but signing only happens if email is processed.`
+        : `Domain "${config.domain}" uses forward mode. Caller-managed DKIM keys are never generated by SmartMTA.`
     );
     
     return result;
@@ -233,7 +239,7 @@ export class DnsManager {
         return result;
       }
       result.warnings.push(
-        `Could not verify NS delegation for ${config.domain}: ${error.message}`
+        `Could not verify NS delegation for ${config.domain}: ${getErrorMessage(error)}`
       );
     }
     
@@ -305,7 +311,7 @@ export class DnsManager {
       if (abortSignal?.aborted) {
         return result;
       }
-      result.errors.push(`DNS validation failed: ${error.message}`);
+      result.errors.push(`DNS validation failed: ${getErrorMessage(error)}`);
       result.valid = false;
     }
     
@@ -404,7 +410,7 @@ export class DnsManager {
       return nsRecords;
     } catch (error) {
       if (!abortSignal?.aborted) {
-        logger.log('warn', `Failed to resolve NS records for ${domain}: ${error.message}`);
+        logger.log('warn', `Failed to resolve NS records for ${domain}: ${getErrorMessage(error)}`);
       }
       return [];
     } finally {
@@ -449,7 +455,10 @@ export class DnsManager {
   }
   
   /** Provision deterministic local DNS records without performing network lookups. */
-  async provisionLocalDnsRecords(domainConfigs: IEmailDomainConfig[], dkimCreator?: any): Promise<void> {
+  async provisionLocalDnsRecords(
+    domainConfigs: IEmailDomainConfig[],
+    dkimCreator?: DKIMCreator,
+  ): Promise<void> {
     logger.log('info', `Provisioning local DNS records for ${domainConfigs.length} domains`);
 
     const internalDnsDomains = domainConfigs.filter(config => config.dnsMode === 'internal-dns');
@@ -458,7 +467,7 @@ export class DnsManager {
       
       // Create DKIM records if DKIMCreator is provided
       if (dkimCreator) {
-        await this.createDkimRecords(domainConfigs, dkimCreator);
+        await this.createDkimRecords(internalDnsDomains, dkimCreator);
       }
     }
   }
@@ -548,7 +557,10 @@ export class DnsManager {
    * Ensure DNS records and validate public DNS state.
    * Prefer the split lifecycle methods when validation must not block readiness.
    */
-  async ensureDnsRecords(domainConfigs: IEmailDomainConfig[], dkimCreator?: any): Promise<void> {
+  async ensureDnsRecords(
+    domainConfigs: IEmailDomainConfig[],
+    dkimCreator?: DKIMCreator,
+  ): Promise<void> {
     await this.provisionLocalDnsRecords(domainConfigs, dkimCreator);
     await this.validateAndReportDnsRecords(domainConfigs);
   }
@@ -658,7 +670,7 @@ export class DnsManager {
   - DKIM: Will be created when keys are generated`);
         
       } catch (error) {
-        logger.log('error', `Failed to create DNS records for ${domain}: ${error.message}`);
+        logger.log('error', `Failed to create DNS records for ${domain}: ${getErrorMessage(error)}`);
       }
     }
   }
@@ -666,13 +678,24 @@ export class DnsManager {
   /**
    * Create DKIM DNS records for all domains
    */
-  private async createDkimRecords(domainConfigs: IEmailDomainConfig[], dkimCreator: any): Promise<void> {
+  private async createDkimRecords(
+    domainConfigs: IEmailDomainConfig[],
+    dkimCreator: DKIMCreator,
+  ): Promise<void> {
     for (const domainConfig of domainConfigs) {
       const domain = domainConfig.domain;
       const selector = domainConfig.dkim?.selector || 'default';
       
       try {
-        // Get DKIM DNS record from DKIMCreator
+        if (this.keyProvisioning === 'caller-managed') {
+          // Ownership remains entirely with the embedding application. This is
+          // a read-only validity check: no handler, storage record, or selector
+          // mutation is permitted in caller-managed mode.
+          await dkimCreator.getDNSRecordForSelector(domain, selector);
+          logger.log('info', `Verified caller-managed DKIM record for ${selector}._domainkey.${domain}`);
+          continue;
+        }
+
         const dnsRecord = await dkimCreator.getDNSRecordForDomain(domain, selector);
         
         // For internal-dns domains, register the DNS handler
@@ -711,7 +734,7 @@ export class DnsManager {
         }
         
       } catch (error) {
-        logger.log('warn', `Could not create DKIM DNS record for ${domain}: ${error.message}`);
+        logger.log('warn', `Could not create DKIM DNS record for ${domain}: ${getErrorMessage(error)}`);
       }
     }
   }

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

@@ -1,4 +1,5 @@
 import { logger } from '../../logger.js';
+import { getErrorMessage } from '../../functions.errors.js';
 import {
   SecurityLogger,
   SecurityLogLevel,
@@ -8,7 +9,12 @@ import type { IEmailAction, IEmailContext } from './interfaces.js';
 import { Email } from '../core/classes.email.js';
 import { BounceManager } from '../core/classes.bouncemanager.js';
 import { UnifiedDeliveryQueue } from '../delivery/classes.delivery.queue.js';
-import type { ISmtpSendResult } from '../../security/classes.rustsecuritybridge.js';
+import { callObserverSafely } from '../delivery/functions.safe-observers.js';
+import {
+  SmtpDeliveryError,
+  type ISmtpRecipientResult,
+  type ISmtpSendResult,
+} from '../../security/classes.rustsecuritybridge.js';
 
 /**
  * Dependencies injected from UnifiedEmailServer to avoid circular imports
@@ -30,6 +36,31 @@ export interface IActionExecutorDeps {
 export class EmailActionExecutor {
   constructor(private deps: IActionExecutorDeps) {}
 
+  private async suppressPermanentRcptFailures(
+    email: Email,
+    results: ISmtpRecipientResult[],
+  ): Promise<void> {
+    for (const result of results) {
+      if (result.accepted || result.responseCode < 500) continue;
+      try {
+        await this.deps.bounceManager.processSmtpFailure(
+          result.recipient,
+          `SMTP recipient rejected with ${result.responseCode}`,
+          {
+            sender: email.from,
+            originalEmailId: email.headers['Message-ID'] as string,
+            statusCode: String(result.responseCode),
+          },
+        );
+      } catch (error) {
+        logger.log(
+          'error',
+          `Failed to persist permanent RCPT failure for ${result.recipient}: ${(error as Error).message}`,
+        );
+      }
+    }
+  }
+
   async executeAction(action: IEmailAction, email: Email, context: IEmailContext): Promise<void> {
     switch (action.type) {
       case 'forward':
@@ -72,13 +103,14 @@ export class EmailActionExecutor {
 
     try {
       // Send email via Rust SMTP client
-      await this.deps.sendOutboundEmail(host, port, email, {
+      const result = await this.deps.sendOutboundEmail(host, port, email, {
         auth: auth as { user: string; pass: string } | undefined,
       });
+      await this.suppressPermanentRcptFailures(email, result.recipientResults || []);
 
       logger.log('info', `Successfully forwarded email to ${host}:${port}`);
 
-      SecurityLogger.getInstance().logEvent({
+      await callObserverSafely('forward success security log', () => SecurityLogger.getInstance().logEvent({
         level: SecurityLogLevel.INFO,
         type: SecurityEventType.EMAIL_FORWARDING,
         message: 'Email forwarded successfully',
@@ -91,11 +123,12 @@ export class EmailActionExecutor {
           recipients: email.to
         },
         success: true
-      });
+      }));
     } catch (error) {
-      logger.log('error', `Failed to forward email: ${error.message}`);
+      const errorMessage = getErrorMessage(error);
+      logger.log('error', `Failed to forward email: ${errorMessage}`);
 
-      SecurityLogger.getInstance().logEvent({
+      await callObserverSafely('forward failure security log', () => SecurityLogger.getInstance().logEvent({
         level: SecurityLogLevel.ERROR,
         type: SecurityEventType.EMAIL_FORWARDING,
         message: 'Email forwarding failed',
@@ -105,17 +138,31 @@ export class EmailActionExecutor {
           routeName: context.session.matchedRoute?.name,
           targetHost: host,
           targetPort: port,
-          error: error.message
+          error: errorMessage
         },
         success: false
-      });
-
-      // Handle as bounce
-      for (const recipient of email.getAllRecipients()) {
-        await this.deps.bounceManager.processSmtpFailure(recipient, error.message, {
-          sender: email.from,
-          originalEmailId: email.headers['Message-ID'] as string
-        });
+      }));
+
+      const smtpError = SmtpDeliveryError.from(error);
+      if (
+        !smtpError.retryable
+        && smtpError.errorType === 'protocol'
+        && smtpError.phase === 'rcpt_to'
+        && (
+          (typeof smtpError.smtpCode === 'number' && smtpError.smtpCode >= 500)
+          || smtpError.recipientResults.some(
+            (result) => !result.accepted && result.responseCode >= 500,
+          )
+        )
+      ) {
+        const permanentResults = smtpError.recipientResults.length > 0
+          ? smtpError.recipientResults
+          : smtpError.recipients.map((recipient) => ({
+              recipient,
+              accepted: false,
+              responseCode: smtpError.smtpCode!,
+            }));
+        await this.suppressPermanentRcptFailures(email, permanentResults);
       }
       throw error;
     }
@@ -151,7 +198,7 @@ export class EmailActionExecutor {
 
     logger.log('info', `Rejecting email with code ${code}: ${message}`);
 
-    SecurityLogger.getInstance().logEvent({
+    await callObserverSafely('routing rejection security log', () => SecurityLogger.getInstance().logEvent({
       level: SecurityLogLevel.WARN,
       type: SecurityEventType.EMAIL_PROCESSING,
       message: 'Email rejected by routing rule',
@@ -165,7 +212,7 @@ export class EmailActionExecutor {
         to: _email.to
       },
       success: false
-    });
+    }));
 
     // Throw error with SMTP code and message
     const error = new Error(message);

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

@@ -3,6 +3,7 @@ import { EventEmitter } from 'node:events';
 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';
 
 /**
  * Email router that evaluates routes and determines actions
@@ -12,6 +13,7 @@ export class EmailRouter extends EventEmitter {
   private patternCache: Map<string, boolean> = new Map();
   private storageManager?: IStorageManager;
   private persistChanges: boolean;
+  private initializationPromise: Promise<void>;
   
   /**
    * Create a new email router
@@ -27,12 +29,17 @@ export class EmailRouter extends EventEmitter {
     this.storageManager = options?.storageManager;
     this.persistChanges = options?.persistChanges ?? !!this.storageManager;
     
-    // If storage manager is provided, try to load persisted routes
-    if (this.storageManager) {
-      this.loadRoutes({ merge: true }).catch(error => {
-        console.error(`Failed to load persisted routes: ${error.message}`);
-      });
-    }
+    // Capture hydration so callers can establish a real readiness barrier before routing.
+    const hydrationPromise = this.storageManager
+      ? this.loadRoutes({ merge: true }).then(() => undefined)
+      : Promise.resolve();
+    hydrationPromise.catch(() => undefined);
+    this.initializationPromise = hydrationPromise;
+  }
+
+  /** Wait until managed routes have been hydrated. */
+  public async initialize(): Promise<void> {
+    await this.initializationPromise;
   }
   
   /**
@@ -413,7 +420,7 @@ export class EmailRouter extends EventEmitter {
       
       this.emit('routesPersisted', this.routes.length);
     } catch (error) {
-      console.error(`Failed to save routes: ${error.message}`);
+      console.error(`Failed to save routes: ${getErrorMessage(error)}`);
       throw error;
     }
   }
@@ -473,7 +480,7 @@ export class EmailRouter extends EventEmitter {
       
       return loadedRoutes;
     } catch (error) {
-      console.error(`Failed to load routes: ${error.message}`);
+      console.error(`Failed to load routes: ${getErrorMessage(error)}`);
       throw error;
     }
   }