@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/groups/ledger-affected-events.js

@@ -0,0 +1,96 @@
+import { toISO } from '../context/types.js';
+/**
+ * Emit the local `P2PEventEmitter` events for a remote-driven control-ledger
+ * entry that a receiving peer just applied, so GraphQL subscribers see
+ * remote circle/group changes live — the same events a local producer fires.
+ *
+ * Only `ledger:entry` projections surface as `affected`; every other applied
+ * message (delegation grant/revoke, advisory leave) already emits its own event
+ * from inside `processBroadcast`, so this covers exactly the circle/group
+ * projection rows the apply core returns rather than emits. The payloads are
+ * built from `affected.row`, which `processBroadcast` snapshots at the right
+ * moment (after-state for create/change, before-state for delete/remove).
+ */ export async function emitLedgerAffectedEvents(emitter, result) {
+    if (!result.applied || result.affected == null || result.affected.kind !== 'ledger') {
+        return;
+    }
+    const { ledger } = result.affected;
+    switch(ledger.entry){
+        case 'circle.def':
+            {
+                const { row } = ledger;
+                // No active pre-state means a create; otherwise a change. Match the
+                // producer: a catalogs-only change emits `circleCatalogsChanged`, any other
+                // change emits `circleDataChanged`. The `*Changed` payloads carry `circleID`.
+                if (!ledger.preExisted) {
+                    await emitter.emit('circleCreated', {
+                        id: row.id,
+                        groupID: row.group_id,
+                        name: row.name,
+                        description: row.description,
+                        createdAt: toISO(row.created_at)
+                    });
+                    return;
+                }
+                const eventName = ledger.catalogsChanged ? 'circleCatalogsChanged' : 'circleDataChanged';
+                await emitter.emit(eventName, {
+                    id: row.id,
+                    groupID: row.group_id,
+                    name: row.name,
+                    description: row.description,
+                    createdAt: toISO(row.created_at),
+                    circleID: row.id
+                });
+                return;
+            }
+        case 'circle.def.removed':
+            {
+                const { row } = ledger;
+                await emitter.emit('circleDeleted', {
+                    id: row.id,
+                    groupID: row.group_id,
+                    name: row.name,
+                    description: row.description,
+                    createdAt: toISO(row.created_at)
+                });
+                return;
+            }
+        case 'circle.member':
+            {
+                const { row } = ledger;
+                // Both a new membership and a role change map here: there is no distinct
+                // "role changed" circle-member event, mirroring the producer.
+                await emitter.emit('circleMemberAdded', {
+                    circleID: row.circle_id,
+                    memberDID: row.member_did,
+                    role: row.role,
+                    createdAt: toISO(row.created_at)
+                });
+                return;
+            }
+        case 'circle.member.removed':
+            {
+                const { row } = ledger;
+                await emitter.emit('circleMemberRemoved', {
+                    circleID: row.circle_id,
+                    memberDID: row.member_did,
+                    role: row.role,
+                    createdAt: toISO(row.created_at)
+                });
+                return;
+            }
+        case 'group.settings':
+            {
+                const { row } = ledger;
+                await emitter.emit('groupDataChanged', {
+                    id: row.id,
+                    name: row.name,
+                    description: row.description,
+                    createdBy: row.created_by,
+                    createdAt: toISO(row.created_at),
+                    groupID: row.id
+                });
+                return;
+            }
+    }
+}

package/lib/groups/ledger-entry.d.ts

