@kubun/plugin-p2p 0.11.0 → 0.12.1

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

@@ -1,10 +1,11 @@
 import type { VerifyTokenHook } from '@kokuin/capability';
 import type { SignedPayload } from '@kokuin/token';
 import type { KubunDB } from '@kubun/db';
-import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
+import { type DefaultAccessLevel, type 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';
+import { type CircleReadGrantResolver } from './authorize.js';
 import { type PeerRegistry } from './peer-registry.js';
 /**
  * Minimal handler context shape for sync/merkle-sync channel.
@@ -47,6 +48,13 @@ export type CreateMerkleSyncChannelHandlerParams = {
      * state and cannot drift.
      */
     getRevocationChecker?: () => Promise<VerifyTokenHook>;
+    /**
+     * Resolves the circle-granted read resolver. Shared with the negotiate handler
+     * so both gates accept identical scopes. Enables a circle member to pull an
+     * owner's docs for a model the owner's tier-2 read default shares with that
+     * circle.
+     */
+    getCircleReadGrant?: () => Promise<CircleReadGrantResolver>;
 };
 export declare function createMerkleSyncChannelHandler(params: CreateMerkleSyncChannelHandlerParams): (ctx: MerkleSyncChannelContext) => Promise<SyncMerkleSyncResult>;
 export {};

package/lib/sync/peer-registry.d.ts

@@ -8,15 +8,23 @@ import type { SyncDirection } from '../protocol.js';
  * Otherwise the responder's policy wins.
  */
 export declare function negotiateDirection(requested: SyncDirection, allowed: SyncDirection): SyncDirection;
+/**
+ * How to REACH a peer, plus the one policy a responder applies to it.
+ *
+ * Deliberately not a place to say what a peer may see. This row is written
+ * locally by whichever side dialled, nothing authenticates it, and it is absent
+ * entirely for a co-member reached through a group tunnel — so a gate keyed on
+ * it would be missing exactly when peering works as designed. What a peer may
+ * read is decided per document at the far end, against its authenticated DID.
+ */
 export type PeerConfig = {
     peerDID: string;
     endpoint: string;
-    mode: 'persistent' | 'on-demand';
-    allowedUsers: Array<string> | {
-        all: boolean;
-    };
-    priority: string;
-    trustLevel: 'trusted' | 'restricted';
+    /**
+     * What this device is willing to do with this peer — a resource decision
+     * about its own disk and apply path, not a claim about the peer's rights.
+     * The responder's policy wins; see {@link negotiateDirection}.
+     */
     allowedDirection?: SyncDirection;
 };
 export type PeerConfigWithID = PeerConfig & {
@@ -50,8 +58,4 @@ export declare class PeerRegistry {
         peerDID: string;
         stores: StoreProvider;
     }): Promise<void>;
-    isPeerAllowed(params: {
-        peerDID: string;
-        stores: StoreProvider;
-    }): Promise<boolean>;
 }

package/lib/sync/peer-registry.js

@@ -11,12 +11,6 @@ import { getP2PStore } from '@kubun/store-p2p';
     // 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);
