@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/groups/group-mls.js

@@ -0,0 +1,696 @@
+import { normalizeDID } from '@kokuin/token';
+import { HLC } from '@kubun/hlc';
+import { getKubunLogger } from '@kubun/logger';
+import { getP2PStore } from '@kubun/store-p2p';
+import { CommitRejectedError, createRecoveryRequest, joinGroupExternal, MissingLedgerEntriesError, openSealedGroupInfo, openSealedLedger, readGroupAnchor, readMessageEpoch, sealGroupInfo, sealLedger } from '@kumiai/mls';
+import { fromB64 } from '@sozai/codec';
+import { toISO } from '../context/types.js';
+import { bootstrapGroupLedger } from './broadcast.js';
+import { readRecoverySecret } from './group-anchor.js';
+import { emitLedgerAffectedEvents } from './ledger-affected-events.js';
+import { entriesRetainedByCommit, foldCommittedLedgerEntries } from './ledger-commit-fold.js';
+import { DecryptError } from './mls-receive-errors.js';
+import { mirrorRosterRoles, roleFromRoster } from './roster-projection.js';
+/**
+ * How long a minted recovery request's private key is retained.
+ *
+ * Bounds a gather that never completes rather than expressing a security
+ * property: the key opens replies to ONE request id, and a reply arriving after
+ * this is simply unopenable. Matches `@kumiai/mls-rpc`'s own retention, so a
+ * kubun peer and an upstream one give up on the same gather at the same time.
+ */ const RECOVERY_REQUEST_TTL_MS = 120_000;
+/**
+ * Adapts a `GroupHandleRegistry` group into the `@kumiai/rpc`
+ * {@link GroupMLS} lifecycle port: apply received Commits to advance the epoch,
+ * read the roster, seal this handle's ledger for another member's gather, and
+ * expose the epoch-independent recovery seed. group-rpc owns the transport +
+ * orchestration (subscribe the non-rotating handshake topic, run these methods,
+ * resync the app lane when the epoch advances); this adapter owns the MLS state,
+ * storage, and atomicity.
+ *
+ * The recovery members that throw below do so for reasons that live in KUBUN,
+ * not upstream: `@kumiai/mls` ships every primitive they would need. An earlier
+ * revision of this file justified the same throws by upstream gaps, and a later
+ * upstream release quietly made those justifications false. So a reader deciding
+ * whether one of these can now be wired must re-check the KUBUN-side statement
+ * in each message — not assume the blocker moved when a dependency did.
+ */ export function createGroupMLS(params) {
+    const { registry, stores, identity, hlc, groupID } = params;
+    const logger = params.logger ?? getKubunLogger('plugin-p2p:group-mls');
+    // The private half of each outstanding recovery request, in process memory.
+    //
+    // Deliberately NOT a store row. The gather this key serves is a live
+    // rendezvous the lane holds open; a restart loses the gather too, so a
+    // surviving key would have no reply left to open and would only be a raw
+    // private key sitting in SQLite at rest, where kubun's at-rest encryption is
+    // not yet wired. Losing it on restart costs a retry and nothing else.
+    const pending = new Map();
+    // The lane has no release hook: a gather that times out drops its request id
+    // without telling this port, so eviction on reply-open alone would leak one
+    // key per timed-out gather for the life of the process. Swept on mint, which
+    // is the only moment the map grows.
+    const sweep = ()=>{
+        const cutoff = Date.now() - RECOVERY_REQUEST_TTL_MS;
+        for (const [id, held] of pending){
+            if (held.mintedAt < cutoff) {
+                pending.delete(id);
+            }
+        }
+    };
+    return {
+        /**
+     * The DIDs this handle's ratchet tree currently holds a leaf for. Read-only.
+     *
+     * The lane diffs this around {@link GroupMLS.processCommit} to detect a
+     * Remove. Compare DIDs rather than count leaves, or a Commit carrying both an
+     * Add and a Remove reads as no change. Sourced from the ratchet TREE, not the
+     * store's roster projection — that is the authority the lane must agree with.
+     */ async rosterDIDs () {
+            return await registry.readHandle(groupID, (handle)=>handle.listMembers().map((member)=>member.id));
+        },
+        /**
+     * Read what a Commit says about itself — its framed epoch, its
+     * MLS-authenticated committer, and whether it is an external commit —
+     * WITHOUT advancing state. `null` for bytes that are not a Commit.
+     *
+     * The committer is recovered from the Commit's OWN bytes, never from the
+     * frame's transport sender — that is the hub's word.
+     *
+     * `external` must be passed through even though nothing here reads it: a
+     * rejoin moves no DID and no occupied leaf index, so the lane's anchor
+     * rotation is the only signal it has, and dropping the flag disables it
+     * silently.
+     */ async readCommitHeader (commit) {
+            return await registry.readHandle(groupID, async (handle)=>{
+                const header = await handle.readCommitHeader(commit);
+                if (header == null) {
+                    return null;
+                }
+                return {
+                    epoch: Number(header.epoch),
+                    committerDID: header.committerDID,
+                    external: header.external
+                };
+            });
+        },
+        /**
+     * Apply a received MLS handshake Commit: advance the local ratchet and write
+     * the membership delta derived by diffing the roster before and after.
+     *
+     * Runs INSIDE a single store transaction so the ratchet advance (persisted
+     * by the registry) and the resulting roster delta writes commit or roll back
+     * together. A roster-write failure after the ratchet persisted would
+     * otherwise leave a removed member's writes still applying. The registry
+     * holds the per-group lock across the whole transaction, so no concurrent
+     * same-group op can interleave.
+     *
+     * A frame this peer is not in a position to apply resolves `advanced:false`,
+     * NEVER a throw — a throw would leave the lane's cursor put and re-read the
+     * frame forever (a late joiner meeting its own add-commit, the first frame it
+     * reads, would wedge on it). All of these are `advanced:false`:
+     * - not a Commit, or a Commit framed at another epoch (past OR future);
+     * - a Commit this device authored (a member can never apply its own commit);
+     * - a Commit the group's control policy refuses.
+     *
+     * The ONE deliberate throw is a Commit this peer SHOULD apply but cannot,
+     * because the ledger entries it names will not resolve from the Commit's own
+     * frame — {@link MissingLedgerEntriesError}, which the lane recognizes as
+     * poison and steps over. A corrupt/forged frame is ack-and-skipped
+     * (`advanced:false`); a transient store fault propagates so the lane retries.
+     */ async processCommit (commit, context) {
+            // The transport sender is auxiliary (logging), NOT the MLS committer and
+            // never an authorization boundary — the Commit authenticates its committer
+            // internally.
+            logger.debug('processCommit', {
+                groupID,
+                senderDID: context.senderDID
+            });
+            // Resolve the commit's sealed ledger bodies BEFORE taking the apply lock.
+            // The frame resolver decrypts via the cached handle (`readHandle`), which
+            // re-enters the per-group mutex; that mutex is held for the whole apply
+            // transaction below, so resolving inside it would self-deadlock. The frame
+            // resolver is id-agnostic — it answers with every token in the blob — so a
+            // single drain with `[]` yields the whole frame's bodies. The unwrap is
+            // read-only and its result is re-verified (content-addressed + signature
+            // checked) by `processMessage`, so moving where it runs changes nothing
+            // durable or trusted; a blob this peer cannot open drains to `[]`, keeping
+            // the missing-entries poison contract intact. When the context carries no
+            // resolver, pass none so the store-based default resolves from the store.
+            let resolveOverride;
+            if (context.resolveLedgerEntries != null) {
+                const resolvedEntries = await context.resolveLedgerEntries([]);
+                resolveOverride = {
+                    resolveLedgerEntries: async ()=>resolvedEntries
+                };
+            }
+            // The entries an accepted commit surfaces, collected for this call only.
+            // The sink is synchronous by contract, so it cannot await a store write:
+            // it only collects, and the fold runs after `processMessage` returns,
+            // inside the same transaction as the ratchet advance and the roster delta.
+            const surfacedEntries = [];
+            // Descriptors the fold produced, emitted only AFTER the transaction
+            // commits: an event announcing a row a rollback erased would be a lie.
+            let affected = [];
+            // The membership deltas this commit enacted, announced under the same
+            // past-commit rule as `affected`. This device did NOT author the commit
+            // (it declines its own below), so nothing else on this device announces
+            // them: the author's own device emits these from the producer path, which
+            // no fold ever visits, and the two therefore cannot both fire.
+            let joined = [];
+            let left = [];
+            let roleChanged = [];
+            // Set when the commit removed THIS device. Emitted last: the teardown it
+            // triggers disposes the listeners the membership events ask to reconcile.
+            let selfRemoved = null;
+            const advance = await registry.withHandleReplacingInTransaction(groupID, stores, async (handle, tx)=>{
+                // The Commit's cleartext wire-header epoch is the sender's pre-commit
+                // epoch — the epoch a receiver must be at to process it. A frame at
+                // any other epoch (past = already applied, future = a gap this peer
+                // has not reached, e.g. a late joiner's own add-commit) is not this
+                // member's to apply and is never opened — the blob riding it stays
+                // sealed because its entries are never resolved.
+                const messageEpoch = readMessageEpoch(commit);
+                if (messageEpoch == null || messageEpoch !== handle.epoch) {
+                    return {
+                        result: {
+                            advanced: false
+                        },
+                        updated: handle
+                    };
+                }
+                // The committer comes from the Commit's own authenticated bytes, not
+                // the frame sender. A member can never apply the frame that is its
+                // OWN commit — MLS merges a pending commit, it does not process one —
+                // so a device meeting its own commit in the log declines it.
+                const header = await handle.readCommitHeader(commit);
+                // `null` means "these bytes are not a Commit" and nothing else —
+                // upstream is explicit that it never means "a Commit I could not
+                // read". So this is also the content-type gate for the channel: a
+                // by-reference Proposal broadcast on the commit lane by any member
+                // stops here, before `processMessage` can store it in the pending
+                // set, where it would be absorbed into the next commit an innocent
+                // member authors and get that member's commit refused by every peer.
+                // Pinned in this position by `commit-ingest-rejects-proposals.test.ts`,
+                // because nothing else would fail if it moved.
+                if (header == null) {
+                    logger.warn('commit ingest dropped a non-Commit message', {
+                        groupID,
+                        senderDID: context.senderDID
+                    });
+                    return {
+                        result: {
+                            advanced: false
+                        },
+                        updated: handle
+                    };
+                }
+                if (header.committerDID === handle.credential.id) {
+                    return {
+                        result: {
+                            advanced: false
+                        },
+                        updated: handle
+                    };
+                }
+                const priorEpoch = handle.epoch;
+                const before = handle.listMembers();
+                // The ledger log's length BEFORE the commit is applied. The handle
+                // appends what an accepted commit enacted to the end of this log, in
+                // enactment order, so this index is the only way to tell this
+                // commit's entries from the ones the handle already held — the log
+                // records repeats, so a token diff would miss a re-enactment.
+                const ledgerLengthBeforeCommit = handle.ledger.length;
+                try {
+                    // No commit policy is passed: the handle carries `@kumiai/mls`'s
+                    // default one, which folds the roster from the signed control ledger
+                    // and refuses a commit whose author lacks the permission for it.
+                    // Passing a policy here would REPLACE that gate rather than add to it.
+                    await handle.processMessage(commit);
+                } catch (error) {
+                    // The commit enacts ledger entries this peer does not hold, and they
+                    // will not resolve from the frame that carries them. This is the one
+                    // deliberate throw: the lane treats it as poison, stepping over the
+                    // frame rather than re-reading it. Let it propagate untouched — its
+                    // NAME is what `isMissingLedgerEntries` matches.
+                    if (error instanceof MissingLedgerEntriesError) {
+                        throw error;
+                    }
+                    // Well-formed but refused: the group's control policy does not accept
+                    // a commit from this committer. A refusal is a judgment, not a
+                    // failure — there is nothing to retry, so ack-and-skip.
+                    if (error instanceof CommitRejectedError) {
+                        return {
+                            result: {
+                                advanced: false
+                            },
+                            updated: handle
+                        };
+                    }
+                    // A Commit that fails the authenticated MLS check at the matching
+                    // epoch is corrupt/forged — unrecoverable, so ack-and-skip rather
+                    // than redeliver.
+                    // biome-ignore lint/style/useErrorCause: DecryptError forwards its second argument as the cause
+                    throw new DecryptError('Failed to process MLS commit', error);
+                }
+                const after = handle.listMembers();
+                const beforeIDs = new Set(before.map((member)=>member.id));
+                const afterIDs = new Set(after.map((member)=>member.id));
+                const removed = before.filter((member)=>!afterIDs.has(member.id)).map((member)=>member.id);
+                const added = after.filter((member)=>!beforeIDs.has(member.id)).map((member)=>member.id);
+                // All reads + writes use the transactional p2p store so they share the
+                // tx's single connection (a bare store read inside the tx would
+                // deadlock single-connection SQLite against the tx's write lock).
+                const localHLC = HLC.serialize(hlc.now());
+                const p2pStore = await getP2PStore(tx);
+                // One read of the pre-commit rows serves both announcements and the
+                // role comparison below: a removal has to report the role its target
+                // held while they were still a member, and the tombstone is about to
+                // put that row out of reach.
+                const membersBefore = await p2pStore.listGroupMembers(groupID);
+                const rowByDID = new Map(membersBefore.map((member)=>[
+                        normalizeDID(member.member_did),
+                        member
+                    ]));
+                // One statement tombstones the whole removed set, so a commit that
+                // drops several members cannot land half its removals.
+                await p2pStore.markMembersRemoved(groupID, removed, localHLC);
+                // The ex-member's advertisement goes with its membership, in the
+                // same transaction: the row is a route MLS would refuse, and a
+                // projection still offering it makes the UI name a device the group
+                // no longer contains.
+                await p2pStore.deletePeerAnnouncements({
+                    groupID,
+                    peerDIDs: removed
+                });
+                // A removal naming THIS device says it has left, and nothing else
+                // ever said it: `setGroupStatus(id, 'left')` was written only by
+                // `markGroupLeft`, on the voluntary path.
+                //
+                // Marked here because this is the one moment the eviction is
+                // AUTHENTICATED — the commit naming this device was processed under
+                // the epoch it still held. Anything downstream (frames that stop
+                // opening, a quiet hub) is indistinguishable from an outage.
+                //
+                // The rows stay: they project what this device saw, and erasing
+                // local history on someone else's say-so is worse.
+                if (removed.some((memberDID)=>normalizeDID(memberDID) === normalizeDID(identity.id))) {
+                    await p2pStore.setGroupStatus(groupID, 'left');
+                    // The status is what a LATER read sees; this tells what is already
+                    // running. `groupLeft` has one consumer (`hub/wiring.ts`) and it is
+                    // the entire teardown: the group leaves the peer manager's
+                    // in-memory `joined` set, its tunnel listeners go, its hub peers
+                    // are disposed. Presence and sync read that set, never the status
+                    // column, so writing the row alone left the device announcing
+                    // itself and encrypting into a group MLS refused.
+                    //
+                    // Emitted from here and from `leaveGroup`, so both ways out produce
+                    // the same teardown. Unlike `leaveGroup` this does NOT drop the MLS
+                    // state: re-admission compares the Welcome's epoch against the
+                    // persisted one, and a device that discarded it cannot be let back.
+                    const row = await p2pStore.getGroup(groupID);
+                    selfRemoved = row == null ? null : {
+                        id: row.id,
+                        groupID: row.id,
+                        name: row.name,
+                        description: row.description,
+                        createdBy: row.created_by,
+                        createdAt: toISO(row.created_at)
+                    };
+                }
+                left = removed.map((memberDID)=>rowByDID.get(normalizeDID(memberDID))).filter((row)=>row != null).map((row)=>({
+                        groupID,
+                        memberDID: row.member_did,
+                        role: row.role,
+                        createdAt: toISO(row.created_at)
+                    }));
+                // Roles come from the handle's own post-commit roster, not from the
+                // ratchet (which carries no kubun role) and not from a separately
+                // delivered ledger token. The roster folds the genesis anchor plus
+                // exactly the entries the authenticated commit chain enacted, in
+                // epoch order, so a receiver reads the same authority its commit
+                // policy enforces. Recovering a role change missed while offline
+                // additionally requires the device to apply the commit that carried
+                // it, which the seed pull does not currently do.
+                const roster = handle.roster;
+                const addedWithRoles = added.map((memberDID)=>({
+                        memberDID,
+                        role: roleFromRoster(roster, memberDID)
+                    }));
+                // One multi-row insert for the whole added set.
+                await p2pStore.addGroupMembers(addedWithRoles.map(({ memberDID, role })=>({
+                        group_id: groupID,
+                        member_did: memberDID,
+                        role,
+                        hlc: localHLC
+                    })));
+                // The rows were created by the write above, so their creation instant
+                // is now; reading them back would cost a query to learn what is
+                // already known.
+                const addedAt = new Date().toISOString();
+                joined = addedWithRoles.map(({ memberDID, role })=>({
+                        groupID,
+                        memberDID,
+                        role,
+                        createdAt: addedAt
+                    }));
+                // A commit can also promote or demote a member it neither adds nor
+                // removes, so every member that survived it is reconciled too. The
+                // rows read above are the pre-commit ones, which is exactly what the
+                // roster must be compared against to tell a real change from a
+                // re-assertion of the role a member already held.
+                roleChanged = await mirrorRosterRoles({
+                    store: p2pStore,
+                    groupID,
+                    roster,
+                    memberDIDs: after.filter((member)=>beforeIDs.has(member.id)).map((member)=>member.id),
+                    members: membersBefore
+                });
+                // A landed commit's surfaced entries fold through the same projection
+                // ingest a broadcast entry does, on the transaction's own store — the
+                // tx holds the write lock, so a bare store read here would deadlock
+                // single-connection SQLite.
+                //
+                // A role entry is NOT among the surfaced ones: the MLS library
+                // interprets it itself, folding it into the roster mirrored onto the
+                // rows above rather than handing it on. It is in the handle's ledger
+                // regardless — which is where the admin roster folds it from — but
+                // its HLC reaches this device by no other path, so it is recovered
+                // from the log and passed through the same ingest for its clock.
+                affected = await foldCommittedLedgerEntries({
+                    handle,
+                    entries: surfacedEntries,
+                    retained: entriesRetainedByCommit(handle, ledgerLengthBeforeCommit),
+                    p2pStore,
+                    groupID,
+                    hlc,
+                    logger
+                });
+                return {
+                    result: {
+                        advanced: handle.epoch > priorEpoch
+                    },
+                    updated: handle
+                };
+            }, // Per-call handle wiring, scoped to the working handle this call
+            // restores. `resolveLedgerEntries` is pre-resolved above so the commit
+            // pre-pass resolves entries from the frame (via a plain non-locking
+            // resolver) rather than re-entering the per-group mutex the transaction
+            // holds; undefined falls back to the store-based default resolver.
+            // `onLedgerEntries` collects what the accepted commit surfaces.
+            {
+                ...resolveOverride != null ? {
+                    resolveLedgerEntries: resolveOverride.resolveLedgerEntries
+                } : {},
+                onLedgerEntries: (entries)=>{
+                    surfacedEntries.push(...entries);
+                }
+            }).catch((error)=>{
+                // A corrupt/forged Commit threw inside the transaction, so it rolled back
+                // (DB untouched). Ack-and-skip it: report no epoch advance so group-rpc
+                // acks and the hub stops redelivering — group-rpc re-fetches any Commit
+                // whose `processCommit` throws, so letting a corrupt frame escape here
+                // would poison-redeliver forever. MissingLedgerEntriesError (poison) and
+                // transient store faults are re-thrown so the lane classifies them.
+                if (error instanceof DecryptError) {
+                    logger.warn('dropping corrupt MLS commit (ack-and-skip)', {
+                        groupID,
+                        error
+                    });
+                    return {
+                        advanced: false
+                    };
+                }
+                throw error;
+            });
+            // Only now, past commit: the rows the events announce are durable. A
+            // rollback (or an ack-and-skip) folded nothing, so there is nothing to
+            // announce. Emitting must not turn a landed commit into a failed one, so a
+            // faulting subscriber is logged, not propagated.
+            const emitter = params.emitter;
+            if (emitter != null) {
+                for (const ledger of affected){
+                    try {
+                        await emitLedgerAffectedEvents(emitter, {
+                            applied: true,
+                            affected: {
+                                kind: 'ledger',
+                                ledger
+                            }
+                        });
+                    } catch (error) {
+                        logger.warn('committed ledger entry event emit failed', {
+                            groupID,
+                            error
+                        });
+                    }
+                }
+                for (const [eventName, members] of [
+                    [
+                        'groupMemberJoined',
+                        joined
+                    ],
+                    [
+                        'groupMemberLeft',
+                        left
+                    ],
+                    [
+                        'groupMemberRoleChanged',
+                        roleChanged
+                    ]
+                ]){
+                    for (const member of members){
+                        try {
+                            await emitter.emit(eventName, member);
+                        } catch (error) {
+                            logger.warn('group membership event emit failed', {
+                                groupID,
+                                eventName,
+                                error
+                            });
+                        }
+                    }
+                }
+                // After `groupMemberLeft`: that reconciles the group's tunnel listeners,
+                // this disposes them. Reversed, the reconcile rebuilds them.
+                if (selfRemoved != null) {
+                    try {
+                        await emitter.emit('groupLeft', selfRemoved);
+                    } catch (error) {
+                        logger.warn('groupLeft emit failed', {
+                            groupID,
+                            error
+                        });
+                    }
+                }
+            }
+            return advance;
+        },
+        /**
+     * Mint the signed rendezvous request this peer publishes to ask the group
+     * for its state, retaining the private half of the request's ephemeral HPKE
+     * keypair so the replies can be opened.
+     *
+     * The request token is signed by this member's identity key. The private half
+     * is held in `pending` under `requestID`, in process memory only, and evicted
+     * by `sweep()` on a TTL — the lane has no release hook, so a timed-out gather
+     * drops its request id silently and an evict-on-reply-open port would leak a
+     * key per timeout.
+     */ async createRecoveryRequest (requestID) {
+            sweep();
+            // Inside the registry lock like every other handle read: the primitive is
+            // read-only, but the handle it reads may not be observed mid-replacement.
+            const { request, ephemeralPrivateKey } = await registry.readHandle(groupID, (handle)=>createRecoveryRequest({
+                    group: handle,
+                    identity,
+                    requestID
+                }));
+            pending.set(requestID, {
+                ephemeralPrivateKey,
+                mintedAt: Date.now()
+            });
+            return new TextEncoder().encode(request);
+        },
+        /**
+     * Answer another member's GroupInfo request: seal current GroupInfo to the
+     * ephemeral key in the signed request and vouch for it with a membership
+     * attestation.
+     *
+     * The seal is HPKE base mode and authenticates NOBODY, so the reply must carry
+     * a membership attestation signed by this member's DID key — that is what lets
+     * the requester tell it from an observer's forgery. Confidentiality against
+     * the relaying hub is intact regardless: the seal targets a per-request
+     * ephemeral public key whose private half the hub never sees.
+     */ async sealGroupInfo (request) {
+            // Throws for a request this member refuses — a requester holding no leaf
+            // in THIS handle's tree gets nothing from a responder that has applied
+            // their removal — and group-rpc reads the throw as "stay silent".
+            // Roster-intrinsic, so there is no check to write here.
+            return await registry.readHandle(groupID, (handle)=>sealGroupInfo({
+                    group: handle,
+                    identity,
+                    request: new TextDecoder().decode(request)
+                }));
+        },
+        /**
+     * Open a sealed GroupInfo reply and build the external commit that rejoins
+     * this peer, adopted only once the head accepts it.
+     *
+     * Wired now: it consumes what {@link GroupMLS.createRecoveryRequest}
+     * retains — the ephemeral private key held under `requestID` in `pending` —
+     * and builds the external commit under the signing `identity`
+     * {@link CreateGroupMLSParams} now carries.
+     *
+     * The rejoin Commit itself has a home: the lane publishes
+     * `PendingRecovery.commit` to the commit topic under a compare-and-set at
+     * the head, so this peer does not have to fan it out and cannot fork the
+     * group by applying it locally. That is not what blocks this member.
+     */ async applyRecovery (sealed, requestID) {
+            const held = pending.get(requestID);
+            if (held == null) {
+                return null;
+            }
+            const rejoined = await registry.readHandle(groupID, async (handle)=>{
+                let groupInfo;
+                try {
+                    groupInfo = await openSealedGroupInfo({
+                        group: handle,
+                        sealed,
+                        requestID,
+                        ephemeralPrivateKey: held.ephemeralPrivateKey
+                    });
+                } catch  {
+                    // Bytes this peer cannot open OR cannot trust. A forgery that merely
+                    // decrypts still fails the membership attestation, and the two are
+                    // indistinguishable to the caller on purpose: neither is a reply.
+                    return null;
+                }
+                return await joinGroupExternal({
+                    identity,
+                    groupInfo,
+                    credential: handle.credential,
+                    resync: true
+                });
+            });
+            if (rejoined == null) {
+                return null;
+            }
+            return {
+                commit: rejoined.commitMessage,
+                // Adopted ONLY once the head accepts the commit. The lane publishes it
+                // under a compare-and-set, and a peer that adopted first would sit on a
+                // branch of its own the moment it lost that race.
+                onAccepted: async ()=>{
+                    pending.delete(requestID);
+                    await registry.replaceHandle(groupID, rejoined.group, {
+                        stores
+                    });
+                }
+            };
+        },
+        /**
+     * Whether the entries this handle holds fold to the head its own GroupContext
+     * attests to. Purely local, read-only: the completeness gate every lane
+     * operation runs before it pulls or commits. False means the handle rejoined
+     * with an empty ledger against a live head and must bootstrap before it can be
+     * trusted to judge a commit.
+     */ async isLedgerComplete () {
+            return await registry.readHandle(groupID, (handle)=>handle.isLedgerComplete());
+        },
+        /**
+     * The whole ordered ledger this handle holds, as signed tokens. Purely local,
+     * read-only. Order is load-bearing: the head is a chain digest, so a permuted
+     * list folds to a different head.
+     */ async getLedger () {
+            return await registry.readHandle(groupID, (handle)=>handle.getLedger());
+        },
+        /**
+     * Answer another member's ledger gather: seal this handle's whole ordered
+     * ledger to the ephemeral key inside the requester's signed request.
+     *
+     * Authorization is roster-intrinsic: the primitive refuses a requester with no
+     * leaf in THIS handle's tree, which matters because the ledger is the group's
+     * entire authority state travelling on a public, secretless topic. A throw
+     * means "stay silent" to group-rpc.
+     *
+     * The payload is read from the handle and never handed in, so this cannot be
+     * made to seal another group's state.
+     */ async sealLedger (request) {
+            return await registry.readHandle(groupID, (handle)=>sealLedger({
+                    group: handle,
+                    request: new TextDecoder().decode(request)
+                }));
+        },
+        /**
+     * Open a sealed gather reply with the key minted for `requestID`.
+     *
+     * Wired now: it reads the ephemeral private key
+     * {@link GroupMLS.createRecoveryRequest} retains under that id in `pending`.
+     * It moves with that member, not with {@link GroupMLS.sealLedger} — the
+     * responder side needs only the handle and the request, so both are now live
+     * on the same custody the requester side holds.
+     */ async openSealedLedger (sealed, requestID) {
+            const held = pending.get(requestID);
+            if (held == null) {
+                return null;
+            }
+            return await registry.readHandle(groupID, async (handle)=>{
+                try {
+                    // The key is NOT consumed here: every responder to a gather answers,
+                    // and the requester must still be able to open the next reply after
+                    // discarding one it could not use.
+                    return await openSealedLedger({
+                        group: handle,
+                        sealed,
+                        requestID,
+                        ephemeralPrivateKey: held.ephemeralPrivateKey
+                    });
+                } catch  {
+                    return null;
+                }
+            });
+        },
+        /**
+     * Install a gathered ledger, replacing what this handle holds once the list
+     * reproduces the head the handle's own GroupContext authenticates.
+     *
+     * The install runs FIRST: a list that does not reproduce the authenticated head
+     * throws before a durable row is touched, so a withholding responder is
+     * rejected whole rather than merged. Only then does kubun's mirror follow.
+     *
+     * Deliberately NOT in a transaction — one spanning this would hold kubun's
+     * single SQLite connection across an unbounded network wait. Safe because
+     * nothing is written until the head check passes, and this REPLACES a ledger
+     * rather than appending, so the next bootstrap heals a stale mirror.
+     */ async bootstrapLedger (tokens) {
+            const p2pStore = await getP2PStore(stores);
+            await bootstrapGroupLedger({
+                p2pStore,
+                // Only the projection rebuild is transactional — never the install
+                // above it, which waits on the network.
+                withProjectionTransaction: (run)=>stores.withTransaction(async (tx)=>await run(await getP2PStore(tx))),
+                hlc,
+                getGroupAnchor: (id)=>registry.readHandle(id, async (handle)=>readGroupAnchor(handle)),
+                getGroupLedger: (id)=>registry.readHandle(id, async (handle)=>handle.ledger),
+                logger,
+                installGroupLedger: async (id, gathered)=>await registry.withHandle(id, async (handle)=>{
+                        await handle.bootstrapLedger(gathered);
+                        // Read under the same hold as the install: this is the roster that
+                        // install folded, not whatever a later operation may have left.
+                        return handle.roster;
+                    })
+            }, tokens, groupID);
+        },
+        /**
+     * The epoch-independent secret for the non-rotating handshake/recovery topic,
+     * sourced from the genesis anchor (immutable, authenticated by the GroupInfo
+     * signature → every member on every epoch reads the same value). Throws when
+     * the anchor is absent: a group with no anchor cannot participate in recovery.
+     */ async exportRecoverySecret () {
+            const anchor = await registry.readHandle(groupID, (handle)=>readGroupAnchor(handle));
+            if (anchor == null) {
+                throw new Error(`group ${groupID} has no genesis anchor; cannot derive recovery secret`);
+            }
+            return fromB64(readRecoverySecret(anchor));
+        }
+    };
+}