rea-agents 1.7.0 → 2.1.0

package/dist/ghidra/GhidraClient.js

@@ -1,5 +1,5 @@
 import { randomBytes, randomUUID } from "node:crypto";
-import { access } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { err, ok } from "../domain/result.js";
 import { silentLogger } from "../logger.js";
@@ -14,19 +14,23 @@ import { GhidraResponseRouter } from "./GhidraResponseRouter.js";
 import { GhidraRequestQueue } from "./GhidraRequestQueue.js";
 import { bindGhidraSessionFailure, GhidraSessionError, } from "./GhidraSessionError.js";
 import { isGhidraShutdownAcknowledgement, parseGhidraSessionInfo, } from "./GhidraSessionValues.js";
-import { attachGhidraSocket, connectGhidraSocketOnce, } from "./GhidraSocketConnection.js";
+import { createGhidraTargetSnapshot } from "./GhidraTargetSnapshot.js";
+import { connectGhidraSocket } from "./GhidraSocketConnection.js";
+import { GhidraWire } from "./GhidraClientWire.js";
+import { completeGhidraStartupHandshake } from "./GhidraClientStartup.js";
 const SHUTDOWN_TIMEOUT_MS = 10_000;
-const SESSION_ROOT = "/tmp";
+const SESSION_ROOT = tmpdir();
 /** Owns one authenticated, private, read-only Ghidra headless session. */
 export class GhidraClient {
     #options;
-    #pending = new PendingOperations();
     #logger;
+    #pending = new PendingOperations();
     #socket;
     #detachSocket;
     #launch;
     #process;
     #runtimeRoot;
+    #snapshotPath;
     #token;
     #runId;
     #nextId = 1;
@@ -37,6 +41,7 @@ export class GhidraClient {
     #startPromise;
     #closePromise;
     #failure = bindGhidraSessionFailure(() => this.#diagnostics());
+    #wire;
     #requestQueue;
     #responseRouter = new GhidraResponseRouter({
         pending: this.#pending,
@@ -60,13 +65,23 @@ export class GhidraClient {
             this.#failAll(this.#failure("process", "Ghidra bridge socket closed"));
     };
     constructor(options) {
-        this.#logger = options.logger ?? silentLogger;
         this.#options = {
             ...options,
             requestTimeoutMs: options.requestTimeoutMs ?? GHIDRA_REQUEST_TIMEOUT_MS,
             startupTimeoutMs: options.startupTimeoutMs ?? GHIDRA_STARTUP_TIMEOUT_MS,
+            transport: options.transport ?? "unix-socket",
         };
-        this.#requestQueue = new GhidraRequestQueue(GHIDRA_MAX_QUEUED_REQUESTS, (method, parameters, requestOptions) => this.#request(method, parameters, requestOptions), (kind, message, timeoutMs) => this.#failure(kind, message, undefined, timeoutMs === undefined ? {} : { timeoutMs }));
+        this.#logger = options.logger ?? silentLogger;
+        this.#wire = new GhidraWire({
+            getSocket: () => this.#socket,
+            getToken: () => this.#token,
+            nextId: () => this.#nextId++,
+            pending: this.#pending,
+            requestTimeoutMs: this.#options.requestTimeoutMs,
+            logger: this.#logger,
+            failure: this.#failure,
+        });
+        this.#requestQueue = new GhidraRequestQueue(GHIDRA_MAX_QUEUED_REQUESTS, (method, parameters, requestOptions) => this.#wire.request(method, parameters, requestOptions), (kind, message, timeoutMs) => this.#failure(kind, message, undefined, timeoutMs === undefined ? {} : { timeoutMs }));
     }
     /** Launch Ghidra once and require its exact post-analysis handshake. */
     start(signal) {
@@ -103,7 +118,7 @@ export class GhidraClient {
         const started = await this.start(options.signal);
         if (!started.ok)
             return started;
-        const result = await this.#request("ping", {}, options);
+        const result = await this.#wire.request("ping", {}, options);
         if (!result.ok)
             return result;
         return this.#parseSessionInfo(result.value);
@@ -155,16 +170,34 @@ export class GhidraClient {
         }
         if (deadline.signal.aborted)
             return this.#startupInterrupted(deadline);
-        const socketPath = join(this.#runtimeRoot.path, "bridge.sock");
+        const endpoint = {
+            transport: this.#options.transport,
+            path: join(this.#runtimeRoot.path, this.#options.transport === "unix-socket"
+                ? "bridge.sock"
+                : "bridge-endpoint.json"),
+        };
+        try {
+            const snapshot = await createGhidraTargetSnapshot(this.#options.targetPath, this.#runtimeRoot.path, this.#options.targetSha256);
+            this.#snapshotPath = snapshot.path;
+        }
+        catch (cause) {
+            const failure = this.#failure("start", "Ghidra target snapshot failed admission", cause);
+            await this.#cleanup();
+            return err(failure);
+        }
+        if (deadline.signal.aborted)
+            return this.#startupInterrupted(deadline);
         this.#token = randomBytes(32).toString("hex");
         this.#runId = randomUUID();
         const launched = await this.#options.launcher
             .launch({
             runtimeRoot: this.#runtimeRoot.path,
-            socketPath,
+            transport: endpoint.transport,
+            endpointPath: endpoint.path,
             token: this.#token,
             runId: this.#runId,
-            targetPath: this.#options.targetPath,
+            targetPath: this.#snapshotPath,
+            targetSha256: this.#options.targetSha256,
             providerVersion: this.#options.providerVersion,
             profileDigest: this.#options.profileDigest,
         }, { signal: deadline.signal })
@@ -182,92 +215,40 @@ export class GhidraClient {
         this.#process = new ProviderProcessSupervisor(launched.value, {
             onDiagnostic: (event) => this.#onProcessDiagnostic(event),
         });
-        const connected = await this.#connect(socketPath, deadline);
+        const connected = await this.#connect(endpoint, deadline);
         if (!connected.ok) {
             const failure = connected.error;
             await this.#cleanup();
             return err(failure);
         }
-        const ping = await this.#request("ping", {}, {
-            signal: deadline.signal,
-            timeoutMs: deadline.remainingMs(),
+        return completeGhidraStartupHandshake({
+            deadline,
+            request: (method, params, requestOptions) => this.#wire.request(method, params, requestOptions),
+            parseSessionInfo: (value) => this.#parseSessionInfo(value),
+            cleanup: () => this.#cleanup(),
+            failure: this.#failure,
+            startupTimeoutMs: this.#options.startupTimeoutMs,
         });
-        if (!ping.ok) {
-            const failure = deadline.signal.aborted
-                ? this.#interruptionFailure(deadline)
-                : ping.error;
-            await this.#cleanup();
-            return err(failure);
-        }
-        const parsed = this.#parseSessionInfo(ping.value);
-        if (!parsed.ok || parsed.value.analysis_timed_out) {
-            const failure = parsed.ok
-                ? this.#failure("analysis_timeout", "Ghidra auto-analysis reached its per-file deadline")
-                : parsed.error;
-            await this.#cleanup();
-            return err(failure);
-        }
-        return parsed;
     }
-    async #connect(socketPath, deadline) {
-        while (deadline.remainingMs() > 0) {
-            if (deadline.signal.aborted)
-                return err(this.#interruptionFailure(deadline));
-            if (this.#closing)
-                return err(this.#failure("cancelled", "Ghidra startup was closed"));
-            if (this.#processSnapshot?.exitCode !== undefined)
-                return err(this.#failure("process", "Ghidra exited before bridge startup"));
-            try {
-                await access(socketPath);
-            }
-            catch {
-                if ((await deadline.wait(50)) === "aborted")
-                    return err(this.#interruptionFailure(deadline));
-                continue;
-            }
-            const connected = await connectGhidraSocketOnce(socketPath, deadline.signal);
-            if (connected.ok) {
-                this.#socket = connected.value;
-                this.#detachSocket = attachGhidraSocket(connected.value, {
-                    data: this.#onSocketData,
-                    error: this.#onSocketError,
-                    close: this.#onSocketClose,
-                });
-                return ok(undefined);
-            }
-            if ((await deadline.wait(50)) === "aborted")
-                return err(this.#interruptionFailure(deadline));
-        }
-        return err(this.#failure("timeout", "Ghidra startup deadline elapsed", undefined, {
-            timeoutMs: this.#options.startupTimeoutMs,
-        }));
-    }
-    async #request(method, params, options) {
-        const socket = this.#socket;
-        const token = this.#token;
-        if (socket === undefined || socket.destroyed || token === undefined)
-            return err(this.#failure("process", "Ghidra bridge is unavailable"));
-        if (options.signal?.aborted === true)
-            return err(this.#failure("cancelled", "Ghidra request was cancelled"));
-        const id = this.#nextId++;
-        const timeoutMs = options.timeoutMs ?? this.#options.requestTimeoutMs;
-        if (timeoutMs <= 0)
-            return err(this.#failure("timeout", "Ghidra request deadline elapsed", undefined, {
-                timeoutMs,
-            }));
-        const response = this.#pending.wait(id, {
-            timeoutMs,
-            ...(options.signal === undefined ? {} : { signal: options.signal }),
-            timeoutValue: () => err(this.#failure("timeout", "Ghidra bridge request timed out", undefined, { timeoutMs })),
-            cancelledValue: () => err(this.#failure("cancelled", "Ghidra request was cancelled")),
-        });
-        socket.write(`${JSON.stringify({ id, token, method, params })}\n`, (cause) => {
-            if (cause !== undefined && cause !== null)
-                this.#pending.settle(id, err(this.#failure("process", "Ghidra bridge write failed", cause)));
+    async #connect(endpoint, deadline) {
+        const connected = await connectGhidraSocket({
+            endpoint,
+            deadline,
+            failure: this.#failure,
+            isClosed: () => this.#closing,
+            processExited: () => this.#processSnapshot?.exitCode !== undefined,
+            startupTimeoutMs: this.#options.startupTimeoutMs,
+            handlers: {
+                data: this.#onSocketData,
+                error: this.#onSocketError,
+                close: this.#onSocketClose,
+            },
         });
-        const result = await response;
-        this.#logger[result.ok ? "debug" : "warn"]({ method, status: result.ok ? "ok" : "error" }, "Ghidra bridge request completed");
-        return result;
+        if (!connected.ok)
+            return connected;
+        this.#socket = connected.value.socket;
+        this.#detachSocket = connected.value.detach;
+        return ok(undefined);
     }
     #parseSessionInfo(value) {
         const runId = this.#runId;
@@ -277,6 +258,7 @@ export class GhidraClient {
             runId,
             providerVersion: this.#options.providerVersion,
             profileDigest: this.#options.profileDigest,
+            targetSha256: this.#options.targetSha256,
         });
         if (parsed.ok)
             return parsed;
@@ -301,9 +283,9 @@ export class GhidraClient {
             this.#requestQueue.failQueued(this.#failure("process", "Ghidra session closed"));
             const socket = this.#socket;
             if (socket !== undefined && !socket.destroyed) {
-                const shutdown = await this.#request("shutdown", {}, {
-                    timeoutMs: SHUTDOWN_TIMEOUT_MS,
-                }).catch(() => err(this.#failure("process", "Ghidra shutdown request failed")));
+                const shutdown = await this.#wire
+                    .request("shutdown", {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS })
+                    .catch(() => err(this.#failure("process", "Ghidra shutdown request failed")));
                 if (!shutdown.ok || !isGhidraShutdownAcknowledgement(shutdown.value))
                     this.#logger.warn({ status: shutdown.ok ? "invalid-acknowledgement" : "failed" }, "Ghidra bridge shutdown was not confirmed");
             }
@@ -331,6 +313,7 @@ export class GhidraClient {
             const runtimeRoot = this.#runtimeRoot;
             this.#runtimeRoot = undefined;
             await runtimeRoot?.close();
+            this.#snapshotPath = undefined;
             this.#token = undefined;
             this.#runId = undefined;
             this.#responseBuffer.reset();
@@ -386,6 +369,8 @@ export class GhidraClient {
         const snapshot = this.#process?.snapshot() ?? this.#processSnapshot;
         return createGhidraDiagnostics({
             targetPath: this.#options.targetPath,
+            targetSha256: this.#options.targetSha256,
+            transport: this.#options.transport,
             providerVersion: this.#options.providerVersion,
             profileDigest: this.#options.profileDigest,
             ...(this.#runtimeRoot === undefined

package/dist/ghidra/GhidraClientStartup.js

@@ -0,0 +1,29 @@
+import { err } from "../domain/result.js";
+/** Ping and validate the bridge after its socket is attached. */
+export async function completeGhidraStartupHandshake(options) {
+    const ping = await options.request("ping", {}, {
+        signal: options.deadline.signal,
+        timeoutMs: options.deadline.remainingMs(),
+    });
+    if (!ping.ok) {
+        const failure = options.deadline.signal.aborted
+            ? interruptionFailure(options)
+            : ping.error;
+        await options.cleanup();
+        return err(failure);
+    }
+    const parsed = options.parseSessionInfo(ping.value);
+    if (!parsed.ok || parsed.value.analysis_timed_out) {
+        const failure = parsed.ok
+            ? options.failure("analysis_timeout", "Ghidra auto-analysis reached its per-file deadline")
+            : parsed.error;
+        await options.cleanup();
+        return err(failure);
+    }
+    return parsed;
+}
+const interruptionFailure = (options) => options.deadline.cancelled
+    ? options.failure("cancelled", "Ghidra startup was cancelled")
+    : options.failure("timeout", "Ghidra startup deadline elapsed", undefined, {
+        timeoutMs: options.startupTimeoutMs,
+    });

package/dist/ghidra/GhidraClientWire.js

@@ -0,0 +1,34 @@
+import { err } from "../domain/result.js";
+/** Owns the socket write and pending-reply lifecycle for one bridge session. */
+export class GhidraWire {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Write one authenticated request and return its correlated reply. */
+    async request(method, params, options) {
+        const socket = this.#options.getSocket();
+        const token = this.#options.getToken();
+        if (socket === undefined || socket.destroyed || token === undefined)
+            return err(this.#options.failure("process", "Ghidra bridge is unavailable"));
+        if (options.signal?.aborted === true)
+            return err(this.#options.failure("cancelled", "Ghidra request was cancelled"));
+        const id = this.#options.nextId();
+        const timeoutMs = options.timeoutMs ?? this.#options.requestTimeoutMs;
+        if (timeoutMs <= 0)
+            return err(this.#options.failure("timeout", "Ghidra request deadline elapsed", undefined, { timeoutMs }));
+        const response = this.#options.pending.wait(id, {
+            timeoutMs,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            timeoutValue: () => err(this.#options.failure("timeout", "Ghidra bridge request timed out", undefined, { timeoutMs })),
+            cancelledValue: () => err(this.#options.failure("cancelled", "Ghidra request was cancelled")),
+        });
+        socket.write(`${JSON.stringify({ id, token, method, params })}\n`, (cause) => {
+            if (cause !== undefined && cause !== null)
+                this.#options.pending.settle(id, err(this.#options.failure("process", "Ghidra bridge write failed", cause)));
+        });
+        const result = await response;
+        this.#options.logger[result.ok ? "debug" : "warn"]({ method, status: result.ok ? "ok" : "error" }, "Ghidra bridge request completed");
+        return result;
+    }
+}

package/dist/ghidra/GhidraDefaults.js

@@ -17,4 +17,4 @@ export const GHIDRA_MAX_QUEUED_REQUESTS = 32;
 /** Maximum encoded response line accepted from the Java bridge. */
 export const GHIDRA_MAX_LINE_BYTES = 1024 * 1024;
 /** Version of REA's Java bridge handshake and request protocol. */
-export const GHIDRA_BRIDGE_VERSION = 3;
+export const GHIDRA_BRIDGE_VERSION = 4;

package/dist/ghidra/GhidraDiagnostics.js

@@ -1,3 +1,4 @@
+import { join } from "node:path";
 /** Preserve actionable runtime coordinates after cleanup and redact bearer data. */
 export const createGhidraDiagnostics = (options) => {
     if (options.runtimeRoot === undefined &&
@@ -9,13 +10,17 @@ export const createGhidraDiagnostics = (options) => {
         : value.replaceAll(options.token, "[REDACTED]");
     return {
         target_path: options.targetPath,
+        target_sha256: options.targetSha256,
+        transport: options.transport,
         provider_version: options.providerVersion,
         profile_digest: options.profileDigest,
         ...(options.runtimeRoot === undefined
             ? {}
             : {
                 runtime_root: options.runtimeRoot,
-                socket_path: `${options.runtimeRoot}/bridge.sock`,
+                endpoint_path: join(options.runtimeRoot, options.transport === "unix-socket"
+                    ? "bridge.sock"
+                    : "bridge-endpoint.json"),
             }),
         ...(options.launch === undefined
             ? {}

package/dist/ghidra/GhidraInstallation.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { constants } from "node:fs";
 import { accessSync, readFileSync } from "node:fs";
-import { delimiter, join } from "node:path";
+import { posix, win32 } from "node:path";
 /** Exact Ghidra build whose Java bridge contract this REA release supports. */
 export const SUPPORTED_GHIDRA_VERSION = "12.1.2";
 /** Exact JDK major documented by the supported Ghidra release. */
@@ -10,7 +10,7 @@ export const SUPPORTED_GHIDRA_JAVA_MAJOR = 21;
 export const inspectGhidraInstallation = (options, host = systemGhidraInstallationHost()) => {
     const platform = options.platform ?? process.platform;
     const architecture = options.architecture ?? process.arch;
-    const coordinates = installationCoordinates(options, host);
+    const coordinates = installationCoordinates(options, platform, host);
     const checks = installationChecks({
         coordinates,
         platform,
@@ -35,18 +35,23 @@ export const inspectGhidraInstallation = (options, host = systemGhidraInstallati
         reason: failed?.remediation ?? null,
     };
 };
-const installationCoordinates = (options, host) => {
+const installationCoordinates = (options, platform, host) => {
+    const path = platform === "win32" ? win32 : posix;
     const installDir = options.installDir ?? null;
     const applicationPropertiesPath = installDir === null
         ? null
-        : join(installDir, "Ghidra", "application.properties");
-    const analyzeHeadlessPath = installDir === null ? null : join(installDir, "support", "analyzeHeadless");
+        : path.join(installDir, "Ghidra", "application.properties");
+    const analyzeHeadlessPath = installDir === null
+        ? null
+        : path.join(installDir, "support", platform === "win32" ? "analyzeHeadless.bat" : "analyzeHeadless");
     const properties = applicationPropertiesPath === null
         ? undefined
         : host.readText(applicationPropertiesPath);
     const javaCommand = options.javaHome === undefined
-        ? "java"
-        : join(options.javaHome, "bin", "java");
+        ? platform === "win32"
+            ? "java.exe"
+            : "java"
+        : path.join(options.javaHome, "bin", platform === "win32" ? "java.exe" : "java");
     return {
         installDir,
         applicationPropertiesPath,
@@ -56,7 +61,7 @@ const installationCoordinates = (options, host) => {
             ? null
             : propertyValue(properties, "application.version"),
         javaCommand,
-        java: host.probeJava(javaCommand, ghidraJavaEnvironment(options.javaHome)),
+        java: host.probeJava(javaCommand, ghidraJavaEnvironment(options.javaHome, process.env, platform)),
     };
 };
 const installationChecks = ({ coordinates, platform, architecture, javaHome, host, }) => [
@@ -69,17 +74,17 @@ const installationChecks = ({ coordinates, platform, architecture, javaHome, hos
     }),
     installationCheck({
         name: "platform",
-        ok: platform === "linux",
+        ok: platform === "linux" || platform === "win32",
         code: "unsupported_host",
         detail: platform,
-        remediation: "REA's Ghidra v1 adapter currently supports Linux only.",
+        remediation: "Use REA's Ghidra adapter on a supported Linux or Windows x64 host.",
     }),
     installationCheck({
         name: "architecture",
         ok: architecture === "x64",
         code: "unsupported_host",
         detail: architecture,
-        remediation: "Use the official Linux x86-64 Ghidra distribution on an x64 host.",
+        remediation: "Use the official x86-64 Ghidra distribution on an x64 Linux or Windows host.",
     }),
     installationCheck({
         name: "installation",
@@ -104,7 +109,7 @@ const installationChecks = ({ coordinates, platform, architecture, javaHome, hos
             host.executable(coordinates.analyzeHeadlessPath),
         code: "executable_missing",
         detail: coordinates.analyzeHeadlessPath ?? "analyzeHeadless unavailable",
-        remediation: "Restore the executable support/analyzeHeadless script from the official Ghidra release.",
+        remediation: "Restore support/analyzeHeadless or support/analyzeHeadless.bat from the official Ghidra release.",
     }),
     javaCheck(coordinates.java, coordinates.javaCommand, javaHome),
 ];
@@ -127,7 +132,7 @@ export const ghidraInstallationDiagnostics = (inspection) => ({
     })),
 });
 /** Environment that makes an explicitly selected JDK win over PATH discovery. */
-export const ghidraJavaEnvironment = (javaHome, environment = process.env) => {
+export const ghidraJavaEnvironment = (javaHome, environment = process.env, platform = process.platform) => {
     const boundedEnvironment = {
         ...environment,
         _JAVA_OPTIONS: "",
@@ -140,7 +145,7 @@ export const ghidraJavaEnvironment = (javaHome, environment = process.env) => {
         : {
             ...boundedEnvironment,
             JAVA_HOME: javaHome,
-            PATH: `${join(javaHome, "bin")}${delimiter}${environment.PATH ?? ""}`,
+            PATH: `${(platform === "win32" ? win32 : posix).join(javaHome, "bin")}${platform === "win32" ? win32.delimiter : posix.delimiter}${environment.PATH ?? ""}`,
         };
 };
 const installationCheck = (options) => ({
@@ -217,7 +222,7 @@ const systemGhidraInstallationHost = () => ({
             major: javaMajor(version),
             home,
             bits,
-            jdk: executablePath(join(home, "bin", "javac")),
+            jdk: executablePath((process.platform === "win32" ? win32 : posix).join(home, "bin", process.platform === "win32" ? "javac.exe" : "javac")),
         };
     },
 });