Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(apple): derive dispatch coverage from located decode facts

morluto488f448ae27f
diff --git a/src/native/AppleDispatchCoverage.ts b/src/native/AppleDispatchCoverage.ts
index 6114a8e87..746e099be 100644
--- a/src/native/AppleDispatchCoverage.ts
+++ b/src/native/AppleDispatchCoverage.ts
@@ -1,5 +1,7 @@
import type { ObjcSwiftMetadata } from "../domain/native/objcSwiftMetadata.js";
import type { PointerFixups } from "./AppleMachoFixups.js";
+import type { DecodeIssue } from "./AppleDispatchDecodeFacts.js";
+import type { FacetDecodeFacts } from "./AppleDispatchDecodeFacts.js";
const describeFixups = (fixups: PointerFixups): string => {
if (fixups.kind === "chained")
@@ -13,13 +15,25 @@ const describeFixups = (fixups: PointerFixups): string => {
export const pushDispatchCoverage = (input: {
readonly result: ObjcSwiftMetadata;
readonly failures: readonly string[];
+ readonly categoryIssues: readonly DecodeIssue[];
readonly examined: number;
readonly categoriesExamined: number;
readonly truncated: boolean;
readonly fixups: PointerFixups;
+ readonly vtables: FacetDecodeFacts;
+ readonly swift: FacetDecodeFacts;
}): void => {
- const { result, failures, examined, categoriesExamined, truncated, fixups } =
- input;
+ const {
+ result,
+ failures,
+ categoryIssues,
+ examined,
+ categoriesExamined,
+ truncated,
+ fixups,
+ vtables,
+ swift,
+ } = input;
result.coverage.push({
facet: "objc_class_method_ivar_metadata",
status: failures.length > 0 || truncated ? "partial" : "complete",
@@ -48,17 +62,22 @@ export const pushDispatchCoverage = (input: {
(item) => item.decode.status === "decoded",
).length,
});
- const categoryFailures = failures.filter((failure) =>
- /^(?:Properties of|Category at)/u.test(failure),
+ const categoryFailures = categoryIssues.map(
+ ({ code, location, message }) =>
+ `${code}${location === undefined ? "" : ` at ${location}`}: ${message}`,
);
result.coverage.push({
facet: "objc_properties_categories",
status:
+ truncated ||
categoryFailures.length > 0 ||
result.objc_categories.some(({ decode }) => decode.status !== "decoded")
? "partial"
: "complete",
- reason: categoryFailures.join("; ") || null,
+ reason:
+ [...categoryFailures, ...(truncated ? ["max_records_reached"] : [])].join(
+ "; ",
+ ) || null,
examined: categoriesExamined,
decoded: result.objc_categories.filter(
({ decode }) => decode.status === "decoded",
@@ -66,8 +85,14 @@ export const pushDispatchCoverage = (input: {
});
result.coverage.push({
facet: "pointer_fixups",
- status: fixups.failures.length > 0 ? "partial" : "complete",
- reason: [describeFixups(fixups), ...fixups.failures].join("; "),
+ status: fixups.issues.length > 0 ? "partial" : "complete",
+ reason: [
+ describeFixups(fixups),
+ ...fixups.issues.map(
+ ({ code, location, message }) =>
+ `${code}${location === undefined ? "" : ` at ${location}`}: ${message}`,
+ ),
+ ].join("; "),
examined: 0,
decoded: 0,
});
@@ -79,4 +104,63 @@ export const pushDispatchCoverage = (input: {
examined: 0,
decoded: 0,
});
+ result.coverage.push({
+ facet: "swift_conformances_static_witness_slots",
+ status:
+ swift.exhaustive &&
+ !truncated &&
+ !result.swift_conformances.some(
+ ({ decode }) => decode.status !== "decoded",
+ ) &&
+ !result.swift_dispatch_slots.some(
+ ({ table_kind, decode }) =>
+ table_kind === "witness_table" && decode.status !== "decoded",
+ )
+ ? "complete"
+ : "partial",
+ reason:
+ [
+ ...swift.issues.map(formatIssue),
+ ...(truncated ? ["max_records_reached"] : []),
+ ...(result.swift_conformances.some(
+ ({ decode }) => decode.status !== "decoded",
+ ) ||
+ result.swift_dispatch_slots.some(
+ ({ table_kind, decode }) =>
+ table_kind === "witness_table" && decode.status !== "decoded",
+ )
+ ? ["swift_records_unresolved"]
+ : []),
+ ].join("; ") || null,
+ examined: swift.examined,
+ decoded: swift.decoded,
+ });
+ result.coverage.push({
+ facet: "swift_class_vtable_descriptors",
+ status:
+ vtables.exhaustive &&
+ !truncated &&
+ !result.swift_dispatch_slots.some(
+ ({ table_kind, decode }) =>
+ table_kind === "class_vtable" && decode.status !== "decoded",
+ )
+ ? "complete"
+ : "partial",
+ reason:
+ [
+ ...vtables.issues.map(formatIssue),
+ ...(truncated ? ["max_records_reached"] : []),
+ ...(result.swift_dispatch_slots.some(
+ ({ table_kind, decode }) =>
+ table_kind === "class_vtable" && decode.status !== "decoded",
+ )
+ ? ["vtable_implementations_unresolved"]
+ : []),
+ ].join("; ") || null,
+ examined: vtables.examined,
+ decoded: vtables.decoded,
+ });
};
+
+const formatIssue = ({ code, location, message }: DecodeIssue): string =>
+ `${code}${location === undefined ? "" : ` at ${location}`}: ${message}`;
diff --git a/src/native/AppleDispatchDecodeFacts.ts b/src/native/AppleDispatchDecodeFacts.ts
new file mode 100644
index 000000000..699235d16
--- /dev/null
+++ b/src/native/AppleDispatchDecodeFacts.ts
@@ -0,0 +1,35 @@
+/** Stable internal decode issues used to derive public facet coverage. */
+export type DispatchFacet =
+ | "objc_class_method_ivar_metadata"
+ | "binary_relative_pointers"
+ | "objc_properties_categories"
+ | "pointer_fixups"
+ | "swift_conformances_static_witness_slots"
+ | "swift_class_vtable_descriptors";
+
+export interface DecodeIssue {
+ readonly facet: DispatchFacet;
+ readonly code: string;
+ readonly location?: string;
+ readonly message: string;
+}
+
+export interface FacetDecodeFacts {
+ readonly facet: DispatchFacet;
+ readonly examined: number;
+ readonly decoded: number;
+ readonly exhaustive: boolean;
+ readonly issues: readonly DecodeIssue[];
+}
+
+export const issue = (
+ facet: DispatchFacet,
+ code: string,
+ message: string,
+ location?: string,
+): DecodeIssue => ({
+ facet,
+ code,
+ message,
+ ...(location === undefined ? {} : { location }),
+});
diff --git a/src/native/AppleDispatchMetadata.test.ts b/src/native/AppleDispatchMetadata.test.ts
index 1c78241a5..a69f20183 100644
--- a/src/native/AppleDispatchMetadata.test.ts
+++ b/src/native/AppleDispatchMetadata.test.ts
@@ -102,9 +102,13 @@ describe("Apple dispatch binary metadata", () => {
implementation_address: null,
decode: { status: "partial" },
});
+ const truncated = decodeAppleDispatchMetadata(fixture(), 1, provenance);
+ expect(truncated.coverage[0]?.reason).toContain("max_records_reached");
expect(
- decodeAppleDispatchMetadata(fixture(), 1, provenance).coverage[0]?.reason,
- ).toContain("max_records_reached");
+ truncated.coverage.find(
+ ({ facet }) => facet === "objc_properties_categories",
+ ),
+ ).toMatchObject({ status: "partial", reason: "max_records_reached" });
});
it("rejects malformed command and section boundaries", () => {
const bytes = fixture();
@@ -171,7 +175,7 @@ describe("FAT64 dispatch slice validation", () => {
const bytes = wrapped();
bytes.writeBigUInt64BE(0x100000000n, field);
expect(() => decodeAppleDispatchMetadata(bytes, 100, provenance)).toThrow(
- "FAT slice exceeds file",
+ "FAT architecture 0 slice range extends beyond the file",
);
},
);
@@ -265,7 +269,7 @@ describe("byte-swapped universal Apple dispatch metadata", () => {
const bytes = wrapped(true);
bytes.writeBigUInt64LE(0x100000000n, 16);
expect(() => decodeAppleDispatchMetadata(bytes, 100, provenance)).toThrow(
- "FAT slice exceeds file (FAT header byte order: little-endian)",
+ "FAT architecture 0 slice range extends beyond the file (FAT header byte order: little-endian)",
);
});
});
diff --git a/src/native/AppleDispatchMetadata.ts b/src/native/AppleDispatchMetadata.ts
index 94daaf9f8..530dd9eb8 100644
--- a/src/native/AppleDispatchMetadata.ts
+++ b/src/native/AppleDispatchMetadata.ts
@@ -99,21 +99,22 @@ export const decodeAppleDispatchMetadata = (
evidence,
offset,
};
- const { failures, examined, categoriesExamined } = decodeObjcDispatchFacets({
- bytes,
- sections,
- segments,
- readers,
- budget,
- result,
- });
+ const { failures, categoryIssues, examined, categoriesExamined } =
+ decodeObjcDispatchFacets({
+ bytes,
+ sections,
+ segments,
+ readers,
+ budget,
+ result,
+ });
const swiftRelative = createSwiftRelativeReader({
bytes,
readers,
budget,
result,
});
- decodeSwiftDispatchFacets({
+ const swift = decodeSwiftDispatchFacets({
sections,
segments,
readers,
@@ -131,7 +132,7 @@ export const decodeAppleDispatchMetadata = (
typeEntries.push(section.address + BigInt(index * 4));
if (section.size / 4 > maxRecords) budget.truncated = true;
}
- decodeSwiftClassVtables({
+ const vtables = decodeSwiftClassVtables({
entries: typeEntries,
result,
readers: {
@@ -153,10 +154,13 @@ export const decodeAppleDispatchMetadata = (
pushDispatchCoverage({
result,
failures,
+ categoryIssues,
examined,
categoriesExamined,
truncated: budget.truncated,
fixups,
+ vtables,
+ swift,
});
return objcSwiftMetadataSchema.parse(result);
};
diff --git a/src/native/AppleMachoFixups.test.ts b/src/native/AppleMachoFixups.test.ts
index b4a2ebdbb..f9218fc7b 100644
--- a/src/native/AppleMachoFixups.test.ts
+++ b/src/native/AppleMachoFixups.test.ts
@@ -144,6 +144,33 @@ const SEGMENTS: Segment[] = [
];
describe("pointer fixup tables", () => {
+ it("reports unsupported pointer formats even when no pointer is visited", () => {
+ const data = chainedData(1);
+ data.writeUInt16LE(99, 46);
+ const fixups = parsePointerFixups(
+ data,
+ { chained: { offset: 0, size: data.length }, binds: [], dylibs: [] },
+ SEGMENTS,
+ BASE,
+ );
+ expect(fixups.failures).toContain("Unsupported chained pointer format 99");
+ });
+
+ it("does not decode unreferenced imports while constructing fixup facts", () => {
+ const data = chainedData(1);
+ // The second import is outside the table bytes; only the first is needed
+ // to construct the fixup reader, so its malformed symbol remains lazy.
+ data.writeUInt32LE(0xffff_ff00, 72);
+ expect(() =>
+ parsePointerFixups(
+ data,
+ { chained: { offset: 0, size: data.length }, binds: [], dylibs: [] },
+ SEGMENTS,
+ BASE,
+ ),
+ ).not.toThrow();
+ });
+
for (const format of [1, 2, 3] as const)
it(`reads chained import format ${format}`, () => {
const data = chainedData(format);
diff --git a/src/native/AppleMachoFixups.ts b/src/native/AppleMachoFixups.ts
index 4f3649082..4c7686790 100644
--- a/src/native/AppleMachoFixups.ts
+++ b/src/native/AppleMachoFixups.ts
@@ -1,4 +1,6 @@
import type { Segment } from "./AppleMachoSelection.js";
+import { issue } from "./AppleDispatchDecodeFacts.js";
+import type { DecodeIssue } from "./AppleDispatchDecodeFacts.js";
/** Where a Mach-O stores pointer fixups, from its load commands. */
export interface FixupCommands {
@@ -23,7 +25,8 @@ export type DecodedPointer =
readonly library: string | null;
readonly weak: boolean;
readonly addend: bigint;
- };
+ }
+ | { readonly kind: "unsupported"; readonly reason: string };
/** Pointer decoding for one Mach-O slice. */
export interface PointerFixups {
@@ -31,6 +34,7 @@ export interface PointerFixups {
/** Chained pointer formats in use, such as `DYLD_CHAINED_PTR_64_OFFSET`. */
readonly formats: readonly string[];
readonly failures: readonly string[];
+ readonly issues: readonly DecodeIssue[];
/** Decode the pointer stored at `address` whose raw 64-bit value is `raw`. */
decode(address: bigint, raw: bigint): DecodedPointer;
}
@@ -72,7 +76,7 @@ const cString = (bytes: Buffer, offset: number, end: number): string => {
return bytes.toString("utf8", offset, stop);
};
-const readImports = (
+const readImport = (
data: {
readonly bytes: Buffer;
readonly base: number;
@@ -85,38 +89,42 @@ const readImports = (
readonly format: number;
readonly symbols: number;
},
-): Import[] => {
+ index: number,
+): Import => {
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)
+ if (
+ !Number.isSafeInteger(header.count) ||
+ 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));
+ 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 + (word >>> 9), end),
+ symbol: cString(
+ bytes,
+ base + header.symbols + Number(bits(word, 32, 32)),
+ end,
+ ),
library: libraryName(ordinal, dylibs),
- weak: ((word >>> 8) & 1) === 1,
- addend: header.format === 2 ? BigInt(bytes.readInt32LE(at + 4)) : 0n,
+ 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. */
@@ -124,10 +132,13 @@ export const decodeChainedPointer = (
raw: bigint,
format: number,
baseAddress: bigint,
- imports: readonly Import[],
+ imports: readonly Import[] | ((index: number) => Import),
): DecodedPointer => {
const bind = (ordinal: bigint, addend: bigint): DecodedPointer => {
- const target = imports[Number(ordinal)];
+ 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 };
@@ -176,15 +187,24 @@ const chainedFixups = (
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),
- },
- );
+ 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: number) =>
+ readImport({ bytes, base, end, dylibs }, importHeader, index);
if (bytes.readUInt32LE(base + 24) !== 0)
throw new RangeError(
"Compressed chained-fixup symbol names are not supported",
@@ -213,10 +233,23 @@ const chainedFixups = (
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: [],
+ failures: issues.map(({ message }) => message),
+ issues,
decode(address, raw) {
const segment = ranges.find(
({ from, to }) => address >= from && address < to,
@@ -224,6 +257,11 @@ const chainedFixups = (
// 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);
},
};
@@ -388,6 +426,7 @@ export const parsePointerFixups = (
kind: "none",
formats: [],
failures: [],
+ issues: [],
decode: (_address, raw) => ({ kind: "rebase", target: raw }),
};
const binds = new Map<bigint, Import>();
@@ -404,6 +443,9 @@ export const parsePointerFixups = (
kind: "dyld-info",
formats: [],
failures,
+ issues: failures.map((message) =>
+ issue("pointer_fixups", "bind_stream_decode_failed", message),
+ ),
decode(address, raw) {
const bound = binds.get(address);
return bound === undefined
diff --git a/src/native/AppleObjcCategories.ts b/src/native/AppleObjcCategories.ts
index 10d5a13df..bd936e0ce 100644
--- a/src/native/AppleObjcCategories.ts
+++ b/src/native/AppleObjcCategories.ts
@@ -2,6 +2,7 @@ import type { ObjcSwiftMetadata } from "../domain/native/objcSwiftMetadata.js";
import type { Section } from "./AppleMachoSelection.js";
import type { ObjcDispatchReaders } from "./AppleObjcDispatchFacets.js";
import { readObjcPropertiesOf } from "./AppleObjcProperties.js";
+import { issue, type DecodeIssue } from "./AppleDispatchDecodeFacts.js";
const CLASS_SYMBOL = /^_OBJC_(?:META)?CLASS_\$_(.+)$/u;
@@ -23,6 +24,7 @@ export const decodeObjcCategories = (input: {
readonly read: ObjcDispatchReaders;
readonly result: ObjcSwiftMetadata;
readonly failures: string[];
+ readonly issues: DecodeIssue[];
readonly admit: () => boolean;
/** Decode a method list into implementations attributed to the category. */
readonly methods: (
@@ -79,7 +81,8 @@ export const decodeObjcCategories = (input: {
properties: readObjcPropertiesOf(read, read.pointer(category + 40n), {
owner: `category ${name}`,
admit: input.admit,
- failures,
+ issues: input.issues,
+ location: `0x${read.pointer(category + 40n).toString(16)}`,
}),
location: read.location(category),
decode:
@@ -89,8 +92,15 @@ export const decodeObjcCategories = (input: {
evidence: read.evidence(category, "Objective-C category_t record"),
});
} catch (cause: unknown) {
- failures.push(
- `Category at ${`0x${field.toString(16)}`}: ${cause instanceof Error ? cause.message : String(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)}`,
+ ),
);
}
}
diff --git a/src/native/AppleObjcDispatchFacets.ts b/src/native/AppleObjcDispatchFacets.ts
index e3485e9c1..e23d4905d 100644
--- a/src/native/AppleObjcDispatchFacets.ts
+++ b/src/native/AppleObjcDispatchFacets.ts
@@ -2,6 +2,7 @@ import type { ObjcSwiftMetadata } from "../domain/native/objcSwiftMetadata.js";
import type { Segment, Section } from "./AppleMachoSelection.js";
import { boundClassName, decodeObjcCategories } from "./AppleObjcCategories.js";
import { readObjcPropertiesOf } from "./AppleObjcProperties.js";
+import type { DecodeIssue } from "./AppleDispatchDecodeFacts.js";
import { createObjcProtocolReader } from "./AppleObjcProtocols.js";
import type {
BinaryMetadataEvidence,
@@ -67,9 +68,15 @@ export const decodeObjcDispatchFacets = (input: {
readers: ObjcDispatchReaders;
budget: DispatchRecordBudget;
result: ObjcSwiftMetadata;
-}): { failures: string[]; examined: number; categoriesExamined: number } => {
+}): {
+ failures: string[];
+ categoryIssues: DecodeIssue[];
+ examined: number;
+ categoriesExamined: number;
+} => {
const { bytes, sections, segments, readers: read, budget, result } = input;
const failures: string[] = [];
+ const categoryIssues: DecodeIssue[] = [];
let examined = 0;
const methods = (
list: bigint,
@@ -275,7 +282,8 @@ export const decodeObjcDispatchFacets = (input: {
properties: readObjcPropertiesOf(read, read.pointer(ro + 64n), {
owner: name,
admit: () => budget.admit(),
- failures,
+ issues: categoryIssues,
+ location: hex(read.pointer(ro + 64n)),
}),
protocols: protocolReader.list(read.pointer(ro + 40n)),
ivar_count: ivarCount,
@@ -328,10 +336,11 @@ export const decodeObjcDispatchFacets = (input: {
read,
result,
failures,
+ issues: categoryIssues,
admit: () => budget.admit(),
methods,
protocols: (list) => protocolReader.list(list),
localClassName: (address) => localClassName(read, address),
});
- return { failures, examined, categoriesExamined };
+ return { failures, categoryIssues, examined, categoriesExamined };
};
diff --git a/src/native/AppleObjcProperties.ts b/src/native/AppleObjcProperties.ts
index 4aac58a18..07dacbc1f 100644
--- a/src/native/AppleObjcProperties.ts
+++ b/src/native/AppleObjcProperties.ts
@@ -1,6 +1,7 @@
import type { z } from "zod";
import type { objcPropertySchema } from "../domain/native/objcSwiftMetadata.js";
+import { issue, type DecodeIssue } from "./AppleDispatchDecodeFacts.js";
type ObjcProperty = z.infer<typeof objcPropertySchema>;
@@ -89,14 +90,20 @@ export const readObjcPropertiesOf = (
context: {
readonly owner: string;
readonly admit: () => boolean;
- readonly failures: string[];
+ readonly issues: DecodeIssue[];
+ readonly location?: string;
},
): ObjcProperty[] => {
try {
return readObjcPropertyList(read, list, context.admit);
} catch (cause: unknown) {
- context.failures.push(
- `Properties of ${context.owner}: ${cause instanceof Error ? cause.message : String(cause)}`,
+ context.issues.push(
+ issue(
+ "objc_properties_categories",
+ "property_decode_failed",
+ `${context.owner}: ${cause instanceof Error ? cause.message : String(cause)}`,
+ context.location,
+ ),
);
return [];
}
diff --git a/src/native/AppleSwiftDispatchFacets.ts b/src/native/AppleSwiftDispatchFacets.ts
index ac6507d1d..c22683a9f 100644
--- a/src/native/AppleSwiftDispatchFacets.ts
+++ b/src/native/AppleSwiftDispatchFacets.ts
@@ -1,5 +1,6 @@
import type { ObjcSwiftMetadata } from "../domain/native/objcSwiftMetadata.js";
import type { Segment, Section } from "./AppleMachoSelection.js";
+import { issue, type FacetDecodeFacts } from "./AppleDispatchDecodeFacts.js";
/** Resolved file-backed metadata location from the Mach-O layout. */
export interface ResolvedMetadataLocation {
@@ -89,10 +90,12 @@ export const decodeSwiftDispatchFacets = (input: {
relative: (field: bigint, indirectable?: boolean) => bigint;
budget: DispatchRecordBudget;
result: ObjcSwiftMetadata;
-}): void => {
+}): FacetDecodeFacts => {
const { sections, segments, readers: read, relative, budget, result } = input;
const swiftFailures: string[] = [];
+ const issues = [] as ReturnType<typeof issue>[];
let swiftExamined = 0;
+ let decodedRecords = 0;
for (const section of sections.filter(
({ name }) => name === "__swift5_proto",
)) {
@@ -130,6 +133,10 @@ export const decodeSwiftDispatchFacets = (input: {
if (staticWitness && read.pointer(witness) !== descriptor)
witnessReason =
"Witness-table conformance header is unresolved or encoded";
+ const conformanceDecode =
+ witnessReason === null
+ ? { status: "decoded" as const, reason: null }
+ : { status: "partial" as const, reason: witnessReason };
result.swift_conformances.push({
type_name: typeName,
protocol_name: protocolName,
@@ -139,20 +146,23 @@ export const decodeSwiftDispatchFacets = (input: {
? { address: null, file_offset: null }
: read.location(witness),
location: read.location(descriptor),
- decode:
- witnessReason === null
- ? decoded
- : {
- status: "partial",
- reason: witnessReason,
- },
+ decode: conformanceDecode,
evidence: read.evidence(
descriptor,
"Swift protocol conformance descriptor and directly encoded type/protocol names",
),
});
+ if (conformanceDecode.status === "decoded") decodedRecords++;
if (witnessReason !== null) {
swiftFailures.push(`${typeName}: ${witnessReason}`);
+ issues.push(
+ issue(
+ "swift_conformances_static_witness_slots",
+ "conformance_decode_partial",
+ witnessReason,
+ hex(descriptor),
+ ),
+ );
continue;
}
const count = read.u32(protocol + 16n);
@@ -177,6 +187,13 @@ export const decodeSwiftDispatchFacets = (input: {
implementation >= segment.address &&
implementation < segment.address + segment.size,
);
+ const slotDecode = executable
+ ? { status: "decoded" as const, reason: null }
+ : {
+ status: "partial" as const,
+ reason:
+ "Witness slot is non-function, async, nil, external, authenticated or encoded; implementation target is unresolved",
+ };
result.swift_dispatch_slots.push({
owner: `${typeName}: ${protocolName}`,
table_kind: "witness_table",
@@ -186,36 +203,41 @@ export const decodeSwiftDispatchFacets = (input: {
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",
- },
+ decode: slotDecode,
evidence: read.evidence(
entry,
"Static Swift witness slot, indexed after the conformance-descriptor header",
),
});
+ if (slotDecode.status !== "decoded")
+ issues.push(
+ issue(
+ "swift_conformances_static_witness_slots",
+ "witness_slot_unresolved",
+ slotDecode.reason,
+ hex(entry),
+ ),
+ );
}
} catch (cause) {
- swiftFailures.push(
- `${hex(field)}: ${cause instanceof Error ? cause.message : String(cause)}`,
+ const message = cause instanceof Error ? cause.message : String(cause);
+ swiftFailures.push(`${hex(field)}: ${message}`);
+ issues.push(
+ issue(
+ "swift_conformances_static_witness_slots",
+ "conformance_decode_failed",
+ message,
+ hex(field),
+ ),
);
}
}
}
- result.coverage.push({
+ return {
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,
- });
+ decoded: decodedRecords,
+ exhaustive: !budget.truncated && issues.length === 0,
+ issues,
+ };
};
diff --git a/src/native/AppleSwiftVtables.test.ts b/src/native/AppleSwiftVtables.test.ts
new file mode 100644
index 000000000..782e09349
--- /dev/null
+++ b/src/native/AppleSwiftVtables.test.ts
@@ -0,0 +1,207 @@
+import { describe, expect, it } from "vitest";
+
+import { objcSwiftMetadataSchema } from "../domain/native/objcSwiftMetadata.js";
+import { pushDispatchCoverage } from "./AppleDispatchCoverage.js";
+import { decodeSwiftClassVtables } from "./AppleSwiftVtables.js";
+import { decodeSwiftDispatchFacets } from "./AppleSwiftDispatchFacets.js";
+import type { DispatchRecordBudget } from "./AppleSwiftDispatchFacets.js";
+import { issue } from "./AppleDispatchDecodeFacts.js";
+
+describe("Swift vtable coverage facts: unresolved Swift dispatch slots", () => {
+ it("returns a located issue for an emitted unresolved async slot", () => {
+ const result = objcSwiftMetadataSchema.parse({ db_save_result: null });
+ const values = new Map<bigint, number>([
+ [0x200n, 0x80000010], // class descriptor with a vtable
+ [0x22cn, 0], // table offset
+ [0x230n, 1], // slot count
+ [0x21cn, 1], // descriptor positive words
+ [0x234n, 0x40], // async method flag
+ ]);
+ const facts = decodeSwiftClassVtables({
+ entries: [0x100n],
+ result,
+ readers: {
+ u32: (address) => values.get(address) ?? 0,
+ relative: (address) =>
+ address === 0x100n ? 0x200n : address === 0x208n ? 0x300n : 0x400n,
+ string: () => "Widget",
+ location: (address) => ({
+ address: `0x${address.toString(16)}`,
+ file_offset: Number(address),
+ }),
+ evidence: (address, description) => [
+ {
+ kind: "binary_metadata",
+ description,
+ location: {
+ address: `0x${address.toString(16)}`,
+ file_offset: Number(address),
+ },
+ artifact_path: "/fixture",
+ artifact_sha256: "a".repeat(64),
+ },
+ ],
+ executable: () => false,
+ admit: () => true,
+ },
+ });
+
+ expect(result.swift_dispatch_slots[0]?.decode.status).toBe("partial");
+ expect(facts).toMatchObject({
+ facet: "swift_class_vtable_descriptors",
+ exhaustive: false,
+ issues: [{ code: "vtable_implementation_unresolved", location: "0x234" }],
+ });
+
+ pushDispatchCoverage({
+ result,
+ failures: [],
+ categoryIssues: [],
+ examined: 0,
+ categoriesExamined: 0,
+ truncated: false,
+ fixups: {
+ kind: "none",
+ formats: [],
+ failures: [],
+ issues: [],
+ decode: (_address, raw) => ({ kind: "rebase", target: raw }),
+ },
+ swift: {
+ facet: "swift_conformances_static_witness_slots",
+ examined: 0,
+ decoded: 0,
+ exhaustive: true,
+ issues: [],
+ },
+ vtables: facts,
+ });
+
+ expect(
+ result.coverage.find(
+ ({ facet }) => facet === "swift_class_vtable_descriptors",
+ ),
+ ).toMatchObject({
+ status: "partial",
+ reason: expect.stringContaining("0x234"),
+ });
+ });
+
+ it("returns a located issue for an emitted unresolved witness slot", () => {
+ const result = objcSwiftMetadataSchema.parse({ db_save_result: null });
+ const values = new Map<bigint, number>([
+ [0x20cn, 0], // simple, unconditional conformance
+ [0x500n, 3], // protocol descriptor kind
+ [0x50cn, 0], // signature count
+ [0x510n, 1], // witness requirement count
+ [0x2b0n, 16], // nominal type descriptor kind
+ [0x518n, 1], // function witness requirement
+ ]);
+ const budget: DispatchRecordBudget = {
+ truncated: false,
+ isFull: () => false,
+ markTruncated: () => {
+ budget.truncated = true;
+ },
+ admit: () => true,
+ };
+ const facts = decodeSwiftDispatchFacets({
+ sections: [{ name: "__swift5_proto", address: 0x100n, size: 4 }],
+ segments: [],
+ readers: {
+ u32: (address) => values.get(address) ?? 0,
+ pointer: (address) => (address === 0x380n ? 0x200n : 0x900n),
+ string: (address) => (address === 0x600n ? "Proto" : "Widget"),
+ location: (address) => ({
+ address: `0x${address.toString(16)}`,
+ file_offset: Number(address),
+ }),
+ evidence: (address, description) => [
+ {
+ kind: "binary_metadata",
+ description,
+ location: {
+ address: `0x${address.toString(16)}`,
+ file_offset: Number(address),
+ },
+ artifact_path: "/fixture",
+ artifact_sha256: "a".repeat(64),
+ },
+ ],
+ offset: (address) => Number(address),
+ },
+ relative: (field) =>
+ new Map<bigint, bigint>([
+ [0x100n, 0x200n],
+ [0x200n, 0x500n],
+ [0x508n, 0x600n],
+ [0x204n, 0x2b0n],
+ [0x2b8n, 0x700n],
+ [0x208n, 0x380n],
+ ]).get(field) ?? 0n,
+ budget,
+ result,
+ });
+
+ expect(result.swift_dispatch_slots[0]?.decode.status).toBe("partial");
+ expect(facts).toMatchObject({
+ facet: "swift_conformances_static_witness_slots",
+ exhaustive: false,
+ issues: [{ code: "witness_slot_unresolved", location: "0x388" }],
+ });
+ });
+});
+
+describe("Swift vtable coverage facts: unsupported pointer fixup coverage", () => {
+ it("marks pointer fixup coverage partial for an unsupported format with no decoded pointers", () => {
+ const result = objcSwiftMetadataSchema.parse({ db_save_result: null });
+ pushDispatchCoverage({
+ result,
+ failures: [],
+ categoryIssues: [],
+ examined: 0,
+ categoriesExamined: 0,
+ truncated: false,
+ fixups: {
+ kind: "chained",
+ formats: ["format-99"],
+ failures: ["Unsupported chained pointer format 99"],
+ issues: [
+ issue(
+ "pointer_fixups",
+ "unsupported_pointer_format",
+ "Unsupported chained pointer format 99",
+ "0x1000",
+ ),
+ ],
+ decode: () => ({
+ kind: "unsupported",
+ reason: "Unsupported chained pointer format 99",
+ }),
+ },
+ swift: {
+ facet: "swift_conformances_static_witness_slots",
+ examined: 0,
+ decoded: 0,
+ exhaustive: true,
+ issues: [],
+ },
+ vtables: {
+ facet: "swift_class_vtable_descriptors",
+ examined: 0,
+ decoded: 0,
+ exhaustive: true,
+ issues: [],
+ },
+ });
+
+ expect(
+ result.coverage.find(({ facet }) => facet === "pointer_fixups"),
+ ).toMatchObject({
+ status: "partial",
+ examined: 0,
+ decoded: 0,
+ reason: expect.stringContaining("0x1000"),
+ });
+ });
+});
diff --git a/src/native/AppleSwiftVtables.ts b/src/native/AppleSwiftVtables.ts
index 1cb843238..64d91b593 100644
--- a/src/native/AppleSwiftVtables.ts
+++ b/src/native/AppleSwiftVtables.ts
@@ -3,6 +3,7 @@ import type {
NativeMetadataEvidence,
NativeMetadataLocation,
} from "../domain/native/objcSwiftMetadata.js";
+import { issue, type FacetDecodeFacts } from "./AppleDispatchDecodeFacts.js";
/** Byte readers shared with the validated Mach-O metadata boundary. */
export interface SwiftMetadataReaders {
@@ -20,13 +21,23 @@ export const decodeSwiftClassVtables = (input: {
readers: SwiftMetadataReaders;
entries: readonly bigint[];
result: ObjcSwiftMetadata;
-}) => {
+}): FacetDecodeFacts => {
const { readers: read, result } = input;
const failures: string[] = [];
+ const issues = [] as ReturnType<typeof issue>[];
let examined = 0;
+ let decoded = 0;
for (const field of input.entries) {
if (!read.admit()) {
failures.push("max_records_reached");
+ issues.push(
+ issue(
+ "swift_class_vtable_descriptors",
+ "record_budget_exhausted",
+ "max_records_reached",
+ `0x${field.toString(16)}`,
+ ),
+ );
break;
}
examined++;
@@ -56,11 +67,19 @@ export const decodeSwiftClassVtables = (input: {
);
const owner = read.string(read.relative(descriptor + 8n));
for (let index = 0; index < count; index++) {
+ const entry = header + 8n + BigInt(index * 8);
if (!read.admit()) {
failures.push("max_records_reached");
+ issues.push(
+ issue(
+ "swift_class_vtable_descriptors",
+ "record_budget_exhausted",
+ "max_records_reached",
+ `0x${entry.toString(16)}`,
+ ),
+ );
break;
}
- const entry = header + 8n + BigInt(index * 8);
const methodFlags = read.u32(entry);
// Async slots reference async descriptors; coroutine and future kinds need separate decoders.
const synchronous =
@@ -90,33 +109,48 @@ export const decodeSwiftClassVtables = (input: {
"Swift class vtable method descriptor; slot index is a metadata word offset, not a source method ordinal",
),
});
+ if (resolved) decoded++;
+ else
+ issues.push(
+ issue(
+ "swift_class_vtable_descriptors",
+ "vtable_implementation_unresolved",
+ "Async, coroutine, external or unmapped vtable implementation is unresolved",
+ `0x${entry.toString(16)}`,
+ ),
+ );
}
- if ((specific & 0x4000) !== 0)
+ if ((specific & 0x4000) !== 0) {
failures.push(
`${owner}: inherited override descriptors are unsupported`,
);
+ issues.push(
+ issue(
+ "swift_class_vtable_descriptors",
+ "inherited_override_descriptors_unsupported",
+ "Inherited override descriptors are unsupported",
+ `0x${descriptor.toString(16)}`,
+ ),
+ );
+ }
} catch (cause) {
- failures.push(
- `0x${field.toString(16)}: ${cause instanceof Error ? cause.message : String(cause)}`,
+ const message = cause instanceof Error ? cause.message : String(cause);
+ failures.push(`0x${field.toString(16)}: ${message}`);
+ issues.push(
+ issue(
+ "swift_class_vtable_descriptors",
+ "vtable_decode_failed",
+ message,
+ `0x${field.toString(16)}`,
+ ),
);
}
}
- const slots = result.swift_dispatch_slots.filter(
- (slot) => slot.table_kind === "class_vtable",
- );
- result.coverage.push({
+ return {
facet: "swift_class_vtable_descriptors",
examined,
- decoded: slots.filter((slot) => slot.decode.status === "decoded").length,
- status:
- failures.length > 0 ||
- slots.some((slot) => slot.decode.status !== "decoded")
- ? "partial"
- : "complete",
- reason:
- failures.join("; ") ||
- (slots.some((slot) => slot.decode.status !== "decoded")
- ? "vtable_implementations_unresolved"
- : null),
- });
+ decoded,
+ exhaustive: issues.length === 0,
+ issues,
+ };
};