@peerbit/pubsub 5.3.12 → 5.4.1

package/dist/src/index.js

@@ -1,11 +1,12 @@
 import {} from "@libp2p/interface";
-import { PublicSignKey, getPublicKeyFromPeerId } from "@peerbit/crypto";
+import { PublicSignKey, getPublicKeyFromPeerId, sha256Sync, } from "@peerbit/crypto";
 import { logger as loggerFn } from "@peerbit/logger";
-import { assertCanonicalTopicRootCandidates, assertTopicRootCandidatesFrame, DataEvent, GetSubscribers, isCanonicalTopicRootCandidate, PeerUnavailable, PubSubData, PubSubMessage, PublishEvent, Subscribe, SubscriptionData, SubscriptionEvent, TOPIC_ROOT_CANDIDATES_MAX, TopicRootCandidates, TopicRootQuery, TopicRootQueryResponse, UnsubcriptionEvent, Unsubscribe, } from "@peerbit/pubsub-interface";
+import { DataEvent, GetSubscribers, PeerUnavailable, PubSubData, PubSubMessage, PublishEvent, Subscribe, SubscriptionData, SubscriptionEvent, TOPIC_ROOT_CANDIDATES_MAX, TOPIC_ROOT_CANDIDATE_CLAIMS_MAX, TOPIC_ROOT_CANDIDATE_CLAIM_MAX_BYTES, TopicRootCandidateClaims, TopicRootCandidates, TopicRootQuery, TopicRootQueryResponse, UnsubcriptionEvent, Unsubscribe, assertCanonicalTopicRootCandidates, assertTopicRootCandidatesFrame, isCanonicalTopicRootCandidate, } from "@peerbit/pubsub-interface";
 import { DirectStream, } from "@peerbit/stream";
 import { AcknowledgeAnyWhere, AcknowledgeDelivery, AnyWhere, DataMessage, DeliveryError, MessageHeader, NotStartedError, SilentDelivery, deliveryModeHasReceiver, getMsgId, isAcknowledgeAnyWhereDeliveryMode, isAcknowledgeDeliveryMode, isAnyWhereDeliveryMode, isSilentDeliveryMode, } from "@peerbit/stream-interface";
 import { AbortError, TimeoutError, delay } from "@peerbit/time";
 import { Uint8ArrayList } from "uint8arraylist";
+import { equals as bytesEqual } from "uint8arrays";
 import { toUint8Array } from "./bytes.js";
 import { debouncedAccumulatorSetCounter, } from "./debounced-set.js";
 import { FanoutChannel } from "./fanout-channel.js";
@@ -112,6 +113,25 @@ const DEFAULT_PUBSUB_SHARD_COUNT = 256;
 const PUBSUB_SHARD_COUNT_HARD_CAP = 16_384;
 const DEFAULT_PUBSUB_SHARD_TOPIC_PREFIX = "/peerbit/pubsub-shard/1/";
 const AUTO_TOPIC_ROOT_CANDIDATE_UPDATE_COOLDOWN_MS = 2_000;
+const TOPIC_CONTROL_PLANE_PROTOCOL_V2_1 = "/peerbit/topic-control-plane/2.1.0";
+const TOPIC_CONTROL_PLANE_PROTOCOL_V2_0 = "/peerbit/topic-control-plane/2.0.0";
+const TOPIC_ROOT_CANDIDATE_CLAIM_DOMAIN = utf8Encoder.encode("peerbit/topic-root-candidate-claim/v1\0");
+const TOPIC_ROOT_CANDIDATE_SCOPE_DOMAIN = "peerbit/topic-root-candidate-scope/v1";
+const TOPIC_ROOT_CANDIDATE_CLAIM_LIFETIME_MS = 90_000;
+const TOPIC_ROOT_CANDIDATE_CLAIM_FUTURE_SKEW_MS = 30_000;
+const TOPIC_ROOT_CANDIDATE_CLAIM_RECEIVER_MAX_LIFETIME_MS = TOPIC_ROOT_CANDIDATE_CLAIM_LIFETIME_MS +
+    TOPIC_ROOT_CANDIDATE_CLAIM_FUTURE_SKEW_MS;
+const TOPIC_ROOT_CANDIDATE_CLAIM_REFRESH_MS = 30_000;
+const TOPIC_ROOT_CANDIDATE_CLAIM_REFRESH_JITTER_MS = 5_000;
+const TOPIC_ROOT_CANDIDATE_CLAIM_REFRESH_RETRY_MS = 1_000;
+const TOPIC_ROOT_CANDIDATE_CLAIM_ADVERTISEMENT_TIMEOUT_MS = 10_000;
+// A sparse leaf can receive a 64-origin snapshot plus two refresh waves through
+// one relay in the first minute. Keep per-relay headroom for that honest burst;
+// the separate global cap still bounds total signature work.
+const TOPIC_ROOT_CANDIDATE_CLAIM_VERIFY_BURST = 256;
+const TOPIC_ROOT_CANDIDATE_CLAIM_GLOBAL_VERIFY_BURST = 512;
+const TOPIC_ROOT_CANDIDATE_CLAIM_VERIFY_REFILL_MS = 60_000;
+const TOPIC_ROOT_CANDIDATE_CLAIM_VERIFY_PEERS_MAX = 4_096;
 const sameCandidates = (left, right) => left.length === right.length &&
     left.every((candidate, index) => candidate === right[index]);
 // Topic-root queries may need to wait for the responder to finish opening an
