@kumiai/hub-server 0.7.0 → 0.9.0

package/lib/handlers.d.ts

@@ -63,6 +63,13 @@ export type AuthorizeRequest = {
 } | {
     action: 'wake/unregister';
     did: string;
+} | {
+    action: 'receive';
+    did: string;
+} | {
+    action: 'receive/deliver';
+    did: string;
+    topicID: string;
 };
 /**
  * A plain `boolean` is shorthand for `{ allow: boolean }`, with no reason, code, or retry hint.
@@ -150,6 +157,12 @@ export declare const DEFAULT_KEYPACKAGE_FETCH_LIMITS: KeyPackageFetchLimits;
  * writer health. The default of 256 is safely above it.
  */
 export declare const DEFAULT_RECEIVE_BUFFER_LIMIT = 256;
+/**
+ * Default TTL (ms) for a receive channel's per-(did, topicID) delivery-authorization decision.
+ * Bounds how long an already-resolved allow is reused before the hook is re-consulted — i.e. the
+ * maximum window a removed member can keep draining a topic. See the receive handler's `gate`.
+ */
+export declare const DEFAULT_RECEIVE_AUTH_CACHE_TTL = 5000;
 export type CreateHandlersParams = {
     registry: HubClientRegistry;
     store: HubStore;
@@ -159,6 +172,12 @@ export type CreateHandlersParams = {
     /** Max frames queued-but-unflushed on a receive channel. See {@link DEFAULT_RECEIVE_BUFFER_LIMIT}
      * for the >= 50-frame-page floor this should respect. Default: 256 */
     receiveBufferLimit?: number;
+    /**
+     * TTL (ms) for the per-(did, topicID) receive delivery-authorization cache. `0` disables reuse
+     * (the hook is consulted for every frame). Non-finite or negative values fall back to
+     * {@link DEFAULT_RECEIVE_AUTH_CACHE_TTL}. Default: 5000.
+     */
+    receiveAuthCacheTTL?: number;
     /**
      * Called when a `HubStore` operation fails at a point where the hub deliberately does not fail
      * the request. Fire-and-forget; a throw here is swallowed.

package/lib/handlers.js

@@ -84,6 +84,11 @@ export const DEFAULT_KEYPACKAGE_FETCH_LIMITS = {
  * before awaiting, so a limit below 50 would trip the cap on the very first page regardless of
  * writer health. The default of 256 is safely above it.
  */ export const DEFAULT_RECEIVE_BUFFER_LIMIT = 256;
+/**
+ * Default TTL (ms) for a receive channel's per-(did, topicID) delivery-authorization decision.
+ * Bounds how long an already-resolved allow is reused before the hook is re-consulted — i.e. the
+ * maximum window a removed member can keep draining a topic. See the receive handler's `gate`.
+ */ export const DEFAULT_RECEIVE_AUTH_CACHE_TTL = 5000;
 function getClientDID(ctx) {
     const iss = ctx.message.payload.iss;
     if (typeof iss !== 'string' || iss.length === 0) {
@@ -105,6 +110,13 @@ function getClientDID(ctx) {
     }
     throw error;
 }
+function resolveReceiveAuthCacheTTL(value) {
+    if (value === undefined || !Number.isFinite(value) || value < 0) {
+        return DEFAULT_RECEIVE_AUTH_CACHE_TTL;
+    }
+    return value // 0 allowed: no reuse
+    ;
+}
 function toReceiveFrame(message) {
     return {
         sequenceID: message.sequenceID,
@@ -134,6 +146,7 @@ export function createHandlers(params) {
     const didLimiter = createRateLimiter(rateLimits.perDID);
     const topicLimiter = createRateLimiter(rateLimits.perTopic);
     const receiveBufferLimit = params.receiveBufferLimit ?? DEFAULT_RECEIVE_BUFFER_LIMIT;
+    const receiveAuthCacheTTL = resolveReceiveAuthCacheTTL(params.receiveAuthCacheTTL);
     const storeErrorReporter = createStoreErrorReporter(params.onStoreError);
     const fetchLimits = {
         ...DEFAULT_KEYPACKAGE_FETCH_LIMITS,
@@ -273,7 +286,9 @@ export function createHandlers(params) {
                 // retry returns `deduped`, and the block below is gated on `!deduped`.
                 let subscribers;
                 try {
-                    subscribers = await store.getSubscribers(topicID);
+                    subscribers = await store.getSubscribers({
+                        topicID
+                    });
                 } catch (error) {
                     storeErrorReporter({
                         method: 'getSubscribers',
@@ -406,7 +421,10 @@ export function createHandlers(params) {
                 });
             }
             try {
-                await store.unsubscribe(clientDID, topicID);
+                await store.unsubscribe({
+                    subscriberDID: clientDID,
+                    topicID
+                });
             } catch (error) {
                 rethrowAsHandlerError(error);
             }
@@ -417,7 +435,43 @@ export function createHandlers(params) {
         'hub/v1/receive': async (ctx)=>{
             const clientDID = getClientDID(ctx);
             const { after } = ctx.param ?? {};
+            const connectDecision = normalizeAuthorizeDecision(await authorize({
+                action: 'receive',
+                did: clientDID
+            }));
+            if (!connectDecision.allow) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.authorizationDenied,
+                    message: connectDecision.reason ?? 'Not authorized to receive'
+                });
+            }
             registry.register(clientDID);
+            // Per-(did, topicID) delivery-authorization cache, local to this channel (torn down with it).
+            // Both allow AND deny are cached for the TTL, so re-grant is not immediate: a topic that was
+            // just re-authorized keeps being denied for up to `receiveAuthCacheTTL` ms, and a frame denied
+            // in-session redelivers on the recipient's next connect.
+            const authCache = new Map();
+            const gate = async (topicID)=>{
+                const key = `${clientDID}${topicID}`;
+                const now = Date.now();
+                const cached = authCache.get(key);
+                if (cached != null && cached.expiresAt > now) return cached.allow;
+                const decision = normalizeAuthorizeDecision(await authorize({
+                    action: 'receive/deliver',
+                    did: clientDID,
+                    topicID
+                }));
+                if (receiveAuthCacheTTL > 0) {
+                    // Expiry is measured from when the decision is stored, AFTER the hook resolves — so the
+                    // reuse window excludes the hook's own execution time. Re-read the clock here rather than
+                    // reusing `now` (captured before the await).
+                    authCache.set(key, {
+                        allow: decision.allow,
+                        expiresAt: Date.now() + receiveAuthCacheTTL
+                    });
+                }
+                return decision.allow;
+            };
             const writer = ctx.writable.getWriter();
             const reader = ctx.readable.getReader();
             let endEvicted;
@@ -464,6 +518,7 @@ export function createHandlers(params) {
                 writeChain = writeChain.then(async ()=>{
                     if (tornDown) return;
                     try {
+                        if (!await gate(frame.topicID)) return; // denied: skip, leave pending, no ack
                         await writer.ready;
                         await writer.write(frame);
                         if (frame.sequenceID > lastServed) lastServed = frame.sequenceID;
@@ -634,9 +689,16 @@ export function createHandlers(params) {
             // The last-resort path has no cap to cross: the slot is one entry, replaced in place.
             try {
                 if (lastResortPackage != null) {
-                    await store.storeLastResortKeyPackage(clientDID, lastResortPackage);
+                    await store.storeLastResortKeyPackage({
+                        ownerDID: clientDID,
+                        keyPackage: lastResortPackage
+                    });
                 } else {
-                    await Promise.all(keyPackages.map((kp)=>store.storeKeyPackage(clientDID, kp, notAfter)));
+                    await Promise.all(keyPackages.map((kp)=>store.storeKeyPackage({
+                            ownerDID: clientDID,
+                            keyPackage: kp,
+                            notAfter
+                        })));
                 }
             } catch (error) {
                 rethrowAsHandlerError(error);
@@ -695,7 +757,9 @@ export function createHandlers(params) {
                 let lastResort = null;
                 let readFailure;
                 try {
-                    lastResort = await store.fetchLastResortKeyPackage(targetDID);
+                    lastResort = await store.fetchLastResortKeyPackage({
+                        ownerDID: targetDID
+                    });
                 } catch (error) {
                     readFailure = error;
                 }
@@ -728,7 +792,10 @@ export function createHandlers(params) {
             // the request when nothing has been consumed and there is therefore nothing to lose.
             let consumed;
             try {
-                consumed = await store.fetchKeyPackages(targetDID, cappedCount);
+                consumed = await store.fetchKeyPackages({
+                    ownerDID: targetDID,
+                    count: cappedCount
+                });
             } catch (error) {
                 rethrowAsHandlerError(error);
             }
@@ -737,7 +804,9 @@ export function createHandlers(params) {
             };
             let lastResort = null;
             try {
-                lastResort = await store.fetchLastResortKeyPackage(targetDID);
+                lastResort = await store.fetchLastResortKeyPackage({
+                    ownerDID: targetDID
+                });
             } catch (error) {
                 // Nothing consumed, so nothing is lost by surfacing it. Otherwise the top-up was a bonus
                 // the caller never paid for: hand back what the store has already given up.
@@ -784,8 +853,12 @@ export function createHandlers(params) {
                 // Two independent reads for one owner: concurrent, since neither informs the other.
                 ;
                 [count, stored] = await Promise.all([
-                    store.countKeyPackages(clientDID),
-                    store.fetchLastResortKeyPackage(clientDID)
+                    store.countKeyPackages({
+                        ownerDID: clientDID
+                    }),
+                    store.fetchLastResortKeyPackage({
+                        ownerDID: clientDID
+                    })
                 ]);
             } catch (error) {
                 rethrowAsHandlerError(error);

package/lib/hub.d.ts

@@ -30,7 +30,12 @@ export type CreateHubParams = {
     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. */
+    /**
+     * Per-action authorization hook. Consulted for publish, subscribe, topic/fetch, keypackage/*,
+     * wake/*, and receive — the coarse `receive` gate at channel open plus a per-frame
+     * `receive/deliver` gate by topic (see {@link CreateHubParams.receiveAuthCacheTTL}). Defaults to
+     * allow-any-authed.
+     */
     authorize?: AuthorizeHook;
     /** Publish rate limits. Merged over {@link DEFAULT_RATE_LIMITS}. */
     rateLimits?: Partial<HubRateLimits>;
@@ -39,6 +44,11 @@ export type CreateHubParams = {
      * {@link DEFAULT_KEYPACKAGE_FETCH_LIMITS}.
      */
     keyPackageFetchLimits?: Partial<KeyPackageFetchLimits>;
+    /**
+     * TTL (ms) for the per-(did, topicID) receive delivery-authorization cache. `0` consults the
+     * hook for every frame. Forwarded to {@link createHandlers}. Default: 5000.
+     */
+    receiveAuthCacheTTL?: number;
     /**
      * Called when a `HubStore` operation fails where the hub deliberately does not fail the
      * request. Forwarded to {@link createHandlers} and used by the purge timer. Fire-and-forget.

package/lib/hub.js

@@ -34,6 +34,7 @@ export function createHub(params) {
         authorize: params.authorize,
         rateLimits: params.rateLimits,
         keyPackageFetchLimits: params.keyPackageFetchLimits,
+        receiveAuthCacheTTL: params.receiveAuthCacheTTL,
         onStoreError: storeErrorReporter,
         wake: params.wake == null ? undefined : {
             registry: params.wake.registry,

package/lib/memoryStore.js

@@ -360,7 +360,7 @@ function isLive(entry, nowSeconds) {
             }
             ownTopics.add(params.topicID);
         },
-        async unsubscribe (subscriberDID, topicID) {
+        async unsubscribe ({ subscriberDID, topicID }) {
             const subscribers = subscriptions.get(topicID);
             if (subscribers != null) {
                 subscribers.delete(subscriberDID);
@@ -386,13 +386,13 @@ function isLive(entry, nowSeconds) {
                 }
             }
         },
-        async getSubscribers (topicID) {
+        async getSubscribers ({ topicID }) {
             const subscribers = subscriptions.get(topicID);
             return subscribers == null ? [] : [
                 ...subscribers.keys()
             ];
         },
-        async storeKeyPackage (ownerDID, keyPackage, notAfter) {
+        async storeKeyPackage ({ ownerDID, keyPackage, notAfter }) {
             let packages = keyPackages.get(ownerDID);
             if (packages == null) {
                 packages = [];
@@ -417,7 +417,7 @@ function isLive(entry, nowSeconds) {
                 } : {}
             });
         },
-        async fetchKeyPackages (ownerDID, count) {
+        async fetchKeyPackages ({ ownerDID, count }) {
             const packages = keyPackages.get(ownerDID);
             if (packages == null || packages.length === 0) return [];
             const nowSeconds = Math.floor(Date.now() / 1000);
@@ -432,16 +432,16 @@ function isLive(entry, nowSeconds) {
             }
             return served;
         },
-        async countKeyPackages (ownerDID) {
+        async countKeyPackages ({ ownerDID }) {
             const packages = keyPackages.get(ownerDID);
             if (packages == null) return 0;
             const nowSeconds = Math.floor(Date.now() / 1000);
             return packages.filter((entry)=>isLive(entry, nowSeconds)).length;
         },
-        async storeLastResortKeyPackage (ownerDID, keyPackage) {
+        async storeLastResortKeyPackage ({ ownerDID, keyPackage }) {
             lastResortKeyPackages.set(ownerDID, keyPackage);
         },
-        async fetchLastResortKeyPackage (ownerDID) {
+        async fetchLastResortKeyPackage ({ ownerDID }) {
             // No splice, ever. Reuse is the point here — this package is marked last-resort in MLS, so
             // serving it again is by design rather than the init-key reuse `fetchKeyPackages` avoids.
             return lastResortKeyPackages.get(ownerDID) ?? null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kumiai/hub-server",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Hub server for Enkaku E2EE group message routing",
   "keywords": [
     "hub",
@@ -25,19 +25,19 @@
     "lib/*"
   ],
   "dependencies": {
-    "@enkaku/protocol": "^0.21.0",
-    "@enkaku/server": "^0.21.1",
+    "@enkaku/protocol": "^0.21.1",
+    "@enkaku/server": "^0.21.2",
     "@kokuin/token": "^0.5.0",
+    "@kumiai/hub-protocol": "^0.9.0",
     "@sozai/codec": "^0.4.0",
     "@sozai/event": "^0.1.3",
-    "@sozai/log": "^0.3.1",
-    "@kumiai/hub-protocol": "^0.7.0"
+    "@sozai/log": "^0.3.1"
   },
   "devDependencies": {
-    "@enkaku/client": "^0.21.0",
+    "@enkaku/client": "^0.21.2",
     "@enkaku/transport": "^0.21.0",
-    "@kumiai/hub-conformance": "^0.7.0",
-    "@kumiai/hub-wake": "^0.7.0"
+    "@kumiai/hub-conformance": "^0.9.0",
+    "@kumiai/hub-wake": "^0.9.0"
   },
   "publishConfig": {
     "access": "public"