rea-agents 5.0.0 → 6.1.0

package/dist/artifacts/MachOSliceArtifactReader.js

@@ -1,8 +1,9 @@
 import { createReadStream } from "node:fs";
-import { stat } from "node:fs/promises";
+import { open as openFile, stat } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { XcrunCommandRunner, } from "../native/CommandRunner.js";
-import { parseLipoArchitectures } from "../native/parsers/lipo.js";
+import { parseLipoArchitectures, } from "../native/parsers/lipo.js";
+import { readMachoImage } from "./apple/MachoLoadCommandReader.js";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 import { streamChunkToBuffer } from "./StreamBytes.js";
 /** Read-only universal Mach-O slice reader backed by native lipo metadata. */
@@ -28,28 +29,75 @@ export class MachOSliceArtifactReader {
             effects: ["read"],
         };
         const fileSize = (await stat(this.path)).size;
-        for (const architecture of parseLipoArchitectures(captured.value.stdout)) {
-            if (architecture.file_offset === null || architecture.size === null)
+        const architectures = parseLipoArchitectures(captured.value.stdout);
+        const structural = await readStructuralSlices(this.path, fileSize);
+        if (structural.status === "malformed")
+            throw new ArtifactReaderFailure("integrity", `Mach-O structural slice index is malformed: ${structural.reason}`);
+        if (structural.status === "unsupported")
+            throw new ArtifactReaderFailure("format", `Mach-O structural slice index is unsupported: ${structural.reason}`);
+        const slices = structural.status === "parsed" ? structural.slices : null;
+        const matchingSlices = new Map();
+        if (slices !== null) {
+            if (slices.length !== architectures.length)
+                throw new ArtifactReaderFailure("integrity", "lipo architecture count disagrees with the Mach-O FAT table");
+            const unmatched = [...slices];
+            for (const reported of architectures) {
+                const match = unmatched.findIndex((observed) => lipoMatchesSlice(reported, observed, slices.length === 1));
+                if (match < 0)
+                    throw new ArtifactReaderFailure("integrity", `lipo slice metadata disagrees with the Mach-O FAT table: ${reported.name} (cputype=${reported.cpu_type ?? "unknown"}, cpusubtype=${reported.cpu_subtype ?? "unknown"}, offset=${reported.file_offset ?? "unknown"}, size=${reported.size ?? "unknown"}, alignment=${reported.alignment ?? "unknown"})`);
+                const [observed] = unmatched.splice(match, 1);
+                if (observed !== undefined)
+                    matchingSlices.set(reported, observed);
+            }
+        }
+        for (const architecture of architectures) {
+            const structuralSlice = matchingSlices.get(architecture);
+            const offset = architecture.file_offset ?? structuralSlice?.slice_offset;
+            const sliceSize = architecture.size ?? structuralSlice?.slice_size;
+            if (offset === undefined || sliceSize === undefined)
                 throw new ArtifactReaderFailure("integrity", "lipo omitted a universal slice byte range");
-            if (!Number.isSafeInteger(architecture.file_offset) ||
-                !Number.isSafeInteger(architecture.size) ||
-                architecture.file_offset < 0 ||
-                architecture.size <= 0 ||
-                !Number.isSafeInteger(architecture.file_offset + architecture.size) ||
-                architecture.file_offset + architecture.size > fileSize)
+            if (!Number.isSafeInteger(offset) ||
+                !Number.isSafeInteger(sliceSize) ||
+                offset < 0 ||
+                sliceSize <= 0 ||
+                !Number.isSafeInteger(offset + sliceSize) ||
+                offset + sliceSize > fileSize)
                 throw new ArtifactReaderFailure("integrity", `lipo reported an out-of-bounds Mach-O slice: ${architecture.name}`);
             yield {
                 path: `slices/${architecture.name}`,
                 kind: "slice",
-                declaredSize: architecture.size,
+                declaredSize: sliceSize,
                 compressedSize: null,
                 executable: true,
                 encrypted: false,
-                byteOffset: architecture.file_offset,
+                byteOffset: offset,
                 declaredSha256: null,
                 unpacked: false,
-                limitations: [],
-                adapterKey: `${String(architecture.file_offset)}:${String(architecture.size)}`,
+                limitations: [
+                    ...(structural.status === "not-mach-o"
+                        ? [
+                            "Structural Mach-O facts were unavailable; slice range is based on lipo output.",
+                        ]
+                        : []),
+                    ...(architecture.file_offset === null || architecture.size === null
+                        ? [
+                            "Slice range was derived from structural Mach-O facts because lipo omitted it.",
+                        ]
+                        : []),
+                    ...(architecture.cpu_type !== null &&
+                        architecture.cpu_type_code === null
+                        ? [
+                            `lipo CPU type is retained as unnormalized source text: ${architecture.cpu_type}`,
+                        ]
+                        : []),
+                    ...(architecture.cpu_subtype !== null &&
+                        architecture.cpu_subtype_code === null
+                        ? [
+                            `lipo CPU subtype is retained as unnormalized source text: ${architecture.cpu_subtype}${architecture.capabilities === null ? "" : `; capabilities ${architecture.capabilities}`}`,
+                        ]
+                        : []),
+                ],
+                adapterKey: `${String(offset)}:${String(sliceSize)}`,
             };
         }
     }
