@scalebun-release/react-native 2.5.0

package/android/src/main/java/com/scalebun/rn/engage/ScaleBunNotificationPresenter.kt

@@ -0,0 +1,110 @@
+package com.scalebun.rn.engage
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+
+/**
+ * ScaleBun native notification presenter — framework-only (NO Notifee, NO new
+ * compile dependency). This is the SDK's native-first display layer: it owns
+ * channel creation and foreground display using only `android.app.*` APIs, so the
+ * same logic can be reused by a future bundled `FirebaseMessagingService`, a native
+ * Android SDK, or mirrored by a Flutter wrapper.
+ *
+ * Delivery is unchanged: background/tray notifications are still rendered by the OS
+ * from the FCM `notification` payload via the host's messaging service. This presenter
+ * only DISPLAYS while the app is foreground (where the OS suppresses the tray), driven
+ * by the JS adapter calling through the bridge.
+ */
+object ScaleBunNotificationPresenter {
+
+    /** Intent extra: marks an activity launch as originating from a ScaleBunB notification. */
+    const val EXTRA_SCALEBUN_FLAG = "scalebun_from_notification"
+
+    /** Intent extra: JSON string of the notification `data` map, for deep-link routing. */
+    const val EXTRA_SCALEBUN_DATA = "scalebun_notification_data"
+
+    /**
+     * Create (or update) the notification channel natively. Required on API 26+;
+     * a no-op on older releases (channels did not exist). Idempotent — safe to call
+     * on every push enable.
+     */
+    fun ensureChannel(
+        context: Context,
+        channelId: String,
+        channelName: String,
+        importance: Int,
+        description: String?,
+    ) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
+            ?: return
+        val channel = NotificationChannel(channelId, channelName, importance)
+        if (!description.isNullOrEmpty()) channel.description = description
+        manager.createNotificationChannel(channel)
+    }
+
+    /**
+     * Display a notification natively. Tapping it relaunches the host app's launcher
+     * activity with the ScaleBunB extras attached, so `ScaleBunEngageModule` can surface an
+     * "opened" event (foreground/background) or seed the initial notification (cold start).
+     *
+     * Uses the host app's own icon (`applicationInfo.icon`) as the small icon — no asset
+     * bundled by the SDK, no dependency on the host declaring `default_notification_icon`.
+     */
+    fun show(
+        context: Context,
+        channelId: String,
+        title: String?,
+        body: String?,
+        dataJson: String?,
+        notificationId: Int,
+    ) {
+        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
+            ?: return
+
+        val launchIntent = context.packageManager
+            .getLaunchIntentForPackage(context.packageName)
+            ?.apply {
+                addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP)
+                putExtra(EXTRA_SCALEBUN_FLAG, true)
+                if (!dataJson.isNullOrEmpty()) putExtra(EXTRA_SCALEBUN_DATA, dataJson)
+            }
+
+        val pendingFlags =
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+                PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+            } else {
+                PendingIntent.FLAG_UPDATE_CURRENT
+            }
+
+        val contentIntent: PendingIntent? = launchIntent?.let {
+            PendingIntent.getActivity(context, notificationId, it, pendingFlags)
+        }
+
+        val smallIcon = context.applicationInfo.icon
+
+        val builder = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            Notification.Builder(context, channelId)
+        } else {
+            @Suppress("DEPRECATION")
+            Notification.Builder(context)
+        }
+
+        builder
+            .setSmallIcon(smallIcon)
+            .setContentTitle(title ?: "")
+            .setContentText(body ?: "")
+            .setAutoCancel(true)
+        if (!body.isNullOrEmpty()) {
+            builder.style = Notification.BigTextStyle().bigText(body)
+        }
+        if (contentIntent != null) builder.setContentIntent(contentIntent)
+
+        manager.notify(notificationId, builder.build())
+    }
+}

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

