@kumiai/hub-server 0.12.2 → 0.13.1

package/README.md

@@ -5,8 +5,8 @@ client registry for push fan-out, and an in-memory `HubStore` for development an
 
 ## Exports
 
-- `createHub({ transport, store, identity, ... })` — the whole server: handlers, registry, access
-  rules, rate limits, and an optional scheduled purge. Returns `{ registry, server }`.
+- `createHub({ transport, store, identity, ... })` -- handlers, registry, access rules, rate limits and an optional scheduled purge.
+  Returns `{ registry, server, dispose }`.
 - `createHandlers({ registry, store, ... })` — the handlers alone, for a host assembling its own
   server.
 - `createMemoryStore({ maxDepth?, retention? })` — an in-memory `HubStore`. For testing and
@@ -160,3 +160,19 @@ rather than passing silently. Pass an empty handler to silence it deliberately.
 There is no throttling: a permanently broken store reports per request. logtape ships
 `getThrottlingFilter`, so rate control belongs in the app's sink configuration where an operator
 can tune it.
+
+## Invocation hooks and attribution
+
+`createHub` accepts optional `onInvocation`, forwarded to the Enkaku server for authenticated invocation context and delegation verification.
+`createHub` and `createHandlers` accept optional `resolveAttribution({ message, senderDID })`.
+The resolver can return `HubAttribution`, `undefined`, or a promise of either.
+
+Without a resolver result, publishes use `{ account: senderDID, actor: senderDID, via: 'direct' }`.
+The sender DID still comes from the verified signature.
+A resolver supplies host accounting metadata rather than changing the authenticated sender or authorisation rules.
+Only a verified delegation yields `via: 'delegated'`. A claimed subject alone does not prove delegation.
+Hosts can use `onInvocation` to verify delegation before resolving attribution.
+
+The store receives the resolved attribution with the publish.
+The SQL stores persist it. The development memory store reports publish outcomes but does not implement occupancy sampling.
+Unconfigured hooks preserve existing routing, retention and delivery behaviour.

package/lib/handlers.d.ts

@@ -1,5 +1,5 @@
 import { type ProcedureHandlers } from '@enkaku/server';
