@kumiai/hub-server 0.6.0 → 0.7.0

package/README.md

@@ -31,10 +31,13 @@ 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 seven actions, but only
-`publish` and `subscribe` are dispatched today. The default allows any authenticated DID.
+`authorize(request)` hook decides the rest. It takes one discriminated `AuthorizeRequest` — narrow
+on `request.action` — and returns `AuthorizeDecision`, either a boolean or
+`{ allow, reason?, code?, retryAfterMs? }`. `AuthorizeRequest` names nine actions, of which only
+`unsubscribe` is not dispatched today; the two `wake/*` actions gate push registration, which is the
+one durable per-device identifier the hub stores. The default allows any authenticated DID, and a
+hook should allow any action it does not recognise, so that a hook written before a variant shipped
+does not start refusing a procedure that used to be ungated.
 
 ## Durable subscription, ephemeral connection
 

package/lib/handlers.d.ts

@@ -1,11 +1,12 @@
 import { type ProcedureHandlers } from '@enkaku/server';
-import type { HubProtocol, HubStore } from '@kumiai/hub-protocol';
+import type { HubProtocol, HubStore, WakeRegistry } from '@kumiai/hub-protocol';
 import { type RateLimitConfig } from './rateLimit.js';
 import type { HubClientRegistry } from './registry.js';
+import type { WakeDispatcher } from './wake.js';
 /**
- * A single request to authorize. All seven 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.
+ * A single request to authorize. All nine variants ship even though `unsubscribe` is not yet
+ * dispatched: the union is the exhaustive-switch surface a host's own `switch (req.action)` closes
+ * over, and widening it after a release is a break for every host that closed over it.
  *
  * 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
@@ -43,6 +44,25 @@ export type AuthorizeRequest = {
 } | {
     action: 'keypackage/status';
     did: string;
+}
+/**
+ * A device registering a push endpoint. `kind` (the opaque sender tag) and `expiresAt` (the
+ * caller-supplied registration lifetime cap, when given) are the only details a host can usefully
+ * gate on — `endpoint`, `publicKey` and `authSecret` are deliberately absent, since a hook that
+ * saw them would be a second place the endpoint gets read, and the hub's rule is that it never
+ * interprets one.
+ *
+ * This is the durable cross-group per-device identifier wake introduces, so it is the one a host
+ * is most likely to want a say over.
+ */
+ | {
+    action: 'wake/register';
+    did: string;
+    kind: string;
+    expiresAt?: number;
+} | {
+    action: 'wake/unregister';
+    did: string;
 };
 /**
  * A plain `boolean` is shorthand for `{ allow: boolean }`, with no reason, code, or retry hint.
@@ -89,6 +109,12 @@ export type HubStoreErrorEvent = {
     method: 'getSubscribers';
     topicID: string;
     error: unknown;
+}
+/** The DID whose wake dispatch (send, or the registry read/delete around it) failed. */
+ | {
+    method: 'wake';
+    did: string;
+    error: unknown;
 };
 export type HubStoreErrorHook = (event: HubStoreErrorEvent) => void;
 /**
@@ -141,5 +167,13 @@ export type CreateHandlersParams = {
      * empty handler to silence it deliberately.
      */
     onStoreError?: HubStoreErrorHook;
+    /**
+     * Wake support. Absent: both wake procedures refuse. The registry is separate from the
+     * dispatcher because the handlers only ever store and remove; sending is the dispatcher's.
+     */
+    wake?: {
+        registry: WakeRegistry;
+        dispatcher?: WakeDispatcher;
+    };
 };
 export declare function createHandlers(params: CreateHandlersParams): ProcedureHandlers<HubProtocol>;

package/lib/handlers.js

@@ -1,5 +1,5 @@
 import { HandlerError } from '@enkaku/server';
