@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/groups/broadcast.d.ts

@@ -1,14 +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 } 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 { 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 { GroupAnchor } from './group-anchor.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;
@@ -43,6 +47,39 @@ export type GroupBroadcastMessage = {
     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
@@ -74,10 +111,6 @@ export type GroupBroadcastMessage = {
     groupID: string;
     /** HLC stamped by the revoker; mirrors the revoker-side stored row. */
     hlc: string;
-} | {
-    type: 'ledger:entry';
-    groupID: string;
-    token: string;
 } | {
     /**
      * A member announces a voluntary leave. MLS forbids self-removal, so this
@@ -93,64 +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 the group's full control
-     * ledger so it can backfill entries 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: 'ledger-catchup:request';
-    requestID: string;
+    senderPeerDID: string | undefined;
 } | {
     /**
-     * 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.
+     * 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: 'ledger-catchup:reply';
-    requestID: string;
-    entries: Array<string>;
-};
-/** 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;
-} | {
-    entry: 'circle.member';
-    row: CircleMember;
-} | {
-    entry: 'circle.member.removed';
-    row: CircleMember;
-} | {
-    entry: 'group.settings';
-    row: Group;
-};
-export type AffectedRow = {
-    kind: 'ledger';
-    ledger: LedgerAffected;
+    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,6 +191,8 @@ export type ProcessBroadcastResult = {
 };
 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
@@ -203,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;
@@ -239,7 +251,7 @@ export type ProcessBroadcastParams = {
      */
     emitter?: P2PEventEmitter;
     /**
-     * Device-wide monotonic clock. On a newly-appended `ledger:entry` the
+     * 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.
@@ -247,12 +259,28 @@ export type ProcessBroadcastParams = {
     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`
+     * 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;
 };
@@ -275,31 +303,121 @@ export type ProcessBroadcastParams = {
  */
 export declare function processBroadcast(params: ProcessBroadcastParams, message: GroupBroadcastMessage, groupID: string): Promise<ProcessBroadcastResult>;
 /**
- * Summary of a batched ledger catch-up apply.
+ * 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 ApplyLedgerCatchupReplyResult = {
-    /** Count of entries whose verified token was newly appended to the ledger. */
+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;
-    /** Count of entries dropped because their token failed verification. */
+    /**
+     * 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 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.
+ * Adopt a whole ledger gathered from one untrusted responder.
  *
- * 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.
+ * 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.
  *
- * Never throws out of the per-token loop: one bad token must not abort the batch.
+ * Throws whatever the install throws — a rejected ledger changes nothing.
  */
-export declare function applyLedgerCatchupReply(params: ProcessBroadcastParams, reply: BroadcastOf<'ledger-catchup:reply'>, groupID: string): Promise<ApplyLedgerCatchupReplyResult>;
-export {};
+export declare function bootstrapGroupLedger(params: BootstrapGroupLedgerParams, tokens: Array<string>, groupID: string): Promise<ApplyLedgerCatchupReplyResult>;