@kubun/plugin-p2p 0.11.0 → 0.12.1

package/lib/groups/mls-codec.d.ts

@@ -1,7 +1,28 @@
 import type { GroupHandle } from '@kumiai/mls';
-export type MLSEncryptFramedResult = {
-    framed: Uint8Array;
-    consumed: Array<Uint8Array>;
-};
-export declare function mlsEncryptFramed(handle: GroupHandle, plaintext: Uint8Array): Promise<MLSEncryptFramedResult>;
-export declare function mlsDecryptFramed(handle: GroupHandle, framed: Uint8Array): Promise<Uint8Array>;
+/**
+ * Encrypt an application message for the group. `@kumiai/mls` returns framed MLS
+ * wire bytes, so kubun puts those on the wire directly — no JSON envelope of its
+ * own, and no retired secret material crossing the boundary.
+ */
+export declare function mlsEncryptFramed(handle: GroupHandle, plaintext: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decrypt a received application message and recover WHO SENT IT.
+ *
+ * `handle.decrypt` rather than `processMessage`, which returns an application
+ * message's plaintext with no sender. The sender is AUTHENTICATED, not claimed:
+ * the leaf index rides sender-data encrypted under the epoch's sender-data
+ * secret, and the body opens only under the ratchet key derived at that leaf, so
+ * a frame naming a leaf it was not sealed at does not open at all.
+ *
+ * A missing sender is an ERROR, never a filled-in blank. Upstream types
+ * `senderDID` optional because the authenticated leaf may hold no parsable
+ * credential — "I cannot name the author", never "there is no author". Any
+ * placeholder (empty string, a transport-claimed DID) would hand callers an
+ * unauthenticated value wearing an authenticated one's type, so the open fails
+ * instead. Callers already treat a throw here as ordinary control flow:
+ * `decrypt` throws for every epoch but its own.
+ */
+export declare function mlsDecryptFramed(handle: GroupHandle, framed: Uint8Array): Promise<{
+    payload: Uint8Array;
+    senderDID: string;
+}>;

package/lib/groups/mls-codec.js

@@ -1,18 +1,33 @@
-import { anchorImmutabilityPolicy } from './group-anchor.js';
-import { replacer, reviver } from './mls-json.js';
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder();
-export async function mlsEncryptFramed(handle, plaintext) {
-    const { message, consumed } = await handle.encrypt(plaintext);
-    const framed = textEncoder.encode(JSON.stringify(message, replacer));
+/**
+ * Encrypt an application message for the group. `@kumiai/mls` returns framed MLS
+ * wire bytes, so kubun puts those on the wire directly — no JSON envelope of its
+ * own, and no retired secret material crossing the boundary.
+ */ export async function mlsEncryptFramed(handle, plaintext) {
+    return await handle.encrypt(plaintext);
+}
+/**
+ * Decrypt a received application message and recover WHO SENT IT.
+ *
+ * `handle.decrypt` rather than `processMessage`, which returns an application
+ * message's plaintext with no sender. The sender is AUTHENTICATED, not claimed:
+ * the leaf index rides sender-data encrypted under the epoch's sender-data
+ * secret, and the body opens only under the ratchet key derived at that leaf, so
+ * a frame naming a leaf it was not sealed at does not open at all.
+ *
+ * A missing sender is an ERROR, never a filled-in blank. Upstream types
+ * `senderDID` optional because the authenticated leaf may hold no parsable
+ * credential — "I cannot name the author", never "there is no author". Any
+ * placeholder (empty string, a transport-claimed DID) would hand callers an
+ * unauthenticated value wearing an authenticated one's type, so the open fails
+ * instead. Callers already treat a throw here as ordinary control flow:
+ * `decrypt` throws for every epoch but its own.
+ */ export async function mlsDecryptFramed(handle, framed) {
+    const { payload, senderDID } = await handle.decrypt(framed);
+    if (senderDID == null) {
+        throw new Error('MLS application message opened at a leaf with no nameable sender');
+    }
     return {
-        framed,
-        consumed
+        payload,
+        senderDID
     };
 }
-export async function mlsDecryptFramed(handle, framed) {
-    const message = JSON.parse(textDecoder.decode(framed), reviver);
-    return await handle.decrypt(message, {
-        commitPolicy: anchorImmutabilityPolicy
-    });
-}

package/lib/groups/mls-encryptor.js

@@ -19,12 +19,15 @@ import { mlsDecryptFramed, mlsEncryptFramed } from './mls-codec.js';
         this.#groupID = params.groupID;
     }
     encrypt(plaintext) {
-        return this.#registry.withHandle(this.#groupID, async (handle)=>{
-            const { framed } = await mlsEncryptFramed(handle, plaintext);
-            return framed;
-        });
+        return this.#registry.withHandle(this.#groupID, (handle)=>mlsEncryptFramed(handle, plaintext));
     }
