@push.rocks/smartmta 8.1.0 → 8.1.1

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

@@ -19,14 +19,25 @@ import type {
   IScramCredentialRequestEvent,
 } from '../../security/classes.rustsecuritybridge.js';
 import { EmailRouter } from './classes.email.router.js';
-import type { IEmailRoute, IEmailContext, IEmailDomainConfig } from './interfaces.js';
+import type {
+  IEmailRoute,
+  IEmailAction,
+  IEmailContext,
+  IEmailDomainConfig,
+} from './interfaces.js';
 import { Email } from '../core/classes.email.js';
 import { DomainRegistry } from './classes.domain.registry.js';
 import { DnsManager } from './classes.dns.manager.js';
 import { BounceManager, BounceType, BounceCategory } from '../core/classes.bouncemanager.js';
 import type { ISmtpSendResult, IOutboundEmail } from '../../security/classes.rustsecuritybridge.js';
 import { MultiModeDeliverySystem, type IDeliveryStats, type IMultiModeDeliveryOptions } from '../delivery/classes.delivery.system.js';
-import { UnifiedDeliveryQueue, type IQueueItem, type IQueueOptions, type IQueueStats } from '../delivery/classes.delivery.queue.js';
+import {
+  ACCEPTED_ENVELOPE_IDEMPOTENCY_RETENTION_MS,
+  UnifiedDeliveryQueue,
+  type IQueueItem,
+  type IQueueOptions,
+  type IQueueStats,
+} from '../delivery/classes.delivery.queue.js';
 import { UnifiedRateLimiter, type IHierarchicalRateLimits } from '../delivery/classes.unified.rate.limiter.js';
 import { SmtpState } from '../delivery/interfaces.js';
 import type { EmailProcessingMode, ISmtpSession as IBaseSmtpSession } from '../delivery/interfaces.js';
@@ -142,6 +153,74 @@ export interface IAcceptEnvelopeContext {
   securityResults: IInboundEmailSecurityResult | null;
 }
 
