@kubun/plugin-p2p 0.9.0 → 0.10.1

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

@@ -1,9 +1,13 @@
 import { Disposer } from '@enkaku/async';
+import type { OwnIdentity } from '@enkaku/token';
 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 { GroupHealthMonitor } from '../groups/group-health-monitor.js';
+import type { RejoinResult } from '../types.js';
 import type { HubConnection } from './hub-connection.js';
+import { RejoinManager } from './rejoin-manager.js';
 export type AckBatchParams = {
     flushMs: number;
     flushMax: number;
@@ -32,6 +36,19 @@ export type GroupChannelParams = {
     broadcastService: BroadcastService;
     p2pStore: P2PStoreAPI;
     logger?: Logger;
+    /** When provided, receive outcomes feed epoch-stale health detection and the
+     *  rejoin flow becomes available (both need the shared health monitor). */
+    monitor?: GroupHealthMonitor;
+    /** Device identity — required by `joinGroupExternal` in the rejoin flow. */
+    identity?: OwnIdentity;
+    /** Fresh correlation ids for rejoin requests. */
+    getRandomID?: () => string;
+    /**
+     * Pre-built rejoin manager, overriding the one this channel would construct
+     * from `monitor`/`identity`/`getRandomID`. Lets the rejoin orchestration be
+     * driven without standing up real MLS; production callers leave it unset.
+     */
+    rejoinManager?: RejoinManager;
 };
 /**
  * Per-group handle: thin wrapper around a shared `HubConnection`.
@@ -52,8 +69,21 @@ export declare class GroupChannel extends Disposer {
     #private;
     constructor(params: GroupChannelParams);
     open(): Promise<void>;
+    /**
+     * Run stale-device recovery for this group. Available only when constructed
+     * with a health monitor + identity; returns `recovery-failed` otherwise.
+     */
+    rejoinGroup(): Promise<RejoinResult>;
     close(): 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{Disposer as e}from"@enkaku/async";import{handleReceivedMessage as t}from"./receive-handler.js";import{handleSendBroadcast as r}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;#l=!1;constructor(e){super({dispose:async()=>{await this.#d()}}),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.#l)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.#l=!0}#p(e){return t({groupID:this.#n,message:e,broadcastService:this.#u,logger:this.#i})}async close(){this.#l&&await this.dispose()}async #d(){if(this.#l){try{await this.#a.unsubscribe(this.#n)}catch(e){this.#i?.warn("hub-connection unsubscribe failed during close",{groupID:this.#n,error:e})}this.#l=!1}}broadcast(e,t){return this.#l?this.#a.runInGroup(this.#n,async()=>{if(!this.#l)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`))}}
+import{Disposer as e}from"@enkaku/async";import{toB64 as r}from"@enkaku/codec";import{CircleCatchupRequester as t}from"./circle-catchup-requester.js";import{CircleCatchupResponder as o}from"./circle-catchup-responder.js";import{EpochStaleDetector as s}from"./epoch-stale-detector.js";import{handleReceivedMessage as i}from"./receive-handler.js";import{RejoinManager as n}from"./rejoin-manager.js";import{RejoinResponder as a}from"./rejoin-responder.js";import{handleSendBroadcast as u,handleSendCommit as h}from"./send-handler.js";export class AckBatch{#e;#r;#t;#o;#s=new Set;#i=null;constructor(e){this.#e=e.flushMs,this.#r=e.flushMax,this.#t=e.send,this.#o=e.logger}add(e){let r=0===this.#s.size;if(this.#s.add(e),this.#s.size>=this.#r){null!==this.#i&&(clearTimeout(this.#i),this.#i=null),this.flush();return}r&&null===this.#i&&(this.#i=setTimeout(()=>{this.#i=null,this.flush()},this.#e))}async flush(){if(null!==this.#i&&(clearTimeout(this.#i),this.#i=null),0===this.#s.size)return;let e=Array.from(this.#s);this.#s.clear();try{await this.#t(e)}catch(r){this.#o?.error("ack batch send failed",{error:r,count:e.length})}}dispose(){null!==this.#i&&(clearTimeout(this.#i),this.#i=null),this.#s.clear()}}export function computeBackoff(e,r,t,o){let s=Math.min(r*2**e*(1+o*(2*Math.random()-1)),t);return s<0?0:s}export function abortableSleep(e,r){return new Promise((t,o)=>{if(r.aborted)return void o(r.reason??Error("aborted"));let s=setTimeout(()=>{r.removeEventListener("abort",i),t()},e),i=()=>{clearTimeout(s),r.removeEventListener("abort",i),o(r.reason??Error("aborted"))};r.addEventListener("abort",i)})}export class GroupChannel extends e{#n;#a;#u;#h;#p;#o;#c;#d;#l;#g;#m;#I=!1;constructor(e){super({dispose:async()=>{await this.#f()}}),this.#n=e.groupID,this.#a=e.deviceID,this.#u=e.hubConnection,this.#h=e.broadcastService,this.#p=e.p2pStore,this.#o=e.logger,null!=e.monitor&&(this.#c=new s({groupID:e.groupID,monitor:e.monitor})),this.#d=new a({groupID:e.groupID,exportGroupInfo:()=>this.#h.exportGroupInfo(this.#n),sendGroupInfo:(e,r)=>this.#D(e,r),logger:e.logger}),null!=e.rejoinManager?this.#l=e.rejoinManager:null!=e.monitor&&null!=e.identity&&null!=e.getRandomID&&(this.#l=new n({groupID:e.groupID,identity:e.identity,readCredential:()=>this.#h.readCredential(this.#n),genRequestID:e.getRandomID,sendRequest:e=>this.#b(e),sendCommit:e=>this.sendCommit(e),replaceHandle:e=>this.#h.replaceHandle(this.#n,e),monitor:e.monitor,logger:e.logger})),this.#g=new o({groupID:e.groupID,store:this.#p,sendCatchupReply:(e,r,t)=>this.#y(e,r,t),logger:e.logger}),null!=e.getRandomID&&(this.#m=new t({groupID:e.groupID,genRequestID:e.getRandomID,sendRequest:e=>this.#R(e),applyReply:async e=>{await this.#u.runInGroup(this.#n,()=>this.#h.applyCatchupReply(this.#n,e))},logger:e.logger}))}async open(){if(this.#I)throw Error("GroupChannel already opened");let e=await this.#p.getMLSState(this.#n,this.#a);if(null==e)throw Error(`MLS state missing for group ${this.#n}; cannot join hub group`);await this.#u.subscribe(this.#n,e.credential,e=>this.#j(e)),this.#I=!0}async #j(e){let r=await i({groupID:this.#n,message:e,broadcastService:this.#h,logger:this.#o});this.#c?.onReceiveOutcome(r.outcome,r.sequenceID);let t=r.result;if(t?.kind==="rejoin-request")this.#d.onRejoinRequest(t.requestID);else if(t?.kind==="rejoin-groupinfo")this.#d.onRejoinGroupInfoSeen(t.requestID),this.#l?.onGroupInfo(t.requestID,t.groupInfo);else if(t?.kind==="app"){let e=t.message;"circle-catchup:request"===e.type?this.#g.onCatchupRequest(e.requestID):"circle-catchup:reply"===e.type&&(this.#g.onCatchupReplySeen(e.requestID),this.#m?.onCatchupReply(e.requestID,e))}return{ack:r.ack}}async rejoinGroup(){if(null==this.#l)return{status:"recovery-failed"};let e=await this.#l.rejoin();return"recovered"===e.status&&null!=this.#m&&this.#m.run().catch(e=>{this.#o?.warn("circle catch-up after rejoin failed",{groupID:this.#n,error:e})}),e}#b(e){return this.#I?this.#h.prepareSendRejoinRequest({requestID:e,send:e=>this.#u.broadcast(this.#n,r(e))}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for rejoin request`))}#D(e,t){return this.#I?this.#h.prepareSendRejoinGroupInfo({requestID:e,groupInfo:t,send:e=>this.#u.broadcast(this.#n,r(e))}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for rejoin reply`))}#R(e){return this.#I?this.#h.prepareSend({groupID:this.#n,message:{type:"circle-catchup:request",requestID:e},send:e=>this.#u.broadcast(this.#n,r(e))}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for catch-up request`))}#y(e,t,o){return this.#I?this.#h.prepareSend({groupID:this.#n,message:{type:"circle-catchup:reply",requestID:e,circles:t,circleMembers:o},send:e=>this.#u.broadcast(this.#n,r(e))}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for catch-up reply`))}async close(){this.#I&&await this.dispose()}async #f(){if(this.#d.dispose(),this.#l?.dispose(),this.#g.dispose(),this.#m?.dispose(),this.#I){try{await this.#u.unsubscribe(this.#n)}catch(e){this.#o?.warn("hub-connection unsubscribe failed during close",{groupID:this.#n,error:e})}this.#I=!1}}broadcast(e,r){return this.#I?this.#u.runInGroup(this.#n,async()=>{if(!this.#I)throw Error(`GroupChannel for ${this.#n} is not ready for broadcast`);await u({groupID:this.#n,message:e,broadcastService:this.#h,send:(e,t)=>this.#u.broadcast(e,t,{timeoutMs:r?.timeoutMs}),logger:this.#o})},{timeoutMs:r?.timeoutMs}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for broadcast`))}sendCommit(e,r){return this.#I?this.#u.runInGroup(this.#n,async()=>{if(!this.#I)throw Error(`GroupChannel for ${this.#n} is not ready for sendCommit`);await h({groupID:this.#n,commitBytes:e,broadcastService:this.#h,send:(e,t)=>this.#u.broadcast(e,t,{timeoutMs:r?.timeoutMs}),logger:this.#o})},{timeoutMs:r?.timeoutMs}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for sendCommit`))}}

package/lib/hub/hub-connection.js

@@ -1 +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;#w=new Map;#y;constructor(e){super({dispose:async()=>{await this.#I()}}),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.#y=new n}get events(){return this.#y}async #D(e){try{await this.#y.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.#L(),this.#f=!0,await this.#D({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 #L(){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,isAllowedSender:t,onRejected:s}){if(this.#w.has(e))throw Error("tunnelMessageStream: peerDID already registered");let n=new c,i={inbox:n,isAllowedSender:t??(()=>!0),onRejected:s};this.#w.set(e,i);let r=!1;return{[Symbol.asyncIterator]:()=>n.iterator(),return:()=>{r||(r=!0,this.#w.get(e)===i&&this.#w.delete(e),n.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.#k(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.#D({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.#D({type:"reconnecting",attempt:this.#g,delayMs:e});try{this.#b?.dispose(),this.#b=null,this.#u=null,await this.#L(),this.#g=0,await this.#D({type:"connected"});return}catch(e){this.#n?.warn("hub-connection reconnect attempt failed",{hubURL:this.#e,attempt:this.#g,error:e}),await this.#D({type:"error",error:e})}}}finally{this.#m=null,e()}}#k(e){if(null==e.groupID){let s=this.#w.get(e.senderDID);if(null!=s){if(!s.isAllowedSender(e.senderDID)){this.#n?.debug("tunnel frame rejected: sender not member",{hubURL:this.#e,sequenceID:e.sequenceID,senderDID:e.senderDID});try{s.onRejected?.("sender-not-member",e.senderDID)}catch(t){this.#n?.warn("tunnel onRejected callback threw",{hubURL:this.#e,senderDID:e.senderDID,error:t})}this.#b?.add(e.sequenceID);return}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 #I(){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.#w.values()))e.inbox.close();this.#w.clear(),this.#f=!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

@@ -65,16 +65,17 @@ export type UpsertHubParams = {
     serverDID?: string | null;
 };
 export declare class HubServerDIDConflictError extends Error {
-    readonly hubID: string;
-    readonly url: string;
-    readonly existingServerDID: string;
-    readonly providedServerDID: string;
+    #private;
     constructor(params: {
         hubID: string;
         url: string;
         existingServerDID: string;
         providedServerDID: string;
     });
+    get hubID(): string;
+    get url(): string;
+    get existingServerDID(): string;
+    get providedServerDID(): string;
 }
 export declare function createHub(params: CreateHubParams): Promise<Hub>;
 /**

package/lib/hub/manager.js

@@ -1 +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})}
+import{getP2PStore as r}from"@kubun/store-p2p";export class HubServerDIDConflictError extends Error{#r;#e;#t;#u;constructor(r){super(`hub at ${r.url} is pinned to ${r.existingServerDID}; refusing to overwrite with ${r.providedServerDID}`),this.name="HubServerDIDConflictError",this.#r=r.hubID,this.#e=r.url,this.#t=r.existingServerDID,this.#u=r.providedServerDID}get hubID(){return this.#r}get url(){return this.#e}get existingServerDID(){return this.#t}get providedServerDID(){return this.#u}}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,5 @@
 import type { Logger } from '@kubun/logger';
-import { type BroadcastService } from '../groups/broadcast-service.js';
+import { type BroadcastService, type ReceiveBroadcastResult } from '../groups/broadcast-service.js';
 /**
  * Shape of a message pushed by `hub/receive`. Matches `@enkaku/hub-protocol`
  * server-to-client push payload.
@@ -17,8 +17,26 @@ export type HandleReceivedMessageParams = {
     broadcastService: BroadcastService;
     logger?: Logger;
 };
+/**
+ * Classification of a single received message's processing result. Drives both
+ * the ack decision and the epoch-stale health signal (see `EpochStaleDetector`):
+ * - `applied` — decrypted/applied cleanly; the device is at the current epoch.
+ * - `decrypt-failed` — could not derive the key for the current epoch.
+ * - `commit-out-of-order` — a Commit ahead of the local epoch (gap in stream).
+ * - `apply-failed` — decrypted but failed to apply to the local DB (transient).
+ * - `error` — unexpected failure.
+ * - `skipped` — not for this group; no processing attempted.
+ * - `control` — a rejoin control frame (request/groupinfo); processed cleanly
+ *   but NOT a health indicator (must not reset epoch-stale tracking).
+ */
+export type ReceiveOutcome = 'applied' | 'decrypt-failed' | 'commit-out-of-order' | 'apply-failed' | 'error' | 'skipped' | 'control';
 export type HandleReceivedMessageResult = {
     ack: boolean;
+    outcome: ReceiveOutcome;
+    sequenceID: string;
+    /** The processed result, present on success — lets the channel route rejoin
+     *  control frames to the responder/requester. */
+    result?: ReceiveBroadcastResult;
 };
 /**
  * Apply a single hub-received message for a group.
@@ -28,6 +46,6 @@ export type HandleReceivedMessageResult = {
  * no recovery path). Returns `{ ack: false }` when the hub should redeliver
  * (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.
+ * was intended for. The `outcome` classifies the result for health tracking.
  */
 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 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}}
