rea-agents 0.3.0 → 0.4.0

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);
+};

package/dist/native/parsers/otool.js

@@ -0,0 +1,193 @@
+/** Parse stable fields from `otool -l`, preserving unknown command fields. */
+export const parseOtoolLoadCommands = (output) => {
+    const headerTokens = parseHeaderTokens(output);
+    const state = createLoadCommandState(headerTokens);
+    for (const block of output.split(/(?=Load command \d+)/u))
+        parseLoadCommand(block, state);
+    return {
+        fileType: headerTokens?.[4] ?? null,
+        flags: [...state.flags].sort(),
+        uuid: state.uuid,
+        commands: state.commands,
+        segments: state.segments,
+        dependencies: state.dependencies,
+        entrypoints: state.entrypoints,
+        builds: state.builds,
+    };
+};
+const parseHeaderTokens = (output) => output
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .find((line) => /^0x[a-fA-F0-9]+\s/u.test(line))
+    ?.split(/\s+/u);
+const createLoadCommandState = (headerTokens) => ({
+    commands: [],
+    segments: [],
+    dependencies: [],
+    entrypoints: [],
+    builds: [],
+    uuid: null,
+    flags: new Set(headerTokens?.slice(7) ?? []),
+});
+const parseLoadCommand = (block, state) => {
+    const indexText = /^Load command (\d+)/u.exec(block)?.[1];
+    if (indexText === undefined)
+        return;
+    const header = block.split(/\n\s*Section\n/u)[0] ?? block;
+    const fields = parseFields(header);
+    const kind = stringField(fields, "cmd") ?? "unknown";
+    state.commands.push({
+        index: Number.parseInt(indexText, 10),
+        kind,
+        file_offset: null,
+        fields,
+    });
+    collectUuid(kind, fields, state);
+    collectEntrypoint(kind, fields, state);
+    collectBuild(kind, block, fields, state);
+    collectDependency(kind, fields, state);
+    collectSegment(kind, block, fields, state);
+    collectFlags(fields, state.flags);
+};
+const collectUuid = (kind, fields, state) => {
+    if (kind === "LC_UUID")
+        state.uuid = stringField(fields, "uuid") ?? state.uuid;
+};
+const collectEntrypoint = (kind, fields, state) => {
+    if (kind !== "LC_MAIN")
+        return;
+    const entry = numberField(fields, "entryoff");
+    if (entry !== null)
+        state.entrypoints.push({ file_offset: entry });
+};
+const collectBuild = (kind, block, fields, state) => {
+    if (kind !== "LC_BUILD_VERSION")
+        return;
+    state.builds.push({
+        platform: stringField(fields, "platform"),
+        minimum_os: stringField(fields, "minos"),
+        sdk: stringField(fields, "sdk"),
+        tools: parseBuildTools(block),
+    });
+};
+const collectDependency = (kind, fields, state) => {
+    if (!kind.startsWith("LC_LOAD_") && kind !== "LC_ID_DYLIB")
+        return;
+    state.dependencies.push({
+        path: stripOffsetSuffix(stringField(fields, "name")),
+        kind,
+        current_version: stringField(fields, "current version"),
+        compatibility_version: stringField(fields, "compatibility version"),
+    });
+};
+const collectSegment = (kind, block, fields, state) => {
+    if (kind === "LC_SEGMENT" || kind === "LC_SEGMENT_64")
+        state.segments.push(parseSegment(block, fields));
+};
+const collectFlags = (fields, flags) => {
+    const rawFlags = stringField(fields, "flags");
+    if (rawFlags === null)
+        return;
+    for (const flag of rawFlags.split(/\s+/u))
+        if (flag.length > 0)
+            flags.add(flag);
+};
+const parseFields = (block) => {
+    const fields = {};
+    for (const rawLine of block.split(/\r?\n/u).slice(1)) {
+        const line = rawLine.trim();
+        const match = /^(\S+(?:\s+version)?)\s+(.+)$/u.exec(line);
+        if (match?.[1] === undefined || match[2] === undefined)
+            continue;
+        const value = match[2].trim();
+        fields[match[1]] = numeric(value) ?? value;
+    }
+    return fields;
+};
+const parseSegment = (block, fields) => ({
+    name: stringField(fields, "segname") ?? "unknown",
+    vm_address: hexField(fields, "vmaddr"),
+    vm_size: numberField(fields, "vmsize"),
+    file_offset: numberField(fields, "fileoff"),
+    file_size: numberField(fields, "filesize"),
+    maximum_permissions: permissions(stringField(fields, "maxprot")),
+    initial_permissions: permissions(stringField(fields, "initprot")),
+    sections: parseSections(block),
+});
+const parseSections = (block) => block
+    .split(/(?=\n\s*Section\n)/u)
+    .slice(1)
+    .map((sectionBlock) => {
+    const fields = parseFields(`Section${sectionBlock}`);
+    return {
+        segment: stringField(fields, "segname") ?? "unknown",
+        name: stringField(fields, "sectname") ?? "unknown",
+        address: hexField(fields, "addr"),
+        size: numberField(fields, "size"),
+        file_offset: numberField(fields, "offset"),
+        alignment: sectionAlignment(numberField(fields, "align")),
+        flags: (stringField(fields, "flags") ?? "")
+            .split(/\s+/u)
+            .filter((flag) => flag.length > 0),
+    };
+});
+const parseBuildTools = (block) => {
+    const tools = [];
+    const lines = block.split(/\r?\n/u).map((line) => line.trim());
+    for (let index = 0; index < lines.length - 1; index += 1) {
+        const tool = /^tool\s+(.+)$/u.exec(lines[index] ?? "")?.[1];
+        const version = /^version\s+(.+)$/u.exec(lines[index + 1] ?? "")?.[1];
+        if (tool !== undefined && version !== undefined)
+            tools.push({ name: tool, version });
+    }
+    return tools;
+};
+const permissions = (raw) => {
+    if (raw === null)
+        return { read: null, write: null, execute: null, raw: null };
+    const numericValue = numeric(raw);
+    if (numericValue !== null)
+        return {
+            read: (numericValue & 4) !== 0,
+            write: (numericValue & 2) !== 0,
+            execute: (numericValue & 1) !== 0,
+            raw,
+        };
+    if (/^[r-][w-][x-]$/u.test(raw))
+        return {
+            read: raw[0] === "r",
+            write: raw[1] === "w",
+            execute: raw[2] === "x",
+            raw,
+        };
+    return { read: null, write: null, execute: null, raw };
+};
+const numeric = (value) => {
+    const token = value.split(/\s+/u)[0];
+    if (token === undefined || !/^(?:0x[a-fA-F0-9]+|\d+)$/u.test(token))
+        return null;
+    const parsed = Number.parseInt(token, token.startsWith("0x") ? 16 : 10);
+    return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
+};
+const stringField = (fields, name) => {
+    const value = fields[name];
+    return typeof value === "string"
+        ? value
+        : value === undefined || value === null
+            ? null
+            : String(value);
+};
+const numberField = (fields, name) => {
+    const value = fields[name];
+    return typeof value === "number"
+        ? value
+        : typeof value === "string"
+            ? numeric(value)
+            : null;
+};
+const hexField = (fields, name) => {
+    const value = numberField(fields, name);
+    return value === null ? null : `0x${value.toString(16)}`;
+};
+const stripOffsetSuffix = (value) => value?.replace(/\s+\(offset\s+\d+\)$/u, "") ?? "unknown";
+const sectionAlignment = (exponent) => exponent === null || exponent > 52 ? null : 2 ** exponent;

