@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/context/hub.js

@@ -1 +1,151 @@
-import{getP2PStore as e}from"@kubun/store-p2p";import{bindHubToGroup as t,createHub as r,deleteHub as s,getHub as a,listHubs as o,listHubsByGroup as u,unbindHubFromGroup as i,updateHub as n}from"../hub/manager.js";import{toISO as l}from"./types.js";function d(e){return{id:e.id,label:e.label,url:e.url,serverDID:e.serverDID,createdAt:e.createdAt.toISOString(),updatedAt:null==e.updatedAt?null:e.updatedAt.toISOString()}}export function createHubContext(c,p){return{list:async()=>(await o({stores:p.stores})).map(d),get:async e=>{let t=await a({stores:p.stores,id:e});return null==t?null:d(t)},create:async e=>d(await r({stores:p.stores,url:e.url,label:e.label,serverDID:e.serverDID})),update:async e=>d(await n({stores:p.stores,id:e.id,url:e.url,label:e.label,serverDID:e.serverDID})),delete:async(e,t)=>{let r=await s({stores:p.stores,id:e,force:t});return{success:r.success,boundGroupIDs:r.boundGroupIDs}},bind:async({hubID:e,groupID:r})=>{let s=await t({stores:p.stores,hubID:e,groupID:r});if(s){let t=await a({stores:p.stores,id:e});null!=t&&await p.emitter.emit("hubBound",{groupID:r,hubID:e,hubURL:t.url,serverDID:t.serverDID})}return s},unbind:async({hubID:e,groupID:t})=>{let r=await u({stores:p.stores,groupID:t}),s=r.find(t=>t.id===e)?.url??null,a=await i({stores:p.stores,hubID:e,groupID:t});return a&&null!=s&&await p.emitter.emit("hubUnbound",{groupID:t,hubID:e,hubURL:s}),a},listByGroup:async e=>(await u({stores:p.stores,groupID:e})).map(d),listGroups:async t=>{let r=await e(p.stores);return(await r.listGroupsByHubID(t)).map(e=>({id:e.id,name:e.name,description:e.description,createdBy:e.created_by,createdAt:l(e.created_at)}))},getGroupHealth:e=>p.monitor.getHealth(e),rejoinGroup:e=>p.rejoinGroup(e)}}
+import { getP2PStore } from '@kubun/store-p2p';
+import { bindHubToGroup, createHub, deleteHub, getHub, listHubs, listHubsByGroup, unbindHubFromGroup, updateHub } from '../hub/manager.js';
+import { toISO } from './types.js';
+function toHubData(hub) {
+    return {
+        id: hub.id,
+        label: hub.label,
+        url: hub.url,
+        serverDID: hub.serverDID,
+        createdAt: hub.createdAt.toISOString(),
+        updatedAt: hub.updatedAt == null ? null : hub.updatedAt.toISOString()
+    };
+}
+export function createHubContext(_ctx, deps) {
+    return {
+        list: async ()=>{
+            const hubs = await listHubs({
+                stores: deps.stores
+            });
+            return hubs.map(toHubData);
+        },
+        get: async (id)=>{
+            const hub = await getHub({
+                stores: deps.stores,
+                id
+            });
+            return hub == null ? null : toHubData(hub);
+        },
+        create: async (input)=>{
+            const hub = await createHub({
+                stores: deps.stores,
+                url: input.url,
+                label: input.label,
+                serverDID: input.serverDID,
+                runtime: deps.runtime
+            });
+            return toHubData(hub);
+        },
+        update: async (input)=>{
+            const hub = await updateHub({
+                stores: deps.stores,
+                id: input.id,
+                url: input.url,
+                label: input.label,
+                serverDID: input.serverDID
+            });
+            return toHubData(hub);
+        },
+        delete: async (id, force)=>{
+            const result = await deleteHub({
+                stores: deps.stores,
+                id,
+                force
+            });
+            return {
+                success: result.success,
+                boundGroupIDs: result.boundGroupIDs
+            };
+        },
+        bind: async ({ hubID, groupID })=>{
+            const inserted = await bindHubToGroup({
+                stores: deps.stores,
+                hubID,
+                groupID
+            });
+            if (inserted) {
+                const hub = await getHub({
+                    stores: deps.stores,
+                    id: hubID
+                });
+                if (hub != null) {
+                    const hubURL = hub.url;
+                    const serverDID = hub.serverDID;
+                    // Defer past the outermost commit: the `hubBound` listener reads the P2P
+                    // store on the main connection (deadlocks single-conn SQLite / uncommitted on PG).
+                    deps.stores.onCommit(()=>{
+                        deps.emitter.emit('hubBound', {
+                            groupID,
+                            hubID,
+                            hubURL,
+                            serverDID
+                        }).catch((error)=>{
+                            deps.logger.error('hubBound emit failed', {
+                                groupID,
+                                hubID,
+                                error
+                            });
+                        });
+                    });
+                }
+            }
+            return inserted;
+        },
+        unbind: async ({ hubID, groupID })=>{
+            // Capture URL from the (group, hub) binding row itself so a concurrent
+            // `deleteHub({ force: true })` racing this unbind can't strand us with
+            // a `removed === true` but no URL to emit. If the binding does not
+            // exist for this group/hub pair, `unbindHubFromGroup` returns false
+            // and no event fires.
+            const boundHubs = await listHubsByGroup({
+                stores: deps.stores,
+                groupID
+            });
+            const hubURL = boundHubs.find((h)=>h.id === hubID)?.url ?? null;
+            const removed = await unbindHubFromGroup({
+                stores: deps.stores,
+                hubID,
+                groupID
+            });
+            if (removed && hubURL != null) {
+                const boundURL = hubURL;
+                // Defer past the outermost commit: the `hubUnbound` listener reads the P2P
+                // store on the main connection (deadlocks single-conn SQLite / uncommitted on PG).
+                deps.stores.onCommit(()=>{
+                    deps.emitter.emit('hubUnbound', {
+                        groupID,
+                        hubID,
+                        hubURL: boundURL
+                    }).catch((error)=>{
+                        deps.logger.error('hubUnbound emit failed', {
+                            groupID,
+                            hubID,
+                            error
+                        });
+                    });
+                });
+            }
+            return removed;
+        },
+        listByGroup: async (groupID)=>{
+            const hubs = await listHubsByGroup({
+                stores: deps.stores,
+                groupID
+            });
+            return hubs.map(toHubData);
+        },
+        listGroups: async (hubID)=>{
+            const store = await getP2PStore(deps.stores);
+            const rows = await store.listGroupsByHubID(hubID);
+            return rows.map((row)=>({
+                    id: row.id,
+                    name: row.name,
+                    description: row.description,
+                    createdBy: row.created_by,
+                    createdAt: toISO(row.created_at)
+                }));
+        },
+        getGroupHealth: (groupID)=>deps.monitor.getHealth(groupID),
+        rejoinGroup: (groupID)=>deps.rejoinGroup(groupID)
+    };
+}

