@serve.zone/dcrouter 17.0.0 → 17.1.1

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

@@ -1,7 +1,10 @@
 import * as plugins from '../plugins.js';
 import { logger } from '../logger.js';
 import { CachedEmail } from '../db/index.js';
-import type { TCachedEmailDirection } from '../db/documents/classes.cached.email.js';
+import type {
+  ICachedEmailSmtpTransaction,
+  TCachedEmailDirection,
+} from '../db/documents/classes.cached.email.js';
 import type {
   Email,
   IExtendedSmtpSession,
@@ -19,6 +22,7 @@ const ACCEPTED_EMAIL_SPOOL_BATCH_SIZE = 25;
 const ACCEPTED_EMAIL_STOP_DRAIN_TIMEOUT_MS = 30_000;
 
 export type TSmartMtaQueueItemLike = {
+  id?: string;
   processingResult?: {
     headers?: Record<string, string>;
     email?: { headers?: Record<string, string> };
@@ -27,8 +31,20 @@ export type TSmartMtaQueueItemLike = {
   attempts?: number;
   nextAttempt?: Date;
   lastError?: string;
+  smtpTransactions?: ICachedEmailSmtpTransaction[];
 };
 
+export interface IEmailQueuePersistedEvent {
+  cachedEmailId: string;
+  status: string;
+  reason: string;
+}
+
+export interface ISmtpTransactionPersistedEvent {
+  cachedEmailId: string;
+  transaction: ICachedEmailSmtpTransaction;
+}
+
 type TSmartMtaQueueReader = UnifiedEmailServer & {
   getQueueItems?: () => TSmartMtaQueueItemLike[];
 };
@@ -86,6 +102,13 @@ export class AcceptedEmailSpool {
   private processing = false;
   private stopping = false;
   private queueUpdatePromises = new Set<Promise<void>>();
+  private cachedEmailUpdateChains = new Map<string, Promise<void>>();
+  private smtpTransactionListeners = new Set<(
+    eventArg: ISmtpTransactionPersistedEvent,
+  ) => void | Promise<void>>();
+  private emailQueuePersistedListeners = new Set<(
+    eventArg: IEmailQueuePersistedEvent,
+  ) => void | Promise<void>>();
 
   constructor(private dcRouterRef: DcRouter) {}
 
@@ -118,7 +141,8 @@ export class AcceptedEmailSpool {
     cachedEmail.cc = Array.isArray(email.cc) ? email.cc : [];
     cachedEmail.bcc = Array.isArray(email.bcc) ? email.bcc : [];
     cachedEmail.subject = email.subject || '';
-    cachedEmail.rawContent = this.setDcRouterCacheIdHeader(rawMessage.toString('utf8'), cachedEmail.id);
+    const persistedRawMessage = this.setDcRouterCacheIdHeader(rawMessage.toString('utf8'), cachedEmail.id);
+    await this.persistRawMessage(cachedEmail, persistedRawMessage);
     cachedEmail.status = 'pending';
     cachedEmail.nextAttempt = new Date();
     cachedEmail.direction = session.authenticated ? 'outbound' : 'inbound';
@@ -137,10 +161,17 @@ export class AcceptedEmailSpool {
     });
     cachedEmail.updateSenderDomain();
     cachedEmail.updateRecipientDomains();
-    await cachedEmail.save();
+    try {
+      await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(cachedEmail, 'email-accepted');
+    } catch (error) {
+      await this.deleteRawMessage(cachedEmail).catch(() => undefined);
+      throw error;
+    }
     if (context.abortSignal?.aborted) {
       cachedEmail.markFailed('Message acceptance aborted before SMTP success');
       await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(cachedEmail, 'email-acceptance-aborted');
       throw new Error('Message acceptance aborted before SMTP success');
     }
 
@@ -149,6 +180,7 @@ export class AcceptedEmailSpool {
     } else {
       cachedEmail.markDelivered();
       await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(cachedEmail, 'email-accepted-without-queue');
     }
 
     return {
@@ -174,7 +206,8 @@ export class AcceptedEmailSpool {
     cachedEmail.cc = [];
     cachedEmail.bcc = [];
     cachedEmail.subject = optionsArg.subject || this.extractHeader(rawMessage, 'subject') || '';
-    cachedEmail.rawContent = this.setDcRouterCacheIdHeader(rawMessage, cachedEmail.id);
+    const persistedRawMessage = this.setDcRouterCacheIdHeader(rawMessage, cachedEmail.id);
+    await this.persistRawMessage(cachedEmail, persistedRawMessage);
     cachedEmail.status = 'pending';
     cachedEmail.nextAttempt = new Date();
     cachedEmail.direction = optionsArg.direction
@@ -194,13 +227,20 @@ export class AcceptedEmailSpool {
     });
     cachedEmail.updateSenderDomain();
     cachedEmail.updateRecipientDomains();
-    await cachedEmail.save();
+    try {
+      await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(cachedEmail, 'raw-email-accepted');
+    } catch (error) {
+      await this.deleteRawMessage(cachedEmail).catch(() => undefined);
+      throw error;
+    }
 
     if (optionsArg.processAfterAccept !== false) {
       this.run();
     } else {
       cachedEmail.markDelivered();
       await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(cachedEmail, 'raw-email-accepted-without-queue');
     }
 
     return {
@@ -268,14 +308,73 @@ export class AcceptedEmailSpool {
     item: TSmartMtaQueueItemLike,
     status: 'queued' | 'deferred' | 'delivered' | 'failed',
     failureMessage: string,
-  ): void {
-    const updatePromise = this.updateAcceptedEmailFromQueueItem(item, status).catch((error) => {
+  ): Promise<void> {
+    const cachedEmailId = this.getCachedEmailIdFromQueueItem(item);
+    const updatePromise = this.runCachedEmailUpdate(cachedEmailId, async () => {
+      await this.updateAcceptedEmailFromQueueItem(item, status);
+    }).catch((error) => {
       logger.log('warn', `${failureMessage}: ${(error as Error).message}`);
     });
-    this.queueUpdatePromises.add(updatePromise);
-    void updatePromise.finally(() => {
-      this.queueUpdatePromises.delete(updatePromise);
+    this.trackUpdatePromise(updatePromise);
+    return updatePromise;
+  }
+
+  public trackSmtpTransaction(
+    transactionArg: ICachedEmailSmtpTransaction,
+    emailServerArg: UnifiedEmailServer,
+  ): Promise<void> {
+    const queueItem = emailServerArg.getQueueItem(
+      transactionArg.queueItemId,
+    ) as TSmartMtaQueueItemLike | undefined;
+    const cachedEmailId = queueItem ? this.getCachedEmailIdFromQueueItem(queueItem) : undefined;
+    const updatePromise = this.runCachedEmailUpdate(cachedEmailId, async () => {
+      if (!cachedEmailId || !this.dcRouterRef.dcRouterDb?.isReady()) return;
+      const cachedEmail = await CachedEmail.findById(cachedEmailId);
+      if (!cachedEmail) return;
+      this.appendSmtpTransaction(cachedEmail, transactionArg);
+      await cachedEmail.save();
+      const event: ISmtpTransactionPersistedEvent = {
+        cachedEmailId,
+        transaction: structuredClone(transactionArg),
+      };
+      await Promise.allSettled(
+        [...this.smtpTransactionListeners].map(async (listener) => await listener(event)),
+      );
+    }).catch((error) => {
+      logger.log('warn', `Unable to persist SMTP transaction: ${(error as Error).message}`);
     });
+    this.trackUpdatePromise(updatePromise);
+    return updatePromise;
+  }
+
+  /** Subscribe to updates only after the SMTP transaction is durably stored. */
+  public onSmtpTransactionPersisted(
+    listenerArg: (eventArg: ISmtpTransactionPersistedEvent) => void | Promise<void>,
+  ): () => void {
+    this.smtpTransactionListeners.add(listenerArg);
+    return () => this.smtpTransactionListeners.delete(listenerArg);
+  }
+  /** Subscribe to queue state changes only after the CachedEmail row is durable. */
+  public onEmailQueuePersisted(
+    listenerArg: (eventArg: IEmailQueuePersistedEvent) => void | Promise<void>,
+  ): () => void {
+    this.emailQueuePersistedListeners.add(listenerArg);
+    return () => this.emailQueuePersistedListeners.delete(listenerArg);
+  }
+
+  private async notifyEmailQueuePersisted(
+    cachedEmailArg: CachedEmail,
+    reasonArg: string,
+  ): Promise<void> {
+    if (this.emailQueuePersistedListeners.size === 0) return;
+    const event: IEmailQueuePersistedEvent = {
+      cachedEmailId: cachedEmailArg.id,
+      status: cachedEmailArg.status,
+      reason: reasonArg,
+    };
+    await Promise.allSettled(
+      [...this.emailQueuePersistedListeners].map(async (listener) => await listener(event)),
+    );
   }
 
   public async drainQueueUpdates(): Promise<void> {
@@ -295,6 +394,22 @@ export class AcceptedEmailSpool {
     }
   }
 
+  /** Reconcile persisted queue traces after restart before queue recovery runs. */
+  public async recoverSmtpTransactionHistory(emailServerArg: UnifiedEmailServer): Promise<void> {
+    for (const item of (emailServerArg as TSmartMtaQueueReader).getQueueItems?.() || []) {
+      const cachedEmailId = this.getCachedEmailIdFromQueueItem(item);
+      if (!cachedEmailId || !item.smtpTransactions?.length) continue;
+      await this.runCachedEmailUpdate(cachedEmailId, async () => {
+        const cachedEmail = await CachedEmail.findById(cachedEmailId);
+        if (!cachedEmail) return;
+        for (const transaction of item.smtpTransactions || []) {
+          this.appendSmtpTransaction(cachedEmail, transaction);
+        }
+        await cachedEmail.save();
+      });
+    }
+  }
+
   /** Requeue emails left in 'queued' state by a previous process as pending. */
   public async recoverQueuedEmails(): Promise<void> {
     while (true) {
@@ -309,6 +424,7 @@ export class AcceptedEmailSpool {
         queuedEmail.status = 'pending';
         queuedEmail.nextAttempt = new Date();
         await queuedEmail.save();
+        await this.notifyEmailQueuePersisted(queuedEmail, 'email-queue-recovered');
       }
       if (queuedEmails.length < ACCEPTED_EMAIL_SPOOL_BATCH_SIZE) {
         return;
@@ -332,7 +448,7 @@ export class AcceptedEmailSpool {
           continue;
         }
         const session = this.buildCachedEmailSession(cachedEmail);
-        const rawMessage = plugins.buffer.Buffer.from(cachedEmail.rawContent || '', 'utf8');
+        const rawMessage = await this.readRawMessage(cachedEmail);
         await this.processAcceptedCachedEmail(cachedEmail, rawMessage, session, emailServer);
       }
     } finally {
@@ -349,6 +465,7 @@ export class AcceptedEmailSpool {
     cachedEmail.status = 'processing';
     cachedEmail.nextAttempt = new Date(Date.now() + ACCEPTED_EMAIL_QUEUE_LEASE_MS);
     await cachedEmail.save();
+    await this.notifyEmailQueuePersisted(cachedEmail, 'email-processing');
 
     try {
       if (plugins.buffer.Buffer.isBuffer(emailData)) {
@@ -360,13 +477,18 @@ export class AcceptedEmailSpool {
         if (handledByTypedEndpoint) {
           cachedEmail.markDelivered();
           await cachedEmail.save();
+          await this.notifyEmailQueuePersisted(cachedEmail, 'email-delivered-to-typed-endpoint');
           return;
         }
       }
 
       await emailServer.processEmailByMode(emailData, session);
       if (session.matchedRoute?.action.type === 'forward') {
-        cachedEmail.markDelivered();
+        const currentCachedEmail = await CachedEmail.findById(cachedEmail.id) || cachedEmail;
+        currentCachedEmail.markDelivered();
+        await currentCachedEmail.save();
+        await this.notifyEmailQueuePersisted(currentCachedEmail, 'email-forwarded');
+        return;
       } else {
         const currentCachedEmail = await CachedEmail.findById(cachedEmail.id) || cachedEmail;
         if (this.isCachedEmailTerminal(currentCachedEmail) || currentCachedEmail.status === 'deferred') {
@@ -375,13 +497,14 @@ export class AcceptedEmailSpool {
         currentCachedEmail.status = 'queued';
         currentCachedEmail.nextAttempt = new Date(Date.now() + ACCEPTED_EMAIL_QUEUE_LEASE_MS);
         await currentCachedEmail.save();
+        await this.notifyEmailQueuePersisted(currentCachedEmail, 'email-queued');
         return;
       }
-      await cachedEmail.save();
     } catch (error: unknown) {
       cachedEmail.scheduleRetry(ACCEPTED_EMAIL_RETRY_DELAY_MS);
       cachedEmail.lastError = (error as Error).message;
       await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(cachedEmail, 'email-spool-deferred');
       logger.log('warn', `Accepted email ${cachedEmail.id} deferred after SmartMTA handoff failure: ${(error as Error).message}`);
     }
   }
@@ -405,7 +528,7 @@ export class AcceptedEmailSpool {
       clientHostname: storedSession.clientHostname || '',
       mailFrom: mailFrom.address,
       rcptTo: rcptTo.map((recipient) => recipient.address),
-      emailData: cachedEmail.rawContent || '',
+      emailData: '',
       useTLS: !!storedSession.secure,
       connectionEnded: false,
       remoteAddress: storedSession.remoteAddress || '127.0.0.1',
@@ -456,6 +579,9 @@ export class AcceptedEmailSpool {
       return;
     }
     cachedEmail.attempts = Math.max(cachedEmail.attempts || 0, item.attempts || 0);
+    for (const transaction of item.smtpTransactions || []) {
+      this.appendSmtpTransaction(cachedEmail, transaction);
+    }
     this.updateSmartMtaRouteData(cachedEmail, item, status);
     if (status === 'delivered') {
       cachedEmail.markDelivered();
@@ -471,6 +597,7 @@ export class AcceptedEmailSpool {
       cachedEmail.nextAttempt = new Date(Date.now() + ACCEPTED_EMAIL_QUEUE_LEASE_MS);
     }
     await cachedEmail.save();
+    await this.notifyEmailQueuePersisted(cachedEmail, `email-queue-${status}`);
   }
 
   private async waitForPromiseToSettleWithTimeout(
@@ -538,10 +665,14 @@ export class AcceptedEmailSpool {
     if (queueItem.lastError) {
       cachedEmail.lastError = queueItem.lastError;
     }
+    for (const transaction of queueItem.smtpTransactions || []) {
+      this.appendSmtpTransaction(cachedEmail, transaction);
+    }
     this.updateSmartMtaRouteData(cachedEmail, queueItem, status);
     const smartMtaNextAttempt = queueItem.nextAttempt || new Date(Date.now() + ACCEPTED_EMAIL_RETRY_DELAY_MS);
     cachedEmail.nextAttempt = new Date(smartMtaNextAttempt.getTime() + ACCEPTED_EMAIL_QUEUE_LEASE_MS);
     await cachedEmail.save();
+    await this.notifyEmailQueuePersisted(cachedEmail, 'email-live-queue-postponed');
     return true;
   }
 
@@ -577,6 +708,81 @@ export class AcceptedEmailSpool {
     cachedEmail.routeData = JSON.stringify(routeData);
   }
 
+  public async readRawMessage(cachedEmailArg: CachedEmail): Promise<plugins.buffer.Buffer> {
+    if (cachedEmailArg.rawContentObjectKey) {
+      const blobStorage = this.dcRouterRef.getSmartMtaBlobStorageManager();
+      if (!blobStorage) {
+        throw new Error(`SmartBucket storage is unavailable for accepted email ${cachedEmailArg.id}`);
+      }
+      const rawMessage = await blobStorage.get(cachedEmailArg.rawContentObjectKey);
+      if (!rawMessage) {
+        throw new Error(`Raw RFC822 object is missing for accepted email ${cachedEmailArg.id}`);
+      }
+      return plugins.buffer.Buffer.from(rawMessage);
+    }
+    throw new Error(`Accepted email ${cachedEmailArg.id} has no raw RFC822 payload`);
+  }
+
+  public async deleteRawMessage(cachedEmailArg: CachedEmail): Promise<void> {
+    if (!cachedEmailArg.rawContentObjectKey) return;
+    const blobStorage = this.dcRouterRef.getSmartMtaBlobStorageManager();
+    if (!blobStorage) {
+      throw new Error(`SmartBucket storage is unavailable for accepted email ${cachedEmailArg.id}`);
+    }
+    await blobStorage.delete(cachedEmailArg.rawContentObjectKey);
+  }
+
+  private async persistRawMessage(cachedEmailArg: CachedEmail, rawMessageArg: string): Promise<void> {
+    const blobStorage = this.dcRouterRef.getSmartMtaBlobStorageManager();
+    if (!blobStorage) {
+      throw new Error('SmartBucket storage is required before accepting SMTP messages');
+    }
+    const objectKey = `/email/messages/${cachedEmailArg.id}.eml`;
+    const rawMessage = plugins.buffer.Buffer.from(rawMessageArg, 'utf8');
+    await blobStorage.set(objectKey, rawMessage);
+    cachedEmailArg.rawContent = undefined;
+    cachedEmailArg.rawContentObjectKey = objectKey;
+    cachedEmailArg.rawContentSize = rawMessage.length;
+  }
+
+  private runCachedEmailUpdate(
+    cachedEmailIdArg: string | undefined,
+    operationArg: () => Promise<void>,
+  ): Promise<void> {
+    if (!cachedEmailIdArg) return operationArg();
+    const previous = this.cachedEmailUpdateChains.get(cachedEmailIdArg) || Promise.resolve();
+    const current = previous.catch(() => undefined).then(operationArg);
+    this.cachedEmailUpdateChains.set(cachedEmailIdArg, current);
+    const cleanup = () => {
+      if (this.cachedEmailUpdateChains.get(cachedEmailIdArg) === current) {
+        this.cachedEmailUpdateChains.delete(cachedEmailIdArg);
+      }
+    };
+    void current.then(cleanup, cleanup);
+    return current;
+  }
+
+  private trackUpdatePromise(updatePromiseArg: Promise<void>): void {
+    this.queueUpdatePromises.add(updatePromiseArg);
+    const cleanup = () => this.queueUpdatePromises.delete(updatePromiseArg);
+    void updatePromiseArg.then(cleanup, cleanup);
+  }
+
+  private appendSmtpTransaction(
+    cachedEmailArg: CachedEmail,
+    transactionArg: ICachedEmailSmtpTransaction,
+  ): void {
+    if (typeof cachedEmailArg.appendSmtpTransaction === 'function') {
+      cachedEmailArg.appendSmtpTransaction(transactionArg);
+      return;
+    }
+    const transactions = (cachedEmailArg.smtpTransactions || []).filter(
+      (transaction) => transaction.id !== transactionArg.id,
+    );
+    transactions.push(structuredClone(transactionArg));
+    cachedEmailArg.smtpTransactions = transactions.slice(-20);
+  }
+
   private removeHeader(headers: Record<string, string>, headerName: string): void {
     const normalizedHeaderName = headerName.toLowerCase();
     for (const key of Object.keys(headers)) {

package/ts/email/classes.email-domain.manager.ts

@@ -26,6 +26,11 @@ export interface IEmailDomainManagerActionResult {
   provisioned?: number;
 }
 
+export interface IManagedDkimRepairResult {
+  repairedDomainIds: string[];
+  failedDomainIds: string[];
+}
+
 /**
  * Persists managed email domains and projects them into SmartMTA. DNS mutation
  * is delegated exclusively to MailDnsSync.
@@ -340,13 +345,23 @@ export class EmailDomainManager {
   }> {
     const doc = await EmailDomainDoc.findByDomain(domainName.toLowerCase());
     if (!doc) return { ready: true, edgeIds: [] }; // unmanaged/static domain policy
+    const repairFailure = doc.reconciliation?.errors?.find(
+      (error) => error.code === 'DKIM_KEY_REPAIR_FAILED',
+    );
+    if (repairFailure) {
+      return { ready: false, reason: repairFailure.message, edgeIds: [] };
+    }
     const activeDkim = this.getActiveDkim(doc);
     if (!activeDkim) return { ready: false, reason: 'no usable active DKIM key', edgeIds: [] };
     if (activeDkim.selector !== 'default' && !this.selectorCorrectSigningCapability) {
       return { ready: false, reason: 'SmartMTA selector-correct signing capability is unavailable', edgeIds: [] };
     }
-    if (!doc.reconciliation?.activeRevision) {
-      return { ready: false, reason: 'no validated active DNS revision', edgeIds: [] };
+    const reconciliation = doc.reconciliation;
+    if (
+      !reconciliation?.activeRevision
+      || reconciliation.activeRevision.generation !== reconciliation.desiredGeneration
+    ) {
+      return { ready: false, reason: 'no current validated active DNS revision', edgeIds: [] };
     }
     const live = await this.dcRouter.mailEdgeEligibility.resolveActiveForDomain(doc);
     if (live.edges.length === 0) {
@@ -359,6 +374,123 @@ export class EmailDomainManager {
     };
   }
 
+  /**
+   * Caller-owned repair for legacy managed domains. SmartMTA remains in
+   * validation-only mode; dcrouter explicitly owns any required key creation.
+   */
+  public async repairManagedDkimBeforeEmailStart(): Promise<IManagedDkimRepairResult> {
+    const repairedDomainIds: string[] = [];
+    const failedDomainIds: string[] = [];
+
+    await this.runMutationExclusive(async () => {
+      const dkimCreator = this.dkimCreator;
+      if (!dkimCreator) {
+        throw new Error('DKIM key creator is not ready for managed-domain repair');
+      }
+
+      for (const doc of await EmailDomainDoc.findAll()) {
+        if (doc.reconciliation?.lifecycleStatus === 'deleting') continue;
+        const currentActive = this.getActiveDkim(doc);
+        const selector = currentActive?.selector || doc.dkim?.selector || 'default';
+        const keySize = currentActive?.keySize || doc.dkim?.keySize || 2048;
+        let regenerated = false;
+        let outcome: 'repaired' | 'failed' | undefined;
+        let failureMessage: string | undefined;
+
+        try {
+          try {
+            await dkimCreator.readValidatedDKIMKeysForSelector(doc.domain, selector);
+          } catch {
+            await dkimCreator.createAndStoreDKIMKeysForSelector(doc.domain, selector, keySize);
+            await dkimCreator.readValidatedDKIMKeysForSelector(doc.domain, selector);
+            regenerated = true;
+          }
+
+          const record = await dkimCreator.getDNSRecordForSelector(doc.domain, selector);
+          const publicKey = this.extractDkimPublicKey(record?.value);
+          if (!publicKey) {
+            throw new Error('validated DKIM material produced no usable public key');
+          }
+
+          if (
+            !regenerated
+            && !this.hasDkimRepairFailure(doc)
+            && currentActive?.selector === selector
+            && currentActive.publicKey === publicKey
+            && doc.dkim?.selector === selector
+            && doc.dkim.publicKey === publicKey
+          ) {
+            continue;
+          }
+
+          const now = new Date().toISOString();
+          doc.activeDkim = {
+            selector,
+            keySize,
+            publicKey,
+            createdAt: regenerated ? now : currentActive?.createdAt || now,
+            validatedAt: now,
+          };
+          doc.dkim = {
+            ...doc.dkim,
+            selector,
+            keySize,
+            publicKey,
+            ...(regenerated ? { lastRotatedAt: now } : {}),
+          };
+          doc.dnsStatus = {
+            ...doc.dnsStatus,
+            dkim: 'unchecked',
+          };
+          doc.reconciliation = this.invalidateDkimReconciliation(
+            doc,
+            regenerated ? 'DKIM_KEY_MATERIAL_REGENERATED' : 'DKIM_KEY_MATERIAL_REPAIRED',
+            regenerated
+              ? 'Caller-managed DKIM key material was regenerated; DNS deployment must be revalidated'
+              : 'Caller-managed DKIM metadata was repaired; DNS deployment must be revalidated',
+          );
+          doc.updatedAt = now;
+          outcome = 'repaired';
+        } catch (error: unknown) {
+          const message = `Failed to repair caller-managed DKIM for ${selector}._domainkey.${doc.domain}: ${(error as Error).message}`;
+          doc.reconciliation = this.invalidateDkimReconciliation(
+            doc,
+            'DKIM_KEY_REPAIR_FAILED',
+            message,
+            false,
+          );
+          doc.dnsStatus = {
+            ...doc.dnsStatus,
+            dkim: 'invalid',
+          };
+          doc.updatedAt = new Date().toISOString();
+          outcome = 'failed';
+          failureMessage = message;
+        }
+
+        // Persistence failures are global prerequisites, not per-domain key
+        // failures. Keep this save outside the material-repair catch.
+        await doc.save();
+        if (outcome === 'repaired') {
+          repairedDomainIds.push(doc.id);
+        } else if (outcome === 'failed') {
+          failedDomainIds.push(doc.id);
+          logger.log('error', failureMessage!);
+        }
+      }
+
+      await this.syncManagedDomainsToRuntime({ excludeDkimRepairFailures: true });
+    });
+
+    if (repairedDomainIds.length > 0) {
+      this.dcRouter.mailDnsSync?.requestSync(
+        'caller-managed DKIM material repaired before SmartMTA start',
+        [...new Set(repairedDomainIds)],
+      );
+    }
+    return { repairedDomainIds, failedDomainIds };
+  }
+
   public async requestDkimRotation(id: string): Promise<IEmailDomainManagerActionResult> {
     const mutation = await this.runMutationExclusive(async () => {
       const doc = await EmailDomainDoc.findById(id);
@@ -472,6 +604,45 @@ export class EmailDomainManager {
     };
   }
 
+  private invalidateDkimReconciliation(
+    doc: EmailDomainDoc,
+    code: string,
+    message: string,
+    retryable = true,
+  ) {
+    const previous = doc.reconciliation || {
+      lifecycleStatus: 'pending' as const,
+      desiredGeneration: 0,
+      intents: [],
+      errors: [],
+    };
+    const {
+      activeRevision: _activeRevision,
+      pendingRevision: _pendingRevision,
+      intents: _intents,
+      errors: _errors,
+      lastSuccessAt: _lastSuccessAt,
+      retryAt: _retryAt,
+      ...preserved
+    } = previous;
+    const alreadyInvalidated = (
+      !previous.activeRevision
+      && previous.errors.length === 1
+      && previous.errors[0].code === code
+      && previous.errors[0].message === message
+    );
+    return {
+      ...preserved,
+      lifecycleStatus: retryable ? 'pending' as const : 'failed' as const,
+      desiredGeneration: alreadyInvalidated
+        ? previous.desiredGeneration
+        : previous.desiredGeneration + 1,
+      intents: [],
+      errors: [{ code, message, retryable }],
+      ...(retryable ? { retryAt: new Date().toISOString() } : {}),
+    };
+  }
+
   private capabilityError(code: string, message: string): Error {
     const error = new Error(message) as Error & Record<string, unknown>;
     error.code = code;
@@ -545,17 +716,23 @@ export class EmailDomainManager {
       .sort((left, right) => right.name.length - left.name.length)[0] || null;
   }
 
-  private async buildManagedDomainConfigs(): Promise<IEmailDomainConfig[]> {
+  private async buildManagedDomainConfigs(optionsArg: {
+    excludeDkimRepairFailures?: boolean;
+  } = {}): Promise<IEmailDomainConfig[]> {
     const docs = await EmailDomainDoc.findAll();
     const managedConfigs: IEmailDomainConfig[] = [];
     for (const doc of docs) {
       if (doc.reconciliation?.lifecycleStatus === 'deleting') continue;
+      const dkimRepairFailed = this.hasDkimRepairFailure(doc);
+      if (dkimRepairFailed && optionsArg.excludeDkimRepairFailures) continue;
       if (!await DomainDoc.findById(doc.linkedDomainId)) {
         logger.log('warn', `Managed email domain ${doc.domain} has no linked DNS domain; keeping it out of runtime`);
         continue;
       }
       const activeDkim = this.getActiveDkim(doc);
-      const dkimConfig = activeDkim && (activeDkim.selector === 'default' || this.selectorCorrectSigningCapability)
+      const dkimConfig = !dkimRepairFailed
+        && activeDkim
+        && (activeDkim.selector === 'default' || this.selectorCorrectSigningCapability)
         ? {
             selector: activeDkim.selector,
             keySize: activeDkim.keySize,
@@ -574,13 +751,24 @@ export class EmailDomainManager {
     return managedConfigs;
   }
 
-  public async syncManagedDomainsToRuntime(): Promise<void> {
+  public async syncManagedDomainsToRuntime(optionsArg: {
+    excludeDkimRepairFailures?: boolean;
+  } = {}): Promise<void> {
     if (!this.dcRouter.options?.emailConfig) return;
+    const failedDomainNames = new Set(
+      (await EmailDomainDoc.findAll())
+        .filter((doc) => this.hasDkimRepairFailure(doc))
+        .map((doc) => doc.domain.toLowerCase()),
+    );
     const mergedDomains = new Map<string, IEmailDomainConfig>();
     for (const domainConfig of this.baseEmailDomains) {
-      mergedDomains.set(domainConfig.domain.toLowerCase(), JSON.parse(JSON.stringify(domainConfig)) as IEmailDomainConfig);
+      const key = domainConfig.domain.toLowerCase();
+      if (failedDomainNames.has(key) && optionsArg.excludeDkimRepairFailures) continue;
+      const projectedConfig = JSON.parse(JSON.stringify(domainConfig)) as IEmailDomainConfig;
+      if (failedDomainNames.has(key)) delete projectedConfig.dkim;
+      mergedDomains.set(key, projectedConfig);
     }
-    for (const managedConfig of await this.buildManagedDomainConfigs()) {
+    for (const managedConfig of await this.buildManagedDomainConfigs(optionsArg)) {
       const key = managedConfig.domain.toLowerCase();
       if (mergedDomains.has(key)) {
         logger.log('warn', `Managed email domain ${managedConfig.domain} duplicates a configured domain; keeping the configured definition`);
@@ -592,4 +780,10 @@ export class EmailDomainManager {
     this.dcRouter.options.emailConfig.domains = domains;
     this.dcRouter.emailServer?.updateOptions({ domains });
   }
+
+  private hasDkimRepairFailure(doc: EmailDomainDoc): boolean {
+    return (doc.reconciliation?.errors || []).some(
+      (error) => error.code === 'DKIM_KEY_REPAIR_FAILED',
+    );
+  }
 }

package/ts/email/classes.email-settings.manager.ts

@@ -155,7 +155,7 @@ export class EmailSettingsManager {
     const nextConfig: IUnifiedEmailServerOptions | undefined = clonePlain(existingConfig) || (nextEnabled ? {
       hostname: 'localhost',
       ports: [...defaultEmailPorts],
-      queue: { storageMode: 'memory' },
+      queue: { storageMode: 'managed' },
       domains: [],
       routes: [],
     } : undefined);