-    decrypt(ciphertext) {
-        return this.#registry.withHandle(this.#groupID, (handle)=>mlsDecryptFramed(handle, ciphertext));
+    // The `Encryptor` port is bytes-in/bytes-out, so the authenticated sender the
+    // open also recovers is discarded here. The sync-transport path this serves
+    // carries its own per-entry signed tokens and authorizes on those; it has no
+    // seam to receive a frame sender through. Dropping it is deliberate — not an
+    // oversight to be routed around by widening the port.
+    async decrypt(ciphertext) {
+        const { payload } = await this.#registry.withHandle(this.#groupID, (handle)=>mlsDecryptFramed(handle, ciphertext));
+        return payload;
     }
 }

package/lib/groups/mls-group-handle.d.ts

@@ -1,4 +1,39 @@
-import { type GroupHandle } from '@kumiai/mls';
+import { type GroupHandle, type VerifiedLedgerEntry } from '@kumiai/mls';
 import { type SerializedMLSGroupState } from './mls-state.js';
 export type MLSGroupHandle = GroupHandle;
-export declare function restoreMLSGroupHandle(serialized: SerializedMLSGroupState): Promise<MLSGroupHandle>;
+/**
+ * Fetch control-ledger entry bodies a handle does not hold, by content id.
+ *
+ * A commit's envelope names the entries it enacts by content id, not by body, and
+ * the ONLY source for a body a receiver lacks is the commit's own frame, wired in
+ * for the duration of applying it. The answer is untrusted: only a token whose
+ * digest matches the requested id and whose signature verifies is kept.
+ *
+ * A handle built without a resolver resolves nothing, deliberately: kubun's store
+ * writes its copy AFTER apply, so reading it would answer every miss with an empty
+ * list — indistinguishable from a resolver that ran. Passing none instead lets
+ * `MissingLedgerEntriesError` reach the lane, which drops the frame as poison.
+ */
+export type LedgerEntryResolver = (ids: Array<string>) => Promise<Array<string>>;
+/**
+ * Receive the notarized non-`group.role` entries an accepted commit carried, in
+ * envelope order. Synchronous by contract, so a sink can only COLLECT: any store
+ * write the entries drive must run after `processMessage` returns.
+ */
+export type LedgerEntrySink = (entries: Array<VerifiedLedgerEntry>) => void;
+export type RestoreMLSGroupHandleParams = {
+    serialized: SerializedMLSGroupState;
+    /**
+     * Resolves the entry bodies a received commit's envelope names, from the
+     * commit's own frame. Supplied only while the restored handle is applying such
+     * a commit.
+     */
+    resolveLedgerEntries?: LedgerEntryResolver;
+    /**
+     * Collects the notarized entries an accepted commit surfaces on this handle,
+     * so the caller can fold them into the projections once `processMessage` has
+     * returned.
+     */
+    onLedgerEntries?: LedgerEntrySink;
+};
+export declare function restoreMLSGroupHandle(params: RestoreMLSGroupHandleParams): Promise<MLSGroupHandle>;

package/lib/groups/mls-group-handle.js

@@ -1,10 +1,18 @@
 import { restoreGroup } from '@kumiai/mls';
 import { deserializeMLSGroupState } from './mls-state.js';
