@contrast/rewriter 1.4.1 → 1.5.0

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright: 2022 Contrast Security, Inc
+Copyright: 2024 Contrast Security, Inc
 Contact: support@contrastsecurity.com
 License: Commercial
 

package/README.md

@@ -2,32 +2,5 @@
 
 Rewrite javascript code with custom rewrite transforms.
 
-For example, Assess will register transforms for `+` -> `contrast_add()` so that it can perform propagation
-via instrumentation of `contrast_add()`.
-
-
-#### Example Service Usage
-
-```typescript
-const { Rewriter } = require('.');
-
-const rewriter = new Rewriter({ logger });
-
-rewriter.addTransforms({
-  BinaryExpression(path) {
-    const method = methodLookups[path.node.operator];
-    if (method) {
-      path.replaceWith(
-        t.callExpression(
-          expression('ContrastMethods.%%method%%')({ method }), [
-            path.node.left,
-            path.node.right
-          ]
-        )
-      );
-    }
-  }
-});
-
-const result = rewriter.rewrite('function add(x, y) { return x + y; }');
-```
+For example, Assess will register transforms for `+` -> `ContrastMethods.add()`
+so that it can perform propagation via instrumentation of `ContrastMethods.add()`.

package/lib/cache.js

@@ -0,0 +1,263 @@
+/*
+ * 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.
+ */
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const fsPromises = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+/**
+ * Returns the modification time of a file as a number.
+ * @param {string} filename
+ * @returns {Promise<number>}
+ */
+const mtime = async (filename) => +(await fsPromises.stat(filename)).mtime;
+
+/**
+ * Returns the modification time of a file as a number.
+ * @param {string} filename
+ * @returns {number}
+ */
+const mtimeSync = (filename) => +fs.statSync(filename).mtime;
+
+module.exports.Cache = class Cache {
+  /**
+   * @param {import('.').Core} core
+   */
+  constructor(core) {
+    this.config = core.config;
+    this.logger = core.logger.child({ name: 'contrast:rewriter:cache' });
+    /** @type {Set<import('.').Mode>} */
+    this.modes = new Set();
+    this.appDirRegex = new RegExp(`^${core.appInfo.app_dir.replace(/\\/g, '\\\\')}`);
+    this.cacheDir = path.join(
+      core.config.agent.node.rewrite.cache.path,
+      core.appInfo.name.replace('/', '_'),
+      core.agentVersion,
+    );
+  }
+
+  /**
+   * Sets the rewriter to 'assess' or 'protect' mode, enabling different
+   * transforms.
+   * @param {import('.').Mode} mode
+   */
+  install(mode) {
+    this.modes.add(mode);
+  }
+
+  /**
+   * Returns the filename of a cached rewrite result. Paths within the `app_dir`
+   *  directory are nested under the `_` directory to prevent potential
+   *  collisions with absolute paths.
+   *   /path/to/app/node_modules/mod/index.js
+   *      -> '.contrast/app_name/5.1.2/assess/_/node_modules/mod/index.js
+   *   /somewhere/else/index.js
+   *      -> .contrast/app_name/5.1.2/assess/somewhere/else/index.js
+   * @param {string} filename
+   * @returns {string}
+   */
+  getCachedFilename(filename) {
+    filename = filename.replace(this.appDirRegex, '_');
+
+    if (os.platform() === 'win32') {
+      filename = filename.replace(/^([A-Za-z]):/, '$1_');
+    }
+
+    return path.join(
+      this.cacheDir,
+      this.modes.has('assess') ? 'assess' : 'protect',
+      filename,
+    );
+  }
+
+  /**
+   * Looks up and returns the string content of a previously rewritten file
+   * asynchronously.
+   * @param {string} filename
+   * @returns {Promise<string | undefined>}
+   */
+  async read(filename) {
+    const filenameCached = this.getCachedFilename(filename);
+
+    try {
+      const [time, timeCached] = await Promise.all([mtime(filename), mtime(filenameCached)]);
+      if (time > timeCached) {
+        this.logger.trace(
+          {
+            filename,
+            filenameCached,
+            mtime: time,
+            mtimeCached: timeCached,
+          },
+          'Cache stale, falling back to compiling.'
+        );
+
+        return undefined;
+      }
+
+      this.logger.trace(
+        {
+          filename,
+          filenameCached,
+          mtime: time,
+          mtimeCached: timeCached,
+        },
+        'Cache current.'
+      );
+
+      return fsPromises.readFile(filenameCached, 'utf8');
+    } catch (err) {
+      // @ts-expect-error ts treats errors poorly.
+      if (err.code !== 'ENOENT') {
+        this.logger.error(
+          { err, filename, filenameCached },
+          'An unexpected error occurred, falling back to compiling.'
+        );
+      } else {
+        this.logger.trace(
+          { filename, filenameCached },
+          'Cache miss, falling back to compiling.',
+        );
+      }
+
+      return undefined;
+    }
+  }
+
+  /**
+   * Looks up and returns the source map for a previously rewritten file.
+   * @param {string} filename
+   * @returns {Promise<string | undefined>}
+   */
+  async readMap(filename) {
+    const filenameCached = this.getCachedFilename(filename);
+    const sourceMap = `${filenameCached}.map`;
+
+    try {
+      return fsPromises.readFile(sourceMap, 'utf8');
+    } catch (err) {
+      // @ts-expect-error ts treats errors poorly.
+      if (err.code !== 'ENOENT') {
+        this.logger.warn(
+          { err, filename, filenameCached, sourceMap },
+          'An unexpected error occurred finding source map.'
+        );
+      }
+      return undefined;
+    }
+  }
+
+  /**
+   * Looks up and returns the string content of a previously rewritten file
+   * synchronously. Used when we need to block on cache lookups.
+   * @param {string} filename
+   * @returns {string | undefined}
+   */
+  readSync(filename) {
+    const filenameCached = this.getCachedFilename(filename);
+
+    try {
+      const time = mtimeSync(filename);
+      const timeCached = mtimeSync(filenameCached);
+      if (time > timeCached) {
+        this.logger.trace(
+          {
+            filename,
+            filenameCached,
+            mtime: time,
+            mtimeCached: timeCached,
+          },
+          'Cache stale, falling back to compiling.'
+        );
+
+        return undefined;
+      }
+
+      this.logger.trace(
+        {
+          filename,
+          filenameCached,
+          mtime: time,
+          mtimeCached: timeCached,
+        },
+        'Cache current.'
+      );
+
+      return fs.readFileSync(filenameCached, 'utf8');
+    } catch (err) {
+      // @ts-expect-error ts treats errors poorly.
+      if (err.code !== 'ENOENT') {
+        this.logger.error(
+          { err, filename, filenameCached },
+          'An unexpected error occurred, falling back to compiling.'
+        );
+      } else {
+        this.logger.trace(
+          { filename, filenameCached },
+          'Cache miss, falling back to compiling.',
+        );
+      }
+
+      return undefined;
+    }
+  }
+
+  /**
+   * Writes a rewritten file to the cache directory. Runs asynchronously so that
+   * disk I/O doesn't impact startup times, regardless of whether we're in a CJS
+   * or ESM environment.
+   * @param {string} filename
+   * @param {import('@swc/core').Output} result
+   */
+  async write(filename, result) {
+    const filenameCached = this.getCachedFilename(filename);
+
+    try {
+      await fsPromises.mkdir(path.dirname(filenameCached), { recursive: true });
+
+      const writePromises = [
+        fsPromises.writeFile(filenameCached, result.code, 'utf8')
+      ];
+
+      if (result.map) {
+        writePromises.push(
+          fsPromises.writeFile(`${filenameCached}.map`, result.map, 'utf8')
+        );
+      }
+
+      await Promise.all(writePromises);
+
+      this.logger.trace(
+        {
+          filename,
+          filenameCached,
+        },
+        'Cache entry created.'
+      );
+    } catch (err) {
+      this.logger.warn(
+        {
+          err,
+          filename,
+          filenameCached,
+        },
+        'Unable to cache rewrite results.'
+      );
+    }
+  }
+};

