@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/groups/group-handlers.js

@@ -0,0 +1,218 @@
+import { signAccessDefaultSet } from './access-default-token.js';
+import { processBroadcast } from './broadcast.js';
+/**
+ * Why this device is not answering a `peer/query`.
+ *
+ * Declining is a THROW because that is the only silence the lane offers: the
+ * broadcast responder writes a reply for whatever a handler returns, and the
+ * requester's gather drops replies that carried an error and keeps the rest. So a
+ * decline bounds the RESULT, not the traffic — every member still publishes one
+ * reply frame — and the spec's "only matching devices reply" is true of what a
+ * gather reports, not of what crosses the hub.
+ */ class PeerQueryDeclined extends Error {
+    constructor(reason){
+        super(`peer/query declined: ${reason}`);
+        this.name = 'PeerQueryDeclined';
+    }
+}
+/**
+ * The MLS-authenticated sender of a frame, which group-rpc surfaces at
+ * `message.payload.iss`. It builds that context message itself from the sender
+ * `unwrap` recovered, so `iss` is an authenticated DID and not a transport-claimed
+ * one.
+ *
+ * Absent when the frame opened at a leaf that could not be named. That is
+ * `undefined`, never a sentinel: a placeholder DID would be an identity claim
+ * nothing vouched for, and a guard comparing against it would be comparing
+ * against a value chosen for never matching rather than one meaning "unknown".
+ */ function authenticatedSender(message) {
+    const payload = message.payload;
+    const iss = payload.iss;
+    return typeof iss === 'string' ? iss : undefined;
+}
+/**
+ * Build the control + sync procedure handlers for a single group.
+ *
+ * Each handler is a thin adapter: it maps the typed group-rpc procedure payload
+ * back to the {@link GroupBroadcastMessage} the pure {@link processBroadcast}
+ * apply logic already understands, re-adding the `groupID` the peer is bound to
+ * (group-rpc strips it from the wire because each topic already encodes the
+ * group). The apply logic owns verification, conflict resolution, and storage;
+ * the handler owns only the shape translation.
+ *
+ * Event handlers are fire-and-forget. `processBroadcast` already drops an
+ * unverifiable or malformed payload and returns `{ applied: false }` rather than
+ * throwing, so the result is intentionally ignored. A programmer-error rethrow
+ * (or an unexpected store fault) is caught and logged here so a single bad frame
+ * never escapes as an unhandled rejection out of the receive loop.
+ */ export function buildGroupHandlers(params, groupID) {
+    const safeApply = async (apply)=>{
+        try {
+            await apply();
+        } catch (error) {
+            params.logger?.warn('group handler apply failed', {
+                groupID,
+                error
+            });
+        }
+    };
+    return {
+        control: {
+            // Event handlers return the (never-rejecting) apply promise. The procedure
+            // contract types them `=> void`, so the server ignores the return; returning
+            // the promise is purely so a caller (e.g. a test) that holds the handler
+            // directly can await the apply completing.
+            'control/delegationShare': ({ data })=>safeApply(()=>processBroadcast(params, {
+                        type: 'delegation:share',
+                        token: data.token,
+                        groupID,
+                        hlc: data.hlc
+                    }, groupID)),
+            'control/delegationRevoke': ({ data })=>safeApply(()=>processBroadcast(params, {
+                        type: 'delegation:revoke',
+                        token: data.token,
+                        groupID,
+                        hlc: data.hlc
+                    }, groupID)),
+            // Every field the sender put on the frame is carried back verbatim. The
+            // signature covers the operation, not just the author, so a handler that
+            // filled a field in from context — or dropped one — would hand
+            // `processBroadcast` a frame whose token no longer describes it.
+            'control/accessDefaultSet': ({ data })=>safeApply(()=>processBroadcast(params, {
+                        type: 'access-default:set',
+                        modelID: data.modelID,
+                        permissionType: data.permissionType,
+                        rule: {
+                            level: data.rule.level,
+                            allowedDIDs: data.rule.allowedDIDs,
+                            allowedCircles: data.rule.allowedCircles,
+                            allowedGroups: data.rule.allowedGroups
+                        },
+                        ownerDID: data.ownerDID,
+                        hlc: data.hlc,
+                        auth: data.auth
+                    }, groupID)),
+            'control/accessDefaultRemove': ({ data })=>safeApply(()=>processBroadcast(params, {
+                        type: 'access-default:remove',
+                        modelID: data.modelID,
+                        permissionTypes: data.permissionTypes,
+                        ownerDID: data.ownerDID,
+                        hlc: data.hlc,
+                        auth: data.auth
+                    }, groupID)),
+            'control/groupLeaveRequest': ({ data })=>safeApply(()=>processBroadcast(params, {
+                        type: 'group:leaveRequest',
+                        groupID,
+                        memberDID: data.memberDID,
+                        hlc: data.hlc
+                    }, groupID)),
+            // Restate this device's OWN rules for a member that fell below the hub's
+            // retention floor and can no longer read the frames that carried them.
+            // Signed fresh, but stamped with each row's STORED hlc: the anchor is when
+            // the owner decided the rule, so re-stamping here would let a repair win
+            // an ordering race against a newer rule the requester already holds.
+            'control/policyCatchup': async ()=>{
+                const identity = params.identity;
+                if (identity == null) {
+                    params.logger?.warn('policy catch-up served empty: no signing identity', {
+                        groupID
+                    });
+                    return {
+                        defaults: []
+                    };
+                }
+                const rows = await params.graphStore.listUserModelAccessDefaults(identity.id);
+                const defaults = await Promise.all(rows// An unstamped row cannot be ordered against what the requester
+                // holds, so restating it could only overwrite by luck.
+                .filter((row)=>row.hlc != null).map((row)=>signAccessDefaultSet(identity, {
+                        modelID: row.modelID,
+                        permissionType: row.permissionType,
+                        rule: {
+                            level: row.level,
+                            allowedDIDs: row.allowedDIDs,
+                            allowedCircles: row.allowedCircles,
+                            allowedGroups: row.allowedGroups
+                        },
+                        hlc: row.hlc
+                    })));
+                return {
+                    defaults
+                };
+            },
+            'control/ledgerCatchup': async ()=>{
+                // The whole ledger this device holds, in ENACTMENT order. Order is
+                // load-bearing: the requester checks the list against the authenticated
+                // head, which is a chain digest, so a permuted list folds to a different
+                // head and is rejected. Only the handle's log records that order — the
+                // store's is insertion order, which is why it cannot answer this.
+                //
+                // A device with no ledger reader serves nothing rather than something
+                // unordered: an empty reply fails the requester's head check (unless the
+                // ledger genuinely is empty) and costs it only this responder.
+                if (params.getGroupLedger == null) {
+                    params.logger?.warn('ledger catch-up served empty: no ledger reader', {
+                        groupID
+                    });
+                    return {
+                        entries: []
+                    };
+                }
+                const ledger = await params.getGroupLedger(groupID);
+                return {
+                    entries: ledger.map((held)=>held.token)
+                };
+            }
+        },
+        sync: {
+            'sync/mutationApply': ({ data, message })=>safeApply(()=>processBroadcast(params, {
+                        type: 'mutation:apply',
+                        entries: data.entries,
+                        senderPeerDID: authenticatedSender(message)
+                    }, groupID))
+        },
+        peer: {
+            // The announcer comes from the LANE, never the body — `peer/announce`
+            // carries no DID field, and the projection row is keyed on what arrives
+            // here. Adding a convenience `peerDID` to the body and reading it instead
+            // would let any member write any other member's row.
+            'peer/announce': ({ data, message })=>safeApply(()=>processBroadcast(params, {
+                        type: 'peer:announce',
+                        label: data.label,
+                        availability: data.availability,
+                        capabilities: data.capabilities,
+                        hlc: data.hlc,
+                        announcerDID: authenticatedSender(message)
+                    }, groupID)),
+            // A reply IS an announcement: this device's OWN projection row, read back
+            // verbatim under the stamp it was announced with. So the gathered copy and
+            // the broadcast copy of one announcement are the same row on the receiver,
+            // and a reply cannot become the one path where a body-carried identity
+            // sneaks in — the row holds no DID field to send.
+            'peer/query': async ({ param })=>{
+                const own = await params.p2pStore.getPeerAnnouncement({
+                    groupID,
+                    peerDID: params.selfDID
+                });
+                if (own == null) {
+                    // Never announced in this group, so there is nothing true to say. A
+                    // fabricated reply would put a capability claim on the wire that no
+                    // announcement backs.
+                    throw new PeerQueryDeclined('this device has not announced in this group');
+                }
+                const requested = param.protocols;
+                if (requested != null && !own.capabilities.some((capability)=>requested.includes(capability.protocol))) {
+                    throw new PeerQueryDeclined('no capability matches the requested protocols');
+                }
+                return {
+                    label: own.label,
+                    // Widened by the store column, narrowed back here: the row was written
+                    // from a schema-validated frame (or from this device's own profile,
+                    // validated the same way), so the value is one of the three.
+                    availability: own.availability,
+                    capabilities: own.capabilities,
+                    hlc: own.hlc
+                };
+            }
+        }
+    };
+}

