@kubun/hub 0.10.0 → 0.12.0

package/lib/create-relay.d.ts

@@ -1,9 +1,8 @@
-import type { HubStore } from '@enkaku/hub-protocol';
-import type { Identity } from '@enkaku/token';
+import type { Identity } from '@kokuin/token';
 import type { Adapter } from '@kubun/db-adapter';
 import { type AdapterInput } from '@kubun/db-provider';
 import { Kysely } from 'kysely';
-import { type HubDatabase } from './hub-store.js';
+import { type HubDatabase, type KubunHubStore } from './hub-store.js';
 import { type RelayObservers } from './observers.js';
 export type HubAuthConfig = {
     mode: 'open';
@@ -15,28 +14,35 @@ export type HubAuthConfig = {
 export type RelayRetentionConfig = {
     olderThanSeconds: number;
     intervalSeconds?: number;
+    subscriptionOlderThanSeconds?: number;
 };
 export type CreateRelayOptions = {
     db: AdapterInput;
-    identity?: Identity;
+    identity: Identity;
     auth?: HubAuthConfig;
     allowedOrigin?: string | Array<string>;
     retention?: RelayRetentionConfig;
+    defaultRetention?: number;
+    maxRetention?: number;
+    maxDepth?: number;
     observers?: RelayObservers;
 };
 export type Relay = {
     fetch: (request: Request) => Promise<Response>;
-    hubStore: HubStore;
+    hubStore: KubunHubStore;
     pendingDeliveries: () => Promise<number>;
     dispose: () => Promise<void>;
 };
 export type RelayInternalOptions = {
     kysely: Kysely<HubDatabase>;
     adapter: Adapter;
-    identity?: Identity;
+    identity: Identity;
     auth?: HubAuthConfig;
     allowedOrigin?: string | Array<string>;
     retention?: RelayRetentionConfig;
+    defaultRetention?: number;
+    maxRetention?: number;
+    maxDepth?: number;
     observers?: RelayObservers;
     ownsKysely: boolean;
 };

package/lib/create-relay.js

@@ -1 +1,233 @@
-import{ServerTransport as e}from"@enkaku/http-server-transport";import{createHandlers as t,HubClientRegistry as r}from"@enkaku/hub-server";import{Server as n}from"@enkaku/server";import{resolveAdapter as o}from"@kubun/db-provider";import{Kysely as i}from"kysely";import{Migrator as a}from"kysely/migration";import{createHubStore as l}from"./hub-store.js";import{createHubMigrations as s}from"./migrations.js";import{decorateHubStore as u}from"./observers.js";export async function createRelayInternal(o){var i;let c,d,{kysely:m,adapter:h,observers:y,ownsKysely:p}=o;if(null!=o.auth&&null==o.identity)throw Error("createRelay: 'identity' is required when 'auth' is set");let f=s({types:h.types,functions:h.functions}),w=new a({db:m,provider:{getMigrations:async()=>f},migrationTableName:"kubun_hub_migration",migrationLockTableName:"kubun_hub_migration_lock"}),{error:g}=await w.migrateToLatest();if(null!=g)throw g;let b=new r,v=l({kysely:m,adapter:h}),k=u(v,y);if(y?.onPurge!=null){let e=y.onPurge;c=v.events.on("purge",t=>{try{e({sequenceCount:t.sequenceIDs.length})}catch{}})}let _=t({registry:b,store:k}),R=new e({allowedOrigin:null==(i=o.allowedOrigin)?["*"]:"string"==typeof i?i.split(",").map(e=>e.trim()):i}),T=function(e){if(null==e)return{};switch(e.mode){case"open":return{"*":{allow:!0}};case"allowlist":{let{allowedDIDs:t,isAllowed:r}=e;if(null!=r)return{"*":{allow:async e=>{let n=e.payload.iss;return!!t?.includes(n)||await r(n)}}};return{"*":{allow:t??[]}}}}}(o.auth),j=new n(o.identity?{identity:o.identity,accessRules:T,handlers:_,transports:[R]}:{handlers:_,transports:[R]});if(y?.onAuthRejected!=null){let e=y.onAuthRejected;j.events.on("handlerError",t=>{if("auth"===t.category)try{e({reason:t.error.message})}catch{}})}if(null!=o.retention){let{olderThanSeconds:e}=o.retention;d=setInterval(()=>{k.purge({olderThan:e}).catch(e=>{if(y?.onError!=null)try{y.onError({stage:"purge",error:e})}catch{}})},Math.max(1,Math.floor(1e3*(o.retention.intervalSeconds??3600))))}return{fetch:e=>R.fetch(e),hubStore:k,pendingDeliveries:async()=>Number((await m.selectFrom("kubun_hub_deliveries").select(({fn:e})=>e.countAll().as("count")).executeTakeFirstOrThrow()).count),dispose:async()=>{null!=d&&(clearInterval(d),d=void 0),null!=c&&(c(),c=void 0),await j.dispose(),p&&await m.destroy()}}}export async function createRelay(e){let t=o(e.db),r=new i({dialect:t.dialect});return await createRelayInternal({kysely:r,adapter:t,identity:e.identity,auth:e.auth,allowedOrigin:e.allowedOrigin,retention:e.retention,observers:e.observers,ownsKysely:!0})}
+import { ServerTransport } from '@enkaku/http-serve';
+import { resolveAdapter } from '@kubun/db-provider';
+import { resolveAllowedOrigin } from '@kubun/http-util';
+import { createHub } from '@kumiai/hub-server';
+import { Kysely } from 'kysely';
+import { Migrator } from 'kysely/migration';
+import { createHubStore } from './hub-store.js';
+import { createHubMigrations } from './migrations.js';
+import { decorateHubStore } from './observers.js';
+const DEFAULT_RETENTION_INTERVAL_SECONDS = 3600;
+const DEFAULT_SUBSCRIPTION_RETENTION_SECONDS = 90 * 24 * 60 * 60;
+const DEFAULT_MAX_RETENTION_SECONDS = 30 * 24 * 60 * 60;
+const DEFAULT_MAX_DEPTH = 1000;
+function resolveAccessRules(auth) {
+    if (auth == null) return {};
+    switch(auth.mode){
+        case 'open':
+            return {
+                '*': {
+                    allow: true
+                }
+            };
+        case 'allowlist':
+            {
+                const { allowedDIDs, isAllowed } = auth;
+                if (isAllowed != null) {
+                    const wrapped = async (ctx)=>{
+                        const did = ctx.payload.iss;
+                        if (allowedDIDs?.includes(did)) return true;
+                        return await isAllowed(did);
+                    };
+                    return {
+                        '*': {
+                            allow: wrapped
+                        }
+                    };
+                }
+                return {
+                    '*': {
+                        allow: allowedDIDs ?? []
+                    }
+                };
+            }
+    }
+}
+export async function createRelayInternal(options) {
+    const { kysely, adapter, observers, ownsKysely } = options;
+    const migrationCtx = {
+        types: adapter.types,
+        functions: adapter.functions
+    };
+    const migrations = createHubMigrations(migrationCtx);
+    const migrationProvider = {
+        getMigrations: async ()=>migrations
+    };
+    const migrator = new Migrator({
+        db: kysely,
+        provider: migrationProvider,
+        migrationTableName: 'kubun_hub_migration',
+        migrationLockTableName: 'kubun_hub_migration_lock'
+    });
+    const { error: migrationError } = await migrator.migrateToLatest();
+    if (migrationError != null) {
+        throw migrationError;
+    }
+    const rawStore = createHubStore({
+        kysely,
+        adapter,
+        defaultRetention: options.defaultRetention ?? 0,
+        maxRetention: options.maxRetention ?? DEFAULT_MAX_RETENTION_SECONDS,
+        maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH
+    });
+    const hubStore = decorateHubStore(rawStore, observers);
+    let unsubscribePurge;
+    if (observers?.onPurge != null) {
+        const onPurge = observers.onPurge;
+        unsubscribePurge = rawStore.events.on('purge', (info)=>{
+            try {
+                onPurge({
+                    sequenceCount: info.sequenceIDs.length
+                });
+            } catch  {
+            // Observer callbacks are diagnostics — never let them break the relay.
+            }
+        });
+    }
+    const allowedOrigin = resolveAllowedOrigin(options.allowedOrigin);
+    const transport = new ServerTransport({
+        allowedOrigin
+    });
+    const accessRules = resolveAccessRules(options.auth);
+    // `@kumiai/hub-server` assembles the handlers, registry, and Enkaku server for
+    // its own protocol. Purging is disabled here because this relay runs its own
+    // retention timer below, over the same store, with kubun's clamped windows.
+    const { server: enkakuServer } = createHub({
+        transport,
+        store: hubStore,
+        identity: options.identity,
+        accessRules,
+        purge: false
+    });
+    if (observers?.onAuthRejected != null) {
+        const onAuthRejected = observers.onAuthRejected;
+        enkakuServer.events.on('handlerError', (info)=>{
+            if (info.category !== 'auth') return;
+            try {
+                onAuthRejected({
+                    reason: info.error.message
+                });
+            } catch  {
+            // Observer callbacks are diagnostics — never let them break the relay.
+            }
+        });
+    }
+    let retentionTimer;
+    // The sweep a fired tick is still running, so `dispose` can wait for it.
+    let sweep;
+    let runSweep;
+    if (options.retention != null) {
+        const { olderThanSeconds } = options.retention;
+        const intervalSeconds = options.retention.intervalSeconds ?? DEFAULT_RETENTION_INTERVAL_SECONDS;
+        const intervalMs = Math.max(1, Math.floor(intervalSeconds * 1000));
+        // A subscriber must never be reaped while a message it would still receive
+        // is retained, so the subscription window is clamped up to the message
+        // window.
+        const configuredSubscription = options.retention.subscriptionOlderThanSeconds ?? DEFAULT_SUBSCRIPTION_RETENTION_SECONDS;
+        const subscriptionOlderThanSeconds = Math.max(configuredSubscription, olderThanSeconds);
+        if (configuredSubscription < olderThanSeconds && observers?.onRetentionConfigClamped != null) {
+            try {
+                observers.onRetentionConfigClamped({
+                    configuredSubscriptionOlderThanSeconds: configuredSubscription,
+                    clampedToSeconds: subscriptionOlderThanSeconds
+                });
+            } catch  {
+            // Observer callbacks are diagnostics — never let them break the relay.
+            }
+        }
+        retentionTimer = setInterval(()=>{
+            // A tick that already fired is live work, not a timer: `purge` is an
+            // unbounded per-topic scan plus two bulk deletes, and on Postgres
+            // destroying the pool underneath one wedges `close()` forever. `dispose`
+            // awaits this handle, so cancelling the timer and draining what it
+            // started are two different things and both are needed.
+            sweep = runSweep?.().finally(()=>{
+                sweep = undefined;
+            });
+        }, intervalMs);
+        runSweep = async ()=>{
+            await hubStore.purge({
+                olderThan: olderThanSeconds
+            }).catch((err)=>{
+                if (observers?.onError != null) {
+                    try {
+                        observers.onError({
+                            stage: 'purge',
+                            error: err
+                        });
+                    } catch  {
+                    // Observer callbacks are diagnostics — never let them break the relay.
+                    }
+                }
+            });
+            await hubStore.purgeSubscribers({
+                olderThan: subscriptionOlderThanSeconds
+            }).then((purged)=>{
+                if (observers?.onSubscriptionPurge != null) {
+                    try {
+                        observers.onSubscriptionPurge({
+                            subscriptionCount: purged.length
+                        });
+                    } catch  {
+                    // Observer callbacks are diagnostics — never let them break the relay.
+                    }
+                }
+            }).catch((err)=>{
+                if (observers?.onError != null) {
+                    try {
+                        observers.onError({
+                            stage: 'subscription-purge',
+                            error: err
+                        });
+                    } catch  {
+                    // Observer callbacks are diagnostics — never let them break the relay.
+                    }
+                }
+            });
+        };
+    }
+    return {
+        fetch: (request)=>transport.fetch(request),
+        hubStore,
+        pendingDeliveries: async ()=>{
+            const row = await kysely.selectFrom('kubun_hub_deliveries').select(({ fn })=>fn.countAll().as('count')).executeTakeFirstOrThrow();
+            return Number(row.count);
+        },
+        dispose: async ()=>{
+            if (retentionTimer != null) {
+                clearInterval(retentionTimer);
+                retentionTimer = undefined;
+            }
+            // Drain before the server and the pool go: cancelling the timer stops the
+            // NEXT tick and does nothing about the one already running.
+            await sweep;
+            if (unsubscribePurge != null) {
+                unsubscribePurge();
+                unsubscribePurge = undefined;
+            }
+            await enkakuServer.dispose();
+            if (ownsKysely) {
+                await kysely.destroy();
+            }
+        }
+    };
+}
+export async function createRelay(options) {
+    const adapter = resolveAdapter(options.db);
+    const kysely = new Kysely({
+        dialect: adapter.dialect
+    });
+    return await createRelayInternal({
+        kysely,
+        adapter,
+        identity: options.identity,
+        auth: options.auth,
+        allowedOrigin: options.allowedOrigin,
+        retention: options.retention,
+        defaultRetention: options.defaultRetention,
+        maxRetention: options.maxRetention,
+        maxDepth: options.maxDepth,
+        observers: options.observers,
+        ownsKysely: true
+    });
+}

package/lib/hub-store.d.ts

@@ -1,13 +1,14 @@
-import type { HubStore } from '@enkaku/hub-protocol';
 import type { Adapter } from '@kubun/db-adapter';
+import { type HubStore } from '@kumiai/hub-protocol';
 import type { ColumnType, Kysely } from 'kysely';
 export type HubDatabase = {
     kubun_hub_messages: {
         sequence_id: string;
         sender_did: string;
-        group_id: string | null;
+        topic_id: string;
         payload: Uint8Array;
         stored_at: number;
+        retain: string;
     };
     kubun_hub_deliveries: {
         sequence_id: string;
@@ -17,14 +18,50 @@ export type HubDatabase = {
         id: ColumnType<number, number | undefined, never>;
         owner_did: string;
         key_package: string;
+        not_after: ColumnType<number | null, number | null | undefined, never>;
     };
-    kubun_hub_group_members: {
-        group_id: string;
-        member_did: string;
+    kubun_hub_last_resort_key_packages: {
+        owner_did: string;
+        key_package: string;
+    };
+    kubun_hub_subscriptions: {
+        topic_id: string;
+        subscriber_did: string;
+        last_active_at: number;
+        retention: ColumnType<number, number | undefined, number>;
+    };
+    kubun_hub_topics: {
+        topic_id: string;
+        head: string;
+    };
+    kubun_hub_sequence: {
+        id: number;
+        counter: ColumnType<number, number, number>;
+    };
+    kubun_hub_publish_ids: {
+        topic_id: string;
+        publish_id: string;
+        sequence_id: string;
+        recorded_at: number;
     };
 };
 export type CreateHubStoreParams = {
     kysely: Kysely<HubDatabase> | Promise<Kysely<HubDatabase>>;
     adapter: Adapter;
+    defaultRetention?: number;
+    maxRetention?: number;
+    maxDepth?: number;
+    maxKeyPackagesPerDID?: number;
+    maxSubscriptionsPerDID?: number;
+};
+export type PurgeSubscriptionsParams = {
+    olderThan: number;
+};
+export type PurgedSubscription = {
+    topicID: string;
+    subscriberDID: string;
+};
+export type KubunHubStore = HubStore & {
+    purgeSubscribers(params: PurgeSubscriptionsParams): Promise<Array<PurgedSubscription>>;
 };
-export declare function createHubStore(params: CreateHubStoreParams): HubStore;
+export declare function createHubStore(params: CreateHubStoreParams): KubunHubStore;

package/lib/hub-store.js

@@ -1 +1,503 @@
-import{EventEmitter as e}from"@enkaku/event";export function createHubStore(u){let n,t,{adapter:a}=u;async function i(){return null==n&&(n=await u.kysely),n}async function s(){let e=await i();if(null==t){let u=await e.selectFrom("kubun_hub_messages").select(e.fn.max("sequence_id").as("max_id")).executeTakeFirst();t=u?.max_id!=null?Number.parseInt(u.max_id,10):0}return String(++t).padStart(12,"0")}let r=new e;async function _(e){if(0===e.sequenceIDs.length)return;let u=await i();await u.deleteFrom("kubun_hub_deliveries").where("recipient_did","=",e.recipientDID).where("sequence_id","in",e.sequenceIDs).execute();let n=new Set((await u.selectFrom("kubun_hub_deliveries").select("sequence_id").where("sequence_id","in",e.sequenceIDs).execute()).map(e=>e.sequence_id)),t=e.sequenceIDs.filter(e=>!n.has(e));t.length>0&&await u.deleteFrom("kubun_hub_messages").where("sequence_id","in",t).execute()}async function c(e){let u=await i(),n=Date.now()-1e3*e.olderThan,t=(await u.selectFrom("kubun_hub_messages").select("sequence_id").where("stored_at","<=",n).execute()).map(e=>e.sequence_id);return 0===t.length?[]:(await u.deleteFrom("kubun_hub_deliveries").where("sequence_id","in",t).execute(),await u.deleteFrom("kubun_hub_messages").where("sequence_id","in",t).execute(),await r.emit("purge",{sequenceIDs:t}),t)}return{events:r,store:async function(e){let u=await s(),n=Date.now(),t=await i();return await t.insertInto("kubun_hub_messages").values({sequence_id:u,sender_did:e.senderDID,group_id:e.groupID??null,payload:a.encodeBinary(e.payload),stored_at:n}).execute(),e.recipients.length>0&&await t.insertInto("kubun_hub_deliveries").values(e.recipients.map(e=>({sequence_id:u,recipient_did:e}))).execute(),u},fetch:async function(e){null!=e.ack&&e.ack.length>0&&await _({recipientDID:e.recipientDID,sequenceIDs:e.ack});let u=(await i()).selectFrom("kubun_hub_deliveries").innerJoin("kubun_hub_messages","kubun_hub_messages.sequence_id","kubun_hub_deliveries.sequence_id").select(["kubun_hub_messages.sequence_id","kubun_hub_messages.sender_did","kubun_hub_messages.group_id","kubun_hub_messages.payload"]).where("kubun_hub_deliveries.recipient_did","=",e.recipientDID).orderBy("kubun_hub_messages.sequence_id","asc");null!=e.after&&(u=u.where("kubun_hub_messages.sequence_id",">",e.after));let n=e.limit;null!=n&&(u=u.limit(n+1));let t=await u.execute(),a=!1,s=t;null!=n&&t.length>n&&(a=!0,s=t.slice(0,n));let r=s.map(e=>({sequenceID:e.sequence_id,senderDID:e.sender_did,groupID:e.group_id??void 0,payload:e.payload})),c=r.length>0?r[r.length-1].sequenceID:null;return{messages:r,cursor:c,hasMore:a}},ack:_,purge:c,storeKeyPackage:async function(e,u){let n=await i();await n.insertInto("kubun_hub_key_packages").values({owner_did:e,key_package:u}).execute()},fetchKeyPackages:async function(e,u){let n=await i();return(await n.deleteFrom("kubun_hub_key_packages").where("id","in",n.selectFrom("kubun_hub_key_packages").select("id").where("owner_did","=",e).orderBy("id","asc").limit(u??1)).returning("key_package").execute()).map(e=>e.key_package)},setGroupMembers:async function(e,u){let n=await i();await n.deleteFrom("kubun_hub_group_members").where("group_id","=",e).execute(),u.length>0&&await n.insertInto("kubun_hub_group_members").values(u.map(u=>({group_id:e,member_did:u}))).execute()},getGroupMembers:async function(e){let u=await i();return(await u.selectFrom("kubun_hub_group_members").select("member_did").where("group_id","=",e).execute()).map(e=>e.member_did)}}}
+import { HeadMismatchError, KeyPackageQuotaExceededError, NotSubscribedError, RetentionExceededError, SubscriptionQuotaExceededError } from '@kumiai/hub-protocol';
+import { EventEmitter } from '@sozai/event';
+// Normalize a DB binary column (a Buffer under better-sqlite3 / node-postgres)
+// to a plain Uint8Array, so payload equality holds against a Uint8Array caller.
+function toBytes(value) {
+    return new Uint8Array(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.
+ */ 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;
+const DEFAULT_MAX_SUBSCRIPTIONS_PER_DID = 1000;
+export function createHubStore(params) {
+    const { adapter } = params;
+    const defaultRetention = params.defaultRetention ?? 0;
+    const maxRetention = params.maxRetention;
+    const maxDepth = params.maxDepth;
+    const maxKeyPackagesPerDID = params.maxKeyPackagesPerDID ?? DEFAULT_MAX_KEY_PACKAGES_PER_DID;
+    const maxSubscriptionsPerDID = params.maxSubscriptionsPerDID ?? DEFAULT_MAX_SUBSCRIPTIONS_PER_DID;
+    // Lazy DB resolution -- accepts Kysely or Promise<Kysely> and caches the resolved instance
+    let resolvedDB;
+    async function db() {
+        if (resolvedDB == null) {
+            resolvedDB = await params.kysely;
+        }
+        return resolvedDB;
+    }
+    const events = new EventEmitter();
+    /**
+   * 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.
+   */ 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);
+            await executor.deleteFrom('kubun_hub_deliveries').where('sequence_id', 'in', chunk).execute();
+            await executor.deleteFrom('kubun_hub_messages').where('sequence_id', 'in', chunk).execute();
+        }
+    }
+    // Mint the next sequenceID inside the accepting transaction, from a persistent
+    // 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.
+    async function nextSequenceID(trx) {
+        const row = await trx.updateTable('kubun_hub_sequence').set((eb)=>({
+                counter: eb('counter', '+', 1)
+            })).where('id', '=', 0).returning('counter').executeTakeFirstOrThrow();
+        return String(row.counter).padStart(12, '0');
+    }
+    // Depth eviction runs inside the publishing transaction. It counts LOG frames
+    // only and removes the oldest beyond the bound (with their deliveries). Silent:
+    // depth eviction is a synchronous consequence of the caller's own publish.
+    async function evictDepth(trx, topicID) {
+        if (maxDepth == null) return;
+        const logRows = await trx.selectFrom('kubun_hub_messages').select('sequence_id').where('topic_id', '=', topicID).where('retain', '=', 'log').orderBy('sequence_id', 'asc').execute();
+        if (logRows.length <= maxDepth) return;
+        const evict = logRows.slice(0, logRows.length - maxDepth).map((r)=>r.sequence_id);
+        await deleteFrames(trx, evict);
+    }
+    async function publish(publishParams) {
+        const kysely = await db();
+        const retain = publishParams.retain ?? 'mailbox';
+        const { senderDID, topicID } = publishParams;
+        // The dedup check, the head compare-and-set, the sequence mint, the append,
+        // and the head advance all happen in ONE transaction, in that order. A
+        // read-then-write CAS split across statements is the exact race the head
+        // exists to eliminate.
+        return await kysely.transaction().execute(async (trx)=>{
+            // 1. Dedup — BEFORE the CAS. A replay carries a stale expectedHead by
+            // construction (the publish it replays is what moved the head), so comparing
+            // first would raise HeadMismatchError and tell the caller its commit was lost
+            // when it landed.
+            if (publishParams.publishID != null) {
+                const existing = await trx.selectFrom('kubun_hub_publish_ids').select('sequence_id').where('topic_id', '=', topicID).where('publish_id', '=', publishParams.publishID).executeTakeFirst();
+                if (existing != null) {
+                    return {
+                        sequenceID: existing.sequence_id,
+                        deduped: true
+                    };
+                }
+            }
+            // 2. Stored head (null when the topic has never had an accepted log publish).
+            const topicRow = await trx.selectFrom('kubun_hub_topics').select('head').where('topic_id', '=', topicID).executeTakeFirst();
+            const currentHead = topicRow?.head ?? null;
+            // 3. Compare-and-set. On mismatch, throw and store NOTHING (the transaction
+            // rolls back — no entry, no delivery, no sequenceID consumed, no event).
+            if (publishParams.expectedHead !== undefined && currentHead !== publishParams.expectedHead) {
+                throw new HeadMismatchError(`head mismatch: expected ${String(publishParams.expectedHead)}, current ${String(currentHead)}`);
+            }
+            // 4. Mint the sequenceID.
+            const sequenceID = await nextSequenceID(trx);
+            // 5. Recipients = current subscribers minus the sender.
+            const subscriberRows = await trx.selectFrom('kubun_hub_subscriptions').select('subscriber_did').where('topic_id', '=', topicID).execute();
+            const recipients = subscriberRows.map((r)=>r.subscriber_did).filter((did)=>did !== senderDID);
+            // 6. Append. A log frame is stored unconditionally (a reader that must read
+            // it may not exist yet). A mailbox frame is delivery-derived: with zero
+            // recipients there is nothing to deliver, so it is not stored — but the
+            // sequenceID is still consumed.
+            const storeMessage = retain === 'log' || recipients.length > 0;
+            if (storeMessage) {
+                await trx.insertInto('kubun_hub_messages').values({
+                    sequence_id: sequenceID,
+                    sender_did: senderDID,
+                    topic_id: topicID,
+                    payload: adapter.encodeBinary(publishParams.payload),
+                    stored_at: Date.now(),
+                    retain
+                }).execute();
+                // Push is untouched by the class: a log frame is delivered to every current
+                // subscriber exactly as a mailbox frame is.
+                if (recipients.length > 0) {
+                    await trx.insertInto('kubun_hub_deliveries').values(recipients.map((did)=>({
+                            sequence_id: sequenceID,
+                            recipient_did: did
+                        }))).execute();
+                }
+            }
+            // 7. Advance the stored head — LOG frames only. A mailbox publish never moves
+            // the head.
+            //
+            // The head advance IS the compare-and-set; the earlier head read is only an
+            // MVCC snapshot, which two transactions racing at the same head both pass. The
+            // arbiter is this CONDITIONAL write, whose row count decides the winner: the
+            // loser matches zero rows, throws, and rolls the whole transaction back.
+            if (retain === 'log') {
+                if (publishParams.expectedHead === undefined) {
+                    // Unconditional log publish: last-writer-wins on the head pointer. The
+                    // frame is already appended; only the pointer races, and the caller did
+                    // not ask for a CAS.
+                    await trx.insertInto('kubun_hub_topics').values({
+                        topic_id: topicID,
+                        head: sequenceID
+                    }).onConflict((oc)=>oc.column('topic_id').doUpdateSet({
+                            head: sequenceID
+                        })).execute();
+                } else if (publishParams.expectedHead === null) {
+                    // Expected "never had a log publish": insert the row, and lose to any
+                    // concurrent transaction that inserted it first (conflict → 0 rows).
+                    const inserted = await trx.insertInto('kubun_hub_topics').values({
+                        topic_id: topicID,
+                        head: sequenceID
+                    }).onConflict((oc)=>oc.column('topic_id').doNothing()).executeTakeFirst();
+                    if (Number(inserted.numInsertedOrUpdatedRows ?? 0n) === 0) {
+                        throw new HeadMismatchError('head mismatch: expected null, a concurrent publish set the head first');
+                    }
+                } else {
+                    // Expected a specific head: advance only if it is still that value.
+                    const updated = await trx.updateTable('kubun_hub_topics').set({
+                        head: sequenceID
+                    }).where('topic_id', '=', topicID).where('head', '=', publishParams.expectedHead).executeTakeFirst();
+                    if (Number(updated.numUpdatedRows ?? 0n) === 0) {
+                        throw new HeadMismatchError(`head mismatch: expected ${publishParams.expectedHead}, a concurrent publish advanced it`);
+                    }
+                }
+                await evictDepth(trx, topicID);
+            }
+            // 8. Record the idempotency key in its own table.
+            if (publishParams.publishID != null) {
+                await trx.insertInto('kubun_hub_publish_ids').values({
+                    topic_id: topicID,
+                    publish_id: publishParams.publishID,
+                    sequence_id: sequenceID,
+                    recorded_at: Date.now()
+                }).execute();
+            }
+            return {
+                sequenceID,
+                deduped: false
+            };
+        });
+    }
+    async function fetch(fetchParams) {
+        // Process acks first if provided
+        if (fetchParams.ack != null && fetchParams.ack.length > 0) {
+            await ack({
+                recipientDID: fetchParams.recipientDID,
+                sequenceIDs: fetchParams.ack
+            });
+        }
+        const kysely = await db();
+        let query = kysely.selectFrom('kubun_hub_deliveries').innerJoin('kubun_hub_messages', 'kubun_hub_messages.sequence_id', 'kubun_hub_deliveries.sequence_id').select([
+            'kubun_hub_messages.sequence_id',
+            'kubun_hub_messages.sender_did',
+            'kubun_hub_messages.topic_id',
+            'kubun_hub_messages.payload',
+            'kubun_hub_messages.retain'
+        ]).where('kubun_hub_deliveries.recipient_did', '=', fetchParams.recipientDID).orderBy('kubun_hub_messages.sequence_id', 'asc');
+        if (fetchParams.after != null) {
+            query = query.where('kubun_hub_messages.sequence_id', '>', fetchParams.after);
+        }
+        const limit = fetchParams.limit;
+        if (limit != null) {
+            query = query.limit(limit + 1); // fetch one extra to determine hasMore
+        }
+        const rows = await query.execute();
+        let hasMore = false;
+        let resultRows = rows;
+        if (limit != null && rows.length > limit) {
+            hasMore = true;
+            resultRows = rows.slice(0, limit);
+        }
+        // One global sequence serves both classes here, so a log frame's own
+        // sequenceID IS its position in the topic's log. A delivery position is a
+        // different number (it spans every subscribed topic, skips the recipient's own
+        // sends, and empties as it is acked), so a recipient cannot derive the log
+        // position itself. Omitted entirely for a mailbox frame — a falsy placeholder is
+        // a position a cursor would move to, skipping every log frame below it.
+        const messages = resultRows.map((row)=>({
+                sequenceID: row.sequence_id,
+                senderDID: row.sender_did,
+                topicID: row.topic_id,
+                payload: toBytes(row.payload),
+                ...row.retain === 'log' ? {
+                    logPosition: row.sequence_id
+                } : {}
+            }));
+        const cursor = messages.length > 0 ? messages[messages.length - 1].sequenceID : null;
+        return {
+            messages,
+            cursor,
+            hasMore
+        };
+    }
+    async function fetchTopic(fetchParams) {
+        const kysely = await db();
+        const { subscriberDID, topicID } = fetchParams;
+        // Authorization: the caller must be a current subscriber of the topic.
+        const subscription = await kysely.selectFrom('kubun_hub_subscriptions').select('subscriber_did').where('topic_id', '=', topicID).where('subscriber_did', '=', subscriberDID).executeTakeFirst();
+        if (subscription == null) {
+            throw new NotSubscribedError(`${subscriberDID} is not subscribed to ${topicID}`);
+        }
+        // Head is stored state — it outlives every frame.
+        const topicRow = await kysely.selectFrom('kubun_hub_topics').select('head').where('topic_id', '=', topicID).executeTakeFirst();
+        const head = topicRow?.head ?? null;
+        // Oldest is the oldest RETAINED log frame, or null if the log is empty.
+        const oldestRow = await kysely.selectFrom('kubun_hub_messages').select((eb)=>eb.fn.min('sequence_id').as('oldest')).where('topic_id', '=', topicID).where('retain', '=', 'log').executeTakeFirst();
+        const oldest = oldestRow?.oldest ?? null;
+        // The log is the topic's log-class frames and NOTHING else — a mailbox frame
+        // never appears here. `limit` counts log frames (applied after the class
+        // filter), so a page of mailbox frames cannot hand a draining reader an empty
+        // page while log frames still wait.
+        let query = kysely.selectFrom('kubun_hub_messages').select([
+            'sequence_id',
+            'sender_did',
+            'topic_id',
+            'payload'
+        ]).where('topic_id', '=', topicID).where('retain', '=', 'log').orderBy('sequence_id', 'asc');
+        if (fetchParams.after != null) {
+            query = query.where('sequence_id', '>', fetchParams.after);
+        }
+        if (fetchParams.limit != null) {
+            query = query.limit(fetchParams.limit);
+        }
+        const rows = await query.execute();
+        // Every row here is log-class by the filter above, so each carries its position
+        // unconditionally — the same value a push of that frame reports.
+        const messages = rows.map((row)=>({
+                sequenceID: row.sequence_id,
+                senderDID: row.sender_did,
+                topicID: row.topic_id,
+                payload: toBytes(row.payload),
+                logPosition: row.sequence_id
+            }));
+        return {
+            messages,
+            head,
+            oldest
+        };
+    }
+    async function ack(ackParams) {
+        if (ackParams.sequenceIDs.length === 0) return;
+        const kysely = await db();
+        // Remove delivery entries for this recipient
+        await kysely.deleteFrom('kubun_hub_deliveries').where('recipient_did', '=', ackParams.recipientDID).where('sequence_id', 'in', ackParams.sequenceIDs).execute();
+        // GC fully-acked MAILBOX messages only. A log frame is removed by trim/purge
+        // alone — ack frees a delivery, never a log entry or the head.
+        const withDeliveries = await kysely.selectFrom('kubun_hub_deliveries').select('sequence_id').where('sequence_id', 'in', ackParams.sequenceIDs).execute();
+        const stillDelivered = new Set(withDeliveries.map((r)=>r.sequence_id));
+        const fullyAcked = ackParams.sequenceIDs.filter((id)=>!stillDelivered.has(id));
+        if (fullyAcked.length > 0) {
+            await kysely.deleteFrom('kubun_hub_messages').where('sequence_id', 'in', fullyAcked).where('retain', '=', 'mailbox').execute();
+        }
+    }
+    async function trim(trimParams) {
+        const kysely = await db();
+        // Remove LOG frames strictly below the bound, and only those. A mailbox frame
+        // on the same topic is delivery-derived and untouched. The head (topics table)
+        // and the publishID records are never touched.
+        const logRows = await kysely.selectFrom('kubun_hub_messages').select('sequence_id').where('topic_id', '=', trimParams.topicID).where('retain', '=', 'log').where('sequence_id', '<', trimParams.before).execute();
+        const sequenceIDs = logRows.map((r)=>r.sequence_id);
+        if (sequenceIDs.length === 0) return;
+        await deleteFrames(kysely, sequenceIDs);
+    }
+    async function purge(purgeParams) {
+        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.
+        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.
+        const retentionRows = await kysely.selectFrom('kubun_hub_subscriptions').select((eb)=>[
+                'topic_id',
+                eb.fn.max('retention').as('maxRetention')
+            ]).groupBy('topic_id').execute();
+        const retentionByTopic = new Map(retentionRows.map((row)=>[
+                row.topic_id,
+                Number(row.maxRetention ?? 0)
+            ]));
+        const removed = [];
+        for (const { topic_id } of topicRows){
+            const subscriberRetention = retentionByTopic.get(topic_id) ?? 0;
+            const effective = Math.max(olderThan, subscriberRetention, defaultRetention);
+            const threshold = now - effective * 1000;
+            const frames = await kysely.selectFrom('kubun_hub_messages').select('sequence_id').where('topic_id', '=', topic_id).where('stored_at', '<=', threshold).execute();
+            for (const frame of frames){
+                removed.push(frame.sequence_id);
+            }
+        }
+        if (removed.length === 0) return [];
+        await deleteFrames(kysely, removed);
+        await events.emit('purge', {
+            sequenceIDs: removed
+        });
+        return removed;
+    }
+    // `not_after` is seconds; every other timestamp here is milliseconds.
+    function nowSeconds() {
+        return Math.floor(Date.now() / 1000);
+    }
+    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) {
+        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
+        // could never be replenished and its owner would be permanently unaddable.
+        await deleteExpiredKeyPackages(kysely, ownerDID);
+        const row = await kysely.selectFrom('kubun_hub_key_packages').select((eb)=>eb.fn.countAll().as('count')).where('owner_did', '=', ownerDID).executeTakeFirst();
+        if (Number(row?.count ?? 0) >= maxKeyPackagesPerDID) {
+            throw new KeyPackageQuotaExceededError(`DID ${ownerDID} exceeds the maximum of ${maxKeyPackagesPerDID} stored key packages`);
+        }
+        await kysely.insertInto('kubun_hub_key_packages').values({
+            owner_did: ownerDID,
+            key_package: keyPackage,
+            not_after: notAfter ?? null
+        }).execute();
+    }
+    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
+        // packages waited behind them.
+        await deleteExpiredKeyPackages(kysely, ownerDID);
+        const limit = count ?? 1;
+        // Atomic delete-returning: a non-atomic select+delete pair would let two
+        // concurrent fetches return the same key package twice.
+        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) {
+        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),
+                eb('not_after', '>', nowSeconds())
+            ])).executeTakeFirst();
+        return Number(row?.count ?? 0);
+    }
+    async function storeLastResortKeyPackage(ownerDID, keyPackage) {
+        const kysely = await db();
+        await kysely.insertInto('kubun_hub_last_resort_key_packages').values({
+            owner_did: ownerDID,
+            key_package: keyPackage
+        }).onConflict((oc)=>oc.column('owner_did').doUpdateSet({
+                key_package: (eb)=>eb.ref('excluded.key_package')
+            })).execute();
+    }
+    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
+        // init-key reuse `fetchKeyPackages` exists to prevent.
+        const row = await kysely.selectFrom('kubun_hub_last_resort_key_packages').select('key_package').where('owner_did', '=', ownerDID).executeTakeFirst();
+        return row?.key_package ?? null;
+    }
+    async function subscribe(subscribeParams) {
+        const { subscriberDID, topicID } = subscribeParams;
+        // A retention above the hub maximum is refused, never clamped — a peer that
+        // believed it had asked for more would otherwise be stranded.
+        if (subscribeParams.retention != null && maxRetention != null && subscribeParams.retention > maxRetention) {
+            throw new RetentionExceededError(`requested retention ${subscribeParams.retention} exceeds the hub maximum ${maxRetention}`);
+        }
+        const retention = subscribeParams.retention ?? defaultRetention;
+        const kysely = await db();
+        // Charged on NEW rows only: a re-subscribe to a topic this DID already holds is a
+        // refresh, and refusing it would strand a subscriber at the cap on every reconnect.
+        const held = await kysely.selectFrom('kubun_hub_subscriptions').select('topic_id').where('subscriber_did', '=', subscriberDID).execute();
+        if (!held.some((row)=>row.topic_id === topicID) && held.length >= maxSubscriptionsPerDID) {
+            throw new SubscriptionQuotaExceededError(`DID ${subscriberDID} exceeds the maximum of ${maxSubscriptionsPerDID} subscriptions`);
+        }
+        // Upsert on the (topic_id, subscriber_did) primary key so re-subscribing an
+        // existing subscriber refreshes its activity timestamp and retention rather
+        // than failing or duplicating.
+        await kysely.insertInto('kubun_hub_subscriptions').values({
+            topic_id: topicID,
+            subscriber_did: subscriberDID,
+            last_active_at: Date.now(),
+            retention
+        }).onConflict((oc)=>oc.columns([
+                'topic_id',
+                'subscriber_did'
+            ]).doUpdateSet({
+                last_active_at: (eb)=>eb.ref('excluded.last_active_at'),
+                retention: (eb)=>eb.ref('excluded.retention')
+            })).execute();
+    }
+    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
+        // pending deliveries for the topic and GCs any MAILBOX frame left without a
+        // recipient. A log frame (which trim alone may remove) and the head are never
+        // touched.
+        const pending = await kysely.selectFrom('kubun_hub_deliveries').innerJoin('kubun_hub_messages', 'kubun_hub_messages.sequence_id', 'kubun_hub_deliveries.sequence_id').select('kubun_hub_deliveries.sequence_id').where('kubun_hub_deliveries.recipient_did', '=', subscriberDID).where('kubun_hub_messages.topic_id', '=', topicID).execute();
+        if (pending.length === 0) return;
+        const sequenceIDs = pending.map((r)=>r.sequence_id);
+        await kysely.deleteFrom('kubun_hub_deliveries').where('recipient_did', '=', subscriberDID).where('sequence_id', 'in', sequenceIDs).execute();
+        const remaining = await kysely.selectFrom('kubun_hub_deliveries').select('sequence_id').where('sequence_id', 'in', sequenceIDs).execute();
+        const stillDelivered = new Set(remaining.map((r)=>r.sequence_id));
+        const orphaned = sequenceIDs.filter((id)=>!stillDelivered.has(id));
+        if (orphaned.length > 0) {
+            await kysely.deleteFrom('kubun_hub_messages').where('sequence_id', 'in', orphaned).where('retain', '=', 'mailbox').execute();
+        }
+    }
+    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);
+    }
+    async function purgeSubscribers(purgeParams) {
+        const kysely = await db();
+        // Strict `<`: a row refreshed exactly at the boundary survives. Subscription
+        // retention runs on a much longer window than message purge.
+        const threshold = Date.now() - purgeParams.olderThan * 1000;
+        // Atomic delete-and-return so the reported set exactly matches the rows
+        // actually removed — a subscriber who rejoins between evaluating and deleting
+        // is neither reaped nor over-reported. Mirrors `fetchKeyPackages`.
+        const deletedRows = await kysely.deleteFrom('kubun_hub_subscriptions').where('last_active_at', '<', threshold).returning([
+            'topic_id',
+            'subscriber_did'
+        ]).execute();
+        return deletedRows.map((row)=>({
+                topicID: row.topic_id,
+                subscriberDID: row.subscriber_did
+            }));
+    }
+    return {
+        events,
+        publish,
+        fetch,
+        fetchTopic,
+        ack,
+        purge,
+        trim,
+        purgeSubscribers,
+        storeKeyPackage,
+        fetchKeyPackages,
+        countKeyPackages,
+        storeLastResortKeyPackage,
+        fetchLastResortKeyPackage,
+        subscribe,
+        unsubscribe,
+        getSubscribers
+    };
+}

