@scalebun-release/react-native 2.5.0

package/android/src/main/java/com/scalebun/rn/ota/ScaleBunOtaModule.kt

@@ -0,0 +1,683 @@
+package com.scalebun.rn.ota
+
+import android.content.Context
+import android.content.pm.ApplicationInfo
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactMethod
+import org.json.JSONObject
+import java.io.File
+
+/**
+ * React Native bridge for OTA bundle management (`ScaleBunOta`).
+ *
+ * Sprint 2: real slot management via [SlotManager]. All filesystem operations
+ * are delegated to SlotManager (pure Kotlin, no RN dependency, testable).
+ *
+ * The static [getJSBundleFile] method is called from the host app's
+ * MainApplication.getJSBundleFile() to resolve the active OTA bundle at launch.
+ *
+ * Architecture-compatible: extends [ScaleBunOtaSpec], which is the codegen
+ * TurboModule base on New Arch (`src/newarch`) and a classic NativeModule
+ * base on Old Arch (`src/oldarch`).
+ */
+class ScaleBunOtaModule(reactContext: ReactApplicationContext) :
+    ScaleBunOtaSpec(reactContext) {
+
+    companion object {
+        const val NAME = "ScaleBunOta"
+
+        /**
+         * Static entry point that resolves the active OTA bundle at launch.
+         *
+         * Called BEFORE React Native initializes JS — this is where the boot
+         * guard runs and the active bundle path is resolved.
+         *
+         * Returns null in DEBUG builds (Metro always wins) or when no OTA
+         * bundle is installed.
+         *
+         * ── Which integration to use ────────────────────────────────────────
+         *
+         * PREFERRED — React Native 0.81 and above, and REQUIRED on 0.82+.
+         * Pass the path directly to the ReactHost. This does not depend on
+         * `ReactNativeHost` at all, which matters because 0.82 REMOVED that
+         * class: the override form below does not compile there.
+         *
+         * ```kotlin
+         * override val reactHost: ReactHost by lazy {
+         *     getDefaultReactHost(
+         *         context = applicationContext,
+         *         packageList = PackageList(this).packages,
+         *         jsBundleFilePath = ScaleBunOtaModule.getJSBundleFile(applicationContext),
+         *     )
+         * }
+         * ```
+         *
+         * LEGACY — React Native 0.76.1 through 0.81, bridge mode any version:
+         *
+         * ```kotlin
+         * override fun getJSBundleFile(): String? {
+         *     return ScaleBunOtaModule.getJSBundleFile(this)
+         *         ?: super.getJSBundleFile()
+         * }
+         * ```
+         *
+         * ⚠️ The legacy form is IGNORED on bridgeless below React Native
+         * 0.76.1. `DefaultReactNativeHost.toReactHost()` did not forward
+         * `jsBundleFile` until then, and `DefaultReactHost` hardcoded
+         * `JSBundleLoader.createAssetLoader(...)` — so an update installs,
+         * reports success, and the app keeps running the APK asset. The SDK
+         * detects that runtime and disables OTA rather than pretending to work
+         * (see `src/features/ota/environment.ts`).
+         *
+         * Whichever form is used, the SDK verifies after restart that the
+         * bundle it installed is the bundle actually executing, and reports
+         * APPLY_FAILED if it is not. A mis-wired integration surfaces as data
+         * rather than as silence.
+         */
+        @JvmStatic
+        fun getJSBundleFile(context: Context): String? {
+            // CRITICAL: never interfere with DEBUG builds
+            if (isDebugBuild(context)) return null
+
+            val slotManager = SlotManager(context.filesDir)
+
+            // Run boot guard check BEFORE JS loads
+            slotManager.checkBootGuard()
+
+            val bundleFile = slotManager.currentBundlePath()
+            return bundleFile?.absolutePath
+        }
+
+        private fun isDebugBuild(context: Context): Boolean {
+            return (context.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0
+        }
+    }
+
+    private val slotManager by lazy { SlotManager(reactApplicationContext.filesDir) }
+
+    /**
+     * Trusted RSA public keys embedded in the APK (docs §9). Non-empty once the
+     * app ships a `scalebun_ota_keys.json` asset — which is what flips staging
+     * into the native-ENFORCED path (see [stageBundle]).
+     */
+    private val keyRegistry by lazy { ScaleBunOtaKeyRegistry.fromAssets(reactApplicationContext) }
+
+    /** Device-derived verification context — never taken from JS. */
+    private fun buildContext(): ExpectedContext = ExpectedContext(
+        projectId = keyRegistry.projectId,
+        applicationId = reactApplicationContext.packageName,
+        currentSequence = slotManager.highestConfirmedSequence(),
+        nowEpochSeconds = System.currentTimeMillis() / 1000,
+    )
+
+    override fun getName(): String = NAME
+
+    /**
+     * Forward download progress to JS as a device event.
+     *
+     * The JS side (`OtaOrchestrator`) turns these into `DOWNLOAD_PROGRESS`
+     * events for the `useOtaUpdate` hook and throttled POSTs to the live
+     * tracker. Until this existed, the hook's `downloadProgress` field and the
+     * dashboard's live-downloads panel were declared on both ends and fed by
+     * neither — the download was one opaque promise.
+     *
+     * `RCTDeviceEventEmitter` works on both architectures (the New Architecture
+     * keeps it via the interop layer). Failures are swallowed: progress display
+     * must never be able to break the download it describes.
+     */
+    private fun emitProgress(bytesRead: Long, totalBytes: Long) {
+        try {
+            if (!reactApplicationContext.hasActiveReactInstance()) return
+            val payload = com.facebook.react.bridge.Arguments.createMap().apply {
+                putDouble("bytesRead", bytesRead.toDouble())
+                putDouble("totalBytes", totalBytes.toDouble())
+            }
+            reactApplicationContext
+                .getJSModule(
+                    com.facebook.react.modules.core.DeviceEventManagerModule.RCTDeviceEventEmitter::class.java,
+                )
+                .emit("ScaleBunOtaProgress", payload)
+        } catch (_: Exception) {
+            // Never let progress reporting interfere with the download itself.
+        }
+    }
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun getActiveBundle(): String? {
+        if (isDebugBuild(reactApplicationContext)) return null
+        return slotManager.currentBundlePath()?.absolutePath
+    }
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun getSlotState(): String {
+        return slotManager.slotState().toString()
+    }
+
+    /**
+     * Device integrity signals as a JSON array of reason strings.
+     *
+     * Reported, never enforced HERE. Native only measures; the decision is made
+     * in JS, where the host's policy lives — `ota.onCompromisedDevice` ('allow'
+     * by default, 'withhold' to refuse updates on such devices; see
+     * BootGuardConfig in features/ota/OtaOrchestrator.ts). Keeping the decision
+     * out of native is deliberate: it is a product choice a host app makes with
+     * knowledge of its own users, and it must be changeable without a native
+     * release.
+     *
+     * Empty array means nothing was detected, which is not proof the device is
+     * clean.
+     */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun getDeviceIntegrity(): String {
+        return org.json.JSONArray(
+            DeviceIntegrity.rootIndicators(reactApplicationContext),
+        ).toString()
+    }
+
+    /** JSON array of the trusted key IDs embedded in this app (SDK trust coverage). */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    override fun getTrustedKeyIds(): String {
+        return org.json.JSONArray(keyRegistry.keyIds().toList()).toString()
+    }
+
+    /**
+     * Stage a bundle into the `next` slot.
+     *
+     * OTA-05: [sourcePath] may be an http(s) URL or a local file path. The JS
+     * orchestrator has always passed `bundle.url` here while this method assumed
+     * a filesystem path, so every install failed at staging. Accepting both keeps
+     * the documented local-path contract for any existing caller and makes the
+     * orchestrator correct without a coordinated JS+native change.
+     *
+     * Downloaded bytes land in a temp file that is always cleaned up:
+     * [SlotManager.stage] copies into its own `_tmp_` directory and verifies the
+     * SHA-256 there, so this file is never the one that gets promoted.
+     */
+    @ReactMethod
+    override fun stageBundle(sourcePath: String, sha256: String, promise: Promise) {
+        // Native-enforced staging (docs §17): once trusted keys are embedded, the
+        // ONLY way to stage is verifyAndStageRelease, which proves an RSA signature
+        // over the release payload first. A hostile JS bundle can therefore not
+        // drive an unauthenticated bundle onto the device by calling this path —
+        // SHA-256 integrity alone (what this method checks) is not authenticity.
+        if (!keyRegistry.isEmpty()) {
+            android.util.Log.w(
+                NAME,
+                "stageBundle refused: trusted keys are embedded — use verifyAndStageRelease (signature-enforced).",
+            )
+            promise.resolve(false)
+            return
+        }
+        var downloaded: File? = null
+        try {
+            val isRemote = sourcePath.startsWith("http://", true) ||
+                sourcePath.startsWith("https://", true)
+
+            val sourceFile: File
+            if (isRemote) {
+                val temp = File(reactApplicationContext.cacheDir, "scalebun_ota_dl_${System.nanoTime()}")
+                downloaded = temp
+                if (!BundleDownloader.download(reactApplicationContext, sourcePath, temp, ::emitProgress)) {
+                    promise.resolve(false)
+                    return
+                }
+                sourceFile = temp
+            } else {
+                sourceFile = File(sourcePath)
+                if (!sourceFile.exists()) {
+                    promise.resolve(false)
+                    return
+                }
+            }
+
+            // Build meta.json from source file info
+            val meta = JSONObject()
+            meta.put("sha256", sha256)
+            meta.put("installedAt", System.currentTimeMillis())
+
+            val success = slotManager.stage(sourceFile, sha256, meta)
+            promise.resolve(success)
+        } catch (e: Exception) {
+            promise.reject("STAGE_ERROR", e.message, e)
+        } finally {
+            downloaded?.delete()
+        }
+    }
+
+    /**
+     * Binary-patch staging (S7-NAT-1).
+     *
+     * Downloads a delta, reconstructs the full bundle from the currently
+     * installed one, and hands the result to the ordinary staging path — so a
+     * patched bundle passes exactly the same SHA-256 and slot-promotion checks
+     * as a fully downloaded one. [expectedSha256] is the hash of the COMPLETE
+     * bundle, which is what makes a bad patch unable to install: reconstruct
+     * the wrong bytes and staging rejects them.
+     *
+     * Resolves `false` — never rejects — for every "cannot patch" case, because
+     * `src/specs/NativeScaleBunOta.ts` defines false as "patching unavailable,
+     * fall back to a full download". The update still lands, just larger. The
+     * cases are: no OTA bundle installed yet (nothing to patch against — the
+     * first install is always full), a patch that does not match its own
+     * advertised hash, and a malformed patch.
+     */
+    @ReactMethod
+    override fun stagePatch(
+        patchUrl: String,
+        patchSha256: String,
+        expectedSha256: String,
+        promise: Promise,
+    ) {
+        // Same native-enforcement as stageBundle: a bsdiff patch staged by hash
+        // alone carries no signature, so once trusted keys are embedded this path
+        // is closed. Result-anchored signed patches are a native follow-up
+        // (verifyAndStagePatch); until then the SDK falls back to the verified
+        // full download (verifyAndStageRelease). false = "patch unavailable".
+        if (!keyRegistry.isEmpty()) {
+            android.util.Log.i(NAME, "stagePatch disabled while trusted keys are embedded — full verified download")
+            promise.resolve(false)
+            return
+        }
+        var downloadedPatch: File? = null
+        var rebuilt: File? = null
+        try {
+            // Patching is relative to the bundle already on disk. With no OTA
+            // bundle installed the source would be the APK's built-in asset,
+            // which the server did not diff against — so there is nothing valid
+            // to apply and a full download is the correct path.
+            val currentBundle = slotManager.currentBundlePath()
+            if (currentBundle == null || !currentBundle.exists()) {
+                android.util.Log.i(NAME, "stagePatch: no current OTA bundle to patch — full download")
+                promise.resolve(false)
+                return
+            }
+
+            val temp = File(reactApplicationContext.cacheDir, "scalebun_ota_patch_${System.nanoTime()}")
+            downloadedPatch = temp
+            if (!BundleDownloader.download(reactApplicationContext, patchUrl, temp, ::emitProgress)) {
+                promise.resolve(false)
+                return
+            }
+
+            val patchBytes = temp.readBytes()
+
+            // Verify the patch against its own hash before parsing it. This is
+            // cheap and keeps obviously-corrupt input away from the parser.
+            val actualPatchSha = sha256Hex(patchBytes)
+            if (!actualPatchSha.equals(patchSha256, ignoreCase = true)) {
+                android.util.Log.w(NAME, "stagePatch: patch hash mismatch — full download")
+                promise.resolve(false)
+                return
+            }
+
+            val sourceBytes = currentBundle.readBytes()
+            val rebuiltBytes = try {
+                BsPatch.apply(sourceBytes, patchBytes)
+            } catch (e: BsPatch.PatchFormatException) {
+                android.util.Log.w(NAME, "stagePatch: ${e.message} — full download")
+                promise.resolve(false)
+                return
+            }
+
+            val out = File(reactApplicationContext.cacheDir, "scalebun_ota_rebuilt_${System.nanoTime()}")
+            rebuilt = out
+            out.writeBytes(rebuiltBytes)
+
+            val meta = JSONObject()
+            meta.put("sha256", expectedSha256)
+            meta.put("installedAt", System.currentTimeMillis())
+            meta.put("patched", true)
+
+            // SlotManager re-hashes and compares against the full-bundle hash;
+            // a mis-applied patch cannot get past this.
+            val success = slotManager.stage(out, expectedSha256, meta)
+            if (!success) {
+                android.util.Log.w(NAME, "stagePatch: rebuilt bundle failed verification — full download")
+            }
+            promise.resolve(success)
+        } catch (e: Throwable) {
+            // Any unexpected failure is still just "no patch" — the caller has
+            // a working full-download path and a rejected promise would turn a
+            // recoverable situation into a failed update. Throwable, not
+            // Exception: an OutOfMemoryError from a hostile patch is an Error,
+            // and uncaught here it took the host app down.
+            android.util.Log.w(NAME, "stagePatch: ${e.javaClass.simpleName} — full download")
+            promise.resolve(false)
+        } finally {
+            downloadedPatch?.delete()
+            rebuilt?.delete()
+        }
+    }
+
+    /**
+     * Verify a SB-OTA-RSA-SHA256-V1 release envelope with PLATFORM crypto and the
+     * EMBEDDED trusted-key registry — no download, no side effects. Resolves the
+     * verdict JSON (see [Verdict.toJson]); a failed verification is a verdict with
+     * `ok:false` and a stable `code`, never a rejected promise.
+     *
+     * Native because the JS verifier lives inside the very bundle it protects, and
+     * because the trusted key must come from the APK, not from JS or the server.
+     * `SHA256withRSA` + RSA `KeyFactory` are available on every supported Android
+     * API level, so there is no API-33 floor (the reason RSA replaced ed25519).
+     */
+    @ReactMethod
+    override fun verifyRelease(envelopeJson: String, promise: Promise) {
+        try {
+            promise.resolve(ScaleBunOtaReleaseVerifier.verify(envelopeJson, buildContext(), keyRegistry).toJson())
+        } catch (e: Throwable) {
+            promise.resolve(
+                Verdict.fail(OtaFailureCode.INTERNAL_VERIFICATION_ERROR, e.message ?: "internal error").toJson(),
+            )
+        }
+    }
+
+    /**
+     * Native-ENFORCED install (docs §5, §17): verify the RSA signature over the
+     * release payload against an embedded key, THEN download to a temp file,
+     * enforce the signed size + SHA-256, and stage into the `next` slot. JS never
+     * gets to stage bytes that were not proven authentic. Does not activate —
+     * [applyUpdate] promotes per the install mode, unchanged.
+     *
+     * Resolves the verdict JSON: `ok:true` once staged, else `ok:false` with the
+     * stage that failed as a stable `code`.
+     */
+    @ReactMethod
+    override fun verifyAndStageRelease(envelopeJson: String, promise: Promise) {
+        var downloaded: File? = null
+        try {
+            val verdict = ScaleBunOtaReleaseVerifier.verify(envelopeJson, buildContext(), keyRegistry)
+            val payload = verdict.payload
+            if (!verdict.ok || payload == null) {
+                promise.resolve(verdict.toJson())
+                return
+            }
+
+            val url = JSONObject(envelopeJson).optString("downloadUrl", "")
+            if (url.isEmpty()) {
+                promise.resolve(Verdict.fail(OtaFailureCode.DOWNLOAD_FAILED, "envelope has no downloadUrl").toJson())
+                return
+            }
+
+            val temp = File(reactApplicationContext.cacheDir, "scalebun_ota_dl_${System.nanoTime()}")
+            downloaded = temp
+            val failure = BundleDownloader.downloadWithReason(reactApplicationContext, url, temp, ::emitProgress)
+            if (failure != null) {
+                // The reason rides beside the code (never inside it): JS decides whether to retry
+                // on it and re-validates it before it reaches the wire.
+                promise.resolve(
+                    Verdict.fail(OtaFailureCode.DOWNLOAD_FAILED, "download failed", failure).toJson(),
+                )
+                return
+            }
+            // Size first (cheap), against the SIGNED artifactSize.
+            if (temp.length() != payload.artifactSize) {
+                promise.resolve(Verdict.fail(OtaFailureCode.ARTIFACT_SIZE_MISMATCH, "downloaded size mismatch").toJson())
+                return
+            }
+
+            // SlotManager.stage streams a SHA-256 and compares against the signed
+            // artifactSha256 (== resultArtifactSha256 for a full artifact), so a
+            // wrong download cannot be staged. meta carries the sequence used by
+            // the anti-downgrade floor once the bundle is confirmed healthy.
+            val meta = JSONObject()
+                .put("sha256", payload.artifactSha256)
+                .put("releaseSequence", payload.releaseSequence)
+                .put("bundleId", payload.bundleId)
+                .put("releaseId", payload.releaseId)
+                .put("installedAt", System.currentTimeMillis())
+            val staged = slotManager.stage(temp, payload.artifactSha256, meta)
+            if (!staged) {
+                promise.resolve(Verdict.fail(OtaFailureCode.ARTIFACT_HASH_MISMATCH, "staged bytes failed hash check").toJson())
+                return
+            }
+            promise.resolve(verdict.toJson())
+        } catch (e: Throwable) {
+            promise.resolve(
+                Verdict.fail(OtaFailureCode.INTERNAL_VERIFICATION_ERROR, e.message ?: "internal error").toJson(),
+            )
+        } finally {
+            downloaded?.delete()
+        }
+    }
+
+    /**
+     * Stage a SIGNED release from a patch — see NativeScaleBunOta.verifyAndStagePatch.
+     *
+     * Order is the security argument (review conditions a–d):
+     *  1. verify the envelope; size, hash and sequence come ONLY from the verified payload;
+     *  2. the base: current bundle read under SLOT_LOCK, installed through the signed path, hash
+     *     intact, and the one the patch was made from;
+     *  3. the patch download, capped and checked against its transport hash;
+     *  4. BsPatch with the SIGNED size as the required target (header checked before any
+     *     allocation, inflation capped);
+     *  5. stage only if the rebuilt bytes hash to the SIGNED artifactSha256.
+     * Any failure resolves ok:false and the caller downloads the full bundle instead.
+     */
+    override fun verifyAndStagePatch(envelopeJson: String, patchJson: String, promise: Promise) {
+        var downloaded: File? = null
+        var rebuilt: File? = null
+        try {
+            val verdict = ScaleBunOtaReleaseVerifier.verify(envelopeJson, buildContext(), keyRegistry)
+            val payload = verdict.payload
+            if (!verdict.ok || payload == null) {
+                promise.resolve(verdict.toJson())
+                return
+            }
+            if (!payload.resultArtifactSha256.equals(payload.artifactSha256, ignoreCase = true)) {
+                promise.resolve(Verdict.fail(OtaFailureCode.PATCH_RESULT_MISMATCH, "payload is not a full release").toJson())
+                return
+            }
+
+            val patch = JSONObject(patchJson)
+            val patchUrl = patch.optString("url", "")
+            val patchSize = patch.optLong("size", -1L)
+            val patchSha = patch.optString("sha256", "")
+            val baseBundleId = patch.optString("baseBundleId", "")
+            val baseSha = patch.optString("baseSha256", "")
+            if (patchUrl.isEmpty() || patchSha.isEmpty() || baseBundleId.isEmpty() || patchSize <= 0) {
+                promise.resolve(Verdict.fail(OtaFailureCode.PATCH_BASE_MISMATCH, "patch descriptor incomplete").toJson())
+                return
+            }
+            // A patch no smaller than the bundle saves nothing and is not worth the risk.
+            if (patchSize >= payload.artifactSize) {
+                promise.resolve(Verdict.fail(OtaFailureCode.PATCH_BASE_MISMATCH, "patch is not smaller than the release").toJson())
+                return
+            }
+
+            val base = slotManager.readSignedBase()
+            if (base == null || base.bundleId != baseBundleId ||
+                (baseSha.isNotEmpty() && !baseSha.equals(base.sha256, ignoreCase = true))
+            ) {
+                promise.resolve(Verdict.fail(OtaFailureCode.PATCH_BASE_MISMATCH, "installed bundle is not this patch's signed base").toJson())
+                return
+            }
+
+            val temp = File(reactApplicationContext.cacheDir, "scalebun_ota_patch_${System.nanoTime()}")
+            downloaded = temp
+            val failure = BundleDownloader.downloadWithReason(reactApplicationContext, patchUrl, temp, ::emitProgress)
+            if (failure != null) {
+                promise.resolve(Verdict.fail(OtaFailureCode.DOWNLOAD_FAILED, "patch download failed", failure).toJson())
+                return
+            }
+            if (temp.length() != patchSize) {
+                promise.resolve(Verdict.fail(OtaFailureCode.ARTIFACT_SIZE_MISMATCH, "patch size mismatch").toJson())
+                return
+            }
+            val patchBytes = temp.readBytes()
+            if (!sha256Hex(patchBytes).equals(patchSha, ignoreCase = true)) {
+                promise.resolve(Verdict.fail(OtaFailureCode.ARTIFACT_HASH_MISMATCH, "patch hash mismatch").toJson())
+                return
+            }
+
+            val rebuiltBytes = try {
+                BsPatch.apply(base.bytes, patchBytes, payload.artifactSize)
+            } catch (e: BsPatch.PatchFormatException) {
+                promise.resolve(Verdict.fail(OtaFailureCode.PATCH_RESULT_MISMATCH, "patch rejected").toJson())
+                return
+            }
+
+            val out = File(reactApplicationContext.cacheDir, "scalebun_ota_rebuilt_${System.nanoTime()}")
+            rebuilt = out
+            out.writeBytes(rebuiltBytes)
+            val meta = JSONObject()
+                .put("sha256", payload.artifactSha256)
+                .put("releaseSequence", payload.releaseSequence)
+                .put("bundleId", payload.bundleId)
+                .put("releaseId", payload.releaseId)
+                .put("installedAt", System.currentTimeMillis())
+                .put("patched", true)
+            // SlotManager.stage re-hashes the rebuilt bytes against the SIGNED hash: a patch that
+            // produced anything else — whatever the base or the patch contained — cannot be staged.
+            if (!slotManager.stage(out, payload.artifactSha256, meta)) {
+                promise.resolve(Verdict.fail(OtaFailureCode.PATCH_RESULT_MISMATCH, "rebuilt bundle does not match the signed hash").toJson())
+                return
+            }
+            promise.resolve(JSONObject(verdict.toJson()).put("patchUsed", true).toString())
+        } catch (e: Throwable) {
+            // Throwable: an OutOfMemoryError must fall back to the full download, not crash the app.
+            promise.resolve(
+                Verdict.fail(OtaFailureCode.INTERNAL_VERIFICATION_ERROR, e.javaClass.simpleName).toJson(),
+            )
+        } finally {
+            downloaded?.delete()
+            rebuilt?.delete()
+        }
+    }
+
+    private fun sha256Hex(bytes: ByteArray): String {
+        val digest = java.security.MessageDigest.getInstance("SHA-256")
+        val hash = digest.digest(bytes)
+        val sb = StringBuilder(hash.size * 2)
+        for (b in hash) sb.append(String.format("%02x", b))
+        return sb.toString()
+    }
+
+    @ReactMethod
+    override fun applyUpdate(promise: Promise) {
+        try {
+            val success = slotManager.apply()
+            promise.resolve(success)
+        } catch (e: Exception) {
+            promise.reject("APPLY_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun markHealthy() {
+        slotManager.markHealthy()
+    }
+
+    @ReactMethod
+    override fun revertToPrevious(promise: Promise) {
+        try {
+            val success = slotManager.revert()
+            promise.resolve(success)
+        } catch (e: Exception) {
+            promise.reject("REVERT_ERROR", e.message, e)
+        }
+    }
+
+    /**
+     * Restart the React runtime so the applied bundle loads NOW.
+     *
+     * `DevSettings.reload()` is a silent no-op in release builds — verified
+     * live: the JS logged "Triggering app restart…" and the old bundle kept
+     * running in the same process.
+     *
+     * The activation path is architecture-dependent, because "reload" does NOT
+     * mean the same thing on both:
+     *  - Bridge (Old Arch): `recreateReactContextInBackground()` re-runs the
+     *    bundle-resolution path (getJSBundleFile → current/), so an in-process
+     *    recreate correctly picks up the new bundle.
+     *  - Bridgeless (New Arch): `ReactHost.reload()` re-runs JS from the
+     *    jsBundleFilePath fixed at host construction — it never re-reads the
+     *    staged bundle, so an in-process reload keeps running the OLD one. RN
+     *    offers no way to swap the bundle file in a live bridgeless process, so
+     *    we do a REAL process restart instead (see [restartProcess]).
+     *
+     * iOS cannot be force-relaunched (Apple disallows it), so the iOS module
+     * always defers to ON_NEXT_RESTART rather than mirroring this.
+     */
+    @ReactMethod
+    override fun restartApp() {
+        // Tell the boot guard this next launch is ours.
+        //
+        // Hooked HERE rather than at the JS call sites so it cannot be forgotten:
+        // every restart the SDK performs goes through this method, and each one
+        // used to spend one of the bundle's two boot attempts as though it had
+        // crashed. Recorded before the restart is dispatched, because after it
+        // there is no "after".
+        try {
+            slotManager.markIntentionalRestart()
+        } catch (e: Throwable) {
+            android.util.Log.w(NAME, "restartApp: could not record intent", e)
+        }
+        val application = reactApplicationContext.applicationContext
+        com.facebook.react.bridge.UiThreadUtil.runOnUiThread {
+            try {
+                val reactApp = application as? com.facebook.react.ReactApplication
+                if (reactApp == null) {
+                    android.util.Log.e(NAME, "restartApp: application is not a ReactApplication")
+                    return@runOnUiThread
+                }
+                val host = try {
+                    reactApp.reactHost
+                } catch (_: Throwable) {
+                    null
+                }
+                if (host != null) {
+                    // Bridgeless (New Architecture): ReactHost.reload() re-runs JS
+                    // but ONLY from the jsBundleFilePath captured when the host was
+                    // constructed at process launch — it never re-reads the staged
+                    // bundle. So a mid-session reload keeps running the OLD bundle
+                    // ("INSTALL DID NOT TAKE EFFECT — running none"), and the update
+                    // silently never activates. RN exposes no supported way to swap
+                    // the JS bundle file in a live bridgeless process, so the only
+                    // correct activation is a REAL process restart: the fresh
+                    // process re-runs MainApplication's getJSBundleFile() → current/
+                    // → the new bundle. The boot marker persisted above survives the
+                    // process kill, and because the new bundle now actually boots it
+                    // clears its own health marker (no false crash-loop revert).
+                    android.util.Log.i(NAME, "restartApp: relaunching process (bridgeless)")
+                    restartProcess(application)
+                    return@runOnUiThread
+                }
+                android.util.Log.i(NAME, "restartApp: recreating React context (bridge)")
+                reactApp.reactNativeHost.reactInstanceManager
+                    .recreateReactContextInBackground()
+            } catch (e: Throwable) {
+                // Never crash the host over a restart; the update still
+                // activates on the next cold start.
+                android.util.Log.e(NAME, "restartApp failed — update applies on next cold start", e)
+            }
+        }
+    }
+
+    /**
+     * A genuine OS process restart — the only way a bridgeless host loads a
+     * newly-staged OTA bundle, since RN cannot swap the JS bundle file in a live
+     * process.
+     *
+     * Full-task relaunch (API 11+): tear the current task down, start it fresh,
+     * then exit THIS process so the OS relaunches into a brand-new one that
+     * re-resolves MainApplication.getJSBundleFile() → current/. The startActivity
+     * request is serviced by the system ActivityManager (a separate process), so
+     * it survives this process's death and the app reappears on the new bundle.
+     */
+    private fun restartProcess(context: Context) {
+        val ctx = context.applicationContext
+        val launch = ctx.packageManager.getLaunchIntentForPackage(ctx.packageName)
+        if (launch?.component == null) {
+            android.util.Log.e(
+                NAME,
+                "restartApp: no launch intent — update applies on next cold start",
+            )
+            return
+        }
+        val restart = android.content.Intent.makeRestartActivityTask(launch.component)
+        restart.setPackage(ctx.packageName)
+        ctx.startActivity(restart)
+        Runtime.getRuntime().exit(0)
+    }
+}