@scalebun/react-native 1.0.1 → 1.0.3

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

@@ -0,0 +1,170 @@
+package com.scalebun.rn.ota
+
+import android.util.Log
+import java.io.File
+import java.io.FileOutputStream
+import java.net.HttpURLConnection
+import java.net.URL
+import java.util.zip.GZIPInputStream
+
+/**
+ * Downloads an OTA bundle to a local file (OTA-05).
+ *
+ * WHY THIS EXISTS. `OtaOrchestrator.sync()` has always passed `bundle.url` — a
+ * presigned HTTPS URL — into `stageBundle()`, while both native slot managers
+ * treated that argument as a filesystem path. Android returned false from
+ * `File(url).exists()`, iOS threw from `copyItem`. No component anywhere in the
+ * SDK downloaded the bundle, so OTA could never install an update at all, and
+ * every safety mechanism downstream (boot guard, slot rollback, guard
+ * thresholds) had only ever run against synthetic events.
+ *
+ * Deliberately built on `HttpURLConnection`: the SDK ships zero third-party
+ * runtime dependencies, and adding OkHttp for one download would put a
+ * transitive version constraint on every host app.
+ *
+ * C2a — gzip. `Content-Encoding: gzip` is decoded transparently here, so the
+ * hash the slot manager verifies is always of the *decompressed* bundle, which
+ * is what the server hashed and what the signature covers. `Accept-Encoding` is
+ * set explicitly because HttpURLConnection's automatic gzip handling is disabled
+ * once a caller touches that header, and the object store serves whatever the
+ * upload was encoded as.
+ */
+internal object BundleDownloader {
+
+    private const val TAG = "ScaleBunOta"
+
+    /** Matches the server-side finalize cap. A larger body is a bug or an attack. */
+    private const val MAX_BYTES = 50L * 1024 * 1024
+
+    private const val CONNECT_TIMEOUT_MS = 15_000
+    private const val READ_TIMEOUT_MS = 60_000
+    private const val MAX_REDIRECTS = 5
+
+    /** Emit at most one progress callback per this interval — the byte loop is hot. */
+    private const val PROGRESS_INTERVAL_MS = 500L
+
+    /**
+     * Download [url] into [destination]. Returns true on success.
+     *
+     * The caller owns [destination]; on any failure it is removed so a partial
+     * body can never be mistaken for a complete bundle. Integrity is NOT checked
+     * here — [SlotManager.stage] re-hashes what actually landed on disk, which is
+     * the only measurement that matters.
+     *
+     * [onProgress] receives (bytesRead, totalBytes) at most every
+     * [PROGRESS_INTERVAL_MS], plus one final call at completion. `totalBytes` is
+     * -1 when the server sent no Content-Length (chunked) or the body is gzip —
+     * the DECLARED length is the compressed size, which would make a progress
+     * bar overshoot 100% and walk backwards. Unknown is reported as unknown.
+     */
+    fun download(
+        url: String,
+        destination: File,
+        onProgress: ((bytesRead: Long, totalBytes: Long) -> Unit)? = null,
+    ): Boolean {
+        var connection: HttpURLConnection? = null
+        try {
+            var current = URL(url)
+            var redirects = 0
+
+            // Followed manually: HttpURLConnection will not follow across
+            // protocols, and presigned URLs on some object stores redirect
+            // http→https. Capped so a redirect loop cannot hang the update.
+            while (true) {
+                connection = (current.openConnection() as HttpURLConnection).apply {
+                    connectTimeout = CONNECT_TIMEOUT_MS
+                    readTimeout = READ_TIMEOUT_MS
+                    requestMethod = "GET"
+                    instanceFollowRedirects = false
+                    setRequestProperty("Accept-Encoding", "gzip")
+                }
+
+                val code = connection.responseCode
+                if (code == HttpURLConnection.HTTP_MOVED_PERM ||
+                    code == HttpURLConnection.HTTP_MOVED_TEMP ||
+                    code == HttpURLConnection.HTTP_SEE_OTHER ||
+                    code == 307 || code == 308
+                ) {
+                    val location = connection.getHeaderField("Location")
+                    connection.disconnect()
+                    if (location.isNullOrBlank() || ++redirects > MAX_REDIRECTS) {
+                        Log.e(TAG, "Download failed: redirect limit or missing Location")
+                        return false
+                    }
+                    current = URL(current, location)
+                    continue
+                }
+
+                if (code !in 200..299) {
+                    Log.e(TAG, "Download failed: HTTP $code for ${current.host}")
+                    return false
+                }
+                break
+            }
+
+            val conn = connection ?: return false
+
+            // Reject an oversized body before reading it, when the server declares one.
+            val declared = conn.getHeaderFieldLong("Content-Length", -1L)
+            if (declared > MAX_BYTES) {
+                Log.e(TAG, "Download rejected: declared $declared bytes exceeds $MAX_BYTES")
+                return false
+            }
+
+            val gzipped = conn.contentEncoding?.equals("gzip", ignoreCase = true) == true
+            val source = if (gzipped) GZIPInputStream(conn.inputStream) else conn.inputStream
+
+            // Total is only trustworthy when it measures the same stream we
+            // count: a gzip body's Content-Length is the COMPRESSED size while
+            // `total` counts decompressed bytes.
+            val progressTotal = if (gzipped) -1L else declared
+
+            destination.parentFile?.mkdirs()
+
+            var total = 0L
+            var lastProgressAt = 0L
+            source.use { input ->
+                FileOutputStream(destination).use { output ->
+                    val buffer = ByteArray(64 * 1024)
+                    while (true) {
+                        val read = input.read(buffer)
+                        if (read == -1) break
+                        total += read
+                        // Enforced during streaming too: Content-Length is absent on
+                        // chunked responses, and gzip hides the decompressed size, so
+                        // this is the only cap that holds for a zip bomb.
+                        if (total > MAX_BYTES) {
+                            Log.e(TAG, "Download aborted: exceeded $MAX_BYTES bytes")
+                            output.close()
+                            destination.delete()
+                            return false
+                        }
+                        output.write(buffer, 0, read)
+
+                        if (onProgress != null) {
+                            val now = System.currentTimeMillis()
+                            if (now - lastProgressAt >= PROGRESS_INTERVAL_MS) {
+                                lastProgressAt = now
+                                onProgress(total, progressTotal)
+                            }
+                        }
+                    }
+                    output.fd.sync()
+                }
+            }
+
+            // Terminal callback: bytesRead == totalBytes signals completion even
+            // when the whole body arrived inside one throttle window.
+            onProgress?.invoke(total, total)
+
+            Log.i(TAG, "Downloaded ${total / 1024} KB${if (gzipped) " (gzip)" else ""}")
+            return true
+        } catch (e: Exception) {
+            Log.e(TAG, "Download failed", e)
+            destination.delete()
+            return false
+        } finally {
+            connection?.disconnect()
+        }
+    }
+}

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

