@kubun/plugin-p2p 0.11.0 → 0.12.1

package/lib/index.js

@@ -3,41 +3,51 @@ import { Server } from '@enkaku/server';
 import { DirectTransports } from '@enkaku/transport';
 import { isFullIdentity } from '@kokuin/token';
 import { resolveAllowedOrigin } from '@kubun/http-util';
+import { getGraphStore } from '@kubun/store-graph';
 import { p2pStoreDefinition } from '@kubun/store-p2p';
 import { createDelegationContext } from './context/delegation.js';
 import { createGroupContext } from './context/group.js';
 import { createHubContext } from './context/hub.js';
 import { createJoinContext } from './context/join.js';
+import { createPeerContext, serveGroupInvite, servePushControl } from './context/peer.js';
 import { createSyncContext } from './context/sync.js';
 import { createP2PEventEmitter } from './groups/events.js';
 import { GroupHandleRegistry } from './groups/group-handle-registry.js';
 import { GroupHealthMonitor } from './groups/group-health-monitor.js';
 import { GroupManager } from './groups/manager.js';
 import { createHTTPHubClient } from './hub/http-client.js';
-import { captureServerDID } from './hub/manager.js';
-import { DISABLED_HUB, setupHubRelay } from './hub/wiring.js';
+import { setupHubRelay } from './hub/wiring.js';
+import { PeerConnectionRegistry } from './peer/connection-registry.js';
+import { createPeerHandlers } from './peer/handlers.js';
 import { createP2PSchemaExtension } from './schema.js';
+import { wireAccessDefaultSender } from './sync/access-default-sender.js';
 import { createBroadcastQueue, DEFAULT_BROADCAST_BATCH_CONFIG } from './sync/broadcast-queue.js';
 import { DEFAULT_PUSH_SYNC_CONFIG, wireBroadcastSender } from './sync/broadcast-sender.js';
 import { createSyncHandlers } from './sync/handlers.js';
 import { SyncManager } from './sync/sync-manager.js';
-// ---- Re-exports: groups ----
-export { ADMIN_ROLE_ENTRY_TYPE, ADMIN_ROSTER_PROJECTION, adminRosterReducer, applyAdminEntryIncremental, foldAdminRoster, projectAdminRoster, projectAdminRosterFromStore, reprojectAdminRoster } from './groups/admin-roster.js';
+export { GROUP_CONTROL_DENIED, LAST_GROUP_ADMIN, NOT_GROUP_ADMIN, requireGroupAdmin } from './context/require-admin.js';
+export { ADMIN_ROLE_ENTRY_TYPE, foldAdminRoster } from './groups/admin-roster.js';
 export { processBroadcast } from './groups/broadcast.js';
 export { deserializeBroadcast, serializeBroadcast } from './groups/broadcast-codec.js';
 export { createFilteredGenerator, createP2PEventEmitter } from './groups/events.js';
-export { groupAnchorCapabilities, readGroupAnchor } from './groups/group-anchor.js';
+export { buildKubunGroupAnchorExtension, readRecoverySecret } from './groups/group-anchor.js';
 export { GroupHandleRegistry } from './groups/group-handle-registry.js';
 export { decodeFullJoinRequest, decodeInvitePayload, decodeJoinRequest, encodeFullJoinRequest, encodeInvitePayload, encodeJoinRequest } from './groups/invite-payload.js';
-export { ledgerEntryDigest, signLedgerEntry, verifyLedgerEntry } from './groups/ledger-entry.js';
-export { foldLedger } from './groups/ledger-fold.js';
-export { GroupManager } from './groups/manager.js';
+export { resolveJoinRequestDID } from './groups/join-request-identity.js';
+export { entryOrd, foldLedgerEntries, ledgerEntryDigest, signLedgerEntry, verifyLedgerEntry } from './groups/ledger.js';
 export { MLSEncryptor } from './groups/mls-encryptor.js';
 export { restoreMLSGroupHandle } from './groups/mls-group-handle.js';
 export { replacer as mlsJSONReplacer, reviver as mlsJSONReviver } from './groups/mls-json.js';
 export { deserializeMLSGroupState, serializeMLSGroupState } from './groups/mls-state.js';
