@serve.zone/dcrouter 17.10.2 → 18.0.0

package/dist_ts/dns/manager.dns.d.ts

@@ -4,6 +4,22 @@ import type { IDcRouterOptions } from '../classes.dcrouter.js';
 import type { IDnsProviderClient } from './providers/interfaces.js';
 import type { TDnsRecordType, TDnsRecordSource } from '../../dist_ts_interfaces/data/dns-record.js';
 import type { TDnsProviderType, TDnsProviderCredentials, IDnsProviderPublic, IProviderDomainListing } from '../../dist_ts_interfaces/data/dns-provider.js';
+import { type IDomainOwnershipZone, type TDomainOwnership } from './domain-ownership.js';
+/**
+ * Where a runtime DnsServer handler came from.
+ *
+ * - 'persisted' → rebuilt from a DnsRecordDoc row.
+ * - 'generated-default' → synthesised by dcrouter (apex NS today; SOA and other
+ *   zone defaults would join this origin), so it has no DB row to enumerate and
+ *   must be torn down from the registry.
+ */
+export type TDnsRuntimeRegistrationOrigin = 'persisted' | 'generated-default';
+/** One runtime DnsServer handler key owned by a DomainDoc. */
+export interface IDnsRuntimeRegistration {
+    name: string;
+    type: TDnsRecordType;
+    origin: TDnsRuntimeRegistrationOrigin;
+}
 /**
  * DnsManager — owns runtime DNS state on top of the embedded DnsServer.
  *
@@ -22,7 +38,7 @@ export declare class DnsManager {
     private options;
     /**
      * Reference to the active smartdns DnsServer (set by DcRouter once it exists).
-     * May be undefined if dnsScopes/dnsNsDomains aren't configured.
+     * May be undefined if dnsNsDomains isn't configured.
      */
     dnsServer?: plugins.smartdns.dnsServerMod.DnsServer;
     /**
@@ -30,7 +46,39 @@ export declare class DnsManager {
      * Created lazily when a provider is first needed.
      */
     private providerClients;
+    /**
+     * Per-domain registry of the runtime DnsServer handlers this manager owns,
+     * keyed by DomainDoc.id then by `name|type`.
+     *
+     * Teardown must remove exactly what registration added — no more, no less.
+     * smartdns' `unregisterHandler(pattern, types)` removes *every* handler for a
+     * pattern/type pair, including the nameserver glue handlers owned by
+     * DnsServerRuntime and the global wildcard A handler. Reconstructing "would I
+     * have registered this?" at delete time is therefore unsafe: any drift in the
+     * inputs (authority changed, ownership changed, a record row vanished) makes the
+     * reconstruction tear down another owner's handlers or miss its own. Recording
+     * the actual registrations, with their origin, removes that class of bug.
+     */
+    private runtimeRegistrations;
+    /** Supplies the effective authority set (bootstrap ∪ delegation-verified). */
+    private authorityZonesResolver?;
     constructor(options: IDcRouterOptions);
+    private trackRuntimeRegistration;
+    private untrackRuntimeRegistration;
+    /** Registrations currently owned by a domain. Exposed for teardown assertions. */
+    listRuntimeRegistrations(domainId: string): IDnsRuntimeRegistration[];
+    /**
+     * Unregister every runtime handler owned by a domain and forget them.
+     *
+     * Called from every path that ends dcrouter's authority over a zone. Without
+     * it, deleting a DomainDoc removed the DB source of truth (so record queries
+     * started answering REFUSED) while the generated apex NS handler kept answering
+     * `aa` with our nameservers until the process was restarted — stale authority
+     * live in memory, with nothing telling the next operator to restart. A restart
+     * is not an acceptable delete procedure: it costs 30–60 s of total public
+     * outage.
+     */
+    private tearDownDomainRuntimeRegistrations;
     start(): Promise<void>;
     stop(): Promise<void>;
     /**
@@ -46,19 +94,72 @@ export declare class DnsManager {
     private applyDcrouterDomainsToDnsServer;
     /**
      * Authoritative zones must answer apex NS queries or their delegation is
-     * lame — Let's Encrypt's DNS-01 resolver SERVFAILs on such zones. Static
-     * dnsScopes zones get NS records in DnsServerRuntime; zones registered in
-     * the DB get them here, served from options.dnsNsDomains unless explicit
-     * apex NS records exist in the DB.
+     * lame — Let's Encrypt's DNS-01 resolver SERVFAILs on such zones. This is the
+     * only place generated apex NS records come from, for every authoritative
+     * zone: they are served from options.dnsNsDomains unless explicit apex NS
+     * records exist in the DB. DnsServerRuntime used to emit a static set for
+     * bootstrap `dnsScopes` zones, which could neither appear for a zone verified
+     * after startup nor disappear for one whose authority was revoked.
+     *
+     * Ownership is verified first. smartdns marks any answer a registered handler
+     * produces as authoritative (`aa`) regardless of `authoritativeZones`, so
+     * registering this handler for a zone we cannot prove we own makes dcrouter
+     * publicly claim authority over somebody else's domain.
      */
     private registerAuthoritativeZoneDefaults;