package/lib/groups/group-health-monitor.d.ts

@@ -1,3 +1,4 @@
+import { type Logger } from '@kubun/logger';
 import type { GroupHealthCondition, GroupHealthSnapshot, GroupHealthState } from '../types.js';
 import type { P2PEventEmitter } from './events.js';
 export type GroupHealthMonitorParams = {
@@ -8,8 +9,18 @@ export type GroupHealthMonitorParams = {
     };
     /** Clock for `lastTransitionAt` stamps. Defaults to `Date.now`. */
     now?: () => number;
+    /** Logger for a throwing `groupHealthChanged` subscriber. Defaults to the
+     *  `group-health-monitor` namespace. */
+    logger?: Logger;
 };
 /**
+ * INERT: the mutating producers (`signal`/`reset`/`mark*`) have no live caller,
+ * so `getHealth` always reports `healthy` and `groupHealthChanged` never fires.
+ * This is the front-end of the epoch-stale-recovery feature, deliberately
+ * dormant until tier-2 Welcome re-admission exists — see
+ * docs/agents/plans/backlog/recovery-rendezvous-transport.md. Kept (not deleted)
+ * because that feature is roadmapped and this scaffolding is design-aligned.
+ *
  * Per-group health state machine. Counts/latches failure signals per
  * `(groupID, condition)` and emits `groupHealthChanged` on transitions.
  * Crypto- and persistence-free: callers classify failures before signalling.

package/lib/groups/group-health-monitor.js

@@ -1 +1,139 @@
-export class GroupHealthMonitor{#e;#t;#s;#h=new Map;#a=new Map;constructor(e){this.#e=e.emitter,this.#t=e.epochStale?.threshold??3,this.#s=e.now??Date.now}signal(e,t){let s=this.#r(e,t);"healthy"===s.phase&&(s.count+=1,s.count>=this.#i(t)&&(s.phase="degraded",this.#o(e),this.#l(e,t,"degraded")))}reset(e,t){let s=this.#r(e,t);s.count=0,"healthy"!==s.phase&&(s.phase="healthy",this.#o(e))}markRecovering(e){this.#r(e,"epoch-stale").phase="recovering",this.#o(e),this.#l(e,"epoch-stale","recovering")}markRecovered(e){let t=this.#r(e,"epoch-stale");t.count=0,t.phase="healthy",this.#o(e),this.#l(e,"epoch-stale","recovered")}markRecoveryFailed(e){this.#r(e,"epoch-stale").phase="recovery-failed",this.#o(e),this.#l(e,"epoch-stale","recovery-failed")}getState(e){let t=this.#h.get(e);if(null==t)return"healthy";for(let e of t.values())if("healthy"!==e.phase)return e.phase;return"healthy"}getHealth(e){return{state:this.getState(e),lastTransitionAt:this.#a.get(e)??null}}#o(e){this.#a.set(e,this.#s())}#i(e){return"epoch-stale"===e?this.#t:1/0}#r(e,t){let s=this.#h.get(e);null==s&&(s=new Map,this.#h.set(e,s));let h=s.get(t);return null==h&&(h={phase:"healthy",count:0},s.set(t,h)),h}#l(e,t,s){this.#e.emit("groupHealthChanged",{groupID:e,condition:t,state:s})}}
+import { getKubunLogger } from '@kubun/logger';
+const DEFAULT_EPOCH_STALE_THRESHOLD = 3;
+/**
+ * INERT: the mutating producers (`signal`/`reset`/`mark*`) have no live caller,
+ * so `getHealth` always reports `healthy` and `groupHealthChanged` never fires.
+ * This is the front-end of the epoch-stale-recovery feature, deliberately
+ * dormant until tier-2 Welcome re-admission exists — see
+ * docs/agents/plans/backlog/recovery-rendezvous-transport.md. Kept (not deleted)
+ * because that feature is roadmapped and this scaffolding is design-aligned.
+ *
+ * Per-group health state machine. Counts/latches failure signals per
+ * `(groupID, condition)` and emits `groupHealthChanged` on transitions.
+ * Crypto- and persistence-free: callers classify failures before signalling.
+ *
+ * State is in-memory per-process — a restart re-derives it from the next signal.
+ * Transitions are synchronous (no `await`), so calls cannot interleave; signals
+ * arriving while a rejoin is in flight (`recovering`) are ignored — the recovery
+ * owns the group until it resolves.
+ */ export class GroupHealthMonitor {
+    #emitter;
+    #epochStaleThreshold;
+    #now;
+    #logger;
+    // groupID -> condition -> per-condition state
+    #groups = new Map();
+    // groupID -> epoch ms of the last transition affecting its aggregate state
+    #lastTransitionAt = new Map();
+    constructor(params){
+        this.#emitter = params.emitter;
+        this.#epochStaleThreshold = params.epochStale?.threshold ?? DEFAULT_EPOCH_STALE_THRESHOLD;
+        this.#now = params.now ?? Date.now;
+        this.#logger = params.logger ?? getKubunLogger('group-health-monitor');
+    }
+    /**
+   * Record a failure observation for a condition. Below the condition's
+   * threshold this only increments the counter; on reaching it the group
+   * transitions to `degraded` (emitted once, then latched). Ignored while the
+   * group is `recovering` (the rejoin owns it) or already `degraded`/failed.
+   */ signal(groupID, condition) {
+        const state = this.#ensure(groupID, condition);
+        if (state.phase !== 'healthy') {
+            // non-healthy: further failures are expected, don't re-emit.
+            return;
+        }
+        state.count += 1;
+        if (state.count >= this.#thresholdFor(condition)) {
+            state.phase = 'degraded';
+            this.#stamp(groupID);
+            this.#emit(groupID, condition, 'degraded');
+        }
+    }
+    /**
+   * Clear a condition to healthy and re-arm (counter reset), driven by the
+   * success path. Silent: only recovery (via the mark* methods) is surfaced.
+   */ reset(groupID, condition) {
+        const state = this.#ensure(groupID, condition);
+        state.count = 0;
+        if (state.phase !== 'healthy') {
+            state.phase = 'healthy';
+            this.#stamp(groupID);
+        }
+    }
+    markRecovering(groupID) {
+        const state = this.#ensure(groupID, 'epoch-stale');
+        state.phase = 'recovering';
+        this.#stamp(groupID);
+        this.#emit(groupID, 'epoch-stale', 'recovering');
+    }
+    /** Emit the transient `recovered` event, then settle the phase to `healthy`. */ markRecovered(groupID) {
+        const state = this.#ensure(groupID, 'epoch-stale');
+        state.count = 0;
+        state.phase = 'healthy';
+        this.#stamp(groupID);
+        this.#emit(groupID, 'epoch-stale', 'recovered');
+    }
+    /** Leave the group `recovery-failed` until a later success resets it. */ markRecoveryFailed(groupID) {
+        const state = this.#ensure(groupID, 'epoch-stale');
+        state.phase = 'recovery-failed';
+        this.#stamp(groupID);
+        this.#emit(groupID, 'epoch-stale', 'recovery-failed');
+    }
+    /** Aggregate state: the first non-healthy condition phase, else `healthy`. */ getState(groupID) {
+        const conditions = this.#groups.get(groupID);
+        if (conditions == null) {
+            return 'healthy';
+        }
+        for (const state of conditions.values()){
+            if (state.phase !== 'healthy') {
+                return state.phase;
+            }
+        }
+        return 'healthy';
+    }
+    getHealth(groupID) {
+        return {
+            state: this.getState(groupID),
+            lastTransitionAt: this.#lastTransitionAt.get(groupID) ?? null
+        };
+    }
+    #stamp(groupID) {
+        this.#lastTransitionAt.set(groupID, this.#now());
+    }
+    #thresholdFor(condition) {
+        // Only `epoch-stale` exists today; switch when more conditions land.
+        return condition === 'epoch-stale' ? this.#epochStaleThreshold : Number.POSITIVE_INFINITY;
+    }
+    #ensure(groupID, condition) {
+        let conditions = this.#groups.get(groupID);
+        if (conditions == null) {
+            conditions = new Map();
+            this.#groups.set(groupID, conditions);
+        }
+        let state = conditions.get(condition);
+        if (state == null) {
+            state = {
+                phase: 'healthy',
+                count: 0
+            };
+            conditions.set(condition, state);
+        }
+        return state;
+    }
+    #emit(groupID, condition, state) {
+        // Enkaku's `emit` rethrows a throwing subscriber; catch so it can't leak an
+        // unhandled rejection.
+        this.#emitter.emit('groupHealthChanged', {
+            groupID,
+            condition,
+            state
+        }).catch((error)=>{
+            this.#logger.error('groupHealthChanged listener failed', {
+                groupID,
+                condition,
+                state,
+                error
+            });
+        });
+    }
+}

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

