@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/groups/broadcast.d.ts

@@ -1,11 +1,18 @@
+import type { OwnIdentity } from '@kokuin/token';
 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 { Circle, CircleMember, Group, P2PStoreAPI } from '@kubun/store-p2p';
+import type { CatalogRecord } from '@kubun/protocol';
+import type { DelegationStoreAPI } from '@kubun/store-delegation';
+import type { GraphStoreAPI } from '@kubun/store-graph';
+import type { P2PStoreAPI } from '@kubun/store-p2p';
+import type { GroupAnchor, LedgerLogEntry, RosterState } from '@kumiai/mls';
 import { type ForwardingConfig } from '../sync/forwarder.js';
 import type { StoreUnreadableMode } from '../types.js';
+import { type AccessDefaultRule } from './access-default-token.js';
 import type { P2PEventEmitter } from './events.js';
+import type { PeerAvailability, PeerCapability } from './group-protocols.js';
+import { type AffectedRow, type LedgerIngestParams } from './ledger-ingest.js';
 export type MutationApplyEntry = {
     mutationJWT: string;
     docID: string;
@@ -14,49 +21,17 @@ export type MutationApplyEntry = {
     modelID: string;
 };
 /**
- * A circle row in a catch-up snapshot. Mirrors the wire form of `circle:create`
- * (matching {@link CircleRecord} field names) plus `removedAtHLC` so tombstoned
- * circles carry their removal HLC. `null` when the circle is active.
+ * 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.
  */
-export type CircleSnapshot = CircleRecord & {
-    removedAtHLC: string | null;
-};
-/**
- * A circle-member row in a catch-up snapshot. Mirrors the wire form of
- * `member:add` (matching {@link CircleMemberRecord} field names) plus
- * `removedAtHLC` so tombstoned memberships carry their removal HLC. `null` when
- * the membership is active.
- */
-export type CircleMemberSnapshot = CircleMemberRecord & {
-    removedAtHLC: string | null;
-};
+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;
@@ -66,10 +41,45 @@ export type GroupBroadcastMessage = {
         filterCriteria?: CatalogRecord['filterCriteria'];
         hlc: string;
     };
+    auth?: ControlAuth;
 } | {
     type: 'catalog:delete';
     catalogID: string;
     hlc: string;
+    auth?: ControlAuth;
+} | {
+    /**
+     * A member states its own model access-default so co-members can evaluate
+     * the owner's documents. `auth` is a signed token whose issuer is the
+     * owner; the receiver derives every authoritative field from that verified
+     * token and applies the rule ONLY when `ownerDID` equals the issuer (a
+     * member states its own policy, never another's). LWW by `hlc`.
+     */
+    type: 'access-default:set';
+    modelID: string;
+    permissionType: 'read' | 'write';
+    rule: {
+        level: string;
+        allowedDIDs: Array<string> | null;
+        allowedCircles: Array<string> | null;
+        allowedGroups: Array<string> | null;
+    };
+    ownerDID: string;
+    hlc: string;
+    auth: ControlAuth;
+} | {
+    /**
+     * A member removes its own model access-default(s). Same sender-bound and
+     * LWW rules as `access-default:set`: applied only when `ownerDID` equals
+     * the verified `auth` issuer and the removal `hlc` is newer than the
+     * stored rule's.
+     */
+    type: 'access-default:remove';
+    modelID: string;
+    permissionTypes: Array<'read' | 'write'>;
+    ownerDID: string;
+    hlc: string;
+    auth: ControlAuth;
 } | {
     /**
      * Distributes a minted `document/write` capability token to group
@@ -101,14 +111,6 @@ export type GroupBroadcastMessage = {
     groupID: string;
     /** HLC stamped by the revoker; mirrors the revoker-side stored row. */
     hlc: string;
-} | {
-    type: 'group:update';
-    groupID: string;
-    update: {
-        name?: string;
-        description?: string;
-        hlc: string;
-    };
 } | {
     /**
      * A member announces a voluntary leave. MLS forbids self-removal, so this
@@ -124,42 +126,35 @@ export type GroupBroadcastMessage = {
 } | {
     type: 'mutation:apply';
     entries: Array<MutationApplyEntry>;
-    /** DID of the peer that authored this broadcast — used for loopback drop. */
-    senderPeerDID: string;
-} | {
     /**
-     * A rejoining peer asks current members for a snapshot of the group's
-     * circle + circle-member rows so it can recover state it missed while
-     * absent. `requestID` correlates the eventual batched reply.
+     * DID of the peer this broadcast arrived FROM — used for loopback drop.
+     * For a forwarded mutation that is the forwarding peer, not the author, so
+     * it is never an authorization input: each entry carries its own signed
+     * `mutationJWT`, verified independently.
+     *
+     * `undefined` when the frame opened at a leaf that could not be named. The
+     * entries still apply — see the loopback guard.
      */
-    type: 'circle-catchup:request';
-    requestID: string;
+    senderPeerDID: string | undefined;
 } | {
     /**
-     * A current member's batched response to a `circle-catchup:request`. One
-     * frame carrying the group's current circle + circle-member rows,
-     * INCLUDING tombstoned entries (each row's `removedAtHLC` distinguishes
-     * active from removed). The requester correlates it via `requestID` and
-     * applies each row through the existing circle/member broadcast handlers.
+     * A device advertises itself to its co-members. Everything here except
+     * `announcerDID` came off the wire; `announcerDID` did NOT — it is the
+     * MLS-authenticated sender the handler read from `message.payload.iss`,
+     * because the announce body carries no DID field at all.
+     *
+     * `undefined` when the frame opened at a leaf that could not be named, and
+     * the apply then writes nothing: a capability claim attributed to nobody is
+     * worse than no row.
      */
-    type: 'circle-catchup:reply';
-    requestID: string;
-    circles: Array<CircleSnapshot>;
-    circleMembers: Array<CircleMemberSnapshot>;
-};
-export type AffectedRow = {
-    kind: 'circle';
-    row: Circle;
-} | {
-    kind: 'member';
-    row: CircleMember;
-} | {
-    kind: 'catalog';
-    row: Catalog;
-} | {
-    kind: 'group';
-    row: Group;
+    type: 'peer:announce';
+    label: string;
+    availability: PeerAvailability;
+    capabilities: Array<PeerCapability>;
+    hlc: string;
+    announcerDID: string | undefined;
 };
