@kubun/plugin-p2p 0.10.1 → 0.11.0

package/lib/groups/store-received-grant.js

@@ -1 +1,116 @@
-import{verifyToken as e}from"@enkaku/token";export async function storeReceivedGrant(i){let t,{p2pStore:a,token:n,groupID:r,hlc:o,selfDID:d,emitter:p,logger:s}=i;try{t=(await e(n)).payload}catch(e){return s?.warn("received grant token verification failed, skipping",{groupID:r,error:e}),!1}if(t.aud!==d)return!1;if(null==t.jti||null==t.exp)return s?.warn("received grant token missing jti/exp, skipping",{groupID:r}),!1;let u="string"==typeof t.res?t.res:JSON.stringify(t.res),c="string"==typeof t.act?t.act:JSON.stringify(t.act),g=await a.addDelegationToken({jti:t.jti,grantor:t.sub,audience:t.aud,token:n,resource:u,act:c,exp:t.exp,group_id:r,hlc:o});if(g){let e=await a.getPendingRevocationByJti(t.jti);if(null!=e)if(e.revoker_did===t.sub){let i=Math.floor(Date.now()/1e3);await a.markRevocationVerified(t.jti,{cap_exp:t.exp,verified_at:i})&&null!=p&&await p.emit("delegationTokenRevoked",{jti:t.jti,grantor:t.sub,audience:t.aud,revokerDID:e.revoker_did,revokedAt:e.revoked_iat,verifiedAt:i,capExp:t.exp,groupID:r})}else s?.warn("pending revocation iss does not match arriving cap, dropping",{jti:t.jti,pendingIss:e.revoker_did,capGrantor:t.sub,groupID:r}),await a.deletePendingRevocation(t.jti)}return g&&null!=p&&await p.emit("delegationTokenAdded",{jwt:n,jti:t.jti,grantor:t.sub,audience:t.aud,resource:u,exp:t.exp}),g}
+import { verifyToken } from '@kokuin/token';
+/**
+ * Verify a received capability grant and, when it is addressed to this device,
+ * store it as a held row so the engine's auto-attach can reuse it on later
+ * mutations.
+ *
+ * Returns `true` when the held row was inserted or materially changed (LWW
+ * upsert with a newer hlc and at least one differing content field). Returns
+ * `false` when no row change occurred — verification failure, audience
+ * mismatch, missing required claims, LWW lost against an existing row, or an
+ * idempotent re-broadcast with identical content. Never throws on a forged or
+ * malformed token — it is skipped like an unverifiable broadcast entry.
+ *
+ * Shared by the `delegation:share` broadcast path and the invite-bootstrap
+ * path so both apply identical verify + audience + null-guard + coercion logic.
+ */ export async function storeReceivedGrant(params) {
+    const { delegationStore, p2pStore, token, groupID, hlc, selfDID, emitter, logger } = params;
+    // Verify the token's signature before trusting any of its claims. A forged
+    // or tampered token throws here; skip it — no row stored, no throw.
+    let payload;
+    try {
+        const verified = await verifyToken(token);
+        payload = verified.payload;
+    } catch (error) {
+        logger?.warn('received grant token verification failed, skipping', {
+            groupID,
+            error
+        });
+        return false;
+    }
+    // Only store grants addressed to this device.
+    if (payload.aud !== selfDID) {
+        return false;
+    }
+    if (payload.jti == null || payload.exp == null) {
+        logger?.warn('received grant token missing jti/exp, skipping', {
+            groupID
+        });
+        return false;
+    }
+    const resource = typeof payload.res === 'string' ? payload.res : JSON.stringify(payload.res);
+    const act = typeof payload.act === 'string' ? payload.act : JSON.stringify(payload.act);
+    const changed = await delegationStore.addDelegationToken({
+        jti: payload.jti,
+        grantor: payload.sub,
+        audience: payload.aud,
+        token,
+        resource,
+        act,
+        exp: payload.exp,
+        hlc
+    });
+    // Record the group this grant belongs to on the p2p edge so the p2p layer can
+    // resolve the cap's group for revoke-broadcast targeting and listing
+    // enrichment. Keyed by `jti`; idempotent on re-broadcast.
+    await p2pStore.addGroupDelegation({
+        group_id: groupID,
+        jti: payload.jti
+    });
+    // Pending revocations are blind cross-checks: when the matching cap finally
+    // arrives we either promote the revocation to verified (issuer matches) or
+    // drop it as a forged broadcast (issuer mismatch). Settled before any
+    // `delegationTokenAdded` emission so subscribers see consistent ground
+    // truth from the revocation backend on the same tick.
+    if (changed) {
+        const pending = await delegationStore.getPendingRevocationByJTI(payload.jti);
+        if (pending != null) {
+            if (pending.revoker_did === payload.sub) {
+                // Pin the `verified_at` we send to subscribers to the same value the
+                // store writes; passing it explicitly avoids a millisecond-scale
+                // skew between the row and the emitted event under clock-tick
+                // boundaries.
+                const verifiedAt = Math.floor(Date.now() / 1000);
+                const flipped = await delegationStore.markRevocationVerified(payload.jti, {
+                    cap_exp: payload.exp,
+                    verified_at: verifiedAt
+                });
+                if (flipped && emitter != null) {
+                    await emitter.emit('delegationTokenRevoked', {
+                        jti: payload.jti,
+                        grantor: payload.sub,
+                        audience: payload.aud,
+                        revokerDID: pending.revoker_did,
+                        revokedAt: pending.revoked_iat,
+                        verifiedAt,
+                        capExp: payload.exp,
+                        groupID
+                    });
+                }
+            } else {
+                logger?.warn('pending revocation iss does not match arriving cap, dropping', {
+                    jti: payload.jti,
+                    pendingIss: pending.revoker_did,
+                    capGrantor: payload.sub,
+                    groupID
+                });
+                await delegationStore.deletePendingRevocation(payload.jti);
+            }
+        }
+    }
+    // Emit only when the held row was actually inserted or materially changed.
+    // Idempotent re-broadcasts (LWW lost, or won with byte-identical content)
+    // are silent — subscribers should not see duplicates for a token they
+    // already received.
+    if (changed && emitter != null) {
+        await emitter.emit('delegationTokenAdded', {
+            jwt: token,
+            jti: payload.jti,
+            grantor: payload.sub,
+            audience: payload.aud,
+            resource,
+            exp: payload.exp
+        });
+    }
+    return changed;
+}

