@kubun/plugin-p2p 0.10.1 → 0.11.0

package/lib/sync/peer-registry.js

@@ -1 +1,107 @@
-import{getP2PStore as e}from"@kubun/store-p2p";export function negotiateDirection(e,t){return"both"===t?e:"both"===e?t:e===t?e:t}function t(e){var t,r;let o="string"==typeof(t=e.config)?JSON.parse(t):t??{};return{id:e.id,peerDID:e.peer_did,endpoint:e.endpoint,mode:e.mode,allowedUsers:"string"==typeof(r=e.allowed_users)?JSON.parse(r):r,priority:e.priority,trustLevel:e.trust_level,allowedDirection:o.allowedDirection,createdAt:e.created_at,updatedAt:e.updated_at}}export class PeerRegistry{#e;constructor(e){this.#e=e.runtime}async addPeer(t){let r=await e(t.stores);await r.addSyncPeer({id:this.#e.getRandomID(),peer_did:t.config.peerDID,endpoint:t.config.endpoint,mode:t.config.mode,allowed_users:t.config.allowedUsers,priority:t.config.priority,trust_level:t.config.trustLevel,config:{allowedDirection:t.config.allowedDirection},created_at:Date.now(),updated_at:Date.now()})}async getPeer(r){let o=await e(r.stores),i=await o.getSyncPeer(r.peerDID);if(i)return t(i)}async listPeers(r){let o=await e(r.stores);return(await o.listSyncPeers()).map(e=>t(e))}async updatePeer(t){let r=await this.getPeer({peerDID:t.peerDID,stores:t.stores});if(!r)throw Error(`Peer ${t.peerDID} not found`);let o={...r,...t.updates},i=await e(t.stores);await i.updateSyncPeer(t.peerDID,{endpoint:o.endpoint,mode:o.mode,allowed_users:o.allowedUsers,priority:o.priority,trust_level:o.trustLevel,config:{allowedDirection:o.allowedDirection}})}async removePeer(t){let r=await e(t.stores);await r.removeSyncPeer(t.peerDID)}async isPeerAllowed(e){return void 0!==await this.getPeer({peerDID:e.peerDID,stores:e.stores})}}
+import { getP2PStore } from '@kubun/store-p2p';
+/**
+ * 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 function negotiateDirection(requested, allowed) {
+    if (allowed === 'both') return requested;
+    if (requested === 'both') return allowed;
+    if (requested === allowed) return requested;
+    // Incompatible — responder policy wins
+    return allowed;
+}
+function parseAllowedUsers(value) {
+    if (typeof value === 'string') {
+        return JSON.parse(value);
+    }
+    return value;
+}
+function parseConfig(value) {
+    if (typeof value === 'string') {
+        return JSON.parse(value);
+    }
+    return value ?? {};
+}
+function rowToPeerConfig(row) {
+    const config = parseConfig(row.config);
+    return {
+        id: row.id,
+        peerDID: row.peer_did,
+        endpoint: row.endpoint,
+        mode: row.mode,
+        allowedUsers: parseAllowedUsers(row.allowed_users),
+        priority: row.priority,
+        trustLevel: row.trust_level,
+        allowedDirection: config.allowedDirection,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+    };
+}
+export class PeerRegistry {
+    #runtime;
+    constructor(params){
+        this.#runtime = params.runtime;
+    }
+    async addPeer(params) {
+        const store = await getP2PStore(params.stores);
+        await store.addSyncPeer({
+            id: this.#runtime.getRandomID(),
+            peer_did: params.config.peerDID,
+            endpoint: params.config.endpoint,
+            mode: params.config.mode,
+            allowed_users: params.config.allowedUsers,
+            priority: params.config.priority,
+            trust_level: params.config.trustLevel,
+            config: {
+                allowedDirection: params.config.allowedDirection
+            },
+            created_at: Date.now(),
+            updated_at: Date.now()
+        });
+    }
+    async getPeer(params) {
+        const store = await getP2PStore(params.stores);
+        const row = await store.getSyncPeer(params.peerDID);
+        if (!row) return undefined;
+        return rowToPeerConfig(row);
+    }
+    async listPeers(params) {
+        const store = await getP2PStore(params.stores);
+        const rows = await store.listSyncPeers();
+        return rows.map((row)=>rowToPeerConfig(row));
+    }
+    async updatePeer(params) {
+        const current = await this.getPeer({
+            peerDID: params.peerDID,
+            stores: params.stores
+        });
+        if (!current) throw new Error(`Peer ${params.peerDID} not found`);
+        const updated = {
+            ...current,
+            ...params.updates
+        };
+        const store = await getP2PStore(params.stores);
+        await store.updateSyncPeer(params.peerDID, {
+            endpoint: updated.endpoint,
+            mode: updated.mode,
+            allowed_users: updated.allowedUsers,
+            priority: updated.priority,
+            trust_level: updated.trustLevel,
+            config: {
+                allowedDirection: updated.allowedDirection
+            }
+        });
+    }
+    async removePeer(params) {
+        const store = await getP2PStore(params.stores);
+        await store.removeSyncPeer(params.peerDID);
+    }
+    async isPeerAllowed(params) {
+        const peer = await this.getPeer({
+            peerDID: params.peerDID,
+            stores: params.stores
+        });
+        return peer !== undefined;
+    }
+}

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

@@ -1 +1,24 @@
-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")}
+import { createAccessChecker } from '@kubun/engine';
+/**
+ * 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 function createReceiveAccessGate(params) {
+    const checker = createAccessChecker({
+        viewerDID: params.selfDID,
+        db: params.db,
+        defaultAccessLevel: params.defaultAccessLevel
+    });
+    return (postState)=>checker(postState, 'read');
+}

package/lib/sync/scope-resolver.js

@@ -1 +1,41 @@
-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)}`)}}}
+/**
+ * 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 function computeBroadcastScopes(input) {
+    const { resolvedRule, senderGroupIDs } = input;
+    switch(resolvedRule.level){
+        case 'only_owner':
+            return [];
+        case 'anyone':
+            // Dedupe sender group IDs while preserving the input order.
+            return Array.from(new Set(senderGroupIDs));
+        case 'restricted':
+            {
+                const scopes = new Set();
+                for (const groupID of senderGroupIDs){
+                    if (resolvedRule.allowedGroupIDs.has(groupID) || resolvedRule.allowedCircleParentGroupIDs.has(groupID) || resolvedRule.allowedDIDGroupIDs.has(groupID)) {
+                        scopes.add(groupID);
+                    }
+                }
+                return Array.from(scopes);
+            }
+        default:
+            {
+                const _exhaustive = resolvedRule.level;
+                throw new Error(`Unknown access level: ${String(_exhaustive)}`);
+            }
+    }
+}

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

@@ -1,15 +1,15 @@
 import { Client } from '@enkaku/client';
 import type { ClientTransportOf } from '@enkaku/protocol';
-import type { Runtime } from '@enkaku/runtime';
-import type { SigningIdentity } from '@enkaku/token';
+import type { SigningIdentity } from '@kokuin/token';
 import type { Logger } from '@kubun/logger';
+import type { Runtime } from '@sozai/runtime';
 import type { SyncDirection, SyncProtocol } from '../protocol.js';
 /**
  * Provider for sync-specific transport to a peer's sync server.
  * The p2p plugin exposes this via `createSyncTransport()`.
  */
 export type SyncTransportProvider = {
-    createSyncTransport: (signal?: AbortSignal) => ClientTransportOf<SyncProtocol>;
+    createSyncTransport: (signal?: AbortSignal) => ClientTransportOf<SyncProtocol> | Promise<ClientTransportOf<SyncProtocol>>;
 };
 export type SyncClientParams = {
     runtime: Runtime;

package/lib/sync/sync-client.js

@@ -1 +1,192 @@
-import{Client as e}from"@enkaku/client";import{ClientTransport as t}from"@enkaku/http-client-transport";import{findDivergentBuckets as r,getTimeBuckets as n,SYNC_BATCH_SIZE as i}from"./merkle-tree.js";export class SyncClient{#e;#t;#r;#n;constructor(e){this.#e=e.runtime,this.#t=e.identity,this.#r=e.logger,this.#n=e.serverResolver}async connect(e,t){if(e.startsWith("direct://"))return this.#i(e);if(e.startsWith("http://")||e.startsWith("https://"))return this.#s(e,t);throw Error(`Unsupported endpoint scheme: ${e}`)}#s(r,n){if(null==n||""===n)throw Error("HTTP sync transport requires a serverID (peer DID) to authenticate; without it the server rejects all requests");let i=new t({url:r,fetch:this.#e.fetch});return new e({runtime:this.#e,identity:this.#t,logger:this.#r.getChild("sync-client"),serverID:n,transport:i})}#i(t){let r=t.replace("direct://","");if(!this.#n)throw Error("Server resolver not configured for direct transport");let n=this.#n(r);if(!n)throw Error(`Server not found: ${r}`);let i=n.createSyncTransport();return new e({runtime:this.#e,identity:this.#t,logger:this.#r.getChild("sync-client"),serverID:r,transport:i})}async negotiate(e,t,r=[],n,i){this.#r.debug("Negotiate: sending {scopeCount} scopes",{scopeCount:t.length});let s=await e.request("sync/negotiate",{param:{scopes:t,delegationTokens:r,knownModelIDs:n,direction:i}});return this.#r.debug("Negotiate: accepted {acceptedCount} scopes, excluded {excludedCount} docs",{acceptedCount:s.acceptedScopes.length,excludedCount:s.excludedDocumentIDs.length}),s}async merkleSync(e,t){let{scopes:s,excludedDocumentIDs:o,localTree:c,direction:l,localEntries:a,delegationTokens:u}=t;this.#r.debug("MerkleSync: creating channel with {buckets} local buckets",{buckets:Object.keys(c.buckets).length});let h=e.createChannel("sync/merkle-sync",{param:{scopes:s,excludedDocumentIDs:o,tree:c.buckets,direction:l,...null!=u&&{delegationTokens:u}}}),d=h.readable.getReader(),g=await d.read();if(g.done)throw Error("MerkleSync: channel closed before receiving remote tree");let p=g.value;if("tree"!==p.type)throw Error(`MerkleSync: expected 'tree' message, got '${p.type}'`);let m=r(c,{root:p.tree?.root??"",buckets:p.tree??{}}),y=m.length;this.#r.debug("MerkleSync: found {count} divergent buckets",{count:y});let f=0,k=async()=>{if("push"===l||"both"===l){let e=new Set(m),t=a.filter(t=>{let{minute:r}=n(t.hlc);return e.has(r)});for(let e=0;e<t.length;e+=i){let r=t.slice(e,e+i);await h.send({type:"mutations",mutationJWTs:r.map(e=>e.mutation_jwt)}),f+=r.length}}await h.send({type:"complete"})},v=async()=>{let e=[];for(;;){let{done:t,value:r}=await d.read();if(t)break;if("mutations"===r.type&&null!=r.mutationJWTs)e.push(...r.mutationJWTs);else if("complete"===r.type)break}return d.releaseLock(),e},[,w]=await Promise.all([k(),v()]),b=await h;if(null!=b&&!b.success)throw Error("MerkleSync: responder reported failure");return this.#r.debug("MerkleSync: completed with {received} received, {sent} sent",{received:w.length,sent:f}),{mutationJWTs:w,divergentBuckets:y,mutationsSent:f}}}
+import { Client } from '@enkaku/client';
+import { ClientTransport as HTTPClientTransport } from '@enkaku/http-fetch';
+import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-tree.js';
+/**
+ * Client for connecting to peer servers for sync operations.
+ * Supports both direct (in-process) and HTTP transports.
+ *
+ * Uses a raw Enkaku `Client<SyncProtocol>` for sync connections rather than
+ * `KubunClient`, since only sync procedures (negotiate, merkle-sync) are needed.
+ */ export class SyncClient {
+    #runtime;
+    #identity;
+    #logger;
+    #serverResolver;
+    constructor(params){
+        this.#runtime = params.runtime;
+        this.#identity = params.identity;
+        this.#logger = params.logger;
+        this.#serverResolver = params.serverResolver;
+    }
+    /**
+   * Connect to a peer server using the specified endpoint.
+   * - `direct://server-id` - Use in-process direct transport via sync server
+   * - `http://...` or `https://...` - Use HTTP transport
+   */ async connect(endpoint, serverID) {
+        if (endpoint.startsWith('direct://')) {
+            return this.#connectDirect(endpoint);
+        }
+        if (endpoint.startsWith('http://') || endpoint.startsWith('https://')) {
+            return this.#connectHTTP(endpoint, serverID);
+        }
+        throw new Error(`Unsupported endpoint scheme: ${endpoint}`);
+    }
+    #connectHTTP(endpoint, serverID) {
+        if (serverID == null || serverID === '') {
+            throw new Error('HTTP sync transport requires a serverID (peer DID) to authenticate; without it the server rejects all requests');
+        }
+        const transport = new HTTPClientTransport({
+            url: endpoint,
+            fetch: this.#runtime.fetch
+        });
+        return new Client({
+            runtime: this.#runtime,
+            identity: this.#identity,
+            logger: this.#logger.getChild('sync-client'),
+            serverID,
+            transport
+        });
+    }
+    async #connectDirect(endpoint) {
+        const serverID = endpoint.replace('direct://', '');
+        if (!this.#serverResolver) {
+            throw new Error('Server resolver not configured for direct transport');
+        }
+        const provider = this.#serverResolver(serverID);
+        if (!provider) {
+            throw new Error(`Server not found: ${serverID}`);
+        }
+        // Get a sync-specific transport from the peer's p2p plugin. The provider may
+        // build the transport asynchronously (e.g. the hub-tunnel provider derives
+        // its epoch-bound inbox topics from the live MLS handle), so await it; an
+        // in-process provider returning a transport synchronously is unaffected.
+        const transport = await provider.createSyncTransport();
+        return new Client({
+            runtime: this.#runtime,
+            identity: this.#identity,
+            logger: this.#logger.getChild('sync-client'),
+            serverID,
+            transport
+        });
+    }
+    /**
+   * Negotiate sync scopes with peer.
+   */ async negotiate(client, scopes, delegationTokens = [], knownModelIDs, direction) {
+        this.#logger.debug('Negotiate: sending {scopeCount} scopes', {
+            scopeCount: scopes.length
+        });
+        const result = await client.request('sync/negotiate', {
+            param: {
+                scopes,
+                delegationTokens,
+                knownModelIDs,
+                direction
+            }
+        });
+        this.#logger.debug('Negotiate: accepted {acceptedCount} scopes, excluded {excludedCount} docs', {
+            acceptedCount: result.acceptedScopes.length,
+            excludedCount: result.excludedDocumentIDs.length
+        });
+        return result;
+    }
+    /**
+   * Perform Merkle tree-based sync with peer using bidirectional channel.
+   * Sends local tree and divergent mutations, receives remote mutations.
+   */ async merkleSync(client, params) {
+        const { scopes, excludedDocumentIDs, localTree, direction, localEntries, delegationTokens } = params;
+        this.#logger.debug('MerkleSync: creating channel with {buckets} local buckets', {
+            buckets: Object.keys(localTree.buckets).length
+        });
+        const channelCall = client.createChannel('sync/merkle-sync', {
+            param: {
+                scopes,
+                excludedDocumentIDs,
+                tree: localTree.buckets,
+                direction,
+                ...delegationTokens != null && {
+                    delegationTokens
+                }
+            }
+        });
+        // Step 1: Read the responder's tree from the first message
+        const reader = channelCall.readable.getReader();
+        const firstRead = await reader.read();
+        if (firstRead.done) {
+            throw new Error('MerkleSync: channel closed before receiving remote tree');
+        }
+        const firstMessage = firstRead.value;
+        if (firstMessage.type !== 'tree') {
+            throw new Error(`MerkleSync: expected 'tree' message, got '${firstMessage.type}'`);
+        }
+        // Step 2: Compute divergent buckets
+        const remoteTree = {
+            root: firstMessage.tree?.root ?? '',
+            buckets: firstMessage.tree ?? {}
+        };
+        const divergentBuckets = findDivergentBuckets(localTree, remoteTree);
+        const divergentBucketCount = divergentBuckets.length;
+        this.#logger.debug('MerkleSync: found {count} divergent buckets', {
+            count: divergentBucketCount
+        });
+        // Step 3: Concurrent send and receive
+        let mutationsSent = 0;
+        // Send task: send divergent mutations to responder
+        const sendTask = async ()=>{
+            if (direction === 'push' || direction === 'both') {
+                // Filter local entries to those in divergent buckets
+                const divergentSet = new Set(divergentBuckets);
+                const entriesToSend = localEntries.filter((entry)=>{
+                    const { minute } = getTimeBuckets(entry.hlc);
+                    return divergentSet.has(minute);
+                });
+                // Send in batches
+                for(let i = 0; i < entriesToSend.length; i += SYNC_BATCH_SIZE){
+                    const batch = entriesToSend.slice(i, i + SYNC_BATCH_SIZE);
+                    await channelCall.send({
+                        type: 'mutations',
+                        mutationJWTs: batch.map((e)=>e.mutation_jwt)
+                    });
+                    mutationsSent += batch.length;
+                }
+            }
+            // Signal completion
+            await channelCall.send({
+                type: 'complete'
+            });
+        };
+        // Receive task: collect mutations from responder
+        const receiveTask = async ()=>{
+            const collectedJWTs = [];
+            while(true){
+                const { done, value } = await reader.read();
+                if (done) break;
+                if (value.type === 'mutations' && value.mutationJWTs != null) {
+                    collectedJWTs.push(...value.mutationJWTs);
+                } else if (value.type === 'complete') {
+                    break;
+                }
+            }
+            reader.releaseLock();
+            return collectedJWTs;
+        };
+        const [, mutationJWTs] = await Promise.all([
+            sendTask(),
+            receiveTask()
+        ]);
+        // Wait for the handler to finish processing (applying pushed mutations)
+        // before returning — prevents transport teardown racing with mutation application
+        const handlerResult = await channelCall;
+        if (handlerResult != null && !handlerResult.success) {
+            throw new Error('MerkleSync: responder reported failure');
+        }
+        this.#logger.debug('MerkleSync: completed with {received} received, {sent} sent', {
+            received: mutationJWTs.length,
+            sent: mutationsSent
+        });
+        return {
+            mutationJWTs,
+            divergentBuckets: divergentBucketCount,
+            mutationsSent
+        };
+    }
+}

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

@@ -1,8 +1,8 @@
-import type { Runtime } from '@enkaku/runtime';
-import { type Identity, type SigningIdentity } from '@enkaku/token';
+import { type Identity, type SigningIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { Logger } from '@kubun/logger';
+import type { Runtime } from '@sozai/runtime';
 import type { SyncDirection } from '../protocol.js';
 import type { StoreUnreadableMode } from '../types.js';
 import { type PeerConfig, type PeerConfigWithID, PeerRegistry } from './peer-registry.js';