@scalebun/react-native 1.13.0 → 2.0.1

package/android/build.gradle

@@ -41,6 +41,10 @@ android {
         // Ship R8 keep-rules to consumer apps so release minification doesn't
         // strip the native modules / codegen TurboModule specs.
         consumerProguardFiles "consumer-rules.pro"
+        // Runs the OTA RSA verifier instrumentation test on-device
+        // (src/androidTest) — proves SHA256withRSA on the device provider across
+        // API levels. Affects only this library's connectedAndroidTest task.
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
     }
 
     sourceSets {
@@ -83,4 +87,8 @@ dependencies {
     // class is absent at runtime. Host apps that want push add the real
     // firebase-messaging dependency in their own app module — additive, no break.
     compileOnly 'com.google.firebase:firebase-messaging:23.4.1'
+
+    // On-device OTA verifier test only (src/androidTest) — not shipped to consumers.
+    androidTestImplementation 'androidx.test.ext:junit:1.1.5'
+    androidTestImplementation 'androidx.test:runner:1.5.2'
 }

package/android/src/androidTest/java/com/scalebun/rn/ota/ScaleBunOtaVerifierInstrumentedTest.kt

@@ -0,0 +1,112 @@
+package com.scalebun.rn.ota
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+
+/**
+ * On-device verification for SB-OTA-RSA-SHA256-V1 (PROMPT §22).
+ *
+ * Proves that the shared committed vector (packages/ota-protocol/fixtures — the
+ * SAME bytes the Node codec, backend, and JVM parity harness use) verifies with
+ * the DEVICE's `SHA256withRSA` provider and parses with the on-device codec, and
+ * that tampering / unknown keys are rejected. RSA verification + RSA KeyFactory
+ * ship on every supported Android API level, so this must pass on the repo's
+ * minSdk (24), on an API below 33, and on API 33+ — run it on each:
+ *
+ *   ./gradlew :scalebun_react-native:connectedAndroidTest   # per running emulator/AVD
+ *
+ * The constants below are copied verbatim from fixtures/vectors/full.json; the
+ * cross-repo parity harness keeps the codec byte-identical, so a drift here shows
+ * up as a verification failure.
+ */
+@RunWith(AndroidJUnit4::class)
+class ScaleBunOtaVerifierInstrumentedTest {
+
+    private val signedPayloadB64 =
+        "U0JPVEEwMDEAAQAAABRTQi1PVEEtUlNBLVNIQTI1Ni1WMQAAAAdTSEEtMjU2AAAAFXRlc3QtcnNhLTMwNzItMjAyNi0wMQAAAA5wcm9qX3Rlc3RfMDAwMQAAABVvcmcuc2NhbGVidW4ubGVnYXJhZ2UAAAANcmVsX2Z1bGxfMDAwMQAAAA5ibmRsX2Z1bGxfMDAwMQAAAAdhbmRyb2lkAAAABGZ1bGwAAAAFNC41LjkAAAAGMC43NC4xAAAAAjI0AAAAAAAAACoAAAAAaVW5AAAAAAAAAAAAAAAAAAAAAWD6bpV7WCc0zBI9NJ6rivyixtOu66jZ7EYSJniR99yQMwAAAAAAAAAA+m6Ve1gnNMwSPTSeq4r8osbTruuo2exGEiZ4kffckDM="
+    private val signatureB64 =
+        "jlC7GRLWKXku3cbqtODlFt+qn2CEmS3oHOr9QTopCCzEovUF5a2GRT0PQ5k2C5EX7UGGO0Sv6/WhkznKR9NVEZl6ed0KARHAY8zfwTjin3czx9jpwV9bfsLlxEoKNo9bPfIs3mc0VoHCWOp95hQAotG+GqEwYsXqPruZ43U87qWT0t9/a3QboX+07hPO5vI4fDZQuPeo3W1HmXPKbOB7QGSijtKgKwQNuJHz+etsVsQelDsDofRSpYV92XCheUWWHP7kZKFOCcYUXnVwJcdU0Jhej+22vAESRK2G0CXP3orXE4pASaA3y4wkBQgJAJkcTN/ic1/Wm5BLo7KH+ypK1eo0hnrrLNSh6E+St5NvxlTM3bmxwnwHkPMYVBuOT0fUJy+gbD1/1CPvKakL12vizKwWDYuhfcIGkQUTvP2zCxcqWLfmZ7ZGo6n6WXMX63Vz+IQG0tnx1cp6YqJVIgxqjskQ47sacsfS9QeV5LyJhvBQrDSbpqujo9la8dDzZfDN"
+    private val keyId = "test-rsa-3072-2026-01"
+    private val projectId = "proj_test_0001"
+    private val applicationId = "org.scalebun.legarage"
+
+    private val spkiPem =
+        "-----BEGIN PUBLIC KEY-----\n" +
+        "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAt3tfFTPE+lkEbFeYi6zE\n" +
+        "+uI+3oJl0HfKtGTh7sr7pSh/uPJq2giF0Uc09ux3Z0i4NlqpOyLmiIrVOgYcWcN+\n" +
+        "/pCl1mh6VmT7nYO3sEhL+HyaIaclCGxvHCJSsaVHH8qQyiCVUypWWKN0L38U4isN\n" +
+        "dJ2x+Wv7iLSZu3oM+ZDyGWCjRLE49jKNl0tfaQX6G1YoyBi1aEu5sWIQ6LjGE4IX\n" +
+        "1AJtOiNoaO9orjVgphA5FDKFFqguhEJrHoSXt3awHaeCYFm/mt+NI6k4sRf59UNx\n" +
+        "hdGh0kVL/6jZncclxueFafOOdfPf+jF3ylTczQhnID7Mg1PdmjXR7cfq7jDdjzfW\n" +
+        "VICJqGt+EhUd92pWrMTa5k3SDin3EetYGJsN7iKLbAl0D6Uy8RfE2mdsF2K6D3EP\n" +
+        "9waHN7vLURCF//TGy84FxPy7vbFgLO4oT07lxaopuGX7vOdONI8qLcFhEAJ9fRVN\n" +
+        "lqPWQGib0iAKE+gLl4CWZen674QZF39fGnOBEz7JsmDfAgMBAAE=\n" +
+        "-----END PUBLIC KEY-----\n"
+
+    private fun registry() = ScaleBunOtaKeyRegistry.fromJson(
+        JSONObject()
+            .put("projectId", projectId)
+            .put("keys", org.json.JSONArray().put(JSONObject().put("keyId", keyId).put("publicKey", spkiPem)))
+            .toString(),
+    )
+
+    private fun context(currentSequence: Long = 0L) = ExpectedContext(
+        projectId = projectId,
+        applicationId = applicationId,
+        currentSequence = currentSequence,
+        nowEpochSeconds = 1_767_225_600L + 60, // just after the vector's issuedAt
+    )
+
+    private fun envelope(payload: String = signedPayloadB64, sig: String = signatureB64) = JSONObject()
+        .put("protocol", OtaProtocol.SIGNATURE_ALGORITHM)
+        .put("keyId", keyId)
+        .put("signedPayload", payload)
+        .put("signature", sig)
+        .toString()
+
+    @Test
+    fun genuineReleaseVerifiesOnDevice() {
+        val v = ScaleBunOtaReleaseVerifier.verify(envelope(), context(), registry())
+        assertTrue("expected ok, got ${v.code}", v.ok)
+        assertEquals("bndl_full_0001", v.payload?.bundleId)
+        assertEquals(42L, v.payload?.releaseSequence)
+        assertEquals("android", v.payload?.platform)
+        // result == artifact hash for a full release
+        assertEquals(v.payload?.artifactSha256, v.payload?.resultArtifactSha256)
+    }
+
+    @Test
+    fun oneBytePayloadMutationRejected() {
+        val bad = signedPayloadB64.dropLast(2) + if (signedPayloadB64.endsWith("M=")) "N=" else "M="
+        val v = ScaleBunOtaReleaseVerifier.verify(envelope(payload = bad), context(), registry())
+        assertTrue(!v.ok)
+        // Either the flipped base64 fails to decode canonically or the signature fails.
+        assertTrue(v.code == OtaFailureCode.INVALID_SIGNATURE || v.code == OtaFailureCode.INVALID_BASE64)
+    }
+
+    @Test
+    fun unknownKeyRejected() {
+        val emptyReg = ScaleBunOtaKeyRegistry.fromJson(
+            JSONObject().put("projectId", projectId).put("keys", org.json.JSONArray()).toString(),
+        )
+        val v = ScaleBunOtaReleaseVerifier.verify(envelope(), context(), emptyReg)
+        assertEquals(OtaFailureCode.UNKNOWN_KEY_ID, v.code)
+    }
+
+    @Test
+    fun downgradeRejected() {
+        val v = ScaleBunOtaReleaseVerifier.verify(envelope(), context(currentSequence = 100L), registry())
+        assertEquals(OtaFailureCode.RELEASE_DOWNGRADE_REJECTED, v.code)
+    }
+
+    @Test
+    fun sha256WithRsaAvailableOnThisApiLevel() {
+        // The whole point of RSA over ed25519: this must not throw on any API level.
+        java.security.Signature.getInstance("SHA256withRSA")
+        java.security.KeyFactory.getInstance("RSA")
+    }
+}

package/android/src/main/java/com/scalebun/rn/ota/BundleDownloader.kt

@@ -58,6 +58,7 @@ internal object BundleDownloader {
      * bar overshoot 100% and walk backwards. Unknown is reported as unknown.
      */
     fun download(
+        context: android.content.Context,
         url: String,
         destination: File,
         onProgress: ((bytesRead: Long, totalBytes: Long) -> Unit)? = null,
@@ -79,6 +80,15 @@ internal object BundleDownloader {
                     setRequestProperty("Accept-Encoding", "gzip")
                 }
 
+                // Certificate pinning, when the host app ships pins. Checked after the
+                // handshake but before a single byte of the body is read, and before any
+                // redirect is followed, so an intercepted endpoint cannot serve content or
+                // bounce us somewhere else. No pins configured = no behaviour change.
+                val https = connection as? javax.net.ssl.HttpsURLConnection
+                if (https != null && !TlsPinning.verify(context, https, current.host)) {
+                  return false
+                }
+
                 val code = connection.responseCode
                 if (code == HttpURLConnection.HTTP_MOVED_PERM ||
                     code == HttpURLConnection.HTTP_MOVED_TEMP ||

package/android/src/main/java/com/scalebun/rn/ota/DeviceIntegrity.kt

@@ -0,0 +1,75 @@
+package com.scalebun.rn.ota
+
+import android.content.Context
+import android.os.Build
+import java.io.File
+
+/**
+ * Best-effort root detection.
+ *
+ * Deliberately modest in what it claims. Root detection is a signal, never a
+ * boundary: anything running with root can defeat any check made from inside the
+ * app, and a determined attacker with a rooted device has already won that
+ * argument. What it IS good for is telling an operator that a fleet's telemetry
+ * — crash rates, adoption, rollback rates — includes devices whose OTA slot is
+ * writable by other processes, and letting a security-sensitive host app decide
+ * to withhold updates on those devices.
+ *
+ * The checks are the cheap, well-understood ones: known su binaries, the
+ * test-keys build tag, and the presence of common management packages. No
+ * heuristics that produce false positives on ordinary devices, because a false
+ * positive here means a paying customer stops receiving updates.
+ */
+object DeviceIntegrity {
+
+    private val SU_PATHS = arrayOf(
+        "/system/bin/su",
+        "/system/xbin/su",
+        "/sbin/su",
+        "/system/su",
+        "/vendor/bin/su",
+        "/data/local/xbin/su",
+        "/data/local/bin/su",
+        "/system/sd/xbin/su",
+    )
+
+    private val MANAGEMENT_PACKAGES = arrayOf(
+        "com.topjohnwu.magisk",
+        "eu.chainfire.supersu",
+        "com.noshufou.android.su",
+        "com.koushikdutta.superuser",
+    )
+
+    /**
+     * Reasons this device looks rooted. Empty list = nothing detected, which is
+     * NOT the same as "device is clean" — see the class comment.
+     */
+    fun rootIndicators(context: Context): List<String> {
+        val found = mutableListOf<String>()
+
+        if (SU_PATHS.any { runCatching { File(it).exists() }.getOrDefault(false) }) {
+            found.add("su_binary_present")
+        }
+
+        // Release builds signed with Android's public test keys are development
+        // images, not retail firmware.
+        if (Build.TAGS?.contains("test-keys") == true) {
+            found.add("test_keys_build")
+        }
+
+        val pm = context.packageManager
+        for (pkg in MANAGEMENT_PACKAGES) {
+            val installed = runCatching {
+                @Suppress("DEPRECATION")
+                pm.getPackageInfo(pkg, 0)
+                true
+            }.getOrDefault(false)
+            if (installed) {
+                found.add("root_manager_installed")
+                break
+            }
+        }
+
+        return found
+    }
+}

package/android/src/main/java/com/scalebun/rn/ota/OtaProtocol.kt

@@ -0,0 +1,244 @@
+package com.scalebun.rn.ota
+
+import java.nio.ByteBuffer
+import java.nio.charset.CodingErrorAction
+import java.nio.charset.StandardCharsets
+import java.util.Base64
+
+/**
+ * SB-OTA-RSA-SHA256-V1 binary codec — the Android mirror of the TypeScript
+ * reference (`packages/ota-protocol/src/codec.ts`) and the JVM parity harness
+ * (`tools/rsa-ota-parity/RsaOtaParity.java`, which is run in CI to gate this
+ * transliteration byte-for-byte against the shared fixtures).
+ *
+ * Pure Kotlin + java.* only — no Android or RN dependency — so the parser is
+ * unit-testable off-device and cannot be neutered by the JS bundle it protects.
+ * See docs/ota/SB-OTA-RSA-SHA256-V1.md for the authoritative wire format.
+ */
+
+/** Stable verification failure codes (docs §6), surfaced to JS verbatim. */
+enum class OtaFailureCode {
+    INVALID_ENVELOPE,
+    INVALID_BASE64,
+    UNSUPPORTED_PROTOCOL,
+    UNSUPPORTED_SCHEMA,
+    UNSUPPORTED_SIGNATURE_ALGORITHM,
+    UNSUPPORTED_HASH_ALGORITHM,
+    UNKNOWN_KEY_ID,
+    INVALID_PUBLIC_KEY,
+    INVALID_SIGNATURE,
+    INVALID_SIGNED_PAYLOAD,
+    PROJECT_MISMATCH,
+    APPLICATION_MISMATCH,
+    PLATFORM_MISMATCH,
+    APP_VERSION_MISMATCH,
+    RUNTIME_VERSION_MISMATCH,
+    RELEASE_DOWNGRADE_REJECTED,
+    RELEASE_EXPIRED,
+    DOWNLOAD_FAILED,
+    DOWNLOAD_TOO_LARGE,
+    ARTIFACT_SIZE_MISMATCH,
+    ARTIFACT_HASH_MISMATCH,
+    PATCH_BASE_MISMATCH,
+    PATCH_RESULT_MISMATCH,
+    UNSAFE_ARCHIVE,
+    STAGING_FAILED,
+    ACTIVATION_FAILED,
+    INTERNAL_VERIFICATION_ERROR,
+}
+
+/** Carries a stable failure code out of the parser/verifier. Never leaks secrets. */
+class OtaVerifyException(val code: OtaFailureCode, message: String) : Exception("$code: $message")
+
+/** Decoded ScaleBunSignedReleaseV1 (hashes exposed as lowercase hex). */
+data class SignedRelease(
+    val signatureAlgorithm: String,
+    val hashAlgorithm: String,
+    val keyId: String,
+    val projectId: String,
+    val applicationId: String,
+    val releaseId: String,
+    val bundleId: String,
+    val platform: String,
+    val artifactType: String,
+    val targetAppVersion: String,
+    val targetRuntimeVersion: String,
+    val minimumSdkVersion: String,
+    val releaseSequence: Long,
+    val issuedAtEpochSeconds: Long,
+    val expiresAtEpochSeconds: Long,
+    val artifactSize: Long,
+    val artifactSha256: String,
+    val baseBundleId: String,
+    val baseArtifactSha256: String,
+    val resultArtifactSha256: String,
+)
+
+object OtaProtocol {
+    const val MAGIC = "SBOTA001"
+    const val SCHEMA_VERSION = 1
+    const val SIGNATURE_ALGORITHM = "SB-OTA-RSA-SHA256-V1"
+    const val HASH_ALGORITHM = "SHA-256"
+    const val MAX_SIGNED_PAYLOAD_BYTES = 8192
+    const val MAX_SIGNATURE_BYTES = 1024
+    const val MAX_STRING_FIELD_BYTES = 256
+    const val SHA256_LEN = 32
+    const val MAX_SAFE_UINT64 = 9007199254740991L // 2^53 - 1
+
+    private val MAGIC_BYTES = MAGIC.toByteArray(StandardCharsets.US_ASCII)
+
+    /**
+     * Strict, canonical standard-Base64 decode with a hard size cap enforced
+     * before allocation. Rejects non-canonical encodings by requiring the
+     * decode→re-encode round trip to reproduce the input exactly.
+     */
+    fun decodeBase64Strict(value: String?, maxBytes: Int, what: String): ByteArray {
+        if (value.isNullOrEmpty()) throw OtaVerifyException(OtaFailureCode.INVALID_BASE64, "$what: empty")
+        if (value.length > (maxBytes * 4) / 3 + 4) {
+            throw OtaVerifyException(OtaFailureCode.INVALID_BASE64, "$what: exceeds size limit")
+        }
+        if (value.length % 4 != 0 || !value.matches(Regex("^[A-Za-z0-9+/]*={0,2}$"))) {
+            throw OtaVerifyException(OtaFailureCode.INVALID_BASE64, "$what: not canonical base64")
+        }
+        val decoded = try {
+            Base64.getDecoder().decode(value)
+        } catch (e: IllegalArgumentException) {
+            throw OtaVerifyException(OtaFailureCode.INVALID_BASE64, "$what: invalid base64")
+        }
+        if (Base64.getEncoder().encodeToString(decoded) != value) {
+            throw OtaVerifyException(OtaFailureCode.INVALID_BASE64, "$what: non-canonical base64")
+        }
+        if (decoded.size > maxBytes) {
+            throw OtaVerifyException(OtaFailureCode.INVALID_BASE64, "$what: decoded exceeds limit")
+        }
+        return decoded
+    }
+
+    /** Parse ONLY enough to obtain the (still-unauthenticated) keyId (docs §5). */
+    fun peekKeyId(bytes: ByteArray): String {
+        if (bytes.size > MAX_SIGNED_PAYLOAD_BYTES) {
+            throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "payload too large")
+        }
+        val r = Reader(bytes)
+        if (!r.fixed(MAGIC_BYTES.size).contentEquals(MAGIC_BYTES)) {
+            throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "bad magic")
+        }
+        if (r.u16() != SCHEMA_VERSION) throw OtaVerifyException(OtaFailureCode.UNSUPPORTED_SCHEMA, "schema")
+        r.str("signatureAlgorithm")
+        r.str("hashAlgorithm")
+        val keyId = r.str("keyId")
+        if (keyId.isEmpty()) throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "empty keyId")
+        return keyId
+    }
+
+    /** Fully parse + validate an authenticated payload. */
+    fun parse(bytes: ByteArray): SignedRelease {
+        if (bytes.size > MAX_SIGNED_PAYLOAD_BYTES) {
+            throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "payload too large")
+        }
+        val r = Reader(bytes)
+        if (!r.fixed(MAGIC_BYTES.size).contentEquals(MAGIC_BYTES)) {
+            throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "bad magic")
+        }
+        if (r.u16() != SCHEMA_VERSION) throw OtaVerifyException(OtaFailureCode.UNSUPPORTED_SCHEMA, "schema")
+        val sigAlg = r.str("signatureAlgorithm")
+        if (sigAlg != SIGNATURE_ALGORITHM) throw OtaVerifyException(OtaFailureCode.UNSUPPORTED_SIGNATURE_ALGORITHM, sigAlg)
+        val hashAlg = r.str("hashAlgorithm")
+        if (hashAlg != HASH_ALGORITHM) throw OtaVerifyException(OtaFailureCode.UNSUPPORTED_HASH_ALGORITHM, hashAlg)
+
+        val keyId = r.str("keyId")
+        val projectId = r.str("projectId")
+        val applicationId = r.str("applicationId")
+        val releaseId = r.str("releaseId")
+        val bundleId = r.str("bundleId")
+        for (v in listOf(keyId, projectId, applicationId, releaseId, bundleId)) {
+            if (v.isEmpty()) throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "empty id")
+        }
+        val platform = r.str("platform")
+        if (platform != "android" && platform != "ios") {
+            throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "platform")
+        }
+        val artifactType = r.str("artifactType")
+        if (artifactType != "full" && artifactType != "patch") {
+            throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "artifactType")
+        }
+        val targetAppVersion = r.str("targetAppVersion")
+        val targetRuntimeVersion = r.str("targetRuntimeVersion")
+        val minimumSdkVersion = r.str("minimumSdkVersion")
+        val releaseSequence = r.u64()
+        val issuedAt = r.u64()
+        val expiresAt = r.u64()
+        val artifactSize = r.u64()
+        if (issuedAt == 0L) throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "issuedAt zero")
+        if (artifactSize == 0L) throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "artifactSize zero")
+        if (expiresAt != 0L && expiresAt < issuedAt) {
+            throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "expiresAt < issuedAt")
+        }
+        val artifactSha = r.fixed(SHA256_LEN)
+        val baseBundleId = r.str("baseBundleId")
+        val baseSha = r.lenBytes(SHA256_LEN, "baseArtifactSha256")
+        val resultSha = r.fixed(SHA256_LEN)
+        if (artifactType == "full") {
+            if (baseBundleId.isNotEmpty() || baseSha.isNotEmpty()) {
+                throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "full has base fields")
+            }
+        } else {
+            if (baseBundleId.isEmpty() || baseSha.size != SHA256_LEN) {
+                throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "patch missing base")
+            }
+        }
+        if (r.remaining() != 0) throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "trailing bytes")
+
+        return SignedRelease(
+            sigAlg, hashAlg, keyId, projectId, applicationId, releaseId, bundleId, platform, artifactType,
+            targetAppVersion, targetRuntimeVersion, minimumSdkVersion,
+            releaseSequence, issuedAt, expiresAt, artifactSize,
+            toHex(artifactSha), baseBundleId, if (baseSha.size == SHA256_LEN) toHex(baseSha) else "", toHex(resultSha),
+        )
+    }
+
+    fun toHex(bytes: ByteArray): String {
+        val sb = StringBuilder(bytes.size * 2)
+        for (b in bytes) sb.append("%02x".format(b))
+        return sb.toString()
+    }
+
+    private class Reader(val b: ByteArray) {
+        var pos = 0
+        private val utf8 = StandardCharsets.UTF_8.newDecoder()
+            .onMalformedInput(CodingErrorAction.REPORT)
+            .onUnmappableCharacter(CodingErrorAction.REPORT)
+
+        fun need(n: Int) {
+            if (n < 0 || pos + n > b.size) throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "truncated")
+        }
+        fun fixed(n: Int): ByteArray { need(n); val o = b.copyOfRange(pos, pos + n); pos += n; return o }
+        fun u16(): Int { val x = fixed(2); return ((x[0].toInt() and 0xff) shl 8) or (x[1].toInt() and 0xff) }
+        fun u32(): Long {
+            val x = fixed(4)
+            return ((x[0].toLong() and 0xff) shl 24) or ((x[1].toLong() and 0xff) shl 16) or
+                ((x[2].toLong() and 0xff) shl 8) or (x[3].toLong() and 0xff)
+        }
+        fun u64(): Long {
+            val x = fixed(8)
+            var v = 0L
+            for (i in 0 until 8) v = (v shl 8) or (x[i].toLong() and 0xff)
+            if (v < 0 || v > MAX_SAFE_UINT64) throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "uint64 out of range")
+            return v
+        }
+        fun lenBytes(max: Int, field: String): ByteArray {
+            val n = u32()
+            if (n > max) throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "$field length $n > $max")
+            return fixed(n.toInt())
+        }
+        fun str(field: String = "string"): String {
+            val raw = lenBytes(MAX_STRING_FIELD_BYTES, field)
+            return try {
+                utf8.reset().decode(ByteBuffer.wrap(raw)).toString()
+            } catch (e: Exception) {
+                throw OtaVerifyException(OtaFailureCode.INVALID_SIGNED_PAYLOAD, "$field: invalid UTF-8")
+            }
+        }
+        fun remaining(): Int = b.size - pos
+    }
+}

