@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/groups/manager.js

@@ -1 +1,281 @@
-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}}}}
+import { normalizeDID } from '@kokuin/token';
+import { HLC } from '@kubun/hlc';
+import { getP2PStore } from '@kubun/store-p2p';
+import { commitInvite, createGroup, createInvite, processWelcome, removeMember } from '@kumiai/mls';
+import { toB64 } from '@sozai/codec';
+import { bindHubToGroup, upsertHub } from '../hub/manager.js';
+import { reprojectAdminRoster } from './admin-roster.js';
+import { reprojectGroupSettings } from './circle-projection.js';
+import { GROUP_SETTINGS_ENTRY_TYPE } from './circle-reducers.js';
+import { buildCurrentGroupAnchorExtension, groupAnchorCapabilities, readGroupAnchor } from './group-anchor.js';
+import { ledgerEntryDigest, signLedgerEntry } from './ledger-entry.js';
+export class GroupManager {
+    #deviceID;
+    #getRandomID;
+    #hlc;
+    #registry;
+    constructor(params){
+        this.#deviceID = params.identity.id;
+        this.#getRandomID = params.getRandomID;
+        this.#hlc = params.hlc;
+        this.#registry = params.registry;
+    }
+    async createGroup(params) {
+        const groupID = this.#getRandomID();
+        // The creator DID is baked into the MLS GroupContext as the immutable
+        // genesis anchor, alongside a fresh 32-byte recovery seed. Both survive
+        // every epoch and are authenticated by the GroupInfo signature, so every
+        // member derives the same recovery rendezvous. Every member leaf advertises
+        // the anchor extension capability so the group can be invited to.
+        const recoverySecret = toB64(crypto.getRandomValues(new Uint8Array(32)));
+        const { group } = await createGroup(params.identity, groupID, {
+            extensions: [
+                buildCurrentGroupAnchorExtension(normalizeDID(params.identity.id), recoverySecret)
+            ],
+            capabilities: groupAnchorCapabilities()
+        });
+        // Atomic register + bind: each `hubs` entry is upserted via `upsertHub`
+        // and bound to the group inside one transaction. A
+        // HubServerDIDConflictError on any entry rolls back the group row, the
+        // MLS state, the membership row, and any earlier hub bindings that were
+        // already added in this transaction.
+        const hubs = params.hubs ?? [];
+        await params.stores.withTransaction(async (tx)=>{
+            const store = await getP2PStore(tx);
+            await store.createGroup({
+                id: groupID,
+                name: params.name,
+                description: params.description ?? '',
+                created_by: params.createdBy ?? params.identity.id,
+                hlc: HLC.serialize(this.#hlc.now())
+            });
+            await this.#registry.seed({
+                groupID,
+                handle: group,
+                stores: tx
+            });
+            // The membership row must exist before projection (setGroupMemberRole is
+            // update-only); the role value here is irrelevant — projecting the genesis
+            // anchor below overwrites it. The ledger fold is the only writer of role.
+            await store.addGroupMember({
+                group_id: groupID,
+                member_did: params.identity.id,
+                role: 'member',
+                hlc: HLC.serialize(this.#hlc.now())
+            });
+            // Derive the creator's admin role from the genesis anchor: folding the
+            // (empty) ledger to its seed {creator} projects the creator to 'admin'.
+            const anchor = readGroupAnchor(group);
+            if (anchor != null) {
+                await reprojectAdminRoster({
+                    store,
+                    groupID,
+                    anchor
+                });
+            }
+            // Seed the group name/description into the ledger: the direct
+            // `store.createGroup` row write does not propagate, so the ledger is the
+            // only channel that carries settings to joiners and survives a reproject.
+            // No broadcast at creation (no co-members yet) — the entry rides catch-up
+            // when peers join. Reprojecting from the seed yields the same name/desc the
+            // group row already holds and sets the settings watermark.
+            const settingsHLC = HLC.serialize(this.#hlc.now());
+            const settingsValue = {
+                name: params.name,
+                description: params.description ?? ''
+            };
+            const settingsToken = await signLedgerEntry(params.identity, {
+                type: GROUP_SETTINGS_ENTRY_TYPE,
+                subject: groupID,
+                value: settingsValue,
+                hlc: settingsHLC
+            });
+            await store.appendLedgerEntry({
+                group_id: groupID,
+                entry_id: ledgerEntryDigest(settingsToken),
+                type: GROUP_SETTINGS_ENTRY_TYPE,
+                subject: groupID,
+                value: settingsValue,
+                hlc: settingsHLC,
+                issuer_did: params.identity.id,
+                signed_token: settingsToken
+            });
+            if (anchor != null) {
+                await reprojectGroupSettings({
+                    store,
+                    groupID,
+                    anchor
+                });
+            }
+            for (const hub of hubs){
+                const upserted = await upsertHub({
+                    stores: tx,
+                    url: hub.url,
+                    serverDID: hub.serverDID ?? null
+                });
+                await bindHubToGroup({
+                    stores: tx,
+                    hubID: upserted.id,
+                    groupID
+                });
+            }
+        });
+        return {
+            groupID
+        };
+    }
+    async inviteToGroup(params) {
+        const opResult = await this.#registry.withHandleReplacing(params.groupID, async (handle)=>{
+            const { invite } = await createInvite({
+                group: handle,
+                identity: params.identity,
+                recipientDID: params.recipientDID,
+                permission: params.permission
+            });
+            const { commitMessage, welcomeMessage, newGroup } = await commitInvite(handle, params.recipientKeyPackage);
+            return {
+                result: {
+                    invite,
+                    commitMessage,
+                    welcomeMessage,
+                    ratchetTree: newGroup.state.ratchetTree
+                },
+                updated: newGroup
+            };
+        }, {
+            stores: params.stores
+        });
+        const store = await getP2PStore(params.stores);
+        await store.addGroupMember({
+            group_id: params.groupID,
+            member_did: params.recipientDID,
+            role: params.permission === 'admin' ? 'admin' : 'member',
+            hlc: HLC.serialize(this.#hlc.now())
+        });
+        return opResult;
+    }
+    async joinGroup(params) {
+        // Process the welcome message using the invitee's key package bundle
+        const { group } = await processWelcome({
+            identity: params.identity,
+            invite: params.invite,
+            welcome: params.welcomeMessage,
+            keyPackageBundle: params.keyPackageBundle,
+            ratchetTree: params.ratchetTree
+        });
+        // Atomic register + bind: hub entries imported from the invite are
+        // upserted and bound to the group inside one transaction. A
+        // HubServerDIDConflictError on any entry rolls back MLS state, the
+        // (provisional) group row, the membership row, and any earlier hub
+        // bindings.
+        const hubs = params.hubs ?? [];
+        await params.stores.withTransaction(async (tx)=>{
+            await this.#registry.seed({
+                groupID: params.groupID,
+                handle: group,
+                stores: tx
+            });
+            // Provision the local Group row if it does not already exist. Required
+            // so downstream group-aware components (e.g. HubRelayManager) can read
+            // group metadata from the joining peer's DB.
+            const store = await getP2PStore(tx);
+            const existing = await store.getGroup(params.groupID);
+            if (existing == null) {
+                await store.createGroup({
+                    id: params.groupID,
+                    name: params.groupName,
+                    description: '',
+                    created_by: params.identity.id,
+                    hlc: HLC.serialize(this.#hlc.now())
+                });
+            }
+            // Seed the full MLS roster (the store roster is the projection of the
+            // ratchet tree) so the admin gate can confirm membership of the
+            // creator/existing admins on this peer. Roles default to 'member';
+            // admin authority is derived from the ledger fold and the role column is
+            // corrected when ledger entries arrive.
+            const localHLC = HLC.serialize(this.#hlc.now());
+            await store.addGroupMembers(group.listMembers().map((member)=>({
+                    group_id: params.groupID,
+                    member_did: member.id,
+                    role: 'member',
+                    hlc: localHLC
+                })));
+            for (const hub of hubs){
+                const upserted = await upsertHub({
+                    stores: tx,
+                    url: hub.url,
+                    serverDID: hub.serverDID ?? null
+                });
+                await bindHubToGroup({
+                    stores: tx,
+                    hubID: upserted.id,
+                    groupID: params.groupID
+                });
+            }
+        });
+        return undefined;
+    }
+    async removeMember(params) {
+        const { commitMessage } = await this.#registry.withHandleReplacing(params.groupID, async (handle)=>{
+            const { commitMessage, newGroup } = await removeMember(handle, params.leafIndex);
+            return {
+                result: {
+                    commitMessage
+                },
+                updated: newGroup
+            };
+        }, {
+            stores: params.stores
+        });
+        const store = await getP2PStore(params.stores);
+        await store.removeGroupMember(params.groupID, params.memberDID, HLC.serialize(this.#hlc.now()));
+        return {
+            commitMessage
+        };
+    }
+    async removeGroupMember(params) {
+        const { commitMessage } = await this.#registry.withHandleReplacing(params.groupID, async (handle)=>{
+            const leafIndex = handle.findMemberLeafIndex(params.memberDID);
+            if (leafIndex == null) {
+                throw new Error(`Member ${params.memberDID} not found in MLS group`);
+            }
+            const { commitMessage, newGroup } = await removeMember(handle, leafIndex);
+            return {
+                result: {
+                    commitMessage
+                },
+                updated: newGroup
+            };
+        }, {
+            stores: params.stores
+        });
+        const store = await getP2PStore(params.stores);
+        await store.removeGroupMember(params.groupID, params.memberDID, params.hlc);
+        return {
+            commitMessage
+        };
+    }
+    async leaveGroup(params) {
+        // MLS does not allow a member to commit their own removal.
+        // leaveGroup performs local cleanup: deletes MLS state and group membership.
+        // The actual MLS group removal happens when another member calls removeGroupMember.
+        const store = await getP2PStore(params.stores);
+        await store.deleteMLSState(params.groupID, this.#deviceID);
+        await store.removeGroupMember(params.groupID, params.identity.id, params.hlc);
+        // Defer cache eviction to onCommit so a future caller wrapping these
+        // deletes in withTransaction does not invalidate the cache when the row
+        // delete rolls back. KubunDB's non-tx onCommit fires synchronously, so
+        // current callers see invalidate immediately.
+        params.stores.onCommit(()=>this.#registry.invalidate(params.groupID));
+    }
+    async loadGroup(stores, groupID) {
+        const store = await getP2PStore(stores);
+        const state = await store.getMLSState(groupID, this.#deviceID);
+        if (state == null) return undefined;
+        return {
+            epoch: state.epoch,
+            credential: state.credential
+        };
+    }
+}

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

@@ -1,4 +1,4 @@
-import type { GroupHandle } from '@enkaku/group';
+import type { GroupHandle } from '@kumiai/mls';
 export type MLSEncryptFramedResult = {
     framed: Uint8Array;
     consumed: Array<Uint8Array>;

package/lib/groups/mls-codec.js

@@ -1 +1,18 @@
-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)}
+import { anchorImmutabilityPolicy } from './group-anchor.js';
+import { replacer, reviver } from './mls-json.js';
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+export async function mlsEncryptFramed(handle, plaintext) {
+    const { message, consumed } = await handle.encrypt(plaintext);
+    const framed = textEncoder.encode(JSON.stringify(message, replacer));
+    return {
+        framed,
+        consumed
+    };
+}
+export async function mlsDecryptFramed(handle, framed) {
+    const message = JSON.parse(textDecoder.decode(framed), reviver);
+    return await handle.decrypt(message, {
+        commitPolicy: anchorImmutabilityPolicy
+    });
+}

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

@@ -1,11 +1,11 @@
-import type { Encryptor } from '@enkaku/hub-tunnel';
+import type { Encryptor } from '@kumiai/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`
+ * Adapts the `GroupHandleRegistry` to the `@kumiai/hub-tunnel` `Encryptor`
  * interface. The registry's per-group mutex serializes encrypt + decrypt
  * across all encryptor instances bound to the same `(registry, groupID)`.
  *

package/lib/groups/mls-encryptor.js

@@ -1 +1,30 @@
-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))}}
+import { mlsDecryptFramed, mlsEncryptFramed } from './mls-codec.js';
+/**
+ * Adapts the `GroupHandleRegistry` to the `@kumiai/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 class MLSEncryptor {
+    #registry;
+    #groupID;
+    constructor(params){
+        this.#registry = params.registry;
+        this.#groupID = params.groupID;
+    }
+    encrypt(plaintext) {
+        return this.#registry.withHandle(this.#groupID, async (handle)=>{
+            const { framed } = await mlsEncryptFramed(handle, plaintext);
+            return framed;
+        });
+    }
+    decrypt(ciphertext) {
+        return this.#registry.withHandle(this.#groupID, (handle)=>mlsDecryptFramed(handle, ciphertext));
+    }
+}

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

@@ -1,4 +1,4 @@
-import { type GroupHandle } from '@enkaku/group';
+import { type GroupHandle } from '@kumiai/mls';
 import { type SerializedMLSGroupState } from './mls-state.js';
 export type MLSGroupHandle = GroupHandle;
 export declare function restoreMLSGroupHandle(serialized: SerializedMLSGroupState): Promise<MLSGroupHandle>;

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

@@ -1 +1,10 @@
-import{restoreGroup as r}from"@enkaku/group";import{deserializeMLSGroupState as o}from"./mls-state.js";export async function restoreMLSGroupHandle(t){let{state:e,credential:n,rootCapability:m}=o(t);return r({state:e,credential:n,rootCapability:m})}
+import { restoreGroup } from '@kumiai/mls';
+import { deserializeMLSGroupState } from './mls-state.js';
+export async function restoreMLSGroupHandle(serialized) {
+    const { state, credential, rootCapability } = deserializeMLSGroupState(serialized);
+    return restoreGroup({
+        state,
+        credential,
+        rootCapability
+    });
+}

package/lib/groups/mls-json.js

@@ -1 +1,17 @@
-import{fromB64 as t,toB64 as e}from"@enkaku/codec";let r="\0bi:",i="\0u8:";export function replacer(t,n){if("bigint"==typeof n)return`${r}${n}`;let o=this[t];return o instanceof Uint8Array?`${i}${e(o)}`:n}export function reviver(e,n){return"string"!=typeof n?n:n.startsWith(r)?BigInt(n.slice(r.length)):n.startsWith(i)?t(n.slice(i.length)):n}
+import { fromB64, toB64 } from '@sozai/codec';
+const BIGINT_PREFIX = '\x00bi:';
+const BYTES_PREFIX = '\x00u8:';
+export function replacer(_key, value) {
+    if (typeof value === 'bigint') return `${BIGINT_PREFIX}${value}`;
+    const raw = this[_key];
+    if (raw instanceof Uint8Array) {
+        return `${BYTES_PREFIX}${toB64(raw)}`;
+    }
+    return value;
+}
+export function reviver(_key, value) {
+    if (typeof value !== 'string') return value;
+    if (value.startsWith(BIGINT_PREFIX)) return BigInt(value.slice(BIGINT_PREFIX.length));
+    if (value.startsWith(BYTES_PREFIX)) return fromB64(value.slice(BYTES_PREFIX.length));
+    return value;
+}

package/lib/groups/mls-receive-errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Errors raised while applying a received MLS handshake Commit to the local
+ * group state. Kept in a standalone, transport-independent module so the
+ * `GroupMLS` adapter and any other surviving receive path can import them
+ * without depending on a specific transport implementation.
+ */
+/**
+ * Thrown when a received Commit fails the authenticated MLS check at the
+ * matching epoch (a corrupt or forged Commit). Unrecoverable: redelivery will
+ * not help, so callers should ack-and-skip rather than wedge the group's
+ * ordered receive stream.
+ */
+export declare class DecryptError extends Error {
+    #private;
+    constructor(message: string, cause: unknown);
+    get cause(): unknown;
+}
+/**
+ * Thrown when a received MLS Commit targets a future epoch the local handle has
+ * not reached yet (a gap in the in-order Commit stream). Callers should NOT ack
+ * — the hub redelivers in order, so the gap-filling Commit arrives first and
+ * this one applies on a later delivery.
+ */
+export declare class CommitOutOfOrderError extends Error {
+    #private;
+    constructor(messageEpoch: bigint, handleEpoch: bigint);
+    get messageEpoch(): bigint;
+    get handleEpoch(): bigint;
+}

