reverseport 0.0.0-stage → 1.2.0

package/dist/artifacts/extraction/ArtifactExtraction.js

@@ -0,0 +1,253 @@
+import { lstat, realpath } from "node:fs/promises";
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
+import { AsarArtifactReader } from "../AsarArtifactReader.js";
+import { ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.js";
+import { ArtifactReaderFailure, } from "../ArtifactReader.js";
+import { abortIfNeeded } from "../ArtifactHash.js";
+import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
+import { SafeOutputTree } from "../SafeOutputTree.js";
+import { SafeOutputTreeCreationFailure } from "../SafeOutputTreeCreationFailure.js";
+import { ZipArtifactReader } from "../ZipArtifactReader.js";
+import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";
+import { artifactExtractionResultSchema, } from "../../domain/artifactGraph.js";
+import { AnalysisUnsupportedTargetError } from "../../domain/analysisErrorCore.js";
+import { isMachOFormat, } from "../../domain/binaryTargetTypes.js";
+import { scanArtifactInventoryInScope } from "../inventory/ArtifactInventory.js";
+/** Extract every regular inventory occurrence into an exclusively owned absent root. */
+export const extractArtifact = async (input, signal) => input.resourceScope.run(() => extractArtifactInScope(input, signal));
+const extractArtifactInScope = async (input, signal) => {
+    // Cancellation wins over every later refusal, including unsupported formats.
+    abortIfNeeded(signal);
+    const sourcePath = await realpath(input.inputPath);
+    await requireExtractableFormat(sourcePath, input);
+    const snapshot = await scanArtifactInventoryInScope(sourcePath, {
+        resourceScope: input.resourceScope,
+        signal,
+        environment: input.environment,
+        integrity: { mode: input.integrityPolicy },
+    });
+    return materializeArtifactInventoryInScope(input, sourcePath, snapshot, signal);
+};
+/** Materialize a scanned inventory, verifying every current occurrence against it. */
+export const materializeArtifactInventory = async (input, sourcePath, snapshot, signal) => {
+    return input.resourceScope.run(() => materializeArtifactInventoryInScope(input, sourcePath, snapshot, signal));
+};
+const materializeArtifactInventoryInScope = async (input, sourcePath, snapshot, signal) => {
+    abortIfNeeded(signal);
+    const selectedOccurrences = snapshot.occurrences.filter((occurrence) => (occurrence.entry_kind === "file" || occurrence.entry_kind === "slice") &&
+        occurrence.logical_path !== ".");
+    const regularPaths = new Set(selectedOccurrences.map(({ logical_path: path }) => path));
+    const activeOccurrences = selectedOccurrences.filter(({ logical_path }) => {
+        // Nested members remain represented by their containing regular file;
+        // only entries exposed by the active reader are materialized.
+        let path = logical_path;
+        for (let slash = path.lastIndexOf("/"); slash >= 0; slash = path.lastIndexOf("/")) {
+            path = path.slice(0, slash);
+            if (regularPaths.has(path))
+                return false;
+        }
+        return true;
+    });
+    const selectedIds = new Set(activeOccurrences.map(({ occurrence_id: id }) => id));
+    const neededNodes = new Set(activeOccurrences.map(({ artifact_id: id }) => id));
+    const nodes = new Map();
+    for (const node of snapshot.nodes)
+        if (neededNodes.has(node.artifact_id))
+            nodes.set(node.artifact_id, node);
+    const inventory = {
+        manifest: snapshot.manifest,
+        integrityContradictions: snapshot.integrity_contradictions.filter(({ occurrence_id: id }) => selectedIds.has(id)),
+    };
+    const selected = activeOccurrences.map((occurrence) => {
+        // REA never decrypts archive entries, so an encrypted entry makes the
+        // complete extraction unsupported rather than the archive invalid.
+        if (occurrence.encrypted)
+            throw new AnalysisUnsupportedTargetError("extract_artifact", input.inputPath, `Archive entry ${occurrence.logical_path} is encrypted; REA does not decrypt archive entries, so the archive cannot be extracted completely`);
+        // Inventory keeps an ASAR unpacked entry whose companion file is absent,
+        // but extraction cannot materialize bytes it never observed.
+        if (occurrence.entry_kind === "file" &&
+            occurrence.artifact_id === null &&
+            occurrence.hash_status === "unavailable")
+            throw new ArtifactReaderFailure("unavailable", `ASAR unpacked companion bytes are unavailable for ${occurrence.logical_path}`, undefined, {
+                logicalPath: occurrence.logical_path,
+                declaredSha256: null,
+                calculatedSha256: null,
+                unpacked: true,
+            });
+        if ((occurrence.entry_kind !== "file" && occurrence.entry_kind !== "slice") ||
+            occurrence.artifact_id === null ||
+            occurrence.logical_path === ".")
+            throw new ArtifactReaderFailure("format", `Selected occurrence is not an extractable regular child file: ${occurrence.logical_path} (${occurrence.occurrence_id})`);
+        const node = nodes.get(occurrence.artifact_id);
+        if (node === undefined)
+            throw new ArtifactReaderFailure("integrity", `Selected occurrence has no inventory node: ${occurrence.occurrence_id}`);
+        return { occurrence, node };
+    });
+    return materializeSelection({
+        input,
+        sourcePath,
+        inventory,
+        selected,
+        signal,
+    });
+};
+const materializeSelection = async ({ input, sourcePath, inventory, selected, signal, }) => {
+    const byPath = new Map(selected.map((item) => [item.occurrence.logical_path, item]));
+    const reader = await createReader(sourcePath, input);
+    const readerOwner = {
+        kind: "reader",
+        reader,
+        resource: `artifact reader for ${sourcePath}`,
+    };
+    let localReaderOwner = readerOwner;
+    let output;
+    let completed;
+    const extracted = [];
+    try {
+        try {
+            output = await SafeOutputTree.create(input.outputRoot);
+        }
+        catch (cause) {
+            if (cause instanceof SafeOutputTreeCreationFailure)
+                output = cause.tree;
+            throw cause;
+        }
+        await writeSelectedEntries({ reader, output, byPath, extracted, signal });
+        localReaderOwner = undefined;
+        const closeAttempt = await input.resourceScope.release(readerOwner);
+        if (closeAttempt.kind === "failed")
+            throw ArtifactReaderFailure.withCleanup(closeAttempt.cause, ArtifactReaderFailure.cleanupObservation(closeAttempt.cause, readerOwner.resource));
+        extracted.sort((left, right) => compareUnicodeCodePoints(left.relative_path, right.relative_path));
+        completed = createExtractionResult(input, inventory, selected, extracted);
+        await output.commit();
+        return completed;
+    }
+    catch (cause) {
+        const cleanupFailures = await releaseExtractionOwners(input.resourceScope, localReaderOwner, output, input.outputRoot);
+        if (cleanupFailures.length > 0) {
+            const observations = cleanupFailures.map(({ cause: cleanupCause, resource }) => ArtifactReaderFailure.cleanupObservation(cleanupCause, resource));
+            throw ArtifactReaderFailure.withCleanup(cause, {
+                reason: observations.map(({ reason }) => reason).join("; "),
+                resources: [
+                    ...new Set(observations.flatMap(({ resources }) => resources)),
+                ],
+            }, output?.published === true && completed !== undefined
+                ? { kind: "artifact-extraction", extraction: completed }
+                : undefined);
+        }
+        if (output?.published === true && completed !== undefined)
+            return completed;
+        throw cause;
+    }
+};
+const writeSelectedEntries = async ({ reader, output, byPath, extracted, signal, }) => {
+    const registry = new ArtifactPathRegistry();
+    for await (const entry of reader.entries(signal)) {
+        const path = normalizeArtifactPath(entry.path);
+        registry.add(path, entry.kind);
+        const selectedItem = byPath.get(path);
+        if (selectedItem === undefined) {
+            if (entry.kind === "file" || entry.kind === "slice")
+                throw new ArtifactReaderFailure("integrity", `Regular artifact entry is missing from inventory: ${path}`);
+            continue;
+        }
+        preflight(entry);
+        const stream = await reader.open(entry, signal);
+        const written = await output.write(path, stream, {
+            sha256: selectedItem.node.sha256,
+            bytes: selectedItem.node.size,
+        }, signal);
+        extracted.push({
+            artifact_id: selectedItem.node.artifact_id,
+            relative_path: written.relativePath,
+            sha256: written.sha256,
+            bytes_written: written.bytesWritten,
+            created: true,
+        });
+        byPath.delete(path);
+    }
+    if (byPath.size > 0)
+        throw new ArtifactReaderFailure("integrity", `Inventoried regular artifact entries were not materialized: ${[...byPath.keys()].sort(compareUnicodeCodePoints).join(", ")}`);
+};
+const releaseExtractionOwners = async (resourceScope, readerOwner, output, outputRoot) => {
+    const failures = [];
+    if (readerOwner !== undefined) {
+        const attempt = await resourceScope.release(readerOwner);
+        if (attempt.kind === "failed")
+            failures.push({ cause: attempt.cause, resource: readerOwner.resource });
+    }
+    if (output !== undefined) {
+        const owner = {
+            kind: "output-tree",
+            tree: output,
+            resource: outputRoot,
+        };
+        const attempt = await resourceScope.release(owner);
+        if (attempt.kind === "failed")
+            failures.push({ cause: attempt.cause, resource: owner.resource });
+    }
+    return failures;
+};
+const createExtractionResult = (input, inventory, selected, extracted) => {
+    const extractionSemantic = {
+        source_manifest_id: inventory.manifest.manifest_id,
+        selected_occurrence_ids: selected
+            .map(({ occurrence }) => occurrence.occurrence_id)
+            .sort(compareUnicodeCodePoints),
+        files_sha256: digestCanonicalValue(extracted, "Artifact"),
+        output_root_alias: "$OUTPUT_ROOT",
+    };
+    return artifactExtractionResultSchema.parse({
+        manifest: inventory.manifest,
+        extraction_manifest: {
+            ...extractionSemantic,
+            extraction_id: `aex_${digestCanonicalValue(extractionSemantic, "Artifact")}`,
+        },
+        output_root: input.outputRoot,
+        artifacts: extracted,
+        containment_verified: true,
+        cleanup: { attempted: false, verified: true, residual_paths: [] },
+        provenance: [],
+        integrity_contradictions: inventory.integrityContradictions,
+        limitations: [
+            "All regular files in the active artifact were materialized; nested archive contents remain represented by their containing file.",
+            ...(inventory.integrityContradictions.length === 0
+                ? []
+                : [
+                    `${String(inventory.integrityContradictions.length)} extracted file(s) contradict declared integrity metadata; their bytes are observed-untrusted.`,
+                ]),
+        ],
+    });
+};
+const ZIP_FORMATS = ["ipa", "apk", "msix", "appx", "zip"];
+const isZipFormat = (format) => ZIP_FORMATS.includes(format);
+/**
+ * Refuse a format without an extraction reader before inventory work starts.
+ * The target kind, not the host, is unsupported by extraction. The error keeps
+ * the caller's spelling of the path; I/O uses the canonical path.
+ */
+const requireExtractableFormat = async (path, input) => {
+    const format = input.inputFormat;
+    const directory = (await lstat(path)).isDirectory();
+    if (!directory &&
+        format !== "asar" &&
+        !isMachOFormat(format) &&
+        !isZipFormat(format))
+        throw new AnalysisUnsupportedTargetError("extract_artifact", input.inputPath, `Artifact format has no extraction reader: ${format}`);
+    return directory;
+};
+const createReader = async (path, input) => {
+    const format = input.inputFormat;
+    if (await requireExtractableFormat(path, input))
+        return new DirectoryArtifactReader(path);
+    if (format === "asar")
+        return new AsarArtifactReader(path);
+    if (isZipFormat(format))
+        return new ZipArtifactReader(path, format);
+    return new MachOSliceArtifactReader(path, input.environment);
+};
+const preflight = (entry) => {
+    if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)
+        throw new ArtifactReaderFailure("format", `Selected artifact entry cannot be read: ${entry.path}`);
+};

