@rovq/react-native 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moatazMahdi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @rovq/react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Over-the-air updates for React Native apps, served by your own ROVQ server. Each release is signed on your computer and verified by the phone, and a release that crashes before it starts rolls itself back.
+
+Requires React Native 0.82 or newer, with the New Architecture.
+
+## Install
+
+```sh
+npm install @rovq/react-native
+cd ios && pod install
+```
+
+Then connect the native side, which decides which bundle runs. The setup page of your app in the ROVQ dashboard shows this code with your app's real values.
+
+### Android, in `MainApplication.kt`
+
+```kotlin
+override val reactHost: ReactHost by lazy {
+  RovqReactHost.create(this, PackageList(this).packages)
+}
+
+override fun onCreate() {
+  super.onCreate()
+  Rovq.initialize(
+    this,
+    RovqConfig(
+      apiUrl = "https://your-server/api/v1",
+      deploymentKey = "rovq_dep_...",
+      runtimeVersion = "1",
+      trustedKeys = mapOf("2026-11" to "<public key>"),
+    ),
+  )
+  loadReactNative(this)
+}
+```
+
+### iOS, in `AppDelegate.swift` and `SceneDelegate.swift`
+
+```swift
+RovqHost.initialize(
+  config: RovqConfig(
+    apiURL: "https://your-server/api/v1",
+    deploymentKey: "rovq_dep_...",
+    runtimeVersion: "1",
+    trustedKeys: ["2026-11": "<public key>"]
+  )
+)
+
+override func bundleURL() -> URL? {
+  #if DEBUG
+  RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
+  #else
+  RovqHost.bundleURL() ?? Bundle.main.url(forResource: "main", withExtension: "jsbundle")
+  #endif
+}
+```
+
+## Use
+
+```ts
+import { notifyApplicationReady, sync } from '@rovq/react-native';
+
+useEffect(() => {
+  // A release that never calls this is abandoned on the next start.
+  notifyApplicationReady();
+  sync().catch((error) => console.warn('Update check failed', error.code));
+}, []);
+```
+
+To ask the user before downloading, use `checkForUpdate`, `downloadUpdate({ onProgress })`, `installUpdate`, and `restartApp`. Failures throw `RovqError` with a stable `code`.
+
+Publish updates with [`@rovq/cli`](https://www.npmjs.com/package/@rovq/cli).
+
+## License
+
+MIT

package/Rovq.podspec

@@ -0,0 +1,19 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'Rovq'
+  s.version = package['version']
+  s.summary = package['description']
+  s.homepage = 'https://github.com/moatazMahdi/rovq'
+  s.license = 'MIT'
+  s.authors = 'moatazMahdi'
+  s.platforms = { ios: min_ios_version_supported }
+  s.source = { git: 'https://github.com/moatazMahdi/rovq.git', tag: s.version.to_s }
+  s.source_files = 'ios/Engine/**/*.swift', 'ios/React/**/*.{swift,mm}'
+  s.swift_version = '5.9'
+  s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
+
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,86 @@
+plugins {
+    id 'com.android.library'
+}
+
+// The engine has no React Native code, so it can be built and tested on its own, in
+// seconds. Inside an app, the React Native integration is added on top of it.
+def insideApp = rootProject.name != 'rovq-engine'
+
+// React Native's app template turns off the Kotlin support built into Android Gradle Plugin 9.
+def usesKotlinPlugin = insideApp && findProperty('android.builtInKotlin') == 'false'
+
+// Rebuilding only changed files fails with "Cannot access ... it is internal" when this package is
+// linked through a symbolic link, as npm's file: dependencies are. Compiling it fully each time
+// costs seconds. The Kotlin plugin reads this when it is applied, so it must be set first.
+if (insideApp) {
+    ext.set('kotlin.incremental', 'false')
+}
+
+if (usesKotlinPlugin) {
+    apply plugin: 'kotlin-android'
+}
+
+// Keeps the two kinds of build from mixing outputs. The build inside an app stays in build/,
+// because React Native's autolinking expects the generated code there.
+if (!insideApp) {
+    layout.buildDirectory = layout.projectDirectory.dir('build/standalone')
+}
+
+if (insideApp) {
+    apply plugin: 'com.facebook.react'
+
+    react {
+        // The app's install holds React Native, not this package's folder.
+        reactNativeDir = rootProject.file('../node_modules/react-native')
+        codegenDir = rootProject.file('../node_modules/@react-native/codegen')
+    }
+}
+
+android {
+    namespace = 'com.rovq.engine'
+    compileSdk = 37
+
+    defaultConfig {
+        minSdk = 24
+        testInstrumentationRunner = 'androidx.test.runner.AndroidJUnitRunner'
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    sourceSets {
+        if (usesKotlinPlugin) {
+            main.java.srcDirs += 'src/react/java'
+        } else if (insideApp) {
+            main.kotlin.directories.add('src/react/java')
+        } else {
+            // Test helpers that run both on the computer and on a device.
+            test.kotlin.directories.add('src/sharedTest/java')
+            androidTest.kotlin.directories.add('src/sharedTest/java')
+        }
+    }
+
+    testOptions {
+        // Keeps unit tests independent of Android framework classes.
+        unitTests.returnDefaultValues = false
+    }
+}
+
+dependencies {
+    // Android includes Ed25519 only from API 33, and the engine supports API 24.
+    implementation 'com.google.crypto.tink:tink-android:1.24.0'
+
+    if (insideApp) {
+        // The version is set by the React Native Gradle Plugin.
+        implementation 'com.facebook.react:react-android'
+    }
+
+    testImplementation 'junit:junit:4.13.2'
+    // Android provides org.json on devices. Unit tests on the computer need their own copy.
+    testImplementation 'org.json:json:20260814'
+
+    androidTestImplementation 'androidx.test:runner:1.7.0'
+    androidTestImplementation 'androidx.test.ext:junit:1.3.0'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+</manifest>

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

@@ -0,0 +1,176 @@
+package com.rovq.engine
+
+import java.io.File
+import java.io.FileOutputStream
+import java.io.IOException
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+
+/** A release on the device, identified by its folder name and its signed sequence. */
+data class ReleaseRef(val id: String, val sequence: Long)
+
+/** Waiting to be sent to the server. Device events are retried, so each has its own ID. */
+data class QueuedEvent(
+    val clientEventId: String,
+    val type: String,
+    val releaseId: String?,
+    val errorCode: String?,
+    val occurredAt: String,
+)
+
+/** A release that failed its checks after downloading, and when it may be tried again. */
+data class PostponedDownload(val releaseId: String, val attempts: Int, val untilMillis: Long)
+
+/**
+ * Everything the engine must remember across process deaths.
+ *
+ * A release moves from [downloaded] to [pending] to [trying] to [current]:
+ * - [downloaded]: verified and on disk, but nothing will load it until the app installs it.
+ * - [pending]: installed, and loads on the next JavaScript start.
+ * - [trying]: being loaded right now. If the next start finds it still here, it never
+ *   confirmed that it works, so it is abandoned.
+ * - [current]: confirmed to work.
+ * - [previous]: the confirmed release before [current], kept to go back to.
+ */
+data class EngineState(
+    val deviceId: String,
+    val binaryId: String,
+    val runtimeVersion: String,
+    val highestSequence: Long = 0,
+    val current: ReleaseRef? = null,
+    val previous: ReleaseRef? = null,
+    val downloaded: ReleaseRef? = null,
+    val pending: ReleaseRef? = null,
+    val trying: ReleaseRef? = null,
+    /** True if the app went to the background while [trying], so a person probably closed it. */
+    val backgroundedWhileTrying: Boolean = false,
+    /** How many more starts [trying] was given because it was closed before confirming. */
+    val tryingRetries: Int = 0,
+    val postponed: PostponedDownload? = null,
+    val revokedPublicKeys: Set<String> = emptySet(),
+    val events: List<QueuedEvent> = emptyList(),
+)
+
+/**
+ * Saves the state so that a crash at any moment leaves either the old state or the new
+ * one, never a mixture. The app's first screen depends on this file being readable.
+ */
+internal class EngineStateStore(rootDir: File) {
+    private val file = File(rootDir, "state.json")
+    private val temporary = File(rootDir, "state.json.tmp")
+
+    /** Returns null if there is no state, or if it is unreadable. */
+    fun read(): EngineState? {
+        if (!file.isFile) return null
+        return try {
+            parse(JSONObject(file.readText()))
+        } catch (error: JSONException) {
+            null
+        } catch (error: IOException) {
+            null
+        }
+    }
+
+    fun write(state: EngineState) {
+        // Writing to another file first means a crash cannot leave a half-written state.
+        FileOutputStream(temporary).use { output ->
+            output.write(toJson(state).toString().toByteArray(Charsets.UTF_8))
+            output.fd.sync()
+        }
+        if (!temporary.renameTo(file)) throw IOException("Could not save the engine state")
+    }
+
+    private fun parse(json: JSONObject): EngineState {
+        val events = json.getJSONArray("events")
+        return EngineState(
+            deviceId = json.getString("deviceId"),
+            binaryId = json.getString("binaryId"),
+            runtimeVersion = json.getString("runtimeVersion"),
+            highestSequence = json.getLong("highestSequence"),
+            current = readRelease(json, "current"),
+            previous = readRelease(json, "previous"),
+            downloaded = readRelease(json, "downloaded"),
+            pending = readRelease(json, "pending"),
+            trying = readRelease(json, "trying"),
+            backgroundedWhileTrying = json.optBoolean("backgroundedWhileTrying", false),
+            tryingRetries = json.optInt("tryingRetries", 0),
+            postponed = readPostponed(json),
+            revokedPublicKeys = readStrings(json, "revokedPublicKeys"),
+            events = (0 until events.length()).map { index ->
+                val event = events.getJSONObject(index)
+                QueuedEvent(
+                    clientEventId = event.getString("clientEventId"),
+                    type = event.getString("type"),
+                    releaseId = optionalString(event, "releaseId"),
+                    errorCode = optionalString(event, "errorCode"),
+                    occurredAt = event.getString("occurredAt"),
+                )
+            },
+        )
+    }
+
+    private fun readPostponed(json: JSONObject): PostponedDownload? {
+        if (json.isNull("postponed")) return null
+        val value = json.getJSONObject("postponed")
+        return PostponedDownload(
+            value.getString("releaseId"),
+            value.getInt("attempts"),
+            value.getLong("untilMillis"),
+        )
+    }
+
+    private fun readStrings(json: JSONObject, name: String): Set<String> {
+        val list = json.optJSONArray(name) ?: return emptySet()
+        return (0 until list.length()).map { list.getString(it) }.toSet()
+    }
+
+    private fun readRelease(json: JSONObject, name: String): ReleaseRef? {
+        if (json.isNull(name)) return null
+        val release = json.getJSONObject(name)
+        return ReleaseRef(release.getString("id"), release.getLong("sequence"))
+    }
+
+    private fun optionalString(json: JSONObject, name: String): String? =
+        if (json.isNull(name)) null else json.getString(name)
+
+    private fun toJson(state: EngineState): JSONObject {
+        val events = JSONArray()
+        state.events.forEach { event ->
+            events.put(
+                JSONObject()
+                    .put("clientEventId", event.clientEventId)
+                    .put("type", event.type)
+                    .put("releaseId", event.releaseId ?: JSONObject.NULL)
+                    .put("errorCode", event.errorCode ?: JSONObject.NULL)
+                    .put("occurredAt", event.occurredAt),
+            )
+        }
+        return JSONObject()
+            .put("deviceId", state.deviceId)
+            .put("binaryId", state.binaryId)
+            .put("runtimeVersion", state.runtimeVersion)
+            .put("highestSequence", state.highestSequence)
+            .put("current", releaseJson(state.current))
+            .put("previous", releaseJson(state.previous))
+            .put("downloaded", releaseJson(state.downloaded))
+            .put("pending", releaseJson(state.pending))
+            .put("trying", releaseJson(state.trying))
+            .put("backgroundedWhileTrying", state.backgroundedWhileTrying)
+            .put("tryingRetries", state.tryingRetries)
+            .put("postponed", postponedJson(state.postponed))
+            .put("revokedPublicKeys", JSONArray(state.revokedPublicKeys.toList()))
+            .put("events", events)
+    }
+
+    private fun postponedJson(value: PostponedDownload?): Any =
+        value?.let {
+            JSONObject()
+                .put("releaseId", it.releaseId)
+                .put("attempts", it.attempts)
+                .put("untilMillis", it.untilMillis)
+        } ?: JSONObject.NULL
+
+    private fun releaseJson(release: ReleaseRef?): Any =
+        release?.let { JSONObject().put("id", it.id).put("sequence", it.sequence) } ?: JSONObject.NULL
+}

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

@@ -0,0 +1,173 @@
+package com.rovq.engine
+
+import com.google.crypto.tink.subtle.Ed25519Verify
+import java.security.GeneralSecurityException
+import org.json.JSONException
+import org.json.JSONObject
+
+private const val PUBLIC_KEY_SIZE = 32
+private const val SIGNATURE_SIZE = 64
+private const val MANIFEST_VERSION = 1
+private const val PLATFORM = "ANDROID"
+private val MANIFEST_FIELDS = setOf(
+    "version",
+    "releaseId",
+    "deploymentKey",
+    "platform",
+    "runtimeVersion",
+    "binaryVersion",
+    "sequence",
+    "mandatory",
+    "package",
+)
+private val PACKAGE_FIELDS = setOf("hash", "size")
+private val UUID_PATTERN = Regex("^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+private val HASH_PATTERN = Regex("^[0-9a-f]{64}$")
+
+/** Facts from a manifest whose signature has been verified. Nothing else should be trusted. */
+data class VerifiedManifest(
+    val releaseId: String,
+    val sequence: Long,
+    val mandatory: Boolean,
+    val packageHash: String,
+    val packageSize: Long,
+)
+
+/**
+ * The device's own security check. It trusts only the public keys built into the
+ * app, so a compromised server cannot get code onto the device.
+ *
+ * @param trustedKeys key IDs and their Base64 Ed25519 public keys, built into the app.
+ */
+class ManifestVerifier(
+    private val trustedKeys: Map<String, String>,
+    private val deploymentKey: String,
+    private val runtimeVersion: String,
+) {
+    private val verifiers: Map<String, Ed25519Verify> = trustedKeys.mapValues { (keyId, publicKey) ->
+        val bytes = StrictBase64.decode(publicKey, PUBLIC_KEY_SIZE)
+            ?: throw IllegalArgumentException("Public key $keyId is not a Base64 Ed25519 key")
+        Ed25519Verify(bytes)
+    }
+
+    // Public keys, not IDs, so a later version of the app can reuse an ID with a new key.
+    @Volatile
+    var revokedPublicKeys: Set<String> = emptySet()
+
+    /**
+     * Checks a key's statement that it must no longer be trusted, and returns its public key.
+     * Only the key's own signature counts, so a stolen key can revoke only itself. Comparing the
+     * exact text means nothing unsigned reaches a parser.
+     *
+     * @return null if the statement is not valid, in which case it must be ignored.
+     */
+    fun verifyRevocation(keyId: String, statement: String, signature: String): String? {
+        val publicKey = trustedKeys[keyId] ?: return null
+        val expected = """{"version":1,"type":"key-revocation","publicKey":"$publicKey"}"""
+        if (statement != expected) return null
+        return try {
+            verifySignature(statement, signature, keyId)
+            publicKey
+        } catch (error: RovqException) {
+            null
+        }
+    }
+
+    /**
+     * @param highestSequence the highest sequence this device has accepted in this stream.
+     * @throws RovqException if anything fails. The device must then ignore the update.
+     */
+    fun verify(
+        manifest: String,
+        signature: String,
+        keyId: String,
+        highestSequence: Long,
+    ): VerifiedManifest {
+        if (trustedKeys[keyId] in revokedPublicKeys) {
+            throw RovqException(RovqErrorCode.REVOKED_SIGNING_KEY, "Signing key $keyId was revoked")
+        }
+        verifySignature(manifest, signature, keyId)
+        // Only signed text reaches the JSON parser.
+        val verified = parseAndCheck(manifest)
+        if (verified.sequence <= highestSequence) {
+            throw RovqException(
+                RovqErrorCode.STALE_SEQUENCE,
+                "Sequence ${verified.sequence} is not above $highestSequence",
+            )
+        }
+        return verified
+    }
+
+    private fun verifySignature(manifest: String, signature: String, keyId: String) {
+        val verifier = verifiers[keyId]
+            ?: throw RovqException(RovqErrorCode.UNKNOWN_SIGNING_KEY, "Unknown signing key $keyId")
+        val signatureBytes = StrictBase64.decode(signature, SIGNATURE_SIZE)
+            ?: throw RovqException(RovqErrorCode.INVALID_SIGNATURE, "Malformed signature")
+        try {
+            verifier.verify(signatureBytes, manifest.toByteArray(Charsets.UTF_8))
+        } catch (error: GeneralSecurityException) {
+            throw RovqException(RovqErrorCode.INVALID_SIGNATURE, "Signature does not match", error)
+        }
+    }
+
+    private fun parseAndCheck(manifest: String): VerifiedManifest {
+        val root = parseObject(manifest)
+        requireOnlyFields(root, MANIFEST_FIELDS)
+        if (longField(root, "version") != MANIFEST_VERSION.toLong()) invalid("Unknown manifest version")
+
+        val releaseId = stringField(root, "releaseId")
+        // Later used as a folder name, so it must be exactly a UUID.
+        if (!UUID_PATTERN.matches(releaseId)) invalid("releaseId is not a UUID")
+
+        val sequence = longField(root, "sequence")
+        if (sequence <= 0) invalid("sequence must be positive")
+
+        val mandatory = root.opt("mandatory") as? Boolean ?: invalid("mandatory must be a boolean")
+        stringField(root, "binaryVersion")
+
+        val packageInfo = root.opt("package") as? JSONObject ?: invalid("package must be an object")
+        requireOnlyFields(packageInfo, PACKAGE_FIELDS)
+        val hash = stringField(packageInfo, "hash")
+        if (!HASH_PATTERN.matches(hash)) invalid("package hash is malformed")
+        val size = longField(packageInfo, "size")
+        if (size <= 0) invalid("package size must be positive")
+
+        // A valid signature for another deployment, platform or runtime must not install here.
+        requireMatch("deploymentKey", stringField(root, "deploymentKey"), deploymentKey)
+        requireMatch("platform", stringField(root, "platform"), PLATFORM)
+        requireMatch("runtimeVersion", stringField(root, "runtimeVersion"), runtimeVersion)
+
+        return VerifiedManifest(releaseId, sequence, mandatory, hash, size)
+    }
+
+    private fun parseObject(text: String): JSONObject = try {
+        JSONObject(text)
+    } catch (error: JSONException) {
+        throw RovqException(RovqErrorCode.INVALID_MANIFEST, "Manifest is not valid JSON", error)
+    }
+
+    private fun requireOnlyFields(value: JSONObject, allowed: Set<String>) {
+        for (key in value.keys()) {
+            if (key !in allowed) invalid("Unknown field $key")
+        }
+    }
+
+    private fun stringField(value: JSONObject, name: String): String =
+        value.opt(name) as? String ?: invalid("$name must be a string")
+
+    private fun longField(value: JSONObject, name: String): Long =
+        when (val raw = value.opt(name)) {
+            is Int -> raw.toLong()
+            is Long -> raw
+            else -> invalid("$name must be a whole number")
+        }
+
+    private fun requireMatch(name: String, actual: String, expected: String) {
+        if (actual != expected) {
+            throw RovqException(RovqErrorCode.MANIFEST_MISMATCH, "$name does not match this app")
+        }
+    }
+
+    private fun invalid(message: String): Nothing =
+        throw RovqException(RovqErrorCode.INVALID_MANIFEST, message)
+}