@serve.zone/dcrouter 17.10.2 → 18.0.1

package/ts/classes.dcrouter.ts

@@ -35,10 +35,13 @@ import { SecurityLogger, ContentScanner, IPReputationChecker, SecurityPolicyMana
 import { type IHttp3Config, augmentRoutesWithHttp3 } from './http3/index.js';
 import { applyDefaultInboundPolicy } from './email/inbound-policy.js';
 import { DnsManager } from './dns/manager.dns.js';
+import { DnsAuthorityManager } from './dns/manager.dns-authority.js';
 import { DnsServerRuntime } from './dns/classes.dns-server-runtime.js';
 import { GatewayRouteDnsReconciler } from './dns/classes.gateway-route-dns-reconciler.js';
+import { DomainOwnershipError } from './dns/domain-ownership.js';
 import { AcmeConfigManager } from './acme/manager.acme-config.js';
 import { SmartAcmeLifecycle } from './acme/classes.smartacme-lifecycle.js';
+import { AcmePermanentFailureError, classifyAcmeFailure } from './acme/acme-failure-classification.js';
 import { AcceptedEmailSpool, EmailDomainManager, EmailRouteBuilder, EmailSettingsManager, MailDnsSync, MailEdgeEligibility, MailEgressCoordinator, ReleasedRemoteIngressEgressIdentitySource, SmartMtaBlobStorageManager, SmartMtaStorageManager, WorkAppMailManager, type ISmartMtaBlobStorageConfig, type TSmartMtaQueueItemLike } from './email/index.js';
 import { WebPushManager } from './webpush/index.js';
 import type { IRoute } from '../ts_interfaces/data/route-management.js';
@@ -95,17 +98,14 @@ export interface IDcRouterOptions {
   /**
    * The nameserver domains (e.g., ['ns1.example.com', 'ns2.example.com'])
    * These will automatically get A records pointing to publicIp or proxyIps[0]
-   * These are what go in the NS records for ALL domains in dnsScopes
+   * A zone becomes authoritative by having its public NS records observed
+   * naming one of these — that is the only way into the authority set.
+   *
+   * There is deliberately no `dnsScopes` counterpart. Which zones dcrouter
+   * answers for is database state carrying its own delegation evidence, not
+   * deployment configuration; see ts/dns/manager.dns-authority.ts.
    */
   dnsNsDomains?: string[];
-  
-  /**
-   * Domains this DNS server is authoritative for (e.g., ['example.com', 'mail.example.org'])
-   * NS records will be auto-generated for these domains
-   * Any DNS record outside these scopes will trigger a warning
-   * Email domains with `internal-dns` mode must be included here
-   */
-  dnsScopes?: string[];
 
   /** Explicit UDP bind address for the embedded DNS server. Defaults to auto-detection. */
   dnsBindInterface?: string;
@@ -127,7 +127,7 @@ export interface IDcRouterOptions {
   
   /**
    * DNS records to register
-   * Must be within the defined dnsScopes (or receive warning)
+   * Must be within a delegation-verified zone (or receive warning)
    * Only need A, CNAME, TXT, MX records (NS records auto-generated, SOA handled by smartdns)
    * Can use `useIngressProxy: false` to expose real server IP (defaults to true)
    */
@@ -314,6 +314,8 @@ export class DcRouter {
 
   // Domain / DNS management (DB-backed providers, domains, records)
   public dnsManager?: DnsManager;
+  /** Owns which zones dcrouter may answer for authoritatively, and proves it. */
+  public dnsAuthorityManager?: DnsAuthorityManager;
   public gatewayRouteDnsReconciler?: GatewayRouteDnsReconciler;
 
   // Durable, acknowledgeable platform configuration events (DB-backed)
@@ -523,7 +525,26 @@ export class DcRouter {
           .optional()
           .dependsOn('DcRouterDb')
           .withStart(async () => {
+            this.dnsAuthorityManager = new DnsAuthorityManager(
+              () => this.options.dnsNsDomains || [],
+            );
+            // Throws when the stored authority set is unreadable. That fails
+            // this service; DnsServerRuntime.setup() independently refuses to
+            // start on an 'unavailable' state, because dependsOn only orders
+            // services and does not gate them. An unknown authority set must
+            // never be served as an empty one.
+            await this.dnsAuthorityManager.start();
+
             this.dnsManager = new DnsManager(this.options);
+            // Ownership proof reads the delegation-verified set, so a zone
+            // verified at runtime counts immediately and a zone revoked at
+            // runtime stops counting immediately.
+            this.dnsManager.setAuthorityZonesResolver(
+              () => this.dnsAuthorityManager?.getEffectiveZoneNames() || [],
+            );
+            this.dnsAuthorityManager.setReconciler(
+              async (reasonArg) => await this.reconcileDnsAuthority(reasonArg),
+            );
             await this.dnsManager.start();
           })
           .withStop(async () => {
@@ -531,6 +552,10 @@ export class DcRouter {
               await this.dnsManager.stop();
               this.dnsManager = undefined;
             }
+            if (this.dnsAuthorityManager) {
+              await this.dnsAuthorityManager.stop();
+              this.dnsAuthorityManager = undefined;
+            }
           })
           .withRetry({ maxRetries: 1, baseDelayMs: 500 }),
       );
@@ -743,14 +768,33 @@ export class DcRouter {
                 } catch (err: unknown) {
                   logger.log('error', `Failed to sync Remote Ingress allowed edges: ${(err as Error).message}`);
                 }
-                this.dnsServerRuntime.syncPrivateRouteOverrides(
-                  routes as IDcRouterRouteConfig[],
-                );
+                try {
+                  await this.dnsServerRuntime.syncPrivateRouteOverrides(
+                    routes as IDcRouterRouteConfig[],
+                  );
+                } catch (err: unknown) {
+                  logger.log(
+                    'error',
+                    `Failed to sync the DNS private-route overlay: ${(err as Error).message}`,
+                  );
+                }
               },
               (preparedRoutes) => buildHttpRedirectRuntimeRoutes(preparedRoutes || []),
               (storedRoute: IRoute) => this.emailRouteBuilder.hydrateStoredRouteForRuntime(storedRoute),
               (routes) => this.routePolicyAugmenter.applyInboundProxyProtocolPolicies(routes),
             );
+            // Certificate requirements may only be created for domains whose
+            // ownership can be proven. Wired before initialize() so the startup
+            // audit and every subsequent mutation see the same source.
+            this.routeConfigManager.setDomainOwnershipSource({
+              listOwnershipZones: async () => {
+                if (!this.dnsManager) {
+                  throw new Error('DnsManager is unavailable, domain ownership cannot be verified');
+                }
+                return await this.dnsManager.listOwnershipZones();
+              },
+              getAuthorityZones: () => this.dnsAuthorityManager?.getEffectiveZoneNames() || [],
+            });
             this.apiTokenManager = new ApiTokenManager();
             await this.apiTokenManager.initialize();
             this.gatewayClientManager = new GatewayClientManager();
@@ -833,12 +877,19 @@ export class DcRouter {
       logger.log('warn', 'EmailServer: dbConfig.enabled=false, skipping SMTP startup because accepted email requires durable DB persistence');
     }
 
-    // DNS Server: optional, depends on SmartProxy
-    if (this.options.dnsNsDomains && this.options.dnsNsDomains.length > 0 && this.options.dnsScopes && this.options.dnsScopes.length > 0) {
-      const dnsServerDeps = ['SmartProxy'];
-      if (this.options.dbConfig?.enabled !== false) {
-        dnsServerDeps.push('ConfigManagers', 'EmailServer');
-      }
+    // DNS Server: optional, depends on SmartProxy and on the authority set.
+    //
+    // Registration used to require a non-empty bootstrap `dnsScopes`, which
+    // meant a router whose authority lived entirely in the database never
+    // started its DNS server at all. The gate is now the nameserver identity —
+    // without `dnsNsDomains` there is nothing a delegation could name, so no
+    // zone could ever be verified — plus the database, because that is where
+    // authority comes from. `DnsManager` is listed as a dependency so it starts
+    // first — it owns `DnsAuthorityManager` — but ordering is all `dependsOn`
+    // provides, so `DnsServerRuntime.setup()` checks the authority state itself
+    // rather than trusting the graph.
+    if (this.options.dnsNsDomains?.length && this.options.dbConfig?.enabled !== false) {
+      const dnsServerDeps = ['SmartProxy', 'DnsManager', 'ConfigManagers', 'EmailServer'];
       this.serviceManager.addService(
         new plugins.taskbuffer.Service('DnsServer')
           .optional()
@@ -856,6 +907,12 @@ export class DcRouter {
           })
           .withRetry({ maxRetries: 3, baseDelayMs: 2000, maxDelayMs: 30_000 }),
       );
+    } else if (this.options.dnsNsDomains?.length) {
+      logger.log(
+        'warn',
+        'DnsServer: dbConfig.enabled=false, skipping the embedded DNS server because DNS authority is '
+          + 'delegation-verified state held in the database — without it there is no zone dcrouter may answer for',
+      );
     }
 
     // RADIUS Server: optional, no dependency on SmartProxy
@@ -899,7 +956,7 @@ export class DcRouter {
       const mailDnsSyncDependencies = [
         'DnsManager', 'EmailDomainManager', 'EmailServer', 'RemoteIngress',
       ];
-      if (this.options.dnsNsDomains?.length && this.options.dnsScopes?.length) {
+      if (this.options.dnsNsDomains?.length) {
         mailDnsSyncDependencies.push('DnsServer');
       }
 
@@ -1052,8 +1109,9 @@ export class DcRouter {
     }
 
     // DNS service summary
-    if (this.dnsServer && this.options.dnsNsDomains && this.options.dnsScopes) {
-      logger.log('info', `DNS Service: nameservers=[${this.options.dnsNsDomains.join(', ')}], authoritative for ${this.options.dnsScopes.length} domains [${this.options.dnsScopes.join(', ')}], UDP:53, DoH enabled`);
+    if (this.dnsServer && this.options.dnsNsDomains) {
+      const authorityZones = this.dnsAuthorityManager?.getEffectiveZoneNames() || [];
+      logger.log('info', `DNS Service: nameservers=[${this.options.dnsNsDomains.join(', ')}], authoritative for ${authorityZones.length} delegation-verified zone(s) [${authorityZones.join(', ') || 'none'}], UDP:53, DoH enabled`);
     }
 
     // RADIUS service summary
@@ -1104,8 +1162,17 @@ export class DcRouter {
     } else {
       logger.log('info', `All ${running} services are running`);
     }
+
+    // Compare claimed authority against real delegation, in the background.
+    //
+    // Nothing used to check these two representations against each other, which
+    // is how one zone sat declared in bootstrap config while four others were
+    // live and delegated to our nameservers. Detached and advisory: it makes
+    // network calls, so it must never delay or fail startup, and it never mutates
+    // the authority set — a resolver blip at boot must not revoke authority.
+    void this.dnsAuthorityManager?.logDelegationDrift();
   }
-  
+
   /**
    * Set up the unified database (smartdata + LocalSmartDb or external MongoDB)
    */
@@ -1403,6 +1470,23 @@ export class DcRouter {
             return 'http01';
           }
 
+          // Pre-flight: a hostname whose ownership we cannot prove has no zone
+          // able to hold the DNS-01 challenge record, so the order can only ever
+          // fail. Refuse before touching the per-domain retry budget — this is
+          // the cause that silently consumed 31–45 attempts per domain and never
+          // surfaced as anything but generic ACME noise.
+          const ownership = await this.dnsManager!.resolveDomainOwnership(domain);
+          if (!ownership.verified) {
+            const permanentError = new DomainOwnershipError(
+              ownership,
+              'Certificate provisioning',
+              'cert-provision-function',
+              { data: { domain } },
+            );
+            eventComms.error(permanentError.message);
+            throw permanentError;
+          }
+
           // Check backoff before attempting provision
           if (await scheduler.isInBackoff(domain)) {
             const info = await scheduler.getBackoffInfo(domain);
@@ -1444,6 +1528,21 @@ export class DcRouter {
             await scheduler.clearBackoff(domain);
             return result;
           } catch (err: unknown) {
+            const classification = classifyAcmeFailure(err);
+            if (classification.permanent) {
+              // A configuration cause cannot be retried away. Consuming the
+              // per-domain budget here is what hid four broken domains behind
+              // ordinary backoff warnings for weeks, so it is left untouched and
+              // the failure is raised as an attributable terminal error instead.
+              const permanentError = new AcmePermanentFailureError(
+                classification,
+                `DNS-01 for ${domain}`,
+                'cert-provision-function',
+                { data: { domain } },
+              );
+              eventComms.error(permanentError.message);
+              throw permanentError;
+            }
             const message = `DNS-01 failed for ${domain}: ${(err as Error).message}`;
             await scheduler.recordFailure(domain, message);
             eventComms.warn(message);
@@ -2200,6 +2299,77 @@ export class DcRouter {
     return await this.remoteIngressHubLifecycle.updateHubSettings(updates, updatedBy);
   }
 
+  /**
+   * Re-derive every piece of runtime state that depends on the effective DNS
+   * authority set, after a zone gained or lost delegation-verified authority.
+   *
+   * Deliberately reuses the existing machinery rather than paralleling it:
+   * `reconcileAuthoritativeZones()` drives the same `runtimeRegistrations`
+   * registry that domain deletion uses, and the overlay and route-warning
+   * refreshes are the same calls the domain mutation paths make. Throws on the
+   * first failure so `DnsAuthorityManager` can roll the change back rather than
+   * leave the router half-converted.
+   */
+  public async reconcileDnsAuthority(reasonArg: string): Promise<void> {
+    if (!this.dnsManager) {
+      throw new Error('DnsManager is unavailable, DNS authority cannot be reconciled');
+    }
+    logger.log('info', `Reconciling DNS authority: ${reasonArg}`, { zone: 'dns' });
+
+    // 0. The running DNS server's own zone set. This decides the *response
+    //    kind* — a name outside every configured zone is REFUSED even when a
+    //    handler answers other qtypes for it — so it has to move before the
+    //    handlers do, or a newly verified zone answers A while REFUSING AAAA
+    //    and SOA, which is precisely the production defect being fixed.
+    this.dnsServerRuntime.syncAuthorityZones(reasonArg);
+
+    // 1. Zone handlers: register what gained proof, tear down what lost it.
+    const zoneResult = await this.dnsManager.reconcileAuthoritativeZones();
+
+    // 2. Keep the persisted authoritative flag honest with the new verdicts.
+    const flagsChanged = await this.dnsManager.syncAuthoritativeFlags();
+
+    // 3. Certificate requirements: re-evaluate which routes are now provable.
+    await this.routeConfigManager?.refreshDomainOwnershipWarnings();
+
+    // 4. The ownership-gated private-route overlay.
+    await this.resyncPrivateRouteDnsOverlay(reasonArg);
+
+    logger.log(
+      'info',
+      `DNS authority reconciled (${reasonArg}): +${zoneResult.registered.length} / -${zoneResult.unregistered.length} apex NS zone(s), `
+        + `${flagsChanged} domain authoritative flag(s) corrected`,
+      { zone: 'dns' },
+    );
+  }
+
+  /**
+   * Re-derive the private-route DNS overlay from the currently applied route set.
+   *
+   * The overlay is derived from routes but gated on domain ownership, so a domain
+   * mutation can invalidate it without any route changing. Deleting a DomainDoc
+   * is the case that matters: without this the overlay keeps answering `aa` for a
+   * hostname whose zone we no longer manage until some unrelated route apply
+   * happens. Named here so the mutation site can trigger its own invalidation
+   * instead of forcing a full route re-apply.
+   */
+  public async resyncPrivateRouteDnsOverlay(reasonArg: string): Promise<void> {
+    const appliedRoutes = this.smartProxy?.routeManager.getRoutes();
+    if (!appliedRoutes) {
+      return;
+    }
+    try {
+      await this.dnsServerRuntime.syncPrivateRouteOverrides(
+        appliedRoutes as IDcRouterRouteConfig[],
+      );
+    } catch (err: unknown) {
+      logger.log(
+        'error',
+        `Failed to re-sync the DNS private-route overlay after ${reasonArg}: ${(err as Error).message}`,
+      );
+    }
+  }
+
   /** Restart SmartProxy after RemoteIngress hub settings changed listener wiring. Called by RemoteIngressHubLifecycle. */
   public async restartSmartProxyForRemoteIngressSettings(): Promise<void> {
     await this.queueSmartProxyLifecycleTask(async () => {

package/ts/config/classes.route-config-manager.ts

@@ -16,6 +16,12 @@ import type {
 } from '../../ts_interfaces/data/route-management.js';
 import type { IDcRouterRouteConfig } from '../../ts_interfaces/data/remoteingress.js';
 import { type IHttp3Config, augmentRouteWithHttp3, routeNeedsHttpProtocol } from '../http3/index.js';
+import {
+  DomainOwnershipError,
+  resolveDomainOwnership,
+  type IDomainOwnershipUnverified,
+  type IDomainOwnershipZone,
+} from '../dns/domain-ownership.js';
 import type { ReferenceResolver } from './classes.reference-resolver.js';
 import { SourcePolicyCompiler } from './classes.source-policy-compiler.js';
 import { deriveHttpRedirects } from './helpers.http-redirects.js';
@@ -32,6 +38,23 @@ export interface IRouteMutationResult {
   message?: string;
 }
 
+/**
+ * Supplies the ownership inputs a route's certificate requirement is checked
+ * against. Injected (rather than importing DnsManager) so route management keeps
+ * its single direction of dependency and stays unit-testable.
+ */
+export interface IRouteDomainOwnershipSource {
+  listOwnershipZones: () => Promise<IDomainOwnershipZone[]>;
+  getAuthorityZones: () => string[];
+}
+
+/** A route hostname whose certificate requirement has no ownership proof. */
+export interface IUnverifiedRouteDomain {
+  routeId: string;
+  routeName: string;
+  ownership: IDomainOwnershipUnverified;
+}
+
 interface IRouteMutationOptions {
   trustedManagedMutation?: boolean;
   replaceMetadata?: boolean;
@@ -72,6 +95,7 @@ export class RouteConfigManager {
   private routes = new Map<string, IRoute>();
   private warnings: IRouteWarning[] = [];
   private routeUpdateMutex = new RouteUpdateMutex();
+  private domainOwnershipSource?: IRouteDomainOwnershipSource;
 
   constructor(
     private getSmartProxy: () => plugins.smartproxy.SmartProxy | undefined,
@@ -99,6 +123,155 @@ export class RouteConfigManager {
     this.getVpnClientAccessForRoute = resolver;
   }
 
+  /**
+   * Wire the ownership inputs used to gate certificate requirements. Until this
+   * is set, any route asking for an automatic certificate is refused — a missing
+   * wiring must never silently disable the gate.
+   */
+  public setDomainOwnershipSource(source?: IRouteDomainOwnershipSource): void {
+    this.domainOwnershipSource = source;
+  }
+
+  // =========================================================================
+  // Certificate requirement / domain ownership gate
+  // =========================================================================
+
+  /**
+   * Hostnames for which this route asks dcrouter to obtain a certificate.
+   * `tls.certificate === 'auto'` on a terminating route is exactly what makes
+   * SmartProxy call certProvisionFunction, i.e. what starts an ACME order.
+   */
+  private collectAutoCertificateHostnames(route: IDcRouterRouteConfig): string[] {
+    const tls = route.action?.tls;
+    if (!tls || tls.mode === 'passthrough' || tls.certificate !== 'auto') {
+      return [];
+    }
+    const domains = route.match?.domains;
+    const entries = Array.isArray(domains)
+      ? domains
+      : typeof domains === 'string'
+        ? domains.split(',')
+        : [];
+    const hostnames = new Set<string>();
+    for (const entry of entries) {
+      const trimmed = typeof entry === 'string' ? entry.trim() : '';
+      if (trimmed) hostnames.add(trimmed);
+    }
+    return [...hostnames];
+  }
+
+  /**
+   * Refuse a route whose certificate requirement covers a domain we cannot prove
+   * we own. This is the point of attribution: the operator making the change gets
+   * the reason, instead of a DNS-01 order failing hours later and consuming a
+   * per-domain retry budget that no retry could ever satisfy.
+   */
+  private async assertCertificateRequirementOwnership(
+    route: IDcRouterRouteConfig,
+    operation: string,
+  ): Promise<void> {
+    const hostnames = this.collectAutoCertificateHostnames(route);
+    if (hostnames.length === 0) {
+      return;
+    }
+    if (!this.domainOwnershipSource) {
+      throw new Error(
+        `${operation} refused: domain ownership verification is unavailable, so a certificate requirement for `
+          + `${hostnames.join(', ')} cannot be checked. This is a wiring defect, not a configuration problem.`,
+      );
+    }
+    const zones = await this.domainOwnershipSource.listOwnershipZones();
+    const authorityZones = this.domainOwnershipSource.getAuthorityZones();
+    for (const hostname of hostnames) {
+      const ownership = resolveDomainOwnership({ fqdn: hostname, zones, authorityZones });
+      if (!ownership.verified) {
+        throw new DomainOwnershipError(ownership, operation, 'route-config-manager', {
+          data: { routeName: route.name },
+        });
+      }
+    }
+  }
+
+  /**
+   * Audit already-stored routes for certificate requirements on unverified
+   * domains.
+   *
+   * Deliberately an audit and not a refusal: these routes are already live, and
+   * a route can be serving traffic on a certificate issued while the domain was
+   * still verifiable, or on a static certificate elsewhere in the set. Refusing
+   * them at startup would convert a latent misconfiguration into an immediate
+   * outage, and the incident these checks exist for cost us silence, not serving.
+   * New and updated routes are refused outright; existing ones are surfaced.
+   */
+  public async auditRouteDomainOwnership(): Promise<IUnverifiedRouteDomain[]> {
+    if (!this.domainOwnershipSource) {
+      return [];
+    }
+    const auditableRoutes = [...this.routes.values()].filter((storedRoute) => {
+      return storedRoute.enabled
+        && this.collectAutoCertificateHostnames(storedRoute.route).length > 0;
+    });
+    if (auditableRoutes.length === 0) {
+      return [];
+    }
+
+    const zones = await this.domainOwnershipSource.listOwnershipZones();
+    const authorityZones = this.domainOwnershipSource.getAuthorityZones();
+    const findings: IUnverifiedRouteDomain[] = [];
+    for (const storedRoute of auditableRoutes) {
+      for (const hostname of this.collectAutoCertificateHostnames(storedRoute.route)) {
+        const ownership = resolveDomainOwnership({ fqdn: hostname, zones, authorityZones });
+        if (ownership.verified) continue;
+        findings.push({
+          routeId: storedRoute.id,
+          routeName: storedRoute.route.name || storedRoute.id,
+          ownership,
+        });
+      }
+    }
+    return findings;
+  }
+
+  /**
+   * Run the audit, publish it as route warnings, and log each finding at `error`
+   * so it reaches the ops log stream rather than only the warnings panel.
+   *
+   * Public because a DNS-authority change can make a previously unprovable
+   * certificate requirement provable (or the reverse) without any route changing.
+   */
+  public async refreshDomainOwnershipWarnings(): Promise<void> {
+    let findings: IUnverifiedRouteDomain[];
+    try {
+      findings = await this.auditRouteDomainOwnership();
+    } catch (err: unknown) {
+      logger.log(
+        'error',
+        `Route domain ownership audit failed: ${(err as Error).message}. `
+          + 'Certificate requirements on unverified domains may be present and unreported.',
+      );
+      return;
+    }
+
+    this.warnings = this.warnings.filter(
+      (warning) => warning.type !== 'unverified-domain-ownership',
+    );
+    for (const finding of findings) {
+      const message = `Route '${finding.routeName}' (id: ${finding.routeId}) requests an automatic certificate for `
+        + `'${finding.ownership.fqdn}', whose ownership is unverified (${finding.ownership.reason}): `
+        + `${finding.ownership.detail}. Certificate provisioning for this domain cannot succeed until that is fixed.`;
+      this.warnings.push({
+        type: 'unverified-domain-ownership',
+        routeName: finding.routeName,
+        message,
+      });
+      logger.log('error', message, {
+        routeId: finding.routeId,
+        domain: finding.ownership.fqdn,
+        ownershipReason: finding.ownership.reason,
+      });
+    }
+  }
+
   public async runExclusiveRouteUpdate<T>(fn: () => Promise<T>): Promise<T> {
     return await this.routeUpdateMutex.runExclusive(fn);
   }
@@ -118,6 +291,7 @@ export class RouteConfigManager {
     await this.seedRoutes(dnsRoutes, 'dns');
     this.computeWarnings();
     this.logWarnings();
+    await this.refreshDomainOwnershipWarnings();
     await this.applyRoutes();
   }
 
@@ -191,6 +365,12 @@ export class RouteConfigManager {
     if (sourceBindingsValidationError) {
       throw new Error(sourceBindingsValidationError);
     }
+    // Nothing is persisted or applied until the certificate requirement is proven
+    // to cover only domains we own. A disabled route provisions nothing, so only
+    // routes that will actually be applied are gated.
+    if (enabled) {
+      await this.assertCertificateRequirementOwnership(route, 'Route creation');
+    }
 
     const stored: IRoute = {
       id,
@@ -334,10 +514,27 @@ export class RouteConfigManager {
       return { success: false, message: sourceBindingsValidationError };
     }
 
+    // An update can introduce a certificate requirement, add a hostname to an
+    // existing one, or re-enable a route that carries one — all of them must
+    // clear the ownership gate before anything is persisted or applied.
+    // Disabling is never gated: an operator must always be able to turn a route
+    // off, including the ones this gate is complaining about.
+    if (stored.enabled) {
+      try {
+        await this.assertCertificateRequirementOwnership(stored.route, 'Route update');
+      } catch (err: unknown) {
+        stored.route = previousRoute;
+        stored.metadata = previousMetadata;
+        stored.enabled = previousEnabled;
+        return { success: false, message: (err as Error).message };
+      }
+    }
+
     stored.updatedAt = Date.now();
 
     await this.persistRoute(stored);
     await this.applyRoutes();
+    await this.refreshDomainOwnershipWarnings();
     return { success: true };
   }
 

package/ts/db/documents/classes.dns-authority.doc.ts

@@ -0,0 +1,49 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { IDnsAuthorityZone } from '../../../ts_interfaces/data/dns-authority.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+/**
+ * Singleton DNS-authority document. One row per dcrouter instance, keyed on the
+ * fixed `settingsId`, following the `AcmeConfigDoc` / `RemoteIngressHubSettingsDoc`
+ * pattern rather than introducing a third settings shape.
+ *
+ * Holds the zones whose authority was **proven** by an observed public
+ * delegation to our nameservers. This is the authority set — the whole of it.
+ * Deployment configuration contributes nothing: `dnsScopes` used to add an
+ * always-in-effect floor, and duplicating one fact into two places is what let
+ * the two representations drift, which is the bug class this document closes.
+ *
+ * Reading it is therefore load-bearing. `DnsAuthorityManager.start()` treats an
+ * absent document (known-empty: claim nothing) differently from an unreadable
+ * one (unknown: refuse to start), because rendering the second as the first
+ * would turn a database blip into every zone dropping off the air.
+ */
+@plugins.smartdata.Collection(() => getDb())
+export class DnsAuthorityDoc extends plugins.smartdata.SmartDataDbDoc<DnsAuthorityDoc, DnsAuthorityDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public settingsId: string = 'dns-authority-settings';
+
+  /**
+   * Delegation-verified zones. Each entry carries the evidence that justified
+   * it, so a later audit can tell what was observed and when.
+   */
+  @plugins.smartdata.svDb()
+  public verifiedZones: IDnsAuthorityZone[] = [];
+
+  @plugins.smartdata.svDb()
+  public updatedAt: number = 0;
+
+  @plugins.smartdata.svDb()
+  public updatedBy: string = '';
+
+  constructor() {
+    super();
+  }
+
+  public static async load(): Promise<DnsAuthorityDoc | null> {
+    return await DnsAuthorityDoc.getInstance({ settingsId: 'dns-authority-settings' });
+  }
+}

package/ts/db/documents/index.ts

@@ -34,6 +34,7 @@ export * from './classes.accounting-session.doc.js';
 export * from './classes.dns-provider.doc.js';
 export * from './classes.domain.doc.js';
 export * from './classes.dns-record.doc.js';
+export * from './classes.dns-authority.doc.js';
 
 // ACME configuration (singleton)
 export * from './classes.acme-config.doc.js';