rea-agents 1.1.0 → 1.2.0

package/README.md

@@ -199,6 +199,7 @@ Uninstall preserves Hopper, Node.js, evidence, captures, external evidence roots
 | Inspect or decompile one part of an app from the Terminal | `rea analyze` or `rea decompile`                               |
 | Validate, canonicalize, or compare Evidence v2 bundles    | `rea evidence-import`, `rea evidence-export`, or `rea compare` |
 | Import source as historical reference                     | `rea import-reference-source`                                  |
+| Capture or compare controlled process behavior            | `rea capture-process` or `rea compare-process-captures`        |
 
 Filesystem evidence commands and MCP file tools are disabled until the operator approves absolute roots:
 
@@ -267,12 +268,12 @@ The public interface describes what the agent is trying to learn. Providers deci
 REA is already useful for native application investigation on macOS:
 
 - Open Mach-O, ELF, PE, `.app`, ZIP, APK, IPA, ASAR, plist, JavaScript, source-map, and Hopper database targets.
-- Traverse content-addressed artifact graphs without extraction; materialize only approved occurrences into absent output roots.
+- Traverse content-addressed artifact graphs without extraction; on macOS, read-only DMG traversal additionally requires `native_mount_approved: true` and `REA_ARTIFACT_NATIVE_MOUNT_ENABLED=true`. Materialize only approved occurrences into absent output roots.
 - Build bounded function dossiers with pseudocode, assembly, CFG edges, comments, calls, references, strings, and names.
 - Search and trace features across symbols, strings, metadata, references, and call paths.
 - Record every successful result as deterministic Evidence v2 with artifact and provider identity, confidence, authority, limitations, and locations.
 - Export and import evidence bundles across sessions.
-- Capture approved PTY scenarios, child processes, filesystem changes, and loopback HTTP/WebSocket exchanges, then compare normalized captures.
+- Capture approved PTY scenarios as Process Capture v4 Evidence, including committed run manifests, raw and rendered terminal frames, scripted interactions, descendant settlement, named filesystem checkpoints, deterministic command shims, and loopback HTTP/WebSocket exchanges.
 - Compare complete artifact inventories by stable path, content, metadata, and relations; incomplete evidence never implies equivalence.
 - Compare explicit function dossiers across text, calls, references, strings, and address-normalized CFG topology with per-facet unknowns.
 - Compare canonical Evidence bundles by exact membership, explicit observation pairs, and residual-unknown histories without turning omissions into behavioral absence.
@@ -389,10 +390,28 @@ environment allowlist in `REA_PROCESS_ALLOWED_ENV_JSON`. Because the current PTY
 adapter uses host networking, it also requires
 `REA_PROCESS_ALLOW_EXTERNAL_NETWORK=true`.
 
+Capture a scenario or compare two saved Process Capture v4 Evidence records:
+
+```bash
+rea capture-process ./scenario.json > authority.json
+rea capture-process ./reconstruction.json > reconstruction.json
+rea compare-process-captures authority.json reconstruction.json
+```
+
+The comparison reports each observed dimension separately and identifies the
+first terminal, interaction, exit, filesystem, protocol, process, or shim
+divergence. See [Process Capture v4](docs/process-capture.md) for scenario
+fields, command-shim replay, checkpoint triggers, limits, and safety behavior.
+
 If the native PTY backend is unavailable, install Xcode command-line tools and
 run `npm run rebuild:native`. Linux source builds require Python, `make`, and a
 C++ toolchain. Compatible packaged binaries do not require this rebuild.
 
+ASAR inventory verifies Electron integrity metadata for both archive entries
+and `.asar.unpacked` companion files. Integrity failures identify the logical
+path, declared and calculated SHA-256 values, and whether the entry was
+unpacked; REA does not silently accept the mismatched artifact.
+
 ## Security model
 
 REA does not provide a hosted analysis service. Hopper communication uses an authenticated private local socket. Dynamic capabilities are disabled by default and require both operator policy and explicit per-call approval. REA is not a security sandbox: providers and launched targets run with the current user's permissions, and each capability reports its side effects and limitations. Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md).

package/dist/application/ArtifactInventory.js

