@serve.zone/dcrouter 32.6.3 → 32.7.0

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

@@ -0,0 +1,398 @@
+import type { UnifiedEmailServer } from '@push.rocks/smartmta';
+import * as plugins from '../plugins.js';
+import { logger } from '../logger.js';
+import { ProxyCertDoc } from '../db/index.js';
+import type { IDcRouterEmailTlsConfig } from '../classes.dcrouter.js';
+import type {
+  IEmailTlsCertificateStatus,
+  TEmailTlsSource,
+} from '../../ts_interfaces/data/email-settings.js';
+
+/** PEM material for the SMTP listener and where it was read from. */
+export interface IEmailTlsMaterial {
+  certPem: string;
+  keyPem: string;
+  origin: string;
+}
+
+/** The part of the SMTP listener that takes replacement TLS material. */
+export type TEmailTlsListener = Pick<UnifiedEmailServer, 'updateOptions'>;
+
+export interface IEmailTlsRequest {
+  source: TEmailTlsSource;
+  tls: IDcRouterEmailTlsConfig | undefined;
+  /** Mail hostname plus every enabled mail-edge hostname. */
+  requiredHostnames: string[];
+}
+
+/** A stored certificate that covers at least one required hostname. */
+export interface IStoredEmailCertificate {
+  domain: string;
+  certPem: string;
+  keyPem: string;
+  certificate: plugins.crypto.X509Certificate;
+  names: string[];
+  uncoveredHostnames: string[];
+  currentlyValid: boolean;
+}
+
+interface IServedEmailTls {
+  source: TEmailTlsSource;
+  origin: string | null;
+  /** ProxyCertDoc key of the served stored certificate. */
+  storedDomain: string | null;
+  certificate: plugins.crypto.X509Certificate | null;
+  names: string[];
+  /** Problems found when the material was read (parse failure, key mismatch, nothing found). */
+  materialProblems: string[];
+}
+
+/** Whether `emailConfig.tls` carries operator-managed certificate material. */
+export const hasConfiguredEmailTlsMaterial = (tlsArg: IDcRouterEmailTlsConfig | undefined): boolean =>
+  Boolean(tlsArg?.certPem || tlsArg?.keyPem || tlsArg?.certPath || tlsArg?.keyPath);
+
+/**
+ * Source for settings persisted without one: the material they served before
+ * the source existed — configured material when present, otherwise the
+ * managed certificate.
+ */
+export const deriveEmailTlsSource = (tlsArg: IDcRouterEmailTlsConfig | undefined): TEmailTlsSource =>
+  hasConfiguredEmailTlsMaterial(tlsArg) ? 'configuredMaterial' : 'managedCertificate';
+
+/** The `tls` block without certificate material; undefined when nothing else remains. */
+export const withoutConfiguredEmailTlsMaterial = (
+  tlsArg: IDcRouterEmailTlsConfig | undefined,
+): IDcRouterEmailTlsConfig | undefined => {
+  if (!tlsArg) return undefined;
+  const { certPem, keyPem, certPath, keyPath, ...remaining } = tlsArg;
+  return Object.keys(remaining).length > 0 ? remaining : undefined;
+};
+
+/** The `tls` block handed to SmartMTA: configured options plus the resolved PEM material. */
+export const composeEmailServerTls = (
+  tlsArg: IDcRouterEmailTlsConfig | undefined,
+  materialArg: IEmailTlsMaterial | undefined,
+): IDcRouterEmailTlsConfig | undefined => {
+  const options = withoutConfiguredEmailTlsMaterial(tlsArg);
+  if (!materialArg) return options;
+  return { ...options, certPem: materialArg.certPem, keyPem: materialArg.keyPem };
+};
+
+const describeError = (errorArg: unknown): string =>
+  errorArg instanceof Error ? errorArg.message : String(errorArg);
+
+const normalizeHostname = (hostnameArg: string): string =>
+  hostnameArg.trim().toLowerCase().replace(/\.$/, '');
+
+/** DNS subject alternative names of a certificate, lowercased. */
+export const getCertificateDnsNames = (certificateArg: plugins.crypto.X509Certificate): string[] =>
+  (certificateArg.subjectAltName || '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.startsWith('DNS:'))
+    .map((entry) => normalizeHostname(entry.slice('DNS:'.length).replace(/^"|"$/g, '')));
+
+/**
+ * RFC 6125 name matching: exact, or a `*.` wildcard standing for exactly one
+ * left-most label. Implemented here because X509Certificate.checkHost does not
+ * match wildcards on every runtime dcrouter ships on.
+ */
+export const certificateNameCovers = (nameArg: string, hostnameArg: string): boolean => {
+  const hostname = normalizeHostname(hostnameArg);
+  if (nameArg === hostname) return true;
+  if (!nameArg.startsWith('*.')) return false;
+  const firstDot = hostname.indexOf('.');
+  return firstDot > 0 && hostname.slice(firstDot + 1) === nameArg.slice(2);
+};
+
+const findUncoveredHostnames = (namesArg: string[], hostnamesArg: string[]): string[] =>
+  hostnamesArg.filter((hostname) => !namesArg.some((name) => certificateNameCovers(name, hostname)));
+
+const parseCertificate = (certPemArg: string): plugins.crypto.X509Certificate => new plugins.crypto.X509Certificate(certPemArg);
+
+const isCurrentlyValid = (certificateArg: plugins.crypto.X509Certificate, nowArg: number): boolean =>
+  certificateArg.validFromDate.getTime() <= nowArg && nowArg < certificateArg.validToDate.getTime();
+
+/**
+ * Owns the SMTP listener's certificate: resolves it from the selected source
+ * on every listener start and relevant renewal, and reports what is served.
+ *
+ * Resolved material is held here and never written back into the email
+ * configuration, so every resolution reads the source of truth again.
+ */
+export class EmailTlsManager {
+  private served: IServedEmailTls | undefined;
+
+  /** Resolve the listener material from the selected source and record it as served. */
+  public async resolve(requestArg: IEmailTlsRequest): Promise<IEmailTlsMaterial | undefined> {
+    const material = requestArg.source === 'configuredMaterial'
+      ? await this.resolveConfiguredMaterial(requestArg.tls)
+      : await this.resolveManagedCertificate(requestArg.requiredHostnames);
+
+    const status = this.getStatus(requestArg.requiredHostnames);
+    if (status && status.problems.length > 0) {
+      logger.log(
+        'error',
+        `SMTP TLS certificate problem (source=${status.source}, origin=${status.origin ?? 'none'}): ${status.problems.join('; ')}`,
+      );
+    } else if (status) {
+      logger.log(
+        'info',
+        `SMTP TLS certificate: source=${status.source}, origin=${status.origin}, notAfter=${status.notAfter === null ? 'unknown' : new Date(status.notAfter).toISOString()}, names=[${status.names.join(', ')}]`,
+      );
+    }
+    return material;
+  }
+
+  /**
+   * Push an issued or renewed certificate to the running listener when it can
+   * change what the listener should serve. Returns the applied material.
+   */
+  public async applyIssuance(
+    domainArg: string,
+    listenerArg: TEmailTlsListener,
+    requestArg: IEmailTlsRequest,
+  ): Promise<IEmailTlsMaterial | undefined> {
+    if (!(await this.isRelevantIssuance(domainArg, requestArg.requiredHostnames))) return undefined;
+    const material = await this.resolve(requestArg);
+    if (!material) return undefined;
+    listenerArg.updateOptions({ tls: composeEmailServerTls(requestArg.tls, material) });
+    return material;
+  }
+
+  /** Forget the served certificate (the listener is stopped). */
+  public clear(): void {
+    this.served = undefined;
+  }
+
+  /**
+   * Whether an issued or renewed certificate can change what the listener
+   * should serve. Only the managed source follows issuance; the stored
+   * certificate is keyed by the requested route domain, so a wildcard or
+   * sibling issuance is matched by the names it covers, not by its key.
+   */
+  public async isRelevantIssuance(domainArg: string, requiredHostnamesArg: string[]): Promise<boolean> {
+    const served = this.served;
+    if (!served || served.source !== 'managedCertificate') return false;
+    const domain = normalizeHostname(domainArg);
+    if (served.storedDomain !== null && normalizeHostname(served.storedDomain) === domain) return true;
+    if (requiredHostnamesArg.some((hostname) => normalizeHostname(hostname) === domain)) return true;
+    const stored = await ProxyCertDoc.findByDomain(domainArg);
+    if (!stored?.publicKey) return false;
+    try {
+      const names = getCertificateDnsNames(parseCertificate(stored.publicKey));
+      return findUncoveredHostnames(names, requiredHostnamesArg).length < requiredHostnamesArg.length;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * The best stored certificate for the required hostnames: currently valid
+   * and covering every name first, then valid, then the most names covered,
+   * then the latest expiry. Undefined when none covers any required hostname.
+   */
+  public async selectStoredCertificate(
+    requiredHostnamesArg: string[],
+    nowArg = Date.now(),
+  ): Promise<IStoredEmailCertificate | undefined> {
+    const candidates: IStoredEmailCertificate[] = [];
+    for (const doc of await ProxyCertDoc.findAll()) {
+      if (!doc.publicKey || !doc.privateKey) continue;
+      let certificate: plugins.crypto.X509Certificate;
+      try {
+        certificate = parseCertificate(doc.publicKey);
+      } catch {
+        continue;
+      }
+      const names = getCertificateDnsNames(certificate);
+      const uncoveredHostnames = findUncoveredHostnames(names, requiredHostnamesArg);
+      if (uncoveredHostnames.length === requiredHostnamesArg.length) continue;
+      candidates.push({
+        domain: doc.domain,
+        certPem: doc.publicKey,
+        keyPem: doc.privateKey,
+        certificate,
+        names,
+        uncoveredHostnames,
+        currentlyValid: isCurrentlyValid(certificate, nowArg),
+      });
+    }
+    const rank = (candidateArg: IStoredEmailCertificate): number[] => [
+      candidateArg.currentlyValid && candidateArg.uncoveredHostnames.length === 0 ? 1 : 0,
+      candidateArg.currentlyValid ? 1 : 0,
+      -candidateArg.uncoveredHostnames.length,
+      candidateArg.certificate.validToDate.getTime(),
+    ];
+    candidates.sort((left, right) => {
+      const leftRank = rank(left);
+      const rightRank = rank(right);
+      for (let index = 0; index < leftRank.length; index++) {
+        if (leftRank[index] !== rightRank[index]) return rightRank[index] - leftRank[index];
+      }
+      return left.domain.localeCompare(right.domain);
+    });
+    return candidates[0];
+  }
+
+  /**
+   * Gate for switching to the managed source: refuses unless a currently
+   * valid stored certificate covers every required hostname.
+   */
+  public async assertManagedCertificateAvailable(requiredHostnamesArg: string[]): Promise<IStoredEmailCertificate> {
+    const stored = await this.selectStoredCertificate(requiredHostnamesArg);
+    if (stored?.currentlyValid && stored.uncoveredHostnames.length === 0) return stored;
+    const closest = !stored
+      ? ''
+      : stored.currentlyValid
+        ? ` The closest stored certificate '${stored.domain}' does not cover ${stored.uncoveredHostnames.join(', ')}.`
+        : ` The closest stored certificate '${stored.domain}' is outside its validity period (notAfter ${stored.certificate.validToDate.toISOString()}).`;
+    throw new Error(
+      `Refusing the managedCertificate email TLS source: no currently valid stored certificate covers ${requiredHostnamesArg.join(', ')}.${closest}`,
+    );
+  }
+
+  /**
+   * The served certificate checked against the required hostnames now, so
+   * expiry while running shows up without a new resolution.
+   */
+  public getStatus(requiredHostnamesArg: string[], nowArg = Date.now()): IEmailTlsCertificateStatus | undefined {
+    const served = this.served;
+    if (!served) return undefined;
+    const problems = [...served.materialProblems];
+    const certificate = served.certificate;
+    if (certificate) {
+      const notBefore = certificate.validFromDate.getTime();
+      const notAfter = certificate.validToDate.getTime();
+      if (nowArg >= notAfter) {
+        problems.push(`certificate expired at ${new Date(notAfter).toISOString()}`);
+      } else if (nowArg < notBefore) {
+        problems.push(`certificate is not valid before ${new Date(notBefore).toISOString()}`);
+      }
+      const uncovered = findUncoveredHostnames(served.names, requiredHostnamesArg);
+      if (uncovered.length > 0) {
+        problems.push(`certificate does not cover ${uncovered.join(', ')}`);
+      }
+    }
+    return {
+      source: served.source,
+      origin: served.origin,
+      names: [...served.names],
+      notBefore: certificate ? certificate.validFromDate.getTime() : null,
+      notAfter: certificate ? certificate.validToDate.getTime() : null,
+      requiredHostnames: [...requiredHostnamesArg],
+      problems,
+      checkedAt: nowArg,
+    };
+  }
+
+  /**
+   * Operator-managed material. Paths that cannot be read FAIL listener
+   * startup: continuing without TLS is what once produced a cleartext
+   * submission port, so a broken explicit configuration must be impossible
+   * to miss.
+   */
+  private async resolveConfiguredMaterial(
+    tlsArg: IDcRouterEmailTlsConfig | undefined,
+  ): Promise<IEmailTlsMaterial | undefined> {
+    let material: IEmailTlsMaterial | undefined;
+    if (tlsArg?.certPem && tlsArg.keyPem) {
+      material = { certPem: tlsArg.certPem, keyPem: tlsArg.keyPem, origin: 'inline PEM' };
+    } else if (tlsArg?.certPath || tlsArg?.keyPath) {
+      if (!tlsArg.certPath || !tlsArg.keyPath) {
+        throw new Error('emailConfig.tls requires both certPath and keyPath when either is configured');
+      }
+      let certPem: string;
+      let keyPem: string;
+      try {
+        certPem = await plugins.fs.promises.readFile(tlsArg.certPath, 'utf8');
+        keyPem = await plugins.fs.promises.readFile(tlsArg.keyPath, 'utf8');
+      } catch (error: unknown) {
+        throw new Error(
+          `Unable to read the configured SMTP TLS material (certPath=${tlsArg.certPath}, keyPath=${tlsArg.keyPath}): ${describeError(error)}`,
+        );
+      }
+      if (!certPem.trim() || !keyPem.trim()) {
+        throw new Error(
+          `The configured SMTP TLS material is empty (certPath=${tlsArg.certPath}, keyPath=${tlsArg.keyPath})`,
+        );
+      }
+      material = { certPem, keyPem, origin: `configured paths (${tlsArg.certPath})` };
+    } else if (tlsArg?.certPem || tlsArg?.keyPem) {
+      throw new Error('emailConfig.tls requires both certPem and keyPem when either is configured');
+    }
+
+    if (!material) {
+      this.served = {
+        source: 'configuredMaterial',
+        origin: null,
+        storedDomain: null,
+        certificate: null,
+        names: [],
+        materialProblems: ['the configuredMaterial source is selected but emailConfig.tls carries no certificate material'],
+      };
+      return undefined;
+    }
+
+    const materialProblems: string[] = [];
+    let certificate: plugins.crypto.X509Certificate | null = null;
+    try {
+      certificate = parseCertificate(material.certPem);
+    } catch (error: unknown) {
+      materialProblems.push(`certificate cannot be parsed: ${describeError(error)}`);
+    }
+    if (certificate) {
+      materialProblems.push(...this.checkKeyPair(certificate, material.keyPem));
+    }
+    this.served = {
+      source: 'configuredMaterial',
+      origin: material.origin,
+      storedDomain: null,
+      certificate,
+      names: certificate ? getCertificateDnsNames(certificate) : [],
+      materialProblems,
+    };
+    return material;
+  }
+
+  private async resolveManagedCertificate(requiredHostnamesArg: string[]): Promise<IEmailTlsMaterial | undefined> {
+    let stored: IStoredEmailCertificate | undefined;
+    let lookupProblem: string | undefined;
+    try {
+      stored = await this.selectStoredCertificate(requiredHostnamesArg);
+    } catch (error: unknown) {
+      lookupProblem = `stored certificates cannot be read: ${describeError(error)}`;
+    }
+    if (!stored) {
+      this.served = {
+        source: 'managedCertificate',
+        origin: null,
+        storedDomain: null,
+        certificate: null,
+        names: [],
+        materialProblems: [lookupProblem ?? `no stored certificate covers ${requiredHostnamesArg.join(', ')}`],
+      };
+      return undefined;
+    }
+    const origin = `stored certificate '${stored.domain}'`;
+    this.served = {
+      source: 'managedCertificate',
+      origin,
+      storedDomain: stored.domain,
+      certificate: stored.certificate,
+      names: stored.names,
+      materialProblems: this.checkKeyPair(stored.certificate, stored.keyPem),
+    };
+    return { certPem: stored.certPem, keyPem: stored.keyPem, origin };
+  }
+
+  private checkKeyPair(certificateArg: plugins.crypto.X509Certificate, keyPemArg: string): string[] {
+    try {
+      return certificateArg.checkPrivateKey(plugins.crypto.createPrivateKey(keyPemArg))
+        ? []
+        : ['private key does not match the certificate'];
+    } catch (error: unknown) {
+      return [`private key cannot be parsed: ${describeError(error)}`];
+    }
+  }
+}

package/ts/email/index.ts

@@ -8,6 +8,7 @@ export * from './reconcile-mail-dns-singleton.js';
 export * from './classes.mail-egress-coordinator.js';
 export * from './classes.mail-edge-eligibility.js';
 export * from './classes.email-settings.manager.js';
+export * from './classes.email-tls-manager.js';
 export * from './classes.gateway-mail-domain.store.js';
 export * from './classes.coremail-gateway.manager.js';
 export * from './classes.coremail-gateway.store.js';

package/ts/opsserver/handlers/email-settings.handler.ts

@@ -58,10 +58,12 @@ export class EmailSettingsHandler {
     const smtpListenerActive = dcRouter.emailServer
       ? dcRouter.emailServer.isSmtpListenerActive()
       : undefined;
+    const tlsCertificate = dcRouter.getEmailTlsCertificateStatus();
     const manager = dcRouter.emailSettingsManager;
     if (manager) {
       return {
         ...manager.getPublicSettings(),
+        ...(tlsCertificate ? { tlsCertificate } : {}),
         outboundEgress,
         mailerBridgeState,
         smtpAccountCount,
@@ -82,6 +84,8 @@ export class EmailSettingsHandler {
       portMapping: emailPortConfig?.portMapping ? { ...emailPortConfig.portMapping } : null,
       receivedEmailsPath: emailPortConfig?.receivedEmailsPath || null,
       maxMessageSize: emailConfig?.maxMessageSize ?? null,
+      tlsSource: dcRouter.getEmailTlsSource(),
+      ...(tlsCertificate ? { tlsCertificate } : {}),
       domainCount: emailConfig?.domains?.length || 0,
       routeCount: emailConfig?.routes?.length || 0,
       authUserCount: emailConfig?.auth?.users?.length || 0,

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '32.6.3',
+  version: '32.7.0',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }