@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/context/hub.js

@@ -1 +1,150 @@
-import{getP2PStore as e}from"@kubun/store-p2p";import{bindHubToGroup as t,createHub as r,deleteHub as s,getHub as a,listHubs as u,listHubsByGroup as i,unbindHubFromGroup as l,updateHub as n}from"../hub/manager.js";import{toISO as o}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 u({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 i({stores:p.stores,groupID:t}),s=r.find(t=>t.id===e)?.url??null,a=await l({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 i({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:o(e.created_at)}))}}}
+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
+            });
+            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,80 @@
-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 { createKeyPackageBundle } from '@kumiai/mls';
+import { groupAnchorCapabilities } from '../groups/group-anchor.js';
+import { decodeInvitePayload, encodeJoinRequest } from '../groups/invite-payload.js';
+import { 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: groupAnchorCapabilities()
+            });
+            deps.pendingJoinRequests.set(ctx.viewerDID, {
+                publicPackage: bundle.publicPackage,
+                privatePackage: bundle.privatePackage,
+                did: ownIdentity.id
+            });
+            const encoded = encodeJoinRequest({
+                did: ownIdentity.id,
+                publicPackage: bundle.publicPackage
+            });
+            return {
+                joinRequest: encoded
+            };
+        },
+        complete: async (invitePayloadStr)=>{
+            checkPeerAccess(ctx.viewerDID, deps.identity.id, deps.autoAcceptPeers);
+            const stored = deps.pendingJoinRequests.get(ctx.viewerDID);
+            if (stored == null) {
+                throw new Error('No pending join request found — call prepareJoinRequest first');
+            }
+            const ownIdentity = deps.identity;
+            const invite = decodeInvitePayload(invitePayloadStr);
+            const keyPackageBundle = {
+                publicPackage: stored.publicPackage,
+                privatePackage: stored.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
+            });
+            const result = await finalizeJoinedGroup({
+                stores: deps.stores,
+                emitter: deps.emitter,
+                invite
+            });
+            deps.pendingJoinRequests.delete(ctx.viewerDID);
+            return result;
+        }
+    };
+}

package/lib/context/sync.js

@@ -1 +1,19 @@
-export function createSyncContext(e,s){return{addPeer:e=>s.syncManager.addPeer({config:e,stores:s.stores}),removePeer:e=>s.syncManager.removePeer({peerDID:e,stores:s.stores}),listPeers:()=>s.syncManager.listPeers({stores:s.stores}),getStatus:e=>s.syncManager.getStatus({peerDID:e,stores:s.stores})}}
+export function createSyncContext(_ctx, deps) {
+    return {
+        addPeer: (config)=>deps.syncManager.addPeer({
+                config,
+                stores: deps.stores
+            }),
+        removePeer: (peerDID)=>deps.syncManager.removePeer({
+                peerDID,
+                stores: deps.stores
+            }),
+        listPeers: ()=>deps.syncManager.listPeers({
+                stores: deps.stores
+            }),
+        getStatus: (peerDID)=>deps.syncManager.getStatus({
+                peerDID,
+                stores: deps.stores
+            })
+    };
+}

package/lib/context/types.d.ts

