@kubun/plugin-p2p 0.10.0 → 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.d.ts

@@ -1,22 +1,10 @@
-import { type VerifyTokenHook } from '@enkaku/capability';
 import type { KubunDB } from '@kubun/db';
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { Logger } from '@kubun/logger';
-import type { SyncDirection } from '../protocol.js';
 import type { StoreUnreadableMode } from '../types.js';
-import type { PeerRegistry } from './peer-registry.js';
-/**
- * Check if delegation tokens grant the viewer read access to a user's documents.
- *
- * @param viewerDID - The DID of the requesting viewer
- * @param ownerDID - The DID of the document owner
- * @param delegationTokens - Array of delegation JWT tokens
- * @param revocationChecker - Optional per-leaf-capability verification hook.
- *   When set, capabilities whose `jti` has been revoked cause the check to
- *   fail closed.
- * @returns true if any token grants read access
- */
-export declare function checkSyncDelegation(viewerDID: string, ownerDID: string, delegationTokens: Array<string>, revocationChecker?: VerifyTokenHook): Promise<boolean>;
+import { checkSyncDelegation } from './authorize.js';
+import { type PeerRegistry } from './peer-registry.js';
+export { checkSyncDelegation };
 export type CreateSyncHandlersParams = {
     db: KubunDB;
     graph: GraphInternals;
@@ -35,13 +23,6 @@ export type CreateSyncHandlersParams = {
     /** Server default access level — required when `storeUnreadable === 'drop'`. */
     defaultAccessLevel?: DefaultAccessLevel;
 };
-/**
- * Resolve the effective sync direction given what the initiator requested
- * and what the responder's per-peer policy allows.
- * If allowed is 'both' (or unset), the request passes through.
- * Otherwise the responder's policy wins.
- */
-export declare function negotiateDirection(requested: SyncDirection, allowed: SyncDirection): SyncDirection;
 /**
  * Create sync protocol handlers served by plugin-p2p's own Enkaku server.
  */

package/lib/sync/handlers.js

@@ -1 +1,160 @@
-import{checkCapability as e,createRevocationChecker as t}from"@enkaku/capability";import{getGraphStore as n}from"@kubun/store-graph";import{createP2PRevocationBackend as r,getP2PStore as o}from"@kubun/store-p2p";import{resolveCatalogSyncScopes as l}from"./catalog-scope.js";import{createMerkleSyncChannelHandler as a}from"./merkle-channel.js";export async function checkSyncDelegation(t,n,r,o){if(!r||0===r.length)return!1;let l=["*","urn:kubun:user:*",`urn:kubun:user:${n}`],a="document/read";for(let s of l)try{return await e({act:a,res:s},{iss:t,sub:n,cap:r},{verifyToken:o}),!0}catch{}for(let s of r)for(let r of l)try{return await e({act:a,res:r},{iss:t,sub:n,cap:s},{verifyToken:o}),!0}catch{}return!1}export function negotiateDirection(e,t){return"both"===t?e:"both"===e?t:e===t?e:t}export function createSyncHandlers(e){let{db:s,graph:i,logger:c,peerRegistry:u}=e,f=e.storeUnreadable??"persist",d=null;async function g(){return null==d&&(d=t(r(await o(s)))),d}return{"sync/negotiate":async e=>{let t,{scopes:r,delegationTokens:o,catalogIDs:a,knownModelIDs:i,direction:f}=e.param,d=e.message.payload,p=d.sub||d.iss;c.debug("sync/negotiate requested",{scopes:r,catalogIDs:a,viewerDID:p});let D=[],m=await n(s);if(null!=a&&a.length>0){let e=await l(s,a,i);if(e.modelIDs.length>0)if(null!=e.owners)for(let t of e.modelIDs)for(let n of e.owners){let e=p===n,r=!e&&await checkSyncDelegation(p,n,o,await g());(e||r)&&D.push({modelID:t,ownerDID:n})}else for(let t of e.modelIDs)for(let e of(await m.getDistinctOwnersForModel(t))){let n=p===e,r=!n&&await checkSyncDelegation(p,e,o,await g());(n||r)&&D.push({modelID:t,ownerDID:e})}e.missingClusterIDs.length>0&&(t=await m.getClusters(e.missingClusterIDs))}if(null!=r)for(let e of r){let t=p===e.ownerDID,n=!t&&await checkSyncDelegation(p,e.ownerDID,o,await g());t||n?D.push(e):c.debug("sync/negotiate: scope rejected",{scope:e,viewerDID:p})}let w=new Set,h=D.filter(e=>{let t=`${e.modelID}:${e.ownerDID}`;return!w.has(t)&&(w.add(t),!0)});c.info("sync/negotiate completed",{requested:(r?.length??0)+(a?.length??0),accepted:h.length,missingClusters:null!=t?Object.keys(t).length:0});let y=f??"pull",b=await u.getPeer({peerDID:p,stores:s}),k=b?.allowedDirection??"both",I=negotiateDirection(y,k);return I!==y&&c.info("sync/negotiate: direction downgraded",{requested:y,allowed:k,agreed:I}),{direction:I,acceptedScopes:h,excludedDocumentIDs:[],...null!=t&&{missingClusters:t}}},"sync/merkle-sync":a({db:s,graph:i,logger:c,selfDID:e.selfDID,storeUnreadable:f,defaultAccessLevel:e.defaultAccessLevel})}}
+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,14 +1,20 @@
-import { type ObservabilityEventListener } from '@enkaku/hub-tunnel';
 import { type ProcedureHandlers } from '@enkaku/server';
+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;
     peerDID: string;
+    identity: OwnIdentity;
     syncHandlers: ProcedureHandlers<SyncProtocol>;
     getRandomID?: () => string;
     idleTimeoutMs?: number;