@kubun/plugin-p2p 0.8.3 → 0.10.0

package/lib/groups/group-handle-registry.d.ts

@@ -0,0 +1,90 @@
+import type { GroupHandle } from '@enkaku/group';
+import type { StoreProvider } from '@kubun/db';
+import { type Logger } from '@kubun/logger';
+export type GroupHandleRegistryParams = {
+    stores: StoreProvider;
+    deviceID: string;
+    logger?: Logger;
+};
+export type SeedParams = {
+    groupID: string;
+    handle: GroupHandle;
+    /**
+     * Pass the transactional `StoreProvider` (the `tx` from
+     * `stores.withTransaction(async (tx) => ...)`) so the initial MLS row
+     * write rolls back with the rest of the create/join flow on transaction
+     * abort. The cache install is deferred to `stores.onCommit` so a rollback
+     * leaves the cache empty.
+     */
+    stores: StoreProvider;
+};
+/**
+ * Single canonical access point for a device's MLS `GroupHandle` instances.
+ *
+ * Owns the per-group async mutex covering encrypt/decrypt and epoch-bumping
+ * operations, and persists the (possibly mutated) handle on every successful
+ * `withHandle` callback. On callback throw, persist is skipped; the in-memory
+ * handle retains its mutated state so the caller can decide whether to retry.
+ *
+ * All five mutation paths (manager member ops, context handlers, broadcast
+ * service encrypt/decrypt, hub-tunnel sync listener, hub-tunnel sync provider)
+ * route MLS state through this registry. Spec:
+ * `docs/superpowers/specs/2026-05-09-group-handle-registry-design.md`.
+ */
+export declare class GroupHandleRegistry {
+    #private;
+    constructor(params: GroupHandleRegistryParams);
+    /**
+     * Acquire the canonical handle for `groupID`, run `fn` under the per-group
+     * mutex, persist the (possibly mutated) handle on success, release.
+     * On throw, persist is skipped; in-memory handle retains its mutated state.
+     *
+     * Use this for in-place mutating ops (encrypt/decrypt) and reads. For
+     * epoch-bumping ops that produce a fresh `GroupHandle` (commitInvite,
+     * removeMember, processCommit), use `withHandleReplacing` instead.
+     *
+     * `options.stores` overrides the constructor-stored `StoreProvider` for the
+     * restore + persist DB calls. Callers running inside an engine transaction
+     * (e.g. context handlers under `mutateGraph`) MUST pass the transactional
+     * `tx` so reads + writes share the tx's connection. Without this, SQLite's
+     * write lock held by the outer tx blocks the registry's persist forever.
+     */
+    withHandle<T>(groupID: string, fn: (handle: GroupHandle) => Promise<T>, options?: {
+        stores?: StoreProvider;
+    }): Promise<T>;
+    /**
+     * Like `withHandle`, but the callback returns `{ result, updated }`.
+     * Registry replaces its cached handle with `updated` before persisting on
+     * success. Required for `@enkaku/group` epoch ops (`commitInvite`,
+     * `removeMember`, `processCommit`) which construct a fresh `GroupHandle`
+     * rather than mutating the input.
+     *
+     * `options.stores` follows the same semantics as `withHandle.options.stores`.
+     */
+    withHandleReplacing<T>(groupID: string, fn: (handle: GroupHandle) => Promise<{
+        result: T;
+        updated: GroupHandle;
+    }>, options?: {
+        stores?: StoreProvider;
+    }): Promise<T>;
+    /**
+     * Drop the cached handle for `groupID`. Next `withHandle` re-restores from DB.
+     * Called by `leaveGroup` after the MLS state row is deleted, and by tests.
+     */
+    invalidate(groupID: string): void;
+    /**
+     * Prime the cache with a freshly-built handle and persist the initial row
+     * via the supplied transactional `StoreProvider`. Called by `createGroup`
+     * and `joinGroup` so the row write rolls back with the rest of the
+     * create/join transaction on `withTransaction` abort. The cache install is
+     * deferred to `stores.onCommit` so a rollback leaves the cache empty.
+     *
+     * Must NOT be called concurrently with `withHandle` / `withHandleReplacing`
+     * on the same `groupID`: the `seed` row write is uncommitted until the
+     * surrounding transaction completes, so a concurrent `withHandle` whose
+     * mutex region runs before commit would `#restore` from a missing row.
+     * `createGroup` and `joinGroup` only seed for fresh groups not yet visible
+     * to other callers, so this constraint is naturally satisfied in practice.
+     */
+    seed(params: SeedParams): Promise<void>;
+}

package/lib/groups/group-handle-registry.js

