@serve.zone/dcrouter-apiclient 34.0.0 → 34.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -13,10 +13,15 @@
13
13
  * The fix is not to make the declared list editable. A list an operator can
14
14
  * simply append to is self-assertion, which is precisely the failure mode that
15
15
  * let routes claim domains nobody verified we own. Instead a zone earns
16
- * authority by *proof*: its public delegation must name our nameservers. That
17
- * proof is unforgeable by an ops-API caller — you cannot point `example.com`'s
18
- * NS records at our nameservers unless you actually control the domain — and it
19
- * is the missing comparison between the two representations.
16
+ * authority by *proof*: its delegation in the parent zone must name our
17
+ * nameservers. That proof is unforgeable by an ops-API caller — you cannot point
18
+ * `example.com`'s delegation at our nameservers unless you actually control the
19
+ * domain — and it is the missing comparison between the two representations.
20
+ *
21
+ * The proof is read from the parent zone's own servers, asked without
22
+ * recursion, never from a recursive resolver: a recursive lookup of a zone
23
+ * delegated to us but not claimed yet reaches our servers, which REFUSE it, so
24
+ * it could never prove the delegation it is supposed to prove.
20
25
  *
21
26
  * `dnsScopes` is gone entirely. There is exactly one representation of DNS
22
27
  * authority now, it lives in the database, and it is the one that carries its
