Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(android): validate engine archive prerequisites (#1145)
Ysopwnablee9ebfb94eff0
diff --git a/docs/android-analysis.md b/docs/android-analysis.mdindex 4251b763a..9b2975138 100644--- a/docs/android-analysis.md+++ b/docs/android-analysis.md@@ -23,6 +23,14 @@ export REA_JADX_MCP_JAR=/absolute/path/jadx-headless-mcp-0.7.1-all.jarexport JAVA_HOME=/absolute/path/existing-jdk```+Readiness checks the selected JAR's ZIP directory for the classes consumed by+REA's metadata bridge, as well as Java's compiler and version modules. It does+not load an APK or execute engine code. Invalid archives and missing bridge+classes report JAR-specific recovery; classpath inventory alone does not prove+that every class or engine operation will load successfully. Discovery limits+each ZIP metadata read to 8 MiB before allocation; a larger directory reports+the exhausted read budget and the selected JAR path.+The current metadata bridge is verified on macOS arm64 with OpenJDK 21 and thepublic Appium ApiDemos fixture. The POSIX adapter also supports Linux; the newbridge has not yet undergone real verification on Linux/JDK 25.diff --git a/scripts/verify/android/failure-recovery.mjs b/scripts/verify/android/failure-recovery.mjsindex 9b1c10be2..42f241d38 100644--- a/scripts/verify/android/failure-recovery.mjs+++ b/scripts/verify/android/failure-recovery.mjs@@ -1,5 +1,12 @@import assert from "node:assert/strict";-import { access, mkdtemp, mkdir, rm, symlink } from "node:fs/promises";+import {+ access,+ mkdtemp,+ mkdir,+ rm,+ symlink,+ writeFile,+} from "node:fs/promises";import { tmpdir } from "node:os";import { delimiter, dirname, isAbsolute, join } from "node:path";import { Client } from "@modelcontextprotocol/client";@@ -67,6 +74,8 @@ export async function verifyAndroidFailureRecovery({}const withoutJavaHome = { ...environment };delete withoutJavaHome.JAVA_HOME;+ const invalidJar = join(root, "invalid.jar");+ await writeFile(invalidJar, "not a Java archive");const environments = [{label: "JRE without compiler",@@ -78,6 +87,12 @@ export async function verifyAndroidFailureRecovery({env: { ...withoutJavaHome, PATH: empty },observation: "ENOENT",},+ {+ label: "invalid engine archive with a working JDK",+ env: { ...environment, REA_JADX_MCP_JAR: invalidJar },+ observation: "Cannot inspect REA_JADX_MCP_JAR",+ jarFailure: true,+ },];if (process.platform === "darwin") {// /usr/bin/java either resolves an installed runtime or reports the actual stub failure.@@ -114,8 +129,16 @@ export async function verifyAndroidFailureRecovery({JSON.stringify(failure).includes(scenario.observation),JSON.stringify(failure),);- assert.match(failure.message, /full JDK/u);- assert.match(failure.remediation.action, /java --list-modules/u);+ assert.match(+ failure.message,+ scenario.jarFailure ? /REA_JADX_MCP_JAR/u : /full JDK/u,+ );+ assert.match(+ failure.remediation.action,+ scenario.jarFailure ? /jadx-headless-mcp/u : /java --list-modules/u,+ );+ if (scenario.jarFailure)+ assert.doesNotMatch(failure.message, /Select a full JDK/u);assert.doesNotMatch(JSON.stringify(failure), /rea doctor/u);await verifyAndroidReadiness({entrypoint,diff --git a/src/android/JadxConfiguration.ts b/src/android/JadxConfiguration.tsindex f423bf228..4eb7654ee 100644--- a/src/android/JadxConfiguration.ts+++ b/src/android/JadxConfiguration.ts@@ -5,6 +5,7 @@ import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.import type { AndroidOperation } from "../domain/android/androidAnalysis.js";import type { JsonValue } from "../domain/jsonValue.js";import type { ProviderAvailability } from "../application/AnalysisProvider.js";+import { ZipArtifactReader } from "../artifacts/ZipArtifactReader.js";import {execFileOutput,execFileOutputFailure,@@ -13,6 +14,9 @@ import { JADX_JAR_CONFIGURATION_REMEDIATION } from "./JadxRelease.js";const JAVA_MODULE_LISTING_TIMEOUT_MS = 10_000;const JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES = 1024 * 1024;+// Bound ZIP metadata allocation during discovery. The audited 0.7.1 JAR's+// central directory occupies 2,294,350 bytes; class bodies are not read here.+const JAR_METADATA_READ_MAX_BYTES = 8 * 1024 * 1024;/** Caller-supplied tools, resolved only when an Android operation is selected. */export interface JadxConfiguration {@@ -116,9 +120,53 @@ const readJadxConfiguration = async (await requireJavaHomeExecutable(environment.JAVA_HOME, java);const jvmArguments = resolveJvmArguments(environment);await inspectJavaRuntime(java, environment, signal);+ await requireEngineArchive(jar, signal);return { jar, java, jvmArguments };};+const requireEngineArchive = async (+ jar: string,+ signal?: AbortSignal,+): Promise<void> => {+ // These classes are consumed directly by ReaJadxBridge.java. This checks the+ // classpath inventory without loading engine code or starting a JADX session.+ const missing = new Set([+ "com/atxx/jhmcp/JadxSession.class",+ "com/atxx/jhmcp/SessionHolder.class",+ "jadx/api/JadxDecompiler.class",+ "com/google/gson/Gson.class",+ "io/modelcontextprotocol/kotlin/sdk/server/Server.class",+ ]);+ const reader = new ZipArtifactReader(jar, "zip", JAR_METADATA_READ_MAX_BYTES);+ try {+ for await (const entry of reader.entries(signal)) {+ if (entry.kind === "file" && !entry.encrypted) missing.delete(entry.path);+ if (missing.size === 0) return;+ }+ } catch (cause) {+ if (signal?.aborted === true) throw cause;+ const reason = cause instanceof Error ? cause.message : String(cause);+ throw configurationFailure(+ "version_unresolved",+ `Cannot inspect REA_JADX_MCP_JAR ${jar} as a Java archive: ${reason}. ${JADX_JAR_CONFIGURATION_REMEDIATION}`,+ {+ jar_path: jar,+ phase: "jar-inspection",+ archive_error: reason,+ maximum_metadata_read_bytes: JAR_METADATA_READ_MAX_BYTES,+ },+ cause,+ );+ } finally {+ await reader.close();+ }+ throw configurationFailure(+ "unsupported_version",+ `REA_JADX_MCP_JAR ${jar} does not contain the required metadata bridge classes: ${[...missing].join(", ")}. ${JADX_JAR_CONFIGURATION_REMEDIATION}`,+ { jar_path: jar, phase: "jar-inspection", missing_classes: [...missing] },+ );+};+const requireSupportedHost = (): void => {if (process.platform === "linux" || process.platform === "darwin") return;throw configurationFailure(diff --git a/src/artifacts/ZipArtifactReader.ts b/src/artifacts/ZipArtifactReader.tsindex 8dd4471bd..3c7a92ea1 100644--- a/src/artifacts/ZipArtifactReader.ts+++ b/src/artifacts/ZipArtifactReader.ts@@ -14,7 +14,10 @@ import type { ZipPackageFormat } from "../domain/zipPackageFormat.js";class NodeFileReader extends Reader<string> {#handle: FileHandle | undefined;- constructor(private readonly path: string) {+ constructor(+ private readonly path: string,+ private readonly maximumReadBytes?: number,+ ) {super(path);}@@ -29,7 +32,16 @@ class NodeFileReader extends Reader<string> {): Promise<Uint8Array> {const handle = this.#handle;if (handle === undefined) throw new Error("ZIP reader is not initialized");- const bytes = Buffer.alloc(Math.min(length, this.size - index));+ const readBytes = Math.min(length, this.size - index);+ if (+ this.maximumReadBytes !== undefined &&+ readBytes > this.maximumReadBytes+ )+ throw new ArtifactReaderFailure(+ "limit",+ `ZIP metadata read requires ${readBytes} bytes, exceeding the ${this.maximumReadBytes}-byte read budget`,+ );+ const bytes = Buffer.alloc(readBytes);const read = await handle.read(bytes, 0, bytes.length, index);return bytes.subarray(0, read.bytesRead);}@@ -47,9 +59,14 @@ export class ZipArtifactReader implements ArtifactReader {readonly #reader: ZipReader<string>;readonly #entries = new Map<string, Entry>();- constructor(path: string, format: ZipPackageFormat) {+ /** Optionally bound each metadata read before allocating its backing buffer. */+ constructor(+ path: string,+ format: ZipPackageFormat,+ maximumMetadataReadBytes?: number,+ ) {this.format = format;- this.#source = new NodeFileReader(path);+ this.#source = new NodeFileReader(path, maximumMetadataReadBytes);this.#reader = new ZipReader(this.#source, {checkSignature: true,checkOverlappingEntry: true,diff --git a/tests/boundary/android/jadxConfiguration.test.ts b/tests/boundary/android/jadxConfiguration.test.tsindex 0f6a8654a..f9072b149 100644--- a/tests/boundary/android/jadxConfiguration.test.ts+++ b/tests/boundary/android/jadxConfiguration.test.ts@@ -9,14 +9,40 @@ import {} from "../../../src/android/JadxConfiguration.js";import { AnalysisCapabilityUnavailableError } from "../../../src/domain/analysisErrorCore.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { writeOrderedZip } from "../../fixtures/artifactEntryOrder.js";+import { writeJadxJarInventory } from "../../fixtures/android/jadxJar.js";const it = test.skipIf(process.platform === "win32");+it("rejects malformed or unrelated engine archives with JAR-specific recovery", async () => {+ const root = await createTestTempDirectory("rea-jadx-invalid-jar-");+ const javaHome = await createFakeJdk(root);+ const jar = join(root, "engine.jar");+ for (const malformed of [true, false]) {+ if (malformed) await writeFile(jar, "not a Java archive");+ else await writeOrderedZip(jar, ["unrelated/Library.class"]);+ const environment = { REA_JADX_MCP_JAR: jar, JAVA_HOME: javaHome };+ const availability = await inspectJadxAvailability(environment);+ expect(availability).toMatchObject({+ status: "unavailable",+ reason: expect.stringContaining("REA_JADX_MCP_JAR"),+ diagnostics: { jar_path: await realpath(jar), phase: "jar-inspection" },+ });+ await expect(+ resolveJadxConfiguration(environment, "inspect_android_package"),+ ).rejects.toMatchObject({+ _tag: "AnalysisCapabilityUnavailableError",+ reason: expect.stringContaining("REA_JADX_MCP_JAR"),+ });+ expect(availability.reason).not.toContain("Select a full JDK");+ }+});+it("rejects an explicit JAVA_HOME without an executable java binary", async () => {const root = await createTestTempDirectory("rea-jadx-config-");const jar = join(root, "jadx-headless-mcp.jar");const javaHome = join(root, "missing-jdk");- await writeFile(jar, "fixture jar");+ await writeJadxJarInventory(jar);await expect(resolveJadxConfiguration(@@ -33,7 +59,7 @@ it("accepts a full JDK and canonicalizes the selected JAR", async () => {const root = await createTestTempDirectory("rea-jadx-config-");const jar = join(root, "jadx-headless-mcp.jar");const javaHome = await createFakeJdk(root);- await writeFile(jar, "fixture jar");+ await writeJadxJarInventory(jar);await expect(resolveJadxConfiguration(@@ -51,7 +77,7 @@ it("configures heap and visible processors independently without forcing either"const root = await createTestTempDirectory("rea-jadx-config-");const jar = join(root, "engine.jar");const javaHome = await createFakeJdk(root);- await writeFile(jar, "fixture jar");+ await writeJadxJarInventory(jar);const configuration = await resolveJadxConfiguration({REA_JADX_MCP_JAR: jar,@@ -98,7 +124,7 @@ it("configures heap and visible processors independently without forcing either"it("distinguishes a runnable JRE from a missing Java executable", async () => {const root = await createTestTempDirectory("rea-jadx-runtime-");const jar = join(root, "jadx-headless-mcp.jar");- await writeFile(jar, "fixture jar");+ await writeJadxJarInventory(jar);const jreHome = await createFakeJdk(root, false);await expect(resolveJadxConfiguration(@@ -142,7 +168,7 @@ it("preserves exact Java probe output and marks max-buffer capture as truncated"const bin = join(javaHome, "bin");const java = join(bin, "java");await mkdir(bin, { recursive: true });- await writeFile(jar, "fixture jar");+ await writeJadxJarInventory(jar);await writeFile(java,`#!/bin/sh\nexec ${process.execPath} -e 'process.stdout.write("x".repeat(2 * 1024 * 1024))'\n`,@@ -186,7 +212,7 @@ it("preserves exact Java probe output and marks max-buffer capture as truncated"it("distinguishes an unreported Java version from an unsupported old version", async () => {const root = await createTestTempDirectory("rea-jadx-version-listing-");const jar = join(root, "jadx-headless-mcp.jar");- await writeFile(jar, "fixture jar");+ await writeJadxJarInventory(jar);const unresolvedHome = await createFakeJdk(root);await writeFile(@@ -233,7 +259,7 @@ it("cancels an in-flight Java readiness probe", async () => {const java = join(bin, "java");const marker = join(root, "java-probe-started");await mkdir(bin, { recursive: true });- await writeFile(jar, "fixture jar");+ await writeJadxJarInventory(jar);await writeFile(java,`#!/bin/sh\nexec ${process.execPath} -e 'require("node:fs").writeFileSync(process.argv[1], "ready"); setTimeout(() => {}, 30_000)' '${marker}'\n`,@@ -269,7 +295,7 @@ it("reports a killed Java probe as unresolved instead of missing runtime", asyncconst java = join(bin, "java");const marker = join(root, "java-probe-started");await mkdir(bin, { recursive: true });- await writeFile(jar, "fixture jar");+ await writeJadxJarInventory(jar);await writeFile(java,`#!/bin/sh\nexec ${process.execPath} -e 'require("node:fs").writeFileSync(process.argv[1], "ready"); setTimeout(() => {}, 30_000)' '${marker}'\n`,diff --git a/tests/boundary/filesystem/artifactZipIntegrity.test.ts b/tests/boundary/filesystem/artifactZipIntegrity.test.tsindex 10b221819..61b6b47c4 100644--- a/tests/boundary/filesystem/artifactZipIntegrity.test.ts+++ b/tests/boundary/filesystem/artifactZipIntegrity.test.ts@@ -9,8 +9,32 @@ import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";import { parseBinaryTarget } from "../../../src/application/BinaryTargetResolver.js";import { ArtifactProvider } from "../../../src/artifacts/ArtifactProvider.js";+import { ZipArtifactReader } from "../../../src/artifacts/ZipArtifactReader.js";import { artifactInventoryResultSchema } from "../../../src/domain/artifactGraph.js";+it("bounds a requested metadata read without rejecting the underlying valid ZIP", async () => {+ const root = await createTestTempDirectory("rea-zip-metadata-budget-");+ const path = join(root, "large-directory.zip");+ const name = `${"a".repeat(8192)}.class`;+ await writeOrderedZip(path, [name]);+ const bounded = new ZipArtifactReader(path, "zip", 4096);+ const control = new ZipArtifactReader(path, "zip");+ const collect = async (reader: ZipArtifactReader): Promise<string[]> => {+ const names: string[] = [];+ for await (const entry of reader.entries()) names.push(entry.path);+ return names;+ };+ try {+ await expect(collect(bounded)).rejects.toMatchObject({+ reason: "limit",+ message: expect.stringContaining("4096-byte read budget"),+ });+ await expect(collect(control)).resolves.toEqual([name]);+ } finally {+ await Promise.all([bounded.close(), control.close()]);+ }+});+it("rejects overlapping ZIP member data ranges through artifact inventory", async () => {const root = await createTestTempDirectory("rea-zip-overlap-");const path = join(root, "overlap.zip");diff --git a/tests/boundary/process/jadxIntegration.test.ts b/tests/boundary/process/jadxIntegration.test.tsindex a4c993847..bd83345b8 100644--- a/tests/boundary/process/jadxIntegration.test.ts+++ b/tests/boundary/process/jadxIntegration.test.ts@@ -13,6 +13,7 @@ import {createJadxProtocolFixture as setup,verifyJadxFixtureCleanup as verifyCleanup,} from "../../fixtures/android/jadx.js";+import { writeJadxJarInventory } from "../../fixtures/android/jadxJar.js";const it = test.skipIf(process.platform === "win32");@@ -104,7 +105,7 @@ it("retire sessions when APK bytes, engine bytes or JVM options change", async (const changed = await inspect();expect(changed.subject?.digest.sha256).not.toBe(first.subject?.digest.sha256);await verifyCleanup(launches.slice(0, 1));- await writeFile(jar, "new engine bytes");+ await writeJadxJarInventory(jar, ["fixture/NewEngineMarker.class"]);await inspect();environment.JAVA_TOOL_OPTIONS = "-Xmx8g";environment._JAVA_OPTIONS = "-XX:+UseG1GC";diff --git a/tests/fixtures/android/jadx.ts b/tests/fixtures/android/jadx.tsindex a537ed476..7ae21e776 100644--- a/tests/fixtures/android/jadx.ts+++ b/tests/fixtures/android/jadx.ts@@ -12,6 +12,7 @@ import {import { cleanupOwnedProcessGroup } from "../../../src/process/ProcessOwnership.js";import { writeOrderedZip } from "../artifactEntryOrder.js";import { createTestTempDirectory } from "../temporaryDirectory.js";+import { writeJadxJarInventory } from "./jadxJar.js";const fixture = fileURLToPath(new URL("./jadx-mcp.mjs", import.meta.url));@@ -30,7 +31,7 @@ export const createJadxProtocolFixture = async (mode = "normal") => {);await chmod(java, 0o755);await writeOrderedZip(apk, ["AndroidManifest.xml", "classes.dex"]);- await writeFile(jar, "synthetic engine bytes; not a Java archive");+ await writeJadxJarInventory(jar);const launches: {runId: string;cwd: string | undefined;diff --git a/tests/fixtures/android/jadxJar.ts b/tests/fixtures/android/jadxJar.tsnew file mode 100644index 000000000..1d7257b3f--- /dev/null+++ b/tests/fixtures/android/jadxJar.ts@@ -0,0 +1,15 @@+import { writeOrderedZip } from "../artifactEntryOrder.js";++/** ZIP classpath inventory for synthetic protocol tests; not executable bytecode. */+export const writeJadxJarInventory = (+ path: string,+ extraEntries: readonly string[] = [],+): Promise<void> =>+ writeOrderedZip(path, [+ "com/atxx/jhmcp/JadxSession.class",+ "com/atxx/jhmcp/SessionHolder.class",+ "jadx/api/JadxDecompiler.class",+ "com/google/gson/Gson.class",+ "io/modelcontextprotocol/kotlin/sdk/server/Server.class",+ ...extraEntries,+ ]);