@serve.zone/dcrouter 17.10.2 → 18.0.0

package/ts/dns/classes.dns-server-runtime.ts

@@ -3,9 +3,25 @@ import { logger } from '../logger.js';
 import { buildEmailDnsRecords } from '../email/index.js';
 import type { DcRouter } from '../classes.dcrouter.js';
 import type { IDcRouterRouteConfig } from '../../ts_interfaces/data/remoteingress.js';
+import {
+  resolveDomainOwnership,
+  type IDomainOwnershipZone,
+} from './domain-ownership.js';
 
 type TDnsRecordSeed = { name: string; type: string; value: string; ttl?: number; useIngressProxy?: boolean };
 
+/**
+ * The zone smartdns is handed when the authority set is empty.
+ *
+ * smartdns falls back to `[dnssecZone]` whenever `authoritativeZones` is empty,
+ * so this value decides what an *unauthoritative* dcrouter would claim. It has
+ * to be a name that can never match a real question, or a database that has not
+ * been seeded yet would quietly start asserting authority over whatever
+ * placeholder we picked. `.invalid` is reserved by RFC 2606 and is guaranteed
+ * never to be delegated to anybody.
+ */
+export const NO_AUTHORITY_SENTINEL_ZONE = 'no-authority.invalid';
+
 /**
  * Sets up and feeds the embedded authoritative smartdns server: validates the
  * DNS configuration, generates authoritative/email/DKIM records, applies
@@ -21,8 +37,37 @@ export class DnsServerRuntime {
 
   private privateRouteHostnames = new Set<string>();
   private privateRouteTargetIp?: string;
+
+  /**
+   * The array instance handed to smartdns as `authoritativeZones`.
+   *
+   * smartdns keeps the options object by reference and re-reads this array on
+   * every query, so mutating it in place changes the authority set of a
+   * *running* server.
+   *
+   * **This is a consumer-side shim, and it is sequenced for replacement.**
+   * `authoritativeZones` is a public option, but "the array is retained by
+   * reference and re-read per query" is storage behaviour, not a documented
+   * contract. The proper fix is a `setAuthoritativeZones()` on smartdns' own
+   * `DnsServer`; it cannot be written here because that release does not exist
+   * yet, and the only alternative available today — re-creating the server to
+   * change its zones — drops UDP/TCP 53, which is the 30–60 s public outage
+   * this entire path exists to remove.
+   *
+   * Guarded two ways until the setter ships: `assertLiveAuthorityZones()` logs
+   * at `error` if the reference is no longer shared after construction, and a
+   * test asserts that identity against the installed smartdns so a release that
+   * starts copying the array fails the suite rather than production.
+   */
+  private readonly authoritativeZones: string[] = [];
+
   constructor(private dcRouterRef: DcRouter) {}
 
