rpc-express-toolkit 4.4.2 → 4.5.1

package/README.md

@@ -201,7 +201,7 @@ Safe type disambiguation is disabled by default for maximum JSON-RPC 2.0 compati
 
 ## Authentication And Method Restrictions
 
-Authentication is supported through the built-in `auth` middleware. The `auth` option is a function that receives the Express request. Returning a truthy value allows the RPC call; returning a falsy value rejects it with JSON-RPC error `-32001` and message `Authentication required`. Throwing also rejects the call and returns a JSON-RPC error based on the thrown error.
+Authentication is supported through the built-in `auth` middleware. The `auth` option is a function that receives the Express request. Returning a truthy value allows the RPC call; a truthy non-boolean value is available to handlers as the optional fourth argument's `authenticatedUser`. Returning a falsy value rejects the call with JSON-RPC error `-32001` and message `Authentication required`. Throwing also rejects the call and returns a JSON-RPC error based on the thrown error.
 
 ```js
 const rpc = new RpcEndpoint(app, context, {
@@ -211,7 +211,9 @@ const rpc = new RpcEndpoint(app, context, {
   },
 });
 
-rpc.addMethod('ping', () => 'pong');
+rpc.addMethod('whoami', (_req, _context, _params, callContext) =>
+  callContext.authenticatedUser
+);
 ```
 
 For simple method-level restriction, use `methodWhitelist`:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "rpc-express-toolkit",
-    "version":  "4.4.2",
+    "version":  "4.5.1",
     "description":  "JSON-RPC 2.0 toolkit for Express.js with simplified APIs, structured logging, middleware, schema validation, batch support, and optional Safe Mode.",
     "main":  "src/index.js",
     "types":  "src/index.d.ts",

package/src/batch.js

@@ -52,6 +52,26 @@ class BatchHandler {
       };
     }
 
+    if (!this.endpoint.options.enableBatch) {
+      return {
+        valid: false,
+        error: {
+          code: -32600,
+          message: 'Invalid Request: Batch requests are not enabled',
+        },
+      };
+    }
+
+    if (batch.length > this.endpoint.options.maxBatchSize) {
+      return {
+        valid: false,
+        error: {
+          code: -32600,
+          message: `Invalid Request: Batch size exceeds maximum of ${this.endpoint.options.maxBatchSize}`,
+        },
+      };
+    }
+
     return { valid: true };
   }
 
