LavaMoat React Native lockdown

LavaMoat React Native lockdown sets up Hardened JavaScript in React Native apps.

This is achieved by repairing and hardening the JS engine shared intrinsics. LavaMoat React Native lockdown integrates with Metro through serializer options.

[!WARNING] This has not been tested on Static Hermes yet! Only on default side-by-side versions of Hermes that shipped with React Native.

Install

npm i @lavamoat/react-native-lockdown

or

yarn add @lavamoat/react-native-lockdown

Usage

Babel config

Add the following to your Babel config:

ignore: [/\/ses\.cjs$/, /\/ses-hermes\.cjs$/],

React Native

// babel.config.js
module.exports = {
  ignore: [/\/ses\.cjs$/, /\/ses-hermes\.cjs$/],
  presets: ['module:@react-native/babel-preset'],
}

React Native <= 0.72.x

// babel.config.js
module.exports = {
  ignore: [/\/ses\.cjs$/, /\/ses-hermes\.cjs$/],
  presets: ['module:metro-react-native-babel-preset'],
}

[!NOTE] React Native <= 0.76.x (old minor series) are unsupported

Expo

// babel.config.js
module.exports = function (api) {
  api.cache(true)
  return {
    ignore: [/\/ses\.cjs$/, /\/ses-hermes\.cjs$/],
    presets: ['babel-preset-expo'],
  }
}

[!WARNING] Ensure your Babel config ignore Array<MatchPattern> (MatchPattern) RegExp is correct for both SES shims to avoid Babel transforming SES and ignoring more than necessary.

Metro config

This section describes how to use lockdownSerializer to configure Metro.

Hermes

New config

// metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config')
const { lockdownSerializer } = require('@lavamoat/react-native-lockdown')

const config = {
  serializer: lockdownSerializer({ hermesRuntime: true }),
}

module.exports = mergeConfig(getDefaultConfig(__dirname), config)

Existing config

If you already used a serializer configuration, you can pass it as second argument. lockdownSerializer will provide the @react-native/js-polyfills by default, but if you specified your own getPolyfills function, Metro is expecting you to provide the polyfills and lockdownSerializer follows that behavior too.

Some modules depend on language features that may not be present in the underlying platform. Shims (other programs that alter JavaScript) may be added, but are obliged to maintain the object capability safety invariants provided by Lockdown and must be carefully reviewed. We call these "vetted shims".

// metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config')
const { lockdownSerializer } = require('@lavamoat/react-native')

const config = {
  serializer: lockdownSerializer(
    { hermesRuntime: true },
    {
      // your previous serializer config if any, for example:
      getPolyfills: () => {
        return [
          ...require('@react-native/js-polyfills')(),
          require.resolve('path-to-shim'), // e.g. 'reflect-metadata'
        ]
      },
    }
  ),
}

module.exports = mergeConfig(getDefaultConfig(__dirname), config)

[!NOTE] @react-native/js-polyfills is a peer dependency, likely stemming from your React Native version (example):

[email protected]
├─┬ @react-native/[email protected] (devDependencies)
│ └── @react-native/[email protected]
└─┬ [email protected] (dependencies)
  └── @react-native/[email protected] deduped

JavaScriptCore (JSC)

// metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config')
const { lockdownSerializer } = require('@lavamoat/react-native')

const config = {
  serializer: lockdownSerializer({ hermesRuntime: false }),
}

module.exports = mergeConfig(getDefaultConfig(__dirname), config)

[!NOTE] JSC is moving to a Community Package available starting with React Native 0.79.

V8

Untested on react-native-v8, an opt-in V8 runtime for Android only.

License

Copyright (c) 2024 Consensys Software Inc. Licensed MIT