reverseport 0.0.0-stage → 1.2.0

package/dist/artifacts/ZipArtifactReader.js

@@ -0,0 +1,222 @@
+import { PassThrough } from "node:stream";
+import { once } from "node:events";
+import { Reader, ZipReader } from "@zip.js/zip.js";
+import { ArtifactReaderFailure, copyArtifactEntry, sameArtifactEntry, } from "./ArtifactReader.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { NonRegularFileReadError, RegularFileAdmissionFailure, openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
+const ZIP_UTF8_DECODER = new TextDecoder("utf-8", {
+    fatal: true,
+    ignoreBOM: true,
+});
+class NodeFileReader extends Reader {
+    path;
+    maximumReadBytes;
+    admitted;
+    #handle;
+    #owner;
+    #initPromise;
+    #ownsHandle;
+    constructor(path, maximumReadBytes, admitted) {
+        super(path);
+        this.path = path;
+        this.maximumReadBytes = maximumReadBytes;
+        this.admitted = admitted;
+        this.#ownsHandle = admitted === undefined;
+    }
+    init() {
+        this.#initPromise ??= this.#initialize();
+        return this.#initPromise;
+    }
+    async #initialize() {
+        try {
+            const handle = this.admitted?.handle ??
+                (await openRegularFile(this.path, { symlinks: "reject" }));
+            this.#handle = handle;
+            if (this.#ownsHandle)
+                this.#owner = new OwnedFileHandle(handle);
+        }
+        catch (cause) {
+            if (cause instanceof RegularFileAdmissionFailure) {
+                this.#owner = cause.owner;
+                const primary = cause.cause instanceof NonRegularFileReadError
+                    ? new ArtifactReaderFailure("format", `ZIP source is not a regular file: ${this.path}`, { cause: cause.cause })
+                    : cause.cause;
+                throw ArtifactReaderFailure.withCleanup(primary, ArtifactReaderFailure.cleanupObservation(cause.cleanupCause, this.path));
+            }
+            if (cause instanceof NonRegularFileReadError)
+                throw new ArtifactReaderFailure("format", `ZIP source is not a regular file: ${this.path}`, { cause });
+            throw cause;
+        }
+        const metadata = await this.#handle.stat();
+        if (!metadata.isFile() ||
+            (this.admitted !== undefined &&
+                !sameRegularFileState(this.admitted.initial, metadata)))
+            throw new ArtifactReaderFailure("integrity", `ZIP source identity changed before reading: ${this.path}`);
+        this.size = metadata.size;
+    }
+    async readUint8Array(index, length) {
+        const handle = this.#handle;
+        if (handle === undefined)
+            throw new Error("ZIP reader is not initialized");
+        const readBytes = Math.min(length, this.size - index);
+        if (this.maximumReadBytes !== undefined &&
+            readBytes > this.maximumReadBytes)
+            throw new ArtifactReaderFailure("limit", `ZIP metadata read requires ${readBytes} bytes, exceeding the ${this.maximumReadBytes}-byte read budget`);
+        const bytes = Buffer.alloc(readBytes);
+        const read = await handle.read(bytes, 0, bytes.length, index);
+        return bytes.subarray(0, read.bytesRead);
+    }
+    async closeHandle() {
+        if (!this.#ownsHandle)
+            return;
+        await this.#initPromise?.catch(() => undefined);
+        if (this.#owner === undefined)
+            return;
+        await this.#owner.close();
+        this.#owner = undefined;
+        this.#handle = undefined;
+    }
+}
+/** Lazy Zip64-capable reader with CRC and overlap verification on every read. */
+export class ZipArtifactReader {
+    format;
+    #source;
+    #reader;
+    #entries = new Map();
+    /** Optionally bound each metadata read before allocating its backing buffer. */
+    constructor(path, format, maximumMetadataReadBytes, admitted) {
+        this.format = format;
+        this.#source = new NodeFileReader(path, maximumMetadataReadBytes, admitted);
+        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) {
+        let index = 0;
+        for await (const entry of this.#reader.getEntriesGenerator({
+            decodeText: decodeZipEntryText,
+        })) {
+            abortIfNeeded(signal);
+            // ZIP member identity is its directory occurrence, not its filename.
+            // Logical path uniqueness belongs to the artifact inventory boundary.
+            const metadata = projectZipEntry(entry, index++);
+            const stored = this.#entries.get(metadata.adapterKey);
+            if (stored !== undefined && !sameArtifactEntry(metadata, stored.metadata))
+                throw new ArtifactReaderFailure("integrity", `ZIP member identity changed during enumeration: ${entry.filename}`);
+            if (stored === undefined)
+                this.#entries.set(metadata.adapterKey, {
+                    source: entry,
+                    metadata: copyArtifactEntry(metadata),
+                });
+            yield metadata;
+        }
+    }
+    open(entry, signal) {
+        abortIfNeeded(signal);
+        const stored = this.#entries.get(entry.adapterKey);
+        if (stored === undefined || !sameArtifactEntry(entry, stored.metadata))
+            return Promise.reject(new ArtifactReaderFailure("integrity", "ZIP entry metadata does not match this reader's inventory"));
+        const source = stored.source;
+        if (source.directory || isSymlink(source))
+            return Promise.reject(new ArtifactReaderFailure("format", "ZIP entry is not a regular file"));
+        if (source.encrypted)
+            return Promise.reject(new ArtifactReaderFailure("unavailable", "Encrypted ZIP entry is unsupported"));
+        return Promise.resolve(extractStream(source, signal));
+    }
+    async close() {
+        // best-effort cleanup: zip-reader close must not mask prior extraction state.
+        await this.#reader.close().catch(() => undefined);
+        await this.#source.closeHandle();
+    }
+    provenance() {
+        return [];
+    }
+}
+const projectZipEntry = (entry, index) => {
+    const symlink = isSymlink(entry);
+    return {
+        path: zipEntryPath(entry),
+        kind: entry.directory ? "directory" : symlink ? "symlink" : "file",
+        declaredSize: entry.directory ? null : entry.uncompressedSize,
+        compressedSize: entry.directory ? null : entry.compressedSize,
+        executable: entry.executable,
+        encrypted: entry.encrypted,
+        byteOffset: null,
+        declaredSha256: null,
+        unpacked: false,
+        limitations: symlink ? ["Archive symlink target was not read."] : [],
+        adapterKey: `zip-entry:${index}`,
+    };
+};
+const decodeZipEntryText = (bytes, encoding, type) => {
+    if (type !== "filename" || encoding !== "utf-8")
+        return undefined;
+    return decodeStrictZipUtf8(bytes, "ZIP filename is not valid UTF-8");
+};
+const zipEntryPath = (entry) => {
+    const field = entry.extraFieldUnicodePath;
+    if (field?.valid !== true)
+        return entry.filename;
+    return decodeStrictZipUtf8(field.data.subarray(5), "ZIP Unicode Path extra field is not valid UTF-8");
+};
+const decodeStrictZipUtf8 = (bytes, message) => {
+    try {
+        // Keep the adapter's path semantics aligned with zip.js's default decoder:
+        // a leading U+FEFF is part of a member name, not a transport signature.
+        return ZIP_UTF8_DECODER.decode(bytes);
+    }
+    catch (cause) {
+        throw new ArtifactReaderFailure("format", message, { cause });
+    }
+};
+const extractStream = (entry, signal) => {
+    const output = new PassThrough();
+    const controller = new AbortController();
+    const onAbort = () => {
+        controller.abort(signal?.reason);
+        // AbortSignal listeners dispatch synchronously, so this destroy wins the race
+        // against `getData` rejecting with its own AbortError. That ordering is what
+        // keeps the caller-visible failure typed as `cancelled`.
+        output.destroy(new ArtifactReaderFailure("cancelled", "ZIP operation cancelled"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    // `close` covers both a consumer walking away mid-entry and normal completion
+    // after `end()`; aborting then is harmless because `getData` has already
+    // resolved, and it releases the producer in the abandoned-consumer case.
+    output.once("close", () => {
+        signal?.removeEventListener("abort", onAbort);
+        controller.abort();
+    });
+    const writable = new WritableStream({
+        write: async (chunk) => {
+            abortIfNeeded(signal);
+            if (!output.write(Buffer.from(chunk)))
+                await once(output, "drain", { signal: controller.signal });
+        },
+        close: () => {
+            output.end();
+        },
+        abort: (reason) => {
+            output.destroy(toError(reason));
+        },
+    });
+    void entry
+        .getData(writable, {
+        signal: controller.signal,
+        checkSignature: true,
+        checkOverlappingEntry: true,
+        onprogress: () => abortIfNeeded(signal),
+    })
+        .catch((cause) => output.destroy(toError(cause)));
+    return output;
+};
+const isSymlink = (entry) => entry.unixMode !== undefined && (entry.unixMode & 0o170000) === 0o120000;
+const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "ZIP operation cancelled");
+};
+const toError = (cause) => cause instanceof Error ? cause : new Error("ZIP extraction failed");

package/dist/artifacts/apple/AppleAssetCatalogAnalysis.js

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
+import { ArtifactReaderFailure, sameArtifactSourceIdentity, } from "../ArtifactReader.js";
+import { analyzeInterfaceBuilderBundle } from "./InterfaceBuilderAnalysis.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;
+const RESOURCE_KEY_FIELDS = new Set([
+    "image",
+    "imageName",
+    "image_name",
+    "resourceName",
+    "resource_name",
+    "assetName",
+    "asset_name",
+    "UIImageName",
+    "NSImageName",
+]);
+/** Inspect compiled asset catalog metadata without extracting rendition bytes. */
+export const analyzeAppleAssetCatalogs = async (input) => {
+    if (process.platform !== "darwin" && input.runAssetUtil === undefined)
+        throw new ArtifactReaderFailure("unavailable", "Apple asset catalog inspection requires macOS assetutil");
+    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.path.endsWith("Assets.car"))
+                continue;
+            if (entry.kind !== "file") {
+                uninspected.push(`${entry.path} (${entry.kind})`);
+                continue;
+            }
+            const inspected = await inspectAssetCatalogEntry({
+                reader,
+                entry,
+                runAssetUtil: input.runAssetUtil ??
+                    ((path, signal) => runAssetUtil(path, input.environment, signal)),
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+            totalMetadataBytes += inspected.metadataBytes;
+            if (totalMetadataBytes > MAX_TOTAL_METADATA_BYTES)
+                throw new ArtifactReaderFailure("limit", `Combined asset catalog metadata exceeds ${MAX_TOTAL_METADATA_BYTES} bytes`);
+            catalogs.push(inspected.catalog);
+        }
+    }
+    finally {
+        await reader.close();
+    }
+    // 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,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    const resourceReferences = collectInterfaceBuilderResourceKeys(interfaceBuilder.graph.nodes);
+    const result = projectAppleAssetCatalogPage({
+        targetSha256: input.targetSha256,
+        catalogs,
+        offset: page.offset,
+        limit: page.limit,
+        resourceReferences,
+    });
+    return {
+        ...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
+                ? [
+                    "Interface Builder resource-key joins may be incomplete because the decoded UI graph was truncated.",
+                ]
+                : []),
+        ],
+    };
+};
+const inspectAssetCatalogEntry = async (input) => {
+    const { entry, reader, signal } = input;
+    const sha256 = await digestBounded(reader, entry, signal);
+    const before = await lstat(entry.adapterKey, { bigint: true });
+    if (!before.isFile() ||
+        !sameArtifactSourceIdentity(entry.sourceIdentity, before))
+        throw new ArtifactReaderFailure("integrity", `Asset catalog changed before inspection: ${entry.path}`);
+    const output = await input.runAssetUtil(entry.adapterKey, signal);
+    const after = await lstat(entry.adapterKey, { bigint: true });
+    if (!after.isFile() ||
+        !sameArtifactSourceIdentity(entry.sourceIdentity, after) ||
+        (await digestBounded(reader, entry, signal)) !== sha256)
+        throw new ArtifactReaderFailure("integrity", `Asset catalog changed during inspection: ${entry.path}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(output);
+    }
+    catch (cause) {
+        throw new ArtifactReaderFailure("format", `assetutil returned invalid JSON for ${entry.path}`, { cause });
+    }
+    try {
+        return {
+            catalog: {
+                path: entry.path,
+                sha256,
+                records: parseAppleAssetCatalogRecords(parsed),
+            },
+            metadataBytes: Buffer.byteLength(output, "utf8"),
+        };
+    }
+    catch (cause) {
+        throw new ArtifactReaderFailure("format", `assetutil returned an unsupported record for ${entry.path}`, { cause });
+    }
+};
+/** Return only explicit image or asset fields from decoded resource objects. */
+export const collectInterfaceBuilderResourceKeys = (nodes) => nodes.flatMap((node) => {
+    const source = node.evidence.find((item) => item.artifact_path !== null && item.artifact_sha256 !== null);
+    const sourcePath = source?.artifact_path;
+    const sourceArchiveSha256 = source?.artifact_sha256;
+    if (sourcePath == null || sourceArchiveSha256 == null)
+        return [];
+    return Object.entries(node.attributes).flatMap(([field, value]) => RESOURCE_KEY_FIELDS.has(field) &&
+        typeof value === "string" &&
+        value.length > 0
+        ? [
+            {
+                sourceNodeId: node.id,
+                sourcePath,
+                sourceArchiveSha256,
+                field,
+                key: value,
+            },
+        ]
+        : []);
+});
+const runAssetUtil = async (path, environment, signal) => {
+    try {
+        return (await execFileOutput(ASSETUTIL, ["--info", path], {
+            env: environment,
+            timeout: 60_000,
+            maxBuffer: MAX_CATALOG_BYTES,
+            ...(signal === undefined ? {} : { signal }),
+        })).stdout;
+    }
+    catch (cause) {
+        if (signal?.aborted === true)
+            throw new ArtifactReaderFailure("cancelled", "Asset catalog inspection cancelled");
+        const code = typeof cause === "object" && cause !== null && "code" in cause
+            ? cause.code
+            : undefined;
+        throw new ArtifactReaderFailure(code === "ENOENT"
+            ? "unavailable"
+            : code === "ETIMEDOUT" || code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
+                ? "limit"
+                : "io", `assetutil failed${code === undefined ? "" : ` (${String(code)})`}`, { cause });
+    }
+};
+const digestBounded = async (reader, entry, signal) => {
+    if (entry.declaredSize === null || entry.declaredSize > MAX_CATALOG_BYTES)
+        throw new ArtifactReaderFailure("limit", `Asset catalog exceeds ${MAX_CATALOG_BYTES} bytes: ${entry.path}`);
+    const stream = await reader.open(entry, signal);
+    const hash = createHash("sha256");
+    let length = 0;
+    for await (const chunk of stream) {
+        if (signal?.aborted === true)
+            throw new ArtifactReaderFailure("cancelled", "Asset catalog inspection cancelled");
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        length += bytes.length;
+        if (length > MAX_CATALOG_BYTES)
+            throw new ArtifactReaderFailure("limit", `Asset catalog exceeds byte limit: ${entry.path}`);
+        hash.update(bytes);
+    }
+    return hash.digest("hex");
+};

package/dist/artifacts/apple/DylibResolutionReader.js

@@ -0,0 +1,269 @@
+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 { AnalysisInputError } from "../../domain/analysisErrorCore.js";
+import { resolveTreePath } from "../../domain/apple/dyldPaths.js";
+import { dylibResolutionInputSchema, dylibResolutionResultSchema, traceDylibLoading, } from "../../domain/apple/dylibResolution.js";
+import { projectInputIssues } from "../../domain/inputIssueProjection.js";
+import { ArtifactReaderFailure } from "../ArtifactReader.js";
+import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
+import { hasMachoMagic, readMachoImage } from "./MachoLoadCommandReader.js";
+const OPERATION = "trace_dylib_resolution";
+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 AnalysisInputError(OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, options.parameters));
+    // 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, parsed.data.roots !== undefined);
+        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.
+ * A root the caller selected that fails is an input error on that root; a
+ * root REA derived itself keeps reporting an artifact failure.
+ */
+const requireMachoRoots = async (view, roots, callerSelected) => {
+    const resolved = [];
+    for (const [index, path] of roots.entries()) {
+        const reject = (reason, message) => callerSelected
+            ? new AnalysisInputError(OPERATION, undefined, [
+                { path: ["roots", index], reason: "invalid_value", message },
+            ])
+            : new ArtifactReaderFailure(reason, message);
+        const lookup = await resolveTreePath(view, path);
+        if (lookup.kind === "escapes")
+            throw reject("path", `Root ${path} resolves outside the analyzed root`);
+        if (lookup.kind !== "file")
+            throw reject("path", `Root ${path} is not a regular file in the analyzed root`);
+        if ((await view.image(lookup.path)).status === "not-mach-o")
+            throw reject("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");