@enbox/dwn-server 0.0.3 → 0.0.5

package/src/http-api.ts

@@ -1,28 +1,50 @@
+import type { JsonRpcRequest } from '@enbox/dwn-clients';
 import type { RecordsReadReply } from '@enbox/dwn-sdk-js';
+import type { ServerInfo } from '@enbox/dwn-clients';
 import type { Server, ServerWebSocket } from 'bun';
 
+import type { ActivityLog } from './admin/activity-log.js';
+import type { AdminApi } from './admin/admin-api.js';
+import type { AdminStore } from './admin/admin-store.js';
+import type { DwnServerConfig } from './config.js';
+import type { DwnServerError } from './dwn-error.js';
+import type { MessageProcessedHook } from './message-processed-hook.js';
+import type { OpenAuthHandler } from './registration/open-auth-handler.js';
+import type { RateLimiter } from './rate-limiter.js';
+import type { RegistrationManager } from './registration/registration-manager.js';
+import type { RegistrationStore } from './registration/registration-store.js';
+import type { RequestContext } from './lib/json-rpc-router.js';
+import type { SocketConnection } from './connection/socket-connection.js';
+
 import log from 'loglevel';
 
 import { Convert } from '@enbox/common';
-import { readFileSync } from 'fs';
 import { register } from 'prom-client';
 import { v4 as uuidv4 } from 'uuid';
+import { createJsonRpcErrorResponse, JsonRpcErrorCodes } from '@enbox/dwn-clients';
 import { DataStream, DateSort, type Dwn, ProtocolsQuery, RecordsQuery, RecordsRead } from '@enbox/dwn-sdk-js';
-
-
-import type { DwnServerConfig } from './config.js';
-import type { DwnServerError } from './dwn-error.js';
-import type { JsonRpcRequest } from './lib/json-rpc.js';
-import type { RegistrationManager } from './registration/registration-manager.js';
-import type { RequestContext } from './lib/json-rpc-router.js';
-import type { SocketConnection } from './connection/socket-connection.js';
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
 
 import { config } from './config.js';
 import { jsonRpcRouter } from './json-rpc-api.js';
+import { validateAdminAuth } from './admin/admin-auth.js';
 import { Web5ConnectServer } from './web5-connect/web5-connect-server.js';
-import { createJsonRpcErrorResponse, JsonRpcErrorCodes } from './lib/json-rpc.js';
 import { requestCounter, responseHistogram } from './metrics.js';
 
