@metamask/device-mcp 0.3.2 → 0.4.0

package/dist/backends/android-instrumentation/errors.d.cts

@@ -0,0 +1,68 @@
+/**
+ * Error types for the Android snapshot-helper trust + install pipeline.
+ *
+ * Two failure classes are deliberately distinct because the ADB backend treats
+ * them differently (see `adb-backend.ts`):
+ *
+ * - {@link SnapshotHelperError} — a *generic* failure (install failed, adb
+ *   hiccup, malformed artifact). The `auto` snapshot strategy is allowed to fall
+ *   back to `uiautomator dump` when one of these occurs.
+ * - {@link UntrustedHelperError} — the installed helper's signing certificate
+ *   does NOT match the pinned signer. This means a possibly-malicious app is
+ *   squatting the helper's package name. The snapshot flow MUST fail closed:
+ *   it is never swallowed and never triggers a dump fallback, because silently
+ *   returning a dump snapshot would hide a compromised device from a wallet
+ *   test harness.
+ *
+ * Structure adapted from agent-device (MIT, Copyright (c) Callstack); the
+ * `UntrustedHelperError` trust class and messaging are ours.
+ */
+/** Machine-readable code for a {@link SnapshotHelperError}. */
+export type SnapshotHelperErrorCode = 'COMMAND_FAILED' | 'INVALID_ARGS' | 'ARTIFACT_INVALID';
+/**
+ * A generic, recoverable snapshot-helper failure. Callers in `auto` mode may
+ * fall back to `uiautomator dump` after catching one of these.
+ */
+export declare class SnapshotHelperError extends Error {
+    readonly code: SnapshotHelperErrorCode;
+    /**
+     * @param code - Machine-readable failure category.
+     * @param message - Human-readable description.
+     * @param options - Standard error options (e.g. `cause`).
+     */
+    constructor(code: SnapshotHelperErrorCode, message: string, options?: ErrorOptions);
+}
+/**
+ * A trust failure: the installed helper is not signed by our pinned key.
+ *
+ * This is a hard stop. It must propagate out of the snapshot flow — never be
+ * converted to `null`, never be collected into a generic failure list, and
+ * never trigger a `uiautomator dump` fallback.
+ */
+export declare class UntrustedHelperError extends Error {
+    /** The signer SHA-256 we required. */
+    readonly expectedSignerSha256: string;
+    /** The signer SHA-256 actually found on the device, if one was extracted. */
+    readonly actualSignerSha256?: string;
+    /**
+     * @param message - Human-readable description of the mismatch.
+     * @param details - The expected and (optionally) observed signer digests.
+     * @param details.expectedSignerSha256 - The pinned signer SHA-256.
+     * @param details.actualSignerSha256 - The observed signer SHA-256, if known.
+     * @param options - Standard error options (e.g. `cause`).
+     */
+    constructor(message: string, details: {
+        expectedSignerSha256: string;
+        actualSignerSha256?: string;
+    }, options?: ErrorOptions);
+}
+/**
+ * Type guard for the fail-closed trust error. The ADB backend uses this to
+ * decide whether an instrumentation failure may fall back to `dump` (generic)
+ * or must propagate (trust).
+ *
+ * @param error - The value to test.
+ * @returns True when `error` is an {@link UntrustedHelperError}.
+ */
+export declare function isUntrustedHelperError(error: unknown): error is UntrustedHelperError;
+//# sourceMappingURL=errors.d.cts.map

package/dist/backends/android-instrumentation/errors.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.cts","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,uBAAuB,GAC/B,gBAAgB,GAChB,cAAc,GACd,kBAAkB,CAAC;AAEvB;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAgB,IAAI,EAAE,uBAAuB,CAAC;IAE9C;;;;OAIG;gBAED,IAAI,EAAE,uBAAuB,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAQzB;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,sCAAsC;IACtC,SAAgB,oBAAoB,EAAE,MAAM,CAAC;IAE7C,6EAA6E;IAC7E,SAAgB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5C;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,oBAAoB,EAAE,MAAM,CAAC;QAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;KAC7B,EACD,OAAO,CAAC,EAAE,YAAY;CASzB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,oBAAoB,CAE/B"}

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

