reverseport 0.0.0-stage → 1.2.0

package/dist/native/AppleMachoFixups.js

@@ -0,0 +1,372 @@
+import { issue } from "./AppleDispatchDecodeFacts.js";
+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 readImport = (data, header, index) => {
+    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 (!Number.isSafeInteger(header.count) ||
+        base + header.offset + header.count * size > end)
+        throw new RangeError("Chained import table exceeds the fixup data");
+    if (index < 0 || index >= header.count)
+        throw new RangeError("Chained import index is outside the table");
+    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 = typeof imports === "function"
+            ? imports(Number(ordinal))
+            : 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 importHeader = {
+        offset: bytes.readUInt32LE(base + 8),
+        symbols: bytes.readUInt32LE(base + 12),
+        count: bytes.readUInt32LE(base + 16),
+        format: bytes.readUInt32LE(base + 20),
+    };
+    const importSize = importHeader.format === 3 ? 16 : importHeader.format === 2 ? 8 : 4;
+    const importTableEnd = base + importHeader.offset + importHeader.count * importSize;
+    if (importHeader.format < 1 || importHeader.format > 3)
+        throw new RangeError(`Unsupported chained import format ${importHeader.format}`);
+    if (!Number.isSafeInteger(importHeader.count) || importTableEnd > end)
+        throw new RangeError("Chained import table exceeds the fixup data");
+    const imports = (index) => readImport({ bytes, base, end, dylibs }, importHeader, index);
+    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}`)),
+    ];
+    const issues = ranges.flatMap(({ format, from }) => POINTER_FORMATS[format] === undefined
+        ? [
+            issue("pointer_fixups", "unsupported_pointer_format", `Unsupported chained pointer format ${format}`, `0x${from.toString(16)}`),
+        ]
+        : []);
+    return {
+        kind: "chained",
+        formats,
+        failures: issues.map(({ message }) => message),
+        issues,
+        examined: Math.max(ranges.length, 1),
+        unreadRebaseBytes: 0,
+        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 };
+            if (POINTER_FORMATS[segment.format] === undefined)
+                return {
+                    kind: "unsupported",
+                    reason: `Unsupported chained pointer format ${segment.format}`,
+                };
+            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.segmentIndex = immediate;
+            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,
+        segmentIndex: -1,
+        symbol: "",
+        weak: false,
+        addend: 0n,
+        address: 0n,
+    };
+    const preflightRun = (count, skip) => {
+        if (count === 0n)
+            return;
+        const segment = image.segments[state.segmentIndex];
+        if (segment === undefined)
+            throw new RangeError("Bind location has no selected segment");
+        const stride = 8n + skip;
+        const end = state.address + (count - 1n) * stride + 8n;
+        if (state.address < segment.address || end > segment.address + segment.size)
+            throw new RangeError("Bind expansion leaves its file-backed segment");
+    };
+    const bind = (count, skip) => {
+        if (count === 0n)
+            return;
+        preflightRun(count, skip);
+        const stride = 8n + skip;
+        const binding = {
+            symbol: state.symbol,
+            library: range.stream === "weak"
+                ? null
+                : libraryName(state.ordinal, image.dylibs),
+            weak: state.weak,
+            addend: state.addend,
+        };
+        const previous = binds.at(-1);
+        if (previous !== undefined &&
+            previous.stride === stride &&
+            previous.start + previous.count * stride === state.address &&
+            previous.binding.symbol === binding.symbol &&
+            previous.binding.library === binding.library &&
+            previous.binding.weak === binding.weak &&
+            previous.binding.addend === binding.addend) {
+            previous.count += count;
+        }
+        else {
+            binds.push({ start: state.address, count, stride, binding });
+        }
+        state.address += count * stride;
+    };
+    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(1n, 0n);
+                break;
+            case 0xa0:
+                bind(1n, uleb(bytes, cursor, end));
+                break;
+            case 0xb0:
+                bind(1n, BigInt(byte & 0x0f) * 8n);
+                break;
+            case 0xc0: {
+                if (range.stream === "lazy")
+                    throw new RangeError("Lazy bind streams do not support repeated bind opcodes");
+                const count = uleb(bytes, cursor, end);
+                const skip = uleb(bytes, cursor, end);
+                bind(count, 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 };
+    const unreadRebaseBytes = commands.rebases.reduce((total, rebase) => total + rebase.size, 0);
+    if (commands.chained !== null) {
+        const chained = chainedFixups(image, commands.chained);
+        return unreadRebaseBytes === 0
+            ? chained
+            : { ...chained, unreadRebaseBytes };
+    }
+    if (commands.binds.length === 0)
+        return {
+            kind: "none",
+            formats: [],
+            failures: [],
+            issues: [],
+            examined: 0,
+            unreadRebaseBytes,
+            decode: (_address, raw) => ({ kind: "rebase", target: raw }),
+        };
+    const binds = [];
+    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,
+        issues: failures.map((message) => issue("pointer_fixups", "bind_stream_decode_failed", message)),
+        examined: commands.binds.length,
+        unreadRebaseBytes,
+        decode(address, raw) {
+            let match;
+            for (const run of binds) {
+                const { start, count, stride } = run;
+                const distance = address - start;
+                if (distance >= 0n &&
+                    distance % stride === 0n &&
+                    distance / stride < count) {
+                    if (match !== undefined)
+                        return {
+                            kind: "unsupported",
+                            reason: `Ambiguous bind records target pointer location 0x${address.toString(16)}`,
+                        };
+                    match = run;
+                }
+            }
+            return match === undefined
+                ? { kind: "rebase", target: raw }
+                : { kind: "bind", ...match.binding };
+        },
+    };
+};

package/dist/native/AppleMachoSelection.js

@@ -0,0 +1,234 @@
+import { readFatSliceDeclarations, validateFatSlice, } from "../domain/apple/machoContainer.js";
+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 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 = MACHO_CPU_TYPE[architecture];
+    if (cpu === undefined)
+        throw invalid("Requested FAT architecture is absent");
+    const declarations = readFatSliceDeclarations(bytes.subarray(8, headerEnd), {
+        count,
+        wide: fat64,
+        littleEndian,
+    });
+    if (declarations.status !== "parsed")
+        throw malformed(declarations.reason);
+    let selected;
+    for (const declaration of declarations.slices) {
+        const issue = validateFatSlice(declaration, bytes.length, headerEnd);
+        if (issue !== null)
+            throw malformed(issue);
+        if (declaration.cpuType !== cpu)
+            continue;
+        if (selected !== undefined)
+            throw invalid("Ambiguous FAT architecture slice");
+        selected = {
+            slice: declaration.offset,
+            sliceEnd: declaration.offset + declaration.size,
+            fatDeclaration: {
+                ...declaration,
+                tableEnd: headerEnd,
+            },
+        };
+    }
+    if (selected === undefined)
+        throw invalid("Requested FAT architecture is absent");
+    if (selected.slice + 4 > bytes.length)
+        throw malformed("Truncated Mach-O header");
+    const sliceMagic = bytes.readUInt32LE(selected.slice);
+    if (sliceMagic === MH_MAGIC || sliceMagic === MH_CIGAM)
+        throw invalid(`Unsupported 32-bit Mach-O metadata for requested CPU type ${architecture}`);
+    return selected;
+};
+/** CPU types admitted by `machArchitecture` in the domain binary target parser. */
+const MACHO_CPU_TYPE = {
+    x86: 7,
+    x86_64: 0x01000007,
+    arm: 12,
+    arm64: 0x0100000c,
+};
+const MH_MAGIC = 0xfeedface;
+const MH_CIGAM = 0xcefaedfe;
+/** 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 selection = selectMachoSlice(bytes, architecture);
+    const { slice, sliceEnd } = selection;
+    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 fat = selection.fatDeclaration;
+    if (fat !== undefined) {
+        const issue = validateFatSlice(fat, bytes.length, fat.tableEnd, {
+            cpuType: bytes.readUInt32LE(slice + 4),
+            cpuSubtype: bytes.readUInt32LE(slice + 8),
+        });
+        if (issue !== null)
+            throw new TypeError(issue);
+    }
+    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: [],
+        rebases: [],
+        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, rebases, 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, rebases, 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) {
+        if (size < 16)
+            throw new RangeError("Truncated chained-fixups command");
+        state.chained = range(cursor + 8);
+    }
+    else if (kind === LC_DYLD_INFO || kind === LC_DYLD_INFO_ONLY) {
+        if (size < 48)
+            throw new RangeError("Truncated dyld-info command");
+        const rebase = range(cursor + 8);
+        if (rebase.size > 0)
+            state.rebases.push(rebase);
+        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)) {
+        if (size < 24)
+            throw new RangeError("Truncated dylib command");
+        const nameOffset = bytes.readUInt32LE(cursor + 8);
+        if (nameOffset < 24 || nameOffset >= size)
+            throw new RangeError("Dylib install name is outside its load command");
+        const end = bytes.indexOf(0, cursor + nameOffset);
+        if (end < 0 || end >= cursor + size)
+            throw new RangeError("Unterminated dylib install name");
+        state.dylibs.push(bytes.toString("utf8", cursor + nameOffset, end));
+    }
+};

package/dist/native/AppleObjcCategories.js

@@ -0,0 +1,63 @@
+import { readObjcPropertiesOf } from "./AppleObjcProperties.js";
+import { issue } from "./AppleDispatchDecodeFacts.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,
+                        issues: input.issues,
+                        location: `0x${read.pointer(category + 40n).toString(16)}`,
+                    }),
+                    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) {
+                const message = cause instanceof Error ? cause.message : String(cause);
+                failures.push(`Category at 0x${field.toString(16)}: ${message}`);
+                input.issues.push(issue("objc_properties_categories", "category_decode_failed", message, `0x${field.toString(16)}`));
+            }
+        }
+    }
+    return examined;
+};