@@ -0,0 +1,37 @@
+import { type OwnIdentity } from '@kokuin/token';
+/**
+ * A control-ledger claim. The payload of a signed ledger token: `type` selects
+ * the reducer, `subject` is the entity the claim is about, `value` carries the
+ * claim data, and `hlc` orders it. The authenticated author is never part of
+ * this shape — it comes from the verified token's `iss`.
+ */
+export type LedgerEntry<TValue = unknown> = {
+    type: string;
+    subject: string;
+    value: TValue;
+    hlc: string;
+};
+/** A ledger entry whose token signature has been cryptographically verified. */
+export type VerifiedLedgerEntry<TValue = unknown> = {
+    /** Authenticated author DID (the verified token issuer), normalized. */
+    issuer: string;
+    entry: LedgerEntry<TValue>;
+};
+/**
+ * Sign a ledger entry. The signer fills `iss` with its DID, so the signature
+ * covers every claim field and binds the author. Returns the stringified token.
+ */
+export declare function signLedgerEntry(identity: OwnIdentity, entry: LedgerEntry): Promise<string>;
+/**
+ * Verify a signed ledger token and extract its claim. Returns `null` (never
+ * throws) when the token is unparseable, unsigned (`alg: 'none'` — `verifyToken`
+ * returns those without checking a signature, so an attacker could forge an
+ * arbitrary `iss`), or structurally malformed. The claim fields come from the
+ * verified payload only; the issuer is the normalized verified `iss`.
+ */
+export declare function verifyLedgerEntry<TValue = unknown>(token: string): Promise<VerifiedLedgerEntry<TValue> | null>;
+/**
+ * Content-addressed digest of a signed ledger token, used as the append-only
+ * store's dedup key. Multibase-encoded SHA-256 multihash over the token bytes.
+ */
+export declare function ledgerEntryDigest(signedToken: string): string;

package/lib/groups/ledger-entry.js

@@ -0,0 +1,56 @@
+import { encodeMultibase, isVerifiedToken, multihashSHA256, normalizeDID, stringifyToken, verifyToken } from '@kokuin/token';
+const textEncoder = new TextEncoder();
+/**
+ * Sign a ledger entry. The signer fills `iss` with its DID, so the signature
+ * covers every claim field and binds the author. Returns the stringified token.
+ */ export async function signLedgerEntry(identity, entry) {
+    const signed = await identity.signToken({
+        type: entry.type,
+        subject: entry.subject,
+        value: entry.value,
+        hlc: entry.hlc
+    }, // Embed the long-form DID so each entry is self-verifying offline: the
+    // ledger is the source of truth and receivers fold it long after first
+    // contact, when the author's DID document may no longer be cached. No-op
+    // for did:key (long form === id).
+    {
+        embedLongForm: true
+    });
+    return stringifyToken(signed);
+}
+/**
+ * Verify a signed ledger token and extract its claim. Returns `null` (never
+ * throws) when the token is unparseable, unsigned (`alg: 'none'` — `verifyToken`
+ * returns those without checking a signature, so an attacker could forge an
+ * arbitrary `iss`), or structurally malformed. The claim fields come from the
+ * verified payload only; the issuer is the normalized verified `iss`.
+ */ export async function verifyLedgerEntry(token) {
+    let verified;
+    try {
+        verified = await verifyToken(token);
+    } catch  {
+        return null;
+    }
+    if (!isVerifiedToken(verified)) {
+        return null;
+    }
+    const { iss, type, subject, value, hlc } = verified.payload;
+    if (typeof type !== 'string' || typeof subject !== 'string' || typeof hlc !== 'string') {
+        return null;
+    }
+    return {
+        issuer: normalizeDID(iss),
+        entry: {
+            type,
+            subject,
+            value,
+            hlc
+        }
+    };
+}
+/**
+ * Content-addressed digest of a signed ledger token, used as the append-only
+ * store's dedup key. Multibase-encoded SHA-256 multihash over the token bytes.
+ */ export function ledgerEntryDigest(signedToken) {
+    return encodeMultibase(multihashSHA256(textEncoder.encode(signedToken)));
+}

package/lib/groups/ledger-fold.d.ts