package/dist/artifacts/hostExecutableMarking.js

@@ -0,0 +1,16 @@
+import { extname } from "node:path";
+/** Extensions Windows launches directly through CreateProcess or cmd.exe. */
+const windowsLaunchableExtensions = new Set([".bat", ".cmd", ".com", ".exe"]);
+/**
+ * Whether a host filesystem entry carries the host's executable marking.
+ *
+ * POSIX hosts mark executability with permission bits. Windows has no execute
+ * bit (Node reports file modes from the read-only attribute alone), so it marks
+ * launchable files by extension instead.
+ */
+export const hostExecutableMarking = (path, metadata, platform = process.platform) => platform === "win32"
+    ? metadata.isFile() &&
+        windowsLaunchableExtensions.has(extname(path).toLowerCase())
+    : typeof metadata.mode === "bigint"
+        ? (metadata.mode & 73n) !== 0n
+        : (metadata.mode & 0o111) !== 0;

package/dist/artifacts/inventory/ArtifactGraphConstruction.js

@@ -0,0 +1,343 @@
+import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
+import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
+import { artifactEdgeId, artifactIdForContent, occurrenceIdForLocation, } from "../../domain/artifactIdentity.js";
+import { hasZipSignature, isZipPackageFormat, zipPackageFormatForPath, } from "../../domain/zipPackageFormat.js";
+import { mzWindowsHeaderOffset, parseDosMzHeader } from "../../domain/dosMz.js";
+/** Index the first occurrence for each canonical logical path. */
+export const indexOccurrencesByPath = (occurrences) => {
+    const byPath = new Map();
+    for (const occurrence of occurrences)
+        if (!byPath.has(occurrence.logical_path))
+            byPath.set(occurrence.logical_path, occurrence);
+    return byPath;
+};
+/**
+ * Create an occurrence before its bytes are read. A container suffix is not a
+ * container family until the bytes are classified, so a member named like a
+ * container starts with an unknown format.
+ */
+export const createOccurrence = (entry, path, parent) => {
+    const role = entry.kind === "directory"
+        ? {
+            kind: path.toLowerCase().endsWith(".framework")
+                ? "framework"
+                : "container",
+            format: "directory",
+        }
+        : containerSuffixFamily(path) === undefined
+            ? classifyArtifactPath(path)
+            : { kind: "unknown", format: "unknown" };
+    return {
+        occurrence_id: `occ_${digestCanonicalValue({ path, kind: entry.kind }, "Artifact")}`,
+        artifact_id: null,
+        parent_occurrence_id: parent,
+        logical_path: path,
+        entry_kind: entry.kind,
+        artifact_kind: role.kind,
+        artifact_format: role.format,
+        declared_size: entry.declaredSize,
+        compressed_size: entry.compressedSize,
+        executable: entry.executable,
+        encrypted: entry.encrypted,
+        hash_status: entry.encrypted ? "unavailable" : "not-hashed",
+        source_location: entry.byteOffset === null || entry.declaredSize === null
+            ? null
+            : { offset: entry.byteOffset, length: entry.declaredSize },
+        limitations: [...entry.limitations],
+    };
+};
+/** Record that an unread member's container suffix was not checked against bytes. */
+export const noteUnreadContainerSuffix = (occurrence) => {
+    if (occurrence.entry_kind === "directory")
+        return;
+    const family = containerSuffixFamily(occurrence.logical_path);
+    if (family === undefined)
+        return;
+    occurrence.limitations.push(`The path suffix suggests ${family.toUpperCase()}, but these bytes were not read, so the container family is unknown.`);
+};
+const containerSuffixFamily = (path) => {
+    const lower = path.toLowerCase();
+    return lower.endsWith(".asar") ? "asar" : zipPackageFormatForPath(lower);
+};
+/** Compare exact child names independently of host locale and traversal order. */
+export const materializeDirectoryNodes = (occurrences, nodes) => {
+    const directories = occurrences
+        .filter(({ entry_kind: kind }) => kind === "directory")
+        .sort((left, right) => depth(right.logical_path) - depth(left.logical_path));
+    const childrenByParent = new Map();
+    for (const occurrence of occurrences) {
+        if (occurrence.parent_occurrence_id === null)
+            continue;
+        const children = childrenByParent.get(occurrence.parent_occurrence_id);
+        if (children === undefined)
+            childrenByParent.set(occurrence.parent_occurrence_id, [occurrence]);
+        else
+            children.push(occurrence);
+    }
+    for (const directory of directories) {
+        const children = (childrenByParent.get(directory.occurrence_id) ?? [])
+            .map(({ logical_path, artifact_id, entry_kind }) => ({
+            // Intermediate directory entries may be absent from an archive.
+            name: logical_path.slice(directory.logical_path.length + 1),
+            artifact_id,
+            entry_kind,
+        }))
+            .sort((left, right) => compareUnicodeCodePoints(left.name, right.name));
+        const node = createArtifactNode({
+            sha256: digestCanonicalValue({ kind: "directory", children }, "Artifact"),
+            size: 0,
+            format: "directory",
+            contentState: "virtual",
+        });
+        nodes.set(node.artifact_id, node);
+        directory.artifact_id = node.artifact_id;
+        directory.hash_status = "verified";
+    }
+};
+export const createRootNode = (input) => createArtifactNode({
+    sha256: input.digest?.sha256 ??
+        digestCanonicalValue({
+            kind: "directory-root",
+            children: input.occurrences
+                .map(({ logical_path, artifact_id }) => ({
+                logical_path,
+                artifact_id,
+            }))
+                .sort((left, right) => compareUnicodeCodePoints(left.logical_path, right.logical_path)),
+        }, "Artifact"),
+    size: input.digest?.bytes ?? 0,
+    format: input.digest === null
+        ? "directory"
+        : classifyArtifactBytes(input.digest.prefix, input.digest.bytes),
+    contentState: "materialized",
+});
+export const createArtifactNode = (input) => ({
+    artifact_id: artifactIdForContent(input.sha256),
+    format: input.format,
+    sha256: input.sha256,
+    size: input.size,
+    media_type: null,
+    architecture: null,
+    content_state: input.contentState,
+    limitations: [],
+});
+export const rootOccurrenceFor = (node, metadata) => ({
+    occurrence_id: occurrenceIdForLocation({
+        rootArtifactId: node.artifact_id,
+        logicalPath: ".",
+        entryKind: metadata.format === "directory" ? "directory" : "file",
+    }),
+    artifact_id: node.artifact_id,
+    parent_occurrence_id: null,
+    logical_path: ".",
+    entry_kind: metadata.format === "directory" ? "directory" : "file",
+    artifact_kind: metadata.format === "directory" ||
+        isZipPackageFormat(metadata.format) ||
+        ["asar", "dmg", "pkg"].includes(metadata.format)
+        ? "container"
+        : artifactRoleForFormat(metadata.path, metadata.format).kind,
+    artifact_format: metadata.format,
+    declared_size: metadata.size,
+    compressed_size: null,
+    executable: metadata.executable,
+    encrypted: false,
+    hash_status: "verified",
+    source_location: null,
+    limitations: [],
+});
+export const rekeyOccurrences = (rootArtifactId, occurrences) => {
+    const replacements = new Map();
+    for (const occurrence of occurrences)
+        replacements.set(occurrence.occurrence_id, occurrenceIdForLocation({
+            rootArtifactId,
+            logicalPath: occurrence.logical_path,
+            entryKind: occurrence.entry_kind,
+        }));
+    for (const occurrence of occurrences) {
+        occurrence.occurrence_id =
+            replacements.get(occurrence.occurrence_id) ?? occurrence.occurrence_id;
+        if (occurrence.parent_occurrence_id !== null)
+            occurrence.parent_occurrence_id =
+                replacements.get(occurrence.parent_occurrence_id) ??
+                    occurrence.parent_occurrence_id;
+    }
+};
+export const createArtifactEdges = (rootArtifactId, occurrences, producer) => {
+    const byId = new Map(occurrences.map((item) => [item.occurrence_id, item]));
+    const byPath = indexOccurrencesByPath(occurrences);
+    const edges = [];
+    for (const occurrence of occurrences) {
+        if (occurrence.parent_occurrence_id === null ||
+            occurrence.artifact_id === null)
+            continue;
+        const mappedSource = occurrence.logical_path.toLowerCase().endsWith(".map")
+            ? byPath.get(occurrence.logical_path.slice(0, -".map".length))
+            : undefined;
+        const parentArtifactId = mappedSource?.artifact_id ??
+            byId.get(occurrence.parent_occurrence_id)?.artifact_id ??
+            rootArtifactId;
+        const semantic = {
+            parent_artifact_id: parentArtifactId,
+            relation: occurrence.entry_kind === "slice"
+                ? "slice-of"
+                : relationFor(occurrence.logical_path),
+            occurrence_id: occurrence.occurrence_id,
+        };
+        edges.push({
+            edge_id: artifactEdgeId(semantic, occurrence),
+            ...semantic,
+            producer: occurrence.entry_kind === "slice" ? (producer ?? null) : null,
+            ordinal: edges.length,
+        });
+    }
+    return edges;
+};
+/** Resolve strict observed ancestors without rebuilding every path prefix. */
+export const resolveOccurrenceParents = (occurrences, byPath, expandedContainerIds) => {
+    const root = { children: new Map() };
+    for (const occurrence of byPath.values()) {
+        if (occurrence.entry_kind !== "directory" &&
+            !expandedContainerIds.has(occurrence.occurrence_id))
+            continue;
+        let branch = root;
+        for (const segment of occurrence.logical_path.split("/")) {
+            let child = branch.children.get(segment);
+            if (child === undefined) {
+                child = { children: new Map() };
+                branch.children.set(segment, child);
+            }
+            branch = child;
+        }
+        branch.occurrence = occurrence;
+    }
+    for (const occurrence of occurrences) {
+        const path = occurrence.logical_path;
+        let branch = root;
+        let parent;
+        // Walk parent segments only. Stop scanning the path once no observed
+        // directory or expanded container can be an ancestor.
+        for (let start = 0;;) {
+            const slash = path.indexOf("/", start);
+            if (slash < 0)
+                break;
+            const segment = path.slice(start, slash);
+            const child = branch.children.get(segment);
+            if (child === undefined)
+                break;
+            branch = child;
+            parent = branch.occurrence ?? parent;
+            start = slash + 1;
+        }
+        occurrence.parent_occurrence_id = parent?.occurrence_id ?? null;
+    }
+};
+/**
+ * Assign a path role hint. Container families are not path roles: ZIP and
+ * ASAR families are chosen only after their bytes have been classified.
+ */
+export const classifyArtifactPath = (path) => {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".map"))
+        return { kind: "source-map", format: "source-map" };
+    if (/\.(?:m?js|cjs)$/u.test(lower))
+        return { kind: "javascript", format: "javascript-bundle" };
+    if (/\.framework(?:\/|$)/u.test(lower))
+        return { kind: "framework", format: "file" };
+    if (/\.(?:node|dylib|so)$/u.test(lower))
+        return {
+            kind: lower.endsWith(".node") ? "native-addon" : "dynamic-library",
+            format: "file",
+        };
+    if (lower.endsWith(".plist"))
+        return { kind: "plist", format: "plist" };
+    if (lower.endsWith(".entitlements"))
+        return { kind: "entitlements", format: "entitlements" };
+    return { kind: "resource", format: "file" };
+};
+/** Classify executable formats from bytes while retaining path-specific roles. */
+export const classifyArtifactContent = (path, prefix, fileSize = prefix.length) => {
+    const format = classifyArtifactBytes(prefix, fileSize);
+    if (format === "file" &&
+        path.toLowerCase().endsWith(".asar") &&
+        hasAsarHeader(prefix))
+        return { kind: "container", format: "asar" };
+    return artifactRoleForFormat(path, format);
+};
+/**
+ * Electron ASAR starts with a size pickle whose payload is one uint32, then
+ * a header pickle whose payload begins with a JSON object.
+ */
+export const hasAsarHeader = (prefix) => {
+    if (prefix.length < 17 || prefix.readUInt32LE(0) !== 4)
+        return false;
+    const headerSize = prefix.readUInt32LE(4);
+    const payloadSize = prefix.readUInt32LE(8);
+    if (headerSize < 16 || payloadSize !== headerSize - 4)
+        return false;
+    const stringLength = prefix.readUInt32LE(12);
+    return (stringLength >= 2 && stringLength <= payloadSize - 4 && prefix[16] === 0x7b);
+};
+const artifactRoleForFormat = (path, format) => {
+    const byPath = classifyArtifactPath(path);
+    if (format === "file" || format === byPath.format)
+        return byPath;
+    if (format === "unknown")
+        return { kind: "unknown", format };
+    if (format === "zip")
+        return {
+            kind: "container",
+            format: zipPackageFormatForPath(path) ?? format,
+        };
+    if (format === "plist")
+        return { kind: "plist", format };
+    return {
+        kind: ["native-addon", "dynamic-library"].includes(byPath.kind)
+            ? byPath.kind
+            : "executable",
+        format,
+    };
+};
+/** Classify storage bytes independently of path names, roles, and permissions. */
+export const classifyArtifactBytes = (prefix, fileSize = prefix.length) => {
+    if (hasZipSignature(prefix))
+        return "zip";
+    if (prefix.subarray(0, 8).equals(Buffer.from("bplist00")))
+        return "plist";
+    if (prefix.length >= 4) {
+        const magic = prefix.readUInt32BE(0);
+        if ([0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
+            return "mach-o-universal";
+        if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic))
+            return "mach-o";
+        if (prefix.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
+            return "elf";
+    }
+    if (prefix.length >= 2 && prefix[0] === 0x4d && prefix[1] === 0x5a) {
+        if (!Number.isSafeInteger(fileSize) ||
+            fileSize < prefix.length ||
+            prefix.length < Math.min(fileSize, 64))
+            return "unknown";
+        const windowsOffset = mzWindowsHeaderOffset(prefix);
+        if (windowsOffset !== null) {
+            if (windowsOffset >= 64 &&
+                windowsOffset <= prefix.length - 4 &&
+                prefix
+                    .subarray(windowsOffset, windowsOffset + 4)
+                    .equals(Buffer.from([0x50, 0x45, 0, 0])))
+                return "pe";
+        }
+        else if (parseDosMzHeader(prefix, fileSize).ok)
+            return "dos-mz";
+        return "unknown";
+    }
+    return "file";
+};
+const relationFor = (path) => {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".map"))
+        return "maps-source";
+    if (lower.includes(".framework/"))
+        return "embeds";
+    return "contains";
+};
+const depth = (path) => path.split("/").length;

package/dist/artifacts/inventory/ArtifactInventory.js

@@ -0,0 +1,16 @@
+import { realpath } from "node:fs/promises";
+import { artifactInventoryResultSchema, } from "../../domain/artifactGraph.js";
+import { abortIfNeeded } from "../ArtifactHash.js";
+import { scanCanonicalArtifactInventoryInScope } from "./scanCanonical.js";
+/** Inventory one local artifact and return every graph collection inline. */
+export const inventoryArtifact = async (inputPath, options) => {
+    const snapshot = await scanArtifactInventory(inputPath, options);
+    return artifactInventoryResultSchema.parse(snapshot);
+};
+/** Scan an artifact once and retain the complete immutable graph for projection. */
+export const scanArtifactInventory = async (inputPath, options) => options.resourceScope.run(() => scanArtifactInventoryInScope(inputPath, options));
+export const scanArtifactInventoryInScope = async (inputPath, options) => {
+    abortIfNeeded(options.signal);
+    const path = await realpath(inputPath);
+    return scanCanonicalArtifactInventoryInScope(path, options);
+};