@shipvo/runtime 0.1.3 → 0.1.5

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/ShipvoRuntimeModule.swift

@@ -35,10 +35,14 @@ public final class ShipvoRuntimeModule: Module {
       let coldStart = max(0, (Date().timeIntervalSince1970 - Self.processStart()) * 1000)
       let sinceLoad = Store.bundleSelectedAt > 0 ? (now - Store.bundleSelectedAt) * 1000 : -1
       let promoted = ShipvoBundleSelector.promoteIfRunning(s)
+      ShipvoBundleSelector.noteHealthy()
+      Self.scheduleStable()
       return ["release": Store.runningRelease, "coldStartMs": Int(coldStart), "sinceLoadMs": Int(sinceLoad), "promoted": promoted,
               "kind": Store.loadsInProcess <= 1 ? "cold" : "reload"]
     }
 
+    OnAppEntersBackground { Self.stableNow() }
+
     Function("consumeEvents") { () -> [String] in Store().consumeEvents() }
 
     Function("rollback") { () in
@@ -56,7 +60,30 @@ public final class ShipvoRuntimeModule: Module {
     Function("reload") { () in Self.reloadHost() }
   }
 
+  private static var stableTimer: DispatchWorkItem?
+
+  /// Clears the unhealthy-boot count once the app has stayed up for the stability window.
+  /// The timer is dropped after it fires and on reload, and `markStableIfHealthy` checks the load number.
+  static func scheduleStable() {
+    Store.lock.lock(); defer { Store.lock.unlock() }
+    stableTimer?.cancel()
+    let item = DispatchWorkItem {
+      ShipvoBundleSelector.markStableIfHealthy(Store())
+      Store.lock.lock(); stableTimer = nil; Store.lock.unlock()
+    }
+    stableTimer = item
+    DispatchQueue.main.asyncAfter(deadline: .now() + ShipvoBundleSelector.stabilitySeconds, execute: item)
+  }
+
+  /// Going to background cleanly counts as stable, but only if this load reported healthy.
+  static func stableNow() {
+    if ShipvoBundleSelector.markStableIfHealthy(Store()) {
+      Store.lock.lock(); stableTimer?.cancel(); stableTimer = nil; Store.lock.unlock()
+    }
+  }
+
   static func reloadHost() {
+    Store.lock.lock(); stableTimer?.cancel(); stableTimer = nil; Store.lock.unlock()
     ShipvoBundleSelector.invalidate()
     DispatchQueue.main.async { RCTTriggerReloadCommandListeners("shipvo-update") }
   }

package/ios/Store.swift

@@ -6,6 +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] = [], hermesEngine: String? = nil, nativeModules: [String: String] = [:]
+    var rootKey: String = "", minSequence: Int = 0, clock: Clock? = nil
   }
 
   private let d: UserDefaults
@@ -44,6 +46,19 @@ final class Store {
   var blockedRelease: Int { get { d.integer(forKey: "blocked_release") } set { d.set(newValue, forKey: "blocked_release") } }
   /// Shell binary the stored OTA bundles were downloaded under.
   var binaryVersion: String? { get { d.string(forKey: "binary_version") } set { d.set(newValue, forKey: "binary_version") } }
+  var appBundle: Bundle { bundle }
+  /// The `main.jsbundle` inside the app: the first release, and the patch base before any download.
+  func embeddedBundle() -> Data? {
+    guard let url = bundle.url(forResource: "main", withExtension: "jsbundle") else { return nil }
+    return try? Data(contentsOf: url)
+  }
+  /// Its sha256, cached per installed binary so the file is hashed once.
+  func embeddedSha() -> String? {
+    let key = "embedded_sha:" + installedBinaryVersion
+    if let v = d.string(forKey: key) { return v }
+    guard let data = embeddedBundle() else { return nil }
+    let sha = Verify.sha256Hex(data); d.set(sha, forKey: key); return sha
+  }
   func block(_ release: Int) { if release > blockedRelease { blockedRelease = release } }
 
   var trialBoots: Int { get { d.integer(forKey: "trial_boots") } set { d.set(newValue, forKey: "trial_boots") } }
@@ -84,7 +99,39 @@ 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] {
+    if let o { return o.hermesBytecodeVersions }
+    let v = bundle.object(forInfoDictionaryKey: "ShipvoHermesBytecodeVersions")
+    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 }
+    return (bundle.object(forInfoDictionaryKey: "ShipvoNativeModules") as? [String: Any])?.compactMapValues { $0 as? String } ?? [:]
+  }
   var shellMajor: Int { if let o { return o.shellMajor }; return Int(plist("ShipvoShellMajor") ?? "1") ?? 1 }
 
   // MARK: per-process state

