@enbox/dwn-server 0.0.2 → 0.0.4

package/src/admin/admin-auth.ts

@@ -0,0 +1,56 @@
+import type { DwnServerConfig } from '../config.js';
+
+import { timingSafeEqual } from 'crypto';
+
+/**
+ * Validates the admin bearer token from the `Authorization` header.
+ *
+ * @returns `null` if authentication succeeds, or a `Response` with the appropriate
+ *          error status (404 if admin is disabled, 401 if credentials are missing/invalid).
+ */
+export function validateAdminAuth(req: Request, config: DwnServerConfig): Response | null {
+  const expectedToken = config.adminToken;
+
+  // If no admin token is configured, the admin API is disabled.
+  // Return 404 to avoid revealing the endpoint exists.
+  if (!expectedToken) {
+    return new Response('Not Found', { status: 404 });
+  }
+
+  const authHeader = req.headers.get('authorization');
+  if (!authHeader) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  // Expect "Bearer <token>" format.
+  if (!authHeader.startsWith('Bearer ')) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  const suppliedToken = authHeader.slice('Bearer '.length);
+
+  if (!constantTimeEquals(expectedToken, suppliedToken)) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  return null; // auth passed
+}
+
+/**
+ * Compares two strings in constant time to prevent timing attacks.
+ * If the strings differ in length, the comparison still takes constant time
+ * relative to the expected token length.
+ */
+function constantTimeEquals(expected: string, supplied: string): boolean {
+  const expectedBuf = Buffer.from(expected, 'utf-8');
+  const suppliedBuf = Buffer.from(supplied, 'utf-8');
+
+  // If lengths differ, we still perform a comparison against the expected buffer
+  // to avoid leaking length information through timing.
+  if (expectedBuf.length !== suppliedBuf.length) {
+    timingSafeEqual(expectedBuf, expectedBuf);
+    return false;
+  }
+
+  return timingSafeEqual(expectedBuf, suppliedBuf);
+}

package/src/admin/admin-store.ts