-import { HUB_ERROR_CODES, hubErrorCodeOf, InvalidPayloadError, KeyPackageFetchLimitError, keyPackageDigest } from '@kumiai/hub-protocol';
+import { HUB_ERROR_CODES, hubErrorCodeOf, InvalidPayloadError, KeyPackageFetchLimitError, keyPackageDigest, wakeRecipientKeyProblem } from '@kumiai/hub-protocol';
 import { fromB64, toB64 } from '@sozai/codec';
 import { getReporter } from '@sozai/log';
 import { createRateLimiter } from './rateLimit.js';
@@ -21,7 +21,8 @@ function normalizeAuthorizeDecision(decision) {
     fetchLastResortKeyPackage: 'The fetch returned what the pool could serve, without the last-resort top-up. A read that ' + 'keeps failing means the availability floor the last-resort slot exists to provide is absent, ' + 'and joins fail downstream at the inviter with no signal here.',
     ack: 'The frame stays pending and the client re-acks on the next round. An ack that keeps failing ' + 'redelivers every frame forever.',
     purge: 'Retried on the next interval. A purge that keeps failing means the store grows without bound.',
-    getSubscribers: 'The frame is committed and queued, but the live push to connected subscribers was skipped: ' + 'each of them stops receiving new frames until it reconnects. A getSubscribers that keeps ' + 'failing means the hub has silently degraded from push to pull for every publish.'
+    getSubscribers: 'The frame is committed and queued, but the live push to connected subscribers was skipped: ' + 'each of them stops receiving new frames until it reconnects. A getSubscribers that keeps ' + 'failing means the hub has silently degraded from push to pull for every publish.',
+    wake: 'The offline device was not pinged for this frame. It still redelivers on the next reconnect ' + '(store-and-forward), so nothing is lost — but a wake that keeps failing means the device ' + 'stays asleep until something else wakes it.'
 };
 const reportStoreError = getReporter([
     'kumiai',
@@ -36,6 +37,7 @@ const reportStoreError = getReporter([
             return ` on topic ${event.topicID}`;
         case 'ack':
         case 'fetchLastResortKeyPackage':
+        case 'wake':
             return ` for ${event.did}`;
     }
 }
@@ -293,6 +295,29 @@ export function createHandlers(params) {
                             payload: payloadBytes,
                             ...logPosition
                         });
+                    } else {
+                        // No live channel: the frame is durably queued, so all that is missing is a nudge to
+                        // come and get it. Both retention classes wake — a commit-lane frame is log-class, and
+                        // a membership change is exactly what a sleeping device must learn.
+                        //
+                        // Guarded even though `notify` is documented never to throw: `dispatcher` is
+                        // caller-injectable (`CreateHandlersParams.wake.dispatcher`), and a misbehaving
+                        // third-party implementation must not abort this loop mid-way — that would cost live
+                        // delivery to every subscriber still to come, for a publish whose append already
+                        // committed.
+                        try {
+                            params.wake?.dispatcher?.notify({
+                                did: recipientDID,
+                                topicID,
+                                sequenceID
+                            });
+                        } catch (error) {
+                            storeErrorReporter({
+                                method: 'wake',
+                                did: recipientDID,
+                                error
+                            });
+                        }
                     }
                 }
             }
