Merge pull request #1 from ExodusForks/exo-doguhan/verify-on-native-side

feat: implement native bundle hash verification on iOS and Android

Author: joshua-rogers-exodus

README.md

@@ -9,7 +9,7 @@ Loads a remote React Native JS bundle, with optional **hash-pinned integrity ver
 
 Loading a remote JS bundle is, by construction, remote code execution inside the host app. **This library is intended for internal/development builds only — do not ship it in store builds without an out-of-band, statically-stripped feature flag.** See `SECURITY.md`.
 
-The `loadVerified()` API closes the dominant runtime risk: it fetches the bundle bytes itself, hashes them with `@exodus/crypto`, compares the hash to a caller-supplied digest in constant time, and only then asks the bridge to reload from the verified bytes. Anything that mutates the response between fetch and reload is rejected.
+The `loadVerified()` API closes the dominant runtime risk: it downloads the bundle natively, hashes the bytes with platform crypto (iOS: `CommonCrypto CC_SHA256`, Android: `MessageDigest SHA-256`), compares the hash to a caller-supplied digest in constant time, and only then loads the verified bytes from app-private storage. Anything that mutates the response between fetch and reload is rejected.
 
 ## Installation
 
@@ -23,7 +23,7 @@ iOS:
 cd ios && pod install
 ```
 
-Android: `BundleLoaderPackage` is autolinked.
+Android: requires both Gradle wiring and host app changes — see [Android integration](#android-integration) below.
 
 ## Usage
 
@@ -43,11 +43,12 @@ Behavior:
 
 - The URL must use the `https:` scheme.
 - The expected sha256 must be a 64-character hex string.
-- The bytes are fetched, hashed in JS using `@exodus/crypto/hash`, and compared to the expected hash with a constant-time comparison.
-- On match, the bytes are written to the platform's app-private cache (iOS: `NSTemporaryDirectory()` with `NSDataWritingFileProtectionComplete`; Android: `Context.getCacheDir()`) and the bridge is reloaded from the local file path.
-- On mismatch, an error is thrown and the bridge is left untouched.
+- Download, SHA-256 hashing, and constant-time comparison all happen in native code. This avoids the Hermes `RangeError` that JS-side `response.arrayBuffer()` causes on large bundles (≥ ~70 MB).
+- On match, the bytes are written to app-private storage and the bundle is loaded (see platform notes below).
+- On mismatch, an error is thrown and the current bundle is left untouched.
+- The remote bundle is active for **one session only**. The next cold start returns to the local bundle — matching the behaviour consumers expect from a developer preview tool.
 
-Works on iOS and Android. The hash check happens in JS before any native call, so the integrity contract is identical on both platforms.
+Works on iOS and Android.
 
 ### Unverified loading
 
@@ -87,12 +88,105 @@ Example: `https://example.ngrok.io/index.bundle?dev=false&platform=ios&excludeSo
 | `loadVerified(url, sha256)` | ✅  | ✅      |
 | `runningMode()`             | ✅  | ✅      |
 
-### How the in-process swap works
+### How bundle loading works
 
-- **iOS** writes the bundle to `NSTemporaryDirectory()` and sets the bridge's `bundleURL` via KVC (`[bridge setValue:url forKey:@"bundleURL"]`), then calls `[bridge reload]`.
-- **Android** writes the bundle to `Context.getCacheDir()`, builds a `JSBundleLoader.createFileLoader(path)`, swaps it into the private `mBundleLoader` field on `ReactInstanceManager` via reflection, and calls `recreateReactContextInBackground()`.
+**iOS** downloads and verifies the bundle natively via `NSURLSession` + `CommonCrypto CC_SHA256`, writes it to `NSTemporaryDirectory()` with `NSDataWritingFileProtectionComplete`, then sets the bridge's `bundleURL` via KVC (`[bridge setValue:url forKey:@"bundleURL"]`) and calls `[bridge reload]`. This is an in-process reload: the old bridge is torn down and a new one is created with the cached file. Because iOS uses ARC, the old bridge's memory (including the Hermes runtime) is freed immediately when the bridge reference is released, before the new runtime allocates — no double-memory peak.
 