package/lib/index.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2022 Contrast Security, Inc
+ * Copyright: 2024 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 
@@ -13,25 +13,100 @@
  * way not consistent with the End User License Agreement.
  */
 // @ts-check
-
 'use strict';
 
-const { transformSync } = require('@swc/core');
-const Module = require('module');
+const { transform, transformSync } = require('@swc/core');
+const Module = require('node:module');
+const { Cache } = require('./cache');
 
-const rewriterPath = require.resolve('@contrast/agent-swc-plugin');
-const unwriterPath = require.resolve('@contrast/agent-swc-plugin-unwrite');
+/**
+ * @typedef {Object} Core
+ * @prop {import('@contrast/common').AppInfo} appInfo
+ * @prop {string} agentVersion
+ * @prop {import('@contrast/config').Config} config
+ * @prop {import('@contrast/logger').Logger} logger
+ */
+/**
+ * @typedef {'assess' | 'protect'} Mode
+ */
+/**
+ * @typedef {Object} RewriteOpts
+ * @prop {string=} filename e.g. 'index.js'
+ * @prop {boolean=} isModule if true, file is parsed as an ES module instead of a CJS script
+ * @prop {boolean=} inject if true, injects ContrastMethods on the global object
+ * @prop {boolean=} wrap if true, wraps the content with a modified module wrapper IIFE
+ * @prop {boolean=} trim if true, removes added characters from the end of the generated code
+ */
 
 // @ts-expect-error `wrapper` is missing from @types/node
 const prefix = Module.wrapper[0];
 // @ts-expect-error `wrapper` is missing from @types/node
 const suffix = Module.wrapper[1].replace(/;$/, '.apply(this, arguments);');
 
