@viettelpost/react-native-ota 0.1.0

package/docs/BACKEND_CONTRACT.md

@@ -0,0 +1,93 @@
+# Backend Contract
+
+## Read Endpoint
+
+The device checks for one eligible release:
+
+```http
+GET /api/ota/check-update?platform=ios|android&currentVersion=<version>
+```
+
+Update response:
+
+```json
+{
+  "version": "2026.06.26-001",
+  "bundleUrl": "https://cdn.example.com/ota/2026.06.26-001/ios/main.jsbundle",
+  "fileName": "main.jsbundle",
+  "platform": "ios",
+  "sha256": "lowercase64hex",
+  "signature": "base64EncodedRsaSha256Signature",
+  "assetsUrl": "https://cdn.example.com/ota/2026.06.26-001/ios/assets.zip",
+  "assetsSha256": "lowercase64hex"
+}
+```
+
+Return `204 No Content` when there is no eligible update.
+
+## Signing Payload
+
+The exact payload is newline joined with no trailing newline:
+
+```text
+version=<version>
+platform=<ios|android>
+fileName=<main.jsbundle|index.android.bundle>
+sha256=<lowercase hex>
+assetsSha256=<lowercase hex>
+```
+
+Omit `assetsSha256` for bundle-only updates.
+
+Algorithm:
+
+- RSA-SHA256
+- PKCS#1 v1.5 padding
+- Base64 signature output
+
+## Upload Endpoint
+
+The CLI expects:
+
+```http
+POST /api/ota/releases
+Authorization: Bearer <token>
+Content-Type: multipart/form-data
+```
+
+Multipart fields:
+
+- `version`
+- `platform`
+- `fileName`
+- `sha256`
+- `assetsSha256`, only when assets are uploaded
+- `signature`
+- `canonicalPayload`, optional audit field
+- `bundle`, JS bundle file
+- `assets`, optional `assets.zip`
+
+Expected responses:
+
+```http
+201 Created
+```
+
+```json
+{
+  "releaseId": "123",
+  "version": "2026.06.26-001",
+  "platform": "ios",
+  "bundleUrl": "https://cdn.example.com/...",
+  "assetsUrl": "https://cdn.example.com/...",
+  "status": "DRAFT"
+}
+```
+
+Return `409 Conflict` when `version + platform` already exists so the CLI can auto-increment the sequence.
+
+Optional publish endpoint:
+
+```http
+POST /api/ota/releases/{id}/publish
+```

package/docs/DEPLOY_CLI.md

@@ -0,0 +1,39 @@
+# Deploy CLI
+
+The package exposes one binary:
+
+```sh
+ota deploy [--platform ios|android|all] [--version <version>] \
+  --api https://cms.example.com \
+  --token <token> \
+  --private-key ./keys/ota_private_key.pem \
+  --public-key ./ios/ota_public_key.pem
+```
+
+Safe local validation:
+
+```sh
+ota deploy --platform android --dry-run
+ota deploy --platform ios --dry-run
+```
+
+Pipeline:
+
+1. Build the platform bundle with `react-native bundle`.
+2. Zip assets from the React Native `--assets-dest` output.
+3. Compute lowercase SHA-256 for the bundle and optional `assets.zip`.
+4. Sign the canonical payload with RSA-SHA256.
+5. Self-verify with the public key when supplied.
+6. Upload multipart data to `POST /api/ota/releases`, unless `--dry-run` is set.
+
+Bundle names are fixed:
+
+- Android: `index.android.bundle`
+- iOS: `main.jsbundle`
+
+Asset zip shape:
+
+- Android: entries are at zip root, such as `drawable-*` and `raw`.
+- iOS: every entry must live under `assets/`.
+
+The default deploy status is `DRAFT`. Passing `--activate` calls the publish endpoint after upload.

package/docs/INTEGRATION_ANDROID.md

@@ -0,0 +1,20 @@
+# Android Integration
+
+This package only provides the OTA runtime. A host app must wire native bundle resolution before downloaded bundles can run.
+
+Expected host-app work:
+
+1. Install `@viettelpost/react-native-ota`.
+2. Ensure the package autolinks or manually add `OTAUpdatePackage`.
+3. Add `ota_public_key.pem` under the host app `res/raw` when overriding the package default public key.
+4. In the app's `ReactNativeHost`, return the package resolver from `getJSBundleFile()`.
+
+Example shape:
+
+```kotlin
+override fun getJSBundleFile(): String? {
+    return OTAUpdateBundleResolver.resolveBundlePath(applicationContext)
+}
+```
+
+If the resolver returns `null`, React Native falls back to the embedded bundle. That fallback is intentional and is the safety floor.