@@ -0,0 +1,515 @@
+import type { Dialect } from '@enbox/dwn-sql-store';
+import type { AdminMessageSummary, AdminProtocolSummary, GlobalStats, TenantExport, TenantStats } from './types.js';
+
+import { Kysely } from 'kysely';
+
+import { escapeLikeWildcards } from '../lib/sql-utils.js';
+import { getDialectFromUrl } from '../storage.js';
+
+/**
+ * Provides cross-tenant SQL queries for admin operations.
+ * The DWN SDK's store interfaces are always tenant-scoped — this store
+ * runs direct SQL for operations like listing tenants and computing aggregates.
+ */
+export class AdminStore {
+  private db: Kysely<AdminDatabase>;
+  private cachedGlobalStats: GlobalStats | undefined;
+  private cachedGlobalStatsTimestamp = 0;
+  private cacheTtlMs: number;
+
+  private constructor(dialect: Dialect, cacheTtlMs: number) {
+    this.db = new Kysely<AdminDatabase>({ dialect });
+    this.cacheTtlMs = cacheTtlMs;
+  }
+
+  /**
+   * Creates an `AdminStore` from a storage URL string.
+   * @param storageUrl - A SQL connection URL (sqlite://, postgres://, mysql://).
+   * @param cacheTtlMs - TTL for cached global stats in milliseconds. Default: 60_000.
+   * @returns An `AdminStore` instance, or `undefined` if the URL uses a non-SQL backend.
+   */
+  public static create(storageUrl: string, cacheTtlMs = 60_000): AdminStore | undefined {
+    // LevelDB and file-path plugins cannot support cross-tenant queries.
+    const isFilePath = storageUrl.startsWith('/') || storageUrl.startsWith('./') || storageUrl.startsWith('../');
+    if (isFilePath || storageUrl.startsWith('level://')) {
+      return undefined;
+    }
+
+    try {
+      const dialect = getDialectFromUrl(new URL(storageUrl));
+      return new AdminStore(dialect, cacheTtlMs);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Creates an `AdminStore` from an already-initialized Kysely dialect.
+   * Used when the admin store should share the same database connection as the DWN stores
+   * (e.g., in-memory SQLite for tests).
+   */
+  public static createFromDialect(dialect: Dialect, cacheTtlMs = 60_000): AdminStore {
+    return new AdminStore(dialect, cacheTtlMs);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tenant discovery
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns `true` if the DWN SQL tables exist (i.e. the admin store shares the same DB as the DWN).
+   */
+  public async isAvailable(): Promise<boolean> {
+    try {
+      await this.db
+        .selectFrom('messageStoreMessages')
+        .select(this.db.fn.countAll<number>().as('count'))
+        .limit(1)
+        .execute();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Returns a paginated list of distinct tenant DIDs from the message store.
+   *
+   * @see https://github.com/enboxorg/enbox/issues/390
+   */
+  public async getDistinctTenants(options?: {
+    cursor? : string;
+    limit? : number;
+    search? : string;
+  }): Promise<{ tenants: string[]; cursor?: string }> {
+    const limit = options?.limit ?? 20;
+
+    let query = this.db
+      .selectFrom('messageStoreMessages')
+      .select(this.db.fn.agg<string>('distinct', ['tenant']).as('tenant'))
+      .orderBy('tenant', 'asc')
+      .limit(limit + 1); // fetch one extra to detect next page
+
+    if (options?.cursor) {
+      query = query.where('tenant', '>', options.cursor);
+    }
+
+    if (options?.search) {
+      query = query.where('tenant', 'like', `%${escapeLikeWildcards(options.search)}%`);
+    }
+
+    const results = await query.execute();
+    const tenants = results.map((r: { tenant: string }): string => r.tenant);
+
+    let cursor: string | undefined;
+    if (tenants.length > limit) {
+      tenants.pop();
+      cursor = tenants[tenants.length - 1];
+    }
+
+    return { tenants, cursor };
+  }
+
+  /**
+   * Returns the total count of distinct tenants.
+   */
+  public async getTenantCount(): Promise<number> {
+    const result = await this.db
+      .selectFrom('messageStoreMessages')
+      .select(this.db.fn.countAll<number>().as('count'))
+      .select('tenant')
+      .groupBy('tenant')
+      .execute();
+
+    return result.length;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Per-tenant aggregates
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns aggregate statistics for a single tenant.
+   */
+  public async getTenantStats(did: string): Promise<TenantStats> {
+    const [messageCount, dataStorageBytes, protocols] = await Promise.all([
+      this.getTenantMessageCount(did),
+      this.getTenantStorageSize(did),
+      this.getTenantProtocols(did),
+    ]);
+
+    return {
+      messageCount,
+      dataStorageBytes,
+      protocolCount: protocols.length,
+      protocols,
+    };
+  }
+
+  /**
+   * Returns the total number of messages for a tenant.
+   */
+  public async getTenantMessageCount(did: string): Promise<number> {
+    const result = await this.db
+      .selectFrom('messageStoreMessages')
+      .select(this.db.fn.countAll<number>().as('count'))
+      .where('tenant', '=', did)
+      .executeTakeFirstOrThrow();
+
+    return Number(result.count);
+  }
+
+  /**
+   * Returns the total data storage in bytes for a tenant.
+   */
+  public async getTenantStorageSize(did: string): Promise<number> {
+    const result = await this.db
+      .selectFrom('dataRefs')
+      .select(this.db.fn.sum<number>('dataSize').as('totalBytes'))
+      .where('tenant', '=', did)
+      .executeTakeFirstOrThrow();
+
+    return Number(result.totalBytes) || 0;
+  }
+
+  /**
+   * Returns the list of distinct protocols used by a tenant.
+   */
+  public async getTenantProtocols(did: string): Promise<string[]> {
+    const results = await this.db
+      .selectFrom('messageStoreMessages')
+      .select('protocol')
+      .distinct()
+      .where('tenant', '=', did)
+      .where('protocol', 'is not', null)
+      .execute();
+
+    return results.map((r: { protocol: string | null }): string => r.protocol!);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Global aggregates (cached)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns global server statistics. Results are cached with the configured TTL.
+   * Pass `refresh: true` to force recalculation.
+   */
+  public async getGlobalStats(options?: { refresh?: boolean }): Promise<GlobalStats> {
+    const now = Date.now();
+    if (
+      !options?.refresh &&
+      this.cachedGlobalStats !== undefined &&
+      (now - this.cachedGlobalStatsTimestamp) < this.cacheTtlMs
+    ) {
+      return this.cachedGlobalStats;
+    }
+
+    const [tenantCount, messageStats, dataStats, protocolStats] = await Promise.all([
+      this.getTenantCount(),
+      this.db
+        .selectFrom('messageStoreMessages')
+        .select(this.db.fn.countAll<number>().as('count'))
+        .executeTakeFirstOrThrow(),
+      this.db
+        .selectFrom('dataRefs')
+        .select(this.db.fn.sum<number>('dataSize').as('totalBytes'))
+        .executeTakeFirstOrThrow(),
+      this.db
+        .selectFrom('messageStoreMessages')
+        .select(
+          this.db.fn.count<number>('protocol').distinct().as('count')
+        )
+        .where('protocol', 'is not', null)
+        .executeTakeFirstOrThrow(),
+    ]);
+
+    this.cachedGlobalStats = {
+      tenantCount,
+      totalMessages  : Number(messageStats.count),
+      totalDataBytes : Number(dataStats.totalBytes) || 0,
+      totalProtocols : Number(protocolStats.count),
+    };
+    this.cachedGlobalStatsTimestamp = now;
+
+    return this.cachedGlobalStats;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tenant data purge
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Deletes all DWN data for a tenant from every SQL table.
+   * @returns The number of messages deleted.
+   */
+  public async purgeTenantData(did: string): Promise<number> {
+    // Delete messages (cascades to tags via FK).
+    const messageResult = await this.db
+      .deleteFrom('messageStoreMessages')
+      .where('tenant', '=', did)
+      .executeTakeFirstOrThrow();
+
+    // Delete data refs for this tenant and garbage-collect orphaned blocks.
+    const tenantRefs = await this.db
+      .selectFrom('dataRefs')
+      .select('dataCid')
+      .where('tenant', '=', did)
+      .execute();
+
+    await this.db
+      .deleteFrom('dataRefs')
+      .where('tenant', '=', did)
+      .execute();
+
+    // GC: delete blocks for dataCids that no longer have any refs.
+    for (const ref of tenantRefs) {
+      const remaining = await this.db
+        .selectFrom('dataRefs')
+        .select('dataCid')
+        .where('dataCid', '=', ref.dataCid)
+        .executeTakeFirst();
+
+      if (!remaining) {
+        await this.db
+          .deleteFrom('dataBlocks')
+          .where('rootDataCid', '=', ref.dataCid)
+          .execute();
+      }
+    }
+
+    // Delete state index entries.
+    await this.db.deleteFrom('stateIndexNodes').where('tenant', '=', did).execute();
+    await this.db.deleteFrom('stateIndexRoots').where('tenant', '=', did).execute();
+    await this.db.deleteFrom('stateIndexMeta').where('tenant', '=', did).execute();
+
+    // Invalidate cache.
+    this.cachedGlobalStats = undefined;
+
+    return Number(messageResult.numDeletedRows);
+  }
+
+  /**
+   * Returns the number of suspended tenants from the registration table.
+   * Returns 0 if the registration table doesn't exist.
+   */
+  public async getSuspendedTenantCount(): Promise<number> {
+    try {
+      const result = await this.db
+        .selectFrom('registeredTenants' as any)
+        .select(this.db.fn.countAll<number>().as('count'))
+        .where('suspended' as any, '=', true)
+        .executeTakeFirstOrThrow();
+
+      return Number(result.count);
+    } catch {
+      return 0;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tenant data browser
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns paginated message metadata for a single tenant.
+   * Only returns metadata columns — never returns `encodedMessageBytes` (raw message content).
+   */
+  public async getTenantMessages(did: string, options?: {
+    interface? : string;
+    method? : string;
+    protocol? : string;
+    limit? : number;
+    cursor? : number;
+  }): Promise<{ messages: AdminMessageSummary[]; cursor?: number }> {
+    const limit = Math.min(options?.limit ?? 20, 100);
+
+    let query = this.db
+      .selectFrom('messageStoreMessages')
+      .select([
+        'messageCid', 'interface', 'method', 'protocol', 'protocolPath',
+        'schema', 'dataFormat', 'dataSize', 'dateCreated', 'messageTimestamp', 'id',
+      ])
+      .where('tenant', '=', did)
+      .orderBy('id', 'desc')
+      .limit(limit + 1);
+
+    if (options?.cursor !== undefined) {
+      query = query.where('id', '<', options.cursor);
+    }
+
+    if (options?.interface !== undefined) {
+      query = query.where('interface', '=', options.interface);
+    }
+
+    if (options?.method !== undefined) {
+      query = query.where('method', '=', options.method);
+    }
+
+    if (options?.protocol !== undefined) {
+      query = query.where('protocol', '=', options.protocol);
+    }
+
+    const results = await query.execute();
+
+    const messages: (AdminMessageSummary & { _id: number })[] = results.map((row): AdminMessageSummary & { _id: number } => ({
+      _id              : Number(row.id),
+      messageCid       : row.messageCid,
+      interface        : row.interface,
+      method           : row.method,
+      protocol         : row.protocol,
+      protocolPath     : row.protocolPath,
+      schema           : row.schema,
+      dataFormat       : row.dataFormat,
+      dataSize         : row.dataSize !== null ? Number(row.dataSize) : null,
+      dateCreated      : row.dateCreated,
+      messageTimestamp : row.messageTimestamp,
+    }));
+
+    let cursor: number | undefined;
+    if (messages.length > limit) {
+      messages.pop();
+      cursor = messages[messages.length - 1]._id;
+    }
+
+    // Strip internal _id before returning.
+    const cleaned: AdminMessageSummary[] = messages.map(({ _id, ...rest }): AdminMessageSummary => rest);
+
+    return { messages: cleaned, cursor };
+  }
+
+  /**
+   * Returns per-protocol message counts for a tenant.
+   */
+  public async getTenantProtocolCounts(did: string): Promise<AdminProtocolSummary[]> {
+    const results = await this.db
+      .selectFrom('messageStoreMessages')
+      .select([
+        'protocol',
+        this.db.fn.countAll<number>().as('messageCount'),
+      ])
+      .where('tenant', '=', did)
+      .where('protocol', 'is not', null)
+      .groupBy('protocol')
+      .orderBy('messageCount', 'desc')
+      .execute();
+
+    return results.map((row): AdminProtocolSummary => ({
+      protocol     : row.protocol!,
+      messageCount : Number(row.messageCount),
+    }));
+  }
+
+  /**
+   * Exports all message metadata and data records for a tenant as an array.
+   * Returns `{ messages, data, metadata }` for streaming/serialization.
+   *
+   * @see https://github.com/enboxorg/enbox/issues/391
+   */
+  public async exportTenantData(did: string): Promise<TenantExport> {
+    const messages = await this.db
+      .selectFrom('messageStoreMessages')
+      .select([
+        'messageCid', 'interface', 'method', 'recordId', 'protocol',
+        'protocolPath', 'schema', 'author', 'recipient', 'messageTimestamp',
+        'dateCreated', 'datePublished', 'published', 'dataFormat', 'dataCid', 'dataSize',
+      ])
+      .where('tenant', '=', did)
+      .orderBy('id', 'asc')
+      .execute();
+
+    const dataRecords = await this.db
+      .selectFrom('dataRefs')
+      .select(['recordId', 'dataCid', 'dataSize'])
+      .where('tenant', '=', did)
+      .execute();
+
+    return {
+      metadata: {
+        tenant          : did,
+        exportedAt      : new Date().toISOString(),
+        messageCount    : messages.length,
+        dataRecordCount : dataRecords.length,
+      },
+      messages    : messages.map((m): Record<string, unknown> => ({ ...m })),
+      dataRecords : dataRecords.map((d): Record<string, unknown> => ({
+        recordId : d.recordId,
+        dataCid  : d.dataCid,
+        dataSize : Number(d.dataSize),
+      })),
+    };
+  }
+
+  /**
+   * Closes the underlying database connection.
+   */
+  public async close(): Promise<void> {
+    await this.db.destroy();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Kysely type definitions for the DWN SQL tables
+// ---------------------------------------------------------------------------
+
+interface MessageStoreMessages {
+  id : number;
+  tenant : string;
+  messageCid : string;
+  interface : string | null;
+  method : string | null;
+  recordId : string | null;
+  protocol : string | null;
+  protocolPath : string | null;
+  schema : string | null;
+  author : string | null;
+  recipient : string | null;
+  messageTimestamp : string | null;
+  dateCreated : string | null;
+  datePublished : string | null;
+  published : boolean | null;
+  dataFormat : string | null;
+  dataCid : string | null;
+  dataSize : number | null;
+  encodedMessageBytes : Uint8Array;
+}
+
+interface DataRefsRow {
+  tenant : string;
+  recordId : string;
+  dataCid : string;
+  dataSize : number;
+}
+
+interface DataBlocksRow {
+  rootDataCid : string;
+  blockCid : string;
+  data : Uint8Array;
+}
+
+interface StateIndexNodes {
+  tenant : string;
+  scope : string;
+  nodeHash : string;
+}
+
+interface StateIndexRoots {
+  tenant : string;
+  scope : string;
+  rootHash : string;
+}
+
+interface StateIndexMeta {
+  tenant : string;
+  messageCid : string;
+  protocol : string | null;
+}
+
+interface AdminDatabase {
+  messageStoreMessages : MessageStoreMessages;
+  dataRefs : DataRefsRow;
+  dataBlocks : DataBlocksRow;
+  stateIndexNodes : StateIndexNodes;
+  stateIndexRoots : StateIndexRoots;
+  stateIndexMeta : StateIndexMeta;
+}