Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

refactor: share Android and firmware provider factories (#826)

N0zoM1z03ed59b281247
diff --git a/.oxlintrc.json b/.oxlintrc.json
index fab5b7126..557dfd7c5 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -46,8 +46,14 @@
{
"patterns": [
{
- "group": ["**/ghidra/**", "**/hopper/**", "**/ida/**"],
- "message": "Deep-provider imports belong behind adapters or in the application composition root."
+ "group": [
+ "**/ghidra/**",
+ "**/hopper/**",
+ "**/ida/**",
+ "**/android/**",
+ "**/firmware/**"
+ ],
+ "message": "Provider imports belong behind typed ports or in production composition."
}
]
}
@@ -80,7 +86,8 @@
"**/native/**",
"**/process/**",
"**/reference/**",
- "**/windows/**"
+ "**/windows/**",
+ "**/composition/**"
],
"message": "Domain and contracts depend inward; use typed ports for application, caller and provider boundaries."
}
@@ -89,6 +96,30 @@
]
}
},
+ {
+ "files": ["src/application/**/*.ts"],
+ "excludeFiles": ["src/application/runtime.ts"],
+ "rules": {
+ "no-restricted-imports": [
+ "error",
+ {
+ "patterns": [
+ {
+ "group": [
+ "**/ghidra/**",
+ "**/hopper/**",
+ "**/ida/**",
+ "**/android/**",
+ "**/firmware/**",
+ "**/composition/**"
+ ],
+ "message": "Application workflows use typed ports; production construction belongs in composition."
+ }
+ ]
+ }
+ ]
+ }
+ },
{
"files": ["tests/**/*.ts", "src/**/*.test.ts", "src/**/*.fixture.ts"],
"rules": {
@@ -121,7 +152,10 @@
"**/ida/**",
"**/replay/**",
"**/cli.*",
- "**/main.*"
+ "**/main.*",
+ "**/composition/**",
+ "**/android/**",
+ "**/firmware/**"
],
"message": "Domain tests may import only their owning domain and inward dependencies."
}
diff --git a/docs/capability-migration.md b/docs/capability-migration.md
index e17b700ee..57ce4449a 100644
--- a/docs/capability-migration.md
+++ b/docs/capability-migration.md
@@ -6,17 +6,17 @@ there is no new universal provider interface or fixed module manifest.
## Ownership to preserve
-| Responsibility | Current owner | Migration direction |
-| --------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------- |
-| Analyst semantics and Evidence representation | domain | Keep pure and provider-neutral |
-| Named public input/output contracts | contracts | Keep exact CLI/MCP meaning and complete discovery |
-| Producer parsing and external tool protocols | provider adapters | Keep behind the relevant typed port |
-| Shared analyst workflows | application | Share between CLI and MCP |
-| Concrete provider construction | binary runtime, CLI registrars, MCP startup | Consolidate one capability at a time in production composition |
-| Investigation Evidence and Unknowns | BinarySessionRecords | Extract one composed record owner after caller migration |
-| Target/profile snapshots and invalidation | BinarySessionRecords/BinarySession | Keep binary-owned |
-| Subprocess ownership and host primitives | process/windows | Reuse; preserve cancellation and cleanup |
-| Public translation | CLI/MCP adapters | Delegate to shared workflows and named contracts |
+| Responsibility | Current owner | Migration direction |
+| --------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------- |
+| Analyst semantics and Evidence representation | domain | Keep pure and provider-neutral |
+| Named public input/output contracts | contracts | Keep exact CLI/MCP meaning and complete discovery |
+| Producer parsing and external tool protocols | provider adapters | Keep behind the relevant typed port |
+| Shared analyst workflows | application | Share between CLI and MCP |
+| Concrete provider construction | binary runtime, composition, MCP startup | Consolidate one capability at a time in production composition |
+| Investigation Evidence and Unknowns | BinarySessionRecords | Extract one composed record owner after caller migration |
+| Target/profile snapshots and invalidation | BinarySessionRecords/BinarySession | Keep binary-owned |
+| Subprocess ownership and host primitives | process/windows | Reuse; preserve cancellation and cleanup |
+| Public translation | CLI/MCP adapters | Delegate to shared workflows and named contracts |
Retain exact Evidence IDs, provenance, detached reads, atomic Evidence/Unknown
mutations and optimistic revisions. Preserve current close and failed-cleanup
@@ -77,3 +77,19 @@ verification. Its integration is broader than swapping a provider. The migration
should eliminate incidental duplicate wiring, not erase those design decisions.
Update these examples with real migrated entrypoints before closing #740.
+
+## First production factory migration
+
+`src/composition/android.ts` and `src/composition/firmware.ts` construct providers
+behind the existing AndroidAnalysisPort and FirmwareAnalysisPort. CLI registrars
+pass their selected environment; MCP uses the process environment unless a caller
+injects a port. Each factory call returns a fresh instance and acquires no process,
+workspace or toolchain. Queues, cleanup-failure state and per-request cleanup stay
+inside the provider. The existing launcher seams remain available to boundary
+fixtures, which now exercise the production factories.
+
+Application workflows and MCP registration must not import these concrete
+providers. Composition may import their implementations. Binary composition is
+still at its existing entrypoint while its direct-analysis callers are investigated.
+This concrete pilot does not introduce a shared provider interface or module
+manifest.
diff --git a/src/cli/androidCommands.ts b/src/cli/androidCommands.ts
index ab0bf9d0f..75408786f 100644
--- a/src/cli/androidCommands.ts
+++ b/src/cli/androidCommands.ts
@@ -1,6 +1,6 @@
import { z } from "incur";
import { AndroidAnalysisService } from "../application/AndroidAnalysisService.js";
-import { JadxProvider } from "../android/JadxProvider.js";
+import { createAndroidAnalysisProvider } from "../composition/android.js";
import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
@@ -15,7 +15,9 @@ export const registerAndroidCommands = (
logger: Logger,
environment: Readonly<Record<string, string | undefined>>,
): void => {
- const service = new AndroidAnalysisService(new JadxProvider(environment));
+ const service = new AndroidAnalysisService(
+ createAndroidAnalysisProvider(environment),
+ );
const execute = (name: string, operation: AndroidOperation, input: unknown) =>
withCommandCancellation((signal) =>
logCliCommand(logger, name, async () => {
diff --git a/src/cli/firmwareCommands.ts b/src/cli/firmwareCommands.ts
index 6ed6d7fdf..dcaf9f6f4 100644
--- a/src/cli/firmwareCommands.ts
+++ b/src/cli/firmwareCommands.ts
@@ -1,6 +1,6 @@
import { z } from "incur";
import { FirmwareAnalysisService } from "../application/FirmwareAnalysisService.js";
-import { FirmwareProvider } from "../firmware/FirmwareProvider.js";
+import { createFirmwareAnalysisProvider } from "../composition/firmware.js";
import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
@@ -16,7 +16,7 @@ export const registerFirmwareCommands = (
environment: Readonly<Record<string, string | undefined>>,
): void => {
const service = new FirmwareAnalysisService(
- new FirmwareProvider(environment),
+ createFirmwareAnalysisProvider(environment),
);
const execute = (
name: string,
diff --git a/src/composition/android.ts b/src/composition/android.ts
new file mode 100644
index 000000000..c9d504be5
--- /dev/null
+++ b/src/composition/android.ts
@@ -0,0 +1,9 @@
+import type { AndroidAnalysisPort } from "../application/AndroidAnalysisPort.js";
+import type { JadxLauncher } from "../android/JadxMcpTransport.js";
+import { JadxProvider } from "../android/JadxProvider.js";
+
+/** Construct one APK provider with its own queue and cleanup-failure state. */
+export const createAndroidAnalysisProvider = (
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+ launcher?: JadxLauncher,
+): AndroidAnalysisPort => new JadxProvider(environment, launcher);
diff --git a/src/composition/firmware.ts b/src/composition/firmware.ts
new file mode 100644
index 000000000..d2cca7dd9
--- /dev/null
+++ b/src/composition/firmware.ts
@@ -0,0 +1,9 @@
+import type { FirmwareAnalysisPort } from "../application/FirmwareAnalysisPort.js";
+import type { FirmwareLauncher } from "../firmware/FirmwareCommand.js";
+import { FirmwareProvider } from "../firmware/FirmwareProvider.js";
+
+/** Construct one firmware provider without launching or acquiring an engine. */
+export const createFirmwareAnalysisProvider = (
+ environment: Readonly<Record<string, string | undefined>> = process.env,
+ launcher?: FirmwareLauncher,
+): FirmwareAnalysisPort => new FirmwareProvider(environment, launcher);
diff --git a/src/server/createServer.ts b/src/server/createServer.ts
index 22cdfb5f7..f75187629 100644
--- a/src/server/createServer.ts
+++ b/src/server/createServer.ts
@@ -22,11 +22,11 @@ import { registerManagedTools } from "./registerManagedTools.js";
import { registerFirmwareTools } from "./registerFirmwareTools.js";
import { FirmwareAnalysisService } from "../application/FirmwareAnalysisService.js";
import type { FirmwareAnalysisPort } from "../application/FirmwareAnalysisPort.js";
-import { FirmwareProvider } from "../firmware/FirmwareProvider.js";
+import { createFirmwareAnalysisProvider } from "../composition/firmware.js";
import { registerAndroidTools } from "./registerAndroidTools.js";
import { AndroidAnalysisService } from "../application/AndroidAnalysisService.js";
import type { AndroidAnalysisPort } from "../application/AndroidAnalysisPort.js";
-import { JadxProvider } from "../android/JadxProvider.js";
+import { createAndroidAnalysisProvider } from "../composition/android.js";
import { registerManagedWorkflowTools } from "./registerManagedWorkflowTools.js";
import { registerNativeTools } from "./registerNativeTools.js";
import { registerOfficialTools } from "./registerOfficialTools.js";
@@ -137,14 +137,16 @@ export const createServer = (
registerBinaryAnalysisTools(toolContext);
registerAndroidTools(
server,
- new AndroidAnalysisService(options.androidAnalysis ?? new JadxProvider()),
+ new AndroidAnalysisService(
+ options.androidAnalysis ?? createAndroidAnalysisProvider(),
+ ),
toolLogger,
recordEvidence,
);
registerFirmwareTools(
server,
new FirmwareAnalysisService(
- options.firmwareAnalysis ?? new FirmwareProvider(),
+ options.firmwareAnalysis ?? createFirmwareAnalysisProvider(),
),
toolLogger,
recordEvidence,
diff --git a/tests/acceptance/nonBinaryComposition.test.ts b/tests/acceptance/nonBinaryComposition.test.ts
new file mode 100644
index 000000000..b15c9d316
--- /dev/null
+++ b/tests/acceptance/nonBinaryComposition.test.ts
@@ -0,0 +1,88 @@
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { expect, onTestFinished } from "vitest";
+
+import { createAndroidAnalysisProvider } from "../../src/composition/android.js";
+import { createFirmwareAnalysisProvider } from "../../src/composition/firmware.js";
+import { createServer } from "../../src/server/createServer.js";
+import { createTestBinarySession } from "../fixtures/binarySession.js";
+import { writeOrderedZip } from "../fixtures/artifactEntryOrder.js";
+import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";
+import { cliTest } from "../support/cli/cliFixture.js";
+
+const connect = async (environment: NodeJS.ProcessEnv) => {
+ const session = createTestBinarySession(() => {
+ throw new Error("Target-free analysis must not acquire a deep provider");
+ });
+ const server = createServer(session, session, {
+ androidAnalysis: createAndroidAnalysisProvider(environment),
+ firmwareAnalysis: createFirmwareAnalysisProvider(environment),
+ });
+ const client = new Client({ name: "composition-parity", version: "1" });
+ onTestFinished(async () => {
+ await client.close();
+ await server.close();
+ await session.close();
+ });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+ return client;
+};
+
+cliTest.skipIf(process.platform === "win32")(
+ "preserves the selected APK configuration through the compiled CLI and MCP factories",
+ async ({ cli }) => {
+ const root = await createTestTempDirectory("rea-android-composition-");
+ const apk = join(root, "fixture.apk");
+ await writeOrderedZip(apk, ["AndroidManifest.xml", "classes.dex"]);
+ const environment = {
+ REA_LOG_LEVEL: "silent",
+ JAVA_HOME: "relative-fixture-jdk",
+ };
+ const cliResult = await cli.run({
+ arguments: ["inspect-android-package", apk, "--json"],
+ environment,
+ timeoutMs: 10_000,
+ });
+ expect(cliResult.exitCode).toBe(1);
+ expect(cliResult.json).toMatchObject({ code: "capability_unavailable" });
+ const client = await connect(environment);
+ const response = await client.callTool({
+ name: "inspect_android_package",
+ arguments: { path: apk },
+ });
+ expect(response.isError).toBe(true);
+ expect(response.structuredContent).toEqual({ error: cliResult.json });
+ expect(JSON.stringify(response.structuredContent)).toContain("JAVA_HOME");
+ },
+);
+
+cliTest.skipIf(process.platform !== "linux")(
+ "preserves the missing firmware command reason through both caller paths",
+ async ({ cli }) => {
+ const root = await createTestTempDirectory("rea-firmware-composition-");
+ const path = join(root, "input.bin");
+ await writeFile(path, "firmware fixture");
+ const environment = { REA_LOG_LEVEL: "silent" };
+ const cliResult = await cli.run({
+ arguments: ["inspect-firmware-regions", path, "--json"],
+ environment,
+ timeoutMs: 10_000,
+ });
+ expect(cliResult.exitCode).toBe(1);
+ expect(cliResult.json).toMatchObject({ code: "capability_unavailable" });
+ const client = await connect(environment);
+ const response = await client.callTool({
+ name: "inspect_firmware_regions",
+ arguments: { path },
+ });
+ expect(response.isError).toBe(true);
+ expect(response.structuredContent).toEqual({ error: cliResult.json });
+ expect(JSON.stringify(response.structuredContent)).toContain(
+ "REA_BINWALK_COMMAND",
+ );
+ },
+);
diff --git a/tests/boundary/android/jadxIntegration.test.ts b/tests/boundary/android/jadxIntegration.test.ts
index efac82772..78df3d72c 100644
--- a/tests/boundary/android/jadxIntegration.test.ts
+++ b/tests/boundary/android/jadxIntegration.test.ts
@@ -11,6 +11,23 @@ import {
const it = test.skipIf(process.platform === "win32");
+it("does not carry a factory instance's cleanup failure into another instance", async () => {
+ const failed = await setup("cleanup-failure");
+ const healthy = await setup();
+ const failure = await failed.service.execute("inspect_android_package", {
+ path: failed.apk,
+ });
+ expect(failure).toMatchObject({
+ ok: false,
+ error: { cleanupIncomplete: true },
+ });
+ const result = await healthy.service.execute("inspect_android_package", {
+ path: healthy.apk,
+ });
+ expect(result.ok).toBe(true);
+ await verifyCleanup(healthy.launches);
+});
+
it("retains APK identity, original input, raw producer data and normalized observations", async () => {
const { service, apk, launches } = await setup();
const outcome = await service.execute("inspect_android_package", {
diff --git a/tests/boundary/firmware/firmwareIntegration.test.ts b/tests/boundary/firmware/firmwareIntegration.test.ts
index a10e82f9a..25a85a665 100644
--- a/tests/boundary/firmware/firmwareIntegration.test.ts
+++ b/tests/boundary/firmware/firmwareIntegration.test.ts
@@ -13,6 +13,23 @@ import { toCallToolResult } from "../../../src/server/toolResult.js";
const it = test.skipIf(process.platform !== "linux");
+it("keeps cleanup-failure state local to the selected factory instance", async () => {
+ const failed = await firmwareFixture("cleanup-failure");
+ const healthy = await firmwareFixture();
+ const failure = await failed.service.execute("inspect_firmware_regions", {
+ path: failed.path,
+ });
+ expect(failure).toMatchObject({
+ ok: false,
+ error: { cleanupIncomplete: true },
+ });
+ const result = await healthy.service.execute("inspect_firmware_regions", {
+ path: healthy.path,
+ });
+ expect(result.ok).toBe(true);
+ await assertFirmwareCleanup(healthy.launches);
+});
+
it("binds region observations to exact bytes and preserves provider-reported uncertainty", async () => {
const fixture = await firmwareFixture();
const result = await fixture.service.execute("inspect_firmware_regions", {
diff --git a/tests/evaluation/moduleBoundaries.test.ts b/tests/evaluation/moduleBoundaries.test.ts
index 2ef304015..8796c4873 100644
--- a/tests/evaluation/moduleBoundaries.test.ts
+++ b/tests/evaluation/moduleBoundaries.test.ts
@@ -11,10 +11,17 @@ describe("incremental module import boundaries", () => {
["src/domain/probe.ts", "../browser/Provider.js", false],
["src/contracts/probe.ts", "../android/Provider.js", false],
["src/contracts/probe.ts", "../cli.js", false],
+ ["src/contracts/probe.ts", "../composition/android.js", false],
+ ["src/domain/probe.test.ts", "../composition/firmware.js", false],
+ ["src/application/probe.ts", "../android/JadxProvider.js", false],
+ ["src/application/probe.ts", "../composition/android.js", false],
+ ["src/server/probe.ts", "../firmware/FirmwareProvider.js", false],
["src/domain/probe.ts", "./result.js", true],
["src/contracts/probe.ts", "../domain/result.js", true],
["src/application/probe.ts", "../domain/result.js", true],
["src/composition/probe.ts", "../ghidra/Provider.js", true],
+ ["src/composition/probe.ts", "../android/JadxProvider.js", true],
+ ["src/composition/probe.ts", "../firmware/FirmwareProvider.js", true],
])("checks %s importing %s", async (file, dependency, allowed) => {
const temporary = await createTestTempDirectory("rea-module-boundary-");
const config = join(temporary, ".oxlintrc.json");
diff --git a/tests/fixtures/android/jadx.ts b/tests/fixtures/android/jadx.ts
index 236b5260d..e1662f4e4 100644
--- a/tests/fixtures/android/jadx.ts
+++ b/tests/fixtures/android/jadx.ts
@@ -3,7 +3,7 @@ import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { expect, onTestFinished } from "vitest";
import { AndroidAnalysisService } from "../../../src/application/AndroidAnalysisService.js";
-import { JadxProvider } from "../../../src/android/JadxProvider.js";
+import { createAndroidAnalysisProvider } from "../../../src/composition/android.js";
import {
ProviderProcessSupervisor,
spawnOwnedProviderProcess,
@@ -26,7 +26,7 @@ export const createJadxProtocolFixture = async (mode = "normal") => {
cwd: string | undefined;
pid: number | undefined;
}[] = [];
- const provider = new JadxProvider(
+ const provider = createAndroidAnalysisProvider(
{ ...process.env, REA_JADX_MCP_JAR: jar },
async (options) => {
const spawned = await spawnOwnedProviderProcess({
diff --git a/tests/fixtures/firmware/provider.ts b/tests/fixtures/firmware/provider.ts
index cb036e0f4..81007923f 100644
--- a/tests/fixtures/firmware/provider.ts
+++ b/tests/fixtures/firmware/provider.ts
@@ -2,7 +2,7 @@ import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { access, rm, writeFile } from "node:fs/promises";
import { expect, onTestFinished } from "vitest";
-import { FirmwareProvider } from "../../../src/firmware/FirmwareProvider.js";
+import { createFirmwareAnalysisProvider } from "../../../src/composition/firmware.js";
import { FirmwareAnalysisService } from "../../../src/application/FirmwareAnalysisService.js";
import { spawnOwnedProviderProcess } from "../../../src/process/ProviderProcess.js";
import { createTestTempDirectory } from "../temporaryDirectory.js";
@@ -18,7 +18,7 @@ export const firmwareFixture = async (mode = "normal") => {
pid: number | undefined;
args: readonly string[];
}[] = [];
- const provider = new FirmwareProvider(
+ const provider = createFirmwareAnalysisProvider(
{
...process.env,
REA_BINWALK_COMMAND: "/usr/bin/true",