@enbox/dwn-server 0.0.3 → 0.0.4

package/src/registration/registration-store.ts

@@ -1,13 +1,16 @@
 import type { Dialect } from '@enbox/dwn-sql-store';
-import type { RegistrationData } from './registration-types.js';
+import type { TenantQuota } from '../admin/types.js';
 
-import { Kysely } from 'kysely';
+import { Kysely, sql } from 'kysely';
+
+import { escapeLikeWildcards } from '../lib/sql-utils.js';
 
 /**
  * The RegistrationStore is responsible for storing and retrieving tenant registration information.
  */
 export class RegistrationStore {
   private static readonly registeredTenantTableName = 'registeredTenants';
+  private static readonly tenantQuotasTableName = 'tenantQuotas';
 
   private db: Kysely<RegistrationDatabase>;
 
@@ -19,11 +22,11 @@ export class RegistrationStore {
    * Creates a new RegistrationStore instance.
    */
   public static async create(sqlDialect: Dialect): Promise<RegistrationStore> {
-    const proofOfWorkManager = new RegistrationStore(sqlDialect);
+    const store = new RegistrationStore(sqlDialect);
 
-    await proofOfWorkManager.initialize();
+    await store.initialize();
 
-    return proofOfWorkManager;
+    return store;
   }
 
   private async initialize(): Promise<void> {
@@ -32,33 +35,101 @@ export class RegistrationStore {
       .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']) {
+      try {
+        await this.db.schema
+          .alterTable(RegistrationStore.registeredTenantTableName)
+          .addColumn(col, 'text')
+          .execute();
+      } catch {
+        // Column already exists — expected.
+      }
+    }
+
+    // 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();
   }
 
   /**
    * Inserts or updates the tenant registration information.
    */
-  public async insertOrUpdateTenantRegistration(registrationData: RegistrationData): Promise<void> {
+  public async insertOrUpdateTenantRegistration(registrationData: {
+    did: string;
+    termsOfServiceHash?: string;
+    accountId?: string;
+    registrationType?: string;
+    metadata?: string;
+  }): Promise<void> {
+    const insertValues: Record<string, unknown> = {
+      did                : registrationData.did,
+      termsOfServiceHash : registrationData.termsOfServiceHash ?? '',
+      suspended          : 0,
+      registeredAt       : new Date().toISOString(),
+    };
+
+    if (registrationData.accountId !== undefined) {
+      insertValues.accountId = registrationData.accountId;
+    }
+    if (registrationData.registrationType !== undefined) {
+      insertValues.registrationType = registrationData.registrationType;
+    }
+    if (registrationData.metadata !== undefined) {
+      insertValues.metadata = registrationData.metadata;
+    }
+
     await this.db
       .insertInto(RegistrationStore.registeredTenantTableName)
-      .values(registrationData)
+      .values(insertValues as any)
       .onConflict((oc) =>
-        oc.column('did').doUpdateSet((eb) => ({
-          termsOfServiceHash: eb.ref('excluded.termsOfServiceHash'),
-        })),
+        oc.column('did').doUpdateSet((eb) => {
+          const updateSet: Record<string, any> = {
+            termsOfServiceHash: eb.ref('excluded.termsOfServiceHash'),
+          };
+          // Do NOT overwrite registeredAt on update.
+          if (registrationData.accountId !== undefined) {
+            updateSet.accountId = registrationData.accountId;
+          }
+          if (registrationData.registrationType !== undefined) {
+            updateSet.registrationType = registrationData.registrationType;
+          }
+          if (registrationData.metadata !== undefined) {
+            updateSet.metadata = registrationData.metadata;
+          }
+          return updateSet;
+        }),
       )
-      // Executes the query. No error is thrown if the query doesn’t affect any rows (ie. if the insert or update didn’t change anything).
       .executeTakeFirst();
   }
 
   /**
    * Retrieves the tenant registration information.
    */
-  public async getTenantRegistration(tenantDid: string): Promise<RegistrationData | undefined> {
+  public async getTenantRegistration(tenantDid: string): Promise<RegisteredTenantRow | undefined> {
     const result = await this.db
       .selectFrom(RegistrationStore.registeredTenantTableName)
-      .select('did')
-      .select('termsOfServiceHash')
+      .select(['did', 'termsOfServiceHash', 'suspended', 'accountId', 'registrationType', 'registeredAt', 'metadata'])
       .where('did', '=', tenantDid)
       .execute();
 
@@ -68,13 +139,251 @@ export class RegistrationStore {
 
     return result[0];
   }
+
+  // ---------------------------------------------------------------------------
+  // Admin operations
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns a paginated list of registered tenants with optional search and status filtering.
+   *
+   * @see https://github.com/enboxorg/enbox/issues/390
+   */
+  public async listTenants(options?: {
+    cursor? : string;
+    limit? : number;
+    search? : string;
+    status? : 'active' | 'suspended';
+  }): Promise<{ tenants: RegisteredTenantRow[]; cursor?: string }> {
+    const limit = options?.limit ?? 20;
+
+    let query = this.db
+      .selectFrom(RegistrationStore.registeredTenantTableName)
+      .select(['did', 'termsOfServiceHash', 'suspended', 'accountId', 'registrationType', 'registeredAt', 'metadata'])
+      .orderBy('did', 'asc')
+      .limit(limit + 1); // fetch one extra to detect next page
+
+    if (options?.cursor) {
+      query = query.where('did', '>', options.cursor);
+    }
+
+    if (options?.search) {
+      query = query.where('did', 'like', `%${escapeLikeWildcards(options.search)}%`);
+    }
+
+    if (options?.status === 'suspended') {
+      query = query.where('suspended', '=', 1);
+    } else if (options?.status === 'active') {
+      query = query.where('suspended', '=', 0);
+    }
+
+    const results = await query.execute();
+
+    let cursor: string | undefined;
+    if (results.length > limit) {
+      results.pop();
+      cursor = results[results.length - 1].did;
+    }
+
+    return { tenants: results, cursor };
+  }
+
+  /**
+   * Returns the total count of registered tenants matching optional filters.
+   */
+  public async getTenantCount(options?: {
+    search? : string;
+    status? : 'active' | 'suspended';
+  }): Promise<number> {
+    let query = this.db
+      .selectFrom(RegistrationStore.registeredTenantTableName)
+      .select(sql<number>`count(*)`.as('count'));
+
+    if (options?.search) {
+      query = query.where('did', 'like', `%${escapeLikeWildcards(options.search)}%`);
+    }
+
+    if (options?.status === 'suspended') {
+      query = query.where('suspended', '=', 1);
+    } else if (options?.status === 'active') {
+      query = query.where('suspended', '=', 0);
+    }
+
+    const result = await query.executeTakeFirstOrThrow();
+    return Number(result.count);
+  }
+
+  /**
+   * Inserts a new tenant registration. Returns `false` if the tenant already exists.
+   *
+   * @see https://github.com/enboxorg/enbox/issues/393
+   */
+  public async createTenant(did: string): Promise<boolean> {
+    try {
+      await this.db
+        .insertInto(RegistrationStore.registeredTenantTableName)
+        .values({ did, termsOfServiceHash: '', suspended: 0 })
+        .execute();
+      return true;
+    } catch {
+      // Unique constraint violation — tenant already exists.
+      return false;
+    }
+  }
+
+  /**
+   * Suspends a tenant. Returns `true` if the tenant was found and suspended.
+   */
+  public async suspendTenant(did: string): Promise<boolean> {
+    const result = await this.db
+      .updateTable(RegistrationStore.registeredTenantTableName)
+      .set({ suspended: 1 })
+      .where('did', '=', did)
+      .executeTakeFirst();
+
+    return Number(result.numUpdatedRows) > 0;
+  }
+
+  /**
+   * Unsuspends a tenant. Returns `true` if the tenant was found and unsuspended.
+   */
+  public async unsuspendTenant(did: string): Promise<boolean> {
+    const result = await this.db
+      .updateTable(RegistrationStore.registeredTenantTableName)
+      .set({ suspended: 0 })
+      .where('did', '=', did)
+      .executeTakeFirst();
+
+    return Number(result.numUpdatedRows) > 0;
+  }
+
+  /**
+   * Deletes a tenant registration. Returns `true` if the tenant was found and deleted.
+   */
+  public async deleteTenant(did: string): Promise<boolean> {
+    const result = await this.db
+      .deleteFrom(RegistrationStore.registeredTenantTableName)
+      .where('did', '=', did)
+      .executeTakeFirst();
+
+    return Number(result.numDeletedRows) > 0;
+  }
+
+  /**
+   * Returns all tenant registrations associated with the given account ID.
+   *
+   * @see https://github.com/enboxorg/enbox/issues/404
+   */
+  public async getTenantsForAccount(accountId: string): Promise<RegisteredTenantRow[]> {
+    return this.db
+      .selectFrom(RegistrationStore.registeredTenantTableName)
+      .select(['did', 'termsOfServiceHash', 'suspended', 'accountId', 'registrationType', 'registeredAt', 'metadata'])
+      .where('accountId', '=', accountId)
+      .orderBy('did', 'asc')
+      .execute();
+  }
+
+  /**
+   * Returns the count of suspended tenants.
+   */
+  public async getSuspendedCount(): Promise<number> {
+    const result = await this.db
+      .selectFrom(RegistrationStore.registeredTenantTableName)
+      .select(sql<number>`count(*)`.as('count'))
+      .where('suspended', '=', 1)
+      .executeTakeFirstOrThrow();
+
+    return Number(result.count);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tenant quota operations
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns the quota for a tenant, or `undefined` if no per-tenant quota is set.
+   */
+  public async getQuota(did: string): Promise<TenantQuota | undefined> {
+    const result = await this.db
+      .selectFrom(RegistrationStore.tenantQuotasTableName)
+      .select(['did', 'maxMessages', 'maxStorageBytes'])
+      .where('did', '=', did)
+      .executeTakeFirst();
+
+    if (result === undefined) {
+      return undefined;
+    }
+
+    return {
+      did             : result.did,
+      maxMessages     : Number(result.maxMessages),
+      maxStorageBytes : Number(result.maxStorageBytes),
+    };
+  }
+
+  /**
+   * Sets (inserts or updates) the quota for a tenant.
+   */
+  public async setQuota(quota: TenantQuota): Promise<void> {
+    await this.db
+      .insertInto(RegistrationStore.tenantQuotasTableName)
+      .values({
+        did             : quota.did,
+        maxMessages     : quota.maxMessages,
+        maxStorageBytes : quota.maxStorageBytes,
+      })
+      .onConflict((oc) =>
+        oc.column('did').doUpdateSet({
+          maxMessages     : quota.maxMessages,
+          maxStorageBytes : quota.maxStorageBytes,
+        }),
+      )
+      .executeTakeFirst();
+  }
+
+  /**
+   * Deletes the per-tenant quota. Returns `true` if a quota existed and was deleted.
+   */
+  public async deleteQuota(did: string): Promise<boolean> {
+    const result = await this.db
+      .deleteFrom(RegistrationStore.tenantQuotasTableName)
+      .where('did', '=', did)
+      .executeTakeFirst();
+
+    return Number(result.numDeletedRows) > 0;
+  }
+}
+
+/**
+ * A row in the `registeredTenants` table.
+ */
+export interface RegisteredTenantRow {
+  did : string;
+  termsOfServiceHash : string;
+  suspended? : number;
+  accountId? : string;
+  registrationType? : string;
+  registeredAt? : string;
+  metadata? : string;
 }
 
 interface RegisteredTenants {
-  did: string;
-  termsOfServiceHash: string;
+  did : string;
+  termsOfServiceHash : string;
+  suspended : number;
+  accountId? : string;
+  registrationType? : string;
+  registeredAt? : string;
+  metadata? : string;
+}
+
+interface TenantQuotasRow {
+  did : string;
+  maxMessages : number;
+  maxStorageBytes : number;
 }
 
 interface RegistrationDatabase {
-  registeredTenants: RegisteredTenants;
+  registeredTenants : RegisteredTenants;
+  tenantQuotas : TenantQuotasRow;
 }

package/src/storage.ts

@@ -5,9 +5,9 @@ import type {
   DataStore,
   DwnConfig,
   EventLog,
-  EventStream,
   MessageStore,
   ResumableTaskStore,
+  StateIndex,
   TenantGate,
 } from '@enbox/dwn-sdk-js';
 
@@ -16,29 +16,32 @@ import Cursor from 'pg-cursor';
 import { createPool as MySQLCreatePool } from 'mysql2';
 import pg from 'pg';
 
+import { Kysely } from 'kysely';
+
 import { createBunSqliteDatabase } from '@enbox/dwn-sql-store';
 import { PluginLoader } from './plugin-loader.js';
 
 import {
   DataStoreLevel,
-  EventLogLevel,
   MessageStoreLevel,
   ResumableTaskStoreLevel,
+  StateIndexLevel,
 } from '@enbox/dwn-sdk-js';
 import {
   DataStoreSql,
-  EventLogSql,
   MessageStoreSql,
   MysqlDialect,
   PostgresDialect,
   ResumableTaskStoreSql,
+  runDwnStoreMigrations,
   SqliteDialect,
+  StateIndexSql,
 } from '@enbox/dwn-sql-store';
 
 export enum StoreType {
   DataStore,
   MessageStore,
-  EventLog,
+  StateIndex,
   ResumableTaskStore,
 }
 
@@ -49,23 +52,113 @@ export enum BackendTypes {
   POSTGRES = 'postgres',
 }
 
-export type DwnStore = DataStore | EventLog | MessageStore | ResumableTaskStore;
+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.
+ */
+const sharedDialectCache: 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) {
+    return getDialectFromUrl(connectionUrl);
+  }
+
+  const key = connectionUrl.toString();
+  const cached = sharedDialectCache.get(key);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  // Create a single pg.Pool instance with configurable sizing.
+  const pool = new pg.Pool({
+    connectionString  : connectionUrl.toString(),
+    min               : config.pgPoolMin,
+    max               : config.pgPoolMax,
+    idleTimeoutMillis : config.pgPoolIdleTimeout,
+  });
+
+  const dialect = new PostgresDialect({
+    pool   : async (): Promise<pg.Pool> => pool,
+    cursor : Cursor,
+  });
+
+  sharedDialectCache.set(key, dialect);
+  return dialect;
+}
 
 export async function getDwnConfig(
   config : DwnServerConfig,
   options : {
     didResolver? : DidResolver,
     tenantGate? : TenantGate,
-    eventStream? : EventStream,
+    eventLog? : EventLog,
   }
 ): Promise<DwnConfig> {
-  const { tenantGate, eventStream, didResolver } = options;
-  const dataStore: DataStore = await getStore(config.dataStore, StoreType.DataStore);
-  const eventLog: EventLog = await getStore(config.eventLog, StoreType.EventLog);
-  const messageStore: MessageStore = await getStore(config.messageStore, StoreType.MessageStore);
-  const resumableTaskStore: ResumableTaskStore = await getStore(config.resumableTaskStore, StoreType.ResumableTaskStore);
+  const { tenantGate, eventLog, didResolver } = options;
 
-  return { didResolver, eventStream, eventLog, dataStore, messageStore, resumableTaskStore, tenantGate };
+  // Run SQL schema migrations before creating stores. Uses the data store
+  // connection to determine the dialect — all SQL stores typically share the
+  // same database. Non-SQL backends (level://) are skipped.
+  await runSqlMigrationsIfNeeded(config);
+
+  const dataStore: DataStore = await getStore(config, config.dataStore, StoreType.DataStore);
+  const stateIndex: StateIndex = await getStore(config, config.stateIndex, StoreType.StateIndex);
+  const messageStore: MessageStore = await getStore(config, config.messageStore, StoreType.MessageStore);
+  const resumableTaskStore: ResumableTaskStore = await getStore(config, config.resumableTaskStore, StoreType.ResumableTaskStore);
+
+  return { didResolver, eventLog, stateIndex, dataStore, messageStore, resumableTaskStore, tenantGate };
+}
+
+/**
+ * Runs DWN SQL schema migrations if the data store is configured with a SQL
+ * backend. Creates a temporary Kysely instance, runs all pending migrations,
+ * then destroys it. The subsequent store `open()` calls will reuse the shared
+ * dialect/pool and find the schema already in place.
+ */
+async function runSqlMigrationsIfNeeded(config: DwnServerConfig): Promise<void> {
+  // Skip if the data store config is a file path (plugin) or non-SQL backend
+  if (isFilePath(config.dataStore)) {
+    return;
+  }
+
+  let storeUrl: URL;
+  try {
+    storeUrl = new URL(config.dataStore);
+  } catch {
+    return; // Not a valid URL — skip
+  }
+
+  const protocol = storeUrl.protocol.slice(0, -1);
+  const sqlBackends: string[] = [BackendTypes.SQLITE, BackendTypes.MYSQL, BackendTypes.POSTGRES];
+  if (!sqlBackends.includes(protocol)) {
+    return;
+  }
+
+  const dialect = getOrCreateDialect(storeUrl, config);
+  const db = new Kysely<Record<string, unknown>>({ dialect });
+  try {
+    const applied = await runDwnStoreMigrations(db, dialect);
+    if (applied.length > 0) {
+      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();
+    }
+  }
 }
 
 function getLevelStore(
@@ -82,9 +175,9 @@ function getLevelStore(
         blockstoreLocation : storeURI.host + storeURI.pathname + '/MESSAGESTORE',
         indexLocation      : storeURI.host + storeURI.pathname + '/INDEX',
       });
-    case StoreType.EventLog:
-      return new EventLogLevel({
-        location: storeURI.host + storeURI.pathname + '/EVENTLOG',
+    case StoreType.StateIndex:
+      return new StateIndexLevel({
+        location: storeURI.host + storeURI.pathname + '/STATEINDEX',
       });
     case StoreType.ResumableTaskStore:
       return new ResumableTaskStoreLevel({
@@ -96,18 +189,19 @@ function getLevelStore(
 }
 
 function getSqlStore(
+  config: DwnServerConfig,
   connectionUrl: URL,
   storeType: StoreType,
 ): DwnStore {
-  const dialect = getDialectFromUrl(connectionUrl);
+  const dialect = getOrCreateDialect(connectionUrl, config);
 
   switch (storeType) {
     case StoreType.DataStore:
       return new DataStoreSql(dialect);
     case StoreType.MessageStore:
       return new MessageStoreSql(dialect);
-    case StoreType.EventLog:
-      return new EventLogSql(dialect);
+    case StoreType.StateIndex:
+      return new StateIndexSql(dialect);
     case StoreType.ResumableTaskStore:
       return new ResumableTaskStoreSql(dialect);
     default:
@@ -123,11 +217,11 @@ function isFilePath(configString: string): boolean {
   return filePathPrefixes.some(prefix => configString.startsWith(prefix));
 }
 
-async function getStore(storeString: string, storeType: StoreType.DataStore): Promise<DataStore>;
-async function getStore(storeString: string, storeType: StoreType.EventLog): Promise<EventLog>;
-async function getStore(storeString: string, storeType: StoreType.MessageStore): Promise<MessageStore>;
-async function getStore(storeString: string, storeType: StoreType.ResumableTaskStore): Promise<ResumableTaskStore>;
-async function getStore(storeConfigString: string, storeType: StoreType): Promise<DwnStore> {
+async function getStore(config: DwnServerConfig, storeString: string, storeType: StoreType.DataStore): Promise<DataStore>;
+async function getStore(config: DwnServerConfig, storeString: string, storeType: StoreType.StateIndex): Promise<StateIndex>;
+async function getStore(config: DwnServerConfig, storeString: string, storeType: StoreType.MessageStore): Promise<MessageStore>;
+async function getStore(config: DwnServerConfig, storeString: string, storeType: StoreType.ResumableTaskStore): Promise<ResumableTaskStore>;
+async function getStore(config: DwnServerConfig, storeConfigString: string, storeType: StoreType): Promise<DwnStore> {
   if (isFilePath(storeConfigString)) {
     return await loadStoreFromFilePath(storeConfigString, storeType);
   }
@@ -142,7 +236,7 @@ async function getStore(storeConfigString: string, storeType: StoreType): Promis
     case BackendTypes.SQLITE:
     case BackendTypes.MYSQL:
     case BackendTypes.POSTGRES:
-      return getSqlStore(storeURI, storeType);
+      return getSqlStore(config, storeURI, storeType);
 
     default:
       throw invalidStorageSchemeMessage(storeURI.protocol);
@@ -159,8 +253,8 @@ async function loadStoreFromFilePath(
   switch (storeType) {
     case StoreType.DataStore:
       return await PluginLoader.loadPlugin<DataStore>(filePath);
-    case StoreType.EventLog:
-      return await PluginLoader.loadPlugin<EventLog>(filePath);
+    case StoreType.StateIndex:
+      return await PluginLoader.loadPlugin<StateIndex>(filePath);
     case StoreType.MessageStore:
       return await PluginLoader.loadPlugin<MessageStore>(filePath);
     case StoreType.ResumableTaskStore:
@@ -207,7 +301,7 @@ function invalidStorageSchemeMessage(protocol: string): string {
   }
   return (
     'Unknown storage protocol ' +
-    protocol.slice(0, 1) +
+    protocol.slice(0, -1) +
     '! Please use one of: ' +
     schemes.join(', ') +
     '. For details, see README'

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

@@ -103,7 +103,13 @@ export class SqlTtlCache {
       return undefined;
     }
 
-    return JSON.parse(entry.value);
+    try {
+      return JSON.parse(entry.value);
+    } catch {
+      // Corrupt entry — remove it and return undefined.
+      this.delete(key); // no need to await
+      return undefined;
+    }
   }
 
   /**