@serve.zone/dcrouter 17.10.2 → 18.0.0

package/readme.hints.md

@@ -1,5 +1,417 @@
 # Implementation Hints and Learnings
 
+## Derived state must name its invalidation trigger (2026-07-25)
+
+Three separate production failures on one day had the same shape: **state was
+mutated in one layer and the mirrored state in another layer was left behind.**
+
+1. `DomainDoc` deleted → the generated apex NS handler stayed registered in the
+   embedded smartdns server, still answering with the `aa` flag until dcrouter was
+   restarted, while record queries already answered REFUSED.
+2. A certificate was successfully re-issued and stored → SmartProxy's private
+   per-domain `certFailureAt` cooldown still gated the domain, so every route
+   reapply skipped it and the proxy kept serving the expired certificate. No
+   error, no log (the sweep returns before its summary line when every domain is
+   skipped).
+3. A null sentinel was translated for validation but persisted raw.
+
+### The rule
+
+> Every cache, negative cache, or derived registration must name, in code, the
+> mutation that invalidates it — and the invalidation must run inside the same
+> operation that mutates the source of truth.
+
+Corollaries, all of which are review-blocking:
+
+- A registration is torn down by the same operation that removes what it was
+  derived from. Track what you actually registered; do not recompute "would I
+  have registered this?" at teardown time. `DnsServer.unregisterHandler(pattern,
+  types)` removes **every** handler for that pattern/type pair, so a recomputed
+  guess can tear down another owner's records — or miss its own when the inputs
+  have drifted. `DnsManager.runtimeRegistrations` is the pattern: a per-domain
+  registry of `name|type` keys, each tagged `persisted` or `generated-default`,
+  torn down by `tearDownDomainRuntimeRegistrations(domainId)`.
+- A negative cache is invalidated by the event that **resolves its cause**, not
+  only by elapsed time. Time-only expiry plus a skip-while-cooling-down rule is a
+  deadlock: the sweep that would clear the entry is the sweep the entry blocks.
+- **Issued is not served.** An operation that advances one layer must verify the
+  layer that actually serves traffic before reporting success. The certificate
+  overview reports `expiryDate` (issued/stored) and `served` (what the Rust engine
+  presents) separately and downgrades the combined `status` to `failed` with
+  `servedMismatch` when they disagree; `reprovisionCertificateDomain` refuses to
+  return success while the engine still serves an invalid certificate.
+- If the layer that owns the derived state exposes no invalidation API, that is
+  the defect. A periodic sweep that blindly clears caches, or a shortened TTL, is
+  a workaround that hides it — fix the owning layer. Reaching into another
+  package's private state (e.g. `smartProxy.bridge`) is an internal bypass and
+  must not ship.
+
+### Known open instance (needs an upstream change)
+
+`@push.rocks/smartproxy` (27.20.0) keeps `certValidity` and `certFailureAt` as
+**private** in-memory maps and exposes no per-domain invalidation. The only two
+public methods that look relevant, `provisionCertificate(routeName)` and
+`renewCertificate(routeName)`, both go through the Rust ACME bridge, which
+SmartProxy force-disables whenever `certProvisionFunction` is set — so a consumer
+using `certProvisionFunction` has no supported way to clear the cooldown or
+hot-load a certificate for one domain. Smallest correct upstream addition:
+`invalidateCertProvisionCooldown(domain: string): boolean` (plus, ideally, a
+`'skip'` member of `TSmartProxyCertProvisionObject` so a consumer can decline an
+attempt without SmartProxy recording it as a failure and re-arming the cooldown).
+Until that ships, the only operator remedy is toggling the single affected route
+off and on; a dcrouter restart costs 30–60 s of total public outage.
+
+## DNS authority is proven by delegation, not declared (2026-07-25)
+
+`dnsScopes` was the last un-migrated bootstrap option in an otherwise DB-driven
+router: read once from the OCI container config at startup, with no mutation
+path, no watcher, no reload. Claiming a newly delegated zone therefore required a
+restart — 30–60 s of total public outage.
+
+**The fix is not a `setDnsScopes` mutation.** The domain-ownership predicate
+accepts scope coverage as *proof* precisely because only a deploy can change it.
+An editable declared list is self-assertion, and would have re-opened the exact
+hole that `createDcrouterDomain` had. Instead a zone earns authority by its
+**public delegation naming our `dnsNsDomains`** — unforgeable through the ops API,
+because you cannot repoint a domain's NS records without controlling the domain.
+That is also the comparison that was missing: declared authority versus real
+delegation, made the mechanism rather than an audit bolted on afterwards.
+
+- `ts_interfaces/data/dns-authority.ts` — the contract.
+- `ts/db/documents/classes.dns-authority.doc.ts` — singleton doc holding only
+  *verified* zones, following the `AcmeConfigDoc` pattern.
+- `ts/dns/manager.dns-authority.ts` — probe, mutations, drift audit.
+- `ts/opsserver/handlers/dns-authority.handler.ts` — `dns-authority:read` /
+  `dns-authority:write`, admin identity required on write.
+
+**Precedence: there is none, because there is one source.** `dnsScopes` is gone
+— the option, the `DCROUTER_DNS_SCOPES` env override, and the bootstrap floor it
+contributed. The authority set is the delegation-verified zones in the database
+and nothing else.
+
+The union it replaced was a floor: always in effect, changeable only by a
+redeploy, and **not revocable through the API**. Those are the same three
+properties that produced the outage this path exists to prevent, so keeping them
+as a safety net kept the disease as the cure.
+
+Removing the floor makes the *unreadable database* case load-bearing, which is
+what the original union was really defending against. The defence was right; the
+mechanism was not. Three situations, three answers — and the whole point is that
+they are three, not two:
+
+| Situation | Authority set | Behaviour |
+| --- | --- | --- |
+| document missing | known-empty | claim nothing, log at `error`, DNS server still starts |
+| document present, zero zones | known-empty | same, different message — somebody revoked everything, and that is an instruction |
+| document unreadable | **unknown** | `start()` throws; `DnsServer` depends on `DnsManager`, so it does not come up claiming nothing |
+
+Rendering an unknown as "claim nothing" is precisely how a transient database
+fault would take every zone off the air. Fail closed on *authority*; never
+silently on *service*. With an empty set the DNS server still binds :53, still
+serves DoH, still runs the private-route overlay, and picks a zone up the moment
+it is verified — REFUSED is a fast, honest "not ours", where an unbound port is
+a timeout.
+
+**The probe must not use the system resolver.** `smartdns.getNameServers()` calls
+`dns.resolveNs`, i.e. the system resolver, which on a dcrouter host may be
+dcrouter itself — it would answer with the very NS records we generated, making
+the probe self-confirming. Use
+`new plugins.smartdns.dnsClientMod.Smartdns({ strategy: 'doh', allowDohFallback: false })`
+and `queryRecords(zone, 'NS')`: one DNS-over-HTTPS attempt against a public
+resolver, no system fallback.
+
+**Three verdicts, never two.** `delegated` / `not-delegated` / `undeterminable`.
+A timeout is not evidence that a zone is not ours. A mutation refuses on
+`undeterminable` (never assume either way); the startup drift audit *skips* it.
+
+**The drift audit is advisory and never mutates.** It reports three directions —
+`delegated-but-unclaimed` (a live zone we could serve but do not),
+`claimed-but-not-delegated` (authority we still assert after delegation moved
+away), and `verified-but-unhosted` (authority with no `DomainDoc` behind it, so
+nothing is served for it at all). It must not revoke: a resolver blip at boot would otherwise take every
+zone off the air, which is the outage this path exists to avoid.
+
+### Deploy sequence — seeding is mandatory, not advisable
+
+Startup ordering is already correct: the service chain is `DcRouterDb` →
+`DnsManager` → `SmartProxy` → `DnsServer`, and `DnsAuthorityManager.start()`
+(which loads the stored verified zones) runs inside `DnsManager`'s `withStart`,
+strictly before `dnsServerRuntime.setup()` reads the set or registers any
+handler. So the stored set is applied on the **first** registration pass —
+restart itself introduces no reconciliation gap.
+
+**Seed before the first restart on this trio.** With `dnsScopes` gone there is no
+floor left to fall back on: a zone that is not in `DnsAuthorityDoc` when the new
+build starts is REFUSED outright, and that now includes the zone that used to be
+declared in `dnsScopes` and was the only healthy one. Insert the singleton
+`DnsAuthorityDoc` (`settingsId: 'dns-authority-settings'`) with one
+`{ zone, origin: 'verified', verifiedAt, observedNameservers, verifiedBy }`
+entry per delegated zone *before* starting the new build. The first startup then
+has proof already, and the startup drift audit re-probes each entry and reports
+any that no longer hold, so a wrong seed is self-correcting rather than silently
+trusted.
+
+The production database is an embedded single-writer `LocalSmartDb` reached over
+a Unix socket in `os.tmpdir()`, so it is not reachable off-host and the seed must
+run on the dcrouter host with dcrouter stopped: stop → seed → start the new
+build. `.nogit/debug/seed-dns-authority.ts` does this; it probes every zone over
+DoH first and writes nothing on an unproven zone, and it is re-runnable (it
+replaces the verified set with what it just proved, so dropping a zone from the
+list drops it from authority).
+
+That script lives under `.nogit/` and is therefore **not committed** — it is a
+one-off operational tool for this specific upgrade, not product code, and it is
+deliberately not a smartmigration step (see the next section for why). So it
+cannot be the only record of the step: the changelog spells out the document
+shape (`settingsId: 'dns-authority-settings'`, one
+`{ zone, origin: 'verified', verifiedAt, observedNameservers, verifiedBy }` per
+zone) inline, and the same result is reachable through `verifyDnsAuthorityZone`
+after startup with no restart. The script is a convenience, not a dependency.
+
+**If a zone was missed** — claim it after startup, no restart needed. Order:
+
+1. Confirm the manager loaded: `DnsAuthorityManager: N delegation-verified zone(s) loaded`.
+   An empty set logs at `error` instead, naming the remediation.
+2. Read the startup drift audit. Every `delegated-but-unclaimed` line is a zone
+   delegated to us that we are refusing to serve — that is the worklist.
+3. Per zone, `probeDnsAuthorityZone` first (read-only, no mutation), then
+   `verifyDnsAuthorityZone` only if the verdict is `delegated`.
+4. `getDnsAuthority` — expect one `verified` entry per claimed zone, each
+   carrying `observedNameservers`.
+5. `getDnsAuthorityDrift` — expect `[]`.
+6. Query each claimed zone's apex NS directly against our nameserver and expect an
+   authoritative answer naming `dnsNsDomains`. Query `AAAA` and `SOA` too, not
+   just `A`: a zone missing from `authoritativeZones` answers `A` and REFUSES the
+   rest, which is the defect this work fixes and the only query pattern that
+   distinguishes it.
+7. `getMergedRoutes` — expect no `unverified-domain-ownership` warnings.
+8. `getCertificateOverview` — expect no entry with `servedMismatch: true`.
+
+Healthy is: drift empty, every claimed zone answering `aa` for its apex NS, no
+ownership route warnings, no served/stored certificate mismatch.
+
+A `verdict: 'undeterminable'` means the host could not reach a public DoH
+resolver. That is an egress problem to fix, not something to retry blindly — and
+the zone stays unserved until it is resolved, which is the correct fail-closed
+behaviour.
+
+### `authoritativeZones` is reconciled on a running server
+
+An earlier revision recorded this as a known limitation: smartdns takes
+`authoritativeZones` in the `DnsServer` constructor, so a zone verified at
+runtime did not join it until the next restart, and it also meant the `DnsServer`
+service only registered when bootstrap `dnsScopes` was non-empty — a
+verified-only configuration never started the DNS server at all. Both are fixed.
+
+It was not a cosmetic limitation. **`authoritativeZones` decides the response
+kind, and it is the entire production defect.** smartdns answers a name inside a
+configured zone and REFUSES a name outside every configured zone — *even when a
+handler is registered and answers other qtypes for that exact name*. In
+production that produced, from `212.95.99.130`:
+
+```
+social.io    A=NOERROR (aa)  AAAA=REFUSED  SOA=REFUSED
+hard.global  A=NOERROR (aa)  AAAA=REFUSED  SOA=REFUSED
+central.eu   A=NOERROR (aa)  AAAA=NOERROR  SOA=NOERROR   <- the only declared zone
+```
+
+Public recursives turn the REFUSED arm into SERVFAIL — `AAAA social.io` SERVFAILs
+on 1.1.1.1, 8.8.8.8 and 9.9.9.9 — and `curl` does a dual A+AAAA lookup and blocks
+on it, so dual-stack clients see a degraded site. Registering handlers for a
+verified zone without moving this set would have reproduced the identical defect
+for every runtime-verified zone.
+
+**How it is reconciled without a restart.** `DnsServerRuntime` owns the array
+instance it passes as `authoritativeZones`. smartdns keeps the options object by
+reference and re-reads the array on every query, so `syncAuthorityZones()`
+mutates it in place and a live server changes its authority set. The alternative
+is re-creating the `DnsServer`, i.e. dropping UDP/TCP 53 — the outage this path
+exists to remove. `assertLiveAuthorityZones()` checks the reference is still
+shared right after construction and logs at `error` if it is not, so a future
+smartdns that copies the array fails loudly instead of silently freezing
+authority at boot; a test asserts the identity against the installed smartdns.
+
+`dnssecZone` cannot be reconciled the same way — it is baked into the Rust config
+at start — so it is taken from the boot-time set, which is **sorted** and
+therefore stable across restarts rather than dependent on database insertion
+order. When the set is empty it becomes `no-authority.invalid`: smartdns falls
+back to `[dnssecZone]` when `authoritativeZones` is empty, and `.invalid` is
+reserved by RFC 2606, so an unseeded database provably cannot claim a real name.
+
+### Why removing `dnsScopes` needs no smartmigration step
+
+`AGENTS.md` requires DB schema migrations to live exclusively in
+`ts_migrations/index.ts`. This change adds none, deliberately, and the reason is
+worth stating so its absence does not read as an oversight:
+
+- **Nothing in the database changes shape.** `DnsAuthorityDoc` is untouched. The
+  only type change is narrowing `TDnsAuthorityZoneOrigin` from
+  `'bootstrap' | 'verified'` to `'verified'`, and no stored document ever
+  carried `'bootstrap'` — `persist()` only ever wrote `verifiedZones`, and
+  `verifyZone()` is the only thing that builds an entry. The bootstrap entries
+  existed solely as a read-time projection inside `getSettings()`.
+  Stronger still: `DnsAuthorityDoc` was introduced in `0d82361`, after the newest
+  tag, so no released build has ever created the collection.
+- **Seeding from `dnsScopes` would forge the proof.** A migration step *could*
+  read it — `createMigrationRunner` runs in-process at startup and already takes
+  deployment-derived seeds — but a `dnsScopes` entry carries no delegation
+  evidence. Persisting one as `origin: 'verified'` would manufacture exactly the
+  proof this change makes unforgeable, and would reintroduce self-asserted
+  authority through the back door.
+
+The other candidate — derive authority by probing every dcrouter-hosted
+`DomainDoc` at upgrade time — was rejected because its outcome would depend on
+whether a public DoH resolver happened to be reachable at that moment, so the
+same upgrade would claim different zones on different runs, and a migration does
+not re-run to correct itself. Nondeterministic authority is worse than no
+automation.
+
+The upgrade path is instead **seed, then start** (above), backed by three
+independent loud signals if it is skipped: `DnsAuthorityManager.start()` logs at
+`error` on an empty set, `DnsServerRuntime.setup()` logs at `error`, and the
+startup drift audit enumerates precisely the zones to claim. Every one of them is
+remediable through `dns-authority:write` without a restart, which is the property
+that makes a missed seed recoverable rather than an outage.
+
+### Sequenced behind an unreleased smartdns
+
+Three items cannot be written against the installed smartdns (7.12.1) and must
+land in the same change that takes the bump. All are recorded at their code
+sites so they cannot be lost.
+
+1. **The private-route overlay must declare itself non-authoritative.** It
+   registers `*` for `A` (`registerPrivateRouteHandler`). The hardened smartdns
+   authority model *suppresses* a default-`authoritative` handler for any name
+   outside every configured zone, so overlay hostnames proven by `provider-zone`
+   — owned, but not delegation-verified, therefore not in `authoritativeZones` —
+   would silently stop being answered. It needs
+   `{ authority: 'non-authoritative', owner: 'private-route-overlay' }`, which
+   is a fourth `registerHandler` parameter that does not exist yet.
+
+2. **A supported way to re-zone a running server.** `DnsServerRuntime` currently
+   keeps the array it passed as `authoritativeZones` and mutates it in place,
+   then verifies through a cast that smartdns still holds the same reference.
+   That is a consumer-side shim on a dependency's storage behaviour, and it is
+   named as one: `authoritativeZones` is a public option, but "the array is kept
+   by reference and re-read per query" is not a documented contract. It is used
+   because the alternative — re-creating the `DnsServer` to change its zones —
+   drops UDP/TCP 53, which is the outage the whole path exists to remove, and
+   because a `setAuthoritativeZones()` cannot be added without releasing
+   smartdns first. Guarded two ways in the meantime:
+   `assertLiveAuthorityZones()` logs at `error` at startup if the reference is
+   no longer shared, and a test asserts the identity against the installed
+   smartdns so a copying release fails the suite rather than production. Replace
+   both with the supported setter when it ships.
+
+3. **Per-registration teardown.** `unregisterHandler(pattern, types)` is coarse:
+   two owners on the identical pattern and type cannot be separated. Nothing
+   does that today — `DnsManager` is the single owner of apex NS, and
+   `DnsServerRuntime`'s glue records use different patterns — but the registry
+   in `DnsManager` exists to work around exactly this. `unregisterHandlerById` /
+   `unregisterHandlersByOwner` and the handle returned by `registerHandler` are
+   the released fix.
+
+### Generated apex NS has exactly one owner
+
+`DnsServerRuntime` used to emit a static apex NS set per `dnsScopes` entry, and
+`DnsManager` skipped those zones to avoid duplicates. Under database-sourced
+authority that is wrong in both directions — a zone verified after startup would
+never get them, and a zone whose authority was revoked would keep them until an
+unrelated restart. `DnsManager.registerAuthoritativeZoneDefaults()` is now the
+only source, for every authoritative zone, reconciled in-process both ways.
+
+Consequence worth knowing: generated apex NS hangs off a dcrouter-hosted
+`DomainDoc`, so a verified zone without one serves nothing at all. That is
+reported as `verified-but-unhosted` drift, because it is otherwise invisible —
+such a zone neither REFUSES nor answers.
+
+## Domain ownership gates certificates and authoritative DNS (2026-07-25)
+
+`ts/dns/domain-ownership.ts` is the single predicate. Ownership is proven by
+exactly two things, neither forgeable through the ops API:
+
+- `provider-zone` — a `DomainDoc` with `source === 'provider'` and a `providerId`.
+  It can only get there via `importDomainsFromProvider()`, which requires the zone
+  to be listed by a credentialed provider account.
+- `delegation-verified-zone` — the FQDN is covered by a zone in the DNS authority
+  set (exact or a subzone). A zone only enters that set by having its public NS
+  records observed naming our nameservers, which an ops-API caller cannot
+  arrange. This replaced `configured-dns-scope`, which read `options.dnsScopes`:
+  deployment configuration was a real trust boundary, but the price was a second,
+  un-reconcilable representation of DNS authority.
+
+Everything else — including a `source === 'dcrouter'` `DomainDoc` outside the
+authority set — is operator self-assertion and fails closed.
+
+**`DomainDoc.authoritative` has been recording intent, not fact.** In production
+all four of `gated.one`, `hard.global`, `shoppinglist.app` and `social.io` carry
+`authoritative: true` with `providerId: no` — a flag nobody ever proved, written
+unconditionally by the old `createDcrouterDomain`. Do not read it as evidence of
+anything. The predicate ignores it and derives authority from proof, and
+`DnsManager.syncAuthoritativeFlags()` now rewrites the stored flag to match the
+current verdict whenever the authority set changes, so the column converges on
+the truth instead of preserving a stale claim.
+
+**Known gap — no persisted lifecycle state.** `DomainDoc.source` is only
+`dcrouter | provider` and `updateDomain` can change only `description`, so
+"we intend to manage this later" still cannot be represented distinctly from
+"we serve this authoritatively now"; the invariants above are enforced by
+recomputing ownership at every decision point instead. The recommended target is
+a four-state machine — `pending`/`unverified`, `active-provider`,
+`active-dcrouter`, `suspended`/`revoked` — with a generation-fenced
+`verifyDomain`/`activateDomain` that proves delegation against the configured
+public nameserver identities, `createDomain` entering `pending`, and
+`deactivateDomain` tearing down runtime state. Two properties to preserve when it
+lands: in `active-provider`, `authoritative` stays **false** and loss of provider
+proof must **suspend** writes rather than fall back to local authority; and
+synthetic NS/SOA is installed only after activation, never on intent. That work
+needs a persisted status field, a release-version-matched `ts_migrations` step,
+new ops API methods, and UI — it is a feature program, not a defect fix.
+
+Why this matters: **smartdns marks any answer a registered handler produces as
+authoritative (`aa`) regardless of `authoritativeZones`.** See
+`classes.dnsserver.js`: a handler hit sends `'answer'`, a miss inside an
+authoritative zone sends `'authoritativeNegative'`, and a miss outside sends
+`'refused'`. So registering *any* handler for a zone is a public claim of
+authority over it, and dcrouter listens on a public UDP/TCP 53.
+
+Enforcement points:
+
+- `RouteConfigManager.createRoute` / `updateRoute` — refuse an enabled route whose
+  `action.tls.certificate === 'auto'` covers an unverified hostname. Disabling is
+  never gated. Already-stored routes are **surfaced** as
+  `unverified-domain-ownership` route warnings plus an `error` log, not refused,
+  because refusing at startup would take down routes that are serving fine.
+- `DnsManager.registerAuthoritativeZoneDefaults` — refuse the generated apex NS
+  handler for an unverified zone; `createDcrouterDomain` / `migrateToDcrouter`
+  derive `authoritative` from the verdict instead of hard-coding `true`.
+- `DnsServerRuntime.syncPrivateRouteOverrides` — the private-route A overlay is
+  "internal" by intent only, never by mechanism. Ungated, one route was enough to
+  make dcrouter publicly hand out an RFC1918 address, authoritatively, for a
+  third party's domain.
+- `certProvisionFunction` and `reprovisionCertificateDomain` — refuse before
+  starting an ACME order that cannot succeed.
+
+## ACME retry budgets are three independent mechanisms (2026-07-25)
+
+Do not assume they share semantics, caps, or re-arm behaviour:
+
+| | `SmartAcmeLifecycle` | `CertProvisionScheduler` | SmartProxy `certFailureAt` |
+|---|---|---|---|
+| scope | provider startup | per domain | per domain |
+| increments on | failed `smartAcme.start()` | `certProvisionFunction` throw | `certProvisionFunction` throw |
+| backoff | 5 s→1 h, ±20% jitter | `min(failures², 24 h)` | flat 30 min |
+| cap | 20 attempts, then gives up | **none** — grows forever | n/a |
+| persisted | no | yes (`CertBackoffDoc`) | no (in-memory, private) |
+| re-armed by | `startInBackground()` only: a SmartProxy rebuild, `rearm()`, or a process restart. **Never on a timer.** | time | time, or a successful provision it cannot reach |
+
+`classifyAcmeFailure()` (`ts/acme/acme-failure-classification.ts`) decides which
+causes may enter a budget at all. A configuration cause (no managed domain, no
+provider zone, unverified ownership, bad ACME account, CAA) is terminal: it is
+raised as `AcmePermanentFailureError` / `DomainOwnershipError` and never consumes
+a budget. Unrecognised causes stay **transient** on purpose — guessing "permanent"
+would strand domains a retry would have fixed.
+
 ## smartmta Migration (2026-02-11)
 
 ### Overview

package/readme.md

@@ -25,7 +25,7 @@ Highlights:
 | --- | --- |
 | Proxying | SmartProxy routes for HTTP, HTTPS, TCP, SNI, TLS termination, passthrough, backend forwarding, source policies, rate limits, and browser challenges |
 | Route ownership | Constructor routes, generated email/DNS routes, and API-created routes with explicit origins |
-| DNS | Authoritative scopes, generated NS records, static DNS records, provider-backed domains, and DoH endpoints |
+| DNS | Delegation-verified authoritative zones, generated NS records, static DNS records, provider-backed domains, and DoH endpoints |
 | Email | UnifiedEmailServer startup, email-domain management, route-backed delivery actions, received mail operations, managed app address bindings, and outbound SMTP submission identities |
 | Certificates | ACME config, managed-domain DNS-01 challenges, HTTP-01 fallback, stored certificate metadata, provisioning backoff, and certificate status reporting |
 | Edge access | Remote ingress hub, edge registrations, derived edge ports, pushed firewall rules, VPN-only route access |
@@ -116,8 +116,7 @@ Bootstrap behavior:
 | `emailOutboundMode` | Outbound SMTP mode. Defaults to `direct`; `remoteIngress` routes outbound SMTP through a RemoteIngress egress edge. |
 | `emailPortConfig` | External-to-internal email port mapping and received-email storage path. |
 | `tls` | Legacy/static TLS and ACME contact settings used to seed certificate config. |
-| `dnsNsDomains` | Nameserver hostnames used for generated NS records and DoH routes. |
-| `dnsScopes` | Authoritative domains served by the embedded DNS server. |
+| `dnsNsDomains` | Nameserver hostnames used for generated NS records and DoH routes. A zone becomes authoritative by having its public NS records observed naming one of these. |
 | `dnsRecords` | Constructor-defined DNS records. |
 | `publicIp` / `proxyIps` | IPs used for generated A records and proxy-aware DNS exposure. |
 | `dbConfig` | Smartdata persistence via embedded LocalSmartDb or external MongoDB. |
@@ -130,7 +129,7 @@ Bootstrap behavior:
 Important runtime behavior:
 
 - `dbConfig.enabled` defaults to enabled. Without `mongoDbUrl`, dcrouter uses embedded LocalSmartDb.
-- If the DB is disabled, constructor-defined proxy traffic can still run, but persistent API routes, tokens, managed domains, and stored certificate state are unavailable.
+- If the DB is disabled, constructor-defined proxy traffic can still run, but persistent API routes, tokens, managed domains, and stored certificate state are unavailable. The embedded DNS server is also skipped entirely, because DNS authority is delegation-verified database state — the DoH routes are still generated, but nothing answers behind them.
 - Qualifying HTTPS forward routes on port `443` are HTTP/3-augmented unless `http3.enabled === false` or the route opts out.
 - DNS-over-HTTPS routes are generated on the first `dnsNsDomains` entry at `/dns-query` and `/resolve`.
 - Email listener ports can be remapped internally, for example public `25`, `587`, and `465` to unprivileged internal ports.
@@ -176,6 +175,47 @@ dcrouter keeps generated and operator-created routes separate so automation can
 
 System routes are persisted with stable `systemKey` values. Ordinary operator-created API routes are editable through generic route CRUD. Routes carrying managed ownership metadata, including Special Forwards and gateway-client routes, reject generic structural updates and deletion so their owning workflow keeps canonical match, priority, source-policy, and ownership fields intact.
 
+## DNS Authority
+
+Which zones the embedded DNS server may answer for authoritatively is database
+state, not deployment configuration. There is no `dnsScopes` option.
+
+A zone enters the authority set exactly one way: its **public delegation must
+name one of `dnsNsDomains`**, observed through a single DNS-over-HTTPS lookup
+against a public resolver. The system resolver is never used for this — on a
+dcrouter host it may be dcrouter itself, which would answer with the very NS
+records dcrouter generated and make the proof self-confirming. An ops-API caller
+cannot repoint somebody else's delegation, so writing the record is not the same
+as manufacturing the proof.
+
+| Operation | Scope | Effect |
+| --- | --- | --- |
+| `getDnsAuthority` | `dns-authority:read` | The authority set, its evidence, and whether it was readable. |
+| `probeDnsAuthorityZone` | `dns-authority:read` | Read-only delegation probe. Never mutates. |
+| `verifyDnsAuthorityZone` | `dns-authority:write` | Claims a zone, only against a `delegated` verdict. |
+| `revokeDnsAuthorityZone` | `dns-authority:write` | Drops a zone. Every zone is revocable. |
+| `getDnsAuthorityDrift` | `dns-authority:read` | Advisory comparison of claimed authority against reality. |
+
+Writes accept an admin identity or an API token carrying `dns-authority:write`;
+a non-admin identity is refused. Probes return three verdicts, never two: `delegated`, `not-delegated`, and
+`undeterminable`. A timeout is not evidence that a zone is not ours, so a
+mutation refuses on `undeterminable` rather than assuming either way.
+
+Claiming or revoking a zone takes effect in-process, with no restart: it moves
+the running DNS server's authoritative zone set, its generated apex NS records,
+route certificate warnings, and the private-route overlay together.
+
+**Cold start.** A database with no authority document is a legitimate state, and
+it means dcrouter is authoritative for nothing and REFUSES every query. The DNS
+server still starts — so DoH keeps serving and a zone verified a moment later
+takes effect immediately — and the condition is logged at `error` alongside a
+startup drift audit listing every dcrouter-hosted zone delegated to us that is
+not being served.
+An authority document that cannot be *read* is treated differently: the set is
+unknown rather than empty, so the DNS services fail and retry instead of quietly
+revoking every zone. dcrouter itself still comes up — both services are optional
+— so the rest of the router keeps running while DNS stays deliberately down.
+
 ## Route Source Bindings
 
 API-created route records pass ordered `metadata.sourceBindings[]` alongside the SmartProxy route config to express source and path policy variants without duplicating whole routes by hand. Each binding points at a source profile id through `sourceProfileRef`. Dashboard presets resolve seeded profile names to ids before saving.
@@ -361,7 +401,9 @@ const router = new DcRouter({
   },
   emailOutboundMode: 'remoteIngress',
   dnsNsDomains: ['ns1.example.com', 'ns2.example.com'],
-  dnsScopes: ['example.com'],
+  // Which zones the embedded DNS server answers for is not configured here.
+  // A zone earns authority by its public delegation naming dnsNsDomains, and
+  // that proof lives in the database — see the "DNS Authority" section above.
   publicIp: '203.0.113.10',
   remoteIngressConfig: {
     enabled: true,
@@ -473,7 +515,7 @@ Supported environment overrides include:
 | `DCROUTER_BASE_DIR` | Runtime data root. |
 | `DCROUTER_TLS_EMAIL` / `DCROUTER_TLS_DOMAIN` | TLS/ACME seed settings. |
 | `DCROUTER_PUBLIC_IP` / `DCROUTER_PROXY_IPS` | Public/proxy IP exposure settings. |
-| `DCROUTER_DNS_NS_DOMAINS` / `DCROUTER_DNS_SCOPES` | DNS nameserver and authoritative scope settings. |
+| `DCROUTER_DNS_NS_DOMAINS` | Nameserver hostnames. `DCROUTER_DNS_SCOPES` is no longer honored — DNS authority is delegation-verified database state, and a container still setting it is warned at startup. |
 | `DCROUTER_EMAIL_HOSTNAME` / `DCROUTER_EMAIL_PORTS` | Email server seed settings. |
 | `DCROUTER_CACHE_ENABLED` | Enables or disables DB-backed persistence. |
 | `DCROUTER_MAX_CONNECTIONS`, `DCROUTER_MAX_CONNECTIONS_PER_IP`, `DCROUTER_CONNECTION_RATE_LIMIT` | SmartProxy capacity and rate-limit overrides. |

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '17.10.2',
+  version: '18.0.0',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }