@kubun/plugin-p2p 0.8.3 → 0.9.0

package/lib/hub/manager.d.ts

@@ -0,0 +1,117 @@
+import type { StoreProvider } from '@kubun/db';
+export type Hub = {
+    id: string;
+    label: string | null;
+    url: string;
+    serverDID: string | null;
+    createdAt: Date;
+    updatedAt: Date | null;
+};
+export type CreateHubParams = {
+    stores: StoreProvider;
+    url: string;
+    label?: string | null;
+    serverDID?: string | null;
+};
+export type UpdateHubParams = {
+    stores: StoreProvider;
+    id: string;
+    label?: string | null;
+    url?: string;
+    serverDID?: string | null;
+};
+export type DeleteHubParams = {
+    stores: StoreProvider;
+    id: string;
+    force?: boolean;
+};
+export type DeleteHubResult = {
+    success: boolean;
+    boundGroupIDs: Array<string>;
+};
+export type GetHubParams = {
+    stores: StoreProvider;
+    id: string;
+};
+export type ListHubsParams = {
+    stores: StoreProvider;
+};
+export type BindHubToGroupParams = {
+    stores: StoreProvider;
+    hubID: string;
+    groupID: string;
+};
+export type UnbindHubFromGroupParams = {
+    stores: StoreProvider;
+    hubID: string;
+    groupID: string;
+};
+export type ListHubsByGroupParams = {
+    stores: StoreProvider;
+    groupID: string;
+};
+export type ListGroupsByHubParams = {
+    stores: StoreProvider;
+    hubID: string;
+};
+export type CaptureServerDIDParams = {
+    stores: StoreProvider;
+    hubURL: string;
+    serverDID: string;
+};
+export type UpsertHubParams = {
+    stores: StoreProvider;
+    url: string;
+    serverDID?: string | null;
+};
+export declare class HubServerDIDConflictError extends Error {
+    readonly hubID: string;
+    readonly url: string;
+    readonly existingServerDID: string;
+    readonly providedServerDID: string;
+    constructor(params: {
+        hubID: string;
+        url: string;
+        existingServerDID: string;
+        providedServerDID: string;
+    });
+}
+export declare function createHub(params: CreateHubParams): Promise<Hub>;
+/**
+ * Idempotent register-or-pin entry-point. Applies the conflict matrix:
+ *
+ * - URL not registered → insert a fresh row with `serverDID` (or null) and
+ *   return it.
+ * - existing row, `server_did === null`, provided null → no-op.
+ * - existing row, `server_did === null`, provided DID-A → upgrade pin to
+ *   DID-A.
+ * - existing row, `server_did === DID-A`, provided null or matching DID-A →
+ *   no-op (no silent downgrade).
+ * - existing row, `server_did === DID-A`, provided DID-B → throws
+ *   `HubServerDIDConflictError`. Caller must explicit `updateHub` to change
+ *   a pinned DID.
+ *
+ * Unlike `createHub`, `upsertHub` takes no `label` — it is for atomic
+ * register+bind paths where the inviter only ships connectivity + pin.
+ */
+export declare function upsertHub(params: UpsertHubParams): Promise<Hub>;
+export declare function updateHub(params: UpdateHubParams): Promise<Hub>;
+export declare function deleteHub(params: DeleteHubParams): Promise<DeleteHubResult>;
+export declare function getHub(params: GetHubParams): Promise<Hub | null>;
+export declare function listHubs(params: ListHubsParams): Promise<Array<Hub>>;
+export declare function bindHubToGroup(params: BindHubToGroupParams): Promise<boolean>;
+export declare function unbindHubFromGroup(params: UnbindHubFromGroupParams): Promise<boolean>;
+export declare function listHubsByGroup(params: ListHubsByGroupParams): Promise<Array<Hub>>;
+export declare function listGroupsByHub(params: ListGroupsByHubParams): Promise<Array<string>>;
+/**
+ * TOFU capture path. Looks up the local hub row by URL and applies the
+ * conflict matrix:
+ * - URL not registered → no-op, returns `false`.
+ * - existing `server_did` is null → upgrade to `serverDID`, returns `true`.
+ * - existing `server_did` matches `serverDID` → no-op, returns `false`.
+ * - existing `server_did` differs from `serverDID` → throws
+ *   `HubServerDIDConflictError`. Pinned-mismatch enforcement (hard-fail
+ *   before any message is delivered) lives in the transport wrapper and
+ *   surfaces `HubServerDIDMismatchError` to callers.
+ */
+export declare function captureServerDID(params: CaptureServerDIDParams): Promise<boolean>;

package/lib/hub/manager.js

