@contrast/route-coverage 1.20.6 → 1.21.0

package/lib/index.js

@@ -37,7 +37,6 @@ module.exports = function init(core) {
   const routeCoverage = core.routeCoverage = {
     discover(info) {
       routeInfo.set(routeIdentifier(info), info);
-      messages.emit(Event.ROUTE_COVERAGE_DISCOVERY, info);
     },
 
     delete(info) {

package/lib/install/express.js

@@ -30,6 +30,7 @@ const fnInspect = require('@contrast/fn-inspect');
 const { createSignature, patchType } = require('../utils/route-info');
 const { ArrayPrototypeJoin, StringPrototypeToLowerCase, isString } = require('@contrast/common');
 
+// Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Express
 module.exports = function init(core) {
   const { patcher, depHooks, routeCoverage } = core;
   const discover = (route) => routeCoverage.discover(route);

package/lib/install/fastify.js

@@ -12,99 +12,116 @@
  * engineered, modified, repackaged, sold, redistributed or otherwise used in a
  * way not consistent with the End User License Agreement.
  */
-// @ts-check
 'use strict';
 
-const { createSignature } = require('./../utils/route-info');
-const { StringPrototypeToLowerCase } = require('@contrast/common');
+const { StringPrototypeToLowerCase, isString } = require('@contrast/common');
+const { getFastifyMethods } = require('./../utils/methods');
+const { patchType } = require('./../utils/route-info');
 
-/** @typedef {Parameters<import('fastify-3.0.0').onRouteHookHandler>[0]} RouteOptions */
-
-/**
- * @param {import('..').Core & {
- *  routeCoverage: import('..').RouteCoverage & {
- *    fastify?: import('@contrast/common').Installable
- *  }
- * }} core
- */
+// Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Fastify
 module.exports = function init(core) {
+  /*
+   Fastify has two ways of defining routes:
+   1. fastify.route({ method: '<method>', url: '<url>', handler: <fn> })
+   2. fastify.<method>('<url>', <fn>)
+   (See NODE-3483 for more detail)
+  We need a way to keep track of which routes were fully declared using .route
+  So, we instrument the route method below and add identifying info to this array
+ */
+  const fullyDeclaredRoutes = [];
   const { patcher, depHooks, routeCoverage } = core;
 
-  /** @param {RouteOptions} routeOptions */
-  function registerRouteHandler(routeOptions) {
-    if (!routeOptions || !routeOptions.method || !routeOptions.url) return;
-
-    const { url, method } = routeOptions;
-    if (Array.isArray(method)) {
-      method.forEach((method) => {
-        emitRouteCoverage(url, method);
-      });
-    } else {
-      emitRouteCoverage(url, method);
+  const isFullyDeclared = (method, url) => isString(method) && fullyDeclaredRoutes.includes(method + url);
+  function fullyDeclare(method, url) {
+    if (isString(method)) {
+      fullyDeclaredRoutes.push(method + url);
+      if (method === 'GET') fullyDeclaredRoutes.push(`HEAD${url}`);
     }
-
-    // TODO
-    observationListener(routeOptions, url);
-  }
-
-  /**
-   * @param {RouteOptions} routeOptions
-   * @param {string} url
-   */
-  function observationListener(routeOptions, url) {
-    patcher.patch(routeOptions, 'handler', {
-      name: 'fastify.routeOptions.handler',
-      patchType: 'route-coverage',
-      pre(data) {
-        const [request] = data.args;
-        const { method } = request.raw;
-        const [parsedUrl] = request.url.split(/\?/);
-        emitObservation(parsedUrl, url, method);
-      },
-    });
   }
 
-  /**
-   * @param {string} url
-   * @param {string} method
-   */
-  function emitRouteCoverage(url, method) {
+  function createRouteInfo(method, url, routePath) {
+    const fullyDeclared = isFullyDeclared(method, routePath);
     method = StringPrototypeToLowerCase.call(method);
-    const event = { signature: createSignature(url, method), url, method, normalizedUrl: url, framework: 'fastify' };
-    routeCoverage.discover(event);
-  }
 
-  /**
-   * @param {string} url
-   * @param {string} normalizedUrl
-   * @param {string=} method
-   */
-  function emitObservation(url, normalizedUrl, method) {
-    method = method && StringPrototypeToLowerCase.call(method);
-    routeCoverage.observe({ method, url, normalizedUrl });
+    const signature = fullyDeclared
+      ? `fastify.route({ method: '${method}', url: '${url}', handler: [Function] })`
+      : `fastify.${method}('${url}', [Function])`;
+
+    const routeInfo = {
+      signature,
+      url,
+      method,
+      normalizedUrl: url,
+      framework: 'fastify'
+    };
+    return routeInfo;
   }
 
   return core.routeCoverage.fastify = {
     install() {
-      depHooks.resolve(
-        { name: 'fastify', version: '>=3.0.0' },
-        /** @param {import("fastify-3.0.0").fastify} fastify */
-        (fastify) =>
-          patcher.patch(fastify, {
-            name: 'fastify.build',
-            patchType: 'route-coverage',
-            post({ result: server }) {
-              server.addHook('onRoute', (routeOptions) => {
-                registerRouteHandler(routeOptions);
-              });
+      // The routePath property used below was introduced in 3.2.0
+      return depHooks.resolve({ name: 'fastify', version: '>=3.2.0' }, (fastify) => patcher.patch(fastify, {
+        name: 'fastify',
+        patchType,
+        post({ result: server }) {
+          patcher.patch(server, 'route', {
+            name: 'server.route',
+            patchType,
+            pre({ args }) {
+              const [{ method, url }] = args;
+              if (!isString(url)) return;
+
+              if (Array.isArray(method)) {
+                method.forEach((verb) => {
+                  fullyDeclare(verb, url);
+                });
+              } else {
+                fullyDeclare(method, url);
+              }
+            }
+          });
+          server.addHook('onRoute', (routeOptions) => {
+            if (!routeOptions) return;
+
+            const { method, url, routePath } = routeOptions;
+            if (!method || !url || !routePath || !isString(routePath)) return;
+
+            let routeInfo;
+            const FASTIFY_METHODS = getFastifyMethods(server.version);
+            if (Array.isArray(method)) {
+              // If a route was defined using .all this method property will be an
+              // array of all methods supported by Fastify
+              if (FASTIFY_METHODS.every(m => method.includes(m))) {
+                routeInfo = createRouteInfo('all', url, routePath);
+                routeCoverage.discover(routeInfo);
+              } else {
+                method.forEach((verb) => {
+                  routeInfo = createRouteInfo(verb, url, routePath);
+                  routeCoverage.discover(routeInfo);
+                });
+              }
+            } else {
+              routeInfo = createRouteInfo(method, url, routePath);
+              routeCoverage.discover(routeInfo);
+            }
 
-              server.addHook('onReady', (done) => {
-                routeCoverage.discoveryFinished();
-                return done();
-              });
-            },
-          }),
-      );
+            patcher.patch(routeOptions, 'handler', {
+              name: 'fastify.routeOptions.handler',
+              patchType,
+              pre({ args }) {
+                const [req] = args;
+                const method = StringPrototypeToLowerCase.call(req.raw?.method);
+                const [url] = req.url.split(/\?/);
+                routeCoverage.observe({ ...routeInfo, url, method });
+              },
+            });
+          });
+          server.addHook('onReady', (done) => {
+            routeCoverage.discoveryFinished();
+            return done();
+          });
+        }
+      }));
     }
   };
 };

package/lib/install/hapi.js

@@ -15,14 +15,21 @@
 'use strict';
 
 const { StringPrototypeToLowerCase } = require('@contrast/common');
-const { createSignature, patchType } = require('./../utils/route-info');
+const { patchType } = require('./../utils/route-info');
 
+// Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Hapi
 module.exports = function init(core) {
   const { patcher, depHooks, routeCoverage } = core;
 
   function emitRouteCoverage(url, method) {
     method = StringPrototypeToLowerCase.call(method);
-    const event = { signature: createSignature(url, method), url, method, normalizedUrl: url, framework: 'hapi' };
+    const event = {
+      signature: `server.route({ method: '${method}', path: '${url}', handler: [Function] })`,
+      url,
+      method,
+      normalizedUrl: url,
+      framework: 'hapi'
+    };
     routeCoverage.discover(event);
   }
 

package/lib/install/koa.js

@@ -14,56 +14,76 @@
  */
 'use strict';
 
-const { StringPrototypeToLowerCase } = require('@contrast/common');
+const { METHODS } = require('./../utils/methods');
+const { StringPrototypeToLowerCase, isString } = require('@contrast/common');
 const { createSignature, patchType } = 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 emitRouteCoverage(url, method) {
-    const event = { signature: createSignature(url, method), url, method, normalizedUrl: url, framework: 'koa' };
-    routeCoverage.discover(event);
-  }
-
-  const routeObservationPathClosure = ({ path }) =>
-    async function routeObservationMiddleware(ctx, next) {
-      const req = ctx.request;
-
-      if (req) {
-        const { url: reqUrl, method } = req;
-        const [url] = reqUrl.split(/\?/);
-        routeCoverage.observe({ url, method: StringPrototypeToLowerCase.call(method || ''), normalizedUrl: path });
-      }
-
-      await next();
+  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() {
-      ['@koa/router', 'koa-router'].forEach((name) => {
-        depHooks.resolve({ name }, (_export) => {
-          if (!_export?.prototype?.register) return;
+      depHooks.resolve({ name: 'koa', version: '>=2.3.0' }, (Koa) => {
+        // 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
+        // instrumenting the routing library
+        patcher.patch(Koa.prototype, 'use', {
+          name: 'Koa.prototype.use',
+          patchType,
+          pre: ({ args }) => {
+            if (args?.length === 0) return;
+            const [router] = args;
 
-          patcher.patch(_export.prototype, 'register', {
-            name: 'koaRouter.prototype',
-            patchType,
-            post: ({ args, result: layer }) => {
-              const [path, methods] = args;
-              if (!path || !methods || Array.isArray(path)) {
-                return;
-              }
+            if (!router?.router) return;
 
+            router.router.stack.forEach((Layer) => {
+              const { methods, path } = Layer;
+              if (!path || !isString(path)) return;
+
+              let routeInfo;
               if (methods.length === 0) {
-                emitRouteCoverage(path, 'use');
+                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);
+                routeCoverage.discover(routeInfo);
               } else {
                 methods.forEach((method) => {
-                  emitRouteCoverage(path, StringPrototypeToLowerCase.call(method || ''));
+                  routeInfo = createRouteInfo(method, path);
+                  routeCoverage.discover(routeInfo);
                 });
               }
 
-              layer.stack.unshift(routeObservationPathClosure({ path }).bind(this));
-            }
-          });
+              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] = reqUrl.split(/\?/);
+                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];
+            });
+          }
         });
       });
     }

package/lib/install/restify.js

@@ -17,6 +17,7 @@
 const { StringPrototypeToLowerCase, isString } = require('@contrast/common');
 const { createSignature, patchType } = require('../utils/route-info');
 
+// Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Restify
 module.exports = function init(core) {
   const { patcher, depHooks, routeCoverage } = core;
   const discover = (route) => routeCoverage.discover(route);
@@ -25,7 +26,7 @@ module.exports = function init(core) {
   function createRoute(url, method) {
     method = StringPrototypeToLowerCase.call(method);
     return {
-      signature: createSignature(url, method, 'Server'),
+      signature: createSignature(url, method, 'server'),
       method,
       url,
       normalizedUrl: url,

package/lib/utils/methods.js

@@ -0,0 +1,45 @@
+/*
+ * 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';
+
+// eslint-disable-next-line node/no-extraneous-require
+const semver = require('semver');
+const { METHODS } = require('http');
+
+function getFastifyMethods(version) {
+  return [
+    'DELETE',
+    'GET',
+    'HEAD',
+    'PATCH',
+    'POST',
+    'PUT',
+    'OPTIONS',
+    ...semver.gte(version, '4.4.0') ?
+        [
+          'PROPFIND',
+          'PROPPATCH',
+          'MKCOL',
+          'COPY',
+          'MOVE',
+          'LOCK',
+          'UNLOCK',
+          'TRACE',
+          'SEARCH'
+        ] : []
+  ];
+}
+
+module.exports = { getFastifyMethods, METHODS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/route-coverage",
-  "version": "1.20.6",
+  "version": "1.21.0",
   "description": "Handles route discovery and observation",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -17,7 +17,7 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.21.2",
+    "@contrast/common": "1.22.0",
     "@contrast/fn-inspect": "^4.0.0"
   }
 }