+import{fromB64 as e}from"@enkaku/codec";import{ApplyError as r,CommitOutOfOrderError as o,DecryptError as a,MalformedControlError as c}from"../groups/broadcast-service.js";export async function handleReceivedMessage(i){let t,{groupID:n,message:s,broadcastService:p,logger:u}=i,d=s.sequenceID;if(s.groupID!==n)return u?.debug("hub message groupID mismatch, skipping",{groupID:n,messageGroupID:s.groupID,sequenceID:d}),{ack:!1,outcome:"skipped",sequenceID:d};let l=e(s.payload);try{t=await p.processReceived({groupID:n,encrypted:l})}catch(e){if(e instanceof c)return u?.debug("malformed control frame, acking and skipping",{groupID:n,sequenceID:d,error:e}),{ack:!0,outcome:"control",sequenceID:d};if(e instanceof a)return u?.debug("decrypt failed, acking and skipping",{groupID:n,sequenceID:d,error:e}),{ack:!0,outcome:"decrypt-failed",sequenceID:d};if(e instanceof o)return u?.debug("mls commit out of order, will redeliver after gap fills",{groupID:n,sequenceID:d,messageEpoch:e.messageEpoch.toString(),handleEpoch:e.handleEpoch.toString()}),{ack:!1,outcome:"commit-out-of-order",sequenceID:d};if(e instanceof r)return u?.error("broadcast apply failed, will redeliver",{groupID:n,sequenceID:d,error:e}),{ack:!1,outcome:"apply-failed",sequenceID:d};return u?.error("unexpected error processing hub message",{groupID:n,sequenceID:d,error:e}),{ack:!1,outcome:"error",sequenceID:d}}return{ack:!0,outcome:"rejoin-request"===t.kind||"rejoin-groupinfo"===t.kind?"control":"applied",sequenceID:d,result:t}}

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

