rea-agents 6.3.0 → 6.5.0

package/dist/artifacts/AsarArtifactReader.js

@@ -1,13 +1,17 @@
-import { constants, createReadStream, createWriteStream, } from "node:fs";
+import { constants, 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, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import { getRawHeader, listPackage, statFile, uncache } from "@electron/asar";
-import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+import { getRawHeader, 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";
+import { readAsarListing, } from "./AsarListing.js";
 /**
  * Official Electron ASAR adapter with range-streamed member reads.
  *
@@ -17,69 +21,59 @@ import { closeAsarHandle, readValidatedAsarEntry } from "./AsarEntryStream.js";
  */
 export class AsarArtifactReader {
     path;
-    openUnpackedFile;
-    removeSnapshot;
+    options;
     format = "asar";
     #archiveSize;
     #headerSize;
     #entries = new Map();
+    #ownedHandles = new Map();
     #snapshot;
     #snapshotRoot;
-    constructor(path, openUnpackedFile = open, removeSnapshot = (path) => rm(path, { recursive: true, force: true })) {
+    #snapshotOperation = Promise.resolve();
+    constructor(path, options = {}) {
         this.path = path;
-        this.openUnpackedFile = openUnpackedFile;
-        this.removeSnapshot = removeSnapshot;
+        this.options = options;
     }
     async *entries(signal) {
         let paths;
         try {
             await this.prepareContainer(undefined, signal);
-            const snapshotPath = this.#snapshotPath();
-            this.#resetArchiveState();
-            this.#entries.clear();
-            paths = listPackage(snapshotPath, { isPack: false }).sort((left, right) => left.localeCompare(right, "en"));
-            this.#headerSize = getRawHeader(snapshotPath).headerSize;
-            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;
+            paths = await this.#withSnapshotOperation(async () => {
+                const snapshotPath = this.#snapshotPath();
+                this.#resetArchiveState();
+                this.#entries.clear();
+                const admitted = await this.#admitHeader(snapshotPath);
+                this.#archiveSize = admitted.archiveBytes;
+                this.#headerSize = admitted.headerBytes;
+                abortIfNeeded(signal);
+                const ordered = await readAsarListing(getRawHeader(snapshotPath).header, signal);
+                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;
+                return ordered;
+            }, signal);
         }
         catch (cause) {
             throw asarFailure(this.path, "inventory", cause);
         }
-        for (const listed of paths) {
+        for (const { metadata, path } of paths) {
             abortIfNeeded(signal);
-            // @electron/asar returns paths assembled with the host path module.
-            // Keep that spelling for its API calls, but expose archive paths with
-            // portable separators. On POSIX, backslashes can be literal filename
-            // characters and must remain untouched.
-            const path = toArtifactPath(listed);
-            if (path.length === 0)
-                continue;
-            const providerPath = listed.startsWith(sep)
-                ? listed.slice(sep.length)
-                : listed;
-            let metadata;
-            try {
-                metadata = statFile(this.#snapshotPath(), providerPath, false);
-            }
-            catch (cause) {
-                throw asarFailure(this.path, `stat ${path}`, cause);
-            }
-            const kind = "files" in metadata
+            const providerPath = path.split("/").join(sep);
+            const kind = metadata.files !== undefined
                 ? "directory"
-                : "link" in metadata
+                : metadata.link !== undefined
                     ? "symlink"
                     : "file";
             const entry = {
                 path,
                 kind,
-                declaredSize: "size" in metadata ? metadata.size : null,
+                declaredSize: metadata.size ?? null,
                 compressedSize: null,
-                executable: "executable" in metadata && metadata.executable,
+                executable: metadata.executable === true,
                 encrypted: false,
                 byteOffset: null,
-                declaredSha256: "integrity" in metadata &&
+                declaredSha256: metadata.integrity !== undefined &&
                     metadata.integrity.algorithm === "SHA256" &&
                     /^[a-f0-9]{64}$/u.test(metadata.integrity.hash)
                     ? metadata.integrity.hash
@@ -98,7 +92,31 @@ export class AsarArtifactReader {
             yield entry;
         }
     }
+    async #admitHeader(snapshotPath) {
+        const headerHandle = await this.#openOwned(snapshotPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        let admission;
+        try {
+            admission = { ok: true, value: await admitAsarHeader(headerHandle) };
+        }
+        catch (cause) {
+            admission = { ok: false, cause };
+        }
+        try {
+            await this.#closeOwnedHandle(headerHandle);
+        }
+        catch (cleanupCause) {
+            if (!admission.ok)
+                throw ArtifactReaderFailure.withCleanup(admission.cause, ArtifactReaderFailure.cleanupObservation(cleanupCause, snapshotPath));
+            throw cleanupCause;
+        }
+        if (!admission.ok)
+            throw admission.cause;
+        return admission.value;
+    }
     async open(entry, signal) {
+        return this.#withSnapshotOperation(() => this.#openEntry(entry, signal), signal);
+    }
+    async #openEntry(entry, signal) {
         abortIfNeeded(signal);
         const state = this.#entries.get(entry.adapterKey);
         if (state === undefined && entry.kind !== "file")
@@ -107,26 +125,12 @@ export class AsarArtifactReader {
             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);
-        }
+        if (state.entry.unpacked)
+            return this.#openUnpackedStream(state.entry, signal);
+        return this.#openPackedStream(state, signal);
+    }
+    async #openPackedStream(state, signal) {
+        const { metadata, entry: producedEntry } = state;
         const archiveSize = this.#archiveSize;
         const headerSize = this.#headerSize;
         const offset = metadata.offset === undefined
@@ -143,79 +147,126 @@ export class AsarArtifactReader {
             start > archiveSize ||
             metadata.size > archiveSize - start)
             throw new ArtifactReaderFailure("format", `ASAR entry range is outside its container: ${producedEntry.path}`);
+        const snapshotPath = this.#snapshotPath();
         let handle;
         try {
-            const openedHandle = await open(this.#snapshotPath(), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const openedHandle = await this.#openOwned(snapshotPath, 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;
+                await closeAsarHandle(() => this.#closeOwnedHandle(openedHandle), signal);
                 return Readable.from([]);
             }
-            const source = openedHandle.createReadStream({
+            const source = this.#ownedReadStream(openedHandle, {
                 start,
                 end: start + metadata.size - 1,
-                autoClose: true,
+                signal,
             });
-            return readValidatedAsarEntry(source, metadata.size, producedEntry.path, this.path, signal);
+            handle = undefined;
+            const output = readValidatedAsarEntry(source, metadata.size, producedEntry.path, this.path, signal);
+            this.#setOwnedOutput(openedHandle, output);
+            return output;
         }
         catch (cause) {
-            await handle?.close().catch(() => undefined);
-            throw asarFailure(this.path, `read ${producedEntry.path}`, cause);
-        }
-    }
-    /** Capture once per reader lifetime; bind all interpretation to these exact bytes. */
-    async prepareContainer(expectedSha256, signal) {
-        abortIfNeeded(signal);
-        if (this.#snapshot === undefined && this.#snapshotRoot !== undefined)
-            await this.close();
-        if (this.#snapshot === undefined) {
-            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);
+            const failure = asarFailure(this.path, `read ${producedEntry.path}`, cause);
+            if (handle !== undefined) {
                 try {
-                    await this.close();
+                    await this.#closeOwnedHandle(handle);
                 }
                 catch (cleanupCause) {
-                    throw ArtifactReaderFailure.withCleanup(primary, ArtifactReaderFailure.cleanupObservation(cleanupCause, this.path));
+                    throw ArtifactReaderFailure.withCleanup(failure, ArtifactReaderFailure.cleanupObservation(cleanupCause, snapshotPath));
                 }
-                throw primary;
             }
+            throw failure;
         }
-        if (expectedSha256 !== undefined &&
-            this.#snapshot.sha256 !== expectedSha256)
-            throw new ArtifactReaderFailure("integrity", `ASAR container changed before interpretation: ${this.path}`);
+    }
+    /** 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);
     }
     /** 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 });
+        return this.#withSnapshotOperation(async () => {
+            abortIfNeeded(signal);
+            const snapshotPath = this.#snapshotPath();
+            const handle = await this.#openOwned(snapshotPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            return this.#ownedReadStream(handle, { signal });
+        }, signal);
     }
     async close() {
+        await this.#withSnapshotOperation(() => this.#closeSnapshot());
+    }
+    async #captureSnapshot(signal) {
+        let inputHandle;
+        try {
+            this.#snapshotRoot = await mkdtemp(join(tmpdir(), "rea-asar-snapshot-"));
+            const snapshotPath = join(this.#snapshotRoot, "container.asar");
+            const hash = createHash("sha256");
+            inputHandle = await this.#openOwned(this.path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const source = this.#ownedReadStream(inputHandle, {
+                signal,
+                releaseOnClose: false,
+            });
+            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 });
+            const completedInput = inputHandle;
+            inputHandle = undefined;
+            await this.#closeOwnedHandle(completedInput);
+            this.#snapshot = { path: snapshotPath, sha256: hash.digest("hex") };
+        }
+        catch (cause) {
+            let failure = signal?.aborted === true
+                ? new ArtifactReaderFailure("cancelled", "ASAR operation cancelled", {
+                    cause,
+                })
+                : asarFailure(this.path, "snapshot", cause);
+            if (inputHandle !== undefined) {
+                const failedInput = inputHandle;
+                inputHandle = undefined;
+                try {
+                    await this.#closeOwnedHandle(failedInput);
+                }
+                catch (cleanupCause) {
+                    failure = ArtifactReaderFailure.withCleanup(failure, ArtifactReaderFailure.cleanupObservation(cleanupCause, this.path));
+                }
+            }
+            try {
+                if (this.#ownedHandles.size === 0)
+                    await this.#closeSnapshot();
+            }
+            catch (cleanupCause) {
+                throw ArtifactReaderFailure.withCleanup(failure, ArtifactReaderFailure.cleanupObservation(cleanupCause, this.#snapshotRoot ?? this.path));
+            }
+            throw failure;
+        }
+    }
+    async #closeSnapshot() {
+        await this.#closeOwnedHandles();
         const root = this.#snapshotRoot;
         if (root !== undefined) {
             try {
-                await this.removeSnapshot(root);
+                await (this.options.removeSnapshot ?? defaultRemoveSnapshot)(root);
+                if (this.#snapshotRoot === root)
+                    this.#snapshotRoot = undefined;
             }
             catch (cause) {
                 throw ArtifactReaderFailure.withCleanup(cause, {
@@ -223,13 +274,35 @@ export class AsarArtifactReader {
                     resources: [root],
                 });
             }
-            this.#snapshotRoot = undefined;
         }
-        if (this.#snapshot !== undefined)
-            uncache(this.#snapshot.path);
-        this.#snapshot = undefined;
-        this.#resetArchiveState();
-        this.#entries.clear();
+        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)
@@ -239,8 +312,9 @@ export class AsarArtifactReader {
     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())
@@ -256,17 +330,13 @@ 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.options.openUnpackedFile ?? open)(canonical, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const openedHandle = handle;
+            this.#adoptHandle(openedHandle, canonical);
+            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,
@@ -274,51 +344,104 @@ export class AsarArtifactReader {
                     unpacked: true,
                 });
             }
-            return handle;
+            abortIfNeeded(signal);
+            const source = this.#ownedReadStream(openedHandle, { start: 0 });
+            handle = undefined;
+            const output = readValidatedAsarEntry(source, undefined, entry.path, this.path, signal);
+            this.#setOwnedOutput(openedHandle, output);
+            return output;
         }
         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.#ownedHandles.has(handle)) {
+                try {
+                    await this.#closeOwnedHandle(handle);
+                }
+                catch (cleanupCause) {
+                    failure = ArtifactReaderFailure.withCleanup(failure, ArtifactReaderFailure.cleanupObservation(cleanupCause, this.#ownedHandles.get(handle)?.path ?? entry.path));
+                }
+            }
+            throw failure;
         }
     }
+    async #closeOwnedHandle(handle) {
+        const owned = this.#ownedHandles.get(handle);
+        if (owned === undefined)
+            return;
+        owned.output?.destroy();
+        owned.source?.destroy();
+        try {
+            await owned.owner.close();
+        }
+        catch (cause) {
+            throw ArtifactReaderFailure.withCleanup(cause, ArtifactReaderFailure.cleanupObservation(cause, owned.path));
+        }
+        this.#ownedHandles.delete(handle);
+    }
+    async #closeOwnedHandles() {
+        let failure;
+        for (const [handle, owned] of this.#ownedHandles) {
+            try {
+                await this.#closeOwnedHandle(handle);
+            }
+            catch (cause) {
+                failure = ArtifactReaderFailure.withCleanup(failure ?? cause, ArtifactReaderFailure.cleanupObservation(cause, owned.path));
+            }
+        }
+        if (failure !== undefined)
+            throw failure;
+    }
+    async #openOwned(path, flags) {
+        const handle = await (this.options.openFile ?? open)(path, flags);
+        this.#adoptHandle(handle, path);
+        return handle;
+    }
+    #adoptHandle(handle, path) {
+        this.#ownedHandles.set(handle, {
+            path,
+            owner: new OwnedFileHandle(handle),
+        });
+    }
+    #ownedReadStream(handle, options) {
+        const { releaseOnClose, ...readOptions } = options;
+        const source = readFileHandleChunks(handle, readOptions);
+        const owned = this.#ownedHandles.get(handle);
+        if (owned === undefined)
+            throw new ArtifactReaderFailure("integrity", "ASAR handle has no owner");
+        owned.source = source;
+        owned.output = source;
+        if (releaseOnClose !== false)
+            source.once("close", () => {
+                void this.#closeOwnedHandle(handle).catch(() => undefined);
+            });
+        return source;
+    }
+    #setOwnedOutput(handle, output) {
+        const owned = this.#ownedHandles.get(handle);
+        if (owned !== undefined)
+            owned.output = output;
+    }
     #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 defaultRemoveSnapshot = (path) => rm(path, { recursive: true, force: true });
+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) => typeof metadata.size === "number" &&
+    metadata.files === undefined &&
+    metadata.link === undefined;
 const parseArchiveOffset = (value) => {
     if (!/^(?:0|[1-9][0-9]*)$/u.test(value))
         return undefined;
@@ -329,9 +452,25 @@ const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
         throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
 };
-const toArtifactPath = (listed) => {
-    const portable = sep === "\\" ? listed.replaceAll("\\", "/") : listed;
-    return portable.replace(/^\/+|\/+$/gu, "");
+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 asarFailure = (path, operation, cause) => {
     if (cause instanceof ArtifactReaderFailure)

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