@@ -169,6 +189,7 @@ export class TopicControlPlane extends DirectStream {
     debounceUnsubscribeAggregator;
     shardCount;
     shardTopicPrefix;
+    topicRootCandidateClaimData;
     hostShards;
     shardRootCache = new Map();
     shardTopicCache = new Map();
@@ -196,16 +217,27 @@ export class TopicControlPlane extends DirectStream {
     topicRootCandidateResolutionAbortController = new AbortController();
     hostOwnedShardRootsInFlight;
     hostOwnedShardRootsDirty = false;
-    autoCandidatesBroadcastTimers = [];
-    autoCandidatesGossipInterval;
-    autoCandidatesGossipUntil = 0;
+    signedTopicRootCandidateClaims = new Map();
+    // Active claims expire, but their per-origin timestamp floors survive for the
+    // auto-mode lifecycle so a frozen wall clock cannot renew a replayed lease.
+    // Retaining only the deterministic lowest origins keeps this state hard-bounded.
+    topicRootCandidateClaimReplayFloors = new Map();
+    localSignedTopicRootCandidateClaim;
+    topicRootCandidateClaimMaintenanceTimer;
+    topicRootCandidateClaimRefreshNotBefore;
+    topicRootCandidateClaimMaintenanceRefreshInFlight;
+    topicRootCandidateClaimVerifyBudgets = new Map();
+    topicRootCandidateClaimGlobalVerifyBudget = {
+        remaining: TOPIC_ROOT_CANDIDATE_CLAIM_GLOBAL_VERIFY_BURST,
+        refilledAt: Date.now(),
+    };
     _onFanoutPeerUnreachable;
     fanoutChannels = new Map();
     ensureFanoutChannelInFlight = new Map();
     pendingTopicRootQueries = new Map();
     nextTopicRootQueryId = 1;
     constructor(components, props) {
-        super(components, ["/peerbit/topic-control-plane/2.0.0"], props);
+        super(components, [TOPIC_CONTROL_PLANE_PROTOCOL_V2_1, TOPIC_CONTROL_PLANE_PROTOCOL_V2_0], props);
         this.subscriptions = new Map();
         this.pendingSubscriptions = new Set();
         this.topics = new Map();
@@ -223,8 +255,8 @@ export class TopicControlPlane extends DirectStream {
         }
         this.fanout = props.fanout;
         // Default to a local-only shard-root candidate set so standalone peers can
-        // subscribe/publish without explicit bootstraps. We'll expand candidates
-        // opportunistically as neighbours connect.
+        // subscribe/publish without explicit bootstraps. Signed peer claims expand
+        // the set opportunistically as the ad-hoc overlay connects.
         if (this.topicRootControlPlane.getTopicRootCandidates().length === 0) {
             this.autoTopicRootCandidates = true;
             this.autoTopicRootCandidateSet = new Set([this.publicKeyHash]);
@@ -234,6 +266,14 @@ export class TopicControlPlane extends DirectStream {
         this.shardCount = Math.min(PUBSUB_SHARD_COUNT_HARD_CAP, Math.max(1, Math.floor(requestedShardCount)));
         const prefix = props?.shardTopicPrefix ?? DEFAULT_PUBSUB_SHARD_TOPIC_PREFIX;
         this.shardTopicPrefix = prefix.endsWith("/") ? prefix : prefix + "/";
+        const scopeDigest = sha256Sync(utf8Encoder.encode(JSON.stringify([
+            TOPIC_ROOT_CANDIDATE_SCOPE_DOMAIN,
+            this.shardTopicPrefix,
+            this.shardCount,
+        ])));
+        this.topicRootCandidateClaimData = new Uint8Array(TOPIC_ROOT_CANDIDATE_CLAIM_DOMAIN.byteLength + scopeDigest.byteLength);
+        this.topicRootCandidateClaimData.set(TOPIC_ROOT_CANDIDATE_CLAIM_DOMAIN, 0);
+        this.topicRootCandidateClaimData.set(scopeDigest, TOPIC_ROOT_CANDIDATE_CLAIM_DOMAIN.byteLength);
         this.hostShards = props?.hostShards ?? false;
         const baseFanoutChannelOptions = {
             ...DEFAULT_PUBSUB_FANOUT_CHANNEL_OPTIONS,
@@ -282,25 +322,20 @@ export class TopicControlPlane extends DirectStream {
      * candidate mode.
      *
      * Auto mode is a convenience for small ad-hoc networks where no bootstraps/
-     * routers are configured. When an explicit candidate set is provided (e.g.
-     * from bootstraps or a test harness), we must stop mutating/gossiping the
+     * routers are configured. Automatic claims authenticate key ownership and
+     * freshness, not liveness, admission, or Sybil resistance; hostile or isolated
+     * deployments should configure explicit candidates. When an explicit candidate
+     * set is provided (e.g. from bootstraps or a test harness), we stop mutating the
      * candidate set; otherwise shard root resolution can diverge and overlays can
      * partition (especially in sparse graphs).
      */
     setTopicRootCandidates(candidates) {
         this.topicRootControlPlane.setTopicRootCandidates(candidates);
-        // Disable auto mode and stop its background gossip/timers.
+        // Disable auto mode and clear its signed-claim state/timers.
         this.autoTopicRootCandidates = false;
         this.autoTopicRootCandidateSet = undefined;
+        this.clearSignedTopicRootCandidateState();
         this.clearAutoTopicRootCandidateUpdateSchedule();
-        for (const t of this.autoCandidatesBroadcastTimers)
-            clearTimeout(t);
-        this.autoCandidatesBroadcastTimers = [];
-        if (this.autoCandidatesGossipInterval) {
-            clearInterval(this.autoCandidatesGossipInterval);
-            this.autoCandidatesGossipInterval = undefined;
-        }
-        this.autoCandidatesGossipUntil = 0;
         // Re-resolve roots under the new mapping.
         this.shardRootCache.clear();
         // Only candidates can become deterministic roots. Avoid doing a full shard
@@ -311,16 +346,39 @@ export class TopicControlPlane extends DirectStream {
         this.scheduleReconcileShardOverlays();
     }
     async start() {
+        // Match DirectStream's idempotent start guard before mutating automatic
+        // candidates. In particular, a repeated start must not restore unsigned
+        // self while a signed-protocol peer is connected.
+        if (this.started)
+            return;
         this.topicControlPlaneStopping = false;
+        if (this.autoTopicRootCandidates &&
+            !this.localSignedTopicRootCandidateClaim) {
+            this.autoTopicRootCandidateSet = new Set([this.publicKeyHash]);
+            this.topicRootControlPlane.setTopicRootCandidates([this.publicKeyHash]);
+            this.shardRootCache.clear();
+        }
         if (this.topicRootResolutionAbortController.signal.aborted) {
             this.topicRootResolutionAbortController = new AbortController();
         }
         await this.fanout.start();
         this._onFanoutPeerUnreachable =
-            this._onFanoutPeerUnreachable ||
-                this.onFanoutPeerUnreachable.bind(this);
+            this._onFanoutPeerUnreachable || this.onFanoutPeerUnreachable.bind(this);
         await this.fanout.addEventListener("fanout:peer-unreachable", this._onFanoutPeerUnreachable);
         await super.start();
+        if (this.autoTopicRootCandidates) {
+            let retryDelayMs = 0;
+            try {
+                if (!(await this.refreshLocalTopicRootCandidateClaim())) {
+                    retryDelayMs = TOPIC_ROOT_CANDIDATE_CLAIM_REFRESH_RETRY_MS;
+                }
+            }
+            catch (error) {
+                logErrorIfStarted(error);
+                retryDelayMs = TOPIC_ROOT_CANDIDATE_CLAIM_REFRESH_RETRY_MS;
+            }
+            this.scheduleTopicRootCandidateClaimMaintenance(retryDelayMs);
+        }
         if (this.hostShards) {
             await this.hostShardRootsNow();
         }
@@ -335,6 +393,7 @@ export class TopicControlPlane extends DirectStream {
         this.topicControlPlaneStopping = true;
         this.topicRootResolutionAbortController.abort(new AbortError("topic control plane stopped"));
         this.clearAutoTopicRootCandidateUpdateSchedule();
+        this.clearSignedTopicRootCandidateState();
         this.topicControlPlaneLifecycleRevision += 1;
         this.reconcileShardOverlaysDirty = false;
         for (const opening of this.ensureFanoutChannelInFlight.values()) {
@@ -373,14 +432,6 @@ export class TopicControlPlane extends DirectStream {
             }
         }
         this.fanoutChannels.clear();
-        for (const t of this.autoCandidatesBroadcastTimers)
-            clearTimeout(t);
-        this.autoCandidatesBroadcastTimers = [];
-        if (this.autoCandidatesGossipInterval) {
-            clearInterval(this.autoCandidatesGossipInterval);
-            this.autoCandidatesGossipInterval = undefined;
-        }
-        this.autoCandidatesGossipUntil = 0;
         this.hostOwnedShardRootsDirty = false;
         this.subscriptions.clear();
         this.pendingSubscriptions.clear();
@@ -405,33 +456,54 @@ export class TopicControlPlane extends DirectStream {
         await super.stop();
         this.reconcileShardOverlaysDirty = false;
     }
-    async onPeerConnected(peerId, connection) {
-        await super.onPeerConnected(peerId, connection);
-        // If we're in auto-candidate mode, expand the deterministic shard-root
-        // candidate set as neighbours connect, then reconcile shard overlays and
-        // re-announce subscriptions so membership knowledge converges.
-        if (!this.autoTopicRootCandidates)
-            return;
-        let peerHash;
-        try {
-            peerHash = getPublicKeyFromPeerId(peerId).hashcode();
-        }
-        catch {
-            return;
-        }
-        void this.maybeUpdateAutoTopicRootCandidates(peerHash);
-    }
+    // Candidate trust starts only after protocol negotiation in `addPeer()`;
+    // a transport connection alone cannot bypass signed 2.1 self-claims.
     // Ensure auto-candidate mode converges even when libp2p topology callbacks
     // are delayed or only fire for one side of a connection. `addPeer()` runs for
     // both inbound + outbound protocol streams once the remote public key is known.
     addPeer(peerId, publicKey, protocol, connId) {
+        const hadSignedPeer = [...this.peers.values()].some((peer) => peer.protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_1);
+        const existingPeer = this.peers.get(publicKey.hashcode());
         const peer = super.addPeer(peerId, publicKey, protocol, connId);
         if (this.autoTopicRootCandidates) {
-            void this.maybeUpdateAutoTopicRootCandidates(publicKey.hashcode());
-            this.scheduleAutoTopicRootCandidatesBroadcast([peer]);
+            const hasSignedPeer = [...this.peers.values()].some((candidate) => candidate.protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_1);
+            this.rebuildAutoTopicRootCandidatesFromClaims(BigInt(Date.now()), {
+                immediate: hadSignedPeer !== hasSignedPeer,
+            });
+            if (peer.protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_1) {
+                const sendWhenOutboundReady = () => {
+                    if (!this.autoTopicRootCandidates ||
+                        this.peers.get(publicKey.hashcode()) !== peer) {
+                        return;
+                    }
+                    void this.sendAutoTopicRootCandidates([peer]).catch(() => { });
+                };
+                if (peer.isWritable) {
+                    void this.sendAutoTopicRootCandidates([peer]).catch(() => { });
+                }
+                if (!existingPeer) {
+                    peer.addEventListener("stream:outbound", sendWhenOutboundReady);
+                    peer.addEventListener("close", () => peer.removeEventListener("stream:outbound", sendWhenOutboundReady), { once: true });
+                }
+            }
         }
         return peer;
     }
+    async _removePeer(publicKey) {
+        const hash = publicKey.hashcode();
+        const protocol = this.peers.get(hash)?.protocol;
+        const hadSignedPeer = [...this.peers.values()].some((peer) => peer.protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_1);
+        const removed = await super._removePeer(publicKey);
+        if (this.autoTopicRootCandidates &&
+            (protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_0 ||
+                protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_1)) {
+            const hasSignedPeer = [...this.peers.values()].some((peer) => peer.protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_1);
+            this.rebuildAutoTopicRootCandidatesFromClaims(BigInt(Date.now()), {
+                immediate: hadSignedPeer !== hasSignedPeer,
+            });
+        }
+        return removed;
+    }
     maybeDisableAutoTopicRootCandidatesIfExternallyConfigured() {
         if (!this.autoTopicRootCandidates)
             return false;
@@ -446,6 +518,7 @@ export class TopicControlPlane extends DirectStream {
         // intact and reconcile shard overlays under the new mapping.
         this.autoTopicRootCandidates = false;
         this.autoTopicRootCandidateSet = undefined;
+        this.clearSignedTopicRootCandidateState();
         this.clearAutoTopicRootCandidateUpdateSchedule();
         this.shardRootCache.clear();
         // Ensure we host any shard roots we're now responsible for. This is important
@@ -456,114 +529,493 @@ export class TopicControlPlane extends DirectStream {
         this.scheduleReconcileShardOverlays();
         return true;
     }
-    maybeUpdateAutoTopicRootCandidates(peerHash) {
-        if (!this.autoTopicRootCandidates)
-            return;
-        if (!isCanonicalTopicRootCandidate(peerHash) ||
-            peerHash === this.publicKeyHash)
-            return;
-        this.queueAutoTopicRootCandidateUpdate([peerHash]);
+    clearTopicRootCandidateClaimTimer() {
+        if (this.topicRootCandidateClaimMaintenanceTimer) {
+            clearTimeout(this.topicRootCandidateClaimMaintenanceTimer);
+            this.topicRootCandidateClaimMaintenanceTimer = undefined;
+        }
+    }
+    clearSignedTopicRootCandidateState() {
+        this.clearTopicRootCandidateClaimTimer();
+        this.signedTopicRootCandidateClaims.clear();
+        this.topicRootCandidateClaimReplayFloors.clear();
+        this.localSignedTopicRootCandidateClaim = undefined;
+        this.topicRootCandidateClaimRefreshNotBefore = undefined;
+        this.topicRootCandidateClaimMaintenanceRefreshInFlight = undefined;
+        this.topicRootCandidateClaimVerifyBudgets.clear();
+        this.topicRootCandidateClaimGlobalVerifyBudget = {
+            remaining: TOPIC_ROOT_CANDIDATE_CLAIM_GLOBAL_VERIFY_BURST,
+            refilledAt: Date.now(),
+        };
     }
-    normalizeAutoTopicRootCandidates(candidates) {
-        const canonicalCandidates = candidates.filter(isCanonicalTopicRootCandidate);
-        if (this.nativeTopicControl) {
-            return this.nativeTopicControl.normalizeAutoCandidates(canonicalCandidates, this.publicKeyHash);
+    isTopicRootCandidateClaimTimeValid(timestamp, expires, now) {
+        return (expires > now &&
+            timestamp <= now + BigInt(TOPIC_ROOT_CANDIDATE_CLAIM_FUTURE_SKEW_MS) &&
+            expires - timestamp === BigInt(TOPIC_ROOT_CANDIDATE_CLAIM_LIFETIME_MS));
+    }
+    topicRootCandidateClaimAcceptanceDeadline(timestamp, expires, wallNow, monotonicNow, maxRemainingMs) {
+        if (!this.isTopicRootCandidateClaimTimeValid(timestamp, expires, wallNow)) {
+            return undefined;
+        }
+        return (monotonicNow +
+            Math.min(Number(expires - wallNow), Math.max(0, maxRemainingMs)));
+    }
+    async refreshLocalTopicRootCandidateClaim() {
+        if (!this.autoTopicRootCandidates ||
+            !this.started ||
+            this.stopping ||
+            this.topicControlPlaneStopping) {
+            return false;
+        }
+        if (!this.canRetainTopicRootCandidateClaimOrigin(this.publicKeyHash)) {
+            return false;
         }
-        const unique = new Set();
-        for (const c of canonicalCandidates) {
-            unique.add(c);
+        const lifecycleRevision = this.topicControlPlaneLifecycleRevision;
+        const claim = await this.createMessage(this.topicRootCandidateClaimData, {
+            mode: new AnyWhere(),
+            priority: 1,
+            expiresInMs: TOPIC_ROOT_CANDIDATE_CLAIM_LIFETIME_MS,
+            skipRecipientValidation: true,
+        });
+        const bytes = toUint8Array(claim.bytes());
+        if (bytes.byteLength > TOPIC_ROOT_CANDIDATE_CLAIM_MAX_BYTES) {
+            throw new Error(`Local topic-root candidate claim exceeds ${TOPIC_ROOT_CANDIDATE_CLAIM_MAX_BYTES} bytes`);
         }
-        if (isCanonicalTopicRootCandidate(this.publicKeyHash)) {
-            unique.add(this.publicKeyHash);
+        if (lifecycleRevision !== this.topicControlPlaneLifecycleRevision ||
+            !this.autoTopicRootCandidates ||
+            !this.started ||
+            this.stopping ||
+            this.topicControlPlaneStopping) {
+            return false;
         }
-        const sorted = [...unique].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-        return sorted.slice(0, TOPIC_ROOT_CANDIDATES_MAX);
+        const timestamp = claim.header.timestamp;
+        const expires = claim.header.expires;
+        const acceptanceDeadline = this.topicRootCandidateClaimAcceptanceDeadline(timestamp, expires, BigInt(Date.now()), performance.now(), TOPIC_ROOT_CANDIDATE_CLAIM_LIFETIME_MS);
+        if (acceptanceDeadline === undefined) {
+            return false;
+        }
+        const record = {
+            bytes,
+            timestamp,
+            expires,
+            acceptUntil: acceptanceDeadline,
+        };
+        const current = this.localSignedTopicRootCandidateClaim;
+        if (current && record.timestamp <= current.timestamp) {
+            return false;
+        }
+        if (!this.retainSignedTopicRootCandidateClaim(this.publicKeyHash, record)) {
+            return false;
+        }
+        this.localSignedTopicRootCandidateClaim = record;
+        this.topicRootCandidateClaimRefreshNotBefore = undefined;
+        this.rebuildAutoTopicRootCandidatesFromClaims();
+        return this.localSignedTopicRootCandidateClaim === record;
     }
-    scheduleAutoTopicRootCandidatesBroadcast(targets) {
-        if (!this.autoTopicRootCandidates)
-            return;
-        if (!this.started || this.stopping)
-            return;
-        if (targets && targets.length > 0) {
-            void this.sendAutoTopicRootCandidates(targets).catch(() => { });
+    scheduleTopicRootCandidateClaimMaintenance(minDelayMs = 0) {
+        if (!this.autoTopicRootCandidates ||
+            !this.started ||
+            this.stopping ||
+            this.topicControlPlaneStopping) {
             return;
         }
-        for (const t of this.autoCandidatesBroadcastTimers)
-            clearTimeout(t);
-        this.autoCandidatesBroadcastTimers = [];
-        // Burst a few times to survive early "stream not writable yet" races.
-        const delays = [25, 500, 2_000];
-        for (const delayMs of delays) {
-            const t = setTimeout(() => {
-                void this.sendAutoTopicRootCandidates().catch(() => { });
-            }, delayMs);
-            t.unref?.();
-            this.autoCandidatesBroadcastTimers.push(t);
-        }
-        // Keep gossiping for a while after changes so partially connected topologies
-        // converge even under slow stream negotiation.
-        this.autoCandidatesGossipUntil = Date.now() + 60_000;
-        this.ensureAutoCandidatesGossipInterval();
-    }
-    ensureAutoCandidatesGossipInterval() {
-        if (!this.autoTopicRootCandidates)
-            return;
-        if (!this.started || this.stopping)
-            return;
-        if (this.autoCandidatesGossipInterval)
-            return;
-        this.autoCandidatesGossipInterval = setInterval(() => {
-            if (!this.started || this.stopping || !this.autoTopicRootCandidates)
+        this.clearTopicRootCandidateClaimTimer();
+        const now = Date.now();
+        const monotonicNow = performance.now();
+        const local = this.localSignedTopicRootCandidateClaim;
+        const localOriginEligible = this.canRetainTopicRootCandidateClaimOrigin(this.publicKeyHash);
+        if (localOriginEligible && minDelayMs > 0) {
+            this.topicRootCandidateClaimRefreshNotBefore = Math.max(this.topicRootCandidateClaimRefreshNotBefore ?? 0, monotonicNow + minDelayMs);
+        }
+        else if (!localOriginEligible) {
+            this.topicRootCandidateClaimRefreshNotBefore = undefined;
+        }
+        const canScheduleLocalRefresh = localOriginEligible &&
+            !this.topicRootCandidateClaimMaintenanceRefreshInFlight;
+        const refreshDueAt = local
+            ? Number(local.timestamp) +
+                TOPIC_ROOT_CANDIDATE_CLAIM_REFRESH_MS +
+                Math.floor(Math.random() * TOPIC_ROOT_CANDIDATE_CLAIM_REFRESH_JITTER_MS)
+            : canScheduleLocalRefresh
+                ? now
+                : Number.POSITIVE_INFINITY;
+        let expiryDelayMs = Number.POSITIVE_INFINITY;
+        for (const claim of this.signedTopicRootCandidateClaims.values()) {
+            expiryDelayMs = Math.min(expiryDelayMs, Number(claim.expires) - now, claim.acceptUntil - monotonicNow);
+        }
+        if (local) {
+            expiryDelayMs = Math.min(expiryDelayMs, Number(local.expires) - now, local.acceptUntil - monotonicNow);
+        }
+        const refreshDelayMs = canScheduleLocalRefresh
+            ? Math.max(refreshDueAt - now, (this.topicRootCandidateClaimRefreshNotBefore ?? monotonicNow) -
+                monotonicNow, 0)
+            : Number.POSITIVE_INFINITY;
+        expiryDelayMs = Math.max(Math.ceil(expiryDelayMs), 0);
+        const delayMs = Math.min(2_147_483_647, refreshDelayMs, expiryDelayMs);
+        const timer = setTimeout(() => {
+            if (this.topicRootCandidateClaimMaintenanceTimer !== timer)
                 return;
-            if (this.autoCandidatesGossipUntil > 0 &&
-                Date.now() > this.autoCandidatesGossipUntil) {
-                if (this.autoCandidatesGossipInterval) {
-                    clearInterval(this.autoCandidatesGossipInterval);
-                    this.autoCandidatesGossipInterval = undefined;
+            this.topicRootCandidateClaimMaintenanceTimer = undefined;
+            let retryDelayMs = 0;
+            try {
+                this.rebuildAutoTopicRootCandidatesFromClaims();
+                const currentLocal = this.localSignedTopicRootCandidateClaim;
+                const refreshDue = !this.topicRootCandidateClaimMaintenanceRefreshInFlight &&
+                    this.canRetainTopicRootCandidateClaimOrigin(this.publicKeyHash) &&
+                    performance.now() >=
+                        (this.topicRootCandidateClaimRefreshNotBefore ?? 0) &&
+                    (!currentLocal ||
+                        Date.now() - Number(currentLocal.timestamp) >=
+                            TOPIC_ROOT_CANDIDATE_CLAIM_REFRESH_MS);
+                if (refreshDue) {
+                    this.startTopicRootCandidateClaimMaintenanceRefresh();
                 }
-                return;
             }
-            void this.sendAutoTopicRootCandidates().catch(() => { });
-        }, 2_000);
-        this.autoCandidatesGossipInterval.unref?.();
+            catch (error) {
+                logErrorIfStarted(error);
+                retryDelayMs = TOPIC_ROOT_CANDIDATE_CLAIM_REFRESH_RETRY_MS;
+            }
+            if (!this.topicRootCandidateClaimMaintenanceTimer) {
+                // Re-arm immediately. While refresh is in flight, its due time is
+                // treated as infinity but independent claim expiries remain scheduled.
+                this.scheduleTopicRootCandidateClaimMaintenance(retryDelayMs);
+            }
+        }, delayMs);
+        timer.unref?.();
+        this.topicRootCandidateClaimMaintenanceTimer = timer;
     }
-    async sendAutoTopicRootCandidates(targets) {
-        if (!this.started)
-            throw new NotStartedError();
-        const streams = targets ?? [...this.peers.values()];
-        if (streams.length === 0)
+    startTopicRootCandidateClaimMaintenanceRefresh() {
+        if (this.topicRootCandidateClaimMaintenanceRefreshInFlight)
             return;
-        const candidates = this.topicRootControlPlane.getTopicRootCandidates();
-        if (candidates.length === 0)
-            return;
-        const msg = new TopicRootCandidates({ candidates });
-        const embedded = await this.createMessage(this.encodePubSubMessage(msg), {
-            mode: new AnyWhere(),
-            priority: 1,
-            skipRecipientValidation: true,
-        });
-        await this.publishMessageMaybe(this.publicKey, embedded, streams);
+        const lifecycleRevision = this.topicControlPlaneLifecycleRevision;
+        let task;
+        task = (async () => {
+            try {
+                const refreshed = await this.refreshLocalTopicRootCandidateClaim();
+                if (this.topicRootCandidateClaimMaintenanceRefreshInFlight !== task ||
+                    lifecycleRevision !== this.topicControlPlaneLifecycleRevision) {
+                    return;
+                }
+                const local = this.localSignedTopicRootCandidateClaim;
+                if (!refreshed || !local) {
+                    if (this.canRetainTopicRootCandidateClaimOrigin(this.publicKeyHash)) {
+                        this.topicRootCandidateClaimRefreshNotBefore =
+                            performance.now() + TOPIC_ROOT_CANDIDATE_CLAIM_REFRESH_RETRY_MS;
+                    }
+                    else {
+                        this.topicRootCandidateClaimRefreshNotBefore = undefined;
+                    }
+                    return;
+                }
+                this.topicRootCandidateClaimRefreshNotBefore = undefined;
+                // Arm the new local lease's expiry before outbound I/O can stall.
+                this.scheduleTopicRootCandidateClaimMaintenance();
+                try {
+                    await this.sendSignedTopicRootCandidateClaims([local.bytes], undefined, AbortSignal.timeout(TOPIC_ROOT_CANDIDATE_CLAIM_ADVERTISEMENT_TIMEOUT_MS));
+                }
+                catch (error) {
+                    // A later renewal or outbound-stream snapshot retries this
+                    // best-effort advertisement; the signed lease itself is valid.
+                    logErrorIfStarted(error);
+                }
+            }
+            catch (error) {
+                if (this.topicRootCandidateClaimMaintenanceRefreshInFlight === task &&
+                    lifecycleRevision === this.topicControlPlaneLifecycleRevision) {
+                    logErrorIfStarted(error);
+                    this.topicRootCandidateClaimRefreshNotBefore =
+                        this.canRetainTopicRootCandidateClaimOrigin(this.publicKeyHash)
+                            ? performance.now() + TOPIC_ROOT_CANDIDATE_CLAIM_REFRESH_RETRY_MS
+                            : undefined;
+                }
+            }
+            finally {
+                if (this.topicRootCandidateClaimMaintenanceRefreshInFlight === task &&
+                    lifecycleRevision === this.topicControlPlaneLifecycleRevision) {
+                    this.topicRootCandidateClaimMaintenanceRefreshInFlight = undefined;
+                    this.scheduleTopicRootCandidateClaimMaintenance();
+                }
+            }
+        })();
+        this.topicRootCandidateClaimMaintenanceRefreshInFlight = task;
+    }
+    pruneExpiredTopicRootCandidateClaims(now = BigInt(Date.now()), monotonicNow = performance.now()) {
+        const localClaim = this.localSignedTopicRootCandidateClaim;
+        if (localClaim &&
+            (localClaim.expires <= now || localClaim.acceptUntil <= monotonicNow)) {
+            this.localSignedTopicRootCandidateClaim = undefined;
+        }
+        let changed = false;
+        for (const [origin, claim] of this.signedTopicRootCandidateClaims) {
+            if (claim.expires <= now || claim.acceptUntil <= monotonicNow) {
+                this.signedTopicRootCandidateClaims.delete(origin);
+                changed = true;
+            }
+        }
+        return changed;
     }
-    mergeAutoTopicRootCandidatesFromPeer(candidates) {
+    rebuildAutoTopicRootCandidatesFromClaims(now = BigInt(Date.now()), options) {
         if (!this.autoTopicRootCandidates)
             return false;
-        return this.queueAutoTopicRootCandidateUpdate(candidates);
+        const removedExpired = this.pruneExpiredTopicRootCandidateClaims(now);
+        const legacyDirectCandidates = [...this.peers.values()]
+            .filter((peer) => peer.protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_0)
+            .map((peer) => peer.publicKey.hashcode());
+        const hasSignedPeer = [...this.peers.values()].some((peer) => peer.protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_1);
+        const next = [
+            ...new Set([
+                ...(this.localSignedTopicRootCandidateClaim || hasSignedPeer
+                    ? []
+                    : [this.publicKeyHash]),
+                ...legacyDirectCandidates,
+                ...this.signedTopicRootCandidateClaims.keys(),
+            ]),
+        ]
+            .filter(isCanonicalTopicRootCandidate)
+            .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+            .slice(0, TOPIC_ROOT_CANDIDATES_MAX);
+        return this.setAutoTopicRootCandidateSnapshot(next, {
+            // A cooldown may coalesce additions, but it must never extend an expired
+            // candidate's effective lease. The full snapshot is authoritative, so any
+            // queued pre-expiry snapshot can be discarded safely here.
+            immediate: removedExpired || options?.immediate,
+        });
     }
-    queueAutoTopicRootCandidateUpdate(candidates) {
+    retainSignedTopicRootCandidateClaim(origin, claim) {
+        if (!this.canAdvanceTopicRootCandidateClaimReplayFloor(origin, claim.timestamp)) {
+            return false;
+        }
+        const existing = this.signedTopicRootCandidateClaims.get(origin);
+        if (existing) {
+            if (claim.timestamp <= existing.timestamp) {
+                return false;
+            }
+        }
+        if (!this.topicRootCandidateClaimReplayFloors.has(origin)) {
+            if (this.topicRootCandidateClaimReplayFloors.size >=
+                TOPIC_ROOT_CANDIDATES_MAX) {
+                const highest = [...this.topicRootCandidateClaimReplayFloors.keys()]
+                    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+                    .at(-1);
+                // `canAdvance...` admitted a lower origin. Removing the displaced
+                // origin's live/local state preserves the same lowest-origin invariant;
+                // because the retained maximum only decreases, it cannot re-enter.
+                this.topicRootCandidateClaimReplayFloors.delete(highest);
+                this.signedTopicRootCandidateClaims.delete(highest);
+                if (highest === this.publicKeyHash) {
+                    this.localSignedTopicRootCandidateClaim = undefined;
+                }
+            }
+        }
+        this.topicRootCandidateClaimReplayFloors.set(origin, claim.timestamp);
+        this.signedTopicRootCandidateClaims.set(origin, claim);
+        return true;
+    }
+    canAdvanceTopicRootCandidateClaimReplayFloor(origin, timestamp) {
+        const floor = this.topicRootCandidateClaimReplayFloors.get(origin);
+        if (floor !== undefined) {
+            return timestamp > floor;
+        }
+        return this.canRetainTopicRootCandidateClaimOrigin(origin);
+    }
+    canRetainTopicRootCandidateClaimOrigin(origin) {
+        if (this.topicRootCandidateClaimReplayFloors.has(origin)) {
+            return true;
+        }
+        if (this.topicRootCandidateClaimReplayFloors.size < TOPIC_ROOT_CANDIDATES_MAX) {
+            return true;
+        }
+        const highest = [...this.topicRootCandidateClaimReplayFloors.keys()]
+            .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+            .at(-1);
+        return origin < highest;
+    }
+    consumeTopicRootCandidateClaimVerifyBudget(peerHash) {
+        const now = Date.now();
+        if (now - this.topicRootCandidateClaimGlobalVerifyBudget.refilledAt >=
+            TOPIC_ROOT_CANDIDATE_CLAIM_VERIFY_REFILL_MS) {
+            this.topicRootCandidateClaimGlobalVerifyBudget = {
+                remaining: TOPIC_ROOT_CANDIDATE_CLAIM_GLOBAL_VERIFY_BURST,
+                refilledAt: now,
+            };
+        }
+        if (this.topicRootCandidateClaimGlobalVerifyBudget.remaining <= 0) {
+            return false;
+        }
+        let budget = this.topicRootCandidateClaimVerifyBudgets.get(peerHash);
+        if (!budget) {
+            if (this.topicRootCandidateClaimVerifyBudgets.size >=
+                TOPIC_ROOT_CANDIDATE_CLAIM_VERIFY_PEERS_MAX) {
+                const oldest = this.topicRootCandidateClaimVerifyBudgets.keys().next()
+                    .value;
+                if (oldest)
+                    this.topicRootCandidateClaimVerifyBudgets.delete(oldest);
+            }
+            budget = {
+                remaining: TOPIC_ROOT_CANDIDATE_CLAIM_VERIFY_BURST,
+                refilledAt: now,
+            };
+            this.topicRootCandidateClaimVerifyBudgets.set(peerHash, budget);
+        }
+        else if (now - budget.refilledAt >=
+            TOPIC_ROOT_CANDIDATE_CLAIM_VERIFY_REFILL_MS) {
+            budget.remaining = TOPIC_ROOT_CANDIDATE_CLAIM_VERIFY_BURST;
+            budget.refilledAt = now;
+            // Refresh insertion order so bounded eviction remains O(1) and LRU-like.
+            this.topicRootCandidateClaimVerifyBudgets.delete(peerHash);
+            this.topicRootCandidateClaimVerifyBudgets.set(peerHash, budget);
+        }
+        if (budget.remaining <= 0)
+            return false;
+        budget.remaining -= 1;
+        this.topicRootCandidateClaimGlobalVerifyBudget.remaining -= 1;
+        return true;
+    }
+    async importSignedTopicRootCandidateClaim(rawClaim, outerPeerHash) {
+        const lifecycleRevision = this.topicControlPlaneLifecycleRevision;
+        if (rawClaim.byteLength === 0 ||
+            rawClaim.byteLength > TOPIC_ROOT_CANDIDATE_CLAIM_MAX_BYTES) {
+            return false;
+        }
+        let claim;
+        try {
+            claim = DataMessage.from(new Uint8ArrayList(rawClaim));
+        }
+        catch {
+            return false;
+        }
+        const canonicalBytes = toUint8Array(claim.bytes());
+        if (!bytesEqual(canonicalBytes, rawClaim))
+            return false;
+        if (!claim.data ||
+            !bytesEqual(claim.data, this.topicRootCandidateClaimData)) {
+            return false;
+        }
+        const signatures = claim.header.signatures?.signatures;
+        if (!signatures || signatures.length !== 1)
+            return false;
+        const signer = signatures[0]?.publicKey;
+        if (!signer)
+            return false;
+        const origin = signer.hashcode();
+        if (!isCanonicalTopicRootCandidate(origin))
+            return false;
+        if (origin === this.publicKeyHash)
+            return false;
+        const now = BigInt(Date.now());
+        const monotonicNow = performance.now();
+        const timestamp = claim.header.timestamp;
+        const expires = claim.header.expires;
+        const acceptanceDeadline = this.topicRootCandidateClaimAcceptanceDeadline(timestamp, expires, now, monotonicNow, TOPIC_ROOT_CANDIDATE_CLAIM_RECEIVER_MAX_LIFETIME_MS);
+        if (acceptanceDeadline === undefined) {
+            return false;
+        }
+        if (!this.canAdvanceTopicRootCandidateClaimReplayFloor(origin, timestamp)) {
+            return false;
+        }
+        this.rebuildAutoTopicRootCandidatesFromClaims(now);
+        if (!this.consumeTopicRootCandidateClaimVerifyBudget(outerPeerHash)) {
+            return false;
+        }
+        this.seedNativeWireVerification(claim, rawClaim);
+        let verified = false;
+        try {
+            verified = await claim.verify(true);
+        }
+        catch {
+            return false;
+        }
+        if (!verified)
+            return false;
+        if (lifecycleRevision !== this.topicControlPlaneLifecycleRevision ||
+            !this.isTopicRootCandidateClaimTimeValid(timestamp, expires, BigInt(Date.now())) ||
+            performance.now() >= acceptanceDeadline ||
+            !this.autoTopicRootCandidates ||
+            !this.started ||
+            this.stopping ||
+            this.topicControlPlaneStopping) {
+            return false;
+        }
+        if (!this.retainSignedTopicRootCandidateClaim(origin, {
+            bytes: rawClaim.slice(),
+            timestamp,
+            expires,
+            acceptUntil: acceptanceDeadline,
+        })) {
+            return false;
+        }
+        this.scheduleTopicRootCandidateClaimMaintenance();
+        return true;
+    }
+    async sendSignedTopicRootCandidateClaims(claims, targets, signal) {
+        if (claims.length === 0)
+            return;
+        const streams = (targets ?? [...this.peers.values()]).filter((stream) => stream.protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_1);
+        if (streams.length === 0)
+            return;
+        for (let offset = 0; offset < claims.length; offset += TOPIC_ROOT_CANDIDATE_CLAIMS_MAX) {
+            throwIfAborted(signal);
+            const message = new TopicRootCandidateClaims({
+                claims: claims.slice(offset, offset + TOPIC_ROOT_CANDIDATE_CLAIMS_MAX),
+            });
+            const embedded = await withAbort(this.createMessage(this.encodePubSubMessage(message), {
+                mode: new AnyWhere(),
+                priority: 1,
+                skipRecipientValidation: true,
+            }), signal);
+            throwIfAborted(signal);
+            await this.publishMessageMaybe(this.publicKey, embedded, streams, undefined, signal);
+        }
+    }
+    async sendAutoTopicRootCandidates(streams) {
+        if (!this.started)
+            throw new NotStartedError();
+        const signedStreams = streams.filter((stream) => stream.protocol === TOPIC_CONTROL_PLANE_PROTOCOL_V2_1);
+        if (signedStreams.length === 0)
+            return;
+        this.rebuildAutoTopicRootCandidatesFromClaims();
+        if (!this.localSignedTopicRootCandidateClaim) {
+            try {
+                await this.refreshLocalTopicRootCandidateClaim();
+            }
+            catch (error) {
+                // Failure to refresh the nested local claim must not suppress
+                // authenticated remote claims; outer-envelope signing is still tried.
+                logErrorIfStarted(error);
+            }
+        }
+        const claims = [...this.signedTopicRootCandidateClaims.entries()]
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+            .map(([, claim]) => claim.bytes);
+        await this.sendSignedTopicRootCandidateClaims(claims, signedStreams);
+        const localClaim = this.localSignedTopicRootCandidateClaim;
+        if (localClaim &&
+            !this.signedTopicRootCandidateClaims.has(this.publicKeyHash)) {
+            await this.sendSignedTopicRootCandidateClaims([localClaim.bytes], signedStreams);
+        }
+    }
+    setAutoTopicRootCandidateSnapshot(next, options) {
         if (!this.autoTopicRootCandidates ||
             this.stopping ||
-            this.topicControlPlaneStopping)
+            this.topicControlPlaneStopping) {
             return false;
-        if (this.maybeDisableAutoTopicRootCandidatesIfExternallyConfigured())
+        }
+        if (this.maybeDisableAutoTopicRootCandidatesIfExternallyConfigured()) {
             return false;
+        }
         const managed = this.autoTopicRootCandidateSet;
         if (!managed)
             return false;
+        if (options?.immediate) {
+            this.clearAutoTopicRootCandidateUpdateSchedule();
+            const current = [...managed];
+            if (sameCandidates(current, next))
+                return false;
+            this.scheduleAutoTopicRootCandidateUpdateCooldown();
+            this.applyAutoTopicRootCandidates(next);
+            return true;
+        }
         const before = this.pendingAutoTopicRootCandidates ?? [...managed];
-        const next = this.normalizeAutoTopicRootCandidates([
-            ...before,
-            ...candidates,
-        ]);
         if (sameCandidates(before, next))
             return false;
         if (this.autoTopicRootCandidateUpdateTimer) {
@@ -580,7 +1032,6 @@ export class TopicControlPlane extends DirectStream {
         this.shardRootCache.clear();
         this.scheduleReconcileShardOverlays();
         this.scheduleHostOwnedShardRoots();
-        this.scheduleAutoTopicRootCandidatesBroadcast();
     }
     scheduleAutoTopicRootCandidateUpdateCooldown() {
         if (this.autoTopicRootCandidateUpdateTimer)
@@ -906,6 +1357,11 @@ export class TopicControlPlane extends DirectStream {
         if (bytes[0] === 4) {
             assertTopicRootCandidatesFrame(bytes);
         }
+        // Signed candidate claims are low-frequency opaque host-side frames. Keep
+        // this explicit seam ahead of the native variants 0-7 codec.
+        if (bytes[0] === 8) {
+            return TopicRootCandidateClaims.from(bytes);
+        }
         const native = this.nativeTopicControl;
         if (native) {
             const decoded = native.decodePubSubMessage(bytes);
@@ -1106,7 +1562,7 @@ export class TopicControlPlane extends DirectStream {
         let requestId = this.nextTopicRootQueryId >>> 0;
         do {
             requestId = requestId === 0 ? 1 : requestId;
-            this.nextTopicRootQueryId = ((requestId + 1) >>> 0) || 1;
+            this.nextTopicRootQueryId = (requestId + 1) >>> 0 || 1;
             if (!this.pendingTopicRootQueries.has(requestId)) {
                 return requestId;
             }
@@ -1764,7 +2220,9 @@ export class TopicControlPlane extends DirectStream {
             this.shardRefCounts.set(shardTopic, next);
         }
         // Best-effort: do not block callers on network I/O (can hang under teardown).
-        void this.debounceUnsubscribeAggregator.add({ key: topic }).catch(logErrorIfStarted);
+        void this.debounceUnsubscribeAggregator
+            .add({ key: topic })
+            .catch(logErrorIfStarted);
         return true;
     }
     async _announceUnsubscribe(topics) {
@@ -1893,9 +2351,7 @@ export class TopicControlPlane extends DirectStream {
         }
     }
     onFanoutPeerUnreachable(ev) {
-        void this
-            .announcePeerUnavailableOnShard(ev.detail.publicKeyHash, ev.detail.topic)
-            .catch(logErrorIfStarted);
+        void this.announcePeerUnavailableOnShard(ev.detail.publicKeyHash, ev.detail.topic).catch(logErrorIfStarted);
     }
     getSubscribers(topic) {
         const t = topic.toString();
@@ -2147,9 +2603,7 @@ export class TopicControlPlane extends DirectStream {
         }))
             .filter((batch) => batch.topics.length > 0);
         if (batches.length > 0) {
-            void this
-                .announcePeerUnavailable(publicKeyHash, batches)
-                .catch(logErrorIfStarted);
+            void this.announcePeerUnavailable(publicKeyHash, batches).catch(logErrorIfStarted);
         }
     }
     collectSubscriptionState(peerHash) {
@@ -2266,9 +2720,7 @@ export class TopicControlPlane extends DirectStream {
             if (!this.lastSubscriptionMessages.has(subscriberKey)) {
                 this.lastSubscriptionMessages.set(subscriberKey, new Map());
             }
-            this.lastSubscriptionMessages
-                .get(subscriberKey)
-                .set(topic, {
+            this.lastSubscriptionMessages.get(subscriberKey).set(topic, {
                 session,
                 timestamp,
             });
@@ -2378,6 +2830,7 @@ export class TopicControlPlane extends DirectStream {
     async processDirectPubSubMessage(input) {
         const { pubsubMessage, message, from, stream } = input;
         const isDirectRootControl = pubsubMessage instanceof TopicRootCandidates ||
+            pubsubMessage instanceof TopicRootCandidateClaims ||
             pubsubMessage instanceof TopicRootQuery ||
             pubsubMessage instanceof TopicRootQueryResponse;
         const directRootSigner = isDirectRootControl
@@ -2388,8 +2841,31 @@ export class TopicControlPlane extends DirectStream {
             return;
         }
         if (pubsubMessage instanceof TopicRootCandidates) {
-            // Used only to converge deterministic shard-root candidates in auto mode.
-            this.mergeAutoTopicRootCandidatesFromPeer(pubsubMessage.candidates);
+            if (stream.protocol !== TOPIC_CONTROL_PLANE_PROTOCOL_V2_0) {
+                return;
+            }
+            // `addPeer()` already admitted the authenticated direct stream identity.
+            // The advertised list is intentionally ignored.
+            return;
+        }
+        if (pubsubMessage instanceof TopicRootCandidateClaims) {
+            if (stream.protocol !== TOPIC_CONTROL_PLANE_PROTOCOL_V2_1 ||
+                !this.autoTopicRootCandidates) {
+                return;
+            }
+            const imported = [];
+            const outerPeerHash = stream.publicKey.hashcode();
+            for (const claim of pubsubMessage.claims) {
+                if (await this.importSignedTopicRootCandidateClaim(claim, outerPeerHash)) {
+                    imported.push(claim);
+                }
+            }
+            if (imported.length > 0) {
+                this.rebuildAutoTopicRootCandidatesFromClaims();
+                // Relay the exact nested claims; no relay signature is substituted for
+                // their origin signatures.
+                void this.sendSignedTopicRootCandidateClaims(imported, [...this.peers.values()].filter((peer) => peer.publicKey.hashcode() !== outerPeerHash)).catch(() => { });
+            }
             return;
         }
         if (pubsubMessage instanceof TopicRootQuery) {
@@ -2439,7 +2915,7 @@ export class TopicControlPlane extends DirectStream {
                 }
                 if (changed.length > 0) {
                     this.dispatchEvent(new CustomEvent("subscribe", {
-                        detail: new SubscriptionEvent(sender, changed),
+                        detail: new SubscriptionEvent(sender, changed, message.header.session),
                     }));
                 }
             }
@@ -2518,7 +2994,7 @@ export class TopicControlPlane extends DirectStream {
                 }
                 if (changed.length > 0) {
                     this.dispatchEvent(new CustomEvent("subscribe", {
-                        detail: new SubscriptionEvent(sender, changed),
+                        detail: new SubscriptionEvent(sender, changed, message.header.session),
                     }));
                 }
             }
@@ -2642,6 +3118,7 @@ export class TopicControlPlane extends DirectStream {
         // messages used for topic-root discovery and direct subscriber snapshots.
         if (!(pubsubMessage instanceof PubSubData) &&
             !(pubsubMessage instanceof TopicRootCandidates) &&
+            !(pubsubMessage instanceof TopicRootCandidateClaims) &&
             !(pubsubMessage instanceof TopicRootQuery) &&
             !(pubsubMessage instanceof GetSubscribers) &&
             !(pubsubMessage instanceof Subscribe) &&