reverseport 0.0.0-stage → 1.2.0

package/dist/artifacts/ArtifactResourceScope.js

@@ -0,0 +1,103 @@
+import { ArtifactReaderFailure } from "./ArtifactReader.js";
+/** Caller-owned scope that retains failed artifact cleanup for a later close. */
+export class ArtifactResourceScope {
+    #pending = new Set();
+    #active = new Set();
+    #draining;
+    #closed = false;
+    /** Admit a resource operation while the scope remains open. */
+    async run(operation) {
+        while (true) {
+            if (this.#closed)
+                throw new ArtifactReaderFailure("unavailable", "Artifact resource scope is closed");
+            if (this.#draining !== undefined)
+                await this.#draining;
+            if (this.#closed)
+                throw new ArtifactReaderFailure("unavailable", "Artifact resource scope is closed");
+            if (this.#pending.size > 0) {
+                await this.retryCleanup();
+                continue;
+            }
+            const running = Promise.resolve().then(operation);
+            this.#active.add(running);
+            try {
+                return await running;
+            }
+            finally {
+                this.#active.delete(running);
+            }
+        }
+    }
+    /** Attempt cleanup now and retain the same owner if it fails. */
+    async release(owner) {
+        try {
+            await cleanup(owner);
+            this.#pending.delete(owner);
+            return { kind: "released" };
+        }
+        catch (cause) {
+            this.#pending.add(owner);
+            return { kind: "failed", cause };
+        }
+    }
+    /** Retry retained owners without closing resource admission. */
+    retryCleanup() {
+        if (this.#draining !== undefined)
+            return this.#draining;
+        this.#draining = this.#drainAndRetry().finally(() => {
+            this.#draining = undefined;
+        });
+        return this.#draining;
+    }
+    /** Stop admission, wait for active operations, and retry every retained owner. */
+    close() {
+        this.#closed = true;
+        return this.retryCleanup();
+    }
+    async #drainAndRetry() {
+        while (this.#active.size > 0)
+            await Promise.allSettled(this.#active);
+        const failures = [];
+        for (const owner of this.#pending) {
+            try {
+                await cleanup(owner);
+                this.#pending.delete(owner);
+            }
+            catch (cause) {
+                failures.push({ owner, cause });
+            }
+        }
+        if (failures.length === 0)
+            return;
+        const observations = failures.map(({ owner, cause }) => ArtifactReaderFailure.cleanupObservation(cause, owner.resource));
+        const resources = [
+            ...new Set(observations.flatMap(({ resources }) => resources)),
+        ];
+        throw new ArtifactReaderFailure("unavailable", `Artifact cleanup remains incomplete: ${resources.join(", ")}`, {
+            cause: new AggregateError(failures.map(({ cause }) => cause), "One or more artifact resources remain owned"),
+            cleanup: {
+                reason: observations.map(({ reason }) => reason).join("; "),
+                resources,
+            },
+        });
+    }
+}
+const cleanup = async (owner) => {
+    switch (owner.kind) {
+        case "javascript-source-analysis":
+            await owner.analysis.close();
+            return;
+        case "reader":
+            await owner.reader.close();
+            return;
+        case "file-handle":
+        case "directory-handle":
+            await owner.handle.close();
+            return;
+        case "output-tree":
+            await owner.tree.rollback();
+            return;
+        case "staged-output":
+            await owner.output.close();
+    }
+};

package/dist/artifacts/AsarArtifactReader.js

@@ -0,0 +1,518 @@
+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 { 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";
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.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 {
+    path;
+    options;
+    format = "asar";
+    #archiveSize;
+    #headerSize;
+    #entries = new Map();
+    #ownedHandles = new Map();
+    #snapshot;
+    #snapshotRoot;
+    #snapshotOperation = Promise.resolve();
+    constructor(path, options = {}) {
+        this.path = path;
+        this.options = options;
+    }
+    async *entries(signal) {
+        let paths;
+        try {
+            await this.prepareContainer(undefined, signal);
+            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 = orderAsarListing(listPackage(snapshotPath, { isPack: false }));
+                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, path } of paths) {
+            abortIfNeeded(signal);
+            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
+                ? "directory"
+                : "link" in metadata
+                    ? "symlink"
+                    : "file";
+            const entry = {
+                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 #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")
+            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}`);
+        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
+            ? 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}`);
+        const snapshotPath = this.#snapshotPath();
+        let handle;
+        try {
+            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) {
+                handle = undefined;
+                await closeAsarHandle(() => this.#closeOwnedHandle(openedHandle), signal);
+                return Readable.from([]);
+            }
+            const source = this.#ownedReadStream(openedHandle, {
+                start,
+                end: start + metadata.size - 1,
+                signal,
+            });
+            handle = undefined;
+            const output = readValidatedAsarEntry(source, metadata.size, producedEntry.path, this.path, signal);
+            this.#setOwnedOutput(openedHandle, output);
+            return output;
+        }
+        catch (cause) {
+            const failure = asarFailure(this.path, `read ${producedEntry.path}`, cause);
+            if (handle !== undefined) {
+                try {
+                    await this.#closeOwnedHandle(handle);
+                }
+                catch (cleanupCause) {
+                    throw ArtifactReaderFailure.withCleanup(failure, ArtifactReaderFailure.cleanupObservation(cleanupCause, snapshotPath));
+                }
+            }
+            throw failure;
+        }
+    }
+    /** 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 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.options.removeSnapshot ?? defaultRemoveSnapshot)(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 #openUnpackedStream(entry, signal) {
+        const unpackedRoot = `${this.path}.unpacked`;
+        let handle;
+        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}`);
+            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) {
+                throw new ArtifactReaderFailure("integrity", `ASAR unpacked entry changed before read: ${entry.path}`, {}, {
+                    logicalPath: entry.path,
+                    declaredSha256: entry.declaredSha256,
+                    calculatedSha256: null,
+                    unpacked: true,
+                });
+            }
+            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) {
+            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 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) => "size" in metadata &&
+    typeof metadata.size === "number" &&
+    !("files" in metadata) &&
+    !("link" in metadata);
+const parseArchiveOffset = (value) => {
+    if (!/^(?:0|[1-9][0-9]*)$/u.test(value))
+        return undefined;
+    const offset = Number(value);
+    return Number.isSafeInteger(offset) ? offset : undefined;
+};
+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);
+        });
+    });
+};
+/**
+ * Pair each host-spelled listing with its portable archive path, ordered by
+ * the portable path so Windows and POSIX hosts agree.
+ *
+ * @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.
+ */
+export const orderAsarListing = (listed, separator = sep) => listed
+    .map((entry) => ({ listed: entry, path: toArtifactPath(entry, separator) }))
+    .sort((left, right) => compareUnicodeCodePoints(left.path, right.path));
+const toArtifactPath = (listed, separator) => {
+    const portable = separator === "\\" ? listed.replaceAll("\\", "/") : listed;
+    return portable.replace(/^\/+|\/+$/gu, "");
+};
+const asarFailure = (path, operation, cause) => {
+    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) => cause instanceof Error &&
+    "errno" in cause &&
+    typeof cause.errno === "number" &&
+    "syscall" in cause &&
+    typeof cause.syscall === "string";
+const isMissingFile = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT";