@enbox/dwn-server 0.0.6 → 0.0.8

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';
 
 /**
@@ -52,6 +54,24 @@ export type DwnServerOptions = {
    * are appended after the DeliveryService hook.
    */
   messageProcessedHooks?: MessageProcessedHook[];
+
+  /**
+   * An externally created RegistrationManager to use as the tenant gate and
+   * registration endpoint handler. When a pre-built `dwn` is provided, the
+   * server cannot create its own RegistrationManager (because it doesn't
+   * control the DWN's TenantGate). Pass one here to enable registration
+   * endpoints (`POST /registration`, etc.) with a pre-built DWN.
+   */
+  registrationManager?: RegistrationManager;
+
+  /**
+   * An externally created OpenAuthHandler for the built-in provider-auth
+   * endpoints (`/provider-auth/authorize`, `/provider-auth/token`,
+   * `/provider-auth/refresh`). When a pre-built `dwn` is provided, the
+   * server skips creating this handler. Pass one here to enable the
+   * open-auth flow with a pre-built DWN.
+   */
+  openAuthHandler?: OpenAuthHandler;
 };
 
 /**
@@ -79,10 +99,16 @@ 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;
 
   /**
-   * @param options.dwn - Dwn instance to use as an override. Registration endpoint will not be enabled if this is provided.
+   * @param options.dwn - Dwn instance to use as an override.
+   * @param options.registrationManager - External RegistrationManager to use with a pre-built DWN.
+   * @param options.openAuthHandler - External OpenAuthHandler to use with a pre-built DWN.
    */
   constructor(options: DwnServerOptions = {}) {
     this.config = options.config ?? defaultConfig;
@@ -90,6 +116,8 @@ export class DwnServer {
     this.didResolver = options.didResolver;
     this.dwn = options.dwn;
     this.#externalHooks = options.messageProcessedHooks ?? [];
+    this.#externalRegistrationManager = options.registrationManager;
+    this.#externalOpenAuthHandler = options.openAuthHandler;
 
     log.setLevel(this.config.logLevel as log.LogLevelDesc);
 
@@ -116,49 +144,18 @@ export class DwnServer {
    */
   async #setupServer(): Promise<void> {
 
-    let registrationManager: RegistrationManager;
-    if (!this.dwn) {
-      // Load provider auth plugin if configured.
-      let providerAuthPlugin: ProviderAuthPlugin | undefined;
-      if (this.config.providerAuthEnabled) {
-        if (this.config.providerAuthPluginPath) {
-          // Custom external plugin.
-          providerAuthPlugin = await loadProviderAuthPlugin(this.config.providerAuthPluginPath);
-          log.info('Provider auth plugin loaded from path');
-        } else if (this.config.providerAuthJwtSecret || this.config.providerAuthJwtJwksUrl) {
-          // Built-in JWT plugin.
-          providerAuthPlugin = await JwtProviderAuthPlugin.create({
-            secret   : this.config.providerAuthJwtSecret,
-            jwksUrl  : this.config.providerAuthJwtJwksUrl,
-            issuer   : this.config.baseUrl,
-            audience : this.config.baseUrl,
-          });
-          log.info('Built-in JWT provider auth plugin created');
-        }
-      }
+    // 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);
 
-      // undefined registrationStoreUrl is used as a signal that there is no need for tenant registration, DWN is open for all.
-      registrationManager = await RegistrationManager.create({
-        registrationStoreUrl                 : this.config.registrationStoreUrl,
-        termsOfServiceFilePath               : this.config.termsOfServiceFilePath,
-        proofOfWorkChallengeNonceSeed        : this.config.registrationProofOfWorkSeed,
-        proofOfWorkInitialMaximumAllowedHash : this.config.registrationProofOfWorkInitialMaxHash,
-        providerAuthPlugin,
-      });
+    let registrationManager: RegistrationManager | undefined;
 
-      // Warn if the tenant gate is active but no registration method is enabled.
-      // This is almost certainly a misconfiguration — new tenants will be rejected
-      // with 401 and have no way to register.
-      if (this.config.registrationStoreUrl
-        && !this.config.registrationProofOfWorkEnabled
-        && !providerAuthPlugin) {
-        log.warn(
-          '*** WARNING: DWN_REGISTRATION_STORE_URL is set (tenant gate active) but neither ' +
-          'proof-of-work (DWN_REGISTRATION_PROOF_OF_WORK_ENABLED) nor provider auth ' +
-          '(DWN_PROVIDER_AUTH_ENABLED + secret/plugin) is configured. ' +
-          'New tenants will be unable to register. ***',
-        );
-      }
+    if (!this.dwn) {
+      // No pre-built DWN — create everything from scratch including registration.
+      registrationManager = await this.#createRegistrationManager();
 
       let eventLog: EventLog | undefined;
       if (this.config.webSocketSupport) {
@@ -186,6 +183,11 @@ export class DwnServer {
         eventLog,
       });
       this.dwn = await Dwn.create(dwnConfig);
+    } else if (this.#externalRegistrationManager) {
+      // Pre-built DWN with an externally-provided RegistrationManager.
+      // The caller is responsible for passing this RegistrationManager as the
+      // TenantGate when creating the DWN instance.
+      registrationManager = this.#externalRegistrationManager;
     }
 
     // Assemble message-processed hooks.
@@ -232,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({
@@ -273,6 +286,8 @@ export class DwnServer {
         ipRateLimiter,
         tenantRateLimiter,
         webhookManager,
+        passkeyStore,
+        sessionManager,
       });
 
       // Record server start event in audit log.
@@ -288,17 +303,22 @@ 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).
-    let openAuthHandler: OpenAuthHandler | undefined;
-    if (this.config.providerAuthEnabled && this.config.providerAuthJwtSecret && !this.config.providerAuthPluginPath) {
+    // An externally-provided handler (e.g. from the relay) takes precedence.
+    let openAuthHandler: OpenAuthHandler | undefined = this.#externalOpenAuthHandler;
+    if (!openAuthHandler && this.config.providerAuthEnabled && this.config.providerAuthJwtSecret && !this.config.providerAuthPluginPath) {
       openAuthHandler = OpenAuthHandler.create(
         this.config.providerAuthJwtSecret,
         this.config.baseUrl,
       );
       log.info('Built-in open-auth endpoints enabled');
+    }
 
+    if (openAuthHandler) {
       // Auto-configure authorize/token/refresh URLs if not explicitly set.
       if (!this.config.providerAuthAuthorizeUrl) {
         this.config.providerAuthAuthorizeUrl = `${this.config.baseUrl}/provider-auth/authorize`;
@@ -313,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);
@@ -339,6 +363,56 @@ export class DwnServer {
     }
   }
 
+  /**
+   * Creates a RegistrationManager based on the server config. Factored out of
+   * `#setupServer()` so the same logic can be reused regardless of whether the
+   * DWN is created internally or externally.
+   */
+  async #createRegistrationManager(): Promise<RegistrationManager> {
+    // Load provider auth plugin if configured.
+    let providerAuthPlugin: ProviderAuthPlugin | undefined;
+    if (this.config.providerAuthEnabled) {
+      if (this.config.providerAuthPluginPath) {
+        // Custom external plugin.
+        providerAuthPlugin = await loadProviderAuthPlugin(this.config.providerAuthPluginPath);
+        log.info('Provider auth plugin loaded from path');
+      } else if (this.config.providerAuthJwtSecret || this.config.providerAuthJwtJwksUrl) {
+        // Built-in JWT plugin.
+        providerAuthPlugin = await JwtProviderAuthPlugin.create({
+          secret   : this.config.providerAuthJwtSecret,
+          jwksUrl  : this.config.providerAuthJwtJwksUrl,
+          issuer   : this.config.baseUrl,
+          audience : this.config.baseUrl,
+        });
+        log.info('Built-in JWT provider auth plugin created');
+      }
+    }
+
+    // undefined registrationStoreUrl is used as a signal that there is no need
+    // for tenant registration, DWN is open for all.
+    const registrationManager = await RegistrationManager.create({
+      registrationStoreUrl                 : this.config.registrationStoreUrl,
+      termsOfServiceFilePath               : this.config.termsOfServiceFilePath,
+      proofOfWorkChallengeNonceSeed        : this.config.registrationProofOfWorkSeed,
+      proofOfWorkInitialMaximumAllowedHash : this.config.registrationProofOfWorkInitialMaxHash,
+      providerAuthPlugin,
+    });
+
+    // Warn if the tenant gate is active but no registration method is enabled.
+    if (this.config.registrationStoreUrl
+      && !this.config.registrationProofOfWorkEnabled
+      && !providerAuthPlugin) {
+      log.warn(
+        '*** WARNING: DWN_REGISTRATION_STORE_URL is set (tenant gate active) but neither ' +
+        'proof-of-work (DWN_REGISTRATION_PROOF_OF_WORK_ENABLED) nor provider auth ' +
+        '(DWN_PROVIDER_AUTH_ENABLED + secret/plugin) is configured. ' +
+        'New tenants will be unable to register. ***',
+      );
+    }
+
+    return registrationManager;
+  }
+
   /**
    * Stops the DWN server.
    */
@@ -356,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,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/index.ts

@@ -13,5 +13,7 @@ export { DwnServer, DwnServerOptions } from './dwn-server.js';
 export { HttpApi } from './http-api.js';
 export { jsonRpcRouter } from './json-rpc-api.js';
 export type { MessageProcessedContext, MessageProcessedHook } from './message-processed-hook.js';
+export { OpenAuthHandler } from './registration/open-auth-handler.js';
+export { RegistrationManager } from './registration/registration-manager.js';
 export { getDwnConfig, StoreType, BackendTypes, DwnStore } from './storage.js';
 export { WsApi } from './ws-api.js';

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