@serve.zone/dcrouter 18.1.1 → 18.2.0

package/ts/classes.dcrouter.ts

@@ -49,6 +49,32 @@ import type { IEmailOutboundEgressStatus, IEmailPortConfig, IEmailServerSettings
 import type { IDcRouterRouteConfig, IRemoteIngressHubSettings, IRemoteIngressPerformanceConfig, TRemoteIngressHubSettingsUpdate } from '../ts_interfaces/data/remoteingress.js';
 import type { ISecurityCompiledPolicy } from '../ts_interfaces/data/security-policy.js';
 
+/**
+ * dcrouter's superset of SmartMTA's SMTP TLS options.
+ *
+ * SmartMTA consumes PEM content (`certPem`/`keyPem`). Deployments configure
+ * certificate FILES, so dcrouter accepts the path form too and loads it eagerly
+ * at startup — a path that cannot be read fails startup rather than silently
+ * leaving the listener without TLS.
+ */
+export interface IDcRouterEmailTlsConfig extends NonNullable<IUnifiedEmailServerOptions['tls']> {
+  /** Path to the certificate chain PEM file. Requires keyPath. */
+  certPath?: string;
+  /** Path to the private key PEM file. Requires certPath. */
+  keyPath?: string;
+}
+
+/** dcrouter's email server options: SmartMTA's, with the path-shaped tls block. */
+export type IDcRouterEmailConfig = Omit<IUnifiedEmailServerOptions, 'tls'> & {
+  tls?: IDcRouterEmailTlsConfig;
+};
+
+/** Whether an email configuration carries any SMTP AUTH credentials. */
+const emailConfigHasAuth = (emailConfigArg: IUnifiedEmailServerOptions | undefined): boolean =>
+  !!emailConfigArg?.auth?.required
+  || !!emailConfigArg?.auth?.users?.length
+  || !!emailConfigArg?.auth?.accounts?.length;
+
 export interface IDcRouterOptions {
   /** Base directory for all dcrouter data. Defaults to ~/.serve.zone/dcrouter */
   baseDir?: string;
@@ -66,7 +92,7 @@ export interface IDcRouterOptions {
    * Email server configuration
    * This enables all email handling with pattern-based routing
    */
-  emailConfig?: IUnifiedEmailServerOptions;
+  emailConfig?: IDcRouterEmailConfig;
 
   /** SmartBucket configuration for durable SmartMTA queue and attachment blobs. */
   emailBlobStorage?: ISmartMtaBlobStorageConfig;
@@ -1623,6 +1649,10 @@ export class DcRouter {
           expiryDate: event.expiryDate, issuedAt: new Date().toISOString(),
           source: event.source,
         });
+        // Renewals arrive here too. The SMTP listener holds its PEM material as
+        // listener-level Rust configuration, so a renewed mail-hostname
+        // certificate must be pushed or STARTTLS keeps serving the stale one.
+        void this.reapplyEmailTlsMaterial(event.domain);
       });
 
       // Note: smartproxy v27.5.0 emits only 'certificate-issued' and 'certificate-failed'.
@@ -1955,6 +1985,10 @@ export class DcRouter {
       storageManager: this.smartMtaBlobStorageManager,
     };
 
