Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
refactor(native): split Apple dispatch metadata decode facets (#855)
morluto676959ecb55b
diff --git a/src/native/AppleDispatchMetadata.ts b/src/native/AppleDispatchMetadata.tsindex c485bfc43..edd3c6d75 100644--- a/src/native/AppleDispatchMetadata.ts+++ b/src/native/AppleDispatchMetadata.ts@@ -9,22 +9,14 @@ import {import type { BinaryTarget } from "../domain/binaryTarget.js";import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";+import { parseMachoLayout } from "./AppleMachoSelection.js";+import { decodeObjcDispatchFacets } from "./AppleObjcDispatchFacets.js";+import {+ createSwiftRelativeReader,+ decodeSwiftDispatchFacets,+ type DispatchRecordBudget,+} from "./AppleSwiftDispatchFacets.js";import { decodeSwiftClassVtables } from "./AppleSwiftVtables.js";-import { createObjcProtocolReader } from "./AppleObjcProtocols.js";--interface Segment {- address: bigint;- size: bigint;- offset: number;- executable: boolean;-}-interface Section {- name: string;- address: bigint;- size: number;-}-const hex = (value: bigint) => `0x${value.toString(16)}`;-const decoded = { status: "decoded" as const, reason: null };/** Decode validated little-endian 64-bit Apple Objective-C metadata without loading target code. */export const decodeAppleDispatchMetadata = (@@ -33,79 +25,12 @@ export const decodeAppleDispatchMetadata = (provenance: { path: string; sha256: string },architecture = "arm64",): ObjcSwiftMetadata => {- 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 segments: Segment[] = [];- const sections: Section[] = [];- let cursor = slice + 32;- for (let index = 0; index < commands; index++) {- if (cursor + 8 > commandEnd) throw new RangeError("Truncated load command");- const kind = bytes.readUInt32LE(cursor),- size = bytes.readUInt32LE(cursor + 4);- if (size < 8 || cursor + size > commandEnd)- throw new RangeError("Invalid load command size");- if (kind === 0x19) {- 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(sliceEnd - slice))- throw new RangeError("Segment file range exceeds target bytes");- segments.push({- address,- size: fileSize,- offset: slice + Number(fileOffset),- executable: (bytes.readUInt32LE(cursor + 60) & 4) !== 0,- });- 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");- sections.push({- name: bytes- .subarray(position, position + 16)- .toString("ascii")- .replace(/\0.*$/u, ""),- address: bytes.readBigUInt64LE(position + 32),- size: Number(sectionSize),- });- }- }- cursor += size;- }- const offset = (address: bigint, size = 1): number => {- 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);- };+ const { segments, sections, offset } = parseMachoLayout(bytes, architecture);const u32 = (address: bigint) => bytes.readUInt32LE(offset(address, 4));const pointer = (address: bigint) =>bytes.readBigUInt64LE(offset(address, 8));const location = (address: bigint) => ({- address: hex(address),+ address: `0x${address.toString(16)}`,file_offset: offset(address),});const evidence = (address: bigint, description: string) => [@@ -129,420 +54,52 @@ export const decodeAppleDispatchMetadata = ();};const result = objcSwiftMetadataSchema.parse({ db_save_result: null });- const failures: string[] = [];- let records = 0,- examined = 0,- truncated = false;- const admit = () => {- if (records >= maxRecords) {- truncated = true;- return false;- }- records++;- return true;- };- const methods = (- list: bigint,- className: string,- methodType: "instance" | "class",- ) => {- if (list === 0n) return;- const flags = u32(list),- count = u32(list + 4n),- relative = (flags & 0x80000000) !== 0;- const stride = flags & 0xfffc;- if (stride !== (relative ? 12 : 24))- throw new TypeError(`Unsupported method stride/flags at ${hex(list)}`);- for (let index = 0; index < count; index++) {- if (!admit()) break;- const entry = list + 8n + BigInt(index * stride);- const rel = (field: bigint) => {- const displacement = bytes.readInt32LE(offset(field, 4));- const target = field + BigInt(displacement);- let fileOffset: number | null = null;- try {- fileOffset = offset(target);- } catch (cause: unknown) {- // best-effort cleanup: serialized target remains unresolved.- void cause;- }- if (admit())- result.relative_pointers.push({- field: location(field),- target: { address: hex(target), file_offset: fileOffset },- displacement,- indirectable: false,- indirect: false,- decode:- fileOffset === null- ? { status: "partial", reason: "relative_target_unmapped" }- : decoded,- evidence: evidence(- field,- "Signed-relative Objective-C method-list pointer",- ),- });- return target;- };- let selectorAddress = relative ? rel(entry) : pointer(entry);- if (relative && (flags & 0x40000000) === 0)- selectorAddress = pointer(selectorAddress);- const implementation = relative ? rel(entry + 8n) : pointer(entry + 16n);- let implementationLocation: {- address: string;- file_offset: number;- } | null = null;- try {- if (- !segments.some(- (segment) =>- segment.executable &&- implementation >= segment.address &&- implementation < segment.address + segment.size,- )- )- throw new RangeError(- "Method implementation is not in an executable segment",- );- implementationLocation = location(implementation);- } catch (cause: unknown) {- // best-effort cleanup: external/chained pointers remain unresolved.- void cause;- }- result.objc_dispatch_implementations.push({- class_name: className,- selector: string(selectorAddress),- method_type: methodType,- implementation_address: implementationLocation?.address ?? null,- location: location(entry),- decode:- implementationLocation === null- ? {- status: "partial",- reason: "implementation_pointer_unmapped_or_encoded",- }- : decoded,- evidence: evidence(- entry,- relative- ? "Encoded relative Objective-C method entry"- : "Encoded absolute Objective-C method entry",- ),- });- }- };- const protocolReader = createObjcProtocolReader({- readers: {- u32,- pointer,- string,- location,- evidence,- admit,- i32: (address) => bytes.readInt32LE(offset(address, 4)),+ let records = 0;+ const budget: DispatchRecordBudget = {+ truncated: false,+ isFull: () => records >= maxRecords,+ markTruncated: () => {+ budget.truncated = true;},- result,- failures,- });- for (const section of sections.filter(- ({ name }) => name === "__objc_protolist",- )) {- if (section.size % 8 !== 0)- throw new RangeError("Misaligned Objective-C protocol list");- for (let index = 0; index < section.size / 8; index++) {+ admit: () => {if (records >= maxRecords) {- truncated = true;- break;- }- protocolReader.record(pointer(section.address + BigInt(index * 8)));- }- }- const visited = new Set<string>();- const readClass = (address: bigint, meta = false) => {- if (address === 0n || visited.has(hex(address)) || !admit()) return;- visited.add(hex(address));- const ro = pointer(address + 32n) & ~7n;- const name = string(pointer(ro + 24n));- const superclass = pointer(address + 8n);- const root = (u32(ro) & 2) !== 0;- let superclassName: string | null = null;- if (superclass !== 0n) {- try {- superclassName = string(- pointer((pointer(superclass + 32n) & ~7n) + 24n),- );- } catch (cause: unknown) {- // Superclass resolution failure is recorded; the cause adds no identity.- void cause;- failures.push(- `Superclass pointer ${hex(superclass)} of ${name} requires unsupported binding/fixup resolution`,- );- }- }- if (superclass === 0n && !root)- failures.push(- `Superclass of ${name} requires external binding resolution`,- );- const ivarList = pointer(ro + 48n);- let ivarCount = 0;- if (ivarList !== 0n && !meta) {- const stride = u32(ivarList),- count = u32(ivarList + 4n);- if (stride !== 32)- throw new TypeError("Unsupported Objective-C ivar entry size");- ivarCount = count;- for (let index = 0; index < count; index++) {- if (!admit()) break;- const entry = ivarList + 8n + BigInt(index * stride);- const encodedOffset = pointer(entry);- let value: number | null = null;- try {- value = u32(encodedOffset);- } catch (cause: unknown) {- // Unresolved offsets are recorded; the cause adds no identity.- void cause;- failures.push(`Unresolved ivar offset pointer ${hex(encodedOffset)}`);- }- result.objc_ivars.push({- class_name: name,- name: string(pointer(entry + 8n)),- type_encoding: string(pointer(entry + 16n)),- offset: value,- size: u32(entry + 28n),- alignment: u32(entry + 24n) < 31 ? 2 ** u32(entry + 24n) : null,- location: location(entry),- decode:- value === null- ? { status: "partial", reason: "ivar_offset_pointer_unresolved" }- : decoded,- evidence: evidence(- entry,- "Objective-C ivar entry and encoded offset storage",- ),- });- }- }- methods(pointer(ro + 32n), name, meta ? "class" : "instance");- result.objc_classes.push({- name,- super_class: superclassName,- is_meta_class: meta,- is_root_class: root,- methods: result.objc_dispatch_implementations- .filter(- (item) =>- item.class_name === name &&- item.method_type === (meta ? "class" : "instance"),- )- .map((item) => ({- selector: item.selector,- method_type: item.method_type,- address:- item.implementation_address !== null &&- BigInt(item.implementation_address) <=- BigInt(Number.MAX_SAFE_INTEGER)- ? Number(BigInt(item.implementation_address))- : null,- is_required: false,- is_optional: false,- })),- properties: [],- protocols: protocolReader.list(pointer(ro + 40n)),- ivar_count: ivarCount,- instance_size: u32(ro + 8n),- location: location(address),- superclass_address: superclass === 0n ? null : hex(superclass),- metaclass_address: meta ? null : hex(pointer(address)),- decode:- superclassName === null && !root- ? { status: "partial", reason: "superclass_binding_unresolved" }- : decoded,- evidence: evidence(address, "Objective-C class and class_ro_t records"),- });- if (!meta) {- try {- readClass(pointer(address), true);- } catch (cause) {- failures.push(- `Metaclass of ${name}: ${cause instanceof Error ? cause.message : String(cause)}`,- );+ budget.truncated = true;+ return false;}- }+ records++;+ return true;+ },};- for (const section of sections.filter(- ({ name }) => name === "__objc_classlist",- )) {- if (section.size % 8 !== 0)- throw new RangeError("Misaligned Objective-C class-list size");- for (let index = 0; index < section.size / 8; index++) {- if (records >= maxRecords) {- truncated = true;- break;- }- examined++;- const field = section.address + BigInt(index * 8);- try {- readClass(pointer(field));- } catch (cause) {- failures.push(- `${hex(field)}: ${cause instanceof Error ? cause.message : String(cause)}`,- );- }- }- }- const swiftRelative = (field: bigint, indirectable = false): bigint => {- const displacement = bytes.readInt32LE(offset(field, 4));- const indirect = indirectable && (displacement & 1) !== 0;- let target =- displacement === 0- ? 0n- : field + BigInt(indirectable ? displacement & ~1 : displacement);- let fileOffset: number | null = null;- let reason: string | null = null;- try {- if (indirect && target !== 0n) target = pointer(target);- if (target !== 0n) fileOffset = offset(target);- } catch (cause) {- reason = cause instanceof Error ? cause.message : String(cause);- }- if (admit())- result.relative_pointers.push({- field: location(field),- target: {- address: target === 0n ? null : hex(target),- file_offset: fileOffset,- },- displacement,- indirectable,- indirect,- decode: reason === null ? decoded : { status: "partial", reason },- evidence: evidence(field, "Swift ABI signed-relative metadata pointer"),- });- if (reason !== null) throw new RangeError(reason);- return target;+ const readers = {+ u32,+ i32: (address: bigint) => bytes.readInt32LE(offset(address, 4)),+ pointer,+ string,+ location,+ evidence,+ offset,};- const swiftFailures: string[] = [];- let swiftExamined = 0;- for (const section of sections.filter(- ({ name }) => name === "__swift5_proto",- )) {- if (section.size % 4 !== 0)- throw new RangeError("Misaligned Swift conformance section");- for (let index = 0; index < section.size / 4; index++) {- if (!admit()) break;- swiftExamined++;- const field = section.address + BigInt(index * 4);- try {- const descriptor = swiftRelative(field);- const flags = u32(descriptor + 12n);- const protocol = swiftRelative(descriptor, true);- if ((u32(protocol) & 31) !== 3)- throw new TypeError("Unsupported Swift protocol descriptor kind");- const protocolName = string(swiftRelative(protocol + 8n));- const typeKind = (flags >>> 3) & 7;- if (typeKind !== 0 && typeKind !== 1)- throw new TypeError(- "Unsupported Swift conformance type-reference kind",- );- let type = swiftRelative(descriptor + 4n);- if (typeKind === 1) type = pointer(type);- if (![16, 17, 18].includes(u32(type) & 31))- throw new TypeError("Unsupported Swift type descriptor kind");- const typeName = string(swiftRelative(type + 8n));- const witness = swiftRelative(descriptor + 8n);- const staticWitness =- witness !== 0n && (flags & ~0x38) === 0 && (u32(type) & 0x80) === 0;- let witnessReason: string | null = staticWitness- ? null- : "Conditional, generic, resilient or missing static witness table is not decoded";- if (staticWitness && pointer(witness) !== descriptor)- witnessReason =- "Witness-table conformance header is unresolved or encoded";- result.swift_conformances.push({- type_name: typeName,- protocol_name: protocolName,- module: null,- witness_table:- witness === 0n- ? { address: null, file_offset: null }- : location(witness),- location: location(descriptor),- decode:- witnessReason === null- ? decoded- : {- status: "partial",- reason: witnessReason,- },- evidence: evidence(- descriptor,- "Swift protocol conformance descriptor and directly encoded type/protocol names",- ),- });- if (witnessReason !== null) {- swiftFailures.push(`${typeName}: ${witnessReason}`);- continue;- }- const count = u32(protocol + 16n);- const signatureCount = u32(protocol + 12n);- if (count > 20_000 || signatureCount > 20_000)- throw new RangeError("Swift witness requirement count exceeds 20000");- for (let slot = 0; slot < count; slot++) {- if (!admit()) break;- const entry = witness + BigInt((slot + 1) * 8);- const implementation = pointer(entry);- const requirementFlags = u32(- protocol + 24n + BigInt(signatureCount * 12 + slot * 8),- );- const kind = requirementFlags & 15;- const synchronousFunction =- kind >= 1 && kind <= 4 && (requirementFlags & 0x20) === 0;- const executable =- synchronousFunction &&- segments.some(- (segment) =>- segment.executable &&- implementation >= segment.address &&- implementation < segment.address + segment.size,- );- result.swift_dispatch_slots.push({- owner: `${typeName}: ${protocolName}`,- table_kind: "witness_table",- slot_index: slot + 1,- requirement: null,- implementation: null,- implementation_address: executable ? hex(implementation) : null,- thunk_address: null,- location: location(entry),- decode: executable- ? decoded- : {- status: "partial",- reason:- "Witness slot is non-function, async, nil, external, authenticated or encoded; implementation target is unresolved",- },- evidence: evidence(- entry,- "Static Swift witness slot, indexed after the conformance-descriptor header",- ),- });- }- } catch (cause) {- swiftFailures.push(- `${hex(field)}: ${cause instanceof Error ? cause.message : String(cause)}`,- );- }- }- }- result.coverage.push({- facet: "swift_conformances_static_witness_slots",- status: swiftFailures.length > 0 || truncated ? "partial" : "complete",- reason:- [...swiftFailures, ...(truncated ? ["max_records_reached"] : [])].join(- "; ",- ) || null,- examined: swiftExamined,- decoded: result.swift_conformances.length,+ const { failures, examined } = decodeObjcDispatchFacets({+ bytes,+ sections,+ segments,+ readers,+ budget,+ result,+ });+ const swiftRelative = createSwiftRelativeReader({+ bytes,+ readers,+ budget,+ result,+ });+ decodeSwiftDispatchFacets({+ sections,+ segments,+ readers,+ relative: swiftRelative,+ budget,+ result,});const typeEntries: bigint[] = [];for (const section of sections.filter(@@ -552,7 +109,7 @@ export const decodeAppleDispatchMetadata = (throw new RangeError("Misaligned Swift type section");for (let index = 0; index < section.size / 4 && index < maxRecords; index++)typeEntries.push(section.address + BigInt(index * 4));- if (section.size / 4 > maxRecords) truncated = true;+ if (section.size / 4 > maxRecords) budget.truncated = true;}decodeSwiftClassVtables({entries: typeEntries,@@ -563,7 +120,7 @@ export const decodeAppleDispatchMetadata = (string,location,evidence,- admit,+ admit: () => budget.admit(),executable: (address) =>segments.some((segment) =>@@ -575,21 +132,22 @@ export const decodeAppleDispatchMetadata = (});result.coverage.push({facet: "objc_class_method_ivar_metadata",- status: failures.length > 0 || truncated ? "partial" : "complete",+ status: failures.length > 0 || budget.truncated ? "partial" : "complete",reason:- [...failures, ...(truncated ? ["max_records_reached"] : [])].join("; ") ||- null,+ [...failures, ...(budget.truncated ? ["max_records_reached"] : [])].join(+ "; ",+ ) || null,examined,decoded: result.objc_classes.length,});result.coverage.push({facet: "binary_relative_pointers",status:- truncated ||+ budget.truncated ||result.relative_pointers.some((item) => item.decode.status !== "decoded")? "partial": "complete",- reason: truncated+ reason: budget.truncated? "max_records_reached": result.relative_pointers.some((item) => item.decode.status !== "decoded",@@ -661,64 +219,3 @@ export const inspectAppleDispatchMetadata = async (await handle.close();}};--const selectMachoSlice = (bytes: Buffer, architecture: string) => {- 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: number) => bytes.readUInt32LE(offset)- : (offset: number) => bytes.readUInt32BE(offset);- const readUInt64 = littleEndian- ? (offset: number) => bytes.readBigUInt64LE(offset)- : (offset: number) => bytes.readBigUInt64BE(offset);- const byteOrder = littleEndian ? "little-endian" : "big-endian";- const malformed = (reason: string) =>- new RangeError(`${reason} (FAT header byte order: ${byteOrder})`);- const invalid = (reason: string) =>- 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: { slice: number; sliceEnd: number } | undefined;- 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;-};--const fatHeaderFormat = (- magic: number,-): { readonly littleEndian: boolean; readonly fat64: boolean } | null => {- 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;- }-};diff --git a/src/native/AppleMachoSelection.ts b/src/native/AppleMachoSelection.tsnew file mode 100644index 000000000..b6de0fe34--- /dev/null+++ b/src/native/AppleMachoSelection.ts@@ -0,0 +1,172 @@+/** One mapped Mach-O segment with file-backed VA range. */+export interface Segment {+ address: bigint;+ size: bigint;+ offset: number;+ executable: boolean;+}++/** Named Mach-O section within a loaded segment. */+export interface Section {+ name: string;+ address: bigint;+ size: number;+}++/** Selected thin slice bounds inside a Mach-O or FAT container. */+export interface MachoSlice {+ slice: number;+ sliceEnd: number;+}++/** Parsed little-endian 64-bit Mach-O layout for the selected architecture slice. */+export interface MachoLayout {+ segments: Segment[];+ sections: Section[];+ /** Map a virtual address range onto a file offset within the selected slice. */+ offset(address: bigint, size?: number): number;+}++const hex = (value: bigint) => `0x${value.toString(16)}`;++/** Classify a FAT magic word; thin Mach-O returns null. */+export const fatHeaderFormat = (+ magic: number,+): { readonly littleEndian: boolean; readonly fat64: boolean } | null => {+ 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: Buffer,+ architecture: string,+): MachoSlice => {+ 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: number) => bytes.readUInt32LE(offset)+ : (offset: number) => bytes.readUInt32BE(offset);+ const readUInt64 = littleEndian+ ? (offset: number) => bytes.readBigUInt64LE(offset)+ : (offset: number) => bytes.readBigUInt64BE(offset);+ const byteOrder = littleEndian ? "little-endian" : "big-endian";+ const malformed = (reason: string) =>+ new RangeError(`${reason} (FAT header byte order: ${byteOrder})`);+ const invalid = (reason: string) =>+ 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: MachoSlice | undefined;+ 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: Buffer,+ architecture: string,+): MachoLayout => {+ 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 segments: Segment[] = [];+ const sections: Section[] = [];+ let cursor = slice + 32;+ for (let index = 0; index < commands; index++) {+ if (cursor + 8 > commandEnd) throw new RangeError("Truncated load command");+ const kind = bytes.readUInt32LE(cursor),+ size = bytes.readUInt32LE(cursor + 4);+ if (size < 8 || cursor + size > commandEnd)+ throw new RangeError("Invalid load command size");+ if (kind === 0x19) {+ 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(sliceEnd - slice))+ throw new RangeError("Segment file range exceeds target bytes");+ segments.push({+ address,+ size: fileSize,+ offset: slice + Number(fileOffset),+ executable: (bytes.readUInt32LE(cursor + 60) & 4) !== 0,+ });+ 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");+ sections.push({+ name: bytes+ .subarray(position, position + 16)+ .toString("ascii")+ .replace(/\0.*$/u, ""),+ address: bytes.readBigUInt64LE(position + 32),+ size: Number(sectionSize),+ });+ }+ }+ cursor += size;+ }+ const offset = (address: bigint, size = 1): number => {+ 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 };+};diff --git a/src/native/AppleObjcDispatchFacets.ts b/src/native/AppleObjcDispatchFacets.tsnew file mode 100644index 000000000..a20123793--- /dev/null+++ b/src/native/AppleObjcDispatchFacets.ts@@ -0,0 +1,292 @@+import type { ObjcSwiftMetadata } from "../domain/objcSwiftMetadata.js";+import type { Segment, Section } from "./AppleMachoSelection.js";+import { createObjcProtocolReader } from "./AppleObjcProtocols.js";+import type {+ BinaryMetadataEvidence,+ DispatchRecordBudget,+ ResolvedMetadataLocation,+} from "./AppleSwiftDispatchFacets.js";++/** Byte readers shared by Objective-C class/method/ivar decode facets. */+export interface ObjcDispatchReaders {+ u32(address: bigint): number;+ i32(address: bigint): number;+ pointer(address: bigint): bigint;+ string(address: bigint): string;+ location(address: bigint): ResolvedMetadataLocation;+ evidence(address: bigint, description: string): BinaryMetadataEvidence;+ offset(address: bigint, size?: number): number;+}++const hex = (value: bigint) => `0x${value.toString(16)}`;+const decoded = { status: "decoded" as const, reason: null };++/** Decode Objective-C protocol lists, classlists, methods, and ivars into `result`. */+export const decodeObjcDispatchFacets = (input: {+ bytes: Buffer;+ sections: readonly Section[];+ segments: readonly Segment[];+ readers: ObjcDispatchReaders;+ budget: DispatchRecordBudget;+ result: ObjcSwiftMetadata;+}): { failures: string[]; examined: number } => {+ const { bytes, sections, segments, readers: read, budget, result } = input;+ const failures: string[] = [];+ let examined = 0;+ const methods = (+ list: bigint,+ className: string,+ methodType: "instance" | "class",+ ) => {+ if (list === 0n) return;+ const flags = read.u32(list),+ count = read.u32(list + 4n),+ relative = (flags & 0x80000000) !== 0;+ const stride = flags & 0xfffc;+ if (stride !== (relative ? 12 : 24))+ throw new TypeError(`Unsupported method stride/flags at ${hex(list)}`);+ for (let index = 0; index < count; index++) {+ if (!budget.admit()) break;+ const entry = list + 8n + BigInt(index * stride);+ const rel = (field: bigint) => {+ const displacement = bytes.readInt32LE(read.offset(field, 4));+ const target = field + BigInt(displacement);+ let fileOffset: number | null = null;+ try {+ fileOffset = read.offset(target);+ } catch (cause: unknown) {+ // best-effort cleanup: serialized target remains unresolved.+ void cause;+ }+ if (budget.admit())+ result.relative_pointers.push({+ field: read.location(field),+ target: { address: hex(target), file_offset: fileOffset },+ displacement,+ indirectable: false,+ indirect: false,+ decode:+ fileOffset === null+ ? { status: "partial", reason: "relative_target_unmapped" }+ : decoded,+ evidence: read.evidence(+ field,+ "Signed-relative Objective-C method-list pointer",+ ),+ });+ return target;+ };+ let selectorAddress = relative ? rel(entry) : read.pointer(entry);+ if (relative && (flags & 0x40000000) === 0)+ selectorAddress = read.pointer(selectorAddress);+ const implementation = relative+ ? rel(entry + 8n)+ : read.pointer(entry + 16n);+ let implementationLocation: {+ address: string;+ file_offset: number;+ } | null = null;+ try {+ if (+ !segments.some(+ (segment) =>+ segment.executable &&+ implementation >= segment.address &&+ implementation < segment.address + segment.size,+ )+ )+ throw new RangeError(+ "Method implementation is not in an executable segment",+ );+ implementationLocation = read.location(implementation);+ } catch (cause: unknown) {+ // best-effort cleanup: external/chained pointers remain unresolved.+ void cause;+ }+ result.objc_dispatch_implementations.push({+ class_name: className,+ selector: read.string(selectorAddress),+ method_type: methodType,+ implementation_address: implementationLocation?.address ?? null,+ location: read.location(entry),+ decode:+ implementationLocation === null+ ? {+ status: "partial",+ reason: "implementation_pointer_unmapped_or_encoded",+ }+ : decoded,+ evidence: read.evidence(+ entry,+ relative+ ? "Encoded relative Objective-C method entry"+ : "Encoded absolute Objective-C method entry",+ ),+ });+ }+ };+ const protocolReader = createObjcProtocolReader({+ readers: {+ u32: read.u32,+ pointer: read.pointer,+ string: read.string,+ location: read.location,+ evidence: read.evidence,+ admit: () => budget.admit(),+ i32: read.i32,+ },+ result,+ failures,+ });+ for (const section of sections.filter(+ ({ name }) => name === "__objc_protolist",+ )) {+ if (section.size % 8 !== 0)+ throw new RangeError("Misaligned Objective-C protocol list");+ for (let index = 0; index < section.size / 8; index++) {+ if (budget.isFull()) {+ budget.markTruncated();+ break;+ }+ protocolReader.record(read.pointer(section.address + BigInt(index * 8)));+ }+ }+ const visited = new Set<string>();+ const readClass = (address: bigint, meta = false) => {+ if (address === 0n || visited.has(hex(address)) || !budget.admit()) return;+ visited.add(hex(address));+ const ro = read.pointer(address + 32n) & ~7n;+ const name = read.string(read.pointer(ro + 24n));+ const superclass = read.pointer(address + 8n);+ const root = (read.u32(ro) & 2) !== 0;+ let superclassName: string | null = null;+ if (superclass !== 0n) {+ try {+ superclassName = read.string(+ read.pointer((read.pointer(superclass + 32n) & ~7n) + 24n),+ );+ } catch (cause: unknown) {+ // Superclass resolution failure is recorded; the cause adds no identity.+ void cause;+ failures.push(+ `Superclass pointer ${hex(superclass)} of ${name} requires unsupported binding/fixup resolution`,+ );+ }+ }+ if (superclass === 0n && !root)+ failures.push(+ `Superclass of ${name} requires external binding resolution`,+ );+ const ivarList = read.pointer(ro + 48n);+ let ivarCount = 0;+ if (ivarList !== 0n && !meta) {+ const stride = read.u32(ivarList),+ count = read.u32(ivarList + 4n);+ if (stride !== 32)+ throw new TypeError("Unsupported Objective-C ivar entry size");+ ivarCount = count;+ for (let index = 0; index < count; index++) {+ if (!budget.admit()) break;+ const entry = ivarList + 8n + BigInt(index * stride);+ const encodedOffset = read.pointer(entry);+ let value: number | null = null;+ try {+ value = read.u32(encodedOffset);+ } catch (cause: unknown) {+ // Unresolved offsets are recorded; the cause adds no identity.+ void cause;+ failures.push(`Unresolved ivar offset pointer ${hex(encodedOffset)}`);+ }+ result.objc_ivars.push({+ class_name: name,+ name: read.string(read.pointer(entry + 8n)),+ type_encoding: read.string(read.pointer(entry + 16n)),+ offset: value,+ size: read.u32(entry + 28n),+ alignment:+ read.u32(entry + 24n) < 31 ? 2 ** read.u32(entry + 24n) : null,+ location: read.location(entry),+ decode:+ value === null+ ? { status: "partial", reason: "ivar_offset_pointer_unresolved" }+ : decoded,+ evidence: read.evidence(+ entry,+ "Objective-C ivar entry and encoded offset storage",+ ),+ });+ }+ }+ methods(read.pointer(ro + 32n), name, meta ? "class" : "instance");+ result.objc_classes.push({+ name,+ super_class: superclassName,+ is_meta_class: meta,+ is_root_class: root,+ methods: result.objc_dispatch_implementations+ .filter(+ (item) =>+ item.class_name === name &&+ item.method_type === (meta ? "class" : "instance"),+ )+ .map((item) => ({+ selector: item.selector,+ method_type: item.method_type,+ address:+ item.implementation_address !== null &&+ BigInt(item.implementation_address) <=+ BigInt(Number.MAX_SAFE_INTEGER)+ ? Number(BigInt(item.implementation_address))+ : null,+ is_required: false,+ is_optional: false,+ })),+ properties: [],+ protocols: protocolReader.list(read.pointer(ro + 40n)),+ ivar_count: ivarCount,+ instance_size: read.u32(ro + 8n),+ location: read.location(address),+ superclass_address: superclass === 0n ? null : hex(superclass),+ metaclass_address: meta ? null : hex(read.pointer(address)),+ decode:+ superclassName === null && !root+ ? { status: "partial", reason: "superclass_binding_unresolved" }+ : decoded,+ evidence: read.evidence(+ address,+ "Objective-C class and class_ro_t records",+ ),+ });+ if (!meta) {+ try {+ readClass(read.pointer(address), true);+ } catch (cause) {+ failures.push(+ `Metaclass of ${name}: ${cause instanceof Error ? cause.message : String(cause)}`,+ );+ }+ }+ };+ for (const section of sections.filter(+ ({ name }) => name === "__objc_classlist",+ )) {+ if (section.size % 8 !== 0)+ throw new RangeError("Misaligned Objective-C class-list size");+ for (let index = 0; index < section.size / 8; index++) {+ if (budget.isFull()) {+ budget.markTruncated();+ break;+ }+ examined++;+ const field = section.address + BigInt(index * 8);+ try {+ readClass(read.pointer(field));+ } catch (cause) {+ failures.push(+ `${hex(field)}: ${cause instanceof Error ? cause.message : String(cause)}`,+ );+ }+ }+ }+ return { failures, examined };+};diff --git a/src/native/AppleSwiftDispatchFacets.ts b/src/native/AppleSwiftDispatchFacets.tsnew file mode 100644index 000000000..95f8c81fa--- /dev/null+++ b/src/native/AppleSwiftDispatchFacets.ts@@ -0,0 +1,221 @@+import type { ObjcSwiftMetadata } from "../domain/objcSwiftMetadata.js";+import type { Segment, Section } from "./AppleMachoSelection.js";++/** Resolved file-backed metadata location from the Mach-O layout. */+export interface ResolvedMetadataLocation {+ address: string;+ file_offset: number;+}++/** Binary-metadata evidence produced by the Apple dispatch readers. */+export type BinaryMetadataEvidence = {+ kind: "binary_metadata";+ description: string;+ location: ResolvedMetadataLocation;+ artifact_path: string;+ artifact_sha256: string;+}[];++/** Shared admission budget for max_records truncation across decode facets. */+export interface DispatchRecordBudget {+ truncated: boolean;+ isFull(): boolean;+ markTruncated(): void;+ admit(): boolean;+}++/** Byte readers for Swift relative-pointer and conformance decode facets. */+export interface SwiftDispatchReaders {+ u32(address: bigint): number;+ pointer(address: bigint): bigint;+ string(address: bigint): string;+ location(address: bigint): ResolvedMetadataLocation;+ evidence(address: bigint, description: string): BinaryMetadataEvidence;+ offset(address: bigint, size?: number): number;+}++const hex = (value: bigint) => `0x${value.toString(16)}`;+const decoded = { status: "decoded" as const, reason: null };++/** Create a Swift ABI signed-relative pointer decoder that records relative_pointers. */+export const createSwiftRelativeReader = (input: {+ bytes: Buffer;+ readers: SwiftDispatchReaders;+ budget: DispatchRecordBudget;+ result: ObjcSwiftMetadata;+}) => {+ const { bytes, readers: read, budget, result } = input;+ return (field: bigint, indirectable = false): bigint => {+ const displacement = bytes.readInt32LE(read.offset(field, 4));+ const indirect = indirectable && (displacement & 1) !== 0;+ let target =+ displacement === 0+ ? 0n+ : field + BigInt(indirectable ? displacement & ~1 : displacement);+ let fileOffset: number | null = null;+ let reason: string | null = null;+ try {+ if (indirect && target !== 0n) target = read.pointer(target);+ if (target !== 0n) fileOffset = read.offset(target);+ } catch (cause) {+ reason = cause instanceof Error ? cause.message : String(cause);+ }+ if (budget.admit())+ result.relative_pointers.push({+ field: read.location(field),+ target: {+ address: target === 0n ? null : hex(target),+ file_offset: fileOffset,+ },+ displacement,+ indirectable,+ indirect,+ decode: reason === null ? decoded : { status: "partial", reason },+ evidence: read.evidence(+ field,+ "Swift ABI signed-relative metadata pointer",+ ),+ });+ if (reason !== null) throw new RangeError(reason);+ return target;+ };+};++/** Decode `__swift5_proto` conformances and static witness slots into `result`. */+export const decodeSwiftDispatchFacets = (input: {+ sections: readonly Section[];+ segments: readonly Segment[];+ readers: SwiftDispatchReaders;+ relative: (field: bigint, indirectable?: boolean) => bigint;+ budget: DispatchRecordBudget;+ result: ObjcSwiftMetadata;+}): void => {+ const { sections, segments, readers: read, relative, budget, result } = input;+ const swiftFailures: string[] = [];+ let swiftExamined = 0;+ for (const section of sections.filter(+ ({ name }) => name === "__swift5_proto",+ )) {+ if (section.size % 4 !== 0)+ throw new RangeError("Misaligned Swift conformance section");+ for (let index = 0; index < section.size / 4; index++) {+ if (!budget.admit()) break;+ swiftExamined++;+ const field = section.address + BigInt(index * 4);+ try {+ const descriptor = relative(field);+ const flags = read.u32(descriptor + 12n);+ const protocol = relative(descriptor, true);+ if ((read.u32(protocol) & 31) !== 3)+ throw new TypeError("Unsupported Swift protocol descriptor kind");+ const protocolName = read.string(relative(protocol + 8n));+ const typeKind = (flags >>> 3) & 7;+ if (typeKind !== 0 && typeKind !== 1)+ throw new TypeError(+ "Unsupported Swift conformance type-reference kind",+ );+ let type = relative(descriptor + 4n);+ if (typeKind === 1) type = read.pointer(type);+ if (![16, 17, 18].includes(read.u32(type) & 31))+ throw new TypeError("Unsupported Swift type descriptor kind");+ const typeName = read.string(relative(type + 8n));+ const witness = relative(descriptor + 8n);+ const staticWitness =+ witness !== 0n &&+ (flags & ~0x38) === 0 &&+ (read.u32(type) & 0x80) === 0;+ let witnessReason: string | null = staticWitness+ ? null+ : "Conditional, generic, resilient or missing static witness table is not decoded";+ if (staticWitness && read.pointer(witness) !== descriptor)+ witnessReason =+ "Witness-table conformance header is unresolved or encoded";+ result.swift_conformances.push({+ type_name: typeName,+ protocol_name: protocolName,+ module: null,+ witness_table:+ witness === 0n+ ? { address: null, file_offset: null }+ : read.location(witness),+ location: read.location(descriptor),+ decode:+ witnessReason === null+ ? decoded+ : {+ status: "partial",+ reason: witnessReason,+ },+ evidence: read.evidence(+ descriptor,+ "Swift protocol conformance descriptor and directly encoded type/protocol names",+ ),+ });+ if (witnessReason !== null) {+ swiftFailures.push(`${typeName}: ${witnessReason}`);+ continue;+ }+ const count = read.u32(protocol + 16n);+ const signatureCount = read.u32(protocol + 12n);+ if (count > 20_000 || signatureCount > 20_000)+ throw new RangeError("Swift witness requirement count exceeds 20000");+ for (let slot = 0; slot < count; slot++) {+ if (!budget.admit()) break;+ const entry = witness + BigInt((slot + 1) * 8);+ const implementation = read.pointer(entry);+ const requirementFlags = read.u32(+ protocol + 24n + BigInt(signatureCount * 12 + slot * 8),+ );+ const kind = requirementFlags & 15;+ const synchronousFunction =+ kind >= 1 && kind <= 4 && (requirementFlags & 0x20) === 0;+ const executable =+ synchronousFunction &&+ segments.some(+ (segment) =>+ segment.executable &&+ implementation >= segment.address &&+ implementation < segment.address + segment.size,+ );+ result.swift_dispatch_slots.push({+ owner: `${typeName}: ${protocolName}`,+ table_kind: "witness_table",+ slot_index: slot + 1,+ requirement: null,+ implementation: null,+ implementation_address: executable ? hex(implementation) : null,+ thunk_address: null,+ location: read.location(entry),+ decode: executable+ ? decoded+ : {+ status: "partial",+ reason:+ "Witness slot is non-function, async, nil, external, authenticated or encoded; implementation target is unresolved",+ },+ evidence: read.evidence(+ entry,+ "Static Swift witness slot, indexed after the conformance-descriptor header",+ ),+ });+ }+ } catch (cause) {+ swiftFailures.push(+ `${hex(field)}: ${cause instanceof Error ? cause.message : String(cause)}`,+ );+ }+ }+ }+ result.coverage.push({+ facet: "swift_conformances_static_witness_slots",+ status:+ swiftFailures.length > 0 || budget.truncated ? "partial" : "complete",+ reason:+ [+ ...swiftFailures,+ ...(budget.truncated ? ["max_records_reached"] : []),+ ].join("; ") || null,+ examined: swiftExamined,+ decoded: result.swift_conformances.length,+ });+};