package/lib/context/join.js

@@ -1 +1,115 @@
-import{createKeyPackageBundle as e}from"@enkaku/group";import{decodeInvitePayload as t,encodeJoinRequest as r}from"../groups/invite-payload.js";import{applyInviteGrants as i,applyInviteRevocations as o,finalizeJoinedGroup as a}from"../groups/join-utils.js";import{checkPeerAccess as s}from"./types.js";export function createJoinContext(g,n){return{prepareRequest:async()=>{s(g.viewerDID,n.identity.id,n.autoAcceptPeers);let t=n.identity,i=await e(t);return n.pendingJoinRequests.set(g.viewerDID,{publicPackage:i.publicPackage,privatePackage:i.privatePackage,did:t.id}),{joinRequest:r({did:t.id,publicPackage:i.publicPackage})}},complete:async e=>{s(g.viewerDID,n.identity.id,n.autoAcceptPeers);let r=n.pendingJoinRequests.get(g.viewerDID);if(null==r)throw Error("No pending join request found — call prepareJoinRequest first");let p=n.identity,u=t(e),c={publicPackage:r.publicPackage,privatePackage:r.privatePackage,ownerDID:p.id};await n.groupManager.joinGroup({stores:n.stores,identity:p,groupID:u.groupID,groupName:u.groupName,hubs:u.suggestedHubs,invite:u.invite,keyPackageBundle:c,welcomeMessage:u.welcomeMessage,ratchetTree:u.ratchetTree}),await i({stores:n.stores,selfDID:p.id,groupID:u.groupID,grants:u.grants,hlc:n.hlc,emitter:n.emitter,logger:n.logger}),await o({stores:n.stores,selfDID:p.id,groupID:u.groupID,revocations:u.revocations,hlc:n.hlc,emitter:n.emitter,logger:n.logger});let l=await a({stores:n.stores,emitter:n.emitter,invite:u});return n.pendingJoinRequests.delete(g.viewerDID),l}}}
+import { getP2PStore } from '@kubun/store-p2p';
+import { controlCapabilities, createKeyPackageBundle, readGroupAnchor } from '@kumiai/mls';
+import { decodeFullJoinRequest, decodeInvitePayload, encodeFullJoinRequest, encodeJoinRequest } from '../groups/invite-payload.js';
+import { applyInviteControlState, applyInviteGrants, applyInviteRevocations, finalizeJoinedGroup } from '../groups/join-utils.js';
+import { checkPeerAccess } from './types.js';
+export function createJoinContext(ctx, deps) {
+    return {
+        prepareRequest: async ()=>{
+            checkPeerAccess(ctx.viewerDID, deps.identity.id, deps.autoAcceptPeers);
+            const ownIdentity = deps.identity;
+            // The invitee leaf must advertise the anchor extension capability or
+            // commitInvite rejects the added leaf when joining an anchored group.
+            const bundle = await createKeyPackageBundle(ownIdentity, {
+                capabilities: controlCapabilities()
+            });
+            // Persisted, not stashed in memory: the offline exchange spans a human
+            // round-trip, so the answering call is routinely a different process —
+            // always so for a CLI device, where the two halves are two commands.
+            const p2pStore = await getP2PStore(deps.stores);
+            await p2pStore.putPendingJoinRequest({
+                did: ctx.viewerDID,
+                // The same encoding the connected join path hands between devices — a
+                // key package carries BigInts and binary that plain JSON drops.
+                payload: encodeFullJoinRequest({
+                    did: ownIdentity.id,
+                    publicPackage: bundle.publicPackage,
+                    privatePackage: bundle.privatePackage
+                })
+            });
+            const encoded = encodeJoinRequest({
+                did: ownIdentity.id,
+                publicPackage: bundle.publicPackage
+            });
+            return {
+                joinRequest: encoded
+            };
+        },
+        complete: async (invitePayloadStr)=>{
+            checkPeerAccess(ctx.viewerDID, deps.identity.id, deps.autoAcceptPeers);
+            const p2pStore = await getP2PStore(deps.stores);
+            const stored = await p2pStore.getPendingJoinRequest(ctx.viewerDID);
+            if (stored == null) {
+                // Naming the way out matters: "no pending join request" reads to an
+                // operator as "the payload you were handed is bad", and they go asking
+                // for a new invite against key material that was never the problem.
+                throw new Error('The invite payload is fine, but this device has no join request awaiting it — create a new join request and ask to be invited again.');
+            }
+            const ownIdentity = deps.identity;
+            const invite = decodeInvitePayload(invitePayloadStr);
+            const pending = decodeFullJoinRequest(stored.payload);
+            const keyPackageBundle = {
+                publicPackage: pending.publicPackage,
+                privatePackage: pending.privatePackage,
+                ownerDID: ownIdentity.id
+            };
+            await deps.groupManager.joinGroup({
+                stores: deps.stores,
+                identity: ownIdentity,
+                groupID: invite.groupID,
+                groupName: invite.groupName,
+                hubs: invite.suggestedHubs,
+                invite: invite.invite,
+                keyPackageBundle,
+                welcomeMessage: invite.welcomeMessage,
+                ratchetTree: invite.ratchetTree
+            });
+            await applyInviteGrants({
+                stores: deps.stores,
+                selfDID: ownIdentity.id,
+                groupID: invite.groupID,
+                grants: invite.grants,
+                hlc: deps.hlc,
+                emitter: deps.emitter,
+                logger: deps.logger
+            });
+            await applyInviteRevocations({
+                stores: deps.stores,
+                selfDID: ownIdentity.id,
+                groupID: invite.groupID,
+                revocations: invite.revocations,
+                hlc: deps.hlc,
+                emitter: deps.emitter,
+                logger: deps.logger
+            });
+            // Fold the invite-carried control state (ledger, access-defaults,
+            // catalogs) so the joiner projects circles/members at join — the same
+            // seeding `joinGroup` performs. The MLS handle now exists, so the genesis
+            // anchor is readable; the anchor is read through `deps.stores` so the
+            // registry shares its connection (a separate connection deadlocks
+            // single-connection SQLite).
+            await applyInviteControlState({
+                stores: deps.stores,
+                groupID: invite.groupID,
+                accessDefaults: invite.accessDefaults,
+                catalogs: invite.catalogs,
+                hlc: deps.hlc,
+                getGroupAnchor: (gid)=>deps.registry.readHandle(gid, (handle)=>readGroupAnchor(handle), {
+                        stores: deps.stores
+                    }),
+                getGroupLedger: (gid)=>deps.registry.readHandle(gid, (handle)=>handle.ledger, {
+                        stores: deps.stores
+                    }),
+                logger: deps.logger
+            });
+            const result = await finalizeJoinedGroup({
+                stores: deps.stores,
+                emitter: deps.emitter,
+                invite,
+                logger: deps.logger
+            });
+            await p2pStore.deletePendingJoinRequest(ctx.viewerDID);
+            return result;
+        }
+    };
+}

