@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/sync/handlers.js

@@ -1 +1,200 @@
-import{createRevocationChecker as e}from"@enkaku/capability";import{getGraphStore as t}from"@kubun/store-graph";import{createP2PRevocationBackend as r,getP2PStore as o}from"@kubun/store-p2p";import{authorizeScope as s,checkSyncDelegation as n}from"./authorize.js";import{resolveCatalogSyncScopes as l}from"./catalog-scope.js";import{SyncAccessDeniedError as a}from"./errors.js";import{createMerkleSyncChannelHandler as i}from"./merkle-channel.js";import{negotiateDirection as c}from"./peer-registry.js";export function createSyncHandlers(n){let{db:u,graph:d,logger:f,peerRegistry:m}=n,p=n.storeUnreadable??"persist",g=null;async function w(){return null==g&&(g=e(r(await o(u)))),g}return{"sync/negotiate":async e=>{let r,{scopes:o,delegationTokens:n,catalogIDs:i,knownModelIDs:d,direction:p}=e.param,g=e.message.payload;if(null!=g.sub&&g.sub!==g.iss)throw new a("forged-subject","Sync access denied: signed payload subject does not match issuer");let D=g.iss;f.debug("sync/negotiate requested",{scopes:o,catalogIDs:i,viewerDID:D});let h=[],y=await t(u);if(null!=i&&i.length>0){let e=await l(u,i,d);if(e.modelIDs.length>0)if(null!=e.owners)for(let t of e.modelIDs)for(let r of e.owners)await s({viewerDID:D,ownerDID:r,delegationTokens:n,revocationChecker:await w()})&&h.push({modelID:t,ownerDID:r});else for(let t of e.modelIDs)for(let e of(await y.getDistinctOwnersForModel(t)))await s({viewerDID:D,ownerDID:e,delegationTokens:n,revocationChecker:await w()})&&h.push({modelID:t,ownerDID:e});e.missingClusterIDs.length>0&&(r=await y.getClusters(e.missingClusterIDs))}if(null!=o)for(let e of o)await s({viewerDID:D,ownerDID:e.ownerDID,delegationTokens:n,revocationChecker:await w()})?h.push(e):f.debug("sync/negotiate: scope rejected",{scope:e,viewerDID:D});let I=new Set,b=h.filter(e=>{let t=`${e.modelID}:${e.ownerDID}`;return!I.has(t)&&(I.add(t),!0)});f.info("sync/negotiate completed",{requested:(o?.length??0)+(i?.length??0),accepted:b.length,missingClusters:null!=r?Object.keys(r).length:0});let k=p??"pull",j=await m.getPeer({peerDID:D,stores:u}),C=j?.allowedDirection??"both",v=c(k,C);return v!==k&&f.info("sync/negotiate: direction downgraded",{requested:k,allowed:C,agreed:v}),{direction:v,acceptedScopes:b,excludedDocumentIDs:[],...null!=r&&{missingClusters:r}}},"sync/merkle-sync":i({db:u,graph:d,logger:f,peerRegistry:m,selfDID:n.selfDID,storeUnreadable:p,defaultAccessLevel:n.defaultAccessLevel,getRevocationChecker:w})}}export{n as checkSyncDelegation};
+import { createDelegationRevocationChecker, getDelegationStore } from '@kubun/store-delegation';
+import { getGraphStore } from '@kubun/store-graph';
+import { getP2PStore } from '@kubun/store-p2p';
+import { wrapHandlers } from '../util/handler-error.js';
+import { authorizeScope, checkSyncDelegation } from './authorize.js';
+import { resolveCatalogSyncScopes } from './catalog-scope.js';
+import { SyncAccessDeniedError } from './errors.js';
+import { createMerkleSyncChannelHandler } from './merkle-channel.js';
+import { negotiateDirection } from './peer-registry.js';
+export { checkSyncDelegation };
+// ---- Handler factory ----
+/**
+ * Create sync protocol handlers served by plugin-p2p's own Enkaku server.
+ */ export function createSyncHandlers(params) {
+    const { db, graph, logger, peerRegistry } = params;
+    const storeUnreadable = params.storeUnreadable ?? 'persist';
+    let cachedRevocationChecker = null;
+    async function getRevocationChecker() {
+        if (cachedRevocationChecker == null) {
+            const delegationStore = await getDelegationStore(db);
+            cachedRevocationChecker = createDelegationRevocationChecker(delegationStore);
+        }
+        return cachedRevocationChecker;
+    }
+    // Circle-granted read resolution, shared by negotiate and merkle-sync so the
+    // two gates authorize identical scopes. Reads run against this device's own
+    // projected state (the owner's tier-2 default + the requester's membership).
+    let cachedCircleReadGrant = null;
+    async function getCircleReadGrant() {
+        if (cachedCircleReadGrant == null) {
+            const [graphStore, p2pStore] = await Promise.all([
+                getGraphStore(db),
+                getP2PStore(db)
+            ]);
+            cachedCircleReadGrant = {
+                getUserModelReadDefault: (ownerDID, modelID)=>graphStore.getUserModelAccessDefault(ownerDID, modelID, 'read'),
+                // `listAccessibleCircles` excludes tombstoned circles, so a removed
+                // circle is simply absent and the gate fails closed on it.
+                listAccessibleCircles: (viewerDID, circleIDs)=>p2pStore.listAccessibleCircles(viewerDID, circleIDs),
+                listMemberGroupIDs: (viewerDID, groupIDs)=>p2pStore.listMemberGroupIDs(viewerDID, groupIDs)
+            };
+        }
+        return cachedCircleReadGrant;
+    }
+    // Wrapped so a refusal carrying a registered KubunErrorCode reaches the
+    // calling device with its code and reason instead of enkaku's generic EK01.
+    return wrapHandlers({
+        'sync/negotiate': async (ctx)=>{
+            const { scopes, delegationTokens, catalogIDs, knownModelIDs, direction } = ctx.param;
+            const payload = ctx.message.payload;
+            // The viewer is the cryptographically-verified signer (`iss`). A signed
+            // payload always carries `iss`; no legitimate kubun client sets `sub`.
+            // Reject any request whose `sub` is present and differs from `iss` to
+            // close the forged-subject path before any store read.
+            if (payload.sub != null && payload.sub !== payload.iss) {
+                throw new SyncAccessDeniedError('forged-subject', 'Sync access denied: signed payload subject does not match issuer');
+            }
+            const viewerDID = payload.iss;
+            logger.debug('sync/negotiate requested', {
+                scopes,
+                catalogIDs,
+                viewerDID
+            });
+            const acceptedScopes = [];
+            let missingClusters;
+            const graphStore = await getGraphStore(db);
+            // Catalog-based scope resolution
+            if (catalogIDs != null && catalogIDs.length > 0) {
+                const catalogScope = await resolveCatalogSyncScopes(db, catalogIDs);
+                // Generate scopes from resolved catalog criteria
+                if (catalogScope.modelIDs.length > 0) {
+                    if (catalogScope.owners != null) {
+                        // Explicit owners from catalog criteria
+                        for (const modelID of catalogScope.modelIDs){
+                            for (const ownerDID of catalogScope.owners){
+                                const accepted = await authorizeScope({
+                                    viewerDID,
+                                    ownerDID,
+                                    modelID,
+                                    delegationTokens,
+                                    revocationChecker: await getRevocationChecker(),
+                                    circleReadGrant: await getCircleReadGrant()
+                                });
+                                if (accepted) {
+                                    acceptedScopes.push({
+                                        modelID,
+                                        ownerDID
+                                    });
+                                }
+                            }
+                        }
+                    } else {
+                        // No owner filter — get all distinct owners for each model
+                        for (const modelID of catalogScope.modelIDs){
+                            const owners = await graphStore.getDistinctOwnersForModel(modelID);
+                            for (const ownerDID of owners){
+                                const accepted = await authorizeScope({
+                                    viewerDID,
+                                    ownerDID,
+                                    modelID,
+                                    delegationTokens,
+                                    revocationChecker: await getRevocationChecker(),
+                                    circleReadGrant: await getCircleReadGrant()
+                                });
+                                if (accepted) {
+                                    acceptedScopes.push({
+                                        modelID,
+                                        ownerDID
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // Explicit scopes (existing behavior)
+            if (scopes != null) {
+                for (const scope of scopes){
+                    const accepted = await authorizeScope({
+                        viewerDID,
+                        ownerDID: scope.ownerDID,
+                        modelID: scope.modelID,
+                        delegationTokens,
+                        revocationChecker: await getRevocationChecker(),
+                        circleReadGrant: await getCircleReadGrant()
+                    });
+                    if (accepted) {
+                        acceptedScopes.push(scope);
+                    } else {
+                        logger.debug('sync/negotiate: scope rejected', {
+                            scope,
+                            viewerDID
+                        });
+                    }
+                }
+            }
+            // Deduplicate scopes
+            const seen = new Set();
+            const uniqueScopes = acceptedScopes.filter((s)=>{
+                const key = `${s.modelID}:${s.ownerDID}`;
+                if (seen.has(key)) return false;
+                seen.add(key);
+                return true;
+            });
+            // A model the requester does not have is one it cannot store documents
+            // for, so ship the cluster it was deployed in. Computed over the ACCEPTED
+            // scopes rather than over a catalog: production negotiates with explicit
+            // scopes and sends no `catalogIDs`, so a catalog-only computation is
+            // unreachable there — and an unauthorized scope must not leak a model
+            // definition either way.
+            const knownSet = new Set(knownModelIDs ?? []);
+            // Concurrently: one read per unknown model, none depending on another, on
+            // the negotiate that a peer waits out before any document moves.
+            const resolved = await Promise.all(uniqueScopes.filter((scope)=>!knownSet.has(scope.modelID)).map((scope)=>graphStore.getClusterForModel(scope.modelID)));
+            const missingClusterIDs = new Set(resolved.filter((id)=>id != null));
+            if (missingClusterIDs.size > 0) {
+                missingClusters = await graphStore.getClusters(Array.from(missingClusterIDs));
+            }
+            logger.info('sync/negotiate completed', {
+                requested: (scopes?.length ?? 0) + (catalogIDs?.length ?? 0),
+                accepted: uniqueScopes.length,
+                missingClusters: missingClusters != null ? Object.keys(missingClusters).length : 0
+            });
+            // Resolve direction against per-peer policy
+            const requestedDirection = direction ?? 'pull';
+            const peer = await peerRegistry.getPeer({
+                peerDID: viewerDID,
+                stores: db
+            });
+            const peerAllowed = peer?.allowedDirection ?? 'both';
+            const agreedDirection = negotiateDirection(requestedDirection, peerAllowed);
+            if (agreedDirection !== requestedDirection) {
+                logger.info('sync/negotiate: direction downgraded', {
+                    requested: requestedDirection,
+                    allowed: peerAllowed,
+                    agreed: agreedDirection
+                });
+            }
+            return {
+                direction: agreedDirection,
+                acceptedScopes: uniqueScopes,
+                excludedDocumentIDs: [],
+                ...missingClusters != null && {
+                    missingClusters
+                }
+            };
+        },
+        'sync/merkle-sync': createMerkleSyncChannelHandler({
+            db,
+            graph,
+            logger,
+            peerRegistry,
+            selfDID: params.selfDID,
+            storeUnreadable,
+            defaultAccessLevel: params.defaultAccessLevel,
+            getRevocationChecker,
+            getCircleReadGrant
+        })
+    });
+}

package/lib/sync/hub-tunnel-sync-listener.d.ts

@@ -1,22 +1,36 @@
-import { type ObservabilityEventListener } from '@enkaku/hub-tunnel';
 import { type ProcedureHandlers } from '@enkaku/server';
-import type { OwnIdentity } from '@enkaku/token';
+import type { OwnIdentity } from '@kokuin/token';
+import type { Logger } from '@kubun/logger';
+import { type MailboxHub, type ObservabilityEventListener } from '@kumiai/hub-tunnel';
+import type { Runtime } from '@sozai/runtime';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
-import type { HubConnection } from '../hub/hub-connection.js';
 import type { SyncProtocol } from '../protocol.js';
 export type HubTunnelSyncListenerParams = {
-    hubConnection: HubConnection;
+    /**
+     * Shared multi-subscriber device hub (from `createHubLike`). Every listener on
+     * a device receives on the SAME topic (this device's inbox for the epoch), so
+     * the hub is not handed to the transport directly — it is fronted by a
+     * per-peer view that drops other peers' frames before they reach the cipher.
+     * Lifecycle events ride `hub.events`.
+     */
+    hub: MailboxHub;
     registry: GroupHandleRegistry;
     groupID: string;
     localDID: string;
     peerDID: string;
     identity: OwnIdentity;
     syncHandlers: ProcedureHandlers<SyncProtocol>;
-    getRandomID?: () => string;
+    /**
+     * Threaded through to every spawned session's server rather than defaulted
+     * here, so a device whose platform primitives differ from the Node defaults
+     * keeps one generator across the whole plugin.
+     */
+    runtime: Runtime;
     idleTimeoutMs?: number;
     reconnectTimeoutMs?: number;
     inboxCapacity?: number;
     onEvent?: ObservabilityEventListener;
+    logger?: Logger;
 };
 export declare class HubTunnelSyncListener {
     #private;

package/lib/sync/hub-tunnel-sync-listener.js

@@ -1 +1,261 @@
-import{createEncryptedHubTunnelTransport as t}from"@enkaku/hub-tunnel";import{Server as e}from"@enkaku/server";import{MLSEncryptor as s}from"../groups/mls-encryptor.js";export class HubTunnelSyncListener{#t;#e;#s;#n;#i;#r;#o;#c;#a;#h;#u;#p;#l=!1;#d=!1;#y;#D;#m;constructor(t){this.#t=t.hubConnection,this.#e=t.registry,this.#s=t.groupID,this.#n=t.localDID,this.#i=t.peerDID,this.#r=t.identity,this.#o=t.syncHandlers,this.#c=t.getRandomID,this.#a=t.idleTimeoutMs,this.#h=t.reconnectTimeoutMs,this.#u=t.inboxCapacity,this.#p=t.onEvent}start(){this.#l||this.#d||(this.#l=!0,this.#m=new s({registry:this.#e,groupID:this.#s}),this.#D=this.#t.tunnelMessageStream({peerDID:this.#i}),this.#I())}async stop(){if(this.#d)return;this.#d=!0;let t=this.#y;if(this.#y=void 0,null!=t){try{await t.transport.dispose()}catch{}try{await t.server.dispose()}catch{}}let e=this.#D;if(this.#D=void 0,null!=e)try{e.return()}catch{}this.#m=void 0}#I(){let s;if(this.#d)return;let n=this.#m;if(null==n)throw Error("HubTunnelSyncListener: encryptor not initialized; call start() first");let i=t({hub:this.#b(),encryptor:n,groupID:this.#s,sessionID:{auto:!0},localDID:this.#n,peerDID:this.#i,idleTimeoutMs:this.#a,reconnectTimeoutMs:this.#h,inboxCapacity:this.#u,onEvent:this.#p,onSessionEnd:()=>{s?.dispose().catch(()=>{})}});s=i;let r=new e({getRandomID:this.#c,handlers:this.#o,identity:this.#r,accessRules:{"sync/*":{allow:!0}},transports:[i]}),o={transport:i,server:r};this.#y=o,i.events.on("disposed",()=>{this.#y===o&&(this.#y=void 0),r.dispose().catch(()=>{}),this.#I()})}#b(){let t=this.#t,e=this.#D;if(null==e)throw Error("HubTunnelSyncListener: stream not initialized; call start() first");return{send:async e=>t.send({recipients:e.recipients,payload:e.payload}),receive:t=>e,events:{subscribe:e=>t.events.on("lifecycle",t=>{let s=function(t){switch(t.type){case"connected":return{type:"connected"};case"disconnected":return{type:"disconnected"};case"reconnecting":return{type:"reconnecting"};case"error":return}}(t);void 0!==s&&e(s)})}}}}
+import { Server } from '@enkaku/server';
+import { createEncryptedHubTunnelTransport } from '@kumiai/hub-tunnel';
+import { APP_TOPIC_LABEL } from '@kumiai/rpc';
+import { createGroupCrypto } from '../groups/group-crypto.js';
+import { MLSEncryptor } from '../groups/mls-encryptor.js';
+import { createPeerScopedHubView } from '../hub/peer-scoped-hub-view.js';
+import { createTunnelEventLogger } from './tunnel-observability.js';
+import { tunnelTopic } from './tunnel-topics.js';
+export class HubTunnelSyncListener {
+    #hub;
+    #registry;
+    #groupID;
+    #localDID;
+    #peerDID;
+    #identity;
+    #syncHandlers;
+    #runtime;
+    #idleTimeoutMs;
+    #reconnectTimeoutMs;
+    #inboxCapacity;
+    #onEvent;
+    #logger;
+    #started = false;
+    #stopped = false;
+    /** Consecutive failed spawns, for the re-arm backoff. Reset by a success. */ #respawnAttempt = 0;
+    #respawnTimer;
+    #current;
+    // Single MLSEncryptor reused across spawns. Ordering across overlapping
+    // spawns (old transport's last decrypt vs. new spawn's first encrypt) is
+    // covered by the GroupHandleRegistry's per-group mutex.
+    #encryptor;
+    // Per-peer view over the device hub, built once and shared by every spawn: it
+    // holds the inbox subscription for the listener's whole life, so respawns
+    // neither re-arm nor release a topic other listeners are draining.
+    #peerHub;
+    constructor(params){
+        this.#hub = params.hub;
+        this.#registry = params.registry;
+        this.#groupID = params.groupID;
+        this.#localDID = params.localDID;
+        this.#peerDID = params.peerDID;
+        this.#identity = params.identity;
+        this.#syncHandlers = params.syncHandlers;
+        this.#runtime = params.runtime;
+        this.#idleTimeoutMs = params.idleTimeoutMs;
+        this.#reconnectTimeoutMs = params.reconnectTimeoutMs;
+        this.#inboxCapacity = params.inboxCapacity;
+        this.#onEvent = params.onEvent;
+        this.#logger = params.logger;
+    }
+    start() {
+        if (this.#started || this.#stopped) return;
+        this.#started = true;
+        this.#encryptor = new MLSEncryptor({
+            registry: this.#registry,
+            groupID: this.#groupID
+        });
+        this.#peerHub = createPeerScopedHubView({
+            hub: this.#hub,
+            peerDID: this.#peerDID
+        });
+        this.#spawnGuarded();
+    }
+    /**
+   * Spawn, and survive a spawn that throws.
+   *
+   * `#spawn` can reject — `exportSecret(APP_TOPIC_LABEL)` throws whenever the
+   * group handle is unavailable (mid-epoch-change, group left, registry lock
+   * contention). Left bare, that was an unhandled rejection AND a listener that
+   * stopped answering forever: the only other respawn trigger is the
+   * transport's `disposed` event, which cannot fire for a session that was
+   * never built. From the dialer's side that is exactly the silence this
+   * listener exists to eliminate.
+   */ #spawnGuarded() {
+        void this.#spawn().then(()=>{
+            this.#respawnAttempt = 0;
+        }).catch((error)=>{
+            this.#logger?.warn('hub tunnel listener spawn failed', {
+                groupID: this.#groupID,
+                peerDID: this.#peerDID,
+                attempt: this.#respawnAttempt,
+                error
+            });
+            this.#scheduleRespawn();
+        });
+    }
+    #scheduleRespawn() {
+        if (this.#stopped || this.#respawnTimer != null) return;
+        // Bounded: a handle that is unavailable because the group was left never
+        // becomes available, and this must not spin on it.
+        const delay = Math.min(30_000, 250 * 2 ** Math.min(this.#respawnAttempt++, 7));
+        const timer = setTimeout(()=>{
+            this.#respawnTimer = undefined;
+            if (this.#stopped) return;
+            this.#spawnGuarded();
+        }, delay);
+        timer.unref?.();
+        this.#respawnTimer = timer;
+    }
+    async stop() {
+        if (this.#stopped) return;
+        this.#stopped = true;
+        if (this.#respawnTimer != null) {
+            clearTimeout(this.#respawnTimer);
+            this.#respawnTimer = undefined;
+        }
+        const current = this.#current;
+        this.#current = undefined;
+        if (current != null) {
+            try {
+                await current.transport.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+            try {
+                await current.server.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+        }
+        this.#encryptor = undefined;
+        this.#peerHub = undefined;
+    }
+    async #spawn() {
+        if (this.#stopped) return;
+        const encryptor = this.#encryptor;
+        const peerHub = this.#peerHub;
+        if (encryptor == null || peerHub == null) {
+            throw new Error('HubTunnelSyncListener: not initialized; call start() first');
+        }
+        // Derive the epoch-bound, role-scoped topics for this spawn. The server
+        // accepts inbound frames on this device's RESPONDER topic and replies to the
+        // peer's DIALER topic — the mirror of what the dialing side derives, and
+        // disjoint from it, so this device's own dial to the same peer never lands
+        // here. Topics rotate with the MLS epoch, so each
+        // spawn re-derives them against the live handle. MLS decrypt inside the
+        // registry lock remains the authoritative membership/forward-secrecy gate;
+        // stale-after-remove ciphertext surfaces as DecryptError.
+        // The seed epoch is unread here: this port never classifies commit frames,
+        // and `exportSecret()` below records the live epoch before `epoch()` is
+        // asked for it. Only a peer that opens a receive drain needs a real seed.
+        const crypto = createGroupCrypto({
+            registry: this.#registry,
+            groupID: this.#groupID,
+            initialEpoch: 0,
+            runtime: this.#runtime
+        });
+        const secret = await crypto.exportSecret(APP_TOPIC_LABEL);
+        const epoch = crypto.epoch();
+        const sendTopicID = tunnelTopic(secret, epoch, 'dialer', this.#peerDID);
+        const receiveTopicID = tunnelTopic(secret, epoch, 'responder', this.#localDID);
+        // A stop() that landed while we awaited the handle must abort the spawn.
+        if (this.#stopped) return;
+        // No sessionID: a responder locks to whatever session dials it, so the id
+        // is not known until the first frame. Everything else is, and `role` is what
+        // separates this listener's lines from the dialer's on the same device. The
+        // two now read disjoint topics, so `receiveTopicID` says the same thing —
+        // but it says it in a hash, and only the role says it at a glance.
+        const sessionLogger = this.#logger?.with({
+            role: 'listener',
+            groupID: this.#groupID,
+            peerDID: this.#peerDID,
+            epoch,
+            receiveTopicID
+        });
+        let transportRef;
+        const transport = createEncryptedHubTunnelTransport({
+            hub: peerHub,
+            encryptor,
+            groupID: this.#groupID,
+            sessionID: {
+                auto: true
+            },
+            localDID: this.#localDID,
+            sendTopicID,
+            receiveTopicID,
+            idleTimeoutMs: this.#idleTimeoutMs,
+            reconnectTimeoutMs: this.#reconnectTimeoutMs,
+            inboxCapacity: this.#inboxCapacity,
+            onEvent: sessionLogger == null ? this.#onEvent : createTunnelEventLogger(sessionLogger, this.#onEvent),
+            onSessionEnd: ()=>{
+                // Peer signaled end-of-session. Dispose the transport deterministically
+                // so the `disposed` event fires and the spawn loop re-arms for the
+                // next session arriving on the shared device drain.
+                void transportRef?.dispose().catch(()=>{
+                // ignore — best-effort
+                });
+            }
+        });
+        transportRef = transport;
+        // Setting identity forces requireAuth: the tunnel server verifies token
+        // signatures and that aud equals its own DID, matching the direct/HTTP sync
+        // servers. Per-scope authorization is handled uniformly by the merkle-sync
+        // scope-gate, not here.
+        const server = new Server({
+            runtime: this.#runtime,
+            handlers: this.#syncHandlers,
+            identity: this.#identity,
+            accessRules: {
+                'sync/*': {
+                    allow: true
+                }
+            },
+            transports: [
+                transport
+            ]
+        });
+        const session = {
+            transport,
+            server
+        };
+        this.#current = session;
+        // Defence in depth, and today only that: there is no `await` between the
+        // `#stopped` check above and this assignment, so a `stop()` cannot
+        // currently interleave into that window. The moment one is introduced —
+        // anything awaited while building the transport or the server — a `stop()`
+        // landing there would find `#current === undefined`, dispose nothing and
+        // return, while this spawn stood up a subscribed, draining transport that
+        // nothing holds a reference to. Re-checking after the assignment is what
+        // makes that a non-event: whichever side runs second does the teardown.
+        if (this.#stopped) {
+            this.#current = undefined;
+            try {
+                await transport.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+            try {
+                await server.dispose();
+            } catch  {
+            // ignore — best-effort teardown
+            }
+            return;
+        }
+        // `disposed` may fire more than once for a single session (disposing the
+        // server can re-enter the transport's dispose). Collapse to exactly one
+        // teardown + respawn so one session leaves exactly one successor.
+        let handled = false;
+        transport.events.on('disposed', ()=>{
+            if (handled) return;
+            handled = true;
+            if (this.#current === session) {
+                this.#current = undefined;
+            }
+            // Server stays around until its handlers drain; explicit cleanup here so
+            // long-running sessions don't leak server instances.
+            void server.dispose().catch(()=>{
+            // ignore
+            });
+            // Nothing re-arms the inbox here. This fires even after stop(), so a
+            // departing listener would be re-subscribing a topic it no longer uses on
+            // behalf of listeners it knows nothing about. The gap it was covering is
+            // closed at the source instead: the per-peer view never releases the
+            // topic, so the departing transport's teardown cannot empty it.
+            //
+            // Respawn for the next session. The next spawn re-derives the topics
+            // against the (possibly advanced) epoch, and survives failing to.
+            this.#spawnGuarded();
+        });
+    }
+}

package/lib/sync/hub-tunnel-sync-provider.d.ts

@@ -1,19 +1,42 @@
-import { type ObservabilityEventListener } from '@enkaku/hub-tunnel';
 import type { ClientTransportOf } from '@enkaku/protocol';
+import type { Logger } from '@kubun/logger';
+import { type ObservabilityEventListener } from '@kumiai/hub-tunnel';
+import type { Runtime } from '@sozai/runtime';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
-import type { HubConnection } from '../hub/hub-connection.js';
+import type { DeviceHub } from '../hub/hub-like.js';
 import type { SyncProtocol } from '../protocol.js';
 import type { SyncTransportProvider } from './sync-client.js';
 export type HubTunnelSyncProviderParams = {
-    hubConnection: HubConnection;
+    /**
+     * Shared multi-subscriber device hub (from `createHubLike`). Each session
+     * attaches its own sink to this device-wide drain, narrowed to the peer it
+     * dialled, and filters to `receiveTopicID`; lifecycle events ride
+     * `hub.events`.
+     */
+    hub: DeviceHub;
     registry: GroupHandleRegistry;
     groupID: string;
     localDID: string;
     peerDID: string;
+    /**
+     * Supplies the platform primitives, including the per-session id generator.
+     * Threaded in from the caller rather than defaulted here: this package runs on
+     * React Native and in the browser as well as on node, so the one runtime the
+     * host built has to reach every seam that mints an id.
+     */
+    runtime: Runtime;
     idleTimeoutMs?: number;
     reconnectTimeoutMs?: number;
     inboxCapacity?: number;
     onEvent?: ObservabilityEventListener;
+    /**
+     * Where this session's frame-level events and its open/close are recorded. A
+     * session that is handed nothing raises nothing until its idle timeout fires
+     * — half a minute later, from inside the dependency, naming neither the group
+     * nor the peer — so without this the only account of a starved dial is a
+     * stack trace with no message.
+     */
+    logger?: Logger;
 };
 export declare class HubTunnelSyncProvider implements SyncTransportProvider {
     #private;
@@ -21,16 +44,13 @@ export declare class HubTunnelSyncProvider implements SyncTransportProvider {
     /**
      * Build a fresh client transport for one tunnel sync session.
      *
-     * **Concurrent-call constraint:** the underlying `HubConnection` keys its
-     * tunnel inbox by `peerDID`, and only one inbox per peer can be registered
-     * at a time. Callers must therefore fully dispose the previous transport
-     * (via `client.dispose()`) before invoking `createSyncTransport` again for
-     * the same provider instance — otherwise the second call throws
-     * `Error('tunnelMessageStream: peerDID already registered')`.
-     *
-     * The default `SyncManager.merkleSyncWithPeer` flow already awaits
-     * `client.dispose()` in its `finally` block, so sequential sync calls are
-     * safe. Concurrent calls are not.
+     * The tunnel rides group-scoped, ROLE-scoped topics derived from the group's
+     * current MLS epoch secret: outbound frames publish to the peer's responder
+     * topic, and the transport subscribes to this device's own dialer topic —
+     * which the peer's listener writes its answers to and nothing else does.
+     * Topics rotate with the epoch, so a transport built in epoch N stops matching
+     * once a commit advances the group — callers create a new transport per
+     * session.
      */
-    createSyncTransport(signal?: AbortSignal): ClientTransportOf<SyncProtocol>;
+    createSyncTransport(signal?: AbortSignal): Promise<ClientTransportOf<SyncProtocol>>;
 }