rea-agents 4.0.1 → 5.0.0

package/dist/artifacts/AsarArtifactReader.js

@@ -1,9 +1,12 @@
-import { sep } from "node:path";
+import { constants, createReadStream } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
 import { Readable } from "node:stream";
-import { extractFile, listPackage, statFile, uncache } from "@electron/asar";
+import { getRawHeader, listPackage, statFile, uncache } from "@electron/asar";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+import { closeAsarHandle, readValidatedAsarEntry } from "./AsarEntryStream.js";
 /**
- * Official Electron ASAR adapter. Individual files remain caller-bounded.
+ * Official Electron ASAR adapter with range-streamed member reads.
  *
  * An entry marked `unpacked` is metadata, not an integrity exemption: Electron
  * stores its bytes beside the archive in `<archive>.unpacked`, and callers must
@@ -11,16 +14,28 @@ import { ArtifactReaderFailure, } from "./ArtifactReader.js";
  */
 export class AsarArtifactReader {
     path;
+    openUnpackedFile;
     format = "asar";
-    constructor(path) {
+    #archiveSize;
+    #headerSize;
+    #entries = new Map();
+    constructor(path, openUnpackedFile = open) {
         this.path = path;
+        this.openUnpackedFile = openUnpackedFile;
     }
     async *entries(signal) {
         let paths;
         try {
             // ASAR caches headers by path even after the archive has been replaced.
+            this.#resetArchiveState();
+            this.#entries.clear();
             uncache(this.path);
             paths = listPackage(this.path, { isPack: false }).sort((left, right) => left.localeCompare(right, "en"));
+            this.#headerSize = getRawHeader(this.path).headerSize;
+            const archiveMetadata = await lstat(this.path);
+            if (!archiveMetadata.isFile() || archiveMetadata.isSymbolicLink())
+                throw new ArtifactReaderFailure("format", "ASAR container is not a regular file");
+            this.#archiveSize = archiveMetadata.size;
         }
         catch (cause) {
             throw asarFailure(this.path, "inventory", cause);
@@ -49,7 +64,7 @@ export class AsarArtifactReader {
                 : "link" in metadata
                     ? "symlink"
                     : "file";
-            yield {
+            const entry = {
                 path,
                 kind,
                 declaredSize: "size" in metadata ? metadata.size : null,
@@ -65,39 +80,187 @@ export class AsarArtifactReader {
                 unpacked: "unpacked" in metadata && metadata.unpacked === true,
                 limitations: kind === "symlink"
                     ? ["ASAR symlink target was not followed or disclosed."]
-                    : [
-                        "Official ASAR extraction buffers each individually bounded file.",
-                    ],
+                    : [],
                 adapterKey: providerPath,
             };
+            if (kind === "file" && isAsarFileMetadata(metadata))
+                this.#entries.set(providerPath, {
+                    metadata,
+                    entry: copyArtifactEntry(entry),
+                });
+            yield entry;
         }
     }
-    open(entry, signal) {
+    async open(entry, signal) {
         abortIfNeeded(signal);
-        if (entry.kind !== "file")
-            return Promise.reject(new ArtifactReaderFailure("format", "ASAR entry is not a regular file"));
+        const state = this.#entries.get(entry.adapterKey);
+        if (state === undefined && entry.kind !== "file")
+            throw new ArtifactReaderFailure("format", "ASAR entry is not a regular file");
+        if (state === undefined)
+            throw new ArtifactReaderFailure("integrity", `ASAR entry was not produced by this reader: ${entry.path}`);
+        if (!sameArtifactEntry(entry, state.entry))
+            throw new ArtifactReaderFailure("integrity", `ASAR entry metadata changed since inventory: ${state.entry.path}`);
+        const { metadata } = state;
+        const producedEntry = state.entry;
+        if (producedEntry.unpacked) {
+            const handle = await this.#openUnpackedEntry(producedEntry);
+            try {
+                const observed = await handle.stat();
+                abortIfNeeded(signal);
+                if (!observed.isFile())
+                    throw new ArtifactReaderFailure("path", `ASAR unpacked entry is not a regular file: ${producedEntry.path}`);
+            }
+            catch (cause) {
+                await handle.close().catch(() => undefined);
+                throw asarFailure(this.path, `read ${producedEntry.path}`, cause);
+            }
+            const source = handle.createReadStream({
+                start: 0,
+                autoClose: true,
+            });
+            return readValidatedAsarEntry(source, undefined, producedEntry.path, this.path, signal);
+        }
+        const archiveSize = this.#archiveSize;
+        const headerSize = this.#headerSize;
+        const offset = metadata.offset === undefined
+            ? undefined
+            : parseArchiveOffset(metadata.offset);
+        const start = offset === undefined || headerSize === undefined
+            ? undefined
+            : 8 + headerSize + offset;
+        if (archiveSize === undefined ||
+            start === undefined ||
+            !Number.isSafeInteger(start) ||
+            metadata.size < 0 ||
+            !Number.isSafeInteger(metadata.size) ||
+            start > archiveSize ||
+            metadata.size > archiveSize - start)
+            throw new ArtifactReaderFailure("format", `ASAR entry range is outside its container: ${producedEntry.path}`);
+        let handle;
         try {
-            return Promise.resolve(Readable.from(extractFile(this.path, entry.adapterKey, false)));
+            const openedHandle = await open(this.path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            handle = openedHandle;
+            const observed = await openedHandle.stat();
+            abortIfNeeded(signal);
+            if (!observed.isFile() || observed.size !== archiveSize)
+                throw new ArtifactReaderFailure("integrity", `ASAR container changed before read: ${producedEntry.path}`);
+            if (metadata.size === 0) {
+                await closeAsarHandle(() => openedHandle.close(), signal);
+                handle = undefined;
+                return Readable.from([]);
+            }
+            const source = openedHandle.createReadStream({
+                start,
+                end: start + metadata.size - 1,
+                autoClose: true,
+            });
+            return readValidatedAsarEntry(source, metadata.size, producedEntry.path, this.path, signal);
         }
         catch (cause) {
-            if (entry.unpacked && isMissingFile(cause))
-                return Promise.reject(new ArtifactReaderFailure("unavailable", `ASAR unpacked entry bytes are unavailable: ${entry.path}`, { cause }, {
-                    logicalPath: entry.path,
-                    declaredSha256: entry.declaredSha256,
-                    calculatedSha256: null,
-                    unpacked: true,
-                }));
-            return Promise.reject(asarFailure(this.path, `read ${entry.path}`, cause));
+            await handle?.close().catch(() => undefined);
+            throw asarFailure(this.path, `read ${producedEntry.path}`, cause);
         }
     }
+    /** Open raw container bytes to verify the inventory identity before analysis. */
+    openContainer(signal) {
+        abortIfNeeded(signal);
+        return createReadStream(this.path, signal === undefined ? {} : { signal });
+    }
     close() {
         uncache(this.path);
+        this.#resetArchiveState();
+        this.#entries.clear();
         return Promise.resolve();
     }
     provenance() {
         return [];
     }
+    async #openUnpackedEntry(entry) {
+        const unpackedRoot = `${this.path}.unpacked`;
+        try {
+            const rootMetadata = await lstat(unpackedRoot);
+            if (!rootMetadata.isDirectory() || rootMetadata.isSymbolicLink())
+                throw new ArtifactReaderFailure("path", "ASAR unpacked companion is not a regular directory");
+            const canonicalRoot = await realpath(unpackedRoot);
+            const candidate = join(unpackedRoot, entry.adapterKey);
+            const canonical = await realpath(candidate);
+            const relativePath = relative(canonicalRoot, canonical);
+            if (relativePath === ".." ||
+                relativePath.startsWith(`..${sep}`) ||
+                isAbsolute(relativePath))
+                throw new ArtifactReaderFailure("path", `ASAR unpacked entry escaped its companion directory: ${entry.path}`);
+            const pathMetadata = await lstat(candidate);
+            if (!pathMetadata.isFile() || pathMetadata.isSymbolicLink())
+                throw new ArtifactReaderFailure("path", `ASAR unpacked entry is not a regular file: ${entry.path}`);
+            const handle = await this.openUnpackedFile(canonical, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const openedMetadata = await handle
+                .stat()
+                .catch(async (cause) => {
+                await handle.close().catch(() => undefined);
+                throw cause;
+            });
+            if (!openedMetadata.isFile() ||
+                openedMetadata.dev !== pathMetadata.dev ||
+                openedMetadata.ino !== pathMetadata.ino) {
+                await handle.close();
+                throw new ArtifactReaderFailure("integrity", `ASAR unpacked entry changed before read: ${entry.path}`, {}, {
+                    logicalPath: entry.path,
+                    declaredSha256: entry.declaredSha256,
+                    calculatedSha256: null,
+                    unpacked: true,
+                });
+            }
+            return handle;
+        }
+        catch (cause) {
+            if (cause instanceof ArtifactReaderFailure)
+                throw cause;
+            if (entry.unpacked && isMissingFile(cause))
+                throw new ArtifactReaderFailure("unavailable", `ASAR unpacked entry bytes are unavailable: ${entry.path}`, { cause }, {
+                    logicalPath: entry.path,
+                    declaredSha256: entry.declaredSha256,
+                    calculatedSha256: null,
+                    unpacked: true,
+                });
+            throw asarFailure(this.path, `read ${entry.path}`, cause);
+        }
+    }
+    #resetArchiveState() {
+        this.#archiveSize = undefined;
+        this.#headerSize = undefined;
+    }
 }
+const copyArtifactEntry = (entry) => ({
+    ...entry,
+    limitations: [...entry.limitations],
+    ...(entry.sourceIdentity === undefined
+        ? {}
+        : { sourceIdentity: { ...entry.sourceIdentity } }),
+});
+const sameArtifactEntry = (entry, produced) => entry.path === produced.path &&
+    entry.kind === produced.kind &&
+    entry.declaredSize === produced.declaredSize &&
+    entry.compressedSize === produced.compressedSize &&
+    entry.executable === produced.executable &&
+    entry.encrypted === produced.encrypted &&
+    entry.byteOffset === produced.byteOffset &&
+    entry.declaredSha256 === produced.declaredSha256 &&
+    entry.unpacked === produced.unpacked &&
+    entry.adapterKey === produced.adapterKey &&
+    entry.limitations.length === produced.limitations.length &&
+    entry.limitations.every((limitation, index) => limitation === produced.limitations[index]) &&
+    entry.sourceIdentity?.device === produced.sourceIdentity?.device &&
+    entry.sourceIdentity?.inode === produced.sourceIdentity?.inode;
+const isAsarFileMetadata = (metadata) => "size" in metadata &&
+    typeof metadata.size === "number" &&
+    !("files" in metadata) &&
+    !("link" in metadata);
+const parseArchiveOffset = (value) => {
+    if (!/^(?:0|[1-9][0-9]*)$/u.test(value))
+        return undefined;
+    const offset = Number(value);
+    return Number.isSafeInteger(offset) ? offset : undefined;
+};
 const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
         throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
@@ -106,9 +269,18 @@ const toArtifactPath = (listed) => {
     const portable = sep === "\\" ? listed.replaceAll("\\", "/") : listed;
     return portable.replace(/^\/+|\/+$/gu, "");
 };
-const asarFailure = (path, operation, cause) => cause instanceof ArtifactReaderFailure
-    ? cause
-    : new ArtifactReaderFailure("format", `Malformed or unreadable ASAR during ${operation}: ${path}`, { cause });
+const asarFailure = (path, operation, cause) => {
+    if (cause instanceof ArtifactReaderFailure)
+        return cause;
+    if (isFilesystemFailure(cause))
+        return new ArtifactReaderFailure("io", `Could not ${operation} ASAR at ${path}: ${cause.message}`, { cause });
+    return new ArtifactReaderFailure("format", `Malformed ASAR during ${operation}: ${path}`, { cause });
+};
+const isFilesystemFailure = (cause) => cause instanceof Error &&
+    "errno" in cause &&
+    typeof cause.errno === "number" &&
+    "syscall" in cause &&
+    typeof cause.syscall === "string";
 const isMissingFile = (cause) => typeof cause === "object" &&
     cause !== null &&
     "code" in cause &&

package/dist/artifacts/AsarEntryStream.js

@@ -0,0 +1,76 @@
+import { Readable } from "node:stream";
+import { ArtifactReaderFailure } from "./ArtifactReader.js";
+/** Close an ASAR file handle before honoring cancellation of an empty member. */
+export const closeAsarHandle = async (close, signal) => {
+    await close();
+    abortIfNeeded(signal);
+};
+/** Validate and contextualize bytes read from one ASAR member source. */
+export const readValidatedAsarEntry = (source, expectedBytes, entryPath, archivePath, signal) => {
+    const output = Readable.from((async function* () {
+        let observedBytes = 0;
+        const iterator = source[Symbol.asyncIterator]();
+        try {
+            while (true) {
+                abortIfNeeded(signal);
+                const next = await iterator.next();
+                if (next.done)
+                    break;
+                const chunk = next.value;
+                if (!Buffer.isBuffer(chunk) && !(chunk instanceof Uint8Array))
+                    throw new ArtifactReaderFailure("format", `ASAR entry did not return bytes: ${entryPath}`);
+                observedBytes += Buffer.isBuffer(chunk)
+                    ? chunk.length
+                    : chunk.byteLength;
+                if (expectedBytes !== undefined && observedBytes > expectedBytes)
+                    throw new ArtifactReaderFailure("integrity", `ASAR entry exceeded its declared size: ${entryPath}`);
+                yield chunk;
+            }
+            if (expectedBytes !== undefined && observedBytes !== expectedBytes)
+                throw new ArtifactReaderFailure("integrity", `ASAR entry size disagrees with its header: ${entryPath}`);
+        }
+        catch (cause) {
+            throw asarFailure(archivePath, `read ${entryPath}`, cause);
+        }
+        finally {
+            try {
+                await iterator.return?.();
+            }
+            catch {
+                // Preserve the read failure; source destruction below owns cleanup.
+            }
+            if (!source.destroyed)
+                source.destroy();
+        }
+    })());
+    const closeSource = () => {
+        signal?.removeEventListener("abort", onAbort);
+        if (!source.destroyed)
+            source.destroy();
+    };
+    const onAbort = () => {
+        closeSource();
+        output.destroy(new ArtifactReaderFailure("cancelled", "ASAR operation cancelled"));
+    };
+    output.once("close", closeSource);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted === true)
+        onAbort();
+    return output;
+};
+const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
+};
+const asarFailure = (path, operation, cause) => {
+    if (cause instanceof ArtifactReaderFailure)
+        return cause;
+    if (isFilesystemFailure(cause))
+        return new ArtifactReaderFailure("io", `Could not ${operation} ASAR at ${path}: ${cause.message}`, { cause });
+    return new ArtifactReaderFailure("format", `Malformed ASAR during ${operation}: ${path}`, { cause });
+};
+const isFilesystemFailure = (cause) => cause instanceof Error &&
+    "errno" in cause &&
+    typeof cause.errno === "number" &&
+    "syscall" in cause &&
+    typeof cause.syscall === "string";

package/dist/artifacts/DirectoryArtifactReader.js

@@ -6,34 +6,46 @@ import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 export class DirectoryArtifactReader {
     format = "directory";
     #rootPromise;
+    #rootPath;
     constructor(root) {
+        this.#rootPath = root;
         this.#rootPromise = realpath(root);
     }
     async *entries(signal) {
-        const root = await this.#rootPromise;
+        const root = await this.#rootPromise.catch((cause) => {
+            throw directoryIoFailure("resolve artifact root", this.#rootPath, cause);
+        });
         const pending = [root];
         while (pending.length > 0) {
             abortIfNeeded(signal);
             const directory = pending.pop();
             if (directory === undefined)
                 break;
-            await assertContainedDirectory(root, directory);
+            await withDirectoryIoContext("inspect directory", directory, () => assertContainedDirectory(root, directory));
             const children = [];
-            const handle = await opendir(directory);
+            const handle = await opendir(directory).catch((cause) => {
+                throw directoryIoFailure("open directory", directory, cause);
+            });
             try {
                 for await (const child of handle)
                     children.push(child.name);
             }
+            catch (cause) {
+                throw directoryIoFailure("read directory", directory, cause);
+            }
             finally {
+                // best-effort cleanup: directory-handle close must not mask traversal.
                 await handle.close().catch(() => undefined);
             }
-            await assertContainedDirectory(root, directory);
+            await withDirectoryIoContext("inspect directory", directory, () => assertContainedDirectory(root, directory));
             children.sort((left, right) => left.localeCompare(right, "en"));
             const directories = [];
             for (const name of children) {
                 abortIfNeeded(signal);
                 const absolute = join(directory, name);
-                const metadata = await lstat(absolute);
+                const metadata = await lstat(absolute).catch((cause) => {
+                    throw directoryIoFailure("inspect entry", absolute, cause);
+                });
                 const path = relative(root, absolute).split(sep).join("/");
                 const kind = metadata.isSymbolicLink()
                     ? "symlink"
@@ -73,9 +85,13 @@ export class DirectoryArtifactReader {
         abortIfNeeded(signal);
         if (entry.kind !== "file")
             throw new ArtifactReaderFailure("format", "Only regular files can be opened");
-        const handle = await open(entry.adapterKey, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const handle = await open(entry.adapterKey, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch((cause) => {
+            throw directoryIoFailure("open entry", entry.adapterKey, cause);
+        });
         try {
-            const observed = await handle.stat();
+            const observed = await handle.stat().catch((cause) => {
+                throw directoryIoFailure("inspect opened entry", entry.adapterKey, cause);
+            });
             if (!observed.isFile() ||
                 entry.sourceIdentity === undefined ||
                 observed.dev !== entry.sourceIdentity.device ||
@@ -85,6 +101,7 @@ export class DirectoryArtifactReader {
             return handle.createReadStream({ autoClose: true });
         }
         catch (cause) {
+            // best-effort cleanup: file-handle close must not mask the open failure.
             await handle.close().catch(() => undefined);
             throw cause;
         }
@@ -96,6 +113,25 @@ export class DirectoryArtifactReader {
         return [];
     }
 }
+const directoryIoFailure = (operation, path, cause) => {
+    if (cause instanceof ArtifactReaderFailure)
+        return cause;
+    const code = typeof cause === "object" &&
+        cause !== null &&
+        "code" in cause &&
+        typeof cause.code === "string"
+        ? ` (${cause.code})`
+        : "";
+    return new ArtifactReaderFailure("io", `Could not ${operation} at ${path}${code}`, { cause });
+};
+const withDirectoryIoContext = async (operation, path, action) => {
+    try {
+        return await action();
+    }
+    catch (cause) {
+        throw directoryIoFailure(operation, path, cause);
+    }
+};
 const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
         throw new ArtifactReaderFailure("cancelled", "Artifact traversal cancelled");