@metamask/device-mcp 0.3.2 → 0.4.0

package/dist/backends/android-instrumentation/installer.d.mts

@@ -0,0 +1,123 @@
+/**
+ * Installs and TRUSTS the bundled Android snapshot-helper instrumentation APK.
+ *
+ * The APK is built during `prepack` into `dist/android/` and shipped with the
+ * npm package (`files: ["dist"]`). Before the ADB backend runs `am instrument`
+ * it must guarantee that the package on the device is OUR helper — not a
+ * malicious app squatting the package name. Package name and versionCode are
+ * attacker-controlled metadata; the only trust anchor is the signing
+ * certificate. So `ensureHelperTrusted` installs/upgrades by versionCode
+ * (freshness only) and then UNCONDITIONALLY verifies the installed APK's v2/v3
+ * signer against the pinned SHA-256 from the build manifest. A mismatch throws
+ * {@link UntrustedHelperError} and the caller must fail closed (no dump
+ * fallback) — see `adb-backend.ts`.
+ *
+ * `__dirname` is used for path resolution because it is portable across the
+ * dual ESM/CJS build: ts-bridge rewrites it to an `import.meta.url`-based shim
+ * in the `.mjs` output and leaves the native binding in the `.cjs` output.
+ *
+ * Version/policy/signer-verify flow adapted from agent-device (MIT, Copyright
+ * (c) Callstack) onto our source-built APK and pure-JS signer verifier.
+ */
+import type { HelperArtifact } from "./artifact.mjs";
+/**
+ * `am instrument` prints this when the target instrumentation is not installed.
+ * The ADB backend keys reactive re-installs off this signature.
+ */
+export declare const INSTRUMENTATION_NOT_FOUND_SIGNATURE = "INSTRUMENTATION_FAILED";
+/**
+ * Resolve the path to the bundled helper APK (validated against its manifest).
+ *
+ * @returns The absolute path to the APK.
+ * @throws When the bundled artifact is missing, malformed, or its digest does
+ * not match the manifest.
+ */
+export declare function resolveHelperApkPath(): Promise<string>;
+/**
+ * Check whether the helper package is present on the device.
+ *
+ * @param serial - The target device serial.
+ * @returns True when the helper package is installed (any signer).
+ */
+export declare function isHelperInstalled(serial: string): Promise<boolean>;
+/**
+ * Install the bundled helper APK onto the device.
+ *
+ * `-r` reinstalls over an existing copy signed by the SAME key and `-t` allows
+ * the `testOnly` APK. It CANNOT overwrite a package signed by a different key:
+ * Android refuses with `INSTALL_FAILED_UPDATE_INCOMPATIBLE` (or
+ * `INSTALL_FAILED_SHARED_USER_INCOMPATIBLE`). That is a squatter signed by a
+ * foreign certificate, so it is a TRUST failure, not a generic one — we throw
+ * {@link UntrustedHelperError} to make the caller fail closed, consistent with
+ * the equal/higher-versionCode squatter path (which fails closed via the signer
+ * verification). Without this, a lower-versionCode squatter would surface as a
+ * generic Error and `auto` mode would silently fall back to `uiautomator dump`.
+ *
+ * @param serial - The target device serial.
+ * @param artifact - The bundled artifact carrying the pinned signer SHA-256,
+ * used both to locate the APK and to describe a trust failure.
+ * @throws {@link UntrustedHelperError} when the install is refused because the
+ * installed package is signed by a different certificate.
+ * @throws When the install command fails for a generic reason.
+ */
+export declare function installHelper(serial: string, artifact?: HelperArtifact): Promise<void>;
+/**
+ * Pull every installed APK path for the helper package (base + splits) into a
+ * private temp dir and verify each is signed by the pinned certificate.
+ *
+ * @param serial - The target device serial.
+ * @param artifact - The bundled artifact carrying the pinned signer SHA-256.
+ * @throws {@link UntrustedHelperError} when the installed signer does not match
+ * the pin.
+ */
+export declare function verifyInstalledSigner(serial: string, artifact: HelperArtifact): Promise<void>;
+/**
+ * Install/upgrade the bundled helper by versionCode (freshness only).
+ *
+ * versionCode is attacker-controlled metadata, so this is NOT a trust decision:
+ * it only decides whether a fresher build should be pushed. It performs NO
+ * signer verification. Callers MUST separately call
+ * {@link assertInstalledHelperTrusted} before every use of the helper.
+ *
+ * This is safe to gate behind a per-process "installed" cache because a stale
+ * cache at worst skips a redundant (idempotent) install; it never skips a trust
+ * check.
+ *
+ * @param serial - The target device serial.
+ * @throws When install fails for a generic reason.
+ */
+export declare function ensureHelperInstalled(serial: string): Promise<void>;
+/**
+ * Verify that the helper currently installed on the device is signed by the
+ * pinned certificate. This is the trust invariant and MUST run before EVERY
+ * `am instrument`, never cached: package name and versionCode are
+ * attacker-controlled, so an actor who can install packages could replace a
+ * previously-trusted helper with a malicious same-package instrumentation
+ * between snapshots. Re-verifying the installed signer on every use (pm path +
+ * pull + hash — cheap relative to the instrumentation run) is what keeps the
+ * signature pin a per-use invariant instead of a one-time check.
+ *
+ * @param serial - The target device serial.
+ * @throws {@link UntrustedHelperError} when the installed helper is signed by
+ * an unexpected certificate (a squatter). The caller MUST NOT fall back to
+ * `uiautomator dump` in that case.
+ */
+export declare function assertInstalledHelperTrusted(serial: string): Promise<void>;
+/**
+ * Ensure a TRUSTED helper is installed: install/upgrade by versionCode
+ * (freshness), then unconditionally verify the installed signer against the
+ * pinned certificate. Fails closed on a signer mismatch.
+ *
+ * Convenience wrapper over {@link ensureHelperInstalled} +
+ * {@link assertInstalledHelperTrusted}. Callers that cache the install step
+ * MUST still call {@link assertInstalledHelperTrusted} on every use rather than
+ * caching this whole call.
+ *
+ * @param serial - The target device serial.
+ * @throws {@link UntrustedHelperError} when the installed helper is signed by
+ * an unexpected certificate (a squatter). The caller MUST NOT fall back to
+ * `uiautomator dump` in that case.
+ * @throws When install fails for a generic reason.
+ */
+export declare function ensureHelperTrusted(serial: string): Promise<void>;
+//# sourceMappingURL=installer.d.mts.map

