@rovq/react-native 0.0.0-stage → 0.1.0

package/android/src/main/java/com/rovq/engine/StrictBase64.kt

@@ -0,0 +1,37 @@
+package com.rovq.engine
+
+/**
+ * Decodes standard Base64 and accepts only one spelling of each value, as the server
+ * does. It is written here because java.util.Base64 needs API 26, android.util.Base64
+ * does not exist in unit tests, and neither of them rejects non-canonical input.
+ */
+internal object StrictBase64 {
+    private const val ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+    /** Returns null unless the value is valid, canonical, and decodes to this many bytes. */
+    fun decode(value: String, expectedSize: Int): ByteArray? {
+        if (value.isEmpty() || value.length % 4 != 0) return null
+        val padding = value.length - value.trimEnd('=').length
+        if (padding > 2) return null
+
+        val output = ByteArray(value.length / 4 * 3 - padding)
+        if (output.size != expectedSize) return null
+
+        var buffer = 0
+        var bits = 0
+        var written = 0
+        for (index in 0 until value.length - padding) {
+            val digit = ALPHABET.indexOf(value[index])
+            if (digit < 0) return null
+            buffer = (buffer shl 6) or digit
+            bits += 6
+            if (bits >= 8) {
+                bits -= 8
+                output[written++] = (buffer shr bits).toByte()
+                buffer = buffer and ((1 shl bits) - 1)
+            }
+        }
+        // Leftover bits must be zero, or two different strings would decode to the same bytes.
+        return if (buffer == 0) output else null
+    }
+}

package/android/src/main/java/com/rovq/engine/UpdateInstaller.kt

@@ -0,0 +1,94 @@
+package com.rovq.engine
+
+import java.io.File
+
+/** What the server offered. None of this is trusted until the manifest has been verified. */
+data class OfferedUpdate(
+    val manifest: String,
+    val signature: String,
+    val keyId: String,
+    val downloadUrl: String,
+)
+
+/** A verified release, fully extracted in its own folder. */
+data class InstalledRelease(
+    val manifest: VerifiedManifest,
+    val folder: File,
+    val bundleFile: File,
+)
+
+/**
+ * Takes an offered update to a verified folder on disk, without activating it.
+ *
+ * Each release gets its own folder because the image cache keys on the path. Reusing a
+ * path would show old images after a reload. See docs/android-bundle-loading.md.
+ *
+ * @param rootDir a folder only the engine uses, normally inside the app's private storage.
+ */
+class UpdateInstaller(
+    rootDir: File,
+    private val verifier: ManifestVerifier,
+    private val downloader: PackageDownloader,
+) {
+    private val updatesDir = File(rootDir, "updates")
+    private val workDir = File(rootDir, "work")
+
+    // Outside the work folder, because a partial download must survive a failure or a restart.
+    private val partialDir = File(rootDir, "partial")
+    private val extractor = SafePackageExtractor()
+
+    /**
+     * @param highestSequence the highest sequence this device has accepted in this stream.
+     * @throws RovqException if any step fails. Nothing is left behind in that case.
+     */
+    @Synchronized
+    fun install(
+        offer: OfferedUpdate,
+        highestSequence: Long,
+        onProgress: (received: Long, total: Long) -> Unit = { _, _ -> },
+    ): InstalledRelease {
+        // Verified first, so an unsigned update causes no network traffic or disk use.
+        val manifest = verifier.verify(offer.manifest, offer.signature, offer.keyId, highestSequence)
+
+        val folder = File(updatesDir, manifest.releaseId)
+        // Folders appear only through the atomic rename below, so one that exists is complete.
+        if (!folder.isDirectory) {
+            install(offer, manifest, folder, onProgress)
+        }
+        return InstalledRelease(manifest, folder, File(folder, PackageRules.BUNDLE_FILE_NAME))
+    }
+
+    private fun install(
+        offer: OfferedUpdate,
+        manifest: VerifiedManifest,
+        folder: File,
+        onProgress: (Long, Long) -> Unit,
+    ) {
+        // Removes anything an earlier run left when the app was killed or the phone lost power.
+        workDir.deleteRecursively()
+        val extracted = File(workDir, "extracted")
+        if (!extracted.mkdirs() ||
+            !(updatesDir.isDirectory || updatesDir.mkdirs()) ||
+            !(partialDir.isDirectory || partialDir.mkdirs())
+        ) {
+            throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not create the engine folders")
+        }
+        val packageFile = File(partialDir, "${manifest.packageHash}.zip")
+        // Only the current offer is worth finishing.
+        partialDir.listFiles()?.filter { it != packageFile }?.forEach { it.delete() }
+        try {
+            downloader.download(offer.downloadUrl, manifest, packageFile, onProgress)
+            extractor.extract(packageFile, extracted)
+            if (!extracted.renameTo(folder)) {
+                throw RovqException(RovqErrorCode.STORAGE_FAILED, "Could not move the release into place")
+            }
+            packageFile.delete()
+        } catch (error: RovqException) {
+            // A file that failed anything but the network is not worth continuing from.
+            if (error.code != RovqErrorCode.DOWNLOAD_FAILED) packageFile.delete()
+            throw error
+        } finally {
+            workDir.deleteRecursively()
+        }
+    }
+}

