rpc-express-toolkit 2.3.2 → 3.0.0

package/src/index.js

@@ -1,7 +1,5 @@
-"use strict";
-
-const path = require("path");
-const express = require("express");
+const path = require('path');
+const express = require('express');
 
 /** @typedef {import("express").Router} Router */
 /** @typedef {import("express").Request} Request */
@@ -10,7 +8,11 @@ const express = require("express");
 const NestedError = require('nested-error-stacks');
 const Logger = require('./logger');
 const { MiddlewareManager, builtInMiddlewares } = require('./middleware');
-const { SchemaValidator, commonSchemas, SchemaBuilder } = require('./validation');
+const {
+  SchemaValidator,
+  commonSchemas,
+  SchemaBuilder,
+} = require('./validation');
 const BatchHandler = require('./batch');
 
 /**
@@ -18,9 +20,22 @@ const BatchHandler = require('./batch');
  * @type {Array<string>}
  */
 const defaultProperties = [
-  'stackTraceLimit', 'cause', 'code', 'message', 'stack', 'address',
-  'dest', 'errno', 'info', 'path', 'port', 'syscall', 'opensslErrorStack',
-  'function', 'library', 'reason'
+  'stackTraceLimit',
+  'cause',
+  'code',
+  'message',
+  'stack',
+  'address',
+  'dest',
+  'errno',
+  'info',
+  'path',
+  'port',
+  'syscall',
+  'opensslErrorStack',
+  'function',
+  'library',
+  'reason',
 ];
 
 /**
@@ -30,31 +45,36 @@ const defaultProperties = [
  * @param {Array<string>} properties - Properties to include in serialization.
  * @returns {Object} The serialized error.
  */
