@serve.zone/dcrouter 34.0.0 → 34.1.0

package/dist_ts_interfaces/data/dns-authority.d.ts

@@ -13,10 +13,15 @@
  * The fix is not to make the declared list editable. A list an operator can
  * simply append to is self-assertion, which is precisely the failure mode that
  * let routes claim domains nobody verified we own. Instead a zone earns
- * authority by *proof*: its public delegation must name our nameservers. That
- * proof is unforgeable by an ops-API caller — you cannot point `example.com`'s
- * NS records at our nameservers unless you actually control the domain — and it
- * is the missing comparison between the two representations.
+ * authority by *proof*: its delegation in the parent zone must name our
+ * nameservers. That proof is unforgeable by an ops-API caller — you cannot point
+ * `example.com`'s delegation at our nameservers unless you actually control the
+ * domain — and it is the missing comparison between the two representations.
+ *
+ * The proof is read from the parent zone's own servers, asked without
+ * recursion, never from a recursive resolver: a recursive lookup of a zone
+ * delegated to us but not claimed yet reaches our servers, which REFUSE it, so
+ * it could never prove the delegation it is supposed to prove.
  *
  * `dnsScopes` is gone entirely. There is exactly one representation of DNS
  * authority now, it lives in the database, and it is the one that carries its
