@kubun/plugin-p2p 0.10.1 → 0.12.0

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

@@ -1,7 +1,28 @@
-import type { GroupHandle } from '@enkaku/group';
-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>;
+import type { GroupHandle } from '@kumiai/mls';
+/**
+ * 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 +1,33 @@
-import{replacer as e,reviver as r}from"./mls-json.js";let t=new TextEncoder,n=new TextDecoder;export async function mlsEncryptFramed(r,n){let{message:c,consumed:o}=await r.encrypt(n);return{framed:t.encode(JSON.stringify(c,e)),consumed:o}}export async function mlsDecryptFramed(e,t){let c=JSON.parse(n.decode(t),r);return await e.decrypt(c)}
+/**
+ * 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 {
+        payload,
+        senderDID
+    };
+}

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

@@ -1,11 +1,11 @@
-import type { Encryptor } from '@enkaku/hub-tunnel';
+import type { Encryptor } from '@kumiai/hub-tunnel';
 import type { GroupHandleRegistry } from './group-handle-registry.js';
 export type MLSEncryptorParams = {
     registry: GroupHandleRegistry;
     groupID: string;
 };
 /**
- * Adapts the `GroupHandleRegistry` to the `@enkaku/hub-tunnel` `Encryptor`
+ * Adapts the `GroupHandleRegistry` to the `@kumiai/hub-tunnel` `Encryptor`
  * interface. The registry's per-group mutex serializes encrypt + decrypt
  * across all encryptor instances bound to the same `(registry, groupID)`.
  *

package/lib/groups/mls-encryptor.js

@@ -1 +1,33 @@
-import{mlsDecryptFramed as r,mlsEncryptFramed as t}from"./mls-codec.js";export class MLSEncryptor{#r;#t;constructor(r){this.#r=r.registry,this.#t=r.groupID}encrypt(r){return this.#r.withHandle(this.#t,async s=>{let{framed:e}=await t(s,r);return e})}decrypt(t){return this.#r.withHandle(this.#t,s=>r(s,t))}}
+import { mlsDecryptFramed, mlsEncryptFramed } from './mls-codec.js';
+/**
+ * Adapts the `GroupHandleRegistry` to the `@kumiai/hub-tunnel` `Encryptor`
+ * interface. The registry's per-group mutex serializes encrypt + decrypt
+ * across all encryptor instances bound to the same `(registry, groupID)`.
+ *
+ * Wedge-protection note: encrypt persists the advanced ratchet immediately
+ * on callback success — BEFORE the wire send happens inside the hub-tunnel
+ * transport. If the wire send fails, the persisted state is already at
+ * generation N+1; the next encrypt advances to N+2 and generation N is
+ * "burned" without wire egress. This is the documented forward-secrecy
+ * trade-off for tunnel sessions; the broadcast path (`BroadcastService.
+ * prepareSend`) inverts the order by pulling send into the registry callback.
+ */ export class MLSEncryptor {
+    #registry;
+    #groupID;
+    constructor(params){
+        this.#registry = params.registry;
+        this.#groupID = params.groupID;
+    }
+    encrypt(plaintext) {
+        return this.#registry.withHandle(this.#groupID, (handle)=>mlsEncryptFramed(handle, plaintext));
+    }
+    // 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 '@enkaku/group';
+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 +1,18 @@
-import{restoreGroup as r}from"@enkaku/group";import{deserializeMLSGroupState as o}from"./mls-state.js";export async function restoreMLSGroupHandle(t){let{state:e,credential:n,rootCapability:m}=o(t);return r({state:e,credential:n,rootCapability:m})}
+import { restoreGroup } from '@kumiai/mls';
+import { deserializeMLSGroupState } from './mls-state.js';
+export async function restoreMLSGroupHandle(params) {
+    const { state, credential, ledgerEntries } = deserializeMLSGroupState(params.serialized);
+    return await restoreGroup({
+        state,
+        credential,
+        ledgerEntries,
+        options: {
+            ...params.resolveLedgerEntries != null ? {
+                resolveLedgerEntries: params.resolveLedgerEntries
+            } : {},
+            ...params.onLedgerEntries != null ? {
+                onLedgerEntries: params.onLedgerEntries
+            } : {}
+        }
+    });
+}

package/lib/groups/mls-json.js

@@ -1 +1,17 @@
-import{fromB64 as t,toB64 as e}from"@enkaku/codec";let r="\0bi:",i="\0u8:";export function replacer(t,n){if("bigint"==typeof n)return`${r}${n}`;let o=this[t];return o instanceof Uint8Array?`${i}${e(o)}`:n}export function reviver(e,n){return"string"!=typeof n?n:n.startsWith(r)?BigInt(n.slice(r.length)):n.startsWith(i)?t(n.slice(i.length)):n}
+import { fromB64, toB64 } from '@sozai/codec';
+const BIGINT_PREFIX = '\x00bi:';
+const BYTES_PREFIX = '\x00u8:';
+export function replacer(_key, value) {
+    if (typeof value === 'bigint') return `${BIGINT_PREFIX}${value}`;
+    const raw = this[_key];
+    if (raw instanceof Uint8Array) {
+        return `${BYTES_PREFIX}${toB64(raw)}`;
+    }
+    return value;
+}
+export function reviver(_key, value) {
+    if (typeof value !== 'string') return value;
+    if (value.startsWith(BIGINT_PREFIX)) return BigInt(value.slice(BIGINT_PREFIX.length));
+    if (value.startsWith(BYTES_PREFIX)) return fromB64(value.slice(BYTES_PREFIX.length));
+    return value;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Errors raised while applying a received MLS handshake Commit to the local
+ * group state. Kept in a standalone, transport-independent module so the
+ * `GroupMLS` adapter and any other surviving receive path can import them
+ * without depending on a specific transport implementation.
+ */
+/**
+ * Thrown when a received Commit fails the authenticated MLS check at the
+ * matching epoch (a corrupt or forged Commit). Unrecoverable: redelivery will
+ * not help, so callers should ack-and-skip rather than wedge the group's
+ * ordered receive stream.
+ */
+export declare class DecryptError extends Error {
+    constructor(message: string, cause: unknown);
+}
+/**
+ * Thrown when a received MLS Commit targets a future epoch the local handle has
+ * not reached yet (a gap in the in-order Commit stream). Callers should NOT ack
+ * — the hub redelivers in order, so the gap-filling Commit arrives first and
+ * this one applies on a later delivery.
+ */
+export declare class CommitOutOfOrderError extends Error {
+    #private;
+    constructor(messageEpoch: bigint, handleEpoch: bigint);
+    get messageEpoch(): bigint;
+    get handleEpoch(): bigint;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Errors raised while applying a received MLS handshake Commit to the local
+ * group state. Kept in a standalone, transport-independent module so the
+ * `GroupMLS` adapter and any other surviving receive path can import them
+ * without depending on a specific transport implementation.
+ */ /**
+ * Thrown when a received Commit fails the authenticated MLS check at the
+ * matching epoch (a corrupt or forged Commit). Unrecoverable: redelivery will
+ * not help, so callers should ack-and-skip rather than wedge the group's
+ * ordered receive stream.
+ */ export class DecryptError extends Error {
+    constructor(message, cause){
+        super(message, {
+            cause
+        });
+        this.name = 'DecryptError';
+    }
+}
+/**
+ * Thrown when a received MLS Commit targets a future epoch the local handle has
+ * not reached yet (a gap in the in-order Commit stream). Callers should NOT ack
+ * — the hub redelivers in order, so the gap-filling Commit arrives first and
+ * this one applies on a later delivery.
+ */ export class CommitOutOfOrderError extends Error {
+    #messageEpoch;
+    #handleEpoch;
+    constructor(messageEpoch, handleEpoch){
+        super(`MLS commit epoch ${messageEpoch} ahead of handle epoch ${handleEpoch}`);
+        this.name = 'CommitOutOfOrderError';
+        this.#messageEpoch = messageEpoch;
+        this.#handleEpoch = handleEpoch;
+    }
+    get messageEpoch() {
+        return this.#messageEpoch;
+    }
+    get handleEpoch() {
+        return this.#handleEpoch;
+    }
+}

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

@@ -1,14 +1,16 @@
-import { type ClientState, type GroupHandle, type MemberCredential } from '@enkaku/group';
 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

@@ -1 +1,79 @@
-import{decodeClientState as t,encodeClientState as e}from"@enkaku/group";import{normalizeCredential as o}from"../context/types.js";export function serializeMLSGroupState(t){return{mlsState:e(t.state),credential:JSON.stringify(t.credential),epoch:Number(t.epoch),rootCapability:t.rootCapability}}export function deserializeMLSGroupState(e){let o=t(e.mlsState);if(null==o)throw Error("Could not decode ClientState");return{state:o,credential:JSON.parse(e.credential),rootCapability:e.rootCapability}}export function fromMLSStateRow(t){return{mlsState:t.mls_state,credential:o(t.credential),epoch:t.epoch,rootCapability:t.root_capability}}export function toMLSStateInsert(t,e,o){return{group_id:e,device_id:o,mls_state:t.mlsState,credential:t.credential,epoch:t.epoch,root_capability:t.rootCapability}}
+import { decodeClientState, encodeClientState } from '@kumiai/mls';
+import { normalizeCredential } from '../context/types.js';
+/**
+ * Serialize a GroupHandle's state for persistence.
+ * The implementer must verify the serialization approach works
+ * with the installed version of ts-mls.
+ */ export function serializeMLSGroupState(group) {
+    return {
+        mlsState: encodeClientState(group.state),
+        credential: JSON.stringify(group.credential),
+        epoch: Number(group.epoch),
+        // 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)
+    };
+}
+/**
+ * Deserialize persisted state back into GroupHandle constructor params.
+ * Returns the params needed to reconstruct a GroupHandle.
+ */ export function deserializeMLSGroupState(serialized) {
+    const state = decodeClientState(serialized.mlsState);
+    if (state == null) {
+        throw new Error('Could not decode ClientState');
+    }
+    return {
+        state,
+        credential: JSON.parse(serialized.credential),
+        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`.
+ *
+ * Credential is stored as TEXT but Kysely's `ParseJSONResultsPlugin` may have
+ * already parsed it into an object on read. `SerializedMLSGroupState.credential`
+ * is a JSON string, so re-stringify when needed.
+ */ export function fromMLSStateRow(row) {
+    return {
+        mlsState: row.mls_state,
+        credential: normalizeCredential(row.credential),
+        epoch: row.epoch,
+        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`.
+ */ export function toMLSStateInsert(serialized, groupID, deviceID) {
+    return {
+        group_id: groupID,
+        device_id: deviceID,
+        mls_state: serialized.mlsState,
+        credential: serialized.credential,
+        epoch: serialized.epoch,
+        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 {};