@serve.zone/dcrouter 34.0.0 → 34.2.0

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.2.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.2.0",
   "description": "A multifaceted routing service handling mail and SMS delivery functions.",
   "type": "module",
   "bin": {
@@ -20,8 +20,11 @@
     "@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",
+    "@serve.zone/dcrouter-v33": "npm:@serve.zone/dcrouter@33.0.0",
+    "@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,14 +44,14 @@
     "@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",
     "@push.rocks/smartlog": "^3.2.2",
     "@push.rocks/smartmcp": "^0.3.0",
     "@push.rocks/smartmetrics": "^3.0.3",
-    "@push.rocks/smartmigration": "2.0.1",
+    "@push.rocks/smartmigration": "2.1.0",
     "@push.rocks/smartmta": "^13.0.1",
     "@push.rocks/smartnetwork": "^4.10.1",
     "@push.rocks/smartpath": "^6.0.0",
@@ -68,6 +71,7 @@
     "@tsclass/tsclass": "^9.5.1",
     "@types/qrcode": "^1.5.6",
     "argon2": "^0.45.1",
+    "bson": "7.3.2",
     "ipaddr.js": "^2.5.0",
     "lru-cache": "^11.5.2",
     "qrcode": "^1.5.4",

package/readme.md

@@ -63,6 +63,31 @@ Use the package as a TypeScript library:
 pnpm add @serve.zone/dcrouter
 ```
 
+## CLI
+
+```bash
+dcrouter                 # start the router (DCROUTER_MODE=OCI_CONTAINER for the container configuration)
+dcrouter --version
+dcrouter --help
+dcrouter migrate --storage-path <absolute root> --to <version> [--db-name dcrouter] [--plan]
+```
+
+`dcrouter` starts the router only without arguments; from 34.2.0 on it refuses any argument it does not know (exit code 2) and starts nothing. Releases up to 34.1.0 started the router on an unknown argument, so check `dcrouter --version` before running a command a later release added.
+
+`dcrouter migrate` walks the data of a **stopped** dcrouter back to an earlier data version through the migration steps' down handlers; forward migrations happen when dcrouter starts. The supported downgrade is data version `34.0.0` → `32.6.0`, the data dcrouter 33.0.0 reads, which returns the route DNS ownership the `release-annexed-gateway-route-dns-records` step released:
+
+```bash
+# the embedded database's default root is ~/.serve.zone/dcrouter/tsmdb (dbConfig.storagePath overrides it)
+dcrouter migrate --storage-path /root/.serve.zone/dcrouter/tsmdb --to 32.6.0 --plan   # report only
+dcrouter migrate --storage-path /root/.serve.zone/dcrouter/tsmdb --to 32.6.0
+```
+
+- `--storage-path` (required, absolute, no default) is the embedded database's storage root; `--db-name` is the database inside it (default `dcrouter`). The root is checked offline first and the engine's owner lock is taken, so a root a running dcrouter owns is refused.
+- `--to` must be a step boundary behind the ledger. A forward target, a ledger a newer dcrouter wrote and a database without a ledger are refused; a target equal to the ledger is a no-op.
+- A database that dcrouter 34.0.0 or 34.1.0 upgraded is refused: those releases did not record the ownership they released, so restore the export taken before that upgrade instead. Upgrade a 33.0.0 database straight to 34.2.0 or later to keep the way back.
+- Records written after the upgrade are kept: a record deleted since is not recreated, an edited one gets its ownership back, and any record whose ownership conflicts with the recorded one refuses the whole downgrade with nothing changed.
+- The last output line is `DCROUTER_MIGRATE_RESULT:{json}` (`ok`, the versions and the steps, or the error); the exit code is 0, 1 on a refusal or failure, and 2 on a command line it does not accept.
+
 ## Quick Start
 
 This starts the gateway on unprivileged ports and stores data under the default `~/.serve.zone/dcrouter` base directory.
@@ -530,13 +555,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 +616,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 +858,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.2.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;
   }