@contrast/agent 5.2.1 → 5.3.0

package/README.md

@@ -47,40 +47,49 @@ $ npm install @contrast/agent
 
 ## Usage
 
-### [CommonJS (CJS) Applications](https://nodejs.org/docs/latest-v12.x/api/modules.html)
+### With LTS (Long Term Support) Node.js Versions
 
-CommonJS is the original Node.js module system. CJS modules are loaded with the
-`const module = require('module')` syntax.
-
-When instrumenting an application written this way, without EJS modules or ESM dependencies, use the following
-method to start the application.
+[Node.js policy](https://nodejs.org/en/about/previous-releases/) is that production applications
+should use only Active LTS or Maintenance LTS releases. All current LTS versions of Node.js support
+ECMAScript modules (ESM) and CommonJS modules (CJS) with the `--import` flag. To ensure that the
+agent can instrument your application, use:
 
 ```sh
-  node -r @contrast/agent app-main.js [app arguments]
+node --import @contrast/agent app-main [app arguments]
 ```
 
-### [ECMAScript (ESM) Applications](https://nodejs.org/docs/latest-v12.x/api/esm.html#esm_ecmascript_modules)
+Notes:
+- `--import` should be used for Node.js LTS (Active and Maintenance) versions `>=18.19.0`
+- Node.js versions `>=20.0.0` and `<20.6.0` are not supported
+
+### With end-of-life Node.js Versions
+
+When using the agent with end-of-life Node.js versions, use either the `--loader` or
+`--require` flag, depending on the version of Node.js and the module system used.
 
-ECMAScript modules are the _new_ official standard format to package JavaScript
-code for reuse. ES Modules are loaded with the `import module from 'module'`
-syntax.
+Use the `--loader` flag for Node.js versions `>=16.17.0` and `<18.19.0`.
+
+```sh
+node --loader @contrast/agent app-main.mjs [app arguments]
+```
 
-When instrumenting an application that utilizes ECMAScript Modules, use the
-following methods to start the application. This is the appropriate method for
-instrumenting an application that uses CJS, ESM, or a combination of both.
+Use the `--require` (`-r`) flag for Node.js versions `<16.17.0`.
 
-- Node versions `>=16.17.0` and `<18.19.0`:
+```sh
+node -r @contrast/agent app-main [app arguments]
+```
 
-    ```sh
-    node --loader @contrast/agent app-main.mjs [app arguments]
-    ```
+Note:
+- `-r` will still work for Node.js versions that have no ESM modules or dependencies.
 
-- Node versions `>=18.19.0` and `<20.0.0`, or versions `>=20.6.0`:
+### With @contrast/agent v4
 
-     ```sh
-     node --import @contrast/agent app-main.mjs [app arguments]
-     ```
+The Contrast Node.js agent v4 is still available for use, but does not support ESM
+modules. To use the v4 agent, use the `--require` (`-r`) flag.
 
+```sh
+node -r @contrast/agent app-main [app arguments]
+```
 
 ### Configuration
 

package/lib/esm-loader.mjs

@@ -14,148 +14,13 @@
  */
 
 import Module from 'node:module';
-import W from 'node:worker_threads';
-import EventEmitter from 'node:events';
-import * as hooks from './esm-hooks.mjs';
-import checkImportVsLoaderVsNodeVersion from './check-flag-vs-node-version.mjs';
-
-// might need to get exclude function here as opposed to deep within initialize
-// execution.
-// 1) core should be a singleton so it's always shared between modules
-// 2) core should include the redirect map.
-// 3) is the exclude function needed here as we move to async loading? if so,
-//    this will need to add the root directory(ies) to an exclude list.
-
-const logLoad = 1;
-// eslint-disable-next-line no-unused-vars
-const logResolve = 2;
-const logRequireAll = 4;
-let log = 0;
-if (process.env.CSI_HOOKS_LOG) {
-  log = +process.env.CSI_HOOKS_LOG;
-}
-
-// verify that we're running with the correct flag for the version of node.
-const { flag, msg } = checkImportVsLoaderVsNodeVersion();
-
-if (msg) {
-  console.error(msg);
-  throw new Error(msg);
-  // belt and suspenders
-  // eslint-disable-next-line no-unreachable
-  process.exit(1); // eslint-disable-line no-process-exit
-}
-
-//
-// if CJS hooks are not already setup, setup CJS hooks. each thread must patch
-// Module. I don't think this will be called more than once, but the flag is
-// in place just in case.
-//
-
-const core = (await import('./initialize.mjs')).default;
+const require = Module.createRequire(import.meta.url);
+const { startAgent } = require('./start-agent');
 let load, resolve;
 
-if (core) {
-  // most of this can be removed; it's here for debugging. but considering the relatively
-  // low cost compared with loading a module, i'm leaving it in.
-  (log & logRequireAll) && console.log('ESM-LOADER executing CJS Module patching');
-  const originalRequire = Module.prototype.require;
-  const originalCompile = Module.prototype._compile;
-  const originalExtensions = Module._extensions['.js'];
-  const originalLoad = Module._load;
-  if (originalLoad?.name !== '__loadOverride') {
-    // debugger; // this is a good place to make a quick check if things aren't working
-  }
-
-  Module.prototype.require = function(moduleId) {
-    (log & logRequireAll) && console.log('CJS -> require() called for', moduleId);
-    return originalRequire.call(this, moduleId);
-  };
-
-  Module.prototype._compile = function(code, filename) {
-    (log & logRequireAll) && console.log('CJS -> _compile() called for', filename);
-    return originalCompile.call(this, code, filename);
-  };
-
-  Module._extensions['.js'] = function(module, filename) {
-    (log & logRequireAll) && console.log('CJS -> _extensions[".js"] called for', filename);
-    return originalExtensions.call(this, module, filename);
-  };
-
-  Module._load = function(request, parent, isMain) {
-    (log & logLoad) && console.log(`CJS(${W.threadId}) -> _load() ${request}`);
-    return originalLoad.call(this, request, parent, isMain);
-  };
-
-  core.threadInfo.syncEmitter = new EventEmitter();
-  // abstract how notifications are posted so that the non-loader
-  // code is not coupled to the implementation. the loader-thread
-  // complement of this is in esm-hooks.
-  //
-  // specifically, this is the main thread and post() directly emits
-  // the event while in the loader thread post() uses post.postMessage()
-  // to communicate back to this (the main) thread.
-  core.threadInfo.post = (type, data) => {
-    core.threadInfo.syncEmitter.emit(type, data);
-  };
-
-  //
-  // setup ESM hooks
-  //
-  // if register exists this is 20.6.0 or later. we do not support
-  // node 20 prior to 20.6.0 (or 20.9.0 when 20 became LTS).
-  // news flash: backported register to node 18.19.0, so checking register
-  // is no longer enough.
-  //
-  if (Module.register && flag === '--import') {
-    // this file should never be executed in the loader thread; this file creates
-    // the loader thread by calling register(). the loader thread must create its
-    // own copy of threadInfo and insert it into core.
-    if (!core.threadInfo.isMainThread) {
-      // only get an error in CI on node v18.
-      throw new Error('esm-loader.mjs should not be executed in the loader thread');
-    }
-    const { MessageChannel } = await import('node:worker_threads');
-    const { port1, port2 } = new MessageChannel();
-
-
-    core.threadInfo.port = port1;
-    // messages received on the port are re-emitted as standard node events. the
-    // body must contain the type; data can be undefined.
-    core.threadInfo.missingTypeCount = 0;
-    core.threadInfo.port.on('message', (body) => {
-      const { type, data } = body;
-      if (type) {
-        core.threadInfo.syncEmitter.emit(type, data);
-      } else {
-        core.threadInfo.missingTypeCount += 1;
-      }
-    });
-    core.threadInfo.port.unref();
-
-    // record the URL of the entry point.
-    core.threadInfo.url = import.meta.url;
-
-    // get relative URL
-    const url = new URL('./esm-hooks.mjs', import.meta.url);
-    await Module.register(url.href, import.meta.url, { data: { port: port2 }, transferList: [port2] });
-
-    // we only need to do this if there is a background thread.
-    // The esmHooks component of the main agent will send TS settings update to the loader agent via the port.
-    // To get the loader agent components to update we just need to forward the settings using `.messages` emitter.
-    core.messages.on(Event.SERVER_SETTINGS_UPDATE, (msg) => {
-      core.threadInfo.port.postMessage({
-        type: Event.SERVER_SETTINGS_UPDATE,
-        ...msg,
-      });
-    });
-  }
-  // it's not possible to conditionally export, but exporting undefined
-  // values is close.
-
-
-  const finalHooks = (Module.register && flag === '--import') ? {} : hooks;
-  ({ load, resolve } = finalHooks);
-}
+try {
+  const core = await startAgent({ type: 'esm' });
+  ({ load, resolve } = core.esmHooks.hooks); // remove when all LTS versions support register
+} catch (err) { } // eslint-disable-line no-empty
 
-export { load, resolve };
+export { load, resolve }; // remove when all LTS versions support register

package/lib/index.js

@@ -15,73 +15,8 @@
 
 'use strict';
 
-const semver = require('semver');
-const {
-  name: agentName,
-  version: agentVersion,
-  engines: {
-    node: nodeEngine,
-    npm: npmEngine
-  }
-} = require('../package.json');
-const agentify = require('@contrast/agentify')({ agentName, agentVersion });
+const { startAgent } = require('./start-agent');
 
-agentify((core) => {
-  if (!semver.satisfies(process.version, nodeEngine)) {
-    let validRanges = '';
-    nodeEngine.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}.`);
-  }
-
-  core.startupValidation = {
-    /**
-     *  This will run after we onboard to the UI and pick up any remote settings.
-     */
-    install() {
-      if (
-        !core.config.getEffectiveValue('assess.enable') &&
-        !core.config.getEffectiveValue('protect.enable')
-      ) {
-        throw new Error('Neither Assess nor Protect are enabled. Check local configuration and UI settings');
-      }
-    }
-  };
-
-  core.npmVersionRange = npmEngine;
-  require('@contrast/telemetry')(core);
-  require('@contrast/assess')(core);
-  require('@contrast/architecture-components')(core);
-  require('@contrast/library-analysis')(core);
-  require('@contrast/route-coverage')(core);
-  require('@contrast/protect')(core); // protect loads lastly, being the only non-passive feature
-
-  if (process.env.CSI_EXPOSE_CORE) {
-    const coreKey = Symbol.for('contrast:core');
-    global[coreKey] = core;
-  }
-}, {
-  installOrder: [
-    'reporter',
-    'startupValidation',
-    'telemetry',
-    'contrastMethods',
-    'deadzones',
-    'scopes',
-    'sources',
-    'architectureComponents',
-    'assess',
-    'protect',
-    'depHooks',
-    'routeCoverage',
-    'libraryAnalysis',
-    'heapSnapshots',
-    'rewriteHooks',
-    'functionHooks',
-    'metrics',
-  ],
-});
+try {
+  startAgent({ type: 'cjs' });
+} catch (err) {} // eslint-disable-line no-empty

package/lib/start-agent.js

@@ -0,0 +1,146 @@
+/*
+ * 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 process = require('process');
+const semver = require('semver');
+const _agentify = require('@contrast/agentify');
+const {
+  name: agentName,
+  version: agentVersion,
+  engines: {
+    node: nodeEngine,
+    npm: npmEngine
+  }
+} = require('../package.json');
+
+function initCore() {
+  if (!semver.satisfies(process.version, nodeEngine)) {
+    let validRanges = '';
+    nodeEngine.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}.`);
+  }
+
+  checkImportVsLoaderVsNodeVersion();
+
+  const core = { agentName, agentVersion };
+
+  core.startupValidation = {
+    /**
+     *  This will run after we onboard to the UI and pick up any remote settings.
+     */
+    install() {
+      if (
+        !core.config.getEffectiveValue('assess.enable') &&
+        !core.config.getEffectiveValue('protect.enable')
+      ) {
+        throw new Error('Neither Assess nor Protect are enabled. Check local configuration and UI settings');
+      }
+    }
+  };
+
+  core.npmVersionRange = npmEngine;
+
+  if (process.env.CSI_EXPOSE_CORE) {
+    global[Symbol.for('contrast:core')] = core;
+  }
+
+  return core;
+}
+
+function loadFeatures(core) {
+  require('@contrast/assess')(core);
+  require('@contrast/architecture-components')(core);
+  require('@contrast/library-analysis')(core);
+  require('@contrast/route-coverage')(core);
+  require('@contrast/protect')(core);
+}
+
+/**
+ * check to see if we're running with the correct flag (--loader or --import)
+ * for the right version of node. we do not function correctly when --loader
+ * is used for node >= 18 or when --import is used for node < 18.
+ */
+function checkImportVsLoaderVsNodeVersion() {
+  // allow testing to ignore these restrictions
+  const noValidate = process.env.CSI_EXPOSE_CORE === 'no-validate';
+  let msg;
+
+  const { execArgv, version } = process;
+  // eslint-disable-next-line newline-per-chained-call
+  const [major, minor] = version.slice(1).split('.').map(Number);
+  for (let i = 0; i < execArgv.length; i++) {
+    const loader = execArgv[i];
+    const agent = execArgv[i + 1];
+    if (['--import', '--loader', '--experimental-loader'].includes(loader) && agent?.startsWith('@contrast/agent')) {
+      if (noValidate) {
+        return;
+      }
+      if (loader === '--import') {
+        // loader is --import
+        if (major === 18 && minor >= 19 || major >= 20) {
+          return;
+        }
+        if (major <= 18 && minor < 19) {
+          msg = 'Contrast requires node versions less than 18.19.0 use the --loader flag for ESM support';
+        }
+      } else {
+        // loader is either --loader or --experimental-loader (same thing)
+        if (major >= 20 || major === 18 && minor >= 19) {
+          msg = 'Contrast requires node versions >= 18.19.0 use the --import flag for ESM support';
+        }
+      }
+      break;
+    }
+  }
+
+  if (msg) throw new Error(msg);
+}
+
+async function startAgent({ type = 'cjs' } = {}) {
+  const core = initCore();
+  const agentify = _agentify(core);
+
+  return agentify(loadFeatures, {
+    installOrder: [
+      'reporter',
+      'startupValidation',
+      'contrastMethods',
+      'deadzones',
+      'scopes',
+      'sources',
+      'architectureComponents',
+      'assess',
+      'protect',
+      'depHooks',
+      'routeCoverage',
+      'libraryAnalysis',
+      'heapSnapshots',
+      'metrics',
+      'rewriteHooks',
+      'functionHooks',
+      'esmHooks',
+    ],
+    type
+  });
+}
+
+module.exports = { startAgent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/agent",
-  "version": "5.2.1",
+  "version": "5.3.0",
   "description": "Assess and Protect agents for Node.js",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -21,13 +21,13 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/agentify": "1.20.1",
-    "@contrast/architecture-components": "1.16.0",
-    "@contrast/assess": "1.24.1",
-    "@contrast/library-analysis": "1.17.0",
-    "@contrast/protect": "1.32.1",
-    "@contrast/route-coverage": "1.16.0",
-    "@contrast/telemetry": "1.4.1",
+    "@contrast/agentify": "1.21.0",
+    "@contrast/architecture-components": "1.17.0",
+    "@contrast/assess": "1.25.0",
+    "@contrast/library-analysis": "1.18.0",
+    "@contrast/protect": "1.33.0",
+    "@contrast/route-coverage": "1.17.0",
+    "@contrast/telemetry": "1.5.0",
     "semver": "^7.3.7"
   }
 }