package/android/src/main/java/com/rovq/engine/UpdateService.kt

@@ -0,0 +1,139 @@
+package com.rovq.engine
+
+import java.io.IOException
+import java.net.HttpURLConnection
+import java.net.URL
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+
+private const val CONNECT_TIMEOUT_MS = 15_000
+private const val READ_TIMEOUT_MS = 30_000
+
+/** What the device tells the server when asking for updates. */
+data class CheckRequest(
+    val deploymentKey: String,
+    val deviceId: String,
+    val runtimeVersion: String,
+    val binaryVersion: String,
+    val currentReleaseId: String?,
+    val highestSequence: Long,
+)
+
+/** The server's answer. It is advice only, because [OfferedUpdate] is verified before use. */
+sealed interface CheckResponse {
+    data object None : CheckResponse
+    data object Rollback : CheckResponse
+    data class Update(val offer: OfferedUpdate) : CheckResponse
+}
+
+/** A key's signed statement that it must no longer be trusted. The engine verifies it. */
+data class KeyRevocation(val keyId: String, val statement: String, val signature: String)
+
+data class CheckAnswer(
+    val response: CheckResponse,
+    val revocations: List<KeyRevocation> = emptyList(),
+)
+
+/** The server API the engine needs, kept separate so tests can replace it. */
+interface UpdateService {
+    /** @throws IOException if the server cannot be reached or answers with an error. */
+    fun check(request: CheckRequest): CheckAnswer
+
+    /** @throws IOException if the events could not be delivered. */
+    fun report(deploymentKey: String, deviceId: String, events: List<QueuedEvent>)
+}
+
+class HttpUpdateService(
+    private val apiUrl: String,
+    private val allowInsecureUrls: Boolean = false,
+) : UpdateService {
+
+    override fun check(request: CheckRequest): CheckAnswer {
+        val body = JSONObject()
+            .put("deploymentKey", request.deploymentKey)
+            .put("deviceId", request.deviceId)
+            .put("platform", "ANDROID")
+            .put("runtimeVersion", request.runtimeVersion)
+            .put("binaryVersion", request.binaryVersion)
+            .put("highestSequence", request.highestSequence)
+        request.currentReleaseId?.let { body.put("currentReleaseId", it) }
+
+        return try {
+            val response = post("/device/updates/check", body)
+            val action = when (val action = response.getString("action")) {
+                "NONE" -> CheckResponse.None
+                "ROLLBACK" -> CheckResponse.Rollback
+                "UPDATE" -> {
+                    val update = response.getJSONObject("update")
+                    CheckResponse.Update(
+                        OfferedUpdate(
+                            manifest = update.getString("manifest"),
+                            signature = update.getString("signature"),
+                            keyId = update.getString("keyId"),
+                            downloadUrl = update.getString("downloadUrl"),
+                        ),
+                    )
+                }
+                else -> throw IOException("Unknown action $action")
+            }
+            CheckAnswer(action, readRevocations(response))
+        } catch (error: JSONException) {
+            throw IOException("The server sent an unreadable response", error)
+        }
+    }
+
+    private fun readRevocations(response: JSONObject): List<KeyRevocation> {
+        val list = response.optJSONArray("revokedKeys") ?: return emptyList()
+        return (0 until list.length()).map { index ->
+            val item = list.getJSONObject(index)
+            KeyRevocation(item.getString("keyId"), item.getString("statement"), item.getString("signature"))
+        }
+    }
+
+    override fun report(deploymentKey: String, deviceId: String, events: List<QueuedEvent>) {
+        val list = JSONArray()
+        events.forEach { event ->
+            val json = JSONObject()
+                .put("clientEventId", event.clientEventId)
+                .put("type", event.type)
+                .put("occurredAt", event.occurredAt)
+            event.releaseId?.let { json.put("releaseId", it) }
+            event.errorCode?.let { json.put("errorCode", it) }
+            list.put(json)
+        }
+        post(
+            "/device/events",
+            JSONObject()
+                .put("deploymentKey", deploymentKey)
+                .put("deviceId", deviceId)
+                .put("events", list),
+        )
+    }
+
+    private fun post(path: String, body: JSONObject): JSONObject {
+        val url = URL(apiUrl.trimEnd('/') + path)
+        if (url.protocol != "https" && !allowInsecureUrls) {
+            throw IOException("The API URL must use HTTPS")
+        }
+        val connection = url.openConnection() as HttpURLConnection
+        try {
+            connection.connectTimeout = CONNECT_TIMEOUT_MS
+            connection.readTimeout = READ_TIMEOUT_MS
+            connection.requestMethod = "POST"
+            connection.doOutput = true
+            connection.setRequestProperty("content-type", "application/json")
+            connection.outputStream.use { it.write(body.toString().toByteArray(Charsets.UTF_8)) }
+            if (connection.responseCode != HttpURLConnection.HTTP_OK) {
+                throw IOException("The server answered ${connection.responseCode}")
+            }
+            return try {
+                JSONObject(connection.inputStream.bufferedReader().use { it.readText() })
+            } catch (error: JSONException) {
+                throw IOException("The server sent an unreadable response", error)
+            }
+        } finally {
+            connection.disconnect()
+        }
+    }
+}