@@ -0,0 +1,78 @@
+import { type GroupHandle, type MemberCredential } from '@enkaku/group';
+import type { OwnIdentity } from '@enkaku/token';
+import type { Logger } from '@kubun/logger';
+import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
+import type { RejoinResult } from '../types.js';
+export type JoinExternalResult = {
+    /** Framed MLSMessage(Commit) bytes to broadcast to existing members. */
+    commitMessage: Uint8Array;
+    /** Optimistic post-commit handle (NOT yet persisted). */
+    pendingHandle: GroupHandle;
+};
+export type RejoinManagerParams = {
+    groupID: string;
+    identity: OwnIdentity;
+    /** Read the stale handle's cached MemberCredential (reused for the rejoin). */
+    readCredential: () => Promise<MemberCredential>;
+    /** Fresh correlation id per request (incl. retries). */
+    genRequestID: () => string;
+    /** Broadcast a `rejoin-request` on the group channel. */
+    sendRequest: (requestID: string) => Promise<void>;
+    /** Broadcast the resync Commit (`mls` frame) to existing members. */
+    sendCommit: (commitBytes: Uint8Array) => Promise<void>;
+    /** Atomically swap the cached handle for the confirmed one (registry). */
+    replaceHandle: (handle: GroupHandle) => Promise<void>;
+    monitor: GroupHealthMonitor;
+    /**
+     * Test seam: defaults to `@enkaku/group` `joinGroupExternal({resync:true})`
+     * built from `identity` + `readCredential`. Override to skip real MLS.
+     */
+    joinExternal?: (groupInfo: Uint8Array) => Promise<JoinExternalResult>;
+    /** Test seam: defaults to `@enkaku/group` `inspectGroupInfo`. */
+    inspectGroupInfo?: (groupInfo: Uint8Array) => {
+        epoch: bigint;
+        treeHash: Uint8Array;
+    };
+    requestTimeoutMs?: number;
+    confirmTimeoutMs?: number;
+    /** Delay between the candidate-head probe and its re-probe (settle window). */
+    confirmSettleMs?: number;
+    maxAttempts?: number;
+    backoffMs?: (attempt: number) => number;
+    logger?: Logger;
+};
+/**
+ * Drives a stale device's MLS epoch recovery for one group: per attempt,
+ * request GroupInfo → `joinGroupExternal({resync:true})` → broadcast the resync
+ * Commit → confirm → `replaceHandle`.
+ *
+ * Confirm is a tree-hash compare against the current head, because the hub never
+ * echoes the sender's own Commit. Three guards keep it reliable under concurrent
+ * rejoins (a resync Commit is canonical only for an instant):
+ * - behind-responder filter: a probe reply below our epoch can't confirm us.
+ * - chase-the-head: a reply above our epoch means we lost the race; re-join the
+ *   newer GroupInfo next attempt (`{resync:true}` rebuilds the tree — no replay).
+ * - settle re-probe: re-probe after a delay and require the head still ours
+ *   before swapping. Shrinks (not closes) the transient-head window — a Commit
+ *   landing in the gap leaves us one epoch behind, which detect→rejoin catches.
+ *   A fall-behind, never a silent fork; a wrong `recovered` is unreachable.
+ *
+ * Retries capped; exhaustion → `recovery-failed`.
+ */
+export declare class RejoinManager {
+    #private;
+    constructor(params: RejoinManagerParams);
+    get inFlight(): boolean;
+    /**
+     * Route a received `rejoin-groupinfo`: resolve the matching in-flight waiter.
+     * Unknown `requestID`s (peers' requests, stale responses) are ignored.
+     */
+    onGroupInfo(requestID: string, groupInfo: Uint8Array): void;
+    /** Run the recovery flow. Idempotent: a concurrent call returns the loser early. */
+    rejoin(): Promise<RejoinResult>;
+    /**
+     * Stop a running rejoin and release timers. Idempotent; the loop checks
+     * `#disposed` between attempts, pending waiters resolve `null`. On channel close.
+     */
+    dispose(): void;
+}

