@otakit/capacitor-updater 1.2.0 → 2.0.0

package/README.md

@@ -4,7 +4,7 @@ Capacitor OTA updater plugin for OtaKit.
 
 ## What it does
 
-- checks the manifest endpoint for a newer bundle
+- fetches the latest manifest for its release lane from the CDN
 - downloads and verifies OTA bundles
 - stages updates safely
 - activates them on the next launch, next resume, or immediately
@@ -14,6 +14,11 @@ Capacitor OTA updater plugin for OtaKit.
 - requires `notifyAppReady()` as the success handshake
 - rolls back automatically if the new bundle does not prove healthy
 
+OtaKit publishes signed static manifests into object storage behind a CDN. The
+plugin fetches the manifest for its `appId + channel + runtimeVersion` lane,
+verifies it, compares it against the current and staged bundle locally, and
+only downloads when the manifest actually points at something newer.
+
 For normal app code, the main public methods are:
 
 ```ts
@@ -57,12 +62,13 @@ plugins: {
 
 Advanced overrides for self-hosting or custom trust only:
 
-- `serverUrl`
+- `cdnUrl` for manifest and bundle delivery
+- `serverUrl` for stats and control-plane requests
 - `manifestKeys`
 - `allowInsecureUrls`
 
-Hosted OtaKit already points at `https://otakit.app/api/v1` and already trusts
-the managed manifest signing keys.
+Hosted OtaKit already points at the managed control-plane API and CDN and already
+trusts the managed manifest signing keys.
 
 ## Channels vs runtimeVersion
 
@@ -84,11 +90,12 @@ When `runtimeVersion` is set:
 
 The plugin does not just download from a URL and trust the result.
 
-1. it fetches a manifest from the server
+1. it fetches the latest manifest from the CDN for its app + channel + runtimeVersion lane
 2. it verifies the manifest signature when manifest keys are configured
-3. it downloads the bundle zip
-4. it verifies the zip against the manifest `sha256`
-5. it stages and activates the bundle
+3. it compares that manifest against the current and staged bundle already on the device
+4. if the manifest is newer, it downloads the bundle zip
+5. it verifies the zip against the manifest `sha256`
+6. it stages and activates the bundle
 
 In the hosted path, managed signing keys are already built in.
 