@@ -0,0 +1 @@
+import{getKubunLogger as e}from"@kubun/logger";import{getP2PStore as t}from"@kubun/store-p2p";import{createMutex as r}from"../util/mutex.js";import{restoreMLSGroupHandle as s}from"./mls-group-handle.js";import{fromMLSStateRow as i,serializeMLSGroupState as a,toMLSStateInsert as l}from"./mls-state.js";export class GroupHandleRegistry{#e;#t;#r;#s=new Map;constructor(t){this.#e=t.stores,this.#t=t.deviceID,this.#r=t.logger??e("plugin-p2p:group-handle-registry")}withHandle(e,t,r){return this.#i(e,r,async(r,s)=>{let i=await t(r.handle);return await this.#a(s,e,r.handle),i})}withHandleReplacing(e,t,r){return this.#i(e,r,async(r,s)=>{let{result:i,updated:a}=await t(r.handle);return r.handle=a,await this.#a(s,e,a),i})}#i(e,t,r){let s=t?.stores??this.#e,i=this.#l(e);return i.mutex.run(async()=>(null==i.handle&&(i.handle=await this.#n(s,e)),r(i,s)))}invalidate(e){this.#s.delete(e)}async seed(e){let{groupID:r,handle:s,stores:i}=e,n=this.#s.get(r);if(n?.handle!=null)throw Error(`GroupHandleRegistry.seed: handle already cached for group ${r}`);let o=a(s),h=await t(i);await h.saveMLSState(l(o,r,this.#t)),i.onCommit(()=>{let e=this.#l(r);null==e.handle&&(e.handle=s)})}#l(e){let t=this.#s.get(e);return null==t&&(t={handle:null,mutex:r()},this.#s.set(e,t)),t}async #n(e,r){let a=await t(e),l=await a.getMLSState(r,this.#t);if(null==l)throw this.#r.debug("restore: no MLS state",{groupID:r,deviceID:this.#t}),Error(`No MLS state for group ${r}`);return this.#r.debug("restore: MLS state",{groupID:r,deviceID:this.#t,epoch:l.epoch}),await s(i(l))}async #a(e,r,s){let i=a(s),n=await t(e);await n.saveMLSState(l(i,r,this.#t)),this.#r.debug("persist: MLS state",{groupID:r,deviceID:this.#t,epoch:i.epoch})}}

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

@@ -8,13 +8,33 @@ export type FullJoinRequestPayload = {
     publicPackage: KeyPackageBundle['publicPackage'];
     privatePackage: KeyPackageBundle['privatePackage'];
 };
+export type SuggestedHub = {
+    url: string;
+    serverDID?: string;
+};
 export type InvitePayload = {
     groupID: string;
     groupName: string;
-    hubURLs: Array<string>;
+    suggestedHubs?: Array<SuggestedHub>;
     invite: Invite;
     welcomeMessage: unknown;
     ratchetTree: unknown;
+    /**
+     * Optional initial write-grant capability tokens (stringified JWTs) the
+     * inviter wants the joiner to hold immediately, before it starts receiving
+     * group broadcasts. Travels alongside the MLS invite as plain app-level data
+     * and is applied after the join completes — tokens addressed to the joiner
+     * are stored, others ignored.
+     */
+    grants?: Array<string>;
+    /**
+     * Optional initial signed-revocation tokens the inviter wants the joiner to
+     * apply immediately, before it starts receiving group broadcasts. Pending
+     * revocations (cap not yet known by the inviter) do NOT travel — only
+     * verified ones — though the receiving joiner re-cross-checks them anyway
+     * against any caps it already holds.
+     */
+    revocations?: Array<string>;
 };
 export declare function encodeJoinRequest(payload: JoinRequestPayload): string;
 export declare function decodeJoinRequest(encoded: string): JoinRequestPayload;

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

@@ -1,9 +1,11 @@
 import type { StoreProvider } from '@kubun/db';
+import type { HLC } from '@kubun/hlc';
+import type { Logger } from '@kubun/logger';
 import type { GroupData } from '../types.js';
-import type { GroupEventEmitter } from './events.js';
+import type { P2PEventEmitter } from './events.js';
 export type FinalizeJoinedGroupParams = {
     stores: StoreProvider;
-    emitter: GroupEventEmitter;
+    emitter: P2PEventEmitter;
     invite: {
         groupID: string;
     };
@@ -11,3 +13,67 @@ export type FinalizeJoinedGroupParams = {
 export declare function finalizeJoinedGroup(params: FinalizeJoinedGroupParams): Promise<{
     group: GroupData | null;
 }>;
+export type ApplyInviteGrantsParams = {
+    stores: StoreProvider;
+    /** DID of the joining device — only grants addressed to it are stored. */
+    selfDID: string;
+    /** Group the joined invite belongs to. */
+    groupID: string;
+    /** Stringified capability JWTs carried by the invite. */
+    grants?: Array<string>;
+    /** Joiner's HLC, used to stamp each stored held row. */
+    hlc: HLC;
+    /**
+     * Optional emitter notified after each held row is written. Lets the joiner's
+     * `ownDelegationTokenAdded` subscription surface invite-bootstrap grants
+     * without waiting for a subsequent broadcast.
+     */
+    emitter?: P2PEventEmitter;
+    logger?: Logger;
+};
+/**
+ * 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 declare function applyInviteGrants(params: ApplyInviteGrantsParams): Promise<number>;
+export type ApplyInviteRevocationsParams = {
+    stores: StoreProvider;
+    /** Group the joined invite belongs to. */
+    groupID: string;
+    /** Signed revocation JWTs carried by the invite. */
+    revocations?: Array<string>;
+    /** Joiner's HLC, used to stamp each stored revocation row. */
+    hlc: HLC;
+    /**
+     * DID of the joining device. Forwarded to `storeReceivedRevocation` for
+     * symmetry; revocation storage is identity-agnostic but the helper accepts
+     * the param.
+     */
+    selfDID: string;
+    /** Optional emitter forwarded to `storeReceivedRevocation`. */
+    emitter?: P2PEventEmitter;
+    logger?: Logger;
+};
+/**
+ * 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 declare function applyInviteRevocations(params: ApplyInviteRevocationsParams): Promise<number>;

package/lib/groups/join-utils.js

@@ -1 +1 @@
-import{getP2PStore as e}from"@kubun/store-p2p";import{toISO as t}from"../context/types.js";export async function finalizeJoinedGroup(r){let{stores:i,emitter:o,invite:n}=r,a=await e(i),p=await a.getGroup(n.groupID),u=null!=p?{id:p.id,name:p.name,description:p.description,createdBy:p.created_by,createdAt:t(p.created_at)}:null;return null!=u&&await o.emit("groupJoined",u),{group:u}}
+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)}

package/lib/groups/manager.d.ts

@@ -1,22 +1,29 @@
-import { type GroupHandle, type GroupPermission, type Invite, type KeyPackageBundle } from '@enkaku/group';
+import { type GroupPermission, type Invite, type KeyPackageBundle } from '@enkaku/group';
 import type { Identity, OwnIdentity } from '@enkaku/token';
 import type { StoreProvider } from '@kubun/db';
 import type { GroupBroadcastMessage } from './broadcast.js';
+import type { GroupHandleRegistry } from './group-handle-registry.js';
+import type { SuggestedHub } from './invite-payload.js';
 export type GroupManagerParams = {
     identity: Identity;
     getRandomID: () => string;
+    /**
+     * Single canonical access point for the device's MLS `GroupHandle` instances.
+     * Required: all member ops + createGroup/joinGroup route MLS state through
+     * the registry's per-group mutex with write-through persist.
+     */
+    registry: GroupHandleRegistry;
 };
 export type CreateGroupParams = {
     stores: StoreProvider;
     identity: OwnIdentity;
     name: string;
     description?: string;
-    hubURLs?: Array<string>;
+    hubs?: Array<SuggestedHub>;
     createdBy?: string;
 };
 export type CreateGroupResult = {
     groupID: string;
-    groupHandle: GroupHandle;
 };
 export type UpdateGroupParams = {
     stores: StoreProvider;
@@ -24,7 +31,6 @@ export type UpdateGroupParams = {
     update: {
         name?: string;
         description?: string;
-        hubURLs?: Array<string>;
     };
 };
 export type UpdateGroupResult = {
@@ -34,51 +40,53 @@ export type InviteToGroupParams = {
     stores: StoreProvider;
     groupID: string;
     identity: OwnIdentity;
-    groupHandle: GroupHandle;
     recipientDID: string;
     recipientKeyPackage: KeyPackageBundle['publicPackage'];
     permission: GroupPermission;
 };
 export type InviteToGroupResult = {
     invite: Invite;
-    welcomeMessage: unknown;
-    commitMessage: unknown;
-    updatedGroupHandle: GroupHandle;
+    /** Framed MLSMessage(Welcome) bytes for the invitee (`@enkaku/group@0.16.1`). */
+    welcomeMessage: Uint8Array;
+    /** Framed MLSMessage(Commit) bytes to fan out to existing members. */
+    commitMessage: Uint8Array;
+    /**
+     * Ratchet tree from the post-commit handle. Required by `joinGroup`
+     * callers that build an invite payload — they no longer hold a
+     * `GroupHandle` reference, so the manager surfaces the tree directly.
+     * Typed `unknown` to match `@enkaku/group`'s `ProcessWelcomeParams.ratchetTree`,
+     * which is opaque on that side too.
+     */
+    ratchetTree: unknown;
 };
 export type JoinGroupParams = {
     stores: StoreProvider;
     identity: OwnIdentity;
     groupID: string;
     groupName: string;
-    hubURLs: Array<string>;
+    hubs?: Array<SuggestedHub>;
     invite: Invite;
     keyPackageBundle: KeyPackageBundle;
     welcomeMessage: unknown;
     ratchetTree: unknown;
 };
-export type JoinGroupResult = {
-    groupHandle: GroupHandle;
-};
+export type JoinGroupResult = undefined;
 export type RemoveMemberParams = {
     stores: StoreProvider;
     groupID: string;
-    groupHandle: GroupHandle;
     leafIndex: number;
     memberDID: string;
 };
 export type RemoveMemberResult = {
-    commitMessage: unknown;
-    updatedGroupHandle: GroupHandle;
+    commitMessage: Uint8Array;
 };
 export type RemoveGroupMemberParams = {
     stores: StoreProvider;
     groupID: string;
-    groupHandle: GroupHandle;
     memberDID: string;
 };
 export type RemoveGroupMemberResult = {
-    commitMessage: unknown;
-    updatedGroupHandle: GroupHandle;
+    commitMessage: Uint8Array;
 };
 export type LeaveGroupParams = {
     stores: StoreProvider;

package/lib/groups/manager.js

@@ -1 +1 @@
-import{commitInvite as e,createGroup as t,createInvite as r,processWelcome as a,removeMember as i}from"@enkaku/group";import{HLC as o}from"@kubun/hlc";import{getGraphStore as s}from"@kubun/store-graph";import{getP2PStore as c}from"@kubun/store-p2p";import{serializeMLSGroupState as d}from"./mls-state.js";export class GroupManager{#e;#t;#r;constructor(e){this.#e=e.identity.id,this.#t=e.getRandomID,this.#r=new o({nodeID:e.identity.id})}async #a(e,t,r){let a=d(r),i=await c(e);await i.saveMLSState({group_id:t,device_id:this.#e,mls_state:a.mlsState,credential:a.credential,epoch:a.epoch,root_capability:a.rootCapability})}async createGroup(e){let r=this.#t(),{group:a}=await t(e.identity,r),i=await c(e.stores);return await i.createGroup({id:r,name:e.name,description:e.description??"",created_by:e.createdBy??e.identity.id,hub_urls:e.hubURLs??[],hlc:o.serialize(this.#r.now())}),await this.#a(e.stores,r,a),await i.addGroupMember({group_id:r,member_did:e.identity.id,role:"admin"}),{groupID:r,groupHandle:a}}async updateGroup(e){let t=o.serialize(this.#r.now()),r=await c(e.stores);return await r.updateGroup(e.groupID,{name:e.update.name,description:e.update.description,hub_urls:e.update.hubURLs,hlc:t}),{broadcast:{type:"group:update",groupID:e.groupID,update:{...e.update,hlc:t}}}}async inviteToGroup(t){let{invite:a}=await r({group:t.groupHandle,identity:t.identity,recipientDID:t.recipientDID,permission:t.permission}),{commitMessage:i,welcomeMessage:o,newGroup:s}=await e(t.groupHandle,t.recipientKeyPackage);await this.#a(t.stores,t.groupID,s);let d=await c(t.stores);return await d.addGroupMember({group_id:t.groupID,member_did:t.recipientDID,role:"admin"===t.permission?"admin":"member"}),{invite:a,welcomeMessage:o,commitMessage:i,updatedGroupHandle:s}}async joinGroup(e){let{group:t}=await a({identity:e.identity,invite:e.invite,welcome:e.welcomeMessage,keyPackageBundle:e.keyPackageBundle,ratchetTree:e.ratchetTree});await this.#a(e.stores,e.groupID,t);let r=await c(e.stores);return null==await r.getGroup(e.groupID)&&await r.createGroup({id:e.groupID,name:e.groupName,description:"",created_by:e.identity.id,hub_urls:e.hubURLs,hlc:o.serialize(this.#r.now())}),await r.addGroupMember({group_id:e.groupID,member_did:e.identity.id,role:"member"}),{groupHandle:t}}async removeMember(e){let{commitMessage:t,newGroup:r}=await i(e.groupHandle,e.leafIndex);await this.#a(e.stores,e.groupID,r);let a=await c(e.stores);return await a.removeGroupMember(e.groupID,e.memberDID),{commitMessage:t,updatedGroupHandle:r}}async removeGroupMember(e){let t=e.groupHandle.findMemberLeafIndex(e.memberDID);if(null==t)throw Error(`Member ${e.memberDID} not found in MLS group`);let{commitMessage:r,newGroup:a}=await i(e.groupHandle,t);await this.#a(e.stores,e.groupID,a);let o=await c(e.stores);return await o.removeGroupMember(e.groupID,e.memberDID),{commitMessage:r,updatedGroupHandle:a}}async leaveGroup(e){let t=await c(e.stores);await t.deleteMLSState(e.groupID,this.#e),await t.removeGroupMember(e.groupID,e.identity.id)}async loadGroup(e,t){let r=await c(e),a=await r.getMLSState(t,this.#e);if(null!=a)return{epoch:a.epoch,credential:a.credential}}async createCircle(e){let t=this.#t(),r=o.serialize(this.#r.now()),a=e.catalogIDs??[],i=await c(e.stores);return await i.createCircle({id:t,group_id:e.groupID,name:e.name,description:e.description??"",catalog_ids:a,hlc:r}),{circleID:t,broadcast:{type:"circle:create",circle:{id:t,groupID:e.groupID,name:e.name,description:e.description??"",catalogIDs:a,hlc:r}}}}async updateCircle(e){let t=o.serialize(this.#r.now()),r=[],a=await c(e.stores);if(null!=e.update.catalogIDs){let t=await a.getCircle(e.circleID),i=new Set(null!=t?t.catalog_ids:[]),o=e.update.catalogIDs.filter(e=>!i.has(e)),c=await s(e.stores);for(let e of(await Promise.all(o.map(e=>c.getCatalog(e)))))null!=e&&r.push({type:"catalog:create",catalog:{id:e.id,ownerDID:e.owner_did,name:e.name,description:e.description,filterCriteria:e.filter_criteria,hlc:e.hlc}})}await a.updateCircle(e.circleID,{name:e.update.name,description:e.update.description,catalog_ids:e.update.catalogIDs,hlc:t});let i={type:"circle:update",circleID:e.circleID,update:{...e.update,hlc:t}};return{broadcast:i,broadcasts:[i,...r]}}async deleteCircle(e){let t=o.serialize(this.#r.now()),r=await c(e.stores);return await r.deleteCircle(e.circleID),{broadcast:{type:"circle:delete",circleID:e.circleID,hlc:t}}}async addCircleMember(e){let t=await c(e.stores);if(!await t.isGroupMember(e.groupID,e.memberDID))throw Error(`${e.memberDID} is not a member of group ${e.groupID}`);let r=o.serialize(this.#r.now());return await t.addCircleMember({circle_id:e.circleID,member_did:e.memberDID,role:e.role,hlc:r}),{broadcast:{type:"member:add",member:{circleID:e.circleID,memberDID:e.memberDID,role:e.role,hlc:r}}}}async removeCircleMember(e){let t=o.serialize(this.#r.now()),r=await c(e.stores);return await r.removeCircleMember(e.circleID,e.memberDID),{broadcast:{type:"member:remove",circleID:e.circleID,memberDID:e.memberDID,hlc:t}}}}
+import{commitInvite as e,createGroup as r,createInvite as t,processWelcome as i,removeMember as a}from"@enkaku/group";import{HLC as o}from"@kubun/hlc";import{getGraphStore as s}from"@kubun/store-graph";import{getP2PStore as l}from"@kubun/store-p2p";import{bindHubToGroup as c,upsertHub as n}from"../hub/manager.js";export class GroupManager{#e;#r;#t;#i;constructor(e){this.#e=e.identity.id,this.#r=e.getRandomID,this.#t=new o({nodeID:e.identity.id}),this.#i=e.registry}async createGroup(e){let t=this.#r(),{group:i}=await r(e.identity,t),a=e.hubs??[];return await e.stores.withTransaction(async r=>{let s=await l(r);for(let l of(await s.createGroup({id:t,name:e.name,description:e.description??"",created_by:e.createdBy??e.identity.id,hlc:o.serialize(this.#t.now())}),await this.#i.seed({groupID:t,handle:i,stores:r}),await s.addGroupMember({group_id:t,member_did:e.identity.id,role:"admin",hlc:o.serialize(this.#t.now())}),a)){let e=await n({stores:r,url:l.url,serverDID:l.serverDID??null});await c({stores:r,hubID:e.id,groupID:t})}}),{groupID:t}}async updateGroup(e){let r=o.serialize(this.#t.now()),t=await l(e.stores);return await t.updateGroup(e.groupID,{name:e.update.name,description:e.update.description,hlc:r}),{broadcast:{type:"group:update",groupID:e.groupID,update:{...e.update,hlc:r}}}}async inviteToGroup(r){let i=await this.#i.withHandleReplacing(r.groupID,async i=>{let{invite:a}=await t({group:i,identity:r.identity,recipientDID:r.recipientDID,permission:r.permission}),{commitMessage:o,welcomeMessage:s,newGroup:l}=await e(i,r.recipientKeyPackage);return{result:{invite:a,commitMessage:o,welcomeMessage:s,ratchetTree:l.state.ratchetTree},updated:l}},{stores:r.stores}),a=await l(r.stores);return await a.addGroupMember({group_id:r.groupID,member_did:r.recipientDID,role:"admin"===r.permission?"admin":"member",hlc:o.serialize(this.#t.now())}),i}async joinGroup(e){let{group:r}=await i({identity:e.identity,invite:e.invite,welcome:e.welcomeMessage,keyPackageBundle:e.keyPackageBundle,ratchetTree:e.ratchetTree}),t=e.hubs??[];await e.stores.withTransaction(async i=>{await this.#i.seed({groupID:e.groupID,handle:r,stores:i});let a=await l(i);for(let r of(null==await a.getGroup(e.groupID)&&await a.createGroup({id:e.groupID,name:e.groupName,description:"",created_by:e.identity.id,hlc:o.serialize(this.#t.now())}),await a.addGroupMember({group_id:e.groupID,member_did:e.identity.id,role:"member",hlc:o.serialize(this.#t.now())}),t)){let t=await n({stores:i,url:r.url,serverDID:r.serverDID??null});await c({stores:i,hubID:t.id,groupID:e.groupID})}})}async removeMember(e){let{commitMessage:r}=await this.#i.withHandleReplacing(e.groupID,async r=>{let{commitMessage:t,newGroup:i}=await a(r,e.leafIndex);return{result:{commitMessage:t},updated:i}},{stores:e.stores}),t=await l(e.stores);return await t.removeGroupMember(e.groupID,e.memberDID,o.serialize(this.#t.now())),{commitMessage:r}}async removeGroupMember(e){let{commitMessage:r}=await this.#i.withHandleReplacing(e.groupID,async r=>{let t=r.findMemberLeafIndex(e.memberDID);if(null==t)throw Error(`Member ${e.memberDID} not found in MLS group`);let{commitMessage:i,newGroup:o}=await a(r,t);return{result:{commitMessage:i},updated:o}},{stores:e.stores}),t=await l(e.stores);return await t.removeGroupMember(e.groupID,e.memberDID,o.serialize(this.#t.now())),{commitMessage:r}}async leaveGroup(e){let r=await l(e.stores);await r.deleteMLSState(e.groupID,this.#e),await r.removeGroupMember(e.groupID,e.identity.id,o.serialize(this.#t.now())),e.stores.onCommit(()=>this.#i.invalidate(e.groupID))}async loadGroup(e,r){let t=await l(e),i=await t.getMLSState(r,this.#e);if(null!=i)return{epoch:i.epoch,credential:i.credential}}async createCircle(e){let r=this.#r(),t=o.serialize(this.#t.now()),i=e.catalogIDs??[],a=await l(e.stores);return await a.createCircle({id:r,group_id:e.groupID,name:e.name,description:e.description??"",catalog_ids:i,hlc:t}),{circleID:r,broadcast:{type:"circle:create",circle:{id:r,groupID:e.groupID,name:e.name,description:e.description??"",catalogIDs:i,hlc:t}}}}async updateCircle(e){let r=o.serialize(this.#t.now()),t=[],i=await l(e.stores);if(null!=e.update.catalogIDs){let r=await i.getCircle(e.circleID),a=new Set(null!=r?r.catalog_ids:[]),o=e.update.catalogIDs.filter(e=>!a.has(e)),l=await s(e.stores);for(let e of(await Promise.all(o.map(e=>l.getCatalog(e)))))null!=e&&t.push({type:"catalog:create",catalog:{id:e.id,ownerDID:e.owner_did,name:e.name,description:e.description,filterCriteria:e.filter_criteria,hlc:e.hlc}})}await i.updateCircle(e.circleID,{name:e.update.name,description:e.update.description,catalog_ids:e.update.catalogIDs,hlc:r});let a={type:"circle:update",circleID:e.circleID,update:{...e.update,hlc:r}};return{broadcast:a,broadcasts:[a,...t]}}async deleteCircle(e){let r=o.serialize(this.#t.now()),t=await l(e.stores);return await t.deleteCircle(e.circleID),{broadcast:{type:"circle:delete",circleID:e.circleID,hlc:r}}}async addCircleMember(e){let r=await l(e.stores);if(!await r.isGroupMember(e.groupID,e.memberDID))throw Error(`${e.memberDID} is not a member of group ${e.groupID}`);let t=o.serialize(this.#t.now());return await r.addCircleMember({circle_id:e.circleID,member_did:e.memberDID,role:e.role,hlc:t}),{broadcast:{type:"member:add",member:{circleID:e.circleID,memberDID:e.memberDID,role:e.role,hlc:t}}}}async removeCircleMember(e){let r=o.serialize(this.#t.now()),t=await l(e.stores);return await t.removeCircleMember(e.circleID,e.memberDID),{broadcast:{type:"member:remove",circleID:e.circleID,memberDID:e.memberDID,hlc:r}}}}

package/lib/groups/mls-codec.d.ts

@@ -0,0 +1,7 @@
+import type { GroupHandle } from '@enkaku/group';
+export type MLSEncryptFramedResult = {
+    framed: Uint8Array;
+    consumed: Array<Uint8Array>;
+};
+export declare function mlsEncryptFramed(handle: GroupHandle, plaintext: Uint8Array): Promise<MLSEncryptFramedResult>;
+export declare function mlsDecryptFramed(handle: GroupHandle, framed: Uint8Array): Promise<Uint8Array>;

package/lib/groups/mls-codec.js

@@ -0,0 +1 @@
+import{replacer as e,reviver as r}from"./mls-json.js";let t=new TextEncoder,n=new TextDecoder;export async function mlsEncryptFramed(r,n){let{message:c,consumed:o}=await r.encrypt(n);return{framed:t.encode(JSON.stringify(c,e)),consumed:o}}export async function mlsDecryptFramed(e,t){let c=JSON.parse(n.decode(t),r);return await e.decrypt(c)}

package/lib/groups/mls-encryptor.d.ts

@@ -0,0 +1,25 @@
+import type { Encryptor } from '@enkaku/hub-tunnel';
+import type { GroupHandleRegistry } from './group-handle-registry.js';
+export type MLSEncryptorParams = {
+    registry: GroupHandleRegistry;
+    groupID: string;
+};
+/**
+ * Adapts the `GroupHandleRegistry` to the `@enkaku/hub-tunnel` `Encryptor`
+ * interface. The registry's per-group mutex serializes encrypt + decrypt
+ * across all encryptor instances bound to the same `(registry, groupID)`.
+ *
+ * Wedge-protection note: encrypt persists the advanced ratchet immediately
+ * on callback success — BEFORE the wire send happens inside the hub-tunnel
+ * transport. If the wire send fails, the persisted state is already at
+ * generation N+1; the next encrypt advances to N+2 and generation N is
+ * "burned" without wire egress. This is the documented forward-secrecy
+ * trade-off for tunnel sessions; the broadcast path (`BroadcastService.
+ * prepareSend`) inverts the order by pulling send into the registry callback.
+ */
+export declare class MLSEncryptor implements Encryptor {
+    #private;
+    constructor(params: MLSEncryptorParams);
+    encrypt(plaintext: Uint8Array): Promise<Uint8Array>;
+    decrypt(ciphertext: Uint8Array): Promise<Uint8Array>;
+}

package/lib/groups/mls-encryptor.js

@@ -0,0 +1 @@
+import{mlsDecryptFramed as r,mlsEncryptFramed as t}from"./mls-codec.js";export class MLSEncryptor{#r;#t;constructor(r){this.#r=r.registry,this.#t=r.groupID}encrypt(r){return this.#r.withHandle(this.#t,async s=>{let{framed:e}=await t(s,r);return e})}decrypt(t){return this.#r.withHandle(this.#t,s=>r(s,t))}}

package/lib/groups/store-received-grant.d.ts

@@ -0,0 +1,47 @@
+import type { Logger } from '@kubun/logger';
+import type { P2PStoreAPI } from '@kubun/store-p2p';
+import type { P2PEventEmitter } from './events.js';
+export type StoreReceivedGrantParams = {
+    /** P2P store the held row is written to. */
+    p2pStore: P2PStoreAPI;
+    /** Stringified capability JWT carrying the `document/write` grant. */
+    token: string;
+    /** Group the grant belongs to. */
+    groupID: string;
+    /**
+     * HLC stamped on the held row. For broadcast-delivered grants this mirrors
+     * the grantor-side issued row; for invite-delivered grants the joiner stamps
+     * its own HLC at apply time (no grantor HLC travels in the invite).
+     */
+    hlc: string;
+    /**
+     * DID of the receiving device. The grant is only stored when the token's
+     * audience (`aud`) matches this DID — co-members relay the same grant but
+     * ignore tokens addressed to someone else.
+     */
+    selfDID: string;
+    /**
+     * Optional emitter notified after a held row is successfully written.
+     * Consumers (e.g. the `ownDelegationTokenAdded` subscription) use this to
+     * surface freshly-arrived tokens to local subscribers.
+     */
+    emitter?: P2PEventEmitter;
+    /** Optional logger — warns on verification failure or missing claims. */
+    logger?: Logger;
+};
+/**
+ * Verify a received capability grant and, when it is addressed to this device,
+ * store it as a held row so the engine's auto-attach can reuse it on later
+ * mutations.
+ *
+ * Returns `true` when the held row was inserted or materially changed (LWW
+ * upsert with a newer hlc and at least one differing content field). Returns
+ * `false` when no row change occurred — verification failure, audience
+ * mismatch, missing required claims, LWW lost against an existing row, or an
+ * idempotent re-broadcast with identical content. Never throws on a forged or
+ * malformed token — it is skipped like an unverifiable broadcast entry.
+ *
+ * Shared by the `delegation:share` broadcast path and the invite-bootstrap
+ * path so both apply identical verify + audience + null-guard + coercion logic.
+ */
+export declare function storeReceivedGrant(params: StoreReceivedGrantParams): Promise<boolean>;

package/lib/groups/store-received-grant.js

@@ -0,0 +1 @@
+import{verifyToken as e}from"@enkaku/token";export async function storeReceivedGrant(i){let t,{p2pStore:a,token:n,groupID:r,hlc:o,selfDID:d,emitter:p,logger:s}=i;try{t=(await e(n)).payload}catch(e){return s?.warn("received grant token verification failed, skipping",{groupID:r,error:e}),!1}if(t.aud!==d)return!1;if(null==t.jti||null==t.exp)return s?.warn("received grant token missing jti/exp, skipping",{groupID:r}),!1;let u="string"==typeof t.res?t.res:JSON.stringify(t.res),c="string"==typeof t.act?t.act:JSON.stringify(t.act),g=await a.addDelegationToken({jti:t.jti,grantor:t.sub,audience:t.aud,token:n,resource:u,act:c,exp:t.exp,group_id:r,hlc:o});if(g){let e=await a.getPendingRevocationByJti(t.jti);if(null!=e)if(e.revoker_did===t.sub){let i=Math.floor(Date.now()/1e3);await a.markRevocationVerified(t.jti,{cap_exp:t.exp,verified_at:i})&&null!=p&&await p.emit("delegationTokenRevoked",{jti:t.jti,grantor:t.sub,audience:t.aud,revokerDID:e.revoker_did,revokedAt:e.revoked_iat,verifiedAt:i,capExp:t.exp,groupID:r})}else s?.warn("pending revocation iss does not match arriving cap, dropping",{jti:t.jti,pendingIss:e.revoker_did,capGrantor:t.sub,groupID:r}),await a.deletePendingRevocation(t.jti)}return g&&null!=p&&await p.emit("delegationTokenAdded",{jwt:n,jti:t.jti,grantor:t.sub,audience:t.aud,resource:u,exp:t.exp}),g}

package/lib/groups/store-received-revocation.d.ts

@@ -0,0 +1,46 @@
+import type { Logger } from '@kubun/logger';
+import type { P2PStoreAPI } from '@kubun/store-p2p';
+import type { P2PEventEmitter } from './events.js';
+export type StoreReceivedRevocationParams = {
+    /** P2P store the revocation row is written to. */
+    p2pStore: P2PStoreAPI;
+    /** Stringified signed revocation JWT carrying `{ jti, iss, rev, iat }`. */
+    token: string;
+    /** Group the revocation belongs to. */
+    groupID: string;
+    /** HLC stamped on the revocation row for LWW arbitration. */
+    hlc: string;
+    /**
+     * DID of the receiving device. Currently unused — revocations are
+     * audience-agnostic at store time — but accepted for symmetry with
+     * `storeReceivedGrant` and to keep call sites uniform.
+     */
+    selfDID?: string;
+    /**
+     * Optional emitter passed through for symmetry with `storeReceivedGrant`.
+     * This helper does not emit; downstream subscription wiring lives elsewhere.
+     */
+    emitter?: P2PEventEmitter;
+    /** Optional logger — debug on verification failure or malformed payload, warn on iss/grantor mismatch. */
+    logger?: Logger;
+};
+/**
+ * Verify a received revocation token and write its row to the P2P store.
+ *
+ * Verified-on-arrival: when the referenced capability is already known
+ * locally and the revocation's `iss` matches that capability's `grantor`,
+ * the row is stored with `verified_at` populated so the hot-path
+ * `isRevoked` gate fires immediately. When the capability is unknown
+ * locally, the row is stored as pending (`verified_at` null) until a later
+ * `delegation:share` triggers a cross-check that flips it via
+ * `markRevocationVerified`. A signature-verified token whose `iss` does
+ * not match a known capability's `grantor` is rejected outright — a forged
+ * revocation must not pollute the local store.
+ *
+ * Returns `true` when the row was inserted or materially changed (LWW
+ * upsert). Returns `false` on verification failure, non-revocation
+ * payload, iss/grantor mismatch, or a lost/idempotent LWW upsert. Never
+ * throws on a forged or malformed token — it is skipped like an
+ * unverifiable broadcast entry.
+ */
+export declare function storeReceivedRevocation(params: StoreReceivedRevocationParams): Promise<boolean>;

package/lib/groups/store-received-revocation.js

@@ -0,0 +1 @@
+import{verifyToken as e}from"@enkaku/token";export async function storeReceivedRevocation(o){let r,{p2pStore:t,token:n,groupID:i,hlc:a,emitter:c,logger:d}=o;try{r=(await e(n)).payload}catch(e){return d?.debug("received revocation token verification failed, skipping",{groupID:i,error:e}),!1}if(!0!==r.rev)return d?.debug("received revocation token is not a revocation record, skipping",{groupID:i}),!1;let{jti:l,iss:v,iat:k}=r,u=await t.getDelegationTokenByJti(l),g=null,p=null;if(null!=u){if(u.grantor!==v)return d?.warn("received revocation iss does not match known capability grantor, skipping",{groupID:i,jti:l,iss:v,grantor:u.grantor}),!1;g=Math.floor(Date.now()/1e3),p=u.exp}let f=await t.addRevocation({jti:l,revoker_did:v,revoked_iat:k,revocation_token:n,verified_at:g,cap_exp:p,group_id:i,hlc:a});return f&&null!=g&&null!=u&&null!=c&&await c.emit("delegationTokenRevoked",{jti:l,grantor:u.grantor,audience:u.audience,revokerDID:v,revokedAt:k,verifiedAt:g,capExp:p,groupID:i}),f}

package/lib/groups/wire-frame.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Outer wire-frame discriminator for group hub payloads.
+ *
+ * The hub relay treats a group send payload as opaque bytes. Kubun prepends a
+ * single `kind` byte so the receiver can route a payload to the right decoder
+ * without trial-decryption:
+ *
+ * - `app` — an MLS-encrypted application broadcast (`GroupBroadcastMessage`),
+ *   decoded via `handle.decrypt` + `deserializeBroadcast`.
+ * - `mls` — a framed MLS handshake message (a Commit), fed straight to
+ *   `handle.processMessage`. The handshake is self-protected (encrypted
+ *   `PrivateMessage`), so it is NOT wrapped in the application-encryption path.
+ *
+ * The discriminator lives entirely in kubun's payload bytes; the hub protocol
+ * is unchanged.
+ */
+export declare const WireKind: {
+    readonly app: 0;
+    readonly mls: 1;
+};
+export type WireKind = (typeof WireKind)[keyof typeof WireKind];
+/** Prepend the `kind` byte to a payload. */
+export declare function frameWire(kind: WireKind, payload: Uint8Array): Uint8Array;
+/**
+ * Split a framed payload into its `kind` and the remaining payload bytes.
+ * Throws on an empty frame or an unrecognized `kind` byte. The returned
+ * payload is a view (`subarray`) over the input, not a copy.
+ */
+export declare function unframeWire(framed: Uint8Array): {
+    kind: WireKind;
+    payload: Uint8Array;
+};

package/lib/groups/wire-frame.js

@@ -0,0 +1 @@
+export const WireKind={app:0,mls:1};export function frameWire(r,e){let n=new Uint8Array(e.length+1);return n[0]=r,n.set(e,1),n}export function unframeWire(r){if(0===r.length)throw Error("empty wire frame");let e=r[0];if(e!==WireKind.app&&e!==WireKind.mls)throw Error(`unknown wire frame kind: ${e}`);return{kind:e,payload:r.subarray(1)}}

package/lib/hub/connection-pool.d.ts

@@ -6,9 +6,33 @@ export type HubClientRef = {
     client: Client<HubProtocol>;
     refID: string;
 };
+/**
+ * Fired once per freshly-spawned hub client when its first signed response
+ * arrives. The pool binds the hub URL into the call site; consumers (hub
+ * manager `captureServerDID`) use the URL to look up the local hub row and
+ * apply the conflict matrix. Errors are caught and logged — capture never
+ * blocks message forwarding, even on `HubServerDIDConflictError`.
+ */
+export type OnServerDIDObserved = (params: {
+    hubURL: string;
+    serverDID: string;
+}) => void | Promise<void>;
+/**
+ * Resolves the locally-pinned `server_did` for a hub URL at spawn time. When
+ * the hub row for this URL exists and has `server_did` set, the pool passes
+ * it as `expectedServerDID` to the client factory so the wrapper enforces
+ * the pin. Returning `null` falls back to TOFU.
+ *
+ * Resolution happens fresh on every spawn so `updateHub({ serverDID: null })`
+ * re-arms TOFU automatically: the next disposed/evicted client triggers a
+ * fresh resolve.
+ */
+export type ResolvePinnedServerDID = (hubURL: string) => Promise<string | null>;
 export type HubConnectionPoolParams = {
     createHubClient: CreateHubClient;
     logger?: Logger;
+    onServerDIDObserved?: OnServerDIDObserved;
+    resolvePinnedDID?: ResolvePinnedServerDID;
 };
 export declare class HubConnectionPool {
     #private;

package/lib/hub/connection-pool.js

@@ -1 +1 @@
-export class HubConnectionPool{#e;#t;#i=new Map;#s=0;constructor(e){this.#e=e.createHubClient,this.#t=e.logger}async acquire(e){let t=this.#i.get(e);if(null!=t&&null!=t.disposing&&(await t.disposing,this.#i.get(e)===t&&this.#i.delete(e),t=void 0),null==t){let i=await this.#e(e),s={client:i,refs:new Set};t=s,this.#i.set(e,s),i.disposed.then(()=>{this.#i.get(e)===s&&(this.#t?.debug("hub client disposed externally, evicting pool entry",{hubURL:e,outstandingRefs:[...s.refs]}),this.#i.delete(e))}).catch(()=>{})}let i=String(++this.#s);return t.refs.add(i),{client:t.client,refID:i}}async release(e,t){let i=this.#i.get(e);if(null==i)return void this.#t?.debug("HubConnectionPool.release: unknown hubURL",{hubURL:e,refID:t});if(!i.refs.has(t))return void this.#t?.debug("HubConnectionPool.release: unknown refID",{hubURL:e,refID:t});if(i.refs.delete(t),i.refs.size>0)return;let s=i.client.dispose();i.disposing=s;try{await s}finally{this.#i.get(e)===i&&this.#i.delete(e)}}async disposeAll(){let e=Array.from(this.#i.entries());await Promise.all(e.map(async([e,t])=>{t.refs.size>0&&this.#t?.warn("Disposing hub client with outstanding refs",{hubURL:e,refs:Array.from(t.refs)}),await t.client.dispose()})),this.#i.clear()}}
+export class HubConnectionPool{#e;#t;#i;#r;#s=new Map;#n=0;constructor(e){this.#e=e.createHubClient,this.#t=e.logger,this.#i=e.onServerDIDObserved,this.#r=e.resolvePinnedDID}async acquire(e){let t=this.#s.get(e);if(null!=t&&null!=t.disposing&&(await t.disposing,this.#s.get(e)===t&&this.#s.delete(e),t=void 0),null==t){let i,r=this.#i;if(null!=this.#r)try{let t=await this.#r(e);null!=t&&(i=t)}catch(t){this.#t?.warn("failed to resolve pinned server DID, falling back to TOFU",{hubURL:e,error:t})}let s=await this.#e(e,{onServerDID:null==r?void 0:async t=>{try{await r({hubURL:e,serverDID:t})}catch(i){this.#t?.warn("hub server DID capture failed",{hubURL:e,serverDID:t,error:i})}},expectedServerDID:i,onMismatch:null==i?void 0:e=>{this.#t?.warn("hub server DID mismatch — pinning enforcement triggered",{hubURL:e.hubURL,expectedServerDID:e.expectedServerDID,observedServerDID:e.observedServerDID})}}),n={client:s,refs:new Set};t=n,this.#s.set(e,n),s.disposed.then(()=>{this.#s.get(e)===n&&(this.#t?.debug("hub client disposed externally, evicting pool entry",{hubURL:e,outstandingRefs:[...n.refs]}),this.#s.delete(e))}).catch(()=>{})}let i=String(++this.#n);return t.refs.add(i),{client:t.client,refID:i}}async release(e,t){let i=this.#s.get(e);if(null==i)return void this.#t?.debug("HubConnectionPool.release: unknown hubURL",{hubURL:e,refID:t});if(!i.refs.has(t))return void this.#t?.debug("HubConnectionPool.release: unknown refID",{hubURL:e,refID:t});if(i.refs.delete(t),i.refs.size>0)return;let r=i.client.dispose();i.disposing=r;try{await r}finally{this.#s.get(e)===i&&this.#s.delete(e)}}async disposeAll(){let e=Array.from(this.#s.entries());await Promise.all(e.map(async([e,t])=>{t.refs.size>0&&this.#t?.warn("Disposing hub client with outstanding refs",{hubURL:e,refs:Array.from(t.refs)}),await t.client.dispose()})),this.#s.clear()}}