+export type { AffectedRow, LedgerAffected } from './ledger-ingest.js';
 export type ProcessBroadcastResult = {
     applied: boolean;
     /**
@@ -187,9 +182,23 @@ 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;
+    /** See {@link ApplyLedgerEntriesParams.withProjectionTransaction}. */
+    withProjectionTransaction?: ApplyLedgerEntriesParams['withProjectionTransaction'];
+    /**
+     * 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
@@ -200,6 +209,12 @@ export type ProcessBroadcastParams = {
     graph: GraphInternals;
     /** Self DID for `mutation:apply` loopback detection. */
     selfDID: string;
+    /**
+     * This device's signing identity, used to restate its own access-defaults on
+     * a `control/policyCatchup`. Optional: a device without one serves nothing
+     * rather than an unsigned rule, which a requester would drop anyway.
+     */
+    identity?: OwnIdentity;
     /**
      * Receiver storage mode for incoming `mutation:apply` entries.
      * - `'persist'` (default) — every entry the engine accepts is persisted;
@@ -235,6 +250,37 @@ export type ProcessBroadcastParams = {
      * Absent in tests that don't exercise the subscription path.
      */
     emitter?: P2PEventEmitter;
+    /**
+     * Device-wide monotonic clock. On a newly-appended control-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
+     * control-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>;
+    /** Read the group's control ledger — see `LedgerIngestParams.getGroupLedger`. */
+    getGroupLedger?: (groupID: string) => Promise<ReadonlyArray<LedgerLogEntry>>;
+    /**
+     * The epoch this device's handle is at, stamped onto a `peer:announce` row.
+     * Synchronous because it reads the registry's published scalar rather than a
+     * handle.
+     *
+     * It is also the epoch the announcement was SEALED at, not merely the one it
+     * was applied at: the app lane only ever hands a handler a frame whose seal
+     * epoch matches the current one — everything else is held as `ahead` or
+     * discarded as dead — so the two cannot disagree for a delivered frame.
+     *
+     * Optional; a caller that omits it (or a group the registry has not observed)
+     * stamps 0, which reads as "epoch unknown" rather than "epoch zero".
+     */
+    getGroupEpoch?: (groupID: string) => number | undefined;
     /** Optional logger — warns on per-entry apply failures. */
     logger?: Logger;
 };