@@ -0,0 +1 @@
+import{getP2PStore as r}from"@kubun/store-p2p";export class HubServerDIDConflictError extends Error{hubID;url;existingServerDID;providedServerDID;constructor(r){super(`hub at ${r.url} is pinned to ${r.existingServerDID}; refusing to overwrite with ${r.providedServerDID}`),this.name="HubServerDIDConflictError",this.hubID=r.hubID,this.url=r.url,this.existingServerDID=r.existingServerDID,this.providedServerDID=r.providedServerDID}}function e(r){return{id:r.id,label:r.label,url:r.url,serverDID:r.server_did,createdAt:new Date(r.created_at),updatedAt:null==r.updated_at?null:new Date(r.updated_at)}}export async function createHub(t){let u=await r(t.stores),i=t.serverDID??null,a=await u.getHubByURL(t.url);if(null!=a){if(null!=a.server_did&&null!=i&&a.server_did!==i)throw new HubServerDIDConflictError({hubID:a.id,url:t.url,existingServerDID:a.server_did,providedServerDID:i});if(null==a.server_did&&null!=i){await u.updateHub(a.id,{server_did:i});let r=await u.getHub(a.id);if(null==r)throw Error("Failed to read hub after upgrade");return e(r)}return e(a)}let l=crypto.randomUUID();await u.insertHub({id:l,label:t.label??null,url:t.url,server_did:i});let n=await u.getHub(l);if(null==n)throw Error("Failed to read hub after insert");return e(n)}export async function upsertHub(r){return await createHub({stores:r.stores,url:r.url,serverDID:r.serverDID})}export async function updateHub(t){let u=await r(t.stores),i=await u.getHub(t.id);if(null==i)throw Error(`Hub ${t.id} not found`);if(null!=t.url&&t.url!==i.url){let r=await u.getHubByURL(t.url);if(null!=r&&r.id!==t.id)throw Error(`URL ${t.url} already in use by hub ${r.id}`)}let a={};void 0!==t.label&&(a.label=t.label),void 0!==t.url&&(a.url=t.url),void 0!==t.serverDID&&(a.server_did=t.serverDID),await u.updateHub(t.id,a);let l=await u.getHub(t.id);if(null==l)throw Error("Failed to read hub after update");return e(l)}export async function deleteHub(e){let t=await r(e.stores),u=await t.listGroupIDsByHubID(e.id);return u.length>0&&!e.force?{success:!1,boundGroupIDs:u}:(u.length>0&&await t.deleteGroupHubsByHubID(e.id),await t.deleteHub(e.id),{success:!0,boundGroupIDs:u})}export async function getHub(t){let u=await r(t.stores),i=await u.getHub(t.id);return null==i?null:e(i)}export async function listHubs(t){let u=await r(t.stores);return(await u.listHubs()).map(e)}export async function bindHubToGroup(e){let t=await r(e.stores);return await t.insertGroupHub({group_id:e.groupID,hub_id:e.hubID})}export async function unbindHubFromGroup(e){let t=await r(e.stores);return await t.deleteGroupHub({groupID:e.groupID,hubID:e.hubID})}export async function listHubsByGroup(t){let u=await r(t.stores);return(await u.listHubsByGroupID(t.groupID)).map(e)}export async function listGroupsByHub(e){let t=await r(e.stores);return await t.listGroupIDsByHubID(e.hubID)}export async function captureServerDID(e){let t=await r(e.stores),u=await t.getHubByURL(e.hubURL);if(null==u)return!1;if(null==u.server_did)return await t.updateHub(u.id,{server_did:e.serverDID}),!0;if(u.server_did===e.serverDID)return!1;throw new HubServerDIDConflictError({hubID:u.id,url:e.hubURL,existingServerDID:u.server_did,providedServerDID:e.serverDID})}

package/lib/hub/receive-handler.d.ts

@@ -1,5 +1,4 @@
 import type { Logger } from '@kubun/logger';
-import type { P2PStoreAPI } from '@kubun/store-p2p';
 import { type BroadcastService } from '../groups/broadcast-service.js';
 /**
  * Shape of a message pushed by `hub/receive`. Matches `@enkaku/hub-protocol`
@@ -14,9 +13,7 @@ export type ReceivedHubMessage = {
 };
 export type HandleReceivedMessageParams = {
     groupID: string;
-    deviceID: string;
     message: ReceivedHubMessage;
-    p2pStore: P2PStoreAPI;
     broadcastService: BroadcastService;
     logger?: Logger;
 };
@@ -29,8 +26,8 @@ export type HandleReceivedMessageResult = {
  * Returns `{ ack: true }` when the message has been processed to a state where
  * redelivery serves no purpose (applied successfully, or decrypt failed with
  * no recovery path). Returns `{ ack: false }` when the hub should redeliver
- * (transient apply or save failure, MLS state missing, unexpected error).
- * Skips with `{ ack: false }` on groupID mismatch so the message stays queued
- * for whichever recipient it was intended for.
+ * (transient apply failure or unexpected error). Skips with `{ ack: false }`
+ * on groupID mismatch so the message stays queued for whichever recipient it
+ * was intended for.
  */
 export declare function handleReceivedMessage(params: HandleReceivedMessageParams): Promise<HandleReceivedMessageResult>;

package/lib/hub/receive-handler.js

@@ -1 +1 @@
-import{fromB64 as e}from"@enkaku/codec";import{ApplyError as r,DecryptError as a}from"../groups/broadcast-service.js";import{fromMLSStateRow as s,toMLSStateInsert as t}from"../groups/mls-state.js";export async function handleReceivedMessage(c){let n,{groupID:u,deviceID:i,message:o,p2pStore:p,broadcastService:l,logger:g}=c;if(o.groupID!==u)return g?.debug("hub message groupID mismatch, skipping",{groupID:u,messageGroupID:o.groupID,sequenceID:o.sequenceID}),{ack:!1};let d=await p.getMLSState(u,i);if(null==d)return g?.warn("mls state missing for group, skipping message",{groupID:u,sequenceID:o.sequenceID}),{ack:!1};let m=s(d),D=e(o.payload);try{n=await l.processReceived({groupID:u,encrypted:D,groupState:m})}catch(e){if(e instanceof a)return g?.debug("decrypt failed, acking and skipping",{groupID:u,sequenceID:o.sequenceID,error:e}),{ack:!0};if(e instanceof r)return g?.error("broadcast apply failed, will redeliver",{groupID:u,sequenceID:o.sequenceID,error:e}),{ack:!1};return g?.error("unexpected error processing hub message",{groupID:u,sequenceID:o.sequenceID,error:e}),{ack:!1}}try{await p.saveMLSState(t(n.updatedGroupState,u,i))}catch(e){return g?.error("save mls state failed after apply, will redeliver",{groupID:u,sequenceID:o.sequenceID,error:e}),{ack:!1}}return{ack:!0}}
+import{fromB64 as e}from"@enkaku/codec";import{ApplyError as r,DecryptError as c}from"../groups/broadcast-service.js";export async function handleReceivedMessage(s){let{groupID:a,message:n,broadcastService:u,logger:i}=s;if(n.groupID!==a)return i?.debug("hub message groupID mismatch, skipping",{groupID:a,messageGroupID:n.groupID,sequenceID:n.sequenceID}),{ack:!1};let o=e(n.payload);try{await u.processReceived({groupID:a,encrypted:o})}catch(e){if(e instanceof c)return i?.debug("decrypt failed, acking and skipping",{groupID:a,sequenceID:n.sequenceID,error:e}),{ack:!0};if(e instanceof r)return i?.error("broadcast apply failed, will redeliver",{groupID:a,sequenceID:n.sequenceID,error:e}),{ack:!1};return i?.error("unexpected error processing hub message",{groupID:a,sequenceID:n.sequenceID,error:e}),{ack:!1}}return{ack:!0}}

