@kubun/plugin-p2p 0.8.2 → 0.9.0

package/lib/sync/merkle-apply.d.ts

@@ -1,12 +1,53 @@
 import type { KubunDB } from '@kubun/db';
+import { type DefaultAccessLevel, type GraphInternals } from '@kubun/engine';
+import type { StoreUnreadableMode } from '../types.js';
 export type ApplySyncMutationsParams = {
     db: KubunDB;
+    graph: GraphInternals;
     mutationJWTs: Array<string>;
+    /**
+     * Local peer's DID — required when `storeUnreadable === 'drop'` to feed the
+     * receive-time access gate. Optional otherwise.
+     */
+    selfDID?: string;
+    /**
+     * Receiver storage mode for incoming sync mutations.
+     * - `'persist'` (default) — every mutation the engine accepts persists.
+     * - `'drop'` — apply a receive-time read-access check using `selfDID` as
+     *   viewer; mutations the local peer cannot read are not persisted.
+     */
+    storeUnreadable?: StoreUnreadableMode;
+    /** Server default access level — required when `storeUnreadable === 'drop'`. */
+    defaultAccessLevel?: DefaultAccessLevel;
 };
 export type ApplySyncMutationsResult = {
     applied: number;
     rejected: number;
     pending: number;
     skipped: number;
+    /** Count of mutations denied by the receive-time access gate. */
+    dropped: number;
 };
+/**
+ * Apply mutation JWTs received from a peer via Merkle sync.
+ *
+ * Routes the successful-apply path through {@link GraphInternals.applyVerifiedMutation}
+ * with `origin: 'peer'` so GraphQL subscriptions (and other engine event
+ * consumers) fire for peer-received documents. The engine handles JWT
+ * verification, validator cache, applying the mutation, and inserting the
+ * `status: 'applied'` mutation log entry.
+ *
+ * Paths that bypass the engine (manual mutation-log insert):
+ * - **skipped**: mutation hash already seen — no-op.
+ * - **pending**: change mutation for a document that doesn't exist yet;
+ *   parked in the log with `status: 'pending'` to be resolved when the
+ *   set arrives.
+ * - **rejected**: JWT verify/validate fails, or engine throws during apply;
+ *   recorded with `status: 'rejected'`.
+ *
+ * We still verify + validate the JWT up front to peek at `mutation.typ` for
+ * the pending-path routing decision. The engine re-verifies on the success
+ * path (defense in depth + avoids plumbing verified payloads through the
+ * public API).
+ */
 export declare function applySyncMutations(params: ApplySyncMutationsParams): Promise<ApplySyncMutationsResult>;

package/lib/sync/merkle-apply.js

@@ -1 +1 @@
-import{asType as t,createValidator as a}from"@enkaku/schema";import{verifyToken as i}from"@enkaku/token";import{computeMutationHash as o}from"@kubun/engine";import{DocumentID as n}from"@kubun/id";import{applyMutation as u}from"@kubun/mutation";import{documentMutation as e}from"@kubun/protocol";import{getGraphStore as r}from"@kubun/store-graph";let m=a(e);export async function applySyncMutations(a){let{db:e,mutationJWTs:s}=a,d=await r(e),l=0,c=0,h=0,p=0,_={store:d,validators:{}};for(let a of s){let e,r=o(a);if(await d.hasMutationHash(r)){p++;continue}try{let o=await i(a);e=t(m,o.payload)}catch{c++;continue}let s=e.sub,f=n.fromString(s).model.toString(),w=n.fromString(s);if(null==await d.getDocument(w)&&"change"===e.typ){await d.insertMutationLogEntry({mutation_hash:r,model_id:f,document_id:s,author_did:e.iss,hlc:e.hlc,mutation_jwt:a,status:"pending"}),h++;continue}try{if(await u(_,e),await d.insertMutationLogEntry({mutation_hash:r,model_id:f,document_id:s,author_did:e.iss,hlc:e.hlc,mutation_jwt:a,status:"applied"}),l++,"set"===e.typ)for(let a of(await d.getPendingMutations(s)))try{let o=await i(a.mutation_jwt),n=t(m,o.payload);await u(_,n),await d.updateMutationStatus(a.mutation_hash,"applied"),l++}catch{await d.updateMutationStatus(a.mutation_hash,"rejected"),c++}}catch{await d.insertMutationLogEntry({mutation_hash:r,model_id:f,document_id:s,author_did:e.iss,hlc:e.hlc,mutation_jwt:a,status:"rejected"}),c++}}return{applied:l,rejected:c,pending:h,skipped:p}}
+import{asType as t,createValidator as e}from"@enkaku/schema";import{verifyToken as a}from"@enkaku/token";import{computeMutationHash as i}from"@kubun/engine";import{DocumentID as o}from"@kubun/id";import{documentMutation as n}from"@kubun/protocol";import{getGraphStore as r}from"@kubun/store-graph";import{getP2PStore as u}from"@kubun/store-p2p";import{createReceiveAccessGate as s}from"./receive-access-gate.js";let l=e(n);export async function applySyncMutations(e){let n,{db:c,graph:p,mutationJWTs:d}=e,m=await r(c);if("drop"===(e.storeUnreadable??"persist")){if(null==e.selfDID)throw Error("applySyncMutations: 'storeUnreadable: drop' requires selfDID");let t=await u(c);n=s({selfDID:e.selfDID,db:{getUserModelAccessDefault:(t,e,a)=>m.getUserModelAccessDefault(t,e,a),isMemberOfAnyCircle:(e,a)=>t.isMemberOfAnyCircle(e,a),isMemberOfAnyGroup:(e,a)=>t.isMemberOfAnyGroup(e,a)},defaultAccessLevel:e.defaultAccessLevel??{read:"only_owner",write:"only_owner"}})}let f=0,h=0,y=0,w=0,g=0;for(let e of d){let r,u=i(e);if(await m.hasMutationHash(u)){w++;continue}try{let i=await a(e);r=t(l,i.payload)}catch{h++;continue}let s=r.sub,c=o.fromString(s).model.toString(),d=o.fromString(s);if(null==await m.getDocument(d)&&"change"===r.typ){await m.insertMutationLogEntry({mutation_hash:u,model_id:c,document_id:s,author_did:r.iss,hlc:r.hlc,mutation_jwt:e,status:"pending"}),y++;continue}try{if((await p.applyVerifiedMutation({token:e,origin:"peer",...null!=n?{accessGate:n}:{}})).dropped){g++;continue}if(f++,"set"===r.typ)for(let t of(await m.getPendingMutations(s)))try{if((await p.applyVerifiedMutation({token:t.mutation_jwt,origin:"peer",...null!=n?{accessGate:n}:{}})).dropped){await m.updateMutationStatus(t.mutation_hash,"rejected"),g++;continue}await m.updateMutationStatus(t.mutation_hash,"applied"),f++}catch{await m.updateMutationStatus(t.mutation_hash,"rejected"),h++}}catch{await m.insertMutationLogEntry({mutation_hash:u,model_id:c,document_id:s,author_did:r.iss,hlc:r.hlc,mutation_jwt:e,status:"rejected"}),h++}}return{applied:f,rejected:h,pending:y,skipped:w,dropped:g}}

