From 3ed59b281247f2180b3c79e658078507e4cc1be2 Mon Sep 17 00:00:00 2001 From: N0zoM1z0 <161784452+N0zoM1z0@users.noreply.github.com> Date: Wed, 7 Oct 2026 11:20:26 +0800 Subject: [PATCH] refactor: share Android and firmware provider factories (#826) --- .oxlintrc.json | 42 ++++++++- docs/capability-migration.md | 38 +++++--- src/cli/androidCommands.ts | 6 +- src/cli/firmwareCommands.ts | 4 +- src/composition/android.ts | 9 ++ src/composition/firmware.ts | 9 ++ src/server/createServer.ts | 10 ++- tests/acceptance/nonBinaryComposition.test.ts | 88 +++++++++++++++++++ .../boundary/android/jadxIntegration.test.ts | 17 ++++ .../firmware/firmwareIntegration.test.ts | 17 ++++ tests/evaluation/moduleBoundaries.test.ts | 7 ++ tests/fixtures/android/jadx.ts | 4 +- tests/fixtures/firmware/provider.ts | 4 +- 13 files changed, 228 insertions(+), 27 deletions(-) create mode 100644 src/composition/android.ts create mode 100644 src/composition/firmware.ts create mode 100644 tests/acceptance/nonBinaryComposition.test.ts 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>, ): 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>, ): 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> = 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> = 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",