package/lib/context/peer.d.ts

@@ -0,0 +1,92 @@
+import type { ExecutionContext } from '@kubun/engine';
+import type { InviteAccessDefault } from '../groups/invite-payload.js';
+import type { GroupRequestContext, PeerRequestContext, SharePeerGroupData } from '../types.js';
+import type { ContextDeps } from './types.js';
+/**
+ * The inviter leg of the inbound dance, run on behalf of a verified caller by
+ * the `group/invite` peer handler. It designates NO circle itself: the joiner
+ * lands only in circles the inviter ALREADY designated — a `sharePeerGroup`
+ * pre-add, or an explicit `requestAddCircleMember` — which `collectInviteSeeds`
+ * snapshots from the ledger. Both of those land through an enacted commit, so
+ * by the time a designation is snapshottable here it is already durable. The
+ * invite runs as THIS device's own identity; the caller only supplies the group
+ * and its KeyPackage.
+ */
+export declare function serveGroupInvite(deps: ContextDeps, params: {
+    callerDID: string;
+    groupID: string;
+    joinRequest: string;
+}): Promise<{
+    invitePayload: string;
+}>;
+/**
+ * Apply the access-default rows a verified caller pushed for itself, run by the
+ * `group/push-control` peer handler. The source is UNTRUSTED, so the rows apply
+ * sender-bound — a row is kept only when its owner equals the authenticated
+ * caller, on top of the owner-equals-token-issuer check
+ * `applyAccessDefaultSetFrame` already enforces. A caller therefore cannot
+ * inject another owner's sharing policy.
+ *
+ * The caller must additionally be a member of the named group per THIS device's
+ * own membership view. The other remote ledger-ingest path rides the group's hub
+ * topic, whose MLS derivation is an implicit membership perimeter; this
+ * procedure is reachable by any accepted peer, so the perimeter is restated
+ * here. Fail-closed: an unknown group reads as no membership.
+ */
+export declare function servePushControl(deps: ContextDeps, params: {
+    callerDID: string;
+    groupID: string;
+    accessDefaults: Array<InviteAccessDefault>;
+}): Promise<{
+    accessDefaultsApplied: number;
+}>;
+export type DesignatePeerAccessParams = {
+    /**
+     * The request/settle facade, supplied rather than built here so a caller that
+     * mints an invite afterwards drives it through the same one.
+     */
+    groupCtx: GroupRequestContext;
+    /**
+     * The designating admin: admitted to the share circle beside the peer, and the
+     * owner whose read defaults are classified.
+     */
+    selfDID: string;
+    peerDID: string;
+    /** Share an existing group, or create a new one with this name. */
+    target: {
+        groupID: string;
+    } | {
+        name: string;
+    };
+    /**
+     * The calling mutation's name and the action its admin gate refuses by, so a
+     * failure inside a shared step names the operation the caller actually
+     * invoked. Without it every caller's errors would answer to whichever one
+     * happened to be written first.
+     */
+    operation: {
+        name: string;
+        adminAction: string;
+    };
+    /** The user's exact model selection, or `null` for no send leg. */
+    sendModels: Array<string> | null;
+    receiveActivate: boolean;
+    /** See {@link SharePeerGroupParams.setReadDefaultForCircle}. */
+    setReadDefaultForCircle: (modelID: string, circleID: string) => Promise<void>;
+};
+/**
+ * Designate one peer's access to one group: resolve or create the group, fold
+ * the commit-hub designation, find or create the share circle, admit both DIDs,
+ * and write the catalog + read defaults the share's scope rests on.
+ *
+ * Local state only — no peer connection is read or written. Whatever follows a
+ * designation (the MLS dance, registering the sync peer) belongs to the caller,
+ * so admitting a peer without a live connection reuses this rather than copying
+ * it: an invite payload snapshots exactly what these steps wrote, so a second
+ * copy of the seeding order drifts into a joiner landing in no circle, silently.
+ *
+ * The steps are ORDER-dependent — each reads what an earlier one wrote — so the
+ * sequence below is the contract, not an arrangement.
+ */
+export declare function designatePeerAccess(deps: ContextDeps, params: DesignatePeerAccessParams): Promise<SharePeerGroupData>;
+export declare function createPeerContext(ctx: ExecutionContext, deps: ContextDeps): PeerRequestContext;