@serve.zone/dcrouter 17.10.2 → 18.0.1

package/dist_ts/dns/domain-ownership.d.ts

@@ -0,0 +1,111 @@
+import { PlatformError, type IErrorContext } from '../errors/base.errors.js';
+import type { TDomainSource } from '../../dist_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 declare const normalizeOwnershipHostname: (hostnameArg: string) => string | undefined;
+/**
+ * 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 declare const findCoveringAuthorityZone: (fqdnArg: string, authorityZones?: string[]) => string | undefined;
+/**
+ * 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 declare const resolveDomainOwnership: (args: {
+    fqdn: string;
+    zones: IDomainOwnershipZone[];
+    authorityZones?: string[];
+}) => TDomainOwnership;
+export declare const buildDomainOwnershipMessage: (ownership: IDomainOwnershipUnverified, operation: string) => string;
+/**
+ * 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 declare class DomainOwnershipError extends PlatformError {
+    readonly ownership: IDomainOwnershipUnverified;
+    constructor(ownership: IDomainOwnershipUnverified, operation: string, component: string, context?: IErrorContext);
+    protected createWithContext(context: IErrorContext): PlatformError;
+}

package/dist_ts/dns/domain-ownership.js

@@ -0,0 +1,152 @@
+import { PlatformError } from '../errors/base.errors.js';
+import { DCR_DOMAIN_OWNERSHIP_UNVERIFIED, ErrorCategory, ErrorRecoverability, ErrorSeverity, } from '../errors/error.codes.js';
+/**
+ * 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) => {
+    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) => zoneArg.trim().toLowerCase().replace(/\.$/, '');
+const coversFqdn = (zone, fqdn) => 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, authorityZones) => {
+    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) => {
+    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 = [];
+    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, operation) => `${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 {
+    ownership;
+    constructor(ownership, operation, component, context = {}) {
+        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;
+    }
+    createWithContext(context) {
+        return new DomainOwnershipError(this.ownership, this.context.operation || 'operation', this.context.component || 'domain-ownership', context);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZG9tYWluLW93bmVyc2hpcC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3RzL2Rucy9kb21haW4tb3duZXJzaGlwLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxhQUFhLEVBQXNCLE1BQU0sMEJBQTBCLENBQUM7QUFDN0UsT0FBTyxFQUNMLCtCQUErQixFQUMvQixhQUFhLEVBQ2IsbUJBQW1CLEVBQ25CLGFBQWEsR0FDZCxNQUFNLDBCQUEwQixDQUFDO0FBNkVsQzs7Ozs7Ozs7Ozs7R0FXRztBQUNILE1BQU0sQ0FBQyxNQUFNLDBCQUEwQixHQUFHLENBQUMsV0FBbUIsRUFBc0IsRUFBRTtJQUNwRixNQUFNLFFBQVEsR0FBRyxXQUFXO1NBQ3pCLElBQUksRUFBRTtTQUNOLFdBQVcsRUFBRTtTQUNiLE9BQU8sQ0FBQyxLQUFLLEVBQUUsRUFBRSxDQUFDO1NBQ2xCLE9BQU8sQ0FBQyxRQUFRLEVBQUUsRUFBRSxDQUFDLENBQUM7SUFDekIsSUFBSSxDQUFDLFFBQVEsSUFBSSxRQUFRLENBQUMsTUFBTSxHQUFHLEdBQUc7UUFBRSxPQUFPLFNBQVMsQ0FBQztJQUN6RCxJQUFJLFFBQVEsQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLElBQUksUUFBUSxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQUMsSUFBSSxRQUFRLENBQUMsUUFBUSxDQUFDLEdBQUcsQ0FBQztRQUFFLE9BQU8sU0FBUyxDQUFDO0lBQ2pHLE1BQU0sTUFBTSxHQUFHLFFBQVEsQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLENBQUM7SUFDbkMsSUFBSSxNQUFNLENBQUMsTUFBTSxHQUFHLENBQUM7UUFBRSxPQUFPLFNBQVMsQ0FBQztJQUN4QyxJQUFJLE1BQU0sQ0FBQyxJQUFJLENBQUMsQ0FBQyxRQUFRLEVBQUUsRUFBRSxDQUFDLENBQUMsUUFBUSxJQUFJLFFBQVEsQ0FBQyxNQUFNLEdBQUcsRUFBRTtXQUMxRCxDQUFDLG1DQUFtQyxDQUFDLElBQUks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

package/dist_ts/dns/index.d.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';

package/dist_ts/dns/index.js

@@ -1,6 +1,8 @@
 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';
 export * from './txt-record-presentation.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9kbnMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsaUNBQWlDLENBQUM7QUFDaEQsY0FBYywyQ0FBMkMsQ0FBQztBQUMxRCxjQUFjLDhCQUE4QixDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9kbnMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsNEJBQTRCLENBQUM7QUFDM0MsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLGlDQUFpQyxDQUFDO0FBQ2hELGNBQWMsMkNBQTJDLENBQUM7QUFDMUQsY0FBYyw4QkFBOEIsQ0FBQyJ9

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

@@ -0,0 +1,143 @@
+import type { IDnsAuthorityDrift, IDnsAuthoritySettings, IDnsDelegationProbe, TDnsAuthorityState } from '../../dist_ts_interfaces/data/dns-authority.js';
+/**
+ * Result of applying an authority change to the running process.
+ * Reconciliation is all-or-nothing: a partial application is rolled back.
+ */
+export interface IDnsAuthorityMutationResult {
+    success: boolean;
+    message?: string;
+    probe?: IDnsDelegationProbe;
+    settings?: IDnsAuthoritySettings;
+}
+/** Re-derives runtime state after the effective authority set changed. */
+export type TDnsAuthorityReconciler = (reasonArg: string) => Promise<void>;
+/**
+ * DnsAuthorityManager — owns which zones dcrouter may answer for
+ * authoritatively, and proves that claim rather than accepting it.
+ *
+ * Why this exists: `dnsScopes` was the last un-migrated bootstrap option in an
+ * otherwise DB-driven router. It was read once at startup and had no mutation
+ * path, so claiming a newly delegated zone required a restart — measured at
+ * 30–60 s of total public outage. But simply making the declared list editable
+ * through the ops API would have been worse than the disease: the domain
+ * ownership predicate accepts zone coverage as *proof* precisely because a
+ * caller cannot write it. A `setDnsScopes` mutation would let an operator append
+ * any domain and manufacture that proof — the identical self-assertion vector
+ * that `createDcrouterDomain` used to have.
+ *
+ * So a zone earns authority by delegation instead: its public NS records must
+ * name our `dnsNsDomains`. An ops-API caller cannot fake that without actually
+ * controlling the domain, so the proof stays unforgeable while becoming
+ * mutable at runtime. It is also the comparison that was missing — claimed
+ * authority versus real delegation, checked by the mechanism itself rather than
+ * by an audit bolted on afterwards.
+ *
+ * **There is exactly one source of authority: this database document.** An
+ * earlier revision kept bootstrap `dnsScopes` as an always-in-effect floor and
+ * unioned it with the verified set. That is gone. A floor is a second
+ * representation of the same fact, it can only be changed by a redeploy, and it
+ * cannot be revoked through the API — all three of which are the properties
+ * that produced the outage this path exists to prevent.
+ *
+ * Removing the floor makes the *unreadable database* case load-bearing, so it is
+ * handled explicitly rather than by accident. Three situations, three answers:
+ *
+ *  - **document missing** — a readable database that has never been seeded. The
+ *    authority set is known, and it is empty: claim nothing. Logged at `error`
+ *    with the remediation, and the startup drift audit enumerates every zone
+ *    delegated to us that we are refusing to serve, which is the worklist.
+ *  - **document present, no zones** — identical handling, different message:
+ *    somebody revoked everything, which is a legitimate state we must not
+ *    silently repopulate.
+ *  - **document unreadable** — the authority set is *unknown*. `start()` throws
+ *    rather than reporting an empty set, because rendering an unknown as "claim
+ *    nothing" is exactly how a transient database fault would take every zone
+ *    off the air. `DnsServerRuntime.setup()` then refuses to start on
+ *    `getState() === 'unavailable'`. That second check is not redundant:
+ *    `DnsServer.dependsOn('DnsManager')` only *orders* startup, and taskbuffer
+ *    starts later levels even when an earlier optional service failed, so the
+ *    consumer has to read the state itself. Both services stay failed and
+ *    dcrouter runs degraded until it is restarted with a readable database —
+ *    DNS down and visibly failed, rather than up and asserting nothing.
+ *
+ * Fail closed on authority, never silently on service: with an empty set the
+ * DNS server still starts, still serves DoH, and still picks zones up the moment
+ * one is verified — without a restart.
+ */
+export declare class DnsAuthorityManager {
+    private getExpectedNameservers;
+    private verifiedZones;
+    private updatedAt;
+    private updatedBy;
+    private state;
+    private reconciler?;
+    constructor(getExpectedNameservers: () => string[]);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Wire the callback that re-derives runtime state (zone handlers, route
+     * certificate warnings, private-route overlay) after the effective set changes.
+     */
+    setReconciler(reconciler?: TDnsAuthorityReconciler): void;
+    /**
+     * The authority set: delegation-verified zones, sorted so every consumer that
+     * needs a stable "first zone" (the DNSSEC signing zone, for one) gets the same
+     * answer across restarts regardless of database insertion order.
+     *
+     * This is what the ownership predicate consumes, and it is the only input to
+     * it. There is no bootstrap contribution.
+     */
+    getEffectiveZoneNames(): string[];
+    /** Whether the stored authority set was readable when it was last loaded. */
+    getState(): TDnsAuthorityState;
+    getSettings(): IDnsAuthoritySettings;
+    /**
+     * Ask the public DNS whether `zone` is delegated to our nameservers.
+     *
+     * Deliberately uses `strategy: 'doh'` — a single DNS-over-HTTPS attempt
+     * against a public resolver, with no system-resolver fallback. smartdns'
+     * `getNameServers()` uses `dns.resolveNs`, i.e. the *system* resolver, which on
+     * a dcrouter host may be dcrouter itself: it would happily answer with the very
+     * NS records we generated, making the probe self-confirming. An independent
+     * vantage point is the whole point of the proof.
+     *
+     * The three verdicts are kept distinct on purpose. A timeout is not evidence
+     * that a zone is not ours; collapsing 'undeterminable' into 'not-delegated'
+     * would let a transient resolver fault revoke authority.
+     */
+    probeDelegation(zoneArg: string): Promise<IDnsDelegationProbe>;
+    /**
+     * Claim authority over a zone, but only against a positive delegation proof.
+     * An undeterminable probe refuses the mutation — never assume either way.
+     */
+    verifyZone(zoneArg: string, verifiedBy: string): Promise<IDnsAuthorityMutationResult>;
+    /**
+     * Drop a verified zone. Every zone is revocable — there is no undroppable
+     * deployment-declared floor any more, so withdrawing authority never needs a
+     * redeploy and never leaves the router asserting a claim it cannot retract.
+     */
+    revokeZone(zoneArg: string, updatedBy: string): Promise<IDnsAuthorityMutationResult>;
+    /**
+     * Persist a new zone set and reconcile the running process against it.
+     *
+     * Fail closed: if reconciliation throws, the previous set is restored in the
+     * database and re-reconciled, so the router is never left half-converted.
+     * Reconciliation is idempotent, which is what makes the rollback safe.
+     */
+    private applyZones;
+    private persist;
+    /**
+     * Compare claimed authority against what is actually true, in every direction.
+     *
+     * This is the check whose absence let one zone sit declared in `dnsScopes`
+     * while four live zones were delegated to our nameservers and unclaimed.
+     *
+     * Advisory by design. It never mutates the authority set: a resolver blip at
+     * startup must not revoke authority for every zone and convert a transient
+     * fault into the outage this whole path exists to avoid. Undeterminable probes
+     * are skipped rather than reported as drift.
+     */
+    auditDelegationDrift(): Promise<IDnsAuthorityDrift[]>;
+    /** Run the audit and log every finding at `error`. Never throws. */
+    logDelegationDrift(): Promise<void>;
+}