package/lib/sync/merkle-channel.d.ts

@@ -1,6 +1,8 @@
 import type { KubunDB } from '@kubun/db';
+import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { Logger } from '@kubun/logger';
 import type { SyncMerkleSyncParams, SyncMerkleSyncReceive, SyncMerkleSyncResult, SyncMerkleSyncSend } from '../protocol.js';
+import type { StoreUnreadableMode } from '../types.js';
 /**
  * Minimal handler context shape for sync/merkle-sync channel.
  * Matches the Enkaku ChannelHandlerContext at runtime.
@@ -12,7 +14,20 @@ type MerkleSyncChannelContext = {
 };
 export type CreateMerkleSyncChannelHandlerParams = {
     db: KubunDB;
+    graph: GraphInternals;
     logger: Logger;
+    /**
+     * Local peer's DID — required when `storeUnreadable === 'drop'` so the
+     * receive-time access gate can use it as viewer.
+     */
+    selfDID?: string;
+    /**
+     * Receive-side storage mode forwarded to `applySyncMutations`.
+     * Defaults to `'persist'` when omitted.
+     */
+    storeUnreadable?: StoreUnreadableMode;
+    /** Server default access level — required when `storeUnreadable === 'drop'`. */
+    defaultAccessLevel?: DefaultAccessLevel;
 };
 export declare function createMerkleSyncChannelHandler(params: CreateMerkleSyncChannelHandlerParams): (ctx: MerkleSyncChannelContext) => Promise<SyncMerkleSyncResult>;
 export {};

package/lib/sync/merkle-channel.js

