@contrast/esm-hooks 2.2.1 → 2.4.0

package/lib/common.mjs

@@ -0,0 +1,136 @@
+/*
+ * 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 { readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+const REDIRECTS_PATH = './redirects';
+
+export const mappings = await makeMappings();
+
+// why do we need to fix paths? Because windows, node, and URLs don't get
+// along very well.
+//
+// the load() hook receives an URL. When the URL is converted into an URL object,
+// the pathname property will be '/C:/Users/.../redirects' on windows. And that
+// doesn't start with a drive letter, so when fsp.readdir() gets it, node decides
+// to add a drive letter: 'C:/C:/Users/.../redirects'. So we have to strip off the
+// the leading / so the drive letter is recognized and another isn't added. it seems
+// like a node bug (or possibly windows bug) but i don't have time to research the
+// standards to figure out what URL.pathname should be in a windows file: context.
+//
+// maybe this should be in the load() hook?
+//
+// should
+/**
+ *
+ * @param {string} path
+ * @returns {string}
+ */
+export function fixPath(p) {
+  if (p.match(/^\/[A-Z]:/)) {
+    p = p.slice(1);
+  }
+  return p;
+}
+
+import { getFileType } from './get-file-type.mjs';
+export { getFileType };
+
+async function makeMappings() {
+  /**
+   * @typedef { 'builtin' | 'commonjs' | 'module' } TargetType
+   * @typedef {string} RequireSpecifier
+   */
+  /**
+   * @type {Record<RequireSpecifier, {url: URL, target: TargetType}>}
+   */
+  const mappings = Object.create(null);
+
+  // the name of the directory is the format of the target being loaded. so "cjs"
+  // means the target is a commonjs module that will be loaded via require(),
+  // "builtin" means the target is a builtin, and "esm" (when it's added) will
+  // mean that the target is a native esm module.
+  //
+  // at this time, all "builtin" modules are "cjs" modules and can be required.
+  // and all "cjs" modules are commonjs modules that can be required. The reason
+  // they need to be here is that they might be loaded by the ESM loader in the
+  // background thread, so we need to redirect them to the commonjs loader.
+  //
+  // all files in the "redirects" directory are .mjs files.
+  //
+  // 'esm' does not currently have any redirect files; there is one example file
+  // for node-fetch, but it does not have the extension .mjs, so it won't be used.
+  // 'esm' will be needed when we have to patch an esm-native file.
+  for (const dir of ['builtin', 'cjs', 'esm']) {
+    // keep track of recursive calls to handle nested directories, e.g., fs/promises
+    const pathStack = [];
+
+    // get an absolute path because reading the redirect file is going to be executed
+    // in another context.
+    const p = path.join(REDIRECTS_PATH, dir);
+    const redirectDir = new URL(p, import.meta.url);
+    const dirpath = fixPath(redirectDir.pathname);
+
+    await recursiveReaddir(dirpath);
+
+    // eslint-disable-next-line no-inner-declarations
+    async function recursiveReaddir(dirpath) {
+      const dirents = await readdir(dirpath, { withFileTypes: true });
+      for (const dirent of dirents) {
+        if (dirent.isDirectory()) {
+          const { name: subdir } = dirent;
+          const subp = path.join(dirpath, subdir);
+          pathStack.push(subdir);
+          await recursiveReaddir(subp);
+          pathStack.pop();
+          continue;
+        }
+        if (!dirent.name.endsWith('.mjs')) {
+          continue;
+        }
+        // it a file that ends with .mjs, so it's a redirect file.
+        const redirectURL = new URL(path.join(p, ...pathStack, dirent.name), import.meta.url);
+
+        // all redirects point to .mjs files; the target property specifies the type of the
+        // the file that will be loaded by the .mjs. target. target is builtin, commonjs, or
+        // module.
+        // e.g., //'node-fetch': {url: new URL(`${p}/node-fetch.mjs`, import.meta.url), target: 'module'},
+        //
+        // there is a separate builtin directory because putting a colon in a filename doesn't work on windows. so
+        // that's why the mapping below adds the `node:` prefix.
+        let name = path.basename(dirent.name, '.mjs');
+        if (pathStack.length) {
+          name = `${pathStack.join('/')}/${name}`;
+        }
+        if (dir === 'builtin') {
+          mappings[name] = { url: redirectURL, target: 'builtin' };
+          mappings[`node:${name}`] = { url: redirectURL, target: 'builtin' };
+        } else if (dir === 'cjs') {
+          mappings[name] = { url: redirectURL, target: 'commonjs' };
+        } else if (dir === 'esm') {
+          mappings[name] = { url: redirectURL, target: 'module' };
+        } else {
+          throw new Error(`target type ${dir} not yet implemented`);
+        }
+      }
+    }
+  }
+
+  return mappings;
+}
+
+// useful for tests
+export { makeMappings };

