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(flutter): select reported ABI labels through shared contracts
morluto64abd4aefb23
diff --git a/docs/flutter-analysis.md b/docs/flutter-analysis.mdindex df68ee9cc..dab4efad9 100644--- a/docs/flutter-analysis.md+++ b/docs/flutter-analysis.md@@ -23,7 +23,9 @@ rea inspect-dart-aot /targets/Example.apk --abi armeabi-v7aThe equivalent MCP methods are `identify_flutter_build` (with `path`) and`inspect_dart_aot` (with `path` and an optional `abi`; the default prefersarm64-v8a, then x86_64, then x86, then armeabi-v7a, then the remaining-ABIs alphabetically).+ABIs alphabetically). An explicit `abi` is the directory label exactly as+`identify_flutter_build` reports it, so a payload under a nonstandard label+stays selectable and keeps that label in the result.## Optional retained AOT deliverydiff --git a/src/cli/flutterCommands.ts b/src/cli/flutterCommands.tsindex 07aa2c8cd..4879d1cea 100644--- a/src/cli/flutterCommands.ts+++ b/src/cli/flutterCommands.ts@@ -4,7 +4,10 @@ import type { FlutterBuildAnalysisPort } from "../application/flutter/FlutterBuiimport { createFlutterBuildAnalysisProvider } from "../composition/flutter.js";import { CLI_COMMANDS } from "../cliCommandNames.js";import { logCliCommand } from "../cliLogging.js";-import type { FlutterOperation } from "../domain/flutter/flutterBuildAnalysis.js";+import {+ flutterInputSchemas,+ type FlutterOperation,+} from "../domain/flutter/flutterBuildAnalysis.js";import type { Logger } from "pino";import type { CliInstance } from "./types.js";import { withCommandCancellation } from "./commandCancellation.js";@@ -35,7 +38,7 @@ export const registerFlutterCommands = (description:"Identify a Flutter build's Dart snapshot hash and engine facts by pure APK parsing",argumentSchema: z.object({- path: z.string().min(1).describe("Local APK file to inspect"),+ path: flutterInputSchemas.identify_flutter_build.shape.path,}),operation: "identify_flutter_build",toInput: (arguments_) => arguments_,@@ -45,18 +48,10 @@ export const registerFlutterCommands = (description:"Inspect one ABI's Dart AOT snapshot: sections, headers, and the string pool",argumentSchema: z.object({- path: z- .string()- .min(1)- .describe("Local APK carrying a Flutter payload"),+ path: flutterInputSchemas.inspect_dart_aot.shape.path,}),optionSchema: z.object({- abi: z- .string()- .min(2)- .max(16)- .optional()- .describe("ABI under lib/ to inspect; defaults to the preferred one"),+ abi: flutterInputSchemas.inspect_dart_aot.shape.abi,}),operation: "inspect_dart_aot",toInput: (arguments_, options) => ({diff --git a/src/domain/flutter/flutterBuildAnalysis.ts b/src/domain/flutter/flutterBuildAnalysis.tsindex 10c5b7b00..37c3987b8 100644--- a/src/domain/flutter/flutterBuildAnalysis.ts+++ b/src/domain/flutter/flutterBuildAnalysis.ts@@ -2,6 +2,33 @@ import { z } from "zod";import { localPathStringSchema } from "../localPath.js";import { digestSchema } from "../digests.js";+/** Full logical ZIP path budget, enforced by Flutter library inventory. */+export const MAX_FLUTTER_LIBRARY_PATH_BYTES = 1024;++/**+ * A libapp label can occupy every remaining byte of an admitted path. Its+ * Unicode character count cannot exceed that byte count. The query permits+ * unmatched labels; inventory owns the exact UTF-8 byte check on real paths.+ */+const ABI_SELECTOR_MAX_CHARACTERS =+ MAX_FLUTTER_LIBRARY_PATH_BYTES - "lib/".length - "/libapp.so".length;++/**+ * ZIP labels are literal names, including backslashes and controls. They are+ * never used as extraction paths. A Unicode regex gives runtime validation+ * and JSON Schema the same character unit; Zod max() counts UTF-16 units.+ * The final lookahead requires the actual end, including a trailing newline.+ */+const abiSelectorSchema = z+ .string()+ .regex(+ new RegExp(+ `^[^/]{1,${String(ABI_SELECTOR_MAX_CHARACTERS)}}(?![\\s\\S])`,+ "u",+ ),+ `ABI must be the exact lib/ directory label: 1β${String(ABI_SELECTOR_MAX_CHARACTERS)} Unicode characters without '/'.`,+ );+/*** Caller intent for Flutter build identification. This family is pure* parsing: it reads an APK's `lib/<abi>/libapp.so` and `libflutter.so`@@ -15,17 +42,10 @@ export const flutterInputSchemas = {path: localPathStringSchema.describe("Local APK file carrying a Flutter AOT payload",),- abi: z- .string()- .min(2)- .max(16)- .regex(- /^[a-z0-9_\x2d]+$/u,- "ABI name as it appears under lib/, e.g. arm64-v8a",- )+ abi: abiSelectorSchema.optional().describe(- "ABI to inspect; defaults to arm64-v8a, x86_64, x86, armeabi-v7a, then remaining ABIs alphabetically",+ "Exact lib/ directory label reported by identify_flutter_build; defaults to arm64-v8a, x86_64, x86, armeabi-v7a, then remaining ABIs alphabetically",),}),} as const;diff --git a/src/flutter/FlutterBuildProvider.ts b/src/flutter/FlutterBuildProvider.tsindex d50eaacf9..ca37a58bc 100644--- a/src/flutter/FlutterBuildProvider.ts+++ b/src/flutter/FlutterBuildProvider.ts@@ -15,7 +15,10 @@ import {createAnalysisExecutionEvidence,type AnalysisExecution,} from "../application/AnalysisProvider.js";-import type { FlutterRequest } from "../domain/flutter/flutterBuildAnalysis.js";+import {+ MAX_FLUTTER_LIBRARY_PATH_BYTES,+ type FlutterRequest,+} from "../domain/flutter/flutterBuildAnalysis.js";import {AnalysisAccessDeniedError,AnalysisArtifactChangedError,@@ -71,7 +74,6 @@ const APK_MAX_BYTES = 2 * 1024 * 1024 * 1024;// engine labels this keeps expanded result metadata below 512 KiB for ordinary// ABI names, independently of the archive's compressed-byte budget.const MAX_FLUTTER_ABIS = 32;-const MAX_LIBRARY_PATH_BYTES = 1024;const MAX_POOL_URIS = 500;const MAX_POOL_TOKENS = 2_000;/** A complete AOT image carries exactly one VM and one isolate section. */@@ -284,7 +286,7 @@ const collectFlutterLibraries = async (abis.add(match[1]!);if (abis.size > MAX_FLUTTER_ABIS ||- Buffer.byteLength(entry.path) > MAX_LIBRARY_PATH_BYTES+ Buffer.byteLength(entry.path) > MAX_FLUTTER_LIBRARY_PATH_BYTES)throw new AnalysisResourceConstraintError(operation,@@ -292,7 +294,7 @@ const collectFlutterLibraries = async ("Flutter library inventory exceeds the bounded ABI projection budget",{max_flutter_abis: MAX_FLUTTER_ABIS,- max_library_path_bytes: MAX_LIBRARY_PATH_BYTES,+ max_library_path_bytes: MAX_FLUTTER_LIBRARY_PATH_BYTES,},);libraries.push({diff --git a/tests/boundary/cli/flutterCli.test.ts b/tests/boundary/cli/flutterCli.test.tsindex 4b424479d..8d09fc90a 100644--- a/tests/boundary/cli/flutterCli.test.ts+++ b/tests/boundary/cli/flutterCli.test.ts@@ -1,11 +1,14 @@import { rm } from "node:fs/promises";import { Cli } from "incur";import { expect, it, onTestFinished } from "vitest";+import { Ajv } from "ajv";+import type { AnySchema } from "ajv";import { registerFlutterCommands } from "../../../src/cli/flutterCommands.js";import { aotFixtureImage } from "../../../src/flutter/FlutterBuild.fixture.js";import { FlutterBuildProvider } from "../../../src/flutter/FlutterBuildProvider.js";import { silentLogger } from "../../../src/logger.js";+import { flutterInputSchemas } from "../../../src/domain/flutter/flutterBuildAnalysis.js";import { createFlutterApk } from "../../fixtures/flutterApk.js";import { serveCli } from "./cliServeHarness.js";@@ -27,6 +30,94 @@ it("reports an unreadable target with an input refusal", async () => {expect(result.stdout).toContain("invalid_request");});+it.each(["identify-flutter-build", "inspect-dart-aot"])(+ "%s uses canonical local-path validation before provider admission",+ async (command) => {+ const result = await serveCli([command, "fixture\u0000.apk", "--json"]);+ expect(JSON.parse(result.stdout)).toMatchObject({+ code: "VALIDATION_ERROR",+ fieldErrors: [+ expect.objectContaining({+ path: "path",+ message: expect.stringContaining("NUL"),+ }),+ ],+ });+ },+);++it("advertises and validates one ABI selector grammar with field correction guidance", async () => {+ const advertised = await serveCli(["inspect-dart-aot", "--schema", "--json"]);+ expect(advertised.exitCode).toBe(0);+ const schema = JSON.parse(advertised.stdout) as { options: AnySchema };+ const ajv = new Ajv({ strict: false });+ expect(ajv.validateSchema(schema.options)).toBe(true);+ const accepts = ajv.compile(schema.options);+ const abiSchema = flutterInputSchemas.inspect_dart_aot.shape.abi;+ for (const abi of [+ "ARM64-V8A",+ "ARM64",+ "arm64.v8a",+ "A",+ "a",+ "abi\\label",+ "abi\nlabel",+ "l".repeat(1010),+ "π".repeat(1010),+ ]) {+ expect(accepts({ abi })).toBe(true);+ expect(abiSchema.safeParse(abi).success).toBe(true);+ }+ for (const abi of [+ "",+ "lib/x86_64",+ "l".repeat(1011),+ "π".repeat(1011),+ "l".repeat(1010) + "\n",+ ]) {+ expect(accepts({ abi })).toBe(false);+ expect(abiSchema.safeParse(abi).success).toBe(false);+ const rejected = await serveCli([+ "inspect-dart-aot",+ "/nonexistent/app.apk",+ "--abi",+ abi,+ "--json",+ ]);+ expect(JSON.parse(rejected.stdout)).toMatchObject({+ code: "VALIDATION_ERROR",+ fieldErrors: [+ expect.objectContaining({+ path: "abi",+ message: expect.stringContaining("ABI"),+ }),+ ],+ });+ }+});++it("inspects the caller-selected nonstandard ABI through the public CLI", async () => {+ const path = await createFlutterApk("selector.apk", [+ { path: "lib/ARM64-V8A/libapp.so", bytes: aotFixtureImage("a".repeat(32)) },+ { path: "lib/x86_64/libapp.so", bytes: aotFixtureImage("b".repeat(32)) },+ ]);+ const selected = await serveCli([+ "inspect-dart-aot",+ path,+ "--abi",+ "ARM64-V8A",+ "--json",+ ]);+ expect(selected.exitCode).toBe(0);+ expect(JSON.parse(selected.stdout)).toMatchObject({+ parameters: { path, abi: "ARM64-V8A" },+ normalized_result: {+ abi: "ARM64-V8A",+ libapp: { snapshot_hash: "a".repeat(32), coverage: "complete" },+ },+ });+});+/** Serve one command whose first snapshot-root removal fails and is retried on close. */const serveWithCleanupRetry = async (command: string,diff --git a/tests/boundary/mcp/flutterMcp.test.ts b/tests/boundary/mcp/flutterMcp.test.tsindex 646f54511..03e879f0e 100644--- a/tests/boundary/mcp/flutterMcp.test.ts+++ b/tests/boundary/mcp/flutterMcp.test.ts@@ -1,5 +1,6 @@import { Client, InMemoryTransport } from "@modelcontextprotocol/client";import { expect, it, onTestFinished } from "vitest";+import { Ajv2020 } from "ajv/dist/2020.js";import type { FlutterBuildAnalysisPort } from "../../../src/application/flutter/FlutterBuildAnalysisPort.js";import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";@@ -8,6 +9,91 @@ import { parseEvidence } from "../../../src/domain/evidence.js";import { ok } from "../../../src/domain/result.js";import { createServer } from "../../../src/server/createServer.js";import { createTestBinarySession } from "../../fixtures/binarySession.js";+import { createFlutterBuildAnalysisProvider } from "../../../src/composition/flutter.js";+import { flutterResultSchemas } from "../../../src/domain/flutter/flutterBuildAnalysis.js";+import { aotFixtureImage } from "../../../src/flutter/FlutterBuild.fixture.js";+import { createFlutterApk } from "../../fixtures/flutterApk.js";+import { createApplicationMcpHarness } from "../../fixtures/applicationMcpHarness.js";++it.each([+ { label: "ARM64-V8A", paired: false },+ ...[+ "ARM64-V8A",+ "arm64.v8a",+ "A",+ ".",+ "..",+ "abi\\label",+ "abi\u0000label",+ "abi\nlabel",+ "abi\u0085label",+ "l".repeat(336),+ "l".repeat(1010),+ "η".repeat(336),+ "π".repeat(252),+ ].map((label) => ({ label, paired: true })),+])(+ "selects the exact reported archive ABI $label (paired=$paired)",+ async ({ label, paired }) => {+ const path = await createFlutterApk("reported-label.apk", [+ {+ path: `lib/${label}/libapp.so`,+ bytes: aotFixtureImage("a".repeat(32)),+ },+ ...(paired+ ? [+ {+ path: "lib/x86_64/libapp.so",+ bytes: aotFixtureImage("b".repeat(32)),+ },+ ]+ : []),+ ]);+ const provider = createFlutterBuildAnalysisProvider();+ onTestFinished(() => provider.close());+ const harness = await createApplicationMcpHarness({+ serverOptions: { flutterAnalysis: provider },+ });+ onTestFinished(harness.close);+ const call = (name: string, abi?: string) =>+ harness.client.callTool({+ name,+ arguments: { path, ...(abi === undefined ? {} : { abi }) },+ });+ const inventoryReply = await call("identify_flutter_build");+ expect(inventoryReply.isError).not.toBe(true);+ const inventory = flutterResultSchemas.identify_flutter_build.parse(+ parseEvidence(inventoryReply.structuredContent).normalized_result,+ );+ expect(inventory.abis.map((row) => row.abi)).toContain(label);+ const defaultReply = await call("inspect_dart_aot");+ expect(defaultReply.isError).not.toBe(true);+ const defaultFacts = flutterResultSchemas.inspect_dart_aot.parse(+ parseEvidence(defaultReply.structuredContent).normalized_result,+ );+ expect(defaultFacts.abi).toBe(paired ? "x86_64" : label);+ expect(defaultFacts.libapp.snapshot_hash).toBe(+ (paired ? "b" : "a").repeat(32),+ );+ const selectedReply = await call("inspect_dart_aot", label);+ expect(selectedReply.isError).not.toBe(true);+ const evidence = parseEvidence(selectedReply.structuredContent);+ const selected = flutterResultSchemas.inspect_dart_aot.parse(+ evidence.normalized_result,+ );+ expect(selected.abi).toBe(label);+ expect(selected.libapp.snapshot_hash).toBe("a".repeat(32));+ expect(selected.libapp.coverage).toBe("complete");+ expect(evidence.parameters).toEqual({ path, abi: label });+ const tool = (await harness.client.listTools()).tools.find(+ (tool) => tool.name === "inspect_dart_aot",+ );+ if (tool === undefined) throw new Error("Missing AOT tool");+ const ajv = new Ajv2020({ strict: false, validateFormats: false });+ expect(ajv.validateSchema(tool.inputSchema)).toBe(true);+ expect(ajv.validate(tool.inputSchema, { path, abi: label })).toBe(true);+ },+);const identity = {id: "flutter",@@ -122,6 +208,51 @@ const fakeProvider = (): FlutterBuildAnalysisPort => ({},});+it("advertises and enforces the same Unicode selector grammar through MCP", async () => {+ const harness = await createApplicationMcpHarness({+ serverOptions: { flutterAnalysis: fakeProvider() },+ });+ onTestFinished(harness.close);+ const tool = (await harness.client.listTools()).tools.find(+ (tool) => tool.name === "inspect_dart_aot",+ );+ if (tool === undefined) throw new Error("Missing AOT tool");+ const ajv = new Ajv2020({ strict: false, validateFormats: false });+ expect(ajv.validateSchema(tool.inputSchema)).toBe(true);+ for (const abi of ["π".repeat(1010), "l".repeat(1010)]) {+ const arguments_ = { path: "/fixture.apk", abi };+ expect(ajv.validate(tool.inputSchema, arguments_)).toBe(true);+ expect(+ (+ await harness.client.callTool({+ name: "inspect_dart_aot",+ arguments: arguments_,+ })+ ).isError,+ ).not.toBe(true);+ }+ for (const abi of [+ "",+ "lib/x86_64",+ "π".repeat(1011),+ "l".repeat(1010) + "\n",+ ]) {+ const arguments_ = { path: "/fixture.apk", abi };+ expect(ajv.validate(tool.inputSchema, arguments_)).toBe(false);+ const refused = await harness.client.callTool({+ name: "inspect_dart_aot",+ arguments: arguments_,+ });+ expect(refused.isError).toBe(true);+ expect(refused.content).toContainEqual({+ type: "text",+ text: expect.stringContaining(+ "abi: ABI must be the exact lib/ directory label",+ ),+ });+ }+});+it("advertises an exact valid Flutter schema and records inline evidence through MCP", async () => {const session = createTestBinarySession(() => {throw new Error("deep provider must not start");