package/lib/check-flag-vs-node-version.mjs

@@ -1,61 +0,0 @@
-/*
- * 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.
- */
-//
-// check to see if we're running with the correct flag (--loader or --import)
-// for the right version of node. we do not function correctly when --loader
-// is used for node >= 20 or when --import is used for node < 20.
-//
-export default function checkImportVsLoaderVsNodeVersion() {
-  // allow testing to ignore these restrictions
-  const noValidate = process.env.CSI_EXPOSE_CORE === 'no-validate';
-  let flag;
-  const { execArgv, version, env: { NODE_OPTIONS } } = process;
-
-  // eslint-disable-next-line newline-per-chained-call
-  const [major, minor] = version.slice(1).split('.').map(Number);
-
-  const _execArgs = [
-    ...(NODE_OPTIONS?.split?.(/\s+/).map((v) => v.trim()) || []),
-    ...execArgv,
-  ]
-
-  for (let i = 0; i < _execArgs.length; i++) {
-    const loader = _execArgs[i];
-    const agent = _execArgs[i + 1];
-    if (['--import', '--loader', '--experimental-loader'].includes(loader) && agent?.startsWith('@contrast/agent')) {
-      flag = loader;
-      if (noValidate) {
-        return { flag, msg: '' };
-      }
-      if (loader === '--import') {
-        // loader is --import
-        if (major === 18 && minor >= 19 || major >= 20) {
-          return { flag, msg: '' };
-        }
-        if (major <= 18 && minor < 19) {
-          return { flag, msg: 'Contrast requires node versions less than 18.19.0 use the --loader flag for ESM support' };
-        }
-      } else {
-        // loader is either --loader or --experimental-loader (same thing)
-        if (major >= 20 || major === 18 && minor >= 19) {
-          return { flag, msg: 'Contrast requires node versions >= 18.19.0 use the --import flag for ESM support' };
-        }
-      }
-      break;
-    }
-  }
-  // i think we only get here if flag === '--loader' and node < 20
-  return { flag, msg: '' };
-}

