@scalebun-release/react-native 2.5.0

package/ios/Ota/ScaleBunOtaModule.swift

@@ -0,0 +1,587 @@
+import Foundation
+import React
+import CommonCrypto
+
+/**
+ * React Native bridge for OTA bundle management (`ScaleBunOta`) on iOS.
+ *
+ * Sprint 2: real slot management via OtaSlotManager. All filesystem operations
+ * are delegated to the slot manager (pure Swift, no RN dependency).
+ *
+ * The static `getBundleURL()` method is called from the host app's
+ * AppDelegate.bundleURL() to resolve the active OTA bundle at launch.
+ *
+ * Selectors are pinned with explicit `@objc(...)` so they match the React Native
+ * Codegen-generated `NativeScaleBunOtaSpec` protocol on the New Architecture and
+ * the `RCT_EXTERN_*` declarations in the bridge on the Old Architecture.
+ */
+@objc(ScaleBunOta)
+class ScaleBunOtaModule: NSObject, RCTBridgeModule {
+
+    private static let slotManager = OtaSlotManager()
+
+    /// Trusted RSA public keys embedded in the app bundle (docs §9). Non-empty
+    /// once the app ships a `ScaleBunOtaKeys.json` resource — which flips staging
+    /// into the native-ENFORCED path (see `stageBundle`).
+    private static let keyRegistry = ScaleBunOtaKeyRegistry.fromBundle()
+
+    /// Device-derived verification context — never taken from JS.
+    private static func buildContext() -> ExpectedContext {
+        ExpectedContext(
+            projectId: keyRegistry.projectId,
+            applicationId: Bundle.main.bundleIdentifier ?? "",
+            currentSequence: slotManager.highestConfirmedSequence(),
+            nowEpochSeconds: Int64(Date().timeIntervalSince1970)
+        )
+    }
+
+    static func moduleName() -> String! { "ScaleBunOta" }
+
+    @objc static func requiresMainQueueSetup() -> Bool { false }
+
+    /**
+     * Static entry point for AppDelegate.bundleURL().
+     *
+     * Called BEFORE React Native initializes JS — this is where the boot
+     * guard runs and the active bundle URL is resolved.
+     *
+     * Returns nil in DEBUG builds (Metro always wins) or when no OTA
+     * bundle is installed.
+     *
+     * Usage in AppDelegate.mm:
+     * ```objc
+     * - (NSURL *)bundleURL {
+     *   #if DEBUG
+     *     return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
+     *   #else
+     *     NSURL *otaURL = [ScaleBunOtaModule getBundleURL];
+     *     if (otaURL) return otaURL;
+     *     return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
+     *   #endif
+     * }
+     * ```
+     */
+    @objc static func getBundleURL() -> URL? {
+        #if DEBUG
+        return nil
+        #else
+        slotManager.checkBootGuard()
+        return slotManager.currentBundleURL()
+        #endif
+    }
+
+    // MARK: - Bridge Methods
+
+    @objc(getActiveBundle)
+    func getActiveBundle() -> NSString? {
+        #if DEBUG
+        return nil
+        #else
+        guard let url = ScaleBunOtaModule.slotManager.currentBundleURL() else { return nil }
+        return url.path as NSString
+        #endif
+    }
+
+    @objc(getSlotState)
+    func getSlotState() -> NSString {
+        return ScaleBunOtaModule.slotManager.slotStateJSON() as NSString
+    }
+
+    /**
+     JSON array of jailbreak indicator strings; `[]` when none found.
+
+     The spec has always declared getDeviceIntegrity() and only Android
+     implemented it, so on iOS the orchestrator's root/jailbreak field was
+     permanently empty — reported as "no indicators" rather than as "not
+     measured", which reads as a clean fleet.
+
+     Empty is NOT a claim that the device is clean; see DeviceIntegrity.
+
+     Reported, never enforced HERE — the same split as Android. Native measures;
+     the policy (`ota.onCompromisedDevice`, 'allow' by default) is applied in JS
+     so it can change without a native release.
+     */
+    @objc(getDeviceIntegrity)
+    func getDeviceIntegrity() -> NSString {
+        let indicators = DeviceIntegrity.jailbreakIndicators()
+        if let data = try? JSONSerialization.data(withJSONObject: indicators),
+           let s = String(data: data, encoding: .utf8) {
+            return s as NSString
+        }
+        return "[]"
+    }
+
+    /// JSON array of the trusted key IDs embedded in this app (SDK trust coverage).
+    @objc(getTrustedKeyIds)
+    func getTrustedKeyIds() -> NSString {
+        let ids = ScaleBunOtaModule.keyRegistry.keyIds()
+        if let data = try? JSONSerialization.data(withJSONObject: ids),
+           let s = String(data: data, encoding: .utf8) {
+            return s as NSString
+        }
+        return "[]"
+    }
+
+    @objc(stageBundle:sha256:resolve:reject:)
+    /// Stage a bundle into the `next` slot.
+    ///
+    /// OTA-05: `sourcePath` may be an http(s) URL or a local file path. The JS
+    /// orchestrator has always passed `bundle.url` here while this method assumed
+    /// a filesystem path, so every install failed at staging. Accepting both keeps
+    /// the documented local-path contract for existing callers and makes the
+    /// orchestrator correct without a coordinated JS+native change.
+    func stageBundle(_ sourcePath: NSString,
+                     sha256: NSString,
+                     resolve: @escaping RCTPromiseResolveBlock,
+                     reject: @escaping RCTPromiseRejectBlock) {
+        // Native-enforced staging (docs §17): once trusted keys are embedded, the
+        // ONLY way to stage is verifyAndStageRelease, which proves an RSA signature
+        // over the release payload first. SHA-256 integrity alone (what this path
+        // checks) is not authenticity, so a hostile JS bundle cannot use it to
+        // drive an unauthenticated bundle onto the device.
+        if !ScaleBunOtaModule.keyRegistry.isEmpty {
+            NSLog("[ScaleBunOta] stageBundle refused: trusted keys embedded — use verifyAndStageRelease")
+            resolve(false)
+            return
+        }
+        let source = sourcePath as String
+        let meta: [String: Any] = [
+            "sha256": sha256 as String,
+            "installedAt": Int(Date().timeIntervalSince1970 * 1000)
+        ]
+
+        let lowered = source.lowercased()
+        var downloadedTo: URL?
+
+        let localPath: String
+        if lowered.hasPrefix("http://") || lowered.hasPrefix("https://") {
+            let temp = FileManager.default.temporaryDirectory
+                .appendingPathComponent("scalebun_ota_dl_\(UUID().uuidString)")
+            downloadedTo = temp
+            guard BundleDownloader.download(urlString: source, destination: temp) else {
+                resolve(false)
+                return
+            }
+            localPath = temp.path
+        } else {
+            localPath = source
+        }
+
+        // The slot manager copies into its own `_tmp_` directory and verifies the
+        // SHA-256 there, so this download is never the file that gets promoted.
+        let success = ScaleBunOtaModule.slotManager.stage(
+            sourcePath: localPath,
+            expectedSha256: sha256 as String,
+            meta: meta
+        )
+
+        if let downloadedTo = downloadedTo {
+            try? FileManager.default.removeItem(at: downloadedTo)
+        }
+        resolve(success)
+    }
+
+    @objc(stagePatch:patchSha256:expectedSha256:resolve:reject:)
+    /// Binary-patch staging (S7-NAT-1).
+    ///
+    /// Downloads a delta, reconstructs the full bundle from the currently
+    /// installed one, and hands the result to the ordinary staging path — so a
+    /// patched bundle passes exactly the same SHA-256 and slot-promotion checks
+    /// as a fully downloaded one. `expectedSha256` is the hash of the COMPLETE
+    /// bundle, which is what makes a bad patch unable to install: reconstruct
+    /// the wrong bytes and staging rejects them.
+    ///
+    /// Resolves `false` — never rejects — for every "cannot patch" case, because
+    /// `src/specs/NativeScaleBunOta.ts` defines false as "patching unavailable,
+    /// fall back to a full download". The update still lands, just larger.
+    func stagePatch(_ patchUrl: NSString,
+                    patchSha256: NSString,
+                    expectedSha256: NSString,
+                    resolve: @escaping RCTPromiseResolveBlock,
+                    reject: @escaping RCTPromiseRejectBlock) {
+        // Same native-enforcement as stageBundle: a bsdiff patch staged by hash
+        // alone carries no signature, so once trusted keys are embedded this path
+        // is closed. Result-anchored signed patches are a native follow-up; until
+        // then the SDK falls back to the verified full download. false = "patch
+        // unavailable".
+        if !ScaleBunOtaModule.keyRegistry.isEmpty {
+            NSLog("[ScaleBunOta] stagePatch disabled while trusted keys are embedded — full verified download")
+            resolve(false)
+            return
+        }
+        // Patching is relative to the bundle already on disk. With no OTA bundle
+        // installed the source would be the app's built-in bundle, which the
+        // server did not diff against — so a full download is the correct path.
+        guard let currentURL = ScaleBunOtaModule.slotManager.currentBundleURL(),
+              let sourceData = try? Data(contentsOf: currentURL) else {
+            NSLog("[ScaleBunOta] stagePatch: no current OTA bundle to patch — full download")
+            resolve(false)
+            return
+        }
+
+        let temp = FileManager.default.temporaryDirectory
+            .appendingPathComponent("scalebun_ota_patch_\(UUID().uuidString)")
+        defer { try? FileManager.default.removeItem(at: temp) }
+
+        guard BundleDownloader.download(urlString: patchUrl as String, destination: temp),
+              let patchData = try? Data(contentsOf: temp) else {
+            resolve(false)
+            return
+        }
+
+        // Verify the patch against its own hash before parsing it. Cheap, and it
+        // keeps obviously-corrupt input away from the parser.
+        guard let actualPatchSha = ScaleBunOtaModule.sha256Hex(patchData),
+              actualPatchSha.caseInsensitiveCompare(patchSha256 as String) == .orderedSame else {
+            NSLog("[ScaleBunOta] stagePatch: patch hash mismatch — full download")
+            resolve(false)
+            return
+        }
+
+        let rebuilt: [UInt8]
+        do {
+            rebuilt = try BsPatch.apply(source: [UInt8](sourceData), patch: [UInt8](patchData))
+        } catch {
+            NSLog("[ScaleBunOta] stagePatch: \(error) — full download")
+            resolve(false)
+            return
+        }
+
+        let rebuiltURL = FileManager.default.temporaryDirectory
+            .appendingPathComponent("scalebun_ota_rebuilt_\(UUID().uuidString)")
+        defer { try? FileManager.default.removeItem(at: rebuiltURL) }
+
+        do {
+            try Data(rebuilt).write(to: rebuiltURL)
+        } catch {
+            NSLog("[ScaleBunOta] stagePatch: could not write rebuilt bundle — full download")
+            resolve(false)
+            return
+        }
+
+        let meta: [String: Any] = [
+            "sha256": expectedSha256 as String,
+            "installedAt": Int(Date().timeIntervalSince1970 * 1000),
+            "patched": true
+        ]
+
+        // The slot manager re-hashes and compares against the full-bundle hash;
+        // a mis-applied patch cannot get past this.
+        let success = ScaleBunOtaModule.slotManager.stage(
+            sourcePath: rebuiltURL.path,
+            expectedSha256: expectedSha256 as String,
+            meta: meta
+        )
+        if !success {
+            NSLog("[ScaleBunOta] stagePatch: rebuilt bundle failed verification — full download")
+        }
+        resolve(success)
+    }
+
+    /// Hex SHA-256 of in-memory bytes. The slot manager has a file-based twin;
+    /// this one avoids a round-trip through disk for the downloaded patch.
+    private static func sha256Hex(_ data: Data) -> String? {
+        var digest = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
+        data.withUnsafeBytes { buf in
+            _ = CC_SHA256(buf.baseAddress, CC_LONG(data.count), &digest)
+        }
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    @objc(applyUpdate:reject:)
+    func applyUpdate(_ resolve: @escaping RCTPromiseResolveBlock,
+                     reject: @escaping RCTPromiseRejectBlock) {
+        let success = ScaleBunOtaModule.slotManager.apply()
+        resolve(success)
+    }
+
+    @objc(markHealthy)
+    func markHealthy() {
+        ScaleBunOtaModule.slotManager.markHealthy()
+    }
+
+    @objc(revertToPrevious:reject:)
+    func revertToPrevious(_ resolve: @escaping RCTPromiseResolveBlock,
+                          reject: @escaping RCTPromiseRejectBlock) {
+        let success = ScaleBunOtaModule.slotManager.revert()
+        resolve(success)
+    }
+
+    /**
+     * Restart the React runtime so the applied bundle loads NOW.
+     *
+     * `DevSettings.reload()` is a silent no-op in release builds (verified live
+     * on Android; the iOS DevSettings path shares the design). RCTReloadCommand
+     * is the mechanism React Native itself uses for every reload.
+     *
+     * REPORTED: on RN 0.87 bridgeless, restartApp left the OLD bundle running
+     * and only a cold start picked up the new one. The cause is NOT in here.
+     *
+     * RCTHost._reloadWithShouldRestartSurfaces does re-resolve:
+     *
+     *     [_instance invalidate];
+     *     if (_bundleURLProvider) { [self _setBundleURL:_bundleURLProvider()]; }
+     *
+     * So a reload DOES ask again — provided the host was built with a provider.
+     * RCTHost also offers `initWithBundleURL:`, which wraps a STATIC url in a
+     * provider that returns that same constant forever. A host constructed that
+     * way can never see a new bundle, no matter how the reload is triggered, and
+     * that is what "only a cold start works" looks like.
+     *
+     * Note also that RCTReloadCommandSetBundleURL only populates
+     * RCTTriggerReloadCommandBundleURLKey on the notification, and nothing in
+     * React Native reads that key — RCTHost conforms to RCTReloadListener, whose
+     * didReceiveReloadCommand takes no URL. Setting it here would look like a fix
+     * and do nothing.
+     *
+     * So the fix belongs in the host app: the AppDelegate must resolve
+     * `bundleURL` per call (see getBundleURL above), and the host must be created
+     * with the PROVIDER initializer rather than a captured URL. `scalebun doctor`
+     * is the place to detect that, not this method.
+     *
+     * Dispatched to the main thread: reload tears down UI.
+     */
+    @objc(restartApp)
+    func restartApp() {
+        // Tell the boot guard this next load is ours.
+        //
+        // Hooked HERE rather than at the JS call sites so it cannot be forgotten:
+        // every restart the SDK performs goes through this method. Recorded
+        // before the reload is dispatched, because after it there is no "after".
+        //
+        // The flag is one-shot and is consumed by whichever boot guard runs
+        // next — the reload's, or the next cold start's if the reload does not
+        // re-resolve. Either way the activation restart is not counted as a
+        // failed boot.
+        ScaleBunOtaModule.slotManager.markIntentionalRestart()
+
+        // Resolved OFF the main thread: currentBundleURL() re-hashes the active
+        // bundle on first call, and a 20-50 MB hash on the main thread is a
+        // visible stall at exactly the moment the UI is being torn down. Logged
+        // rather than acted on — it is what the reload SHOULD land on, so a log
+        // line that disagrees with what renders afterwards localises the problem
+        // to the host's bundleURL wiring in one step.
+        let target = ScaleBunOtaModule.slotManager.currentBundleURL()
+        if let target {
+            NSLog("[ScaleBunOta] restartApp: reloading onto \(target.lastPathComponent)")
+        } else {
+            NSLog("[ScaleBunOta] restartApp: no valid OTA bundle — expecting the binary baseline")
+        }
+
+        DispatchQueue.main.async {
+            RCTTriggerReloadCommandListeners("ScaleBun OTA update")
+        }
+    }
+
+    /**
+     * Verify a SB-OTA-RSA-SHA256-V1 release envelope with PLATFORM crypto
+     * (`SecKeyVerifySignature`) and the EMBEDDED trusted-key registry — no
+     * download, no side effects. Resolves the verdict JSON (`{ ok, code?, keyId?,
+     * releaseId?, bundleId?, releaseSequence?, artifactSha256?, artifactSize?,
+     * resultArtifactSha256?, fingerprint? }`). A failed check is `ok:false` with a
+     * stable `code`, never a rejected promise. Native because the JS verifier
+     * lives inside the very bundle it protects, and the trusted key must come from
+     * the app bundle, not from JS or the server.
+     *
+     * The verifier this calls into (OtaProtocol + ScaleBunOtaKeyRegistry +
+     * ScaleBunOtaReleaseVerifier) is compiled and executed on every CI run by
+     * ci.yml's `ios-ota-verifier` job — `swift test` on macOS against the shared
+     * fixtures in packages/ota-protocol/fixtures, alongside the JVM parity harness.
+     * THIS file is not in that package (it imports React); it is compiled by
+     * native-build.yml inside a scaffolded host app instead.
+     */
+    @objc(verifyRelease:resolve:reject:)
+    func verifyRelease(_ envelopeJson: NSString,
+                       resolve: @escaping RCTPromiseResolveBlock,
+                       reject: @escaping RCTPromiseRejectBlock) {
+        let verdict = ScaleBunOtaReleaseVerifier.verify(
+            envelopeJson: envelopeJson as String,
+            expected: ScaleBunOtaModule.buildContext(),
+            registry: ScaleBunOtaModule.keyRegistry
+        )
+        resolve(verdict.toJson())
+    }
+
+    /**
+     * Native-ENFORCED install (docs §5, §17): verify the RSA signature against an
+     * embedded key, THEN download, enforce the SIGNED size + SHA-256, and stage
+     * into the `next` slot. JS never stages bytes that were not proven authentic
+     * (once keys are embedded, `stageBundle` refuses). Does not activate —
+     * `applyUpdate` promotes per the install mode. Resolves the verdict JSON.
+     */
+    @objc(verifyAndStageRelease:resolve:reject:)
+    func verifyAndStageRelease(_ envelopeJson: NSString,
+                               resolve: @escaping RCTPromiseResolveBlock,
+                               reject: @escaping RCTPromiseRejectBlock) {
+        let verdict = ScaleBunOtaReleaseVerifier.verify(
+            envelopeJson: envelopeJson as String,
+            expected: ScaleBunOtaModule.buildContext(),
+            registry: ScaleBunOtaModule.keyRegistry
+        )
+        guard verdict.ok, let payload = verdict.payload else {
+            resolve(verdict.toJson())
+            return
+        }
+
+        guard let data = (envelopeJson as String).data(using: .utf8),
+              let env = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let url = env["downloadUrl"] as? String, !url.isEmpty else {
+            resolve(Verdict.fail(.DOWNLOAD_FAILED, "envelope has no downloadUrl").toJson())
+            return
+        }
+
+        let temp = FileManager.default.temporaryDirectory
+            .appendingPathComponent("scalebun_ota_dl_\(UUID().uuidString)")
+        defer { try? FileManager.default.removeItem(at: temp) }
+
+        if let failure = BundleDownloader.downloadWithReason(urlString: url, destination: temp) {
+            // The reason rides beside the code (never inside it): JS decides whether to
+            // retry on it and re-validates it before it reaches the wire.
+            resolve(Verdict.fail(.DOWNLOAD_FAILED, "download failed", reason: failure).toJson())
+            return
+        }
+        // Size first (cheap) against the SIGNED artifactSize.
+        let attrs = try? FileManager.default.attributesOfItem(atPath: temp.path)
+        let fileSize = (attrs?[.size] as? NSNumber)?.int64Value ?? -1
+        if fileSize != payload.artifactSize {
+            resolve(Verdict.fail(.ARTIFACT_SIZE_MISMATCH, "downloaded size mismatch").toJson())
+            return
+        }
+
+        // The slot manager streams a SHA-256 and compares against the signed
+        // artifactSha256 (== resultArtifactSha256 for a full artifact), so a wrong
+        // download cannot be staged. meta carries the sequence used by the
+        // anti-downgrade floor once the bundle is confirmed healthy.
+        let meta: [String: Any] = [
+            "sha256": payload.artifactSha256,
+            "releaseSequence": payload.releaseSequence,
+            "bundleId": payload.bundleId,
+            "releaseId": payload.releaseId,
+            "installedAt": Int(Date().timeIntervalSince1970 * 1000)
+        ]
+        let staged = ScaleBunOtaModule.slotManager.stage(
+            sourcePath: temp.path,
+            expectedSha256: payload.artifactSha256,
+            meta: meta
+        )
+        if !staged {
+            resolve(Verdict.fail(.ARTIFACT_HASH_MISMATCH, "staged bytes failed hash check").toJson())
+            return
+        }
+        resolve(verdict.toJson())
+    }
+
+    /// Stage a SIGNED release from a patch — twin of Android verifyAndStagePatch; see
+    /// NativeScaleBunOta.verifyAndStagePatch. Order is the security argument: verified envelope
+    /// (size/hash/sequence from the payload only) → signed base under the slot lock → capped patch
+    /// download + transport hash → BsPatch bound to the SIGNED size → stage only if the result
+    /// hashes to the SIGNED artifactSha256. Every failure resolves ok:false; JS falls back to
+    /// verifyAndStageRelease.
+    @objc(verifyAndStagePatch:patchJson:resolve:reject:)
+    func verifyAndStagePatch(_ envelopeJson: NSString,
+                             patchJson: NSString,
+                             resolve: @escaping RCTPromiseResolveBlock,
+                             reject: @escaping RCTPromiseRejectBlock) {
+        let verdict = ScaleBunOtaReleaseVerifier.verify(
+            envelopeJson: envelopeJson as String,
+            expected: ScaleBunOtaModule.buildContext(),
+            registry: ScaleBunOtaModule.keyRegistry
+        )
+        guard verdict.ok, let payload = verdict.payload else {
+            resolve(verdict.toJson())
+            return
+        }
+        guard payload.resultArtifactSha256.caseInsensitiveCompare(payload.artifactSha256) == .orderedSame else {
+            resolve(Verdict.fail(.PATCH_RESULT_MISMATCH, "payload is not a full release").toJson())
+            return
+        }
+
+        guard let pdata = (patchJson as String).data(using: .utf8),
+              let p = try? JSONSerialization.jsonObject(with: pdata) as? [String: Any],
+              let patchUrl = p["url"] as? String, !patchUrl.isEmpty,
+              let patchSha = p["sha256"] as? String, !patchSha.isEmpty,
+              let baseBundleId = p["baseBundleId"] as? String, !baseBundleId.isEmpty,
+              let patchSize = (p["size"] as? NSNumber)?.int64Value, patchSize > 0 else {
+            resolve(Verdict.fail(.PATCH_BASE_MISMATCH, "patch descriptor incomplete").toJson())
+            return
+        }
+        guard patchSize < payload.artifactSize else {
+            resolve(Verdict.fail(.PATCH_BASE_MISMATCH, "patch is not smaller than the release").toJson())
+            return
+        }
+
+        let baseSha = (p["baseSha256"] as? String) ?? ""
+        guard let base = ScaleBunOtaModule.slotManager.readSignedBase(),
+              base.bundleId == baseBundleId,
+              baseSha.isEmpty || baseSha.caseInsensitiveCompare(base.sha256) == .orderedSame else {
+            resolve(Verdict.fail(.PATCH_BASE_MISMATCH, "installed bundle is not this patch's signed base").toJson())
+            return
+        }
+
+        let fm = FileManager.default
+        let temp = fm.temporaryDirectory.appendingPathComponent("scalebun_ota_patch_\(UUID().uuidString)")
+        let rebuilt = fm.temporaryDirectory.appendingPathComponent("scalebun_ota_rebuilt_\(UUID().uuidString)")
+        defer {
+            try? fm.removeItem(at: temp)
+            try? fm.removeItem(at: rebuilt)
+        }
+
+        if let failure = BundleDownloader.downloadWithReason(urlString: patchUrl, destination: temp) {
+            resolve(Verdict.fail(.DOWNLOAD_FAILED, "patch download failed", reason: failure).toJson())
+            return
+        }
+        guard let patchData = try? Data(contentsOf: temp), Int64(patchData.count) == patchSize else {
+            resolve(Verdict.fail(.ARTIFACT_SIZE_MISMATCH, "patch size mismatch").toJson())
+            return
+        }
+        var hash = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
+        patchData.withUnsafeBytes { raw in _ = CC_SHA256(raw.baseAddress, CC_LONG(patchData.count), &hash) }
+        let actualPatchSha = hash.map { String(format: "%02x", $0) }.joined()
+        guard actualPatchSha.caseInsensitiveCompare(patchSha) == .orderedSame else {
+            resolve(Verdict.fail(.ARTIFACT_HASH_MISMATCH, "patch hash mismatch").toJson())
+            return
+        }
+
+        let rebuiltBytes: [UInt8]
+        do {
+            rebuiltBytes = try BsPatch.apply(
+                source: base.bytes,
+                patch: [UInt8](patchData),
+                expectedTargetSize: Int(payload.artifactSize)
+            )
+        } catch {
+            resolve(Verdict.fail(.PATCH_RESULT_MISMATCH, "patch rejected").toJson())
+            return
+        }
+        do {
+            try Data(rebuiltBytes).write(to: rebuilt)
+        } catch {
+            resolve(Verdict.fail(.INTERNAL_VERIFICATION_ERROR, "could not write rebuilt bundle").toJson())
+            return
+        }
+
+        let meta: [String: Any] = [
+            "sha256": payload.artifactSha256,
+            "releaseSequence": payload.releaseSequence,
+            "bundleId": payload.bundleId,
+            "releaseId": payload.releaseId,
+            "installedAt": Int(Date().timeIntervalSince1970 * 1000),
+            "patched": true
+        ]
+        // The slot manager re-hashes the rebuilt bytes against the SIGNED hash: a patch that
+        // produced anything else cannot be staged, whatever the base or the patch contained.
+        guard ScaleBunOtaModule.slotManager.stage(
+            sourcePath: rebuilt.path,
+            expectedSha256: payload.artifactSha256,
+            meta: meta
+        ) else {
+            resolve(Verdict.fail(.PATCH_RESULT_MISMATCH, "rebuilt bundle does not match the signed hash").toJson())
+            return
+        }
+
+        var out = (try? JSONSerialization.jsonObject(with: Data(verdict.toJson().utf8)) as? [String: Any]) ?? ["ok": true]
+        out["patchUsed"] = true
+        let json = (try? JSONSerialization.data(withJSONObject: out)).flatMap { String(data: $0, encoding: .utf8) }
+        resolve(json ?? "{\"ok\":true,\"patchUsed\":true}")
+    }
+}