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; + readonly realpath: (path: string) => Promise; + readonly decodeBinaryPlist?: (path: string) => Promise; +} + +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> => { - 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 => { 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 => { const wrapper = join(bundle, "Wrapper"); @@ -111,20 +167,45 @@ const wrappedBundle = async (bundle: string): Promise => { const resolveLayoutExecutable = async ( bundle: string, layout: BundleLayout, + fileSystem: AppBundleFileSystem, ): Promise> => { 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"), + "CFBundleExecutableApp", + ); + 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"), + "", + ); + 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");