feat(native): add inspection primitives, dispatch traces and approved UI observation (#500)

* fix(hopper): normalize string-backed addresses and update verification

* feat(native): add inspection primitives, dispatch traces and approved UI observation

* test: prioritize real artifact E2E and captured golden regressions

* fix(process): queue observed output before reactive rendering actions

* test: prune redundant cases and strengthen boundary assertions

* fix(cli): route native value tracing through shared workflows

* test: replace synthetic success with real workflows and captured data

* fix(catalog): separate portable metadata from native host availability
This commit is contained in:
morluto
2026-10-04 16:02:36 +08:00
committed by GitHub
parent 0356f7677f
commit 4fbc501121
205 changed files with 8136 additions and 1816 deletions
+119
View File
@@ -0,0 +1,119 @@
import { describe, expect, it } from "vitest";
import { decodeAppleDispatchMetadata } from "./AppleDispatchMetadata.js";
const base = 0x100000000n;
const fixture = (relative = false) => {
const bytes = Buffer.alloc(2048);
const u32 = (offset: number, value: number) =>
bytes.writeUInt32LE(value, offset);
const ptr = (offset: number, target: number) =>
bytes.writeBigUInt64LE(base + BigInt(target), offset);
u32(0, 0xfeedfacf);
u32(4, 0x0100000c);
u32(16, 1);
u32(20, 152);
u32(32, 0x19);
u32(36, 152);
bytes.write("__DATA", 40);
ptr(56, 0);
bytes.writeBigUInt64LE(2048n, 64);
bytes.writeBigUInt64LE(2048n, 80);
u32(92, 5);
u32(96, 1);
bytes.write("__objc_classlist", 104);
bytes.write("__DATA", 120);
ptr(136, 0x180);
bytes.writeBigUInt64LE(8n, 144);
u32(152, 0x180);
ptr(0x180, 0x200);
ptr(0x200, 0x280);
ptr(0x220, 0x300);
ptr(0x2a0, 0x380);
u32(0x308, 16);
ptr(0x318, 0x450);
ptr(0x320, 0x480);
ptr(0x330, 0x500);
u32(0x380, 1);
ptr(0x398, 0x450);
bytes.write("Fixture\0", 0x450);
bytes.write("performAction:\0", 0x460);
u32(0x480, relative ? 0xc000000c : 24);
u32(0x484, 1);
if (relative) {
bytes.writeInt32LE(0x460 - 0x488, 0x488);
bytes.writeInt32LE(0x5c0 - 0x48c, 0x48c);
bytes.writeInt32LE(0x700 - 0x490, 0x490);
} else {
ptr(0x488, 0x460);
ptr(0x490, 0x5c0);
ptr(0x498, 0x700);
}
u32(0x500, 32);
u32(0x504, 1);
ptr(0x508, 0x580);
ptr(0x510, 0x5a0);
ptr(0x518, 0x5c0);
u32(0x580, 8);
bytes.write("state\0", 0x5a0);
bytes.write("i\0", 0x5c0);
return bytes;
};
const provenance = { path: "/fixture/app", sha256: "a".repeat(64) };
describe("Apple dispatch binary metadata", () => {
it.each([false, true])(
"decodes stripped absolute/relative method lists (relative=%s) with exact offsets",
(relative) => {
const result = decodeAppleDispatchMetadata(
fixture(relative),
100,
provenance,
);
expect(result.objc_classes).toMatchObject([
{
name: "Fixture",
instance_size: 16,
location: { address: "0x100000200", file_offset: 512 },
},
{ name: "Fixture", is_meta_class: true },
]);
expect(result.objc_dispatch_implementations).toMatchObject([
{
selector: "performAction:",
implementation_address: "0x100000700",
location: { file_offset: 0x488 },
decode: { status: "decoded" },
},
]);
expect(result.objc_ivars).toMatchObject([
{
name: "state",
type_encoding: "i",
offset: 8,
location: { file_offset: 0x508 },
},
]);
},
);
it("keeps unsupported pointers and record truncation explicit", () => {
const bytes = fixture();
bytes.writeBigUInt64LE(0xffffffffffffffffn, 0x498);
const result = decodeAppleDispatchMetadata(bytes, 100, provenance);
expect(result.objc_dispatch_implementations[0]).toMatchObject({
implementation_address: null,
decode: { status: "partial" },
});
expect(
decodeAppleDispatchMetadata(fixture(), 1, provenance).coverage[0]?.reason,
).toContain("max_records_reached");
});
it("rejects malformed command and section boundaries", () => {
const bytes = fixture();
bytes.writeUInt32LE(7, 36);
expect(() => decodeAppleDispatchMetadata(bytes, 100, provenance)).toThrow(
"command size",
);
expect(() =>
decodeAppleDispatchMetadata(Buffer.alloc(10), 100, provenance),
).toThrow("Truncated");
});
});
+674
View File
@@ -0,0 +1,674 @@
import { createHash } from "node:crypto";
import { open } from "node:fs/promises";
import { constants } from "node:fs";
import {
objcSwiftMetadataSchema,
nativeDispatchMetadataResultSchema,
type ObjcSwiftMetadata,
} from "../domain/objcSwiftMetadata.js";
import type { BinaryTarget } from "../domain/binaryTarget.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 = (
bytes: Buffer,
maxRecords: number,
provenance: { path: string; sha256: string },
architecture = "arm64",
): ObjcSwiftMetadata => {
let slice = 0;
let sliceEnd = bytes.length;
if (bytes.length < 32) throw new RangeError("Truncated Mach-O header");
if (bytes.readUInt32BE(0) === 0xcafebabe) {
const count = bytes.readUInt32BE(4);
if (count > 128 || 8 + count * 20 > bytes.length)
throw new RangeError("Malformed FAT architecture table");
const cpu = architecture === "arm64" ? 0x0100000c : 0x01000007;
let selected: number | undefined;
for (let index = 0; index < count; index++) {
const offset = 8 + index * 20;
if (bytes.readUInt32BE(offset) === cpu) {
if (selected !== undefined)
throw new TypeError("Ambiguous FAT architecture slice");
selected = bytes.readUInt32BE(offset + 8);
sliceEnd = selected + bytes.readUInt32BE(offset + 12);
if (sliceEnd > bytes.length || selected < 8 + count * 20)
throw new RangeError("FAT slice exceeds file");
}
}
if (selected === undefined)
throw new TypeError("Requested FAT architecture is absent");
slice = selected;
}
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 u32 = (address: bigint) => bytes.readUInt32LE(offset(address, 4));
const pointer = (address: bigint) =>
bytes.readBigUInt64LE(offset(address, 8));
const location = (address: bigint) => ({
address: hex(address),
file_offset: offset(address),
});
const evidence = (address: bigint, description: string) => [
{
kind: "binary_metadata" as const,
description,
location: location(address),
artifact_path: provenance.path,
artifact_sha256: provenance.sha256,
},
];
const string = (address: bigint) => {
const start = offset(address);
let end = start;
while (end < bytes.length && end - start < 4096 && bytes[end] !== 0) end++;
if (end === bytes.length || end - start >= 4096)
throw new RangeError("Unterminated or oversized metadata string");
offset(address, end - start + 1);
return new TextDecoder("utf-8", { fatal: true }).decode(
bytes.subarray(start, end),
);
};
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 {
/* serialized target remains unresolved */
}
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 {
/* external/chained pointers remain unresolved */
}
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)),
},
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 (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 {
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 {
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)}`,
);
}
}
};
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 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 typeEntries: bigint[] = [];
for (const section of sections.filter(
({ name }) => name === "__swift5_types",
)) {
if (section.size % 4 !== 0)
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;
}
decodeSwiftClassVtables({
entries: typeEntries,
result,
readers: {
u32,
relative: swiftRelative,
string,
location,
evidence,
admit,
executable: (address) =>
segments.some(
(segment) =>
segment.executable &&
address >= segment.address &&
address < segment.address + segment.size,
),
},
});
result.coverage.push({
facet: "objc_class_method_ivar_metadata",
status: failures.length > 0 || truncated ? "partial" : "complete",
reason:
[...failures, ...(truncated ? ["max_records_reached"] : [])].join("; ") ||
null,
examined,
decoded: result.objc_classes.length,
});
result.coverage.push({
facet: "binary_relative_pointers",
status:
truncated ||
result.relative_pointers.some((item) => item.decode.status !== "decoded")
? "partial"
: "complete",
reason: truncated
? "max_records_reached"
: result.relative_pointers.some(
(item) => item.decode.status !== "decoded",
)
? "relative_pointer_targets_unresolved"
: null,
examined: result.relative_pointers.length,
decoded: result.relative_pointers.filter(
(item) => item.decode.status === "decoded",
).length,
});
for (const facet of [
"objc_properties_categories",
"swift_generic_resilient_witnesses_overrides_async_coroutines",
])
result.coverage.push({
facet,
status: "unsupported",
reason:
"This reader admits validated 64-bit Objective-C class/ivar/method lists and simple Swift conformance/static witness records; chained fixups, generic/resilient tables and other metadata families are not decoded",
examined: 0,
decoded: 0,
});
return objcSwiftMetadataSchema.parse(result);
};
/** Read digest-verified target bytes under a 64 MiB static metadata budget. */
export const inspectAppleDispatchMetadata = async (
target: BinaryTarget,
maxRecords: number,
signal?: AbortSignal,
) => {
if (target.kind !== "executable" || target.format !== "mach-o")
throw new TypeError("Apple dispatch metadata requires a Mach-O target");
const handle = await open(
target.path,
constants.O_RDONLY | constants.O_NOFOLLOW,
);
try {
const before = await handle.stat();
if (!before.isFile() || before.size > 64 * 1024 * 1024)
throw new RangeError(
"Apple metadata target must be a regular file no larger than 64 MiB",
);
if (signal?.aborted) throw new Error("cancelled");
const bytes = await handle.readFile({ signal });
const digest = createHash("sha256").update(bytes).digest("hex");
if (digest !== target.sha256)
throw new Error(
"Apple metadata target digest changed after session binding",
);
return nativeDispatchMetadataResultSchema.parse({
target_sha256: target.sha256,
provider: {
id: "native-macos",
name: "macOS native inspection utilities",
version: "apple-metadata-reader-1",
},
analysis_profile_digest: null,
result: decodeAppleDispatchMetadata(
bytes,
maxRecords,
{ path: target.path, sha256: digest },
target.architecture,
),
});
} finally {
await handle.close();
}
};
+98
View File
@@ -0,0 +1,98 @@
import type { ObjcSwiftMetadata } from "../domain/objcSwiftMetadata.js";
import type { SwiftMetadataReaders } from "./AppleSwiftVtables.js";
/** Read protocol lists and absolute protocol method declarations with cycle-safe identities. */
export const createObjcProtocolReader = (input: {
readers: Pick<
SwiftMetadataReaders,
"u32" | "string" | "location" | "evidence" | "admit"
> & { pointer(address: bigint): bigint; i32(address: bigint): number };
result: ObjcSwiftMetadata;
failures: string[];
}) => {
const { readers: read, result, failures } = input;
const visited = new Set<bigint>();
const name = (address: bigint) => read.string(read.pointer(address + 8n));
const list = (address: bigint): string[] => {
if (address === 0n) return [];
const count = read.pointer(address);
if (count > 20000n)
throw new RangeError("Protocol list exceeds 20000 entries");
const names: string[] = [];
for (let index = 0n; index < count; index++) {
if (!read.admit()) break;
const protocol = read.pointer(address + 8n + index * 8n);
names.push(name(protocol));
record(protocol);
}
return names;
};
const methods = (address: bigint, required: boolean, instance: boolean) => {
const output: ObjcSwiftMetadata["objc_protocols"][number]["methods"] = [];
if (address === 0n) return output;
const flags = read.u32(address),
count = read.u32(address + 4n);
const relative = (flags & 0x80000000) !== 0;
const stride = flags & 0xfffc;
if (stride !== (relative ? 12 : 24))
throw new TypeError("Unsupported Objective-C protocol method entry size");
for (let index = 0; index < count; index++) {
if (!read.admit()) break;
const entry = address + 8n + BigInt(index * stride);
let selector = relative
? entry + BigInt(read.i32(entry))
: read.pointer(entry);
if (relative && (flags & 0x40000000) === 0)
selector = read.pointer(selector);
output.push({
selector: read.string(selector),
method_type: instance ? "instance" : "class",
address: null,
is_required: required,
is_optional: !required,
});
}
return output;
};
const record = (address: bigint) => {
if (address === 0n || visited.has(address) || !read.admit()) return;
visited.add(address);
try {
if (read.u32(address + 64n) < 72)
throw new RangeError("Truncated Objective-C protocol declaration");
const protocolName = name(address);
const adopted = list(read.pointer(address + 16n));
const required = [
...methods(read.pointer(address + 24n), true, true),
...methods(read.pointer(address + 32n), true, false),
];
const optional = [
...methods(read.pointer(address + 40n), false, true),
...methods(read.pointer(address + 48n), false, false),
];
result.objc_protocols.push({
name: protocolName,
methods: required,
optional_methods: optional,
properties: [],
});
result.objc_protocol_records.push({
name: protocolName,
adopted_protocols: adopted,
methods: required,
optional_methods: optional,
location: read.location(address),
decode: { status: "decoded", reason: null },
evidence: read.evidence(
address,
"Objective-C protocol declaration and encoded method lists; IMP fields are not handler targets",
),
});
} catch (cause) {
failures.push(
`Protocol 0x${address.toString(16)}: ${cause instanceof Error ? cause.message : String(cause)}`,
);
}
};
return { list, record };
};
+122
View File
@@ -0,0 +1,122 @@
import type {
ObjcSwiftMetadata,
NativeMetadataEvidence,
NativeMetadataLocation,
} from "../domain/objcSwiftMetadata.js";
/** Byte readers shared with the validated Mach-O metadata boundary. */
export interface SwiftMetadataReaders {
u32(address: bigint): number;
relative(address: bigint): bigint;
string(address: bigint): string;
location(address: bigint): NativeMetadataLocation;
evidence(address: bigint, description: string): NativeMetadataEvidence[];
executable(address: bigint): boolean;
admit(): boolean;
}
/** Decode non-generic, non-resilient Swift class vtable descriptors without instantiating metadata. */
export const decodeSwiftClassVtables = (input: {
readers: SwiftMetadataReaders;
entries: readonly bigint[];
result: ObjcSwiftMetadata;
}) => {
const { readers: read, result } = input;
const failures: string[] = [];
let examined = 0;
for (const field of input.entries) {
if (!read.admit()) {
failures.push("max_records_reached");
break;
}
examined++;
try {
const descriptor = read.relative(field);
const flags = read.u32(descriptor);
if ((flags & 31) !== 16) continue;
const specific = flags >>> 16;
if ((flags & 0x80) !== 0 || (specific & 0x2000) !== 0)
throw new TypeError(
"Generic class or resilient superclass metadata is unsupported",
);
if ((specific & 0x8000) === 0) continue;
const initialization = specific & 3;
if (initialization === 3)
throw new TypeError("Unknown metadata initialization kind");
const header =
descriptor +
44n +
BigInt(initialization === 1 ? 12 : initialization === 2 ? 4 : 0);
const tableOffset = read.u32(header);
const count = read.u32(header + 4n);
const positiveWords = read.u32(descriptor + 28n);
if (count > 20000 || tableOffset + count > positiveWords)
throw new RangeError(
"Swift vtable count or offset exceeds declared metadata bounds",
);
const owner = read.string(read.relative(descriptor + 8n));
for (let index = 0; index < count; index++) {
if (!read.admit()) {
failures.push("max_records_reached");
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 =
(methodFlags & 0x40) === 0 && (methodFlags & 15) <= 3;
const implementation = read.relative(entry + 4n);
const resolved = synchronous && read.executable(implementation);
result.swift_dispatch_slots.push({
owner,
table_kind: "class_vtable",
slot_index: tableOffset + index,
requirement: null,
implementation: null,
implementation_address: resolved
? `0x${implementation.toString(16)}`
: null,
thunk_address: null,
location: read.location(entry),
decode: resolved
? { status: "decoded", reason: null }
: {
status: "partial",
reason:
"Async, coroutine, external or unmapped vtable implementation is unresolved",
},
evidence: read.evidence(
entry,
"Swift class vtable method descriptor; slot index is a metadata word offset, not a source method ordinal",
),
});
}
if ((specific & 0x4000) !== 0)
failures.push(
`${owner}: inherited override descriptors are unsupported`,
);
} catch (cause) {
failures.push(
`0x${field.toString(16)}: ${cause instanceof Error ? cause.message : String(cause)}`,
);
}
}
const slots = result.swift_dispatch_slots.filter(
(slot) => slot.table_kind === "class_vtable",
);
result.coverage.push({
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),
});
};
+29
View File
@@ -0,0 +1,29 @@
import type { CapabilityDescriptor } from "../application/AnalysisProvider.js";
/** Apply native host restrictions to portable provider discovery metadata. */
export const nativeHostCapabilities = (
capabilities: readonly CapabilityDescriptor[],
platform: NodeJS.Platform = process.platform,
): readonly CapabilityDescriptor[] => {
if (platform === "darwin") return capabilities;
return capabilities.map((capability): CapabilityDescriptor => {
if (capability.provider.id === "native-macos")
return {
...capability,
available: false,
availabilityCode: "unsupported_host",
reason: "Native macOS utilities require macOS.",
};
if (
capability.provider.id === "rea-artifact-graph" &&
capability.operation === "inspect_asset_catalog"
)
return {
...capability,
available: false,
availabilityCode: "unsupported_host",
reason: "Apple asset catalogs require macOS assetutil.",
};
return capability;
});
};
+83 -5
View File
@@ -1,3 +1,5 @@
import { inspectAppleDispatchMetadata } from "./AppleDispatchMetadata.js";
import { observeNativeUi } from "./NativeUiObservation.js";
import { dirname, isAbsolute, resolve } from "node:path";
import { stat } from "node:fs/promises";
@@ -67,7 +69,10 @@ export class NativeMacOSProvider implements AnalysisProvider {
) {
const available = platform === "darwin";
this.#capabilities = Object.freeze(
NATIVE_TOOL_CONTRACTS.map((contract): CapabilityDescriptor => {
[
...NATIVE_TOOL_CONTRACTS,
{ name: "inspect_native_dispatch_metadata" as const },
].map((contract): CapabilityDescriptor => {
const availability = available
? ({ available: true, reason: null } as const)
: ({
@@ -81,10 +86,13 @@ export class NativeMacOSProvider implements AnalysisProvider {
...availability,
effects: Object.freeze({
mutatesArtifact: false,
launchesProcess: true,
mayShowUi: false,
mayAccessNetwork: false,
mayWriteFilesystem: false,
launchesProcess:
contract.name !== "inspect_native_dispatch_metadata",
mayShowUi: contract.name === "capture_native_ui_scenario",
mayAccessNetwork: contract.name === "capture_native_ui_scenario",
mayWriteFilesystem:
contract.name === "capture_native_ui_scenario" ||
contract.name === "observe_native_ui",
changesPermissions: false,
requiresRoot: false,
}),
@@ -124,6 +132,50 @@ class NativeMacOSClient implements AnalysisClient {
return err(new AnalysisCancelledError(operation));
if (operation === "health")
return ok(createAnalysisExecution(null, IDENTITY));
if (operation === "inspect_native_dispatch_metadata") {
if (this.target.kind !== "executable" || this.target.format !== "mach-o")
return err(
new AnalysisCapabilityUnavailableError(
IDENTITY.id,
operation,
"Binary Apple metadata requires Mach-O; other providers can report symbol-only metadata",
),
);
try {
const maxRecords = z
.number()
.int()
.min(1)
.max(20000)
.parse(parameters.max_records ?? 5000);
const result = await inspectAppleDispatchMetadata(
this.target,
maxRecords,
options?.signal,
);
return ok(
createAnalysisExecution(result, result.provider, {
locations: [{ kind: "artifact-path", path: this.target.path }],
limitations: result.result.coverage.flatMap(({ reason }) =>
reason === null ? [] : [reason],
),
}),
);
} catch (cause) {
return err(
options?.signal?.aborted
? new AnalysisCancelledError(operation)
: new ProviderAdapterError(IDENTITY.id, operation, {
cause,
diagnostics: {
target_path: this.target.path,
reason:
cause instanceof Error ? cause.message : String(cause),
},
}),
);
}
}
if (!isNativeOperation(operation))
return err(
new AnalysisCapabilityUnavailableError(
@@ -132,6 +184,21 @@ class NativeMacOSClient implements AnalysisClient {
"Operation is not implemented by native macOS tools.",
),
);
if (
operation === "observe_native_ui" ||
operation === "capture_native_ui_scenario"
) {
const result = await observeNativeUi(this.target, operation, parameters, {
signal: options?.signal,
});
return result.ok
? ok(
createAnalysisExecution(result.value, IDENTITY, {
limitations: result.value.limitations,
}),
)
: result;
}
try {
const observation = await this.#dispatch(
operation,
@@ -166,6 +233,17 @@ class NativeMacOSClient implements AnalysisClient {
signal?: AbortSignal,
): Promise<Result<NativeObservation, AnalysisError>> {
switch (operation) {
case "observe_native_ui":
case "capture_native_ui_scenario":
return Promise.resolve(
err(
new AnalysisCapabilityUnavailableError(
IDENTITY.id,
operation,
"UI observation uses its explicit authority boundary",
),
),
);
case "inspect_macho":
return this.#inspectMacho(signal);
case "inspect_signature":
+53
View File
@@ -0,0 +1,53 @@
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { execFileOutput } from "../process/ExecFileOutput.js";
import type { NativeUiHelper } from "./NativeUiObservation.js";
/** Lazily compile one owned helper per observation/scenario and remove its compiler cache. */
export const createNativeUiHelperRuntime = () => {
let root: string | undefined;
let executable: string | undefined;
const invoke: NativeUiHelper = async (parameters, signal) => {
if (executable === undefined) {
root = await mkdtemp(join(tmpdir(), "rea-native-ui-"));
const output = join(root, "observer");
await execFileOutput(
"/usr/bin/xcrun",
[
"swiftc",
"-module-cache-path",
join(root, "modules"),
fileURLToPath(
new URL("../../bridge/native/ReaNativeUI.swift", import.meta.url),
),
"-o",
output,
],
{
timeout: 60_000,
maxBuffer: 1024 * 1024,
...(signal === undefined ? {} : { signal }),
},
);
executable = output;
}
const output = await execFileOutput(
executable,
[JSON.stringify(parameters)],
{
timeout: 30_000,
maxBuffer: 16 * 1024 * 1024,
...(signal === undefined ? {} : { signal }),
},
);
return JSON.parse(output.stdout) as unknown;
};
return {
invoke,
close: async () => {
if (root !== undefined) await rm(root, { recursive: true, force: true });
},
};
};
+153
View File
@@ -0,0 +1,153 @@
import { describe, expect, it } from "vitest";
import { observeNativeUi } from "./NativeUiObservation.js";
import type { BinaryTarget } from "../domain/binaryTarget.js";
const target: BinaryTarget = {
path: "/fixture/App",
sha256: "a".repeat(64),
kind: "executable",
format: "mach-o",
architecture: "arm64",
availableArchitectures: ["arm64"],
};
const scope = {
pid: 123,
window_id: 456,
observation_approved: true,
screenshot: false,
};
const snapshot = {
window: {
pid: 123,
window_id: 456,
executable: target.path,
launch_time: 1,
title: "Fixture",
},
nodes: [],
screenshot: null,
gaps: [],
truncated: false,
};
describe("native UI authority and lifecycle", () => {
it("requires observation and independent action approval before invoking a helper", async () => {
let calls = 0;
const invoke = async () => {
calls++;
return { ok: true, result: snapshot };
};
expect(
(
await observeNativeUi(
target,
"observe_native_ui",
{ ...scope, observation_approved: false },
{ invoke },
)
).ok,
).toBe(false);
expect(
(
await observeNativeUi(
target,
"capture_native_ui_scenario",
{
...scope,
restore: "leave-as-is",
steps: [{ kind: "click", path: [] }],
},
{ invoke },
)
).ok,
).toBe(false);
expect(calls).toBe(0);
});
it.each([
"accessibility-denied",
"screen-recording-denied",
"ambiguous-window",
])("preserves actionable %s without fallback", async (code) => {
const result = await observeNativeUi(target, "observe_native_ui", scope, {
invoke: async () => ({
ok: false,
code,
message: "Grant permission or select an unambiguous window",
}),
});
expect(result.ok).toBe(false);
if (!result.ok) expect(result.error.message).toContain(code);
});
it("stops on a failed action and returns ordered before/capture-gap evidence", async () => {
const calls: Readonly<Record<string, unknown>>[] = [];
const result = await observeNativeUi(
target,
"capture_native_ui_scenario",
{
...scope,
actions_approved: true,
restore: "leave-as-is",
steps: [
{ kind: "scroll", path: [1], direction: "increment" },
{ kind: "click", path: [2] },
],
},
{
invoke: async (parameters) => {
calls.push(parameters);
return calls.length === 1
? { ok: true, result: snapshot }
: {
ok: false,
code: "action-failed",
message: "AXIncrement unsupported",
};
},
},
);
expect(calls).toHaveLength(2);
expect(calls[1]).toMatchObject({
launch_time: 1,
action: { kind: "scroll", path: [1] },
});
expect(result.ok).toBe(true);
if (result.ok)
expect(result.value.steps).toMatchObject([
{ index: 0, outcome: "failed", before: snapshot, after: null },
]);
});
it("rejects target replacement and stops subsequent actions after cancellation", async () => {
const controller = new AbortController();
let calls = 0;
const result = await observeNativeUi(
target,
"capture_native_ui_scenario",
{
...scope,
actions_approved: true,
restore: "leave-as-is",
steps: [
{ kind: "wait", milliseconds: 1000 },
{ kind: "click", path: [] },
],
},
{
signal: controller.signal,
invoke: async () => {
calls++;
controller.abort();
return { ok: true, result: snapshot };
},
},
);
expect(calls).toBe(1);
expect(result.ok).toBe(true);
if (result.ok) expect(result.value.steps[0]?.outcome).toBe("cancelled");
const replaced = await observeNativeUi(target, "observe_native_ui", scope, {
invoke: async () => ({
ok: true,
result: { ...snapshot, window: { ...snapshot.window, pid: 999 } },
}),
});
expect(replaced.ok).toBe(false);
});
});
+255
View File
@@ -0,0 +1,255 @@
import { fileURLToPath } from "node:url";
import { z } from "zod";
import type { BinaryTarget } from "../domain/binaryTarget.js";
import {
nativeUiObservationInputSchema,
nativeUiScenarioInputSchema,
nativeUiSnapshotSchema,
nativeUiResultSchema,
} from "../domain/nativeUiObservation.js";
import {
AnalysisCancelledError,
AnalysisCapabilityUnavailableError,
AnalysisInputError,
ProviderAdapterError,
type AnalysisError,
} from "../domain/errors.js";
import { err, ok, type Result } from "../domain/result.js";
import { createNativeUiHelperRuntime } from "./NativeUiHelperRuntime.js";
const helper = fileURLToPath(
new URL("../../bridge/native/ReaNativeUI.swift", import.meta.url),
);
const responseSchema = z.discriminatedUnion("ok", [
z.strictObject({ ok: z.literal(true), result: nativeUiSnapshotSchema }),
z.strictObject({
ok: z.literal(false),
code: z.string(),
message: z.string(),
}),
]);
/** Narrow process seam preserves the native helper's permission and target failures. */
export type NativeUiHelper = (
parameters: Readonly<Record<string, unknown>>,
signal?: AbortSignal,
) => Promise<unknown>;
/** Capture a selected existing app window, with separately approved bounded scenarios. */
export const observeNativeUi = async (
target: BinaryTarget,
operation: "observe_native_ui" | "capture_native_ui_scenario",
parameters: unknown,
options: { signal?: AbortSignal | undefined; invoke?: NativeUiHelper } = {},
): Promise<Result<z.infer<typeof nativeUiResultSchema>, AnalysisError>> => {
const runtime = createNativeUiHelperRuntime();
try {
return await observeWithHelper(target, operation, parameters, {
...options,
invoke: options.invoke ?? runtime.invoke,
});
} finally {
await runtime.close();
}
};
const observeWithHelper = async (
target: BinaryTarget,
operation: "observe_native_ui" | "capture_native_ui_scenario",
parameters: unknown,
options: { signal?: AbortSignal | undefined; invoke: NativeUiHelper },
): Promise<Result<z.infer<typeof nativeUiResultSchema>, AnalysisError>> => {
const parsed = (
operation === "observe_native_ui"
? nativeUiObservationInputSchema
: nativeUiScenarioInputSchema
).safeParse(parameters);
if (!parsed.success)
return err(new AnalysisInputError(operation, { cause: parsed.error }));
if (target.kind !== "executable" || target.format !== "mach-o")
return err(
new AnalysisCapabilityUnavailableError(
"native-macos",
operation,
"Native UI observation requires an active Mach-O executable or app target",
),
);
const input = parsed.data;
if (!input.screenshot && !input.accessibility)
return err(
new AnalysisInputError(operation, {
cause: new Error("Enable screenshot or accessibility capture"),
}),
);
const steps =
operation === "capture_native_ui_scenario"
? nativeUiScenarioInputSchema.parse(parameters).steps
: [];
const waitMs = steps.reduce(
(sum, step) => sum + (step.kind === "wait" ? step.milliseconds : 0),
0,
);
if (waitMs > 30_000)
return err(
new AnalysisInputError(operation, {
cause: new Error("Scenario waits may total at most 30000 ms"),
}),
);
const signal =
options.signal === undefined
? AbortSignal.timeout(180_000)
: AbortSignal.any([options.signal, AbortSignal.timeout(180_000)]);
const invoke = options.invoke;
let launchTime: number | undefined;
let outputBytes = 0;
const take = async (
action?: unknown,
): Promise<Result<z.infer<typeof nativeUiSnapshotSchema>, AnalysisError>> => {
if (signal.aborted) return err(new AnalysisCancelledError(operation));
try {
const response = responseSchema.parse(
await invoke(
{
pid: input.pid,
window_id: input.window_id,
executable: target.path,
sha256: target.sha256,
...(launchTime === undefined ? {} : { launch_time: launchTime }),
screenshot: input.screenshot,
accessibility: input.accessibility,
max_nodes: input.max_nodes,
...(action === undefined ? {} : { action }),
},
signal,
),
);
if (!response.ok)
return err(
new AnalysisCapabilityUnavailableError(
"native-macos",
operation,
`${response.code}: ${response.message}`,
),
);
if (
response.result.window.pid !== input.pid ||
response.result.window.window_id !== input.window_id ||
response.result.window.executable !== target.path ||
(launchTime !== undefined &&
response.result.window.launch_time !== launchTime)
)
return err(
new AnalysisCapabilityUnavailableError(
"native-macos",
operation,
"Native helper returned a different target process or window",
),
);
launchTime = response.result.window.launch_time;
outputBytes += 2 * Buffer.byteLength(JSON.stringify(response.result));
if (outputBytes > 64 * 1024 * 1024)
return err(
new AnalysisCapabilityUnavailableError(
"native-macos",
operation,
"Scenario captures exceeded the 64 MiB output budget",
),
);
return ok(response.result);
} catch (cause) {
return err(
signal.aborted
? new AnalysisCancelledError(operation)
: new ProviderAdapterError("native-macos", operation, {
cause,
diagnostics: {
helper_path: helper,
reason:
"Native helper failed, timed out, or returned malformed capture data; install compatible Xcode command-line tools and inspect local OS permissions",
},
}),
);
}
};
const initial = await take();
if (!initial.ok) return initial;
const results: z.infer<typeof nativeUiResultSchema>["steps"] = [];
let before = initial.value;
for (const [index, step] of steps.entries()) {
if (signal.aborted) {
results.push({
index,
kind: step.kind,
before,
after: null,
outcome: "cancelled",
reason: "Scenario cancelled before action",
});
break;
}
if (step.kind === "wait") {
try {
await new Promise<void>((resolve, reject) => {
const abort = () => {
clearTimeout(timer);
reject(new Error("cancelled"));
};
const timer = setTimeout(() => {
signal.removeEventListener("abort", abort);
resolve();
}, step.milliseconds);
signal.addEventListener("abort", abort, { once: true });
if (signal.aborted) abort();
});
} catch {
results.push({
index,
kind: step.kind,
before,
after: null,
outcome: "cancelled",
reason: "Scenario cancelled during wait",
});
break;
}
}
const after = await take(step.kind === "wait" ? undefined : step);
if (!after.ok) {
results.push({
index,
kind: step.kind,
before,
after: null,
outcome:
after.error._tag === "AnalysisCancelledError"
? "cancelled"
: "failed",
reason: after.error.message,
});
break;
}
results.push({
index,
kind: step.kind,
before,
after: after.value,
outcome: "completed",
reason: null,
});
before = after.value;
}
return ok(
nativeUiResultSchema.parse({
target_sha256: target.sha256,
initial: initial.value,
steps: results,
restore: "leave-as-is",
limitations: [
"Only the explicitly selected already-running process/window is admitted. REA starts no target process and does not change permissions, foreground applications, or restore application data.",
"Click uses AXPress; scroll uses AXIncrement/AXDecrement; key-entry sets the selected element's AXValue. Unsupported elements fail without global event fallback.",
"Each completed action is followed immediately by capture; delayed UI changes require explicit wait steps. A failed after-capture can follow a completed action, so failure does not prove absence of application effects.",
"Scenarios can change app data, cause app network activity and persist changes. The caller explicitly chooses leave-as-is; automatic restoration is unsupported.",
"Window matching uses exact PID and window ID for screenshots and unique accessibility geometry. Accessibility paths can change as the UI changes; stale or ambiguous paths fail. Screenshots are scaled to at most 2048 pixels, each PNG to 8 MiB, total captures to 64 MiB, and scenario duration to 180 seconds.",
],
}),
);
};