@@ -28,7 +28,7 @@ class ScaleBunOtaModule(reactContext: ReactApplicationContext) :
         const val NAME = "ScaleBunOta"
 
         /**
-         * Static entry point for MainApplication.getJSBundleFile().
+         * 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.
@@ -36,13 +36,44 @@ class ScaleBunOtaModule(reactContext: ReactApplicationContext) :
          * Returns null in DEBUG builds (Metro always wins) or when no OTA
          * bundle is installed.
          *
-         * Usage in MainApplication.kt:
+         * ── 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? {
@@ -67,6 +98,36 @@ class ScaleBunOtaModule(reactContext: ReactApplicationContext) :
 
     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
@@ -78,13 +139,41 @@ class ScaleBunOtaModule(reactContext: ReactApplicationContext) :
         return slotManager.slotState().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) {
+        var downloaded: File? = null
         try {
-            val sourceFile = File(sourcePath)
-            if (!sourceFile.exists()) {
-                promise.resolve(false)
-                return
+            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(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
@@ -96,16 +185,34 @@ class ScaleBunOtaModule(reactContext: ReactApplicationContext) :
             promise.resolve(success)
         } catch (e: Exception) {
             promise.reject("STAGE_ERROR", e.message, e)
+        } finally {
+            downloaded?.delete()
         }
     }
 
+    /**
+     * Binary-patch staging (S7-NAT-1) — NOT IMPLEMENTED on Android.
+     *
+     * [SlotManager] has no patch/bspatch path, so there is nothing to apply a diff
+     * with. The JS contract in `src/specs/NativeScaleBunOta.ts` defines `false` as
+     * "patching unavailable — fall back to a full-bundle download", which is exactly
+     * the honest answer here; OtaOrchestrator then downloads the whole bundle and the
+     * update still lands. Resolving false (rather than rejecting) keeps that fallback
+     * on its documented path instead of surfacing an error the caller must special-case.
+     *
+     * This override must exist regardless: on the New Architecture the codegen base
+     * (`NativeScaleBunOtaSpec`, generated from the JS spec) declares `stagePatch`
+     * abstract, so omitting it fails Kotlin compilation for every new-arch consumer.
+     *
+     * Replace the body with a real bspatch once SlotManager grows patch support.
+     */
     @ReactMethod