package/android/src/main/java/com/rovq/engine/ZipStructureCheck.kt

@@ -0,0 +1,194 @@
+package com.rovq.engine
+
+import java.io.File
+import java.io.IOException
+import java.io.RandomAccessFile
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+
+private const val END_OF_DIRECTORY_SIGNATURE = 0x06054b50L
+private const val CENTRAL_HEADER_SIGNATURE = 0x02014b50L
+private const val LOCAL_HEADER_SIGNATURE = 0x04034b50L
+private const val END_OF_DIRECTORY_SIZE = 22
+private const val CENTRAL_HEADER_SIZE = 46
+private const val LOCAL_HEADER_SIZE = 30
+private const val MAX_COMMENT_SIZE = 65_535
+private const val MAX_DIRECTORY_SIZE = 64L * 1024 * 1024
+private const val FLAG_ENCRYPTED = 0x1
+private const val FLAG_UTF8_NAME = 0x800
+private const val UNICODE_PATH_EXTRA_FIELD = 0x7075
+private const val FILE_TYPE_MASK = 0xF000
+private const val REGULAR_FILE = 0x8000
+private const val FOLDER = 0x4000
+private const val MAX_16_BITS = 0xFFFF
+private const val MAX_32_BITS = 0xFFFFFFFFL
+
+/**
+ * Checks the structure of a ZIP file, which Java's ZipFile reads but does not question. These are
+ * the same rules as the iOS reader, so both platforms refuse the same files.
+ */
+internal object ZipStructureCheck {
+    private class Header(val name: String, val offset: Long, val compressedSize: Long)
+
+    /** @throws RovqException with INVALID_PACKAGE if anything is wrong. */
+    fun check(file: File) {
+        try {
+            RandomAccessFile(file, "r").use { zip ->
+                val headers = readDirectory(zip)
+                checkNoOverlap(zip, headers)
+            }
+        } catch (error: IOException) {
+            throw invalid("Could not read the ZIP file", error)
+        }
+    }
+
+    private fun readDirectory(zip: RandomAccessFile): List<Header> {
+        val end = findEndOfDirectory(zip)
+        if (end.u16(4) != 0 || end.u16(6) != 0 || end.u16(8) != end.u16(10)) {
+            throw invalid("Split ZIP files are not supported")
+        }
+        val count = end.u16(10)
+        val directorySize = end.u32(12)
+        val directoryOffset = end.u32(16)
+        if (count == MAX_16_BITS || directorySize == MAX_32_BITS || directoryOffset == MAX_32_BITS) {
+            throw invalid("ZIP64 files are not supported")
+        }
+        if (directoryOffset + directorySize > zip.length()) {
+            throw invalid("The directory is outside the file")
+        }
+        if (directorySize > MAX_DIRECTORY_SIZE) throw invalid("The directory is too large")
+
+        val directory = read(zip, directoryOffset, directorySize.toInt())
+        val headers = ArrayList<Header>(minOf(count, PackageRules.MAX_ENTRIES))
+        var position = 0
+        repeat(count) {
+            if (position + CENTRAL_HEADER_SIZE > directory.capacity() ||
+                directory.u32(position) != CENTRAL_HEADER_SIGNATURE
+            ) {
+                throw invalid("The directory is malformed")
+            }
+            val flags = directory.u16(position + 8)
+            val nameLength = directory.u16(position + 28)
+            val extraLength = directory.u16(position + 30)
+            val commentLength = directory.u16(position + 32)
+            val attributes = directory.u32(position + 38)
+            val total = CENTRAL_HEADER_SIZE + nameLength + extraLength + commentLength
+            if (position + total > directory.capacity()) throw invalid("The directory is malformed")
+            if (flags and FLAG_ENCRYPTED != 0) throw invalid("A file is encrypted")
+
+            val nameBytes = directory.bytes(position + CENTRAL_HEADER_SIZE, nameLength)
+            val name = decodeName(nameBytes, flags)
+            checkExtraFields(directory.bytes(position + CENTRAL_HEADER_SIZE + nameLength, extraLength))
+
+            // Symbolic links could point outside the package folder after extraction.
+            val fileType = ((attributes shr 16) and FILE_TYPE_MASK.toLong()).toInt()
+            if (fileType != 0 && fileType != REGULAR_FILE && fileType != FOLDER) {
+                throw invalid("The file $name is not a regular file")
+            }
+            headers += Header(name, directory.u32(position + 42), directory.u32(position + 20))
+            position += total
+        }
+        if (position != directory.capacity()) throw invalid("The directory has extra data")
+        return headers
+    }
+
+    /**
+     * Rejects names that different ZIP readers would decode differently. Otherwise the server
+     * could approve one path while this device writes to another.
+     */
+    private fun decodeName(bytes: ByteBuffer, flags: Int): String {
+        val raw = ByteArray(bytes.remaining()).also { bytes.duplicate().get(it) }
+        if (flags and FLAG_UTF8_NAME == 0 && raw.any { it < 0x20 || it >= 0x7F }) {
+            throw invalid("A file name is not ASCII and is not marked as UTF-8")
+        }
+        val name = String(raw, Charsets.UTF_8)
+        if (!name.toByteArray(Charsets.UTF_8).contentEquals(raw)) {
+            throw invalid("A file name is not valid UTF-8")
+        }
+        return name
+    }
+
+    private fun checkExtraFields(extra: ByteBuffer) {
+        var position = 0
+        while (position + 4 <= extra.capacity()) {
+            if (extra.u16(position) == UNICODE_PATH_EXTRA_FIELD) {
+                throw invalid("A file has an alternative name, which is not allowed")
+            }
+            position += 4 + extra.u16(position + 2)
+        }
+    }
+
+    private fun findEndOfDirectory(zip: RandomAccessFile): ByteBuffer {
+        val size = zip.length()
+        if (size < END_OF_DIRECTORY_SIZE) throw invalid("Not a ZIP file")
+        val tailSize = minOf(size, (END_OF_DIRECTORY_SIZE + MAX_COMMENT_SIZE).toLong()).toInt()
+        val tail = read(zip, size - tailSize, tailSize)
+        var position = tailSize - END_OF_DIRECTORY_SIZE
+        while (position >= 0) {
+            // The comment length must reach exactly to the end, so comment bytes that merely look
+            // like this record are not mistaken for it.
+            if (tail.u32(position) == END_OF_DIRECTORY_SIGNATURE &&
+                position + END_OF_DIRECTORY_SIZE + tail.u16(position + 20) == tailSize
+            ) {
+                return tail.bytes(position, END_OF_DIRECTORY_SIZE)
+            }
+            position -= 1
+        }
+        throw invalid("Not a ZIP file")
+    }
+
+    /** Entries that share bytes let a tiny file expand enormously, so each must have its own. */
+    private fun checkNoOverlap(zip: RandomAccessFile, headers: List<Header>) {
+        val ranges = headers.map { it.offset to dataEnd(zip, it) }.sortedBy { it.first }
+        ranges.zipWithNext { previous, next ->
+            if (next.first < previous.second) throw invalid("Files in the ZIP overlap")
+        }
+    }
+
+    /**
+     * The local header must name the same file as the directory, because other readers trust the
+     * local header instead.
+     */
+    private fun dataEnd(zip: RandomAccessFile, entry: Header): Long {
+        if (entry.offset + LOCAL_HEADER_SIZE > zip.length()) {
+            throw invalid("A file is outside the ZIP file")
+        }
+        val header = read(zip, entry.offset, LOCAL_HEADER_SIZE)
+        if (header.u32(0) != LOCAL_HEADER_SIGNATURE) throw invalid("A file header is malformed")
+        val nameLength = header.u16(26)
+        val extraLength = header.u16(28)
+        if (entry.offset + LOCAL_HEADER_SIZE + nameLength > zip.length()) {
+            throw invalid("A file is outside the ZIP file")
+        }
+        val name = read(zip, entry.offset + LOCAL_HEADER_SIZE, nameLength)
+        val nameBytes = ByteArray(nameLength).also { name.get(it) }
+        if (!nameBytes.contentEquals(entry.name.toByteArray(Charsets.UTF_8))) {
+            throw invalid("The file ${entry.name} has a different name in its local header")
+        }
+        val end = entry.offset + LOCAL_HEADER_SIZE + nameLength + extraLength + entry.compressedSize
+        if (end > zip.length()) throw invalid("The file ${entry.name} is outside the ZIP file")
+        return end
+    }
+
+    private fun read(zip: RandomAccessFile, offset: Long, count: Int): ByteBuffer {
+        val bytes = ByteArray(count)
+        zip.seek(offset)
+        zip.readFully(bytes)
+        return ByteBuffer.wrap(bytes).order(ByteOrder.LITTLE_ENDIAN)
+    }
+
+    private fun ByteBuffer.u16(position: Int): Int = getShort(position).toInt() and 0xFFFF
+
+    private fun ByteBuffer.u32(position: Int): Long = getInt(position).toLong() and MAX_32_BITS
+
+    private fun ByteBuffer.bytes(position: Int, count: Int): ByteBuffer {
+        val copy = ByteArray(count)
+        val view = duplicate()
+        view.position(position)
+        view.get(copy)
+        return ByteBuffer.wrap(copy).order(ByteOrder.LITTLE_ENDIAN)
+    }
+
+    private fun invalid(message: String, cause: Throwable? = null) =
+        RovqException(RovqErrorCode.INVALID_PACKAGE, message, cause)
+}