+    /** Ownership inputs for every managed zone, fetched once per evaluation pass. */
+    listOwnershipZones(): Promise<IDomainOwnershipZone[]>;
+    /**
+     * The authority set used as an ownership proof: the delegation-verified zones
+     * held in the database, and nothing else. Empty until the resolver is wired,
+     * which fails closed — an unwired manager proves ownership of nothing rather
+     * than falling back to a declared list that no longer exists.
+     */
+    getAuthorityZones(): string[];
+    /**
+     * Supply the effective authority set. Injected rather than imported so
+     * DnsManager keeps a single direction of dependency and stays unit-testable.
+     */
+    setAuthorityZonesResolver(resolver?: () => string[]): void;
+    /**
+     * Re-derive every generated apex NS registration against the current authority
+     * set. Zones that gained proof start being served; zones that lost it are torn
+     * down — both in-process, with no restart.
+     *
+     * Throws on the first failure so the caller can roll the change back rather
+     * than leave the router half-converted.
+     */
+    reconcileAuthoritativeZones(): Promise<{
+        registered: string[];
+        unregistered: string[];
+    }>;
+    /** Keep `DomainDoc.authoritative` honest after an authority change. */
+    syncAuthoritativeFlags(): Promise<number>;
+    /**
+     * Can we prove the zone containing `fqdn` is ours? This gates certificate
+     * requirements and authoritative DNS. See ts/dns/domain-ownership.ts.
+     */
+    resolveDomainOwnership(fqdn: string): Promise<TDomainOwnership>;
+    /**
+     * Ownership of a zone that is about to become dcrouter-hosted, evaluated
+     * against its post-write shape. Create and provider→dcrouter migration must
+     * not read their own pre-write row: the provider link they are removing would
+     * otherwise still count as the proof.
+     */
+    private resolveOwnershipForPendingDcrouterZone;
     /**
      * Register a single record with the embedded DnsServer. The handler closure
      * captures the record fields, so updates require a re-register cycle.
      */
     private registerRecordWithDnsServer;
     private rrsetKey;
-    /** Rebuild one authoritative RRset atomically from persisted rows. */
+    /**
+     * Rebuild one authoritative RRset atomically from persisted rows.
+     *
+     * The unregister-then-rebuild cycle also replaces a generated default on the
+     * same key (an explicit apex NS row supersedes the generated one), so the
+     * registry is updated to match what is actually registered afterwards.
+     */
     private refreshLocalRrset;
     private parseRecordData;
     /**
@@ -127,8 +228,14 @@ export declare class DnsManager {
     listDomains(): Promise<DomainDoc[]>;
     getDomain(id: string): Promise<DomainDoc | null>;
     /**
-     * Create a dcrouter-hosted (authoritative) domain. dcrouter will serve
-     * DNS records for this domain via the embedded smartdns.DnsServer.
+     * Create a dcrouter-hosted domain. dcrouter serves DNS records for it via the
+     * embedded smartdns.DnsServer.
+     *
+     * `authoritative` reflects whether ownership can actually be proven — it used
+     * to be hard-coded to `true`, which let an ops-API caller self-assert authority
+     * over any zone on the internet. Creating the record still succeeds (it is the
+     * container records and provider migration need), but an unverified zone is
+     * recorded as non-authoritative and gets no generated apex NS handler.
      */
     createDcrouterDomain(args: {
         name: string;
@@ -153,10 +260,12 @@ export declare class DnsManager {
      * For dcrouter-hosted domains, also unregisters records from the embedded
      * DnsServer.
      *
-     * Note: smartdns has no public unregister-by-name API in the version pinned
-     * here, so local record deletes only take effect after a restart. The DB
-     * is the source of truth and the next start will not register the deleted
-     * record.
+     * The unregister path is complete in-process: every runtime handler this
+     * manager registered for the domain — persisted RRsets and generated defaults
+     * alike — is removed from the registry, so deletion never leaves stale
+     * authority answering `aa` until an unrelated restart. Nameserver glue
+     * handlers and other domains' handlers are never touched, because only the
+     * domain's own recorded registrations are removed.
      */
     deleteDomain(id: string): Promise<boolean>;
     /**