@@ -1 +1 @@
-import{getGraphStore as e}from"@kubun/store-graph";import{applySyncMutations as t}from"./merkle-apply.js";import{buildMerkleTree as r,findDivergentBuckets as a,getTimeBuckets as n,SYNC_BATCH_SIZE as l}from"./merkle-tree.js";export function createMerkleSyncChannelHandler(i){let{db:o,logger:s}=i;return async i=>{let{scopes:c,excludedDocumentIDs:m,tree:u,direction:p}=i.param,y=i.writable.getWriter();s.info("sync/merkle-sync channel started",{scopes:c,excludedDocumentIDs:m,direction:p});let w=0,f=0,k=0;try{let h=await e(o),d=await h.getDocumentIDsForScope(c,m),g=await h.getMutationLogForDocuments(d),b=r(g);await y.write({type:"tree",tree:b.buckets});let v={root:u.root??"",buckets:u},W=a(b,v);w=W.length;let J=async()=>{if("pull"===p||"both"===p){let e=new Set(W),t=g.filter(t=>{let{minute:r}=n(t.hlc);return e.has(r)});for(let e=0;e<t.length;e+=l){let r=t.slice(e,e+l);await y.write({type:"mutations",mutationJWTs:r.map(e=>e.mutation_jwt)}),f+=r.length}await y.write({type:"complete"})}else await y.write({type:"complete"})},S=async()=>{let e=[],t=i.readable.getReader();try{for(;;){let{done:r,value:a}=await t.read();if(r)break;if("mutations"===a.type&&null!=a.mutationJWTs)e.push(...a.mutationJWTs);else if("complete"===a.type)break}}finally{t.releaseLock()}return e},[,T]=await Promise.all([J(),S()]);if(T.length>0){let e=await t({db:o,mutationJWTs:T});k=e.applied+e.pending,s.info("sync/merkle-sync: applied received mutations",{result:e})}}catch(e){return s.error("sync/merkle-sync channel error",{error:e}),{success:!1,divergentBuckets:0,mutationsSent:0,mutationsReceived:0}}finally{try{await y.close()}catch{}}return s.info("sync/merkle-sync channel completed",{divergentBuckets:w,mutationsSent:f,mutationsReceived:k}),{success:!0,divergentBuckets:w,mutationsSent:f,mutationsReceived:k}}}
+import{getGraphStore as e}from"@kubun/store-graph";import{applySyncMutations as t}from"./merkle-apply.js";import{buildMerkleTree as r,findDivergentBuckets as a,getTimeBuckets as l,SYNC_BATCH_SIZE as n}from"./merkle-tree.js";export function createMerkleSyncChannelHandler(i){let{db:s,graph:c,logger:o}=i,u=i.storeUnreadable??"persist";return async m=>{let{scopes:p,excludedDocumentIDs:y,tree:f,direction:w}=m.param,d=m.writable.getWriter();o.info("sync/merkle-sync channel started",{scopes:p,excludedDocumentIDs:y,direction:w});let k=0,h=0,g=0;try{let b=await e(s),v=await b.getDocumentIDsForScope(p,y),D=await b.getMutationLogForDocuments(v),W=r(D);await d.write({type:"tree",tree:W.buckets});let J={root:f.root??"",buckets:f},L=a(W,J);k=L.length;let S=async()=>{if("pull"===w||"both"===w){let e=new Set(L),t=D.filter(t=>{let{minute:r}=l(t.hlc);return e.has(r)});for(let e=0;e<t.length;e+=n){let r=t.slice(e,e+n);await d.write({type:"mutations",mutationJWTs:r.map(e=>e.mutation_jwt)}),h+=r.length}await d.write({type:"complete"})}else await d.write({type:"complete"})},T=async()=>{let e=[],t=m.readable.getReader();try{for(;;){let{done:r,value:a}=await t.read();if(r)break;if("mutations"===a.type&&null!=a.mutationJWTs)e.push(...a.mutationJWTs);else if("complete"===a.type)break}}finally{t.releaseLock()}return e},[,j]=await Promise.all([S(),T()]);if(j.length>0){let e=await t({db:s,graph:c,mutationJWTs:j,selfDID:i.selfDID,storeUnreadable:u,defaultAccessLevel:i.defaultAccessLevel});g=e.applied+e.pending,o.info("sync/merkle-sync: applied received mutations",{result:e})}}catch(e){return o.error("sync/merkle-sync channel error",{error:e}),{success:!1,divergentBuckets:0,mutationsSent:0,mutationsReceived:0}}finally{try{await d.close()}catch{}}return o.info("sync/merkle-sync channel completed",{divergentBuckets:k,mutationsSent:h,mutationsReceived:g}),{success:!0,divergentBuckets:k,mutationsSent:h,mutationsReceived:g}}}

package/lib/sync/receive-access-gate.d.ts

@@ -0,0 +1,36 @@
+import { type AccessControlDB, type AccessGate, type DefaultAccessLevel } from '@kubun/engine';
+/**
+ * Inputs for {@link createReceiveAccessGate}. The gate composes
+ * `resolveAccessRule` + `checkAccess` (via `createAccessChecker`) at receive
+ * time using the local peer's DID as viewer. Builds an `AccessControlDB`
+ * adapter from the underlying p2p + graph stores.
+ */
+export type ReceiveAccessGateParams = {
+    /** Local peer's DID — used as the viewer in the access check. */
+    selfDID: string;
+    /**
+     * Access-control DB facade — typically built inline from
+     * `graphStore.getUserModelAccessDefault` + `p2pStore.isMemberOfAnyCircle` +
+     * `p2pStore.isMemberOfAnyGroup`.
+     */
+    db: AccessControlDB;
+    /** Server default access level used when no rule is declared. */
+    defaultAccessLevel: DefaultAccessLevel;
+};
+/**
+ * Build an {@link AccessGate} that returns `true` iff the local peer can
+ * read the post-state document under the resolved access rule.
+ *
+ * Used by the receive paths (`processBroadcast` mutation:apply branch and
+ * `applySyncMutations`) when `storeUnreadable: 'drop'` is configured. The
+ * gate is intentionally cheap to construct — the heavy work (rule
+ * resolution + membership lookups) happens lazily when the gate is invoked
+ * inside the engine's apply pipeline.
+ *
+ * Drop-mode access checks happen at receive time without delegation
+ * token context (the broadcast doesn't carry tokens). A peer who would
+ * gain read access only via a delegation token will have the doc
+ * dropped under `storeUnreadable: 'drop'`. Use `'persist'` if delegation
+ * chains must be honored at receive time.
+ */
+export declare function createReceiveAccessGate(params: ReceiveAccessGateParams): AccessGate;

package/lib/sync/receive-access-gate.js

@@ -0,0 +1 @@
+import{createAccessChecker as e}from"@kubun/engine";export function createReceiveAccessGate(c){let t=e({viewerDID:c.selfDID,db:c.db,defaultAccessLevel:c.defaultAccessLevel});return e=>t(e,"read")}

package/lib/sync/scope-resolver.d.ts

