@push.rocks/smartmta 8.2.1 → 9.1.0

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

@@ -18,12 +18,15 @@ import type {
   IRcptToRequestEvent,
   IScramCredentialRequestEvent,
 } from '../../security/classes.rustsecuritybridge.js';
-import { EmailRouter } from './classes.email.router.js';
+import { EmailRouter, addressGlobToRegExp } from './classes.email.router.js';
+import { assertValidAuthAccounts } from './functions.routing.validation.js';
 import type {
   IEmailRoute,
   IEmailAction,
   IEmailContext,
   IEmailDomainConfig,
+  ISmtpAuthAccount,
+  ISmtpScramVerifier,
 } from './interfaces.js';
 import { Email } from '../core/classes.email.js';
 import { DomainRegistry } from './classes.domain.registry.js';
@@ -61,7 +64,10 @@ export type TRecipientRejectionReason =
   | 'domain-not-hosted'
   | 'relay-denied'
   | 'recipient-hook'
-  | 'policy-error';
+  | 'policy-error'
+  | 'sender-scope'
+  | 'recipient-scope'
+  | 'account-disabled';
 
 export interface IResolvedRecipientRoute {
   recipient: string;
@@ -147,8 +153,9 @@ export class AcceptEnvelopeRejectionError extends Error {
 }
 
 /**
- * Terminal durable acceptance context for an envelope containing at least one `store` route.
- * The consumer owns persistence and all recipient fan-out before this hook resolves.
+ * Terminal durable acceptance context for an envelope containing at least one
+ * `store` or `deliver` route. The consumer owns persistence and all recipient
+ * fan-out before this hook resolves.
  */
 export interface IAcceptEnvelopeContext {
   email: Email;
@@ -294,6 +301,11 @@ export interface IUnifiedEmailServerOptions {
     required?: boolean;
     methods?: ('PLAIN' | 'LOGIN' | 'OAUTH2')[];
     users?: Array<{username: string, password: string}>;
+    /**
+     * Authenticated SMTP accounts with hashed credentials and send scopes.
+     * Coexists with legacy `users`; accounts win on username collision.
+     */
+    accounts?: ISmtpAuthAccount[];
   };
 
   // TLS options
@@ -338,9 +350,14 @@ export interface IUnifiedEmailServerOptions {
   hooks?: {
     /** Async recipient policy hook that may further restrict an accepted built-in decision. */
     onRcptTo?: (context: IRcptToPolicyContext) => Promise<ISmtpDecision>;
-    /** Async message acceptance hook for envelopes with no resolved `store` action. */
+    /** Async message acceptance hook for envelopes with no resolved `store` or `deliver` action. */
     onMessageData?: (context: IMessageAcceptanceContext) => Promise<IMessageAcceptanceDecision>;
-    /** Required terminal durable owner for any envelope containing a resolved `store` action. */
+    /**
+     * Required terminal durable owner for any envelope containing a resolved
+     * `store` or `deliver` action. The hook must durably persist the exact
+     * raw message before resolving; its resolution is what authorizes the
+     * SMTP 250 for those envelopes.
+     */
     onAcceptEnvelope?: (context: IAcceptEnvelopeContext) => Promise<void>;
     /** Observer-safe callback for SMTP recipient rejections. */
     onRecipientRejected?: (event: IRecipientRejectedEvent) => Promise<void> | void;
@@ -456,6 +473,15 @@ export class UnifiedEmailServer extends EventEmitter {
   private acceptedEnvelopeDispatchCleanupTimer?: ReturnType<typeof setInterval>;
   private acceptedEnvelopeDispatchCleanupPromise?: Promise<void>;
   private acceptedEnvelopeDispatchCleanupCursor?: string;
+  private smtpListenerActive = false;
+  private smtpListenerShutdown = false;
+  private smtpListenerRestartPromise?: Promise<void>;
+  private static readonly VERIFIER_DERIVATION_CONCURRENCY = 4;
+  private static readonly VERIFIER_DERIVATION_MAX_QUEUE = 32;
+  private verifierDerivationActive = 0;
+  private verifierDerivationWaiters: Array<() => void> = [];
+  /** Compiled scope patterns; keys are config-supplied, bounded by config size. */
+  private scopePatternCache: Map<string, RegExp> = new Map();
 
   constructor(dcRouter: DcRouter, options: IUnifiedEmailServerOptions) {
     super();
@@ -472,6 +498,10 @@ export class UnifiedEmailServer extends EventEmitter {
       socketTimeout: options.socketTimeout || 60000 // 1 minute
     };
 
+    // Auth account misconfiguration must fail loudly at configuration time,
+    // never degrade into silent deny-all scopes or silent auth failures.
+    assertValidAuthAccounts(this.options.auth?.accounts);
+
     // Initialize Rust security bridge (singleton)
     this.rustBridge = RustSecurityBridge.getInstance();
 
@@ -488,10 +518,13 @@ export class UnifiedEmailServer extends EventEmitter {
     // Initialize domain registry
     this.domainRegistry = new DomainRegistry(options.domains, options.defaults);
 
-    // Initialize email router with routes and storage manager
+    // Initialize email router with routes and storage manager. The action
+    // policy applies to configured, updated, and storage-hydrated routes so
+    // an unservable route set fails loudly at configuration time.
     this.emailRouter = new EmailRouter(options.routes || [], {
       storageManager: dcRouter.storageManager,
-      persistChanges: options.persistRoutes ?? true
+      persistChanges: options.persistRoutes ?? true,
+      validateAction: (route) => this.assertRouteActionServable(route),
     });
 
     // Initialize rate limiter
@@ -918,6 +951,7 @@ export class UnifiedEmailServer extends EventEmitter {
    */
   public async start(): Promise<void> {
     logger.log('info', `Starting UnifiedEmailServer on ports: ${(this.options.ports as number[]).join(', ')}`);
+    this.smtpListenerShutdown = false;
 
     try {
       await this.startDeliveryPipeline();
@@ -1160,7 +1194,7 @@ export class UnifiedEmailServer extends EventEmitter {
       maxRecipients: 100,
       connectionTimeoutSecs: this.options.connectionTimeout ? Math.floor(this.options.connectionTimeout / 1000) : 30,
       dataTimeoutSecs: 60,
-      authEnabled: !!this.options.auth?.required || !!(this.options.auth?.users?.length),
+      authEnabled: this.isAuthConfigured(this.options),
       maxAuthFailures: 3,
       socketTimeoutSecs: this.options.socketTimeout ? Math.floor(this.options.socketTimeout / 1000) : 300,
       processingTimeoutSecs: this.options.hooks?.onMessageData || this.options.hooks?.onAcceptEnvelope
@@ -1184,9 +1218,57 @@ export class UnifiedEmailServer extends EventEmitter {
       throw new Error('Failed to start Rust SMTP server');
     }
 
+    this.smtpListenerActive = true;
     logger.log('info', `Rust SMTP server listening on ports: ${smtpPorts.join(', ')}${securePort ? ` + ${securePort} (TLS)` : ''}`);
   }
 
+  /** Whether the current options require SMTP AUTH support on the listener. */
+  private isAuthConfigured(options: IUnifiedEmailServerOptions): boolean {
+    return !!options.auth?.required
+      || !!options.auth?.users?.length
+      || !!options.auth?.accounts?.length;
+  }
+
+  /**
+   * Whether the Rust SMTP listener is currently accepting connections.
+   * Embedders should surface this next to getBridgeState() in health
+   * endpoints: a failed listener reconfiguration leaves it false.
+   */
+  public isSmtpListenerActive(): boolean {
+    return this.smtpListenerActive;
+  }
+
+  /**
+   * Restart only the Rust SMTP listener so listener-level configuration such
+   * as AUTH availability takes effect without a full process restart.
+   * Restarts are serialized and become no-ops once shutdown has begun; a
+   * failed restart leaves the listener inactive, logs loudly, and emits
+   * 'smtpListenerRestartFailed' so embedders can react (e.g. by calling
+   * stop()/start()).
+   */
+  private scheduleSmtpListenerRestart(reason: string): void {
+    const previous = this.smtpListenerRestartPromise || Promise.resolve();
+    this.smtpListenerRestartPromise = previous
+      .then(async () => {
+        if (this.smtpListenerShutdown) return;
+        logger.log('info', `Restarting Rust SMTP listener: ${reason}`);
+        this.smtpListenerActive = false;
+        await this.rustBridge.stopSmtpServer();
+        if (this.smtpListenerShutdown) return;
+        await this.startSmtpServer();
+      })
+      .catch(async (error) => {
+        logger.log(
+          'error',
+          `Failed to restart Rust SMTP listener (${reason}): ${getErrorMessage(error)}`,
+        );
+        await emitSafely(this, 'smtpListenerRestartFailed', {
+          reason,
+          message: getErrorMessage(error),
+        });
+      });
+  }
+
   /**
    * Stop the unified email server
    */
@@ -1199,6 +1281,18 @@ export class UnifiedEmailServer extends EventEmitter {
         this.acceptedEnvelopeDispatchCleanupTimer = undefined;
       }
       await this.acceptedEnvelopeDispatchCleanupPromise;
+      // Prevent new listener restarts from being scheduled or executed
+      // during shutdown, then drain any in-flight reconfiguration before
+      // tearing down (the chain may be extended while awaited).
+      this.smtpListenerShutdown = true;
+      this.smtpListenerActive = false;
+      while (this.smtpListenerRestartPromise) {
+        const pendingRestart = this.smtpListenerRestartPromise;
+        await pendingRestart;
+        if (this.smtpListenerRestartPromise === pendingRestart) {
+          this.smtpListenerRestartPromise = undefined;
+        }
+      }
       await this.stopDnsValidation();
 
       // Stop the Rust SMTP server first
@@ -1208,6 +1302,7 @@ export class UnifiedEmailServer extends EventEmitter {
       } catch (err) {
         logger.log('warn', `Error stopping Rust SMTP server: ${(err as Error).message}`);
       }
+      this.smtpListenerActive = false;
 
       // Clear the servers array - servers will be garbage collected
       this.servers = [];
@@ -1325,6 +1420,30 @@ export class UnifiedEmailServer extends EventEmitter {
     emailArg?: Email,
     sessionArg?: IExtendedSmtpSession,
   ): Promise<IRecipientPolicyResolution> {
+    // Account scopes are envelope policy and precede route evaluation. This
+    // runs both at RCPT TO and again per recipient at DATA (where the
+    // context is rebuilt from session.envelope truth), so an out-of-scope
+    // MAIL FROM is rejected before any recipient is accepted and cannot be
+    // smuggled past the first phase.
+    const scopeViolation = this.resolveAuthAccountScopeDecision(
+      context.authenticatedUser,
+      context.mailFrom,
+      context.rcptTo,
+    );
+    if (scopeViolation) {
+      const scopeRecipientDomain = this.getAddressDomain(context.rcptTo);
+      return {
+        recipient: context.rcptTo,
+        localDomain: scopeRecipientDomain && this.domainRegistry.isDomainRegistered(scopeRecipientDomain)
+          ? scopeRecipientDomain
+          : null,
+        route: null,
+        source: 'no-route',
+        decision: scopeViolation.decision,
+        rejectionReason: scopeViolation.rejectionReason,
+      };
+    }
+
     const currentRecipientContext = { ...context, acceptedRcptTo: [] };
     const email = emailArg || new Email({
       from: context.mailFrom || '<>',
@@ -1354,6 +1473,37 @@ export class UnifiedEmailServer extends EventEmitter {
         };
       }
 
+      if (route.action.type === 'deliver') {
+        if (!isLocalRecipient) {
+          // Deliver actions are terminal local deliveries and never relay;
+          // `allowRelay` is ignored for them.
+          return {
+            recipient: context.rcptTo,
+            localDomain: null,
+            route,
+            source: 'explicit-route',
+            decision: { accepted: false, smtpCode: 550, smtpMessage: 'Relay not permitted' },
+            rejectionReason: 'relay-denied',
+          };
+        }
+        if (!this.options.hooks?.onAcceptEnvelope) {
+          // Defense in depth: route validation rejects this configuration,
+          // so refuse loudly at accept time rather than accept-then-fail.
+          return {
+            recipient: context.rcptTo,
+            localDomain,
+            route,
+            source: 'explicit-route',
+            decision: {
+              accepted: false,
+              smtpCode: 451,
+              smtpMessage: 'Local delivery temporarily unavailable',
+            },
+            rejectionReason: 'policy-error',
+          };
+        }
+      }
+
       if (!isLocalRecipient && !route.action.allowRelay) {
         return {
           recipient: context.rcptTo,
@@ -1500,6 +1650,156 @@ export class UnifiedEmailServer extends EventEmitter {
     return match?.[1];
   }
 
+  // -----------------------------------------------------------------------
+  // SMTP auth accounts and scopes
+  // -----------------------------------------------------------------------
+
+  /** Resolve the configured account for a username. Accounts win over legacy users. */
+  private findAuthAccount(username: string): ISmtpAuthAccount | undefined {
+    return this.options.auth?.accounts?.find(
+      (account) => account.username === username,
+    );
+  }
+
+  private normalizeScopeAddress(addressArg: string | null | undefined): string {
+    return (addressArg || '').trim().replace(/^<|>$/g, '').toLowerCase();
+  }
+
+  /**
+   * Glob match ('a@b.com' | '*@b.com') against a normalized address, using
+   * the same pattern semantics as route matching. Compiled patterns are
+   * cached; keys are configuration-supplied (never remote-controlled), so
+   * the cache is bounded by account configuration size.
+   */
+  private matchesScopePatterns(
+    addressArg: string | null | undefined,
+    patterns: string[] | undefined,
+  ): boolean {
+    const address = this.normalizeScopeAddress(addressArg);
+    return (patterns || []).some((pattern) => {
+      let regExp = this.scopePatternCache.get(pattern);
+      if (!regExp) {
+        regExp = addressGlobToRegExp(pattern.trim());
+        this.scopePatternCache.set(pattern, regExp);
+      }
+      return regExp.test(address);
+    });
+  }
+
+  /**
+   * Envelope-level scope decision for an authenticated session. Returns null
+   * when the envelope is permitted (unauthenticated sessions, usernames with
+   * no configured account, and accounts without a scope are unrestricted).
+   */
+  private resolveAuthAccountScopeDecision(
+    authenticatedUser: string | null,
+    mailFrom: string,
+    rcptTo: string,
+  ): { decision: ISmtpDecision; rejectionReason: TRecipientRejectionReason } | null {
+    if (!authenticatedUser) return null;
+    const account = this.findAuthAccount(authenticatedUser);
+    if (!account) return null;
+    if (account.enabled === false) {
+      // The account was disabled after authentication succeeded; the session
+      // must not be able to send anything.
+      return {
+        decision: {
+          accepted: false,
+          smtpCode: 550,
+          smtpMessage: '5.7.1 Account disabled',
+        },
+        rejectionReason: 'account-disabled',
+      };
+    }
+    const scope = account.scope;
+    if (!scope) return null;
+    if (!this.matchesScopePatterns(mailFrom, scope.senders)) {
+      return {
+        decision: {
+          accepted: false,
+          smtpCode: 553,
+          smtpMessage: `5.7.1 Sender address not permitted for authenticated user ${authenticatedUser}`,
+        },
+        rejectionReason: 'sender-scope',
+      };
+    }
+    if (
+      scope.recipients?.mode === 'patterns'
+      && !this.matchesScopePatterns(rcptTo, scope.recipients.patterns)
+    ) {
+      return {
+        decision: {
+          accepted: false,
+          smtpCode: 550,
+          smtpMessage: `5.7.1 Recipient not permitted for authenticated user ${authenticatedUser}`,
+        },
+        rejectionReason: 'recipient-scope',
+      };
+    }
+    return null;
+  }
+
+  /**
+   * Extract every mailbox address from the parsed From header. The Email
+   * abstraction keeps only the first From mailbox, which is not sufficient
+   * for scope enforcement: `From: allowed@a.com, victim@b.com` must not
+   * pass. Parsing stops at the first CRLFCRLF header boundary when present
+   * (the Rust receiver normalizes line endings to CRLF); a bodyless message
+   * without one is parsed whole.
+   */
+  private async parseHeaderFromMailboxes(rawMessage: Buffer): Promise<string[]> {
+    const headerBoundary = rawMessage.indexOf('\r\n\r\n');
+    const headerSection = headerBoundary === -1
+      ? rawMessage
+      : rawMessage.subarray(0, headerBoundary + 4);
+    const parsed = await plugins.mailparser.simpleParser(headerSection);
+    return ((parsed.from as any)?.value || [])
+      .map((mailbox: any) => mailbox?.address)
+      .filter(Boolean) as string[];
+  }
+
+  /**
+   * Header-From alignment for scoped authenticated accounts at DATA. The
+   * envelope MAIL FROM is enforced per recipient via resolveRecipientPolicy
+   * from session.envelope truth; every parsed header From mailbox must
+   * independently stay in scope because route matching and downstream
+   * consumers see the header identity.
+   */
+  private async checkAuthenticatedHeaderFromScope(
+    email: Email,
+    rawMessage: Buffer,
+    session: IExtendedSmtpSession,
+  ): Promise<ISmtpDecision | null> {
+    const username = session.user?.username;
+    if (!username) return null;
+    const account = this.findAuthAccount(username);
+    // Disabled accounts and envelope violations are rejected by
+    // resolveRecipientPolicy; this check only adds header alignment.
+    if (!account || account.enabled === false || !account.scope) return null;
+    let fromMailboxes: string[];
+    try {
+      fromMailboxes = await this.parseHeaderFromMailboxes(rawMessage);
+    } catch {
+      fromMailboxes = [];
+    }
+    if (fromMailboxes.length === 0) {
+      // No parsable From header: Email.from falls back to the envelope
+      // MAIL FROM, which resolveRecipientPolicy has already scope-checked.
+      fromMailboxes = [email.getFromAddress()];
+    }
+    const outOfScope = fromMailboxes.find(
+      (mailbox) => !this.matchesScopePatterns(mailbox, account.scope!.senders),
+    );
+    if (outOfScope === undefined) {
+      return null;
+    }
+    return {
+      accepted: false,
+      smtpCode: 553,
+      smtpMessage: `5.7.1 Header From address not permitted for authenticated user ${username}`,
+    };
+  }
+
   private getRecipientValidationTimeoutMs(): number {
     return this.options.smtp?.recipientValidationTimeoutMs || 5000;
   }
@@ -2088,7 +2388,6 @@ export class UnifiedEmailServer extends EventEmitter {
     }
     const hasQueueAction = plan.some((entry) => (
       entry.action.type === 'forward'
-      || entry.action.type === 'deliver'
       || entry.action.type === 'process'
     ));
     if (hasQueueAction) {
@@ -2168,7 +2467,16 @@ export class UnifiedEmailServer extends EventEmitter {
 
       try {
         let result: IAcceptedEnvelopeRecipientDispatchResult;
-        if (entry.action.type === 'store') {
+        if (entry.action.type === 'store' || entry.action.type === 'deliver') {
+          // Terminal local deliveries: the consumer's durably persisted copy
+          // of the accepted envelope IS the delivery. Nothing is enqueued.
+          if (entry.action.type === 'deliver' && entry.localDomain === null) {
+            // Pre-9.x plans could contain relay-intended deliver entries.
+            // Deliver never relays, so fail loudly instead of dropping.
+            throw new Error(
+              `Deliver action for ${entry.recipient} has no local domain; deliver actions never relay`,
+            );
+          }
           result = { ...commonResult, status: 'stored' };
         } else {
           parsedEmail ||= await this.createEmailFromBuffer(rawCopy, baseSession);
@@ -2275,6 +2583,29 @@ export class UnifiedEmailServer extends EventEmitter {
 
 
       const email = await this.createEmailFromBuffer(rawMessageBuffer, session);
+
+      // Header-From alignment for scoped authenticated accounts must be
+      // enforced before any durable acceptance or routing: the RCPT phase
+      // only ever saw the envelope MAIL FROM.
+      const headerFromViolation = await this.checkAuthenticatedHeaderFromScope(
+        email,
+        rawMessageBuffer,
+        session,
+      );
+      if (headerFromViolation) {
+        logger.log(
+          'warn',
+          `Rejected DATA from authenticated user ${session.user?.username}: ${headerFromViolation.smtpMessage}`,
+        );
+        await this.rustBridge.sendEmailProcessingResult({
+          correlationId,
+          accepted: false,
+          smtpCode: headerFromViolation.smtpCode || 553,
+          smtpMessage: headerFromViolation.smtpMessage || 'Header From not permitted',
+        });
+        return;
+      }
+
       const resolvedRecipientRoutes = await this.resolveDataRecipientRoutes(email, session);
       const rejectedRecipients = resolvedRecipientRoutes.filter(
         (resolution) => !resolution.decision.accepted,
@@ -2298,10 +2629,13 @@ export class UnifiedEmailServer extends EventEmitter {
         return;
       }
 
-      const hasStoreRoute = resolvedRecipientRoutes.some(
-        (resolution) => resolution.route?.action.type === 'store',
+      // `store` and `deliver` are both terminal local deliveries: the
+      // envelope must be durably owned by the consumer before SMTP 250.
+      const hasDurableLocalRoute = resolvedRecipientRoutes.some(
+        (resolution) => resolution.route?.action.type === 'store'
+          || resolution.route?.action.type === 'deliver',
       );
-      if (hasStoreRoute) {
+      if (hasDurableLocalRoute) {
         try {
           await this.acceptDurableEnvelope(
             email,
@@ -2498,20 +2832,161 @@ export class UnifiedEmailServer extends EventEmitter {
   }
 
   /**
-   * Handle an authRequest event from the Rust SMTP server.
+   * Compute SCRAM-SHA-256 credential fields from a plaintext password with a
+   * fresh random salt (used for legacy plaintext credentials only; verifier
+   * accounts return their stored fields directly).
+   */
+  private computeScramCredentials(password: string): {
+    salt: string;
+    iterations: number;
+    storedKey: string;
+    serverKey: string;
+  } {
+    const salt = plugins.crypto.randomBytes(16);
+    const iterations = 4096;
+
+    // SaltedPassword = PBKDF2-HMAC-SHA256(password, salt, iterations, 32)
+    const saltedPassword = plugins.crypto.pbkdf2Sync(password, salt, iterations, 32, 'sha256');
+
+    // ClientKey = HMAC-SHA256(SaltedPassword, "Client Key")
+    const clientKey = plugins.crypto.createHmac('sha256', saltedPassword).update('Client Key').digest();
+
+    // StoredKey = SHA256(ClientKey)
+    const storedKey = plugins.crypto.createHash('sha256').update(clientKey).digest();
+
+    // ServerKey = HMAC-SHA256(SaltedPassword, "Server Key")
+    const serverKey = plugins.crypto.createHmac('sha256', saltedPassword).update('Server Key').digest();
+
+    return {
+      salt: salt.toString('base64'),
+      iterations,
+      storedKey: storedKey.toString('base64'),
+      serverKey: serverKey.toString('base64'),
+    };
+  }
+
+  /**
+   * Bound concurrent PBKDF2 derivations so credential-stuffing pressure at
+   * high configured iteration counts cannot exhaust the shared libuv
+   * threadpool. Returns false when the wait queue is saturated (fail fast).
+   */
+  private async acquireVerifierDerivationSlot(): Promise<boolean> {
+    if (this.verifierDerivationActive < UnifiedEmailServer.VERIFIER_DERIVATION_CONCURRENCY) {
+      this.verifierDerivationActive++;
+      return true;
+    }
+    if (this.verifierDerivationWaiters.length >= UnifiedEmailServer.VERIFIER_DERIVATION_MAX_QUEUE) {
+      return false;
+    }
+    await new Promise<void>((resolve) => {
+      this.verifierDerivationWaiters.push(resolve);
+    });
+    // Slot ownership was handed over directly by the releaser.
+    return true;
+  }
+
+  private releaseVerifierDerivationSlot(): void {
+    const nextWaiter = this.verifierDerivationWaiters.shift();
+    if (nextWaiter) {
+      // Hand the active slot to the waiter without decrementing so the
+      // concurrency bound is exact even across microtask gaps.
+      nextWaiter();
+      return;
+    }
+    this.verifierDerivationActive--;
+  }
+
+  /**
+   * Verify a presented plaintext password against a stored SCRAM verifier by
+   * deriving StoredKey from the presented password and comparing in constant
+   * time. PBKDF2 runs on the async crypto threadpool so caller-configured
+   * iteration counts never block the event loop inside the Rust auth
+   * callback window; iteration bounds are enforced at configuration time and
+   * in-flight derivations are bounded by a small semaphore.
+   */
+  private async verifyPasswordAgainstScramVerifier(
+    password: string,
+    verifier: ISmtpScramVerifier,
+  ): Promise<boolean> {
+    const acquired = await this.acquireVerifierDerivationSlot();
+    if (!acquired) {
+      logger.log(
+        'warn',
+        'SCRAM verifier derivation queue is saturated; failing authentication fast',
+      );
+      return false;
+    }
+    try {
+      const salt = Buffer.from(verifier.salt, 'base64');
+      const storedKey = Buffer.from(verifier.storedKey, 'base64');
+      const saltedPassword = await new Promise<Buffer>((resolve, reject) => {
+        plugins.crypto.pbkdf2(
+          password,
+          salt,
+          verifier.iterations,
+          32,
+          'sha256',
+          (error, derivedKey) => (error ? reject(error) : resolve(derivedKey)),
+        );
+      });
+      const clientKey = plugins.crypto.createHmac('sha256', saltedPassword)
+        .update('Client Key')
+        .digest();
+      const candidateStoredKey = plugins.crypto.createHash('sha256')
+        .update(clientKey)
+        .digest();
+      if (candidateStoredKey.length !== storedKey.length) {
+        return false;
+      }
+      return plugins.crypto.timingSafeEqual(candidateStoredKey, storedKey);
+    } catch {
+      return false;
+    } finally {
+      this.releaseVerifierDerivationSlot();
+    }
+  }
+
+  /** Constant-time string comparison for legacy plaintext credentials. */
+  private timingSafeStringEqual(left: string, right: string): boolean {
+    const leftBuffer = Buffer.from(left, 'utf8');
+    const rightBuffer = Buffer.from(right, 'utf8');
+    if (leftBuffer.length !== rightBuffer.length) {
+      // Burn comparable time so length mismatches are not a fast path.
+      plugins.crypto.timingSafeEqual(leftBuffer, leftBuffer);
+      return false;
+    }
+    return plugins.crypto.timingSafeEqual(leftBuffer, rightBuffer);
+  }
+
+  /**
+   * Handle an authRequest event from the Rust SMTP server (PLAIN/LOGIN).
+   * Accounts win over legacy users on username collision; disabled accounts
+   * always fail.
    */
   private async handleRustAuthRequest(data: IAuthRequestEvent): Promise<void> {
     const { correlationId, username, password, remoteAddr } = data;
 
     logger.log('info', `Rust SMTP auth request for user=${username} from=${remoteAddr}`);
 
-    // Check against configured users
-    const users = this.options.auth?.users || [];
-    const matched = users.find(
-      u => u.username === username && u.password === password
-    );
+    const account = this.findAuthAccount(username);
+    let success = false;
+    if (account) {
+      if (account.enabled === false) {
+        success = false;
+      } else if ('verifier' in account.credential) {
+        success = await this.verifyPasswordAgainstScramVerifier(password, account.credential.verifier);
+      } else {
+        success = this.timingSafeStringEqual(account.credential.password, password);
+      }
+    } else {
+      // Legacy users array keeps its existing behavior.
+      const users = this.options.auth?.users || [];
+      success = users.some(
+        u => u.username === username && u.password === password
+      );
+    }
 
-    if (matched) {
+    if (success) {
       await this.rustBridge.sendAuthResult({
         correlationId,
         success: true,
@@ -2528,14 +3003,43 @@ export class UnifiedEmailServer extends EventEmitter {
 
   /**
    * Handle a SCRAM credential request from the Rust SMTP server.
-   * Computes SCRAM-SHA-256 credentials from the stored password for the given user.
+   * Verifier accounts return their stored fields directly; plaintext
+   * credentials (accounts or legacy users) derive fields on the fly.
    */
   private async handleScramCredentialRequest(data: { correlationId: string; username: string; remoteAddr: string }): Promise<void> {
     const { correlationId, username, remoteAddr } = data;
-    const crypto = await import('crypto');
 
     logger.log('info', `SCRAM credential request for user=${username} from=${remoteAddr}`);
 
+    const account = this.findAuthAccount(username);
+    if (account) {
+      if (account.enabled === false) {
+        await this.rustBridge.sendScramCredentialResult({
+          correlationId,
+          found: false,
+        });
+        return;
+      }
+      if ('verifier' in account.credential) {
+        const { salt, iterations, storedKey, serverKey } = account.credential.verifier;
+        await this.rustBridge.sendScramCredentialResult({
+          correlationId,
+          found: true,
+          salt,
+          iterations,
+          storedKey,
+          serverKey,
+        });
+        return;
+      }
+      await this.rustBridge.sendScramCredentialResult({
+        correlationId,
+        found: true,
+        ...this.computeScramCredentials(account.credential.password),
+      });
+      return;
+    }
+
     const users = this.options.auth?.users || [];
     const matched = users.find(u => u.username === username);
 
@@ -2547,29 +3051,10 @@ export class UnifiedEmailServer extends EventEmitter {
       return;
     }
 
-    // Compute SCRAM-SHA-256 credentials from plaintext password
-    const salt = crypto.randomBytes(16);
-    const iterations = 4096;
-
-    // SaltedPassword = PBKDF2-HMAC-SHA256(password, salt, iterations, 32)
-    const saltedPassword = crypto.pbkdf2Sync(matched.password, salt, iterations, 32, 'sha256');
-
-    // ClientKey = HMAC-SHA256(SaltedPassword, "Client Key")
-    const clientKey = crypto.createHmac('sha256', saltedPassword).update('Client Key').digest();
-
-    // StoredKey = SHA256(ClientKey)
-    const storedKey = crypto.createHash('sha256').update(clientKey).digest();
-
-    // ServerKey = HMAC-SHA256(SaltedPassword, "Server Key")
-    const serverKey = crypto.createHmac('sha256', saltedPassword).update('Server Key').digest();
-
     await this.rustBridge.sendScramCredentialResult({
       correlationId,
       found: true,
-      salt: salt.toString('base64'),
-      iterations,
-      storedKey: storedKey.toString('base64'),
-      serverKey: serverKey.toString('base64'),
+      ...this.computeScramCredentials(matched.password),
     });
   }
 
@@ -2807,13 +3292,35 @@ export class UnifiedEmailServer extends EventEmitter {
     return routes;
   }
 
+  /**
+   * Server-level action policy for a single route. A `deliver` action is a
+   * terminal local delivery owned by the durable `hooks.onAcceptEnvelope`
+   * acceptance path; without that hook the route could only accept-then-fail,
+   * so it is rejected at configuration time instead.
+   */
+  private assertRouteActionServable(route: IEmailRoute): void {
+    if (
+      route.action.type === 'deliver'
+      && !this.options.hooks?.onAcceptEnvelope
+    ) {
+      throw new Error(
+        `Route ${route.name}: action type 'deliver' requires a configured hooks.onAcceptEnvelope durable local-delivery owner`,
+      );
+    }
+  }
+
   /**
    * Update server configuration
    */
   public updateOptions(options: Partial<IUnifiedEmailServerOptions>): void {
+    // Fail loudly before any option state is mutated.
+    if (options.auth) {
+      assertValidAuthAccounts(options.auth.accounts);
+    }
     const portsChanged = options.ports &&
       (!this.options.ports ||
        JSON.stringify(options.ports) !== JSON.stringify(this.options.ports));
+    const authEnabledBefore = this.isAuthConfigured(this.options);
 
     if (portsChanged) {
       this.stop().then(() => {
@@ -2821,7 +3328,21 @@ export class UnifiedEmailServer extends EventEmitter {
         this.start();
       });
     } else {
-      this.options = { ...this.options, ...options };
+      if (options.routes) {
+        // Validate synchronously against the incoming hook configuration
+        // before any option state is mutated, so invalid routes throw here
+        // instead of surfacing as an unhandled rejection.
+        const previousOptions = this.options;
+        this.options = { ...this.options, ...options };
+        try {
+          this.emailRouter.assertRoutesValid(options.routes);
+        } catch (error) {
+          this.options = previousOptions;
+          throw error;
+        }
+      } else {
+        this.options = { ...this.options, ...options };
+      }
 
       if (options.domains) {
         this.domainRegistry = new DomainRegistry(options.domains, options.defaults || this.options.defaults);
@@ -2830,6 +3351,26 @@ export class UnifiedEmailServer extends EventEmitter {
       if (options.routes) {
         this.emailRouter.updateRoutes(options.routes);
       }
+
+      if (options.auth) {
+        // Drop compiled patterns from replaced account configurations.
+        this.scopePatternCache.clear();
+      }
+
+      // AUTH availability is listener-level Rust configuration. When the
+      // auth presence transitions (zero -> first account/user or reverse)
+      // the running listener must be restarted for AUTH to take effect
+      // without a full process restart.
+      if (
+        options.auth
+        && this.smtpListenerActive
+        && !this.smtpListenerShutdown
+        && this.isAuthConfigured(this.options) !== authEnabledBefore
+      ) {
+        this.scheduleSmtpListenerRestart(
+          `SMTP AUTH ${this.isAuthConfigured(this.options) ? 'enabled' : 'disabled'} by configuration update`,
+        );
+      }
     }
   }
 
@@ -2837,6 +3378,8 @@ export class UnifiedEmailServer extends EventEmitter {
    * Update email routes
    */
   public updateEmailRoutes(routes: IEmailRoute[]): void {
+    // Fail loudly and synchronously before mutating server options.
+    this.emailRouter.assertRoutesValid(routes);
     this.options.routes = routes;
     this.emailRouter.updateRoutes(routes);
   }