+    const emailTls = await this.resolveEmailTlsMaterial();
+    const tlsTerminatedPorts = this.resolveEdgeTerminatedEmailPorts(portMapping);
+    this.logEmailAuthTransportPosture(emailConfigHasAuth(baseEmailConfig), emailTls, mappedEmailPorts, tlsTerminatedPorts, mappedSecurePort);
+
     let emailConfig: IUnifiedEmailServerOptions = await this.smtpAccountManager.composeEmailConfig({
       ...this.options.emailConfig,
       ports: mappedEmailPorts,
@@ -1962,6 +1996,7 @@ export class DcRouter {
       dkimKeyProvisioning: 'caller-managed',
       persistRoutes: this.options.emailConfig.persistRoutes ?? false,
       queue: queueOptions,
+      ...(emailTls ? { tls: { ...baseEmailConfig.tls, certPem: emailTls.certPem, keyPem: emailTls.keyPem } } : {}),
       outbound: {
         ...baseEmailConfig.outbound,
         connectionProxyProvider: (context) => this.mailEgressCoordinator.provideConnectionProxy(context),
@@ -1971,6 +2006,7 @@ export class DcRouter {
         ...(mappedSecurePort !== undefined
           ? { securePort: mappedSecurePort }
           : {}),
+        ...(tlsTerminatedPorts.length > 0 ? { tlsTerminatedPorts } : {}),
         recipientValidation: true,
         proxyProtocol: {
           ...baseEmailConfig.smtp?.proxyProtocol,
@@ -2178,6 +2214,168 @@ export class DcRouter {
     this.mailDnsSync.requestSync('email server start');
   }
 
+  /**
+   * Resolve the PEM material for the SMTP listener.
+   *
+   * SmartMTA consumes `tls.certPem`/`tls.keyPem`; a path-shaped `tls` block is
+   * ignored, which leaves the Rust listener with no TLS material at all — no
+   * STARTTLS on the plain submission ports. Resolution order matches the
+   * RemoteIngress tunnel precedent: explicit paths, then the ACME cert store.
+   *
+   * Explicitly configured paths that cannot be read FAIL STARTUP. Silently
+   * continuing without TLS is what produced a cleartext submission port in
+   * production, so a broken explicit configuration must be impossible to miss.
+   */
+  private async resolveEmailTlsMaterial(): Promise<{ certPem: string; keyPem: string; source: string } | undefined> {
+    const tlsConfig = this.options.emailConfig?.tls as (IUnifiedEmailServerOptions['tls'] & {
+      certPath?: string;
+      keyPath?: string;
+    }) | undefined;
+
+    if (tlsConfig?.certPem && tlsConfig?.keyPem) {
+      return { certPem: tlsConfig.certPem, keyPem: tlsConfig.keyPem, source: 'inline PEM' };
+    }
+
+    if (tlsConfig?.certPath || tlsConfig?.keyPath) {
+      if (!tlsConfig.certPath || !tlsConfig.keyPath) {
+        throw new Error(
+          'emailConfig.tls requires both certPath and keyPath when either is configured',
+        );
+      }
+      let certPem: string;
+      let keyPem: string;
+      try {
+        certPem = await plugins.fs.promises.readFile(tlsConfig.certPath, 'utf8');
+        keyPem = await plugins.fs.promises.readFile(tlsConfig.keyPath, 'utf8');
+      } catch (error: unknown) {
+        throw new Error(
+          `Unable to read the configured SMTP TLS material (certPath=${tlsConfig.certPath}, keyPath=${tlsConfig.keyPath}): ${(error as Error).message}`,
+        );
+      }
+      if (!certPem.trim() || !keyPem.trim()) {
+        throw new Error(
+          `The configured SMTP TLS material is empty (certPath=${tlsConfig.certPath}, keyPath=${tlsConfig.keyPath})`,
+        );
+      }
+      logger.log('info', `SMTP TLS material loaded from configured paths (${tlsConfig.certPath})`);
+      return { certPem, keyPem, source: `configured paths (${tlsConfig.certPath})` };
+    }
+
+    const mailHostname = this.options.emailConfig?.hostname;
+    if (mailHostname) {
+      try {
+        const stored = await ProxyCertDoc.findByDomain(mailHostname);
+        if (stored?.publicKey && stored?.privateKey) {
+          logger.log('info', `SMTP TLS material loaded from the stored ACME certificate for ${mailHostname}`);
+          return { certPem: stored.publicKey, keyPem: stored.privateKey, source: `stored ACME certificate for ${mailHostname}` };
+        }
+      } catch (error: unknown) {
+        logger.log('warn', `Unable to read the stored certificate for the mail hostname ${mailHostname}: ${(error as Error).message}`);
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Push renewed TLS material to the running SMTP listener.
+   *
+   * Only reacts to the mail hostname, and only when explicit paths are NOT
+   * configured — an operator-managed file pair is not superseded by an ACME
+   * renewal for the same name. SmartMTA restarts just the Rust listener when
+   * the PEM material actually changes.
+   */
+  private async reapplyEmailTlsMaterial(domainArg: string): Promise<void> {
+    const emailServer = this.emailServer;
+    const mailHostname = this.options.emailConfig?.hostname;
+    if (!emailServer || !mailHostname) return;
+    if (domainArg.toLowerCase() !== mailHostname.toLowerCase()) return;
+    const tlsConfig = this.options.emailConfig?.tls;
+    if (tlsConfig?.certPath || tlsConfig?.keyPath) return;
+
+    try {
+      const emailTls = await this.resolveEmailTlsMaterial();
+      if (!emailTls) return;
+      emailServer.updateOptions({
+        tls: { ...this.options.emailConfig?.tls, certPem: emailTls.certPem, keyPem: emailTls.keyPem },
+      });
+      if (this.options.emailConfig) {
+        this.options.emailConfig.tls = {
+          ...this.options.emailConfig.tls,
+          certPem: emailTls.certPem,
+          keyPem: emailTls.keyPem,
+        };
+      }
+      logger.log('info', `Pushed renewed SMTP TLS material for ${mailHostname} to the email listener`);
+    } catch (error: unknown) {
+      logger.log('error', `Unable to apply renewed SMTP TLS material for ${mailHostname}: ${(error as Error).message}`);
+    }
+  }
+
+  /**
+   * Internal SMTP ports whose public leg is TLS-terminated by CoreTraffic.
+   *
+   * Those backend legs arrive as plaintext even though the client's channel was
+   * encrypted, so without declaring them the AUTH-requires-encryption gate would
+   * refuse authentication on the only encrypted submission port. Derived from
+   * the generated route set rather than hardcoding 465, so it stays true when
+   * emailPortConfig changes.
+   */
+  private resolveEdgeTerminatedEmailPorts(portMapping: Record<number, number>): number[] {
+    if (!this.options.emailConfig) return [];
+    const terminatedPorts: number[] = [];
+    for (const route of this.emailRouteBuilder.generateEmailRoutes(this.options.emailConfig)) {
+      if ((route.action as { tls?: { mode?: string } }).tls?.mode !== 'terminate') continue;
+      const publicPorts = Array.isArray(route.match?.ports) ? route.match.ports : [];
+      for (const publicPort of publicPorts) {
+        if (typeof publicPort !== 'number') continue;
+        const internalPort = portMapping[publicPort] || publicPort + 10000;
+        // The implicit-TLS securePort is terminated by smartmta itself.
+        if (internalPort === this.options.emailConfig.smtp?.securePort) continue;
+        if (!terminatedPorts.includes(internalPort)) {
+          terminatedPorts.push(internalPort);
+        }
+      }
+    }
+    return terminatedPorts;
+  }
+
+  /**
+   * State the transport posture of every SMTP listener port at startup.
+   *
+   * AUTH is only offered on an encrypted transport, so an operator has to be
+   * able to see at a glance which submission ports can actually authenticate —
+   * missing certificate material silently disabling AUTH on 587 would otherwise
+   * look like a client problem.
+   */
+  private logEmailAuthTransportPosture(
+    authConfigured: boolean,
+    emailTls: { source: string } | undefined,
+    mappedPorts: number[],
+    tlsTerminatedPorts: number[],
+    mappedSecurePort: number | undefined,
+  ): void {
+    const authCapable: number[] = [];
+    const cleartext: number[] = [];
+    for (const port of mappedPorts) {
+      if (port === mappedSecurePort || tlsTerminatedPorts.includes(port) || emailTls) {
+        authCapable.push(port);
+      } else {
+        cleartext.push(port);
+      }
+    }
+    logger.log(
+      'info',
+      `SMTP transport posture: TLS material=${emailTls ? emailTls.source : 'NONE'}, edge-terminated ports=[${tlsTerminatedPorts.join(', ') || 'none'}], implicit-TLS port=${mappedSecurePort ?? 'none'}, AUTH-capable ports=[${authCapable.join(', ') || 'none'}]`,
+    );
+    if (authConfigured && !emailTls && cleartext.length > 0) {
+      logger.log(
+        'error',
+        `SMTP AUTH is configured but ports [${cleartext.join(', ')}] have no TLS material and no upstream TLS terminator — AUTH is refused there because credentials must never cross a cleartext channel. Configure emailConfig.tls.certPath/keyPath, or provision an ACME certificate for ${this.options.emailConfig?.hostname || 'the mail hostname'}.`,
+      );
+    }
+  }
+
   /**
    * Readiness of the RemoteIngress outbound mail egress path (mail-tagged edges).
    */

package/ts/email/classes.accepted-email-spool.ts

@@ -8,10 +8,13 @@ import type {
 import { AcceptEnvelopeRejectionError } from '@push.rocks/smartmta';
 import type {
   Email,
+  IAcceptedEnvelopeDispatchMetadata,
+  IAcceptedEnvelopeRecipientPlan,
   IAcceptEnvelopeContext,
   IExtendedSmtpSession,
   IMessageAcceptanceContext,
   IMessageAcceptanceDecision,
+  IResolvedRecipientRoute,
   UnifiedEmailServer,
 } from '@push.rocks/smartmta';
 import type { DcRouter } from '../classes.dcrouter.js';
@@ -76,6 +79,9 @@ const ACCEPTED_EMAIL_SPOOL_BATCH_SIZE = 25;
 const ACCEPTED_EMAIL_STOP_DRAIN_TIMEOUT_MS = 30_000;
 /** Retention for catch-all stored inbound mail (30 days). */
 const INBOUND_STORE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** Redispatch attempts for the non-store recipients of a durable envelope. */
+const ENVELOPE_DISPATCH_MAX_ATTEMPTS = 10;
+const ENVELOPE_DISPATCH_RETRY_DELAY_MS = 5 * 60_000;
 
 /**
  * Permanent per-email storage failure: the raw RFC822 payload of an accepted
@@ -136,8 +142,32 @@ type TStoredCachedEmailSession = {
   };
 };
 
+/**
+ * Persisted per-recipient dispatch state for a durably accepted envelope.
+ * Holds everything needed to replay `dispatchAcceptedEnvelope` byte-identically:
+ * upstream fingerprints each recipient over the raw message, the metadata and
+ * the plan entry, so a replay reconstructed from anything else would be refused
+ * as an idempotency-key reuse instead of retrying.
+ */
+type TStoredEnvelopeDispatch = {
+  plan: IAcceptedEnvelopeRecipientPlan[];
+  metadata: IAcceptedEnvelopeDispatchMetadata;
+  attempts: number;
+  results?: Array<{
+    recipient: string;
+    status: string;
+    message?: string;
+    smtpCode?: number;
+  }>;
+  pendingRecipients?: string[];
+  /** Set once retries are exhausted; the row stops being redispatched. */
+  abandonedAt?: string;
+};
+
 type TStoredCachedEmailRouteData = {
+  acceptance?: string;
   session?: TStoredCachedEmailSession;
+  envelopeDispatch?: TStoredEnvelopeDispatch;
   smartMta?: {
     status?: 'queued' | 'deferred' | 'delivered' | 'failed';
     nextAttempt?: string;
@@ -185,6 +215,54 @@ export class AcceptedEmailSpool {
 
   constructor(private dcRouterRef: DcRouter) {}
 
+  /**
+   * Direction is decided by the RECIPIENT, never by whether the session
+   * authenticated. Authentication grants permission to relay; it does not make
+   * a message addressed to a mailbox we host into outbound mail. A message with
+   * at least one locally hosted recipient is inbound — a local mailbox receives
+   * it — and only an envelope addressed exclusively to remote recipients is
+   * outbound.
+   *
+   * `IResolvedRecipientRoute.localDomain` is smartmta's own per-recipient
+   * verdict (non-null exactly when the domain registry hosts the domain), so
+   * the classification uses the same truth the routing decision used. When an
+   * acceptance context carries no resolution the envelope recipients are
+   * classified against the live registry instead — never against the session,
+   * which is the mistake being fixed.
+   */
+  private deriveDirectionFromResolvedRoutes(
+    resolvedRecipientRoutes: readonly IResolvedRecipientRoute[] | undefined,
+    envelopeRecipientsArg: readonly string[],
+  ): TCachedEmailDirection {
+    if (resolvedRecipientRoutes?.length) {
+      return resolvedRecipientRoutes.some((resolution) => !!resolution.localDomain)
+        ? 'inbound'
+        : 'outbound';
+    }
+    return this.deriveDirectionFromRecipients(envelopeRecipientsArg);
+  }
+
+  /**
+   * Recipient-derived direction for programmatic submitters, which have no SMTP
+   * recipient resolution to consult. Falls back to the live domain registry.
+   */
+  private deriveDirectionFromRecipients(recipientsArg: readonly string[]): TCachedEmailDirection {
+    const domainRegistry = this.dcRouterRef.emailServer?.domainRegistry;
+    if (!domainRegistry) {
+      // Without the registry there is no recipient truth to classify against.
+      // Programmatic submission is relay by construction, so outbound is the
+      // honest label rather than guessing from the session.
+      return 'outbound';
+    }
+    for (const recipient of recipientsArg) {
+      const domain = recipient.split('@')[1]?.trim().toLowerCase();
+      if (domain && domainRegistry.isDomainRegistered(domain)) {
+        return 'inbound';
+      }
+    }
+    return 'outbound';
+  }
+
   public async acceptMessage(
     context: IMessageAcceptanceContext,
     processAfterAccept = true,
@@ -218,7 +296,10 @@ export class AcceptedEmailSpool {
     await this.persistRawMessage(cachedEmail, persistedRawMessage);
     cachedEmail.status = 'pending';
     cachedEmail.nextAttempt = new Date();
-    cachedEmail.direction = session.authenticated ? 'outbound' : 'inbound';
+    cachedEmail.direction = this.deriveDirectionFromResolvedRoutes(
+      context.resolvedRecipientRoutes,
+      envelopeRecipients.length > 0 ? envelopeRecipients : cachedEmail.to,
+    );
     cachedEmail.acceptedAt = Date.now();
     cachedEmail.routeData = JSON.stringify({
       acceptedAt: new Date().toISOString(),
@@ -288,7 +369,7 @@ export class AcceptedEmailSpool {
     cachedEmail.status = 'pending';
     cachedEmail.nextAttempt = new Date();
     cachedEmail.direction = optionsArg.direction
-      ?? (optionsArg.session.authenticated ? 'outbound' : 'inbound');
+      ?? this.deriveDirectionFromRecipients(optionsArg.envelope.rcptTo);
     cachedEmail.acceptedAt = Date.now();
     cachedEmail.routeData = JSON.stringify({
       acceptedAt: new Date().toISOString(),
@@ -379,7 +460,10 @@ export class AcceptedEmailSpool {
       cachedEmail.id,
     );
     await this.persistRawMessage(cachedEmail, persistedRawMessage);
-    cachedEmail.direction = session.authenticated ? 'outbound' : 'inbound';
+    cachedEmail.direction = this.deriveDirectionFromResolvedRoutes(
+      context.resolvedRecipientRoutes,
+      context.envelope.rcptTo,
+    );
     cachedEmail.acceptedAt = startedAtMs;
 
     if (acceptance.dmarcReject) {
@@ -415,6 +499,15 @@ export class AcceptedEmailSpool {
     } else {
       cachedEmail.status = 'accepted';
     }
+    if (nonStoreEntries.length > 0) {
+      // Relay recipients are dispatched after this row is committed. Park the
+      // row in a status the spool actually scans so a crash between the commit
+      // and the dispatch leaves those recipients recoverable instead of stranded
+      // in a terminal-looking 'accepted' row. The dispatch outcome settles it
+      // straight back to the acceptance status.
+      cachedEmail.status = 'deferred';
+      cachedEmail.nextAttempt = new Date(Date.now() + ENVELOPE_DISPATCH_RETRY_DELAY_MS);
+    }
     cachedEmail.deliveredAt = new Date();
     cachedEmail.setTTL(INBOUND_STORE_RETENTION_MS);
     cachedEmail.appendSmtpTransaction(this.buildInboundTransaction(context, cachedEmail.id, {
@@ -424,6 +517,7 @@ export class AcceptedEmailSpool {
       doubts: acceptance.doubts,
       startedAtMs,
     }));
+    const dispatchMetadata = this.buildEnvelopeDispatchMetadata(context);
     cachedEmail.routeData = JSON.stringify({
       acceptedAt: new Date(startedAtMs).toISOString(),
       acceptance: 'durable-envelope',
@@ -434,6 +528,18 @@ export class AcceptedEmailSpool {
         source: entry.source,
         actionType: entry.action.type,
       })),
+      // Persisted BEFORE the SMTP 250, so a dispatch failure for the non-store
+      // recipients is recoverable instead of being lost with the process.
+      ...(nonStoreEntries.length > 0
+        ? {
+          envelopeDispatch: {
+            plan: [...plan],
+            metadata: dispatchMetadata,
+            attempts: 0,
+            pendingRecipients: nonStoreEntries.map((entry) => entry.recipient),
+          } satisfies TStoredEnvelopeDispatch,
+        }
+        : {}),
       session: {
         id: session.id,
         remoteAddress: session.remoteAddress,
@@ -461,28 +567,193 @@ export class AcceptedEmailSpool {
     }
 
     if (nonStoreEntries.length > 0) {
-      const dispatchResult = await emailServer.dispatchAcceptedEnvelope(
-        context.rawMessage,
-        plan,
-        {
-          mailFrom: context.envelope.mailFrom,
-          session: {
-            id: session.id,
-            remoteAddress: session.remoteAddress,
-            clientHostname: session.clientHostname,
-            secure: !!session.secure,
-            authenticated: !!session.authenticated,
-          },
-        },
-      );
-      const failed = dispatchResult.results.filter(
-        (result) => result.status === 'failed' || result.status === 'rejected',
+      await this.dispatchEnvelopeRecipients(cachedEmail, persistedRawMessage, emailServer);
+    }
+    this.trackAcceptedInboundEmail(cachedEmail);
+  }
+
+  /**
+   * Session metadata for `dispatchAcceptedEnvelope`. It feeds the per-recipient
+   * idempotency fingerprint, so it must be JSON-round-trip stable: a replay
+   * reconstructed from persisted state has to produce byte-identical metadata
+   * or upstream refuses it as an idempotency-key reuse.
+   */
+  private buildEnvelopeDispatchMetadata(
+    context: IAcceptEnvelopeContext,
+  ): IAcceptedEnvelopeDispatchMetadata {
+    const session = context.session;
+    return {
+      mailFrom: context.envelope.mailFrom,
+      session: {
+        id: session.id || '',
+        remoteAddress: session.remoteAddress || '',
+        clientHostname: session.clientHostname || '',
+        secure: !!session.secure,
+        authenticated: !!session.authenticated,
+      },
+    };
+  }
+
+  /**
+   * Dispatch (or redispatch) the non-store recipients of a durably accepted
+   * envelope.
+   *
+   * The raw bytes handed to upstream are the exact bytes persisted for this row,
+   * because upstream fingerprints every recipient over the raw message: a later
+   * replay with different bytes would be rejected as an idempotency-key reuse
+   * rather than retried. Recipients that already succeeded are short-circuited
+   * by upstream's checkpoints, and `failed` results are deliberately not
+   * checkpointed upstream, so an identical replay retries exactly those.
+   *
+   * A `failed` recipient leaves the row non-terminal so the spool retries it;
+   * a `rejected` recipient is a permanent per-recipient refusal and is recorded
+   * durably instead of being retried. Either way the outcome is persisted — a
+   * relay recipient is never silently dropped after the SMTP 250.
+   */
+  private async dispatchEnvelopeRecipients(
+    cachedEmailArg: CachedEmail,
+    rawMessageArg: string,
+    emailServerArg: UnifiedEmailServer,
+  ): Promise<void> {
+    const routeData = this.parseCachedEmailRouteData(cachedEmailArg);
+    const envelopeDispatch = routeData.envelopeDispatch;
+    if (!envelopeDispatch || envelopeDispatch.abandonedAt) return;
+
+    const attempts = (envelopeDispatch.attempts || 0) + 1;
+    let dispatchResults: Array<{
+      recipient: string;
+      status: string;
+      message?: string;
+      smtpCode?: number;
+    }>;
+    try {
+      const dispatchResult = await emailServerArg.dispatchAcceptedEnvelope(
+        plugins.buffer.Buffer.from(rawMessageArg, 'utf8'),
+        envelopeDispatch.plan,
+        envelopeDispatch.metadata,
       );
-      if (failed.length > 0) {
-        logger.log('warn', `Durable envelope ${cachedEmail.id}: ${failed.length}/${dispatchResult.results.length} non-store recipients failed dispatch: ${failed.map((result) => `${result.recipient}=${result.message || result.status}`).join('; ')}`);
+      dispatchResults = dispatchResult.results.map((result) => ({
+        recipient: result.recipient,
+        status: result.status,
+        ...(result.message ? { message: result.message } : {}),
+        ...(result.smtpCode !== undefined ? { smtpCode: result.smtpCode } : {}),
+      }));
+    } catch (error: unknown) {
+      // A whole-call failure (missing managed queue storage, malformed
+      // checkpoint) is retried the same way a per-recipient failure is.
+      dispatchResults = envelopeDispatch.plan
+        .filter((entry) => entry.action.type !== 'store' && entry.action.type !== 'deliver')
+        .map((entry) => ({
+          recipient: entry.recipient,
+          status: 'failed',
+          message: (error as Error).message,
+        }));
+    }
+
+    const retryable = dispatchResults.filter((result) => result.status === 'failed');
+    const rejected = dispatchResults.filter((result) => result.status === 'rejected');
+    const exhausted = retryable.length > 0 && attempts >= ENVELOPE_DISPATCH_MAX_ATTEMPTS;
+
+    await this.persistEnvelopeDispatchOutcome(cachedEmailArg.id, {
+      attempts,
+      results: dispatchResults,
+      pendingRecipients: exhausted ? [] : retryable.map((result) => result.recipient),
+      abandoned: exhausted,
+    });
+
+    if (rejected.length > 0) {
+      logger.log('error', `Durable envelope ${cachedEmailArg.id}: ${rejected.length} relay recipient(s) permanently refused: ${rejected.map((result) => `${result.recipient}=${result.smtpCode || 550} ${result.message || 'rejected'}`).join('; ')}`);
+    }
+    if (exhausted) {
+      logger.log('error', `Durable envelope ${cachedEmailArg.id}: giving up on ${retryable.length} relay recipient(s) after ${attempts} dispatch attempts: ${retryable.map((result) => `${result.recipient}=${result.message || 'failed'}`).join('; ')}`);
+    } else if (retryable.length > 0) {
+      logger.log('warn', `Durable envelope ${cachedEmailArg.id}: ${retryable.length} relay recipient(s) failed dispatch (attempt ${attempts}/${ENVELOPE_DISPATCH_MAX_ATTEMPTS}), scheduled for redispatch: ${retryable.map((result) => `${result.recipient}=${result.message || 'failed'}`).join('; ')}`);
+    }
+  }
+
+  /**
+   * Persist a dispatch attempt's outcome on the durable-envelope row.
+   *
+   * The row's status tracks the stored envelope, not the relay: it goes
+   * `deferred` only while relay recipients still need a redispatch, and returns
+   * to its acceptance status once none do. Relay progress itself lives in
+   * `routeData.envelopeDispatch`, so a relay failure can never mark a row whose
+   * local copy stored successfully as failed.
+   */
+  private async persistEnvelopeDispatchOutcome(
+    cachedEmailIdArg: string,
+    outcomeArg: {
+      attempts: number;
+      results: Array<{ recipient: string; status: string; message?: string; smtpCode?: number }>;
+      pendingRecipients: string[];
+      abandoned: boolean;
+    },
+  ): Promise<void> {
+    await this.runCachedEmailUpdate(cachedEmailIdArg, async () => {
+      const cachedEmail = await CachedEmail.findById(cachedEmailIdArg);
+      if (!cachedEmail) return;
+      const routeData = this.parseCachedEmailRouteData(cachedEmail);
+      if (!routeData.envelopeDispatch) return;
+      routeData.envelopeDispatch = {
+        ...routeData.envelopeDispatch,
+        attempts: outcomeArg.attempts,
+        results: outcomeArg.results,
+        pendingRecipients: outcomeArg.pendingRecipients,
+        ...(outcomeArg.abandoned ? { abandonedAt: new Date().toISOString() } : {}),
+      };
+      cachedEmail.routeData = JSON.stringify(routeData);
+
+      const stillPending = outcomeArg.pendingRecipients.length > 0;
+      const acceptanceStatus = cachedEmail.lastError && !stillPending ? 'flagged' : 'accepted';
+      if (stillPending) {
+        cachedEmail.status = 'deferred';
+        cachedEmail.nextAttempt = new Date(Date.now() + ENVELOPE_DISPATCH_RETRY_DELAY_MS);
+      } else if (cachedEmail.status === 'deferred') {
+        cachedEmail.status = acceptanceStatus;
+        cachedEmail.nextAttempt = new Date();
       }
+      await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(
+        cachedEmail,
+        stillPending ? 'envelope-dispatch-deferred' : 'envelope-dispatch-settled',
+      );
+    });
+  }
+
+  /**
+   * Take exclusive ownership of a durably accepted envelope row in the spool.
+   *
+   * Runs before live-queue postponement and before the normal spool handoff: a
+   * relay sibling that did enqueue would otherwise postpone this row forever,
+   * and the normal handoff would re-run route evaluation and duplicate a
+   * delivery the stored copy already fulfilled.
+   */
+  private async handleDurableEnvelopeRow(
+    cachedEmailArg: CachedEmail,
+    emailServerArg: UnifiedEmailServer,
+  ): Promise<boolean> {
+    if (!this.isDurableEnvelopeRow(cachedEmailArg)) return false;
+    const envelopeDispatch = this.parseCachedEmailRouteData(cachedEmailArg).envelopeDispatch;
+
+    if (envelopeDispatch?.pendingRecipients?.length && !envelopeDispatch.abandonedAt) {
+      const rawMessage = await this.readRawMessage(cachedEmailArg);
+      await this.dispatchEnvelopeRecipients(
+        cachedEmailArg,
+        rawMessage.toString('utf8'),
+        emailServerArg,
+      );
+      return true;
     }
-    this.trackAcceptedInboundEmail(cachedEmail);
+
+    // Nothing left to dispatch: settle the row back onto its acceptance status
+    // so a fully dispatched envelope does not linger as deferred.
+    if (cachedEmailArg.status === 'deferred') {
+      cachedEmailArg.status = cachedEmailArg.lastError ? 'flagged' : 'accepted';
+      cachedEmailArg.nextAttempt = new Date();
+      await cachedEmailArg.save();
+      await this.notifyEmailQueuePersisted(cachedEmailArg, 'envelope-dispatch-settled');
+    }
+    return true;
   }
 
   private trackAcceptedInboundEmail(cachedEmailArg: CachedEmail): void {
@@ -780,6 +1051,11 @@ export class AcceptedEmailSpool {
           break;
         }
         try {
+          // Durable envelopes are owned by the accepted-envelope dispatch path,
+          // never by the route-evaluating handoff below.
+          if (await this.handleDurableEnvelopeRow(cachedEmail, emailServer)) {
+            continue;
+          }
           if (await this.postponeLiveSmartMtaOwnedEmail(cachedEmail, emailServer)) {
             continue;
           }
@@ -954,6 +1230,15 @@ export class AcceptedEmailSpool {
       this.appendSmtpTransaction(cachedEmail, transaction);
     }
     this.updateSmartMtaRouteData(cachedEmail, item, status);
+    if (this.isDurableEnvelopeRow(cachedEmail)) {
+      // The row represents the durably accepted and stored envelope; the queue
+      // item only covers its relay recipients. Record the relay telemetry but
+      // never let a relay outcome overwrite the stored copy's status — a failed
+      // relay must not mark a successfully stored envelope as failed.
+      await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(cachedEmail, `envelope-relay-${status}`);
+      return;
+    }
     if (status === 'delivered') {
       cachedEmail.markDelivered();
     } else if (status === 'failed') {
@@ -1016,6 +1301,11 @@ export class AcceptedEmailSpool {
     return cachedEmail.status === 'delivered' || cachedEmail.status === 'failed';
   }
 
+  /** Whether this row was durably accepted through the envelope acceptance path. */
+  private isDurableEnvelopeRow(cachedEmail: CachedEmail): boolean {
+    return this.parseCachedEmailRouteData(cachedEmail).acceptance === 'durable-envelope';
+  }
+
   /** The CachedEmail row a live queue item was spooled from (via the cache-id header). */
   public getCachedEmailIdFromQueueItem(item: TSmartMtaQueueItemLike): string | undefined {
     return this.getHeaderValue(item.processingResult?.headers, DCROUTER_CACHE_ID_HEADER)