-const serializeError = (error, sanitize = false, properties = defaultProperties) => {
+const serializeError = (
+  error,
+  sanitize = false,
+  properties = defaultProperties
+) => {
   if (error === null || error === undefined) return error;
 
   const result = {};
   const includeProperties = sanitize
-      ? properties.filter(prop => !['address', 'path'].includes(prop))
-      : properties;
+    ? properties.filter((prop) => !['address', 'path'].includes(prop))
+    : properties;
 
-  includeProperties.forEach(prop => {
-      if (error?.[prop] !== undefined) {
-          result[prop] = error[prop];
-      }
+  includeProperties.forEach((prop) => {
+    if (error?.[prop] !== undefined) {
+      result[prop] = error[prop];
+    }
   });
 
   if (error instanceof NestedError) {
-      result.type = 'NestedError';
-      if (error.nested) result.nested = serializeError(error.nested, sanitize, properties);
+    result.type = 'NestedError';
+    if (error.nested)
+      result.nested = serializeError(error.nested, sanitize, properties);
   } else if (error instanceof Error) {
-      result.type = 'Error';
+    result.type = 'Error';
   } else if (error instanceof Object) {
-      result.type = 'Object';
-      Object.assign(result, error);
+    result.type = 'Object';
+    Object.assign(result, error);
   } else {
-      result.type = 'Default';
-      result.instance = error;
+    result.type = 'Default';
+    result.instance = error;
   }
 
   return result;
@@ -70,8 +90,8 @@ class RpcEndpoint {
    * @param {string} [url="/vendor/rpc-client"]
    *    The path from which client scripts will be served.
    */
-  static serveScripts(router, url = "/vendor/rpc-client") {
-    router.use(url, express.static(path.join(__dirname, "clients")));
+  static serveScripts(router, url = '/vendor/rpc-client') {
+    router.use(url, express.static(path.join(__dirname, 'clients')));
   }
 
   /** @type {string} */
@@ -101,13 +121,13 @@ class RpcEndpoint {
    * @param {string|Object} [endpointOrOptions="/api"] The endpoint path or options object.
    * @param {Object} [options={}] Options object if first param is string.
    */
-  constructor(router, context, endpointOrOptions = "/api", options = {}) {
+  constructor(router, context, endpointOrOptions = '/api', options = {}) {
     // Handle both signatures: (router, context, "/api", options) and (router, context, options)
     if (typeof endpointOrOptions === 'string') {
       this.#endpoint = endpointOrOptions;
       this.#options = { ...options };
     } else {
-      this.#endpoint = endpointOrOptions.endpoint || "/api";
+      this.#endpoint = endpointOrOptions.endpoint || '/api';
       this.#options = { ...endpointOrOptions };
     }
 
@@ -117,6 +137,15 @@ class RpcEndpoint {
     this.#validator = new SchemaValidator(this.#options.validation || {});
     this.#batchHandler = new BatchHandler(this);
 
+    // Set default options
+    this.#options.safeStringEnabled = this.#options.safeStringEnabled !== false; // Default true
+    this.#options.safeDateEnabled = this.#options.safeDateEnabled !== false; // Default true
+    this.#options.warnOnUnsafeString = this.#options.warnOnUnsafeString !== false; // Default true
+    this.#options.warnOnUnsafeDate = this.#options.warnOnUnsafeDate !== false; // Default true
+
+    // Validate that the router can handle JSON parsing
+    this.#validateJsonMiddleware();
+
     // Setup built-in middleware if configured
     this.#setupBuiltInMiddleware();
 
@@ -147,23 +176,73 @@ class RpcEndpoint {
     }
 
     if (methodWhitelist && Array.isArray(methodWhitelist)) {
-      this.use('beforeCall', builtInMiddlewares.methodWhitelist(methodWhitelist));
+      this.use(
+        'beforeCall',
+        builtInMiddlewares.methodWhitelist(methodWhitelist)
+      );
+    }
+  }
+
+  /**
+   * Validate JSON middleware functionality and Express compatibility
+   * @private
+   */
+  #validateJsonMiddleware() {
+    try {
+      // Check if express.json is available (Express 4.16.0+)
+      if (typeof express.json !== 'function') {
+        throw new Error('express.json() is not available. Please ensure you are using Express 4.16.0 or later, or install body-parser separately.');
+      }
+      
+      // Test JSON middleware creation with default options
+      const jsonMiddleware = express.json({ limit: '10mb' });
+      
+      if (typeof jsonMiddleware !== 'function') {
+        throw new Error('express.json() did not return a valid middleware function');
+      }
+      
+      // Verify middleware has correct signature (req, res, next)
+      if (jsonMiddleware.length !== 3) {
+        throw new Error('JSON middleware has invalid signature - expected (req, res, next)');
+      }
+      
+      this.#logger.debug('JSON middleware validation passed', {
+        expressJsonAvailable: true,
+        middlewareValid: true,
+        endpoint: this.#endpoint
+      });
+      
+    } catch (error) {
+      const errorMsg = `JSON middleware validation failed: ${error.message}\n` +
+        `This router cannot handle JSON-RPC requests properly.\n\n` +
+        `Possible solutions:\n` +
+        `- Update Express: npm install express@latest (requires >=4.16.0)\n` +
+        `- Add JSON parsing middleware manually: router.use(express.json())\n` +
+        `- Install body-parser: npm install body-parser`;
+      
+      this.#logger.error('JSON middleware validation failed', {
+        error: error.message,
+        expressVersion: require('express/package.json')?.version || 'unknown',
+        endpoint: this.#endpoint
+      });
+      
+      throw new Error(errorMsg);
     }
   }
 
   /**
    * Setup Express routes
-   * @param {Router} router 
-   * @param {C} context 
+   * @param {Router} router
+   * @param {C} context
    */
   #setupRoutes(router, context) {
     // Health check endpoint
     if (this.#options.healthCheck !== false) {
       router.get(`${this.#endpoint}/health`, (req, res) => {
-        res.json({ 
-          status: 'ok', 
+        res.json({
+          status: 'ok',
           timestamp: new Date().toISOString(),
-          version: require('../package.json').version
+          version: require('../package.json').version,
         });
       });
     }
@@ -178,47 +257,54 @@ class RpcEndpoint {
     // Main JSON-RPC endpoint
     router.post(this.#endpoint, async (req, res) => {
       const startTime = Date.now();
-      
+
       try {
         // Check if it's a batch request
         if (this.#batchHandler.isBatchRequest(req.body)) {
           this.#logger.info('Batch request received', {
             batchSize: req.body.length,
-            ip: req.ip
+            ip: req.ip,
           });
 
-          const results = await this.#batchHandler.processBatch(req.body, req, res, context);
-          
+          const results = await this.#batchHandler.processBatch(
+            req.body,
+            req,
+            res,
+            context
+          );
+
           // Only send response if there are results (non-notification requests)
           if (results.length > 0) {
             res.json(results);
           } else {
             res.status(204).end(); // No content for all-notification batch
           }
-          
+
           this.#logger.info('Batch request completed', {
             batchSize: req.body.length,
             responseCount: results.length,
-            duration: Date.now() - startTime
+            duration: Date.now() - startTime,
           });
-          
+
           return;
         }
 
         // Single request processing
         await this.#processSingleRequest(req, res, context, startTime);
-        
       } catch (error) {
-        this.#logger.error('Endpoint error', { error: error.message, stack: error.stack });
-        
+        this.#logger.error('Endpoint error', {
+          error: error.message,
+          stack: error.stack,
+        });
+
         res.json({
-          jsonrpc: "2.0",
+          jsonrpc: '2.0',
           id: null,
-          error: { 
-            code: -32603, 
-            message: "Internal error",
-            data: serializeError(error, true)
-          }
+          error: {
+            code: -32603,
+            message: 'Internal error',
+            data: serializeError(error, true),
+          },
         });
       }
     });