@@ -0,0 +1,240 @@
+package com.scalebun.rn.ota
+
+import java.io.ByteArrayOutputStream
+import java.util.zip.Inflater
+
+/**
+ * bspatch — reconstructs a bundle from a previous bundle plus a delta.
+ *
+ * WHAT WAS WRONG. `stagePatch` resolved `false` unconditionally on both
+ * platforms, so the whole delta pipeline was decorative: the server generated
+ * patches, the check response advertised them, the orchestrator asked for
+ * them, and the device always fell back to a full download. Nobody ever
+ * downloaded less than the entire bundle.
+ *
+ * FORMAT (produced by the backend's `bsdiff.ts`; all integers little-endian):
+ *
+ *   0   8   magic "SBDIFF01"
+ *   8   4   target size — the exact number of bytes this must produce
+ *   12  4   deflated control-block length
+ *   16  4   inflated control-block length
+ *   20  4   deflated diff-block length
+ *   24  4   inflated diff-block length
+ *   28  4   deflated extra-block length
+ *   32  4   inflated extra-block length
+ *   36  .   deflate(control) ++ deflate(diff) ++ deflate(extra)
+ *
+ * Control is a run of (addLen, extraLen, seek) int32 triples. `addLen` bytes
+ * are read from the diff block and added, bytewise mod 256, to the source at
+ * the current read cursor; `extraLen` bytes are copied verbatim from the extra
+ * block; then the source cursor moves by the signed `seek`.
+ *
+ * WHY RAW DEFLATE. Android has `java.util.zip` and iOS has the Compression
+ * framework; neither ships zstd. On real Hermes bundles zstd-19 beat deflate-9
+ * by 0.3 percentage points (95.79% vs 95.51%) — not worth a native dependency
+ * on two platforms forever. See the backend module for the measurements.
+ *
+ * EVERY FIELD HERE IS UNTRUSTED. The patch arrives over the network, so a
+ * malformed or hostile one must fail cleanly rather than index out of bounds.
+ * Each run is bounds-checked against all four buffers before it is used, and
+ * the caller still verifies the SHA-256 of the result before anything is
+ * promoted — this routine producing the wrong bytes can never install them.
+ */
+internal object BsPatch {
+
+    private const val MAGIC = "SBDIFF01"
+    private const val HEADER_BYTES = 36
+
+    /**
+     * Refuse absurd allocations from a corrupt header (bundles are single-digit MB). 50 MB is the
+     * server's finalize cap and the downloader's MAX_BYTES: no bundle can legitimately be larger,
+     * and 256 MB — the old value — was an allocation a phone's heap may not survive.
+     */
+    private const val MAX_TARGET_BYTES = 50 * 1024 * 1024
+
+    class PatchFormatException(message: String) : Exception(message)
+
+    private fun u32(b: ByteArray, off: Int): Long =
+        (b[off].toLong() and 0xff) or
+            ((b[off + 1].toLong() and 0xff) shl 8) or
+            ((b[off + 2].toLong() and 0xff) shl 16) or
+            ((b[off + 3].toLong() and 0xff) shl 24)
+
+    private fun i32(b: ByteArray, off: Int): Int =
+        (b[off].toInt() and 0xff) or
+            ((b[off + 1].toInt() and 0xff) shl 8) or
+            ((b[off + 2].toInt() and 0xff) shl 16) or
+            ((b[off + 3].toInt() and 0xff) shl 24)
+
+    /**
+     * Raw DEFLATE (no zlib header) — matches Node's `deflateRawSync`.
+     *
+     * CAPPED at [maxOut], the size the header declared for this block. Uncapped, a patch of a
+     * few KB whose block inflates to gigabytes (a deflate bomb) filled the heap before the
+     * size check that followed could reject it — an OutOfMemoryError, which is not an
+     * Exception, so no caller's catch saw it and the host app crashed. The stream is now
+     * refused the moment it produces more than it declared.
+     */
+    private fun inflateRaw(data: ByteArray, offset: Int, length: Int, maxOut: Int): ByteArray {
+        val inflater = Inflater(true)
+        try {
+            inflater.setInput(data, offset, length)
+            val out = ByteArrayOutputStream(minOf(maxOf(maxOut, 16), 1 shl 20))
+            val buf = ByteArray(64 * 1024)
+            var total = 0L
+            while (true) {
+                // A corrupt stream makes Inflater throw DataFormatException. It is translated so a
+                // malformed patch fails with ONE exception type, the one callers are written for —
+                // the fuzz harness found it escaping raw on 1 in 11 mutated patches.
+                val n = try {
+                    inflater.inflate(buf)
+                } catch (e: java.util.zip.DataFormatException) {
+                    throw PatchFormatException("compressed block is corrupt")
+                }
+                if (n > 0) {
+                    total += n
+                    if (total > maxOut) {
+                        throw PatchFormatException("compressed block inflates past its declared $maxOut bytes")
+                    }
+                    out.write(buf, 0, n)
+                    continue
+                }
+                // ORDER MATTERS. A block that legitimately decodes to zero bytes
+                // — an empty extra block, which happens whenever a patch is one
+                // unbroken run — also reports needsInput() once the stream is
+                // consumed. Testing needsInput() first therefore rejected valid
+                // patches as truncated; `finished()` has to be asked first.
+                if (inflater.finished()) break
+                if (inflater.needsInput() || inflater.needsDictionary()) {
+                    throw PatchFormatException("compressed block is truncated")
+                }
+            }
+            return out.toByteArray()
+        } finally {
+            inflater.end()
+        }
+    }
+
+    /**
+     * Apply [patch] to [source], returning the reconstructed bundle.
+     *
+     * @throws PatchFormatException if the patch is malformed, truncated, or
+     *   inconsistent with [source]. Callers treat this as "fall back to a full
+     *   download", never as a fatal error.
+     */
+    /**
+     * @param expectedTargetSize the size the result MUST have — for a signed release, the signed
+     *   `artifactSize`. Checked against the header BEFORE anything is allocated or inflated, so a
+     *   patch cannot make the device build something of a size the publisher never signed.
+     */
+    @JvmOverloads
+    fun apply(source: ByteArray, patch: ByteArray, expectedTargetSize: Long? = null): ByteArray {
+        if (patch.size < HEADER_BYTES) throw PatchFormatException("patch too short")
+        val magic = String(patch, 0, 8, Charsets.ISO_8859_1)
+        if (magic != MAGIC) throw PatchFormatException("bad patch magic '$magic'")
+
+        val targetSizeL = u32(patch, 8)
+        val cLen = u32(patch, 12)
+        val cRaw = u32(patch, 16)
+        val dLen = u32(patch, 20)
+        val dRaw = u32(patch, 24)
+        val eLen = u32(patch, 28)
+        val eRaw = u32(patch, 32)
+
+        if (targetSizeL > MAX_TARGET_BYTES) {
+            throw PatchFormatException("declared target size $targetSizeL is implausible")
+        }
+        if (expectedTargetSize != null && targetSizeL != expectedTargetSize) {
+            throw PatchFormatException("patch builds $targetSizeL bytes, the signed release is $expectedTargetSize")
+        }
+        // Every block is bounded by what it can legitimately contribute to the target: diff and
+        // extra bytes each land in the output at most once, and every control triple (12 bytes)
+        // advances the output or is the final one. Anything larger is corrupt or hostile, and is
+        // refused before a byte is inflated.
+        if (dRaw > targetSizeL || eRaw > targetSizeL) {
+            throw PatchFormatException("declared diff/extra block is larger than the target")
+        }
+        if (cRaw > 12L * (targetSizeL + 1)) {
+            throw PatchFormatException("declared control block is larger than the target allows")
+        }
+        if (HEADER_BYTES + cLen + dLen + eLen != patch.size.toLong()) {
+            throw PatchFormatException("block lengths do not match patch size")
+        }
+        val targetSize = targetSizeL.toInt()
+
+        var off = HEADER_BYTES
+        val control = inflateRaw(patch, off, cLen.toInt(), cRaw.toInt()); off += cLen.toInt()
+        val diff = inflateRaw(patch, off, dLen.toInt(), dRaw.toInt()); off += dLen.toInt()
+        val extra = inflateRaw(patch, off, eLen.toInt(), eRaw.toInt())
+
+        // A block that inflates to a size other than the declared one is
+        // corrupt; iOS sizes its buffers from these numbers, so Android holds
+        // the format to the same contract rather than trusting the stream.
+        if (control.size.toLong() != cRaw) throw PatchFormatException("control block size mismatch")
+        if (diff.size.toLong() != dRaw) throw PatchFormatException("diff block size mismatch")
+        if (extra.size.toLong() != eRaw) throw PatchFormatException("extra block size mismatch")
+
+        if (control.size % 12 != 0) {
+            throw PatchFormatException("control block is not a whole number of triples")
+        }
+        // Every output byte comes from the diff block (one per added byte) or the extra block, so
+        // a real patch can never produce more than their sum — measured on what actually INFLATED,
+        // not what the header claims. Checked before the output is allocated, so a header that
+        // lies about the target cannot make the device reserve memory the data could never fill.
+        if (targetSizeL > diff.size.toLong() + extra.size.toLong()) {
+            throw PatchFormatException("target is larger than the diff and extra blocks can produce")
+        }
+
+        val out = ByteArray(targetSize)
+        // Positions are LONG. With Int, `newpos + addLen` and `oldpos + seek` could wrap past
+        // Int.MAX_VALUE to a negative number and slip under a bounds check; the JVM's own array
+        // checks were the only thing stopping it. Every check below is exact, in 64 bits.
+        var newpos = 0L
+        var oldpos = 0L
+        var dpos = 0L
+        var epos = 0L
+
+        var c = 0
+        while (c < control.size) {
+            val addLen = i32(control, c).toLong()
+            val extraLen = i32(control, c + 4).toLong()
+            val seek = i32(control, c + 8).toLong()
+            c += 12
+
+            if (addLen < 0 || extraLen < 0) throw PatchFormatException("negative run length")
+            if (newpos + addLen > targetSize) throw PatchFormatException("add run overruns target")
+            if (dpos + addLen > diff.size) throw PatchFormatException("add run overruns diff block")
+            if (addLen > 0 && (oldpos < 0 || oldpos + addLen > source.size)) {
+                throw PatchFormatException("add run overruns source")
+            }
+
+            val n = newpos.toInt()
+            val o = oldpos.toInt()
+            val d = dpos.toInt()
+            for (i in 0 until addLen.toInt()) {
+                out[n + i] = ((diff[d + i].toInt() + source[o + i].toInt()) and 0xff).toByte()
+            }
+            newpos += addLen
+            oldpos += addLen
+            dpos += addLen
+
+            if (newpos + extraLen > targetSize) throw PatchFormatException("extra run overruns target")
+            if (epos + extraLen > extra.size) throw PatchFormatException("extra run overruns extra block")
+            System.arraycopy(extra, epos.toInt(), out, newpos.toInt(), extraLen.toInt())
+            newpos += extraLen
+            epos += extraLen
+
+            oldpos += seek
+            // A cursor that has left any plausible range can never be used again; stop now rather
+            // than carry an absurd value into the next run.
+            if (oldpos < -(1L shl 32) || oldpos > (1L shl 32)) {
+                throw PatchFormatException("seek moved the source cursor out of range")
+            }
+        }
+
+        if (newpos != targetSize.toLong()) {
+            throw PatchFormatException("patch produced $newpos bytes, declared $targetSize")
+        }
+        return out
+    }
+}

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