@@ -29,10 +23,6 @@ function rowToPeerConfig(row) {
         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
@@ -49,10 +39,6 @@ export class PeerRegistry {
             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
             },
@@ -84,10 +70,6 @@ export class PeerRegistry {
         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
             }
@@ -97,11 +79,4 @@ export class PeerRegistry {
         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/sync-client.d.ts

@@ -11,11 +11,20 @@ import type { SyncDirection, SyncProtocol } from '../protocol.js';
 export type SyncTransportProvider = {
     createSyncTransport: (signal?: AbortSignal) => ClientTransportOf<SyncProtocol> | Promise<ClientTransportOf<SyncProtocol>>;
 };
+/**
+ * What a route carries beyond the peer DID. `tunnel://` names the group whose
+ * MLS epoch keys the session's inbox topics; `direct://` names nothing, so a
+ * resolver serving only in-process peers can ignore the second argument.
+ */
+export type SyncRoute = {
+    groupID: string;
+};
+export type SyncServerResolver = (serverID: string, route?: SyncRoute) => SyncTransportProvider | undefined;
 export type SyncClientParams = {
     runtime: Runtime;
     identity: SigningIdentity;
     logger: Logger;
-    serverResolver?: (serverID: string) => SyncTransportProvider | undefined;
+    serverResolver?: SyncServerResolver;
 };
 export type SyncScope = {
     modelID: string;
@@ -34,6 +43,7 @@ export declare class SyncClient {
     /**
      * Connect to a peer server using the specified endpoint.
      * - `direct://server-id` - Use in-process direct transport via sync server
+     * - `tunnel://group-id/peer-did` - Use a hub tunnel through the named group
      * - `http://...` or `https://...` - Use HTTP transport
      */
     connect(endpoint: string, serverID?: string): Promise<Client<SyncProtocol>>;

package/lib/sync/sync-client.js

@@ -12,6 +12,19 @@ import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-
     #identity;
     #logger;
     #serverResolver;
+    /**
+   * The context each session's lines carry, keyed by the client `connect` built
+   * for it.
+   *
+   * Held here rather than passed through `negotiate` / `merkleSync` because the
+   * peer a session is talking to is fixed when it is dialled and is not a
+   * parameter of either call. Without it these logs report bucket and mutation
+   * counts with nothing naming the peer, which is what makes two devices' logs
+   * impossible to join except by grepping DIDs out of unrelated lines.
+   *
+   * The transport's own `sessionID` is not here: it is minted inside the tunnel
+   * provider, which logs it against the same (group, peer, epoch).
+   */ #sessionLoggers = new WeakMap();
     constructor(params){
         this.#runtime = params.runtime;
         this.#identity = params.identity;
@@ -21,16 +34,27 @@ import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-
     /**
    * Connect to a peer server using the specified endpoint.
    * - `direct://server-id` - Use in-process direct transport via sync server
+   * - `tunnel://group-id/peer-did` - Use a hub tunnel through the named group
    * - `http://...` or `https://...` - Use HTTP transport
    */ async connect(endpoint, serverID) {
         if (endpoint.startsWith('direct://')) {
             return this.#connectDirect(endpoint);
         }
+        if (endpoint.startsWith('tunnel://')) {
+            return this.#connectTunnel(endpoint);
+        }
         if (endpoint.startsWith('http://') || endpoint.startsWith('https://')) {
             return this.#connectHTTP(endpoint, serverID);
         }
         throw new Error(`Unsupported endpoint scheme: ${endpoint}`);
     }
+    /** The session's own logger, or the client-wide one for a session built elsewhere. */ #loggerFor(client) {
+        return this.#sessionLoggers.get(client) ?? this.#logger;
+    }
+    #trackSession(client, context) {
+        this.#sessionLoggers.set(client, this.#logger.getChild('sync-client').with(context));
+        return client;
+    }
     #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');
@@ -39,20 +63,42 @@ import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-
             url: endpoint,
             fetch: this.#runtime.fetch
         });
-        return new Client({
+        return this.#trackSession(new Client({
             runtime: this.#runtime,
             identity: this.#identity,
             logger: this.#logger.getChild('sync-client'),
             serverID,
             transport
+        }), {
+            peerDID: serverID,
+            scheme: 'http'
         });
     }
     async #connectDirect(endpoint) {
-        const serverID = endpoint.replace('direct://', '');
+        return await this.#connectResolved(endpoint.replace('direct://', ''), 'direct');
+    }
+    /**
+   * `tunnel://<groupID>/<peerDID>` — a session relayed by the group's hub, with
+   * no server listening on either device. The audience comes from the route
+   * itself rather than from `connect`'s `serverID` argument: the route names the
+   * device whose inbox the frames are addressed to, so the two cannot disagree.
+   */ async #connectTunnel(endpoint) {
+        const route = endpoint.slice('tunnel://'.length);
+        const separator = route.indexOf('/');
+        const groupID = separator === -1 ? '' : route.slice(0, separator);
+        const peerDID = separator === -1 ? '' : route.slice(separator + 1);
+        if (groupID === '' || peerDID === '') {
+            throw new Error(`Invalid tunnel endpoint: ${endpoint} — expected tunnel://<groupID>/<peerDID>`);
+        }
+        return await this.#connectResolved(peerDID, 'tunnel', {
+            groupID
+        });
+    }
+    async #connectResolved(serverID, scheme, route) {
         if (!this.#serverResolver) {
-            throw new Error('Server resolver not configured for direct transport');
+            throw new Error(`Server resolver not configured for ${scheme} transport`);
         }
