@onekeyfe/react-native-bundle-update 3.0.20 → 3.0.22

package/android/src/main/java/com/margelo/nitro/reactnativebundleupdate/ReactNativeBundleUpdate.kt

@@ -114,8 +114,43 @@ object BundleUpdateStoreAndroid {
     private const val COMMON_BUNDLE_FILE_NAME = "common.bundle"
     private const val METADATA_REQUIRES_BACKGROUND_BUNDLE_KEY = "requiresBackgroundBundle"
     private const val METADATA_BACKGROUND_PROTOCOL_VERSION_KEY = "backgroundProtocolVersion"
+    private const val METADATA_REQUIRES_COMMON_BUNDLE_KEY = "requiresCommonBundle"
+    private const val METADATA_BUNDLE_FORMAT_KEY = "bundleFormat"
+    private const val BUNDLE_FORMAT_THREE_BUNDLE = "three-bundle"
     private const val SUPPORTED_BACKGROUND_PROTOCOL_VERSION = "1"
 
+    // In-memory cache for getValidatedCurrentBundleInfo. Without this, every
+    // bundleURL / common / main / background path getter on startup re-runs
+    // the whole validation pipeline. Cache key is currentBundleVersion;
+    // invalidated on any mutation of the current bundle.
+    @Volatile private var cachedValidatedBundleInfo: ValidatedBundleInfo? = null
+
+    // Lazy per-version cache for the web-embed subtree. getWebEmbedPath is
+    // called every time a WebView is created, but the subtree contents are
+    // immutable for a given currentBundleVersion. Stores the version that
+    // most recently passed full sha256 sweep over web-embed/**; invalidated
+    // alongside cachedValidatedBundleInfo on any bundle mutation.
+    @Volatile private var cachedWebEmbedVerifiedVersion: String? = null
+
+    @Synchronized
+    fun invalidateValidatedBundleInfoCache() {
+        cachedValidatedBundleInfo = null
+        cachedWebEmbedVerifiedVersion = null
+    }
+
+    /**
+     * True when the current bundle's metadata declares the three-bundle /
+     * split-thread layout (or explicitly opts in via requiresCommonBundle).
+     * SplitBundleLoader queries this reflectively to decide whether an empty
+     * per-segment sha256 is a back-compat skip (older formats) or a hard
+     * fail (three-bundle, which always ships per-segment hashes).
+     */
+    @JvmStatic
+    fun currentBundleRequiresPerSegmentHash(context: Context): Boolean {
+        val info = getValidatedCurrentBundleInfo(context) ?: return false
+        return metadataRequiresCommonBundle(info.metadata)
+    }
+
     fun getDownloadBundleDir(context: Context): String {
         val dir = File(context.filesDir, "onekey-bundle-download")
         if (!dir.exists()) dir.mkdirs()
@@ -190,6 +225,7 @@ object BundleUpdateStoreAndroid {
     }
 
     fun clearUpdateBundleData(context: Context) {
+        invalidateValidatedBundleInfoCache()
         val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
         prefs.edit().clear().commit()
         // Clear all signature files
@@ -407,7 +443,16 @@ object BundleUpdateStoreAndroid {
             val keys = obj.keys()
             while (keys.hasNext()) {
                 val key = keys.next()
-                metadata[key] = obj.getString(key)
+                // Only accept string-valued entries. Any nested object / array
+                // / numeric value is silently skipped so the metadata can carry
+                // non-string scalars (e.g. runtimeGraphVersion) or future V2
+                // descriptors without breaking file-level SHA verification.
+                val value = obj.opt(key)
+                if (value is String) {
+                    metadata[key] = value
+                } else if (value is Boolean || value is Number) {
+                    metadata[key] = value.toString()
+                }
             }
         } catch (e: Exception) {
             OneKeyLog.error("BundleUpdate", "Error parsing metadata JSON: ${e.message}")
@@ -421,7 +466,9 @@ object BundleUpdateStoreAndroid {
 
     private fun isReservedMetadataKey(key: String): Boolean {
         return key == METADATA_REQUIRES_BACKGROUND_BUNDLE_KEY ||
-            key == METADATA_BACKGROUND_PROTOCOL_VERSION_KEY
+            key == METADATA_BACKGROUND_PROTOCOL_VERSION_KEY ||
+            key == METADATA_REQUIRES_COMMON_BUNDLE_KEY ||
+            key == METADATA_BUNDLE_FORMAT_KEY
     }
 
     private fun getFileMetadataEntries(metadata: Map<String, String>): Map<String, String> {
@@ -435,6 +482,18 @@ object BundleUpdateStoreAndroid {
             ?: false
     }
 
+    private fun metadataRequiresCommonBundle(metadata: Map<String, String>): Boolean {
+        // OR semantics matching iOS: an explicit `requiresCommonBundle=false`
+        // does NOT suppress the `bundleFormat=three-bundle` signal. Both
+        // signals are treated as opt-ins; either one being true is enough.
+        val explicit = metadata[METADATA_REQUIRES_COMMON_BUNDLE_KEY]
+            ?.lowercase()
+            ?.let { value -> value == "1" || value == "true" || value == "yes" }
+            ?: false
+        if (explicit) return true
+        return metadata[METADATA_BUNDLE_FORMAT_KEY]?.lowercase() == BUNDLE_FORMAT_THREE_BUNDLE
+    }
+
     private fun metadataBackgroundProtocolVersion(metadata: Map<String, String>): String {
         return metadata[METADATA_BACKGROUND_PROTOCOL_VERSION_KEY] ?: ""
     }
@@ -686,6 +745,21 @@ object BundleUpdateStoreAndroid {
             return false
         }
 
+        // Three-bundle (union / split thread) mode requires a common.bundle
+        // shipped alongside main.jsbundle.hbc. Without it, entry-only main
+        // bundle references moduleIds that live in the common bundle and the
+        // runtime crashes on first require().
+        if (metadataRequiresCommonBundle(metadata)) {
+            val commonBundleFile = File(bundleDir, COMMON_BUNDLE_FILE_NAME)
+            if (!commonBundleFile.exists()) {
+                OneKeyLog.error(
+                    "BundleUpdate",
+                    "requiresCommonBundle is true but common.bundle is missing at ${commonBundleFile.absolutePath}",
+                )
+                return false
+            }
+        }
+
         if (!metadataRequiresBackgroundBundle(metadata)) {
             return true
         }
@@ -723,9 +797,19 @@ object BundleUpdateStoreAndroid {
             val currentAppVersion = getAppVersion(context)
             val currentBundleVersion = getCurrentBundleVersion(context) ?: run {
                 OneKeyLog.warn("BundleUpdate", "getJsBundlePath: no currentBundleVersion stored")
+                invalidateValidatedBundleInfoCache()
                 return null
             }
 
+            // Memo cache: avoid re-running signature + entry-bundle sha256 for
+            // every bundleURL / common / main / background path getter on
+            // startup.
+            cachedValidatedBundleInfo?.let { cached ->
+                if (cached.currentBundleVersion == currentBundleVersion) {
+                    return cached
+                }
+            }
+
             OneKeyLog.info("BundleUpdate", "currentAppVersion: $currentAppVersion, currentBundleVersion: $currentBundleVersion")
 
             val prevNativeVersion = getNativeVersion(context)
@@ -777,31 +861,78 @@ object BundleUpdateStoreAndroid {
             }
             val metadata = parseMetadataJson(metadataContent)
 
-            val lastDashIndex = currentBundleVersion.lastIndexOf("-")
-            if (lastDashIndex > 0) {
-                val appVer = currentBundleVersion.substring(0, lastDashIndex)
-                val bundleVer = currentBundleVersion.substring(lastDashIndex + 1)
-                if (!validateAllFilesInDir(context, bundleDir, metadata, appVer, bundleVer)) {
-                    OneKeyLog.info("BundleUpdate", "validateAllFilesInDir failed on startup")
-                    return null
-                }
+            // Startup hot path: only verify entry-bundle SHA-256
+            // (main + common + background as required by metadata flags). The
+            // full-tree sha256 sweep already runs at install time
+            // (validateAllFilesInDir in installBundle), so re-doing it on every
+            // launch costs hundreds of ms per startup with no security gain
+            // (sandboxed app data + signed metadata.json bind every file's
+            // expected hash). Per-segment integrity is checked at loadSegment
+            // time by SplitBundleLoader.
+            if (!validateEntryBundlesSha256(bundleDir, metadata)) {
+                OneKeyLog.info("BundleUpdate", "validateEntryBundlesSha256 failed on startup")
+                return null
             }
 
             if (!validateBundlePairCompatibility(bundleDir, metadata)) {
                 return null
             }
 
-            ValidatedBundleInfo(
+            val info = ValidatedBundleInfo(
                 bundleDir = bundleDir,
                 currentBundleVersion = currentBundleVersion,
                 metadata = metadata,
             )
+            cachedValidatedBundleInfo = info
+            info
         } catch (e: Exception) {
             OneKeyLog.error("BundleUpdate", "Error getting bundle: ${e.message}")
             null
         }
     }
 
+    /**
+     * Verifies SHA-256 of just the entry bundles required to boot the JS
+     * runtime (main + common + background, gated by metadata flags). Runs in
+     * place of the legacy validateAllFilesInDir on the startup hot path.
+     */
+    fun validateEntryBundlesSha256(bundleDir: String, metadata: Map<String, String>): Boolean {
+        val fileEntries = getFileMetadataEntries(metadata)
+        val entriesToCheck = mutableListOf(MAIN_JS_BUNDLE_FILE_NAME)
+        if (metadataRequiresCommonBundle(metadata)) {
+            entriesToCheck += COMMON_BUNDLE_FILE_NAME
+        }
+        if (metadataRequiresBackgroundBundle(metadata)) {
+            entriesToCheck += BACKGROUND_BUNDLE_FILE_NAME
+        }
+        for (entry in entriesToCheck) {
+            val file = File(bundleDir, entry)
+            if (!file.exists()) {
+                OneKeyLog.error("BundleUpdate", "[entry-verify] missing entry file: $entry")
+                return false
+            }
+            val expected = fileEntries[entry]
+            if (expected.isNullOrEmpty()) {
+                OneKeyLog.error("BundleUpdate", "[entry-verify] no metadata sha256 for entry: $entry")
+                return false
+            }
+            val actual = calculateSHA256(file.absolutePath)
+            // secureCompare is byte-wise (case-sensitive); lowercase both
+            // sides so an uppercase-hex manifest doesn't false-mismatch
+            // against `calculateSHA256`'s lowercase output. Matches the
+            // semantic of the previous `equals(actual, ignoreCase = true)`
+            // while preserving the constant-time guarantee against timing
+            // attacks on hash comparisons (consistent with every other
+            // sha256 comparison in this file: validateFilesRecursive,
+            // validateWebEmbedRecursive, iOS validateEntryBundlesSha256).
+            if (actual == null || !secureCompare(expected.lowercase(), actual.lowercase())) {
+                OneKeyLog.error("BundleUpdate", "[entry-verify] sha256 mismatch for entry: $entry")
+                return false
+            }
+        }
+        return true
+    }
+
     fun getCurrentBundleEntryPath(context: Context, entryFileName: String): String? {
         val bundleInfo = getValidatedCurrentBundleInfo(context) ?: return null
         val entryFile = File(bundleInfo.bundleDir, entryFileName)
@@ -826,9 +957,122 @@ object BundleUpdateStoreAndroid {
 
     fun getWebEmbedPath(context: Context): String {
         val bundleInfo = getValidatedCurrentBundleInfo(context) ?: return ""
+        // Lazy full-tree sha256 sweep for web-embed/**. The startup hot path
+        // only validates the JS entry bundles (validateEntryBundlesSha256), so
+        // without this, a tampered web-embed asset would slip through. Result
+        // is cached per currentBundleVersion and invalidated on any bundle
+        // mutation, so cost is paid once per (re)install.
+        if (!ensureWebEmbedVerified(
+                bundleDir = bundleInfo.bundleDir,
+                currentBundleVersion = bundleInfo.currentBundleVersion,
+                metadata = bundleInfo.metadata,
+            )) {
+            return ""
+        }
         return File(bundleInfo.bundleDir, "web-embed").absolutePath
     }
 
+    @Synchronized
+    private fun ensureWebEmbedVerified(
+        bundleDir: String,
+        currentBundleVersion: String,
+        metadata: Map<String, String>,
+    ): Boolean {
+        if (cachedWebEmbedVerifiedVersion == currentBundleVersion) {
+            return true
+        }
+        if (!validateWebEmbedSha256(bundleDir, metadata)) {
+            OneKeyLog.error("BundleUpdate", "validateWebEmbedSha256 failed for $currentBundleVersion")
+            return false
+        }
+        cachedWebEmbedVerifiedVersion = currentBundleVersion
+        return true
+    }
+
+    /**
+     * Walks bundleDir/web-embed/** and verifies every file's sha256 against
+     * the metadata entry (key is the bundle-relative path). Also rejects
+     * files on disk that aren't listed in metadata, and metadata entries
+     * whose backing file is missing. Returns true when web-embed is absent
+     * from both disk and metadata (bundles without web-embed).
+     */
+    fun validateWebEmbedSha256(bundleDir: String, metadata: Map<String, String>): Boolean {
+        val webEmbedRoot = File(bundleDir, "web-embed")
+        val fileEntries = getFileMetadataEntries(metadata)
+        val webEmbedEntries = fileEntries.filterKeys { it.startsWith("web-embed/") }
+
+        if (!webEmbedRoot.exists() || !webEmbedRoot.isDirectory) {
+            if (webEmbedEntries.isNotEmpty()) {
+                OneKeyLog.error(
+                    "BundleUpdate",
+                    "[web-embed-verify] metadata lists web-embed entries but directory is missing",
+                )
+                return false
+            }
+            return true
+        }
+
+        val bundleDirWithSlash = if (bundleDir.endsWith("/")) bundleDir else "$bundleDir/"
+        if (!validateWebEmbedRecursive(webEmbedRoot, webEmbedEntries, bundleDirWithSlash)) {
+            return false
+        }
+        for ((key, _) in webEmbedEntries) {
+            val expectedFile = File(bundleDirWithSlash + key)
+            if (!expectedFile.exists()) {
+                OneKeyLog.error(
+                    "BundleUpdate",
+                    "[web-embed-verify] file listed in metadata but missing on disk: $key",
+                )
+                return false
+            }
+        }
+        return true
+    }
+
+    private fun validateWebEmbedRecursive(
+        dir: File,
+        webEmbedEntries: Map<String, String>,
+        bundleDirWithSlash: String,
+    ): Boolean {
+        val files = dir.listFiles()
+        if (files == null) {
+            // listFiles() returns null on I/O error or unreadable directory.
+            // Fail closed instead of treating an unlistable subtree as
+            // "nothing to verify" — that would silently allow a tampered
+            // web-embed asset whose containing dir was made unreadable.
+            OneKeyLog.error(
+                "BundleUpdate",
+                "[web-embed-verify] failed to list directory: ${dir.absolutePath}",
+            )
+            return false
+        }
+        for (file in files) {
+            if (file.isDirectory) {
+                if (!validateWebEmbedRecursive(file, webEmbedEntries, bundleDirWithSlash)) return false
+                continue
+            }
+            if (file.name == ".DS_Store") continue
+            val relativePath = file.absolutePath.removePrefix(bundleDirWithSlash)
+            val expected = webEmbedEntries[relativePath]
+            if (expected.isNullOrEmpty()) {
+                OneKeyLog.error(
+                    "BundleUpdate",
+                    "[web-embed-verify] file on disk not in metadata: $relativePath",
+                )
+                return false
+            }
+            val actual = calculateSHA256(file.absolutePath)
+            if (actual == null || !secureCompare(expected, actual)) {
+                OneKeyLog.error(
+                    "BundleUpdate",
+                    "[web-embed-verify] sha256 mismatch for $relativePath",
+                )
+                return false
+            }
+        }
+        return true
+    }
+
     /**
      * Returns true if the OneKey developer mode (DevSettings) is enabled.
      * Reads the persisted value from MMKV storage (key: onekey_developer_mode_enabled,
@@ -1242,6 +1486,11 @@ class ReactNativeBundleUpdate : HybridReactNativeBundleUpdateSpec() {
     }
 
     override fun installBundle(params: BundleInstallParams): Promise<Unit> {
+        // Invalidate up front so any concurrent reader misses the cache while
+        // the install is running. We invalidate again after the async body
+        // commits so a same-version reinstall (or any reader that re-cached
+        // pre-commit data inside the race window) can't leave stale entries.
+        BundleUpdateStoreAndroid.invalidateValidatedBundleInfoCache()
         return Promise.async {
             val context = getContext()
             val appVersion = params.latestVersion
@@ -1311,6 +1560,11 @@ class ReactNativeBundleUpdate : HybridReactNativeBundleUpdateSpec() {
             } catch (e: Exception) {
                 OneKeyLog.error("BundleUpdate", "installBundle: fallbackUpdateBundleData error: ${e.message}")
             }
+            // Second invalidate: closes the race window between the up-front
+            // invalidate and the actual currentBundleVersion write. Without
+            // this, a reader entering getValidatedCurrentBundleInfo() between
+            // the two could re-cache pre-install state and leave it stale.
+            BundleUpdateStoreAndroid.invalidateValidatedBundleInfoCache()
         }
     }
 
@@ -1331,6 +1585,7 @@ class ReactNativeBundleUpdate : HybridReactNativeBundleUpdateSpec() {
     }
 
     override fun clearBundle(): Promise<Unit> {
+        BundleUpdateStoreAndroid.invalidateValidatedBundleInfoCache()
         return Promise.async {
             OneKeyLog.info("BundleUpdate", "clearBundle: clearing download and bundle directories...")
             val context = getContext()
@@ -1352,6 +1607,7 @@ class ReactNativeBundleUpdate : HybridReactNativeBundleUpdateSpec() {
     }
 
     override fun resetToBuiltInBundle(): Promise<Unit> {
+        BundleUpdateStoreAndroid.invalidateValidatedBundleInfoCache()
         return Promise.async {
             OneKeyLog.info("BundleUpdate", "resetToBuiltInBundle: clearing currentBundleVersion preference...")
             val context = getContext()
@@ -1368,6 +1624,7 @@ class ReactNativeBundleUpdate : HybridReactNativeBundleUpdateSpec() {
     }
 
     override fun clearAllJSBundleData(): Promise<TestResult> {
+        BundleUpdateStoreAndroid.invalidateValidatedBundleInfoCache()
         return Promise.async {
             OneKeyLog.info("BundleUpdate", "clearAllJSBundleData: starting...")
             val context = getContext()
@@ -1405,6 +1662,7 @@ class ReactNativeBundleUpdate : HybridReactNativeBundleUpdateSpec() {
     }
 
     override fun setCurrentUpdateBundleData(params: BundleSwitchParams): Promise<Unit> {
+        BundleUpdateStoreAndroid.invalidateValidatedBundleInfoCache()
         return Promise.async {
             val context = getContext()
             val bundleVersion = "${params.appVersion}-${params.bundleVersion}"

package/ios/ReactNativeBundleUpdate.swift

@@ -82,10 +82,58 @@ public class BundleUpdateStore: NSObject {
     private static let nativeBuildNumberKey = "nativeBuildNumber"
     private static let mainBundleEntryFileName = "main.jsbundle.hbc"
     private static let backgroundBundleEntryFileName = "background.bundle"
+    private static let commonBundleEntryFileName = "common.bundle"
     private static let metadataRequiresBackgroundBundleKey = "requiresBackgroundBundle"
     private static let metadataBackgroundProtocolVersionKey = "backgroundProtocolVersion"
+    private static let metadataRequiresCommonBundleKey = "requiresCommonBundle"
+    private static let metadataBundleFormatKey = "bundleFormat"
+    private static let bundleFormatThreeBundle = "three-bundle"
     private static let supportedBackgroundProtocolVersion = "1"
 
+    // In-memory cache for validatedCurrentBundleInfo. Without this, every
+    // bundleURL / common / main / background path getter on startup re-runs
+    // the whole validation pipeline (signature + sha256 of every entry file).
+    // Cache key is currentBundleVersion; invalidated on any mutation of the
+    // current bundle (setCurrentUpdateBundleData / clearBundle /
+    // resetToBuiltInBundle / clearAllJSBundleData / native version change).
+    private static var cachedValidatedBundleInfo: (
+        bundleDirPath: String,
+        currentBundleVersion: String,
+        metadata: [String: Any]
+    )?
+    private static let cachedValidatedBundleInfoLock = NSLock()
+
+    // Lazy per-version cache for the web-embed subtree. getWebEmbedPath is
+    // called every time a WebView is created, but the subtree contents are
+    // immutable for a given currentBundleVersion. Stores the version that
+    // most recently passed full sha256 sweep over web-embed/**; invalidated
+    // alongside cachedValidatedBundleInfo on any bundle mutation.
+    private static var cachedWebEmbedVerifiedVersion: String?
+    private static let cachedWebEmbedVerifiedVersionLock = NSLock()
+
+    public static func invalidateValidatedBundleInfoCache() {
+        cachedValidatedBundleInfoLock.lock()
+        cachedValidatedBundleInfo = nil
+        cachedValidatedBundleInfoLock.unlock()
+        cachedWebEmbedVerifiedVersionLock.lock()
+        cachedWebEmbedVerifiedVersion = nil
+        cachedWebEmbedVerifiedVersionLock.unlock()
+    }
+
+    /// True when the current bundle's metadata declares the three-bundle /
+    /// split-thread layout (or explicitly opts in via requiresCommonBundle).
+    /// SplitBundleLoader queries this reflectively to decide whether an empty
+    /// per-segment sha256 is a back-compat skip (older formats) or a hard
+    /// fail (three-bundle, which always ships per-segment hashes).
+    public static func currentBundleRequiresPerSegmentHash() -> Bool {
+        guard let info = validatedCurrentBundleInfo() else { return false }
+        if metadataBoolValue(info.metadata, key: metadataRequiresCommonBundleKey) {
+            return true
+        }
+        let format = metadataStringValue(info.metadata, key: metadataBundleFormatKey) ?? ""
+        return format.lowercased() == bundleFormatThreeBundle
+    }
+
     public static func documentDirectory() -> String {
         NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0]
     }
@@ -165,9 +213,105 @@ public class BundleUpdateStore: NSObject {
 
     public static func getWebEmbedPath() -> String {
         guard let bundleInfo = validatedCurrentBundleInfo() else { return "" }
+        // Lazy full-tree sha256 sweep for web-embed/**. The startup hot path
+        // only validates the JS entry bundles (validateEntryBundlesSha256), so
+        // without this, a tampered web-embed asset would slip through. Result
+        // is cached per currentBundleVersion and invalidated on any bundle
+        // mutation, so cost is paid once per (re)install.
+        if !ensureWebEmbedVerified(
+            bundleDirPath: bundleInfo.bundleDirPath,
+            currentBundleVersion: bundleInfo.currentBundleVersion,
+            metadata: bundleInfo.metadata,
+        ) {
+            return ""
+        }
         return (bundleInfo.bundleDirPath as NSString).appendingPathComponent("web-embed")
     }
 
+    private static func ensureWebEmbedVerified(
+        bundleDirPath: String,
+        currentBundleVersion: String,
+        metadata: [String: Any],
+    ) -> Bool {
+        cachedWebEmbedVerifiedVersionLock.lock()
+        if cachedWebEmbedVerifiedVersion == currentBundleVersion {
+            cachedWebEmbedVerifiedVersionLock.unlock()
+            return true
+        }
+        cachedWebEmbedVerifiedVersionLock.unlock()
+
+        if !validateWebEmbedSha256(bundleDirPath: bundleDirPath, metadata: metadata) {
+            OneKeyLog.error("BundleUpdate", "validateWebEmbedSha256 failed for \(currentBundleVersion)")
+            return false
+        }
+
+        cachedWebEmbedVerifiedVersionLock.lock()
+        cachedWebEmbedVerifiedVersion = currentBundleVersion
+        cachedWebEmbedVerifiedVersionLock.unlock()
+        return true
+    }
+
+    /// Walks bundleDirPath/web-embed/** and verifies every file's sha256
+    /// against the metadata entry (key is the bundle-relative path). Also
+    /// rejects files on disk that aren't listed in metadata, and metadata
+    /// entries whose backing file is missing. Returns true when web-embed
+    /// is absent from both disk and metadata (bundles without web-embed).
+    static func validateWebEmbedSha256(
+        bundleDirPath: String,
+        metadata: [String: Any],
+    ) -> Bool {
+        let fm = FileManager.default
+        let webEmbedDir = (bundleDirPath as NSString).appendingPathComponent("web-embed")
+        let allEntries = fileMetadataEntries(from: metadata)
+        let webEmbedEntries = allEntries.filter { $0.key.hasPrefix("web-embed/") }
+
+        var dirExists: ObjCBool = false
+        let dirPresent = fm.fileExists(atPath: webEmbedDir, isDirectory: &dirExists) && dirExists.boolValue
+        if !dirPresent {
+            // No web-embed in this bundle is fine, as long as metadata agrees.
+            if !webEmbedEntries.isEmpty {
+                OneKeyLog.error("BundleUpdate", "[web-embed-verify] metadata lists web-embed entries but directory is missing")
+                return false
+            }
+            return true
+        }
+
+        let bundleDirWithSlash = bundleDirPath.hasSuffix("/") ? bundleDirPath : bundleDirPath + "/"
+        guard let enumerator = fm.enumerator(atPath: webEmbedDir) else {
+            OneKeyLog.error("BundleUpdate", "[web-embed-verify] failed to enumerate web-embed directory")
+            return false
+        }
+        while let entry = enumerator.nextObject() as? String {
+            let fullPath = (webEmbedDir as NSString).appendingPathComponent(entry)
+            var isDir: ObjCBool = false
+            if fm.fileExists(atPath: fullPath, isDirectory: &isDir), isDir.boolValue { continue }
+            if entry.hasSuffix(".DS_Store") { continue }
+
+            let relativePath = fullPath.replacingOccurrences(of: bundleDirWithSlash, with: "")
+            guard let expected = webEmbedEntries[relativePath], !expected.isEmpty else {
+                OneKeyLog.error("BundleUpdate", "[web-embed-verify] file on disk not in metadata: \(relativePath)")
+                return false
+            }
+            guard let actual = calculateSHA256(fullPath) else {
+                OneKeyLog.error("BundleUpdate", "[web-embed-verify] failed to hash file: \(relativePath)")
+                return false
+            }
+            if !expected.secureCompare(actual) {
+                OneKeyLog.error("BundleUpdate", "[web-embed-verify] sha256 mismatch for \(relativePath)")
+                return false
+            }
+        }
+
+        for key in webEmbedEntries.keys {
+            let expectedFilePath = bundleDirWithSlash + key
+            if !fm.fileExists(atPath: expectedFilePath) {
+                OneKeyLog.error("BundleUpdate", "[web-embed-verify] file listed in metadata but missing on disk: \(key)")
+                return false
+            }
+        }
+        return true
+    }
+
     public static func calculateSHA256(_ filePath: String) -> String? {
         guard let fileHandle = FileHandle(forReadingAtPath: filePath) else { return nil }
         defer { fileHandle.closeFile() }
@@ -335,7 +479,10 @@ public class BundleUpdateStore: NSObject {
     }
 
     private static func isReservedMetadataKey(_ key: String) -> Bool {
-        key == metadataRequiresBackgroundBundleKey || key == metadataBackgroundProtocolVersionKey
+        key == metadataRequiresBackgroundBundleKey ||
+        key == metadataBackgroundProtocolVersionKey ||
+        key == metadataRequiresCommonBundleKey ||
+        key == metadataBundleFormatKey
     }
 
     private static func metadataStringValue(
@@ -589,6 +736,26 @@ public class BundleUpdateStore: NSObject {
             return false
         }
 
+        // Three-bundle (union build / split thread) mode requires a
+        // common.bundle shipped alongside main.jsbundle.hbc. Without it
+        // the entry-only main bundle references moduleIds that only exist in
+        // the common bundle and the runtime crashes on first require().
+        let bundleFormat = metadataStringValue(metadata, key: metadataBundleFormatKey) ?? ""
+        let requiresCommonBundle =
+            metadataBoolValue(metadata, key: metadataRequiresCommonBundleKey) ||
+            bundleFormat.lowercased() == bundleFormatThreeBundle
+        if requiresCommonBundle {
+            let commonBundlePath = (bundleDirPath as NSString)
+                .appendingPathComponent(commonBundleEntryFileName)
+            guard FileManager.default.fileExists(atPath: commonBundlePath) else {
+                OneKeyLog.error(
+                    "BundleUpdate",
+                    "requiresCommonBundle is true but common.bundle is missing at \(commonBundlePath)",
+                )
+                return false
+            }
+        }
+
         let requiresBackgroundBundle = metadataBoolValue(
             metadata,
             key: metadataRequiresBackgroundBundleKey,
@@ -630,9 +797,19 @@ public class BundleUpdateStore: NSObject {
         processPreLaunchPendingTask()
         guard let currentBundleVer = currentBundleVersion() else {
             OneKeyLog.warn("BundleUpdate", "getJsBundlePath: no currentBundleVersion stored")
+            invalidateValidatedBundleInfoCache()
             return nil
         }
 
+        // Memo cache: avoid re-running signature + entry-bundle sha256 for every
+        // bundleURL / common / main / background path getter on startup.
+        cachedValidatedBundleInfoLock.lock()
+        if let cached = cachedValidatedBundleInfo, cached.currentBundleVersion == currentBundleVer {
+            cachedValidatedBundleInfoLock.unlock()
+            return cached
+        }
+        cachedValidatedBundleInfoLock.unlock()
+
         let currentAppVersion = getCurrentNativeVersion()
         guard let prevNativeVersion = getNativeVersion() else {
             OneKeyLog.warn("BundleUpdate", "getJsBundlePath: prevNativeVersion is nil")
@@ -694,20 +871,69 @@ public class BundleUpdateStore: NSObject {
             return nil
         }
 
-        if let dashRange = currentBundleVer.range(of: "-", options: .backwards) {
-            let appVer = String(currentBundleVer[currentBundleVer.startIndex..<dashRange.lowerBound])
-            let bundleVer = String(currentBundleVer[dashRange.upperBound...])
-            if !validateAllFilesInDir(folderName, metadata: metadata, appVersion: appVer, bundleVersion: bundleVer) {
-                OneKeyLog.info("BundleUpdate", "validateAllFilesInDir failed on startup")
-                return nil
-            }
+        // Startup hot path: only verify entry-bundle SHA-256
+        // (main + common + background as required by metadata flags). The
+        // full-tree sha256 sweep already runs at install time
+        // (validateAllFilesInDir in installBundle), so re-doing it on every
+        // launch costs hundreds of ms per startup with no security gain
+        // (sandboxed app data + signed metadata.json bind every file's
+        // expected hash). Per-segment integrity is checked at loadSegment
+        // time by SplitBundleLoader.
+        if !validateEntryBundlesSha256(bundleDirPath: folderName, metadata: metadata) {
+            OneKeyLog.info("BundleUpdate", "validateEntryBundlesSha256 failed on startup")
+            return nil
         }
 
         if !validateBundlePairCompatibility(bundleDirPath: folderName, metadata: metadata) {
             return nil
         }
 
-        return (folderName, currentBundleVer, metadata)
+        let result = (folderName, currentBundleVer, metadata)
+        cachedValidatedBundleInfoLock.lock()
+        cachedValidatedBundleInfo = result
+        cachedValidatedBundleInfoLock.unlock()
+        return result
+    }
+
+    /// Verifies SHA-256 of just the entry bundles required to boot the JS
+    /// runtime (main + common + background, gated by metadata flags). Runs in
+    /// place of the legacy validateAllFilesInDir on the startup hot path.
+    static func validateEntryBundlesSha256(
+        bundleDirPath: String,
+        metadata: [String: Any],
+    ) -> Bool {
+        let fileEntries = fileMetadataEntries(from: metadata)
+
+        var entriesToCheck: [String] = [mainBundleEntryFileName]
+        let bundleFormat = metadataStringValue(metadata, key: metadataBundleFormatKey) ?? ""
+        if metadataBoolValue(metadata, key: metadataRequiresCommonBundleKey) ||
+            bundleFormat.lowercased() == bundleFormatThreeBundle {
+            entriesToCheck.append(commonBundleEntryFileName)
+        }
+        if metadataBoolValue(metadata, key: metadataRequiresBackgroundBundleKey) {
+            entriesToCheck.append(backgroundBundleEntryFileName)
+        }
+
+        for entry in entriesToCheck {
+            let path = (bundleDirPath as NSString).appendingPathComponent(entry)
+            guard FileManager.default.fileExists(atPath: path) else {
+                OneKeyLog.error("BundleUpdate", "[entry-verify] missing entry file: \(entry)")
+                return false
+            }
+            guard let expected = fileEntries[entry], !expected.isEmpty else {
+                OneKeyLog.error("BundleUpdate", "[entry-verify] no metadata sha256 for entry: \(entry)")
+                return false
+            }
+            guard let actual = calculateSHA256(path) else {
+                OneKeyLog.error("BundleUpdate", "[entry-verify] failed to hash entry: \(entry)")
+                return false
+            }
+            if !expected.secureCompare(actual) {
+                OneKeyLog.error("BundleUpdate", "[entry-verify] sha256 mismatch for entry: \(entry)")
+                return false
+            }
+        }
+        return true
     }
 
     private static func currentBundleEntryPath(_ entryFileName: String) -> String? {
@@ -731,6 +957,10 @@ public class BundleUpdateStore: NSObject {
         currentBundleEntryPath(backgroundBundleEntryFileName)
     }
 
+    public static func currentBundleCommonJSBundle() -> String? {
+        currentBundleEntryPath(commonBundleEntryFileName)
+    }
+
     // Fallback data management
     static func getFallbackUpdateBundleDataPath() -> String {
         let path = (bundleDir() as NSString).appendingPathComponent("fallbackUpdateBundleData.json")
@@ -759,6 +989,7 @@ public class BundleUpdateStore: NSObject {
     }
 
     public static func clearUpdateBundleData() {
+        invalidateValidatedBundleInfoCache()
         let bDir = bundleDir()
         let fm = FileManager.default
         if fm.fileExists(atPath: bDir) {
@@ -1225,6 +1456,11 @@ class ReactNativeBundleUpdate: HybridReactNativeBundleUpdateSpec {
     }
 
     func installBundle(params: BundleInstallParams) throws -> Promise<Void> {
+        // Invalidate up front so any concurrent reader misses the cache while
+        // the install is running. We invalidate again after the async body
+        // commits so a same-version reinstall (or any reader that re-cached
+        // pre-commit data inside the race window) can't leave stale entries.
+        BundleUpdateStore.invalidateValidatedBundleInfoCache()
         return Promise.async {
             let appVersion = params.latestVersion
             let bundleVersion = params.bundleVersion
@@ -1295,6 +1531,12 @@ class ReactNativeBundleUpdate: HybridReactNativeBundleUpdateSpec {
             BundleUpdateStore.writeFallbackUpdateBundleDataFile(fallbackData)
             ud.synchronize()
 
+            // Second invalidate: closes the race window between the up-front
+            // invalidate and the actual currentBundleVersion write. Without
+            // this, a reader entering validatedCurrentBundleInfo() between
+            // the two could re-cache pre-install state and leave it stale.
+            BundleUpdateStore.invalidateValidatedBundleInfoCache()
+
             OneKeyLog.info("BundleUpdate", "installBundle: completed successfully, installed version=\(folderName), fallbackCount=\(fallbackData.count)")
         }
     }
@@ -1318,6 +1560,7 @@ class ReactNativeBundleUpdate: HybridReactNativeBundleUpdateSpec {
     }
 
     func clearBundle() throws -> Promise<Void> {
+        BundleUpdateStore.invalidateValidatedBundleInfoCache()
         return Promise.async { [weak self] in
             OneKeyLog.info("BundleUpdate", "clearBundle: clearing download and bundle directories...")
             // Clear download directory
@@ -1341,6 +1584,7 @@ class ReactNativeBundleUpdate: HybridReactNativeBundleUpdateSpec {
     }
 
     func resetToBuiltInBundle() throws -> Promise<Void> {
+        BundleUpdateStore.invalidateValidatedBundleInfoCache()
         return Promise.async {
             OneKeyLog.info("BundleUpdate", "resetToBuiltInBundle: clearing currentBundleVersion preference...")
             let ud = UserDefaults.standard
@@ -1357,6 +1601,7 @@ class ReactNativeBundleUpdate: HybridReactNativeBundleUpdateSpec {
     }
 
     func clearAllJSBundleData() throws -> Promise<TestResult> {
+        BundleUpdateStore.invalidateValidatedBundleInfoCache()
         return Promise.async {
             OneKeyLog.info("BundleUpdate", "clearAllJSBundleData: starting...")
             let bundleDir = BundleUpdateStore.bundleDir()
@@ -1393,6 +1638,7 @@ class ReactNativeBundleUpdate: HybridReactNativeBundleUpdateSpec {
     }
 
     func setCurrentUpdateBundleData(params: BundleSwitchParams) throws -> Promise<Void> {
+        BundleUpdateStore.invalidateValidatedBundleInfoCache()
         return Promise.async {
             let bundleVersion = "\(params.appVersion)-\(params.bundleVersion)"
             OneKeyLog.info("BundleUpdate", "setCurrentUpdateBundleData: switching to \(bundleVersion)")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-bundle-update",
-  "version": "3.0.20",
+  "version": "3.0.22",
   "description": "react-native-bundle-update",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",