@metamask/device-mcp 0.3.2 → 0.4.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"adb.cjs","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/adb.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAwBH,4DAMC;AA5BD,kDAA2C;AAa3C,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C;;;;;;GAMG;AACH,SAAgB,wBAAwB,CAAC,MAAc;IACrD,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAC7B,IAAA,cAAI,EAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE;QACnC,SAAS,EAAE,OAAO,EAAE,SAAS;QAC7B,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,kBAAkB;KACpD,CAAC,CAAC;AACP,CAAC","sourcesContent":["/**\n * Device-scoped ADB executor used by the snapshot-helper trust + install\n * modules. Wrapping `exec('adb', ['-s', serial, ...])` behind a small function\n * keeps the serial in one place and lets those modules be unit-tested with an\n * injected fake executor instead of spawning real `adb`.\n *\n * The executor abstraction is adapted from agent-device (MIT, Copyright (c)\n * Callstack); our `ExecResult` already matches its result shape.\n */\n\nimport { exec } from '../../utils/exec.js';\nimport type { ExecResult } from '../../utils/exec.js';\n\nexport type AndroidAdbExecOptions = {\n  timeoutMs?: number;\n  maxBuffer?: number;\n};\n\nexport type AndroidAdbExecutor = (\n  args: string[],\n  options?: AndroidAdbExecOptions,\n) => Promise<ExecResult>;\n\nconst DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;\n\n/**\n * Create an ADB executor bound to a single device serial. Every call is\n * prefixed with `-s <serial>` so callers pass only the sub-command.\n *\n * @param serial - The target device serial.\n * @returns An executor that runs `adb -s <serial> <args...>`.\n */\nexport function createAndroidAdbExecutor(serial: string): AndroidAdbExecutor {\n  return async (args, options) =>\n    exec('adb', ['-s', serial, ...args], {\n      timeoutMs: options?.timeoutMs,\n      maxBuffer: options?.maxBuffer ?? DEFAULT_MAX_BUFFER,\n    });\n}\n"]}

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

@@ -0,0 +1,24 @@
+/**
+ * Device-scoped ADB executor used by the snapshot-helper trust + install
+ * modules. Wrapping `exec('adb', ['-s', serial, ...])` behind a small function
+ * keeps the serial in one place and lets those modules be unit-tested with an
+ * injected fake executor instead of spawning real `adb`.
+ *
+ * The executor abstraction is adapted from agent-device (MIT, Copyright (c)
+ * Callstack); our `ExecResult` already matches its result shape.
+ */
+import type { ExecResult } from "../../utils/exec.cjs";
+export type AndroidAdbExecOptions = {
+    timeoutMs?: number;
+    maxBuffer?: number;
+};
+export type AndroidAdbExecutor = (args: string[], options?: AndroidAdbExecOptions) => Promise<ExecResult>;
+/**
+ * Create an ADB executor bound to a single device serial. Every call is
+ * prefixed with `-s <serial>` so callers pass only the sub-command.
+ *
+ * @param serial - The target device serial.
+ * @returns An executor that runs `adb -s <serial> <args...>`.
+ */
+export declare function createAndroidAdbExecutor(serial: string): AndroidAdbExecutor;
+//# sourceMappingURL=adb.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adb.d.cts","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/adb.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,6BAA4B;AAEtD,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAC/B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,qBAAqB,KAC5B,OAAO,CAAC,UAAU,CAAC,CAAC;AAIzB;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAM3E"}

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

@@ -0,0 +1,24 @@
+/**
+ * Device-scoped ADB executor used by the snapshot-helper trust + install
+ * modules. Wrapping `exec('adb', ['-s', serial, ...])` behind a small function
+ * keeps the serial in one place and lets those modules be unit-tested with an
+ * injected fake executor instead of spawning real `adb`.
+ *
+ * The executor abstraction is adapted from agent-device (MIT, Copyright (c)
+ * Callstack); our `ExecResult` already matches its result shape.
+ */
+import type { ExecResult } from "../../utils/exec.mjs";
+export type AndroidAdbExecOptions = {
+    timeoutMs?: number;
+    maxBuffer?: number;
+};
+export type AndroidAdbExecutor = (args: string[], options?: AndroidAdbExecOptions) => Promise<ExecResult>;
+/**
+ * Create an ADB executor bound to a single device serial. Every call is
+ * prefixed with `-s <serial>` so callers pass only the sub-command.
+ *
+ * @param serial - The target device serial.
+ * @returns An executor that runs `adb -s <serial> <args...>`.
+ */
+export declare function createAndroidAdbExecutor(serial: string): AndroidAdbExecutor;
+//# sourceMappingURL=adb.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adb.d.mts","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/adb.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,6BAA4B;AAEtD,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAC/B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,qBAAqB,KAC5B,OAAO,CAAC,UAAU,CAAC,CAAC;AAIzB;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAM3E"}

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

