@otakit/capacitor-updater 1.0.0 → 1.2.0

package/ios/Sources/UpdaterPlugin/ManifestVerifier.swift

@@ -19,7 +19,7 @@ enum ManifestVerifier {
   ///
   /// - Parameters:
   ///   - appId, channel, platform: Request context (known by plugin).
-  ///   - version, sha256, size, minNativeBuild: Response fields.
+  ///   - version, sha256, size, runtimeVersion: Response fields.
   ///   - signature: The signature object from the manifest response.
   ///   - trustedKeys: Array of verification keys configured in the plugin.
   ///
@@ -31,22 +31,10 @@ enum ManifestVerifier {
     version: String,
     sha256: String,
     size: Int,
-    minNativeBuild: Int?,
+    runtimeVersion: String?,
     signature: ManifestSignature,
     trustedKeys: [ManifestKey]
   ) throws {
-    // Check expiry
-    let now = Int(Date().timeIntervalSince1970)
-    guard signature.exp > now else {
-      throw ManifestVerifierError.expired
-    }
-
-    // Find matching key
-    guard let keyEntry = trustedKeys.first(where: { $0.kid == signature.kid }) else {
-      throw ManifestVerifierError.unknownKid(signature.kid)
-    }
-
-    // Build canonical payload (must match server exactly)
     let payload = buildCanonicalPayload(
       appId: appId,
       channel: channel,
@@ -54,11 +42,53 @@ enum ManifestVerifier {
       version: version,
       sha256: sha256,
       size: size,
-      minNativeBuild: minNativeBuild,
+      runtimeVersion: runtimeVersion,
       kid: signature.kid,
       iat: signature.iat,
       exp: signature.exp
     )
+    try verifyPayload(payload, signature: signature, trustedKeys: trustedKeys)
+  }
+
+  static func verifyLegacy(
+    appId: String,
+    channel: String?,
+    platform: String,
+    version: String,
+    sha256: String,
+    size: Int,
+    signature: ManifestSignature,
+    trustedKeys: [ManifestKey]
+  ) throws {
+    let payload = buildLegacyCanonicalPayload(
+      appId: appId,
+      channel: channel,
+      platform: platform,
+      version: version,
+      sha256: sha256,
+      size: size,
+      kid: signature.kid,
+      iat: signature.iat,
+      exp: signature.exp
+    )
+    try verifyPayload(payload, signature: signature, trustedKeys: trustedKeys)
+  }
+
+  private static func verifyPayload(
+    _ payload: String,
+    signature: ManifestSignature,
+    trustedKeys: [ManifestKey]
+  ) throws {
+    // Check expiry
+    let now = Int(Date().timeIntervalSince1970)
+    guard signature.exp > now else {
+      throw ManifestVerifierError.expired
+    }
+
+    // Find matching key
+    guard let keyEntry = trustedKeys.first(where: { $0.kid == signature.kid }) else {
+      throw ManifestVerifierError.unknownKid(signature.kid)
+    }
 
     // Decode base64url signature
     guard let sigData = base64UrlDecode(signature.sig) else {
@@ -81,12 +111,37 @@ enum ManifestVerifier {
     version: String,
     sha256: String,
     size: Int,
-    minNativeBuild: Int?,
+    runtimeVersion: String?,
+    kid: String,
+    iat: Int,
+    exp: Int
+  ) -> String {
+    return [
+      "MANIFEST_V2",
+      "appId:\(appId)",
+      "channel:\(channel ?? "null")",
+      "platform:\(platform)",
+      "version:\(version)",
+      "sha256:\(sha256)",
+      "size:\(size)",
+      "runtimeVersion:\(runtimeVersion ?? "null")",
+      "kid:\(kid)",
+      "iat:\(iat)",
+      "exp:\(exp)",
+    ].joined(separator: "\n")
+  }
+
+  private static func buildLegacyCanonicalPayload(
+    appId: String,
+    channel: String?,
+    platform: String,
+    version: String,
+    sha256: String,
+    size: Int,
     kid: String,
     iat: Int,
     exp: Int
   ) -> String {
-    let minBuildStr = minNativeBuild.map { String($0) } ?? "null"
     return [
       "MANIFEST_V1",
       "appId:\(appId)",
@@ -95,7 +150,7 @@ enum ManifestVerifier {
       "version:\(version)",
       "sha256:\(sha256)",
       "size:\(size)",
-      "minNativeBuild:\(minBuildStr)",
+      "minNativeBuild:null",
       "kid:\(kid)",
       "iat:\(iat)",
       "exp:\(exp)",

package/ios/Sources/UpdaterPlugin/UpdaterPlugin.swift

@@ -7,9 +7,15 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
   private enum UpdateMode: String {
     case manual
     case nextLaunch = "next-launch"
+    case nextResume = "next-resume"
     case immediate
   }
 
+  private enum Trigger {
+    case launch
+    case resume
+  }
+
   public let identifier = "UpdaterPlugin"
   public let jsName = "OtaKit"
   public let pluginMethods: [CAPPluginMethod] = [
@@ -37,10 +43,16 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
   private var updateUrl = UpdaterPlugin.defaultUpdateURL
   private var appId: String?
   private var channel: String?
+  private var runtimeVersion: String?
   private var manifestKeys: [(kid: String, key: Data)] = []
   private var trialTimeoutWorkItem: DispatchWorkItem?
+  private var checkIntervalMs: Int = 600_000
+  private let isCheckInProgress = NSLock()
+  private var checkInProgress = false
+  private var foregroundObserver: NSObjectProtocol?
   private static let defaultUpdateURL = "https://www.otakit.app/api/v1"
   private static let apiPathSuffix = "/api/v1"
+  private static let lastCheckTimestampKey = "otakit_last_check_timestamp"
 
   public override func load() {
     let envUpdateUrl = ProcessInfo.processInfo.environment["OTAKIT_SERVER_URL"]
@@ -50,11 +62,14 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     )
     appId = getConfig().getString("appId")
     channel = trimToNil(getConfig().getString("channel"))
+    runtimeVersion = trimToNil(getConfig().getString("runtimeVersion"))
+    store.appRuntimeVersion = runtimeVersion
     allowInsecureUrls = getConfig().getBoolean("allowInsecureUrls", false)
     let updateModeRaw = getConfig().getString("updateMode", UpdateMode.nextLaunch.rawValue)
     updateMode = resolveUpdateMode(configured: updateModeRaw)
     downloader = Downloader(allowInsecureUrls: allowInsecureUrls)
     appReadyTimeoutMs = max(1000, getConfig().getInt("appReadyTimeout", 10_000))
+    checkIntervalMs = max(600_000, getConfig().getInt("checkInterval", 600_000))
 
     let rawKeysValue = getConfig().getArray("manifestKeys")
     if let rawKeys = rawKeysValue as? [[String: String]] {
@@ -77,6 +92,8 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
       manifestKeys = HostedManifestKeys.defaults
     }
 
+    pruneIncompatibleBundles()
+
     var current = store.getCurrentBundle()
     if current.status == .trial {
       rollbackCurrentBundle(reason: "app_restarted_before_notify")
@@ -99,33 +116,126 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     if isAutomaticUpdateMode() {
-      startAutoUpdate()
+      runAutomaticUpdate(trigger: .launch)
+    }
+
+    if isAutomaticUpdateMode() {
+      foregroundObserver = NotificationCenter.default.addObserver(
+        forName: UIApplication.willEnterForegroundNotification,
+        object: nil,
+        queue: .main
+      ) { [weak self] _ in
+        self?.handleAppWillEnterForeground()
+      }
     }
   }
 
-  private func startAutoUpdate() {
-    switch updateMode {
-    case .manual:
-      return
-    case .nextLaunch:
+  deinit {
+    if let observer = foregroundObserver {
+      NotificationCenter.default.removeObserver(observer)
+    }
+  }
+
+  private func handleAppWillEnterForeground() {
+    runAutomaticUpdate(trigger: .resume)
+  }
+
+  private func runAutomaticUpdate(trigger: Trigger) {
+    // Resume-only guards
+    if trigger == .resume {
+      if updateMode == .manual { return }
+
+      // next-resume and immediate: activate staged bundle on resume without server check
+      if (updateMode == .nextResume || updateMode == .immediate),
+         let stagedId = store.getStagedBundleId(),
+         store.getBundle(id: stagedId) != nil {
+        activateStagedBundleForReload()
+        reloadWebView()
+        return
+      }
+
+      if shouldThrottleCheck() { return }
+    }
+
+    // Acquire in-flight guard (submit-time)
+    guard claimCheckInProgress() else { return }
+
+    // Immediate mode on cold start: block until check+download+activate completes
+    if updateMode == .immediate && trigger == .launch {
       Task {
-        _ = try? await performCheckAndDownload(channel: nil, emitEvents: true)
+        defer { releaseCheckInProgress() }
+        do {
+          let result = try await performCheckAndDownload(channel: nil, emitEvents: true)
+          recordCheckTimestamp()
+          if result != nil {
+            activateStagedBundleForReload()
+            reloadWebView()
+          }
+        } catch {
+          print("[OtaKit] immediate startup update failed: \(error.localizedDescription)")
+        }
       }
-    case .immediate:
+      return
+    }
+
+    // Immediate mode on resume: background check+download, activate when done
+    if updateMode == .immediate && trigger == .resume {
       Task {
+        defer { releaseCheckInProgress() }
         do {
-          let downloaded = try await performCheckAndDownload(channel: nil, emitEvents: true)
-          if downloaded != nil {
+          let result = try await performCheckAndDownload(channel: nil, emitEvents: true)
+          recordCheckTimestamp()
+          if result != nil {
             activateStagedBundleForReload()
             reloadWebView()
           }
         } catch {
-          print("[UpdateKit] immediate startup update failed: \(error.localizedDescription)")
+          print("[OtaKit] immediate resume update failed: \(error.localizedDescription)")
         }
       }
+      return
+    }
+
+    // next-launch / next-resume: background check+download (fire-and-forget)
+    Task {
+      defer { releaseCheckInProgress() }
+      do {
+        _ = try await performCheckAndDownload(channel: nil, emitEvents: true)
+        recordCheckTimestamp()
+      } catch {
+        // Check failed — timestamp not recorded, will retry on next trigger
+      }
     }
   }
 
+  private func shouldThrottleCheck() -> Bool {
+    let lastCheck = UserDefaults.standard.double(forKey: UpdaterPlugin.lastCheckTimestampKey)
+    guard lastCheck > 0 else { return false }
+    let elapsed = Date().timeIntervalSince1970 * 1000 - lastCheck
+    return elapsed < Double(checkIntervalMs)
+  }
+
+  private func recordCheckTimestamp() {
+    UserDefaults.standard.set(
+      Date().timeIntervalSince1970 * 1000,
+      forKey: UpdaterPlugin.lastCheckTimestampKey
+    )
+  }
+
+  private func claimCheckInProgress() -> Bool {
+    isCheckInProgress.lock()
+    defer { isCheckInProgress.unlock() }
+    if checkInProgress { return false }
+    checkInProgress = true
+    return true
+  }
+
+  private func releaseCheckInProgress() {
+    isCheckInProgress.lock()
+    defer { isCheckInProgress.unlock() }
+    checkInProgress = false
+  }
+
   private func shouldActivateStagedOnLaunch() -> Bool {
     updateMode != .manual
   }
@@ -141,10 +251,12 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
       return .nextLaunch
     case UpdateMode.manual.rawValue:
       return .manual
+    case UpdateMode.nextResume.rawValue:
+      return .nextResume
     case UpdateMode.immediate.rawValue:
       return .immediate
     default:
-      print("[UpdateKit] Unknown updateMode '\(raw)', defaulting to 'next-launch'")
+      print("[OtaKit] Unknown updateMode '\(raw)', defaulting to 'next-launch'")
       return .nextLaunch
     }
   }
@@ -189,10 +301,36 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
   }
 
   @objc func check(_ call: CAPPluginCall) {
+    // Respect throttle — return staged bundle as a LatestVersion if available, else null
+    if shouldThrottleCheck() || !claimCheckInProgress() {
+      if let stagedId = store.getStagedBundleId(),
+         let staged = store.getBundle(id: stagedId) {
+        var payload: [String: Any] = [
+          "version": staged.version,
+          "url": "",
+          "sha256": staged.sha256 ?? "",
+          "size": 0,
+          "downloaded": true,
+        ]
+        if let runtimeVersion = staged.runtimeVersion {
+          payload["runtimeVersion"] = runtimeVersion
+        }
+        if let releaseId = staged.releaseId {
+          payload["releaseId"] = releaseId
+        }
+        call.resolve(payload)
+      } else {
+        call.resolve()
+      }
+      return
+    }
     let targetChannel = resolveTargetChannel(nil)
     Task {
+      defer { releaseCheckInProgress() }
       do {
         let latest = try await fetchLatest(channel: targetChannel)
+        // check() does NOT record timestamp — only download() and automatic paths do.
+        // This keeps check() -> download() working without the throttle blocking download().
         if let latest {
           let staged = findMatchingStagedBundle(latest: latest, targetChannel: targetChannel)
           call.resolve(manifestToDictionary(latest, downloaded: staged != nil))
@@ -225,9 +363,21 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
   }
 
   @objc func download(_ call: CAPPluginCall) {
+    // Respect throttle — return staged info if available, else null
+    if shouldThrottleCheck() || !claimCheckInProgress() {
+      if let stagedId = store.getStagedBundleId(),
+         let staged = store.getBundle(id: stagedId) {
+        call.resolve(staged.toDictionary())
+      } else {
+        call.resolve()
+      }
+      return
+    }
     Task {
+      defer { releaseCheckInProgress() }
       do {
         let bundle = try await performCheckAndDownload(channel: nil, emitEvents: true)
+        recordCheckTimestamp()
         if let bundle {
           call.resolve(bundle.toDictionary())
         } else {
@@ -361,7 +511,7 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
       channel: channel,
       currentVersion: current.version,
       currentReleaseId: current.releaseId,
-      nativeBuild: store.nativeBuild,
+      runtimeVersion: runtimeVersion,
       platform: "ios",
       allowInsecureUrls: allowInsecureUrls,
       manifestKeys: manifestKeys.map {
@@ -384,6 +534,14 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
       return nil
     }
 
+    guard isCompatibleRuntime(manifest.runtimeVersion) else {
+      throw NSError(
+        domain: "OtaKit",
+        code: 1,
+        userInfo: [NSLocalizedDescriptionKey: "Manifest runtimeVersion does not match the installed app runtime"]
+      )
+    }
+
     let staged = findMatchingStagedBundle(latest: manifest, targetChannel: targetChannel)
     if emitEvents {
       notifyListeners("updateAvailable", data: manifestToDictionary(manifest, downloaded: staged != nil))
@@ -407,6 +565,7 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         version: manifest.version,
         expectedSha256: manifest.sha256,
         expectedSize: manifest.size,
+        runtimeVersion: manifest.runtimeVersion,
         channel: targetChannel,
         releaseId: manifest.releaseId
       )
@@ -426,6 +585,7 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         version: manifest.version,
         expectedSha256: manifest.sha256,
         expectedSize: manifest.size,
+        runtimeVersion: manifest.runtimeVersion,
         channel: targetChannel,
         releaseId: manifest.releaseId
       )
@@ -446,6 +606,7 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     version: String,
     expectedSha256: String,
     expectedSize: Int? = nil,
+    runtimeVersion: String? = nil,
     channel: String? = nil,
     releaseId: String? = nil
   ) async throws -> BundleInfo {
@@ -510,6 +671,7 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
       let info = BundleInfo(
         id: bundleId,
         version: version,
+        runtimeVersion: runtimeVersion,
         status: .pending,
         downloadedAt: Date(),
         sha256: expectedSha256,
@@ -581,6 +743,10 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
       store.setStagedBundleId(nil)
       return store.getCurrentBundle()
     }
+    guard isCompatibleRuntime(staged) else {
+      try? store.deleteBundle(id: staged.id)
+      return store.getCurrentBundle()
+    }
 
     store.setCurrentBundleId(staged.id)
     store.setStagedBundleId(nil)
@@ -595,6 +761,10 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
       store.setStagedBundleId(nil)
       return
     }
+    guard isCompatibleRuntime(staged) else {
+      try? store.deleteBundle(id: staged.id)
+      return
+    }
 
     store.setCurrentBundleId(staged.id)
     store.setStagedBundleId(nil)
@@ -653,6 +823,7 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     let failed = BundleInfo(
       id: current.id,
       version: current.version,
+      runtimeVersion: current.runtimeVersion,
       status: .error,
       downloadedAt: current.downloadedAt,
       sha256: current.sha256,
@@ -759,12 +930,12 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
       "size": latest.size,
       "downloaded": downloaded,
     ]
+    if let runtimeVersion = latest.runtimeVersion {
+      payload["runtimeVersion"] = runtimeVersion
+    }
     if let releaseId = latest.releaseId {
       payload["releaseId"] = releaseId
     }
-    if let minNativeBuild = latest.minNativeBuild {
-      payload["minNativeBuild"] = minNativeBuild
-    }
     return payload
   }
 
@@ -784,6 +955,10 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
       return nil
     }
 
+    if trimToNil(staged.runtimeVersion) != trimToNil(latest.runtimeVersion) {
+      return nil
+    }
+
     if let latestReleaseId = latest.releaseId,
        let stagedReleaseId = staged.releaseId,
        latestReleaseId == stagedReleaseId {
@@ -798,6 +973,24 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     return nil
   }
 
+  private func pruneIncompatibleBundles() {
+    for bundle in store.listDownloadedBundles() where !isCompatibleRuntime(bundle) {
+      try? store.deleteBundle(id: bundle.id)
+    }
+
+    if let failed = store.getFailedBundle(), !isCompatibleRuntime(failed) {
+      store.setFailedBundle(nil)
+    }
+  }
+
+  private func isCompatibleRuntime(_ runtimeVersion: String?) -> Bool {
+    trimToNil(runtimeVersion) == self.runtimeVersion
+  }
+
+  private func isCompatibleRuntime(_ bundle: BundleInfo) -> Bool {
+    isCompatibleRuntime(bundle.runtimeVersion)
+  }
+
   private func buildBundleId(from version: String) -> String {
     let trimmed = version.trimmingCharacters(in: .whitespacesAndNewlines)
     let allowed = CharacterSet(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otakit/capacitor-updater",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Capacitor plugin for OTA updates",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",