@push.rocks/smartmta 6.5.2 → 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/interfaces.storage.ts

@@ -1,13 +1,67 @@
-export interface IStorageManagerLike {
-  get?(key: string): Promise<string | null>;
-  set?(key: string, value: string): Promise<void>;
-  list?(prefix: string): Promise<string[]>;
-  delete?(key: string): Promise<void>;
+/**
+ * Durable storage for SmartMTA's small textual state.
+ *
+ * Implementations are supplied by the embedding application and are expected
+ * to use SmartData, SmartBucket, or another explicitly managed backend.
+ * SmartMTA never falls back to the local filesystem.
+ */
+export interface IStorageManager {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+  delete(key: string): Promise<void>;
 }
 
-export function hasStorageManagerMethods<T extends keyof IStorageManagerLike>(
-  storageManager: IStorageManagerLike | undefined,
-  methods: T[],
-): storageManager is IStorageManagerLike & Required<Pick<IStorageManagerLike, T>> {
-  return !!storageManager && methods.every((method) => typeof storageManager[method] === 'function');
+/** Blob storage for queued messages and template attachments. */
+export interface IBlobStorageManager {
+  get(key: string): Promise<Buffer | null>;
+  set(key: string, value: Buffer): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+  delete(key: string): Promise<void>;
 }
+
+/** In-memory small-state store for tests and explicitly non-durable runtimes. */
+export class MemoryStorageManager implements IStorageManager {
+  private readonly entries = new Map<string, string>();
+
+  public async get(key: string): Promise<string | null> {
+    return this.entries.get(key) ?? null;
+  }
+
+  public async set(key: string, value: string): Promise<void> {
+    this.entries.set(key, value);
+  }
+
+  public async list(prefix: string): Promise<string[]> {
+    return [...this.entries.keys()].filter((key) => key.startsWith(prefix)).sort();
+  }
+
+  public async delete(key: string): Promise<void> {
+    this.entries.delete(key);
+  }
+}
+
+/** In-memory blob store for tests and explicitly non-durable runtimes. */
+export class MemoryBlobStorageManager implements IBlobStorageManager {
+  private readonly entries = new Map<string, Buffer>();
+
+  public async get(key: string): Promise<Buffer | null> {
+    const value = this.entries.get(key);
+    return value ? Buffer.from(value) : null;
+  }
+
+  public async set(key: string, value: Buffer): Promise<void> {
+    this.entries.set(key, Buffer.from(value));
+  }
+
+  public async list(prefix: string): Promise<string[]> {
+    return [...this.entries.keys()].filter((key) => key.startsWith(prefix)).sort();
+  }
+
+  public async delete(key: string): Promise<void> {
+    this.entries.delete(key);
+  }
+}
+
+/** @deprecated Use IStorageManager. */
+export type IStorageManagerLike = IStorageManager;

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

@@ -1,13 +1,16 @@
 import { logger } from '../../logger.js';
+import { getErrorMessage } from '../../functions.errors.js';
 import { DKIMCreator } from '../security/classes.dkimcreator.js';
-import { hasStorageManagerMethods, type IStorageManagerLike } from '../interfaces.storage.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 {
-  storageManager?: IStorageManagerLike;
+  storageManager?: IStorageManager;
   dnsServer?: any;
 }
 
@@ -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) {
@@ -115,7 +143,7 @@ export class DkimManager {
 
             logger.log('info', `DKIM DNS handler registered for new selector: ${newSelector}._domainkey.${domain}`);
 
-            if (hasStorageManagerMethods(this.dcRouter.storageManager, ['set'])) {
+            if (this.dcRouter.storageManager) {
               await this.dcRouter.storageManager.set(
                 `/email/dkim/${domain}/public.key`,
                 keyPair.publicKey
@@ -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,10 +1,12 @@
 import * as plugins from '../../plugins.js';
 import type { IEmailDomainConfig } from './interfaces.js';
-import type { IStorageManagerLike } from '../interfaces.storage.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: IStorageManagerLike;
+  storageManager: IStorageManager;
   dnsServer?: any;
   options?: { dnsNsDomains?: string[]; dnsScopes?: string[] };
 }
@@ -50,19 +52,22 @@ interface IDnsValidationRun {
  */
 export class DnsManager {
   private dcRouter: IDcRouterLike;
-  private storageManager: IStorageManagerLike;
+  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)}`);
       }
     }
   }