@@ -37,7 +42,10 @@ export interface IDnsAuthorityZone {
37
42
  origin: TDnsAuthorityZoneOrigin;
38
43
  /** When the delegation proof was observed. */
39
44
  verifiedAt?: number;
40
- /** Nameservers observed at verification time — the evidence for the proof. */
45
+ /**
46
+ * The NS set the parent zone's servers delegated the zone to at verification
47
+ * time — the evidence for the proof.
48
+ */
41
49
  observedNameservers?: string[];
42
50
  /** Operator who performed the verification. */
43
51
  verifiedBy?: string;
@@ -62,20 +70,69 @@ export interface IDnsAuthoritySettings {
62
70
  updatedBy: string;
63
71
  }
64
72
  /**
65
- * Outcome of a delegation probe.
73
+ * Outcome of a delegation probe, decided by the parent zone's servers alone.
74
+ *
75
+ * - 'delegated': at least two of the parent's servers, reached through at least
76
+ * two different parent nameserver names, gave the identical referral for the
77
+ * zone, and its NS set names at least one of our nameservers. A referral that
78
+ * carries a DS sets `dsPresent`, and such a zone cannot be claimed.
79
+ * - 'not-delegated': the same agreement on a referral that names none of our
80
+ * nameservers, or on an authoritative "no such delegation" (NXDOMAIN or NODATA
81
+ * with the parent's SOA). Also the verdict for an unusable zone name.
82
+ * - 'undeterminable': anything less — a failed lookup, fewer than two
83
+ * conclusive answers, or any disagreement between them.
66
84
  *
67
85
  * 'undeterminable' is deliberately distinct from 'not-delegated': a resolver
68
86
  * timeout is not evidence that a zone is not ours. Conflating them would let a
69
87
  * transient network fault revoke authority, turning a blip into an outage.
70
88
  */
71
89
  export type TDnsDelegationVerdict = 'delegated' | 'not-delegated' | 'undeterminable';
90
+ /**
91
+ * How the probe classified one parent server's answer to the non-recursive
92
+ * NS query for the zone.
93
+ *
94
+ * - 'referral': RCODE 0, AA=0, an empty answer section, and an authority
95
+ * section whose NS records are all owned by the zone, with an OPT record that
96
+ * echoes DO=1 (otherwise a missing DS would prove nothing).
97
+ * - 'negative': AA=1 NXDOMAIN or NODATA with an empty answer section and the
98
+ * parent zone's SOA in the authority section.
99
+ * - 'inconclusive': everything else, including timeouts, REFUSED, any other
100
+ * AA=1 answer (a server that hosts the parent and the child zone answers for
101
+ * the child instead of referring) and referrals to any other name.
102
+ */
103
+ export type TDnsDelegationParentOutcome = 'referral' | 'negative' | 'inconclusive';
104
+ /** One parent server's answer to the non-recursive NS query for the zone. */
105
+ export interface IDnsDelegationParentAnswer {
106
+ /** The parent server the probe asked, as `ip:port` (`[ip]:port` for IPv6). */
107
+ server: string;
108
+ /** The parent nameserver name this address belongs to. */
109
+ nameserver: string;
110
+ outcome: TDnsDelegationParentOutcome;
111
+ /** The referral's NS set, lowercased, trailing-dot stripped and sorted (referral only). */
112
+ nameservers?: string[];
113
+ /** Whether the referral carried a DS RRset for the zone (referral only). */
114
+ dsPresent?: boolean;
115
+ detail: string;
116
+ }
72
117
  export interface IDnsDelegationProbe {
73
118
  zone: string;
74
119
  verdict: TDnsDelegationVerdict;
75
- /** NS records observed for the zone, lowercased and trailing-dot stripped. */
120
+ /**
121
+ * The NS set the parent zone's servers delegate the zone to, lowercased and
122
+ * trailing-dot stripped; empty when there is no agreed referral.
123
+ */
76
124
  observedNameservers: string[];
77
125
  expectedNameservers: string[];
78
126
  detail: string;
127
+ /** The parent zone whose servers were asked; absent when it was not found. */
128
+ parentZone?: string;
129
+ /**
130
+ * Whether the agreed referral carried a DS for the zone. Set on a verdict
131
+ * that rests on a referral; a `delegated` zone with a DS cannot be claimed.
132
+ */
133
+ dsPresent?: boolean;
134
+ /** Every parent server's classified answer, when parent servers were asked. */
135
+ parentAnswers?: IDnsDelegationParentAnswer[];
79
136
  }
80
137
  /** A disagreement between claimed authority and what is actually true. */
81
138
  export type TDnsAuthorityDriftKind =
@@ -13,14 +13,19 @@
13
13
  * The fix is not to make the declared list editable. A list an operator can
14
14
  * simply append to is self-assertion, which is precisely the failure mode that
15
15
  * let routes claim domains nobody verified we own. Instead a zone earns
16
- * authority by *proof*: its public delegation must name our nameservers. That
17
- * proof is unforgeable by an ops-API caller — you cannot point `example.com`'s
18
- * NS records at our nameservers unless you actually control the domain — and it
19
- * is the missing comparison between the two representations.
16
+ * authority by *proof*: its delegation in the parent zone must name our
17
+ * nameservers. That proof is unforgeable by an ops-API caller — you cannot point
18
+ * `example.com`'s delegation at our nameservers unless you actually control the
19
+ * domain — and it is the missing comparison between the two representations.
20
+ *
21
+ * The proof is read from the parent zone's own servers, asked without
22
+ * recursion, never from a recursive resolver: a recursive lookup of a zone
23
+ * delegated to us but not claimed yet reaches our servers, which REFUSE it, so
24
+ * it could never prove the delegation it is supposed to prove.
20
25
  *
21
26
  * `dnsScopes` is gone entirely. There is exactly one representation of DNS
22
27
  * authority now, it lives in the database, and it is the one that carries its
23
28
  * own evidence.
24
29
  */
25
30
  export {};
26
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZG5zLWF1dGhvcml0eS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX2ludGVyZmFjZXMvZGF0YS9kbnMtYXV0aG9yaXR5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXVCRyJ9
31
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZG5zLWF1dGhvcml0eS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX2ludGVyZmFjZXMvZGF0YS9kbnMtYXV0aG9yaXR5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBNEJHIn0=
@@ -12,8 +12,9 @@ export interface IReq_GetDnsAuthority extends plugins.typedrequestInterfaces.imp
12
12
  };
13
13
  }
14
14
  /**
15
- * Probe a zone's public delegation without changing anything. Lets an operator
16
- * see the evidence before claiming authority.
15
+ * Probe a zone's delegation in its parent zone without changing anything. Lets
16
+ * an operator see the evidence (the parent zone and each parent server's
17
+ * answer) before claiming authority.
17
18
  */
18
19
  export interface IReq_ProbeDnsAuthorityZone extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ProbeDnsAuthorityZone> {
19
20
  method: 'probeDnsAuthorityZone';
@@ -27,9 +28,10 @@ export interface IReq_ProbeDnsAuthorityZone extends plugins.typedrequestInterfac
27
28
  };
28
29
  }
