@kubun/plugin-p2p 0.8.3 → 0.10.0

package/lib/hub/did-observing-transport.d.ts

@@ -0,0 +1,64 @@
+import { Disposer } from '@enkaku/async';
+import type { EventEmitter } from '@enkaku/event';
+import type { AnyClientMessageOf, AnyServerMessageOf, ClientTransportOf, ProtocolDefinition } from '@enkaku/protocol';
+import type { TransportEvents } from '@enkaku/transport';
+export type ServerDIDObserver = (serverDID: string) => void | Promise<void>;
+export type ServerDIDMismatchObserver = (params: {
+    hubURL: string;
+    expectedServerDID: string;
+    observedServerDID: string;
+}) => void;
+export type DIDObservingTransportParams<Protocol extends ProtocolDefinition> = {
+    inner: ClientTransportOf<Protocol>;
+    /**
+     * Fired on the first message bearing `payload.iss` when no `expectedServerDID`
+     * is set (TOFU capture). When `expectedServerDID` is set and matches, the
+     * callback is NOT fired — the pin is already authoritative.
+     */
+    onServerDID: ServerDIDObserver;
+    /**
+     * Pinned hub server DID. When set, the wrapper enforces it: a non-matching
+     * first observed `iss` triggers a permanent failed state — `read()` rejects
+     * with `HubServerDIDMismatchError`, the offending message is NOT delivered
+     * to the inner Client, and every subsequent `read()` re-raises the same
+     * error. When unset, the wrapper falls back to TOFU capture.
+     */
+    expectedServerDID?: string;
+    /** Hub URL — only used to populate `HubServerDIDMismatchError` for callers. */
+    hubURL?: string;
+    /**
+     * Optional side-channel notification fired on mismatch. Lets the pool log /
+     * evict without having to inspect the rejected `read()` cause. Inner
+     * transport disposal is the pool's job, not the wrapper's.
+     */
+    onMismatch?: ServerDIDMismatchObserver;
+};
+/**
+ * Wraps a `ClientTransportOf<Protocol>` to enforce hub-server-DID
+ * TOFU + pinned-mismatch semantics on the receive side.
+ *
+ * - `expectedServerDID == null`: TOFU mode. First message bearing
+ *   `payload.iss` fires `onServerDID(iss)` exactly once; subsequent messages
+ *   never re-fire, even with a differing `iss`. Every message is forwarded
+ *   to the inner Client untouched.
+ * - `expectedServerDID != null` and the first observed `iss` matches: the
+ *   pin is already authoritative; `onServerDID` is NOT fired and forwarding
+ *   continues normally.
+ * - `expectedServerDID != null` and the first observed `iss` differs: the
+ *   wrapper enters a permanent failed state (`HubServerDIDMismatchError`).
+ *   The current `read()` call AND every subsequent `read()` reject with the
+ *   error; the offending message is NOT delivered. Inner-transport lifecycle
+ *   stays the pool's responsibility — the wrapper does not dispose its inner.
+ *
+ * Extends `Disposer` and matches the `ClientTransportOf<Protocol>` shape
+ * structurally so it can be passed straight to `Client<Protocol>`.
+ */
+export declare class DIDObservingTransport<Protocol extends ProtocolDefinition> extends Disposer {
+    #private;
+    constructor(params: DIDObservingTransportParams<Protocol>);
+    get events(): EventEmitter<TransportEvents>;
+    getWritable(): WritableStream<AnyClientMessageOf<Protocol>>;
+    read(): Promise<ReadableStreamReadResult<AnyServerMessageOf<Protocol>>>;
+    write(value: AnyClientMessageOf<Protocol>): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterator<AnyServerMessageOf<Protocol>, AnyServerMessageOf<Protocol> | null>;
+}

package/lib/hub/did-observing-transport.js

