@kumiai/hub-server 0.1.0

package/lib/handlers.d.ts

@@ -0,0 +1,28 @@
+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>;
+export type HubRateLimits = {
+    perDID: RateLimitConfig;
+    perTopic: RateLimitConfig;
+};
+export declare const DEFAULT_RATE_LIMITS: HubRateLimits;
+export type KeyPackageFetchLimits = {
+    /** Maximum number of key packages returned per fetch. Default: 10 */
+    maxCount: number;
+    /** Maximum number of fetch requests per requester DID per window. Default: 30 */
+    maxRequests: number;
+    /** Rate-limit window duration in milliseconds. Default: 60000 (1 min) */
+    windowMs: number;
+};
+export declare const DEFAULT_KEYPACKAGE_FETCH_LIMITS: KeyPackageFetchLimits;
+export type CreateHandlersParams = {
+    registry: HubClientRegistry;
+    store: HubStore;
+    authorize?: AuthorizeHook;
+    rateLimits?: Partial<HubRateLimits>;
+    keyPackageFetchLimits?: Partial<KeyPackageFetchLimits>;
+};
+export declare function createHandlers(params: CreateHandlersParams): ProcedureHandlers<HubProtocol>;

package/lib/handlers.js

@@ -0,0 +1,229 @@
+import { HandlerError } from '@enkaku/server';
+import { fromB64, toB64 } from '@sozai/codec';
+import { createRateLimiter } from './rateLimit.js';
+export const DEFAULT_RATE_LIMITS = {
+    perDID: {
+        rate: 20,
+        burst: 50
+    },
+    perTopic: {
+        rate: 100,
+        burst: 200
+    }
+};
+export const DEFAULT_KEYPACKAGE_FETCH_LIMITS = {
+    maxCount: 10,
+    maxRequests: 30,
+    windowMs: 60_000
+};
+function getClientDID(ctx) {
+    const iss = ctx.message.payload.iss;
+    if (typeof iss !== 'string' || iss.length === 0) {
+        throw new Error('Unauthenticated message: missing verified issuer DID');
+    }
+    return iss;
+}
+export function createHandlers(params) {
+    const { store, registry } = params;
+    const authorize = params.authorize ?? (()=>true);
+    const rateLimits = {
+        perDID: {
+            ...DEFAULT_RATE_LIMITS.perDID,
+            ...params.rateLimits?.perDID
+        },
+        perTopic: {
+            ...DEFAULT_RATE_LIMITS.perTopic,
+            ...params.rateLimits?.perTopic
+        }
+    };
+    const didLimiter = createRateLimiter(rateLimits.perDID);
+    const topicLimiter = createRateLimiter(rateLimits.perTopic);
+    const fetchLimits = {
+        ...DEFAULT_KEYPACKAGE_FETCH_LIMITS,
+        ...params.keyPackageFetchLimits
+    };
+    const fetchWindows = new Map();
+    function assertKeyPackageFetchAllowed(requesterDID) {
+        const now = Date.now();
+        if (fetchWindows.size > 1024) {
+            for (const [did, window] of fetchWindows){
+                if (window.resetAt <= now) {
+                    fetchWindows.delete(did);
+                }
+            }
+        }
+        const window = fetchWindows.get(requesterDID);
+        if (window == null || window.resetAt <= now) {
+            fetchWindows.set(requesterDID, {
+                count: 1,
+                resetAt: now + fetchLimits.windowMs
+            });
+            return;
+        }
+        if (window.count >= fetchLimits.maxRequests) {
+            throw new Error('Key package fetch rate limit exceeded');
+        }
+        window.count++;
+    }
+    return {
+        'hub/publish': async (ctx)=>{
+            const { topicID, payload } = ctx.param;
+            const senderDID = getClientDID(ctx);
+            if (!await authorize(senderDID, 'publish', topicID)) {
+                throw new HandlerError({
+                    code: 'EK02',
+                    message: 'Not authorized to publish to topic'
+                });
+            }
+            if (!didLimiter.tryConsume(senderDID)) {
+                throw new HandlerError({
+                    code: 'EK01',
+                    message: 'Publish rate limit exceeded for DID'
+                });
+            }
+            if (!topicLimiter.tryConsume(topicID)) {
+                throw new HandlerError({
+                    code: 'EK01',
+                    message: 'Publish rate limit exceeded for topic'
+                });
+            }
+            const payloadBytes = fromB64(payload);
+            const sequenceID = await store.publish({
+                senderDID,
+                topicID,
+                payload: payloadBytes
+            });
+            // Live-deliver to currently-connected subscribers (minus the sender).
+            const subscribers = await store.getSubscribers(topicID);
+            for (const recipientDID of subscribers){
+                if (recipientDID === senderDID) continue;
+                const client = registry.getClient(recipientDID);
+                if (client?.sendMessage != null) {
+                    client.sendMessage({
+                        sequenceID,
+                        senderDID,
+                        topicID,
+                        payload: payloadBytes
+                    });
+                }
+            }
+            return {
+                sequenceID
+            };
+        },
+        'hub/subscribe': async (ctx)=>{
+            const { topicID } = ctx.param;
+            const clientDID = getClientDID(ctx);
+            if (!await authorize(clientDID, 'subscribe', topicID)) {
+                throw new HandlerError({
+                    code: 'EK02',
+                    message: 'Not authorized to subscribe to topic'
+                });
+            }
+            await store.subscribe(clientDID, topicID);
+            return {
+                subscribed: true
+            };
+        },
+        'hub/unsubscribe': async (ctx)=>{
+            const { topicID } = ctx.param;
+            const clientDID = getClientDID(ctx);
+            await store.unsubscribe(clientDID, topicID);
+            return {
+                unsubscribed: true
+            };
+        },
+        'hub/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();
+            try {
+                registry.setReceiveWriter(clientDID, (message)=>{
+                    writer.write({
+                        sequenceID: message.sequenceID,
+                        senderDID: message.senderDID,
+                        topicID: message.topicID,
+                        payload: toB64(message.payload)
+                    }).catch(()=>{});
+                });
+                let cursor = after;
+                while(true){
+                    const result = await store.fetch({
+                        recipientDID: clientDID,
+                        after: cursor ?? undefined,
+                        limit: 50
+                    });
+                    for (const msg of result.messages){
+                        await writer.write({
+                            sequenceID: msg.sequenceID,
+                            senderDID: msg.senderDID,
+                            topicID: msg.topicID,
+                            payload: toB64(msg.payload)
+                        });
+                    }
+                    cursor = result.cursor;
+                    if (!result.hasMore) break;
+                }
+            } catch (error) {
+                registry.clearReceiveWriter(clientDID);
+                registry.unregisterIfIdle(clientDID);
+                reader.cancel().catch(()=>{});
+                writer.abort(error).catch(()=>{});
+                throw error;
+            }
+            void (async ()=>{
+                try {
+                    while(true){
+                        const { done, value } = await reader.read();
+                        if (done) break;
+                        if (value?.ack != null) {
+                            await store.ack({
+                                recipientDID: clientDID,
+                                sequenceIDs: value.ack
+                            });
+                        }
+                    }
+                } catch  {
+                // Channel closed
+                }
+            })();
+            return new Promise((resolve)=>{
+                ctx.signal.addEventListener('abort', ()=>{
+                    registry.clearReceiveWriter(clientDID);
+                    registry.unregisterIfIdle(clientDID);
+                    reader.cancel().catch(()=>{});
+                    writer.close().catch(()=>{});
+                    resolve(undefined);
+                }, {
+                    once: true
+                });
+            });
+        },
+        'hub/keypackage/upload': async (ctx)=>{
+            const { keyPackages } = ctx.param;
+            const clientDID = getClientDID(ctx);
+            await Promise.all(keyPackages.map((kp)=>store.storeKeyPackage(clientDID, kp)));
+            return {
+                stored: keyPackages.length
+            };
+        },
+        'hub/keypackage/fetch': async (ctx)=>{
+            const requesterDID = getClientDID(ctx);
+            assertKeyPackageFetchAllowed(requesterDID);
+            const { did, count } = ctx.param;
+            const cappedCount = Math.min(Math.max(count ?? 1, 1), fetchLimits.maxCount);
+            const keyPackages = await store.fetchKeyPackages(did, cappedCount);
+            return {
+                keyPackages
+            };
+        }
+    };
+}