@@ -0,0 +1,25 @@
+/**
+ * Device-scoped ADB executor used by the snapshot-helper trust + install
+ * modules. Wrapping `exec('adb', ['-s', serial, ...])` behind a small function
+ * keeps the serial in one place and lets those modules be unit-tested with an
+ * injected fake executor instead of spawning real `adb`.
+ *
+ * The executor abstraction is adapted from agent-device (MIT, Copyright (c)
+ * Callstack); our `ExecResult` already matches its result shape.
+ */
+import { exec } from "../../utils/exec.mjs";
+const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;
+/**
+ * Create an ADB executor bound to a single device serial. Every call is
+ * prefixed with `-s <serial>` so callers pass only the sub-command.
+ *
+ * @param serial - The target device serial.
+ * @returns An executor that runs `adb -s <serial> <args...>`.
+ */
+export function createAndroidAdbExecutor(serial) {
+    return async (args, options) => exec('adb', ['-s', serial, ...args], {
+        timeoutMs: options?.timeoutMs,
+        maxBuffer: options?.maxBuffer ?? DEFAULT_MAX_BUFFER,
+    });
+}
+//# sourceMappingURL=adb.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adb.mjs","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/adb.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,6BAA4B;AAa3C,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAc;IACrD,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAC7B,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE;QACnC,SAAS,EAAE,OAAO,EAAE,SAAS;QAC7B,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,kBAAkB;KACpD,CAAC,CAAC;AACP,CAAC","sourcesContent":["/**\n * Device-scoped ADB executor used by the snapshot-helper trust + install\n * modules. Wrapping `exec('adb', ['-s', serial, ...])` behind a small function\n * keeps the serial in one place and lets those modules be unit-tested with an\n * injected fake executor instead of spawning real `adb`.\n *\n * The executor abstraction is adapted from agent-device (MIT, Copyright (c)\n * Callstack); our `ExecResult` already matches its result shape.\n */\n\nimport { exec } from '../../utils/exec.js';\nimport type { ExecResult } from '../../utils/exec.js';\n\nexport type AndroidAdbExecOptions = {\n  timeoutMs?: number;\n  maxBuffer?: number;\n};\n\nexport type AndroidAdbExecutor = (\n  args: string[],\n  options?: AndroidAdbExecOptions,\n) => Promise<ExecResult>;\n\nconst DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;\n\n/**\n * Create an ADB executor bound to a single device serial. Every call is\n * prefixed with `-s <serial>` so callers pass only the sub-command.\n *\n * @param serial - The target device serial.\n * @returns An executor that runs `adb -s <serial> <args...>`.\n */\nexport function createAndroidAdbExecutor(serial: string): AndroidAdbExecutor {\n  return async (args, options) =>\n    exec('adb', ['-s', serial, ...args], {\n      timeoutMs: options?.timeoutMs,\n      maxBuffer: options?.maxBuffer ?? DEFAULT_MAX_BUFFER,\n    });\n}\n"]}

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

