rea-agents 6.2.0 → 6.4.0

package/dist/artifacts/AsarArtifactReader.js

@@ -1,10 +1,16 @@
-import { constants, createReadStream } from "node:fs";
-import { lstat, open, realpath } from "node:fs/promises";
+import { constants, createReadStream, createWriteStream, } from "node:fs";
+import { lstat, mkdtemp, open, realpath, rm, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
 import { isAbsolute, join, relative, sep } from "node:path";
-import { Readable } from "node:stream";
-import { getRawHeader, listPackage, statFile, uncache } from "@electron/asar";
-import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { listPackage, statFile, uncache } from "@electron/asar";
+import { ArtifactReaderFailure, copyArtifactEntry, sameArtifactEntry, } from "./ArtifactReader.js";
 import { closeAsarHandle, readValidatedAsarEntry } from "./AsarEntryStream.js";
+import { admitAsarHeader } from "./AsarHeader.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
 /**
  * Official Electron ASAR adapter with range-streamed member reads.
  *
@@ -15,24 +21,39 @@ import { closeAsarHandle, readValidatedAsarEntry } from "./AsarEntryStream.js";
 export class AsarArtifactReader {
     path;
     openUnpackedFile;
+    removeSnapshot;
     format = "asar";
     #archiveSize;
     #headerSize;
     #entries = new Map();
-    constructor(path, openUnpackedFile = open) {
+    #unpackedHandles = new Map();
+    #snapshot;
+    #snapshotRoot;
+    #snapshotOperation = Promise.resolve();
+    constructor(path, openUnpackedFile = open, removeSnapshot = (path) => rm(path, { recursive: true, force: true })) {
         this.path = path;
         this.openUnpackedFile = openUnpackedFile;
+        this.removeSnapshot = removeSnapshot;
     }
     async *entries(signal) {
         let paths;
         try {
-            // ASAR caches headers by path even after the archive has been replaced.
+            await this.prepareContainer(undefined, signal);
+            const snapshotPath = this.#snapshotPath();
             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);
+            const headerHandle = await open(snapshotPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const admitted = await admitAsarHeader(headerHandle);
+                this.#archiveSize = admitted.archiveBytes;
+                this.#headerSize = admitted.headerBytes;
+            }
+            finally {
+                await headerHandle.close();
+            }
+            abortIfNeeded(signal);
+            paths = listPackage(snapshotPath, { isPack: false }).sort((left, right) => left.localeCompare(right, "en"));
+            const archiveMetadata = await lstat(snapshotPath);
             if (!archiveMetadata.isFile() || archiveMetadata.isSymbolicLink())
                 throw new ArtifactReaderFailure("format", "ASAR container is not a regular file");
             this.#archiveSize = archiveMetadata.size;
@@ -54,7 +75,7 @@ export class AsarArtifactReader {
                 : listed;
             let metadata;
             try {
-                metadata = statFile(this.path, providerPath, false);
+                metadata = statFile(this.#snapshotPath(), providerPath, false);
             }
             catch (cause) {
                 throw asarFailure(this.path, `stat ${path}`, cause);
@@ -102,24 +123,8 @@ export class AsarArtifactReader {
             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);
-        }
+        if (producedEntry.unpacked)
+            return this.#openUnpackedStream(producedEntry, signal);
         const archiveSize = this.#archiveSize;
         const headerSize = this.#headerSize;
         const offset = metadata.offset === undefined
@@ -138,7 +143,7 @@ export class AsarArtifactReader {
             throw new ArtifactReaderFailure("format", `ASAR entry range is outside its container: ${producedEntry.path}`);
         let handle;
         try {
-            const openedHandle = await open(this.path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const openedHandle = await open(this.#snapshotPath(), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
             handle = openedHandle;
             const observed = await openedHandle.stat();
             abortIfNeeded(signal);
@@ -161,22 +166,131 @@ export class AsarArtifactReader {
             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 });
+    /** Capture once per reader lifetime; bind all interpretation to these exact bytes. */
+    async prepareContainer(expectedSha256, signal) {
+        await this.#withSnapshotOperation(async () => {
+            abortIfNeeded(signal);
+            if (this.#snapshot === undefined && this.#snapshotRoot !== undefined)
+                await this.#closeSnapshot();
+            if (this.#snapshot === undefined)
+                await this.#captureSnapshot(signal);
+            if (expectedSha256 !== undefined &&
+                this.#snapshot?.sha256 !== expectedSha256)
+                throw new ArtifactReaderFailure("integrity", `ASAR container changed before interpretation: ${this.path}`);
+        }, signal);
     }
-    close() {
-        uncache(this.path);
-        this.#resetArchiveState();
-        this.#entries.clear();
-        return Promise.resolve();
+    /** Read the same captured container that supplies headers and packed members. */
+    async openContainer(signal) {
+        await this.prepareContainer(undefined, signal);
+        return createReadStream(this.#snapshotPath(), signal === undefined ? {} : { signal });
+    }
+    async close() {
+        await this.#withSnapshotOperation(async () => {
+            let cleanupFailure;
+            for (const [handle, { path }] of this.#unpackedHandles) {
+                try {
+                    await this.#closeUnpackedHandle(handle);
+                }
+                catch (cause) {
+                    cleanupFailure = ArtifactReaderFailure.withCleanup(cleanupFailure ?? cause, ArtifactReaderFailure.cleanupObservation(cause, path));
+                }
+            }
+            try {
+                await this.#closeSnapshot();
+            }
+            catch (cause) {
+                cleanupFailure = ArtifactReaderFailure.withCleanup(cleanupFailure ?? cause, ArtifactReaderFailure.cleanupObservation(cause, this.path));
+            }
+            if (cleanupFailure !== undefined)
+                throw cleanupFailure;
+        });
+    }
+    async #captureSnapshot(signal) {
+        try {
+            this.#snapshotRoot = await mkdtemp(join(tmpdir(), "rea-asar-snapshot-"));
+            const snapshotPath = join(this.#snapshotRoot, "container.asar");
+            const hash = createHash("sha256");
+            const handle = await open(this.path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const source = handle.createReadStream();
+            const digesting = new Transform({
+                transform(chunk, _encoding, callback) {
+                    hash.update(chunk);
+                    callback(null, chunk);
+                },
+            });
+            await pipeline(source, digesting, createWriteStream(snapshotPath, { flags: "wx", mode: 0o600 }), signal === undefined ? {} : { signal });
+            this.#snapshot = { path: snapshotPath, sha256: hash.digest("hex") };
+        }
+        catch (cause) {
+            const primary = signal?.aborted === true
+                ? new ArtifactReaderFailure("cancelled", "ASAR operation cancelled", {
+                    cause,
+                })
+                : asarFailure(this.path, "snapshot", cause);
+            try {
+                await this.#closeSnapshot();
+            }
+            catch (cleanupCause) {
+                throw ArtifactReaderFailure.withCleanup(primary, ArtifactReaderFailure.cleanupObservation(cleanupCause, this.#snapshotRoot ?? this.path));
+            }
+            throw primary;
+        }
+    }
+    async #closeSnapshot() {
+        const root = this.#snapshotRoot;
+        if (root !== undefined) {
+            try {
+                await this.removeSnapshot(root);
+                if (this.#snapshotRoot === root)
+                    this.#snapshotRoot = undefined;
+            }
+            catch (cause) {
+                throw ArtifactReaderFailure.withCleanup(cause, {
+                    reason: `Could not remove ASAR snapshot: ${root}`,
+                    resources: [root],
+                });
+            }
+        }
+        if (root === undefined || this.#snapshotRoot === undefined) {
+            if (this.#snapshot !== undefined)
+                uncache(this.#snapshot.path);
+            this.#snapshot = undefined;
+            this.#resetArchiveState();
+            this.#entries.clear();
+        }
+    }
+    async #withSnapshotOperation(operation, signal) {
+        const previous = this.#snapshotOperation;
+        let release;
+        this.#snapshotOperation = new Promise((resolve) => {
+            release = resolve;
+        });
+        try {
+            await waitForOperation(previous, signal);
+        }
+        catch (cause) {
+            void previous.then(release, release);
+            throw cause;
+        }
+        try {
+            abortIfNeeded(signal);
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    #snapshotPath() {
+        if (this.#snapshot === undefined)
+            throw new ArtifactReaderFailure("integrity", "ASAR snapshot is not available");
+        return this.#snapshot.path;
     }
     provenance() {
         return [];
     }
-    async #openUnpackedEntry(entry) {
+    async #openUnpackedStream(entry, signal) {
         const unpackedRoot = `${this.path}.unpacked`;
+        let handle;
         try {
             const rootMetadata = await lstat(unpackedRoot);
             if (!rootMetadata.isDirectory() || rootMetadata.isSymbolicLink())
@@ -192,17 +306,16 @@ export class AsarArtifactReader {
             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;
+            handle = await this.openUnpackedFile(canonical, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const openedHandle = handle;
+            this.#unpackedHandles.set(openedHandle, {
+                path: canonical,
+                owner: new OwnedFileHandle(openedHandle),
             });
+            const openedMetadata = await openedHandle.stat();
             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,
@@ -210,47 +323,52 @@ export class AsarArtifactReader {
                     unpacked: true,
                 });
             }
-            return handle;
+            abortIfNeeded(signal);
+            const source = readFileHandleChunks(openedHandle, {
+                start: 0,
+            });
+            source.once("close", () => {
+                void this.#closeUnpackedHandle(openedHandle).catch(() => undefined);
+            });
+            return readValidatedAsarEntry(source, undefined, entry.path, this.path, signal);
         }
         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);
+            let failure = asarUnpackedEntryFailure(this.path, entry, cause);
+            if (handle !== undefined && this.#unpackedHandles.has(handle)) {
+                try {
+                    await this.#closeUnpackedHandle(handle);
+                }
+                catch (cleanupCause) {
+                    failure = ArtifactReaderFailure.withCleanup(failure, ArtifactReaderFailure.cleanupObservation(cleanupCause, this.#unpackedHandles.get(handle)?.path ?? entry.path));
+                }
+            }
+            throw failure;
         }
     }
+    async #closeUnpackedHandle(handle) {
+        const owned = this.#unpackedHandles.get(handle);
+        if (owned === undefined)
+            return;
+        await owned.owner.close();
+        this.#unpackedHandles.delete(handle);
+    }
     #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 asarUnpackedEntryFailure = (archivePath, entry, cause) => {
+    if (cause instanceof ArtifactReaderFailure)
+        return cause;
+    if (entry.unpacked && isMissingFile(cause))
+        return new ArtifactReaderFailure("unavailable", `ASAR unpacked entry bytes are unavailable: ${entry.path}`, { cause }, {
+            logicalPath: entry.path,
+            declaredSha256: entry.declaredSha256,
+            calculatedSha256: null,
+            unpacked: true,
+        });
+    return asarFailure(archivePath, `read ${entry.path}`, cause);
+};
 const isAsarFileMetadata = (metadata) => "size" in metadata &&
     typeof metadata.size === "number" &&
     !("files" in metadata) &&
@@ -265,6 +383,26 @@ const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
         throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
 };
