reverseport 0.0.0-stage → 1.2.0

package/dist/domain/apple/appleAssetCatalog.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { jsonValueSchema } from "../jsonValue.js";
+import { AnalysisOutputError } from "../analysisErrorCore.js";
+/** Caller-controlled page bounds for compiled Apple asset metadata. */
+export const appleAssetCatalogInputSchema = z.strictObject({
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(10_000).default(1_000),
+});
+const catalogSchema = z.strictObject({
+    path: z.string().min(1),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    record_count: z.number().int().nonnegative(),
+});
+const recordSchema = z.strictObject({
+    catalog_path: z.string().min(1),
+    catalog_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    index: z.number().int().nonnegative(),
+    kind: z.enum(["catalog", "rendition"]),
+    asset_name: z.string().nullable(),
+    rendition_name: z.string().nullable(),
+    metadata: z.record(z.string(), jsonValueSchema),
+});
+const resourceKeyMatchSchema = z.strictObject({
+    source_node_id: z.string().min(1),
+    source_path: z.string().min(1),
+    source_archive_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    field: z.string().min(1),
+    key: z.string().min(1),
+    status: z.enum(["matched", "ambiguous", "unmatched"]),
+    renditions: z.array(z.strictObject({
+        catalog_path: z.string().min(1),
+        catalog_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        record_index: z.number().int().nonnegative(),
+        rendition_name: z.string().nullable(),
+    })),
+});
+/** Normalized result returned by asset catalog inspection. */
+export const appleAssetCatalogResultSchema = z.strictObject({
+    target_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    catalogs: z.array(catalogSchema),
+    total_records: z.number().int().nonnegative(),
+    offset: z.number().int().nonnegative(),
+    limit: z.number().int().positive(),
+    records: z.array(recordSchema),
+    resource_key_matches: z.array(resourceKeyMatchSchema),
+    next_offset: z.number().int().nonnegative().nullable(),
+    truncated: z.boolean(),
+    limitations: z.array(z.string()),
+});
+/** Parse assetutil JSON records without discarding format-specific metadata. */
+export const parseAppleAssetCatalogRecords = (value) => {
+    if (!Array.isArray(value))
+        throw new AnalysisOutputError("inspect_asset_catalog", "assetutil output must be a JSON array");
+    return value.map((record, index) => {
+        const parsed = z.record(z.string(), jsonValueSchema).safeParse(record);
+        if (!parsed.success)
+            throw new AnalysisOutputError("inspect_asset_catalog", `assetutil record ${index} is not a JSON object`, { cause: parsed.error });
+        return parsed.data;
+    });
+};
+/** Project catalog records and apply stable global pagination. */
+export const projectAppleAssetCatalogPage = (input) => {
+    const all = input.catalogs.flatMap((catalog) => catalog.records.map((metadata, index) => ({
+        catalog_path: catalog.path,
+        catalog_sha256: catalog.sha256,
+        index,
+        kind: typeof metadata.RenditionName === "string" ||
+            typeof metadata.Name === "string"
+            ? "rendition"
+            : "catalog",
+        asset_name: typeof metadata.Name === "string" ? metadata.Name : null,
+        rendition_name: typeof metadata.RenditionName === "string"
+            ? metadata.RenditionName
+            : null,
+        metadata,
+    })));
+    const records = all.slice(input.offset, input.offset + input.limit);
+    const next = input.offset + records.length;
+    const recordsByAssetName = new Map();
+    for (const record of all) {
+        if (record.kind !== "rendition" || record.asset_name === null)
+            continue;
+        const matches = recordsByAssetName.get(record.asset_name) ?? [];
+        matches.push(record);
+        recordsByAssetName.set(record.asset_name, matches);
+    }
+    const resourceKeyMatches = (input.resourceReferences ?? []).map((source) => {
+        const matches = recordsByAssetName.get(source.key) ?? [];
+        return {
+            source_node_id: source.sourceNodeId,
+            source_path: source.sourcePath,
+            source_archive_sha256: source.sourceArchiveSha256,
+            field: source.field,
+            key: source.key,
+            status: matches.length === 0
+                ? "unmatched"
+                : matches.length === 1
+                    ? "matched"
+                    : "ambiguous",
+            renditions: matches.map((record) => ({
+                catalog_path: record.catalog_path,
+                catalog_sha256: record.catalog_sha256,
+                record_index: record.index,
+                rendition_name: record.rendition_name,
+            })),
+        };
+    });
+    return appleAssetCatalogResultSchema.parse({
+        target_sha256: input.targetSha256,
+        catalogs: input.catalogs.map(({ path, sha256, records: catalogRecords }) => ({
+            path,
+            sha256,
+            record_count: catalogRecords.length,
+        })),
+        total_records: all.length,
+        offset: input.offset,
+        limit: input.limit,
+        records,
+        resource_key_matches: resourceKeyMatches,
+        next_offset: next < all.length ? next : null,
+        truncated: input.offset > 0 || next < all.length,
+        limitations: [
+            "Rendition metadata is reported as emitted by the installed assetutil version; private fields and platform-specific interpretations are not normalized.",
+            "Asset catalog inspection does not decode or extract rendition image bytes.",
+        ],
+    });
+};