@@ -37,7 +42,10 @@ export interface IDnsAuthorityZone {
     origin: TDnsAuthorityZoneOrigin;
     /** When the delegation proof was observed. */
     verifiedAt?: number;
-    /** Nameservers observed at verification time — the evidence for the proof. */
+    /**
+     * The NS set the parent zone's servers delegated the zone to at verification
+     * time — the evidence for the proof.
+     */
     observedNameservers?: string[];
     /** Operator who performed the verification. */
     verifiedBy?: string;
@@ -62,20 +70,69 @@ export interface IDnsAuthoritySettings {
     updatedBy: string;
 }
 /**
- * Outcome of a delegation probe.
+ * Outcome of a delegation probe, decided by the parent zone's servers alone.
+ *
+ * - 'delegated': at least two of the parent's servers, reached through at least
+ *   two different parent nameserver names, gave the identical referral for the
+ *   zone, and its NS set names at least one of our nameservers. A referral that
+ *   carries a DS sets `dsPresent`, and such a zone cannot be claimed.
+ * - 'not-delegated': the same agreement on a referral that names none of our
+ *   nameservers, or on an authoritative "no such delegation" (NXDOMAIN or NODATA
+ *   with the parent's SOA). Also the verdict for an unusable zone name.
+ * - 'undeterminable': anything less — a failed lookup, fewer than two
+ *   conclusive answers, or any disagreement between them.
  *
  * 'undeterminable' is deliberately distinct from 'not-delegated': a resolver
  * timeout is not evidence that a zone is not ours. Conflating them would let a
  * transient network fault revoke authority, turning a blip into an outage.
  */
 export type TDnsDelegationVerdict = 'delegated' | 'not-delegated' | 'undeterminable';
+/**
+ * How the probe classified one parent server's answer to the non-recursive
+ * NS query for the zone.
+ *
+ * - 'referral': RCODE 0, AA=0, an empty answer section, and an authority
+ *   section whose NS records are all owned by the zone, with an OPT record that
+ *   echoes DO=1 (otherwise a missing DS would prove nothing).
+ * - 'negative': AA=1 NXDOMAIN or NODATA with an empty answer section and the
+ *   parent zone's SOA in the authority section.
+ * - 'inconclusive': everything else, including timeouts, REFUSED, any other
+ *   AA=1 answer (a server that hosts the parent and the child zone answers for
+ *   the child instead of referring) and referrals to any other name.
+ */
+export type TDnsDelegationParentOutcome = 'referral' | 'negative' | 'inconclusive';
+/** One parent server's answer to the non-recursive NS query for the zone. */
+export interface IDnsDelegationParentAnswer {
+    /** The parent server the probe asked, as `ip:port` (`[ip]:port` for IPv6). */
+    server: string;
+    /** The parent nameserver name this address belongs to. */
+    nameserver: string;
+    outcome: TDnsDelegationParentOutcome;
+    /** The referral's NS set, lowercased, trailing-dot stripped and sorted (referral only). */
+    nameservers?: string[];
+    /** Whether the referral carried a DS RRset for the zone (referral only). */
+    dsPresent?: boolean;
+    detail: string;
+}
 export interface IDnsDelegationProbe {
     zone: string;
     verdict: TDnsDelegationVerdict;
-    /** NS records observed for the zone, lowercased and trailing-dot stripped. */
+    /**
+     * The NS set the parent zone's servers delegate the zone to, lowercased and
+     * trailing-dot stripped; empty when there is no agreed referral.
+     */
     observedNameservers: string[];
     expectedNameservers: string[];
     detail: string;
+    /** The parent zone whose servers were asked; absent when it was not found. */
+    parentZone?: string;
+    /**
+     * Whether the agreed referral carried a DS for the zone. Set on a verdict
+     * that rests on a referral; a `delegated` zone with a DS cannot be claimed.
+     */
+    dsPresent?: boolean;
+    /** Every parent server's classified answer, when parent servers were asked. */
+    parentAnswers?: IDnsDelegationParentAnswer[];
 }
 /** A disagreement between claimed authority and what is actually true. */
 export type TDnsAuthorityDriftKind = 

package/dist_ts_interfaces/data/dns-authority.js

@@ -13,14 +13,19 @@
  * The fix is not to make the declared list editable. A list an operator can
  * simply append to is self-assertion, which is precisely the failure mode that
  * let routes claim domains nobody verified we own. Instead a zone earns
- * authority by *proof*: its public delegation must name our nameservers. That
- * proof is unforgeable by an ops-API caller — you cannot point `example.com`'s
- * NS records at our nameservers unless you actually control the domain — and it
- * is the missing comparison between the two representations.
+ * authority by *proof*: its delegation in the parent zone must name our
+ * nameservers. That proof is unforgeable by an ops-API caller — you cannot point
+ * `example.com`'s delegation at our nameservers unless you actually control the
+ * domain — and it is the missing comparison between the two representations.
+ *
+ * The proof is read from the parent zone's own servers, asked without
+ * recursion, never from a recursive resolver: a recursive lookup of a zone
+ * delegated to us but not claimed yet reaches our servers, which REFUSE it, so
+ * it could never prove the delegation it is supposed to prove.
  *
  * `dnsScopes` is gone entirely. There is exactly one representation of DNS
  * authority now, it lives in the database, and it is the one that carries its
  * own evidence.
  */
 export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZG5zLWF1dGhvcml0eS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX2ludGVyZmFjZXMvZGF0YS9kbnMtYXV0aG9yaXR5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXVCRyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZG5zLWF1dGhvcml0eS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX2ludGVyZmFjZXMvZGF0YS9kbnMtYXV0aG9yaXR5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBNEJHIn0=

package/dist_ts_interfaces/requests/dns-authority.d.ts

@@ -12,8 +12,9 @@ export interface IReq_GetDnsAuthority extends plugins.typedrequestInterfaces.imp
     };
 }
 /**
- * Probe a zone's public delegation without changing anything. Lets an operator
- * see the evidence before claiming authority.
+ * Probe a zone's delegation in its parent zone without changing anything. Lets
+ * an operator see the evidence (the parent zone and each parent server's
+ * answer) before claiming authority.
  */
 export interface IReq_ProbeDnsAuthorityZone extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ProbeDnsAuthorityZone> {
     method: 'probeDnsAuthorityZone';
@@ -27,9 +28,10 @@ export interface IReq_ProbeDnsAuthorityZone extends plugins.typedrequestInterfac
     };
 }
 /**
- * Claim authority over a zone. Succeeds only when the zone's public delegation
- * names our nameservers; the claim is then persisted and reconciled in-process,
- * with no restart.
+ * Claim authority over a zone. Succeeds only on a `delegated` probe without a
+ * DS: the parent zone's servers agree that the zone is delegated to our
+ * nameservers and publish no DS for it. The claim is then persisted and
+ * reconciled in-process, with no restart.
  */
 export interface IReq_VerifyDnsAuthorityZone extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_VerifyDnsAuthorityZone> {
     method: 'verifyDnsAuthorityZone';

package/dist_ts_web/00_commitinfo_data.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@serve.zone/dcrouter",
   "private": false,
-  "version": "34.0.0",
+  "version": "34.1.0",
   "description": "A multifaceted routing service handling mail and SMS delivery functions.",
   "type": "module",
   "bin": {
@@ -20,8 +20,10 @@
     "@git.zone/tsrepo": "^1.1.1",
     "@push.rocks/smartdb-v2": "npm:@push.rocks/smartdb@2.14.6",
     "@push.rocks/smartdb-v5.2": "npm:@push.rocks/smartdb@5.2.2",
+    "@types/dns-packet": "^5.6.5",
     "@types/node": "26.6.5",
     "@types/web-push": "3.6.4",
+    "dns-packet": "^5.6.1",
     "tsx": "^4.23.15"
   },
   "dependencies": {
@@ -41,7 +43,7 @@
     "@push.rocks/smartbucket": "^4.13.0",
     "@push.rocks/smartchallenge": "^1.1.0",
     "@push.rocks/smartdb": "5.7.1",
-    "@push.rocks/smartdns": "^8.2.1",
+    "@push.rocks/smartdns": "^11.1.0",
     "@push.rocks/smartfs": "^1.7.0",
     "@push.rocks/smartguard": "^3.1.2",
     "@push.rocks/smartjwt": "^2.5.1",

package/readme.md

@@ -530,13 +530,55 @@ records and testing DNS keep their own durable records and are not journaled her
 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.
+A zone enters the authority set exactly one way: its **delegation in the parent
+zone must name one of `dnsNsDomains`**, read from the parent zone's own servers.
+An ops-API caller cannot repoint somebody else's delegation, so writing the
+record is not the same as manufacturing the proof.
+
+The probe never looks the zone up through a recursive resolver: for a zone that
+is delegated to dcrouter but not claimed yet, the resolver would ask dcrouter,
+which REFUSES the unclaimed zone, and the lookup would fail with SERVFAIL. It
+works like this instead:
+
+1. It finds the parent zone over DNS-over-HTTPS: the nearest proper suffix of the
+   zone that has NS records (at most 8 levels up). The zone itself and names
+   below it are never asked over DoH, and a failed lookup at any level makes the
+   probe `undeterminable` rather than skipping to a grandparent.
+2. It looks up A and AAAA of up to 8 of the parent's nameserver names over DoH
+   and picks up to 4 distinct addresses: one per name first, IPv4 before IPv6.
+   Fewer than 2 names with an address is `undeterminable`.
+3. It asks each picked server for the zone's NS records without recursion
+   (RD=0) and with DO=1, over UDP and TCP when the answer is truncated.
+4. Only two answers are conclusive. A referral: no AA bit, an empty answer
+   section, authority NS records all owned by the zone, and an OPT record that
+   echoes DO=1. A negative: an authoritative NXDOMAIN or NODATA with an empty
+   answer section and the parent zone's SOA. Anything else is inconclusive,
+   including an authoritative answer from a server that hosts both the parent
+   and the zone.
+5. At least 2 conclusive answers, through at least 2 different parent
+   nameserver names, must be identical (the NS set and whether a DS came with
+   it; glue, TTLs, case and order are ignored). Any disagreement is
+   `undeterminable`.
+
+The result is `delegated` when the agreed referral names one of `dnsNsDomains`,
+and `not-delegated` when it names none of them (a foreign delegation) or the
+parent has no delegation for the zone. `observedNameservers` is the NS set the
+parent delegates to, and the probe also returns `parentZone`, `dsPresent` and
+every parent server's classified answer (`parentAnswers`). DoH never decides a
+verdict, and the system resolver is never used: on a dcrouter host it may be
+dcrouter itself, which would make the proof self-confirming.
+
+A zone whose parent publishes a **DS** for it is reported as `delegated` with
+`dsPresent: true`, and `verifyDnsAuthorityZone` refuses it: remove the DS at the
+registrar, then verify. The drift audit says so too. A zone below a zone dcrouter
+already serves is `undeterminable`: its parent servers are dcrouter's own, which
+answer for the parent authoritatively instead of referring.
+
+DoH lookups time out after 5 s and each parent server attempt after 2 s (a
+truncated UDP answer gets one more TCP attempt). No probe step starts after
+30 s, so the probe's lookups and queries end within 35 s (plus starting and
+stopping the probe's DNS client); a claim holds the DNS mutation lock about
+that long at most while it probes.
 
 | Operation | Scope | Effect |
 | --- | --- | --- |
@@ -549,7 +591,13 @@ as manufacturing the proof.
 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.
+mutation refuses on `undeterminable` rather than assuming either way, and a
+claim also refuses a `delegated` zone with a DS.
+
+The embedded DNS server synthesizes every SOA itself, with TTL 3600, refresh
+3600, retry 600, expire 604800, minimum 86400, rname `hostmaster.<zone>` and
+mname the first `dnsNsDomains` entry (smartdns falls back to `ns1.<dnssecZone>`, the DNSSEC signing zone, when
+`dnsNsDomains` is empty); negative answers carry the SOA with TTL 3600.
 
 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,
@@ -785,8 +833,9 @@ const router = new DcRouter({
   emailOutboundMode: 'remoteIngress',
   dnsNsDomains: ['ns1.example.com', 'ns2.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.
+  // A zone earns authority by its delegation in the parent zone naming
+  // dnsNsDomains, and that proof lives in the database — see the "DNS
+  // Authority" section above.
   publicIp: '203.0.113.10',
   remoteIngressConfig: {
     enabled: true,

package/ts/00_commitinfo_data.ts

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

package/ts/dns/classes.dns-server-runtime.ts

@@ -13,6 +13,24 @@ type TDnsRecordSeed = { name: string; type: string; value: string; ttl?: number;
 /** The required DNSSEC keying zone when dcrouter currently claims no DNS zone. */
 export const NO_AUTHORITY_SENTINEL_ZONE = 'no-authority.invalid';
 
+/**
+ * The server-wide SOA values of the embedded DNS server.
+ *
+ * smartdns 11 lowered its default SOA `minimum` from 86400 to 300, which would
+ * cut the negative-answer SOA TTL from min(3600, 86400) = 3600 to 300. The pin
+ * keeps the wire values dcrouter has always served: TTL 3600, refresh 3600,
+ * retry 600, expire 604800, minimum 86400, rname `hostmaster.<zone>`, and mname
+ * the primary nameserver, else smartdns' `ns1.<dnssecZone>`. smartdns refuses
+ * `soaDefaults.mname` together with the deprecated `primaryNameserver` with a
+ * TypeError, so dcrouter sets the mname here and never passes the latter.
+ */
+export const buildDnsServerSoaDefaults = (
+  primaryNameserverArg: string | undefined,
+): Partial<plugins.smartdns.dnsServerMod.IDnsSoaSettings> => ({
+  ...(primaryNameserverArg ? { mname: primaryNameserverArg } : {}),
+  minimum: 86400,
+});
+
 /**
  * Sets up and feeds the embedded authoritative smartdns server: validates the
  * DNS configuration, generates authoritative/email/DKIM records, applies
@@ -139,7 +157,8 @@ export class DnsServerRuntime {
       dnssecZone: bootAuthorityZones[0] || NO_AUTHORITY_SENTINEL_ZONE,
       // SmartDNS copies this boot snapshot; later changes use its live setter.
       authoritativeZones: bootAuthorityZones,
-      primaryNameserver: primaryNameserver, // Automatically generates correct SOA records
+      // smartdns synthesizes every SOA (apex and negative answers) from these.
+      soaDefaults: buildDnsServerSoaDefaults(primaryNameserver),
       // For now, use self-signed cert until we integrate with Let's Encrypt
       httpsKey: '',
       httpsCert: ''
@@ -828,7 +847,7 @@ export class DnsServerRuntime {
     }
 
     // Apex NS records are owned by DnsManager (see the doc comment above), and
-    // SOA is synthesized by smartdns from `primaryNameserver`.
+    // SOA is synthesized by smartdns from `soaDefaults` (buildDnsServerSoaDefaults).
     return records;
   }