@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/groups/broadcast.d.ts

@@ -1,11 +1,14 @@
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
+import { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
-import type { CatalogRecord, CircleMemberRecord, CircleRecord } from '@kubun/protocol';
-import type { Catalog, GraphStoreAPI } from '@kubun/store-graph';
+import type { CatalogRecord } from '@kubun/protocol';
+import type { DelegationStoreAPI } from '@kubun/store-delegation';
+import type { GraphStoreAPI } from '@kubun/store-graph';
 import type { Circle, CircleMember, Group, P2PStoreAPI } from '@kubun/store-p2p';
 import { type ForwardingConfig } from '../sync/forwarder.js';
 import type { StoreUnreadableMode } from '../types.js';
 import type { P2PEventEmitter } from './events.js';
+import type { GroupAnchor } from './group-anchor.js';
 export type MutationApplyEntry = {
     mutationJWT: string;
     docID: string;
@@ -13,33 +16,18 @@ export type MutationApplyEntry = {
     version: string;
     modelID: string;
 };
+/**
+ * Optional signed token over a control operation. Its issuer (`iss`) is the
+ * authenticated author; receivers verify it and authorize that author as a
+ * group admin, dropping the operation when the token is absent or invalid. The
+ * signed payload is the whole message minus this field, so the signature covers
+ * every operation field, not just the author.
+ */
+type ControlAuth = string;
 export type GroupBroadcastMessage = {
-    type: 'circle:create';
-    circle: CircleRecord;
-} | {
-    type: 'circle:update';
-    circleID: string;
-    update: {
-        name?: string;
-        description?: string;
-        catalogIDs?: Array<string>;
-        hlc: string;
-    };
-} | {
-    type: 'circle:delete';
-    circleID: string;
-    hlc: string;
-} | {
-    type: 'member:add';
-    member: CircleMemberRecord;
-} | {
-    type: 'member:remove';
-    circleID: string;
-    memberDID: string;
-    hlc: string;
-} | {
     type: 'catalog:create';
     catalog: CatalogRecord;
+    auth?: ControlAuth;
 } | {
     type: 'catalog:update';
     catalogID: string;
@@ -49,10 +37,12 @@ export type GroupBroadcastMessage = {
         filterCriteria?: CatalogRecord['filterCriteria'];
         hlc: string;
     };
+    auth?: ControlAuth;
 } | {
     type: 'catalog:delete';
     catalogID: string;
     hlc: string;
+    auth?: ControlAuth;
 } | {
     /**
      * Distributes a minted `document/write` capability token to group
@@ -85,13 +75,9 @@ export type GroupBroadcastMessage = {
     /** HLC stamped by the revoker; mirrors the revoker-side stored row. */
     hlc: string;
 } | {
-    type: 'group:update';
+    type: 'ledger:entry';
     groupID: string;
-    update: {
-        name?: string;
-        description?: string;
-        hlc: string;
-    };
+    token: string;
 } | {
     /**
      * A member announces a voluntary leave. MLS forbids self-removal, so this
@@ -109,20 +95,62 @@ export type GroupBroadcastMessage = {
     entries: Array<MutationApplyEntry>;
     /** DID of the peer that authored this broadcast — used for loopback drop. */
     senderPeerDID: string;
+} | {
+    /**
+     * A rejoining peer asks current members for the group's full control
+     * ledger so it can backfill entries it missed while absent. `requestID`
+     * correlates the eventual batched reply.
+     */
+    type: 'ledger-catchup:request';
+    requestID: string;
+} | {
+    /**
+     * A member's reply to a `ledger-catchup:request`: the group's control
+     * ledger as an array of signed entry tokens. The responder is UNTRUSTED —
+     * each token self-authenticates, so the requester re-verifies every one
+     * independently and a forged or unsigned token is dropped without
+     * poisoning the rest. Idempotent + order-independent on the token digest.
+     */
+    type: 'ledger-catchup:reply';
+    requestID: string;
+    entries: Array<string>;
 };
-export type AffectedRow = {
-    kind: 'circle';
+/** Narrow {@link GroupBroadcastMessage} to the variant(s) carrying the given `type`. */
+export type BroadcastOf<TType extends GroupBroadcastMessage['type']> = Extract<GroupBroadcastMessage, {
+    type: TType;
+}>;
+/**
+ * The local-event descriptor for an applied `ledger:entry`. The ingest arm
+ * captures it after reprojecting, while the store still holds the post-state,
+ * so {@link forwardRemoteBroadcast} can emit the matching local event for a
+ * remote-driven change without re-reading or re-verifying. Each variant carries
+ * the projected row plus the create-vs-change / add-vs-remove discriminators the
+ * ingest derived by comparing the pre-state it read before reprojecting.
+ */
+export type LedgerAffected = {
+    entry: 'circle.def';
+    row: Circle;
+    /** True when an active circle row existed before this entry (changed, not created). */
+    preExisted: boolean;
+    /** True when the entry's catalog set differs from the pre-state's (catalogs changed). */
+    catalogsChanged: boolean;
+} | {
+    entry: 'circle.def.removed';
     row: Circle;
 } | {
-    kind: 'member';
+    entry: 'circle.member';
     row: CircleMember;
 } | {
-    kind: 'catalog';
-    row: Catalog;
+    entry: 'circle.member.removed';
+    row: CircleMember;
 } | {
-    kind: 'group';
+    entry: 'group.settings';
     row: Group;
 };
+export type AffectedRow = {
+    kind: 'ledger';
+    ledger: LedgerAffected;
+};
 export type ProcessBroadcastResult = {
     applied: boolean;
     /**
@@ -150,9 +178,21 @@ export type ProcessBroadcastResult = {
      * (possibly `0`) on `mutation:apply`.
      */
     duplicates?: number;
+    /**
+     * Set to `'unknown-type'` when the message carried a `type` outside the
+     * known discriminated union (version skew). The frame is not applied and is
+     * logged; other branches never set this.
+     */
+    reason?: 'unknown-type';
 };
 export type ProcessBroadcastParams = {
     p2pStore: P2PStoreAPI;
+    /**
+     * Delegation store for received-grant / received-revocation handling. The
+     * delegation token and revocation rows live here (group-agnostic); the p2p
+     * store keeps only the `jti` → group edge.
+     */
+    delegationStore: DelegationStoreAPI;
     graphStore: GraphStoreAPI;
     /**
      * Engine graph internals — required to apply `mutation:apply` entries via
@@ -198,6 +238,21 @@ export type ProcessBroadcastParams = {
      * Absent in tests that don't exercise the subscription path.
      */
     emitter?: P2PEventEmitter;
+    /**
+     * Device-wide monotonic clock. On a newly-appended `ledger:entry` the
+     * receiver merges the entry's HLC into this clock so its own later entries
+     * sort strictly after observed ones. Optional: callers that never receive
+     * ledger entries (and existing tests) omit it and the merge is skipped.
+     */
+    hlc?: HLC;
+    /**
+     * Resolve a group's genesis anchor, or `null` when none is available yet. A
+     * `ledger:entry` is always stored durably, but the admin-role overlay can
+     * only be projected once the authenticated epoch-0 root is known; a `null`
+     * anchor defers projection without dropping the entry. Optional so callers
+     * that never project (and existing tests) can omit it.
+     */
+    getGroupAnchor?: (groupID: string) => Promise<GroupAnchor | null>;
     /** Optional logger — warns on per-entry apply failures. */
     logger?: Logger;
 };
@@ -219,3 +274,32 @@ export type ProcessBroadcastParams = {
  * payload fidelity.
  */
 export declare function processBroadcast(params: ProcessBroadcastParams, message: GroupBroadcastMessage, groupID: string): Promise<ProcessBroadcastResult>;
+/**
+ * Summary of a batched ledger catch-up apply.
+ */
+export type ApplyLedgerCatchupReplyResult = {
+    /** Count of entries whose verified token was newly appended to the ledger. */
+    applied: number;
+    /** Count of entries dropped because their token failed verification. */
+    rejected: number;
+};
+/**
+ * Apply a batched ledger catch-up reply from an UNTRUSTED responder. Each entry
+ * carries its own signed token, so the responder's identity is irrelevant: every
+ * token is verified independently and a forged or unsigned one is dropped without
+ * aborting the batch. Surviving entries are appended idempotently on the token
+ * digest, so a replayed or duplicated reply is a harmless no-op.
+ *
+ * A catch-up reply delivers the ledger's history out of order by construction, so
+ * after any new entry lands the projection is rebuilt authoritatively from the
+ * whole ledger (a full reproject) rather than applied incrementally. All four
+ * control projections — admin roster, circle defs, circle members, group
+ * settings — rebuild here, so a circle or settings entry delivered via catch-up
+ * materializes immediately rather than waiting for a later live entry. Projection
+ * is deferred when no genesis anchor is available yet — the entries are still
+ * stored durably.
+ *
+ * Never throws out of the per-token loop: one bad token must not abort the batch.
+ */
+export declare function applyLedgerCatchupReply(params: ProcessBroadcastParams, reply: BroadcastOf<'ledger-catchup:reply'>, groupID: string): Promise<ApplyLedgerCatchupReplyResult>;
+export {};