* fix(artifacts): stream ASAR members without full buffering * fix(artifacts): close unopened ASAR member streams * fix(artifacts): preserve unpacked ASAR mismatch digests * fix(artifacts): preserve ASAR read failures * fix(artifacts): retain unpacked ASAR stat failures * fix(artifacts): validate ASAR entry producer identity
412 lines
13 KiB
TypeScript
412 lines
13 KiB
TypeScript
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 { 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 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
|
|
* hash those companion bytes against the archive's declared integrity value.
|
|
*/
|
|
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,
|
|
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);
|
|
}
|
|
for (const listed 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: ReturnType<typeof statFile>;
|
|
try {
|
|
metadata = statFile(this.path, providerPath, false);
|
|
} catch (cause: unknown) {
|
|
throw asarFailure(this.path, `stat ${path}`, cause);
|
|
}
|
|
const kind =
|
|
"files" in metadata
|
|
? "directory"
|
|
: "link" in metadata
|
|
? "symlink"
|
|
: "file";
|
|
const entry: ArtifactEntry = {
|
|
path,
|
|
kind,
|
|
declaredSize: "size" in metadata ? metadata.size : null,
|
|
compressedSize: null,
|
|
executable: "executable" in metadata && metadata.executable,
|
|
encrypted: false,
|
|
byteOffset: null,
|
|
declaredSha256:
|
|
"integrity" in metadata &&
|
|
metadata.integrity.algorithm === "SHA256" &&
|
|
/^[a-f0-9]{64}$/u.test(metadata.integrity.hash)
|
|
? metadata.integrity.hash
|
|
: null,
|
|
unpacked: "unpacked" in metadata && metadata.unpacked === true,
|
|
limitations:
|
|
kind === "symlink"
|
|
? ["ASAR symlink target was not followed or disclosed."]
|
|
: [],
|
|
adapterKey: providerPath,
|
|
};
|
|
if (kind === "file" && isAsarFileMetadata(metadata))
|
|
this.#entries.set(providerPath, {
|
|
metadata,
|
|
entry: copyArtifactEntry(entry),
|
|
});
|
|
yield entry;
|
|
}
|
|
}
|
|
|
|
async open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable> {
|
|
abortIfNeeded(signal);
|
|
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 {
|
|
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: unknown) {
|
|
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?: AbortSignal): Readable {
|
|
abortIfNeeded(signal);
|
|
return createReadStream(this.path, signal === undefined ? {} : { signal });
|
|
}
|
|
|
|
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");
|
|
};
|
|
|
|
const toArtifactPath = (listed: string): string => {
|
|
const portable = sep === "\\" ? listed.replaceAll("\\", "/") : listed;
|
|
return portable.replace(/^\/+|\/+$/gu, "");
|
|
};
|
|
|
|
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";
|
|
|
|
const isMissingFile = (cause: unknown): boolean =>
|
|
typeof cause === "object" &&
|
|
cause !== null &&
|
|
"code" in cause &&
|
|
cause.code === "ENOENT";
|