@@ -226,10 +312,10 @@ class RpcEndpoint {
 
   /**
    * Process a single JSON-RPC request
-   * @param {Request} req 
-   * @param {Response} res 
-   * @param {C} context 
-   * @param {number} startTime 
+   * @param {Request} req
+   * @param {Response} res
+   * @param {C} context
+   * @param {number} startTime
    */
   async #processSingleRequest(req, res, context, startTime) {
     const { jsonrpc, method, params, id } = req.body || {};
@@ -238,17 +324,23 @@ class RpcEndpoint {
     this.#logger.rpcCall(method, params, id, req);
 
     // Validate JSON-RPC 2.0 request
-    if (jsonrpc !== "2.0") {
+    if (jsonrpc !== '2.0') {
       return this.reply(res, {
         id,
-        error: { code: -32600, message: `Invalid Request: 'jsonrpc' must be '2.0'.` }
+        error: {
+          code: -32600,
+          message: `Invalid Request: 'jsonrpc' must be '2.0'.`,
+        },
       });
     }
 
-    if (typeof method !== "string") {
+    if (typeof method !== 'string') {
       return this.reply(res, {
         id,
-        error: { code: -32600, message: `Invalid Request: 'method' must be a string.` }
+        error: {
+          code: -32600,
+          message: `Invalid Request: 'method' must be a string.`,
+        },
       });
     }
 
@@ -256,53 +348,82 @@ class RpcEndpoint {
     if (!methodConfig) {
       return this.reply(res, {
         id,
-        error: { code: -32601, message: `Method "${method}" not found` }
+        error: { code: -32601, message: `Method "${method}" not found` },
       });
     }
 
-    const handler = typeof methodConfig === 'function' ? methodConfig : methodConfig.handler;
-    const schema = typeof methodConfig === 'object' ? methodConfig.schema : null;
+    const handler =
+      typeof methodConfig === 'function' ? methodConfig : methodConfig.handler;
+    const schema =
+      typeof methodConfig === 'object' ? methodConfig.schema : null;
 
     try {
+      // Check client's safe options from request headers
+      const clientSafeStringEnabled = req.headers['x-rpc-safestring-enabled'] === 'true';
+      const clientSafeDateEnabled = req.headers['x-rpc-safedate-enabled'] === 'true';
+
+      // Create deserialization options based on client's configuration
+      const deserializationOptions = {
+        safeStringEnabled: clientSafeStringEnabled,
+        safeDateEnabled: clientSafeDateEnabled
+      };
+
+      // Deserialize parameters using client's safe options
+      const deserializedParams = params ? this.deserializeBigIntsAndDates(params, deserializationOptions) : params;
+
       // Prepare middleware context
       let middlewareContext = {
         req,
         res,
         method,
-        params,
+        params: deserializedParams,
         context,
         id,
-        startTime
+        startTime,
       };
 
       // Execute beforeCall middleware
-      middlewareContext = await this.#middleware.execute('beforeCall', middlewareContext);
+      middlewareContext = await this.#middleware.execute(
+        'beforeCall',
+        middlewareContext
+      );
 
       // Validate parameters if schema is provided
       if (schema) {
-        middlewareContext = await this.#middleware.execute('beforeValidation', middlewareContext);
-        
-        const validation = this.#validator.validate(middlewareContext.params, schema);
+        middlewareContext = await this.#middleware.execute(
+          'beforeValidation',
+          middlewareContext
+        );
+
+        const validation = this.#validator.validate(
+          middlewareContext.params,
+          schema
+        );
         if (!validation.valid) {
           const error = new Error('Validation failed');
           error.code = -32602;
           error.data = {
-            validationErrors: validation.errors.map(err => ({
+            validationErrors: validation.errors.map((err) => ({
               field: err.instancePath || err.schemaPath,
               message: err.message,
-              value: err.data
-            }))
+              value: err.data,
+            })),
           };
           throw error;
         }
-        
+
         middlewareContext.params = validation.data;
-        middlewareContext = await this.#middleware.execute('afterValidation', middlewareContext);
+        middlewareContext = await this.#middleware.execute(
+          'afterValidation',
+          middlewareContext
+        );
       }
 
       // Invoke the handler
-      const result = await Promise.resolve(handler(req, context, middlewareContext.params));
-      
+      const result = await Promise.resolve(
+        handler(req, context, middlewareContext.params)
+      );
+
       // Execute afterCall middleware
       middlewareContext.result = result;
       await this.#middleware.execute('afterCall', middlewareContext);
@@ -314,7 +435,6 @@ class RpcEndpoint {
       // Convert any BigInt/Date values before JSON-stringifying
       const safeResult = this.serializeBigIntsAndDates(result);
       this.reply(res, { id, result: safeResult });
-
     } catch (err) {
       const duration = Date.now() - startTime;
       this.#logger.rpcError(method, id, duration, err);
@@ -330,20 +450,22 @@ class RpcEndpoint {
           id,
           error: err,
           startTime,
-          duration
+          duration,
         });
       } catch (middlewareError) {
-        this.#logger.error('Error middleware failed', { error: middlewareError.message });
+        this.#logger.error('Error middleware failed', {
+          error: middlewareError.message,
+        });
       }
 
       this.reply(res, {
         id,
-        error: { 
-          code: err.code || -32603, 
-          message: err.message || `Internal error`, 
+        error: {
+          code: err.code || -32603,
+          message: err.message || `Internal error`,
           ...(err.data && { data: err.data }),
-          error: serializeError(err, true) 
-        }
+          error: serializeError(err, true),
+        },
       });
     }
   }
