@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/groups/commit-journal.d.ts

@@ -0,0 +1,14 @@
+import type { StoreProvider } from '@kubun/db';
+import type { CommitJournal } from '@kumiai/rpc';
+/**
+ * The `@kumiai/rpc` `CommitJournal` port for one group, backed by the device's
+ * single-slot commit-journal store. The port carries no group scope — the group
+ * a peer commits to is fixed for its lifetime — so the adapter closes over
+ * `groupID` and threads it into every store call.
+ *
+ * `get` maps the store's raw selectable (snake_case, decoded blobs) to the port's
+ * `JournalEntry`: an absent row is `null`, a null `accepted_as` omits `acceptedAs`
+ * (the outcome is unknown until the hub answers), and `commit`/`journal` are
+ * copied into fresh `Uint8Array`s the port owns.
+ */
+export declare function createCommitJournal(stores: StoreProvider, groupID: string): CommitJournal;

package/lib/groups/commit-journal.js

@@ -0,0 +1,65 @@
+import { getP2PStore } from '@kubun/store-p2p';
+/**
+ * The `@kumiai/rpc` `CommitJournal` port for one group, backed by the device's
+ * single-slot commit-journal store. The port carries no group scope — the group
+ * a peer commits to is fixed for its lifetime — so the adapter closes over
+ * `groupID` and threads it into every store call.
+ *
+ * `get` maps the store's raw selectable (snake_case, decoded blobs) to the port's
+ * `JournalEntry`: an absent row is `null`, a null `accepted_as` omits `acceptedAs`
+ * (the outcome is unknown until the hub answers), and `commit`/`journal` are
+ * copied into fresh `Uint8Array`s the port owns.
+ */ export function createCommitJournal(stores, groupID) {
+    return {
+        async put (entry) {
+            const store = await getP2PStore(stores);
+            await store.putCommitJournalEntry({
+                groupID,
+                publishID: entry.publishID,
+                expectedHead: entry.expectedHead,
+                epoch: entry.epoch,
+                ...entry.acceptedAs != null ? {
+                    acceptedAs: entry.acceptedAs
+                } : {},
+                commit: entry.commit,
+                bodies: entry.bodies,
+                kind: entry.kind,
+                journal: entry.journal
+            });
+        },
+        async markAccepted (publishID, sequenceID) {
+            const store = await getP2PStore(stores);
+            await store.markCommitJournalAccepted({
+                groupID,
+                publishID,
+                sequenceID
+            });
+        },
+        async get () {
+            const store = await getP2PStore(stores);
+            const row = await store.getCommitJournalEntry(groupID);
+            if (row == null) {
+                return null;
+            }
+            return {
+                publishID: row.publish_id,
+                expectedHead: row.expected_head,
+                epoch: row.epoch,
+                ...row.accepted_as != null ? {
+                    acceptedAs: row.accepted_as
+                } : {},
+                commit: new Uint8Array(row.commit),
+                bodies: row.bodies,
+                kind: row.kind,
+                journal: new Uint8Array(row.journal)
+            };
+        },
+        async clear (publishID) {
+            const store = await getP2PStore(stores);
+            await store.clearCommitJournalEntry({
+                groupID,
+                publishID
+            });
+        }
+    };
+}

package/lib/groups/control-request.d.ts