-    override fun stagePatch(patchUrl: String, patchSha256: String, expectedSha256: String, promise: Promise) {
-        // Delta/patch updates (native bspatch) are not implemented yet. The TS spec
-        // declares stagePatch, so the codegen New-Arch base makes it an abstract
-        // member this class MUST override — otherwise @scalebun/react-native fails
-        // to compile on Android. Resolve false so OtaOrchestrator falls back to
-        // full-bundle staging (which is the only supported path today).
+    override fun stagePatch(
+        patchUrl: String,
+        patchSha256: String,
+        expectedSha256: String,
+        promise: Promise,
+    ) {
         promise.resolve(false)
     }
 
@@ -133,4 +240,45 @@ class ScaleBunOtaModule(reactContext: ReactApplicationContext) :
             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. This is the production-grade path:
+     * bridgeless hosts reload through [com.facebook.react.ReactHost.reload],
+     * bridge hosts through `recreateReactContextInBackground()`. Both re-run
+     * the bundle-resolution path, which is what picks up the new `current/`.
+     */
+    @ReactMethod
+    override fun restartApp() {
+        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) {
+                    android.util.Log.i(NAME, "restartApp: reloading via ReactHost (bridgeless)")
+                    host.reload("ScaleBun OTA update")
+                    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)
+            }
+        }
+    }
 }

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

