rea-agents 0.3.0 → 0.5.0

package/dist/native/NativeMacOSProvider.js

@@ -0,0 +1,306 @@
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { realpath, stat } from "node:fs/promises";
+import { parse as parseXmlPlist } from "plist";
+import { z } from "zod";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { NATIVE_TOOL_CONTRACTS, } from "../contracts/nativeToolContracts.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, AnalysisTimeoutError, ProviderAdapterError, } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { demangleSwiftSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/nativeInspection.js";
+import { err, ok } from "../domain/result.js";
+import { NativeCommandFailure, XcrunCommandRunner, } from "./CommandRunner.js";
+import { parseCodeSignature } from "./parsers/codesign.js";
+import { parseDemangledSymbols } from "./parsers/demangle.js";
+import { parseLipoArchitectures } from "./parsers/lipo.js";
+import { parsePlistJson } from "./parsers/plist.js";
+import { architectureLocations, inspectNativeMacho, } from "./NativeMachoInspection.js";
+const IDENTITY = Object.freeze({
+    id: "native-macos",
+    name: "macOS native inspection utilities",
+    version: null,
+});
+const TIMEOUT_MS = 30_000;
+const OUTPUT_LIMIT = 4 * 1024 * 1024;
+/** Read-only semantic provider composed from Xcode command-line utilities. */
+export class NativeMacOSProvider {
+    runner;
+    #capabilities;
+    constructor(runner = new XcrunCommandRunner(), platform = process.platform) {
+        this.runner = runner;
+        const available = platform === "darwin";
+        this.#capabilities = Object.freeze(NATIVE_TOOL_CONTRACTS.map((contract) => {
+            const availability = available
+                ? { available: true, reason: null }
+                : {
+                    available: false,
+                    reason: "Native macOS utilities require macOS.",
+                };
+            return Object.freeze({
+                provider: IDENTITY,
+                operation: contract.name,
+                inputContractVersion: 1,
+                outputContractVersion: 1,
+                ...availability,
+                pagination: "none",
+                exhaustive: contract.name !== "inspect_macho",
+                effects: Object.freeze({
+                    mutatesArtifact: false,
+                    launchesProcess: true,
+                    mayShowUi: false,
+                    mayAccessNetwork: false,
+                    mayWriteFilesystem: false,
+                    changesPermissions: false,
+                    requiresRoot: false,
+                }),
+                limits: Object.freeze({
+                    maxResults: contract.name === "demangle_swift" ? 500 : null,
+                    maxPayloadBytes: OUTPUT_LIMIT,
+                    timeoutMs: TIMEOUT_MS,
+                }),
+                limitations: Object.freeze([
+                    "Availability and textual formats depend on the installed macOS/Xcode toolchain.",
+                ]),
+            });
+        }));
+    }
+    identity() {
+        return IDENTITY;
+    }
+    capabilities() {
+        return this.#capabilities;
+    }
+    createClient(target) {
+        return new NativeMacOSClient(target, this.runner);
+    }
+}
+class NativeMacOSClient {
+    target;
+    runner;
+    constructor(target, runner) {
+        this.target = target;
+        this.runner = runner;
+    }
+    async execute(operation, parameters, options) {
+        if (operation === "health")
+            return ok(createAnalysisExecution(null, IDENTITY));
+        if (!isNativeOperation(operation))
+            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Operation is not implemented by native macOS tools."));
+        try {
+            const observation = await this.#dispatch(operation, parameters, options?.signal);
+            return observation.ok
+                ? ok(createAnalysisExecution(observation.value.result, IDENTITY, {
+                    rawResult: { provenance: observation.value.provenance },
+                    limitations: observation.value.limitations,
+                    locations: observation.value.locations,
+                }))
+                : observation;
+        }
+        catch (cause) {
+            return err(new AnalysisOutputError(operation, "Native output parsing failed", {
+                cause,
+            }));
+        }
+    }
+    close() {
+        return Promise.resolve();
+    }
+    #dispatch(operation, parameters, signal) {
+        switch (operation) {
+            case "inspect_macho":
+                return this.#inspectMacho(signal);
+            case "inspect_signature":
+                return this.#inspectSignature(signal);
+            case "inspect_plist":
+                return this.#inspectPlist(parameters, signal);
+            case "list_architectures":
+                return this.#listArchitectures(signal);
+            case "demangle_swift":
+                return this.#demangle(parameters, signal);
+        }
+    }
+    async #listArchitectures(signal) {
+        const capture = await this.#run("list_architectures", "lipo", ["-detailed_info", this.target.path], { signal });
+        if (!capture.ok)
+            return capture;
+        const provenance = [invocation(capture.value, this.target.path)];
+        const result = listArchitecturesSchema.parse({
+            architectures: {
+                items: parseLipoArchitectures(capture.value.stdout),
+                total: parseLipoArchitectures(capture.value.stdout).length,
+                exhaustive: true,
+                limitations: [],
+            },
+            provenance,
+            limitations: [],
+        });
+        return ok({
+            result: jsonValueSchema.parse(result),
+            provenance,
+            limitations: [],
+            locations: architectureLocations(result.architectures.items),
+        });
+    }
+    async #demangle(parameters, signal) {
+        const symbols = z.array(z.string()).safeParse(parameters.symbols);
+        if (!symbols.success)
+            return err(new AnalysisOutputError("demangle_swift", "symbols were not parsed strings"));
+        const capture = await this.#run("demangle_swift", "swift-demangle", ["--compact", ...symbols.data], { signal });
+        if (!capture.ok)
+            return capture;
+        const provenance = [invocation(capture.value, this.target.path)];
+        const result = demangleSwiftSchema.parse({
+            symbols: parseDemangledSymbols(symbols.data, capture.value.stdout),
+            provenance,
+            limitations: [],
+        });
+        return ok({
+            result: jsonValueSchema.parse(result),
+            provenance,
+            limitations: [],
+            locations: [],
+        });
+    }
+    async #inspectSignature(signal) {
+        const display = await this.#run("inspect_signature", "codesign", ["-d", "--verbose=4", this.target.path], { signal, acceptNonZero: true });
+        if (!display.ok)
+            return display;
+        const requirements = await this.#run("inspect_signature", "codesign", ["-d", "-r-", this.target.path], { signal, acceptNonZero: true });
+        if (!requirements.ok)
+            return requirements;
+        const entitlements = await this.#run("inspect_signature", "codesign", ["-d", "--entitlements", ":-", this.target.path], { signal, acceptNonZero: true });
+        if (!entitlements.ok)
+            return entitlements;
+        const unsigned = /not signed at all|code object is not signed/iu.test(`${display.value.stdout}\n${display.value.stderr}`);
+        const parsed = parseCodeSignature(`${display.value.stdout}\n${display.value.stderr}`, unsigned);
+        const requirementText = /designated\s*=>\s*(.+)$/mu.exec(`${requirements.value.stdout}\n${requirements.value.stderr}`)?.[1] ?? null;
+        const entitlementValue = parseEntitlements(`${entitlements.value.stdout}\n${entitlements.value.stderr}`);
+        const provenance = [
+            display.value,
+            requirements.value,
+            entitlements.value,
+        ].map((capture) => invocation(capture, this.target.path));
+        const result = inspectSignatureSchema.parse({
+            ...parsed,
+            designated_requirement: requirementText,
+            entitlements: entitlementValue,
+            provenance,
+        });
+        return ok({
+            result: jsonValueSchema.parse(result),
+            provenance,
+            limitations: result.limitations,
+            locations: [],
+        });
+    }
+    async #inspectPlist(parameters, signal) {
+        const requested = parameters.relative_path;
+        if (typeof requested !== "string")
+            return err(new AnalysisOutputError("inspect_plist", "relative_path was not a string"));
+        const plist = await resolvePlistPath(this.target, requested);
+        if (!plist.ok)
+            return plist;
+        const classified = await this.#run("inspect_plist", "file", ["-b", plist.value], { signal });
+        if (!classified.ok)
+            return classified;
+        const capture = await this.#run("inspect_plist", "plutil", ["-convert", "json", "-o", "-", "--", plist.value], { signal });
+        if (!capture.ok)
+            return capture;
+        const parsed = parsePlistJson(capture.value.stdout);
+        const provenance = [classified.value, capture.value].map((item) => invocation(item, plist.value, "$PLIST"));
+        const result = inspectPlistSchema.parse({
+            format: /binary property list/iu.test(classified.value.stdout)
+                ? "binary"
+                : /XML|text/iu.test(classified.value.stdout)
+                    ? "xml"
+                    : "unknown",
+            ...parsed,
+            source_path: requested,
+            provenance,
+            limitations: [],
+        });
+        return ok({
+            result: jsonValueSchema.parse(result),
+            provenance,
+            limitations: [],
+            locations: [{ kind: "artifact-path", path: requested }],
+        });
+    }
+    async #inspectMacho(signal) {
+        if (this.target.format !== "mach-o")
+            return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, "inspect_macho", "Active artifact is not Mach-O."));
+        return inspectNativeMacho({
+            target: this.target,
+            ...(signal === undefined ? {} : { signal }),
+            run: (tool, arguments_, commandSignal) => this.#run("inspect_macho", tool, arguments_, {
+                signal: commandSignal,
+            }),
+            invocation: (capture) => invocation(capture, this.target.path),
+        });
+    }
+    async #run(operation, tool, arguments_, options = {}) {
+        const captured = await this.runner.run(tool, arguments_, {
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            timeoutMs: TIMEOUT_MS,
+            maxOutputBytes: OUTPUT_LIMIT,
+            acceptNonZero: options.acceptNonZero ?? false,
+        });
+        if (captured.ok)
+            return captured;
+        return err(translateCommandFailure(operation, captured.error));
+    }
+}
+const isNativeOperation = (operation) => NATIVE_TOOL_CONTRACTS.some(({ name }) => name === operation);
+const translateCommandFailure = (operation, failure) => {
+    if (failure.reason === "unavailable")
+        return new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `${failure.tool} is unavailable through xcrun.`);
+    if (failure.reason === "cancelled")
+        return new AnalysisCancelledError(operation);
+    if (failure.reason === "timeout")
+        return new AnalysisTimeoutError(operation, TIMEOUT_MS);
+    return new ProviderAdapterError(IDENTITY.id, operation, { cause: failure });
+};
+const invocation = (capture, artifactPath, alias = "$ARTIFACT") => ({
+    tool: capture.tool,
+    command: [
+        capture.executable,
+        ...capture.arguments.map((argument) => argument === artifactPath ? alias : argument),
+    ],
+    tool_version: capture.toolVersion,
+    version_reason: capture.versionReason,
+    executable_sha256: capture.executableSha256,
+    exit: { code: capture.exitCode, signal: capture.signal },
+    stdout_bytes: capture.stdoutBytes,
+    stderr_bytes: capture.stderrBytes,
+    stdout_truncated: capture.stdoutTruncated,
+    stderr_truncated: capture.stderrTruncated,
+});
+const parseEntitlements = (output) => {
+    const start = output.indexOf("<?xml");
+    const end = output.lastIndexOf("</plist>");
+    if (start < 0 || end < start)
+        return null;
+    return jsonValueSchema.parse(parseXmlPlist(output.slice(start, end + "</plist>".length)));
+};
+const resolvePlistPath = async (target, requested) => {
+    try {
+        const source = target.sourcePath ?? target.path;
+        const sourceMetadata = await stat(source);
+        const root = sourceMetadata.isDirectory() ? source : dirname(target.path);
+        const candidate = resolve(root, requested);
+        if (!within(root, candidate))
+            return err(new ProviderAdapterError(IDENTITY.id, "inspect_plist"));
+        const canonicalRoot = await realpath(root);
+        const canonical = await realpath(candidate);
+        if (!within(canonicalRoot, canonical))
+            return err(new ProviderAdapterError(IDENTITY.id, "inspect_plist"));
+        return ok(canonical);
+    }
+    catch (cause) {
+        return err(new ProviderAdapterError(IDENTITY.id, "inspect_plist", { cause }));
+    }
+};
+const within = (root, candidate) => {
+    const child = relative(root, candidate);
+    return (child === "" ||
+        (!child.startsWith(`..${sep}`) && child !== ".." && !isAbsolute(child)));
+};