-Both mechanisms touch private/internal React Native surface and could break on a major RN upgrade. See `SECURITY.md`. The Android implementation requires the host app to implement `ReactApplication` (the standard React Native template does).
+**Android** uses a process restart instead of an in-process bridge swap. The reason: Android's ART garbage collector is non-deterministic. When a new React context is created alongside an existing one, ART does not guarantee the old Hermes runtime's native heap is freed before the new runtime allocates. On real-world bundle sizes (~50 MB of Hermes bytecode) this causes OOM. The process restart avoids the problem entirely by ensuring only one runtime is ever live.
+
+After download and hash verification, the module:
+
+1. Writes the bundle to `Context.getCacheDir()/verified-bundle.jsbundle`.
+2. Sets a one-shot flag in `SharedPreferences` (`"BundleLoader"` / `"pending_remote_bundle"`), using a synchronous `commit()` so the flag survives the imminent process kill.
+3. Restarts the process via `startActivity` + `Process.killProcess`.
+
+On the next launch, the host app reads the flag, disables Metro (so `ReactInstanceManager` does not query the packager and ignore the file — confirmed necessary by bytecode analysis of RN 0.78), and serves `verified-bundle.jsbundle` as the JS bundle for this session. The flag is consumed on first use so subsequent restarts return to Metro.
+
+## Android integration
+
+Because Android requires host app changes that cannot be encapsulated in the module itself, the following manual steps are required.
+
+### 1. Gradle wiring
+
+`settings.gradle` — include the subproject conditionally (the module is a `devDependency`; prod CI runs `yarn install --production` and the directory won't exist):
+
+```groovy
+def bundleLoaderDir = new File(rootProject.projectDir, '../node_modules/@exodus/react-native-bundle-loader/android')
+if (bundleLoaderDir.exists()) {
+    include ':@exodus_react-native-bundle-loader'
+    project(':@exodus_react-native-bundle-loader').projectDir = bundleLoaderDir
+}
+```
+
+`app/build.gradle` — depend only in debug builds:
+
+```groovy
+if (new File("$rootDir/../node_modules/@exodus/react-native-bundle-loader/android").exists()) {
+    debugImplementation project(':@exodus_react-native-bundle-loader')
+}
+```
+
+### 2. Register the package
+
+In `MainApplication.java`, inside `getPackages()`, add the package via reflection so a missing module (absent in prod CI) doesn't cause a compile-time error:
+
+```java
+if (BuildConfig.DEBUG) {
+    // devDependency absent in prod CI (yarn install --production); reflection avoids a compile-time import
+    try {
+        packages.add((ReactPackage) Class.forName("com.reactnativebundleloader.BundleLoaderPackage")
+                .getDeclaredConstructor().newInstance());
+    } catch (ReflectiveOperationException e) {
+        throw new RuntimeException(e);
+    }
+}
+```
+
+### 3. Hook bundle loading into ReactNativeHost
+
+Add these three methods to your `ReactNativeHost` anonymous subclass in `MainApplication.java`:
+
+```java
+import java.io.File;
+
+// ...
+
+@Override
+public boolean getUseDeveloperSupport() {
+    if (BuildConfig.DEBUG && hasPendingRemoteBundle()) {
+        // Must disable dev support: when enabled and Metro is reachable,
+        // ReactInstanceManager queries the packager and ignores getJSBundleFile().
+        return false;
+    }
+    // No pending bundle — clear the active flag so runningMode() returns LOCAL.
+    getSharedPreferences("BundleLoader", MODE_PRIVATE)
+            .edit().remove("active_remote_bundle").apply();
+    return BuildConfig.DEBUG;
+}
+
+@Override
+protected String getJSBundleFile() {
+    if (BuildConfig.DEBUG && hasPendingRemoteBundle()) {
+        File cachedBundle = new File(getCacheDir(), "verified-bundle.jsbundle");
+        if (cachedBundle.exists()) {
+            // Consume the one-shot latch: next restart goes back to Metro.
+            getSharedPreferences("BundleLoader", MODE_PRIVATE).edit()
+                    .remove("pending_remote_bundle")
+                    .putBoolean("active_remote_bundle", true)
+                    .apply();
+            return cachedBundle.getAbsolutePath();
+        }
+    }
+    return null;
+}
+
+private boolean hasPendingRemoteBundle() {
+    return getSharedPreferences("BundleLoader", MODE_PRIVATE)
+            .getBoolean("pending_remote_bundle", false);
+}
+```
+
+The SharedPreferences keys (`"BundleLoader"`, `"pending_remote_bundle"`, `"active_remote_bundle"`) must match the constants defined in `BundleLoaderModule` (`PREFS_NAME`, `PREFS_PENDING_KEY`, `PREFS_ACTIVE_KEY`).
 
 ## Provenance
 

SECURITY.md

@@ -15,9 +15,9 @@ This library exists to load and execute a remote JavaScript bundle inside the ho
 
 | Surface                                     | Upstream `0.1.0`                                        | This fork                                                                                                                          |
 | ------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| Bundle integrity                            | None — bridge fetches whatever the URL serves           | `loadVerified(url, sha256)` fetches bytes in JS, hashes with `@exodus/crypto`, compares constant-time, only then reloads from disk |
+| Bundle integrity                            | None — bridge fetches whatever the URL serves           | `loadVerified(url, sha256)` downloads bytes natively (iOS: `NSURLSession`, Android: `HttpURLConnection`), hashes with platform crypto (iOS: `CommonCrypto CC_SHA256`, Android: `MessageDigest SHA-256`), compares in constant-time, writes to app-private storage, and reloads the bridge from the local file — closing the TOCTOU window between fetch and load |
 | `BundlePrompt` default URL                  | Hardcoded `cdn.jsdelivr.net/gh/jusbrasil/...` (deleted) | Empty — operator must type a URL                                                                                                   |
-| Scheme enforcement                          | None — accepts `http://`, `file://`, etc.               | `https://` required at the JS boundary; native iOS `load:` re-checks                                                               |
+| Scheme enforcement                          | None — accepts `http://`, `file://`, etc.               | `https://` required at the JS boundary; both native `load` implementations re-check before touching the network                     |
 | Verified bundle on-disk protection (iOS)    | n/a                                                     | Written with `NSDataWritingFileProtectionComplete`                                                                                 |
 | Lockfile                                    | Not shipped                                             | `yarn.lock` committed; `.yarnrc` enforces `--frozen-lockfile`                                                                      |
 | Dependency version pinning                  | Carets (`^`)                                            | All direct deps pinned to exact versions; `.npmrc` `save-exact=true`                                                               |
@@ -35,15 +35,15 @@ This library exists to load and execute a remote JavaScript bundle inside the ho
 
 - **The bridge `bundleURL` setter is a KVC write** on iOS (`[bridge setValue:url forKey:@"bundleURL"]`) to a non-public RN property. Behavior could change on an RN upgrade and silently no-op the loader.
 - **The Android bundle swap reflects on a private field.** `ReactInstanceManager.mBundleLoader` has no public setter, so we use `Field.setAccessible(true)` to install a fresh `JSBundleLoader.createFileLoader(...)` before calling `recreateReactContextInBackground()`. The field name has been stable across RN 0.62–0.74 but is not part of the public API; an RN upgrade could rename or remove it, in which case `loadVerified`/`load` will throw `NoSuchFieldException` rather than silently no-op.
-- **`@exodus/crypto/hash` runs in JS on the JS thread.** Bundles are typically a few MB; hashing time is acceptable. We deliberately keep hashing in JS so the threat-model contract — "Exodus crypto verifies, and the verified bytes are what we hand to native" — is auditable in TypeScript and identical on iOS and Android.
-- **`timingSafeEqual()` is currently inlined** as a small constant-time XOR loop. The threat model anticipates this moving to a future `@exodus/crypto` export. The inlined version is functionally equivalent and lives in `src/index.tsx`.
+- **Hash verification runs in native code, not JS.** `loadVerifiedFromUrl` uses `CommonCrypto CC_SHA256` (iOS) and `MessageDigest SHA-256` (Android) with a constant-time XOR comparison loop in native code. This avoids a Hermes `RangeError: Maximum regex stack depth reached` that the previous JS-side `response.arrayBuffer()` path hit on bundles ≥ ~70 MB. The trade-off is that the integrity contract is no longer auditable as TypeScript.
+- **`timingSafeEqual` is an inlined XOR loop in native code.** Both `ios/BundleLoader.m` and `android/src/main/java/com/reactnativebundleloader/BundleLoaderModule.java` XOR all byte pairs into an accumulator and reject the bundle if the accumulator is non-zero.
 
 ## Release process
 
 This package has no CI/CD. Maintainers cut releases manually from a developer machine:
 
 ```sh
-yarn preflight   # lint + typecheck + test + verify-pack
+yarn preflight   # lint + typecheck + JS tests + Android JVM tests + iOS XCTests + verify-pack
 npm publish --access public
 ```