rea-agents 6.4.0 → 6.7.0

package/dist/electron/ElectronFusePath.js

@@ -0,0 +1,248 @@
+import { assertArtifactReadActive } from "../artifacts/ArtifactFileOperation.js";
+import { lstat, readlink } from "node:fs/promises";
+import { basename, dirname, isAbsolute, sep } from "node:path";
+import { isPathWithinRoot } from "../domain/localPath.js";
+const FRAMEWORK_NAME = "Electron Framework.framework";
+const BINARY_NAME = "Electron Framework";
+const MAX_SYMLINK_HOPS = 32;
+/** A selected path is not an admitted Electron bundle or regular file. */
+export class ElectronFusePathFailure extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "ElectronFusePathFailure";
+    }
+}
+/**
+ * Admit a regular executable, a macOS app bundle, or an Electron Framework
+ * binary reached through `Versions/Current` without leaving the framework.
+ */
+export const resolveElectronFuseTarget = async (selectedPath, signal) => {
+    assertArtifactReadActive(signal);
+    const metadata = await lstat(selectedPath, { bigint: true });
+    let file;
+    if (metadata.isSymbolicLink())
+        file = await resolveFrameworkSymlink(selectedPath, signal);
+    else if (metadata.isFile())
+        file =
+            frameworkRootOf(selectedPath) === null
+                ? { path: selectedPath, metadata, nodes: [] }
+                : await resolveFrameworkSymlink(selectedPath, signal);
+    else if (metadata.isDirectory()) {
+        file = await resolveBundleBinary(selectedPath, signal);
+        file = {
+            ...file,
+            nodes: [{ path: selectedPath, metadata }, ...file.nodes],
+        };
+    }
+    else
+        throw new ElectronFusePathFailure("invalid_format", `Expected a regular file or Electron app bundle: ${selectedPath}`);
+    return { selectedPath, file };
+};
+const resolveFrameworkSymlink = async (selectedPath, signal) => {
+    const root = frameworkRootOf(selectedPath);
+    if (root === null)
+        throw new ElectronFusePathFailure("invalid_format", `Expected a regular file without a symlink: ${selectedPath}`);
+    const nodes = await requireFrameworkRoot(root, selectedPath);
+    const relativePath = relativeInside(root, selectedPath);
+    if (relativePath === null)
+        throw new ElectronFusePathFailure("invalid_value", `Framework symlink escapes ${FRAMEWORK_NAME}: ${selectedPath}`);
+    return requireFile(await resolveInside(root, relativePath, signal), selectedPath, nodes);
+};
+const resolveBundleBinary = async (selectedPath, signal) => {
+    const directory = await resolveDirectorySuffix(selectedPath, signal);
+    const name = basename(directory.path);
+    let file;
+    if (name === FRAMEWORK_NAME)
+        file = await resolveKnownBinary(directory.path, selectedPath, signal);
+    else if (name.endsWith(".app"))
+        file = await resolveKnownBinary(appendPath(directory.path, "Contents", "Frameworks", FRAMEWORK_NAME), selectedPath, signal);
+    else
+        throw new ElectronFusePathFailure("invalid_format", `Expected an Electron .app bundle, ${FRAMEWORK_NAME} directory, or executable file: ${selectedPath}`);
+    return { ...file, nodes: [...directory.nodes, ...file.nodes] };
+};
+/** Reduce directory suffixes only when doing so preserves filesystem selection. */
+const resolveDirectorySuffix = async (selectedPath, signal) => {
+    let path = selectedPath;
+    const pending = [];
+    const nodes = [];
+    while (true) {
+        assertArtifactReadActive(signal);
+        const name = basename(path);
+        // lstat("link/") follows a link; inspect the named component itself.
+        if (name !== "")
+            while (path.endsWith(sep))
+                path = path.slice(0, -1);
+        if (name === "." || name === "..") {
+            pending.push(name);
+            path = dirname(path);
+            continue;
+        }
+        const component = pending.pop();
+        if (component === undefined)
+            return { path, nodes };
+        if (component === ".")
+            continue;
+        const metadata = await lstat(path, { bigint: true });
+        if (!metadata.isDirectory() || metadata.isSymbolicLink())
+            throw new ElectronFusePathFailure("invalid_value", `A bundle path ending in '..' requires a real directory before each parent segment: ${selectedPath}`);
+        nodes.push({ path, metadata });
+        path = dirname(path);
+    }
+};
+/** `root` is the framework directory for both an `.app` and a framework selection. */
+const resolveKnownBinary = async (root, bundle, signal) => {
+    const nodes = await requireFrameworkRoot(root, bundle);
+    for (const candidate of [
+        BINARY_NAME,
+        `Versions/Current/${BINARY_NAME}`,
+        `Versions/A/${BINARY_NAME}`,
+    ]) {
+        const selected = await resolveInside(root, candidate, signal);
+        if (selected.kind === "file")
+            return requireFile(selected, bundle, nodes);
+        if (selected.kind !== "absent")
+            throw pathWalkFailure(selected.kind, bundle);
+    }
+    throw new ElectronFusePathFailure("invalid_value", `Electron Framework binary was not found inside ${bundle}.`);
+};
+const resolveInside = async (root, relativePath, signal) => {
+    const pending = relativePath.split("/").filter((segment) => segment !== "");
+    const resolved = [];
+    const nodes = [];
+    let fileMetadata;
+    let hops = 0;
+    let last;
+    while (pending.length > 0) {
+        assertArtifactReadActive(signal);
+        const segment = pending.shift() ?? "";
+        if (segment === ".")
+            continue;
+        if (segment === "..") {
+            if (resolved.length === 0)
+                return { kind: "escapes" };
+            resolved.pop();
+            last = "directory";
+            continue;
+        }
+        const absolute = appendPath(root, ...resolved, segment);
+        if (!isPathWithinRoot(root, absolute))
+            return { kind: "escapes" };
+        let metadata;
+        try {
+            metadata = await lstat(absolute, { bigint: true });
+        }
+        catch (cause) {
+            if (isMissing(cause))
+                return { kind: "absent" };
+            throw cause;
+        }
+        if (metadata.isSymbolicLink()) {
+            nodes.push({ path: absolute, metadata });
+            hops += 1;
+            if (hops > MAX_SYMLINK_HOPS)
+                return { kind: "loop" };
+            const target = await readlink(absolute);
+            if (isAbsolute(target))
+                return { kind: "escapes" };
+            pending.unshift(...target.split("/").filter((part) => part !== ""));
+            continue;
+        }
+        if (metadata.isDirectory()) {
+            nodes.push({ path: absolute, metadata });
+            resolved.push(segment);
+            last = "directory";
+            continue;
+        }
+        if (!metadata.isFile() || pending.length > 0)
+            return { kind: "not-file" };
+        resolved.push(segment);
+        fileMetadata = metadata;
+        last = "file";
+    }
+    if (last !== "file" || fileMetadata === undefined)
+        return { kind: "not-file" };
+    const path = appendPath(root, ...resolved);
+    return isPathWithinRoot(root, path)
+        ? { kind: "file", path, metadata: fileMetadata, nodes }
+        : { kind: "escapes" };
+};
+/** Validate the app-parent chain equally for app, framework, and binary selection. */
+const requireFrameworkRoot = async (root, selectedPath) => {
+    const frameworks = dirname(root);
+    const contents = dirname(frameworks);
+    const app = dirname(contents);
+    if (basename(frameworks) === "Frameworks" &&
+        basename(contents) === "Contents" &&
+        basename(app).endsWith(".app"))
+        return requireRealDirectories(dirname(app), [basename(app), "Contents", "Frameworks", FRAMEWORK_NAME], selectedPath);
+    else
+        return requireRealDirectories(dirname(root), [basename(root)], selectedPath);
+};
+/**
+ * Each named directory below `anchor` must be a real directory, so the
+ * framework root cannot redirect the walk outside the selected bundle.
+ */
+const requireRealDirectories = async (anchor, segments, selectedPath) => {
+    let current = anchor;
+    const nodes = [];
+    for (const segment of segments) {
+        current = appendPath(current, segment);
+        let metadata;
+        try {
+            metadata = await lstat(current, { bigint: true });
+        }
+        catch (cause) {
+            if (isMissing(cause))
+                throw new ElectronFusePathFailure("invalid_value", `Electron Framework binary was not found inside ${selectedPath}.`);
+            throw cause;
+        }
+        nodes.push({ path: current, metadata });
+        if (metadata.isSymbolicLink())
+            throw pathWalkFailure("escapes", selectedPath);
+        if (!metadata.isDirectory())
+            throw pathWalkFailure("not-file", selectedPath);
+    }
+    return nodes;
+};
+const requireFile = (walk, selectedPath, nodes) => {
+    if (walk.kind === "file")
+        return {
+            path: walk.path,
+            metadata: walk.metadata,
+            nodes: [...nodes, ...walk.nodes],
+        };
+    if (walk.kind === "absent")
+        throw new ElectronFusePathFailure("invalid_value", `Electron Framework symlink target was not found: ${selectedPath}`);
+    throw pathWalkFailure(walk.kind, selectedPath);
+};
+const pathWalkFailure = (kind, path) => new ElectronFusePathFailure("invalid_value", kind === "escapes"
+    ? `Framework symlink escapes ${FRAMEWORK_NAME}: ${path}`
+    : kind === "loop"
+        ? `Framework symlink hop limit exceeded: ${path}`
+        : `Electron Framework path is not a regular file: ${path}`);
+const frameworkRootOf = (path) => {
+    let current = dirname(path);
+    while (basename(current) !== FRAMEWORK_NAME) {
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+    return current;
+};
+const relativeInside = (root, path) => {
+    // Keep dot segments until resolveInside has followed preceding symlinks.
+    // Lexical normalization would select a different file for link/../ paths.
+    const prefix = root.endsWith(sep) ? root : `${root}${sep}`;
+    if (!path.startsWith(prefix))
+        return null;
+    const value = path.slice(prefix.length);
+    return value === "" ? null : value.split(sep).join("/");
+};
+/** Append known components without normalizing a caller-selected parent path. */
+const appendPath = (parent, ...segments) => `${parent}${parent.endsWith(sep) ? "" : sep}${segments.join(sep)}`;
+const isMissing = (cause) => cause instanceof Error &&
+    "code" in cause &&
+    ["ENOENT", "ENOTDIR"].includes(String(cause.code));

package/dist/electron/ElectronFuseProvider.js

@@ -0,0 +1,88 @@
+import { createElectronFuseEvidence } from "../domain/electron/electronFuseEvidence.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { assertArtifactReadActive, ArtifactFileCancelled, ArtifactFileCleanupFailure, } from "../artifacts/ArtifactFileOperation.js";
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { describeElectronFuseFindings, electronFuseReportSchema, } from "../domain/electron/electronFuses.js";
+import { err, ok } from "../domain/result.js";
+import { resolveElectronFuseTarget } from "./ElectronFusePath.js";
+import { electronFuseReadLimitation, readElectronFuseImage, } from "./ElectronFuseReader.js";
+import { ELECTRON_FUSE_PROVIDER_IDENTITY, electronFuseFailure, } from "./ElectronFuseFailures.js";
+export { ELECTRON_FUSE_PROVIDER_IDENTITY };
+const OPERATION = "inspect_electron_fuses";
+/** Read packaged Electron fuse wires from one selected local file or app bundle. */
+export class ElectronFuseProvider {
+    identity = ELECTRON_FUSE_PROVIDER_IDENTITY;
+    #resources = new ArtifactResourceScope();
+    /** Retry the same failed descriptor owners, awaiting active reads first. */
+    async close() {
+        try {
+            await this.#resources.close();
+        }
+        catch (cause) {
+            throw electronFuseFailure(cause, "artifact-resources");
+        }
+    }
+    async inspect(input, options) {
+        try {
+            return await this.#resources.run(() => this.#inspectFile(input, options));
+        }
+        catch (cause) {
+            return err(electronFuseFailure(cause, input.path));
+        }
+    }
+    async #inspectFile(input, options) {
+        let resolvedPath = input.path;
+        let completed;
+        try {
+            assertArtifactReadActive(options?.signal);
+            const located = await resolveElectronFuseTarget(input.path, options?.signal);
+            assertArtifactReadActive(options?.signal);
+            resolvedPath = located.file.path;
+            const image = await readElectronFuseImage(located.file.path, {
+                resources: this.#resources,
+                selection: located.file,
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            });
+            completed = reportFor(image, located.selectedPath, resolvedPath);
+            assertArtifactReadActive(options?.signal);
+            return ok(completed);
+        }
+        catch (cause) {
+            const failure = electronFuseFailure(cause, input.path);
+            // Only this reader's completed physical outcome supplies partial fuse facts.
+            const outcome = cause instanceof ArtifactFileCleanupFailure
+                ? cause
+                    .fileCleanupFailure.outcome
+                : cause instanceof ArtifactFileCancelled
+                    ? cause
+                        .fileCancellation.outcome
+                    : undefined;
+            const report = completed ??
+                (outcome?.kind === "completed"
+                    ? reportFor(outcome.value, input.path, resolvedPath)
+                    : undefined);
+            if (report !== undefined) {
+                failure.retainPartialObservation(createElectronFuseEvidence(input, report, this.identity));
+            }
+            return err(failure);
+        }
+    }
+}
+const reportFor = (image, selectedPath, resolvedPath) => {
+    const findings = describeElectronFuseFindings(image.slices, image.format);
+    const parsed = electronFuseReportSchema.safeParse({
+        artifact: {
+            selected_path: selectedPath,
+            resolved_path: resolvedPath,
+            sha256: image.sha256,
+            bytes: image.bytes,
+            format: image.format,
+        },
+        slices: image.slices,
+        runtime_implications: findings.runtime_implications,
+        limitations: [...findings.limitations, electronFuseReadLimitation()],
+    });
+    if (!parsed.success)
+        throw new AnalysisOutputError(OPERATION, "Electron fuse reader produced a report outside its schema.", { cause: parsed.error });
+    return parsed.data;
+};

