@viettelpost/react-native-ota 0.1.0

package/ios/OTAUpdateDownloader.swift

@@ -0,0 +1,709 @@
+import Foundation
+
+struct OTADownloadInfo: Codable {
+  let version: String
+  let tempBundlePath: String
+  let finalBundlePath: String
+  let tempAssetsZipPath: String
+  let finalAssetsDirectoryPath: String
+  let tempExists: Bool
+  let finalExists: Bool
+  let tempAssetsZipExists: Bool
+  let finalAssetFileCount: Int
+  let tempSize: UInt64
+  let finalSize: UInt64
+  let tempAssetsZipSize: UInt64
+  let finalAssetsSize: UInt64
+  let tempSha256: String?
+  let finalSha256: String?
+  let tempAssetsSha256: String?
+  let signatureRequired: Bool
+}
+
+struct OTAUpdateDownloaderError: Error {
+  let code: String
+  let message: String
+  let underlyingError: Error?
+
+  init(code: String, message: String, underlyingError: Error? = nil) {
+    self.code = code
+    self.message = message
+    self.underlyingError = underlyingError
+  }
+
+  var nsError: NSError {
+    var userInfo: [String: Any] = [
+      NSLocalizedDescriptionKey: message,
+      "otaCode": code,
+    ]
+    if let underlyingError = underlyingError {
+      userInfo[NSUnderlyingErrorKey] = underlyingError as NSError
+    }
+    return NSError(domain: "OTAUpdateDownloader", code: 1, userInfo: userInfo)
+  }
+}
+
+private struct OTAUpdatePayload {
+  let version: String
+  let bundleUrl: String?
+  let assetsUrl: String?
+  let platform: String
+  let fileName: String
+  let sha256: String?
+  let assetsSha256: String?
+  let signature: String?
+}
+
+@objc(OTAUpdateDownloader)
+final class OTAUpdateDownloader: NSObject {
+  @objc static let shared = OTAUpdateDownloader()
+
+  private let storage = OTAUpdateStorage.shared
+  private let fileManager = FileManager.default
+  private let encoder = JSONEncoder()
+
+  private let bundleFileName = "main.jsbundle"
+  private let assetsZipFileName = "assets.zip"
+  private let platformIOS = "ios"
+  private let partialSuffix = ".download"
+
+  private let statusDownloaded = "downloaded"
+  private let statusDownloadFailed = "download_failed"
+  private let statusVerifying = "verifying"
+  private let statusVerified = "verified"
+  private let statusVerifyFailed = "verify_failed"
+  private let statusPending = "pending"
+
+  private let reasonDownloadFailed = "download_failed"
+  private let reasonMissingSha256 = "missing_sha256"
+  private let reasonMissingAssetsSha256 = "missing_assets_sha256"
+  private let reasonMissingSignature = "missing_signature"
+  private let reasonSignatureInvalid = "signature_invalid"
+  private let reasonSha256Mismatch = "sha256_mismatch"
+  private let reasonAssetsSha256Mismatch = "assets_sha256_mismatch"
+  private let reasonAssetsZipInvalid = "assets_zip_invalid"
+  private let reasonAssetsExtractFailed = "assets_extract_failed"
+  private let reasonTempBundleNotFoundForVerify = "temp_bundle_not_found_for_verify"
+  private let reasonTempAssetsNotFoundForVerify = "temp_assets_not_found_for_verify"
+  private let signatureMismatchMessage = "OTA signature mismatch. Check that version, platform, fileName, lowercase sha256, and assetsSha256 when assets are included exactly match the signed payload."
+
+  @objc func downloadAndInstallBundle(_ updateJson: String, completion: @escaping (NSNumber?, NSError?) -> Void) {
+    DispatchQueue.global(qos: .utility).async {
+      do {
+        _ = try self.downloadBundle(updateJson)
+        let didInstall = try self.installDownloadedBundle(updateJson)
+        completion(didInstall as NSNumber, nil)
+      } catch {
+        completion(nil, self.toNSError(error))
+      }
+    }
+  }
+
+  @objc func getDownloadInfo(_ version: String) throws -> String {
+    let normalizedVersion = try normalizeVersion(version)
+    let tempBundleURL = try tempBundleURL(version: normalizedVersion)
+    let finalBundleURL = try finalBundleURL(version: normalizedVersion)
+    let tempAssetsURL = try tempAssetsURL(version: normalizedVersion)
+    let finalAssetsDirectoryURL = try finalAssetsDirectoryURL(version: normalizedVersion)
+    let info = OTADownloadInfo(
+      version: normalizedVersion,
+      tempBundlePath: tempBundleURL.path,
+      finalBundlePath: finalBundleURL.path,
+      tempAssetsZipPath: tempAssetsURL.path,
+      finalAssetsDirectoryPath: finalAssetsDirectoryURL.path,
+      tempExists: fileExistsAndNonEmpty(tempBundleURL),
+      finalExists: fileExistsAndNonEmpty(finalBundleURL),
+      tempAssetsZipExists: fileExistsAndNonEmpty(tempAssetsURL),
+      finalAssetFileCount: directoryFileCount(finalAssetsDirectoryURL),
+      tempSize: fileSize(tempBundleURL),
+      finalSize: fileSize(finalBundleURL),
+      tempAssetsZipSize: fileSize(tempAssetsURL),
+      finalAssetsSize: directorySize(finalAssetsDirectoryURL),
+      tempSha256: try fileSha256IfExists(tempBundleURL),
+      finalSha256: try fileSha256IfExists(finalBundleURL),
+      tempAssetsSha256: try fileSha256IfExists(tempAssetsURL),
+      signatureRequired: true
+    )
+    let data = try encoder.encode(info)
+    guard let json = String(data: data, encoding: .utf8) else {
+      throw OTAUpdateDownloaderError(code: "OTA_GET_DOWNLOAD_INFO_FAILED", message: "Failed to encode OTA download info")
+    }
+    return json
+  }
+
+  private func downloadBundle(_ updateJson: String) throws -> String {
+    let update = try parsePayload(updateJson, requireBundleUrl: true)
+    try validateVersionCanInstall(update.version)
+
+    let tempDir = try tempBundleDirectory(version: update.version)
+    let partialURL = tempDir.appendingPathComponent(bundleFileName + partialSuffix)
+    let tempBundleURL = tempDir.appendingPathComponent(bundleFileName)
+    let partialAssetsURL = tempDir.appendingPathComponent(assetsZipFileName + partialSuffix)
+    let tempAssetsURL = tempDir.appendingPathComponent(assetsZipFileName)
+
+    try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+    try fileManager.createDirectory(at: tempDir, withIntermediateDirectories: true, attributes: nil)
+
+    do {
+      try downloadToFile(
+        urlString: update.bundleUrl ?? "",
+        destinationURL: partialURL
+      )
+      guard fileExistsAndNonEmpty(partialURL) else {
+        throw OTAUpdateDownloaderError(code: "OTA_DOWNLOAD_FAILED", message: "Downloaded OTA bundle is empty")
+      }
+      if fileManager.fileExists(atPath: tempBundleURL.path) {
+        try fileManager.removeItem(at: tempBundleURL)
+      }
+      do {
+        try fileManager.moveItem(at: partialURL, to: tempBundleURL)
+      } catch {
+        try fileManager.copyItem(at: partialURL, to: tempBundleURL)
+        try? fileManager.removeItem(at: partialURL)
+      }
+      guard fileExistsAndNonEmpty(tempBundleURL) else {
+        throw OTAUpdateDownloaderError(code: "OTA_DOWNLOAD_FAILED", message: "Downloaded OTA bundle was not finalized")
+      }
+
+      if let assetsUrl = update.assetsUrl, !assetsUrl.isEmpty {
+        try downloadToFile(
+          urlString: assetsUrl,
+          destinationURL: partialAssetsURL,
+          label: "OTA assets ZIP"
+        )
+        guard fileExistsAndNonEmpty(partialAssetsURL) else {
+          throw OTAUpdateDownloaderError(code: "OTA_ASSETS_DOWNLOAD_FAILED", message: "Downloaded OTA assets ZIP is empty")
+        }
+        if fileManager.fileExists(atPath: tempAssetsURL.path) {
+          try fileManager.removeItem(at: tempAssetsURL)
+        }
+        do {
+          try fileManager.moveItem(at: partialAssetsURL, to: tempAssetsURL)
+        } catch {
+          try fileManager.copyItem(at: partialAssetsURL, to: tempAssetsURL)
+          try? fileManager.removeItem(at: partialAssetsURL)
+        }
+        guard fileExistsAndNonEmpty(tempAssetsURL) else {
+          throw OTAUpdateDownloaderError(code: "OTA_ASSETS_DOWNLOAD_FAILED", message: "Downloaded OTA assets ZIP was not finalized")
+        }
+      }
+
+      var metadata = try storage.readMetadata()
+      metadata.status = statusDownloaded
+      metadata.failedBundleVersion = nil
+      metadata.lastFailureReason = nil
+      try storage.writeMetadata(metadata)
+      return tempBundleURL.path
+    } catch {
+      try? fileManager.removeItem(at: partialURL)
+      try? fileManager.removeItem(at: partialAssetsURL)
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+      var metadata = try storage.readMetadata()
+      metadata.status = statusDownloadFailed
+      metadata.failedBundleVersion = update.version
+      let otaError = error as? OTAUpdateDownloaderError
+      metadata.lastFailureReason = otaError?.code == "OTA_ASSETS_DOWNLOAD_FAILED" ? "assets_download_failed" : reasonDownloadFailed
+      try storage.writeMetadata(metadata)
+      if let otaError = otaError, otaError.code == "OTA_ASSETS_DOWNLOAD_FAILED" {
+        throw otaError
+      }
+      throw OTAUpdateDownloaderError(code: "OTA_DOWNLOAD_FAILED", message: "Failed to download OTA bundle for version \(update.version)", underlyingError: error)
+    }
+  }
+
+  private func verifyDownloadedBundle(_ updateJson: String) throws -> Bool {
+    let update = try parsePayload(updateJson, requireSha256: true)
+    return try verifyDownloadedBundle(update)
+  }
+
+  private func verifyUpdateSignature(_ updateJson: String) throws -> Bool {
+    let update = try parsePayload(
+      updateJson,
+      requireSha256: true,
+      requireSignature: true,
+      requireSigningFields: true
+    )
+    return try verifyUpdateSignature(update)
+  }
+
+  private func installDownloadedBundle(_ updateJson: String) throws -> Bool {
+    let update = try parsePayload(
+      updateJson,
+      requireSha256: true,
+      requireSignature: true,
+      requireSigningFields: true
+    )
+    try validateVersionCanInstall(update.version)
+    try verifyDownloadedUpdate(update)
+
+    let tempDir = try tempBundleDirectory(version: update.version)
+    let tempBundle = tempDir.appendingPathComponent(bundleFileName)
+    let tempAssets = tempDir.appendingPathComponent(assetsZipFileName)
+    guard fileExistsAndNonEmpty(tempBundle) else {
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+      throw OTAUpdateDownloaderError(code: "OTA_TEMP_BUNDLE_NOT_FOUND", message: "Downloaded OTA temp bundle was not found at \(tempBundle.path)")
+    }
+
+    let finalDir = try finalBundleDirectory(version: update.version)
+    let finalBundle = finalDir.appendingPathComponent(bundleFileName)
+    do {
+      _ = try OTAUpdateCleanup.shared.deleteFinalBundleForFailedInstall(version: update.version)
+      if fileManager.fileExists(atPath: finalDir.path) {
+        throw OTAUpdateDownloaderError(code: "OTA_INSTALL_FAILED", message: "Unable to clear previous OTA bundle directory")
+      }
+      try fileManager.createDirectory(at: finalDir, withIntermediateDirectories: true, attributes: nil)
+      try fileManager.copyItem(at: tempBundle, to: finalBundle)
+      guard fileExistsAndNonEmpty(finalBundle) else {
+        throw OTAUpdateDownloaderError(code: "OTA_INSTALL_FAILED", message: "Installed OTA bundle is missing or empty")
+      }
+      if update.assetsUrl?.isEmpty == false {
+        guard fileExistsAndNonEmpty(tempAssets) else {
+          try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+          try? OTAUpdateCleanup.shared.deleteFinalBundleForFailedInstall(version: update.version)
+          throw OTAUpdateDownloaderError(code: "OTA_TEMP_ASSETS_NOT_FOUND", message: "Downloaded OTA temp assets ZIP was not found at \(tempAssets.path)")
+        }
+        do {
+          try OTAZipUtils.unzip(zipURL: tempAssets, destinationURL: finalDir)
+        } catch {
+          try markVerifyFailed(version: update.version, reason: reasonAssetsExtractFailed)
+          try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+          try? OTAUpdateCleanup.shared.deleteFinalBundleForFailedInstall(version: update.version)
+          if let otaError = error as? OTAUpdateDownloaderError {
+            throw otaError
+          }
+          throw OTAUpdateDownloaderError(code: "OTA_ASSETS_EXTRACT_FAILED", message: "Failed to extract OTA assets for version \(update.version)", underlyingError: error)
+        }
+      }
+      do {
+        _ = try OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+      } catch {
+        NSLog("OTAKit cleanup temp after install failed: %@", error.localizedDescription)
+      }
+
+      var metadata = try storage.readMetadata()
+      metadata.previousBundleVersion = metadata.activeBundleVersion
+      metadata.pendingBundleVersion = update.version
+      metadata.status = statusPending
+      metadata.launchCountForPending = 0
+      metadata.failedBundleVersion = nil
+      metadata.lastFailureReason = nil
+      try storage.writeMetadata(metadata)
+      return true
+    } catch {
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+      try? OTAUpdateCleanup.shared.deleteFinalBundleForFailedInstall(version: update.version)
+      if let otaError = error as? OTAUpdateDownloaderError {
+        throw otaError
+      }
+      throw OTAUpdateDownloaderError(code: "OTA_INSTALL_FAILED", message: "Failed to install downloaded OTA bundle for version \(update.version)", underlyingError: error)
+    }
+  }
+
+  private func verifyDownloadedUpdate(_ update: OTAUpdatePayload) throws {
+    do {
+      _ = try verifyDownloadedBundle(update)
+      _ = try verifyUpdateSignature(update)
+    } catch {
+      if let otaError = error as? OTAUpdateDownloaderError,
+         otaError.code == "OTA_MISSING_SIGNATURE" ||
+         otaError.code == "OTA_SIGNATURE_INVALID" ||
+         otaError.code == "OTA_ASSETS_SHA256_MISMATCH" ||
+         otaError.code == "OTA_ASSETS_ZIP_INVALID" {
+        try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+      }
+      throw error
+    }
+  }
+
+  private func verifyDownloadedBundle(_ update: OTAUpdatePayload) throws -> Bool {
+    guard let expectedSha256 = update.sha256, !expectedSha256.isEmpty else {
+      try markVerifyFailed(version: update.version, reason: reasonMissingSha256)
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+      throw OTAUpdateDownloaderError(code: "OTA_MISSING_SHA256", message: "OTA update \(update.version) is missing required sha256")
+    }
+
+    let tempDir = try tempBundleDirectory(version: update.version)
+    let tempBundle = tempDir.appendingPathComponent(bundleFileName)
+    guard fileExistsAndNonEmpty(tempBundle) else {
+      try markVerifyFailed(version: update.version, reason: reasonTempBundleNotFoundForVerify)
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+      throw OTAUpdateDownloaderError(code: "OTA_TEMP_BUNDLE_NOT_FOUND", message: "Downloaded OTA temp bundle was not found at \(tempBundle.path)")
+    }
+
+    var metadata = try storage.readMetadata()
+    metadata.status = statusVerifying
+    metadata.failedBundleVersion = nil
+    metadata.lastFailureReason = nil
+    try storage.writeMetadata(metadata)
+
+    let actualSha256 = try OTAHashUtils.sha256(fileURL: tempBundle)
+    guard actualSha256.caseInsensitiveCompare(expectedSha256) == .orderedSame else {
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+      try markVerifyFailed(version: update.version, reason: reasonSha256Mismatch)
+      throw OTAUpdateDownloaderError(code: "OTA_SHA256_MISMATCH", message: "OTA SHA-256 verification failed for version \(update.version)")
+    }
+
+    if let assetsUrl = update.assetsUrl, !assetsUrl.isEmpty {
+      guard let expectedAssetsSha256 = update.assetsSha256, !expectedAssetsSha256.isEmpty else {
+        try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+        try markVerifyFailed(version: update.version, reason: reasonMissingAssetsSha256)
+        throw OTAUpdateDownloaderError(code: "OTA_MISSING_ASSETS_SHA256", message: "OTA update \(update.version) includes assetsUrl but is missing required assetsSha256")
+      }
+
+      let tempAssets = tempDir.appendingPathComponent(assetsZipFileName)
+      guard fileExistsAndNonEmpty(tempAssets) else {
+        try markVerifyFailed(version: update.version, reason: reasonTempAssetsNotFoundForVerify)
+        try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+        throw OTAUpdateDownloaderError(code: "OTA_TEMP_ASSETS_NOT_FOUND", message: "Downloaded OTA temp assets ZIP was not found at \(tempAssets.path)")
+      }
+
+      let actualAssetsSha256 = try OTAHashUtils.sha256(fileURL: tempAssets)
+      guard actualAssetsSha256.caseInsensitiveCompare(expectedAssetsSha256) == .orderedSame else {
+        try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+        try markVerifyFailed(version: update.version, reason: reasonAssetsSha256Mismatch)
+        throw OTAUpdateDownloaderError(code: "OTA_ASSETS_SHA256_MISMATCH", message: "OTA assets SHA-256 verification failed for version \(update.version)")
+      }
+
+      do {
+        try OTAZipUtils.validate(zipURL: tempAssets)
+      } catch {
+        try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+        try markVerifyFailed(version: update.version, reason: reasonAssetsZipInvalid)
+        if let otaError = error as? OTAUpdateDownloaderError {
+          throw otaError
+        }
+        throw OTAUpdateDownloaderError(code: "OTA_ASSETS_ZIP_INVALID", message: "OTA assets ZIP validation failed for version \(update.version)", underlyingError: error)
+      }
+    }
+
+    var verifiedMetadata = try storage.readMetadata()
+    verifiedMetadata.status = statusVerified
+    verifiedMetadata.failedBundleVersion = nil
+    verifiedMetadata.lastFailureReason = nil
+    try storage.writeMetadata(verifiedMetadata)
+    return true
+  }
+
+  private func verifyUpdateSignature(_ update: OTAUpdatePayload) throws -> Bool {
+    guard let signature = update.signature, !signature.isEmpty else {
+      try markVerifyFailed(version: update.version, reason: reasonMissingSignature)
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+      throw OTAUpdateDownloaderError(code: "OTA_MISSING_SIGNATURE", message: "OTA update \(update.version) is missing required signature")
+    }
+    let canonicalPayload = OTAUpdateSignatureVerifier.canonicalPayload(
+      version: update.version,
+      platform: update.platform,
+      fileName: update.fileName,
+      sha256: update.sha256 ?? "",
+      assetsSha256: update.assetsSha256
+    )
+    let isValid: Bool
+    do {
+      isValid = try OTAUpdateSignatureVerifier.verifySignature(
+        canonicalPayload: canonicalPayload,
+        base64Signature: signature
+      )
+    } catch {
+      NSLog(
+        "OTA signature verification error for version %@. Canonical payload used by iOS:\n%@",
+        update.version,
+        canonicalPayload
+      )
+      try? markVerifyFailed(version: update.version, reason: reasonSignatureInvalid)
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+      throw OTAUpdateDownloaderError(
+        code: "OTA_SIGNATURE_INVALID",
+        message: signatureMismatchMessage,
+        underlyingError: error
+      )
+    }
+
+    guard isValid else {
+      NSLog(
+        "OTA signature mismatch for version %@. Canonical payload used by iOS:\n%@",
+        update.version,
+        canonicalPayload
+      )
+      try markVerifyFailed(version: update.version, reason: reasonSignatureInvalid)
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: update.version)
+      throw OTAUpdateDownloaderError(code: "OTA_SIGNATURE_INVALID", message: signatureMismatchMessage)
+    }
+    return true
+  }
+
+  private func parsePayload(
+    _ updateJson: String,
+    requireBundleUrl: Bool = false,
+    requireSha256: Bool = false,
+    requireSignature: Bool = false,
+    requireSigningFields: Bool = false
+  ) throws -> OTAUpdatePayload {
+    guard let data = updateJson.data(using: .utf8),
+          let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+      throw OTAUpdateDownloaderError(code: "OTA_INVALID_UPDATE", message: "updateJson must be valid JSON")
+    }
+
+    let version = try normalizeVersion(stringValue(json["version"]))
+    let bundleUrl = stringValue(json["bundleUrl"])?.trimmingCharacters(in: .whitespacesAndNewlines)
+    if requireBundleUrl && (bundleUrl?.isEmpty ?? true) {
+      throw OTAUpdateDownloaderError(code: "OTA_INVALID_UPDATE", message: "bundleUrl must not be empty")
+    }
+
+    let rawAssetsUrl = stringValue(json["assetsUrl"])
+    let assetsUrl = rawAssetsUrl?.trimmingCharacters(in: .whitespacesAndNewlines)
+
+    let rawPlatform = stringValue(json["platform"])?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+    if requireSigningFields && (rawPlatform?.isEmpty ?? true) {
+      throw OTAUpdateDownloaderError(code: "OTA_INVALID_UPDATE", message: "platform must not be empty")
+    }
+    if let rawPlatform = rawPlatform, !rawPlatform.isEmpty, rawPlatform != platformIOS {
+      throw OTAUpdateDownloaderError(code: "OTA_INVALID_UPDATE", message: "platform must be ios")
+    }
+    let platform = rawPlatform?.isEmpty == false ? rawPlatform! : platformIOS
+
+    let rawFileName = stringValue(json["fileName"])?.trimmingCharacters(in: .whitespacesAndNewlines)
+    if requireSigningFields && (rawFileName?.isEmpty ?? true) {
+      throw OTAUpdateDownloaderError(code: "OTA_INVALID_UPDATE", message: "fileName must not be empty")
+    }
+    if let rawFileName = rawFileName, !rawFileName.isEmpty, rawFileName != bundleFileName {
+      throw OTAUpdateDownloaderError(code: "OTA_INVALID_UPDATE", message: "fileName must be \(bundleFileName)")
+    }
+    let fileName = rawFileName?.isEmpty == false ? rawFileName! : bundleFileName
+
+    let sha256 = stringValue(json["sha256"])?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+    if requireSha256 && (sha256?.isEmpty ?? true) {
+      try? markVerifyFailed(version: version, reason: reasonMissingSha256)
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: version)
+      throw OTAUpdateDownloaderError(code: "OTA_MISSING_SHA256", message: "OTA update \(version) is missing required sha256")
+    }
+
+    let assetsSha256 = stringValue(json["assetsSha256"])?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+    if requireSha256 && (assetsUrl?.isEmpty == false) && (assetsSha256?.isEmpty ?? true) {
+      try? markVerifyFailed(version: version, reason: reasonMissingAssetsSha256)
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: version)
+      throw OTAUpdateDownloaderError(code: "OTA_MISSING_ASSETS_SHA256", message: "OTA update \(version) includes assetsUrl but is missing required assetsSha256")
+    }
+
+    let signature = stringValue(json["signature"])?.trimmingCharacters(in: .whitespacesAndNewlines)
+    if requireSignature && (signature?.isEmpty ?? true) {
+      try? markVerifyFailed(version: version, reason: reasonMissingSignature)
+      try? OTAUpdateCleanup.shared.cleanupTemp(version: version)
+      throw OTAUpdateDownloaderError(code: "OTA_MISSING_SIGNATURE", message: "OTA update \(version) is missing required signature")
+    }
+
+    return OTAUpdatePayload(
+      version: version,
+      bundleUrl: bundleUrl,
+      assetsUrl: assetsUrl,
+      platform: platform,
+      fileName: fileName,
+      sha256: sha256,
+      assetsSha256: assetsSha256,
+      signature: signature
+    )
+  }
+
+  private func validateVersionCanInstall(_ version: String) throws {
+    let metadata = try storage.readMetadata()
+    if metadata.activeBundleVersion == version || metadata.pendingBundleVersion == version {
+      throw OTAUpdateDownloaderError(
+        code: "OTA_VERSION_ALREADY_EXISTS",
+        message: "OTA version already exists as active or pending. Use a new version and recalculate hashes for every rebuild. version=\(version)"
+      )
+    }
+  }
+
+  private func downloadToFile(urlString: String, destinationURL: URL, label: String = "OTA bundle") throws {
+    guard let url = URL(string: urlString) else {
+      throw OTAUpdateDownloaderError(code: "OTA_INVALID_UPDATE", message: "\(label) URL is invalid")
+    }
+
+    let semaphore = DispatchSemaphore(value: 0)
+    var result: Result<URL, Error>?
+    let configuration = URLSessionConfiguration.ephemeral
+    configuration.timeoutIntervalForRequest = 15
+    configuration.timeoutIntervalForResource = 60
+    let session = URLSession(configuration: configuration)
+    let task = session.downloadTask(with: url) { temporaryURL, response, error in
+      defer {
+        semaphore.signal()
+      }
+      if let error = error {
+        result = .failure(error)
+        return
+      }
+      if let response = response as? HTTPURLResponse, !(200...299).contains(response.statusCode) {
+        let code = label == "OTA assets ZIP" ? "OTA_ASSETS_DOWNLOAD_FAILED" : "OTA_DOWNLOAD_FAILED"
+        result = .failure(OTAUpdateDownloaderError(code: code, message: "HTTP \(response.statusCode) while downloading \(label)"))
+        return
+      }
+      guard let temporaryURL = temporaryURL else {
+        let code = label == "OTA assets ZIP" ? "OTA_ASSETS_DOWNLOAD_FAILED" : "OTA_DOWNLOAD_FAILED"
+        result = .failure(OTAUpdateDownloaderError(code: code, message: "URLSession did not produce a temporary file for \(label)"))
+        return
+      }
+      result = .success(temporaryURL)
+    }
+
+    task.resume()
+    semaphore.wait()
+    session.finishTasksAndInvalidate()
+
+    switch result {
+    case .success(let temporaryURL):
+      try fileManager.moveItem(at: temporaryURL, to: destinationURL)
+    case .failure(let error):
+      if let otaError = error as? OTAUpdateDownloaderError {
+        throw otaError
+      }
+      let code = label == "OTA assets ZIP" ? "OTA_ASSETS_DOWNLOAD_FAILED" : "OTA_DOWNLOAD_FAILED"
+      throw OTAUpdateDownloaderError(code: code, message: "Failed to download \(label)", underlyingError: error)
+    case .none:
+      let code = label == "OTA assets ZIP" ? "OTA_ASSETS_DOWNLOAD_FAILED" : "OTA_DOWNLOAD_FAILED"
+      throw OTAUpdateDownloaderError(code: code, message: "\(label) download did not complete")
+    }
+  }
+
+  private func tempBundleDirectory(version: String) throws -> URL {
+    try otaDirectory()
+      .appendingPathComponent("tmp", isDirectory: true)
+      .appendingPathComponent(version, isDirectory: true)
+  }
+
+  private func finalBundleDirectory(version: String) throws -> URL {
+    try otaDirectory()
+      .appendingPathComponent("bundles", isDirectory: true)
+      .appendingPathComponent(version, isDirectory: true)
+  }
+
+  private func tempBundleURL(version: String) throws -> URL {
+    try tempBundleDirectory(version: version).appendingPathComponent(bundleFileName)
+  }
+
+  private func tempAssetsURL(version: String) throws -> URL {
+    try tempBundleDirectory(version: version).appendingPathComponent(assetsZipFileName)
+  }
+
+  private func finalBundleURL(version: String) throws -> URL {
+    try finalBundleDirectory(version: version).appendingPathComponent(bundleFileName)
+  }
+
+  private func finalAssetsDirectoryURL(version: String) throws -> URL {
+    try finalBundleDirectory(version: version).appendingPathComponent("assets", isDirectory: true)
+  }
+
+  private func otaDirectory() throws -> URL {
+    let supportURL = try fileManager.url(
+      for: .applicationSupportDirectory,
+      in: .userDomainMask,
+      appropriateFor: nil,
+      create: true
+    )
+    let otaURL = supportURL.appendingPathComponent("OTA", isDirectory: true)
+    try fileManager.createDirectory(at: otaURL, withIntermediateDirectories: true, attributes: nil)
+    return otaURL
+  }
+
+  private func markVerifyFailed(version: String, reason: String) throws {
+    var metadata = try storage.readMetadata()
+    metadata.status = statusVerifyFailed
+    metadata.pendingBundleVersion = nil
+    metadata.failedBundleVersion = version
+    metadata.lastFailureReason = reason
+    try storage.writeMetadata(metadata)
+  }
+
+  private func fileExistsAndNonEmpty(_ url: URL) -> Bool {
+    fileManager.fileExists(atPath: url.path) && fileSize(url) > 0
+  }
+
+  private func directoryExistsAndHasFiles(_ url: URL) -> Bool {
+    guard let enumerator = fileManager.enumerator(at: url, includingPropertiesForKeys: nil) else {
+      return false
+    }
+    return enumerator.nextObject() != nil
+  }
+
+  private func fileSize(_ url: URL) -> UInt64 {
+    guard let attributes = try? fileManager.attributesOfItem(atPath: url.path),
+          let size = attributes[.size] as? NSNumber else {
+      return 0
+    }
+    return size.uint64Value
+  }
+
+  private func directorySize(_ url: URL) -> UInt64 {
+    guard let enumerator = fileManager.enumerator(at: url, includingPropertiesForKeys: [.fileSizeKey, .isRegularFileKey]) else {
+      return 0
+    }
+
+    var totalSize: UInt64 = 0
+    for case let fileURL as URL in enumerator {
+      let values = try? fileURL.resourceValues(forKeys: [.fileSizeKey, .isRegularFileKey])
+      if values?.isRegularFile == true, let fileSize = values?.fileSize {
+        totalSize += UInt64(fileSize)
+      }
+    }
+    return totalSize
+  }
+
+  private func directoryFileCount(_ url: URL) -> Int {
+    guard let enumerator = fileManager.enumerator(at: url, includingPropertiesForKeys: [.isRegularFileKey]) else {
+      return 0
+    }
+
+    var fileCount = 0
+    for case let fileURL as URL in enumerator {
+      let values = try? fileURL.resourceValues(forKeys: [.isRegularFileKey])
+      if values?.isRegularFile == true {
+        fileCount += 1
+      }
+    }
+    return fileCount
+  }
+
+  private func fileSha256IfExists(_ url: URL) throws -> String? {
+    guard fileExistsAndNonEmpty(url) else {
+      return nil
+    }
+    return try OTAHashUtils.sha256(fileURL: url)
+  }
+
+  private func normalizeVersion(_ version: String?) throws -> String {
+    let normalizedVersion = version?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+    if normalizedVersion.isEmpty {
+      throw OTAUpdateDownloaderError(code: "OTA_INVALID_UPDATE", message: "version must not be empty")
+    }
+    if normalizedVersion.contains("/") || normalizedVersion.contains("\\") {
+      throw OTAUpdateDownloaderError(code: "OTA_INVALID_UPDATE", message: "version must not contain path separators")
+    }
+    return normalizedVersion
+  }
+
+  private func stringValue(_ value: Any?) -> String? {
+    switch value {
+    case let value as String:
+      return value
+    case let value as NSNumber:
+      return value.stringValue
+    default:
+      return nil
+    }
+  }
+
+  private func toNSError(_ error: Error) -> NSError {
+    if let otaError = error as? OTAUpdateDownloaderError {
+      return otaError.nsError
+    }
+    var userInfo: [String: Any] = [
+      NSLocalizedDescriptionKey: error.localizedDescription,
+      "otaCode": "OTA_DOWNLOAD_AND_INSTALL_FAILED",
+    ]
+    userInfo[NSUnderlyingErrorKey] = error as NSError
+    return NSError(
+      domain: "OTAUpdateDownloader",
+      code: 1,
+      userInfo: userInfo
+    )
+  }
+}