@@ -257,35 +303,121 @@ export type ProcessBroadcastParams = {
  */
 export declare function processBroadcast(params: ProcessBroadcastParams, message: GroupBroadcastMessage, groupID: string): Promise<ProcessBroadcastResult>;
 /**
- * Summary of a batched catch-up apply: how many rows mutated local state.
+ * Sender-bound, LWW apply of a signed `access-default:set` frame. Shared by the
+ * live broadcast path and the invite-seeding path so both authenticate through
+ * the same token verification. The authoritative fields come from the verified
+ * token; the plaintext `ownerDID` is used only for the sender-bound equality
+ * check. Returns whether a row was written.
  */
-export type ApplyCatchupReplyResult = {
-    /** Count of circle rows whose synthesized message mutated local state. */
-    circlesApplied: number;
-    /** Count of member rows whose synthesized message mutated local state. */
-    membersApplied: number;
+export type AccessDefaultSetFrame = {
+    ownerDID: string;
+    modelID: string;
+    permissionType: 'read' | 'write';
+    rule: AccessDefaultRule;
+    hlc: string;
+    auth: string;
+};
+export type ApplyAccessDefaultSetFrameParams = {
+    graphStore: GraphStoreAPI;
+    frame: AccessDefaultSetFrame;
+    logger?: Logger;
+    /** Scopes the log lines to the group the frame arrived on, when it arrived on one. */
+    groupID?: string;
+};
+export declare function applyAccessDefaultSetFrame(params: ApplyAccessDefaultSetFrameParams): Promise<boolean>;
+/**
+ * Apply one signed access-default set token, with no surrounding frame.
+ *
+ * What a catch-up reply carries: a token and nothing else, so there is no
+ * plaintext mirror to cross-check and none is needed — the frame's mirror
+ * fields exist for a receiver rebuilding what was signed, and the authoritative
+ * values were always the claim's. Every other rule is the live path's: the owner
+ * is the authenticated issuer, and the write happens only if strictly newer than
+ * what is stored.
+ */
+export declare function applyAccessDefaultSetToken(params: {
+    graphStore: GraphStoreAPI;
+    token: string;
+    logger?: Logger;
+    groupID: string;
+}): Promise<boolean>;
+/** Summary of a whole-ledger adoption. */
+type ApplyLedgerCatchupReplyResult = {
+    /** Size of the ledger that was adopted. */
+    applied: number;
+    /**
+     * Always `0` on this path, and structurally so: the install verifies the whole
+     * ledger against the authenticated head before folding a single entry, so a
+     * bad token rejects the batch rather than dropping an entry out of it. Carried
+     * because the catch-up summary reports it beside counts from paths that CAN
+     * drop per entry.
+     */
+    rejected: number;
+};
+/** Inputs the ledger-fold helpers need — a strict subset of the receive params. */
+export type ApplyLedgerEntriesParams = LedgerIngestParams & {
+    /**
+     * Run the projection rebuild atomically, given the store to write it through.
+     *
+     * A rebuild materializes several tables from one fold — circle rows, every
+     * circle's `open` flag, the group row, the commit-hub designation — and a crash
+     * between them leaves them disagreeing. A device with no flagged commit hub
+     * cannot commit at all, which reads as a hang rather than an error.
+     *
+     * A seam rather than a `StoreProvider` because the surrounding operations must
+     * NOT be in the same transaction: an install or a gather waits on the network,
+     * and a transaction spanning one holds kubun's single SQLite connection across
+     * it. So the caller decides what the transaction covers. Omitted, the rebuild
+     * runs on {@link LedgerIngestParams.p2pStore} unwrapped — correct when the
+     * caller already holds a transaction, and self-healing on the bootstrap paths,
+     * where the next reproject rebuilds from the same ledger anyway.
+     *
+     * Declared here rather than on {@link LedgerIngestParams} because only the
+     * batch folds below read it: `ingestVerifiedLedgerEntry` reprojects through
+     * `p2pStore` directly, so a caller passing this to the single-entry path would
+     * be promised an atomicity it does not get.
+     */
+    withProjectionTransaction?: (run: (store: P2PStoreAPI) => Promise<void>) => Promise<void>;
+};
+/**
+ * Adopt the control state a handle already holds: merge the HLCs its entries
+ * carry into this device's clock, then rebuild every projection from them.
+ *
+ * For a peer whose handle was filled by something other than a landed commit —
+ * a joiner, whose Welcome folded the group's whole ledger and checked it against
+ * the authenticated head before this device had any say. Those entries never
+ * passed through the receive path, so nothing else has observed their clocks or
+ * projected them.
+ *
+ * The merge keeps this device's later writes sorting after what the group did
+ * before it arrived. It decides no authority — that reads the enacted position —
+ * but the LWW comparisons that are not ledger folds (removal timestamps,
+ * access-default rules) still depend on a clock that has seen the group's.
+ */
+export declare function adoptHandleLedgerState(params: ApplyLedgerEntriesParams, groupID: string): Promise<void>;
+/** Inputs {@link bootstrapGroupLedger} needs on top of the ingest's. */
+export type BootstrapGroupLedgerParams = ApplyLedgerEntriesParams & {
+    /**
+     * Install a gathered WHOLE ledger into the group's handle, verified against
+     * the authenticated head before a single entry is folded, and answer with the
+     * roster the install left the handle holding. Throws when the list does not
+     * reproduce that head.
+     *
+     * The roster is returned rather than read back afterwards so it is the one the
+     * install itself produced, taken while the handle is still held: a second read
+     * could observe a handle another operation has since advanced.
+     */
+    installGroupLedger: (groupID: string, tokens: Array<string>) => Promise<RosterState>;
 };
 /**
- * Apply a batched catch-up reply row-by-row through the existing per-row
- * broadcast handlers. Each snapshot row is turned into the single equivalent
- * {@link GroupBroadcastMessage} and fed through {@link processBroadcast}, so all
- * conflict resolution (HLC last-write-wins for circle create/update, the
- * earliest-wins tombstone guards for circle/member removal) is the exact same
- * code the live broadcast path runs. No additional merge logic lives here.
+ * Adopt a whole ledger gathered from one untrusted responder.
  *
- * A tombstoned circle replays a `circle:create` (so a rejoiner that never saw
- * the circle materializes the row) immediately followed by a `circle:delete`
- * stamped with the row's `removedAtHLC`. The delete's earliest-wins guard
- * converges the tombstone; the create is a no-op when a newer local row already
- * exists. An active circle replays a single `circle:create` (the apply path
- * routes create -> update for an existing id). Member rows map symmetrically to
- * `member:add` / `member:remove` — `member:add` materializes the row so the
- * subsequent `member:remove` has a row to tombstone.
+ * Signatures do NOT cover omission or reordering — a responder can hand back
+ * genuine tokens with a demotion missing — so the list is installed against the
+ * authenticated head FIRST and rejected whole on mismatch, before anything is
+ * projected. Roles are reconciled against the roster the install folded, not the
+ * ledger, because nothing later revisits a stale `admin` row.
  *
- * Idempotent and order-independent: re-applying the same batch, or applying its
- * rows in any order, lands the same final state because every synthesized
- * message runs the same LWW / earliest-wins guards.
+ * Throws whatever the install throws — a rejected ledger changes nothing.
  */
-export declare function applyCatchupReply(params: ProcessBroadcastParams, reply: Extract<GroupBroadcastMessage, {
-    type: 'circle-catchup:reply';
-}>, groupID: string): Promise<ApplyCatchupReplyResult>;
+export declare function bootstrapGroupLedger(params: BootstrapGroupLedgerParams, tokens: Array<string>, groupID: string): Promise<ApplyLedgerCatchupReplyResult>;