29
30
  /**
30
- * Claim authority over a zone. Succeeds only when the zone's public delegation
31
- * names our nameservers; the claim is then persisted and reconciled in-process,
32
- * with no restart.
31
+ * Claim authority over a zone. Succeeds only on a `delegated` probe without a
32
+ * DS: the parent zone's servers agree that the zone is delegated to our
33
+ * nameservers and publish no DS for it. The claim is then persisted and
34
+ * reconciled in-process, with no restart.
33
35
  */
34
36
  export interface IReq_VerifyDnsAuthorityZone extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_VerifyDnsAuthorityZone> {
35
37
  method: 'verifyDnsAuthorityZone';
package/package.json CHANGED
@@ -28,7 +28,7 @@
28
28
  "MAC authentication"
29
29
  ],
30
30
  "name": "@serve.zone/dcrouter-apiclient",
31
- "version": "34.0.0",
31
+ "version": "34.1.0",
32
32
  "type": "module",
33
33
  "description": "Object-oriented TypeScript client and shared TypedRequest contracts for the dcrouter OpsServer API.",
34
34
  "main": "./dist_ts_apiclient/index.js",
@@ -13,10 +13,15 @@
13
13
  * The fix is not to make the declared list editable. A list an operator can
14
14
  * simply append to is self-assertion, which is precisely the failure mode that
15
15
  * let routes claim domains nobody verified we own. Instead a zone earns
16
- * authority by *proof*: its public delegation must name our nameservers. That
17
- * proof is unforgeable by an ops-API caller — you cannot point `example.com`'s
18
- * NS records at our nameservers unless you actually control the domain — and it
19
- * is the missing comparison between the two representations.
16
+ * authority by *proof*: its delegation in the parent zone must name our
17
+ * nameservers. That proof is unforgeable by an ops-API caller — you cannot point
18
+ * `example.com`'s delegation at our nameservers unless you actually control the
19
+ * domain — and it is the missing comparison between the two representations.
20
+ *
21
+ * The proof is read from the parent zone's own servers, asked without
22
+ * recursion, never from a recursive resolver: a recursive lookup of a zone
23
+ * delegated to us but not claimed yet reaches our servers, which REFUSE it, so
24
+ * it could never prove the delegation it is supposed to prove.
20
25
  *
21
26
  * `dnsScopes` is gone entirely. There is exactly one representation of DNS
22
27
  * authority now, it lives in the database, and it is the one that carries its
