@contrast/route-coverage 1.33.0 → 1.35.0

package/lib/index.js

@@ -16,7 +16,6 @@
 'use strict';
 
 const { callChildComponentMethodsSync, Event } = require('@contrast/common');
-const { routeIdentifier } = require('./utils/route-info');
 const NormalizedUrlMapper = require('./normalized-url-mapper');
 
 /**
@@ -36,6 +35,7 @@ module.exports = function init(core) {
   const recentlyObserved = new Set();
   const routeQueue = new Map();
 
+  const routeIdentifier = (method, signature) => `${method}.${signature}`;
   const routeCoverage = core.routeCoverage = {
     _normalizedUrlMapper: new NormalizedUrlMapper(),
 
@@ -45,8 +45,9 @@ module.exports = function init(core) {
 
     discover(info) {
       logger.trace({ info }, 'Discovered new route:');
-      routeInfo.set(routeIdentifier(info), info);
+      routeInfo.set(routeIdentifier(info.method, info.signature), info);
       this._normalizedUrlMapper.handleDiscover(info);
+
     },
 
     discoveryFinished() {
@@ -58,7 +59,7 @@ module.exports = function init(core) {
 
     // See NODE-3548: routes defined "lazily" will be discovered here after startup, queued, and reported
     queue(info) {
-      const id = routeIdentifier(info);
+      const id = routeIdentifier(info.method, info.signature);
       if (routeInfo.has(id)) return;
 
       routeInfo.set(id, info);
@@ -77,13 +78,20 @@ module.exports = function init(core) {
     },
 
     observe(info) {
-      const route = info.signature ? info : routeInfo.get(routeIdentifier(info));
+      let route;
+      const { signature } = info;
+      const methods = [info.method, 'all', 'use'];
+      for (const method of methods) {
+        route = routeInfo.get(routeIdentifier(method, signature));
+        if (route) break;
+      }
 
       if (!route) {
         logger.debug(info, 'unable to observe undiscovered route');
         return;
       }
 
+      route.method = info.method;
       route.url = info.url;
       const store = scopes.sources.getStore();
       if (store && !store.route) {
@@ -112,6 +120,7 @@ module.exports = function init(core) {
   require('./install/http')(core);
   require('./install/express')(core);
   require('./install/fastify')(core);
+  require('./install/graphql')(core);
   require('./install/hapi')(core);
   require('./install/koa')(core);
   require('./install/restify')(core);

package/lib/index.test.js

@@ -48,8 +48,8 @@ describe('route coverage', function () {
     });
 
     it('emits an event when discovery is finished', function () {
-      const eventA = { signature: 'hello', url: 'url', method: 'get' };
-      const eventB = { signature: 'hello', url: 'url', method: 'post' };
+      const eventA = { signature: 'url.get', url: 'url', method: 'get' };
+      const eventB = { signature: 'url.post', url: 'url', method: 'post' };
       core.routeCoverage.discover(eventA);
       core.routeCoverage.discover(eventA); // check that we dedupe discovery.
       core.routeCoverage.discover(eventB);
@@ -62,7 +62,7 @@ describe('route coverage', function () {
     });
 
     it('queues new events after initial discovery is finished', function () {
-      const eventA = { signature: 'hello', url: 'url', method: 'get' };
+      const eventA = { signature: 'url.get', url: 'url', method: 'get' };
       core.routeCoverage.discover(eventA);
       core.routeCoverage.discoveryFinished();
       expect(core.messages.emit).to.have.been.calledWith(
@@ -70,7 +70,7 @@ describe('route coverage', function () {
         [eventA],
       );
 
-      const eventB = { signature: 'hello', url: 'url', method: 'post' };
+      const eventB = { signature: 'url.post', url: 'url', method: 'post' };
       core.routeCoverage.discover(eventA); // check that we dedupe routes discoverd on startup
       core.routeCoverage.discover(eventB);
       core.routeCoverage.discover(eventB); // check that we dedupe routes defined lazily
@@ -105,7 +105,7 @@ describe('route coverage', function () {
         sourceInfo: undefined
       };
       core.routeCoverage.discover(event);
-      core.routeCoverage.observe({ url: 'url', method: 'get' });
+      core.routeCoverage.observe(event);
 
       expect(core.messages.emit).to.have.been.calledWith(
         Event.ROUTE_COVERAGE_OBSERVATION,
@@ -122,7 +122,7 @@ describe('route coverage', function () {
       core.routeCoverage.discover(event);
 
       simulateRequestScope(() => {
-        core.routeCoverage.observe({ url: 'url', method: 'get' });
+        core.routeCoverage.observe(event);
         const { sourceInfo, route } = core.scopes.sources.getStore();
         expect(sourceInfo).to.be.ok;
         expect(route).to.eql({ method: 'get', signature: 'hello', url: 'url' });

package/lib/install/{express.js → express/express4.js}

@@ -12,7 +12,6 @@
  * engineered, modified, repackaged, sold, redistributed or otherwise used in a
  * way not consistent with the End User License Agreement.
  */
