rea-agents 6.3.0 → 6.4.0

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

package/dist/process/OwnedCommand.js

@@ -7,12 +7,14 @@ export class OwnedCommandFailure extends Error {
     snapshot;
     cleanupFailure;
     resources;
-    constructor(reason, message, snapshot = null, cleanupFailure = null, options, resources = []) {
+    cleanupOwner;
+    constructor(reason, message, snapshot = null, cleanupFailure = null, options, resources = [], cleanupOwner) {
         super(message, options);
         this.reason = reason;
         this.snapshot = snapshot;
         this.cleanupFailure = cleanupFailure;
         this.resources = resources;
+        this.cleanupOwner = cleanupOwner;
     }
 }
 /** Execute a single owned process with independent cleanup and bounded diagnostic retention. */
@@ -102,14 +104,13 @@ const collectOwnedCommand = async (spawn, limits, launcher, deadline, callerSign
     }
     const stopped = await supervisor.stop();
     const snapshot = supervisor.snapshot();
-    supervisor.dispose();
     if (stopped.status === "incomplete")
         throw new OwnedCommandFailure(failure?.reason ?? "process", failure?.message ?? "Command cleanup failed.", snapshot, stopped.reason, failure === undefined ? undefined : { cause: failure }, [
             spawn.runId,
             ...(spawn.cwd === undefined ? [] : [spawn.cwd]),
             `pid:${launched.ownership.leaderPid}`,
             `process-group:${launched.ownership.processGroupId}`,
-        ]);
+        ], supervisor);
     if (failure !== undefined)
         throw new OwnedCommandFailure(failure.reason, failure.message, snapshot, failure.cleanupFailure, { cause: failure }, failure.resources);
     if (callerSignal?.aborted)