@serve.zone/dcrouter 17.10.2 → 18.0.1

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/dcrouter',
-    version: '17.10.2',
+    version: '18.0.1',
     description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxzQkFBc0I7SUFDNUIsT0FBTyxFQUFFLFNBQVM7SUFDbEIsV0FBVyxFQUFFLDBFQUEwRTtDQUN4RixDQUFBIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxzQkFBc0I7SUFDNUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLDBFQUEwRTtDQUN4RixDQUFBIn0=

package/dist_ts/acme/acme-failure-classification.d.ts

@@ -0,0 +1,64 @@
+import { PlatformError, type IErrorContext } from '../errors/base.errors.js';
+/**
+ * ACME failure classification.
+ *
+ * dcrouter has two independent ACME retry budgets, and neither used to look at
+ * *why* a failure happened:
+ *
+ *  1. `SmartAcmeLifecycle` — SmartAcme provider startup. 5 s→1 h exponential
+ *     backoff with jitter, hard cap of 20 attempts, then permanent give-up.
+ *     Only a SmartProxy rebuild or a process restart re-arms it.
+ *  2. `CertProvisionScheduler` — per-domain certificate provisioning.
+ *     `min(failures², 24 h)` backoff, **no cap**, re-armed by time forever.
+ *     This is the budget that reached 31–45 failures on the broken domains.
+ *
+ * Retrying is correct for rate limits, DNS propagation and transport faults. It
+ * is never correct for a configuration cause: a hostname with no managed domain
+ * cannot acquire one by waiting, so every one of those attempts was a silent
+ * no-op that also kept the real reason out of the operator's view. Permanent
+ * causes must therefore skip the budget entirely and surface attributably.
+ *
+ * Unclassified causes stay transient on purpose. Guessing "permanent" would
+ * strand recoverable domains, so the default preserves existing retry behaviour;
+ * only causes we can positively recognise are treated as terminal.
+ */
+export type TAcmeFailureReason = 
+/** Ownership of the hostname could not be proven (no DomainDoc / no provider zone / not delegation-verified). */
+'domain-ownership-unverified'
+/** The DNS-01 dispatcher found no managed zone able to hold the challenge record. */
+ | 'no-managed-dns-zone'
+/** No challenge handler / provider is wired for this domain at all. */
+ | 'no-challenge-handler'
+/** The ACME account itself is misconfigured (email, terms, key, directory URL). */
+ | 'acme-account-configuration'
+/** CAA forbids our issuer — only the domain holder can change this. */
+ | 'caa-forbids-issuance'
+/** ACME server rate limit — retrying is exactly right. */
+ | 'rate-limited'
+/** Challenge not yet visible, propagation delay, transport fault. */
+ | 'transient'
+/** Nothing recognised. Treated as transient so recoverable causes keep retrying. */
+ | 'unclassified';
+export interface IAcmeFailureClassification {
+    reason: TAcmeFailureReason;
+    /** True when no retry can resolve the cause, so the retry budget must not be consumed. */
+    permanent: boolean;
+    message: string;
+}
+/**
+ * Classify an ACME/provisioning failure into a retryable or terminal cause.
+ * Structured errors win over text matching: a `DomainOwnershipError` and any
+ * NON_RECOVERABLE CONFIGURATION `PlatformError` are permanent by declaration.
+ */
+export declare const classifyAcmeFailure: (errorArg: unknown) => IAcmeFailureClassification;
+/**
+ * Terminal ACME failure. HIGH severity so the automatic PlatformError log lands
+ * at `error` rather than being lost in provisioning warn noise, and
+ * NON_RECOVERABLE so `isRetryable()` and every downstream retry layer agree that
+ * this must not be retried.
+ */
+export declare class AcmePermanentFailureError extends PlatformError {
+    readonly classification: IAcmeFailureClassification;
+    constructor(classification: IAcmeFailureClassification, operation: string, component: string, context?: IErrorContext);
+    protected createWithContext(context: IErrorContext): PlatformError;
+}

package/dist_ts/acme/acme-failure-classification.js