package/lib/groups/mls-receive-errors.js

@@ -0,0 +1,42 @@
+/**
+ * Errors raised while applying a received MLS handshake Commit to the local
+ * group state. Kept in a standalone, transport-independent module so the
+ * `GroupMLS` adapter and any other surviving receive path can import them
+ * without depending on a specific transport implementation.
+ */ /**
+ * Thrown when a received Commit fails the authenticated MLS check at the
+ * matching epoch (a corrupt or forged Commit). Unrecoverable: redelivery will
+ * not help, so callers should ack-and-skip rather than wedge the group's
+ * ordered receive stream.
+ */ export class DecryptError extends Error {
+    #cause;
+    constructor(message, cause){
+        super(message);
+        this.name = 'DecryptError';
+        this.#cause = cause;
+    }
+    get cause() {
+        return this.#cause;
+    }
+}
+/**
+ * Thrown when a received MLS Commit targets a future epoch the local handle has
+ * not reached yet (a gap in the in-order Commit stream). Callers should NOT ack
+ * — the hub redelivers in order, so the gap-filling Commit arrives first and
+ * this one applies on a later delivery.
+ */ export class CommitOutOfOrderError extends Error {
+    #messageEpoch;
+    #handleEpoch;
+    constructor(messageEpoch, handleEpoch){
+        super(`MLS commit epoch ${messageEpoch} ahead of handle epoch ${handleEpoch}`);
+        this.name = 'CommitOutOfOrderError';
+        this.#messageEpoch = messageEpoch;
+        this.#handleEpoch = handleEpoch;
+    }
+    get messageEpoch() {
+        return this.#messageEpoch;
+    }
+    get handleEpoch() {
+        return this.#handleEpoch;
+    }
+}

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

