@protobase/mobile 0.57.2 → 0.57.3

package/android/build.gradle

@@ -24,6 +24,7 @@ android {
         targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
         versionCode 1
         versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
     }
     buildTypes {
         release {
@@ -39,6 +40,14 @@ android {
     if (liveUpdate != null) {
         sourceSets.main.java.srcDirs += 'src/liveupdate/java'
     }
+    // The guard's tests, in the repository only (harness/ runs them): on the JVM, and on a device the same again, on
+    // Android's own org.json, beside the guard in a running Capacitor app.
+    if (liveUpdate != null && file('src/androidTestLiveupdate').exists()) {
+        sourceSets.test.java.srcDirs += 'src/testLiveupdate/java'
+        sourceSets.androidTest.java.srcDirs += ['src/testLiveupdate/java', 'src/androidTestLiveupdate/java']
+        sourceSets.androidTest.assets.srcDirs += 'src/androidTestLiveupdate/assets'
+        sourceSets.androidTest.manifest.srcFile 'src/androidTestLiveupdate/AndroidManifest.xml'
+    }
     compileOptions {
         sourceCompatibility JavaVersion.VERSION_21
         targetCompatibility JavaVersion.VERSION_21
@@ -55,6 +64,14 @@ dependencies {
     if (liveUpdate != null) {
         implementation liveUpdate
     }
+    // The guard's checks run on the JVM (src/testLiveupdate, or jvm-tests.sh without Android), with the real org.json
+    // in place of android.jar's stubs.
+    testImplementation 'junit:junit:4.13.2'
+    testImplementation 'org.json:json:20250517'
+    androidTestImplementation 'androidx.test:runner:1.7.0'
+    androidTestImplementation 'androidx.test:core:1.7.0'
+    androidTestImplementation 'androidx.test.ext:junit:1.3.0'
+    androidTestImplementation 'androidx.appcompat:appcompat:1.7.1'
 }
 
 // The plugin list the app loads must match what this build compiles, however the build was started (protobase mobile,

package/android/src/liveupdate/java/net/protobase/mobile/Bounded.java

@@ -0,0 +1,30 @@
+package net.protobase.mobile;
+
+import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+
+/** Reads a whole stream or file of at most a fixed size, so a planted or served file cannot fill the memory. */
+final class Bounded {
+
+    private Bounded() {}
+
+    static byte[] read(InputStream in, int limit, String what) throws IOException, BundleRefused {
+        ByteArrayOutputStream out = new ByteArrayOutputStream();
+        byte[] buffer = new byte[16 * 1024];
+        for (int read; (read = in.read(buffer)) != -1; ) {
+            if (out.size() + read > limit) throw new BundleRefused(what + " is larger than " + limit + " bytes");
+            out.write(buffer, 0, read);
+        }
+        return out.toByteArray();
+    }
+
+    static byte[] read(File file, int limit, String what) throws IOException, BundleRefused {
+        if (!file.isFile()) throw new BundleRefused(what + " is missing");
+        try (InputStream in = new FileInputStream(file)) {
+            return read(in, limit, what);
+        }
+    }
+}

package/android/src/liveupdate/java/net/protobase/mobile/BundleCheck.java

@@ -0,0 +1,53 @@
+package net.protobase.mobile;
+
+import java.io.File;
+import java.io.IOException;
+import java.security.PublicKey;
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * Checks a bundle folder on disk before the app runs it: its statement names its id and is signed with the app's key
+ * for this binary, its manifest is the one the statement names, every file it lists is there with its checksum and
+ * size, and the folder holds nothing else, no link either.
+ */
+final class BundleCheck {
+
+    private BundleCheck() {}
+
+    static ReleaseStatement check(File dir, String bundleId, PublicKey key, ReleaseBinary binary) throws BundleRefused {
+        try {
+            if (!dir.isDirectory() || BundleRemoval.isLink(dir)) throw new BundleRefused("it is no bundle folder");
+            ReleaseStatement statement = ReleaseStatement.verify(Bounded.read(new File(dir, ReleaseStatement.FILE), ReleaseStatement.MAX_BYTES, "its statement"), bundleId, key);
+            binary.accept(statement);
+            ReleaseManifest manifest = ReleaseManifest.verify(Bounded.read(new File(dir, ReleaseManifest.FILE), ReleaseManifest.MAX_BYTES, "its manifest"), statement, dir);
+            Set<String> expected = new HashSet<>();
+            expected.add(ReleaseStatement.FILE);
+            expected.add(ReleaseManifest.FILE);
+            for (ReleaseManifest.Item item : manifest.items) expected.add(item.href);
+            walk(dir, "", expected, new int[] { expected.size() * 2 });
+            for (ReleaseManifest.Item item : manifest.items) {
+                File file = new File(dir, item.href);
+                if (!file.isFile()) throw new BundleRefused("it lacks " + item.href);
+                if (file.length() != item.size || !Sha256.of(file).equals(item.checksum)) throw new BundleRefused("its " + item.href + " is not the file its manifest names");
+            }
+            return statement;
+        } catch (IOException e) {
+            throw new BundleRefused("it could not be read");
+        }
+    }
+
+    // Every entry below `dir`, as `prefix` + its name: a file must be expected, a folder is walked, a link refuses the
+    // bundle. `budget` bounds the entries, so a planted tree cannot keep the check busy.
+    private static void walk(File dir, String prefix, Set<String> expected, int[] budget) throws BundleRefused {
+        File[] children = dir.listFiles();
+        if (children == null) throw new BundleRefused("it could not be read");
+        for (File child : children) {
+            if (--budget[0] < 0) throw new BundleRefused("its folder holds files its manifest does not list");
+            String path = prefix + child.getName();
+            if (BundleRemoval.isLink(child)) throw new BundleRefused("its folder holds a link");
+            if (child.isDirectory()) walk(child, path + "/", expected, budget);
+            else if (!expected.contains(path)) throw new BundleRefused("its folder holds " + path + ", which its manifest does not list");
+        }
+    }
+}

package/android/src/liveupdate/java/net/protobase/mobile/BundleRefused.java

@@ -0,0 +1,9 @@
+package net.protobase.mobile;
+
+/** Why the guard refuses a release or a bundle: its message says so to page script, never a library's own message. */
+final class BundleRefused extends Exception {
+
+    BundleRefused(String reason) {
+        super(reason);
+    }
+}

package/android/src/liveupdate/java/net/protobase/mobile/BundleRemoval.java

@@ -0,0 +1,33 @@
+package net.protobase.mobile;
+
+import java.io.File;
+import java.io.IOException;
+
+/** Deletes a folder the guard owns, never following a link out of it: a link is deleted itself. */
+final class BundleRemoval {
+
+    private BundleRemoval() {}
+
+    static void delete(File root, File target) {
+        if (!target.exists() || !BundlesFolder.contains(root, target)) return;
+        deleteTree(target);
+    }
+
+    private static void deleteTree(File file) {
+        if (file.isDirectory() && !isLink(file)) {
+            File[] children = file.listFiles();
+            if (children != null) for (File child : children) deleteTree(child);
+        }
+        file.delete();
+    }
+
+    /** Whether `file` is a link: its canonical path is not its parent's followed by its name. One that cannot be resolved counts. */
+    static boolean isLink(File file) {
+        try {
+            File parent = file.getAbsoluteFile().getParentFile();
+            return parent == null || !file.getCanonicalPath().equals(new File(parent.getCanonicalFile(), file.getName()).getPath());
+        } catch (IOException e) {
+            return true;
+        }
+    }
+}

package/android/src/liveupdate/java/net/protobase/mobile/GuardedLiveUpdate.java

@@ -1,5 +1,8 @@
 package net.protobase.mobile;
 
+import android.app.Activity;
+import android.content.SharedPreferences;
+import android.util.Base64;
 import com.getcapacitor.JSObject;
 import com.getcapacitor.Logger;
 import com.getcapacitor.Plugin;
@@ -8,13 +11,23 @@ import com.getcapacitor.PluginConfig;
 import com.getcapacitor.PluginMethod;
 import com.getcapacitor.annotation.CapacitorPlugin;
 import io.capawesome.capacitorjs.plugins.liveupdate.LiveUpdatePlugin;
+import java.io.File;
+import java.io.IOException;
 import java.lang.reflect.Method;
 import java.net.URI;
 import java.net.URISyntaxException;
+import java.security.GeneralSecurityException;
+import java.security.KeyFactory;
+import java.security.PublicKey;
+import java.security.interfaces.RSAPublicKey;
+import java.security.spec.X509EncodedKeySpec;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Iterator;
 import java.util.List;
+import java.util.UUID;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
 import java.util.concurrent.atomic.AtomicInteger;
 import org.json.JSONObject;
 
@@ -28,8 +41,13 @@ import org.json.JSONObject;
  *   upgrade that adds a method leaves no LiveUpdate at all rather than an open one.
  * - The methods the shell needs that take no input clear what page script passed before the stock code reads it.
  * - downloadBundle takes only a manifest from the app's own releases URL, `releasesUrl + "/" + bundleId`, over https
- *   or loopback http, with `publicKey` pinned, so the stock code checks each file's signature (LiveUpdate.java:1633-1654)
- *   and a caller's checksum and signature are dropped. A few per run of the app, so a loop cannot drain the data plan.
+ *   or loopback http, and downloads it itself (ReleaseDownload), bound by the release's statement to the id, the pinned
+ *   `publicKey`, this binary and its order; a caller's checksum and signature are dropped. A few per run of the app, so
+ *   a loop cannot drain the data plan.
+ * - setNextBundle checks the bundle on disk (BundleCheck), then takes it only above the running bundle's order and not
+ *   below the highest the app downloaded; a refused bundle that is neither running nor next is deleted, as the stock
+ *   code deletes an unused one (LiveUpdate.java:803-810). It is the only way to a downloaded bundle: reset, sync and the
+ *   rest are refused, reload only runs the next bundle and a rollback goes to the built-in one (LiveUpdate.java:1411).
  * - Ids are a single safe component naming a direct child of the bundles folder: the stock code joins them to its path
  *   unchecked (LiveUpdate.java:665-667,1299-1302).
  * - Everything else is refused: deleting, resetting, the vendor's cloud, config, channel and ids.
@@ -46,6 +64,17 @@ public class GuardedLiveUpdate extends LiveUpdatePlugin {
 
     private static final int MAX_DOWNLOADS = 3;
     private static final AtomicInteger downloads = new AtomicInteger();
+    // One download at a time, and one lock over the highest order downloaded and the choice of the next bundle.
+    private static final ExecutorService downloader = Executors.newSingleThreadExecutor();
+    private static final Object order = new Object();
+    // Beside the bundles folder, on the same file system, so a checked download moves into it whole.
+    private static final String DOWNLOADS = "_protobase_live_update_downloads";
+    private static final String ORDER_PREFS = "ProtobaseLiveUpdate";
+    private static final String HIGHEST_ORDER = "highestOrder";
+
+    private String releasesUrl;
+    private PublicKey publicKey;
+    private ReleaseBinary binary;
 
     @Override
     public void load() {
@@ -65,9 +94,38 @@ public class GuardedLiveUpdate extends LiveUpdatePlugin {
         if (config.getInt("readyTimeout", 0) <= 0) {
             refuseToLoad("plugins.LiveUpdate.readyTimeout must be above 0 in a Protobase app");
         }
+        releasesUrl = config.getString("releasesUrl");
+        if (!ownSource(releasesUrl)) {
+            refuseToLoad("plugins.LiveUpdate.releasesUrl must be an https URL, or http to the device itself, in a Protobase app");
+        }
+        publicKey = rsaKey(config.getString("publicKey"));
+        String fingerprint = config.getString("fingerprint");
+        String shellVersion = config.getString("shellVersion");
+        if (fingerprint == null || !Hex.isHex(fingerprint, 16) || !ReleaseStatement.isVersion(shellVersion)) {
+            refuseToLoad("plugins.LiveUpdate needs the binary's fingerprint and shellVersion in a Protobase app: run protobase mobile again");
+        }
+        binary = new ReleaseBinary(getContext().getPackageName(), fingerprint, shellVersion);
+        // What a download the app did not finish left.
+        File downloads = new File(getContext().getFilesDir(), DOWNLOADS);
+        BundleRemoval.delete(downloads, downloads);
         super.load();
     }
 
+    // The key the releases are signed with: an RSA public key as base64 SPKI DER, with or without PEM's lines, as the
+    // stock code reads it (LiveUpdate.java:744-755).
+    private static PublicKey rsaKey(String value) {
+        if (value == null || value.trim().isEmpty()) refuseToLoad("plugins.LiveUpdate.publicKey must be set in a Protobase app");
+        String body = value.replace("-----BEGIN PUBLIC KEY-----", "").replace("-----END PUBLIC KEY-----", "").replaceAll("\\s", "");
+        try {
+            PublicKey key = KeyFactory.getInstance("RSA").generatePublic(new X509EncodedKeySpec(Base64.decode(body, Base64.DEFAULT)));
+            if (!(key instanceof RSAPublicKey)) refuseToLoad("plugins.LiveUpdate.publicKey must be an RSA public key in a Protobase app");
+            return key;
+        } catch (GeneralSecurityException | IllegalArgumentException e) {
+            refuseToLoad("plugins.LiveUpdate.publicKey must be an RSA public key in a Protobase app");
+            return null;
+        }
+    }
+
     // Capacitor then leaves the plugin unregistered, logging only that it failed to load (PluginHandle.java:98-109), so
     // the reason is logged here.
     private static void refuseToLoad(String reason) {
@@ -80,12 +138,6 @@ public class GuardedLiveUpdate extends LiveUpdatePlugin {
     @Override
     @PluginMethod
     public void downloadBundle(PluginCall call) {
-        String releasesUrl = getConfig().getString("releasesUrl");
-        String publicKey = getConfig().getString("publicKey");
-        if (!ownSource(releasesUrl) || publicKey == null || publicKey.trim().isEmpty()) {
-            Refusal.rejectMethod(call, "LiveUpdate", "downloadBundle");
-            return;
-        }
         String bundleId = call.getString("bundleId");
         boolean allowed =
             "manifest".equals(call.getString("artifactType")) &&
@@ -99,11 +151,34 @@ public class GuardedLiveUpdate extends LiveUpdatePlugin {
             call.reject("LiveUpdate.downloadBundle was called too often in this run of the app");
             return;
         }
-        JSObject data = clear(call);
-        data.put("artifactType", "manifest");
-        data.put("bundleId", bundleId);
-        data.put("url", releasesUrl + "/" + bundleId);
-        super.downloadBundle(call);
+        clear(call);
+        downloader.execute(() -> download(call, bundleId));
+    }
+
+    private void download(PluginCall call, String bundleId) {
+        File bundles = BundlesFolder.of(getContext());
+        File downloads = new File(getContext().getFilesDir(), DOWNLOADS);
+        File dir = new File(downloads, UUID.randomUUID().toString());
+        try {
+            if (!dir.mkdirs() || !(bundles.isDirectory() || bundles.mkdirs())) throw new IOException("Cannot create " + dir);
+            String current = bundleIdOf(getBridge().getServerBasePath());
+            ReleaseStatement statement = new ReleaseDownload(releasesUrl, publicKey, binary).download(bundleId, dir, current == null ? null : new File(bundles, current), highestOrder());
+            File target = new File(bundles, bundleId);
+            // The same release downloaded before stays; setNextBundle checks it anyway.
+            if (!target.exists() && !dir.renameTo(target)) throw new IOException("Cannot move " + dir);
+            synchronized (order) {
+                if (ReleaseOrder.compare(statement.order, highestOrder()) > 0) {
+                    prefs().edit().putString(HIGHEST_ORDER, ReleaseOrder.format(statement.order)).commit();
+                }
+            }
+            call.resolve();
+        } catch (BundleRefused e) {
+            call.reject("LiveUpdate.downloadBundle refused release " + bundleId + ": " + e.getMessage());
+        } catch (IOException e) {
+            call.reject("LiveUpdate.downloadBundle could not download release " + bundleId);
+        } finally {
+            BundleRemoval.delete(downloads, dir);
+        }
     }
 
     @Override
@@ -120,8 +195,56 @@ public class GuardedLiveUpdate extends LiveUpdatePlugin {
             Refusal.rejectMethod(call, "LiveUpdate", "setNextBundle");
             return;
         }
-        clear(call).put("bundleId", bundleId);
-        super.setNextBundle(call);
+        String id = (String) bundleId;
+        File bundles = BundlesFolder.of(getContext());
+        synchronized (order) {
+            try {
+                ReleaseStatement next = BundleCheck.check(new File(bundles, id), id, publicKey, binary);
+                ReleaseOrder.acceptNext(next.order, currentOrder(bundles), highestOrder());
+            } catch (BundleRefused e) {
+                if (!id.equals(bundleIdOf(getBridge().getServerBasePath())) && !id.equals(bundleIdOf(nextPath()))) {
+                    BundleRemoval.delete(bundles, new File(bundles, id));
+                }
+                call.reject("LiveUpdate.setNextBundle refused bundle " + id + ": " + e.getMessage());
+                return;
+            }
+            clear(call).put("bundleId", id);
+            super.setNextBundle(call);
+        }
+    }
+
+    // The running bundle's order: the built-in one's, or what its statement says, checked against the key.
+    private long[] currentOrder(File bundles) throws BundleRefused {
+        String current = bundleIdOf(getBridge().getServerBasePath());
+        if (current == null) return ReleaseOrder.BUILT_IN;
+        try {
+            byte[] statement = Bounded.read(new File(new File(bundles, current), ReleaseStatement.FILE), ReleaseStatement.MAX_BYTES, "the running bundle's statement");
+            return ReleaseStatement.verify(statement, current, publicKey).order;
+        } catch (IOException e) {
+            throw new BundleRefused("the running bundle's statement could not be read");
+        }
+    }
+
+    private long[] highestOrder() {
+        return ReleaseOrder.parse(prefs().getString(HIGHEST_ORDER, null));
+    }
+
+    private SharedPreferences prefs() {
+        return getContext().getSharedPreferences(ORDER_PREFS, Activity.MODE_PRIVATE);
+    }
+
+    // Where the stock code keeps the next bundle, Capacitor's server path (LiveUpdate.java:1550, Bridge.java:295-302).
+    private String nextPath() {
+        return getContext().getSharedPreferences(com.getcapacitor.plugin.WebView.WEBVIEW_PREFS_NAME, Activity.MODE_PRIVATE).getString(com.getcapacitor.plugin.WebView.CAP_SERVER_PATH, null);
+    }
+
+    // The id of the downloaded bundle at `path`, as the stock code names it (LiveUpdate.java:1214-1262), or null for the
+    // built-in one and any path outside the bundles folder.
+    private String bundleIdOf(String path) {
+        if (path == null || path.isEmpty()) return null;
+        File bundles = BundlesFolder.of(getContext());
+        String name = new File(path).getName();
+        return BundlesFolder.isBundleId(bundles, name) && new File(bundles, name).getAbsolutePath().equals(new File(path).getAbsolutePath()) ? name : null;
     }
 
     // Allowed: no input

package/android/src/liveupdate/java/net/protobase/mobile/Hex.java

@@ -0,0 +1,42 @@
+package net.protobase.mobile;
+
+/** Lowercase hex, as the server writes hashes and the statement; anything else is refused. */
+final class Hex {
+
+    private static final char[] DIGITS = "0123456789abcdef".toCharArray();
+
+    private Hex() {}
+
+    static String encode(byte[] bytes) {
+        char[] text = new char[bytes.length * 2];
+        for (int i = 0; i < bytes.length; i++) {
+            text[i * 2] = DIGITS[(bytes[i] >> 4) & 0xf];
+            text[i * 2 + 1] = DIGITS[bytes[i] & 0xf];
+        }
+        return new String(text);
+    }
+
+    static byte[] decode(String text, String what) throws BundleRefused {
+        if (text.length() % 2 != 0) throw new BundleRefused(what + " is no hex");
+        byte[] bytes = new byte[text.length() / 2];
+        for (int i = 0; i < bytes.length; i++) {
+            int high = digit(text.charAt(i * 2));
+            int low = digit(text.charAt(i * 2 + 1));
+            if (high < 0 || low < 0) throw new BundleRefused(what + " is no hex");
+            bytes[i] = (byte) ((high << 4) | low);
+        }
+        return bytes;
+    }
+
+    static boolean isHex(String text, int length) {
+        if (text.length() != length) return false;
+        for (int i = 0; i < length; i++) if (digit(text.charAt(i)) < 0) return false;
+        return true;
+    }
+
+    private static int digit(char c) {
+        if (c >= '0' && c <= '9') return c - '0';
+        if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+        return -1;
+    }
+}

package/android/src/liveupdate/java/net/protobase/mobile/ReleaseBinary.java

@@ -0,0 +1,30 @@
+package net.protobase.mobile;
+
+/**
+ * This binary: its app id, its native fingerprint and the Protobase version of its shell, from the app's package and
+ * capacitor.config.json, beyond page script and a live update. It takes a release only for itself.
+ */
+final class ReleaseBinary {
+
+    final String appId;
+    final String fingerprint;
+    final String shellVersion;
+
+    ReleaseBinary(String appId, String fingerprint, String shellVersion) {
+        this.appId = appId;
+        this.fingerprint = fingerprint;
+        this.shellVersion = shellVersion;
+    }
+
+    /**
+     * Refuses a release for another app or fingerprint, or of a server whose API this shell does not work with: the same
+     * major, and below 1.0 the same minor, as the server's `shellUpdateRequired` says.
+     */
+    void accept(ReleaseStatement statement) throws BundleRefused {
+        if (!appId.equals(statement.appId)) throw new BundleRefused("it is a release of another app");
+        if (!fingerprint.equals(statement.fingerprint)) throw new BundleRefused("it is a release for another binary");
+        long[] own = ReleaseStatement.majorMinor(shellVersion);
+        long[] server = ReleaseStatement.majorMinor(statement.shellVersion);
+        if (own[0] != server[0] || (server[0] == 0 && own[1] != server[1])) throw new BundleRefused("it is a release for another shell version");
+    }
+}

package/android/src/liveupdate/java/net/protobase/mobile/ReleaseDownload.java

@@ -0,0 +1,128 @@
+package net.protobase.mobile;
+
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.io.UnsupportedEncodingException;
+import java.net.HttpURLConnection;
+import java.net.URI;
+import java.net.URLEncoder;
+import java.security.PublicKey;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Downloads release `bundleId` from `releasesUrl/<id>?href=<file>` into a folder, in place of the stock downloader,
+ * which joins a manifest's hrefs to its path unchecked and checks each file only against its own signature
+ * (LiveUpdate.java:817-872 of @capawesome/capacitor-live-update 8.7.1). First the statement, checked against the id,
+ * the key, this binary and the highest order the app downloaded; then the manifest, checked against the statement and
+ * every href against the folder before any file is fetched; then each file, hashed as it is written and refused unless
+ * it is the one the manifest names. A file the running bundle has with the same checksum is copied from it and hashed
+ * again, so it is bound by its content, never by its href.
+ */
+final class ReleaseDownload {
+
+    private static final int TIMEOUT_MS = 30_000;
+
+    private final String releasesUrl;
+    private final PublicKey key;
+    private final ReleaseBinary binary;
+
+    ReleaseDownload(String releasesUrl, PublicKey key, ReleaseBinary binary) {
+        this.releasesUrl = releasesUrl;
+        this.key = key;
+        this.binary = binary;
+    }
+
+    /**
+     * Fills the empty folder `dir` with release `bundleId`, `current` the running bundle's folder (null for the built-in
+     * one), and checks it as a whole. Returns its statement.
+     */
+    ReleaseStatement download(String bundleId, File dir, File current, long[] highest) throws BundleRefused, IOException {
+        byte[] statementBytes = fetch(bundleId, ReleaseStatement.FILE, ReleaseStatement.MAX_BYTES);
+        ReleaseStatement statement = ReleaseStatement.verify(statementBytes, bundleId, key);
+        binary.accept(statement);
+        if (ReleaseOrder.compare(statement.order, highest) < 0) throw new BundleRefused("it is older than a release the app downloaded");
+        byte[] manifestBytes = fetch(bundleId, ReleaseManifest.FILE, ReleaseManifest.MAX_BYTES);
+        ReleaseManifest manifest = ReleaseManifest.verify(manifestBytes, statement, dir);
+        Map<String, File> own = filesOf(current);
+        for (ReleaseManifest.Item item : manifest.items) {
+            File target = new File(dir, item.href);
+            File parent = target.getParentFile();
+            if (!parent.isDirectory() && !parent.mkdirs()) throw new IOException("Cannot create " + parent);
+            File copy = own.get(item.checksum);
+            if (copy != null && item.checksum.equals(write(new FileInputStream(copy), target, item.size))) continue;
+            if (!item.checksum.equals(write(open(bundleId, item.href), target, item.size))) {
+                throw new BundleRefused("its " + item.href + " is not the file its manifest names");
+            }
+        }
+        writeBytes(new File(dir, ReleaseStatement.FILE), statementBytes);
+        writeBytes(new File(dir, ReleaseManifest.FILE), manifestBytes);
+        return BundleCheck.check(dir, bundleId, key, binary);
+    }
+
+    // The running bundle's files by checksum, as its own manifest lists them; none when it has none that parses.
+    private static Map<String, File> filesOf(File current) throws IOException {
+        Map<String, File> files = new HashMap<>();
+        if (current == null) return files;
+        ReleaseManifest manifest;
+        try {
+            manifest = ReleaseManifest.parse(Bounded.read(new File(current, ReleaseManifest.FILE), ReleaseManifest.MAX_BYTES, "its manifest"), current);
+        } catch (BundleRefused e) {
+            return files;
+        }
+        for (ReleaseManifest.Item item : manifest.items) {
+            File file = new File(current, item.href);
+            if (file.isFile() && !BundleRemoval.isLink(file)) files.put(item.checksum, file);
+        }
+        return files;
+    }
+
+    // Writes at most `size` bytes of `in` to `target`; returns their sha256, or null when there were more or fewer.
+    private static String write(InputStream in, File target, long size) throws IOException {
+        try (InputStream source = in; OutputStream out = new FileOutputStream(target)) {
+            String checksum = Sha256.copy(source, out, size);
+            return target.length() == size ? checksum : null;
+        }
+    }
+
+    private static void writeBytes(File target, byte[] bytes) throws IOException {
+        try (OutputStream out = new FileOutputStream(target)) {
+            out.write(bytes);
+        }
+    }
+
+    private byte[] fetch(String bundleId, String href, int limit) throws BundleRefused, IOException {
+        try (InputStream in = open(bundleId, href)) {
+            return Bounded.read(in, limit, "its " + href);
+        }
+    }
+
+    // The file `href` of the release, answered 200 by the releases URL itself: a redirect is no answer.
+    private InputStream open(String bundleId, String href) throws BundleRefused, IOException {
+        HttpURLConnection connection = (HttpURLConnection) URI.create(releasesUrl + "/" + bundleId + "?href=" + query(href)).toURL().openConnection();
+        connection.setInstanceFollowRedirects(false);
+        connection.setUseCaches(false);
+        connection.setConnectTimeout(TIMEOUT_MS);
+        connection.setReadTimeout(TIMEOUT_MS);
+        int status = connection.getResponseCode();
+        if (status != HttpURLConnection.HTTP_OK) {
+            connection.disconnect();
+            throw new BundleRefused("the server answered " + status + " for " + href);
+        }
+        return connection.getInputStream();
+    }
+
+    // The href as a form value: a space as %20, which every server decodes alike, rather than `+`.
+    private static String query(String href) {
+        try {
+            return URLEncoder.encode(href, "UTF-8").replace("+", "%20");
+        } catch (UnsupportedEncodingException e) {
+            // Every runtime has UTF-8.
+            throw new IllegalStateException(e);
+        }
+    }
+}

package/android/src/liveupdate/java/net/protobase/mobile/ReleaseManifest.java

@@ -0,0 +1,98 @@
+package net.protobase.mobile;
+
+import java.io.File;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+/**
+ * A release's manifest (`releaseManifestFile` in @protobase/schema): every file by `href`, with its sha256 and size.
+ * Each href is checked as the very string the guard joins to a folder, before any file of it is read or written.
+ */
+final class ReleaseManifest {
+
+    static final String FILE = "capawesome-live-update-manifest.json";
+    static final int MAX_BYTES = 4 * 1024 * 1024;
+    static final int MAX_FILES = 10_000;
+    static final long MAX_FILE_BYTES = 64L * 1024 * 1024;
+    static final long MAX_TOTAL_BYTES = 256L * 1024 * 1024;
+    private static final int MAX_HREF = 1024;
+
+    static final class Item {
+
+        final String href;
+        final String checksum;
+        final long size;
+
+        Item(String href, String checksum, long size) {
+            this.href = href;
+            this.checksum = checksum;
+            this.size = size;
+        }
+    }
+
+    final List<Item> items;
+
+    private ReleaseManifest(List<Item> items) {
+        this.items = Collections.unmodifiableList(items);
+    }
+
+    /** The manifest `bytes` hold, when they are the ones `statement` names, its files to lie inside `dir`. */
+    static ReleaseManifest verify(byte[] bytes, ReleaseStatement statement, File dir) throws BundleRefused {
+        if (!Sha256.of(bytes).equals(statement.manifest)) throw new BundleRefused("its manifest is not the one its statement names");
+        return parse(bytes, dir);
+    }
+
+    /** The manifest `bytes` hold, each href naming a file inside `dir`. */
+    static ReleaseManifest parse(byte[] bytes, File dir) throws BundleRefused {
+        if (bytes.length > MAX_BYTES) throw new BundleRefused("its manifest is too large");
+        try {
+            JSONArray array = new JSONArray(new String(bytes, StandardCharsets.UTF_8));
+            if (array.length() > MAX_FILES) throw new BundleRefused("its manifest lists too many files");
+            List<Item> items = new ArrayList<>();
+            Set<String> hrefs = new HashSet<>();
+            long total = 0;
+            for (int i = 0; i < array.length(); i++) {
+                Item item = item(array.getJSONObject(i), dir);
+                if (!hrefs.add(item.href)) throw new BundleRefused("its manifest lists " + item.href + " twice");
+                total += item.size;
+                if (total > MAX_TOTAL_BYTES) throw new BundleRefused("its files are too large");
+                items.add(item);
+            }
+            return new ReleaseManifest(items);
+        } catch (JSONException e) {
+            throw new BundleRefused("its manifest is malformed");
+        }
+    }
+
+    private static Item item(JSONObject entry, File dir) throws JSONException, BundleRefused {
+        if (entry.length() != 3) throw new BundleRefused("its manifest has an entry that is not an href, checksum and size");
+        String href = entry.getString("href");
+        String checksum = entry.getString("checksum");
+        Object size = entry.get("sizeInBytes");
+        if (!isRelativePath(href) || href.equals(FILE) || href.equals(ReleaseStatement.FILE) || !BundlesFolder.contains(dir, new File(dir, href))) {
+            throw new BundleRefused("its manifest names a file outside its folder");
+        }
+        if (!Hex.isHex(checksum, 64)) throw new BundleRefused("its manifest names no checksum for " + href);
+        if (!(size instanceof Integer || size instanceof Long) || ((Number) size).longValue() < 0 || ((Number) size).longValue() > MAX_FILE_BYTES) {
+            throw new BundleRefused("its manifest names no size for " + href);
+        }
+        return new Item(href, checksum, ((Number) size).longValue());
+    }
+
+    // Path components joined by `/`: none empty, `.` or `..`, and no `\` or NUL, so neither an absolute path nor one
+    // that climbs, nor one another platform reads otherwise.
+    static boolean isRelativePath(String href) {
+        if (href.isEmpty() || href.length() > MAX_HREF || href.indexOf('\\') >= 0 || href.indexOf('\0') >= 0) return false;
+        for (String part : href.split("/", -1)) {
+            if (part.isEmpty() || part.equals(".") || part.equals("..")) return false;
+        }
+        return true;
+    }
+}

package/android/src/liveupdate/java/net/protobase/mobile/ReleaseOrder.java

@@ -0,0 +1,46 @@
+package net.protobase.mobile;
+
+/**
+ * Release orders, compared element by element, a missing element counting as 0, so a later server can add one without
+ * breaking binaries already shipped. Kept as text such as `1800000000000,0`.
+ */
+final class ReleaseOrder {
+
+    /** The built-in bundle's order. */
+    static final long[] BUILT_IN = { 0 };
+
+    private ReleaseOrder() {}
+
+    static int compare(long[] a, long[] b) {
+        for (int i = 0; i < Math.max(a.length, b.length); i++) {
+            long x = i < a.length ? a[i] : 0;
+            long y = i < b.length ? b[i] : 0;
+            if (x != y) return x < y ? -1 : 1;
+        }
+        return 0;
+    }
+
+    /**
+     * Refuses a bundle of order `next` as the next bundle unless it is above the running one's, `current`, and not below
+     * the highest order the app downloaded, `highest`.
+     */
+    static void acceptNext(long[] next, long[] current, long[] highest) throws BundleRefused {
+        if (compare(next, current) <= 0) throw new BundleRefused("it is not newer than the bundle the app runs");
+        if (compare(next, highest) < 0) throw new BundleRefused("it is older than a release the app downloaded");
+    }
+
+    static String format(long[] order) {
+        StringBuilder text = new StringBuilder();
+        for (int i = 0; i < order.length; i++) text.append(i == 0 ? "" : ",").append(order[i]);
+        return text.toString();
+    }
+
+    /** The order `text` holds, or the built-in bundle's for none. Only this class writes it. */
+    static long[] parse(String text) {
+        if (text == null || text.isEmpty()) return BUILT_IN;
+        String[] parts = text.split(",");
+        long[] order = new long[parts.length];
+        for (int i = 0; i < parts.length; i++) order[i] = Long.parseLong(parts[i]);
+        return order;
+    }
+}

package/android/src/liveupdate/java/net/protobase/mobile/ReleaseStatement.java

@@ -0,0 +1,124 @@
+package net.protobase.mobile;
+
+import java.nio.charset.StandardCharsets;
+import java.security.InvalidKeyException;
+import java.security.NoSuchAlgorithmException;
+import java.security.PublicKey;
+import java.security.Signature;
+import java.security.SignatureException;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.Set;
+import java.util.regex.Pattern;
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+/**
+ * A release's statement (`releaseStatementFile` in @protobase/schema): what binds its manifest to its order, the app,
+ * the binary and the shell, signed with the app's key. Only bytes the signature covers are parsed for what they say.
+ */
+final class ReleaseStatement {
+
+    static final String FILE = "protobase-release.json";
+    static final int MAX_BYTES = 64 * 1024;
+    private static final byte[] CONTEXT = "protobase-mobile-release\n".getBytes(StandardCharsets.UTF_8);
+    private static final Set<String> KEYS = new HashSet<>(Arrays.asList("manifest", "order", "appId", "fingerprint", "shellVersion"));
+    private static final Pattern VERSION = Pattern.compile("(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)");
+    private static final int MAX_ORDER = 8;
+
+    final String manifest;
+    final long[] order;
+    final String appId;
+    final String fingerprint;
+    final String shellVersion;
+
+    private ReleaseStatement(String manifest, long[] order, String appId, String fingerprint, String shellVersion) {
+        this.manifest = manifest;
+        this.order = order;
+        this.appId = appId;
+        this.fingerprint = fingerprint;
+        this.shellVersion = shellVersion;
+    }
+
+    /**
+     * The statement `file` holds, when it is the one bundle `bundleId` names, the first 16 hex of the sha256 of its bytes
+     * and of `key`'s SPKI DER, as `composeRelease` derives it, and `key` signed what it says.
+     */
+    static ReleaseStatement verify(byte[] file, String bundleId, PublicKey key) throws BundleRefused {
+        if (file.length > MAX_BYTES) throw new BundleRefused("its statement is too large");
+        if (!Sha256.of(file, key.getEncoded()).substring(0, 16).equals(bundleId)) {
+            throw new BundleRefused("its id does not name its statement and the app's key");
+        }
+        byte[] payload;
+        byte[] signature;
+        try {
+            JSONObject outer = new JSONObject(new String(file, StandardCharsets.UTF_8));
+            payload = Hex.decode(outer.getString("payload"), "its statement's payload");
+            signature = Hex.decode(outer.getString("signature"), "its statement's signature");
+        } catch (JSONException e) {
+            throw new BundleRefused("its statement is malformed");
+        }
+        if (!signed(payload, signature, key)) throw new BundleRefused("its statement is not signed with the app's key");
+        try {
+            return parse(new JSONObject(new String(payload, StandardCharsets.UTF_8)));
+        } catch (JSONException e) {
+            throw new BundleRefused("its statement says nothing it can read");
+        }
+    }
+
+    private static boolean signed(byte[] payload, byte[] signature, PublicKey key) {
+        try {
+            Signature verifier = Signature.getInstance("SHA256withRSA");
+            verifier.initVerify(key);
+            verifier.update(CONTEXT);
+            verifier.update(payload);
+            return verifier.verify(signature);
+        } catch (SignatureException e) {
+            // A signature of the wrong length or shape.
+            return false;
+        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
+            // Every runtime has SHA256withRSA, and load() takes only an RSA key.
+            throw new IllegalStateException(e);
+        }
+    }
+
+    private static ReleaseStatement parse(JSONObject payload) throws JSONException, BundleRefused {
+        Set<String> keys = new HashSet<>();
+        for (Iterator<String> it = payload.keys(); it.hasNext(); ) keys.add(it.next());
+        if (!keys.equals(KEYS)) throw new BundleRefused("its statement does not say exactly what binds it");
+        String manifest = payload.getString("manifest");
+        String appId = payload.getString("appId");
+        String fingerprint = payload.getString("fingerprint");
+        String shellVersion = payload.getString("shellVersion");
+        if (!Hex.isHex(manifest, 64)) throw new BundleRefused("its statement names no manifest hash");
+        if (appId.isEmpty()) throw new BundleRefused("its statement names no app");
+        if (!Hex.isHex(fingerprint, 16)) throw new BundleRefused("its statement names no fingerprint");
+        if (!VERSION.matcher(shellVersion).matches()) throw new BundleRefused("its statement names no shell version");
+        return new ReleaseStatement(manifest, order(payload.getJSONArray("order")), appId, fingerprint, shellVersion);
+    }
+
+    private static long[] order(JSONArray array) throws JSONException, BundleRefused {
+        if (array.length() == 0 || array.length() > MAX_ORDER) throw new BundleRefused("its statement names no order");
+        long[] order = new long[array.length()];
+        for (int i = 0; i < order.length; i++) {
+            Object part = array.get(i);
+            if (!(part instanceof Integer || part instanceof Long) || ((Number) part).longValue() < 0) {
+                throw new BundleRefused("its statement names no order");
+            }
+            order[i] = ((Number) part).longValue();
+        }
+        return order;
+    }
+
+    /** The major and minor of an x.y.z version this class accepted. */
+    static long[] majorMinor(String version) {
+        String[] parts = version.split("\\.");
+        return new long[] { Long.parseLong(parts[0]), Long.parseLong(parts[1]) };
+    }
+
+    static boolean isVersion(String version) {
+        return version != null && VERSION.matcher(version).matches();
+    }
+}

package/android/src/liveupdate/java/net/protobase/mobile/Sha256.java

@@ -0,0 +1,53 @@
+package net.protobase.mobile;
+
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+
+/** SHA-256 in lowercase hex, of bytes, of a file, and of a bounded copy from a stream into a file. */
+final class Sha256 {
+
+    private Sha256() {}
+
+    static MessageDigest digest() {
+        try {
+            return MessageDigest.getInstance("SHA-256");
+        } catch (NoSuchAlgorithmException e) {
+            // Every Java and Android runtime has SHA-256.
+            throw new IllegalStateException(e);
+        }
+    }
+
+    static String of(byte[]... parts) {
+        MessageDigest digest = digest();
+        for (byte[] part : parts) digest.update(part);
+        return Hex.encode(digest.digest());
+    }
+
+    static String of(File file) throws IOException {
+        try (InputStream in = new FileInputStream(file)) {
+            return copy(in, null, Long.MAX_VALUE);
+        }
+    }
+
+    /**
+     * Hashes what `in` holds while writing it to `out` (none: only hashes), refusing more than `limit` bytes. Returns
+     * the hash, or null when `in` held more.
+     */
+    static String copy(InputStream in, OutputStream out, long limit) throws IOException {
+        MessageDigest digest = digest();
+        byte[] buffer = new byte[64 * 1024];
+        long total = 0;
+        for (int read; (read = in.read(buffer)) != -1; ) {
+            total += read;
+            if (total > limit) return null;
+            digest.update(buffer, 0, read);
+            if (out != null) out.write(buffer, 0, read);
+        }
+        return Hex.encode(digest.digest());
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/mobile",
-  "version": "0.57.2",
+  "version": "0.57.3",
   "description": "The Capacitor that protobase mobile builds a Protobase app's iOS and Android projects with, at fixed versions, and the native plugins that keep page script away from the session and give the iOS app its bounce; installed by the CLI on first use.",
   "license": "Apache-2.0",
   "repository": {
@@ -22,7 +22,7 @@
     "android/build.gradle",
     "icon"
   ],
-  "nativeContract": 5,
+  "nativeContract": 6,
   "capacitor": {
     "ios": {
       "src": "ios"