package/lib/hub.d.ts

@@ -0,0 +1,48 @@
+import type { ServerTransportOf } from '@enkaku/protocol';
+import type { AccessRules, ResourceLimits, Server } from '@enkaku/server';
+import type { Identity } from '@kokuin/token';
+import { type HubProtocol, type HubStore } from '@kumiai/hub-protocol';
+import { type AuthorizeHook, type HubRateLimits, type KeyPackageFetchLimits } from './handlers.js';
+import { HubClientRegistry } from './registry.js';
+/**
+ * Default access rules: any authenticated DID may call hub procedures.
+ * The hub is a blind relay — per-procedure authorization (the `authorize`
+ * hook) happens in the handlers.
+ */
+export declare const DEFAULT_HUB_ACCESS_RULES: AccessRules;
+export type HubPurgeOptions = {
+    /** Interval between purge runs in milliseconds. Default: 3600000 (1 hour) */
+    interval?: number;
+    /** Age in seconds after which unacked stored messages are purged. Default: 604800 (7 days) */
+    olderThan?: number;
+};
+export type CreateHubParams = {
+    transport: ServerTransportOf<HubProtocol>;
+    store: HubStore;
+    /**
+     * Hub server identity. Required: all hub procedures derive the client DID
+     * from the verified `iss` of signed messages.
+     */
+    identity: Identity;
+    /** Access rules enforced by the server. Defaults to {@link DEFAULT_HUB_ACCESS_RULES}. */
+    accessRules?: AccessRules;
+    /** Per-procedure publish/subscribe authorization. Defaults to allow-any-authed. */
+    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}. */
+    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
+     * `longLivedProcedures` so open mailbox channels are exempt from
+     * `controllerTimeoutMs` and from the `maxConcurrentHandlers` cap.
+     */
+    limits?: Partial<ResourceLimits>;
+};
+export type HubInstance = {
+    registry: HubClientRegistry;
+    server: Server<HubProtocol>;
+};
+export declare function createHub(params: CreateHubParams): HubInstance;

