@capgo/capacitor-updater 6.30.0 → 6.34.0

package/android/src/main/java/ee/forgr/capacitor_updater/{CryptoCipherV2.java → CryptoCipher.java}

@@ -10,8 +10,6 @@ package ee.forgr.capacitor_updater;
  * Created by Awesometic
  * It's encrypt returns Base64 encoded, and also decrypt for Base64 encoded cipher
  * references: http://stackoverflow.com/questions/12471999/rsa-encryption-decryption-in-android
- *
- * V2 Encryption - uses publicKey (modern encryption from main branch)
  */
 import android.util.Base64;
 import java.io.BufferedInputStream;
@@ -37,7 +35,7 @@ import javax.crypto.SecretKey;
 import javax.crypto.spec.IvParameterSpec;
 import javax.crypto.spec.SecretKeySpec;
 
-public class CryptoCipherV2 {
+public class CryptoCipher {
 
     private static Logger logger;
 
@@ -155,10 +153,10 @@ public class CryptoCipherV2 {
             String sessionKeyB64 = ivSessionKey.split(":")[1];
             byte[] iv = Base64.decode(ivB64.getBytes(), Base64.DEFAULT);
             byte[] sessionKey = Base64.decode(sessionKeyB64.getBytes(), Base64.DEFAULT);
-            PublicKey pKey = CryptoCipherV2.stringToPublicKey(publicKey);
-            byte[] decryptedSessionKey = CryptoCipherV2.decryptRSA(sessionKey, pKey);
+            PublicKey pKey = CryptoCipher.stringToPublicKey(publicKey);
+            byte[] decryptedSessionKey = CryptoCipher.decryptRSA(sessionKey, pKey);
 
-            SecretKey sKey = CryptoCipherV2.byteToSessionKey(decryptedSessionKey);
+            SecretKey sKey = CryptoCipher.byteToSessionKey(decryptedSessionKey);
             byte[] content = new byte[(int) file.length()];
 
             try (
@@ -168,7 +166,7 @@ public class CryptoCipherV2 {
             ) {
                 dis.readFully(content);
                 dis.close();
-                byte[] decrypted = CryptoCipherV2.decryptAES(content, sKey, iv);
+                byte[] decrypted = CryptoCipher.decryptAES(content, sKey, iv);
                 // write the decrypted string to the file
                 try (final FileOutputStream fos = new FileOutputStream(file.getAbsolutePath())) {
                     fos.write(decrypted);
@@ -200,14 +198,26 @@ public class CryptoCipherV2 {
             // Determine if input is hex or base64 encoded
             // Hex strings only contain 0-9 and a-f, while base64 contains other characters
             byte[] checksumBytes;
+            String detectedFormat;
             if (checksum.matches("^[0-9a-fA-F]+$")) {
                 // Hex encoded (new format from CLI for plugin versions >= 5.30.0, 6.30.0, 7.30.0)
                 checksumBytes = hexStringToByteArray(checksum);
+                detectedFormat = "hex";
             } else {
                 // TODO: remove backwards compatibility
                 // Base64 encoded (old format for backwards compatibility)
                 checksumBytes = Base64.decode(checksum, Base64.DEFAULT);
+                detectedFormat = "base64";
             }
+            logger.debug(
+                "Received encrypted checksum format: " +
+                    detectedFormat +
+                    " (length: " +
+                    checksum.length() +
+                    " chars, " +
+                    checksumBytes.length +
+                    " bytes)"
+            );
             PublicKey pKey = CryptoCipher.stringToPublicKey(publicKey);
             byte[] decryptedChecksum = CryptoCipher.decryptRSA(checksumBytes, pKey);
             // Return as hex string to match calcChecksum output format
@@ -217,13 +227,75 @@ public class CryptoCipherV2 {
                 if (hex.length() == 1) hexString.append('0');
                 hexString.append(hex);
             }
-            return hexString.toString();
+            String result = hexString.toString();
+
+            // Detect checksum algorithm based on length
+            String detectedAlgorithm;
+            if (decryptedChecksum.length == 32) {
+                detectedAlgorithm = "SHA-256";
+            } else if (decryptedChecksum.length == 4) {
+                detectedAlgorithm = "CRC32 (deprecated)";
+                logger.error(
+                    "CRC32 checksum detected. This algorithm is deprecated and no longer supported. Please update your CLI to use SHA-256 checksums."
+                );
+            } else {
+                detectedAlgorithm = "unknown (" + decryptedChecksum.length + " bytes)";
+                logger.error(
+                    "Unknown checksum algorithm detected with " + decryptedChecksum.length + " bytes. Expected SHA-256 (32 bytes)."
+                );
+            }
+            logger.debug(
+                "Decrypted checksum: " +
+                    detectedAlgorithm +
+                    " hex format (length: " +
+                    result.length() +
+                    " chars, " +
+                    decryptedChecksum.length +
+                    " bytes)"
+            );
+            return result;
         } catch (GeneralSecurityException e) {
             logger.error("decryptChecksum fail: " + e.getMessage());
             throw new IOException("Decryption failed: " + e.getMessage());
         }
     }
 
+    /**
+     * Detect checksum algorithm based on hex string length.
+     * SHA-256 = 64 hex chars (32 bytes)
+     * CRC32 = 8 hex chars (4 bytes)
+     */
+    public static String detectChecksumAlgorithm(String hexChecksum) {
+        if (hexChecksum == null || hexChecksum.isEmpty()) {
+            return "empty";
+        }
+        int len = hexChecksum.length();
+        if (len == 64) {
+            return "SHA-256";
+        } else if (len == 8) {
+            return "CRC32 (deprecated)";
+        } else {
+            return "unknown (" + len + " hex chars)";
+        }
+    }
+
+    /**
+     * Log checksum info and warn if deprecated algorithm detected.
+     */
+    public static void logChecksumInfo(String label, String hexChecksum) {
+        String algorithm = detectChecksumAlgorithm(hexChecksum);
+        logger.debug(label + ": " + algorithm + " hex format (length: " + hexChecksum.length() + " chars)");
+        if (algorithm.contains("CRC32")) {
+            logger.error(
+                "CRC32 checksum detected. This algorithm is deprecated and no longer supported. Please update your CLI to use SHA-256 checksums."
+            );
+        } else if (algorithm.contains("unknown")) {
+            logger.error(
+                "Unknown checksum algorithm detected. Expected SHA-256 (64 hex chars) but got " + hexChecksum.length() + " chars."
+            );
+        }
+    }
+
     public static String calcChecksum(File file) {
         final int BUFFER_SIZE = 1024 * 1024 * 5; // 5 MB buffer size
         MessageDigest digest;

package/android/src/main/java/ee/forgr/capacitor_updater/DownloadService.java

@@ -293,7 +293,7 @@ public class DownloadService extends Worker {
 
                 if (!publicKey.isEmpty() && sessionKey != null && !sessionKey.isEmpty()) {
                     try {
-                        fileHash = CryptoCipherV2.decryptChecksum(fileHash, publicKey);
+                        fileHash = CryptoCipher.decryptChecksum(fileHash, publicKey);
                     } catch (Exception e) {
                         logger.error("Error decrypting checksum for " + fileName + "fileHash: " + fileHash);
                         hasError.set(true);
@@ -606,7 +606,7 @@ public class DownloadService extends Worker {
 
             if (!publicKey.isEmpty() && sessionKey != null && !sessionKey.isEmpty()) {
                 logger.debug("Decrypting file " + targetFile.getName());
-                CryptoCipherV2.decryptFile(compressedFile, publicKey, sessionKey);
+                CryptoCipher.decryptFile(compressedFile, publicKey, sessionKey);
             }
 
             // Only decompress if file has .br extension
@@ -619,6 +619,8 @@ public class DownloadService extends Worker {
                     try {
                         decompressedData = decompressBrotli(compressedData, targetFile.getName());
                     } catch (IOException e) {
+                        // Delete the compressed file before throwing error
+                        compressedFile.delete();
                         sendStatsAsync(
                             "download_manifest_brotli_fail",
                             getInputData().getString(VERSION) + ":" + finalTargetFile.getName()
@@ -640,7 +642,9 @@ public class DownloadService extends Worker {
 
             // Delete the compressed file
             compressedFile.delete();
-            String calculatedHash = CryptoCipherV2.calcChecksum(finalTargetFile);
+            String calculatedHash = CryptoCipher.calcChecksum(finalTargetFile);
+            CryptoCipher.logChecksumInfo("Calculated checksum", calculatedHash);
+            CryptoCipher.logChecksumInfo("Expected checksum", expectedHash);
 
             // Verify checksum
             if (calculatedHash.equals(expectedHash)) {
@@ -769,7 +773,7 @@ public class DownloadService extends Worker {
 
             // Verify checksum if provided
             if (expectedChecksum != null && !expectedChecksum.isEmpty()) {
-                String actualChecksum = CryptoCipherV2.calcChecksum(tempFile);
+                String actualChecksum = CryptoCipher.calcChecksum(tempFile);
                 if (!expectedChecksum.equalsIgnoreCase(actualChecksum)) {
                     tempFile.delete();
                     throw new IOException("Checksum verification failed");

package/dist/docs.json

@@ -492,14 +492,14 @@
           },
           {
             "name": "throws",
-            "text": "{Error} If the request fails or the server returns an error."
+            "text": "{Error} Always throws when no new version is available (`error: \"no_new_version_available\"`), or when the request fails."
           },
           {
             "name": "since",
             "text": "4.0.0"
           }
         ],
-        "docs": "Check the update server for the latest available bundle version.\n\nThis queries your configured update URL (or Capgo backend) to see if a newer bundle\nis available for download. It does NOT download the bundle automatically.\n\nThe response includes:\n- `version`: The latest available version identifier\n- `url`: Download URL for the bundle (if available)\n- `breaking`: Whether this update is marked as incompatible (requires native app update)\n- `message`: Optional message from the server\n- `manifest`: File list for partial updates (if using multi-file downloads)\n\nAfter receiving the latest version info, you can:\n1. Compare it with your current version\n2. Download it using {@link download}\n3. Apply it using {@link next} or {@link set}",
+        "docs": "Check the update server for the latest available bundle version.\n\nThis queries your configured update URL (or Capgo backend) to see if a newer bundle\nis available for download. It does NOT download the bundle automatically.\n\nThe response includes:\n- `version`: The latest available version identifier\n- `url`: Download URL for the bundle (if available)\n- `breaking`: Whether this update is marked as incompatible (requires native app update)\n- `message`: Optional message from the server\n- `manifest`: File list for partial updates (if using multi-file downloads)\n\nAfter receiving the latest version info, you can:\n1. Compare it with your current version\n2. Download it using {@link download}\n3. Apply it using {@link next} or {@link set}\n\n**Important: Error handling for \"no new version available\"**\n\nWhen the device's current version matches the latest version on the server (i.e., the device is already\nup-to-date), the server returns a 200 response with `error: \"no_new_version_available\"` and\n`message: \"No new version available\"`. **This causes `getLatest()` to throw an error**, even though\nthis is a normal, expected condition.\n\nYou should catch this specific error to handle it gracefully:\n\n```typescript\ntry {\n  const latest = await CapacitorUpdater.getLatest();\n  // New version is available, proceed with download\n} catch (error) {\n  if (error.message === 'No new version available') {\n    // Device is already on the latest version - this is normal\n    console.log('Already up to date');\n  } else {\n    // Actual error occurred\n    console.error('Failed to check for updates:', error);\n  }\n}\n```\n\nIn this scenario, the server:\n- Logs the request with a \"No new version available\" message\n- Sends a \"noNew\" stat action to track that the device checked for updates but was already current (done on the backend)",
         "complexTypes": [
           "LatestVersion",
           "GetLatestOptions"
@@ -535,7 +535,7 @@
             "text": "4.7.0"
           }
         ],
-        "docs": "Assign this device to a specific update channel at runtime.\n\nChannels allow you to distribute different bundle versions to different groups of users\n(e.g., \"production\", \"beta\", \"staging\"). This method switches the device to a new channel.\n\n**Requirements:**\n- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)\n- The backend may accept or reject the request based on channel settings\n\n**When to use:**\n- After the app is ready and the user has interacted (e.g., opted into beta program)\n- To implement in-app channel switching (beta toggle, tester access, etc.)\n- For user-driven channel changes\n\n**When NOT to use:**\n- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead\n- Before user interaction\n\nThis sends a request to the Capgo backend linking your device ID to the specified channel.",
+        "docs": "Assign this device to a specific update channel at runtime.\n\nChannels allow you to distribute different bundle versions to different groups of users\n(e.g., \"production\", \"beta\", \"staging\"). This method switches the device to a new channel.\n\n**Requirements:**\n- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)\n- The backend may accept or reject the request based on channel settings\n\n**When to use:**\n- After the app is ready and the user has interacted (e.g., opted into beta program)\n- To implement in-app channel switching (beta toggle, tester access, etc.)\n- For user-driven channel changes\n\n**When NOT to use:**\n- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead\n- Before user interaction\n\n**Important: Listen for the `channelPrivate` event**\n\nWhen a user attempts to set a channel that doesn't allow device self-assignment, the method will\nthrow an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event\nto provide appropriate feedback to users:\n\n```typescript\nCapacitorUpdater.addListener('channelPrivate', (data) => {\n  console.warn(`Cannot access channel \"${data.channel}\": ${data.message}`);\n  // Show user-friendly message\n});\n```\n\nThis sends a request to the Capgo backend linking your device ID to the specified channel.",
         "complexTypes": [
           "ChannelRes",
           "SetChannelOptions"
@@ -1062,6 +1062,35 @@
         ],
         "slug": "addlistenerappready-"
       },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'channelPrivate', listenerFunc: (state: ChannelPrivateEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'channelPrivate'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(state: ChannelPrivateEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "7.34.0"
+          }
+        ],
+        "docs": "Listen for channel private event, fired when attempting to set a channel that doesn't allow device self-assignment.\n\nThis event is useful for:\n- Informing users they don't have permission to switch to a specific channel\n- Implementing custom error handling for channel restrictions\n- Logging unauthorized channel access attempts",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "ChannelPrivateEvent"
+        ],
+        "slug": "addlistenerchannelprivate-"
+      },
       {
         "name": "isAutoUpdateAvailable",
         "signature": "() => Promise<AutoUpdateAvailable>",
@@ -1690,7 +1719,7 @@
         {
           "name": "message",
           "tags": [],
-          "docs": "",
+          "docs": "Optional message from the server.\nWhen no new version is available, this will be \"No new version available\".",
           "complexTypes": [],
           "type": "string | undefined"
         },
@@ -1704,21 +1733,21 @@
         {
           "name": "error",
           "tags": [],
-          "docs": "",
+          "docs": "Error code from the server, if any.\nCommon values:\n- `\"no_new_version_available\"`: Device is already on the latest version (not a failure)\n- Other error codes indicate actual failures in the update process",
           "complexTypes": [],
           "type": "string | undefined"
         },
         {
           "name": "old",
           "tags": [],
-          "docs": "",
+          "docs": "The previous/current version name (provided for reference).",
           "complexTypes": [],
           "type": "string | undefined"
         },
         {
           "name": "url",
           "tags": [],
-          "docs": "",
+          "docs": "Download URL for the bundle (when a new version is available).",
           "complexTypes": [],
           "type": "string | undefined"
         },
@@ -1730,7 +1759,7 @@
               "name": "since"
             }
           ],
-          "docs": "",
+          "docs": "File list for partial updates (when using multi-file downloads).",
           "complexTypes": [
             "ManifestEntry"
           ],
@@ -2260,6 +2289,34 @@
         }
       ]
     },
+    {
+      "name": "ChannelPrivateEvent",
+      "slug": "channelprivateevent",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "channel",
+          "tags": [
+            {
+              "text": "7.34.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Emitted when attempting to set a channel that doesn't allow device self-assignment.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "message",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string"
+        }
+      ]
+    },
     {
       "name": "AutoUpdateAvailable",
       "slug": "autoupdateavailable",
@@ -2876,6 +2933,22 @@
           "complexTypes": [],
           "type": "boolean | undefined"
         },
+        {
+          "name": "allowSetDefaultChannel",
+          "tags": [
+            {
+              "text": "true",
+              "name": "default"
+            },
+            {
+              "text": "7.34.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Allow or disallow the {@link CapacitorUpdaterPlugin.setChannel} method to modify the defaultChannel.\nWhen set to `false`, calling `setChannel()` will return an error with code `disabled_by_config`.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
         {
           "name": "defaultChannel",
           "tags": [

package/dist/esm/definitions.d.ts

@@ -278,6 +278,14 @@ declare module '@capacitor/cli' {
              * @since  7.20.0
              */
             persistModifyUrl?: boolean;
+            /**
+             * Allow or disallow the {@link CapacitorUpdaterPlugin.setChannel} method to modify the defaultChannel.
+             * When set to `false`, calling `setChannel()` will return an error with code `disabled_by_config`.
+             *
+             * @default true
+             * @since 7.34.0
+             */
+            allowSetDefaultChannel?: boolean;
             /**
              * Set the default channel for the app in the config. Case sensitive.
              * This will setting will override the default channel set in the cloud, but will still respect overrides made in the cloud.
@@ -665,9 +673,37 @@ export interface CapacitorUpdaterPlugin {
      * 2. Download it using {@link download}
      * 3. Apply it using {@link next} or {@link set}
      *
+     * **Important: Error handling for "no new version available"**
+     *
+     * When the device's current version matches the latest version on the server (i.e., the device is already
+     * up-to-date), the server returns a 200 response with `error: "no_new_version_available"` and
+     * `message: "No new version available"`. **This causes `getLatest()` to throw an error**, even though
+     * this is a normal, expected condition.
+     *
+     * You should catch this specific error to handle it gracefully:
+     *
+     * ```typescript
+     * try {
+     *   const latest = await CapacitorUpdater.getLatest();
+     *   // New version is available, proceed with download
+     * } catch (error) {
+     *   if (error.message === 'No new version available') {
+     *     // Device is already on the latest version - this is normal
+     *     console.log('Already up to date');
+     *   } else {
+     *     // Actual error occurred
+     *     console.error('Failed to check for updates:', error);
+     *   }
+     * }
+     * ```
+     *
+     * In this scenario, the server:
+     * - Logs the request with a "No new version available" message
+     * - Sends a "noNew" stat action to track that the device checked for updates but was already current (done on the backend)
+     *
      * @param options Optional {@link GetLatestOptions} to specify which channel to check.
      * @returns {Promise<LatestVersion>} Information about the latest available bundle version.
-     * @throws {Error} If the request fails or the server returns an error.
+     * @throws {Error} Always throws when no new version is available (`error: "no_new_version_available"`), or when the request fails.
      * @since 4.0.0
      */
     getLatest(options?: GetLatestOptions): Promise<LatestVersion>;
@@ -690,6 +726,19 @@ export interface CapacitorUpdaterPlugin {
      * - At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead
      * - Before user interaction
      *
+     * **Important: Listen for the `channelPrivate` event**
+     *
+     * When a user attempts to set a channel that doesn't allow device self-assignment, the method will
+     * throw an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event
+     * to provide appropriate feedback to users:
+     *
+     * ```typescript
+     * CapacitorUpdater.addListener('channelPrivate', (data) => {
+     *   console.warn(`Cannot access channel "${data.channel}": ${data.message}`);
+     *   // Show user-friendly message
+     * });
+     * ```
+     *
      * This sends a request to the Capgo backend linking your device ID to the specified channel.
      *
      * @param options The {@link SetChannelOptions} containing the channel name and optional auto-update trigger.
@@ -948,6 +997,17 @@ export interface CapacitorUpdaterPlugin {
      * @since 5.1.0
      */
     addListener(eventName: 'appReady', listenerFunc: (state: AppReadyEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for channel private event, fired when attempting to set a channel that doesn't allow device self-assignment.
+     *
+     * This event is useful for:
+     * - Informing users they don't have permission to switch to a specific channel
+     * - Implementing custom error handling for channel restrictions
+     * - Logging unauthorized channel access attempts
+     *
+     * @since 7.34.0
+     */
+    addListener(eventName: 'channelPrivate', listenerFunc: (state: ChannelPrivateEvent) => void): Promise<PluginListenerHandle>;
     /**
      * Check if the auto-update feature is available (not disabled by custom server configuration).
      *
@@ -1234,6 +1294,15 @@ export interface AppReadyEvent {
     bundle: BundleInfo;
     status: string;
 }
+export interface ChannelPrivateEvent {
+    /**
+     * Emitted when attempting to set a channel that doesn't allow device self-assignment.
+     *
+     * @since 7.34.0
+     */
+    channel: string;
+    message: string;
+}
 export interface ManifestEntry {
     file_name: string | null;
     file_hash: string | null;
@@ -1260,12 +1329,29 @@ export interface LatestVersion {
      * @deprecated Use {@link LatestVersion.breaking} instead.
      */
     major?: boolean;
+    /**
+     * Optional message from the server.
+     * When no new version is available, this will be "No new version available".
+     */
     message?: string;
     sessionKey?: string;
+    /**
+     * Error code from the server, if any.
+     * Common values:
+     * - `"no_new_version_available"`: Device is already on the latest version (not a failure)
+     * - Other error codes indicate actual failures in the update process
+     */
     error?: string;
+    /**
+     * The previous/current version name (provided for reference).
+     */
     old?: string;
+    /**
+     * Download URL for the bundle (when a new version is available).
+     */
     url?: string;
     /**
+     * File list for partial updates (when using multi-file downloads).
      * @since 6.1
      */
     manifest?: ManifestEntry[];