@otakit/capacitor-updater 2.1.2 → 2.3.0

package/README.md

@@ -98,6 +98,25 @@ resumePolicy = 'off';
 runtimePolicy = 'off';
 ```
 
+## Force-immediate releases
+
+A release (or revert) can be marked **force immediate** in the dashboard or
+with `otakit release --force-immediate`. The flag is baked into the signed
+manifest; when a device's automatic flow sees it, `shadow` and `apply-staged`
+events escalate to the `immediate` behavior for that release: download, apply,
+and reload on that event.
+
+Bounds to keep in mind:
+
+- It is "immediate on the next event/check", not push — delivery is bounded by
+  lifecycle events and `checkInterval` (static CDN, no server→device channel).
+- `off` policies never fetch a manifest, so they never see the flag. `off`
+  stays the device-owned kill switch, and the manual APIs are unchanged.
+- Trial and rollback still apply: a forced bundle that never calls
+  `notifyAppReady()` rolls back like any other.
+- It reloads the app under the user, possibly mid-task. Use it for broken
+  releases, not routine rollouts.
+
 ## Check interval
 
 `checkInterval` defaults to 10 minutes and only applies to background resume
@@ -210,8 +229,42 @@ of splitting it into separate `download()` and `apply()` calls.
 - they do not resolve back into the old JS context
 - call `notifyAppReady()` from normal startup after the reloaded app boots
 
-There is no listener/event API in this refactor. If an app later needs a
-smaller reactive surface, that can be added intentionally.
+## Events
+
+The plugin emits lifecycle events alongside the pull APIs:
+
+```ts
+OtaKit.addListener('updateAvailable', (latest) => {}); // newer bundle found, before download
+OtaKit.addListener('updateStaged', ({ bundle }) => {}); // downloaded + verified + staged
+OtaKit.addListener('updateApplied', ({ bundle }) => {}); // new bundle confirmed healthy
+OtaKit.addListener('downloadFailed', (failure) => {}); // non-terminal download/verify error
+OtaKit.addListener('rollback', (failure) => {}); // applied bundle reverted (notify timeout)
+OtaKit.removeAllListeners();
+```
+
+Events fire only while the app process is alive — there is 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
+  before any JS runs, so it never reaches a listener — check
+  `getLastFailure()`
+
+`apply()` reloads the WebView and destroys the JS context, so `updateApplied`
+fires in the _reloaded_ bundle. Attach `updateApplied`/`rollback` listeners
+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.
+
+The headline pattern — background download via `shadow` policies, prompt to
+restart:
+
+```ts
+const state = await OtaKit.getState();
+if (state.staged) showRestartPrompt(state.staged);
+OtaKit.addListener('updateStaged', ({ bundle }) => showRestartPrompt(bundle));
+```
 
 ## Example manual flow
 
@@ -238,6 +291,42 @@ After the app reloads and starts again, call:
 await OtaKit.notifyAppReady();
 ```
 
+## Runtime channel switching
+
+`setChannel()` overrides the configured channel at runtime — for example a
+"Join beta" toggle in settings — without rebuilding the app:
+
+```ts
+// Opt into the beta channel; takes effect on the next check/download cycle.
+await OtaKit.setChannel({ channel: 'beta' });
+
+// Back to the channel from capacitor.config.ts (or the base channel).
+await OtaKit.setChannel({ channel: null });
+
+const { channel, source } = await OtaKit.getChannel();
+// source is 'override' after setChannel(), 'config' otherwise
+```
+
+The override is persisted across launches and slots into channel resolution
+as: explicit call argument → persisted override → config `channel` → base.
+`setChannel()` itself never checks, downloads, or reloads anything — call
+`OtaKit.download()` / `OtaKit.update()` afterwards if you want the switch to
+take effect immediately.
+
+Channel names must match `^[A-Za-z0-9._-]{1,64}$`, must not contain `..`, and
+must not be the reserved names `base` or `default` (matching server-side
+validation). Invalid names reject without persisting.
+
+Limitations to be aware of:
+
+- **Channels are public CDN paths.** A channel name is not a secret and this
+  cannot enforce private distribution — anyone who guesses the name can fetch
+  that channel's manifest.
+- **The backend is not aware of the switch.** There is no server-side record
+  of which device is on which channel; the switch is purely client-side.
+- **The channel must exist and have a release.** Switching to a channel with
+  no published manifest yields `no_update` until something is released there.
+
 ## Compatibility lanes
 
 - `channel` answers "who should get this rollout?"
@@ -257,8 +346,57 @@ The plugin does not just download arbitrary zips from a URL.
 2. it verifies the manifest signature when keys are configured
 3. it compares the manifest with current, staged, and last-failed local state
 4. it downloads only when a newer usable bundle exists