package/dist/native/NativeMachoInspection.js

@@ -0,0 +1,135 @@
+import { inspectMachoSchema, } from "../domain/nativeInspection.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { parseDyldSymbols } from "./parsers/dyldInfo.js";
+import { parseLipoArchitectures } from "./parsers/lipo.js";
+import { parseOtoolLoadCommands } from "./parsers/otool.js";
+const COMMANDS = [
+    ["file", ["-b"]],
+    ["lipo", ["-detailed_info"]],
+    ["otool", ["-l"]],
+    ["nm", ["-gjU"]],
+    ["dyld_info", ["-imports"]],
+    ["dyld_info", ["-exports"]],
+    ["dwarfdump", ["--uuid"]],
+    ["vtool", ["-show-build"]],
+];
+/** Inspect one Mach-O with bounded native commands and normalized output. */
+export const inspectNativeMacho = async (context) => {
+    const captures = [];
+    for (const [tool, prefix] of COMMANDS) {
+        const captured = await context.run(tool, [...prefix, context.target.path], context.signal);
+        if (!captured.ok)
+            return err(captured.error);
+        captures.push(captured.value);
+    }
+    const result = normalizeMacho(captures, context.invocation);
+    return ok({
+        result: jsonValueSchema.parse(result),
+        provenance: result.provenance,
+        limitations: result.limitations,
+        locations: fileOffsetLocations(result),
+    });
+};
+const normalizeMacho = (captures, toInvocation) => {
+    const byTool = captureLookup(captures);
+    const architectures = parseLipoArchitectures(byTool("lipo").stdout);
+    const load = parseOtoolLoadCommands(byTool("otool").stdout);
+    const imports = parseDyldSymbols(byTool("dyld_info", 0).stdout, "imports");
+    const dyldExports = parseDyldSymbols(byTool("dyld_info", 1).stdout, "exports");
+    const exports = uniqueSymbols([
+        ...dyldExports,
+        ...parseNmExports(byTool("nm").stdout),
+    ]);
+    const uuid = /UUID:\s*([A-Fa-f0-9-]+)/u.exec(byTool("dwarfdump").stdout)?.[1] ??
+        load.uuid;
+    const provenance = captures.map(toInvocation);
+    const limitations = [
+        "Imports and exports combine dyld_info and nm; stripped or toolchain-hidden symbols may be absent.",
+        "vtool output is retained as provenance but only otool build metadata is normalized.",
+    ];
+    return inspectMachoSchema.parse({
+        format: "mach-o",
+        endian: parseEndian(byTool("file").stdout),
+        word_size: parseWordSize(byTool("file").stdout),
+        file_type: load.fileType,
+        flags: load.flags,
+        uuid: uuid ?? null,
+        entrypoints: covered(load.entrypoints, true),
+        architectures: covered(architectures, true),
+        build_metadata: covered(load.builds, true),
+        load_commands: covered(load.commands, true),
+        dependencies: covered(load.dependencies, true),
+        imports: covered(imports, false, [
+            "dyld_info textual imports may omit chained or toolchain-unsupported metadata.",
+        ]),
+        exports: covered(exports, false, [
+            "Merged nm/dyld_info results may be incomplete for stripped binaries.",
+        ]),
+        segments: covered(load.segments.map((segment) => ({
+            ...segment,
+            sections: covered(segment.sections, true),
+        })), true),
+        provenance,
+        limitations,
+    });
+};
+const captureLookup = (captures) => (tool, occurrence = 0) => {
+    const capture = captures.filter((item) => item.tool === tool)[occurrence];
+    if (capture === undefined)
+        throw new TypeError(`Missing ${tool} capture`);
+    return capture;
+};
+const parseNmExports = (output) => output
+    .split(/\r?\n/u)
+    .filter((name) => name.length > 0)
+    .map((name) => ({
+    name,
+    address: null,
+    weak: null,
+    reexport: null,
+    source: "nm",
+}));
+const parseEndian = (output) => /little-endian/iu.test(output)
+    ? "little"
+    : /big-endian/iu.test(output)
+        ? "big"
+        : null;
+const parseWordSize = (output) => /64-bit/iu.test(output) ? 64 : /32-bit/iu.test(output) ? 32 : null;
+const covered = (items, exhaustive, limitations = []) => ({
+    items: [...items],
+    total: exhaustive ? items.length : null,
+    exhaustive,
+    limitations: [...limitations],
+});
+const uniqueSymbols = (items) => {
+    const unique = new Map();
+    for (const item of items)
+        unique.set(item.name, item);
+    return [...unique.values()].sort((left, right) => left.name.localeCompare(right.name));
+};
+const fileOffsetLocations = (macho) => {
+    const locations = architectureLocations(macho.architectures.items);
+    for (const segment of macho.segments.items) {
+        if (segment.file_offset === null || segment.file_size === null)
+            continue;
+        locations.push({
+            kind: "file-offset-range",
+            start: segment.file_offset,
+            end: segment.file_offset + segment.file_size,
+        });
+    }
+    return locations;
+};
+/** Project architecture slices into evidence file-offset locations. */
+export const architectureLocations = (architectures) => {
+    const locations = [];
+    for (const { file_offset: offset, size } of architectures) {
+        if (offset === null)
+            continue;
+        locations.push(size === null
+            ? { kind: "file-offset", offset }
+            : { kind: "file-offset-range", start: offset, end: offset + size });
+    }
+    return locations;
+};

