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:
@@ -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");
|
||||
});
|
||||
});
|
||||
@@ -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();
|
||||
}
|
||||
};
|
||||
@@ -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 };
|
||||
};
|
||||
@@ -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),
|
||||
});
|
||||
};
|
||||
@@ -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;
|
||||
});
|
||||
};
|
||||
@@ -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":
|
||||
|
||||
@@ -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 });
|
||||
},
|
||||
};
|
||||
};
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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.",
|
||||
],
|
||||
}),
|
||||
);
|
||||
};
|
||||
Reference in New Issue
Block a user