rpc-express-toolkit 4.5.0 → 4.5.2

package/README.md

@@ -10,6 +10,9 @@
 
 JSON-RPC 2.0 toolkit for Express.js with simplified APIs, middleware, schema validation, batch support, and optional Safe Mode type preservation.
 
+Version **4.5.2**, including the Safe proxy, sanitizes unexpected errors by
+default and tightens invalid envelope handling; see [Changelog](CHANGELOG.md).
+
 ## Which Package Should I Use?
 
 - Use `rpc-express-toolkit` if you are building a JSON-RPC endpoint on Express.
@@ -34,7 +37,7 @@ Requirements:
 
 ### Compatibility
 
-`rpc-express-toolkit` is tested with Node.js 18, 20, 22, and 24 across Express 4 and Express 5. See [Compatibility](docs/COMPATIBILITY.md) for the current runtime matrix.
+The CI matrix covers Node.js 18, 20, 22, 24, and 26 across Express 4 and Express 5. See [Compatibility](docs/COMPATIBILITY.md) for the configured runtime matrix.
 
 ### TypeScript
 
@@ -226,6 +229,10 @@ const rpc = new RpcEndpoint(app, context, {
 
 Calls to methods outside the whitelist are rejected. This is a basic method restriction mechanism, not a complete role or permission system. Project-specific authorization rules can be implemented with middleware hooks such as `beforeCall`; see `README_ADVANCED.md`.
 
+Client `params` are passed as one object or array argument, never expanded into
+the server-owned application or call context. Base authorization on the
+server-validated context rather than identity claims in client parameters.
+
 ### Safe Import (opt-in)
 
 [![npm (proxy)](https://img.shields.io/npm/v/rpc-express-toolkit-safe.svg)](https://www.npmjs.com/package/rpc-express-toolkit-safe)
@@ -250,6 +257,11 @@ const client = new RpcSafeClient('http://localhost:3000/api');
 
 This keeps JSON-RPC 2.0 compliance as default for the main entrypoint, while offering a convenient safe-mode import for projects that prefer explicit type disambiguation.
 
+Safe encoding applies only to `params`, `result`, and `error.data`, not to
+`method`, `id`, or `error.message`. It is type preservation, not authentication
+or encryption. See the [request contract](README_ADVANCED.md#request-contract)
+for notification, ID, and invalid-envelope behavior.
+
 #### Alternative Compatibility Package
 
 `rpc-express-toolkit-safe` is a thin compatibility package that re-exports the same safe preset. Use it only when a separate package name is useful for dependency policy or migration; new projects can import `rpc-express-toolkit/safe` directly.
@@ -314,7 +326,14 @@ In `__rpc.capabilities`, `auth` is a boolean indicating whether authentication m
 
 ## Full Details
 
-For advanced configuration, middleware, structured logging, safe serialization, error handling, and more, see `README_ADVANCED.md`.
+Unexpected exceptions return only `code: -32603` and `message: "Internal error"`
+by default, for both single calls and batches. Intentional application errors
+with an explicit safe-integer RPC `code` other than `-32603` retain their `message`
+and optional `data`, without an automatically attached stack trace. Treat those
+fields as public. Set `sanitizeErrors: false` only for local debugging; it can
+expose internal messages, exception data, and stack traces to callers.
+
+For advanced configuration, middleware, structured logging, safe serialization, error handling, and more, see [Advanced Usage](README_ADVANCED.md).
 
 ## Related Projects
 

package/docs/COMPATIBILITY.md

@@ -6,14 +6,17 @@
 
 | Runtime | Status |
 | --- | --- |
-| Node.js 18.x | CI tested |
-| Node.js 20.x | CI tested |
-| Node.js 22.x | CI tested |
-| Node.js 24.x | CI tested |
-| Express 4.x | CI tested |
-| Express 5.x | CI tested |
-
-The GitHub Actions matrix runs the test suite across Node.js 18, 20, 22, and 24 with both Express 4 and Express 5.
+| Node.js 18.x | Configured CI target |
+| Node.js 20.x | Configured CI target |
+| Node.js 22.x | Configured CI target |
+| Node.js 24.x | Configured CI target |
+| Node.js 26.x | Configured CI target |
+| Express 4.x | Configured CI target |
+| Express 5.x | Configured CI target |
+
+The GitHub Actions matrix is configured to run the test suite across Node.js 18,
+20, 22, 24, and 26 with both Express 4 and Express 5. This is the configured
+coverage, not a claim that every target has been rerun for the 4.5.2 release.
 
 ## Module And TypeScript Compatibility
 
@@ -42,6 +45,26 @@ acknowledge the compiler's deprecation notice for the deliberately explicit
 
 Package validation runs in CI and as part of `prepublishOnly`, so declaration or packaging regressions block publication.
 
+Under WSL, run packaging from a native Linux filesystem: Windows-mounted source trees can
+make regular files appear executable (`0755`), which the runner deliberately
+rejects. A temporary source copy with regular file modes preserves this check
+without changing the original checkout.
+
+An offline run requires both registry metadata and package tarballs in npm's
+selected cache. A package installed elsewhere, or a cached version listing,
+does not by itself guarantee that npm can install the isolated consumer offline.
+Select the cache for that process with `npm_config_cache`; use
+`npm_config_offline=true` when network access must be disabled.
+
+Local validation on 2026-10-12 passed the full packaged-consumer runner for the
+4.5.2 source: Node.js 24.14.0, npm 11.12.0, TypeScript 6.0.3, Express
+4.22.2, `@types/express` 5.0.6, and `@types/node` 26.6.2. The offline run used
+`npm_config_before=2026-09-20T00:00:00Z` to select compatible versions already
+cached, without changing manifests or tests. It covered packaging, installation,
+ESM/CommonJS types and runtime, Publint, and ATTW for both the main and Safe proxy
+packages. This does not establish a result for uncached `@types/node` 26.6.4 or
+for every configured CI target.
+
 ## Express Dependency
 
 Express is declared as a peer dependency:
@@ -59,6 +82,8 @@ The Express compatibility tests cover:
 - standard JSON-RPC endpoint calls;
 - batch requests;
 - Safe Mode endpoints;
-- introspection reporting of the active Express runtime.
+- introspection reporting of the active Express runtime;
+- invalid request envelopes and null IDs/results;
+- default error sanitization, intentional public errors, and the debug opt-out.
 
 Broader RPC behavior is covered by the main test suite and is expected to run identically on Express 4 and Express 5. Module and declaration compatibility is covered separately by the packaged consumer validation.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "rpc-express-toolkit",
-    "version":  "4.5.0",
+    "version":  "4.5.2",
     "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

@@ -9,14 +9,6 @@ class BatchHandler {
     this.endpoint = endpoint;
   }
 
-  serializeErrorData(error, batchIndex) {
-    const errorWithBatchIndex = addBatchIndex(error, batchIndex);
-    if (!hasOwn(errorWithBatchIndex, 'data')) {
-      return undefined;
-    }
-    return this.endpoint.serializeBigIntsAndDates(errorWithBatchIndex.data);
-  }
-
   /**
    * Check if request is a batch request
    * @param {any} body
@@ -104,15 +96,10 @@ class BatchHandler {
           index
         );
       } catch (error) {
-        const errorData = this.serializeErrorData(error, index);
         return {
           jsonrpc: '2.0',
           id: request && hasOwn(request, 'id') ? request.id : null,
-          error: {
-            code: error.code || -32603,
-            message: error.message || 'Internal error',
-            ...(errorData !== undefined && { data: errorData }),
-          },
+          error: this.endpoint.formatError(error, index),
         };
       }
     });
@@ -314,16 +301,10 @@ class BatchHandler {
         return null;
       }
 
-      const errorData = this.serializeErrorData(error, batchIndex);
-
       return {
         jsonrpc: '2.0',
         id,
-        error: {
-          code: error.code || -32603,
-          message: error.message || 'Internal error',
-          ...(errorData !== undefined && { data: errorData }),
-        },
+        error: this.endpoint.formatError(error, batchIndex),
       };
     }
   }

package/src/index.d.ts

@@ -60,6 +60,8 @@ declare class RpcEndpoint<C = any> {
   listMethods(): string[];
   getMetrics(): object;
 
+  formatError(error: unknown, batchIndex?: number): RpcEndpoint.JSONRPCError;
+
   static serveScripts(router: Router, url?: string): void;
 
   reply(
@@ -193,6 +195,8 @@ declare namespace RpcEndpoint {
     logging?: LoggingConfig;
     warnOnUnsafe?: boolean;
     strictMode?: boolean;
+    /** Hide unexpected error details (default true); false is for local debugging only. */
+    sanitizeErrors?: boolean;
     maxSerializationDepth?: number;
     maxDeserializationDepth?: number;
     autoJsonMiddleware?: boolean;

package/src/index.js

@@ -31,7 +31,7 @@ const {
   SchemaBuilder,
 } = require('./validation');
 const BatchHandler = require('./batch');
-const { hasOwn, validateEnvelope } = require('./protocol');
+const { addBatchIndex, hasOwn, validateEnvelope } = require('./protocol');
 
 /**
  * Default properties to include in error serialization.
@@ -165,6 +165,7 @@ class RpcEndpoint {
     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
+    this.#options.sanitizeErrors = this.#options.sanitizeErrors !== false;
     this.#options.enableIntrospection =
       this.#options.enableIntrospection === true; // Default false
     this.#options.introspectionPrefix =
@@ -499,18 +500,13 @@ class RpcEndpoint {
         await this.#processSingleRequest(req, res, context, startTime);
       } catch (error) {
         this.#logger.error('Endpoint error', {
-          error: error.message,
-          stack: error.stack,
+          error: error?.message,
+          stack: error?.stack,
         });
 
-        res.json({
-          jsonrpc: '2.0',
+        this.reply(res, {
           id: null,
-          error: {
-            code: -32603,
-            message: 'Internal error',
-            data: serializeError(error, true),
-          },
+          error: this.formatError(error),
         });
       }
     });
@@ -695,7 +691,7 @@ class RpcEndpoint {
         });
       } catch (middlewareError) {
         this.#logger.error('Error middleware failed', {
-          error: middlewareError.message,
+          error: middlewareError?.message,
         });
       }
 
@@ -704,19 +700,9 @@ class RpcEndpoint {
         return null;
       }
 
-      const errorData =
-        hasOwn(err, 'data') && err.data !== undefined
-          ? this.serializeBigIntsAndDates(err.data)
-          : undefined;
-
       this.reply(res, {
         id,
-        error: {
-          code: err.code || -32603,
-          message: err.message || `Internal error`,
-          ...(errorData !== undefined && { data: errorData }),
-          error: serializeError(err, true),
-        },
+        error: this.formatError(err),
       });
     }
     // Ensure explicit return for consistent-return rule
@@ -881,6 +867,41 @@ class RpcEndpoint {
     };
   }
 
+  /**
+   * Build a public RPC error consistently for single and batch requests.
+   * Only explicit integer RPC codes identify application errors; native error
+   * codes such as ENOENT must not expose unexpected implementation details.
+   * @param {any} error
+   * @param {number} [batchIndex]
+   * @returns {{ code: number, message: string, data?: any, error?: Object }}
+   */
+  formatError(error, batchIndex) {
+    const code = Number.isSafeInteger(error?.code) ? error.code : -32603;
+    if (this.#options.sanitizeErrors && code === -32603) {
+      return { code: -32603, message: 'Internal error' };
+    }
+
+    let response = {
+      code,
+      message:
+        typeof error?.message === 'string' && error.message
+          ? error.message
+          : 'Internal error',
+      ...(error?.data !== undefined && { data: error.data }),
+    };
+    if (batchIndex !== undefined) {
+      response = addBatchIndex(response, batchIndex);
+    }
+    if (hasOwn(response, 'data')) {
+      response.data = this.serializeBigIntsAndDates(response.data);
+    }
+    if (code === -32603) {
+      // Debug opt-out only: never add raw exceptions to application errors.
+      response.error = serializeError(error, true);
+    }
+    return response;
+  }
+
   /**
    * Send a JSON-RPC 2.0 response.
    * @param {Response} res The Express response object.

package/src/logger.js

@@ -159,10 +159,10 @@ class Logger {
       method,
       id,
       duration: `${duration}ms`,
-      error: error.message,
-      code: error.code,
+      error: error?.message,
+      code: error?.code,
       stack:
-        this.levels[this.level] >= this.levels.debug ? error.stack : undefined,
+        this.levels[this.level] >= this.levels.debug ? error?.stack : undefined,
     });
   }
 

package/src/protocol.js

@@ -5,17 +5,21 @@ function isObject(value) {
 }
 
 function isValidId(id) {
-  return id === null || typeof id === 'string' || typeof id === 'number';
+  return (
+    id === null ||
+    typeof id === 'string' ||
+    (typeof id === 'number' && Number.isFinite(id))
+  );
 }
 
 function isValidParams(params) {
   return Array.isArray(params) || isObject(params);
 }
 
-function validationError(message, id = null) {
+function validationError(message) {
   return {
     valid: false,
-    responseId: id,
+    responseId: null,
     error: {
       code: -32600,
       message,
@@ -32,37 +36,26 @@ function validateEnvelope(request) {
   const responseId = hasId && isValidId(request.id) ? request.id : null;
 
   if (request.jsonrpc !== '2.0') {
-    return validationError(
-      "Invalid Request: 'jsonrpc' must be '2.0'.",
-      responseId
-    );
+    return validationError("Invalid Request: 'jsonrpc' must be '2.0'.");
   }
 
   if (typeof request.method !== 'string') {
-    return validationError(
-      "Invalid Request: 'method' must be a string.",
-      responseId
-    );
+    return validationError("Invalid Request: 'method' must be a string.");
   }
 
   if (request.method.length === 0) {
-    return validationError(
-      "Invalid Request: 'method' must not be empty.",
-      responseId
-    );
+    return validationError("Invalid Request: 'method' must not be empty.");
   }
 
   if (hasOwn(request, 'params') && !isValidParams(request.params)) {
     return validationError(
-      "Invalid Request: 'params' must be an object or array.",
-      responseId
+      "Invalid Request: 'params' must be an object or array."
     );
   }
 
   if (hasId && !isValidId(request.id)) {
     return validationError(
-      "Invalid Request: 'id' must be a string, number, or null.",
-      null
+      "Invalid Request: 'id' must be a string, number, or null."
     );
   }