@@ -0,0 +1,32 @@
+export type ResolvedAccessRule = {
+    level: 'only_owner' | 'anyone' | 'restricted';
+    /** rule.allowedGroups (MLS group IDs) */
+    allowedGroupIDs: Set<string>;
+    /** MLS group IDs that are parents of any rule.allowedCircles entry */
+    allowedCircleParentGroupIDs: Set<string>;
+    /** MLS group IDs where at least one rule.allowedDIDs entry is a member */
+    allowedDIDGroupIDs: Set<string>;
+};
+export type BroadcastScopeInput = {
+    resolvedRule: ResolvedAccessRule;
+    /** MLS group IDs of sender's own memberships that already passed catalog-match for this doc */
+    senderGroupIDs: Array<string>;
+};
+/**
+ * Compute the set of MLS group IDs to broadcast a document to,
+ * given its resolved access rule and the sender's group memberships.
+ *
+ * Pure, synchronous. The caller is responsible for:
+ * - Pre-resolving the access rule into a `ResolvedAccessRule` (all rule-side
+ *   lookups — circle parent groups and per-DID group memberships —
+ *   collapsed to MLS group ID sets).
+ * - Pre-filtering `senderGroupIDs` by catalog-match against the document.
+ *
+ * Per spec §3 "Sync routing" (sender side): a sender's own MLS group is a
+ * valid broadcast scope iff that group is the encryption perimeter for at
+ * least one allowed principal — either the group itself is in allowedGroups,
+ * or an allowed circle's parent group matches, or an allowed DID is a member
+ * of that group. The receiver applies the per-recipient access check on
+ * decrypt; the sender's own circle membership is irrelevant for routing.
+ */
+export declare function computeBroadcastScopes(input: BroadcastScopeInput): Array<string>;

package/lib/sync/scope-resolver.js

@@ -0,0 +1 @@
+export function computeBroadcastScopes(e){let{resolvedRule:r,senderGroupIDs:o}=e;switch(r.level){case"only_owner":return[];case"anyone":return Array.from(new Set(o));case"restricted":{let e=new Set;for(let t of o)(r.allowedGroupIDs.has(t)||r.allowedCircleParentGroupIDs.has(t)||r.allowedDIDGroupIDs.has(t))&&e.add(t);return Array.from(e)}default:{let e=r.level;throw Error(`Unknown access level: ${String(e)}`)}}}

package/lib/sync/sync-manager.d.ts