@@ -103,6 +151,42 @@ export class MachOSliceArtifactReader {
         return Promise.resolve();
     }
 }
+/** Compare lipo's independent ranges with structurally parsed slice identity. */
+const readStructuralSlices = async (path, size) => {
+    const file = await openFile(path, "r");
+    try {
+        const readAt = async (offset, length) => {
+            const bytes = Buffer.alloc(length);
+            const { bytesRead } = await file.read(bytes, 0, length, offset);
+            return bytes.subarray(0, bytesRead);
+        };
+        const facts = await readMachoImage(readAt, size);
+        return facts;
+    }
+    finally {
+        await file.close();
+    }
+};
+const lipoMatchesSlice = (reported, observed, structurallyUnique) => {
+    const observedCpuType = observed.fat_cpu_type ?? observed.cpu_type;
+    const observedCpuSubtype = observed.fat_cpu_subtype ?? observed.cpu_subtype;
+    const hasPhysicalIdentity = reported.file_offset !== null ||
+        reported.size !== null ||
+        reported.cpu_type_code !== null ||
+        reported.cpu_subtype_code !== null;
+    return ((hasPhysicalIdentity || structurallyUnique) &&
+        reported.name === observed.architecture &&
+        (reported.file_offset === null ||
+            reported.file_offset === observed.slice_offset) &&
+        (reported.size === null || reported.size === observed.slice_size) &&
+        (reported.cpu_type_code === null ||
+            reported.cpu_type_code === observedCpuType) &&
+        (reported.cpu_subtype_code === null ||
+            reported.cpu_subtype_code === observedCpuSubtype) &&
+        (reported.alignment === null ||
+            observed.fat_alignment_exponent === null ||
+            reported.alignment === 2 ** observed.fat_alignment_exponent));
+};
 const parseSliceKeyInteger = (value) => {
     if (value === undefined || !/^\d+$/u.test(value))
         return null;

package/dist/artifacts/NativeDmgArtifactReader.js

@@ -80,6 +80,7 @@ export class NativeDmgArtifactReader {
     }
     async close() {
         let detachFailure;
+        const remainingDevices = [];
         for (const device of [...this.#devices].reverse()) {
             try {
                 await runChecked(this.host, ["detach", device], undefined, {
@@ -91,17 +92,22 @@ export class NativeDmgArtifactReader {
                 // Detaching a synthesized APFS container also ejects the image that
                 // backs it, so a later whole disk of the same image may already be
                 // gone. Only a device that is still attached is a cleanup failure.
-                if (await this.#isAttached(device))
+                if (await this.#isAttached(device)) {
+                    remainingDevices.push(device);
                     detachFailure ??= cause;
+                }
             }
         }
-        this.#devices = [];
-        if (this.#mountRoot !== undefined)
-            await rm(this.#mountRoot, { recursive: true, force: true }).catch((cause) => {
+        this.#devices = remainingDevices.reverse();
+        if (this.#devices.length === 0 && this.#mountRoot !== undefined)
+            await rm(this.#mountRoot, { recursive: true, force: true }).then(() => {
+                this.#mountRoot = undefined;
+                this.#directory = undefined;
+            }, (cause) => {
                 detachFailure ??= cause;
             });
         if (detachFailure !== undefined)
-            throw new ArtifactReaderFailure("unavailable", "DMG detach or mount-root cleanup failed", { cause: detachFailure });
+            throw new ArtifactReaderFailure("unavailable", `DMG detach or mount-root cleanup failed for ${JSON.stringify(this.path)}: ${failureMessage(detachFailure)}`, { cause: detachFailure });
     }
     /**
      * Report whether hdiutil still lists a device; unknown state counts as
@@ -169,11 +175,12 @@ export class NativeDmgArtifactReader {
                 cleanupFailure = cleanupCause;
             }
             if (cleanupFailure !== undefined)
-                throw new ArtifactReaderFailure("unavailable", "DMG attach failed and cleanup could not detach every device", { cause: new AggregateError([cause, cleanupFailure]) });
+                throw new ArtifactReaderFailure("unavailable", `DMG attach failed and cleanup could not detach every device: ${failureMessage(cause)}; cleanup: ${failureMessage(cleanupFailure)}`, { cause: new AggregateError([cause, cleanupFailure]) });
             throw cause;
         }
     }
 }
+const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
 const runChecked = async (host, arguments_, signal, options) => {
     let result;
     try {

package/dist/artifacts/ZipArtifactReader.js

@@ -39,6 +39,9 @@ export class ZipArtifactReader {
         this.#reader = new ZipReader(this.#source, {
             checkSignature: true,
             checkOverlappingEntry: true,
+            // REA applies its own provider-neutral path validation in scanReader and
+            // must preserve that typed failure instead of zip.js rejecting first.
+            filenameValidation: "tolerant",
         });
     }
     async *entries(signal) {

package/dist/artifacts/apple/AppleAssetCatalogAnalysis.js

@@ -26,11 +26,16 @@ export const analyzeAppleAssetCatalogs = async (input) => {
     const page = appleAssetCatalogInputSchema.parse(input.page ?? {});
     const reader = new DirectoryArtifactReader(input.bundlePath);
     const catalogs = [];
+    const uninspected = [];
     let totalMetadataBytes = 0;
     try {
         for await (const entry of reader.entries(input.signal)) {
-            if (entry.kind !== "file" || !entry.path.endsWith("Assets.car"))
+            if (!entry.path.endsWith("Assets.car"))
                 continue;
+            if (entry.kind !== "file") {
+                uninspected.push(`${entry.path} (${entry.kind})`);
+                continue;
+            }
             const inspected = await inspectAssetCatalogEntry({
                 reader,
                 entry,
@@ -46,8 +51,10 @@ export const analyzeAppleAssetCatalogs = async (input) => {
     finally {
         await reader.close();
     }
-    if (catalogs.length === 0)
-        throw new ArtifactReaderFailure("unavailable", "No compiled Assets.car catalogs were found in the app bundle");
+    // Without any readable catalog, unmatched resource keys would overstate an
+    // absence that a skipped catalog entry may contradict.
+    if (catalogs.length === 0 && uninspected.length > 0)
+        throw new ArtifactReaderFailure("path", `Asset catalog entries are not regular files and were not inspected: ${uninspected.join(", ")}`);
     const interfaceBuilder = await analyzeInterfaceBuilderBundle({
         bundlePath: input.bundlePath,
         targetSha256: input.targetSha256,
@@ -65,6 +72,18 @@ export const analyzeAppleAssetCatalogs = async (input) => {
         ...result,
         limitations: [
             ...result.limitations,
+            // An app without a compiled catalog is an observed empty inventory, not
+            // a missing host tool.
+            ...(catalogs.length === 0
+                ? [
+                    "No compiled Assets.car catalog was found among the app bundle's regular files (symlinks are not followed); any resource keys are reported as unmatched.",
+                ]
+                : []),
+            ...(uninspected.length === 0
+                ? []
+                : [
+                    `Asset catalog entries that are not regular files were not inspected, so resource keys reported as unmatched may resolve there: ${uninspected.join(", ")}`,
+                ]),
             "Exact resource-key joins use only recognized image or asset key fields on decoded Interface Builder resource objects; other archive resource references are not inferred.",
             ...(interfaceBuilder.graph.truncated
                 ? [

package/dist/artifacts/apple/DylibResolutionReader.js

@@ -0,0 +1,259 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readlink, realpath } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { resolveTreePath } from "../../domain/apple/dyldPaths.js";
+import { dylibResolutionInputSchema, dylibResolutionResultSchema, traceDylibLoading, } from "../../domain/apple/dylibResolution.js";
+import { ArtifactReaderFailure } from "../ArtifactReader.js";
+import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
+import { hasMachoMagic, readMachoImage } from "./MachoLoadCommandReader.js";
+const HASH_CHUNK_BYTES = 1024 * 1024;
+/** Lazily probed, symlink-preserving view of one analyzed directory. */
+class FilesystemTreeView {
+    root;
+    signal;
+    #entries = new Map();
+    #images = new Map();
+    #identities = new Map();
+    constructor(root, signal) {
+        this.root = root;
+        this.signal = signal;
+    }
+    entry(path) {
+        const cached = this.#entries.get(path);
+        if (cached !== undefined)
+            return cached;
+        const pending = this.#readEntry(path);
+        this.#entries.set(path, pending);
+        return pending;
+    }
+    image(path) {
+        const cached = this.#images.get(path);
+        if (cached !== undefined)
+            return cached;
+        const pending = readImage(join(this.root, path), this.signal).then(({ facts, identity }) => {
+            this.#identities.set(path, identity);
+            return facts;
+        });
+        this.#images.set(path, pending);
+        return pending;
+    }
+    /** Identity of the file whose header bytes `image()` parsed. */
+    identity(path) {
+        return this.#identities.get(path);
+    }
+    async #readEntry(path) {
+        cancelled(this.signal);
+        const absolute = join(this.root, path);
+        try {
+            const metadata = await lstat(absolute);
+            if (metadata.isSymbolicLink())
+                return { kind: "symlink", target: await readlink(absolute) };
+            if (metadata.isDirectory())
+                return { kind: "directory" };
+            return metadata.isFile() ? { kind: "file" } : undefined;
+        }
+        catch (cause) {
+            if (missing(cause))
+                return undefined;
+            throw cause;
+        }
+    }
+}
+/** Resolve dyld load paths for the active Mach-O or every executable in its bundle. */
+export const traceDylibResolution = async (options) => {
+    const parsed = dylibResolutionInputSchema.safeParse(options.parameters);
+    if (!parsed.success)
+        throw new ArtifactReaderFailure("path", "roots must be normalized paths relative to the analyzed root");
+    // Canonicalization is inside the translated region: a revoked permission
+    // keeps its reason and path.
+    let root = options.rootPath;
+    try {
+        root = await realpath(options.rootPath);
+        const target = relative(root, await realpath(options.targetPath))
+            .split(sep)
+            .join("/");
+        const view = new FilesystemTreeView(root, options.signal);
+        const { roots: requested, unclassified } = parsed.data.roots !== undefined
+            ? { roots: parsed.data.roots, unclassified: [] }
+            : options.enumerateRoots
+                ? await executableRoots(root, view, options.signal)
+                : { roots: [target], unclassified: [] };
+        const roots = await requireMachoRoots(view, requested);
+        const trace = await traceDylibLoading(view, {
+            roots,
+            unclassified,
+            ...(parsed.data.architecture === undefined
+                ? {}
+                : { architecture: parsed.data.architecture }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
+        // Each digest must describe the same file whose headers were parsed.
+        const digests = new Map();
+        for (const { path } of trace.images)
+            digests.set(path, await fileSha256(join(root, path), {
+                path,
+                expected: view.identity(path),
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+            }));
+        const targetDigest = digests.get(target) ??
+            (await fileSha256(join(root, target), {
+                path: target,
+                expected: undefined,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+            }));
+        if (targetDigest !== options.targetSha256)
+            throw new ArtifactReaderFailure("integrity", `Active target digest changed: expected ${options.targetSha256}, observed ${targetDigest}`);
+        return dylibResolutionResultSchema.parse({
+            ...trace,
+            root_path: options.rootPath,
+            target_sha256: options.targetSha256,
+            images: trace.images.map((image) => ({
+                ...image,
+                sha256: digests.get(image.path),
+            })),
+        });
+    }
+    catch (cause) {
+        if (options.signal?.aborted === true)
+            throw new ArtifactReaderFailure("cancelled", "Dylib resolution was cancelled", { cause });
+        const denied = permissionDenied(cause);
+        if (denied !== undefined)
+            throw new ArtifactReaderFailure("unavailable", `Permission denied (${denied.code}) reading ${deniedPath(root, denied.path)}`, { cause });
+        throw cause;
+    }
+};
+/**
+ * Every Mach-O in the bundle with an executable slice is its own process root.
+ * Mach-O files that do not parse are returned separately: whether they are
+ * executables is unknown, so they make coverage partial instead of vanishing.
+ */
+const executableRoots = async (root, view, signal) => {
+    const roots = [];
+    const unclassified = [];
+    for await (const entry of new DirectoryArtifactReader(root).entries(signal)) {
+        if (entry.kind !== "file" ||
+            !(await startsWithMachoMagic(entry.adapterKey)))
+            continue;
+        const facts = await view.image(entry.path);
+        if (facts.status === "malformed" || facts.status === "unsupported")
+            unclassified.push(entry.path);
+        else if (facts.status === "parsed" &&
+            facts.slices.some(({ file_type: type }) => type === "execute"))
+            roots.push(entry.path);
+    }
+    return {
+        roots: roots.sort(compare),
+        unclassified: unclassified.sort(compare),
+    };
+};
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+/**
+ * Resolve each root segment by segment, as dependency candidates are, so a
+ * symlink in an intermediate directory cannot lead outside the analyzed root.
+ */
+const requireMachoRoots = async (view, roots) => {
+    const resolved = [];
+    for (const path of roots) {
+        const lookup = await resolveTreePath(view, path);
+        if (lookup.kind === "escapes")
+            throw new ArtifactReaderFailure("path", `Root ${path} resolves outside the analyzed root`);
+        if (lookup.kind !== "file")
+            throw new ArtifactReaderFailure("path", `Root ${path} is not a regular file in the analyzed root`);
+        if ((await view.image(lookup.path)).status === "not-mach-o")
+            throw new ArtifactReaderFailure("format", `Root ${path} is not a Mach-O image`);
+        if (!resolved.includes(lookup.path))
+            resolved.push(lookup.path);
+    }
+    return resolved;
+};
+const startsWithMachoMagic = async (path) => {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const buffer = new Uint8Array(4);
+        const { bytesRead } = await handle.read(buffer, 0, 4, 0);
+        return hasMachoMagic(buffer.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+};
+const identityOf = (metadata) => [
+    metadata.dev,
+    metadata.ino,
+    metadata.size,
+    metadata.mtimeNs,
+    metadata.ctimeNs,
+].join(":");
+const readImage = async (path, signal) => {
+    cancelled(signal);
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const metadata = await handle.stat({ bigint: true });
+        const size = Number(metadata.size);
+        const facts = await readMachoImage(async (offset, length) => {
+            cancelled(signal);
+            const buffer = new Uint8Array(Math.max(0, Math.min(length, size - offset)));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+            return buffer.subarray(0, bytesRead);
+        }, size);
+        return { facts, identity: identityOf(metadata) };
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** Hash a file, failing if it is not the file (or the version) that was parsed. */
+const fileSha256 = async (absolute, options) => {
+    const { signal } = options;
+    const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const unchanged = async () => {
+        if (options.expected !== undefined &&
+            identityOf(await handle.stat({ bigint: true })) !== options.expected)
+            throw new ArtifactReaderFailure("integrity", `${options.path} changed while its dyld load commands were traced`);
+    };
+    try {
+        await unchanged();
+        const hash = createHash("sha256");
+        const buffer = new Uint8Array(HASH_CHUNK_BYTES);
+        for (;;) {
+            cancelled(signal);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+        }
+        await unchanged();
+        return hash.digest("hex");
+    }
+    finally {
+        await handle.close();
+    }
+};
+const cancelled = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "Dylib resolution was cancelled");
+};
+/** A denied path relative to the analyzed root, or absolute when outside it. */
+const deniedPath = (root, path) => {
+    if (path === undefined)
+        return "a file in the analyzed root";
+    const inside = relative(root, path);
+    return inside === "" || inside.startsWith("..") ? path : inside;
+};
+/** Host permission denials, kept distinct from malformed or missing files. */
+const permissionDenied = (cause) => {
+    if (!(cause instanceof Error) || !("code" in cause))
+        return undefined;
+    if (cause.code !== "EACCES" && cause.code !== "EPERM")
+        return undefined;
+    return {
+        code: cause.code,
+        path: "path" in cause && typeof cause.path === "string"
+            ? cause.path
+            : undefined,
+    };
+};
+const missing = (cause) => cause instanceof Error &&
+    "code" in cause &&
+    (cause.code === "ENOENT" || cause.code === "ENOTDIR");