-5. it verifies the zip against the manifest `sha256`
-6. it stages and later applies the bundle
+5. it verifies the downloaded object against the manifest `sha256`
+6. if the bundle is encrypted, it decrypts it (AES-256-GCM; the tag authenticates the plaintext)
+7. it stages and later applies the bundle
+
+## Bundle encryption (optional)
+
+Bundles can be end-to-end encrypted so that object storage and the CDN only
+ever hold ciphertext. Generate a key with `otakit generate-encryption-key`,
+put it in CI as `OTAKIT_ENCRYPTION_KEY` (the CLI then encrypts uploads), and
+ship the same key in the app:
+
+```ts
+plugins: {
+  OtaKit: {
+    // Inject from an env var at build time — never commit the key.
+    bundleKeys: [{ kid: process.env.OTAKIT_ENCRYPTION_KID!, key: process.env.OTAKIT_ENCRYPTION_KEY! }],
+  },
+},
+```
+
+Per upload the CLI generates a random data key (DEK), encrypts the zip with
+AES-256-GCM, and wraps the DEK under your app key; the wrapped DEK and nonces
+travel in the signed manifest. The server never sees the key and cannot
+decrypt your bundles.
+
+**Threat model — confidentiality, not DRM.** The decryption key ships inside
+the app binary, so a determined attacker who reverse-engineers the app can
+extract it — true of every client-side encryption scheme. What it protects
+against: leaked or guessed CDN URLs, bucket misconfiguration, and casual
+inspection of stored objects. Update _forgery_ is independently blocked by
+the ES256 manifest signature — which is also why encryption should only be
+used with manifest signing enabled (hosted default): the encryption
+parameters are covered by the signature.
+
+Operational rules:
+
+- **Rollout order:** ship a store build containing `bundleKeys` **before**
+  releasing encrypted bundles. Installed apps without the key cannot decrypt
+  and will stay on their current version (they keep running; the failure is
+  recorded as `download_error` telemetry and, if you listen for it, the
+  `downloadFailed` event — it does not appear in `getLastFailure()`, which
+  reports rollbacks only).
+- **Rotation:** `bundleKeys` is an array — ship old + new keys together
+  during a transition, then drop the old key in a later store build.
+- **Key custody:** back the key up. Losing it means installed apps cannot
+  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.
 
 ## Source areas
 

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

@@ -0,0 +1,81 @@
+package com.otakit.updater;
+
+import java.io.ByteArrayOutputStream;
+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;
+
+/**
+ * AES-256-GCM bundle decryption.
+ *
+ * The CLI encrypts the zip with a random per-bundle DEK and wraps the DEK
+ * under the app KEK; both ciphertexts carry the 16-byte GCM tag appended
+ * (Java's AES/GCM/NoPadding expects exactly that layout).
+ */
+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 BundleCrypto() {}
+
+  static byte[] unwrapDek(byte[] kek, byte[] wrapNonce, byte[] wrappedDek) throws Exception {
+    if (kek == null || kek.length != KEY_LENGTH) {
+      throw new IllegalStateException("invalid bundle encryption parameter: bundle key length");
+    }
+    if (wrappedDek == null || wrappedDek.length != KEY_LENGTH + TAG_LENGTH) {
+      throw new IllegalStateException("invalid bundle encryption parameter: wrappedDek");
+    }
+    Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
+    cipher.init(
+      Cipher.DECRYPT_MODE,
+      new SecretKeySpec(kek, "AES"),
+      new GCMParameterSpec(GCM_TAG_BITS, wrapNonce)
+    );
+    byte[] dek = cipher.doFinal(wrappedDek);
+    if (dek.length != KEY_LENGTH) {
+      throw new IllegalStateException("bundle decryption failed: unexpected DEK length");
+    }
+    return dek;
+  }
+
+  static void decryptFile(byte[] dek, byte[] nonce, File input, File output) throws Exception {
+    Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
+    cipher.init(
+      Cipher.DECRYPT_MODE,
+      new SecretKeySpec(dek, "AES"),
+      new GCMParameterSpec(GCM_TAG_BITS, nonce)
+    );
+
+    // 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[] 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();
+    }
+  }
+}

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

@@ -22,10 +22,12 @@ final class BundleStore {
   private static final String KEY_STAGED = "staged_bundle_id";
   private static final String KEY_LAST_FAILED_BUNDLE_INFO = "last_failed_bundle_info";
   private static final String KEY_LAST_RESOLVED_RUNTIME_KEY = "last_resolved_runtime_key";
+  private static final String KEY_OVERRIDE_CHANNEL = "override_channel";
 
   private final Context context;
   private final SharedPreferences prefs;
   private final File bundlesDirectory;
+  private final File filesCacheDirectory;
   private final String builtinVersion;
   private final String nativeBuild;
   private final String appRuntimeVersion;
@@ -46,6 +48,16 @@ final class BundleStore {
       //noinspection ResultOfMethodCallIgnored
       bundlesDirectory.mkdirs();
     }
+    this.filesCacheDirectory = new File(this.context.getFilesDir(), "otakit_files");
+    if (!filesCacheDirectory.exists()) {
+      //noinspection ResultOfMethodCallIgnored
+      filesCacheDirectory.mkdirs();
+    }
+  }
+
+  /** Content-addressed file cache for the deltas strategy ({@code otakit_files/<sha256>}). */
+  File getFilesCacheDirectory() {
+    return filesCacheDirectory;
   }
 
   String getNativeBuild() {
@@ -217,6 +229,20 @@ final class BundleStore {
     }
   }
 
+  synchronized String getOverrideChannel() {
+    return prefs.getString(KEY_OVERRIDE_CHANNEL, null);
+  }
+
+  synchronized void setOverrideChannel(String channel) {
+    SharedPreferences.Editor editor = prefs.edit();
+    if (channel == null) {
+      editor.remove(KEY_OVERRIDE_CHANNEL);
+    } else {
+      editor.putString(KEY_OVERRIDE_CHANNEL, channel);
+    }
+    editor.commit();
+  }
+
   synchronized String getLastResolvedRuntimeKey() {
     return prefs.getString(KEY_LAST_RESOLVED_RUNTIME_KEY, null);
   }