rea-agents 6.2.0 → 6.4.0

package/dist/native/NativeMachoInspection.js

@@ -1,3 +1,4 @@
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
 import { inspectMachoSchema, } from "../domain/native/nativeInspection.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
@@ -30,7 +31,11 @@ export const inspectNativeMacho = async (context) => {
     const lipo = captures.find(({ tool }) => tool === "lipo");
     if (lipo === undefined)
         throw new TypeError("Missing lipo capture");
-    const selectedArchitecture = selectArchitecture(context.target, parseLipoArchitectures(lipo.stdout).map(({ name }) => name));
+    const availableArchitectures = parseLipoArchitectures(lipo.stdout).map(({ name }) => name);
+    const selection = selectArchitecture(context.target, availableArchitectures);
+    if (selection.status === "absent")
+        return err(new AnalysisOutputError("inspect_macho", `lipo did not list ${selection.architecture}; refusing to read another slice`));
+    const selectedArchitecture = selection.status === "selected" ? selection.architecture : null;
     for (const [tool, prefix] of REQUIRED_SLICE_COMMANDS) {
         const captured = await context.run(tool, [
             ...prefix,
@@ -67,7 +72,6 @@ export const inspectNativeMacho = async (context) => {
         : normalized;
     return ok({
         result: jsonValueSchema.parse(result),
-        provenance: result.provenance,
         limitations: result.limitations,
         locations: fileOffsetLocations(result, segmentOffset),
     });
@@ -226,19 +230,19 @@ const selectedArchitectureArguments = (tool, architecture) => {
 };
 const selectArchitecture = (target, available) => {
     if (target.kind !== "executable" || target.availableArchitectures.length < 2)
-        return null;
+        return { status: "unfiltered" };
     const normalized = target.architecture === "x86" ? "i386" : target.architecture;
     if (available.includes(normalized))
-        return normalized;
+        return { status: "selected", architecture: normalized };
     // BinaryTarget intentionally normalizes ARM64 CPU subtypes. Recover the
     // concrete arm64e slice name from lipo before invoking slice-aware tools.
     if (normalized === "arm64") {
         const arm64e = available.find((architecture) => architecture === "arm64e");
         if (arm64e !== undefined)
-            return arm64e;
+            return { status: "selected", architecture: arm64e };
         const variant = available.find((architecture) => /^arm64e\.[A-Za-z0-9_]+$/u.test(architecture));
         if (variant !== undefined)
-            return variant;
+            return { status: "selected", architecture: variant };
     }
-    return normalized;
+    return { status: "absent", architecture: normalized };
 };

package/dist/native/NativeUiHelperRuntime.js

@@ -41,6 +41,7 @@ export const createNativeUiHelperRuntime = (environment) => {
         const output = await execFileOutput(executable, [JSON.stringify(parameters)], {
             timeout: 30_000,
             maxBuffer: NATIVE_UI_HELPER_MAX_BUFFER,
+            stopSignal: "SIGTERM",
             env: selectedEnvironment,
             ...(signal === undefined ? {} : { signal }),
         });
@@ -54,8 +55,12 @@ export const createNativeUiHelperRuntime = (environment) => {
     return {
         invoke,
         close: async () => {
-            if (root !== undefined)
+            if (root !== undefined) {
                 await rm(root, { recursive: true, force: true });
+                root = undefined;
+                executable = undefined;
+            }
         },
+        resources: () => (root === undefined ? [] : [root]),
     };
 };

package/dist/native/NativeUiObservation.js

@@ -5,7 +5,7 @@ import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInp
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import {} from "../domain/analysisErrorBase.js";
 import { err, ok } from "../domain/result.js";
-import { createNativeUiHelperRuntime } from "./NativeUiHelperRuntime.js";
+import { createNativeUiHelperRuntime, } from "./NativeUiHelperRuntime.js";
 import { NATIVE_UI_OUTPUT_BUDGET_BYTES, NATIVE_UI_OUTPUT_WEIGHT, } from "./NativeUiOutputBudget.js";
 const helper = fileURLToPath(new URL("../../bridge/native/ReaNativeUI.swift", import.meta.url));
 const responseSchema = z.discriminatedUnion("ok", [
@@ -18,7 +18,7 @@ const responseSchema = z.discriminatedUnion("ok", [
 ]);
 /** Capture a selected existing app window and run explicitly selected scenarios. */
 export const observeNativeUi = async (target, operation, parameters, options) => {
-    const runtime = createNativeUiHelperRuntime(options.environment);
+    const runtime = options.runtime ?? createNativeUiHelperRuntime(options.environment);
     try {
         return await observeWithHelper(target, operation, parameters, {
             ...options,
@@ -26,7 +26,8 @@ export const observeNativeUi = async (target, operation, parameters, options) =>
         });
     }
     finally {
-        await runtime.close();
+        if (options.runtime === undefined)
+            await runtime.close();
     }
 };
 const observeWithHelper = async (target, operation, parameters, options) => {

package/dist/native/pe/PeResourceLayout.js

@@ -0,0 +1,120 @@
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+export const peFailure = (message) => {
+    throw new ArtifactReaderFailure("format", message);
+};
+export const requirePeRange = (bytes, offset, length) => {
+    if (!Number.isSafeInteger(offset) ||
+        !Number.isSafeInteger(length) ||
+        offset < 0 ||
+        length < 0 ||
+        offset > bytes.length - length)
+        peFailure(`PE range ${String(offset)} + ${String(length)} leaves the artifact.`);
+};
+// RVA ownership follows the declared virtual extent. Raw size describes
+// initialized file bytes and can include file-alignment padding; loaders may
+// map page-rounded tails, but those bytes are outside the declared section.
+const virtualExtent = (section) => section.virtualSize === 0 ? section.size : section.virtualSize;
+/** Header admission and unambiguous file-backed RVA mapping, independent of section names. */
+export const readPeResourceLayout = (bytes) => {
+    requirePeRange(bytes, 0, 64);
+    if (bytes.readUInt16LE(0) !== 0x5a4d)
+        peFailure("Expected an MZ PE image.");
+    const pe = bytes.readUInt32LE(60);
+    requirePeRange(bytes, pe, 24);
+    if (bytes.readUInt32LE(pe) !== 0x4550)
+        peFailure("Expected a PE signature.");
+    const sectionCount = bytes.readUInt16LE(pe + 6);
+    const optionalSize = bytes.readUInt16LE(pe + 20);
+    const optional = pe + 24;
+    requirePeRange(bytes, optional, optionalSize);
+    if (optionalSize < 64)
+        peFailure("Truncated PE optional header.");
+    const magic = bytes.readUInt16LE(optional);
+    if (magic !== 0x10b && magic !== 0x20b)
+        peFailure("Unsupported PE optional header magic.");
+    const countAt = magic === 0x10b ? 92 : 108;
+    const directoriesAt = countAt + 4;
+    if (optionalSize < directoriesAt)
+        peFailure("Truncated PE data directory count.");
+    const directoryCount = bytes.readUInt32LE(optional + countAt);
+    if (directoryCount > Math.floor((optionalSize - directoriesAt) / 8))
+        peFailure("PE directory count exceeds its optional header.");
+    const headerSize = bytes.readUInt32LE(optional + 60);
+    const table = optional + optionalSize;
+    requirePeRange(bytes, table, sectionCount * 40);
+    if (headerSize < table + sectionCount * 40 || headerSize > bytes.length)
+        peFailure("Invalid PE SizeOfHeaders.");
+    const sections = [];
+    for (let index = 0; index < sectionCount; index++) {
+        const at = table + index * 40;
+        const section = {
+            rva: bytes.readUInt32LE(at + 12),
+            virtualSize: bytes.readUInt32LE(at + 8),
+            offset: bytes.readUInt32LE(at + 20),
+            size: bytes.readUInt32LE(at + 16),
+        };
+        if (section.rva + virtualExtent(section) > 0x100000000)
+            peFailure("PE section RVA range overflows.");
+        if (section.size > 0) {
+            requirePeRange(bytes, section.offset, section.size);
+            if (section.offset < headerSize)
+                peFailure("PE section raw bytes overlap headers.");
+        }
+        sections.push(section);
+    }
+    const backed = sections
+        .filter(({ size }) => size > 0)
+        .sort((left, right) => left.offset - right.offset);
+    for (let index = 1; index < backed.length; index++) {
+        const previous = backed[index - 1];
+        const current = backed[index];
+        if (previous !== undefined &&
+            current !== undefined &&
+            current.offset < previous.offset + previous.size)
+            peFailure("PE sections have overlapping raw file ranges.");
+    }
+    const map = (rva, size) => {
+        if (rva + size > 0x100000000)
+            peFailure("Resource RVA range overflows.");
+        const candidates = sections.filter((section) => rva >= section.rva && rva - section.rva < virtualExtent(section));
+        if (rva < headerSize) {
+            if (sections.some((section) => section.rva < rva + size &&
+                section.rva + virtualExtent(section) > rva) ||
+                size > headerSize - rva)
+                peFailure("Ambiguous resource header RVA mapping.");
+            requirePeRange(bytes, rva, size);
+            return rva;
+        }
+        if (candidates.length !== 1)
+            peFailure("Resource RVA has missing or overlapping section mappings.");
+        const section = candidates[0];
+        if (section === undefined)
+            return peFailure("Missing resource section.");
+        const within = rva - section.rva;
+        if (size > virtualExtent(section) - within)
+            peFailure("Resource range leaves its section's virtual size.");
+        if (within > section.size || size > section.size - within)
+            peFailure("Resource range is not entirely file-backed in one section.");
+        // A second section starting inside the requested interval is ambiguous too.
+        if (sections.some((other) => other !== section &&
+            other.rva < rva + size &&
+            other.rva + virtualExtent(other) > rva))
+            peFailure("Resource interval intersects overlapping virtual sections.");
+        const offset = section.offset + within;
+        requirePeRange(bytes, offset, size);
+        return offset;
+    };
+    const directoryAt = optional + directoriesAt + 16;
+    const rva = directoryCount > 2 ? bytes.readUInt32LE(directoryAt) : 0;
+    const size = directoryCount > 2 ? bytes.readUInt32LE(directoryAt + 4) : 0;
+    if ((rva === 0) !== (size === 0))
+        peFailure("Inconsistent PE resource directory RVA/size.");
+    return {
+        format: magic === 0x10b ? "pe32" : "pe32-plus",
+        machine: bytes.readUInt16LE(pe + 4),
+        directoryAt,
+        rva,
+        size,
+        map,
+    };
+};

package/dist/native/pe/PeResourceParser.js

@@ -0,0 +1,286 @@
+import { createHash } from "node:crypto";
+import { setImmediate } from "node:timers/promises";
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { jsonParts } from "../../domain/jsonSerialization.js";
+import { peFailure, readPeResourceLayout, requirePeRange, } from "./PeResourceLayout.js";
+const METADATA_BYTES = 8 * 1024 * 1024;
+const limit = (message) => {
+    throw new ArtifactReaderFailure("limit", message);
+};
+/** Count bytes through the canonical bounded JSON writer. */
+const jsonBytes = (value, maximum) => {
+    let size = 0;
+    for (const part of jsonParts(value)) {
+        size += Buffer.byteLength(part, "utf8");
+        if (size > maximum)
+            return size;
+    }
+    return size;
+};
+const identityKey = (id) => id.kind === "id" ? `id:${String(id.id)}` : `name:${id.utf16le_hex}`;
+/** Decode the conventional type/name/language tree; never infer payload meaning or runtime loading. */
+export const parsePeResources = async (bytes, artifact, input, signal) => {
+    signal?.throwIfAborted();
+    const layout = readPeResourceLayout(bytes);
+    const directories = [];
+    const resources = [];
+    const occupied = [];
+    const names = new Map();
+    let examined = 0;
+    let metadataBytes = 0;
+    const ensureCapacity = (projectedBytes) => {
+        if (metadataBytes + projectedBytes > METADATA_BYTES)
+            limit("PE resource metadata exceeds the 8 MiB complete-result allocation budget.");
+    };
+    const accountBytes = (projectedBytes) => {
+        ensureCapacity(projectedBytes);
+        metadataBytes += projectedBytes;
+    };
+    const account = (value) => {
+        // Rows are retained in arrays; reserve a separator along with each row.
+        accountBytes(jsonBytes(value, METADATA_BYTES - metadataBytes - 1) + 1);
+    };
+    const reserveDecodedName = (utf16Units) => {
+        // A JSON string can need six ASCII bytes per UTF-16 code unit (for example,
+        // a control character encoded as `\\u0000`). The original spelling and
+        // its hex form are both retained in the result.
+        const projectedBytes = 10 * utf16Units + 256;
+        ensureCapacity(projectedBytes);
+    };
+    const root = layout.size === 0 ? 0 : layout.map(layout.rva, layout.size);
+    const relative = (at, length) => {
+        if (at > layout.size - length || at < 0)
+            peFailure("Resource directory offset leaves the declared resource interval.");
+        requirePeRange(bytes, root + at, length);
+        return root + at;
+    };
+    const recordRange = (offset, size, kind) => {
+        const range = { offset, bytes: size };
+        if (size > 0)
+            occupied.push({ ...range, kind });
+        return range;
+    };
+    const readIdentity = (encoded) => {
+        if ((encoded & 0x80000000) === 0)
+            return { kind: "id", id: encoded };
+        const at = encoded & 0x7fffffff;
+        const previous = names.get(at);
+        if (previous !== undefined)
+            return previous;
+        if (at % 2 !== 0)
+            peFailure("Unaligned PE resource name.");
+        const start = relative(at, 2);
+        const utf16Units = bytes.readUInt16LE(start);
+        reserveDecodedName(utf16Units);
+        const length = utf16Units * 2;
+        relative(at, 2 + length);
+        const raw = bytes.subarray(start + 2, start + 2 + length);
+        const value = {
+            kind: "name",
+            name: raw.toString("utf16le"),
+            utf16le_hex: raw.toString("hex"),
+            location: recordRange(start, 2 + length, "name"),
+        };
+        names.set(at, value);
+        return value;
+    };
+    const visit = async (at, path, entryLocations, ancestors) => {
+        if (ancestors.has(at))
+            peFailure("Cyclic PE resource directory.");
+        if (at % 4 !== 0)
+            peFailure("Unaligned PE resource directory.");
+        const header = relative(at, 16);
+        const named = bytes.readUInt16LE(header + 12);
+        const ids = bytes.readUInt16LE(header + 14);
+        const count = named + ids;
+        if (count > input.max_entries - examined)
+            limit("PE resource directory entry budget exceeded; no partial inventory was returned.");
+        examined += count;
+        relative(at, 16 + 8 * count);
+        const directory = {
+            location: recordRange(header, 16 + 8 * count, "directory"),
+            characteristics: bytes.readUInt32LE(header),
+            timestamp: bytes.readUInt32LE(header + 4),
+            major_version: bytes.readUInt16LE(header + 8),
+            minor_version: bytes.readUInt16LE(header + 10),
+            named_entries: named,
+            id_entries: ids,
+        };
+        account(directory);
+        directories.push(directory);
+        const keys = new Set();
+        const nested = new Set([...ancestors, at]);
+        for (let index = 0; index < count; index++) {
+            if (index % 128 === 0) {
+                await setImmediate();
+                signal?.throwIfAborted();
+            }
+            const entry = header + 16 + index * 8;
+            const encoded = bytes.readUInt32LE(entry);
+            if (((encoded & 0x80000000) !== 0) !== index < named)
+                peFailure("Resource name/ID entry counts disagree with encoded identities.");
+            const identity = readIdentity(encoded);
+            const key = identityKey(identity);
+            if (keys.has(key))
+                peFailure("Duplicate identity within a resource directory.");
+            keys.add(key);
+            const next = [...path, identity];
+            const locations = [...entryLocations, { offset: entry, bytes: 8 }];
+            const target = bytes.readUInt32LE(entry + 4);
+            const offset = target & 0x7fffffff;
+            if ((target & 0x80000000) !== 0) {
+                if (next.length >= 3)
+                    peFailure("Unsupported resource tree deeper than type/name/language.");
+                await visit(offset, next, locations, nested);
+            }
+            else {
+                if (next.length !== 3)
+                    peFailure("Unsupported resource leaf outside the type/name/language profile.");
+                const data = relative(offset, 16);
+                if (offset % 4 !== 0)
+                    peFailure("Unaligned resource data entry.");
+                const rva = bytes.readUInt32LE(data);
+                const size = bytes.readUInt32LE(data + 4);
+                const payloadOffset = layout.map(rva, size);
+                const [type, name, language] = next;
+                if (type === undefined || name === undefined || language === undefined)
+                    return peFailure("Incomplete resource identity.");
+                const resource = {
+                    index: resources.length,
+                    type,
+                    name,
+                    language,
+                    entry_locations: locations,
+                    data_entry_location: recordRange(data, 16, "data-entry"),
+                    code_page: bytes.readUInt32LE(data + 8),
+                    reserved: bytes.readUInt32LE(data + 12),
+                    payload: {
+                        rva,
+                        location: recordRange(payloadOffset, size, "payload"),
+                        sha256: "0".repeat(64),
+                    },
+                };
+                account(resource);
+                resources.push(resource);
+            }
+        }
+    };
+    if (layout.size > 0)
+        await visit(0, [], [], new Set());
+    rejectOverlappingRanges(occupied);
+    const hashes = new Map();
+    for (const resource of resources) {
+        const range = resource.payload.location;
+        const key = `${String(range.offset)}:${String(range.bytes)}`;
+        let digest = hashes.get(key);
+        if (digest === undefined) {
+            const hash = createHash("sha256");
+            for (let offset = 0; offset < range.bytes; offset += 1048576) {
+                await setImmediate();
+                signal?.throwIfAborted();
+                hash.update(bytes.subarray(range.offset + offset, range.offset + Math.min(range.bytes, offset + 1048576)));
+            }
+            digest = hash.digest("hex");
+            hashes.set(key, digest);
+        }
+        resource.payload.sha256 = digest;
+    }
+    const iconGroups = readIconGroups(bytes, resources, account, ensureCapacity);
+    const report = {
+        artifact,
+        format: layout.format,
+        machine: layout.machine,
+        directory: layout.size === 0
+            ? null
+            : {
+                rva: layout.rva,
+                location: { offset: root, bytes: layout.size },
+                data_directory_location: { offset: layout.directoryAt, bytes: 8 },
+            },
+        directories,
+        resources,
+        icon_groups: iconGroups,
+        coverage: {
+            status: "complete",
+            examined_entries: examined,
+            resources: resources.length,
+        },
+        limitations: [
+            "Static PE32/PE32+ type/name/language resource inventory; payloads other than RT_GROUP_ICON remain opaque.",
+            "Icon candidates are resource-table relationships. Language fallback, image decoding and actual shell/window loading are not observed.",
+            "Exact shared byte ranges are retained; non-identical overlapping resource structures or payloads are rejected.",
+        ],
+    };
+    signal?.throwIfAborted();
+    if (jsonBytes(report, METADATA_BYTES) > METADATA_BYTES)
+        limit("PE resource result exceeds the 8 MiB allocation budget.");
+    return report;
+};
+const rejectOverlappingRanges = (ranges) => {
+    ranges.sort((left, right) => left.offset - right.offset || right.bytes - left.bytes);
+    let previous;
+    for (const current of ranges) {
+        if (previous !== undefined &&
+            current.offset < previous.offset + previous.bytes &&
+            (current.offset !== previous.offset ||
+                current.bytes !== previous.bytes ||
+                current.kind !== previous.kind))
+            peFailure("Non-identical resource byte ranges overlap.");
+        previous = current;
+    }
+};
+const readIconGroups = (bytes, resources, account, ensureCapacity) => {
+    const imagesById = new Map();
+    for (const resource of resources) {
+        if (resource.type.kind !== "id" ||
+            resource.type.id !== 3 ||
+            resource.name.kind !== "id")
+            continue;
+        const candidates = imagesById.get(resource.name.id) ?? [];
+        candidates.push(resource);
+        imagesById.set(resource.name.id, candidates);
+    }
+    return resources
+        .filter((resource) => resource.type.kind === "id" && resource.type.id === 14)
+        .map((group) => {
+        const { offset, bytes: size } = group.payload.location;
+        if (size < 6 ||
+            bytes.readUInt16LE(offset) !== 0 ||
+            bytes.readUInt16LE(offset + 2) !== 1)
+            peFailure("Malformed RT_GROUP_ICON header.");
+        const count = bytes.readUInt16LE(offset + 4);
+        if (size !== 6 + count * 14)
+            peFailure("RT_GROUP_ICON length does not match its image count.");
+        const images = [];
+        for (let index = 0; index < count; index++) {
+            const at = offset + 6 + index * 14;
+            const id = bytes.readUInt16LE(at + 12);
+            const candidates = imagesById.get(id) ?? [];
+            const exact = candidates.find((resource) => identityKey(resource.language) === identityKey(group.language));
+            // Indices are uint32 values and each needs at most ten decimal digits
+            // plus a comma. Check the expanded candidate list before allocating it.
+            ensureCapacity(302 + candidates.length * 11);
+            const declaredBytes = bytes.readUInt32LE(at + 8);
+            const image = {
+                location: { offset: at, bytes: 14 },
+                width: bytes[at] ?? 0,
+                height: bytes[at + 1] ?? 0,
+                color_count: bytes[at + 2] ?? 0,
+                reserved: bytes[at + 3] ?? 0,
+                planes: bytes.readUInt16LE(at + 4),
+                bit_count: bytes.readUInt16LE(at + 6),
+                declared_bytes: declaredBytes,
+                resource_id: id,
+                candidate_resource_indices: candidates.map(({ index }) => index),
+                same_language_resource_index: exact?.index ?? null,
+                size_matches: exact === undefined
+                    ? null
+                    : exact.payload.location.bytes === declaredBytes,
+            };
+            account(image);
+            images.push(image);
+        }
+        account({ resource_index: group.index, images: [] });
+        return { resource_index: group.index, images };
+    });
+};

package/dist/native/pe/PeResourcesProvider.js

@@ -0,0 +1,63 @@
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisInputError, AnalysisResourceConstraintError, } from "../../domain/analysisErrorCore.js";
+import { err, ok } from "../../domain/result.js";
+import { PE_RESOURCES_PROVIDER } from "../../application/InvestigationProviders.js";
+import { parsePeResources } from "./PeResourceParser.js";
+/** Portable parser over one bounded, identity-checked regular file. */
+export class PeResourcesProvider {
+    identity = PE_RESOURCES_PROVIDER;
+    async inspect(input, options) {
+        try {
+            const snapshot = await readStableArtifact(input.path, input.max_file_bytes, options?.signal);
+            return ok(await parsePeResources(snapshot.bytes, {
+                path: input.path,
+                sha256: snapshot.sha256,
+                bytes: snapshot.bytes.length,
+            }, input, options?.signal));
+        }
+        catch (cause) {
+            return err(peResourcesFailure(cause, input, options?.signal));
+        }
+    }
+}
+const peResourcesFailure = (cause, input, signal) => {
+    const operation = "inspect_pe_resources";
+    if (signal?.aborted)
+        return new AnalysisCancelledError(operation, { cause });
+    if (cause instanceof ArtifactReaderFailure) {
+        if (cause.reason === "limit")
+            return new AnalysisResourceConstraintError(operation, "memory", cause.message, {
+                max_file_bytes: input.max_file_bytes,
+                max_entries: input.max_entries,
+            }, { cause });
+        if (cause.reason === "integrity")
+            return new AnalysisArtifactChangedError(operation, input.path, cause.message, { cause });
+        if (cause.reason === "path" || cause.reason === "format")
+            return new AnalysisInputError(operation, { cause }, [
+                {
+                    path: ["path"],
+                    reason: "invalid_format",
+                    message: cause.message,
+                },
+            ]);
+        if (cause.reason === "cancelled")
+            return new AnalysisCancelledError(operation, { cause });
+    }
+    if (cause instanceof Error && "code" in cause) {
+        if (cause.code === "EACCES" || cause.code === "EPERM")
+            return new AnalysisAccessDeniedError(operation, input.path, cause.code, {
+                cause,
+            });
+        if (cause.code === "ENOENT" || cause.code === "ENOTDIR")
+            return new AnalysisInputError(operation, { cause }, [
+                {
+                    path: ["path"],
+                    reason: "invalid_value",
+                    message: `Selected PE image could not be read (${cause.code}): ${input.path}.`,
+                },
+            ]);
+    }
+    return new ArtifactOperationError(operation, cause instanceof ArtifactReaderFailure ? cause.reason : "io", undefined, cause instanceof Error ? cause.message : "PE artifact inspection failed.", { cause });
+};

package/dist/process/BoundedFileBytes.js

@@ -1,17 +1,40 @@
-/** Read through EOF, returning undefined on overflow; consume at most maxBytes + 1 bytes without closing the handle. */
-export const readBoundedFileBytes = async (handle, maxBytes) => {
+/** Read through EOF, returning undefined on overflow; leave the handle open. */
+export const readBoundedFileBytes = async (handle, maxBytes, signal, expectedSize) => {
     if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
         throw new RangeError("File byte limit must be a nonnegative safe integer");
-    const chunks = [];
-    const buffer = Buffer.allocUnsafe(Math.min(64 * 1_024, maxBytes + 1));
+    if (expectedSize !== undefined &&
+        (!Number.isSafeInteger(expectedSize) ||
+            expectedSize < 0 ||
+            expectedSize > maxBytes))
+        throw new RangeError("Expected file size must fit the byte limit");
+    if (expectedSize === undefined) {
+        const chunks = [];
+        const buffer = Buffer.allocUnsafe(Math.min(64 * 1_024, maxBytes + 1));
+        let total = 0;
+        for (;;) {
+            signal?.throwIfAborted();
+            const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, maxBytes - total + 1), null);
+            if (bytesRead === 0)
+                return Buffer.concat(chunks, total);
+            total += bytesRead;
+            if (total > maxBytes)
+                return undefined;
+            chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+        }
+    }
+    const buffer = Buffer.allocUnsafe(expectedSize);
+    if (expectedSize === 0)
+        return buffer;
     let total = 0;
     for (;;) {
-        const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, maxBytes - total + 1), null);
+        signal?.throwIfAborted();
+        const { bytesRead } = await handle.read(buffer, total, expectedSize - total, null);
         if (bytesRead === 0)
-            return Buffer.concat(chunks, total);
+            return buffer.subarray(0, total);
         total += bytesRead;
         if (total > maxBytes)
             return undefined;
-        chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+        if (total === expectedSize)
+            return buffer;
     }
 };

package/dist/process/DarwinProcessRunTokenReader.js

@@ -223,12 +223,17 @@ export const createDarwinProcessRunTokenReader = (options = {}) => {
             }
         }
     };
-    const read = async (processes) => {
+    const read = async (processes, signal) => {
+        signal?.throwIfAborted();
         if (processes.length === 0)
             return new Map();
-        const binary = await compile();
+        const binary = await compile(signal);
         const pids = processes.map(({ pid }) => String(pid));
-        const { stdout } = await execFileOutput(binary, pids, { timeout: 15_000 });
+        const { stdout } = await execFileOutput(binary, pids, {
+            timeout: 15_000,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        signal?.throwIfAborted();
         const decoded = safeParseJson(stdout);
         if (!decoded.ok)
             throw new Error(`macOS process token helper returned invalid JSON: ${decoded.error}`, { cause: decoded.cause });