@viettelpost/react-native-ota 0.1.0

package/android/src/main/java/com/viettelpost/otakit/OTAUpdateDownloader.kt

@@ -0,0 +1,649 @@
+package com.viettelpost.otakit
+
+import android.content.Context
+import android.util.Log
+import org.json.JSONException
+import org.json.JSONObject
+import java.io.BufferedOutputStream
+import java.io.File
+import java.io.FileOutputStream
+import java.io.IOException
+import java.net.HttpURLConnection
+import java.net.URL
+import java.util.Locale
+
+object OTAUpdateDownloader {
+    private const val TAG = "OTAKit"
+    private const val PLATFORM_ANDROID = "android"
+    private const val BUNDLE_FILE_NAME = "index.android.bundle"
+    private const val ASSETS_ZIP_FILE_NAME = "assets.zip"
+    private const val PARTIAL_SUFFIX = ".download"
+
+    private const val STATUS_DOWNLOADED = "downloaded"
+    private const val STATUS_DOWNLOAD_FAILED = "download_failed"
+    private const val STATUS_VERIFIED = "verified"
+    private const val STATUS_VERIFYING = "verifying"
+    private const val STATUS_VERIFY_FAILED = "verify_failed"
+    private const val STATUS_PENDING = "pending"
+    private const val REASON_DOWNLOAD_FAILED = "download_failed"
+    private const val REASON_ASSETS_DOWNLOAD_FAILED = "assets_download_failed"
+    private const val REASON_MISSING_SHA256 = "missing_sha256"
+    private const val REASON_MISSING_ASSETS_SHA256 = "missing_assets_sha256"
+    private const val REASON_MISSING_SIGNATURE = "missing_signature"
+    private const val REASON_SIGNATURE_INVALID = "signature_invalid"
+    private const val REASON_SHA256_MISMATCH = "sha256_mismatch"
+    private const val REASON_ASSETS_SHA256_MISMATCH = "assets_sha256_mismatch"
+    private const val REASON_ASSETS_EXTRACT_FAILED = "assets_extract_failed"
+    private const val REASON_UNSAFE_ASSET_ZIP_ENTRY = "unsafe_asset_zip_entry"
+    private const val REASON_TEMP_BUNDLE_NOT_FOUND_FOR_VERIFY = "temp_bundle_not_found_for_verify"
+    private const val REASON_TEMP_ASSETS_NOT_FOUND_FOR_VERIFY = "temp_assets_not_found_for_verify"
+    private const val CONNECT_TIMEOUT_MS = 15_000
+    private const val READ_TIMEOUT_MS = 30_000
+
+    fun downloadBundle(context: Context, updateJson: String): String {
+        val update = OTAUpdatePayload.parse(updateJson, requireBundleUrl = true)
+        validateVersionCanInstall(context, update.version)
+        val tempDir = tempBundleDir(context, update.version)
+        val partialFile = File(tempDir, BUNDLE_FILE_NAME + PARTIAL_SUFFIX)
+        val tempBundleFile = File(tempDir, BUNDLE_FILE_NAME)
+        val partialAssetsFile = File(tempDir, ASSETS_ZIP_FILE_NAME + PARTIAL_SUFFIX)
+        val tempAssetsFile = File(tempDir, ASSETS_ZIP_FILE_NAME)
+
+        OTAUpdateCleanup.cleanupTemp(context, update.version)
+        ensureDirectory(tempDir)
+
+        Log.d(
+            TAG,
+            "OTA download started; version=${update.version}, bundleUrl=${update.bundleUrl}, " +
+                "assetsUrl=${update.assetsUrl ?: "none"}",
+        )
+
+        try {
+            downloadToFile(update.bundleUrl ?: throw IllegalArgumentException("bundleUrl must not be empty"), partialFile)
+            if (partialFile.length() <= 0L) {
+                throw IOException("Downloaded OTA bundle is empty")
+            }
+            if (tempBundleFile.exists() && !tempBundleFile.delete()) {
+                throw IOException("Unable to replace temp OTA bundle")
+            }
+            if (!partialFile.renameTo(tempBundleFile)) {
+                partialFile.copyTo(tempBundleFile, overwrite = true)
+                if (!partialFile.delete()) {
+                    throw IOException("Unable to delete partial OTA bundle after copy")
+                }
+            }
+            if (!tempBundleFile.exists() || tempBundleFile.length() <= 0L) {
+                throw IOException("Downloaded OTA bundle was not finalized")
+            }
+
+            if (!update.assetsUrl.isNullOrEmpty()) {
+                try {
+                    downloadToFile(update.assetsUrl, partialAssetsFile)
+                    if (partialAssetsFile.length() <= 0L) {
+                        throw IOException("Downloaded OTA assets zip is empty")
+                    }
+                    if (tempAssetsFile.exists() && !tempAssetsFile.delete()) {
+                        throw IOException("Unable to replace temp OTA assets zip")
+                    }
+                    if (!partialAssetsFile.renameTo(tempAssetsFile)) {
+                        partialAssetsFile.copyTo(tempAssetsFile, overwrite = true)
+                        if (!partialAssetsFile.delete()) {
+                            throw IOException("Unable to delete partial OTA assets zip after copy")
+                        }
+                    }
+                    if (!tempAssetsFile.exists() || tempAssetsFile.length() <= 0L) {
+                        throw IOException("Downloaded OTA assets zip was not finalized")
+                    }
+                } catch (error: Exception) {
+                    throw OTAAssetsDownloadFailedException(update.version, error)
+                }
+            }
+
+            val metadata = OTAUpdateStorage.readMetadata(context)
+            OTAUpdateStorage.writeMetadata(
+                context,
+                metadata.copy(
+                    status = STATUS_DOWNLOADED,
+                    failedBundleVersion = null,
+                    lastFailureReason = null,
+                ),
+            )
+            Log.d(
+                TAG,
+                "OTA download completed; version=${update.version}, bundlePath=${tempBundleFile.absolutePath}, " +
+                    "assetsPath=${tempAssetsFile.takeIf { it.exists() }?.absolutePath ?: "none"}",
+            )
+            return tempBundleFile.absolutePath
+        } catch (error: Exception) {
+            partialFile.delete()
+            partialAssetsFile.delete()
+            OTAUpdateCleanup.cleanupTemp(context, update.version)
+            val isAssetsDownloadFailure = error is OTAAssetsDownloadFailedException
+            val metadata = OTAUpdateStorage.readMetadata(context)
+            OTAUpdateStorage.writeMetadata(
+                context,
+                metadata.copy(
+                    status = STATUS_DOWNLOAD_FAILED,
+                    failedBundleVersion = update.version,
+                    lastFailureReason = if (isAssetsDownloadFailure) {
+                        REASON_ASSETS_DOWNLOAD_FAILED
+                    } else {
+                        REASON_DOWNLOAD_FAILED
+                    },
+                ),
+            )
+            Log.e(TAG, "OTA download failed; version=${update.version}", error)
+            if (isAssetsDownloadFailure) {
+                throw error
+            }
+            throw OTADownloadFailedException(update.version, error)
+        }
+    }
+
+    fun installDownloadedBundle(context: Context, updateJson: String): Boolean {
+        val update = OTAUpdatePayload.parse(
+            updateJson,
+            requireBundleUrl = false,
+            requireSha256 = true,
+            requireSignature = true,
+            requireSigningFields = true,
+            context = context,
+        )
+        validateVersionCanInstall(context, update.version)
+        verifyDownloadedUpdate(context, update)
+
+        val tempDir = tempBundleDir(context, update.version)
+        val tempBundleFile = File(tempDir, BUNDLE_FILE_NAME)
+        if (!tempBundleFile.exists() || tempBundleFile.length() <= 0L) {
+            OTAUpdateCleanup.cleanupTemp(context, update.version)
+            throw OTATempBundleNotFoundException(tempBundleFile.absolutePath)
+        }
+
+        val finalDir = finalBundleDir(context, update.version)
+        val finalBundleFile = File(finalDir, BUNDLE_FILE_NAME)
+        val tempAssetsFile = File(tempDir, ASSETS_ZIP_FILE_NAME)
+        val hasAssetsZip = tempAssetsFile.exists()
+
+        try {
+            // Install only after a complete temp download exists. Do not replace active metadata here.
+            OTAUpdateCleanup.deleteFinalBundleForFailedInstall(context, update.version)
+            if (finalDir.exists()) {
+                throw IOException("Unable to clear previous OTA bundle directory")
+            }
+            ensureDirectory(finalDir)
+            tempBundleFile.copyTo(finalBundleFile, overwrite = false)
+            if (!finalBundleFile.exists() || finalBundleFile.length() <= 0L) {
+                throw IOException("Installed OTA bundle is missing or empty")
+            }
+            if (hasAssetsZip) {
+                try {
+                    OTAZipUtils.unzip(tempAssetsFile, finalDir)
+                } catch (error: OTAUnsafeAssetsZipEntryException) {
+                    markVerifyFailed(context, update.version, REASON_UNSAFE_ASSET_ZIP_ENTRY)
+                    OTAUpdateCleanup.cleanupTemp(context, update.version)
+                    OTAUpdateCleanup.deleteFinalBundleForFailedInstall(context, update.version)
+                    throw error
+                } catch (error: Exception) {
+                    markVerifyFailed(context, update.version, REASON_ASSETS_EXTRACT_FAILED)
+                    OTAUpdateCleanup.cleanupTemp(context, update.version)
+                    OTAUpdateCleanup.deleteFinalBundleForFailedInstall(context, update.version)
+                    throw OTAAssetsInstallFailedException(update.version, error)
+                }
+            }
+            OTAUpdateCleanup.cleanupTemp(context, update.version)
+
+            val metadata = OTAUpdateStorage.readMetadata(context)
+            OTAUpdateStorage.writeMetadata(
+                context,
+                metadata.copy(
+                    previousBundleVersion = metadata.activeBundleVersion,
+                    pendingBundleVersion = update.version,
+                    status = STATUS_PENDING,
+                    launchCountForPending = 0,
+                    failedBundleVersion = null,
+                    lastFailureReason = null,
+                ),
+            )
+            Log.d(
+                TAG,
+                "OTA install prepared; version=${update.version}, bundlePath=${finalBundleFile.absolutePath}, " +
+                    "assetsInstalled=$hasAssetsZip",
+            )
+            return true
+        } catch (error: Exception) {
+            // A failed install must not leave a partial bundle that can later be selected.
+            OTAUpdateCleanup.cleanupTemp(context, update.version)
+            OTAUpdateCleanup.deleteFinalBundleForFailedInstall(context, update.version)
+            Log.e(TAG, "OTA install failed; version=${update.version}", error)
+            when (error) {
+                is OTAUnsafeAssetsZipEntryException,
+                is OTAAssetsInstallFailedException -> throw error
+                else -> throw OTAInstallFailedException(update.version, error)
+            }
+        }
+    }
+
+    fun downloadAndInstallBundle(context: Context, updateJson: String): Boolean {
+        downloadBundle(context, updateJson)
+        return installDownloadedBundle(context, updateJson)
+    }
+
+    fun getDownloadInfo(context: Context, version: String): JSONObject {
+        val normalizedVersion = normalizeVersion(version)
+        val tempBundleFile = File(tempBundleDir(context, normalizedVersion), BUNDLE_FILE_NAME)
+        val finalBundleFile = File(finalBundleDir(context, normalizedVersion), BUNDLE_FILE_NAME)
+        val tempAssetsFile = File(tempBundleDir(context, normalizedVersion), ASSETS_ZIP_FILE_NAME)
+        val finalDir = finalBundleDir(context, normalizedVersion)
+        val finalAssetFiles = finalDir.walkTopDown()
+            .filter { it.isFile && it.name != BUNDLE_FILE_NAME }
+            .toList()
+
+        return JSONObject().apply {
+            put("version", normalizedVersion)
+            put("tempBundlePath", tempBundleFile.absolutePath)
+            put("finalBundlePath", finalBundleFile.absolutePath)
+            put("tempAssetsZipPath", tempAssetsFile.absolutePath)
+            put("finalAssetsDirectoryPath", finalDir.absolutePath)
+            put("tempExists", tempBundleFile.exists())
+            put("finalExists", finalBundleFile.exists())
+            put("tempAssetsZipExists", tempAssetsFile.exists())
+            put("finalAssetFileCount", finalAssetFiles.size)
+            put("tempSize", fileSize(tempBundleFile))
+            put("finalSize", fileSize(finalBundleFile))
+            put("tempAssetsZipSize", fileSize(tempAssetsFile))
+            put("finalAssetsSize", finalAssetFiles.sumOf { it.length() })
+            putNullable("tempSha256", fileSha256(tempBundleFile))
+            putNullable("finalSha256", fileSha256(finalBundleFile))
+            putNullable("tempAssetsSha256", fileSha256(tempAssetsFile))
+            put("signatureRequired", true)
+        }
+    }
+
+    private fun verifyDownloadedUpdate(context: Context, update: OTAUpdatePayload): Boolean {
+        try {
+            verifyDownloadedBundle(context, update)
+            verifyUpdateSignature(context, update)
+            return true
+        } catch (error: OTAMissingSignatureException) {
+            OTAUpdateCleanup.cleanupTemp(context, update.version)
+            throw error
+        } catch (error: OTASignatureInvalidException) {
+            OTAUpdateCleanup.cleanupTemp(context, update.version)
+            throw error
+        }
+    }
+
+    private fun verifyDownloadedBundle(context: Context, update: OTAUpdatePayload): Boolean {
+        val tempDir = tempBundleDir(context, update.version)
+        val tempBundleFile = File(tempDir, BUNDLE_FILE_NAME)
+        val tempAssetsFile = File(tempDir, ASSETS_ZIP_FILE_NAME)
+        val expectedSha256 = update.sha256
+        val expectedAssetsSha256 = update.assetsSha256
+
+        if (expectedSha256.isNullOrEmpty()) {
+            markVerifyFailed(context, update.version, REASON_MISSING_SHA256)
+            OTAUpdateCleanup.cleanupTemp(context, update.version)
+            Log.w(TAG, "OTA verify failed; version=${update.version}, reason=$REASON_MISSING_SHA256")
+            throw OTAMissingSha256Exception(update.version)
+        }
+
+        if (!tempBundleFile.exists() || tempBundleFile.length() <= 0L) {
+            markVerifyFailed(context, update.version, REASON_TEMP_BUNDLE_NOT_FOUND_FOR_VERIFY)
+            OTAUpdateCleanup.cleanupTemp(context, update.version)
+            Log.w(TAG, "OTA verify failed; version=${update.version}, reason=$REASON_TEMP_BUNDLE_NOT_FOUND_FOR_VERIFY")
+            throw OTATempBundleNotFoundException(tempBundleFile.absolutePath)
+        }
+
+        if (!update.assetsUrl.isNullOrEmpty()) {
+            if (expectedAssetsSha256.isNullOrEmpty()) {
+                markVerifyFailed(context, update.version, REASON_MISSING_ASSETS_SHA256)
+                OTAUpdateCleanup.cleanupTemp(context, update.version)
+                Log.w(TAG, "OTA verify failed; version=${update.version}, reason=$REASON_MISSING_ASSETS_SHA256")
+                throw OTAMissingAssetsSha256Exception(update.version)
+            }
+            if (!tempAssetsFile.exists() || tempAssetsFile.length() <= 0L) {
+                markVerifyFailed(context, update.version, REASON_TEMP_ASSETS_NOT_FOUND_FOR_VERIFY)
+                OTAUpdateCleanup.cleanupTemp(context, update.version)
+                Log.w(TAG, "OTA verify failed; version=${update.version}, reason=$REASON_TEMP_ASSETS_NOT_FOUND_FOR_VERIFY")
+                throw OTAAssetsZipNotFoundException(tempAssetsFile.absolutePath)
+            }
+        }
+
+        val metadata = OTAUpdateStorage.readMetadata(context)
+        OTAUpdateStorage.writeMetadata(
+            context,
+            metadata.copy(
+                status = STATUS_VERIFYING,
+                failedBundleVersion = null,
+                lastFailureReason = null,
+            ),
+        )
+        Log.d(TAG, "OTA verify started; version=${update.version}, path=${tempBundleFile.absolutePath}")
+
+        val actualSha256 = OTAHashUtils.sha256(tempBundleFile)
+        if (!actualSha256.equals(expectedSha256, ignoreCase = true)) {
+            OTAUpdateCleanup.cleanupTemp(context, update.version)
+            markVerifyFailed(context, update.version, REASON_SHA256_MISMATCH)
+            Log.e(
+                TAG,
+                "OTA verify failed; version=${update.version}, reason=$REASON_SHA256_MISMATCH, expected=$expectedSha256, actual=$actualSha256",
+            )
+            throw OTASha256MismatchException(update.version)
+        }
+
+        if (tempAssetsFile.exists()) {
+            if (expectedAssetsSha256.isNullOrEmpty()) {
+                OTAUpdateCleanup.cleanupTemp(context, update.version)
+                markVerifyFailed(context, update.version, REASON_MISSING_ASSETS_SHA256)
+                throw OTAMissingAssetsSha256Exception(update.version)
+            }
+            val actualAssetsSha256 = OTAHashUtils.sha256(tempAssetsFile)
+            if (!actualAssetsSha256.equals(expectedAssetsSha256, ignoreCase = true)) {
+                OTAUpdateCleanup.cleanupTemp(context, update.version)
+                markVerifyFailed(context, update.version, REASON_ASSETS_SHA256_MISMATCH)
+                Log.e(
+                    TAG,
+                    "OTA assets verify failed; version=${update.version}, reason=$REASON_ASSETS_SHA256_MISMATCH, " +
+                        "expected=$expectedAssetsSha256, actual=$actualAssetsSha256",
+                )
+                throw OTAAssetsSha256MismatchException(update.version)
+            }
+            try {
+                OTAZipUtils.validate(tempAssetsFile)
+            } catch (error: OTAUnsafeAssetsZipEntryException) {
+                OTAUpdateCleanup.cleanupTemp(context, update.version)
+                markVerifyFailed(context, update.version, REASON_UNSAFE_ASSET_ZIP_ENTRY)
+                Log.w(TAG, "OTA assets zip rejected; version=${update.version}", error)
+                throw error
+            } catch (error: Exception) {
+                OTAUpdateCleanup.cleanupTemp(context, update.version)
+                markVerifyFailed(context, update.version, REASON_ASSETS_EXTRACT_FAILED)
+                Log.w(TAG, "OTA assets zip validation failed; version=${update.version}", error)
+                throw OTAAssetsInstallFailedException(update.version, error)
+            }
+            Log.d(TAG, "OTA assets verify succeeded; version=${update.version}, sha256=$actualAssetsSha256")
+        }
+
+        val verifiedMetadata = OTAUpdateStorage.readMetadata(context)
+        OTAUpdateStorage.writeMetadata(
+            context,
+            verifiedMetadata.copy(
+                status = STATUS_VERIFIED,
+                failedBundleVersion = null,
+                lastFailureReason = null,
+            ),
+        )
+        Log.d(TAG, "OTA verify succeeded; version=${update.version}, sha256=$actualSha256")
+        return true
+    }
+
+    private fun verifyUpdateSignature(context: Context, update: OTAUpdatePayload): Boolean {
+        val signature = update.signature
+        if (signature.isNullOrEmpty()) {
+            markVerifyFailed(context, update.version, REASON_MISSING_SIGNATURE)
+            Log.w(TAG, "OTA signature verify failed; version=${update.version}, reason=$REASON_MISSING_SIGNATURE")
+            throw OTAMissingSignatureException(update.version)
+        }
+
+        val canonicalPayload = OTAUpdateSignatureVerifier.canonicalPayload(
+            version = update.version,
+            platform = update.platform,
+            fileName = update.fileName,
+            sha256 = update.sha256 ?: "",
+            assetsSha256 = update.assetsSha256,
+        )
+        val isValid = try {
+            OTAUpdateSignatureVerifier.verifySignature(context, canonicalPayload, signature)
+        } catch (error: Exception) {
+            false
+        }
+        if (!isValid) {
+            markVerifyFailed(context, update.version, REASON_SIGNATURE_INVALID)
+            Log.w(
+                TAG,
+                "OTA signature verify failed; version=${update.version}, reason=$REASON_SIGNATURE_INVALID, " +
+                    "canonicalPayload=\n$canonicalPayload",
+            )
+            throw OTASignatureInvalidException(update.version)
+        }
+
+        Log.d(TAG, "OTA signature verify succeeded; version=${update.version}")
+        return true
+    }
+
+    private fun validateVersionCanInstall(context: Context, version: String) {
+        val metadata = OTAUpdateStorage.readMetadata(context)
+        if (metadata.activeBundleVersion == version || metadata.pendingBundleVersion == version) {
+            Log.w(
+                TAG,
+                "OTA version rejected; version=$version, active=${metadata.activeBundleVersion}, " +
+                    "pending=${metadata.pendingBundleVersion ?: "none"}",
+            )
+            throw OTAVersionAlreadyExistsException(version)
+        }
+        if (metadata.failedBundleVersion == version) {
+            Log.w(TAG, "OTA retrying previously failed version=$version")
+        }
+    }
+
+    private fun downloadToFile(urlString: String, destination: File) {
+        val connection = URL(urlString).openConnection() as HttpURLConnection
+        connection.connectTimeout = CONNECT_TIMEOUT_MS
+        connection.readTimeout = READ_TIMEOUT_MS
+        connection.requestMethod = "GET"
+        connection.useCaches = false
+
+        try {
+            val statusCode = connection.responseCode
+            if (statusCode !in 200..299) {
+                throw IOException("HTTP $statusCode while downloading OTA bundle")
+            }
+
+            connection.inputStream.use { input ->
+                BufferedOutputStream(FileOutputStream(destination)).use { output ->
+                    val buffer = ByteArray(DEFAULT_BUFFER_SIZE)
+                    while (true) {
+                        val bytesRead = input.read(buffer)
+                        if (bytesRead == -1) {
+                            break
+                        }
+                        output.write(buffer, 0, bytesRead)
+                    }
+                    output.flush()
+                }
+            }
+        } finally {
+            connection.disconnect()
+        }
+    }
+
+    private fun tempBundleDir(context: Context, version: String): File =
+        File(File(OTAUpdateBundleResolver.otaDirectory(context), "tmp"), version)
+
+    private fun finalBundleDir(context: Context, version: String): File =
+        File(File(OTAUpdateBundleResolver.otaDirectory(context), "bundles"), version)
+
+    private fun ensureDirectory(directory: File) {
+        if (!directory.exists() && !directory.mkdirs()) {
+            throw IOException("Unable to create directory ${directory.absolutePath}")
+        }
+    }
+
+    private fun fileSize(file: File): Long =
+        if (file.exists()) {
+            file.length()
+        } else {
+            0L
+        }
+
+    private fun fileSha256(file: File): String? =
+        if (file.exists() && file.length() > 0L) {
+            OTAHashUtils.sha256(file)
+        } else {
+            null
+        }
+
+    private fun markVerifyFailed(context: Context, version: String, reason: String) {
+        val metadata = OTAUpdateStorage.readMetadata(context)
+        OTAUpdateStorage.writeMetadata(
+            context,
+            metadata.copy(
+                status = STATUS_VERIFY_FAILED,
+                pendingBundleVersion = null,
+                failedBundleVersion = version,
+                lastFailureReason = reason,
+            ),
+        )
+    }
+
+    private fun normalizeVersion(version: String): String {
+        val normalizedVersion = version.trim()
+        if (normalizedVersion.isEmpty()) {
+            throw IllegalArgumentException("version must not be empty")
+        }
+        if (normalizedVersion.contains("/") || normalizedVersion.contains("\\")) {
+            throw IllegalArgumentException("version must not contain path separators")
+        }
+        return normalizedVersion
+    }
+
+    private data class OTAUpdatePayload(
+        val version: String,
+        val bundleUrl: String?,
+        val platform: String,
+        val fileName: String,
+        val sha256: String?,
+        val signature: String?,
+        val assetsUrl: String?,
+        val assetsSha256: String?,
+    ) {
+        companion object {
+            fun parse(
+                updateJson: String,
+                requireBundleUrl: Boolean,
+                requireSha256: Boolean = false,
+                requireSignature: Boolean = false,
+                requireSigningFields: Boolean = false,
+                context: Context? = null,
+            ): OTAUpdatePayload {
+                val data = try {
+                    JSONObject(updateJson)
+                } catch (error: JSONException) {
+                    throw IllegalArgumentException("updateJson must be valid JSON", error)
+                }
+                val version = normalizeVersion(data.optString("version", ""))
+                val bundleUrl = data.optNullableString("bundleUrl")?.trim()
+                if (requireBundleUrl && bundleUrl.isNullOrEmpty()) {
+                    throw IllegalArgumentException("bundleUrl must not be empty")
+                }
+
+                val sha256 = data.optNullableString("sha256")?.trim()?.lowercase(Locale.US)
+                if (requireSha256 && sha256.isNullOrEmpty()) {
+                    context?.let { markVerifyFailed(it, version, REASON_MISSING_SHA256) }
+                    context?.let { OTAUpdateCleanup.cleanupTemp(it, version) }
+                    throw OTAMissingSha256Exception(version)
+                }
+
+                val assetsUrl = data.optNullableString("assetsUrl")?.trim()
+                    ?.takeUnless { it.isEmpty() }
+                val assetsSha256 = data.optNullableString("assetsSha256")?.trim()?.lowercase(Locale.US)
+                if (!assetsUrl.isNullOrEmpty() && requireSha256 && assetsSha256.isNullOrEmpty()) {
+                    context?.let { markVerifyFailed(it, version, REASON_MISSING_ASSETS_SHA256) }
+                    context?.let { OTAUpdateCleanup.cleanupTemp(it, version) }
+                    throw OTAMissingAssetsSha256Exception(version)
+                }
+
+                val rawPlatform = data.optNullableString("platform")?.trim()?.lowercase(Locale.US)
+                if (requireSigningFields && rawPlatform.isNullOrEmpty()) {
+                    throw IllegalArgumentException("platform must not be empty")
+                }
+                if (!rawPlatform.isNullOrEmpty() && rawPlatform != PLATFORM_ANDROID) {
+                    throw IllegalArgumentException("platform must be android")
+                }
+                val platform = rawPlatform ?: PLATFORM_ANDROID
+
+                val rawFileName = data.optNullableString("fileName")?.trim()
+                if (requireSigningFields && rawFileName.isNullOrEmpty()) {
+                    throw IllegalArgumentException("fileName must not be empty")
+                }
+                if (!rawFileName.isNullOrEmpty() && rawFileName != BUNDLE_FILE_NAME) {
+                    throw IllegalArgumentException("fileName must be $BUNDLE_FILE_NAME")
+                }
+                val fileName = rawFileName ?: BUNDLE_FILE_NAME
+
+                val signature = data.optNullableString("signature")?.trim()
+                if (requireSignature && signature.isNullOrEmpty()) {
+                    context?.let { markVerifyFailed(it, version, REASON_MISSING_SIGNATURE) }
+                    context?.let { OTAUpdateCleanup.cleanupTemp(it, version) }
+                    throw OTAMissingSignatureException(version)
+                }
+
+                return OTAUpdatePayload(
+                    version = version,
+                    bundleUrl = bundleUrl,
+                    platform = platform,
+                    fileName = fileName,
+                    sha256 = sha256,
+                    signature = signature,
+                    assetsUrl = assetsUrl,
+                    assetsSha256 = assetsSha256,
+                )
+            }
+        }
+    }
+}
+
+class OTADownloadFailedException(version: String, cause: Throwable) :
+    IOException("Failed to download OTA bundle for version $version", cause)
+
+class OTAAssetsDownloadFailedException(version: String, cause: Throwable) :
+    IOException("Failed to download OTA assets for version $version", cause)
+
+class OTATempBundleNotFoundException(path: String) :
+    IllegalStateException("Downloaded OTA temp bundle was not found at $path")
+
+class OTAMissingSha256Exception(version: String) :
+    IllegalArgumentException("OTA update $version is missing required sha256")
+
+class OTASha256MismatchException(version: String) :
+    IllegalStateException("OTA SHA-256 verification failed for version $version")
+
+class OTAMissingAssetsSha256Exception(version: String) :
+    IllegalArgumentException("OTA update $version is missing required assetsSha256")
+
+class OTAMissingSignatureException(version: String) :
+    IllegalArgumentException("OTA update $version is missing required signature")
+
+class OTASignatureInvalidException(version: String) :
+    IllegalStateException("OTA signature verification failed for version $version")
+
+class OTAAssetsSha256MismatchException(version: String) :
+    IllegalStateException("OTA assets ZIP SHA-256 verification failed for version $version")
+
+class OTAAssetsZipNotFoundException(path: String) :
+    IllegalStateException("Downloaded OTA assets zip was not found at $path")
+
+class OTAUnsafeAssetsZipEntryException(entryName: String) :
+    IllegalStateException("OTA assets zip contains unsafe entry $entryName")
+
+class OTAAssetsInstallFailedException(version: String, cause: Throwable) :
+    IOException("Failed to install OTA assets for version $version", cause)
+
+class OTAVersionAlreadyExistsException(version: String) :
+    IllegalStateException(
+        "OTA version already exists as active or pending. Use a new version and recalculate hashes for every rebuild. version=$version",
+    )
+
+class OTAInstallFailedException(version: String, cause: Throwable) :
+    IOException("Failed to install downloaded OTA bundle for version $version", cause)
+
+private fun JSONObject.optNullableString(name: String): String? {
+    if (!has(name) || isNull(name)) {
+        return null
+    }
+    return optString(name)
+}
+
+private fun JSONObject.putNullable(name: String, value: String?) {
+    put(name, value ?: JSONObject.NULL)
+}