@kumiai/hub-server 0.3.0 → 0.4.0

package/README.md

@@ -0,0 +1,84 @@
+# @kumiai/hub-server
+
+The hub server: `@kumiai/hub-protocol`'s procedure handlers wired to an `@enkaku` server, a live
+client registry for push fan-out, and an in-memory `HubStore` for development and tests.
+
+## Exports
+
+- `createHub({ transport, store, identity, ... })` — the whole server: handlers, registry, access
+  rules, rate limits, and an optional scheduled purge. Returns `{ registry, server }`.
+- `createHandlers({ registry, store, ... })` — the handlers alone, for a host assembling its own
+  server.
+- `createMemoryStore({ maxDepth?, retention? })` — an in-memory `HubStore`. For testing and
+  development; it is also what runs the `@kumiai/hub-conformance` suites in this repo.
+- `HubClientRegistry` — the live-connection table.
+- `createRateLimiter`, `DEFAULT_RATE_LIMITS`, `DEFAULT_KEYPACKAGE_FETCH_LIMITS`,
+  `DEFAULT_HUB_ACCESS_RULES`.
+
+```ts
+import { createHub, createMemoryStore } from '@kumiai/hub-server'
+
+const { server } = createHub({ transport, identity, store: createMemoryStore() })
+```
+
+## The hub is blind, and identity comes only from the signature
+
+Topic IDs are opaque and payloads are ciphertext the hub never opens. Every handler takes the caller
+DID from the **verified issuer** of the signed message, never from a wire field — so
+`hub/v1/topic/fetch` cannot be pointed at someone else's subscription, and a publish cannot claim
+another sender. The `identity` param is required for that reason.
+
+Authorization is two layers, and only the second one knows about topics: `accessRules` gate the
+procedures (the default lets any authenticated DID call them), and the optional
+`authorize(request)` hook decides publish and subscribe per topic. It takes one discriminated
+`AuthorizeRequest` — narrow on `request.action` — and returns `AuthorizeDecision`, either a boolean
+or `{ allow, reason?, code?, retryAfterMs? }`. `AuthorizeRequest` names six actions, but only
+`publish` and `subscribe` are dispatched today. The default allows any authenticated DID.
+
+## Durable subscription, ephemeral connection
+
+Subscription state lives in the store. `HubClientRegistry` holds only currently-connected clients and
+their live `hub/v1/receive` writers, so it routes push fan-out and nothing else — a restart loses no
+subscription.
+
+Binding a receive channel **evicts** whatever held the lane for that DID. A reconnect happens because
+the old connection broke and the server learns that last, so the stale writer must give way to the
+live one, not the other way round. The evicted channel is resolved rather than thrown: being replaced
+is not its error, and the client that replaced it is the same client.
+
+`hub/v1/receive` is always added to the server's `longLivedProcedures`, so open mailbox channels are
+exempt from `controllerTimeoutMs` and from the `maxConcurrentHandlers` cap. A host passing its own
+`limits` does not need to remember this.
+
+## What live fan-out does and does not push
+
+A **deduped** publish fans out to nobody. It appended nothing — the frame was already accepted and
+already delivered to whoever was subscribed then, and its sequenceID may since have been acked and
+its delivery row removed — so re-running the loop would push a frame every current subscriber has
+already applied, named by a dead sequenceID. Fan-out is for a genuine append only.
+
+The sender is excluded from its own fan-out. `hub/v1/topic/fetch` makes no such exclusion — a topic's
+log holds every log-class frame including the caller's own — so a reader that must not see its own
+messages twice filters them itself, as `@kumiai/rpc`'s drain does.
+
+A pushed frame carries `logPosition` **only** when it is log-class, and the key is spread in rather
+than assigned, because `logPosition: undefined` becomes a present key with a falsy value once it is
+off the wire — and the entire point of the field is that a reader can tell "no place in any log" from
+a place.
+
+## Retention: the store refuses, the hub schedules
+
+Two different knobs, easily confused. `createHub`'s `purge.olderThan` (default 7 days) is the **age
+bound** the scheduled sweep applies to a topic no subscriber asked to keep longer; the sweep runs on
+`purge.interval` (default 1 hour) and stops with the server. The **ceiling** on what a subscriber may
+request belongs to the store, because the store is what refuses the subscribe —
+`createMemoryStore`'s is 30 days, finite by design, since an unbounded ceiling lets any subscriber
+pin a topic's frames forever with `subscribe({ retention: 2 ** 31 })`. A subscribe above the ceiling
+is refused with `RetentionExceededError`, never clamped.
+
+`createMemoryStore`'s `maxDepth` (default 1000) evicts the oldest **log** frames beyond that count.
+Mailbox frames on the same topic are not counted, so a member cannot evict the log with a mailbox
+flood.
+
+Publish rate limits are per DID (20/s, burst 50) and per topic (100/s, burst 200), merged over
+`DEFAULT_RATE_LIMITS`; `hub/v1/keypackage/fetch` has its own request quota per requester DID.

