@contrast/route-coverage 1.50.0 → 1.52.0

package/lib/install/fastify/fastify-middie.js

@@ -0,0 +1,67 @@
+/*
+ * Copyright: 2025 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */
+'use strict';
+
+const { RouteType } = require('@contrast/common');
+const { patchType, formatHandler } = require('./../../utils/route-info');
+const isArray = (arr) => Array.isArray(arr);
+module.exports = function init(core) {
+  const { patcher, depHooks, routeCoverage } = core;
+
+  return core.routeCoverage.fastifyMiddie = {
+    install() {
+      depHooks.resolve({ name: '@fastify/middie', version: '*', file: 'lib/engine.js' }, (middie) => patcher.patch(middie, {
+        name: 'fastifyMiddie',
+        patchType,
+        post(data) {
+          patcher.patch(data.result, 'use', {
+            name: 'use',
+            patchType,
+            pre(data) {
+              const [url, fn] = data.args;
+              if (!url || !fn || !core.config.getEffectiveValue('assess.report_middleware_routes')) return;
+
+              const middleware = isArray(fn) ? fn : [fn];
+              const formattedPath = isArray(url) ? `[${url.join(', ')}]` : url;
+              const patchedMiddleware = middleware.map((f) => {
+                const formattedHandler = formatHandler(f);
+                const signature = `fastify.use(${formattedPath}, ${formattedHandler})`;
+
+                const routeInfo = {
+                  signature,
+                  url: formattedPath,
+                  method: 'use',
+                  normalizedUrl: formattedPath,
+                  type: RouteType.MIDDLEWARE,
+                  framework: 'fastify'
+                };
+                routeCoverage.discover(routeInfo);
+
+                return patcher.patch(f, {
+                  name: 'middleware',
+                  patchType,
+                  post() {
+                    routeCoverage.observe(routeInfo);
+                  }
+                });
+              });
+              data.args[1] = patchedMiddleware;
+            }
+          });
+        }
+      }));
+    }
+  };
+};

package/lib/install/{fastify.js → fastify/fastify.js}

@@ -14,9 +14,12 @@
  */
 'use strict';
 
