@optimystic/db-core 1.25.0 → 1.27.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.
Files changed (74) hide show
  1. package/dist/src/cluster/structs.d.ts +10 -0
  2. package/dist/src/cluster/structs.d.ts.map +1 -1
  3. package/dist/src/cohort-topic/addressing.d.ts +26 -2
  4. package/dist/src/cohort-topic/addressing.d.ts.map +1 -1
  5. package/dist/src/cohort-topic/addressing.js +35 -4
  6. package/dist/src/cohort-topic/addressing.js.map +1 -1
  7. package/dist/src/cohort-topic/member-engine.d.ts +17 -10
  8. package/dist/src/cohort-topic/member-engine.d.ts.map +1 -1
  9. package/dist/src/cohort-topic/member-engine.js +20 -18
  10. package/dist/src/cohort-topic/member-engine.js.map +1 -1
  11. package/dist/src/cohort-topic/registration/renewal.d.ts +21 -14
  12. package/dist/src/cohort-topic/registration/renewal.d.ts.map +1 -1
  13. package/dist/src/cohort-topic/registration/renewal.js +38 -28
  14. package/dist/src/cohort-topic/registration/renewal.js.map +1 -1
  15. package/dist/src/collection/collection.d.ts +123 -34
  16. package/dist/src/collection/collection.d.ts.map +1 -1
  17. package/dist/src/collection/collection.js +231 -74
  18. package/dist/src/collection/collection.js.map +1 -1
  19. package/dist/src/collection/segments.d.ts +71 -14
  20. package/dist/src/collection/segments.d.ts.map +1 -1
  21. package/dist/src/collection/segments.js +94 -14
  22. package/dist/src/collection/segments.js.map +1 -1
  23. package/dist/src/network/i-key-network.d.ts +28 -0
  24. package/dist/src/network/i-key-network.d.ts.map +1 -1
  25. package/dist/src/network/i-repo.d.ts +16 -0
  26. package/dist/src/network/i-repo.d.ts.map +1 -1
  27. package/dist/src/offline/queue.d.ts +13 -0
  28. package/dist/src/offline/queue.d.ts.map +1 -1
  29. package/dist/src/offline/queue.js +22 -3
  30. package/dist/src/offline/queue.js.map +1 -1
  31. package/dist/src/reactivity/topic-anchor.d.ts.map +1 -1
  32. package/dist/src/reactivity/topic-anchor.js +20 -2
  33. package/dist/src/reactivity/topic-anchor.js.map +1 -1
  34. package/dist/src/transaction/coordinator.d.ts +1 -1
  35. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  36. package/dist/src/transaction/coordinator.js +15 -16
  37. package/dist/src/transaction/coordinator.js.map +1 -1
  38. package/dist/src/transactor/network-transactor.d.ts +16 -3
  39. package/dist/src/transactor/network-transactor.d.ts.map +1 -1
  40. package/dist/src/transactor/network-transactor.js +22 -5
  41. package/dist/src/transactor/network-transactor.js.map +1 -1
  42. package/dist/src/transform/atomic.d.ts +8 -2
  43. package/dist/src/transform/atomic.d.ts.map +1 -1
  44. package/dist/src/transform/atomic.js +10 -4
  45. package/dist/src/transform/atomic.js.map +1 -1
  46. package/dist/src/transform/helpers.d.ts +29 -3
  47. package/dist/src/transform/helpers.d.ts.map +1 -1
  48. package/dist/src/transform/helpers.js +62 -3
  49. package/dist/src/transform/helpers.js.map +1 -1
  50. package/dist/src/transform/tracker.d.ts +57 -5
  51. package/dist/src/transform/tracker.d.ts.map +1 -1
  52. package/dist/src/transform/tracker.js +111 -11
  53. package/dist/src/transform/tracker.js.map +1 -1
  54. package/dist/src/utility/expiring-lru-map.d.ts +16 -0
  55. package/dist/src/utility/expiring-lru-map.d.ts.map +1 -0
  56. package/dist/src/utility/expiring-lru-map.js +39 -0
  57. package/dist/src/utility/expiring-lru-map.js.map +1 -0
  58. package/package.json +1 -1
  59. package/src/cluster/structs.ts +10 -0
  60. package/src/cohort-topic/addressing.ts +42 -4
  61. package/src/cohort-topic/member-engine.ts +35 -28
  62. package/src/cohort-topic/registration/renewal.ts +62 -42
  63. package/src/collection/collection.ts +3462 -3272
  64. package/src/collection/segments.ts +140 -22
  65. package/src/network/i-key-network.ts +30 -0
  66. package/src/network/i-repo.ts +16 -0
  67. package/src/offline/queue.ts +23 -3
  68. package/src/reactivity/topic-anchor.ts +23 -3
  69. package/src/transaction/coordinator.ts +15 -16
  70. package/src/transactor/network-transactor.ts +24 -6
  71. package/src/transform/atomic.ts +12 -5
  72. package/src/transform/helpers.ts +61 -3
  73. package/src/transform/tracker.ts +110 -12
  74. package/src/utility/expiring-lru-map.ts +42 -0
