@viettelpost/react-native-ota 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @viettelpost/react-native-ota
+
+Standalone React Native OTA runtime and deploy CLI.
+
+This package contains:
+
+- `ota deploy`: build, zip assets, hash, sign, and upload OTA release files.
+- JS API: `OTA.configure()`, `OTA.sync()`, status helpers, and dev utilities.
+- Native runtime: Android Kotlin and iOS Swift/ObjC++ bundle resolver, installer, verification, rollback, and cleanup.
+
+This package does not integrate itself into a host app. The host app must wire the native bundle resolver at startup before OTA bundles can run.
+
+## CLI
+
+```sh
+ota deploy --platform android --dry-run
+ota deploy --platform ios --dry-run
+ota sign --platform ios --bundle ./build/main.jsbundle --version 2026.06.26-001
+```
+
+Non-dry-run deploys require the backend upload endpoint documented in `docs/BACKEND_CONTRACT.md`.
+
+## JS API
+
+```ts
+import { OTA } from '@viettelpost/react-native-ota';
+
+OTA.configure({
+  baseURL: 'https://ota.example.com',
+  headers: () => ({ Authorization: `Bearer ${token}` }),
+});
+
+const result = await OTA.sync();
+```
+
+## Security
+
+The client verifies SHA-256 for the bundle and optional `assets.zip`, then verifies an RSA-SHA256 signature over the canonical metadata payload. The private key must never be committed.

package/android/build.gradle

@@ -0,0 +1,48 @@
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+plugins {
+    id "com.android.library"
+    id "org.jetbrains.kotlin.android"
+}
+
+def getExtOrDefault(name) {
+    if (rootProject.ext.has(name)) {
+        return rootProject.ext.get(name)
+    }
+    if (project.hasProperty("ReactNativeOta_" + name)) {
+        return project.properties["ReactNativeOta_" + name]
+    }
+    if (name == "compileSdkVersion") return 35
+    if (name == "targetSdkVersion") return 35
+    if (name == "minSdkVersion") return 23
+    throw new GradleException("Missing ReactNativeOta Android property: " + name)
+}
+
+android {
+    namespace "com.viettelpost.otakit"
+    compileSdkVersion getExtOrDefault("compileSdkVersion").toInteger()
+
+    defaultConfig {
+        minSdkVersion getExtOrDefault("minSdkVersion").toInteger()
+        targetSdkVersion getExtOrDefault("targetSdkVersion").toInteger()
+    }
+
+    sourceSets {
+        main.java.srcDirs += ["src/main/java"]
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation "com.facebook.react:react-android"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib"
+}

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

@@ -0,0 +1,21 @@
+package com.viettelpost.otakit
+
+import java.io.File
+import java.security.MessageDigest
+
+object OTAHashUtils {
+    fun sha256(file: File): String {
+        val digest = MessageDigest.getInstance("SHA-256")
+        file.inputStream().use { input ->
+            val buffer = ByteArray(DEFAULT_BUFFER_SIZE)
+            while (true) {
+                val bytesRead = input.read(buffer)
+                if (bytesRead <= 0) {
+                    break
+                }
+                digest.update(buffer, 0, bytesRead)
+            }
+        }
+        return digest.digest().joinToString(separator = "") { byte -> "%02x".format(byte) }
+    }
+}

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

@@ -0,0 +1,51 @@
+package com.viettelpost.otakit
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+
+class OTATestReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        val action = intent.action ?: return
+
+        try {
+            when (action) {
+                ACTION_PREPARE -> {
+                    val version = intent.getStringExtra(EXTRA_VERSION)
+                        ?: intent.getStringExtra(EXTRA_BUNDLE_VERSION)
+                        ?: ""
+                    val didPrepare = OTAUpdateBundleResolver.prepareManualInstall(context, version)
+                    Log.d(TAG, "OTA test prepare result=$didPrepare, version=$version")
+                }
+                ACTION_CONFIRM -> {
+                    val didConfirm = OTAUpdateBundleResolver.markSuccess(context)
+                    Log.d(TAG, "OTA test confirm result=$didConfirm")
+                }
+                ACTION_INFO -> {
+                    val metadata = OTAUpdateStorage.readMetadata(context)
+                    val bundleInfo = OTAUpdateBundleResolver.getCurrentBundleInfo(context)
+                    Log.d(TAG, "OTA test metadata=${metadata.toJson()}")
+                    Log.d(TAG, "OTA test bundleInfo=$bundleInfo")
+                }
+                ACTION_RESET -> {
+                    val metadata = OTAUpdateStorage.resetMetadata(context)
+                    Log.d(TAG, "OTA test reset metadata=${metadata.toJson()}")
+                }
+            }
+        } catch (error: Exception) {
+            Log.e(TAG, "OTA test receiver failed; action=$action", error)
+        }
+    }
+
+    companion object {
+        private const val TAG = "OTAKit"
+        private const val EXTRA_VERSION = "version"
+        private const val EXTRA_BUNDLE_VERSION = "bundleVersion"
+
+        const val ACTION_PREPARE = "com.viettelpost.otakit.OTA_TEST_PREPARE"
+        const val ACTION_CONFIRM = "com.viettelpost.otakit.OTA_TEST_CONFIRM"
+        const val ACTION_INFO = "com.viettelpost.otakit.OTA_TEST_INFO"
+        const val ACTION_RESET = "com.viettelpost.otakit.OTA_TEST_RESET"
+    }
+}

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

