@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/peer/connection-registry.js

@@ -0,0 +1,52 @@
+/**
+ * In-memory registry of live peer connections, keyed by `peerDID`. A second
+ * `connectPeer` to the same DID replaces the prior entry and disposes the old
+ * client + transport, so a stale connection is never leaked. Purely ephemeral:
+ * durable peer state (endpoint, DID) lives in the peer registry, written by the
+ * later dance ops — not here.
+ */ export class PeerConnectionRegistry {
+    #connections = new Map();
+    #logger;
+    constructor(params){
+        this.#logger = params.logger;
+    }
+    /**
+   * Register a connection, replacing (and disposing) any existing connection
+   * for the same `peerDID`.
+   */ async set(connection) {
+        const existing = this.#connections.get(connection.peerDID);
+        if (existing != null) {
+            await this.#dispose(existing);
+        }
+        this.#connections.set(connection.peerDID, connection);
+    }
+    get(peerDID) {
+        return this.#connections.get(peerDID);
+    }
+    list() {
+        return Array.from(this.#connections.values());
+    }
+    /** Dispose every held connection and clear the registry. */ async disposeAll() {
+        const all = Array.from(this.#connections.values());
+        this.#connections.clear();
+        await Promise.all(all.map((connection)=>this.#dispose(connection)));
+    }
+    async #dispose(connection) {
+        try {
+            await connection.client.dispose();
+        } catch (error) {
+            this.#logger.debug('peer client dispose failed', {
+                peerDID: connection.peerDID,
+                error
+            });
+        }
+        try {
+            await connection.transport.dispose();
+        } catch (error) {
+            this.#logger.debug('peer transport dispose failed', {
+                peerDID: connection.peerDID,
+                error
+            });
+        }
+    }
+}

package/lib/peer/handlers.d.ts

@@ -0,0 +1,69 @@
+import type { OwnIdentity } from '@kokuin/token';
+import type { KubunDB } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { InviteAccessDefault } from '../groups/invite-payload.js';
+export type CreatePeerHandlersParams = {
+    db: KubunDB;
+    identity: OwnIdentity;
+    logger: Logger;
+    /**
+     * DIDs permitted to reach the peer procedures. Mirrors the gating the join
+     * context applies (`prepareJoinRequest`, `completeJoin`): when set,
+     * only these DIDs may list the device's groups; when omitted, only the
+     * device's own identity (self / same-DID other device) may.
+     */
+    autoAcceptPeers?: Array<string>;
+    /**
+     * Run the SAME context op as the `prepareJoinRequest` GraphQL mutation, on
+     * behalf of the verified caller. Wired by the plugin factory to
+     * `createJoinContext(...).prepareRequest`; the handler does not reimplement
+     * MLS logic.
+     */
+    runPrepareJoin: (callerDID: string) => Promise<{
+        joinRequest: string;
+    }>;
+    /**
+     * Run the SAME context op as the `completeJoin` GraphQL mutation, on behalf of
+     * the verified caller. Wired to `createJoinContext(...).complete`.
+     */
+    runCompleteJoin: (callerDID: string, invitePayload: string) => Promise<{
+        group: {
+            id: string;
+        } | null;
+    }>;
+    /**
+     * Run the inviter leg of the inbound dance on behalf of the verified caller:
+     * add the caller to the group's share circles and run the invite as this
+     * device's own identity. Wired by the plugin factory to `serveGroupInvite`;
+     * the handler does not reimplement MLS or circle logic.
+     */
+    runInvite: (callerDID: string, groupID: string, joinRequest: string) => Promise<{
+        invitePayload: string;
+    }>;
+    /**
+     * Apply the access-default rows a verified caller pushed for itself. Wired by
+     * the plugin factory to `servePushControl`; the handler does not reimplement
+     * the untrusted-source apply — access-default rows are sender-bound to the
+     * caller.
+     */
+    runPushControl: (callerDID: string, param: {
+        groupID: string;
+        accessDefaults: Array<InviteAccessDefault>;
+    }) => Promise<{
+        accessDefaultsApplied: number;
+    }>;
+};
+/**
+ * Create the peer-protocol handlers served by plugin-p2p's own Enkaku server,
+ * a sibling to the sync handlers. `peer/groups` returns the serving device's
+ * DID and its groups so a connecting device can build its `connectPeer`
+ * payload.
+ *
+ * Unlike `sync/*` — whose procedure layer is intentionally open because
+ * authorization is enforced downstream per document — `peer/groups` has no
+ * downstream per-document gate: it lists group metadata directly. So the caller
+ * is authorized here, using the SAME gate the low-level dance mutations use
+ * (`checkPeerAccess`): the peer procedures wrap those same ops, and the group
+ * list is only served to DIDs already trusted to run the dance.
+ */
+export declare function createPeerHandlers(params: CreatePeerHandlersParams): Record<string, unknown>;

