@enbox/dwn-server 0.0.2 → 0.0.4

package/src/registration/registration-manager.ts

@@ -1,12 +1,14 @@
-import { ProofOfWorkManager } from "./proof-of-work-manager.js";
-import { ProofOfWork } from "./proof-of-work.js";
-import { RegistrationStore } from "./registration-store.js";
-import type { RegistrationData, RegistrationRequest } from "./registration-types.js";
-import type { ProofOfWorkChallengeModel } from "./proof-of-work-types.js";
-import { DwnServerError, DwnServerErrorCode } from "../dwn-error.js";
-import type { ActiveTenantCheckResult, TenantGate } from "@enbox/dwn-sdk-js";
-import { getDialectFromUrl } from "../storage.js";
-import { readFileSync } from "fs";
+import type { ProviderAuthPlugin } from './provider-auth-plugin.js';
+import type { ActiveTenantCheckResult, TenantGate } from '@enbox/dwn-sdk-js';
+import type { ProofOfWorkChallengeModel, RegistrationRequest } from '@enbox/dwn-clients';
+
+import { readFileSync } from 'fs';
+
+import { getDialectFromUrl } from '../storage.js';
+import { ProofOfWork } from './proof-of-work.js';
+import { ProofOfWorkManager } from './proof-of-work-manager.js';
+import { RegistrationStore } from './registration-store.js';
+import { DwnServerError, DwnServerErrorCode } from '../dwn-error.js';
 
 /**
  * The RegistrationManager is responsible for managing the registration of tenants.
@@ -14,6 +16,7 @@ import { readFileSync } from "fs";
  */
 export class RegistrationManager implements TenantGate {
   private proofOfWorkManager: ProofOfWorkManager;
+  private providerAuthPlugin?: ProviderAuthPlugin;
   private registrationStore: RegistrationStore;
 
   private termsOfServiceHash?: string;
@@ -27,7 +30,7 @@ export class RegistrationManager implements TenantGate {
   }
 
   /**
-   * The terms-of-service hash. 
+   * The terms-of-service hash.
    */
   public getTermsOfServiceHash(): string | undefined {
     return this.termsOfServiceHash;
@@ -45,13 +48,14 @@ export class RegistrationManager implements TenantGate {
    * Creates a new RegistrationManager instance.
    * @param input.registrationStoreUrl - The URL of the registration store.
    * Set to `undefined` or empty string if tenant registration is not required (ie. DWN is open for all).
-   * 
+   *
    */
   public static async create(input: {
     registrationStoreUrl?: string,
-    termsOfServiceFilePath?: string
+    termsOfServiceFilePath?: string,
     proofOfWorkChallengeNonceSeed?: string,
     proofOfWorkInitialMaximumAllowedHash?: string,
+    providerAuthPlugin?: ProviderAuthPlugin,
   }): Promise<RegistrationManager> {
     const { termsOfServiceFilePath, registrationStoreUrl } = input;
 
@@ -70,17 +74,22 @@ export class RegistrationManager implements TenantGate {
 
     // Initialize and start ProofOfWorkManager.
     registrationManager.proofOfWorkManager = await ProofOfWorkManager.create({
-      autoStart: true,
-      desiredSolveCountPerMinute: 10,
-      initialMaximumAllowedHashValue: input.proofOfWorkInitialMaximumAllowedHash,
-      challengeSeed: input.proofOfWorkChallengeNonceSeed,
+      autoStart                      : true,
+      desiredSolveCountPerMinute     : 10,
+      initialMaximumAllowedHashValue : input.proofOfWorkInitialMaximumAllowedHash,
+      challengeSeed                  : input.proofOfWorkChallengeNonceSeed,
     });
 
     // Initialize RegistrationStore.
     const sqlDialect = getDialectFromUrl(new URL(registrationStoreUrl));
     const registrationStore = await RegistrationStore.create(sqlDialect);
     registrationManager.registrationStore = registrationStore;
-    
+
+    // Store optional provider auth plugin.
+    if (input.providerAuthPlugin !== undefined) {
+      registrationManager.providerAuthPlugin = input.providerAuthPlugin;
+    }
+
     return registrationManager;
   }
 
@@ -93,17 +102,79 @@ export class RegistrationManager implements TenantGate {
   }
 
   /**
-   * Handles a registration request.
+   * Handles a registration request by dispatching to the appropriate handler
+   * based on the credentials provided.
    */
   public async handleRegistrationRequest(registrationRequest: RegistrationRequest): Promise<void> {
-    // Ensure the supplied terms of service hash matches the one we require.
-    if (registrationRequest.registrationData.termsOfServiceHash !== this.termsOfServiceHash) {
-      throw new DwnServerError(DwnServerErrorCode.RegistrationManagerInvalidOrOutdatedTermsOfServiceHash,
-        `Expecting terms-of-service hash ${this.termsOfServiceHash}, but got ${registrationRequest.registrationData.termsOfServiceHash}.`
+    if (registrationRequest.providerAuth?.registrationToken !== undefined) {
+      await this.handleProviderAuthRegistration(registrationRequest);
+    } else if (registrationRequest.proofOfWork !== undefined) {
+      await this.handleProofOfWorkRegistration(registrationRequest);
+    } else {
+      throw new DwnServerError(
+        DwnServerErrorCode.RegistrationRequestMissingCredentials,
+        'Registration request must include either providerAuth or proofOfWork credentials.',
       );
     }
+  }
 
-    const { challengeNonce, responseNonce } = registrationRequest.proofOfWork;
+  /**
+   * Handles a provider-auth registration request.
+   */
+  private async handleProviderAuthRegistration(registrationRequest: RegistrationRequest): Promise<void> {
+    if (this.providerAuthPlugin === undefined) {
+      throw new DwnServerError(
+        DwnServerErrorCode.ProviderAuthNotEnabled,
+        'Provider auth registration is not enabled on this server.',
+      );
+    }
+
+    const token = registrationRequest.providerAuth!.registrationToken;
+    const validationResult = await this.providerAuthPlugin.validateRegistrationToken(token);
+
+    if (!validationResult.isValid) {
+      throw new DwnServerError(
+        DwnServerErrorCode.ProviderAuthTokenInvalid,
+        validationResult.detail ?? 'Provider auth registration token is invalid.',
+      );
+    }
+
+    // Validate ToS only when the server has ToS configured AND the request includes a hash.
+    if (this.termsOfServiceHash !== undefined && registrationRequest.registrationData.termsOfServiceHash !== undefined) {
+      if (registrationRequest.registrationData.termsOfServiceHash !== this.termsOfServiceHash) {
+        throw new DwnServerError(DwnServerErrorCode.RegistrationManagerInvalidOrOutdatedTermsOfServiceHash,
+          `Expecting terms-of-service hash ${this.termsOfServiceHash}, ` +
+          `but got ${registrationRequest.registrationData.termsOfServiceHash}.`,
+        );
+      }
+    }
+
+    await this.registrationStore.insertOrUpdateTenantRegistration({
+      did                : registrationRequest.registrationData.did,
+      termsOfServiceHash : registrationRequest.registrationData.termsOfServiceHash,
+      accountId          : validationResult.accountId,
+      registrationType   : 'provider-auth',
+      metadata           : validationResult.metadata !== undefined
+        ? JSON.stringify(validationResult.metadata)
+        : undefined,
+    });
+  }
+
+  /**
+   * Handles a proof-of-work registration request.
+   */
+  private async handleProofOfWorkRegistration(registrationRequest: RegistrationRequest): Promise<void> {
+    // Validate ToS only when the server has ToS configured.
+    if (this.termsOfServiceHash !== undefined) {
+      if (registrationRequest.registrationData.termsOfServiceHash !== this.termsOfServiceHash) {
+        throw new DwnServerError(DwnServerErrorCode.RegistrationManagerInvalidOrOutdatedTermsOfServiceHash,
+          `Expecting terms-of-service hash ${this.termsOfServiceHash}, ` +
+          `but got ${registrationRequest.registrationData.termsOfServiceHash}.`,
+        );
+      }
+    }
+
+    const { challengeNonce, responseNonce } = registrationRequest.proofOfWork!;
 
     await this.proofOfWorkManager.verifyProofOfWork({
       challengeNonce,
@@ -112,14 +183,24 @@ export class RegistrationManager implements TenantGate {
     });
 
     // Store tenant registration data in database.
-    await this.recordTenantRegistration(registrationRequest.registrationData);
+    await this.recordTenantRegistration({
+      did                : registrationRequest.registrationData.did,
+      termsOfServiceHash : registrationRequest.registrationData.termsOfServiceHash,
+      registrationType   : 'proof-of-work',
+    });
   }
 
   /**
    * Records the given registration data in the database.
    * Exposed as a public method for testing purposes.
    */
-  public async recordTenantRegistration(registrationData: RegistrationData): Promise<void> {
+  public async recordTenantRegistration(registrationData: {
+    did: string;
+    termsOfServiceHash?: string;
+    accountId?: string;
+    registrationType?: string;
+    metadata?: string;
+  }): Promise<void> {
     await this.registrationStore.insertOrUpdateTenantRegistration(registrationData);
   }
 
@@ -136,18 +217,35 @@ export class RegistrationManager implements TenantGate {
 
     if (tenantRegistration === undefined) {
       return {
-        isActiveTenant: false,
-        detail: 'Not a registered tenant.'
+        isActiveTenant : false,
+        detail         : 'Not a registered tenant.'
       };
     }
 
-    if (tenantRegistration.termsOfServiceHash !== this.termsOfServiceHash) {
+    if (tenantRegistration.suspended) {
       return {
-        isActiveTenant: false,
-        detail: 'Agreed terms-of-service is outdated.'
+        isActiveTenant : false,
+        detail         : 'Tenant is suspended.'
       };
     }
 
-    return { isActiveTenant: true }
+    // Only enforce ToS hash check when the server has a ToS configured.
+    if (this.termsOfServiceHash !== undefined &&
+      tenantRegistration.termsOfServiceHash !== this.termsOfServiceHash) {
+      return {
+        isActiveTenant : false,
+        detail         : 'Agreed terms-of-service is outdated.'
+      };
+    }
+
+    return { isActiveTenant: true };
+  }
+
+  /**
+   * Returns the underlying RegistrationStore, if initialized.
+   * Used by the admin API to access tenant data.
+   */
+  public getRegistrationStore(): RegistrationStore | undefined {
+    return this.registrationStore;
   }
 }

package/src/registration/registration-store.ts

@@ -1,12 +1,16 @@
-import { Kysely } from 'kysely';
-import type { RegistrationData } from './registration-types.js';
 import type { Dialect } from '@enbox/dwn-sql-store';
+import type { TenantQuota } from '../admin/types.js';
+
+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>;
 
@@ -18,46 +22,114 @@ 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> {
     await this.db.schema
-    .createTable(RegistrationStore.registeredTenantTableName)
-    .ifNotExists()
-    .addColumn('did', 'text', (column) => column.primaryKey())
-    .addColumn('termsOfServiceHash', 'text')
-    .execute();
+      .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']) {
+      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();
 
@@ -67,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;
 }