@@ -1,15 +1,17 @@
-import type { KeyPackageBundle } from '@enkaku/group';
-import type { Runtime } from '@enkaku/runtime';
-import type { OwnIdentity } from '@enkaku/token';
+import type { OwnIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import type { Adapter } from '@kubun/db-adapter';
 import type { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
+import type { KeyPackageBundle } from '@kumiai/mls';
+import type { Runtime } from '@sozai/runtime';
 import type { GroupBroadcastMessage } from '../groups/broadcast.js';
 import type { P2PEventEmitter } from '../groups/events.js';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
 import type { GroupManager } from '../groups/manager.js';
 import type { SyncManager } from '../sync/sync-manager.js';
+import type { RejoinResult } from '../types.js';
 export type PendingJoinRequest = {
     publicPackage: KeyPackageBundle['publicPackage'];
     privatePackage: KeyPackageBundle['privatePackage'];
@@ -48,6 +50,13 @@ export type ContextDeps = {
      * runs after the mutation transaction commits.
      */
     scheduleSendCommit: (groupID: string, commitBytes: Uint8Array) => void;
+    /** Shared group-health monitor; source for the `groupHealth` query. */
+    monitor: GroupHealthMonitor;
+    /**
+     * Run stale-device recovery for a group. Wired to `HubWiring.rejoinGroup`;
+     * a no-op `recovery-failed` under `DISABLED_HUB`.
+     */
+    rejoinGroup: (groupID: string) => Promise<RejoinResult>;
     logger: Logger;
 };
 export declare function toISO(timestamp: unknown): string;

package/lib/context/types.js

@@ -1 +1,28 @@
-export function toISO(e){return"number"==typeof e?new Date(1e3*e).toISOString():e instanceof Date?e.toISOString():String(e)}export function normalizeCredential(e){return"string"==typeof e?e:JSON.stringify(e)}export function checkPeerAccess(e,t,n){if(null!=n){if(!n.includes(e))throw Error("Peer not in autoAcceptPeers list")}else if(e!==t)throw Error("Only the engine identity can perform this operation")}
+export function toISO(timestamp) {
+    if (typeof timestamp === 'number') {
+        return new Date(timestamp * 1000).toISOString();
+    }
+    if (timestamp instanceof Date) {
+        return timestamp.toISOString();
+    }
+    return String(timestamp);
+}
+/**
+ * Normalize a credential value from the DB.
+ * Kysely's ParseJSONResultsPlugin may have already parsed the JSON string
+ * into an object. SerializedMLSGroupState expects a JSON string.
+ */ export function normalizeCredential(value) {
+    if (typeof value === 'string') return value;
+    return JSON.stringify(value);
+}
+export function checkPeerAccess(viewerDID, identityID, autoAcceptPeers) {
+    if (autoAcceptPeers != null) {
+        if (!autoAcceptPeers.includes(viewerDID)) {
+            throw new Error('Peer not in autoAcceptPeers list');
+        }
+    } else {
+        if (viewerDID !== identityID) {
+            throw new Error('Only the engine identity can perform this operation');
+        }
+    }
+}

package/lib/groups/admin-roster.d.ts

@@ -0,0 +1,130 @@
+import type { Logger } from '@kubun/logger';
+import type { P2PStoreAPI } from '@kubun/store-p2p';
+import type { GroupAnchor } from './group-anchor.js';
+import { type VerifiedLedgerEntry } from './ledger-entry.js';
+import { type FoldInput, type LedgerReducer } from './ledger-fold.js';
+/** Ledger entry `type` for an admin-role grant or revocation. */
+export declare const ADMIN_ROLE_ENTRY_TYPE = "group.role.admin";
+/**
+ * Projection key for the admin-roster watermark. One projection per entry type
+ * in this design, so the key is the entry type itself.
+ */
+export declare const ADMIN_ROSTER_PROJECTION = "group.role.admin";
+/**
+ * The claim carried by an admin-role entry. `subject` (on the entry) is the
+ * member DID the claim is about; this value says whether that member becomes an
+ * admin or loses the role.
+ */
+export type AdminRoleValue = 'admin' | 'revoked';
+/** Folded admin set: the normalized DIDs currently holding the admin role. */
+export type AdminRosterState = {
+    admins: Set<string>;
+};
+/**
+ * Self-referential admin roster. Authority is rooted at the genesis anchor (the
+ * creator is the epoch-0 admin) and grows only through admins-so-far: every
+ * grant or revocation must be issued by a DID already in the set accumulated
+ * from strictly-earlier entries. That state-so-far check is what makes rotation
+ * sound — an admin can revoke the very creator that granted them without
+ * retroactively voiding their own earlier grants.
+ */
+export declare const adminRosterReducer: LedgerReducer<AdminRoleValue, AdminRosterState>;
+/**
+ * Fold the admin-role ledger into the current admin set. With `atHLC`, only
+ * entries at or before that HLC are folded, yielding the exact was-admin-at-HLC
+ * answer the current-only role column cannot express. The string `<=` compare on
+ * the serialized HLC is the total order (zero-padded, lexicographic), matching
+ * the membership-removal LWW elsewhere in the store.
+ */
+export declare function foldAdminRoster(entries: Array<FoldInput<AdminRoleValue>>, anchor: GroupAnchor, atHLC?: string): AdminRosterState;
+export type ProjectAdminRosterParams = {
+    store: P2PStoreAPI;
+    groupID: string;
+    anchor: GroupAnchor;
+    /** The group's admin-role ledger entries, in any order. */
+    entries: Array<FoldInput<AdminRoleValue>>;
+    /** Current active members whose role overlay should be reconciled. */
+    memberDIDs: Array<string>;
+};
+/**
+ * Project the folded admin set onto the store's `role` column. Membership stays
+ * MLS-native — this only overlays a role on members that already exist: each
+ * current member is set to `admin` when the fold places them in the set and
+ * `member` otherwise. `setGroupMemberRole` is update-only, so a DID in the
+ * admin set with no membership row is silently skipped.
+ */
+export declare function projectAdminRoster(params: ProjectAdminRosterParams): Promise<void>;
+/**
+ * Load the group's admin-role ledger entries and re-verify each `signed_token`
+ * into a fold input. The stored token is re-verified rather than trusting the
+ * decoded `value` column: the ledger is the source of truth and must stay
+ * self-verifying, so a stored token that no longer verifies is dropped and the
+ * rest survive. Returned in store order; the fold sorts by total order. Results
+ * are memoized per group on the stored id set (see {@link verifiedAdminEntryCache}).
+ */
+export declare function loadVerifiedAdminEntries(store: P2PStoreAPI, groupID: string, logger?: Logger): Promise<Array<FoldInput<AdminRoleValue>>>;
+/**
+ * Re-project the admin overlay from the stored ledger. The active member set
+ * bounds the overlay — `projectAdminRoster` only touches rows that already
+ * exist, so an admin DID with no membership is silently skipped.
+ */
+export type ProjectAdminRosterFromStoreParams = {
+    store: P2PStoreAPI;
+    groupID: string;
+    anchor: GroupAnchor;
+    logger?: Logger;
+};
+export declare function projectAdminRosterFromStore(params: ProjectAdminRosterFromStoreParams): Promise<void>;
+/**
+ * Was `did` a group admin at `atHLC`? Authority is folded from the
+ * anchor-seeded ledger evaluated at the operation's HLC (rotation-aware:
+ * was-admin-at-HLC, not is-admin-now), conjoined with membership at that HLC.
+ * Folding from the genesis anchor — not the local `role` column — is what makes
+ * a receiver agree with the author's peer: the creator is the epoch-0 admin on
+ * every peer regardless of how its membership row's role was written.
+ *
+ * Admin implies membership: an MLS-removed member loses admin regardless of the
+ * ledger, so membership-at-HLC is checked first and short-circuits.
+ */
+export type IsLedgerAdminAtHLCParams = {
+    store: P2PStoreAPI;
+    groupID: string;
+    anchor: GroupAnchor;
+    did: string;
+    atHLC: string;
+    logger?: Logger;
+};
+export declare function isLedgerAdminAtHLC(params: IsLedgerAdminAtHLCParams): Promise<boolean>;
+/**
+ * Authoritatively rebuild the admin overlay from the whole ledger and reset the
+ * watermark to the newest folded entry. Used on a first projection, an
+ * out-of-order arrival, or drift repair — anywhere the cached projection can no
+ * longer be trusted as a fold-through-watermark. Seeds the admin set from the
+ * genesis anchor (the creator is the epoch-0 admin), so it never relies on a
+ * pre-existing `role` value in the store.
+ */
+export type ReprojectAdminRosterParams = {
+    store: P2PStoreAPI;
+    groupID: string;
+    anchor: GroupAnchor;
+    logger?: Logger;
+};
+export declare function reprojectAdminRoster(params: ReprojectAdminRosterParams): Promise<void>;
+/**
+ * Apply a single just-appended in-order entry onto the current projection
+ * without re-folding the whole ledger. The caller guarantees the entry is
+ * strictly newer than the watermark, so the projection already equals the
+ * fold-so-far: the current admins are exactly the members projected with role
+ * `admin`. Authority is read from that projection — only a current admin may
+ * grant or revoke — so an entry from a non-admin issuer is dropped (never
+ * thrown). `setGroupMemberRole` is update-only, so a grant for a DID with no
+ * membership row is silently skipped; admin implies membership and membership
+ * stays MLS-native.
+ */
+export type ApplyAdminEntryIncrementalParams = {
+    store: P2PStoreAPI;
+    groupID: string;
+    verified: VerifiedLedgerEntry<AdminRoleValue>;
+    logger?: Logger;
+};
+export declare function applyAdminEntryIncremental(params: ApplyAdminEntryIncrementalParams): Promise<void>;

package/lib/groups/admin-roster.js

@@ -0,0 +1,184 @@
+import { normalizeDID } from '@kokuin/token';
+import { verifyLedgerEntry } from './ledger-entry.js';
+import { foldLedger } from './ledger-fold.js';
+/** Ledger entry `type` for an admin-role grant or revocation. */ export const ADMIN_ROLE_ENTRY_TYPE = 'group.role.admin';
+/**
+ * Projection key for the admin-roster watermark. One projection per entry type
+ * in this design, so the key is the entry type itself.
+ */ export const ADMIN_ROSTER_PROJECTION = ADMIN_ROLE_ENTRY_TYPE;
+/**
+ * Self-referential admin roster. Authority is rooted at the genesis anchor (the
+ * creator is the epoch-0 admin) and grows only through admins-so-far: every
+ * grant or revocation must be issued by a DID already in the set accumulated
+ * from strictly-earlier entries. That state-so-far check is what makes rotation
+ * sound — an admin can revoke the very creator that granted them without
+ * retroactively voiding their own earlier grants.
+ */ export const adminRosterReducer = {
+    type: ADMIN_ROLE_ENTRY_TYPE,
+    seed: (anchor)=>({
+            admins: new Set([
+                normalizeDID(anchor.creatorDID)
+            ])
+        }),
+    verifyAuthority: (verified, state)=>state.admins.has(verified.issuer),
+    apply: (verified, state)=>{
+        const admins = new Set(state.admins);
+        const subject = normalizeDID(verified.entry.subject);
+        if (verified.entry.value === 'admin') {
+            admins.add(subject);
+        } else if (verified.entry.value === 'revoked') {
+            admins.delete(subject);
+        } else {
+            // Unknown claim value: leave the set untouched rather than guess intent.
+            return state;
+        }
+        return {
+            admins
+        };
+    }
+};
+/**
+ * Fold the admin-role ledger into the current admin set. With `atHLC`, only
+ * entries at or before that HLC are folded, yielding the exact was-admin-at-HLC
+ * answer the current-only role column cannot express. The string `<=` compare on
+ * the serialized HLC is the total order (zero-padded, lexicographic), matching
+ * the membership-removal LWW elsewhere in the store.
+ */ export function foldAdminRoster(entries, anchor, atHLC) {
+    const scoped = atHLC == null ? entries : entries.filter(({ verified })=>verified.entry.hlc <= atHLC);
+    return foldLedger(scoped, anchor, adminRosterReducer);
+}
+/**
+ * Project the folded admin set onto the store's `role` column. Membership stays
+ * MLS-native — this only overlays a role on members that already exist: each
+ * current member is set to `admin` when the fold places them in the set and
+ * `member` otherwise. `setGroupMemberRole` is update-only, so a DID in the
+ * admin set with no membership row is silently skipped.
+ */ export async function projectAdminRoster(params) {
+    const { store, groupID, anchor, entries, memberDIDs } = params;
+    const { admins } = foldAdminRoster(entries, anchor);
+    for (const memberDID of memberDIDs){
+        const role = admins.has(normalizeDID(memberDID)) ? 'admin' : 'member';
+        await store.setGroupMemberRole(groupID, memberDID, role);
+    }
+}
+/**
+ * Memoized verified admin entries, one slot per group keyed by the exact set of
+ * stored entry ids. Verifying every stored token is the dominant cost of an
+ * authority check, and the gate folds on every control op, so re-verifying an
+ * unchanged ledger each time is pure waste. Reading the id set stays cheap (an
+ * indexed scan); signatures are re-verified only when the set changes. The key
+ * is derived purely from content-addressed entry ids — never the `role` column —
+ * so the cache can never reintroduce the column-trust bypass: a forged or
+ * altered entry produces a different id set, a different key, and a full
+ * re-verification. One slot per group bounds memory and self-invalidates, since
+ * the ledger is append-only and every append changes the id set.
+ *
+ * Cross-instance safety: this Map is process-global, shared across store
+ * instances and keyed only by group id. Two instances using the same group id
+ * with different ledgers stay correct because differing ledgers yield differing
+ * keys (entry ids are content digests); the only shared key is the empty-ledger
+ * `''`, whose cached value is `[]` — exactly what either empty ledger produces.
+ * Group growth is bounded: only device-side peers fold rosters (the blind relay
+ * hub never calls this path), so the distinct-group set per process is small and
+ * needs no eviction.
+ */ const verifiedAdminEntryCache = new Map();
+function adminEntryCacheKey(entryIDs) {
+    return entryIDs.join('\n');
+}
+/**
+ * Load the group's admin-role ledger entries and re-verify each `signed_token`
+ * into a fold input. The stored token is re-verified rather than trusting the
+ * decoded `value` column: the ledger is the source of truth and must stay
+ * self-verifying, so a stored token that no longer verifies is dropped and the
+ * rest survive. Returned in store order; the fold sorts by total order. Results
+ * are memoized per group on the stored id set (see {@link verifiedAdminEntryCache}).
+ */ export async function loadVerifiedAdminEntries(store, groupID, logger) {
+    const rows = await store.getLedgerEntriesByType(groupID, ADMIN_ROLE_ENTRY_TYPE);
+    const key = adminEntryCacheKey(rows.map((row)=>row.entry_id));
+    const cached = verifiedAdminEntryCache.get(groupID);
+    if (cached != null && cached.key === key) {
+        return cached.entries;
+    }
+    const entries = [];
+    for (const row of rows){
+        const verified = await verifyLedgerEntry(row.signed_token);
+        if (verified == null) {
+            logger?.warn('admin roster: dropped stored entry whose token no longer verifies', {
+                groupID,
+                entryID: row.entry_id
+            });
+            continue;
+        }
+        entries.push({
+            verified,
+            entryID: row.entry_id
+        });
+    }
+    verifiedAdminEntryCache.set(groupID, {
+        key,
+        entries
+    });
+    return entries;
+}
+export async function projectAdminRosterFromStore(params) {
+    const { store, groupID, anchor, logger } = params;
+    const entries = await loadVerifiedAdminEntries(store, groupID, logger);
+    const memberDIDs = (await store.listGroupMembers(groupID)).map((member)=>member.member_did);
+    await projectAdminRoster({
+        store,
+        groupID,
+        anchor,
+        entries,
+        memberDIDs
+    });
+}
+export async function isLedgerAdminAtHLC(params) {
+    const { store, groupID, anchor, did, atHLC, logger } = params;
+    if (!await store.isGroupMemberAtHLC(groupID, did, atHLC)) return false;
+    const entries = await loadVerifiedAdminEntries(store, groupID, logger);
+    const { admins } = foldAdminRoster(entries, anchor, atHLC);
+    return admins.has(normalizeDID(did));
+}
+export async function reprojectAdminRoster(params) {
+    const { store, groupID, anchor, logger } = params;
+    const entries = await loadVerifiedAdminEntries(store, groupID, logger);
+    const memberDIDs = (await store.listGroupMembers(groupID)).map((member)=>member.member_did);
+    await projectAdminRoster({
+        store,
+        groupID,
+        anchor,
+        entries,
+        memberDIDs
+    });
+    // Watermark through the newest folded entry: the projection now equals the
+    // fold of every verified entry, so a later in-order arrival (strictly newer
+    // HLC) can be applied incrementally instead of forcing a full reproject.
+    let maxHLC = null;
+    for (const { verified } of entries){
+        if (maxHLC == null || verified.entry.hlc > maxHLC) {
+            maxHLC = verified.entry.hlc;
+        }
+    }
+    if (maxHLC != null) {
+        await store.setProjectionWatermark(groupID, ADMIN_ROSTER_PROJECTION, maxHLC);
+    }
+}
+export async function applyAdminEntryIncremental(params) {
+    const { store, groupID, verified, logger } = params;
+    const members = await store.listGroupMembers(groupID);
+    const currentAdmins = new Set(members.filter((m)=>m.role === 'admin').map((m)=>normalizeDID(m.member_did)));
+    if (!currentAdmins.has(verified.issuer)) {
+        logger?.warn('admin roster: dropped incremental entry from a non-admin issuer', {
+            groupID,
+            issuer: verified.issuer
+        });
+        return;
+    }
+    const subject = normalizeDID(verified.entry.subject);
+    if (verified.entry.value === 'admin') {
+        await store.setGroupMemberRole(groupID, subject, 'admin');
+    } else if (verified.entry.value === 'revoked') {
+        await store.setGroupMemberRole(groupID, subject, 'member');
+    }
+// Unknown value: no-op, mirroring the reducer's leave-untouched policy.
+}

package/lib/groups/broadcast-codec.js

@@ -1 +1,6 @@
-export function serializeBroadcast(e){return new TextEncoder().encode(JSON.stringify(e))}export function deserializeBroadcast(e){return JSON.parse(new TextDecoder().decode(e))}
+export function serializeBroadcast(message) {
+    return new TextEncoder().encode(JSON.stringify(message));
+}
+export function deserializeBroadcast(bytes) {
+    return JSON.parse(new TextDecoder().decode(bytes));
+}