package/dist/electron/ElectronFuseReader.js

@@ -0,0 +1,333 @@
+import { readElfFixedHeader } from "../domain/elfFixedHeader.js";
+import { decodePeMachine } from "../domain/peMachine.js";
+import { createHash } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { hasMachoMagic, readMachoImage, } from "../artifacts/apple/MachoLoadCommandReader.js";
+import { electronFuseName, electronFuseState, ELECTRON_FUSE_SENTINEL, } from "../domain/electron/electronFuses.js";
+import { RegularFileChangedError, sameRegularFileState, } from "../filesystem/RegularFile.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { assertArtifactReadActive, withArtifactRegularFile, } from "../artifacts/ArtifactFileOperation.js";
+/** Admission and search bounds for one Electron executable. */
+export const ELECTRON_FUSE_LIMITS = {
+    maximumFileBytes: 1024 * 1024 * 1024,
+    chunkBytes: 256 * 1024,
+    maximumSentinelsPerSlice: 32,
+    maximumPeHeaderOffset: 1024 * 1024,
+};
+const SENTINEL = Buffer.from(ELECTRON_FUSE_SENTINEL, "ascii");
+const FAT_MAGICS = new Set([0xcafebabe, 0xcafebabf, 0xbebafeca, 0xbfbafeca]);
+/** The selected container is malformed or outside the supported formats. */
+export class ElectronFuseFormatFailure extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "ElectronFuseFormatFailure";
+    }
+}
+/** A measured bound was hit before a complete fuse report could be returned. */
+export class ElectronFuseResourceFailure extends Error {
+    boundary;
+    constructor(boundary, message) {
+        super(message);
+        this.boundary = boundary;
+        this.name = "ElectronFuseResourceFailure";
+    }
+}
+/**
+ * Hash one admitted regular file and search each slice for the fuse sentinel.
+ * The search keeps only a sentinel-sized overlap between chunks.
+ */
+export const readElectronFuseImage = async (path, options) => {
+    const signal = options?.signal;
+    assertArtifactReadActive(signal);
+    const selection = options?.selection;
+    const recheckPath = async (candidate) => {
+        assertArtifactReadActive(signal);
+        try {
+            const metadata = await lstat(candidate, { bigint: true });
+            assertArtifactReadActive(signal);
+            return metadata;
+        }
+        catch (cause) {
+            if (selection !== undefined && isMissingPath(cause))
+                throw new RegularFileChangedError(path);
+            throw cause;
+        }
+    };
+    const assertPathNodes = async () => {
+        if (selection === undefined)
+            return;
+        if (selection.path !== path)
+            throw new RegularFileChangedError(path);
+        for (const node of selection.nodes) {
+            const current = await recheckPath(node.path);
+            if (current.dev !== node.metadata.dev ||
+                current.ino !== node.metadata.ino ||
+                current.isDirectory() !== node.metadata.isDirectory() ||
+                current.isSymbolicLink() !== node.metadata.isSymbolicLink())
+                throw new RegularFileChangedError(path);
+        }
+    };
+    await assertPathNodes();
+    const before = await recheckPath(path);
+    if (selection !== undefined &&
+        !sameRegularFileState(selection.metadata, before))
+        throw new RegularFileChangedError(path);
+    if (!before.isFile() || before.isSymbolicLink())
+        throw new ElectronFuseFormatFailure("unsupported", `Expected a regular file without a symlink: ${path}`);
+    if (before.size > BigInt(ELECTRON_FUSE_LIMITS.maximumFileBytes))
+        throw new ElectronFuseResourceFailure("file-size", `Selected artifact exceeds ${ELECTRON_FUSE_LIMITS.maximumFileBytes} bytes: ${path}`);
+    const size = Number(before.size);
+    const chunkBytes = options?.chunkBytes ?? ELECTRON_FUSE_LIMITS.chunkBytes;
+    if (!Number.isSafeInteger(chunkBytes) ||
+        chunkBytes < 1 ||
+        chunkBytes > ELECTRON_FUSE_LIMITS.chunkBytes)
+        throw new TypeError(`chunkBytes must be an integer between 1 and ${ELECTRON_FUSE_LIMITS.chunkBytes}.`);
+    return withArtifactRegularFile(path, options?.resources ?? new ArtifactResourceScope(), signal, async (owned) => {
+        const opened = await owned.stat({ bigint: true });
+        if (!sameRegularFileState(before, opened))
+            throw new RegularFileChangedError(path);
+        await assertPathNodes();
+        const readAt = readerFor(owned, size, path, signal);
+        const container = await identifyContainer(readAt, size, path);
+        const scanned = await scanSlices(owned, path, size, container.slices, chunkBytes, signal);
+        const current = await recheckPath(path);
+        if (!sameRegularFileState(before, current))
+            throw new RegularFileChangedError(path);
+        await assertPathNodes();
+        return {
+            sha256: scanned.sha256,
+            bytes: size,
+            format: container.format,
+            slices: scanned.slices,
+        };
+    });
+};
+/** Sentence describing the file and sentinel bounds enforced by this reader. */
+export const electronFuseReadLimitation = () => `The selected file is admitted as one regular file of at most 1 GiB. Sentinel search uses ${ELECTRON_FUSE_LIMITS.chunkBytes}-byte windows, and each slice keeps at most ${ELECTRON_FUSE_LIMITS.maximumSentinelsPerSlice} sentinels.`;
+const readerFor = (handle, size, path, signal) => async (offset, length) => {
+    assertArtifactReadActive(signal);
+    if (length <= 0 || offset < 0 || offset >= size)
+        return new Uint8Array();
+    const bounded = Math.min(length, size - offset);
+    const buffer = Buffer.alloc(bounded);
+    const read = await handle.read(buffer, 0, bounded, offset);
+    if (read.bytesRead !== bounded)
+        throw new RegularFileChangedError(path);
+    return buffer.subarray(0, read.bytesRead);
+};
+const identifyContainer = async (readAt, size, path) => {
+    const head = await readAt(0, Math.min(size, 8));
+    if (hasMachoMagic(head))
+        return identifyMacho(readAt, size, head, path);
+    if (isElf(head)) {
+        const header = await readAt(0, 64);
+        const parsed = readElfFixedHeader(Buffer.from(header), size);
+        return {
+            format: "elf",
+            slices: [
+                {
+                    index: 0,
+                    fileOffset: 0,
+                    size,
+                    architecture: parsed.ok ? parsed.value.architecture : null,
+                },
+            ],
+        };
+    }
+    const pe = await identifyPe(readAt, size);
+    if (pe !== undefined)
+        return {
+            format: "pe",
+            slices: [
+                { index: 0, fileOffset: 0, size, architecture: pe.architecture },
+            ],
+        };
+    throw new ElectronFuseFormatFailure("unsupported", `Selected artifact ${path} does not contain a Mach-O, ELF, or PE container.`);
+};
+const identifyMacho = async (readAt, size, head, path) => {
+    const facts = await readMachoImage(readAt, size);
+    if (facts.status !== "parsed") {
+        const reason = facts.status === "not-mach-o"
+            ? `Selected artifact ${path} does not contain a Mach-O, ELF, or PE container.`
+            : facts.reason;
+        throw new ElectronFuseFormatFailure(facts.status === "malformed" ? "malformed" : "unsupported", reason);
+    }
+    const format = isFat(head) ? "mach-o-universal" : "mach-o";
+    const slices = facts.slices.map((slice, index) => ({
+        index,
+        fileOffset: slice.slice_offset,
+        size: slice.slice_size,
+        architecture: slice.architecture,
+    }));
+    assertNonOverlappingSlices(slices);
+    return {
+        format,
+        slices,
+    };
+};
+/** A FAT architecture owns a distinct byte range; overlap is malformed. */
+const assertNonOverlappingSlices = (ranges) => {
+    const ordered = [...ranges].sort((left, right) => left.fileOffset - right.fileOffset);
+    for (let index = 1; index < ordered.length; index += 1) {
+        const previous = ordered[index - 1];
+        const current = ordered[index];
+        if (previous !== undefined &&
+            current !== undefined &&
+            current.fileOffset < previous.fileOffset + previous.size)
+            throw new ElectronFuseFormatFailure("malformed", `Mach-O slices ${previous.index} and ${current.index} overlap.`);
+    }
+};
+const scanSlices = async (handle, path, size, ranges, chunkBytes, signal) => {
+    const states = ranges.map((slice) => ({
+        slice,
+        carry: Buffer.alloc(0),
+        hits: [],
+    }));
+    const hash = createHash("sha256");
+    const chunk = Buffer.allocUnsafe(chunkBytes);
+    let position = 0;
+    while (position < size) {
+        assertArtifactReadActive(signal);
+        const length = Math.min(chunkBytes, size - position);
+        const read = await handle.read(chunk, 0, length, position);
+        if (read.bytesRead !== length)
+            throw new RegularFileChangedError(path);
+        const piece = chunk.subarray(0, length);
+        hash.update(piece);
+        absorbChunk(states, piece, position);
+        position += length;
+    }
+    if (position !== size)
+        throw new RegularFileChangedError(path);
+    const slices = [];
+    for (const state of states) {
+        const sentinels = [];
+        for (const offset of state.hits)
+            sentinels.push(await parseWire(handle, path, offset, state.slice.fileOffset + state.slice.size, signal));
+        slices.push({
+            index: state.slice.index,
+            file_offset: state.slice.fileOffset,
+            size: state.slice.size,
+            architecture: state.slice.architecture,
+            sentinel_count: sentinels.length,
+            sentinels,
+        });
+    }
+    return { sha256: hash.digest("hex"), slices };
+};
+const absorbChunk = (states, chunk, position) => {
+    const chunkEnd = position + chunk.length;
+    for (const state of states) {
+        const start = Math.max(position, state.slice.fileOffset);
+        const end = Math.min(chunkEnd, state.slice.fileOffset + state.slice.size);
+        if (start >= end)
+            continue;
+        const piece = chunk.subarray(start - position, end - position);
+        const carryLength = state.carry.length;
+        const window = carryLength === 0 ? piece : Buffer.concat([state.carry, piece]);
+        const windowFileStart = start - carryLength;
+        let from = 0;
+        while (from <= window.length - SENTINEL.length) {
+            const found = window.indexOf(SENTINEL, from);
+            if (found < 0)
+                break;
+            const sentinelOffset = windowFileStart + found;
+            if (!state.hits.includes(sentinelOffset)) {
+                if (state.hits.length >= ELECTRON_FUSE_LIMITS.maximumSentinelsPerSlice)
+                    throw new ElectronFuseResourceFailure("capacity", `Slice ${state.slice.index} contains more than ${ELECTRON_FUSE_LIMITS.maximumSentinelsPerSlice} Electron fuse sentinels.`);
+                state.hits.push(sentinelOffset);
+            }
+            from = found + 1;
+        }
+        const tail = SENTINEL.length - 1;
+        state.carry =
+            window.length <= tail
+                ? Buffer.from(window)
+                : Buffer.from(window.subarray(window.length - tail));
+    }
+};
+const parseWire = async (handle, path, sentinelOffset, sliceEnd, signal) => {
+    const wireStart = sentinelOffset + SENTINEL.length;
+    const available = sliceEnd - wireStart;
+    if (available < 1)
+        return {
+            sentinel_offset: sentinelOffset,
+            wire_version: null,
+            declared_length: null,
+            fuses: [],
+            complete: false,
+        };
+    const header = await readExact(handle, path, wireStart, Math.min(available, 2), signal);
+    const wireVersion = header[0];
+    if (wireVersion === undefined || header.length < 2)
+        return {
+            sentinel_offset: sentinelOffset,
+            wire_version: wireVersion ?? null,
+            declared_length: null,
+            fuses: [],
+            complete: false,
+        };
+    const declared = header[1] ?? 0;
+    const fuseLength = Math.min(declared, available - 2);
+    const fuseBytes = fuseLength === 0
+        ? Buffer.alloc(0)
+        : await readExact(handle, path, wireStart + 2, fuseLength, signal);
+    return {
+        sentinel_offset: sentinelOffset,
+        wire_version: wireVersion,
+        declared_length: declared,
+        fuses: [...fuseBytes].map((raw, index) => ({
+            index,
+            name: electronFuseName(wireVersion, index),
+            state: electronFuseState(raw),
+            raw_byte: raw,
+        })),
+        complete: fuseBytes.length === declared,
+    };
+};
+const readExact = async (handle, path, offset, length, signal) => {
+    assertArtifactReadActive(signal);
+    const buffer = Buffer.alloc(length);
+    const read = await handle.read(buffer, 0, length, offset);
+    if (read.bytesRead !== length)
+        throw new RegularFileChangedError(path);
+    return buffer;
+};
+const isElf = (head) => head.length >= 4 &&
+    head[0] === 0x7f &&
+    head[1] === 0x45 &&
+    head[2] === 0x4c &&
+    head[3] === 0x46;
+const isFat = (head) => {
+    if (head.length < 4)
+        return false;
+    const magic = Buffer.from(head.buffer, head.byteOffset, 4).readUInt32BE(0);
+    return FAT_MAGICS.has(magic);
+};
+const identifyPe = async (readAt, size) => {
+    if (size < 64)
+        return undefined;
+    const header = await readAt(0, 64);
+    if (header.length < 64 || header[0] !== 0x4d || header[1] !== 0x5a)
+        return undefined;
+    const offset = Buffer.from(header.buffer, header.byteOffset, header.byteLength).readUInt32LE(0x3c);
+    if (!Number.isSafeInteger(offset) ||
+        offset < 64 ||
+        offset > ELECTRON_FUSE_LIMITS.maximumPeHeaderOffset ||
+        offset > size - 4)
+        return undefined;
+    const bytes = Buffer.from(await readAt(offset, 24));
+    if (bytes.length < 4 || bytes.readUInt32LE(0) !== 0x00004550)
+        return undefined;
+    // A signature establishes the existing scan boundary; only a complete COFF
+    // header establishes its machine. Managed OS overrides need separate proof.
+    const machine = bytes.length === 24 ? decodePeMachine(bytes.readUInt16LE(4)) : undefined;
+    return {
+        architecture: machine?.nativeOsOverride === false ? machine.architecture : null,
+    };
+};
+const isMissingPath = (cause) => cause instanceof Error &&
+    "code" in cause &&
+    ["ENOENT", "ENOTDIR"].includes(String(cause.code));