rpc-express-toolkit 3.0.2 → 4.0.1

package/src/index.d.ts

@@ -96,17 +96,16 @@ interface RpcEndpointOptions {
   prefix?: string;
   maxBodySize?: string;
   timeout?: number;
-  cors?: boolean | CorsOptions;
+  cors?: boolean | CorsConfig;
   auth?: AuthConfig;
   validation?: ValidationConfig;
-  safeStringEnabled?: boolean;
-  safeDateEnabled?: boolean;
+  safeEnabled?: boolean;
   crossConfigurationEnabled?: boolean;
   enableSchema?: boolean;
   rateLimit?: RateLimitConfig;
   logging?: LoggingConfig;
-  warnOnUnsafeString?: boolean;
-  warnOnUnsafeDate?: boolean;
+  warnOnUnsafe?: boolean;
+  strictMode?: boolean;
   autoJsonMiddleware?: boolean;
   jsonOptions?: {
     limit?: string;
@@ -114,24 +113,26 @@ interface RpcEndpointOptions {
     type?: string | string[] | ((req: any) => boolean);
     verify?: (req: any, res: any, buf: Buffer, encoding: string) => void;
   };
+  // Additional options supported by implementation
+  methodWhitelist?: string[];
+  timing?: boolean;
+  metrics?: boolean;
+  healthCheck?: boolean;
 }
 
 /**
  * RPC client configuration options
  */
 interface RpcClientOptions {
-  safeStringEnabled?: boolean;
-  safeDateEnabled?: boolean;
-  warnOnUnsafeString?: boolean;
-  warnOnUnsafeDate?: boolean;
+  safeEnabled?: boolean;
+  warnOnUnsafe?: boolean;
 }
 
 /**
  * Deserialization options for safe prefixes
  */
 interface DeserializationOptions {
-  safeStringEnabled?: boolean;
-  safeDateEnabled?: boolean;
+  safeEnabled?: boolean;
 }
 
 /**
@@ -236,12 +237,12 @@ declare class RpcClient {
   /**
    * Make a JSON-RPC call to the server.
    */
-  call(
+  call<T = any>(
     method: string,
     params?: any,
     id?: string | number | null,
     overrideHeaders?: Record<string, string>
-  ): Promise<any>;
+  ): Promise<T>;
 
   /**
    * Make a JSON-RPC notification (no response expected).
@@ -255,7 +256,7 @@ declare class RpcClient {
   /**
    * Make a batch JSON-RPC call.
    */
-  batch(
+  batch<T = any>(
     requests: Array<{
       method: string;
       params?: any;
@@ -263,7 +264,7 @@ declare class RpcClient {
       notification?: boolean;
     }>,
     overrideHeaders?: Record<string, string>
-  ): Promise<any[]>;
+  ): Promise<T[]>;
 
   /**
    * Recursively serialize BigInt and Date to JSON-safe string formats.

package/src/index.js

@@ -1,11 +1,13 @@
 const path = require('path');
 const express = require('express');
+const expressPkg = require('express/package.json');
+const NestedError = require('nested-error-stacks');
+const pkg = require('../package.json');
 
 /** @typedef {import("express").Router} Router */
 /** @typedef {import("express").Request} Request */
 /** @typedef {import("express").Response} Response */
 
-const NestedError = require('nested-error-stacks');
 const Logger = require('./logger');
 const { MiddlewareManager, builtInMiddlewares } = require('./middleware');
 const {
@@ -138,10 +140,9 @@ class RpcEndpoint {
     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
+    this.#options.safeEnabled = this.#options.safeEnabled === true; // Default false
+    this.#options.warnOnUnsafe = this.#options.warnOnUnsafe !== false; // Default true
+    this.#options.strictMode = this.#options.strictMode !== false; // Default true
 
     // Validate that the router can handle JSON parsing
     this.#validateJsonMiddleware();
@@ -191,41 +192,47 @@ class RpcEndpoint {
     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.');
+        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');
+        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)');
+        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
+        endpoint: this.#endpoint,
       });
-      
     } catch (error) {
-      const errorMsg = `JSON middleware validation failed: ${error.message}\n` +
+      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
+        expressVersion: expressPkg?.version || 'unknown',
+        endpoint: this.#endpoint,
       });