-        const provider = this.#serverResolver(serverID);
+        const provider = this.#serverResolver(serverID, route);
         if (!provider) {
             throw new Error(`Server not found: ${serverID}`);
         }
@@ -61,18 +107,25 @@ import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-
         // 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({
+        return this.#trackSession(new Client({
             runtime: this.#runtime,
             identity: this.#identity,
             logger: this.#logger.getChild('sync-client'),
             serverID,
             transport
+        }), {
+            peerDID: serverID,
+            scheme,
+            ...route == null ? {} : {
+                groupID: route.groupID
+            }
         });
     }
     /**
    * Negotiate sync scopes with peer.
    */ async negotiate(client, scopes, delegationTokens = [], knownModelIDs, direction) {
-        this.#logger.debug('Negotiate: sending {scopeCount} scopes', {
+        const logger = this.#loggerFor(client);
+        logger.debug('Negotiate: sending {scopeCount} scopes', {
             scopeCount: scopes.length
         });
         const result = await client.request('sync/negotiate', {
@@ -83,7 +136,7 @@ import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-
                 direction
             }
         });
-        this.#logger.debug('Negotiate: accepted {acceptedCount} scopes, excluded {excludedCount} docs', {
+        logger.debug('Negotiate: accepted {acceptedCount} scopes, excluded {excludedCount} docs', {
             acceptedCount: result.acceptedScopes.length,
             excludedCount: result.excludedDocumentIDs.length
         });
@@ -94,7 +147,8 @@ import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-
    * 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', {
+        const logger = this.#loggerFor(client);
+        logger.debug('MerkleSync: creating channel with {buckets} local buckets', {
             buckets: Object.keys(localTree.buckets).length
         });
         const channelCall = client.createChannel('sync/merkle-sync', {
@@ -108,6 +162,14 @@ import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-
                 }
             }
         });
+        // Marked handled the moment it exists, because the call is awaited LAST —
+        // after the send/receive pair below. A transport that aborts rejects all
+        // three, `Promise.all` throws first, and this one's rejection then reaches
+        // nobody: on React Native that is an error overlay with no message, which
+        // is exactly how a starved tunnel session presented during device QA. The
+        // await at the end still sees the rejection; this only stops it counting as
+        // unhandled in the window before that.
+        void channelCall.catch(()=>{});
         // Step 1: Read the responder's tree from the first message
         const reader = channelCall.readable.getReader();
         const firstRead = await reader.read();
@@ -125,7 +187,7 @@ import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-
         };
         const divergentBuckets = findDivergentBuckets(localTree, remoteTree);
         const divergentBucketCount = divergentBuckets.length;
-        this.#logger.debug('MerkleSync: found {count} divergent buckets', {
+        logger.debug('MerkleSync: found {count} divergent buckets', {
             count: divergentBucketCount
         });
         // Step 3: Concurrent send and receive
@@ -179,7 +241,7 @@ import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-
         if (handlerResult != null && !handlerResult.success) {
             throw new Error('MerkleSync: responder reported failure');
         }
-        this.#logger.debug('MerkleSync: completed with {received} received, {sent} sent', {
+        logger.debug('MerkleSync: completed with {received} received, {sent} sent', {
             received: mutationJWTs.length,
             sent: mutationsSent
         });

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