package/lib/peer/handlers.js

@@ -0,0 +1,110 @@
+import { getP2PStore } from '@kubun/store-p2p';
+import { checkPeerAccess } from '../context/types.js';
+import { SyncAccessDeniedError } from '../sync/errors.js';
+import { wrapHandlers } from '../util/handler-error.js';
+/**
+ * Create the peer-protocol handlers served by plugin-p2p's own Enkaku server,
+ * a sibling to the sync handlers. `peer/groups` returns the serving device's
+ * DID and its groups so a connecting device can build its `connectPeer`
+ * payload.
+ *
+ * Unlike `sync/*` — whose procedure layer is intentionally open because
+ * authorization is enforced downstream per document — `peer/groups` has no
+ * downstream per-document gate: it lists group metadata directly. So the caller
+ * is authorized here, using the SAME gate the low-level dance mutations use
+ * (`checkPeerAccess`): the peer procedures wrap those same ops, and the group
+ * list is only served to DIDs already trusted to run the dance.
+ */ export function createPeerHandlers(params) {
+    const { db, identity, logger, autoAcceptPeers, runPrepareJoin, runCompleteJoin, runInvite, runPushControl } = params;
+    // Derive the cryptographically-verified caller DID from the signed payload and
+    // reject a forged subject. Shared by every peer procedure — the same
+    // forged-`sub` guard `sync/negotiate` applies before any authorization.
+    function verifiedCaller(payload) {
+        const signed = payload;
+        if (signed.sub != null && signed.sub !== signed.iss) {
+            throw new SyncAccessDeniedError('forged-subject', 'Peer access denied: signed payload subject does not match issuer');
+        }
+        return signed.iss;
+    }
+    // Wrapped so a refusal carrying a registered KubunErrorCode reaches the
+    // calling device with its code and reason instead of enkaku's generic EK01.
+    return wrapHandlers({
+        'peer/groups': async (ctx)=>{
+            const callerDID = verifiedCaller(ctx.message.payload);
+            // Same gate as the dance mutations: only a trusted caller (in
+            // `autoAcceptPeers`, or the device's own DID when unset) may list groups.
+            checkPeerAccess(callerDID, identity.id, autoAcceptPeers);
+            const store = await getP2PStore(db);
+            const rows = await store.listGroups();
+            logger.debug('peer/groups served', {
+                callerDID,
+                groupCount: rows.length
+            });
+            return {
+                did: identity.id,
+                groups: rows.map((row)=>({
+                        id: row.id,
+                        name: row.name
+                    }))
+            };
+        },
+        // The joining device mints its KeyPackage bundle. `runPrepareJoin` runs the
+        // same context op as `prepareJoinRequest`, which itself re-checks
+        // `checkPeerAccess` for the verified caller and stashes the pending bundle
+        // keyed by that caller DID.
+        'group/prepare-join': async (ctx)=>{
+            const callerDID = verifiedCaller(ctx.message.payload);
+            const result = await runPrepareJoin(callerDID);
+            logger.debug('group/prepare-join served', {
+                callerDID
+            });
+            return {
+                joinRequest: result.joinRequest
+            };
+        },
+        // The joining device processes the Welcome the caller returns. `runCompleteJoin`
+        // runs the same context op as `completeJoin` (`joinGroup` + invite seeding),
+        // re-checking `checkPeerAccess` and consuming the pending bundle.
+        'group/complete-join': async (ctx)=>{
+            const callerDID = verifiedCaller(ctx.message.payload);
+            const result = await runCompleteJoin(callerDID, ctx.param.invitePayload);
+            logger.debug('group/complete-join served', {
+                callerDID,
+                groupID: result.group?.id ?? null
+            });
+            return {
+                groupID: result.group?.id ?? null
+            };
+        },
+        // The inviter leg of the inbound dance. Same gate as `peer/groups`: only a
+        // trusted caller may pull an invite. `runInvite` adds the caller to the
+        // group's share circles and runs the invite as this device's own identity,
+        // returning the Welcome + seeds for the caller to complete the join.
+        'group/invite': async (ctx)=>{
+            const callerDID = verifiedCaller(ctx.message.payload);
+            checkPeerAccess(callerDID, identity.id, autoAcceptPeers);
+            const result = await runInvite(callerDID, ctx.param.groupID, ctx.param.joinRequest);
+            logger.debug('group/invite served', {
+                callerDID,
+                groupID: ctx.param.groupID
+            });
+            return {
+                invitePayload: result.invitePayload
+            };
+        },
+        // A verified caller applies access-default rows it minted for itself. Same
+        // gate as `group/invite`. `runPushControl` applies those rows sender-bound to
+        // `callerDID`, so a trusted peer cannot inject another owner's sharing policy.
+        'group/push-control': async (ctx)=>{
+            const callerDID = verifiedCaller(ctx.message.payload);
+            checkPeerAccess(callerDID, identity.id, autoAcceptPeers);
+            const result = await runPushControl(callerDID, ctx.param);
+            logger.debug('group/push-control served', {
+                callerDID,
+                groupID: ctx.param.groupID,
+                accessDefaultsApplied: result.accessDefaultsApplied
+            });
+            return result;
+        }
+    });
+}