@@ -0,0 +1,114 @@
+import { PlatformError } from '../errors/base.errors.js';
+import { DCR_ACME_PERMANENT_FAILURE, ErrorCategory, ErrorRecoverability, ErrorSeverity, } from '../errors/error.codes.js';
+import { DomainOwnershipError } from '../dns/domain-ownership.js';
+/**
+ * Ordered most-specific-first. Each pattern must only match text that uniquely
+ * identifies the cause — a false "permanent" verdict silently stops legitimate
+ * retries, which is a worse failure than an extra retry.
+ */
+const reasonPatterns = [
+    {
+        // Thrown by DnsManager.buildAcmeConvenientDnsProvider() when no DomainDoc covers the FQDN.
+        reason: 'no-managed-dns-zone',
+        permanent: true,
+        patterns: [
+            /no managed domain found for/i,
+            /add the domain in domains before issuing certificates/i,
+        ],
+    },
+    {
+        reason: 'no-challenge-handler',
+        permanent: true,
+        patterns: [
+            /no (?:challenge )?handler (?:found |available )?for/i,
+            /no dns-01 (?:handler|provider)/i,
+            /domain is not supported by any challenge handler/i,
+        ],
+    },
+    {
+        reason: 'caa-forbids-issuance',
+        permanent: true,
+        patterns: [
+            /caa record(?:s)? (?:for [^\s]+ )?(?:prevent|forbid|do not allow)/i,
+            /urn:ietf:params:acme:error:caa/i,
+        ],
+    },
+    {
+        reason: 'acme-account-configuration',
+        permanent: true,
+        patterns: [
+            /urn:ietf:params:acme:error:invalidemail/i,
+            /urn:ietf:params:acme:error:accountdoesnotexist/i,
+            /urn:ietf:params:acme:error:unsupportedcontact/i,
+            /must agree to (?:the )?terms of service/i,
+            /accountemail is required/i,
+        ],
+    },
+    {
+        reason: 'rate-limited',
+        permanent: false,
+        patterns: [
+            /urn:ietf:params:acme:error:ratelimited/i,
+            /too many (?:certificates|requests|failed authorizations)/i,
+            /rate ?limit/i,
+        ],
+    },
+];
+const extractMessage = (errorArg) => {
+    if (errorArg instanceof Error)
+        return errorArg.message;
+    if (typeof errorArg === 'string')
+        return errorArg;
+    if (errorArg && typeof errorArg === 'object' && 'message' in errorArg) {
+        return String(errorArg.message);
+    }
+    return String(errorArg);
+};
+/**
+ * Classify an ACME/provisioning failure into a retryable or terminal cause.
+ * Structured errors win over text matching: a `DomainOwnershipError` and any
+ * NON_RECOVERABLE CONFIGURATION `PlatformError` are permanent by declaration.
+ */
+export const classifyAcmeFailure = (errorArg) => {
+    const message = extractMessage(errorArg);
+    if (errorArg instanceof DomainOwnershipError) {
+        return { reason: 'domain-ownership-unverified', permanent: true, message };
+    }
+    if (errorArg instanceof PlatformError
+        && errorArg.category === ErrorCategory.CONFIGURATION
+        && errorArg.recoverability === ErrorRecoverability.NON_RECOVERABLE) {
+        return { reason: 'acme-account-configuration', permanent: true, message };
+    }
+    for (const candidate of reasonPatterns) {
+        if (candidate.patterns.some((pattern) => pattern.test(message))) {
+            return { reason: candidate.reason, permanent: candidate.permanent, message };
+        }
+    }
+    return { reason: 'unclassified', permanent: false, message };
+};
+/**
+ * Terminal ACME failure. HIGH severity so the automatic PlatformError log lands
+ * at `error` rather than being lost in provisioning warn noise, and
+ * NON_RECOVERABLE so `isRetryable()` and every downstream retry layer agree that
+ * this must not be retried.
+ */
+export class AcmePermanentFailureError extends PlatformError {
+    classification;
+    constructor(classification, operation, component, context = {}) {
+        super(`${operation} failed permanently (${classification.reason}): ${classification.message}`, DCR_ACME_PERMANENT_FAILURE, ErrorSeverity.HIGH, ErrorCategory.CONFIGURATION, ErrorRecoverability.NON_RECOVERABLE, {
+            component,
+            operation,
+            userMessage: `${operation} cannot succeed until its configuration is fixed (${classification.reason}): ${classification.message}`,
+            ...context,
+            data: {
+                acmeFailureReason: classification.reason,
+                ...context.data,
+            },
+        });
+        this.classification = classification;
+    }
+    createWithContext(context) {
+        return new AcmePermanentFailureError(this.classification, this.context.operation || 'operation', this.context.component || 'acme', context);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWNtZS1mYWlsdXJlLWNsYXNzaWZpY2F0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvYWNtZS9hY21lLWZhaWx1cmUtY2xhc3NpZmljYXRpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLGFBQWEsRUFBc0IsTUFBTSwwQkFBMEIsQ0FBQztBQUM3RSxPQUFPLEVBQ0wsMEJBQTBCLEVBQzFCLGFBQWEsRUFDYixtQkFBbUIsRUFDbkIsYUFBYSxHQUNkLE1BQU0sMEJBQTBCLENBQUM7QUFDbEMsT0FBTyxFQUFFLG9CQUFvQixFQUFFLE1BQU0sNEJBQTRCLENBQUM7QUF5RGxFOzs7O0dBSUc7QUFDSCxNQUFNLGNBQWMsR0FBcUI7SUFDdkM7UUFDRSwyRkFBMkY7UUFDM0YsTUFBTSxFQUFFLHFCQUFxQjtRQUM3QixTQUFTLEVBQUUsSUFBSTtRQUNmLFFBQVEsRUFBRTtZQUNSLDhCQUE4QjtZQUM5Qix3REFBd0Q7U0FDekQ7S0FDRjtJQUNEO1FBQ0UsTUFBTSxFQUFFLHNCQUFzQjtRQUM5QixTQUFTLEVBQUUsSUFBSTtRQUNmLFFBQVEsRUFBRTtZQUNSLHNEQUFzRDtZQUN0RCxpQ0FBaUM7WUFDakMsbURBQW1EO1NBQ3BEO0tBQ0Y7SUFDRDtRQUNFLE1BQU0sRUFBRSxzQkFBc0I7UUFDOUIsU0FBUyxFQUFFLElBQUk7UUFDZixRQUFRLEVBQUU7WUFDUixtRUFBbUU7WUFDbkUsaUNBQWlDO1NBQ2xDO0tBQ0Y7SUFDRDtRQUNFLE1BQU0sRUFBRSw0QkFBNEI7UUFDcEMsU0FBUyxFQUFFLElBQUk7UUFDZixRQUFRLEVBQUU7WUFDUiwwQ0FBMEM7WUFDMUMsaURBQWlEO1lBQ2pELGdEQUFnRDtZQUNoRCwwQ0FBMEM7WUFDMUMsMkJBQTJCO1NBQzVCO0tBQ0Y7SUFDRDtRQUNFLE1BQU0sRUFBRSxjQUFjO1FBQ3RCLFNBQVMsRUFBRSxLQUFLO1FBQ2hCLFFBQVEsRUFBRTtZQUNSLHlDQUF5QztZQUN6Qywy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

package/dist_ts/acme/classes.smartacme-lifecycle.d.ts

@@ -1,9 +1,38 @@
 import type { DcRouter } from '../classes.dcrouter.js';
+import { type TAcmeFailureReason } from './acme-failure-classification.js';
+/** Terminal state of the SmartAcme provider startup budget. */
+export interface IAcmeStartFailure {
+    reason: TAcmeFailureReason;
+    /** True when no further retry can resolve the cause. */
+    permanent: boolean;
+    /** Attempts consumed when the budget ended. */
+    attempts: number;
+    message: string;
+    at: number;
+    /** What an operator has to do to re-arm startup. */
+    rearmedBy: string;
+}
+/** Attempts allowed for transient SmartAcme startup failures before giving up. */
+export declare const smartAcmeStartMaxAttempts = 20;
 /**
  * Background start/retry/stop lifecycle for the DcRouter-owned SmartAcme
  * instance. SmartAcme startup can hit ACME rate limits, so startup runs in
  * the background with generation-guarded exponential retry, and certificate
  * provisioning is re-triggered once DNS-01 becomes ready.
+ *
+ * Retry semantics, which are NOT shared with the per-domain
+ * `CertProvisionScheduler` budget:
+ *  - increments once per failed `smartAcme.start()`;
+ *  - 5 s → 1 h exponential backoff with ±20% jitter;
+ *  - capped at `smartAcmeStartMaxAttempts` transient attempts;
+ *  - reset by `startInBackground()`, `stop()`, and a successful start;
+ *  - re-armed only by `startInBackground()`, i.e. a SmartProxy rebuild, an
+ *    explicit `rearm()` after a configuration change, or a process restart.
+ *    Nothing re-arms it on a timer, so the terminal state is recorded in
+ *    `startFailure` and logged at `error` instead of scrolling past as a warning.
+ *
+ * A permanent cause never enters the backoff at all: retrying a misconfigured
+ * ACME account cannot fix it, and spending the budget on it hides the reason.
  */
 export declare class SmartAcmeLifecycle {
     private dcRouterRef;
@@ -11,12 +40,25 @@ export declare class SmartAcmeLifecycle {
     ready: boolean;
     /** Tracks whether the taskbuffer SmartAcme service is started, so SmartProxy rebuilds can re-kick startup. */
     serviceStarted: boolean;
+    /**
+     * Set when the startup budget ended — either immediately for a permanent cause
+     * or after the transient attempt cap. Cleared on every (re-)arm and on success.
+     */
+    startFailure?: IAcmeStartFailure;
     private startGeneration;
     private startPromise?;
     private retryTimer?;
     private retryAttempt;
     constructor(dcRouterRef: DcRouter);
     startInBackground(): void;
+    /**
+     * Re-arm startup after a configuration change that can plausibly fix a
+     * previously terminal cause (e.g. the ACME account settings were corrected).
+     * Without this, an exhausted or permanently-failed budget could only be reset
+     * by a SmartProxy rebuild or a full restart — and a dcrouter restart is a
+     * measured 30–60 s of total public outage.
+     */
+    rearm(reasonArg: string): boolean;
     stop(): Promise<void>;
     private scheduleStart;
     private runStartAttempt;

package/dist_ts/acme/classes.smartacme-lifecycle.js

@@ -1,10 +1,27 @@
 import * as plugins from '../plugins.js';
 import { logger } from '../logger.js';
+import { AcmePermanentFailureError, classifyAcmeFailure, } from './acme-failure-classification.js';
+/** Attempts allowed for transient SmartAcme startup failures before giving up. */
+export const smartAcmeStartMaxAttempts = 20;
 /**
  * Background start/retry/stop lifecycle for the DcRouter-owned SmartAcme
  * instance. SmartAcme startup can hit ACME rate limits, so startup runs in
  * the background with generation-guarded exponential retry, and certificate
  * provisioning is re-triggered once DNS-01 becomes ready.
+ *
+ * Retry semantics, which are NOT shared with the per-domain
+ * `CertProvisionScheduler` budget:
+ *  - increments once per failed `smartAcme.start()`;
+ *  - 5 s → 1 h exponential backoff with ±20% jitter;
+ *  - capped at `smartAcmeStartMaxAttempts` transient attempts;
+ *  - reset by `startInBackground()`, `stop()`, and a successful start;
+ *  - re-armed only by `startInBackground()`, i.e. a SmartProxy rebuild, an
+ *    explicit `rearm()` after a configuration change, or a process restart.
+ *    Nothing re-arms it on a timer, so the terminal state is recorded in
+ *    `startFailure` and logged at `error` instead of scrolling past as a warning.
+ *
+ * A permanent cause never enters the backoff at all: retrying a misconfigured
+ * ACME account cannot fix it, and spending the budget on it hides the reason.
  */
 export class SmartAcmeLifecycle {
     dcRouterRef;
@@ -12,6 +29,11 @@ export class SmartAcmeLifecycle {
     ready = false;
     /** Tracks whether the taskbuffer SmartAcme service is started, so SmartProxy rebuilds can re-kick startup. */
     serviceStarted = false;
+    /**
+     * Set when the startup budget ended — either immediately for a permanent cause
+     * or after the transient attempt cap. Cleared on every (re-)arm and on success.
+     */
+    startFailure;
     startGeneration = 0;
     startPromise;
     retryTimer;
@@ -27,13 +49,33 @@ export class SmartAcmeLifecycle {
         const generation = ++this.startGeneration;
         this.ready = false;
         this.retryAttempt = 0;
+        this.startFailure = undefined;
         this.clearRetryTimer();
         this.scheduleStart(generation, 0);
     }
+    /**
+     * Re-arm startup after a configuration change that can plausibly fix a
+     * previously terminal cause (e.g. the ACME account settings were corrected).
+     * Without this, an exhausted or permanently-failed budget could only be reset
+     * by a SmartProxy rebuild or a full restart — and a dcrouter restart is a
+     * measured 30–60 s of total public outage.
+     */
+    rearm(reasonArg) {
+        if (!this.dcRouterRef.smartAcme || !this.serviceStarted) {
+            return false;
+        }
+        if (this.ready && !this.startFailure) {
+            return false;
+        }
+        logger.log('info', `Re-arming SmartAcme DNS-01 provider startup: ${reasonArg}`);
+        this.startInBackground();
+        return true;
+    }
     async stop() {
         this.startGeneration++;
         this.ready = false;
         this.retryAttempt = 0;
+        this.startFailure = undefined;
         this.clearRetryTimer();
         const smartAcme = this.dcRouterRef.smartAcme;
         if (!smartAcme) {
@@ -82,6 +124,7 @@ export class SmartAcmeLifecycle {
             }
             this.ready = true;
             this.retryAttempt = 0;
+            this.startFailure = undefined;
             logger.log('info', 'SmartAcme DNS-01 provider is now ready');
             this.retriggerCertificateProvisioning();
         }
@@ -93,9 +136,37 @@ export class SmartAcmeLifecycle {
             await smartAcme.stop().catch((stopErr) => {
                 logger.log('warn', `Failed to clean up SmartAcme after startup failure: ${stopErr.message}`);
             });
+            // Classify before spending any of the budget: a permanent cause is not made
+            // truer by 20 more attempts, and every attempt spent on it is an hour in
+            // which nothing tells the operator what is actually wrong.
+            const classification = classifyAcmeFailure(err);
+            if (classification.permanent) {
+                this.startFailure = {
+                    reason: classification.reason,
+                    permanent: true,
+                    attempts: this.retryAttempt,
+                    message: classification.message,
+                    at: Date.now(),
+                    rearmedBy: 'fixing the ACME configuration (which calls rearm()), a SmartProxy rebuild, or a process restart',
+                };
+                // Constructing this logs at `error` with the code and category attached.
+                new AcmePermanentFailureError(classification, 'SmartAcme DNS-01 provider startup', 'smartacme-lifecycle', { data: { attempts: this.retryAttempt, rearmedBy: this.startFailure.rearmedBy } });
+                return;
+            }
             this.retryAttempt++;
-            if (this.retryAttempt > 20) {
-                logger.log('error', `SmartAcme DNS-01 provider failed after 20 startup attempts: ${err.message}`);
+            if (this.retryAttempt > smartAcmeStartMaxAttempts) {
+                this.startFailure = {
+                    reason: classification.reason,
+                    permanent: false,
+                    attempts: this.retryAttempt - 1,
+                    message: classification.message,
+                    at: Date.now(),
+                    rearmedBy: 'a SmartProxy rebuild, an explicit rearm() after a configuration change, or a process restart',
+                };
+                logger.log('error', `SmartAcme DNS-01 provider gave up after ${smartAcmeStartMaxAttempts} startup attempts `
+                    + `(${classification.reason}): ${classification.message}. `
+                    + 'Nothing re-arms this on a timer — DNS-01 stays unavailable and every affected route falls back to a '
+                    + `no-op http-01 path until ${this.startFailure.rearmedBy}.`, { acmeFailureReason: classification.reason, attempts: this.startFailure.attempts });
                 return;
             }
             const baseDelayMs = 5000;
@@ -103,7 +174,7 @@ export class SmartAcmeLifecycle {
             const delayMs = Math.min(baseDelayMs * Math.pow(2, this.retryAttempt - 1), maxDelayMs);
             const jitter = 0.8 + Math.random() * 0.4;
             const actualDelayMs = Math.floor(delayMs * jitter);
-            logger.log('warn', `SmartAcme DNS-01 provider startup failed: ${err.message}; retrying in ${actualDelayMs}ms (attempt ${this.retryAttempt}/20)`);
+            logger.log('warn', `SmartAcme DNS-01 provider startup failed: ${err.message}; retrying in ${actualDelayMs}ms (attempt ${this.retryAttempt}/${smartAcmeStartMaxAttempts})`);
             this.scheduleStart(generation, actualDelayMs);
         }
         finally {
@@ -141,4 +212,4 @@ export class SmartAcmeLifecycle {
         }
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5zbWFydGFjbWUtbGlmZWN5Y2xlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvYWNtZS9jbGFzc2VzLnNtYXJ0YWNtZS1saWZlY3ljbGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUM7QUFDekMsT0FBTyxFQUFFLE1BQU0sRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUd0Qzs7Ozs7R0FLRztBQUNILE1BQU0sT0FBTyxrQkFBa0I7SUFXVDtJQVZwQixpRUFBaUU7SUFDMUQsS0FBSyxHQUFHLEtBQUssQ0FBQztJQUNyQiw4R0FBOEc7SUFDdkcsY0FBYyxHQUFHLEtBQUssQ0FBQztJQUV0QixlQUFlLEdBQUcsQ0FBQyxDQUFDO0lBQ3BCLFlBQVksQ0FBaUI7SUFDN0IsVUFBVSxDQUFpQztJQUMzQyxZQUFZLEdBQUcsQ0FBQyxDQUFDO0lBRXpCLFlBQW9CLFdBQXFCO1FBQXJCLGdCQUFXLEdBQVgsV0FBVyxDQUFVO0lBQUcsQ0FBQztJQUV0QyxpQkFBaUI7UUFDdEIsSUFBSSxDQUFDLElBQUksQ0FBQyxXQUFXLENBQUMsU0FBUyxFQUFFLENBQUM7WUFDaEMsSUFBSSxDQUFDLEtBQUssR0FBRyxLQUFLLENBQUM7WUFDbkIsT0FBTztRQUNULENBQUM7UUFFRCxNQUFNLFVBQVUsR0FBRyxFQUFFLElBQUksQ0FBQyxlQUFlLENBQUM7UUFDMUMsSUFBSSxDQUFDLEtBQUssR0FBRyxLQUFLLENBQUM7UUFDbkIsSUFBSSxDQUFDLFlBQVksR0FBRyxDQUFDLENBQUM7UUFDdEIsSUFBSSxDQUFDLGVBQWUsRUFBRSxDQUFDO1FBQ3ZCLElBQUksQ0FBQyxhQUFhLENBQUMsVUFBVSxFQUFFLENBQUMsQ0FBQyxDQUFDO0lBQ3BDLENBQUM7SUFFTSxLQUFLLENBQUMsSUFBSTtRQUNmLElBQUksQ0FBQyxlQUFlLEVBQUUsQ0FBQztRQUN2QixJQUFJLENBQUMsS0FBSyxHQUFHLEtB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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5zbWFydGFjbWUtbGlmZWN5Y2xlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvYWNtZS9jbGFzc2VzLnNtYXJ0YWNtZS1saWZlY3ljbGUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUM7QUFDekMsT0FBTyxFQUFFLE1BQU0sRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUV0QyxPQUFPLEVBQ0wseUJBQXlCLEVBQ3pCLG1CQUFtQixHQUVwQixNQUFNLGtDQUFrQyxDQUFDO0FBZTFDLGtGQUFrRjtBQUNsRixNQUFNLENBQUMsTUFBTSx5QkFBeUIsR0FBRyxFQUFFLENBQUM7QUFFNUM7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FtQkc7QUFDSCxNQUFNLE9BQU8sa0JBQWtCO0lBZ0JUO0lBZnBCLGlFQUFpRTtJQUMxRCxLQUFLLEdBQUcsS0FBSyxDQUFDO0lBQ3JCLDhHQUE4RztJQUN2RyxjQUFjLEdBQUcsS0FBSyxDQUFDO0lBQzlCOzs7T0FHRztJQUNJLFlBQVksQ0FBcUI7SUFFaEMsZUFBZSxHQUFHLENBQUMsQ0FBQztJQUNwQixZQUFZLENBQWlCO0lBQzdCLFVBQVUsQ0FBaUM7SUFDM0MsWUFBWSxHQUFHLENBQUMsQ0FBQztJQUV6QixZQUFvQixXQUFxQjtRQUFyQixnQkFBVyxHQUFYLFdBQVcsQ0FBVTtJQUFHLENBQUM7SUFFdEMsaUJBQWlCO1FBQ3RCLElBQUksQ0FBQyxJQUFJLENBQUMsV0FBVyxDQUFDLFNBQVMsRUFBRSxDQUFDO1lBQ2hDLElBQUksQ0FBQyxLQUFLLEdBQUcsS0FBSyxDQUFDO1lBQ25CLE9BQU87UUFDVCxDQUFDO1FBRUQsTUFBTSxVQUFVLEdBQUcsRUFBRSxJQUFJLENBQUMsZUFBZSxDQUFDO1FBQzFDLElBQUksQ0FBQyxLQUFLLEdBQUcsS0FBSyxDQUFDO1FBQ25CLElBQUksQ0FBQyxZQUFZLEdBQUcsQ0FBQyxDQUFDO1FBQ3RCLElBQUks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

package/dist_ts/acme/index.d.ts

@@ -1,2 +1,3 @@
 export * from './manager.acme-config.js';
 export * from './classes.smartacme-lifecycle.js';
+export * from './acme-failure-classification.js';

package/dist_ts/acme/index.js

@@ -1,3 +1,4 @@
 export * from './manager.acme-config.js';
 export * from './classes.smartacme-lifecycle.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9hY21lL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyxrQ0FBa0MsQ0FBQyJ9
+export * from './acme-failure-classification.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9hY21lL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyxrQ0FBa0MsQ0FBQztBQUNqRCxjQUFjLGtDQUFrQyxDQUFDIn0=

package/dist_ts/classes.dcrouter.d.ts

@@ -12,6 +12,7 @@ import { RouteConfigManager, ApiTokenManager, GatewayClientManager, ReferenceRes
 import { SecurityPolicyManager, RoutePolicyAugmenter } from './security/index.js';
 import { type IHttp3Config } from './http3/index.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 { AcmeConfigManager } from './acme/manager.acme-config.js';
@@ -61,16 +62,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;
     /**
@@ -88,7 +87,7 @@ export interface IDcRouterOptions {
     publicIp?: string;
     /**
      * 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)
      */
@@ -246,6 +245,8 @@ export declare class DcRouter {
     referenceResolver?: ReferenceResolver;
     targetProfileManager?: TargetProfileManager;
     dnsManager?: DnsManager;
+    /** Owns which zones dcrouter may answer for authoritatively, and proves it. */
+    dnsAuthorityManager?: DnsAuthorityManager;
     gatewayRouteDnsReconciler?: GatewayRouteDnsReconciler;
     opsEventManager?: OpsEventManager;
     acmeConfigManager?: AcmeConfigManager;
@@ -373,6 +374,29 @@ export declare class DcRouter {
     /** Serialized edge mutation on the RemoteIngress hub (delegates to the hub lifecycle). */
     mutateRemoteIngressEdges<T>(mutation: (manager: RemoteIngressManager) => Promise<T>, syncAllowedEdges?: boolean): Promise<T>;
     updateRemoteIngressHubSettings(updates: TRemoteIngressHubSettingsUpdate, updatedBy: string): Promise<IRemoteIngressHubSettings>;
+    /**
+     * 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.
+     */
+    reconcileDnsAuthority(reasonArg: string): Promise<void>;
+    /**
+     * 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.
+     */
+    resyncPrivateRouteDnsOverlay(reasonArg: string): Promise<void>;
     /** Restart SmartProxy after RemoteIngress hub settings changed listener wiring. Called by RemoteIngressHubLifecycle. */
     restartSmartProxyForRemoteIngressSettings(): Promise<void>;
     /** Bootstrap routes the RemoteIngress hub uses to derive edge ports before the DB route set is applied. */