@@ -356,20 +478,25 @@ class RpcEndpoint {
    */
   addMethod(name, handlerOrConfig, schema = null) {
     if (typeof handlerOrConfig === 'function') {
-      this.#methods[name] = schema ? { handler: handlerOrConfig, schema } : handlerOrConfig;
+      this.#methods[name] = schema
+        ? { handler: handlerOrConfig, schema }
+        : handlerOrConfig;
     } else if (typeof handlerOrConfig === 'object' && handlerOrConfig.handler) {
       this.#methods[name] = handlerOrConfig;
     } else {
       throw new Error('Invalid handler configuration');
     }
 
-    this.#logger.debug('Method registered', { method: name, hasSchema: !!schema });
+    this.#logger.debug('Method registered', {
+      method: name,
+      hasSchema: !!schema,
+    });
   }
 
   /**
    * Add middleware for specific hooks
-   * @param {string} hook 
-   * @param {Function} middleware 
+   * @param {string} hook
+   * @param {Function} middleware
    */
   use(hook, middleware) {
     this.#middleware.use(hook, middleware);
@@ -377,7 +504,7 @@ class RpcEndpoint {
 
   /**
    * Remove method
-   * @param {string} name 
+   * @param {string} name
    */
   removeMethod(name) {
     delete this.#methods[name];
@@ -386,7 +513,7 @@ class RpcEndpoint {
 
   /**
    * Get method configuration
-   * @param {string} name 
+   * @param {string} name
    * @returns {any}
    */
   getMethod(name) {
@@ -448,11 +575,11 @@ class RpcEndpoint {
       middleware: {
         beforeCall: this.#middleware.getMiddlewares('beforeCall').length,
         afterCall: this.#middleware.getMiddlewares('afterCall').length,
-        onError: this.#middleware.getMiddlewares('onError').length
+        onError: this.#middleware.getMiddlewares('onError').length,
       },
       uptime: process.uptime(),
       memory: process.memoryUsage(),
-      timestamp: new Date().toISOString()
+      timestamp: new Date().toISOString(),
     };
   }
 
@@ -466,7 +593,7 @@ class RpcEndpoint {
    * }} responsePayload The JSON-RPC response fields.
    */
   reply(res, { id, result, error }) {
-    const response = { jsonrpc: "2.0", id: id === undefined ? null : id };
+    const response = { jsonrpc: '2.0', id: id === undefined ? null : id };
 
     if (error) {
       response.error = error;
@@ -474,6 +601,10 @@ class RpcEndpoint {
       response.result = result;
     }
 
+    // Add safe options headers so client knows how to deserialize
+    res.setHeader('X-RPC-SafeString-Enabled', this.#options.safeStringEnabled ? 'true' : 'false');
+    res.setHeader('X-RPC-SafeDate-Enabled', this.#options.safeDateEnabled ? 'true' : 'false');
+
     res.json(response);
   }
 
@@ -486,20 +617,45 @@ class RpcEndpoint {
    * @returns {any} A version of `value` safe for JSON serialization.
    */
   serializeBigIntsAndDates(value) {
-    if (typeof value === "bigint") {
-      // Convert BigInt to string
-      return value.toString();
-    } else if (Array.isArray(value)) {
-      // Recurse into arrays
-      return value.map((v) => this.serializeBigIntsAndDates(v));
+    return this.#serializeValue(value, false);
+  }
+
+  /**
+   * Internal serialization method with BigInt and Date warning tracking
+   * @private
+   */
+  #serializeValue(value, hasBigInt = false, hasDate = false) {
+    if (typeof value === 'bigint') {
+      // Warn if safeStringEnabled is disabled and we have BigInt
+      if (!this.#options.safeStringEnabled && !hasBigInt && this.#options.warnOnUnsafeString) {
+        this.#logger.warn('BigInt detected in serialization. Consider enabling safeStringEnabled option to avoid potential string/BigInt confusion.');
+      }
+      // Convert BigInt to string with 'n' suffix for proper deserialization
+      return value.toString() + 'n';
     } else if (value instanceof Date) {
-      // Convert Date to ISO string (UTC)
-      return value.toISOString();
-    } else if (value && typeof value === "object") {
-      // Recurse into plain objects
+      // Warn if safeDateEnabled is disabled and we have Date
+      if (!this.#options.safeDateEnabled && !hasDate && this.#options.warnOnUnsafeDate) {
+        this.#logger.warn('Date detected in serialization. Consider enabling safeDateEnabled option to avoid potential string/Date confusion.');
+      }
+      // Convert Date to ISO string with D: prefix if safeDateEnabled
+      const isoString = value.toISOString();
+      return this.#options.safeDateEnabled ? `D:${isoString}` : isoString;
+    } else if (typeof value === 'string') {
+      // Add S: prefix if safeStringEnabled is true
+      if (this.#options.safeStringEnabled) {
+        return 'S:' + value;
+      }
+      return value;
+    } else if (Array.isArray(value)) {
+      // Recurse into arrays - don't pass hasBigInt/hasDate to children
+      // Each element should be checked independently for warnings
+      return value.map((v) => this.#serializeValue(v, false, false));
+    } else if (value && typeof value === 'object') {
+      // Recurse into plain objects - don't pass hasBigInt/hasDate to children
+      // Each property should be checked independently for warnings
       const result = {};
       for (const [key, val] of Object.entries(value)) {
-        result[key] = this.serializeBigIntsAndDates(val);
+        result[key] = this.#serializeValue(val, false, false);
       }
       return result;
     }
@@ -508,6 +664,32 @@ class RpcEndpoint {
     return value;
   }
 
+  /**
+   * Check if an object has BigInt values deep inside
+   * @private
+   */
+  #hasDeepBigInt(obj) {
+    if (typeof obj === 'bigint') return true;
+    if (Array.isArray(obj)) return obj.some(item => this.#hasDeepBigInt(item));
+    if (obj && typeof obj === 'object') {
+      return Object.values(obj).some(val => this.#hasDeepBigInt(val));
+    }
+    return false;
+  }
+
+  /**
+   * Check if an object has Date values deep inside
+   * @private
+   */
+  #hasDeepDate(obj) {
+    if (obj instanceof Date) return true;
+    if (Array.isArray(obj)) return obj.some(item => this.#hasDeepDate(item));
+    if (obj && typeof obj === 'object') {
+      return Object.values(obj).some(val => this.#hasDeepDate(val));
+    }
+    return false;
+  }
+
   /**
    * Recursively convert stringified BigInts back to BigInt,
    * and ISO 8601 date strings back to Date objects.
@@ -517,25 +699,47 @@ class RpcEndpoint {
    * the original types.
    *
    * @param {any} value The value to deserialize.
+   * @param {Object} [options] Custom deserialization options (uses server options if not provided).
+   * @param {boolean} [options.safeStringEnabled] Whether to expect S: prefixed strings.
+   * @param {boolean} [options.safeDateEnabled] Whether to expect D: prefixed dates.
    * @returns {any} The re-hydrated value.
    */
-  deserializeBigIntsAndDates(value) {
+  deserializeBigIntsAndDates(value, options = null) {
+    // Use provided options or fall back to server options
+    const safeStringEnabled = options ? options.safeStringEnabled : this.#options.safeStringEnabled;
+    const safeDateEnabled = options ? options.safeDateEnabled : this.#options.safeDateEnabled;
+
     // More comprehensive ISO date regex that handles:
     // - UTC: 2023-01-01T12:00:00.000Z
-    // - With timezone: 2023-01-01T12:00:00.000+01:00  
+    // - With timezone: 2023-01-01T12:00:00.000+01:00
     // - Without timezone: 2023-01-01T12:00:00.000 (treated as local)
-    const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;
-
-    // 1. Check if it's a string that might be a BigInt or a Date
-    if (typeof value === "string") {
-      // BigInt check: matches digits (including negative), optionally ending in "n"
-      // e.g., "42n", "42", "-42n", "-42"
-      if (/^-?\d+n?$/.test(value)) {
-        return BigInt(value.replace(/n$/, ""));
+    const ISO_DATE_REGEX =
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/;
+
+    // 1. Check if it's a string that might be a BigInt, Date, or safe string
+    if (typeof value === 'string') {
+      // Safe string check: if safeStringEnabled and starts with S:
+      if (safeStringEnabled && value.startsWith('S:')) {
+        return value.substring(2); // Remove 'S:' prefix
+      }
+
+      // Safe date check: if safeDateEnabled and starts with D:
+      if (safeDateEnabled && value.startsWith('D:')) {
+        const isoString = value.substring(2); // Remove 'D:' prefix
+        const date = new Date(isoString);
+        // Double-check that we got a valid date
+        if (!isNaN(date.getTime())) {
+          return date;
+        }
+      }
+
+      // BigInt check: matches digits (including negative), ending in "n"
+      if (/^-?\d+n$/.test(value)) {
+        return BigInt(value.slice(0, -1)); // Remove 'n' and convert
       }
 
-      // Date check: matches an ISO 8601 string
-      if (ISO_DATE_REGEX.test(value)) {
+      // Date check: matches an ISO 8601 string (only if safeDateEnabled is false)
+      if (!safeDateEnabled && ISO_DATE_REGEX.test(value)) {
         const date = new Date(value);
         // Double-check that we got a valid date
         if (!isNaN(date.getTime())) {
@@ -546,15 +750,15 @@ class RpcEndpoint {
 
     // 2. If it's an array, handle each element
     if (Array.isArray(value)) {
-      return value.map((v) => this.deserializeBigIntsAndDates(v));
+      return value.map((v) => this.deserializeBigIntsAndDates(v, options));
     }
 
     // 3. If it's a plain object, recurse into each property
-    if (value && typeof value === "object") {
+    if (value && typeof value === 'object') {
       return Object.fromEntries(
         Object.entries(value).map(([key, val]) => [
           key,
-          this.deserializeBigIntsAndDates(val)
+          this.deserializeBigIntsAndDates(val, options),
         ])
       );
     }