@fireota/react-native 0.1.0 → 0.2.0

package/README.md

@@ -1,119 +1,254 @@
-# @fireota/react-native
-
-Over-the-air JavaScript updates for React Native, served from **your own Firebase project** by [FireOTA](https://www.npmjs.com/package/@fireota/cli).
-
-- SHA-256 verified downloads, straight from your Firebase Storage bucket
-- Staged rollouts, pause and rollback from the FireOTA dashboard
-- Automatic rollback when a new bundle crashes before it starts
-- Old updates are discarded when a new store build is installed
-- No third-party native dependencies
-
-> **Beta (0.x).** Verified on Android with React Native 0.87. iOS support is implemented but not yet device-tested.
-
-## Install
-
-```sh
-npm install @fireota/react-native
-npm install --save-dev @fireota/cli
-cd ios && pod install
-```
-
-Requires a bare React Native app, 0.73 or newer (Expo: run `npx expo prebuild`).
-
-## Android
-
-In `MainApplication.kt` (React Native 0.76+ template):
-
-```kotlin
-import dev.fireota.reactnative.FireOTA
-
-override val reactHost: ReactHost by lazy {
-  getDefaultReactHost(
-    context = applicationContext,
-    packageList = PackageList(this).packages,
-    jsBundleFilePath = if (BuildConfig.DEBUG) null else FireOTA.getJSBundleFile(applicationContext),
-  )
-}
-```
-
-Older templates that override `reactNativeHost`:
-
-```kotlin
-override fun getJSBundleFile(): String? =
-  if (BuildConfig.DEBUG) super.getJSBundleFile()
-  else FireOTA.getJSBundleFile(applicationContext) ?: super.getJSBundleFile()
-```
-
-## iOS
-
-```objc
-// AppDelegate.mm
-#import <FireOTA.h>
-
-- (NSURL *)bundleURL
-{
-#if DEBUG
-  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
-#else
-  return [FireOTA bundleURL] ?: [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
-#endif
-}
-```
-
-Swift: add `#import <FireOTA.h>` to the bridging header and return `FireOTA.bundleURL() ?? Bundle.main.url(forResource: "main", withExtension: "jsbundle")` from `bundleURL()` in release builds.
-
-## Configure
-
-Call once, early and unconditionally (e.g. `index.js`). Reaching this call confirms a new bundle starts; a bundle that never reaches it is rolled back on the next launch.
-
-```js
-import FireOTA from "@fireota/react-native";
-
-if (!__DEV__) {
-  FireOTA.configure({
-    appId: "YOUR_APP_ID",
-    serverUrl: "https://ota.example.com",
-    runtimeVersion: "1.3.0", // must equal this store build; bump when native code changes
-    channel: "production",
-  });
-}
-```
-
-By default updates download silently and apply on the next cold start; mandatory updates restart immediately. To show your own prompt, set `checkOnAppStart: false` and use the API:
-
-```js
-const result = await FireOTA.checkForUpdate();
-if (result.updateAvailable) {
-  // show your UI with result.release.version / result.release.notes, then:
-  await FireOTA.downloadUpdate(result.release);
-  await FireOTA.installUpdate(result.release, "immediate");
-}
-```
-
-## API
-
-| Method | Description |
-| --- | --- |
-| `configure(options)` | Initialize once at startup (required). |
-| `sync()` | Check, download and install, honouring install modes. |
-| `checkForUpdate()` | `{ updateAvailable, reason?, release? }` |
-| `downloadUpdate(release)` | Download and verify; the running bundle is untouched. |
-| `installUpdate(release, mode)` | `"nextRestart"` or `"immediate"`. |
-| `reload()` | Restart now to apply a pending update. |
-| `clearPendingUpdate()` | Drop a downloaded update that is not applied yet. |
-| `getCurrentRelease()` | `{ releaseId, pendingReleaseId, installationId }` |
-| `getUpdateStatus()` | Current status string. |
-
-Options: `appId`, `serverUrl`, `runtimeVersion` (required), `channel`, `checkOnAppStart`, `installMode`, `mandatoryInstallMode`, `onStatusChange(status, detail)`.
-
-## Publishing updates
-
-Use [`@fireota/cli`](https://www.npmjs.com/package/@fireota/cli):
-
-```sh
-npx fireota publish --app YOUR_APP_ID --platform android --version 1.3.1 --runtime 1.3.0 --channel production --rollout 10
-```
-
-## License
-
-MIT
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Sujay-Dynamisch/FireOTA/main/public/logo-mark.png" alt="FireOTA" width="96" />
+</p>
+
+<h1 align="center">FireOTA</h1>
+
+<p align="center">
+  Over-the-air updates for React Native — served from <strong>your own Firebase project</strong>.<br />
+  Staged rollouts, checksum verification, automatic rollback, audit logs and a CI-ready CLI.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@fireota/react-native"><img alt="@fireota/react-native" src="https://img.shields.io/npm/v/@fireota/react-native?label=%40fireota%2Freact-native" /></a>
+  <a href="https://www.npmjs.com/package/@fireota/cli"><img alt="@fireota/cli" src="https://img.shields.io/npm/v/@fireota/cli?label=%40fireota%2Fcli" /></a>
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue" />
+</p>
+
+---
+
+## What it does
+
+Ship JavaScript fixes and features to your React Native app **without a store review**:
+
+1. `npx fireota publish` bundles your JS (Hermes bytecode + images) and uploads it to **your** Firebase Storage bucket.
+2. FireOTA records the release — version, runtime, SHA-256, channel, rollout — and writes every action to an audit log.
+3. The SDK in your app checks for a compatible release on launch, downloads it **directly from your bucket**, verifies the checksum, and applies it on the next start.
+4. If the new bundle crashes before starting, the device rolls back to the previous bundle automatically and reports it.
+
+You own the artifacts and pay Google directly for storage and bandwidth. FireOTA never proxies downloads.
+
+## Features
+
+| | |
+| --- | --- |
+| **Releases** | Strict state machine (draft → ready → published → paused / rolled back / archived), atomic publish and rollback |
+| **Rollouts** | Deterministic per-device buckets, 0–100 %, per-platform channel targets (Android and iOS independent) |
+| **Safety** | Server-side SHA-256, exact runtime matching, native-version constraints, automatic pause on high failure rates |
+| **Teams** | Organizations, roles (owner, admin, release manager, developer, viewer), Supabase Row Level Security |
+| **Integrations** | Scoped API keys, CI/CD API, HMAC-signed webhooks with retries, notifications, analytics |
+| **Firebase** | Google OAuth (PKCE) per customer project, encrypted refresh tokens, live Storage write verification |
+
+## Repository layout
+
+```text
+src/                     Web dashboard + API (TanStack Start, React, Tailwind)
+  routes/                Pages and HTTP routes (/api/public/v1/*, /health, /docs)
+  lib/backend/           Release engine, OTA resolver, Firebase adapter, RBAC, webhooks
+  lib/api/               Server functions used by the dashboard
+  components/docs/       Documentation site content (/docs)
+supabase/migrations/     Database schema, RLS policies and transactional functions
+packages/react-native/   @fireota/react-native — the app SDK (Kotlin + Objective-C)
+packages/cli/            @fireota/cli — bundle, upload and publish from a terminal or CI
+tests/                   Integration, end-to-end and package-format tests
+```
+
+## Quick start (local)
+
+**Prerequisites:** Node.js 20+, a [Supabase](https://supabase.com) project, a Google Cloud OAuth client.
+
+```sh
+git clone https://github.com/Sujay-Dynamisch/FireOTA.git
+cd FireOTA
+npm install
+```
+
+### 1. Environment
+
+Create `.env` in the project root (never commit it):
+
+```sh
+# Supabase -> Project Settings -> API
+SUPABASE_URL="https://<project-ref>.supabase.co"
+SUPABASE_PUBLISHABLE_KEY="sb_publishable_..."
+VITE_SUPABASE_URL="https://<project-ref>.supabase.co"
+VITE_SUPABASE_PUBLISHABLE_KEY="sb_publishable_..."
+SUPABASE_PROJECT_ID="<project-ref>"
+VITE_SUPABASE_PROJECT_ID="<project-ref>"
+
+# Server-only secrets
+SUPABASE_SERVICE_ROLE_KEY="..."        # Supabase -> API Keys -> Secret key (bypasses RLS)
+FIREOTA_ENCRYPTION_KEY="..."           # random; encrypts Google tokens and webhook secrets — never change it
+FIREOTA_CRON_SECRET="..."              # bearer token for the maintenance endpoint
+
+# Google Cloud -> APIs & Services -> Credentials -> OAuth client (Web application)
+GOOGLE_CLIENT_ID="..."
+GOOGLE_CLIENT_SECRET="..."
+GOOGLE_REDIRECT_URI="http://localhost:8080/api/public/v1/firebase/callback"
+```
+
+Generate random secrets with:
+
+```sh
+node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
+```
+
+### 2. Database
+
+Apply every file in `supabase/migrations/` in order — with the Supabase CLI (`supabase link` then `supabase db push`) or by running them in the SQL editor.
+
+### 3. Auth and Google OAuth
+
+- **Supabase → Authentication → URL Configuration:** Site URL `http://localhost:8080`; add redirect URLs `http://localhost:8080/dashboard`, `/onboarding`, `/reset-password`.
+- **Supabase → Authentication → Providers → Google:** enable it with your OAuth client for "Continue with Google".
+- **Google Cloud → OAuth client → Authorised redirect URIs:** add `http://localhost:8080/api/public/v1/firebase/callback` and `https://<project-ref>.supabase.co/auth/v1/callback`.
+
+### 4. Run
+
+```sh
+npm run dev        # http://localhost:8080
+```
+
+Open `/signup`, create your workspace, connect a Firebase project (Cloud Storage must be set up) and register your app.
+
+## Deploy to Vercel
+
+The repository includes [`vercel.json`](vercel.json). Nitro detects Vercel and builds a Node.js function plus static assets.
+
+1. Import the repository in Vercel (no framework preset needed).
+2. Add every variable from the `.env` section under **Project → Settings → Environment Variables**, with production URLs:
+   - `GOOGLE_REDIRECT_URI=https://<your-domain>/api/public/v1/firebase/callback`
+   - `CRON_SECRET=<random>` — Vercel sends it to the maintenance cron automatically.
+3. Deploy, then update the production URLs in Supabase Auth and in the Google OAuth client.
+4. Check `https://<your-domain>/health/ready` returns `{"status":"ok"}`.
+
+The cron in `vercel.json` runs the maintenance job (webhook retries, OAuth state cleanup) daily, which works on the Hobby plan. On Pro, change the schedule to `*/5 * * * *` for faster webhook retries.
+
+> **Upload size on Vercel:** Vercel Functions accept request bodies up to **4.5 MB**. Larger update packages must be published against a deployment without that limit (or a direct-to-Storage upload, on the roadmap).
+
+## Install
+
+```sh
+npm install @fireota/react-native
+npm install --save-dev @fireota/cli
+cd ios && pod install
+```
+
+Requires a bare React Native app, 0.73 or newer (Expo: run `npx expo prebuild`).
+
+## Android
+
+In `MainApplication.kt` (React Native 0.76+ template):
+
+```kotlin
+import dev.fireota.reactnative.FireOTA
+
+override val reactHost: ReactHost by lazy {
+  getDefaultReactHost(
+    context = applicationContext,
+    packageList = PackageList(this).packages,
+    jsBundleFilePath = if (BuildConfig.DEBUG) null else FireOTA.getJSBundleFile(applicationContext),
+  )
+}
+```
+
+Older templates that override `reactNativeHost`:
+
+```kotlin
+override fun getJSBundleFile(): String? =
+  if (BuildConfig.DEBUG) super.getJSBundleFile()
+  else FireOTA.getJSBundleFile(applicationContext) ?: super.getJSBundleFile()
+```
+
+## iOS
+
+```objc
+// AppDelegate.mm
+#import <FireOTA.h>
+
+- (NSURL *)bundleURL
+{
+#if DEBUG
+  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
+#else
+  return [FireOTA bundleURL] ?: [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
+#endif
+}
+```
+
+Swift: add `#import <FireOTA.h>` to the bridging header and return `FireOTA.bundleURL() ?? Bundle.main.url(forResource: "main", withExtension: "jsbundle")` from `bundleURL()` in release builds.
+
+## Configure
+
+Call once, early and unconditionally (e.g. `index.js`). Reaching this call confirms a new bundle starts; a bundle that never reaches it is rolled back on the next launch.
+
+```js
+import FireOTA from "@fireota/react-native";
+
+if (!__DEV__) {
+  FireOTA.configure({
+    appId: "YOUR_APP_ID",
+    serverUrl: "https://ota.example.com",
+    runtimeVersion: "1.3.0", // must equal this store build; bump when native code changes
+    channel: "production",
+  });
+}
+```
+
+By default updates download silently and apply on the next cold start; mandatory updates restart immediately. To show your own prompt, set `checkOnAppStart: false` and use the API:
+
+```js
+const result = await FireOTA.checkForUpdate();
+if (result.updateAvailable) {
+  // show your UI with result.release.message (what changed) and result.release.id, then:
+  await FireOTA.downloadUpdate(result.release);
+  await FireOTA.installUpdate(result.release, "immediate");
+}
+```
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `configure(options)` | Initialize once at startup (required). |
+| `sync()` | Check, download and install, honouring install modes. |
+| `checkForUpdate()` | `{ updateAvailable, reason?, release? }` |
+| `downloadUpdate(release)` | Download and verify; the running bundle is untouched. |
+| `installUpdate(release, mode)` | `"nextRestart"` or `"immediate"`. |
+| `reload()` | Restart now to apply a pending update. |
+| `clearPendingUpdate()` | Drop a downloaded update that is not applied yet. |
+| `getCurrentRelease()` | `{ releaseId, pendingReleaseId, installationId }` |
+| `getUpdateStatus()` | Current status string. |
+
+Options: `appId`, `serverUrl`, `runtimeVersion` (required), `channel`, `checkOnAppStart`, `installMode`, `mandatoryInstallMode`, `codeSigningCertificate`, `onStatusChange(status, detail)`.
+
+## Versioning
+
+Like Expo, an update is identified by its **ID**, not a version number, and belongs to exactly one **runtime version**. The runtime version describes the native code of a store build (Play Store / App Store): the app only receives updates published for the runtime it was built with, so an update can never reach a binary it is incompatible with. Bump `runtimeVersion` (and publish a new store build) whenever native code changes. Publishers may add an optional human label (`--version 1.3.1-hotfix`).
+
+## Code signing (optional)
+
+Prove every update was built by you. Generate a key pair with `npx fireota signing generate`, register the public key in the dashboard (app → Code signing) and embed it in the app:
+
+```js
+FireOTA.configure({
+  // …
+  codeSigningCertificate: `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqh…
+-----END PUBLIC KEY-----`,
+});
+```
+
+With a certificate set, the SDK verifies the RSA-SHA256 signature natively (Android `java.security`, iOS Security framework) **before** downloading, and rejects unsigned or wrongly signed updates — even if the server or your Firebase bucket were compromised. The signature covers the package's SHA-256, the runtime version and the platform, and the download is then checked against that SHA-256.
+
+## Publishing updates
+
+Use [`@fireota/cli`](https://www.npmjs.com/package/@fireota/cli):
+
+```sh
+npx fireota publish --app YOUR_APP_ID --platform all --runtime 1.3.0 --channel production --rollout 10 --message "Fix checkout crash"
+```
+
+## License
+
+MIT

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

@@ -2,11 +2,15 @@ package dev.fireota.reactnative
 
 import android.content.Intent
 import android.os.Process
+import android.util.Base64
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReactContextBaseJavaModule
 import com.facebook.react.bridge.ReactMethod
+import java.security.KeyFactory
+import java.security.Signature
+import java.security.spec.X509EncodedKeySpec
 import java.util.concurrent.Executors
 
 class FireOTAModule(private val reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
@@ -47,6 +51,23 @@ class FireOTAModule(private val reactContext: ReactApplicationContext) : ReactCo
     }
   }
 
+  /**
+   * Verifies an RSA-SHA256 (PKCS#1 v1.5) update signature against the app's embedded public key
+   * (base64 X.509 SubjectPublicKeyInfo). Any parsing problem counts as an invalid signature.
+   */
+  @ReactMethod
+  fun verifySignature(message: String, signatureBase64: String, publicKeyBase64: String, promise: Promise) {
+    try {
+      val key = KeyFactory.getInstance("RSA").generatePublic(X509EncodedKeySpec(Base64.decode(publicKeyBase64, Base64.DEFAULT)))
+      val verifier = Signature.getInstance("SHA256withRSA")
+      verifier.initVerify(key)
+      verifier.update(message.toByteArray(Charsets.UTF_8))
+      promise.resolve(verifier.verify(Base64.decode(signatureBase64, Base64.DEFAULT)))
+    } catch (e: Throwable) {
+      promise.resolve(false)
+    }
+  }
+
   @ReactMethod
   fun installUpdate(releaseId: String, promise: Promise) {
     try {

package/fireota-react-native.podspec

@@ -16,4 +16,5 @@ Pod::Spec.new do |s|
   s.source_files = "ios/**/*.{h,m}"
   s.libraries    = "z"
   s.dependency "React-Core"
+  s.frameworks = "Security"
 end

package/ios/FireOTA.m

@@ -1,6 +1,7 @@
 #import "FireOTA.h"
 
 #import <CommonCrypto/CommonDigest.h>
+#import <Security/Security.h>
 #import <React/RCTReloadCommand.h>
 #import <zlib.h>
 
@@ -251,6 +252,39 @@ RCT_EXPORT_METHOD(clearFailed:(RCTPromiseResolveBlock)resolve reject:(RCTPromise
   resolve(nil);
 }
 
+/// Verifies an RSA-SHA256 (PKCS#1 v1.5) update signature against the app's embedded public key.
+/// publicKey is base64 PKCS#1 (the JS layer unwraps the PEM's SubjectPublicKeyInfo).
+RCT_EXPORT_METHOD(verifySignature:(NSString *)message
+                  signature:(NSString *)signatureBase64
+                  publicKey:(NSString *)publicKeyBase64
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+{
+  NSData *keyData = [[NSData alloc] initWithBase64EncodedString:publicKeyBase64 options:0];
+  NSData *signature = [[NSData alloc] initWithBase64EncodedString:signatureBase64 options:0];
+  NSData *payload = [message dataUsingEncoding:NSUTF8StringEncoding];
+  if (!keyData || !signature || !payload) {
+    resolve(@NO);
+    return;
+  }
+  NSDictionary *attributes = @{
+    (__bridge id)kSecAttrKeyType : (__bridge id)kSecAttrKeyTypeRSA,
+    (__bridge id)kSecAttrKeyClass : (__bridge id)kSecAttrKeyClassPublic,
+  };
+  CFErrorRef error = NULL;
+  SecKeyRef key = SecKeyCreateWithData((__bridge CFDataRef)keyData, (__bridge CFDictionaryRef)attributes, &error);
+  if (!key) {
+    if (error) CFRelease(error);
+    resolve(@NO);
+    return;
+  }
+  Boolean valid = SecKeyVerifySignature(key, kSecKeyAlgorithmRSASignatureMessagePKCS1v15SHA256,
+                                        (__bridge CFDataRef)payload, (__bridge CFDataRef)signature, &error);
+  if (error) CFRelease(error);
+  CFRelease(key);
+  resolve(@(valid));
+}
+
 /// Reloads JavaScript; React Native asks AppDelegate.bundleURL again, which applies the pending release.
 RCT_EXPORT_METHOD(restartApp:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fireota/react-native",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Over-the-air JavaScript updates for React Native apps, served from your own Firebase project by FireOTA.",
   "license": "MIT",
   "author": "FireOTA",
@@ -22,9 +22,6 @@
   "peerDependencies": {
     "react-native": ">=0.73.0"
   },
-  "dependencies": {
-    "@fireota/react-native": "file:fireota-react-native-0.1.0.tgz"
-  },
   "keywords": [
     "react-native",
     "ota",

package/src/index.ts

@@ -1,9 +1,12 @@
 /**
  * FireOTA React Native SDK.
  *
- * Flow: check -> download (native, SHA-256 verified) -> install (pending) -> applied on the
- * next start (or immediately for mandatory updates) -> the new bundle confirms itself on
- * launch; a bundle that never confirms is rolled back to the previous one by the native loader.
+ * Flow: check -> (signature verified, when code signing is on) -> download (native, SHA-256
+ * verified) -> install (pending) -> applied on the next start (or immediately for mandatory
+ * updates) -> the new bundle confirms itself on launch; a bundle that never confirms is
+ * rolled back to the previous one by the native loader.
+ *
+ * Updates are identified by their ID (like Expo) and target exactly one runtime version.
  */
 import { NativeModules, Platform } from "react-native";
 
@@ -25,6 +28,11 @@ export interface FireOTAConfig {
   /** Must equal the runtime version of the release; bump it whenever native code changes. */
   runtimeVersion: string;
   channel?: string;
+  /**
+   * PEM public key (contents of fireota-public.pem). When set, every update must carry a valid
+   * signature from the matching private key or it is rejected before download.
+   */
+  codeSigningCertificate?: string;
   /** Check (and download) automatically when configure() runs. Default true. */
   checkOnAppStart?: boolean;
   /** When a normal update is applied. Default "nextRestart". */
@@ -35,12 +43,20 @@ export interface FireOTAConfig {
 }
 
 export interface AvailableUpdate {
+  /** The update's unique ID. */
   id: string;
+  /** Optional human label set by the publisher ("" when none). */
   version: string;
   runtimeVersion: string;
   mandatory: boolean;
   notes: string;
+  /** What changed, as written by the publisher (same as notes). */
+  message?: string;
+  /** Shared by the Android and iOS updates published together. */
+  groupId?: string | null;
+  createdAt?: string;
   bundle: { url: string; hash: string; size: number };
+  signature?: { value: string; keyId: string | null; algorithm: string } | null;
 }
 
 export interface CheckResult {
@@ -70,12 +86,14 @@ interface FireOTANative {
   clearPending(): Promise<void>;
   clearFailed(): Promise<void>;
   restartApp(): Promise<void>;
+  verifySignature(message: string, signatureBase64: string, publicKeyBase64: string): Promise<boolean>;
 }
 
 const native = NativeModules["FireOTA"] as FireOTANative | undefined;
 const PROTOCOL_VERSION = "1";
 
-let config: Required<Omit<FireOTAConfig, "onStatusChange">> & Pick<FireOTAConfig, "onStatusChange">;
+let config: Required<Omit<FireOTAConfig, "onStatusChange" | "codeSigningCertificate">> &
+  Pick<FireOTAConfig, "onStatusChange" | "codeSigningCertificate">;
 let status: UpdateStatus = "idle";
 let running: Promise<CheckResult> | null = null;
 
@@ -157,9 +175,87 @@ export async function checkForUpdate(): Promise<CheckResult> {
   return result;
 }
 
-/** Downloads and verifies (SHA-256) an update. The running bundle is untouched. */
+// ---------- code signing ----------
+
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+function base64ToBytes(input: string): Uint8Array {
+  const clean = input.replace(/[^A-Za-z0-9+/]/g, "");
+  const out: number[] = [];
+  for (let i = 0; i < clean.length; i += 4) {
+    const n = [0, 1, 2, 3].map((k) => (i + k < clean.length ? B64.indexOf(clean[i + k]!) : 0));
+    const triple = (n[0]! << 18) | (n[1]! << 12) | (n[2]! << 6) | n[3]!;
+    out.push((triple >> 16) & 255);
+    if (i + 2 < clean.length) out.push((triple >> 8) & 255);
+    if (i + 3 < clean.length) out.push(triple & 255);
+  }
+  return new Uint8Array(out);
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const triple = (bytes[i]! << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+    out += B64[(triple >> 18) & 63]! + B64[(triple >> 12) & 63]!;
+    out += i + 1 < bytes.length ? B64[(triple >> 6) & 63]! : "=";
+    out += i + 2 < bytes.length ? B64[triple & 63]! : "=";
+  }
+  return out;
+}
+
+/** Reads one DER element header; returns where its content starts and how long it is. */
+function derElement(der: Uint8Array, offset: number) {
+  let length = der[offset + 1]!;
+  let start = offset + 2;
+  if (length & 0x80) {
+    const bytes = length & 0x7f;
+    length = 0;
+    for (let i = 0; i < bytes; i += 1) length = (length << 8) | der[start + i]!;
+    start += bytes;
+  }
+  return { tag: der[offset]!, start, end: start + length };
+}
+
+/**
+ * The certificate is a PEM "PUBLIC KEY" (X.509 SubjectPublicKeyInfo). Android accepts that
+ * directly; iOS's SecKeyCreateWithData wants the inner PKCS#1 RSAPublicKey.
+ */
+function publicKeyForPlatform(pem: string): string {
+  const spki = base64ToBytes(pem.replace(/-----[^-]+-----/g, ""));
+  if (Platform.OS !== "ios") return bytesToBase64(spki);
+  const outer = derElement(spki, 0); // SEQUENCE
+  const algorithm = derElement(spki, outer.start); // SEQUENCE { oid, null }
+  const bitString = derElement(spki, algorithm.end); // BIT STRING
+  if (outer.tag !== 0x30 || algorithm.tag !== 0x30 || bitString.tag !== 0x03) throw new Error("Invalid code signing certificate.");
+  return bytesToBase64(spki.slice(bitString.start + 1, bitString.end)); // skip the unused-bits byte
+}
+
+/** Same message the CLI signs and the server verifies. */
+function signatureMessage(runtimeVersion: string, platform: string, sha256: string) {
+  return `fireota-update-v1\n${runtimeVersion}\n${platform}\n${sha256.toLowerCase()}`;
+}
+
+async function assertSigned(release: AvailableUpdate) {
+  const certificate = config.codeSigningCertificate;
+  if (!certificate) return;
+  const signature = release.signature?.value;
+  const valid = signature
+    ? await requireNative().verifySignature(
+        signatureMessage(config.runtimeVersion, Platform.OS, release.bundle.hash),
+        signature,
+        publicKeyForPlatform(certificate),
+      )
+    : false;
+  if (!valid) {
+    void report("install_failed", release.id, { reason: signature ? "signature_invalid" : "unsigned" });
+    throw new Error(signature ? "The update signature is not valid for this app." : "The update is not signed; this app only accepts signed updates.");
+  }
+}
+
+/** Verifies the signature (when code signing is on), then downloads and checks SHA-256. The running bundle is untouched. */
 export async function downloadUpdate(release: AvailableUpdate) {
   if (!/^[0-9a-f]{64}$/i.test(release.bundle.hash)) throw new Error("The update has no valid checksum.");
+  await assertSigned(release);
   setStatus("downloading", { releaseId: release.id });
   void report("download_started", release.id);
   await requireNative().downloadUpdate(release.bundle.url, release.bundle.hash.toLowerCase(), release.id);