@@ -0,0 +1,195 @@
+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(
+        context: android.content.Context,
+        url: String,
+        destination: File,
+        onProgress: ((bytesRead: Long, totalBytes: Long) -> Unit)? = null,
+    ): Boolean = downloadWithReason(context, url, destination, onProgress) == null
+
+    /**
+     * As [download], but says WHY it failed: null on success, otherwise a [DownloadFailure] code.
+     * Never a URL, host or exception message — see [DownloadFailure]. Logs follow the same rule:
+     * they used to print the host and the exception, whose message routinely embeds the presigned
+     * URL, signature included, into logcat.
+     */
+    fun downloadWithReason(
+        context: android.content.Context,
+        url: String,
+        destination: File,
+        onProgress: ((bytesRead: Long, totalBytes: Long) -> Unit)? = null,
+    ): String? {
+        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")
+                }
+
+                // Certificate pinning, when the host app ships pins. Checked after the
+                // handshake but before a single byte of the body is read, and before any
+                // redirect is followed, so an intercepted endpoint cannot serve content or
+                // bounce us somewhere else. No pins configured = no behaviour change.
+                val https = connection as? javax.net.ssl.HttpsURLConnection
+                if (https != null && !TlsPinning.verify(context, https, current.host)) {
+                  return DownloadFailure.PIN_MISMATCH
+                }
+
+                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 DownloadFailure.REDIRECT_LIMIT
+                    }
+                    current = URL(current, location)
+                    continue
+                }
+
+                if (code !in 200..299) {
+                    Log.e(TAG, "Download failed: HTTP $code")
+                    return DownloadFailure.http(code)
+                }
+                break
+            }
+
+            val conn = connection ?: return DownloadFailure.IO
+
+            // 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 DownloadFailure.SIZE_EXCEEDED
+            }
+
+            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 DownloadFailure.SIZE_EXCEEDED
+                        }
+                        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 null
+        } catch (e: Exception) {
+            val reason = DownloadFailure.of(e)
+            // The class and our code only — the exception message can carry the presigned URL.
+            Log.e(TAG, "Download failed: ${e.javaClass.simpleName} ($reason)")
+            destination.delete()
+            return reason
+        } finally {
+            connection?.disconnect()
+        }
+    }
+}

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