-      
+
       throw new Error(errorMsg);
     }
   }
@@ -242,7 +249,7 @@ class RpcEndpoint {
         res.json({
           status: 'ok',
           timestamp: new Date().toISOString(),
-          version: require('../package.json').version,
+          version: pkg.version,
         });
       });
     }
@@ -275,6 +282,11 @@ class RpcEndpoint {
 
           // Only send response if there are results (non-notification requests)
           if (results.length > 0) {
+            // Align batch responses with single-call header negotiation
+            res.setHeader(
+              'X-RPC-Safe-Enabled',
+              this.#options.safeEnabled ? 'true' : 'false'
+            );
             res.json(results);
           } else {
             res.status(204).end(); // No content for all-notification batch
@@ -359,17 +371,41 @@ class RpcEndpoint {
 
     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';
+      const clientSafeHeader = req.headers['x-rpc-safe-enabled'];
+
+      // Strict mode: se server ha safe enabled ma client non invia header → JSON-RPC ERROR
+      if (
+        this.#options.strictMode &&
+        this.#options.safeEnabled &&
+        !clientSafeHeader
+      ) {
+        return this.reply(res, {
+          id,
+          error: {
+            code: -32600, // Invalid Request
+            message:
+              'RPC Compatibility Error: Server requires safe serialization header but client did not provide it.',
+            data: {
+              serverSafeEnabled: this.#options.safeEnabled,
+              requiredHeader: 'X-RPC-Safe-Enabled',
+              strictMode: true,
+              solution:
+                'Update client to rpc-express-toolkit v4+ or disable server strict mode',
+            },
+          },
+        });
+      }
 
-      // Create deserialization options based on client's configuration
+      // Use client's safe options for parameter deserialization
+      const clientSafeEnabled = clientSafeHeader === 'true';
       const deserializationOptions = {
-        safeStringEnabled: clientSafeStringEnabled,
-        safeDateEnabled: clientSafeDateEnabled
+        safeEnabled: clientSafeEnabled,
       };
 
       // Deserialize parameters using client's safe options
-      const deserializedParams = params ? this.deserializeBigIntsAndDates(params, deserializationOptions) : params;
+      const deserializedParams = params
+        ? this.deserializeBigIntsAndDates(params, deserializationOptions)
+        : params;
 
       // Prepare middleware context
       let middlewareContext = {
@@ -468,6 +504,8 @@ class RpcEndpoint {
         },
       });
     }
+    // Ensure explicit return for consistent-return rule
+    return null;
   }
 
   /**
@@ -602,8 +640,11 @@ class RpcEndpoint {
     }
 
     // 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');
+    // Send safe options headers to client
+    res.setHeader(
+      'X-RPC-Safe-Enabled',
+      this.#options.safeEnabled ? 'true' : 'false'
+    );
 
     res.json(response);
   }
@@ -626,31 +667,47 @@ class RpcEndpoint {
    */
   #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.');
+      // Warn if safeEnabled is disabled and we have BigInt
+      if (
+        !this.#options.safeEnabled &&
+        !hasBigInt &&
+        this.#options.warnOnUnsafe
+      ) {
+        this.#logger.warn(
+          'BigInt detected in serialization. Consider enabling safeEnabled 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) {
-      // 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.');
+      return `${value.toString()}n`;
+    }
+    if (value instanceof Date) {
+      // Warn if safeEnabled is disabled and we have Date
+      if (
+        !this.#options.safeEnabled &&
+        !hasDate &&
+        this.#options.warnOnUnsafe
+      ) {
+        this.#logger.warn(
+          'Date detected in serialization. Consider enabling safeEnabled option to avoid potential string/Date confusion.'
+        );
       }