@@ -0,0 +1 @@
+import{Disposer as e}from"@enkaku/async";import{HubServerDIDMismatchError as r}from"./errors.js";export class DIDObservingTransport extends e{#e;#r;#t;#n;#i;#s=!1;#l=null;constructor(e){super({signal:e.inner.signal,dispose:async r=>{await e.inner.dispose(r)}}),this.#e=e.inner,this.#r=e.onServerDID,this.#t=e.expectedServerDID,this.#n=e.hubURL,this.#i=e.onMismatch}get events(){return this.#e.events}getWritable(){return this.#e.getWritable()}async read(){if(null!=this.#l)throw this.#l;let e=await this.#e.read(),r=this.#a(e);if(null!=r)throw r;return e}async write(e){await this.#e.write(e)}[Symbol.asyncIterator](){return{next:async()=>{let e=await this.read();return e.done?{done:!0,value:e.value??null}:{done:!1,value:e.value}}}}#a(e){if(this.#s||e.done||null==e.value)return null;let t=e.value.payload,n=t?.iss;if("string"!=typeof n||0===n.length)return null;if(this.#s=!0,null!=this.#t){if(n===this.#t)return null;let e=new r({hubURL:this.#n??"",expectedServerDID:this.#t,observedServerDID:n});if(this.#l=e,null!=this.#i)try{this.#i({hubURL:this.#n??"",expectedServerDID:this.#t,observedServerDID:n})}catch{}return e}return Promise.resolve().then(()=>this.#r(n)).catch(()=>{}),null}}

package/lib/hub/errors.d.ts

@@ -0,0 +1,28 @@
+export declare class ReconnectingError extends Error {
+    readonly hubURL: string;
+    readonly attempt: number;
+    constructor(hubURL: string, attempt: number);
+}
+/**
+ * Thrown by `DIDObservingTransport.read()` when the first observed `payload.iss`
+ * does not match the pinned `expectedServerDID`. The transport enters a
+ * permanent failed state: no message bearing the offending `iss` is delivered
+ * to the inner Client, and every subsequent `read()` rejects with the same
+ * error. In-flight Enkaku RPCs see this error as the `cause` of the Client's
+ * "Transport read failed" abort.
+ *
+ * Distinct from `HubServerDIDConflictError` (raised by manager-level
+ * `captureServerDID` when the pin row already differs from the observed DID
+ * on the TOFU capture path); this class is raised client-side, before any
+ * message is delivered, when a row was already pinned at connect time.
+ */
+export declare class HubServerDIDMismatchError extends Error {
+    readonly hubURL: string;
+    readonly expectedServerDID: string;
+    readonly observedServerDID: string;
+    constructor(params: {
+        hubURL: string;
+        expectedServerDID: string;
+        observedServerDID: string;
+    });
+}

package/lib/hub/errors.js

@@ -0,0 +1 @@
+export class ReconnectingError extends Error{hubURL;attempt;constructor(e,r){super(`broadcast wait timed out: hub ${e} reconnecting (attempt ${r})`),this.name="ReconnectingError",this.hubURL=e,this.attempt=r}}export class HubServerDIDMismatchError extends Error{hubURL;expectedServerDID;observedServerDID;constructor(e){super(`hub at ${e.hubURL} signed responses with ${e.observedServerDID}; pinned to ${e.expectedServerDID}`),this.name="HubServerDIDMismatchError",this.hubURL=e.hubURL,this.expectedServerDID=e.expectedServerDID,this.observedServerDID=e.observedServerDID}}

package/lib/hub/forward-remote-broadcast.d.ts

@@ -0,0 +1,15 @@
+import type { Logger } from '@kubun/logger';
+import type { BroadcastEvent } from '../groups/broadcast-service.js';
+import type { P2PEventEmitter } from '../groups/events.js';
+/**
+ * Map a `BroadcastEvent` from `BroadcastService` into the matching
+ * `P2PEventEmitter` event.
+ *
+ * - Events with `applied === false` are ignored (no state change).
+ * - `catalog:*` messages are currently a no-op. Catalog send-side broadcasts
+ *   and event propagation are deferred to a future task (see design spec).
+ * - Payloads are built from `event.affected.row`, which `processBroadcast`
+ *   captures at the appropriate moment (after-state for create / update,
+ *   before-state for delete / remove).
+ */
+export declare function forwardRemoteBroadcast(emitter: P2PEventEmitter, event: BroadcastEvent, logger?: Logger): Promise<void>;

package/lib/hub/forward-remote-broadcast.js

@@ -0,0 +1 @@
+import{toISO as e}from"../context/types.js";export async function forwardRemoteBroadcast(r,t,a){if(!t.applied)return;let{message:i,affected:c}=t;if("delegation:share"!==i.type){if(null==c)return void a?.warn("remote broadcast applied but affected row missing",{type:i.type});switch(i.type){case"circle:create":{if("circle"!==c.kind)return;let{row:t}=c;await r.emit("circleCreated",{id:t.id,groupID:t.group_id,name:t.name,description:t.description,createdAt:e(t.created_at)});return}case"circle:update":{if("circle"!==c.kind)return;let{row:t}=c,a=null!=i.update.catalogIDs?"circleCatalogsChanged":"circleDataChanged";await r.emit(a,{id:t.id,groupID:t.group_id,name:t.name,description:t.description,createdAt:e(t.created_at),circleID:t.id});return}case"circle:delete":{if("circle"!==c.kind)return;let{row:t}=c;await r.emit("circleDeleted",{id:t.id,groupID:t.group_id,name:t.name,description:t.description,createdAt:e(t.created_at)});return}case"member:add":{if("member"!==c.kind)return;let{row:t}=c;await r.emit("circleMemberAdded",{circleID:t.circle_id,memberDID:t.member_did,role:t.role,createdAt:e(t.created_at)});return}case"member:remove":{if("member"!==c.kind)return;let{row:t}=c;await r.emit("circleMemberRemoved",{circleID:t.circle_id,memberDID:t.member_did,role:t.role,createdAt:e(t.created_at)});return}case"group:update":{if("group"!==c.kind)return;let{row:t}=c;await r.emit("groupDataChanged",{id:t.id,name:t.name,description:t.description,createdBy:t.created_by,createdAt:e(t.created_at),groupID:t.id});return}case"catalog:create":case"catalog:update":case"catalog:delete":return void a?.debug("catalog broadcast ignored (not yet wired)",{type:i.type})}}}

package/lib/hub/group-channel.d.ts

@@ -1,26 +1,9 @@
+import { Disposer } from '@enkaku/async';
 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 { HubConnectionPool } from './connection-pool.js';
-export type GroupChannelParams = {
-    groupID: string;
-    hubURL: string;
-    deviceID: string;
-    pool: HubConnectionPool;
-    broadcastService: BroadcastService;
-    p2pStore: P2PStoreAPI;
-    logger?: Logger;
-    ackFlushMs: number;
-    ackFlushMax: number;
-    backoffBaseMs: number;
-    backoffMaxMs: number;
-    backoffJitter: number;
-};
-export type Mutex = {
-    run<T>(fn: () => Promise<T>): Promise<T>;
-};
-export declare function createMutex(): Mutex;
+import type { HubConnection } from './hub-connection.js';
 export type AckBatchParams = {
     flushMs: number;
     flushMax: number;
@@ -42,10 +25,43 @@ export declare class AckBatch {
 }
 export declare function computeBackoff(attempt: number, base: number, max: number, jitter: number): number;
 export declare function abortableSleep(ms: number, signal: AbortSignal): Promise<void>;
-export declare class GroupChannel {
+export type GroupChannelParams = {
+    groupID: string;
+    deviceID: string;
+    hubConnection: HubConnection;
+    broadcastService: BroadcastService;
+    p2pStore: P2PStoreAPI;
+    logger?: Logger;
+};
+/**
+ * Per-group handle: thin wrapper around a shared `HubConnection`.
+ *
+ * `open()` subscribes to the connection (issuing `hub/group/join` once),
+ * `close()` unsubscribes (drains the per-group mutex then issues
+ * `hub/group/leave`), and `broadcast()` runs the MLS encrypt+send pipeline
+ * inside `HubConnection.runInGroup()` so the per-group mutex serializes send
+ * and receive on the same MLS state.
+ *
+ * All transport state (refID, ack batching, receive loop, reconnect/backoff)
+ * lives on `HubConnection` and is shared across every channel for that
+ * `hubURL`. A peer with N groups uses ONE `hub/receive` stream per
+ * `(deviceDID, hubURL)` rather than N — this preserves the hub-server's
+ * single-writer-per-DID invariant for bridge peers.
+ */
+export declare class GroupChannel extends Disposer {
     #private;
     constructor(params: GroupChannelParams);
     open(): Promise<void>;
     close(): Promise<void>;
-    broadcast(message: GroupBroadcastMessage): Promise<void>;
+    broadcast(message: GroupBroadcastMessage, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Fan out a pre-produced MLS handshake Commit to the group's existing
+     * members. Mirrors {@link broadcast} but routes through `handleSendCommit`
+     * (no application encryption — the Commit is already self-protected).
+     */
+    sendCommit(commitBytes: Uint8Array, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
 }

package/lib/hub/group-channel.js

@@ -1 +1 @@
-import{handleReceivedMessage as e}from"./receive-handler.js";import{handleSendBroadcast as t}from"./send-handler.js";export function createMutex(){let e=Promise.resolve();return{run(t){let r=e.then(()=>t());return e=r.catch(()=>{}),r}}}export class AckBatch{#e;#t;#r;#i;#s=new Set;#o=null;constructor(e){this.#e=e.flushMs,this.#t=e.flushMax,this.#r=e.send,this.#i=e.logger}add(e){let t=0===this.#s.size;if(this.#s.add(e),this.#s.size>=this.#t){null!==this.#o&&(clearTimeout(this.#o),this.#o=null),this.flush();return}t&&null===this.#o&&(this.#o=setTimeout(()=>{this.#o=null,this.flush()},this.#e))}async flush(){if(null!==this.#o&&(clearTimeout(this.#o),this.#o=null),0===this.#s.size)return;let e=Array.from(this.#s);this.#s.clear();try{await this.#r(e)}catch(t){this.#i?.error("ack batch send failed",{error:t,count:e.length})}}dispose(){null!==this.#o&&(clearTimeout(this.#o),this.#o=null),this.#s.clear()}}export function computeBackoff(e,t,r,i){let s=Math.min(t*2**e*(1+i*(2*Math.random()-1)),r);return s<0?0:s}export function abortableSleep(e,t){return new Promise((r,i)=>{if(t.aborted)return void i(t.reason??Error("aborted"));let s=setTimeout(()=>{t.removeEventListener("abort",o),r()},e),o=()=>{clearTimeout(s),t.removeEventListener("abort",o),i(t.reason??Error("aborted"))};t.addEventListener("abort",o)})}let r=Symbol("disposed");export class GroupChannel{#a;#h;#l;#n;#c;#u;#i;#p;#g;#d;#f;#b;#I;#D=new AbortController;#m=null;#k=null;#v=null;#M=null;#y=null;#w=0;#x=!1;#C=!1;constructor(e){this.#a=e.groupID,this.#h=e.hubURL,this.#l=e.deviceID,this.#n=e.pool,this.#c=e.broadcastService,this.#u=e.p2pStore,this.#i=e.logger,this.#p=e.ackFlushMs,this.#g=e.ackFlushMax,this.#d=e.backoffBaseMs,this.#f=e.backoffMaxMs,this.#b=e.backoffJitter,this.#I=createMutex()}async open(){if(this.#x)throw Error("GroupChannel already opened");try{await this.#S(),this.#x=!0}catch(e){if(null!=this.#k){try{await this.#n.release(this.#h,this.#k)}catch(e){this.#i?.debug("pool release after open failure failed",{groupID:this.#a,error:e})}this.#k=null}throw this.#m=null,e}}async #S(){if(null!=this.#k){let e=this.#k;this.#k=null,this.#m=null;try{await this.#n.release(this.#h,e)}catch(e){this.#i?.debug("pool release before reconnect failed",{groupID:this.#a,error:e})}}let{client:e,refID:t}=await this.#n.acquire(this.#h);this.#m=e,this.#k=t;let r=await this.#u.getMLSState(this.#a,this.#l);if(null==r)throw Error(`MLS state missing for group ${this.#a}; cannot join hub group`);await e.request("hub/group/join",{param:{groupID:this.#a,credential:r.credential}});let i=e.createChannel("hub/receive",{param:{groupIDs:[this.#a]},signal:this.#D.signal});this.#v=i,i.catch(()=>{}),this.#M=new AckBatch({flushMs:this.#p,flushMax:this.#g,send:async e=>{await i.send({ack:e})},logger:this.#i}),this.#y=this.#L(e).catch(e=>{this.#i?.debug("receive task tail error",{groupID:this.#a,error:e})}),this.#C=!0}async #L(t){let i=this.#v;if(null==i)return;let s=i.readable.getReader();try{for(;!this.#D.signal.aborted;){let i=s.read(),o=t.disposed.then(()=>r),a=await Promise.race([i,o]);if("symbol"==typeof a){this.#i?.debug("receive loop observed hub client disposal",{groupID:this.#a});break}let{done:h,value:l}=a;if(h)break;(await this.#I.run(()=>e({groupID:this.#a,deviceID:this.#l,message:l,p2pStore:this.#u,broadcastService:this.#c,logger:this.#i}))).ack&&this.#M?.add(l.sequenceID),this.#w=0}}catch(e){this.#i?.warn("hub receive loop error",{groupID:this.#a,error:e})}finally{try{s.releaseLock()}catch{}}this.#C=!1,this.#D.signal.aborted||this.#B()}#B(){this.#C=!1,this.#y=this.#R().catch(e=>{this.#i?.debug("reconnect task tail error",{groupID:this.#a,error:e})})}async #R(){for(;!this.#D.signal.aborted;){this.#C=!1;let e=computeBackoff(this.#w++,this.#d,this.#f,this.#b);this.#i?.debug("reconnect scheduled",{groupID:this.#a,delay:e,attempt:this.#w});try{await abortableSleep(e,this.#D.signal)}catch{return}try{this.#M?.dispose(),this.#M=null,this.#v=null,await this.#S(),this.#w=0;return}catch(e){this.#i?.warn("reconnect attempt failed",{groupID:this.#a,attempt:this.#w,error:e})}}}async close(){if(!this.#x)return;this.#C=!1;let e=this.#M;this.#M=null;try{await e?.flush()}catch(e){this.#i?.debug("ack flush during close failed",{groupID:this.#a,error:e})}e?.dispose();try{await this.#m?.request("hub/group/leave",{param:{groupID:this.#a}})}catch(e){this.#i?.warn("hub/group/leave failed",{groupID:this.#a,error:e})}try{this.#v?.close()}catch{}if(!this.#D.signal.aborted)try{this.#D.abort()}catch{}try{await this.#y}catch{}if(null!=this.#k){try{await this.#n.release(this.#h,this.#k)}catch(e){this.#i?.debug("pool release during close failed",{groupID:this.#a,error:e})}this.#k=null}this.#m=null,this.#v=null,this.#y=null,this.#x=!1}broadcast(e){return this.#x&&this.#C&&null!=this.#m?this.#I.run(async()=>{if(!this.#x||!this.#C||null==this.#m)throw Error(`GroupChannel for ${this.#a} is not ready for broadcast`);let r=this.#m;return t({groupID:this.#a,deviceID:this.#l,message:e,p2pStore:this.#u,broadcastService:this.#c,hubClient:r,logger:this.#i})}):Promise.reject(Error(`GroupChannel for ${this.#a} is not ready for broadcast`))}}
+import{Disposer as e}from"@enkaku/async";import{handleReceivedMessage as t}from"./receive-handler.js";import{handleSendBroadcast as r,handleSendCommit as i}from"./send-handler.js";export class AckBatch{#e;#t;#r;#i;#s=new Set;#o=null;constructor(e){this.#e=e.flushMs,this.#t=e.flushMax,this.#r=e.send,this.#i=e.logger}add(e){let t=0===this.#s.size;if(this.#s.add(e),this.#s.size>=this.#t){null!==this.#o&&(clearTimeout(this.#o),this.#o=null),this.flush();return}t&&null===this.#o&&(this.#o=setTimeout(()=>{this.#o=null,this.flush()},this.#e))}async flush(){if(null!==this.#o&&(clearTimeout(this.#o),this.#o=null),0===this.#s.size)return;let e=Array.from(this.#s);this.#s.clear();try{await this.#r(e)}catch(t){this.#i?.error("ack batch send failed",{error:t,count:e.length})}}dispose(){null!==this.#o&&(clearTimeout(this.#o),this.#o=null),this.#s.clear()}}export function computeBackoff(e,t,r,i){let s=Math.min(t*2**e*(1+i*(2*Math.random()-1)),r);return s<0?0:s}export function abortableSleep(e,t){return new Promise((r,i)=>{if(t.aborted)return void i(t.reason??Error("aborted"));let s=setTimeout(()=>{t.removeEventListener("abort",o),r()},e),o=()=>{clearTimeout(s),t.removeEventListener("abort",o),i(t.reason??Error("aborted"))};t.addEventListener("abort",o)})}export class GroupChannel extends e{#n;#h;#a;#u;#c;#i;#d=!1;constructor(e){super({dispose:async()=>{await this.#l()}}),this.#n=e.groupID,this.#h=e.deviceID,this.#a=e.hubConnection,this.#u=e.broadcastService,this.#c=e.p2pStore,this.#i=e.logger}async open(){if(this.#d)throw Error("GroupChannel already opened");let e=await this.#c.getMLSState(this.#n,this.#h);if(null==e)throw Error(`MLS state missing for group ${this.#n}; cannot join hub group`);await this.#a.subscribe(this.#n,e.credential,e=>this.#p(e)),this.#d=!0}#p(e){return t({groupID:this.#n,message:e,broadcastService:this.#u,logger:this.#i})}async close(){this.#d&&await this.dispose()}async #l(){if(this.#d){try{await this.#a.unsubscribe(this.#n)}catch(e){this.#i?.warn("hub-connection unsubscribe failed during close",{groupID:this.#n,error:e})}this.#d=!1}}broadcast(e,t){return this.#d?this.#a.runInGroup(this.#n,async()=>{if(!this.#d)throw Error(`GroupChannel for ${this.#n} is not ready for broadcast`);await r({groupID:this.#n,message:e,broadcastService:this.#u,send:(e,r)=>this.#a.broadcast(e,r,{timeoutMs:t?.timeoutMs}),logger:this.#i})},{timeoutMs:t?.timeoutMs}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for broadcast`))}sendCommit(e,t){return this.#d?this.#a.runInGroup(this.#n,async()=>{if(!this.#d)throw Error(`GroupChannel for ${this.#n} is not ready for sendCommit`);await i({groupID:this.#n,commitBytes:e,broadcastService:this.#u,send:(e,r)=>this.#a.broadcast(e,r,{timeoutMs:t?.timeoutMs}),logger:this.#i})},{timeoutMs:t?.timeoutMs}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for sendCommit`))}}

package/lib/hub/http-client.d.ts

@@ -0,0 +1,17 @@
+import type { Identity } from '@enkaku/token';
+import { type ServerDIDObserver } from './did-observing-transport.js';
+import type { CreateHubClient } from './relay-manager.js';
+export type CreateHTTPHubClientParams = {
+    identity: Identity;
+    fetch?: typeof globalThis.fetch;
+    serverID?: string;
+    /**
+     * Fired once per hub client when the first signed response from the server
+     * arrives carrying `payload.iss = serverDID`. Subsequent responses do NOT
+     * re-fire this hook, even if `iss` differs. Used by `HubConnectionPool` to
+     * drive TOFU pinning into the hub manager. Per-call `onServerDID` from
+     * `CreateHubClientOptions` overrides this factory-level default.
+     */
+    onServerDID?: ServerDIDObserver;
+};
+export declare function createHTTPHubClient(params: CreateHTTPHubClientParams): CreateHubClient;

package/lib/hub/http-client.js

@@ -0,0 +1 @@
+import{Client as e}from"@enkaku/client";import{ClientTransport as r}from"@enkaku/http-client-transport";import{DIDObservingTransport as t}from"./did-observing-transport.js";export function createHTTPHubClient(n){return async(o,i)=>{let l=new r({url:o,fetch:n.fetch}),u=i?.onServerDID??n.onServerDID,D=i?.expectedServerDID,c=i?.onMismatch;return new e({transport:null!=u||null!=D||null!=c?new t({inner:l,onServerDID:u??(()=>{}),expectedServerDID:D,hubURL:o,onMismatch:c}):l,identity:n.identity,serverID:n.serverID})}}

package/lib/hub/hub-connection.d.ts

@@ -0,0 +1,96 @@
+import { Disposer } from '@enkaku/async';
+import { EventEmitter } from '@enkaku/event';
+import type { StoredMessage } from '@enkaku/hub-protocol';
+import type { Logger } from '@kubun/logger';
+import type { HubConnectionPool } from './connection-pool.js';
+import type { ReceivedHubMessage } from './receive-handler.js';
+export type TunnelMessageStream = AsyncIterable<StoredMessage> & {
+    return(): void;
+};
+export type TunnelMessageStreamParams = {
+    peerDID: string;
+};
+export type SubscriptionHandler = (message: ReceivedHubMessage) => Promise<{
+    ack: boolean;
+}>;
+export type ConnectionLifecycleEvent = {
+    type: 'connected';
+} | {
+    type: 'disconnected';
+    reason?: string;
+} | {
+    type: 'error';
+    error: unknown;
+} | {
+    type: 'reconnecting';
+    attempt: number;
+    delayMs: number;
+};
+type HubConnectionEvents = {
+    lifecycle: ConnectionLifecycleEvent;
+};
+export type HubConnectionParams = {
+    hubURL: string;
+    deviceID: string;
+    pool: HubConnectionPool;
+    logger?: Logger;
+    ackFlushMs?: number;
+    ackFlushMax?: number;
+    backoffBaseMs?: number;
+    backoffMaxMs?: number;
+    backoffJitter?: number;
+};
+export declare class HubConnection extends Disposer {
+    #private;
+    constructor(params: HubConnectionParams);
+    get events(): EventEmitter<HubConnectionEvents>;
+    open(): Promise<void>;
+    subscribe(groupID: string, credential: string, handler: SubscriptionHandler): Promise<void>;
+    unsubscribe(groupID: string): Promise<void>;
+    broadcast(groupID: string, encryptedPayload: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Send an opaque tunnel-style message to explicit recipients via
+     * `hub/send`. No `groupID` is attached at the hub level — recipients
+     * receive the message on the tunnel-routing path (see
+     * {@link tunnelMessageStream}). Used by hub-mediated document sync.
+     */
+    send(params: {
+        recipients: Array<string>;
+        payload: Uint8Array;
+        timeoutMs?: number;
+    }): Promise<{
+        sequenceID: string;
+    }>;
+    /**
+     * Run `fn` inside the same per-group mutex used by receive `#dispatch`. This
+     * lets callers (e.g. `GroupChannel.broadcast`) serialize MLS-state-mutating
+     * pipelines with incoming-message handling on the same group, avoiding races
+     * between concurrent send-encrypt and receive-decrypt against shared MLS
+     * group state.
+     *
+     * The gate-await ensures the subscription map is settled before lookup —
+     * i.e. mid-reconnect callers wait for the subscription to be (re)registered
+     * rather than throwing.
+     */
+    runInGroup<T>(groupID: string, fn: () => Promise<T>, opts?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    /**
+     * Register a per-peer tunnel inbox and return a disposable async iterable
+     * of {@link StoredMessage} values received from that peer over the tunnel
+     * (i.e. direct hub messages with no `groupID`).
+     *
+     * Used by the hub-mediated document sync server adapter (see Q3 of the
+     * hub-mediated document sync plan). The hub's receive-side dispatcher
+     * keys tunnel routing on `senderDID` because hub-level messages cannot
+     * reveal the in-frame `sessionID` (the body is encrypted). P2P pairs
+     * `peerDID` and `sessionID` at session creation, so peer-keying is
+     * sufficient. Concurrent tunnel sessions to the same peer are not
+     * supported and are the caller's responsibility to avoid.
+     */
+    tunnelMessageStream({ peerDID }: TunnelMessageStreamParams): TunnelMessageStream;
+    close(): Promise<void>;
+}
+export {};

package/lib/hub/hub-connection.js

@@ -0,0 +1 @@
+import{Disposer as e}from"@enkaku/async";import{fromB64 as t,toB64 as s}from"@enkaku/codec";import{EventEmitter as n}from"@enkaku/event";import{createMutex as i}from"../util/mutex.js";import{ReconnectingError as r}from"./errors.js";import{AckBatch as o,abortableSleep as h,computeBackoff as a}from"./group-channel.js";import{TunnelInbox as c}from"./tunnel-inbox.js";import{waitForGate as l}from"./wait-for-gate.js";let u=Symbol("disposed");export class HubConnection extends e{#e;#t;#s;#n;#i;#r;#o;#h;#a;#c=null;#l=null;#u=null;#b=null;#p=null;#d=new Map;#f=!1;#g=0;#m=null;#y=new Map;#w;constructor(e){super({dispose:async()=>{await this.#L()}}),this.#e=e.hubURL,this.#t=e.deviceID,this.#s=e.pool,this.#n=e.logger,this.#i=e.ackFlushMs??500,this.#r=e.ackFlushMax??10,this.#o=e.backoffBaseMs??1e3,this.#h=e.backoffMaxMs??6e4,this.#a=e.backoffJitter??.25,this.#w=new n}get events(){return this.#w}async #I(e){try{await this.#w.emit("lifecycle",e)}catch(t){this.#n?.warn("hub-connection lifecycle subscriber threw",{hubURL:this.#e,type:e.type,error:t})}}async open(){if(this.#f)throw Error("HubConnection already opened");try{await this.#k(),this.#f=!0,await this.#I({type:"connected"})}catch(e){if(null!=this.#l){try{await this.#s.release(this.#e,this.#l)}catch(e){this.#n?.debug("hub-connection pool release after open failure failed",{hubURL:this.#e,error:e})}this.#l=null}throw this.#c=null,e}}async #k(){if(null!=this.#l){let e=this.#l;this.#l=null,this.#c=null;try{await this.#s.release(this.#e,e)}catch(e){this.#n?.debug("hub-connection pool release before reconnect failed",{hubURL:this.#e,error:e})}}let{client:e,refID:t}=await this.#s.acquire(this.#e);this.#c=e,this.#l=t;let s=e.createChannel("hub/receive",{param:{},signal:this.signal});this.#u=s,s.catch(()=>{}),this.#b=new o({flushMs:this.#i,flushMax:this.#r,send:async e=>{await s.send({ack:e})},logger:this.#n}),this.#p=this.#R(e).catch(e=>{this.#n?.debug("hub-connection receive task tail error",{hubURL:this.#e,error:e})});let n=[...this.#d.entries()];if(n.length>0){let t=await Promise.allSettled(n.map(async([t,s])=>{await e.request("hub/group/join",{param:{groupID:t,credential:s.credential}})}));for(let e=0;e<t.length;e++){let s=t[e];if("rejected"===s.status){let t=n[e][0];this.#n?.warn("hub-connection rejoin failed",{hubURL:this.#e,groupID:t,error:s.reason})}}}}async subscribe(e,t,s){if(await l(this.#m,void 0),!this.#f||null==this.#c)throw Error("HubConnection not open");if(this.#d.has(e))throw Error(`already subscribed to group ${e}`);await this.#c.request("hub/group/join",{param:{groupID:e,credential:t}}),this.#d.set(e,{credential:t,handler:s,mutex:i()})}async unsubscribe(e){await l(this.#m,void 0);let t=this.#c;if(!this.#f||null==t)throw Error("HubConnection not open");let s=this.#d.get(e);if(null==s)throw Error(`not subscribed to group ${e}`);await s.mutex.run(async()=>{}),await t.request("hub/group/leave",{param:{groupID:e}}),this.#d.delete(e)}async broadcast(e,t,s){if(await l(this.#m,s?.timeoutMs,()=>new r(this.#e,this.#g)),!this.#f||null==this.#c)throw Error("HubConnection not open");await this.#c.request("hub/group/send",{param:{groupID:e,payload:t}})}async send(e){if(await l(this.#m,e.timeoutMs,()=>new r(this.#e,this.#g)),!this.#f||null==this.#c)throw Error("HubConnection not open");return{sequenceID:(await this.#c.request("hub/send",{param:{recipients:e.recipients,payload:s(e.payload)}})).sequenceID}}async runInGroup(e,t,s){if(await l(this.#m,s?.timeoutMs,()=>new r(this.#e,this.#g)),!this.#f)throw Error("HubConnection not open");let n=this.#d.get(e);if(null==n)throw Error(`not subscribed to group ${e}`);return n.mutex.run(t)}tunnelMessageStream({peerDID:e}){if(this.#y.has(e))throw Error("tunnelMessageStream: peerDID already registered");let t=new c,s={inbox:t};this.#y.set(e,s);let n=!1;return{[Symbol.asyncIterator]:()=>t.iterator(),return:()=>{n||(n=!0,this.#y.get(e)===s&&this.#y.delete(e),t.close())}}}async #R(e){let t=this.#u;if(null==t)return;let s=t.readable.getReader(),n=null;try{for(;!this.signal.aborted;){let t=s.read(),n=e.disposed.then(()=>u),i=await Promise.race([t,n]);if("symbol"==typeof i){this.#n?.debug("hub-connection receive loop observed hub client disposal",{hubURL:this.#e});break}let{done:r,value:o}=i;if(r)break;this.#D(o),this.#g=0}}catch(e){n=e,this.#n?.warn("hub-connection receive loop error",{hubURL:this.#e,error:e})}finally{try{s.releaseLock()}catch{}}if(!this.signal.aborted){let e=n instanceof Error&&n.message?n.message:"receive loop ended";await this.#I({type:"disconnected",reason:e}),this.#U()}}#U(){this.#p=this.#M().catch(e=>{this.#n?.debug("hub-connection reconnect task tail error",{hubURL:this.#e,error:e})})}async #M(){let e=()=>{};this.#m=new Promise(t=>{e=t});try{for(;!this.signal.aborted;){let e=a(this.#g++,this.#o,this.#h,this.#a);this.#n?.debug("hub-connection reconnect scheduled",{hubURL:this.#e,delay:e,attempt:this.#g});try{await h(e,this.signal)}catch{return}await this.#I({type:"reconnecting",attempt:this.#g,delayMs:e});try{this.#b?.dispose(),this.#b=null,this.#u=null,await this.#k(),this.#g=0,await this.#I({type:"connected"});return}catch(e){this.#n?.warn("hub-connection reconnect attempt failed",{hubURL:this.#e,attempt:this.#g,error:e}),await this.#I({type:"error",error:e})}}}finally{this.#m=null,e()}}#D(e){if(null==e.groupID){let s=this.#y.get(e.senderDID);if(null!=s){let n={sequenceID:e.sequenceID,senderDID:e.senderDID,payload:t(e.payload)};s.inbox.push(n),this.#b?.add(e.sequenceID);return}this.#n?.debug("direct message received, no handler",{hubURL:this.#e,sequenceID:e.sequenceID}),this.#b?.add(e.sequenceID);return}let s=this.#d.get(e.groupID);null==s?this.#n?.debug("message for unsubscribed group",{hubURL:this.#e,groupID:e.groupID,sequenceID:e.sequenceID}):s.mutex.run(()=>s.handler(e)).then(t=>{t.ack&&this.#b?.add(e.sequenceID)}).catch(t=>{this.#n?.warn("hub-connection subscription handler error",{hubURL:this.#e,groupID:e.groupID,sequenceID:e.sequenceID,error:t})})}async close(){this.#f&&await this.dispose()}async #L(){if(!this.#f)return;let e=this.#b;if(this.#b=null,null!=e){try{await e.flush()}catch(e){this.#n?.debug("hub-connection ack flush during close failed",{hubURL:this.#e,error:e})}e.dispose()}try{this.#u?.close()}catch{}try{await this.#p}catch{}let t=[...this.#d.values()].map(e=>e.mutex.run(async()=>{}).catch(()=>{}));if(await Promise.allSettled(t),null!=this.#l){try{await this.#s.release(this.#e,this.#l)}catch(e){this.#n?.debug("hub-connection pool release during close failed",{hubURL:this.#e,error:e})}this.#l=null}for(let e of(this.#c=null,this.#u=null,this.#p=null,this.#d.clear(),this.#y.values()))e.inbox.close();this.#y.clear(),this.#f=!1}}

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,CommitOutOfOrderError as c,DecryptError as s}from"../groups/broadcast-service.js";export async function handleReceivedMessage(a){let{groupID:n,message:o,broadcastService:i,logger:t}=a;if(o.groupID!==n)return t?.debug("hub message groupID mismatch, skipping",{groupID:n,messageGroupID:o.groupID,sequenceID:o.sequenceID}),{ack:!1};let u=e(o.payload);try{await i.processReceived({groupID:n,encrypted:u})}catch(e){if(e instanceof s)return t?.debug("decrypt failed, acking and skipping",{groupID:n,sequenceID:o.sequenceID,error:e}),{ack:!0};if(e instanceof c)return t?.debug("mls commit out of order, will redeliver after gap fills",{groupID:n,sequenceID:o.sequenceID,messageEpoch:e.messageEpoch.toString(),handleEpoch:e.handleEpoch.toString()}),{ack:!1};if(e instanceof r)return t?.error("broadcast apply failed, will redeliver",{groupID:n,sequenceID:o.sequenceID,error:e}),{ack:!1};return t?.error("unexpected error processing hub message",{groupID:n,sequenceID:o.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,33 @@ 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>;
+    /**
+     * Fan out a pre-produced MLS handshake Commit to a group's existing members
+     * via its active channel. Mirrors {@link broadcast}.
+     */
+    sendCommit(groupID: string, commitBytes: Uint8Array, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
     stop(): Promise<void>;
 }
+export {};