package/lib/debug-methods.mjs

@@ -0,0 +1,84 @@
+/*
+ * 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 * as process from 'node:process';
+import { threadId as tid } from 'node:worker_threads';
+
+const DEFAULT_OPTS = { mask: process.env.CSI_HOOKS_LOG, install: true };
+const LOG_LOAD = 1;
+const LOG_RESOLVE = 2;
+const LOG_REQUIRE_ALL = 4;
+
+export default function init(core, opts = DEFAULT_OPTS) {
+  const { esmHooks } = core;
+
+  if (!opts.mask) return;
+  const LOG = +opts.mask;
+
+  Object.assign(esmHooks, {
+    _rawDebug(value) {
+      process._rawDebug(value);
+    },
+    debugCjsCompile(filename) {
+      (LOG & LOG_REQUIRE_ALL) && esmHooks._rawDebug(`CJS(${tid}) _compile() ${filename}`);
+    },
+    debugCjsExtensions(filename) {
+      (LOG & LOG_REQUIRE_ALL) && esmHooks._rawDebug(`CJS(${tid}) extensions.js() ${filename}`);
+    },
+    debugCjsLoad(request) {
+      (LOG & LOG_LOAD) && esmHooks._rawDebug(`CJS(${tid}) _load() ${request}`);
+    },
+    debugCjsRequire(moduleId) {
+      (LOG & LOG_REQUIRE_ALL) && esmHooks._rawDebug(`CJS(${tid}) require() ${moduleId}`);
+    },
+    debugEsmInitialize(specifier) {
+      LOG && esmHooks._rawDebug(`ESM(${tid}) initialize() ${specifier}`);
+    },
+    debugEsmResolve(specifier) {
+      (LOG & LOG_RESOLVE) && esmHooks._rawDebug(`ESM(${tid}) resolve() ${specifier}`);
+    },
+    debugEsmLoad(url) {
+      (LOG & LOG_LOAD) && esmHooks._rawDebug(`ESM(${tid}) load() ${url}`);
+    },
+  });
+
+  if (opts.install) {
+    const originalRequire = Module.prototype.require;
+    Module.prototype.require = function(moduleId) {
+      esmHooks.debugCjsRequire(moduleId);
+      return originalRequire.call(this, moduleId);
+    };
+
+    const originalCompile = Module.prototype._compile;
+    Module.prototype._compile = function(code, filename) {
+      esmHooks.debugCjsCompile(filename);
+      return originalCompile.call(this, code, filename);
+    };
+
+    const originalExtensions = Module._extensions['.js'];
+    Module._extensions['.js'] = function(module, filename) {
+      esmHooks.debugCjsExtensions(filename);
+      return originalExtensions.call(this, module, filename);
+    };
+
+    const originalLoad = Module._load;
+    Module._load = function(request, parent, isMain) {
+      esmHooks.debugCjsLoad(request);
+      return originalLoad.call(this, request, parent, isMain);
+    };
+  }
+  return esmHooks;
+}

package/lib/hooks.mjs

@@ -0,0 +1,163 @@
+/*
+ * 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 { readFile as rf } from 'node:fs/promises';
+import * as process from 'node:process';
+import { fixPath, getFileType, mappings } from './common.mjs';
+import { default as initLoaderAgent } from './loader-agent.mjs';
+const [major, minor] = process.versions.node.split('.').map(it => +it);
+const isLT16_12 = major < 16 || (major === 16 && minor < 12);
+
+const readFile = rf;
+
+/**
+ * Agent instance with minimum footprint that handles functionality related esm module loading.
+ * - We handles redirects to force require.
+ * - Module rewriting via exported load hook
+ */
+let loaderAgent;
+
+/**
+ * @param {{
+ *   modes: string[],
+ *   port: import('node:worker_threads').MessagePort,
+ *   appInfo: import('@contrast/common').AppInfo,
+ *   agentVersion: string,
+ * }} data
+ */
+async function initialize(data = {}) {
+  loaderAgent = initLoaderAgent(data);
+  loaderAgent.esmHooks.debugEsmInitialize?.();
+  await loaderAgent.install();
+}
+
+async function resolve(specifier, context, nextResolve) {
+  loaderAgent?.esmHooks?.debugEsmResolve?.(specifier);
+
+  let isFlaggedToPatch = false;
+  if (context.parentURL) {
+    isFlaggedToPatch = context.parentURL.endsWith('csi-flag=', context.parentURL.length - 1);
+  }
+
+  if (loaderAgent?.enable && !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);
+}
+
+async function load(url, context, nextLoad) {
+  loaderAgent?.esmHooks?.debugEsmLoad?.(url);
+
+  const urlObject = new URL(url);
+
+  if (loaderAgent?.enable && urlObject.searchParams.has('csi-flag')) {
+    const { pathname } = urlObject;
+    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');
+    let result;
+
+    if (loaderAgent?.enable) {
+      const rewriteOptions = {
+        filename,
+        isModule: type === 'module',
+        inject: true,
+        wrap: type !== 'module', // cannot wrap modules
+      };
+      result = await loaderAgent.rewriter.rewrite(source, rewriteOptions);
+
+      if (process.env.CSI_EXPOSE_CORE) {
+        // only do this in testing scenarios (todo: compose this functionality into test agents instead)
+        loaderAgent.esmHooks.portClient.sendStatus('rewriting file during ESM load hook', rewriteOptions);
+      }
+    }
+
+    return {
+      source: result?.code || source,
+      format: type || 'commonjs', // don't know what else to do here. log?
+      shortCircuit: true,
+    };
+  }
+
+  // this never gets called, so hmmm.
+  return nextLoad(url, context);
+}
+
+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);
+}
+
+export { initialize, resolve, load };

