@kubun/plugin-p2p 0.10.1 → 0.12.0

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

@@ -0,0 +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 `@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`, 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.
+ *
+ * `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 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;

package/lib/groups/group-crypto.js

@@ -0,0 +1,159 @@
+import { readMessageEpoch } from '@kumiai/mls';
+import { ENTRY_SEAL_LABEL } from '@kumiai/mls-rpc';
+import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
+import { toB64 } from '@sozai/codec';
+import { createRuntime } from '@sozai/runtime';
+import { mlsExporter } from 'ts-mls';
+import { mlsDecryptFramed, mlsEncryptFramed } from './mls-codec.js';
+// Empty context: the epoch already varies the secret; topic derivation mixes in
+// its own epoch/protocol/scope on top. Byte-identical to the exporter context
+// `@kumiai/mls-rpc` uses for the ledger-entry seal (`new Uint8Array()`), which is
+// what lets a blob sealed here open there.
+const TOPIC_SECRET_CONTEXT = new Uint8Array(0);
+// Default when a caller names no length. 32 bytes feeds an HKDF-based topic
+// derivation; the length is otherwise unconstrained. It is also XChaCha20-
+// Poly1305's key size, and the same 32 the ledger-entry seal exports at — RFC
+// 9420 §8.5 binds the length into the exporter's KDFLabel, so deriving this from
+// the ciphersuite instead would return 48 on SHA-384 and break every seal.
+const DEFAULT_SECRET_LENGTH = 32;
+// XChaCha20-Poly1305's nonce, carried in the clear ahead of the ciphertext.
+const ENTRY_NONCE_BYTES = 24;
+// Sealed blob format version, first byte, in the clear:
+//   [ VERSION(1) | NONCE(24) | CIPHERTEXT ]
+// Unauthenticated by necessity — it is read to decide how to open, so it cannot
+// sit under the seal. It buys diagnosis, not compatibility: no v1 reader can open
+// a v2 blob either way, but the failure reads as "unsupported version" rather
+// than an AEAD refusal indistinguishable from a wrong epoch or a tampered frame.
+const ENTRY_VERSION = 1;
+export function createGroupCrypto(params) {
+    const { registry, groupID, initialEpoch, runtime = createRuntime() } = params;
+    // Exports the ledger-entry seal key for this epoch. Not routed through
+    // `exportSecret`, which refuses this label: the two are the same exporter call,
+    // and the point of the refusal is that only the seal reaches it.
+    const exportEntryKey = ()=>registry.readHandle(groupID, async (handle)=>{
+            return await mlsExporter(handle.state.keySchedule.exporterSecret, ENTRY_SEAL_LABEL, TOPIC_SECRET_CONTEXT, DEFAULT_SECRET_LENGTH, handle.context.cipherSuite);
+        });
+    const exportSecret = (label, length)=>{
+        // Reusing the ledger-entry label would not be an independent export: it is
+        // the exact exporter call `sealEntries`/`openEntries` make (same context,
+        // same length), so it would hand back the ledger-entry seal key under
+        // another name and make every holder of a topic secret a reader of the
+        // group's control ledger. Refused here rather than left to the doc.
+        if (label === ENTRY_SEAL_LABEL) {
+            throw new Error(`exportSecret: label '${label}' is reserved for the ledger-entry seal`);
+        }
+        return registry.readHandle(groupID, async (handle)=>{
+            return await mlsExporter(handle.state.keySchedule.exporterSecret, label, TOPIC_SECRET_CONTEXT, length ?? DEFAULT_SECRET_LENGTH, handle.context.cipherSuite);
+        });
+    };
+    // A NUMBER off the registry, never a handle: the registry publishes a scalar
+    // precisely so this synchronous contract can be met without anyone reaching
+    // MLS state outside the per-group mutex. `initialEpoch` only covers the window
+    // before the registry has observed a handle for this group.
+    const epoch = ()=>registry.groupEpoch(groupID) ?? initialEpoch;
+    const wrap = (bytes)=>registry.readHandle(groupID, (handle)=>mlsEncryptFramed(handle, bytes));
+    // In-flight decrypt cache, keyed by the ciphertext bytes.
+    //
+    // group-rpc subscribes TWO broadcast transports per app-protocol topic (the
+    // anycast `BroadcastClient` and the `busServer`) and the hub mux fans every
+    // frame to both, so `unwrap` runs twice in one synchronous burst. MLS
+    // decryption is single-use: `handle.decrypt` consumes a forward-secret ratchet
+    // generation, so the second call fails with "Desired gen in the past" and the
+    // frame never reaches its handler. Caching the in-flight promise per ciphertext
+    // makes `unwrap` idempotent — the first call advances the ratchet, the sibling
+    // (calling before it resolves) replays the plaintext. Entries drop once
+    // settled, so the map holds only concurrent in-flight decrypts and never an
+    // evicted pending one; distinct ciphertexts miss and decrypt normally, so
+    // forward secrecy across messages is preserved.
+    //
+    // The replayed value carries an IDENTITY, not just bytes. That is sound only
+    // because the key is the ciphertext: one ciphertext at one epoch has exactly
+    // one MLS-authenticated sender, so a replay cannot attribute a frame to
+    // anyone but the leaf that sealed it.
+    const unwrapCache = new Map();
+    const unwrap = (bytes)=>{
+        const key = toB64(bytes);
+        const cached = unwrapCache.get(key);
+        if (cached != null) {
+            return cached;
+        }
+        const promise = registry.readHandle(groupID, async (handle)=>{
+            const { payload, senderDID } = await mlsDecryptFramed(handle, bytes);
+            return {
+                payload,
+                senderDID
+            };
+        });
+        // Drop the entry once it settles (success or failure): the sibling transport
+        // has already taken the in-flight promise, and a genuine failure must not be
+        // cached so a later valid frame with the same bytes (e.g. after a resync) can
+        // decrypt afresh.
+        //
+        // `.finally()` returns a NEW promise that rejects with the same reason, so
+        // this cleanup branch needs a handler of its own. The caller handles the
+        // promise it was handed; without the catch here the derived one escapes as an
+        // unhandled rejection. Not an edge case: a frame this handle cannot open —
+        // another epoch's, another group's — is ordinary on a shared log, so the
+        // rejecting path is the common one. Only this branch is absorbed; the promise
+        // returned below still rejects to the caller, which is what decides the frame
+        // is dead.
+        unwrapCache.set(key, promise);
+        void promise.finally(()=>{
+            unwrapCache.delete(key);
+        }).catch(()=>{});
+        return promise;
+    };
+    // Reads the epoch every MLSMessage carries in its own cleartext. Needs no
+    // handle and no key, and must never throw: it is asked about every frame a log
+    // holds, most of which are not this member's to open. `null` for anything
+    // ts-mls will not decode, which is how a caller tells a frame sealed AHEAD
+    // (openable once it catches up) from one sealed BELOW (gone forever, since MLS
+    // ratchets forward) — the distinction the app lane's durable cursor rests on.
+    // Untrusted: it is the publisher's word relayed by an untrusted hub, so it may
+    // only decide what to TRY, never that bytes are authentic.
+    const frameEpoch = (bytes)=>{
+        const epochValue = readMessageEpoch(bytes);
+        return epochValue == null ? null : Number(epochValue);
+    };
+    // Seals the ledger-entry blob a Commit carries, under a key derived from this
+    // epoch's exporter secret rather than the message ratchet `wrap` consumes.
+    // Derived-key sealing is what makes the open PURE, so it can run from inside
+    // the apply of the very commit whose blob it opens — the only place it runs,
+    // and one the ratchet-backed pair cannot serve. Byte format is fixed by
+    // `@kumiai/mls-rpc`; a one-byte drift is a group that silently partitions.
+    const sealEntries = async (bytes)=>{
+        const key = await exportEntryKey();
+        // Random per seal: two members can frame a commit at the same epoch, and a
+        // repeated nonce under one key is a break. 24 bytes puts a collision out of
+        // reach without needing a counter.
+        const nonce = runtime.getRandomValues(new Uint8Array(ENTRY_NONCE_BYTES));
+        const ciphertext = xchacha20poly1305(key, nonce).encrypt(bytes);
+        const sealed = new Uint8Array(1 + nonce.length + ciphertext.length);
+        sealed[0] = ENTRY_VERSION;
+        sealed.set(nonce, 1);
+        sealed.set(ciphertext, 1 + nonce.length);
+        return sealed;
+    };
+    const openEntries = async (sealed)=>{
+        if (sealed.length <= 1 + ENTRY_NONCE_BYTES) {
+            throw new Error('openEntries: not a sealed blob');
+        }
+        if (sealed[0] !== ENTRY_VERSION) {
+            // Distinguishable on purpose: every other failure here is an opaque AEAD
+            // refusal, and this lets an operator tell "unsupported version" apart from
+            // a wrong epoch or a tampered frame. The lane handles all three the same.
+            throw new Error(`openEntries: unsupported blob version ${sealed[0]}`);
+        }
+        const key = await exportEntryKey();
+        return xchacha20poly1305(key, sealed.subarray(1, 1 + ENTRY_NONCE_BYTES)).decrypt(sealed.subarray(1 + ENTRY_NONCE_BYTES));
+    };
+    return {
+        epoch,
+        exportSecret,
+        wrap,
+        unwrap,
+        frameEpoch,
+        sealEntries,
+        openEntries
+    };
+}

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

@@ -1,10 +1,29 @@
-import type { GroupHandle } from '@enkaku/group';
 import type { StoreProvider } from '@kubun/db';
 import { type Logger } from '@kubun/logger';
+import type { GroupHandle } from '@kumiai/mls';
+import { type LedgerEntryResolver, type LedgerEntrySink } from './mls-group-handle.js';
+/**
+ * Per-call handle wiring: the two hooks a caller may bind for the duration of
+ * ONE operation rather than for the lifetime of the cached handle. Both are
+ * scoped to the working handle a call restores, so nothing a caller binds here
+ * leaks into another caller's handle.
+ */
+export type HandleCallOptions = {
+    /** Replaces the store-based resolver — a received commit's bodies ride its own frame. */
+    resolveLedgerEntries?: LedgerEntryResolver;
+    /** Collects the entries an accepted commit surfaces, for the caller to fold. */
+    onLedgerEntries?: LedgerEntrySink;
+};
 export type GroupHandleRegistryParams = {
     stores: StoreProvider;
     deviceID: string;
     logger?: Logger;
+    /**
+     * How long an operation waits for a group's handle before failing. Test-only
+     * knob — production runs on {@link MUTEX_ACQUIRE_TIMEOUT_MS}, which is orders
+     * of magnitude above any legitimate hold.
+     */
+    mutexTimeoutMs?: number;
 };
 export type SeedParams = {
     groupID: string;
@@ -17,6 +36,22 @@ export type SeedParams = {
      * leaves the cache empty.
      */
     stores: StoreProvider;
+    /**
+     * Replace a handle this device already holds for the group, rather than
+     * refusing.
+     *
+     * Only for a REJOIN: a device that left, or that someone else removed, keeps
+     * its MLS state and therefore its cached handle, and that handle can decrypt
+     * nothing at the group's current epoch. Being admitted back hands it a live
+     * one, and the guard below — which exists to stop a live member being rolled
+     * back to a handle frozen at its joining epoch — would otherwise refuse the
+     * only handle that works.
+     *
+     * The caller establishes the rejoin from the group row's own `status`, never
+     * from the invite: an unauthenticated payload must not be able to displace a
+     * live member's handle.
+     */
+    replace?: boolean;
 };
 /**
  * Single canonical access point for a device's MLS `GroupHandle` instances.
@@ -28,8 +63,7 @@ export type SeedParams = {
  *
  * All five mutation paths (manager member ops, context handlers, broadcast
  * service encrypt/decrypt, hub-tunnel sync listener, hub-tunnel sync provider)
- * route MLS state through this registry. Spec:
- * `docs/superpowers/specs/2026-05-09-group-handle-registry-design.md`.
+ * route MLS state through this registry.
  */
 export declare class GroupHandleRegistry {
     #private;
@@ -43,19 +77,36 @@ export declare class GroupHandleRegistry {
      * epoch-bumping ops that produce a fresh `GroupHandle` (commitInvite,
      * removeMember, processCommit), use `withHandleReplacing` instead.
      *
-     * `options.stores` overrides the constructor-stored `StoreProvider` for the
-     * restore + persist DB calls. Callers running inside an engine transaction
-     * (e.g. context handlers under `mutateGraph`) MUST pass the transactional
-     * `tx` so reads + writes share the tx's connection. Without this, SQLite's
-     * write lock held by the outer tx blocks the registry's persist forever.
+     * BOUND: under a caller transaction that commits later, the mutex releases
+     * before that commit, so a concurrent same-group op can observe the uncommitted
+     * handle. `onRollback` repairs the cache; the live exposure is a cross-epoch
+     * decrypt that fails the MLS check and skips its persist — a dropped message,
+     * never a durable divergence, and only on a multi-connection adapter. Use
+     * `withHandleReplacingInTransaction` to avoid the window entirely.
+     *
+     * The persist runs AFTER the mutex is released — see {@link #withLockedHandle}
+     * — but is still awaited here, so a caller that returns has its state durable.
      */
     withHandle<T>(groupID: string, fn: (handle: GroupHandle) => Promise<T>, options?: {
         stores?: StoreProvider;
     }): Promise<T>;
+    /**
+     * Acquire the canonical handle for `groupID`, run `fn` under the per-group
+     * mutex, return the result, release — WITHOUT persisting MLS state.
+     *
+     * Read-only access: takes the lock and lazy-restores the cached handle if
+     * absent, but never writes MLS state. Use this for pure reads that do not
+     * mutate the handle (anchor reads, `GroupInfo` export, credential reads). For
+     * in-place-mutating ops that advance the MLS secret tree (encrypt/decrypt),
+     * use `withHandle`, which persists the advanced state.
+     */
+    readHandle<T>(groupID: string, fn: (handle: GroupHandle) => Promise<T> | T, options?: {
+        stores?: StoreProvider;
+    }): Promise<T>;
     /**
      * Like `withHandle`, but the callback returns `{ result, updated }`.
      * Registry replaces its cached handle with `updated` before persisting on
-     * success. Required for `@enkaku/group` epoch ops (`commitInvite`,
+     * success. Required for `@kumiai/mls` epoch ops (`commitInvite`,
      * `removeMember`, `processCommit`) which construct a fresh `GroupHandle`
      * rather than mutating the input.
      *
@@ -67,15 +118,93 @@ export declare class GroupHandleRegistry {
     }>, options?: {
         stores?: StoreProvider;
     }): Promise<T>;
+    /**
+     * Like `withHandleReplacing`, but the per-group mutex is held across the
+     * ENTIRE transaction — it is acquired once, then a transaction is opened, run,
+     * and committed under that single lock, which releases only AFTER commit (or
+     * rollback). The cached `entry.handle` is NEVER touched by this method; the
+     * cache swap is the `onCommit` invalidation.
+     *
+     * Use this when the MLS advance must commit or roll back together with other
+     * rows written in the same transaction (e.g. receive-side commit processing
+     * that advances the ratchet AND writes the roster delta). `fn` receives both
+     * the working handle and the transactional `StoreProvider` so it can write
+     * those other rows on the same connection.
+     *
+     * The lock MUST span the commit: the `onCommit` invalidation then fires while it
+     * is still held, so there is no post-mutex / pre-commit window for a concurrent
+     * op to clobber the advance.
+     *
+     * The working handle MUST be fresh, not the cached one: `processMessage` advances
+     * the ratchet IN PLACE, so running against the cache would advance it while the
+     * transaction is still uncommitted, and a rollback would leave the cache ahead of
+     * the reverted DB row. Costs one extra MLS-state restore per call.
+     *
+     * THE ONE PATH that still touches the database under the mutex, because its
+     * whole contract is that the lock spans the commit. It is therefore the only
+     * remaining candidate to be the holder in a lock-order cycle — see
+     * {@link #withLockedHandle} for why that matters — and the acquisition
+     * deadline on every other caller is what stops such a cycle being permanent.
+     */
+    withHandleReplacingInTransaction<T>(groupID: string, stores: StoreProvider, fn: (handle: GroupHandle, tx: StoreProvider) => Promise<{
+        result: T;
+        updated: GroupHandle;
+    }>, options?: HandleCallOptions): Promise<T>;
+    /**
+     * The last epoch this registry observed for `groupID`, or `null` if it has
+     * never held a handle for it. Synchronous, because the one port that needs it
+     * — `GroupCrypto.epoch()` — is synchronous by contract while every handle
+     * access here is async and mutex-guarded.
+     *
+     * Publishes a NUMBER, never the handle: a scalar cannot advance a ratchet, skip
+     * the per-group mutex, or mutate MLS state. DO NOT widen this to return the
+     * handle — the mutex is what makes the ratchet advance and its row write one
+     * atomic step.
+     *
+     * Deliberately NOT monotonic: a rolled-back advance must republish the LOWER
+     * epoch, or the reader is pinned above the state the device holds. Genuine
+     * backwards installs are refused upstream, by `replaceHandle`'s epoch guard and
+     * `saveMLSState`'s no-op on a lower row.
+     */
+    groupEpoch(groupID: string): number | null;
+    /**
+     * Called when the epoch published for a group CHANGES — an advance, or the
+     * lower republish a rolled-back one produces. Returns the unsubscribe.
+     *
+     * The first observation of a group is deliberately NOT a change: restoring a
+     * handle at boot publishes an epoch where there was none, and treating that as
+     * a rotation would have every group fire its epoch-change consumers once per
+     * process start.
+     *
+     * Listeners run INSIDE the per-group mutex and inside whatever transaction the
+     * advancing operation holds, so one must never await the registry or the store
+     * from here. Defer the work.
+     */
+    onEpochChanged(listener: (groupID: string, epoch: number) => void): () => void;
     /**
      * Drop the cached handle for `groupID`. Next `withHandle` re-restores from DB.
      * Called by `leaveGroup` after the MLS state row is deleted, and by tests.
+     *
+     * The published epoch is deliberately LEFT in place. Invalidation is how this
+     * registry says "re-read the durable row", not "this device no longer has an
+     * epoch" — and the transactional advance path invalidates immediately after
+     * committing an advance, so clearing here would discard the newest epoch the
+     * device has. The next restore republishes whatever the row actually holds.
      */
     invalidate(groupID: string): void;
     /**
      * Atomically swap+persist the cached handle under the per-group mutex, so a
      * concurrent decrypt runs strictly before (stale handle, fails harmlessly) or
      * after (new handle), never interleaved.
+     *
+     * MONOTONIC in the epoch: a handle strictly BEHIND the one held is refused, no
+     * cache swap and no persist. Installing one would roll this device's key schedule
+     * back and have it encrypt at an epoch its co-members have left, producing traffic
+     * nobody can open with nothing raised. Reachable because a journalled commit is
+     * adopted at-least-once, carrying a handle frozen at the epoch it was built.
+     *
+     * The bound is STRICT — a same-epoch re-install must still win, because decrypting
+     * an application message advances the secret-tree generation within one epoch.
      */
     replaceHandle(groupID: string, handle: GroupHandle, options?: {
         stores?: StoreProvider;