@push.rocks/smartmta 9.5.0 → 9.6.0

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

@@ -28,6 +28,9 @@ import type {
   IEmailContext,
   IEmailDomainConfig,
   ISmtpAuthAccount,
+  ISmtpAuthAccountScope,
+  ISmtpAuthenticateContext,
+  ISmtpAuthenticateDecision,
   ISmtpScramVerifier,
 } from './interfaces.js';
 import { Email } from '../core/classes.email.js';
@@ -84,7 +87,8 @@ export type TRecipientRejectionReason =
   | 'policy-error'
   | 'sender-scope'
   | 'recipient-scope'
-  | 'account-disabled';
+  | 'account-disabled'
+  | 'auth-scope-expired';
 
 export interface IResolvedRecipientRoute {
   recipient: string;
@@ -398,6 +402,8 @@ export interface IUnifiedEmailServerOptions {
     tlsTerminatedPorts?: number[];
     /** Timeout for RCPT policy callbacks. Defaults to 5000 ms. */
     recipientValidationTimeoutMs?: number;
+    /** Timeout for `hooks.onAuthenticate` callbacks. Defaults to 5000 ms. */
+    authenticationTimeoutMs?: number;
     /** Timeout for message acceptance callbacks. Defaults to 30000 ms. */
     messageAcceptanceTimeoutMs?: number;
     /** Maximum complete messages concurrently held across Rust and TypeScript. */
@@ -410,6 +416,24 @@ export interface IUnifiedEmailServerOptions {
   };
 
   hooks?: {
+    /**
+     * Async credential verification for PLAIN/LOGIN, letting an embedding
+     * application own dynamic SMTP credentials that no static configuration
+     * can express.
+     *
+     * Consulted only for usernames that `auth.accounts` and `auth.users` do
+     * not declare: configuration always owns the usernames it lists, so a
+     * hook can never override or weaken a configured credential. Configuring
+     * the hook enables SMTP AUTH on the listener even with no accounts.
+     *
+     * The returned `scope` is enforced for that session exactly as a
+     * configured account's scope is. A throw or a
+     * `smtp.authenticationTimeoutMs` timeout fails the attempt closed.
+     *
+     * SCRAM cannot be served from this hook — see `onAuthenticate` notes in
+     * the readme. Hook-owned usernames authenticate over PLAIN/LOGIN only.
+     */
+    onAuthenticate?: (context: ISmtpAuthenticateContext) => Promise<ISmtpAuthenticateDecision>;
     /** 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` or `deliver` action. */
@@ -548,6 +572,31 @@ export class UnifiedEmailServer extends EventEmitter {
   private verifierDerivationWaiters: Array<() => void> = [];
   /** Compiled scope patterns; keys are config-supplied, bounded by config size. */
   private scopePatternCache: Map<string, RegExp> = new Map();
+  /**
+   * Scopes granted by `hooks.onAuthenticate`, keyed by the session the
+   * credential authenticated. The SMTP listener reports no session-close
+   * event, so entries are bounded by both a TTL and a hard cap rather than
+   * by session lifetime.
+   *
+   * Losing an entry must never widen a session, so the absence of a grant is
+   * not read as "unrestricted": a session authenticated as a username that
+   * configuration does not declare can only have come from the hook, and is
+   * refused with a temporary failure until it authenticates again.
+   */
+  private hookAuthenticatedSessions: Map<
+    string,
+    { username: string; scope?: ISmtpAuthAccountScope; expiresAt: number }
+  > = new Map();
+  private static readonly hookAuthSessionTtlMs = 60 * 60 * 1000;
+  private static readonly hookAuthSessionMax = 4096;
+  private static readonly hookAuthSweepInterval = 256;
+  private hookAuthSweepCountdown = UnifiedEmailServer.hookAuthSweepInterval;
+  /** The Rust listener's fixed AUTH round-trip deadline. */
+  private static readonly listenerAuthDeadlineMs = 5000;
+  /** Leave headroom so a hook answering just in time still beats the listener. */
+  private static readonly authHookMaxTimeoutMs = 4500;
+  private static readonly authHookDefaultTimeoutMs = 4000;
+  private loggedAuthTimeoutClamp = false;
 
   constructor(dcRouter: DcRouter, options: IUnifiedEmailServerOptions) {
     super();
@@ -568,113 +617,146 @@ export class UnifiedEmailServer extends EventEmitter {
     // 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();
+    // Subsystem construction below takes ownership of event-loop resources
+    // (the bounce manager and the rate limiter arm cleanup intervals in their
+    // constructors) while later steps still reject invalid configuration by
+    // throwing. A throwing constructor never returns an instance, so nothing
+    // can ever call stop() on it: construction is the only owner that can hand
+    // those resources back.
+    try {
+      // Initialize Rust security bridge (singleton)
+      this.rustBridge = RustSecurityBridge.getInstance();
 
-    // Initialize DKIM creator with storage manager
-    this.dkimCreator = new DKIMCreator(dcRouter.storageManager);
+      // Initialize DKIM creator with storage manager
+      this.dkimCreator = new DKIMCreator(dcRouter.storageManager);
 
-    // Initialize bounce manager with storage manager
-    this.bounceManager = new BounceManager({
-      maxCacheSize: 10000,
-      cacheTTL: 30 * 24 * 60 * 60 * 1000, // 30 days
-      storageManager: dcRouter.storageManager
-    });
+      // Initialize bounce manager with storage manager
+      this.bounceManager = new BounceManager({
+        maxCacheSize: 10000,
+        cacheTTL: 30 * 24 * 60 * 60 * 1000, // 30 days
+        storageManager: dcRouter.storageManager
+      });
 
-    // Initialize domain registry
-    this.domainRegistry = new DomainRegistry(options.domains, options.defaults);
+      // Initialize domain registry
+      this.domainRegistry = new DomainRegistry(options.domains, options.defaults);
 
-    // 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,
-      validateAction: (route) => this.assertRouteActionServable(route),
-    });
+      // 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,
+        validateAction: (route) => this.assertRouteActionServable(route),
+      });
 
-    // Initialize rate limiter
-    this.rateLimiter = new UnifiedRateLimiter(options.rateLimits || {
-      global: {
-        maxConnectionsPerIP: 10,
-        maxMessagesPerMinute: 100,
-        maxRecipientsPerMessage: 50,
-        maxErrorsPerIP: 10,
-        maxAuthFailuresPerIP: 5,
-        blockDuration: 300000 // 5 minutes
-      }
-    });
+      // Initialize rate limiter
+      this.rateLimiter = new UnifiedRateLimiter(options.rateLimits || {
+        global: {
+          maxConnectionsPerIP: 10,
+          maxMessagesPerMinute: 100,
+          maxRecipientsPerMessage: 50,
+          maxErrorsPerIP: 10,
+          maxAuthFailuresPerIP: 5,
+          blockDuration: 300000 // 5 minutes
+        }
+      });
 
-    // Initialize delivery components
-    const queueOptions: IQueueOptions = {
-      maxRetries: 3,
-      baseRetryDelay: 300000, // 5 minutes
-      maxRetryDelay: 3600000, // 1 hour
-      ...options.queue,
-    };
+      // Initialize delivery components
+      const queueOptions: IQueueOptions = {
+        maxRetries: 3,
+        baseRetryDelay: 300000, // 5 minutes
+        maxRetryDelay: 3600000, // 1 hour
+        ...options.queue,
+      };
 
-    this.deliveryQueue = new UnifiedDeliveryQueue(queueOptions);
-
-    const deliveryOptions: IMultiModeDeliveryOptions = {
-      globalRateLimit: 100, // Default to 100 emails per minute
-      concurrentDeliveries: 10,
-      processBounces: true,
-      bounceHandler: {
-        processSmtpFailure: async (recipient, smtpResponse, failureOptions) => {
-          const processed = await this.processSmtpFailure(
-            recipient,
-            smtpResponse,
-            failureOptions,
-          );
-          if (!processed) {
-            throw new Error(`SMTP bounce operation failed for ${recipient}`);
-          }
+      this.deliveryQueue = new UnifiedDeliveryQueue(queueOptions);
+
+      const deliveryOptions: IMultiModeDeliveryOptions = {
+        globalRateLimit: 100, // Default to 100 emails per minute
+        concurrentDeliveries: 10,
+        processBounces: true,
+        bounceHandler: {
+          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
-      }
-    };
+        onDeliverySuccess: async (_item, _result) => {
+          // Delivery success recorded via delivery system
+        }
+      };
 
-    this.deliverySystem = new MultiModeDeliverySystem(this.deliveryQueue, deliveryOptions, this);
+      this.deliverySystem = new MultiModeDeliverySystem(this.deliveryQueue, deliveryOptions, this);
 
-    // Initialize action executor
-    this.actionExecutor = new EmailActionExecutor({
-      sendOutboundEmail: this.sendOutboundEmail.bind(this),
-      bounceManager: this.bounceManager,
-      deliveryQueue: this.deliveryQueue,
-    });
+      // Initialize action executor
+      this.actionExecutor = new EmailActionExecutor({
+        sendOutboundEmail: this.sendOutboundEmail.bind(this),
+        bounceManager: this.bounceManager,
+        deliveryQueue: this.deliveryQueue,
+      });
 
-    // Initialize DKIM manager
-    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 = {
-      startTime: new Date(),
-      connections: {
-        current: 0,
-        total: 0
-      },
-      messages: {
-        processed: 0,
-        delivered: 0,
-        failed: 0
-      },
-      processingTime: {
-        avg: 0,
-        max: 0,
-        min: 0
+      // Initialize DKIM manager
+      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 = {
+        startTime: new Date(),
+        connections: {
+          current: 0,
+          total: 0
+        },
+        messages: {
+          processed: 0,
+          delivered: 0,
+          failed: 0
+        },
+        processingTime: {
+          avg: 0,
+          max: 0,
+          min: 0
+        }
+      };
+
+      // We'll create the SMTP servers during the start() method
+    } catch (error) {
+      this.releaseConstructionOwnedResources();
+      throw error;
+    }
+  }
+
+  /**
+   * Hand back every event-loop resource a partially completed construction has
+   * already taken ownership of, so a rejected configuration leaves the process
+   * exactly as it found it.
+   *
+   * Only construction-time owners belong here: the delivery queue and the
+   * delivery system arm their timers in `initialize()` and `start()`, which a
+   * failed construction never reaches, and the Rust bridge is an unstarted
+   * singleton until `start()` spawns it.
+   */
+  private releaseConstructionOwnedResources(): void {
+    const release = (nameArg: string, stepArg: () => void): void => {
+      try {
+        stepArg();
+      } catch (error) {
+        logger.log('warn', `${nameArg}: ${getErrorMessage(error)}`);
       }
     };
-
-    // We'll create the SMTP servers during the start() method
+    release('bounce-manager release after failed construction', () => this.bounceManager?.stop());
+    release('rate-limiter release after failed construction', () => this.rateLimiter?.stop());
   }
 
   private assertAcceptingOutboundWork(): void {
@@ -1604,11 +1686,16 @@ export class UnifiedEmailServer extends EventEmitter {
     return resolved;
   }
 
-  /** Whether the current options require SMTP AUTH support on the listener. */
+  /**
+   * Whether the current options require SMTP AUTH support on the listener.
+   * A configured `hooks.onAuthenticate` counts on its own: its whole purpose
+   * is to own credentials that no static account list contains.
+   */
   private isAuthConfigured(options: IUnifiedEmailServerOptions): boolean {
     return !!options.auth?.required
       || !!options.auth?.users?.length
-      || !!options.auth?.accounts?.length;
+      || !!options.auth?.accounts?.length
+      || !!options.hooks?.onAuthenticate;
   }
 
   /**
@@ -1833,6 +1920,7 @@ export class UnifiedEmailServer extends EventEmitter {
       context.authenticatedUser,
       context.mailFrom,
       context.rcptTo,
+      context.sessionId,
     );
     if (scopeViolation) {
       const scopeRecipientDomain = this.getAddressDomain(context.rcptTo);
@@ -2116,6 +2204,115 @@ export class UnifiedEmailServer extends EventEmitter {
     );
   }
 
+  /** Whether the legacy `auth.users` array declares this username. */
+  private hasLegacyAuthUser(username: string): boolean {
+    return (this.options.auth?.users || []).some((user) => user.username === username);
+  }
+
+  /**
+   * Whether configuration claims this username, for the purpose of deciding
+   * that `hooks.onAuthenticate` must not see it.
+   *
+   * Deliberately case-insensitive, while credential verification itself stays
+   * exact. Otherwise `Tenant-A` would slip past an operator's configured
+   * `tenant-a` — including a `tenant-a` the operator had set `enabled: false`
+   * — and reach a hook that may well resolve names case-insensitively.
+   * Configuration owning a name means owning every casing of it: a casing that
+   * matches no exact credential simply fails, and never reaches the hook.
+   */
+  private declaresUsername(username: string): boolean {
+    const normalized = username.toLowerCase();
+    const accounts = this.options.auth?.accounts || [];
+    if (accounts.some((account) => account.username.toLowerCase() === normalized)) return true;
+    const users = this.options.auth?.users || [];
+    return users.some((user) => user.username.toLowerCase() === normalized);
+  }
+
+  /**
+   * Hook timeout, clamped below the Rust listener's own AUTH deadline.
+   *
+   * The listener waits a fixed 5 s for the TypeScript answer
+   * (`rust/crates/mailer-smtp/src/connection.rs`), so a larger value here
+   * could never take effect: the listener would already have failed the
+   * attempt and reset the session while the hook was still running. Clamping
+   * keeps the configured number meaningful instead of silently unreachable.
+   */
+  private getAuthenticationTimeoutMs(): number {
+    const configured = this.options.smtp?.authenticationTimeoutMs;
+    if (!configured) return UnifiedEmailServer.authHookDefaultTimeoutMs;
+    if (configured <= UnifiedEmailServer.authHookMaxTimeoutMs) return configured;
+    if (!this.loggedAuthTimeoutClamp) {
+      this.loggedAuthTimeoutClamp = true;
+      logger.log(
+        'warn',
+        `smtp.authenticationTimeoutMs ${configured} exceeds the SMTP listener's `
+          + `${UnifiedEmailServer.listenerAuthDeadlineMs}ms AUTH deadline; `
+          + `clamping to ${UnifiedEmailServer.authHookMaxTimeoutMs}ms`,
+      );
+    }
+    return UnifiedEmailServer.authHookMaxTimeoutMs;
+  }
+
+  /**
+   * Enforce the hard cap oldest-first, and sweep expired grants periodically.
+   *
+   * The cap is what bounds memory, and it is O(1) amortised because Map
+   * preserves insertion order. The TTL sweep is hygiene on top — expiry is
+   * always enforced on read — so it runs every `hookAuthSweepInterval`
+   * insertions rather than walking the whole table on every authentication.
+   */
+  private pruneHookAuthSessions(): void {
+    while (this.hookAuthenticatedSessions.size > UnifiedEmailServer.hookAuthSessionMax) {
+      const oldest = this.hookAuthenticatedSessions.keys().next();
+      if (oldest.done) break;
+      this.hookAuthenticatedSessions.delete(oldest.value);
+    }
+    this.hookAuthSweepCountdown -= 1;
+    if (this.hookAuthSweepCountdown > 0) return;
+    this.hookAuthSweepCountdown = UnifiedEmailServer.hookAuthSweepInterval;
+    const now = Date.now();
+    for (const [sessionId, grant] of this.hookAuthenticatedSessions) {
+      if (grant.expiresAt <= now) {
+        this.hookAuthenticatedSessions.delete(sessionId);
+      }
+    }
+  }
+
+  /** Record the scope a hook granted, replacing any earlier grant for the session. */
+  private rememberHookAuthGrant(
+    sessionId: string,
+    username: string,
+    scope: ISmtpAuthAccountScope | undefined,
+  ): void {
+    this.hookAuthenticatedSessions.delete(sessionId);
+    this.hookAuthenticatedSessions.set(sessionId, {
+      username,
+      scope,
+      expiresAt: Date.now() + UnifiedEmailServer.hookAuthSessionTtlMs,
+    });
+    this.pruneHookAuthSessions();
+  }
+
+  /**
+   * Live hook grant for a session, or undefined when none is held. The
+   * username must match the grant: a session may not present one username to
+   * the listener and inherit another's scope.
+   */
+  private findHookAuthGrant(
+    sessionId: string | null | undefined,
+    username: string,
+  ): { username: string; scope?: ISmtpAuthAccountScope } | undefined {
+    if (!sessionId) return undefined;
+    const grant = this.hookAuthenticatedSessions.get(sessionId);
+    if (!grant) return undefined;
+    if (grant.expiresAt <= Date.now()) {
+      this.hookAuthenticatedSessions.delete(sessionId);
+      return undefined;
+    }
+    if (grant.username !== username) return undefined;
+    return grant;
+  }
+
   private normalizeScopeAddress(addressArg: string | null | undefined): string {
     return (addressArg || '').trim().replace(/^<|>$/g, '').toLowerCase();
   }
@@ -2144,16 +2341,25 @@ export class UnifiedEmailServer extends EventEmitter {
   /**
    * 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).
+   * no configured account and no `hooks.onAuthenticate`, and accounts without
+   * a scope are unrestricted).
    */
   private resolveAuthAccountScopeDecision(
     authenticatedUser: string | null,
     mailFrom: string,
     rcptTo: string,
+    sessionId?: string | null,
   ): { decision: ISmtpDecision; rejectionReason: TRecipientRejectionReason } | null {
     if (!authenticatedUser) return null;
     const account = this.findAuthAccount(authenticatedUser);
-    if (!account) return null;
+    if (!account) {
+      return this.resolveHookAuthScopeDecision(
+        authenticatedUser,
+        mailFrom,
+        rcptTo,
+        sessionId,
+      );
+    }
     if (account.enabled === false) {
       // The account was disabled after authentication succeeded; the session
       // must not be able to send anything.
@@ -2166,7 +2372,53 @@ export class UnifiedEmailServer extends EventEmitter {
         rejectionReason: 'account-disabled',
       };
     }
-    const scope = account.scope;
+    return this.applyScopeToEnvelope(account.scope, authenticatedUser, mailFrom, rcptTo);
+  }
+
+  /**
+   * Envelope-level scope decision for a session authenticated by
+   * `hooks.onAuthenticate`. Reached only for usernames no configured account
+   * declares, so when a hook is configured the session must hold a live
+   * grant; a missing grant is refused temporarily rather than treated as
+   * unrestricted. With no hook configured the pre-existing behaviour stands:
+   * legacy users and unknown usernames are unscoped.
+   */
+  private resolveHookAuthScopeDecision(
+    authenticatedUser: string,
+    mailFrom: string,
+    rcptTo: string,
+    sessionId?: string | null,
+  ): { decision: ISmtpDecision; rejectionReason: TRecipientRejectionReason } | null {
+    const resolved = this.resolveSessionSenderScope(authenticatedUser, sessionId);
+    if (resolved.kind === 'unrestricted') return null;
+    if (resolved.kind === 'refused') {
+      return {
+        decision: UnifiedEmailServer.authScopeUnavailableDecision(),
+        rejectionReason: 'auth-scope-expired',
+      };
+    }
+    return this.applyScopeToEnvelope(resolved.scope, authenticatedUser, mailFrom, rcptTo);
+  }
+
+  /** Temporary refusal for a session whose hook grant is not available. */
+  private static authScopeUnavailableDecision(): ISmtpDecision {
+    return {
+      accepted: false,
+      smtpCode: 451,
+      smtpMessage: '4.7.1 Authentication scope unavailable; authenticate again',
+    };
+  }
+
+  /**
+   * Shared sender/recipient scope enforcement. An absent scope is
+   * unrestricted, matching `ISmtpAuthAccount.scope`.
+   */
+  private applyScopeToEnvelope(
+    scope: ISmtpAuthAccountScope | undefined,
+    authenticatedUser: string,
+    mailFrom: string,
+    rcptTo: string,
+  ): { decision: ISmtpDecision; rejectionReason: TRecipientRejectionReason } | null {
     if (!scope) return null;
     if (!this.matchesScopePatterns(mailFrom, scope.senders)) {
       return {
@@ -2194,6 +2446,34 @@ export class UnifiedEmailServer extends EventEmitter {
     return null;
   }
 
+  /**
+   * Sender scope in force for a session.
+   *
+   * The three outcomes are kept distinct on purpose. Collapsing `refused` into
+   * "no scope" would make a session whose hook grant is gone look unrestricted
+   * to any caller that only asks "is there a scope?", which is the opposite of
+   * what a missing grant means.
+   */
+  private resolveSessionSenderScope(
+    username: string,
+    sessionId?: string | null,
+  ):
+    | { kind: 'unrestricted' }
+    | { kind: 'scope'; scope: ISmtpAuthAccountScope }
+    | { kind: 'refused' } {
+    const account = this.findAuthAccount(username);
+    if (account) {
+      if (account.enabled === false || !account.scope) return { kind: 'unrestricted' };
+      return { kind: 'scope', scope: account.scope };
+    }
+    if (!this.options.hooks?.onAuthenticate) return { kind: 'unrestricted' };
+    // Legacy users and other configuration-owned names are unscoped by design.
+    if (this.declaresUsername(username)) return { kind: 'unrestricted' };
+    const grant = this.findHookAuthGrant(sessionId, username);
+    if (!grant) return { kind: 'refused' };
+    return grant.scope ? { kind: 'scope', scope: grant.scope } : { kind: 'unrestricted' };
+  }
+
   /**
    * Extract every mailbox address from the parsed From header. The Email
    * abstraction keeps only the first From mailbox, which is not sufficient
@@ -2227,10 +2507,15 @@ export class UnifiedEmailServer extends EventEmitter {
   ): 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;
+    // resolveRecipientPolicy; this check adds header alignment, for configured
+    // accounts and hook grants alike. A session whose hook grant is gone is
+    // refused here in its own right rather than relying on the envelope check
+    // having run first.
+    const resolved = this.resolveSessionSenderScope(username, session.id);
+    if (resolved.kind === 'unrestricted') return null;
+    if (resolved.kind === 'refused') return UnifiedEmailServer.authScopeUnavailableDecision();
+    const scope = resolved.scope;
     let fromMailboxes: string[];
     try {
       fromMailboxes = await this.parseHeaderFromMailboxes(rawMessage);
@@ -2243,7 +2528,7 @@ export class UnifiedEmailServer extends EventEmitter {
       fromMailboxes = [email.getFromAddress()];
     }
     const outOfScope = fromMailboxes.find(
-      (mailbox) => !this.matchesScopePatterns(mailbox, account.scope!.senders),
+      (mailbox) => !this.matchesScopePatterns(mailbox, scope.senders),
     );
     if (outOfScope === undefined) {
       return null;
@@ -3419,12 +3704,13 @@ export class UnifiedEmailServer extends EventEmitter {
    * always fail.
    */
   private async handleRustAuthRequest(data: IAuthRequestEvent): Promise<void> {
-    const { correlationId, username, password, remoteAddr } = data;
+    const { correlationId, sessionId, username, password, remoteAddr } = data;
 
     logger.log('info', `Rust SMTP auth request for user=${username} from=${remoteAddr}`);
 
     const account = this.findAuthAccount(username);
     let success = false;
+    let failureMessage: string | undefined;
     if (account) {
       if (account.enabled === false) {
         success = false;
@@ -3433,12 +3719,27 @@ export class UnifiedEmailServer extends EventEmitter {
       } else {
         success = this.timingSafeStringEqual(account.credential.password, password);
       }
-    } else {
+    } else if (this.hasLegacyAuthUser(username)) {
       // Legacy users array keeps its existing behavior.
       const users = this.options.auth?.users || [];
       success = users.some(
         u => u.username === username && u.password === password
       );
+    } else if (this.options.hooks?.onAuthenticate && !this.declaresUsername(username)) {
+      // Only usernames configuration does not declare reach the hook. A casing
+      // variant of a configured name is owned by configuration too, so it
+      // falls through here and fails rather than reaching the hook.
+      const outcome = await this.runHookAuthentication({
+        username,
+        password,
+        sessionId,
+        remoteAddress: remoteAddr,
+      });
+      success = outcome.accepted;
+      failureMessage = outcome.message;
+      if (outcome.accepted) {
+        this.rememberHookAuthGrant(sessionId, username, outcome.scope);
+      }
     }
 
     if (success) {
@@ -3447,19 +3748,62 @@ export class UnifiedEmailServer extends EventEmitter {
         success: true,
       });
     } else {
-      logger.log('warn', `Auth failed for user=${username} from=${remoteAddr}`);
+      // The listener answers every failed AUTH with the same 535, so a hook's
+      // reason is recorded here rather than disclosed to the client.
+      logger.log(
+        'warn',
+        `Auth failed for user=${username} from=${remoteAddr}`
+          + (failureMessage ? `: ${failureMessage}` : ''),
+      );
       await this.rustBridge.sendAuthResult({
         correlationId,
         success: false,
-        message: 'Invalid credentials',
+        message: failureMessage || 'Invalid credentials',
       });
     }
   }
 
+  /**
+   * Run `hooks.onAuthenticate` under the configured timeout. Any throw, any
+   * timeout and any non-object result fail the attempt closed — an embedder
+   * that cannot answer must never widen access.
+   */
+  private async runHookAuthentication(
+    context: Omit<ISmtpAuthenticateContext, 'abortSignal'>,
+  ): Promise<ISmtpAuthenticateDecision> {
+    try {
+      const decision = await this.runHookWithTimeout(
+        this.getAuthenticationTimeoutMs(),
+        'Authentication hook timeout',
+        (abortSignal) => this.options.hooks!.onAuthenticate!({ ...context, abortSignal }),
+      );
+      if (!decision || typeof decision !== 'object') {
+        logger.log(
+          'error',
+          `Authentication hook returned no decision for user=${context.username}`,
+        );
+        return { accepted: false };
+      }
+      return decision;
+    } catch (error) {
+      logger.log(
+        'error',
+        `Authentication hook failed for user=${context.username}: ${getErrorMessage(error)}`,
+      );
+      return { accepted: false };
+    }
+  }
+
   /**
    * Handle a SCRAM credential request from the Rust SMTP server.
    * Verifier accounts return their stored fields directly; plaintext
    * credentials (accounts or legacy users) derive fields on the fly.
+   *
+   * Usernames owned by `hooks.onAuthenticate` fall through to `found: false`:
+   * SCRAM requires the server to hold the salt, iteration count, stored key
+   * and server key, and a hook that verifies an opaque credential (argon2id,
+   * a remote authority) cannot produce them. Those usernames authenticate
+   * over PLAIN/LOGIN only, which is why the hook receives the password.
    */
   private async handleScramCredentialRequest(data: { correlationId: string; username: string; remoteAddr: string }): Promise<void> {
     const { correlationId, username, remoteAddr } = data;