@@ -480,6 +505,8 @@ export function createHandlers(params) {
                 receiveToken = token;
                 // After the bind, so the lane is never unheld between the two.
                 evicted?.();
+                // The device is draining; a trailing summary would be noise it has already outrun.
+                params.wake?.dispatcher?.online(clientDID);
                 // Drain the backlog. Await each page so lastServed is exact before the flush.
                 let cursor = after;
                 while(!tornDown){
@@ -767,6 +794,111 @@ export function createHandlers(params) {
                 count,
                 lastResort: stored == null ? null : keyPackageDigest(stored)
             };
+        },
+        'hub/v1/wake/register': async (ctx)=>{
+            const clientDID = getClientDID(ctx);
+            const wake = params.wake;
+            if (wake == null) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.wakeNotSupported,
+                    message: 'This hub does not support wake notifications'
+                });
+            }
+            // After the not-supported refusal, before the rate limit — the order every enforced variant
+            // uses. Configuration is answered first because a hub with no wake support has nothing for a
+            // host to have an opinion about.
+            const decision = normalizeAuthorizeDecision(await authorize({
+                action: 'wake/register',
+                did: clientDID,
+                kind: ctx.param.kind,
+                expiresAt: ctx.param.expiresAt
+            }));
+            if (!decision.allow) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.authorizationDenied,
+                    message: decision.reason ?? 'Not authorized to register a wake endpoint'
+                });
+            }
+            if (!didLimiter.tryConsume(clientDID)) {
+                throw new HandlerError({
+                    code: 'EK01',
+                    message: 'Wake rate limit exceeded for DID'
+                });
+            }
+            // The param schema bounds the length (`minLength: 1`, `maxLength: 128`/`64`) but not the
+            // shape, which accepts key material the hub can never seal to. Storing it answers
+            // `registered: true` and then fails inside every single seal — one error per frame, forever,
+            // since a seal failure is not a `gone` verdict and nothing removes the entry. The device
+            // believes it is reachable and is never woken.
+            // The rule itself lives in hub-protocol next to RFC 8291, so the hub needs no curve of its
+            // own to know that a 65-byte value off the curve fails exactly as a 33-byte one does.
+            const keyProblem = wakeRecipientKeyProblem({
+                publicKey: ctx.param.publicKey,
+                authSecret: ctx.param.authSecret
+            });
+            if (keyProblem != null) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.invalidPayload,
+                    message: `Wake ${keyProblem}`
+                });
+            }
+            try {
+                await wake.registry.put({
+                    // The DID is the verified issuer, never a wire field — otherwise any member could
+                    // redirect another member's wakes to an endpoint they control.
+                    did: clientDID,
+                    kind: ctx.param.kind,
+                    endpoint: ctx.param.endpoint,
+                    publicKey: ctx.param.publicKey,
+                    authSecret: ctx.param.authSecret,
+                    ...ctx.param.expiresAt != null ? {
+                        expiresAt: ctx.param.expiresAt
+                    } : {}
+                });
+            } catch (error) {
+                rethrowAsHandlerError(error);
+            }
+            return {
+                registered: true
+            };
+        },
+        'hub/v1/wake/unregister': async (ctx)=>{
+            const clientDID = getClientDID(ctx);
+            const wake = params.wake;
+            if (wake == null) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.wakeNotSupported,
+                    message: 'This hub does not support wake notifications'
+                });
+            }
+            const decision = normalizeAuthorizeDecision(await authorize({
+                action: 'wake/unregister',
+                did: clientDID
+            }));
+            if (!decision.allow) {
+                throw new HandlerError({
+                    code: HUB_ERROR_CODES.authorizationDenied,
+                    message: decision.reason ?? 'Not authorized to unregister a wake endpoint'
+                });
+            }
+            // Matches `register` above and the subscribe/unsubscribe pair: both halves of a pair cost
+            // the same, or the uncounted half is the one an abusive caller uses.
+            if (!didLimiter.tryConsume(clientDID)) {
+                throw new HandlerError({
+                    code: 'EK01',
+                    message: 'Wake rate limit exceeded for DID'
+                });
+            }
+            let existed;
+            try {
+                existed = await wake.registry.get(clientDID) != null;
+                await wake.registry.delete(clientDID);
+            } catch (error) {
+                rethrowAsHandlerError(error);
+            }
+            return {
+                unregistered: existed
+            };
         }
     };
 }

package/lib/hub.d.ts

@@ -1,7 +1,7 @@
 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 { HubProtocol, HubStore, WakeRegistry, WakeSender } from '@kumiai/hub-protocol';
 import { type AuthorizeHook, type HubRateLimits, type HubStoreErrorHook, type KeyPackageFetchLimits } from './handlers.js';
 import { HubClientRegistry } from './registry.js';
 /**
@@ -52,6 +52,17 @@ export type CreateHubParams = {
      * `controllerTimeoutMs` and from the `maxConcurrentHandlers` cap.
      */
     limits?: Partial<ResourceLimits>;