package/lib/groups/store-received-revocation.d.ts

@@ -1,9 +1,9 @@
 import type { Logger } from '@kubun/logger';
-import type { P2PStoreAPI } from '@kubun/store-p2p';
+import type { DelegationStoreAPI } from '@kubun/store-delegation';
 import type { P2PEventEmitter } from './events.js';
 export type StoreReceivedRevocationParams = {
-    /** P2P store the revocation row is written to. */
-    p2pStore: P2PStoreAPI;
+    /** Delegation store the revocation row is written to. */
+    delegationStore: DelegationStoreAPI;
     /** Stringified signed revocation JWT carrying `{ jti, iss, rev, iat }`. */
     token: string;
     /** Group the revocation belongs to. */

package/lib/groups/store-received-revocation.js

@@ -1 +1,82 @@
-import{verifyToken as e}from"@enkaku/token";export async function storeReceivedRevocation(o){let r,{p2pStore:t,token:n,groupID:i,hlc:a,emitter:c,logger:d}=o;try{r=(await e(n)).payload}catch(e){return d?.debug("received revocation token verification failed, skipping",{groupID:i,error:e}),!1}if(!0!==r.rev)return d?.debug("received revocation token is not a revocation record, skipping",{groupID:i}),!1;let{jti:l,iss:v,iat:k}=r,u=await t.getDelegationTokenByJti(l),g=null,p=null;if(null!=u){if(u.grantor!==v)return d?.warn("received revocation iss does not match known capability grantor, skipping",{groupID:i,jti:l,iss:v,grantor:u.grantor}),!1;g=Math.floor(Date.now()/1e3),p=u.exp}let f=await t.addRevocation({jti:l,revoker_did:v,revoked_iat:k,revocation_token:n,verified_at:g,cap_exp:p,group_id:i,hlc:a});return f&&null!=g&&null!=u&&null!=c&&await c.emit("delegationTokenRevoked",{jti:l,grantor:u.grantor,audience:u.audience,revokerDID:v,revokedAt:k,verifiedAt:g,capExp:p,groupID:i}),f}
+import { verifyToken } from '@kokuin/token';
+/**
+ * Verify a received revocation token and write its row to the P2P store.
+ *
+ * Verified-on-arrival: when the referenced capability is already known
+ * locally and the revocation's `iss` matches that capability's `grantor`,
+ * the row is stored with `verified_at` populated so the hot-path
+ * `isRevoked` gate fires immediately. When the capability is unknown
+ * locally, the row is stored as pending (`verified_at` null) until a later
+ * `delegation:share` triggers a cross-check that flips it via
+ * `markRevocationVerified`. A signature-verified token whose `iss` does
+ * not match a known capability's `grantor` is rejected outright — a forged
+ * revocation must not pollute the local store.
+ *
+ * Returns `true` when the row was inserted or materially changed (LWW
+ * upsert). Returns `false` on verification failure, non-revocation
+ * payload, iss/grantor mismatch, or a lost/idempotent LWW upsert. Never
+ * throws on a forged or malformed token — it is skipped like an
+ * unverifiable broadcast entry.
+ */ export async function storeReceivedRevocation(params) {
+    const { delegationStore, token, groupID, hlc, emitter, logger } = params;
+    let payload;
+    try {
+        const verified = await verifyToken(token);
+        payload = verified.payload;
+    } catch (error) {
+        logger?.debug('received revocation token verification failed, skipping', {
+            groupID,
+            error
+        });
+        return false;
+    }
+    if (payload.rev !== true) {
+        logger?.debug('received revocation token is not a revocation record, skipping', {
+            groupID
+        });
+        return false;
+    }
+    const { jti, iss, iat } = payload;
+    const cap = await delegationStore.getDelegationTokenByJTI(jti);
+    let verifiedAt = null;
+    let capExp = null;
+    if (cap != null) {
+        if (cap.grantor !== iss) {
+            logger?.warn('received revocation iss does not match known capability grantor, skipping', {
+                groupID,
+                jti,
+                iss,
+                grantor: cap.grantor
+            });
+            return false;
+        }
+        verifiedAt = Math.floor(Date.now() / 1000);
+        capExp = cap.exp;
+    }
+    const changed = await delegationStore.addRevocation({
+        jti,
+        revoker_did: iss,
+        revoked_iat: iat,
+        revocation_token: token,
+        verified_at: verifiedAt,
+        cap_exp: capExp,
+        hlc
+    });
+    // Only verified-on-arrival writes are binding to local subscribers — a
+    // pending row carries no enforcement weight until the deferred cross-check
+    // promotes it. The cross-check path (in `storeReceivedGrant`) emits there
+    // when it flips a row from pending to verified.
+    if (changed && verifiedAt != null && cap != null && emitter != null) {
+        await emitter.emit('delegationTokenRevoked', {
+            jti,
+            grantor: cap.grantor,
+            audience: cap.audience,
+            revokerDID: iss,
+            revokedAt: iat,
+            verifiedAt,
+            capExp,
+            groupID
+        });
+    }
+    return changed;
+}

package/lib/hub/ack-backoff.d.ts

@@ -0,0 +1,22 @@
+import type { Logger } from '@kubun/logger';
+export type AckBatchParams = {
+    flushMs: number;
+    flushMax: number;
+    send: (ids: Array<string>) => Promise<void>;
+    logger?: Logger;
+};
+export declare class AckBatch {
+    #private;
+    constructor(params: AckBatchParams);
+    add(id: string): void;
+    /**
+     * Drain the pending id set and send it via the configured sender. Never
+     * rejects: send errors are logged and the ids are dropped silently (the hub
+     * will redeliver unacknowledged messages, so the next receive will produce a
+     * fresh ack).
+     */
+    flush(): Promise<void>;
+    dispose(): void;
+}
+export declare function computeBackoff(attempt: number, base: number, max: number, jitter: number): number;
+export declare function abortableSleep(ms: number, signal: AbortSignal): Promise<void>;

package/lib/hub/ack-backoff.js

@@ -0,0 +1,88 @@
+export class AckBatch {
+    #flushMs;
+    #flushMax;
+    #send;
+    #logger;
+    #ids = new Set();
+    #timer = null;
+    constructor(params){
+        this.#flushMs = params.flushMs;
+        this.#flushMax = params.flushMax;
+        this.#send = params.send;
+        this.#logger = params.logger;
+    }
+    add(id) {
+        const wasEmpty = this.#ids.size === 0;
+        this.#ids.add(id);
+        if (this.#ids.size >= this.#flushMax) {
+            if (this.#timer !== null) {
+                clearTimeout(this.#timer);
+                this.#timer = null;
+            }
+            void this.flush();
+            return;
+        }
+        if (wasEmpty && this.#timer === null) {
+            this.#timer = setTimeout(()=>{
+                this.#timer = null;
+                void this.flush();
+            }, this.#flushMs);
+        }
+    }
+    /**
+   * Drain the pending id set and send it via the configured sender. Never
+   * rejects: send errors are logged and the ids are dropped silently (the hub
+   * will redeliver unacknowledged messages, so the next receive will produce a
+   * fresh ack).
+   */ async flush() {
+        if (this.#timer !== null) {
+            clearTimeout(this.#timer);
+            this.#timer = null;
+        }
+        if (this.#ids.size === 0) {
+            return;
+        }
+        const snapshot = Array.from(this.#ids);
+        this.#ids.clear();
+        try {
+            await this.#send(snapshot);
+        } catch (err) {
+            this.#logger?.error('ack batch send failed', {
+                error: err,
+                count: snapshot.length
+            });
+        }
+    }
+    dispose() {
+        if (this.#timer !== null) {
+            clearTimeout(this.#timer);
+            this.#timer = null;
+        }
+        this.#ids.clear();
+    }
+}
+// --- Backoff ---
+export function computeBackoff(attempt, base, max, jitter) {
+    const exponential = base * 2 ** attempt;
+    const jittered = exponential * (1 + jitter * (2 * Math.random() - 1));
+    const clamped = Math.min(jittered, max);
+    return clamped < 0 ? 0 : clamped;
+}
+export function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject)=>{
+        if (signal.aborted) {
+            reject(signal.reason ?? new Error('aborted'));
+            return;
+        }
+        const timer = setTimeout(()=>{
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = ()=>{
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            reject(signal.reason ?? new Error('aborted'));
+        };
+        signal.addEventListener('abort', onAbort);
+    });
+}

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

@@ -1,13 +1,24 @@
-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';
+import { Disposer } from '@sozai/async';
+import type { EventEmitter } from '@sozai/event';
 export type ServerDIDObserver = (serverDID: string) => void | Promise<void>;
 export type ServerDIDMismatchObserver = (params: {
     hubURL: string;
     expectedServerDID: string;
     observedServerDID: string;
 }) => void;
+/**
+ * Fired once per freshly-spawned hub client when its first signed response
+ * arrives. The hub URL is bound into the call site; consumers (hub manager
+ * `captureServerDID`) use the URL to look up the local hub row and apply the
+ * TOFU conflict matrix. Errors are caught and logged — capture never blocks
+ * message forwarding, even on `HubServerDIDConflictError`.
+ */
+export type OnServerDIDObserved = (params: {
+    hubURL: string;
+    serverDID: string;
+}) => void | Promise<void>;
 export type DIDObservingTransportParams<Protocol extends ProtocolDefinition> = {
     inner: ClientTransportOf<Protocol>;
     /**

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

@@ -1 +1,126 @@
-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}}
+import { Disposer } from '@sozai/async';
+import { HubServerDIDMismatchError } from './errors.js';
+/**
+ * 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 class DIDObservingTransport extends Disposer {
+    #inner;
+    #onServerDID;
+    #expectedServerDID;
+    #hubURL;
+    #onMismatch;
+    #fired = false;
+    #failure = null;
+    constructor(params){
+        super({
+            signal: params.inner.signal,
+            dispose: async (reason)=>{
+                await params.inner.dispose(reason);
+            }
+        });
+        this.#inner = params.inner;
+        this.#onServerDID = params.onServerDID;
+        this.#expectedServerDID = params.expectedServerDID;
+        this.#hubURL = params.hubURL;
+        this.#onMismatch = params.onMismatch;
+    }
+    get events() {
+        return this.#inner.events;
+    }
+    getWritable() {
+        return this.#inner.getWritable();
+    }
+    async read() {
+        if (this.#failure != null) {
+            throw this.#failure;
+        }
+        const result = await this.#inner.read();
+        const failure = this.#observe(result);
+        if (failure != null) {
+            throw failure;
+        }
+        return result;
+    }
+    async write(value) {
+        await this.#inner.write(value);
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: async ()=>{
+                const result = await this.read();
+                if (result.done) {
+                    return {
+                        done: true,
+                        value: result.value ?? null
+                    };
+                }
+                return {
+                    done: false,
+                    value: result.value
+                };
+            }
+        };
+    }
+    /**
+   * Inspect a freshly-read result for `payload.iss`. Returns a
+   * `HubServerDIDMismatchError` to be thrown by the caller when in pinned
+   * mode and the observed DID does not match — in that case the wrapper
+   * also enters a permanent failed state and the offending message must NOT
+   * be returned to the caller. Returns `null` otherwise.
+   */ #observe(result) {
+        if (this.#fired || result.done || result.value == null) {
+            return null;
+        }
+        const payload = result.value.payload;
+        const iss = payload?.iss;
+        if (typeof iss !== 'string' || iss.length === 0) {
+            return null;
+        }
+        this.#fired = true;
+        if (this.#expectedServerDID != null) {
+            if (iss === this.#expectedServerDID) {
+                return null;
+            }
+            const error = new HubServerDIDMismatchError({
+                hubURL: this.#hubURL ?? '',
+                expectedServerDID: this.#expectedServerDID,
+                observedServerDID: iss
+            });
+            this.#failure = error;
+            if (this.#onMismatch != null) {
+                try {
+                    this.#onMismatch({
+                        hubURL: this.#hubURL ?? '',
+                        expectedServerDID: this.#expectedServerDID,
+                        observedServerDID: iss
+                    });
+                } catch  {
+                // observer errors must not mask the typed mismatch path
+                }
+            }
+            return error;
+        }
+        // TOFU mode — fire-and-forget: forwarding must not wait on the observer.
+        // Errors are swallowed at the wrapper; the pool-side handler logs them.
+        void Promise.resolve().then(()=>this.#onServerDID(iss)).catch(()=>{
+        // intentional: capture failures don't break the read loop in TOFU mode
+        });
+        return null;
+    }
+}