@@ -0,0 +1,66 @@
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import { type ControlRequest, type ControlRequestOutcome } from '@kubun/store-p2p';
+import type { ControlRequestData } from '../types.js';
+import type { P2PEventEmitter } from './events.js';
+/**
+ * Project a stored control-request row into its API-facing shape. `kind` and
+ * `status` are stored as bare text (no CHECK constraint), so the store types
+ * them as `string`; only this store's own writers ever produce them, and they
+ * write nothing outside the two unions.
+ */
+export declare function toControlRequestData(row: ControlRequest): ControlRequestData;
+export type SettleControlRequestParams = {
+    stores: StoreProvider;
+    requestID: string;
+    outcome: ControlRequestOutcome;
+    error?: string;
+    /**
+     * The artifact this request produced. Written in the same update as the
+     * status and BEFORE the announcement, so a caller woken by the settle always
+     * finds it there.
+     */
+    result?: string;
+    emitter?: P2PEventEmitter;
+    logger?: Logger;
+};
+/**
+ * Record a control request's terminal outcome and announce it.
+ *
+ * The row is RETAINED — a client holding the id must be able to read the
+ * outcome back — so this only moves `status`/`error`/`settledAt`; the row
+ * leaves on ack alone. The announcement carries the row as it was just
+ * written, read back rather than reconstructed, so a subscriber and a later
+ * query never disagree about the outcome.
+ *
+ * Settling an id with no row (already acked, or never enqueued) is a silent
+ * no-op that announces nothing: there is no outcome for anyone to observe.
+ *
+ * Never throws. Callers are the commit lane and the drive-failure path, where
+ * the outcome has already happened — a bookkeeping fault here cannot un-happen
+ * it, and must not turn an accepted commit into a lane error.
+ */
+export declare function settleControlRequest(params: SettleControlRequestParams): Promise<void>;
+export type AwaitControlRequestSettledParams = {
+    stores: StoreProvider;
+    emitter: P2PEventEmitter;
+    requestID: string;
+    /** Rejects once this many milliseconds pass with the request still pending. */
+    timeoutMs: number;
+};
+/**
+ * Resolve when a control request reaches a terminal status.
+ *
+ * Both halves are load-bearing. The subscription alone loses every request that
+ * settles before the caller gets here — the common case for a fast lane — and
+ * the store read alone cannot observe a settle that has not happened yet. The
+ * listener is registered BEFORE the read so there is no window between them
+ * where a settle is neither in the row nor in the stream.
+ *
+ * The timeout is mandatory and REJECTS: callers await this inside a mutation,
+ * where an unbounded wait is a request that never answers. A request with no
+ * row (never enqueued, or already acked) is indistinguishable from one whose
+ * enqueue has not committed yet, so it waits rather than failing fast, and the
+ * timeout is what ends it.
+ */
+export declare function awaitControlRequestSettled(params: AwaitControlRequestSettledParams): Promise<ControlRequestData>;

package/lib/groups/control-request.js

@@ -0,0 +1,101 @@
+import { getP2PStore } from '@kubun/store-p2p';
+/**
+ * Project a stored control-request row into its API-facing shape. `kind` and
+ * `status` are stored as bare text (no CHECK constraint), so the store types
+ * them as `string`; only this store's own writers ever produce them, and they
+ * write nothing outside the two unions.
+ */ export function toControlRequestData(row) {
+    return {
+        id: row.id,
+        groupID: row.group_id,
+        kind: row.kind,
+        status: row.status,
+        error: row.error,
+        enqueuedAt: row.enqueued_at,
+        settledAt: row.settled_at
+    };
+}
+/**
+ * Record a control request's terminal outcome and announce it.
+ *
+ * The row is RETAINED — a client holding the id must be able to read the
+ * outcome back — so this only moves `status`/`error`/`settledAt`; the row
+ * leaves on ack alone. The announcement carries the row as it was just
+ * written, read back rather than reconstructed, so a subscriber and a later
+ * query never disagree about the outcome.
+ *
+ * Settling an id with no row (already acked, or never enqueued) is a silent
+ * no-op that announces nothing: there is no outcome for anyone to observe.
+ *
+ * Never throws. Callers are the commit lane and the drive-failure path, where
+ * the outcome has already happened — a bookkeeping fault here cannot un-happen
+ * it, and must not turn an accepted commit into a lane error.
+ */ export async function settleControlRequest(params) {
+    try {
+        const store = await getP2PStore(params.stores);
+        await store.settleControlRequest({
+            id: params.requestID,
+            outcome: params.outcome,
+            ...params.error != null ? {
+                error: params.error
+            } : {},
+            ...params.result != null ? {
+                result: params.result
+            } : {},
+            settledAt: new Date().toISOString()
+        });
+        const row = await store.getControlRequest(params.requestID);
+        if (row == null || params.emitter == null) {
+            return;
+        }
+        await params.emitter.emit('controlRequestSettled', toControlRequestData(row));
+    } catch (error) {
+        params.logger?.error('settling a control request failed', {
+            requestID: params.requestID,
+            outcome: params.outcome,
+            error
+        });
+    }
+}
+/**
+ * Resolve when a control request reaches a terminal status.
+ *
+ * Both halves are load-bearing. The subscription alone loses every request that
+ * settles before the caller gets here — the common case for a fast lane — and
+ * the store read alone cannot observe a settle that has not happened yet. The
+ * listener is registered BEFORE the read so there is no window between them
+ * where a settle is neither in the row nor in the stream.
+ *
+ * The timeout is mandatory and REJECTS: callers await this inside a mutation,
+ * where an unbounded wait is a request that never answers. A request with no
+ * row (never enqueued, or already acked) is indistinguishable from one whose
+ * enqueue has not committed yet, so it waits rather than failing fast, and the
+ * timeout is what ends it.
+ */ export async function awaitControlRequestSettled(params) {
+    const { requestID } = params;
+    let unsubscribe;
+    let timer;
+    try {
+        const settled = new Promise((resolve, reject)=>{
+            unsubscribe = params.emitter.on('controlRequestSettled', (data)=>{
+                if (data.id === requestID) {
+                    resolve(data);
+                }
+            });
+            timer = setTimeout(()=>{
+                reject(new Error(`control request ${requestID} did not settle in ${params.timeoutMs}ms`));
+            }, params.timeoutMs);
+        });
+        const store = await getP2PStore(params.stores);
+        const row = await store.getControlRequest(requestID);
+        if (row != null && row.status !== 'pending') {
+            return toControlRequestData(row);
+        }
+        return await settled;
+    } finally{
+        unsubscribe?.();
+        if (timer != null) {
+            clearTimeout(timer);
+        }
+    }
+}