-import type { HubProtocol, HubStore, WakeRegistry } from '@kumiai/hub-protocol';
+import type { HubAttribution, 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';
@@ -198,6 +198,10 @@ export type CreateHandlersParams = {
     registry: HubClientRegistry;
     store: HubStore;
     authorize?: AuthorizeHook;
+    resolveAttribution?: (params: {
+        message: unknown;
+        senderDID: string;
+    }) => HubAttribution | undefined | Promise<HubAttribution | undefined>;
     rateLimits?: Partial<HubRateLimits>;
     keyPackageFetchLimits?: Partial<KeyPackageFetchLimits>;
     /** Max frames queued-but-unflushed on a receive channel. See {@link DEFAULT_RECEIVE_BUFFER_LIMIT}

package/lib/handlers.js

@@ -287,8 +287,17 @@ export function createHandlers(params) {
             let sequenceID;
             let deduped;
             try {
+                const attribution = await params.resolveAttribution?.({
+                    message: ctx.message,
+                    senderDID
+                }) ?? {
+                    account: senderDID,
+                    actor: senderDID,
+                    via: 'direct'
+                };
                 const result = await store.publish({
                     senderDID,
+                    attribution,
                     topicID,
                     payload: payloadBytes,
                     retain: ctx.param.retain,
@@ -624,7 +633,10 @@ export function createHandlers(params) {
                 logUnackedFrames();
                 tornDown = true;
                 notifyWindow();
-                if (receiveToken != null) registry.releaseReceiveWriter(clientDID, receiveToken);
+                if (receiveToken != null) registry.releaseReceiveWriter({
+                    did: clientDID,
+                    token: receiveToken
+                });
                 registry.unregisterIfIdle(clientDID);
                 reader.cancel().catch(()=>{});
                 writer.abort(new Error('receive channel torn down')).catch(()=>{});
@@ -718,7 +730,11 @@ export function createHandlers(params) {
                 // 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, onLive, ()=>endEvicted?.());
+                const { token, evicted } = registry.bindReceiveWriter({
+                    did: clientDID,
+                    writer: onLive,
+                    endReceive: ()=>endEvicted?.()
+                });
                 receiveToken = token;
                 // After the bind, so the lane is never unheld between the two.
                 evicted?.();
@@ -770,7 +786,10 @@ export function createHandlers(params) {
                 if (!tornDown) logUnackedFrames();
                 tornDown = true;
                 notifyWindow();
-                if (receiveToken != null) registry.releaseReceiveWriter(clientDID, receiveToken);
+                if (receiveToken != null) registry.releaseReceiveWriter({
+                    did: clientDID,
+                    token: receiveToken
+                });
                 registry.unregisterIfIdle(clientDID);
                 reader.cancel().catch(()=>{});
                 writer.abort(error).catch(()=>{});

package/lib/hub.d.ts

@@ -1,9 +1,9 @@
 import type { ServerTransportOf } from '@enkaku/protocol';
-import type { AccessRules, ReplayOptions, ResourceLimits, Server } from '@enkaku/server';
+import type { AccessRules, InvocationHook, ReplayOptions, ResourceLimits, Server } from '@enkaku/server';
 import type { VerifyTokenHook } from '@kokuin/capability';
-import type { Identity } from '@kokuin/token';
+import type { CryptoOptions, Identity } from '@kokuin/token';
 import type { HubProtocol, HubStore, WakeRegistry, WakeSender } from '@kumiai/hub-protocol';
-import { type AuthorizeHook, type HubRateLimits, type HubStoreErrorHook, type KeyPackageFetchLimits } from './handlers.js';
+import type { AuthorizeHook, CreateHandlersParams, HubRateLimits, HubStoreErrorHook, KeyPackageFetchLimits } from './handlers.js';
 import { HubClientRegistry } from './registry.js';
 /**
  * Default access rules: any authenticated DID may call hub procedures.
@@ -28,7 +28,7 @@ export type HubPurgeOptions = {
 };
 /** Replay settings a host may tune. The hub always enables replay checks and rejects stale tokens. */
 export type HubReplayOptions = Omit<ReplayOptions, 'enabled' | 'rejectStale'>;
-export type CreateHubParams = {
+export type CreateHubParams = CryptoOptions & {
     transport: ServerTransportOf<HubProtocol>;
     store: HubStore;
     /**
@@ -53,6 +53,9 @@ export type CreateHubParams = {
      * delegated capabilities.
      */
     verifyToken?: VerifyTokenHook;
+    onInvocation?: InvocationHook;
+    /** An absent result attributes directly to the sender. */
+    resolveAttribution?: CreateHandlersParams['resolveAttribution'];
     /** Publish rate limits. Merged over {@link DEFAULT_RATE_LIMITS}. */
     rateLimits?: Partial<HubRateLimits>;
     /**

package/lib/hub.js

@@ -32,6 +32,7 @@ export function createHub(params) {
         registry,
         store: params.store,
         authorize: params.authorize,
+        resolveAttribution: params.resolveAttribution,
         rateLimits: params.rateLimits,
         keyPackageFetchLimits: params.keyPackageFetchLimits,
         receiveAuthCacheTTL: params.receiveAuthCacheTTL,
@@ -55,8 +56,10 @@ export function createHub(params) {
         protocol: hubProtocol,
         transport: params.transport,
         identity: params.identity,
+        crypto: params.crypto,
         accessRules: params.accessRules ?? DEFAULT_HUB_ACCESS_RULES,
         verifyToken: params.verifyToken,
+        onInvocation: params.onInvocation,
         replay: {
             ...params.replay,
             enabled: true,

package/lib/index.d.ts

@@ -4,6 +4,6 @@ export type { CreateHubParams, HubInstance, HubPurgeOptions, HubReplayOptions }
 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 type { ClientEntry, HubClientRegistryBindReceiveWriterParams, HubClientRegistryReleaseReceiveWriterParams, } from './registry.js';
 export { HubClientRegistry } from './registry.js';
 export { createWakeDispatcher, type WakeDispatcher, type WakeDispatcherParams, type WakeNotifyParams, } from './wake.js';

package/lib/memoryStore.js

@@ -137,7 +137,9 @@ function isLive(entry, nowSeconds) {
                 if (accepted !== undefined) {
                     return {
                         sequenceID: accepted,
-                        deduped: true
+                        deduped: true,
+                        outcome: 'deduplicated',
+                        storedBytes: 0
                     };
                 }
             }
@@ -174,7 +176,9 @@ function isLive(entry, nowSeconds) {
             if (retain === 'mailbox' && recipients.size === 0) {
                 return {
                     sequenceID,
-                    deduped: false
+                    deduped: false,
+                    outcome: 'no-recipients',
+                    storedBytes: 0
                 };
             }
             const entry = {
@@ -219,7 +223,9 @@ function isLive(entry, nowSeconds) {
             }
             return {
                 sequenceID,
-                deduped: false
+                deduped: false,
+                outcome: 'inserted',
+                storedBytes: params.payload.byteLength
             };
         },
         async fetch (params) {

package/lib/registry.d.ts

@@ -7,6 +7,15 @@ export type ClientEntry = {
     /** Identifies the binding, so a channel can only ever release its OWN. */
     token: symbol | null;
 };
+export type HubClientRegistryBindReceiveWriterParams = {
+    did: string;
+    writer: (message: StoredMessage) => void;
+    endReceive: () => void;
+};
+export type HubClientRegistryReleaseReceiveWriterParams = {
+    did: string;
+    token: symbol;
+};
 /**
  * Tracks online clients and their live receive-channel writers. Subscription
  * state is durable in the store, not here — the registry only routes live
@@ -39,12 +48,12 @@ export declare class HubClientRegistry {
      * 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): {
+    bindReceiveWriter({ did, writer, endReceive }: HubClientRegistryBindReceiveWriterParams): {
         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;
+    releaseReceiveWriter({ did, token }: HubClientRegistryReleaseReceiveWriterParams): void;
     getClient(did: string): ClientEntry | undefined;
     isOnline(did: string): boolean;
     isWriterBound(did: string): boolean;

package/lib/registry.js

@@ -47,7 +47,7 @@
    * 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) {
+   */ bindReceiveWriter({ did, writer, endReceive }) {
         const entry = this.#clients.get(did);
         if (entry == null) return {
             token: Symbol('unbound'),
@@ -63,7 +63,7 @@
             evicted
         };
     }
-    /** Clear the binding this token names. A token that is no longer current is a no-op. */ releaseReceiveWriter(did, token) {
+    /** 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.token !== token) return;
         entry.sendMessage = null;

package/lib/wake.js

@@ -31,12 +31,15 @@ const DEFAULT_DEBOUNCE_MS = 10_000;
                 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)
+                    hint: {
+                        topicID,
+                        sequenceID,
+                        count
+                    },
+                    recipient: {
+                        publicKey: fromB64U(registration.publicKey),
+                        authSecret: fromB64U(registration.authSecret)
+                    }
                 });
                 const verdict = await params.sender.send({
                     registration,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kumiai/hub-server",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "description": "Hub server for Enkaku E2EE group message routing",
   "keywords": [
     "hub",
@@ -25,20 +25,21 @@
     "lib/*"
   ],
   "dependencies": {
-    "@enkaku/protocol": "^0.22.5",
-    "@enkaku/server": "^0.22.5",
-    "@kokuin/capability": "^0.5.2",
-    "@kokuin/token": "^0.6.4",
-    "@kumiai/hub-protocol": "^0.12.0",
+    "@enkaku/protocol": "^0.23.1",
+    "@enkaku/server": "^0.23.1",
+    "@kokuin/capability": "^0.7.0",
+    "@kokuin/token": "^0.7.0",
+    "@kumiai/hub-protocol": "^0.13.1",
     "@sozai/codec": "^0.4.4",
     "@sozai/event": "^0.1.6",
     "@sozai/log": "^0.4.0"
   },
   "devDependencies": {
-    "@enkaku/client": "^0.22.5",
-    "@enkaku/transport": "^0.22.5",
-    "@kumiai/hub-conformance": "^0.12.0",
-    "@kumiai/hub-wake": "^0.12.0"
+    "@enkaku/client": "^0.23.1",
+    "@enkaku/transport": "^0.23.1",
+    "@kokuin/crypto": "^0.7.1",
+    "@kumiai/hub-conformance": "^0.13.0",
+    "@kumiai/hub-wake": "^0.13.0"
   },
   "publishConfig": {
     "access": "public"