package/lib/hub/relay-manager.d.ts

@@ -1,12 +1,65 @@
 import type { Client } from '@enkaku/client';
+import { EventEmitter } from '@enkaku/event';
 import type { HubProtocol } from '@enkaku/hub-protocol';
 import type { Logger } from '@kubun/logger';
 import type { P2PStoreAPI } from '@kubun/store-p2p';
 import type { GroupBroadcastMessage } from '../groups/broadcast.js';
 import type { BroadcastService } from '../groups/broadcast-service.js';
+import { type OnServerDIDObserved } from './connection-pool.js';
+import type { ServerDIDMismatchObserver, ServerDIDObserver } from './did-observing-transport.js';
 import { GroupChannel, type GroupChannelParams } from './group-channel.js';
-export type CreateHubClient = (hubURL: string) => Promise<Client<HubProtocol>>;
+import { HubConnection, type HubConnectionParams } from './hub-connection.js';
+export type CreateHubClientOptions = {
+    /**
+     * Per-call observer fired once when the first signed response arrives. Set
+     * by `HubConnectionPool` so the pool can route the observed server DID
+     * through its `onServerDIDObserved` handler with the hub URL bound. Factories
+     * that don't honour this opt simply skip TOFU capture for pool-spawned
+     * clients.
+     */
+    onServerDID?: ServerDIDObserver;
+    /**
+     * Pinned `server_did` resolved by the pool from the local hub row at spawn
+     * time. When set, the underlying `DIDObservingTransport` enforces it: a
+     * non-matching first response raises `HubServerDIDMismatchError` and no
+     * message is delivered to the inner Client (hard-fail path). When unset,
+     * the wrapper falls back to TOFU capture via `onServerDID`.
+     */
+    expectedServerDID?: string;
+    /**
+     * Side-channel notifier fired when a pinned-DID mismatch is detected. Lets
+     * the pool log + evict on top of the typed error that propagates through
+     * the read loop.
+     */
+    onMismatch?: ServerDIDMismatchObserver;
+};
+export type CreateHubClient = (hubURL: string, opts?: CreateHubClientOptions) => Promise<Client<HubProtocol>>;
 export type CreateGroupChannel = (params: GroupChannelParams) => GroupChannel;