@@ -0,0 +1,66 @@
+import { type OwnIdentity } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import { HLC } from '@kubun/hlc';
+import { type Logger } from '@kubun/logger';
+import type { GroupMLS } from '@kumiai/rpc';
+import type { P2PEventEmitter } from './events.js';
+import type { GroupHandleRegistry } from './group-handle-registry.js';
+export type CreateGroupMLSParams = {
+    /** Single canonical access point for the device's MLS `GroupHandle`. */
+    registry: GroupHandleRegistry;
+    /**
+     * The device's own signing identity. The recovery members sign under it — the
+     * request token, the membership attestation on a sealed reply, and the
+     * external commit that rejoins — and the commit-apply path reads its DID to
+     * recognise a removal that names THIS device.
+     *
+     * Held rather than passed per call, which departs from how the rest of this
+     * package takes an identity ({@link GroupManager}'s methods each receive one
+     * from the request that drove them). Recovery has no such request: the lane
+     * mints a gather on its own, off a drain that no user mutation is waiting on,
+     * so there is no caller to take the key from at the moment it is needed.
+     */
+    identity: OwnIdentity;
+    /**
+     * Store coordinator used to open the receive-side commit transaction so the
+     * MLS ratchet advance and the roster delta writes commit (or roll back)
+     * together. Without one transaction, a roster-write failure after the ratchet
+     * persists would silently keep a removed member's writes applying.
+     */
+    stores: StoreProvider;
+    /**
+     * Device-wide monotonic clock for stamping the `removed_at_hlc` of members
+     * dropped (and the `hlc` of members added) by a received MLS Commit. Pass the
+     * engine's single instance so every write from this device advances one shared
+     * clock, preventing two same-millisecond writes from minting identical
+     * timestamps (the second would silently lose under last-writer-wins).
+     */
+    hlc: HLC;
+    groupID: string;
+    /**
+     * Emitter for the domain events a landed commit's control entries drive
+     * (circle created/changed/deleted, circle membership, group settings) — the
+     * same events a broadcast-delivered entry fires. Optional: a caller that
+     * never surfaces those changes to subscribers (and existing tests) omits it
+     * and the fold still writes the projections.
+     */
+    emitter?: P2PEventEmitter;
+    logger?: Logger;
+};
+/**
+ * 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 declare function createGroupMLS(params: CreateGroupMLSParams): GroupMLS;