fix: validate android helper install args

Author: thymikee

android-snapshot-helper/README.md

@@ -8,6 +8,8 @@ unavailable, it falls back to the active-window root.
 
 The helper is intentionally provider-neutral. Local `adb`, cloud ADB tunnels, and remote device
 providers can all install and run the same APK as long as they can execute ADB-style operations.
+Released helper APKs use the committed `debug.keystore`; do not rotate it casually, because Android
+requires a stable signing certificate for `adb install -r` upgrades.
 
 ## Build
 
@@ -31,6 +33,9 @@ adb shell am instrument -w \
 ```
 
 `maxDepth` also caps recursive traversal depth inside the helper.
+The `-t` install flag is required because the helper is a debuggable instrumentation/test APK.
+Devices or providers that block test-package installs must allow this package before helper capture
+can run.
 
 ## Output Contract
 
@@ -60,3 +65,8 @@ The final instrumentation result includes:
 - `elapsedMs`
 
 Failures return `ok=false`, `errorType`, and `message` in the final result.
+
+The release manifest is a stable provider contract for the current helper protocol. Providers should
+resolve the APK from `apkUrl`, verify `sha256`, install using `installArgs`, and run
+`instrumentationRunner`. `installArgs` must start with `install`; extra arguments are limited to adb
+install flags and the consumer appends the APK path.

android-snapshot-helper/src/main/java/com/callstack/agentdevice/snapshothelper/SnapshotInstrumentation.java

@@ -162,6 +162,7 @@ private static int appendInteractiveWindowRoots(
         if (root != null) {
           root.recycle();
         }
+        // UiAutomation.getWindows() transfers recyclable AccessibilityWindowInfo instances.
         window.recycle();
       }
     }

src/platforms/android/__tests__/snapshot-helper.test.ts

@@ -432,6 +432,9 @@ test('parseAndroidSnapshotHelperManifest validates manifest shape', () => {
   assert.throws(() => parseAndroidSnapshotHelperManifest({ ...manifest, outputFormat: 'json' }), {
     message: 'Android snapshot helper manifest outputFormat must be "uiautomator-xml".',
   });
+  assert.throws(() => parseAndroidSnapshotHelperManifest({ ...manifest, installArgs: ['shell'] }), {
+    message: 'Android snapshot helper manifest installArgs must start with "install".',
+  });
 });
 
 function helperOutput(options: { chunks: string[]; result: Record<string, string> }): string {

src/platforms/android/snapshot-helper.ts

@@ -154,7 +154,10 @@ export async function ensureAndroidSnapshotHelper(options: {
   }
 
   await verifyAndroidSnapshotHelperArtifact(artifact);
-  const installArgs = [...artifact.manifest.installArgs, artifact.apkPath];
+  const installArgs = [
+    ...readAndroidSnapshotHelperInstallArgs(artifact.manifest),
+    artifact.apkPath,
+  ];
   const result = await installAndroidSnapshotHelper(adb, installArgs, {
     packageName,
     timeoutMs: options.timeoutMs,
@@ -182,7 +185,7 @@ export async function verifyAndroidSnapshotHelperArtifact(
   artifact: AndroidSnapshotHelperArtifact,
 ): Promise<void> {
   const actual = await sha256File(artifact.apkPath);
-  if (actual !== artifact.manifest.sha256.toLowerCase()) {
+  if (actual !== artifact.manifest.sha256) {
     throw new AppError('COMMAND_FAILED', 'Android snapshot helper APK checksum mismatch', {
       apkPath: artifact.apkPath,
       expectedSha256: artifact.manifest.sha256,
@@ -503,10 +506,31 @@ export function parseAndroidSnapshotHelperManifest(value: unknown): AndroidSnaps
       'statusProtocol',
       'android-snapshot-helper-v1',
     ),
-    installArgs: readStringArray(record.installArgs, 'installArgs'),
+    installArgs: readAndroidSnapshotHelperManifestInstallArgs(record.installArgs),
   };
 }
 
+function readAndroidSnapshotHelperInstallArgs(manifest: AndroidSnapshotHelperManifest): string[] {
+  return readAndroidSnapshotHelperManifestInstallArgs(manifest.installArgs);
+}
+
+function readAndroidSnapshotHelperManifestInstallArgs(value: unknown): string[] {
+  const installArgs = readStringArray(value, 'installArgs');
+  if (installArgs[0] !== 'install') {
+    throw new AppError(
+      'INVALID_ARGS',
+      'Android snapshot helper manifest installArgs must start with "install".',
+    );
+  }
+  if (installArgs.some((arg) => arg.includes('\u0000'))) {
+    throw new AppError(
+      'INVALID_ARGS',
+      'Android snapshot helper manifest installArgs must not contain null bytes.',
+    );
+  }
+  return installArgs;
+}
+
 async function readInstalledVersionCode(
   adb: AndroidAdbExecutor,
   packageName: string,