+/**
+ * JSON-safe, immutable snapshot of one accepted envelope recipient's exact
+ * routing decision. The snapshot is safe to persist and replay without
+ * consulting the live route table.
+ */
+export interface IAcceptedEnvelopeRecipientPlan {
+  readonly recipient: string;
+  readonly localDomain: string | null;
+  readonly routeName: string;
+  readonly source: TRecipientRouteSource;
+  readonly action: IEmailAction;
+  readonly idempotencyKey: string;
+}
+
+/** Serializable SMTP metadata needed to recreate an isolated action session. */
+export interface IAcceptedEnvelopeDispatchMetadata {
+  readonly mailFrom: string;
+  readonly session?: {
+    readonly id?: string;
+    readonly remoteAddress?: string;
+    readonly clientHostname?: string;
+    readonly secure?: boolean;
+    readonly authenticated?: boolean;
+    readonly authenticatedUser?: string | null;
+    readonly user?: Readonly<{
+      username: string;
+      [key: string]: unknown;
+    }>;
+  };
+}
+
+export type TAcceptedEnvelopeRecipientDispatchStatus =
+  | 'stored'
+  | 'queued'
+  | 'rejected'
+  | 'failed';
+
+export interface IAcceptedEnvelopeRecipientDispatchResult {
+  recipient: string;
+  localDomain: string | null;
+  routeName: string;
+  source: TRecipientRouteSource;
+  actionType: IEmailAction['type'];
+  idempotencyKey: string;
+  status: TAcceptedEnvelopeRecipientDispatchStatus;
+  replayed: boolean;
+  queueId?: string;
+  smtpCode?: number;
+  message?: string;
+}
+
+export interface IAcceptedEnvelopeDispatchResult {
+  complete: boolean;
+  results: IAcceptedEnvelopeRecipientDispatchResult[];
+}
+
+interface IStoredAcceptedEnvelopeDispatchResult {
+  schemaVersion: 1;
+  fingerprint: string;
+  expiresAt: number;
+  result: Omit<IAcceptedEnvelopeRecipientDispatchResult, 'replayed'>;
+}
+
+const ACCEPTED_ENVELOPE_DISPATCH_STORAGE_PREFIX =
+  '/email/accepted-envelope-dispatch/v1/';
+const ACCEPTED_ENVELOPE_DISPATCH_CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+const ACCEPTED_ENVELOPE_DISPATCH_CLEANUP_LIMIT = 256;
+
 export interface IMessageAcceptanceDecision extends ISmtpDecision {
   /** Continue SmartMTA's built-in route processing after the consumer accepted responsibility. */
   continueProcessing?: boolean;
@@ -359,6 +438,9 @@ export class UnifiedEmailServer extends EventEmitter {
   private bridgeEmailReceivedHandler?: (data: IEmailReceivedEvent) => void;
   private bridgeAuthRequestHandler?: (data: IAuthRequestEvent) => void;
   private bridgeScramCredentialRequestHandler?: (data: IScramCredentialRequestEvent) => void;
+  private acceptedEnvelopeDispatchCleanupTimer?: ReturnType<typeof setInterval>;
+  private acceptedEnvelopeDispatchCleanupPromise?: Promise<void>;
+  private acceptedEnvelopeDispatchCleanupCursor?: string;
 
   constructor(dcRouter: DcRouter, options: IUnifiedEmailServerOptions) {
     super();
@@ -824,6 +906,7 @@ export class UnifiedEmailServer extends EventEmitter {
 
     try {
       await this.startDeliveryPipeline();
+      this.startAcceptedEnvelopeDispatchCleanup();
       await this.startRustBridge();
       await this.initializeDkimAndDns();
       await this.startDeliveryProcessing();
@@ -1096,6 +1179,11 @@ export class UnifiedEmailServer extends EventEmitter {
     logger.log('info', 'Stopping UnifiedEmailServer');
 
     try {
+      if (this.acceptedEnvelopeDispatchCleanupTimer) {
+        clearInterval(this.acceptedEnvelopeDispatchCleanupTimer);
+        this.acceptedEnvelopeDispatchCleanupTimer = undefined;
+      }
+      await this.acceptedEnvelopeDispatchCleanupPromise;
       await this.stopDnsValidation();
 
       // Stop the Rust SMTP server first
@@ -1448,12 +1536,17 @@ export class UnifiedEmailServer extends EventEmitter {
       subject: email.subject,
       text: email.text,
       html: email.html,
-      attachments: email.attachments,
+      attachments: email.attachments.map((attachment) => ({
+        ...attachment,
+        content: Buffer.from(attachment.content),
+      })),
       headers: { ...email.headers },
       mightBeSpam: email.mightBeSpam,
       priority: email.priority,
-      variables: { ...email.variables },
-    });
+      variables: structuredClone(email.variables),
+    })
+      .setMessageId(email.getMessageId())
+      .setEnvelopeFrom(email.getEnvelopeFrom());
   }
 
   private scopeSessionForRoutingRecipient(
@@ -1462,6 +1555,10 @@ export class UnifiedEmailServer extends EventEmitter {
   ): IExtendedSmtpSession {
     return {
       ...session,
+      ...(session.user ? { user: structuredClone(session.user) } : {}),
+      ...(session.securityResults
+        ? { securityResults: structuredClone(session.securityResults) }
+        : {}),
       rcptTo: [recipient],
       envelope: {
         mailFrom: { ...session.envelope.mailFrom },
@@ -1562,6 +1659,571 @@ export class UnifiedEmailServer extends EventEmitter {
     );
   }
 
+  private cloneJsonSafe<T>(
+    value: T,
+    path = 'value',
+    seen = new WeakSet<object>(),
+  ): T {
+    if (
+      value === null
+      || typeof value === 'string'
+      || typeof value === 'boolean'
+    ) {
+      return value;
+    }
+    if (typeof value === 'number') {
+      if (!Number.isFinite(value)) {
+        throw new Error(`${path} must contain only finite JSON numbers`);
+      }
+      return value;
+    }
+    if (Array.isArray(value)) {
+      if (Object.getPrototypeOf(value) !== Array.prototype) {
+        throw new Error(`${path} must use the standard Array prototype`);
+      }
+      if (seen.has(value)) {
+        throw new Error(`${path} must not contain circular references`);
+      }
+      seen.add(value);
+      const ownKeys = Reflect.ownKeys(value);
+      if (ownKeys.some((key) => typeof key === 'symbol')) {
+        throw new Error(`${path} must not contain symbol keys`);
+      }
+      const elementKeys = ownKeys.filter((key) => key !== 'length') as string[];
+      if (
+        elementKeys.length !== value.length
+        || elementKeys.some((key, index) => key !== String(index))
+      ) {
+        throw new Error(`${path} must be a dense JSON array without custom keys`);
+      }
+      const clone: unknown[] = [];
+      for (let index = 0; index < value.length; index++) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (!descriptor?.enumerable || !('value' in descriptor)) {
+          throw new Error(`${path}[${index}] must be an enumerable data property`);
+        }
+        clone.push(this.cloneJsonSafe(
+          descriptor.value,
+          `${path}[${index}]`,
+          seen,
+        ));
+      }
+      seen.delete(value);
+      return Object.freeze(clone) as T;
+    }
+    if (typeof value === 'object') {
+      const prototype = Object.getPrototypeOf(value);
+      if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error(`${path} must contain only JSON-safe plain objects`);
+      }
+      if (seen.has(value)) {
+        throw new Error(`${path} must not contain circular references`);
+      }
+      seen.add(value);
+      const ownKeys = Reflect.ownKeys(value);
+      if (ownKeys.some((key) => typeof key === 'symbol')) {
+        throw new Error(`${path} must not contain symbol keys`);
+      }
+      const clone = Object.create(null) as Record<string, unknown>;
+      for (const key of ownKeys as string[]) {
+        if (key === '__proto__') {
+          throw new Error(`${path} must not contain __proto__ keys`);
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable || !('value' in descriptor)) {
+          throw new Error(`${path}.${key} must be an enumerable data property`);
+        }
+        if (descriptor.value === undefined) {
+          throw new Error(`${path}.${key} must not be undefined`);
+        }
+        clone[key] = this.cloneJsonSafe(
+          descriptor.value,
+          `${path}.${key}`,
+          seen,
+        );
+      }
+      seen.delete(value);
+      return Object.freeze(clone) as T;
+    }
+    throw new Error(`${path} contains a non-JSON-safe value`);
+  }
+
+  private stableJson(value: unknown): string {
+    if (value === null || typeof value !== 'object') return JSON.stringify(value);
+    if (Array.isArray(value)) {
+      return `[${value.map((entry) => this.stableJson(entry)).join(',')}]`;
+    }
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${this.stableJson(record[key])}`)
+      .join(',')}}`;
+  }
+
+  private validateAcceptedEnvelopeAction(
+    action: IEmailAction,
+    path: string,
+  ): void {
+    if (!['forward', 'deliver', 'reject', 'process', 'store'].includes(action.type)) {
+      throw new Error(`${path}.type is unsupported`);
+    }
+    if (action.type === 'forward') {
+      if (!action.forward?.host?.trim()) {
+        throw new Error(`${path}.forward.host is required`);
+      }
+      if (
+        action.forward.port !== undefined
+        && (
+          !Number.isInteger(action.forward.port)
+          || action.forward.port < 1
+          || action.forward.port > 65_535
+        )
+      ) {
+        throw new Error(`${path}.forward.port is invalid`);
+      }
+    }
+    if (action.type === 'store') {
+      if (
+        !Number.isInteger(action.store?.retentionDays)
+        || (action.store?.retentionDays || 0) < 1
+      ) {
+        throw new Error(`${path}.store.retentionDays must be a positive integer`);
+      }
+    }
+    if (action.type === 'reject') {
+      if (
+        !Number.isInteger(action.reject?.code)
+        || (action.reject?.code || 0) < 400
+        || (action.reject?.code || 0) > 599
+        || !action.reject?.message?.trim()
+      ) {
+        throw new Error(`${path}.reject must contain a 4xx/5xx code and message`);
+      }
+    }
+  }
+
+  private normalizeAcceptedEnvelopePlan(
+    plan: readonly IAcceptedEnvelopeRecipientPlan[],
+  ): readonly IAcceptedEnvelopeRecipientPlan[] {
+    if (!Array.isArray(plan) || plan.length === 0) {
+      throw new Error('Accepted envelope dispatch plan must contain at least one recipient');
+    }
+    const keys = new Set<string>();
+    const normalized = plan.map((entry, index) => {
+      const path = `plan[${index}]`;
+      if (!entry || typeof entry !== 'object') {
+        throw new Error(`${path} must be an object`);
+      }
+      const atIndex = entry.recipient?.lastIndexOf('@') ?? -1;
+      if (
+        !entry.recipient?.trim()
+        || atIndex < 1
+        || atIndex === entry.recipient.length - 1
+      ) {
+        throw new Error(`${path}.recipient is invalid`);
+      }
+      if (entry.localDomain !== null && !entry.localDomain?.trim()) {
+        throw new Error(`${path}.localDomain is invalid`);
+      }
+      if (!entry.routeName?.trim()) {
+        throw new Error(`${path}.routeName is required`);
+      }
+      if (!['explicit-route', 'domain-policy'].includes(entry.source)) {
+        throw new Error(`${path}.source cannot represent an accepted route`);
+      }
+      if (!entry.idempotencyKey || entry.idempotencyKey.length > 512) {
+        throw new Error(`${path}.idempotencyKey must contain 1 to 512 characters`);
+      }
+      if (keys.has(entry.idempotencyKey)) {
+        throw new Error(`${path}.idempotencyKey is duplicated`);
+      }
+      keys.add(entry.idempotencyKey);
+      const action = this.cloneJsonSafe(entry.action, `${path}.action`);
+      this.validateAcceptedEnvelopeAction(action, `${path}.action`);
+      return Object.freeze({
+        recipient: entry.recipient,
+        localDomain: entry.localDomain,
+        routeName: entry.routeName,
+        source: entry.source,
+        action,
+        idempotencyKey: entry.idempotencyKey,
+      });
+    });
+    return Object.freeze(normalized);
+  }
+
+  /**
+   * Snapshot the already-resolved acceptance plan for durable consumer storage.
+   * No live route lookup is performed when the returned plan is dispatched.
+   */
+  public createAcceptedEnvelopeDispatchPlan(
+    context: IAcceptEnvelopeContext,
+    idempotencyKeys: readonly string[],
+  ): readonly IAcceptedEnvelopeRecipientPlan[] {
+    if (context.resolvedRecipientRoutes.length !== idempotencyKeys.length) {
+      throw new Error('One idempotency key is required for every resolved recipient route');
+    }
+    return this.normalizeAcceptedEnvelopePlan(
+      context.resolvedRecipientRoutes.map((resolution, index) => {
+        if (!resolution.route) {
+          throw new Error(
+            `Accepted recipient ${resolution.recipient} has no resolved route action`,
+          );
+        }
+        return {
+          recipient: resolution.recipient,
+          localDomain: resolution.localDomain,
+          routeName: resolution.route.name,
+          source: resolution.source,
+          action: resolution.route.action,
+          idempotencyKey: idempotencyKeys[index],
+        };
+      }),
+    );
+  }
+
+  private acceptedEnvelopeDispatchStorageKey(idempotencyKey: string): string {
+    const digest = plugins.crypto
+      .createHash('sha256')
+      .update('smartmta-accepted-envelope-dispatch-v1\0')
+      .update(idempotencyKey)
+      .digest('hex');
+    return `${ACCEPTED_ENVELOPE_DISPATCH_STORAGE_PREFIX}${digest}.json`;
+  }
+
+  private startAcceptedEnvelopeDispatchCleanup(): void {
+    if (this.acceptedEnvelopeDispatchCleanupTimer) return;
+    this.acceptedEnvelopeDispatchCleanupTimer = setInterval(() => {
+      void this.cleanupExpiredAcceptedEnvelopeDispatchResults();
+    }, ACCEPTED_ENVELOPE_DISPATCH_CLEANUP_INTERVAL_MS);
+    this.acceptedEnvelopeDispatchCleanupTimer.unref?.();
+  }
+
+  private async cleanupExpiredAcceptedEnvelopeDispatchResults(
+    limit = ACCEPTED_ENVELOPE_DISPATCH_CLEANUP_LIMIT,
+  ): Promise<void> {
+    if (!this.dcRouter.storageManager.listPage) return;
+    if (this.acceptedEnvelopeDispatchCleanupPromise) {
+      return this.acceptedEnvelopeDispatchCleanupPromise;
+    }
+    const cleanup = (async () => {
+      if (!Number.isInteger(limit) || limit < 1) {
+        throw new Error('Accepted-envelope cleanup limit must be a positive integer');
+      }
+      const now = Date.now();
+      const page = await this.dcRouter.storageManager.listPage!(
+        ACCEPTED_ENVELOPE_DISPATCH_STORAGE_PREFIX,
+        {
+          limit,
+          ...(this.acceptedEnvelopeDispatchCleanupCursor
+            ? { continuationToken: this.acceptedEnvelopeDispatchCleanupCursor }
+            : {}),
+        },
+      );
+      if (
+        !page
+        || !Array.isArray(page.keys)
+        || page.keys.length > limit
+        || page.keys.some((key) => (
+          typeof key !== 'string'
+          || !key.startsWith(ACCEPTED_ENVELOPE_DISPATCH_STORAGE_PREFIX)
+        ))
+        || new Set(page.keys).size !== page.keys.length
+        || (
+          page.continuationToken !== undefined
+          && (
+            typeof page.continuationToken !== 'string'
+            || page.continuationToken.length === 0
+            || page.continuationToken === this.acceptedEnvelopeDispatchCleanupCursor
+          )
+        )
+      ) {
+        throw new Error('Invalid paginated accepted-envelope checkpoint listing');
+      }
+      this.acceptedEnvelopeDispatchCleanupCursor = page.continuationToken;
+      for (const key of page.keys) {
+        const value = await this.dcRouter.storageManager.get(key);
+        if (!value) continue;
+        try {
+          if (!key.endsWith('.json')) {
+            throw new Error(`Invalid accepted-envelope checkpoint key: ${key}`);
+          }
+          const stored = JSON.parse(value) as Partial<IStoredAcceptedEnvelopeDispatchResult>;
+          if (
+            stored.schemaVersion !== 1
+            || typeof stored.fingerprint !== 'string'
+            || !/^[a-f0-9]{64}$/.test(stored.fingerprint)
+            || !Number.isFinite(stored.expiresAt)
+            || !stored.result
+            || typeof stored.result !== 'object'
+            || stored.expiresAt! <= now
+          ) {
+            await this.dcRouter.storageManager.delete(key);
+          }
+        } catch {
+          await this.dcRouter.storageManager.delete(key);
+        }
+      }
+    })();
+    this.acceptedEnvelopeDispatchCleanupPromise = cleanup
+      .catch((error) => {
+        logger.log(
+          'warn',
+          `Accepted-envelope dispatch checkpoint cleanup failed: ${getErrorMessage(error)}`,
+        );
+      })
+      .finally(() => {
+        this.acceptedEnvelopeDispatchCleanupPromise = undefined;
+      });
+    return this.acceptedEnvelopeDispatchCleanupPromise;
+  }
+
+  private async readAcceptedEnvelopeDispatchResult(
+    entry: IAcceptedEnvelopeRecipientPlan,
+    fingerprint: string,
+  ): Promise<IAcceptedEnvelopeRecipientDispatchResult | null> {
+    const key = this.acceptedEnvelopeDispatchStorageKey(entry.idempotencyKey);
+    const storedText = await this.dcRouter.storageManager.get(key);
+    if (!storedText) return null;
+    let stored: IStoredAcceptedEnvelopeDispatchResult;
+    try {
+      stored = JSON.parse(storedText) as IStoredAcceptedEnvelopeDispatchResult;
+    } catch {
+      throw new Error(`Accepted-envelope dispatch checkpoint is malformed for ${entry.recipient}`);
+    }
+    if (Number.isFinite(stored.expiresAt) && stored.expiresAt <= Date.now()) {
+      await this.dcRouter.storageManager.delete(key);
+      return null;
+    }
+    if (
+      stored?.schemaVersion !== 1
+      || stored.fingerprint !== fingerprint
+      || !Number.isFinite(stored.expiresAt)
+      || stored.result?.idempotencyKey !== entry.idempotencyKey
+      || stored.result?.recipient !== entry.recipient
+      || stored.result?.localDomain !== entry.localDomain
+      || stored.result?.routeName !== entry.routeName
+      || stored.result?.source !== entry.source
+      || stored.result?.actionType !== entry.action.type
+      || (stored.result as Record<string, unknown> | undefined)?.replayed !== undefined
+      || !['stored', 'queued', 'rejected'].includes(stored.result?.status)
+      || (
+        stored.result?.status === 'queued'
+        && (
+          typeof stored.result.queueId !== 'string'
+          || !stored.result.queueId
+        )
+      )
+      || (
+        stored.result?.status !== 'queued'
+        && stored.result?.queueId !== undefined
+      )
+      || (
+        stored.result?.status === 'rejected'
+        && !Number.isInteger(stored.result.smtpCode)
+      )
+    ) {
+      throw new Error(
+        `Accepted-envelope idempotency key was reused or has invalid state for ${entry.recipient}`,
+      );
+    }
+    return { ...stored.result, replayed: true };
+  }
+
+  private async writeAcceptedEnvelopeDispatchResult(
+    result: IAcceptedEnvelopeRecipientDispatchResult,
+    fingerprint: string,
+  ): Promise<void> {
+    const { replayed: _replayed, ...storedResult } = result;
+    const stored: IStoredAcceptedEnvelopeDispatchResult = {
+      schemaVersion: 1,
+      fingerprint,
+      expiresAt: Date.now() + ACCEPTED_ENVELOPE_IDEMPOTENCY_RETENTION_MS,
+      result: storedResult,
+    };
+    await this.dcRouter.storageManager.set(
+      this.acceptedEnvelopeDispatchStorageKey(result.idempotencyKey),
+      JSON.stringify(stored),
+    );
+  }
+
+  /**
+   * Dispatch a durably accepted raw envelope using only its persisted exact
+   * action snapshots. Each recipient receives an isolated Email and session.
+   * Queue-backed actions require managed queue storage and are replay-safe.
+   */
+  public async dispatchAcceptedEnvelope(
+    rawMessage: Uint8Array,
+    planArg: readonly IAcceptedEnvelopeRecipientPlan[],
+    metadataArg: IAcceptedEnvelopeDispatchMetadata,
+  ): Promise<IAcceptedEnvelopeDispatchResult> {
+    if (!(rawMessage instanceof Uint8Array) || rawMessage.byteLength === 0) {
+      throw new Error('Accepted envelope raw message must contain exact RFC822 bytes');
+    }
+    const rawCopy = Buffer.from(rawMessage);
+    const plan = this.normalizeAcceptedEnvelopePlan(planArg);
+    const metadata = this.cloneJsonSafe(metadataArg, 'metadata');
+    if (!metadata?.mailFrom && metadata?.mailFrom !== '') {
+      throw new Error('Accepted envelope metadata.mailFrom is required');
+    }
+    if (!this.dcRouter.storageManager.listPage) {
+      throw new Error(
+        'Accepted-envelope dispatch requires paginated small-state storage',
+      );
+    }
+    const hasQueueAction = plan.some((entry) => (
+      entry.action.type === 'forward'
+      || entry.action.type === 'deliver'
+      || entry.action.type === 'process'
+    ));
+    if (hasQueueAction) {
+      if (!this.deliveryQueue.hasManagedStorage()) {
+        throw new Error(
+          'Accepted-envelope queue actions require managed queue storage',
+        );
+      }
+      if (!this.deliveryQueue.hasPaginatedManagedStorage()) {
+        throw new Error(
+          'Accepted-envelope queue actions require paginated managed queue storage',
+        );
+      }
+    }
+
+    const rawDigest = plugins.crypto.createHash('sha256').update(rawCopy).digest('hex');
+    const fingerprints = plan.map((entry) => plugins.crypto
+      .createHash('sha256')
+      .update(this.stableJson({
+        rawDigest,
+        metadata,
+        entry,
+      }))
+      .digest('hex'));
+
+    const results: Array<IAcceptedEnvelopeRecipientDispatchResult | null> = [];
+    for (let index = 0; index < plan.length; index++) {
+      results.push(await this.readAcceptedEnvelopeDispatchResult(
+        plan[index],
+        fingerprints[index],
+      ));
+    }
+    if (results.every(Boolean)) {
+      return {
+        complete: true,
+        results: results as IAcceptedEnvelopeRecipientDispatchResult[],
+      };
+    }
+
+    const baseSession: IExtendedSmtpSession = {
+      id: metadata.session?.id || `accepted-envelope-${rawDigest.slice(0, 16)}`,
+      state: SmtpState.FINISHED,
+      mailFrom: metadata.mailFrom,
+      rcptTo: plan.map((entry) => entry.recipient),
+      emailData: '',
+      useTLS: !!metadata.session?.secure,
+      connectionEnded: true,
+      remoteAddress: metadata.session?.remoteAddress || '',
+      clientHostname: metadata.session?.clientHostname || '',
+      secure: !!metadata.session?.secure,
+      authenticated: !!metadata.session?.authenticated,
+      envelope: {
+        mailFrom: { address: metadata.mailFrom, args: {} },
+        rcptTo: plan.map((entry) => ({ address: entry.recipient, args: {} })),
+      },
+    };
+    if (metadata.session?.user) {
+      baseSession.user = structuredClone(metadata.session.user) as IExtendedSmtpSession['user'];
+    } else if (metadata.session?.authenticatedUser) {
+      baseSession.user = { username: metadata.session.authenticatedUser };
+    }
+    let parsedEmail: Email | undefined;
+
+    for (let index = 0; index < plan.length; index++) {
+      if (results[index]) continue;
+      const entry = plan[index];
+      const fingerprint = fingerprints[index];
+      const commonResult = {
+        recipient: entry.recipient,
+        localDomain: entry.localDomain,
+        routeName: entry.routeName,
+        source: entry.source,
+        actionType: entry.action.type,
+        idempotencyKey: entry.idempotencyKey,
+        replayed: false,
+      } as const;
+
+      try {
+        let result: IAcceptedEnvelopeRecipientDispatchResult;
+        if (entry.action.type === 'store') {
+          result = { ...commonResult, status: 'stored' };
+        } else {
+          parsedEmail ||= await this.createEmailFromBuffer(rawCopy, baseSession);
+          const route: IEmailRoute = Object.freeze({
+            name: entry.routeName,
+            match: Object.freeze({ recipients: entry.recipient }),
+            action: entry.action,
+          });
+          const email = this.cloneEmailForRoutingRecipient(parsedEmail, entry.recipient);
+          const session = this.scopeSessionForRoutingRecipient(baseSession, entry.recipient);
+          session.id = `${baseSession.id}:${index}`;
+          session.matchedRoute = route;
+          session.resolvedRecipientRoutes = [{
+            recipient: entry.recipient,
+            localDomain: entry.localDomain,
+            route,
+            source: entry.source,
+          }];
+          try {
+            const execution = await this.actionExecutor.executeActionWithResult(
+              entry.action,
+              email,
+              { email, session },
+              {
+                durableQueue: {
+                  idempotencyKey: entry.idempotencyKey,
+                  fingerprint,
+                },
+              },
+            );
+            if (execution.outcome !== 'queued' || !execution.queueId) {
+              throw new Error(
+                `Accepted-envelope ${entry.action.type} action did not durably enqueue`,
+              );
+            }
+            result = {
+              ...commonResult,
+              status: 'queued',
+              queueId: execution.queueId,
+            };
+          } catch (error) {
+            if (entry.action.type !== 'reject') throw error;
+            result = {
+              ...commonResult,
+              status: 'rejected',
+              smtpCode: Number((error as any)?.responseCode)
+                || entry.action.reject?.code
+                || 550,
+              message: getErrorMessage(error),
+            };
+          }
+        }
+        await this.writeAcceptedEnvelopeDispatchResult(result, fingerprint);
+        results[index] = result;
+      } catch (error) {
+        results[index] = {
+          ...commonResult,
+          status: 'failed',
+          message: getErrorMessage(error),
+        };
+      }
+    }
+
+    const finalResults = results as IAcceptedEnvelopeRecipientDispatchResult[];
+    return {
+      complete: finalResults.every((result) => result.status !== 'failed'),
+      results: finalResults,
+    };
+  }
+
   /**
    * Handle an emailReceived event from the Rust SMTP server.
    */