@@ -0,0 +1,81 @@
+package com.scalebun.rn.ota
+
+import android.content.Context
+import android.os.Build
+import java.io.File
+
+/**
+ * Best-effort root detection.
+ *
+ * Deliberately modest in what it claims. Root detection is a signal, never a
+ * boundary: anything running with root can defeat any check made from inside the
+ * app, and a determined attacker with a rooted device has already won that
+ * argument. What it IS good for is telling an operator that a fleet's telemetry
+ * — crash rates, adoption, rollback rates — includes devices whose OTA slot is
+ * writable by other processes, and letting a security-sensitive host app decide
+ * to withhold updates on those devices.
+ *
+ * That decision point now exists, in JS rather than here: `ota.onCompromisedDevice`
+ * ('allow' by default; 'withhold' short-circuits the check/download path and
+ * emits an UPDATE_WITHHELD event naming these indicators). See BootGuardConfig
+ * in features/ota/OtaOrchestrator.ts. Nothing in this file enforces anything —
+ * it measures, and the measurement is reported either way.
+ *
+ * The checks are the cheap, well-understood ones: known su binaries, the
+ * test-keys build tag, and the presence of common management packages. No
+ * heuristics that produce false positives on ordinary devices, because a false
+ * positive here means a paying customer stops receiving updates.
+ */
+object DeviceIntegrity {
+
+    private val SU_PATHS = arrayOf(
+        "/system/bin/su",
+        "/system/xbin/su",
+        "/sbin/su",
+        "/system/su",
+        "/vendor/bin/su",
+        "/data/local/xbin/su",
+        "/data/local/bin/su",
+        "/system/sd/xbin/su",
+    )
+
+    private val MANAGEMENT_PACKAGES = arrayOf(
+        "com.topjohnwu.magisk",
+        "eu.chainfire.supersu",
+        "com.noshufou.android.su",
+        "com.koushikdutta.superuser",
+    )
+
+    /**
+     * Reasons this device looks rooted. Empty list = nothing detected, which is
+     * NOT the same as "device is clean" — see the class comment.
+     */
+    fun rootIndicators(context: Context): List<String> {
+        val found = mutableListOf<String>()
+
+        if (SU_PATHS.any { runCatching { File(it).exists() }.getOrDefault(false) }) {
+            found.add("su_binary_present")
+        }
+
+        // Release builds signed with Android's public test keys are development
+        // images, not retail firmware.
+        if (Build.TAGS?.contains("test-keys") == true) {
+            found.add("test_keys_build")
+        }
+
+        val pm = context.packageManager
+        for (pkg in MANAGEMENT_PACKAGES) {
+            val installed = runCatching {
+                @Suppress("DEPRECATION")
+                pm.getPackageInfo(pkg, 0)
+                true
+            }.getOrDefault(false)
+            if (installed) {
+                found.add("root_manager_installed")
+                break
+            }
+        }
+
+        return found
+    }
+}

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