package/lib/protocol.d.ts

@@ -1,5 +1,5 @@
 import type { AnyClientMessageOf, AnyServerMessageOf } from '@enkaku/protocol';
-import type { FromSchema } from '@enkaku/schema';
+import type { FromSchema } from '@sozai/schema';
 export declare const syncProtocol: {
     readonly 'sync/negotiate': {
         readonly type: "request";
@@ -205,6 +205,217 @@ export declare const syncProtocol: {
     };
 };
 export type SyncProtocol = typeof syncProtocol;
+/**
+ * Peer protocol — the wire leg of the high-level peer ops. Served as a sibling
+ * to {@link syncProtocol} and advertised in `/info` under its own name so a
+ * connecting device can discover it independently of the data-sync protocol.
+ *
+ * The GraphQL mutations remain the app-facing surface; these procedures are the
+ * device-to-device leg the mutations dispatch to. `peer/groups` returns the
+ * serving device's DID and its groups for the `connectPeer` payload. The MLS
+ * dance procedures (`group/prepare-join`, `group/invite`, `group/complete-join`)
+ * extend this same protocol in later work.
+ */
+export declare const peerProtocol: {
+    readonly 'peer/groups': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {};
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly did: {
+                    readonly type: "string";
+                    readonly description: "DID of the serving device";
+                };
+                readonly groups: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                            readonly name: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["id", "name"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly description: "The serving device's groups (id + name)";
+                };
+            };
+            readonly required: readonly ["did", "groups"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'group/prepare-join': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {};
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly joinRequest: {
+                    readonly type: "string";
+                    readonly description: "The serving device's encoded join request (its KeyPackage)";
+                };
+            };
+            readonly required: readonly ["joinRequest"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'group/complete-join': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly invitePayload: {
+                    readonly type: "string";
+                    readonly description: "The invite payload (Welcome + seeds) minted by the caller";
+                };
+            };
+            readonly required: readonly ["invitePayload"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly groupID: {
+                    readonly type: readonly ["string", "null"];
+                    readonly description: "The joined group ID, or null when the group row was not found";
+                };
+            };
+            readonly required: readonly ["groupID"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'group/invite': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly groupID: {
+                    readonly type: "string";
+                    readonly description: "The group the caller wants to join";
+                };
+                readonly joinRequest: {
+                    readonly type: "string";
+                    readonly description: "The caller's encoded join request (its KeyPackage)";
+                };
+            };
+            readonly required: readonly ["groupID", "joinRequest"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly invitePayload: {
+                    readonly type: "string";
+                    readonly description: "The invite payload (Welcome + seeds) for the caller to complete the join";
+                };
+            };
+            readonly required: readonly ["invitePayload"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'group/push-control': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly groupID: {
+                    readonly type: "string";
+                    readonly description: "The group whose control state is being pushed";
+                };
+                readonly accessDefaults: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly ownerDID: {
+                                readonly type: "string";
+                            };
+                            readonly modelID: {
+                                readonly type: "string";
+                            };
+                            readonly permissionType: {
+                                readonly type: "string";
+                                readonly enum: readonly ["read", "write"];
+                            };
+                            readonly rule: {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly level: {
+                                        readonly type: "string";
+                                    };
+                                    readonly allowedDIDs: {
+                                        readonly type: readonly ["array", "null"];
+                                        readonly items: {
+                                            readonly type: "string";
+                                        };
+                                    };
+                                    readonly allowedCircles: {
+                                        readonly type: readonly ["array", "null"];
+                                        readonly items: {
+                                            readonly type: "string";
+                                        };
+                                    };
+                                    readonly allowedGroups: {
+                                        readonly type: readonly ["array", "null"];
+                                        readonly items: {
+                                            readonly type: "string";
+                                        };
+                                    };
+                                };
+                                readonly required: readonly ["level", "allowedDIDs", "allowedCircles", "allowedGroups"];
+                                readonly additionalProperties: false;
+                            };
+                            readonly hlc: {
+                                readonly type: "string";
+                            };
+                            readonly auth: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["ownerDID", "modelID", "permissionType", "rule", "hlc", "auth"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly description: "The caller's own signed access-default rows (sender-bound on apply)";
+                };
+            };
+            readonly required: readonly ["groupID", "accessDefaults"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly accessDefaultsApplied: {
+                    readonly type: "number";
+                    readonly description: "Count of pushed access-default rows applied (sender-bound, LWW)";
+                };
+            };
+            readonly required: readonly ["accessDefaultsApplied"];
+            readonly additionalProperties: false;
+        };
+    };
+};
+export type PeerProtocol = typeof peerProtocol;
+export type PeerGroupsResult = FromSchema<PeerProtocol['peer/groups']['result']>;
+export type PrepareJoinResult = FromSchema<PeerProtocol['group/prepare-join']['result']>;
+export type CompleteJoinParam = FromSchema<PeerProtocol['group/complete-join']['param']>;
+export type CompleteJoinResult = FromSchema<PeerProtocol['group/complete-join']['result']>;
+export type GroupInviteParam = FromSchema<PeerProtocol['group/invite']['param']>;
+export type GroupInviteResult = FromSchema<PeerProtocol['group/invite']['result']>;
+export type PushControlParam = FromSchema<PeerProtocol['group/push-control']['param']>;
+export type PushControlResult = FromSchema<PeerProtocol['group/push-control']['result']>;
 export type SyncNegotiateParams = FromSchema<SyncProtocol['sync/negotiate']['param']>;
 export type SyncNegotiateResult = FromSchema<SyncProtocol['sync/negotiate']['result']>;
 export type SyncMerkleSyncParams = FromSchema<SyncProtocol['sync/merkle-sync']['param']>;
@@ -214,3 +425,5 @@ export type SyncMerkleSyncResult = FromSchema<SyncProtocol['sync/merkle-sync']['
 export type SyncDirection = 'push' | 'pull' | 'both';
 export type SyncClientMessage = AnyClientMessageOf<SyncProtocol>;
 export type SyncServerMessage = AnyServerMessageOf<SyncProtocol>;
+export type PeerClientMessage = AnyClientMessageOf<PeerProtocol>;
+export type PeerServerMessage = AnyServerMessageOf<PeerProtocol>;