Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
import { z } from "zod";
import type {
ProjectedComponent as Component,
ProjectedInventoryEntry,
} from "../mobileApplicationGraphProjection.js";
import { compareUnicodeCodePoints as compare } from "../unicodeCodePointOrder.js";
const pathSchema = z.string().min(1);
const BUNDLE_EXTENSION =
/\.(?:app|appex|xpc|framework|systemextension|dext|bundle|plugin|qlgenerator|mdimporter)$/iu;
const MACH_O_FORMATS: readonly string[] = ["mach-o", "mach-o-universal"];
/** One application root or nested bundle classified by path convention. */
export const appleBundleSchema = z.strictObject({
path: pathSchema,
parent_path: pathSchema.nullable(),
layout: z.enum(["shallow", "macos-deep", "versioned-framework"]),
role: z.enum([
"application",
"app-extension",
"xpc-service",
"framework",
"login-item",
"system-extension",
"driver-extension",
"plug-in",
"resource-bundle",
"bundle",
"helper-application",
"nested-application",
]),
role_basis: z.literal("path-convention"),
info_plist_path: pathSchema.nullable(),
executable_candidates: z.array(pathSchema),
signing_paths: z.array(pathSchema),
});
type Bundle = z.infer<typeof appleBundleSchema>;
type Entry = Pick<ProjectedInventoryEntry, "path" | "kind" | "component">;
/** Report whether an inventory format is a thin or universal Mach-O. */
export const isMachOFormat = (format: string): boolean =>
MACH_O_FORMATS.includes(format);
/** AppleDouble metadata written beside archived files (`._name`, `__MACOSX/`). */
export const isSidecar = (path: string): boolean => {
const segments = path.split("/");
return (
segments.includes("__MACOSX") || (segments.at(-1) ?? "").startsWith("._")
);
};
export const isWithin = (path: string, root: string): boolean =>
root === "." || path === root || path.startsWith(`${root}/`);
/**
* English (en-US) case fold used only for Apple's fixed anatomy vocabulary.
* Reported paths keep the archive spelling. Inventory identity stays case-sensitive.
*/
export const anatomyNameIs = (actual: string, expected: string): boolean =>
actual.toLocaleLowerCase("en-US") === expected.toLocaleLowerCase("en-US");
/** Directory entry that folds to one vocabulary word. The exact spelling wins. */
export const anatomyChild = (
names: Iterable<string> | undefined,
expected: string,
): string | null => {
if (names === undefined) return null;
let exact: string | undefined;
let folded: string | undefined;
for (const name of names) {
if (name === expected) exact = name;
else if (
anatomyNameIs(name, expected) &&
(folded === undefined || compare(name, folded) < 0)
)
folded = name;
}
return exact ?? folded ?? null;
};
/**
* Whether `path`'s tail matches anatomy vocabulary. `*` matches one segment
* that is not itself a vocabulary comparison.
*/
export const anatomyTailMatches = (
path: string,
expected: readonly string[],
): boolean => {
const actual = path.split("/");
if (actual.length < expected.length) return false;
const tail = actual.slice(-expected.length);
return expected.every((name, index) => {
const segment = tail[index];
if (segment === undefined || segment.length === 0) return false;
return name === "*" || anatomyNameIs(segment, name);
});
};
/** Interpret bundle roots and anatomy from the same directory and file indexes. */
export const projectAppleBundleAnatomy = (
entries: readonly Entry[],
subject: { readonly name: string; readonly format: string },
) => {
const tree = indexTree(entries);
const roots = applicationRoots(tree, subject);
return { roots, bundles: detectBundles(tree, roots) };
};
/**
* Outermost iOS (`Payload/X.app`) and macOS (`X.app/Contents/…`) applications.
* An inventoried `.app` directory is its own root, `.`.
*/
const applicationRoots = (
tree: Tree,
subject: { readonly name: string; readonly format: string },
): string[] => {
// A selected `.app` directory is the application, even when its inventory
// is partial or lacks Contents/; coverage and limitations describe that.
if (subject.format === "directory" && /\.app$/iu.test(subject.name))
return ["."];
const found = new Set<string>();
for (const path of directoryPaths(tree)) {
const segments = path.split("/");
const app = segments[1];
if (
anatomyNameIs(segments[0] ?? "", "Payload") &&
app !== undefined &&
/\.app$/iu.test(app)
) {
found.add(`${segments[0]}/${app}`);
continue;
}
const index = segments.findIndex(
(segment, position) =>
/\.app$/iu.test(segment) &&
anatomyNameIs(segments[position + 1] ?? "", "Contents"),
);
if (index >= 0) found.add(segments.slice(0, index + 1).join("/"));
}
const roots = [...found];
return roots
.filter(
(root) => !roots.some((other) => other !== root && isWithin(root, other)),
)
.sort(compare);
};
const detectBundles = (tree: Tree, roots: readonly string[]): Bundle[] => {
const paths = new Set<string>(roots);
for (const path of directoryPaths(tree)) {
if (
BUNDLE_EXTENSION.test(path.split("/").at(-1) ?? "") &&
roots.some((root) => isWithin(path, root))
)
paths.add(path);
}
return [...paths].sort(compare).map((path) => {
const layout = bundleLayout(path, tree);
return {
path,
parent_path: enclosingBundle(path, paths),
layout,
role: roots.includes(path) ? "application" : bundleRole(path),
role_basis: "path-convention",
info_plist_path: infoPlistPath(path, layout, tree),
executable_candidates: executableCandidates(path, layout, tree),
signing_paths: signingPaths(path, layout, tree),
} satisfies Bundle;
});
};
/** Keep directory identity separate from authenticated file content before name selection. */
interface Tree {
readonly directories: ReadonlyMap<string, ReadonlySet<string>>;
readonly files: ReadonlyMap<string, ReadonlyMap<string, Component>>;
}
const indexTree = (entries: readonly Entry[]): Tree => {
const directories = new Map<string, Set<string>>();
const files = new Map<string, Map<string, Component>>();
for (const { path, kind, component } of entries) {
if (isSidecar(path)) continue;
const segments = path.split("/");
let parent = "";
for (const [index, segment] of segments.entries()) {
const leaf = index === segments.length - 1;
if (!leaf || kind === "directory") {
const names = directories.get(parent) ?? new Set<string>();
names.add(segment);
directories.set(parent, names);
} else if (kind === "file" && component !== undefined) {
const children = files.get(parent) ?? new Map<string, Component>();
children.set(segment, component);
files.set(parent, children);
}
parent = joinPath(parent, segment);
}
}
return { directories, files };
};
function* directoryPaths(tree: Tree): Iterable<string> {
for (const [parent, names] of tree.directories)
for (const name of names) yield joinPath(parent, name);
}
const joinPath = (directory: string, name: string): string =>
directory === "" ? name : `${directory}/${name}`;
const directoryOf = (bundle: string): string => (bundle === "." ? "" : bundle);
const enclosingBundle = (
path: string,
bundles: ReadonlySet<string>,
): string | null => {
if (path === ".") return null;
const segments = path.split("/");
for (let length = segments.length - 1; length > 0; length--) {
const candidate = segments.slice(0, length).join("/");
if (bundles.has(candidate)) return candidate;
}
return bundles.has(".") ? "." : null;
};
const bundleLayout = (bundle: string, tree: Tree): Bundle["layout"] => {
const directory = directoryOf(bundle);
if (namedDirectory(tree, directory, "Contents") !== null) return "macos-deep";
if (namedDirectory(tree, directory, "Versions") !== null)
return "versioned-framework";
return "shallow";
};
const bundleRole = (bundle: string): Bundle["role"] => {
const segments = bundle.split("/");
const name = (segments.at(-1) ?? "").toLowerCase();
const container = segments.at(-2);
if (name.endsWith(".appex")) return "app-extension";
if (name.endsWith(".xpc")) return "xpc-service";
if (name.endsWith(".framework")) return "framework";
if (name.endsWith(".systemextension")) return "system-extension";
if (name.endsWith(".dext")) return "driver-extension";
if (name.endsWith(".bundle")) {
if (anatomyNameIs(container ?? "", "PlugIns")) return "plug-in";
return anatomyNameIs(container ?? "", "Resources")
? "resource-bundle"
: "bundle";
}
if (!name.endsWith(".app")) return "plug-in";
if (
anatomyNameIs(container ?? "", "LoginItems") &&
anatomyNameIs(segments.at(-3) ?? "", "Library")
)
return "login-item";
if (anatomyNameIs(container ?? "", "Helpers")) return "helper-application";
return "nested-application";
};
/** Files directly inside one directory; nested bundles are deeper paths. */
const directFiles = (directory: string, tree: Tree): Component[] =>
[...(tree.files.get(directory)?.values() ?? [])].sort((left, right) =>
compare(left.path, right.path),
);
/** Content directories; `Versions/Current` is a symlink outside the inventory. */
const contentDirectories = (
bundle: string,
layout: Bundle["layout"],
tree: Tree,
): string[] => {
const directory = directoryOf(bundle);
if (layout === "macos-deep") {
const contents = namedDirectory(tree, directory, "Contents");
return contents === null ? [] : [contents];
}
if (layout === "shallow") return [directory];
const versions = namedDirectory(tree, directory, "Versions");
if (versions === null) return [];
// Only real version directories count: Current is a symlink, and files
// such as .DS_Store are not versions.
return [...(tree.directories.get(versions) ?? [])]
.filter((version) => !anatomyNameIs(version, "Current"))
.map((version) => joinPath(versions, version))
.sort(compare);
};
/** Select applicable entry kinds before applying Apple's case preference. */
const namedDirectory = (
tree: Tree,
directory: string,
expected: string,
): string | null => {
const name = anatomyChild(tree.directories.get(directory), expected);
return name === null ? null : joinPath(directory, name);
};
const namedFile = (
tree: Tree,
directory: string,
expected: string,
): string | null => {
const name = anatomyChild(tree.files.get(directory)?.keys(), expected);
return name === null ? null : joinPath(directory, name);
};
const infoPlistPath = (
bundle: string,
layout: Bundle["layout"],
tree: Tree,
): string | null => {
const directories = contentDirectories(bundle, layout, tree);
// With several real versions, Versions/Current (a symlink outside the
// inventory) decides which plist applies, so the plist stays unknown.
if (directories.length !== 1) return null;
const directory = directories[0];
if (directory === undefined) return null;
const parent =
layout === "versioned-framework"
? namedDirectory(tree, directory, "Resources")
: directory;
if (parent === null) return null;
return namedFile(tree, parent, "Info.plist");
};
const executableCandidates = (
bundle: string,
layout: Bundle["layout"],
tree: Tree,
): string[] =>
contentDirectories(bundle, layout, tree)
.flatMap((directory) => {
const executableDirectory =
layout === "macos-deep"
? namedDirectory(tree, directory, "MacOS")
: directory;
return executableDirectory === null
? []
: directFiles(executableDirectory, tree);
})
.filter(({ format }) => isMachOFormat(format))
.map(({ path }) => path);
const signingPaths = (
bundle: string,
layout: Bundle["layout"],
tree: Tree,
): string[] =>
contentDirectories(bundle, layout, tree)
.flatMap((directory) => {
const signature = namedDirectory(tree, directory, "_CodeSignature");
return [
signature === null ? null : namedFile(tree, signature, "CodeResources"),
namedFile(tree, directory, "embedded.provisionprofile"),
namedFile(tree, directory, "embedded.mobileprovision"),
];
})
.filter((path): path is string => path !== null)
.sort(compare);
/** Platforms of application roots whose layout was observed, not assumed. */
export const platformsOf = (bundles: readonly Bundle[]): ("ios" | "macos")[] =>
[
...new Set(
bundles.flatMap(({ role, layout, info_plist_path: plist }) => {
if (role !== "application") return [];
if (layout === "macos-deep") return ["macos" as const];
// An empty or partial root has no Contents/ either; require Info.plist.
if (layout === "shallow" && plist !== null) return ["ios" as const];
return [];
}),
),
].sort(compare);