rea-agents 4.1.0 → 6.0.0

package/dist/native/LldbCallTracer.js

@@ -0,0 +1,278 @@
+import { spawn } from "node:child_process";
+import { open, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { nativeCallEventSchema, nativeCodeLocationSchema, } from "../domain/native/nativeCallObservation.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { err, ok } from "../domain/result.js";
+import { safeParseJson } from "../domain/safeJson.js";
+import { execFileOutput } from "../process/ExecFileOutput.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { resolveXcrunTool } from "./CommandRunner.js";
+const OPERATION = "observe_native_calls";
+const PROVIDER = "native-macos";
+/** Captured target output kept per stream; the rest is counted, not stored. */
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+/** LLDB startup, symbol loading and teardown beyond the observation window. */
+const DEADLINE_GRACE_MS = 60_000;
+const DIAGNOSTIC_BYTES = 16 * 1024;
+const BRIDGE = fileURLToPath(new URL("../../bridge/native/rea_lldb_tracer.py", import.meta.url));
+/** JSON the LLDB bridge writes after a completed run. */
+const tracedSchema = z.strictObject({
+    status: z.literal("traced"),
+    version: z.string(),
+    pid: z.number().int().positive(),
+    outcome: z.enum(["exited", "duration-elapsed", "event-limit", "stop-limit"]),
+    exit_status: z.number().int().nullable(),
+    exit_description: z.string().nullable(),
+    killed: z.boolean(),
+    terminated: z.boolean(),
+    elapsed_ms: z.number().nonnegative(),
+    breakpoints: z.array(z.strictObject({
+        index: z.number().int().nonnegative(),
+        location_count: z.number().int().nonnegative(),
+        locations: z.array(nativeCodeLocationSchema),
+    })),
+    events: z.array(nativeCallEventSchema),
+    other_stops: z.array(z.string()),
+});
+const tracerOutputSchema = z.discriminatedUnion("status", [
+    tracedSchema,
+    z.strictObject({
+        status: z.enum(["target-error", "launch-error", "tracer-error"]),
+        error: z.string().nullable(),
+    }),
+]);
+/** Remediation for a target LLDB may not debug. */
+const ATTACH_REMEDIATION = "Allow debugging for this user (Developer Tools access: `DevToolsSecurity -enable`, or membership in the _developer group). A hardened-runtime target is debuggable only with the com.apple.security.get-task-allow entitlement; see inspect_signature's debugger-attach facet.";
+/** Production tracer: `lldb --batch` running the REA LLDB bridge. */
+export class LldbCallTracer {
+    async trace(request, signal) {
+        const lldb = await resolveXcrunTool("lldb", signal);
+        if (!lldb.ok)
+            return err(lldb.error.reason === "cancelled"
+                ? new AnalysisCancelledError(OPERATION)
+                : new AnalysisCapabilityUnavailableError(PROVIDER, OPERATION, "LLDB from Xcode or the Command Line Tools is not available"));
+        const root = await PrivateRuntimeRoot.create({ prefix: "rea-lldb-" });
+        try {
+            return await this.#run(lldb.value, root.path, request, signal);
+        }
+        finally {
+            await root.close();
+        }
+    }
+    async #run(lldb, directory, request, signal) {
+        const paths = {
+            config: join(directory, "config.json"),
+            result: join(directory, "result.json"),
+            pid: join(directory, "pid"),
+            stdout: join(directory, "stdout"),
+            stderr: join(directory, "stderr"),
+        };
+        const { input } = request;
+        await writeFile(paths.config, JSON.stringify({
+            executable: request.executable,
+            architecture: request.architecture,
+            arguments: input.arguments,
+            environment: input.environment,
+            working_directory: input.working_directory ?? null,
+            breakpoints: input.breakpoints.map((breakpoint) => breakpoint.kind === "function"
+                ? { ...breakpoint, module: breakpoint.module ?? null }
+                : { ...breakpoint, class_name: breakpoint.class_name ?? null }),
+            duration_ms: input.duration_ms,
+            max_events: input.max_events,
+            argument_registers: input.argument_registers,
+            backtrace_frames: input.backtrace_frames,
+            stdout_path: paths.stdout,
+            stderr_path: paths.stderr,
+            result_path: paths.result,
+            pid_path: paths.pid,
+        }), { mode: 0o600 });
+        const exited = await runLldb(lldb.path, [
+            "--batch",
+            "--no-lldbinit",
+            "--no-use-colors",
+            "-o",
+            `command script import ${quote(BRIDGE)}`,
+            "-o",
+            `rea_trace ${paths.config}`,
+        ], {
+            deadlineMs: input.duration_ms + DEADLINE_GRACE_MS,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        const terminated = await ensureTerminated(paths.pid, request.executable);
+        if (exited.kind === "cancelled")
+            return err(new AnalysisCancelledError(OPERATION));
+        if (exited.kind === "timeout")
+            return err(new AnalysisTimeoutError(OPERATION, input.duration_ms + DEADLINE_GRACE_MS));
+        const output = await readTracerOutput(paths.result);
+        if (output === undefined)
+            return err(new ProviderAdapterError(PROVIDER, OPERATION, {
+                diagnostics: {
+                    reason: "LLDB exited without a tracer result",
+                    exit_code: exited.exitCode,
+                    lldb_output: exited.output,
+                },
+            }));
+        if (output.status !== "traced")
+            return err(tracerFailure(output));
+        return ok({
+            debugger: { ...lldb, version: output.version },
+            run: output,
+            stdout: await capturedOutput(paths.stdout),
+            stderr: await capturedOutput(paths.stderr),
+            terminated,
+        });
+    }
+}
+/** LLDB command arguments are quoted; the bridge path is REA's own install path. */
+const quote = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+const tracerFailure = (output) => {
+    const message = output.error ?? "no LLDB error text";
+    if (output.status === "tracer-error")
+        return new ProviderAdapterError(PROVIDER, OPERATION, {
+            diagnostics: { reason: `LLDB bridge failed: ${message}` },
+        });
+    if (output.status === "target-error")
+        return new AnalysisCapabilityUnavailableError(PROVIDER, OPERATION, `lldb-target-unloadable: ${message}`);
+    // debugserver reports denied task access as an attach failure.
+    return /attach|not allowed|permission|denied|debugserver/iu.test(message)
+        ? new AnalysisCapabilityUnavailableError(PROVIDER, OPERATION, `debugger-attach-denied: ${message}`, { userMessage: ATTACH_REMEDIATION })
+        : new AnalysisCapabilityUnavailableError(PROVIDER, OPERATION, `launch-failed: ${message}`);
+};
+const readTracerOutput = async (path) => {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = safeParseJson(text);
+    if (!parsed.ok)
+        return undefined;
+    const output = tracerOutputSchema.safeParse(parsed.value);
+    return output.success ? output.data : undefined;
+};
+const capturedOutput = async (path) => {
+    let handle;
+    try {
+        handle = await open(path, "r");
+    }
+    catch {
+        return { text: "", bytes: 0, truncated: false };
+    }
+    try {
+        const { size } = await handle.stat();
+        const buffer = Buffer.alloc(Math.min(size, MAX_OUTPUT_BYTES));
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        return {
+            text: buffer.subarray(0, bytesRead).toString("utf8"),
+            bytes: size,
+            truncated: size > MAX_OUTPUT_BYTES,
+        };
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** Run LLDB in its own process group so cancellation can stop it and debugserver. */
+const runLldb = (executable, arguments_, options) => new Promise((resolve) => {
+    if (options.signal?.aborted === true) {
+        resolve({ kind: "cancelled" });
+        return;
+    }
+    const child = spawn(executable, [...arguments_], {
+        shell: false,
+        detached: true,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    let output = "";
+    let stopped;
+    const keep = (chunk) => {
+        output = (output + chunk.toString("utf8")).slice(-DIAGNOSTIC_BYTES);
+    };
+    child.stdout.on("data", keep);
+    child.stderr.on("data", keep);
+    const kill = (reason) => {
+        stopped ??= reason;
+        if (child.pid !== undefined)
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                // The group already exited.
+            }
+    };
+    const timer = setTimeout(() => {
+        kill("timeout");
+    }, options.deadlineMs);
+    const onAbort = () => {
+        kill("cancelled");
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const finish = (exitCode) => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+        resolve(stopped === undefined
+            ? { kind: "exited", exitCode, output }
+            : { kind: stopped });
+    };
+    child.on("error", () => {
+        finish(null);
+    });
+    child.on("close", (code) => {
+        finish(code);
+    });
+});
+/**
+ * debugserver kills the traced process when LLDB exits. Confirm it, and kill a
+ * survivor only when its executable is still the traced one.
+ */
+const ensureTerminated = async (pidPath, executable) => {
+    let pid;
+    try {
+        pid = Number.parseInt(await readFile(pidPath, "utf8"), 10);
+    }
+    catch {
+        // LLDB never launched the target.
+        return true;
+    }
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    for (let attempt = 0; attempt < 20; attempt++) {
+        if (!alive(pid))
+            return true;
+        if (attempt === 10 && (await commandOf(pid)) === executable)
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch {
+                // It exited between the checks.
+            }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return !alive(pid);
+};
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (cause) {
+        return !(cause instanceof Error &&
+            "code" in cause &&
+            cause.code === "ESRCH");
+    }
+};
+const commandOf = async (pid) => {
+    try {
+        const { stdout } = await execFileOutput("/bin/ps", ["-o", "comm=", "-p", String(pid)], { timeout: 5_000 });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/native/NativeCallObservation.js

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { open } from "node:fs/promises";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, } from "../domain/analysisErrorCore.js";
+import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
+import { nativeCallObservationInputSchema, nativeCallObservationResultSchema, } from "../domain/native/nativeCallObservation.js";
+import { err, ok } from "../domain/result.js";
+const OPERATION = "observe_native_calls";
+/** What every call observation leaves unobserved or approximated. */
+export const NATIVE_CALL_OBSERVATION_LIMITATIONS = [
+    "Only entries are observed; return values, floating-point and stack-passed arguments are not captured.",
+    "Registers are the raw integer argument registers at entry. For Objective-C methods the first two hold the receiver and the selector.",
+    "Receiver classes come from LLDB's Objective-C runtime reader without running target code; they are null for class methods and for receivers LLDB cannot classify.",
+    "Calls that never reach a symbol's entry, such as inlined code or objc_direct methods called directly, are not observed.",
+    "The target is launched directly under LLDB, not through LaunchServices; LLDB disables ASLR for it, so load addresses can equal file addresses.",
+    "The observation window is checked about once a second, and recording pauses the process at every entry, which slows it.",
+];
+/** Launch the active Mach-O under LLDB, record requested call entries, then stop it. */
+export const observeNativeCalls = async (target, parameters, tracer, signal) => {
+    if (target.kind !== "executable" || target.format !== "mach-o")
+        return err(new AnalysisCapabilityUnavailableError("native-macos", OPERATION, "Native call observation launches a Mach-O executable; the active target is not one"));
+    const parsed = nativeCallObservationInputSchema.safeParse(parameters);
+    if (!parsed.success)
+        return err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
+    // Observe the bytes the session's other Evidence describes.
+    if ((await fileSha256(target.path, signal)) !== target.sha256)
+        return err(new EvidenceIntegrityError("Native call observation target digest changed after session binding"));
+    if (signal?.aborted === true)
+        return err(new AnalysisCancelledError(OPERATION));
+    const traced = await tracer.trace({
+        executable: target.path,
+        architecture: target.architecture,
+        input: parsed.data,
+    }, signal);
+    if (!traced.ok)
+        return traced;
+    return ok(projectNativeCalls(target, parsed.data, traced.value));
+};
+/** Join the request, the tracer's run and REA's own checks into the result contract. */
+export const projectNativeCalls = (target, input, trace) => {
+    const { run } = trace;
+    const unresolved = run.breakpoints
+        .filter(({ location_count: count }) => count === 0)
+        .map(({ index }) => index);
+    const eventLimit = run.outcome === "event-limit";
+    const partial = eventLimit || run.outcome === "stop-limit" || unresolved.length > 0;
+    return nativeCallObservationResultSchema.parse({
+        target: {
+            path: target.path,
+            sha256: target.sha256,
+            architecture: target.architecture,
+            arguments: input.arguments,
+            working_directory: input.working_directory ?? null,
+        },
+        debugger: trace.debugger,
+        process: {
+            pid: run.pid,
+            outcome: run.outcome,
+            exit_status: run.exit_status,
+            exit_description: run.exit_description,
+            terminated: run.terminated && trace.terminated,
+            elapsed_ms: run.elapsed_ms,
+            stdout: trace.stdout,
+            stderr: trace.stderr,
+            other_stops: run.other_stops,
+        },
+        breakpoints: input.breakpoints.map((request, index) => ({
+            index,
+            request: request.kind === "function"
+                ? { ...request, module: request.module ?? null }
+                : { ...request, class_name: request.class_name ?? null },
+            location_count: run.breakpoints[index]?.location_count ?? 0,
+            locations: run.breakpoints[index]?.locations ?? [],
+        })),
+        events: run.events,
+        coverage: {
+            status: partial ? "partial" : "complete",
+            event_limit_reached: eventLimit,
+            unresolved_breakpoints: unresolved,
+        },
+        limitations: [
+            ...NATIVE_CALL_OBSERVATION_LIMITATIONS,
+            ...(eventLimit
+                ? [
+                    `Observation stopped at max_events (${input.max_events}); later calls were not recorded and the process was killed.`,
+                ]
+                : []),
+            ...(run.outcome === "duration-elapsed"
+                ? [
+                    `The process was still running after duration_ms (${input.duration_ms}) and was killed.`,
+                ]
+                : []),
+            ...(run.outcome === "stop-limit"
+                ? [
+                    "Observation stopped after repeated signal or exception stops; the process was killed.",
+                ]
+                : []),
+            ...(unresolved.length === 0
+                ? []
+                : [
+                    `Breakpoints ${unresolved.join(", ")} matched no code in any image loaded while observing; their calls could not be observed.`,
+                ]),
+            ...(run.breakpoints.some(({ location_count: count, locations }) => locations.length < count)
+                ? [
+                    "Breakpoints with many matching locations list only the first 64; location_count gives the total.",
+                ]
+                : []),
+            ...(trace.stdout.truncated || trace.stderr.truncated
+                ? ["Target output beyond 1 MiB per stream is counted but not kept."]
+                : []),
+            ...(run.terminated && trace.terminated
+                ? []
+                : [
+                    `REA could not confirm that process ${run.pid} exited; check for it before relying on host state.`,
+                ]),
+        ],
+    });
+};
+const fileSha256 = async (path, signal) => {
+    const handle = await open(path, "r");
+    try {
+        const hash = createHash("sha256");
+        const buffer = new Uint8Array(1024 * 1024);
+        for (;;) {
+            signal?.throwIfAborted();
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+        }
+        return hash.digest("hex");
+    }
+    finally {
+        await handle.close();
+    }
+};