rea-agents 1.7.0 → 2.1.0

package/dist/application/ArtifactInventory.js

@@ -1,148 +1,19 @@
-import { createHash } from "node:crypto";
-import { createReadStream } from "node:fs";
-import { lstat, open, realpath } from "node:fs/promises";
-import { AsarArtifactReader } from "../artifacts/AsarArtifactReader.js";
-import { ArtifactPathRegistry, normalizeArtifactPath, } from "../artifacts/ArtifactPaths.js";
-import { ArtifactReaderFailure, } from "../artifacts/ArtifactReader.js";
-import { DirectoryArtifactReader } from "../artifacts/DirectoryArtifactReader.js";
-import { ZipArtifactReader } from "../artifacts/ZipArtifactReader.js";
-import { MachOSliceArtifactReader } from "../artifacts/MachOSliceArtifactReader.js";
-import { NativeDmgArtifactReader } from "../artifacts/NativeDmgArtifactReader.js";
-import { streamChunkToBuffer } from "../artifacts/StreamBytes.js";
+import { realpath } from "node:fs/promises";
 import { artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
-import { classifyArtifactPath, classifyArtifactContent, createArtifactEdges, createArtifactNode, createOccurrence, createRootNode, digestCanonical, indexOccurrencesByPath, materializeDirectoryNodes, nearestParent, pageOf, rekeyOccurrences, rootOccurrenceFor, toOutputLimits, } from "./ArtifactGraphConstruction.js";
-const NATIVE_MOUNT_DISABLED = {
-    nativeMountApproved: false,
-    nativeMountEnabled: false,
-};
-const STRICT_INTEGRITY_POLICY = {
-    mode: "fail",
-    approved: false,
-    enabled: false,
-    maxMismatches: 1,
-};
+import { pageOf } from "./ArtifactGraphConstruction.js";
+import { abortIfNeeded } from "./ArtifactInventory/hash.js";
+import { scanCanonicalArtifactInventory } from "./ArtifactInventory/scanCanonical.js";
+export { scanCanonicalArtifactInventory } from "./ArtifactInventory/scanCanonical.js";
 /** Inventory one local artifact without extracting or mounting it. */
 export const inventoryArtifact = async (inputPath, limits, page, options = {}) => {
-    const snapshot = await scanArtifactInventory(inputPath, limits, options.signal, options.nativeMount ?? NATIVE_MOUNT_DISABLED, options.integrity ?? STRICT_INTEGRITY_POLICY);
+    const snapshot = await scanArtifactInventory(inputPath, limits, options);
     return paginateArtifactInventory(snapshot, page);
 };
 /** Scan an artifact once and retain the complete immutable graph for projection. */
-export const scanArtifactInventory = async (inputPath, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED, integrity = STRICT_INTEGRITY_POLICY) => {
-    abortIfNeeded(signal);
+export const scanArtifactInventory = async (inputPath, limits, options = {}) => {
+    abortIfNeeded(options.signal);
     const path = await realpath(inputPath);
-    return scanCanonicalArtifactInventory(path, limits, signal, nativeMount, integrity);
-};
-/** Scan one already-canonical artifact path without resolving it again. */
-export const scanCanonicalArtifactInventory = async (path, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED, integrity = STRICT_INTEGRITY_POLICY) => {
-    if (integrity.mode === "record-and-continue" &&
-        (!integrity.approved || !integrity.enabled))
-        throw new ArtifactReaderFailure("unavailable", "Integrity continuation requires explicit approval and operator policy");
-    const metadata = await lstat(path);
-    const rootFormat = await classifyRoot(path, metadata.isDirectory());
-    const rootDigest = metadata.isDirectory()
-        ? null
-        : await hashReadable(createReadStream(path), limits.maxTotalBytes, signal);
-    const reader = await createReader(path, rootFormat, nativeMount, signal);
-    try {
-        const { nodes, occurrences, pendingContradictions } = await scanReader(reader, limits, signal, integrity);
-        materializeDirectoryNodes(occurrences, nodes);
-        const rootNode = createRootNode({
-            path,
-            format: rootFormat,
-            directory: metadata.isDirectory(),
-            digest: rootDigest,
-            occurrences,
-        });
-        nodes.set(rootNode.artifact_id, rootNode);
-        rekeyOccurrences(rootNode.artifact_id, occurrences);
-        const rootOccurrence = rootOccurrenceFor(rootNode, metadata.size);
-        for (const occurrence of occurrences)
-            if (occurrence.parent_occurrence_id === null)
-                occurrence.parent_occurrence_id = rootOccurrence.occurrence_id;
-        occurrences.unshift(rootOccurrence);
-        const occurrenceById = new Map(occurrences.map((occurrence) => [occurrence.occurrence_id, occurrence]));
-        const occurrenceByPath = indexOccurrencesByPath(occurrences);
-        const integrityContradictions = pendingContradictions.map((contradiction) => {
-            const occurrence = occurrenceByPath.get(contradiction.logicalPath);
-            if (occurrence === undefined)
-                throw new ArtifactReaderFailure("integrity", "Integrity contradiction lost its graph occurrence");
-            const parent = occurrence.parent_occurrence_id === null
-                ? undefined
-                : occurrenceById.get(occurrence.parent_occurrence_id);
-            const parentArtifactId = parent?.artifact_id ?? rootNode.artifact_id;
-            return {
-                contradiction_id: `ic_${digestCanonical({
-                    root_artifact_id: rootNode.artifact_id,
-                    logical_path: contradiction.logicalPath,
-                    declared_sha256: contradiction.declaredSha256,
-                    observed_sha256: contradiction.observedSha256,
-                })}`,
-                occurrence_id: occurrence.occurrence_id,
-                parent_artifact_id: parentArtifactId,
-                logical_path: contradiction.logicalPath,
-                declared_sha256: contradiction.declaredSha256,
-                observed_sha256: contradiction.observedSha256,
-                entry_kind: contradiction.entryKind,
-                unpacked: contradiction.unpacked,
-                trust: "observed-untrusted",
-                provenance: "container-integrity-metadata-versus-observed-bytes",
-                limitations: [
-                    "Observed bytes contradict declared integrity metadata and cannot support equivalence.",
-                ],
-            };
-        });
-        const edges = createArtifactEdges(rootNode.artifact_id, occurrences, reader?.provenance()[0]);
-        const orderedNodes = [...nodes.values()].sort((left, right) => left.artifact_id.localeCompare(right.artifact_id));
-        const orderedOccurrences = occurrences.sort((left, right) => left.logical_path.localeCompare(right.logical_path, "en"));
-        const orderedEdges = edges.sort((left, right) => left.edge_id.localeCompare(right.edge_id));
-        if (rootDigest !== null) {
-            const verified = await hashReadable(createReadStream(path), limits.maxTotalBytes, signal);
-            if (verified.sha256 !== rootDigest.sha256 ||
-                verified.bytes !== rootDigest.bytes)
-                throw new ArtifactReaderFailure("integrity", "Root artifact changed during inventory");
-        }
-        const graphSha256 = digestCanonical({
-            nodes: orderedNodes,
-            occurrences: orderedOccurrences,
-            edges: orderedEdges,
-            integrity_contradictions: integrityContradictions,
-        });
-        const manifestId = `agm_${digestCanonical({
-            schema_version: 1,
-            root_artifact_id: rootNode.artifact_id,
-            graph_sha256: graphSha256,
-        })}`;
-        return {
-            manifest: artifactInventoryResultSchema.shape.manifest.parse({
-                schema_version: 1,
-                manifest_id: manifestId,
-                root_artifact_id: rootNode.artifact_id,
-                root_sha256: rootNode.sha256,
-                root_format: rootNode.format,
-                graph_sha256: graphSha256,
-                node_count: orderedNodes.length,
-                occurrence_count: orderedOccurrences.length,
-                edge_count: orderedEdges.length,
-            }),
-            nodes: orderedNodes,
-            occurrences: orderedOccurrences,
-            edges: orderedEdges,
-            limits: toOutputLimits(limits),
-            provenance: reader?.provenance() ?? [],
-            integrity_contradictions: integrityContradictions,
-            limitations: [
-                ...inventoryLimitations(rootFormat, reader),
-                ...(integrityContradictions.length === 0
-                    ? []
-                    : [
-                        `${String(integrityContradictions.length)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`,
-                    ]),
-            ],
-        };
-    }
-    finally {
-        await reader?.close();
-    }
+    return scanCanonicalArtifactInventory(path, limits, options);
 };
 /** Project independently paged graph collections from one inventory snapshot. */
 export const paginateArtifactInventory = (snapshot, page) => artifactInventoryResultSchema.parse({
@@ -151,216 +22,3 @@ export const paginateArtifactInventory = (snapshot, page) => artifactInventoryRe
     occurrences: pageOf(snapshot.occurrences, page.occurrenceOffset, page.occurrenceLimit),
     edges: pageOf(snapshot.edges, page.edgeOffset, page.edgeLimit),
 });
-const inventoryLimitations = (format, reader) => {
-    if (reader !== undefined)
-        return [];
-    if (format === "dmg" || format === "pkg")
-        return [
-            `${format.toUpperCase()} root hash is observed; child inventory requires an approved native macOS adapter.`,
-        ];
-    if (format === "mach-o-universal" && process.platform !== "darwin")
-        return ["Universal Mach-O slices require the native macOS lipo adapter."];
-    return ["Artifact has no child container entries."];
-};
-const createReader = async (path, format, nativeMount, signal) => {
-    switch (format) {
-        case "directory":
-            return new DirectoryArtifactReader(path);
-        case "zip":
-        case "ipa":
-        case "apk":
-            return new ZipArtifactReader(path, format);
-        case "asar":
-            return new AsarArtifactReader(path);
-        case "mach-o-universal":
-            return process.platform === "darwin"
-                ? new MachOSliceArtifactReader(path)
-                : undefined;
-        case "dmg":
-            if (!nativeMount.nativeMountApproved)
-                return undefined;
-            if (!nativeMount.nativeMountEnabled)
-                throw new ArtifactReaderFailure("unavailable", "Native DMG mounting is disabled by operator policy");
-            return NativeDmgArtifactReader.create(path, signal);
-        default:
-            return undefined;
-    }
-};
-const visitNestedAsar = async (adapterKey, logicalPath, visit) => {
-    const nested = new AsarArtifactReader(adapterKey);
-    try {
-        await visit(nested, logicalPath);
-    }
-    finally {
-        await nested.close();
-    }
-};
-const isExpandableAsar = (entry, logicalPath) => entry.kind === "file" &&
-    logicalPath.toLowerCase().endsWith(".asar") &&
-    entry.adapterKey.startsWith("/");
-const emptyScan = () => ({ nodes: new Map(), occurrences: [], pendingContradictions: [] });
-const scanReader = async (reader, limits, signal, integrity = STRICT_INTEGRITY_POLICY) => {
-    const { nodes, occurrences, pendingContradictions } = emptyScan();
-    if (reader === undefined)
-        return { nodes, occurrences, pendingContradictions };
-    const occurrenceByPath = new Map();
-    const registry = new ArtifactPathRegistry();
-    let totalBytes = 0;
-    const digestEntry = async (currentReader, entry, logicalPath) => {
-        if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)
-            return undefined;
-        const remainingBytes = limits.maxTotalBytes - totalBytes;
-        if (remainingBytes <= 0)
-            throw new ArtifactReaderFailure("limit", "Artifact total byte limit exceeded");
-        if (entry.declaredSize !== null && entry.declaredSize > remainingBytes)
-            throw new ArtifactReaderFailure("limit", "Declared artifact bytes exceed remaining cumulative limit");
-        const digest = await hashReadable(await currentReader.open(entry, signal), Math.min(limits.maxEntryBytes, remainingBytes), signal);
-        totalBytes += digest.bytes;
-        const mismatched = entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256;
-        if (mismatched && integrity.mode === "fail")
-            throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`, undefined, {
-                logicalPath,
-                declaredSha256: entry.declaredSha256,
-                calculatedSha256: digest.sha256,
-                unpacked: entry.unpacked,
-            });
-        if (mismatched && entry.declaredSha256 !== null) {
-            if (pendingContradictions.length >= integrity.maxMismatches)
-                throw new ArtifactReaderFailure("limit", "Artifact integrity mismatch limit exceeded");
-            pendingContradictions.push({
-                logicalPath,
-                declaredSha256: entry.declaredSha256,
-                observedSha256: digest.sha256,
-                entryKind: entry.kind,
-                unpacked: entry.unpacked,
-            });
-        }
-        const classified = entry.kind === "slice"
-            ? { kind: "universal-slice", format: "mach-o" }
-            : classifyArtifactContent(logicalPath, digest.prefix);
-        return {
-            node: createArtifactNode({
-                sha256: digest.sha256,
-                size: digest.bytes,
-                kind: classified.kind,
-                format: classified.format,
-                executable: entry.executable,
-                contentState: "embedded",
-                limitations: mismatched
-                    ? [
-                        "Observed content contradicts declared integrity metadata and is untrusted.",
-                    ]
-                    : [],
-            }),
-            mismatched,
-        };
-    };
-    const visit = async (currentReader, prefix) => {
-        for await (const entry of currentReader.entries(signal)) {
-            if (occurrences.length >= limits.maxEntries)
-                throw new ArtifactReaderFailure("limit", "Artifact entry limit exceeded");
-            const logicalPath = normalizeArtifactPath(prefix.length === 0 ? entry.path : `${prefix}/${entry.path}`, limits);
-            const expandableAsar = isExpandableAsar(entry, logicalPath);
-            registry.add(logicalPath, expandableAsar ? "directory" : entry.kind);
-            preflightEntry(entry, limits);
-            const parent = nearestParent(logicalPath, occurrenceByPath);
-            const occurrence = createOccurrence(entry, logicalPath, parent?.occurrence_id ?? null);
-            const digested = await digestEntry(currentReader, entry, logicalPath);
-            if (digested !== undefined) {
-                nodes.set(digested.node.artifact_id, digested.node);
-                occurrence.artifact_id = digested.node.artifact_id;
-                occurrence.hash_status = digested.mismatched
-                    ? "mismatched"
-                    : "verified";
-                if (digested.mismatched)
-                    occurrence.limitations.push("Declared integrity metadata contradicts observed bytes.");
-            }
-            occurrences.push(occurrence);
-            occurrenceByPath.set(logicalPath, occurrence);
-            if (expandableAsar && digested?.mismatched !== true)
-                await visitNestedAsar(entry.adapterKey, logicalPath, visit);
-        }
-    };
-    await visit(reader, "");
-    return { nodes, occurrences, pendingContradictions };
-};
-const classifyRoot = async (path, directory) => {
-    if (directory)
-        return "directory";
-    const extensionFormat = classifyContainerExtension(path);
-    if (extensionFormat !== undefined)
-        return extensionFormat;
-    const handle = await open(path, "r");
-    try {
-        const magic = Buffer.alloc(4);
-        const observed = await handle.read(magic, 0, magic.length, 0);
-        if (observed.bytesRead === 4 &&
-            magic[0] === 0x50 &&
-            magic[1] === 0x4b &&
-            [0x03, 0x05, 0x07].includes(magic[2] ?? -1) &&
-            [0x04, 0x06, 0x08].includes(magic[3] ?? -1))
-            return "zip";
-        if (observed.bytesRead === 4) {
-            const header = magic.readUInt32BE(0);
-            if ([0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(header))
-                return "mach-o-universal";
-            if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(header))
-                return "mach-o";
-            if (magic.equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
-                return "elf";
-        }
-        if (observed.bytesRead >= 2 && magic[0] === 0x4d && magic[1] === 0x5a)
-            return "pe";
-    }
-    finally {
-        await handle.close();
-    }
-    return classifyArtifactPath(path).format;
-};
-const classifyContainerExtension = (path) => {
-    const lower = path.toLowerCase();
-    for (const format of ["asar", "ipa", "apk", "zip", "dmg", "pkg"])
-        if (lower.endsWith(`.${format}`))
-            return format;
-    return undefined;
-};
-const preflightEntry = (entry, limits) => {
-    if (entry.declaredSize !== null && entry.declaredSize > limits.maxEntryBytes)
-        throw new ArtifactReaderFailure("limit", `Entry exceeds byte limit: ${entry.path}`);
-    if (entry.declaredSize !== null &&
-        entry.compressedSize !== null &&
-        entry.compressedSize === 0 &&
-        entry.declaredSize > 0)
-        throw new ArtifactReaderFailure("limit", `Invalid compression ratio: ${entry.path}`);
-    if (entry.declaredSize !== null &&
-        entry.compressedSize !== null &&
-        entry.compressedSize > 0 &&
-        entry.declaredSize / entry.compressedSize > limits.maxCompressionRatio)
-        throw new ArtifactReaderFailure("limit", `Compression ratio exceeds limit: ${entry.path}`);
-};
-const hashReadable = async (stream, maximum, signal) => {
-    const hash = createHash("sha256");
-    const prefixes = [];
-    let prefixBytes = 0;
-    let bytes = 0;
-    for await (const raw of stream) {
-        abortIfNeeded(signal);
-        const chunk = streamChunkToBuffer(raw);
-        bytes += chunk.length;
-        if (bytes > maximum) {
-            stream.destroy();
-            throw new ArtifactReaderFailure("limit", "Observed entry bytes exceed limit");
-        }
-        hash.update(chunk);
-        if (prefixBytes < 16) {
-            const selected = chunk.subarray(0, 16 - prefixBytes);
-            prefixes.push(selected);
-            prefixBytes += selected.length;
-        }
-    }
-    return { sha256: hash.digest("hex"), bytes, prefix: Buffer.concat(prefixes) };
-};
-const abortIfNeeded = (signal) => {
-    if (signal?.aborted === true)
-        throw new ArtifactReaderFailure("cancelled", "Artifact inventory cancelled");
-};

package/dist/application/AuthorizedArtifactInventory.js

@@ -4,7 +4,7 @@ import { withinRoot } from "../reference/ReferenceSourceReaderPaths.js";
 import { scanCanonicalArtifactInventory, } from "./ArtifactInventory.js";
 import { canonicalizeConfiguredRoots } from "./ConfiguredRoots.js";
 /** Resolve, authorize, and scan one artifact without a second path resolution. */
-export const scanAuthorizedArtifactInventory = async (inputPath, roots, limits, signal, integrity) => {
+export const scanAuthorizedArtifactInventory = async (inputPath, roots, limits, options = {}) => {
     if (roots.length === 0)
         throw new ArtifactReaderFailure("path", "Artifact input roots are disabled");
     const [path, approved] = await Promise.all([
@@ -13,5 +13,5 @@ export const scanAuthorizedArtifactInventory = async (inputPath, roots, limits,
     ]);
     if (!approved.some((root) => withinRoot(root, path)))
         throw new ArtifactReaderFailure("path", "Artifact path is outside approved input roots");
-    return scanCanonicalArtifactInventory(path, limits, signal, undefined, integrity);
+    return scanCanonicalArtifactInventory(path, limits, options);
 };