@@ -369,16 +369,6 @@ export interface RenewalCohortSideDeps {
369
369
  * when this returns `true` `onRenew` touches and serves instead of replying `primary_moved`.
370
370
  */
371
371
  isServing?: (topicId: Uint8Array, participantId: Uint8Array) => boolean;
372
- /**
373
- * Optional participant peer-key signature verifier (db-p2p binds it to the peer-sig primitive over
374
- * {@link import("../wire/payloads.js").renewSigningPayload}). It gates the two privileged
375
- * participant-attested paths: a `reattach` promotion and a `withdraw` eviction. A renew on either path
376
- * whose signature does not verify against the claimed `participantId` must never act — a stray/MITM'd
377
- * ping cannot usurp a live primary or evict someone else's registration (§TTL and renewal). Absent →
378
- * the gate is skipped (unit tests run without peer crypto); plain pings are never verified here (they
379
- * only touch `lastPing`).
380
- */
381
- verifyParticipantSig?: (renew: RenewV1) => boolean;
382
372
  /**
383
373
  * Optional freshness window for the two privileged, participant-attested paths (`withdraw` eviction and
384
374
  * `reattach` promotion). The renew signature already binds `timestamp` (see
@@ -389,17 +379,37 @@ export interface RenewalCohortSideDeps {
389
379
  * using state already on the record. Defaults to the register-path skew constants
390
380
  * ({@link DEFAULT_REPLAY_MAX_AGE_MS} / {@link DEFAULT_REPLAY_MAX_FUTURE_SKEW_MS}); db-p2p wires the same
391
381
  * `{ maxAgeMs, maxFutureSkewMs }` config the register path's replay guard consumes so an operator tuning
392
- * the skew window moves both paths together. Absent → defaults (key-less unit tests and callers work
393
- * unchanged, matching how {@link verifyParticipantSig} is optional). Plain pings are NOT gated (a
394
- * replayed ping is low-harm — it only re-touches `lastPing`).
382
+ * the skew window moves both paths together. Absent → defaults. Plain pings are NOT gated (a replayed
383
+ * ping is low-harm — it only re-touches `lastPing`).
395
384
  */
396
385
  freshness?: { maxAgeMs?: number; maxFutureSkewMs?: number };
397
386
  }
398
387
 
388
+ /** A withdraw or re-attach, the two renews whose signature matters. */
389
+ export function isPrivilegedRenew(msg: RenewV1): boolean {
390
+ return msg.withdraw === true || msg.reattach === true;
391
+ }
392
+
399
393
  /** Cohort-side TTL handling: touch on renew, redirect on rotation, sweep stale records. */
400
394
  export interface RenewalCohortSide {
401
- /** Handle an inbound renew. Touches the record, or replies `primary_moved` if this member is no longer primary. */
395
+ /**
396
+ * Handle an inbound renew. Touches the record, or replies `primary_moved` if this member is no longer primary.
397
+ *
398
+ * **The caller has authenticated `msg`.** This side checks no signature, so a withdraw or re-attach reaching
399
+ * here acts if it is fresh: a live-signer host verifies a remote one first and asks
400
+ * {@link refusalBeforeSignature} and {@link refuseUnauthenticated} for the answers around that wait, and a
401
+ * key-less host hands every frame over unchecked. A plain ping has no signature check anywhere: it only
402
+ * touches `lastPing`.
403
+ */
402
404
  onRenew(msg: RenewV1, now: number): RenewReplyV1;
405
+ /**
406
+ * The answer the privileged `msg` gets whatever its signature says: no record, or it fails the freshness gate.
407
+ * Undefined: the signature decides. A stale frame and a forged one get the same answer, so asking first changes
408
+ * no reply.
409
+ */
410
+ refusalBeforeSignature(msg: RenewV1, now: number): RenewReplyV1 | undefined;
411
+ /** The opaque answer to a privileged renew whose signature failed. */
412
+ refuseUnauthenticated(msg: RenewV1): RenewReplyV1;
403
413
  /** Evict every stale record and gossip each eviction; returns the evicted set. */
404
414
  sweepStale(now: number): readonly RegistrationRecord[];
405
415
  }