@@ -202,7 +202,10 @@ class SlotManager(private val filesDir: File) {
 
         try {
             val markerJson = JSONObject(bootMarker.readText())
-            val markerBundleId = markerJson.optString("bundleId", "")
+            // Read the marker's sha256, falling back to the legacy `bundleId`
+            // field so a marker written by a previous build is still readable.
+            val markerId = markerJson.optString("sha256", "")
+                .ifEmpty { markerJson.optString("bundleId", "") }
 
             val metaFile = File(currentSlot, META_FILENAME)
             if (!metaFile.exists()) {
@@ -212,10 +215,21 @@ class SlotManager(private val filesDir: File) {
             }
 
             val currentMeta = JSONObject(metaFile.readText())
-            val currentBundleId = currentMeta.optString("bundleId", "")
-
-            if (currentBundleId != markerBundleId) {
-                Log.w(TAG, "Boot marker bundleId mismatch — auto-reverting")
+            val currentId = currentMeta.optString("sha256", "")
+
+            // Both sides must be non-empty for the comparison to mean anything.
+            // Treating "" == "" as a match is what made this check vacuous
+            // before; treating "" != "x" as corruption would revert every
+            // bundle staged by an older build. So: compare only when we have
+            // two real values, and say so plainly when we do not.
+            if (markerId.isEmpty() || currentId.isEmpty()) {
+                Log.w(
+                    TAG,
+                    "Boot guard cannot verify this bundle — marker or meta has no sha256. " +
+                        "Leaving it in place; restage with a current SDK to re-enable the check.",
+                )
+            } else if (currentId != markerId) {
+                Log.w(TAG, "Boot marker sha256 mismatch — auto-reverting")
                 revert()
             }
             // If they match: this is the first launch of a new bundle.
@@ -244,7 +258,19 @@ class SlotManager(private val filesDir: File) {
         val meta = readMeta(currentSlot)
         if (meta != null) {
             val marker = JSONObject()
-            marker.put("bundleId", meta.optString("bundleId"))
+            // Identify the bundle by its SHA-256, not by `bundleId`.
+            //
+            // `stageBundle` writes a meta.json containing only `sha256` and
+            // `installedAt` — it is never told the bundleId. So this used to
+            // record an empty string, checkBootGuard() then compared that empty
+            // string against another empty string read from the same absent
+            // field, they were always equal, and the corruption check could
+            // never fire. The guard's most important comparison was a no-op.
+            //
+            // sha256 is the field that is actually present, and it is a
+            // strictly better identity for this purpose anyway: it detects a
+            // bundle whose CONTENT changed, not merely one whose id differs.
+            marker.put("sha256", meta.optString("sha256"))
             marker.put("appliedAt", System.currentTimeMillis())
             otaRoot.mkdirs()
             bootMarker.writeText(marker.toString())

package/android/src/oldarch/java/com/scalebun/rn/ota/ScaleBunOtaSpec.kt

@@ -18,8 +18,14 @@ abstract class ScaleBunOtaSpec(reactContext: ReactApplicationContext) :
     abstract fun getActiveBundle(): String?
     abstract fun getSlotState(): String
     abstract fun stageBundle(sourcePath: String, sha256: String, promise: Promise)
-    abstract fun stagePatch(patchUrl: String, patchSha256: String, expectedSha256: String, promise: Promise)
+    abstract fun stagePatch(
+        patchUrl: String,
+        patchSha256: String,
+        expectedSha256: String,
+        promise: Promise,
+    )
     abstract fun applyUpdate(promise: Promise)
     abstract fun markHealthy()
     abstract fun revertToPrevious(promise: Promise)
+    abstract fun restartApp()
 }

package/ios/Ota/BundleDownloader.swift

@@ -0,0 +1,182 @@
+import Foundation
+
+/**
+ Downloads an OTA bundle to a local file (OTA-05).
+
+ WHY THIS EXISTS. `OtaOrchestrator.sync()` has always passed `bundle.url` — a
+ presigned HTTPS URL — into `stageBundle()`, while `OtaSlotManager.stage` treated
+ that argument as a filesystem path and called
+ `copyItem(at: URL(fileURLWithPath:))`, which throws for a remote URL. No part of
+ the SDK downloaded the bundle, so OTA could never install an update, and every
+ safety mechanism downstream had only ever run against synthetic events.
+
+ Synchronous by design: `stageBundle` is a promise-returning bridge method that
+ already runs off the main thread, and the slot manager's staging step is
+ synchronous. A semaphore here keeps the call site a straight line rather than
+ threading a completion handler through the bridge for no behavioural gain.
+
+ Delegate-based rather than completion-handler-based, for one reason: the size
+ cap must fire DURING the stream, not after it. The previous implementation
+ checked the file size only once the download completed — by which point a
+ hostile or buggy 5 GB body had already been written to the user's disk. The
+ Android downloader has always cancelled mid-stream; this brings iOS to parity.
+ */
+enum BundleDownloader {
+
+    /// Matches the server-side finalize cap. A larger body is a bug or an attack.
+    fileprivate static let maxBytes: Int64 = 50 * 1024 * 1024
+    fileprivate static let timeout: TimeInterval = 60
+
+    /**
+     Download `urlString` to `destination`. Returns true on success.
+
+     Integrity is NOT checked here — `OtaSlotManager.stage` re-hashes what landed
+     on disk, which is the only measurement that matters. On any failure the
+     destination is removed so a partial body cannot be mistaken for a bundle.
+
+     C2a: `URLSession` advertises and transparently decodes gzip, so what reaches
+     disk is the decompressed bundle — the same bytes the server hashed and the
+     signature covers.
+     */
+    static func download(urlString: String, destination: URL) -> Bool {
+        guard let url = URL(string: urlString) else {
+            NSLog("[ScaleBunOta] Download failed: malformed URL")
+            return false
+        }
+
+        let configuration = URLSessionConfiguration.ephemeral
+        configuration.timeoutIntervalForRequest = timeout
+        configuration.timeoutIntervalForResource = timeout * 4
+
+        let delegate = SizeCappedDownloadDelegate(destination: destination)
+        let session = URLSession(
+            configuration: configuration,
+            delegate: delegate,
+            delegateQueue: nil
+        )
+
+        // downloadTask streams to a temp file rather than buffering the whole
+        // bundle in memory — a 50 MB dataTask spike is enough to get the host app
+        // jetsammed on an older device.
+        session.downloadTask(with: url).resume()
+        _ = delegate.semaphore.wait(timeout: .now() + timeout * 4)
+
+        // The session retains its delegate until invalidated; without this,
+        // every download across the app's lifetime leaked a session + delegate.
+        session.invalidateAndCancel()
+
+        if !delegate.success {
+            try? FileManager.default.removeItem(at: destination)
+        }
+        return delegate.success
+    }
+}
+
+/**
+ URLSession delegate enforcing the byte cap while the body streams in.
+
+ `urlSession(_:downloadTask:didWriteData:...)` fires per chunk; the moment the
+ running total (or the server's own Content-Length claim) exceeds the cap, the
+ task is cancelled — nothing more lands on disk. All terminal paths signal the
+ semaphore exactly once: didFinishDownloading only signals on success, and every
+ completion (success, cancel, error, timeout) also passes through
+ `didCompleteWithError`, where the single signal for failures lives.
+ */
+private final class SizeCappedDownloadDelegate: NSObject, URLSessionDownloadDelegate {
+    let semaphore = DispatchSemaphore(value: 0)
+    private(set) var success = false
+
+    private let destination: URL
+    private var cancelledForSize = false
+
+    init(destination: URL) {
+        self.destination = destination
+    }
+
+    /// Emit at most one progress event per this interval — didWriteData is hot.
+    private static let progressIntervalMs: Int64 = 500
+    private var lastProgressAtMs: Int64 = 0
+
+    func urlSession(
+        _ session: URLSession,
+        downloadTask: URLSessionDownloadTask,
+        didWriteData bytesWritten: Int64,
+        totalBytesWritten: Int64,
+        totalBytesExpectedToWrite: Int64
+    ) {
+        let claimed = totalBytesExpectedToWrite // NSURLSessionTransferSizeUnknown (-1) when absent
+        if totalBytesWritten > BundleDownloader.maxBytes ||
+            (claimed > 0 && claimed > BundleDownloader.maxBytes) {
+            cancelledForSize = true
+            NSLog(
+                "[ScaleBunOta] Download rejected: exceeds \(BundleDownloader.maxBytes) bytes " +
+                "(written=\(totalBytesWritten), claimed=\(claimed)) — cancelling mid-stream"
+            )
+            downloadTask.cancel()
+            return
+        }
+
+        // Throttled progress to JS. `claimed` can be the COMPRESSED length on
+        // an encoded response while written bytes are decompressed — JS clamps
+        // the percentage, and -1 (unknown) is passed through as unknown.
+        let nowMs = Int64(Date().timeIntervalSince1970 * 1000)
+        if nowMs - lastProgressAtMs >= SizeCappedDownloadDelegate.progressIntervalMs {
+            lastProgressAtMs = nowMs
+            ScaleBunOtaEventsModule.emitProgress(
+                bytesRead: totalBytesWritten,
+                totalBytes: claimed
+            )
+        }
+    }
+
+    func urlSession(
+        _ session: URLSession,
+        downloadTask: URLSessionDownloadTask,
+        didFinishDownloadingTo location: URL
+    ) {
+        if let http = downloadTask.response as? HTTPURLResponse,
+           !(200...299).contains(http.statusCode) {
+            NSLog("[ScaleBunOta] Download failed: HTTP \(http.statusCode)")
+            return // didCompleteWithError still fires and signals
+        }
+
+        let fm = FileManager.default
+
+        // Belt over the streaming brace: a body small enough to never trip the
+        // per-chunk check is re-measured once whole.
+        let attributes = try? fm.attributesOfItem(atPath: location.path)
+        let size = (attributes?[.size] as? NSNumber)?.int64Value ?? 0
+        if size > BundleDownloader.maxBytes {
+            NSLog("[ScaleBunOta] Download rejected: \(size) bytes exceeds \(BundleDownloader.maxBytes)")
+            return
+        }
+
+        do {
+            try? fm.removeItem(at: destination)
+            try fm.createDirectory(
+                at: destination.deletingLastPathComponent(),
+                withIntermediateDirectories: true
+            )
+            // The system deletes `location` as soon as this handler returns,
+            // so the file must be moved out synchronously, not scheduled.
+            try fm.moveItem(at: location, to: destination)
+            success = true
+            // Terminal tick: read == total signals completion even when the
+            // whole body arrived inside one throttle window.
+            ScaleBunOtaEventsModule.emitProgress(bytesRead: size, totalBytes: size)
+        } catch {
+            NSLog("[ScaleBunOta] Download failed to persist: \(error.localizedDescription)")
+        }
+    }
+
+    func urlSession(
+        _ session: URLSession,
+        task: URLSessionTask,
+        didCompleteWithError error: Error?
+    ) {
+        if let error = error, !cancelledForSize {
+            NSLog("[ScaleBunOta] Download failed: \(error.localizedDescription)")
+        }
+        semaphore.signal()
+    }
+}