@contrast/route-coverage 1.51.0 → 1.53.0

package/lib/install/express/express5.js

@@ -1,553 +0,0 @@
-/*
- * 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 { AsyncLocalStorage } = require('node:async_hooks');
-const {
-  get,
-  set,
-  isString,
-  Event,
-  RouteType,
-  primordials: {
-    ArrayPrototypeJoin,
-    StringPrototypeSubstring,
-    StringPrototypeToLowerCase,
-    StringPrototypeReplace,
-  }
-} = require('@contrast/common');
-const { funcInfo } = require('@contrast/fn-inspect');
-const Core = require('@contrast/core/lib/ioc/core');
-
-const METHODS = [
-  'all',
-  'get',
-  'post',
-  'put',
-  'delete',
-  'patch',
-  'options',
-  'head',
-];
-const componentName = 'routeCoverage.express5';
-const kMetaKey = Symbol('cs_meta');
-const enumerable = false;
-
-module.exports = Core.makeComponent({
-  name: componentName,
-  factory: (core) => new ExpressInstrumentation(core),
-});
-
-class ExpressInstrumentation {
-  constructor(core) {
-    // decorate
-    set(core, componentName, this);
-
-    this.core = core;
-    this.methodScope = new AsyncLocalStorage();
-    this.handleScope = new AsyncLocalStorage();
-  }
-
-  install() {
-    const self = this;
-    const { core, handleScope, methodScope } = this;
-    const patchType = 'route-coverage-express';
-    const name = 'express-5';
-
-    //
-    // discovery instrumentation
-    //
-
-    core.depHooks.resolve({ name: 'express', version: '5' }, (express) => {
-      // wrap router and app methods in "method scope" to capture info to help build signatures.
-      // express has a number of APIs that work at different levels of abstraction, and we need to patch
-      // all of them. the scopes let us know what top-level APIs are being called by application code.
-      [...METHODS, 'use', 'route'].forEach((method) => {
-        // then setup app and router to run in method scopes
-        core.patcher.patch(express.application, method, {
-          name: `express.application.${method}`,
-          patchType: `${patchType}-discovery`,
-          around(next, data) {
-            if (methodScope.getStore()) return next();
-            return methodScope.run({ method, args: data.args, type: 'app' }, next);
-          }
-        });
-
-        core.patcher.patch(express.Router.prototype, method, {
-          name: `express.Router.prototype.${method}`,
-          patchType: `${patchType}-discovery`,
-          around(next, data) {
-            if (methodScope.getStore()) return next();
-            return methodScope.run({ method, args: data.args, type: 'router' }, next);
-          }
-        });
-      });
-
-      // app[method] and router[method] end up calling this
-      // Append metadata to the created Route object at layer.route.
-      // we also patch the returned Route's methods for building signatures
-      core.patcher.patch(express.Router.prototype, 'route', {
-        name: 'express.Route',
-        patchType: `${patchType}-discovery`,
-        post(data) {
-          const { result } = data;
-          const methodStore = methodScope.getStore();
-          const meta = {
-            paths: ExpressInstrumentation.normalizePaths(data.args[0]),
-            method: methodStore?.method,
-            type: methodStore?.type || 'route',
-          };
-
-          Object.defineProperty(result, kMetaKey, {
-            enumerable,
-            value: meta
-          });
-
-          // patch route instance methods we do that here when we have
-          // todo move to prototype to help w/ memory
-          METHODS.forEach((method) => {
-            if (result[method]) {
-              core.patcher.patch(result, method, {
-                name: `express.Router.prototype.route${method}`,
-                patchType: `${patchType}-discovery`,
-                pre(data) {
-                  data._stackIdx = data.obj.stack?.length;
-                },
-                post(data) {
-                  if (data.obj.stack?.length > data._stackIdx) {
-                    for (let i = data._stackIdx; i < data.obj.stack.length; i++) {
-                      const layer = data.obj.stack[i];
-                      const methodStore = methodScope.getStore();
-                      const meta = {
-                        type: methodStore?.type || 'route',
-                        method: methodStore?.method == 'all' ? 'all' : method,
-                      };
-
-                      Object.defineProperty(layer, kMetaKey, {
-                        enumerable,
-                        value: meta,
-                      });
-                    }
-                  }
-                },
-              });
-            }
-          });
-
-          return result;
-        },
-      });
-
-      core.patcher.patch(express.Router.prototype, 'use', {
-        name: `${name}.Router.prototype.use`,
-        patchType: `${patchType}-discovery`,
-        pre(data) {
-          data._stackLength = data.obj.stack?.length;
-        },
-        post(data) {
-          if (data.obj.stack.length > data._stackLength) {
-            for (let i = data._stackLength; i < data.obj.stack.length; i++) {
-              const layer = data.obj.stack[i];
-              const paths = ExpressInstrumentation.normalizePaths(data.args[0]);
-              const methodStore = methodScope.getStore();
-              const meta = {
-                paths,
-                method: 'use',
-                type: methodStore?.type || 'router',
-              };
-
-              if (layer) {
-                Object.defineProperty(layer, kMetaKey, {
-                  enumerable: false,
-                  value: meta
-                });
-              }
-            }
-          }
-        },
-      });
-
-      return core.patcher.patch(express, {
-        name: 'express-5.application',
-        patchType: `${patchType}-discovery`,
-        post(data) {
-          const app = data.result;
-          core.messages.on(Event.SERVER_LISTENING, () => {
-            if (!app.router.stack[0]) {
-              core.logger.debug('no routes detected in express router stack');
-              return;
-            }
-            self.handleDiscovery(app);
-          });
-          return app;
-        }
-      });
-    });
-
-    core.depHooks.resolve({ name: 'express', version: '5' }, (express) => {
-      core.patcher.patch(express.application, 'handle', {
-        name: 'express.application.handle',
-        patchType: `${patchType}-discovery`,
-        around(next, data) {
-          // wrap request handling in "handle scope". the scope's store data
-          // helps for building observation templates as routing occurs
-          const store = {
-            matchIdx: -1,
-            templateSegments: [],
-          };
-          return handleScope.run(store, next);
-        }
-      });
-    });
-
-    //
-    // observation instrumentation
-    //
-
-    // when Layer.match gets called, matchers functions run underneath. the API doesn't present a really clean
-    // way to instrument, so we're using scopes. we reference the scope's store in the instrumented matcher
-    // functions so we can correlate a matcher that succeeds to its corresponding route template segment.
-    core.depHooks.resolve({ name: 'router', file: 'lib/layer.js', version: '2' }, (Layer) => {
-      core.patcher.patch(Layer.prototype, 'match', {
-        name: 'Layer.prototype.match',
-        patchType: `${patchType}-observation`,
-        pre(data) {
-          data._store = handleScope.getStore();
-          if (!data._store) return;
-
-          // we check in post hook whether any matcher instrumentation reset this in scope.
-          // matchers will set this to a number only if multiple matchers run and one succeeds.
-          // use the index of that matcher to get associated template segment from the metadata.
-          data._store.matcherIdx = null;
-          // save reference to metadata source
-          data[kMetaKey] = data.obj[kMetaKey] || data.obj.route?.[kMetaKey];
-        },
-        post(data) {
-          // whenever a layer matches, save the corresponding
-          // template segment metadata in the handle scope store
-          const { result } = data;
-          if (!result || !data._store || !data[kMetaKey]?.paths) return;
-
-          let template;
-          if (data._store.matcherIdx != null) {
-            template = data[kMetaKey].paths[data._store.matcherIdx];
-          } else {
-            template = data[kMetaKey].paths[0];
-          }
-
-          // if the layer matches, we know to push corresponding path to store's template segments.
-          // we pop this value from the array in hook to all `next` callbacks below.
-          data._store.templateSegments.push(template);
-        }
-      });
-
-      // patch the `next` callback of every Layer's request handler.
-      // we pop the value from the stack of route template segments being managed.
-      core.patcher.patch(Layer.prototype, 'handleRequest', {
-        name: 'Layer.prototype.handleRequest',
-        patchType: `${patchType}-observation`,
-        pre(data) {
-          const next = data.args[2];
-          const meta = data.obj[kMetaKey] || data.obj.route?.[kMetaKey];
-          if (meta?.paths) {
-            const store = handleScope.getStore();
-            // this runs often and there's no need to use patcher here. monkey patch directly to optimize
-            data.args[2] = function(...args) {
-              if (store) store.templateSegments.pop();
-              const ret = next(...args);
-              return ret;
-            };
-          }
-        }
-      });
-
-      // instrument the Layer constructor. this will allow us to patch
-      // created matchers to help us build observation template from metadata.
-      // if matcher was successful we store index of it in handle scope.
-      return core.patcher.patch(Layer, {
-        name: 'router.Layer',
-        patchType: `${patchType}-observation`,
-        pre(data) {
-          data._methodScope = methodScope.getStore();
-        },
-        post(data) {
-          const instance = data.result;
-          // only instrument matchers if the Layer is being instantiated within method scope, and
-          // if there are multiple matchers and we need the index to correlate to tempate segment
-          if (data._methodScope && instance.matchers.length > 1) {
-            for (let i = 0; i < instance.matchers.length; i++) {
-              const matcher = instance.matchers[i];
-              instance.matchers[i] = function(...args) {
-                const result = matcher.apply(this, args);
-                if (result) {
-                  const store = handleScope.getStore();
-                  if (store) store.matcherIdx = i;
-                }
-                return result;
-              };
-            }
-          }
-          // patch handle to report observation when called. it checks handle
-          // scope to get current request's template to match with discovery info
-          core.patcher.patch(instance, 'handle', {
-            name: 'router.Layer.handle',
-            patchType: `${patchType}-observation`,
-            pre(data) {
-              if (instance[kMetaKey]?.observables) {
-                const store = handleScope.getStore();
-                if (store) {
-                  const method = StringPrototypeToLowerCase.call(data.args[0].method || '');
-                  const template = ArrayPrototypeJoin.call(store.templateSegments, '') || '/';
-
-
-                  if (instance[kMetaKey]?.observables?.[template]) {
-                    self.observe({
-                      url: data.args[0].originalUrl,
-                      normalizedUrl: template,
-                      method,
-                      signature: instance[kMetaKey].observables[template],
-                      type: instance[kMetaKey].routeType,
-                    });
-                  } else {
-                    core.logger.error({
-                      // url: data.args[0].originalUrl, // this would need masking to log
-                      method,
-                      template,
-                      observables: instance[kMetaKey]?.observables,
-                    }, 'unable to map route template to signature');
-                  }
-                }
-              }
-            },
-          });
-        },
-      });
-    });
-  }
-
-  discover(info) {
-    const { method, observables, routeType } = info;
-    if (!method || !observables) return;
-
-    for (const [normalizedUrl, signature] of Object.entries(observables)) {
-      this.core.routeCoverage.discover({
-        url: normalizedUrl,
-        normalizedUrl,
-        method,
-        signature,
-        type: routeType,
-        framework: 'express',
-      });
-    }
-  }
-
-  observe(info) {
-    this.core.routeCoverage.observe({ framework: 'express', ...info });
-  }
-
-  /**
-   * Traverse the application's router "stack" and generate route discovery events
-   * using layer/route metadata that was appended by methods like router.post().
-   * @param {object} app express instance
-   */
-  handleDiscovery(app) {
-    const self = this;
-    const router = app.router || app._router;
-
-    // traverse fn executes this callback when visiting Layer instances
-    this.traverse(router, (path, key, value, target, state) => {
-      if (value.stack?.length > 0 || value.route) return;
-
-      // get metadata for this Layer
-      // metadata is on Layers within stacks and on Routes instances.
-      const metas = [];
-      for (let i = 0; i < path.length; i++) {
-        const seg = path[i];
-        if (Number.isFinite((Number(seg))) || seg == 'route') {
-          const metaPath = ArrayPrototypeJoin.call(path.slice(0, i + 1), '.');
-          const layerOrRoute = get(router, metaPath);
-          if (layerOrRoute?.[kMetaKey]) {
-            metas.push(layerOrRoute[kMetaKey]);
-          }
-        }
-      }
-
-      // mounted routers aren't discoverable since they themselves don't
-      // represent routes, they dispatch to sub routers/route handlers.
-      if (value.name != 'router' && value.handle?.name != 'router') {
-        let routeType;
-        if (value[kMetaKey]?.method == 'use') {
-          // if the handler is registered via `use` method, there are no
-          // associated HTTP methods. this use case is considered middleware.
-          if (!this.core.config.getEffectiveValue('assess.report_middleware_routes')) return;
-          routeType = RouteType.MIDDLEWARE;
-        } else {
-          routeType = RouteType.HTTP;
-        }
-
-        // `value` is a terminal Layer with observable signatures.
-        // emit discovery after appending metadata.
-        if (value[kMetaKey]) {
-          const observables = this.generateObservables(metas, value.handle);
-          if (observables) {
-            value[kMetaKey].routeType = routeType;
-            if (!value[kMetaKey].observables) {
-              value[kMetaKey].observables = observables;
-            } else {
-              Object.assign(value[kMetaKey].observables, observables);
-            }
-          }
-          self.discover(value[kMetaKey]);
-        }
-      }
-    });
-  }
-
-  /**
-   * Traverses the top-level app's routing stack and executes the provided callback when
-   * visiting nodes. The callback is invoked only to visit Layer instances, objects and
-   * functions, since these are the only 2 types that could have our metadata attached.
-   */
-  traverse(target, cb, path = [], data = new Map()) {
-    loopKeys: for (const key in target) {
-      path.push(key);
-
-      // only visit Layer instances
-      const maybeLayer = target[key];
-      if (
-        maybeLayer?.constructor?.name == 'Layer' &&
-        !maybeLayer?.stack?.length
-      ) {
-        let _data = data.get(maybeLayer);
-
-        if (!_data) {
-          _data = { paths: [] };
-          data.set(maybeLayer, _data);
-        }
-
-        // you can mount a router on itself
-        // prevent infinitely recursing into self-mounted routers
-        for (const visitedPath of _data.paths) {
-          // these conditions indicate recursive nesting at particular path
-          if (
-            path.length > visitedPath.length &&
-            visitedPath.every((el, i) => path[i] == el)
-          ) {
-            path.pop();
-            continue loopKeys;
-          }
-        }
-
-        _data.paths.push([...path]); // copy because path argument mutates
-
-        const halt = cb(path, key, maybeLayer, target) === false;
-        if (halt) return;
-      }
-
-      // might be able to fine-tune this a bit more
-      if (typeof maybeLayer == 'object' || typeof maybeLayer == 'function') {
-        this.traverse(maybeLayer, cb, path, data);
-      }
-
-      path.pop();
-    }
-  }
-
-  generateObservables(metas, handler) {
-    const { core } = this;
-    handler = core.patcher.unwrap(handler);
-
-    let type = '';
-    let method = '';
-    let templates = [];
-    const info = funcInfo(handler);
-
-    let file = info.file ?
-      StringPrototypeReplace.call(info.file, core.appInfo.app_dir, '') :
-      '';
-    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
-
-    // loop backwards
-    for (let i = metas.length - 1; i >= 0; i--) {
-      const meta = metas[i];
-      // use the most recent `type` and `method` used when building routes, so don't overwrite if set
-      if (!type && meta.type) type = meta.type;
-      if (!method && meta.method) method = meta.method;
-
-      // builds out all possible template combinations that the Layer is able to handle during routing
-      if (Array.isArray(meta.paths)) {
-        if (!templates.length) {
-          templates = [...meta.paths];
-        } else {
-          const _t = [];
-          for (const templateSegment of meta.paths) {
-            for (const templateAcc of templates) {
-              _t.push(`${templateSegment}${templateAcc}`);
-            }
-          }
-          templates = [..._t];
-        }
-      }
-    }
-
-    // build signature lookup based on each template (normalizeUri)
-    const map = templates.reduce((acc, routeTemplate) => {
-      if (!routeTemplate) routeTemplate = '/';
-      acc[routeTemplate] = `${type}.${method}('${routeTemplate}', ${formattedHandler})`;
-      return acc;
-    }, {});
-
-    return map;
-  }
-
-  static normalizePathSegment(value) {
-    if (!value || value == '/') {
-      // app.[method](handler) and app.[method]('/', handler) are the same so default to empty string
-      return '';
-    }
-    if (value instanceof RegExp) {
-      const rxString = value.toString();
-      // todo: figure out best way to represent regexp in route template
-      return `/[${StringPrototypeSubstring.call(rxString, 1, rxString.length - 1)}]`;
-    }
-    return value;
-  }
-
-  static normalizePaths(paths) {
-    const ret = [];
-
-    // same as mounting as /
-    if (typeof paths == 'function') {
-      // default to ''
-      ret.push('');
-    } else if (isString(paths)) {
-      ret.push(ExpressInstrumentation.normalizePathSegment(paths));
-    } else if (Array.isArray(paths)) {
-      paths = paths.flat(Infinity).filter((v) => typeof v !== 'function');
-      if (paths.length) ret.push(...paths.map(ExpressInstrumentation.normalizePathSegment));
-      else ret.push('');
-    } else if (paths instanceof RegExp) {
-      ret.push(ExpressInstrumentation.normalizePathSegment(paths));
-    }
-
-    return ret;
-  }
-}