@@ -459,27 +469,20 @@ class StoreRenewalCohortSide implements RenewalCohortSide {
459
469
  const participantId = b64(msg.participantId);
460
470
  const rec = this.deps.store.getByParticipant(topicId, participantId);
461
471
  if (rec === undefined) {
462
- return { v: 1, result: "unknown_registration" };
472
+ return this.refusalFor(msg, rec);
473
+ }
474
+ // Freshness gate: a signed withdraw or re-attach is valid forever without this, so a captured one could be
475
+ // replayed to evict a *fresh* record (after the victim's expired and it re-registered) or to force bogus
476
+ // primary re-stamps. A stale or replayed frame gets the answer a forged one gets, and never acts.
477
+ if (isPrivilegedRenew(msg) && !this.isFreshPrivileged(msg, rec, now)) {
478
+ return this.refusalFor(msg, rec);
463
479
  }
464
480
  const key = recordKey(topicId, participantId);
465
481
 
466
482
  if (msg.withdraw === true) {
467
- // Signed leave attestation. A forged/missing signature must never evict someone else's
468
- // registration → ignore, revealing nothing (`unknown_registration`, the same opaque answer a
469
- // non-existent record gets). The gate is absent in key-less unit mode, matching reattach.
470
- // `withdraw` is checked before the slot/primary computation: a withdraw needs no slot or
471
- // primary check (any holder evicts its replica), and it takes precedence over a (malformed)
483
+ // Signed leave attestation. `withdraw` is checked before the slot/primary computation: a withdraw needs
484
+ // no slot or primary check (any holder evicts its replica), and it takes precedence over a (malformed)
472
485
  // co-set `reattach` — a record being withdrawn is gone regardless of a promotion request.
473
- if (this.deps.verifyParticipantSig?.(msg) === false) {
474
- return { v: 1, result: "unknown_registration" };
475
- }
476
- // Freshness gate: a signed withdraw is valid forever without this, so a captured one could be
477
- // replayed after the victim's record TTL-expires and re-registers, evicting the *fresh* record.
478
- // Reject a stale/replayed frame with the same opaque `unknown_registration` the forged-sig branch
479
- // returns above — indistinguishable from an untrusted frame — and never delete.
480
- if (!this.isFreshPrivileged(msg, rec, now)) {
481
- return { v: 1, result: "unknown_registration" };
482
- }
483
486
  this.deps.store.delete(topicId, participantId);
484
487
  this.failoverServing.delete(key); // mirror sweepStale: drop any crash-failover override
485
488
  this.deps.gossip.evicted(rec);
@@ -491,18 +494,8 @@ class StoreRenewalCohortSide implements RenewalCohortSide {
491
494
  const self = this.deps.self;
492
495
 
493
496
  if (msg.reattach === true) {
494
- // Crash-failover promotion request (participant attests primary unreachable). The signed
495
- // `reattach` flag is what a backup trusts to promote itself, so a missing/forged signature
496
- // must never escalate: fall through to a plain redirect (never promote).
497
- if (this.deps.verifyParticipantSig?.(msg) === false) {
498
- return this.primaryMoved(primary, backups, cohortEpoch);
499
- }
500
- // Freshness gate: a signed reattach is valid forever without this, so a captured one could be
501
- // replayed to force bogus primary re-stamps. Reject a stale/replayed frame with the same redirect
502
- // the forged-sig branch returns above — revealing nothing — and never promote.
503
- if (!this.isFreshPrivileged(msg, rec, now)) {
504
- return this.primaryMoved(primary, backups, cohortEpoch);
505
- }
497
+ // Crash-failover promotion request (participant attests primary unreachable). The signed `reattach`
498
+ // flag is what a backup trusts to promote itself, which is why the caller authenticates it first.
506
499
  if (bytesEqual(primary, self)) {
507
500
  // A rotation already made this member the computed primary; serve, no override needed.
508
501
  return this.touchAndServe(rec, now);
@@ -550,6 +543,33 @@ class StoreRenewalCohortSide implements RenewalCohortSide {
550
543
  return this.primaryMoved(primary, backups, cohortEpoch);
551
544
  }
552
545
 
546
+ refusalBeforeSignature(msg: RenewV1, now: number): RenewReplyV1 | undefined {
547
+ const rec = this.heldRecordFor(msg);
548
+ return rec !== undefined && this.isFreshPrivileged(msg, rec, now) ? undefined : this.refusalFor(msg, rec);
549
+ }
550
+
551
+ refuseUnauthenticated(msg: RenewV1): RenewReplyV1 {
552
+ return this.refusalFor(msg, this.heldRecordFor(msg));
553
+ }
554
+
555
+ private heldRecordFor(msg: RenewV1): RegistrationRecord | undefined {
556
+ return this.deps.store.getByParticipant(b64(msg.topicId), b64(msg.participantId));
557
+ }
558
+
559
+ /**
560
+ * What a renew that may not act is told, revealing nothing about why. No record or a withdraw (judged before a
561
+ * co-set `reattach`) gets `unknown_registration`, the answer a non-existent record gets. A re-attach gets a plain
562
+ * redirect to the current assignment, and the participant carries on with its failover.
563
+ */
564
+ private refusalFor(msg: RenewV1, rec: RegistrationRecord | undefined): RenewReplyV1 {
565
+ if (rec === undefined || msg.withdraw === true) {
566
+ return { v: 1, result: "unknown_registration" };
567
+ }
568
+ const { members, cohortEpoch } = this.deps.cohort();
569
+ const { primary, backups } = this.deps.slots.assignSlots(rec.participantId, cohortEpoch, members);
570
+ return this.primaryMoved(primary, backups, cohortEpoch);
571
+ }
572
+
553
573
  /** Existing touch path: stamp `lastPing`, gossip the touch, reply `ok`. */
554
574
  private touchAndServe(rec: RegistrationRecord, now: number): RenewReplyV1 {
555
575
  const touched: RegistrationRecord = { ...rec, lastPing: now };