-/** @typedef {'assess' | 'protect'} Mode */
+const rewriterPath = require.resolve('@contrast/agent-swc-plugin');
+const unwriterPath = require.resolve('@contrast/agent-swc-plugin-unwrite');
+
+/**
+ * Wraps the source content as necessary to support rewriting.
+ * Wrapping must occur before rewriting since the underlying rewriter cannot
+ * parse certain valid statements such as `return` statements in a CJS script.
+ * @param {string} content
+ * @returns {string}
+ */
+const wrap = (content) => {
+  let shebang = '';
+
+  // The shebang will be commented out since it cannot be present in a
+  // function body. swc doesn't include the commented shebang in the generated
+  // code despite including comments otherwise.
+  if (content.charAt(0) === '#') {
+    shebang = content.substring(0, content.indexOf('\n') + 1);
+    content = `//${content}`;
+  }
+
+  content = `${shebang}${prefix}${content}${suffix}`;
+
+  return content;
+};
+
+/**
+ * Trims extraneous characters that may have been added by the rewriter.
+ * Handles newline or semicolon insertion, removing the added characters if they
+ * were not present in the original source content.
+ * @param {string} content
+ * @param {import('@swc/core').Output} result
+ * @returns {import('@swc/core').Output}
+ */
+const trim = (content, result) => {
+  let carriageReturn = 0;
+  // swc always adds a newline, so we only need to check the input
+  if (!content.endsWith('\n')) {
+    result.code = result.code.substring(0, result.code.length - 1);
+  } else if (content.endsWith('\r\n')) {
+    // if EOL is \r\n, then we need to account for that when we check the
+    // negative index of the last semicolon below
+    carriageReturn = 1;
+  }
+  const resultSemicolonIdx = result.code.lastIndexOf(';');
+  const contentSemicolonIdx = content.lastIndexOf(';');
+  if (contentSemicolonIdx === -1 || resultSemicolonIdx - result.code.length !== contentSemicolonIdx - content.length + carriageReturn) {
+    result.code = result.code.substring(0, resultSemicolonIdx) + result.code.substring(resultSemicolonIdx + 1, result.code.length);
+  }
+
+  return result;
+};
 
