Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(target): preserve app bundle filesystem failure reasons

morlutod4c2c3c18f69
diff --git a/src/application/AppBundleExecutable.ts b/src/application/AppBundleExecutable.ts
index 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.ts
index 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");