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 `.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(); constructor( private readonly path: string, private readonly openUnpackedFile: OpenAsarUnpackedFile = open, ) {} async *entries(signal?: AbortSignal): AsyncIterable { 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; 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 { 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 { uncache(this.path); this.#resetArchiveState(); this.#entries.clear(); return Promise.resolve(); } provenance(): readonly [] { return []; } async #openUnpackedEntry(entry: ArtifactEntry): Promise { 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, { size: number }>; type AsarEntryState = { readonly metadata: AsarFileMetadata; readonly entry: ArtifactEntry; }; type UnpackedFileHandle = { stat(): Promise; close(): Promise; createReadStream: FileHandle["createReadStream"]; }; type OpenAsarUnpackedFile = ( path: string, flags: number, ) => Promise; 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, ): 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";