+export type CreateHubConnection = (params: HubConnectionParams) => HubConnection;
+export type RelayEvent = {
+    type: 'connected';
+    hubURL: string;
+    groupIDs: Array<string>;
+} | {
+    type: 'disconnected';
+    hubURL: string;
+    groupIDs: Array<string>;
+    reason?: string;
+} | {
+    type: 'error';
+    hubURL: string;
+    groupIDs: Array<string>;
+    error: unknown;
+} | {
+    type: 'reconnecting';
+    hubURL: string;
+    groupIDs: Array<string>;
+    attempt: number;
+    delayMs: number;
+};
+type RelayManagerEvents = {
+    relay: RelayEvent;
+};
 export type HubRelayManagerParams = {
     p2pStore: P2PStoreAPI;
     broadcastService: BroadcastService;
@@ -18,10 +71,21 @@ export type HubRelayManagerParams = {
     backoffBaseMs?: number;
     backoffMaxMs?: number;
     backoffJitter?: number;
+    broadcastTimeoutMs?: number;
     createGroupChannel?: CreateGroupChannel;
+    createHubConnection?: CreateHubConnection;
+    /**
+     * Forwarded to the underlying `HubConnectionPool`. Fired with the observed
+     * `serverDID` after the first signed response from a freshly-spawned client.
+     * Used by the hub manager to apply the TOFU capture conflict matrix (the
+     * `null → DID-A` upgrade). Errors are caught and logged by the pool;
+     * pinned-mismatch enforcement is a separate path inside the wrapper.
+     */
+    onServerDIDObserved?: OnServerDIDObserved;
 };
 export declare class HubRelayManager {
     #private;
+    readonly relayEvents: EventEmitter<RelayManagerEvents>;
     constructor(params: HubRelayManagerParams);
     /**
      * Open channels for each group in parallel. Per-group failures are logged
@@ -31,7 +95,26 @@ export declare class HubRelayManager {
      */
     start(groupIDs: Array<string>): Promise<void>;
     addGroup(groupID: string): Promise<void>;
+    /**
+     * Post-join binding-add hook. Single-hub regime — when the group already
+     * has an active channel:
+     *   - same hubURL → debug log, no-op (idempotent re-bind);
+     *   - different hubURL → warn, no-op (extra binding deferred until
+     *     multi-hub support lands).
+     * When the group has no active channel yet (e.g. binding was created
+     * before relay setup ran), open one for the supplied hub.
+     */
+    addBinding(groupID: string, hubURL: string): Promise<void>;
+    /**
+     * Post-join binding-remove hook. No-op when the unbound hub is not the
+     * group's active hub (single-hub regime: unbinding a non-active hub leaves
+     * the channel intact). When it matches, behaves like `removeGroup`.
+     */
+    removeBinding(groupID: string, hubURL: string): Promise<void>;
     removeGroup(groupID: string): Promise<void>;
-    broadcast(groupID: string, message: GroupBroadcastMessage): Promise<void>;
+    broadcast(groupID: string, message: GroupBroadcastMessage, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
     stop(): Promise<void>;
 }
+export {};

package/lib/hub/relay-manager.js

@@ -1 +1 @@
-import{HubConnectionPool as e}from"./connection-pool.js";import{GroupChannel as a}from"./group-channel.js";export class HubRelayManager{#e;#a;#t;#s;#r;#o;#i;#l;#c;#h;#u;#p=new Map;constructor(t){this.#e=t.p2pStore,this.#a=t.broadcastService,this.#t=t.deviceID,this.#r=t.logger,this.#o=t.ackFlushMs??500,this.#i=t.ackFlushMax??10,this.#l=t.backoffBaseMs??1e3,this.#c=t.backoffMaxMs??6e4,this.#h=t.backoffJitter??.25,this.#s=new e({createHubClient:t.createHubClient,logger:t.logger}),this.#u=t.createGroupChannel??(e=>new a(e))}async start(e){(await Promise.allSettled(e.map(e=>this.addGroup(e)))).forEach((a,t)=>{"rejected"===a.status&&this.#r?.error("addGroup failed during start",{groupID:e[t],error:a.reason})})}async addGroup(e){if(this.#p.has(e))return void this.#r?.debug("group already added",{groupID:e});let a=await this.#e.getGroup(e);if(null==a)throw Error(`Group ${e} not found`);let t=a.hub_urls;if(null==t||0===t.length)return void this.#r?.warn("group has no hub URLs, skipping",{groupID:e});t.length>1&&this.#r?.warn("multi-hub not yet supported, using first",{groupID:e,hubURLs:t});let s=this.#u({groupID:e,hubURL:t[0],deviceID:this.#t,pool:this.#s,broadcastService:this.#a,p2pStore:this.#e,logger:this.#r,ackFlushMs:this.#o,ackFlushMax:this.#i,backoffBaseMs:this.#l,backoffMaxMs:this.#c,backoffJitter:this.#h});await s.open(),this.#p.set(e,s)}async removeGroup(e){let a=this.#p.get(e);null!=a&&(this.#p.delete(e),await a.close())}async broadcast(e,a){let t=this.#p.get(e);if(null==t)throw Error(`Group ${e} is not active in HubRelayManager`);await t.broadcast(a)}async stop(){let e=[...this.#p.values()];this.#p.clear(),(await Promise.allSettled(e.map(e=>e.close()))).forEach(e=>{"rejected"===e.status&&this.#r?.warn("GroupChannel close failed",{error:e.reason})}),await this.#s.disposeAll()}}
+import{EventEmitter as e}from"@enkaku/event";import{HubConnectionPool as t}from"./connection-pool.js";import{GroupChannel as s}from"./group-channel.js";import{HubConnection as r}from"./hub-connection.js";export class HubRelayManager{#e;#t;#s;#r;#o;#a;#i;#n;#l;#c;#u;#h;#p;#g=new Map;#d=new Map;#b=new Map;#f=new Map;relayEvents;constructor(o){this.#e=o.p2pStore,this.#t=o.broadcastService,this.#s=o.deviceID,this.#o=o.logger,this.#a=o.ackFlushMs??500,this.#i=o.ackFlushMax??10,this.#n=o.backoffBaseMs??1e3,this.#l=o.backoffMaxMs??6e4,this.#c=o.backoffJitter??.25,this.#u=o.broadcastTimeoutMs;let a=o.p2pStore;this.#r=new t({createHubClient:o.createHubClient,logger:o.logger,onServerDIDObserved:o.onServerDIDObserved,resolvePinnedDID:async e=>{let t=await a.getHubByURL(e);return t?.server_did??null}}),this.#h=o.createGroupChannel??(e=>new s(e)),this.#p=o.createHubConnection??(e=>new r(e)),this.relayEvents=new e}async #M(e){let t=this.#g.get(e);if(null!=t)return t;let s=this.#p({hubURL:e,deviceID:this.#s,pool:this.#r,logger:this.#o,ackFlushMs:this.#a,ackFlushMax:this.#i,backoffBaseMs:this.#n,backoffMaxMs:this.#l,backoffJitter:this.#c});try{await s.open()}catch(e){try{await s.dispose()}catch{}throw e}let r=s.events.on("lifecycle",async t=>{let s=Object.freeze([...this.#b.entries()].filter(([,t])=>t===e).map(([e])=>e));await this.relayEvents.emit("relay",{...t,hubURL:e,groupIDs:s})});return this.#f.set(e,r),this.#g.set(e,s),s}async start(e){(await Promise.allSettled(e.map(e=>this.addGroup(e)))).forEach((t,s)=>{"rejected"===t.status&&this.#o?.error("addGroup failed during start",{groupID:e[s],error:t.reason})})}async addGroup(e){if(this.#d.has(e))return void this.#o?.debug("group already added",{groupID:e});if(null==await this.#e.getGroup(e))throw Error(`Group ${e} not found`);let t=await this.#e.listHubsByGroupID(e);0===t.length?this.#o?.warn("group has no hub bindings, skipping",{groupID:e}):(t.length>1&&this.#o?.warn("multi-hub not yet supported, using first",{groupID:e,hubURLs:t.map(e=>e.url)}),await this.#v(e,t[0].url))}async #v(e,t){let s=await this.#M(t),r=this.#h({groupID:e,deviceID:this.#s,hubConnection:s,broadcastService:this.#t,p2pStore:this.#e,logger:this.#o});await r.open(),this.#d.set(e,r),this.#b.set(e,t)}async addBinding(e,t){let s=this.#b.get(e);null!=s?s===t?this.#o?.debug("binding already active",{groupID:e,hubURL:t}):this.#o?.warn("multi-hub not yet supported, ignoring extra binding",{groupID:e,activeHubURL:s,newHubURL:t}):await this.#v(e,t)}async removeBinding(e,t){this.#b.get(e)!==t?this.#o?.debug("binding not active, ignoring removal",{groupID:e,hubURL:t}):await this.removeGroup(e)}async removeGroup(e){let t=this.#d.get(e);null!=t&&(await t.close(),this.#d.delete(e),this.#b.delete(e))}async broadcast(e,t,s){let r=this.#d.get(e);if(null==r)throw Error(`Group ${e} is not active in HubRelayManager`);let o=s?.timeoutMs??this.#u;await r.broadcast(t,{timeoutMs:o})}async stop(){for(let e of this.#f.values())e();this.#f.clear();let e=[...this.#d.values()];this.#d.clear(),this.#b.clear(),(await Promise.allSettled(e.map(e=>e.close()))).forEach(e=>{"rejected"===e.status&&this.#o?.warn("GroupChannel close failed",{error:e.reason})});let t=[...this.#g.values()];this.#g.clear(),(await Promise.allSettled(t.map(e=>e.close()))).forEach(e=>{"rejected"===e.status&&this.#o?.warn("HubConnection close failed",{error:e.reason})}),await this.#r.disposeAll()}}

package/lib/hub/send-handler.d.ts

@@ -1,28 +1,24 @@
-import type { Client } from '@enkaku/client';
-import type { HubProtocol } from '@enkaku/hub-protocol';
 import type { Logger } from '@kubun/logger';
-import type { P2PStoreAPI } from '@kubun/store-p2p';
 import type { GroupBroadcastMessage } from '../groups/broadcast.js';
 import type { BroadcastService } from '../groups/broadcast-service.js';
 export type HandleSendBroadcastParams = {
     groupID: string;
-    deviceID: string;
     message: GroupBroadcastMessage;
-    p2pStore: P2PStoreAPI;
     broadcastService: BroadcastService;
-    hubClient: Client<HubProtocol>;
+    /**
+     * Wire-send callback. Receives the groupID and the base64-encoded encrypted
+     * MLS application message, and is expected to fan it out via the underlying
+     * hub transport (e.g. `HubConnection.broadcast`). Decoupling from the hub
+     * client lets callers serialize the send through a per-group mutex shared
+     * with the receive path.
+     */
+    send: (groupID: string, payloadB64: string) => Promise<void>;
     logger?: Logger;
 };
 /**
- * Encrypt + send a broadcast for a group, then persist the advanced MLS state.
- *
- * Failure semantics:
- * - Missing MLS state for (group, device) → throw, caller cannot broadcast.
- * - `prepareSend` failure → throw, no save (epoch unchanged on disk).
- * - `hub/group/send` failure → throw, do NOT save advanced MLS state.
- *   Prevents an MLS epoch wedge where local state outpaces recipients.
- * - `saveMLSState` failure → throw. State has advanced in memory; on next call
- *   the load-from-disk path will re-derive a fresh handle from the prior epoch
- *   and re-encrypt. (Wedge protection only applies pre-save by design.)
+ * Encrypt + send a broadcast for a group. MLS state persistence is handled
+ * by the registry inside `BroadcastService.prepareSend`. Wedge protection
+ * (failed send → no advance of persisted state) is preserved because send
+ * runs INSIDE the registry's per-group lock and a throw skips persist.
  */
 export declare function handleSendBroadcast(params: HandleSendBroadcastParams): Promise<void>;

package/lib/hub/send-handler.js

@@ -1 +1 @@
-import{toB64 as a}from"@enkaku/codec";import{fromMLSStateRow as r,toMLSStateInsert as t}from"../groups/mls-state.js";export async function handleSendBroadcast(e){let{groupID:o,deviceID:s,message:n,p2pStore:i,broadcastService:p,hubClient:d,logger:u}=e,c=await i.getMLSState(o,s);if(null==c)throw Error(`MLS state missing for group ${o}; cannot broadcast`);let l=r(c),{encrypted:m,updatedGroupState:S}=await p.prepareSend({groupID:o,message:n,groupState:l});try{await d.request("hub/group/send",{param:{groupID:o,payload:a(m)}})}catch(a){throw u?.error("hub/group/send failed",{groupID:o,error:a}),a}await i.saveMLSState(t(S,o,s))}
+import{toB64 as r}from"@enkaku/codec";export async function handleSendBroadcast(e){let{groupID:a,message:o,broadcastService:n,send:t,logger:d}=e;try{await n.prepareSend({groupID:a,message:o,send:e=>t(a,r(e))})}catch(r){throw d?.error("hub/group/send failed",{groupID:a,error:r}),r}}

package/lib/hub/tunnel-inbox.d.ts

@@ -0,0 +1,20 @@
+import type { StoredMessage } from '@enkaku/hub-protocol';
+/**
+ * FIFO queue used by `HubConnection.tunnelMessageStream` to deliver synthetic /
+ * forwarded `StoredMessage` values to tunnel transports. Callers `push` messages;
+ * each consumer drains via an `AsyncIterator` returned from
+ * {@link TunnelInbox.iterator}. Disposal is idempotent: once `close` runs,
+ * subsequent pushes are dropped and pending iteration resolves to `done`.
+ *
+ * Multiple sequential iterators are supported (one consumer at a time, but
+ * iterators may be created and returned across the inbox's lifetime). Each
+ * iterator tracks its own pending waiter so `iterator.return()` drains only
+ * that iterator's waiter — leaving queued messages and other consumers'
+ * waiters intact for future iterators.
+ */
+export declare class TunnelInbox {
+    #private;
+    push(message: StoredMessage): void;
+    close(): void;
+    iterator(onReturn?: () => void): AsyncIterator<StoredMessage>;
+}

package/lib/hub/tunnel-inbox.js

@@ -0,0 +1 @@
+export class TunnelInbox{#e=[];#s=[];#t=!1;push(e){if(this.#t)return;let s=this.#s.shift();null!=s?s.resolve({value:e,done:!1}):this.#e.push(e)}close(){if(!this.#t)for(this.#t=!0;this.#s.length>0;){let e=this.#s.shift();e?.resolve({value:void 0,done:!0})}}iterator(e){let s=!1,t=new Set,i=()=>{if(!s){for(let e of(s=!0,t)){let s=this.#s.indexOf(e);s>=0&&this.#s.splice(s,1),e.resolve({value:void 0,done:!0})}t.clear(),e?.()}};return{next:()=>{let e;return s?Promise.resolve({value:void 0,done:!0}):this.#e.length>0?Promise.resolve({value:this.#e.shift(),done:!1}):this.#t?(i(),Promise.resolve({value:void 0,done:!0})):new Promise(s=>{e={resolve:s},t.add(e),this.#s.push(e)}).then(s=>(null!=e&&t.delete(e),!0===s.done&&i(),s))},return:()=>(i(),Promise.resolve({value:void 0,done:!0}))}}}

package/lib/hub/wait-for-gate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Wait for a reconnect gate (or similar boolean-style gate) to clear, with an
+ * optional timeout. If `gate` is null the call returns immediately without
+ * allocating any timer or signal — this is the hot path while the connection
+ * is healthy. If `timeoutMs` is undefined we simply await the gate without
+ * arming a timer (callers with no timeout can also omit `onTimeout` to skip
+ * the closure allocation). Both set: race the gate against
+ * `AbortSignal.timeout`; the first to settle wins.
+ *
+ * `onTimeout` is invoked lazily — only when the timeout actually fires — so
+ * callers can capture mutable state (e.g. current reconnect attempt) at the
+ * moment of failure rather than at call time.
+ */
+export declare function waitForGate(gate: Promise<void> | null, timeoutMs: number | undefined, onTimeout?: () => Error): Promise<void>;

package/lib/hub/wait-for-gate.js

@@ -0,0 +1 @@
+export async function waitForGate(e,t,r){if(null==e)return;if(null==t)return void await e;if(null==r)throw Error("waitForGate: onTimeout required when timeoutMs is set");let i=AbortSignal.timeout(t),n=null,o=new Promise((e,t)=>{i.aborted?t(r()):(n=()=>{t(r())},i.addEventListener("abort",n,{once:!0}))});try{await Promise.race([e,o])}finally{null!=n&&i.removeEventListener("abort",n)}}

package/lib/hub/wiring.d.ts

@@ -0,0 +1,73 @@
+import type { OwnIdentity } from '@enkaku/token';
+import type { KubunDB } from '@kubun/db';
+import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
+import type { Logger } from '@kubun/logger';
+import type { GroupBroadcastMessage } from '../groups/broadcast.js';
+import { type BroadcastEvent } from '../groups/broadcast-service.js';
+import type { GroupEventEmitter } from '../groups/events.js';
+import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+import type { ForwardingConfig } from '../sync/forwarder.js';
+import type { StoreUnreadableMode } from '../types.js';
+import type { OnServerDIDObserved } from './connection-pool.js';
+import type { GroupChannel, GroupChannelParams } from './group-channel.js';
+import type { HubConnection, HubConnectionParams } from './hub-connection.js';
+import { type CreateHubClient } from './relay-manager.js';
+export type HubWiring = {
+    ready: Promise<void>;
+    scheduleBroadcast: (groupID: string, message: GroupBroadcastMessage) => void;
+    dispose: () => Promise<void>;
+};
+export type SetupHubRelayParams = {
+    identity: OwnIdentity;
+    db: KubunDB;
+    /**
+     * Engine graph internals — threaded through to `BroadcastService` so the
+     * `mutation:apply` broadcast variant can route peer-authored mutations
+     * through the engine with `origin: 'peer'`.
+     */
+    graph: GraphInternals;
+    emitter: GroupEventEmitter;
+    createHubClient: CreateHubClient;
+    onRemoteBroadcast: (event: BroadcastEvent) => void;
+    /**
+     * Single canonical access point for MLS `GroupHandle` instances. Threaded
+     * into `BroadcastService` so encrypt/decrypt go through the per-group
+     * mutex once Phase 3 lands. Currently stored but unused.
+     */
+    registry: GroupHandleRegistry;
+    logger: Logger;
+    /**
+     * Optional testing seam forwarded to `HubRelayManager`. Production code
+     * leaves this unset so the manager uses its default `GroupChannel`
+     * constructor.
+     */
+    createGroupChannel?: (params: GroupChannelParams) => GroupChannel;
+    /**
+     * Optional testing seam forwarded to `HubRelayManager`. Production code
+     * leaves this unset so the manager uses its default `HubConnection`
+     * constructor.
+     */
+    createHubConnection?: (params: HubConnectionParams) => HubConnection;
+    /**
+     * Receive-side storage mode. Forwarded to `BroadcastService` →
+     * `processBroadcast`. Defaults to `'persist'` when omitted.
+     */
+    storeUnreadable?: StoreUnreadableMode;
+    /** Server default access level — required when `storeUnreadable === 'drop'`. */
+    defaultAccessLevel?: DefaultAccessLevel;
+    /**
+     * Forwarding config. Threaded through to `BroadcastService` →
+     * `processBroadcast` along with the hub's own `scheduleBroadcast` hook.
+     * Default `false` disables the receive-time forwarding pipeline.
+     */
+    forwarding?: ForwardingConfig;
+    /**
+     * Forwarded to `HubRelayManager` → `HubConnectionPool`. Fired with the
+     * observed `serverDID` after the first signed response from a freshly-spawned
+     * client. Lets callers route capture into `captureServerDID` for TOFU
+     * pinning; omitting it skips capture entirely.
+     */
+    onServerDIDObserved?: OnServerDIDObserved;
+};
+export declare function setupHubRelay(params: SetupHubRelayParams): HubWiring;
+export declare const DISABLED_HUB: HubWiring;

package/lib/hub/wiring.js

@@ -0,0 +1 @@
+import{BroadcastService as r}from"../groups/broadcast-service.js";import{HubRelayManager as e}from"./relay-manager.js";export function setupHubRelay(o){let a,{identity:t,db:d,graph:i,emitter:s,createHubClient:n,onRemoteBroadcast:p,registry:c,logger:u,createGroupChannel:h,createHubConnection:l,storeUnreadable:g,defaultAccessLevel:f,forwarding:m,onServerDIDObserved:y}=o,b=[],D=(r,e)=>{a.then(o=>o.broadcast(r,e).catch(e=>{u.error("broadcast failed",{groupID:r,error:e})}),()=>{})};return(a=(async()=>{let[o,a]=await Promise.all([d.getStore("p2p"),d.getStore("graph")]),v=new r({p2pStore:o,graphStore:a,graph:i,selfDID:t.id,registry:c,storeUnreadable:g,defaultAccessLevel:f,forwarding:m,scheduleBroadcast:D,logger:u}),B=new e({p2pStore:o,broadcastService:v,deviceID:t.id,createHubClient:n,logger:u,createGroupChannel:h,createHubConnection:l,onServerDIDObserved:y});b.push(v.on("broadcast",p)),b.push(s.on("groupJoined",r=>B.addGroup(r.id).catch(e=>{u.error("addGroup failed",{groupID:r.id,error:e})}))),b.push(s.on("groupLeft",r=>B.removeGroup(r.groupID).catch(e=>{u.error("removeGroup failed",{groupID:r.groupID,error:e})}))),b.push(s.on("hubBound",({groupID:r,hubURL:e})=>B.addBinding(r,e).catch(o=>{u.error("addBinding failed",{groupID:r,hubURL:e,error:o})}))),b.push(s.on("hubUnbound",({groupID:r,hubURL:e})=>B.removeBinding(r,e).catch(o=>{u.error("removeBinding failed",{groupID:r,hubURL:e,error:o})})));let w=await o.listGroups();return await B.start(w.map(r=>r.id)),B})()).catch(r=>{u.error("hub relay setup failed",{error:r})}),{ready:a.then(()=>void 0),scheduleBroadcast:D,dispose:async()=>{for(let r of b)try{r()}catch{}b.length=0;try{let r=await a;await r.stop()}catch{}}}}export const DISABLED_HUB={ready:Promise.resolve(),scheduleBroadcast:()=>{},dispose:async()=>{}};

package/lib/index.d.ts

@@ -1,26 +1,122 @@
-import type { KubunPlugin, PluginFactoryParams } from '@kubun/engine';
+import type { DefaultAccessLevel, KubunPlugin, PluginFactoryParams } from '@kubun/engine';
+import type { CreateHubClient } from './hub/relay-manager.js';
+import { type BroadcastBatchConfig } from './sync/broadcast-queue.js';
+import { type PushSyncConfig } from './sync/broadcast-sender.js';
+import type { ForwardingConfig } from './sync/forwarder.js';
+import type { StoreUnreadableMode } from './types.js';
 export type { ContextDeps, PendingJoinRequest } from './context/types.js';
-export { type GroupBroadcastMessage, type ProcessBroadcastParams, processBroadcast, } from './groups/broadcast.js';
+export { type AffectedRow, type GroupBroadcastMessage, type MutationApplyEntry, type ProcessBroadcastParams, type ProcessBroadcastResult, processBroadcast, } from './groups/broadcast.js';
 export { deserializeBroadcast, serializeBroadcast } from './groups/broadcast-codec.js';
-export { ApplyError, type BroadcastEvent, BroadcastService, type BroadcastServiceEvents, type BroadcastServiceParams, DecryptError, type ReceiveBroadcastParams, type ReceiveBroadcastResult, type SendBroadcastParams, type SendBroadcastResult, } from './groups/broadcast-service.js';
+export { ApplyError, type BroadcastEvent, BroadcastService, type BroadcastServiceEvents, type BroadcastServiceParams, DecryptError, type ReceiveBroadcastParams, type ReceiveBroadcastResult, type SendBroadcastParams, } from './groups/broadcast-service.js';
 export { createFilteredGenerator, createGroupEventEmitter, type GroupEventEmitter, type GroupEventMap, } from './groups/events.js';
-export { decodeFullJoinRequest, decodeInvitePayload, decodeJoinRequest, encodeFullJoinRequest, encodeInvitePayload, encodeJoinRequest, type FullJoinRequestPayload, type InvitePayload, type JoinRequestPayload, } from './groups/invite-payload.js';
+export { GroupHandleRegistry, type GroupHandleRegistryParams, type SeedParams, } from './groups/group-handle-registry.js';
+export { decodeFullJoinRequest, decodeInvitePayload, decodeJoinRequest, encodeFullJoinRequest, encodeInvitePayload, encodeJoinRequest, type FullJoinRequestPayload, type InvitePayload, type JoinRequestPayload, type SuggestedHub, } from './groups/invite-payload.js';
 export { type AddCircleMemberParams, type AddCircleMemberResult, type CreateCircleParams, type CreateCircleResult, type CreateGroupParams, type CreateGroupResult, type DeleteCircleParams, type DeleteCircleResult, GroupManager, type GroupManagerParams, type InviteToGroupParams, type InviteToGroupResult, type JoinGroupParams, type JoinGroupResult, type LeaveGroupParams, type LeaveGroupResult, type RemoveCircleMemberParams, type RemoveCircleMemberResult, type RemoveGroupMemberParams, type RemoveGroupMemberResult, type RemoveMemberParams, type RemoveMemberResult, type UpdateCircleParams, type UpdateCircleResult, type UpdateGroupParams, type UpdateGroupResult, } from './groups/manager.js';
+export { MLSEncryptor, type MLSEncryptorParams } from './groups/mls-encryptor.js';
 export { type MLSGroupHandle, restoreMLSGroupHandle } from './groups/mls-group-handle.js';
 export { replacer as mlsJSONReplacer, reviver as mlsJSONReviver } from './groups/mls-json.js';
 export { deserializeMLSGroupState, type MLSGroupState, type SerializedMLSGroupState, serializeMLSGroupState, } from './groups/mls-state.js';
 export type { SyncClientMessage, SyncProtocol, SyncServerMessage } from './protocol.js';
 export { createP2PSchemaExtension } from './schema.js';
+export { type BroadcastBatchConfig, type BroadcastQueue, type BroadcastQueueParams, createBroadcastQueue, DEFAULT_BROADCAST_BATCH_CONFIG, } from './sync/broadcast-queue.js';
+export { type BroadcastSenderParams, DEFAULT_PUSH_SYNC_CONFIG, type PushSyncConfig, wireBroadcastSender, } from './sync/broadcast-sender.js';
+export { catalogMatchesDoc } from './sync/catalog-match.js';
 export { type CatalogSyncScope, resolveCatalogSyncScopes } from './sync/catalog-scope.js';
+export { type EvaluateAndForwardParams, type EvaluateAndForwardResult, evaluateAndForward, type ForwardContext, type ForwardFilter, type ForwardingConfig, } from './sync/forwarder.js';
 export { checkSyncDelegation, negotiateDirection } from './sync/handlers.js';
+export { HubTunnelSyncListener, type HubTunnelSyncListenerParams, } from './sync/hub-tunnel-sync-listener.js';
+export { HubTunnelSyncProvider, type HubTunnelSyncProviderParams, } from './sync/hub-tunnel-sync-provider.js';
 export { type PeerConfig, type PeerConfigWithID, PeerRegistry } from './sync/peer-registry.js';
 export { SyncClient, type SyncClientParams, type SyncScope, type SyncTransportProvider, } from './sync/sync-client.js';
 export { type SyncEvent, SyncManager, type SyncManagerParams, type SyncSessionInfo, type SyncStatus, } from './sync/sync-manager.js';
+export type { OnServerDIDObserved } from './hub/connection-pool.js';
+export { DIDObservingTransport, type DIDObservingTransportParams, type ServerDIDObserver, } from './hub/did-observing-transport.js';
+export { ReconnectingError } from './hub/errors.js';
 export type { GroupChannel, GroupChannelParams } from './hub/group-channel.js';
-export { type CreateGroupChannel, type CreateHubClient, HubRelayManager, type HubRelayManagerParams, } from './hub/relay-manager.js';
-export type { CatalogData, CircleData, CircleMemberData, DeleteCatalogData, DeleteCircleData, GroupData, GroupMemberData, GroupRequestContext, InviteToGroupData, JoinGroupData, LeaveGroupData, P2PContext, P2PJoinRequestContext, RemoveCircleMemberData, RemoveGroupMemberData, SyncPluginAPI, SyncRequestContext, SyncSessionResult, UpdateCircleInput, UpdateGroupInput, } from './types.js';
+export { type CreateHTTPHubClientParams, createHTTPHubClient } from './hub/http-client.js';
+export type { ConnectionLifecycleEvent } from './hub/hub-connection.js';
+export { type BindHubToGroupParams, bindHubToGroup, type CaptureServerDIDParams, type CreateHubParams, captureServerDID, createHub, type DeleteHubParams, type DeleteHubResult, deleteHub, type GetHubParams, getHub, type Hub, HubServerDIDConflictError, type ListGroupsByHubParams, type ListHubsByGroupParams, type ListHubsParams, listGroupsByHub, listHubs, listHubsByGroup, type UnbindHubFromGroupParams, type UpdateHubParams, type UpsertHubParams, unbindHubFromGroup, updateHub, upsertHub, } from './hub/manager.js';
+export { type CreateGroupChannel, type CreateHubClient, type CreateHubClientOptions, type CreateHubConnection, HubRelayManager, type HubRelayManagerParams, type RelayEvent, } from './hub/relay-manager.js';
+export { DISABLED_HUB, type HubWiring, type SetupHubRelayParams, setupHubRelay, } from './hub/wiring.js';
+export type { CatalogData, CircleData, CircleMemberData, DeleteCatalogData, DeleteCircleData, GroupData, GroupMemberData, GroupRequestContext, InviteToGroupData, JoinGroupData, LeaveGroupData, P2PContext, P2PJoinRequestContext, RemoveCircleMemberData, RemoveGroupMemberData, StoreUnreadableMode, SyncPluginAPI, SyncRequestContext, SyncSessionResult, UpdateCircleInput, UpdateGroupInput, } from './types.js';
+export type ReceiveConfig = {
+    /**
+     * Receiver storage mode for incoming peer mutations.
+     * - `'persist'` (default) — store every doc that passes catalog/group
+     *   checks. Access enforced at query time; unreadable docs remain in DB
+     *   but filtered.
+     * - `'drop'` — apply read-access check at receive time using the local
+     *   peer's own DID as viewer. Mutations the local peer cannot read are
+     *   not persisted.
+     */
+    storeUnreadable: StoreUnreadableMode;
+};
+/**
+ * Default receive config. Under `'persist'` no gate is built and no extra
+ * DB lookups occur during receive.
+ */
+export declare const DEFAULT_RECEIVE_CONFIG: ReceiveConfig;
 export type P2PPluginOptions = {
     autoAcceptPeers?: Array<string>;
     http?: boolean | string;
+    /**
+     * Enable hub-mediated group broadcasts.
+     * - `true` / `{}` — build a default HTTP hub client factory from
+     *   `params.identity` + `params.runtime.fetch`.
+     * - `{ createHubClient }` — caller supplies a custom factory.
+     * - absent / `false` — hub relay disabled; all broadcast call-sites are
+     *   no-ops.
+     */
+    hub?: boolean | {
+        createHubClient?: CreateHubClient;
+    };
+    /**
+     * Batch broadcast queue config. Sender-side mutation:apply broadcasts are
+     * accumulated per target MLS group and flushed when window/count/byte
+     * thresholds trip. Defaults from {@link DEFAULT_BROADCAST_BATCH_CONFIG}.
+     * Set `enabled: false` to bypass the queue and emit one broadcast per
+     * mutation per scope.
+     */
+    batch?: Partial<BroadcastBatchConfig>;
+    /**
+     * Push-sync config. Gates the local `engine:mutation:authored` subscriber
+     * that drives `mutation:apply` broadcasts.
+     * - When `enabled: false` (default), no `mutation:apply` broadcasts are
+     *   emitted from this peer when local mutations land — even if `hub` is
+     *   configured. Merkle-pull continues to work, and the receive path
+     *   (incoming `mutation:apply` broadcasts) is unaffected.
+     * - When `enabled: true`, locally-authored mutations fan out per-scope
+     *   through the hub.
+     *
+     * Defaults from {@link DEFAULT_PUSH_SYNC_CONFIG}.
+     */
+    pushSync?: Partial<PushSyncConfig>;
+    /**
+     * Receive-side storage config. Controls whether peer mutations the local
+     * peer cannot read are persisted to the local DB or dropped at receive
+     * time. Defaults to {@link DEFAULT_RECEIVE_CONFIG} (persist).
+     */
+    receive?: Partial<ReceiveConfig>;
+    /**
+     * Server default access level used by the receive-time access gate when
+     * `receive.storeUnreadable === 'drop'` and no document or per-user-model
+     * default rule is declared. Defaults to `{ read: 'only_owner', write:
+     * 'only_owner' }` (no fan-out for undeclared models). Ignored under
+     * `'persist'`.
+     */
+    defaultAccessLevel?: DefaultAccessLevel;
+    /**
+     * Forwarding config. Controls per-peer N+1 re-broadcast.
+     * - `false` (default) — incoming `mutation:apply` broadcasts are NOT
+     *   re-broadcast.
+     * - `true` — re-broadcast each applied entry to every other MLS group the
+     *   local peer belongs to whose access + catalog gates pass.
+     * - {@link ForwardFilter} — same as `true`, plus per-candidate filter
+     *   callback that further narrows. Filter receives a {@link ForwardContext}.
+     *
+     * Push-sync config (`pushSync.enabled`) is orthogonal — forwarding fires
+     * regardless of whether locally-authored mutations are broadcast.
+     */
+    forwarding?: ForwardingConfig;
 };
 export declare function createP2PPlugin(options?: P2PPluginOptions): (params: PluginFactoryParams) => KubunPlugin;