@@ -0,0 +1,56 @@
+import type { GroupAnchor } from './group-anchor.js';
+import type { VerifiedLedgerEntry } from './ledger-entry.js';
+/**
+ * A per-type projection over the control ledger. The fold stays free of any
+ * admin/circle semantics: a reducer owns its own initial state (derived from
+ * the genesis anchor), its authority rule, and its fold step, so a new ledger
+ * type plugs in as a parameter with zero edits to {@link foldLedger}.
+ */
+export type LedgerReducer<TValue, TState> = {
+    /** Ledger entry `type` this reducer projects; entries of any other type are dropped. */
+    type: string;
+    /**
+     * Initial fold state, derived from the genesis anchor. The anchor is the
+     * authenticated epoch-0 root (e.g. the creator DID is the first admin), so
+     * seeding from it is what makes the very first claims evaluable.
+     */
+    seed(anchor: GroupAnchor): TState;
+    /** Is the verified issuer allowed to make this claim, given the state so far? */
+    verifyAuthority(verified: VerifiedLedgerEntry<TValue>, stateSoFar: TState): boolean;
+    /** Fold step: return the next state after applying an authorized claim. */
+    apply(verified: VerifiedLedgerEntry<TValue>, stateSoFar: TState): TState;
+};
+/**
+ * A verified entry paired with its content-addressed id. The id is the
+ * total-order tie-breaker when two entries share an `hlc`, and identifies the
+ * entry in drop notices.
+ */
+export type FoldInput<TValue = unknown> = {
+    verified: VerifiedLedgerEntry<TValue>;
+    entryID: string;
+};
+/** Why an entry was skipped during the fold, for an optional observer. */
+export type FoldDrop = {
+    entryID: string;
+    type: string;
+    reason: string;
+};
+/**
+ * Replay the ledger into a single reducer's projection.
+ *
+ * Signatures are verified at ingest, not here — this fold evaluates AUTHORITY:
+ * whether each issuer was allowed to make its claim given the state accumulated
+ * from strictly-earlier entries. Evaluating against state-so-far (never the
+ * final state) is what makes rotation sound: a key authorized at HLC `t` can be
+ * revoked at `t+1` without retroactively invalidating its earlier claims.
+ *
+ * Deterministic on any arrival order: it seeds from the genesis anchor, sorts a
+ * copy of the entries by the total order `(hlc, entryID)`, then folds. Pure — no
+ * clock, no randomness, no I/O, and the input array is never mutated. A claim of
+ * an unrelated type or one whose authority fails is dropped (never thrown) so a
+ * single bad entry can never abort the projection. Drops are silent unless an
+ * `onDrop` observer is supplied — the fold runs on every authority check, where
+ * authority-failed drops are expected, so the caller decides whether to surface
+ * them rather than the fold emitting to the console.
+ */
+export declare function foldLedger<TValue, TState>(entries: Array<FoldInput<TValue>>, anchor: GroupAnchor, reducer: LedgerReducer<TValue, TState>, onDrop?: (drop: FoldDrop) => void): TState;

package/lib/groups/ledger-fold.js

