@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/groups/group-handlers.js

@@ -1,6 +1,35 @@
-import { isSignedToken } from '@kokuin/token';
+import { signAccessDefaultSet } from './access-default-token.js';
 import { processBroadcast } from './broadcast.js';
-import { emitLedgerAffectedEvents } from './ledger-affected-events.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.
  *
@@ -33,19 +62,6 @@ import { emitLedgerAffectedEvents } from './ledger-affected-events.js';
             // 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/ledgerEntry': ({ data })=>safeApply(async ()=>{
-                    // A remote-applied ledger entry returns its circle/group projection row
-                    // as `affected` rather than emitting; surface the matching local events
-                    // so this receiver's GraphQL subscribers see the change live.
-                    const result = await processBroadcast(params, {
-                        type: 'ledger:entry',
-                        groupID,
-                        token: data.token
-                    }, groupID);
-                    if (params.emitter != null) {
-                        await emitLedgerAffectedEvents(params.emitter, result);
-                    }
-                }),
             'control/delegationShare': ({ data })=>safeApply(()=>processBroadcast(params, {
                         type: 'delegation:share',
                         token: data.token,
@@ -58,34 +74,144 @@ import { emitLedgerAffectedEvents } from './ledger-affected-events.js';
                         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 ()=>{
-                // Untrusted responder: hand back every stored signed entry token. The
-                // requester re-verifies each one independently, so authority lives in the
-                // token, not in this reply.
-                const rows = await params.p2pStore.getLedgerEntries(groupID);
+                // 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: rows.map((row)=>row.signed_token)
+                    entries: ledger.map((held)=>held.token)
                 };
             }
         },
         sync: {
-            'sync/mutationApply': ({ data, message })=>{
-                // The authenticated transport sender is the signed frame's issuer. It is
-                // only a belt-and-suspenders loopback guard — the hub already fans a
-                // publish to subscribers minus the sender, so a peer never receives its
-                // own broadcast. An unsigned frame yields '' (harmless: no self-match).
-                const senderPeerDID = isSignedToken(message) ? message.payload.iss : '';
-                return safeApply(()=>processBroadcast(params, {
+            'sync/mutationApply': ({ data, message })=>safeApply(()=>processBroadcast(params, {
                         type: 'mutation:apply',
                         entries: data.entries,
-                        senderPeerDID
-                    }, groupID));
+                        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

@@ -18,7 +18,7 @@ export type GroupHealthMonitorParams = {
  * 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/welcome-based-deep-recovery.md. Kept (not deleted)
+ * 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

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

@@ -5,7 +5,7 @@ const DEFAULT_EPOCH_STALE_THRESHOLD = 3;
  * 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/welcome-based-deep-recovery.md. Kept (not deleted)
+ * 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

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

@@ -1,11 +1,26 @@
+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)
@@ -22,14 +37,30 @@ export type CreateGroupMLSParams = {
      */
     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,
- * export GroupInfo for a recovery responder, 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.
+ * 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;