-const { getFastifyMethods } = require('../utils/methods');
-const { primordials: { StringPrototypeToLowerCase, StringPrototypeSplit } } = require('@contrast/common');
-const { patchType } = require('./../utils/route-info');
+const { getFastifyMethods } = require('../../utils/methods');
+const {
+  primordials: { StringPrototypeToLowerCase, StringPrototypeSplit },
+  RouteType,
+} = require('@contrast/common');
+const { patchType, formatHandler } = require('./../../utils/route-info');
 
 // Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Fastify
 module.exports = function init(core) {
@@ -35,18 +38,19 @@ module.exports = function init(core) {
     return route?.[kRoutePrefix];
   }
 
-  function createRouteInfo(method, url, fullyDeclared) {
+  function createRouteInfo(method, url, fullyDeclared, type, handler) {
     method = StringPrototypeToLowerCase.call(method);
 
     const signature = fullyDeclared
-      ? `fastify.route({ method: '${method}', url: '${url}', handler: [Function] })`
-      : `fastify.${method}('${url}', [Function])`;
+      ? `fastify.route({ method: ${method}, url: ${url}, handler: ${formatHandler(handler)} })`
+      : `fastify.${method}(${url}, ${formatHandler(handler)})`;
 
     const routeInfo = {
       signature,
       url,
       method,
       normalizedUrl: url,
+      type,
       framework: 'fastify'
     };
     return routeInfo;
@@ -54,14 +58,18 @@ module.exports = function init(core) {
 
   function patchHandler(route, handle, routeInfo) {
     const pre = ({ args }) => {
-      const [req] = args;
-
-      // todo(NODE-3793): support for @fastify/websocket
-      if (req.constructor.name == 'WebSocket') return;
-
+      let req, type;
+      if (args[0]?.constructor?.name == 'WebSocket') {
+        req = args[1];
+        type = RouteType.MESSAGE_BROKER;
+      } else {
+        req = args[0];
+        type = RouteType.HTTP;
+      }
       const method = StringPrototypeToLowerCase.call(req.raw?.method);
       const [url] = StringPrototypeSplit.call(req.url, /\?/);
-      routeCoverage.observe({ ...routeInfo, url, method });
+
+      routeCoverage.observe({ ...routeInfo, method, type, url });
     };
 
     const name = `fastify.route.${handle}`;
@@ -81,28 +89,30 @@ module.exports = function init(core) {
     }
   }
 
-  function discoverAndPatch(method, path, handler, handle, methods, fullyDeclared) {
+  function discoverAndPatch(method, path, routeObj, handle, handler, methods, fullyDeclared) {
+    const type = routeObj?.options?.websocket ? RouteType.MESSAGE_BROKER : RouteType.HTTP;
+
     if (Array.isArray(method)) {
       // If all valid methods are included in `method` then .all shorthand was most likely used
       if (methods.every(m => method.includes(m))) {
-        const routeInfo = createRouteInfo('all', path, fullyDeclared);
+        const routeInfo = createRouteInfo('all', path, fullyDeclared, type, handler);
         routeCoverage.discover(routeInfo);
-        patchHandler(handler, handle, routeInfo);
+        patchHandler(routeObj, handle, routeInfo);
       } else {
         method.forEach((verb) => {
-          const routeInfo = createRouteInfo(verb, path, fullyDeclared);
+          const routeInfo = createRouteInfo(verb, path, fullyDeclared, type, handler);
           routeCoverage.discover(routeInfo);
-          patchHandler(handler, handle, routeInfo);
+          patchHandler(routeObj, handle, routeInfo);
         });
       }
     } else {
-      const routeInfo = createRouteInfo(method, path, fullyDeclared);
+      const routeInfo = createRouteInfo(method, path, fullyDeclared, type, handler);
       routeCoverage.discover(routeInfo);
-      patchHandler(handler, handle, routeInfo);
+      patchHandler(routeObj, handle, routeInfo);
     }
   }
 
-  return core.routeCoverage.fastify = {
+  return core.routeCoverage.fastifyCore = {
     install() {
       /**
        * There are some subtle differences between fastify minor versions the instrumentation must account for
@@ -148,7 +158,7 @@ module.exports = function init(core) {
                   let handle = 'handler';
                   if (!handler && typeof options === 'function') handle = 'options';
 
-                  discoverAndPatch(method, path, routeObj ? data.args[0] : data.args, handle, fastifyMethods, false);
+                  discoverAndPatch(method, path, routeObj ? data.args[0] : data.args, handle, options || handler, fastifyMethods, false);
                 }
               });
 
@@ -165,7 +175,7 @@ module.exports = function init(core) {
 
                   const prefix = getPrefix(data.obj);
                   const path = prefix ? prefix + url : url;
-                  discoverAndPatch(method, path, routeArgs, 'handler', fastifyMethods, true);
+                  discoverAndPatch(method, path, routeArgs, 'handler', handler, fastifyMethods, true);
                 }
               });
             }

package/lib/install/{express → fastify}/index.js

@@ -18,14 +18,15 @@
 const { callChildComponentMethodsSync } = require('@contrast/common');
 
 module.exports = function(core) {
-  const expressRouteCoverage = core.routeCoverage.express = {
+  const fastifyRouteCoverage = core.routeCoverage.fastify = {
     install() {
-      callChildComponentMethodsSync(expressRouteCoverage, 'install');
+      callChildComponentMethodsSync(fastifyRouteCoverage, 'install');
     },
   };
 
-  require('./express4')(core);
-  require('./express5')(core);
+  require('./fastify')(core);
+  require('./fastify-express')(core);
+  require('./fastify-middie')(core);
 
-  return expressRouteCoverage;
+  return fastifyRouteCoverage;
 };

package/lib/install/graphql.js

@@ -14,7 +14,10 @@
  */
 'use strict';
 
-const { primordials: { ArrayPrototypeJoin } } = require('@contrast/common');
+const {
+  RouteType,
+  primordials: { ArrayPrototypeJoin },
+} = require('@contrast/common');
 const { patchType } = require('./../utils/route-info');
 
 module.exports = function init(core) {
@@ -61,6 +64,7 @@ module.exports = function init(core) {
             method,
             normalizedUrl,
             signature,
+            type: RouteType.HTTP, // todo: extend existing types
             framework: 'graphql',
           });
         });
@@ -77,6 +81,7 @@ module.exports = function init(core) {
                 method: store.sourceInfo?.method,
                 normalizedUrl,
                 signature,
+                type: RouteType.HTTP, // todo: extend existing types
                 url: normalizedUrl,
                 framework: 'graphql',
               });

package/lib/install/koa.js

@@ -15,28 +15,15 @@
 'use strict';
 
 const { METHODS } = require('./../utils/methods');
-const { isString, primordials: { StringPrototypeToLowerCase, StringPrototypeSplit } } = require('@contrast/common');
-const { createSignature, patchType } = require('./../utils/route-info');
+const { isString, RouteType, primordials: { StringPrototypeToLowerCase, StringPrototypeSplit } } = require('@contrast/common');
+const { patchType, formatHandler } = require('./../utils/route-info');
 
 // Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Koa
 module.exports = function init(core) {
   const { patcher, depHooks, routeCoverage } = core;
-
-  function createRouteInfo(method, url) {
-    method = StringPrototypeToLowerCase.call(method);
-    const routeInfo = {
-      signature: createSignature(url, method),
-      url,
-      method,
-      normalizedUrl: url,
-      framework: 'koa'
-    };
-    return routeInfo;
-  }
-
   return core.routeCoverage.koa = {
     install() {
-      depHooks.resolve({ name: 'koa', version: '>=2.3.0 <3' }, (Koa) => {
+      depHooks.resolve({ name: 'koa', version: '>=2.3.0 <4' }, (Koa, pkgMeta) => {
         // Koa uses its own routing library @koa/router to define routes before
         // mounting them on the app with .use so instrumenting use and traversing
         // the constructed routes is the more technically correct approach than
@@ -48,40 +35,47 @@ module.exports = function init(core) {
             if (args?.length === 0) return;
             const [router] = args;
 
-            if (!router?.router) return;
+            if (!router?.router) {
+              core.logger.debug('no routes detected in koa router stack: %s@%s', pkgMeta.name, pkgMeta.version);
+              return;
+            }
 
             router.router.stack.forEach((Layer) => {
-              const { methods, path } = Layer;
-              if (!path || !isString(path)) return;
+              const { methods, path, stack } = Layer;
+              if (!path || !isString(path) || !stack || stack.length === 0) return;
 
-              let routeInfo;
-              if (methods.length === 0) {
-                routeInfo = createRouteInfo('use', path);
-                routeCoverage.discover(routeInfo);
-              } else if (METHODS.every(m => methods.includes(m))) {
-                // If a route was defined using .all this methods property will be an
-                // array of all methods supported by Koa
-                routeInfo = createRouteInfo('all', path);
+              const patchedMiddleware = [];
+              stack.forEach((handler) => {
+                const method = methods.length === 0 ? 'use' : METHODS.every(m => methods.includes(m)) ? 'all' : StringPrototypeToLowerCase.call(methods[methods.length - 1]);
+                if (method === 'use' && !core.config.getEffectiveValue('assess.report_middleware_routes')) return;
+                const routeInfo = {
+                  signature: `Router.${method}(${path}, ${formatHandler(handler)})`,
+                  method,
+                  url: path,
+                  normalizedUrl: path,
+                  framework: 'koa',
+                  type: method === 'use' ? RouteType.MIDDLEWARE : RouteType.HTTP
+                };
                 routeCoverage.discover(routeInfo);
-              } else {
-                methods.forEach((method) => {
-                  routeInfo = createRouteInfo(method, path);
-                  routeCoverage.discover(routeInfo);
-                });
-              }
+                const patchedHandler = patcher.patch(handler, {
+                  name: 'handler',
+                  patchType,
+                  pre(data) {
+                    const { request } = data.args[0];
+                    if (!request) return;
 
-              if (!Layer.stack || Layer.stack.length === 0) return;
-              async function observationMiddleware(ctx, next) {
-                if (!ctx.request) return;
-                const { url: reqUrl, method } = ctx.request;
-                const [url] = StringPrototypeSplit.call(reqUrl, /\?/);
-                routeCoverage.observe({ ...routeInfo, url, method: StringPrototypeToLowerCase.call(method) });
-                await next();
-              }
-              // If two routes share middleware, the same stack is used
-              // To add our observation middleware without adding them to all routes
-              // we need to create a shallow copy
-              Layer.stack = [observationMiddleware, ...Layer.stack];
+                    const { method, url } = request;
+                    if (!method | !url) return;
+                    routeCoverage.observe({
+                      ...routeInfo,
+                      method: StringPrototypeToLowerCase.call(method),
+                      url: StringPrototypeSplit.call(url, /\?/)[0]
+                    });
+                  }
+                });
+                patchedMiddleware.push(patchedHandler);
+              });
+              Layer.stack = patchedMiddleware;
             });
           }
         });

package/lib/install/socket.io.js

@@ -0,0 +1,127 @@
+/*
+ * Copyright: 2025 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */
+'use strict';
+
+const { set, RouteType, primordials } = require('@contrast/common');
+const Core = require('@contrast/core/lib/ioc/core');
+const { patchType } = require('../utils/route-info');
+
+const COMPONENT_NAME = 'routeCoverage.socketio';
+const FRAMEWORK = 'socket.io';
+const kServerMountPath = Symbol('cs:socket.io.path');
+const kServerRouteSignature = Symbol('cs:socket.io.route-signature');
+
+module.exports = Core.makeComponent({
+  name: COMPONENT_NAME,
+  factory: (core) => new SocketIORouteCoverage(core),
+});
+
+class SocketIORouteCoverage {
+  constructor(core) {
+    Object.defineProperty(this, 'core', { value: core });
+    set(core, COMPONENT_NAME, this);
+  }
+
+  makePath(mountPath) {
+    // we append trailing "/" since that's part of socket.io protocol
+    return mountPath.endsWith('/') ? mountPath : `${mountPath}/`;
+  }
+
+  makeSignature(mountPath) {
+    return `Socket.IO ${mountPath}`;
+  }
+
+  install() {
+    const self = this;
+    const {
+      depHooks,
+      patcher,
+      routeCoverage,
+    } = this.core;
+
+    depHooks.resolve(
+      { name: 'socket.io', version: '4' },
+      /** @param {import('socket.io-4')} xport the exported socket.io module */
+      (xport) => {
+        patcher.patch(xport.Server.prototype, 'initEngine', {
+          name: 'socket.io.Server.prototype.initEngine',
+          patchType,
+          post(data) {
+            if (!this._path) return;
+            const [httpServer] = data.args;
+            const path = self.makePath(this._path);
+            const signature = self.makeSignature(path);
+
+            this.eio[kServerMountPath] = path;
+            this.eio[kServerRouteSignature] = signature;
+
+            routeCoverage.discover({
+              framework: FRAMEWORK,
+              signature,
+              method: 'all',
+              normalizedUri: path,
+              type: RouteType.MESSAGE_BROKER,
+              url: path,
+            });
+
+            // handle observation for HTTP polling; this doesn't emit when upgrading to ws://
+            httpServer.on(
+              'request',
+              /** @param {import('http').IncomingMessage} req */
+              (req /*, res */) => {
+                if (req.url?.startsWith?.(path)) {
+                  routeCoverage.observe({
+                    framework: FRAMEWORK,
+                    method: primordials.StringPrototypeToLowerCase.call(req.method),
+                    normalizedUrl: path,
+                    signature,
+                    type: RouteType.MESSAGE_BROKER,
+                    url: path,
+                  });
+                }
+              });
+          }
+        });
+      }
+    );
+
+    // this is to handle observations for websocket upgrades; 1 upgrade request counts as single observation
+    depHooks.resolve(
+      { name: 'engine.io', version: '6' },
+      /** @param {import('engine.io')} xport the exported engine.io module */
+      (xport) => {
+        patcher.patch(xport.Server.prototype, 'onWebSocket', {
+          name: 'engine.io.Server.prototype.onWebSocket',
+          patchType,
+          pre(data) {
+            const eioServer = this;
+            const [req] = data.args;
+
+            if (!eioServer[kServerMountPath] || !eioServer[kServerRouteSignature]) return;
+
+            routeCoverage.observe({
+              framework: FRAMEWORK,
+              method: req.method,
+              normalizedUrl: eioServer[kServerMountPath],
+              signature: eioServer[kServerRouteSignature],
+              type: RouteType.MESSAGE_BROKER,
+              url: eioServer[kServerMountPath],
+            });
+          },
+        });
+      }
+    );
+  }
+}

package/lib/utils/route-info.js

@@ -15,6 +15,8 @@
 'use strict';
 
 const patchType = 'route-coverage';
+const { funcInfo } = require('@contrast/fn-inspect');
+const { primordials: { StringPrototypeReplace, StringPrototypeSubstring } } = require('@contrast/common');
 
 /**
  * Creates a formatted "signature" for a route
@@ -28,4 +30,27 @@ function createSignature(path, method = '', obj = 'Router', handler = '[Function
   return `${obj}.${method}('${path}', ${handler})`;
 }
 
-module.exports = { createSignature, patchType };
+/**
+ * Creates a formatted handler signature for a route
+ * @param {function} handler
+ * @param {string} appDir
+ * @return {string} formatted handler
+ */
+function formatHandler(handler, appDir) {
+  const info = funcInfo(handler);
+  if (!info) return '[Function]';
+
+  let file = info.file ?
+    StringPrototypeReplace.call(info.file, appDir, '') :
+    '';
+  if (file.length > 30) {
+    file = `...${StringPrototypeSubstring.call(file, file.length - 40)}`;
+  }
+  const handlerName = info.method || handler.name || 'anonymous';
+  const formattedHandler = (file && Number.isFinite(info.lineNumber) && Number.isFinite(info.column)) ?
+    `[${handlerName} ${file} ${info.lineNumber}:${info.column}]` :
+    `[Function: ${handlerName}]`; // what util.inspect(handler) would return
+  return formattedHandler;
+}
+
+module.exports = { createSignature, patchType, formatHandler };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/route-coverage",
-  "version": "1.50.0",
+  "version": "1.52.0",
   "description": "Handles route discovery and observation",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -20,14 +20,14 @@
     "test": "bash ../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.37.0",
-    "@contrast/config": "1.53.0",
-    "@contrast/core": "1.58.0",
-    "@contrast/dep-hooks": "1.27.0",
+    "@contrast/common": "1.38.0",
+    "@contrast/config": "1.54.1",
+    "@contrast/core": "1.59.1",
+    "@contrast/dep-hooks": "1.28.1",
     "@contrast/fn-inspect": "^5.0.2",
-    "@contrast/logger": "1.31.0",
-    "@contrast/patcher": "1.30.0",
-    "@contrast/scopes": "1.28.0",
+    "@contrast/logger": "1.32.1",
+    "@contrast/patcher": "1.31.1",
+    "@contrast/scopes": "1.29.1",
     "semver": "^7.6.0"
   }
 }