react-native-bspatch 4.1.0 → 5.0.0

package/src/ota/otaCore.ts

@@ -11,7 +11,9 @@
  *  - Structured telemetry logging
  */
 
+import { Platform } from 'react-native';
 import NativeBsPatch from '../NativeBsPatch';
+import { entryPayload, parsePublicKeys } from './entrySignature';
 import { createOtaLogger, OtaEvent } from './otaLogger';
 import {
     ASSET_LIST_FILE,
@@ -23,7 +25,7 @@ import {
     registerNewVersion,
     updateMetadata,
 } from './otaMetadata';
-import { fetchJson, GitHubRawStorageProvider } from './storage/GitHubRawStorage';
+import { normalizeChannel, R2StorageProvider } from './storage/R2Storage';
 import {
     OtaStatus,
     type OtaAsset,
@@ -35,9 +37,9 @@ import {
 
 // ─── Storage Provider Factory ──────────────────────────────────────────
 
-const DEFAULT_STORAGE = new GitHubRawStorageProvider();
+const DEFAULT_STORAGE = new R2StorageProvider();
 
-/** Explicit `config.storage` or the default static-host provider (GitHub raw, R2, CDN...). */
+/** Explicit `config.storage` or the default provider (R2 public URL). */
 const getStorage = (config: OtaConfig): OtaStorageProvider =>
     config.storage ?? DEFAULT_STORAGE;
 
@@ -104,8 +106,9 @@ export const verifyHash = async (
 };
 
 /**
- * When `config.publicKey` is set, an RSA/ECDSA SHA-256 signature is mandatory
- * and must verify (fail closed). Without a public key, signing is not enforced.
+ * When there is a public key (config.publicKey, else the embedded ones), an RSA/ECDSA
+ * SHA-256 signature is mandatory and must verify against one of them (fail closed):
+ * the backup key takes over without a store build if the primary is lost.
  */
 const assertSigned = async (
     filePath: string,
@@ -113,19 +116,55 @@ const assertSigned = async (
     config: OtaConfig,
     what: string,
 ): Promise<void> => {
-    if (!config.publicKey) return;
-    const valid =
-        !!signature &&
-        (await NativeBsPatch.verifySignature(filePath, signature, config.publicKey).catch(() => false));
+    const keys = parsePublicKeys(config.publicKey);
+    if (keys.length === 0) return;
+    let valid = false;
+    for (const key of signature ? keys : []) {
+        if (await NativeBsPatch.verifySignature(filePath, signature!, key).catch(() => false)) {
+            valid = true;
+            break;
+        }
+    }
     if (!valid) {
         throw new Error(`${what} signature missing or invalid`);
     }
 };
 
+/**
+ * With config.publicKey the registry entry itself must be signed and meant for this app,
+ * so a registry served by someone else (e.g. a lapsed domain) can't hand over another
+ * flavor's, platform's or release's signed bundle, or swap the asset manifest.
+ */
+const assertEntrySigned = async (patch: OtaPatch, config: OtaConfig): Promise<void> => {
+    if (parsePublicKeys(config.publicKey).length === 0) return;
+    const channel = config.customServer?.channel;
+    const mismatch =
+        patch.appVersion !== config.appVersion
+            ? 'appVersion'
+            : patch.platform !== Platform.OS
+                ? 'platform'
+                : channel && patch.flavor !== normalizeChannel(channel)
+                    ? 'flavor'
+                    : patch.assetManifestUrl && !patch.assetManifestHash
+                        ? 'assetManifestHash'
+                        : null;
+    if (mismatch) {
+        throw new Error(`Registry entry rejected: ${mismatch} doesn't match this app`);
+    }
+    const payloadPath = `${OTA_DIR}/entry-payload.txt`;
+    await NativeBsPatch.writeFile(payloadPath, entryPayload(patch));
+    try {
+        await assertSigned(payloadPath, patch.entrySignature, config, 'Registry entry');
+    } finally {
+        await NativeBsPatch.removePath(payloadPath).catch(() => {});
+    }
+};
+
 /**
  * Download a file with retry logic using exponential backoff.
  * Native streams to `${destPath}.part` and renames only on a 2xx response, so a
- * cut-off download or an error page never sits at destPath looking complete.
+ * cut-off download or an error page never sits at destPath looking complete;
+ * each retry resumes where the last attempt stopped.
  * @returns Size of the downloaded file in bytes
  */
 const downloadWithRetry = async (
@@ -136,6 +175,7 @@ const downloadWithRetry = async (
 ): Promise<number> => {
     const retryLimit = Math.max(1, config.network?.retry ?? 3);
     const timeout = config.network?.timeoutMs ?? 30000;
+    const headers = JSON.stringify(config.customServer?.headers ?? {});
     const subscription = NativeBsPatch.onDownloadProgress(e => {
         // total is -1 without a Content-Length
         if (e.path === destPath && e.total > 0) {
@@ -146,7 +186,7 @@ const downloadWithRetry = async (
     try {
         for (let i = 0; ; i++) {
             try {
-                return await NativeBsPatch.downloadFile(url, destPath, timeout);
+                return await NativeBsPatch.downloadFile(url, destPath, timeout, headers);
             } catch (e) {
                 if (i >= retryLimit - 1) throw e;
                 const delay = Math.pow(2, i) * 1000; // Exponential backoff: 1s, 2s, 4s...
@@ -194,6 +234,7 @@ const isSafeRelativePath = (p: string): boolean =>
  */
 const downloadAndSyncAssets = async (
     assetManifestUrl: string,
+    assetManifestHash: string | undefined,
     version: number,
     config: OtaConfig,
     log: ReturnType<typeof createOtaLogger>,
@@ -210,7 +251,14 @@ const downloadAndSyncAssets = async (
 
     let assets: OtaAsset[] = [];
     try {
-        const manifest = await fetchJson(assetManifestUrl, 10000);
+        // Through a file: its hash is in the (signed) registry entry
+        const manifestPath = `${versionDir}/asset-manifest.json`;
+        await downloadWithRetry(assetManifestUrl, manifestPath, config, () => {});
+        if (!(await verifyHash(manifestPath, assetManifestHash))) {
+            throw new Error('hash mismatch');
+        }
+        const manifest = JSON.parse(await fs.readFile(manifestPath));
+        await fs.removePath(manifestPath).catch(() => {});
         // Hash/ext/path become file names: reject anything unexpected
         assets = (manifest.assets || []).filter(
             (a: any) =>
@@ -342,6 +390,7 @@ export const selectUpdate = (
  * Full path (store build, no patch, or patch path failed):
  *   download full bundle → hash → signature
  * Both then: sync assets → atomic commit → metadata → mark healthy → reload.
+ * Only a patch-path failure falls back to the full bundle, never a failed commit.
  *
  * The store build's bundle is never used as a patch source: it can't be
  * reproduced byte-for-byte at build time, so the first OTA is always a full download.
@@ -382,12 +431,21 @@ const runUpdatePipeline = async (
 
     const log = createOtaLogger(config.onEvent);
     await ensureOtaDir();
+    try {
+        await assertEntrySigned(patch, config);
+    } catch (error) {
+        log.emit(OtaEvent.SIGNATURE_INVALID, { version: patch.toVersion, error: (error as Error).message });
+        onStatus(OtaStatus.ERROR, `Error: ${(error as Error).message}`);
+        throw error;
+    }
     const totalStart = Date.now();
     const fs = NativeBsPatch;
 
     const finalBundlePath =
         getBundlePath(patch.toVersion, config.baseAppVersion) || '';
     const tempBundle = `${finalBundlePath}.tmp`;
+    /** Compressed full bundle, before decompressing into tempBundle */
+    const tempDownload = `${finalBundlePath}.download`;
     const versionDir = `${OTA_DIR}/v${patch.toVersion}`;
     const localPatchPath = getLocalPatchPath(patch, DOCUMENT_DIR);
 
@@ -414,6 +472,14 @@ const runUpdatePipeline = async (
         }
     }
 
+    // Room for the download, the decompressed bundle and its assets; a full disk mid-write
+    // would fail later and leave the user's storage fuller
+    const needBytes = (patch.bundleSize ?? 0) * 3 + 20 * 1024 * 1024;
+    const freeBytes = await fs.getFreeDiskSpace().catch(() => Number.MAX_SAFE_INTEGER);
+    if (freeBytes < needBytes) {
+        throw new Error(`Not enough free storage: ${Math.ceil(needBytes / 1048576)} MB needed`);
+    }
+
     await fs.mkdir(versionDir);
 
     const download = async (remoteName: string, dest: string) => {
@@ -450,8 +516,10 @@ const runUpdatePipeline = async (
         throw new Error(`${what} hash mismatch`);
     };
 
+    type BundleMetrics = Omit<OtaMetrics, 'totalMs' | 'fromCache'>;
+
     /** tempBundle is verified: sync assets, swap it in, record the version, reload. */
-    const commit = async (metrics: Omit<OtaMetrics, 'totalMs' | 'fromCache'>) => {
+    const commit = async (metrics: BundleMetrics) => {
         if (patch.assetManifestUrl) {
             const manifestUrl = await getStorage(config).getUpdateFileUrl(
                 patch.assetManifestUrl,
@@ -459,6 +527,7 @@ const runUpdatePipeline = async (
             );
             await downloadAndSyncAssets(
                 manifestUrl,
+                patch.assetManifestHash,
                 patch.toVersion,
                 config,
                 log,
@@ -498,7 +567,8 @@ const runUpdatePipeline = async (
         }
     };
 
-    const applyPatchFile = async (sourcePath: string) => {
+    /** Leaves the verified result at tempBundle. */
+    const applyPatchFile = async (sourcePath: string): Promise<BundleMetrics> => {
         onStatus(OtaStatus.DOWNLOADING, `Downloading V${patch.toVersion}...`);
         const { downloadMs, sizeBytes } = await download(patch.filename!, localPatchPath);
 
@@ -528,24 +598,33 @@ const runUpdatePipeline = async (
 
         await assertHash(tempBundle, patch.bundleHash, 'Result bundle');
         await assertSigned(tempBundle, patch.bundleSignature, config, 'Bundle');
-        await commit({ patchSizeKB: sizeBytes / 1024, downloadMs, applyMs });
+        return { patchSizeKB: sizeBytes / 1024, downloadMs, applyMs };
     };
 
-    const installFullBundle = async () => {
+    /** Leaves the verified full bundle at tempBundle. */
+    const installFullBundle = async (): Promise<BundleMetrics> => {
         if (!patch.fullBundleUrl) {
             throw new Error(`No full bundle for V${patch.toVersion}`);
         }
         log.emit(OtaEvent.FALLBACK_FULL_BUNDLE, { version: patch.toVersion });
         onStatus(OtaStatus.DOWNLOADING, `Downloading V${patch.toVersion} (full bundle)...`);
-        const { downloadMs, sizeBytes } = await download(patch.fullBundleUrl, tempBundle);
+        const compression = patch.fullBundleCompression;
+        const { downloadMs, sizeBytes } = await download(patch.fullBundleUrl, compression ? tempDownload : tempBundle);
+        if (compression) {
+            onStatus(OtaStatus.APPLYING, 'Decompressing...');
+            await fs.decompressFile(tempDownload, tempBundle, compression);
+            await fs.removePath(tempDownload).catch(() => {});
+        }
         await assertHash(tempBundle, patch.bundleHash, 'Full bundle');
         await assertSigned(tempBundle, patch.bundleSignature, config, 'Full bundle');
-        await commit({ patchSizeKB: sizeBytes / 1024, downloadMs, applyMs: 0 });
+        return { patchSizeKB: sizeBytes / 1024, downloadMs, applyMs: 0 };
     };
 
     const cleanup = async () => {
         await fs.removePath(localPatchPath).catch(() => {});
         await fs.removePath(tempBundle).catch(() => {});
+        // tempDownload's .part stays: the next attempt resumes it
+        await fs.removePath(tempDownload).catch(() => {});
     };
 
     // Patch only from an OTA bundle we installed ourselves (byte-identical to the build output)
@@ -557,10 +636,12 @@ const runUpdatePipeline = async (
         !!sourcePath &&
         (await fs.exists(sourcePath));
 
+    // Only a failed patch falls back to the full bundle; a failed commit (asset sync)
+    // would fail the same way after re-downloading the whole bundle
+    let metrics: BundleMetrics | undefined;
     if (canPatch) {
         try {
-            await applyPatchFile(sourcePath!);
-            return;
+            metrics = await applyPatchFile(sourcePath!);
         } catch (error) {
             await cleanup();
             if (__DEV__) {
@@ -574,7 +655,7 @@ const runUpdatePipeline = async (
     }
 
     try {
-        await installFullBundle();
+        await commit(metrics ?? (await installFullBundle()));
     } catch (error) {
         await cleanup();
         onStatus(OtaStatus.ERROR, `Error: ${(error as Error).message}`);

package/src/ota/storage/{GitHubRawStorage.ts → R2Storage.ts}

@@ -1,8 +1,8 @@
 import type { OtaConfig, OtaPatch, OtaStorageProvider } from '../types';
 
 /**
- * Storage Provider for any static host with this layout: GitHub raw, a public
- * Cloudflare R2 bucket (r2.dev or custom domain), S3, a CDN...
+ * Storage Provider for the public URL of a Cloudflare R2 bucket (r2.dev or a custom
+ * domain): plain HTTP GETs, so any static host serving the same layout also works.
  *
  * Direct URL mapping:
  * - Manifest: `${baseUrl}/${baseFolder}/ota_registry.json`
@@ -10,19 +10,23 @@ import type { OtaConfig, OtaPatch, OtaStorageProvider } from '../types';
  * - Assets: `${baseUrl}/${baseFolder}/assets/${hash}.${ext}`
  *
  * NOTE: Only the registry is mutable: it is fetched with Cache-Control: no-cache
- * and a timestamp query param (GitHub's CDN caches for 5 minutes). Bundles,
+ * and a timestamp query param (the CDN in front of the bucket may cache it). Bundles,
  * patches, manifests and assets are never overwritten, so they stay cacheable.
  */
 
-/** Headers to bypass GitHub CDN cache on mutable files (registry, manifests) */
+/** Headers to bypass the CDN cache on mutable files (registry, manifests) */
 const NO_CACHE_HEADERS = { 'Cache-Control': 'no-cache' };
 
 /** GET + JSON.parse with a timeout (fetch has none of its own); rejects on non-2xx. */
-export const fetchJson = async (url: string, timeoutMs: number): Promise<any> => {
+export const fetchJson = async (
+    url: string,
+    timeoutMs: number,
+    headers?: Record<string, string>,
+): Promise<any> => {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
-        const res = await fetch(url, { headers: NO_CACHE_HEADERS, signal: controller.signal });
+        const res = await fetch(url, { headers: { ...NO_CACHE_HEADERS, ...headers }, signal: controller.signal });
         if (!res.ok) {
             throw new Error(`HTTP ${res.status} for ${url}`);
         }
@@ -36,20 +40,20 @@ export const fetchJson = async (url: string, timeoutMs: number): Promise<any> =>
 const bustCache = (url: string): string =>
     `${url}?cb=${Date.now()}`;
 
-const normalizeChannel = (channel: string): string => {
+export const normalizeChannel = (channel: string): string => {
     const lower = channel.toLowerCase();
     if (lower === 'dev') return 'development';
     if (lower === 'prod') return 'production';
     return lower;
 };
 
-export class GitHubRawStorageProvider implements OtaStorageProvider {
+export class R2StorageProvider implements OtaStorageProvider {
     async fetchManifest(config: OtaConfig): Promise<OtaPatch[]> {
         if (!config.customServer) {
-            throw new Error('[GitHubRawStorage] customServer configuration missing');
+            throw new Error('[R2Storage] customServer configuration missing');
         }
 
-        const { baseUrl, channel, baseFolder = 'ota' } = config.customServer;
+        const { baseUrl, channel, baseFolder = 'ota', headers } = config.customServer;
         const channelName = normalizeChannel(channel);
         const normalizedBaseUrl = baseUrl.endsWith('/')
             ? baseUrl.slice(0, -1)
@@ -60,11 +64,11 @@ export class GitHubRawStorageProvider implements OtaStorageProvider {
         );
 
         try {
-            const registry = await fetchJson(registryUrl, 15000);
+            const registry = await fetchJson(registryUrl, 15000, headers);
 
             if (!config.appVersion) {
                 throw new Error(
-                    '[GitHubRawStorage] config.appVersion is required to query OTA registry',
+                    '[R2Storage] config.appVersion is required to query OTA registry',
                 );
             }
             const appGroup = registry?.apps?.[config.appVersion];
@@ -73,7 +77,7 @@ export class GitHubRawStorageProvider implements OtaStorageProvider {
             return flavorGroup?.patches ?? [];
         } catch (error) {
             // Surface it: "no patches" would report a broken registry as up to date
-            throw new Error(`[GitHubRawStorage] Manifest fetch error: ${(error as Error).message}`);
+            throw new Error(`[R2Storage] Manifest fetch error: ${(error as Error).message}`);
         }
     }
 

package/src/ota/types.ts

@@ -49,16 +49,40 @@ export type OtaPatch = {
     minAppVersion?: string;
     /** Full bundle file: used when there is no OTA bundle to patch from, or the patch fails */
     fullBundleUrl?: string;
+    /** Size of the full bundle in bytes: download progress when it arrives Content-Encoded */
+    bundleSize?: number;
     /** RSA/ECDSA SHA-256 signature (base64) of the patch file */
     signature?: string;
     /** RSA/ECDSA SHA-256 signature (base64) of the resulting bundle */
     bundleSignature?: string;
     /** URL to the asset manifest JSON for this version */
     assetManifestUrl?: string;
+    /** SHA-256 of the asset manifest file (covered by entrySignature) */
+    assetManifestHash?: string;
+    /** Signature (base64) of entryPayload(entry): required when a public key is set */
+    entrySignature?: string;
     /** Target platform for this patch */
     platform?: string;
     /** Flavor/channel for this patch */
     flavor?: string;
+    /** How fullBundleUrl is compressed ('gzip' | 'bz2'); absent = raw .hbc */
+    fullBundleCompression?: string;
+    /** Native runtime fingerprint the bundle was built against: installs only on a matching binary */
+    runtimeFingerprint?: string;
+    /** Hermes bytecode version of the bundle: installs only on a runtime that reads it */
+    hermesBytecodeVersion?: number;
+    /** Client features this entry needs; a client missing one skips the entry */
+    requires?: string[];
+
+    // ── Release controls (not signed: they can only hold an update back or release a signed one) ──
+    /** Kill switch: no client installs this version */
+    disabled?: boolean;
+    /** Staged rollout: share of installs (0-100) that get this version, by a stable per-install bucket */
+    rolloutPercent?: number;
+    /** QA: only these install IDs (useOta().installId) get this version */
+    allowInstallIds?: string[];
+    /** Apply as soon as it's ready instead of on the next launch (BACKGROUND_DOWNLOAD) */
+    mandatory?: boolean;
 };
 
 /**
@@ -99,6 +123,8 @@ export type OtaMetrics = {
 export type OtaNetworkStrategy = {
     retry?: number;
     timeoutMs?: number;
+    /** Automatic downloads only on Wi-Fi/Ethernet (manual applyUpdate always downloads) */
+    wifiOnly?: boolean;
 };
 
 export type OtaConfig = {
@@ -119,8 +145,19 @@ export type OtaConfig = {
     /** Telemetry: structured event callback for analytics */
     onEvent?: OtaEventCallback;
     /**
-     * SPKI public key (PEM or base64) for RSA/ECDSA signature verification.
-     * When set, patches and bundles without a valid signature are rejected.
+     * POSTs every OTA event as JSON to `url` (fire-and-forget), with installId, platform,
+     * appVersion, appBuild, runtimeFingerprint, flavor and the running OTA version attached.
+     */
+    telemetry?: { url: string; headers?: Record<string, string> };
+    /**
+     * Minimum time between automatic update checks (app start / foreground / checkUpdate()).
+     * checkUpdate({ force: true }) ignores it. Default 10 minutes.
+     */
+    minCheckIntervalMs?: number;
+    /**
+     * SPKI public key(s), PEM or base64 (comma-separated for several), for RSA/ECDSA
+     * signature verification. Defaults to the keys `patch` embedded in the app.
+     * When there is a key, unsigned or wrongly signed updates are rejected.
      */
     publicKey?: string;
 
@@ -130,13 +167,15 @@ export type OtaConfig = {
      * Read-only and public: never put upload credentials here, they ship inside the app.
      */
     customServer?: {
-        /** e.g. https://raw.githubusercontent.com/<owner>/<repo>/<branch> */
+        /** R2 public URL, e.g. https://pub-<id>.r2.dev or a custom domain */
         baseUrl: string;
         channel: string;
         baseFolder?: string;
+        /** Extra headers on every request (registry, bundles, assets), e.g. auth for a private server */
+        headers?: Record<string, string>;
     };
 
-    /** Storage provider instance (optional, defaults to GitHubRawStorageProvider) */
+    /** Storage provider instance (optional, defaults to R2StorageProvider) */
     storage?: OtaStorageProvider;
 };
 
@@ -163,12 +202,17 @@ export type OtaState = {
     metrics: OtaMetrics | null;
     /** True if a background update has been downloaded and prepared silently */
     isUpdateReady: boolean;
+    /** The ready update is marked mandatory: it reloads as soon as the app is in the foreground */
+    isMandatory: boolean;
+    /** Stable random ID of this install (rollout bucket, QA allow-lists, telemetry) */
+    installId: string;
     applyUpdate: () => Promise<void>;
     /** Installs and reloads `version` from the last checked manifest (full bundle, or a patch from the current version) */
     applyVersion: (version: number) => Promise<void>;
     resetToFactory: () => Promise<void>;
     markAsHealthy: () => Promise<void>;
-    checkUpdate: () => Promise<void>;
+    /** Checks now unless the last check was under minCheckIntervalMs ago (force: always) */
+    checkUpdate: (options?: { force?: boolean }) => Promise<void>;
     /** Reload the React Native JS bundle immediately to apply downloaded update */
     reloadBundle: () => void;
 };