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(target): preserve app bundle filesystem failure reasons
morlutod4c2c3c18f69
diff --git a/src/application/AppBundleExecutable.ts b/src/application/AppBundleExecutable.tsindex f3e8b30c3..06d2251a6 100644--- a/src/application/AppBundleExecutable.ts+++ b/src/application/AppBundleExecutable.ts@@ -36,6 +36,15 @@ export interface ResolvedAppBundle {readonly infoPlist?: string;}+/** Filesystem operations used by the resolver, injectable for boundary tests. */+export interface AppBundleFileSystem {+ readonly readFile: (path: string) => Promise<Buffer>;+ readonly realpath: (path: string) => Promise<string>;+ readonly decodeBinaryPlist?: (path: string) => Promise<string>;+}++const defaultFileSystem: AppBundleFileSystem = { readFile, realpath };+/*** Resolve an app bundle directory to its declared program file. macOS and* flat iOS-style layouts are read directly. An iOS app installed on a Mac is@@ -44,21 +53,34 @@ export interface ResolvedAppBundle {*/export const resolveAppBundleExecutable = async (path: string,+ fileSystem: AppBundleFileSystem = defaultFileSystem,): Promise<Result<ResolvedAppBundle, BinaryTargetError>> => {- const layout = await presentLayout(path);- if (layout !== undefined) return resolveLayoutExecutable(path, layout);- const wrapped = await wrappedBundle(path);- if (wrapped !== undefined) {- const wrappedLayout = await presentLayout(wrapped);- if (wrappedLayout !== undefined)- return resolveLayoutExecutable(wrapped, wrappedLayout);+ try {+ const layout = await presentLayout(path);+ if (layout !== undefined)+ return resolveLayoutExecutable(path, layout, fileSystem);+ const wrapped = await wrappedBundle(path);+ if (wrapped !== undefined) {+ const wrappedLayout = await presentLayout(wrapped);+ if (wrappedLayout !== undefined)+ return resolveLayoutExecutable(wrapped, wrappedLayout, fileSystem);+ }+ } catch (cause: unknown) {+ if (cause instanceof BinaryTargetError) return err(cause);+ return err(+ new BinaryTargetError(path, errorReason(cause, path), { cause }),+ );}return err(- new BinaryTargetError(path, "app has no readable CFBundleExecutable", {- cause: new Error(- "No Contents/Info.plist, root Info.plist, or single Wrapper/*.app bundle was found",- ),- }),+ new BinaryTargetError(+ path,+ `app Info.plist is missing or no supported bundle layout was found: ${path}`,+ {+ cause: new Error(+ "No Contents/Info.plist, root Info.plist, or single Wrapper/*.app bundle was found",+ ),+ },+ ),);};@@ -80,16 +102,50 @@ const layoutPlistPresent = async (path: string): Promise<boolean> => {return (await stat(path)).isFile();} catch (cause: unknown) {if (isAbsence(cause)) return false;+ if (isPermissionDenied(cause))+ throw new BinaryTargetError(+ path,+ `permission denied inspecting app Info.plist ${path}`,+ { cause },+ );throw cause;}};const isAbsence = (cause: unknown): boolean => {- const code: unknown =- cause instanceof Error ? Reflect.get(cause, "code") : undefined;+ const code = errorCode(cause);return code === "ENOENT" || code === "ENOTDIR";};+const errorCode = (cause: unknown): unknown =>+ cause instanceof Error ? Reflect.get(cause, "code") : undefined;++const codeDescription = (cause: unknown): string => {+ const code = errorCode(cause);+ return typeof code === "string" || typeof code === "number"+ ? ` (${String(code)})`+ : "";+};++const isSystemErrorCode = (cause: unknown): boolean => {+ const code = errorCode(cause);+ return (+ typeof code === "string" &&+ /^[A-Z][A-Z0-9_]+$/u.test(code) &&+ !code.startsWith("ERR_")+ );+};++const isPermissionDenied = (cause: unknown): boolean =>+ errorCode(cause) === "EACCES" || errorCode(cause) === "EPERM";++const errorReason = (cause: unknown, path: string): string =>+ isPermissionDenied(cause)+ ? `permission denied accessing app bundle path ${path}`+ : isAbsence(cause)+ ? `app bundle path is missing: ${path}`+ : `could not inspect app bundle path ${path}`;+/** The single real `.app` directory inside an iOS-on-Mac `Wrapper`. */const wrappedBundle = async (bundle: string): Promise<string | undefined> => {const wrapper = join(bundle, "Wrapper");@@ -111,20 +167,45 @@ const wrappedBundle = async (bundle: string): Promise<string | undefined> => {const resolveLayoutExecutable = async (bundle: string,layout: BundleLayout,+ fileSystem: AppBundleFileSystem,): Promise<Result<ResolvedAppBundle, BinaryTargetError>> => {const plistPath = join(bundle, ...layout.plist);+ let plist: Buffer;+ try {+ plist = await fileSystem.readFile(plistPath);+ } catch (cause: unknown) {+ return err(+ new BinaryTargetError(+ plistPath,+ isPermissionDenied(cause)+ ? `permission denied reading app Info.plist ${plistPath}`+ : isAbsence(cause)+ ? `app Info.plist is missing: ${plistPath}`+ : `could not read app Info.plist ${plistPath}${codeDescription(cause)}`,+ { cause },+ ),+ );+ }+let name: string;try {- const plist = await readFile(plistPath);name =plist.subarray(0, 6).toString("ascii") === "bplist"- ? await readBinaryPlistExecutable(plistPath)+ ? await (fileSystem.decodeBinaryPlist ?? readBinaryPlistExecutable)(+ plistPath,+ ): parseXmlPlistExecutable(plist.toString("utf8"));} catch (cause: unknown) {return err(- new BinaryTargetError(bundle, "app has no readable CFBundleExecutable", {- cause,- }),+ new BinaryTargetError(+ plistPath,+ isPermissionDenied(cause)+ ? `permission denied decoding app Info.plist ${plistPath}${codeDescription(cause)}`+ : isSystemErrorCode(cause)+ ? `could not decode app Info.plist ${plistPath}${codeDescription(cause)}`+ : `app Info.plist is malformed or lacks CFBundleExecutable: ${plistPath}`,+ { cause },+ ),);}if (!isSafeExecutableName(name))@@ -135,8 +216,8 @@ const resolveLayoutExecutable = async (const executable = join(programs, name);try {const [canonicalPrograms, canonicalExecutable] = await Promise.all([- realpath(programs),- realpath(executable),+ fileSystem.realpath(programs),+ fileSystem.realpath(executable),]);if (!isPathWithinRoot(canonicalPrograms, canonicalExecutable))return err(@@ -148,7 +229,15 @@ const resolveLayoutExecutable = async (return ok({ executable: canonicalExecutable, infoPlist: plistPath });} catch (cause: unknown) {return err(- new BinaryTargetError(bundle, "app program file is missing", { cause }),+ new BinaryTargetError(+ executable,+ isPermissionDenied(cause)+ ? `permission denied resolving app program file ${executable}`+ : isAbsence(cause)+ ? `app program file is missing: ${executable}`+ : `could not resolve app program file ${executable}`,+ { cause },+ ),);}};diff --git a/tests/boundary/filesystem/binaryTarget.test.ts b/tests/boundary/filesystem/binaryTarget.test.tsindex 979904547..f6f87f681 100644--- a/tests/boundary/filesystem/binaryTarget.test.ts+++ b/tests/boundary/filesystem/binaryTarget.test.ts@@ -1,11 +1,22 @@import { execFile } from "node:child_process";-import { chmod, mkdir, realpath, symlink, writeFile } from "node:fs/promises";+import {+ chmod,+ mkdir,+ readFile,+ realpath,+ symlink,+ writeFile,+} from "node:fs/promises";import { join } from "node:path";import { promisify } from "node:util";import { describe, expect, it } from "vitest";import { parseBinaryTarget } from "../../../src/application/BinaryTargetResolver.js";+import {+ resolveAppBundleExecutable,+ type AppBundleFileSystem,+} from "../../../src/application/AppBundleExecutable.js";import {dosMz,pe,@@ -13,7 +24,154 @@ import {} from "../../../src/domain/binaryTarget.fixture.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";-describe("binary target I/O", () => {+describe("binary target I/O: app plist permissions and decoding", () => {+ it.each([+ ["EACCES", "permission denied reading app Info.plist"],+ ["EPERM", "permission denied reading app Info.plist"],+ ])("preserves %s while reading an app plist", async (code, message) => {+ const directory = await createTestTempDirectory("rea-app-permission-");+ const app = join(directory, "Permission.app");+ await mkdir(join(app, "Contents"), { recursive: true });+ await writeFile(join(app, "Contents", "Info.plist"), "placeholder");+ const denied = Object.assign(new Error("denied"), { code });+ const fileSystem: AppBundleFileSystem = {+ readFile: async () => {+ throw denied;+ },+ realpath,+ };+ const result = await resolveAppBundleExecutable(app, fileSystem);+ expect(result).toMatchObject({+ ok: false,+ error: {+ _tag: "BinaryTargetError",+ path: join(app, "Contents", "Info.plist"),+ reason: expect.stringContaining(message),+ cause: denied,+ },+ });+ });++ it("preserves non-permission plist read failures as read failures", async () => {+ const directory = await createTestTempDirectory("rea-app-read-error-");+ const app = join(directory, "ReadError.app");+ await mkdir(join(app, "Contents"), { recursive: true });+ await writeFile(join(app, "Contents", "Info.plist"), "placeholder");+ const readError = Object.assign(new Error("I/O failure"), { code: "EIO" });+ const result = await resolveAppBundleExecutable(app, {+ readFile: async () => {+ throw readError;+ },+ realpath,+ });+ expect(result).toMatchObject({+ ok: false,+ error: {+ path: join(app, "Contents", "Info.plist"),+ reason: expect.stringContaining("could not read app Info.plist"),+ cause: readError,+ },+ });+ });++ it("does not label binary plist decoder I/O failures as malformed data", async () => {+ const directory = await createTestTempDirectory("rea-app-decode-error-");+ const app = join(directory, "DecodeError.app");+ await mkdir(join(app, "Contents"), { recursive: true });+ await writeFile(join(app, "Contents", "Info.plist"), "bplist00");+ const decodeError = Object.assign(new Error("I/O failure"), {+ code: "EIO",+ });+ const result = await resolveAppBundleExecutable(app, {+ readFile: async () => Buffer.from("bplist00"),+ realpath,+ decodeBinaryPlist: async () => {+ throw decodeError;+ },+ });+ expect(result).toMatchObject({+ ok: false,+ error: {+ path: join(app, "Contents", "Info.plist"),+ reason: expect.stringContaining("could not decode app Info.plist"),+ cause: decodeError,+ },+ });+ });++ it.each(["EACCES", "EPERM", "ENOENT", "ENOTDIR"])(+ "preserves %s while resolving an app executable",+ async (code) => {+ const directory = await createTestTempDirectory("rea-app-permission-");+ const app = join(directory, "Permission.app");+ const programs = join(app, "Contents", "MacOS");+ await mkdir(programs, { recursive: true });+ await writeFile(+ join(app, "Contents", "Info.plist"),+ "<plist><dict><key>CFBundleExecutable</key><string>App</string></dict></plist>",+ );+ const denied = Object.assign(new Error("denied"), { code });+ const fileSystem: AppBundleFileSystem = {+ readFile,+ realpath: async (path) => {+ if (String(path) === join(programs, "App")) throw denied;+ return realpath(path);+ },+ };+ const result = await resolveAppBundleExecutable(app, fileSystem);+ expect(result).toMatchObject({+ ok: false,+ error: {+ _tag: "BinaryTargetError",+ path: join(programs, "App"),+ reason: expect.stringContaining(+ code === "EACCES" || code === "EPERM"+ ? "permission denied"+ : "missing",+ ),+ cause: denied,+ },+ });+ },+ );++ it("keeps missing and malformed plist diagnostics distinct", async () => {+ const directory = await createTestTempDirectory("rea-app-diagnostics-");+ const missing = join(directory, "Missing.app");+ await mkdir(join(missing, "Contents"), { recursive: true });+ const missingResult = await resolveAppBundleExecutable(missing);+ expect(missingResult).toMatchObject({+ ok: false,+ error: { reason: expect.stringContaining("missing") },+ });++ const notDirectory = join(directory, "NotDirectory.app");+ await mkdir(notDirectory, { recursive: true });+ await writeFile(join(notDirectory, "Contents"), "not a directory");+ const notDirectoryResult = await resolveAppBundleExecutable(notDirectory);+ expect(notDirectoryResult).toMatchObject({+ ok: false,+ error: { reason: expect.stringContaining("missing") },+ });++ const malformed = join(directory, "Malformed.app");+ await mkdir(join(malformed, "Contents", "MacOS"), { recursive: true });+ await writeFile(+ join(malformed, "Contents", "Info.plist"),+ "<plist><dict></dict></plist>",+ );+ const malformedResult = await resolveAppBundleExecutable(malformed);+ expect(malformedResult).toMatchObject({+ ok: false,+ error: {+ path: join(malformed, "Contents", "Info.plist"),+ reason: expect.stringContaining("malformed"),+ },+ });+ });+});++describe("binary target I/O: package classification", () => {it("classifies ZIP package families and text artifacts without Hopper", async () => {const directory = await createTestTempDirectory("rea-artifact-target-");const zip = join(directory, "fixture.apk");@@ -59,7 +217,9 @@ describe("binary target I/O", () => {error: { _tag: "BinaryTargetError" },});});+});+describe("binary target I/O: filesystem and app bundle target resolution", () => {it("resolves relative Hopper databases and rejects unknown or unreadable paths", async () => {const directory = await createTestTempDirectory("rea-target-");await writeFile(join(directory, "sample.hop"), "database");@@ -137,7 +297,9 @@ describe("binary target I/O", () => {expect((await parseBinaryTarget(app, directory, "arm64")).ok).toBe(false);},);+});+describe("binary target I/O: explicit kinds and executable headers", () => {it("honors an explicit database kind without relying on the file suffix", async () => {const directory = await createTestTempDirectory("rea-target-");await writeFile(join(directory, "saved-analysis"), "database");