@kubun/plugin-p2p 0.11.0 → 0.12.1

package/lib/groups/group-crypto.js

@@ -1,58 +1,75 @@
+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';
-// Domain-separation label for the epoch-bound topic-derivation secret. Stable so
-// the exported secret is constant within an epoch and rotates when a commit
-// advances the epoch (MLS re-derives exporterSecret per epoch).
-const TOPIC_SECRET_LABEL = 'kubun/group-rpc/topic';
 // Empty context: the epoch already varies the secret; topic derivation mixes in
-// its own epoch/protocol/scope on top.
+// 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);
-// 32-byte secret feeds an HKDF-based topic derivation; the length is otherwise
-// unconstrained.
-const TOPIC_SECRET_LENGTH = 32;
-/**
- * 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.
- *
- * `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`).
- *
- * `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.
- */ export function createGroupCrypto(registry, groupID) {
-    let lastEpoch = 0;
-    const exportSecret = ()=>registry.readHandle(groupID, async (handle)=>{
-            lastEpoch = Number(handle.epoch);
-            return await mlsExporter(handle.state.keySchedule.exporterSecret, TOPIC_SECRET_LABEL, TOPIC_SECRET_CONTEXT, TOPIC_SECRET_LENGTH, handle.context.cipherSuite);
+// 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 epoch = ()=>lastEpoch;
-    const wrap = (bytes)=>registry.readHandle(groupID, async (handle)=>{
-            const { framed } = await mlsEncryptFramed(handle, bytes);
-            return framed;
+    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 to each app-protocol topic —
-    // the anycast `BroadcastClient` and the `busServer` — and the hub mux fans
-    // every inbound frame to BOTH, so each frame's `unwrap` is invoked twice in the
-    // same synchronous burst. MLS application-message decryption is single-use:
-    // `handle.decrypt` consumes a forward-secret ratchet generation, so a second
-    // decrypt of the same ciphertext fails with "Desired gen in the past" and the
-    // frame never reaches the event handler. Caching the in-flight decrypt promise
-    // per ciphertext makes `unwrap` idempotent: the first call advances the ratchet
-    // once and the sibling transport (which calls before the decrypt resolves)
-    // replays the same plaintext without touching the ratchet. The entry is removed
-    // once it settles, so the cache only ever holds the handful of concurrently
-    // in-flight decrypts — no unbounded growth and never an evicted pending entry.
-    // Distinct ciphertexts always miss and decrypt normally, so forward secrecy
-    // across messages is preserved.
+    // 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);
@@ -61,25 +78,82 @@ const TOPIC_SECRET_LENGTH = 32;
             return cached;
         }
         const promise = registry.readHandle(groupID, async (handle)=>{
-            const payload = await mlsDecryptFramed(handle, bytes);
+            const { payload, senderDID } = await mlsDecryptFramed(handle, bytes);
             return {
-                payload
+                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
+        unwrap,
+        frameEpoch,
+        sealEntries,
+        openEntries
     };
 }

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

@@ -1,10 +1,29 @@
 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,22 +77,15 @@ export declare class GroupHandleRegistry {
      * epoch-bumping ops that produce a fresh `GroupHandle` (commitInvite,
      * removeMember, processCommit), use `withHandleReplacing` instead.
      *
-     * Bound: when called under a caller transaction that commits later, this
-     * mutates/eager-uses the shared cached handle and releases the mutex before
-     * that commit, so a concurrent same-group op can observe the uncommitted
-     * handle during the window. `onRollback` repairs the cache after a rollback;
-     * the live exposure is a concurrent cross-epoch decrypt during a rolling-back
-     * membership mutation, which fails the MLS check and skips its persist (a
-     * dropped message, never a durable divergence), and only on a multi-connection
-     * adapter. The transactional epoch-bumping path uses
-     * `withHandleReplacingInTransaction` (fresh handle + mutex held across commit)
-     * to avoid the window entirely.
-     *
-     * `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;
@@ -104,37 +131,80 @@ export declare class GroupHandleRegistry {
      * the working handle and the transactional `StoreProvider` so it can write
      * those other rows on the same connection.
      *
-     * WHY the lock spans commit: holding the mutex until after commit means the
-     * `onCommit` invalidation fires while the lock is still held. By the time a
-     * concurrent same-group op acquires the lock, the cache is already invalidated
-     * and the committed advanced row is durable, so the concurrent op re-restores
-     * the advanced handle. There is no post-mutex / pre-commit window for a
-     * concurrent op to interleave and clobber the advance.
-     *
-     * WHY a fresh working handle rather than the cached one: epoch ops here
-     * advance the MLS ratchet IN PLACE (`handle.processMessage` mutates the handle
-     * object and returns bytes, not a fresh handle). If the callback ran against
-     * the cached `entry.handle`, that in-place mutation would advance the cache
-     * immediately — but the transaction is still uncommitted. On ROLLBACK the DB
-     * ratchet row reverts while the cached handle stays advanced, so cache and DB
-     * diverge. Restoring a throwaway working handle keeps the cache untouched: on
-     * rollback the cache still matches the reverted DB; on commit the cache is
-     * invalidated and the next access lazily re-restores the committed advanced
-     * state. This costs one extra MLS-state restore per call.
+     * 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;
-    }>): Promise<T>;
+    }>, 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;