+    /**
+     * Wake notifications. Absent: `hub/v1/wake/*` refuse with `WakeNotSupportedError` — refusing is
+     * the only honest answer, since accepting a registration the hub will never act on leaves the
+     * device believing it is reachable.
+     */
+    wake?: {
+        registry: WakeRegistry;
+        sender: WakeSender;
+        /** Coalescing window in milliseconds. Default: 10 000. */
+        debounceMs?: number;
+    };
 };
 export type HubInstance = {
     registry: HubClientRegistry;

package/lib/hub.js

@@ -2,6 +2,7 @@ import { serve } from '@enkaku/server';
 import { hubProtocol } from '@kumiai/hub-protocol';
 import { createHandlers, createStoreErrorReporter } from './handlers.js';
 import { HubClientRegistry } from './registry.js';
+import { createWakeDispatcher } from './wake.js';
 /**
  * Default access rules: any authenticated DID may call hub procedures.
  * The hub is a blind relay — per-procedure authorization (the `authorize`
@@ -17,13 +18,27 @@ export function createHub(params) {
     // wrapper delegates to this instance rather than building a second one from the same hook —
     // which matters the moment a reporter holds state, as the throttling the README names would.
     const storeErrorReporter = createStoreErrorReporter(params.onStoreError);
+    const wakeDispatcher = params.wake == null ? undefined : createWakeDispatcher({
+        registry: params.wake.registry,
+        sender: params.wake.sender,
+        debounceMs: params.wake.debounceMs,
+        onError: ({ did, error })=>storeErrorReporter({
+                method: 'wake',
+                did,
+                error
+            })
+    });
     const handlers = createHandlers({
         registry,
         store: params.store,
         authorize: params.authorize,
         rateLimits: params.rateLimits,
         keyPackageFetchLimits: params.keyPackageFetchLimits,
-        onStoreError: storeErrorReporter
+        onStoreError: storeErrorReporter,
+        wake: params.wake == null ? undefined : {
+            registry: params.wake.registry,
+            dispatcher: wakeDispatcher
+        }
     });
     const limits = {
         ...params.limits,
@@ -58,6 +73,9 @@ export function createHub(params) {
         }, interval);
         server.disposed.then(()=>clearInterval(purgeTimer));
     }
+    if (wakeDispatcher != null) {
+        server.disposed.then(()=>wakeDispatcher.dispose());
+    }
     return {
         registry,
         server

package/lib/index.d.ts

@@ -6,3 +6,4 @@ 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';
+export { createWakeDispatcher, type WakeDispatcher, type WakeDispatcherParams, type WakeNotifyParams, } from './wake.js';

package/lib/index.js

@@ -3,3 +3,4 @@ export { createHub, DEFAULT_HUB_ACCESS_RULES } from './hub.js';
 export { createMemoryStore } from './memoryStore.js';
 export { createRateLimiter } from './rateLimit.js';
 export { HubClientRegistry } from './registry.js';
+export { createWakeDispatcher } from './wake.js';

package/lib/wake.d.ts

@@ -0,0 +1,33 @@
+import { type WakeRegistry, type WakeSender } from '@kumiai/hub-protocol';
+export type WakeDispatcherParams = {
+    registry: WakeRegistry;
+    sender: WakeSender;
+    /** Coalescing window in milliseconds. Default: 10 000. */
+    debounceMs?: number;
+    /** Reports a transient send failure or a throwing sender. Fire-and-forget. */
+    onError?: (params: {
+        did: string;
+        error: unknown;
+    }) => void;
+};
+export type WakeNotifyParams = {
+    did: string;
+    topicID: string;
+    sequenceID: string;
+};
+export type WakeDispatcher = {
+    /** A frame was queued for an OFFLINE subscriber. Never throws, never awaited by the caller. */
+    notify(params: WakeNotifyParams): void;
+    /** The device bound a receive channel: drop any pending trailing ping. */
+    online(did: string): void;
+    dispose(): void;
+};
+/**
+ * Coalesces wake pings per DID on a LEADING edge: the first frame pings immediately, then a window
+ * opens and everything inside it collapses into one trailing summary.
+ *
+ * Leading rather than trailing because the timer map is in-process. A hub restart drops pending
+ * windows; on a leading edge that loses at most a summary, whereas trailing-only would lose the
+ * notification itself every time a restart landed inside a window.
+ */
+export declare function createWakeDispatcher(params: WakeDispatcherParams): WakeDispatcher;

