@serve.zone/dcrouter 16.4.1 → 17.0.0

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

@@ -4,22 +4,40 @@ import { logger } from '../logger.js';
 import { EmailDomainDoc } from '../db/documents/classes.email-domain.doc.js';
 import { DomainDoc } from '../db/documents/classes.domain.doc.js';
 import { DnsRecordDoc } from '../db/documents/classes.dns-record.doc.js';
-import type { DnsManager } from '../dns/manager.dns.js';
-import type { IEmailDomain, IEmailDnsRecord, IEmailDomainRemoteIngress, TDnsRecordStatus } from '../../ts_interfaces/data/email-domain.js';
-import type { IRemoteIngress } from '../../ts_interfaces/data/remoteingress.js';
-import { buildEmailDnsRecords } from './email-dns-records.js';
+import type {
+  IEmailDomain,
+  IEmailDnsRecord,
+  IEmailDomainRemoteIngress,
+  IEmailDkimMaterial,
+  IEmailDomainOperationError,
+  TEmailDomainLifecycleStatus,
+} from '../../ts_interfaces/data/email-domain.js';
+
+export interface IEmailDomainManagerActionResult {
+  success: boolean;
+  message?: string;
+  lifecycleStatus?: TEmailDomainLifecycleStatus;
+  code?: string;
+  errors?: IEmailDomainOperationError[];
+  retryAt?: string;
+  capability?: 'supported' | 'unsupported';
+  domain?: IEmailDomain;
+  records?: IEmailDnsRecord[];
+  provisioned?: number;
+}
 
 /**
- * EmailDomainManager — orchestrates email domain setup.
- *
- * Wires smartmta's DKIMCreator (key generation) with dcrouter's DnsManager
- * (record creation for dcrouter-hosted and provider-managed zones) to provide
- * a single entry point for setting up an email domain from A to Z.
+ * Persists managed email domains and projects them into SmartMTA. DNS mutation
+ * is delegated exclusively to MailDnsSync.
  */
 export class EmailDomainManager {
   private dcRouter: any; // DcRouter — avoids circular import
   private baseEmailDomains: IEmailDomainConfig[] = [];
-  private dnsClient?: plugins.smartdns.dnsClientMod.Smartdns;
+  private mutationChain: Promise<unknown> = Promise.resolve();
+  /** Explicit upstream capability marker; absence is deliberately fail-closed. */
+  private get selectorCorrectSigningCapability(): boolean {
+    return (plugins.smartmta as any).smartMtaCapabilities?.selectorCorrectDkimSigning === true;
+  }
 
   constructor(dcRouterRef: any) {
     this.dcRouter = dcRouterRef;
@@ -31,34 +49,33 @@ export class EmailDomainManager {
       .map((domainConfig) => JSON.parse(JSON.stringify(domainConfig)) as IEmailDomainConfig);
   }
 
-  private get dnsManager(): DnsManager | undefined {
-    return this.dcRouter.dnsManager;
-  }
-
   private get dkimCreator(): any | undefined {
     return this.dcRouter.emailServer?.dkimCreator;
   }
 
-  private get emailHostname(): string {
-    return this.dcRouter.options?.emailConfig?.hostname || this.dcRouter.options?.tls?.domain || 'localhost';
-  }
-
   public async start(): Promise<void> {
+    // Inbound projection is safe before the SMTP server exists. DNS scheduling
+    // starts later, after DNS, RemoteIngress, tunnel, and DKIM dependencies.
     await this.syncManagedDomainsToRuntime();
   }
 
   public async stop(): Promise<void> {
-    this.dnsClient?.destroy();
-    this.dnsClient = undefined;
+    await this.mutationChain.catch(() => undefined);
+  }
+
+  public supportsSelectorCorrectSigning(): boolean {
+    return this.selectorCorrectSigningCapability;
   }
 
-  // ---------------------------------------------------------------------------
-  // CRUD
-  // ---------------------------------------------------------------------------
+  private async runMutationExclusive<T>(action: () => Promise<T>): Promise<T> {
+    const result = this.mutationChain.catch(() => undefined).then(action);
+    this.mutationChain = result.then(() => undefined, () => undefined);
+    return await result;
+  }
 
   public async getAll(): Promise<IEmailDomain[]> {
     const docs = await EmailDomainDoc.findAll();
-    return docs.map((d) => this.docToInterface(d));
+    return docs.map((doc) => this.docToInterface(doc));
   }
 
   public async getById(id: string): Promise<IEmailDomain | null> {
@@ -76,19 +93,12 @@ export class EmailDomainManager {
     const existing = await this.getByDomain(normalizedDomain);
     if (existing) return existing;
     if (this.isDomainAlreadyConfigured(normalizedDomain)) return null;
-
     const linkedDomain = await this.findLinkedDnsDomain(normalizedDomain);
-    if (!linkedDomain) {
-      throw new Error(`DNS domain not found for email domain: ${normalizedDomain}`);
-    }
-
+    if (!linkedDomain) throw new Error(`DNS domain not found for email domain: ${normalizedDomain}`);
     const subdomain = normalizedDomain === linkedDomain.name
       ? undefined
       : normalizedDomain.slice(0, -(linkedDomain.name.length + 1));
-    return await this.createEmailDomain({
-      linkedDomainId: linkedDomain.id,
-      subdomain,
-    });
+    return await this.createEmailDomain({ linkedDomainId: linkedDomain.id, subdomain });
   }
 
   public async createEmailDomain(opts: {
@@ -100,71 +110,100 @@ export class EmailDomainManager {
     rotationIntervalDays?: number;
     remoteIngress?: IEmailDomainRemoteIngress;
   }): Promise<IEmailDomain> {
-    // Resolve the linked DNS domain
-    const domainDoc = await DomainDoc.findById(opts.linkedDomainId);
-    if (!domainDoc) {
-      throw new Error(`DNS domain not found: ${opts.linkedDomainId}`);
-    }
-    const baseDomain = domainDoc.name;
-    const subdomain = opts.subdomain?.trim() || undefined;
-    const domainName = subdomain ? `${subdomain}.${baseDomain}` : baseDomain;
-
-    // Check for duplicates
-    if (this.isDomainAlreadyConfigured(domainName)) {
-      throw new Error(`Email domain already configured for ${domainName}`);
-    }
-    const existing = await EmailDomainDoc.findByDomain(domainName);
-    if (existing) {
-      throw new Error(`Email domain already exists for ${domainName}`);
-    }
+    const created = await this.runMutationExclusive(async () => {
+      const domainDoc = await DomainDoc.findById(opts.linkedDomainId);
+      if (!domainDoc) throw new Error(`DNS domain not found: ${opts.linkedDomainId}`);
+      const subdomain = opts.subdomain?.trim().toLowerCase() || undefined;
+      const domainName = (subdomain ? `${subdomain}.${domainDoc.name}` : domainDoc.name).toLowerCase();
+      if (this.isDomainAlreadyConfigured(domainName)) {
+        throw new Error(`Email domain already configured for ${domainName}`);
+      }
+      if (await EmailDomainDoc.findByDomain(domainName)) {
+        throw new Error(`Email domain already exists for ${domainName}`);
+      }
 
-    const selector = opts.dkimSelector || 'default';
-    const keySize = opts.dkimKeySize || 2048;
-    const now = new Date().toISOString();
+      const selector = opts.dkimSelector?.trim() || 'default';
+      if (selector !== 'default' && !this.selectorCorrectSigningCapability) {
+        throw this.capabilityError(
+          'SMARTMTA_SELECTOR_SIGNING_UNSUPPORTED',
+          'Custom DKIM selectors are disabled until the selector-correct SmartMTA release is consumed',
+        );
+      }
+      if (opts.rotateKeys && !this.selectorCorrectSigningCapability) {
+        throw this.capabilityError(
+          'SMARTMTA_DKIM_ROTATION_UNSUPPORTED',
+          'Automatic DKIM rotation is disabled until the selector-correct SmartMTA release is consumed',
+        );
+      }
+      if (!this.dkimCreator) {
+        throw new Error('DKIM key creator is not ready; email domain was not persisted');
+      }
+      const keySize = opts.dkimKeySize || 2048;
+      await this.dkimCreator.handleDKIMKeysForSelector(domainName, selector, keySize);
+      const dnsRecord = await this.dkimCreator.getDNSRecordForDomain(domainName, selector);
+      const publicKey = this.extractDkimPublicKey(dnsRecord?.value);
+      if (!publicKey) {
+        throw new Error(`DKIM key generation for ${domainName} returned no usable public key; email domain was not persisted`);
+      }
 
-    // Generate DKIM keys
-    let publicKey: string | undefined;
-    if (this.dkimCreator) {
+      const now = new Date().toISOString();
+      const activeDkim: IEmailDkimMaterial = {
+        selector,
+        keySize,
+        publicKey,
+        createdAt: now,
+      };
+      const doc = new EmailDomainDoc();
+      doc.id = plugins.smartunique.shortId();
+      doc.domain = domainName;
+      doc.linkedDomainId = opts.linkedDomainId;
+      doc.subdomain = subdomain;
+      doc.dkim = {
+        selector,
+        keySize,
+        publicKey,
+        rotateKeys: opts.rotateKeys ?? false,
+        rotationIntervalDays: opts.rotationIntervalDays ?? 90,
+        retirementOverlapDays: 30,
+      };
+      doc.activeDkim = activeDkim;
+      doc.retiringDkim = [];
+      doc.remoteIngress = this.normalizeRemoteIngressPin(opts.remoteIngress, domainName);
+      doc.dnsStatus = { mx: 'unchecked', spf: 'unchecked', dkim: 'unchecked', dmarc: 'unchecked' };
+      doc.reconciliation = {
+        lifecycleStatus: 'pending',
+        desiredGeneration: 1,
+        intents: [],
+        errors: [{
+          code: 'RECONCILIATION_PENDING',
+          message: 'Initial DNS reconciliation has not completed',
+          retryable: true,
+        }],
+        capability: {
+          egressIdentityProof: 'unsupported',
+          selectorCorrectSigning: selector === 'default' || this.selectorCorrectSigningCapability
+            ? 'supported'
+            : 'unsupported',
+        },
+      };
+      doc.createdAt = now;
+      doc.updatedAt = now;
       try {
-        await this.dkimCreator.handleDKIMKeysForSelector(domainName, selector, keySize);
-        const dnsRecord = await this.dkimCreator.getDNSRecordForDomain(domainName, selector);
-        // Extract public key from the DNS record value
-        const match = dnsRecord?.value?.match(/p=([A-Za-z0-9+/=]+)/);
-        publicKey = match ? match[1] : undefined;
-        logger.log('info', `DKIM keys generated for ${domainName} (selector: ${selector})`);
-      } catch (err: unknown) {
-        logger.log('warn', `DKIM key generation failed for ${domainName}: ${(err as Error).message}`);
+        await doc.save();
+      } catch (error: unknown) {
+        if ((error as any)?.code === 11000 || (error as any)?.codeName === 'DuplicateKey') {
+          throw new Error(`Email domain already exists for ${domainName}`);
+        }
+        throw error;
       }
-    }
-
-    // Create the document
-    const doc = new EmailDomainDoc();
-    doc.id = plugins.smartunique.shortId();
-    doc.domain = domainName.toLowerCase();
-    doc.linkedDomainId = opts.linkedDomainId;
-    doc.subdomain = subdomain;
-    doc.dkim = {
-      selector,
-      keySize,
-      publicKey,
-      rotateKeys: opts.rotateKeys ?? false,
-      rotationIntervalDays: opts.rotationIntervalDays ?? 90,
-    };
-    doc.dnsStatus = {
-      mx: 'unchecked',
-      spf: 'unchecked',
-      dkim: 'unchecked',
-      dmarc: 'unchecked',
-    };
-    doc.remoteIngress = this.normalizeRemoteIngressPin(opts.remoteIngress, domainName);
-    doc.createdAt = now;
-    doc.updatedAt = now;
-    await doc.save();
-    await this.syncManagedDomainsToRuntime();
-    this.dcRouter.mailDnsSync?.requestSync(`email domain created: ${domainName}`);
-
-    logger.log('info', `Email domain created: ${domainName}`);
-    return this.docToInterface(doc);
+      await this.syncManagedDomainsToRuntime();
+      return { id: doc.id, domainName };
+    });
+    await this.dcRouter.mailDnsSync?.sync(`email domain created: ${created.domainName}`);
+    const current = await EmailDomainDoc.findById(created.id);
+    if (!current) throw new Error(`Email domain disappeared during reconciliation: ${created.domainName}`);
+    logger.log('info', `Email domain created in ${current.reconciliation?.lifecycleStatus || 'pending'} state: ${created.domainName}`);
+    return this.docToInterface(current);
   }
 
   public async updateEmailDomain(
@@ -173,292 +212,307 @@ export class EmailDomainManager {
       rotateKeys?: boolean;
       rotationIntervalDays?: number;
       rateLimits?: IEmailDomain['rateLimits'];
-      /** null clears the pin. */
       remoteIngress?: IEmailDomainRemoteIngress | null;
     },
-  ): Promise<void> {
-    const doc = await EmailDomainDoc.findById(id);
-    if (!doc) throw new Error(`Email domain not found: ${id}`);
-
-    if (changes.rotateKeys !== undefined) doc.dkim.rotateKeys = changes.rotateKeys;
-    if (changes.rotationIntervalDays !== undefined) doc.dkim.rotationIntervalDays = changes.rotationIntervalDays;
-    if (changes.rateLimits !== undefined) doc.rateLimits = changes.rateLimits;
-    if (changes.remoteIngress !== undefined) {
-      doc.remoteIngress = changes.remoteIngress === null
-        ? undefined
-        : this.normalizeRemoteIngressPin(changes.remoteIngress, doc.domain);
-    }
-    doc.updatedAt = new Date().toISOString();
-    await doc.save();
-    await this.syncManagedDomainsToRuntime();
-    this.dcRouter.mailDnsSync?.requestSync(`email domain updated: ${doc.domain}`);
+  ): Promise<IEmailDomainManagerActionResult> {
+    const mutation = await this.runMutationExclusive(async () => {
+      const doc = await EmailDomainDoc.findById(id);
+      if (!doc) throw new Error(`Email domain not found: ${id}`);
+      if (changes.rotateKeys === true && !this.selectorCorrectSigningCapability) {
+        return {
+          kind: 'result' as const,
+          result: this.unsupportedResult(
+            doc,
+            'SMARTMTA_DKIM_ROTATION_UNSUPPORTED',
+            'Automatic DKIM rotation is disabled until the selector-correct SmartMTA release is consumed',
+          ),
+        };
+      }
+      if (changes.rotateKeys !== undefined) doc.dkim.rotateKeys = changes.rotateKeys;
+      if (changes.rotationIntervalDays !== undefined) doc.dkim.rotationIntervalDays = changes.rotationIntervalDays;
+      if (changes.rateLimits !== undefined) doc.rateLimits = changes.rateLimits;
+      if (changes.remoteIngress !== undefined) {
+        doc.remoteIngress = changes.remoteIngress === null
+          ? undefined
+          : this.normalizeRemoteIngressPin(changes.remoteIngress, doc.domain);
+      }
+      doc.reconciliation = this.invalidateReconciliation(doc, 'EMAIL_DOMAIN_CONFIGURATION_CHANGED');
+      doc.updatedAt = new Date().toISOString();
+      await doc.save();
+      await this.syncManagedDomainsToRuntime();
+      return { kind: 'sync' as const, domainName: doc.domain };
+    });
+    if (mutation.kind === 'result') return mutation.result;
+    await this.dcRouter.mailDnsSync?.sync(`email domain updated: ${mutation.domainName}`);
+    const current = await EmailDomainDoc.findById(id);
+    if (!current) throw new Error(`Email domain disappeared during reconciliation: ${id}`);
+    return this.resultForDoc(current, !this.hasDnsMutationFailure(current));
   }
 
-  /**
-   * Normalize a per-domain edge pin. Pins may reference edges that are not
-   * registered yet — that only warns, so pins can precede edge registration.
-   */
-  private normalizeRemoteIngressPin(
-    pin: IEmailDomainRemoteIngress | undefined,
-    domainName: string,
-  ): IEmailDomainRemoteIngress | undefined {
-    const edgeFilter = [...new Set((pin?.edgeFilter || []).map((entry) => `${entry}`.trim()).filter(Boolean))];
-    if (edgeFilter.length === 0) {
-      return undefined;
-    }
-    const manager = this.dcRouter.remoteIngressManager;
-    if (manager && manager.resolveEdgesByFilter(edgeFilter).length === 0) {
-      logger.log('warn', `Email domain ${domainName}: edge pin [${edgeFilter.join(', ')}] matches no registered enabled edge yet`);
+  public async deleteEmailDomain(id: string): Promise<IEmailDomainManagerActionResult> {
+    const mutation = await this.runMutationExclusive(async () => {
+      const doc = await EmailDomainDoc.findById(id);
+      if (!doc) throw new Error(`Email domain not found: ${id}`);
+      const bindings = await this.dcRouter.workAppMailManager?.listMailAddressBindings({ domain: doc.domain }) || [];
+      if (bindings.length > 0) {
+        return {
+          kind: 'result' as const,
+          result: {
+            success: false,
+            lifecycleStatus: doc.reconciliation?.lifecycleStatus || 'pending',
+            code: 'EMAIL_DOMAIN_HAS_BINDINGS',
+            message: `Email domain ${doc.domain} still has ${bindings.length} WorkApp mail binding(s)`,
+            errors: [{
+              code: 'EMAIL_DOMAIN_HAS_BINDINGS',
+              message: 'Delete all WorkApp mail bindings before deleting the email domain',
+              retryable: false,
+            }],
+          } satisfies IEmailDomainManagerActionResult,
+        };
+      }
+      const now = new Date().toISOString();
+      doc.reconciliation = {
+        ...(doc.reconciliation || { desiredGeneration: 1, intents: [], errors: [] }),
+        lifecycleStatus: 'deleting',
+        intents: [],
+        errors: [],
+        deletingAt: now,
+        retryAt: new Date(Date.now() + 300_000).toISOString(),
+      };
+      doc.updatedAt = now;
+      await doc.save();
+      await this.syncManagedDomainsToRuntime();
+      return { kind: 'sync' as const, domainName: doc.domain };
+    });
+    if (mutation.kind === 'result') return mutation.result;
+    await this.dcRouter.mailDnsSync?.sync(`email domain deleting: ${mutation.domainName}`);
+    const remaining = await EmailDomainDoc.findById(id);
+    if (!remaining) {
+      return { success: true, lifecycleStatus: 'deleting', message: `Email domain ${mutation.domainName} deleted` };
     }
-    return { edgeFilter };
+    return this.resultForDoc(remaining, remaining.reconciliation?.errors.length === 0);
   }
 
-  /** Enabled edges pinned for this domain (empty when unpinned). */
-  private resolvePinnedEdges(doc: EmailDomainDoc): IRemoteIngress[] {
-    const edgeFilter = doc.remoteIngress?.edgeFilter;
-    if (!edgeFilter?.length) {
-      return [];
-    }
-    return this.dcRouter.remoteIngressManager?.resolveEdgesByFilter(edgeFilter) || [];
+  public async getRequiredDnsRecords(id: string): Promise<IEmailDnsRecord[]> {
+    const doc = await EmailDomainDoc.findById(id);
+    if (!doc) throw new Error(`Email domain not found: ${id}`);
+    return (doc.reconciliation?.intents || []).map((intent) => ({
+      type: intent.type,
+      name: intent.name,
+      value: intent.value,
+      status: intent.status === 'valid'
+        ? 'valid'
+        : intent.status === 'conflict' || intent.status === 'failed'
+          ? 'invalid'
+          : 'missing',
+    }));
   }
 
-  public async deleteEmailDomain(id: string): Promise<void> {
+  public async provisionDnsRecords(id: string): Promise<IEmailDomainManagerActionResult> {
+    const before = new Set(
+      (await DnsRecordDoc.findAll()).filter((record) => record.managedBy === 'mail-dns-reconciler').map((record) => record.id),
+    );
+    await this.dcRouter.mailDnsSync?.sync(`manual provision: ${id}`);
     const doc = await EmailDomainDoc.findById(id);
     if (!doc) throw new Error(`Email domain not found: ${id}`);
-    await doc.delete();
-    await this.syncManagedDomainsToRuntime();
-    this.dcRouter.mailDnsSync?.requestSync(`email domain deleted: ${doc.domain}`);
-    logger.log('info', `Email domain deleted: ${doc.domain}`);
+    const provisioned = (await DnsRecordDoc.findAll())
+      .filter((record) => record.managedBy === 'mail-dns-reconciler' && !before.has(record.id)).length;
+    return { ...this.resultForDoc(doc, !this.hasDnsMutationFailure(doc)), provisioned };
   }
 
-  // ---------------------------------------------------------------------------
-  // DNS record computation
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Compute the 4 required DNS records for an email domain.
-   */
-  public async getRequiredDnsRecords(id: string): Promise<IEmailDnsRecord[]> {
+  public async validateDns(id: string): Promise<IEmailDomainManagerActionResult> {
+    await this.dcRouter.mailDnsSync?.sync(`manual validation: ${id}`);
     const doc = await EmailDomainDoc.findById(id);
     if (!doc) throw new Error(`Email domain not found: ${id}`);
+    const records = await this.getRequiredDnsRecords(id);
+    return {
+      ...this.resultForDoc(doc, doc.reconciliation?.lifecycleStatus === 'active'),
+      domain: this.docToInterface(doc),
+      records,
+    };
+  }
 
-    const domain = doc.domain;
-    const selector = doc.dkim.selector;
-    // Pinned domains get their own MX host whose A records are the pinned edges'
-    // public IPs; unpinned domains use the shared mail hostname.
-    const pinnedEdges = this.resolvePinnedEdges(doc);
-    const hostname = pinnedEdges.length > 0 ? `mx.${domain}` : this.emailHostname;
-    let dkimValue = `v=DKIM1; h=sha256; k=rsa; p=${doc.dkim.publicKey || ''}`;
-
-    if (this.dkimCreator) {
-      try {
-        const dnsRecord = await this.dkimCreator.getDNSRecordForDomain(domain, selector);
-        dkimValue = dnsRecord.value;
-      } catch (err: unknown) {
-        logger.log('warn', `Failed to load DKIM DNS record for ${domain}: ${(err as Error).message}`);
-      }
+  public async getOutboundReadiness(domainName: string): Promise<{
+    ready: boolean;
+    reason?: string;
+    edgeIds: string[];
+    selector?: string;
+  }> {
+    const doc = await EmailDomainDoc.findByDomain(domainName.toLowerCase());
+    if (!doc) return { ready: true, edgeIds: [] }; // unmanaged/static domain policy
+    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: [] };
     }
-
-    const records = buildEmailDnsRecords({
-      domain,
-      hostname,
-      selector,
-      dkimValue,
-      statuses: doc.dnsStatus,
-    });
-
-    for (const edge of pinnedEdges) {
-      if (edge.publicIp) {
-        records.push({ type: 'A', name: hostname, value: edge.publicIp, status: doc.dnsStatus.mx });
-      }
-      if (edge.publicIpV6) {
-        records.push({ type: 'AAAA', name: hostname, value: edge.publicIpV6, status: doc.dnsStatus.mx });
-      }
+    if (!doc.reconciliation?.activeRevision) {
+      return { ready: false, reason: 'no validated active DNS revision', edgeIds: [] };
     }
-
-    return records;
+    const live = await this.dcRouter.mailEdgeEligibility.resolveActiveForDomain(doc);
+    if (live.edges.length === 0) {
+      return { ready: false, reason: live.reason || 'no validated active egress edge is live', edgeIds: [] };
+    }
+    return {
+      ready: true,
+      edgeIds: live.edges.map((candidate: any) => candidate.edge.id),
+      selector: activeDkim.selector,
+    };
   }
 
-  // ---------------------------------------------------------------------------
-  // DNS provisioning
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Auto-create missing DNS records via the linked domain's DNS path.
-   */
-  public async provisionDnsRecords(id: string): Promise<number> {
-    const doc = await EmailDomainDoc.findById(id);
-    if (!doc) throw new Error(`Email domain not found: ${id}`);
-    if (!this.dnsManager) throw new Error('DnsManager not available');
-
-    const requiredRecords = await this.getRequiredDnsRecords(id);
-    const domainId = doc.linkedDomainId;
-
-    // Get existing DNS records for the linked domain
-    const existingRecords = await DnsRecordDoc.findByDomainId(domainId);
-    let provisioned = 0;
-
-    for (const required of requiredRecords) {
-      // Check if a matching record already exists
-      const exists = existingRecords.some((r) => this.recordMatchesRequired(r, required));
-
-      if (!exists) {
-        try {
-          await this.dnsManager.createRecord({
-            domainId,
-            name: required.name,
-            type: required.type as any,
-            value: required.value,
-            ttl: 3600,
-            createdBy: 'email-domain-manager',
-          });
-          provisioned++;
-          logger.log('info', `Provisioned ${required.type} record for ${required.name}`);
-        } catch (err: unknown) {
-          logger.log('warn', `Failed to provision ${required.type} for ${required.name}: ${(err as Error).message}`);
-        }
+  public async requestDkimRotation(id: string): Promise<IEmailDomainManagerActionResult> {
+    const mutation = await this.runMutationExclusive(async () => {
+      const doc = await EmailDomainDoc.findById(id);
+      if (!doc) throw new Error(`Email domain not found: ${id}`);
+      if (!this.selectorCorrectSigningCapability) {
+        return {
+          kind: 'result' as const,
+          result: this.unsupportedResult(
+            doc,
+            'SMARTMTA_DKIM_ROTATION_UNSUPPORTED',
+            'DKIM rotation remains pending until the selector-correct SmartMTA release is consumed',
+          ),
+        };
       }
-    }
-
-    // Re-validate after provisioning
-    await this.validateDns(id);
-
-    return provisioned;
+      if (doc.pendingDkim) {
+        return {
+          kind: 'result' as const,
+          result: {
+            ...this.resultForDoc(doc, true),
+            message: `Selector ${doc.pendingDkim.selector} is already staged`,
+          },
+        };
+      }
+      await this.stageDkimRotation(doc);
+      return { kind: 'sync' as const, domainName: doc.domain };
+    });
+    if (mutation.kind === 'result') return mutation.result;
+    await this.dcRouter.mailDnsSync?.sync(`DKIM rotation staged: ${mutation.domainName}`);
+    const current = await EmailDomainDoc.findById(id);
+    if (!current) throw new Error(`Email domain disappeared during reconciliation: ${id}`);
+    return this.resultForDoc(current, !this.hasDnsMutationFailure(current));
   }
 
-  // ---------------------------------------------------------------------------
-  // DNS validation
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Validate DNS records via live lookups.
-   */
-  public async validateDns(id: string): Promise<IEmailDnsRecord[]> {
-    const doc = await EmailDomainDoc.findById(id);
-    if (!doc) throw new Error(`Email domain not found: ${id}`);
-
-    const domain = doc.domain;
-    const selector = doc.dkim.selector;
-    const dnsClient = this.getDnsClient();
-
-    // MX check
-    const requiredRecords = await this.getRequiredDnsRecords(id);
-
-    const mxRecord = requiredRecords.find((record) => record.type === 'MX');
-    const spfRecord = requiredRecords.find((record) => record.name === domain && record.value.startsWith('v=spf1'));
-    const dkimRecord = requiredRecords.find((record) => record.name === `${selector}._domainkey.${domain}`);
-    const dmarcRecord = requiredRecords.find((record) => record.name === `_dmarc.${domain}`);
-
-    doc.dnsStatus.mx = await this.checkMx(dnsClient, domain, mxRecord?.value);
-
-    // Pinned domains: the MX host's A records must cover the pinned edges' IPs.
-    const requiredARecords = requiredRecords.filter((record) => record.type === 'A');
-    if (doc.dnsStatus.mx === 'valid' && requiredARecords.length > 0) {
-      const mxHostname = mxRecord?.value?.split(/\s+/)[1] || `mx.${domain}`;
-      const aStatus = await this.checkARecords(dnsClient, mxHostname, requiredARecords.map((record) => record.value));
-      if (aStatus !== 'valid') {
-        doc.dnsStatus.mx = aStatus;
+  /** Called by the reconciler before planning so scheduled external rotation is durable first. */
+  public async stageDkimRotationIfDue(id: string): Promise<EmailDomainDoc | undefined> {
+    return await this.runMutationExclusive(async () => {
+      const doc = await EmailDomainDoc.findById(id);
+      if (!doc || !doc.dkim.rotateKeys || doc.pendingDkim || !this.selectorCorrectSigningCapability) {
+        return doc || undefined;
       }
-    }
-
-    // SPF check
-    doc.dnsStatus.spf = await this.checkTxtRecord(dnsClient, domain, spfRecord?.value);
-
-    // DKIM check
-    doc.dnsStatus.dkim = await this.checkTxtRecord(dnsClient, `${selector}._domainkey.${domain}`, dkimRecord?.value);
-
-    // DMARC check
-    doc.dnsStatus.dmarc = await this.checkTxtRecord(dnsClient, `_dmarc.${domain}`, dmarcRecord?.value);
+      const active = this.getActiveDkim(doc);
+      const reference = Date.parse(active?.promotedAt || doc.dkim.lastRotatedAt || active?.createdAt || doc.createdAt);
+      const intervalMs = Math.max(1, doc.dkim.rotationIntervalDays || 90) * 86_400_000;
+      if (Number.isFinite(reference) && Date.now() - reference < intervalMs) return doc;
+      try {
+        await this.stageDkimRotation(doc);
+      } catch (error: unknown) {
+        doc.reconciliation = this.invalidateReconciliation(doc, 'DKIM_ROTATION_STAGE_FAILED');
+        doc.reconciliation.errors = [{
+          code: 'DKIM_ROTATION_STAGE_FAILED',
+          message: `Failed to stage DKIM rotation: ${(error as Error).message}`,
+          retryable: true,
+        }];
+        doc.updatedAt = new Date().toISOString();
+        await doc.save();
+      }
+      return doc;
+    });
+  }
 
-    doc.dnsStatus.lastCheckedAt = new Date().toISOString();
+  private async stageDkimRotation(doc: EmailDomainDoc): Promise<void> {
+    if (!this.dkimCreator) throw new Error('DKIM key creator is not ready');
+    const selector = `s${new Date().toISOString().slice(0, 10).replace(/-/g, '')}-${plugins.smartunique.shortId()}`;
+    const keySize = doc.dkim.keySize || 2048;
+    await this.dkimCreator.handleDKIMKeysForSelector(doc.domain, selector, keySize);
+    const record = await this.dkimCreator.getDNSRecordForDomain(doc.domain, selector);
+    const publicKey = this.extractDkimPublicKey(record?.value);
+    if (!publicKey) throw new Error(`DKIM rotation generated no public key for ${selector}`);
+    doc.pendingDkim = { selector, keySize, publicKey, createdAt: new Date().toISOString() };
+    doc.reconciliation = this.invalidateReconciliation(doc, 'DKIM_ROTATION_STAGED');
     doc.updatedAt = new Date().toISOString();
     await doc.save();
-
-    return this.getRequiredDnsRecords(id);
   }
 
-  private recordMatchesRequired(record: DnsRecordDoc, required: IEmailDnsRecord): boolean {
-    if (record.type !== required.type || record.name.toLowerCase() !== required.name.toLowerCase()) {
-      return false;
+  private normalizeRemoteIngressPin(
+    pin: IEmailDomainRemoteIngress | undefined,
+    domainName: string,
+  ): IEmailDomainRemoteIngress | undefined {
+    const edgeFilter = [...new Set((pin?.edgeFilter || []).map((entry) => `${entry}`.trim()).filter(Boolean))];
+    if (edgeFilter.length === 0) return undefined;
+    const manager = this.dcRouter.remoteIngressManager;
+    if (manager && manager.resolveEdgesByFilter(edgeFilter).length === 0) {
+      logger.log('warn', `Email domain ${domainName}: pin [${edgeFilter.join(', ')}] matches no enabled edge yet`);
     }
-    return record.value.trim() === required.value.trim();
+    return { edgeFilter };
   }
 
-  /** Lazy shared smartdns client; the Rust bridge spawns on first non-system lookup. */
-  private getDnsClient(): plugins.smartdns.dnsClientMod.Smartdns {
-    if (!this.dnsClient) {
-      this.dnsClient = new plugins.smartdns.dnsClientMod.Smartdns({});
-    }
-    return this.dnsClient;
+  private extractDkimPublicKey(value: unknown): string | undefined {
+    if (typeof value !== 'string') return undefined;
+    return value.match(/(?:^|;)\s*p=([A-Za-z0-9+/=]+)(?:;|$)/)?.[1];
   }
 
-  /** 'pref exchange' normalized for comparison: numeric pref, lowercased exchange, no trailing dot. */
-  private normalizeMxValue(value: string): string {
-    const [pref, exchange = ''] = value.trim().split(/\s+/);
-    return `${Number(pref)} ${exchange.toLowerCase().replace(/\.$/, '')}`;
+  private getActiveDkim(doc: EmailDomainDoc): IEmailDkimMaterial | undefined {
+    if (doc.activeDkim?.publicKey) return doc.activeDkim;
+    if (!doc.dkim?.publicKey) return undefined;
+    return {
+      selector: doc.dkim.selector || 'default',
+      keySize: doc.dkim.keySize || 2048,
+      publicKey: doc.dkim.publicKey,
+      createdAt: doc.createdAt,
+    };
   }
 
-  private async checkMx(
-    dnsClient: plugins.smartdns.dnsClientMod.Smartdns,
-    domain: string,
-    expectedValue?: string,
-  ): Promise<TDnsRecordStatus> {
-    try {
-      const records = await dnsClient.getRecords(domain, 'MX');
-      if (!records || records.length === 0) {
-        return 'missing';
-      }
-      if (!expectedValue) {
-        return 'valid';
-      }
-      const expected = this.normalizeMxValue(expectedValue);
-      const found = records.some((record) => this.normalizeMxValue(record.value) === expected);
-      return found ? 'valid' : 'invalid';
-    } catch {
-      return 'missing';
-    }
+  private invalidateReconciliation(doc: EmailDomainDoc, code: string) {
+    return {
+      ...(doc.reconciliation || { desiredGeneration: 0, intents: [], errors: [] }),
+      lifecycleStatus: doc.reconciliation?.activeRevision ? 'active' as const : 'pending' as const,
+      desiredGeneration: (doc.reconciliation?.desiredGeneration || 0) + 1,
+      errors: [{ code, message: 'DNS reconciliation is pending', retryable: true }],
+      retryAt: new Date().toISOString(),
+    };
   }
 
-  private async checkARecords(
-    dnsClient: plugins.smartdns.dnsClientMod.Smartdns,
-    name: string,
-    expectedIps: string[],
-  ): Promise<TDnsRecordStatus> {
-    try {
-      const records = await dnsClient.getRecordsA(name);
-      if (!records || records.length === 0) {
-        return 'missing';
-      }
-      const resolved = new Set(records.map((record) => record.value));
-      return expectedIps.every((ip) => resolved.has(ip)) ? 'valid' : 'invalid';
-    } catch {
-      return 'missing';
-    }
+  private capabilityError(code: string, message: string): Error {
+    const error = new Error(message) as Error & Record<string, unknown>;
+    error.code = code;
+    error.capability = 'unsupported';
+    error.errors = [{ code, message, retryable: false }];
+    return error;
   }
 
-  private async checkTxtRecord(
-    dnsClient: plugins.smartdns.dnsClientMod.Smartdns,
-    name: string,
-    expectedValue?: string,
-  ): Promise<TDnsRecordStatus> {
-    try {
-      const records = await dnsClient.getRecordsTxt(name);
-      if (!records || records.length === 0) {
-        return 'missing';
-      }
-      if (!expectedValue) {
-        return 'valid';
-      }
-      const found = records.some((record) => record.value.trim() === expectedValue.trim());
-      return found ? 'valid' : 'invalid';
-    } catch {
-      return 'missing';
-    }
+  private unsupportedResult(doc: EmailDomainDoc, code: string, message: string): IEmailDomainManagerActionResult {
+    return {
+      success: false,
+      lifecycleStatus: doc.reconciliation?.lifecycleStatus || 'pending',
+      code,
+      capability: 'unsupported',
+      message,
+      errors: [{ code, message, retryable: false }],
+    };
   }
 
-  // ---------------------------------------------------------------------------
-  // Helpers
-  // ---------------------------------------------------------------------------
+  private hasDnsMutationFailure(doc: EmailDomainDoc): boolean {
+    return (doc.reconciliation?.intents || []).some((intent) => (
+      intent.status === 'failed' || intent.status === 'conflict'
+    )) || (doc.reconciliation?.errors || []).some((error) => (
+      ['DNS_PROVIDER_ZONE_FAILED', 'DNS_UNMANAGED_CONFLICT', 'DNS_CLEANUP_FAILED'].includes(error.code)
+    ));
+  }
+
+  private resultForDoc(doc: EmailDomainDoc, actionSucceeded: boolean): IEmailDomainManagerActionResult {
+    const state = doc.reconciliation;
+    const firstError = state?.errors[0];
+    return {
+      success: actionSucceeded,
+      lifecycleStatus: state?.lifecycleStatus || 'pending',
+      message: firstError?.message,
+      code: firstError?.code,
+      errors: state?.errors,
+      retryAt: state?.retryAt,
+      capability: state?.capability?.egressIdentityProof,
+      domain: this.docToInterface(doc),
+    };
+  }
 
   private docToInterface(doc: EmailDomainDoc): IEmailDomain {
     return {
@@ -470,65 +524,62 @@ export class EmailDomainManager {
       rateLimits: doc.rateLimits,
       remoteIngress: doc.remoteIngress,
       dnsStatus: doc.dnsStatus,
+      reconciliation: doc.reconciliation,
+      activeDkim: doc.activeDkim,
+      pendingDkim: doc.pendingDkim,
+      retiringDkim: doc.retiringDkim,
       createdAt: doc.createdAt,
       updatedAt: doc.updatedAt,
     };
   }
 
   private isDomainAlreadyConfigured(domainName: string): boolean {
-    const configuredDomains = ((this.dcRouter.options?.emailConfig?.domains || []) as IEmailDomainConfig[])
-      .map((domainConfig) => domainConfig.domain.toLowerCase());
-    return configuredDomains.includes(domainName.toLowerCase());
+    return ((this.dcRouter.options?.emailConfig?.domains || []) as IEmailDomainConfig[])
+      .some((domainConfig) => domainConfig.domain.toLowerCase() === domainName.toLowerCase());
   }
 
   private async findLinkedDnsDomain(domainName: string): Promise<DomainDoc | null> {
     const domains = await DomainDoc.findAll();
     return domains
       .filter((domainDoc) => domainName === domainDoc.name || domainName.endsWith(`.${domainDoc.name}`))
-      .sort((a, b) => b.name.length - a.name.length)[0] || null;
+      .sort((left, right) => right.name.length - left.name.length)[0] || null;
   }
 
   private async buildManagedDomainConfigs(): Promise<IEmailDomainConfig[]> {
     const docs = await EmailDomainDoc.findAll();
     const managedConfigs: IEmailDomainConfig[] = [];
-
     for (const doc of docs) {
-      const linkedDomain = await DomainDoc.findById(doc.linkedDomainId);
-      if (!linkedDomain) {
-        logger.log('warn', `Skipping managed email domain ${doc.domain}: linked domain missing`);
+      if (doc.reconciliation?.lifecycleStatus === 'deleting') 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)
+        ? {
+            selector: activeDkim.selector,
+            keySize: activeDkim.keySize,
+            // Dcrouter exclusively owns staged external rotation.
+            rotateKeys: false,
+            rotationInterval: doc.dkim.rotationIntervalDays,
+          }
+        : undefined;
       managedConfigs.push({
         domain: doc.domain,
-        // Always external-dns: DcRouter owns the DNS records for managed domains
-        // (email-domain-manager DnsRecordDocs). internal-dns would make smartmta
-        // self-register a conflicting MX (exchange = the domain itself) plus
-        // duplicate SPF/DKIM TXT handlers on the shared DNS server.
         dnsMode: 'external-dns',
-        dkim: {
-          selector: doc.dkim.selector,
-          keySize: doc.dkim.keySize,
-          rotateKeys: doc.dkim.rotateKeys,
-          rotationInterval: doc.dkim.rotationIntervalDays,
-        },
+        ...(dkimConfig ? { dkim: dkimConfig } : {}),
         rateLimits: doc.rateLimits,
       });
     }
-
     return managedConfigs;
   }
 
   public async syncManagedDomainsToRuntime(): Promise<void> {
-    if (!this.dcRouter.options?.emailConfig) {
-      return;
-    }
-
+    if (!this.dcRouter.options?.emailConfig) return;
     const mergedDomains = new Map<string, IEmailDomainConfig>();
     for (const domainConfig of this.baseEmailDomains) {
       mergedDomains.set(domainConfig.domain.toLowerCase(), JSON.parse(JSON.stringify(domainConfig)) as IEmailDomainConfig);
     }
-
     for (const managedConfig of await this.buildManagedDomainConfigs()) {
       const key = managedConfig.domain.toLowerCase();
       if (mergedDomains.has(key)) {
@@ -537,11 +588,8 @@ export class EmailDomainManager {
       }
       mergedDomains.set(key, managedConfig);
     }
-
-    const domains = Array.from(mergedDomains.values());
+    const domains = [...mergedDomains.values()];
     this.dcRouter.options.emailConfig.domains = domains;
-    if (this.dcRouter.emailServer) {
-      this.dcRouter.emailServer.updateOptions({ domains });
-    }
+    this.dcRouter.emailServer?.updateOptions({ domains });
   }
 }