package/lib/esm-hooks.mjs

@@ -1,266 +0,0 @@
-/*
- * 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.
- */
-import Module from 'node:module';
-import { readFile as rf } from 'node:fs/promises';
-import W from 'node:worker_threads';
-
-const logLoad = 1;
-const logResolve = 2;
-const logRequireAll = 4;
-const logApplication = 8; // eslint-disable-line no-unused-vars
-let log = 0;
-if (process.env.CSI_HOOKS_LOG) {
-  log = +process.env.CSI_HOOKS_LOG;
-}
-
-const [major, minor] = process.versions.node.split('.').map(it => +it);
-const isLT16_12 = major < 16 || (major === 16 && minor < 12);
-
-
-// from esmock: git@github.com:iambumblehead/esmock.git
-//
-// new versions of node: when multiple loaders are used and context
-// is passed to nextResolve, the process crashes in a recursive call
-// see: /esmock/issues/#48
-//
-// old versions of node: if context.parentURL is defined, and context
-// is not passed to nextResolve, the tests fail
-//
-// later versions of node v16 include 'node-addons'
-async function protectedNextResolve(nextResolve, specifier, context) {
-  if (context.parentURL) {
-    if (context.conditions.at(-1) === 'node-addons' || context.importAssertions || isLT16_12) {
-      return nextResolve(specifier, context);
-    }
-  }
-
-  return nextResolve(specifier);
-}
-
-// import.meta.resolve('node-fetch') v20 became synchronous. not all that useful for now because
-// of the significant break in behavior. but the function is great - it resolves a specifier to the
-// file that would be loaded.
-// file:///home/bruce/github/csi/rasp-v3/node_modules/node-fetch/src/index.js
-
-const { default: core } = await import('./initialize.mjs');
-let load, resolve, initialize;
-
-if (core) {
-  const { esmHooks: { mappings, fixPath, getFileType } } = core;
-  initialize = Module.register && async function(data) {
-    if (data?.port) {
-      data.port.on('message', _msg => {
-        // we don't currently send messages to the loader thread but when we do,
-        // this is where they will show up.
-        //console.log('ESM HOOK -> INIT -> MESSAGE', _msg);
-      });
-      data.port.postMessage({ type: 'keep-alive', data: 'hello from esm-hooks' });
-      data.port.unref();
-      // this is running in the loader thread. save thread info because it can't
-      // be set from the main thread.
-      if (W.isMainThread) {
-        throw new Error('initialize() called from main thread.');
-      }
-      core.threadInfo.isMainThread = false;
-      core.threadInfo.threadId = W.threadId;
-      core.threadInfo.port = data.port;
-      // the loader thread's post() sends via the port.
-      core.threadInfo.post = (type, data) => {
-        core.threadInfo.port.postMessage({ type, data });
-      };
-    }
-
-    log && console.log('ESM HOOK -> INIT');
-    // it's not clear to me why Module is present when initialize() is being
-    // executed in the loader thread. but it is. (code here originally loaded
-    // Module via createRequire(), but that is not necessary.)
-    const originalRequire = Module.prototype.require;
-    const originalCompile = Module.prototype._compile;
-    const originalExtensions = Module._extensions['.js'];
-    const originalLoad = Module._load;
-
-    // Module needs to be patched in the loader thread too. initialize() runs in
-    // that context.
-    Module.prototype.require = function(moduleId) {
-      (log & logRequireAll) && console.log(`CJS(init ${W.threadId}) -> require(${moduleId})`);
-      return originalRequire.call(this, moduleId);
-    };
-
-    Module.prototype._compile = function(code, filename) {
-      (log & logRequireAll) && console.log(`CJS(init ${W.threadId}) -> _compile(${filename})`);
-      return originalCompile.call(this, code, filename);
-    };
-
-    Module._extensions['.js'] = function(module, filename) {
-      (log & logRequireAll) && console.log(`CJS(init ${W.threadId}) -> _extensions[".js"]: ${filename}`);
-      return originalExtensions.call(this, module, filename);
-    };
-
-    Module._load = function(request, parent, isMain) {
-      (log & logLoad) && console.log(`CJS(init ${W.threadId}) -> _load(${request})`);
-      return originalLoad.call(this, request, parent, isMain);
-    };
-  };
-
-  resolve = async function(specifier, context, nextResolve) {
-    (log & logResolve) && console.log(`ESM HOOK(${W.threadId}) -> RESOLVE -> ${specifier}`);
-    let isFlaggedToPatch = false;
-    if (context.parentURL) {
-      isFlaggedToPatch = context.parentURL.endsWith('csi-flag=', context.parentURL.length - 1);
-    }
-
-    // this needs to be generalized so it uses the execArgv value. the idea is to
-    // capture when the application actually starts. is this needed? i don't think so
-    // because the loaders aren't instantiated until esm-loader.mjs returns/register()s
-    // the hooks. i am leaving the comment here as a breadcrumb in case we need to
-    // capture the application start time. but we could 1) look at process.argv, 2)
-    // find the first argument, and 3) notice when that's loaded and capture that
-    // "now we are in the user's application".
-    //
-    //if (false) debugger;
-    //if (log & logApplication) {
-    //  const RE = /test-integration-servers\/express.m?js(\?.+)?$/;
-    //  if (specifier.match(RE) || context.parentURL?.match(RE)) {
-    //    console.log(`ESM HOOK(${W.threadId}) -> RESOLVE -> ${specifier} from ${context.parentURL}`);
-    //  }
-    //}
-
-    // this works for most of what we need to patch because they are not esm-native
-    // modules. but for esm-native modules, e.g., node-fetch, this won't work. they
-    // will need to be patched in the loader thread.
-    //
-    // We could walk up the parent chain to see if we should interpret this specifier
-    // as a module or commonjs, but it seems more straightforward to just always
-    // redirect. walking up the parent chain would let us avoid redirecting commonjs
-    // files. we could also call nextResolve() and let node tell us type of the file
-    // is but that would potentially create problems when other hooks, e.g., datadog,
-    // are in place.
-    //
-    // also we could check to see if this module's already been patched and skip this.
-    // not sure of that though; it might get loaded as a module, not a commonjs file,
-    // and that would be a problem. so when we start patching esm-native modules, we'll
-    // need a second "already patched" weakmap.
-    if (!isFlaggedToPatch && specifier in mappings) {
-      // eslint-disable-next-line prefer-const
-      let { url, format, target } = mappings[specifier];
-      // set flag to module or commonjs. i'm not sure this is needed but am keeping it
-      // in place until we have to implement esm-native module rewrites/wrapping. this
-      // is the point at which resolve() communicates to load().
-      //
-      // builtin's are probably the most likely to be loaded, so they're first.
-      // some tweaks might be needed when we start to patch esm-native modules
-      // in esm-native-code:
-      // https://nodejs.org/docs/latest-v20.x/api/esm.html#builtin-modules
-      // https://nodejs.org/docs/latest-v20.x/api/module.html#modulesyncbuiltinesmexports
-      if (target === 'builtin') {
-        url = `${url.href}?csi-flag=m`;
-        format = 'module';
-      } else if (target === 'commonjs') {
-        url = `${url.href}?csi-flag=c`;
-        format = getFileType(url) || format || 'commonjs';
-      } else if (target === 'module') {
-        url = `${url.href}?csi-flag=m`;
-        format = getFileType(url) || format || 'module';
-      } else {
-        throw new Error(`unexpected target ${target} for ${specifier}`);
-      }
-
-      return {
-        url,
-        format,
-        shortCircuit: true,
-      };
-    }
-
-    return protectedNextResolve(nextResolve, specifier, context);
-  };
-
-  // readFile is a live binding. we need to capture it so it won't be
-  // altered by any patching later.
-  const readFile = rf;
-
-  load = async function(url, context, nextLoad) {
-    (log & logLoad) && console.log(`ESM HOOK(${W.threadId}) -> LOAD ${url}`);
-
-    const urlObject = new URL(url);
-
-    if (urlObject.searchParams.has('csi-flag')) {
-      // target type will, i think, be used to determine if this will require extra
-      // processing of some sort for esm-native modules.
-      // eslint-disable-next-line no-unused-vars
-      const targetType = urlObject.searchParams.get('csi-flag');
-      const { pathname } = urlObject;
-
-      (log & logLoad) && console.log(`ESM HOOK(${W.threadId}) -> LOAD -> CSI FLAG ${pathname}`);
-
-      const source = await readFile(fixPath(pathname), 'utf8');
-      return {
-        source,
-        format: 'module',
-        shortCircuit: true,
-      };
-    }
-
-    if (urlObject.pathname.endsWith('.node')) {
-      const metaUrl = JSON.stringify(url);
-      const addon = urlObject.pathname;
-      return {
-        source: `require("node:module").createRequire(${metaUrl})("${addon}")`,
-        format: 'commonjs',
-        shortCircuit: true,
-      };
-    }
-
-    // if it's not a builtin, a .node addon, or a flagged file, it needs to be
-    // rewritten if it's a module.
-    if (urlObject.pathname.match(/(.js|.mjs|.cjs)$/)) {
-      // if it's not a module it will be rewritten by the require hooks.
-      const type = getFileType(urlObject);
-      if (type !== 'module') {
-        return nextLoad(url, context);
-      }
-
-      const filename = fixPath(urlObject.pathname);
-      const source = await readFile(filename, 'utf8');
-
-      const rewriteOptions = {
-        filename,
-        isModule: type === 'module',
-        inject: true,
-        wrap: type !== 'module', // cannot wrap modules
-      };
-
-      core.threadInfo.post('rewrite', rewriteOptions);
-
-      const result = core.rewriter.rewrite(source, rewriteOptions);
-
-      return {
-        source: result.code,
-        format: type || 'commonjs', // don't know what else to do here. log?
-        shortCircuit: true,
-      };
-    }
-    // this never gets called, so hmmm.
-    return nextLoad(url, context);
-  };
-}
-
-export {
-  load,
-  resolve,
-  initialize,
-  // TODO: add for testing/verification
-  //loaderIsVerified as default
-};

