rea-agents 4.1.0 → 6.0.0

package/dist/native/parsers/codesign.js

@@ -1,10 +1,18 @@
-import { inspectSignatureSchema, } from "../../domain/nativeInspection.js";
-/** Parse bounded `codesign -d` diagnostics, which Apple emits on stderr. */
-export const parseCodeSignature = (output, unsigned) => {
+import { inspectSignatureSchema, } from "../../domain/native/nativeInspection.js";
+/**
+ * Parse bounded `codesign -d --verbose=4` diagnostics, which Apple emits on
+ * stderr. codesign echoes the executable path and signing identifier
+ * verbatim, and an ad hoc identifier derives from the file name, so either
+ * can contain line breaks and text that resembles other fields. The path is
+ * removed by its exact value from `executablePaths`, and the identifier runs
+ * to the `Format=` field that codesign prints after it.
+ */
+export const parseCodeSignature = (output, unsigned, executablePaths = []) => {
+    const { identifier, fields } = splitEchoedValues(output.replaceAll("\r\n", "\n"), executablePaths);
     const values = new Map();
     const authorities = [];
     const cdhashes = [];
-    for (const line of output.split(/\r?\n/u)) {
+    for (const line of fields.split("\n")) {
         if (line.startsWith("CodeDirectory ")) {
             values.set("CodeDirectory", line.slice("CodeDirectory ".length));
             continue;
@@ -23,7 +31,7 @@ export const parseCodeSignature = (output, unsigned) => {
     }
     const parsed = inspectSignatureSchema.omit({ provenance: true }).parse({
         signed: !unsigned,
-        identifier: values.get("Identifier") ?? null,
+        identifier: identifier ?? null,
         team_identifier: nullableCodeSignValue(values.get("TeamIdentifier")),
         format: values.get("Format") ?? null,
         cdhashes,
@@ -41,6 +49,33 @@ export const parseCodeSignature = (output, unsigned) => {
     });
     return parsed;
 };
+/**
+ * Separate the echoed executable path and signing identifier, which codesign
+ * prints first, from the fields that follow them.
+ */
+const splitEchoedValues = (text, executablePaths) => {
+    const executable = executablePaths
+        .map((path) => `Executable=${path}\n`)
+        .find((line) => text.startsWith(line));
+    let rest = text;
+    if (executable !== undefined)
+        rest = text.slice(executable.length);
+    else if (text.startsWith("Executable=")) {
+        const identifierLine = text.indexOf("\nIdentifier=");
+        rest = identifierLine < 0 ? text : text.slice(identifierLine + 1);
+    }
+    if (!rest.startsWith("Identifier="))
+        return { identifier: undefined, fields: rest };
+    // Later fields come from the signature itself, so the last `Format=` line
+    // is the one codesign printed after the identifier.
+    const format = rest.lastIndexOf("\nFormat=");
+    const lineEnd = rest.indexOf("\n");
+    const end = format >= 0 ? format : lineEnd >= 0 ? lineEnd : rest.length;
+    return {
+        identifier: rest.slice("Identifier=".length, end),
+        fields: rest.slice(end),
+    };
+};
 const nullableCodeSignValue = (value) => value === undefined || value === "not set" ? null : value;
 const splitAlgorithms = (value) => value === undefined
     ? []

package/dist/native/parsers/demangle.js

@@ -4,9 +4,13 @@ const resultSchema = z.object({
     output: z.string(),
     status: z.enum(["demangled", "unchanged", "invalid"]),
 });
-/** Preserve input ordering while parsing `swift-demangle --compact` lines. */
+/**
+ * Preserve input ordering while parsing `swift-demangle --compact` lines.
+ * The demangler ends each record with LF, so a carriage return belongs to the
+ * symbol text.
+ */
 export const parseDemangledSymbols = (inputs, output) => {
-    const lines = output.replace(/\r?\n$/u, "").split(/\r?\n/u);
+    const lines = output.replace(/\n$/u, "").split("\n");
     if (lines.length !== inputs.length)
         throw new TypeError("swift-demangle output count does not match input");
     return inputs.map((input, index) => {

package/dist/native/parsers/dyldInfo.js

@@ -1,5 +1,5 @@
 /** Decode Apple dyld inventory rows, projecting export offsets to VM addresses. */
-export const parseDyldSymbols = (output, mode, imageBase = null) => {
+export const parseDyldSymbols = (output, mode, imageBase = null, knownExportNames = new Set()) => {
     const offsets = /^\s*offset\s+symbol\s*$/mu.test(output);
     return output.split(/\r?\n/u).flatMap((rawLine) => {
         const line = rawLine.trim();
@@ -31,7 +31,16 @@ export const parseDyldSymbols = (output, mode, imageBase = null) => {
         const exported = /^(0x[\da-f]+)\s+(.+?)(?:\s+\[([^\]]+)\])?$/iu.exec(line);
         if (exported?.[1] === undefined || exported[2] === undefined)
             return [];
-        const absolute = /\babsolute\b/u.test(exported[3] ?? "");
+        const rawName = /^0x[\da-f]+\s+(.+)$/iu.exec(line)?.[1];
+        const literalName = rawName !== undefined && knownExportNames.has(rawName);
+        // If nm establishes both interpretations, the textual row cannot bind an address or flags.
+        // Let the caller retain the exact nm names without guessing which one owns this row.
+        if (literalName &&
+            exported[3] !== undefined &&
+            knownExportNames.has(exported[2]))
+            return [];
+        const annotation = literalName ? undefined : exported[3];
+        const absolute = /\babsolute\b/u.test(annotation ?? "");
         const address = offsets && !absolute
             ? imageBase === null
                 ? null
@@ -39,9 +48,9 @@ export const parseDyldSymbols = (output, mode, imageBase = null) => {
             : canonicalHex(exported[1]);
         return [
             {
-                name: exported[2],
+                name: literalName ? rawName : exported[2],
                 address,
-                weak: /\bweak-def\b/u.test(exported[3] ?? "") ? true : null,
+                weak: /\bweak-def\b/u.test(annotation ?? "") ? true : null,
                 reexport: false,
                 source: null,
             },

package/dist/native/parsers/echoedPath.js

@@ -0,0 +1,14 @@
+/**
+ * Remove the header line otool and dyld_info print before a slice's output:
+ * `<path>:`, `<path> (architecture <arch>):`, or `<path> [<arch>]:`. File
+ * names may contain line breaks and tool keywords, so only the exact operand
+ * path is stripped; output without that header is returned unchanged.
+ */
+export const withoutEchoedPathHeader = (output, path) => {
+    if (path === undefined || !output.startsWith(path))
+        return output;
+    const header = /^(?: \(architecture [^)\n]*\)| \[[^\]\n]*\])?:\r?\n/u.exec(output.slice(path.length));
+    return header === null
+        ? output
+        : output.slice(path.length + header[0].length);
+};

package/dist/native/parsers/lipo.js

@@ -9,6 +9,20 @@ const architectureSchema = z.object({
 });
 /** Parse `lipo -detailed_info` into deterministic slice metadata. */
 export const parseLipoArchitectures = (output) => {
+    // lipo echoes a thin file's pathname verbatim, including embedded newlines.
+    // Match its final architecture field before splitting records into lines.
+    const thinArchitecture = /(?:^|\r?\n)Non-fat file:[\s\S]* is architecture: ([^\s]+)\s*$/u.exec(output)?.[1];
+    if (thinArchitecture !== undefined)
+        return [
+            architectureSchema.parse({
+                name: thinArchitecture,
+                cpu_type: null,
+                cpu_subtype: null,
+                file_offset: null,
+                size: null,
+                alignment: null,
+            }),
+        ];
     const architectures = [];
     let current;
     const flush = () => {

package/dist/native/parsers/otool.js

@@ -11,7 +11,7 @@ export const parseOtoolLoadCommands = (raw) => {
     const output = normalizeLineEndings(raw);
     const header = parseHeader(output);
     const state = createLoadCommandState(header?.flags);
-    for (const block of output.split(/(?=Load command \d+)/u))
+    for (const block of output.split(/(?=^Load command \d+$)/mu))
         parseLoadCommand(block, state);
     return {
         fileType: header?.fileType ?? null,

package/dist/native/parsers/plist.js

@@ -1,17 +1,175 @@
 import { z } from "zod";
 import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { projectPlistValue, } from "../../domain/apple/plistValue.js";
+import { omitPrototypeKeys, omittedPrototypeKeysLimitation, parseXmlPropertyList, } from "../../domain/propertyListKeys.js";
 import { err, ok } from "../../domain/result.js";
-import { safeParseJson } from "../../domain/safeJson.js";
 const plistObject = z.record(z.string(), z.unknown());
-/** Parse plutil JSON output and project stable bundle metadata. */
-export const parsePlistJson = (output) => {
+/** Digits of a JSON number literal that has no fraction or exponent. */
+const INTEGRAL_LITERAL = /^-?\d+$/u;
+/**
+ * Decode plutil JSON, passing each integral number literal beyond the exact
+ * range of a JavaScript number, with its source digits, to `unsafe`.
+ */
+const decodePlistJson = (output, unsafe) => {
     // plutil output can carry a UTF-8 BOM, which JSON.parse rejects outright.
-    const parsed = safeParseJson(output.replace(/^\uFEFF/u, ""));
-    if (!parsed.ok)
-        return err(new AnalysisOutputError("inspect_plist", parsed.error, {
-            cause: parsed.cause,
-        }));
-    const value = parsed.value;
+    const text = output.replace(/^\uFEFF/u, "");
+    return JSON.parse(text, (_key, item, context) => {
+        const source = context?.source;
+        return typeof item !== "number" ||
+            Number.isSafeInteger(item) ||
+            source === undefined ||
+            !INTEGRAL_LITERAL.test(source)
+            ? item
+            : unsafe(item, source);
+    });
+};
+/**
+ * Whether plutil JSON holds an integral number beyond the exact range of a
+ * JSON number. JSON prints an integral `<real>` and an `<integer>` alike, so
+ * such a number's element type must be read from plutil's XML conversion.
+ */
+export const plistJsonNeedsNumberTypes = (output) => {
+    let found = false;
+    try {
+        decodePlistJson(output, (item) => {
+            found = true;
+            return item;
+        });
+    }
+    catch {
+        // Malformed JSON is reported by `parsePlistJson`.
+    }
+    return found;
+};
+/**
+ * Parse plutil JSON output and project stable bundle metadata. An integer
+ * beyond the exact range of a JSON number keeps its decimal text when
+ * `xmlConversion`, plutil's XML form of the same plist, shows that it came
+ * from an `<integer>` rather than a `<real>`.
+ */
+export const parsePlistJson = (output, xmlConversion) => {
+    const literals = xmlConversion === undefined ? undefined : xmlNumberLiterals(xmlConversion);
+    let exactIntegerCount = 0;
+    let ambiguousNumberCount = 0;
+    const classify = (item, digits) => {
+        const exact = BigInt(digits).toString();
+        const integer = literals?.integers.get(item)?.has(exact) === true;
+        const real = literals?.reals.has(item) === true;
+        if (integer && !real) {
+            exactIntegerCount += 1;
+            return { $plist_type: "integer", decimal: digits };
+        }
+        // An integral <real> decodes exactly; only its JSON spelling is integral.
+        if (real && !integer)
+            return item;
+        ambiguousNumberCount += 1;
+        return item;
+    };
+    let decoded;
+    try {
+        decoded = omitPrototypeKeys(decodePlistJson(output, classify));
+    }
+    catch (cause) {
+        return err(new AnalysisOutputError("inspect_plist", cause instanceof Error ? cause.message : String(cause), { cause }));
+    }
+    const { value } = decoded;
+    return ok({
+        value,
+        bundle: projectPlistBundle(value),
+        limitations: [
+            ...numberLimitations(exactIntegerCount, ambiguousNumberCount),
+            ...prototypeKeyLimitations(decoded.omittedPrototypeKeys),
+        ],
+    });
+};
+/**
+ * Parse plutil XML output for a plist that JSON cannot express, such as one
+ * containing data, dates, or non-finite reals.
+ */
+export const parsePlistXml = (output) => {
+    let projected;
+    let omittedPrototypeKeys;
+    try {
+        const decoded = parseXmlPropertyList(output);
+        omittedPrototypeKeys = decoded.omittedPrototypeKeys;
+        projected = projectPlistValue(decoded.value);
+    }
+    catch (cause) {
+        return err(new AnalysisOutputError("inspect_plist", "plutil XML conversion was not a readable plist", { cause }));
+    }
+    // The XML decoder turns <integer> and <real> into numbers before REA sees
+    // them, rounding integers beyond the exact range.
+    const literals = xmlNumberLiterals(output);
+    let exactIntegerCount = 0;
+    let ambiguousNumberCount = 0;
+    const value = mapJsonNumbers(projected.value, (item) => {
+        const decimals = literals.integers.get(item);
+        if (decimals === undefined)
+            return item;
+        const [decimal] = decimals;
+        if (decimals.size !== 1 ||
+            decimal === undefined ||
+            literals.reals.has(item)) {
+            ambiguousNumberCount += 1;
+            return item;
+        }
+        exactIntegerCount += 1;
+        return { $plist_type: "integer", decimal };
+    });
+    return ok({
+        value,
+        bundle: projectPlistBundle(value),
+        limitations: [
+            'plutil cannot express this plist as JSON, so it was decoded from plutil\'s XML conversion; data and date values are typed objects such as { "$plist_type": "data", "base64": ... }.',
+            ...(projected.unknownRealCount === 0
+                ? []
+                : [
+                    `${String(projected.unknownRealCount)} non-finite real value(s) are reported as { "$plist_type": "real", "value": null } because the XML decoder does not distinguish NaN from infinity.`,
+                ]),
+            ...numberLimitations(exactIntegerCount, ambiguousNumberCount),
+            ...prototypeKeyLimitations(omittedPrototypeKeys),
+        ],
+    });
+};
+// plutil escapes "<" in keys and strings, so these element literals can be
+// read from the XML text.
+const xmlNumberLiterals = (xml) => {
+    const integers = new Map();
+    for (const [, decimal = ""] of xml.matchAll(/<integer>\s*([+-]?\d+)\s*<\/integer>/gu)) {
+        const rounded = Number(decimal);
+        if (Number.isSafeInteger(rounded))
+            continue;
+        integers.set(rounded, (integers.get(rounded) ?? new Set()).add(BigInt(decimal).toString()));
+    }
+    const reals = new Set([...xml.matchAll(/<real>([^<]*)<\/real>/gu)].map(([, text = ""]) => Number.parseFloat(text)));
+    return { integers, reals };
+};
+const prototypeKeyLimitations = (count) => count === 0 ? [] : [omittedPrototypeKeysLimitation(count)];
+const numberLimitations = (exactIntegerCount, ambiguousNumberCount) => [
+    ...(exactIntegerCount === 0
+        ? []
+        : [
+            `${String(exactIntegerCount)} integer value(s) exceed the exact range of a JSON number and are reported as { "$plist_type": "integer", "decimal": "<exact digits>" }.`,
+        ]),
+    ...(ambiguousNumberCount === 0
+        ? []
+        : [
+            `${String(ambiguousNumberCount)} number(s) beyond the exact range of a JSON number are reported as decoded because the XML literal they came from, a rounded <integer> or a <real>, cannot be identified.`,
+        ]),
+];
+const mapJsonNumbers = (value, map) => {
+    if (typeof value === "number")
+        return map(value);
+    if (Array.isArray(value))
+        return value.map((item) => mapJsonNumbers(item, map));
+    if (value !== null && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            mapJsonNumbers(item, map),
+        ]));
+    return value;
+};
+const projectPlistBundle = (value) => {
     const object = plistObject.safeParse(value);
     const field = (name) => {
         if (!object.success)
@@ -19,14 +177,11 @@ export const parsePlistJson = (output) => {
         const candidate = object.data[name];
         return typeof candidate === "string" ? candidate : null;
     };
-    return ok({
-        value,
-        bundle: {
-            identifier: field("CFBundleIdentifier"),
-            executable: field("CFBundleExecutable"),
-            name: field("CFBundleName"),
-            version: field("CFBundleVersion"),
-            short_version: field("CFBundleShortVersionString"),
-        },
-    });
+    return {
+        identifier: field("CFBundleIdentifier"),
+        executable: field("CFBundleExecutable"),
+        name: field("CFBundleName"),
+        version: field("CFBundleVersion"),
+        short_version: field("CFBundleShortVersionString"),
+    };
 };

package/dist/native/pwndbg/PwndbgCoreContext.js

@@ -0,0 +1,160 @@
+import { access, mkdir, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { recordedCrashDebuggerSchema, } from "../../domain/native/recordedCrash.js";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { runOwnedCommand } from "../../process/OwnedCommand.js";
+import { capturedPwntoolsOutput, pwntoolsDecoderFailure, } from "../pwntools/PwntoolsFailures.js";
+import { PWNTOOLS_LIMITS } from "../pwntools/PwntoolsRelease.js";
+import { readPwntoolsFailureEvidence } from "../pwntools/PwntoolsResourceLimits.js";
+const OPERATION = "inspect_recorded_crash";
+const replySchema = z.discriminatedUnion("ok", [
+    z.strictObject({ ok: z.literal(true), value: recordedCrashDebuggerSchema }),
+    z.strictObject({
+        ok: z.literal(false),
+        reason: z.enum([
+            "unavailable",
+            "unsupported",
+            "decoder",
+            "format",
+            "output-limit",
+        ]),
+        message: z.string(),
+    }),
+]);
+/** Add mapping candidates from an owned core-only debugger, using the existing snapshot. */
+export const inspectPwndbgCore = async ({ environment, rootPath, diagnostics, options, launcher, }) => {
+    const gdb = environment.REA_PWNDBG_GDB ?? "/usr/bin/gdb";
+    const entry = environment.REA_PWNDBG_GDBINIT ?? "";
+    const venv = environment.REA_PWNDBG_VENV_PATH ?? "";
+    const unavailable = (message, cause) => new AnalysisCapabilityUnavailableError("pwndbg-core", OPERATION, message, {
+        ...(cause === undefined ? {} : { cause }),
+        userMessage: message,
+        capturedOutput: diagnostics,
+    });
+    for (const [key, path, kind] of [
+        ["REA_PWNDBG_GDB", gdb, "file"],
+        ["REA_PWNDBG_GDBINIT", entry, "file"],
+        ["REA_PWNDBG_VENV_PATH", venv, "directory"],
+    ]) {
+        try {
+            if (!isAbsolute(path))
+                throw new Error("Expected an absolute caller-supplied path.");
+            await access(path, key === "REA_PWNDBG_GDB" ? constants.X_OK : constants.R_OK);
+            const information = await stat(path);
+            if (kind === "file" ? !information.isFile() : !information.isDirectory())
+                throw new Error(`Expected a ${kind}.`);
+        }
+        catch (cause) {
+            throw unavailable(`${key} is unavailable at ${path}: ${cause instanceof Error ? cause.message : String(cause)}. Configure the requested core-only context, or omit include_debugger_context for basic recorded evidence.`, cause);
+        }
+    }
+    const stage = join(rootPath, "debugger");
+    await mkdir(stage, { mode: 0o700 });
+    const requestPath = join(stage, "request.json");
+    const replyPath = join(stage, "reply.json");
+    await writeFile(requestPath, JSON.stringify({
+        snapshot_path: join(rootPath, "object.snapshot"),
+        reply_path: replyPath,
+        gdb,
+        gdbinit: entry,
+        venv,
+    }), { flag: "wx", mode: 0o600 });
+    let output;
+    try {
+        options?.signal?.throwIfAborted();
+        const execution = await runOwnedCommand({
+            command: environment.REA_PWNTOOLS_PYTHON ?? "",
+            arguments: [
+                "-I",
+                fileURLToPath(new URL("../../../bridge/pwndbg/launch.py", import.meta.url)),
+                join(stage, "resource.failure"),
+                requestPath,
+            ],
+            cwd: stage,
+            runId: `rea-recorded-core-debugger-${randomUUID()}`,
+            hostEnvironment: {
+                ...environment,
+                PWNDBG_NO_AUTOUPDATE: "1",
+                PWNDBG_VENV_PATH: venv,
+                PWNLIB_NOTERM: "1",
+                TERM: "dumb",
+                HOME: stage,
+                XDG_CACHE_HOME: join(stage, "cache"),
+                XDG_CONFIG_HOME: join(stage, "config"),
+                PYTHONNOUSERSITE: "1",
+                OPENBLAS_NUM_THREADS: "1",
+                OMP_NUM_THREADS: "1",
+            },
+        }, {
+            timeoutMs: PWNTOOLS_LIMITS.timeoutMs,
+            diagnosticBytes: PWNTOOLS_LIMITS.diagnosticBytes,
+        }, {
+            ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            ...(launcher === undefined ? {} : { launcher }),
+        });
+        output = capturedPwntoolsOutput(execution);
+        let reply;
+        try {
+            const raw = await readStableArtifact(replyPath, PWNTOOLS_LIMITS.outputBytes, options?.signal);
+            reply = replySchema.parse(JSON.parse(raw.bytes.toString("utf8")));
+        }
+        catch (cause) {
+            if (options?.signal?.aborted)
+                throw new AnalysisCancelledError(OPERATION, {
+                    capturedOutput: recordedCrashStageOutput(diagnostics, output),
+                });
+            throw new AnalysisOutputError(OPERATION, `Core-only debugger reply failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+                cause,
+                capturedOutput: recordedCrashStageOutput(diagnostics, output),
+            });
+        }
+        if (!reply.ok) {
+            if (reply.reason === "unavailable" || reply.reason === "unsupported")
+                throw new AnalysisCapabilityUnavailableError("pwndbg-core", OPERATION, reply.message, {
+                    userMessage: reply.message,
+                    capturedOutput: recordedCrashStageOutput(diagnostics, output),
+                });
+            if (reply.reason === "format" || reply.reason === "output-limit")
+                throw new AnalysisOutputError(OPERATION, reply.message, {
+                    capturedOutput: recordedCrashStageOutput(diagnostics, output),
+                });
+            throw new ProviderAdapterError("pwndbg-core", OPERATION, {
+                diagnostics: {
+                    stage: "debugger",
+                    reason: reply.message,
+                    captured_output: { ...recordedCrashStageOutput(diagnostics, output) },
+                },
+            });
+        }
+        if (reply.value.status !== "available")
+            throw new AnalysisOutputError(OPERATION, "Requested debugger context returned no core evidence.", { capturedOutput: recordedCrashStageOutput(diagnostics, output) });
+        return { ...reply.value, diagnostics: output };
+    }
+    catch (cause) {
+        if (options?.signal?.aborted &&
+            (cause === options.signal.reason ||
+                (cause instanceof Error && cause.name === "AbortError")))
+            throw new AnalysisCancelledError(OPERATION, {
+                capturedOutput: recordedCrashStageOutput(diagnostics, output),
+            });
+        throw pwntoolsDecoderFailure(cause, "debugger", gdb, environment.REA_PWNTOOLS_PYTHON ?? "", await readPwntoolsFailureEvidence(cause, stage), {
+            operation: OPERATION,
+            providerId: "pwndbg-core",
+            precedingOutput: diagnostics,
+        });
+    }
+};
+/** Preserve both stages' exact text and their independently observed truncation state. */
+export const recordedCrashStageOutput = (basic, debuggerOutput) => debuggerOutput === undefined
+    ? basic
+    : {
+        stdout: `[core decoder]\n${basic.stdout}\n[debugger]\n${debuggerOutput.stdout}`,
+        stderr: `[core decoder]\n${basic.stderr}\n[debugger]\n${debuggerOutput.stderr}`,
+        truncated: basic.truncated || debuggerOutput.truncated,
+    };