@otakit/capacitor-updater 2.1.1 → 2.2.0

package/Package.swift

@@ -0,0 +1,27 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "OtakitCapacitorUpdater",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "OtakitCapacitorUpdater",
+            targets: ["UpdaterPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", "7.0.0"..<"9.0.0"),
+        .package(url: "https://github.com/weichsel/ZIPFoundation.git", .upToNextMajor(from: "0.9.0"))
+    ],
+    targets: [
+        .target(
+            name: "UpdaterPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm"),
+                .product(name: "ZIPFoundation", package: "ZIPFoundation")
+            ],
+            path: "ios/Sources/UpdaterPlugin",
+            exclude: ["UpdaterPlugin.m"])
+    ]
+)

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,6 +22,7 @@ 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;
@@ -217,6 +218,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);
   }

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

@@ -28,6 +28,23 @@ final class ManifestClient {
     }
   }
 
+  static final class ManifestEncryption {
+
+    final String alg;
+    final String kid;
+    final String wrapNonce;
+    final String wrappedDek;
+    final String nonce;
+
+    ManifestEncryption(String alg, String kid, String wrapNonce, String wrappedDek, String nonce) {
+      this.alg = alg;
+      this.kid = kid;
+      this.wrapNonce = wrapNonce;
+      this.wrappedDek = wrappedDek;
+      this.nonce = nonce;
+    }
+  }
+
   static final class LatestManifest {
 
     final String version;
@@ -36,6 +53,9 @@ final class ManifestClient {
     final int size;
     final String runtimeVersion;
     final String releaseId;
+    final String strategy;
+    final boolean forceImmediate;
+    final ManifestEncryption encryption;
 
     LatestManifest(
       String version,
@@ -43,7 +63,10 @@ final class ManifestClient {
       String sha256,
       int size,
       String runtimeVersion,
-      String releaseId
+      String releaseId,
+      String strategy,
+      boolean forceImmediate,
+      ManifestEncryption encryption
     ) {
       this.version = version;
       this.url = url;
@@ -51,6 +74,9 @@ final class ManifestClient {
       this.size = size;
       this.runtimeVersion = runtimeVersion;
       this.releaseId = releaseId;
+      this.strategy = strategy;
+      this.forceImmediate = forceImmediate;
+      this.encryption = encryption;
     }
   }
 
@@ -145,6 +171,18 @@ final class ManifestClient {
         throw new IllegalStateException("Manifest response missing required releaseId");
       }
 
+      String strategy = "zip";
+      if (json.has("strategy") && !json.isNull("strategy")) {
+        String rawStrategy = json.getString("strategy").trim();
+        if (!rawStrategy.isEmpty()) {
+          strategy = rawStrategy;
+        }
+      }
+      // Strict boolean (no string coercion) to match the iOS parser.
+      Object rawForceImmediate = json.opt("forceImmediate");
+      boolean forceImmediate = Boolean.TRUE.equals(rawForceImmediate);
+      ManifestEncryption encryption = parseEncryption(json);
+
       requireHTTPS(new URL(downloadUrl), allowInsecureUrls);
 
       if (manifestKeys == null || manifestKeys.isEmpty()) {
@@ -168,6 +206,9 @@ final class ManifestClient {
           sha256,
           size,
           responseRuntimeVersion,
+          strategy,
+          forceImmediate,
+          encryption,
           signature,
           manifestKeys
         );
@@ -179,13 +220,39 @@ final class ManifestClient {
         sha256,
         size,
         responseRuntimeVersion,
-        releaseId
+        releaseId,
+        strategy,
+        forceImmediate,
+        encryption
       );
     } finally {
       connection.disconnect();
     }
   }
 
+  private static ManifestEncryption parseEncryption(JSONObject json) throws Exception {
+    if (!json.has("encryption") || json.isNull("encryption")) {
+      return null;
+    }
+    JSONObject encObj = json.getJSONObject("encryption");
+    if (
+      !encObj.has("alg") ||
+      !encObj.has("kid") ||
+      !encObj.has("wrapNonce") ||
+      !encObj.has("wrappedDek") ||
+      !encObj.has("nonce")
+    ) {
+      throw new IllegalStateException("Manifest encryption block is missing required fields");
+    }
+    return new ManifestEncryption(
+      encObj.getString("alg"),
+      encObj.getString("kid"),
+      encObj.getString("wrapNonce"),
+      encObj.getString("wrappedDek"),
+      encObj.getString("nonce")
+    );
+  }
+
   private static String readStream(InputStream input) throws Exception {
     if (input == null) {
       return "";

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

@@ -34,6 +34,9 @@ final class ManifestVerifier {
     String sha256,
     int size,
     String runtimeVersion,
+    String strategy,
+    boolean forceImmediate,
+    ManifestClient.ManifestEncryption encryption,
     ManifestClient.ManifestSignature signature,
     List<KeyEntry> trustedKeys
   ) throws Exception {
@@ -44,6 +47,9 @@ final class ManifestVerifier {
       sha256,
       size,
       runtimeVersion,
+      strategy,
+      forceImmediate,
+      encryption,
       signature.kid,
       signature.iat,
       signature.exp
@@ -91,6 +97,31 @@ final class ManifestVerifier {
     }
   }
 
+  /**
+   * Encode the encryption block for the canonical payload.
+   * Must match the server's encodeEncryptionForPayload exactly.
+   */
+  private static String encodeEncryptionForPayload(ManifestClient.ManifestEncryption encryption) {
+    if (encryption == null) {
+      return "null";
+    }
+    return (
+      encryption.alg +
+      "|" +
+      encryption.kid +
+      "|" +
+      encryption.wrapNonce +
+      "|" +
+      encryption.wrappedDek +
+      "|" +
+      encryption.nonce
+    );
+  }
+
+  /**
+   * Canonical payload v2 — must match the server's buildCanonicalPayload
+   * (console/lib/manifest-signing.ts) and the iOS mirror byte-for-byte.
+   */
   private static String buildCanonicalPayload(
     String appId,
     String channel,
@@ -98,6 +129,9 @@ final class ManifestVerifier {
     String sha256,
     int size,
     String runtimeVersion,
+    String strategy,
+    boolean forceImmediate,
+    ManifestClient.ManifestEncryption encryption,
     String kid,
     int iat,
     int exp
@@ -122,6 +156,15 @@ final class ManifestVerifier {
       "runtimeVersion:" +
       (runtimeVersion != null ? runtimeVersion : "null") +
       "\n" +
+      "strategy:" +
+      strategy +
+      "\n" +
+      "forceImmediate:" +
+      (forceImmediate ? "true" : "false") +
+      "\n" +
+      "encryption:" +
+      encodeEncryptionForPayload(encryption) +
+      "\n" +
       "kid:" +
       kid +
       "\n" +