Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

perf(artifacts): stream ASAR members without full buffering (#962)

morlutoabd7a5ed0910
diff --git a/src/artifacts/AsarArtifactReader.ts b/src/artifacts/AsarArtifactReader.ts
index e231dae96..02ebb1bbe 100644
--- a/src/artifacts/AsarArtifactReader.ts
+++ b/src/artifacts/AsarArtifactReader.ts
@@ -1,17 +1,19 @@
-import { createReadStream } from "node:fs";
-import { sep } from "node:path";
+import { constants, createReadStream, type Stats } from "node:fs";
+import { lstat, open, realpath, type FileHandle } 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,
type ArtifactEntry,
type ArtifactReader,
} 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
@@ -19,17 +21,33 @@ import {
*/
export class AsarArtifactReader implements ArtifactReader {
readonly format = "asar" as const;
+ #archiveSize: number | undefined;
+ #headerSize: number | undefined;
+ readonly #entries = new Map<string, AsarEntryState>();
- constructor(private readonly path: string) {}
+ constructor(
+ private readonly path: string,
+ private readonly openUnpackedFile: OpenAsarUnpackedFile = open,
+ ) {}
async *entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry> {
let paths: string[];
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: unknown) {
throw asarFailure(this.path, "inventory", cause);
}
@@ -56,7 +74,7 @@ export class AsarArtifactReader implements ArtifactReader {
: "link" in metadata
? "symlink"
: "file";
- yield {
+ const entry: ArtifactEntry = {
path,
kind,
declaredSize: "size" in metadata ? metadata.size : null,
@@ -74,42 +92,121 @@ export class AsarArtifactReader implements ArtifactReader {
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: ArtifactEntry, signal?: AbortSignal): Promise<Readable> {
+ async open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable> {
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: unknown) {
+ 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: FileHandle | undefined;
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,
);
- } catch (cause: unknown) {
- 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,
- },
- ),
+ 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}`,
);
- return Promise.reject(
- asarFailure(this.path, `read ${entry.path}`, cause),
+ 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: unknown) {
+ await handle?.close().catch(() => undefined);
+ throw asarFailure(this.path, `read ${producedEntry.path}`, cause);
}
}
@@ -121,14 +218,154 @@ export class AsarArtifactReader implements ArtifactReader {
close(): Promise<void> {
uncache(this.path);
+ this.#resetArchiveState();
+ this.#entries.clear();
return Promise.resolve();
}
provenance(): readonly [] {
return [];
}
+
+ async #openUnpackedEntry(entry: ArtifactEntry): Promise<UnpackedFileHandle> {
+ 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: unknown) => {
+ 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: unknown) {
+ 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(): void {
+ this.#archiveSize = undefined;
+ this.#headerSize = undefined;
+ }
}
+type AsarFileMetadata = Extract<ReturnType<typeof statFile>, { size: number }>;
+type AsarEntryState = {
+ readonly metadata: AsarFileMetadata;
+ readonly entry: ArtifactEntry;
+};
+type UnpackedFileHandle = {
+ stat(): Promise<Stats>;
+ close(): Promise<void>;
+ createReadStream: FileHandle["createReadStream"];
+};
+type OpenAsarUnpackedFile = (
+ path: string,
+ flags: number,
+) => Promise<UnpackedFileHandle>;
+
+const copyArtifactEntry = (entry: ArtifactEntry): ArtifactEntry => ({
+ ...entry,
+ limitations: [...entry.limitations],
+ ...(entry.sourceIdentity === undefined
+ ? {}
+ : { sourceIdentity: { ...entry.sourceIdentity } }),
+});
+
+const sameArtifactEntry = (
+ entry: ArtifactEntry,
+ produced: ArtifactEntry,
+): boolean =>
+ 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: ReturnType<typeof statFile>,
+): metadata is AsarFileMetadata =>
+ "size" in metadata &&
+ typeof metadata.size === "number" &&
+ !("files" in metadata) &&
+ !("link" in metadata);
+
+const parseArchiveOffset = (value: string): number | undefined => {
+ if (!/^(?:0|[1-9][0-9]*)$/u.test(value)) return undefined;
+ const offset = Number(value);
+ return Number.isSafeInteger(offset) ? offset : undefined;
+};
+
const abortIfNeeded = (signal?: AbortSignal): void => {
if (signal?.aborted === true)
throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
diff --git a/src/artifacts/AsarEntryStream.ts b/src/artifacts/AsarEntryStream.ts
new file mode 100644
index 000000000..b11b233d6
--- /dev/null
+++ b/src/artifacts/AsarEntryStream.ts
@@ -0,0 +1,111 @@
+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: () => Promise<void>,
+ signal?: AbortSignal,
+): Promise<void> => {
+ await close();
+ abortIfNeeded(signal);
+};
+
+/** Validate and contextualize bytes read from one ASAR member source. */
+export const readValidatedAsarEntry = (
+ source: Readable,
+ expectedBytes: number | undefined,
+ entryPath: string,
+ archivePath: string,
+ signal?: AbortSignal,
+): Readable => {
+ 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: unknown = 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: unknown) {
+ 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 = (): void => {
+ signal?.removeEventListener("abort", onAbort);
+ if (!source.destroyed) source.destroy();
+ };
+ const onAbort = (): void => {
+ 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?: AbortSignal): void => {
+ if (signal?.aborted === true)
+ throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
+};
+
+const asarFailure = (
+ path: string,
+ operation: string,
+ cause: unknown,
+): ArtifactReaderFailure => {
+ 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: unknown,
+): cause is NodeJS.ErrnoException & Error =>
+ cause instanceof Error &&
+ "errno" in cause &&
+ typeof cause.errno === "number" &&
+ "syscall" in cause &&
+ typeof cause.syscall === "string";
diff --git a/tests/boundary/filesystem/asarStreamingAllocation.test.ts b/tests/boundary/filesystem/asarStreamingAllocation.test.ts
new file mode 100644
index 000000000..6a5fac5e4
--- /dev/null
+++ b/tests/boundary/filesystem/asarStreamingAllocation.test.ts
@@ -0,0 +1,474 @@
+import { createHash } from "node:crypto";
+import { fstatSync, type Stats } from "node:fs";
+import {
+ open as openFile,
+ lstat,
+ mkdir,
+ rm,
+ readdir,
+ writeFile,
+ truncate,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { buffer } from "node:stream/consumers";
+import { createPackageWithOptions } from "@electron/asar";
+import { describe, expect, it } from "vitest";
+import { scanArtifactInventory } from "../../../src/application/ArtifactInventory.js";
+import { AsarArtifactReader } from "../../../src/artifacts/AsarArtifactReader.js";
+import {
+ closeAsarHandle,
+ readValidatedAsarEntry,
+} from "../../../src/artifacts/AsarEntryStream.js";
+import { hashReadable } from "../../../src/artifacts/ArtifactHash.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+
+const memberBytes = 64 * 1024 * 1024;
+const expectedSha256 = (): string => {
+ const hash = createHash("sha256");
+ const zeros = Buffer.alloc(64 * 1024);
+ for (let written = 0; written < memberBytes; written += zeros.length)
+ hash.update(zeros);
+ return hash.digest("hex");
+};
+
+const descriptorDirectory =
+ process.platform === "darwin" ? "/dev/fd" : "/proc/self/fd";
+
+const matchingDescriptorCount = async (identity: Stats): Promise<number> => {
+ const descriptors = await readdir(descriptorDirectory);
+ return descriptors.filter((descriptor) => {
+ if (!/^\d+$/u.test(descriptor)) return false;
+ try {
+ const observed = fstatSync(Number(descriptor));
+ return observed.dev === identity.dev && observed.ino === identity.ino;
+ } catch {
+ return false;
+ }
+ }).length;
+};
+
+const waitForNoMatchingDescriptor = async (identity: Stats): Promise<void> => {
+ for (let attempt = 0; attempt < 100; attempt += 1) {
+ if ((await matchingDescriptorCount(identity)) === 0) return;
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ }
+ expect(await matchingDescriptorCount(identity)).toBe(0);
+};
+
+describe("ASAR entry streaming", () => {
+ it.skipIf(process.platform === "win32")(
+ "closes a packed member handle when its unopened output stream is destroyed",
+ async () => {
+ const root = await createTestTempDirectory(
+ "rea-asar-destroy-before-read-",
+ );
+ const source = join(root, "source");
+ const archive = join(root, "fixture.asar");
+ await mkdir(source);
+ await writeFile(join(source, "small.js"), "module.exports = 1;\n");
+ await createPackageWithOptions(source, archive, {});
+
+ const identity = await lstat(archive);
+ const probe = await openFile(archive, "r");
+ expect(await matchingDescriptorCount(identity)).toBeGreaterThan(0);
+ await probe.close();
+ await waitForNoMatchingDescriptor(identity);
+ const reader = new AsarArtifactReader(archive);
+
+ try {
+ const entries = [];
+ for await (const entry of reader.entries()) {
+ entries.push(entry);
+ }
+ const entry = entries.find(({ path }) => path === "small.js");
+ if (entry === undefined) throw new Error("Expected packed ASAR member");
+ expect(await matchingDescriptorCount(identity)).toBe(0);
+ const output = await reader.open(entry);
+ expect(await matchingDescriptorCount(identity)).toBeGreaterThan(0);
+ const closed = new Promise<void>((resolve) =>
+ output.once("close", resolve),
+ );
+ output.destroy();
+ await closed;
+ await waitForNoMatchingDescriptor(identity);
+ } finally {
+ await reader.close();
+ }
+ },
+ );
+
+ it.skipIf(process.platform === "win32")(
+ "closes a packed member handle when cancellation arrives during open",
+ async () => {
+ const root = await createTestTempDirectory("rea-asar-abort-during-stat-");
+ const source = join(root, "source");
+ const archive = join(root, "fixture.asar");
+ await mkdir(source);
+ await writeFile(join(source, "small.js"), "module.exports = 1;\n");
+ await createPackageWithOptions(source, archive, {});
+
+ const identity = await lstat(archive);
+ const reader = new AsarArtifactReader(archive);
+
+ try {
+ const entries = [];
+ for await (const entry of reader.entries()) entries.push(entry);
+ const entry = entries.find(({ path }) => path === "small.js");
+ if (entry === undefined) throw new Error("Expected packed ASAR member");
+ const controller = new AbortController();
+ const opening = reader.open(entry, controller.signal);
+ controller.abort();
+ await expect(opening).rejects.toMatchObject({ reason: "cancelled" });
+ await waitForNoMatchingDescriptor(identity);
+ } finally {
+ await reader.close();
+ }
+ },
+ );
+
+ it("classifies a missing packed member container as an I/O failure", async () => {
+ const root = await createTestTempDirectory("rea-asar-missing-member-");
+ const source = join(root, "source");
+ const archive = join(root, "fixture.asar");
+ await mkdir(source);
+ await writeFile(join(source, "small.js"), "module.exports = 1;\n");
+ await createPackageWithOptions(source, archive, {});
+
+ const reader = new AsarArtifactReader(archive);
+ try {
+ const entries = [];
+ for await (const entry of reader.entries()) entries.push(entry);
+ const entry = entries.find(({ path }) => path === "small.js");
+ if (entry === undefined) throw new Error("Expected packed ASAR member");
+ await rm(archive);
+ await expect(reader.open(entry)).rejects.toMatchObject({
+ reason: "io",
+ cause: { code: "ENOENT" },
+ });
+ } finally {
+ await reader.close();
+ }
+ });
+});
+
+describe("ASAR entry producer identity", () => {
+ it.each([false, true] as const)(
+ "rejects a copied entry with a changed unpacked flag for unpacked=%s",
+ async (unpacked) => {
+ const root = await createTestTempDirectory("rea-asar-entry-identity-");
+ const source = join(root, "source");
+ const archive = join(root, "fixture.asar");
+ await mkdir(source);
+ await writeFile(join(source, "small.js"), "module.exports = 1;\n");
+ await createPackageWithOptions(
+ source,
+ archive,
+ unpacked ? { unpack: "small.js" } : {},
+ );
+ const selectedPath = unpacked
+ ? join(`${archive}.unpacked`, "small.js")
+ : archive;
+ const identity = await lstat(selectedPath);
+ const reader = new AsarArtifactReader(archive);
+
+ try {
+ const entries = [];
+ for await (const entry of reader.entries()) entries.push(entry);
+ const entry = entries.find(({ path }) => path === "small.js");
+ if (entry === undefined) throw new Error("Expected ASAR file entry");
+ expect(entry.unpacked).toBe(unpacked);
+ expect(await matchingDescriptorCount(identity)).toBe(0);
+ if (entry.declaredSize === null)
+ throw new Error("Expected ASAR file size metadata");
+
+ for (const changedEntry of [
+ { ...entry, unpacked: !entry.unpacked },
+ { ...entry, path: `stale/${entry.path}` },
+ { ...entry, declaredSize: entry.declaredSize + 1 },
+ ])
+ await expect(reader.open(changedEntry)).rejects.toMatchObject({
+ name: "ArtifactReaderFailure",
+ reason: "integrity",
+ message: expect.stringContaining(
+ `ASAR entry metadata changed since inventory: ${entry.path}`,
+ ),
+ });
+ await waitForNoMatchingDescriptor(identity);
+ } finally {
+ await reader.close();
+ }
+ },
+ );
+
+ it.each([
+ ["packed to unpacked", false],
+ ["unpacked to packed", true],
+ ] as const)(
+ "rejects a retained %s entry after a new entries pass",
+ async (_transition, wasUnpacked) => {
+ const root = await createTestTempDirectory("rea-asar-entry-refresh-");
+ const source = join(root, "source");
+ const archive = join(root, "fixture.asar");
+ const memberContents = "module.exports = 1;\n";
+ await mkdir(source);
+ await writeFile(join(source, "small.js"), memberContents);
+ const reader = new AsarArtifactReader(archive);
+
+ try {
+ await createPackageWithOptions(
+ source,
+ archive,
+ wasUnpacked ? { unpack: "small.js" } : {},
+ );
+ const firstEntries = [];
+ for await (const entry of reader.entries()) firstEntries.push(entry);
+ const retained = firstEntries.find(({ path }) => path === "small.js");
+ if (retained === undefined)
+ throw new Error("Expected first ASAR file entry");
+ const copiedRetained = {
+ ...retained,
+ limitations: [...retained.limitations],
+ };
+
+ await createPackageWithOptions(
+ source,
+ archive,
+ wasUnpacked ? {} : { unpack: "small.js" },
+ );
+ const currentEntries = [];
+ for await (const entry of reader.entries()) currentEntries.push(entry);
+ const current = currentEntries.find(({ path }) => path === "small.js");
+ if (current === undefined)
+ throw new Error("Expected refreshed ASAR file entry");
+ expect(current.unpacked).toBe(!wasUnpacked);
+
+ await expect(reader.open(copiedRetained)).rejects.toMatchObject({
+ name: "ArtifactReaderFailure",
+ reason: "integrity",
+ message: expect.stringContaining(
+ "ASAR entry metadata changed since inventory",
+ ),
+ });
+ expect((await buffer(await reader.open(current))).toString()).toBe(
+ memberContents,
+ );
+ } finally {
+ await reader.close();
+ }
+ },
+ );
+});
+
+describe("ASAR read failures", () => {
+ it.skipIf(process.platform === "win32")(
+ "checks cancellation after closing an empty member handle",
+ async () => {
+ const root = await createTestTempDirectory("rea-asar-empty-close-");
+ const archive = join(root, "container.asar");
+ await writeFile(archive, "container bytes");
+ const identity = await lstat(archive);
+ const handle = await openFile(archive, "r");
+ try {
+ expect(await matchingDescriptorCount(identity)).toBeGreaterThan(0);
+ const controller = new AbortController();
+
+ await expect(
+ closeAsarHandle(async () => {
+ await handle.close();
+ controller.abort();
+ }, controller.signal),
+ ).rejects.toMatchObject({ reason: "cancelled" });
+ await waitForNoMatchingDescriptor(identity);
+ } finally {
+ await handle.close().catch(() => undefined);
+ }
+ },
+ );
+
+ it.skipIf(process.platform === "win32")(
+ "closes the opened unpacked file and retains ASAR context when handle stat fails",
+ async () => {
+ const root = await createTestTempDirectory("rea-asar-unpacked-stat-");
+ const source = join(root, "source");
+ const archive = join(root, "fixture.asar");
+ await mkdir(source);
+ await writeFile(join(source, "small.js"), "module.exports = 1;\n");
+ await createPackageWithOptions(source, archive, { unpack: "small.js" });
+ const unpackedPath = join(`${archive}.unpacked`, "small.js");
+ const identity = await lstat(unpackedPath);
+ const ioError = Object.assign(new Error("device stat failed"), {
+ code: "EIO",
+ errno: -5,
+ syscall: "fstat",
+ });
+ let closeCount = 0;
+ const reader = new AsarArtifactReader(archive, async (path, flags) => {
+ const handle = await openFile(path, flags);
+ expect(await matchingDescriptorCount(identity)).toBeGreaterThan(0);
+ let statCount = 0;
+ return {
+ async stat() {
+ statCount += 1;
+ if (statCount === 2) throw ioError;
+ return handle.stat();
+ },
+ async close() {
+ closeCount += 1;
+ await handle.close();
+ },
+ createReadStream: (options) => handle.createReadStream(options),
+ };
+ });
+
+ try {
+ const entries = [];
+ for await (const entry of reader.entries()) entries.push(entry);
+ const entry = entries.find(({ path }) => path === "small.js");
+ if (entry === undefined)
+ throw new Error("Expected unpacked ASAR member");
+
+ await expect(reader.open(entry)).rejects.toMatchObject({
+ name: "ArtifactReaderFailure",
+ reason: "io",
+ message: expect.stringContaining(
+ `Could not read ${entry.path} ASAR at ${archive}: device stat failed`,
+ ),
+ cause: { code: "EIO", errno: -5, syscall: "fstat" },
+ });
+ expect(closeCount).toBe(1);
+ await waitForNoMatchingDescriptor(identity);
+ } finally {
+ await reader.close();
+ }
+ },
+ );
+
+ it.each(["missing", "replaced"] as const)(
+ "validates the container before returning a zero-length member when it is %s",
+ async (change) => {
+ const root = await createTestTempDirectory("rea-asar-empty-member-");
+ const source = join(root, "source");
+ const archive = join(root, "fixture.asar");
+ await mkdir(source);
+ await writeFile(join(source, "empty.js"), "");
+ await createPackageWithOptions(source, archive, {});
+ const reader = new AsarArtifactReader(archive);
+
+ try {
+ const entries = [];
+ for await (const entry of reader.entries()) entries.push(entry);
+ const entry = entries.find(({ path }) => path === "empty.js");
+ if (entry === undefined) throw new Error("Expected empty ASAR member");
+ if (change === "missing") await rm(archive);
+ else await writeFile(archive, "replacement container");
+
+ await expect(reader.open(entry)).rejects.toMatchObject(
+ change === "missing"
+ ? { reason: "io", cause: { code: "ENOENT" } }
+ : { reason: "integrity" },
+ );
+ } finally {
+ await reader.close();
+ }
+ },
+ );
+
+ it("preserves filesystem errors raised while consuming a member stream", async () => {
+ const ioError = Object.assign(new Error("device read failed"), {
+ code: "EIO",
+ errno: -5,
+ syscall: "read",
+ });
+ const source = Readable.from(
+ (async function* () {
+ yield Buffer.from("partial");
+ throw ioError;
+ })(),
+ );
+ const output = readValidatedAsarEntry(
+ source,
+ undefined,
+ "nested/member.bin",
+ "/tmp/source.asar",
+ );
+
+ await expect(async () => {
+ for await (const _chunk of output) {
+ // Consume through the source failure.
+ }
+ }).rejects.toMatchObject({
+ name: "ArtifactReaderFailure",
+ reason: "io",
+ message: expect.stringContaining(
+ "Could not read nested/member.bin ASAR at /tmp/source.asar",
+ ),
+ cause: { code: "EIO", errno: -5, syscall: "read" },
+ });
+ });
+});
+
+describe("ASAR entry streaming", () => {
+ it("reports the observed digest when an unpacked member changes size", async () => {
+ const root = await createTestTempDirectory(
+ "rea-asar-unpacked-size-change-",
+ );
+ const source = join(root, "source");
+ const archive = join(root, "fixture.asar");
+ const original = join(source, "small.js");
+ const changed = "changed();\n";
+ await mkdir(source);
+ await writeFile(original, "module.exports = 1;\n");
+ await createPackageWithOptions(source, archive, { unpack: "small.js" });
+ await writeFile(join(`${archive}.unpacked`, "small.js"), changed);
+
+ await expect(scanArtifactInventory(archive)).rejects.toMatchObject({
+ reason: "integrity",
+ details: {
+ logicalPath: "small.js",
+ calculatedSha256: createHash("sha256").update(changed).digest("hex"),
+ unpacked: true,
+ },
+ });
+ });
+
+ it.each([
+ ["packed", {}],
+ ["unpacked", { unpack: "large.bin" }],
+ ] as const)(
+ "opens a %s member without allocating its full contents",
+ async (_kind, options) => {
+ const root = await createTestTempDirectory("rea-asar-streaming-");
+ const source = join(root, "source");
+ const archive = join(root, "fixture.asar");
+ const member = join(source, "large.bin");
+ await mkdir(source);
+ await writeFile(member, Buffer.alloc(0));
+ await truncate(member, memberBytes);
+ await createPackageWithOptions(source, archive, options);
+
+ const reader = new AsarArtifactReader(archive);
+ try {
+ const entries = [];
+ for await (const entry of reader.entries()) entries.push(entry);
+ const entry = entries.find(({ path }) => path === "large.bin");
+ if (entry === undefined) throw new Error("Expected large ASAR member");
+
+ const before = process.memoryUsage().arrayBuffers;
+ const stream = await reader.open(entry);
+ const afterOpen = process.memoryUsage().arrayBuffers;
+ const observed = await hashReadable(stream);
+ const allocation = afterOpen - before;
+
+ expect(allocation).toBeLessThan(memberBytes / 2);
+ expect(observed).toMatchObject({
+ sha256: expectedSha256(),
+ bytes: memberBytes,
+ });
+ } finally {
+ await reader.close();
+ }
+ },
+ 120_000,
+ );
+});
diff --git a/tests/boundary/filesystem/javascriptArtifactContentIdentity.test.ts b/tests/boundary/filesystem/javascriptArtifactContentIdentity.test.ts
index 74fb9ab22..da79929f7 100644
--- a/tests/boundary/filesystem/javascriptArtifactContentIdentity.test.ts
+++ b/tests/boundary/filesystem/javascriptArtifactContentIdentity.test.ts
@@ -1,4 +1,4 @@
-import { mkdir, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { createPackage } from "@electron/asar";
@@ -86,6 +86,24 @@ describe("JavaScript artifact ingestion content identities", () => {
}
});
+ it("rejects a same-size ASAR replacement against the inventoried root digest", async () => {
+ const { source, archive } = await fixture();
+ const snapshot = await scanArtifactInventory(archive);
+ const original = await lstat(archive);
+ await writeFile(join(source, "main.js"), "module.exports = 43;\n");
+ await createPackage(source, archive);
+ expect((await lstat(archive)).size).toBe(original.size);
+
+ const reader = new AsarArtifactReader(archive);
+ try {
+ await expect(
+ readJavaScriptArtifactFiles(reader, snapshot),
+ ).rejects.toMatchObject({ reason: "integrity" });
+ } finally {
+ await reader.close();
+ }
+ });
+
it("preserves typed cancellation when the direct ASAR filesystem stream aborts", async () => {
const { archive } = await fixture();
const snapshot = await scanArtifactInventory(archive);