package/lib/index.mjs

@@ -13,121 +13,65 @@
  * way not consistent with the End User License Agreement.
  */
 
-//
-// this file supports agent/lib/esm-hooks.mjs.
-//
+import Module from 'node:module';
+import { MessageChannel } from 'node:worker_threads';
+import { default as debugMethods } from './debug-methods.mjs';
+import { initialize, load, resolve } from './hooks.mjs';
+import { default as portClient } from './post-message/main-client.mjs';
 
-import { readdir } from 'node:fs/promises';
-import path from 'node:path';
+export default function init(core) {
+  const {
+    port1: mainPort,
+    port2: workerPort
+  } = new MessageChannel();
 
-const redirectPath = './redirects';
+  const esmHooks = core.esmHooks = {
+    hooks: { resolve, load }, // remove when all LTS versions support Module.register
+    getActiveModes() {
+      const modes = [];
+      if (core.config.getEffectiveValue('assess.enable')) {
+        modes.push('assess');
+      }
+      if (core.config.getEffectiveValue('protect.enable')) {
+        modes.push('protect');
+      }
+      return modes;
+    },
 
-// why do we need to fix paths? Because windows, node, and URLs don't get
-// along very well.
-//
-// the load() hook receives an URL. When the URL is converted into an URL object,
-// the pathname property will be '/C:/Users/.../redirects' on windows. And that
-// doesn't start with a drive letter, so when fsp.readdir() gets it, node decides
-// to add a drive letter: 'C:/C:/Users/.../redirects'. So we have to strip off the
-// the leading / so the drive letter is recognized and another isn't added. it seems
-// like a node bug (or possibly windows bug) but i don't have time to research the
-// standards to figure out what URL.pathname should be in a windows file: context.
-//
-// maybe this should be in the load() hook?
-//
+    /**
+     * Install AFTER we have onboarded with contrast-ui. This way we will have
+     * effective values for whether to enable protect/assess.
+     */
+    async install() {
+      const data = {
+        port: workerPort,
+        modes: esmHooks.getActiveModes(),
+        appInfo: core.appInfo,
+        agentVersion: core.agentVersion,
+      };
 
-import { fixPath, getFileType } from './get-file-type.mjs';
+      // Instantiate loader agent via register (if available) or manually.
+      // we can simplify when all LTS versions support register
+      if (Module.register) {
+        await Module.register(new URL('./hooks.mjs', import.meta.url).href, {
+          data,
+          transferList: [workerPort],
+        });
+      } else {
+        await initialize(data);
+      }
 
-// useful for tests
-export { makeMappings };
+      // these have side-effects, so compose during installation phase
+      debugMethods(core);
+    },
 
-export default async function init(core) {
-  return {
-    mappings: await makeMappings(),
-    fixPath,
-    getFileType,
+    async uninstall() {
+      // inform the loader agent it needs to disable and stop rewrites etc
+      esmHooks.portClient?.sendRPC?.('disable');
+    },
   };
-}
-
-async function makeMappings() {
-  /**
-   * @typedef { 'builtin' | 'commonjs' | 'module' } TargetType
-   * @typedef {string} RequireSpecifier
-   */
-  /**
-   * @type {Record<RequireSpecifier, {url: URL, target: TargetType}>}
-   */
-  const mappings = Object.create(null);
 
-  // the name of the directory is the format of the target being loaded. so "cjs"
-  // means the target is a commonjs module that will be loaded via require(),
-  // "builtin" means the target is a builtin, and "esm" (when it's added) will
-  // mean that the target is a native esm module.
-  //
-  // at this time, all "builtin" modules are "cjs" modules and can be required.
-  // and all "cjs" modules are commonjs modules that can be required. The reason
-  // they need to be here is that they might be loaded by the ESM loader in the
-  // background thread, so we need to redirect them to the commonjs loader.
-  //
-  // all files in the "redirects" directory are .mjs files.
-  //
-  // 'esm' does not currently have any redirect files; there is one example file
-  // for node-fetch, but it does not have the extension .mjs, so it won't be used.
-  // 'esm' will be needed when we have to patch an esm-native file.
-  for (const dir of ['builtin', 'cjs', 'esm']) {
-    // keep track of recursive calls to handle nested directories, e.g., fs/promises
-    const pathStack = [];
-
-    // get an absolute path because reading the redirect file is going to be executed
-    // in another context.
-    const p = path.join(redirectPath, dir);
-    const redirectDir = new URL(p, import.meta.url);
-    const dirpath = fixPath(redirectDir.pathname);
-
-    await recursiveReaddir(dirpath);
-
-    // eslint-disable-next-line no-inner-declarations
-    async function recursiveReaddir(dirpath) {
-      const dirents = await readdir(dirpath, { withFileTypes: true });
-      for (const dirent of dirents) {
-        if (dirent.isDirectory()) {
-          const { name: subdir } = dirent;
-          const subp = path.join(dirpath, subdir);
-          pathStack.push(subdir);
-          await recursiveReaddir(subp);
-          pathStack.pop();
-          continue;
-        }
-        if (!dirent.name.endsWith('.mjs')) {
-          continue;
-        }
-        // it a file that ends with .mjs, so it's a redirect file.
-        const redirectURL = new URL(path.join(p, ...pathStack, dirent.name), import.meta.url);
-
-        // all redirects point to .mjs files; the target property specifies the type of the
-        // the file that will be loaded by the .mjs. target. target is builtin, commonjs, or
-        // module.
-        // e.g., //'node-fetch': {url: new URL(`${p}/node-fetch.mjs`, import.meta.url), target: 'module'},
-        //
-        // there is a separate builtin directory because putting a colon in a filename doesn't work on windows. so
-        // that's why the mapping below adds the `node:` prefix.
-        let name = path.basename(dirent.name, '.mjs');
-        if (pathStack.length) {
-          name = `${pathStack.join('/')}/${name}`;
-        }
-        if (dir === 'builtin') {
-          mappings[name] = { url: redirectURL, target: 'builtin' };
-          mappings[`node:${name}`] = { url: redirectURL, target: 'builtin' };
-        } else if (dir === 'cjs') {
-          mappings[name] = { url: redirectURL, target: 'commonjs' };
-        } else if (dir === 'esm') {
-          mappings[name] = { url: redirectURL, target: 'module' };
-        } else {
-          throw new Error(`target type ${dir} not yet implemented`);
-        }
-      }
-    }
-  }
+  portClient(core, { port: mainPort });
 
-  return mappings;
+  return esmHooks;
 }

package/lib/loader-agent.mjs

@@ -0,0 +1,78 @@
+/*
+ * 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 { IntentionalError } from '@contrast/common';
+import { default as debugMethods } from './debug-methods.mjs';
+import { default as portClient } from './post-message/loader-client.mjs';
+const require = Module.createRequire(import.meta.url);
+
+// TODO: language
+const ERROR_MESSAGE = 'An error prevented the Contrast agent from initializing in the loader thread.';
+
+/**
+ * @param {{
+ *   modes: string[],
+ *   port: import('node:worker_threads').MessagePort,
+ *   appInfo: import('@contrast/common').AppInfo,
+ *   agentVersion: string,
+ * }} data
+ */
+export default function init({ appInfo, agentVersion, port, modes }) {
+  const core = {
+    appInfo,
+    agentVersion,
+    // this will toggle functionality in hooks.mjs e.g. redirects/rewriting
+    enable: true,
+    // stub for debugMethods
+    esmHooks: {},
+    async install() {
+      if (!modes?.length) {
+        throw new Error('worker agent invalid state: no modes');
+      }
+
+      for (const mode of modes) {
+        core.rewriter.install(mode);
+      }
+
+      debugMethods(core);
+      core.esmHooks?.portClient?.sendStatus?.('initialized and installed esm loader agent');
+    },
+    uninstall() {
+      core.enable = false;
+    },
+  };
+
+  try {
+    require('@contrast/core/lib/messages')(core);
+    require('@contrast/config')(core);
+    require('@contrast/logger').default(core);
+    require('@contrast/rewriter')(core);
+    portClient(core, { port });
+
+    return core;
+  } catch (err) {
+    core.enable = false;
+
+    // ignore intentional errors
+    if (!(err instanceof IntentionalError)) {
+      if (core.logger) {
+        core.logger.error({ err }, ERROR_MESSAGE);
+      } else {
+        console.error(new Error(ERROR_MESSAGE, { cause: err }));
+      }
+    }
+  }
+}

package/lib/post-message/loader-client.mjs

@@ -0,0 +1,58 @@
+/*
+ * 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 { Event } from '@contrast/common';
+import { send } from './send.mjs';
+
+/**
+ * Handles loader agent communication with the main agent's port client.
+ * Has API to send status messages to main agent e.g. for when it installs/uninstalls.
+ * Also listens for for TS settings updates and messages from main agent instructing it to disable.
+ * @param {any} core
+ * @param {Object} opts
+ * @param {import('node:worker_threads').MessagePort} opts.port
+*/
+export default function init(core, { port }) {
+  const portClient = core.esmHooks.portClient = {
+    _port: port,
+    _handlers: {
+      disable() {
+        core.uninstall?.();
+        portClient.sendStatus('loader agent has been uninstalled');
+      },
+    },
+    sendStatus(msg, data) {
+      send(port, { type: 'status', msg, data });
+    },
+  };
+
+  port.on('message', (raw) => {
+    if (raw?.type === Event.SERVER_SETTINGS_UPDATE) {
+      // forward main agent settings updates to loader components
+      core.messages.emit(Event.SERVER_SETTINGS_UPDATE, raw);
+    }
+
+    if (raw?.type === 'rpc') {
+      // dispatch appropriately
+      portClient._handlers[raw.action]?.(raw.data);
+    }
+  });
+
+  // do this after 'message' listeners are added, otherwise that process will automatically ref again
+  // https://nodejs.org/api/worker_threads.html#portunref
+  port.unref();
+
+  return portClient;
+}

package/lib/post-message/main-client.mjs

@@ -0,0 +1,66 @@
+/*
+ * 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 { Event } from '@contrast/common';
+import { send } from './send.mjs';
+
+/**
+ * Handles main agent communication with the loader agent's port client.
+ * Has API to forward events, and for sending RPC-like messages e.g. for instructing it to disable.
+ * Will listen for status messages from the loader agent and log them.
+ * @param {any} core
+ * @param {Object} opts
+ * @param {import('node:worker_threads').MessagePort} opts.port
+ */
+export default function init(core, { port }) {
+  const portClient = core.esmHooks.portClient = {
+    _port: port,
+    _handlers: {
+      status(msg, data) {
+        core.logger.trace({ name: 'contrast:esm:loader', data }, msg);
+      },
+    },
+    /**
+     * Forward events e.g. SERVER_SETTINGS_UPDATE
+     */
+    sendEvent(event, data) {
+      send(port, { type: event, ...data });
+    },
+    /**
+     * Tell the loader agent to do something e.g. disable/uninstall
+     */
+    sendRPC(action, data) {
+      send(port, { type: 'rpc', action, data });
+    },
+  };
+
+  // handling messages from loader agent
+  portClient._port.on('message', (raw) => {
+    if (raw?.type == 'status') {
+      portClient._handlers.status(raw.msg, raw.data);
+    }
+  });
+
+  // forward settings updates to loader agent via port
+  core.messages.on(Event.SERVER_SETTINGS_UPDATE, (msg) => {
+    portClient.sendEvent(Event.SERVER_SETTINGS_UPDATE, msg);
+  });
+
+  // do this after 'message' listeners are added, otherwise that process will automatically ref again
+  // https://nodejs.org/api/worker_threads.html#portunref
+  port.unref();
+
+  return portClient;
+}

package/lib/post-message/send.mjs

@@ -0,0 +1,25 @@
+/*
+ * 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 W from 'node:worker_threads';
+
+/**
+ * Wraps postMessage to handle generic message-sending activities e.g. enriching messages with tid.
+ * @param {W.MessagePort} port
+ * @param {any} data
+ */
+export function send(port, data) {
+  port.postMessage({ tid: W.threadId, ...data });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/esm-hooks",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "type": "module",
   "description": "Support for loading and instrumenting ECMAScript modules",
   "license": "SEE LICENSE IN LICENSE",
@@ -19,7 +19,8 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/core": "1.29.1",
+    "@contrast/common": "1.19.0",
+    "@contrast/core": "1.30.0",
     "@contrast/find-package-json": "^1.0.0"
   }
 }