@enbox/dwn-server 0.0.7 → 0.0.9

package/src/{web5-connect → 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 {

package/src/dwn-server.ts

@@ -16,6 +16,8 @@ import type { ProviderAuthPlugin } from './registration/provider-auth-plugin.js'
 
 import { ActivityLog } from './admin/activity-log.js';
 import { AdminApi } from './admin/admin-api.js';
+import { AdminPasskeyStore } from './admin/admin-passkey-store.js';
+import { AdminSessionManager } from './admin/admin-session.js';
 import { AdminStore } from './admin/admin-store.js';
 import { AuditLog } from './admin/audit-log.js';
 import { config as defaultConfig } from './config.js';
@@ -29,7 +31,7 @@ import { RateLimiter } from './rate-limiter.js';
 import { RegistrationManager } from './registration/registration-manager.js';
 import { WebhookManager } from './admin/webhook-manager.js';
 import { WsApi } from './ws-api.js';
-import { getDialectFromUrl, getDwnConfig } from './storage.js';
+import { getDialectFromUrl, getDwnConfig, runServerMigrationsIfNeeded } from './storage.js';
 import { removeProcessHandlers, setProcessHandlers } from './process-handlers.js';
 
 /**
@@ -97,6 +99,8 @@ export class DwnServer {
   #ipRateLimiter: RateLimiter | undefined;
   #tenantRateLimiter: RateLimiter | undefined;
   #auditLog: AuditLog | undefined;
+  #passkeyStore: AdminPasskeyStore | undefined;
+  #sessionManager: AdminSessionManager | undefined;
   #externalHooks: MessageProcessedHook[];
   #externalRegistrationManager: RegistrationManager | undefined;
   #externalOpenAuthHandler: OpenAuthHandler | undefined;
@@ -140,6 +144,13 @@ export class DwnServer {
    */
   async #setupServer(): Promise<void> {
 
+    // Run server migrations (admin stores, registration, TTL cache) FIRST,
+    // before creating any stores that depend on the server schema. The
+    // returned dialect is reused for the TTL cache and admin stores so that
+    // in-memory SQLite shares a single database instance across migrations
+    // and stores.
+    const serverDialect = await runServerMigrationsIfNeeded(this.config);
+
     let registrationManager: RegistrationManager | undefined;
 
     if (!this.dwn) {
@@ -223,34 +234,45 @@ export class DwnServer {
     let adminStore: AdminStore | undefined;
     let auditLog: AuditLog | undefined;
     let webhookManager: WebhookManager | undefined;
+    let passkeyStore: AdminPasskeyStore | undefined;
+    let sessionManager: AdminSessionManager | undefined;
 
     if (this.config.adminToken) {
       const storageUrl = this.config.messageStore;
       adminStore = AdminStore.create(storageUrl);
       activityLog = new ActivityLog(this.config.adminActivityLogCapacity);
 
-      // Create the persistent audit log using the registration store's dialect
-      // (same DB) or the message store URL as fallback.
+      // Reuse the dialect returned by server migrations when available — this
+      // is critical for in-memory SQLite where every `getDialectFromUrl` call
+      // creates a separate database. For Postgres, `serverDialect` points at
+      // the same shared pool, so reusing it also avoids pool proliferation.
       if (this.config.registrationStoreUrl) {
+        const adminDialect = serverDialect ?? getDialectFromUrl(new URL(this.config.registrationStoreUrl));
+
         try {
-          const auditDialect = getDialectFromUrl(new URL(this.config.registrationStoreUrl));
-          auditLog = await AuditLog.create(auditDialect, {
+          auditLog = await AuditLog.create(adminDialect, {
             maxAgeDays : this.config.auditLogMaxAgeDays,
             maxRows    : this.config.auditLogMaxRows,
           });
         } catch (err) {
           log.warn('Failed to create audit log:', err);
         }
-      }
 
-      // Create webhook manager using the same dialect as the audit log.
-      if (this.config.registrationStoreUrl) {
         try {
-          const webhookDialect = getDialectFromUrl(new URL(this.config.registrationStoreUrl));
-          webhookManager = await WebhookManager.create(webhookDialect);
+          webhookManager = await WebhookManager.create(adminDialect);
         } catch (err) {
           log.warn('Failed to create webhook manager:', err);
         }
+
+        // Create passkey store and session manager for WebAuthn admin auth.
+        // @see https://github.com/enboxorg/enbox/issues/546
+        try {
+          passkeyStore = await AdminPasskeyStore.create(adminDialect);
+          sessionManager = new AdminSessionManager(this.config.adminSessionTtlSeconds);
+          log.info('Admin passkey authentication enabled');
+        } catch (err) {
+          log.warn('Failed to create passkey store:', err);
+        }
       }
 
       adminApi = AdminApi.create({
@@ -264,6 +286,8 @@ export class DwnServer {
         ipRateLimiter,
         tenantRateLimiter,
         webhookManager,
+        passkeyStore,
+        sessionManager,
       });
 
       // Record server start event in audit log.
@@ -279,6 +303,8 @@ export class DwnServer {
     this.#ipRateLimiter = ipRateLimiter;
     this.#tenantRateLimiter = tenantRateLimiter;
     this.#auditLog = auditLog;
+    this.#passkeyStore = passkeyStore;
+    this.#sessionManager = sessionManager;
 
     // Create open-auth handler if provider auth is enabled with a JWT secret
     // and authorize/token URLs point to this server (or are not set — defaulting to built-in).
@@ -307,7 +333,11 @@ export class DwnServer {
 
     this.#httpApi = await HttpApi.create(
       this.config, this.dwn, registrationManager, adminApi, activityLog,
-      { adminStore, registrationStore, ipRateLimiter, tenantRateLimiter, messageProcessedHooks, openAuthHandler },
+      {
+        adminStore, registrationStore, ipRateLimiter, tenantRateLimiter,
+        messageProcessedHooks, openAuthHandler, sessionManager,
+        ttlCacheDialect: serverDialect,
+      },
     );
 
     await this.#httpApi.start(this.config.port);
@@ -400,6 +430,14 @@ export class DwnServer {
       await this.#auditLog.close();
     }
 
+    // Clean up passkey store and session manager.
+    if (this.#passkeyStore) {
+      await this.#passkeyStore.close();
+    }
+    if (this.#sessionManager) {
+      this.#sessionManager.destroy();
+    }
+
     // Clean up rate limiters (stops their interval timers).
     if (this.#ipRateLimiter) {
       this.#ipRateLimiter.destroy();

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,9 +30,10 @@ import { existsSync, readFileSync } from 'fs';
 import { join, resolve } from 'path';
 
 import { config } from './config.js';
+import { ConnectServer } from './connect/connect-server.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';
 import { requestCounter, responseHistogram } from './metrics.js';
 
 /** Property names that must never be used as keys when building objects from user input. */
@@ -62,8 +66,9 @@ export class HttpApi {
   #tenantRateLimiter: RateLimiter | undefined;
   #messageProcessedHooks: MessageProcessedHook[];
   #openAuthHandler: OpenAuthHandler | undefined;
+  #sessionManager: AdminSessionManager | undefined;
   #adminUiPath: string | undefined;
-  web5ConnectServer: Web5ConnectServer;
+  connectServer: ConnectServer;
   registrationManager: RegistrationManager;
   dwn: Dwn;
 
@@ -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;
     }
 
-    httpApi.web5ConnectServer = await Web5ConnectServer.create({
-      baseUrl        : config.baseUrl,
-      sqlTtlCacheUrl : config.ttlCacheUrl,
+    // 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.connectServer = await ConnectServer.create({
+      baseUrl    : config.baseUrl,
+      sqlDialect : ttlDialect,
     });
 
     return httpApi;
@@ -211,6 +223,10 @@ export class HttpApi {
           response.headers.set('access-control-allow-methods', 'GET, POST, OPTIONS');
           response.headers.set('access-control-allow-headers', '*');
           response.headers.set('access-control-expose-headers', 'dwn-response');
+          // Cache preflight responses for 24 hours to reduce OPTIONS round-trips,
+          // which is especially important for local DWN discovery that probes
+          // multiple ports from the browser (e.g. `probeLocalDwn()` in @enbox/auth).
+          response.headers.set('access-control-max-age', '86400');
         }
 
         // --- Response-time metrics ---
@@ -258,6 +274,9 @@ export class HttpApi {
     if (this.#openAuthHandler) {
       this.#openAuthHandler.destroy();
     }
+    if (this.connectServer) {
+      this.connectServer.close();
+    }
     if (this.#server) {
       this.#server.stop(true); // close all connections immediately
     }
@@ -321,9 +340,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 {
@@ -338,7 +357,7 @@ export class HttpApi {
 
     if (method === 'GET' && path === '/') {
       return new Response(
-        'please use am enbox client, for example: https://github.com/enboxorg/enbox ',
+        'please use an enbox client, for example: https://github.com/enboxorg/enbox ',
         { headers: { 'content-type': 'text/plain' } },
       );
     }
@@ -384,8 +403,8 @@ export class HttpApi {
       return registrationResponse;
     }
 
-    // --- Web5 Connect routes ---
-    const connectResponse = await this.#matchWeb5ConnectRoutes(req, path, method);
+    // --- Connect routes ---
+    const connectResponse = await this.#matchConnectRoutes(req, path, method);
     if (connectResponse) {
       return connectResponse;
     }
@@ -791,10 +810,10 @@ export class HttpApi {
   }
 
   // ---------------------------------------------------------------------------
-  // Web5 Connect routes
+  // Connect routes
   // ---------------------------------------------------------------------------
 
-  async #matchWeb5ConnectRoutes(
+  async #matchConnectRoutes(
     req: Request, path: string, method: string
   ): Promise<Response | null> {
     // POST /connect/par
@@ -816,7 +835,7 @@ export class HttpApi {
         }, { status: 400 });
       }
 
-      const result = await this.web5ConnectServer.setWeb5ConnectRequest(body.request);
+      const result = await this.connectServer.setConnectRequest(body.request);
       return Response.json(result, { status: 201 });
     }
 
@@ -825,9 +844,9 @@ export class HttpApi {
       const match = path.match(/^\/connect\/authorize\/([^/]+)\.jwt$/);
       if (match && method === 'GET') {
         const requestId = match[1];
-        log.info(`Retrieving Web5 Connect Request object of ID: ${requestId}...`);
+        log.info(`Retrieving Connect Request object of ID: ${requestId}...`);
 
-        const requestObjectJwt = await this.web5ConnectServer.getWeb5ConnectRequest(requestId);
+        const requestObjectJwt = await this.connectServer.getConnectRequest(requestId);
         if (!requestObjectJwt) {
           return Response.json({
             ok     : false,
@@ -852,7 +871,7 @@ export class HttpApi {
       const state = body.state;
 
       if (idToken !== undefined && state != undefined) {
-        await this.web5ConnectServer.setWeb5ConnectResponse(state, idToken);
+        await this.connectServer.setConnectResponse(state, idToken);
         return Response.json({
           ok     : true,
           status : { code: 201, message: 'Created' },
@@ -872,7 +891,7 @@ export class HttpApi {
         const state = match[1];
         log.info(`Retrieving ID token for state: ${state}...`);
 
-        const idToken = await this.web5ConnectServer.getWeb5ConnectResponse(state);
+        const idToken = await this.connectServer.getConnectResponse(state);
         if (!idToken) {
           return Response.json({
             ok     : false,

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);
+}