@@ -0,0 +1,53 @@
+/** Total order over the ledger: HLC first, then content-addressed id to break ties. */ function compareFoldInputs(a, b) {
+    if (a.verified.entry.hlc !== b.verified.entry.hlc) {
+        return a.verified.entry.hlc < b.verified.entry.hlc ? -1 : 1;
+    }
+    if (a.entryID === b.entryID) {
+        return 0;
+    }
+    return a.entryID < b.entryID ? -1 : 1;
+}
+/**
+ * Replay the ledger into a single reducer's projection.
+ *
+ * Signatures are verified at ingest, not here — this fold evaluates AUTHORITY:
+ * whether each issuer was allowed to make its claim given the state accumulated
+ * from strictly-earlier entries. Evaluating against state-so-far (never the
+ * final state) is what makes rotation sound: a key authorized at HLC `t` can be
+ * revoked at `t+1` without retroactively invalidating its earlier claims.
+ *
+ * Deterministic on any arrival order: it seeds from the genesis anchor, sorts a
+ * copy of the entries by the total order `(hlc, entryID)`, then folds. Pure — no
+ * clock, no randomness, no I/O, and the input array is never mutated. A claim of
+ * an unrelated type or one whose authority fails is dropped (never thrown) so a
+ * single bad entry can never abort the projection. Drops are silent unless an
+ * `onDrop` observer is supplied — the fold runs on every authority check, where
+ * authority-failed drops are expected, so the caller decides whether to surface
+ * them rather than the fold emitting to the console.
+ */ export function foldLedger(entries, anchor, reducer, onDrop) {
+    const ordered = [
+        ...entries
+    ].sort(compareFoldInputs);
+    let state = reducer.seed(anchor);
+    for (const { verified, entryID } of ordered){
+        const { entry } = verified;
+        if (entry.type !== reducer.type) {
+            onDrop?.({
+                entryID,
+                type: entry.type,
+                reason: `unknown type for reducer '${reducer.type}'`
+            });
+            continue;
+        }
+        if (!reducer.verifyAuthority(verified, state)) {
+            onDrop?.({
+                entryID,
+                type: entry.type,
+                reason: `issuer '${verified.issuer}' not authorized`
+            });
+            continue;
+        }
+        state = reducer.apply(verified, state);
+    }
+    return state;
+}

package/lib/groups/manager.d.ts