@@ -0,0 +1,68 @@
+/**
+ * Error types for the Android snapshot-helper trust + install pipeline.
+ *
+ * Two failure classes are deliberately distinct because the ADB backend treats
+ * them differently (see `adb-backend.ts`):
+ *
+ * - {@link SnapshotHelperError} — a *generic* failure (install failed, adb
+ *   hiccup, malformed artifact). The `auto` snapshot strategy is allowed to fall
+ *   back to `uiautomator dump` when one of these occurs.
+ * - {@link UntrustedHelperError} — the installed helper's signing certificate
+ *   does NOT match the pinned signer. This means a possibly-malicious app is
+ *   squatting the helper's package name. The snapshot flow MUST fail closed:
+ *   it is never swallowed and never triggers a dump fallback, because silently
+ *   returning a dump snapshot would hide a compromised device from a wallet
+ *   test harness.
+ *
+ * Structure adapted from agent-device (MIT, Copyright (c) Callstack); the
+ * `UntrustedHelperError` trust class and messaging are ours.
+ */
+/** Machine-readable code for a {@link SnapshotHelperError}. */
+export type SnapshotHelperErrorCode = 'COMMAND_FAILED' | 'INVALID_ARGS' | 'ARTIFACT_INVALID';
+/**
+ * A generic, recoverable snapshot-helper failure. Callers in `auto` mode may
+ * fall back to `uiautomator dump` after catching one of these.
+ */
+export declare class SnapshotHelperError extends Error {
+    readonly code: SnapshotHelperErrorCode;
+    /**
+     * @param code - Machine-readable failure category.
+     * @param message - Human-readable description.
+     * @param options - Standard error options (e.g. `cause`).
+     */
+    constructor(code: SnapshotHelperErrorCode, message: string, options?: ErrorOptions);
+}
+/**
+ * A trust failure: the installed helper is not signed by our pinned key.
+ *
+ * This is a hard stop. It must propagate out of the snapshot flow — never be
+ * converted to `null`, never be collected into a generic failure list, and
+ * never trigger a `uiautomator dump` fallback.
+ */
+export declare class UntrustedHelperError extends Error {
+    /** The signer SHA-256 we required. */
+    readonly expectedSignerSha256: string;
+    /** The signer SHA-256 actually found on the device, if one was extracted. */
+    readonly actualSignerSha256?: string;
+    /**
+     * @param message - Human-readable description of the mismatch.
+     * @param details - The expected and (optionally) observed signer digests.
+     * @param details.expectedSignerSha256 - The pinned signer SHA-256.
+     * @param details.actualSignerSha256 - The observed signer SHA-256, if known.
+     * @param options - Standard error options (e.g. `cause`).
+     */
+    constructor(message: string, details: {
+        expectedSignerSha256: string;
+        actualSignerSha256?: string;
+    }, options?: ErrorOptions);
+}
+/**
+ * Type guard for the fail-closed trust error. The ADB backend uses this to
+ * decide whether an instrumentation failure may fall back to `dump` (generic)
+ * or must propagate (trust).
+ *
+ * @param error - The value to test.
+ * @returns True when `error` is an {@link UntrustedHelperError}.
+ */
+export declare function isUntrustedHelperError(error: unknown): error is UntrustedHelperError;
+//# sourceMappingURL=errors.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,uBAAuB,GAC/B,gBAAgB,GAChB,cAAc,GACd,kBAAkB,CAAC;AAEvB;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAgB,IAAI,EAAE,uBAAuB,CAAC;IAE9C;;;;OAIG;gBAED,IAAI,EAAE,uBAAuB,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAQzB;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,sCAAsC;IACtC,SAAgB,oBAAoB,EAAE,MAAM,CAAC;IAE7C,6EAA6E;IAC7E,SAAgB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5C;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,oBAAoB,EAAE,MAAM,CAAC;QAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;KAC7B,EACD,OAAO,CAAC,EAAE,YAAY;CASzB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,oBAAoB,CAE/B"}

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