package/lib/hub/errors.d.ts

@@ -1,9 +1,3 @@
-export declare class ReconnectingError extends Error {
-    #private;
-    constructor(hubURL: string, attempt: number);
-    get hubURL(): string;
-    get attempt(): number;
-}
 /**
  * Thrown by `DIDObservingTransport.read()` when the first observed `payload.iss`
  * does not match the pinned `expectedServerDID`. The transport enters a

package/lib/hub/errors.js

@@ -1 +1,33 @@
-export class ReconnectingError extends Error{#e;#r;constructor(e,r){super(`broadcast wait timed out: hub ${e} reconnecting (attempt ${r})`),this.name="ReconnectingError",this.#e=e,this.#r=r}get hubURL(){return this.#e}get attempt(){return this.#r}}export class HubServerDIDMismatchError extends Error{#e;#t;#s;constructor(e){super(`hub at ${e.hubURL} signed responses with ${e.observedServerDID}; pinned to ${e.expectedServerDID}`),this.name="HubServerDIDMismatchError",this.#e=e.hubURL,this.#t=e.expectedServerDID,this.#s=e.observedServerDID}get hubURL(){return this.#e}get expectedServerDID(){return this.#t}get observedServerDID(){return this.#s}}
+/**
+ * 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 class HubServerDIDMismatchError extends Error {
+    #hubURL;
+    #expectedServerDID;
+    #observedServerDID;
+    constructor(params){
+        super(`hub at ${params.hubURL} signed responses with ${params.observedServerDID}; pinned to ${params.expectedServerDID}`);
+        this.name = 'HubServerDIDMismatchError';
+        this.#hubURL = params.hubURL;
+        this.#expectedServerDID = params.expectedServerDID;
+        this.#observedServerDID = params.observedServerDID;
+    }
+    get hubURL() {
+        return this.#hubURL;
+    }
+    get expectedServerDID() {
+        return this.#expectedServerDID;
+    }
+    get observedServerDID() {
+        return this.#observedServerDID;
+    }
+}

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

@@ -1,6 +1,31 @@
-import type { Identity } from '@enkaku/token';
-import { type ServerDIDObserver } from './did-observing-transport.js';
-import type { CreateHubClient } from './relay-manager.js';
+import { Client } from '@enkaku/client';
+import type { Identity } from '@kokuin/token';
+import type { HubProtocol } from '@kumiai/hub-protocol';
+import { type ServerDIDMismatchObserver, type ServerDIDObserver } from './did-observing-transport.js';
+export type CreateHubClientOptions = {
+    /**
+     * Per-call observer fired once when the first signed response arrives. Set by
+     * the caller so observed server DIDs can be routed through TOFU capture with
+     * the hub URL bound. Factories that don't honour this opt simply skip TOFU
+     * capture for the spawned client.
+     */
+    onServerDID?: ServerDIDObserver;
+    /**
+     * Pinned `server_did` resolved 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
+     * caller 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 CreateHTTPHubClientParams = {
     identity: Identity;
     fetch?: typeof globalThis.fetch;

package/lib/hub/http-client.js

@@ -1 +1,32 @@
-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})}}
+import { Client } from '@enkaku/client';
+import { ClientTransport } from '@enkaku/http-fetch';
+import { DIDObservingTransport } from './did-observing-transport.js';
+export function createHTTPHubClient(params) {
+    return async (hubURL, opts)=>{
+        const inner = new ClientTransport({
+            url: hubURL,
+            fetch: params.fetch
+        });
+        const observer = opts?.onServerDID ?? params.onServerDID;
+        const expectedServerDID = opts?.expectedServerDID;
+        const onMismatch = opts?.onMismatch;
+        // Wrap whenever any DID-aware behaviour is needed: TOFU capture (observer),
+        // pinned-DID enforcement (expectedServerDID), or mismatch side-channel.
+        const needsWrapper = observer != null || expectedServerDID != null || onMismatch != null;
+        const transport = needsWrapper ? new DIDObservingTransport({
+            inner,
+            // Wrapper requires an observer; supply a no-op when only enforcement
+            // is requested. The TOFU branch in the wrapper is gated by
+            // `expectedServerDID == null` regardless.
+            onServerDID: observer ?? (()=>{}),
+            expectedServerDID,
+            hubURL,
+            onMismatch
+        }) : inner;
+        return new Client({
+            transport,
+            identity: params.identity,
+            serverID: params.serverID
+        });
+    };
+}

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

@@ -0,0 +1,24 @@
+import type { Client } from '@enkaku/client';
+import type { Logger } from '@kubun/logger';
+import type { HubProtocol } from '@kumiai/hub-protocol';
+import type { HubLike } from '@kumiai/hub-tunnel';
+export type CreateHubLikeParams = {
+    /**
+     * Builds a fresh `Client<HubProtocol>` bound to one hub URL + device identity.
+     * Called once on the first connect and again on every reconnect. Injected
+     * rather than constructed here so the adapter is testable against a fake
+     * client without standing up HTTP.
+     */
+    createClient: () => Client<HubProtocol> | Promise<Client<HubProtocol>>;
+    /** Authenticated DID of this device — drains receive and stamps publishes. */
+    localDID: string;
+    logger?: Logger;
+    ackFlushMs?: number;
+    ackFlushMax?: number;
+    backoffBaseMs?: number;
+    backoffMaxMs?: number;
+    backoffJitter?: number;
+};
+export declare function createHubLike(params: CreateHubLikeParams): HubLike & {
+    dispose: () => Promise<void>;
+};