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

This commit is contained in:
N0zoM1z0
2026-10-07 11:20:26 +08:00
committed by GitHub
parent 764ff05231
commit 3ed59b2812
13 changed files with 228 additions and 27 deletions
+38 -4
View File
@@ -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."
}
+27 -11
View File
@@ -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.
+4 -2
View File
@@ -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 () => {
+2 -2
View File
@@ -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,
+9
View File
@@ -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);
+9
View File
@@ -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);
+6 -4
View File
@@ -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,
@@ -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",
);
},
);
@@ -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", {
@@ -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", {
@@ -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");
+2 -2
View File
@@ -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({
+2 -2
View File
@@ -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",