@@ -7,16 +7,21 @@ 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 { artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
 import { classifyArtifactPath, classifyArtifactContent, createArtifactEdges, createArtifactNode, createOccurrence, createRootNode, digestCanonical, materializeDirectoryNodes, nearestParent, pageOf, rekeyOccurrences, rootOccurrenceFor, toOutputLimits, } from "./ArtifactGraphConstruction.js";
+const NATIVE_MOUNT_DISABLED = {
+    nativeMountApproved: false,
+    nativeMountEnabled: false,
+};
 /** Inventory one local artifact without extracting or mounting it. */
-export const inventoryArtifact = async (inputPath, limits, page, signal) => {
-    const snapshot = await scanArtifactInventory(inputPath, limits, signal);
+export const inventoryArtifact = async (inputPath, limits, page, options = {}) => {
+    const snapshot = await scanArtifactInventory(inputPath, limits, options.signal, options.nativeMount ?? NATIVE_MOUNT_DISABLED);
     return paginateArtifactInventory(snapshot, page);
 };
 /** Scan an artifact once and retain the complete immutable graph for projection. */
-export const scanArtifactInventory = async (inputPath, limits, signal) => {
+export const scanArtifactInventory = async (inputPath, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED) => {
     abortIfNeeded(signal);
     const path = await realpath(inputPath);
     const metadata = await lstat(path);
@@ -24,7 +29,7 @@ export const scanArtifactInventory = async (inputPath, limits, signal) => {
     const rootDigest = metadata.isDirectory()
         ? null
         : await hashReadable(createReadStream(path), limits.maxTotalBytes, signal);
-    const reader = await createReader(path, rootFormat);
+    const reader = await createReader(path, rootFormat, nativeMount, signal);
     try {
         const { nodes, occurrences } = await scanReader(reader, limits, signal);
         materializeDirectoryNodes(occurrences, nodes);
@@ -104,7 +109,7 @@ const inventoryLimitations = (format, reader) => {
         return ["Universal Mach-O slices require the native macOS lipo adapter."];
     return ["Artifact has no child container entries."];
 };
-const createReader = async (path, format) => {
+const createReader = async (path, format, nativeMount, signal) => {
     switch (format) {
         case "directory":
             return new DirectoryArtifactReader(path);
@@ -118,57 +123,88 @@ const createReader = async (path, format) => {
             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: [] });
 const scanReader = async (reader, limits, signal) => {
-    const nodes = new Map();
-    const occurrences = [];
+    const { nodes, occurrences } = emptyScan();
     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",
+    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;
+        if (entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256)
+            throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`, undefined, {
+                logicalPath,
+                declaredSha256: entry.declaredSha256,
+                calculatedSha256: digest.sha256,
+                unpacked: entry.unpacked,
             });
-            nodes.set(node.artifact_id, node);
-            occurrence.artifact_id = node.artifact_id;
-            occurrence.hash_status = "verified";
+        const classified = entry.kind === "slice"
+            ? { kind: "universal-slice", format: "mach-o" }
+            : classifyArtifactContent(logicalPath, digest.prefix);
+        return createArtifactNode({
+            sha256: digest.sha256,
+            size: digest.bytes,
+            kind: classified.kind,
+            format: classified.format,
+            executable: entry.executable,
+            contentState: "embedded",
+        });
+    };
+    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 node = await digestEntry(currentReader, entry, logicalPath);
+            if (node !== undefined) {
+                nodes.set(node.artifact_id, node);
+                occurrence.artifact_id = node.artifact_id;
+                occurrence.hash_status = "verified";
+            }
+            occurrences.push(occurrence);
+            occurrenceByPath.set(logicalPath, occurrence);
+            if (expandableAsar)
+                await visitNestedAsar(entry.adapterKey, logicalPath, visit);
         }
-        occurrences.push(occurrence);
-        occurrenceByPath.set(logicalPath, occurrence);
-    }
+    };
+    await visit(reader, "");
     return { nodes, occurrences };
 };
 const classifyRoot = async (path, directory) => {

package/dist/application/CommandShimReplay.js

@@ -0,0 +1,136 @@
+import { createServer } from "node:http";
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const RUNNER = `const command = process.argv[2];
+const response = await fetch(process.env.REA_SHIM_LEDGER_URL, {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ command, arguments: process.argv.slice(3), working_directory: process.cwd() }),
+});
+if (!response.ok) process.exit(127);
+const route = await response.json();
+let elapsed = 0;
+for (const output of route.outputs) {
+  const wait = Math.max(0, output.at_ms - elapsed);
+  if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+  elapsed = output.at_ms;
+  (output.stream === "stdout" ? process.stdout : process.stderr).write(output.data);
+}
+if (route.termination.type === "signal") process.kill(process.pid, route.termination.signal);
+else process.exit(route.termination.code);
+`;
+const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
+/**
+ * Start bounded executable replay wrappers and their private invocation ledger.
+ *
+ * Exact argument matching is deliberate: a fallback to the host executable
+ * would make an unmatched dependency call look authoritative. Unmatched and
+ * exhausted routes therefore fail visibly and remain part of the capture.
+ */
+export const startCommandShimReplay = async (scenario, temporaryRoot, started) => {
+    const binPath = join(temporaryRoot, "shims");
+    await mkdir(binPath);
+    const runnerPath = join(temporaryRoot, "shim-runner.mjs");
+    await writeFile(runnerPath, RUNNER, { mode: 0o600, flag: "wx" });
+    for (const shim of scenario.command_shims) {
+        const path = join(binPath, shim.name);
+        const wrapper = `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(runnerPath)} ${shellQuote(shim.name)} "$@"\n`;
+        await writeFile(path, wrapper, { mode: 0o700, flag: "wx" });
+        await chmod(path, 0o700);
+    }
+    const events = [];
+    let truncated = false;
+    const calls = new Map();
+    const server = createServer((request, response) => {
+        if (request.method !== "POST" || request.url !== "/invoke") {
+            response.writeHead(404).end();
+            return;
+        }
+        readInvocation(request)
+            .then((invocation) => {
+            const shim = scenario.command_shims.find(({ name }) => name === invocation.command);
+            const routeIndex = shim?.routes.findIndex(({ arguments: expected }) => JSON.stringify(expected) === JSON.stringify(invocation.arguments));
+            const key = `${invocation.command}:${String(routeIndex ?? -1)}`;
+            const used = calls.get(key) ?? 0;
+            const route = shim !== undefined && routeIndex !== undefined && routeIndex >= 0
+                ? shim.routes[routeIndex]
+                : undefined;
+            const outcome = route === undefined
+                ? "unmatched"
+                : used >= route.max_calls
+                    ? "exhausted"
+                    : "matched";
+            if (events.length >= scenario.limits.protocol_events)
+                truncated = true;
+            else
+                events.push({
+                    sequence: events.length,
+                    at_ms: Math.max(0, Date.now() - started),
+                    command: invocation.command,
+                    route_index: routeIndex !== undefined && routeIndex >= 0 ? routeIndex : null,
+                    arguments: invocation.arguments,
+                    working_directory: invocation.working_directory,
+                    outcome,
+                });
+            if (outcome !== "matched" || route === undefined) {
+                response.writeHead(409).end();
+                return;
+            }
+            calls.set(key, used + 1);
+            response
+                .writeHead(200, { "content-type": "application/json" })
+                .end(JSON.stringify(route));
+        })
+            .catch(() => response.writeHead(400).end());
+    });
+    await listen(server);
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        await closeServer(server);
+        throw new Error("command shim ledger did not bind an IPv4 port");
+    }
+    return {
+        binPath,
+        url: `http://127.0.0.1:${String(address.port)}/invoke`,
+        events,
+        get truncated() {
+            return truncated;
+        },
+        close: () => closeServer(server),
+    };
+};
+const readInvocation = async (request) => {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > 64 * 1024)
+            throw new Error("shim invocation exceeds limit");
+        chunks.push(buffer);
+    }
+    const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    if (typeof value !== "object" ||
+        value === null ||
+        !("command" in value) ||
+        typeof value.command !== "string" ||
+        !("arguments" in value) ||
+        !Array.isArray(value.arguments) ||
+        !value.arguments.every((item) => typeof item === "string") ||
+        !("working_directory" in value) ||
+        typeof value.working_directory !== "string")
+        throw new Error("invalid shim invocation");
+    return {
+        command: value.command,
+        arguments: value.arguments,
+        working_directory: value.working_directory,
+    };
+};
+const listen = (server) => new Promise((resolveListen, rejectListen) => {
+    server.once("error", rejectListen);
+    server.listen(0, "127.0.0.1", () => {
+        server.off("error", rejectListen);
+        resolveListen();
+    });
+});
+const closeServer = (server) => new Promise((resolveClose, rejectClose) => server.close((cause) => cause === undefined ? resolveClose() : rejectClose(cause)));

package/dist/application/EvidenceBundleFiles.js

@@ -4,6 +4,7 @@ import writeFileAtomic from "write-file-atomic";
 import { parseEvidenceBundle, serializeEvidenceBundle, } from "../domain/evidenceBundle.js";
 import { EvidenceFileError, EvidenceIntegrityError } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
+import { LEGACY_PROCESS_CAPTURE_MESSAGE, parseProcessCapture, } from "../domain/processCapture.js";
 /** Read and validate a bounded evidence bundle inside an approved root. */
 export const readEvidenceBundle = async (path, policy) => {
     if (policy.roots.length === 0)
@@ -31,7 +32,14 @@ export const readEvidenceBundle = async (path, policy) => {
         if (!limits.ok)
             return limits;
         try {
-            return ok(parseEvidenceBundle(decoded));
+            const bundle = parseEvidenceBundle(decoded);
+            for (const record of bundle.records) {
+                if (record.predicate_type === "rea.process-capture/v3")
+                    throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);
+                if (record.predicate_type === "rea.process-capture/v4")
+                    parseProcessCapture(record.normalized_result);
+            }
+            return ok(bundle);
         }
         catch (cause) {
             return err(new EvidenceIntegrityError("Evidence bundle validation failed", {

package/dist/application/ProcessCaptureAuthority.js

@@ -0,0 +1,25 @@
+import { realpath } from "node:fs/promises";
+import { ProcessCaptureError } from "./ProcessCaptureError.js";
+const isWithin = (candidate, root) => candidate === root ||
+    candidate.startsWith(`${root.endsWith("/") ? root.slice(0, -1) : root}/`);
+export const assertRealPathAuthority = async (scenario, policy) => {
+    const executable = await realpath(scenario.executable);
+    const executableRoots = await Promise.all(policy.executableRoots.map((root) => realpath(root)));
+    if (!executableRoots.some((root) => isWithin(executable, root)))
+        throw new ProcessCaptureError("resolved executable is outside approved roots");
+    const workingDirectory = await realpath(scenario.working_directory);
+    const workingRoots = await Promise.all(policy.workingRoots.map((root) => realpath(root)));
+    if (!workingRoots.some((root) => isWithin(workingDirectory, root)))
+        throw new ProcessCaptureError("resolved working directory is outside approved roots");
+    for (const root of scenario.filesystem_roots) {
+        const resolvedRoot = await realpath(root);
+        if (!workingRoots.some((approved) => isWithin(resolvedRoot, approved)))
+            throw new ProcessCaptureError("resolved filesystem root is outside approved roots");
+    }
+};
+/** Expected refusal or runtime failure from the process capture adapter. */
+export const assertNotCancelled = (signal) => {
+    if (signal?.aborted === true)
+        throw new ProcessCaptureError("process capture was cancelled");
+};
+/** Runtime availability of the native PTY adapter on this host. */

package/dist/application/ProcessCaptureCapability.js

@@ -0,0 +1,23 @@
+import { tmpdir } from "node:os";
+import { spawn } from "node-pty";
+/** Probe the actual native PTY seam instead of inferring support from the OS name. */
+export const probeProcessCaptureCapability = async () => {
+    try {
+        const terminal = spawn(process.platform === "win32" ? "cmd.exe" : "/bin/sh", process.platform === "win32" ? ["/c", "exit", "0"] : ["-c", "exit 0"], {
+            cwd: tmpdir(),
+            env: { HOME: tmpdir(), TERM: "xterm-256color" },
+            cols: 80,
+            rows: 24,
+            name: "xterm-256color",
+        });
+        await new Promise((resolveExit) => terminal.onExit(() => resolveExit()));
+        return { available: true, backend: "node-pty" };
+    }
+    catch {
+        return {
+            available: false,
+            backend: "node-pty",
+            reason: "the native PTY backend could not start a probe process",
+        };
+    }
+};

package/dist/application/ProcessCaptureError.js

@@ -0,0 +1,5 @@
+import { AnalysisError } from "../domain/errors.js";
+/** Typed application failure produced by controlled process capture. */
+export class ProcessCaptureError extends AnalysisError {
+    _tag = "ProcessCaptureError";
+}