package/dist/domain/apple/appleBundleAnatomy.js

@@ -0,0 +1,303 @@
+import { z } from "zod";
+import { digestSchema, prefixedDigestSchema } from "../digests.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 = ["mach-o", "mach-o-universal"];
+/** One inventoried file or directory with its content identity. */
+export const appleComponentSchema = z.strictObject({
+    path: pathSchema,
+    artifact_id: prefixedDigestSchema("art"),
+    sha256: digestSchema,
+    format: z.string().min(1),
+});
+/** 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),
+});
+/** Report whether an inventory format is a thin or universal Mach-O. */
+export const isMachOFormat = (format) => MACH_O_FORMATS.includes(format);
+/** AppleDouble metadata written beside archived files (`._name`, `__MACOSX/`). */
+export const isSidecar = (path) => {
+    const segments = path.split("/");
+    return (segments.includes("__MACOSX") || (segments.at(-1) ?? "").startsWith("._"));
+};
+export const isWithin = (path, root) => 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, expected) => actual.toLocaleLowerCase("en-US") === expected.toLocaleLowerCase("en-US");
+/** Directory entry that folds to one vocabulary word. The exact spelling wins. */
+export const anatomyChild = (names, expected) => {
+    if (names === undefined)
+        return null;
+    let exact;
+    let folded;
+    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, expected) => {
+    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);
+    });
+};
+/**
+ * Outermost iOS (`Payload/X.app`) and macOS (`X.app/Contents/…`) applications.
+ * An inventoried `.app` directory is its own root, `.`.
+ */
+export const applicationRoots = (entries, subject) => {
+    // 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();
+    for (const { path } of entries) {
+        if (isSidecar(path))
+            continue;
+        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);
+};
+export const detectBundles = (entries, roots) => {
+    const paths = new Set(roots);
+    for (const { path, kind } of entries) {
+        if (isSidecar(path))
+            continue;
+        const root = roots.find((candidate) => isWithin(path, candidate));
+        if (root === undefined)
+            continue;
+        const segments = path.split("/");
+        const start = root === "." ? 0 : root.split("/").length;
+        for (let index = start; index < segments.length; index++) {
+            const segment = segments[index] ?? "";
+            const leaf = index === segments.length - 1;
+            // A symlink or file named like a bundle has no observed contents.
+            if (BUNDLE_EXTENSION.test(segment) && (!leaf || kind === "directory"))
+                paths.add(segments.slice(0, index + 1).join("/"));
+        }
+    }
+    const tree = indexTree(entries);
+    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),
+        };
+    });
+};
+const indexTree = (entries) => {
+    const children = new Map();
+    const files = new Map();
+    const directories = new Set();
+    for (const { path, kind, component } of entries) {
+        if (isSidecar(path))
+            continue;
+        if (kind === "file" && component !== undefined)
+            files.set(path, component);
+        if (kind === "directory")
+            directories.add(path);
+        const segments = path.split("/");
+        let parent = "";
+        for (const segment of segments) {
+            const names = children.get(parent) ?? new Set();
+            names.add(segment);
+            children.set(parent, names);
+            parent = joinPath(parent, segment);
+            if (parent !== path)
+                directories.add(parent);
+        }
+    }
+    return { children, files, directories };
+};
+const joinPath = (directory, name) => directory === "" ? name : `${directory}/${name}`;
+const directoryOf = (bundle) => (bundle === "." ? "" : bundle);
+const enclosingBundle = (path, bundles) => {
+    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, tree) => {
+    const names = tree.children.get(directoryOf(bundle));
+    if (anatomyChild(names, "Contents") !== null)
+        return "macos-deep";
+    if (anatomyChild(names, "Versions") !== null)
+        return "versioned-framework";
+    return "shallow";
+};
+const bundleRole = (bundle) => {
+    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, tree) => [...(tree.children.get(directory) ?? [])]
+    .map((name) => joinPath(directory, name))
+    .filter((path) => tree.files.has(path))
+    .sort(compare);
+/** Content directories; `Versions/Current` is a symlink outside the inventory. */
+const contentDirectories = (bundle, layout, tree) => {
+    const directory = directoryOf(bundle);
+    if (layout === "macos-deep") {
+        const contents = namedChild(tree, directory, "Contents");
+        return contents === null ? [] : [contents];
+    }
+    if (layout === "shallow")
+        return [directory];
+    const versions = namedChild(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.children.get(versions) ?? [])]
+        .filter((version) => !anatomyNameIs(version, "Current"))
+        .map((version) => joinPath(versions, version))
+        .filter((version) => tree.directories.has(version))
+        .sort(compare);
+};
+/** Child path using the archive's spelling of one anatomy name. */
+const namedChild = (tree, directory, expected) => {
+    const name = anatomyChild(tree.children.get(directory), expected);
+    return name === null ? null : joinPath(directory, name);
+};
+const infoPlistPath = (bundle, layout, tree) => {
+    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"
+        ? namedChild(tree, directory, "Resources")
+        : directory;
+    if (parent === null)
+        return null;
+    const info = namedChild(tree, parent, "Info.plist");
+    return info !== null && tree.files.has(info) ? info : null;
+};
+const executableCandidates = (bundle, layout, tree) => contentDirectories(bundle, layout, tree)
+    .flatMap((directory) => {
+    const executableDirectory = layout === "macos-deep"
+        ? namedChild(tree, directory, "MacOS")
+        : directory;
+    return executableDirectory === null
+        ? []
+        : directFiles(executableDirectory, tree);
+})
+    .filter((path) => MACH_O_FORMATS.includes(tree.files.get(path)?.format ?? ""));
+const signingPaths = (bundle, layout, tree) => contentDirectories(bundle, layout, tree)
+    .flatMap((directory) => {
+    const signature = namedChild(tree, directory, "_CodeSignature");
+    return [
+        signature === null
+            ? null
+            : namedChild(tree, signature, "CodeResources"),
+        namedChild(tree, directory, "embedded.provisionprofile"),
+        namedChild(tree, directory, "embedded.mobileprovision"),
+    ];
+})
+    .filter((path) => path !== null && tree.files.has(path))
+    .sort(compare);
+/** Platforms of application roots whose layout was observed, not assumed. */
+export const platformsOf = (bundles) => [
+    ...new Set(bundles.flatMap(({ role, layout, info_plist_path: plist }) => {
+        if (role !== "application")
+            return [];
+        if (layout === "macos-deep")
+            return ["macos"];
+        // An empty or partial root has no Contents/ either; require Info.plist.
+        if (layout === "shallow" && plist !== null)
+            return ["ios"];
+        return [];
+    })),
+].sort(compare);
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;