+  /** The authority set, from the database and nowhere else. */
+  private effectiveAuthorityZones(): string[] {
+    return this.dcRouterRef.dnsAuthorityManager?.getEffectiveZoneNames() || [];
+  }
+
   /**
    * Create the DNS server, start it on UDP, wire metrics/logging, and
    * register all generated records.
@@ -33,8 +78,41 @@ export class DnsServerRuntime {
       throw new Error('dnsNsDomains is required for DNS server setup');
     }
 
-    if (!options.dnsScopes || options.dnsScopes.length === 0) {
-      throw new Error('dnsScopes is required for DNS server setup');
+    // Refuse to start when the authority set is *unknown*.
+    //
+    // This guard is load-bearing and cannot be delegated to the service graph.
+    // `DnsServer.dependsOn('DnsManager')` only orders startup levels — taskbuffer
+    // starts later levels even when an earlier optional service failed — so
+    // without this check an unreadable authority document would leave
+    // `dnsAuthorityManager` undefined, `effectiveAuthorityZones()` would return
+    // `[]`, and the server would come up REFUSING every query. That is exactly
+    // the collapse of "unknown" into "claim nothing" that the three-state model
+    // exists to prevent, and it would be indistinguishable from a legitimately
+    // empty database.
+    const authorityManager = this.dcRouterRef.dnsAuthorityManager;
+    if (!authorityManager || authorityManager.getState() === 'unavailable') {
+      throw new Error(
+        'DNS authority is unknown (the authority manager is '
+          + `${authorityManager ? 'unavailable' : 'not initialized'}), so the DNS server will not start. `
+          + 'dcrouter serves DNS authority from the database alone; answering with an empty authority set would '
+          + 'assert "we are authoritative for nothing", which is a claim an unreadable database cannot back. '
+          + 'Restore database access and restart.',
+      );
+    }
+
+    // A *known*-empty set is different, and must not stop the server: DoH
+    // routes, the private-route overlay and, above all, the ability to pick up
+    // a zone the moment it is verified all depend on the server being up.
+    // Fail closed on *authority*, never silently on *service*.
+    const bootAuthorityZones = this.syncAuthorityZones('DNS server setup');
+    if (bootAuthorityZones.length === 0) {
+      logger.log(
+        'error',
+        'DNS server is starting with an empty authority set: no zone has been delegation-verified, so every '
+          + 'query will be REFUSED until one is. This is what an unseeded database looks like — read the startup '
+          + 'delegation drift audit for the list of zones delegated to us that we are refusing to serve.',
+        { zone: 'dns' },
+      );
     }
 
     const primaryNameserver = options.dnsNsDomains[0];
@@ -71,13 +149,19 @@ export class DnsServerRuntime {
       udpBindInterface: vmIpAddress,
       httpsPort: 443, // Required but won't bind due to manual mode
       manualHttpsMode: true, // Enable manual HTTPS socket handling
-      dnssecZone: options.dnsScopes[0],
-      authoritativeZones: options.dnsScopes,
+      // The DNSSEC signing zone is baked into the Rust config at start and
+      // cannot be changed without a restart, so it is taken from the boot-time
+      // authority set — sorted, therefore stable across restarts rather than
+      // dependent on database insertion order.
+      dnssecZone: bootAuthorityZones[0] || NO_AUTHORITY_SENTINEL_ZONE,
+      // Live array, mutated in place by syncAuthorityZones(). See the field.
+      authoritativeZones: this.authoritativeZones,
       primaryNameserver: primaryNameserver, // Automatically generates correct SOA records
       // For now, use self-signed cert until we integrate with Let's Encrypt
       httpsKey: '',
       httpsCert: ''
     });
+    this.assertLiveAuthorityZones(dnsServer);
     this.dcRouterRef.dnsServer = dnsServer;
     this.registerPrivateRouteHandler(dnsServer);
 
@@ -180,13 +264,80 @@ export class DnsServerRuntime {
     this.dcRouterRef.mailDnsSync?.requestSync('DNS server attached');
   }
 
+  /**
+   * Re-derive the running server's authoritative zone set from the database.
+   *
+   * This is the half of authority that registering handlers cannot express.
+   * smartdns decides the *response kind* from `authoritativeZones` alone: a name
+   * inside a configured zone gets an answer or an authoritative negative, and a
+   * name outside every configured zone gets REFUSED — even when a handler is
+   * registered and answers other qtypes for that exact name. That asymmetry is
+   * the live production defect. `social.io` and `hard.global` are delegated to
+   * us and have handlers, so `A` is answered with the `aa` bit, while `AAAA` and
+   * `SOA` for the same name are REFUSED, and public recursives turn a REFUSED
+   * arm of a dual-stack lookup into SERVFAIL. Verifying a zone therefore has to
+   * update this set, not just register handlers, or the zone stays half-served.
+   *
+   * Idempotent, and safe to call on every authority reconcile.
+   *
+   * @returns the zone set now in effect.
+   */
+  public syncAuthorityZones(reasonArg: string): string[] {
+    const nextZones = this.effectiveAuthorityZones();
+    const changed = nextZones.length !== this.authoritativeZones.length
+      || nextZones.some((zone, index) => zone !== this.authoritativeZones[index]);
+    // In place: smartdns holds this exact array and re-reads it per query.
+    this.authoritativeZones.splice(0, this.authoritativeZones.length, ...nextZones);
+    if (changed) {
+      logger.log(
+        'info',
+        `DNS authoritative zone set is now [${nextZones.join(', ') || 'empty'}] (${reasonArg})`,
+        { zone: 'dns' },
+      );
+    }
+    return nextZones;
+  }
+
+  /**
+   * Prove smartdns kept our array rather than copying it.
+   *
+   * If this ever fails, authority silently freezes at its boot-time value and
+   * every runtime verification stops taking effect until a restart — a failure
+   * that is invisible from the outside because the server keeps answering
+   * correctly for the zones it started with. Logged rather than thrown: a frozen
+   * authority set is a degradation, and taking DNS down entirely over it would
+   * be worse than the fault it reports.
+   */
+  private assertLiveAuthorityZones(
+    dnsServerArg: plugins.smartdns.dnsServerMod.DnsServer,
+  ): void {
+    const heldZones = (dnsServerArg as unknown as {
+      options?: { authoritativeZones?: string[] };
+    }).options?.authoritativeZones;
+    if (heldZones === this.authoritativeZones) return;
+    logger.log(
+      'error',
+      'smartdns did not retain the authoritative zone array by reference, so DNS authority can no longer be '
+        + 'reconciled without restarting the DNS server. Zones verified at runtime will register handlers but '
+        + 'keep answering REFUSED for every qtype they do not handle until dcrouter is restarted.',
+      { zone: 'dns' },
+    );
+  }
+
   /**
    * Keep an internal-only A-record overlay for exact route hostnames whose
    * compiled source policy is private or whose only ingress is SmartVPN.
    * Public routes compile without clientIp restrictions and are never added.
+   *
+   * Every hostname must clear the domain-ownership gate first. This overlay is
+   * only "internal" by intent, never by mechanism: smartdns marks any answer a
+   * registered handler produces authoritative, and the server listens on a public
+   * UDP/TCP 53. Ungated, a single route was enough to make dcrouter publicly hand
+   * out an RFC1918 address, with the `aa` flag, for a domain whose real
+   * delegation belonged to somebody else.
    */