+/** Property names that must never be used as keys when building objects from user input. */
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+// Resolve admin UI dist path at module load time. Gracefully handle the case
+// where the admin UI package is not installed.
+let resolvedAdminUiPath: string | undefined;
+try {
+  const adminUiModule = require('@enbox/dwn-server-admin-ui');
+  resolvedAdminUiPath = adminUiModule.adminUiDistPath;
+} catch {
+  // Admin UI package not installed — static serving will be disabled.
+}
+
 /** Data attached to each Bun WebSocket via `ws.data`. */
 export interface WsData {
   connection: SocketConnection;
@@ -32,6 +54,15 @@ export class HttpApi {
   #config: DwnServerConfig;
   #packageInfo: { version?: string, sdkVersion?: string, server: string };
   #server!: Server<WsData>;
+  #adminApi: AdminApi | undefined;
+  #activityLog: ActivityLog | undefined;
+  #adminStore: AdminStore | undefined;
+  #registrationStore: RegistrationStore | undefined;
+  #ipRateLimiter: RateLimiter | undefined;
+  #tenantRateLimiter: RateLimiter | undefined;
+  #messageProcessedHooks: MessageProcessedHook[];
+  #openAuthHandler: OpenAuthHandler | undefined;
+  #adminUiPath: string | undefined;
   web5ConnectServer: Web5ConnectServer;
   registrationManager: RegistrationManager;
   dwn: Dwn;
@@ -42,11 +73,20 @@ export class HttpApi {
   private constructor() { }
 
   public static async create(
-    config: DwnServerConfig, dwn: Dwn, registrationManager?: RegistrationManager
+    config: DwnServerConfig, dwn: Dwn, registrationManager?: RegistrationManager,
+    adminApi?: AdminApi, activityLog?: ActivityLog,
+    options?: {
+      adminStore? : AdminStore;
+      registrationStore? : RegistrationStore;
+      ipRateLimiter? : RateLimiter;
+      tenantRateLimiter? : RateLimiter;
+      messageProcessedHooks? : MessageProcessedHook[];
+      openAuthHandler? : OpenAuthHandler;
+    },
   ): Promise<HttpApi> {
     const httpApi = new HttpApi();
 
-    log.info(config);
+    log.info(HttpApi.#redactConfig(config));
 
     httpApi.#packageInfo = {
       server: config.serverName,
@@ -64,6 +104,15 @@ export class HttpApi {
 
     httpApi.#config = config;
     httpApi.dwn = dwn;
+    httpApi.#adminApi = adminApi;
+    httpApi.#activityLog = activityLog;
+    httpApi.#adminStore = options?.adminStore;
+    httpApi.#registrationStore = options?.registrationStore;
+    httpApi.#ipRateLimiter = options?.ipRateLimiter;
+    httpApi.#tenantRateLimiter = options?.tenantRateLimiter;
+    httpApi.#messageProcessedHooks = options?.messageProcessedHooks ?? [];
+    httpApi.#openAuthHandler = options?.openAuthHandler;
+    httpApi.#adminUiPath = resolvedAdminUiPath;
 
     if (registrationManager !== undefined) {
       httpApi.registrationManager = registrationManager;
@@ -81,6 +130,18 @@ export class HttpApi {
     return this.#server;
   }
 
+  get ipRateLimiter(): RateLimiter | undefined {
+    return this.#ipRateLimiter;
+  }
+
+  get tenantRateLimiter(): RateLimiter | undefined {
+    return this.#tenantRateLimiter;
+  }
+
+  get messageProcessedHooks(): MessageProcessedHook[] {
+    return this.#messageProcessedHooks;
+  }
+
   // ---------------------------------------------------------------------------
   // HTTP request handler
   // ---------------------------------------------------------------------------
@@ -106,6 +167,25 @@ export class HttpApi {
           return new Response('WebSocket upgrade failed', { status: 400 });
         }
 
+        // --- Per-IP rate limiting ---
+        if (self.#ipRateLimiter) {
+          const ip = server.requestIP(req)?.address ?? 'unknown';
+          const result = self.#ipRateLimiter.consume(ip);
+          if (result.allowed === false) {
+            const retryAfterSec = Math.ceil(result.retryAfterMs / 1000);
+            return new Response(
+              JSON.stringify({ error: 'Rate limit exceeded' }),
+              {
+                status  : 429,
+                headers : {
+                  'content-type' : 'application/json',
+                  'retry-after'  : String(retryAfterSec),
+                },
+              },
+            );
+          }
+        }
+
         // --- Route matching ---
         let response: Response;
         try {
@@ -116,10 +196,15 @@ export class HttpApi {
         }
 
         // --- CORS headers ---
-        response.headers.set('access-control-allow-origin', '*');
-        response.headers.set('access-control-allow-methods', 'GET, POST, OPTIONS');
-        response.headers.set('access-control-allow-headers', '*');
-        response.headers.set('access-control-expose-headers', 'dwn-response');
+        // Admin API and metrics endpoints do not receive wildcard CORS headers
+        // to limit cross-origin access when the admin token is configured.
+        const isAdminRoute = path.startsWith('/admin') || path === '/metrics';
+        if (!isAdminRoute) {
+          response.headers.set('access-control-allow-origin', '*');
+          response.headers.set('access-control-allow-methods', 'GET, POST, OPTIONS');
+          response.headers.set('access-control-allow-headers', '*');
+          response.headers.set('access-control-expose-headers', 'dwn-response');
+        }
 
         // --- Response-time metrics ---
         const elapsed = performance.now() - startTime;
@@ -134,6 +219,7 @@ export class HttpApi {
       },
 
       websocket: {
+        maxPayloadLength: self.#config.maxRecordDataSize,
         open(ws: ServerWebSocket<WsData>): void {
           if (self.onWebSocketConnection) {
             self.onWebSocketConnection(ws);
@@ -151,17 +237,65 @@ export class HttpApi {
             connection.close();
           }
         },
-        // Bun automatically responds to pings with pongs
+        pong(ws: ServerWebSocket<WsData>): void {
+          const connection = ws.data?.connection;
+          if (connection) {
+            connection.pong();
+          }
+        },
       },
     });
   }
 
   async close(): Promise<void> {
+    if (this.#openAuthHandler) {
+      this.#openAuthHandler.destroy();
+    }
     if (this.#server) {
       this.#server.stop(true); // close all connections immediately
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // Admin UI static file serving
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Serves static files from the admin UI dist directory. Returns `null` when
+   * the admin UI package is not installed or the requested file does not exist.
+   * All non-file paths under `/admin` fall back to `index.html` (SPA routing).
+   */
+  #serveAdminUi(path: string): Response | null {
+    if (!this.#adminUiPath) {
+      return null;
+    }
+
+    // Strip the `/admin` prefix to get the file path within the dist directory.
+    const relativePath = path.replace(/^\/admin\/?/, '');
+
+    // Map to a file on disk. Empty path or paths without an extension get
+    // the SPA index.html (client-side routing).
+    let filePath: string;
+    if (relativePath === '' || !relativePath.includes('.')) {
+      filePath = join(this.#adminUiPath, 'index.html');
+    } else {
+      filePath = join(this.#adminUiPath, relativePath);
+    }
+
+    // Prevent path traversal: resolved path must stay within the admin UI directory.
+    const resolvedBase = resolve(this.#adminUiPath);
+    if (!resolve(filePath).startsWith(resolvedBase)) {
+      return null;
+    }
+
+    if (!existsSync(filePath)) {
+      return null;
+    }
+
+    const file = Bun.file(filePath);
+    return new Response(file);
+  }
+
   // ---------------------------------------------------------------------------
   // Router
   // ---------------------------------------------------------------------------
@@ -178,6 +312,13 @@ 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;
+        }
+      }
       try {
         const metricsBody = await register.metrics();
         return new Response(metricsBody, {
@@ -204,6 +345,32 @@ export class HttpApi {
       return this.#handleJsonRpcPost(req);
     }
 
+    // --- Admin API routes ---
+    if (path.startsWith('/admin/api/') && this.#adminApi) {
+      return this.#adminApi.route(req, url, path, method);
+    }
+
+    // --- Admin UI static files (only when admin API is enabled) ---
+    if (method === 'GET' && path.startsWith('/admin') && this.#adminApi) {
+      const uiResponse = this.#serveAdminUi(path);
+      if (uiResponse) {
+        return uiResponse;
+      }
+    }
+
+    // --- Provider auth (open-auth) routes ---
+    if (this.#openAuthHandler && path.startsWith('/provider-auth/')) {
+      if (method === 'GET' && path === '/provider-auth/authorize') {
+        return this.#openAuthHandler.handleAuthorize(url);
+      }
+      if (method === 'POST' && path === '/provider-auth/token') {
+        return this.#openAuthHandler.handleToken(req);
+      }
+      if (method === 'POST' && path === '/provider-auth/refresh') {
+        return this.#openAuthHandler.handleRefresh(req);
+      }
+    }
+
     // --- Registration routes ---
     const registrationResponse = await this.#matchRegistrationRoutes(req, path, method);
     if (registrationResponse) {
@@ -275,6 +442,38 @@ export class HttpApi {
     return new Response('Not Found', { status: 404 });
   }
 
+  // ---------------------------------------------------------------------------
+  // Security helpers
+  // ---------------------------------------------------------------------------
+
+  /** Returns `true` if the given key is a prototype-pollution-dangerous property name. */
+  static #isDangerousKey(key: string | undefined): boolean {
+    return key !== undefined && DANGEROUS_KEYS.has(key);
+  }
+
+  /** Returns `true` if any element in `keys` is a dangerous property name. */
+  static #hasDangerousKey(keys: string[]): boolean {
+    return keys.some(k => DANGEROUS_KEYS.has(k));
+  }
+
+  /** Returns a shallow copy of the config with sensitive values redacted for logging. */
+  static #redactConfig(cfg: DwnServerConfig): Record<string, unknown> {
+    const redacted: Record<string, unknown> = { ...cfg };
+    const sensitiveKeys = ['adminToken', 'providerAuthJwtSecret'];
+    for (const key of sensitiveKeys) {
+      if (redacted[key]) {
+        redacted[key] = '[REDACTED]';
+      }
+    }
+    // Redact passwords in connection-string-like values.
+    for (const [key, value] of Object.entries(redacted)) {
+      if (typeof value === 'string' && /^(?:postgres|mysql|sqlite):\/\//.test(value) && value.includes('@')) {
+        redacted[key] = value.replace(/:\/\/([^:]+):([^@]+)@/, '://$1:****@');
+      }
+    }
+    return redacted;
+  }
+
   // ---------------------------------------------------------------------------
   // Handlers
   // ---------------------------------------------------------------------------
@@ -287,16 +486,31 @@ export class HttpApi {
     if (config.termsOfServiceFilePath !== undefined) {
       registrationRequirements.push('terms-of-service');
     }
+    if (config.providerAuthEnabled && !registrationRequirements.includes('provider-auth-v0')) {
+      registrationRequirements.push('provider-auth-v0');
+    }
 
-    return Response.json({
-      url                      : config.baseUrl,
-      server                   : this.#packageInfo.server,
+    const serverInfo: ServerInfo = {
       maxFileSize              : config.maxRecordDataSize,
+      maxInFlight              : config.maxInFlight,
       registrationRequirements : registrationRequirements,
-      version                  : this.#packageInfo.version,
+      server                   : this.#packageInfo.server,
       sdkVersion               : this.#packageInfo.sdkVersion,
+      url                      : config.baseUrl,
+      version                  : this.#packageInfo.version,
       webSocketSupport         : config.webSocketSupport,
-    });
+    };
+
+    if (config.providerAuthEnabled) {
+      serverInfo.providerAuth = {
+        authorizeUrl  : config.providerAuthAuthorizeUrl,
+        tokenUrl      : config.providerAuthTokenUrl,
+        refreshUrl    : config.providerAuthRefreshUrl,
+        managementUrl : config.providerAuthManagementUrl,
+      };
+    }
+
+    return Response.json(serverInfo);
   }
 
   async #handleJsonRpcPost(req: Request): Promise<Response> {
@@ -319,9 +533,13 @@ export class HttpApi {
       return Response.json(reply, { status: 400 });
     }
 
-    // Read the request body into bytes first, then wrap in a fresh ReadableStream.
-    // Bun's native Request.body stream has an incompatible reader.releaseLock()
-    // that breaks DWN SDK's DataStream.toBytes(), so we materialise the body here.
+    // Materialise the request body before passing to DWN.
+    // Bun's Bun.serve() returns a ReadableStream for req.body that is
+    // incompatible with the ReadableStream consumer code in dwn-sdk-js,
+    // causing DataStream.toBytes() to crash with "undefined is not a
+    // function" at reader.releaseLock().  Buffering via arrayBuffer()
+    // converts it into a well-behaved stream that dwn-sdk-js can consume.
+    // TODO: https://github.com/enboxorg/enbox/issues/90 — remove once Bun ships fix
     const contentLength = req.headers.get('content-length');
     const transferEncoding = req.headers.get('transfer-encoding');
     let requestDataStream: ReadableStream<Uint8Array> | undefined;
@@ -331,15 +549,31 @@ export class HttpApi {
     }
 
     const requestContext: RequestContext = {
-      dwn        : this.dwn,
-      transport  : 'http',
-      dataStream : requestDataStream,
+      dwn                   : this.dwn,
+      transport             : 'http',
+      dataStream            : requestDataStream,
+      activityLog           : this.#activityLog,
+      adminStore            : this.#adminStore,
+      registrationStore     : this.#registrationStore,
+      config                : this.#config,
+      tenantRateLimiter     : this.#tenantRateLimiter,
+      messageProcessedHooks : this.#messageProcessedHooks,
     };
     const { jsonRpcResponse, dataStream: responseDataStream } =
       await jsonRpcRouter.handle(dwnRpcRequest, requestContext);
 
     if (jsonRpcResponse.error) {
       requestCounter.inc({ method: dwnRpcRequest.method, error: 1 });
+
+      // Return HTTP 429 with Retry-After header for rate-limit rejections.
+      if (jsonRpcResponse.error.code === JsonRpcErrorCodes.TooManyRequests) {
+        const retryAfterSec = jsonRpcResponse.error.data?.retryAfterSec ?? 1;
+        return Response.json(jsonRpcResponse, {
+          status  : 429,
+          headers : { 'retry-after': String(retryAfterSec) },
+        });
+      }
+
       return Response.json(jsonRpcResponse, { status: 500 });
     }
 
@@ -400,6 +634,9 @@ export class HttpApi {
       for (const [param, value] of url.searchParams) {
         const keys = param.split('.');
         const lastKey = keys.pop();
+        if (HttpApi.#hasDangerousKey(keys) || HttpApi.#isDangerousKey(lastKey)) {
+          continue;
+        }
         const nestObj = (obj: Record<string, any>, key: string): Record<string, any> =>
           obj[key] = obj[key] || {};
         const lastLevelObject = keys.reduce(nestObj, queryOptions);
@@ -481,6 +718,9 @@ export class HttpApi {
       for (const [param, value] of url.searchParams) {
         const keys = param.split('.');
         const lastKey = keys.pop();
+        if (HttpApi.#hasDangerousKey(keys) || HttpApi.#isDangerousKey(lastKey)) {
+          continue;
+        }
         const nestObj = (obj: Record<string, any>, key: string): Record<string, any> =>
           obj[key] = obj[key] || {};
         const lastLevelObject = keys.reduce(nestObj, recordsQueryOptions);
@@ -498,7 +738,8 @@ export class HttpApi {
         headers: { 'content-type': 'application/json' },
       });
     } catch (error) {
-      return Response.json(error, { status: 400 });
+      log.error('Error processing query records request', error);
+      return Response.json({ error: 'Bad Request' }, { status: 400 });
     }
   }
 
@@ -523,7 +764,7 @@ export class HttpApi {
     if (method === 'POST' && path === '/registration'
       && this.#config.registrationStoreUrl !== undefined) {
       const requestBody = await req.json();
-      log.info('Registration request:', requestBody);
+      log.info('Registration request received');
 
       try {
         await this.registrationManager.handleRegistrationRequest(requestBody);

package/src/index.ts

@@ -1,6 +1,17 @@
-export { DwnServerConfig } from './config.js';
+export { ActivityLog, AdminApi, AdminStore } from './admin/index.js';
+export type {
+  AdminActivityEvent,
+  AdminConnectionSnapshot,
+  AdminHealthCheck,
+  AdminServerStats,
+  AdminTenantDetail,
+  AdminTenantSummary,
+} from './admin/index.js';
+export { config as defaultDwnServerConfig, DwnServerConfig } from './config.js';
+export { DeliveryService } from './delivery-service.js';
 export { DwnServer, DwnServerOptions } from './dwn-server.js';
 export { HttpApi } from './http-api.js';
 export { jsonRpcRouter } from './json-rpc-api.js';
-export { StoreType, BackendTypes, DwnStore } from './storage.js';
+export type { MessageProcessedContext, MessageProcessedHook } from './message-processed-hook.js';
+export { getDwnConfig, StoreType, BackendTypes, DwnStore } from './storage.js';
 export { WsApi } from './ws-api.js';

package/src/json-rpc-api.ts

@@ -1,11 +1,12 @@
 import { JsonRpcRouter } from './lib/json-rpc-router.js';
 
 import { handleDwnProcessMessage } from './json-rpc-handlers/dwn/index.js';
-import { handleSubscriptionsClose } from './json-rpc-handlers/subscription/index.js';
+import { handleSubscriptionAck, handleSubscriptionsClose } from './json-rpc-handlers/subscription/index.js';
 
 export const jsonRpcRouter = new JsonRpcRouter();
 
 jsonRpcRouter.on('dwn.processMessage', handleDwnProcessMessage);
 jsonRpcRouter.on('rpc.subscribe.dwn.processMessage', handleDwnProcessMessage);
 
+jsonRpcRouter.on('rpc.ack', handleSubscriptionAck);
 jsonRpcRouter.on('rpc.subscribe.close', handleSubscriptionsClose);

package/src/json-rpc-handlers/dwn/process-message.ts

@@ -4,17 +4,19 @@ import { DwnInterfaceName, DwnMethodName } from '@enbox/dwn-sdk-js';
 import log from 'loglevel';
 import { v4 as uuidv4 } from 'uuid';
 
-import type { JsonRpcSubscription } from '../../lib/json-rpc.js';
+import type { JsonRpcSubscription } from '@enbox/dwn-clients';
 import type {
   HandlerResponse,
   JsonRpcHandler,
 } from '../../lib/json-rpc-router.js';
 
+import { DwnServerErrorCode } from '../../dwn-error.js';
+import { requestDataBytesTotal } from '../../metrics.js';
 import {
   createJsonRpcErrorResponse,
   createJsonRpcSuccessResponse,
   JsonRpcErrorCodes,
-} from '../../lib/json-rpc.js';
+} from '@enbox/dwn-clients';
 
 
 export const handleDwnProcessMessage: JsonRpcHandler = async (
@@ -73,6 +75,34 @@ export const handleDwnProcessMessage: JsonRpcHandler = async (
       return { jsonRpcResponse };
     }
 
+    // --- Per-tenant rate limiting (before any DWN processing) ---
+    if (context.tenantRateLimiter) {
+      const result = context.tenantRateLimiter.consume(target);
+      if (result.allowed === false) {
+        const retryAfterSec = Math.ceil(result.retryAfterMs / 1000);
+        const jsonRpcResponse = createJsonRpcErrorResponse(
+          requestId,
+          JsonRpcErrorCodes.TooManyRequests,
+          `${DwnServerErrorCode.RateLimitExceeded}: tenant rate limit exceeded, retry after ${retryAfterSec}s`,
+          { retryAfterSec },
+        );
+        return { jsonRpcResponse };
+      }
+    }
+
+    // --- Per-tenant storage quota enforcement (RecordsWrite only) ---
+    if (
+      context.config &&
+      context.adminStore &&
+      message.descriptor.interface === DwnInterfaceName.Records &&
+      message.descriptor.method === DwnMethodName.Write
+    ) {
+      const quotaResult = await enforceQuota(target, message, context);
+      if (quotaResult !== undefined) {
+        return quotaResult;
+      }
+    }
+
     const reply = await dwn.processMessage(target, message, {
       dataStream,
       subscriptionHandler: subscriptionRequest?.subscriptionHandler,
@@ -107,16 +137,121 @@ export const handleDwnProcessMessage: JsonRpcHandler = async (
       responsePayload.dataStream = recordDataStream;
     }
 
+    // --- Fire-and-forget: post-processing hooks ---
+    const statusCode = reply.status?.code ?? 0;
+    if (context.messageProcessedHooks) {
+      const hookContext = { tenant: target, message, status: reply.status, transport };
+      for (const hook of context.messageProcessedHooks) {
+        try {
+          const result = hook.onMessageProcessed(hookContext);
+          if (result instanceof Promise) {
+            result.catch((err: unknown): void => {
+              log.error('MessageProcessedHook error', err);
+            });
+          }
+        } catch (err) {
+          log.error('MessageProcessedHook error', err);
+        }
+      }
+    }
+
+    // Capture activity event and per-request metrics.
+    const dwnInterface = message.descriptor.interface as string;
+    const dwnMethod = message.descriptor.method as string;
+    const dataSizeBytes = (message.descriptor as { dataSize?: number }).dataSize;
+
+    if (dataSizeBytes !== undefined && dataSizeBytes > 0) {
+      requestDataBytesTotal.inc({ interface: dwnInterface, method: dwnMethod }, dataSizeBytes);
+    }
+
+    if (context.activityLog) {
+      context.activityLog.record({
+        tenant    : target,
+        interface : dwnInterface,
+        method    : dwnMethod,
+        statusCode,
+        transport,
+        dataSizeBytes,
+      });
+    }
+
     return responsePayload;
   } catch (error) {
+    // Log the full error internally but return a generic message to the client
+    // to avoid leaking implementation details (SQL errors, file paths, etc.).
+    log.error('handleDwnProcessMessage error', error);
+
     const jsonRpcResponse = createJsonRpcErrorResponse(
       requestId,
       JsonRpcErrorCodes.InternalError,
-      error.message,
+      'an unexpected error occurred while processing the message',
     );
 
-    // log the unhandled error response
-    log.error('handleDwnProcessMessage error', jsonRpcResponse, dwnRequest, error);
     return { jsonRpcResponse } as HandlerResponse;
   }
 };
+
+// ---------------------------------------------------------------------------
+// Quota enforcement helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Checks whether the tenant has exceeded their message count or storage quota.
+ * Returns a JSON-RPC error response if the quota is exceeded, or `undefined` to proceed.
+ */
+async function enforceQuota(
+  target: string,
+  message: GenericMessage,
+  context: Parameters<JsonRpcHandler>[1],
+): Promise<HandlerResponse | undefined> {
+  const { config, adminStore, registrationStore } = context;
+  const requestId = (message as any).recordId ?? uuidv4();
+
+  // Resolve effective quota: per-tenant override > global config > unlimited.
+  let maxMessages = config!.quotaMaxMessages ?? 0;
+  let maxStorageBytes = config!.quotaMaxStorageBytes ?? 0;
+
+  if (registrationStore) {
+    const tenantQuota = await registrationStore.getQuota(target);
+    if (tenantQuota !== undefined) {
+      maxMessages = tenantQuota.maxMessages ?? maxMessages;
+      maxStorageBytes = tenantQuota.maxStorageBytes ?? maxStorageBytes;
+    }
+  }
+
+  // 0 means unlimited — skip enforcement.
+  if (maxMessages === 0 && maxStorageBytes === 0) {
+    return undefined;
+  }
+
+  // Check message count quota.
+  if (maxMessages > 0) {
+    const currentMessages = await adminStore!.getTenantMessageCount(target);
+    if (currentMessages >= maxMessages) {
+      return {
+        jsonRpcResponse: createJsonRpcErrorResponse(
+          requestId,
+          JsonRpcErrorCodes.InvalidRequest,
+          `${DwnServerErrorCode.TenantMessageQuotaExceeded}: tenant has reached the message limit of ${maxMessages}`,
+        ),
+      };
+    }
+  }
+
+  // Check storage size quota.
+  if (maxStorageBytes > 0) {
+    const dataSize = (message.descriptor as { dataSize?: number }).dataSize ?? 0;
+    const currentStorage = await adminStore!.getTenantStorageSize(target);
+    if (currentStorage + dataSize > maxStorageBytes) {
+      return {
+        jsonRpcResponse: createJsonRpcErrorResponse(
+          requestId,
+          JsonRpcErrorCodes.InvalidRequest,
+          `${DwnServerErrorCode.TenantStorageQuotaExceeded}: tenant would exceed storage limit of ${maxStorageBytes} bytes`,
+        ),
+      };
+    }
+  }
+
+  return undefined;
+}