package/lib/index.d.ts

@@ -1,13 +1,13 @@
-import type { Identity } from '@enkaku/token';
+import type { Identity } from '@kokuin/token';
 import type { Adapter } from '@kubun/db-adapter';
 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 CreateRelayOptions, createRelay, createRelayInternal, type HubAuthConfig, type Relay, type RelayRetentionConfig, } from './create-relay.js';
-export { type CreateHubStoreParams, createHubStore, type HubDatabase } from './hub-store.js';
+export { type CreateHubStoreParams, createHubStore, type HubDatabase, type KubunHubStore, type PurgedSubscription, type PurgeSubscriptionsParams, } from './hub-store.js';
 export { createHubMigrations, type MigrationContext } from './migrations.js';
-export { decorateHubStore, type RelayObserverAckInfo, type RelayObserverAuthRejectedInfo, type RelayObserverErrorInfo, type RelayObserverErrorStage, type RelayObserverFetchInfo, type RelayObserverPurgeInfo, type RelayObserverStoreInfo, type RelayObservers, } from './observers.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 = {
     /** Kysely instance for the hub database. */
     kysely: Kysely<HubDatabase>;
@@ -18,14 +18,14 @@ export type HubOptions = {
     /** Allowed CORS origin(s). Default: ['*']. */
     allowedOrigin?: string | Array<string>;
     /**
-     * Hub server identity. Required when `auth` is provided — the server
-     * signs response tokens and clients pin its DID for TOFU verification.
+     * Hub server identity. Required — the server signs response tokens, derives
+     * the sender DID from each verified request, and clients pin its DID for
+     * TOFU verification.
      */
-    identity?: Identity;
+    identity: Identity;
     /**
-     * Authentication configuration. When omitted, the hub runs without
-     * access control (back-compat). When provided, `identity` must also be
-     * provided.
+     * Authentication configuration layered over the required identity. When
+     * omitted, no access rules are configured beyond signature verification.
      */
     auth?: HubAuthConfig;
     /** Optional retention scheduler. */

package/lib/index.js

@@ -1 +1,42 @@
-import{serve as e}from"@hono/node-server";import t from"get-port";import{Hono as r}from"hono";import{createRelayInternal as o}from"./create-relay.js";export{createRelay,createRelayInternal}from"./create-relay.js";export{createHubStore}from"./hub-store.js";export{createHubMigrations}from"./migrations.js";export{decorateHubStore}from"./observers.js";export async function createHub(a){let s=await o({kysely:a.kysely,adapter:a.adapter,identity:a.identity,auth:a.auth,allowedOrigin:a.allowedOrigin,retention:a.retention,observers:a.observers,ownsKysely:!1}),i=new r;i.get("/health",e=>e.json({status:"ok"})),i.post("*",async e=>s.fetch(e.req.raw)),i.options("*",async e=>s.fetch(e.req.raw));let n=a.port??await t(),c=`http://localhost:${n}`,l=await new Promise(t=>{let r=e({fetch:i.fetch,port:n},()=>t(r))});return{port:n,url:c,dispose:async()=>{await s.dispose(),l.close()}}}
+import { serve } from '@hono/node-server';
+import getPort from 'get-port';
+import { Hono } from 'hono';
+import { createRelayInternal } from './create-relay.js';
+export { createRelay, createRelayInternal } from './create-relay.js';
+export { createHubStore } from './hub-store.js';
+export { createHubMigrations } from './migrations.js';
+export { decorateHubStore } from './observers.js';
+export async function createHub(options) {
+    const relay = await createRelayInternal({
+        kysely: options.kysely,
+        adapter: options.adapter,
+        identity: options.identity,
+        auth: options.auth,
+        allowedOrigin: options.allowedOrigin,
+        retention: options.retention,
+        observers: options.observers,
+        ownsKysely: false
+    });
+    const app = new Hono();
+    app.get('/health', (c)=>c.json({
+            status: 'ok'
+        }));
+    app.post('*', async (c)=>relay.fetch(c.req.raw));
+    app.options('*', async (c)=>relay.fetch(c.req.raw));
+    const port = options.port ?? await getPort();
+    const url = `http://localhost:${port}`;
+    const httpServer = await new Promise((resolve)=>{
+        const server = serve({
+            fetch: app.fetch,
+            port
+        }, ()=>resolve(server));
+    });
+    return {
+        port,
+        url,
+        dispose: async ()=>{
+            await relay.dispose();
+            httpServer.close();
+        }
+    };
+}

package/lib/migrations.js

@@ -1 +1,68 @@
-export function createHubMigrations(e){let t=e.types;return{"001_create_hub_tables":{async up(e){await e.schema.createTable("kubun_hub_messages").ifNotExists().addColumn("sequence_id",t.text,e=>e.notNull().primaryKey()).addColumn("sender_did",t.text,e=>e.notNull()).addColumn("group_id",t.text).addColumn("payload",t.binary,e=>e.notNull()).addColumn("stored_at","integer",e=>e.notNull()).execute(),await e.schema.createTable("kubun_hub_deliveries").ifNotExists().addColumn("sequence_id",t.text,e=>e.notNull()).addColumn("recipient_did",t.text,e=>e.notNull()).addPrimaryKeyConstraint("pk_hub_deliveries",["sequence_id","recipient_did"]).execute(),await e.schema.createIndex("idx_hub_deliveries_recipient").ifNotExists().on("kubun_hub_deliveries").column("recipient_did").execute(),await e.schema.createTable("kubun_hub_key_packages").ifNotExists().addColumn("id",t.serial,e=>e.primaryKey()).addColumn("owner_did",t.text,e=>e.notNull()).addColumn("key_package",t.text,e=>e.notNull()).execute(),await e.schema.createIndex("idx_hub_key_packages_owner").ifNotExists().on("kubun_hub_key_packages").column("owner_did").execute(),await e.schema.createTable("kubun_hub_group_members").ifNotExists().addColumn("group_id",t.text,e=>e.notNull()).addColumn("member_did",t.text,e=>e.notNull()).addPrimaryKeyConstraint("pk_hub_group_members",["group_id","member_did"]).execute()},async down(e){await e.schema.dropTable("kubun_hub_group_members").ifExists().execute(),await e.schema.dropTable("kubun_hub_key_packages").ifExists().execute(),await e.schema.dropTable("kubun_hub_deliveries").ifExists().execute(),await e.schema.dropTable("kubun_hub_messages").ifExists().execute()}}}}
+import { sql } from 'kysely';
+export function createHubMigrations(ctx) {
+    const t = ctx.types;
+    return {
+        '001_create_hub_tables': {
+            async up (db) {
+                // Hub messages
+                await db.schema.createTable('kubun_hub_messages').ifNotExists().addColumn('sequence_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('sender_did', t.text, (col)=>col.notNull()).addColumn('topic_id', t.text, (col)=>col.notNull()).addColumn('payload', t.binary, (col)=>col.notNull()).addColumn('stored_at', t.bigint, (col)=>col.notNull())// Retention class: 'mailbox' is delivery-derived, 'log' is topic-retained.
+                .addColumn('retain', t.text, (col)=>col.notNull().defaultTo('mailbox')).execute();
+                // Hub deliveries
+                await db.schema.createTable('kubun_hub_deliveries').ifNotExists().addColumn('sequence_id', t.text, (col)=>col.notNull()).addColumn('recipient_did', t.text, (col)=>col.notNull()).addPrimaryKeyConstraint('pk_hub_deliveries', [
+                    'sequence_id',
+                    'recipient_did'
+                ]).execute();
+                await db.schema.createIndex('idx_hub_deliveries_recipient').ifNotExists().on('kubun_hub_deliveries').column('recipient_did').execute();
+                // Hub key packages
+                await db.schema.createTable('kubun_hub_key_packages').ifNotExists().addColumn('id', t.serial, (col)=>col.primaryKey()).addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('key_package', t.text, (col)=>col.notNull())// Expiry in SECONDS, unlike every millisecond column here. Null never expires.
+                .addColumn('not_after', t.bigint).execute();
+                await db.schema.createIndex('idx_hub_key_packages_owner').ifNotExists().on('kubun_hub_key_packages').column('owner_did').execute();
+                // The last-resort slot gets its OWN table so no ordinary-pool query can reach
+                // it: it is reusable and uncapped, and both properties invert the pool's. The
+                // primary key is what holds "one slot per owner".
+                await db.schema.createTable('kubun_hub_last_resort_key_packages').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull().primaryKey()).addColumn('key_package', t.text, (col)=>col.notNull()).execute();
+                // Hub subscriptions
+                await db.schema.createTable('kubun_hub_subscriptions').ifNotExists().addColumn('topic_id', t.text, (col)=>col.notNull()).addColumn('subscriber_did', t.text, (col)=>col.notNull()).addColumn('last_active_at', t.bigint, (col)=>col.notNull().defaultTo(0))// Requested retention (seconds). The topic's age bound is the longest any
+                // current subscriber asked for, floored at the hub default.
+                .addColumn('retention', t.bigint, (col)=>col.notNull().defaultTo(0)).addPrimaryKeyConstraint('pk_hub_subscriptions', [
+                    'topic_id',
+                    'subscriber_did'
+                ]).execute();
+                // Stored per-topic head: the sequenceID of the last accepted log publish.
+                // Stored state, NOT a projection — it outlives every frame, so a trim or
+                // purge that empties the log leaves it standing.
+                await db.schema.createTable('kubun_hub_topics').ifNotExists().addColumn('topic_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('head', t.text, (col)=>col.notNull()).execute();
+                // Persistent, global, monotonic sequence counter. Persisted (not derived
+                // from surviving frames) so trimming or purging a topic to empty never
+                // regresses minting below a head the topic still names. Global so a
+                // sequenceID is unique across topics and the mailbox fetch stays globally
+                // ordered.
+                await db.schema.createTable('kubun_hub_sequence').ifNotExists().addColumn('id', t.bigint, (col)=>col.notNull().primaryKey()).addColumn('counter', t.bigint, (col)=>col.notNull()).execute();
+                await sql`INSERT INTO kubun_hub_sequence (id, counter) VALUES (0, 0)`.execute(db);
+                // Idempotency records: publishID -> sequenceID. Its OWN table, so trim and
+                // purge never remove it; its retention is its own (indefinite). Scoped per
+                // topic lane.
+                await db.schema.createTable('kubun_hub_publish_ids').ifNotExists().addColumn('topic_id', t.text, (col)=>col.notNull()).addColumn('publish_id', t.text, (col)=>col.notNull()).addColumn('sequence_id', t.text, (col)=>col.notNull())// Every commit publish writes a row here and nothing else ever deletes one,
+                // so on a long-lived hub this is the fastest-growing table, outliving frames
+                // purged years earlier. The contract only requires that trim and purge never
+                // take a record while the FRAME it dedups survives; keeping records forever
+                // was never part of it. This column is what lets `purge` sweep them on a
+                // window longer than any plausible replay.
+                .addColumn('recorded_at', t.bigint, (col)=>col.notNull().defaultTo(0)).addPrimaryKeyConstraint('pk_hub_publish_ids', [
+                    'topic_id',
+                    'publish_id'
+                ]).execute();
+            },
+            async down (db) {
+                await db.schema.dropTable('kubun_hub_publish_ids').ifExists().execute();
+                await db.schema.dropTable('kubun_hub_last_resort_key_packages').ifExists().execute();
+                await db.schema.dropTable('kubun_hub_sequence').ifExists().execute();
+                await db.schema.dropTable('kubun_hub_topics').ifExists().execute();
+                await db.schema.dropTable('kubun_hub_subscriptions').ifExists().execute();
+                await db.schema.dropTable('kubun_hub_key_packages').ifExists().execute();
+                await db.schema.dropTable('kubun_hub_deliveries').ifExists().execute();
+                await db.schema.dropTable('kubun_hub_messages').ifExists().execute();
+            }
+        }
+    };
+}

package/lib/observers.d.ts

@@ -1,8 +1,7 @@
-import type { HubStore } from '@enkaku/hub-protocol';
+import type { KubunHubStore } from './hub-store.js';
 export type RelayObserverStoreInfo = {
     senderDID: string;
-    groupID?: string;
-    recipientCount: number;
+    topicID: string;
     sequenceID: string;
 };
 export type RelayObserverFetchInfo = {
@@ -16,10 +15,17 @@ export type RelayObserverAckInfo = {
 export type RelayObserverPurgeInfo = {
     sequenceCount: number;
 };
+export type RelayObserverSubscriptionPurgeInfo = {
+    subscriptionCount: number;
+};
 export type RelayObserverAuthRejectedInfo = {
     reason: string;
 };
-export type RelayObserverErrorStage = 'store' | 'fetch' | 'ack' | 'purge';
+export type RelayObserverRetentionConfigClampedInfo = {
+    configuredSubscriptionOlderThanSeconds: number;
+    clampedToSeconds: number;
+};
+export type RelayObserverErrorStage = 'store' | 'fetch' | 'ack' | 'purge' | 'subscription-purge';
 export type RelayObserverErrorInfo = {
     stage: RelayObserverErrorStage;
     error: unknown;
@@ -29,7 +35,9 @@ export type RelayObservers = {
     onFetch?: (info: RelayObserverFetchInfo) => void;
     onAck?: (info: RelayObserverAckInfo) => void;
     onPurge?: (info: RelayObserverPurgeInfo) => void;
+    onSubscriptionPurge?: (info: RelayObserverSubscriptionPurgeInfo) => void;
     onAuthRejected?: (info: RelayObserverAuthRejectedInfo) => void;
+    onRetentionConfigClamped?: (info: RelayObserverRetentionConfigClampedInfo) => void;
     onError?: (info: RelayObserverErrorInfo) => void;
 };
-export declare function decorateHubStore(store: HubStore, observers?: RelayObservers): HubStore;
+export declare function decorateHubStore(store: KubunHubStore, observers?: RelayObservers): KubunHubStore;

package/lib/observers.js

@@ -1 +1,76 @@
-function e(e,t){if(null!=e)try{e(t)}catch{}}export function decorateHubStore(t,r){if(null==r)return t;let{onStore:n,onFetch:c,onAck:s,onError:a}=r;return{events:t.events,storeKeyPackage:t.storeKeyPackage.bind(t),fetchKeyPackages:t.fetchKeyPackages.bind(t),setGroupMembers:t.setGroupMembers.bind(t),getGroupMembers:t.getGroupMembers.bind(t),purge:t.purge.bind(t),async store(r){try{let c=await t.store(r);return e(n,{senderDID:r.senderDID,groupID:r.groupID,recipientCount:r.recipients.length,sequenceID:c}),c}catch(t){throw e(a,{stage:"store",error:t}),t}},async fetch(r){try{let n=await t.fetch(r);return e(c,{recipientDID:r.recipientDID,messageCount:n.messages.length}),n}catch(t){throw e(a,{stage:"fetch",error:t}),t}},async ack(r){try{await t.ack(r),e(s,{recipientDID:r.recipientDID,sequenceCount:r.sequenceIDs.length})}catch(t){throw e(a,{stage:"ack",error:t}),t}}}}
+function safeCall(callback, info) {
+    if (callback == null) return;
+    try {
+        callback(info);
+    } catch  {
+    // Observer callbacks are diagnostics — never let them break the relay.
+    }
+}
+export function decorateHubStore(store, observers) {
+    if (observers == null) return store;
+    const { onStore, onFetch, onAck, onError } = observers;
+    const wrappedStore = {
+        events: store.events,
+        storeKeyPackage: store.storeKeyPackage.bind(store),
+        fetchKeyPackages: store.fetchKeyPackages.bind(store),
+        countKeyPackages: store.countKeyPackages.bind(store),
+        storeLastResortKeyPackage: store.storeLastResortKeyPackage.bind(store),
+        fetchLastResortKeyPackage: store.fetchLastResortKeyPackage.bind(store),
+        subscribe: store.subscribe.bind(store),
+        unsubscribe: store.unsubscribe.bind(store),
+        getSubscribers: store.getSubscribers.bind(store),
+        purgeSubscribers: store.purgeSubscribers.bind(store),
+        purge: store.purge.bind(store),
+        fetchTopic: store.fetchTopic.bind(store),
+        trim: store.trim.bind(store),
+        async publish (params) {
+            try {
+                const result = await store.publish(params);
+                safeCall(onStore, {
+                    senderDID: params.senderDID,
+                    topicID: params.topicID,
+                    sequenceID: result.sequenceID
+                });
+                return result;
+            } catch (error) {
+                safeCall(onError, {
+                    stage: 'store',
+                    error
+                });
+                throw error;
+            }
+        },
+        async fetch (params) {
+            try {
+                const result = await store.fetch(params);
+                safeCall(onFetch, {
+                    recipientDID: params.recipientDID,
+                    messageCount: result.messages.length
+                });
+                return result;
+            } catch (error) {
+                safeCall(onError, {
+                    stage: 'fetch',
+                    error
+                });
+                throw error;
+            }
+        },
+        async ack (params) {
+            try {
+                await store.ack(params);
+                safeCall(onAck, {
+                    recipientDID: params.recipientDID,
+                    sequenceCount: params.sequenceIDs.length
+                });
+            } catch (error) {
+                safeCall(onError, {
+                    stage: 'ack',
+                    error
+                });
+                throw error;
+            }
+        }
+    };
+    return wrappedStore;
+}

package/package.json

@@ -1,45 +1,51 @@
 {
   "name": "@kubun/hub",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "license": "see LICENSE.md",
+  "sideEffects": false,
   "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "exports": {
     ".": "./lib/index.js"
   },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
     "lib/*",
     "LICENSE.md"
   ],
-  "sideEffects": false,
   "dependencies": {
-    "@enkaku/event": "^0.16.0",
-    "@enkaku/http-server-transport": "^0.16.0",
-    "@enkaku/hub-protocol": "^0.16.0",
-    "@enkaku/hub-server": "^0.16.0",
-    "@enkaku/server": "^0.16.0",
-    "@enkaku/token": "^0.16.0",
-    "@hono/node-server": "^2.0.4",
+    "@enkaku/http-serve": "^0.20.0",
+    "@enkaku/server": "^0.20.0",
+    "@hono/node-server": "^2.1.0",
+    "@kokuin/token": "^0.3.0",
+    "@kumiai/hub-protocol": "^0.5.0",
+    "@kumiai/hub-server": "^0.5.0",
+    "@sozai/event": "^0.1.3",
     "get-port": "^7.2.0",
-    "hono": "^4.12.23",
-    "kysely": "^0.29.2",
-    "@kubun/db-adapter": "^0.10.0",
-    "@kubun/db-provider": "^0.10.0"
+    "hono": "^4.13.0",
+    "kysely": "^0.29.4",
+    "@kubun/db-adapter": "^0.12.0",
+    "@kubun/db-provider": "^0.12.0",
+    "@kubun/http-util": "^0.12.0"
   },
   "devDependencies": {
-    "@enkaku/async": "^0.16.0",
-    "@enkaku/client": "^0.16.0",
-    "@enkaku/http-client-transport": "^0.16.0",
-    "@enkaku/protocol": "^0.16.0",
-    "@enkaku/transport": "^0.16.0",
-    "@kubun/db-node-sqlite": "^0.10.0",
-    "@kubun/db-better-sqlite": "^0.10.0"
+    "@enkaku/client": "^0.20.0",
+    "@enkaku/http-fetch": "^0.20.0",
+    "@enkaku/protocol": "^0.20.0",
+    "@enkaku/transport": "^0.20.0",
+    "@kumiai/hub-conformance": "^0.5.0",
+    "@kumiai/mls": "^0.5.0",
+    "@sozai/async": "^0.2.1",
+    "@testcontainers/postgresql": "^12.1.0",
+    "@kubun/db-better-sqlite": "^0.12.0",
+    "@kubun/db-node-sqlite": "^0.12.0",
+    "@kubun/db-postgres": "^0.12.0"
   },
   "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
-    "build:js": "swc src -d ./lib --config-file ../../swc.json --strip-leading-paths",
+    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
-    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types"
+    "test:types": "tsc --noEmit -p tsconfig.test.json"
   }
 }