rea-agents 4.1.0 → 5.0.0

package/dist/native/AppleMachoFixups.js

@@ -0,0 +1,292 @@
+const POINTER_FORMATS = {
+    1: "DYLD_CHAINED_PTR_ARM64E",
+    2: "DYLD_CHAINED_PTR_64",
+    6: "DYLD_CHAINED_PTR_64_OFFSET",
+    9: "DYLD_CHAINED_PTR_ARM64E_USERLAND",
+    12: "DYLD_CHAINED_PTR_ARM64E_USERLAND24",
+};
+const bits = (value, from, width) => (value >> BigInt(from)) & ((1n << BigInt(width)) - 1n);
+const signed = (value, width) => value >= 1n << BigInt(width - 1) ? value - (1n << BigInt(width)) : value;
+/** Library ordinal to install name; 0 and negative ordinals are special lookups. */
+const libraryName = (ordinal, dylibs) => {
+    if (ordinal > 0)
+        return dylibs[ordinal - 1] ?? null;
+    return null;
+};
+const cString = (bytes, offset, end) => {
+    const stop = bytes.indexOf(0, offset);
+    if (offset < 0 || offset >= end || stop < 0 || stop >= end)
+        throw new RangeError("Fixup symbol name is outside the symbol pool");
+    return bytes.toString("utf8", offset, stop);
+};
+const readImports = (data, header) => {
+    const { bytes, base, end, dylibs } = data;
+    const size = header.format === 3 ? 16 : header.format === 2 ? 8 : 4;
+    if (header.format < 1 || header.format > 3)
+        throw new RangeError(`Unsupported chained import format ${header.format}`);
+    if (base + header.offset + header.count * size > end)
+        throw new RangeError("Chained import table exceeds the fixup data");
+    return Array.from({ length: header.count }, (_, index) => {
+        const at = base + header.offset + index * size;
+        if (header.format === 3) {
+            const word = bytes.readBigUInt64LE(at);
+            const ordinal = Number(signed(bits(word, 0, 16), 16));
+            return {
+                symbol: cString(bytes, base + header.symbols + Number(bits(word, 32, 32)), end),
+                library: libraryName(ordinal, dylibs),
+                weak: bits(word, 16, 1) === 1n,
+                addend: bytes.readBigInt64LE(at + 8),
+            };
+        }
+        const word = bytes.readUInt32LE(at);
+        const ordinal = Number(signed(BigInt(word & 0xff), 8));
+        return {
+            symbol: cString(bytes, base + header.symbols + (word >>> 9), end),
+            library: libraryName(ordinal, dylibs),
+            weak: ((word >>> 8) & 1) === 1,
+            addend: header.format === 2 ? BigInt(bytes.readInt32LE(at + 4)) : 0n,
+        };
+    });
+};
+/** Decode one raw chained pointer for its segment's pointer format. */
+export const decodeChainedPointer = (raw, format, baseAddress, imports) => {
+    const bind = (ordinal, addend) => {
+        const target = imports[Number(ordinal)];
+        if (target === undefined)
+            throw new RangeError(`Chained bind ordinal ${ordinal} has no import`);
+        return { kind: "bind", ...target, addend: target.addend + addend };
+    };
+    if (format === 2 || format === 6) {
+        if (bits(raw, 63, 1) === 1n)
+            return bind(bits(raw, 0, 24), bits(raw, 24, 8));
+        const target = bits(raw, 0, 36) | (bits(raw, 36, 8) << 56n);
+        return {
+            kind: "rebase",
+            target: format === 6 ? target + baseAddress : target,
+        };
+    }
+    if (format === 1 || format === 9 || format === 12) {
+        const auth = bits(raw, 63, 1) === 1n;
+        if (bits(raw, 62, 1) === 1n)
+            return bind(bits(raw, 0, format === 12 ? 24 : 16), auth ? 0n : signed(bits(raw, 32, 19), 19));
+        if (auth)
+            return { kind: "rebase", target: bits(raw, 0, 32) + baseAddress };
+        const target = bits(raw, 0, 43) | (bits(raw, 43, 8) << 56n);
+        return {
+            kind: "rebase",
+            target: format === 1 ? target : target + baseAddress,
+        };
+    }
+    throw new RangeError(`Unsupported chained pointer format ${format}`);
+};
+const chainedFixups = (image, range) => {
+    const { bytes, segments, dylibs, baseAddress } = image;
+    const base = range.offset;
+    const end = range.offset + range.size;
+    if (range.size < 28 || end > bytes.length)
+        throw new RangeError("Chained fixup header exceeds the target");
+    const startsOffset = bytes.readUInt32LE(base + 4);
+    const imports = readImports({ bytes, base, end, dylibs }, {
+        offset: bytes.readUInt32LE(base + 8),
+        symbols: bytes.readUInt32LE(base + 12),
+        count: bytes.readUInt32LE(base + 16),
+        format: bytes.readUInt32LE(base + 20),
+    });
+    if (bytes.readUInt32LE(base + 24) !== 0)
+        throw new RangeError("Compressed chained-fixup symbol names are not supported");
+    const starts = base + startsOffset;
+    const segmentCount = bytes.readUInt32LE(starts);
+    const ranges = [];
+    for (let index = 0; index < segmentCount; index++) {
+        const infoOffset = bytes.readUInt32LE(starts + 4 + index * 4);
+        if (infoOffset === 0)
+            continue;
+        const segment = segments[index];
+        if (segment === undefined || starts + infoOffset + 22 > end)
+            throw new RangeError("Chained fixup segment table is out of range");
+        ranges.push({
+            from: segment.address,
+            to: segment.address + segment.size,
+            format: bytes.readUInt16LE(starts + infoOffset + 6),
+        });
+    }
+    const formats = [
+        ...new Set(ranges.map(({ format }) => POINTER_FORMATS[format] ?? `format-${format}`)),
+    ];
+    return {
+        kind: "chained",
+        formats,
+        failures: [],
+        decode(address, raw) {
+            const segment = ranges.find(({ from, to }) => address >= from && address < to);
+            // Pointers outside fixup segments, such as in __TEXT, are stored plainly.
+            if (segment === undefined)
+                return { kind: "rebase", target: raw };
+            if (raw === 0n)
+                return { kind: "rebase", target: 0n };
+            return decodeChainedPointer(raw, segment.format, baseAddress, imports);
+        },
+    };
+};
+const uleb = (bytes, cursor, end) => {
+    let value = 0n;
+    let shift = 0n;
+    for (;;) {
+        if (cursor.at >= end)
+            throw new RangeError("Truncated bind opcode operand");
+        const byte = bytes[cursor.at++] ?? 0;
+        value |= BigInt(byte & 0x7f) << shift;
+        shift += 7n;
+        if ((byte & 0x80) === 0)
+            return value;
+        if (shift > 63n)
+            throw new RangeError("Oversized bind opcode operand");
+    }
+};
+const sleb = (bytes, cursor, end) => {
+    let value = 0n;
+    let shift = 0n;
+    let byte = 0;
+    do {
+        if (cursor.at >= end)
+            throw new RangeError("Truncated bind opcode operand");
+        byte = bytes[cursor.at++] ?? 0;
+        value |= BigInt(byte & 0x7f) << shift;
+        shift += 7n;
+    } while ((byte & 0x80) !== 0 && shift <= 63n);
+    return (byte & 0x40) !== 0 ? value - (1n << shift) : value;
+};
+/** Apply a bind opcode that sets a register; false when the opcode is not one. */
+const setBindRegister = (image, stream, state, byte) => {
+    const { bytes } = image;
+    const { cursor, end } = stream;
+    const immediate = byte & 0x0f;
+    switch (byte & 0xf0) {
+        case 0x10:
+            state.ordinal = immediate;
+            return true;
+        case 0x20:
+            state.ordinal = Number(uleb(bytes, cursor, end));
+            return true;
+        case 0x30:
+            state.ordinal = immediate === 0 ? 0 : immediate - 16;
+            return true;
+        case 0x40: {
+            const stop = bytes.indexOf(0, cursor.at);
+            if (stop < 0 || stop >= end)
+                throw new RangeError("Unterminated bind symbol");
+            state.symbol = bytes.toString("utf8", cursor.at, stop);
+            state.weak = (immediate & 0x1) !== 0;
+            cursor.at = stop + 1;
+            return true;
+        }
+        case 0x50:
+            return true;
+        case 0x60:
+            state.addend = sleb(bytes, cursor, end);
+            return true;
+        case 0x70: {
+            const segment = image.segments[immediate];
+            if (segment === undefined)
+                throw new RangeError("Bind segment index is out of range");
+            state.address = segment.address + uleb(bytes, cursor, end);
+            return true;
+        }
+        case 0x80:
+            // ULEB deltas wrap at 64 bits to encode negative steps.
+            state.address =
+                (state.address + uleb(bytes, cursor, end)) & 0xffffffffffffffffn;
+            return true;
+        default:
+            return false;
+    }
+};
+/** Interpret one `LC_DYLD_INFO` bind opcode stream into address -> import. */
+const readBindStream = (image, range, binds) => {
+    const { bytes } = image;
+    const end = range.offset + range.size;
+    if (end > bytes.length)
+        throw new RangeError("Bind opcodes exceed the target");
+    const cursor = { at: range.offset };
+    const state = {
+        ordinal: 0,
+        symbol: "",
+        weak: false,
+        addend: 0n,
+        address: 0n,
+    };
+    const bind = (skip) => {
+        binds.set(state.address, {
+            symbol: state.symbol,
+            library: range.stream === "weak"
+                ? null
+                : libraryName(state.ordinal, image.dylibs),
+            weak: state.weak,
+            addend: state.addend,
+        });
+        state.address += 8n + skip;
+    };
+    while (cursor.at < end) {
+        const byte = bytes[cursor.at++] ?? 0;
+        if (setBindRegister(image, { cursor, end }, state, byte))
+            continue;
+        switch (byte & 0xf0) {
+            case 0x00:
+                // DONE separates lazy-bind entries; other streams end here.
+                if (range.stream !== "lazy")
+                    return;
+                break;
+            case 0x90:
+                bind(0n);
+                break;
+            case 0xa0:
+                bind(uleb(bytes, cursor, end));
+                break;
+            case 0xb0:
+                bind(BigInt(byte & 0x0f) * 8n);
+                break;
+            case 0xc0: {
+                const count = uleb(bytes, cursor, end);
+                const skip = uleb(bytes, cursor, end);
+                for (let index = 0n; index < count; index++)
+                    bind(skip);
+                break;
+            }
+            default:
+                throw new RangeError(`Unsupported bind opcode 0x${byte.toString(16)}`);
+        }
+    }
+};
+/** Build pointer decoding for one slice from its fixup load commands. */
+export const parsePointerFixups = (bytes, commands, segments, baseAddress) => {
+    const image = { bytes, segments, dylibs: commands.dylibs, baseAddress };
+    if (commands.chained !== null)
+        return chainedFixups(image, commands.chained);
+    if (commands.binds.length === 0)
+        return {
+            kind: "none",
+            formats: [],
+            failures: [],
+            decode: (_address, raw) => ({ kind: "rebase", target: raw }),
+        };
+    const binds = new Map();
+    const failures = [];
+    for (const stream of commands.binds)
+        try {
+            readBindStream(image, stream, binds);
+        }
+        catch (cause) {
+            failures.push(`${stream.stream} bind opcodes: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+    return {
+        kind: "dyld-info",
+        formats: [],
+        failures,
+        decode(address, raw) {
+            const bound = binds.get(address);
+            return bound === undefined
+                ? { kind: "rebase", target: raw }
+                : { kind: "bind", ...bound };
+        },
+    };
+};

package/dist/native/AppleMachoSelection.js

@@ -0,0 +1,188 @@
+const hex = (value) => `0x${value.toString(16)}`;
+/** Classify a FAT magic word; thin Mach-O returns null. */
+export const fatHeaderFormat = (magic) => {
+    switch (magic) {
+        case 0xcafebabe:
+            return { littleEndian: false, fat64: false };
+        case 0xcafebabf:
+            return { littleEndian: false, fat64: true };
+        case 0xbebafeca:
+            return { littleEndian: true, fat64: false };
+        case 0xbfbafeca:
+            return { littleEndian: true, fat64: true };
+        default:
+            return null;
+    }
+};
+/** Select the thin Mach-O slice for `architecture` inside a FAT or thin container. */
+export const selectMachoSlice = (bytes, architecture) => {
+    const magic = bytes.readUInt32BE(0);
+    const header = fatHeaderFormat(magic);
+    if (header === null)
+        return { slice: 0, sliceEnd: bytes.length };
+    const { littleEndian, fat64 } = header;
+    const stride = fat64 ? 32 : 20;
+    const readUInt32 = littleEndian
+        ? (offset) => bytes.readUInt32LE(offset)
+        : (offset) => bytes.readUInt32BE(offset);
+    const readUInt64 = littleEndian
+        ? (offset) => bytes.readBigUInt64LE(offset)
+        : (offset) => bytes.readBigUInt64BE(offset);
+    const byteOrder = littleEndian ? "little-endian" : "big-endian";
+    const malformed = (reason) => new RangeError(`${reason} (FAT header byte order: ${byteOrder})`);
+    const invalid = (reason) => new TypeError(`${reason} (FAT header byte order: ${byteOrder})`);
+    if (bytes.length < 8)
+        throw malformed("Malformed FAT architecture table");
+    const count = readUInt32(4);
+    const headerEnd = 8 + count * stride;
+    if (count > 128 || headerEnd > bytes.length)
+        throw malformed("Malformed FAT architecture table");
+    const cpu = architecture === "arm64" ? 0x0100000c : 0x01000007;
+    let selected;
+    for (let index = 0; index < count; index++) {
+        const offset = 8 + index * stride;
+        if (readUInt32(offset) !== cpu)
+            continue;
+        if (selected !== undefined)
+            throw invalid("Ambiguous FAT architecture slice");
+        const start = fat64
+            ? readUInt64(offset + 8)
+            : BigInt(readUInt32(offset + 8));
+        const size = fat64
+            ? readUInt64(offset + 16)
+            : BigInt(readUInt32(offset + 12));
+        if (start < BigInt(headerEnd) || start + size > BigInt(bytes.length))
+            throw malformed("FAT slice exceeds file");
+        selected = { slice: Number(start), sliceEnd: Number(start + size) };
+    }
+    if (selected === undefined)
+        throw invalid("Requested FAT architecture is absent");
+    return selected;
+};
+/** Parse segments/sections for a little-endian 64-bit Mach-O architecture slice. */
+export const parseMachoLayout = (bytes, architecture) => {
+    if (bytes.length < 4)
+        throw new RangeError("Truncated Mach-O header");
+    const { slice, sliceEnd } = selectMachoSlice(bytes, architecture);
+    if (slice === 0 && sliceEnd === bytes.length && bytes.length < 32)
+        throw new RangeError("Truncated Mach-O header");
+    if (slice + 32 > sliceEnd || bytes.readUInt32LE(slice) !== 0xfeedfacf)
+        throw new TypeError("Only little-endian 64-bit Mach-O metadata is supported");
+    const commands = bytes.readUInt32LE(slice + 16);
+    const commandEnd = slice + 32 + bytes.readUInt32LE(slice + 20);
+    if (commands > 4096 || commandEnd > sliceEnd)
+        throw new RangeError("Malformed Mach-O command bounds");
+    const state = {
+        slice,
+        sliceEnd,
+        segments: [],
+        sections: [],
+        dylibs: [],
+        binds: [],
+        chained: null,
+        baseAddress: undefined,
+    };
+    let cursor = slice + 32;
+    for (let index = 0; index < commands; index++) {
+        if (cursor + 8 > commandEnd)
+            throw new RangeError("Truncated load command");
+        const command = {
+            cursor,
+            kind: bytes.readUInt32LE(cursor),
+            size: bytes.readUInt32LE(cursor + 4),
+        };
+        if (command.size < 8 || cursor + command.size > commandEnd)
+            throw new RangeError("Invalid load command size");
+        if (command.kind === 0x19)
+            collectSegment(bytes, command, state);
+        else
+            collectFixupCommand(bytes, command, state);
+        cursor += command.size;
+    }
+    const { segments, sections, chained, binds, dylibs } = state;
+    const offset = (address, size = 1) => {
+        const matches = segments.filter((segment) => address >= segment.address &&
+            address + BigInt(size) <= segment.address + segment.size);
+        if (matches.length !== 1)
+            throw new RangeError(`Unmapped or ambiguous metadata pointer ${hex(address)}`);
+        const segment = matches[0];
+        if (segment === undefined)
+            throw new RangeError("Missing metadata segment");
+        return segment.offset + Number(address - segment.address);
+    };
+    return {
+        segments,
+        sections,
+        offset,
+        fixups: { chained, binds, dylibs },
+        baseAddress: state.baseAddress ?? 0n,
+    };
+};
+/** Record an `LC_SEGMENT_64` and its section table. */
+const collectSegment = (bytes, { cursor, size }, state) => {
+    if (size < 72)
+        throw new RangeError("Truncated segment command");
+    const address = bytes.readBigUInt64LE(cursor + 24), fileSize = bytes.readBigUInt64LE(cursor + 48), fileOffset = bytes.readBigUInt64LE(cursor + 40);
+    if (fileOffset + fileSize > BigInt(state.sliceEnd - state.slice))
+        throw new RangeError("Segment file range exceeds target bytes");
+    state.segments.push({
+        address,
+        size: fileSize,
+        offset: state.slice + Number(fileOffset),
+        executable: (bytes.readUInt32LE(cursor + 60) & 4) !== 0,
+    });
+    if (fileOffset === 0n && fileSize > 0n)
+        state.baseAddress ??= address;
+    const count = bytes.readUInt32LE(cursor + 64);
+    if (72 + count * 80 > size)
+        throw new RangeError("Truncated section table");
+    for (let section = 0; section < count; section++) {
+        const position = cursor + 72 + section * 80;
+        const sectionSize = bytes.readBigUInt64LE(position + 40);
+        if (sectionSize > BigInt(Number.MAX_SAFE_INTEGER))
+            throw new RangeError("Section size exceeds exact numeric range");
+        state.sections.push({
+            name: bytes
+                .subarray(position, position + 16)
+                .toString("ascii")
+                .replace(/\0.*$/u, ""),
+            address: bytes.readBigUInt64LE(position + 32),
+            size: Number(sectionSize),
+        });
+    }
+};
+const LC_DYLD_INFO = 0x22;
+const LC_DYLD_INFO_ONLY = 0x80000022;
+const LC_DYLD_CHAINED_FIXUPS = 0x80000034;
+const DYLIB_COMMANDS = [
+    0xc, 0x80000018, 0x8000001f, 0x20, 0x80000023,
+];
+/** Record fixup data ranges and dylib install names from one load command. */
+const collectFixupCommand = (bytes, { cursor, kind, size }, state) => {
+    const range = (at) => {
+        const offset = state.slice + bytes.readUInt32LE(at);
+        const length = bytes.readUInt32LE(at + 4);
+        if (offset + length > state.sliceEnd)
+            throw new RangeError("Fixup data exceeds the Mach-O slice");
+        return { offset, size: length };
+    };
+    if (kind === LC_DYLD_CHAINED_FIXUPS && size >= 16)
+        state.chained = range(cursor + 8);
+    else if ((kind === LC_DYLD_INFO || kind === LC_DYLD_INFO_ONLY) && size >= 48)
+        for (const [at, stream] of [
+            [cursor + 16, "bind"],
+            [cursor + 24, "weak"],
+            [cursor + 32, "lazy"],
+        ]) {
+            const bound = range(at);
+            if (bound.size > 0)
+                state.binds.push({ ...bound, stream });
+        }
+    else if (DYLIB_COMMANDS.includes(kind) && size >= 24) {
+        const nameOffset = bytes.readUInt32LE(cursor + 8);
+        const end = bytes.indexOf(0, cursor + nameOffset);
+        state.dylibs.push(nameOffset >= size || end < 0 || end > cursor + size
+            ? ""
+            : bytes.toString("utf8", cursor + nameOffset, end));
+    }
+};

package/dist/native/AppleObjcCategories.js

@@ -0,0 +1,59 @@
+import { readObjcPropertiesOf } from "./AppleObjcProperties.js";
+const CLASS_SYMBOL = /^_OBJC_(?:META)?CLASS_\$_(.+)$/u;
+/** External class name from a bound `_OBJC_CLASS_$_Name` symbol. */
+export const boundClassName = (read, field) => {
+    const bound = read.bound(field);
+    return bound === undefined ? undefined : CLASS_SYMBOL.exec(bound.symbol)?.[1];
+};
+/**
+ * Decode `__objc_catlist` `category_t` records:
+ * name, cls, instanceMethods, classMethods, protocols, instanceProperties.
+ */
+export const decodeObjcCategories = (input) => {
+    const { read, result, failures } = input;
+    let examined = 0;
+    for (const section of input.sections.filter(({ name }) => name === "__objc_catlist")) {
+        if (section.size % 8 !== 0)
+            throw new RangeError("Misaligned Objective-C category list");
+        for (let index = 0; index < section.size / 8; index++) {
+            if (!input.admit())
+                break;
+            examined++;
+            const field = section.address + BigInt(index * 8);
+            try {
+                const category = read.pointer(field);
+                const name = read.string(read.pointer(category));
+                const external = boundClassName(read, category + 8n);
+                const local = read.pointer(category + 8n);
+                const className = external ?? (local === 0n ? null : input.localClassName(local));
+                const owner = className ?? `(${name})`;
+                result.objc_categories.push({
+                    name,
+                    class_name: className,
+                    class_source: external !== undefined
+                        ? "external"
+                        : className === null
+                            ? "unresolved"
+                            : "local",
+                    instance_methods: input.methods(read.pointer(category + 16n), owner, "instance", name),
+                    class_methods: input.methods(read.pointer(category + 24n), owner, "class", name),
+                    protocols: input.protocols(read.pointer(category + 32n)),
+                    properties: readObjcPropertiesOf(read, read.pointer(category + 40n), {
+                        owner: `category ${name}`,
+                        admit: input.admit,
+                        failures,
+                    }),
+                    location: read.location(category),
+                    decode: className === null
+                        ? { status: "partial", reason: "category_class_unresolved" }
+                        : { status: "decoded", reason: null },
+                    evidence: read.evidence(category, "Objective-C category_t record"),
+                });
+            }
+            catch (cause) {
+                failures.push(`Category at ${`0x${field.toString(16)}`}: ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        }
+    }
+    return examined;
+};