package/ios/Updater.swift

@@ -3,7 +3,7 @@ import Foundation
 struct UpdateError: Error { let message: String; init(_ m: String) { message = m } }
 
 /// Fetch, verify and stage the newest signed release for this device's band. Mirrors Android `check()`.
-/// Uses a bsdiff patch when the pointer lists one from the bundle this device runs; any patch problem falls back to the full bundle.
+/// Uses a bsdiff patch when the pointer lists one from the bundle this device runs (or the app's embedded bundle); any patch problem falls back to the full bundle.
 enum Updater {
   private static func require(_ cond: Bool, _ msg: @autoclosure () -> String) throws { if !cond { throw UpdateError(msg()) } }
 
@@ -16,18 +16,42 @@ enum Updater {
 
   private static func resolve(_ s: Store, _ url: String) -> String { url.hasPrefix("http") ? url : "\(s.baseUrl)/\(url.drop(while: { $0 == "/" }))" }
 
+  /// 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: "&") }
+    return url
+  }
+
   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("\(s.baseUrl)/p/\(s.appId)/\(s.shellMajor)/ios/\(s.band).json", etag: known > 0 ? "\"\(known)\"" : nil))
+    let (data, resp) = try await URLSession.shared.data(for: request(pointerURL(s), etag: known > 0 ? "\"\(known)\"" : nil))
     let code = (resp as? HTTPURLResponse)?.statusCode ?? 0
-    if code == 304 || code == 404 { return ["status": "none"] }
+    if code == 404 {
+      // The control plane says this shell cannot run the release. Keep the current one; stage nothing.
+      let text = String(data: data, encoding: .utf8) ?? ""
+      let reason = ((try? JSONSerialization.jsonObject(with: data)) as? [String: Any])?["error"] as? String ?? text.trimmingCharacters(in: .whitespacesAndNewlines)
+      if ["hermes_bytecode_mismatch", "native_module_missing", "native_module_version"].contains(reason) { return ["status": "none", "reason": reason] }
+      return ["status": "none"]
+    }
+    if code == 304 { return ["status": "none"] }
     try require(code == 200, "pointer HTTP \(code)")
     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")
@@ -35,11 +59,18 @@ enum Updater {
     if release <= known { return ["status": "none"] }
     try require(!Verify.semverLess(s.shellVersion, body["min_shell_version"] as? String ?? "0.0.0"), "shell too old for release \(release)")
     let verifyPointerMs = (Store.now() - t0) * 1000
+    // Beside the signature checks, not inside them: refuse a bundle built for another Hermes bytecode version.
+    if let ev = HermesGuard.mismatchEvent(release: release, releaseVersion: HermesGuard.releaseVersionOf(body["hermes_bytecode_version"]), shellVersion: HermesGuard.shellVersion(s.appBundle)) {
+      s.addEvent(ev); s.block(release)
+      return ["status": "none", "reason": HermesGuard.reason]
+    }
 
     guard let core = body["core"] as? [String: Any], let wantSha = core["sha256"] as? String,
           let wantSize = (core["size"] as? NSNumber)?.intValue, let url = core["url"] as? String else { throw UpdateError("pointer core incomplete") }
     let tmp = s.dir.appendingPathComponent("dl-\(release).tmp")
     try? FileManager.default.removeItem(at: tmp)
+    let part = partialURL(s, sha: wantSha)
+    dropOtherPartials(s, keep: part)
 
     var via = "full", downloadedBytes = 0
     let d0 = Store.now()
@@ -48,21 +79,20 @@ enum Updater {
       ready = true; via = "patch"; downloadedBytes = patch
     }
     var downloadMs = (Store.now() - d0) * 1000
+    var resumedFrom = 0
     if !ready {
       let f0 = Store.now()
-      let (fileURL, dresp) = try await URLSession.shared.download(for: request(resolve(s, url), etag: nil))
-      let dcode = (dresp as? HTTPURLResponse)?.statusCode ?? 0
-      try require(dcode == 200, "bundle HTTP \(dcode)")
+      resumedFrom = try await downloadFull(s, url: resolve(s, url), part: part, wantSize: wantSize)
       try? FileManager.default.removeItem(at: tmp)
-      try FileManager.default.moveItem(at: fileURL, to: tmp)
+      try FileManager.default.moveItem(at: part, to: tmp)
       downloadMs += (Store.now() - f0) * 1000
     }
 
     let v0 = Store.now()
     let size = (try? FileManager.default.attributesOfItem(atPath: tmp.path)[.size] as? Int) ?? -1
-    if via == "full" { downloadedBytes = size }
+    if via == "full" { downloadedBytes = max(0, size - resumedFrom) }
     let ok = try (size == wantSize && Verify.sha256Hex(file: tmp) == wantSha)
-    if !ok { try? FileManager.default.removeItem(at: tmp); s.addEvent("verify_failed:\(release)"); throw UpdateError("bundle hash/size mismatch") }
+    if !ok { try? FileManager.default.removeItem(at: tmp); try? FileManager.default.removeItem(at: part); s.addEvent("verify_failed:\(release)"); throw UpdateError("bundle hash/size mismatch") }
     let verifyMs = (Store.now() - v0) * 1000 + verifyPointerMs
 
     let dest = s.dir.appendingPathComponent("r\(release).hbc")
@@ -73,19 +103,63 @@ enum Updater {
             "downloadMs": Int(downloadMs), "verifyMs": Int(verifyMs), "issuedAt": body["issued_at"] as? String ?? ""]
   }
 