@@ -0,0 +1,139 @@
+"use strict";
+// Derived from agent-device (MIT, Copyright (c) Callstack); adapted for our
+// source-built helper APK and package constants.
+/**
+ * Reads and validates the provenance manifest that `build-android-helper.sh`
+ * emits next to the bundled helper APK. The manifest is the single source of
+ * truth for the package name, instrumentation runner, versionCode, the APK
+ * file digest (a tamper check on `dist/`), and the pinned signer certificate
+ * SHA-256 that the installed helper must match before we run `am instrument`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadHelperArtifact = loadHelperArtifact;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const errors_js_1 = require("./errors.cjs");
+const snapshot_js_1 = require("./snapshot.cjs");
+// The compiled module lives at dist/backends/android-instrumentation/, so the
+// bundled helper APK directory (dist/android) is two levels up.
+const HELPER_APK_DIR = (0, node_path_1.join)(__dirname, '..', '..', 'android');
+const HELPER_APK_PREFIX = 'device-mcp-android-snapshot-helper-';
+const MANIFEST_SUFFIX = '.manifest.json';
+/**
+ * Raise an {@link SnapshotHelperError} for a missing or malformed artifact.
+ *
+ * @param message - What went wrong.
+ * @throws Always.
+ */
+function invalid(message) {
+    throw new errors_js_1.SnapshotHelperError('ARTIFACT_INVALID', message);
+}
+/**
+ * Assert a manifest field is a non-empty string.
+ *
+ * @param value - The parsed field value.
+ * @param field - The field name, for error messages.
+ * @returns The value, narrowed to string.
+ */
+function requireString(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        invalid(`Helper manifest field "${field}" is missing or not a string`);
+    }
+    return value;
+}
+/**
+ * Assert a manifest field is a finite non-negative integer.
+ *
+ * @param value - The parsed field value.
+ * @param field - The field name, for error messages.
+ * @returns The value, narrowed to number.
+ */
+function requireInt(value, field) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        invalid(`Helper manifest field "${field}" is missing or not an integer`);
+    }
+    return value;
+}
+/**
+ * Locate the helper manifest in the bundled `dist/android` directory.
+ *
+ * @returns The absolute path to the newest matching manifest.
+ * @throws {@link SnapshotHelperError} when the directory or manifest is absent.
+ */
+async function resolveManifestPath() {
+    let entries;
+    try {
+        entries = await (0, promises_1.readdir)(HELPER_APK_DIR);
+    }
+    catch {
+        return invalid(`Snapshot helper directory is missing (${HELPER_APK_DIR}). ` +
+            'The package may have been built without the Android helper.');
+    }
+    const manifest = entries
+        .filter((name) => name.startsWith(HELPER_APK_PREFIX) && name.endsWith(MANIFEST_SUFFIX))
+        .sort()
+        .at(-1);
+    if (!manifest) {
+        return invalid(`No snapshot helper manifest found in ${HELPER_APK_DIR}. ` +
+            'The package may have been built without the Android helper.');
+    }
+    return (0, node_path_1.join)(HELPER_APK_DIR, manifest);
+}
+/**
+ * Compute the SHA-256 of a file as lowercase hex.
+ *
+ * @param path - The file to digest.
+ * @returns The lowercase-hex SHA-256.
+ */
+async function sha256File(path) {
+    const bytes = await (0, promises_1.readFile)(path);
+    return (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+}
+/**
+ * Load and validate the bundled helper artifact: parse the manifest, confirm
+ * it targets our package, resolve the APK path, and verify the APK's SHA-256
+ * matches the manifest (a tamper check on the shipped `dist/`).
+ *
+ * @returns The validated artifact descriptor.
+ * @throws {@link SnapshotHelperError} when anything is missing, malformed, or
+ * the APK digest does not match the manifest.
+ */
+async function loadHelperArtifact() {
+    const manifestPath = await resolveManifestPath();
+    let parsed;
+    try {
+        parsed = JSON.parse(await (0, promises_1.readFile)(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        return invalid(`Helper manifest is not valid JSON (${manifestPath}): ${String(error)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return invalid(`Helper manifest is not an object (${manifestPath})`);
+    }
+    const manifest = parsed;
+    const packageName = requireString(manifest.packageName, 'packageName');
+    if (packageName !== snapshot_js_1.HELPER_PACKAGE) {
+        invalid(`Helper manifest packageName "${packageName}" does not match the ` +
+            `expected "${snapshot_js_1.HELPER_PACKAGE}"`);
+    }
+    const assetName = requireString(manifest.assetName, 'assetName');
+    const sha256 = requireString(manifest.sha256, 'sha256');
+    const apkPath = (0, node_path_1.join)(HELPER_APK_DIR, assetName);
+    const actualSha256 = await sha256File(apkPath).catch(() => invalid(`Helper APK is missing or unreadable (${apkPath})`));
+    if (actualSha256 !== sha256.toLowerCase()) {
+        invalid(`Helper APK digest does not match its manifest (${apkPath}). ` +
+            'The bundled artifact may be corrupt or tampered with.');
+    }
+    return {
+        version: requireString(manifest.version, 'version'),
+        versionCode: requireInt(manifest.versionCode, 'versionCode'),
+        packageName,
+        instrumentationRunner: requireString(manifest.instrumentationRunner, 'instrumentationRunner'),
+        apkPath,
+        sha256: sha256.toLowerCase(),
+        signerSha256: requireString(manifest.signerSha256, 'signerSha256').toLowerCase(),
+        minSdk: requireInt(manifest.minSdk, 'minSdk'),
+    };
+}
+//# sourceMappingURL=artifact.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.cjs","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/artifact.ts"],"names":[],"mappings":"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","sourcesContent":["// Derived from agent-device (MIT, Copyright (c) Callstack); adapted for our\n// source-built helper APK and package constants.\n/**\n * Reads and validates the provenance manifest that `build-android-helper.sh`\n * emits next to the bundled helper APK. The manifest is the single source of\n * truth for the package name, instrumentation runner, versionCode, the APK\n * file digest (a tamper check on `dist/`), and the pinned signer certificate\n * SHA-256 that the installed helper must match before we run `am instrument`.\n */\n\nimport { createHash } from 'node:crypto';\nimport { readdir, readFile } from 'node:fs/promises';\nimport { join } from 'node:path';\n\nimport { SnapshotHelperError } from './errors.js';\nimport { HELPER_PACKAGE } from './snapshot.js';\n\n// The compiled module lives at dist/backends/android-instrumentation/, so the\n// bundled helper APK directory (dist/android) is two levels up.\nconst HELPER_APK_DIR = join(__dirname, '..', '..', 'android');\n\nconst HELPER_APK_PREFIX = 'device-mcp-android-snapshot-helper-';\n\nconst MANIFEST_SUFFIX = '.manifest.json';\n\nexport type HelperArtifact = {\n  version: string;\n  versionCode: number;\n  packageName: string;\n  instrumentationRunner: string;\n  apkPath: string;\n  sha256: string;\n  signerSha256: string;\n  minSdk: number;\n};\n\n/**\n * Raise an {@link SnapshotHelperError} for a missing or malformed artifact.\n *\n * @param message - What went wrong.\n * @throws Always.\n */\nfunction invalid(message: string): never {\n  throw new SnapshotHelperError('ARTIFACT_INVALID', message);\n}\n\n/**\n * Assert a manifest field is a non-empty string.\n *\n * @param value - The parsed field value.\n * @param field - The field name, for error messages.\n * @returns The value, narrowed to string.\n */\nfunction requireString(value: unknown, field: string): string {\n  if (typeof value !== 'string' || value.length === 0) {\n    invalid(`Helper manifest field \"${field}\" is missing or not a string`);\n  }\n  return value;\n}\n\n/**\n * Assert a manifest field is a finite non-negative integer.\n *\n * @param value - The parsed field value.\n * @param field - The field name, for error messages.\n * @returns The value, narrowed to number.\n */\nfunction requireInt(value: unknown, field: string): number {\n  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {\n    invalid(`Helper manifest field \"${field}\" is missing or not an integer`);\n  }\n  return value;\n}\n\n/**\n * Locate the helper manifest in the bundled `dist/android` directory.\n *\n * @returns The absolute path to the newest matching manifest.\n * @throws {@link SnapshotHelperError} when the directory or manifest is absent.\n */\nasync function resolveManifestPath(): Promise<string> {\n  let entries: string[];\n  try {\n    entries = await readdir(HELPER_APK_DIR);\n  } catch {\n    return invalid(\n      `Snapshot helper directory is missing (${HELPER_APK_DIR}). ` +\n        'The package may have been built without the Android helper.',\n    );\n  }\n  const manifest = entries\n    .filter(\n      (name) =>\n        name.startsWith(HELPER_APK_PREFIX) && name.endsWith(MANIFEST_SUFFIX),\n    )\n    .sort()\n    .at(-1);\n  if (!manifest) {\n    return invalid(\n      `No snapshot helper manifest found in ${HELPER_APK_DIR}. ` +\n        'The package may have been built without the Android helper.',\n    );\n  }\n  return join(HELPER_APK_DIR, manifest);\n}\n\n/**\n * Compute the SHA-256 of a file as lowercase hex.\n *\n * @param path - The file to digest.\n * @returns The lowercase-hex SHA-256.\n */\nasync function sha256File(path: string): Promise<string> {\n  const bytes = await readFile(path);\n  return createHash('sha256').update(bytes).digest('hex');\n}\n\n/**\n * Load and validate the bundled helper artifact: parse the manifest, confirm\n * it targets our package, resolve the APK path, and verify the APK's SHA-256\n * matches the manifest (a tamper check on the shipped `dist/`).\n *\n * @returns The validated artifact descriptor.\n * @throws {@link SnapshotHelperError} when anything is missing, malformed, or\n * the APK digest does not match the manifest.\n */\nexport async function loadHelperArtifact(): Promise<HelperArtifact> {\n  const manifestPath = await resolveManifestPath();\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(await readFile(manifestPath, 'utf8'));\n  } catch (error) {\n    return invalid(\n      `Helper manifest is not valid JSON (${manifestPath}): ${String(error)}`,\n    );\n  }\n  if (typeof parsed !== 'object' || parsed === null) {\n    return invalid(`Helper manifest is not an object (${manifestPath})`);\n  }\n  const manifest = parsed as Record<string, unknown>;\n\n  const packageName = requireString(manifest.packageName, 'packageName');\n  if (packageName !== HELPER_PACKAGE) {\n    invalid(\n      `Helper manifest packageName \"${packageName}\" does not match the ` +\n        `expected \"${HELPER_PACKAGE}\"`,\n    );\n  }\n\n  const assetName = requireString(manifest.assetName, 'assetName');\n  const sha256 = requireString(manifest.sha256, 'sha256');\n  const apkPath = join(HELPER_APK_DIR, assetName);\n\n  const actualSha256 = await sha256File(apkPath).catch(() =>\n    invalid(`Helper APK is missing or unreadable (${apkPath})`),\n  );\n  if (actualSha256 !== sha256.toLowerCase()) {\n    invalid(\n      `Helper APK digest does not match its manifest (${apkPath}). ` +\n        'The bundled artifact may be corrupt or tampered with.',\n    );\n  }\n\n  return {\n    version: requireString(manifest.version, 'version'),\n    versionCode: requireInt(manifest.versionCode, 'versionCode'),\n    packageName,\n    instrumentationRunner: requireString(\n      manifest.instrumentationRunner,\n      'instrumentationRunner',\n    ),\n    apkPath,\n    sha256: sha256.toLowerCase(),\n    signerSha256: requireString(\n      manifest.signerSha256,\n      'signerSha256',\n    ).toLowerCase(),\n    minSdk: requireInt(manifest.minSdk, 'minSdk'),\n  };\n}\n"]}

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

@@ -0,0 +1,28 @@
+/**
+ * Reads and validates the provenance manifest that `build-android-helper.sh`
+ * emits next to the bundled helper APK. The manifest is the single source of
+ * truth for the package name, instrumentation runner, versionCode, the APK
+ * file digest (a tamper check on `dist/`), and the pinned signer certificate
+ * SHA-256 that the installed helper must match before we run `am instrument`.
+ */
+export type HelperArtifact = {
+    version: string;
+    versionCode: number;
+    packageName: string;
+    instrumentationRunner: string;
+    apkPath: string;
+    sha256: string;
+    signerSha256: string;
+    minSdk: number;
+};
+/**
+ * Load and validate the bundled helper artifact: parse the manifest, confirm
+ * it targets our package, resolve the APK path, and verify the APK's SHA-256
+ * matches the manifest (a tamper check on the shipped `dist/`).
+ *
+ * @returns The validated artifact descriptor.
+ * @throws {@link SnapshotHelperError} when anything is missing, malformed, or
+ * the APK digest does not match the manifest.
+ */
+export declare function loadHelperArtifact(): Promise<HelperArtifact>;
+//# sourceMappingURL=artifact.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.cts","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/artifact.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAiBH,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAmFF;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,cAAc,CAAC,CAqDlE"}

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

@@ -0,0 +1,28 @@
+/**
+ * Reads and validates the provenance manifest that `build-android-helper.sh`
+ * emits next to the bundled helper APK. The manifest is the single source of
+ * truth for the package name, instrumentation runner, versionCode, the APK
+ * file digest (a tamper check on `dist/`), and the pinned signer certificate
+ * SHA-256 that the installed helper must match before we run `am instrument`.
+ */
+export type HelperArtifact = {
+    version: string;
+    versionCode: number;
+    packageName: string;
+    instrumentationRunner: string;
+    apkPath: string;
+    sha256: string;
+    signerSha256: string;
+    minSdk: number;
+};
+/**
+ * Load and validate the bundled helper artifact: parse the manifest, confirm
+ * it targets our package, resolve the APK path, and verify the APK's SHA-256
+ * matches the manifest (a tamper check on the shipped `dist/`).
+ *
+ * @returns The validated artifact descriptor.
+ * @throws {@link SnapshotHelperError} when anything is missing, malformed, or
+ * the APK digest does not match the manifest.
+ */
+export declare function loadHelperArtifact(): Promise<HelperArtifact>;
+//# sourceMappingURL=artifact.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.mts","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/artifact.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAiBH,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAmFF;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,cAAc,CAAC,CAqDlE"}

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

@@ -0,0 +1,154 @@
+function $__filename(fileUrl) {
+    const url = new URL(fileUrl);
+    return url.pathname.replace(/^\/([a-zA-Z]:)/u, "$1");
+}
+function $getDirname(path) {
+    const sanitisedPath = path.toString().replace(/\\/gu, "/").replace(/\/$/u, "");
+    const index = sanitisedPath.lastIndexOf("/");
+    if (index === -1) {
+        return path;
+    }
+    if (index === 0) {
+        return "/";
+    }
+    return sanitisedPath.slice(0, index);
+}
+function $__dirname(url) {
+    return $getDirname($__filename(url));
+}
+// Derived from agent-device (MIT, Copyright (c) Callstack); adapted for our
+// source-built helper APK and package constants.
+/**
+ * Reads and validates the provenance manifest that `build-android-helper.sh`
+ * emits next to the bundled helper APK. The manifest is the single source of
+ * truth for the package name, instrumentation runner, versionCode, the APK
+ * file digest (a tamper check on `dist/`), and the pinned signer certificate
+ * SHA-256 that the installed helper must match before we run `am instrument`.
+ */
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { SnapshotHelperError } from "./errors.mjs";
+import { HELPER_PACKAGE } from "./snapshot.mjs";
+// The compiled module lives at dist/backends/android-instrumentation/, so the
+// bundled helper APK directory (dist/android) is two levels up.
+const HELPER_APK_DIR = join($__dirname(import.meta.url), '..', '..', 'android');
+const HELPER_APK_PREFIX = 'device-mcp-android-snapshot-helper-';
+const MANIFEST_SUFFIX = '.manifest.json';
+/**
+ * Raise an {@link SnapshotHelperError} for a missing or malformed artifact.
+ *
+ * @param message - What went wrong.
+ * @throws Always.
+ */
+function invalid(message) {
+    throw new SnapshotHelperError('ARTIFACT_INVALID', message);
+}
+/**
+ * Assert a manifest field is a non-empty string.
+ *
+ * @param value - The parsed field value.
+ * @param field - The field name, for error messages.
+ * @returns The value, narrowed to string.
+ */
+function requireString(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        invalid(`Helper manifest field "${field}" is missing or not a string`);
+    }
+    return value;
+}
+/**
+ * Assert a manifest field is a finite non-negative integer.
+ *
+ * @param value - The parsed field value.
+ * @param field - The field name, for error messages.
+ * @returns The value, narrowed to number.
+ */
+function requireInt(value, field) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        invalid(`Helper manifest field "${field}" is missing or not an integer`);
+    }
+    return value;
+}
+/**
+ * Locate the helper manifest in the bundled `dist/android` directory.
+ *
+ * @returns The absolute path to the newest matching manifest.
+ * @throws {@link SnapshotHelperError} when the directory or manifest is absent.
+ */
+async function resolveManifestPath() {
+    let entries;
+    try {
+        entries = await readdir(HELPER_APK_DIR);
+    }
+    catch {
+        return invalid(`Snapshot helper directory is missing (${HELPER_APK_DIR}). ` +
+            'The package may have been built without the Android helper.');
+    }
+    const manifest = entries
+        .filter((name) => name.startsWith(HELPER_APK_PREFIX) && name.endsWith(MANIFEST_SUFFIX))
+        .sort()
+        .at(-1);
+    if (!manifest) {
+        return invalid(`No snapshot helper manifest found in ${HELPER_APK_DIR}. ` +
+            'The package may have been built without the Android helper.');
+    }
+    return join(HELPER_APK_DIR, manifest);
+}
+/**
+ * Compute the SHA-256 of a file as lowercase hex.
+ *
+ * @param path - The file to digest.
+ * @returns The lowercase-hex SHA-256.
+ */
+async function sha256File(path) {
+    const bytes = await readFile(path);
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/**
+ * Load and validate the bundled helper artifact: parse the manifest, confirm
+ * it targets our package, resolve the APK path, and verify the APK's SHA-256
+ * matches the manifest (a tamper check on the shipped `dist/`).
+ *
+ * @returns The validated artifact descriptor.
+ * @throws {@link SnapshotHelperError} when anything is missing, malformed, or
+ * the APK digest does not match the manifest.
+ */
+export async function loadHelperArtifact() {
+    const manifestPath = await resolveManifestPath();
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        return invalid(`Helper manifest is not valid JSON (${manifestPath}): ${String(error)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return invalid(`Helper manifest is not an object (${manifestPath})`);
+    }
+    const manifest = parsed;
+    const packageName = requireString(manifest.packageName, 'packageName');
+    if (packageName !== HELPER_PACKAGE) {
+        invalid(`Helper manifest packageName "${packageName}" does not match the ` +
+            `expected "${HELPER_PACKAGE}"`);
+    }
+    const assetName = requireString(manifest.assetName, 'assetName');
+    const sha256 = requireString(manifest.sha256, 'sha256');
+    const apkPath = join(HELPER_APK_DIR, assetName);
+    const actualSha256 = await sha256File(apkPath).catch(() => invalid(`Helper APK is missing or unreadable (${apkPath})`));
+    if (actualSha256 !== sha256.toLowerCase()) {
+        invalid(`Helper APK digest does not match its manifest (${apkPath}). ` +
+            'The bundled artifact may be corrupt or tampered with.');
+    }
+    return {
+        version: requireString(manifest.version, 'version'),
+        versionCode: requireInt(manifest.versionCode, 'versionCode'),
+        packageName,
+        instrumentationRunner: requireString(manifest.instrumentationRunner, 'instrumentationRunner'),
+        apkPath,
+        sha256: sha256.toLowerCase(),
+        signerSha256: requireString(manifest.signerSha256, 'signerSha256').toLowerCase(),
+        minSdk: requireInt(manifest.minSdk, 'minSdk'),
+    };
+}
+//# sourceMappingURL=artifact.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.mjs","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/artifact.ts"],"names":[],"mappings":"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","sourcesContent":["// Derived from agent-device (MIT, Copyright (c) Callstack); adapted for our\n// source-built helper APK and package constants.\n/**\n * Reads and validates the provenance manifest that `build-android-helper.sh`\n * emits next to the bundled helper APK. The manifest is the single source of\n * truth for the package name, instrumentation runner, versionCode, the APK\n * file digest (a tamper check on `dist/`), and the pinned signer certificate\n * SHA-256 that the installed helper must match before we run `am instrument`.\n */\n\nimport { createHash } from 'node:crypto';\nimport { readdir, readFile } from 'node:fs/promises';\nimport { join } from 'node:path';\n\nimport { SnapshotHelperError } from './errors.js';\nimport { HELPER_PACKAGE } from './snapshot.js';\n\n// The compiled module lives at dist/backends/android-instrumentation/, so the\n// bundled helper APK directory (dist/android) is two levels up.\nconst HELPER_APK_DIR = join(__dirname, '..', '..', 'android');\n\nconst HELPER_APK_PREFIX = 'device-mcp-android-snapshot-helper-';\n\nconst MANIFEST_SUFFIX = '.manifest.json';\n\nexport type HelperArtifact = {\n  version: string;\n  versionCode: number;\n  packageName: string;\n  instrumentationRunner: string;\n  apkPath: string;\n  sha256: string;\n  signerSha256: string;\n  minSdk: number;\n};\n\n/**\n * Raise an {@link SnapshotHelperError} for a missing or malformed artifact.\n *\n * @param message - What went wrong.\n * @throws Always.\n */\nfunction invalid(message: string): never {\n  throw new SnapshotHelperError('ARTIFACT_INVALID', message);\n}\n\n/**\n * Assert a manifest field is a non-empty string.\n *\n * @param value - The parsed field value.\n * @param field - The field name, for error messages.\n * @returns The value, narrowed to string.\n */\nfunction requireString(value: unknown, field: string): string {\n  if (typeof value !== 'string' || value.length === 0) {\n    invalid(`Helper manifest field \"${field}\" is missing or not a string`);\n  }\n  return value;\n}\n\n/**\n * Assert a manifest field is a finite non-negative integer.\n *\n * @param value - The parsed field value.\n * @param field - The field name, for error messages.\n * @returns The value, narrowed to number.\n */\nfunction requireInt(value: unknown, field: string): number {\n  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {\n    invalid(`Helper manifest field \"${field}\" is missing or not an integer`);\n  }\n  return value;\n}\n\n/**\n * Locate the helper manifest in the bundled `dist/android` directory.\n *\n * @returns The absolute path to the newest matching manifest.\n * @throws {@link SnapshotHelperError} when the directory or manifest is absent.\n */\nasync function resolveManifestPath(): Promise<string> {\n  let entries: string[];\n  try {\n    entries = await readdir(HELPER_APK_DIR);\n  } catch {\n    return invalid(\n      `Snapshot helper directory is missing (${HELPER_APK_DIR}). ` +\n        'The package may have been built without the Android helper.',\n    );\n  }\n  const manifest = entries\n    .filter(\n      (name) =>\n        name.startsWith(HELPER_APK_PREFIX) && name.endsWith(MANIFEST_SUFFIX),\n    )\n    .sort()\n    .at(-1);\n  if (!manifest) {\n    return invalid(\n      `No snapshot helper manifest found in ${HELPER_APK_DIR}. ` +\n        'The package may have been built without the Android helper.',\n    );\n  }\n  return join(HELPER_APK_DIR, manifest);\n}\n\n/**\n * Compute the SHA-256 of a file as lowercase hex.\n *\n * @param path - The file to digest.\n * @returns The lowercase-hex SHA-256.\n */\nasync function sha256File(path: string): Promise<string> {\n  const bytes = await readFile(path);\n  return createHash('sha256').update(bytes).digest('hex');\n}\n\n/**\n * Load and validate the bundled helper artifact: parse the manifest, confirm\n * it targets our package, resolve the APK path, and verify the APK's SHA-256\n * matches the manifest (a tamper check on the shipped `dist/`).\n *\n * @returns The validated artifact descriptor.\n * @throws {@link SnapshotHelperError} when anything is missing, malformed, or\n * the APK digest does not match the manifest.\n */\nexport async function loadHelperArtifact(): Promise<HelperArtifact> {\n  const manifestPath = await resolveManifestPath();\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(await readFile(manifestPath, 'utf8'));\n  } catch (error) {\n    return invalid(\n      `Helper manifest is not valid JSON (${manifestPath}): ${String(error)}`,\n    );\n  }\n  if (typeof parsed !== 'object' || parsed === null) {\n    return invalid(`Helper manifest is not an object (${manifestPath})`);\n  }\n  const manifest = parsed as Record<string, unknown>;\n\n  const packageName = requireString(manifest.packageName, 'packageName');\n  if (packageName !== HELPER_PACKAGE) {\n    invalid(\n      `Helper manifest packageName \"${packageName}\" does not match the ` +\n        `expected \"${HELPER_PACKAGE}\"`,\n    );\n  }\n\n  const assetName = requireString(manifest.assetName, 'assetName');\n  const sha256 = requireString(manifest.sha256, 'sha256');\n  const apkPath = join(HELPER_APK_DIR, assetName);\n\n  const actualSha256 = await sha256File(apkPath).catch(() =>\n    invalid(`Helper APK is missing or unreadable (${apkPath})`),\n  );\n  if (actualSha256 !== sha256.toLowerCase()) {\n    invalid(\n      `Helper APK digest does not match its manifest (${apkPath}). ` +\n        'The bundled artifact may be corrupt or tampered with.',\n    );\n  }\n\n  return {\n    version: requireString(manifest.version, 'version'),\n    versionCode: requireInt(manifest.versionCode, 'versionCode'),\n    packageName,\n    instrumentationRunner: requireString(\n      manifest.instrumentationRunner,\n      'instrumentationRunner',\n    ),\n    apkPath,\n    sha256: sha256.toLowerCase(),\n    signerSha256: requireString(\n      manifest.signerSha256,\n      'signerSha256',\n    ).toLowerCase(),\n    minSdk: requireInt(manifest.minSdk, 'minSdk'),\n  };\n}\n"]}

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

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UntrustedHelperError = exports.SnapshotHelperError = void 0;
+exports.isUntrustedHelperError = isUntrustedHelperError;
+/**
+ * A generic, recoverable snapshot-helper failure. Callers in `auto` mode may
+ * fall back to `uiautomator dump` after catching one of these.
+ */
+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);
+    }
+}
+exports.SnapshotHelperError = SnapshotHelperError;
+/**
+ * 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.
+ */
+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);
+    }
+}
+exports.UntrustedHelperError = UntrustedHelperError;
+/**
+ * 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}.
+ */
+function isUntrustedHelperError(error) {
+    return error instanceof UntrustedHelperError;
+}
+//# sourceMappingURL=errors.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.cjs","sourceRoot":"","sources":["../../../src/backends/android-instrumentation/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AA+EH,wDAIC;AA3ED;;;GAGG;AACH,MAAa,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;AAnBD,kDAmBC;AAED;;;;;;GAMG;AACH,MAAa,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;AA7BD,oDA6BC;AAED;;;;;;;GAOG;AACH,SAAgB,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"]}