@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/index.js

@@ -1 +1,563 @@
-import{ServerTransport as e}from"@enkaku/http-server-transport";import{Server as r}from"@enkaku/server";import{isFullIdentity as t}from"@enkaku/token";import{DirectTransports as o}from"@enkaku/transport";import{p2pStoreDefinition as s}from"@kubun/store-p2p";import{createDelegationContext as n}from"./context/delegation.js";import{createGroupContext as a}from"./context/group.js";import{createHubContext as i}from"./context/hub.js";import{createJoinContext as c}from"./context/join.js";import{createSyncContext as p}from"./context/sync.js";import{createP2PEventEmitter as d}from"./groups/events.js";import{GroupHandleRegistry as u}from"./groups/group-handle-registry.js";import{GroupHealthMonitor as l}from"./groups/group-health-monitor.js";import{GroupManager as g}from"./groups/manager.js";import{forwardRemoteBroadcast as m}from"./hub/forward-remote-broadcast.js";import{createHTTPHubClient as y}from"./hub/http-client.js";import{captureServerDID as b}from"./hub/manager.js";import{DISABLED_HUB as f,setupHubRelay as h}from"./hub/wiring.js";import{createP2PSchemaExtension as j}from"./schema.js";import{createBroadcastQueue as v,DEFAULT_BROADCAST_BATCH_CONFIG as x}from"./sync/broadcast-queue.js";import{DEFAULT_PUSH_SYNC_CONFIG as w,wireBroadcastSender as S}from"./sync/broadcast-sender.js";import{createSyncHandlers as D}from"./sync/handlers.js";import{SyncManager as R}from"./sync/sync-manager.js";export{processBroadcast}from"./groups/broadcast.js";export{deserializeBroadcast,serializeBroadcast}from"./groups/broadcast-codec.js";export{ApplyError,BroadcastService,DecryptError}from"./groups/broadcast-service.js";export{createFilteredGenerator,createP2PEventEmitter}from"./groups/events.js";export{GroupHandleRegistry}from"./groups/group-handle-registry.js";export{decodeFullJoinRequest,decodeInvitePayload,decodeJoinRequest,encodeFullJoinRequest,encodeInvitePayload,encodeJoinRequest}from"./groups/invite-payload.js";export{GroupManager}from"./groups/manager.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{createP2PSchemaExtension}from"./schema.js";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";export{SyncAccessDeniedError}from"./sync/errors.js";export{evaluateAndForward}from"./sync/forwarder.js";export{checkSyncDelegation}from"./sync/handlers.js";export{HubTunnelSyncListener}from"./sync/hub-tunnel-sync-listener.js";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";export{DIDObservingTransport}from"./hub/did-observing-transport.js";export{ReconnectingError}from"./hub/errors.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{HubRelayManager}from"./hub/relay-manager.js";export{DISABLED_HUB,setupHubRelay}from"./hub/wiring.js";export const DEFAULT_RECEIVE_CONFIG={storeUnreadable:"persist"};export function createP2PPlugin(P){return I=>{var E;let H,L,B,C;I.db.register(s);let G=I.db.adapter;if(!(t(E=I.identity)&&"privateKey"in E))throw Error("createP2PPlugin requires an OwnIdentity (full identity with privateKey) — received a narrower Identity");let A=I.identity,F=I.hlc,T={...DEFAULT_RECEIVE_CONFIG,...P?.receive},U=P?.defaultAccessLevel??{read:"only_owner",write:"only_owner"},_=new u({stores:I.db,deviceID:A.id,logger:I.getLogger("group-handle-registry")}),k=new g({identity:A,getRandomID:I.runtime.getRandomID,registry:_,hlc:F}),O=d(),q=new l({emitter:O}),N=new R({deployClusters:async e=>{let r=Object.values(e);await I.engine.deployGraph({clusters:r})},graph:I.graph,runtime:I.runtime,identity:I.identity,logger:I.getLogger("sync"),storeUnreadable:T.storeUnreadable,defaultAccessLevel:U}),M=D({db:I.db,graph:I.graph,logger:I.getLogger("sync-handlers"),peerRegistry:N.peerRegistry,selfDID:A.id,storeUnreadable:T.storeUnreadable,defaultAccessLevel:U}),J=new Map,z=[],K=I.getLogger("hub-relay"),V=f,W={...w,...P?.pushSync};if(P?.hub){let e="object"==typeof P.hub&&null!=P.hub.createHubClient?P.hub.createHubClient:y({identity:A,fetch:I.runtime.fetch});V=h({identity:A,getRandomID:I.runtime.getRandomID,db:I.db,hlc:F,graph:I.graph,emitter:O,createHubClient:e,registry:_,monitor:q,onRemoteBroadcast:e=>{m(O,e,K).catch(e=>{K.error("forwardRemoteBroadcast failed",{error:e})})},logger:K,storeUnreadable:T.storeUnreadable,defaultAccessLevel:U,forwarding:P.forwarding,onServerDIDObserved:({hubURL:e,serverDID:r})=>b({stores:I.db,hubURL:e,serverDID:r}).then(()=>void 0)}),W.enabled&&(L=v({config:{...x,...P.batch},scheduleBroadcast:V.scheduleBroadcast,logger:I.getLogger("broadcast-queue")}),H=S({db:I.db,eventBus:I.eventBus,selfDID:A.id,queue:L,logger:I.getLogger("broadcast-sender")}))}let Q={hubReady:V.ready,addPeer:e=>N.addPeer({config:e,stores:I.db}),removePeer:e=>N.removePeer({peerDID:e,stores:I.db}),listPeers:()=>N.listPeers({stores:I.db}),syncWithPeer:e=>N.merkleSyncWithPeer({...e,stores:I.db}),getStatus:e=>N.getStatus({peerDID:e,stores:I.db}),onSyncEvent:e=>N.onSyncEvent(e),createSyncTransport:function(e){let t=new o({signal:e}),s=new r({getRandomID:I.runtime.getRandomID,handlers:M,identity:A,accessRules:{"sync/*":{allow:!0}},logger:I.getLogger("sync-server"),transports:[t.server],signal:e});return z.push(s),t.client}};if(P?.http){let t=P.http,o=("string"==typeof t?t:"object"==typeof t?t.path??"sync":"sync").replace(/^\//,""),s="object"==typeof t?t.allowedOrigin??["*"]:["*"];Q.syncReady=(async()=>{let t=await I.engine.getAPI("http");await t.listening,B=new e({allowedOrigin:s}),C=new r({getRandomID:I.runtime.getRandomID,handlers:M,identity:A,accessRules:{"sync/*":{allow:!0}},logger:I.getLogger("sync-http-server"),transports:[B]}),z.push(C),t.registerProtocol(o,B.fetch.bind(B))})()}return{name:"p2p",schemaExtension:e=>j(O),api:Q,createContextFactory:()=>(e,r)=>{let t={identity:A,groupManager:k,registry:_,syncManager:N,stores:r,adapter:G,hlc:F,emitter:O,pendingJoinRequests:J,runtime:I.runtime,autoAcceptPeers:P?.autoAcceptPeers,scheduleBroadcast:V.scheduleBroadcast,broadcastNow:V.broadcastNow,scheduleSendCommit:V.scheduleSendCommit,monitor:q,rejoinGroup:V.rejoinGroup,logger:I.getLogger("context")};return{group:a(e,t),sync:p(e,t),join:c(e,t),hub:i(e,t),delegation:n(e,t)}},dispose:async()=>{if(null!=H)try{H()}catch{}if(null!=L)try{L.dispose()}catch{}let e=(async()=>{for(let e of z)await e.dispose();null!=B&&await B.dispose()})(),r=I.getLogger("dispose"),t=await Promise.allSettled([e,N.dispose(),V.dispose()]),o=["sync-http","sync-manager","hub"];t.forEach((e,t)=>{"rejected"===e.status&&r.error("dispose branch failed",{branch:o[t],error:e.reason})})}}}}
+import { ServerTransport } from '@enkaku/http-serve';
+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 { 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';
+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 { 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 { 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';
+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';
+export { SyncAccessDeniedError } from './sync/errors.js';
+export { evaluateAndForward } from './sync/forwarder.js';
+export { checkSyncDelegation } from './sync/handlers.js';
+export { HubTunnelSyncListener } from './sync/hub-tunnel-sync-listener.js';
+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';
+/**
+ * Default receive config. Under `'persist'` no gate is built and no extra
+ * DB lookups occur during receive.
+ */ export const DEFAULT_RECEIVE_CONFIG = {
+    storeUnreadable: 'persist'
+};
+function isOwnIdentity(identity) {
+    return isFullIdentity(identity) && 'privateKey' in identity;
+}
+export function createP2PPlugin(options) {
+    return (params)=>{
+        params.db.register(p2pStoreDefinition);
+        const adapter = params.db.adapter;
+        if (!isOwnIdentity(params.identity)) {
+            throw new Error('createP2PPlugin requires an OwnIdentity (full identity with privateKey) — received a narrower Identity');
+        }
+        const identity = params.identity;
+        // The engine's single device-wide clock. Sharing it across the p2p group/
+        // circle/member metadata paths (context, GroupManager, BroadcastService)
+        // keeps every write from this device on one monotonic counter, so two
+        // writes in the same millisecond mint strictly-increasing timestamps rather
+        // than identical ones (the second of which would silently lose under
+        // last-writer-wins).
+        const hlc = params.hlc;
+        // 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
+        // no extra DB lookups occur.
+        const receiveConfig = {
+            ...DEFAULT_RECEIVE_CONFIG,
+            ...options?.receive
+        };
+        const defaultAccessLevel = options?.defaultAccessLevel ?? {
+            read: 'only_owner',
+            write: 'only_owner'
+        };
+        // Single canonical access point for the device's MLS GroupHandle instances.
+        // 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({
+            stores: params.db,
+            deviceID: identity.id,
+            logger: params.getLogger('group-handle-registry')
+        });
+        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,
+            runtime: params.runtime,
+            registry,
+            hlc,
+            stores: params.db,
+            emitter,
+            logger: params.getLogger('group-manager')
+        });
+        const groupHealthMonitor = new GroupHealthMonitor({
+            emitter,
+            logger: params.getLogger('group-health-monitor')
+        });
+        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);
+                // 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,
+            identity: params.identity,
+            logger: params.getLogger('sync'),
+            storeUnreadable: receiveConfig.storeUnreadable,
+            defaultAccessLevel
+        });
+        const syncHandlers = createSyncHandlers({
+            db: params.db,
+            graph: params.graph,
+            logger: params.getLogger('sync-handlers'),
+            peerRegistry: syncManager.peerRegistry,
+            selfDID: identity.id,
+            storeUnreadable: receiveConfig.storeUnreadable,
+            defaultAccessLevel
+        });
+        // 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 = [];
+        function createSyncTransport(signal) {
+            const directTransports = new DirectTransports({
+                signal
+            });
+            const server = new Server({
+                runtime: params.runtime,
+                handlers: syncHandlers,
+                identity,
+                // Open at the procedure layer by design: the sync protocol's
+                // authorization is enforced downstream, per document (read-ACL and
+                // write-delegation tokens), not by a coarse caller allow-list here.
+                accessRules: {
+                    'sync/*': {
+                        allow: true
+                    }
+                },
+                logger: params.getLogger('sync-server'),
+                transports: [
+                    directTransports.server
+                ],
+                signal
+            });
+            syncServers.push(server);
+            return directTransports.client;
+        }
+        const hubRelayLogger = params.getLogger('hub-relay');
+        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) {
+            // 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,
+                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`. 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,
+                    ...options.batch
+                };
+                broadcastQueue = createBroadcastQueue({
+                    config: batchConfig,
+                    scheduleBroadcast: hub.scheduleBroadcast,
+                    logger: params.getLogger('broadcast-queue')
+                });
+                unwireBroadcastSender = wireBroadcastSender({
+                    db: params.db,
+                    eventBus: params.eventBus,
+                    selfDID: identity.id,
+                    queue: broadcastQueue,
+                    logger: params.getLogger('broadcast-sender')
+                });
+            }
+        }
+        // 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({
+                    config,
+                    stores: params.db
+                }),
+            removePeer: (peerDID)=>syncManager.removePeer({
+                    peerDID,
+                    stores: params.db
+                }),
+            listPeers: ()=>syncManager.listPeers({
+                    stores: params.db
+                }),
+            syncWithPeer: (syncParams)=>syncManager.merkleSyncWithPeer({
+                    ...syncParams,
+                    stores: params.db
+                }),
+            getStatus: (peerDID)=>syncManager.getStatus({
+                    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),
+            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)
+        };
+        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).
+            const httpOption = options.http;
+            const rawPath = typeof httpOption === 'string' ? httpOption : typeof httpOption === 'object' ? httpOption.path ?? 'sync' : 'sync';
+            const protocolName = rawPath.replace(/^\//, '');
+            // Default-deny cross-origin browser requests, consistent with the other
+            // HTTP surfaces. The sync server authenticates every request (signed
+            // Enkaku procedures), so CORS is defense-in-depth here, not the security
+            // boundary; non-browser sync clients send no Origin and are unaffected.
+            // Operators opt into cross-origin via the object form's `allowedOrigin`.
+            const allowedOrigin = resolveAllowedOrigin(typeof httpOption === 'object' ? httpOption.allowedOrigin : undefined);
+            // Maximum request body size, enforced by the transport (default 1 MiB,
+            // matching the Enkaku ServerTransport default).
+            const maxRequestBodySize = (typeof httpOption === 'object' ? httpOption.bodyLimit : undefined) ?? 1024 * 1024;
+            pluginAPI.syncReady = (async ()=>{
+                const httpAPI = await params.engine.getAPI('http');
+                await httpAPI.listening;
+                httpSyncTransport = new ServerTransport({
+                    allowedOrigin,
+                    maxRequestBodySize
+                });
+                httpSyncServer = new Server({
+                    runtime: params.runtime,
+                    handlers: syncHandlers,
+                    identity,
+                    // Open at the procedure layer by design: the sync protocol's
+                    // authorization is enforced downstream, per document (read-ACL and
+                    // write-delegation tokens), not by a coarse caller allow-list here.
+                    accessRules: {
+                        'sync/*': {
+                            allow: true
+                        }
+                    },
+                    logger: params.getLogger('sync-http-server'),
+                    transports: [
+                        httpSyncTransport
+                    ]
+                });
+                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, syncManager, params.getLogger('p2p-schema')),
+            api: pluginAPI,
+            createContextFactory: ()=>{
+                return (ctx, stores)=>{
+                    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),
+                        peer: createPeerContext(ctx, deps)
+                    };
+                };
+            },
+            dispose: async ()=>{
+                // Unwire the broadcast-sender subscriber first so no new broadcasts
+                // are enqueued while teardown is in flight.
+                if (unwireBroadcastSender != null) {
+                    try {
+                        unwireBroadcastSender();
+                    } catch  {
+                    // 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) {
+                    try {
+                        broadcastQueue.dispose();
+                    } catch  {
+                    // ignore
+                    }
+                }
+                // 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'
+                ];
+                results.forEach((result, i)=>{
+                    if (result.status === 'rejected') {
+                        disposeLogger.error('dispose branch failed', {
+                            branch: labels[i],
+                            error: result.reason
+                        });
+                    }
+                });
+            }
+        };
+    };
+}

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>;
+}