package/dist/native/parsers/plist.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+const plistObject = z.record(z.string(), z.unknown());
+/** Parse plutil JSON output and project stable bundle metadata. */
+export const parsePlistJson = (output) => {
+    const value = JSON.parse(output);
+    const object = plistObject.safeParse(value);
+    const field = (name) => {
+        if (!object.success)
+            return null;
+        const candidate = object.data[name];
+        return typeof candidate === "string" ? candidate : null;
+    };
+    return {
+        value,
+        bundle: {
+            identifier: field("CFBundleIdentifier"),
+            executable: field("CFBundleExecutable"),
+            name: field("CFBundleName"),
+            version: field("CFBundleVersion"),
+            short_version: field("CFBundleShortVersionString"),
+        },
+    };
+};

package/dist/reference/ReferenceSourceReader.js

@@ -0,0 +1,73 @@
+import { err, ok } from "../domain/result.js";
+import { traverseDirectory } from "./ReferenceSourceReaderEntries.js";
+import { compareNames } from "./ReferenceSourceReaderPaths.js";
+import {} from "./ReferenceSourceReaderTypes.js";
+import { isAborted, noFollowOpenSupported, prepareRoot, } from "./ReferenceSourceReaderValidate.js";
+const DEFAULT_LIMITS = {
+    maxBytes: 16 * 1024 * 1024,
+    maxEntries: 10_000,
+    maxDepth: 32,
+    maxPathBytes: 4_096,
+};
+const PATH_RACE_LIMITATION = "Path identity is revalidated around operations; Node lacks portable descriptor-relative openat traversal, so a syscall-boundary pathname race remains.";
+/** Read a bounded source tree without intentionally following symbolic links. */
+export const readReferenceSource = async (root, limits = DEFAULT_LIMITS, options = {}) => {
+    if (!noFollowOpenSupported())
+        return err({
+            tag: "reference-source-reader",
+            code: "unsupported",
+            message: "Safe no-follow file opens are unavailable",
+        });
+    const prepared = await prepareRoot(root, limits, options.signal);
+    if (!prepared.ok)
+        return prepared;
+    const { canonicalRoot, rootIdentity } = prepared.value;
+    const state = {
+        root: canonicalRoot,
+        rootIdentity,
+        limits,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.shouldExclude === undefined
+            ? {}
+            : { shouldExclude: options.shouldExclude }),
+        entries: [],
+        pending: [{ path: canonicalRoot, depth: 0 }],
+        bytesRead: 0,
+        filesSeen: 0,
+        truncated: false,
+        stopped: false,
+    };
+    const traversal = await traverse(state);
+    if (!traversal.ok)
+        return traversal;
+    state.entries.sort((left, right) => compareNames(left.path, right.path));
+    return ok({
+        root: canonicalRoot,
+        entries: state.entries,
+        bytesRead: state.bytesRead,
+        truncated: state.truncated,
+        limitations: [
+            PATH_RACE_LIMITATION,
+            ...(state.stopped
+                ? ["Traversal stopped because the entry limit was reached."]
+                : []),
+        ],
+    });
+};
+const traverse = async (state) => {
+    while (state.pending.length > 0 && !state.stopped) {
+        if (isAborted(state.signal))
+            return err({
+                tag: "reference-source-reader",
+                code: "cancelled",
+                message: "Reference source traversal cancelled",
+            });
+        const current = state.pending.pop();
+        if (current === undefined)
+            break;
+        const result = await traverseDirectory(state, current);
+        if (!result.ok)
+            return result;
+    }
+    return ok(undefined);
+};