package/dist/domain/apple/dyldEnvironment.js

@@ -0,0 +1,73 @@
+/** Retain recognized image-selection settings separately from diagnostic observations. */
+export const embeddedDyldOverrides = (environment, platforms) => {
+    const overrides = [];
+    for (const setting of environment) {
+        const delimiter = setting.indexOf("=");
+        if (delimiter <= 0)
+            continue;
+        const variable = setting.slice(0, delimiter);
+        const value = setting.slice(delimiter + 1);
+        const effect = overrideEffect(variable, value);
+        if (effect === undefined)
+            continue;
+        // ROOT_PATH is accepted only for simulator processes. Missing or unknown
+        // platform metadata cannot establish that dyld ignores it.
+        if (variable === "DYLD_ROOT_PATH" &&
+            platforms.length > 0 &&
+            platforms.every((platform) => platform >= 1 && platform <= 12) &&
+            !platforms.some((platform) => [7, 8, 9, 12].includes(platform)))
+            continue;
+        overrides.push({ variable, value, ...effect });
+    }
+    return overrides;
+};
+const overrideEffect = (variable, value) => {
+    switch (variable) {
+        // Empty directory components still produce /leaf candidates in dyld.
+        // In particular, an empty fallback value is not a no-op.
+        case "DYLD_LIBRARY_PATH":
+            return { phase: "override", scope: "library" };
+        case "DYLD_FRAMEWORK_PATH":
+            return { phase: "override", scope: "framework" };
+        case "DYLD_FALLBACK_LIBRARY_PATH":
+            return { phase: "fallback", scope: "library" };
+        case "DYLD_FALLBACK_FRAMEWORK_PATH":
+            return { phase: "fallback", scope: "framework" };
+        // Versioned paths map discovered images to their reported install names,
+        // so the directory's kind does not establish the replaced image's kind.
+        case "DYLD_VERSIONED_LIBRARY_PATH":
+        case "DYLD_VERSIONED_FRAMEWORK_PATH":
+        case "DYLD_IMAGE_SUFFIX":
+            // Versioned paths scan directories; suffixes create path variants.
+            // Empty directories cannot be scanned and empty suffixes repeat a path.
+            return /[^:]/u.test(value)
+                ? { phase: "override", scope: "all" }
+                : undefined;
+        case "DYLD_INSERT_LIBRARIES":
+            return value === "" ? undefined : { phase: "override", scope: "all" };
+        case "DYLD_ROOT_PATH":
+        case "DYLD_OVERLAY_PATH":
+            return value === "" ? undefined : { phase: "override", scope: "prefix" };
+        default:
+            return undefined;
+    }
+};
+const isFrameworkInstallName = (name, overrides) => {
+    const separator = name.lastIndexOf(".framework/");
+    if (separator < 0)
+        return false;
+    const framework = name.slice(0, separator).split("/").at(-1);
+    const leaf = name.slice(name.lastIndexOf("/") + 1);
+    return (leaf === framework ||
+        overrides.some(({ variable, value }) => variable === "DYLD_IMAGE_SUFFIX" && leaf === `${framework}${value}`));
+};
+/** Select only settings that can affect this dependency at its reached search phase. */
+export const hasApplicableDyldOverrides = (overrides, installName, ordinarySearchFoundImage) => {
+    const kind = isFrameworkInstallName(installName, overrides)
+        ? "framework"
+        : "library";
+    return overrides.some(({ phase, scope }) => (phase === "override" || !ordinarySearchFoundImage) &&
+        (scope === "all" ||
+            scope === kind ||
+            (scope === "prefix" && !installName.startsWith("@"))));
+};