@@ -0,0 +1,55 @@
+package com.scalebun.rn.ota
+
+import java.io.InterruptedIOException
+import java.net.SocketTimeoutException
+import java.net.UnknownHostException
+import javax.net.ssl.SSLException
+
+/**
+ * WHY a bundle download failed, as a code from a FIXED vocabulary.
+ *
+ * The downloader used to return a bare Boolean, so every failure reached the dashboard as
+ * "DOWNLOAD_FAILED" — an expired presigned URL, a DNS failure and a dropped connection were one
+ * row. The 2026-09-20 outage (the backend issued URLs signed with the wrong keys, every download
+ * 403'd in under a second) took a manual correlation of timestamps to diagnose for exactly that
+ * reason.
+ *
+ * NEVER a URL, host or exception message. Presigned URLs carry X-Amz-Signature / X-Amz-Credential,
+ * the object-store host names the account, and `IOException.message` routinely embeds the URL.
+ * Only these constants leave the device, and the JS side re-validates them against the same list
+ * (signedDownload.ts DOWNLOAD_REASON) before anything reaches the wire.
+ *
+ * Pure JVM (no Android imports) so tools/download-reason compiles and runs it with plain kotlinc.
+ */
+object DownloadFailure {
+    const val TIMEOUT = "timeout"
+    const val DNS = "dns"
+    const val TLS = "tls"
+    const val IO = "io"
+    const val PIN_MISMATCH = "pin_mismatch"
+    const val SIZE_EXCEEDED = "size_exceeded"
+    const val REDIRECT_LIMIT = "redirect_limit"
+
+    /** `http_404`. A status outside 100..599 is not HTTP at all — reported as io. */
+    fun http(status: Int): String = if (status in 100..599) "http_$status" else IO
+
+    /**
+     * Classify an exception by TYPE, walking the cause chain (OkHttp/URLConnection wrap). Never
+     * reads the message.
+     */
+    fun of(error: Throwable?): String {
+        var e: Throwable? = error
+        var depth = 0
+        while (e != null && depth < 8) {
+            when (e) {
+                is SocketTimeoutException -> return TIMEOUT
+                is UnknownHostException -> return DNS
+                is SSLException -> return TLS
+            }
+            e = e.cause
+            depth++
+        }
+        // InterruptedIOException without a SocketTimeoutException is a timeout on some JDKs.
+        return if (error is InterruptedIOException) TIMEOUT else IO
+    }
+}