@kubun/hub 0.14.0 → 0.16.0

package/lib/create-relay.d.ts

@@ -1,6 +1,7 @@
 import type { Identity } from '@kokuin/token';
 import type { Adapter } from '@kubun/db-adapter';
 import { type AdapterInput } from '@kubun/db-provider';
+import type { AuthorizeHook } from '@kumiai/hub-server';
 import { Kysely } from 'kysely';
 import { type HubDatabase, type KubunHubStore } from './hub-store.js';
 import { type RelayObservers } from './observers.js';
@@ -20,6 +21,13 @@ export type CreateRelayOptions = {
     db: AdapterInput;
     identity: Identity;
     auth?: HubAuthConfig;
+    /**
+     * Per-action authorization hook, forwarded verbatim to `@kumiai/hub-server`
+     * `createHub`. Composes with `auth`: the coarse `AccessRules` gate runs first,
+     * then this refines per action and topic. Omitted, the hub allows any
+     * authenticated request (its default).
+     */
+    authorize?: AuthorizeHook;
     allowedOrigin?: string | Array<string>;
     retention?: RelayRetentionConfig;
     defaultRetention?: number;
@@ -38,6 +46,13 @@ export type RelayInternalOptions = {
     adapter: Adapter;
     identity: Identity;
     auth?: HubAuthConfig;
+    /**
+     * Per-action authorization hook, forwarded verbatim to `@kumiai/hub-server`
+     * `createHub`. Composes with `auth`: the coarse `AccessRules` gate runs first,
+     * then this refines per action and topic. Omitted, the hub allows any
+     * authenticated request (its default).
+     */
+    authorize?: AuthorizeHook;
     allowedOrigin?: string | Array<string>;
     retention?: RelayRetentionConfig;
     defaultRetention?: number;

package/lib/create-relay.js

@@ -97,6 +97,7 @@ export async function createRelayInternal(options) {
         store: hubStore,
         identity: options.identity,
         accessRules,
+        authorize: options.authorize,
         purge: false
     });
     if (observers?.onAuthRejected != null) {
@@ -222,6 +223,7 @@ export async function createRelay(options) {
         adapter,
         identity: options.identity,
         auth: options.auth,
+        authorize: options.authorize,
         allowedOrigin: options.allowedOrigin,
         retention: options.retention,
         defaultRetention: options.defaultRetention,

package/lib/hub-store.js

@@ -8,11 +8,10 @@ function toBytes(value) {
 /**
  * How long an idempotency record outlives its own publish, in seconds.
  *
- * A year: a publish repeated after this is treated as new, so the window has to
- * exceed any replay a real client could still be holding — a parked commit, a
- * device restored from a backup, a lane retried after an outage. It is not a
- * retention knob a host tunes; it is the horizon past which "the same publish"
- * stops being a coherent claim.
+ * A year: past this a repeated publish is treated as new, so the window must
+ * exceed any replay a real client could still hold — a parked commit, a device
+ * restored from backup, a lane retried after an outage. Not a host-tuned knob;
+ * it is the horizon past which "the same publish" stops being coherent.
  */ const PUBLISH_ID_RETENTION_SECONDS = 365 * 24 * 60 * 60;
 /** Frames deleted per statement — see {@link deleteFrames}. */ const DELETE_CHUNK_SIZE = 500;
 /** Matches `@kumiai/hub-server`'s own defaults — a kubun relay is not a laxer hub. */ const DEFAULT_MAX_KEY_PACKAGES_PER_DID = 100;
@@ -36,11 +35,10 @@ export function createHubStore(params) {
     /**
    * Remove frames and the deliveries pointing at them, a chunk at a time.
    *
-   * SQLite binds one parameter per element of an `in` list and throws "too many
-   * SQL variables" past its limit — 32766 on the build this ships with, 999 on
-   * older ones — so an unchunked sweep fails precisely when the backlog it exists
-   * to clear is large. Deliveries first: a delivery references a frame and cannot
-   * be pushed once its referent is gone.
+   * SQLite binds one parameter per `in` element and throws "too many SQL
+   * variables" past its limit (32766 here, 999 on older builds), so an unchunked
+   * sweep fails precisely when the backlog is large. Deliveries first: a delivery
+   * references a frame and cannot be pushed once its referent is gone.
    */ async function deleteFrames(executor, sequenceIDs) {
         for(let index = 0; index < sequenceIDs.length; index += DELETE_CHUNK_SIZE){
             const chunk = sequenceIDs.slice(index, index + DELETE_CHUNK_SIZE);
@@ -52,10 +50,9 @@ export function createHubStore(params) {
     // global counter. Fixed-width zero-padded so lexicographic order matches
     // numeric order (`"10" > "9"`), and strictly increasing.
     //
-    // One row, so every publish on every topic serializes behind it. That is the
-    // cost of a single total order; it deadlocks nothing, because every writer
-    // takes this row FIRST and the per-topic rows after it, so no two transactions
-    // hold each other's next lock.
+    // One row, so every publish on every topic serializes behind it — the cost of
+    // a single total order. It deadlocks nothing: every writer takes this row FIRST
+    // and per-topic rows after, so no two transactions hold each other's next lock.
     async function nextSequenceID(trx) {
         const row = await trx.updateTable('kubun_hub_sequence').set((eb)=>({
                 counter: eb('counter', '+', 1)
@@ -310,22 +307,20 @@ export function createHubStore(params) {
         const kysely = await db();
         const now = Date.now();
         const olderThan = purgeParams.olderThan;
-        // Idempotency records outlive the frames they dedup, on their own clock and
-        // deliberately: the contract is that no message deleter reaches one for a
-        // frame it still guards, NOT that they are kept forever. Every commit
-        // publish writes one, so without this the table is the fastest-growing on a
-        // long-lived hub, holding rows for frames purged years earlier. The window
-        // is far longer than any plausible replay — a publish repeated after it is
-        // accepted as new, which is what a fresh publishID would be anyway.
+        // Idempotency records outlive the frames they dedup, on their own clock: the
+        // contract is that no message deleter reaches one for a frame it still
+        // guards, NOT that they are kept forever. Every commit publish writes one, so
+        // without this the table is the fastest-growing on a long-lived hub. The
+        // window far exceeds any plausible replay (see PUBLISH_ID_RETENTION_SECONDS).
         await kysely.deleteFrom('kubun_hub_publish_ids').where('recorded_at', '<=', now - PUBLISH_ID_RETENTION_SECONDS * 1000).execute();
         // Per topic, the effective age bound is the longest retention any CURRENT
         // subscriber asked for, floored at the hub default (and at the sweep's
         // olderThan). Applies to both classes. Never touches the head or a publishID
         // record for a frame it removes.
         const topicRows = await kysely.selectFrom('kubun_hub_messages').select('topic_id').distinct().execute();
-        // Every topic's longest CURRENT subscriber retention in one grouped read
-        // rather than one read per topic: the sweep walks every topic the hub holds,
-        // so the per-topic version is a query count that grows with the hub.
+        // Every topic's longest CURRENT subscriber retention in one grouped read, not
+        // one read per topic: the sweep walks every topic, so per-topic reads would be
+        // a query count that grows with the hub.
         const retentionRows = await kysely.selectFrom('kubun_hub_subscriptions').select((eb)=>[
                 'topic_id',
                 eb.fn.max('retention').as('maxRetention')
@@ -358,7 +353,7 @@ export function createHubStore(params) {
     async function deleteExpiredKeyPackages(kysely, ownerDID) {
         await kysely.deleteFrom('kubun_hub_key_packages').where('owner_did', '=', ownerDID).where('not_after', 'is not', null).where('not_after', '<=', nowSeconds()).execute();
     }
-    async function storeKeyPackage(ownerDID, keyPackage, notAfter) {
+    async function storeKeyPackage({ ownerDID, keyPackage, notAfter }) {
         const kysely = await db();
         // Drop the dead BEFORE charging the cap. The cap rejects rather than evicts, so
         // nothing else would ever remove them: a pool that filled with expired entries
@@ -374,7 +369,7 @@ export function createHubStore(params) {
             not_after: notAfter ?? null
         }).execute();
     }
-    async function fetchKeyPackages(ownerDID, count) {
+    async function fetchKeyPackages({ ownerDID, count }) {
         const kysely = await db();
         // Expired entries are DELETED first, not filtered after the limit: a run of dead
         // rows would otherwise consume the whole page and return nothing while live
@@ -386,7 +381,7 @@ export function createHubStore(params) {
         const rows = await kysely.deleteFrom('kubun_hub_key_packages').where('id', 'in', kysely.selectFrom('kubun_hub_key_packages').select('id').where('owner_did', '=', ownerDID).orderBy('id', 'asc').limit(limit)).returning('key_package').execute();
         return rows.map((r)=>r.key_package);
     }
-    async function countKeyPackages(ownerDID) {
+    async function countKeyPackages({ ownerDID }) {
         const kysely = await db();
         const row = await kysely.selectFrom('kubun_hub_key_packages').select((eb)=>eb.fn.countAll().as('count')).where('owner_did', '=', ownerDID).where((eb)=>eb.or([
                 eb('not_after', 'is', null),
@@ -394,7 +389,7 @@ export function createHubStore(params) {
             ])).executeTakeFirst();
         return Number(row?.count ?? 0);
     }
-    async function storeLastResortKeyPackage(ownerDID, keyPackage) {
+    async function storeLastResortKeyPackage({ ownerDID, keyPackage }) {
         const kysely = await db();
         await kysely.insertInto('kubun_hub_last_resort_key_packages').values({
             owner_did: ownerDID,
@@ -403,7 +398,7 @@ export function createHubStore(params) {
                 key_package: (eb)=>eb.ref('excluded.key_package')
             })).execute();
     }
-    async function fetchLastResortKeyPackage(ownerDID) {
+    async function fetchLastResortKeyPackage({ ownerDID }) {
         const kysely = await db();
         // Never consumes. Reuse is the point: the package carries MLS's `last_resort`
         // extension, so serving it twice is the availability floor rather than the
@@ -442,7 +437,7 @@ export function createHubStore(params) {
                 retention: (eb)=>eb.ref('excluded.retention')
             })).execute();
     }
-    async function unsubscribe(subscriberDID, topicID) {
+    async function unsubscribe({ subscriberDID, topicID }) {
         const kysely = await db();
         await kysely.deleteFrom('kubun_hub_subscriptions').where('topic_id', '=', topicID).where('subscriber_did', '=', subscriberDID).execute();
         // unsubscribe is a delivery operation, not a trim: it drops this subscriber's
@@ -460,7 +455,7 @@ export function createHubStore(params) {
             await kysely.deleteFrom('kubun_hub_messages').where('sequence_id', 'in', orphaned).where('retain', '=', 'mailbox').execute();
         }
     }
-    async function getSubscribers(topicID) {
+    async function getSubscribers({ topicID }) {
         const kysely = await db();
         const rows = await kysely.selectFrom('kubun_hub_subscriptions').select('subscriber_did').where('topic_id', '=', topicID).execute();
         return rows.map((r)=>r.subscriber_did);

package/lib/index.d.ts

@@ -4,8 +4,10 @@ import type { Kysely } from 'kysely';
 import { type HubAuthConfig, type RelayRetentionConfig } from './create-relay.js';
 import type { HubDatabase } from './hub-store.js';
 import type { RelayObservers } from './observers.js';
+export type { AuthorizeDecision, AuthorizeHook, AuthorizeRequest } from '@kumiai/hub-server';
 export { type CreateRelayOptions, createRelay, createRelayInternal, type HubAuthConfig, type Relay, type RelayRetentionConfig, } from './create-relay.js';
 export { type CreateHubStoreParams, createHubStore, type HubDatabase, type KubunHubStore, type PurgedSubscription, type PurgeSubscriptionsParams, } from './hub-store.js';
+export { type JoinLaneAuthorizeConfig, joinLaneAuthorize } from './join-lane-authorize.js';
 export { createHubMigrations, type MigrationContext } from './migrations.js';
 export { decorateHubStore, type RelayObserverAckInfo, type RelayObserverAuthRejectedInfo, type RelayObserverErrorInfo, type RelayObserverErrorStage, type RelayObserverFetchInfo, type RelayObserverPurgeInfo, type RelayObserverRetentionConfigClampedInfo, type RelayObserverStoreInfo, type RelayObserverSubscriptionPurgeInfo, type RelayObservers, } from './observers.js';
 export type HubOptions = {

package/lib/index.js

@@ -4,6 +4,7 @@ import { Hono } from 'hono';
 import { createRelayInternal } from './create-relay.js';
 export { createRelay, createRelayInternal } from './create-relay.js';
 export { createHubStore } from './hub-store.js';
+export { joinLaneAuthorize } from './join-lane-authorize.js';
 export { createHubMigrations } from './migrations.js';
 export { decorateHubStore } from './observers.js';
 export async function createHub(options) {

package/lib/join-lane-authorize.d.ts

@@ -0,0 +1,13 @@
+import type { AuthorizeHook } from '@kumiai/hub-server';
+export type JoinLaneAuthorizeConfig = {
+    /** The single topic a not-yet-member device may touch. */
+    joinTopic: string;
+    /** Whether a DID is already a member (gets full access). */
+    isMember: (did: string) => boolean | Promise<boolean>;
+};
+/**
+ * Build an `authorize` hook implementing a pre-membership "join lane": a member
+ * DID may do anything; a non-member may only publish/subscribe/fetch exactly the
+ * one join topic, and nothing else. Pair with `createRelay({ authorize })`.
+ */
+export declare function joinLaneAuthorize(config: JoinLaneAuthorizeConfig): AuthorizeHook;

package/lib/join-lane-authorize.js

@@ -0,0 +1,26 @@
+// Actions a non-member is allowed on the join topic — the minimum to post a
+// join request and receive the answer. Everything else is denied.
+const JOIN_LANE_ACTIONS = new Set([
+    'publish',
+    'subscribe',
+    'topic/fetch'
+]);
+/**
+ * Build an `authorize` hook implementing a pre-membership "join lane": a member
+ * DID may do anything; a non-member may only publish/subscribe/fetch exactly the
+ * one join topic, and nothing else. Pair with `createRelay({ authorize })`.
+ */ export function joinLaneAuthorize(config) {
+    return async (req)=>{
+        if (await config.isMember(req.did)) {
+            return true;
+        }
+        const topicID = 'topicID' in req ? req.topicID : undefined;
+        if (JOIN_LANE_ACTIONS.has(req.action) && topicID === config.joinTopic) {
+            return true;
+        }
+        return {
+            allow: false,
+            reason: 'join lane: non-members may only use the join topic'
+        };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/hub",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "license": "see LICENSE.md",
   "sideEffects": false,
   "type": "module",
@@ -18,26 +18,26 @@
     "@enkaku/server": "^0.21.2",
     "@hono/node-server": "^2.1.1",
     "@kokuin/token": "^0.5.0",
-    "@kubun/db-adapter": "^0.14.0",
-    "@kubun/db-provider": "^0.14.0",
-    "@kubun/http-util": "^0.14.0",
-    "@kumiai/hub-protocol": "^0.7.0",
-    "@kumiai/hub-server": "^0.7.0",
+    "@kubun/db-adapter": "^0.16.0",
+    "@kubun/db-provider": "^0.16.0",
+    "@kubun/http-util": "^0.16.0",
+    "@kumiai/hub-protocol": "^0.9.0",
+    "@kumiai/hub-server": "^0.9.0",
     "@sozai/event": "^0.1.3",
     "get-port": "^7.2.0",
-    "hono": "^4.13.4",
+    "hono": "^4.13.5",
     "kysely": "^0.29.5"
   },
   "devDependencies": {
-    "@enkaku/client": "^0.21.0",
+    "@enkaku/client": "^0.21.2",
     "@enkaku/http-fetch": "^0.21.0",
-    "@enkaku/protocol": "^0.21.0",
+    "@enkaku/protocol": "^0.21.1",
     "@enkaku/transport": "^0.21.0",
-    "@kubun/db-better-sqlite": "^0.14.0",
-    "@kubun/db-node-sqlite": "^0.14.0",
-    "@kubun/db-postgres": "^0.14.0",
-    "@kumiai/hub-conformance": "^0.7.0",
-    "@kumiai/mls": "^0.7.0",
+    "@kubun/db-better-sqlite": "^0.16.0",
+    "@kubun/db-node-sqlite": "^0.16.0",
+    "@kubun/db-postgres": "^0.16.0",
+    "@kumiai/hub-conformance": "^0.9.0",
+    "@kumiai/mls": "^0.9.0",
     "@sozai/async": "^0.2.1",
     "@testcontainers/postgresql": "^12.1.0"
   },