@rovq/react-native 0.0.0-stage → 0.2.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,121 @@
-# 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));
+}, []);
+```
+
+For full control, use `checkForUpdate`, `downloadUpdate({ onProgress })`, `installUpdate`, and `restartApp`. They throw `RovqError` with a stable `code`.
+
+## Updating in the foreground or the background
+
+Wrap your app in `RovqUpdateGate`, and choose how updates arrive:
+
+```tsx
+import { RovqUpdateGate } from '@rovq/react-native';
+
+export default function Root() {
+  return (
+    <RovqUpdateGate mode="auto" variant="bar">
+      <App />
+    </RovqUpdateGate>
+  );
+}
+```
+
+| `mode`           | What the user sees                                                                |
+| ---------------- | --------------------------------------------------------------------------------- |
+| `background`     | Nothing. The update downloads while they use the app, and loads on the next start |
+| `foreground`     | A progress screen, then the app restarts on the new version at once               |
+| `auto` (default) | Foreground for a release published with `--mandatory`, background otherwise       |
+
+`variant` is `bar` or `percent`. The gate shows your app while it checks, so a slow server never holds it up, and it confirms the running release with `notifyApplicationReady` for you. Pass `title`, `color`, and `backgroundColor`, or draw your own screen with `renderProgress={(state) => ...}`.
+
+To build your own interface, use the hook and the progress component:
+
+```tsx
+import { RovqUpdateProgress, useRovqUpdate } from '@rovq/react-native';
+
+const { phase, progress, update, error, check } = useRovqUpdate({ mode: 'background' });
+// phase: idle, checking, upToDate, downloading, installing, ready, restarting, or error
+{
+  progress !== null && <RovqUpdateProgress progress={progress} variant="percent" />;
+}
+```
+
+A failure never throws. It ends in the `error` phase, and the app keeps running what it has.
+
+"Background" means while the app is open. When the user leaves the app, the system can pause the download, and it continues from where it stopped the next time the app runs.
+
+Publish updates with [`@rovq/cli`](https://www.npmjs.com/package/@rovq/cli).
+
+## Downloading only what changed
+
+A release published by `@rovq/cli` 0.2 lists its files, and the SDK downloads only those it does not already have. Files from the release before, and assets inside the app itself, are checked against the signed hash and reused. A change to one screen downloads only the bundle, however many images and sounds the app has.
+
+## 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,230 @@
+package com.rovq.engine
+
+import com.google.crypto.tink.subtle.Ed25519Verify
+import java.security.GeneralSecurityException
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+
+private const val PUBLIC_KEY_SIZE = 32
+private const val SIGNATURE_SIZE = 64
+private const val PLATFORM = "ANDROID"
+private val STREAM_FIELDS = setOf(
+    "version",
+    "releaseId",
+    "deploymentKey",
+    "platform",
+    "runtimeVersion",
+    "binaryVersion",
+    "sequence",
+    "mandatory",
+)
+
+// Version 1 names one ZIP package. Version 2 lists files. See docs/file-packages.md.
+private val ZIP_MANIFEST_FIELDS = STREAM_FIELDS + "package"
+private val FILES_MANIFEST_FIELDS = STREAM_FIELDS + "files"
+private val PACKAGE_FIELDS = setOf("hash", "size")
+private val FILE_FIELDS = setOf("path", "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}$")
+
+/** One file of a release made of files, from a verified manifest. */
+data class ManifestFile(val path: String, val hash: String, val size: Long)
+
+/** 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,
+    /** The ZIP package's hash. Empty for a release made of files. */
+    val packageHash: String,
+    /** The ZIP package's size, or all files together. */
+    val packageSize: Long,
+    /** Set for a release made of files, sorted by path. Null for a ZIP package. */
+    val files: List<ManifestFile>? = null,
+)
+
+/**
+ * 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)
+        val version = longField(root, "version")
+        if (version != 1L && version != 2L) invalid("Unknown manifest version")
+        requireOnlyFields(root, if (version == 1L) ZIP_MANIFEST_FIELDS else FILES_MANIFEST_FIELDS)
+
+        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")
+
+        // 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)
+
+        if (version == 2L) {
+            val files = fileList(root.opt("files"))
+            return VerifiedManifest(releaseId, sequence, mandatory, "", files.sumOf { it.size }, files)
+        }
+
+        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")
+
+        return VerifiedManifest(releaseId, sequence, mandatory, hash, size)
+    }
+
+    /**
+     * The same rules as a ZIP package, because each path is written to disk the same way.
+     * Sorted by UTF-16 code units, as JavaScript and Kotlin both sort, so one set of files has
+     * one signed form.
+     */
+    private fun fileList(value: Any?): List<ManifestFile> {
+        val list = value as? JSONArray ?: invalid("files must be an array")
+        if (list.length() == 0 || list.length() > PackageRules.MAX_ENTRIES) {
+            invalid("A package must have from 1 to ${PackageRules.MAX_ENTRIES} files")
+        }
+        val files = ArrayList<ManifestFile>(list.length())
+        val seen = HashSet<String>()
+        var total = 0L
+        for (index in 0 until list.length()) {
+            val entry = list.opt(index) as? JSONObject ?: invalid("Each file must be an object")
+            requireOnlyFields(entry, FILE_FIELDS)
+            val path = stringField(entry, "path")
+            PackageRules.findPathProblem(path)?.let { invalid("The file $path $it") }
+            val previous = files.lastOrNull()
+            if (previous != null && previous.path >= path) {
+                invalid("The files must be sorted by path, each path once")
+            }
+            if (!seen.add(PackageRules.pathIdentity(path))) {
+                invalid("The file $path differs from another only by letter case")
+            }
+            val hash = stringField(entry, "hash")
+            if (!HASH_PATTERN.matches(hash)) invalid("The file $path has a malformed hash")
+            val size = longField(entry, "size")
+            // Bounded before adding, so the total cannot overflow.
+            if (size < 0 || size > PackageRules.MAX_TOTAL_SIZE) invalid("The file $path has an invalid size")
+            total += size
+            if (total > PackageRules.MAX_TOTAL_SIZE) invalid("The files are larger than the allowed total")
+            files += ManifestFile(path, hash, size)
+        }
+        val bundle = files.firstOrNull { it.path == PackageRules.BUNDLE_FILE_NAME }
+            ?: invalid("The bundle file is missing")
+        if (bundle.size == 0L) invalid("The bundle file is empty")
+        return files
+    }
+
+    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)
+}