@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/groups/group-protocols.js

@@ -14,26 +14,40 @@ import { defineGroupProtocol } from '@kumiai/rpc';
  * self-authenticating at the payload level (signed tokens / HLC-stamped
  * records), so the lane provides ordering + delivery, not authorization.
  */ export const controlProtocol = defineGroupProtocol({
-    'control/ledgerEntry': {
-        type: 'event',
-        description: 'A self-signed control-ledger entry appended by its author.',
-        data: {
+    'control/ledgerCatchup': {
+        type: 'request',
+        retain: 'ephemeral',
+        description: 'Ask current members for the group control ledger to backfill missed entries. Gathered: each member replies with its entries; the requester re-verifies every token.',
+        param: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        result: {
             type: 'object',
             properties: {
-                token: {
-                    type: 'string',
-                    description: 'Signed control-ledger entry token.'
+                entries: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'Signed control-ledger entry tokens.'
                 }
             },
             required: [
-                'token'
+                'entries'
             ],
             additionalProperties: false
         }
     },
-    'control/ledgerCatchup': {
+    'control/policyCatchup': {
         type: 'request',
-        description: 'Ask current members for the group control ledger to backfill missed entries. Gathered: each member replies with its entries; the requester re-verifies every token.',
+        // Nothing kept: the reply is a snapshot of what each responder's rules are
+        // right now, and one that outlived its window would be answering for a
+        // policy that may since have been rewritten. The durable half of this lane
+        // is `control/accessDefaultSet`, which this repairs rather than replaces.
+        retain: 'ephemeral',
+        description: 'Ask current members to restate their OWN model access-defaults, for a member whose read position fell below the hub retention floor and can no longer read the frames that carried them. Gathered: each member replies with signed tokens for its own rules; the requester verifies every token and applies it under the same sender-bound LWW rules as a live frame.',
         param: {
             type: 'object',
             properties: {},
@@ -42,22 +56,23 @@ import { defineGroupProtocol } from '@kumiai/rpc';
         result: {
             type: 'object',
             properties: {
-                entries: {
+                defaults: {
                     type: 'array',
                     items: {
                         type: 'string'
                     },
-                    description: 'Signed control-ledger entry tokens.'
+                    description: 'Signed access-default set tokens, one per rule the responder owns.'
                 }
             },
             required: [
-                'entries'
+                'defaults'
             ],
             additionalProperties: false
         }
     },
     'control/delegationShare': {
         type: 'event',
+        retain: 'log',
         description: 'Distribute a minted document/write capability token to group co-members.',
         data: {
             type: 'object',
@@ -80,6 +95,7 @@ import { defineGroupProtocol } from '@kumiai/rpc';
     },
     'control/delegationRevoke': {
         type: 'event',
+        retain: 'log',
         description: 'Distribute a signed revocation record for a previously minted capability.',
         data: {
             type: 'object',
@@ -100,8 +116,142 @@ import { defineGroupProtocol } from '@kumiai/rpc';
             additionalProperties: false
         }
     },
+    'control/accessDefaultSet': {
+        type: 'event',
+        // Durable policy, not a notification: a member offline while the owner
+        // rewrites its sharing rule must learn it on return, or it keeps serving
+        // that owner's documents under a rule the owner replaced. Retained like the
+        // delegation frames, and for the same reason.
+        retain: 'log',
+        description: "Distribute a member's own model access-default to co-members. `auth` is the signed statement; every other field mirrors it so the receiver can rebuild the frame before verifying.",
+        data: {
+            type: 'object',
+            properties: {
+                modelID: {
+                    type: 'string'
+                },
+                permissionType: {
+                    type: 'string',
+                    enum: [
+                        'read',
+                        'write'
+                    ]
+                },
+                rule: {
+                    type: 'object',
+                    properties: {
+                        level: {
+                            type: 'string'
+                        },
+                        allowedDIDs: {
+                            type: [
+                                'array',
+                                'null'
+                            ],
+                            items: {
+                                type: 'string'
+                            }
+                        },
+                        allowedCircles: {
+                            type: [
+                                'array',
+                                'null'
+                            ],
+                            items: {
+                                type: 'string'
+                            }
+                        },
+                        allowedGroups: {
+                            type: [
+                                'array',
+                                'null'
+                            ],
+                            items: {
+                                type: 'string'
+                            }
+                        }
+                    },
+                    required: [
+                        'level',
+                        'allowedDIDs',
+                        'allowedCircles',
+                        'allowedGroups'
+                    ],
+                    additionalProperties: false
+                },
+                ownerDID: {
+                    type: 'string',
+                    description: 'Claimed owner; checked against the `auth` issuer.'
+                },
+                hlc: {
+                    type: 'string',
+                    description: 'Owner-stamped LWW anchor, mirroring the stored row.'
+                },
+                auth: {
+                    type: 'string',
+                    description: 'Signed access-default token.'
+                }
+            },
+            required: [
+                'modelID',
+                'permissionType',
+                'rule',
+                'ownerDID',
+                'hlc',
+                'auth'
+            ],
+            additionalProperties: false
+        }
+    },
+    'control/accessDefaultRemove': {
+        type: 'event',
+        // Same retention as the set, and load-bearing in the other direction: an
+        // ephemeral removal would distribute every widening and swallow the
+        // narrowings, leaving an absent member serving under a withdrawn rule.
+        retain: 'log',
+        description: "Distribute a member's own model access-default removal to co-members.",
+        data: {
+            type: 'object',
+            properties: {
+                modelID: {
+                    type: 'string'
+                },
+                permissionTypes: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                        enum: [
+                            'read',
+                            'write'
+                        ]
+                    }
+                },
+                ownerDID: {
+                    type: 'string',
+                    description: 'Claimed owner; checked against the `auth` issuer.'
+                },
+                hlc: {
+                    type: 'string',
+                    description: 'Owner-stamped LWW anchor for the removal.'
+                },
+                auth: {
+                    type: 'string',
+                    description: 'Signed access-default removal token.'
+                }
+            },
+            required: [
+                'modelID',
+                'permissionTypes',
+                'ownerDID',
+                'hlc',
+                'auth'
+            ],
+            additionalProperties: false
+        }
+    },
     'control/groupLeaveRequest': {
         type: 'event',
+        retain: 'ephemeral',
         description: 'Advisory voluntary-leave notice. Not authoritative — an admin must issue a real removeMember; receivers surface it as an event and never tombstone on it.',
         data: {
             type: 'object',
@@ -128,6 +278,7 @@ import { defineGroupProtocol } from '@kumiai/rpc';
  */ export const syncProtocol = defineGroupProtocol({
     'sync/mutationApply': {
         type: 'event',
+        retain: 'ephemeral',
         description: 'Broadcast a batch of signed document mutations to group members.',
         data: {
             type: 'object',
@@ -168,7 +319,130 @@ import { defineGroupProtocol } from '@kumiai/rpc';
         }
     }
 });
-/** The two app-lane protocols, keyed for `createGroupPeer({ protocols })`. */ export const groupProtocols = {
+/**
+ * Peer plane: what each device advertises about itself to its co-members. Its
+ * own protocol rather than a third control procedure, so its traffic and
+ * retention floor stay independent of the control ledger's — the topic derives
+ * per protocol NAME (`protocolTopic(secret, epoch, name)`), so a new name can
+ * only add a lane.
+ *
+ * ATTRIBUTION IS THE LANE'S, NOT THE BODY'S: `peer/announce` carries no DID
+ * field and the receiver keys the row on `message.payload.iss`, the
+ * MLS-authenticated sender. A convenience `peerDID` in the body would let any
+ * member write any other member's row — a defect this project has shipped once.
+ */ /**
+ * What a device says about itself. ONE schema object, used as `peer/announce`'s
+ * body and as `peer/query`'s result: a query reply IS an announcement, delivered
+ * on demand, and two schemas that happen to agree today would drift the first
+ * time one of them gained a field.
+ */ const peerAnnouncementBody = {
+    type: 'object',
+    properties: {
+        label: {
+            type: 'string',
+            description: 'Self-declared display hint, Bluetooth-style. Rendered beside the DID, never read as an identity.'
+        },
+        availability: {
+            type: 'string',
+            enum: [
+                'always-on',
+                'interactive',
+                'mobile'
+            ],
+            description: 'Steers automatic selection only; it never refuses to serve.'
+        },
+        capabilities: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    protocol: {
+                        type: 'string'
+                    },
+                    version: {
+                        type: 'number'
+                    },
+                    transports: {
+                        type: [
+                            'array',
+                            'null'
+                        ],
+                        items: {
+                            type: 'string'
+                        },
+                        description: 'Addressing hints for a capability the hub tunnel does not already reach. Null for one it does.'
+                    }
+                },
+                // Nullable-and-required rather than optional, as the access-default
+                // rule's arms are: an absent key and an explicit null would otherwise
+                // be two encodings of one fact, and only one of them round-trips.
+                required: [
+                    'protocol',
+                    'version',
+                    'transports'
+                ],
+                additionalProperties: false
+            },
+            description: 'Matched EXACTLY on protocol AND version.'
+        },
+        hlc: {
+            type: 'string',
+            description: 'Announcer-stamped LWW anchor for its own projection row.'
+        }
+    },
+    required: [
+        'label',
+        'availability',
+        'capabilities',
+        'hlc'
+    ],
+    additionalProperties: false
+};
+export const peerProtocol = defineGroupProtocol({
+    'peer/announce': {
+        type: 'event',
+        // Durable state, not a notification. A device that was offline (or was added
+        // at a later epoch, and so was never on the old topic) has no other way to
+        // learn who else is reachable: the projection is the source of truth and this
+        // lane is what fills it.
+        retain: 'log',
+        description: 'Advertise this device to its co-members: display label, availability class, and the exact capabilities it answers on. The announcer is taken from the authenticated sender, so the body names nobody.',
+        data: peerAnnouncementBody
+    },
+    'peer/query': {
+        type: 'request',
+        // Liveness, so nothing is kept: a reply that outlived its window would be
+        // answering a question nobody is still asking, and the durable half of this
+        // lane is `peer/announce`.
+        retain: 'ephemeral',
+        description: 'Ask who is reachable right now, optionally narrowed to devices answering named protocols. Gathered: every matching device replies with its own advertisement within the window. A result is "who answered", never "who exists".',
+        param: {
+            type: 'object',
+            properties: {
+                protocols: {
+                    type: [
+                        'array',
+                        'null'
+                    ],
+                    items: {
+                        type: 'string'
+                    },
+                    description: "Only devices answering one of these reply. Null means any. Nullable-and-required, as the announce body's `transports` is."
+                }
+            },
+            required: [
+                'protocols'
+            ],
+            additionalProperties: false
+        },
+        result: peerAnnouncementBody
+    }
+});
+/**
+ * The app-lane protocols, keyed for `createGroupPeer({ protocols })`. Each key
+ * names its own topic, so adding one moves no existing lane.
+ */ export const groupProtocols = {
     control: controlProtocol,
-    sync: syncProtocol
+    sync: syncProtocol,
+    peer: peerProtocol
 };

package/lib/groups/invite-payload.d.ts

@@ -1,4 +1,36 @@
+import type { CatalogRecord } from '@kubun/protocol';
 import type { Invite, KeyPackageBundle } from '@kumiai/mls';
+import type { AccessDefaultRule } from './access-default-token.js';
+/**
+ * The inviter's own model access-default, carried as a self-authenticating seed
+ * so the joiner holds it before any broadcast arrives. `auth` is a token signed
+ * by the owner; the joiner derives the authoritative fields from it and applies
+ * the rule only when `ownerDID` equals the verified issuer (sender-bound), LWW
+ * by `hlc`. Mirrors the `access-default:set` broadcast frame minus the `type`.
+ */
+export type InviteAccessDefault = {
+    ownerDID: string;
+    modelID: string;
+    permissionType: 'read' | 'write';
+    rule: AccessDefaultRule;
+    hlc: string;
+    auth: string;
+};
+/**
+ * A group catalog seeded into a joiner, tagged with the circle whose
+ * `catalog_ids` referenced it. `token` is the creator's original signed
+ * `catalog:set` token, forwarded verbatim: the joiner re-verifies it with the
+ * same helper the broadcast receive path uses (creator-binding `ownerDID ===
+ * iss`, payload matches the signed record) before storing anything, so an
+ * inviter cannot inject a spoofed catalog. The joiner stores it as a KNOWN (not
+ * active) catalog with provenance `source_group_id` = the joined group and
+ * `source_circle_id` = this circle — activation stays an explicit local decision.
+ */
+export type InviteCatalogSeed = {
+    catalog: CatalogRecord;
+    sourceCircleID: string;
+    token: string;
+};
 export type JoinRequestPayload = {
     did: string;
     publicPackage: KeyPackageBundle['publicPackage'];
@@ -35,6 +67,22 @@ export type InvitePayload = {
      * against any caps it already holds.
      */
     revocations?: Array<string>;
+    /**
+     * The inviter's OWN model access-default rows, each carrying a token signed by
+     * the inviter. Applied sender-bound (owner must equal the token issuer) and
+     * LWW by HLC at join, so a third-party row a malicious inviter tries to inject
+     * cannot be signed and is dropped.
+     */
+    accessDefaults?: Array<InviteAccessDefault>;
+    /**
+     * The group's catalog records (those referenced by the group's circles), each
+     * tagged with the referencing circle. Stored as KNOWN (not active) catalogs at
+     * join — discovery applies no sync, so activation stays an explicit local
+     * decision. Carried as plain records: catalogs are sync-scope hints, not
+     * authorization, so they are trusted from the inviter like `groupName` and
+     * `suggestedHubs` rather than individually signed.
+     */
+    catalogs?: Array<InviteCatalogSeed>;
 };
 export declare function encodeJoinRequest(payload: JoinRequestPayload): string;
 export declare function decodeJoinRequest(encoded: string): JoinRequestPayload;

package/lib/groups/join-request-identity.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The DID of the device that authored a join request.
+ *
+ * Read from the MLS credential inside the KeyPackage, which the leaf signature
+ * covers; NEVER from the payload's sibling `did` field, which its author writes
+ * freely. Those two are one identity claim written in two places, so a
+ * disagreement REFUSES — resolving it in either direction would pick a winner
+ * silently.
+ *
+ * Every path that mints an invite resolves the recipient through here, because
+ * the mint hands the two halves to different subsystems: the KeyPackage becomes
+ * an MLS leaf and the DID becomes a membership row and a role entry. Taking the
+ * DID from the payload lets a forged pairing put those two names out of step —
+ * a leaf for one identity, an authenticated membership row for another — and no
+ * later fold reconciles them, because each side is doing exactly what it was
+ * told.
+ *
+ * An envelope-bound caller can additionally compare the result against the DID
+ * that signed the request, which is a check this function cannot make.
+ */
+export declare function resolveJoinRequestDID(joinRequest: string): string;

package/lib/groups/join-request-identity.js

@@ -0,0 +1,43 @@
+import { normalizeDID } from '@kokuin/token';
+import { parseMLSCredentialIdentity } from '@kumiai/mls';
+import { GraphQLError } from 'graphql';
+import { defaultCredentialTypes, isDefaultCredential } from 'ts-mls';
+import { decodeJoinRequest } from './invite-payload.js';
+/**
+ * The DID of the device that authored a join request.
+ *
+ * Read from the MLS credential inside the KeyPackage, which the leaf signature
+ * covers; NEVER from the payload's sibling `did` field, which its author writes
+ * freely. Those two are one identity claim written in two places, so a
+ * disagreement REFUSES — resolving it in either direction would pick a winner
+ * silently.
+ *
+ * Every path that mints an invite resolves the recipient through here, because
+ * the mint hands the two halves to different subsystems: the KeyPackage becomes
+ * an MLS leaf and the DID becomes a membership row and a role entry. Taking the
+ * DID from the payload lets a forged pairing put those two names out of step —
+ * a leaf for one identity, an authenticated membership row for another — and no
+ * later fold reconciles them, because each side is doing exactly what it was
+ * told.
+ *
+ * An envelope-bound caller can additionally compare the result against the DID
+ * that signed the request, which is a check this function cannot make.
+ */ export function resolveJoinRequestDID(joinRequest) {
+    const decoded = decodeJoinRequest(joinRequest);
+    const credential = decoded.publicPackage.leafNode.credential;
+    // Only a basic credential carries an `identity` at all — x509 carries
+    // certificates and a custom one opaque bytes — so a non-basic credential binds
+    // no DID. Refused rather than coerced back onto the payload field.
+    if (!isDefaultCredential(credential) || credential.credentialType !== defaultCredentialTypes.basic) {
+        throw new GraphQLError(`the join request carries a non-basic MLS credential (type ${credential.credentialType}), which binds no identity`);
+    }
+    const credentialDID = parseMLSCredentialIdentity(credential.identity).id;
+    if (credentialDID === '') {
+        throw new GraphQLError('the join request credential carries no identity');
+    }
+    const payloadDID = typeof decoded.did === 'string' ? decoded.did : null;
+    if (payloadDID == null || normalizeDID(payloadDID) !== normalizeDID(credentialDID)) {
+        throw new GraphQLError(`the join request's did field (${String(payloadDID)}) disagrees with its KeyPackage credential (${credentialDID})`);
+    }
+    return credentialDID;
+}

package/lib/groups/join-utils.d.ts

@@ -1,8 +1,11 @@
+import { type OwnIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import type { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
+import type { GroupAnchor, LedgerLogEntry } from '@kumiai/mls';
 import type { GroupData } from '../types.js';
 import type { P2PEventEmitter } from './events.js';
+import type { InviteAccessDefault, InviteCatalogSeed } from './invite-payload.js';
 export type FinalizeJoinedGroupParams = {
     stores: StoreProvider;
     emitter: P2PEventEmitter;
@@ -78,3 +81,60 @@ export type ApplyInviteRevocationsParams = {
  * Returns the number of revocations that resulted in a stored row.
  */
 export declare function applyInviteRevocations(params: ApplyInviteRevocationsParams): Promise<number>;
+/**
+ * The group's control state an invite carries so a joiner is current at join.
+ *
+ * NOT the control ledger. That travels on the invite `@kumiai/mls` builds, as
+ * the list its own head check is computed over — a second copy assembled here
+ * could only agree with it or corrupt it.
+ */
+export type InviteControlSeeds = {
+    accessDefaults: Array<InviteAccessDefault>;
+    catalogs: Array<InviteCatalogSeed>;
+};
+export type CollectInviteSeedsParams = {
+    stores: StoreProvider;
+    /** Inviter identity — signs the access-default seeds so they self-authenticate. */
+    identity: OwnIdentity;
+    /** Owner DID whose model access-defaults are seeded (the inviter). */
+    ownerDID: string;
+    groupID: string;
+    logger?: Logger;
+};
+/**
+ * Gather the group state an invite seeds into the joiner: the inviter's own
+ * model access-defaults (each signed so it self-authenticates), and the catalogs
+ * the group's circles reference. Access-default rows without an HLC anchor are
+ * skipped — they carry no LWW ordering and cannot be authenticated for
+ * replication.
+ */
+export declare function collectInviteSeeds(params: CollectInviteSeedsParams): Promise<InviteControlSeeds>;
+export type ApplyInviteControlStateParams = {
+    stores: StoreProvider;
+    groupID: string;
+    accessDefaults?: Array<InviteAccessDefault>;
+    catalogs?: Array<InviteCatalogSeed>;
+    /** Device-wide clock — the joined ledger's HLCs merge into it. */
+    hlc: HLC;
+    /** Resolves the group's genesis anchor so ledger entries can project at join. */
+    getGroupAnchor?: (groupID: string) => Promise<GroupAnchor | null>;
+    /** Resolves the group's control ledger, which every projection folds from. */
+    getGroupLedger?: (groupID: string) => Promise<ReadonlyArray<LedgerLogEntry>>;
+    logger?: Logger;
+};
+/**
+ * Apply the control state a join produced, after the MLS join completes.
+ *
+ * The control ledger is NOT among the parameters, deliberately: it arrived on
+ * the MLS invite and `processWelcome` has already checked it against the
+ * authenticated head and folded it into the handle, which is what every
+ * projection reads. All that is left is to adopt what the handle now holds. A
+ * second copy carried beside it could only agree or disagree, and a joiner has
+ * no way to tell which.
+ *
+ * The rest authenticates independently: access-defaults apply sender-bound + LWW
+ * via their owner-signed tokens, and catalogs upsert as plain sync-scope records
+ * trusted from the inviter. A third-party access-default row is dropped without
+ * blocking the rest.
+ */
+export declare function applyInviteControlState(params: ApplyInviteControlStateParams): Promise<void>;