@kubun/plugin-p2p 0.11.0 → 0.12.0

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

@@ -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>;

package/lib/protocol.js

@@ -249,3 +249,271 @@ export const 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 const peerProtocol = {
+    'peer/groups': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                did: {
+                    type: 'string',
+                    description: 'DID of the serving device'
+                },
+                groups: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string'
+                            },
+                            name: {
+                                type: 'string'
+                            }
+                        },
+                        required: [
+                            'id',
+                            'name'
+                        ],
+                        additionalProperties: false
+                    },
+                    description: "The serving device's groups (id + name)"
+                }
+            },
+            required: [
+                'did',
+                'groups'
+            ],
+            additionalProperties: false
+        }
+    },
+    // The peer leg of the MLS invite dance. `group/prepare-join` and
+    // `group/complete-join` wrap the SAME context ops as the `prepareJoinRequest`
+    // and `completeJoin` GraphQL mutations — the serving (joining) device mints
+    // its KeyPackage bundle, then processes the Welcome the caller returns. Gated
+    // exactly like `peer/groups` (forged-`sub` rejection + `checkPeerAccess`).
+    'group/prepare-join': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                joinRequest: {
+                    type: 'string',
+                    description: "The serving device's encoded join request (its KeyPackage)"
+                }
+            },
+            required: [
+                'joinRequest'
+            ],
+            additionalProperties: false
+        }
+    },
+    'group/complete-join': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                invitePayload: {
+                    type: 'string',
+                    description: 'The invite payload (Welcome + seeds) minted by the caller'
+                }
+            },
+            required: [
+                'invitePayload'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                groupID: {
+                    type: [
+                        'string',
+                        'null'
+                    ],
+                    description: 'The joined group ID, or null when the group row was not found'
+                }
+            },
+            required: [
+                'groupID'
+            ],
+            additionalProperties: false
+        }
+    },
+    // The inviter leg of the inbound dance (`joinPeerGroup`). The caller (joiner)
+    // sends the group it wants to join plus its KeyPackage bundle; the serving
+    // device (inviter) adds the caller to the group's share circles, runs the
+    // invite as ITSELF, and returns the Welcome + invite payload. Gated exactly
+    // like the other peer procedures (forged-`sub` rejection + `checkPeerAccess`
+    // against the inviter's `autoAcceptPeers`), so only a trusted caller can pull
+    // an invite from this device.
+    'group/invite': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                groupID: {
+                    type: 'string',
+                    description: 'The group the caller wants to join'
+                },
+                joinRequest: {
+                    type: 'string',
+                    description: "The caller's encoded join request (its KeyPackage)"
+                }
+            },
+            required: [
+                'groupID',
+                'joinRequest'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                invitePayload: {
+                    type: 'string',
+                    description: 'The invite payload (Welcome + seeds) for the caller to complete the join'
+                }
+            },
+            required: [
+                'invitePayload'
+            ],
+            additionalProperties: false
+        }
+    },
+    // The caller hands the serving device its own access-default rows over the
+    // held connection, so the serving device applies them without waiting on hub
+    // fan-out (which is dropped for a group with no live binding). The source is
+    // UNTRUSTED: access-default rows are sender-bound (owner must equal the
+    // verified token issuer AND the authenticated caller). Gated exactly like
+    // `group/invite` (forged-`sub` rejection + `checkPeerAccess`).
+    'group/push-control': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                groupID: {
+                    type: 'string',
+                    description: 'The group whose control state is being pushed'
+                },
+                accessDefaults: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            ownerDID: {
+                                type: 'string'
+                            },
+                            modelID: {
+                                type: 'string'
+                            },
+                            permissionType: {
+                                type: 'string',
+                                enum: [
+                                    'read',
+                                    'write'
+                                ]
+                            },
+                            rule: {
+                                type: 'object',
+                                properties: {
+                                    level: {
+                                        type: 'string'
+                                    },
+                                    allowedDIDs: {
+                                        type: [
+                                            'array',
+                                            'null'
+                                        ],
+                                        items: {
+                                            type: 'string'
+                                        }
+                                    },
+                                    allowedCircles: {
+                                        type: [
+                                            'array',
+                                            'null'
+                                        ],
+                                        items: {
+                                            type: 'string'
+                                        }
+                                    },
+                                    allowedGroups: {
+                                        type: [
+                                            'array',
+                                            'null'
+                                        ],
+                                        items: {
+                                            type: 'string'
+                                        }
+                                    }
+                                },
+                                required: [
+                                    'level',
+                                    'allowedDIDs',
+                                    'allowedCircles',
+                                    'allowedGroups'
+                                ],
+                                additionalProperties: false
+                            },
+                            hlc: {
+                                type: 'string'
+                            },
+                            auth: {
+                                type: 'string'
+                            }
+                        },
+                        required: [
+                            'ownerDID',
+                            'modelID',
+                            'permissionType',
+                            'rule',
+                            'hlc',
+                            'auth'
+                        ],
+                        additionalProperties: false
+                    },
+                    description: "The caller's own signed access-default rows (sender-bound on apply)"
+                }
+            },
+            required: [
+                'groupID',
+                'accessDefaults'
+            ],
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                accessDefaultsApplied: {
+                    type: 'number',
+                    description: 'Count of pushed access-default rows applied (sender-bound, LWW)'
+                }
+            },
+            required: [
+                'accessDefaultsApplied'
+            ],
+            additionalProperties: false
+        }
+    }
+};

package/lib/schema.d.ts

@@ -1,4 +1,5 @@
 import type { SchemaExtension } from '@kubun/engine';
 import { type Logger } from '@kubun/logger';
 import { type P2PEventEmitter } from './groups/events.js';
-export declare function createP2PSchemaExtension(emitter: P2PEventEmitter, logger?: Logger): SchemaExtension;
+import type { SyncManager } from './sync/sync-manager.js';
+export declare function createP2PSchemaExtension(emitter: P2PEventEmitter, syncManager: SyncManager, logger?: Logger): SchemaExtension;