@contrast/route-coverage 1.3.0 → 1.4.0

package/lib/index.d.ts

@@ -13,11 +13,26 @@
  * way not consistent with the End User License Agreement.
  */
 
-export interface RouteCoverage {
-  discover: (infos: { signature: string, url: string, method: string }) => void
-  observe: (data: { url: string, verb: string }) => void
+import { Installable, Messages, RouteInfo } from '@contrast/common';
+import { Logger } from '@contrast/logger';
+import { Patcher } from '@contrast/patcher';
+import RequireHook from '@contrast/require-hook';
+
+export { RouteInfo };
+
+export interface RouteCoverage extends Installable {
+  discover(info: RouteInfo): void;
+  discoveryFinished(): void;
+  observe(info: Pick<RouteInfo, 'method' | 'url'>): void;
+}
+
+export interface Core {
+  readonly depHooks: RequireHook;
+  readonly logger: Logger;
+  readonly messages: Messages;
+  readonly patcher: Patcher;
 }
 
-declare function init(core: any): RouteCoverage;
+declare function init(core: Core): RouteCoverage;
 
 export = init;

package/lib/index.js

@@ -12,42 +12,60 @@
  * engineered, modified, repackaged, sold, redistributed or otherwise used in a
  * way not consistent with the End User License Agreement.
  */
+// @ts-check
 'use strict';
 
 const { callChildComponentMethodsSync, Event } = require('@contrast/common');
 const { routeIdentifier } = require('./utils/route-info');
 
-module.exports = function(core) {
-  const { logger, messages } = core;
+/**
+ * @param {import('.').Core & {
+ *  routeCoverage: import('.').RouteCoverage
+ * }} core
+ */
+module.exports = function init(core) {
+  const { logger, messages, scopes } = core;
 
-  const routeCoverage = core.routeCoverage = {};
+  /** @type {Map<string, import('@contrast/common').RouteInfo} */
   const routeInfo = new Map();
 
-  const discover = (info) => {
-    routeInfo.set(routeIdentifier(info), info);
-    messages.emit(Event.ROUTE_COVERAGE_DISCOVERY, info);
-  };
+  core.routeCoverage = {
+    discover(info) {
+      routeInfo.set(routeIdentifier(info), info);
+      messages.emit(Event.ROUTE_COVERAGE_DISCOVERY, info);
+    },
 
-  const observe = ({ url, verb }) => {
-    const info = { url, verb };
+    discoveryFinished() {
+      const routes = Array.from(routeInfo.values());
+      messages.emit(Event.ROUTE_COVERAGE_DISCOVERY_FINISHED, routes);
+    },
 
-    const route = routeInfo.get(routeIdentifier({ url, method: verb }));
-    if (!route) {
-      logger.debug('Unable to observe routes not discovered %j', info);
-      return null;
-    }
+    observe(info) {
+      const route = routeInfo.get(routeIdentifier(info));
 
-    messages.emit(Event.ROUTE_COVERAGE_OBSERVATION, route);
-  };
+      if (!route) {
+        logger.debug(info, 'unable to observe undiscovered route');
+        return;
+      }
 
-  routeCoverage.discover = discover;
-  routeCoverage.observe = observe;
+      const store = scopes.sources.getStore();
+      if (store && !store.route) {
+        store.route = route;
+      }
+      // these events need source correlation
+      messages.emit(Event.ROUTE_COVERAGE_OBSERVATION, {
+        ...route,
+        sourceInfo: store?.sourceInfo,
+      });
+    },
 
-  require('./install/fastify')(core);
-
-  routeCoverage.install = function () {
-    callChildComponentMethodsSync(routeCoverage, 'install');
+    install() {
+      callChildComponentMethodsSync(this, 'install');
+    },
   };
 
-  return routeCoverage;
+  require('./install/fastify')(core);
+  require('./install/koa')(core);
+
+  return core.routeCoverage;
 };

package/lib/install/fastify.js

@@ -12,15 +12,24 @@
  * 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');
 
-module.exports = function (core) {
-  const { patcher, depHooks, routeCoverage } = core;
+/** @typedef {Parameters<import('fastify3.0.0').onRouteHookHandler>[0]} RouteOptions */
 
-  const routeCoverageFastify = core.routeCoverage.fastify = {};
+/**
+ * @param {import('..').Core & {
+ *  routeCoverage: import('..').RouteCoverage & {
+ *    fastify?: import('@contrast/common').Installable
+ *  }
+ * }} core
+ */
+module.exports = function init(core) {
+  const { patcher, depHooks, routeCoverage } = core;
 
+  /** @param {RouteOptions} routeOptions */
   function registerRouteHandler(routeOptions) {
     if (!routeOptions || !routeOptions.method || !routeOptions.url) return;
 
@@ -37,6 +46,10 @@ module.exports = function (core) {
     observationListener(routeOptions, url);
   }
 
+  /**
+   * @param {RouteOptions} routeOptions
+   * @param {string} url
+   */
   function observationListener(routeOptions, url) {
     patcher.patch(routeOptions, 'handler', {
       name: 'fastify.routeOptions.handler',
@@ -44,35 +57,53 @@ module.exports = function (core) {
       pre(data) {
         const [request] = data.args;
         const { method } = request.raw;
-        emitObservation(method, url);
+        emitObservation(url, method);
       },
     });
   }
 
+  /**
+   * @param {string} url
+   * @param {string} method
+   */
   function emitRouteCoverage(url, method) {
     method = method.toLowerCase();
     const event = { signature: createSignature(url, method), url, method };
     routeCoverage.discover(event);
   }
 
-  function emitObservation(verb, url) {
-    verb = verb.toLowerCase();
-    routeCoverage.observe({ verb, url });
+  /**
+   * @param {string} url
+   * @param {string=} method
+   */
+  function emitObservation(url, method) {
+    method = method?.toLowerCase();
+    routeCoverage.observe({ method, url });
   }
 
-  routeCoverageFastify.install = function() {
-    depHooks.resolve({ name: 'fastify', version: '>=3.0.0' }, (fastify) =>
-      patcher.patch(fastify, {
-        name: 'fastify.build',
-        patchType: 'route-coverage',
-        post({ orig, hooked, result: server }) {
-          server.addHook('onRoute', function (routeOptions) {
-            registerRouteHandler(routeOptions);
-          });
-        },
-      })
-    );
+  core.routeCoverage.fastify = {
+    install() {
+      depHooks.resolve(
+        { name: 'fastify', version: '>=3.0.0' },
+        /** @param {import("fastify3.0.0").fastify} fastify */
+        (fastify) =>
+          patcher.patch(fastify, {
+            name: 'fastify.build',
+            patchType: 'route-coverage',
+            post({ result: server }) {
+              server.addHook('onRoute', (routeOptions) => {
+                registerRouteHandler(routeOptions);
+              });
+
+              server.addHook('onReady', (done) => {
+                routeCoverage.discoveryFinished();
+                return done();
+              });
+            },
+          }),
+      );
+    }
   };
 
-  return routeCoverageFastify;
+  return core.routeCoverage.fastify;
 };

package/lib/install/koa.js

@@ -0,0 +1,90 @@
+/*
+ * Copyright: 2022 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 { createSignature, patchType } = require('./../utils/route-info');
+
+module.exports = function init(core) {
+  const { patcher, depHooks, routeCoverage, logger } = core;
+
+  function emitRouteCoverage(url, method) {
+    const event = { signature: createSignature(url, method), url, method };
+    routeCoverage.discover(event);
+  }
+
+  function emitObservation(url, method) {
+    routeCoverage.observe({ method, url });
+  }
+
+  async function routeObservationMiddleware(ctx, next) {
+    const req = ctx.request;
+
+    if (req) {
+      const { url, method } = req;
+      try {
+        // Arbitrary basename needed to parse out path
+        const parsedUrl = new URL(url, 'file://').pathname;
+        emitObservation(parsedUrl, method.toLowerCase());
+      } catch (err) {
+        logger.error({ err, url }, 'failed to parse route');
+      }
+    }
+
+    await next();
+  }
+
+  function registerRouteHandler(Router) {
+    patcher.patch(Router.prototype, 'register', {
+      name: 'koaRouter.prototype',
+      patchType,
+      post: ({ args, result: layer }) => {
+        const [path, methods] = args;
+        if (!path || !methods || Array.isArray(path)) {
+          return;
+        }
+
+        if (methods.length === 0) {
+          emitRouteCoverage(path, 'use');
+        } else {
+          methods.forEach((method) => {
+            emitRouteCoverage(path, method.toLowerCase());
+          });
+        }
+
+        layer.stack.unshift(routeObservationMiddleware.bind(this));
+      }
+    });
+
+    patcher.patch(Router.prototype, 'routes', {
+      name: 'koaRouter.prototype',
+      patchType,
+      post: () => {
+        routeCoverage.discoveryFinished();
+      }
+    });
+  }
+
+  core.routeCoverage.koa = {
+    install() {
+      ['@koa/router', 'koa-router'].forEach((name) => {
+        depHooks.resolve(
+          { name }, registerRouteHandler.bind(this)
+        );
+      });
+    }
+  };
+
+  return core.routeCoverage.koa;
+};

package/lib/utils/route-info.js

@@ -14,10 +14,12 @@
  */
 'use strict';
 
+const patchType = 'route-coverage';
+
 /**
  * Creates a formatted "signature" for a route
  * @param {string} path
- * @param {Array} [methods=['get']]
+ * @param {string} method
  * @return {string} formatted signature
  */
 function createSignature(path, method) {
@@ -26,9 +28,9 @@ function createSignature(path, method) {
 
 /**
  * Creates a route identifier based on the method name and the url
- * @param {Object} Route Information
+ * @param {Pick<import('../index').RouteInfo, 'method' | 'url'>} info
  * @return {string}
  */
 const routeIdentifier = (info) => `${info.method}.${info.url}`;
 
-module.exports = { createSignature, routeIdentifier };
+module.exports = { createSignature, routeIdentifier, patchType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/route-coverage",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -14,6 +14,6 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.7.0"
+    "@contrast/common": "1.8.0"
   }
 }