rea-agents 0.2.1 → 0.4.0

package/dist/application/ArtifactGraphConstruction.js

@@ -0,0 +1,257 @@
+import { createHash } from "node:crypto";
+import { extname } from "node:path";
+import canonicalize from "canonicalize";
+export const createOccurrence = (entry, path, parent) => ({
+    occurrence_id: `occ_${digestCanonical({ path, kind: entry.kind })}`,
+    artifact_id: null,
+    parent_occurrence_id: parent,
+    logical_path: path,
+    entry_kind: entry.kind,
+    declared_size: entry.declaredSize,
+    compressed_size: entry.compressedSize,
+    executable: entry.executable,
+    encrypted: entry.encrypted,
+    hash_status: entry.encrypted ? "unavailable" : "not-hashed-limit",
+    source_location: entry.byteOffset === null || entry.declaredSize === null
+        ? null
+        : { offset: entry.byteOffset, length: entry.declaredSize },
+    limitations: [...entry.limitations],
+});
+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 }) => ({
+            name: logical_path.split("/").at(-1),
+            artifact_id,
+            entry_kind,
+        }))
+            .sort((left, right) => String(left.name).localeCompare(String(right.name)));
+        const node = createArtifactNode({
+            sha256: digestCanonical({ kind: "directory", children }),
+            size: 0,
+            kind: directory.logical_path.toLowerCase().endsWith(".framework")
+                ? "framework"
+                : "container",
+            format: "directory",
+            executable: false,
+            contentState: "virtual",
+        });
+        const existing = nodes.get(node.artifact_id);
+        nodes.set(node.artifact_id, existing?.kind === "framework" ? existing : node);
+        directory.artifact_id = node.artifact_id;
+        directory.hash_status = "verified";
+    }
+};
+export const createRootNode = (input) => createArtifactNode({
+    sha256: input.digest?.sha256 ??
+        digestCanonical({
+            kind: "directory-root",
+            children: input.occurrences.map(({ logical_path, artifact_id }) => ({
+                logical_path,
+                artifact_id,
+            })),
+        }),
+    size: input.digest?.bytes ?? 0,
+    kind: input.directory ||
+        ["zip", "ipa", "apk", "asar", "dmg", "pkg"].includes(input.format)
+        ? "container"
+        : classifyArtifactPath(input.path).kind,
+    format: input.format,
+    executable: false,
+    contentState: "materialized",
+});
+export const createArtifactNode = (input) => ({
+    artifact_id: `art_${digestCanonical({ schema_version: 1, sha256: input.sha256 })}`,
+    kind: input.kind,
+    format: input.format,
+    sha256: input.sha256,
+    size: input.size,
+    media_type: null,
+    architecture: null,
+    executable: input.executable,
+    content_state: input.contentState,
+    limitations: [],
+});
+export const rootOccurrenceFor = (node, declaredSize) => ({
+    occurrence_id: `occ_${digestCanonical({ root: node.artifact_id })}`,
+    artifact_id: node.artifact_id,
+    parent_occurrence_id: null,
+    logical_path: ".",
+    entry_kind: node.format === "directory" ? "directory" : "file",
+    declared_size: declaredSize,
+    compressed_size: null,
+    executable: node.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, `occ_${digestCanonical({
+            root_artifact_id: rootArtifactId,
+            logical_path: occurrence.logical_path,
+            entry_kind: 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 edges = [];
+    for (const occurrence of occurrences) {
+        if (occurrence.parent_occurrence_id === null ||
+            occurrence.artifact_id === null)
+            continue;
+        const mappedSource = occurrence.logical_path.endsWith(".map")
+            ? occurrences.find(({ logical_path: path }) => path === 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,
+            child_artifact_id: occurrence.artifact_id,
+            relation: occurrence.entry_kind === "slice"
+                ? "slice-of"
+                : relationFor(occurrence.logical_path),
+            occurrence_id: occurrence.occurrence_id,
+            logical_path: occurrence.logical_path,
+        };
+        edges.push({
+            edge_id: `edge_${digestCanonical(semantic)}`,
+            ...semantic,
+            producer: occurrence.entry_kind === "slice" ? (producer ?? null) : null,
+            ordinal: edges.length,
+        });
+    }
+    return edges;
+};
+export const nearestParent = (path, occurrences) => {
+    const parts = path.split("/");
+    while (parts.length > 1) {
+        parts.pop();
+        const candidate = occurrences.get(parts.join("/"));
+        if (candidate?.entry_kind === "directory")
+            return candidate;
+    }
+    return undefined;
+};
+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 (lower.endsWith(".asar"))
+        return { kind: "container", format: "asar" };
+    const archiveFormat = archiveFormatForExtension(extname(lower));
+    if (archiveFormat !== undefined)
+        return { kind: "container", format: archiveFormat };
+    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) => {
+    const byPath = classifyArtifactPath(path);
+    if (prefix.length >= 4) {
+        const magic = prefix.readUInt32BE(0);
+        if ([0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
+            return {
+                kind: byPath.kind === "native-addon" ? "native-addon" : "executable",
+                format: "mach-o-universal",
+            };
+        if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic))
+            return {
+                kind: ["native-addon", "dynamic-library"].includes(byPath.kind)
+                    ? byPath.kind
+                    : "executable",
+                format: "mach-o",
+            };
+        if (prefix.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
+            return {
+                kind: ["native-addon", "dynamic-library"].includes(byPath.kind)
+                    ? byPath.kind
+                    : "executable",
+                format: "elf",
+            };
+    }
+    if (prefix.length >= 2 && prefix[0] === 0x4d && prefix[1] === 0x5a)
+        return {
+            kind: byPath.kind === "native-addon" ? "native-addon" : "executable",
+            format: "pe",
+        };
+    return byPath;
+};
+export const pageOf = (items, offset, limit) => ({
+    items: items.slice(offset, offset + limit),
+    offset,
+    limit,
+    total: items.length,
+    next_offset: offset + limit < items.length ? offset + limit : null,
+});
+export const toOutputLimits = (limits) => ({
+    max_entries: limits.maxEntries,
+    max_total_bytes: limits.maxTotalBytes,
+    max_entry_bytes: limits.maxEntryBytes,
+    max_compression_ratio: limits.maxCompressionRatio,
+    max_depth: limits.maxDepth,
+    max_path_bytes: limits.maxPathBytes,
+});
+export const digestCanonical = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Artifact value is not canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const relationFor = (path) => {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".map"))
+        return "maps-source";
+    if (lower.includes(".framework/"))
+        return "embeds";
+    return "contains";
+};
+const archiveFormatForExtension = (extension) => {
+    switch (extension) {
+        case ".zip":
+            return "zip";
+        case ".ipa":
+            return "ipa";
+        case ".apk":
+            return "apk";
+        default:
+            return undefined;
+    }
+};
+const depth = (path) => path.split("/").length;

package/dist/application/ArtifactInventory.js

@@ -0,0 +1,253 @@
+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 { streamChunkToBuffer } from "../artifacts/StreamBytes.js";
+import { artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
+import { classifyArtifactPath, classifyArtifactContent, createArtifactEdges, createArtifactNode, createOccurrence, createRootNode, digestCanonical, materializeDirectoryNodes, nearestParent, pageOf, rekeyOccurrences, rootOccurrenceFor, toOutputLimits, } from "./ArtifactGraphConstruction.js";
+/** Inventory one local artifact without extracting or mounting it. */
+export const inventoryArtifact = async (inputPath, limits, page, signal) => {
+    const snapshot = await scanArtifactInventory(inputPath, limits, signal);
+    return paginateArtifactInventory(snapshot, page);
+};
+/** Scan an artifact once and retain the complete immutable graph for projection. */
+export const scanArtifactInventory = async (inputPath, limits, signal) => {
+    abortIfNeeded(signal);
+    const path = await realpath(inputPath);
+    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);
+    try {
+        const { nodes, occurrences } = await scanReader(reader, limits, signal);
+        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 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,
+        });
+        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() ?? [],
+            limitations: inventoryLimitations(rootFormat, reader),
+        };
+    }
+    finally {
+        await reader?.close();
+    }
+};
+/** Project independently paged graph collections from one inventory snapshot. */
+export const paginateArtifactInventory = (snapshot, page) => artifactInventoryResultSchema.parse({
+    ...snapshot,
+    nodes: pageOf(snapshot.nodes, page.nodeOffset, page.nodeLimit),
+    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) => {
+    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;
+        default:
+            return undefined;
+    }
+};
+const scanReader = async (reader, limits, signal) => {
+    const nodes = new Map();
+    const occurrences = [];
+    if (reader === undefined)
+        return { nodes, occurrences };
+    const occurrenceByPath = new Map();
+    const registry = new ArtifactPathRegistry();
+    let totalBytes = 0;
+    for await (const entry of reader.entries(signal)) {
+        if (occurrences.length >= limits.maxEntries)
+            throw new ArtifactReaderFailure("limit", "Artifact entry limit exceeded");
+        const logicalPath = normalizeArtifactPath(entry.path, limits);
+        registry.add(logicalPath, entry.kind);
+        preflightEntry(entry, limits);
+        const parent = nearestParent(logicalPath, occurrenceByPath);
+        const occurrence = createOccurrence(entry, logicalPath, parent?.occurrence_id ?? null);
+        if ((entry.kind === "file" || entry.kind === "slice") && !entry.encrypted) {
+            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 reader.open(entry, signal), Math.min(limits.maxEntryBytes, remainingBytes), signal);
+            totalBytes += digest.bytes;
+            if (entry.declaredSha256 !== null &&
+                entry.declaredSha256 !== digest.sha256)
+                throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`);
+            if (totalBytes > limits.maxTotalBytes)
+                throw new ArtifactReaderFailure("limit", "Artifact total byte limit exceeded");
+            const classified = entry.kind === "slice"
+                ? { kind: "universal-slice", format: "mach-o" }
+                : classifyArtifactContent(logicalPath, digest.prefix);
+            const node = createArtifactNode({
+                sha256: digest.sha256,
+                size: digest.bytes,
+                kind: classified.kind,
+                format: classified.format,
+                executable: entry.executable,
+                contentState: "embedded",
+            });
+            nodes.set(node.artifact_id, node);
+            occurrence.artifact_id = node.artifact_id;
+            occurrence.hash_status = "verified";
+        }
+        occurrences.push(occurrence);
+        occurrenceByPath.set(logicalPath, occurrence);
+    }
+    return { nodes, occurrences };
+};
+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");
+};