package/dist/backends/android-instrumentation/installer.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.d.mts","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/installer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,uBAAsB;AAapD;;;GAGG;AACH,eAAO,MAAM,mCAAmC,2BAA2B,CAAC;AAE5E;;;;;;GAMG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAG5D;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAwCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAqCf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOzE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE"}

package/dist/backends/android-instrumentation/installer.mjs

@@ -0,0 +1,225 @@
+/**
+ * Installs and TRUSTS the bundled Android snapshot-helper instrumentation APK.
+ *
+ * The APK is built during `prepack` into `dist/android/` and shipped with the
+ * npm package (`files: ["dist"]`). Before the ADB backend runs `am instrument`
+ * it must guarantee that the package on the device is OUR helper — not a
+ * malicious app squatting the package name. Package name and versionCode are
+ * attacker-controlled metadata; the only trust anchor is the signing
+ * certificate. So `ensureHelperTrusted` installs/upgrades by versionCode
+ * (freshness only) and then UNCONDITIONALLY verifies the installed APK's v2/v3
+ * signer against the pinned SHA-256 from the build manifest. A mismatch throws
+ * {@link UntrustedHelperError} and the caller must fail closed (no dump
+ * fallback) — see `adb-backend.ts`.
+ *
+ * `__dirname` is used for path resolution because it is portable across the
+ * dual ESM/CJS build: ts-bridge rewrites it to an `import.meta.url`-based shim
+ * in the `.mjs` output and leaves the native binding in the `.cjs` output.
+ *
+ * Version/policy/signer-verify flow adapted from agent-device (MIT, Copyright
+ * (c) Callstack) onto our source-built APK and pure-JS signer verifier.
+ */
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { createAndroidAdbExecutor } from "./adb.mjs";
+import { loadHelperArtifact } from "./artifact.mjs";
+import { UntrustedHelperError } from "./errors.mjs";
+import { assertApkSignerSha256 } from "./signer.mjs";
+import { HELPER_PACKAGE } from "./snapshot.mjs";
+import { exec } from "../../utils/exec.mjs";
+import { createPrivateTempDir } from "../../utils/output-path.mjs";
+const INSTALL_TIMEOUT_MS = 60000;
+const QUERY_TIMEOUT_MS = 10000;
+const PULL_TIMEOUT_MS = 30000;
+/**
+ * `am instrument` prints this when the target instrumentation is not installed.
+ * The ADB backend keys reactive re-installs off this signature.
+ */
+export const INSTRUMENTATION_NOT_FOUND_SIGNATURE = 'INSTRUMENTATION_FAILED';
+/**
+ * Resolve the path to the bundled helper APK (validated against its manifest).
+ *
+ * @returns The absolute path to the APK.
+ * @throws When the bundled artifact is missing, malformed, or its digest does
+ * not match the manifest.
+ */
+export async function resolveHelperApkPath() {
+    const artifact = await loadHelperArtifact();
+    return artifact.apkPath;
+}
+/**
+ * Check whether the helper package is present on the device.
+ *
+ * @param serial - The target device serial.
+ * @returns True when the helper package is installed (any signer).
+ */
+export async function isHelperInstalled(serial) {
+    const result = await exec('adb', ['-s', serial, 'shell', 'pm', 'list', 'packages', HELPER_PACKAGE], { timeoutMs: QUERY_TIMEOUT_MS });
+    return result.stdout.includes(`package:${HELPER_PACKAGE}`);
+}
+/**
+ * Read the installed helper's versionCode via `dumpsys package`.
+ *
+ * versionCode is attacker-controlled metadata: it is used ONLY to decide
+ * whether to (re)install a fresher build, never as a trust signal.
+ *
+ * @param serial - The target device serial.
+ * @returns The installed versionCode, or null when not installed / unreadable.
+ */
+async function readInstalledVersionCode(serial) {
+    const result = await exec('adb', ['-s', serial, 'shell', 'dumpsys', 'package', HELPER_PACKAGE], { timeoutMs: QUERY_TIMEOUT_MS });
+    const match = /versionCode=(\d+)/u.exec(result.stdout);
+    return match ? Number(match[1]) : null;
+}
+/**
+ * Android install-result tokens that specifically indicate the already-
+ * installed same-package app was signed by a DIFFERENT certificate, so the
+ * reinstall was refused on trust grounds (not a generic install failure). These
+ * constant names are stable across API 23-35 and are printed by PackageManager
+ * in the `Failure [<TOKEN>: ...]` line (on stdout; we scan both streams).
+ *
+ * Deliberately excludes generic failures like INSTALL_FAILED_TEST_ONLY,
+ * INSTALL_FAILED_VERSION_DOWNGRADE, INSTALL_FAILED_DUPLICATE_PERMISSION, and
+ * the parse-time no/inconsistent-certificate codes: none of those mean a
+ * squatter is signed by a different key on a normal reinstall.
+ */
+const SIGNER_CONFLICT_TOKENS = [
+    'INSTALL_FAILED_UPDATE_INCOMPATIBLE',
+    'INSTALL_FAILED_SHARED_USER_INCOMPATIBLE',
+];
+/**
+ * Install the bundled helper APK onto the device.
+ *
+ * `-r` reinstalls over an existing copy signed by the SAME key and `-t` allows
+ * the `testOnly` APK. It CANNOT overwrite a package signed by a different key:
+ * Android refuses with `INSTALL_FAILED_UPDATE_INCOMPATIBLE` (or
+ * `INSTALL_FAILED_SHARED_USER_INCOMPATIBLE`). That is a squatter signed by a
+ * foreign certificate, so it is a TRUST failure, not a generic one — we throw
+ * {@link UntrustedHelperError} to make the caller fail closed, consistent with
+ * the equal/higher-versionCode squatter path (which fails closed via the signer
+ * verification). Without this, a lower-versionCode squatter would surface as a
+ * generic Error and `auto` mode would silently fall back to `uiautomator dump`.
+ *
+ * @param serial - The target device serial.
+ * @param artifact - The bundled artifact carrying the pinned signer SHA-256,
+ * used both to locate the APK and to describe a trust failure.
+ * @throws {@link UntrustedHelperError} when the install is refused because the
+ * installed package is signed by a different certificate.
+ * @throws When the install command fails for a generic reason.
+ */
+export async function installHelper(serial, artifact) {
+    const resolved = artifact ?? (await loadHelperArtifact());
+    const { apkPath } = resolved;
+    const result = await exec('adb', ['-s', serial, 'install', '-r', '-t', apkPath], { timeoutMs: INSTALL_TIMEOUT_MS });
+    if (result.exitCode !== 0 || !result.stdout.includes('Success')) {
+        const output = `${result.stdout.trim()} ${result.stderr.trim()}`.trim();
+        if (SIGNER_CONFLICT_TOKENS.some((token) => output.includes(token))) {
+            throw new UntrustedHelperError(`Snapshot helper install was refused because the installed package is ` +
+                `signed by a different certificate (a squatter). ${output}`, { expectedSignerSha256: resolved.signerSha256 });
+        }
+        throw new Error(`Failed to install snapshot helper APK (${apkPath}).\n${output}`);
+    }
+}
+/**
+ * Pull every installed APK path for the helper package (base + splits) into a
+ * private temp dir and verify each is signed by the pinned certificate.
+ *
+ * @param serial - The target device serial.
+ * @param artifact - The bundled artifact carrying the pinned signer SHA-256.
+ * @throws {@link UntrustedHelperError} when the installed signer does not match
+ * the pin.
+ */
+export async function verifyInstalledSigner(serial, artifact) {
+    const run = createAndroidAdbExecutor(serial);
+    const pathsResult = await run(['shell', 'pm', 'path', HELPER_PACKAGE], {
+        timeoutMs: QUERY_TIMEOUT_MS,
+    });
+    const remotePaths = pathsResult.stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('package:'))
+        .map((line) => line.slice('package:'.length));
+    if (remotePaths.length === 0) {
+        throw new UntrustedHelperError('Snapshot helper is installed but its APK path could not be resolved', { expectedSignerSha256: artifact.signerSha256 });
+    }
+    const tempDir = createPrivateTempDir('helper-verify');
+    try {
+        let index = 0;
+        for (const remotePath of remotePaths) {
+            const localPath = join(tempDir, `apk-${index}.apk`);
+            index += 1;
+            const pull = await run(['pull', remotePath, localPath], {
+                timeoutMs: PULL_TIMEOUT_MS,
+            });
+            if (pull.exitCode !== 0) {
+                throw new UntrustedHelperError(`Could not pull installed helper APK for verification (${remotePath})`, { expectedSignerSha256: artifact.signerSha256 });
+            }
+            await assertApkSignerSha256(localPath, artifact.signerSha256);
+        }
+    }
+    finally {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Install/upgrade the bundled helper by versionCode (freshness only).
+ *
+ * versionCode is attacker-controlled metadata, so this is NOT a trust decision:
+ * it only decides whether a fresher build should be pushed. It performs NO
+ * signer verification. Callers MUST separately call
+ * {@link assertInstalledHelperTrusted} before every use of the helper.
+ *
+ * This is safe to gate behind a per-process "installed" cache because a stale
+ * cache at worst skips a redundant (idempotent) install; it never skips a trust
+ * check.
+ *
+ * @param serial - The target device serial.
+ * @throws When install fails for a generic reason.
+ */
+export async function ensureHelperInstalled(serial) {
+    const artifact = await loadHelperArtifact();
+    const installedVersion = await readInstalledVersionCode(serial);
+    if (installedVersion === null || installedVersion < artifact.versionCode) {
+        await installHelper(serial, artifact);
+    }
+}
+/**
+ * Verify that the helper currently installed on the device is signed by the
+ * pinned certificate. This is the trust invariant and MUST run before EVERY
+ * `am instrument`, never cached: package name and versionCode are
+ * attacker-controlled, so an actor who can install packages could replace a
+ * previously-trusted helper with a malicious same-package instrumentation
+ * between snapshots. Re-verifying the installed signer on every use (pm path +
+ * pull + hash — cheap relative to the instrumentation run) is what keeps the
+ * signature pin a per-use invariant instead of a one-time check.
+ *
+ * @param serial - The target device serial.
+ * @throws {@link UntrustedHelperError} when the installed helper is signed by
+ * an unexpected certificate (a squatter). The caller MUST NOT fall back to
+ * `uiautomator dump` in that case.
+ */
+export async function assertInstalledHelperTrusted(serial) {
+    const artifact = await loadHelperArtifact();
+    await verifyInstalledSigner(serial, artifact);
+}
+/**
+ * Ensure a TRUSTED helper is installed: install/upgrade by versionCode
+ * (freshness), then unconditionally verify the installed signer against the
+ * pinned certificate. Fails closed on a signer mismatch.
+ *
+ * Convenience wrapper over {@link ensureHelperInstalled} +
+ * {@link assertInstalledHelperTrusted}. Callers that cache the install step
+ * MUST still call {@link assertInstalledHelperTrusted} on every use rather than
+ * caching this whole call.
+ *
+ * @param serial - The target device serial.
+ * @throws {@link UntrustedHelperError} when the installed helper is signed by
+ * an unexpected certificate (a squatter). The caller MUST NOT fall back to
+ * `uiautomator dump` in that case.
+ * @throws When install fails for a generic reason.
+ */
+export async function ensureHelperTrusted(serial) {
+    await ensureHelperInstalled(serial);
+    await assertInstalledHelperTrusted(serial);
+}
+//# sourceMappingURL=installer.mjs.map

package/dist/backends/android-instrumentation/installer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.mjs","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/installer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Installs and TRUSTS the bundled Android snapshot-helper instrumentation APK.\n *\n * The APK is built during `prepack` into `dist/android/` and shipped with the\n * npm package (`files: [\"dist\"]`). Before the ADB backend runs `am instrument`\n * it must guarantee that the package on the device is OUR helper — not a\n * malicious app squatting the package name. Package name and versionCode are\n * attacker-controlled metadata; the only trust anchor is the signing\n * certificate. So `ensureHelperTrusted` installs/upgrades by versionCode\n * (freshness only) and then UNCONDITIONALLY verifies the installed APK's v2/v3\n * signer against the pinned SHA-256 from the build manifest. A mismatch throws\n * {@link UntrustedHelperError} and the caller must fail closed (no dump\n * fallback) — see `adb-backend.ts`.\n *\n * `__dirname` is used for path resolution because it is portable across the\n * dual ESM/CJS build: ts-bridge rewrites it to an `import.meta.url`-based shim\n * in the `.mjs` output and leaves the native binding in the `.cjs` output.\n *\n * Version/policy/signer-verify flow adapted from agent-device (MIT, Copyright\n * (c) Callstack) onto our source-built APK and pure-JS signer verifier.\n */\n\nimport { rmSync } from 'node:fs';\nimport { join } from 'node:path';\n\nimport { createAndroidAdbExecutor } from './adb.js';\nimport { loadHelperArtifact } from './artifact.js';\nimport type { HelperArtifact } from './artifact.js';\nimport { UntrustedHelperError } from './errors.js';\nimport { assertApkSignerSha256 } from './signer.js';\nimport { HELPER_PACKAGE } from './snapshot.js';\nimport { exec } from '../../utils/exec.js';\nimport { createPrivateTempDir } from '../../utils/output-path.js';\n\nconst INSTALL_TIMEOUT_MS = 60_000;\n\nconst QUERY_TIMEOUT_MS = 10_000;\n\nconst PULL_TIMEOUT_MS = 30_000;\n\n/**\n * `am instrument` prints this when the target instrumentation is not installed.\n * The ADB backend keys reactive re-installs off this signature.\n */\nexport const INSTRUMENTATION_NOT_FOUND_SIGNATURE = 'INSTRUMENTATION_FAILED';\n\n/**\n * Resolve the path to the bundled helper APK (validated against its manifest).\n *\n * @returns The absolute path to the APK.\n * @throws When the bundled artifact is missing, malformed, or its digest does\n * not match the manifest.\n */\nexport async function resolveHelperApkPath(): Promise<string> {\n  const artifact = await loadHelperArtifact();\n  return artifact.apkPath;\n}\n\n/**\n * Check whether the helper package is present on the device.\n *\n * @param serial - The target device serial.\n * @returns True when the helper package is installed (any signer).\n */\nexport async function isHelperInstalled(serial: string): Promise<boolean> {\n  const result = await exec(\n    'adb',\n    ['-s', serial, 'shell', 'pm', 'list', 'packages', HELPER_PACKAGE],\n    { timeoutMs: QUERY_TIMEOUT_MS },\n  );\n  return result.stdout.includes(`package:${HELPER_PACKAGE}`);\n}\n\n/**\n * Read the installed helper's versionCode via `dumpsys package`.\n *\n * versionCode is attacker-controlled metadata: it is used ONLY to decide\n * whether to (re)install a fresher build, never as a trust signal.\n *\n * @param serial - The target device serial.\n * @returns The installed versionCode, or null when not installed / unreadable.\n */\nasync function readInstalledVersionCode(\n  serial: string,\n): Promise<number | null> {\n  const result = await exec(\n    'adb',\n    ['-s', serial, 'shell', 'dumpsys', 'package', HELPER_PACKAGE],\n    { timeoutMs: QUERY_TIMEOUT_MS },\n  );\n  const match = /versionCode=(\\d+)/u.exec(result.stdout);\n  return match ? Number(match[1]) : null;\n}\n\n/**\n * Android install-result tokens that specifically indicate the already-\n * installed same-package app was signed by a DIFFERENT certificate, so the\n * reinstall was refused on trust grounds (not a generic install failure). These\n * constant names are stable across API 23-35 and are printed by PackageManager\n * in the `Failure [<TOKEN>: ...]` line (on stdout; we scan both streams).\n *\n * Deliberately excludes generic failures like INSTALL_FAILED_TEST_ONLY,\n * INSTALL_FAILED_VERSION_DOWNGRADE, INSTALL_FAILED_DUPLICATE_PERMISSION, and\n * the parse-time no/inconsistent-certificate codes: none of those mean a\n * squatter is signed by a different key on a normal reinstall.\n */\nconst SIGNER_CONFLICT_TOKENS = [\n  'INSTALL_FAILED_UPDATE_INCOMPATIBLE',\n  'INSTALL_FAILED_SHARED_USER_INCOMPATIBLE',\n];\n\n/**\n * Install the bundled helper APK onto the device.\n *\n * `-r` reinstalls over an existing copy signed by the SAME key and `-t` allows\n * the `testOnly` APK. It CANNOT overwrite a package signed by a different key:\n * Android refuses with `INSTALL_FAILED_UPDATE_INCOMPATIBLE` (or\n * `INSTALL_FAILED_SHARED_USER_INCOMPATIBLE`). That is a squatter signed by a\n * foreign certificate, so it is a TRUST failure, not a generic one — we throw\n * {@link UntrustedHelperError} to make the caller fail closed, consistent with\n * the equal/higher-versionCode squatter path (which fails closed via the signer\n * verification). Without this, a lower-versionCode squatter would surface as a\n * generic Error and `auto` mode would silently fall back to `uiautomator dump`.\n *\n * @param serial - The target device serial.\n * @param artifact - The bundled artifact carrying the pinned signer SHA-256,\n * used both to locate the APK and to describe a trust failure.\n * @throws {@link UntrustedHelperError} when the install is refused because the\n * installed package is signed by a different certificate.\n * @throws When the install command fails for a generic reason.\n */\nexport async function installHelper(\n  serial: string,\n  artifact?: HelperArtifact,\n): Promise<void> {\n  const resolved = artifact ?? (await loadHelperArtifact());\n  const { apkPath } = resolved;\n  const result = await exec(\n    'adb',\n    ['-s', serial, 'install', '-r', '-t', apkPath],\n    { timeoutMs: INSTALL_TIMEOUT_MS },\n  );\n  if (result.exitCode !== 0 || !result.stdout.includes('Success')) {\n    const output = `${result.stdout.trim()} ${result.stderr.trim()}`.trim();\n    if (SIGNER_CONFLICT_TOKENS.some((token) => output.includes(token))) {\n      throw new UntrustedHelperError(\n        `Snapshot helper install was refused because the installed package is ` +\n          `signed by a different certificate (a squatter). ${output}`,\n        { expectedSignerSha256: resolved.signerSha256 },\n      );\n    }\n    throw new Error(\n      `Failed to install snapshot helper APK (${apkPath}).\\n${output}`,\n    );\n  }\n}\n\n/**\n * Pull every installed APK path for the helper package (base + splits) into a\n * private temp dir and verify each is signed by the pinned certificate.\n *\n * @param serial - The target device serial.\n * @param artifact - The bundled artifact carrying the pinned signer SHA-256.\n * @throws {@link UntrustedHelperError} when the installed signer does not match\n * the pin.\n */\nexport async function verifyInstalledSigner(\n  serial: string,\n  artifact: HelperArtifact,\n): Promise<void> {\n  const run = createAndroidAdbExecutor(serial);\n  const pathsResult = await run(['shell', 'pm', 'path', HELPER_PACKAGE], {\n    timeoutMs: QUERY_TIMEOUT_MS,\n  });\n  const remotePaths = pathsResult.stdout\n    .split('\\n')\n    .map((line) => line.trim())\n    .filter((line) => line.startsWith('package:'))\n    .map((line) => line.slice('package:'.length));\n  if (remotePaths.length === 0) {\n    throw new UntrustedHelperError(\n      'Snapshot helper is installed but its APK path could not be resolved',\n      { expectedSignerSha256: artifact.signerSha256 },\n    );\n  }\n\n  const tempDir = createPrivateTempDir('helper-verify');\n  try {\n    let index = 0;\n    for (const remotePath of remotePaths) {\n      const localPath = join(tempDir, `apk-${index}.apk`);\n      index += 1;\n      const pull = await run(['pull', remotePath, localPath], {\n        timeoutMs: PULL_TIMEOUT_MS,\n      });\n      if (pull.exitCode !== 0) {\n        throw new UntrustedHelperError(\n          `Could not pull installed helper APK for verification (${remotePath})`,\n          { expectedSignerSha256: artifact.signerSha256 },\n        );\n      }\n      await assertApkSignerSha256(localPath, artifact.signerSha256);\n    }\n  } finally {\n    rmSync(tempDir, { recursive: true, force: true });\n  }\n}\n\n/**\n * Install/upgrade the bundled helper by versionCode (freshness only).\n *\n * versionCode is attacker-controlled metadata, so this is NOT a trust decision:\n * it only decides whether a fresher build should be pushed. It performs NO\n * signer verification. Callers MUST separately call\n * {@link assertInstalledHelperTrusted} before every use of the helper.\n *\n * This is safe to gate behind a per-process \"installed\" cache because a stale\n * cache at worst skips a redundant (idempotent) install; it never skips a trust\n * check.\n *\n * @param serial - The target device serial.\n * @throws When install fails for a generic reason.\n */\nexport async function ensureHelperInstalled(serial: string): Promise<void> {\n  const artifact = await loadHelperArtifact();\n  const installedVersion = await readInstalledVersionCode(serial);\n\n  if (installedVersion === null || installedVersion < artifact.versionCode) {\n    await installHelper(serial, artifact);\n  }\n}\n\n/**\n * Verify that the helper currently installed on the device is signed by the\n * pinned certificate. This is the trust invariant and MUST run before EVERY\n * `am instrument`, never cached: package name and versionCode are\n * attacker-controlled, so an actor who can install packages could replace a\n * previously-trusted helper with a malicious same-package instrumentation\n * between snapshots. Re-verifying the installed signer on every use (pm path +\n * pull + hash — cheap relative to the instrumentation run) is what keeps the\n * signature pin a per-use invariant instead of a one-time check.\n *\n * @param serial - The target device serial.\n * @throws {@link UntrustedHelperError} when the installed helper is signed by\n * an unexpected certificate (a squatter). The caller MUST NOT fall back to\n * `uiautomator dump` in that case.\n */\nexport async function assertInstalledHelperTrusted(\n  serial: string,\n): Promise<void> {\n  const artifact = await loadHelperArtifact();\n  await verifyInstalledSigner(serial, artifact);\n}\n\n/**\n * Ensure a TRUSTED helper is installed: install/upgrade by versionCode\n * (freshness), then unconditionally verify the installed signer against the\n * pinned certificate. Fails closed on a signer mismatch.\n *\n * Convenience wrapper over {@link ensureHelperInstalled} +\n * {@link assertInstalledHelperTrusted}. Callers that cache the install step\n * MUST still call {@link assertInstalledHelperTrusted} on every use rather than\n * caching this whole call.\n *\n * @param serial - The target device serial.\n * @throws {@link UntrustedHelperError} when the installed helper is signed by\n * an unexpected certificate (a squatter). The caller MUST NOT fall back to\n * `uiautomator dump` in that case.\n * @throws When install fails for a generic reason.\n */\nexport async function ensureHelperTrusted(serial: string): Promise<void> {\n  await ensureHelperInstalled(serial);\n  await assertInstalledHelperTrusted(serial);\n}\n"]}