@fireota/react-native 0.0.0-stage → 0.1.1

package/android/src/main/java/dev/fireota/reactnative/FireOTAStore.kt

@@ -0,0 +1,207 @@
+package dev.fireota.reactnative
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.content.pm.PackageManager
+import android.os.Build
+import java.io.DataInputStream
+import java.io.File
+import java.io.FileInputStream
+import java.io.FileOutputStream
+import java.security.MessageDigest
+import java.util.UUID
+import java.util.zip.GZIPInputStream
+import org.json.JSONObject
+
+/**
+ * On-device OTA state. Bundles live in app-private storage:
+ *   filesDir/fireota/releases/<releaseId>/index.android.bundle (+ drawable-* assets)
+ *
+ * Launch rules (resolveLaunchBundle, once per process):
+ *  - a new native binary (store update / reinstall) discards every OTA bundle;
+ *  - a pending release is promoted to current and must confirm (markSuccess) during this launch;
+ *  - a current release that reaches a second launch unconfirmed is rolled back to the previous one.
+ */
+internal class FireOTAStore(private val context: Context) {
+  private val prefs: SharedPreferences = context.getSharedPreferences("dev.fireota", Context.MODE_PRIVATE)
+  private val root = File(context.filesDir, "fireota/releases")
+
+  fun releaseDir(releaseId: String) = File(root, safe(releaseId))
+  fun bundleFile(releaseId: String) = File(releaseDir(releaseId), BUNDLE_NAME)
+
+  val installationId: String
+    get() = prefs.getString(KEY_INSTALLATION, null) ?: UUID.randomUUID().toString().also {
+      prefs.edit().putString(KEY_INSTALLATION, it).apply()
+    }
+
+  fun get(key: String): String? = prefs.getString(key, null)
+  fun isUnconfirmed() = prefs.getBoolean(KEY_UNCONFIRMED, false)
+
+  @Synchronized
+  fun resolveLaunchBundle(): String? {
+    val binary = binaryVersion()
+    if (prefs.getString(KEY_BINARY, null) != binary) {
+      root.deleteRecursively()
+      prefs.edit()
+        .remove(KEY_CURRENT).remove(KEY_PREVIOUS).remove(KEY_PENDING).remove(KEY_DOWNLOADED)
+        .putBoolean(KEY_UNCONFIRMED, false).putInt(KEY_ATTEMPTS, 0)
+        .putString(KEY_BINARY, binary)
+        .commit()
+    }
+
+    val edit = prefs.edit()
+    val pending = prefs.getString(KEY_PENDING, null)
+    if (pending != null && bundleFile(pending).exists()) {
+      edit.putString(KEY_PREVIOUS, prefs.getString(KEY_CURRENT, null))
+        .putString(KEY_CURRENT, pending)
+        .putBoolean(KEY_UNCONFIRMED, true)
+        .putInt(KEY_ATTEMPTS, 0)
+    }
+    edit.remove(KEY_PENDING).commit()
+
+    if (prefs.getBoolean(KEY_UNCONFIRMED, false)) {
+      val attempts = prefs.getInt(KEY_ATTEMPTS, 0) + 1
+      if (attempts >= 2) {
+        val failed = prefs.getString(KEY_CURRENT, null)
+        prefs.edit()
+          .putString(KEY_FAILED, failed)
+          .putString(KEY_CURRENT, prefs.getString(KEY_PREVIOUS, null))
+          .remove(KEY_PREVIOUS)
+          .putBoolean(KEY_UNCONFIRMED, false)
+          .putInt(KEY_ATTEMPTS, 0)
+          .commit()
+        failed?.let { releaseDir(it).deleteRecursively() }
+      } else {
+        prefs.edit().putInt(KEY_ATTEMPTS, attempts).commit()
+      }
+    }
+
+    val current = prefs.getString(KEY_CURRENT, null) ?: return null
+    val file = bundleFile(current)
+    if (!file.exists()) {
+      prefs.edit().remove(KEY_CURRENT).putBoolean(KEY_UNCONFIRMED, false).commit()
+      return null
+    }
+    return file.absolutePath
+  }
+
+  fun markSuccess() {
+    prefs.edit().putBoolean(KEY_UNCONFIRMED, false).putInt(KEY_ATTEMPTS, 0).commit()
+    val keep = setOf(get(KEY_CURRENT), get(KEY_PREVIOUS), get(KEY_PENDING), get(KEY_DOWNLOADED)).filterNotNull().map(::safe)
+    root.listFiles()?.filter { it.name !in keep }?.forEach { it.deleteRecursively() }
+  }
+
+  fun setPending(releaseId: String) {
+    require(bundleFile(releaseId).exists()) { "Release $releaseId has not been downloaded." }
+    prefs.edit().putString(KEY_PENDING, releaseId).remove(KEY_DOWNLOADED).commit()
+  }
+
+  fun clear(key: String) = prefs.edit().remove(key).commit()
+
+  /** Streams the package to disk, verifies its SHA-256, then unpacks it atomically. */
+  fun download(url: String, expectedSha256: String, releaseId: String) {
+    require(url.startsWith("https://")) { "Updates must be downloaded over HTTPS." }
+    root.mkdirs()
+    val tmp = File(root, ".${safe(releaseId)}.download")
+    val connection = java.net.URL(url).openConnection() as java.net.HttpURLConnection
+    connection.connectTimeout = 15_000
+    connection.readTimeout = 60_000
+    connection.instanceFollowRedirects = true
+    try {
+      if (connection.responseCode !in 200..299) throw IllegalStateException("Download failed: HTTP ${connection.responseCode}")
+      val digest = MessageDigest.getInstance("SHA-256")
+      connection.inputStream.use { input ->
+        FileOutputStream(tmp).use { output ->
+          val buffer = ByteArray(64 * 1024)
+          while (true) {
+            val read = input.read(buffer)
+            if (read < 0) break
+            digest.update(buffer, 0, read)
+            output.write(buffer, 0, read)
+          }
+        }
+      }
+      val actual = digest.digest().joinToString("") { "%02x".format(it) }
+      if (!actual.equals(expectedSha256, ignoreCase = true)) throw SecurityException("Checksum mismatch: the update was rejected.")
+
+      val staging = File(root, ".${safe(releaseId)}.staging")
+      staging.deleteRecursively()
+      unpack(tmp, staging)
+      if (!File(staging, BUNDLE_NAME).exists()) throw IllegalStateException("The update package has no $BUNDLE_NAME.")
+      val target = releaseDir(releaseId)
+      target.deleteRecursively()
+      if (!staging.renameTo(target)) throw IllegalStateException("Could not store the update.")
+      prefs.edit().putString(KEY_DOWNLOADED, releaseId).commit()
+    } finally {
+      connection.disconnect()
+      tmp.delete()
+    }
+  }
+
+  /**
+   * FireOTA package: gzip( "FOTA1\n" | u32 header length | JSON {files:[{path,size}]} | file bytes... ).
+   * Paths are validated so a package can never write outside its release directory.
+   */
+  private fun unpack(archive: File, into: File) {
+    DataInputStream(GZIPInputStream(FileInputStream(archive), 64 * 1024)).use { input ->
+      val magic = ByteArray(6)
+      input.readFully(magic)
+      if (String(magic, Charsets.US_ASCII) != "FOTA1\n") throw IllegalStateException("Not a FireOTA package.")
+      val headerLength = input.readInt()
+      if (headerLength <= 0 || headerLength > 4 * 1024 * 1024) throw IllegalStateException("Invalid package header.")
+      val header = ByteArray(headerLength)
+      input.readFully(header)
+      val files = JSONObject(String(header, Charsets.UTF_8)).getJSONArray("files")
+      val base = into.canonicalFile
+      for (i in 0 until files.length()) {
+        val entry = files.getJSONObject(i)
+        val path = entry.getString("path")
+        val size = entry.getLong("size")
+        val out = File(base, path).canonicalFile
+        if (path.startsWith("/") || path.contains("..") || !out.path.startsWith(base.path + File.separator)) {
+          throw SecurityException("Unsafe path in update package: $path")
+        }
+        out.parentFile?.mkdirs()
+        FileOutputStream(out).use { output ->
+          var remaining = size
+          val buffer = ByteArray(64 * 1024)
+          while (remaining > 0) {
+            val read = input.read(buffer, 0, minOf(buffer.size.toLong(), remaining).toInt())
+            if (read < 0) throw IllegalStateException("Truncated update package.")
+            output.write(buffer, 0, read)
+            remaining -= read
+          }
+        }
+      }
+    }
+  }
+
+  fun nativeVersion(): String = packageInfo()?.versionName ?: ""
+
+  private fun binaryVersion(): String {
+    val info = packageInfo() ?: return ""
+    val code = if (Build.VERSION.SDK_INT >= 28) info.longVersionCode else @Suppress("DEPRECATION") info.versionCode.toLong()
+    return "${info.versionName}-$code-${info.lastUpdateTime}"
+  }
+
+  private fun packageInfo() = try {
+    context.packageManager.getPackageInfo(context.packageName, 0)
+  } catch (_: PackageManager.NameNotFoundException) {
+    null
+  }
+
+  private fun safe(id: String) = id.replace(Regex("[^A-Za-z0-9_-]"), "")
+
+  companion object {
+    const val BUNDLE_NAME = "index.android.bundle"
+    const val KEY_INSTALLATION = "installationId"
+    const val KEY_BINARY = "binary"
+    const val KEY_CURRENT = "current"
+    const val KEY_PREVIOUS = "previous"
+    const val KEY_PENDING = "pending"
+    const val KEY_DOWNLOADED = "downloaded"
+    const val KEY_FAILED = "failed"
+    const val KEY_UNCONFIRMED = "unconfirmed"
+    const val KEY_ATTEMPTS = "attempts"
+  }
+}