package/dist/domain/apple/dyldPaths.js

@@ -0,0 +1,89 @@
+const MAX_SYMLINK_HOPS = 32;
+/**
+ * Resolve a root-relative path one segment at a time, as `open` would:
+ * symlinks are followed inside the root, `..` applies to the real parent,
+ * and any escape above the root or through an absolute link stops.
+ */
+export const resolveTreePath = async (view, input) => {
+    const pending = segmentsOf(input);
+    const resolved = [];
+    let last;
+    let hops = 0;
+    while (pending.length > 0) {
+        const segment = pending.shift() ?? "";
+        if (segment === ".")
+            continue;
+        if (segment === "..") {
+            if (resolved.length === 0)
+                return { kind: "escapes" };
+            resolved.pop();
+            last = { kind: "directory" };
+            continue;
+        }
+        const path = [...resolved, segment].join("/");
+        const entry = await view.entry(path);
+        if (entry === undefined)
+            return { kind: "absent" };
+        if (entry.kind === "symlink") {
+            hops += 1;
+            if (hops > MAX_SYMLINK_HOPS)
+                return { kind: "absent" };
+            if (entry.target.startsWith("/"))
+                return { kind: "escapes" };
+            pending.unshift(...segmentsOf(entry.target));
+            continue;
+        }
+        if (entry.kind === "file" && pending.length > 0)
+            return { kind: "absent" };
+        resolved.push(segment);
+        last = entry;
+    }
+    return last?.kind === "file"
+        ? { kind: "file", path: resolved.join("/") }
+        : { kind: "not-file" };
+};
+const segmentsOf = (path) => {
+    const segments = path.split("/").filter((segment) => segment !== "");
+    // a trailing slash requires a directory, just like a final dot component.
+    if (path.endsWith("/"))
+        segments.push(".");
+    return segments;
+};
+export const directoryOf = (path) => {
+    const index = path.lastIndexOf("/");
+    return index < 0 ? "" : path.slice(0, index);
+};
+export const joinPath = (directory, rest) => directory === "" ? rest : rest === "" ? directory : `${directory}/${rest}`;
+/** Expand one dyld path prefix relative to its owning image. */
+export const expandPrefix = (raw, context) => {
+    const variable = /^@(executable_path|loader_path)(?:\/(.*))?$/u.exec(raw);
+    if (variable !== null) {
+        const rest = variable[2] ?? "";
+        if (variable[1] === "loader_path")
+            return { scope: "target", path: joinPath(context.ownerDirectory, rest) };
+        return context.executable === null
+            ? { scope: "undetermined", path: raw }
+            : {
+                scope: "target",
+                path: joinPath(directoryOf(context.executable), rest),
+            };
+    }
+    if (raw.startsWith("/"))
+        return { scope: "outside", path: raw };
+    return { scope: "undetermined", path: raw };
+};
+/**
+ * Slices a process may load, best first, following dyld's graded
+ * architectures: an x86_64h process also accepts generic x86_64.
+ */
+const COMPATIBLE_ARCHITECTURES = {
+    x86_64h: ["x86_64h", "x86_64"],
+};
+export const compatibleSlice = (slices, process) => {
+    for (const architecture of COMPATIBLE_ARCHITECTURES[process] ?? [process]) {
+        const slice = slices.find((item) => item.architecture === architecture);
+        if (slice !== undefined)
+            return slice;
+    }
+    return undefined;
+};