@serve.zone/dcrouter 15.11.0 → 16.0.1

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

@@ -5,7 +5,8 @@ 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, TDnsRecordStatus } from '../../ts_interfaces/data/email-domain.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';
 
 /**
@@ -18,6 +19,7 @@ import { buildEmailDnsRecords } from './email-dns-records.js';
 export class EmailDomainManager {
   private dcRouter: any; // DcRouter — avoids circular import
   private baseEmailDomains: IEmailDomainConfig[] = [];
+  private dnsClient?: plugins.smartdns.dnsClientMod.Smartdns;
 
   constructor(dcRouterRef: any) {
     this.dcRouter = dcRouterRef;
@@ -45,7 +47,10 @@ export class EmailDomainManager {
     await this.syncManagedDomainsToRuntime();
   }
 
-  public async stop(): Promise<void> {}
+  public async stop(): Promise<void> {
+    this.dnsClient?.destroy();
+    this.dnsClient = undefined;
+  }
 
   // ---------------------------------------------------------------------------
   // CRUD
@@ -93,6 +98,7 @@ export class EmailDomainManager {
     dkimKeySize?: number;
     rotateKeys?: boolean;
     rotationIntervalDays?: number;
+    remoteIngress?: IEmailDomainRemoteIngress;
   }): Promise<IEmailDomain> {
     // Resolve the linked DNS domain
     const domainDoc = await DomainDoc.findById(opts.linkedDomainId);
@@ -150,10 +156,12 @@ export class EmailDomainManager {
       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);
@@ -165,6 +173,8 @@ 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);
@@ -173,9 +183,43 @@ export class EmailDomainManager {
     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}`);
+  }
+
+  /**
+   * 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`);
+    }
+    return { edgeFilter };
+  }
+
+  /** 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 deleteEmailDomain(id: string): Promise<void> {
@@ -183,6 +227,7 @@ export class EmailDomainManager {
     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}`);
   }
 
@@ -199,7 +244,10 @@ export class EmailDomainManager {
 
     const domain = doc.domain;
     const selector = doc.dkim.selector;
-    const hostname = this.emailHostname;
+    // 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) {
@@ -211,13 +259,24 @@ export class EmailDomainManager {
       }
     }
 
-    return buildEmailDnsRecords({
+    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 });
+      }
+    }
+
+    return records;
   }
 
   // ---------------------------------------------------------------------------
@@ -280,7 +339,7 @@ export class EmailDomainManager {
 
     const domain = doc.domain;
     const selector = doc.dkim.selector;
-    const resolver = new plugins.dns.promises.Resolver();
+    const dnsClient = this.getDnsClient();
 
     // MX check
     const requiredRecords = await this.getRequiredDnsRecords(id);
@@ -290,16 +349,26 @@ export class EmailDomainManager {
     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(resolver, domain, mxRecord?.value);
+    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;
+      }
+    }
 
     // SPF check
-    doc.dnsStatus.spf = await this.checkTxtRecord(resolver, domain, spfRecord?.value);
+    doc.dnsStatus.spf = await this.checkTxtRecord(dnsClient, domain, spfRecord?.value);
 
     // DKIM check
-    doc.dnsStatus.dkim = await this.checkTxtRecord(resolver, `${selector}._domainkey.${domain}`, dkimRecord?.value);
+    doc.dnsStatus.dkim = await this.checkTxtRecord(dnsClient, `${selector}._domainkey.${domain}`, dkimRecord?.value);
 
     // DMARC check
-    doc.dnsStatus.dmarc = await this.checkTxtRecord(resolver, `_dmarc.${domain}`, dmarcRecord?.value);
+    doc.dnsStatus.dmarc = await this.checkTxtRecord(dnsClient, `_dmarc.${domain}`, dmarcRecord?.value);
 
     doc.dnsStatus.lastCheckedAt = new Date().toISOString();
     doc.updatedAt = new Date().toISOString();
@@ -315,41 +384,72 @@ export class EmailDomainManager {
     return record.value.trim() === required.value.trim();
   }
 
+  /** 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;
+  }
+
+  /** '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 async checkMx(
-    resolver: plugins.dns.promises.Resolver,
+    dnsClient: plugins.smartdns.dnsClientMod.Smartdns,
     domain: string,
     expectedValue?: string,
   ): Promise<TDnsRecordStatus> {
     try {
-      const records = await resolver.resolveMx(domain);
+      const records = await dnsClient.getRecords(domain, 'MX');
       if (!records || records.length === 0) {
         return 'missing';
       }
       if (!expectedValue) {
         return 'valid';
       }
-      const found = records.some((record) => `${record.priority} ${record.exchange}`.trim() === expectedValue.trim());
+      const expected = this.normalizeMxValue(expectedValue);
+      const found = records.some((record) => this.normalizeMxValue(record.value) === expected);
       return found ? 'valid' : 'invalid';
     } catch {
       return 'missing';
     }
   }
 
+  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 async checkTxtRecord(
-    resolver: plugins.dns.promises.Resolver,
+    dnsClient: plugins.smartdns.dnsClientMod.Smartdns,
     name: string,
     expectedValue?: string,
   ): Promise<TDnsRecordStatus> {
     try {
-      const records = await resolver.resolveTxt(name);
-      const flat = records.map((r) => r.join(''));
-      if (flat.length === 0) {
+      const records = await dnsClient.getRecordsTxt(name);
+      if (!records || records.length === 0) {
         return 'missing';
       }
       if (!expectedValue) {
         return 'valid';
       }
-      const found = flat.some((record) => record.trim() === expectedValue.trim());
+      const found = records.some((record) => record.value.trim() === expectedValue.trim());
       return found ? 'valid' : 'invalid';
     } catch {
       return 'missing';
@@ -368,6 +468,7 @@ export class EmailDomainManager {
       subdomain: doc.subdomain,
       dkim: doc.dkim,
       rateLimits: doc.rateLimits,
+      remoteIngress: doc.remoteIngress,
       dnsStatus: doc.dnsStatus,
       createdAt: doc.createdAt,
       updatedAt: doc.updatedAt,
@@ -400,7 +501,11 @@ export class EmailDomainManager {
 
       managedConfigs.push({
         domain: doc.domain,
-        dnsMode: linkedDomain.source === 'dcrouter' ? 'internal-dns' : 'external-dns',
+        // 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,

package/ts/email/classes.email-route-builder.ts

@@ -3,6 +3,7 @@ import { logger } from '../logger.js';
 import type { IUnifiedEmailServerOptions } from '@push.rocks/smartmta';
 import type { IRoute } from '../../ts_interfaces/data/route-management.js';
 import type { IDcRouterRouteConfig } from '../../ts_interfaces/data/remoteingress.js';
+import { REMOTE_INGRESS_MAIL_TAG } from '../../ts_interfaces/data/remoteingress.js';
 import type { DcRouter } from '../classes.dcrouter.js';
 
 type TInboundProxyProtocolPolicy = NonNullable<plugins.smartproxy.IRouteMatch['inboundProxyProtocol']>;
@@ -99,7 +100,9 @@ export class EmailRouteBuilder {
       };
 
       if (this.dcRouterRef.isRemoteIngressHubEnabled()) {
-        routeConfig.remoteIngress = { enabled: true };
+        // Only mail-tagged edges bind SMTP ports — other edges may sit on hosts
+        // where 25/465/587 belong to a different mail system.
+        routeConfig.remoteIngress = { enabled: true, edgeFilter: [REMOTE_INGRESS_MAIL_TAG] };
         const inboundProxyProtocol = this.getRemoteIngressEmailInboundProxyPolicy(port);
         if (inboundProxyProtocol) {
           routeConfig.match.inboundProxyProtocol = inboundProxyProtocol;

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

@@ -22,7 +22,7 @@ function hasOwn(objectArg: object, keyArg: string): boolean {
 export class EmailSettingsManager {
   private cachedEmailConfig?: IUnifiedEmailServerOptions;
   private cachedEmailPortConfig?: IEmailPortConfig;
-  private outboundMode: TEmailOutboundMode = 'direct';
+  private outboundMode: TEmailOutboundMode = 'remoteIngress';
   private enabled = false;
   private updatedAt = 0;
   private updatedBy = 'default';
@@ -140,7 +140,7 @@ export class EmailSettingsManager {
   }
 
   private normalizeOutboundMode(mode: TEmailOutboundMode | undefined): TEmailOutboundMode {
-    if (!mode) return 'direct';
+    if (!mode) return 'remoteIngress';
     if (mode !== 'direct' && mode !== 'remoteIngress') {
       throw new Error('Invalid email outbound mode');
     }

package/ts/email/classes.mail-dns-sync.ts

@@ -0,0 +1,218 @@
+import { logger } from '../logger.js';
+import { DnsRecordDoc } from '../db/documents/classes.dns-record.doc.js';
+import { DomainDoc } from '../db/documents/classes.domain.doc.js';
+import { EmailDomainDoc } from '../db/documents/classes.email-domain.doc.js';
+import type { DcRouter } from '../classes.dcrouter.js';
+import type { IRemoteIngress } from '../../ts_interfaces/data/remoteingress.js';
+
+export const MAIL_DNS_SYNC_CREATED_BY = 'mail-edge-sync';
+
+interface IDesiredMailDnsRecord {
+  name: string;
+  type: 'A' | 'AAAA';
+  value: string;
+}
+
+/**
+ * Reconciles the mail-facing A/AAAA records that make edges — never the hub —
+ * the public identity of the mail platform:
+ *  (a) shared mail hostname → publicIp/publicIpV6 of every enabled mail edge,
+ *  (b) each edge's mailHostname → that edge's IPs (FCrDNS for outbound EHLO),
+ *  (c) mx.<domain> → the pinned edges' IPs for every pinned email domain.
+ * Records are DB-backed DnsRecordDoc rows owned via createdBy 'mail-edge-sync';
+ * provider-hosted zones (e.g. Cloudflare) are written through DnsManager's
+ * provider path, dcrouter-authoritative zones serve immediately.
+ */
+export class MailDnsSync {
+  private syncInFlight?: Promise<void>;
+  private resyncQueued = false;
+
+  constructor(private dcRouterRef: DcRouter) {}
+
+  /** Fire-and-forget trigger for CRUD hooks; failures are logged, not thrown. */
+  public requestSync(reason: string): void {
+    this.sync(reason).catch((err: unknown) => {
+      logger.log('error', `MailDnsSync failed (${reason}): ${(err as Error).message}`);
+    });
+  }
+
+  /** Coalescing entry point: concurrent triggers fold into one follow-up pass. */
+  public async sync(reason: string): Promise<void> {
+    if (this.syncInFlight) {
+      this.resyncQueued = true;
+      return this.syncInFlight;
+    }
+    this.syncInFlight = this.reconcile(reason).finally(() => {
+      this.syncInFlight = undefined;
+      if (this.resyncQueued) {
+        this.resyncQueued = false;
+        this.requestSync(`${reason} (coalesced)`);
+      }
+    });
+    return this.syncInFlight;
+  }
+
+  private async reconcile(reason: string): Promise<void> {
+    if (this.dcRouterRef.options.dbConfig?.enabled === false) {
+      return;
+    }
+    const dnsManager = this.dcRouterRef.dnsManager;
+    const remoteIngressManager = this.dcRouterRef.remoteIngressManager;
+    if (!dnsManager || !remoteIngressManager) {
+      // Without both managers the edge registry / record store is not
+      // authoritative — skip entirely rather than delete managed records.
+      return;
+    }
+
+    const desired = await this.computeDesiredRecords();
+    const zones = await DomainDoc.findAll();
+
+    // Place each desired record in its zone (longest-suffix match). Records
+    // without a managed zone are reported — the operator must onboard the zone.
+    const placed = new Map<string, { domainId: string; record: IDesiredMailDnsRecord }>();
+    const unplacedNames = new Set<string>();
+    for (const record of desired) {
+      const zone = this.findZoneForName(record.name, zones);
+      if (!zone) {
+        unplacedNames.add(record.name);
+        continue;
+      }
+      placed.set(`${zone.id}|${record.name}|${record.type}|${record.value}`, {
+        domainId: zone.id,
+        record,
+      });
+    }
+    for (const name of unplacedNames) {
+      logger.log('warn', `MailDnsSync: no managed DNS zone covers ${name} — record skipped`);
+    }
+
+    const existing = (await DnsRecordDoc.findAll())
+      .filter((record) => record.createdBy === MAIL_DNS_SYNC_CREATED_BY);
+
+    let created = 0;
+    let deleted = 0;
+
+    for (const record of existing) {
+      const key = `${record.domainId}|${record.name}|${record.type}|${record.value}`;
+      if (placed.has(key)) {
+        placed.delete(key); // already present — nothing to create
+        continue;
+      }
+      const result = await dnsManager.deleteRecord(record.id);
+      if (result.success) {
+        deleted++;
+      } else {
+        logger.log('warn', `MailDnsSync: failed to delete stale ${record.type} ${record.name} → ${record.value}: ${result.message}`);
+      }
+    }
+
+    for (const { domainId, record } of placed.values()) {
+      const result = await dnsManager.createRecord({
+        domainId,
+        name: record.name,
+        type: record.type,
+        value: record.value,
+        // Short TTL: edge IPs are burnable identities and failover heals via DNS.
+        ttl: 300,
+        createdBy: MAIL_DNS_SYNC_CREATED_BY,
+      });
+      if (result.success) {
+        created++;
+      } else {
+        logger.log('warn', `MailDnsSync: failed to create ${record.type} ${record.name} → ${record.value}: ${result.message}`);
+      }
+    }
+
+    if (created > 0 || deleted > 0) {
+      logger.log('info', `MailDnsSync (${reason}): ${created} record(s) created, ${deleted} deleted`);
+    }
+  }
+
+  private async computeDesiredRecords(): Promise<IDesiredMailDnsRecord[]> {
+    const remoteIngressManager = this.dcRouterRef.remoteIngressManager!;
+    const desired: IDesiredMailDnsRecord[] = [];
+
+    const pushEdgeIps = (name: string | undefined, edge: IRemoteIngress) => {
+      if (!name) return;
+      const normalizedName = name.toLowerCase();
+      if (edge.publicIp) {
+        desired.push({ name: normalizedName, type: 'A', value: edge.publicIp });
+      }
+      if (edge.publicIpV6) {
+        desired.push({ name: normalizedName, type: 'AAAA', value: edge.publicIpV6 });
+      }
+    };
+
+    // (a) shared mail hostname → every enabled mail edge
+    const sharedHostname = this.getSharedMailHostname();
+    const mailEdges = remoteIngressManager.getMailEdges();
+    for (const edge of mailEdges) {
+      pushEdgeIps(sharedHostname, edge);
+    }
+
+    // (b) per-edge FCrDNS hostname → that edge only
+    for (const edge of remoteIngressManager.getAllEdges()) {
+      if (!edge.enabled) continue;
+      pushEdgeIps(edge.mailHostname, edge);
+    }
+
+    // (c) mx.<domain> → pinned edges for every pinned email domain
+    const emailDomainDocs = await EmailDomainDoc.findAll();
+    for (const doc of emailDomainDocs) {
+      const edgeFilter = doc.remoteIngress?.edgeFilter;
+      if (!edgeFilter?.length) continue;
+      const pinnedEdges = remoteIngressManager.resolveEdgesByFilter(edgeFilter);
+      if (pinnedEdges.length === 0) {
+        logger.log('warn', `MailDnsSync: email domain ${doc.domain} pin [${edgeFilter.join(', ')}] matches no enabled edge — mx.${doc.domain} not published`);
+        continue;
+      }
+      for (const edge of pinnedEdges) {
+        pushEdgeIps(`mx.${doc.domain}`, edge);
+      }
+    }
+
+    // Hard hub-hiding guard: a hub IP must never become a mail-facing answer.
+    const hubIps = new Set(
+      [this.dcRouterRef.options.publicIp, this.dcRouterRef.detectedPublicIp].filter(Boolean),
+    );
+    const guarded = desired.filter((record) => {
+      if (hubIps.has(record.value)) {
+        logger.log('error', `MailDnsSync: refusing to publish ${record.type} ${record.name} → ${record.value} — value is the hub public IP`);
+        return false;
+      }
+      return true;
+    });
+
+    // Dedupe (several edges may share a tag and a pin may overlap the mail pool)
+    const seen = new Set<string>();
+    return guarded.filter((record) => {
+      const key = `${record.name}|${record.type}|${record.value}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+
+  private getSharedMailHostname(): string | undefined {
+    const hostname = this.dcRouterRef.options.emailConfig?.hostname
+      || this.dcRouterRef.options.tls?.domain;
+    if (!hostname || hostname === 'localhost') {
+      return undefined;
+    }
+    return hostname;
+  }
+
+  /** Longest-suffix zone match: 'mx.gated.one' → zone 'gated.one'. */
+  private findZoneForName(name: string, zones: DomainDoc[]): DomainDoc | undefined {
+    let best: DomainDoc | undefined;
+    for (const zone of zones) {
+      const zoneName = zone.name.toLowerCase();
+      if (name === zoneName || name.endsWith(`.${zoneName}`)) {
+        if (!best || zoneName.length > best.name.length) {
+          best = zone;
+        }
+      }
+    }
+    return best;
+  }
+}

package/ts/email/classes.mail-egress-coordinator.ts

@@ -0,0 +1,125 @@
+import type {
+  IOutboundConnectionProxy,
+  IOutboundConnectionProxyContext,
+} from '@push.rocks/smartmta';
+import { logger } from '../logger.js';
+import { REMOTE_INGRESS_MAIL_TAG } from '../../ts_interfaces/data/remoteingress.js';
+import type { IEmailOutboundEgressStatus, TEmailOutboundMode } from '../../ts_interfaces/data/email-settings.js';
+import type { DcRouter } from '../classes.dcrouter.js';
+
+/**
+ * Routes outbound SMTP deliveries over RemoteIngress edges: resolves the
+ * outbound mode per attempt (no silent direct fallback), maps sender-domain
+ * pins to an edgeFilter, opens the per-delivery QUIC egress proxy, and
+ * presents the selected edge's FCrDNS hostname as the EHLO identity.
+ */
+export class MailEgressCoordinator {
+  constructor(private dcRouterRef: DcRouter) {}
+
+  /**
+   * smartmta connectionProxyProvider. Wired unconditionally so the outbound
+   * mode is resolved per delivery attempt: a failed/late settings manager
+   * defers mail loudly instead of silently degrading to direct-from-hub
+   * egress, and mode changes take effect without an email server restart.
+   */
+  public async provideConnectionProxy(
+    context: IOutboundConnectionProxyContext,
+  ): Promise<IOutboundConnectionProxy | null> {
+    const mode = this.resolveOutboundModeStrict();
+    if (mode === 'direct') {
+      return null;
+    }
+    return await this.createRemoteIngressConnectionProxy(context);
+  }
+
+  /**
+   * Resolve the effective email outbound mode for a delivery attempt.
+   * Throws when the settings manager is unavailable — deferring the delivery —
+   * because guessing here is what silently degraded outbound to direct egress.
+   */
+  public resolveOutboundModeStrict(): TEmailOutboundMode {
+    if (this.dcRouterRef.emailSettingsManager) {
+      return this.dcRouterRef.emailSettingsManager.getOutboundMode();
+    }
+    if (this.dcRouterRef.options.emailOutboundMode) {
+      return this.dcRouterRef.options.emailOutboundMode;
+    }
+    throw new Error('EmailSettingsManager unavailable: refusing to resolve email outbound mode implicitly');
+  }
+
+  /**
+   * Readiness of the RemoteIngress outbound mail egress path (mail-tagged edges).
+   */
+  public getOutboundEgressStatus(): IEmailOutboundEgressStatus {
+    const tunnelManager = this.dcRouterRef.tunnelManager;
+    if (!tunnelManager) {
+      return { ready: false, eligibleEdgeCount: 0, reason: 'RemoteIngress hub is not running' };
+    }
+    return tunnelManager.getEgressReadiness([REMOTE_INGRESS_MAIL_TAG]);
+  }
+
+  /**
+   * Post-start preflight: with remoteIngress outbound (the default), mail
+   * defers until a QUIC mail egress edge connects. Surface that loudly
+   * instead of silently queueing.
+   */
+  public logEgressPreflight(): void {
+    try {
+      if (this.resolveOutboundModeStrict() === 'remoteIngress') {
+        const egressStatus = this.getOutboundEgressStatus();
+        if (!egressStatus.ready) {
+          logger.log('warn', `Outbound mail egress is NOT ready (${egressStatus.reason}); outbound mail will defer until a QUIC mail egress edge connects`);
+        }
+      }
+    } catch (error: unknown) {
+      logger.log('error', `Outbound mail mode could not be resolved: ${(error as Error).message}; outbound deliveries will defer until EmailSettingsManager is available`);
+    }
+  }
+
+  private async createRemoteIngressConnectionProxy(
+    context: IOutboundConnectionProxyContext,
+  ): Promise<IOutboundConnectionProxy> {
+    const tunnelManager = this.dcRouterRef.tunnelManager;
+    if (!tunnelManager) {
+      throw new Error('RemoteIngress outbound SMTP egress is enabled, but the hub is not running');
+    }
+
+    // Per-domain pinning: a sender domain with a configured edgeFilter uses only
+    // matching edges; everything else uses the mail-tagged edge pool.
+    let edgeFilter: string[] = [REMOTE_INGRESS_MAIL_TAG];
+    if (context.senderDomain && this.dcRouterRef.emailDomainManager) {
+      const domain = await this.dcRouterRef.emailDomainManager.getByDomain(context.senderDomain);
+      if (domain?.remoteIngress?.edgeFilter?.length) {
+        edgeFilter = domain.remoteIngress.edgeFilter;
+      }
+    }
+
+    const connectionTimeoutMs = this.dcRouterRef.options.emailConfig?.outbound?.connectionTimeout ?? 30_000;
+    const proxy = await tunnelManager.startEgressTcpProxy({
+      logicalHost: context.host,
+      port: context.port,
+      serverFirst: !context.secure,
+      connectTimeoutMs: connectionTimeoutMs,
+      acceptTimeoutMs: connectionTimeoutMs,
+      edgeFilter,
+    });
+    let closed = false;
+    return {
+      connectHost: proxy.listenHost,
+      connectPort: proxy.listenPort,
+      poolKey: `remoteIngress:${proxy.edgeId}:${context.host}:${context.port}`,
+      ehloHostname: this.dcRouterRef.remoteIngressManager?.getEdge(proxy.edgeId)?.mailHostname,
+      close: async () => {
+        if (closed) {
+          return;
+        }
+        closed = true;
+        try {
+          await tunnelManager.stopEgressTcpProxy(proxy.proxyId);
+        } catch (err: unknown) {
+          logger.log('warn', `Failed to stop RemoteIngress egress proxy ${proxy.proxyId}: ${(err as Error).message}`);
+        }
+      },
+    };
+  }
+}

package/ts/email/index.ts

@@ -1,6 +1,8 @@
 export * from './classes.accepted-email-spool.js';
 export * from './classes.email-domain.manager.js';
 export * from './classes.email-route-builder.js';
+export * from './classes.mail-dns-sync.js';
+export * from './classes.mail-egress-coordinator.js';
 export * from './classes.email-settings.manager.js';
 export * from './classes.smartmta-storage-manager.js';
 export * from './classes.workapp-mail-manager.js';