+const waitForOperation = async (operation, signal) => {
+    if (signal === undefined)
+        return operation;
+    abortIfNeeded(signal);
+    await new Promise((resolve, reject) => {
+        const removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+        const onAbort = () => {
+            removeAbortListener();
+            reject(new ArtifactReaderFailure("cancelled", "ASAR operation cancelled"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        operation.then(() => {
+            removeAbortListener();
+            resolve();
+        }, (cause) => {
+            removeAbortListener();
+            reject(cause);
+        });
+    });
+};
 const toArtifactPath = (listed) => {
     const portable = sep === "\\" ? listed.replaceAll("\\", "/") : listed;
     return portable.replace(/^\/+|\/+$/gu, "");

package/dist/artifacts/AsarHeader.js

@@ -0,0 +1,24 @@
+import { ArtifactReaderFailure } from "./ArtifactReader.js";
+/** Shared resource budget for the eagerly decoded ASAR header, not member bytes. */
+export const MAX_ASAR_HEADER_BYTES = 16 * 1024 * 1024;
+/** Admit both Chromium pickle extents before an upstream decoder allocates them. */
+export const admitAsarHeader = async (handle) => {
+    const observed = await handle.stat();
+    if (!observed.isFile())
+        throw new ArtifactReaderFailure("format", "ASAR container is not a regular file");
+    const prefix = Buffer.alloc(16);
+    const read = await handle.read(prefix, 0, prefix.length, 0);
+    if (read.bytesRead !== prefix.length || prefix.readUInt32LE(0) !== 4)
+        throw new ArtifactReaderFailure("format", "Truncated or invalid ASAR size pickle");
+    const headerBytes = prefix.readUInt32LE(4);
+    const payloadBytes = prefix.readUInt32LE(8);
+    const jsonBytes = prefix.readUInt32LE(12);
+    if (headerBytes < 8 ||
+        headerBytes > observed.size - 8 ||
+        payloadBytes !== headerBytes - 4 ||
+        jsonBytes > payloadBytes - 4)
+        throw new ArtifactReaderFailure("format", "ASAR header leaves its container or has invalid pickle extents");
+    if (headerBytes > MAX_ASAR_HEADER_BYTES)
+        throw new ArtifactReaderFailure("limit", `ASAR header exceeds the ${String(MAX_ASAR_HEADER_BYTES)} byte decode budget`);
+    return { archiveBytes: observed.size, headerBytes, jsonBytes };
+};