-      // Convert Date to ISO string with D: prefix if safeDateEnabled
+      // Convert Date to ISO string with D: prefix if safeEnabled
       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 this.#options.safeEnabled ? `D:${isoString}` : isoString;
+    }
+    if (typeof value === 'string') {
+      // Add S: prefix if safeEnabled is true
+      if (this.#options.safeEnabled) {
+        return `S:${value}`;
       }
       return value;
-    } else if (Array.isArray(value)) {
+    }
+    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') {
+    }
+    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 = {};
@@ -670,9 +727,10 @@ class RpcEndpoint {
    */
   #hasDeepBigInt(obj) {
     if (typeof obj === 'bigint') return true;
-    if (Array.isArray(obj)) return obj.some(item => this.#hasDeepBigInt(item));
+    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 Object.values(obj).some((val) => this.#hasDeepBigInt(val));
     }
     return false;
   }
@@ -683,9 +741,9 @@ class RpcEndpoint {
    */
   #hasDeepDate(obj) {
     if (obj instanceof Date) return true;
-    if (Array.isArray(obj)) return obj.some(item => this.#hasDeepDate(item));
+    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 Object.values(obj).some((val) => this.#hasDeepDate(val));
     }
     return false;
   }
@@ -700,14 +758,14 @@ class RpcEndpoint {
    *
    * @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.
+   * @param {boolean} [options.safeEnabled] Whether to expect safe prefixes for strings and dates.
    * @returns {any} The re-hydrated 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;
+    const safeEnabled = options
+      ? options.safeEnabled
+      : this.#options.safeEnabled;
 
     // More comprehensive ISO date regex that handles:
     // - UTC: 2023-01-01T12:00:00.000Z
@@ -718,17 +776,17 @@ class RpcEndpoint {
 
     // 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:')) {
+      // Safe string check: if safeEnabled and starts with S:
+      if (safeEnabled && value.startsWith('S:')) {
         return value.substring(2); // Remove 'S:' prefix
       }
 
-      // Safe date check: if safeDateEnabled and starts with D:
-      if (safeDateEnabled && value.startsWith('D:')) {
+      // Safe date check: if safeEnabled and starts with D:
+      if (safeEnabled && 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())) {
+        if (!Number.isNaN(date.getTime())) {
           return date;
         }
       }
@@ -738,11 +796,11 @@ class RpcEndpoint {
         return BigInt(value.slice(0, -1)); // Remove 'n' and convert
       }
 
-      // Date check: matches an ISO 8601 string (only if safeDateEnabled is false)
-      if (!safeDateEnabled && ISO_DATE_REGEX.test(value)) {
+      // Date check: matches an ISO 8601 string (only if safeEnabled is false)
+      if (!safeEnabled && ISO_DATE_REGEX.test(value)) {
         const date = new Date(value);
         // Double-check that we got a valid date
-        if (!isNaN(date.getTime())) {
+        if (!Number.isNaN(date.getTime())) {
           return date;
         }
       }

package/src/logger.js

@@ -47,6 +47,24 @@ class Logger {
     };
   }
 
+  /**
+   * Safely stringify objects that may contain BigInt/Date
+   * @param {any} obj
+   * @returns {string}
+   */
+  safeStringify(obj) {
+    try {
+      return JSON.stringify(obj, (key, value) => {
+        if (typeof value === 'bigint') return `${value.toString()}n`;
+        if (value instanceof Date) return value.toISOString();
+        return value;
+      });
+    } catch (e) {
+      // Fallback: best-effort toString
+      return String(obj);
+    }
+  }
+
   /**
    * Generic log method
    * @param {string} level
@@ -63,7 +81,7 @@ class Logger {
     } else {
       const logMessage = `${this.prefix} ${logData.timestamp} [${logData.level}] ${message}`;
       const metaStr =
-        Object.keys(meta).length > 0 ? ` | ${JSON.stringify(meta)}` : '';
+        Object.keys(meta).length > 0 ? ` | ${this.safeStringify(meta)}` : '';
       console[level === 'debug' || level === 'trace' ? 'log' : level](
         `${logMessage}${metaStr}`
       );
@@ -120,7 +138,7 @@ class Logger {
       id,
       duration: `${duration}ms`,
       resultType: typeof result,
-      resultSize: result ? JSON.stringify(result).length : 0,
+      resultSize: result ? this.safeStringify(result).length : 0,
     });
   }
 
@@ -160,21 +178,23 @@ class Logger {
     ];
     const sanitized = Array.isArray(params) ? [...params] : { ...params };
 
-    const sanitizeObj = (obj) => {
-      if (typeof obj !== 'object' || obj === null) return obj;
-
-      for (const [key, value] of Object.entries(obj)) {
-        if (
-          sensitiveKeys.some((sensitive) =>
-            key.toLowerCase().includes(sensitive)
-          )
-        ) {
-          obj[key] = '[REDACTED]';
-        } else if (typeof value === 'object') {
-          sanitizeObj(value);
+    const sanitizeObj = (input) => {
+      if (typeof input !== 'object' || input === null) return input;
+
+      const output = Array.isArray(input) ? [] : {};
+      for (const [key, value] of Object.entries(input)) {
+        const isSensitive = sensitiveKeys.some((sensitive) =>
+          key.toLowerCase().includes(sensitive)
+        );
+        if (isSensitive) {
+          output[key] = '[REDACTED]';
+        } else if (typeof value === 'object' && value !== null) {
+          output[key] = sanitizeObj(value);
+        } else {
+          output[key] = value;
         }
       }
-      return obj;
+      return output;
     };
 
     return sanitizeObj(sanitized);

package/src/middleware.js

@@ -42,32 +42,47 @@ class MiddlewareManager {
    */
   async execute(hook, context) {
     const middlewares = this.middlewares[hook] || [];
-    let result = context;
-
-    for (const middleware of middlewares) {
-      try {
-        const middlewareResult = await middleware(result);
-
-        // If middleware returns an object, merge it with context
-        if (middlewareResult && typeof middlewareResult === 'object') {
-          result = { ...result, ...middlewareResult };
-        }
-
-        // If middleware explicitly returns false, stop execution
-        if (middlewareResult === false) {
-          throw new Error('Middleware execution stopped');
-        }
-      } catch (error) {
-        // For error hooks, continue even if middleware fails
-        if (hook === 'onError') {
-          console.error('Error middleware failed:', error);
-          continue;
-        }
-        throw error;
-      }
+    const isErrorHook = hook === 'onError';
+
+    const finalResult = await middlewares.reduce(
+      (promise, middleware) =>
+        promise.then(async (acc) => {
+          // If a previous middleware requested stop, propagate without executing others
+          if (acc && acc.__middlewareStopped) {
+            return acc;
+          }
+          try {
+            const middlewareResult = await middleware(acc);
+
+            if (middlewareResult === false) {
+              // Mark chain as stopped
+              return { ...acc, __middlewareStopped: true };
+            }
+
+            // If middleware returns an object, merge it with context
+            if (middlewareResult && typeof middlewareResult === 'object') {
+              return { ...acc, ...middlewareResult };
+            }
+
+            return acc;
+          } catch (error) {
+            if (isErrorHook) {
+              console.error('Error middleware failed:', error);
+              return acc;
+            }
+            throw error;
+          }
+        }),
+      Promise.resolve(context)
+    );
+
+    // Do not expose internal marker
+    if (finalResult && finalResult.__middlewareStopped) {
+      const rest = { ...finalResult };
+      delete rest.__middlewareStopped;
+      return rest;
     }
-
-    return result;
+    return finalResult;
   }
 
   /**

package/src/validation.js

@@ -1,3 +1,4 @@
+/* eslint max-classes-per-file: off */
 const Ajv = require('ajv');
 const addFormats = require('ajv-formats');