+export { MERKLE_SYNC_PROTOCOL } from './groups/peer-selection.js';
+export { createHTTPHubClient } from './hub/http-client.js';
+export { bindHubToGroup, createHub, deleteHub, getHub, listGroupsByHub, listHubs, listHubsByGroup, unbindHubFromGroup, updateHub, upsertHub } from './hub/manager.js';
+export { createHubServerDIDResolver, fetchHubInfo } from './hub/server-did.js';
+export { setupHubRelay } from './hub/wiring.js';
+export { PeerConnectionRegistry } from './peer/connection-registry.js';
+export { createPeerHandlers } from './peer/handlers.js';
+export { peerProtocol } from './protocol.js';
 export { createP2PSchemaExtension } from './schema.js';
-// ---- Re-exports: sync ----
 export { createBroadcastQueue, DEFAULT_BROADCAST_BATCH_CONFIG } from './sync/broadcast-queue.js';
 export { DEFAULT_PUSH_SYNC_CONFIG, wireBroadcastSender } from './sync/broadcast-sender.js';
 export { resolveCatalogSyncScopes } from './sync/catalog-scope.js';
@@ -49,18 +59,12 @@ export { HubTunnelSyncProvider } from './sync/hub-tunnel-sync-provider.js';
 export { negotiateDirection, PeerRegistry } from './sync/peer-registry.js';
 export { SyncClient } from './sync/sync-client.js';
 export { SyncManager } from './sync/sync-manager.js';
-// ---- Re-exports: hub ----
-export { DIDObservingTransport } from './hub/did-observing-transport.js';
-export { createHTTPHubClient } from './hub/http-client.js';
-export { bindHubToGroup, captureServerDID, createHub, deleteHub, getHub, HubServerDIDConflictError, listGroupsByHub, listHubs, listHubsByGroup, unbindHubFromGroup, updateHub, upsertHub } from './hub/manager.js';
-export { DISABLED_HUB, setupHubRelay } from './hub/wiring.js';
 /**
  * Default receive config. Under `'persist'` no gate is built and no extra
  * DB lookups occur during receive.
  */ export const DEFAULT_RECEIVE_CONFIG = {
     storeUnreadable: 'persist'
 };
-// ---- Plugin factory ----
 function isOwnIdentity(identity) {
     return isFullIdentity(identity) && 'privateKey' in identity;
 }
