@contrast/esm-hooks 1.0.0

package/README.md

@@ -0,0 +1,21 @@
+### Using [ECMAScript Modules (ESM)](https://nodejs.org/docs/latest-v12.x/api/esm.html#esm_ecmascript_modules)
+
+> NOTE: ECMAScript instrumentation is experimental and Contrast requires at least Node version 14.15.0 for support.
+
+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.
+
+When instrumenting an application that utilizes ECMAScript Modules, use the
+following method to start the application. This is the appropriate method for
+instrumenting an application that uses CJS, ESM, or a combination of both.
+
+```
+    Usage: node --experimental-loader @contrast/protect/esm-loader.mjs index.mjs [agent arguments] -- [app arguments]
+
+    Options:
+
+        -h, --help               output usage information
+        -V, --version            output the version number
+        -c, --configFile <path>  path to agent config file
+```

package/lib/get-file-type.mjs

@@ -0,0 +1,27 @@
+import path from 'path';
+import parent from 'parent-package-json';
+
+export default function getType(filename) {
+
+  let pathname = filename.pathname || filename;
+
+  if (pathname.startsWith('node:')) {
+    return 'builtin';
+  }
+  pathname = pathname.replace('file://', '');
+
+  let parentType = 'commonjs';
+  try {
+    parentType = parent(pathname).parse().type;
+  } catch (err) {
+    // Node assumes `commonjs ` if there's no `type` set in package.json
+  }
+
+  const ext = path.extname(pathname);
+  if (ext === '.mjs' || (ext === '.js' && parentType === 'module')) {
+    return 'module';
+  } else if (ext === '.cjs' || (ext === '.js' && parentType !== 'module')) {
+    return 'commonjs';
+  }
+  return 'unknown';
+}

package/lib/index.mjs

@@ -0,0 +1,66 @@
+import { promises as fs } from 'fs';
+import { fileURLToPath } from 'url';
+import initCore from '@contrast/core';
+import getType from './get-file-type.mjs';
+
+export default function (core = initCore()) {
+
+  const esmHooks = {
+
+    async getSource(url, context, defaultGetSource) {
+      const filename = fileURLToPath(url);
+      core.logger.trace('getSource %s', filename);
+      return defaultGetSource(url, context, defaultGetSource);
+    },
+
+    async transformSource(source, context, defaultTransformSource) {
+      let result;
+      const filename = fileURLToPath(context.url);
+      core.logger.trace('transformSource %s', filename);
+      try {
+        result = core.rewriter.rewrite(source.toString(), { filename, sourceType: 'module' });
+        return { source: result.code };
+      } catch (err) {
+        core.logger.error(
+          { err, result },
+          'Failed to compile rewritten code for %s. compiling original code.',
+          filename,
+        );
+        return defaultTransformSource(source, context, defaultTransformSource);
+      }
+    },
+
+    async  load(url, context, defaultLoad) {
+      const type = getType(url);
+
+      if (type === 'builtin' || type === 'unknown') {
+        core.logger.debug(
+          'Skipping rewrite for %s module %s, loading original code',
+          type,
+          url
+        );
+        return defaultLoad(url, context, defaultLoad);
+      }
+
+      const filename = fileURLToPath(url);
+      core.logger.trace('load %s', filename);
+
+      let result;
+      try {
+        const source = await fs.readFile(filename, 'utf8');
+        result = core.rewriter.rewrite(source, { filename, sourceType: type === 'commonjs' ? 'script' : 'module' });
+        return { format: type, source: result.code };
+      } catch (err) {
+        core.logger.error(
+          { err, result },
+          'Failed to load rewritten code for %s. loading original code.',
+          filename,
+        );
+        return defaultLoad(url, context, defaultLoad);
+      }
+    }
+  };
+
+  core.esmHooks = esmHooks;
+  return core.esmHooks;
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@contrast/esm-hooks",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Support for loading and instrumenting ECMAScript modules",
+  "license": "UNLICENSED",
+  "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
+  "main": "lib/index.mjs",
+  "engines": {
+    "npm": ">= 8.4.0",
+    "node": ">= 14.15.0"
+  },
+  "scripts": {
+    "test": "../scripts/test.sh"
+  },
+  "dependencies": {
+    "@contrast/core": "^1.0.0",
+    "parent-package-json": "^2.0.1"
+  }
+}