@serve.zone/dcrouter 13.5.0 → 13.7.1

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

@@ -0,0 +1,227 @@
+import * as plugins from '../plugins.js';
+import { DnsProviderDoc, DomainDoc, DnsRecordDoc } from '../db/documents/index.js';
+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';
+/**
+ * DnsManager — owns runtime DNS state on top of the embedded DnsServer.
+ *
+ * Responsibilities:
+ *  - Load Domain/DnsRecord docs from the DB on start
+ *  - First-boot seeding from legacy constructor config (dnsScopes/dnsRecords/dnsNsDomains)
+ *  - Register manual-domain records with smartdns.DnsServer at startup
+ *  - Provide CRUD methods used by OpsServer handlers (manual domains hit smartdns,
+ *    provider domains hit the provider API)
+ *  - Expose a provider lookup used by the ACME DNS-01 wiring in setupSmartProxy()
+ *
+ * Provider-managed domains are NEVER served from the embedded DnsServer — the
+ * provider stays authoritative. We only mirror their records locally for the UI
+ * and to track providerRecordIds for updates / deletes.
+ */
+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.
+     */
+    dnsServer?: plugins.smartdns.dnsServerMod.DnsServer;
+    /**
+     * Cached provider clients, keyed by DnsProviderDoc.id.
+     * Created lazily when a provider is first needed.
+     */
+    private providerClients;
+    constructor(options: IDcRouterOptions);
+    /**
+     * Called from DcRouter after DcRouterDb is up. Performs first-boot seeding
+     * from legacy constructor config if (and only if) the DB is empty.
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Wire the embedded DnsServer instance after it has been created by
+     * DcRouter.setupDnsWithSocketHandler(). After this, manual records loaded
+     * from the DB are registered with the server.
+     */
+    attachDnsServer(dnsServer: plugins.smartdns.dnsServerMod.DnsServer): Promise<void>;
+    /**
+     * If no DomainDocs exist yet but the constructor has legacy DNS fields,
+     * seed them as `source: 'manual'` records. On subsequent boots (DB has
+     * entries), constructor config is ignored with a warning.
+     */
+    private seedFromConstructorConfigIfEmpty;
+    private findParentDomain;
+    /**
+     * Register all manual-domain records from the DB with the embedded DnsServer.
+     * Called once after attachDnsServer().
+     */
+    private applyManualDomainsToDnsServer;
+    /**
+     * 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 parseRecordData;
+    /**
+     * Get the provider client for a given DnsProviderDoc id, instantiating
+     * (and caching) it on first use.
+     */
+    getProviderClientById(providerId: string): Promise<IDnsProviderClient | null>;
+    /**
+     * Find the IDnsProviderClient that owns the given FQDN (by walking up its
+     * labels to find a matching DomainDoc with `source === 'provider'`).
+     * Returns null if no provider claims this FQDN.
+     *
+     * Used by:
+     *  - SmartAcme DNS-01 wiring in setupSmartProxy()
+     *  - DnsRecordHandler when creating provider records
+     */
+    getProviderClientForDomain(fqdn: string): Promise<IDnsProviderClient | null>;
+    /**
+     * True if any cloudflare provider exists in the DB. Used by setupSmartProxy()
+     * to decide whether to wire SmartAcme with a DNS-01 handler.
+     */
+    hasAcmeCapableProvider(): Promise<boolean>;
+    /**
+     * Build an IConvenientDnsProvider that dispatches each ACME challenge to
+     * the right provider client (whichever provider type owns the parent zone),
+     * based on the challenge's hostName. Provider-agnostic — uses the IDnsProviderClient
+     * interface, so any registered provider implementation works.
+     * Returned object plugs directly into smartacme's Dns01Handler.
+     */
+    buildAcmeConvenientDnsProvider(): plugins.tsclass.network.IConvenientDnsProvider;
+    listProviders(): Promise<IDnsProviderPublic[]>;
+    getProvider(id: string): Promise<IDnsProviderPublic | null>;
+    createProvider(args: {
+        name: string;
+        type: TDnsProviderType;
+        credentials: TDnsProviderCredentials;
+        createdBy: string;
+    }): Promise<string>;
+    updateProvider(id: string, args: {
+        name?: string;
+        credentials?: TDnsProviderCredentials;
+    }): Promise<boolean>;
+    deleteProvider(id: string, force: boolean): Promise<{
+        success: boolean;
+        message?: string;
+    }>;
+    testProvider(id: string): Promise<{
+        ok: boolean;
+        error?: string;
+        testedAt: number;
+    }>;
+    listProviderDomains(providerId: string): Promise<IProviderDomainListing[]>;
+    listDomains(): Promise<DomainDoc[]>;
+    getDomain(id: string): Promise<DomainDoc | null>;
+    /**
+     * Create a manual (authoritative) domain. dcrouter will serve DNS records
+     * for this domain via the embedded smartdns.DnsServer.
+     */
+    createManualDomain(args: {
+        name: string;
+        description?: string;
+        createdBy: string;
+    }): Promise<string>;
+    /**
+     * Import one or more domains from a provider, pulling all of their DNS
+     * records into local DnsRecordDocs.
+     */
+    importDomainsFromProvider(args: {
+        providerId: string;
+        domainNames: string[];
+        createdBy: string;
+    }): Promise<string[]>;
+    updateDomain(id: string, args: {
+        description?: string;
+    }): Promise<boolean>;
+    /**
+     * Delete a domain and all of its DNS records. For provider domains, only
+     * removes the local mirror — does NOT touch the provider.
+     * For manual domains, also unregisters records from the embedded DnsServer.
+     *
+     * Note: smartdns has no public unregister-by-name API in the version pinned
+     * here, so manual 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.
+     */
+    deleteDomain(id: string): Promise<boolean>;
+    /**
+     * Force-resync a provider-managed domain: re-pull all records from the
+     * provider API, replacing the cached DnsRecordDocs.
+     */
+    syncDomain(id: string): Promise<{
+        success: boolean;
+        recordCount?: number;
+        message?: string;
+    }>;
+    listRecordsForDomain(domainId: string): Promise<DnsRecordDoc[]>;
+    getRecord(id: string): Promise<DnsRecordDoc | null>;
+    createRecord(args: {
+        domainId: string;
+        name: string;
+        type: TDnsRecordType;
+        value: string;
+        ttl?: number;
+        proxied?: boolean;
+        createdBy: string;
+    }): Promise<{
+        success: boolean;
+        id?: string;
+        message?: string;
+    }>;
+    updateRecord(args: {
+        id: string;
+        name?: string;
+        value?: string;
+        ttl?: number;
+        proxied?: boolean;
+    }): Promise<{
+        success: boolean;
+        message?: string;
+    }>;
+    deleteRecord(id: string): Promise<{
+        success: boolean;
+        message?: string;
+    }>;
+    private createSyncedRecord;
+    /**
+     * Convert a DnsProviderDoc to its public, secret-stripped representation
+     * for the OpsServer API.
+     */
+    toPublicProvider(doc: DnsProviderDoc): IDnsProviderPublic;
+    /**
+     * Convert a DomainDoc to its plain interface representation.
+     */
+    toPublicDomain(doc: DomainDoc): {
+        id: string;
+        name: string;
+        source: 'manual' | 'provider';
+        providerId?: string;
+        authoritative: boolean;
+        nameservers?: string[];
+        externalZoneId?: string;
+        lastSyncedAt?: number;
+        description?: string;
+        createdAt: number;
+        updatedAt: number;
+        createdBy: string;
+    };
+    /**
+     * Convert a DnsRecordDoc to its plain interface representation.
+     */
+    toPublicRecord(doc: DnsRecordDoc): {
+        id: string;
+        domainId: string;
+        name: string;
+        type: TDnsRecordType;
+        value: string;
+        ttl: number;
+        proxied?: boolean;
+        source: TDnsRecordSource;
+        providerRecordId?: string;
+        createdAt: number;
+        updatedAt: number;
+        createdBy: string;
+    };
+}