package/android/src/main/java/com/scalebun/rn/ota/ScaleBunOtaKeyRegistry.kt

@@ -0,0 +1,100 @@
+package com.scalebun.rn.ota
+
+import android.content.Context
+import org.json.JSONObject
+import java.security.KeyFactory
+import java.security.MessageDigest
+import java.security.interfaces.RSAPublicKey
+import java.security.spec.X509EncodedKeySpec
+import java.util.Base64
+
+/**
+ * Native trusted-key registry (docs §9). Trusted RSA public keys are EMBEDDED in
+ * the app package — never fetched over the OTA channel — so a compromised server
+ * cannot introduce a key the device will trust.
+ *
+ * Config is a JSON asset shipped in the APK (default `scalebun_ota_keys.json`):
+ *
+ * ```json
+ * { "projectId": "proj_abc",
+ *   "keys": [ { "keyId": "production-2026-01", "publicKey": "-----BEGIN PUBLIC KEY----- …" } ] }
+ * ```
+ *
+ * `publicKey` may be an SPKI PEM or bare base64 SPKI DER. Keys are validated as
+ * RSA with a modulus of at least 2048 bits; duplicates and malformed entries are
+ * rejected. An absent/empty asset yields an empty registry — verification then
+ * fails closed (UNKNOWN_KEY_ID), never open.
+ */
+class TrustedKey(
+    val keyId: String,
+    val publicKey: RSAPublicKey,
+    /** SHA-256 over the SPKI DER, lowercase hex. */
+    val fingerprint: String,
+)
+
+class ScaleBunOtaKeyRegistry private constructor(
+    val projectId: String,
+    private val byKeyId: Map<String, TrustedKey>,
+) {
+    fun get(keyId: String): TrustedKey? = byKeyId[keyId]
+    fun isEmpty(): Boolean = byKeyId.isEmpty()
+    fun keyIds(): Set<String> = byKeyId.keys
+
+    companion object {
+        const val DEFAULT_ASSET = "scalebun_ota_keys.json"
+
+        /** Load from an APK asset. Returns an empty registry if the asset is absent. */
+        fun fromAssets(context: Context, assetName: String = DEFAULT_ASSET): ScaleBunOtaKeyRegistry {
+            return try {
+                val json = context.assets.open(assetName).use { it.readBytes().toString(Charsets.UTF_8) }
+                fromJson(json)
+            } catch (_: java.io.FileNotFoundException) {
+                ScaleBunOtaKeyRegistry("", emptyMap())
+            }
+        }
+
+        fun fromJson(json: String): ScaleBunOtaKeyRegistry {
+            val root = JSONObject(json)
+            val projectId = root.optString("projectId", "")
+            val arr = root.optJSONArray("keys") ?: throw OtaVerifyException(
+                OtaFailureCode.INVALID_PUBLIC_KEY, "trusted-key config has no `keys` array",
+            )
+            val map = LinkedHashMap<String, TrustedKey>()
+            for (i in 0 until arr.length()) {
+                val entry = arr.getJSONObject(i)
+                val keyId = entry.optString("keyId", "").trim()
+                val pem = entry.optString("publicKey", "").trim()
+                if (keyId.isEmpty() || pem.isEmpty()) {
+                    throw OtaVerifyException(OtaFailureCode.INVALID_PUBLIC_KEY, "key entry missing keyId/publicKey")
+                }
+                if (map.containsKey(keyId)) {
+                    throw OtaVerifyException(OtaFailureCode.INVALID_PUBLIC_KEY, "duplicate keyId $keyId")
+                }
+                map[keyId] = parseKey(keyId, pem)
+            }
+            return ScaleBunOtaKeyRegistry(projectId, map)
+        }
+
+        private fun parseKey(keyId: String, pem: String): TrustedKey {
+            val b64 = pem.replace(Regex("-----[A-Z ]+-----"), "").replace(Regex("\\s"), "")
+            val der = try {
+                Base64.getDecoder().decode(b64)
+            } catch (e: IllegalArgumentException) {
+                throw OtaVerifyException(OtaFailureCode.INVALID_PUBLIC_KEY, "key $keyId: bad base64")
+            }
+            val key = try {
+                KeyFactory.getInstance("RSA").generatePublic(X509EncodedKeySpec(der))
+            } catch (e: Exception) {
+                throw OtaVerifyException(OtaFailureCode.INVALID_PUBLIC_KEY, "key $keyId: not a valid SPKI RSA key")
+            }
+            if (key !is RSAPublicKey) {
+                throw OtaVerifyException(OtaFailureCode.INVALID_PUBLIC_KEY, "key $keyId: not RSA")
+            }
+            if (key.modulus.bitLength() < 2048) {
+                throw OtaVerifyException(OtaFailureCode.INVALID_PUBLIC_KEY, "key $keyId: modulus < 2048 bits")
+            }
+            val fp = MessageDigest.getInstance("SHA-256").digest(der)
+            return TrustedKey(keyId, key, OtaProtocol.toHex(fp))
+        }
+    }
+}