package/dist/native/parsers/codesign.js

@@ -0,0 +1,55 @@
+import { inspectSignatureSchema, } from "../../domain/nativeInspection.js";
+/** Parse bounded `codesign -d` diagnostics, which Apple emits on stderr. */
+export const parseCodeSignature = (output, unsigned) => {
+    const values = new Map();
+    const authorities = [];
+    const cdhashes = [];
+    for (const line of output.split(/\r?\n/u)) {
+        if (line.startsWith("CodeDirectory ")) {
+            values.set("CodeDirectory", line.slice("CodeDirectory ".length));
+            continue;
+        }
+        const separator = line.indexOf("=");
+        if (separator < 1)
+            continue;
+        const key = line.slice(0, separator).trim();
+        const value = line.slice(separator + 1).trim();
+        if (key === "Authority")
+            authorities.push(value);
+        else if (key === "CDHash")
+            cdhashes.push(value);
+        else
+            values.set(key, value);
+    }
+    const parsed = inspectSignatureSchema.omit({ provenance: true }).parse({
+        signed: !unsigned,
+        identifier: values.get("Identifier") ?? null,
+        team_identifier: nullableCodeSignValue(values.get("TeamIdentifier")),
+        format: values.get("Format") ?? null,
+        cdhashes,
+        hash_algorithms: splitAlgorithms(values.get("Hash choices")),
+        authorities,
+        designated_requirement: values.get("designated") ?? null,
+        entitlements: null,
+        timestamp: values.get("Timestamp") ?? null,
+        hardened_runtime: parseRuntime(values.get("CodeDirectory")),
+        limitations: unsigned
+            ? ["Artifact is not signed."]
+            : [
+                "Entitlements and designated requirements require separate bounded commands.",
+            ],
+    });
+    return parsed;
+};
+const nullableCodeSignValue = (value) => value === undefined || value === "not set" ? null : value;
+const splitAlgorithms = (value) => value === undefined
+    ? []
+    : value
+        .split(/[,+\s]+/u)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+const parseRuntime = (value) => {
+    if (value === undefined)
+        return null;
+    return /\bruntime\b/u.test(value);
+};