+  /// Partial full-bundle download, named by the release sha256 so a different release never reuses it.
+  static func partialURL(_ s: Store, sha: String) -> URL { s.dir.appendingPathComponent("dl-\(sha).part") }
+
+  /// The release changed: partial files for other hashes can never complete.
+  private static func dropOtherPartials(_ s: Store, keep: URL) {
+    let files = (try? FileManager.default.contentsOfDirectory(at: s.dir, includingPropertiesForKeys: nil)) ?? []
+    for f in files where f.pathExtension == "part" && f.lastPathComponent != keep.lastPathComponent { try? FileManager.default.removeItem(at: f) }
+  }
+
+  /// Download the full bundle into `part`, resuming with `Range: bytes=<n>-` when a partial file exists.
+  /// A 200 answer means the server ignored the range: start over. Returns how many bytes were already on disk.
+  /// If the connection drops, the partial file stays for the next attempt. The caller still checks the signed hash.
+  private static func downloadFull(_ s: Store, url: String, part: URL, wantSize: Int) async throws -> Int {
+    let fm = FileManager.default
+    func have() -> Int { (try? fm.attributesOfItem(atPath: part.path)[.size] as? Int) ?? 0 }
+    var offset = have()
+    if offset > wantSize { try? fm.removeItem(at: part); offset = 0 }
+    if offset == wantSize { return offset }
+    for attempt in 0..<2 {
+      var req = try request(url, etag: nil)
+      if offset > 0 { req.setValue("bytes=\(offset)-", forHTTPHeaderField: "Range") }
+      let (stream, resp) = try await URLSession.shared.bytes(for: req)
+      let code = (resp as? HTTPURLResponse)?.statusCode ?? 0
+      if code == 416 && offset > 0 && attempt == 0 { try? fm.removeItem(at: part); offset = 0; continue }
+      try require(code == 200 || (code == 206 && offset > 0), "bundle HTTP \(code)")
+      if code == 200 { try? fm.removeItem(at: part); offset = 0 }
+      if !fm.fileExists(atPath: part.path) { try require(fm.createFile(atPath: part.path, contents: nil), "cannot create partial file") }
+      let h = try FileHandle(forWritingTo: part)
+      defer { try? h.close() }
+      try h.seekToEnd()
+      var buf = Data(); buf.reserveCapacity(64 * 1024)
+      for try await b in stream {
+        buf.append(b)
+        if buf.count >= 64 * 1024 { try h.write(contentsOf: buf); buf.removeAll(keepingCapacity: true) }
+      }
+      if !buf.isEmpty { try h.write(contentsOf: buf) }
+      return offset
+    }
+    throw UpdateError("bundle download failed")
+  }
+
   /// Try the patch from the bundle this device runs. Writes the rebuilt bundle to `tmp` and returns the patch size,
   /// or throws (nothing left behind) so the caller can fetch the full bundle. The caller still checks the signed hash.
   private static func patched(_ s: Store, core: [String: Any], wantSha: String, wantSize: Int, to tmp: URL) async throws -> Int {
-    guard let base = s.currentPath, s.currentSha != nil, FileManager.default.fileExists(atPath: base),
+    // Base: the bundle this device runs, or the embedded main.jsbundle before the first update.
+    let baseFile = s.currentPath.flatMap { FileManager.default.fileExists(atPath: $0) ? $0 : nil }
+    let baseSha: String? = baseFile != nil ? s.currentSha : s.embeddedSha()
+    guard let baseSha,
           let list = core["patches"] as? [[String: Any]],
-          let entry = list.first(where: { $0["from_sha256"] as? String == s.currentSha }),
+          let entry = list.first(where: { $0["from_sha256"] as? String == baseSha }),
           let purl = entry["url"] as? String, let psha = entry["sha256"] as? String, let psize = (entry["size"] as? NSNumber)?.intValue,
           psize > 0, psize < wantSize else { throw UpdateError("no usable patch") }
     do {
       let (data, resp) = try await URLSession.shared.data(for: request(resolve(s, purl), etag: nil))
       try require((resp as? HTTPURLResponse)?.statusCode == 200 && data.count == psize && Verify.sha256Hex(data) == psha, "patch download invalid")
-      let old = try Data(contentsOf: URL(fileURLWithPath: base))
-      try require(Verify.sha256Hex(old) == s.currentSha, "current bundle changed on disk")
+      guard let old = try baseFile.map({ try Data(contentsOf: URL(fileURLWithPath: $0)) }) ?? s.embeddedBundle() else { throw UpdateError("no base bundle") }
+      try require(Verify.sha256Hex(old) == baseSha, "base bundle changed on disk")
       let new = try Patch.apply(old: old, patch: data)
       try require(new.count == wantSize && Verify.sha256Hex(new) == wantSha, "patched bundle does not match")
       try new.write(to: tmp)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/runtime",
-  "version": "0.1.3",
+  "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",
@@ -56,5 +57,12 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "scripts": {
+    "test": "vitest run"
   }
 }

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";
@@ -11,6 +18,8 @@ export type CheckResult = {
   /** Shell 1.0.2+ (Android): "patch" when a bsdiff patch was applied, "full" otherwise. iOS always downloads "full". */
   via?: "patch" | "full"; bundleBytes?: number; patchError?: string | null;
   issuedAt?: string; error?: string;
+  /** Android only for now: why a "none" result happened when the control plane rejected the shell's bytecode or native modules. */
+  reason?: "hermes_bytecode_mismatch" | "native_module_missing" | "native_module_version";
 };
 export type HealthyResult = {
   release: number; coldStartMs: number; sinceLoadMs: number; promoted: boolean;
@@ -39,4 +48,96 @@ const fallback: Native = {
   markHealthy: () => ({ release: 0, coldStartMs: Date.now() - t0, sinceLoadMs: 0, promoted: false, kind: "cold" }),
   consumeEvents: () => [], rollback: () => {}, reload: () => {},
 };
-export const Runtime: Native = requireOptionalNativeModule<Native>("ShipvoRuntime") ?? fallback;
+const native = requireOptionalNativeModule<Native & { noteCrash?(): void }>("ShipvoRuntime");
+
+// After markHealthy, tell the native side about an uncaught JS error before React destroys the host. Destroying the host
+// pauses the activity, and that pause must not count as "stable". Needs a shell with `noteCrash`; older shells skip it.
+let crashHookInstalled = false;
+function installCrashHook() {
+  if (crashHookInstalled || typeof native?.noteCrash !== "function") return;
+  const eu = (globalThis as any).ErrorUtils;
+  if (!eu?.setGlobalHandler || !eu.getGlobalHandler) return;
+  crashHookInstalled = true;
+  const prev = eu.getGlobalHandler();
+  eu.setGlobalHandler((e: unknown, isFatal?: boolean) => {
+    if (isFatal) { try { native.noteCrash!(); } catch {} }
+    prev?.(e, isFatal);
+  });
+}
+
+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: 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(),
+    }
+  : fallback;

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 () => {}; }