package/android/src/react/java/com/rovq/engine/react/Rovq.kt

@@ -0,0 +1,101 @@
+package com.rovq.engine.react
+
+import android.app.Activity
+import android.app.Application
+import android.content.pm.PackageInfo
+import android.os.Build
+import android.os.Bundle
+import com.rovq.engine.EngineConfig
+import com.rovq.engine.RovqEngine
+import java.io.File
+
+/** What an app supplies. Everything here ships inside the app, so nothing here is secret. */
+data class RovqConfig(
+    val apiUrl: String,
+    val deploymentKey: String,
+    /** Change this whenever native code changes. */
+    val runtimeVersion: String,
+    /** Key IDs and their Base64 Ed25519 public keys. */
+    val trustedKeys: Map<String, String>,
+    /** Allows http:// for local development only. */
+    val allowInsecureUrls: Boolean = false,
+)
+
+/** Holds the one engine of this process. Call [initialize] first, in Application.onCreate. */
+object Rovq {
+    @Volatile
+    private var instance: RovqEngine? = null
+
+    val engine: RovqEngine
+        get() = instance ?: error("Call Rovq.initialize in Application.onCreate first")
+
+    /** For JavaScript, where a missing engine should be an error it can handle, not a crash. */
+    val engineOrNull: RovqEngine?
+        get() = instance
+
+    @Synchronized
+    fun initialize(application: Application, config: RovqConfig) {
+        if (instance != null) return
+        val info = application.packageManager.getPackageInfo(application.packageName, 0)
+        val engine = RovqEngine(
+            File(application.filesDir, "rovq"),
+            EngineConfig(
+                apiUrl = config.apiUrl,
+                deploymentKey = config.deploymentKey,
+                runtimeVersion = config.runtimeVersion,
+                binaryVersion = info.versionName ?: "0",
+                binaryId = binaryIdOf(info),
+                trustedKeys = config.trustedKeys,
+                allowInsecureUrls = config.allowInsecureUrls,
+            ),
+        )
+        instance = engine
+        application.registerActivityLifecycleCallbacks(BackgroundWatcher(engine))
+        watchForCrashes(engine)
+    }
+
+    private fun watchForCrashes(engine: RovqEngine) {
+        val previous = Thread.getDefaultUncaughtExceptionHandler()
+        Thread.setDefaultUncaughtExceptionHandler { thread, error ->
+            try {
+                engine.noteCrashed()
+            } finally {
+                // The app's own crash handling must always run, whatever happens above.
+                previous?.uncaughtException(thread, error)
+            }
+        }
+    }
+
+    /** Tells the engine when no activity is visible, which is what closing an app looks like. */
+    private class BackgroundWatcher(private val engine: RovqEngine) :
+        Application.ActivityLifecycleCallbacks {
+        private var visible = 0
+
+        override fun onActivityStarted(activity: Activity) {
+            visible += 1
+        }
+
+        override fun onActivityStopped(activity: Activity) {
+            visible -= 1
+            // Rotating the screen also stops the activity, but nobody left the app.
+            if (visible == 0 && !activity.isChangingConfigurations) engine.noteBackgrounded()
+        }
+
+        override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) = Unit
+        override fun onActivityResumed(activity: Activity) = Unit
+        override fun onActivityPaused(activity: Activity) = Unit
+        override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) = Unit
+        override fun onActivityDestroyed(activity: Activity) = Unit
+    }
+
+    /** The install time changes with every update of the app itself, even at the same version. */
+    private fun binaryIdOf(info: PackageInfo): String {
+        val versionCode = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+            info.longVersionCode
+        } else {
+            @Suppress("DEPRECATION")
+            info.versionCode.toLong()
+        }
+        return "$versionCode:${info.lastUpdateTime}"
+    }
+}