package/dist/native/parsers/demangle.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+const resultSchema = z.object({
+    input: z.string(),
+    output: z.string(),
+    status: z.enum(["demangled", "unchanged", "invalid"]),
+});
+/** Preserve input ordering while parsing `swift-demangle --compact` lines. */
+export const parseDemangledSymbols = (inputs, output) => {
+    const lines = output.trimEnd().split(/\r?\n/u);
+    if (lines.length !== inputs.length)
+        throw new TypeError("swift-demangle output count does not match input");
+    return inputs.map((input, index) => {
+        const value = lines[index];
+        if (value === undefined)
+            throw new TypeError("swift-demangle omitted an output line");
+        return resultSchema.parse({
+            input,
+            output: value,
+            status: value === input
+                ? input.startsWith("$s") || input.startsWith("_$s")
+                    ? "invalid"
+                    : "unchanged"
+                : "demangled",
+        });
+    });
+};

package/dist/native/parsers/dyldInfo.js

@@ -0,0 +1,25 @@
+/** Parse bounded imports/exports from dyld_info's line-oriented tables. */
+export const parseDyldSymbols = (output, mode) => output.split(/\r?\n/u).flatMap((rawLine) => {
+    const line = rawLine.trim();
+    if (line.length === 0 ||
+        /^(?:imports|exports|binding|address|segment|ordinal)\b/iu.test(line))
+        return [];
+    const tokens = line.split(/\s+/u);
+    const name = tokens.at(-1);
+    if (name === undefined || !/^(?:_|\$s|objc_|swift_)/u.test(name))
+        return [];
+    const addressToken = tokens.find((token) => /^0x[a-fA-F0-9]+$/u.test(token));
+    return [
+        {
+            name,
+            address: addressToken ?? null,
+            weak: /\bweak\b/iu.test(line) ? true : null,
+            reexport: /\bre-?export\b/iu.test(line)
+                ? true
+                : mode === "exports"
+                    ? false
+                    : null,
+            source: mode === "imports" ? (tokens.at(-2) ?? null) : null,
+        },
+    ];
+});