@@ -39,7 +44,10 @@ export interface IDnsAuthorityZone {
39
44
  origin: TDnsAuthorityZoneOrigin;
40
45
  /** When the delegation proof was observed. */
41
46
  verifiedAt?: number;
42
- /** Nameservers observed at verification time — the evidence for the proof. */
47
+ /**
48
+ * The NS set the parent zone's servers delegated the zone to at verification
49
+ * time — the evidence for the proof.
50
+ */
43
51
  observedNameservers?: string[];
44
52
  /** Operator who performed the verification. */
45
53
  verifiedBy?: string;
@@ -67,7 +75,17 @@ export interface IDnsAuthoritySettings {
67
75
  }
68
76
 
69
77
  /**
70
- * Outcome of a delegation probe.
78
+ * Outcome of a delegation probe, decided by the parent zone's servers alone.
79
+ *
80
+ * - 'delegated': at least two of the parent's servers, reached through at least
81
+ * two different parent nameserver names, gave the identical referral for the
82
+ * zone, and its NS set names at least one of our nameservers. A referral that
83
+ * carries a DS sets `dsPresent`, and such a zone cannot be claimed.
84
+ * - 'not-delegated': the same agreement on a referral that names none of our
85
+ * nameservers, or on an authoritative "no such delegation" (NXDOMAIN or NODATA
86
+ * with the parent's SOA). Also the verdict for an unusable zone name.
87
+ * - 'undeterminable': anything less — a failed lookup, fewer than two
88
+ * conclusive answers, or any disagreement between them.
71
89
  *
72
90
  * 'undeterminable' is deliberately distinct from 'not-delegated': a resolver
73
91
  * timeout is not evidence that a zone is not ours. Conflating them would let a
@@ -75,13 +93,54 @@ export interface IDnsAuthoritySettings {
75
93
  */
76
94
  export type TDnsDelegationVerdict = 'delegated' | 'not-delegated' | 'undeterminable';
77
95
 
96
+ /**
97
+ * How the probe classified one parent server's answer to the non-recursive
98
+ * NS query for the zone.
99
+ *
100
+ * - 'referral': RCODE 0, AA=0, an empty answer section, and an authority
101
+ * section whose NS records are all owned by the zone, with an OPT record that
102
+ * echoes DO=1 (otherwise a missing DS would prove nothing).
103
+ * - 'negative': AA=1 NXDOMAIN or NODATA with an empty answer section and the
104
+ * parent zone's SOA in the authority section.
105
+ * - 'inconclusive': everything else, including timeouts, REFUSED, any other
106
+ * AA=1 answer (a server that hosts the parent and the child zone answers for
107
+ * the child instead of referring) and referrals to any other name.
108
+ */
109
+ export type TDnsDelegationParentOutcome = 'referral' | 'negative' | 'inconclusive';
110
+
111
+ /** One parent server's answer to the non-recursive NS query for the zone. */
112
+ export interface IDnsDelegationParentAnswer {
113
+ /** The parent server the probe asked, as `ip:port` (`[ip]:port` for IPv6). */
114
+ server: string;
115
+ /** The parent nameserver name this address belongs to. */
116
+ nameserver: string;
117
+ outcome: TDnsDelegationParentOutcome;
118
+ /** The referral's NS set, lowercased, trailing-dot stripped and sorted (referral only). */
119
+ nameservers?: string[];
120
+ /** Whether the referral carried a DS RRset for the zone (referral only). */
121
+ dsPresent?: boolean;
122
+ detail: string;
123
+ }
124
+
78
125
  export interface IDnsDelegationProbe {
79
126
  zone: string;
80
127
  verdict: TDnsDelegationVerdict;
81
- /** NS records observed for the zone, lowercased and trailing-dot stripped. */
128
+ /**
129
+ * The NS set the parent zone's servers delegate the zone to, lowercased and
130
+ * trailing-dot stripped; empty when there is no agreed referral.
131
+ */
82
132
  observedNameservers: string[];
83
133
  expectedNameservers: string[];
84
134
  detail: string;
135
+ /** The parent zone whose servers were asked; absent when it was not found. */
136
+ parentZone?: string;
137
+ /**
138
+ * Whether the agreed referral carried a DS for the zone. Set on a verdict
139
+ * that rests on a referral; a `delegated` zone with a DS cannot be claimed.
140
+ */
141
+ dsPresent?: boolean;
142
+ /** Every parent server's classified answer, when parent servers were asked. */
143
+ parentAnswers?: IDnsDelegationParentAnswer[];
85
144
  }
86
145
 
87
146
  /** A disagreement between claimed authority and what is actually true. */
@@ -21,8 +21,9 @@ export interface IReq_GetDnsAuthority extends plugins.typedrequestInterfaces.imp
21
21
  }
22
22
 
23
23
  /**
24
- * Probe a zone's public delegation without changing anything. Lets an operator
25
- * see the evidence before claiming authority.
24
+ * Probe a zone's delegation in its parent zone without changing anything. Lets
25
+ * an operator see the evidence (the parent zone and each parent server's
26
+ * answer) before claiming authority.
26
27
  */
27
28
  export interface IReq_ProbeDnsAuthorityZone extends plugins.typedrequestInterfaces.implementsTR<
28
29
  plugins.typedrequestInterfaces.ITypedRequest,
@@ -40,9 +41,10 @@ export interface IReq_ProbeDnsAuthorityZone extends plugins.typedrequestInterfac
40
41
  }
41
42
 
42
43
  /**
43
- * Claim authority over a zone. Succeeds only when the zone's public delegation
44
- * names our nameservers; the claim is then persisted and reconciled in-process,
45
- * with no restart.
44
+ * Claim authority over a zone. Succeeds only on a `delegated` probe without a
45
+ * DS: the parent zone's servers agree that the zone is delegated to our
46
+ * nameservers and publish no DS for it. The claim is then persisted and
47
+ * reconciled in-process, with no restart.
46
48
  */
47
49
  export interface IReq_VerifyDnsAuthorityZone extends plugins.typedrequestInterfaces.implementsTR<
48
50
  plugins.typedrequestInterfaces.ITypedRequest,