package/lib/groups/events.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from '@sozai/event';
-import type { CircleData, CircleMemberData, DelegationData, GroupData, GroupHealthData, GroupMemberData, RevokedDelegationData } from '../types.js';
+import type { CircleData, CircleMemberData, ControlRequestData, DelegationData, GroupData, GroupHealthData, GroupMemberData, HubServerDIDChangedData, RevokedDelegationData } from '../types.js';
 export type P2PEventMap = {
     groupJoined: GroupData;
     groupLeft: GroupData & {
@@ -55,9 +55,22 @@ export type P2PEventMap = {
         hubID: string;
         hubURL: string;
     };
+    /**
+     * The hub at this URL answers under a different DID than the device had
+     * recorded; the new one is adopted and the connection re-dialled with it.
+     */
+    hubServerDIDChanged: HubServerDIDChangedData;
     delegationTokenAdded: DelegationData;
     delegationTokenRevoked: RevokedDelegationData;
     groupHealthChanged: GroupHealthData;
+    /**
+     * A control request reached a terminal status; carries the settled request as
+     * it was written, so a subscriber and a later query agree on the outcome.
+     * Emitted by the commit lane when a commit lands, by the drive path when the
+     * lane refuses one, and by the restart adopt path for a commit whose process
+     * died before it could report.
+     */
+    controlRequestSettled: ControlRequestData;
 };
 export type P2PEventEmitter = EventEmitter<P2PEventMap>;
 export declare function createP2PEventEmitter(): P2PEventEmitter;

package/lib/groups/group-anchor.d.ts

@@ -1,63 +1,24 @@
-import { type Capabilities, type GroupContextExtension, type GroupHandle, type IncomingMessageCallback } from '@kumiai/mls';
+import type { GroupContextExtension } from '@kumiai/mls';
+import { type GroupAnchor } from '@kumiai/mls';
 /**
- * MLS GroupContext extension type carrying the genesis anchor. A uint16 outside
- * the MLS default extension types (1–5) and clear of every reserved GREASE
- * value, so it can never collide with a ts-mls built-in or a probing extension.
+ * The anchor's opaque `app` slot as kubun writes it. `@kumiai/mls` owns the
+ * anchor container (creator DID, version) and never reads this payload.
+ *
+ * `recoverySecret` is base64 of 32 cryptographically-random bytes minted once at
+ * group creation. It is the epoch-independent seed for the non-rotating
+ * handshake/recovery topic: baked into the MLS GroupContext, authenticated by
+ * the GroupInfo signature, so every member on every epoch derives the same
+ * rendezvous and a peer stranded on a stale epoch can always rejoin.
  */
-export declare const GROUP_ANCHOR_EXTENSION_TYPE = 61696;
-/**
- * Genesis anchor baked into the MLS GroupContext at group creation: the creator
- * DID is the epoch-0 admin. It survives every epoch and is authenticated by the
- * GroupInfo signature, so every joiner reads the same value. Treated as
- * immutable for the lifetime of the group.
- */
-export type GroupAnchor = {
-    creatorDID: string;
-    version: number;
-    /**
-     * Base64 of 32 cryptographically-random bytes minted once at group creation.
-     * It is the epoch-independent seed for the non-rotating handshake/recovery
-     * topic: baked into the MLS GroupContext, authenticated by the GroupInfo
-     * signature, so every member on every epoch derives the same rendezvous and a
-     * peer stranded on a stale epoch can always rejoin. Immutable for the group's
-     * whole life.
-     */
+export type GroupAnchorApp = {
     recoverySecret: string;
 };
-export declare function encodeGroupAnchor(anchor: GroupAnchor): Uint8Array;
-/**
- * Tolerant decode: returns null on malformed bytes or wrong shape. The
- * `recoverySecret` is required and must be a non-empty string — an anchor
- * without it cannot seed the recovery rendezvous, so a missing/empty value is a
- * malformed anchor, not a tolerated absence.
- */
-export declare function decodeGroupAnchor(bytes: Uint8Array): GroupAnchor | null;
-export declare function buildGroupAnchorExtension(anchor: GroupAnchor): GroupContextExtension;
-export declare function buildCurrentGroupAnchorExtension(creatorDID: string, recoverySecret: string): GroupContextExtension;
-/**
- * Leaf-node capabilities advertising the genesis-anchor extension. RFC 9420
- * requires every member leaf to advertise each custom GroupContext extension
- * type, or `commitInvite` rejects the added leaf. Pass these at both
- * `createGroup` (creator leaf) and `createKeyPackageBundle` (invitee leaf) so an
- * anchored group can be joined.
- */
-export declare function groupAnchorCapabilities(): Capabilities;
-/**
- * Commit policy enforcing genesis-anchor immutability. The anchor lives in the
- * GroupContext extensions and is written once at group creation; kubun issues no
- * group-context-extensions proposal through any normal path, so any incoming
- * commit or proposal carrying one is anomalous and is refused before it can
- * alter the anchor. Refine to inspect the specific extension type if a future
- * feature legitimately mutates non-anchor group-context extensions.
- */
-export declare const anchorImmutabilityPolicy: IncomingMessageCallback;
+/** Build the genesis-anchor extension for a group kubun is creating. */
+export declare function buildKubunGroupAnchorExtension(creatorDID: string, recoverySecret: string): GroupContextExtension;
 /**
- * Read the genesis anchor from a group handle. Returns null only when the anchor
- * extension is genuinely absent (a group created before the anchor, or
- * external). A present-but-undecodable extension is corruption, not absence, and
- * throws — so the control gate treats it as "anchor unreadable" and fails closed
- * rather than silently downgrading to the forgeable role-column gate. (The anchor
- * is kubun-written, frozen by the immutability commit policy, and authenticated
- * by the GroupInfo signature, so this is a corruption guard, not a forgery path.)
+ * Read the recovery seed out of an anchor's `app` slot. Throws when the payload
+ * is missing or malformed: the anchor is written once by kubun and authenticated
+ * by the GroupInfo signature, so an unreadable seed is corruption, not absence,
+ * and a group whose seed cannot be read cannot participate in recovery.
  */
-export declare function readGroupAnchor(handle: GroupHandle): GroupAnchor | null;
+export declare function readRecoverySecret(anchor: GroupAnchor): string;

package/lib/groups/group-anchor.js

@@ -1,107 +1,22 @@
-import { defaultCapabilities, defaultProposalTypes, makeCustomExtension } from '@kumiai/mls';
-/**
- * MLS GroupContext extension type carrying the genesis anchor. A uint16 outside
- * the MLS default extension types (1–5) and clear of every reserved GREASE
- * value, so it can never collide with a ts-mls built-in or a probing extension.
- */ export const GROUP_ANCHOR_EXTENSION_TYPE = 0xf100;
-const CURRENT_VERSION = 1;
-const encoder = new TextEncoder();
-const decoder = new TextDecoder();
-export function encodeGroupAnchor(anchor) {
-    return encoder.encode(JSON.stringify(anchor));
-}
-/**
- * Tolerant decode: returns null on malformed bytes or wrong shape. The
- * `recoverySecret` is required and must be a non-empty string — an anchor
- * without it cannot seed the recovery rendezvous, so a missing/empty value is a
- * malformed anchor, not a tolerated absence.
- */ export function decodeGroupAnchor(bytes) {
-    let parsed;
-    try {
-        parsed = JSON.parse(decoder.decode(bytes));
-    } catch  {
-        return null;
-    }
-    if (parsed == null || typeof parsed !== 'object') {
-        return null;
-    }
-    const record = parsed;
-    if (typeof record.creatorDID !== 'string' || typeof record.version !== 'number') {
-        return null;
-    }
-    if (typeof record.recoverySecret !== 'string' || record.recoverySecret.length === 0) {
-        return null;
-    }
-    return {
-        creatorDID: record.creatorDID,
-        version: record.version,
-        recoverySecret: record.recoverySecret
-    };
-}
-export function buildGroupAnchorExtension(anchor) {
-    return makeCustomExtension({
-        extensionType: GROUP_ANCHOR_EXTENSION_TYPE,
-        extensionData: encodeGroupAnchor(anchor)
-    });
-}
-export function buildCurrentGroupAnchorExtension(creatorDID, recoverySecret) {
-    return buildGroupAnchorExtension({
-        creatorDID,
-        version: CURRENT_VERSION,
+import { buildCurrentGroupAnchorExtension } from '@kumiai/mls';
+/** Build the genesis-anchor extension for a group kubun is creating. */ export function buildKubunGroupAnchorExtension(creatorDID, recoverySecret) {
+    return buildCurrentGroupAnchorExtension(creatorDID, {
         recoverySecret
     });
 }
 /**
- * Leaf-node capabilities advertising the genesis-anchor extension. RFC 9420
- * requires every member leaf to advertise each custom GroupContext extension
- * type, or `commitInvite` rejects the added leaf. Pass these at both
- * `createGroup` (creator leaf) and `createKeyPackageBundle` (invitee leaf) so an
- * anchored group can be joined.
- */ export function groupAnchorCapabilities() {
-    const base = defaultCapabilities();
-    return base.extensions.includes(GROUP_ANCHOR_EXTENSION_TYPE) ? base : {
-        ...base,
-        extensions: [
-            ...base.extensions,
-            GROUP_ANCHOR_EXTENSION_TYPE
-        ]
-    };
-}
-/**
- * Commit policy enforcing genesis-anchor immutability. The anchor lives in the
- * GroupContext extensions and is written once at group creation; kubun issues no
- * group-context-extensions proposal through any normal path, so any incoming
- * commit or proposal carrying one is anomalous and is refused before it can
- * alter the anchor. Refine to inspect the specific extension type if a future
- * feature legitimately mutates non-anchor group-context extensions.
- */ export const anchorImmutabilityPolicy = (incoming)=>{
-    const proposals = incoming.kind === 'commit' ? incoming.proposals : [
-        incoming.proposal
-    ];
-    for (const { proposal } of proposals){
-        if (proposal.proposalType === defaultProposalTypes.group_context_extensions) {
-            return 'reject';
-        }
-    }
-    return 'accept';
-};
-/**
- * Read the genesis anchor from a group handle. Returns null only when the anchor
- * extension is genuinely absent (a group created before the anchor, or
- * external). A present-but-undecodable extension is corruption, not absence, and
- * throws — so the control gate treats it as "anchor unreadable" and fails closed
- * rather than silently downgrading to the forgeable role-column gate. (The anchor
- * is kubun-written, frozen by the immutability commit policy, and authenticated
- * by the GroupInfo signature, so this is a corruption guard, not a forgery path.)
- */ export function readGroupAnchor(handle) {
-    const extension = handle.state.groupContext.extensions.find((ext)=>ext.extensionType === GROUP_ANCHOR_EXTENSION_TYPE);
-    if (extension == null) {
-        return null;
+ * Read the recovery seed out of an anchor's `app` slot. Throws when the payload
+ * is missing or malformed: the anchor is written once by kubun and authenticated
+ * by the GroupInfo signature, so an unreadable seed is corruption, not absence,
+ * and a group whose seed cannot be read cannot participate in recovery.
+ */ export function readRecoverySecret(anchor) {
+    const app = anchor.app;
+    if (app == null || typeof app !== 'object') {
+        throw new Error('group anchor carries no application payload; cannot derive recovery secret');
     }
-    const data = extension.extensionData;
-    const anchor = data instanceof Uint8Array ? decodeGroupAnchor(data) : null;
-    if (anchor == null) {
-        throw new Error('group anchor extension present but could not be decoded');
+    const { recoverySecret } = app;
+    if (typeof recoverySecret !== 'string' || recoverySecret.length === 0) {
+        throw new Error('group anchor carries no recovery secret');
     }
-    return anchor;
+    return recoverySecret;
 }

package/lib/groups/group-crypto.d.ts

@@ -1,19 +1,42 @@
 import type { GroupCrypto } from '@kumiai/rpc';
+import { type Runtime } from '@sozai/runtime';
 import type { GroupHandleRegistry } from './group-handle-registry.js';
 /**
- * Adapts a `GroupHandleRegistry` group into the `@kumiai/rpc`
- * {@link GroupCrypto} port: epoch number, an epoch-bound topic-derivation
- * secret, and byte-level encrypt/decrypt over the live MLS handle.
+ * Adapts a `GroupHandleRegistry` group into `@kumiai/rpc`'s {@link GroupCrypto}
+ * port: epoch, an epoch-bound topic-derivation secret, and byte-level
+ * encrypt/decrypt over the live MLS handle.
  *
- * `wrap`/`unwrap`/`exportSecret` route through `registry.readHandle` so they take
- * the per-group mutex and observe the canonical handle, using the same framing as
- * `MLSEncryptor` (see `mls-codec.ts`).
+ * `wrap`/`unwrap`/`exportSecret` route through `registry.readHandle`, taking the
+ * per-group mutex and observing the canonical handle, framed as in
+ * `mls-codec.ts`. `exportSecret` passes the caller's label through untouched:
+ * the labels belong to the package deriving topics from the result, so
+ * substituting one moves every topic ID away from what the caller addressed.
  *
- * `GroupCrypto.epoch()` is synchronous by contract, but the registry only
- * exposes the handle behind an async, mutex-guarded `readHandle`. group-rpc
- * always calls `epoch()` immediately after awaiting `exportSecret()` (see
- * GroupPeer's epoch rebuild), so `exportSecret` records the epoch it read under
- * the same lock and `epoch()` returns that cached value — no second, racy lock
- * acquisition.
+ * `sealEntries`/`openEntries` are a SECOND seal, NOT interchangeable with
+ * `wrap`/`unwrap`: those consume a ratchet generation and mutate the handle, so
+ * they cannot serve an open running inside the apply of the commit carrying the
+ * blob. The bytes must match `@kumiai/mls-rpc` exactly — the seal is agreed
+ * without exchange, so a divergence is not a decode error but a group whose
+ * members silently stop reading each other's commits.
+ *
+ * The epoch is READ FROM THE REGISTRY, never cached: applying someone else's
+ * commit advances the handle without touching this file, and a stale number
+ * classifies every later frame as `ahead`, so the cursor skips it forever.
+ * `initialEpoch` covers only construction before the registry has observed a
+ * handle — the caller MUST read the handle's epoch first, or a returning peer
+ * answering `0` steps over every commit it missed. Construction is synchronous
+ * and eager, leaving no window to prime it afterwards.
  */
-export declare function createGroupCrypto(registry: GroupHandleRegistry, groupID: string): GroupCrypto;
+export type GroupCryptoParams = {
+    registry: GroupHandleRegistry;
+    groupID: string;
+    /** The handle's CURRENT epoch — see the note above on why `0` is not a safe placeholder. */
+    initialEpoch: number;
+    /**
+     * Host runtime supplying the seal's randomness, so the source follows the
+     * platform the host is on. Pass the host's — the default constructs a SECOND
+     * runtime rather than propagating one.
+     */
+    runtime?: Runtime;
+};
+export declare function createGroupCrypto(params: GroupCryptoParams): GroupCrypto;