@contrast/agentify 1.24.0 → 1.24.2

package/lib/function-hooks.js

@@ -18,8 +18,49 @@
 const IS_CLASS_REGEX = /^class\W/;
 const IS_FUNCTION_REGEX = /^(async\s+)?function\W/;
 const IS_RETURN_REGEX = /^return\W/;
-const METHOD_CONTEXT = 'function _contrast_';
-const FUNCTION_CONTEXT = 'const _contrast_fn = ';
+const FUNCTION_DECL = 'function _contrast_';
+const VARIABLE_DECL = 'const _contrast_fn = ';
+
+/**
+ * Injects some context around a function's toString() to make it syntactically
+ * valid. The `swc` parser expects input to be a valid `Statement` like one of
+ * the following:
+ * ```js
+ * // (named) function declaration
+ * function f() {}
+ * // (named) class declaration
+ * class C {}
+ * // variable declaration with an (anonymous?) class or function expression
+ * const _contrast_fn = function () {};
+ * const _contrast_fn = () => {};
+ * const _contrast_fn = class {};
+ * ```
+ * @param   {string} code original toString() return value
+ * @returns {string}      the contextualized statement
+ */
+function contextualize(code) {
+  // in case the class is anonymous we need to prepend a variable declaration.
+  if (IS_CLASS_REGEX.exec(code)) {
+    return `${VARIABLE_DECL}${code}`;
+  }
+
+  // if the function is a return, we don't need to add context.
+  if (!IS_RETURN_REGEX.exec(code)) {
+    const [orig] = code.split('{');
+    let lineOne = orig;
+
+    // When stringified, class methods look like normal function without the
+    // `function` keyword. We can normalize this by prepending `function`.
+    if (!IS_FUNCTION_REGEX.exec(lineOne) && lineOne.indexOf('=>') === -1) {
+      lineOne = `${FUNCTION_DECL}${lineOne}`;
+    }
+    lineOne = `${VARIABLE_DECL}${lineOne}`;
+
+    code = code.replace(orig, lineOne);
+  }
+
+  return code;
+}
 
 module.exports = function (deps) {
   const {
@@ -36,58 +77,26 @@ module.exports = function (deps) {
     cache: new WeakMap(),
   });
 
-  /**
-   * Create some code context around a function to make it syntactically valid
-   * the three general types of syntactic function definitions are:
-   *   - functions (declared with the function keyword)
-   *   - arrow functions
-   *   - class methods
-   * @param   {string} code the user code
-   * @returns {string}      the contextualized function
-   */
-  functionHooks.contextualizeFunction = (code) => {
-    // Classes themselves are functions, so we need to exit early to avoid
-    // clobbering the `class` keyword.
-    if (IS_CLASS_REGEX.exec(code)) return code;
-    const [orig] = code.split('{');
-
-    let lineOne = orig;
-
-    // if the function is a return, we don't need to add context.
-    if (!IS_RETURN_REGEX.exec(lineOne)) {
-      // When stringified, class methods look like normal function without the
-      // `function` keyword. We can normalize this by prepending `function`.
-      if (!IS_FUNCTION_REGEX.exec(lineOne) && lineOne.indexOf('=>') === -1) {
-        lineOne = `${METHOD_CONTEXT}${lineOne}`;
-      }
-      lineOne = `${FUNCTION_CONTEXT}${lineOne}`;
-
-      code = code.replace(orig, lineOne);
-    }
-
-    return code;
-  };
-
   /**
    * Returns the rewritten function code. If an error occurs during rewriting,
    * we log the error and code information and return the original code string.
-   * @param {string} code string value of the JavaScript function
-   * @returns {string} the code rewritten to remove Contrast tokens
+   * @param {string} code original toString() return value
+   * @returns {string}    the code rewritten to remove Contrast tokens
    */
-  functionHooks.unwrite = function (code) {
+  function unwrite(code) {
     // cannot parse lone function expressions that are not part of an assignment.
     try {
-      let unwritten = functionHooks.contextualizeFunction(code);
+      let unwritten = contextualize(code);
       unwritten = rewriter.unwriteSync(unwritten);
-      unwritten = unwritten.replace(METHOD_CONTEXT, '');
-      unwritten = unwritten.replace(FUNCTION_CONTEXT, '');
+      unwritten = unwritten.replace(FUNCTION_DECL, '');
+      unwritten = unwritten.replace(VARIABLE_DECL, '');
       unwritten = unwritten.replace(/;\s*$/, ''); // removes trailing semicolon/whitespace
       return unwritten;
     } catch (err) {
       logger.warn({ err, code }, 'Failed to unwrite function code');
       return code;
     }
-  };
+  }
 
   functionHooks.install = function () {
     if (deps.functionHooks.installed) return;
@@ -113,7 +122,7 @@ module.exports = function (deps) {
         let result = code;
 
         if (code.indexOf('ContrastMethods') > -1) {
-          const unwritten = functionHooks.unwrite(code);
+          const unwritten = unwrite(code);
           functionHooks.cache.set(data.obj, unwritten);
           result = unwritten;
         }

package/lib/index.js

@@ -17,6 +17,10 @@
 
 const Module = require('module');
 const { IntentionalError } = require('@contrast/common');
+const {
+  assertValidOpts,
+  preStartupValidation
+} = require('./utils');
 
 const ERROR_MESSAGE = 'An error prevented the Contrast agent from installing. The application will be run without instrumentation.';
 /**
@@ -61,6 +65,9 @@ module.exports = function init(core = {}) {
   let _opts;
 
   core.agentify = async function agentify(callback, opts = {}) {
+    // options are hardcoded, so if this throws it's going to be in testing/dev situation
+    assertValidOpts(opts);
+
     _callback = callback;
     _opts = opts;
     _opts.type = _opts.type ?? 'cjs';
@@ -124,6 +131,9 @@ module.exports = function init(core = {}) {
   }
 
   try {
+    // check supported Node version and correct preload usage before anything else
+    preStartupValidation(core);
+
     require('@contrast/core/lib/messages')(core);
     require('@contrast/config')(core);
     if (core.config._errors?.length) {
@@ -131,7 +141,7 @@ module.exports = function init(core = {}) {
     }
     if (!core.config.enable) {
       const errorMessage = 'Contrast agent disabled by configuration (enable: false)';
-      console.log(errorMessage);
+      console.info(errorMessage);
       throw new IntentionalError(errorMessage);
     }
 
@@ -172,7 +182,8 @@ module.exports = function init(core = {}) {
       if (core.logger) {
         core.logger.error({ err }, ERROR_MESSAGE);
       } else {
-        console.error(new Error(ERROR_MESSAGE, { cause: err }));
+        console.error(err);
+        console.error(ERROR_MESSAGE);
       }
     }
   }

package/lib/utils.js

@@ -0,0 +1,153 @@
+/*
+ * 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 path = require('path');
+const process = require('process');
+const semver = require('semver');
+const { findPackageJsonSync } = require('@contrast/find-package-json');
+const {
+  engines: {
+    node: nodeEngines,
+  }
+} = require('../package.json');
+
+/**
+ * Performs various startup validation checks. All checks throw errors when they
+ * fail so startup/installation stops.
+ * @param {string} core.nodeEngines
+ */
+function preStartupValidation(core) {
+  assertSupportedNodeVersion(core.nodeEngines || nodeEngines);
+  assertSupportedPreloadUsage();
+}
+
+/**
+ * Checks current running version of Node against provided engines descriptor.
+ * If the Node version doesn't satisfy supported versions from engines, then
+ * we will throw an error to prevent instrumentation.
+ * @param {string} engines engines that must be satisfied
+ * @throws {Error}
+ */
+function assertSupportedNodeVersion(engines) {
+  if (!semver.satisfies(process.version, engines)) {
+    let validRanges = '';
+    engines.split('||').forEach((range) => {
+      const minVersion = semver.minVersion(range).toString();
+      const maxVersion = range.split('<').pop()
+        .trim();
+      validRanges += `${minVersion} and ${maxVersion}, `;
+    });
+    throw new Error(`Contrast only officially supports Node LTS versions between ${validRanges}but detected ${process.version}.`);
+  }
+}
+
+/**
+ * Checks that the correct preload flag is used given running node version.
+ * @throws {Error}
+ */
+function assertSupportedPreloadUsage() {
+  const {
+    execArgv,
+    version,
+    env: { CSI_EXPOSE_CORE, NODE_OPTIONS },
+  } = process;
+
+  let msg;
+
+  // allow testing to ignore these restrictions
+  if (CSI_EXPOSE_CORE === 'no-validate') return;
+
+  // eslint-disable-next-line newline-per-chained-call
+  const [major, minor] = version.slice(1).split('.').map(Number);
+  const nodeOptionArgs = (NODE_OPTIONS || '').split(/\s+/).filter((v) => v);
+  const allArgsToCheck = [...execArgv, ...nodeOptionArgs];
+
+  let checkOccurred = false;
+
+  for (let i = 0; i < allArgsToCheck.length; i++) {
+    const preloadFlag = allArgsToCheck[i];
+    let preloadTarget = allArgsToCheck[i + 1];
+
+    if (!isLoader(preloadFlag)) continue;
+
+    if (preloadTarget && !preloadTarget.startsWith('@contrast/agent')) {
+      // if absolute path is provided read the package name to check if it's our agent
+      if (path.isAbsolute(preloadTarget)) {
+        try {
+          const { name } = require(findPackageJsonSync({ cwd: path.dirname(preloadTarget) }));
+          if (name !== '@contrast/agent') continue;
+          preloadTarget = name;
+        } catch (err) {
+          //
+        }
+      } else {
+        continue;
+      }
+    }
+
+    if (preloadTarget?.startsWith?.('@contrast/agent')) {
+      checkOccurred = true;
+
+      if (preloadFlag === '--import') {
+        if (major <= 18 && minor < 19) {
+          msg = 'Contrast requires that Node LTS versions >= 18.19.0 use the --import flag for ESM support';
+        }
+      } else {
+        // --loader or --experimental-loader
+        if (major >= 20 || (major === 18 && minor >= 19)) {
+          msg = 'Contrast requires that Node versions less than 18.19.0 use the --loader flag for ESM support';
+        }
+      }
+
+      // done since we've found us
+      break;
+    }
+  }
+
+  if (msg) throw new Error(msg);
+
+  // indicates we found ourselves
+  return checkOccurred;
+}
+
+function isLoader(arg) {
+  return arg == '--import' || arg == '--loader' || arg == '--experimental-loader';
+}
+
+/**
+ * Validates custom `installOrder` options. We currently need the reporter component
+ * to install first in order to onboard and get effective settings and mode values.
+ * @param {Object} opts The options object param
+ * @param {string[]} opts.installOrder array of component names to install in order
+ */
+function assertValidOpts(opts) {
+  if (opts.noValidate) return;
+
+  if (opts.installOrder?.length) {
+    if (opts.installOrder[0] !== 'reporter') {
+      const msg = `The 'installOrder' option must include 'reporter' as first element. found '${opts.installOrder[0]}'`;
+      throw new Error(msg);
+    }
+  }
+}
+
+module.exports = {
+  assertValidOpts,
+  assertSupportedNodeVersion,
+  assertSupportedPreloadUsage,
+  preStartupValidation,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/agentify",
-  "version": "1.24.0",
+  "version": "1.24.2",
   "description": "Configures Contrast agent services and instrumentation within an application",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -11,24 +11,26 @@
   "types": "lib/index.d.ts",
   "engines": {
     "npm": ">=6.13.7 <7 || >= 8.3.1",
-    "node": ">= 14.15.0"
+    "node": ">= 14.18.0"
   },
   "scripts": {
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.20.0",
-    "@contrast/config": "1.27.0",
-    "@contrast/core": "1.31.0",
-    "@contrast/deadzones": "1.1.2",
-    "@contrast/dep-hooks": "1.3.1",
-    "@contrast/esm-hooks": "2.5.0",
-    "@contrast/instrumentation": "1.7.0",
-    "@contrast/logger": "1.8.0",
-    "@contrast/metrics": "1.7.0",
-    "@contrast/patcher": "1.7.1",
-    "@contrast/reporter": "1.26.0",
-    "@contrast/rewriter": "1.7.0",
-    "@contrast/scopes": "1.4.0"
+    "@contrast/common": "1.20.1",
+    "@contrast/config": "1.27.1",
+    "@contrast/core": "1.31.2",
+    "@contrast/deadzones": "1.1.3",
+    "@contrast/dep-hooks": "1.3.2",
+    "@contrast/esm-hooks": "2.5.2",
+    "@contrast/find-package-json": "^1.1.0",
+    "@contrast/instrumentation": "1.7.1",
+    "@contrast/logger": "1.8.1",
+    "@contrast/metrics": "1.7.1",
+    "@contrast/patcher": "1.7.2",
+    "@contrast/reporter": "1.26.1",
+    "@contrast/rewriter": "1.7.2",
+    "@contrast/scopes": "1.4.1",
+    "semver": "^7.6.0"
   }
 }