@@ -76,7 +96,13 @@ class BatchHandler {
     // Process all requests in parallel
     const promises = batch.map(async (request, index) => {
       try {
-        return await this.processSingleRequest(request, req, context, index);
+        return await this.processSingleRequest(
+          request,
+          req,
+          res,
+          context,
+          index
+        );
       } catch (error) {
         const errorData = this.serializeErrorData(error, index);
         return {
@@ -101,11 +127,12 @@ class BatchHandler {
    * Process a single request within a batch
    * @param {Object} request
    * @param {Object} req
+   * @param {Object} res
    * @param {any} context
    * @param {number} batchIndex
    * @returns {Promise<Object|null>}
    */
-  async processSingleRequest(request, req, context, batchIndex) {
+  async processSingleRequest(request, req, res, context, batchIndex) {
     const { method, params, id } = request || {};
     const envelope = validateEnvelope(request);
 
@@ -183,7 +210,7 @@ class BatchHandler {
     // Initialize middleware context
     let middlewareContext = {
       req,
-      res: null, // No response object for batch items
+      res,
       method,
       params: deserializedParams,
       context,
@@ -236,14 +263,23 @@ class BatchHandler {
       }
 
       // Execute the handler
-      const result = await Promise.resolve(
-        handler(req, context, middlewareContext.params)
+      let result = await Promise.resolve(
+        handler(
+          req,
+          middlewareContext.context,
+          middlewareContext.params,
+          middlewareContext
+        )
       );
 
       // Execute after middleware
       if (this.endpoint.middleware) {
         middlewareContext.result = result;
-        await this.endpoint.middleware.execute('afterCall', middlewareContext);
+        middlewareContext = await this.endpoint.middleware.execute(
+          'afterCall',
+          middlewareContext
+        );
+        result = middlewareContext.result;
       }
 
       // For notifications, return null (will be filtered out)

package/src/index.d.ts

@@ -93,7 +93,8 @@ declare namespace RpcEndpoint {
   export type JSONRPCHandler<C> = (
     req: Request,
     context: C,
-    params: any
+    params: any,
+    callContext?: MiddlewareContext<C>
   ) => any | Promise<any>;
 
   /** Method configuration object. */
@@ -153,10 +154,19 @@ declare namespace RpcEndpoint {
     message?: string;
     standardHeaders?: boolean;
     legacyHeaders?: boolean;
+    store?: RateLimitStore;
   }
 
-  /** Authentication verifier. Return a truthy value to allow the call. */
-  export type AuthConfig = (req: Request) => boolean | Promise<boolean>;
+  /** Authentication verifier. A truthy non-boolean result becomes authenticatedUser. */
+  export type AuthConfig = (req: Request) => unknown | Promise<unknown>;
+
+  export interface RateLimitStore {
+    increment(
+      key: string,
+      windowMs: number,
+      now: number
+    ): number | Promise<number>;
+  }
 
   /** Schema validation configuration. */
   export interface ValidationConfig {
@@ -198,6 +208,8 @@ declare namespace RpcEndpoint {
     healthCheck?: boolean;
     enableIntrospection?: boolean;
     introspectionPrefix?: string;
+    enableBatch?: boolean;
+    maxBatchSize?: number;
   }
 
   /** RPC client configuration options. */
@@ -227,6 +239,7 @@ declare namespace RpcEndpoint {
     batchIndex?: number;
     isNotification?: boolean;
     startTime?: number;
+    authenticatedUser?: unknown;
     [key: string]: any;
   }
 
@@ -258,6 +271,10 @@ declare namespace RpcEndpoint {
     new (...args: any[]): MiddlewareManager;
   };
 
+  export const MemoryRateLimitStore: {
+    new (): RateLimitStore;
+  };
+
   export const builtInMiddlewares: any;
 
   export interface SchemaValidationResult<T = any> {

package/src/index.js

@@ -20,7 +20,11 @@ const DEFAULT_MAX_SERIALIZATION_DEPTH = 100;
 /** @typedef {import("express").Response} Response */
 
 const Logger = require('./logger');
-const { MiddlewareManager, builtInMiddlewares } = require('./middleware');
+const {
+  MiddlewareManager,
+  MemoryRateLimitStore,
+  builtInMiddlewares,
+} = require('./middleware');
 const {
   SchemaValidator,
   commonSchemas,
@@ -165,6 +169,12 @@ class RpcEndpoint {
       this.#options.enableIntrospection === true; // Default false
     this.#options.introspectionPrefix =
       this.#options.introspectionPrefix || '__rpc'; // Default __rpc
+    this.#options.enableBatch = this.#options.enableBatch !== false;
+    this.#options.maxBatchSize =
+      Number.isInteger(this.#options.maxBatchSize) &&
+      this.#options.maxBatchSize > 0
+        ? this.#options.maxBatchSize
+        : 100;
 
     this.#introspectionPrefix = this.#options.introspectionPrefix;
 
@@ -334,7 +344,7 @@ class RpcEndpoint {
       `${this.#introspectionPrefix}.capabilities`,
       async (_req, _context, _params) => ({
         safeMode: this.#options.safeEnabled,
-        batch: true,
+        batch: this.#options.enableBatch,
         introspection: true,
         introspectionPrefix: this.#introspectionPrefix,
         validation: !!this.#options.validation,
@@ -431,6 +441,14 @@ class RpcEndpoint {
       });
     }
 
+    if (this.#options.cors) {
+      const corsMiddleware = builtInMiddlewares.cors(this.#options.cors);
+      router.options(this.#endpoint, async (req, res) => {
+        await corsMiddleware({ req, res });
+        res.status(204).end();
+      });
+    }
+
     // Main JSON-RPC endpoint
     router.post(this.#endpoint, async (req, res) => {
       const startTime = Date.now();
@@ -629,13 +647,22 @@ class RpcEndpoint {
       }
 
       // Invoke the handler
-      const result = await Promise.resolve(
-        handler(req, context, middlewareContext.params)
+      let result = await Promise.resolve(
+        handler(
+          req,
+          middlewareContext.context,
+          middlewareContext.params,
+          middlewareContext
+        )
       );
 
       // Execute afterCall middleware
       middlewareContext.result = result;
-      await this.#middleware.execute('afterCall', middlewareContext);
+      middlewareContext = await this.#middleware.execute(
+        'afterCall',
+        middlewareContext
+      );
+      result = middlewareContext.result;
 
       // Log success
       const duration = Date.now() - startTime;
@@ -1153,6 +1180,7 @@ module.exports.RpcHttpError = RpcHttpError;
 module.exports.RpcSafeClient = RpcSafeClient;
 module.exports.Logger = Logger;
 module.exports.MiddlewareManager = MiddlewareManager;
+module.exports.MemoryRateLimitStore = MemoryRateLimitStore;
 module.exports.builtInMiddlewares = builtInMiddlewares;
 module.exports.SchemaValidator = SchemaValidator;
 module.exports.commonSchemas = commonSchemas;

package/src/memory-rate-limit-store.js

@@ -0,0 +1,28 @@
+/**
+ * In-process sliding-window store used by the rate limiter by default.
+ * Multi-process and multi-instance deployments should provide a shared store
+ * implementing the same increment() contract.
+ */
+class MemoryRateLimitStore {
+  constructor() {
+    this.requests = new Map();
+  }
+
+  /**
+   * Record a hit and return the number of hits still inside the window.
+   * @param {string} key
+   * @param {number} windowMs
+   * @param {number} [now]
+   * @returns {Promise<number>}
+   */
+  async increment(key, windowMs, now = Date.now()) {
+    const validRequests = (this.requests.get(key) || []).filter(
+      (time) => now - time < windowMs
+    );
+    validRequests.push(now);
+    this.requests.set(key, validRequests);
+    return validRequests.length;
+  }
+}
+
+module.exports = MemoryRateLimitStore;

package/src/middleware.js

@@ -3,6 +3,8 @@
  * @description Handles middleware execution for JSON-RPC requests including built-in middleware
  */
 
+const MemoryRateLimitStore = require('./memory-rate-limit-store');
+
 /**
  * Middleware manager for handling RPC middleware
  */
@@ -138,33 +140,27 @@ const builtInMiddlewares = {
     const max = options.max || 100; // 100 requests per window
     const message = options.message || 'Too many requests';
 
-    const requests = new Map();
+    const store = options.store || new MemoryRateLimitStore();
+
+    if (!store || typeof store.increment !== 'function') {
+      throw new TypeError(
+        'Rate limit store must implement increment(key, windowMs, now)'
+      );
+    }
 
     return async (context) => {
       const { req } = context;
       const key = req.ip || req.connection?.remoteAddress || 'unknown';
       const now = Date.now();
 
-      // Clean old entries
-      if (requests.has(key)) {
-        const userRequests = requests.get(key);
-        const validRequests = userRequests.filter(
-          (time) => now - time < windowMs
-        );
-        requests.set(key, validRequests);
-      }
+      const requestCount = await store.increment(key, windowMs, now);
 
-      const userRequests = requests.get(key) || [];
-
-      if (userRequests.length >= max) {
+      if (requestCount > max) {
         const error = new Error(message);
         error.code = -32000; // Custom JSON-RPC error code
         throw error;
       }
 
-      userRequests.push(now);
-      requests.set(key, userRequests);
-
       return context;
     };
   },
@@ -177,15 +173,19 @@ const builtInMiddlewares = {
   auth(authFunction) {
     return async (context) => {
       const { req } = context;
-      const isAuthenticated = await authFunction(req);
+      const authenticatedUser = await authFunction(req);
 
-      if (!isAuthenticated) {
+      if (!authenticatedUser) {
         const error = new Error('Authentication required');
         error.code = -32001;
         throw error;
       }
 
-      return context;
+      return {
+        ...context,
+        authenticatedUser:
+          authenticatedUser === true ? undefined : authenticatedUser,
+      };
     };
   },
 
@@ -195,16 +195,37 @@ const builtInMiddlewares = {
    * @returns {Function}
    */
   cors(options = {}) {
-    const origin = options.origin || '*';
-    const methods = options.methods || ['POST'];
-    const headers = options.headers || ['Content-Type'];
+    const config = options === true ? {} : options;
+    const origin = config.origin ?? '*';
+    const methods = config.methods || ['POST'];
+    const headers = config.headers || config.allowedHeaders || ['Content-Type'];
 
     return async (context) => {
-      const { res } = context;
+      const { req, res } = context;
+      const requestOrigin = req?.headers?.origin;
+      let allowedOrigin = origin;
 
-      res.header('Access-Control-Allow-Origin', origin);
+      if (origin === false) {
+        return context;
+      }
+
+      if (Array.isArray(origin)) {
+        if (!requestOrigin || !origin.includes(requestOrigin)) {
+          return context;
+        }
+        allowedOrigin = requestOrigin;
+        res.vary('Origin');
+      } else if (origin === true) {
+        allowedOrigin = requestOrigin || '*';
+        if (requestOrigin) res.vary('Origin');
+      }
+
+      res.header('Access-Control-Allow-Origin', allowedOrigin);
       res.header('Access-Control-Allow-Methods', methods.join(', '));
       res.header('Access-Control-Allow-Headers', headers.join(', '));
+      if (config.credentials === true) {
+        res.header('Access-Control-Allow-Credentials', 'true');
+      }
 
       return context;
     };
@@ -241,4 +262,8 @@ const builtInMiddlewares = {
   },
 };
 
-module.exports = { MiddlewareManager, builtInMiddlewares };
+module.exports = {
+  MiddlewareManager,
+  MemoryRateLimitStore,
+  builtInMiddlewares,
+};

package/src/safe.d.ts

@@ -12,6 +12,7 @@ declare namespace Safe {
   export import RpcHttpError = Main.RpcHttpError;
   export import Logger = Main.Logger;
   export import MiddlewareManager = Main.MiddlewareManager;
+  export import MemoryRateLimitStore = Main.MemoryRateLimitStore;
   export import builtInMiddlewares = Main.builtInMiddlewares;
   export import SchemaValidator = Main.SchemaValidator;
   export import commonSchemas = Main.commonSchemas;
@@ -27,6 +28,7 @@ declare namespace Safe {
   export import LoggingConfig = Main.LoggingConfig;
   export import CorsConfig = Main.CorsConfig;
   export import RateLimitConfig = Main.RateLimitConfig;
+  export import RateLimitStore = Main.RateLimitStore;
   export import AuthConfig = Main.AuthConfig;
   export import ValidationConfig = Main.ValidationConfig;
   export import RpcEndpointOptions = Main.RpcEndpointOptions;

package/src/safe.js

@@ -119,6 +119,7 @@ module.exports.RpcError = Main.RpcError;
 module.exports.RpcHttpError = Main.RpcHttpError;
 module.exports.Logger = Main.Logger;
 module.exports.MiddlewareManager = Main.MiddlewareManager;
+module.exports.MemoryRateLimitStore = Main.MemoryRateLimitStore;
 module.exports.builtInMiddlewares = Main.builtInMiddlewares;
 module.exports.SchemaValidator = Main.SchemaValidator;
 module.exports.commonSchemas = Main.commonSchemas;