@@ -79,7 +83,6 @@ export function createP2PPlugin(options) {
         // than identical ones (the second of which would silently lose under
         // last-writer-wins).
         const hlc = params.hlc;
-        // ---- Receive config ----
         // Computed up front so SyncManager + sync handlers + the hub-relay
         // BroadcastService all see the same receive policy. Hot-path invariant:
         // when `storeUnreadable === 'persist'` (default), no gate is built and
@@ -92,9 +95,8 @@ export function createP2PPlugin(options) {
             read: 'only_owner',
             write: 'only_owner'
         };
-        // ---- Group handle registry ----
         // Single canonical access point for the device's MLS GroupHandle instances.
-        // Threaded through GroupManager + BroadcastService + (Phase 4) tunnel
+        // Threaded through GroupManager + BroadcastService + the tunnel
         // listener/provider so all five mutation paths serialize through one
         // per-group mutex with write-through persist.
         const registry = new GroupHandleRegistry({
@@ -102,27 +104,47 @@ export function createP2PPlugin(options) {
             deviceID: identity.id,
             logger: params.getLogger('group-handle-registry')
         });
-        // ---- Group manager ----
+        const emitter = createP2PEventEmitter();
+        // `stores` + `emitter` are the lane-side wiring: a commit's `onAccepted`
+        // fires decoupled from the resolver that started it, so it folds this
+        // device's own committed entries on the device-wide connection and emits the
+        // resulting domain events itself.
         const groupManager = new GroupManager({
             identity,
-            getRandomID: params.runtime.getRandomID,
+            runtime: params.runtime,
             registry,
-            hlc
+            hlc,
+            stores: params.db,
+            emitter,
+            logger: params.getLogger('group-manager')
         });
-        const emitter = createP2PEventEmitter();
         const groupHealthMonitor = new GroupHealthMonitor({
             emitter,
             logger: params.getLogger('group-health-monitor')
         });
-        // ---- Sync manager ----
         const syncManager = new SyncManager({
             deployClusters: async (clusters)=>{
                 // Values are ClusterModel objects serialized through the protocol —
                 // cast through unknown since SyncManager doesn't depend on protocol types.
                 const clusterModels = Object.values(clusters);
-                await params.engine.deployGraph({
-                    clusters: clusterModels
-                });
+                // Into the graphs this device already syncs on, never a fresh one. A
+                // received model deployed under a new id gets its tables and nothing
+                // else: the document lands and the device's own graph — the one its app
+                // queries — has no schema for it, so the model reads as absent while
+                // being present. Deployed WITHOUT `plugins`, which leaves each graph's
+                // existing extension SDL and plugin config untouched.
+                const graphStore = await getGraphStore(params.db);
+                const targets = (await graphStore.listGraphs()).filter((graph)=>graph.plugin_config != null && 'p2p' in graph.plugin_config);
+                if (targets.length === 0) {
+                    params.getLogger('sync').warn('Received clusters but no p2p-enabled graph to deploy them into');
+                    return;
+                }
+                for (const graph of targets){
+                    await params.engine.deployGraph({
+                        id: graph.id,
+                        clusters: clusterModels
+                    });
+                }
             },
             graph: params.graph,
             runtime: params.runtime,
@@ -140,9 +162,12 @@ export function createP2PPlugin(options) {
             storeUnreadable: receiveConfig.storeUnreadable,
             defaultAccessLevel
         });
-        // ---- Pending join requests (for CLI peering flow) ----
-        const pendingJoinRequests = new Map();
-        // ---- Sync server ----
+        // In-memory registry of live peer connections, keyed by remote DID. Written
+        // by `connectPeer`; nothing persisted. Plugin-scoped so a connection
+        // outlives a single GraphQL request.
+        const peerConnections = new PeerConnectionRegistry({
+            logger: params.getLogger('peer-connections')
+        });
         // The p2p plugin manages its own Enkaku server for sync handlers,
         // separate from plugin-rpc's graph server.
         const syncServers = [];
@@ -151,7 +176,7 @@ export function createP2PPlugin(options) {
                 signal
             });
             const server = new Server({
-                getRandomID: params.runtime.getRandomID,
+                runtime: params.runtime,
                 handlers: syncHandlers,
                 identity,
                 // Open at the procedure layer by design: the sync protocol's
@@ -171,48 +196,95 @@ export function createP2PPlugin(options) {
             syncServers.push(server);
             return directTransports.client;
         }
-        // ---- Hub relay ----
         const hubRelayLogger = params.getLogger('hub-relay');
-        let hub = DISABLED_HUB;
         let unwireBroadcastSender;
+        let unwireAccessDefaultSender;
         let broadcastQueue;
         const pushSyncConfig = {
             ...DEFAULT_PUSH_SYNC_CONFIG,
             ...options?.pushSync
         };
+        // The relay always runs: it is what gives every joined group a commit lane,
+        // including a group with no hub bound (which commits against an in-process
+        // loopback log). Hub clients are only ever spawned for a group that has a
+        // hub row, so a device configured without hubs opens no connection.
+        const createHubClient = typeof options?.hub === 'object' && options.hub.createHubClient != null ? options.hub.createHubClient : createHTTPHubClient({
+            identity,
+            fetch: params.runtime.fetch
+        });
+        const hubReconnectBackoff = typeof options?.hub === 'object' ? options.hub.reconnectBackoff : undefined;
+        const hub = setupHubRelay({
+            identity,
+            runtime: params.runtime,
+            db: params.db,
+            hlc,
+            graph: params.graph,
+            emitter,
+            createHubClient,
+            registry,
+            // Re-drive a lost `ledger` commit's surviving tokens through the group
+            // manager's own ledger write path, so the seam stays a consumer of it.
+            buildLedgerRedrive: (groupID, tokens, requestID)=>groupManager.buildEnactLedgerCommit({
+                    groupID,
+                    tokens,
+                    requestID
+                }),
+            logger: hubRelayLogger,
+            storeUnreadable: receiveConfig.storeUnreadable,
+            defaultAccessLevel,
+            forwarding: options?.forwarding,
+            ...hubReconnectBackoff != null ? {
+                hubReconnectBackoff
+            } : {},
+            ...options?.tunnelIdleTimeoutMs != null ? {
+                tunnelIdleTimeoutMs: options.tunnelIdleTimeoutMs
+            } : {},
+            // The same handlers the direct and HTTP transports serve — a tunnel is a
+            // route, so it must not reach a different sync implementation.
+            syncHandlers: syncHandlers
+        });
+        // Turn a `tunnel://<groupID>/<peerDID>` route into a live session over the
+        // group's hub. Until this existed the scheme parsed and then failed at
+        // "Server resolver not configured", so every device could only be reached by
+        // URL — the topology this design retires.
+        //
+        // Route resolution only. A resolver hands back a transport; what the far end
+        // serves over it is decided per document there, so nothing here can widen
+        // what a peer may read.
+        syncManager.setServerResolver((serverID, route)=>{
+            if (route == null) {
+                // `direct://` — in-process peers, which only a test wires by hand.
+                return undefined;
+            }
+            // Built lazily: the hub relay binds asynchronously, and a resolver that
+            // waited for it here would have to be async, which this seam is not.
+            return {
+                createSyncTransport: async (signal)=>{
+                    const provider = await hub.syncTransportTo(route.groupID, serverID);
+                    if (provider == null) {
+                        throw new Error(`No hub bound for group ${route.groupID}: cannot open a tunnel`);
+                    }
+                    return await provider.createSyncTransport(signal);
+                }
+            };
+        });
         if (options?.hub) {
-            const createHubClient = typeof options.hub === 'object' && options.hub.createHubClient != null ? options.hub.createHubClient : createHTTPHubClient({
-                identity,
-                fetch: params.runtime.fetch
-            });
-            hub = setupHubRelay({
-                identity,
-                getRandomID: params.runtime.getRandomID,
+            // Replicate this peer's own model access-defaults to co-members.
+            // Control-plane, not document push-sync: always wired when a hub exists so
+            // an owner's sharing policy reaches members that must evaluate its docs.
+            unwireAccessDefaultSender = wireAccessDefaultSender({
                 db: params.db,
-                hlc,
-                graph: params.graph,
-                emitter,
-                createHubClient,
-                registry,
-                logger: hubRelayLogger,
-                storeUnreadable: receiveConfig.storeUnreadable,
-                defaultAccessLevel,
-                // TOFU capture. The pool fires this once per fresh client when the
-                // first signed response arrives. Manager-level conflicts are caught
-                // and logged inside the pool; the pinned-DID mismatch path surfaces
-                // a typed error to callers via the transport wrapper.
-                onServerDIDObserved: ({ hubURL, serverDID })=>captureServerDID({
-                        stores: params.db,
-                        hubURL,
-                        serverDID
-                    }).then(()=>undefined)
+                eventBus: params.eventBus,
+                identity,
+                scheduleBroadcast: hub.scheduleBroadcast,
+                logger: params.getLogger('access-default-sender')
             });
             // Subscribe to locally-authored mutations and fan out per-scope
             // `mutation:apply` broadcasts through the hub. Gated independently from
             // the hub itself: the hub is needed for receive + pull regardless, but
-            // push-sync is opt-in via `pushSync.enabled`. With `DISABLED_HUB` we'd
-            // also skip wiring (scheduleBroadcast no-ops + spurious broadcast_log
-            // rows), but the explicit gate here makes intent observable.
+            // push-sync is opt-in via `pushSync.enabled`. Without the gate an
+            // unconfigured device would still accrue broadcast_log rows for sends that
+            // reach no hub-backed peer.
             if (pushSyncConfig.enabled) {
                 const batchConfig = {
                     ...DEFAULT_BROADCAST_BATCH_CONFIG,
@@ -232,7 +304,60 @@ export function createP2PPlugin(options) {
                 });
             }
         }
-        // ---- Plugin API ----
+        // Single builder for the per-request ContextDeps, shared by the GraphQL
+        // context factory and the peer-procedure runners. Reads `hub` at call time
+        // so the hub wiring assigned above is always current.
+        function buildContextDeps(stores) {
+            return {
+                identity,
+                groupManager,
+                registry,
+                syncManager,
+                peerConnections,
+                stores,
+                deviceStores: params.db,
+                adapter,
+                hlc,
+                emitter,
+                runtime: params.runtime,
+                autoAcceptPeers: options?.autoAcceptPeers,
+                ...options?.inviteCommitTimeoutMs != null ? {
+                    inviteCommitTimeoutMs: options.inviteCommitTimeoutMs
+                } : {},
+                scheduleBroadcast: hub.scheduleBroadcast,
+                broadcastNow: hub.broadcastNow,
+                commitToGroup: hub.commitToGroup,
+                monitor: groupHealthMonitor,
+                rejoinGroup: hub.rejoinGroup,
+                requestLedgerCatchup: hub.requestLedgerCatchup,
+                logger: params.getLogger('context')
+            };
+        }
+        // The dance runners reuse the SAME join context ops the GraphQL mutations
+        // use, executed on behalf of the verified caller against the plugin's own
+        // DB (peer procedures run outside an engine transaction; `joinGroup` manages
+        // its own inner transaction). No MLS logic is reimplemented here.
+        const peerHandlers = createPeerHandlers({
+            db: params.db,
+            identity,
+            logger: params.getLogger('peer-handlers'),
+            autoAcceptPeers: options?.autoAcceptPeers,
+            runPrepareJoin: (callerDID)=>createJoinContext({
+                    viewerDID: callerDID
+                }, buildContextDeps(params.db)).prepareRequest(),
+            runCompleteJoin: (callerDID, invitePayload)=>createJoinContext({
+                    viewerDID: callerDID
+                }, buildContextDeps(params.db)).complete(invitePayload),
+            runInvite: (callerDID, groupID, joinRequest)=>serveGroupInvite(buildContextDeps(params.db), {
+                    callerDID,
+                    groupID,
+                    joinRequest
+                }),
+            runPushControl: (callerDID, param)=>servePushControl(buildContextDeps(params.db), {
+                    callerDID,
+                    ...param
+                })
+        });
         const pluginAPI = {
             hubReady: hub.ready,
             addPeer: (config)=>syncManager.addPeer({
@@ -254,12 +379,28 @@ export function createP2PPlugin(options) {
                     peerDID,
                     stores: params.db
                 }),
+            // Through the same context the GraphQL surface uses, as the peer-procedure
+            // runners do: the scopes an automatic catch-up asks for cannot drift from
+            // the ones an explicit one asks for if there is only one implementation.
+            catchUpWithBestPeer: (groupID)=>createSyncContext(null, buildContextDeps(params.db)).catchUpWithBestPeer(groupID),
+            listPeerDevices: (groupID)=>createSyncContext(null, buildContextDeps(params.db)).listPeerDevices(groupID),
             onSyncEvent: (callback)=>syncManager.onSyncEvent(callback),
-            createSyncTransport
+            onHubServerDIDChanged: (listener)=>emitter.on('hubServerDIDChanged', listener),
+            createSyncTransport,
+            requestLedgerCatchup: (groupID, options)=>hub.requestLedgerCatchup(groupID, options),
+            setLocalPeerProfile: async (profile)=>{
+                await (await hub.presence()).setProfile(profile);
+            },
+            getLocalPeerProfile: async ()=>await (await hub.presence()).getProfile(),
+            gatherPeers: async (groupID, options)=>await (await hub.presence()).gather(groupID, options),
+            refreshPeerPresence: async (groupID, options)=>await (await hub.presence()).refresh(groupID, options),
+            retryHubConnection: async ()=>await hub.retryHubs(),
+            getPeerConnection: (peerDID)=>peerConnections.get(peerDID)
         };
-        // ---- HTTP sync transport (optional) ----
         let httpSyncTransport;
         let httpSyncServer;
+        let httpPeerTransport;
+        let httpPeerServer;
         if (options?.http) {
             // Capture in the outer scope so the union is narrowed before the async
             // closure below (re-reading options.http inside the IIFE would widen it).
@@ -283,7 +424,7 @@ export function createP2PPlugin(options) {
                     maxRequestBodySize
                 });
                 httpSyncServer = new Server({
-                    getRandomID: params.runtime.getRandomID,
+                    runtime: params.runtime,
                     handlers: syncHandlers,
                     identity,
                     // Open at the procedure layer by design: the sync protocol's
@@ -301,39 +442,52 @@ export function createP2PPlugin(options) {
                 });
                 syncServers.push(httpSyncServer);
                 httpAPI.registerProtocol(protocolName, httpSyncTransport.fetch.bind(httpSyncTransport));
+                // Mount the peer protocol alongside sync, advertised under its own
+                // well-known name so a connecting device discovers it in `/info`. Same
+                // CORS + body-limit policy as the sync surface. Its procedure layer is
+                // open (`allow: true`); `peer/groups` gates the verified caller in the
+                // handler via `checkPeerAccess`, mirroring the dance mutations.
+                httpPeerTransport = new ServerTransport({
+                    allowedOrigin,
+                    maxRequestBodySize
+                });
+                httpPeerServer = new Server({
+                    runtime: params.runtime,
+                    handlers: peerHandlers,
+                    identity,
+                    // Open at the procedure layer, like the sync server: each peer handler
+                    // gates the verified caller itself (forged-`sub` rejection +
+                    // `checkPeerAccess`). Covers `peer/*` and the dance `group/*`.
+                    accessRules: {
+                        'peer/*': {
+                            allow: true
+                        },
+                        'group/*': {
+                            allow: true
+                        }
+                    },
+                    logger: params.getLogger('peer-http-server'),
+                    transports: [
+                        httpPeerTransport
+                    ]
+                });
+                httpAPI.registerProtocol('peer', httpPeerTransport.fetch.bind(httpPeerTransport));
             })();
         }
         return {
             name: 'p2p',
-            schemaExtension: (_config)=>createP2PSchemaExtension(emitter, params.getLogger('p2p-schema')),
+            schemaExtension: (_config)=>createP2PSchemaExtension(emitter, syncManager, params.getLogger('p2p-schema')),
             api: pluginAPI,
             createContextFactory: ()=>{
                 return (ctx, stores)=>{
-                    const deps = {
-                        identity,
-                        groupManager,
-                        registry,
-                        syncManager,
-                        stores,
-                        adapter,
-                        hlc,
-                        emitter,
-                        pendingJoinRequests,
-                        runtime: params.runtime,
-                        autoAcceptPeers: options?.autoAcceptPeers,
-                        scheduleBroadcast: hub.scheduleBroadcast,
-                        broadcastNow: hub.broadcastNow,
-                        scheduleSendCommit: hub.scheduleSendCommit,
-                        monitor: groupHealthMonitor,
-                        rejoinGroup: hub.rejoinGroup,
-                        logger: params.getLogger('context')
-                    };
+                    const deps = buildContextDeps(stores);
                     return {
                         group: createGroupContext(ctx, deps),
                         sync: createSyncContext(ctx, deps),
                         join: createJoinContext(ctx, deps),
                         hub: createHubContext(ctx, deps),
-                        delegation: createDelegationContext(ctx, deps)
+                        delegation: createDelegationContext(ctx, deps),
+                        peer: createPeerContext(ctx, deps)
                     };
                 };
             },
@@ -347,6 +501,13 @@ export function createP2PPlugin(options) {
                     // ignore
                     }
                 }
+                if (unwireAccessDefaultSender != null) {
+                    try {
+                        unwireAccessDefaultSender();
+                    } catch  {
+                    // ignore
+                    }
+                }
                 // Synchronously drain the batch queue BEFORE other teardown so any
                 // pending broadcasts ship through the still-live hub transport.
                 if (broadcastQueue != null) {
@@ -356,25 +517,35 @@ export function createP2PPlugin(options) {
                     // ignore
                     }
                 }
-                // Sync HTTP server depends on httpSyncTransport — dispose servers
-                // first, then the transport. Runs in parallel with syncManager and
+                // Tear down every live outbound peer connection (client + transport).
+                const peerConnectionsPath = peerConnections.disposeAll();
+                // Sync + peer HTTP servers depend on their transports — dispose servers
+                // first, then the transports. Runs in parallel with syncManager and
                 // hub teardown, which have no such dependency.
                 const httpPath = (async ()=>{
                     for (const server of syncServers){
                         await server.dispose();
                     }
+                    if (httpPeerServer != null) {
+                        await httpPeerServer.dispose();
+                    }
                     if (httpSyncTransport != null) {
                         await httpSyncTransport.dispose();
                     }
+                    if (httpPeerTransport != null) {
+                        await httpPeerTransport.dispose();
+                    }
                 })();
                 const disposeLogger = params.getLogger('dispose');
                 const results = await Promise.allSettled([
                     httpPath,
+                    peerConnectionsPath,
                     syncManager.dispose(),
                     hub.dispose()
                 ]);
                 const labels = [
                     'sync-http',
+                    'peer-connections',
                     'sync-manager',
                     'hub'
                 ];

package/lib/peer/connection-registry.d.ts

@@ -0,0 +1,45 @@
+import type { Client } from '@enkaku/client';
+import type { ClientTransport } from '@enkaku/http-fetch';
+import type { Logger } from '@kubun/logger';
+import type { PeerProtocol } from '../protocol.js';
+/**
+ * A live, in-memory connection to a remote peer. Holds the Enkaku client used
+ * to dispatch peer procedures plus the transport it rides, so the connection
+ * can be torn down cleanly on replacement or plugin dispose. Nothing here is
+ * persisted — a connection lives only for the process, keyed by `peerDID`.
+ */
+export type PeerConnection = {
+    peerDID: string;
+    /** Base URL the peer was reached at (the `connectPeer` argument). */
+    endpoint: string;
+    /**
+     * Fully-resolved sync-protocol endpoint discovered from the peer's `/info`.
+     * Recorded at connect so `sharePeerGroup` can register the sync peer without
+     * re-fetching `/info` or assuming the default `/sync` path.
+     */
+    syncEndpoint: string;
+    client: Client<PeerProtocol>;
+    transport: ClientTransport<PeerProtocol>;
+};
+/**
+ * In-memory registry of live peer connections, keyed by `peerDID`. A second
+ * `connectPeer` to the same DID replaces the prior entry and disposes the old
+ * client + transport, so a stale connection is never leaked. Purely ephemeral:
+ * durable peer state (endpoint, DID) lives in the peer registry, written by the
+ * later dance ops — not here.
+ */
+export declare class PeerConnectionRegistry {
+    #private;
+    constructor(params: {
+        logger: Logger;
+    });
+    /**
+     * Register a connection, replacing (and disposing) any existing connection
+     * for the same `peerDID`.
+     */
+    set(connection: PeerConnection): Promise<void>;
+    get(peerDID: string): PeerConnection | undefined;
+    list(): Array<PeerConnection>;
+    /** Dispose every held connection and clear the registry. */
+    disposeAll(): Promise<void>;
+}

package/lib/peer/connection-registry.js

@@ -0,0 +1,52 @@
+/**
+ * In-memory registry of live peer connections, keyed by `peerDID`. A second
+ * `connectPeer` to the same DID replaces the prior entry and disposes the old
+ * client + transport, so a stale connection is never leaked. Purely ephemeral:
+ * durable peer state (endpoint, DID) lives in the peer registry, written by the
+ * later dance ops — not here.
+ */ export class PeerConnectionRegistry {
+    #connections = new Map();
+    #logger;
+    constructor(params){
+        this.#logger = params.logger;
+    }
+    /**
+   * Register a connection, replacing (and disposing) any existing connection
+   * for the same `peerDID`.
+   */ async set(connection) {
+        const existing = this.#connections.get(connection.peerDID);
+        if (existing != null) {
+            await this.#dispose(existing);
+        }
+        this.#connections.set(connection.peerDID, connection);
+    }
+    get(peerDID) {
+        return this.#connections.get(peerDID);
+    }
+    list() {
+        return Array.from(this.#connections.values());
+    }
+    /** Dispose every held connection and clear the registry. */ async disposeAll() {
+        const all = Array.from(this.#connections.values());
+        this.#connections.clear();
+        await Promise.all(all.map((connection)=>this.#dispose(connection)));
+    }
+    async #dispose(connection) {
+        try {
+            await connection.client.dispose();
+        } catch (error) {
+            this.#logger.debug('peer client dispose failed', {
+                peerDID: connection.peerDID,
+                error
+            });
+        }
+        try {
+            await connection.transport.dispose();
+        } catch (error) {
+            this.#logger.debug('peer transport dispose failed', {
+                peerDID: connection.peerDID,
+                error
+            });
+        }
+    }
+}