package/lib/handlers.d.ts

@@ -2,8 +2,61 @@ import { type ProcedureHandlers } from '@enkaku/server';
 import type { HubProtocol, HubStore } from '@kumiai/hub-protocol';
 import { type RateLimitConfig } from './rateLimit.js';
 import type { HubClientRegistry } from './registry.js';
-export type AuthorizeAction = 'publish' | 'subscribe';
-export type AuthorizeHook = (did: string, action: AuthorizeAction, topicID: string) => boolean | Promise<boolean>;
+/**
+ * A single request to authorize. All six variants ship even though only `publish` and
+ * `subscribe` are currently enforced: the union is the exhaustive-switch surface a host's own
+ * `switch (req.action)` closes over, so adding a seventh variant later is the compatibility break
+ * this type exists to avoid.
+ *
+ * A host's `switch` need not handle every action today — an unrecognized action should default to
+ * allow, so a hook written before a new variant shipped doesn't silently start refusing a
+ * procedure that was previously ungated.
+ */
+export type AuthorizeRequest = {
+    action: 'publish';
+    did: string;
+    topicID: string;
+    retain: 'log' | 'mailbox';
+    payloadSize: number;
+} | {
+    action: 'subscribe';
+    did: string;
+    topicID: string;
+    retention?: number;
+} | {
+    action: 'unsubscribe';
+    did: string;
+    topicID: string;
+} | {
+    action: 'topic/fetch';
+    did: string;
+    topicID: string;
+} | {
+    action: 'keypackage/upload';
+    did: string;
+    count: number;
+} | {
+    action: 'keypackage/fetch';
+    did: string;
+    targetDID: string;
+    count: number;
+};
+/**
+ * A plain `boolean` is shorthand for `{ allow: boolean }`, with no reason, code, or retry hint.
+ *
+ * **`reason` is the only field a caller sees today.** `code` and `retryAfterMs` are reserved for
+ * enforcement that hasn't been built yet — a hook may return them, but both are silently dropped
+ * before the refusal reaches the client. They ship now because widening this union later is the
+ * break the surface exists to avoid; until enforcement lands, don't depend on either reaching a
+ * caller.
+ */
+export type AuthorizeDecision = boolean | {
+    allow: boolean;
+    reason?: string;
+    code?: string;
+    retryAfterMs?: number;
+};
+export type AuthorizeHook = (req: AuthorizeRequest) => AuthorizeDecision | Promise<AuthorizeDecision>;
 export type HubRateLimits = {
     perDID: RateLimitConfig;
     perTopic: RateLimitConfig;

package/lib/handlers.js

@@ -2,6 +2,11 @@ import { HandlerError } from '@enkaku/server';
 import { hubErrorCodeOf } from '@kumiai/hub-protocol';
 import { fromB64, toB64 } from '@sozai/codec';
 import { createRateLimiter } from './rateLimit.js';
+function normalizeAuthorizeDecision(decision) {
+    return typeof decision === 'boolean' ? {
+        allow: decision
+    } : decision;
+}
 export const DEFAULT_RATE_LIMITS = {
     perDID: {
         rate: 20,
@@ -81,13 +86,32 @@ export function createHandlers(params) {
         window.count++;
     }
     return {
-        'hub/publish': async (ctx)=>{
+        'hub/v1/publish': async (ctx)=>{
             const { topicID, payload } = ctx.param;
             const senderDID = getClientDID(ctx);
-            if (!await authorize(senderDID, 'publish', topicID)) {
+            // Decoded before authorize (not after) so the hook can see the real size. Two consequences
+            // are deliberate: an unauthorized caller sending malformed base64 gets a decode error instead
+            // of EK02, and decoding runs before both rate limiters, so oversized payloads are decoded
+            // before being throttled (bounded by the transport's own message limit). Deriving the size
+            // arithmetically from the base64 length instead was rejected — it drifts from
+            // `@sozai/codec`'s actual decoding and can hand the hook a wrong number.
+            //
+            // `retain` defaults to 'mailbox' here, matching the store's own default (`memoryStore.ts`) —
+            // the hook must never see an absent retain, since `AuthorizeRequest`'s `publish` variant
+            // declares it required.
+            const payloadBytes = fromB64(payload);
+            const retain = ctx.param.retain ?? 'mailbox';
+            const decision = normalizeAuthorizeDecision(await authorize({
+                action: 'publish',
+                did: senderDID,
+                topicID,
+                retain,
+                payloadSize: payloadBytes.length
+            }));
+            if (!decision.allow) {
                 throw new HandlerError({
                     code: 'EK02',
-                    message: 'Not authorized to publish to topic'
+                    message: decision.reason ?? 'Not authorized to publish to topic'
                 });
             }
             if (!didLimiter.tryConsume(senderDID)) {
@@ -102,7 +126,6 @@ export function createHandlers(params) {
                     message: 'Publish rate limit exceeded for topic'
                 });
             }
-            const payloadBytes = fromB64(payload);
             let sequenceID;
             let deduped;
             try {
@@ -123,11 +146,16 @@ export function createHandlers(params) {
             } catch (error) {
                 rethrowAsHandlerError(error);
             }
-            // A deduped publish appended nothing: the frame was already accepted, already fanned out to
-            // whoever was subscribed then, and its sequenceID may since have been acked and its delivery
-            // row removed. Re-running the loop would push a frame every current subscriber has already
-            // applied, named by a dead sequenceID. Live fan-out is for a genuine append only.
+            // A deduped publish appended nothing: already fanned out to whoever was subscribed then, and
+            // its sequenceID may since be acked and its delivery row gone. Re-running would push a frame
+            // every current subscriber already has, named by a dead sequenceID.
             if (!deduped) {
+                // Only a log-class publish carries a logPosition. This sequenceID IS the log position (the
+                // store just minted it for this accepted append); a mailbox publish has none, since its
+                // recipient's own delivery-queue position isn't usable as a durable log cursor.
+                const logPosition = ctx.param.retain === 'log' ? {
+                    logPosition: sequenceID
+                } : {};
                 // Live-deliver to currently-connected subscribers (minus the sender).
                 const subscribers = await store.getSubscribers(topicID);
                 for (const recipientDID of subscribers){
@@ -138,7 +166,8 @@ export function createHandlers(params) {
                             sequenceID,
                             senderDID,
                             topicID,
-                            payload: payloadBytes
+                            payload: payloadBytes,
+                            ...logPosition
                         });
                     }
                 }
@@ -147,20 +176,26 @@ export function createHandlers(params) {
                 sequenceID
             };
         },
-        'hub/subscribe': async (ctx)=>{
-            const { topicID } = ctx.param;
+        'hub/v1/subscribe': async (ctx)=>{
+            const { topicID, retention } = ctx.param;
             const clientDID = getClientDID(ctx);
-            if (!await authorize(clientDID, 'subscribe', topicID)) {
+            const decision = normalizeAuthorizeDecision(await authorize({
+                action: 'subscribe',
+                did: clientDID,
+                topicID,
+                retention
+            }));
+            if (!decision.allow) {
                 throw new HandlerError({
                     code: 'EK02',
-                    message: 'Not authorized to subscribe to topic'
+                    message: decision.reason ?? 'Not authorized to subscribe to topic'
                 });
             }
             try {
                 await store.subscribe({
                     subscriberDID: clientDID,
                     topicID,
-                    retention: ctx.param.retention
+                    retention
                 });
             } catch (error) {
                 rethrowAsHandlerError(error);
@@ -169,10 +204,10 @@ export function createHandlers(params) {
                 subscribed: true
             };
         },
-        'hub/topic/fetch': async (ctx)=>{
+        'hub/v1/topic/fetch': async (ctx)=>{
             const { topicID, after, limit } = ctx.param;
-            // The subscriber is the authenticated caller, taken from the verified issuer of the signed
-            // message — never a wire field, or any member could read a topic's log by naming another.
+            // subscriberDID is the authenticated caller (verified issuer), never a wire field — or any
+            // member could read another's topic log by naming them.
             const subscriberDID = getClientDID(ctx);
             try {
                 const result = await store.fetchTopic({
@@ -195,7 +230,7 @@ export function createHandlers(params) {
                 rethrowAsHandlerError(error);
             }
         },
-        'hub/unsubscribe': async (ctx)=>{
+        'hub/v1/unsubscribe': async (ctx)=>{
             const { topicID } = ctx.param;
             const clientDID = getClientDID(ctx);
             await store.unsubscribe(clientDID, topicID);
@@ -203,27 +238,40 @@ export function createHandlers(params) {
                 unsubscribed: true
             };
         },
-        'hub/receive': async (ctx)=>{
+        'hub/v1/receive': async (ctx)=>{
             const clientDID = getClientDID(ctx);
             const { after } = ctx.param ?? {};
             registry.register(clientDID);
-            if (registry.isWriterBound(clientDID)) {
-                throw new HandlerError({
-                    code: 'EK01',
-                    message: `receive writer already bound for DID ${clientDID}`
-                });
-            }
             const writer = ctx.writable.getWriter();
             const reader = ctx.readable.getReader();
+            // Ends this channel when a newer one for the same DID takes the lane. Resolved, not thrown —
+            // replacement isn't this channel's error, and it's the same client that replaced it.
+            let endEvicted;
+            const evictedHere = new Promise((resolve)=>{
+                endEvicted = resolve;
+            });
+            let receiveToken;
             try {
-                registry.setReceiveWriter(clientDID, (message)=>{
+                // Binding evicts whatever held the lane: a reconnect means the old connection broke and the
+                // server learns last, so the stale writer must give way to the live one. See
+                // `HubClientRegistry.bindReceiveWriter`.
+                const { token, evicted } = registry.bindReceiveWriter(clientDID, (message)=>{
                     writer.write({
                         sequenceID: message.sequenceID,
                         senderDID: message.senderDID,
                         topicID: message.topicID,
-                        payload: toB64(message.payload)
+                        payload: toB64(message.payload),
+                        // Spread, not plain assignment — `logPosition: undefined` becomes a present key
+                        // once serialized, defeating the field's whole point (telling absent from present).
+                        ...message.logPosition != null ? {
+                            logPosition: message.logPosition
+                        } : {}
                     }).catch(()=>{});
-                });
+                }, ()=>endEvicted?.());
+                receiveToken = token;
+                // After the bind, so the lane is never unheld between the two — a frame arriving in that
+                // gap would have nowhere to go, and mailbox frames drop when nobody's there.
+                evicted?.();
                 let cursor = after;
                 while(true){
                     const result = await store.fetch({
@@ -236,19 +284,23 @@ export function createHandlers(params) {
                             sequenceID: msg.sequenceID,
                             senderDID: msg.senderDID,
                             topicID: msg.topicID,
-                            payload: toB64(msg.payload)
+                            payload: toB64(msg.payload),
+                            ...msg.logPosition != null ? {
+                                logPosition: msg.logPosition
+                            } : {}
                         });
                     }
                     cursor = result.cursor;
                     if (!result.hasMore) break;
                 }
             } catch (error) {
-                registry.clearReceiveWriter(clientDID);
+                if (receiveToken != null) registry.releaseReceiveWriter(clientDID, receiveToken);
                 registry.unregisterIfIdle(clientDID);
                 reader.cancel().catch(()=>{});
                 writer.abort(error).catch(()=>{});
                 throw error;
             }
+            const token = receiveToken;
             void (async ()=>{
                 try {
                     while(true){
@@ -266,18 +318,23 @@ export function createHandlers(params) {
                 }
             })();
             return new Promise((resolve)=>{
-                ctx.signal.addEventListener('abort', ()=>{
-                    registry.clearReceiveWriter(clientDID);
+                const finish = ()=>{
+                    // Token-scoped, so an already-evicted channel can't unbind the one that replaced it.
+                    if (token != null) registry.releaseReceiveWriter(clientDID, token);
                     registry.unregisterIfIdle(clientDID);
                     reader.cancel().catch(()=>{});
                     writer.close().catch(()=>{});
                     resolve(undefined);
-                }, {
+                };
+                // Evicted by a newer channel: end this one; `finish` releases only its own token, which is
+                // no longer current.
+                void evictedHere.then(finish);
+                ctx.signal.addEventListener('abort', finish, {
                     once: true
                 });
             });
         },
-        'hub/keypackage/upload': async (ctx)=>{
+        'hub/v1/keypackage/upload': async (ctx)=>{
             const { keyPackages } = ctx.param;
             const clientDID = getClientDID(ctx);
             await Promise.all(keyPackages.map((kp)=>store.storeKeyPackage(clientDID, kp)));
@@ -285,7 +342,7 @@ export function createHandlers(params) {
                 stored: keyPackages.length
             };
         },
-        'hub/keypackage/fetch': async (ctx)=>{
+        'hub/v1/keypackage/fetch': async (ctx)=>{
             const requesterDID = getClientDID(ctx);
             assertKeyPackageFetchAllowed(requesterDID);
             const { did, count } = ctx.param;

package/lib/hub.d.ts

@@ -34,12 +34,15 @@ export type CreateHubParams = {
     authorize?: AuthorizeHook;
     /** Publish rate limits. Merged over {@link DEFAULT_RATE_LIMITS}. */
     rateLimits?: Partial<HubRateLimits>;
-    /** Quotas applied to hub/keypackage/fetch. Merged over {@link DEFAULT_KEYPACKAGE_FETCH_LIMITS}. */
+    /**
+     * Quotas applied to hub/v1/keypackage/fetch. Merged over
+     * {@link DEFAULT_KEYPACKAGE_FETCH_LIMITS}.
+     */
     keyPackageFetchLimits?: Partial<KeyPackageFetchLimits>;
     /** Scheduled purge of expired stored messages. Set to `false` to disable. */
     purge?: HubPurgeOptions | false;
     /**
-     * Server resource limits. `hub/receive` is always added to
+     * Server resource limits. `hub/v1/receive` is always added to
      * `longLivedProcedures` so open mailbox channels are exempt from
      * `controllerTimeoutMs` and from the `maxConcurrentHandlers` cap.
      */

package/lib/hub.js

@@ -25,7 +25,7 @@ export function createHub(params) {
         longLivedProcedures: [
             ...new Set([
                 ...params.limits?.longLivedProcedures ?? [],
-                'hub/receive'
+                'hub/v1/receive'
             ])
         ]
     };

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export type { AuthorizeAction, AuthorizeHook, CreateHandlersParams, HubRateLimits, KeyPackageFetchLimits, } from './handlers.js';
+export type { AuthorizeDecision, AuthorizeHook, AuthorizeRequest, CreateHandlersParams, HubRateLimits, KeyPackageFetchLimits, } from './handlers.js';
 export { createHandlers, DEFAULT_KEYPACKAGE_FETCH_LIMITS, DEFAULT_RATE_LIMITS } from './handlers.js';
 export type { CreateHubParams, HubInstance, HubPurgeOptions } from './hub.js';
 export { createHub, DEFAULT_HUB_ACCESS_RULES } from './hub.js';

package/lib/memoryStore.js

@@ -5,6 +5,27 @@ const DEFAULT_MAX_DEPTH = 1000;
 function formatSequenceID(counter) {
     return String(counter).padStart(12, '0');
 }
+/**
+ * The entry as a reader sees it, with the ONE piece of routing metadata a reader cannot recover for
+ * itself: where the frame sits in its topic's log.
+ *
+ * Present iff the entry is log-class, and the key is left off entirely otherwise — a mailbox frame
+ * has no place in a log, and a falsy placeholder is a position a reader's cursor would move to,
+ * skipping every log frame below it. This store mints one sequence for both, so the log position of
+ * a log-class frame IS its sequenceID here; a store that mints a separate per-recipient delivery
+ * sequence reports its log's own value, and the conformance suite pins the equality that matters —
+ * a pushed log frame's `logPosition` is the position `fetchTopic` serves that same frame at.
+ */ function asStoredMessage(entry) {
+    return {
+        sequenceID: entry.sequenceID,
+        senderDID: entry.senderDID,
+        topicID: entry.topicID,
+        payload: entry.payload,
+        ...entry.retain === 'log' ? {
+            logPosition: entry.sequenceID
+        } : {}
+    };
+}
 /**
  * In-memory HubStore for testing and development.
  *
@@ -224,12 +245,7 @@ function formatSequenceID(counter) {
             for (const sequenceID of selected){
                 const entry = entries.get(sequenceID);
                 if (entry != null) {
-                    resultMessages.push({
-                        sequenceID: entry.sequenceID,
-                        senderDID: entry.senderDID,
-                        topicID: entry.topicID,
-                        payload: entry.payload
-                    });
+                    resultMessages.push(asStoredMessage(entry));
                 }
             }
             const cursor = resultMessages.length > 0 ? resultMessages[resultMessages.length - 1].sequenceID : null;
@@ -262,12 +278,7 @@ function formatSequenceID(counter) {
             for (const sequenceID of limited){
                 const entry = entries.get(sequenceID);
                 if (entry != null) {
-                    messages.push({
-                        sequenceID: entry.sequenceID,
-                        senderDID: entry.senderDID,
-                        topicID: entry.topicID,
-                        payload: entry.payload
-                    });
+                    messages.push(asStoredMessage(entry));
                 }
             }
             return {

package/lib/registry.d.ts

@@ -2,6 +2,10 @@ import type { StoredMessage } from '@kumiai/hub-protocol';
 export type ClientEntry = {
     did: string;
     sendMessage: ((message: StoredMessage) => void) | null;
+    /** Ends the currently bound receive channel. Set with the writer and cleared with it. */
+    endReceive: (() => void) | null;
+    /** Identifies the binding, so a channel can only ever release its OWN. */
+    token: symbol | null;
 };
 /**
  * Tracks online clients and their live receive-channel writers. Subscription
@@ -14,8 +18,33 @@ export declare class HubClientRegistry {
     unregister(did: string): void;
     /** Removes the entry only when no receive writer is bound. */
     unregisterIfIdle(did: string): void;
-    setReceiveWriter(did: string, writer: (message: StoredMessage) => void): void;
-    clearReceiveWriter(did: string): void;
+    /**
+     * Bind this DID's receive writer, EVICTING whatever was bound before it.
+     *
+     * One writer per DID, and the newest one wins. The alternative — refuse the second — reads as
+     * the safer rule and is not: a client whose socket died has a writer the server still believes
+     * in, because nothing has told it otherwise yet, and that belief outlives the socket by however
+     * long the transport takes to notice. Refusing on it means the reconnect that the client makes
+     * precisely BECAUSE its connection dropped is the one that gets turned away, and the member has
+     * no push lane until a timeout it cannot see or influence expires. Last-writer-wins costs a
+     * live connection only when the same authenticated DID opens a second channel, which is the
+     * same client and its own business.
+     *
+     * The eviction is handed back rather than run here: ending a channel is the handler's to do,
+     * and a registry that closed streams would be doing two jobs.
+     *
+     * The TOKEN is what keeps the eviction from unbinding its successor. The evicted handler runs
+     * its own cleanup afterwards — it does not know why it ended — and a `clear(did)` there would
+     * null the writer the new channel has just bound, leaving the DID online with nothing behind
+     * it. So a release names the binding it is releasing, and one that is no longer current is a
+     * no-op.
+     */
+    bindReceiveWriter(did: string, writer: (message: StoredMessage) => void, endReceive: () => void): {
+        token: symbol;
+        evicted: (() => void) | null;
+    };
+    /** Clear the binding this token names. A token that is no longer current is a no-op. */
+    releaseReceiveWriter(did: string, token: symbol): void;
     getClient(did: string): ClientEntry | undefined;
     isOnline(did: string): boolean;
     isWriterBound(did: string): boolean;

package/lib/registry.js

@@ -11,7 +11,9 @@
         }
         const entry = {
             did,
-            sendMessage: null
+            sendMessage: null,
+            endReceive: null,
+            token: null
         };
         this.#clients.set(did, entry);
         return entry;
@@ -25,19 +27,48 @@
             this.#clients.delete(did);
         }
     }
-    setReceiveWriter(did, writer) {
+    /**
+   * Bind this DID's receive writer, EVICTING whatever was bound before it.
+   *
+   * One writer per DID, and the newest one wins. The alternative — refuse the second — reads as
+   * the safer rule and is not: a client whose socket died has a writer the server still believes
+   * in, because nothing has told it otherwise yet, and that belief outlives the socket by however
+   * long the transport takes to notice. Refusing on it means the reconnect that the client makes
+   * precisely BECAUSE its connection dropped is the one that gets turned away, and the member has
+   * no push lane until a timeout it cannot see or influence expires. Last-writer-wins costs a
+   * live connection only when the same authenticated DID opens a second channel, which is the
+   * same client and its own business.
+   *
+   * The eviction is handed back rather than run here: ending a channel is the handler's to do,
+   * and a registry that closed streams would be doing two jobs.
+   *
+   * The TOKEN is what keeps the eviction from unbinding its successor. The evicted handler runs
+   * its own cleanup afterwards — it does not know why it ended — and a `clear(did)` there would
+   * null the writer the new channel has just bound, leaving the DID online with nothing behind
+   * it. So a release names the binding it is releasing, and one that is no longer current is a
+   * no-op.
+   */ bindReceiveWriter(did, writer, endReceive) {
         const entry = this.#clients.get(did);
-        if (entry == null) return;
-        if (entry.sendMessage != null) {
-            throw new Error(`receive writer already bound for DID ${did}`);
-        }
+        if (entry == null) return {
+            token: Symbol('unbound'),
+            evicted: null
+        };
+        const evicted = entry.endReceive;
+        const token = Symbol('receive');
         entry.sendMessage = writer;
+        entry.endReceive = endReceive;
+        entry.token = token;
+        return {
+            token,
+            evicted
+        };
     }
-    clearReceiveWriter(did) {
+    /** Clear the binding this token names. A token that is no longer current is a no-op. */ releaseReceiveWriter(did, token) {
         const entry = this.#clients.get(did);
-        if (entry != null) {
-            entry.sendMessage = null;
-        }
+        if (entry == null || entry.token !== token) return;
+        entry.sendMessage = null;
+        entry.endReceive = null;
+        entry.token = null;
     }
     getClient(did) {
         return this.#clients.get(did);

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@kumiai/hub-server",
-  "version": "0.3.0",
-  "license": "MIT",
+  "version": "0.4.0",
   "description": "Hub server for Enkaku E2EE group message routing",
   "keywords": [
     "hub",
@@ -14,38 +13,37 @@
     "url": "https://github.com/TairuFramework/kumiai",
     "directory": "packages/hub-server"
   },
+  "license": "MIT",
+  "sideEffects": false,
   "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "exports": {
     ".": "./lib/index.js"
   },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
     "lib/*"
   ],
-  "sideEffects": false,
   "dependencies": {
-    "@sozai/codec": "^0.2.0",
-    "@sozai/event": "^0.1.1",
     "@enkaku/protocol": "^0.19.0",
     "@enkaku/server": "^0.19.0",
-    "@sozai/stream": "^0.2.0",
-    "@kokuin/token": "^0.2.0",
-    "@kumiai/hub-protocol": "^0.3.0",
-    "@kumiai/mls": "^0.3.0"
+    "@kokuin/token": "^0.3.0",
+    "@sozai/codec": "^0.2.0",
+    "@sozai/event": "^0.1.1",
+    "@kumiai/hub-protocol": "^0.4.0"
   },
   "devDependencies": {
     "@enkaku/client": "^0.19.0",
     "@enkaku/transport": "^0.19.1",
-    "@kumiai/hub-conformance": "^0.3.0"
+    "@kumiai/hub-conformance": "^0.4.0"
   },
   "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
     "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
-    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
-    "test:unit": "vitest run",
-    "test": "pnpm run test:types && pnpm run test:unit"
+    "test:unit": "vitest run"
   }
 }