@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/groups/group-protocols.d.ts

@@ -0,0 +1,297 @@
+import type { FromSchema } from '@sozai/schema';
+/**
+ * App-lane group-rpc protocols carried over a group's rotating broadcast topics.
+ * Each peer is group-scoped (its topics encode the group), so payloads omit
+ * `groupID` — the handler already knows which group it serves. Loopback drop is
+ * automatic: the hub fans a publish to subscribers minus the sender, so a peer
+ * never receives its own broadcast.
+ *
+ * Procedure kinds map to the broadcast surface: `event` is fire-and-forget
+ * (`dispatch`); `request` is correlated (`request` for the first reply,
+ * `gather` for every reply within a window).
+ */
+/**
+ * Control plane: membership ledger, delegation, and advisory leave. All are
+ * self-authenticating at the payload level (signed tokens / HLC-stamped
+ * records), so the lane provides ordering + delivery, not authorization.
+ */
+export declare const controlProtocol: {
+    readonly 'control/ledgerEntry': {
+        readonly type: "event";
+        readonly description: "A self-signed control-ledger entry appended by its author.";
+        readonly data: {
+            readonly type: "object";
+            readonly properties: {
+                readonly token: {
+                    readonly type: "string";
+                    readonly description: "Signed control-ledger entry token.";
+                };
+            };
+            readonly required: readonly ["token"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'control/ledgerCatchup': {
+        readonly type: "request";
+        readonly description: "Ask current members for the group control ledger to backfill missed entries. Gathered: each member replies with its entries; the requester re-verifies every token.";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {};
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly entries: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Signed control-ledger entry tokens.";
+                };
+            };
+            readonly required: readonly ["entries"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'control/delegationShare': {
+        readonly type: "event";
+        readonly description: "Distribute a minted document/write capability token to group co-members.";
+        readonly data: {
+            readonly type: "object";
+            readonly properties: {
+                readonly token: {
+                    readonly type: "string";
+                    readonly description: "Stringified capability JWT.";
+                };
+                readonly hlc: {
+                    readonly type: "string";
+                    readonly description: "Grantor-stamped HLC, mirroring the issued row.";
+                };
+            };
+            readonly required: readonly ["token", "hlc"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'control/delegationRevoke': {
+        readonly type: "event";
+        readonly description: "Distribute a signed revocation record for a previously minted capability.";
+        readonly data: {
+            readonly type: "object";
+            readonly properties: {
+                readonly token: {
+                    readonly type: "string";
+                    readonly description: "Stringified signed revocation JWT.";
+                };
+                readonly hlc: {
+                    readonly type: "string";
+                    readonly description: "Revoker-stamped HLC, mirroring the stored row.";
+                };
+            };
+            readonly required: readonly ["token", "hlc"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'control/groupLeaveRequest': {
+        readonly type: "event";
+        readonly description: "Advisory voluntary-leave notice. Not authoritative — an admin must issue a real removeMember; receivers surface it as an event and never tombstone on it.";
+        readonly data: {
+            readonly type: "object";
+            readonly properties: {
+                readonly memberDID: {
+                    readonly type: "string";
+                    readonly description: "DID of the member announcing departure.";
+                };
+                readonly hlc: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["memberDID", "hlc"];
+            readonly additionalProperties: false;
+        };
+    };
+};
+/**
+ * Sync plane: document mutation broadcasts. Each entry carries a signed mutation
+ * JWT the receiver verifies before applying, so the lane is transport only.
+ */
+export declare const syncProtocol: {
+    readonly 'sync/mutationApply': {
+        readonly type: "event";
+        readonly description: "Broadcast a batch of signed document mutations to group members.";
+        readonly data: {
+            readonly type: "object";
+            readonly properties: {
+                readonly entries: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly mutationJWT: {
+                                readonly type: "string";
+                            };
+                            readonly docID: {
+                                readonly type: "string";
+                            };
+                            readonly version: {
+                                readonly type: "string";
+                                readonly description: "HLC string identifying this version.";
+                            };
+                            readonly modelID: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["mutationJWT", "docID", "version", "modelID"];
+                        readonly additionalProperties: false;
+                    };
+                };
+            };
+            readonly required: readonly ["entries"];
+            readonly additionalProperties: false;
+        };
+    };
+};
+export type ControlProtocol = typeof controlProtocol;
+export type SyncProtocol = typeof syncProtocol;
+export type LedgerEntryData = FromSchema<(typeof controlProtocol)['control/ledgerEntry']['data']>;
+export type LedgerCatchupResult = FromSchema<(typeof controlProtocol)['control/ledgerCatchup']['result']>;
+export type DelegationShareData = FromSchema<(typeof controlProtocol)['control/delegationShare']['data']>;
+export type DelegationRevokeData = FromSchema<(typeof controlProtocol)['control/delegationRevoke']['data']>;
+export type GroupLeaveRequestData = FromSchema<(typeof controlProtocol)['control/groupLeaveRequest']['data']>;
+export type MutationApplyData = FromSchema<(typeof syncProtocol)['sync/mutationApply']['data']>;
+/** The two app-lane protocols, keyed for `createGroupPeer({ protocols })`. */
+export declare const groupProtocols: {
+    control: {
+        readonly 'control/ledgerEntry': {
+            readonly type: "event";
+            readonly description: "A self-signed control-ledger entry appended by its author.";
+            readonly data: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly token: {
+                        readonly type: "string";
+                        readonly description: "Signed control-ledger entry token.";
+                    };
+                };
+                readonly required: readonly ["token"];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly 'control/ledgerCatchup': {
+            readonly type: "request";
+            readonly description: "Ask current members for the group control ledger to backfill missed entries. Gathered: each member replies with its entries; the requester re-verifies every token.";
+            readonly param: {
+                readonly type: "object";
+                readonly properties: {};
+                readonly additionalProperties: false;
+            };
+            readonly result: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly entries: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Signed control-ledger entry tokens.";
+                    };
+                };
+                readonly required: readonly ["entries"];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly 'control/delegationShare': {
+            readonly type: "event";
+            readonly description: "Distribute a minted document/write capability token to group co-members.";
+            readonly data: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly token: {
+                        readonly type: "string";
+                        readonly description: "Stringified capability JWT.";
+                    };
+                    readonly hlc: {
+                        readonly type: "string";
+                        readonly description: "Grantor-stamped HLC, mirroring the issued row.";
+                    };
+                };
+                readonly required: readonly ["token", "hlc"];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly 'control/delegationRevoke': {
+            readonly type: "event";
+            readonly description: "Distribute a signed revocation record for a previously minted capability.";
+            readonly data: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly token: {
+                        readonly type: "string";
+                        readonly description: "Stringified signed revocation JWT.";
+                    };
+                    readonly hlc: {
+                        readonly type: "string";
+                        readonly description: "Revoker-stamped HLC, mirroring the stored row.";
+                    };
+                };
+                readonly required: readonly ["token", "hlc"];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly 'control/groupLeaveRequest': {
+            readonly type: "event";
+            readonly description: "Advisory voluntary-leave notice. Not authoritative — an admin must issue a real removeMember; receivers surface it as an event and never tombstone on it.";
+            readonly data: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly memberDID: {
+                        readonly type: "string";
+                        readonly description: "DID of the member announcing departure.";
+                    };
+                    readonly hlc: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["memberDID", "hlc"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    sync: {
+        readonly 'sync/mutationApply': {
+            readonly type: "event";
+            readonly description: "Broadcast a batch of signed document mutations to group members.";
+            readonly data: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly entries: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly mutationJWT: {
+                                    readonly type: "string";
+                                };
+                                readonly docID: {
+                                    readonly type: "string";
+                                };
+                                readonly version: {
+                                    readonly type: "string";
+                                    readonly description: "HLC string identifying this version.";
+                                };
+                                readonly modelID: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly required: readonly ["mutationJWT", "docID", "version", "modelID"];
+                            readonly additionalProperties: false;
+                        };
+                    };
+                };
+                readonly required: readonly ["entries"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+};
+export type GroupProtocols = typeof groupProtocols;

package/lib/groups/group-protocols.js

@@ -0,0 +1,174 @@
+import { defineGroupProtocol } from '@kumiai/rpc';
+/**
+ * App-lane group-rpc protocols carried over a group's rotating broadcast topics.
+ * Each peer is group-scoped (its topics encode the group), so payloads omit
+ * `groupID` — the handler already knows which group it serves. Loopback drop is
+ * automatic: the hub fans a publish to subscribers minus the sender, so a peer
+ * never receives its own broadcast.
+ *
+ * Procedure kinds map to the broadcast surface: `event` is fire-and-forget
+ * (`dispatch`); `request` is correlated (`request` for the first reply,
+ * `gather` for every reply within a window).
+ */ /**
+ * Control plane: membership ledger, delegation, and advisory leave. All are
+ * self-authenticating at the payload level (signed tokens / HLC-stamped
+ * records), so the lane provides ordering + delivery, not authorization.
+ */ export const controlProtocol = defineGroupProtocol({
+    'control/ledgerEntry': {
+        type: 'event',
+        description: 'A self-signed control-ledger entry appended by its author.',
+        data: {
+            type: 'object',
+            properties: {
+                token: {
+                    type: 'string',
+                    description: 'Signed control-ledger entry token.'
+                }
+            },
+            required: [
+                'token'
+            ],
+            additionalProperties: false
+        }
+    },
+    'control/ledgerCatchup': {
+        type: 'request',
+        description: 'Ask current members for the group control ledger to backfill missed entries. Gathered: each member replies with its entries; the requester re-verifies every token.',
+        param: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                entries: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'Signed control-ledger entry tokens.'
+                }
+            },
+            required: [
+                'entries'
+            ],
+            additionalProperties: false
+        }
+    },
+    'control/delegationShare': {
+        type: 'event',
+        description: 'Distribute a minted document/write capability token to group co-members.',
+        data: {
+            type: 'object',
+            properties: {
+                token: {
+                    type: 'string',
+                    description: 'Stringified capability JWT.'
+                },
+                hlc: {
+                    type: 'string',
+                    description: 'Grantor-stamped HLC, mirroring the issued row.'
+                }
+            },
+            required: [
+                'token',
+                'hlc'
+            ],
+            additionalProperties: false
+        }
+    },
+    'control/delegationRevoke': {
+        type: 'event',
+        description: 'Distribute a signed revocation record for a previously minted capability.',
+        data: {
+            type: 'object',
+            properties: {
+                token: {
+                    type: 'string',
+                    description: 'Stringified signed revocation JWT.'
+                },
+                hlc: {
+                    type: 'string',
+                    description: 'Revoker-stamped HLC, mirroring the stored row.'
+                }
+            },
+            required: [
+                'token',
+                'hlc'
+            ],
+            additionalProperties: false
+        }
+    },
+    'control/groupLeaveRequest': {
+        type: 'event',
+        description: 'Advisory voluntary-leave notice. Not authoritative — an admin must issue a real removeMember; receivers surface it as an event and never tombstone on it.',
+        data: {
+            type: 'object',
+            properties: {
+                memberDID: {
+                    type: 'string',
+                    description: 'DID of the member announcing departure.'
+                },
+                hlc: {
+                    type: 'string'
+                }
+            },
+            required: [
+                'memberDID',
+                'hlc'
+            ],
+            additionalProperties: false
+        }
+    }
+});
+/**
+ * Sync plane: document mutation broadcasts. Each entry carries a signed mutation
+ * JWT the receiver verifies before applying, so the lane is transport only.
+ */ export const syncProtocol = defineGroupProtocol({
+    'sync/mutationApply': {
+        type: 'event',
+        description: 'Broadcast a batch of signed document mutations to group members.',
+        data: {
+            type: 'object',
+            properties: {
+                entries: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            mutationJWT: {
+                                type: 'string'
+                            },
+                            docID: {
+                                type: 'string'
+                            },
+                            version: {
+                                type: 'string',
+                                description: 'HLC string identifying this version.'
+                            },
+                            modelID: {
+                                type: 'string'
+                            }
+                        },
+                        required: [
+                            'mutationJWT',
+                            'docID',
+                            'version',
+                            'modelID'
+                        ],
+                        additionalProperties: false
+                    }
+                }
+            },
+            required: [
+                'entries'
+            ],
+            additionalProperties: false
+        }
+    }
+});
+/** The two app-lane protocols, keyed for `createGroupPeer({ protocols })`. */ export const groupProtocols = {
+    control: controlProtocol,
+    sync: syncProtocol
+};

package/lib/groups/invite-payload.d.ts

@@ -1,4 +1,4 @@
-import type { Invite, KeyPackageBundle } from '@enkaku/group';
+import type { Invite, KeyPackageBundle } from '@kumiai/mls';
 export type JoinRequestPayload = {
     did: string;
     publicPackage: KeyPackageBundle['publicPackage'];

package/lib/groups/invite-payload.js

@@ -1 +1,26 @@
-import{fromB64 as e,toB64 as n}from"@enkaku/codec";import{replacer as o,reviver as t}from"./mls-json.js";export function encodeJoinRequest(e){let t=JSON.stringify(e,o);return n(new TextEncoder().encode(t))}export function decodeJoinRequest(n){return JSON.parse(new TextDecoder().decode(e(n)),t)}export function encodeInvitePayload(e){let t=JSON.stringify(e,o);return n(new TextEncoder().encode(t))}export function decodeInvitePayload(n){return JSON.parse(new TextDecoder().decode(e(n)),t)}export function encodeFullJoinRequest(e){let t=JSON.stringify(e,o);return n(new TextEncoder().encode(t))}export function decodeFullJoinRequest(n){return JSON.parse(new TextDecoder().decode(e(n)),t)}
+import { fromB64, toB64 } from '@sozai/codec';
+import { replacer, reviver } from './mls-json.js';
+export function encodeJoinRequest(payload) {
+    const json = JSON.stringify(payload, replacer);
+    return toB64(new TextEncoder().encode(json));
+}
+export function decodeJoinRequest(encoded) {
+    const json = new TextDecoder().decode(fromB64(encoded));
+    return JSON.parse(json, reviver);
+}
+export function encodeInvitePayload(payload) {
+    const json = JSON.stringify(payload, replacer);
+    return toB64(new TextEncoder().encode(json));
+}
+export function decodeInvitePayload(encoded) {
+    const json = new TextDecoder().decode(fromB64(encoded));
+    return JSON.parse(json, reviver);
+}
+export function encodeFullJoinRequest(payload) {
+    const json = JSON.stringify(payload, replacer);
+    return toB64(new TextEncoder().encode(json));
+}
+export function decodeFullJoinRequest(encoded) {
+    const json = new TextDecoder().decode(fromB64(encoded));
+    return JSON.parse(json, reviver);
+}

package/lib/groups/join-utils.d.ts

@@ -9,6 +9,7 @@ export type FinalizeJoinedGroupParams = {
     invite: {
         groupID: string;
     };
+    logger?: Logger;
 };
 export declare function finalizeJoinedGroup(params: FinalizeJoinedGroupParams): Promise<{
     group: GroupData | null;

package/lib/groups/join-utils.js

@@ -1 +1,104 @@
-import{HLC as e}from"@kubun/hlc";import{getP2PStore as t}from"@kubun/store-p2p";import{toISO as r}from"../context/types.js";import{storeReceivedGrant as n}from"./store-received-grant.js";import{storeReceivedRevocation as i}from"./store-received-revocation.js";export async function finalizeJoinedGroup(e){let{stores:n,emitter:i,invite:o}=e,a=await t(n),l=await a.getGroup(o.groupID),p=null!=l?{id:l.id,name:l.name,description:l.description,createdBy:l.created_by,createdAt:r(l.created_at)}:null;return null!=p&&await i.emit("groupJoined",p),{group:p}}export async function applyInviteGrants(r){let{stores:i,selfDID:o,groupID:a,grants:l,hlc:p,emitter:u,logger:c}=r;if(null==l||0===l.length)return 0;let s=await t(i);return(await Promise.all(l.map(t=>n({p2pStore:s,token:t,groupID:a,hlc:e.serialize(p.now()),selfDID:o,...null!=u?{emitter:u}:{},...null!=c?{logger:c}:{}})))).reduce((e,t)=>e+ +!!t,0)}export async function applyInviteRevocations(r){let{stores:n,groupID:o,revocations:a,hlc:l,selfDID:p,emitter:u,logger:c}=r;if(null==a||0===a.length)return 0;let s=await t(n);return(await Promise.all(a.map(t=>i({p2pStore:s,token:t,groupID:o,hlc:e.serialize(l.now()),selfDID:p,...null!=u?{emitter:u}:{},...null!=c?{logger:c}:{}})))).reduce((e,t)=>e+ +!!t,0)}
+import { HLC as HLCClass } from '@kubun/hlc';
+import { getDelegationStore } from '@kubun/store-delegation';
+import { getP2PStore } from '@kubun/store-p2p';
+import { toISO } from '../context/types.js';
+import { storeReceivedGrant } from './store-received-grant.js';
+import { storeReceivedRevocation } from './store-received-revocation.js';
+export async function finalizeJoinedGroup(params) {
+    const { stores, emitter, invite, logger } = params;
+    const store = await getP2PStore(stores);
+    const groupRow = await store.getGroup(invite.groupID);
+    const joinedGroupData = groupRow != null ? {
+        id: groupRow.id,
+        name: groupRow.name,
+        description: groupRow.description,
+        createdBy: groupRow.created_by,
+        createdAt: toISO(groupRow.created_at)
+    } : null;
+    if (joinedGroupData != null) {
+        // Defer past the outermost commit (`stores` is that tx): the `groupJoined`
+        // listener reads the P2P store on the main connection (deadlocks single-conn
+        // SQLite / uncommitted on PG).
+        stores.onCommit(()=>{
+            emitter.emit('groupJoined', joinedGroupData).catch((error)=>{
+                logger?.error('groupJoined emit failed', {
+                    groupID: invite.groupID,
+                    error
+                });
+            });
+        });
+    }
+    return {
+        group: joinedGroupData
+    };
+}
+/**
+ * Apply invite-bootstrap grants after a join completes. Each token is verified
+ * and, when addressed to the joining device, stored as a held row so the
+ * engine's auto-attach can use it on the very first mutation — before any group
+ * broadcast arrives.
+ *
+ * No grantor HLC travels in the invite (it carries plain tokens, not the
+ * grantor's issued rows), so the joiner stamps a fresh HLC of its own at apply
+ * time. This is consistent with how every other join-time row the joiner
+ * materializes is locally stamped.
+ *
+ * Returns the number of grants that resulted in a stored held row.
+ */ export async function applyInviteGrants(params) {
+    const { stores, selfDID, groupID, grants, hlc, emitter, logger } = params;
+    if (grants == null || grants.length === 0) {
+        return 0;
+    }
+    const [store, delegationStore] = await Promise.all([
+        getP2PStore(stores),
+        getDelegationStore(stores)
+    ]);
+    const results = await Promise.all(grants.map((token)=>storeReceivedGrant({
+            delegationStore,
+            p2pStore: store,
+            token,
+            groupID,
+            hlc: HLCClass.serialize(hlc.now()),
+            selfDID,
+            ...emitter != null ? {
+                emitter
+            } : {},
+            ...logger != null ? {
+                logger
+            } : {}
+        })));
+    return results.reduce((count, applied)=>count + (applied ? 1 : 0), 0);
+}
+/**
+ * Apply invite-bootstrap revocations after a join completes. Each token is
+ * verified and stored — cap-known locally with matching `iss` yields a
+ * verified row, cap-unknown yields a pending row that the joiner will
+ * cross-check when the cap later arrives.
+ *
+ * The inviter's caller is responsible for filtering to verified revocations
+ * only; pending revocations do not travel via the invite envelope. The joiner
+ * stamps a fresh HLC since the inviter's HLC for these rows is not in the
+ * payload.
+ *
+ * Returns the number of revocations that resulted in a stored row.
+ */ export async function applyInviteRevocations(params) {
+    const { stores, groupID, revocations, hlc, selfDID, emitter, logger } = params;
+    if (revocations == null || revocations.length === 0) {
+        return 0;
+    }
+    const delegationStore = await getDelegationStore(stores);
+    const results = await Promise.all(revocations.map((token)=>storeReceivedRevocation({
+            delegationStore,
+            token,
+            groupID,
+            hlc: HLCClass.serialize(hlc.now()),
+            selfDID,
+            ...emitter != null ? {
+                emitter
+            } : {},
+            ...logger != null ? {
+                logger
+            } : {}
+        })));
+    return results.reduce((count, applied)=>count + (applied ? 1 : 0), 0);
+}

package/lib/groups/ledger-affected-events.d.ts

@@ -0,0 +1,15 @@
+import type { ProcessBroadcastResult } from './broadcast.js';
+import type { P2PEventEmitter } from './events.js';
+/**
+ * Emit the local `P2PEventEmitter` events for a remote-driven control-ledger
+ * entry that a receiving peer just applied, so GraphQL subscribers see
+ * remote circle/group changes live — the same events a local producer fires.
+ *
+ * Only `ledger:entry` projections surface as `affected`; every other applied
+ * message (delegation grant/revoke, advisory leave) already emits its own event
+ * from inside `processBroadcast`, so this covers exactly the circle/group
+ * projection rows the apply core returns rather than emits. The payloads are
+ * built from `affected.row`, which `processBroadcast` snapshots at the right
+ * moment (after-state for create/change, before-state for delete/remove).
+ */
+export declare function emitLedgerAffectedEvents(emitter: P2PEventEmitter, result: ProcessBroadcastResult): Promise<void>;