@@ -1,8 +1,10 @@
 import type { Runtime } from '@enkaku/runtime';
 import { type Identity, type SigningIdentity } from '@enkaku/token';
 import type { StoreProvider } 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 PeerConfig, type PeerConfigWithID, PeerRegistry } from './peer-registry.js';
 import { type SyncScope, type SyncTransportProvider } from './sync-client.js';
 export type SyncSessionInfo = {
@@ -25,10 +27,18 @@ export type SyncEvent = {
 };
 export type SyncManagerParams = {
     deployClusters?: (clusters: Record<string, unknown>) => Promise<void>;
+    graph: GraphInternals;
     runtime: Runtime;
     identity: Identity;
     logger: Logger;
     serverResolver?: (serverID: string) => SyncTransportProvider | undefined;
+    /**
+     * Receive-side storage mode forwarded to `applySyncMutations`.
+     * Defaults to `'persist'` when omitted.
+     */
+    storeUnreadable?: StoreUnreadableMode;
+    /** Server default access level — required when `storeUnreadable === 'drop'`. */
+    defaultAccessLevel?: DefaultAccessLevel;
 };
 export type MerkleSyncParams = {
     peerDID: string;

package/lib/sync/sync-manager.js

@@ -1 +1 @@
-import{EventEmitter as e}from"@enkaku/event";import{isSigningIdentity as t}from"@enkaku/token";import{getGraphStore as r}from"@kubun/store-graph";import{applySyncMutations as s}from"./merkle-apply.js";import{buildMerkleTree as i}from"./merkle-tree.js";import{PeerRegistry as n}from"./peer-registry.js";import{SyncClient as o}from"./sync-client.js";export class SyncManager{#e;#t;#r;#s;#i=new e;#n=new Map;#o=new Map;#l;#a;constructor(e){this.#e=e.deployClusters,this.#t=e.runtime,this.#l=e.identity,this.#r=e.logger,this.#s=new n({runtime:e.runtime}),this.#a=e.serverResolver}get peerRegistry(){return this.#s}setIdentity(e){this.#l=e}setServerResolver(e){this.#a=e}async addPeer(e){await this.#s.addPeer(e),this.#r.info("Peer added",{peerDID:e.config.peerDID})}async removePeer(e){await this.#s.removePeer(e),this.#r.info("Peer removed",{peerDID:e.peerDID})}async updatePeerConfig(e){await this.#s.updatePeer(e),this.#r.info("Peer updated",{peerDID:e.peerDID})}async listPeers(e){return this.#s.listPeers(e)}async getPeer(e){return this.#s.getPeer(e)}async merkleSyncWithPeer(e){let n,{peerDID:l,scopes:a,delegationTokens:c=[],knownModelIDs:g,direction:m}=e;this.#r.info("Starting Merkle sync with peer",{peerDID:l,scopes:a});let p=await this.#s.getPeer({peerDID:l,stores:e.stores});if(!p)throw Error(`Peer ${l} not found`);let y=`merkle-sync-${l}-${Date.now()}`,u={peerID:l,startTime:Date.now(),documentsAttempted:0,documentsCompleted:0};this.#n.set(y,u),this.#c({type:"started",peerID:l,timestamp:Date.now()});try{let d=this.#l;if(!t(d))throw Error("Signing identity required for Merkle sync");let h=new o({runtime:this.#t,identity:d,logger:this.#r,serverResolver:this.#a});n=await h.connect(p.endpoint,l);let v=m??"pull";this.#r.info("Negotiating sync scopes",{scopes:a,direction:v});let{acceptedScopes:f,excludedDocumentIDs:D,missingClusters:w,direction:k}=await h.negotiate(n,a,c,g,v);if(0===f.length)return this.#r.info("No scopes accepted by peer"),this.#o.set(l,Date.now()),this.#c({type:"completed",peerID:l,timestamp:Date.now()}),this.#n.delete(y),{sessionID:y,divergentBuckets:0,messagesReceived:0,messagesSent:0,missingClusters:w};null!=w&&Object.keys(w).length>0&&(null!=this.#e?(this.#r.info("Deploying missing clusters from peer",{clusterCount:Object.keys(w).length}),await this.#e(w)):this.#r.warn("Missing clusters received but no deployClusters callback configured",{clusterCount:Object.keys(w).length})),this.#r.info("Building local Merkle tree",{acceptedScopes:f});let S=await r(e.stores),P=await S.getDocumentIDsForScope(f,D),R=await S.getMutationLogForDocuments(P),I=i(R),C=k??v;this.#r.info("Requesting Merkle sync from peer",{localTreeBuckets:Object.keys(I.buckets).length,direction:C});let B=await h.merkleSync(n,{scopes:f,excludedDocumentIDs:D,localTree:I,direction:C,localEntries:R});return B.mutationJWTs.length>0&&(this.#r.info("Applying sync mutations",{mutations:B.mutationJWTs.length}),u.documentsCompleted=(await s({db:e.stores,mutationJWTs:B.mutationJWTs})).applied),this.#o.set(l,Date.now()),this.#c({type:"completed",peerID:l,timestamp:Date.now()}),this.#r.info("Merkle sync completed",{divergentBuckets:B.divergentBuckets,mutationsReceived:B.mutationJWTs.length}),{sessionID:y,divergentBuckets:B.divergentBuckets,messagesReceived:B.mutationJWTs.length,messagesSent:B.mutationsSent,missingClusters:w}}catch(e){throw this.#r.error("Merkle sync failed",{peerDID:l,error:e}),this.#c({type:"error",peerID:l,timestamp:Date.now(),error:e instanceof Error?e.message:String(e)}),e}finally{if(null!=n)try{n.abort("SyncComplete"),await n.dispose()}catch{}this.#n.delete(y)}}getStatus(e){let{peerDID:t}=e,r=Array.from(this.#n.values()).filter(e=>!t||e.peerID===t).map(e=>({peerID:e.peerID,startTime:e.startTime,documentsAttempted:e.documentsAttempted,documentsCompleted:e.documentsCompleted})),s={};for(let[e,r]of this.#o.entries())t&&e!==t||(s[e]=r);return{activeSessions:r,lastSyncByPeer:s}}onSyncEvent(e){return this.#i.on("sync",e)}#c(e){this.#i.emit("sync",e).catch(e=>{this.#r.error("Error in sync event listener",{error:e})})}async dispose(){this.#n.clear(),this.#o.clear()}}
+import{EventEmitter as e}from"@enkaku/event";import{isSigningIdentity as t}from"@enkaku/token";import{getGraphStore as s}from"@kubun/store-graph";import{applySyncMutations as r}from"./merkle-apply.js";import{buildMerkleTree as i}from"./merkle-tree.js";import{PeerRegistry as n}from"./peer-registry.js";import{SyncClient as o}from"./sync-client.js";export class SyncManager{#e;#t;#s;#r;#i;#n=new e;#o=new Map;#a=new Map;#l;#c;#g;#p;constructor(e){this.#e=e.deployClusters,this.#t=e.graph,this.#s=e.runtime,this.#l=e.identity,this.#r=e.logger,this.#i=new n({runtime:e.runtime}),this.#c=e.serverResolver,this.#g=e.storeUnreadable??"persist",this.#p=e.defaultAccessLevel}get peerRegistry(){return this.#i}setIdentity(e){this.#l=e}setServerResolver(e){this.#c=e}async addPeer(e){await this.#i.addPeer(e),this.#r.info("Peer added",{peerDID:e.config.peerDID})}async removePeer(e){await this.#i.removePeer(e),this.#r.info("Peer removed",{peerDID:e.peerDID})}async updatePeerConfig(e){await this.#i.updatePeer(e),this.#r.info("Peer updated",{peerDID:e.peerDID})}async listPeers(e){return this.#i.listPeers(e)}async getPeer(e){return this.#i.getPeer(e)}async merkleSyncWithPeer(e){let n,{peerDID:a,scopes:l,delegationTokens:c=[],knownModelIDs:g,direction:p}=e;this.#r.info("Starting Merkle sync with peer",{peerDID:a,scopes:l});let m=await this.#i.getPeer({peerDID:a,stores:e.stores});if(!m)throw Error(`Peer ${a} not found`);let d=`merkle-sync-${a}-${Date.now()}`,h={peerID:a,startTime:Date.now(),documentsAttempted:0,documentsCompleted:0};this.#o.set(d,h),this.#m({type:"started",peerID:a,timestamp:Date.now()});try{let u=this.#l;if(!t(u))throw Error("Signing identity required for Merkle sync");let y=new o({runtime:this.#s,identity:u,logger:this.#r,serverResolver:this.#c});n=await y.connect(m.endpoint,a);let v=p??"pull";this.#r.info("Negotiating sync scopes",{scopes:l,direction:v});let{acceptedScopes:f,excludedDocumentIDs:D,missingClusters:w,direction:k}=await y.negotiate(n,l,c,g,v);if(0===f.length)return this.#r.info("No scopes accepted by peer"),this.#a.set(a,Date.now()),this.#m({type:"completed",peerID:a,timestamp:Date.now()}),this.#o.delete(d),{sessionID:d,divergentBuckets:0,messagesReceived:0,messagesSent:0,missingClusters:w};null!=w&&Object.keys(w).length>0&&(null!=this.#e?(this.#r.info("Deploying missing clusters from peer",{clusterCount:Object.keys(w).length}),await this.#e(w)):this.#r.warn("Missing clusters received but no deployClusters callback configured",{clusterCount:Object.keys(w).length})),this.#r.info("Building local Merkle tree",{acceptedScopes:f});let S=await s(e.stores),P=await S.getDocumentIDsForScope(f,D),R=await S.getMutationLogForDocuments(P),I=i(R),b=k??v;this.#r.info("Requesting Merkle sync from peer",{localTreeBuckets:Object.keys(I.buckets).length,direction:b});let C=await y.merkleSync(n,{scopes:f,excludedDocumentIDs:D,localTree:I,direction:b,localEntries:R});return C.mutationJWTs.length>0&&(this.#r.info("Applying sync mutations",{mutations:C.mutationJWTs.length}),h.documentsCompleted=(await r({db:e.stores,graph:this.#t,mutationJWTs:C.mutationJWTs,selfDID:this.#l.id,storeUnreadable:this.#g,defaultAccessLevel:this.#p})).applied),this.#a.set(a,Date.now()),this.#m({type:"completed",peerID:a,timestamp:Date.now()}),this.#r.info("Merkle sync completed",{divergentBuckets:C.divergentBuckets,mutationsReceived:C.mutationJWTs.length}),{sessionID:d,divergentBuckets:C.divergentBuckets,messagesReceived:C.mutationJWTs.length,messagesSent:C.mutationsSent,missingClusters:w}}catch(e){throw this.#r.error("Merkle sync failed",{peerDID:a,error:e}),this.#m({type:"error",peerID:a,timestamp:Date.now(),error:e instanceof Error?e.message:String(e)}),e}finally{if(null!=n)try{n.abort("SyncComplete"),await n.dispose()}catch{}this.#o.delete(d)}}getStatus(e){let{peerDID:t}=e,s=Array.from(this.#o.values()).filter(e=>!t||e.peerID===t).map(e=>({peerID:e.peerID,startTime:e.startTime,documentsAttempted:e.documentsAttempted,documentsCompleted:e.documentsCompleted})),r={};for(let[e,s]of this.#a.entries())t&&e!==t||(r[e]=s);return{activeSessions:s,lastSyncByPeer:r}}onSyncEvent(e){return this.#n.on("sync",e)}#m(e){this.#n.emit("sync",e).catch(e=>{this.#r.error("Error in sync event listener",{error:e})})}async dispose(){this.#o.clear(),this.#a.clear()}}

package/lib/types.d.ts

@@ -3,6 +3,15 @@ import type { SyncDirection, SyncProtocol } from './protocol.js';
 import type { PeerConfig, PeerConfigWithID } from './sync/peer-registry.js';
 import type { SyncScope } from './sync/sync-client.js';
 import type { SyncEvent, SyncStatus } from './sync/sync-manager.js';
+/**
+ * Receiver storage mode for incoming peer mutations.
+ * - `'persist'` — store every doc that passes catalog/group checks. Access
+ *   enforced at query time; unreadable docs remain in DB but filtered.
+ * - `'drop'` — apply read-access check at receive time using the local
+ *   peer's own DID as viewer. Mutations the local peer cannot read are
+ *   not persisted.
+ */
+export type StoreUnreadableMode = 'persist' | 'drop';
 export type GroupData = {
     id: string;
     name: string;
@@ -37,6 +46,14 @@ export type CatalogData = {
     filterCriteria: string;
     createdAt: string;
 };
+export type HubData = {
+    id: string;
+    label: string | null;
+    url: string;
+    serverDID: string | null;
+    createdAt: string;
+    updatedAt: string | null;
+};
 export type InviteToGroupData = {
     invitePayload: string;
     groupID: string;
@@ -73,56 +90,103 @@ export type UpdateCircleInput = {
     catalogIDs?: Array<string>;
 };
 export type GroupRequestContext = {
-    p2pCreateGroup: (input: {
+    create: (input: {
         name: string;
         description?: string;
+        hubs?: Array<{
+            url: string;
+            serverDID?: string | null;
+        }>;
     }) => Promise<GroupData>;
-    p2pGetGroups: () => Promise<Array<GroupData>>;
-    p2pGetGroup: (id: string) => Promise<GroupData | null>;
-    p2pAddGroupMember: (groupID: string, memberDID: string, role: string) => Promise<GroupMemberData>;
-    p2pGetGroupMembers: (groupID: string) => Promise<Array<GroupMemberData>>;
-    p2pCreateCircle: (params: {
+    list: () => Promise<Array<GroupData>>;
+    get: (id: string) => Promise<GroupData | null>;
+    addMember: (groupID: string, memberDID: string, role: string) => Promise<GroupMemberData>;
+    listMembers: (groupID: string) => Promise<Array<GroupMemberData>>;
+    createCircle: (params: {
         groupID: string;
         name: string;
         description?: string;
     }) => Promise<CircleData>;
-    p2pGetCircles: (groupID: string) => Promise<Array<CircleData>>;
-    p2pAddCircleMember: (circleID: string, memberDID: string, role: string) => Promise<CircleMemberData>;
-    p2pCreateCatalog: (params: {
+    listCircles: (groupID: string) => Promise<Array<CircleData>>;
+    addCircleMember: (circleID: string, memberDID: string, role: string) => Promise<CircleMemberData>;
+    createCatalog: (params: {
         name: string;
         description?: string;
         filterCriteria: string;
     }) => Promise<CatalogData>;
-    p2pGetCatalogs: (ownerDID?: string) => Promise<Array<CatalogData>>;
-    p2pInviteToGroup: (groupID: string, joinRequest: string) => Promise<InviteToGroupData>;
-    p2pJoinGroup: (invitePayload: string, joinRequestPayload: string) => Promise<JoinGroupData>;
-    p2pLeaveGroup: (groupID: string) => Promise<LeaveGroupData>;
-    p2pRemoveGroupMember: (groupID: string, memberDID: string) => Promise<RemoveGroupMemberData>;
-    p2pUpdateGroup: (input: UpdateGroupInput) => Promise<GroupData>;
-    p2pUpdateCircle: (input: UpdateCircleInput) => Promise<CircleData>;
-    p2pUpdateCatalog: (params: {
+    listCatalogs: (ownerDID?: string) => Promise<Array<CatalogData>>;
+    invite: (groupID: string, joinRequest: string) => Promise<InviteToGroupData>;
+    join: (invitePayload: string, joinRequestPayload: string) => Promise<JoinGroupData>;
+    leave: (groupID: string) => Promise<LeaveGroupData>;
+    removeMember: (groupID: string, memberDID: string) => Promise<RemoveGroupMemberData>;
+    update: (input: UpdateGroupInput) => Promise<GroupData>;
+    updateCircle: (input: UpdateCircleInput) => Promise<CircleData>;
+    updateCatalog: (params: {
         catalogID: string;
         name?: string;
         filterCriteria?: string;
     }) => Promise<CatalogData>;
-    p2pDeleteCatalog: (catalogID: string) => Promise<DeleteCatalogData>;
-    p2pDeleteCircle: (circleID: string) => Promise<DeleteCircleData>;
-    p2pRemoveCircleMember: (circleID: string, memberDID: string) => Promise<RemoveCircleMemberData>;
+    deleteCatalog: (catalogID: string) => Promise<DeleteCatalogData>;
+    deleteCircle: (circleID: string) => Promise<DeleteCircleData>;
+    removeCircleMember: (circleID: string, memberDID: string) => Promise<RemoveCircleMemberData>;
 };
 export type SyncRequestContext = {
-    syncAddPeer: (config: PeerConfig) => Promise<void>;
-    syncRemovePeer: (peerDID: string) => Promise<void>;
-    syncListPeers: () => Promise<Array<PeerConfigWithID>>;
-    syncGetStatus: (peerDID?: string) => SyncStatus;
+    addPeer: (config: PeerConfig) => Promise<void>;
+    removePeer: (peerDID: string) => Promise<void>;
+    listPeers: () => Promise<Array<PeerConfigWithID>>;
+    getStatus: (peerDID?: string) => SyncStatus;
 };
 export type P2PJoinRequestContext = {
-    p2pPrepareJoinRequest: () => Promise<{
+    prepareRequest: () => Promise<{
         joinRequest: string;
     }>;
-    p2pCompleteJoin: (invitePayload: string) => Promise<{
+    complete: (invitePayload: string) => Promise<{
         group: GroupData | null;
     }>;
 };
+export type CreateHubInput = {
+    url: string;
+    label?: string | null;
+    serverDID?: string | null;
+};
+export type UpdateHubInput = {
+    id: string;
+    url?: string;
+    label?: string | null;
+    serverDID?: string | null;
+};
+export type DeleteHubData = {
+    success: boolean;
+    boundGroupIDs: Array<string>;
+};
+export type HubRequestContext = {
+    list: () => Promise<Array<HubData>>;
+    get: (id: string) => Promise<HubData | null>;
+    create: (input: CreateHubInput) => Promise<HubData>;
+    update: (input: UpdateHubInput) => Promise<HubData>;
+    delete: (id: string, force?: boolean) => Promise<DeleteHubData>;
+    bind: (params: {
+        hubID: string;
+        groupID: string;
+    }) => Promise<boolean>;
+    unbind: (params: {
+        hubID: string;
+        groupID: string;
+    }) => Promise<boolean>;
+    listByGroup: (groupID: string) => Promise<Array<HubData>>;
+    listGroups: (hubID: string) => Promise<Array<GroupData>>;
+};
+export type P2PContext = {
+    group: GroupRequestContext;
+    sync: SyncRequestContext;
+    join: P2PJoinRequestContext;
+    hub: HubRequestContext;
+};
+declare module '@kubun/graphql' {
+    interface PluginContextMap {
+        p2p: P2PContext;
+    }
+}
 export type SyncSessionResult = {
     sessionID: string;
     divergentBuckets: number;
@@ -133,6 +197,11 @@ export type SyncSessionResult = {
 export type SyncPluginAPI = {
     /** Resolves when the HTTP sync transport is registered (only present when http option is enabled). */
     syncReady?: Promise<void>;
+    /**
+     * Resolves when hub relay setup completes. `DISABLED_HUB.ready` is already
+     * resolved when the `hub` plugin option is absent.
+     */
+    hubReady: Promise<void>;
     addPeer(config: PeerConfig): Promise<void>;
     removePeer(peerDID: string): Promise<void>;
     listPeers(): Promise<Array<PeerConfigWithID>>;

package/lib/util/mutex.d.ts

@@ -0,0 +1,4 @@
+export type Mutex = {
+    run<T>(fn: () => Promise<T>): Promise<T>;
+};
+export declare function createMutex(): Mutex;

package/lib/util/mutex.js

@@ -0,0 +1 @@
+export function createMutex(){let e=Promise.resolve();return{run(t){let r=e.then(()=>t());return e=r.catch(()=>{}),r}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/plugin-p2p",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "license": "see LICENSE.md",
   "type": "module",
   "main": "lib/index.js",
@@ -14,47 +14,50 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@enkaku/async": "^0.14.1",
-    "@enkaku/capability": "^0.14.0",
-    "@enkaku/client": "^0.14.4",
-    "@enkaku/codec": "^0.14.0",
-    "@enkaku/event": "^0.14.1",
-    "@enkaku/generator": "^0.14.0",
-    "@enkaku/group": "^0.14.6",
-    "@enkaku/http-client-transport": "^0.14.3",
-    "@enkaku/http-server-transport": "^0.14.2",
-    "@enkaku/hub-protocol": "^0.14.0",
-    "@enkaku/protocol": "^0.14.0",
-    "@enkaku/runtime": "^0.14.0",
-    "@enkaku/schema": "^0.14.0",
-    "@enkaku/server": "^0.14.4",
-    "@enkaku/stream": "^0.14.1",
-    "@enkaku/token": "0.14.1",
-    "@enkaku/transport": "0.14.1",
+    "@enkaku/async": "^0.15.0",
+    "@enkaku/capability": "^0.15.0",
+    "@enkaku/client": "^0.15.1",
+    "@enkaku/codec": "^0.15.0",
+    "@enkaku/event": "^0.15.0",
+    "@enkaku/generator": "^0.15.0",
+    "@enkaku/group": "^0.15.0",
+    "@enkaku/http-client-transport": "^0.15.0",
+    "@enkaku/http-server-transport": "^0.15.0",
+    "@enkaku/hub-protocol": "^0.15.0",
+    "@enkaku/hub-tunnel": "^0.15.0",
+    "@enkaku/protocol": "^0.15.0",
+    "@enkaku/runtime": "^0.15.0",
+    "@enkaku/schema": "^0.15.0",
+    "@enkaku/server": "^0.15.0",
+    "@enkaku/stream": "^0.15.0",
+    "@enkaku/token": "^0.15.0",
+    "@enkaku/transport": "^0.15.0",
     "@noble/hashes": "^2.2.0",
     "graphql": "^16.13.2",
-    "kysely": "^0.28.16",
-    "@kubun/client": "^0.8.0",
-    "@kubun/store-p2p": "^0.8.0",
-    "@kubun/graphql": "^0.8.1",
-    "@kubun/engine": "^0.8.2",
-    "@kubun/id": "^0.8.0",
-    "@kubun/hlc": "^0.8.0",
-    "@kubun/mutation": "^0.8.1",
-    "@kubun/db": "^0.8.1",
-    "@kubun/store-graph": "^0.8.1",
-    "@kubun/protocol": "^0.8.1",
-    "@kubun/logger": "^0.8.0",
-    "@kubun/db-adapter": "^0.8.1"
+    "kysely": "^0.28.17",
+    "@kubun/client": "^0.9.0",
+    "@kubun/db": "^0.9.0",
+    "@kubun/db-adapter": "^0.9.0",
+    "@kubun/engine": "^0.9.0",
+    "@kubun/store-p2p": "^0.9.0",
+    "@kubun/store-graph": "^0.9.0",
+    "@kubun/graphql": "^0.9.0",
+    "@kubun/hlc": "^0.9.0",
+    "@kubun/id": "^0.9.0",
+    "@kubun/logger": "^0.9.0",
+    "@kubun/mutation": "^0.9.0",
+    "@kubun/protocol": "^0.9.0"
   },
   "devDependencies": {
-    "@enkaku/hub-server": "^0.14.1",
+    "@enkaku/hub-server": "^0.15.0",
     "get-port": "^7.2.0",
-    "@kubun/db-better-sqlite": "^0.8.1",
-    "@kubun/plugin-connector": "^0.8.1",
-    "@kubun/plugin-rpc": "^0.8.1",
-    "@kubun/plugin-http": "^0.8.1",
-    "@kubun/test-utils": "^0.8.0"
+    "@kubun/db-node-sqlite": "^0.9.0",
+    "@kubun/db-better-sqlite": "^0.9.0",
+    "@kubun/hub": "^0.9.0",
+    "@kubun/plugin-connector": "^0.9.0",
+    "@kubun/plugin-http": "^0.9.0",
+    "@kubun/plugin-rpc": "^0.9.0",
+    "@kubun/test-utils": "^0.9.0"
   },
   "scripts": {
     "build:clean": "del lib",