package/lib/wake.js

@@ -0,0 +1,112 @@
+import { sealWakeHint } from '@kumiai/hub-protocol';
+import { fromB64U } from '@sozai/codec';
+const DEFAULT_DEBOUNCE_MS = 10_000;
+/**
+ * Coalesces wake pings per DID on a LEADING edge: the first frame pings immediately, then a window
+ * opens and everything inside it collapses into one trailing summary.
+ *
+ * Leading rather than trailing because the timer map is in-process. A hub restart drops pending
+ * windows; on a leading edge that loses at most a summary, whereas trailing-only would lose the
+ * notification itself every time a restart landed inside a window.
+ */ export function createWakeDispatcher(params) {
+    const debounceMs = params.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const pending = new Map();
+    let disposed = false;
+    function report(did, error) {
+        try {
+            params.onError?.({
+                did,
+                error
+            });
+        } catch  {
+        // A reporter that throws must not take the dispatcher with it.
+        }
+    }
+    function send(did, topicID, sequenceID, count) {
+        // Deliberately not awaited: a slow or hanging provider must never delay the publish fan-out
+        // this is called from.
+        void (async ()=>{
+            try {
+                const registration = await params.registry.get(did);
+                if (registration == null) return;
+                const body = sealWakeHint({
+                    topicID,
+                    sequenceID,
+                    count
+                }, {
+                    publicKey: fromB64U(registration.publicKey),
+                    authSecret: fromB64U(registration.authSecret)
+                });
+                const verdict = await params.sender.send({
+                    registration,
+                    body
+                });
+                switch(verdict){
+                    case 'delivered':
+                        break;
+                    case 'gone':
+                        await params.registry.delete(did);
+                        break;
+                    case 'retry':
+                        report(did, new Error('Wake send failed transiently'));
+                        break;
+                    default:
+                        // Exhaustive over WakeVerdict: a future verdict must be handled explicitly here rather
+                        // than silently falling through as 'delivered'.
+                        verdict;
+                }
+            } catch (error) {
+                report(did, error);
+            }
+        })();
+    }
+    function openWindow(did) {
+        const entry = {
+            timer: setTimeout(()=>{
+                const current = pending.get(did);
+                pending.delete(did);
+                if (current?.latest == null) return;
+                send(did, current.latest.topicID, current.latest.sequenceID, current.count);
+                // Traffic is still flowing, so a fresh window opens behind the summary rather than letting
+                // the next frame ping immediately and undo the coalescing.
+                pending.set(did, openWindow(did));
+            }, debounceMs),
+            latest: null,
+            count: 0
+        };
+        // A pending wake must never hold a process open by itself. `.unref` is a Node timer method
+        // absent from the DOM `Timeout` type; it only typechecks here because this package's
+        // tsconfig.json (unlike its siblings') sets `"types": ["node"]`. If hub-server is ever
+        // aligned to drop that, this line needs `(entry.timer as NodeJS.Timeout).unref?.()` or an
+        // equivalent cast.
+        entry.timer.unref?.();
+        return entry;
+    }
+    return {
+        notify ({ did, topicID, sequenceID }) {
+            if (disposed) return;
+            const entry = pending.get(did);
+            if (entry == null) {
+                pending.set(did, openWindow(did));
+                send(did, topicID, sequenceID, 1);
+                return;
+            }
+            entry.latest = {
+                topicID,
+                sequenceID
+            };
+            entry.count += 1;
+        },
+        online (did) {
+            const entry = pending.get(did);
+            if (entry == null) return;
+            clearTimeout(entry.timer);
+            pending.delete(did);
+        },
+        dispose () {
+            disposed = true;
+            for (const entry of pending.values())clearTimeout(entry.timer);
+            pending.clear();
+        }
+    };
+}

package/package.json

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