@kumiai/hub-server 0.7.0 → 0.8.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,
@@ -417,7 +430,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 +513,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;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kumiai/hub-server",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Hub server for Enkaku E2EE group message routing",
   "keywords": [
     "hub",
@@ -26,18 +26,18 @@
   ],
   "dependencies": {
     "@enkaku/protocol": "^0.21.0",
-    "@enkaku/server": "^0.21.1",
+    "@enkaku/server": "^0.21.2",
     "@kokuin/token": "^0.5.0",
+    "@kumiai/hub-protocol": "^0.8.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.1",
     "@enkaku/transport": "^0.21.0",
-    "@kumiai/hub-conformance": "^0.7.0",
-    "@kumiai/hub-wake": "^0.7.0"
+    "@kumiai/hub-conformance": "^0.8.0",
+    "@kumiai/hub-wake": "^0.8.0"
   },
   "publishConfig": {
     "access": "public"