@enbox/dwn-server 0.0.7 → 0.0.8

package/src/http-api.ts

@@ -3,8 +3,11 @@ import type { RecordsReadReply } from '@enbox/dwn-sdk-js';
 import type { ServerInfo } from '@enbox/dwn-clients';
 import type { Server, ServerWebSocket } from 'bun';
 
+import type { Dialect } from '@enbox/dwn-sql-store';
+
 import type { ActivityLog } from './admin/activity-log.js';
 import type { AdminApi } from './admin/admin-api.js';
+import type { AdminSessionManager } from './admin/admin-session.js';
 import type { AdminStore } from './admin/admin-store.js';
 import type { DwnServerConfig } from './config.js';
 import type { DwnServerError } from './dwn-error.js';
@@ -27,6 +30,7 @@ import { existsSync, readFileSync } from 'fs';
 import { join, resolve } from 'path';
 
 import { config } from './config.js';
+import { getDialectFromUrl } from './storage.js';
 import { jsonRpcRouter } from './json-rpc-api.js';
 import { validateAdminAuth } from './admin/admin-auth.js';
 import { Web5ConnectServer } from './web5-connect/web5-connect-server.js';
@@ -62,6 +66,7 @@ export class HttpApi {
   #tenantRateLimiter: RateLimiter | undefined;
   #messageProcessedHooks: MessageProcessedHook[];
   #openAuthHandler: OpenAuthHandler | undefined;
+  #sessionManager: AdminSessionManager | undefined;
   #adminUiPath: string | undefined;
   web5ConnectServer: Web5ConnectServer;
   registrationManager: RegistrationManager;
@@ -82,6 +87,8 @@ export class HttpApi {
       tenantRateLimiter? : RateLimiter;
       messageProcessedHooks? : MessageProcessedHook[];
       openAuthHandler? : OpenAuthHandler;
+      sessionManager? : AdminSessionManager;
+      ttlCacheDialect? : Dialect;
     },
   ): Promise<HttpApi> {
     const httpApi = new HttpApi();
@@ -119,15 +126,20 @@ export class HttpApi {
     httpApi.#tenantRateLimiter = options?.tenantRateLimiter;
     httpApi.#messageProcessedHooks = options?.messageProcessedHooks ?? [];
     httpApi.#openAuthHandler = options?.openAuthHandler;
+    httpApi.#sessionManager = options?.sessionManager;
     httpApi.#adminUiPath = resolvedAdminUiPath;
 
     if (registrationManager !== undefined) {
       httpApi.registrationManager = registrationManager;
     }
 
+    // Use an externally provided dialect when available (required for
+    // in-memory SQLite so that migrations and the TTL cache share the same
+    // database instance). Falls back to creating a dialect from the URL.
+    const ttlDialect = options?.ttlCacheDialect ?? getDialectFromUrl(new URL(config.ttlCacheUrl));
     httpApi.web5ConnectServer = await Web5ConnectServer.create({
-      baseUrl        : config.baseUrl,
-      sqlTtlCacheUrl : config.ttlCacheUrl,
+      baseUrl    : config.baseUrl,
+      sqlDialect : ttlDialect,
     });
 
     return httpApi;
@@ -258,6 +270,9 @@ export class HttpApi {
     if (this.#openAuthHandler) {
       this.#openAuthHandler.destroy();
     }
+    if (this.web5ConnectServer) {
+      this.web5ConnectServer.close();
+    }
     if (this.#server) {
       this.#server.stop(true); // close all connections immediately
     }
@@ -321,9 +336,9 @@ export class HttpApi {
     if (method === 'GET' && path === '/metrics') {
       // Metrics require admin authentication when an admin token is configured.
       if (this.#config.adminToken) {
-        const authError = validateAdminAuth(req, this.#config);
-        if (authError) {
-          return authError;
+        const authResult = validateAdminAuth(req, this.#config, this.#sessionManager);
+        if (authResult.error) {
+          return authResult.error;
         }
       }
       try {

package/src/migrations/001-initial-server-schema.ts

@@ -0,0 +1,114 @@
+import type { Dialect } from '@enbox/dwn-sql-store';
+import type { Kysely, Migration } from 'kysely';
+
+/**
+ * Factory type for server migrations. Mirrors the `DwnMigrationFactory` from
+ * `@enbox/dwn-sql-store` — receives the {@link Dialect} so migrations can use
+ * dialect-specific helpers like `addAutoIncrementingColumn()`.
+ */
+export type ServerMigrationFactory = (dialect: Dialect) => Migration;
+
+/**
+ * Baseline server migration: creates all DWN server admin and cache tables.
+ *
+ * Tables:
+ * - `registeredTenants`: tenant registration data
+ * - `tenantQuotas`: per-tenant storage quotas
+ * - `adminAuditLog`: append-only admin event log
+ * - `adminWebhooks`: webhook registrations
+ * - `adminPasskeys`: WebAuthn admin passkeys
+ * - `cacheEntries`: TTL-based key/value cache (Web5 Connect state, etc.)
+ */
+export const migration001InitialServerSchema: ServerMigrationFactory = (dialect): Migration => ({
+
+  async up(db: Kysely<any>): Promise<void> {
+
+    // ─── registeredTenants ────────────────────────────────────────────
+    await db.schema
+      .createTable('registeredTenants')
+      .ifNotExists()
+      .addColumn('did', 'text', (col) => col.primaryKey())
+      .addColumn('termsOfServiceHash', 'text')
+      .addColumn('suspended', 'integer', (col) => col.defaultTo(0))
+      .addColumn('accountId', 'text')
+      .addColumn('registrationType', 'text')
+      .addColumn('registeredAt', 'text')
+      .addColumn('metadata', 'text')
+      .execute();
+
+    // ─── tenantQuotas ─────────────────────────────────────────────────
+    await db.schema
+      .createTable('tenantQuotas')
+      .ifNotExists()
+      .addColumn('did', 'text', (col) => col.primaryKey())
+      .addColumn('maxMessages', 'integer', (col) => col.defaultTo(0))
+      .addColumn('maxStorageBytes', 'bigint', (col) => col.defaultTo(0))
+      .execute();
+
+    // ─── adminAuditLog ────────────────────────────────────────────────
+    let auditTable = db.schema
+      .createTable('adminAuditLog')
+      .ifNotExists()
+      .addColumn('timestamp', 'text', (col) => col.notNull())
+      .addColumn('actor', 'text', (col) => col.notNull())
+      .addColumn('action', 'text', (col) => col.notNull())
+      .addColumn('target', 'text')
+      .addColumn('detail', 'text');
+
+    auditTable = dialect.addAutoIncrementingColumn(auditTable, 'id', (col) => col.primaryKey());
+    await auditTable.execute();
+
+    try {
+      await db.schema.createIndex('index_audit_timestamp')
+        .ifNotExists().on('adminAuditLog').column('timestamp').execute();
+    } catch { /* index already exists */ }
+
+    try {
+      await db.schema.createIndex('index_audit_target')
+        .ifNotExists().on('adminAuditLog').column('target').execute();
+    } catch { /* index already exists */ }
+
+    try {
+      await db.schema.createIndex('index_audit_action')
+        .ifNotExists().on('adminAuditLog').column('action').execute();
+    } catch { /* index already exists */ }
+
+    // ─── adminWebhooks ────────────────────────────────────────────────
+    await db.schema
+      .createTable('adminWebhooks')
+      .ifNotExists()
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('url', 'text', (col) => col.notNull())
+      .addColumn('events', 'text', (col) => col.notNull())
+      .addColumn('secret', 'text')
+      .addColumn('createdAt', 'text', (col) => col.notNull())
+      .execute();
+
+    // ─── adminPasskeys ────────────────────────────────────────────────
+    await db.schema
+      .createTable('adminPasskeys')
+      .ifNotExists()
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('name', 'text', (col) => col.notNull())
+      .addColumn('publicKey', 'text', (col) => col.notNull())
+      .addColumn('counter', 'integer', (col) => col.notNull().defaultTo(0))
+      .addColumn('transports', 'text', (col) => col.notNull().defaultTo('[]'))
+      .addColumn('createdAt', 'text', (col) => col.notNull())
+      .addColumn('lastUsedAt', 'text')
+      .execute();
+
+    // ─── cacheEntries (TTL cache) ─────────────────────────────────────
+    await db.schema
+      .createTable('cacheEntries')
+      .ifNotExists()
+      .addColumn('key', 'varchar(512)', (col) => col.primaryKey())
+      .addColumn('value', 'text', (col) => col.notNull())
+      .addColumn('expiry', 'bigint', (col) => col.notNull())
+      .execute();
+
+    try {
+      await db.schema.createIndex('index_expiry')
+        .ifNotExists().on('cacheEntries').column('expiry').execute();
+    } catch { /* index already exists */ }
+  },
+});

package/src/migrations/index.ts

@@ -0,0 +1,18 @@
+import type { ServerMigrationFactory } from './001-initial-server-schema.js';
+
+import { migration001InitialServerSchema } from './001-initial-server-schema.js';
+
+/**
+ * All DWN server migrations in sequential order.
+ *
+ * Each entry is a `[name, factory]` tuple where the factory receives the
+ * `Dialect` and returns a standard Kysely `Migration`. This mirrors the
+ * pattern used by DWN store migrations in `@enbox/dwn-sql-store`.
+ *
+ * **Ordering contract:** Entries MUST be sorted by name (lexicographic).
+ */
+export type { ServerMigrationFactory };
+
+export const allServerMigrations: ReadonlyArray<readonly [name: string, factory: ServerMigrationFactory]> = [
+  ['001-initial-server-schema', migration001InitialServerSchema],
+];

package/src/registration/registration-store.ts

@@ -29,47 +29,24 @@ export class RegistrationStore {
     return store;
   }
 
+  /**
+   * Verifies that the required tables exist. Throws a clear error directing
+   * the caller to run server migrations first.
+   */
   private async initialize(): Promise<void> {
-    await this.db.schema
-      .createTable(RegistrationStore.registeredTenantTableName)
-      .ifNotExists()
-      .addColumn('did', 'text', (column) => column.primaryKey())
-      .addColumn('termsOfServiceHash', 'text')
-      .addColumn('suspended', 'integer', (column) => column.defaultTo(0))
-      .execute();
-
-    // Add the `suspended` column to existing tables that don't have it yet.
-    // Kysely doesn't support `ADD COLUMN IF NOT EXISTS` across all dialects, so we
-    // catch and ignore the "column already exists" error.
-    try {
-      await this.db.schema
-        .alterTable(RegistrationStore.registeredTenantTableName)
-        .addColumn('suspended', 'integer', (column) => column.defaultTo(0))
-        .execute();
-    } catch {
-      // Column already exists — expected for new installations.
-    }
-
-    // Add provider-auth columns (idempotent migration). https://github.com/enboxorg/enbox/issues/404
-    for (const col of ['accountId', 'registrationType', 'registeredAt', 'metadata']) {
+    const tables = [
+      RegistrationStore.registeredTenantTableName,
+      RegistrationStore.tenantQuotasTableName,
+    ];
+    for (const table of tables) {
       try {
-        await this.db.schema
-          .alterTable(RegistrationStore.registeredTenantTableName)
-          .addColumn(col, 'text')
-          .execute();
+        await sql`SELECT 1 FROM ${sql.table(table)} LIMIT 0`.execute(this.db);
       } catch {
-        // Column already exists — expected.
+        throw new Error(
+          `RegistrationStore: table '${table}' does not exist. Run server migrations before starting.`
+        );
       }
     }
-
-    // Per-tenant storage quotas table.
-    await this.db.schema
-      .createTable(RegistrationStore.tenantQuotasTableName)
-      .ifNotExists()
-      .addColumn('did', 'text', (column) => column.primaryKey())
-      .addColumn('maxMessages', 'integer', (column) => column.defaultTo(0))
-      .addColumn('maxStorageBytes', 'bigint', (column) => column.defaultTo(0))
-      .execute();
   }
 
   /**

package/src/server-migration-runner.ts

@@ -0,0 +1,74 @@
+import type { Dialect } from '@enbox/dwn-sql-store';
+import type { ServerMigrationFactory } from './migrations/index.js';
+import type { Kysely, Migration, MigrationProvider, MigrationResultSet } from 'kysely';
+
+import { allServerMigrations } from './migrations/index.js';
+import { Migrator } from 'kysely';
+
+/**
+ * {@link MigrationProvider} for server migrations. Wraps an ordered list of
+ * `(name, factory)` pairs. At resolution time each factory is called with the
+ * dialect, producing the concrete Kysely {@link Migration} objects.
+ */
+class ServerMigrationProvider implements MigrationProvider {
+  #dialect: Dialect;
+  #factories: ReadonlyArray<readonly [name: string, factory: ServerMigrationFactory]>;
+
+  constructor(
+    dialect: Dialect,
+    factories: ReadonlyArray<readonly [name: string, factory: ServerMigrationFactory]>,
+  ) {
+    this.#dialect = dialect;
+    this.#factories = factories;
+  }
+
+  public async getMigrations(): Promise<Record<string, Migration>> {
+    const migrations: Record<string, Migration> = {};
+    for (const [name, factory] of this.#factories) {
+      migrations[name] = factory(this.#dialect);
+    }
+    return migrations;
+  }
+}
+
+/**
+ * Runs all pending DWN server migrations against the given database.
+ *
+ * Uses Kysely's native {@link Migrator} with a separate migration table
+ * (`dwn_server_migration`) to avoid collisions with the DWN store
+ * migrations that use the default `kysely_migration` table.
+ *
+ * Call this once during server startup, before creating admin stores,
+ * registration stores, or the TTL cache.
+ *
+ * @param db - An open Kysely instance connected to the target database.
+ * @param dialect - The dialect for the target database. Passed to each
+ *   migration factory so it can use dialect-specific DDL helpers.
+ * @param migrations - Optional custom migration list; defaults to the
+ *   built-in {@link allServerMigrations}.
+ * @returns The names of newly applied migrations (empty if already up-to-date).
+ * @throws If any migration fails.
+ */
+export async function runServerMigrations(
+  db: Kysely<any>,
+  dialect: Dialect,
+  migrations?: ReadonlyArray<readonly [name: string, factory: ServerMigrationFactory]>,
+): Promise<string[]> {
+  const provider = new ServerMigrationProvider(dialect, migrations ?? allServerMigrations);
+  const migrator = new Migrator({
+    db,
+    provider,
+    migrationTableName     : 'dwn_server_migration',
+    migrationLockTableName : 'dwn_server_migration_lock',
+  });
+
+  const resultSet: MigrationResultSet = await migrator.migrateToLatest();
+
+  if (resultSet.error) {
+    throw resultSet.error;
+  }
+
+  return (resultSet.results ?? [])
+    .filter((r) => r.status === 'Success')
+    .map((r) => r.migrationName);
+}

package/src/storage.ts

@@ -20,6 +20,7 @@ import { Kysely } from 'kysely';
 
 import { createBunSqliteDatabase } from '@enbox/dwn-sql-store';
 import { PluginLoader } from './plugin-loader.js';
+import { runServerMigrations } from './server-migration-runner.js';
 
 import {
   DataStoreLevel,
@@ -55,26 +56,27 @@ export enum BackendTypes {
 export type DwnStore = DataStore | StateIndex | MessageStore | ResumableTaskStore;
 
 /**
- * Cache of shared PostgreSQL dialects keyed by connection URL. When multiple
- * DWN stores share the same Postgres URL, they reuse a single dialect (and
- * thus a single `pg.Pool`) instead of each creating their own. This reduces
- * connection count from 4 × pool_max to 1 × pool_max per DWN process.
+ * Returns a (potentially cached) dialect for the given connection URL. For
+ * Postgres, creates a pool with configurable sizing from the server config.
+ * For other backends, delegates to `getDialectFromUrl()` which handles its
+ * own caching (critical for in-memory SQLite).
+ *
+ * All Postgres dialects are cached in a separate map keyed by URL so that
+ * multiple DWN stores sharing the same Postgres URL reuse a single
+ * `pg.Pool`, reducing connection count from 4 × pool_max to 1 × pool_max.
  */
-const sharedDialectCache: Map<string, Dialect> = new Map();
+const postgresDialectCache: Map<string, Dialect> = new Map();
 
-/**
- * Returns a (potentially cached) dialect for the given Postgres connection URL.
- * Non-Postgres URLs always return a fresh dialect (no caching).
- */
 function getOrCreateDialect(connectionUrl: URL, config: DwnServerConfig): Dialect {
   const protocol = connectionUrl.protocol.slice(0, -1);
 
   if (protocol !== BackendTypes.POSTGRES) {
+    // getDialectFromUrl handles its own caching for SQLite/MySQL.
     return getDialectFromUrl(connectionUrl);
   }
 
   const key = connectionUrl.toString();
-  const cached = sharedDialectCache.get(key);
+  const cached = postgresDialectCache.get(key);
   if (cached !== undefined) {
     return cached;
   }
@@ -92,7 +94,7 @@ function getOrCreateDialect(connectionUrl: URL, config: DwnServerConfig): Dialec
     cursor : Cursor,
   });
 
-  sharedDialectCache.set(key, dialect);
+  postgresDialectCache.set(key, dialect);
   return dialect;
 }
 
@@ -152,13 +154,99 @@ async function runSqlMigrationsIfNeeded(config: DwnServerConfig): Promise<void>
       console.log(`DWN migrations applied: ${applied.join(', ')}`);
     }
   } finally {
-    // Don't destroy the Kysely instance if using a shared Postgres pool —
-    // the pool is cached in sharedDialectCache and will be reused by stores.
-    // Only destroy for non-cached dialects (SQLite, MySQL).
-    if (protocol !== BackendTypes.POSTGRES) {
-      await db.destroy();
+    // Do NOT destroy the Kysely instance — the dialect is cached and will be
+    // reused by stores. For in-memory SQLite, destroying would close the
+    // database and lose all migrated schema. For Postgres, the pool is shared.
+  }
+}
+
+/**
+ * Runs DWN server schema migrations (admin stores, registration, TTL cache)
+ * if the given URL points to a SQL backend. Uses the `registrationStoreUrl`
+ * (or the TTL cache URL) as the target database.
+ *
+ * Server migrations use a separate tracking table (`dwn_server_migration`)
+ * so they do not conflict with the DWN store migrations.
+ *
+ * Call this once during server startup, before creating admin stores.
+ *
+ * @returns The dialect used for the target database (so the caller can reuse
+ *          it for the TTL cache and admin stores), or `undefined` if no SQL
+ *          backend was configured or needed.
+ */
+export async function runServerMigrationsIfNeeded(config: DwnServerConfig): Promise<Dialect | undefined> {
+  const sqlBackends: string[] = [BackendTypes.SQLITE, BackendTypes.MYSQL, BackendTypes.POSTGRES];
+
+  // Determine the target URL for server migrations. Prefer registrationStoreUrl
+  // since admin stores and the TTL cache share that database. Fall back to
+  // ttlCacheUrl when no registration store is configured (the cacheEntries
+  // table still needs a schema).
+  const targetUrl = config.registrationStoreUrl ?? config.ttlCacheUrl;
+  if (!targetUrl) {
+    return undefined;
+  }
+
+  if (isFilePath(targetUrl)) {
+    return undefined;
+  }
+
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(targetUrl);
+  } catch {
+    return undefined;
+  }
+
+  const protocol = parsedUrl.protocol.slice(0, -1);
+  if (!sqlBackends.includes(protocol)) {
+    return undefined;
+  }
+
+  // When both registrationStoreUrl and ttlCacheUrl are set and differ,
+  // validate they point at the same database — the cacheEntries table is
+  // included in the server migration so it must live alongside the other
+  // server tables.
+  if (config.registrationStoreUrl && config.ttlCacheUrl
+    && config.ttlCacheUrl !== config.registrationStoreUrl) {
+    let ttlUrl: URL | undefined;
+    try {
+      ttlUrl = new URL(config.ttlCacheUrl);
+    } catch { /* not a URL */ }
+
+    if (ttlUrl) {
+      const ttlProtocol = ttlUrl.protocol.slice(0, -1);
+      if (sqlBackends.includes(ttlProtocol)) {
+        throw new Error(
+          'DWN server misconfiguration: DWN_TTL_CACHE_URL must point to the same database as ' +
+          'DWN_REGISTRATION_STORE_URL (or DWN_STORAGE) because the cacheEntries table is managed ' +
+          'by the server migration system. ' +
+          `Got registrationStoreUrl="${config.registrationStoreUrl}", ttlCacheUrl="${config.ttlCacheUrl}".`
+        );
+      }
+    }
+  }
+
+  const dialect = getOrCreateDialect(parsedUrl, config);
+  const db = new Kysely<Record<string, unknown>>({ dialect });
+  try {
+    const applied = await runServerMigrations(db, dialect);
+    if (applied.length > 0) {
+      console.log(`Server migrations applied: ${applied.join(', ')}`);
+    }
+  } finally {
+    // For Postgres, don't destroy — the pool is cached in sharedDialectCache.
+    // For SQLite/MySQL, we also keep the Kysely instance alive so the caller
+    // can reuse the same dialect (critical for in-memory SQLite).
+    if (protocol === BackendTypes.POSTGRES) {
+      // Pool stays alive via sharedDialectCache.
     }
+    // NOTE: We intentionally do NOT destroy the Kysely instance for any
+    // backend. The dialect is returned to the caller for reuse (e.g. by the
+    // TTL cache and admin stores). For in-memory SQLite, destroying would
+    // lose the database.
   }
+
+  return dialect;
 }
 
 function getLevelStore(
@@ -264,6 +352,21 @@ async function loadStoreFromFilePath(
   }
 }
 
+/**
+ * Cache for the in-memory SQLite dialect. Since every call to
+ * `createBunSqliteDatabase(':memory:')` creates a separate, empty database,
+ * we must ensure that `getDialectFromUrl(new URL('sqlite://'))` always
+ * returns the same dialect (and thus the same underlying database) within a
+ * process. This is critical for the DWN server startup flow where migrations,
+ * the registration store, and the TTL cache all need to share the same
+ * in-memory database.
+ *
+ * File-based SQLite and other backends are NOT cached here — file-based SQLite
+ * connections naturally share state through the filesystem, and caching would
+ * break test isolation when multiple test files run in the same process.
+ */
+let inMemorySqliteDialect: Dialect | undefined;
+
 export function getDialectFromUrl(connectionUrl: URL): Dialect {
   switch (connectionUrl.protocol.slice(0, -1)) {
     case BackendTypes.SQLITE: {
@@ -275,9 +378,32 @@ export function getDialectFromUrl(connectionUrl: URL): Dialect {
         fs.mkdirSync(connectionUrl.host, { recursive: true });
       }
 
-      // Use in-memory database if no path is provided (for tests)
+      // Use in-memory database if no path is provided (for tests).
       const dbPath = path || ':memory:';
 
+      // For in-memory SQLite, return a cached dialect so that all callers
+      // (migrations, registration store, TTL cache) share the same database.
+      // The wrapper makes close() a no-op so that individual consumers (e.g.
+      // DwnServer.stop() → Dwn.close() → store.close()) cannot destroy the
+      // shared database out from under other consumers.
+      if (dbPath === ':memory:') {
+        if (inMemorySqliteDialect === undefined) {
+          const sharedDb = createBunSqliteDatabase(':memory:');
+          const nonCloseableDb = {
+            close(): void {
+              // no-op — shared instance must survive the process
+            },
+            prepare(sql: string): ReturnType<typeof sharedDb.prepare> {
+              return sharedDb.prepare(sql);
+            },
+          };
+          inMemorySqliteDialect = new SqliteDialect({
+            database: async (): Promise<typeof nonCloseableDb> => nonCloseableDb,
+          });
+        }
+        return inMemorySqliteDialect;
+      }
+
       return new SqliteDialect({
         database: async () => createBunSqliteDatabase(dbPath),
       });
@@ -291,6 +417,8 @@ export function getDialectFromUrl(connectionUrl: URL): Dialect {
         pool   : async () => new pg.Pool({ connectionString: connectionUrl.toString() }),
         cursor : Cursor,
       });
+    default:
+      throw new Error(`Unsupported database protocol: ${connectionUrl.protocol}`);
   }
 }
 

package/src/web5-connect/sql-ttl-cache.ts

@@ -1,5 +1,5 @@
 import type { Dialect } from '@enbox/dwn-sql-store';
-import { Kysely } from 'kysely';
+import { Kysely, sql } from 'kysely';
 
 /**
  * The SqlTtlCache is responsible for storing and retrieving cache data with TTL (Time-to-Live).
@@ -8,13 +8,11 @@ export class SqlTtlCache {
   private static readonly cacheTableName = 'cacheEntries';
   private static readonly cleanupIntervalInSeconds = 60;
 
-  private sqlDialect: Dialect;
   private db: Kysely<CacheDatabase>;
   private cleanupTimer: NodeJS.Timeout;
 
   private constructor(sqlDialect: Dialect) {
     this.db = new Kysely<CacheDatabase>({ dialect: sqlDialect });
-    this.sqlDialect = sqlDialect;
   }
 
   /**
@@ -28,26 +26,17 @@ export class SqlTtlCache {
     return cacheManager;
   }
 
+  /**
+   * Verifies that the required table exists and starts the cleanup timer.
+   * Throws a clear error directing the caller to run server migrations first.
+   */
   private async initialize(): Promise<void> {
-
-    // create table if it doesn't exist
-    const tableExists = await this.sqlDialect.hasTable(this.db, SqlTtlCache.cacheTableName);
-    if (!tableExists) {
-      await this.db.schema
-        .createTable(SqlTtlCache.cacheTableName)
-        .ifNotExists() // kept to show supported by all dialects in contrast to ifNotExists() below, though not needed due to tableExists check above
-        // 512 chars to accommodate potentially large `state` in Web5 Connect flow
-        .addColumn('key', 'varchar(512)', (column) => column.primaryKey())
-        .addColumn('value', 'text', (column) => column.notNull())
-        .addColumn('expiry', 'bigint', (column) => column.notNull())
-        .execute();
-
-      await this.db.schema
-        .createIndex('index_expiry')
-        // .ifNotExists() // intentionally kept commented out code to show that it is not supported by all dialects (ie. MySQL)
-        .on(SqlTtlCache.cacheTableName)
-        .column('expiry')
-        .execute();
+    try {
+      await sql`SELECT 1 FROM ${sql.table(SqlTtlCache.cacheTableName)} LIMIT 0`.execute(this.db);
+    } catch {
+      throw new Error(
+        `SqlTtlCache: table '${SqlTtlCache.cacheTableName}' does not exist. Run server migrations before starting.`
+      );
     }
 
     // Start the cleanup timer
@@ -131,6 +120,16 @@ export class SqlTtlCache {
       .where('expiry', '<', Date.now())
       .execute();
   }
+
+  /**
+   * Stops the background cleanup timer. The underlying database connection is
+   * NOT destroyed here because the dialect is shared with other components
+   * (e.g. DWN stores, registration store) and its lifecycle is managed by the
+   * dialect owner.
+   */
+  public close(): void {
+    clearInterval(this.cleanupTimer);
+  }
 }
 
 interface CacheEntry {