rea-agents 1.2.0 → 1.3.0

package/dist/application/EvidenceLedger.js

@@ -1,3 +1,4 @@
+import canonicalize from "canonicalize";
 import { createEvidenceBundle, parseEvidenceBundle, } from "../domain/evidenceBundle.js";
 import { EvidenceIntegrityError, EvidenceLimitError, UnknownRegistryError, } from "../domain/errors.js";
 import { parseEvidence } from "../domain/evidence.js";
@@ -258,8 +259,8 @@ export class EvidenceLedger {
 }
 const serializedBytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
 const unknownRevisionKey = (unknown) => `${unknown.unknown_id}:${String(unknown.revision)}`;
-const recordsAgree = (left, right) => JSON.stringify(withoutLocalPath(left)) ===
-    JSON.stringify(withoutLocalPath(right));
+const recordsAgree = (left, right) => canonicalize(withoutLocalPath(left)) ===
+    canonicalize(withoutLocalPath(right));
 const withoutLocalPath = (evidence) => ({
     ...evidence,
     subject: evidence.subject === null

package/dist/application/InvestigationProviders.js

@@ -0,0 +1,48 @@
+/** Provider identity for deterministic artifact inventories. */
+export const ARTIFACT_GRAPH_PROVIDER = {
+    id: "rea-artifact-graph",
+    name: "REA safe artifact graph provider",
+    version: "1",
+};
+/** Provider identity for deterministic cross-artifact comparisons. */
+export const ARTIFACT_COMPARISON_PROVIDER = {
+    id: "rea-artifact-comparison",
+    name: "REA artifact comparison",
+    version: "1",
+};
+/** Provider identity for deterministic cross-function comparisons. */
+export const FUNCTION_COMPARISON_PROVIDER = {
+    id: "rea-function-comparison",
+    name: "REA function comparison",
+    version: "1",
+};
+/** Provider identity for deterministic Evidence bundle comparisons. */
+export const BUNDLE_COMPARISON_PROVIDER = {
+    id: "rea-bundle-comparison",
+    name: "REA Evidence bundle comparison",
+    version: "1",
+};
+/** Provider identity for comparison-Evidence behavior aggregation. */
+export const CHANGED_BEHAVIOR_PROVIDER = {
+    id: "rea-changed-behavior",
+    name: "REA changed behavior investigation",
+    version: "1",
+};
+/** Provider identity for Evidence-backed call-path reconstruction. */
+export const CALL_PATH_PROVIDER = {
+    id: "rea-call-path",
+    name: "REA call path reconstruction",
+    version: "1",
+};
+/** Provider identity for explicit static/runtime hypothesis correlation. */
+export const STATIC_RUNTIME_PROVIDER = {
+    id: "rea-static-runtime-correlation",
+    name: "REA static/runtime correlation",
+    version: "1",
+};
+/** Provider identity for finite reconstruction specification verification. */
+export const RECONSTRUCTION_PROVIDER = {
+    id: "rea-reconstruction-verifier",
+    name: "REA reconstruction verifier",
+    version: "1",
+};

package/dist/application/InvestigationWorkspaceStore.js

@@ -0,0 +1,214 @@
+import { lstat, open, readFile, realpath, unlink, } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { InvestigationWorkspaceError } from "../domain/errors.js";
+import { parseInvestigationWorkspace, serializeInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
+import { err, ok } from "../domain/result.js";
+/** Read a validated workspace, returning null only when it does not exist. */
+export const readInvestigationWorkspace = async (path, policy) => {
+    if (policy.roots.length === 0)
+        return err(new InvestigationWorkspaceError("read", "disabled"));
+    try {
+        const destination = await resolveDestination(path, policy.roots);
+        if (destination === null)
+            return err(new InvestigationWorkspaceError("read", "outside-root"));
+        return await readWorkspaceFile(destination, policy);
+    }
+    catch (cause) {
+        return err(new InvestigationWorkspaceError("read", "io", { cause }));
+    }
+};
+/** Atomically append one CAS-linked workspace revision under an exclusive lock. */
+export const writeInvestigationWorkspace = async (workspace, path, expectedRevision, policy) => {
+    if (policy.roots.length === 0)
+        return err(new InvestigationWorkspaceError("update", "disabled"));
+    let encoded;
+    try {
+        encoded = serializeInvestigationWorkspace(workspace);
+    }
+    catch (cause) {
+        return err(new InvestigationWorkspaceError("update", "integrity", { cause }));
+    }
+    const bytes = Buffer.byteLength(encoded, "utf8");
+    if (bytes > policy.maxBytes)
+        return err(new InvestigationWorkspaceError("update", "too-large"));
+    let lock;
+    try {
+        const destination = await resolveDestination(path, policy.roots);
+        if (destination === null)
+            return err(new InvestigationWorkspaceError("update", "outside-root"));
+        const acquired = await acquireLock(destination);
+        if (!acquired.ok)
+            return acquired;
+        lock = acquired.value;
+        const current = await readWorkspaceFile(destination, policy);
+        if (!current.ok)
+            return current;
+        const checked = validateNextRevision(current.value, workspace, expectedRevision);
+        if (!checked.ok)
+            return checked;
+        await writeFileAtomic(destination, encoded, {
+            encoding: "utf8",
+            mode: 0o600,
+            fsync: true,
+        });
+        return ok({ path: resolve(path), bytes });
+    }
+    catch (cause) {
+        return err(new InvestigationWorkspaceError("update", "io", { cause }));
+    }
+    finally {
+        if (lock !== undefined)
+            await releaseLock(lock);
+    }
+};
+const resolveDestination = async (path, roots) => {
+    const requested = resolve(path);
+    const canonicalParent = await realpath(dirname(requested));
+    const destination = resolve(canonicalParent, basename(requested));
+    for (const configuredRoot of roots) {
+        const root = await realpath(resolve(configuredRoot));
+        const relation = relative(root, destination);
+        if (relation === "" ||
+            (!relation.startsWith("..") && !isAbsolute(relation)))
+            return destination;
+    }
+    return null;
+};
+const readWorkspaceFile = async (destination, policy) => {
+    const stats = await lstat(destination).catch((cause) => {
+        if (isFileNotFound(cause))
+            return undefined;
+        throw cause;
+    });
+    if (stats === undefined)
+        return ok(null);
+    if (!stats.isFile() || stats.isSymbolicLink())
+        return err(new InvestigationWorkspaceError("read", "not-file"));
+    if (stats.size > policy.maxBytes)
+        return err(new InvestigationWorkspaceError("read", "too-large"));
+    const encoded = await readFile(destination);
+    if (encoded.byteLength > policy.maxBytes)
+        return err(new InvestigationWorkspaceError("read", "too-large"));
+    let decoded;
+    try {
+        decoded = JSON.parse(encoded.toString("utf8"));
+    }
+    catch (cause) {
+        return err(new InvestigationWorkspaceError("read", "invalid-json", { cause }));
+    }
+    if (!withinJsonLimits(decoded, policy))
+        return err(new InvestigationWorkspaceError("read", "too-large"));
+    try {
+        return ok(parseInvestigationWorkspace(decoded));
+    }
+    catch (cause) {
+        return err(new InvestigationWorkspaceError("read", "integrity", { cause }));
+    }
+};
+const acquireLock = async (destination) => {
+    const path = `${destination}.lock`;
+    try {
+        return ok(await createLock(path));
+    }
+    catch (cause) {
+        if (isAlreadyExists(cause) && (await removeStaleLock(path))) {
+            try {
+                return ok(await createLock(path));
+            }
+            catch (retryCause) {
+                return err(new InvestigationWorkspaceError("update", isAlreadyExists(retryCause) ? "locked" : "io", { cause: retryCause }));
+            }
+        }
+        return err(new InvestigationWorkspaceError("update", isAlreadyExists(cause) ? "locked" : "io", { cause }));
+    }
+};
+const createLock = async (path) => {
+    const handle = await open(path, "wx", 0o600);
+    try {
+        await handle.writeFile(`${String(process.pid)}\n`, "utf8");
+        await handle.sync();
+        return { path, handle };
+    }
+    catch (cause) {
+        await handle.close().catch(() => undefined);
+        await unlink(path).catch(() => undefined);
+        throw cause;
+    }
+};
+const removeStaleLock = async (path) => {
+    try {
+        const stats = await lstat(path);
+        if (!stats.isFile() || stats.isSymbolicLink() || stats.size > 32)
+            return false;
+        const encoded = (await readFile(path, "utf8")).trim();
+        if (!/^[1-9][0-9]{0,9}$/u.test(encoded))
+            return false;
+        const pid = Number(encoded);
+        if (processIsAlive(pid))
+            return false;
+        await unlink(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const processIsAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (cause) {
+        return errorCode(cause) !== "ESRCH";
+    }
+};
+const releaseLock = async (lock) => {
+    await lock.handle.close().catch(() => undefined);
+    await unlink(lock.path).catch(() => undefined);
+};
+const validateNextRevision = (current, next, expectedRevision) => {
+    if ((current?.revision ?? null) !== expectedRevision)
+        return err(new InvestigationWorkspaceError("update", "revision-conflict"));
+    if (current === null) {
+        return next.revision === 1 && next.previous_revision_digest === null
+            ? ok(null)
+            : err(new InvestigationWorkspaceError("update", "revision-conflict"));
+    }
+    if (current.name !== next.name || current.workspace_id !== next.workspace_id)
+        return err(new InvestigationWorkspaceError("update", "name-conflict"));
+    return next.revision === current.revision + 1 &&
+        next.previous_revision_digest === current.revision_digest
+        ? ok(null)
+        : err(new InvestigationWorkspaceError("update", "revision-conflict"));
+};
+const withinJsonLimits = (root, policy) => {
+    const pending = [
+        { value: root, depth: 0 },
+    ];
+    let nodes = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        nodes += 1;
+        if (nodes > policy.maxNodes || current.depth > policy.maxDepth)
+            return false;
+        if (typeof current.value === "string" &&
+            current.value.length > policy.maxStringLength)
+            return false;
+        if (typeof current.value !== "object" || current.value === null)
+            continue;
+        for (const [key, value] of Object.entries(current.value)) {
+            if (key.length > policy.maxStringLength)
+                return false;
+            pending.push({ value, depth: current.depth + 1 });
+        }
+    }
+    return true;
+};
+const isFileNotFound = (cause) => errorCode(cause) === "ENOENT";
+const isAlreadyExists = (cause) => errorCode(cause) === "EEXIST";
+const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
+    ? cause.code
+    : undefined;

package/dist/application/LinuxHopper.js

@@ -1,14 +1,31 @@
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
+import { createReadStream } from "node:fs";
 import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
-import { z } from "zod";
 const execFileAsync = promisify(execFile);
-const RELEASES_URL = "https://www.hopperapp.com/include/files-api.php?request=releases&public=true";
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
 const MAX_PACKAGE_BYTES = 100_000_000;
+const SUPPORTED_HOPPER_SHA256 = "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded";
+const SUPPORTED_RELEASES = {
+    deb: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.deb`,
+        file_length: "35755772",
+        file_hash: "e4f79dff602648a8ff4a88b773875b6bfac0dc65",
+    },
+    rpm: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.rpm`,
+        file_length: "32264475",
+        file_hash: "b9a65f2f583a386d440d4401d9140aef3bf305de",
+    },
+    arch: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.pkg.tar.xz`,
+        file_length: "29405968",
+        file_hash: "92d780b61cab38eda95dc4112dee4fbeb0920f46",
+    },
+};
 /** Parse an os-release document without executing its shell syntax. */
 export const parseLinuxDistribution = (text) => {
     const fields = new Map();
@@ -57,15 +74,7 @@ export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(),
         return { status: "failed", reason: "unsupported_host" };
     let temporary;
     try {
-        const metadataDownload = await host.download(RELEASES_URL, options);
-        if (!metadataDownload.ok)
-            return { status: "failed", reason: "release_metadata" };
-        const releases = parseReleases(metadataDownload.bytes);
-        if (releases === undefined)
-            return { status: "failed", reason: "release_metadata" };
-        const release = releases[releaseKey(distribution.packageFamily)];
-        if (!release.filename.startsWith(DOWNLOAD_PREFIX))
-            return { status: "failed", reason: "release_metadata" };
+        const release = (options.releases ?? SUPPORTED_RELEASES)[distribution.packageFamily];
         const archiveDownload = await host.download(release.filename, options);
         if (!archiveDownload.ok)
             return { status: "failed", reason: "download" };
@@ -77,8 +86,12 @@ export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(),
         if (!(await host.installPackage(distribution.packageFamily, archive)))
             return { status: "failed", reason: "authorization_or_package_manager" };
         const launcherPath = "/opt/hopper/bin/Hopper";
-        if (!(await host.launcherReady(launcherPath)))
-            return { status: "failed", reason: "launcher_missing" };
+        const launcherStatus = await host.launcherStatus(launcherPath);
+        if (launcherStatus !== "ready")
+            return {
+                status: "failed",
+                reason: launcherStatus === "missing" ? "launcher_missing" : launcherStatus,
+            };
         return { status: "installed", launcherPath };
     }
     catch (cause) {
@@ -108,24 +121,40 @@ const systemLinuxHopperInstallHost = () => ({
     createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-")),
     writeArchive: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
     installPackage: installSystemPackage,
-    async launcherReady(path) {
+    async launcherStatus(path) {
         try {
             await access(path);
             const linked = await execFileAsync("ldd", [path]);
-            return linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`);
+            if (!linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`))
+                return "runtime_dependencies";
+            return (await linuxHopperBinarySupported(path))
+                ? "ready"
+                : "unsupported_hopper_build";
         }
         catch {
-            return false;
+            return "missing";
         }
     },
     cleanup: (path) => rm(path, { recursive: true, force: true }),
 });
+/** Match the Linux Hopper build validated by the packaged demo-dialog adapter. */
+export const linuxHopperBinarySupported = async (path) => {
+    try {
+        const hash = createHash("sha256");
+        for await (const chunk of createReadStream(path))
+            hash.update(chunk);
+        return hash.digest("hex") === SUPPORTED_HOPPER_SHA256;
+    }
+    catch {
+        return false;
+    }
+};
 /** Interpret ldd output conservatively so a present but broken launcher is unhealthy. */
 export const linuxSharedLibrariesAvailable = (output) => !/(?:=>\s+not found|error while loading shared libraries)/iu.test(output);
 const installSystemPackage = async (family, archive) => {
     try {
-        const command = linuxPackageManagerCommand(family, archive, process.getuid?.() === 0);
-        await execFileAsync(command.executable, command.args);
+        for (const command of linuxPackageManagerCommands(family, archive, process.getuid?.() === 0))
+            await execFileAsync(command.executable, command.args);
         return true;
     }
     catch {
@@ -133,26 +162,32 @@ const installSystemPackage = async (family, archive) => {
     }
 };
 /** Select the native package manager and authorization boundary without shell evaluation. */
-export const linuxPackageManagerCommand = (family, archive, isRoot) => {
-    const command = family === "deb"
-        ? ["apt-get", "install", "-y", archive]
+export const linuxPackageManagerCommands = (family, archive, isRoot) => {
+    const runtimeDependencies = family === "deb"
+        ? ["xvfb", "xauth", "python3", "libx11-6", "libxtst6"]
         : family === "rpm"
-            ? ["dnf", "install", "-y", archive]
-            : ["pacman", "-U", "--noconfirm", archive];
-    const executable = isRoot ? command[0] : "pkexec";
-    if (executable === undefined)
-        throw new Error("package command is empty");
-    return { executable, args: isRoot ? command.slice(1) : command };
-};
-const parseReleases = (bytes) => {
-    try {
-        const parsed = JSON.parse(new TextDecoder().decode(bytes));
-        const result = releasesSchema.safeParse(parsed);
-        return result.success ? result.data : undefined;
-    }
-    catch {
-        return undefined;
-    }
+            ? [
+                "xorg-x11-server-Xvfb",
+                "xorg-x11-xauth",
+                "python3",
+                "libX11",
+                "libXtst",
+            ]
+            : ["xorg-server-xvfb", "xorg-xauth", "python", "libx11", "libxtst"];
+    const commands = family === "deb"
+        ? [["apt-get", "install", "-y", archive, ...runtimeDependencies]]
+        : family === "rpm"
+            ? [["dnf", "install", "-y", archive, ...runtimeDependencies]]
+            : [
+                ["pacman", "-S", "--needed", "--noconfirm", ...runtimeDependencies],
+                ["pacman", "-U", "--noconfirm", archive],
+            ];
+    return commands.map((command) => {
+        const executable = isRoot ? command[0] : "pkexec";
+        if (executable === undefined)
+            throw new Error("package command is empty");
+        return { executable, args: isRoot ? command.slice(1) : command };
+    });
 };
 const packageIntegrityMatches = (bytes, release) => bytes.byteLength === Number(release.file_length) &&
     bytes.byteLength <= MAX_PACKAGE_BYTES &&
@@ -172,15 +207,4 @@ const packageFamilyFor = (id, idLike) => {
 };
 const versionAtLeast = (version, minimum) => version !== undefined &&
     Number.parseInt(version.split(".")[0] ?? "0", 10) >= minimum;
-const releaseKey = (family) => family === "deb" ? "Ubuntu / Mint" : family === "rpm" ? "Fedora" : "Arch";
 const isAbortCause = (cause) => cause instanceof Error && cause.name === "AbortError";
-const releaseSchema = z.object({
-    filename: z.string().url(),
-    file_length: z.string().regex(/^\d+$/u),
-    file_hash: z.string().regex(/^[a-f0-9]{40}$/u),
-});
-const releasesSchema = z.object({
-    "Ubuntu / Mint": releaseSchema,
-    Fedora: releaseSchema,
-    Arch: releaseSchema,
-});

package/dist/application/ProcessCaptureAuthority.js

@@ -1,5 +1,5 @@
 import { realpath } from "node:fs/promises";
-import { ProcessCaptureError } from "./ProcessCaptureError.js";
+import { ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
 const isWithin = (candidate, root) => candidate === root ||
     candidate.startsWith(`${root.endsWith("/") ? root.slice(0, -1) : root}/`);
 export const assertRealPathAuthority = async (scenario, policy) => {
@@ -20,6 +20,6 @@ export const assertRealPathAuthority = async (scenario, policy) => {
 /** 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");
+        throw processCaptureCancelled();
 };
 /** Runtime availability of the native PTY adapter on this host. */

package/dist/application/ProcessCaptureError.js

@@ -2,4 +2,16 @@ import { AnalysisError } from "../domain/errors.js";
 /** Typed application failure produced by controlled process capture. */
 export class ProcessCaptureError extends AnalysisError {
     _tag = "ProcessCaptureError";
+    userMessage;
+    userCategory;
+    constructor(message, options) {
+        super(message, options);
+        this.userMessage = options?.userMessage;
+        this.userCategory = options?.userCategory;
+    }
 }
+/** Caller-visible cancellation without exposing capture implementation state. */
+export const processCaptureCancelled = () => new ProcessCaptureError("process capture was cancelled", {
+    userCategory: "cancelled",
+    userMessage: "Process capture was cancelled. Start it again when ready.",
+});

package/dist/application/ProcessCaptureLifecycle.js

@@ -257,7 +257,10 @@ export const resolveProcessResult = (capture, executionFailure, cleanupFailure)
 export const prepareProcessCapture = async (scenario, policy, signal) => {
     const decision = authorizeProcessScenario(scenario, policy);
     if (!decision.allowed)
-        throw new ProcessCaptureError(decision.reason);
+        throw new ProcessCaptureError(decision.reason, {
+            userCategory: "permission_required",
+            userMessage: processPolicyMessage(decision.reason),
+        });
     await assertRealPathAuthority(scenario, policy);
     assertNotCancelled(signal);
     const before = await snapshotRoots(scenario, signal);
@@ -267,3 +270,18 @@ export const prepareProcessCapture = async (scenario, policy, signal) => {
     await import("node:fs/promises").then(({ mkdir }) => mkdir(home));
     return { temporaryRoot, runId, home, before };
 };
+const processPolicyMessage = (reason) => {
+    if (reason === "process capture is disabled")
+        return "Process capture is disabled. Set `REA_PROCESS_CAPTURE_ENABLED=true`, configure approved roots, then restart REA.";
+    if (reason === "host network access is not approved by operator policy")
+        return "This capture requests host network access, but policy does not allow it. Use replayed network access or ask the operator to enable external network capture.";
+    if (reason === "executable is outside approved roots")
+        return "The executable is outside the approved capture directories. Choose an approved executable or add its directory to `REA_PROCESS_EXECUTABLE_ROOTS_JSON`.";
+    if (reason === "working directory is outside approved roots")
+        return "The working directory is outside the approved capture directories. Choose an approved directory or add it to `REA_PROCESS_WORKING_ROOTS_JSON`.";
+    if (reason === "filesystem root is outside approved roots")
+        return "A requested filesystem root is outside the approved capture directories. Remove it or add its directory to `REA_PROCESS_WORKING_ROOTS_JSON`.";
+    if (reason === "scenario requests an environment variable not allowed by policy")
+        return "The capture requests an environment variable that policy does not allow. Remove it or add its name to `REA_PROCESS_ALLOWED_ENV_JSON`.";
+    return reason;
+};