Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(target): explain static WASM inspection after native rejection
SII-YDD1f17ac82282d
diff --git a/docs/wasm-artifacts.md b/docs/wasm-artifacts.mdindex 5289976a7..21e2735a0 100644--- a/docs/wasm-artifacts.md+++ b/docs/wasm-artifacts.md@@ -4,6 +4,15 @@local WASM bytes using caller-supplied WABT 1.0.42. No active binary target isrequired. REA does not install tools or fetch artifacts and does not execute WASM.+`open_binary` is not the WASM inspection route. A recognized WASM v1 header+returns `target_unavailable` with category `unsupported_target` and constraint+`wasm_requires_static_inspection`, including the selected path in a valid+`inspect_wasm_artifact` call. Use that target-free tool or+`rea inspect-wasm-artifact <path> --format json` with the toolchain below.+Check `binary_session` for configured capability availability. A recognized+header is not validation of the complete module; missing WABT is reported+separately as an unavailable capability, not as missing native engine support.+Set `REA_WABT_BIN_DIRECTORY` to an absolute directory containing executable`wasm-validate`, `wasm-objdump` and `wasm2wat` (with `.exe` on Windows). Missingexecutables, unsupported banners and inaccessible tools produce actionablediff --git a/src/application/BinaryTargetResolver.ts b/src/application/BinaryTargetResolver.tsindex ca8a4ab73..9e0f5274c 100644--- a/src/application/BinaryTargetResolver.ts+++ b/src/application/BinaryTargetResolver.ts@@ -247,6 +247,15 @@ const detectArtifactFormat = async (const magic = Buffer.alloc(8);const observed = await handle.read(magic, 0, magic.length, 0);throwIfTargetResolutionCancelled(signal);+ if (+ observed.bytesRead === 8 &&+ magic.equals(Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]))+ )+ throw new BinaryTargetError(+ path,+ "WebAssembly v1 artifacts are not supported by the native opening route",+ { constraint: "wasm_requires_static_inspection" },+ );if (hasZipSignature(magic.subarray(0, observed.bytesRead))) {// The HarmonyOS App Pack suffix `.app` is a root-input concept; a nested// ZIP member ending in `.app` keeps the generic zip classification.diff --git a/src/application/Doctor.ts b/src/application/Doctor.tsindex 5ffc9f340..3e8659dca 100644--- a/src/application/Doctor.ts+++ b/src/application/Doctor.ts@@ -421,7 +421,7 @@ export const systemDoctorHost = (name: "target",ok: false,classification:- targetError?.constraint === "directory_requires_file"+ targetError?.constraint !== undefined? "unsupported_target": "config_drift",detail: path,diff --git a/src/domain/analysisErrorPresentation.ts b/src/domain/analysisErrorPresentation.tsindex 0c433e789..c28f926b5 100644--- a/src/domain/analysisErrorPresentation.ts+++ b/src/domain/analysisErrorPresentation.ts@@ -76,6 +76,11 @@ export const analysisErrorRemediationAction = (error.constraint === "directory_requires_file")return "For a JavaScript/Electron application directory, call analyze_javascript_application with input_path or run `rea analyze <directory>`. For binary analysis, select its executable file.";+ if (+ error instanceof BinaryTargetError &&+ error.constraint === "wasm_requires_static_inspection"+ )+ return `For static inspection, call inspect_wasm_artifact with ${JSON.stringify({ path: error.path })} or run \`rea inspect-wasm-artifact <path> --format json\`. This separate lane requires caller-supplied WABT 1.0.42 via absolute REA_WABT_BIN_DIRECTORY; check its availability in binary_session. REA does not execute WASM or install tools, and the header alone does not establish that the complete module is valid.`;if (error instanceof AnalysisAccessDeniedError ||(error instanceof BinaryTargetError && error.systemCode !== undefined)@@ -95,6 +100,11 @@ export const analysisErrorRemediationAction = (export const analysisErrorCategory = (error: AnalysisError,): AnalysisErrorProjection["category"] => {+ if (+ error instanceof BinaryTargetError &&+ error.constraint === "wasm_requires_static_inspection"+ )+ return "unsupported_target";if (error instanceof ProviderSelectionError &&error.reason === "provider_unavailable"@@ -213,6 +223,11 @@ export const analysisErrorUserMessage = (error: AnalysisError): string => {).join("; ")}.`;if (error instanceof NoBinaryOpenError) return error.message;+ if (+ error instanceof BinaryTargetError &&+ error.constraint === "wasm_requires_static_inspection"+ )+ return `${error.message}. Static WebAssembly inspection uses a separate optional WABT lane, not a native analysis engine.`;if (error instanceof BinaryTargetError)return error.constraint === "directory_requires_file"? "open_binary accepts files and macOS app bundles. This target is a directory; JavaScript/Electron application directories can be analyzed directly with analyze_javascript_application or `rea analyze <directory>`."diff --git a/src/domain/configurationErrors.ts b/src/domain/configurationErrors.tsindex 88078d0be..803a21a65 100644--- a/src/domain/configurationErrors.ts+++ b/src/domain/configurationErrors.ts@@ -38,7 +38,9 @@ export class NoBinaryOpenError extends AnalysisError {/** Additional constraints identified while admitting a filesystem target. */export interface BinaryTargetErrorOptions extends AnalysisErrorOptions {- readonly constraint?: "directory_requires_file";+ readonly constraint?:+ | "directory_requires_file"+ | "wasm_requires_static_inspection";}/** A supplied target path could not be safely opened as a supported app or binary. */diff --git a/tests/boundary/filesystem/mipsAbiFlags.test.ts b/tests/boundary/filesystem/mipsAbiFlags.test.tsindex 4cab9b702..01a219657 100644--- a/tests/boundary/filesystem/mipsAbiFlags.test.ts+++ b/tests/boundary/filesystem/mipsAbiFlags.test.ts@@ -131,6 +131,8 @@ for (const little of [true, false]) {const fp64 = await inspect(bytes, little);assert.ok(fp64.ok);const changed = target({ ...metadata(little), abiFlags: fp64.value });+ assert.equal(fp64.value?.cpr1Size, 2);+ assert.equal(fp64.value?.fpAbi, 6);assert.match(ghidraMipsUnsupportedReason(changed) ?? "", /FP64/u);assert.notDeepEqual(ghidraMipsProfileParameters(changed), before);});@@ -271,6 +273,13 @@ const unsupported: [string, (bytes: Buffer) => void, RegExp][] = [},/MIPS32r2/u,],+ [+ "soft-float with declared CPR1",+ (b) => {+ b[abiOffset + 7] = 3;+ },+ /soft-float without CPR1/u,+ ],["unspecified FP ABI",(b) => {@@ -301,19 +310,22 @@ for (const [name, change, reason] of unsupported) {);});}-it("resolves soft-float ABI metadata and commits its integer-register storage policy", async () => {- const bytes = fixture();- bytes[abiOffset + 5] = 0;- bytes[abiOffset + 7] = 3;- const resolved = await resolveFixture(bytes);- assert.equal(resolved.mips.abiFlags?.cpr1Size, 0);- assert.equal(resolved.mips.abiFlags?.fpAbi, 3);- assert.equal(ghidraMipsUnsupportedReason(resolved), null);- assert.equal(- ghidraMipsProfileParameters(resolved).mips_soft_float_storage,- "o32-soft-float-prototype-v1",- );-});+it.each([true, false])(+ "resolves soft-float ABI metadata and commits its integer-register storage policy (little endian: %s)",+ async (little) => {+ const bytes = fixture(little);+ bytes[abiOffset + 5] = 0;+ bytes[abiOffset + 7] = 3;+ const resolved = await resolveFixture(bytes);+ assert.equal(resolved.mips.abiFlags?.cpr1Size, 0);+ assert.equal(resolved.mips.abiFlags?.fpAbi, 3);+ assert.equal(ghidraMipsUnsupportedReason(resolved), null);+ assert.equal(+ ghidraMipsProfileParameters(resolved).mips_soft_float_storage,+ "o32-soft-float-prototype-v1",+ );+ },+);it("preserves the caller's cancellation error during table inspection", async () => {const cancelled = new Error("caller cancellation sentinel");let checks = 0;diff --git a/tests/boundary/filesystem/targetDiagnostics.test.ts b/tests/boundary/filesystem/targetDiagnostics.test.tsindex 645846fe5..32b86bbce 100644--- a/tests/boundary/filesystem/targetDiagnostics.test.ts+++ b/tests/boundary/filesystem/targetDiagnostics.test.ts@@ -7,6 +7,81 @@ import { projectAnalysisError } from "../../../src/domain/analysisErrorProjectioimport { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";describe("target route diagnostics", () => {+ it.each(["module.wasm", "module.bin", "misleading.js"])(+ "identifies a WASM v1 header in %s without suggesting native provider installation",+ async (name) => {+ const directory = await createTestTempDirectory("rea-wasm-target-");+ const path = join(directory, name);+ const bytes = Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]);+ await writeFile(path, bytes);+ const result = await parseBinaryTarget(path);+ if (result.ok) throw new Error("WASM was admitted to native opening");+ const projected = projectAnalysisError(result.error);+ expect(projected).toMatchObject({+ code: "target_unavailable",+ category: "unsupported_target",+ retryable: false,+ details: {+ path: await realpath(path),+ constraint: "wasm_requires_static_inspection",+ },+ });+ expect(projected.message).toContain("WebAssembly");+ expect(projected.remediation.action).toContain("inspect_wasm_artifact");+ expect(projected.remediation.action).toContain("REA_WABT_BIN_DIRECTORY");+ expect(projected.remediation.action).toContain("WABT 1.0.42");+ expect(projected.remediation.action).toContain("does not execute");+ expect(await systemDoctorHost().inspectTarget?.(path)).toMatchObject({+ ok: false,+ classification: "unsupported_target",+ details: { constraint: "wasm_requires_static_inspection" },+ remediation: projected.remediation.action,+ });+ },+ );++ it.each([+ [0, 0x61, 0x73, 0x6d],+ [0, 0x61, 0x73, 0x6d, 2, 0, 0, 0],+ [1, 2, 3, 4, 5, 6, 7, 8],+ ])(+ "does not infer supported WASM encoding from a suffix or incomplete header",+ async (...bytes) => {+ const directory = await createTestTempDirectory("rea-wasm-unknown-");+ const path = join(directory, "module.wasm");+ await writeFile(path, Buffer.from(bytes));+ const result = await parseBinaryTarget(path);+ if (result.ok) throw new Error("unknown header was admitted");+ const projected = projectAnalysisError(result.error);+ expect(projected.details).not.toHaveProperty("constraint");+ expect(projected.remediation.action).not.toContain(+ "inspect_wasm_artifact",+ );+ },+ );++ it("preserves an explicit raw-binary selection even when the bytes have a WASM header", async () => {+ const directory = await createTestTempDirectory("rea-wasm-explicit-raw-");+ const path = join(directory, "module.wasm");+ await writeFile(path, Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]));+ expect(+ await parseBinaryTarget(path, {+ formatHint: "raw-binary",+ architecture: "x86",+ entryPoint: "0x001000",+ }),+ ).toMatchObject({+ ok: true,+ value: {+ path: await realpath(path),+ format: "raw-binary",+ architecture: "x86",+ entryPoint: "0x1000",+ entryPointSource: "0x001000",+ },+ });+ });+it("identifies the directory opening constraint and gives the direct analysis route", async () => {const directory = await createTestTempDirectory("rea-js-target-");await writeFile(join(directory, "index.js"), "export const answer = 42;\n");diff --git a/tests/boundary/mcp/wasmArtifactMcp.test.ts b/tests/boundary/mcp/wasmArtifactMcp.test.tsindex 62b85b6e1..0a4a2610c 100644--- a/tests/boundary/mcp/wasmArtifactMcp.test.ts+++ b/tests/boundary/mcp/wasmArtifactMcp.test.ts@@ -1,17 +1,93 @@-import { Client, InMemoryTransport } from "@modelcontextprotocol/client";+import type { Client } from "@modelcontextprotocol/client";import { Ajv2020 } from "ajv/dist/2020.js";import { expect, it, onTestFinished, vi } from "vitest";+import { readFile, realpath, writeFile } from "node:fs/promises";+import { join } from "node:path";import { WasmArtifactService } from "../../../src/application/wasm/WasmArtifactService.js";import { toolContract } from "../../../src/contracts/toolContracts.js";import { parseEvidence } from "../../../src/domain/evidence.js";import { ok } from "../../../src/domain/result.js";-import { createServer } from "../../../src/server/createServer.js";+import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js";import { createTestBinarySession } from "../../fixtures/binarySession.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { parseMcpToolError } from "../../fixtures/mcpToolError.js";import {wasmArtifactFixture,wasmArtifactExecution,} from "../../fixtures/wasm/artifact.js";+const wasmToolSchemas = async (client: Client) => {+ const advertised = (await client.listTools()).tools.find(+ (tool) => tool.name === "inspect_wasm_artifact",+ );+ if (advertised?.outputSchema === undefined)+ throw new Error("WASM recovery must name an advertised static tool");+ const ajv = new Ajv2020({ strict: false, validateFormats: false });+ const inputSchema: Record<string, unknown> = advertised.inputSchema;+ const outputSchema: Record<string, unknown> = advertised.outputSchema;+ expect(ajv.validateSchema(inputSchema)).toBe(true);+ expect(ajv.validateSchema(outputSchema)).toBe(true);+ return { name: advertised.name, ajv, inputSchema, outputSchema };+};++it("directs rejected native WASM opening to the advertised static tool while preserving missing-WABT diagnostics", async () => {+ const directory = await createTestTempDirectory("rea-wasm-recovery-");+ const path = join(+ await realpath(directory),+ process.platform === "win32" ? "module space.bin" : 'module "quoted".bin',+ );+ await writeFile(path, Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]));+ const createClient = vi.fn(() => {+ throw new Error("native provider must not start for WASM");+ });+ const session = createTestBinarySession(createClient);+ const harness = await createApplicationMcpHarness({+ session,+ serverOptions: { environment: {} },+ });+ onTestFinished(harness.close);+ const { client } = harness;+ const { name, ajv, inputSchema } = await wasmToolSchemas(client);+ const input = { path };+ expect(+ toolContract("inspect_wasm_artifact").inputSchema.safeParse(input).success,+ ).toBe(true);+ const opening = await client.callTool({+ name: "open_binary",+ arguments: input,+ });+ expect(opening.isError).toBe(true);+ const failure = parseMcpToolError(opening);+ expect(failure).toMatchObject({+ error: {+ code: "target_unavailable",+ category: "unsupported_target",+ details: { constraint: "wasm_requires_static_inspection" },+ },+ });+ expect(failure.error.remediation.action).toContain(JSON.stringify({ path }));+ expect(ajv.validate(inputSchema, input)).toBe(true);+ const inspection = await client.callTool({+ name,+ arguments: input,+ });+ expect(inspection.isError).toBe(true);+ expect(parseMcpToolError(inspection)).toMatchObject({+ error: {+ code: "capability_unavailable",+ details: {+ operation: "inspect_wasm_artifact",+ reason: expect.stringContaining("REA_WABT_BIN_DIRECTORY"),+ },+ },+ });+ await client.ping();+ expect(createClient).not.toHaveBeenCalled();+ expect(await readFile(path)).toEqual(+ Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]),+ );+});+it("advertises exact valid schemas and records inline WASM interface evidence without a binary target", async () => {const value = wasmArtifactFixture();const close = vi.fn(() => Promise.resolve());@@ -22,30 +98,13 @@ it("advertises exact valid schemas and records inline WASM interface evidence wiconst session = createTestBinarySession(() => {throw new Error("deep provider must not start");});- const server = createServer(- { kind: "session", session },- { wasmArtifact: service },- );- const client = new Client({ name: "wasm-artifact-contract", version: "1" });- onTestFinished(async () => {- await client.close();- await server.close();- await session.close();+ const harness = await createApplicationMcpHarness({+ session,+ serverOptions: { wasmArtifact: service },});- const [clientTransport, serverTransport] =- InMemoryTransport.createLinkedPair();- await server.connect(serverTransport);- await client.connect(clientTransport);- const advertised = (await client.listTools()).tools.find(- (tool) => tool.name === "inspect_wasm_artifact",- );- if (advertised?.outputSchema === undefined)- throw new Error("WASM interface inspection must publish both schemas");- const ajv = new Ajv2020({ strict: false, validateFormats: false });- const inputSchema: Record<string, unknown> = advertised.inputSchema;- const outputSchema: Record<string, unknown> = advertised.outputSchema;- expect(ajv.validateSchema(inputSchema)).toBe(true);- expect(ajv.validateSchema(outputSchema)).toBe(true);+ onTestFinished(harness.close);+ const { client } = harness;+ const { ajv, inputSchema, outputSchema } = await wasmToolSchemas(client);expect(ajv.validate(inputSchema, { path: value.artifact.path })).toBe(true);expect(ajv.validate(inputSchema, {@@ -79,6 +138,6 @@ it("advertises exact valid schemas and records inline WASM interface evidence wi})).isError,).toBe(true);- await server.close();+ await harness.close();expect(close).toHaveBeenCalled();});diff --git a/tests/fixtures/applicationMcpHarness.ts b/tests/fixtures/applicationMcpHarness.tsindex f9e8f38b1..95196e621 100644--- a/tests/fixtures/applicationMcpHarness.ts+++ b/tests/fixtures/applicationMcpHarness.ts@@ -14,12 +14,22 @@ export interface ApplicationMcpHarness {}/** Connect application workflows through the production MCP registration. */-export async function createApplicationMcpHarness(): Promise<ApplicationMcpHarness> {- const session = createTestBinarySession(() => ({- execute: () => Promise.resolve(observed(null)),- close: () => Promise.resolve(resultOk(null)),- }));- const server = createServer({ kind: "session", session });+export async function createApplicationMcpHarness(+ options: {+ readonly session?: BinarySession;+ readonly serverOptions?: Parameters<typeof createServer>[1];+ } = {},+): Promise<ApplicationMcpHarness> {+ const session =+ options.session ??+ createTestBinarySession(() => ({+ execute: () => Promise.resolve(observed(null)),+ close: () => Promise.resolve(resultOk(null)),+ }));+ const server = createServer(+ { kind: "session", session },+ options.serverOptions,+ );const client = new Client({name: "application-workflow-test",version: "1",