package/docs/INTEGRATION_IOS.md

@@ -0,0 +1,21 @@
+# iOS Integration
+
+This package only provides the OTA runtime. A host app must wire native bundle resolution before downloaded bundles can run.
+
+Expected host-app work:
+
+1. Install `@viettelpost/react-native-ota`.
+2. Run `pod install`.
+3. Add `ota_public_key.pem` to the host app bundle when overriding the package default public key.
+4. In the app delegate bundle URL method, ask the package resolver for an OTA bundle URL before falling back to the embedded bundle.
+
+Example shape:
+
+```swift
+override func bundleURL() -> URL? {
+  return OTAUpdateBundleResolver.shared.resolveBundleURL()
+    ?? Bundle.main.url(forResource: "main", withExtension: "jsbundle")
+}
+```
+
+If the resolver returns `nil`, React Native falls back to the embedded bundle. That fallback is intentional and is the safety floor.

package/docs/RELEASE_WORKFLOW.md

@@ -0,0 +1,14 @@
+# Release Workflow
+
+Recommended flow:
+
+1. Run `ota deploy --platform all --dry-run`.
+2. Inspect bundle names, asset zip shape, hashes, and canonical payload.
+3. Run non-dry-run deploy with a CI-provided private key and token.
+4. Review the `DRAFT` release in the CMS.
+5. Publish through CMS or pass `--activate` when the release should become active immediately.
+6. Launch a test device, call `OTA.sync()`, restart, and call `OTA.markSuccess()` after the app is healthy.
+
+Rollback behavior is handled on-device for failed pending bundles and by backend release status for disabling bad releases globally.
+
+Never commit private keys or generated release bundles.

package/ios/OTAHashUtils.swift

@@ -0,0 +1,22 @@
+import Foundation
+import CryptoKit
+
+enum OTAHashUtils {
+  static func sha256(fileURL: URL) throws -> String {
+    let handle = try FileHandle(forReadingFrom: fileURL)
+    defer {
+      try? handle.close()
+    }
+
+    var hasher = SHA256()
+    while true {
+      let data = handle.readData(ofLength: 1024 * 1024)
+      if data.isEmpty {
+        break
+      }
+      hasher.update(data: data)
+    }
+
+    return hasher.finalize().map { String(format: "%02x", $0) }.joined()
+  }
+}

package/ios/OTAUpdateBundleResolver.swift