package/lib/initialize.mjs

@@ -1,133 +0,0 @@
-/*
- * 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.
- */
-
-// this file is the bootstrap for starting the agent's loader. it needs to be executed
-// in the main thread and the loader thread. it should not try to load all the modules
-// required to fully instantiate the agent, but only those required to make the loader
-// work.
-
-import { default as semver } from 'semver';
-import { default as Module } from 'node:module';
-import { isMainThread, threadId } from 'node:worker_threads';
-
-const require = Module.createRequire(import.meta.url);
-
-const {
-  name: agentName,
-  version: agentVersion,
-  engines: {
-    node: nodeEngine,
-    npm: npmEngine
-  }
-} = require('../package.json');
-
-const installOrder = [
-  'reporter',
-  'startupValidation',
-  'contrastMethods',
-  'deadzones',
-  'scopes',
-  'sources',
-  'architectureComponents',
-  'assess',
-  'protect',
-  'depHooks',
-  'esmHooks',
-  'routeCoverage',
-  'libraryAnalysis',
-  'heapSnapshots',
-  'rewriteHooks',
-  'functionHooks',
-  'metrics',
-];
-
-//
-// In order to avoid breaking every test and function in the agent, agentify
-// isn't changed at all; initialize() replaces it with new behavior.
-//
-import { loadModules, startAgent } from '@contrast/agentify/lib/initialize.mjs';
-
-let core;
-
-if (!core) {
-  // self-identification
-  const me = import.meta.url;
-  // we can determine when the app is being run by examining this
-  const argv = process.argv.slice();
-  // we can tell how the agent was started by examining this. --loader/--import must
-  // be correct for the node version.
-  const execArgv = process.execArgv.slice();
-
-  core = { agentName, agentVersion, me, argv, execArgv };
-
-  core = await loadModules({ core, options: {} });
-
-  if (core) core = await startAgent({ core, options: { executor, installOrder } });
-
-  // self identification
-  // for communications between the main and loader thread (if present)
-  if (core) core.threadInfo = {
-    isMainThread,
-    threadId,
-    port: undefined, // filled in if there's a loader thread
-    post: () => {}, // replaced by appropriate function
-  };
-
-  if (process.env.CSI_EXPOSE_CORE) {
-    const coreKey = Symbol.for('contrast:core');
-    global[coreKey] = core;
-  }
-}
-
-export default core;
-
-async function executor(core) {
-  if (!semver.satisfies(process.version, nodeEngine)) {
-    let validRanges = '';
-    nodeEngine.split('||').forEach((range) => {
-      const minVersion = semver.minVersion(range).toString();
-      const maxVersion = range.split('<').pop()
-        .trim();
-      validRanges += `${minVersion} and ${maxVersion}, `;
-    });
-    throw new Error(`Contrast supports Node LTS versions between ${validRanges}but detected ${process.version}.`);
-  }
-
-  core.startupValidation = {
-    /**
-     *  This will run after we onboard to the UI and pick up any remote settings.
-     */
-    install() {
-      if (
-        isMainThread &&
-        !core.config.getEffectiveValue('assess.enable') &&
-        !core.config.getEffectiveValue('protect.enable')
-      ) {
-        throw new Error('Neither Assess nor Protect are enabled. Check local configuration and UI settings');
-      }
-    }
-  };
-
-  core.npmVersionRange = npmEngine;
-  if (isMainThread) {
-    require('@contrast/assess')(core);
-    require('@contrast/architecture-components')(core);
-    require('@contrast/library-analysis')(core);
-    require('@contrast/route-coverage')(core);
-    require('@contrast/protect')(core); // protect loads last; the other features are all passive
-  }
-
-  return core; // should this return core or just null/undefined?
-}