@kubun/plugin-p2p 0.10.1 → 0.11.0

package/lib/sync/forwarder.js

@@ -1 +1,277 @@
-import{catalogMatchesDoc as r,resolveAccessRule as e}from"@kubun/engine";import{computeBroadcastScopes as o}from"./scope-resolver.js";export function rethrowIfProgrammerError(r){if(r instanceof SyntaxError||r instanceof TypeError||r instanceof ReferenceError||r instanceof RangeError)throw r}export async function evaluateAndForward(t){let a,l;if(!1===t.forwarding)return{forwarded:0,skipped:0};let i=!0===t.forwarding?()=>!0:t.forwarding,n=(await t.p2pStore.getGroupsForMember(t.selfDID)).map(r=>r.id).filter(r=>r!==t.sourceGroupID);if(0===n.length)return{forwarded:0,skipped:0};try{a=await e(t.postState,t.postState.model,t.postState.owner,"read",{getUserModelAccessDefault:(r,e,o)=>t.graphStore.getUserModelAccessDefault(r,e,o),isMemberOfAnyCircle:(r,e)=>t.p2pStore.isMemberOfAnyCircle(r,e),isMemberOfAnyGroup:(r,e)=>t.p2pStore.isMemberOfAnyGroup(r,e),getModelInterfaces:r=>t.graphStore.getModelInterfaces(r)},t.defaultAccessLevel)}catch(r){return rethrowIfProgrammerError(r),t.logger?.warn("forwarder: resolveAccessRule failed, skipping forward",{docID:t.entry.docID,version:t.entry.version,sourceGroupID:t.sourceGroupID,error:String(r)}),{forwarded:0,skipped:0}}let s=new Set(a.allowedGroups??[]),f=new Set;if(null!=a.allowedCircles&&a.allowedCircles.length>0)try{for(let r of(await t.p2pStore.getCircles(a.allowedCircles)).values())null!=r.group_id&&f.add(r.group_id)}catch(r){rethrowIfProgrammerError(r),t.logger?.warn("forwarder: getCircles failed, skipping allowedCircles",{count:a.allowedCircles.length,error:String(r)})}let d=new Set;if(null!=a.allowedDIDs&&a.allowedDIDs.length>0)try{for(let r of(await t.p2pStore.getGroupsForMembers(a.allowedDIDs)).values())for(let e of r)d.add(e.id)}catch(r){rethrowIfProgrammerError(r),t.logger?.warn("forwarder: getGroupsForMembers failed, skipping allowedDIDs",{count:a.allowedDIDs.length,error:String(r)})}let p=o({resolvedRule:{level:a.level,allowedGroupIDs:s,allowedCircleParentGroupIDs:f,allowedDIDGroupIDs:d},senderGroupIDs:n});if(0===p.length)return{forwarded:0,skipped:0};try{l=await t.p2pStore.getCirclesForMember(t.selfDID)}catch(r){return rethrowIfProgrammerError(r),t.logger?.warn("forwarder: getCirclesForMember failed",{selfDID:t.selfDID,error:String(r)}),{forwarded:0,skipped:0}}let c=new Set(p),g=new Map;for(let r of l){if(!c.has(r.group_id))continue;let e=g.get(r.group_id);null!=e?e.push(r):g.set(r.group_id,[r])}let u=new Set;for(let r of g.values())for(let e of r)for(let r of e.catalog_ids??[])u.add(r);let w=new Map;if(u.size>0)try{w=await t.graphStore.getCatalogs(Array.from(u))}catch(r){rethrowIfProgrammerError(r),t.logger?.warn("forwarder: getCatalogs failed, treating all as missing",{count:u.size,error:String(r)})}let D=0,I=0;for(let e of p)try{let o=g.get(e)??[],a=!1;for(let e of o){for(let o of e.catalog_ids??[]){let e=w.get(o);if(null!=e&&await r(e.filter_criteria,t.postState,t.p2pStore)){a=!0;break}}if(a)break}if(!a){I++;continue}let l={docID:t.entry.docID,modelID:t.entry.modelID,ownerDID:t.postState.owner,sourceGroupID:t.sourceGroupID,candidateGroupID:e,postState:t.postState};if(!await i(l)){I++;continue}if(!await t.p2pStore.recordBroadcast({docID:t.entry.docID,version:t.entry.version,mlsGroupID:e}))continue;let n={type:"mutation:apply",entries:[t.entry],senderPeerDID:t.selfDID};await t.scheduleBroadcast(e,n),D++}catch(r){t.logger?.warn("forwarder: candidate evaluation failed",{docID:t.entry.docID,version:t.entry.version,candidateGroupID:e,sourceGroupID:t.sourceGroupID,error:String(r)})}return{forwarded:D,skipped:I}}
+import { catalogMatchesDoc, resolveAccessRule } from '@kubun/engine';
+import { computeBroadcastScopes } from './scope-resolver.js';
+// The store-read catch blocks below degrade gracefully on a transient failure
+// (treat the result as missing and skip the forward). A SyntaxError / TypeError
+// / ReferenceError / RangeError is a bug or corrupt data, not a transient
+// condition — rethrow it so it surfaces instead of being silently swallowed.
+export function rethrowIfProgrammerError(error) {
+    if (error instanceof SyntaxError || error instanceof TypeError || error instanceof ReferenceError || error instanceof RangeError) {
+        throw error;
+    }
+}
+/**
+ * Evaluate forwarding candidates for a single mutation:apply entry the local
+ * peer has just applied, and forward to each surviving candidate group via
+ * `scheduleBroadcast`.
+ *
+ * Pipeline (per candidate group):
+ * 1. Source group exclusion — `sourceGroupID` is filtered out before any check.
+ * 2. Access gate — `computeBroadcastScopes` against the post-apply rule.
+ * 3. Catalog gate — at least one circle the local peer belongs to in the
+ *    candidate group must have a catalog whose `filter_criteria` matches the
+ *    document.
+ * 4. Filter (when `forwarding` is a function) — narrows further.
+ * 5. Dedup — `recordBroadcast` BEFORE schedule. False return → skip silently.
+ * 6. Schedule — single-entry `mutation:apply` broadcast with
+ *    `senderPeerDID = selfDID`.
+ *
+ * Per-candidate errors are isolated: one bad candidate logs + continues; the
+ * rest still get evaluated. The function never throws.
+ *
+ * Routing decision: each candidate gets its OWN single-entry broadcast (no
+ * batch queue). The queue's `senderPeerDID`-mismatch flush conflicts
+ * with mixing locally-authored and forwarded entries in one batch — deferring
+ * batched-forwarding keeps the receive path simple.
+ */ export async function evaluateAndForward(params) {
+    // 1. Zero-overhead short-circuit when forwarding is disabled.
+    if (params.forwarding === false) {
+        return {
+            forwarded: 0,
+            skipped: 0
+        };
+    }
+    const filter = params.forwarding === true ? ()=>true : params.forwarding;
+    // 2. Enumerate self group memberships and exclude the source group.
+    const myGroups = await params.p2pStore.getGroupsForMember(params.selfDID);
+    const candidateGroupIDs = myGroups.map((g)=>g.id).filter((id)=>id !== params.sourceGroupID);
+    if (candidateGroupIDs.length === 0) {
+        return {
+            forwarded: 0,
+            skipped: 0
+        };
+    }
+    // 3. Resolve the effective read rule against the post-apply state. Same
+    // db-shape wrappers as `processBroadcast` uses for `createReceiveAccessGate`.
+    let rule;
+    try {
+        rule = await resolveAccessRule(params.postState, params.postState.model, params.postState.owner, 'read', {
+            getUserModelAccessDefault: (ownerDID, modelID, permissionType)=>params.graphStore.getUserModelAccessDefault(ownerDID, modelID, permissionType),
+            isMemberOfAnyCircle: (viewerDID, circleIDs)=>params.p2pStore.isMemberOfAnyCircle(viewerDID, circleIDs),
+            isMemberOfAnyGroup: (viewerDID, groupIDs)=>params.p2pStore.isMemberOfAnyGroup(viewerDID, groupIDs),
+            getModelInterfaces: (modelID)=>params.graphStore.getModelInterfaces(modelID)
+        }, params.defaultAccessLevel);
+    } catch (error) {
+        rethrowIfProgrammerError(error);
+        params.logger?.warn('forwarder: resolveAccessRule failed, skipping forward', {
+            docID: params.entry.docID,
+            version: params.entry.version,
+            sourceGroupID: params.sourceGroupID,
+            error: String(error)
+        });
+        return {
+            forwarded: 0,
+            skipped: 0
+        };
+    }
+    // 4. Build the resolved-rule shape consumed by computeBroadcastScopes. This
+    // mirrors the sender's pre-resolution in broadcast-sender.ts.
+    const allowedGroupIDs = new Set(rule.allowedGroups ?? []);
+    // Single batched query for allowedCircles → parent group IDs. Replaces a
+    // per-circle `getCircle` loop. A query-level failure aborts only this
+    // sub-step (with a log) and yields an empty set, mirroring the prior
+    // per-circle skip-on-error behavior in aggregate.
+    const allowedCircleParentGroupIDs = new Set();
+    if (rule.allowedCircles != null && rule.allowedCircles.length > 0) {
+        try {
+            const circlesByID = await params.p2pStore.getCircles(rule.allowedCircles);
+            for (const circle of circlesByID.values()){
+                if (circle.group_id != null) {
+                    allowedCircleParentGroupIDs.add(circle.group_id);
+                }
+            }
+        } catch (error) {
+            rethrowIfProgrammerError(error);
+            params.logger?.warn('forwarder: getCircles failed, skipping allowedCircles', {
+                count: rule.allowedCircles.length,
+                error: String(error)
+            });
+        }
+    }
+    // Single batched query for allowedDIDs → groups. Replaces a per-DID
+    // `getGroupsForMember` loop.
+    const allowedDIDGroupIDs = new Set();
+    if (rule.allowedDIDs != null && rule.allowedDIDs.length > 0) {
+        try {
+            const groupsByDID = await params.p2pStore.getGroupsForMembers(rule.allowedDIDs);
+            for (const groups of groupsByDID.values()){
+                for (const g of groups){
+                    allowedDIDGroupIDs.add(g.id);
+                }
+            }
+        } catch (error) {
+            rethrowIfProgrammerError(error);
+            params.logger?.warn('forwarder: getGroupsForMembers failed, skipping allowedDIDs', {
+                count: rule.allowedDIDs.length,
+                error: String(error)
+            });
+        }
+    }
+    const resolvedRule = {
+        level: rule.level,
+        allowedGroupIDs,
+        allowedCircleParentGroupIDs,
+        allowedDIDGroupIDs
+    };
+    // 5. Apply access gate via computeBroadcastScopes.
+    const accessPermitted = computeBroadcastScopes({
+        resolvedRule,
+        senderGroupIDs: candidateGroupIDs
+    });
+    if (accessPermitted.length === 0) {
+        return {
+            forwarded: 0,
+            skipped: 0
+        };
+    }
+    // 6. Resolve self circles once and bucket by group_id for catalog-match
+    // lookups. A candidate group is catalog-eligible iff at least one of the
+    // local peer's circles WITHIN that group has a catalog matching the doc.
+    let myCircles;
+    try {
+        myCircles = await params.p2pStore.getCirclesForMember(params.selfDID);
+    } catch (error) {
+        rethrowIfProgrammerError(error);
+        params.logger?.warn('forwarder: getCirclesForMember failed', {
+            selfDID: params.selfDID,
+            error: String(error)
+        });
+        return {
+            forwarded: 0,
+            skipped: 0
+        };
+    }
+    const accessSet = new Set(accessPermitted);
+    const circlesByGroup = new Map();
+    for (const circle of myCircles){
+        if (!accessSet.has(circle.group_id)) continue;
+        const list = circlesByGroup.get(circle.group_id);
+        if (list != null) {
+            list.push(circle);
+        } else {
+            circlesByGroup.set(circle.group_id, [
+                circle
+            ]);
+        }
+    }
+    // 6b. Pre-fetch every catalog referenced by the relevant circles in a
+    // single batched DB query. This collapses O(candidates × circles ×
+    // catalogs) sequential awaits in the candidate loop down to ONE DB call
+    // per evaluation. Catalogs can be shared across circles, so the Set
+    // already dedups IDs before the call.
+    const catalogIDSet = new Set();
+    for (const circles of circlesByGroup.values()){
+        for (const circle of circles){
+            for (const catalogID of circle.catalog_ids ?? []){
+                catalogIDSet.add(catalogID);
+            }
+        }
+    }
+    let catalogByID = new Map();
+    if (catalogIDSet.size > 0) {
+        try {
+            catalogByID = await params.graphStore.getCatalogs(Array.from(catalogIDSet));
+        } catch (error) {
+            rethrowIfProgrammerError(error);
+            // Single-query failure: treat all catalogs as missing (preserves the
+            // prior per-getCatalog-failure semantics in aggregate). Candidate
+            // groups whose catalogs are now unresolved will fall through the
+            // catalog gate as no-match.
+            params.logger?.warn('forwarder: getCatalogs failed, treating all as missing', {
+                count: catalogIDSet.size,
+                error: String(error)
+            });
+        }
+    }
+    let forwarded = 0;
+    let skipped = 0;
+    // 7. Evaluate each candidate group SEQUENTIALLY. This loop is deliberately
+    // not parallelized:
+    //   - `filter(ctx)` is a user-supplied callback whose side effects (e.g.
+    //     logging, metrics) may rely on candidate order.
+    //   - `recordBroadcast` ordering matters for the at-most-once invariant —
+    //     a failure mid-loop must not leave broadcasts recorded for groups
+    //     that were never scheduled.
+    //   - `scheduleBroadcast` ordering keeps test assertions stable and
+    //     surfaces failures deterministically.
+    // Pure DB reads upstream (catalog batch fetch, getCircles,
+    // getGroupsForMembers) are batched/parallel — only this side-effecting
+    // dispatch stays sequential.
+    for (const candidateGroupID of accessPermitted){
+        try {
+            // Catalog gate.
+            const circlesInGroup = circlesByGroup.get(candidateGroupID) ?? [];
+            let catalogEligible = false;
+            for (const circle of circlesInGroup){
+                const catalogIDs = circle.catalog_ids ?? [];
+                for (const catalogID of catalogIDs){
+                    const catalog = catalogByID.get(catalogID);
+                    if (catalog == null) continue;
+                    if (await catalogMatchesDoc(catalog.filter_criteria, params.postState, params.p2pStore)) {
+                        catalogEligible = true;
+                        break;
+                    }
+                }
+                if (catalogEligible) break;
+            }
+            if (!catalogEligible) {
+                skipped++;
+                continue;
+            }
+            // Filter gate.
+            const ctx = {
+                docID: params.entry.docID,
+                modelID: params.entry.modelID,
+                ownerDID: params.postState.owner,
+                sourceGroupID: params.sourceGroupID,
+                candidateGroupID,
+                postState: params.postState
+            };
+            const allow = await filter(ctx);
+            if (!allow) {
+                skipped++;
+                continue;
+            }
+            // Dedup BEFORE schedule — record-before-send pattern (sender mirror).
+            const recorded = await params.p2pStore.recordBroadcast({
+                docID: params.entry.docID,
+                version: params.entry.version,
+                mlsGroupID: candidateGroupID
+            });
+            if (!recorded) {
+                continue;
+            }
+            const message = {
+                type: 'mutation:apply',
+                entries: [
+                    params.entry
+                ],
+                senderPeerDID: params.selfDID
+            };
+            await params.scheduleBroadcast(candidateGroupID, message);
+            forwarded++;
+        } catch (error) {
+            // Per-candidate isolation: log and continue with rest.
+            params.logger?.warn('forwarder: candidate evaluation failed', {
+                docID: params.entry.docID,
+                version: params.entry.version,
+                candidateGroupID,
+                sourceGroupID: params.sourceGroupID,
+                error: String(error)
+            });
+        }
+    }
+    return {
+        forwarded,
+        skipped
+    };
+}

