rea-agents 5.0.0 → 6.1.0

package/dist/application/AppBundleExecutable.js

@@ -6,6 +6,7 @@ import { z } from "zod";
 import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { isPathWithinRoot } from "../domain/localPath.js";
 import { parseXmlPropertyList } from "../domain/propertyListKeys.js";
+import { decodeXmlPlistText } from "../domain/propertyListXmlText.js";
 import { err, ok } from "../domain/result.js";
 const execFileAsync = promisify(execFile);
 const BUNDLE_LAYOUTS = [
@@ -18,23 +19,31 @@ const BUNDLE_LAYOUTS = [
     // iOS-style bundles, as extracted from an IPA, keep both at the root.
     { plist: ["Info.plist"], programs: [], programsLabel: "the bundle root" },
 ];
+const defaultFileSystem = { readFile, realpath };
 /**
  * Resolve an app bundle directory to its declared program file. macOS and
  * flat iOS-style layouts are read directly. An iOS app installed on a Mac is
  * a wrapper whose `Wrapper` directory holds the iOS bundle; that bundle is
  * found by listing `Wrapper`, never by following the `WrappedBundle` link.
  */
-export const resolveAppBundleExecutable = async (path) => {
-    const layout = await presentLayout(path);
-    if (layout !== undefined)
-        return resolveLayoutExecutable(path, layout);
-    const wrapped = await wrappedBundle(path);
-    if (wrapped !== undefined) {
-        const wrappedLayout = await presentLayout(wrapped);
-        if (wrappedLayout !== undefined)
-            return resolveLayoutExecutable(wrapped, wrappedLayout);
+export const resolveAppBundleExecutable = async (path, fileSystem = defaultFileSystem) => {
+    try {
+        const layout = await presentLayout(path);
+        if (layout !== undefined)
+            return resolveLayoutExecutable(path, layout, fileSystem);
+        const wrapped = await wrappedBundle(path);
+        if (wrapped !== undefined) {
+            const wrappedLayout = await presentLayout(wrapped);
+            if (wrappedLayout !== undefined)
+                return resolveLayoutExecutable(wrapped, wrappedLayout, fileSystem);
+        }
+    }
+    catch (cause) {
+        if (cause instanceof BinaryTargetError)
+            return err(cause);
+        return err(new BinaryTargetError(path, errorReason(cause, path), { cause }));
     }
-    return err(new BinaryTargetError(path, "app has no readable CFBundleExecutable", {
+    return err(new BinaryTargetError(path, `app Info.plist is missing or no supported bundle layout was found: ${path}`, {
         cause: new Error("No Contents/Info.plist, root Info.plist, or single Wrapper/*.app bundle was found"),
     }));
 };
@@ -56,13 +65,34 @@ const layoutPlistPresent = async (path) => {
     catch (cause) {
         if (isAbsence(cause))
             return false;
+        if (isPermissionDenied(cause))
+            throw new BinaryTargetError(path, `permission denied inspecting app Info.plist ${path}`, { cause });
         throw cause;
     }
 };
 const isAbsence = (cause) => {
-    const code = cause instanceof Error ? Reflect.get(cause, "code") : undefined;
+    const code = errorCode(cause);
     return code === "ENOENT" || code === "ENOTDIR";
 };
+const errorCode = (cause) => cause instanceof Error ? Reflect.get(cause, "code") : undefined;
+const codeDescription = (cause) => {
+    const code = errorCode(cause);
+    return typeof code === "string" || typeof code === "number"
+        ? ` (${String(code)})`
+        : "";
+};
+const isSystemErrorCode = (cause) => {
+    const code = errorCode(cause);
+    return (typeof code === "string" &&
+        /^[A-Z][A-Z0-9_]+$/u.test(code) &&
+        !code.startsWith("ERR_"));
+};
+const isPermissionDenied = (cause) => errorCode(cause) === "EACCES" || errorCode(cause) === "EPERM";
+const errorReason = (cause, path) => isPermissionDenied(cause)
+    ? `permission denied accessing app bundle path ${path}`
+    : isAbsence(cause)
+        ? `app bundle path is missing: ${path}`
+        : `could not inspect app bundle path ${path}`;
 /** The single real `.app` directory inside an iOS-on-Mac `Wrapper`. */
 const wrappedBundle = async (bundle) => {
     const wrapper = join(bundle, "Wrapper");
@@ -81,20 +111,32 @@ const wrappedBundle = async (bundle) => {
         ? join(wrapper, app.name)
         : undefined;
 };
-const resolveLayoutExecutable = async (bundle, layout) => {
+const resolveLayoutExecutable = async (bundle, layout, fileSystem) => {
     const plistPath = join(bundle, ...layout.plist);
+    let plist;
+    try {
+        plist = await fileSystem.readFile(plistPath);
+    }
+    catch (cause) {
+        return err(new BinaryTargetError(plistPath, isPermissionDenied(cause)
+            ? `permission denied reading app Info.plist ${plistPath}`
+            : isAbsence(cause)
+                ? `app Info.plist is missing: ${plistPath}`
+                : `could not read app Info.plist ${plistPath}${codeDescription(cause)}`, { cause }));
+    }
     let name;
     try {
-        const plist = await readFile(plistPath);
         name =
             plist.subarray(0, 6).toString("ascii") === "bplist"
-                ? await readBinaryPlistExecutable(plistPath)
-                : parseXmlPlistExecutable(plist.toString("utf8"));
+                ? await (fileSystem.decodeBinaryPlist ?? readBinaryPlistExecutable)(plistPath)
+                : parseXmlPlistExecutable(decodeXmlPlistText(plist));
     }
     catch (cause) {
-        return err(new BinaryTargetError(bundle, "app has no readable CFBundleExecutable", {
-            cause,
-        }));
+        return err(new BinaryTargetError(plistPath, isPermissionDenied(cause)
+            ? `permission denied decoding app Info.plist ${plistPath}${codeDescription(cause)}`
+            : isSystemErrorCode(cause)
+                ? `could not decode app Info.plist ${plistPath}${codeDescription(cause)}`
+                : `app Info.plist is malformed, unsupported, or lacks CFBundleExecutable: ${plistPath}${cause instanceof Error ? ` (${cause.message})` : ""}`, { cause }));
     }
     if (!isSafeExecutableName(name))
         return err(new BinaryTargetError(bundle, "app has an unsafe CFBundleExecutable"));
@@ -102,15 +144,19 @@ const resolveLayoutExecutable = async (bundle, layout) => {
     const executable = join(programs, name);
     try {
         const [canonicalPrograms, canonicalExecutable] = await Promise.all([
-            realpath(programs),
-            realpath(executable),
+            fileSystem.realpath(programs),
+            fileSystem.realpath(executable),
         ]);
         if (!isPathWithinRoot(canonicalPrograms, canonicalExecutable))
             return err(new BinaryTargetError(bundle, `app program file leaves ${layout.programsLabel}`));
         return ok({ executable: canonicalExecutable, infoPlist: plistPath });
     }
     catch (cause) {
-        return err(new BinaryTargetError(bundle, "app program file is missing", { cause }));
+        return err(new BinaryTargetError(executable, isPermissionDenied(cause)
+            ? `permission denied resolving app program file ${executable}`
+            : isAbsence(cause)
+                ? `app program file is missing: ${executable}`
+                : `could not resolve app program file ${executable}`, { cause }));
     }
 };
 /** Decode the top-level executable name with an XML parser, not a pattern. */

package/dist/application/CallPathTracing.js

@@ -2,9 +2,25 @@ import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import {} from "../domain/analysisErrorBase.js";
 import { parseRelatedAddresses } from "../domain/hopperValues.js";
 import { ok } from "../domain/result.js";
+import { resolveProcedureAddress } from "./ProcedureAddressResolution.js";
 /** Trace direct caller/callee relationships until the graph is exhausted or the goal is reached. */
 export const traceCallPath = async (call, input, signal) => {
-    const state = createTraceState(input);
+    const start = await resolveProcedureAddress(call, input.start, signal);
+    if (!start.ok)
+        return start;
+    let goal;
+    if (input.goal !== undefined) {
+        const resolved = await resolveProcedureAddress(call, input.goal, signal);
+        if (!resolved.ok)
+            return resolved;
+        goal = resolved.value;
+    }
+    const resolvedInput = {
+        start: start.value,
+        ...(goal === undefined ? {} : { goal }),
+        direction: input.direction,
+    };
+    const state = createTraceState(resolvedInput);
     while (state.queueIndex < state.queue.length &&
         state.traversalPath.length === 0) {
         const address = state.queue[state.queueIndex++];
@@ -14,7 +30,7 @@ export const traceCallPath = async (call, input, signal) => {
         if (current === undefined)
             continue;
         const found = await expandAddress(call, {
-            input,
+            input: resolvedInput,
             state,
             address,
             current,
@@ -23,7 +39,7 @@ export const traceCallPath = async (call, input, signal) => {
         if (found)
             break;
     }
-    return ok(projectTrace(input, state));
+    return ok(projectTrace(resolvedInput, state));
 };
 const createTraceState = (input) => ({
     visited: new Map([[input.start, { depth: 0, path: [input.start] }]]),

package/dist/application/CapabilityInventory.js

@@ -186,6 +186,27 @@ const workflowAvailabilityFor = ({ name, kind, policy, }) => {
                 reason: "provider_missing",
                 remediation: "On Linux x64, provide an absolute REA_WAKARU_COMMAND for Wakaru 1.13.0 and util-linux prlimit. No binary target is required.",
             };
+    if (name === "inspect_binary_layout")
+        return policy.binaryLayoutEnabled === true
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "provider_missing",
+                remediation: "On Linux x64, set absolute REA_PWNTOOLS_PYTHON to caller-supplied Python with pwntools 4.15.0. No active binary target is required.",
+            };
+    if (name === "inspect_evm_interface")
+        return policy.evmInterfaceEnabled === true
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "provider_missing",
+                remediation: "The bundled offline EVM interface profile is currently real-verified on Linux x64. No active binary target or chain endpoint is required.",
+            };
+    if (name === "inspect_recorded_crash")
+        return policy.recordedCrashEnabled === true
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "provider_missing",
+                remediation: "On Linux x64, set absolute REA_PWNTOOLS_PYTHON to caller-supplied Python with pwntools 4.15.0. No active binary target is required.",
+            };
     if (kind === "firmware-provider") {
         const enabled = name === "inspect_firmware_regions"
             ? policy.firmwareInspectionEnabled
@@ -198,11 +219,14 @@ const workflowAvailabilityFor = ({ name, kind, policy, }) => {
             };
     }
     if (kind === "android-provider")
-        return policy.androidAnalysisEnabled === true
+        return policy.androidAnalysisAvailability?.status === "available"
             ? { reason: "available", remediation: null }
             : {
-                reason: "provider_missing",
-                remediation: "Set REA_JADX_MCP_JAR to a caller-supplied jadx-headless-mcp 0.7.1 JAR and provide Java on Linux or macOS. Only Linux has real-provider verification.",
+                reason: policy.androidAnalysisAvailability?.code === "unsupported_host"
+                    ? "unsupported_host"
+                    : "provider_missing",
+                remediation: policy.androidAnalysisAvailability?.reason ??
+                    "Set REA_JADX_MCP_JAR to a caller-supplied jadx-headless-mcp 0.7.1 JAR and provide a full JDK on Linux or macOS.",
             };
     const browser = browserProviderAvailability(name, kind, policy);
     if (browser !== null)