@@ -0,0 +1,73 @@
+/**
+ * Error types for the Android snapshot-helper trust + install pipeline.
+ *
+ * Two failure classes are deliberately distinct because the ADB backend treats
+ * them differently (see `adb-backend.ts`):
+ *
+ * - {@link SnapshotHelperError} — a *generic* failure (install failed, adb
+ *   hiccup, malformed artifact). The `auto` snapshot strategy is allowed to fall
+ *   back to `uiautomator dump` when one of these occurs.
+ * - {@link UntrustedHelperError} — the installed helper's signing certificate
+ *   does NOT match the pinned signer. This means a possibly-malicious app is
+ *   squatting the helper's package name. The snapshot flow MUST fail closed:
+ *   it is never swallowed and never triggers a dump fallback, because silently
+ *   returning a dump snapshot would hide a compromised device from a wallet
+ *   test harness.
+ *
+ * Structure adapted from agent-device (MIT, Copyright (c) Callstack); the
+ * `UntrustedHelperError` trust class and messaging are ours.
+ */
+/**
+ * A generic, recoverable snapshot-helper failure. Callers in `auto` mode may
+ * fall back to `uiautomator dump` after catching one of these.
+ */
+export class SnapshotHelperError extends Error {
+    /**
+     * @param code - Machine-readable failure category.
+     * @param message - Human-readable description.
+     * @param options - Standard error options (e.g. `cause`).
+     */
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'SnapshotHelperError';
+        this.code = code;
+        // Restore prototype chain for `instanceof` across the dual ESM/CJS build.
+        Object.setPrototypeOf(this, SnapshotHelperError.prototype);
+    }
+}
+/**
+ * A trust failure: the installed helper is not signed by our pinned key.
+ *
+ * This is a hard stop. It must propagate out of the snapshot flow — never be
+ * converted to `null`, never be collected into a generic failure list, and
+ * never trigger a `uiautomator dump` fallback.
+ */
+export class UntrustedHelperError extends Error {
+    /**
+     * @param message - Human-readable description of the mismatch.
+     * @param details - The expected and (optionally) observed signer digests.
+     * @param details.expectedSignerSha256 - The pinned signer SHA-256.
+     * @param details.actualSignerSha256 - The observed signer SHA-256, if known.
+     * @param options - Standard error options (e.g. `cause`).
+     */
+    constructor(message, details, options) {
+        super(message, options);
+        this.name = 'UntrustedHelperError';
+        this.expectedSignerSha256 = details.expectedSignerSha256;
+        this.actualSignerSha256 = details.actualSignerSha256;
+        // Restore prototype chain for `instanceof` across the dual ESM/CJS build.
+        Object.setPrototypeOf(this, UntrustedHelperError.prototype);
+    }
+}
+/**
+ * Type guard for the fail-closed trust error. The ADB backend uses this to
+ * decide whether an instrumentation failure may fall back to `dump` (generic)
+ * or must propagate (trust).
+ *
+ * @param error - The value to test.
+ * @returns True when `error` is an {@link UntrustedHelperError}.
+ */
+export function isUntrustedHelperError(error) {
+    return error instanceof UntrustedHelperError;
+}
+//# sourceMappingURL=errors.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAG5C;;;;OAIG;IACH,YACE,IAA6B,EAC7B,OAAe,EACf,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,0EAA0E;QAC1E,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC7D,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAO7C;;;;;;OAMG;IACH,YACE,OAAe,EACf,OAGC,EACD,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;QACzD,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;QACrD,0EAA0E;QAC1E,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC9D,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAc;IAEd,OAAO,KAAK,YAAY,oBAAoB,CAAC;AAC/C,CAAC","sourcesContent":["/**\n * Error types for the Android snapshot-helper trust + install pipeline.\n *\n * Two failure classes are deliberately distinct because the ADB backend treats\n * them differently (see `adb-backend.ts`):\n *\n * - {@link SnapshotHelperError} — a *generic* failure (install failed, adb\n *   hiccup, malformed artifact). The `auto` snapshot strategy is allowed to fall\n *   back to `uiautomator dump` when one of these occurs.\n * - {@link UntrustedHelperError} — the installed helper's signing certificate\n *   does NOT match the pinned signer. This means a possibly-malicious app is\n *   squatting the helper's package name. The snapshot flow MUST fail closed:\n *   it is never swallowed and never triggers a dump fallback, because silently\n *   returning a dump snapshot would hide a compromised device from a wallet\n *   test harness.\n *\n * Structure adapted from agent-device (MIT, Copyright (c) Callstack); the\n * `UntrustedHelperError` trust class and messaging are ours.\n */\n\n/** Machine-readable code for a {@link SnapshotHelperError}. */\nexport type SnapshotHelperErrorCode =\n  | 'COMMAND_FAILED'\n  | 'INVALID_ARGS'\n  | 'ARTIFACT_INVALID';\n\n/**\n * A generic, recoverable snapshot-helper failure. Callers in `auto` mode may\n * fall back to `uiautomator dump` after catching one of these.\n */\nexport class SnapshotHelperError extends Error {\n  public readonly code: SnapshotHelperErrorCode;\n\n  /**\n   * @param code - Machine-readable failure category.\n   * @param message - Human-readable description.\n   * @param options - Standard error options (e.g. `cause`).\n   */\n  public constructor(\n    code: SnapshotHelperErrorCode,\n    message: string,\n    options?: ErrorOptions,\n  ) {\n    super(message, options);\n    this.name = 'SnapshotHelperError';\n    this.code = code;\n    // Restore prototype chain for `instanceof` across the dual ESM/CJS build.\n    Object.setPrototypeOf(this, SnapshotHelperError.prototype);\n  }\n}\n\n/**\n * A trust failure: the installed helper is not signed by our pinned key.\n *\n * This is a hard stop. It must propagate out of the snapshot flow — never be\n * converted to `null`, never be collected into a generic failure list, and\n * never trigger a `uiautomator dump` fallback.\n */\nexport class UntrustedHelperError extends Error {\n  /** The signer SHA-256 we required. */\n  public readonly expectedSignerSha256: string;\n\n  /** The signer SHA-256 actually found on the device, if one was extracted. */\n  public readonly actualSignerSha256?: string;\n\n  /**\n   * @param message - Human-readable description of the mismatch.\n   * @param details - The expected and (optionally) observed signer digests.\n   * @param details.expectedSignerSha256 - The pinned signer SHA-256.\n   * @param details.actualSignerSha256 - The observed signer SHA-256, if known.\n   * @param options - Standard error options (e.g. `cause`).\n   */\n  public constructor(\n    message: string,\n    details: {\n      expectedSignerSha256: string;\n      actualSignerSha256?: string;\n    },\n    options?: ErrorOptions,\n  ) {\n    super(message, options);\n    this.name = 'UntrustedHelperError';\n    this.expectedSignerSha256 = details.expectedSignerSha256;\n    this.actualSignerSha256 = details.actualSignerSha256;\n    // Restore prototype chain for `instanceof` across the dual ESM/CJS build.\n    Object.setPrototypeOf(this, UntrustedHelperError.prototype);\n  }\n}\n\n/**\n * Type guard for the fail-closed trust error. The ADB backend uses this to\n * decide whether an instrumentation failure may fall back to `dump` (generic)\n * or must propagate (trust).\n *\n * @param error - The value to test.\n * @returns True when `error` is an {@link UntrustedHelperError}.\n */\nexport function isUntrustedHelperError(\n  error: unknown,\n): error is UntrustedHelperError {\n  return error instanceof UntrustedHelperError;\n}\n"]}

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

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTRUMENTATION_NOT_FOUND_SIGNATURE = void 0;
+exports.resolveHelperApkPath = resolveHelperApkPath;
+exports.isHelperInstalled = isHelperInstalled;
+exports.installHelper = installHelper;
+exports.verifyInstalledSigner = verifyInstalledSigner;
+exports.ensureHelperInstalled = ensureHelperInstalled;
+exports.assertInstalledHelperTrusted = assertInstalledHelperTrusted;
+exports.ensureHelperTrusted = ensureHelperTrusted;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const adb_js_1 = require("./adb.cjs");
+const artifact_js_1 = require("./artifact.cjs");
+const errors_js_1 = require("./errors.cjs");
+const signer_js_1 = require("./signer.cjs");
+const snapshot_js_1 = require("./snapshot.cjs");
+const exec_js_1 = require("../../utils/exec.cjs");
+const output_path_js_1 = require("../../utils/output-path.cjs");
+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.
+ */
+exports.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.
+ */
+async function resolveHelperApkPath() {
+    const artifact = await (0, artifact_js_1.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).
+ */
+async function isHelperInstalled(serial) {
+    const result = await (0, exec_js_1.exec)('adb', ['-s', serial, 'shell', 'pm', 'list', 'packages', snapshot_js_1.HELPER_PACKAGE], { timeoutMs: QUERY_TIMEOUT_MS });
+    return result.stdout.includes(`package:${snapshot_js_1.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 (0, exec_js_1.exec)('adb', ['-s', serial, 'shell', 'dumpsys', 'package', snapshot_js_1.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.
+ */
+async function installHelper(serial, artifact) {
+    const resolved = artifact ?? (await (0, artifact_js_1.loadHelperArtifact)());
+    const { apkPath } = resolved;
+    const result = await (0, exec_js_1.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 errors_js_1.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.
+ */
+async function verifyInstalledSigner(serial, artifact) {
+    const run = (0, adb_js_1.createAndroidAdbExecutor)(serial);
+    const pathsResult = await run(['shell', 'pm', 'path', snapshot_js_1.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 errors_js_1.UntrustedHelperError('Snapshot helper is installed but its APK path could not be resolved', { expectedSignerSha256: artifact.signerSha256 });
+    }
+    const tempDir = (0, output_path_js_1.createPrivateTempDir)('helper-verify');
+    try {
+        let index = 0;
+        for (const remotePath of remotePaths) {
+            const localPath = (0, node_path_1.join)(tempDir, `apk-${index}.apk`);
+            index += 1;
+            const pull = await run(['pull', remotePath, localPath], {
+                timeoutMs: PULL_TIMEOUT_MS,
+            });
+            if (pull.exitCode !== 0) {
+                throw new errors_js_1.UntrustedHelperError(`Could not pull installed helper APK for verification (${remotePath})`, { expectedSignerSha256: artifact.signerSha256 });
+            }
+            await (0, signer_js_1.assertApkSignerSha256)(localPath, artifact.signerSha256);
+        }
+    }
+    finally {
+        (0, node_fs_1.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.
+ */
+async function ensureHelperInstalled(serial) {
+    const artifact = await (0, artifact_js_1.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.
+ */
+async function assertInstalledHelperTrusted(serial) {
+    const artifact = await (0, artifact_js_1.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.
+ */
+async function ensureHelperTrusted(serial) {
+    await ensureHelperInstalled(serial);
+    await assertInstalledHelperTrusted(serial);
+}
+//# sourceMappingURL=installer.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"installer.cjs","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"]}

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

@@ -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.cjs";
+/**
+ * `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.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"installer.d.cts","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"}