rea-agents 4.1.0 → 5.0.0

package/dist/application/{NativeValueTrace.js → native/NativeValueTrace.js}

@@ -1,9 +1,9 @@
-import { functionDossierSchema } from "../domain/hopperValues.js";
-import { nativeCallTargetsSchema } from "../domain/nativeInstruction.js";
-import { nativeValueTraceInputSchema, nativeValueTraceSchema, } from "../domain/nativeValueTrace.js";
-import { createEvidence } from "../domain/evidence.js";
-import { AnalysisCancelledError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
-import { err, ok } from "../domain/result.js";
+import { functionDossierSchema } from "../../domain/hopperValues.js";
+import { nativeCallTargetsSchema } from "../../domain/native/nativeInstruction.js";
+import { nativeValueTraceInputSchema, nativeValueTraceSchema, } from "../../domain/native/nativeValueTrace.js";
+import { createEvidence } from "../../domain/evidence.js";
+import { AnalysisCancelledError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { err, ok } from "../../domain/result.js";
 /** Compose bounded high-p-code def-use graphs across exactly referenced call destinations. */
 export const traceNativeValues = async (analysis, parameters, signal) => {
     const input = nativeValueTraceInputSchema.parse(parameters);

package/dist/{application/ArtifactInventory/hash.js → artifacts/ArtifactHash.js}

@@ -1,12 +1,14 @@
 import { createHash } from "node:crypto";
-import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
-import { streamChunkToBuffer } from "../../artifacts/StreamBytes.js";
+import { ArtifactReaderFailure } from "./ArtifactReader.js";
+import { streamChunkToBuffer } from "./StreamBytes.js";
 /** Bounded classification evidence; this is not an executable format size limit. */
 export const ARTIFACT_CLASSIFICATION_PREFIX_BYTES = 8_192;
+/** Preserve the inventory cancellation reason at a stream boundary. */
 export const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
         throw new ArtifactReaderFailure("cancelled", "Artifact inventory cancelled");
 };
+/** Hash every stream byte and retain its bounded classification prefix. */
 export const hashReadable = async (stream, signal) => {
     const hash = createHash("sha256");
     const prefixes = [];

package/dist/artifacts/ArtifactPaths.js

@@ -7,13 +7,13 @@ export const normalizeArtifactPath = (input) => {
         input.includes("\\") ||
         input.startsWith("/") ||
         DRIVE_OR_UNC.test(input))
-        throw new ArtifactReaderFailure("path", "Artifact path is absolute or unsafe");
+        throw new ArtifactReaderFailure("path", `Artifact path is absolute or unsafe: ${JSON.stringify(input)}`);
     const normalized = input.normalize("NFC").replace(/\/+$/u, "");
     const parts = normalized.split("/");
     if (normalized.length === 0 ||
         parts.some((part) => part === "" || part === "." || part === "..") ||
         posix.normalize(normalized) !== normalized)
-        throw new ArtifactReaderFailure("path", "Artifact path is not normalized");
+        throw new ArtifactReaderFailure("path", `Artifact path is not normalized: ${JSON.stringify(input)}`);
     return normalized;
 };
 /** Reject exact, Unicode-normalized, case-folded, and prefix collisions. */
@@ -28,7 +28,7 @@ export class ArtifactPathRegistry {
             const foldedPart = part.toLocaleLowerCase("en-US");
             let child = node.children.get(foldedPart);
             if (child !== undefined && child.spelling !== part)
-                throw new ArtifactReaderFailure("path", `Artifact path collision: ${path}`);
+                throw new ArtifactReaderFailure("path", `Artifact path collision: ${path} differs only in case from ${[...parts.slice(0, index), child.spelling].join("/")}`);
             if (child === undefined) {
                 child = { spelling: part, kind: undefined, children: new Map() };
                 node.children.set(foldedPart, child);

package/dist/artifacts/ArtifactProvider.js

@@ -1,56 +1,26 @@
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { inspectBundleKeyedArchive } from "./KeyedArchiveReader.js";
+import { inspectBundleKeyedArchive } from "./apple/KeyedArchiveReader.js";
 import { basename, dirname } from "node:path";
 import { inventoryArtifact } from "../application/ArtifactInventory.js";
 import { extractArtifact } from "../application/ArtifactExtraction.js";
-import { analyzeInterfaceBuilderBundle } from "../application/InterfaceBuilderAnalysis.js";
-import { analyzeAppleAssetCatalogs } from "../application/AppleAssetCatalogAnalysis.js";
+import { analyzeInterfaceBuilderBundle } from "./apple/InterfaceBuilderAnalysis.js";
+import { analyzeAppleAssetCatalogs } from "./apple/AppleAssetCatalogAnalysis.js";
 import { ARTIFACT_ANALYSIS_OPERATIONS, artifactInventoryInputSchema, artifactExtractionExecutionSchema, } from "../contracts/artifactToolContracts.js";
 import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
 import { ArtifactOperationError } from "../domain/artifactOperationError.js";
 import {} from "../domain/analysisErrorBase.js";
-import { interfaceBuilderLimitsSchema } from "../domain/interfaceBuilderGraph.js";
+import { interfaceBuilderLimitsSchema } from "../domain/apple/interfaceBuilderGraph.js";
 import { err, ok } from "../domain/result.js";
 import { ArtifactReaderFailure } from "./ArtifactReader.js";
-import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";
+import { ARTIFACT_PROVIDER_IDENTITY as IDENTITY, artifactCapabilities, } from "./ArtifactProviderMetadata.js";
 import { createEvidence } from "../domain/evidence.js";
 import { createArtifactInspection } from "../domain/artifactInspection.js";
 import { resolveArtifactIntegrityPolicy } from "../application/ArtifactInventory/policy.js";
-const IDENTITY = Object.freeze(ARTIFACT_GRAPH_PROVIDER);
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
     #capabilities;
     constructor(platform = process.platform) {
-        this.#capabilities = Object.freeze(ARTIFACT_ANALYSIS_OPERATIONS.map((operation) => {
-            const common = {
-                provider: IDENTITY,
-                operation,
-                effects: Object.freeze({
-                    mutatesArtifact: false,
-                    launchesProcess: operation !== "decode_interface_builder" &&
-                        operation !== "inspect_keyed_archive",
-                    mayShowUi: false,
-                    mayAccessNetwork: false,
-                    mayWriteFilesystem: operation === "extract_artifact" ||
-                        operation === "inspect_artifact" ||
-                        operation === "inventory_artifact",
-                    changesPermissions: false,
-                    requiresRoot: false,
-                }),
-                limitations: Object.freeze([
-                    "DMG child inventory automatically uses a read-only native macOS mount; PKG remains root-hash-only.",
-                    "ASAR files discovered in filesystem-backed inventories are expanded without bulk extraction; other nested containers remain recorded only.",
-                ]),
-            };
-            return Object.freeze(operation === "inspect_asset_catalog" && platform !== "darwin"
-                ? {
-                    ...common,
-                    available: false,
-                    availabilityCode: "unsupported_host",
-                    reason: "Apple asset catalogs require macOS assetutil.",
-                }
-                : { ...common, available: true, reason: null });
-        }));
+        this.#capabilities = artifactCapabilities(platform);
     }
     identity() {
         return IDENTITY;
@@ -235,7 +205,7 @@ class ArtifactClient {
 const isArtifactOperation = (operation) => ARTIFACT_ANALYSIS_OPERATIONS.includes(operation);
 const translateFailure = (operation, cause) => {
     if (cause instanceof ArtifactReaderFailure)
-        return new ArtifactOperationError(operation, cause.reason, cause.details);
+        return new ArtifactOperationError(operation, cause.reason, cause.details, cause.message);
     return new ArtifactOperationError(operation, "io");
 };
 const subjectFor = (path, manifest) => ({

package/dist/artifacts/ArtifactProviderMetadata.js

@@ -0,0 +1,36 @@
+import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";
+import { ARTIFACT_ANALYSIS_OPERATIONS } from "../contracts/artifactToolContracts.js";
+/** Identity of artifact inventory and owned extraction observations. */
+export const ARTIFACT_PROVIDER_IDENTITY = Object.freeze(ARTIFACT_GRAPH_PROVIDER);
+const IDENTITY = ARTIFACT_PROVIDER_IDENTITY;
+/** Declare artifact coverage without constructing readers or acquiring resources. */
+export const artifactCapabilities = (platform = process.platform) => Object.freeze(ARTIFACT_ANALYSIS_OPERATIONS.map((operation) => {
+    const common = {
+        provider: IDENTITY,
+        operation,
+        effects: Object.freeze({
+            mutatesArtifact: false,
+            launchesProcess: operation !== "decode_interface_builder" &&
+                operation !== "inspect_keyed_archive",
+            mayShowUi: false,
+            mayAccessNetwork: false,
+            mayWriteFilesystem: operation === "extract_artifact" ||
+                operation === "inspect_artifact" ||
+                operation === "inventory_artifact",
+            changesPermissions: false,
+            requiresRoot: false,
+        }),
+        limitations: Object.freeze([
+            "DMG child inventory automatically uses a read-only native macOS mount; PKG remains root-hash-only.",
+            "ASAR files discovered in filesystem-backed inventories are expanded without bulk extraction; other nested containers remain recorded only.",
+        ]),
+    };
+    return Object.freeze(operation === "inspect_asset_catalog" && platform !== "darwin"
+        ? {
+            ...common,
+            available: false,
+            availabilityCode: "unsupported_host",
+            reason: "Apple asset catalogs require macOS assetutil.",
+        }
+        : { ...common, available: true, reason: null });
+}));

package/dist/artifacts/AsarArtifactReader.js

@@ -1,9 +1,12 @@
-import { sep } from "node:path";
+import { constants, createReadStream } from "node:fs";
+import { lstat, open, realpath } 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, } 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
@@ -11,16 +14,28 @@ import { ArtifactReaderFailure, } from "./ArtifactReader.js";
  */
 export class AsarArtifactReader {
     path;
+    openUnpackedFile;
     format = "asar";
-    constructor(path) {
+    #archiveSize;
+    #headerSize;
+    #entries = new Map();
+    constructor(path, openUnpackedFile = open) {
         this.path = path;
+        this.openUnpackedFile = openUnpackedFile;
     }
     async *entries(signal) {
         let paths;
         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) {
             throw asarFailure(this.path, "inventory", cause);
@@ -49,7 +64,7 @@ export class AsarArtifactReader {
                 : "link" in metadata
                     ? "symlink"
                     : "file";
-            yield {
+            const entry = {
                 path,
                 kind,
                 declaredSize: "size" in metadata ? metadata.size : null,
@@ -65,39 +80,187 @@ export class AsarArtifactReader {
                 unpacked: "unpacked" in metadata && metadata.unpacked === true,
                 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, signal) {
+    async open(entry, signal) {
         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) {
+                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;
         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);
+            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) {
-            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,
-                }));
-            return Promise.reject(asarFailure(this.path, `read ${entry.path}`, cause));
+            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) {
+        abortIfNeeded(signal);
+        return createReadStream(this.path, signal === undefined ? {} : { signal });
+    }
     close() {
         uncache(this.path);
+        this.#resetArchiveState();
+        this.#entries.clear();
         return Promise.resolve();
     }
     provenance() {
         return [];
     }
+    async #openUnpackedEntry(entry) {
+        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) => {
+                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) {
+            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() {
+        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 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");
@@ -106,9 +269,18 @@ const toArtifactPath = (listed) => {
     const portable = sep === "\\" ? listed.replaceAll("\\", "/") : listed;
     return portable.replace(/^\/+|\/+$/gu, "");
 };
-const asarFailure = (path, operation, cause) => cause instanceof ArtifactReaderFailure
-    ? cause
-    : new ArtifactReaderFailure("format", `Malformed or unreadable ASAR during ${operation}: ${path}`, { cause });
+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 &&

package/dist/artifacts/AsarEntryStream.js

@@ -0,0 +1,76 @@
+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, signal) => {
+    await close();
+    abortIfNeeded(signal);
+};
+/** Validate and contextualize bytes read from one ASAR member source. */
+export const readValidatedAsarEntry = (source, expectedBytes, entryPath, archivePath, signal) => {
+    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 = 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) {
+            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 = () => {
+        signal?.removeEventListener("abort", onAbort);
+        if (!source.destroyed)
+            source.destroy();
+    };
+    const onAbort = () => {
+        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) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
+};
+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";

package/dist/artifacts/DirectoryArtifactReader.js

@@ -6,35 +6,46 @@ import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 export class DirectoryArtifactReader {
     format = "directory";
     #rootPromise;
+    #rootPath;
     constructor(root) {
+        this.#rootPath = root;
         this.#rootPromise = realpath(root);
     }
     async *entries(signal) {
-        const root = await this.#rootPromise;
+        const root = await this.#rootPromise.catch((cause) => {
+            throw directoryIoFailure("resolve artifact root", this.#rootPath, cause);
+        });
         const pending = [root];
         while (pending.length > 0) {
             abortIfNeeded(signal);
             const directory = pending.pop();
             if (directory === undefined)
                 break;
-            await assertContainedDirectory(root, directory);
+            await withDirectoryIoContext("inspect directory", directory, () => assertContainedDirectory(root, directory));
             const children = [];
-            const handle = await opendir(directory);
+            const handle = await opendir(directory).catch((cause) => {
+                throw directoryIoFailure("open directory", directory, cause);
+            });
             try {
                 for await (const child of handle)
                     children.push(child.name);
             }
+            catch (cause) {
+                throw directoryIoFailure("read directory", directory, cause);
+            }
             finally {
                 // best-effort cleanup: directory-handle close must not mask traversal.
                 await handle.close().catch(() => undefined);
             }
-            await assertContainedDirectory(root, directory);
+            await withDirectoryIoContext("inspect directory", directory, () => assertContainedDirectory(root, directory));
             children.sort((left, right) => left.localeCompare(right, "en"));
             const directories = [];
             for (const name of children) {
                 abortIfNeeded(signal);
                 const absolute = join(directory, name);
-                const metadata = await lstat(absolute);
+                const metadata = await lstat(absolute).catch((cause) => {
+                    throw directoryIoFailure("inspect entry", absolute, cause);
+                });
                 const path = relative(root, absolute).split(sep).join("/");
                 const kind = metadata.isSymbolicLink()
                     ? "symlink"
@@ -74,9 +85,13 @@ export class DirectoryArtifactReader {
         abortIfNeeded(signal);
         if (entry.kind !== "file")
             throw new ArtifactReaderFailure("format", "Only regular files can be opened");
-        const handle = await open(entry.adapterKey, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const handle = await open(entry.adapterKey, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch((cause) => {
+            throw directoryIoFailure("open entry", entry.adapterKey, cause);
+        });
         try {
-            const observed = await handle.stat();
+            const observed = await handle.stat().catch((cause) => {
+                throw directoryIoFailure("inspect opened entry", entry.adapterKey, cause);
+            });
             if (!observed.isFile() ||
                 entry.sourceIdentity === undefined ||
                 observed.dev !== entry.sourceIdentity.device ||
@@ -98,6 +113,25 @@ export class DirectoryArtifactReader {
         return [];
     }
 }
+const directoryIoFailure = (operation, path, cause) => {
+    if (cause instanceof ArtifactReaderFailure)
+        return cause;
+    const code = typeof cause === "object" &&
+        cause !== null &&
+        "code" in cause &&
+        typeof cause.code === "string"
+        ? ` (${cause.code})`
+        : "";
+    return new ArtifactReaderFailure("io", `Could not ${operation} at ${path}${code}`, { cause });
+};
+const withDirectoryIoContext = async (operation, path, action) => {
+    try {
+        return await action();
+    }
+    catch (cause) {
+        throw directoryIoFailure(operation, path, cause);
+    }
+};
 const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
         throw new ArtifactReaderFailure("cancelled", "Artifact traversal cancelled");