@@ -0,0 +1,405 @@
+package com.viettelpost.otakit
+
+import android.content.Context
+import android.util.Log
+import org.json.JSONObject
+import java.io.File
+import java.io.IOException
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+
+object OTAUpdateBundleResolver {
+    private const val TAG = "OTAKit"
+    private const val EMBEDDED_VERSION = "embedded"
+    private const val STATUS_ACTIVE = "active"
+    private const val STATUS_PENDING = "pending"
+    private const val STATUS_FAILED = "failed"
+    private const val STATUS_ROLLED_BACK = "rolled_back"
+
+    private const val REASON_MISSING_PENDING_BUNDLE = "missing_pending_bundle"
+    private const val REASON_PENDING_BUNDLE_FILE_MISSING = "pending_bundle_file_missing"
+    private const val REASON_MARK_SUCCESS_NOT_CALLED = "mark_success_not_called"
+    private const val REASON_ACTIVE_BUNDLE_FILE_MISSING = "active_bundle_file_missing"
+
+    fun otaDirectory(context: Context): File = File(context.filesDir, "ota")
+
+    @Throws(IOException::class)
+    fun ensureOTADirectory(context: Context): File {
+        val directory = otaDirectory(context)
+        if (!directory.exists() && !directory.mkdirs()) {
+            throw IOException("Unable to create OTA directory")
+        }
+        return directory
+    }
+
+    fun resolveBundlePath(context: Context): String? =
+        try {
+            Log.d(
+                TAG,
+                "resolveBundlePath entered; metadataFile=${OTAUpdateStorage.getMetadataPath(context).absolutePath}",
+            )
+            resolveBundlePathOrThrow(context)
+        } catch (error: Exception) {
+            Log.e(TAG, "resolveBundlePath failed; using embedded bundle", error)
+            logBundleSelection(
+                source = "fallback",
+                version = EMBEDDED_VERSION,
+                status = STATUS_FAILED,
+                path = null,
+                reason = error.message ?: "resolve_exception",
+            )
+            null
+        }
+
+    // Manual test hook: the bundle file must already be copied into private OTA storage.
+    fun prepareManualInstall(context: Context, bundleVersion: String): Boolean {
+        val normalizedVersion = bundleVersion.trim()
+        if (normalizedVersion.isEmpty()) {
+            throw IllegalArgumentException("bundleVersion must not be empty")
+        }
+
+        val bundleFile = bundleFile(context, normalizedVersion)
+        if (!bundleFile.exists()) {
+            throw OTABundleFileNotFoundException(bundleFile.absolutePath)
+        }
+
+        val metadata = OTAUpdateStorage.readMetadata(context)
+        OTAUpdateStorage.writeMetadata(
+            context,
+            metadata.copy(
+                previousBundleVersion = metadata.activeBundleVersion,
+                pendingBundleVersion = normalizedVersion,
+                status = STATUS_PENDING,
+                launchCountForPending = 0,
+                lastFailureReason = null,
+            ),
+        )
+        return true
+    }
+
+    // Manual test hook: promote only the pending bundle that actually launched.
+    fun markSuccess(context: Context): Boolean {
+        val metadata = OTAUpdateStorage.readMetadata(context)
+        val pendingVersion = metadata.pendingBundleVersion
+
+        if (metadata.status != STATUS_PENDING ||
+            pendingVersion.isNullOrBlank() ||
+            metadata.runningBundleVersion != pendingVersion
+        ) {
+            Log.w(
+                TAG,
+                "OTA mark success rejected; status=${metadata.status}, " +
+                    "running=${metadata.runningBundleVersion}, pending=${pendingVersion ?: "none"}",
+            )
+            throw OTAMarkSuccessRejectedException(
+                metadata.runningBundleVersion,
+                pendingVersion,
+            )
+        }
+
+        OTAUpdateStorage.writeMetadata(
+            context,
+            metadata.copy(
+                previousBundleVersion = metadata.activeBundleVersion,
+                activeBundleVersion = pendingVersion,
+                pendingBundleVersion = null,
+                status = STATUS_ACTIVE,
+                launchCountForPending = 0,
+                lastSuccessfulLaunchAt = currentIsoTimestamp(),
+                lastFailureReason = null,
+            ),
+        )
+        // Metadata is saved before cleanup so a cleanup warning cannot undo a confirmed update.
+        OTAUpdateCleanup.cleanupAfterSuccessfulActivation(context, pendingVersion)
+        OTAUpdateCleanup.cleanupAllTemp(context)
+        Log.d(
+            TAG,
+            "OTA mark success accepted; active=$pendingVersion, previous=${metadata.activeBundleVersion}",
+        )
+        return true
+    }
+
+    fun getCurrentBundleInfo(context: Context): JSONObject {
+        val metadata = OTAUpdateStorage.readMetadata(context)
+        val runningVersion = metadata.runningBundleVersion
+        val isEmbedded = isEmbeddedVersion(runningVersion)
+        val bundlePath = if (isEmbedded) {
+            null
+        } else {
+            bundleFile(context, runningVersion).takeIf { it.exists() }?.absolutePath
+        }
+        val assetsDirectory = if (isEmbedded) {
+            null
+        } else {
+            bundleDirectory(context, runningVersion)
+        }
+
+        return JSONObject().apply {
+            put("runningBundleVersion", runningVersion)
+            put("activeBundleVersion", metadata.activeBundleVersion)
+            putNullable("pendingBundleVersion", metadata.pendingBundleVersion)
+            put("status", metadata.status)
+            putNullable("bundlePath", bundlePath)
+            putNullable("assetsDirectoryPath", assetsDirectory?.absolutePath)
+            put("assetsDirectoryExists", assetsDirectory?.exists() == true)
+            put("isEmbedded", isEmbedded)
+        }
+    }
+
+    private fun resolveBundlePathOrThrow(context: Context): String? {
+        val metadata = OTAUpdateStorage.readMetadata(context)
+        Log.d(TAG, "OTA metadata loaded: ${metadata.toLogString()}")
+        if (!metadata.lastFailureReason.isNullOrBlank()) {
+            Log.w(
+                TAG,
+                "OTA metadata contains previous failure reason=${metadata.lastFailureReason}, " +
+                    "failed=${metadata.failedBundleVersion ?: "none"}",
+            )
+        }
+
+        if (metadata.status == STATUS_PENDING) {
+            return resolvePendingBundle(context, metadata)
+        }
+
+        return resolveActiveBundle(context, metadata)
+    }
+
+    private fun resolvePendingBundle(context: Context, metadata: OTAUpdateMetadata): String? {
+        val pendingVersion = metadata.pendingBundleVersion
+        if (pendingVersion.isNullOrBlank()) {
+            Log.w(
+                TAG,
+                "Pending OTA status has no pending version; reason=$REASON_MISSING_PENDING_BUNDLE; using embedded bundle",
+            )
+            OTAUpdateStorage.writeMetadata(
+                context,
+                metadata.copy(
+                    status = STATUS_FAILED,
+                    pendingBundleVersion = null,
+                    runningBundleVersion = EMBEDDED_VERSION,
+                    launchCountForPending = 0,
+                    lastFailureReason = REASON_MISSING_PENDING_BUNDLE,
+                ),
+            )
+            logBundleSelection(
+                source = "fallback",
+                version = EMBEDDED_VERSION,
+                status = STATUS_FAILED,
+                path = null,
+                reason = REASON_MISSING_PENDING_BUNDLE,
+            )
+            return null
+        }
+
+        val pendingFile = bundleFile(context, pendingVersion)
+        if (!pendingFile.exists()) {
+            val runningVersion = validActiveBundleVersion(context, metadata) ?: EMBEDDED_VERSION
+            Log.w(
+                TAG,
+                "Pending OTA bundle missing; pending=$pendingVersion, path=${pendingFile.absolutePath}, " +
+                    "reason=$REASON_PENDING_BUNDLE_FILE_MISSING, fallback=$runningVersion",
+            )
+            OTAUpdateStorage.writeMetadata(
+                context,
+                metadata.copy(
+                    status = STATUS_FAILED,
+                    pendingBundleVersion = null,
+                    failedBundleVersion = pendingVersion,
+                    runningBundleVersion = runningVersion,
+                    launchCountForPending = 0,
+                    lastFailureReason = REASON_PENDING_BUNDLE_FILE_MISSING,
+                ),
+            )
+            // The pending version cannot run, so its package and temp files are safe to remove.
+            OTAUpdateCleanup.cleanupFailedPendingBundle(context, pendingVersion)
+            val fallbackPath = bundlePathForVersion(context, runningVersion)
+            logBundleSelection(
+                source = if (isEmbeddedVersion(runningVersion)) "fallback" else "active_ota",
+                version = runningVersion,
+                status = STATUS_FAILED,
+                path = fallbackPath,
+                reason = REASON_PENDING_BUNDLE_FILE_MISSING,
+            )
+            return fallbackPath
+        }
+
+        if (metadata.launchCountForPending > 0) {
+            val runningVersion = validActiveBundleVersion(context, metadata) ?: EMBEDDED_VERSION
+            Log.w(
+                TAG,
+                "Pending OTA bundle did not confirm success; pending=$pendingVersion, " +
+                    "launchCount=${metadata.launchCountForPending}, reason=$REASON_MARK_SUCCESS_NOT_CALLED, " +
+                    "rollback=$runningVersion",
+            )
+            OTAUpdateStorage.writeMetadata(
+                context,
+                metadata.copy(
+                    status = STATUS_ROLLED_BACK,
+                    pendingBundleVersion = null,
+                    failedBundleVersion = pendingVersion,
+                    runningBundleVersion = runningVersion,
+                    launchCountForPending = 0,
+                    lastFailureReason = REASON_MARK_SUCCESS_NOT_CALLED,
+                ),
+            )
+            // Save rollback metadata first; cleanup failure must not prevent fallback startup.
+            OTAUpdateCleanup.cleanupFailedPendingBundle(context, pendingVersion)
+            val rollbackPath = bundlePathForVersion(context, runningVersion)
+            logBundleSelection(
+                source = if (isEmbeddedVersion(runningVersion)) "fallback" else "active_ota",
+                version = runningVersion,
+                status = STATUS_ROLLED_BACK,
+                path = rollbackPath,
+                reason = REASON_MARK_SUCCESS_NOT_CALLED,
+            )
+            return rollbackPath
+        }
+
+        OTAUpdateStorage.writeMetadata(
+            context,
+            metadata.copy(
+                runningBundleVersion = pendingVersion,
+                launchCountForPending = metadata.launchCountForPending + 1,
+            ),
+        )
+        Log.d(
+            TAG,
+            "Selected pending OTA bundle; version=$pendingVersion, path=${pendingFile.absolutePath}, " +
+                "launchCount=${metadata.launchCountForPending + 1}",
+        )
+        logBundleSelection(
+            source = "pending_ota",
+            version = pendingVersion,
+            status = STATUS_PENDING,
+            path = pendingFile.absolutePath,
+        )
+        return pendingFile.absolutePath
+    }
+
+    private fun resolveActiveBundle(context: Context, metadata: OTAUpdateMetadata): String? {
+        val activeVersion = metadata.activeBundleVersion
+        if (!isEmbeddedVersion(activeVersion)) {
+            val activeFile = bundleFile(context, activeVersion)
+            if (activeFile.exists()) {
+                OTAUpdateStorage.writeMetadata(
+                    context,
+                    metadata.copy(runningBundleVersion = activeVersion),
+                )
+                Log.d(
+                    TAG,
+                    "Selected active OTA bundle; version=$activeVersion, path=${activeFile.absolutePath}",
+                )
+                logBundleSelection(
+                    source = "active_ota",
+                    version = activeVersion,
+                    status = metadata.status,
+                    path = activeFile.absolutePath,
+                )
+                return activeFile.absolutePath
+            }
+
+            Log.w(
+                TAG,
+                "Active OTA bundle missing; active=$activeVersion, path=${activeFile.absolutePath}, " +
+                    "reason=$REASON_ACTIVE_BUNDLE_FILE_MISSING; using embedded bundle",
+            )
+            OTAUpdateStorage.writeMetadata(
+                context,
+                metadata.copy(
+                    status = STATUS_FAILED,
+                    failedBundleVersion = activeVersion,
+                    runningBundleVersion = EMBEDDED_VERSION,
+                    lastFailureReason = REASON_ACTIVE_BUNDLE_FILE_MISSING,
+                ),
+            )
+            logBundleSelection(
+                source = "fallback",
+                version = EMBEDDED_VERSION,
+                status = STATUS_FAILED,
+                path = null,
+                reason = REASON_ACTIVE_BUNDLE_FILE_MISSING,
+            )
+            return null
+        }
+
+        Log.d(TAG, "No active OTA bundle selected; using embedded bundle")
+        OTAUpdateStorage.writeMetadata(
+            context,
+            metadata.copy(runningBundleVersion = EMBEDDED_VERSION),
+        )
+        logBundleSelection(
+            source = "apk_bundled",
+            version = EMBEDDED_VERSION,
+            status = metadata.status,
+            path = null,
+        )
+        return null
+    }
+
+    private fun validActiveBundleVersion(context: Context, metadata: OTAUpdateMetadata): String? {
+        val activeVersion = metadata.activeBundleVersion
+        if (isEmbeddedVersion(activeVersion)) {
+            return null
+        }
+        return activeVersion.takeIf { bundleFile(context, it).exists() }
+    }
+
+    private fun bundlePathForVersion(context: Context, bundleVersion: String): String? {
+        if (isEmbeddedVersion(bundleVersion)) {
+            return null
+        }
+        return bundleFile(context, bundleVersion).absolutePath
+    }
+
+    private fun bundleFile(context: Context, bundleVersion: String): File =
+        File(bundleDirectory(context, bundleVersion), "index.android.bundle")
+
+    private fun bundleDirectory(context: Context, bundleVersion: String): File =
+        File(otaDirectory(context), "bundles/$bundleVersion")
+
+    private fun isEmbeddedVersion(bundleVersion: String?): Boolean =
+        bundleVersion.isNullOrBlank() || bundleVersion == EMBEDDED_VERSION
+
+    private fun currentIsoTimestamp(): String {
+        val formatter = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US)
+        formatter.timeZone = TimeZone.getTimeZone("UTC")
+        return formatter.format(Date())
+    }
+
+    private fun logBundleSelection(
+        source: String,
+        version: String,
+        status: String,
+        path: String?,
+        reason: String? = null,
+    ) {
+        Log.d(
+            TAG,
+            "OTA startup selection; source=$source, version=$version, status=$status, " +
+                "path=${path ?: "apk"}, assetsPath=${path?.let { File(it).parent } ?: "apk"}, " +
+                "reason=${reason ?: "none"}",
+        )
+    }
+
+    private fun OTAUpdateMetadata.toLogString(): String =
+        "status=$status, active=$activeBundleVersion, pending=${pendingBundleVersion ?: "none"}, " +
+            "running=$runningBundleVersion, failed=${failedBundleVersion ?: "none"}, " +
+            "launchCount=$launchCountForPending, lastFailure=${lastFailureReason ?: "none"}"
+}
+
+class OTABundleFileNotFoundException(path: String) :
+    IllegalStateException("OTA bundle file was not found at $path")
+
+class OTAMarkSuccessRejectedException(
+    runningVersion: String,
+    pendingVersion: String?,
+) : IllegalStateException(
+    "OTA success can only be confirmed while running the pending OTA bundle. " +
+        "running=$runningVersion, pending=${pendingVersion ?: "none"}",
+)
+
+private fun JSONObject.putNullable(name: String, value: String?) {
+    put(name, value ?: JSONObject.NULL)
+}