@@ -165,8 +172,9 @@ await OtaKit.notifyAppReady();
 ```
 
 The plugin handles checking, downloading, activation, and rollback based on
-`updateMode`. It checks on cold start and every time the app comes back from
-the background (throttled by `checkInterval`).
+`updateMode`. In `next-launch` and `next-resume`, it checks on cold start and
+every time the app comes back from the background, throttled by `checkInterval`.
+`immediate` bypasses that throttle.
 
 For most apps, this is the entire runtime integration.
 
@@ -195,10 +203,9 @@ only after explicit user confirmation.
 
 ## Throttle
 
-All server checks are rate-limited by `checkInterval` (default 10 min).
-This applies to automatic resume checks and to manual `check()` / `download()`
-calls. Within the interval, calls return the staged bundle if one exists, or
-null.
+`checkInterval` (default 10 min) only applies to automatic checks in
+`next-launch` and `next-resume`. Manual `check()` / `download()` calls are
+always live, and `immediate` mode ignores the interval entirely.
 
 ## Retention and deletion
 

package/android/src/main/java/com/updatekit/updater/HostedManifestKeys.java

@@ -7,18 +7,17 @@ import java.util.Locale;
 
 final class HostedManifestKeys {
 
-  private static final String MANAGED_SERVER_URL = "https://www.otakit.app/api/v1";
+  private static final String MANAGED_CDN_URL = "https://cdn.otakit.app";
 
   private HostedManifestKeys() {}
 
-  static boolean matchesManagedServer(String updateUrl) {
-    if (updateUrl == null) {
+  static boolean matchesManagedManifestUrl(String cdnUrl) {
+    if (cdnUrl == null) {
       return false;
     }
 
-    String normalized = updateUrl.trim().replaceAll("/+$", "").toLowerCase(Locale.ROOT);
-    return normalized.equals(MANAGED_SERVER_URL)
-        || normalized.equals("https://otakit.app/api/v1");
+    String normalized = cdnUrl.trim().replaceAll("/+$", "").toLowerCase(Locale.ROOT);
+    return normalized.equals(MANAGED_CDN_URL) || normalized.equals("https://www.otakit.app");
   }
 
   static List<ManifestVerifier.KeyEntry> createDefaultKeys() {

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

@@ -9,6 +9,9 @@ import org.json.JSONObject;
 
 final class ManifestClient {
 
+  private static final String BASE_CHANNEL_KEY = "__base__";
+  private static final String DEFAULT_RUNTIME_KEY = "__default__";
+
   static final class ManifestSignature {
 
     final String kid;
@@ -63,41 +66,33 @@ final class ManifestClient {
   }
 
   static LatestManifest fetchLatest(
-    String updateUrl,
+    String cdnUrl,
     String appId,
     String channel,
-    String currentVersion,
-    String currentReleaseId,
     String runtimeVersion,
-    String platform,
     boolean allowInsecureUrls,
     java.util.List<ManifestVerifier.KeyEntry> manifestKeys
   ) throws Exception {
-    String base = updateUrl.replaceAll("/+$", "");
-    URL url = new URL(base + "/manifest");
+    String base = cdnUrl.replaceAll("/+$", "");
+    String channelKey = channel != null && !channel.trim().isEmpty() ? channel.trim() : BASE_CHANNEL_KEY;
+    String runtimeKey =
+      runtimeVersion != null && !runtimeVersion.trim().isEmpty()
+        ? runtimeVersion.trim()
+        : DEFAULT_RUNTIME_KEY;
+    URL url = new URL(
+      base + "/manifests/" + appId + "/" + channelKey + "/" + runtimeKey + "/manifest.json"
+    );
 
     requireHTTPS(url, allowInsecureUrls);
 
     HttpURLConnection connection = (HttpURLConnection) url.openConnection();
     try {
       connection.setRequestMethod("GET");
-      connection.setRequestProperty("X-App-Id", appId);
-      connection.setRequestProperty("X-Platform", platform);
-      if (channel != null && !channel.trim().isEmpty()) {
-        connection.setRequestProperty("X-Channel", channel);
-      }
-      connection.setRequestProperty("X-Current-Version", currentVersion);
-      if (currentReleaseId != null && !currentReleaseId.trim().isEmpty()) {
-        connection.setRequestProperty("X-Release-Id", currentReleaseId);
-      }
-      if (runtimeVersion != null && !runtimeVersion.trim().isEmpty()) {
-        connection.setRequestProperty("X-Runtime-Version", runtimeVersion);
-      }
       connection.setConnectTimeout(15_000);
       connection.setReadTimeout(30_000);
 
       int status = connection.getResponseCode();
-      if (status == 204) {
+      if (status == 404 || status == 204) {
         return null;
       }
       if (status != 200) {
@@ -125,14 +120,12 @@ final class ManifestClient {
       }
 
       ManifestSignature signature = parseSignature(json.optJSONObject("signature"));
-      ManifestSignature signatureV2 = parseSignature(json.optJSONObject("signatureV2"));
 
       String releaseId = null;
       if (json.has("releaseId") && !json.isNull("releaseId")) {
         releaseId = json.getString("releaseId");
       }
 
-      // Validate download URL scheme
       requireHTTPS(new URL(downloadUrl), allowInsecureUrls);
 
       if (manifestKeys == null || manifestKeys.isEmpty()) {
@@ -142,36 +135,23 @@ final class ManifestClient {
         );
       }
 
-      // Verify manifest signature if signing keys are configured
       if (manifestKeys != null && !manifestKeys.isEmpty()) {
-        if (signatureV2 != null) {
-          ManifestVerifier.verify(
-            appId,
-            channel,
-            platform,
-            version,
-            sha256,
-            size,
-            responseRuntimeVersion,
-            signatureV2,
-            manifestKeys
-          );
-        } else if (signature != null) {
-          ManifestVerifier.verifyLegacy(
-            appId,
-            channel,
-            platform,
-            version,
-            sha256,
-            size,
-            signature,
-            manifestKeys
-          );
-        } else {
+        if (signature == null) {
           throw new IllegalStateException(
             "Manifest signature missing but signing keys are configured"
           );
         }
+
+        ManifestVerifier.verify(
+          appId,
+          channel,
+          version,
+          sha256,
+          size,
+          responseRuntimeVersion,
+          signature,
+          manifestKeys
+        );
       }
 
       return new LatestManifest(

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

@@ -30,7 +30,6 @@ final class ManifestVerifier {
   static void verify(
     String appId,
     String channel,
-    String platform,
     String version,
     String sha256,
     int size,
@@ -41,7 +40,6 @@ final class ManifestVerifier {
     String payload = buildCanonicalPayload(
       appId,
       channel,
-      platform,
       version,
       sha256,
       size,
@@ -53,30 +51,6 @@ final class ManifestVerifier {
     verifyPayload(payload, signature, trustedKeys);
   }
 
-  static void verifyLegacy(
-    String appId,
-    String channel,
-    String platform,
-    String version,
-    String sha256,
-    int size,
-    ManifestClient.ManifestSignature signature,
-    List<KeyEntry> trustedKeys
-  ) throws Exception {
-    String payload = buildLegacyCanonicalPayload(
-      appId,
-      channel,
-      platform,
-      version,
-      sha256,
-      size,
-      signature.kid,
-      signature.iat,
-      signature.exp
-    );
-    verifyPayload(payload, signature, trustedKeys);
-  }
-
   private static void verifyPayload(
     String payload,
     ManifestClient.ManifestSignature signature,
@@ -120,7 +94,6 @@ final class ManifestVerifier {
   private static String buildCanonicalPayload(
     String appId,
     String channel,
-    String platform,
     String version,
     String sha256,
     int size,
@@ -130,16 +103,13 @@ final class ManifestVerifier {
     int exp
   ) {
     return (
-      "MANIFEST_V2\n" +
+      "MANIFEST\n" +
       "appId:" +
       appId +
       "\n" +
       "channel:" +
       (channel != null ? channel : "null") +
       "\n" +
-      "platform:" +
-      platform +
-      "\n" +
       "version:" +
       version +
       "\n" +
@@ -163,50 +133,6 @@ final class ManifestVerifier {
     );
   }
 
-  private static String buildLegacyCanonicalPayload(
-    String appId,
-    String channel,
-    String platform,
-    String version,
-    String sha256,
-    int size,
-    String kid,
-    int iat,
-    int exp
-  ) {
-    return (
-      "MANIFEST_V1\n" +
-      "appId:" +
-      appId +
-      "\n" +
-      "channel:" +
-      (channel != null ? channel : "null") +
-      "\n" +
-      "platform:" +
-      platform +
-      "\n" +
-      "version:" +
-      version +
-      "\n" +
-      "sha256:" +
-      sha256 +
-      "\n" +
-      "size:" +
-      size +
-      "\n" +
-      "minNativeBuild:null" +
-      "\n" +
-      "kid:" +
-      kid +
-      "\n" +
-      "iat:" +
-      iat +
-      "\n" +
-      "exp:" +
-      exp
-    );
-  }
-
   private static byte[] base64UrlDecode(String input) {
     // Convert base64url to standard base64
     String base64 = input.replace('-', '+').replace('_', '/');

package/android/src/main/java/com/updatekit/updater/UpdaterPlugin.java

@@ -37,6 +37,7 @@ public class UpdaterPlugin extends Plugin {
   private boolean allowInsecureUrls = false;
   private String updateMode = UPDATE_MODE_NEXT_LAUNCH;
   private String updateUrl;
+  private String cdnUrl;
   private String appId;
   private String channel;
   private String runtimeVersion;
@@ -44,6 +45,7 @@ public class UpdaterPlugin extends Plugin {
   private long checkIntervalMs = 600_000;
   private final AtomicBoolean checkInProgress = new AtomicBoolean(false);
   private static final String DEFAULT_UPDATE_URL = "https://www.otakit.app/api/v1";
+  private static final String DEFAULT_CDN_URL = "https://cdn.otakit.app";
   private static final String API_PATH_SUFFIX = "/api/v1";
   private static final String UPDATE_MODE_MANUAL = "manual";
   private static final String UPDATE_MODE_NEXT_LAUNCH = "next-launch";
@@ -76,6 +78,11 @@ public class UpdaterPlugin extends Plugin {
       getConfig().getString("serverUrl"),
       System.getenv("OTAKIT_SERVER_URL")
     );
+    this.cdnUrl = resolveCdnUrl(
+      getConfig().getString("cdnUrl"),
+      System.getenv("OTAKIT_CDN_URL"),
+      this.updateUrl
+    );
     this.appId = getConfig().getString("appId");
     this.channel = trimToNull(getConfig().getString("channel"));
     this.runtimeVersion = trimToNull(getConfig().getString("runtimeVersion"));
@@ -116,7 +123,7 @@ public class UpdaterPlugin extends Plugin {
       manifestKeys.add(new ManifestVerifier.KeyEntry("_invalid_", new byte[0]));
     }
 
-    if (manifestKeys.isEmpty() && HostedManifestKeys.matchesManagedServer(updateUrl)) {
+    if (manifestKeys.isEmpty() && HostedManifestKeys.matchesManagedManifestUrl(cdnUrl)) {
       manifestKeys.addAll(HostedManifestKeys.createDefaultKeys());
     }
 
@@ -174,7 +181,15 @@ public class UpdaterPlugin extends Plugin {
         }
       }
 
-      if (shouldThrottleCheck()) return;
+      if (!UPDATE_MODE_IMMEDIATE.equals(updateMode) && shouldThrottleCheck()) return;
+    }
+
+    if (
+      TRIGGER_LAUNCH.equals(trigger) &&
+      !UPDATE_MODE_IMMEDIATE.equals(updateMode) &&
+      shouldThrottleCheck()
+    ) {
+      return;
     }
 
     // Acquire in-flight guard (submit-time)
@@ -185,7 +200,6 @@ public class UpdaterPlugin extends Plugin {
       executor.execute(() -> {
         try {
           BundleInfo result = performCheckAndDownload(null, true);
-          recordCheckTimestamp();
           if (result != null) {
             activateStagedBundleForReload();
             reloadWebView();
@@ -282,8 +296,7 @@ public class UpdaterPlugin extends Plugin {
 
   @PluginMethod
   public void check(PluginCall call) {
-    // Respect throttle — return staged bundle as a LatestVersion if available, else null
-    if (shouldThrottleCheck() || !checkInProgress.compareAndSet(false, true)) {
+    if (!checkInProgress.compareAndSet(false, true)) {
       String stagedId = store.getStagedBundleId();
       if (stagedId != null) {
         BundleInfo staged = store.getBundle(stagedId);
@@ -311,10 +324,10 @@ public class UpdaterPlugin extends Plugin {
     executor.execute(() -> {
       try {
         ManifestClient.LatestManifest latest = fetchLatest(targetChannel);
-        // check() does NOT record timestamp — only download() and automatic paths do.
-        // This keeps check() -> download() working without the throttle blocking download().
         if (latest == null) {
           call.resolve((JSObject) null);
+        } else if (isCurrentBundleLatest(latest, targetChannel)) {
+          call.resolve((JSObject) null);
         } else {
           BundleInfo staged = findMatchingStagedBundle(latest, targetChannel);
           call.resolve(manifestToJSObject(latest, staged != null));
@@ -329,8 +342,7 @@ public class UpdaterPlugin extends Plugin {
 
   @PluginMethod
   public void download(PluginCall call) {
-    // Respect throttle — return staged info if available, else null
-    if (shouldThrottleCheck() || !checkInProgress.compareAndSet(false, true)) {
+    if (!checkInProgress.compareAndSet(false, true)) {
       String stagedId = store.getStagedBundleId();
       if (stagedId != null) {
         BundleInfo staged = store.getBundle(stagedId);
@@ -345,7 +357,6 @@ public class UpdaterPlugin extends Plugin {
     executor.execute(() -> {
       try {
         BundleInfo bundle = performCheckAndDownload(null, true);
-        recordCheckTimestamp();
         if (bundle == null) {
           call.resolve((JSObject) null);
         } else {
@@ -359,42 +370,6 @@ public class UpdaterPlugin extends Plugin {
     });
   }
 
-  @PluginMethod
-  public void debugCheck(PluginCall call) {
-    String requestedChannel = call.getString("channel");
-    String targetChannel = resolveTargetChannel(requestedChannel);
-    executor.execute(() -> {
-      try {
-        ManifestClient.LatestManifest latest = fetchLatest(targetChannel);
-        if (latest == null) {
-          call.resolve((JSObject) null);
-        } else {
-          BundleInfo staged = findMatchingStagedBundle(latest, targetChannel);
-          call.resolve(manifestToJSObject(latest, staged != null));
-        }
-      } catch (Exception e) {
-        call.reject("debugCheck failed: " + e.getMessage());
-      }
-    });
-  }
-
-  @PluginMethod
-  public void debugDownload(PluginCall call) {
-    String requestedChannel = call.getString("channel");
-    executor.execute(() -> {
-      try {
-        BundleInfo bundle = performCheckAndDownload(requestedChannel, true);
-        if (bundle == null) {
-          call.resolve((JSObject) null);
-        } else {
-          call.resolve(bundle.toJSObject());
-        }
-      } catch (Exception e) {
-        call.reject("debugDownload failed: " + e.getMessage());
-      }
-    });
-  }
-
   @PluginMethod
   public void apply(PluginCall call) {
     String stagedId = store.getStagedBundleId();
@@ -512,16 +487,11 @@ public class UpdaterPlugin extends Plugin {
       throw new IllegalStateException("Missing appId in plugin config");
     }
 
-    BundleInfo current = store.getCurrentBundle();
-
     return ManifestClient.fetchLatest(
-      updateUrl,
+      cdnUrl,
       appId,
       channel,
-      current.version,
-      current.releaseId,
       runtimeVersion,
-      "android",
       allowInsecureUrls,
       manifestKeys
     );
@@ -543,6 +513,13 @@ public class UpdaterPlugin extends Plugin {
       );
     }
 
+    if (isCurrentBundleLatest(latest, targetChannel)) {
+      if (emitEvents) {
+        notifyListeners("noUpdateAvailable", new JSObject());
+      }
+      return null;
+    }
+
     BundleInfo staged = findMatchingStagedBundle(latest, targetChannel);
     if (emitEvents) {
       notifyListeners("updateAvailable", manifestToJSObject(latest, staged != null));
@@ -912,6 +889,54 @@ public class UpdaterPlugin extends Plugin {
     return object;
   }
 
+  private boolean isCurrentBundleLatest(
+    ManifestClient.LatestManifest latest,
+    String targetChannel
+  ) {
+    return doesBundleMatchLatest(store.getCurrentBundle(), latest, targetChannel);
+  }
+
+  private boolean doesBundleMatchLatest(
+    BundleInfo bundle,
+    ManifestClient.LatestManifest latest,
+    String targetChannel
+  ) {
+    if (bundle == null) {
+      return false;
+    }
+
+    if (!java.util.Objects.equals(trimToNull(bundle.channel), targetChannel)) {
+      return false;
+    }
+
+    if (
+      !java.util.Objects.equals(
+        trimToNull(bundle.runtimeVersion),
+        trimToNull(latest.runtimeVersion)
+      )
+    ) {
+      return false;
+    }
+
+    if (
+      latest.releaseId != null &&
+      bundle.releaseId != null &&
+      latest.releaseId.equals(bundle.releaseId)
+    ) {
+      return true;
+    }
+
+    if (
+      latest.sha256 != null &&
+      bundle.sha256 != null &&
+      latest.sha256.equals(bundle.sha256)
+    ) {
+      return true;
+    }
+
+    return latest.version != null && latest.version.equals(bundle.version);
+  }
+
   private BundleInfo findMatchingStagedBundle(
     ManifestClient.LatestManifest latest,
     String targetChannel
@@ -935,24 +960,7 @@ public class UpdaterPlugin extends Plugin {
       return null;
     }
 
-    if (
-      latest.releaseId != null &&
-      staged.releaseId != null &&
-      latest.releaseId.equals(staged.releaseId)
-    ) {
-      return staged;
-    }
-
-    if (
-      latest.version != null &&
-      latest.version.equals(staged.version) &&
-      latest.sha256 != null &&
-      latest.sha256.equals(staged.sha256)
-    ) {
-      return staged;
-    }
-
-    return null;
+    return doesBundleMatchLatest(staged, latest, targetChannel) ? staged : null;
   }
 
   private void moveDirectory(File source, File destination) throws Exception {
@@ -1049,6 +1057,28 @@ public class UpdaterPlugin extends Plugin {
     return DEFAULT_UPDATE_URL;
   }
 
+  private String resolveCdnUrl(String configured, String env, String resolvedUpdateUrl) {
+    String configuredValue = trimToNull(configured);
+    if (configuredValue != null) {
+      return normalizeCdnUrl(configuredValue);
+    }
+
+    String envValue = trimToNull(env);
+    if (envValue != null) {
+      return normalizeCdnUrl(envValue);
+    }
+
+    if (
+      resolvedUpdateUrl != null &&
+      !DEFAULT_UPDATE_URL.equalsIgnoreCase(resolvedUpdateUrl) &&
+      resolvedUpdateUrl.toLowerCase(java.util.Locale.ROOT).endsWith(API_PATH_SUFFIX)
+    ) {
+      return resolvedUpdateUrl.substring(0, resolvedUpdateUrl.length() - API_PATH_SUFFIX.length());
+    }
+
+    return DEFAULT_CDN_URL;
+  }
+
   private String normalizeUpdateUrl(String raw) {
     String trimmed = raw.trim().replaceAll("/+$", "");
     if (trimmed.toLowerCase(java.util.Locale.ROOT).endsWith(API_PATH_SUFFIX)) {
@@ -1057,6 +1087,10 @@ public class UpdaterPlugin extends Plugin {
     return trimmed + API_PATH_SUFFIX;
   }
 
+  private String normalizeCdnUrl(String raw) {
+    return raw.trim().replaceAll("/+$", "");
+  }
+
   private String trimToNull(String value) {
     if (value == null) {
       return null;

package/dist/esm/definitions.d.ts

@@ -78,34 +78,22 @@ export interface OtaKitConfig {
     updateMode?: OtaKitUpdateMode;
     /**
      * Minimum milliseconds between automatic update checks.
-     * Applies to both resume-triggered and manual check()/download() calls.
-     * Debug APIs bypass this throttle. Defaults to 600000 (10 min).
+     * Applies only to automatic checks in `next-launch` and `next-resume`.
+     * Manual APIs and `immediate` mode bypass this throttle. Defaults to 600000 (10 min).
      */
     checkInterval?: number;
     /** Milliseconds to wait for notifyAppReady(). Defaults to 10000. */
     appReadyTimeout?: number;
-    /** Custom API base URL for self-hosted or custom servers. */
+    /** Custom API base URL for stats and other control-plane requests. */
     serverUrl?: string;
+    /** Custom CDN base URL for manifest and bundle delivery. */
+    cdnUrl?: string;
     /** Custom manifest verification keys for self-hosted or custom trust. */
     manifestKeys?: OtaKitManifestKey[];
     /** Allow HTTP only for localhost development. Defaults to false. */
     allowInsecureUrls?: boolean;
 }
 export interface OtaKitDebugApi {
-    /**
-     * Check the server for a newer version without downloading it.
-     * You can optionally pass { channel } for a one-off debug override.
-     */
-    check(options?: {
-        channel?: string;
-    }): Promise<LatestVersion | null>;
-    /**
-     * Check the server and download the latest bundle if available.
-     * Ensures the latest bundle is staged for later activation.
-     */
-    download(options?: {
-        channel?: string;
-    }): Promise<BundleInfo | null>;
     /**
      * Reset to the builtin bundle and reload the WebView.
      *
@@ -206,12 +194,6 @@ export interface OtaKitBridgePlugin {
     apply(): Promise<void>;
     notifyAppReady(): Promise<void>;
     debugGetState(): Promise<OtaKitDebugState>;
-    debugCheck(options?: {
-        channel?: string;
-    }): Promise<LatestVersion | null>;
-    debugDownload(options?: {
-        channel?: string;
-    }): Promise<BundleInfo | null>;
     debugReset(): Promise<void>;
     debugListBundles(): Promise<BundleListResult>;
     debugDeleteBundle(options: {