-const rewriter = {
-  /** @type {Set<Mode>} */
-  modes: new Set(),
+class Rewriter {
+  /**
+   * @param {Core} core
+   */
+  constructor(core) {
+    this.core = core;
+    this.logger = core.logger.child({ name: 'contrast:rewriter' });
+    /** @type {Set<Mode>} */
+    this.modes = new Set();
+    this.cache = new Cache(core);
+  }
 
   /**
    * Sets the rewriter to 'assess' or 'protect' mode, enabling different
@@ -39,94 +114,113 @@ const rewriter = {
    * @param {Mode} mode
    */
   install(mode) {
+    this.logger.trace('installing rewriter mode: %s', mode);
     this.modes.add(mode);
-  },
+    this.cache.install(mode);
+  }
 
   /**
-   * @param {string} content the source code
-   * @param {object} opts
-   * @param {string=} opts.filename e.g. 'index.js'
-   * @param {boolean=} opts.isModule if true, file is parsed as an ES module instead of a CJS script
-   * @param {boolean=} opts.inject if true, injects ContrastMethods on the global object
-   * @param {boolean=} opts.wrap if true, wraps the content with a modified module wrapper IIFE
-   * @returns {import("@swc/core").Output}
+   * @param {RewriteOpts} opts
+   * @returns {import('@swc/core').Options}
    */
-  rewrite(content, opts = {}) {
-    let shebang = '';
-
-    if (content.charAt(0) === '#') {
-      shebang = content.substring(0, content.indexOf('\n') + 1);
-      // see the test output: swc doesn't include the commented shebang in the generated code despite including comments otherwise
-      content = `//${content}`;
-    }
-
-    if (opts.wrap) {
-      content = `${shebang}${prefix}${content}${suffix}`;
-    }
-
-    const result = transformSync(content, {
+  rewriteConfig(opts) {
+    return {
       filename: opts.filename,
       isModule: opts.isModule,
+      env: {
+        targets: {
+          node: process.versions.node
+        }
+      },
       jsc: {
-        target: 'es2019', // should work for node >14
         experimental: {
-          plugins: [
-            [
-              rewriterPath,
-              {
-                assess: this.modes.has('assess'),
-                inject: this.modes.has('assess') && opts.inject,
-              },
-            ],
-          ],
+          plugins: [[rewriterPath, {
+            assess: this.modes.has('assess'),
+            inject: opts.inject,
+          }]],
         },
       },
-      sourceMaps: true,
-    });
-
-    if (!opts.wrap) {
-      let carriageReturn = 0;
-      // swc always adds a newline, so we only need to check the input
-      if (!content.endsWith('\n')) {
-        result.code = result.code.substring(0, result.code.length - 1);
-      } else if (content.endsWith('\r\n')) {
-        // if EOL is \r\n, then we need to account for that when we check the
-        // negative index of the last semicolon below
-        carriageReturn = 1;
-      }
-      const resultSemicolonIdx = result.code.lastIndexOf(';');
-      const contentSemicolonIdx = content.lastIndexOf(';');
-      if (contentSemicolonIdx === -1 || resultSemicolonIdx - result.code.length !== contentSemicolonIdx - content.length + carriageReturn) {
-        result.code = result.code.substring(0, resultSemicolonIdx) + result.code.substring(resultSemicolonIdx + 1, result.code.length);
-      }
+      // if we're trimming the output we're not rewriting an entire file, which
+      // means source maps are not relevant.
+      sourceMaps: !opts.trim && this.core.config.agent.node.source_maps.enable,
+    };
+  }
+
+  /**
+   * Rewrites the provided source code string asynchronously to be consumed by
+   * ESM hooks.
+   * @param {string} content
+   * @param {RewriteOpts=} opts
+   * @returns {Promise<import('@swc/core').Output>}
+   */
+  async rewrite(content, opts = {}) {
+    this.logger.trace({ opts }, 'rewriting %s', opts.filename);
+
+    if (opts.wrap) {
+      content = wrap(content);
+    }
+
+    let result = await transform(content, this.rewriteConfig(opts));
+
+    if (opts.trim) {
+      result = trim(content, result);
+    }
+
+    return result;
+  }
+
+  /**
+   * Rewrites the provided source code string synchronously to be consumed by
+   * CJS hooks.
+   * @param {string} content
+   * @param {RewriteOpts=} opts
+   * @returns {import('@swc/core').Output}
+   */
+  rewriteSync(content, opts = {}) {
+    this.logger.trace({ opts }, 'rewriting %s', opts.filename);
+
+    if (opts.wrap) {
+      content = wrap(content);
+    }
+
+    let result = transformSync(content, this.rewriteConfig(opts));
+
+    if (opts.trim) {
+      result = trim(content, result);
     }
 
     return result;
-  },
+  }
 
   /**
+   * Removes contrast-related rewritten code from provided source code string.
    * @param {string} content
    * @returns {string}
    */
-  unwrite(content) {
+  unwriteSync(content) {
     return transformSync(content, {
+      env: {
+        targets: {
+          node: process.versions.node
+        }
+      },
       jsc: {
-        target: 'es2019', // should work for node >14
         experimental: {
           plugins: [[unwriterPath, {}]],
         },
       },
+      sourceMaps: false,
     }).code;
-  },
-};
-
-/** @typedef {typeof rewriter} Rewriter */
+  }
+}
 
 /**
- * @param {{ rewriter: Rewriter }} core
+ * @param {Core & { rewriter?: Rewriter; }} core
  * @returns {Rewriter}
  */
 module.exports = function init(core) {
-  core.rewriter = rewriter;
-  return rewriter;
+  core.rewriter = new Rewriter(core);
+  return core.rewriter;
 };