package/dist/native/parsers/lipo.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+const architectureSchema = z.object({
+    name: z.string().min(1),
+    cpu_type: z.string().nullable(),
+    cpu_subtype: z.string().nullable(),
+    file_offset: z.number().int().min(0).nullable(),
+    size: z.number().int().min(0).nullable(),
+    alignment: z.number().int().min(0).nullable(),
+});
+/** Parse `lipo -detailed_info` into deterministic slice metadata. */
+export const parseLipoArchitectures = (output) => {
+    const architectures = [];
+    let current;
+    const flush = () => {
+        if (current === undefined)
+            return;
+        const name = current.architecture ?? current["Non-fat file"];
+        if (name !== undefined)
+            architectures.push(architectureSchema.parse({
+                name: name.includes(" is architecture: ")
+                    ? (name.split(" is architecture: ").at(-1) ?? name)
+                    : name,
+                cpu_type: current.cputype ?? null,
+                cpu_subtype: current.cpusubtype ?? null,
+                file_offset: integer(current.offset),
+                size: integer(current.size),
+                alignment: alignment(current.align),
+            }));
+        current = undefined;
+    };
+    for (const rawLine of output.split(/\r?\n/u)) {
+        const line = rawLine.trim();
+        if (line.startsWith("Non-fat file:")) {
+            flush();
+            current = { "Non-fat file": line };
+            continue;
+        }
+        if (line.startsWith("architecture ")) {
+            flush();
+            current = { architecture: line.slice("architecture ".length).trim() };
+            continue;
+        }
+        const match = /^(cputype|cpusubtype|offset|size|align)\s+(.+)$/u.exec(line);
+        if (match?.[1] !== undefined && match[2] !== undefined) {
+            current ??= {};
+            current[match[1]] = match[2].trim();
+        }
+    }
+    flush();
+    if (architectures.length === 0)
+        throw new TypeError("lipo output contained no architectures");
+    return architectures;
+};
+const integer = (value) => {
+    if (value === undefined)
+        return null;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
+};
+const alignment = (value) => {
+    if (value === undefined)
+        return null;
+    const exponent = /2\^(\d+)/u.exec(value)?.[1];
+    if (exponent !== undefined)
+        return 2 ** Number.parseInt(exponent, 10);
+    return integer(value);
+};