package/lib/hub/rejoin-manager.js

@@ -0,0 +1 @@
+import{inspectGroupInfo as e,joinGroupExternal as t}from"@enkaku/group";import{bytesEqual as r,sleep as i,unref as s}from"../utils.js";export class RejoinManager{#e;#t;#r;#i;#s;#o;#n;#a;#l;#u;#h;#c;#p;#m;#d=new Map;#f=!1;#g=!1;constructor(r){this.#e=r.groupID,this.#t=r.genRequestID,this.#r=r.sendRequest,this.#i=r.sendCommit,this.#s=r.replaceHandle,this.#o=r.monitor,this.#n=r.joinExternal??(async e=>{let i=await r.readCredential(),{commitMessage:s,group:o}=await t({identity:r.identity,groupInfo:e,credential:i,resync:!0});return{commitMessage:s,pendingHandle:o}}),this.#a=r.inspectGroupInfo??e,this.#l=r.requestTimeoutMs??5e3,this.#u=r.confirmTimeoutMs??5e3,this.#h=r.confirmSettleMs??300,this.#c=r.maxAttempts??8,this.#p=r.backoffMs??o,this.#m=r.logger}get inFlight(){return this.#f}onGroupInfo(e,t){let r=this.#d.get(e);null!=r&&(this.#d.delete(e),r.resolve(t))}async rejoin(){if(this.#f)return{status:"recovery-failed"};this.#f=!0,this.#o.markRecovering(this.#e);try{for(let e=0;e<this.#c&&!this.#g&&(await i(this.#p(e)),!this.#g);e++){let e=await this.#w();if("recovered"===e)return this.#o.markRecovered(this.#e),{status:"recovered"}}return this.#o.markRecoveryFailed(this.#e),{status:"recovery-failed"}}finally{this.#f=!1}}async #w(){let e,t=await this.#I(this.#l);if(null==t)return"retry";try{e=await this.#n(t)}catch(e){return this.#m?.warn("rejoin: joinGroupExternal failed",{groupID:this.#e,error:e}),"retry"}let{commitMessage:s,pendingHandle:o}=e,n=o.epoch,a=o.treeHash;try{await this.#i(s)}catch(e){return this.#m?.warn("rejoin: resync Commit send failed",{groupID:this.#e,error:e}),"retry"}let l=await this.#y(n);if(null==l||!(l.epoch===n&&r(l.treeHash,a)))return"retry";await i(this.#h);let u=await this.#y(n);return null==u?"retry":u.epoch===n&&r(u.treeHash,a)?(await this.#s(o),"recovered"):"retry"}async #y(e){let t,r=await this.#I(this.#u);if(null==r)return null;try{t=this.#a(r)}catch(e){return this.#m?.warn("rejoin: confirm GroupInfo inspect failed",{groupID:this.#e,error:e}),null}return t.epoch<e?null:t}async #I(e){let t=this.#t(),r=this.#M(t,e);try{await this.#r(t)}catch(e){return this.#D(t),this.#m?.warn("rejoin: request send failed",{groupID:this.#e,error:e}),null}return r}#M(e,t){return new Promise(r=>{let i=setTimeout(()=>{this.#d.delete(e),r(null)},t);s(i),this.#d.set(e,{resolve:e=>{clearTimeout(i),r(e)},cancel:()=>{clearTimeout(i),r(null)}})})}#D(e){this.#d.delete(e)}dispose(){for(let e of(this.#g=!0,this.#d.values()))e.cancel();this.#d.clear()}}function o(e){return Math.floor(Math.random()*Math.min(500*2**(e-1),5e3))}

package/lib/hub/rejoin-responder.d.ts

@@ -0,0 +1,32 @@
+import type { Logger } from '@kubun/logger';
+export type RejoinResponderParams = {
+    groupID: string;
+    /** Produce a fresh GroupInfo for this group (current MLS handle). */
+    exportGroupInfo: () => Promise<Uint8Array>;
+    /** Broadcast a `rejoin-groupinfo` reply to the group channel. */
+    sendGroupInfo: (requestID: string, groupInfo: Uint8Array) => Promise<void>;
+    /** Jitter delay (ms) before replying. Defaults to a random 0..250ms. */
+    nextJitterMs?: () => number;
+    /** How long a `requestID` stays suppressed after being answered. */
+    suppressTTLMs?: number;
+    logger?: Logger;
+};
+/**
+ * Answers `rejoin-request`s with a fresh GroupInfo. Every member could reply, so
+ * jitter (random pre-reply delay) + suppression (cancel on seeing a peer's reply
+ * for the same `requestID`) collapse the storm to ~1 reply. Keyed on `requestID`
+ * (fresh per attempt); suppression entries TTL out to bound memory.
+ *
+ * Suppression collapses only duplicates of one `requestID`, so distinct
+ * `requestID`s still draw one reply each — an amplification. A per-window reply
+ * cap is tracked in `docs/agents/plans/backlog/rejoin-frame-authentication.md`.
+ */
+export declare class RejoinResponder {
+    #private;
+    constructor(params: RejoinResponderParams);
+    /** Handle an inbound `rejoin-request`: schedule a jittered, suppressible reply. */
+    onRejoinRequest(requestID: string): void;
+    /** Handle an observed `rejoin-groupinfo` (own or peer's): suppress this request. */
+    onRejoinGroupInfoSeen(requestID: string): void;
+    dispose(): void;
+}

package/lib/hub/rejoin-responder.js

@@ -0,0 +1 @@
+import{unref as e}from"../utils.js";export class RejoinResponder{#e;#s;#t;#r;#p;#o;#i=new Map;#n=new Map;constructor(e){this.#e=e.groupID,this.#s=e.exportGroupInfo,this.#t=e.sendGroupInfo,this.#r=e.nextJitterMs??(()=>Math.floor(250*Math.random())),this.#p=e.suppressTTLMs??5e3,this.#o=e.logger}onRejoinRequest(s){if(this.#n.has(s)||this.#i.has(s))return;let t=setTimeout(()=>{this.#i.delete(s),this.#u(s)},this.#r());e(t),this.#i.set(s,t)}onRejoinGroupInfoSeen(e){let s=this.#i.get(e);null!=s&&(clearTimeout(s),this.#i.delete(e)),this.#h(e)}dispose(){for(let e of this.#i.values())clearTimeout(e);for(let e of(this.#i.clear(),this.#n.values()))clearTimeout(e);this.#n.clear()}async #u(e){if(!this.#n.has(e)){this.#h(e);try{let s=await this.#s();await this.#t(e,s)}catch(s){this.#o?.warn("rejoin responder failed to reply",{groupID:this.#e,requestID:e,error:s})}}}#h(s){let t=this.#n.get(s);null!=t&&clearTimeout(t);let r=setTimeout(()=>{this.#n.delete(s)},this.#p);e(r),this.#n.set(s,r)}}

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

@@ -1,10 +1,13 @@
 import type { Client } from '@enkaku/client';
 import { EventEmitter } from '@enkaku/event';
 import type { HubProtocol } from '@enkaku/hub-protocol';
+import type { OwnIdentity } from '@enkaku/token';
 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 { GroupHealthMonitor } from '../groups/group-health-monitor.js';
+import type { RejoinResult } from '../types.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';
@@ -72,6 +75,12 @@ export type HubRelayManagerParams = {
     backoffMaxMs?: number;
     backoffJitter?: number;
     broadcastTimeoutMs?: number;
+    /** When provided, receive outcomes drive epoch-stale health detection. */
+    monitor?: GroupHealthMonitor;
+    /** Device identity — enables the rejoin flow (needs `joinGroupExternal`). */
+    identity?: OwnIdentity;
+    /** Fresh correlation ids for rejoin requests. */
+    getRandomID?: () => string;
     createGroupChannel?: CreateGroupChannel;
     createHubConnection?: CreateHubConnection;
     /**
@@ -85,7 +94,7 @@ export type HubRelayManagerParams = {
 };
 export declare class HubRelayManager {
     #private;
-    readonly relayEvents: EventEmitter<RelayManagerEvents>;
+    get relayEvents(): EventEmitter<RelayManagerEvents>;
     constructor(params: HubRelayManagerParams);
     /**
      * Open channels for each group in parallel. Per-group failures are logged
@@ -112,9 +121,22 @@ export declare class HubRelayManager {
      */
     removeBinding(groupID: string, hubURL: string): Promise<void>;
     removeGroup(groupID: string): Promise<void>;
+    /**
+     * Run stale-device MLS epoch recovery for an active group via its channel.
+     * Throws if the group is not active; returns `recovery-failed` if the rejoin
+     * flow is unavailable (no monitor/identity wired).
+     */
+    rejoinGroup(groupID: string): Promise<RejoinResult>;
     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 {};

package/lib/hub/relay-manager.js

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

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

@@ -22,3 +22,19 @@ export type HandleSendBroadcastParams = {
  * runs INSIDE the registry's per-group lock and a throw skips persist.
  */
 export declare function handleSendBroadcast(params: HandleSendBroadcastParams): Promise<void>;
+export type HandleSendCommitParams = {
+    groupID: string;
+    /** Framed MLSMessage(Commit) bytes from the committer's `GroupManager` call. */
+    commitBytes: Uint8Array;
+    broadcastService: BroadcastService;
+    /** Same wire-send callback as {@link HandleSendBroadcastParams.send}. */
+    send: (groupID: string, payloadB64: string) => Promise<void>;
+    logger?: Logger;
+};
+/**
+ * Fan out a pre-produced MLS handshake Commit to a group's existing members.
+ * Unlike {@link handleSendBroadcast} this does not encrypt — the Commit is
+ * already a self-protected `PrivateMessage`; `prepareSendCommit` just tags it
+ * `mls` on the wire.
+ */
+export declare function handleSendCommit(params: HandleSendCommitParams): Promise<void>;

package/lib/hub/send-handler.js

@@ -1 +1 @@
-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}}
+import{toB64 as r}from"@enkaku/codec";export async function handleSendBroadcast(e){let{groupID:o,message:t,broadcastService:a,send:n,logger:d}=e;try{await a.prepareSend({groupID:o,message:t,send:e=>n(o,r(e))})}catch(r){throw d?.error("hub/group/send failed",{groupID:o,error:r}),r}}export async function handleSendCommit(e){let{groupID:o,commitBytes:t,broadcastService:a,send:n,logger:d}=e;try{await a.prepareSendCommit({groupID:o,commitBytes:t,send:e=>n(o,r(e))})}catch(r){throw d?.error("hub/group/send (mls commit) failed",{groupID:o,error:r}),r}}

package/lib/hub/wiring.d.ts

@@ -1,13 +1,15 @@
 import type { OwnIdentity } from '@enkaku/token';
 import type { KubunDB } from '@kubun/db';
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
+import type { HLC } from '@kubun/hlc';
 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 { P2PEventEmitter } from '../groups/events.js';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
 import type { ForwardingConfig } from '../sync/forwarder.js';
-import type { StoreUnreadableMode } from '../types.js';
+import type { RejoinResult, 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';
@@ -15,10 +17,30 @@ import { type CreateHubClient } from './relay-manager.js';
 export type HubWiring = {
     ready: Promise<void>;
     scheduleBroadcast: (groupID: string, message: GroupBroadcastMessage) => void;
+    /**
+     * Awaitable broadcast — resolves only after the message is encrypted + sent.
+     * Use when ordering matters relative to a subsequent local op (e.g. a
+     * leave-request that must be encrypted with the still-live MLS handle before
+     * `leaveGroup` tears it down). Rejects on send failure.
+     */
+    broadcastNow: (groupID: string, message: GroupBroadcastMessage) => Promise<void>;
+    /**
+     * Fire-and-forget fan-out of a pre-produced MLS handshake Commit to a
+     * group's existing members. Wired to `HubRelayManager.sendCommit`.
+     */
+    scheduleSendCommit: (groupID: string, commitBytes: Uint8Array) => void;
+    /**
+     * Run stale-device MLS epoch recovery for an active group. Wired to
+     * `HubRelayManager.rejoinGroup`; a no-op `recovery-failed` under
+     * `DISABLED_HUB` (no relay, nothing to rejoin).
+     */
+    rejoinGroup: (groupID: string) => Promise<RejoinResult>;
     dispose: () => Promise<void>;
 };
 export type SetupHubRelayParams = {
     identity: OwnIdentity;
+    /** Fresh correlation ids for the rejoin flow. */
+    getRandomID: () => string;
     db: KubunDB;
     /**
      * Engine graph internals — threaded through to `BroadcastService` so the
@@ -26,7 +48,7 @@ export type SetupHubRelayParams = {
      * through the engine with `origin: 'peer'`.
      */
     graph: GraphInternals;
-    emitter: GroupEventEmitter;
+    emitter: P2PEventEmitter;
     createHubClient: CreateHubClient;
     onRemoteBroadcast: (event: BroadcastEvent) => void;
     /**
@@ -35,6 +57,8 @@ export type SetupHubRelayParams = {
      * mutex once Phase 3 lands. Currently stored but unused.
      */
     registry: GroupHandleRegistry;
+    /** Shared health monitor; receive outcomes drive epoch-stale detection. */
+    monitor?: GroupHealthMonitor;
     logger: Logger;
     /**
      * Optional testing seam forwarded to `HubRelayManager`. Production code
@@ -68,6 +92,12 @@ export type SetupHubRelayParams = {
      * pinning; omitting it skips capture entirely.
      */
     onServerDIDObserved?: OnServerDIDObserved;
+    /**
+     * Device-wide monotonic clock forwarded to `BroadcastService` for stamping
+     * `removed_at_hlc` on roster reconciliation. Required: production passes the
+     * engine's single instance so roster writes share the device's one clock.
+     */
+    hlc: HLC;
 };
 export declare function setupHubRelay(params: SetupHubRelayParams): HubWiring;
 export declare const DISABLED_HUB: HubWiring;

package/lib/hub/wiring.js

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

package/lib/index.d.ts

@@ -8,7 +8,7 @@ export type { ContextDeps, PendingJoinRequest } from './context/types.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, } from './groups/broadcast-service.js';
-export { createFilteredGenerator, createGroupEventEmitter, type GroupEventEmitter, type GroupEventMap, } from './groups/events.js';
+export { createFilteredGenerator, createP2PEventEmitter, type P2PEventEmitter, type P2PEventMap, } from './groups/events.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';
@@ -20,13 +20,13 @@ export type { SyncClientMessage, SyncProtocol, SyncServerMessage } from './proto
 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 { SyncAccessDeniedError } from './sync/errors.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 { checkSyncDelegation } 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 { negotiateDirection, 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';
@@ -58,7 +58,21 @@ export type ReceiveConfig = {
 export declare const DEFAULT_RECEIVE_CONFIG: ReceiveConfig;
 export type P2PPluginOptions = {
     autoAcceptPeers?: Array<string>;
-    http?: boolean | string;
+    /**
+     * Expose the sync protocol over the HTTP plugin transport.
+     * - `true` / `{}` — enable at the default protocol path `'sync'` with CORS
+     *   open to all origins (`['*']`).
+     * - `'name'` / `'/name'` — enable at the given protocol path.
+     * - `{ path?, allowedOrigin? }` — `path` is the protocol path (default
+     *   `'sync'`); `allowedOrigin` restricts CORS origins (default `['*']`).
+     *   The default is open because the sync server authenticates every request,
+     *   so CORS is not the security boundary; operators may still restrict it.
+     * - absent / `false` — HTTP sync transport disabled.
+     */
+    http?: boolean | string | {
+        path?: string;
+        allowedOrigin?: string | Array<string>;
+    };
     /**
      * Enable hub-mediated group broadcasts.
      * - `true` / `{}` — build a default HTTP hub client factory from