@@ -1,7 +1,7 @@
-import { type GroupPermission, type Invite, type KeyPackageBundle } from '@enkaku/group';
-import type { Identity, OwnIdentity } from '@enkaku/token';
+import { type Identity, type OwnIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
-import type { GroupBroadcastMessage } from './broadcast.js';
+import { HLC } from '@kubun/hlc';
+import { type GroupPermission, type Invite, type KeyPackageBundle } from '@kumiai/mls';
 import type { GroupHandleRegistry } from './group-handle-registry.js';
 import type { SuggestedHub } from './invite-payload.js';
 export type GroupManagerParams = {
@@ -13,6 +13,14 @@ export type GroupManagerParams = {
      * the registry's per-group mutex with write-through persist.
      */
     registry: GroupHandleRegistry;
+    /**
+     * Device-wide monotonic clock for stamping group/circle/member metadata.
+     * Required: production passes the engine's single instance so every write
+     * from this device — graph mutations and group metadata alike — advances one
+     * shared clock, preventing two same-millisecond writes from minting identical
+     * timestamps (the second would silently lose under last-writer-wins).
+     */
+    hlc: HLC;
 };
 export type CreateGroupParams = {
     stores: StoreProvider;
@@ -25,17 +33,6 @@ export type CreateGroupParams = {
 export type CreateGroupResult = {
     groupID: string;
 };
-export type UpdateGroupParams = {
-    stores: StoreProvider;
-    groupID: string;
-    update: {
-        name?: string;
-        description?: string;
-    };
-};
-export type UpdateGroupResult = {
-    broadcast: GroupBroadcastMessage;
-};
 export type InviteToGroupParams = {
     stores: StoreProvider;
     groupID: string;
@@ -46,7 +43,7 @@ export type InviteToGroupParams = {
 };
 export type InviteToGroupResult = {
     invite: Invite;
-    /** Framed MLSMessage(Welcome) bytes for the invitee (`@enkaku/group@0.16.1`). */
+    /** Framed MLSMessage(Welcome) bytes for the invitee (`@kumiai/mls`). */
     welcomeMessage: Uint8Array;
     /** Framed MLSMessage(Commit) bytes to fan out to existing members. */
     commitMessage: Uint8Array;
@@ -54,7 +51,7 @@ export type InviteToGroupResult = {
      * Ratchet tree from the post-commit handle. Required by `joinGroup`
      * callers that build an invite payload — they no longer hold a
      * `GroupHandle` reference, so the manager surfaces the tree directly.
-     * Typed `unknown` to match `@enkaku/group`'s `ProcessWelcomeParams.ratchetTree`,
+     * Typed `unknown` to match `@kumiai/mls`'s `ProcessWelcomeParams.ratchetTree`,
      * which is opaque on that side too.
      */
     ratchetTree: unknown;
@@ -84,6 +81,14 @@ export type RemoveGroupMemberParams = {
     stores: StoreProvider;
     groupID: string;
     memberDID: string;
+    /**
+     * The HLC stamped by the caller for the roster tombstone. Lifted out of this
+     * method so the producer can stamp ONE HLC that orders both the MLS-roster
+     * tombstone here and the admin-role revocation it appends in the same
+     * transaction — the two must share a timestamp for the fold to drop exactly
+     * the ex-admin's later control entries.
+     */
+    hlc: string;
 };
 export type RemoveGroupMemberResult = {
     commitMessage: Uint8Array;
@@ -92,62 +97,20 @@ export type LeaveGroupParams = {
     stores: StoreProvider;
     groupID: string;
     identity: OwnIdentity;
+    /**
+     * The HLC stamped by the caller for the self-removal tombstone. Lifted out of
+     * this method so the `leave` producer can stamp ONE HLC that orders both this
+     * self-tombstone and the admin-role self-revocation it appends in the same
+     * transaction — the two must share a timestamp for a receiver's fold to drop
+     * exactly the leaver's control entries signed at or after the departure.
+     */
+    hlc: string;
 };
 export type LeaveGroupResult = undefined;
-export type CreateCircleParams = {
-    stores: StoreProvider;
-    groupID: string;
-    name: string;
-    description?: string;
-    catalogIDs?: Array<string>;
-};
-export type CreateCircleResult = {
-    circleID: string;
-    broadcast: GroupBroadcastMessage;
-};
-export type UpdateCircleParams = {
-    stores: StoreProvider;
-    circleID: string;
-    update: {
-        name?: string;
-        description?: string;
-        catalogIDs?: Array<string>;
-    };
-};
-export type UpdateCircleResult = {
-    broadcast: GroupBroadcastMessage;
-    broadcasts: Array<GroupBroadcastMessage>;
-};
-export type DeleteCircleParams = {
-    stores: StoreProvider;
-    circleID: string;
-};
-export type DeleteCircleResult = {
-    broadcast: GroupBroadcastMessage;
-};
-export type AddCircleMemberParams = {
-    stores: StoreProvider;
-    groupID: string;
-    circleID: string;
-    memberDID: string;
-    role: 'admin' | 'member';
-};
-export type AddCircleMemberResult = {
-    broadcast: GroupBroadcastMessage;
-};
-export type RemoveCircleMemberParams = {
-    stores: StoreProvider;
-    circleID: string;
-    memberDID: string;
-};
-export type RemoveCircleMemberResult = {
-    broadcast: GroupBroadcastMessage;
-};
 export declare class GroupManager {
     #private;
     constructor(params: GroupManagerParams);
     createGroup(params: CreateGroupParams): Promise<CreateGroupResult>;
-    updateGroup(params: UpdateGroupParams): Promise<UpdateGroupResult>;
     inviteToGroup(params: InviteToGroupParams): Promise<InviteToGroupResult>;
     joinGroup(params: JoinGroupParams): Promise<JoinGroupResult>;
     removeMember(params: RemoveMemberParams): Promise<RemoveMemberResult>;
@@ -157,9 +120,4 @@ export declare class GroupManager {
         epoch: number;
         credential: string;
     } | undefined>;
-    createCircle(params: CreateCircleParams): Promise<CreateCircleResult>;
-    updateCircle(params: UpdateCircleParams): Promise<UpdateCircleResult>;
-    deleteCircle(params: DeleteCircleParams): Promise<DeleteCircleResult>;
-    addCircleMember(params: AddCircleMemberParams): Promise<AddCircleMemberResult>;
-    removeCircleMember(params: RemoveCircleMemberParams): Promise<RemoveCircleMemberResult>;
 }