package/fireota-react-native.podspec

@@ -0,0 +1,19 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "fireota-react-native"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"] || "https://www.npmjs.com/package/@fireota/react-native"
+  s.license      = package["license"]
+  s.authors      = package["author"]
+  s.platforms    = { :ios => "13.4" }
+  # Installed from node_modules by React Native autolinking; the git source is only used for trunk.
+  repo = (package["repository"].is_a?(Hash) ? package["repository"]["url"] : package["repository"]).to_s.sub(/^git\+/, "")
+  s.source       = { :git => repo, :tag => "v#{s.version}" }
+  s.source_files = "ios/**/*.{h,m}"
+  s.libraries    = "z"
+  s.dependency "React-Core"
+end

package/ios/FireOTA.h

@@ -0,0 +1,20 @@
+#import <Foundation/Foundation.h>
+#import <React/RCTBridgeModule.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * FireOTA native module. In AppDelegate (release builds):
+ *
+ *   - (NSURL *)bundleURL {
+ *     return [FireOTA bundleURL] ?: [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
+ *   }
+ */
+@interface FireOTA : NSObject <RCTBridgeModule>
+
+/// The OTA bundle to load, or nil to use the bundle shipped in the app binary.
++ (nullable NSURL *)bundleURL;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/FireOTA.m

@@ -0,0 +1,346 @@
+#import "FireOTA.h"
+
+#import <CommonCrypto/CommonDigest.h>
+#import <React/RCTReloadCommand.h>
+#import <zlib.h>
+
+static NSString *const kBundleName = @"main.jsbundle";
+static NSString *const kSuite = @"dev.fireota";
+static NSString *const kInstallation = @"installationId";
+static NSString *const kBinary = @"binary";
+static NSString *const kCurrent = @"current";
+static NSString *const kPrevious = @"previous";
+static NSString *const kPending = @"pending";
+static NSString *const kDownloaded = @"downloaded";
+static NSString *const kFailed = @"failed";
+static NSString *const kUnconfirmed = @"unconfirmed";
+static NSString *const kAttempts = @"attempts";
+
+static NSUserDefaults *FOTADefaults(void) { return [[NSUserDefaults alloc] initWithSuiteName:kSuite]; }
+
+static NSString *FOTASafe(NSString *value)
+{
+  NSCharacterSet *allowed = [NSCharacterSet characterSetWithCharactersInString:
+      @"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-"];
+  return [[value componentsSeparatedByCharactersInSet:allowed.invertedSet] componentsJoinedByString:@""];
+}
+
+static NSURL *FOTARoot(void)
+{
+  NSURL *support = [[NSFileManager defaultManager] URLsForDirectory:NSApplicationSupportDirectory
+                                                          inDomains:NSUserDomainMask].firstObject;
+  NSURL *root = [support URLByAppendingPathComponent:@"fireota/releases" isDirectory:YES];
+  [[NSFileManager defaultManager] createDirectoryAtURL:root withIntermediateDirectories:YES attributes:nil error:nil];
+  [root setResourceValue:@YES forKey:NSURLIsExcludedFromBackupKey error:nil];
+  return root;
+}
+
+static NSURL *FOTAReleaseDir(NSString *releaseId)
+{
+  return [FOTARoot() URLByAppendingPathComponent:FOTASafe(releaseId) isDirectory:YES];
+}
+
+static NSURL *FOTABundleFile(NSString *releaseId)
+{
+  return [FOTAReleaseDir(releaseId) URLByAppendingPathComponent:kBundleName];
+}
+
+/// Changes on every App Store / TestFlight install, which invalidates bundles built for the old binary.
+static NSString *FOTABinaryVersion(void)
+{
+  NSDictionary *info = [NSBundle mainBundle].infoDictionary;
+  NSDictionary *attrs = [[NSFileManager defaultManager] attributesOfItemAtPath:[NSBundle mainBundle].executablePath error:nil];
+  return [NSString stringWithFormat:@"%@-%@-%.0f", info[@"CFBundleShortVersionString"] ?: @"", info[@"CFBundleVersion"] ?: @"",
+                                    [attrs.fileModificationDate timeIntervalSince1970]];
+}
+
+static BOOL FOTAExists(NSURL *url) { return [[NSFileManager defaultManager] fileExistsAtPath:url.path]; }
+
+static BOOL FOTARead(gzFile gz, void *into, unsigned length)
+{
+  unsigned done = 0;
+  while (done < length) {
+    int n = gzread(gz, (char *)into + done, length - done);
+    if (n <= 0) return NO;
+    done += (unsigned)n;
+  }
+  return YES;
+}
+
+@implementation FireOTA
+
+RCT_EXPORT_MODULE(FireOTA)
+
++ (BOOL)requiresMainQueueSetup { return NO; }
+
+/// Same launch rules as Android: a new binary clears OTA state, a pending release is promoted and
+/// must confirm, and a release reaching a second launch unconfirmed is rolled back.
++ (nullable NSURL *)bundleURL
+{
+  static NSURL *resolved = nil;
+  static BOOL didResolve = NO;
+  @synchronized(self) {
+    NSUserDefaults *d = FOTADefaults();
+    BOOL hasPending = [d stringForKey:kPending] != nil;
+    if (didResolve && !hasPending) return resolved; // once per launch, unless a reload applies an update
+
+    NSString *binary = FOTABinaryVersion();
+    if (![[d stringForKey:kBinary] isEqualToString:binary]) {
+      [[NSFileManager defaultManager] removeItemAtURL:FOTARoot() error:nil];
+      for (NSString *key in @[ kCurrent, kPrevious, kPending, kDownloaded ]) [d removeObjectForKey:key];
+      [d setBool:NO forKey:kUnconfirmed];
+      [d setInteger:0 forKey:kAttempts];
+      [d setObject:binary forKey:kBinary];
+    }
+
+    NSString *pending = [d stringForKey:kPending];
+    if (pending && FOTAExists(FOTABundleFile(pending))) {
+      NSString *current = [d stringForKey:kCurrent];
+      if (current) [d setObject:current forKey:kPrevious]; else [d removeObjectForKey:kPrevious];
+      [d setObject:pending forKey:kCurrent];
+      [d setBool:YES forKey:kUnconfirmed];
+      [d setInteger:0 forKey:kAttempts];
+    }
+    [d removeObjectForKey:kPending];
+
+    if ([d boolForKey:kUnconfirmed]) {
+      NSInteger attempts = [d integerForKey:kAttempts] + 1;
+      if (attempts >= 2) {
+        NSString *failed = [d stringForKey:kCurrent];
+        if (failed) {
+          [d setObject:failed forKey:kFailed];
+          [[NSFileManager defaultManager] removeItemAtURL:FOTAReleaseDir(failed) error:nil];
+        }
+        NSString *previous = [d stringForKey:kPrevious];
+        if (previous) [d setObject:previous forKey:kCurrent]; else [d removeObjectForKey:kCurrent];
+        [d removeObjectForKey:kPrevious];
+        [d setBool:NO forKey:kUnconfirmed];
+        [d setInteger:0 forKey:kAttempts];
+      } else {
+        [d setInteger:attempts forKey:kAttempts];
+      }
+    }
+
+    resolved = nil;
+    NSString *current = [d stringForKey:kCurrent];
+    if (current) {
+      NSURL *file = FOTABundleFile(current);
+      if (FOTAExists(file)) {
+        resolved = file;
+      } else {
+        [d removeObjectForKey:kCurrent];
+        [d setBool:NO forKey:kUnconfirmed];
+      }
+    }
+    didResolve = YES;
+    return resolved;
+  }
+}
+
+RCT_EXPORT_METHOD(getState:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  NSUserDefaults *d = FOTADefaults();
+  NSString *installation = [d stringForKey:kInstallation];
+  if (!installation) {
+    installation = [NSUUID UUID].UUIDString.lowercaseString;
+    [d setObject:installation forKey:kInstallation];
+  }
+  NSString *version = [NSBundle mainBundle].infoDictionary[@"CFBundleShortVersionString"] ?: @"";
+  resolve(@{
+    @"installationId" : installation,
+    @"nativeVersion" : version,
+    @"appVersion" : version,
+    @"currentReleaseId" : [d stringForKey:kCurrent] ?: [NSNull null],
+    @"pendingReleaseId" : [d stringForKey:kPending] ?: [NSNull null],
+    @"previousReleaseId" : [d stringForKey:kPrevious] ?: [NSNull null],
+    @"failedReleaseId" : [d stringForKey:kFailed] ?: [NSNull null],
+    @"isFirstRun" : @([d boolForKey:kUnconfirmed]),
+  });
+}
+
+RCT_EXPORT_METHOD(downloadUpdate:(NSString *)urlString
+                  sha256:(NSString *)expected
+                  releaseId:(NSString *)releaseId
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+{
+  NSURL *url = [NSURL URLWithString:urlString];
+  if (!url || ![url.scheme isEqualToString:@"https"]) {
+    reject(@"FIREOTA_DOWNLOAD", @"Updates must be downloaded over HTTPS.", nil);
+    return;
+  }
+  NSURLSessionConfiguration *config = [NSURLSessionConfiguration defaultSessionConfiguration];
+  config.timeoutIntervalForRequest = 60;
+  NSURLSession *session = [NSURLSession sessionWithConfiguration:config];
+  [[session downloadTaskWithURL:url
+              completionHandler:^(NSURL *location, NSURLResponse *response, NSError *error) {
+                NSInteger status =
+                    [response isKindOfClass:[NSHTTPURLResponse class]] ? ((NSHTTPURLResponse *)response).statusCode : 0;
+                if (error || !location || status < 200 || status > 299) {
+                  reject(@"FIREOTA_DOWNLOAD", [NSString stringWithFormat:@"Download failed (HTTP %ld).", (long)status], error);
+                  return;
+                }
+                if (![[FireOTA sha256OfFile:location] isEqualToString:expected.lowercaseString]) {
+                  reject(@"FIREOTA_CHECKSUM", @"Checksum mismatch: the update was rejected.", nil);
+                  return;
+                }
+                NSFileManager *fm = [NSFileManager defaultManager];
+                NSURL *staging =
+                    [FOTARoot() URLByAppendingPathComponent:[NSString stringWithFormat:@".%@.staging", FOTASafe(releaseId)]];
+                [fm removeItemAtURL:staging error:nil];
+                NSString *problem = [FireOTA unpack:location into:staging];
+                if (!problem && !FOTAExists([staging URLByAppendingPathComponent:kBundleName])) {
+                  problem = @"The update package has no main.jsbundle.";
+                }
+                if (problem) {
+                  [fm removeItemAtURL:staging error:nil];
+                  reject(@"FIREOTA_DOWNLOAD", problem, nil);
+                  return;
+                }
+                NSURL *target = FOTAReleaseDir(releaseId);
+                [fm removeItemAtURL:target error:nil];
+                NSError *moveError = nil;
+                if (![fm moveItemAtURL:staging toURL:target error:&moveError]) {
+                  reject(@"FIREOTA_DOWNLOAD", @"Could not store the update.", moveError);
+                  return;
+                }
+                [FOTADefaults() setObject:releaseId forKey:kDownloaded];
+                resolve(nil);
+              }] resume];
+}
+
+RCT_EXPORT_METHOD(installUpdate:(NSString *)releaseId resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  if (!FOTAExists(FOTABundleFile(releaseId))) {
+    reject(@"FIREOTA_INSTALL", @"This release has not been downloaded.", nil);
+    return;
+  }
+  NSUserDefaults *d = FOTADefaults();
+  [d setObject:releaseId forKey:kPending];
+  [d removeObjectForKey:kDownloaded];
+  resolve(nil);
+}
+
+RCT_EXPORT_METHOD(markSuccess:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  NSUserDefaults *d = FOTADefaults();
+  [d setBool:NO forKey:kUnconfirmed];
+  [d setInteger:0 forKey:kAttempts];
+  NSMutableSet *keep = [NSMutableSet set];
+  for (NSString *key in @[ kCurrent, kPrevious, kPending, kDownloaded ]) {
+    NSString *value = [d stringForKey:key];
+    if (value) [keep addObject:FOTASafe(value)];
+  }
+  NSFileManager *fm = [NSFileManager defaultManager];
+  for (NSURL *dir in [fm contentsOfDirectoryAtURL:FOTARoot() includingPropertiesForKeys:nil options:0 error:nil]) {
+    if (![keep containsObject:dir.lastPathComponent]) [fm removeItemAtURL:dir error:nil];
+  }
+  resolve(nil);
+}
+
+RCT_EXPORT_METHOD(clearPending:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  [FOTADefaults() removeObjectForKey:kPending];
+  [FOTADefaults() removeObjectForKey:kDownloaded];
+  resolve(nil);
+}
+
+RCT_EXPORT_METHOD(clearFailed:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  [FOTADefaults() removeObjectForKey:kFailed];
+  resolve(nil);
+}
+
+/// Reloads JavaScript; React Native asks AppDelegate.bundleURL again, which applies the pending release.
+RCT_EXPORT_METHOD(restartApp:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  resolve(nil);
+  dispatch_async(dispatch_get_main_queue(), ^{
+    RCTTriggerReloadCommandListeners(@"FireOTA update");
+  });
+}
+
++ (NSString *)sha256OfFile:(NSURL *)url
+{
+  NSInputStream *stream = [NSInputStream inputStreamWithURL:url];
+  [stream open];
+  CC_SHA256_CTX ctx;
+  CC_SHA256_Init(&ctx);
+  uint8_t buffer[65536];
+  NSInteger read;
+  while ((read = [stream read:buffer maxLength:sizeof(buffer)]) > 0) CC_SHA256_Update(&ctx, buffer, (CC_LONG)read);
+  [stream close];
+  unsigned char digest[CC_SHA256_DIGEST_LENGTH];
+  CC_SHA256_Final(digest, &ctx);
+  NSMutableString *hex = [NSMutableString stringWithCapacity:CC_SHA256_DIGEST_LENGTH * 2];
+  for (int i = 0; i < CC_SHA256_DIGEST_LENGTH; i++) [hex appendFormat:@"%02x", digest[i]];
+  return hex;
+}
+
+/// FireOTA package: gzip("FOTA1\n" | u32 big-endian header length | JSON {files:[{path,size}]} | bytes).
+/// Paths are validated so a package can never write outside its release directory.
++ (nullable NSString *)unpack:(NSURL *)archive into:(NSURL *)dir
+{
+  gzFile gz = gzopen(archive.fileSystemRepresentation, "rb");
+  if (!gz) return @"Could not open the update package.";
+  char magic[6];
+  uint8_t lengthBytes[4];
+  if (!FOTARead(gz, magic, 6) || memcmp(magic, "FOTA1\n", 6) != 0 || !FOTARead(gz, lengthBytes, 4)) {
+    gzclose(gz);
+    return @"Not a FireOTA package.";
+  }
+  uint32_t headerLength = ((uint32_t)lengthBytes[0] << 24) | ((uint32_t)lengthBytes[1] << 16) |
+                          ((uint32_t)lengthBytes[2] << 8) | lengthBytes[3];
+  if (headerLength == 0 || headerLength > 4 * 1024 * 1024) {
+    gzclose(gz);
+    return @"Invalid package header.";
+  }
+  NSMutableData *header = [NSMutableData dataWithLength:headerLength];
+  if (!FOTARead(gz, header.mutableBytes, headerLength)) {
+    gzclose(gz);
+    return @"Truncated update package.";
+  }
+  id json = [NSJSONSerialization JSONObjectWithData:header options:0 error:nil];
+  NSArray *files = [json isKindOfClass:[NSDictionary class]] ? json[@"files"] : nil;
+  if (![files isKindOfClass:[NSArray class]]) {
+    gzclose(gz);
+    return @"Invalid package header.";
+  }
+
+  NSString *problem = nil;
+  NSFileManager *fm = [NSFileManager defaultManager];
+  NSString *base = [dir.path stringByStandardizingPath];
+  [fm createDirectoryAtURL:dir withIntermediateDirectories:YES attributes:nil error:nil];
+  uint8_t buffer[65536];
+  for (NSDictionary *entry in files) {
+    NSString *path = entry[@"path"];
+    if (![path isKindOfClass:[NSString class]]) {
+      problem = @"Invalid package header.";
+      break;
+    }
+    NSString *out = [[base stringByAppendingPathComponent:path] stringByStandardizingPath];
+    if ([path hasPrefix:@"/"] || [path containsString:@".."] || ![out hasPrefix:[base stringByAppendingString:@"/"]]) {
+      problem = [NSString stringWithFormat:@"Unsafe path in update package: %@", path];
+      break;
+    }
+    [fm createDirectoryAtPath:[out stringByDeletingLastPathComponent] withIntermediateDirectories:YES attributes:nil error:nil];
+    [fm createFileAtPath:out contents:nil attributes:nil];
+    NSFileHandle *handle = [NSFileHandle fileHandleForWritingAtPath:out];
+    unsigned long long remaining = [entry[@"size"] unsignedLongLongValue];
+    while (remaining > 0) {
+      unsigned chunk = (unsigned)MIN((unsigned long long)sizeof(buffer), remaining);
+      if (!FOTARead(gz, buffer, chunk)) {
+        problem = @"Truncated update package.";
+        break;
+      }
+      [handle writeData:[NSData dataWithBytes:buffer length:chunk]];
+      remaining -= chunk;
+    }
+    [handle closeFile];
+    if (problem) break;
+  }
+  gzclose(gz);
+  return problem;
+}
+
+@end

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@fireota/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Over-the-air JavaScript updates for React Native apps, served from your own Firebase project by FireOTA.",
+  "license": "MIT",
+  "author": "FireOTA",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.ts",
+  "files": [
+    "src",
+    "android/build.gradle",
+    "android/src",
+    "ios",
+    "fireota-react-native.podspec",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "react-native": ">=0.73.0"
+  },
+  "dependencies": {
+    "@fireota/react-native": "file:fireota-react-native-0.1.0.tgz"
+  },
+  "keywords": [
+    "react-native",
+    "ota",
+    "over-the-air",
+    "code-push",
+    "hot-update",
+    "firebase",
+    "updates",
+    "hermes"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sujay-Dynamisch/FireOTA.git",
+    "directory": "packages/react-native"
+  },
+  "homepage": "https://github.com/Sujay-Dynamisch/FireOTA/tree/main/packages/react-native#readme",
+  "bugs": {
+    "url": "https://github.com/Sujay-Dynamisch/FireOTA/issues"
+  }
+}