jscrambler-metro-plugin 9.0.4 → 9.1.0

package/README.md

@@ -1,5 +1,5 @@
 # ![Jscrambler](https://media.jscrambler.com/images/logo_500px.png)
-# Jscrambler Code Integrity for React-Native (Metro Bundler)
+# Jscrambler Code Integrity for React-Native and Vega Os
 
 Jscrambler [Code Integrity](https://jscrambler.com/code-integrity) is a JavaScript protection technology for Web and Mobile Applications. Its main purpose is to enable JavaScript applications to become self-defensive and resilient to tampering and reverse engineering.
 
@@ -19,44 +19,75 @@ Please make sure you install the right version, otherwise some functionalities m
 
 # Usage
 
-This metro plugin protects your **React Native** bundle using Jscrambler.
+This metro plugin protects your [React Native](https://reactnative.dev/) and [Vega](https://developer.amazon.com/apps-and-games/vega) bundle using Jscrambler.
 
-Include the plugin in your `metro.config.js` and add the following code:
+First install the **jscrambler-metro-plugin** as a development dependency
 
-```js
-const {resolve} = require('path');
-const jscramblerMetroPlugin = require('jscrambler-metro-plugin')(
-  /* optional */
-  {
-    enable: true,
-    enabledHermes: true, // true by default. If you are not using Hermes engine, set to false
-    ignoreFile: resolve(__dirname, '.jscramblerignore'),
-    params: [
-      {
-        name: 'selfDefending',
-        options: {
-          threshold: 1
-        }
-      }
-    ]
-  }
-);
-
-module.exports = jscramblerMetroPlugin;
+```shell
+npm install -D jscrambler-metro.plugin
 ```
 
-You can pass your Jscrambler configuration using the plugin parameter or using
-the usual `.jscramblerrc` file.
+Then, set up the plugin in your `metro.config.js` by adding the following code:
 
-If you use a different location for the `.jscramblerignore` file, you can use the `ignoreFile` option to tell Jscrambler the path to the file.
-Otherwise, if a `.jscramblerignore` file is found in a project root folder, it will be considered. You can find more information and examples in Ignoring Files.
+```js
+const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
+const jscramblerMetroPlugin = require('jscrambler-metro-plugin')();
+
+/**
+ * Metro configuration
+ * https://reactnative.dev/docs/metro
+ *
+ * @type {import('@react-native/metro-config').MetroConfig}
+ */
+const config = {
+  ...jscramblerMetroPlugin
+};
+
+module.exports = mergeConfig(getDefaultConfig(__dirname), config);
+```
+
+Finally, create a `.jscramblerrc` file with your Jscrambler configuration downloaded from Code Integrity Application Dashboard.
 
 By default, Jscrambler protection is **ignored** when bundle mode is set for **Development**. You can override this behavior by setting env variable `JSCRAMBLER_METRO_DEV=true`
 
 In order to activate source map generation effectively, you will need to enable source maps both in the Jscrambler configuration file, by adding the following parameter to said file:
 
-...
-"sourceMaps": true,
-...
+```json
+{
+  ...
+ "sourceMaps": true,
+  ...
+}
+```
 
 and in the [React Native app](https://reactnative.dev/docs/debugging-release-builds?platform=android#enabling-source-maps).
+
+## Plugin Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enable` | `boolean` | `true` | Enables Jscrambler protection. Set to `false` to skip protection. |
+| `enabledHermes` | `boolean` | `true` | Enables Hermes-specific compatibility handling. Set to `false` when the app does not use Hermes. |
+| `ignoreFile` | `string` | `.jscramblerignore` in the project root | Path to the ignore file used to exclude files from protection. |
+| `params` | `Array<object>` | Value from `.jscramblerrc` | Overrides the `params` transformation list from `.jscramblerrc`, useful for testing. |
+
+```js
+const jscramblerMetroPlugin = require('jscrambler-metro-plugin')(
+    /* OPTIONAL */
+    {
+        enable: true, 
+        enabledHermes: true,
+        ignoreFile: resolve(__dirname, '.jscramblerignore'),
+        // overrides the params on `.jscramblerrc` file. Usefull for testing purposes.
+        params: [  
+            {
+              name: "stringConcealing",
+              options: {
+                freq: 1,
+                max: -1
+              }
+            }
+        ]
+    }
+);
+```

package/lib/constants.js

@@ -1,9 +1,18 @@
 const path = require('path');
 
-const BUNDLE_CMD = 'bundle';
+/** commands used to build the bundle
+ *  - bundle: react native standard bundle command for android/iOS
+ *  - export:embed: react native export command for expo builds
+ *  - build-kepler: react native legacy bundle command for VegaOS
+ *  - build-vega: react native current bundle command for VegaOS
+ */
+const EXPO_BUNDLE_CMDS = ['export:embed'];
+const VEGA_BUNDLE_CMDS = ['build-kepler', 'build-vega'];
+const BUNDLE_CMDS = ['bundle', ...VEGA_BUNDLE_CMDS, ...EXPO_BUNDLE_CMDS ];
 const BUNDLE_OUTPUT_CLI_ARG = '--bundle-output';
 const BUNDLE_SOURCEMAP_OUTPUT_CLI_ARG = '--sourcemap-output';
 const BUNDLE_DEV_CLI_ARG = '--dev';
+const BUNDLE_EAGER_CLI_ARG = '--eager';
 // path.join so it supports both linux and windows fs
 const INIT_CORE_MODULE = path.join(process.platform === 'win32' ? '/' : '', 'node_modules', 'react-native', 'Libraries', 'Core', 'InitializeCore.js');
 const JSCRAMBLER_CLIENT_ID = 6;
@@ -35,10 +44,13 @@ const JSCRAMBLER_HERMES_ADD_SHOW_SOURCE_DIRECTIVE = [
 ];
 
 module.exports = {
-  BUNDLE_CMD,
+  BUNDLE_CMDS,
+  EXPO_BUNDLE_CMDS,
+  VEGA_BUNDLE_CMDS,
   BUNDLE_OUTPUT_CLI_ARG,
   BUNDLE_SOURCEMAP_OUTPUT_CLI_ARG,
   BUNDLE_DEV_CLI_ARG,
+  BUNDLE_EAGER_CLI_ARG,
   INIT_CORE_MODULE,
   JSCRAMBLER_CLIENT_ID,
   JSCRAMBLER_IGNORE,
@@ -58,5 +70,5 @@ module.exports = {
   JSCRAMBLER_HERMES_ADD_SHOW_SOURCE_DIRECTIVE,
   JSCRAMBLER_ANTI_TAMPERING_MODE_SKL,
   HERMES_SHOW_SOURCE_DIRECTIVE,
-  JSCRAMBLER_EXTS
+  JSCRAMBLER_EXTS,
 }

package/lib/index.js

@@ -1,4 +1,6 @@
 const {copy, emptyDir, mkdirp, readFile, writeFile} = require('fs-extra');
+const { getDefaultConfig } = require('@react-native/metro-config');
+const { getDefaultConfig: getDefaultExpoConfig } = require('expo/metro-config');
 const jscrambler = require('jscrambler').default;
 const fs = require('fs');
 const path = require('path');
@@ -34,7 +36,10 @@ const {
   handleAntiTampering,
   addHermesShowSourceDirective,
   handleHermesIncompatibilities,
-  wrapCodeWithTags
+  wrapCodeWithTags,
+  isVegaBuild,
+  isExpoBuild,
+  resolveMetroOutputBundle
 } = require('./utils');
 
 const debug = !!process.env.DEBUG;
@@ -277,12 +282,172 @@ function validateModule(modulePath, config, projectRoot) {
   }
 }
 
+let calledByMetro = false;
+
+/**
+ * Validates that Metro invoked the Jscrambler serializer integration.
+ *
+ * If Metro never calls the serializer hook, the plugin was not applied through
+ * metro.config.js and the bundle cannot be obfuscated reliably.
+ * @returns {void}
+ */
+function validateIfJscramblerWasApplied() {
+  if (!calledByMetro) {
+    console.error(
+      '*jscrambler-metro-plugin* was not properly configured on metro.config.js file. Please verify our documentation in https://docs.jscrambler.com/code-integrity/frameworks-and-libraries/react-native/integration.',
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * Configures the Metro integration for Vega OS builds.
+ *
+ * Vega OS overrides Metro's processModuleFilter, so this patches Metro's bundle
+ * save path to run Jscrambler after Metro writes the output and uses
+ * getPolyfills to wrap the final module filter.
+ * @param {object} options
+ * @param {function(*): boolean} options.applyJscramblerSerializerToModule Applies
+ * Jscrambler tagging and filtering to a Metro module.
+ * @param {function(string, string=): Promise<void>} options.runObfuscation Runs
+ * Jscrambler against the generated bundle and optional source map.
+ * @param {string} options.projectRoot Project root used to resolve Metro.
+ * @returns {{serializer: {getPolyfills(): string[]}}} Vega OS Metro config.
+ */
+function setupViaSaveHook({
+  applyJscramblerSerializerToModule,
+  runObfuscation,
+  projectRoot,
+}) {
+  const metroOutput = resolveMetroOutputBundle(projectRoot);
+  if (!metroOutput) {
+    console.error(
+      `Jscrambler could not hook Metro bundle output. Please contact Jscrambler support team at support@jscrambler.com`,
+    );
+    process.exit(1);
+  }
+
+  const originalSave = metroOutput.save.bind(metroOutput);
+
+  metroOutput.save = async function jscramblerMetroSave(...opts) {
+    const [, args] = opts;
+    if (typeof args !== 'object' || args === null || !args.bundleOutput) {
+      console.error(
+        `Jscrambler output bundle could not be found. Please contact Jscrambler support at support@jscrambler.com`,
+      );
+      process.exit(1);
+    }
+
+    const result = await originalSave(...opts);
+    if (args && args.bundleOutput) {
+      try {
+        debug &&
+          console.log(
+            `debug Jscrambler obfuscating bundle at ${args.bundleOutput}`,
+        );
+        console.log(
+          `info Jscrambler ${isVegaBuild() ? 'VegaOS' : 'Expo'} application`,
+        );
+        await runObfuscation(args.bundleOutput, args.sourcemapOutput);
+      } catch (err) {
+        console.error(err);
+        process.exit(1);
+      }
+    }
+    return result;
+  };
+
+  if (isExpoBuild()) {
+    const getDefaultprocessModuleFilter = getDefaultExpoConfig(projectRoot)?.serializer?.processModuleFilter;
+    return {
+      serializer: {
+        processModuleFilter(_module) {
+          const allow = getDefaultprocessModuleFilter(_module);
+          if (allow) {
+            applyJscramblerSerializerToModule(_module);
+          }
+          return allow;
+        },
+      }
+    };
+  }
+
+  const getPolyfills = getDefaultConfig(projectRoot)?.serializer?.getPolyfills;
+  const metroPollyfils =
+      typeof getPolyfills === 'function' ? getPolyfills() : [];
+
+  return {
+    serializer: {
+      getPolyfills() {
+        // wrap processModuleFilter to apply Jscrambler module filtering
+        // due to Amazon overriding processModuleFilter in VegaOS
+        const originalProcessModuleFilter = this.processModuleFilter;
+        this.processModuleFilter = (_module) => {
+          const allow = originalProcessModuleFilter(_module);
+          if (allow) {
+            applyJscramblerSerializerToModule(_module);
+          }
+          return allow;
+        };
+        return metroPollyfils;
+      },
+    },
+  };
+}
+
+/**
+ * Configures the Metro integration for React Native builds.
+ *
+ * Registers a beforeExit hook that obfuscates the bundle produced by Metro and
+ * returns a serializer processModuleFilter that tags user modules while Metro
+ * serializes them.
+ * @param {object} options
+ * @param {function(*): boolean} options.applyJscramblerSerializerToModule Applies
+ * Jscrambler tagging and filtering to a Metro module.
+ * @param {function(string, string=): Promise<void>} options.runObfuscation Runs
+ * Jscrambler against the generated bundle and optional source map.
+ * @returns {{serializer: {processModuleFilter(*): boolean}}} React Native Metro config.
+ */
+function setupViaBeforeExitEvent({
+  applyJscramblerSerializerToModule,
+  runObfuscation,
+}) {
+  process.on('beforeExit', async (exitCode) => {
+    try {
+      const bundlePaths = getBundlePath();
+      await runObfuscation(
+        bundlePaths.bundlePath,
+        bundlePaths.bundleSourceMapPath,
+      );
+      process.exit(typeof exitCode === 'number' ? exitCode : 0);
+    } catch (err) {
+      console.error(err);
+      process.exit(1);
+    }
+  });
+
+  /**
+   * Select user files ONLY (no vendor) to be obfuscated. That code should be tagged with
+   * {@JSCRAMBLER_BEG_ANNOTATION} and {@JSCRAMBLER_END_ANNOTATION}.
+   * Also gather metro source-maps in case of instrumentation process.
+   * @param {{output: Array<*>, path: string, getSource: function():Buffer}} _module
+   * @returns {boolean}
+   */
+  return {
+    serializer: {
+      processModuleFilter(_module) {
+        return applyJscramblerSerializerToModule(_module);
+      },
+    },
+  };
+}
+
 /**
  * Add serialize.processModuleFilter option to metro and attach listener to beforeExit event.
  * *config.fileSrc* and *config.filesDest* will be ignored.
  * @param {{enable: boolean, enabledHermes: boolean }} _config
  * @param {string} [projectRoot=process.cwd()]
- * @returns {{serializer: {processModuleFilter(*): boolean}}}
+ * @returns {{serializer: {processModuleFilter?(*): boolean, getPolyfills?(*): string[]}}}
  */
 module.exports = function (_config = {}, projectRoot = process.cwd()) {
   const skipReason = skipObfuscation(_config);
@@ -291,9 +456,6 @@ module.exports = function (_config = {}, projectRoot = process.cwd()) {
     return {};
   }
 
-  const bundlePath = getBundlePath();
-  // make sure jscrambler-metro-plugin is properly configure on metro bundler
-  let calledByMetro = false;
   const fileNames = new Set();
   const sourceMapFiles = [];
   const config = Object.assign(
@@ -313,84 +475,82 @@ module.exports = function (_config = {}, projectRoot = process.cwd()) {
     console.warn('warning: Jscrambler recommends you to declare your transformations list on the configuration file.')
   }
 
-  process.on('beforeExit', async function (exitCode) {
-    try{
-      if (!calledByMetro) {
-        throw new Error('*jscrambler-metro-plugin* was not properly configured on metro.config.js file. Please verify our documentation in https://docs.jscrambler.com/code-integrity/frameworks-and-libraries/react-native/integration.');
-      }
+  async function runObfuscation(bundlePath, bundleSourceMapPath) {
+    validateIfJscramblerWasApplied();
 
-      console.log(
-        instrument
-          ? 'info Jscrambler Instrumenting Code'
-          : `info Jscrambler Obfuscating Code ${
-              config.enabledHermes
-                ? "(Using Hermes Engine)"
-                : "(If you are using Hermes Engine set enabledHermes=true)"
-            }`,
+    console.log(
+      instrument
+        ? 'info Jscrambler Instrumenting Code'
+        : `info Jscrambler Obfuscating Code ${
+            config.enabledHermes
+              ? "(Using Hermes Engine)"
+              : "(If you are using Hermes Engine set enabledHermes=true)"
+          }`,
+    );
+
+    const isCodeHardeningThresholdSupported =
+      await jscrambler.introspectFieldOnMethod.call(
+        jscrambler,
+        config,
+        'mutation',
+        'createApplicationProtection',
+        'codeHardeningThreshold',
       );
 
-      const isCodeHardeningThresholdSupported =
-        await jscrambler.introspectFieldOnMethod.call(
-          jscrambler,
-          config,
-          'mutation',
-          'createApplicationProtection',
-          'codeHardeningThreshold',
-        );
+    handleHermesIncompatibilities(config, isCodeHardeningThresholdSupported);
+    await obfuscateBundle(
+      {bundlePath, bundleSourceMapPath},
+      {fileNames: Array.from(fileNames), entryPointCode, isCodeHardeningThresholdSupported},
+      sourceMapFiles,
+      config,
+      projectRoot,
+    );
 
-      // check for incompatible transformations and turn off code hardening
-      handleHermesIncompatibilities(config, isCodeHardeningThresholdSupported);
+    // clear obfuscation state to allow multiple builds at once
+    fileNames.clear();
+    sourceMapFiles.splice(0);
+    entryPointCode = undefined;
+  }
 
-      // start obfuscation
-      await obfuscateBundle(bundlePath, {fileNames: Array.from(fileNames), entryPointCode, isCodeHardeningThresholdSupported}, sourceMapFiles, config, projectRoot);
-    } catch(err) {
-      console.error(err);
-      process.exit(1);
-    } finally {
-      process.exit(exitCode)
-    }
-  });
+  function applyJscramblerSerializerToModule(_module) {
+    calledByMetro = true;
+    const modulePath = _module.path;
+    const shouldSkipModule = !validateModule(modulePath, config, projectRoot);
 
-  return {
-    serializer: {
-      /**
-       * Select user files ONLY (no vendor) to be obfuscated. That code should be tagged with
-       * {@JSCRAMBLER_BEG_ANNOTATION} and {@JSCRAMBLER_END_ANNOTATION}.
-       * Also gather metro source-maps in case of instrumentation process.
-       * @param {{output: Array<*>, path: string, getSource: function():Buffer}} _module
-       * @returns {boolean}
-       */
-      processModuleFilter(_module) {
-        calledByMetro = true;
-
-        const modulePath = _module.path;
-        const shouldSkipModule = !validateModule(modulePath, config, projectRoot);
-
-        if (shouldSkipModule) {
-          return true;
-        }
-
-        const normalizePath = buildNormalizePath(modulePath, projectRoot);
-        fileNames.add(normalizePath);
-
-        _module.output.forEach(({data}) => {
-          if (instrument && Array.isArray(data.map)) {
-            sourceMapFiles.push({
-              filename: `${normalizePath}.map`,
-              content: buildModuleSourceMap(
-                data,
-                normalizePath,
-                _module.getSource().toString()
-              )
-            });
-          }
-          if (modulePath.includes(INIT_CORE_MODULE)){
-            entryPointCode = data.code;
-          }
-          data.code = wrapCodeWithTags(data.code);
+    if (shouldSkipModule) {
+      return true;
+    }
+    const normalizePath = buildNormalizePath(modulePath, projectRoot);
+    fileNames.add(normalizePath);
+
+    _module.output.forEach(({data}) => {
+      if (instrument && Array.isArray(data.map)) {
+        sourceMapFiles.push({
+          filename: `${normalizePath}.map`,
+          content: buildModuleSourceMap(
+            data,
+            normalizePath,
+            _module.getSource().toString()
+          )
         });
-        return true;
       }
-    }
+      if (modulePath.includes(INIT_CORE_MODULE) && entryPointCode === undefined) {
+        entryPointCode = data.code;
+      }
+      data.code = wrapCodeWithTags(data.code);
+    });
+    return true;
+  }
+
+  const options = {
+    applyJscramblerSerializerToModule,
+    runObfuscation,
+    projectRoot,
   };
+
+  const useSaveHook = isVegaBuild() || isExpoBuild();
+
+  return useSaveHook
+    ? setupViaSaveHook(options)
+    : setupViaBeforeExitEvent(options);
 };

package/lib/utils.js

@@ -19,12 +19,15 @@ const {
   BUNDLE_OUTPUT_CLI_ARG,
   BUNDLE_SOURCEMAP_OUTPUT_CLI_ARG,
   BUNDLE_DEV_CLI_ARG,
+  BUNDLE_EAGER_CLI_ARG,
   HERMES_SHOW_SOURCE_DIRECTIVE,
-  BUNDLE_CMD
+  VEGA_BUNDLE_CMDS,
+  EXPO_BUNDLE_CMDS,
+  BUNDLE_CMDS
 } = require('./constants');
 
 /**
- * Only 'bundle' command triggers obfuscation.
+ * Only known Metro bundle CLI subcommands trigger obfuscation (see BUNDLE_CMDS).
  * Development bundles will be ignored (--dev true). Use JSCRAMBLER_METRO_DEV to override this behaviour.
  * @returns {string} skip reason. If falsy value dont skip obfuscation
  */
@@ -39,14 +42,22 @@ function skipObfuscation(config) {
 
   let isBundleCmd = false;
   const command = new Command();
+  BUNDLE_CMDS.forEach(bundleCmd => {
+    command
+      .command(bundleCmd)
+      .allowUnknownOption()
+      .action(() => (isBundleCmd = true));
+  });
   command
-    .command(BUNDLE_CMD)
-    .allowUnknownOption()
-    .action(() => (isBundleCmd = true));
-  command.option(`${BUNDLE_DEV_CLI_ARG} <boolean>`).parse(process.argv);
+    .option(`${BUNDLE_DEV_CLI_ARG} <boolean>`)
+    .option(BUNDLE_EAGER_CLI_ARG)
+    .parse(process.argv);
   if (!isBundleCmd) {
     return 'Not a *bundle* command';
   }
+  if (command.eager) {
+    return 'warning: Jscrambler Obfuscation SKIPPED [Eager export:embed]';
+  }
   if (command.dev === 'true') {
     return (
       process.env.JSCRAMBLER_METRO_DEV !== 'true' &&
@@ -58,6 +69,8 @@ function skipObfuscation(config) {
 
 /**
  * Get bundle path based CLI arguments
+ * Only for some android/iOS builds, VegaOS
+ * does not reach this logic.
  * @returns {{bundlePath: string, bundleSourceMapPath: string}}
  * @throws {Error} when bundle output was not found
  */
@@ -77,6 +90,20 @@ function getBundlePath() {
   return process.exit(-1);
 }
 
+/**
+ * Check if contains {VEGA_BUNDLE_CMDS} commands.
+ */
+function isVegaBuild() {
+  return VEGA_BUNDLE_CMDS.some((cmd) => process.argv.includes(cmd));
+}
+
+/**
+ * Check if contains {EXPO_BUNDLE_CMDS} commands.
+ */
+function isExpoBuild() {
+  return EXPO_BUNDLE_CMDS.some((cmd) => process.argv.includes(cmd));
+}
+
 /**
  * Extract the lines of code for a given string.
  * @param {string} inputStr
@@ -401,6 +428,31 @@ function handleHermesIncompatibilities(
   }
 }
 
+/**
+ * Resolve Metro's bundle output module for expo and VegaOS.
+ * @param {string} projectRoot
+ * @returns {object}
+ */
+function resolveMetroOutputBundle(projectRoot) {
+  const moduleCandidates = [
+    "@expo/metro/metro/shared/output/bundle", // expo
+    "metro/src/shared/output/bundle", // pre react native 0.83
+    "metro/private/shared/output/bundle" // TODO: Check this path for react native 0.83+
+  ];
+
+  for (const moduleId of moduleCandidates) {
+    try {
+      return require(
+        require.resolve(moduleId, {
+          paths: [projectRoot],
+        }),
+      );
+    } catch (_) {
+      /* empty */
+    }
+  }
+}
+
 module.exports = {
   buildModuleSourceMap,
   buildNormalizePath,
@@ -416,5 +468,8 @@ module.exports = {
   handleAntiTampering,
   addHermesShowSourceDirective,
   handleHermesIncompatibilities,
-  wrapCodeWithTags
+  isVegaBuild,
+  wrapCodeWithTags,
+  isExpoBuild,
+  resolveMetroOutputBundle
 };

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "jscrambler-metro-plugin",
-  "version": "9.0.4",
+  "version": "9.1.0",
   "description": "A plugin to use metro with Jscrambler Code Integrity",
   "exports": "./lib/index.js",
   "peerDependencies": {
-    "metro-source-map": "0.x"
+    "metro-source-map": "0.x",
+    "@react-native/metro-config": "*",
+    "expo": "*"
   },
   "dependencies": {
     "commander": "^2.20.0",
@@ -15,6 +17,8 @@
     "jscrambler",
     "javascript",
     "react-native",
+    "vega-os",
+    "expo",
     "metro",
     "obfuscate",
     "protect",