@@ -6,7 +6,7 @@ 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';
-import { type SyncScope, type SyncTransportProvider } from './sync-client.js';
+import { type SyncScope, type SyncServerResolver } from './sync-client.js';
 export type SyncSessionInfo = {
     peerID: string;
     startTime: number;
@@ -31,7 +31,7 @@ export type SyncManagerParams = {
     runtime: Runtime;
     identity: Identity;
     logger: Logger;
-    serverResolver?: (serverID: string) => SyncTransportProvider | undefined;
+    serverResolver?: SyncServerResolver;
     /**
      * Receive-side storage mode forwarded to `applySyncMutations`.
      * Defaults to `'persist'` when omitted.
@@ -47,6 +47,15 @@ export type MerkleSyncParams = {
     delegationTokens?: Array<string>;
     knownModelIDs?: Array<string>;
     direction?: SyncDirection;
+    /**
+     * Where to reach the peer, when the caller already resolved it. Omitted, the
+     * persisted registry answers and a peer with no row is an error.
+     *
+     * A route, and only a route: what a session serves is decided per document
+     * downstream, so supplying one reaches a peer the registry never heard of and
+     * grants it nothing.
+     */
+    endpoint?: string;
 };
 export declare class SyncManager {
     #private;
@@ -57,9 +66,11 @@ export declare class SyncManager {
      */
     setIdentity(identity: SigningIdentity): void;
     /**
-     * Configure the server resolver for direct transport connections.
+     * Configure the resolver for the transports built locally rather than dialled:
+     * `direct://` (in-process) and `tunnel://` (relayed by the group's hub, whose
+     * group id arrives as the resolver's `route`).
      */
-    setServerResolver(resolver: (serverID: string) => SyncTransportProvider | undefined): void;
+    setServerResolver(resolver: SyncServerResolver): void;
     addPeer(params: {
         config: PeerConfig;
         stores: StoreProvider;
@@ -92,5 +103,12 @@ export declare class SyncManager {
         stores: StoreProvider;
     }): SyncStatus;
     onSyncEvent(callback: (event: SyncEvent) => void): () => void;
+    /**
+     * Async-iterable view of the sync event stream, for bridging into a GraphQL
+     * subscription. An optional `filter` narrows to a single peer. Closing the
+     * generator (its `return()`, e.g. a subscriber disconnecting) unsubscribes the
+     * underlying listener, so no listener leaks past the consumer.
+     */
+    subscribeEvents(filter?: (event: SyncEvent) => boolean): AsyncGenerator<SyncEvent, void, void>;
     dispose(): Promise<void>;
 }

package/lib/sync/sync-manager.js

@@ -1,6 +1,7 @@
 import { isSigningIdentity } from '@kokuin/token';
 import { getGraphStore } from '@kubun/store-graph';
 import { EventEmitter } from '@sozai/event';
+import { fromEmitter } from '@sozai/generator';
 import { applySyncMutations } from './merkle-apply.js';
 import { buildMerkleTree } from './merkle-tree.js';
 import { PeerRegistry } from './peer-registry.js';
@@ -40,7 +41,9 @@ export class SyncManager {
         this.#identity = identity;
     }
     /**
-   * Configure the server resolver for direct transport connections.
+   * Configure the resolver for the transports built locally rather than dialled:
+   * `direct://` (in-process) and `tunnel://` (relayed by the group's hub, whose
+   * group id arrives as the resolver's `route`).
    */ setServerResolver(resolver) {
         this.#serverResolver = resolver;
     }
@@ -76,14 +79,21 @@ export class SyncManager {
             peerDID,
             scopes
         });
-        const peer = await this.#peerRegistry.getPeer({
-            peerDID,
-            stores: params.stores
-        });
-        if (!peer) {
-            throw new Error(`Peer ${peerDID} not found`);
+        let endpoint = params.endpoint;
+        if (endpoint == null) {
+            const peer = await this.#peerRegistry.getPeer({
+                peerDID,
+                stores: params.stores
+            });
+            if (!peer) {
+                throw new Error(`Peer ${peerDID} not found`);
+            }
+            endpoint = peer.endpoint;
         }
-        const sessionID = `merkle-sync-${peerDID}-${Date.now()}`;
+        // Random, not a timestamp: two syncs to the same peer in the same
+        // millisecond collide, and the second overwrites the first's entry in
+        // `#activeSessions` — so one of them never clears.
+        const sessionID = `merkle-sync-${peerDID}-${this.#runtime.getRandomID()}`;
         const sessionData = {
             peerID: peerDID,
             startTime: Date.now(),
@@ -108,7 +118,7 @@ export class SyncManager {
                 logger: this.#logger,
                 serverResolver: this.#serverResolver
             });
-            client = await syncClient.connect(peer.endpoint, peerDID);
+            client = await syncClient.connect(endpoint, peerDID);
             // Step 1: Negotiate scopes
             const direction = requestedDirection ?? 'pull';
             this.#logger.info('Negotiating sync scopes', {
@@ -185,6 +195,10 @@ export class SyncManager {
                     storeUnreadable: this.#storeUnreadable,
                     defaultAccessLevel: this.#defaultAccessLevel
                 });
