rea-agents 4.1.0 → 6.0.0

package/dist/artifacts/NativeDmgArtifactReader.js

@@ -13,21 +13,32 @@ const attachOutputSchema = z.object({
         "mount-point": z.string().optional(),
     })),
 });
+const infoOutputSchema = z.object({
+    images: z.array(z.object({
+        "system-entities": z.array(z.object({ "dev-entry": z.string() })),
+    })),
+});
 const systemHost = {
     async run(arguments_, signal, options) {
         try {
-            const { stdout } = await execFileOutput("/usr/bin/hdiutil", [...arguments_], {
+            const { stdout, stderr } = await execFileOutput("/usr/bin/hdiutil", [...arguments_], {
                 ...(options === undefined ? {} : { timeout: options.timeoutMs }),
                 ...(signal === undefined ? {} : { signal }),
             });
-            return { stdout, exitCode: 0 };
+            return { stdout, stderr, exitCode: 0 };
         }
         catch (cause) {
             if (cause instanceof Error && cause.name === "AbortError")
                 throw new ArtifactReaderFailure("cancelled", "DMG operation cancelled");
-            throw new ArtifactReaderFailure("format", "hdiutil rejected the DMG", {
-                cause,
-            });
+            const exitCode = processExitCode(cause);
+            if (exitCode !== undefined)
+                return {
+                    stdout: processOutput(cause, "stdout"),
+                    stderr: processOutput(cause, "stderr"),
+                    exitCode,
+                    cause,
+                };
+            throw new ArtifactReaderFailure(commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, { cause });
         }
     },
 };
@@ -77,7 +88,11 @@ export class NativeDmgArtifactReader {
                 this.#provenance.push(command(["detach", device], ["mount"]));
             }
             catch (cause) {
-                detachFailure ??= cause;
+                // 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))
+                    detachFailure ??= cause;
             }
         }
         this.#devices = [];
@@ -88,6 +103,23 @@ export class NativeDmgArtifactReader {
         if (detachFailure !== undefined)
             throw new ArtifactReaderFailure("unavailable", "DMG detach or mount-root cleanup failed", { cause: detachFailure });
     }
+    /**
+     * Report whether hdiutil still lists a device; unknown state counts as
+     * attached. Like detach, this cleanup query runs after the inventory
+     * snapshot has captured provenance, so it is not recorded there.
+     */
+    async #isAttached(device) {
+        try {
+            const info = await runChecked(this.host, ["info", "-plist"], undefined, {
+                timeoutMs: DETACH_TIMEOUT_MS,
+            });
+            const parsed = infoOutputSchema.parse(parse(info.stdout));
+            return parsed.images.some((image) => image["system-entities"].some((entity) => entity["dev-entry"] === device));
+        }
+        catch {
+            return true;
+        }
+    }
     async attach(signal) {
         await runChecked(this.host, ["verify", this.path], signal);
         this.#provenance.push(command(["verify", this.path], ["read"]));
@@ -143,11 +175,131 @@ export class NativeDmgArtifactReader {
     }
 }
 const runChecked = async (host, arguments_, signal, options) => {
-    const result = await host.run(arguments_, signal, options);
-    if (result.exitCode !== 0)
-        throw new ArtifactReaderFailure("unavailable", `hdiutil ${arguments_[0] ?? "operation"} failed with a non-zero exit code`);
+    let result;
+    try {
+        result = await host.run(arguments_, signal, options);
+    }
+    catch (cause) {
+        if (cause instanceof ArtifactReaderFailure)
+            throw cause;
+        if (cause instanceof Error && cause.name === "AbortError")
+            throw new ArtifactReaderFailure("cancelled", "DMG operation cancelled", {
+                cause,
+            });
+        throw new ArtifactReaderFailure(commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, { cause });
+    }
+    if (result.exitCode !== 0) {
+        const failure = {
+            command: "/usr/bin/hdiutil",
+            exitCode: result.exitCode,
+            ...(result.cause === undefined
+                ? {}
+                : { code: processExitCode(result.cause) }),
+            stdout: result.stdout,
+            ...(result.stderr === undefined ? {} : { stderr: result.stderr }),
+        };
+        const reason = commandFailureReason(failure, arguments_[0]);
+        const details = describeCommandFailure(failure, arguments_);
+        const unknownVerifyFailure = arguments_[0] === "verify" && reason === "unavailable";
+        throw new ArtifactReaderFailure(reason, unknownVerifyFailure
+            ? `hdiutil verify failed; captured diagnostics do not establish the failure cause: ${details}`
+            : `hdiutil ${arguments_[0] ?? "operation"} failed: ${details}`, result.cause === undefined ? undefined : { cause: result.cause });
+    }
     return { stdout: result.stdout, exitCode: 0 };
 };