package/lib/sync/handlers.js

@@ -1 +1,160 @@
-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 { createRevocationChecker } from '@kokuin/capability';
+import { createRevocationBackend, getDelegationStore } from '@kubun/store-delegation';
+import { getGraphStore } from '@kubun/store-graph';
+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 = createRevocationChecker(createRevocationBackend(delegationStore));
+        }
+        return cachedRevocationChecker;
+    }
+    return {
+        '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, knownModelIDs);
+                // 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,
+                                    delegationTokens,
+                                    revocationChecker: await getRevocationChecker()
+                                });
+                                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,
+                                    delegationTokens,
+                                    revocationChecker: await getRevocationChecker()
+                                });
+                                if (accepted) {
+                                    acceptedScopes.push({
+                                        modelID,
+                                        ownerDID
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                // Fetch missing cluster definitions
+                if (catalogScope.missingClusterIDs.length > 0) {
+                    missingClusters = await graphStore.getClusters(catalogScope.missingClusterIDs);
+                }
+            }
+            // Explicit scopes (existing behavior)
+            if (scopes != null) {
+                for (const scope of scopes){
+                    const accepted = await authorizeScope({
+                        viewerDID,
+                        ownerDID: scope.ownerDID,
+                        delegationTokens,
+                        revocationChecker: await getRevocationChecker()
+                    });
+                    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;
+            });
+            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
+        })
+    };
+}

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