+                // Attempted counts what arrived to be applied; completed counts what
+                // landed. Reported side by side, so leaving one at 0 makes every sync
+                // read as having applied nothing of nothing.
+                sessionData.documentsAttempted += syncResult.mutationJWTs.length;
                 sessionData.documentsCompleted = applyResult.applied;
                 if (applyResult.deferred > 0) {
                     this.#logger.info('Deferred sync mutations for retry next round', {
@@ -210,7 +224,12 @@ export class SyncManager {
                 missingClusters
             };
         } catch (error) {
-            this.#logger.error('Merkle sync failed', {
+            // DEBUG, and re-thrown: this layer cannot know whether the failure is a
+            // problem. An unreachable peer is `catchUpWithBestPeer`'s ORDINARY outcome
+            // (it warns once and walks past), while `syncPeer` raises to a screen.
+            // Reporting `error` here made every napping phone a red console error on
+            // the other one. Kept for the session-scoped detail no caller holds.
+            this.#logger.debug('Merkle sync failed', {
                 peerDID,
                 error
             });
@@ -257,6 +276,16 @@ export class SyncManager {
     onSyncEvent(callback) {
         return this.#events.on('sync', callback);
     }
+    /**
+   * Async-iterable view of the sync event stream, for bridging into a GraphQL
+   * subscription. An optional `filter` narrows to a single peer. Closing the
+   * generator (its `return()`, e.g. a subscriber disconnecting) unsubscribes the
+   * underlying listener, so no listener leaks past the consumer.
+   */ subscribeEvents(filter) {
+        return fromEmitter(this.#events, 'sync', {
+            filter
+        });
+    }
     #emitEvent(event) {
         this.#events.emit('sync', event).catch((error)=>{
             this.#logger.error('Error in sync event listener', {

package/lib/sync/tunnel-listeners.d.ts

@@ -0,0 +1,52 @@
+import type { ProcedureHandlers } from '@enkaku/server';
+import type { OwnIdentity } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { MailboxHub } from '@kumiai/hub-tunnel';
+import type { Runtime } from '@sozai/runtime';
+import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+import type { SyncProtocol } from '../protocol.js';
+export type TunnelListenersParams = {
+    stores: StoreProvider;
+    registry: GroupHandleRegistry;
+    identity: OwnIdentity;
+    localDID: string;
+    runtime: Runtime;
+    syncHandlers: ProcedureHandlers<SyncProtocol>;
+    /** The group's device-wide drain, or `undefined` when no hub is bound. */
+    tunnelHub: (groupID: string) => MailboxHub | undefined;
+    logger?: Logger;
+    idleTimeoutMs?: number;
+};
+export type TunnelListeners = {
+    /**
+     * Bring one group's listener set in line with its roster. Safe to call on any
+     * signal and at any frequency — repeated calls for an unchanged group do
+     * nothing.
+     */
+    reconcile: (groupID: string) => Promise<void>;
+    /** Reconcile every group this device has joined. */
+    reconcileAll: (groupIDs: Array<string>) => Promise<void>;
+    /** Stop and forget one group's listeners. */
+    removeGroup: (groupID: string) => Promise<void>;
+    dispose: () => Promise<void>;
+};
+/**
+ * The answering half of the tunnel: one listener per co-member per group, so a
+ * device that dials `tunnel://<groupID>/<ourDID>` finds something draining the
+ * mailbox.
+ *
+ * Without this a route resolves, opens, publishes its first frame and idles out:
+ * "nobody is home" and "nobody is listening" are the same silence to the dialer.
+ *
+ * ONE PER PEER, not one per group: every listener on a device receives on the
+ * same inbox topic, and two sharing a raw drain destroy each other's frames.
+ * `HubTunnelSyncListener` fronts the hub with a per-peer view for exactly this,
+ * so peers are separated here rather than multiplexed inside a session.
+ *
+ * Gated on this device having declared a profile — the same invariant presence
+ * runs on. A device that never opted in is in nobody's projection, so nothing
+ * can dial it and a listener would hold a subscription open for a session that
+ * cannot arrive.
+ */
+export declare function createTunnelListeners(params: TunnelListenersParams): TunnelListeners;