@@ -1,5 +1,5 @@
-import { type ClientState, type GroupHandle, type MemberCredential } from '@enkaku/group';
 import type { GroupMLSState, InsertGroupMLSState } from '@kubun/store-p2p';
+import { type ClientState, type GroupHandle, type MemberCredential } from '@kumiai/mls';
 /**
  * Serialized form of a GroupHandle for DB persistence.
  * The MLS ClientState is opaque binary; the credential is JSON.

package/lib/groups/mls-state.js

@@ -1 +1,56 @@
-import{decodeClientState as t,encodeClientState as e}from"@enkaku/group";import{normalizeCredential as o}from"../context/types.js";export function serializeMLSGroupState(t){return{mlsState:e(t.state),credential:JSON.stringify(t.credential),epoch:Number(t.epoch),rootCapability:t.rootCapability}}export function deserializeMLSGroupState(e){let o=t(e.mlsState);if(null==o)throw Error("Could not decode ClientState");return{state:o,credential:JSON.parse(e.credential),rootCapability:e.rootCapability}}export function fromMLSStateRow(t){return{mlsState:t.mls_state,credential:o(t.credential),epoch:t.epoch,rootCapability:t.root_capability}}export function toMLSStateInsert(t,e,o){return{group_id:e,device_id:o,mls_state:t.mlsState,credential:t.credential,epoch:t.epoch,root_capability:t.rootCapability}}
+import { decodeClientState, encodeClientState } from '@kumiai/mls';
+import { normalizeCredential } from '../context/types.js';
+/**
+ * Serialize a GroupHandle's state for persistence.
+ * The implementer must verify the serialization approach works
+ * with the installed version of ts-mls.
+ */ export function serializeMLSGroupState(group) {
+    return {
+        mlsState: encodeClientState(group.state),
+        credential: JSON.stringify(group.credential),
+        epoch: Number(group.epoch),
+        rootCapability: group.rootCapability
+    };
+}
+/**
+ * Deserialize persisted state back into GroupHandle constructor params.
+ * Returns the params needed to reconstruct a GroupHandle.
+ */ export function deserializeMLSGroupState(serialized) {
+    const state = decodeClientState(serialized.mlsState);
+    if (state == null) {
+        throw new Error('Could not decode ClientState');
+    }
+    return {
+        state,
+        credential: JSON.parse(serialized.credential),
+        rootCapability: serialized.rootCapability
+    };
+}
+/**
+ * Map a persisted `GroupMLSState` DB row to the `SerializedMLSGroupState` shape
+ * expected by `BroadcastService.prepareSend` / `processReceived`.
+ *
+ * Credential is stored as TEXT but Kysely's `ParseJSONResultsPlugin` may have
+ * already parsed it into an object on read. `SerializedMLSGroupState.credential`
+ * is a JSON string, so re-stringify when needed.
+ */ export function fromMLSStateRow(row) {
+    return {
+        mlsState: row.mls_state,
+        credential: normalizeCredential(row.credential),
+        epoch: row.epoch,
+        rootCapability: row.root_capability
+    };
+}
+/**
+ * Map a `SerializedMLSGroupState` plus scope (group + device) to an
+ * `InsertGroupMLSState` row suitable for `P2PStoreAPI.saveMLSState`.
+ */ export function toMLSStateInsert(serialized, groupID, deviceID) {
+    return {
+        group_id: groupID,
+        device_id: deviceID,
+        mls_state: serialized.mlsState,
+        credential: serialized.credential,
+        epoch: serialized.epoch,
+        root_capability: serialized.rootCapability
+    };
+}

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

@@ -1,8 +1,11 @@
 import type { Logger } from '@kubun/logger';
+import type { DelegationStoreAPI } from '@kubun/store-delegation';
 import type { P2PStoreAPI } from '@kubun/store-p2p';
 import type { P2PEventEmitter } from './events.js';
 export type StoreReceivedGrantParams = {
-    /** P2P store the held row is written to. */
+    /** Delegation store the held token row and revocation cross-check are written to. */
+    delegationStore: DelegationStoreAPI;
+    /** P2P store the group-delegation edge (`jti` → group) is written to. */
     p2pStore: P2PStoreAPI;
     /** Stringified capability JWT carrying the `document/write` grant. */
     token: string;