+const describeCommandFailure = (cause, arguments_) => {
+    const fields = {
+        command: "/usr/bin/hdiutil",
+        arguments: [...arguments_],
+    };
+    if (typeof cause === "object" && cause !== null) {
+        for (const key of [
+            "code",
+            "exitCode",
+            "errno",
+            "syscall",
+            "signal",
+            "stdout",
+            "stderr",
+        ]) {
+            const value = Reflect.get(cause, key);
+            if (typeof value === "string" || typeof value === "number")
+                fields[key] = value;
+        }
+        const code = Reflect.get(cause, "code");
+        if (typeof code === "number")
+            fields.exitCode = code;
+    }
+    if (cause instanceof ArtifactReaderFailure)
+        fields.message = cause.message;
+    else if (cause instanceof Error)
+        fields.message = cause.message;
+    return JSON.stringify(fields);
+};
+const processExitCode = (cause) => {
+    if (typeof cause !== "object" || cause === null)
+        return undefined;
+    const exitCode = Reflect.get(cause, "exitCode");
+    if (typeof exitCode === "number")
+        return exitCode;
+    const code = Reflect.get(cause, "code");
+    return typeof code === "number" ? code : undefined;
+};
+const processOutput = (cause, field) => {
+    if (typeof cause !== "object" || cause === null)
+        return "";
+    const value = Reflect.get(cause, field);
+    return typeof value === "string" ? value : "";
+};
+const commandFailureReason = (cause, operation) => {
+    if (typeof cause !== "object" || cause === null)
+        return "unavailable";
+    const code = Reflect.get(cause, "code");
+    const exitCode = Reflect.get(cause, "exitCode");
+    if (typeof code === "number" || typeof exitCode === "number")
+        return operation === "verify" ? verifyFailureReason(cause) : "unavailable";
+    if (code === "ENOENT") {
+        const syscall = Reflect.get(cause, "syscall");
+        return typeof syscall === "string" && syscall.startsWith("spawn")
+            ? "unavailable"
+            : "io";
+    }
+    if (code === "EACCES" ||
+        code === "EPERM" ||
+        code === "EIO" ||
+        code === "ENOTDIR" ||
+        code === "EISDIR" ||
+        code === "ENODEV" ||
+        code === "EROFS" ||
+        code === "EMFILE" ||
+        code === "ENFILE")
+        return "io";
+    return "unavailable";
+};
+const verifyFailureReason = (cause) => {
+    const diagnostic = verifyFailureDiagnostic(processOutput(cause, "stdout"), processOutput(cause, "stderr"));
+    switch (diagnostic) {
+        case "image not recognized":
+            return "format";
+        case "invalid checksum":
+        case "image data corrupted":
+            return "integrity";
+        case "No such file or directory":
+        case "Permission denied":
+        case "Input/output error":
+            return "io";
+        default:
+            return "unavailable";
+    }
+};
+const verifyFailureDiagnostic = (stdout, stderr) => {
+    const prefix = "hdiutil: verify failed - ";
+    return `${stdout}\n${stderr}`
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .find((line) => line.startsWith(prefix))
+        ?.slice(prefix.length);
+};
 const command = (arguments_, effects) => ({
     tool: "/usr/bin/hdiutil",
     arguments: [...arguments_],

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/{application → artifacts/apple}/AppleAssetCatalogAnalysis.js

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import { lstat } from "node:fs/promises";
-import { DirectoryArtifactReader } from "../artifacts/DirectoryArtifactReader.js";
-import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
+import { ArtifactReaderFailure } from "../ArtifactReader.js";
 import { analyzeInterfaceBuilderBundle } from "./InterfaceBuilderAnalysis.js";
-import { appleAssetCatalogInputSchema, parseAppleAssetCatalogRecords, projectAppleAssetCatalogPage, } from "../domain/appleAssetCatalog.js";
-import { execFileOutput } from "../process/ExecFileOutput.js";
+import { appleAssetCatalogInputSchema, parseAppleAssetCatalogRecords, projectAppleAssetCatalogPage, } from "../../domain/apple/appleAssetCatalog.js";
+import { execFileOutput } from "../../process/ExecFileOutput.js";
 const ASSETUTIL = "/usr/bin/assetutil";
 const MAX_CATALOG_BYTES = 64 * 1024 * 1024;
 const MAX_TOTAL_METADATA_BYTES = 64 * 1024 * 1024;

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");