rea-agents 1.7.0 → 2.1.0

package/dist/application/ArtifactInventory/hash.js

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+import { ArtifactReaderFailure, } from "../../artifacts/ArtifactReader.js";
+import { streamChunkToBuffer } from "../../artifacts/StreamBytes.js";
+export const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "Artifact inventory cancelled");
+};
+export 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}`);
+};
+export 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) };
+};

package/dist/application/ArtifactInventory/reader.js

@@ -0,0 +1,41 @@
+import { AsarArtifactReader } from "../../artifacts/AsarArtifactReader.js";
+import { ArtifactReaderFailure, } from "../../artifacts/ArtifactReader.js";
+import { DirectoryArtifactReader } from "../../artifacts/DirectoryArtifactReader.js";
+import { MachOSliceArtifactReader } from "../../artifacts/MachOSliceArtifactReader.js";
+import { NativeDmgArtifactReader } from "../../artifacts/NativeDmgArtifactReader.js";
+import { ZipArtifactReader } from "../../artifacts/ZipArtifactReader.js";
+export 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;
+    }
+};
+export 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."];
+};

package/dist/application/ArtifactInventory/scanCanonical.js

@@ -0,0 +1,155 @@
+import { createReadStream } from "node:fs";
+import { lstat } from "node:fs/promises";
+import { ArtifactReaderFailure, } from "../../artifacts/ArtifactReader.js";
+import { artifactInventoryResultSchema, } from "../../domain/artifactGraph.js";
+import { createArtifactEdges, createRootNode, digestCanonical, indexOccurrencesByPath, materializeDirectoryNodes, rekeyOccurrences, rootOccurrenceFor, toOutputLimits, } from "../ArtifactGraphConstruction.js";
+import { classifyRoot } from "./classify.js";
+import { hashReadable } from "./hash.js";
+import { createReader, inventoryLimitations } from "./reader.js";
+import { scanReader, } from "./scanReader.js";
+import { NATIVE_MOUNT_DISABLED, STRICT_INTEGRITY_POLICY, } from "./types.js";
+export const scanCanonicalArtifactInventory = async (path, limits, options = {}) => {
+    const integrity = options.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, options.signal);
+    const reader = await createReader(path, rootFormat, options.nativeMount ?? NATIVE_MOUNT_DISABLED, options.signal);
+    try {
+        const { nodes, occurrences, pendingContradictions } = await scanReader(reader, limits, options.signal, integrity);
+        return await buildInventorySnapshot({
+            path,
+            metadata,
+            rootFormat,
+            rootDigest,
+            reader,
+            limits,
+            signal: options.signal,
+            nodes,
+            occurrences,
+            pendingContradictions,
+        });
+    }
+    finally {
+        await reader?.close();
+    }
+};
+const buildInventorySnapshot = async (input) => {
+    const { path, metadata, rootFormat, rootDigest, reader, limits, signal } = input;
+    materializeDirectoryNodes(input.occurrences, input.nodes);
+    const rootNode = createRootNode({
+        path,
+        format: rootFormat,
+        directory: metadata.isDirectory(),
+        digest: rootDigest,
+        occurrences: input.occurrences,
+    });
+    input.nodes.set(rootNode.artifact_id, rootNode);
+    rekeyOccurrences(rootNode.artifact_id, input.occurrences);
+    const rootOccurrence = rootOccurrenceFor(rootNode, metadata.size);
+    for (const occurrence of input.occurrences)
+        if (occurrence.parent_occurrence_id === null)
+            occurrence.parent_occurrence_id = rootOccurrence.occurrence_id;
+    input.occurrences.unshift(rootOccurrence);
+    const occurrenceById = new Map(input.occurrences.map((occurrence) => [
+        occurrence.occurrence_id,
+        occurrence,
+    ]));
+    const occurrenceByPath = indexOccurrencesByPath(input.occurrences);
+    const integrityContradictions = buildIntegrityContradictions(input.pendingContradictions, occurrenceByPath, occurrenceById, rootNode);
+    const edges = createArtifactEdges(rootNode.artifact_id, input.occurrences, reader?.provenance()[0]);
+    const orderedNodes = sortNodes([...input.nodes.values()]);
+    const orderedOccurrences = sortOccurrences(input.occurrences);
+    const orderedEdges = sortEdges(edges);
+    await verifyRootDigest(path, rootDigest, limits.maxTotalBytes, signal);
+    const graphSha256 = digestCanonical({
+        nodes: orderedNodes,
+        occurrences: orderedOccurrences,
+        edges: orderedEdges,
+        integrity_contradictions: integrityContradictions,
+    });
+    const manifest = buildManifest({
+        rootNode,
+        graphSha256,
+        orderedNodes,
+        orderedOccurrences,
+        orderedEdges,
+    });
+    return {
+        manifest,
+        nodes: orderedNodes,
+        occurrences: orderedOccurrences,
+        edges: orderedEdges,
+        limits: toOutputLimits(limits),
+        provenance: reader?.provenance() ?? [],
+        integrity_contradictions: integrityContradictions,
+        limitations: buildLimitations(rootFormat, reader, integrityContradictions),
+    };
+};
+const buildIntegrityContradictions = (pending, occurrenceByPath, occurrenceById, rootNode) => pending.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 verifyRootDigest = async (path, rootDigest, maxTotalBytes, signal) => {
+    if (rootDigest === null)
+        return;
+    const verified = await hashReadable(createReadStream(path), maxTotalBytes, signal);
+    if (verified.sha256 !== rootDigest.sha256 ||
+        verified.bytes !== rootDigest.bytes)
+        throw new ArtifactReaderFailure("integrity", "Root artifact changed during inventory");
+};
+const sortNodes = (nodes) => nodes.sort((left, right) => left.artifact_id.localeCompare(right.artifact_id));
+const sortOccurrences = (occurrences) => occurrences.sort((left, right) => left.logical_path.localeCompare(right.logical_path, "en"));
+const sortEdges = (edges) => edges.sort((left, right) => left.edge_id.localeCompare(right.edge_id));
+const buildManifest = ({ rootNode, graphSha256, orderedNodes, orderedOccurrences, orderedEdges, }) => artifactInventoryResultSchema.shape.manifest.parse({
+    schema_version: 1,
+    manifest_id: `agm_${digestCanonical({
+        schema_version: 1,
+        root_artifact_id: rootNode.artifact_id,
+        graph_sha256: graphSha256,
+    })}`,
+    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,
+});
+const buildLimitations = (rootFormat, reader, integrityContradictions) => [
+    ...inventoryLimitations(rootFormat, reader),
+    ...(integrityContradictions.length === 0
+        ? []
+        : [
+            `${String(integrityContradictions.length)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`,
+        ]),
+];

package/dist/application/ArtifactInventory/scanReader.js

@@ -0,0 +1,124 @@
+import { ArtifactPathRegistry, normalizeArtifactPath, } from "../../artifacts/ArtifactPaths.js";
+import { ArtifactReaderFailure, } from "../../artifacts/ArtifactReader.js";
+import { AsarArtifactReader } from "../../artifacts/AsarArtifactReader.js";
+import { classifyArtifactContent, createArtifactNode, createOccurrence, nearestParent, } from "../ArtifactGraphConstruction.js";
+import { STRICT_INTEGRITY_POLICY, } from "./types.js";
+import { hashReadable, preflightEntry } from "./hash.js";
+const UNAVAILABLE_UNPACKED_LIMITATION = "ASAR unpacked companion bytes were unavailable; no content hash or child artifact was produced.";
+const emptyScan = () => ({ nodes: new Map(), occurrences: [], pendingContradictions: [] });
+export const scanReader = async (reader, limits, signal, integrity = STRICT_INTEGRITY_POLICY) => {
+    const { nodes, occurrences, pendingContradictions } = emptyScan();
+    if (reader === undefined)
+        return { nodes, occurrences, pendingContradictions };
+    const context = {
+        reader,
+        limits,
+        signal,
+        integrity,
+        nodes,
+        occurrences,
+        pendingContradictions,
+        occurrenceByPath: new Map(),
+        registry: new ArtifactPathRegistry(),
+        totalBytes: 0,
+    };
+    await visitArtifactEntries(context, reader, "");
+    return { nodes, occurrences, pendingContradictions };
+};
+const visitArtifactEntries = async (context, currentReader, prefix) => {
+    for await (const entry of currentReader.entries(context.signal)) {
+        if (context.occurrences.length >= context.limits.maxEntries)
+            throw new ArtifactReaderFailure("limit", "Artifact entry limit exceeded");
+        const logicalPath = normalizeArtifactPath(prefix.length === 0 ? entry.path : `${prefix}/${entry.path}`, context.limits);
+        const expandableAsar = isExpandableAsar(entry, logicalPath);
+        context.registry.add(logicalPath, expandableAsar ? "directory" : entry.kind);
+        preflightEntry(entry, context.limits);
+        const parent = nearestParent(logicalPath, context.occurrenceByPath);
+        const occurrence = createOccurrence(entry, logicalPath, parent?.occurrence_id ?? null);
+        let digested;
+        try {
+            digested = await digestArtifactEntry(context, currentReader, entry, logicalPath);
+        }
+        catch (cause) {
+            if (!isUnavailableUnpackedEntry(cause, entry))
+                throw cause;
+            occurrence.hash_status = "unavailable";
+            occurrence.limitations.push(UNAVAILABLE_UNPACKED_LIMITATION);
+        }
+        if (digested !== undefined) {
+            context.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.");
+        }
+        context.occurrences.push(occurrence);
+        context.occurrenceByPath.set(logicalPath, occurrence);
+        if (expandableAsar && digested?.mismatched !== true)
+            await visitNestedAsar(context, entry.adapterKey, logicalPath);
+    }
+};
+const digestArtifactEntry = async (context, currentReader, entry, logicalPath) => {
+    if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)
+        return undefined;
+    const remainingBytes = context.limits.maxTotalBytes - context.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, context.signal), Math.min(context.limits.maxEntryBytes, remainingBytes), context.signal);
+    context.totalBytes += digest.bytes;
+    const mismatched = entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256;
+    if (mismatched && context.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 (context.pendingContradictions.length >= context.integrity.maxMismatches)
+            throw new ArtifactReaderFailure("limit", "Artifact integrity mismatch limit exceeded");
+        context.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 visitNestedAsar = async (context, adapterKey, logicalPath) => {
+    const nested = new AsarArtifactReader(adapterKey);
+    try {
+        await visitArtifactEntries(context, nested, logicalPath);
+    }
+    finally {
+        await nested.close();
+    }
+};
+const isExpandableAsar = (entry, logicalPath) => entry.kind === "file" &&
+    logicalPath.toLowerCase().endsWith(".asar") &&
+    entry.adapterKey.startsWith("/");
+const isUnavailableUnpackedEntry = (cause, entry) => entry.unpacked &&
+    cause instanceof ArtifactReaderFailure &&
+    cause.reason === "unavailable";

package/dist/application/ArtifactInventory/types.js

@@ -0,0 +1,10 @@
+export const NATIVE_MOUNT_DISABLED = {
+    nativeMountApproved: false,
+    nativeMountEnabled: false,
+};
+export const STRICT_INTEGRITY_POLICY = {
+    mode: "fail",
+    approved: false,
+    enabled: false,
+    maxMismatches: 1,
+};