@otakit/capacitor-updater 2.3.3 → 3.0.0

package/README.md

@@ -19,6 +19,36 @@ The plugin is intentionally small:
 
 There is no built-in splash or overlay manager in this model.
 
+## Reliability update compatibility
+
+These native reliability changes require rebuilding and distributing the iOS/Android
+app. An OTA web update cannot replace the native plugin.
+
+- **Android WebView:** applying an update requires support for
+  `WebViewFeature.DOCUMENT_START_SCRIPT`. Update Android System WebView on devices
+  without that capability. A confirmed installed app can still launch, and a new
+  update stays staged, but it cannot activate without the readiness guard. Include
+  older supported WebView versions in your native rollout tests.
+- **Readiness:** keep calling `OtaKit.notifyAppReady()` with no arguments after
+  startup succeeds. Native code binds the call to its WebView document. The default
+  `appReadyTimeout` remains 10 seconds and now counts cumulative foreground time;
+  backgrounding pauses the remaining budget. Process exit before readiness still
+  triggers rollback on the next launch.
+- **Encrypted bundles:** the downloaded encrypted object must fit within 128 MiB
+  and a smaller device-dependent memory budget. Oversized objects fail before
+  decryption with `insufficient_memory_for_encrypted_bundle`, preserving the
+  current installation. Previously attempted large encrypted bundles may now be
+  rejected; reduce their assets before rollout.
+- **Signing configuration:** explicit `manifestKeys` values must be arrays.
+  A string, object, number, boolean, or null fails closed. Omitted keys or an empty
+  array retain the hosted defaults or existing self-hosted unsigned mode.
+- **Self-hosted telemetry:** deploy nullable event-context columns, then the
+  updated ingest Worker and Tinybird endpoints, before releasing the native SDK.
+  Old ingest Workers discard context and reject the new `check_error` action.
+
+Use a native canary rollout to check startup, rollback, background/resume behavior,
+and encrypted downloads on physical low-memory devices before widening adoption.
+
 ## Hosted config
 
 ```ts
@@ -247,8 +277,8 @@ OtaKit.addListener('rollback', (failure) => {}); // applied bundle reverted (not
 OtaKit.removeAllListeners();
 ```
 
-Events fire only while the app process is alive — there is no buffering or
-replay. Reconcile on startup:
+JavaScript listener events fire only while the app process is alive and have no
+buffering or replay. Reconcile on startup:
 
 - a bundle staged in a previous session: `getState().staged`
 - a startup rollback (app restarted before `notifyAppReady()`): it happens
@@ -262,6 +292,11 @@ early in app startup, not in the restart click handler.
 Download and stage are atomic in this plugin — there is a single
 `updateStaged` event, not separate "downloaded" and "staged" events.
 
+Server telemetry uses a separate durable retry queue with stable event IDs. It is
+limited to 256 events, seven days, and 8 KiB per event; storage failures and process
+termination between a state commit and event creation can still lose telemetry.
+Suspended/terminated apps resume delivery when their process runs again.
+
 The headline pattern — background download via `shadow` policies, prompt to
 restart:
 
@@ -399,9 +434,15 @@ Operational rules:
   receive updates until a store build ships a new key.
 - Decryption failures are never fatal: they behave like download failures —
   the running bundle is untouched and nothing unverified is ever applied.
-- **Memory:** decryption buffers the bundle in memory (roughly 2–3× the
-  bundle size at peak). Keep encrypted bundles comfortably under ~100 MB,
-  especially for low-end Android devices.
+- **Memory:** authenticated decryption still uses whole-object buffers. Admission
+  is limited to the smaller of 128 MiB and one quarter of currently available
+  process memory after reserving 32 MiB. This is a conservative estimate, not a
+  reservation or an OOM guarantee. Test representative physical devices and keep
+  encrypted assets small.
+- **iOS Simulator:** admission uses host physical RAM as an estimate because the
+  process-memory API can report zero in simulator apps. The same reserve, factor,
+  and 128 MiB ceiling apply. Simulator decryption does not validate physical-device
+  memory pressure or establish that the host has that much memory free.
 
 ## Source areas
 

package/android/build.gradle

