@shipvo/runtime 0.1.4 → 0.1.5

package/README.md

@@ -28,15 +28,38 @@ Runtime.markHealthy();                   // call once the first screen rendered
 
 `shipvo init` wires all of this for you.
 
-## Events to forward
+## Events
 
-`Runtime.consumeEvents()` returns strings such as `verify_failed:<release>`. Forward `crash_loop_revert`, `rolled_back` and `verify_failed` to telemetry (`POST /t`), once per event. The sample app does this in `apps/tide-and-tackle/src/runtimeEvents.ts`. `verify_failed` is reported under the failed release id. A rejected or corrupt release then shows on the server, not only as repeated downloads.
+The runtime reports refused and reverted releases for you. `Runtime.markHealthy()` and every `Runtime.checkForUpdate()` drain the device's event queue and send each event to `POST {baseUrl}/t`, using `baseUrl` and `appId` from `expo.extra.shipvo`. A refusal found during a background check is reported in the same session, without a restart.
 
-The runtime does not emit `download_failed` yet. The sample app and the control plane accept it, so it can be forwarded once the runtime raises it.
+Forwarded events: `crash_loop_revert`, `rolled_back`, `verify_failed`, `download_failed`, `hermes_bytecode_mismatch`, `native_module_missing`, `native_module_version`. `verify_failed`, `download_failed` and `hermes_bytecode_mismatch` are reported under the failed release id. The native-module reasons arrive as `pointer_rejected:<reason>` and are reported under the reason name. Sending is best effort: a failed send never throws and never blocks.
 
-`Runtime.consumeEvents()` can also return `pointer_rejected:<reason>` on Android when the control plane says this shell cannot run the newest release. It is queued once per reason. `/t` accepts `hermes_bytecode_mismatch`, `native_module_missing` and `native_module_version`. The sample app forwards the two native-module reasons under those names. `hermes_bytecode_mismatch` is its own event and carries a release id.
+```ts
+import { reportRuntimeEvents, onRuntimeEvents } from "@shipvo/runtime";
+reportRuntimeEvents();                       // drain and send now (markHealthy and checkForUpdate already do)
+onRuntimeEvents((events) => console.log(events)); // see the drained strings, for a log
+```
+
+To turn the automatic report off, pass `reportEvents: false` to the config plugin (it lands in `expo.extra.shipvo`), and call `reportRuntimeEvents()` yourself. `forwardRuntimeEvents(events, send)` and `FORWARDED_EVENTS` are also exported for custom senders. If you call `Runtime.consumeEvents()` yourself, you take events away from the report.
+
+The runtime does not emit `download_failed` yet. The control plane accepts it.
+
+## Signed telemetry
+
+Call `enableSignedTelemetry` once at startup. The install registers once, keeps a secret key in your storage, and then signs each report. If registration fails, reports go out unsigned and the next launch tries again.
+
+```ts
+import { enableSignedTelemetry } from "@shipvo/runtime";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+await enableSignedTelemetry({
+  storage: AsyncStorage,
+  registerUrl: "https://cp.example.com/t/register",
+  // crypto: { randomBytes, hmacSha256 }  // React Native has no crypto.subtle, so pass your own
+});
+```
 
-Events are read at launch. A `verify_failed` raised during `checkForUpdate` is reported on the next cold start.
+The sent body is the unsigned JSON with its closing `}` replaced by `,"sig":"<hex>"}`. The HMAC-SHA256 covers the unsigned JSON, closing `}` included. A second call replaces the first identity.
 
 ## Crash after `markHealthy`
 

package/android/build.gradle

@@ -13,10 +13,16 @@ android {
     versionName "0.0.1"
     consumerProguardFiles "proguard-rules.pro"
   }
