@scalebun-release/react-native 2.5.0

package/ios/Ota/OtaSlotManager.swift

@@ -0,0 +1,613 @@
+import Foundation
+import CommonCrypto
+
+/**
+ * Pure Swift slot manager for OTA bundles — no React Native dependency.
+ *
+ * Implements the three-slot layout from docs/ota-native-design.md:
+ *   Library/Application Support/scalebun_ota/
+ *   ├── current/   — active bundle
+ *   ├── next/      — staged downloaded bundle
+ *   ├── previous/  — rollback target
+ *   └── boot_marker — boot guard file
+ *
+ * Atomicity via FileManager.moveItem(): atomic on the same filesystem.
+ */
+class OtaSlotManager {
+
+    private static let otaDirName = "scalebun_ota"
+    private static let bundleFilename = "bundle.jsbundle"
+    private static let metaFilename = "meta.json"
+    private static let bootMarkerFilename = "boot_marker"
+    private static let revertRecordFilename = "revert_record"
+
+    /// Launches a new bundle gets to call markHealthy() before it is reverted.
+    /// Matches the Android limit — the two platforms must agree or the same bad
+    /// release behaves differently depending on the phone.
+    private static let maxBootAttempts = 2
+
+    private let otaRoot: URL
+
+    init() {
+        let appSupport = FileManager.default.urls(
+            for: .applicationSupportDirectory,
+            in: .userDomainMask
+        ).first!
+        self.otaRoot = appSupport.appendingPathComponent(OtaSlotManager.otaDirName)
+    }
+
+    private var currentSlot: URL { otaRoot.appendingPathComponent("current") }
+    private var nextSlot: URL { otaRoot.appendingPathComponent("next") }
+    private var previousSlot: URL { otaRoot.appendingPathComponent("previous") }
+    private var bootMarkerFile: URL { otaRoot.appendingPathComponent(OtaSlotManager.bootMarkerFilename) }
+    private var revertRecordFile: URL { otaRoot.appendingPathComponent(OtaSlotManager.revertRecordFilename) }
+
+    // MARK: - Public API
+
+    /// Record that the next bridge load is a restart WE asked for.
+    ///
+    /// Consumed once by the boot guard so an intentional restart does not spend
+    /// one of the bundle's two boot attempts. No-op when no boot marker is
+    /// present, which is the normal steady state.
+    ///
+    /// Mirrors SlotManager.markIntentionalRestart() on Android. It matters more
+    /// here: checkBootGuard() runs from getBundleURL(), which React Native calls
+    /// on every bridge creation — including the reload restartApp() triggers —
+    /// so without this the activation restart ALWAYS consumes an attempt.
+    func markIntentionalRestart() {
+        let fm = FileManager.default
+        guard fm.fileExists(atPath: bootMarkerFile.path) else { return }
+        do {
+            let data = try Data(contentsOf: bootMarkerFile)
+            guard var marker = try JSONSerialization.jsonObject(with: data) as? [String: Any] else { return }
+            marker["intentionalRestart"] = true
+            let out = try JSONSerialization.data(withJSONObject: marker)
+            try out.write(to: bootMarkerFile, options: .atomic)
+        } catch {
+            // Best effort: failing to record intent only costs a boot attempt,
+            // which is strictly better than failing the restart itself.
+            NSLog("[ScaleBunOta] Could not record intentional restart: \(error)")
+        }
+    }
+
+    /// Returns the URL to the active JS bundle, or nil if no OTA bundle is installed.
+    func currentBundleURL() -> URL? {
+        let bundle = currentSlot.appendingPathComponent(OtaSlotManager.bundleFilename)
+        guard FileManager.default.fileExists(atPath: bundle.path) else { return nil }
+
+        // Integrity re-check on execution.
+        //
+        // The signature and hash are verified when a bundle is STAGED. That
+        // protects the download path, but it says nothing about the bytes still
+        // being the ones we installed: on a jailbroken device, anything able to
+        // write into the app container can replace current/bundle.jsbundle after
+        // the fact, and the old `fileExists` check would happily execute it.
+        //
+        // meta.json already records the sha256 the slot manager installed, so the
+        // comparison costs one hash of the active bundle per process — not per
+        // call, hence the cache. On mismatch we refuse the slot and return nil,
+        // which makes AppDelegate fall back to the bundle compiled into the app.
+        // Failing closed to a known-good baseline is the only safe answer here.
+        if let verified = verifiedBundleURL {
+            return FileManager.default.fileExists(atPath: verified.path) ? verified : nil
+        }
+        if integrityFailed { return nil }
+
+        let expected = (readMeta(slot: currentSlot)?["sha256"] as? String) ?? ""
+        if expected.isEmpty {
+            // Pre-integrity install, or metadata lost. Nothing to compare against;
+            // do not invent a failure for a bundle that may be perfectly good.
+            NSLog("[ScaleBunOta] current/ has no recorded sha256 — skipping integrity re-check")
+            verifiedBundleURL = bundle
+            return bundle
+        }
+
+        guard let actual = streamingSha256(fileURL: bundle) else {
+            NSLog("[ScaleBunOta] Integrity re-check could not hash current/ — refusing the slot")
+            integrityFailed = true
+            return nil
+        }
+
+        if !constantTimeEquals(actual, expected) {
+            NSLog(
+                "[ScaleBunOta] INTEGRITY FAILURE — current/ bundle does not match the sha256 "
+                    + "recorded at install (expected=\(expected.prefix(12))… "
+                    + "actual=\(actual.prefix(12))…). The bundle was modified after installation. "
+                    + "Falling back to the binary baseline and clearing the slot."
+            )
+            integrityFailed = true
+            try? FileManager.default.removeItem(at: currentSlot)
+            return nil
+        }
+
+        verifiedBundleURL = bundle
+        return bundle
+    }
+
+    /// Proven this process; the hash is not recomputed on later calls.
+    private var verifiedBundleURL: URL?
+    /// Latched: once the active slot fails, it is not re-examined this process.
+    private var integrityFailed = false
+
+    /// Called whenever current/ is replaced — the previous verdict no longer
+    /// describes the bundle at that path.
+    private func invalidateIntegrityCache() {
+        verifiedBundleURL = nil
+        integrityFailed = false
+    }
+
+    /// Length-independent comparison, so a mismatch leaks nothing through timing.
+    private func constantTimeEquals(_ a: String, _ b: String) -> Bool {
+        let x = Array(a.utf8)
+        let y = Array(b.utf8)
+        if x.count != y.count { return false }
+        var diff: UInt8 = 0
+        for i in x.indices { diff |= x[i] ^ y[i] }
+        return diff == 0
+    }
+
+    /**
+     SHA-256 over a file, read in chunks.
+
+     Streaming rather than `Data(contentsOf:)` because this now runs on every cold
+     start: mapping a 20-50 MB bundle into memory at launch is exactly the spike
+     that gets a host app jetsammed on an older device. Matches the Android
+     implementation, which has always read in 8 KB blocks.
+     */
+    private func streamingSha256(fileURL: URL) -> String? {
+        guard let handle = try? FileHandle(forReadingFrom: fileURL) else { return nil }
+        defer { try? handle.close() }
+
+        var context = CC_SHA256_CTX()
+        CC_SHA256_Init(&context)
+
+        let chunkSize = 64 * 1024
+        while true {
+            let chunk: Data = autoreleasepool { handle.readData(ofLength: chunkSize) }
+            if chunk.isEmpty { break }
+            // Copied out of the closure first: passing &context into a closure
+            // that also borrows `chunk` is an overlapping-access complaint the
+            // compiler is entitled to make.
+            let updated: Bool = chunk.withUnsafeBytes { buffer -> Bool in
+                guard let base = buffer.baseAddress else { return false }
+                CC_SHA256_Update(&context, base, CC_LONG(buffer.count))
+                return true
+            }
+            if !updated { return nil }
+        }
+
+        var digest = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
+        CC_SHA256_Final(&digest, &context)
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    /**
+     * Serialises the three operations that MOVE slot directories.
+     *
+     * stage() ends with "remove next/, rename tmp -> next/" while apply() is doing
+     * "move current/ -> previous/, move next/ -> current/". Run concurrently, one
+     * renames a directory out from under the other and apply() throws — and its
+     * recovery only restores when previous/ exists AND current/ is gone, so any
+     * other interleaving leaves NO current/ slot. The device then has no bundle to
+     * load. A host that syncs on screen mount and again on foreground reproduces
+     * this in seconds; on 2026-09-21 it cost two devices that could only be
+     * recovered by reinstalling.
+     *
+     * Class-level, not per-instance: the manager is constructed in more than one
+     * place, so an instance lock would let two managers race the same directories.
+     * Recursive/reentrant so a future caller that already holds it cannot deadlock.
+     */
+    private static let slotLock = NSRecursiveLock()
+
+    /// Stage a downloaded bundle into the 'next' slot with SHA-256 verification.
+    func stage(sourcePath: String, expectedSha256: String, meta: [String: Any]) -> Bool {
+        OtaSlotManager.slotLock.lock()
+        defer { OtaSlotManager.slotLock.unlock() }
+        let fm = FileManager.default
+
+        do {
+            try fm.createDirectory(at: otaRoot, withIntermediateDirectories: true)
+
+            // Clean up orphaned temp dirs
+            cleanupTempDirs()
+
+            let tmpDir = otaRoot.appendingPathComponent("_tmp_\(UUID().uuidString)")
+            try fm.createDirectory(at: tmpDir, withIntermediateDirectories: true)
+
+            let tmpBundle = tmpDir.appendingPathComponent(OtaSlotManager.bundleFilename)
+            try fm.copyItem(at: URL(fileURLWithPath: sourcePath), to: tmpBundle)
+
+            // Verify SHA-256
+            guard let actualSha256 = sha256(fileURL: tmpBundle) else {
+                NSLog("[ScaleBunOta] Failed to compute SHA-256")
+                try? fm.removeItem(at: tmpDir)
+                return false
+            }
+
+            if actualSha256 != expectedSha256 {
+                NSLog("[ScaleBunOta] SHA-256 mismatch: expected=\(expectedSha256) actual=\(actualSha256)")
+                try? fm.removeItem(at: tmpDir)
+                return false
+            }
+
+            // Write meta.json. `.atomic` = write-to-temp + rename, so a crash or
+            // power loss mid-write can never leave a truncated meta.json — the
+            // Android side fsyncs for the same reason. A corrupt meta here would
+            // make the boot guard revert a perfectly healthy bundle.
+            let metaData = try JSONSerialization.data(withJSONObject: meta)
+            let tmpMeta = tmpDir.appendingPathComponent(OtaSlotManager.metaFilename)
+            try metaData.write(to: tmpMeta, options: .atomic)
+
+            // Atomic rename: delete old next, rename tmp → next
+            try? fm.removeItem(at: nextSlot)
+            try fm.moveItem(at: tmpDir, to: nextSlot)
+
+            NSLog("[ScaleBunOta] Staged bundle (sha256=\(actualSha256.prefix(12))…) to next/")
+            return true
+        } catch {
+            NSLog("[ScaleBunOta] stage() failed: \(error)")
+            return false
+        }
+    }
+
+    /// Apply: promote next → current (and current → previous). Sets the boot guard marker.
+    func apply() -> Bool {
+        OtaSlotManager.slotLock.lock()
+        defer { OtaSlotManager.slotLock.unlock() }
+        let fm = FileManager.default
+
+        do {
+            guard fm.fileExists(atPath: nextSlot.path) else {
+                NSLog("[ScaleBunOta] apply() called but next/ does not exist")
+                return false
+            }
+
+            // 1. Delete previous/
+            try? fm.removeItem(at: previousSlot)
+
+            // 2. current → previous
+            if fm.fileExists(atPath: currentSlot.path) {
+                try fm.moveItem(at: currentSlot, to: previousSlot)
+            }
+
+            // 3. next → current
+            try fm.moveItem(at: nextSlot, to: currentSlot)
+            // The active bundle just changed, so anything proven about the last
+            // one is void. This matters more on iOS than on Android: restartApp()
+            // reloads the BRIDGE, not the process, and this slot manager is a
+            // static that survives the reload — without this the freshly applied
+            // bundle would inherit the previous bundle's verdict and skip its own
+            // integrity re-check on the very launch that first executes it.
+            invalidateIntegrityCache()
+
+            // 4. Write boot_marker
+            writeBootMarker()
+
+            NSLog("[ScaleBunOta] Applied update — current/ now active")
+            return true
+        } catch {
+            NSLog("[ScaleBunOta] apply() failed: \(error)")
+            // Attempt recovery
+            if fm.fileExists(atPath: previousSlot.path) && !fm.fileExists(atPath: currentSlot.path) {
+                try? fm.moveItem(at: previousSlot, to: currentSlot)
+            }
+            return false
+        }
+    }
+
+    /// Mark the current bundle as healthy — clears the boot guard marker.
+    func markHealthy() {
+        if FileManager.default.fileExists(atPath: bootMarkerFile.path) {
+            try? FileManager.default.removeItem(at: bootMarkerFile)
+            NSLog("[ScaleBunOta] Boot marker cleared — bundle marked healthy")
+        }
+        // A bundle is only trusted for anti-downgrade once it has run healthily.
+        confirmCurrentSequence()
+    }
+
+    private var sequenceFile: URL { otaRoot.appendingPathComponent("highest_sequence") }
+
+    /// Highest CONFIRMED release sequence — the anti-downgrade floor (docs §15).
+    /// Raised only at markHealthy, so a failed/rolled-back higher sequence never
+    /// blocks a legitimate re-install.
+    func highestConfirmedSequence() -> Int64 {
+        guard let s = try? String(contentsOf: sequenceFile, encoding: .utf8),
+              let v = Int64(s.trimmingCharacters(in: .whitespacesAndNewlines)) else { return 0 }
+        return v
+    }
+
+    private func confirmCurrentSequence() {
+        guard let meta = readMeta(slot: currentSlot) else { return }
+        let seq: Int64
+        if let n = meta["releaseSequence"] as? Int64 { seq = n }
+        else if let n = meta["releaseSequence"] as? Int { seq = Int64(n) }
+        else if let n = meta["releaseSequence"] as? NSNumber { seq = n.int64Value }
+        else { return }
+        if seq > highestConfirmedSequence() {
+            try? FileManager.default.createDirectory(at: otaRoot, withIntermediateDirectories: true)
+            try? String(seq).write(to: sequenceFile, atomically: true, encoding: .utf8)
+        }
+    }
+
+    /// Revert to previous slot.
+    func revert(reason: String = "boot_guard") -> Bool {
+        OtaSlotManager.slotLock.lock()
+        defer { OtaSlotManager.slotLock.unlock() }
+        let fm = FileManager.default
+        // Every path out of here either removes current/ or replaces it from
+        // previous/, so the cached verdict is void before any of them run.
+        invalidateIntegrityCache()
+
+        // Leave a record so slotStateJSON can tell JS a revert happened. Without
+        // it `bootGuardReverted` was read by the orchestrator and written by
+        // nobody on iOS, so an auto-rollback that DID occur reported nothing —
+        // the dashboard counted zero rollbacks while devices were reverting.
+        // Stamp WHICH bundle is being reverted away from, read before current/ is
+        // removed below. Without it JS had nothing to name: slot meta carries no
+        // bundleId and the previous slot is gone by the time JS looks, so every
+        // AUTO_ROLLBACK reported bundleId "unknown" and the server dropped it as
+        // unresolvable — leaving the crash guard's rollback signal at zero.
+        var record: [String: Any] = [
+            "reason": reason,
+            "at": Int(Date().timeIntervalSince1970 * 1000),
+        ]
+        if let meta = readMeta(slot: currentSlot),
+           let failingSha = meta["sha256"] as? String, !failingSha.isEmpty {
+            record["sha256"] = failingSha
+        }
+        if let data = try? JSONSerialization.data(withJSONObject: record) {
+            try? data.write(to: revertRecordFile, options: .atomic)
+        }
+
+        do {
+            if !fm.fileExists(atPath: previousSlot.path) {
+                NSLog("[ScaleBunOta] No previous/ to revert to — clearing current/")
+                try? fm.removeItem(at: currentSlot)
+                try? fm.removeItem(at: bootMarkerFile)
+                try? fm.removeItem(at: nextSlot)
+                return true
+            }
+
+            try? fm.removeItem(at: currentSlot)
+            try fm.moveItem(at: previousSlot, to: currentSlot)
+            try? fm.removeItem(at: bootMarkerFile)
+            try? fm.removeItem(at: nextSlot)
+
+            NSLog("[ScaleBunOta] Reverted to previous bundle")
+            return true
+        } catch {
+            NSLog("[ScaleBunOta] revert() failed: \(error)")
+            return false
+        }
+    }
+
+    /// Boot guard check — called BEFORE JS loads.
+    func checkBootGuard() {
+        let fm = FileManager.default
+
+        guard fm.fileExists(atPath: bootMarkerFile.path) else { return }
+
+        do {
+            let markerData = try Data(contentsOf: bootMarkerFile)
+            // Prefer sha256; fall back to the legacy `bundleId` key so a marker
+            // left behind by a previous build is still readable.
+            guard let markerJson = try JSONSerialization.jsonObject(with: markerData) as? [String: Any],
+                  let markerId = (markerJson["sha256"] as? String)
+                      ?? (markerJson["bundleId"] as? String) else {
+                NSLog("[ScaleBunOta] Invalid boot marker — reverting")
+                _ = revert(reason: "invalid_marker")
+                return
+            }
+
+            let metaURL = currentSlot.appendingPathComponent(OtaSlotManager.metaFilename)
+            guard fm.fileExists(atPath: metaURL.path) else {
+                NSLog("[ScaleBunOta] Boot marker present but no current/meta.json — reverting")
+                _ = revert(reason: "missing_meta")
+                return
+            }
+
+            let metaData = try Data(contentsOf: metaURL)
+            guard let metaJson = try JSONSerialization.jsonObject(with: metaData) as? [String: Any],
+                  let currentId = metaJson["sha256"] as? String else {
+                NSLog("[ScaleBunOta] Invalid current/meta.json — reverting")
+                _ = revert(reason: "invalid_meta")
+                return
+            }
+
+            // Both sides must be real values for the comparison to mean
+            // anything. Comparing two empty strings is what made the Android
+            // equivalent vacuous; reverting on a legacy marker would revert
+            // bundles staged by an older build.
+            if markerId.isEmpty || currentId.isEmpty {
+                NSLog("[ScaleBunOta] Boot guard cannot verify this bundle — marker or meta has no sha256. Leaving it in place.")
+            } else if currentId != markerId {
+                NSLog("[ScaleBunOta] Boot marker sha256 mismatch — reverting")
+                _ = revert(reason: "hash_mismatch")
+            } else {
+                // ── Crash-loop revert ────────────────────────────────────────
+                // Matching hashes mean the bundle is INTACT, which says nothing
+                // about whether it RUNS. A bundle that throws at JS init installs
+                // cleanly, matches on every boot, and never reaches markHealthy()
+                // — so a hash-only guard let it crash-loop forever, bricking the
+                // app until reinstall. iOS had no counter at all, so this was the
+                // outcome on every iPhone.
+                //
+                // The marker doubles as a boot-attempt counter: each launch that
+                // still finds it increments it, and reaching the limit means the
+                // bundle has had its chances and never became healthy.
+                var marker = markerJson
+
+                // The counter cannot tell "the bundle crashed on startup" from
+                // "the app restarted itself on purpose" — both simply arrive
+                // with the marker still present. An update that installs and
+                // then restarts to activate would spend one of its two lives
+                // immediately, and any second restart inside the healthy window
+                // would spend the other and revert a bundle that was never
+                // broken. That is exactly what happened on Android before
+                // markIntentionalRestart(): six full downloads, five reverts,
+                // one cycle that happened to survive.
+                //
+                // restartApp() records its intent first. That load is expected,
+                // so it is not counted; the flag is one-shot, so a crash on the
+                // very next launch still counts and a genuinely broken bundle
+                // still goes.
+                if marker["intentionalRestart"] as? Bool == true {
+                    marker.removeValue(forKey: "intentionalRestart")
+                    if let data = try? JSONSerialization.data(withJSONObject: marker) {
+                        try? data.write(to: bootMarkerFile, options: .atomic)
+                    }
+                    NSLog("[ScaleBunOta] Boot guard: expected restart, not counted as a failed boot")
+                    return
+                }
+
+                let attempts = (marker["bootAttempts"] as? Int ?? 0) + 1
+                if attempts >= OtaSlotManager.maxBootAttempts {
+                    NSLog("[ScaleBunOta] Bundle failed to become healthy in \(attempts) launch(es) — reverting")
+                    _ = revert(reason: "boot_crash_guard")
+                    return
+                }
+                marker["bootAttempts"] = attempts
+                if let data = try? JSONSerialization.data(withJSONObject: marker) {
+                    try? data.write(to: bootMarkerFile, options: .atomic)
+                }
+                NSLog("[ScaleBunOta] Boot guard: attempt \(attempts)/\(OtaSlotManager.maxBootAttempts) for this bundle")
+            }
+        } catch {
+            NSLog("[ScaleBunOta] checkBootGuard() failed — reverting: \(error)")
+            _ = revert(reason: "boot_guard_error")
+        }
+    }
+
+    /// Returns JSON string with current slot state.
+    func slotStateJSON() -> String {
+        var state: [String: Any] = [
+            "bootMarkerPresent": FileManager.default.fileExists(atPath: bootMarkerFile.path)
+        ]
+        state["current"] = readMeta(slot: currentSlot) as Any
+        state["next"] = readMeta(slot: nextSlot) as Any
+        state["previous"] = readMeta(slot: previousSlot) as Any
+
+        // Consume-on-read: the orchestrator turns this into exactly one
+        // AUTO_ROLLBACK event. Leaving it would re-report the same rollback on
+        // every launch.
+        let fm = FileManager.default
+        if fm.fileExists(atPath: revertRecordFile.path) {
+            if let data = try? Data(contentsOf: revertRecordFile),
+               let rec = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
+                state["bootGuardReverted"] = true
+                state["bootGuardRevertReason"] = rec["reason"] as? String ?? "boot_guard"
+                state["bootGuardRevertedAt"] = rec["at"] as? Int ?? 0
+                // The bundle reverted AWAY from. JS joins it back to a bundle id
+                // through its install record so the rollback can be reported.
+                if let sha = rec["sha256"] as? String, !sha.isEmpty {
+                    state["bootGuardRevertedSha256"] = sha
+                }
+            }
+            try? fm.removeItem(at: revertRecordFile)
+        }
+
+        guard let data = try? JSONSerialization.data(withJSONObject: state),
+              let json = String(data: data, encoding: .utf8) else {
+            return "{\"current\":null,\"next\":null,\"previous\":null,\"bootMarkerPresent\":false}"
+        }
+        return json
+    }
+
+    // MARK: - Private Helpers
+
+    private func writeBootMarker() {
+        // Identify the bundle by SHA-256, not by `bundleId`.
+        //
+        // `stageBundle` is never told the bundleId — it writes a meta.json of
+        // just `sha256` and `installedAt`. So this used to `guard let bundleId`
+        // on an absent key and return early, meaning THE BOOT MARKER WAS NEVER
+        // WRITTEN. checkBootGuard() then returned immediately because no marker
+        // file existed, so the iOS boot guard never armed at all — a
+        // crash-looping bundle would never have been reverted.
+        //
+        // sha256 is the key that is actually present, and it is the better
+        // identity regardless: it detects a bundle whose CONTENT changed.
+        guard let meta = readMeta(slot: currentSlot),
+              let sha256 = meta["sha256"] else { return }
+
+        let marker: [String: Any] = [
+            "sha256": sha256,
+            "appliedAt": Int(Date().timeIntervalSince1970 * 1000)
+        ]
+
+        if let data = try? JSONSerialization.data(withJSONObject: marker) {
+            try? FileManager.default.createDirectory(at: otaRoot, withIntermediateDirectories: true)
+            // `.atomic`: a half-written marker is indistinguishable from a
+            // corrupt one, and checkBootGuard() reverts on corrupt markers —
+            // so a power cut here could have rolled back a healthy install.
+            try? data.write(to: bootMarkerFile, options: .atomic)
+        }
+    }
+
+    /// The installed bundle as a SIGNED patch base — twin of Android SlotManager.readSignedBase.
+    struct SignedBase {
+        let bytes: [UInt8]
+        let sha256: String
+        let bundleId: String?
+        let releaseSequence: Int64
+    }
+
+    /// The current bundle as a base for a SIGNED patch, or nil when it cannot be one: it must have
+    /// come through the signed path (meta carries `releaseSequence`), its bytes must still hash to
+    /// the recorded sha256 — computed on the SAME buffer returned, so what is hashed is what is
+    /// patched — and it is read under `slotLock`, because stage/apply/revert move these directories.
+    func readSignedBase() -> SignedBase? {
+        OtaSlotManager.slotLock.lock()
+        defer { OtaSlotManager.slotLock.unlock() }
+        guard let meta = readMeta(slot: currentSlot) else { return nil }
+        var sequence: Int64 = -1
+        if let n = meta["releaseSequence"] as? Int64 { sequence = n }
+        else if let n = meta["releaseSequence"] as? Int { sequence = Int64(n) }
+        else if let n = meta["releaseSequence"] as? NSNumber { sequence = n.int64Value }
+        guard sequence >= 0 else { return nil }
+        guard let recorded = meta["sha256"] as? String, !recorded.isEmpty else { return nil }
+        let url = currentSlot.appendingPathComponent(OtaSlotManager.bundleFilename)
+        guard let data = try? Data(contentsOf: url) else { return nil }
+        var hash = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
+        data.withUnsafeBytes { raw in
+            _ = CC_SHA256(raw.baseAddress, CC_LONG(data.count), &hash)
+        }
+        let actual = hash.map { String(format: "%02x", $0) }.joined()
+        guard actual.caseInsensitiveCompare(recorded) == .orderedSame else {
+            NSLog("[ScaleBunOta] readSignedBase: current bundle no longer matches its recorded hash")
+            return nil
+        }
+        let bundleId = (meta["bundleId"] as? String).flatMap { $0.isEmpty ? nil : $0 }
+        return SignedBase(bytes: [UInt8](data), sha256: actual, bundleId: bundleId, releaseSequence: sequence)
+    }
+
+    private func readMeta(slot: URL) -> [String: Any]? {
+        let metaURL = slot.appendingPathComponent(OtaSlotManager.metaFilename)
+        guard let data = try? Data(contentsOf: metaURL),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return nil
+        }
+        return json
+    }
+
+    private func cleanupTempDirs() {
+        guard let contents = try? FileManager.default.contentsOfDirectory(
+            at: otaRoot, includingPropertiesForKeys: nil
+        ) else { return }
+
+        for url in contents where url.lastPathComponent.hasPrefix("_tmp_") {
+            NSLog("[ScaleBunOta] Cleaning orphaned temp dir: \(url.lastPathComponent)")
+            try? FileManager.default.removeItem(at: url)
+        }
+    }
+
+    private func sha256(fileURL: URL) -> String? {
+        guard let data = try? Data(contentsOf: fileURL) else { return nil }
+
+        var hash = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
+        data.withUnsafeBytes { bytes in
+            _ = CC_SHA256(bytes.baseAddress, CC_LONG(data.count), &hash)
+        }
+        return hash.map { String(format: "%02x", $0) }.joined()
+    }
+}