@optimystic/db-core 1.9.0 → 1.10.1
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.
- package/dist/src/cohort-topic/addressing.d.ts +46 -6
- package/dist/src/cohort-topic/addressing.d.ts.map +1 -1
- package/dist/src/cohort-topic/addressing.js +58 -18
- package/dist/src/cohort-topic/addressing.js.map +1 -1
- package/dist/src/cohort-topic/member-engine.d.ts +21 -1
- package/dist/src/cohort-topic/member-engine.d.ts.map +1 -1
- package/dist/src/cohort-topic/member-engine.js +39 -9
- package/dist/src/cohort-topic/member-engine.js.map +1 -1
- package/dist/src/cohort-topic/membership/publisher.js +1 -1
- package/dist/src/cohort-topic/membership/publisher.js.map +1 -1
- package/dist/src/cohort-topic/membership/source.d.ts +4 -0
- package/dist/src/cohort-topic/membership/source.d.ts.map +1 -1
- package/dist/src/cohort-topic/membership/source.js +4 -0
- package/dist/src/cohort-topic/membership/source.js.map +1 -1
- package/dist/src/cohort-topic/membership/verifier.d.ts +51 -9
- package/dist/src/cohort-topic/membership/verifier.d.ts.map +1 -1
- package/dist/src/cohort-topic/membership/verifier.js +138 -46
- package/dist/src/cohort-topic/membership/verifier.js.map +1 -1
- package/dist/src/cohort-topic/ports.d.ts +85 -14
- package/dist/src/cohort-topic/ports.d.ts.map +1 -1
- package/dist/src/cohort-topic/ports.js +1 -1
- package/dist/src/cohort-topic/ports.js.map +1 -1
- package/dist/src/cohort-topic/promotion.d.ts +3 -2
- package/dist/src/cohort-topic/promotion.d.ts.map +1 -1
- package/dist/src/cohort-topic/promotion.js +15 -3
- package/dist/src/cohort-topic/promotion.js.map +1 -1
- package/dist/src/cohort-topic/registration/renewal.d.ts +26 -5
- package/dist/src/cohort-topic/registration/renewal.d.ts.map +1 -1
- package/dist/src/cohort-topic/registration/renewal.js +71 -21
- package/dist/src/cohort-topic/registration/renewal.js.map +1 -1
- package/dist/src/cohort-topic/service.d.ts +34 -2
- package/dist/src/cohort-topic/service.d.ts.map +1 -1
- package/dist/src/cohort-topic/service.js +86 -28
- package/dist/src/cohort-topic/service.js.map +1 -1
- package/dist/src/cohort-topic/sig/payloads.d.ts +5 -1
- package/dist/src/cohort-topic/sig/payloads.d.ts.map +1 -1
- package/dist/src/cohort-topic/sig/payloads.js +6 -1
- package/dist/src/cohort-topic/sig/payloads.js.map +1 -1
- package/dist/src/cohort-topic/sig/threshold.d.ts +29 -4
- package/dist/src/cohort-topic/sig/threshold.d.ts.map +1 -1
- package/dist/src/cohort-topic/sig/threshold.js +39 -7
- package/dist/src/cohort-topic/sig/threshold.js.map +1 -1
- package/dist/src/cohort-topic/walk.d.ts +19 -4
- package/dist/src/cohort-topic/walk.d.ts.map +1 -1
- package/dist/src/cohort-topic/walk.js +29 -6
- package/dist/src/cohort-topic/walk.js.map +1 -1
- package/dist/src/cohort-topic/willingness.d.ts +17 -1
- package/dist/src/cohort-topic/willingness.d.ts.map +1 -1
- package/dist/src/cohort-topic/willingness.js +18 -3
- package/dist/src/cohort-topic/willingness.js.map +1 -1
- package/dist/src/cohort-topic/wire/index.d.ts +1 -1
- package/dist/src/cohort-topic/wire/index.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/index.js +1 -1
- package/dist/src/cohort-topic/wire/index.js.map +1 -1
- package/dist/src/cohort-topic/wire/payloads.d.ts +14 -0
- package/dist/src/cohort-topic/wire/payloads.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/payloads.js +20 -0
- package/dist/src/cohort-topic/wire/payloads.js.map +1 -1
- package/dist/src/cohort-topic/wire/primitives.d.ts +8 -0
- package/dist/src/cohort-topic/wire/primitives.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/primitives.js +24 -4
- package/dist/src/cohort-topic/wire/primitives.js.map +1 -1
- package/dist/src/cohort-topic/wire/types.d.ts +37 -0
- package/dist/src/cohort-topic/wire/types.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/validate.d.ts +9 -1
- package/dist/src/cohort-topic/wire/validate.d.ts.map +1 -1
- package/dist/src/cohort-topic/wire/validate.js +23 -4
- package/dist/src/cohort-topic/wire/validate.js.map +1 -1
- package/dist/src/reactivity/config.d.ts +9 -10
- package/dist/src/reactivity/config.d.ts.map +1 -1
- package/dist/src/reactivity/config.js +9 -9
- package/dist/src/reactivity/config.js.map +1 -1
- package/dist/src/reactivity/index.d.ts +4 -3
- package/dist/src/reactivity/index.d.ts.map +1 -1
- package/dist/src/reactivity/index.js +4 -3
- package/dist/src/reactivity/index.js.map +1 -1
- package/dist/src/reactivity/rotation.d.ts +73 -57
- package/dist/src/reactivity/rotation.d.ts.map +1 -1
- package/dist/src/reactivity/rotation.js +54 -54
- package/dist/src/reactivity/rotation.js.map +1 -1
- package/dist/src/reactivity/subscription.d.ts +12 -9
- package/dist/src/reactivity/subscription.d.ts.map +1 -1
- package/dist/src/reactivity/subscription.js +9 -6
- package/dist/src/reactivity/subscription.js.map +1 -1
- package/dist/src/reactivity/topic-anchor.d.ts +36 -31
- package/dist/src/reactivity/topic-anchor.d.ts.map +1 -1
- package/dist/src/reactivity/topic-anchor.js +41 -39
- package/dist/src/reactivity/topic-anchor.js.map +1 -1
- package/dist/src/reactivity/verify.d.ts +26 -9
- package/dist/src/reactivity/verify.d.ts.map +1 -1
- package/dist/src/reactivity/verify.js +26 -11
- package/dist/src/reactivity/verify.js.map +1 -1
- package/dist/src/reactivity/wire.d.ts +1 -1
- package/dist/src/reactivity/wire.d.ts.map +1 -1
- package/dist/src/transactor/change-notifier.d.ts +1 -1
- package/package.json +1 -1
- package/src/cohort-topic/addressing.ts +83 -23
- package/src/cohort-topic/member-engine.ts +77 -8
- package/src/cohort-topic/membership/publisher.ts +1 -1
- package/src/cohort-topic/membership/source.ts +4 -0
- package/src/cohort-topic/membership/verifier.ts +169 -51
- package/src/cohort-topic/ports.ts +87 -15
- package/src/cohort-topic/promotion.ts +15 -3
- package/src/cohort-topic/registration/renewal.ts +87 -24
- package/src/cohort-topic/service.ts +157 -35
- package/src/cohort-topic/sig/payloads.ts +7 -2
- package/src/cohort-topic/sig/threshold.ts +41 -7
- package/src/cohort-topic/walk.ts +46 -9
- package/src/cohort-topic/willingness.ts +34 -3
- package/src/cohort-topic/wire/index.ts +1 -0
- package/src/cohort-topic/wire/payloads.ts +21 -0
- package/src/cohort-topic/wire/primitives.ts +26 -4
- package/src/cohort-topic/wire/types.ts +37 -0
- package/src/cohort-topic/wire/validate.ts +26 -3
- package/src/reactivity/config.ts +10 -10
- package/src/reactivity/index.ts +4 -3
- package/src/reactivity/rotation.ts +86 -78
- package/src/reactivity/subscription.ts +12 -9
- package/src/reactivity/topic-anchor.ts +42 -45
- package/src/reactivity/verify.ts +36 -17
- package/src/reactivity/wire.ts +1 -1
- package/src/transactor/change-notifier.ts +1 -1
|
@@ -5,7 +5,10 @@
|
|
|
5
5
|
* a threshold-signed message:
|
|
6
6
|
*
|
|
7
7
|
* 1. takes the message's `signers`, the cohort `coord` the signers should belong to, and the tier;
|
|
8
|
-
* 2. looks up the cached `MembershipCertV1` for that coord (or pulls the source's `current`);
|
|
8
|
+
* 2. looks up the cached `MembershipCertV1` for that coord (or pulls the source's `current`); a
|
|
9
|
+
* fetched cert is considered only if its own `cohortCoord` names that coord — a cert for any other
|
|
10
|
+
* coord is treated as no cert, since the trust gate and the cache would otherwise be consulted for
|
|
11
|
+
* the coord the cert names rather than the one being verified;
|
|
9
12
|
* 3. checks the signers are a `≥ minSigs` subset of the cert's members and the signature verifies;
|
|
10
13
|
* 4. **on failure against a cached/stale cert, re-fetches the cert from any cohort member exactly
|
|
11
14
|
* once and retries**; still failing → the message is untrusted.
|
|
@@ -14,7 +17,8 @@
|
|
|
14
17
|
* is a `≥ minSigs` quorum over its own `members`) proves only internal well-formedness — *not* that the
|
|
15
18
|
* attesting key set is the legitimate cohort for the coord. An adversary controlling `k − x` keys could
|
|
16
19
|
* mint a self-consistent cert over a coord it does not own. So before a (re)fetched cert is believed,
|
|
17
|
-
* {@link CachingMembershipVerifier.
|
|
20
|
+
* the gate ({@link CachingMembershipVerifier.directVerdict}, then
|
|
21
|
+
* {@link CachingMembershipVerifier.certIsTrusted}) requires it to be self-consistent **AND** anchored by
|
|
18
22
|
* at least one of:
|
|
19
23
|
*
|
|
20
24
|
* - **Trust root** — `(coord, epoch, member-set)` is in the out-of-band-seeded {@link TrustRoot} set
|
|
@@ -33,23 +37,45 @@
|
|
|
33
37
|
* behavior, so there is strictly no regression on coords no node can verify today (distant T2/T3, and
|
|
34
38
|
* T0/T1 until the committed-index binding lands). Once a coord *does* hold a trusted cert, the chain
|
|
35
39
|
* governs successors: an un-anchored cert for an already-trusted coord is rejected (no TOFU downgrade),
|
|
36
|
-
* which is what gives the rotation chain its teeth.
|
|
37
|
-
* the
|
|
38
|
-
*
|
|
40
|
+
* which is what gives the rotation chain its teeth. Two direct-anchor bindings in db-p2p close parts of
|
|
41
|
+
* the gap: `FretTrustAnchor` judges a coord this node serves against its own ring view, and
|
|
42
|
+
* `CommitLogTrustAnchor` judges a reactivity root — a root-placed coord whose placement names its key —
|
|
43
|
+
* against the tail block's commit proof, fetched from the tail's storage group, so a distant subscriber
|
|
44
|
+
* is anchored too. What remains TOFU is a distant coord under neither (other T2/T3 coords a node does
|
|
45
|
+
* not serve, tracked in the backlog `...-fret-stabilization-proof`, and T0/T1 until
|
|
46
|
+
* `...-txlog-committed-binding`).
|
|
47
|
+
*
|
|
48
|
+
* **The gate waits only for the direct verdict.** `directAnchor` may return a promise (the commit-log
|
|
49
|
+
* anchor asks the network), so the gate is in two steps: {@link CachingMembershipVerifier.directVerdict}
|
|
50
|
+
* (self-consistency, trust roots, the direct anchor — nothing that reads per-coord state) is awaited by
|
|
51
|
+
* `loadFrom`, and {@link CachingMembershipVerifier.certIsTrusted} then decides synchronously. Everything
|
|
52
|
+
* that reads or writes the per-coord maps runs after that one `await`, in one synchronous turn with the
|
|
53
|
+
* cache write — see the comment at the `await`.
|
|
39
54
|
*
|
|
40
55
|
* **Deviation from the ticket sketch (documented):** `verifyMessage` takes the cohort `tier`. A coord
|
|
41
56
|
* is an opaque hash, so the T0/T1-vs-T2/T3 source dispatch the same ticket mandates cannot be derived
|
|
42
57
|
* from the coord alone; the caller already knows the tier (it computed the coord from the message's
|
|
43
58
|
* claimed tier/topic). The `tier` is threaded into the gate so the direct anchor is consulted with the
|
|
44
59
|
* same tier the router used (the binding is tier-scoped).
|
|
60
|
+
*
|
|
61
|
+
* **Root-placed coords (§Tier addressing → Root placement at a routing key).** Everything above says
|
|
62
|
+
* "`≥ minSigs`" for the node-wide threshold. The root of a root-placed topic is a different kind of
|
|
63
|
+
* cohort — the group responsible for a routing key, typically smaller than `minSigs` — so a caller that
|
|
64
|
+
* knows the coord is root-placed passes a {@link RootPlacement}, and the verifier then uses
|
|
65
|
+
* `ceil(members × quorumRatio)` of the cert being checked against for **every** threshold it applies at
|
|
66
|
+
* that coord: the cert's self-consistency, the rotation-chain quorum (over the predecessor's members),
|
|
67
|
+
* and the message itself. The ratio is the caller's own configuration, never read off a message or cert.
|
|
68
|
+
* The placement is also handed to the membership source and the direct anchor, which need it to find
|
|
69
|
+
* and judge the root group. A cached cert remembers the rule it was validated under, and a call under a
|
|
70
|
+
* different rule does not see it — see {@link CachingMembershipVerifier.heldUnder}.
|
|
45
71
|
*/
|
|
46
72
|
|
|
47
|
-
import type { IMembershipTrustAnchor, RingCoord, TrustRoot } from "../ports.js";
|
|
73
|
+
import type { IMembershipTrustAnchor, MembershipLookupOptions, RingCoord, RootPlacement, TrustAnchorVerdict, TrustRoot } from "../ports.js";
|
|
48
74
|
import { noAuthorityTrustAnchor } from "../ports.js";
|
|
49
75
|
import { b64urlToBytes, bytesToB64url, decodeMembershipCertV1 } from "../wire/codec.js";
|
|
50
76
|
import { CohortWireError } from "../wire/validate.js";
|
|
51
77
|
import type { MembershipCertV1 } from "../wire/types.js";
|
|
52
|
-
import { DEFAULT_MIN_SIGS, type CohortSigner } from "../sig/threshold.js";
|
|
78
|
+
import { DEFAULT_MIN_SIGS, rootPlacedMinSigs, type CohortSigner } from "../sig/threshold.js";
|
|
53
79
|
import { membershipCertSigningPayload } from "../sig/payloads.js";
|
|
54
80
|
import type { IMembershipSourceRouter } from "./source.js";
|
|
55
81
|
import { LruMap } from "../../utility/lru-map.js";
|
|
@@ -67,8 +93,12 @@ export type VerifyResult = "verified" | "untrusted";
|
|
|
67
93
|
|
|
68
94
|
/** Caches certs per coord and verifies threshold-signed messages with one stale-cert refetch. */
|
|
69
95
|
export interface MembershipVerifier {
|
|
70
|
-
/**
|
|
71
|
-
|
|
96
|
+
/**
|
|
97
|
+
* Cache `cert` as the latest known membership for its coord. `placement` is the rule the cert was
|
|
98
|
+
* published under — pass it for a root-placed coord, so later calls carrying the same placement use
|
|
99
|
+
* the entry; omit it for every other coord.
|
|
100
|
+
*/
|
|
101
|
+
cache(cert: MembershipCertV1, placement?: RootPlacement): void;
|
|
72
102
|
/**
|
|
73
103
|
* Drop everything cached for `cohortCoord` (base64url form, as on a cert's `cohortCoord`): the cached
|
|
74
104
|
* cert — including a *trusted* self-published one, i.e. the trust lock — and any stale-gap strike
|
|
@@ -88,8 +118,11 @@ export interface MembershipVerifier {
|
|
|
88
118
|
* Eventual refetch is *preserved*: a cold cache or a membership rotation still re-fetches once the
|
|
89
119
|
* interval elapses (unlike outright suppression). Omit `opts` (the default, and every existing caller)
|
|
90
120
|
* for the unbounded exactly-one-refetch behavior.
|
|
121
|
+
*
|
|
122
|
+
* `opts.placement` declares `expectedCoord` root-placed: the threshold is then
|
|
123
|
+
* `ceil(members × quorumRatio)` instead of the verifier's `minSigs` (see the module header).
|
|
91
124
|
*/
|
|
92
|
-
verifyMessage(signers: readonly Uint8Array[], expectedCoord: RingCoord, tier: number, payload: Uint8Array, sig: Uint8Array, opts?:
|
|
125
|
+
verifyMessage(signers: readonly Uint8Array[], expectedCoord: RingCoord, tier: number, payload: Uint8Array, sig: Uint8Array, opts?: VerifyMessageOptions): Promise<VerifyResult>;
|
|
93
126
|
}
|
|
94
127
|
|
|
95
128
|
/**
|
|
@@ -103,6 +136,16 @@ export interface RefetchBound {
|
|
|
103
136
|
readonly now?: number;
|
|
104
137
|
}
|
|
105
138
|
|
|
139
|
+
/** Per-call options of {@link MembershipVerifier.verifyMessage}: the refetch bound, plus the coord's placement. */
|
|
140
|
+
export interface VerifyMessageOptions extends RefetchBound {
|
|
141
|
+
/**
|
|
142
|
+
* Present when `expectedCoord` is the root of a root-placed topic. Its threshold is then
|
|
143
|
+
* `ceil(cert.members.length × quorumRatio)` — the formula a storage group's commit certificate uses —
|
|
144
|
+
* rather than the verifier's constructor `minSigs`. Build it with `createRootPlacement`.
|
|
145
|
+
*/
|
|
146
|
+
readonly placement?: RootPlacement;
|
|
147
|
+
}
|
|
148
|
+
|
|
106
149
|
export interface MembershipVerifierDeps {
|
|
107
150
|
signer: CohortSigner;
|
|
108
151
|
router: IMembershipSourceRouter;
|
|
@@ -154,6 +197,11 @@ interface CachedCert {
|
|
|
154
197
|
cert: MembershipCertV1;
|
|
155
198
|
/** True only when the cert passed via trust-root / direct-anchor / chain, or was self-published (`cache`). */
|
|
156
199
|
trusted: boolean;
|
|
200
|
+
/**
|
|
201
|
+
* The threshold rule the cert was validated (or self-published) under: the root-placement quorum ratio,
|
|
202
|
+
* or `undefined` for the default `minSigs` rule. See {@link CachingMembershipVerifier.heldUnder}.
|
|
203
|
+
*/
|
|
204
|
+
quorumRatio: number | undefined;
|
|
157
205
|
}
|
|
158
206
|
|
|
159
207
|
/** A {@link TrustRoot} pre-normalized to the cert's base64url form for cheap matching. */
|
|
@@ -200,10 +248,10 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
200
248
|
this.staleGapStrikes = new LruMap(maxCoords);
|
|
201
249
|
}
|
|
202
250
|
|
|
203
|
-
cache(cert: MembershipCertV1): void {
|
|
251
|
+
cache(cert: MembershipCertV1, placement?: RootPlacement): void {
|
|
204
252
|
// The public cache feeds this node its OWN freshly-published cert — a node trusts a cert it itself
|
|
205
253
|
// published, so it is marked trusted and may anchor the next rotation in the attestation chain.
|
|
206
|
-
this.byCoord.set(cert.cohortCoord, { cert, trusted: true });
|
|
254
|
+
this.byCoord.set(cert.cohortCoord, { cert, trusted: true, quorumRatio: placement?.quorumRatio });
|
|
207
255
|
}
|
|
208
256
|
|
|
209
257
|
forget(cohortCoord: string): void {
|
|
@@ -224,17 +272,20 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
224
272
|
this.staleGapStrikes.delete(cohortCoord);
|
|
225
273
|
}
|
|
226
274
|
|
|
227
|
-
async verifyMessage(signers: readonly Uint8Array[], expectedCoord: RingCoord, tier: number, payload: Uint8Array, sig: Uint8Array, opts?:
|
|
275
|
+
async verifyMessage(signers: readonly Uint8Array[], expectedCoord: RingCoord, tier: number, payload: Uint8Array, sig: Uint8Array, opts?: VerifyMessageOptions): Promise<VerifyResult> {
|
|
228
276
|
const coordKey = bytesToB64url(expectedCoord);
|
|
229
277
|
const source = this.deps.router.for(tier);
|
|
278
|
+
const placement = opts?.placement;
|
|
279
|
+
const lookup = lookupOptionsFor(placement);
|
|
230
280
|
|
|
231
281
|
// Seed from the cheap cached view if we hold nothing yet. A cached cert already passed the gate when
|
|
232
|
-
// it was loaded (or was self-published via `cache`), so it is used directly for message verification
|
|
233
|
-
|
|
282
|
+
// it was loaded (or was self-published via `cache`), so it is used directly for message verification
|
|
283
|
+
// — provided it passed under the rule this call applies (see `heldUnder`).
|
|
284
|
+
let cert = this.heldUnder(coordKey, placement)?.cert;
|
|
234
285
|
if (cert === undefined) {
|
|
235
|
-
cert = await this.loadFrom(source.current(expectedCoord), tier);
|
|
286
|
+
cert = await this.loadFrom(source.current(expectedCoord, lookup), coordKey, tier, placement);
|
|
236
287
|
}
|
|
237
|
-
if (cert !== undefined && this.messageVerifies(cert, signers, payload, sig)) {
|
|
288
|
+
if (cert !== undefined && this.messageVerifies(cert, signers, payload, sig, placement)) {
|
|
238
289
|
this.staleGapStrikes.delete(coordKey); // a verify resets the consecutive stale-gap strike count
|
|
239
290
|
return "verified";
|
|
240
291
|
}
|
|
@@ -247,14 +298,31 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
247
298
|
if (!this.refetchAllowed(coordKey, opts)) {
|
|
248
299
|
return "untrusted";
|
|
249
300
|
}
|
|
250
|
-
const refreshed = await this.loadFrom(source.fetch(expectedCoord), tier);
|
|
251
|
-
if (refreshed !== undefined && this.messageVerifies(refreshed, signers, payload, sig)) {
|
|
301
|
+
const refreshed = await this.loadFrom(source.fetch(expectedCoord, lookup), coordKey, tier, placement);
|
|
302
|
+
if (refreshed !== undefined && this.messageVerifies(refreshed, signers, payload, sig, placement)) {
|
|
252
303
|
this.staleGapStrikes.delete(coordKey); // a verify resets the consecutive stale-gap strike count
|
|
253
304
|
return "verified";
|
|
254
305
|
}
|
|
255
306
|
return "untrusted";
|
|
256
307
|
}
|
|
257
308
|
|
|
309
|
+
/**
|
|
310
|
+
* The cached entry for `coordKey`, **only if it was validated under the rule this call applies** — the
|
|
311
|
+
* same root-placement ratio, or both the default rule. An entry held under any other rule reads as
|
|
312
|
+
* absent, for every purpose: message verification, the attestation-chain predecessor, and the trust
|
|
313
|
+
* lock. So a cert that passed one threshold is never taken as having passed another, and the call
|
|
314
|
+
* re-validates from the source under its own rule instead.
|
|
315
|
+
*/
|
|
316
|
+
private heldUnder(coordKey: string, placement: RootPlacement | undefined): CachedCert | undefined {
|
|
317
|
+
const held = this.byCoord.get(coordKey);
|
|
318
|
+
return held !== undefined && held.quorumRatio === placement?.quorumRatio ? held : undefined;
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
/** The signature threshold over `cert`'s members: `ceil(members × quorumRatio)` for a root-placed coord, else the node-wide `minSigs`. */
|
|
322
|
+
private minSigsFor(cert: MembershipCertV1, placement: RootPlacement | undefined): number {
|
|
323
|
+
return placement === undefined ? this.minSigs : rootPlacedMinSigs(cert.members.length, placement);
|
|
324
|
+
}
|
|
325
|
+
|
|
258
326
|
/**
|
|
259
327
|
* Whether a `source.fetch()` refetch is permitted for `coordKey` now. Unbounded (always `true`) unless
|
|
260
328
|
* the caller supplies both `minRefetchIntervalMs` and `now`, in which case at most one refetch per coord
|
|
@@ -277,11 +345,14 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
277
345
|
|
|
278
346
|
/**
|
|
279
347
|
* Decode an encoded cert, run it through the trust gate, cache it (with its trusted status), and return
|
|
280
|
-
* it for message verification; `undefined` if absent, malformed,
|
|
281
|
-
* cert (failed self-consistency, a `"rejected"` direct anchor, or an
|
|
282
|
-
* already-trusted coord) is treated exactly like an absent cert, so the single
|
|
348
|
+
* it for message verification; `undefined` if absent, malformed, for a coord other than `coordKey`, or
|
|
349
|
+
* rejected by the gate. A rejected cert (failed self-consistency, a `"rejected"` direct anchor, or an
|
|
350
|
+
* un-anchored cert for an already-trusted coord) is treated exactly like an absent cert, so the single
|
|
351
|
+
* refetch still fires. The coord check runs before the gate: the gate, the direct anchor and the cache
|
|
352
|
+
* are all keyed on the cert's own `cohortCoord`, so a self-consistent cert for an unrelated coord would
|
|
353
|
+
* otherwise pass as trust-on-first-use there and then verify a message for `coordKey`.
|
|
283
354
|
*/
|
|
284
|
-
private async loadFrom(pending: Promise<Uint8Array | undefined>, tier: number): Promise<MembershipCertV1 | undefined> {
|
|
355
|
+
private async loadFrom(pending: Promise<Uint8Array | undefined>, coordKey: string, tier: number, placement: RootPlacement | undefined): Promise<MembershipCertV1 | undefined> {
|
|
285
356
|
const encoded = await pending;
|
|
286
357
|
if (encoded === undefined) {
|
|
287
358
|
return undefined;
|
|
@@ -290,7 +361,17 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
290
361
|
let trust: CertTrust;
|
|
291
362
|
try {
|
|
292
363
|
cert = decodeMembershipCertV1(encoded, this.deps.maxMessageBytes);
|
|
293
|
-
|
|
364
|
+
if (cert.cohortCoord !== coordKey) {
|
|
365
|
+
return undefined;
|
|
366
|
+
}
|
|
367
|
+
// The last `await` on the load path, and it has to be in this function. Two loads of one coord can
|
|
368
|
+
// be in flight across it, so everything that reads or writes `byCoord` / `staleGapStrikes` — the
|
|
369
|
+
// gate's chain, fallback and stale-gap recovery, then the `lockedUnderAnotherRule` read and the
|
|
370
|
+
// cache write below — runs after it in one synchronous turn. Awaiting an async gate here instead
|
|
371
|
+
// puts a microtask between the gate's reads and the write, and a second load's first-use check
|
|
372
|
+
// then misses the lock this load is about to write.
|
|
373
|
+
const direct = await this.directVerdict(cert, tier, placement);
|
|
374
|
+
trust = this.certIsTrusted(cert, direct, placement);
|
|
294
375
|
} catch (err) {
|
|
295
376
|
if (err instanceof CohortWireError) {
|
|
296
377
|
return undefined; // a malformed cert (or non-base64url signer) is treated as no cert
|
|
@@ -300,37 +381,68 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
300
381
|
if (trust === "reject") {
|
|
301
382
|
return undefined;
|
|
302
383
|
}
|
|
384
|
+
if (this.lockedUnderAnotherRule(cert.cohortCoord, placement)) {
|
|
385
|
+
return cert; // usable for this call's message check, but it must not displace the lock
|
|
386
|
+
}
|
|
303
387
|
// Only a `"trusted"` cert may anchor a successor in the attestation chain; a `"tofu"` cert is cached
|
|
304
388
|
// for message verification but must never launder trust into a rotation.
|
|
305
|
-
this.byCoord.set(cert.cohortCoord, { cert, trusted: trust === "trusted" });
|
|
389
|
+
this.byCoord.set(cert.cohortCoord, { cert, trusted: trust === "trusted", quorumRatio: placement?.quorumRatio });
|
|
306
390
|
return cert;
|
|
307
391
|
}
|
|
308
392
|
|
|
309
393
|
/**
|
|
310
|
-
*
|
|
311
|
-
*
|
|
312
|
-
*
|
|
313
|
-
*
|
|
394
|
+
* Whether the coord holds a **trusted** cert validated under a rule other than this call's. Such an entry
|
|
395
|
+
* is invisible to this call ({@link heldUnder}), so the trust gate ran as if the coord were cold and may
|
|
396
|
+
* have accepted the cert on first use. Caching that result would erase the trust lock through a side
|
|
397
|
+
* door — a call under one rule downgrading what another rule established — so it is used for the
|
|
398
|
+
* current message only.
|
|
399
|
+
*
|
|
400
|
+
* NOTE: a coord has one rule by construction (it follows from how the coord was derived), so two rules
|
|
401
|
+
* meeting at one coord is an anomaly, and the cost here — a source read on every call under the second
|
|
402
|
+
* rule — is not paid in normal operation. If it ever is, key the cache by `(coord, rule)` instead.
|
|
314
403
|
*/
|
|
315
|
-
private
|
|
316
|
-
|
|
317
|
-
|
|
404
|
+
private lockedUnderAnotherRule(coordKey: string, placement: RootPlacement | undefined): boolean {
|
|
405
|
+
const held = this.byCoord.get(coordKey);
|
|
406
|
+
return held !== undefined && held.trusted && held.quorumRatio !== placement?.quorumRatio;
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
/**
|
|
410
|
+
* The first step of the trust gate: what can be said of a cert without reading per-coord state. A cert
|
|
411
|
+
* that is not self-consistent is `"rejected"` (internal well-formedness is the precondition for any trust
|
|
412
|
+
* path), one matching a configured genesis root is `"anchored"` (authoritative, checked before the direct
|
|
413
|
+
* anchor), and otherwise the direct anchor decides. This is the only step that may wait — the anchor may
|
|
414
|
+
* ask the network — which is why it reads none of the per-coord maps: self-consistency is pure and the
|
|
415
|
+
* trust roots are fixed at construction. Keep it that way.
|
|
416
|
+
*/
|
|
417
|
+
private async directVerdict(cert: MembershipCertV1, tier: number, placement: RootPlacement | undefined): Promise<TrustAnchorVerdict> {
|
|
418
|
+
if (!this.certIsSelfConsistent(cert, placement)) {
|
|
419
|
+
return "rejected";
|
|
318
420
|
}
|
|
319
421
|
if (this.matchesTrustRoot(cert)) {
|
|
320
|
-
return "
|
|
422
|
+
return "anchored";
|
|
321
423
|
}
|
|
322
|
-
|
|
323
|
-
|
|
424
|
+
return this.anchor.directAnchor(cert, tier, placement);
|
|
425
|
+
}
|
|
426
|
+
|
|
427
|
+
/**
|
|
428
|
+
* The trust gate (see the module header), given the cert's {@link directVerdict}. A cert is accepted iff
|
|
429
|
+
* it is self-consistent **and** anchored by a trust root, the direct anchor, or the attestation chain;
|
|
430
|
+
* otherwise it falls to the interim TOFU fallback (first-use only). Returns whether the cert is a trusted
|
|
431
|
+
* anchor (`"trusted"`), an interim TOFU acceptance (`"tofu"`), or rejected (`"reject"`). Synchronous on
|
|
432
|
+
* purpose: it reads the per-coord maps, and `loadFrom` runs it in the same turn as its cache write.
|
|
433
|
+
*/
|
|
434
|
+
private certIsTrusted(cert: MembershipCertV1, direct: TrustAnchorVerdict, placement: RootPlacement | undefined): CertTrust {
|
|
435
|
+
if (direct === "anchored") {
|
|
324
436
|
return "trusted";
|
|
325
437
|
}
|
|
326
|
-
if (
|
|
438
|
+
if (direct === "rejected") {
|
|
327
439
|
return "reject"; // a contradicted binding is a forgery — fatal, overrides the TOFU fallback
|
|
328
440
|
}
|
|
329
|
-
//
|
|
330
|
-
if (this.hasRotationAttestation(cert) && this.chainGrantsTrust(cert)) {
|
|
441
|
+
// direct === "unknown": no local authority for this coord. Try the attestation chain, else fall back.
|
|
442
|
+
if (this.hasRotationAttestation(cert) && this.chainGrantsTrust(cert, placement)) {
|
|
331
443
|
return "trusted";
|
|
332
444
|
}
|
|
333
|
-
const fallback = this.fallbackTrust(cert);
|
|
445
|
+
const fallback = this.fallbackTrust(cert, placement);
|
|
334
446
|
if (fallback !== "reject") {
|
|
335
447
|
return fallback; // first-use TOFU (coord not locked): no stale lock to recover from
|
|
336
448
|
}
|
|
@@ -338,7 +450,7 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
338
450
|
// did not chain-verify — the state that strands a former cohort member forever. Consult the stale-gap
|
|
339
451
|
// recovery counter, which releases the lock only on a demonstrated chain gap (never a forged rotation
|
|
340
452
|
// off the current predecessor). See {@link staleGapRecovery}.
|
|
341
|
-
return this.staleGapRecovery(cert);
|
|
453
|
+
return this.staleGapRecovery(cert, placement);
|
|
342
454
|
}
|
|
343
455
|
|
|
344
456
|
/**
|
|
@@ -361,9 +473,9 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
361
473
|
* reach the source, so a {@link RefetchBound}-suppressed refetch observes no cert and recovery paces itself
|
|
362
474
|
* with the (bounded) refetch rate — intended, do not "fix" that pacing.
|
|
363
475
|
*/
|
|
364
|
-
private staleGapRecovery(cert: MembershipCertV1): CertTrust {
|
|
476
|
+
private staleGapRecovery(cert: MembershipCertV1, placement: RootPlacement | undefined): CertTrust {
|
|
365
477
|
const coordKey = cert.cohortCoord;
|
|
366
|
-
const locked = this.
|
|
478
|
+
const locked = this.heldUnder(coordKey, placement);
|
|
367
479
|
// Recovery-eligible only on an explicit rotation gap: a full attestation whose prevEpoch is neither the
|
|
368
480
|
// cert's own epoch (a self-referential rotation) nor the cached trusted epoch (a forgery off the current
|
|
369
481
|
// predecessor — the case the lock exists to reject).
|
|
@@ -394,8 +506,8 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
394
506
|
* cert (a failed/absent rotation, including a forged rotation off a trusted predecessor) is **rejected**
|
|
395
507
|
* — no silent TOFU downgrade — which is what gives the attestation chain its teeth.
|
|
396
508
|
*/
|
|
397
|
-
private fallbackTrust(cert: MembershipCertV1): CertTrust {
|
|
398
|
-
return this.
|
|
509
|
+
private fallbackTrust(cert: MembershipCertV1, placement: RootPlacement | undefined): CertTrust {
|
|
510
|
+
return this.heldUnder(cert.cohortCoord, placement)?.trusted ? "reject" : "tofu";
|
|
399
511
|
}
|
|
400
512
|
|
|
401
513
|
/** Whether a cert carries a full rotation attestation (all three fields; validated all-or-nothing on the wire). */
|
|
@@ -409,12 +521,12 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
409
521
|
* quorum over this cert's signing payload via `rotationSig`. A predecessor that only reached the cache via
|
|
410
522
|
* TOFU (not trusted) must not anchor the successor — the trusted-cache invariant.
|
|
411
523
|
*/
|
|
412
|
-
private chainGrantsTrust(cert: MembershipCertV1): boolean {
|
|
524
|
+
private chainGrantsTrust(cert: MembershipCertV1, placement: RootPlacement | undefined): boolean {
|
|
413
525
|
const prevEpoch = cert.prevEpoch!;
|
|
414
526
|
if (prevEpoch === cert.cohortEpoch) {
|
|
415
527
|
return false; // a cert cannot rotate from itself
|
|
416
528
|
}
|
|
417
|
-
const predecessor = this.
|
|
529
|
+
const predecessor = this.heldUnder(cert.cohortCoord, placement);
|
|
418
530
|
if (predecessor === undefined || !predecessor.trusted || predecessor.cert.cohortEpoch !== prevEpoch) {
|
|
419
531
|
return false;
|
|
420
532
|
}
|
|
@@ -425,7 +537,8 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
425
537
|
b64urlToBytes(cert.rotationSig!),
|
|
426
538
|
cert.rotationSigners!.map((s) => b64urlToBytes(s)),
|
|
427
539
|
predecessor.cert,
|
|
428
|
-
|
|
540
|
+
// The rotation is signed by the PREDECESSOR cohort, so the quorum is counted over its members.
|
|
541
|
+
this.minSigsFor(predecessor.cert, placement),
|
|
429
542
|
);
|
|
430
543
|
}
|
|
431
544
|
|
|
@@ -440,7 +553,7 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
440
553
|
}
|
|
441
554
|
|
|
442
555
|
/** A cert is self-consistent only if its own threshold signature is a valid quorum of its members. */
|
|
443
|
-
private certIsSelfConsistent(cert: MembershipCertV1): boolean {
|
|
556
|
+
private certIsSelfConsistent(cert: MembershipCertV1, placement: RootPlacement | undefined): boolean {
|
|
444
557
|
// `signers` is validated only as a string array (not per-element base64url), so `b64urlToBytes`
|
|
445
558
|
// below may throw `CohortWireError` on a malformed signer — `loadFrom`'s try/catch turns that
|
|
446
559
|
// into "no cert" rather than letting it escape.
|
|
@@ -449,15 +562,20 @@ class CachingMembershipVerifier implements MembershipVerifier {
|
|
|
449
562
|
b64urlToBytes(cert.thresholdSig),
|
|
450
563
|
cert.signers.map((s) => b64urlToBytes(s)),
|
|
451
564
|
cert,
|
|
452
|
-
this.
|
|
565
|
+
this.minSigsFor(cert, placement),
|
|
453
566
|
);
|
|
454
567
|
}
|
|
455
568
|
|
|
456
|
-
private messageVerifies(cert: MembershipCertV1, signers: readonly Uint8Array[], payload: Uint8Array, sig: Uint8Array): boolean {
|
|
457
|
-
return this.deps.signer.verifyThreshold(payload, sig, signers, cert, this.
|
|
569
|
+
private messageVerifies(cert: MembershipCertV1, signers: readonly Uint8Array[], payload: Uint8Array, sig: Uint8Array, placement: RootPlacement | undefined): boolean {
|
|
570
|
+
return this.deps.signer.verifyThreshold(payload, sig, signers, cert, this.minSigsFor(cert, placement));
|
|
458
571
|
}
|
|
459
572
|
}
|
|
460
573
|
|
|
574
|
+
/** The membership-source options for a call: `{ rootPlaced: true }` under a placement, none otherwise. */
|
|
575
|
+
function lookupOptionsFor(placement: RootPlacement | undefined): MembershipLookupOptions | undefined {
|
|
576
|
+
return placement === undefined ? undefined : { rootPlaced: true };
|
|
577
|
+
}
|
|
578
|
+
|
|
461
579
|
/** Pre-normalize a {@link TrustRoot} (raw bytes) to the cert's base64url form for cheap matching. */
|
|
462
580
|
function normalizeTrustRoot(root: TrustRoot): NormalizedTrustRoot {
|
|
463
581
|
return {
|
|
@@ -22,6 +22,21 @@ import type { MembershipCertV1 } from "./wire/types.js";
|
|
|
22
22
|
*/
|
|
23
23
|
export type RingCoord = Uint8Array;
|
|
24
24
|
|
|
25
|
+
declare const topicRouteKeyBrand: unique symbol;
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* The bytes a cohort-topic frame is routed on: FRET hashes them exactly once into the cohort's ring
|
|
29
|
+
* coordinate. FRET's `routeAct` hashes the key it is handed — at the origin and again at every forwarding
|
|
30
|
+
* hop — so handing it a coordinate lands the frame at the hash of that coordinate, a ring position no
|
|
31
|
+
* cohort serves. Branded so the only way to obtain one is `TierAddressing.routeKey`, which builds the
|
|
32
|
+
* preimage of `TierAddressing.coord` for the same inputs; a {@link RingCoord} does not type-check where a
|
|
33
|
+
* route key belongs.
|
|
34
|
+
*
|
|
35
|
+
* A separate brand from `RoutingKey` (`network/routing-key.ts`): that one is obtainable only from a block
|
|
36
|
+
* id, and these preimages are not block keys.
|
|
37
|
+
*/
|
|
38
|
+
export type TopicRouteKey = Uint8Array & { readonly [topicRouteKeyBrand]: true };
|
|
39
|
+
|
|
25
40
|
/** A peer, referenced only by its opaque byte-array id. No multiaddr, no libp2p PeerId here. */
|
|
26
41
|
export interface PeerRef {
|
|
27
42
|
readonly id: Uint8Array;
|
|
@@ -33,13 +48,57 @@ export interface PeerRef {
|
|
|
33
48
|
*/
|
|
34
49
|
export interface ITopicRouter {
|
|
35
50
|
/**
|
|
36
|
-
* Route `activity` to the cohort
|
|
37
|
-
* collecting up to `wantK` participants and at least `minSigs` signatures.
|
|
51
|
+
* Route `activity` to the cohort at `H(key)` and run the cohort's activity callback,
|
|
52
|
+
* collecting up to `wantK` participants and at least `minSigs` signatures. The router hashes `key`
|
|
53
|
+
* once; build it with `TierAddressing.routeKey` so that hash is the tier's coordinate.
|
|
38
54
|
* @returns the encoded cohort reply.
|
|
39
55
|
*/
|
|
40
|
-
routeAndAct(key:
|
|
56
|
+
routeAndAct(key: TopicRouteKey, activity: Uint8Array, opts: { wantK: number; minSigs: number }): Promise<Uint8Array>;
|
|
41
57
|
/** Direct dial to a cached primary; falls back to {@link routeAndAct} on failure (caller decides). */
|
|
42
58
|
dialMember(member: PeerRef, activity: Uint8Array): Promise<Uint8Array>;
|
|
59
|
+
/**
|
|
60
|
+
* Deliver `activity` to the **root group** of a root-placed topic — the peers responsible for
|
|
61
|
+
* `rootKey` — and return the encoded reply. Optional: the walk uses it for the tier-0 step of a
|
|
62
|
+
* root-placed topic when the router has it, and otherwise falls back to ring routing on the root key,
|
|
63
|
+
* which reaches the root coordinate `H(rootKey)`.
|
|
64
|
+
*
|
|
65
|
+
* It exists because the two can disagree: `routeAndAct` lands on the ring's nearest peer to the
|
|
66
|
+
* coordinate, which on a ring shared with another network may be a peer of that other network, whereas
|
|
67
|
+
* the root group is chosen by the rule storage placement uses. db-p2p binds this to the key network.
|
|
68
|
+
*/
|
|
69
|
+
routeToRoot?(rootKey: Uint8Array, activity: Uint8Array): Promise<Uint8Array>;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* The per-coord rule for a **root-placed** cohort — the root of a topic whose tier-0 coordinate is
|
|
74
|
+
* `H(rootKey)` (see `addressing.ts`). Such a cohort is the group of peers responsible for the root key
|
|
75
|
+
* rather than the FRET cohort of `wantK`, so the node-wide `minSigs` does not describe it: its signature
|
|
76
|
+
* threshold is `ceil(memberCount × quorumRatio)`.
|
|
77
|
+
*
|
|
78
|
+
* `quorumRatio` is always the **verifying node's own** configuration, never a value read off a message or
|
|
79
|
+
* a certificate. Build one with `createRootPlacement` (`sig/threshold.ts`), which rejects a ratio outside
|
|
80
|
+
* `(0, 1]`.
|
|
81
|
+
*/
|
|
82
|
+
export interface RootPlacement {
|
|
83
|
+
/** Fraction of a root-placed cohort's members whose signatures make a quorum, in `(0, 1]`. */
|
|
84
|
+
readonly quorumRatio: number;
|
|
85
|
+
/**
|
|
86
|
+
* The routing key whose ring position is the root coordinate, when the caller knows it — for a reactivity
|
|
87
|
+
* root, the tail block's routing key (`routingKeyForBlock(tailId)`, the raw UTF-8 of the id). A direct
|
|
88
|
+
* anchor that can locate the group's own commit record from the key (db-p2p's commit-log anchor) needs it;
|
|
89
|
+
* one that cannot ignores it. It takes no part in cache identity: a coordinate is the hash of its key, so
|
|
90
|
+
* one coordinate has one key, and the verifier keys its cache by `quorumRatio` alone.
|
|
91
|
+
*/
|
|
92
|
+
readonly rootKey?: Uint8Array;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** Options for a membership-cert lookup ({@link IMembershipSource}). */
|
|
96
|
+
export interface MembershipLookupOptions {
|
|
97
|
+
/**
|
|
98
|
+
* The coord is the root of a root-placed topic, so its cert is held by (and must be fetched from) the
|
|
99
|
+
* root group rather than the FRET cohort around the coord.
|
|
100
|
+
*/
|
|
101
|
+
readonly rootPlaced?: true;
|
|
43
102
|
}
|
|
44
103
|
|
|
45
104
|
/** Intra-cohort gossip transport (FRET cohort gossip underneath). */
|
|
@@ -53,9 +112,9 @@ export interface ICohortGossipTransport {
|
|
|
53
112
|
/** Authoritative cohort membership snapshots (FRET `MembershipCertV1` / stabilization underneath). */
|
|
54
113
|
export interface IMembershipSource {
|
|
55
114
|
/** Current cached membership cert for `coord`, encoded; `undefined` if none is cached. */
|
|
56
|
-
current(coord: RingCoord): Promise<Uint8Array | undefined>;
|
|
115
|
+
current(coord: RingCoord, opts?: MembershipLookupOptions): Promise<Uint8Array | undefined>;
|
|
57
116
|
/** Force one refresh of `coord`'s membership cert (stale-cache retry); encoded, or `undefined`. */
|
|
58
|
-
fetch(coord: RingCoord): Promise<Uint8Array | undefined>;
|
|
117
|
+
fetch(coord: RingCoord, opts?: MembershipLookupOptions): Promise<Uint8Array | undefined>;
|
|
59
118
|
}
|
|
60
119
|
|
|
61
120
|
/**
|
|
@@ -77,10 +136,11 @@ export interface ICohortThresholdCrypto {
|
|
|
77
136
|
/**
|
|
78
137
|
* Sink the cohort uses to publish a `MembershipCertV1` (over FRET's `/membership` protocol).
|
|
79
138
|
* db-core's publisher builds + threshold-signs the cert and hands it here; db-p2p serves it.
|
|
139
|
+
* A node serves one cohort per coordinate it is in, so a cert is published under its coordinate.
|
|
80
140
|
*/
|
|
81
141
|
export interface IMembershipPublishSink {
|
|
82
|
-
/** Publish (advertise/serve) an already-signed membership certificate, encoded
|
|
83
|
-
publish(encodedCert: Uint8Array): void;
|
|
142
|
+
/** Publish (advertise/serve) an already-signed membership certificate, encoded, for cohort coord `coord`. */
|
|
143
|
+
publish(coord: RingCoord, encodedCert: Uint8Array): void;
|
|
84
144
|
}
|
|
85
145
|
|
|
86
146
|
/** Network-size estimate feeding `d_max`. */
|
|
@@ -106,15 +166,27 @@ export type TrustAnchorVerdict = "anchored" | "rejected" | "unknown";
|
|
|
106
166
|
* Direct (base-case) trust anchor for a {@link MembershipCertV1}'s `coord → keyset` binding.
|
|
107
167
|
*
|
|
108
168
|
* db-core owns the chain-of-attestations and trust-root logic; the **direct** anchor is
|
|
109
|
-
* tier/transport-specific
|
|
110
|
-
*
|
|
111
|
-
*
|
|
112
|
-
*
|
|
113
|
-
*
|
|
169
|
+
* tier/transport-specific and is therefore delegated through this port. db-p2p binds two: the FRET ring
|
|
170
|
+
* agreement for a coord this node serves (`FretTrustAnchor`), and, for a reactivity root — a root-placed
|
|
171
|
+
* coord whose placement names its key — the tail block's own commit proof, fetched from the tail's storage
|
|
172
|
+
* group (`CommitLogTrustAnchor`); the host asks the first and falls through to the second on `"unknown"`.
|
|
173
|
+
* **db-core never imports FRET.** A node with no authority for the coord returns `"unknown"` so the
|
|
174
|
+
* verifier falls through to the chain / interim fallback instead of breaking distant verification. See
|
|
175
|
+
* {@link noAuthorityTrustAnchor} for the db-core default (every coord `"unknown"`).
|
|
176
|
+
*
|
|
177
|
+
* **The verdict may be asynchronous.** An anchor that judges from local state answers synchronously; one
|
|
178
|
+
* that has to ask the network (the commit-log anchor) returns a promise, and the verifier's trust gate
|
|
179
|
+
* awaits either. An anchor is total: it never throws or rejects, and answers `"unknown"` for anything it
|
|
180
|
+
* cannot decode or reach.
|
|
114
181
|
*/
|
|
115
182
|
export interface IMembershipTrustAnchor {
|
|
116
|
-
/**
|
|
117
|
-
|
|
183
|
+
/**
|
|
184
|
+
* Judge, from a directly-trusted source, whether `cert.members` is authoritative for `cert.cohortCoord`
|
|
185
|
+
* at `tier`. `placement` is present when the verifier was told the coord is root-placed, so the anchor
|
|
186
|
+
* compares against the root group (and its threshold) rather than the FRET cohort around the coord; its
|
|
187
|
+
* `rootKey`, when the caller knew it, is what lets an anchor locate that group's own records.
|
|
188
|
+
*/
|
|
189
|
+
directAnchor(cert: MembershipCertV1, tier: number, placement?: RootPlacement): TrustAnchorVerdict | Promise<TrustAnchorVerdict>;
|
|
118
190
|
}
|
|
119
191
|
|
|
120
192
|
/**
|
|
@@ -139,7 +211,7 @@ export interface TrustRoot {
|
|
|
139
211
|
* the interim TOFU behavior (no regression) until db-p2p binds a real anchor.
|
|
140
212
|
*/
|
|
141
213
|
export const noAuthorityTrustAnchor: IMembershipTrustAnchor = {
|
|
142
|
-
directAnchor(_cert: MembershipCertV1, _tier: number): TrustAnchorVerdict {
|
|
214
|
+
directAnchor(_cert: MembershipCertV1, _tier: number, _placement?: RootPlacement): TrustAnchorVerdict {
|
|
143
215
|
return "unknown";
|
|
144
216
|
},
|
|
145
217
|
};
|
|
@@ -12,8 +12,9 @@
|
|
|
12
12
|
* - `directParticipants(T) ≥ cap_promote` (64), OR
|
|
13
13
|
* - `loadBucket[tier(T)] ≥ bucket_overload` (6) AND `directParticipants(T) ≥ cap_promote_fast` (32)
|
|
14
14
|
* — the hot-load fast path from the capacity-barometer ticket, OR
|
|
15
|
-
* - the growth **slope** predicts crossing `cap_promote`
|
|
16
|
-
* early to avoid the gossip-lag overshoot (`§Promotion`:
|
|
15
|
+
* - `directParticipants(T) > cap_demote` (16) AND the growth **slope** predicts crossing `cap_promote`
|
|
16
|
+
* within `T_promote_lookahead` (30s) — fires early to avoid the gossip-lag overshoot (`§Promotion`:
|
|
17
|
+
* pre-promotion on slope); the floor keeps a burst of a few arrivals from reading as a flood.
|
|
17
18
|
*
|
|
18
19
|
* Once promoted, the state is **sticky** for ≥ `T_promote_sticky` (60s) before it can be reconsidered
|
|
19
20
|
* for demotion, so transient count drops don't flap a cohort back to accepting.
|
|
@@ -318,7 +319,13 @@ class CohortPromotionLifecycle implements PromotionLifecycle {
|
|
|
318
319
|
if (this.deps.loadBucket(topicId) >= this.bucketOverload && count >= this.capPromoteFast) {
|
|
319
320
|
return true;
|
|
320
321
|
}
|
|
321
|
-
|
|
322
|
+
// The slope trigger is floored at cap_demote. Pre-promotion exists to avoid overshooting cap_promote
|
|
323
|
+
// under gossip lag, which only matters near the cap; a promotion at or below cap_demote would put the
|
|
324
|
+
// cohort in a state the demotion rule already calls under-loaded (contradicting the cap_promote /
|
|
325
|
+
// cap_demote hysteresis), and two or three samples in under a second are noise, not a growth rate.
|
|
326
|
+
// Without the floor, two registrations < ~0.5 s apart promoted a root a small network can never serve
|
|
327
|
+
// past — the root never demotes, so every later watcher was redirected to an unformable tier 1.
|
|
328
|
+
return count > this.capDemote && this.slopePredictsCrossing(state, count);
|
|
322
329
|
}
|
|
323
330
|
|
|
324
331
|
/**
|
|
@@ -350,6 +357,11 @@ class CohortPromotionLifecycle implements PromotionLifecycle {
|
|
|
350
357
|
// NOTE: no guard here against fromTier === DEFAULT_D_MAX_CAP (60). At that depth toTier = 61 exceeds the
|
|
351
358
|
// tree-tier ceiling, so validatePromotionNoticeV1 rejects the notice on every receiver. Unreachable today
|
|
352
359
|
// (tree tier 60 is pathological); if the tree can ever reach the cap, gate promotion below the cap here.
|
|
360
|
+
// NOTE: promotion assumes tier fromTier+1 can form a cohort that signs at minSigs. With the defaults no trigger fires at or
|
|
361
|
+
// below cap_demote distinct participants, which implies enough peers only while participants are peers
|
|
362
|
+
// willing to serve that tier and cap_demote ≥ minSigs; if either stops holding (an edge-heavy network
|
|
363
|
+
// whose edge profiles keep deeper-tier willingness off, or a lowered cap_demote), gate promotion on the
|
|
364
|
+
// network-size estimate.
|
|
353
365
|
const topicB64 = bytesToB64url(topicId);
|
|
354
366
|
const epochB64 = bytesToB64url(this.deps.cohortEpoch());
|
|
355
367
|
const cohortB64 = bytesToB64url(this.deps.cohortCoord());
|