react-native-bspatch 1.0.0

package/lib/module/ota/otaCore.js

@@ -0,0 +1,725 @@
+"use strict";
+
+/**
+ * Core OTA Logic (Stateless)
+ *
+ * Responsibilities:
+ *  - Download patches with retry
+ *  - Verify integrity (SHA-256 hash)
+ *  - Verify security (HMAC signature)
+ *  - Handle gzip decompression
+ *  - Apply binary patch (bsdiff)
+ *  - Atomic bundle swap
+ *  - Full bundle fallback on failure
+ *  - Structured telemetry logging
+ */
+
+import { Platform } from 'react-native';
+import ReactNativeBlobUtil from 'react-native-blob-util';
+import CryptoJS from 'crypto-js';
+import NativeBsPatch from '../NativeBsPatch';
+import { createOtaLogger, OtaEvent } from './otaLogger';
+import { ensureOtaDir, getBundlePath, loadMetadata, registerNewVersion, saveMetadata } from './otaMetadata';
+import { CustomStorageProvider } from './storage/CustomStorage';
+import { GitHubReleaseStorageProvider } from './storage/GitHubReleaseStorage';
+import { OtaStatus, OtaStorageType } from './types';
+const OTA_DIR = `${ReactNativeBlobUtil.fs.dirs.DocumentDir}/ota`;
+
+// ─── Storage Provider Factory ──────────────────────────────────────────
+
+const DEFAULT_STORAGE = new CustomStorageProvider();
+const GITHUB_STORAGE = new GitHubReleaseStorageProvider();
+
+/**
+ * Get the storage provider for the given configuration.
+ * Priority: explicit storage instance > storageType > default (CustomStorage)
+ */
+const getStorage = config => {
+  if (config.storage) return config.storage;
+  if (config.storageType === OtaStorageType.GITHUB) return GITHUB_STORAGE;
+  return DEFAULT_STORAGE;
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Compares two semantic version strings.
+ *
+ * @param a - First version string (e.g., "1.2.3")
+ * @param b - Second version string (e.g., "1.2.4")
+ * @returns `true` if `a >= b`, `false` otherwise
+ *
+ * @example
+ * semverGte("1.2.3", "1.2.3") // true
+ * semverGte("1.2.4", "1.2.3") // true
+ * semverGte("1.2.2", "1.2.3") // false
+ */
+export const semverGte = (a, b) => {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const va = pa[i] || 0;
+    const vb = pb[i] || 0;
+    if (va > vb) return true;
+    if (va < vb) return false;
+  }
+  return true; // equal
+};
+
+/**
+ * Verifies the SHA-256 hash of a file.
+ *
+ * @param path - Absolute path to the file to verify
+ * @param expectedHash - Expected SHA-256 hash (hex string). If undefined, verification is skipped.
+ * @returns `true` if hash matches or `expectedHash` is undefined, `false` otherwise
+ */
+export const verifyHash = async (path, expectedHash) => {
+  if (!expectedHash) return true;
+  try {
+    const hash = await ReactNativeBlobUtil.fs.hash(path, 'sha256');
+    return hash.toLowerCase() === expectedHash.toLowerCase();
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Verify HMAC-SHA256 signature of a file.
+ *
+ * Uses CryptoJS to verify that the signature matches the file content
+ * using the provided HMAC key.
+ *
+ * @param filePath - Path to the file to verify
+ * @param signature - Base64-encoded HMAC signature to verify against
+ * @param publicKey - Base64-encoded HMAC key
+ * @returns true if signature is valid, false otherwise
+ *
+ * @example
+ * // Server-side (Node.js) - generate signature:
+ * const crypto = require('crypto');
+ * const key = crypto.randomBytes(32).toString('base64');
+ * const fileBuffer = fs.readFileSync('bundle.patch');
+ * const signature = crypto.createHmac('sha256', Buffer.from(key, 'base64'))
+ *     .update(fileBuffer)
+ *     .digest('base64');
+ */
+export const verifySignature = async (filePath, signature, publicKey) => {
+  if (!signature || !publicKey) return true; // Skip if not configured
+  try {
+    // Read file content
+    const fileData = await ReactNativeBlobUtil.fs.readFile(filePath, 'base64');
+
+    // Convert base64 to WordArray for CryptoJS
+    const fileWords = CryptoJS.enc.Base64.parse(fileData);
+    const keyWords = CryptoJS.enc.Base64.parse(publicKey);
+    const signatureWords = CryptoJS.enc.Base64.parse(signature);
+
+    // Compute HMAC
+    const hmac = CryptoJS.HmacSHA256(fileWords, keyWords);
+
+    // Compare computed HMAC with provided signature
+    const isValid = hmac.toString(CryptoJS.enc.Base64) === signatureWords.toString(CryptoJS.enc.Base64);
+    if (!isValid && __DEV__) {
+      console.warn('[otaCore] Signature mismatch');
+    }
+    return isValid;
+  } catch (error) {
+    if (__DEV__) {
+      console.error('[otaCore] Signature verification failed:', error);
+    }
+    return false;
+  }
+};
+
+/**
+ * Decompress a .gz file in-place using native helpers.
+ * Falls back to skipping decompression if no native helper is available,
+ * but enforces that the patch file must NOT be gzip-compressed in that case.
+ */
+const decompressGzip = async filePath => {
+  if (!filePath.endsWith('.gz')) {
+    return filePath;
+  }
+  const decompressedPath = filePath.replace(/\.gz$/, '');
+  try {
+    const success = await NativeBsPatch.decompressGzip(filePath, decompressedPath);
+    if (success) {
+      return decompressedPath;
+    }
+  } catch {
+    // Native decompress not available — fall through
+  }
+
+  // No native gzip support: abort if file is actually compressed.
+  // Do NOT silently rename a .gz file to .patch — bspatch will read gzip
+  // magic bytes and fail with a confusing error.
+  console.error('[otaCore] .gz decompression is not supported on this platform. ' + 'Ensure the OTA server sends uncompressed patches (compressed: false).');
+  throw new Error('Gzip decompression is not supported on this platform.');
+};
+
+/**
+ * Download a file with retry logic using exponential backoff.
+ * Cancels any in-flight request before retrying to avoid resource leaks.
+ */
+const downloadWithRetry = async (url, destPath, config, onProgress, headers = {}) => {
+  const retryLimit = config.network?.retry ?? 3;
+  const timeout = config.network?.timeoutMs ?? 30000;
+  for (let i = 0; i < retryLimit; i++) {
+    let taskRef = null;
+    try {
+      const task = ReactNativeBlobUtil.config({
+        fileCache: true,
+        path: destPath,
+        followRedirect: true,
+        timeout
+      }).fetch('GET', url, {
+        'Cache-Control': 'no-cache',
+        ...headers
+      }).progress((received, total) => {
+        const percent = Math.floor(Number(received) / Number(total) * 100);
+        onProgress(percent);
+      });
+      taskRef = {
+        cancel: () => task.cancel()
+      };
+      await task;
+      return;
+    } catch (e) {
+      // Cancel any lingering request before retrying
+      taskRef?.cancel();
+      if (i === retryLimit - 1) throw e;
+      const delay = Math.pow(2, i) * 1000; // Exponential backoff: 1s, 2s, 4s...
+      if (__DEV__) {
+        console.warn(`[otaCore] Download attempt ${i + 1} failed. Retrying in ${delay}ms...`);
+      }
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+};
+
+// ─── Manifest ─────────────────────────────────────────────────────────
+
+/**
+ * Fetches the list of available OTA patches from the remote manifest.
+ *
+ * Falls back to bundled patches if the remote fetch fails, ensuring
+ * the app can still apply updates that were bundled at build time.
+ *
+ * @param config - OTA configuration containing storage provider and fallback patches
+ * @returns Array of available patches, or bundled patches if remote fetch fails
+ */
+export const fetchOtaManifest = async config => {
+  try {
+    const storage = getStorage(config);
+    return await storage.fetchManifest(config);
+  } catch (error) {
+    console.warn('[otaCore] Manifest fetch error:', error.message);
+    return config.bundledPatches || [];
+  }
+};
+
+// ─── Hashed Asset Store ───────────────────────────────────────────────
+
+const ASSET_STORE_DIR = `${ReactNativeBlobUtil.fs.dirs.DocumentDir}/ota/assets`;
+
+/**
+ * Downloads and syncs assets from the content-addressed asset store.
+ * Only downloads assets that are not already cached locally.
+ *
+ * @param assetManifestUrl URL to the asset-manifest.json for this version
+ * @param config OTA configuration
+ * @param log Logger instance
+ * @param onStatus Status update callback
+ */
+const downloadAndSyncAssets = async (assetManifestUrl, version, config, log, onStatus, onProgress) => {
+  onStatus(OtaStatus.SYNCING_ASSETS, 'Syncing assets...');
+  const versionDir = `${OTA_DIR}/v${version}`;
+  const manifestPath = `${versionDir}/asset-manifest-v${version}.json`;
+
+  // Ensure asset store dir exists
+  if (!(await ReactNativeBlobUtil.fs.exists(ASSET_STORE_DIR))) {
+    await ReactNativeBlobUtil.fs.mkdir(ASSET_STORE_DIR);
+  }
+
+  // Fetch the asset manifest
+  let assets = [];
+  try {
+    if (__DEV__) {
+      console.log(`[otaCore] Fetching asset manifest from: ${assetManifestUrl}`);
+    }
+    const resp = await ReactNativeBlobUtil.config({
+      followRedirect: true,
+      timeout: 10000
+    }).fetch('GET', assetManifestUrl, {
+      'Cache-Control': 'no-cache'
+    });
+    if (resp.respInfo.status !== 200) {
+      throw new Error(`Manifest fetch failed with status ${resp.respInfo.status}`);
+    }
+
+    // Save manifest to disk for future reloads (AssetResolver needs it)
+    if (!(await ReactNativeBlobUtil.fs.exists(versionDir))) {
+      await ReactNativeBlobUtil.fs.mkdir(versionDir);
+    }
+    const manifestData = typeof resp.data === 'string' ? resp.data : JSON.stringify(resp.data);
+    await ReactNativeBlobUtil.fs.writeFile(manifestPath, manifestData, 'utf8');
+    if (__DEV__) {
+      console.log(`[otaCore] Saved asset manifest to: ${manifestPath}`);
+    }
+    const manifest = JSON.parse(manifestData);
+    // Filter out base assets, we don't need to download them
+    assets = (manifest.assets || []).filter(a => !a.isBase);
+  } catch (e) {
+    if (__DEV__) {
+      console.warn('[otaCore] Failed to fetch asset manifest:', e);
+    }
+    return;
+  }
+  if (assets.length === 0) {
+    if (__DEV__) {
+      console.log('[otaCore] No new assets to sync for this version.');
+    }
+    return;
+  }
+
+  // Only notify UI now that we actually have assets to download
+  onStatus(OtaStatus.SYNCING_ASSETS, `Syncing ${assets.length} asset(s)...`);
+  let processed = 0;
+  let downloaded = 0;
+  let cached = 0;
+  const updateProgress = () => {
+    processed++;
+    const percent = Math.round(processed / assets.length * 100);
+    onProgress(percent);
+  };
+
+  // Concurrency-limited download queue
+  const maxConcurrency = 6; // Optimal for most mobile networks
+  let index = 0;
+  const downloadNext = async () => {
+    if (index >= assets.length) return;
+    const asset = assets[index++];
+    const filename = `${asset.hash}.${asset.ext}`;
+    const localPath = `${ASSET_STORE_DIR}/${filename}`;
+
+    // Check if already cached
+    if (await ReactNativeBlobUtil.fs.exists(localPath)) {
+      cached++;
+      updateProgress();
+      await downloadNext(); // Start next download
+      return;
+    }
+
+    // Download missing asset
+    onStatus(OtaStatus.SYNCING_ASSETS, `Syncing assets (${processed + 1}/${assets.length})...`);
+    try {
+      const storage = getStorage(config);
+      const assetUrl = await storage.getAssetUrl(asset.hash, asset.ext, config);
+      if (!assetUrl) {
+        if (__DEV__) {
+          console.warn(`[otaCore] Could not get URL for asset ${filename}`);
+        }
+      } else {
+        await ReactNativeBlobUtil.config({
+          fileCache: true,
+          path: localPath,
+          followRedirect: true,
+          timeout: config.network?.timeoutMs ?? 30000
+        }).fetch('GET', assetUrl);
+        downloaded++;
+        log.emit(OtaEvent.DOWNLOAD_SUCCESS, {
+          message: `Asset downloaded: ${filename}`
+        });
+      }
+    } catch (e) {
+      if (__DEV__) {
+        console.warn(`[otaCore] Failed to download asset ${filename}:`, e);
+      }
+      // Non-fatal: continue with other assets
+    } finally {
+      updateProgress();
+      await downloadNext(); // Start next download
+    }
+  };
+
+  // Start initial batch of downloads
+  const initialWorkers = Math.min(maxConcurrency, assets.length);
+  const workers = Array(initialWorkers).fill(null).map(() => downloadNext());
+  await Promise.all(workers);
+  onStatus(OtaStatus.SYNCING_ASSETS, `Assets synced (${downloaded} new, ${cached} cached)`);
+  console.log(`[otaCore] Assets: ${downloaded} downloaded, ${cached} from cache`);
+};
+
+/**
+ * Gets the local filesystem path for a content-addressed asset.
+ *
+ * Assets are stored by their hash, so the same asset file is shared
+ * across all OTA versions that reference it.
+ *
+ * @param hash - SHA-256 hash of the asset content
+ * @param ext - File extension (e.g., "png", "jpg")
+ * @returns Absolute path to the asset in the local store
+ *
+ * @example
+ * getLocalAssetPath("abc123...", "png")
+ * // Returns: "/var/mobile/Containers/Data/Application/.../ota/assets/abc123....png"
+ */
+export const getLocalAssetPath = (hash, ext) => `${ASSET_STORE_DIR}/${hash}.${ext}`;
+
+/**
+ * Gets the local filesystem path for a downloaded patch file.
+ *
+ * @param patch - Patch metadata object
+ * @param docDir - Document directory path (use `ReactNativeBlobUtil.fs.dirs.DocumentDir`)
+ * @returns Absolute path to the patch file
+ */
+export const getLocalPatchPath = (patch, docDir) => `${docDir}/ota/patch-${patch.id}.patch`;
+
+// ─── Main Update Pipeline ─────────────────────────────────────────────
+
+/**
+ * Applies a single patch and reloads the bundle.
+ *
+ * Pipeline:
+ *  1. Version compatibility check
+ *  2. Download patch (with retry)
+ *  3. Decompress (if .gz)
+ *  4. Security signature check
+ *  5. Resolve source bundle
+ *  6. Verify source hash
+ *  7. Apply binary patch
+ *  8. Verify result hash
+ *  9. Atomic commit (mv)
+ * 10. Update metadata
+ * 11. Reload bundle
+ *
+ * On failure → fallback to full bundle download if URL available.
+ */
+export const applyOtaPatchInternal = async (patch, config, onStatus, onProgress) => {
+  const log = createOtaLogger(config.onEvent);
+  await ensureOtaDir();
+  const totalStart = Date.now();
+  const finalBundlePath = getBundlePath(patch.toVersion, config.baseAppVersion) || '';
+  const tempBundle = `${finalBundlePath}.tmp`;
+  const localPatchPath = getLocalPatchPath(patch, ReactNativeBlobUtil.fs.dirs.DocumentDir);
+  try {
+    // ── Step 1: Version Compatibility ──
+    if (patch.minAppVersion) {
+      if (!semverGte(config.appVersion, patch.minAppVersion)) {
+        log.emit(OtaEvent.VERSION_INCOMPATIBLE, {
+          message: `App ${config.appVersion} < required ${patch.minAppVersion}`,
+          version: patch.toVersion
+        });
+        throw new Error(`Native app ${config.appVersion} is too old. Update to ${patch.minAppVersion}+ first.`);
+      }
+    }
+
+    // ── Step 2: Download ──
+    let downloadMs = 0;
+    let patchSizeBytes = 0;
+    let fromCache = false;
+    if (await ReactNativeBlobUtil.fs.exists(localPatchPath)) {
+      const stat = await ReactNativeBlobUtil.fs.stat(localPatchPath);
+      patchSizeBytes = Number(stat.size);
+      fromCache = true;
+      onProgress(100);
+    } else {
+      log.emit(OtaEvent.DOWNLOAD_START, {
+        version: patch.toVersion
+      });
+      onStatus(OtaStatus.DOWNLOADING, `Downloading V${patch.toVersion}...`);
+      const dlStart = Date.now();
+      try {
+        const storage = getStorage(config);
+        const url = await storage.getUpdateFileUrl(patch.filename, config);
+        await downloadWithRetry(url, localPatchPath, config, onProgress, {});
+        downloadMs = Date.now() - dlStart;
+        const stat = await ReactNativeBlobUtil.fs.stat(localPatchPath);
+        patchSizeBytes = Number(stat.size);
+        log.emit(OtaEvent.DOWNLOAD_SUCCESS, {
+          version: patch.toVersion,
+          durationMs: downloadMs,
+          sizeKB: patchSizeBytes / 1024
+        });
+      } catch (dlError) {
+        log.emit(OtaEvent.DOWNLOAD_FAIL, {
+          error: dlError.message,
+          version: patch.toVersion
+        });
+        throw dlError;
+      }
+    }
+
+    // ── Step 3: Decompress if needed ──
+    let actualPatchPath = localPatchPath;
+    if (patch.compressed) {
+      log.emit(OtaEvent.DECOMPRESS_START);
+      onStatus(OtaStatus.APPLYING, 'Decompressing...');
+      actualPatchPath = await decompressGzip(localPatchPath);
+      log.emit(OtaEvent.DECOMPRESS_SUCCESS);
+    }
+
+    // ── Step 4: Signature Verification ──
+    if (patch.signature && config.publicKey) {
+      onStatus(OtaStatus.APPLYING, 'Verifying signature...');
+      const sigValid = await verifySignature(actualPatchPath, patch.signature, config.publicKey);
+      if (!sigValid) {
+        log.emit(OtaEvent.SIGNATURE_INVALID, {
+          version: patch.toVersion
+        });
+        throw new Error('Patch signature verification failed. Possible MITM.');
+      }
+    }
+
+    // ── Step 4.2: Download & Sync Assets ──
+    if (patch.assetManifestUrl) {
+      const storage = getStorage(config);
+      const manifestUrl = await storage.getUpdateFileUrl(patch.assetManifestUrl, config);
+      await downloadAndSyncAssets(manifestUrl, patch.toVersion, config, log, onStatus, onProgress);
+    }
+
+    // ── Step 5: Resolve Source Bundle ──
+    onStatus(OtaStatus.APPLYING, 'Preparing source...');
+    const metadata = await loadMetadata(config.baseAppVersion);
+    const oldBundlePath = getBundlePath(metadata.currentVersion, config.baseAppVersion);
+
+    // ── Resolve the actual old bundle path ──────────────────────────────
+    // getBundlePath returns null when currentVersion == baseAppVersion, meaning
+    // "use the APK's baked-in bundle". However, if BASE_APP_VERSION was bumped
+    // to match a version that was applied via OTA (not actually baked into the
+    // installed APK), direct APK extraction would produce a DIFFERENT file than
+    // what the build script recorded as the baseHash for the next patch.
+    //
+    // Strategy (in order of precedence):
+    //   1. Use the explicit OTA bundle path from getBundlePath (version > base) ✓
+    //   2. If null (version == base), check for a previously OTA-stored bundle
+    //      at ota/v{currentVersion}/ — its hash matches the server registry.
+    //   3. Fall back to APK extraction only if no OTA bundle exists on disk.
+    const bundleFilename = Platform.OS === 'android' ? 'index.android.bundle' : 'main.jsbundle';
+    let actualOldPath = '';
+    if (!oldBundlePath) {
+      // currentVersion == baseAppVersion: prefer OTA-stored bundle for this
+      // version over APK extraction (handles BASE_APP_VERSION bump scenarios).
+      const otaStoredPath = `${OTA_DIR}/v${metadata.currentVersion}/${bundleFilename}`;
+      if (await ReactNativeBlobUtil.fs.exists(otaStoredPath)) {
+        if (__DEV__) {
+          console.log(`[otaCore] Source: OTA-stored bundle for V${metadata.currentVersion} (BASE_APP_VERSION match)`);
+        }
+        actualOldPath = otaStoredPath;
+      } else {
+        // True base: extract byte-for-byte from APK assets.
+        // RNFS.copyFileAssets is known to produce inconsistent bytes in some
+        // APK configurations (e.g., release signing + resource shrinking).
+        actualOldPath = `${OTA_DIR}/base.hbc`;
+        if (!(await ReactNativeBlobUtil.fs.exists(actualOldPath))) {
+          if (__DEV__) {
+            console.log(`[otaCore] Source: extracting bundle from APK assets → ${actualOldPath}`);
+          }
+          await NativeBsPatch.extractBundleFromAssets(bundleFilename, actualOldPath);
+        } else if (__DEV__) {
+          console.log(`[otaCore] Source: cached APK-extracted bundle → ${actualOldPath}`);
+        }
+      }
+    } else {
+      actualOldPath = oldBundlePath;
+    }
+
+    // ── Debug: log file sizes for diagnostic ──
+    try {
+      const oldStat = await ReactNativeBlobUtil.fs.stat(actualOldPath);
+      const patchStat = await ReactNativeBlobUtil.fs.stat(actualPatchPath);
+      if (__DEV__) {
+        console.log(`[otaCore] DEBUG old bundle size=${oldStat.size} path=${actualOldPath}`);
+        console.log(`[otaCore] DEBUG patch size=${patchStat.size} path=${actualPatchPath}`);
+        console.log(`[otaCore] DEBUG baseHash expected=${patch.baseHash}`);
+      }
+    } catch {
+      // Non-fatal: stat is for diagnostic only
+    }
+
+    // ── Step 6: Verify Source Integrity ──
+    if (patch.baseHash) {
+      log.emit(OtaEvent.HASH_VERIFY_START, {
+        message: 'Verifying source bundle'
+      });
+      onStatus(OtaStatus.APPLYING, 'Verifying source integrity...');
+      const isValid = await verifyHash(actualOldPath, patch.baseHash);
+      if (!isValid) {
+        // Re-hash only for the diagnostic log (verifyHash doesn't return the actual hash)
+        let actualSourceHash = '';
+        let srcSize = 'unknown';
+        try {
+          actualSourceHash = await ReactNativeBlobUtil.fs.hash(actualOldPath, 'sha256');
+          const srcStat = await ReactNativeBlobUtil.fs.stat(actualOldPath);
+          srcSize = `${srcStat.size} bytes`;
+        } catch {
+          // stat failure is non-fatal for the error message
+        }
+        if (__DEV__) {
+          console.error('[otaCore] SOURCE HASH MISMATCH\n' + `  path:     ${actualOldPath}\n` + `  size:     ${srcSize}\n` + `  expected: ${patch.baseHash}\n` + `  actual:   ${actualSourceHash}\n` + `  patch.id: ${patch.id} (v${patch.fromVersion}→v${patch.toVersion})`);
+        }
+        log.emit(OtaEvent.HASH_MISMATCH, {
+          version: metadata.currentVersion,
+          message: 'Source bundle hash mismatch',
+          metadata: {
+            expected: patch.baseHash,
+            actual: actualSourceHash,
+            path: actualOldPath
+          }
+        });
+        throw new Error('Source bundle hash mismatch. Fallback required.');
+      }
+      log.emit(OtaEvent.HASH_VERIFY_SUCCESS, {
+        message: 'Source bundle verified'
+      });
+    }
+
+    // ── Step 7: Apply Patch ──
+    const versionDir = `${OTA_DIR}/v${patch.toVersion}`;
+    if (!(await ReactNativeBlobUtil.fs.exists(versionDir))) {
+      await ReactNativeBlobUtil.fs.mkdir(versionDir);
+    }
+    log.emit(OtaEvent.PATCH_START, {
+      version: patch.toVersion
+    });
+    onStatus(OtaStatus.APPLYING, 'Applying binary patch...');
+    const applyStart = Date.now();
+    const success = await NativeBsPatch.applyPatch(actualOldPath, tempBundle, actualPatchPath);
+    const applyMs = Date.now() - applyStart;
+    if (!success) {
+      log.emit(OtaEvent.PATCH_FAIL, {
+        message: 'BsPatch returned false',
+        version: patch.toVersion
+      });
+      throw new Error('BsPatch application failed');
+    }
+
+    // ── Step 8: Verify Result Integrity ──
+    if (patch.bundleHash) {
+      log.emit(OtaEvent.HASH_VERIFY_START, {
+        message: 'Verifying result bundle'
+      });
+      onStatus(OtaStatus.APPLYING, 'Verifying integrity...');
+      const isValid = await verifyHash(tempBundle, patch.bundleHash);
+      if (!isValid) {
+        console.error('[otaCore] Result bundle hash mismatch | expected:', patch.bundleHash, 'path:', tempBundle);
+        log.emit(OtaEvent.HASH_MISMATCH, {
+          message: 'Result bundle hash mismatch',
+          version: patch.toVersion,
+          metadata: {
+            expected: patch.bundleHash,
+            path: tempBundle
+          }
+        });
+        throw new Error('Result bundle hash mismatch');
+      }
+      log.emit(OtaEvent.HASH_VERIFY_SUCCESS, {
+        message: 'Result bundle verified'
+      });
+    }
+
+    // ── Step 9: Atomic Commit ──
+    if (await ReactNativeBlobUtil.fs.exists(finalBundlePath)) {
+      await ReactNativeBlobUtil.fs.unlink(finalBundlePath);
+    }
+    await ReactNativeBlobUtil.fs.mv(tempBundle, finalBundlePath);
+
+    // ── Step 10: Update Metadata ──
+    const newMetadata = registerNewVersion(metadata, patch.toVersion);
+    await saveMetadata(newMetadata);
+    const totalMs = Date.now() - totalStart;
+    log.emit(OtaEvent.PATCH_SUCCESS, {
+      version: patch.toVersion,
+      durationMs: totalMs,
+      sizeKB: patchSizeBytes / 1024
+    });
+    onStatus(OtaStatus.SUCCESS, `Update V${patch.toVersion} Successful!`, {
+      patchSizeKB: patchSizeBytes / 1024,
+      downloadMs,
+      applyMs,
+      totalMs,
+      fromCache
+    });
+
+    // ── Step 11: Reload ──
+    // CRITICAL: Mark healthy BEFORE reload — reloadBundle() calls Runtime.exit(0)
+    // and JS will NOT run again before restart. Native OtaBundleResolver sets
+    // lastLaunchSuccessful=false before loading the new bundle. Without this call,
+    // the next cold boot sees false → rollback to previous version.
+    NativeBsPatch.markAsHealthy();
+    if (__DEV__) {
+      console.log(`[otaCore] V${patch.toVersion} marked healthy — reloading.`);
+    }
+    NativeBsPatch.reloadBundle();
+  } catch (error) {
+    if (__DEV__) {
+      console.error('[otaCore] Pipeline failed:', error);
+    }
+
+    // ── Fallback: Full Bundle Download ──
+    if (patch.fullBundleUrl) {
+      try {
+        onStatus(OtaStatus.DOWNLOADING, 'Fallback: Downloading full bundle...');
+        const storage = getStorage(config);
+        const url = await storage.getUpdateFileUrl(patch.fullBundleUrl || patch.filename, config);
+        await downloadWithRetry(url, tempBundle, config, onProgress, {});
+
+        // Verify full bundle hash
+        if (patch.bundleHash) {
+          const isValid = await verifyHash(tempBundle, patch.bundleHash);
+          if (!isValid) {
+            let actualHash = '';
+            let size;
+            try {
+              actualHash = await ReactNativeBlobUtil.fs.hash(tempBundle, 'sha256');
+              const stat = await ReactNativeBlobUtil.fs.stat(tempBundle);
+              size = stat.size;
+            } catch {
+              // stat failure is non-fatal
+            }
+            if (__DEV__) {
+              console.error('[otaCore] Full bundle hash mismatch | expected:', patch.bundleHash, 'actual:', actualHash);
+            }
+            log.emit(OtaEvent.HASH_MISMATCH, {
+              message: 'Full bundle hash mismatch',
+              metadata: {
+                expected: patch.bundleHash,
+                actual: actualHash,
+                size
+              }
+            });
+            throw new Error('Full bundle hash mismatch after fallback');
+          }
+        }
+
+        // Atomic swap
+        if (await ReactNativeBlobUtil.fs.exists(finalBundlePath)) {
+          await ReactNativeBlobUtil.fs.unlink(finalBundlePath);
+        }
+        await ReactNativeBlobUtil.fs.mv(tempBundle, finalBundlePath);
+        const metadata = await loadMetadata(config.baseAppVersion);
+        const newMetadata = registerNewVersion(metadata, patch.toVersion);
+        await saveMetadata(newMetadata);
+
+        // ── CRITICAL: Mark healthy BEFORE reload so native OtaBundleResolver
+        // does NOT see lastLaunchSuccessful=false on the very next boot and
+        // immediately rollback the version we just successfully downloaded.
+        // (reloadBundle() calls Runtime.exit(0) — JS won't run again before restart)
+        NativeBsPatch.markAsHealthy();
+        if (__DEV__) {
+          console.log(`[otaCore] Fallback V${patch.toVersion} marked healthy — reloading.`);
+        }
+        onStatus(OtaStatus.SUCCESS, `Fallback successful! Reloading...`);
+        NativeBsPatch.reloadBundle();
+        return;
+      } catch (fallbackError) {
+        if (__DEV__) {
+          console.error('[otaCore] Full bundle fallback also failed:', fallbackError);
+        }
+      }
+    }
+    onStatus(OtaStatus.ERROR, `Error: ${error.message}`);
+    throw error;
+  }
+};
+//# sourceMappingURL=otaCore.js.map