package/lib/hub.js

@@ -0,0 +1,56 @@
+import { serve } from '@enkaku/server';
+import { hubProtocol } from '@kumiai/hub-protocol';
+import { createHandlers } from './handlers.js';
+import { HubClientRegistry } from './registry.js';
+/**
+ * Default access rules: any authenticated DID may call hub procedures.
+ * The hub is a blind relay — per-procedure authorization (the `authorize`
+ * hook) happens in the handlers.
+ */ export const DEFAULT_HUB_ACCESS_RULES = {
+    'hub/*': {
+        allow: true
+    }
+};
+export function createHub(params) {
+    const registry = new HubClientRegistry();
+    const handlers = createHandlers({
+        registry,
+        store: params.store,
+        authorize: params.authorize,
+        rateLimits: params.rateLimits,
+        keyPackageFetchLimits: params.keyPackageFetchLimits
+    });
+    const limits = {
+        ...params.limits,
+        longLivedProcedures: [
+            ...new Set([
+                ...params.limits?.longLivedProcedures ?? [],
+                'hub/receive'
+            ])
+        ]
+    };
+    const server = serve({
+        handlers,
+        protocol: hubProtocol,
+        transport: params.transport,
+        identity: params.identity,
+        accessRules: params.accessRules ?? DEFAULT_HUB_ACCESS_RULES,
+        limits
+    });
+    if (params.purge !== false) {
+        const interval = params.purge?.interval ?? 3_600_000;
+        const olderThan = params.purge?.olderThan ?? 604_800;
+        const purgeTimer = setInterval(()=>{
+            params.store.purge({
+                olderThan
+            }).catch(()=>{
+            // Purge failures are non-fatal; retried on the next interval
+            });
+        }, interval);
+        server.disposed.then(()=>clearInterval(purgeTimer));
+    }
+    return {
+        registry,
+        server
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+export type { AuthorizeAction, AuthorizeHook, 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';
+export { createMemoryStore, type MemoryStoreOptions } from './memoryStore.js';
+export { createRateLimiter, type RateLimitConfig, type RateLimiter } from './rateLimit.js';
+export type { ClientEntry } from './registry.js';
+export { HubClientRegistry } from './registry.js';

package/lib/index.js

@@ -0,0 +1,5 @@
+export { createHandlers, DEFAULT_KEYPACKAGE_FETCH_LIMITS, DEFAULT_RATE_LIMITS } from './handlers.js';
+export { createHub, DEFAULT_HUB_ACCESS_RULES } from './hub.js';
+export { createMemoryStore } from './memoryStore.js';
+export { createRateLimiter } from './rateLimit.js';
+export { HubClientRegistry } from './registry.js';

package/lib/memoryStore.d.ts

@@ -0,0 +1,12 @@
+import type { HubStore } from '@kumiai/hub-protocol';
+export type MemoryStoreOptions = {
+    /** Per-topic max retained messages; oldest are trimmed beyond this. Default 1000. */
+    maxDepth?: number;
+};
+/**
+ * In-memory implementation of HubStore for testing and development.
+ *
+ * Single message copy + per-subscriber delivery index + refcount GC. Recipients
+ * are resolved from the subscription table at publish time, never passed in.
+ */
+export declare function createMemoryStore(options?: MemoryStoreOptions): HubStore;

package/lib/memoryStore.js

@@ -0,0 +1,230 @@
+import { EventEmitter } from '@sozai/event';
+const DEFAULT_MAX_DEPTH = 1000;
+function formatSequenceID(counter) {
+    return String(counter).padStart(12, '0');
+}
+/**
+ * In-memory implementation of HubStore for testing and development.
+ *
+ * Single message copy + per-subscriber delivery index + refcount GC. Recipients
+ * are resolved from the subscription table at publish time, never passed in.
+ */ export function createMemoryStore(options = {}) {
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    let counter = 0;
+    const messages = new Map();
+    const deliveries = new Map();
+    const subscriptions = new Map();
+    const topicMessages = new Map();
+    const keyPackages = new Map();
+    const events = new EventEmitter();
+    // Remove a message entirely: every recipient delivery list, the topic log,
+    // and the message record.
+    function deleteMessage(sequenceID) {
+        const record = messages.get(sequenceID);
+        if (record == null) return;
+        for (const recipient of record.recipients){
+            const list = deliveries.get(recipient);
+            if (list != null) {
+                const index = list.indexOf(sequenceID);
+                if (index !== -1) list.splice(index, 1);
+            }
+        }
+        const topicLog = topicMessages.get(record.topicID);
+        if (topicLog != null) {
+            const index = topicLog.indexOf(sequenceID);
+            if (index !== -1) topicLog.splice(index, 1);
+            if (topicLog.length === 0) topicMessages.delete(record.topicID);
+        }
+        messages.delete(sequenceID);
+    }
+    // Drop one subscriber's delivery of a message; GC the message when its last
+    // recipient is gone (refcount → 0).
+    function removeDelivery(recipientDID, sequenceID) {
+        const list = deliveries.get(recipientDID);
+        if (list != null) {
+            const index = list.indexOf(sequenceID);
+            if (index !== -1) list.splice(index, 1);
+        }
+        const record = messages.get(sequenceID);
+        if (record != null) {
+            record.recipients.delete(recipientDID);
+            if (record.recipients.size === 0) {
+                deleteMessage(sequenceID);
+            }
+        }
+    }
+    return {
+        events,
+        async publish (params) {
+            counter++;
+            const sequenceID = formatSequenceID(counter);
+            // Recipients = current subscribers minus the sender. Zero recipients
+            // (no subscribers, or only the sender) → drop immediately, store nothing.
+            const subscribers = subscriptions.get(params.topicID);
+            const recipients = new Set();
+            if (subscribers != null) {
+                for (const did of subscribers){
+                    if (did !== params.senderDID) recipients.add(did);
+                }
+            }
+            if (recipients.size === 0) {
+                return sequenceID;
+            }
+            const record = {
+                sequenceID,
+                senderDID: params.senderDID,
+                topicID: params.topicID,
+                payload: params.payload,
+                recipients,
+                storedAt: Date.now()
+            };
+            messages.set(sequenceID, record);
+            for (const recipient of recipients){
+                let list = deliveries.get(recipient);
+                if (list == null) {
+                    list = [];
+                    deliveries.set(recipient, list);
+                }
+                list.push(sequenceID);
+            }
+            let topicLog = topicMessages.get(params.topicID);
+            if (topicLog == null) {
+                topicLog = [];
+                topicMessages.set(params.topicID, topicLog);
+            }
+            topicLog.push(sequenceID);
+            // Per-topic max-depth trim: drop oldest beyond the bound.
+            while(topicLog.length > maxDepth){
+                deleteMessage(topicLog[0]);
+            }
+            return sequenceID;
+        },
+        async fetch (params) {
+            if (params.ack != null && params.ack.length > 0) {
+                for (const sequenceID of params.ack){
+                    removeDelivery(params.recipientDID, sequenceID);
+                }
+            }
+            const recipientDeliveries = deliveries.get(params.recipientDID);
+            if (recipientDeliveries == null || recipientDeliveries.length === 0) {
+                return {
+                    messages: [],
+                    cursor: null
+                };
+            }
+            let startIndex = 0;
+            if (params.after != null) {
+                const afterIndex = recipientDeliveries.indexOf(params.after);
+                if (afterIndex !== -1) {
+                    startIndex = afterIndex + 1;
+                }
+            }
+            const available = recipientDeliveries.slice(startIndex);
+            const limit = params.limit ?? available.length;
+            const selected = available.slice(0, limit);
+            const hasMore = available.length > limit;
+            const resultMessages = [];
+            for (const sequenceID of selected){
+                const record = messages.get(sequenceID);
+                if (record != null) {
+                    resultMessages.push({
+                        sequenceID: record.sequenceID,
+                        senderDID: record.senderDID,
+                        topicID: record.topicID,
+                        payload: record.payload
+                    });
+                }
+            }
+            const cursor = resultMessages.length > 0 ? resultMessages[resultMessages.length - 1].sequenceID : null;
+            const result = {
+                messages: resultMessages,
+                cursor
+            };
+            if (hasMore) {
+                result.hasMore = true;
+            }
+            return result;
+        },
+        async ack (params) {
+            for (const sequenceID of params.sequenceIDs){
+                removeDelivery(params.recipientDID, sequenceID);
+            }
+        },
+        async purge (params) {
+            const threshold = Date.now() - params.olderThan * 1000;
+            const purgedIDs = [];
+            for (const [sequenceID, record] of messages){
+                if (record.storedAt <= threshold) {
+                    purgedIDs.push(sequenceID);
+                    deleteMessage(sequenceID);
+                }
+            }
+            if (purgedIDs.length > 0) {
+                await events.emit('purge', {
+                    sequenceIDs: purgedIDs
+                });
+            }
+            return purgedIDs;
+        },
+        async subscribe (subscriberDID, topicID) {
+            let subs = subscriptions.get(topicID);
+            if (subs == null) {
+                subs = new Set();
+                subscriptions.set(topicID, subs);
+            }
+            subs.add(subscriberDID);
+        },
+        async unsubscribe (subscriberDID, topicID) {
+            const subs = subscriptions.get(topicID);
+            if (subs != null) {
+                subs.delete(subscriberDID);
+                if (subs.size === 0) {
+                    subscriptions.delete(topicID);
+                }
+            }
+            // Drop this subscriber's pending deliveries for the topic.
+            const list = deliveries.get(subscriberDID);
+            if (list != null) {
+                for (const sequenceID of [
+                    ...list
+                ]){
+                    const record = messages.get(sequenceID);
+                    if (record != null && record.topicID === topicID) {
+                        removeDelivery(subscriberDID, sequenceID);
+                    }
+                }
+            }
+            // Last subscriber gone → drop the whole topic log immediately.
+            if (!subscriptions.has(topicID)) {
+                const topicLog = topicMessages.get(topicID);
+                if (topicLog != null) {
+                    for (const sequenceID of [
+                        ...topicLog
+                    ]){
+                        deleteMessage(sequenceID);
+                    }
+                }
+            }
+        },
+        async getSubscribers (topicID) {
+            const subs = subscriptions.get(topicID);
+            return subs == null ? [] : [
+                ...subs
+            ];
+        },
+        async storeKeyPackage (ownerDID, keyPackage) {
+            let packages = keyPackages.get(ownerDID);
+            if (packages == null) {
+                packages = [];
+                keyPackages.set(ownerDID, packages);
+            }
+            packages.push(keyPackage);
+        },
+        async fetchKeyPackages (ownerDID, count) {
+            const packages = keyPackages.get(ownerDID);
+            if (packages == null || packages.length === 0) return [];
+            const n = count ?? 1;
+            return packages.splice(0, n);
+        }
+    };
+}

package/lib/rateLimit.d.ts

@@ -0,0 +1,12 @@
+export type RateLimitConfig = {
+    /** Sustained refill rate in tokens per second. */
+    rate: number;
+    /** Maximum bucket capacity (burst). */
+    burst: number;
+};
+export type RateLimiter = {
+    /** Consumes a token if available, returning true; returns false otherwise. */
+    tryConsume(key: string): boolean;
+};
+/** Per-key token-bucket rate limiter. */
+export declare function createRateLimiter(config: RateLimitConfig): RateLimiter;

package/lib/rateLimit.js

@@ -0,0 +1,25 @@
+/** Per-key token-bucket rate limiter. */ export function createRateLimiter(config) {
+    const buckets = new Map();
+    return {
+        tryConsume (key) {
+            const now = Date.now();
+            let bucket = buckets.get(key);
+            if (bucket == null) {
+                bucket = {
+                    tokens: config.burst,
+                    lastRefill: now
+                };
+                buckets.set(key, bucket);
+            } else {
+                const elapsedSeconds = (now - bucket.lastRefill) / 1000;
+                bucket.tokens = Math.min(config.burst, bucket.tokens + elapsedSeconds * config.rate);
+                bucket.lastRefill = now;
+            }
+            if (bucket.tokens < 1) {
+                return false;
+            }
+            bucket.tokens -= 1;
+            return true;
+        }
+    };
+}

package/lib/registry.d.ts

@@ -0,0 +1,22 @@
+import type { StoredMessage } from '@kumiai/hub-protocol';
+export type ClientEntry = {
+    did: string;
+    sendMessage: ((message: StoredMessage) => void) | null;
+};
+/**
+ * Tracks online clients and their live receive-channel writers. Subscription
+ * state is durable in the store, not here — the registry only routes live
+ * fan-out to currently-connected subscribers.
+ */
+export declare class HubClientRegistry {
+    #private;
+    register(did: string): ClientEntry;
+    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;
+    getClient(did: string): ClientEntry | undefined;
+    isOnline(did: string): boolean;
+    isWriterBound(did: string): boolean;
+}

package/lib/registry.js

@@ -0,0 +1,51 @@
+/**
+ * Tracks online clients and their live receive-channel writers. Subscription
+ * state is durable in the store, not here — the registry only routes live
+ * fan-out to currently-connected subscribers.
+ */ export class HubClientRegistry {
+    #clients = new Map();
+    register(did) {
+        const existing = this.#clients.get(did);
+        if (existing != null) {
+            return existing;
+        }
+        const entry = {
+            did,
+            sendMessage: null
+        };
+        this.#clients.set(did, entry);
+        return entry;
+    }
+    unregister(did) {
+        this.#clients.delete(did);
+    }
+    /** Removes the entry only when no receive writer is bound. */ unregisterIfIdle(did) {
+        const entry = this.#clients.get(did);
+        if (entry != null && entry.sendMessage == null) {
+            this.#clients.delete(did);
+        }
+    }
+    setReceiveWriter(did, writer) {
+        const entry = this.#clients.get(did);
+        if (entry == null) return;
+        if (entry.sendMessage != null) {
+            throw new Error(`receive writer already bound for DID ${did}`);
+        }
+        entry.sendMessage = writer;
+    }
+    clearReceiveWriter(did) {
+        const entry = this.#clients.get(did);
+        if (entry != null) {
+            entry.sendMessage = null;
+        }
+    }
+    getClient(did) {
+        return this.#clients.get(did);
+    }
+    isOnline(did) {
+        return this.#clients.get(did)?.sendMessage != null;
+    }
+    isWriterBound(did) {
+        return this.#clients.get(did)?.sendMessage != null;
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@kumiai/hub-server",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Hub server for Enkaku E2EE group message routing",
+  "keywords": [
+    "hub",
+    "server",
+    "e2ee",
+    "routing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TairuFramework/kumiai",
+    "directory": "packages/hub-server"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@sozai/codec": "^0.1.0",
+    "@sozai/event": "^0.1.0",
+    "@enkaku/protocol": "^0.18.0",
+    "@enkaku/server": "^0.18.0",
+    "@sozai/stream": "^0.1.0",
+    "@kokuin/token": "^0.1.0",
+    "@kumiai/mls": "^0.1.0",
+    "@kumiai/hub-protocol": "^0.1.0"
+  },
+  "devDependencies": {
+    "@enkaku/client": "^0.18.0",
+    "@enkaku/transport": "^0.18.0"
+  },
+  "scripts": {
+    "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:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run",
+    "test": "pnpm run test:types && pnpm run test:unit"
+  }
+}