@@ -1,11 +1,15 @@
-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 HubLike, type ObservabilityEventListener } from '@kumiai/hub-tunnel';
 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`). Each spawned
+     * server transport attaches its own sink to this device-wide drain and filters
+     * to its `receiveTopicID`; lifecycle events ride `hub.events`.
+     */
+    hub: HubLike;
     registry: GroupHandleRegistry;
     groupID: string;
     localDID: string;

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

@@ -1 +1,172 @@
-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 { inboxTopic } from '@kumiai/rpc';
+import { createGroupCrypto } from '../groups/group-crypto.js';
+import { MLSEncryptor } from '../groups/mls-encryptor.js';
+export class HubTunnelSyncListener {
+    #hub;
+    #registry;
+    #groupID;
+    #localDID;
+    #peerDID;
+    #identity;
+    #syncHandlers;
+    #getRandomID;
+    #idleTimeoutMs;
+    #reconnectTimeoutMs;
+    #inboxCapacity;
+    #onEvent;
+    #started = false;
+    #stopped = false;
+    #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;
+    // This device's inbox topic for the live epoch, cached from the first spawn.
+    // Within an epoch it is stable (same secret + localDID), so it lets the
+    // disposed handler re-subscribe synchronously and close the gap left by the
+    // departing transport's teardown-unsubscribe before the async respawn lands.
+    #receiveTopicID;
+    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.#getRandomID = params.getRandomID;
+        this.#idleTimeoutMs = params.idleTimeoutMs;
+        this.#reconnectTimeoutMs = params.reconnectTimeoutMs;
+        this.#inboxCapacity = params.inboxCapacity;
+        this.#onEvent = params.onEvent;
+    }
+    start() {
+        if (this.#started || this.#stopped) return;
+        this.#started = true;
+        this.#encryptor = new MLSEncryptor({
+            registry: this.#registry,
+            groupID: this.#groupID
+        });
+        void this.#spawn();
+    }
+    async stop() {
+        if (this.#stopped) return;
+        this.#stopped = true;
+        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;
+    }
+    async #spawn() {
+        if (this.#stopped) return;
+        const encryptor = this.#encryptor;
+        if (encryptor == null) {
+            throw new Error('HubTunnelSyncListener: encryptor not initialized; call start() first');
+        }
+        // Derive the epoch-bound inbox topics for this spawn. The server accepts
+        // inbound frames on its own inbox (`receiveTopicID`) and replies to the
+        // peer's inbox (`sendTopicID`). 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.
+        const crypto = createGroupCrypto(this.#registry, this.#groupID);
+        const secret = await crypto.exportSecret();
+        const epoch = crypto.epoch();
+        const sendTopicID = inboxTopic(secret, epoch, this.#peerDID);
+        const receiveTopicID = inboxTopic(secret, epoch, this.#localDID);
+        this.#receiveTopicID = receiveTopicID;
+        // A stop() that landed while we awaited the handle must abort the spawn.
+        if (this.#stopped) return;
+        let transportRef;
+        const transport = createEncryptedHubTunnelTransport({
+            hub: this.#hub,
+            encryptor,
+            groupID: this.#groupID,
+            sessionID: {
+                auto: true
+            },
+            localDID: this.#localDID,
+            sendTopicID,
+            receiveTopicID,
+            idleTimeoutMs: this.#idleTimeoutMs,
+            reconnectTimeoutMs: this.#reconnectTimeoutMs,
+            inboxCapacity: this.#inboxCapacity,
+            onEvent: 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({
+            getRandomID: this.#getRandomID,
+            handlers: this.#syncHandlers,
+            identity: this.#identity,
+            accessRules: {
+                'sync/*': {
+                    allow: true
+                }
+            },
+            transports: [
+                transport
+            ]
+        });
+        const session = {
+            transport,
+            server
+        };
+        this.#current = session;
+        // `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 the inbox is re-armed once, not N times.
+        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
+            });
+            // The departing transport's teardown unsubscribes this device's inbox
+            // topic. Re-subscribe it eagerly (idempotent server-side) so a peer that
+            // reconnects immediately — before the async respawn re-derives and
+            // re-subscribes — does not lose its first frame to a momentarily empty
+            // topic. Within an epoch the topic is stable, so this targets the same
+            // inbox the next spawn will use.
+            const receiveTopicID = this.#receiveTopicID;
+            if (receiveTopicID != null) {
+                void Promise.resolve(this.#hub.subscribe(this.#localDID, receiveTopicID)).catch(()=>{
+                // best-effort; the respawn re-subscribes authoritatively
+                });
+            }
+            // Respawn for the next session. The next spawn re-derives the topics
+            // against the (possibly advanced) epoch and re-subscribes.
+            void this.#spawn();
+        });
+    }
+}