+  // The shared key rotation vectors (also used by the CLI and iOS tests) are read as test resources.
+  sourceSets {
+    test.resources.srcDirs += ["../test-vectors"]
+  }
 }
 
 dependencies {
   testImplementation 'junit:junit:4.13.2'
+  // The Android SDK's org.json is a stub in JVM unit tests.
+  testImplementation 'org.json:json:20231013'
   implementation 'com.facebook.react:react-android'
   // Ed25519 verification on Android 7+ (no platform Ed25519 before API 33). Pure Java, ~60 KB.
   implementation 'net.i2p.crypto:eddsa:0.3.0'

package/android/src/main/java/dev/shipvo/runtime/Clock.kt

@@ -0,0 +1,9 @@
+package dev.shipvo.runtime
+
+/** Source of wall-clock time for rotation checks. Rotation code never reads the system time directly. */
+internal fun interface Clock {
+  /** Milliseconds since the Unix epoch. */
+  fun now(): Long
+
+  object Wall : Clock { override fun now() = System.currentTimeMillis() }
+}

package/android/src/main/java/dev/shipvo/runtime/PointerQuery.kt

@@ -8,11 +8,12 @@ internal object PointerQuery {
 
   private fun enc(v: String) = URLEncoder.encode(v, "UTF-8")
 
-  /** `hbc` is "96,98"; `nm` is "name@1.2.3,@scope/pkg@2.0.0". A blank value is treated as not declared. */
-  fun url(base: String, app: String, shellMajor: Int, band: String, hbc: String?, nm: String?): String {
+  /** `hbc` is "96,98"; `hbe` is the engine build id "250829098.0.10"; `nm` is "name@1.2.3,@scope/pkg@2.0.0". A blank value is treated as not declared. */
+  fun url(base: String, app: String, shellMajor: Int, band: String, hbc: String?, nm: String?, hbe: String? = null): String {
     val q = ArrayList<String>()
     hbc?.split(',')?.map { it.trim() }?.filter { it.isNotEmpty() }?.takeIf { it.isNotEmpty() }
       ?.let { q += "hbc=" + it.joinToString(",") { v -> enc(v) } }
+    hbe?.trim()?.takeIf { it.isNotEmpty() }?.let { q += "hbe=" + enc(it) }
     nm?.split(',')?.map { it.trim() }?.filter { it.isNotEmpty() }?.takeIf { it.isNotEmpty() }
       ?.let { q += "nm=" + it.joinToString(",") { v -> enc(v) } }
     val path = "$base/p/$app/$shellMajor/$band.json"

package/android/src/main/java/dev/shipvo/runtime/Rotation.kt

@@ -0,0 +1,134 @@
+package dev.shipvo.runtime
+
+import android.util.Base64
+import org.json.JSONArray
+import org.json.JSONObject
+import java.text.SimpleDateFormat
+import java.util.Locale
+import java.util.TimeZone
+
+/** What Rotation needs from storage. [commit] writes all three values in one atomic step. */
+internal interface RotationState {
+  val storedReleaseKey: String?
+  val storedSequence: Long
+  val storedPinnedKey: String?
+  val storedPending: String?
+  fun commit(releaseKey: String?, sequence: Long, pinnedKey: String?, pending: String?)
+}
+
+/**
+ * Root-signed release key rotation (docs/design/key-rotation.md, sections 3 to 9).
+ * A statement is an envelope {body, signature}; the signature is by the pinned root key over the exact body string.
+ */
+internal class Rotation(
+  private val state: RotationState,
+  private val appId: String,
+  private val pinnedReleaseKey: String,
+  private val rootKey: String,
+  private val minSequence: Long,
+  private val clock: Clock = Clock.Wall,
+  private val verify: (ByteArray, String, String) -> Boolean = Verify::ed25519,
+  private val decode: (String) -> ByteArray = { Base64.decode(it, Base64.DEFAULT) },
+) {
+  class Result(val ok: Boolean, val reason: String? = null)
+
+  private class Stmt(val body: String, val signature: String, val sequence: Long, val newKey: String, val validFrom: Long)
+
+  /** Signature checks made so far (tests count them). */
+  var signatureChecks = 0
+    private set
+
+  /** The release key pointers are verified against: the stored one, or the pinned one when nothing usable is stored. */
+  fun currentReleaseKey(): String {
+    val k = state.storedReleaseKey
+    return if (k != null && state.storedPinnedKey == pinnedReleaseKey && keyOk(k)) k else pinnedReleaseKey
+  }
+
+  fun effectiveSequence(): Long = maxOf(state.storedSequence, minSequence)
+
+  /** Applies due pending statements. Run on launch and before every pointer check. */
+  fun applyDue() { handle(null) }
+
+  /**
+   * Handles a delivered `rotations` array (null for none). Returns one result per envelope; empty when the array
+   * is refused whole. Verdicts are against the state before this delivery.
+   */
+  fun handle(rotations: JSONArray?): List<Result> {
+    if (rotations != null && rotations.length() > MAX) return emptyList()
+    val effective = effectiveSequence()
+    val known = HashMap<Long, Stmt>()
+    for (s in loadPending()) if (s.sequence > effective) known.putIfAbsent(s.sequence, s)
+    val results = ArrayList<Result>()
+    if (rotations != null) for (i in 0 until rotations.length()) {
+      val env = rotations.optJSONObject(i)
+      val body = env?.opt("body") as? String
+      val sig = env?.opt("signature") as? String
+      if (body == null || sig == null || body.toByteArray(Charsets.UTF_8).size > MAX_BODY) { results.add(Result(false, "malformed")); continue }
+      val r = check(body, sig, effective)
+      if (r is Stmt) {
+        // Same sequence twice: the first accepted stays.
+        if (known.containsKey(r.sequence)) results.add(Result(false, "replay")) else { known[r.sequence] = r; results.add(Result(true)) }
+      } else results.add(r as Result)
+    }
+    commitState(known.values.sortedBy { it.sequence }, effective)
+    return results
+  }
+
+  /** Section 3 rules 1 to 5 in order. Returns a [Stmt] when valid, else a [Result]. */
+  private fun check(body: String, sig: String, effective: Long, reload: Boolean = false): Any {
+    signatureChecks++
+    if (!verify(body.toByteArray(Charsets.UTF_8), sig, rootKey)) return Result(false, "bad_signature")
+    val j = try { JSONObject(body) } catch (_: Exception) { return Result(false, "malformed") }
+    if (j.opt("type") != "key-rotation") return Result(false, "bad_type")
+    if (j.opt("appId") != appId) return Result(false, "wrong_app")
+    val seq = j.opt("sequence").let { if (it is Int) it.toLong() else it as? Long } ?: return Result(false, "malformed")
+    if (seq < 1) return Result(false, "malformed")
+    if (seq <= effective) return Result(false, "replay")
+    val validFrom = (j.opt("validFrom") as? String)?.let { parseTime(it) } ?: return Result(false, "malformed")
+    if (!reload && validFrom > clock.now() + NINETY_DAYS_MS) return Result(false, "too_far")
+    val newKey = j.opt("newKey") as? String
+    if (newKey == null || !keyOk(newKey)) return Result(false, "bad_key")
+    return Stmt(body, sig, seq, newKey, validFrom)
+  }
+
+  /** Section 7: apply the due statement with the highest sequence, keep the later ones, at most 8. */
+  private fun commitState(all: List<Stmt>, effective: Long) {
+    val now = clock.now()
+    val due = all.filter { it.validFrom <= now }.maxByOrNull { it.sequence }
+    val keep = (if (due == null) all else all.filter { it.sequence > due.sequence }).take(MAX)
+    val pending = if (keep.isEmpty()) null else JSONArray(keep.map { JSONObject().put("body", it.body).put("signature", it.signature) }).toString()
+    val changed = due != null || pending != state.storedPending || state.storedPinnedKey != pinnedReleaseKey
+    if (!changed) return
+    // A different pin than the one that wrote the state: drop the stored key, keep the sequence (design section 4).
+    val key = due?.newKey ?: if (state.storedPinnedKey == pinnedReleaseKey) state.storedReleaseKey else null
+    state.commit(key, maxOf(due?.sequence ?: 0L, state.storedSequence), pinnedReleaseKey, pending)
+  }
+
+  /** A corrupt or unverifiable pending list is cleared by the next commit; key and sequence stay. */
+  private fun loadPending(): List<Stmt> {
+    val raw = state.storedPending ?: return emptyList()
+    return try {
+      val arr = JSONArray(raw)
+      if (arr.length() > MAX) return emptyList()
+      val out = ArrayList<Stmt>()
+      for (i in 0 until arr.length()) {
+        val o = arr.getJSONObject(i)
+        val r = check(o.getString("body"), o.getString("signature"), 0, reload = true)
+        if (r is Stmt) out.add(r)
+      }
+      out
+    } catch (_: Exception) { emptyList() }
+  }
+
+  private fun keyOk(k: String): Boolean = try { decode(k).size == 32 } catch (_: Exception) { false }
+
+  private fun parseTime(s: String): Long? = try {
+    SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US).apply { timeZone = TimeZone.getTimeZone("UTC"); isLenient = false }.parse(s)?.time
+  } catch (_: Exception) { null }
+
+  companion object {
+    const val MAX = 8
+    const val MAX_BODY = 1024
+    const val NINETY_DAYS_MS = 90L * 24 * 60 * 60 * 1000
+  }
+}

package/android/src/main/java/dev/shipvo/runtime/ShipvoRuntimeModule.kt

@@ -128,8 +128,10 @@ class ShipvoRuntimeModule : Module() {
   private fun check(): Map<String, Any?> {
     val s = Store(ctx)
     require(s.baseUrl.isNotEmpty() && s.publicKey.isNotEmpty() && s.appId.isNotEmpty()) { "runtime not configured" }
+    val rotation = s.rotation()
+    rotation.applyDue() // due root-signed key rotations apply before any pointer is checked
     val known = maxOf(s.currentRelease, s.pendingRelease, s.blockedRelease)
-    val conn = http(PointerQuery.url(s.baseUrl, s.appId, s.shellMajor, s.band, s.hermesBytecodeVersions, s.nativeModules), if (known > 0) "\"$known\"" else null)
+    val conn = http(PointerQuery.url(s.baseUrl, s.appId, s.shellMajor, s.band, s.hermesBytecodeVersions, s.nativeModules, s.hermesEngine), if (known > 0) "\"$known\"" else null)
     val code = conn.responseCode
     if (code == 404) {
       // The shell cannot run the newest release. Keep the current one and say why.
@@ -144,9 +146,11 @@ class ShipvoRuntimeModule : Module() {
     val envelope = JSONObject(conn.inputStream.bufferedReader().use { it.readText() })
     conn.disconnect()
 
+    // Root-signed rotation statements ride along with the pointer; handle them before the pointer is verified.
+    envelope.optJSONArray("rotations")?.let { rotation.handle(it) }
     val t0 = SystemClock.elapsedRealtime()
     val bodyStr = envelope.getString("body")
-    require(Verify.ed25519(bodyStr.toByteArray(Charsets.UTF_8), envelope.getString("signature"), s.publicKey)) { "pointer signature invalid" }
+    require(Verify.ed25519(bodyStr.toByteArray(Charsets.UTF_8), envelope.getString("signature"), rotation.currentReleaseKey())) { "pointer signature invalid" }
     val body = JSONObject(bodyStr)
     require(body.getString("app_id") == s.appId && body.getInt("shell_major") == s.shellMajor) { "pointer for another app/shell" }
     val release = body.getInt("release")

package/android/src/main/java/dev/shipvo/runtime/Store.kt

@@ -8,7 +8,7 @@ import java.io.File
 import kotlin.random.Random
 
 /** Persistent runtime state. All bundle decisions go through here so the host handler and module agree. */
-internal class Store(private val ctx: Context) : BootCounts {
+internal class Store(private val ctx: Context) : BootCounts, RotationState {
   private val p: SharedPreferences = ctx.getSharedPreferences("shipvo.runtime", Context.MODE_PRIVATE)
   val dir: File get() = File(ctx.filesDir, "shipvo").apply { mkdirs() }
 
@@ -66,6 +66,22 @@ internal class Store(private val ctx: Context) : BootCounts {
   override var unhealthyBoots: Int get() = p.getInt("unhealthy_boots", 0); set(v) { p.edit().putInt("unhealthy_boots", v).commit() }
   override var firstUnhealthyAt: Long get() = p.getLong("first_unhealthy_at", 0); set(v) { p.edit().putLong("first_unhealthy_at", v).commit() }
 
+  override val storedReleaseKey: String? get() = p.getString("rotation.releaseKey", null)
+  override val storedSequence: Long get() = try { p.getLong("rotation.sequence", 0) } catch (_: ClassCastException) { 0 }
+  override val storedPinnedKey: String? get() = p.getString("rotation.pinnedKey", null)
+  override val storedPending: String? get() = p.getString("rotation.pending", null)
+  /** One commit() writes key, sequence, pinned key and pending list together. */
+  override fun commit(releaseKey: String?, sequence: Long, pinnedKey: String?, pending: String?) {
+    p.edit().apply {
+      if (releaseKey != null) putString("rotation.releaseKey", releaseKey) else remove("rotation.releaseKey")
+      putLong("rotation.sequence", sequence)
+      if (pinnedKey != null) putString("rotation.pinnedKey", pinnedKey) else remove("rotation.pinnedKey")
+      if (pending != null) putString("rotation.pending", pending) else remove("rotation.pending")
+    }.commit()
+  }
+  /** Key rotation for this shell: root-signed statements can replace the release key (docs/design/key-rotation.md). */
+  fun rotation(clock: Clock = Clock.Wall) = Rotation(this, appId, publicKey, rootKey, minSequence, clock)
+
   fun addEvent(e: String) {
     val list = p.getString("events", "")!!.split('\n').filter { it.isNotBlank() }.takeLast(49) + e
     p.edit().putString("events", list.joinToString("\n")).commit()
@@ -88,9 +104,15 @@ internal class Store(private val ctx: Context) : BootCounts {
   } catch (_: Exception) { null }
   val baseUrl: String get() = (meta("dev.shipvo.BASE_URL") ?: "").trimEnd('/')
   val publicKey: String get() = meta("dev.shipvo.PUBLIC_KEY") ?: ""
+  /** Root public key that signs rotation statements. Empty when the shell does not declare one: rotation is then off. */
+  val rootKey: String get() = meta("dev.shipvo.ROOT_KEY") ?: ""
+  /** Highest rotation sequence that existed when this shell was built. */
+  val minSequence: Long get() = metaAny("dev.shipvo.MIN_SEQUENCE")?.toLongOrNull() ?: 0
   val appId: String get() = meta("dev.shipvo.APP_ID") ?: ""
   /** Hermes bytecode versions this shell runs, e.g. "96,98". Null when the shell does not declare them. */
   val hermesBytecodeVersions: String? get() = metaAny("dev.shipvo.HERMES_BYTECODE_VERSIONS")?.takeIf { it.isNotBlank() }
+  /** Hermes engine build id this shell runs, e.g. "250829098.0.10". Null when the shell does not declare it. */
+  val hermesEngine: String? get() = metaAny("dev.shipvo.HERMES_ENGINE")?.takeIf { it.isNotBlank() }
   /** Native modules in this shell, e.g. "react-native-mmkv@3.1.0,@scope/pkg@1.0.0". Null when not declared. */
   val nativeModules: String? get() = metaAny("dev.shipvo.NATIVE_MODULES")?.takeIf { it.isNotBlank() }
   val shellMajor: Int get() = (meta("dev.shipvo.SHELL_MAJOR") ?: "1").toIntOrNull() ?: 1

package/android/src/test/java/dev/shipvo/runtime/PointerQueryTest.kt

@@ -15,6 +15,9 @@ class PointerQueryTest {
   @Test fun queryWhenDeclared() {
     assertEquals("https://x.dev/p/app/1/b2.json?hbc=96,98", url("96,98", null))
     assertEquals("https://x.dev/p/app/1/b2.json?hbc=96&nm=a%401.0.0", url("96", "a@1.0.0"))
+    assertEquals("https://x.dev/p/app/1/b2.json?hbc=96&hbe=250829098.0.10&nm=a%401.0.0", PointerQuery.url("https://x.dev", "app", 1, "b2", "96", "a@1.0.0", "250829098.0.10"))
+    assertEquals("https://x.dev/p/app/1/b2.json?hbe=1.2.3", PointerQuery.url("https://x.dev", "app", 1, "b2", null, null, " 1.2.3 "))
+    assertEquals("https://x.dev/p/app/1/b2.json", PointerQuery.url("https://x.dev", "app", 1, "b2", null, null, " "))
   }
 
   @Test fun scopedNamesAreEncoded() {

package/android/src/test/java/dev/shipvo/runtime/RotationTest.kt

@@ -0,0 +1,141 @@
+package dev.shipvo.runtime
+
+import net.i2p.crypto.eddsa.EdDSAEngine
+import net.i2p.crypto.eddsa.EdDSAPrivateKey
+import net.i2p.crypto.eddsa.EdDSAPublicKey
+import net.i2p.crypto.eddsa.spec.EdDSANamedCurveTable
+import net.i2p.crypto.eddsa.spec.EdDSAPrivateKeySpec
+import net.i2p.crypto.eddsa.spec.EdDSAPublicKeySpec
+import org.json.JSONArray
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import java.security.MessageDigest
+import java.text.SimpleDateFormat
+import java.util.Base64
+import java.util.Locale
+import java.util.TimeZone
+
+/** Runs the shared vectors (packages/runtime/test-vectors/rotation.json) against Rotation with an in-memory store. */
+class RotationTest {
+  private class Mem : RotationState {
+    override var storedReleaseKey: String? = null
+    override var storedSequence = 0L
+    override var storedPinnedKey: String? = null
+    override var storedPending: String? = null
+    var commits = 0
+    override fun commit(releaseKey: String?, sequence: Long, pinnedKey: String?, pending: String?) {
+      storedReleaseKey = releaseKey; storedSequence = sequence; storedPinnedKey = pinnedKey; storedPending = pending; commits++
+    }
+  }
+
+  private val spec = EdDSANamedCurveTable.getByName(EdDSANamedCurveTable.ED_25519)
+  private fun dec(s: String) = Base64.getDecoder().decode(s)
+  private fun verify(m: ByteArray, sig: String, key: String): Boolean = try {
+    val e = EdDSAEngine(MessageDigest.getInstance(spec.hashAlgorithm))
+    e.initVerify(EdDSAPublicKey(EdDSAPublicKeySpec(dec(key), spec)))
+    e.update(m); e.verify(dec(sig))
+  } catch (_: Exception) { false }
+  private fun sign(m: ByteArray, seed: String): String {
+    val e = EdDSAEngine(MessageDigest.getInstance(spec.hashAlgorithm))
+    e.initSign(EdDSAPrivateKey(EdDSAPrivateKeySpec(dec(seed), spec)))
+    e.update(m); return Base64.getEncoder().encodeToString(e.sign())
+  }
+  private fun time(s: String) = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US).apply { timeZone = TimeZone.getTimeZone("UTC") }.parse(s)!!.time
+
+  private val vectors = JSONObject(javaClass.classLoader!!.getResourceAsStream("rotation.json")!!.bufferedReader().readText())
+  private val keys = vectors.getJSONObject("keys")
+  private fun pub(name: String) = keys.getJSONObject(name).getString("publicKey")
+
+
+  private fun make(state: Mem, clock: Array<Long>, count: IntArray) = Rotation(
+    state, vectors.getString("appId"), pub("K1"), vectors.getJSONObject("root").getString("publicKey"),
+    vectors.getLong("minSequence"), { clock[0] }, { m, s, k -> count[0]++; verify(m, s, k) }, { dec(it) })
+
+  @Test fun sharedVectors() {
+    val cases = vectors.getJSONArray("cases")
+    assertEquals(14, cases.length())
+    for (c in 0 until cases.length()) {
+      val case = cases.getJSONObject(c)
+      val name = "case ${case.getInt("id")}: ${case.getString("name")}"
+      val state = Mem(); val clock = arrayOf(time(vectors.getString("startTime"))); val count = intArrayOf(0)
+      var rot = make(state, clock, count)
+      val steps = case.getJSONArray("steps")
+      for (i in 0 until steps.length()) {
+        val step = steps.getJSONObject(i)
+        clock[0] = time(step.getString("now"))
+        if (step.optBoolean("relaunch")) rot = make(state, clock, count) // new process, same stored state
+        count[0] = 0
+        val results = rot.handle(step.getJSONArray("deliver"))
+        if (step.optBoolean("rejectedWhole")) {
+          assertTrue("$name step $i whole", results.isEmpty())
+          assertEquals("$name step $i signature checks", step.getInt("signatureChecks"), count[0])
+        } else {
+          val want = step.getJSONArray("verify")
+          assertEquals("$name step $i result count", want.length(), results.size)
+          for (k in 0 until want.length()) {
+            val w = want.getJSONObject(k)
+            assertEquals("$name step $i env $k", w.getBoolean("ok"), results[k].ok)
+            if (!w.getBoolean("ok")) assertEquals("$name step $i env $k reason", w.getString("reason"), results[k].reason)
+          }
+        }
+        val expect = step.getJSONObject("expect")
+        assertEquals("$name step $i key", pub(expect.getString("currentKey")), rot.currentReleaseKey())
+        assertEquals("$name step $i sequence", expect.getLong("sequence"), rot.effectiveSequence())
+        val pending = state.storedPending?.let { JSONArray(it) } ?: JSONArray()
+        val seqs = (0 until pending.length()).map { JSONObject(pending.getJSONObject(it).getString("body")).getLong("sequence") }
+        val wantSeqs = expect.getJSONArray("pending").let { a -> (0 until a.length()).map { a.getLong(it) } }
+        assertEquals("$name step $i pending", wantSeqs, seqs)
+      }
+    }
+  }
+
+  private fun firstDelivery(caseId: Int): JSONArray {
+    val cases = vectors.getJSONArray("cases")
+    for (i in 0 until cases.length()) if (cases.getJSONObject(i).getInt("id") == caseId)
+      return cases.getJSONObject(i).getJSONArray("steps").getJSONObject(0).getJSONArray("deliver")
+    error("no case $caseId")
+  }
+
+  @Test fun pointersFollowTheRotatedKey() {
+    val state = Mem(); val clock = arrayOf(time(vectors.getString("startTime"))); val count = intArrayOf(0)
+    val rot = make(state, clock, count)
+    val pointer = "{\"release\":2}".toByteArray()
+    val bySeed = { n: String -> sign(pointer, keys.getJSONObject(n).getString("seed")) }
+    assertTrue(verify(pointer, bySeed("K1"), rot.currentReleaseKey()))
+    assertTrue(rot.handle(firstDelivery(1))[0].ok)
+    assertTrue(verify(pointer, bySeed("K2"), rot.currentReleaseKey()))
+    assertFalse(verify(pointer, bySeed("K1"), rot.currentReleaseKey()))
+  }
+
+  @Test fun corruptPendingIsClearedAndKeyAndSequenceKept() {
+    val state = Mem(); val clock = arrayOf(time(vectors.getString("startTime"))); val count = intArrayOf(0)
+    val rot = make(state, clock, count)
+    assertTrue(rot.handle(firstDelivery(1))[0].ok)
+    state.storedPending = "not json {"
+    rot.applyDue()
+    assertEquals(null, state.storedPending)
+    assertEquals(1L, state.storedSequence)
+    assertEquals(pub("K2"), rot.currentReleaseKey())
+  }
+
+  @Test fun newPinDiscardsStoredKeyButKeepsSequence() {
+    val state = Mem(); val clock = arrayOf(time(vectors.getString("startTime"))); val count = intArrayOf(0)
+    assertTrue(make(state, clock, count).handle(firstDelivery(1))[0].ok)
+    // A new shell build pins K3 and MIN_SEQUENCE 1: the stored K2 is dropped, and statement 1 cannot come back.
+    val rot = Rotation(state, "tide", pub("K3"), vectors.getJSONObject("root").getString("publicKey"), 1, { clock[0] }, ::verify, { dec(it) })
+    assertEquals(pub("K3"), rot.currentReleaseKey())
+    assertFalse(rot.handle(firstDelivery(1))[0].ok)
+    assertEquals(pub("K3"), rot.currentReleaseKey())
+    assertEquals(1L, state.storedSequence)
+  }
+
+  @Test fun noRootKeyMeansNothingApplies() {
+    val state = Mem(); val clock = arrayOf(time(vectors.getString("startTime")))
+    val rot = Rotation(state, "tide", pub("K1"), "", 0, { clock[0] }, ::verify, { dec(it) })
+    assertFalse(rot.handle(firstDelivery(1))[0].ok)
+    assertEquals(pub("K1"), rot.currentReleaseKey())
+  }
+}

package/app.plugin.js

@@ -15,6 +15,15 @@ function formatBytecodeVersions(value) {
   return value.join(",");
 }
 
+// Returns the engine build id (like "250829098.0.10"), or undefined when the prop is omitted.
+function formatHermesEngine(value) {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || !/^\d+\.\d+\.\d+$/.test(value.trim())) {
+    throw new Error(`@shipvo/runtime: hermesEngine must look like 250829098.0.10, got ${JSON.stringify(value)}`);
+  }
+  return value.trim();
+}
+
 // Returns "name@version,..." for the native modules, or undefined when the prop is omitted.
 function formatNativeModules(value) {
   if (value === undefined) return undefined;
@@ -35,18 +44,41 @@ function formatNativeModules(value) {
     .join(",");
 }
 
+// Returns the root key, or undefined when the prop is omitted. Must be base64 of 32 bytes (an Ed25519 public key).
+function checkRootKey(value) {
+  if (value === undefined) return undefined;
+  const ok = typeof value === "string" && /^[A-Za-z0-9+/]+={0,2}$/.test(value) && value.length % 4 === 0 && Buffer.from(value, "base64").length === 32;
+  if (!ok) throw new Error("@shipvo/runtime: rootKey must be a base64 string that decodes to 32 bytes");
+  return value;
+}
+
+// Returns the minimum rotation sequence, or undefined when the prop is omitted.
+function checkMinSequence(value) {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`@shipvo/runtime: minSequence must be a non-negative integer, got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
 module.exports = function withShipvo(config, props) {
-  const { baseUrl, publicKey, appId, shellMajor = 1 } = props || {};
+  const { baseUrl, publicKey, appId, shellMajor = 1, rootKey, minSequence } = props || {};
   if (!baseUrl || !publicKey || !appId) throw new Error("@shipvo/runtime: baseUrl, publicKey and appId are required");
+  checkRootKey(rootKey);
+  checkMinSequence(minSequence);
+  // minSequence is the replay floor for rotation statements; without a root key no statement is accepted, so it would do nothing.
+  if (minSequence !== undefined && rootKey === undefined) throw new Error("@shipvo/runtime: minSequence needs rootKey");
   const hbc = formatBytecodeVersions(props.hermesBytecodeVersions);
+  const hbe = formatHermesEngine(props.hermesEngine);
   const nm = formatNativeModules(props.nativeModules);
-  config.extra = { ...(config.extra ?? {}), shipvo: { baseUrl, appId, shellMajor } };
+  config.extra = { ...(config.extra ?? {}), shipvo: { baseUrl, appId, shellMajor, ...(props.reportEvents === false ? { reportEvents: false } : {}) } };
   config = withInfoPlist(config, (cfg) => {
     cfg.modResults.ShipvoBaseURL = baseUrl;
     cfg.modResults.ShipvoPublicKey = publicKey;
     cfg.modResults.ShipvoAppId = appId;
     cfg.modResults.ShipvoShellMajor = String(shellMajor);
     if (hbc !== undefined) cfg.modResults.ShipvoHermesBytecodeVersions = hbc;
+    if (hbe !== undefined) cfg.modResults.ShipvoHermesEngine = hbe;
     if (nm !== undefined) cfg.modResults.ShipvoNativeModules = nm;
     return cfg;
   });
@@ -57,7 +89,10 @@ module.exports = function withShipvo(config, props) {
     set("dev.shipvo.PUBLIC_KEY", publicKey);
     set("dev.shipvo.APP_ID", appId);
     set("dev.shipvo.SHELL_MAJOR", shellMajor);
+    if (rootKey !== undefined) set("dev.shipvo.ROOT_KEY", rootKey);
+    if (minSequence !== undefined) set("dev.shipvo.MIN_SEQUENCE", minSequence);
     if (hbc !== undefined) set("dev.shipvo.HERMES_BYTECODE_VERSIONS", hbc);
+    if (hbe !== undefined) set("dev.shipvo.HERMES_ENGINE", hbe);
     if (nm !== undefined) set("dev.shipvo.NATIVE_MODULES", nm);
     return cfg;
   });

package/ios/Rotation.swift

@@ -0,0 +1,147 @@
+import Foundation
+
+/// Time source for rotation. No rotation code reads the system time directly (design section 9).
+protocol Clock { func now() -> Date }
+struct SystemClock: Clock { func now() -> Date { Date() } }
+
+/// Signing key rotation (docs/design/key-rotation.md, sections 3 to 9).
+/// A statement is an envelope `{body, signature}` signed by the pinned root key. It replaces the current release key.
+/// The pointer check in `Updater` uses `Rotation.currentKey`; nothing else about that check changes.
+enum Rotation {
+  static let maxEntries = 8
+  static let maxBodyBytes = 1024
+  static let maxAheadDays = 90.0
+
+  struct Statement { let body: String, signature: String, sequence: Int, newKey: String, validFrom: Date }
+  struct Result: Equatable { let ok: Bool; let reason: String? }
+  struct Outcome { var rejectedWhole = false; var results: [Result] = [] }
+  struct State { var releaseKey: String, sequence: Int, pinnedKey: String, pending: [Statement] }
+
+  /// Test hook: how many root signature checks ran (design test 7).
+  static var signatureChecks = 0
+
+  // MARK: reading
+
+  /// The key that pointer signatures are checked against now: the pinned release key, or the one a root statement named.
+  /// Statements that came due since the last call are applied first.
+  static func currentKey(_ s: Store) -> String {
+    guard enabled(s) else { return s.publicKey }
+    return sync(s).releaseKey
+  }
+
+  static func enabled(_ s: Store) -> Bool { !s.rootKey.isEmpty }
+
+  /// Load the stored state and apply every pending statement that is due. Run on every launch and every fetch.
+  @discardableResult
+  static func sync(_ s: Store) -> State {
+    let before = load(s)
+    var st = before
+    settle(&st, incoming: [], now: s.clock.now())
+    if !same(st, before) { save(s, st) }
+    return st
+  }
+
+  // MARK: delivery
+
+  /// Handle the `rotations` array of a pointer response, before the pointer is looked at.
+  /// More than 8 entries are refused whole before any signature check.
+  @discardableResult
+  static func process(_ s: Store, rotations: Any?) -> Outcome {
+    var out = Outcome()
+    guard enabled(s), let list = rotations as? [Any] else { return out }
+    if list.count > maxEntries { out.rejectedWhole = true; return out }
+    let now = s.clock.now()
+    var st = load(s)
+    let effective = max(st.sequence, s.minSequence)
+    var incoming: [Statement] = []
+    for item in list {
+      let r = check(item, root: s.rootKey, appId: s.appId, ctx: (effective, now))
+      switch r {
+      case .failure(let f): out.results.append(Result(ok: false, reason: f.reason))
+      case .success(let stmt):
+        // Rule 4: the same sequence with other bytes does not replace the first one accepted.
+        if st.pending.contains(where: { $0.sequence == stmt.sequence }) || incoming.contains(where: { $0.sequence == stmt.sequence }) {
+          out.results.append(Result(ok: false, reason: "replay"))
+        } else { incoming.append(stmt); out.results.append(Result(ok: true, reason: nil)) }
+      }
+    }
+    let before = st
+    settle(&st, incoming: incoming, now: now)
+    if !same(st, before) { save(s, st) }
+    return out
+  }
+
+  // MARK: checks
+
+  struct Failure: Error { let reason: String }
+
+  /// Section 8 order: envelope shape, root signature, then the field rules of section 3.
+  /// `ctx` nil skips the replay and 90-day rules (used for statements already accepted and stored).
+  static func check(_ item: Any, root: String, appId: String, ctx: (effective: Int, now: Date)?) -> Swift.Result<Statement, Failure> {
+    guard let e = item as? [String: Any], let body = e["body"] as? String, let sig = e["signature"] as? String,
+          body.utf8.count <= maxBodyBytes else { return .failure(Failure(reason: "bad_envelope")) }
+    signatureChecks += 1
+    guard Verify.ed25519(Data(body.utf8), signatureB64: sig, publicKeyB64: root) else { return .failure(Failure(reason: "bad_signature")) }
+    guard let b = (try? JSONSerialization.jsonObject(with: Data(body.utf8))) as? [String: Any] else { return .failure(Failure(reason: "bad_body")) }
+    guard b["type"] as? String == "key-rotation" else { return .failure(Failure(reason: "wrong_type")) }
+    guard b["appId"] as? String == appId else { return .failure(Failure(reason: "wrong_app")) }
+    guard let seq = b["sequence"] as? Int, seq >= 1, seq <= 9_007_199_254_740_991 else { return .failure(Failure(reason: "bad_sequence")) }
+    if let ctx, seq <= ctx.effective { return .failure(Failure(reason: "replay")) }
+    guard let vf = (b["validFrom"] as? String).flatMap(parseDate) else { return .failure(Failure(reason: "bad_body")) }
+    if let ctx, vf.timeIntervalSince(ctx.now) > maxAheadDays * 86_400 { return .failure(Failure(reason: "too_far")) }
+    guard let key = b["newKey"] as? String, Data(base64Encoded: key)?.count == 32 else { return .failure(Failure(reason: "bad_key")) }
+    return .success(Statement(body: body, signature: sig, sequence: seq, newKey: key, validFrom: vf))
+  }
+
+  static func parseDate(_ s: String) -> Date? {
+    let f = ISO8601DateFormatter()
+    f.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+    if let d = f.date(from: s) { return d }
+    f.formatOptions = [.withInternetDateTime]
+    return f.date(from: s)
+  }
+
+  // MARK: section 7
+
+  /// Apply the due statement with the highest sequence, then keep the later ones (at most 8, lowest sequences first).
+  private static func settle(_ st: inout State, incoming: [Statement], now: Date) {
+    let known = (st.pending + incoming).sorted { $0.sequence < $1.sequence }
+    if let top = known.last(where: { $0.validFrom <= now }), top.sequence > st.sequence {
+      st.releaseKey = top.newKey; st.sequence = top.sequence
+    }
+    st.pending = Array(known.filter { $0.sequence > st.sequence }.prefix(maxEntries))
+  }
+
+  // MARK: storage (one atomic UserDefaults write of a single dictionary)
+
+  private static func same(_ a: State, _ b: State) -> Bool {
+    a.releaseKey == b.releaseKey && a.sequence == b.sequence && a.pinnedKey == b.pinnedKey && a.pending.map { $0.body + $0.signature } == b.pending.map { $0.body + $0.signature }
+  }
+
+  private static func load(_ s: Store) -> State {
+    let pin = s.publicKey
+    let fresh = State(releaseKey: pin, sequence: 0, pinnedKey: pin, pending: [])
+    guard let d = s.rotationRecord else { return fresh }
+    // Missing or unreadable values fall back to the pinned key, never to "no check".
+    guard let seq = d["rotation.sequence"] as? Int, seq >= 0 else { return fresh }
+    var st = fresh; st.sequence = seq
+    // A new store build pinning another release key drops the stored key and keeps the sequence.
+    if d["rotation.pinnedKey"] as? String == pin, let k = d["rotation.releaseKey"] as? String, Data(base64Encoded: k)?.count == 32 { st.releaseKey = k }
+    if let raw = d["rotation.pending"] {
+      var list: [Statement] = []
+      var good = (raw as? [Any]) != nil
+      for item in (raw as? [Any]) ?? [] {
+        if case .success(let stmt) = check(item, root: s.rootKey, appId: s.appId, ctx: nil), stmt.sequence > seq { list.append(stmt) } else { good = false; break }
+      }
+      st.pending = good && list.count <= maxEntries ? list : []   // a corrupt list is cleared, key and sequence are kept
+    }
+    return st
+  }
+
+  private static func save(_ s: Store, _ st: State) {
+    s.rotationRecord = [
+      "rotation.releaseKey": st.releaseKey, "rotation.sequence": st.sequence, "rotation.pinnedKey": st.pinnedKey,
+      "rotation.pending": st.pending.map { ["body": $0.body, "signature": $0.signature] },
+    ]
+  }
+}

package/ios/Store.swift

@@ -6,7 +6,8 @@ final class Store {
   /// Replaces what the app's Info.plist and file system would say. Tests use it; the app never does.
   struct Overrides {
     var suite: String, dir: URL, baseUrl: String, publicKey: String, appId: String, shellMajor: Int, shellVersion: String, binaryVersion: String
-    var hermesBytecodeVersions: [Int] = [], nativeModules: [String: String] = [:]
+    var hermesBytecodeVersions: [Int] = [], hermesEngine: String? = nil, nativeModules: [String: String] = [:]
+    var rootKey: String = "", minSequence: Int = 0, clock: Clock? = nil
   }
 
   private let d: UserDefaults
@@ -98,6 +99,20 @@ final class Store {
   private func plist(_ key: String) -> String? { bundle.object(forInfoDictionaryKey: key) as? String }
   var baseUrl: String { var s = o?.baseUrl ?? plist("ShipvoBaseURL") ?? ""; while s.hasSuffix("/") { s.removeLast() }; return s }
   var publicKey: String { o?.publicKey ?? plist("ShipvoPublicKey") ?? "" }
+  /// Pinned root key (Info.plist `ShipvoRootKey`). Empty means key rotation is off for this shell.
+  var rootKey: String { o?.rootKey ?? plist("ShipvoRootKey") ?? "" }
+  /// Highest rotation statement sequence that existed when this build was made (Info.plist `ShipvoMinSequence`, default 0).
+  var minSequence: Int {
+    if let o { return o.minSequence }
+    let v = bundle.object(forInfoDictionaryKey: "ShipvoMinSequence")
+    return max(0, (v as? NSNumber)?.intValue ?? Int((v as? String) ?? "") ?? 0)
+  }
+  var clock: Clock { o?.clock ?? SystemClock() }
+  /// Rotation state: key, sequence, pinned key and pending statements, written as one dictionary so they change together.
+  var rotationRecord: [String: Any]? {
+    get { d.dictionary(forKey: "rotation") }
+    set { if let newValue { d.set(newValue, forKey: "rotation") } else { d.removeObject(forKey: "rotation") } }
+  }
   var appId: String { o?.appId ?? plist("ShipvoAppId") ?? "" }
   /// Hermes bytecode versions this shell runs (Info.plist `ShipvoHermesBytecodeVersions`: an array of numbers or a "96,98" string).
   var hermesBytecodeVersions: [Int] {
@@ -106,6 +121,12 @@ final class Store {
     let list: [Any] = (v as? [Any]) ?? ((v as? String)?.split(separator: ",").map { String($0).trimmingCharacters(in: .whitespaces) } ?? [])
     return list.compactMap { ($0 as? NSNumber)?.intValue ?? Int("\($0)") }.filter { $0 > 0 }
   }
+  /// Hermes engine build id this shell runs (Info.plist `ShipvoHermesEngine`), or nil when not declared.
+  var hermesEngine: String? {
+    let v = o != nil ? o?.hermesEngine : plist("ShipvoHermesEngine")
+    let t = v?.trimmingCharacters(in: .whitespaces) ?? ""
+    return t.isEmpty ? nil : t
+  }
   /// Native modules in this shell (Info.plist `ShipvoNativeModules`: a name-to-version dictionary).
   var nativeModules: [String: String] {
     if let o { return o.nativeModules }

package/ios/Updater.swift

@@ -16,13 +16,14 @@ enum Updater {
 
   private static func resolve(_ s: Store, _ url: String) -> String { url.hasPrefix("http") ? url : "\(s.baseUrl)/\(url.drop(while: { $0 == "/" }))" }
 
-  /// Pointer URL. `?hbc=` and `?nm=` are added only when the shell declares them. Scoped names are percent-encoded.
+  /// Pointer URL. `?hbc=`, `?hbe=` and `?nm=` are added only when the shell declares them. Scoped names are percent-encoded.
   static func pointerURL(_ s: Store) -> String {
     var url = "\(s.baseUrl)/p/\(s.appId)/\(s.shellMajor)/ios/\(s.band).json"
     func enc(_ x: String) -> String { x.addingPercentEncoding(withAllowedCharacters: CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~")) ?? x }
     var q: [String] = []
     let hbc = s.hermesBytecodeVersions
     if !hbc.isEmpty { q.append("hbc=" + hbc.map(String.init).joined(separator: ",")) }
+    if let hbe = s.hermesEngine { q.append("hbe=" + enc(hbe)) }
     let nm = s.nativeModules
     if !nm.isEmpty { q.append("nm=" + nm.keys.sorted().map { enc($0) + "%40" + enc(nm[$0]!) }.joined(separator: ",")) }
     if !q.isEmpty { url += "?" + q.joined(separator: "&") }
@@ -31,6 +32,7 @@ enum Updater {
 
   static func check(_ s: Store) async throws -> [String: Any] {
     try require(!s.baseUrl.isEmpty && !s.publicKey.isEmpty && !s.appId.isEmpty, "runtime not configured")
+    Rotation.sync(s)   // statements that came due since the last launch apply before any pointer check
     let known = max(s.currentRelease, s.pendingRelease, s.blockedRelease)
     let (data, resp) = try await URLSession.shared.data(for: request(pointerURL(s), etag: known > 0 ? "\"\(known)\"" : nil))
     let code = (resp as? HTTPURLResponse)?.statusCode ?? 0
@@ -46,8 +48,10 @@ enum Updater {
     guard let envelope = try JSONSerialization.jsonObject(with: data) as? [String: Any],
           let bodyStr = envelope["body"] as? String, let sig = envelope["signature"] as? String else { throw UpdateError("pointer is not an envelope") }
 
+    // Rotation statements first, so a release signed by a new key can arrive in the same fetch.
+    Rotation.process(s, rotations: envelope["rotations"])
     let t0 = Store.now()
-    try require(Verify.ed25519(Data(bodyStr.utf8), signatureB64: sig, publicKeyB64: s.publicKey), "pointer signature invalid")
+    try require(Verify.ed25519(Data(bodyStr.utf8), signatureB64: sig, publicKeyB64: Rotation.currentKey(s)), "pointer signature invalid")
     guard let body = try JSONSerialization.jsonObject(with: Data(bodyStr.utf8)) as? [String: Any] else { throw UpdateError("pointer body unreadable") }
     try require(body["platform"] as? String == "ios", "pointer is not for iOS")
     try require(body["app_id"] as? String == s.appId && body["shell_major"] as? Int == s.shellMajor, "pointer for another app/shell")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/runtime",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "license": "Apache-2.0",
   "description": "The Shipvo native runtime: a tiny Expo module that verifies (Ed25519 + SHA-256), downloads (bsdiff patches), stages and applies signed over-the-air releases, with crash-loop rollback. Plus the config plugin that pins the trust root in the native shell.",
   "main": "src/index.ts",
@@ -16,6 +16,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "skills",
     "src",
     "android",
     "ios",
@@ -58,6 +59,7 @@
     "provenance": true
   },
   "devDependencies": {
+    "typescript": "^5.6.3",
     "vitest": "^2.1.4"
   },
   "scripts": {

package/skills/shipvo-runtime/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: shipvo-runtime
+description: Use the Shipvo over-the-air update runtime in an Expo or React Native app. Use when the project depends on @shipvo/runtime and you need to check for an update, mark a release healthy or forward update events.
+---
+
+# @shipvo/runtime
+
+The native half of Shipvo updates. It verifies every release (Ed25519 and SHA-256), applies patches, and goes back to the previous release after 3 unhealthy boots.
+
+`shipvo init --dry-run` then `shipvo init --yes` wires it for you. Never print or commit `.shipvo/seed.txt`.
+
+## In the app
+
+```ts
+import { Runtime } from "@shipvo/runtime";
+
+const state = Runtime.getState();        // running, pending and previous release, baseUrl, appId
+await Runtime.checkForUpdate(true);      // verify, download, stage, apply
+Runtime.markHealthy();                   // once the first screen rendered
+```
+
+The runtime reports its own events (`crash_loop_revert`, `rolled_back`, `verify_failed`) to telemetry. Use `onRuntimeEvents` to log them. `reportEvents: false` turns reporting off. Do not call `Runtime.consumeEvents()` unless you forward events yourself: it drains the queue before the runtime reports it.
+
+## Config plugin
+
+```json
+{ "expo": { "plugins": [["@shipvo/runtime", { "baseUrl": "https://<control plane>", "publicKey": "<base64 public key>", "appId": "myshop" }]] } }
+```
+
+Rebuild the native app after you change plugin props.
+
+## Check and release
+
+```bash
+shipvo doctor
+shipvo status --json
+shipvo publish --dry-run
+shipvo rollback --to <release>
+```

package/src/index.ts

@@ -1,4 +1,11 @@
 import { requireOptionalNativeModule } from "expo-modules-core";
+import { forwardRuntimeEvents, FORWARDED_EVENTS, type ForwardedEvent } from "./runtimeEvents";
+
+import { ensureInstallIdentity, signReport, webCrypto, type InstallIdentity, type TelemetryCrypto, type TelemetryStorage } from "./install";
+
+export { forwardRuntimeEvents, FORWARDED_EVENTS, ensureInstallIdentity, signReport, webCrypto };
+export type { InstallIdentity, TelemetryCrypto, TelemetryStorage };
+export type { ForwardedEvent };
 
 export type RuntimeState = {
   cohort: number; band: "b0" | "b1" | "b2";
@@ -58,12 +65,77 @@ function installCrashHook() {
   });
 }
 
+let identity: InstallIdentity | null = null;
+let identityCrypto: TelemetryCrypto = webCrypto;
+/**
+ * Turn on signed telemetry. Registers this install once (see `ensureInstallIdentity`); until that finishes, and if it
+ * fails, reports are sent unsigned. Pass your own `crypto` on React Native. Never throws. The identity is module-global:
+ * calling this again replaces the previous identity and crypto.
+ */
+export async function enableSignedTelemetry(opts: { storage: TelemetryStorage; registerUrl: string; crypto?: TelemetryCrypto }): Promise<InstallIdentity | null> {
+  identityCrypto = opts.crypto ?? webCrypto;
+  identity = await ensureInstallIdentity(opts.storage, identityCrypto, opts.registerUrl);
+  return identity;
+}
+
+const listeners = new Set<(events: string[]) => void>();
+/** Called with every batch of queued events the runtime drains, in `reportRuntimeEvents`. Returns an unsubscribe function. */
+export function onRuntimeEvents(fn: (events: string[]) => void): () => void {
+  listeners.add(fn);
+  return () => { listeners.delete(fn); };
+}
+
+/**
+ * Drain the device's event queue and send each forwarded event to the control plane (`POST {baseUrl}/t`), using
+ * `baseUrl` and `appId` from the native state or `expo.extra.shipvo`. Best effort: it never throws, a failed send
+ * never blocks the others, and nothing is sent without a `baseUrl`. Returns the drained event strings.
+ * `Runtime.markHealthy` and `Runtime.checkForUpdate` call this for you. Set `extra.shipvo.reportEvents` to `false`
+ * to turn that off.
+ */
+export function reportRuntimeEvents(): string[] {
+  let events: string[] = [];
+  try { events = native ? native.consumeEvents() : []; } catch { return []; }
+  if (!Array.isArray(events) || events.length === 0) return [];
+  for (const l of listeners) { try { l(events); } catch {} }
+  let state: Partial<RuntimeState> = {};
+  try { state = (native ?? fallback).getState() ?? {}; } catch {}
+  const baseUrl = state.baseUrl || extra.baseUrl;
+  const appId = state.appId || extra.appId;
+  if (!baseUrl || !appId) return events;
+  let androidApi: number | undefined;
+  try {
+    const rn = require("react-native");
+    if (rn.Platform?.OS === "android" && typeof rn.Platform.Version === "number") androidApi = rn.Platform.Version;
+  } catch {}
+  forwardRuntimeEvents(events, (event, release) => {
+    try {
+      // Same payload the sample app sent before this moved here: device_class is fixed to "low", android_api is set on Android only.
+      const body = { schema_version: "1.0", app_id: appId, release: release ?? state.runningRelease ?? 0, event,
+        device_class: "low", android_api: androidApi };
+      const post = (b: string) => Promise.resolve(fetch(`${baseUrl}/t`, { method: "POST", headers: { "content-type": "application/json" },
+        body: b })).catch(() => {});
+      const id = identity;
+      if (!id) { post(JSON.stringify(body)); return; }
+      const plain = JSON.stringify(body);
+      // `sig` is the HMAC of `signed`, closing `}` included. We send `signed` with that `}` replaced by
+      // `,"sig":"<hex>"}`. The server cuts that suffix, appends `}` and checks the HMAC. If signing fails, send unsigned.
+      const signed = JSON.stringify({ ...body, install_id: id.install_id });
+      signReport(id, signed, identityCrypto).then(
+        (r) => post(`${signed.slice(0, -1)},"sig":"${r.sig}"}`),
+        () => post(plain));
+    } catch {}
+  });
+  return events;
+}
+
+const autoReport = () => { if (extra.reportEvents !== false) reportRuntimeEvents(); };
+
 // Every `Native` method must be listed here, or it is silently dropped from `Runtime`.
 export const Runtime: Native = native
   ? {
       getState: () => native.getState(),
-      checkForUpdate: (apply) => native.checkForUpdate(apply),
-      markHealthy: () => { const r = native.markHealthy(); installCrashHook(); return r; },
+      checkForUpdate: async (apply) => { try { return await native.checkForUpdate(apply); } finally { autoReport(); } },
+      markHealthy: () => { const r = native.markHealthy(); installCrashHook(); autoReport(); return r; },
       consumeEvents: () => native.consumeEvents(),
       rollback: () => native.rollback(),
       reload: () => native.reload(),

package/src/index.web.ts

@@ -16,3 +16,6 @@ export const Runtime = {
   rollback(): void {},
   reload(): void { (globalThis as any).location?.reload(); },
 };
+export { FORWARDED_EVENTS, forwardRuntimeEvents } from "./runtimeEvents";
+export function reportRuntimeEvents(): string[] { return []; }
+export function onRuntimeEvents(_fn: (events: string[]) => void): () => void { return () => {}; }

package/src/install.ts

@@ -0,0 +1,74 @@
+/**
+ * Install identity for signed telemetry. On first launch the app makes a random install id and registers it once
+ * (`POST registerUrl` with `{ install_id }`, answer `{ key }`). The key is a secret string. Reports are signed with
+ * HMAC-SHA256, using the UTF-8 bytes of the key, and the signature is lower-case hex.
+ *
+ * Signing rule: the sent body is `<unsigned>` with its last `}` replaced by `,"sig":"<hex>"}`. The HMAC covers the
+ * unsigned JSON string, including its closing `}`. To verify, the server cuts the suffix `,"sig":"<hex>"}` from the
+ * received string, appends `}`, and checks the HMAC of that string.
+ */
+export type InstallIdentity = { install_id: string; key: string };
+
+/** Where the identity lives. Pass an AsyncStorage-style adapter on React Native. */
+export interface TelemetryStorage {
+  getItem(key: string): Promise<string | null> | string | null;
+  setItem(key: string, value: string): Promise<void> | void;
+}
+
+/** React Native has no `crypto.subtle`, so apps can pass their own. */
+export interface TelemetryCrypto {
+  /** Random bytes, for the install id. */
+  randomBytes(n: number): Uint8Array | Promise<Uint8Array>;
+  /** HMAC-SHA256 of `data` under `key`. */
+  hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array | Promise<Uint8Array>;
+}
+
+export const IDENTITY_STORAGE_KEY = "shipvo.install_identity";
+
+const hex = (b: Uint8Array) => Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+
+/** Default for web and Node (needs `globalThis.crypto.subtle`). */
+export const webCrypto: TelemetryCrypto = {
+  randomBytes: (n) => globalThis.crypto.getRandomValues(new Uint8Array(n)),
+  hmacSha256: async (key, data) => {
+    const k = await globalThis.crypto.subtle.importKey("raw", key as BufferSource, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await globalThis.crypto.subtle.sign("HMAC", k, data as BufferSource));
+  },
+};
+
+/**
+ * Load the stored identity, or create and register one. Returns `null` when registration fails (offline, server
+ * error, bad answer); nothing is stored then and the next launch tries again. Never throws.
+ */
+export async function ensureInstallIdentity(
+  storage: TelemetryStorage, crypto: TelemetryCrypto, registerUrl: string,
+): Promise<InstallIdentity | null> {
+  try {
+    const raw = await storage.getItem(IDENTITY_STORAGE_KEY);
+    if (raw) {
+      let s: any = null;
+      try { s = JSON.parse(raw); } catch {} // corrupted: register again
+      if (typeof s?.install_id === "string" && typeof s?.key === "string") return { install_id: s.install_id, key: s.key };
+    }
+    const install_id = hex(await crypto.randomBytes(16));
+    const res = await fetch(registerUrl, { method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ install_id }) });
+    if (!res.ok) return null;
+    const out: any = await res.json();
+    if (typeof out?.key !== "string" || !out.key) return null;
+    const identity = { install_id, key: out.key };
+    await storage.setItem(IDENTITY_STORAGE_KEY, JSON.stringify(identity));
+    return identity;
+  } catch {
+    return null;
+  }
+}
+
+/** Sign `body`, the unsigned JSON string (with its closing `}`). See the signing rule at the top of this file. */
+export async function signReport(
+  identity: InstallIdentity, body: string, crypto: TelemetryCrypto = webCrypto,
+): Promise<{ install_id: string; sig: string }> {
+  const enc = new TextEncoder();
+  const mac = await crypto.hmacSha256(enc.encode(identity.key), enc.encode(body));
+  return { install_id: identity.install_id, sig: hex(mac) };
+}

package/src/runtimeEvents.ts

@@ -0,0 +1,38 @@
+/** Runtime events the app forwards to telemetry. Each one is sent once per event. */
+export const FORWARDED_EVENTS = [
+  "crash_loop_revert",
+  "rolled_back",
+  "verify_failed",
+  "download_failed",
+  "hermes_bytecode_mismatch",
+  "native_module_missing",
+  "native_module_version",
+] as const;
+export type ForwardedEvent = (typeof FORWARDED_EVENTS)[number];
+
+const CARRIES_RELEASE: string[] = ["verify_failed", "download_failed", "hermes_bytecode_mismatch"];
+const NATIVE_MODULE_REASONS: string[] = ["native_module_missing", "native_module_version"];
+
+/**
+ * Turn runtime event strings ("name" or "name:<release>") into telemetry reports.
+ * `verify_failed`, `download_failed` and `hermes_bytecode_mismatch:<release>:...`
+ * carry a release id: a failed release is reported under its own id. `crash_loop_revert` and `rolled_back` never override the
+ * release, so the sender uses the running release as before. A missing or non-numeric
+ * id also falls back to the running release.
+ */
+export function forwardRuntimeEvents(
+  events: string[],
+  send: (event: ForwardedEvent, release?: number) => void,
+): void {
+  for (const e of events) {
+    const [name, id] = e.split(":");
+    if (name === "pointer_rejected") {
+      // "pointer_rejected:<reason>": only the two native-module reasons are reported.
+      if (id !== undefined && NATIVE_MODULE_REASONS.includes(id)) send(id as ForwardedEvent);
+      continue;
+    }
+    if (!(FORWARDED_EVENTS as readonly string[]).includes(name)) continue;
+    const release = CARRIES_RELEASE.includes(name) && id !== undefined && /^\d+$/.test(id) ? Number(id) : undefined;
+    send(name as ForwardedEvent, release);
+  }
+}