@@ -33,6 +33,20 @@ android {
     lintOptions {
         abortOnError false
     }
+    testOptions {
+        unitTests.includeAndroidResources = true
+        unitTests.all {
+            jvmArgs '--add-opens=java.base/java.lang=ALL-UNNAMED',
+                '--add-opens=java.base/java.util=ALL-UNNAMED',
+                '--add-opens=java.base/java.io=ALL-UNNAMED',
+                '--add-opens=java.base/java.net=ALL-UNNAMED',
+                '--add-opens=java.base/java.security=ALL-UNNAMED',
+                '--add-opens=java.base/java.text=ALL-UNNAMED',
+                '--add-opens=java.base/jdk.internal.access=ALL-UNNAMED',
+                '--add-opens=java.desktop/java.awt.font=ALL-UNNAMED',
+                '--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED'
+        }
+    }
 }
 
 repositories {
@@ -43,7 +57,9 @@ repositories {
 dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
+    implementation "androidx.webkit:webkit:${rootProject.ext.has('androidxWebkitVersion') ? rootProject.ext.androidxWebkitVersion : '1.12.1'}"
     testImplementation "junit:junit:$junitVersion"
+    testImplementation 'org.robolectric:robolectric:4.17'
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
 }

package/android/src/main/java/com/otakit/updater/BundleCrypto.java

@@ -1,10 +1,9 @@
 package com.otakit.updater;
 
-import java.io.ByteArrayOutputStream;
+import java.io.DataInputStream;
 import java.io.File;
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
-import java.io.InputStream;
 import javax.crypto.Cipher;
 import javax.crypto.spec.GCMParameterSpec;
 import javax.crypto.spec.SecretKeySpec;
@@ -21,6 +20,8 @@ final class BundleCrypto {
   private static final int GCM_TAG_BITS = 128;
   private static final int KEY_LENGTH = 32;
   private static final int TAG_LENGTH = 16;
+  private static final long RESERVE_BYTES = 32L * 1024 * 1024;
+  private static final long MAX_ENCRYPTED_BYTES = 128L * 1024 * 1024;
 
   private BundleCrypto() {}
 
@@ -45,6 +46,34 @@ final class BundleCrypto {
   }
 
   static void decryptFile(byte[] dek, byte[] nonce, File input, File output) throws Exception {
+    Runtime runtime = Runtime.getRuntime();
+    long available = runtime.maxMemory() - (runtime.totalMemory() - runtime.freeMemory());
+    decryptFile(dek, nonce, input, output, available);
+  }
+
+  static void requireMemoryBudget(long encryptedBytes, long availableBytes) {
+    long budget =
+      availableBytes <= RESERVE_BYTES
+        ? 0
+        : Math.min(MAX_ENCRYPTED_BYTES, (availableBytes - RESERVE_BYTES) / 4);
+    if (encryptedBytes > budget) throw new IllegalStateException(
+      "insufficient_memory_for_encrypted_bundle; encryptedBytes=" +
+        encryptedBytes +
+        "; budgetBytes=" +
+        budget
+    );
+  }
+
+  static void decryptFile(byte[] dek, byte[] nonce, File input, File output, long availableBytes)
+    throws Exception {
+    long size = input.length();
+    if (size <= TAG_LENGTH) throw new IllegalStateException(
+      "invalid bundle encryption parameter: ciphertext too short"
+    );
+    requireMemoryBudget(size, availableBytes);
+    if (dek == null || dek.length != KEY_LENGTH || nonce == null || nonce.length != 12) {
+      throw new IllegalStateException("invalid bundle encryption parameter: key or nonce length");
+    }
     Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
     cipher.init(
       Cipher.DECRYPT_MODE,
@@ -55,27 +84,19 @@ final class BundleCrypto {
     // Explicit doFinal (not CipherOutputStream) so a GCM tag failure always
     // throws instead of depending on close() behavior. GCM decryption
     // buffers the full input internally anyway before releasing plaintext.
-    byte[] ciphertext = readAllBytes(input);
-    if (ciphertext.length <= TAG_LENGTH) {
-      throw new IllegalStateException("invalid bundle encryption parameter: ciphertext too short");
-    }
+    byte[] ciphertext = readExactBytes(input, (int) size);
     byte[] plaintext = cipher.doFinal(ciphertext);
     try (FileOutputStream out = new FileOutputStream(output)) {
       out.write(plaintext);
     }
   }
 
-  private static byte[] readAllBytes(File file) throws Exception {
-    try (
-      InputStream in = new FileInputStream(file);
-      ByteArrayOutputStream out = new ByteArrayOutputStream()
-    ) {
-      byte[] buffer = new byte[8192];
-      int read;
-      while ((read = in.read(buffer)) > 0) {
-        out.write(buffer, 0, read);
-      }
-      return out.toByteArray();
+  private static byte[] readExactBytes(File file, int size) throws Exception {
+    byte[] bytes = new byte[size];
+    try (DataInputStream input = new DataInputStream(new FileInputStream(file))) {
+      input.readFully(bytes);
+      if (input.read() != -1) throw new java.io.IOException("Encrypted bundle changed during read");
     }
+    return bytes;
   }
 }

package/android/src/main/java/com/otakit/updater/BundleInfo.java

@@ -42,6 +42,16 @@ class BundleInfo {
     return "builtin".equals(id);
   }
 
+  String attemptId() {
+    if (
+      id == null ||
+      !id.matches(
+        "bundle-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"
+      )
+    ) return null;
+    return id;
+  }
+
   JSObject toJSObject() {
     JSObject object = new JSObject();
     object.put("id", id);

package/android/src/main/java/com/otakit/updater/BundleStore.java

@@ -2,9 +2,9 @@ package com.otakit.updater;
 
 import android.content.Context;
 import android.content.SharedPreferences;
+import android.util.AtomicFile;
 import com.getcapacitor.JSArray;
 import java.io.File;
-import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
@@ -16,6 +16,11 @@ import org.json.JSONObject;
 
 final class BundleStore {
 
+  /** Release identity is metadata; an installation must never reuse a live directory. */
+  static String newInstallationId() {
+    return "bundle-" + java.util.UUID.randomUUID();
+  }
+
   private static final String PREFS_NAME = "otakit_updater_state";
   private static final String KEY_CURRENT = "current_bundle_id";
   private static final String KEY_FALLBACK = "fallback_bundle_id";
@@ -105,9 +110,7 @@ final class BundleStore {
     }
 
     byte[] bytes = bundle.toJSONObject().toString().getBytes(StandardCharsets.UTF_8);
-    try (FileOutputStream output = new FileOutputStream(metadataFile(bundle.id), false)) {
-      output.write(bytes);
-    }
+    writeAtomically(metadataFile(bundle.id), bytes);
   }
 
   synchronized BundleInfo getBundle(String id) {
@@ -116,12 +119,8 @@ final class BundleStore {
     }
 
     File metadata = metadataFile(id);
-    if (!metadata.exists()) {
-      return null;
-    }
-
-    try (FileInputStream input = new FileInputStream(metadata)) {
-      byte[] bytes = readAllBytes(input);
+    try {
+      byte[] bytes = new AtomicFile(metadata).readFully();
       JSONObject json = new JSONObject(new String(bytes, StandardCharsets.UTF_8));
       return BundleInfo.fromJSONObject(json);
     } catch (Exception ignored) {
@@ -129,104 +128,156 @@ final class BundleStore {
     }
   }
 
-  private static byte[] readAllBytes(FileInputStream input) throws Exception {
-    java.io.ByteArrayOutputStream buffer = new java.io.ByteArrayOutputStream();
-    byte[] chunk = new byte[8192];
-    int read;
-    while ((read = input.read(chunk)) != -1) {
-      buffer.write(chunk, 0, read);
+  synchronized boolean bundleExists(String id) {
+    return getBundle(id) != null;
+  }
+
+  private File stateFile() {
+    return new File(context.getFilesDir(), "otakit-state.json");
+  }
+
+  private static void writeAtomically(File file, byte[] bytes) throws Exception {
+    AtomicFile atomic = new AtomicFile(file);
+    FileOutputStream output = null;
+    try {
+      output = atomic.startWrite();
+      output.write(bytes);
+      output.getFD().sync();
+      atomic.finishWrite(output);
+      output = null;
+      if (!Arrays.equals(atomic.readFully(), bytes)) {
+        throw new java.io.IOException("Atomic updater state write did not complete");
+      }
+    } catch (Exception error) {
+      if (output != null) atomic.failWrite(output);
+      throw error;
     }
-    return buffer.toByteArray();
   }
 
-  synchronized boolean bundleExists(String id) {
-    return getBundle(id) != null;
+  private JSONObject readCoreState() throws Exception {
+    File file = stateFile();
+    if (file.exists() || new File(file.getPath() + ".bak").exists()) {
+      JSONObject state = new JSONObject(
+        new String(new AtomicFile(file).readFully(), StandardCharsets.UTF_8)
+      );
+      if (state.getInt("version") != 1) throw new IllegalStateException(
+        "Unsupported updater state"
+      );
+      return state;
+    }
+    JSONObject state = new JSONObject();
+    state.put("version", 1);
+    state.put("currentId", prefs.getString(KEY_CURRENT, null));
+    state.put("fallbackId", prefs.getString(KEY_FALLBACK, null));
+    state.put("stagedId", prefs.getString(KEY_STAGED, null));
+    String failed = prefs.getString(KEY_LAST_FAILED_BUNDLE_INFO, null);
+    if (failed != null) {
+      try {
+        state.put("lastFailed", new JSONObject(failed));
+      } catch (JSONException ignored) {}
+    }
+    return state;
+  }
+
+  private JSONObject readCoreStateOrEmpty() {
+    try {
+      return readCoreState();
+    } catch (Exception error) {
+      return new JSONObject();
+    }
+  }
+
+  private void writeCoreState(JSONObject state) throws Exception {
+    writeAtomically(stateFile(), state.toString().getBytes(StandardCharsets.UTF_8));
+  }
+
+  private void setCoreValue(String key, Object value) {
+    try {
+      JSONObject state = readCoreState();
+      state.put(key, value);
+      writeCoreState(state);
+    } catch (Exception error) {
+      throw new IllegalStateException("Could not persist updater state", error);
+    }
+  }
+
+  synchronized void setCoreState(
+    String currentId,
+    String fallbackId,
+    String stagedId,
+    BundleInfo lastFailed
+  ) {
+    try {
+      readCoreState();
+      JSONObject state = new JSONObject();
+      state.put("version", 1);
+      state.put("currentId", currentId);
+      state.put("fallbackId", fallbackId);
+      state.put("stagedId", stagedId);
+      if (lastFailed != null) state.put("lastFailed", lastFailed.toJSONObject());
+      writeCoreState(state);
+    } catch (Exception error) {
+      throw new IllegalStateException("Could not persist updater state", error);
+    }
   }
 
   synchronized BundleInfo getCurrentBundle() {
-    String currentId = prefs.getString(KEY_CURRENT, null);
-    if (currentId == null) {
-      return builtinBundle();
+    String id = getCurrentBundleId();
+    BundleInfo bundle = id == null ? null : getBundle(id);
+    return bundle != null ? bundle : builtinBundle();
+  }
+
+  synchronized java.util.Set<String> protectedBundleIds() throws Exception {
+    JSONObject state = readCoreState();
+    java.util.Set<String> ids = new java.util.HashSet<>();
+    for (String key : new String[] { "currentId", "fallbackId", "stagedId" }) {
+      String id = state.optString(key, null);
+      if (id != null) ids.add(id);
     }
-    BundleInfo current = getBundle(currentId);
-    return current != null ? current : builtinBundle();
+    return ids;
   }
 
   synchronized String getCurrentBundleId() {
-    return prefs.getString(KEY_CURRENT, null);
+    return readCoreStateOrEmpty().optString("currentId", null);
   }
 
   synchronized void setCurrentBundleId(String id) {
-    SharedPreferences.Editor editor = prefs.edit();
-    if (id == null) {
-      editor.remove(KEY_CURRENT);
-    } else {
-      editor.putString(KEY_CURRENT, id);
-    }
-    editor.commit();
+    setCoreValue("currentId", id);
   }
 
   synchronized BundleInfo getFallbackBundle() {
-    String fallbackId = prefs.getString(KEY_FALLBACK, null);
-    if (fallbackId == null) {
-      return builtinBundle();
-    }
-    BundleInfo fallback = getBundle(fallbackId);
-    return fallback != null ? fallback : builtinBundle();
+    String id = getFallbackBundleId();
+    BundleInfo bundle = id == null ? null : getBundle(id);
+    return bundle != null ? bundle : builtinBundle();
   }
 
   synchronized String getFallbackBundleId() {
-    return prefs.getString(KEY_FALLBACK, null);
+    return readCoreStateOrEmpty().optString("fallbackId", null);
   }
 
   synchronized void setFallbackBundleId(String id) {
-    SharedPreferences.Editor editor = prefs.edit();
-    if (id == null) {
-      editor.remove(KEY_FALLBACK);
-    } else {
-      editor.putString(KEY_FALLBACK, id);
-    }
-    editor.commit();
+    setCoreValue("fallbackId", id);
   }
 
   synchronized String getStagedBundleId() {
-    return prefs.getString(KEY_STAGED, null);
+    return readCoreStateOrEmpty().optString("stagedId", null);
   }
 
   synchronized void setStagedBundleId(String id) {
-    SharedPreferences.Editor editor = prefs.edit();
-    if (id == null) {
-      editor.remove(KEY_STAGED);
-    } else {
-      editor.putString(KEY_STAGED, id);
-    }
-    editor.commit();
+    setCoreValue("stagedId", id);
   }
 
   synchronized void setLastFailedBundle(BundleInfo bundle) {
-    SharedPreferences.Editor editor = prefs.edit();
-    if (bundle == null) {
-      editor.remove(KEY_LAST_FAILED_BUNDLE_INFO);
-    } else {
-      try {
-        editor.putString(KEY_LAST_FAILED_BUNDLE_INFO, bundle.toJSONObject().toString());
-      } catch (JSONException ignored) {
-        editor.remove(KEY_LAST_FAILED_BUNDLE_INFO);
-      }
+    try {
+      setCoreValue("lastFailed", bundle == null ? null : bundle.toJSONObject());
+    } catch (JSONException error) {
+      throw new IllegalStateException(error);
     }
-    editor.apply();
   }
 
   synchronized BundleInfo getLastFailedBundle() {
-    String json = prefs.getString(KEY_LAST_FAILED_BUNDLE_INFO, null);
-    if (json == null) {
-      return null;
-    }
-    try {
-      return BundleInfo.fromJSONObject(new JSONObject(json));
-    } catch (Exception e) {
-      return null;
-    }
+    JSONObject failed = readCoreStateOrEmpty().optJSONObject("lastFailed");
+    return failed == null ? null : BundleInfo.fromJSONObject(failed);
   }
 
   synchronized String getOverrideChannel() {
@@ -265,7 +316,9 @@ final class BundleStore {
     }
     try {
       saveBundle(existing.withStatus(status));
-    } catch (Exception ignored) {}
+    } catch (Exception error) {
+      throw new IllegalStateException("Could not persist bundle status", error);
+    }
   }
 
   synchronized void deleteBundle(String id) throws Exception {
@@ -273,18 +326,13 @@ final class BundleStore {
       return;
     }
 
-    File directory = bundleDirectory(id);
-    deleteRecursively(directory);
-
-    if (id.equals(getStagedBundleId())) {
-      setStagedBundleId(null);
-    }
-    if (id.equals(prefs.getString(KEY_CURRENT, null))) {
-      setCurrentBundleId(null);
-    }
-    if (id.equals(prefs.getString(KEY_FALLBACK, null))) {
-      setFallbackBundleId(null);
-    }
+    setCoreState(
+      id.equals(getCurrentBundleId()) ? null : getCurrentBundleId(),
+      id.equals(getFallbackBundleId()) ? null : getFallbackBundleId(),
+      id.equals(getStagedBundleId()) ? null : getStagedBundleId(),
+      getLastFailedBundle()
+    );
+    deleteRecursively(bundleDirectory(id));
   }
 
   synchronized List<BundleInfo> listDownloadedBundleInfos() {

package/android/src/main/java/com/otakit/updater/CheckFailure.java

@@ -0,0 +1,53 @@
+package com.otakit.updater;
+
+import java.util.concurrent.Callable;
+import java.util.concurrent.CancellationException;
+
+/** Bounded diagnostics: never include manifest bodies, URLs, signatures, or key IDs. */
+final class CheckFailure {
+
+  final String phase;
+  final String detail;
+
+  private CheckFailure(String phase, String detail) {
+    this.phase = phase;
+    this.detail = detail;
+  }
+
+  static CheckFailure from(Exception error) {
+    if (
+      error instanceof CancellationException || Thread.currentThread().isInterrupted()
+    ) return null;
+    if (error instanceof ManifestVerifier.VerificationException) {
+      return new CheckFailure("signature", ((ManifestVerifier.VerificationException) error).reason);
+    }
+    if (error instanceof ManifestClient.HttpFailure) {
+      return new CheckFailure(
+        "check",
+        "manifest_http_" + ((ManifestClient.HttpFailure) error).status
+      );
+    }
+    if (error instanceof org.json.JSONException) return new CheckFailure(
+      "check",
+      "manifest_invalid"
+    );
+    if (error instanceof java.io.IOException) {
+      return new CheckFailure("check", "manifest_network_" + error.getClass().getSimpleName());
+    }
+    return new CheckFailure("check", "manifest_check_failed");
+  }
+
+  interface Reporter {
+    void report(CheckFailure failure) throws Exception;
+  }
+
+  static <T> T observe(Callable<T> operation, Reporter reporter) throws Exception {
+    try {
+      return operation.call();
+    } catch (Exception error) {
+      CheckFailure failure = from(error);
+      if (failure != null) reporter.report(failure);
+      throw error;
+    }
+  }
+}