@@ -0,0 +1,359 @@
+import Foundation
+
+struct OTABundleInfo: Codable {
+  let runningBundleVersion: String
+  let activeBundleVersion: String
+  let pendingBundleVersion: String?
+  let status: String
+  let bundlePath: String?
+  let assetsDirectoryPath: String?
+  let assetsDirectoryExists: Bool
+  let isEmbedded: Bool
+}
+
+@objc(OTAUpdateBundleResolver)
+public final class OTAUpdateBundleResolver: NSObject {
+  @objc public static let shared = OTAUpdateBundleResolver()
+
+  private let storage: OTAUpdateStorage
+  private let fileManager: FileManager
+  private let encoder: JSONEncoder
+
+  private let embeddedVersion = "embedded"
+  private let statusActive = "active"
+  private let statusPending = "pending"
+  private let statusFailed = "failed"
+  private let statusRolledBack = "rolled_back"
+
+  private let missingPendingBundleReason = "missing_pending_bundle"
+  private let pendingBundleFileMissingReason = "pending_bundle_file_missing"
+  private let markSuccessNotCalledReason = "mark_success_not_called"
+  private let activeBundleFileMissingReason = "active_bundle_file_missing"
+
+  override init() {
+    storage = OTAUpdateStorage.shared
+    fileManager = .default
+    encoder = JSONEncoder()
+    super.init()
+  }
+
+  init(storage: OTAUpdateStorage, fileManager: FileManager, encoder: JSONEncoder) {
+    self.storage = storage
+    self.fileManager = fileManager
+    self.encoder = encoder
+    super.init()
+  }
+
+  @objc public func resolveBundleURL() -> URL? {
+    do {
+      return try resolveBundleURLOrThrow()
+    } catch {
+      return nil
+    }
+  }
+
+  @objc func getOTADirectoryPath() throws -> String {
+    let directoryURL = try otaDirectoryURL()
+    try fileManager.createDirectory(
+      at: directoryURL,
+      withIntermediateDirectories: true,
+      attributes: nil
+    )
+    return directoryURL.path
+  }
+
+  // Manual test hook: the bundle file must already be copied into private OTA storage.
+  @objc func prepareManualInstall(_ bundleVersion: String) throws -> NSNumber {
+    let normalizedVersion = bundleVersion.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !normalizedVersion.isEmpty else {
+      throw NSError(
+        domain: "OTAUpdateManualInstall",
+        code: OTAUpdateManualInstallErrorCode.invalidBundleVersion.rawValue,
+        userInfo: [NSLocalizedDescriptionKey: "bundleVersion must not be empty"]
+      )
+    }
+
+    let url = try bundleURL(for: normalizedVersion)
+    guard fileManager.fileExists(atPath: url.path) else {
+      throw NSError(
+        domain: "OTAUpdateManualInstall",
+        code: OTAUpdateManualInstallErrorCode.bundleFileNotFound.rawValue,
+        userInfo: [NSLocalizedDescriptionKey: "OTA bundle file was not found at \(url.path)"]
+      )
+    }
+
+    var metadata = try storage.readMetadata()
+    metadata.previousBundleVersion = metadata.activeBundleVersion
+    metadata.pendingBundleVersion = normalizedVersion
+    metadata.status = statusPending
+    metadata.launchCountForPending = 0
+    metadata.lastFailureReason = nil
+    try storage.writeMetadata(metadata)
+    return true as NSNumber
+  }
+
+  // Manual test hook: promote only the pending bundle that actually launched.
+  @objc func markSuccess() throws -> NSNumber {
+    var metadata = try storage.readMetadata()
+    guard metadata.status == statusPending,
+          let pendingVersion = metadata.pendingBundleVersion,
+          !pendingVersion.isEmpty,
+          metadata.runningBundleVersion == pendingVersion else {
+      return false as NSNumber
+    }
+
+    metadata.previousBundleVersion = metadata.activeBundleVersion
+    metadata.activeBundleVersion = pendingVersion
+    metadata.pendingBundleVersion = nil
+    metadata.status = statusActive
+    metadata.launchCountForPending = 0
+    metadata.lastSuccessfulLaunchAt = ISO8601DateFormatter().string(from: Date())
+    metadata.lastFailureReason = nil
+    try storage.writeMetadata(metadata)
+
+    // Metadata is saved before cleanup so a cleanup warning cannot undo a confirmed update.
+    do {
+      _ = try OTAUpdateCleanup.shared.cleanupAfterSuccessfulActivation(activeVersion: pendingVersion)
+      _ = try OTAUpdateCleanup.shared.cleanupAllTemp()
+    } catch {
+      NSLog("OTAKit cleanup after markSuccess failed: %@", error.localizedDescription)
+    }
+    return true as NSNumber
+  }
+
+  @objc func copyBundleFromDocuments(_ bundleVersion: String, fileName: String) throws -> NSNumber {
+    let normalizedVersion = bundleVersion.trimmingCharacters(in: .whitespacesAndNewlines)
+    let normalizedFileName = fileName.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !normalizedVersion.isEmpty, !normalizedFileName.isEmpty else {
+      throw NSError(
+        domain: "OTAUpdateManualInstall",
+        code: OTAUpdateManualInstallErrorCode.invalidBundleVersion.rawValue,
+        userInfo: [NSLocalizedDescriptionKey: "bundleVersion and fileName must not be empty"]
+      )
+    }
+
+    let documentsURL = try fileManager.url(
+      for: .documentDirectory,
+      in: .userDomainMask,
+      appropriateFor: nil,
+      create: false
+    )
+    let sourceURL = documentsURL.appendingPathComponent(normalizedFileName)
+    guard fileManager.fileExists(atPath: sourceURL.path) else {
+      throw NSError(
+        domain: "OTAUpdateManualInstall",
+        code: OTAUpdateManualInstallErrorCode.bundleFileNotFound.rawValue,
+        userInfo: [NSLocalizedDescriptionKey: "Source bundle file was not found at \(sourceURL.path)"]
+      )
+    }
+
+    let destinationURL = try bundleURL(for: normalizedVersion)
+    try fileManager.createDirectory(
+      at: destinationURL.deletingLastPathComponent(),
+      withIntermediateDirectories: true,
+      attributes: nil
+    )
+    if fileManager.fileExists(atPath: destinationURL.path) {
+      try fileManager.removeItem(at: destinationURL)
+    }
+    try fileManager.copyItem(at: sourceURL, to: destinationURL)
+    return true as NSNumber
+  }
+
+  @objc func getCurrentBundleInfoJSONString() throws -> String {
+    let metadata = try storage.readMetadata()
+    let info = currentBundleInfo(for: metadata)
+    let data = try encoder.encode(info)
+    guard let jsonString = String(data: data, encoding: .utf8) else {
+      throw OTAUpdateBundleResolverError.jsonEncodingFailed
+    }
+    return jsonString
+  }
+
+  private func resolveBundleURLOrThrow() throws -> URL? {
+    let metadata = try storage.readMetadata()
+
+    if metadata.status == statusPending {
+      return try resolvePendingBundle(metadata)
+    }
+
+    return try resolveActiveBundle(metadata)
+  }
+
+  private func resolvePendingBundle(_ metadata: OTAUpdateMetadata) throws -> URL? {
+    guard let pendingVersion = metadata.pendingBundleVersion, !pendingVersion.isEmpty else {
+      var nextMetadata = metadata
+      nextMetadata.status = statusFailed
+      nextMetadata.pendingBundleVersion = nil
+      nextMetadata.runningBundleVersion = embeddedVersion
+      nextMetadata.launchCountForPending = 0
+      nextMetadata.lastFailureReason = missingPendingBundleReason
+      try storage.writeMetadata(nextMetadata)
+      return nil
+    }
+
+    let pendingURL = try bundleURL(for: pendingVersion)
+    guard fileManager.fileExists(atPath: pendingURL.path) else {
+      let runningVersion = try validActiveBundleVersion(metadata) ?? embeddedVersion
+      var nextMetadata = metadata
+      nextMetadata.status = statusFailed
+      nextMetadata.pendingBundleVersion = nil
+      nextMetadata.failedBundleVersion = pendingVersion
+      nextMetadata.runningBundleVersion = runningVersion
+      nextMetadata.launchCountForPending = 0
+      nextMetadata.lastFailureReason = pendingBundleFileMissingReason
+      try storage.writeMetadata(nextMetadata)
+      // The pending version cannot run, so its package and temp files are safe to remove.
+      do {
+        _ = try OTAUpdateCleanup.shared.cleanupFailedPendingBundle(failedVersion: pendingVersion)
+      } catch {
+        NSLog("OTAKit cleanup missing pending bundle failed: %@", error.localizedDescription)
+      }
+      return try bundleURLIfNotEmbedded(for: runningVersion)
+    }
+
+    if metadata.launchCountForPending > 0 {
+      let runningVersion = try validActiveBundleVersion(metadata) ?? embeddedVersion
+      var nextMetadata = metadata
+      nextMetadata.status = statusRolledBack
+      nextMetadata.pendingBundleVersion = nil
+      nextMetadata.failedBundleVersion = pendingVersion
+      nextMetadata.runningBundleVersion = runningVersion
+      nextMetadata.launchCountForPending = 0
+      nextMetadata.lastFailureReason = markSuccessNotCalledReason
+      try storage.writeMetadata(nextMetadata)
+      // Save rollback metadata first; cleanup failure must not prevent fallback startup.
+      do {
+        _ = try OTAUpdateCleanup.shared.cleanupFailedPendingBundle(failedVersion: pendingVersion)
+      } catch {
+        NSLog("OTAKit cleanup failed pending bundle failed: %@", error.localizedDescription)
+      }
+      return try bundleURLIfNotEmbedded(for: runningVersion)
+    }
+
+    var nextMetadata = metadata
+    nextMetadata.runningBundleVersion = pendingVersion
+    nextMetadata.launchCountForPending = metadata.launchCountForPending + 1
+    try storage.writeMetadata(nextMetadata)
+    return pendingURL
+  }
+
+  private func resolveActiveBundle(_ metadata: OTAUpdateMetadata) throws -> URL? {
+    let activeVersion = metadata.activeBundleVersion
+    if !isEmbeddedVersion(activeVersion) {
+      let activeURL = try bundleURL(for: activeVersion)
+      if fileManager.fileExists(atPath: activeURL.path) {
+        var nextMetadata = metadata
+        nextMetadata.runningBundleVersion = activeVersion
+        try storage.writeMetadata(nextMetadata)
+        return activeURL
+      }
+
+      var nextMetadata = metadata
+      nextMetadata.status = statusFailed
+      nextMetadata.failedBundleVersion = activeVersion
+      nextMetadata.runningBundleVersion = embeddedVersion
+      nextMetadata.lastFailureReason = activeBundleFileMissingReason
+      try storage.writeMetadata(nextMetadata)
+      return nil
+    }
+
+    var nextMetadata = metadata
+    nextMetadata.runningBundleVersion = embeddedVersion
+    try storage.writeMetadata(nextMetadata)
+    return nil
+  }
+
+  private func currentBundleInfo(for metadata: OTAUpdateMetadata) -> OTABundleInfo {
+    let isEmbedded = isEmbeddedVersion(metadata.runningBundleVersion)
+    let bundlePath: String?
+    let assetsDirectoryPath: String?
+    let assetsDirectoryExists: Bool
+    if isEmbedded {
+      bundlePath = Bundle.main.url(forResource: "main", withExtension: "jsbundle")?.path
+      assetsDirectoryPath = nil
+      assetsDirectoryExists = false
+    } else {
+      let bundleURL = try? bundleURL(for: metadata.runningBundleVersion)
+      bundlePath = bundleURL.flatMap { fileManager.fileExists(atPath: $0.path) ? $0.path : nil }
+      let assetsURL = try? assetsDirectoryURL(for: metadata.runningBundleVersion)
+      assetsDirectoryPath = assetsURL?.path
+      assetsDirectoryExists = assetsURL.map { directoryExistsAndHasFiles($0) } ?? false
+    }
+
+    return OTABundleInfo(
+      runningBundleVersion: metadata.runningBundleVersion,
+      activeBundleVersion: metadata.activeBundleVersion,
+      pendingBundleVersion: metadata.pendingBundleVersion,
+      status: metadata.status,
+      bundlePath: bundlePath,
+      assetsDirectoryPath: assetsDirectoryPath,
+      assetsDirectoryExists: assetsDirectoryExists,
+      isEmbedded: isEmbedded
+    )
+  }
+
+  private func validActiveBundleVersion(_ metadata: OTAUpdateMetadata) throws -> String? {
+    let activeVersion = metadata.activeBundleVersion
+    if isEmbeddedVersion(activeVersion) {
+      return nil
+    }
+
+    let activeURL = try bundleURL(for: activeVersion)
+    return fileManager.fileExists(atPath: activeURL.path) ? activeVersion : nil
+  }
+
+  private func bundleURLIfNotEmbedded(for bundleVersion: String) throws -> URL? {
+    if isEmbeddedVersion(bundleVersion) {
+      return nil
+    }
+    return try bundleURL(for: bundleVersion)
+  }
+
+  private func bundleURL(for bundleVersion: String) throws -> URL {
+    try otaDirectoryURL()
+      .appendingPathComponent("bundles", isDirectory: true)
+      .appendingPathComponent(bundleVersion, isDirectory: true)
+      .appendingPathComponent("main.jsbundle")
+  }
+
+  private func assetsDirectoryURL(for bundleVersion: String) throws -> URL {
+    try otaDirectoryURL()
+      .appendingPathComponent("bundles", isDirectory: true)
+      .appendingPathComponent(bundleVersion, isDirectory: true)
+      .appendingPathComponent("assets", isDirectory: true)
+  }
+
+  private func otaDirectoryURL() throws -> URL {
+    let supportURL = try fileManager.url(
+      for: .applicationSupportDirectory,
+      in: .userDomainMask,
+      appropriateFor: nil,
+      create: true
+    )
+    return supportURL.appendingPathComponent("OTA", isDirectory: true)
+  }
+
+  private func isEmbeddedVersion(_ bundleVersion: String?) -> Bool {
+    guard let bundleVersion = bundleVersion, !bundleVersion.isEmpty else {
+      return true
+    }
+    return bundleVersion == embeddedVersion
+  }
+
+  private func directoryExistsAndHasFiles(_ url: URL) -> Bool {
+    guard let enumerator = fileManager.enumerator(at: url, includingPropertiesForKeys: nil) else {
+      return false
+    }
+    return enumerator.nextObject() != nil
+  }
+}
+
+enum OTAUpdateBundleResolverError: Error {
+  case jsonEncodingFailed
+}
+
+private enum OTAUpdateManualInstallErrorCode: Int {
+  case invalidBundleVersion = 1
+  case bundleFileNotFound = 2
+}