-// @ts-check
 'use strict';
 
 const METHODS = [
@@ -27,7 +26,7 @@ const METHODS = [
 ];
 
 const fnInspect = require('@contrast/fn-inspect');
-const { createSignature, patchType } = require('../utils/route-info');
+const { createSignature, patchType } = require('../../utils/route-info');
 const { isString, primordials: { ArrayPrototypeJoin, StringPrototypeToLowerCase, StringPrototypeReplace, StringPrototypeReplaceAll, StringPrototypeSplit, StringPrototypeSlice } } = require('@contrast/common');
 
 // Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Express
@@ -113,7 +112,7 @@ module.exports = function init(core) {
       }
     });
   }
-  return core.routeCoverage.express = {
+  return core.routeCoverage.express4 = {
     install() {
       depHooks.resolve({ name: 'express', version: '>=4 <5' }, (express) => {
         patcher.patch(express.application, 'use', {

package/lib/install/{express.test.js → express/express4.test.js}

@@ -86,7 +86,7 @@ describe('route-coverage express', function () {
     core.depHooks.resolve.withArgs({ name: 'express', version: '>=4 <5' }).yields(express);
     core.depHooks.resolve.withArgs({ name: 'http' }).yields(http);
 
-    require('./express')(core).install();
+    require('./express4')(core).install();
   });
 
   describe('app', function () {

package/lib/install/express/express5.js

@@ -0,0 +1,256 @@
+/*
+ * Copyright: 2024 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 METHODS = [
+  'all',
+  'get',
+  'post',
+  'put',
+  'delete',
+  'patch',
+  'options',
+  'head',
+];
+const framework = 'express';
+const { patchType, createSignature } = require('../../utils/route-info');
+const {
+  isString,
+  primordials: {
+    ArrayPrototypeJoin,
+    ArrayPrototypeSlice,
+    StringPrototypeSplit,
+    StringPrototypeToLowerCase,
+    StringPrototypeReplace,
+    StringPrototypeSlice,
+    PathBasename
+  }
+} = require('@contrast/common');
+const { match } = require('path-to-regexp');
+const fnInspect = require('@contrast/fn-inspect');
+
+module.exports = function init(core) {
+
+  const discovered = [];
+  const routerMap = new Map();
+  const { patcher, depHooks, routeCoverage } = core;
+
+  const removeTrailingSlash = (url) => (url.endsWith('/') && url !== '/') ? StringPrototypeSlice.call(url, 0, -1) : url;
+  const format = (url) => Array.isArray(url)
+    ? `/[${ArrayPrototypeJoin.call(url)}]`
+    : removeTrailingSlash(url); // remove trailing slash
+  const isRouter = (layer) => layer?.name && StringPrototypeToLowerCase.call(layer.name) === 'router';
+
+  function getFnName({ method, file, lineNumber, column }) {
+    if (method) return method;
+    if (!file) return '(anonymous)';
+    const base = PathBasename(file);
+    return `(anonymous ${base} ${lineNumber}:${column})`;
+  }
+
+  function createRouteInfo(url, method, obj, fn) {
+    const fnInfo = fnInspect.funcInfo(fn);
+    const fnName = getFnName(fnInfo);
+    const originalUrl = url;
+    url = format(url);
+    return {
+      url,
+      method,
+      fnName,
+      framework,
+      originalUrl,
+      normalizedUrl: url,
+      signature: createSignature(url, method, obj, fnName)
+    };
+  }
+
+  function updateRouteInfo(prefix, routeInfo) {
+    const { url, normalizedUrl, fnName, method, addedPrefix = '' } = routeInfo;
+    const updatedUrl = removeTrailingSlash(prefix + url);
+    const updatedNormalizedUrl = removeTrailingSlash(prefix + normalizedUrl);
+    const updatedAddedPrefix = removeTrailingSlash(prefix + addedPrefix);
+    const updatedSignature = createSignature(updatedUrl, method, 'router', fnName);
+    return {
+      ...routeInfo,
+      url: updatedUrl,
+      addedPrefix: updatedAddedPrefix,
+      normalizedUrl: updatedNormalizedUrl,
+      signature: updatedSignature
+    };
+  }
+
+  function discover(routeInfo) {
+    const { url, normalizedUrl, signature, method, framework } = routeInfo;
+    if (!url || !normalizedUrl || !signature || !method || !framework) return;
+    routeCoverage.discover({
+      url,
+      normalizedUrl,
+      signature,
+      method,
+      framework
+    });
+
+    // Used to match urls during route observation
+    let urlToMatch = routeInfo.normalizedUrl;
+    if (Array.isArray(routeInfo.originalUrl)) {
+      const prefix = routeInfo?.addedPrefix || '';
+      urlToMatch = routeInfo.originalUrl.map(seg => prefix + seg);
+    }
+    const matchUrl = match(urlToMatch);
+    routeInfo.match = matchUrl;
+
+    discovered.push(routeInfo);
+  }
+
+  function wrapForObservation(handler, routeInfo, isRouter = false) {
+    const handlerInfo = fnInspect.funcInfo(handler);
+    const handlerName = getFnName(handlerInfo);
+    return patcher.patch(handler, {
+      name: 'handler',
+      patchType,
+      post(data) {
+        const [req] = data.args;
+        const [url] = StringPrototypeSplit.call(req.originalUrl, '?');
+        const method = StringPrototypeToLowerCase.call(req.method);
+        if (url && method) {
+          if (isRouter) {
+            for (const route of discovered) {
+              if (route.match(url) && route.fnName === handlerName) {
+                const { signature, normalizedUrl } = route;
+                routeCoverage.observe({ url, method, signature, framework, normalizedUrl });
+                break;
+              }
+            }
+          } else {
+            const { signature, normalizedUrl } = routeInfo;
+            routeCoverage.observe({ url, method, signature, framework, normalizedUrl });
+          }
+        }
+      }
+    });
+  }
+
+  return core.routeCoverage.express5 = {
+    install() {
+      depHooks.resolve({ name: 'express', version: '5' }, (express) => {
+        METHODS.forEach((method) => {
+          patcher.patch(express.application, method, {
+            name: `express.application.${method}`,
+            patchType,
+            pre(data) {
+              const [path, ...args] = data.args;
+              if ((!isString(path) && !Array.isArray(path)) || path === '') return;
+
+              const fns = args.flat(Infinity);
+              for (let i = 0; i < fns.length; i++) {
+                if (typeof fns[i] !== 'function') continue;
+                const routeInfo = createRouteInfo(path, method, 'app', fns[i]);
+
+                discover(routeInfo);
+                fns[i] = wrapForObservation(fns[i], routeInfo);
+              }
+              data.args.splice(1, fns.length, ...fns);
+            }
+          });
+
+          patcher.patch(express.Router.prototype, method, {
+            name: `express.Router.prototype.${method}`,
+            patchType,
+            pre(data) {
+              const Router = data.obj;
+              const [path, ...args] = data.args;
+              if (!isString(path) && !Array.isArray(path)) return;
+
+              const fns = args.flat(Infinity);
+              const routes = routerMap.get(Router) || [];
+              for (let i = 0; i < fns.length; i++) {
+                if (typeof fns[i] !== 'function') continue;
+                const routeInfo = createRouteInfo(path, method, 'router', fns[i]);
+
+                fns[i] = wrapForObservation(fns[i], routeInfo, true);
+
+                routes.push(routeInfo);
+                data.args.splice(1, fns.length, ...fns);
+              }
+              routerMap.set(Router, routes);
+            }
+          });
+        });
+
+        let appRouter;
+        patcher.patch(express.application, 'use', {
+          name: 'express.application.use',
+          patchType,
+          pre(data) {
+            appRouter = data.obj.router;
+
+            const arg0 = data.args[0];
+            const prefix = (Array.isArray(arg0) || isString(arg0)) ? arg0 : undefined;
+            const args = prefix ? ArrayPrototypeSlice.call(data.args, 1) : data.args;
+            const fns = args.flat(Infinity);
+            for (let i = 0; i < fns.length; i++) {
+              if (isRouter(fns[i])) {
+                let routes = routerMap.get(fns[i]);
+                if (routes) {
+                  if (prefix) routes = routes.map(route => updateRouteInfo(prefix, route));
+                  routes.forEach((route) => discover(route));
+                }
+              } else if (prefix && typeof fns[i] === 'function') {
+                const routeInfo = createRouteInfo(prefix, 'use', 'app', fns[i]);
+                discover(routeInfo);
+                fns[i] = wrapForObservation(fns[i], routeInfo);
+              }
+            }
+            data.args.splice(prefix ? 1 : 0, fns.length, ...fns);
+          }
+        });
+        patcher.patch(express.Router.prototype, 'use', {
+          name: 'express.Router.prototype.use',
+          patchType,
+          pre(data) {
+            const Router = data.obj;
+            const isAppRouter = Router === appRouter;
+            if (isAppRouter) return;
+
+            let routerRoutes = routerMap.get(Router) || [];
+
+            const arg0 = data.args[0];
+            let prefix = (Array.isArray(arg0) || isString(arg0)) ? arg0 : undefined;
+            const args = prefix ? ArrayPrototypeSlice.call(data.args, 1) : data.args;
+            const fns = args.flat(Infinity);
+
+            for (let i = 0; i < fns.length; i++) {
+              const selfNested = fns[i] === Router;
+              if (isRouter(fns[i])) {
+                let routes = routerMap.get(fns[i]) || [];
+                if (prefix) {
+                  if (selfNested) prefix = StringPrototypeReplace.call(prefix, '/', '/*');
+                  routes = routes.map(route => updateRouteInfo(prefix, route));
+                }
+                routerRoutes = selfNested ? routes : routerRoutes.concat(routes);
+              } else if (prefix && typeof fns[i] === 'function') {
+                const routeInfo = createRouteInfo(prefix, 'use', 'router', fns[i]);
+                routerRoutes.push(routeInfo);
+                fns[i] = wrapForObservation(fns[i], routeInfo);
+              }
+            }
+            routerMap.set(Router, routerRoutes);
+            data.args.splice(prefix ? 1 : 0, fns.length, ...fns);
+          }
+        });
+      });
+    }
+  };
+};