+
+module.exports.Rewriter = Rewriter;

package/lib/source-maps.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2022 Contrast Security, Inc
+ * Copyright: 2024 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 
@@ -19,27 +19,26 @@ const { readFileSync, existsSync } = require('fs');
 const { transfer } = require('multi-stage-sourcemap');
 const { SourceMapConsumer } = require('@contrast/synchronous-source-maps');
 
-module.exports = function(deps) {
+module.exports = function (deps) {
   const sourceMaps = deps.rewriter.sourceMaps = {};
   const consumerCache = sourceMaps.consumerCache = {};
 
-  sourceMaps.cacheConsumerMap = function(filename, map) {
+  sourceMaps.cacheConsumerMap = function (filename, map) {
     consumerCache[filename] = new SourceMapConsumer(map);
   };
 
   /**
    */
-  sourceMaps.chain = function(filename, map) {
+  sourceMaps.chain = function (filename, map) {
     let ret;
 
     if (existsSync(`${filename}.map`)) {
       try {
         const existingMap = JSON.parse(readFileSync(`${filename}.map`, 'utf8'));
         ret = transfer({ fromSourceMap: map, toSourceMap: existingMap });
-        deps.logger.trace(`Merged sourcemap from ${filename}.map`);
-      } catch (e) {
-        deps.logger.debug(`Unable to read ${filename}.map.js`);
-        deps.logger.debug(`${e}`);
+        deps.logger.trace('Merged sourcemap from %s.map', filename);
+      } catch (err) {
+        deps.logger.debug({ err }, 'Unable to read %s.map.js', filename);
       }
     }
 

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "@contrast/rewriter",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A transpilation tool mainly used for instrumentation",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
-  "files": [
-    "lib/"
-  ],
   "main": "lib/index.js",
-  "types": "lib/index.d.ts",
+  "types": "types/index.d.ts",
   "engines": {
     "npm": ">=6.13.7 <7 || >= 8.3.1",
     "node": ">= 14.15.0"
@@ -17,10 +14,11 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/agent-swc-plugin": "^1.1.0",
-    "@contrast/agent-swc-plugin-unwrite": "^1.1.0",
+    "@contrast/agent-swc-plugin": "^1.3.0",
+    "@contrast/agent-swc-plugin-unwrite": "^1.3.0",
+    "@contrast/common": "^1.16.0",
     "@contrast/synchronous-source-maps": "^1.1.3",
     "@swc/core": "1.3.39",
     "multi-stage-sourcemap": "^0.3.1"
   }
-}
+}