-export async function restoreMLSGroupHandle(serialized) {
-    const { state, credential, rootCapability } = deserializeMLSGroupState(serialized);
-    return restoreGroup({
+export async function restoreMLSGroupHandle(params) {
+    const { state, credential, ledgerEntries } = deserializeMLSGroupState(params.serialized);
+    return await restoreGroup({
         state,
         credential,
-        rootCapability
+        ledgerEntries,
+        options: {
+            ...params.resolveLedgerEntries != null ? {
+                resolveLedgerEntries: params.resolveLedgerEntries
+            } : {},
+            ...params.onLedgerEntries != null ? {
+                onLedgerEntries: params.onLedgerEntries
+            } : {}
+        }
     });
 }

package/lib/groups/mls-receive-errors.d.ts

@@ -11,9 +11,7 @@
  * ordered receive stream.
  */
 export declare class DecryptError extends Error {
-    #private;
     constructor(message: string, cause: unknown);
-    get cause(): unknown;
 }
 /**
  * Thrown when a received MLS Commit targets a future epoch the local handle has

package/lib/groups/mls-receive-errors.js

@@ -9,14 +9,11 @@
  * not help, so callers should ack-and-skip rather than wedge the group's
  * ordered receive stream.
  */ export class DecryptError extends Error {
-    #cause;
     constructor(message, cause){
-        super(message);
+        super(message, {
+            cause
+        });
         this.name = 'DecryptError';
-        this.#cause = cause;
-    }
-    get cause() {
-        return this.#cause;
     }
 }
 /**

package/lib/groups/mls-state.d.ts

@@ -2,13 +2,15 @@ import type { GroupMLSState, InsertGroupMLSState } from '@kubun/store-p2p';
 import { type ClientState, type GroupHandle, type MemberCredential } from '@kumiai/mls';
 /**
  * Serialized form of a GroupHandle for DB persistence.
- * The MLS ClientState is opaque binary; the credential is JSON.
+ * The MLS ClientState is opaque binary; the credential and the control-ledger
+ * tokens are JSON.
  */
 export type SerializedMLSGroupState = {
     mlsState: Uint8Array;
     credential: string;
     epoch: number;
-    rootCapability: string;
+    /** The handle's signed ledger tokens, in enactment order, JSON-encoded. */
+    ledgerEntries: string;
 };
 /**
  * Serialize a GroupHandle's state for persistence.
@@ -19,7 +21,7 @@ export declare function serializeMLSGroupState(group: GroupHandle): SerializedML
 export type MLSGroupState = {
     state: ClientState;
     credential: MemberCredential;
-    rootCapability: string;
+    ledgerEntries: Array<string>;
 };
 /**
  * Deserialize persisted state back into GroupHandle constructor params.

package/lib/groups/mls-state.js

@@ -9,7 +9,10 @@ import { normalizeCredential } from '../context/types.js';
         mlsState: encodeClientState(group.state),
         credential: JSON.stringify(group.credential),
         epoch: Number(group.epoch),
-        rootCapability: group.rootCapability
+        // The tokens are the ledger's only export form — the verified entries a
+        // handle folds cannot be reconstructed from anything else — so persisting
+        // them is what lets a restored handle refold the roster it had.
+        ledgerEntries: JSON.stringify(group.ledgerTokens)
     };
 }
 /**
@@ -23,9 +26,23 @@ import { normalizeCredential } from '../context/types.js';
     return {
         state,
         credential: JSON.parse(serialized.credential),
-        rootCapability: serialized.rootCapability
+        ledgerEntries: parseLedgerEntries(serialized.ledgerEntries)
     };
 }
+/**
+ * Ledger tokens are stored as a JSON array of strings. An empty column (a row
+ * written before any entry was enacted) parses to an empty ledger, which folds
+ * to the anchor-seeded roster — the same state the handle held.
+ */ function parseLedgerEntries(value) {
+    if (value === '') {
+        return [];
+    }
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed)) {
+        throw new Error('Could not decode persisted control-ledger tokens');
+    }
+    return parsed;
+}
 /**
  * Map a persisted `GroupMLSState` DB row to the `SerializedMLSGroupState` shape
  * expected by `BroadcastService.prepareSend` / `processReceived`.
@@ -38,9 +55,15 @@ import { normalizeCredential } from '../context/types.js';
         mlsState: row.mls_state,
         credential: normalizeCredential(row.credential),
         epoch: row.epoch,
-        rootCapability: row.root_capability
+        ledgerEntries: normalizeLedgerEntriesColumn(row.ledger_entries)
     };
 }
+/**
+ * The ledger-tokens column is TEXT, but `ParseJSONResultsPlugin` may hand back
+ * an already-parsed array — the same asymmetry `normalizeCredential` handles.
+ */ function normalizeLedgerEntriesColumn(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
 /**
  * Map a `SerializedMLSGroupState` plus scope (group + device) to an
  * `InsertGroupMLSState` row suitable for `P2PStoreAPI.saveMLSState`.
@@ -51,6 +74,6 @@ import { normalizeCredential } from '../context/types.js';
         mls_state: serialized.mlsState,
         credential: serialized.credential,
         epoch: serialized.epoch,
-        root_capability: serialized.rootCapability
+        ledger_entries: serialized.ledgerEntries
     };
 }

package/lib/groups/peer-presence.d.ts

@@ -0,0 +1,90 @@
+import type { StoreProvider } from '@kubun/db';
+import { HLC } from '@kubun/hlc';
+import type { Logger } from '@kubun/logger';
+import type { GatheredPeer, LocalPeerAnnouncement, PeerGatherOptions, PresenceReason } from '../types.js';
+import type { GroupBroadcastMessage } from './broadcast.js';
+import type { PeerQueryParam } from './group-protocols.js';
+/** One `peer/query` reply as the gather surface hands it back. */
+type RawReply = {
+    senderDID: string;
+    value: unknown;
+};
+export type PeerPresenceParams = {
+    stores: StoreProvider;
+    /** This device's authenticated DID. */
+    localDID: string;
+    /** Device-wide clock. Every announcement is stamped from it and never by a caller. */
+    hlc: HLC;
+    /** The epoch stamped onto this device's own row, as the apply path stamps a received one. */
+    getGroupEpoch: (groupID: string) => number | undefined;
+    /** Fan one broadcast out across every live peer of the group. */
+    publish: (groupID: string, message: GroupBroadcastMessage) => Promise<void>;
+    /** Gather `peer/query` replies from the group's live peers. */
+    query: (groupID: string, param: PeerQueryParam, options: PeerGatherOptions) => Promise<Array<RawReply>>;
+    /**
+     * Fold one reply into the projection through the SAME apply a broadcast frame
+     * takes, so a gathered announcement and a pushed one cannot diverge.
+     */
+    applyAnnouncement: (groupID: string, message: GroupBroadcastMessage) => Promise<void>;
+    /** Every group this device currently belongs to, for a device-wide announce. */
+    joinedGroupIDs: () => Array<string>;
+    /**
+     * Called after this device declares (or redeclares) its profile — the moment
+     * it becomes visible, and so the moment a co-member may start dialling it.
+     * Whatever answers those dials is stood up here rather than on a timer.
+     */
+    onProfileSet?: () => void;
+    logger?: Logger;
+};
+/**
+ * Everything that makes this device visible to its co-members, and everything
+ * that asks who else is.
+ *
+ * A GATHER IS LIVENESS, NEVER MEMBERSHIP. It reports who answered inside a
+ * window; it never deletes a row, and a device that says nothing keeps whatever
+ * it last said. Only a roster removal deletes.
+ */
+export type PeerPresence = {
+    /** Record what this device is, then announce it to every group it belongs to. */
+    setProfile: (profile: LocalPeerAnnouncement) => Promise<void>;
+    getProfile: () => Promise<LocalPeerAnnouncement | null>;
+    /**
+     * Announce this device's stored profile to one group. Reports whether anything
+     * was said — a device with no profile advertises nothing rather than inventing
+     * a label for itself.
+     */
+    announce: (groupID: string) => Promise<boolean>;
+    /** Ask who is live. Annotates the projection; never prunes it. */
+    gather: (groupID: string, options?: PeerGatherOptions) => Promise<Array<GatheredPeer>>;
+    /**
+     * Announce, then gather — what "I have just (re)appeared" means, and what every
+     * internal trigger runs.
+     *
+     * A device with no declared profile does NEITHER: presence is opt-in, and a host
+     * that never said what its device is has not joined the peer lane. So the whole
+     * invariant is "no profile, no peer-lane traffic" — an explicit
+     * {@link PeerPresence.gather} still asks, because there the host did.
+     */
+    refresh: (groupID: string, options?: PeerGatherOptions) => Promise<Array<GatheredPeer>>;
+    /** Fire-and-forget {@link refresh}, off the current turn. For an event handler. */
+    scheduleRefresh: (groupID: string, reason: PresenceReason) => void;
+    /**
+     * Fire-and-forget {@link announce}, off the current turn and COALESCED per
+     * group. Only the epoch lane uses this, and only it needs to: a device catching
+     * up walks many commits back to back, and one announce per commit is a storm
+     * where one announce per burst is the same information.
+     */
+    scheduleAnnounce: (groupID: string, reason: PresenceReason) => void;
+    /**
+     * Stop scheduling, and WAIT for whatever is already running.
+     *
+     * Cancelling the pending timers is only half of it: a scheduled task whose
+     * timer has already fired is a live store read, and the caller's next step is
+     * closing the database. On Postgres a query overlapping the close wedges it
+     * permanently, so abandoning that read hangs the shutdown it was meant to
+     * finish.
+     */
+    dispose: () => Promise<void>;
+};
+export declare function createPeerPresence(params: PeerPresenceParams): PeerPresence;
+export {};