-  public syncPrivateRouteOverrides(routesArg: IDcRouterRouteConfig[]): void {
-    const nextHostnames = new Set<string>();
+  public async syncPrivateRouteOverrides(routesArg: IDcRouterRouteConfig[]): Promise<void> {
+    const candidateHostnames = new Set<string>();
     for (const route of routesArg) {
       if (route.action?.type !== 'forward') continue;
       const ingress = route.ingress;
@@ -211,10 +362,12 @@ export class DnsServerRuntime {
           : [];
       for (const domainArg of domainEntries) {
         const hostname = this.normalizePrivateRouteHostname(domainArg);
-        if (hostname) nextHostnames.add(hostname);
+        if (hostname) candidateHostnames.add(hostname);
       }
     }
 
+    const nextHostnames = await this.filterOwnedPrivateRouteHostnames(candidateHostnames);
+
     const changed = nextHostnames.size !== this.privateRouteHostnames.size
       || [...nextHostnames].some((hostnameArg) => !this.privateRouteHostnames.has(hostnameArg));
     this.privateRouteHostnames = nextHostnames;
@@ -227,6 +380,68 @@ export class DnsServerRuntime {
     }
   }
 
+  /**
+   * Drop overlay hostnames whose zone ownership cannot be proven, logging each
+   * rejection at `error` with the reason. Fails closed: if the ownership inputs
+   * cannot be read, no hostname is served rather than all of them.
+   */
+  private async filterOwnedPrivateRouteHostnames(
+    candidateHostnames: Set<string>,
+  ): Promise<Set<string>> {
+    if (candidateHostnames.size === 0) {
+      return new Set<string>();
+    }
+    // The delegation-verified authority set, so a zone verified at runtime
+    // starts serving its overlay entries without a restart.
+    const authorityZones = this.dcRouterRef.dnsManager?.getAuthorityZones()
+      || this.effectiveAuthorityZones();
+    let zones: IDomainOwnershipZone[];
+    try {
+      zones = (await this.dcRouterRef.dnsManager?.listOwnershipZones()) || [];
+    } catch (error: unknown) {
+      logger.log(
+        'error',
+        `DNS private-route overlay: cannot read managed zones (${(error as Error).message}); `
+          + `refusing to serve ${candidateHostnames.size} private route hostname(s) rather than answering for unverified domains`,
+        { zone: 'dns' },
+      );
+      return new Set<string>();
+    }
+
+    const ownedHostnames = new Set<string>();
+    for (const hostname of candidateHostnames) {
+      const ownership = resolveDomainOwnership({ fqdn: hostname, zones, authorityZones });
+      if (ownership.verified) {
+        ownedHostnames.add(hostname);
+        continue;
+      }
+      logger.log(
+        'error',
+        `DNS private-route overlay: refusing to answer for '${hostname}' — ${ownership.detail}. `
+          + 'dcrouter answers authoritatively on a public port, so serving this would claim a domain we cannot prove we own.',
+        { zone: 'dns', ownershipReason: ownership.reason },
+      );
+    }
+    return ownedHostnames;
+  }
+
+  /**
+   * SEQUENCED BEHIND A SMARTDNS RELEASE — this registration must become
+   * `{ authority: 'non-authoritative', owner: 'private-route-overlay' }`.
+   *
+   * The overlay is a split-horizon answer by intent: it hands out an internal
+   * address for a hostname whose zone we own, and it deliberately matches `*`
+   * so it can cover any owned hostname. Under the hardened smartdns authority
+   * model, a handler left at the default `authoritative` mode is *suppressed*
+   * for any name outside every configured `authoritativeZones` entry. Overlay
+   * hostnames proven by `provider-zone` are exactly that — owned, but not in
+   * the delegation-verified set — so on that smartdns they would stop being
+   * answered entirely, silently.
+   *
+   * The options parameter does not exist in the installed smartdns (7.12.1) and
+   * the change adding it is unreleased, so this cannot be written yet. It must
+   * land in the same change that takes the smartdns bump.
+   */
   private registerPrivateRouteHandler(
     dnsServerArg: plugins.smartdns.dnsServerMod.DnsServer,
   ): void {
@@ -370,32 +585,38 @@ export class DnsServerRuntime {
 
   private async validateConfiguration(): Promise<void> {
     const options = this.dcRouterRef.options;
-    if (!options.dnsNsDomains || !options.dnsScopes) {
+    if (!options.dnsNsDomains) {
       return;
     }
+    const authorityZones = this.effectiveAuthorityZones();
 
     logger.log('info', 'Validating DNS configuration...');
+    const covered = (nameArg: string): boolean => authorityZones.some((zone) =>
+      nameArg === zone || nameArg.endsWith(`.${zone}`));
 
-    // Check if email domains with internal-dns are in dnsScopes
+    // Email domains served from the embedded DNS need the zone to be ours.
     if (options.emailConfig?.domains) {
       for (const domainConfig of options.emailConfig.domains) {
-        if (domainConfig.dnsMode === 'internal-dns' &&
-            !options.dnsScopes.includes(domainConfig.domain)) {
-          logger.log('warn', `Email domain '${domainConfig.domain}' with internal-dns mode is not in dnsScopes. It should be added to dnsScopes.`);
+        if (domainConfig.dnsMode === 'internal-dns' && !covered(domainConfig.domain.toLowerCase())) {
+          logger.log(
+            'warn',
+            `Email domain '${domainConfig.domain}' uses internal-dns but its zone is not delegation-verified, `
+              + 'so dcrouter will REFUSE queries for it. Verify the zone (dns-authority:write) to serve it.',
+          );
         }
       }
     }
 
-    // Validate user-provided DNS records are within scopes
+    // Validate caller-provided DNS records fall inside a zone we may answer for
     if (options.dnsRecords) {
       for (const record of options.dnsRecords) {
-        const recordDomain = this.extractDomain(record.name);
-        const isInScope = options.dnsScopes.some(scope =>
-          recordDomain === scope || recordDomain.endsWith(`.${scope}`)
-        );
-
-        if (!isInScope) {
-          logger.log('warn', `DNS record for '${record.name}' is outside defined scopes [${options.dnsScopes.join(', ')}]`);
+        const recordDomain = this.extractDomain(record.name).toLowerCase();
+        if (!covered(recordDomain)) {
+          logger.log(
+            'warn',
+            `DNS record for '${record.name}' is outside every delegation-verified zone `
+              + `[${authorityZones.join(', ') || 'none'}] and will be REFUSED`,
+          );
         }
       }
     }
@@ -486,11 +707,24 @@ export class DnsServerRuntime {
     );
   }
 
+  /**
+   * Nameserver A records (glue) only.
+   *
+   * Generated apex NS records used to be emitted here, one static set per
+   * bootstrap `dnsScopes` entry, registered once at setup and never revisited.
+   * Under database-sourced authority that is wrong twice over: a zone verified
+   * after startup would never get them, and a zone whose authority was revoked
+   * would keep them until an unrelated restart. `DnsManager` owns generated apex
+   * NS for every authoritative zone now — it already did for every zone that was
+   * not in `dnsScopes` — and reconciles them in-process in both directions.
+   * A verified zone with no `DomainDoc` behind it therefore serves no apex NS,
+   * which the `verified-but-unhosted` drift finding reports at `error`.
+   */
   private async generateAuthoritativeRecords(): Promise<TDnsRecordSeed[]> {
     const options = this.dcRouterRef.options;
     const records: TDnsRecordSeed[] = [];
 
-    if (!options.dnsNsDomains || !options.dnsScopes) {
+    if (!options.dnsNsDomains) {
       return records;
     }
 
@@ -544,23 +778,8 @@ export class DnsServerRuntime {
       logger.log('info', `Generated A records for ${options.dnsNsDomains.length} nameservers`);
     }
 
-    // Generate NS records for each domain in scopes
-    for (const domain of options.dnsScopes) {
-      // Add NS records for all nameservers
-      for (const nsDomain of options.dnsNsDomains) {
-        records.push({
-          name: domain,
-          type: 'NS',
-          value: nsDomain,
-          ttl: 3600
-        });
-      }
-
-      // SOA records are now automatically generated by smartdns DnsServer
-      // with the primaryNameserver configuration option
-    }
-
-    logger.log('info', `Generated ${records.length} total records (A + NS) for ${options.dnsScopes.length} domains`);
+    // Apex NS records are owned by DnsManager (see the doc comment above), and
+    // SOA is synthesized by smartdns from `primaryNameserver`.
     return records;
   }
 

package/ts/dns/domain-ownership.ts

@@ -0,0 +1,272 @@
+import { PlatformError, type IErrorContext } from '../errors/base.errors.js';
+import {
+  DCR_DOMAIN_OWNERSHIP_UNVERIFIED,
+  ErrorCategory,
+  ErrorRecoverability,
+  ErrorSeverity,
+} from '../errors/error.codes.js';
+import type { TDomainSource } from '../../ts_interfaces/data/domain.js';
+
+/**
+ * Domain ownership verification.
+ *
+ * dcrouter may only take two kinds of action on a hostname if we can prove the
+ * zone is ours: request an ACME certificate for it, and answer DNS queries for
+ * it authoritatively. Both used to be reachable without any ownership record at
+ * all, which produced two production failures:
+ *
+ *  - Routes with `tls.certificate === 'auto'` were created for zones that had no
+ *    `DomainDoc`. DNS-01 could never place the challenge TXT, so the per-domain
+ *    provisioning budget was consumed against a cause no retry can fix and the
+ *    certificates silently expired.
+ *  - `DomainDoc`s created through the ops API set `authoritative = true`
+ *    unconditionally, and the embedded smartdns server marks *any* answer a
+ *    registered handler produces as authoritative (`aa`) regardless of
+ *    `authoritativeZones`. dcrouter therefore served apex NS records and an
+ *    RFC1918 A record, publicly, for zones whose real delegation belonged to
+ *    third parties.
+ *
+ * There are exactly two proofs available in-process, neither of which an ops-API
+ * caller can forge:
+ *
+ *  - `provider-zone`: the zone has a `DomainDoc` with `source === 'provider'` and
+ *    a `providerId`. It only gets there through `importDomainsFromProvider()`,
+ *    which requires the zone to be listed by a credentialed provider account.
+ *  - `delegation-verified-zone`: the zone is in the DNS authority set, which a
+ *    zone only enters by having its public NS records observed naming our
+ *    nameservers. An ops-API caller cannot repoint somebody else's delegation,
+ *    so writing the record is not the same as manufacturing the proof.
+ *
+ * This used to read `options.dnsScopes` instead — deployment configuration,
+ * trusted because only a redeploy could change it. That trust was real but the
+ * cost was a second, un-reconcilable representation of DNS authority, so it is
+ * gone: the authority set now comes from the database and carries its evidence.
+ *
+ * Anything else is unverified and must fail closed.
+ */
+
+export type TDomainOwnershipMethod = 'provider-zone' | 'delegation-verified-zone';
+
+export type TDomainOwnershipFailure =
+  /** No DomainDoc covers the hostname at all. */
+  | 'no-managed-domain'
+  /** Provider-sourced DomainDoc without a providerId — the credentialed link is gone. */
+  | 'provider-link-missing'
+  /** dcrouter-hosted DomainDoc outside every verified zone: self-asserted authority. */
+  | 'unverified-dcrouter-zone'
+  /** The hostname is not a usable FQDN (wildcard-only, empty, malformed labels). */
+  | 'invalid-hostname';
+
+export interface IDomainOwnershipZone {
+  name: string;
+  source: TDomainSource;
+  providerId?: string;
+}
+
+export interface IDomainOwnershipVerified {
+  verified: true;
+  fqdn: string;
+  zone: string;
+  method: TDomainOwnershipMethod;
+  evidence: string;
+}
+
+export interface IDomainOwnershipUnverified {
+  verified: false;
+  fqdn: string;
+  zone?: string;
+  reason: TDomainOwnershipFailure;
+  detail: string;
+}
+
+export type TDomainOwnership = IDomainOwnershipVerified | IDomainOwnershipUnverified;
+
+/**
+ * Normalize a route/record hostname to the FQDN whose ownership must be proven.
+ *
+ * A wildcard is proven by the zone beneath it, so a single leading `*` is
+ * stripped in both forms SmartProxy accepts for certificate provisioning:
+ * `*.example.com` and the routing-glob `*example.com` (see
+ * `normalizeDomainsForCertProvisioning` in smartproxy). A bare `*` normalizes to
+ * nothing and is rejected — no certificate can be issued for it, so it must fail
+ * loudly rather than reach ACME.
+ *
+ * Returns undefined for anything that is not a usable single hostname.
+ */
+export const normalizeOwnershipHostname = (hostnameArg: string): string | undefined => {
+  const hostname = hostnameArg
+    .trim()
+    .toLowerCase()
+    .replace(/\.$/, '')
+    .replace(/^\*\.?/, '');
+  if (!hostname || hostname.length > 253) return undefined;
+  if (hostname.includes('*') || hostname.includes(',') || hostname.includes(' ')) return undefined;
+  const labels = hostname.split('.');
+  if (labels.length < 2) return undefined;
+  if (labels.some((labelArg) => !labelArg || labelArg.length > 63
+    || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(labelArg))) return undefined;
+  return hostname;
+};
+
+const normalizeZoneName = (zoneArg: string): string =>
+  zoneArg.trim().toLowerCase().replace(/\.$/, '');
+
+const coversFqdn = (zone: string, fqdn: string): boolean =>
+  Boolean(zone) && (fqdn === zone || fqdn.endsWith(`.${zone}`));
+
+/**
+ * The authority zone covering `fqdn`, if any (the zone itself or a subzone of
+ * one). Subzones count: being authoritative for `example.com` means
+ * `internal.example.com` is ours too.
+ */
+export const findCoveringAuthorityZone = (
+  fqdnArg: string,
+  authorityZones?: string[],
+): string | undefined => {
+  const fqdn = normalizeZoneName(fqdnArg);
+  return (authorityZones || [])
+    .map(normalizeZoneName)
+    .filter(Boolean)
+    .sort((a, b) => b.length - a.length)
+    .find((zone) => coversFqdn(zone, fqdn));
+};
+
+/**
+ * Resolve whether we can prove ownership of `fqdn`. Pure: callers pass the zone
+ * set and the authority set so this stays testable and does exactly one DB
+ * read per audit pass rather than one per hostname.
+ */
+export const resolveDomainOwnership = (args: {
+  fqdn: string;
+  zones: IDomainOwnershipZone[];
+  authorityZones?: string[];
+}): TDomainOwnership => {
+  const fqdn = normalizeOwnershipHostname(args.fqdn);
+  if (!fqdn) {
+    return {
+      verified: false,
+      fqdn: args.fqdn,
+      reason: 'invalid-hostname',
+      detail: `'${args.fqdn}' is not a usable hostname, so its ownership cannot be established`,
+    };
+  }
+
+  // A delegation-verified zone is proof on its own: the public NS records were
+  // observed naming our nameservers, which no ops-API caller can arrange.
+  const coveringZone = findCoveringAuthorityZone(fqdn, args.authorityZones);
+  if (coveringZone) {
+    return {
+      verified: true,
+      fqdn,
+      zone: coveringZone,
+      method: 'delegation-verified-zone',
+      evidence: `dns-authority:${coveringZone}`,
+    };
+  }
+
+  // Otherwise the proof must come from a credentialed provider zone. Most
+  // specific zone first, but every covering zone is a candidate: owning
+  // example.com still proves sub.example.com even when a more specific
+  // dcrouter-hosted doc for the subzone exists. The first verified candidate
+  // wins; otherwise the most specific failure is reported.
+  const candidates = args.zones
+    .map((zoneArg) => ({ ...zoneArg, name: normalizeZoneName(zoneArg.name) }))
+    .filter((zoneArg) => coversFqdn(zoneArg.name, fqdn))
+    .sort((a, b) => b.name.length - a.name.length);
+
+  if (candidates.length === 0) {
+    return {
+      verified: false,
+      fqdn,
+      reason: 'no-managed-domain',
+      detail: `no managed domain and no delegation-verified zone covers ${fqdn}; import the zone from a DNS provider, or point its NS records at our nameservers and verify it, before requesting certificates or serving DNS for it`,
+    };
+  }
+
+  const failures: IDomainOwnershipUnverified[] = [];
+  for (const zone of candidates) {
+    if (zone.source === 'provider') {
+      if (!zone.providerId) {
+        failures.push({
+          verified: false,
+          fqdn,
+          zone: zone.name,
+          reason: 'provider-link-missing',
+          detail: `managed domain ${zone.name} is provider-sourced but has no providerId, so the credentialed zone listing that proved ownership is gone`,
+        });
+        continue;
+      }
+      return {
+        verified: true,
+        fqdn,
+        zone: zone.name,
+        method: 'provider-zone',
+        evidence: `provider:${zone.providerId}`,
+      };
+    }
+
+    failures.push({
+      verified: false,
+      fqdn,
+      zone: zone.name,
+      reason: 'unverified-dcrouter-zone',
+      detail: `managed domain ${zone.name} is dcrouter-hosted but is not in the DNS authority set, so nothing proves the zone is delegated to us; verify its delegation (dns-authority:write) or import it from the DNS provider that holds it`,
+    });
+  }
+
+  return failures[0];
+};
+
+export const buildDomainOwnershipMessage = (
+  ownership: IDomainOwnershipUnverified,
+  operation: string,
+): string =>
+  `${operation} refused for '${ownership.fqdn}': domain ownership is unverified (${ownership.reason}) — ${ownership.detail}`;
+
+/**
+ * Thrown wherever an unverified domain would otherwise gain a certificate
+ * requirement or authoritative DNS. HIGH severity so PlatformError's automatic
+ * log lands at `error` (this must never be a debuggable-later warning), and
+ * NON_RECOVERABLE by construction: no retry can turn an unowned domain into an
+ * owned one, so retry layers must classify it as permanent.
+ */
+export class DomainOwnershipError extends PlatformError {
+  public readonly ownership: IDomainOwnershipUnverified;
+
+  constructor(
+    ownership: IDomainOwnershipUnverified,
+    operation: string,
+    component: string,
+    context: IErrorContext = {},
+  ) {
+    super(
+      buildDomainOwnershipMessage(ownership, operation),
+      DCR_DOMAIN_OWNERSHIP_UNVERIFIED,
+      ErrorSeverity.HIGH,
+      ErrorCategory.CONFIGURATION,
+      ErrorRecoverability.NON_RECOVERABLE,
+      {
+        component,
+        operation,
+        userMessage: `Ownership of '${ownership.fqdn}' is not verified: ${ownership.detail}`,
+        ...context,
+        data: {
+          fqdn: ownership.fqdn,
+          zone: ownership.zone,
+          reason: ownership.reason,
+          ...context.data,
+        },
+      },
+    );
+    this.ownership = ownership;
+  }
+
+  protected createWithContext(context: IErrorContext): PlatformError {
+    return new DomainOwnershipError(
+      this.ownership,
+      this.context.operation || 'operation',
+      this.context.component || 'domain-ownership',
+      context,
+    );
+  }
+}

package/ts/dns/index.ts

@@ -1,4 +1,6 @@
 export * from './manager.dns.js';
+export * from './domain-ownership.js';
+export * from './manager.dns-authority.js';
 export * from './providers/index.js';
 export * from './classes.dns-server-runtime.js';
 export * from './classes.gateway-route-dns-reconciler.js';