reverseport 0.0.0-stage → 1.2.0

package/dist/hopper/HopperDiagnostics.js

@@ -0,0 +1,14 @@
+/** Retain actionable ownership coordinates without exposing the run token. */
+export const createOwnedHopperShutdownDiagnostic = (launch, stopped, cleanup) => ({
+    type: "owned-shutdown",
+    status: stopped.status,
+    launcher_pid: launch.ownership?.leaderPid ?? launch.process.pid ?? null,
+    process_group_id: launch.ownership?.processGroupId ?? null,
+    cleanup_signaled: cleanup?.cleaned === true ? cleanup.signaled : null,
+    reason: stopped.status === "incomplete" ? stopped.reason : null,
+});
+/** Convert an unexpected cleanup rejection without exposing a stack or token. */
+export const providerCleanupFailure = (_cause) => ({
+    cleaned: false,
+    reason: "owned provider cleanup failed",
+});

package/dist/hopper/HopperFileOffset.js

@@ -0,0 +1,237 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { z } from "zod";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { BinaryTargetError } from "../domain/configurationErrors.js";
+import { readFatSliceDeclarations, validateFatSlice, } from "../domain/apple/machoContainer.js";
+import { err, ok } from "../domain/result.js";
+const OPERATION = "address_to_file_offset";
+const MAX_FAT_ARCHITECTURES = 128;
+const PREFIX_BYTES = 8 + MAX_FAT_ARCHITECTURES * 32;
+const observationSchema = z.strictObject({
+    address: z.string().regex(/^0x[0-9a-f]+$/u),
+    provider_file_offset: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(Number.MAX_SAFE_INTEGER),
+    provider_source_path: z.string().nullable(),
+    provider_image_header_hex: z
+        .string()
+        .regex(/^[a-f0-9]{24}$/u)
+        .nullable(),
+});
+/** Bind native image-relative offsets to coordinates in the admitted source bytes. */
+export async function mapHopperFileOffset(target, value, signal) {
+    const parsed = observationSchema.safeParse(value);
+    if (!parsed.success)
+        return err(new AnalysisOutputError(OPERATION, "Hopper's native file mapping observation is malformed"));
+    const observation = parsed.data;
+    const partial = (reason) => ({
+        operation: OPERATION,
+        ...observation,
+        original_file_offset: { available: false, reason },
+    });
+    const unavailable = (reason) => err(new AnalysisCapabilityUnavailableError("hopper", OPERATION, reason, {
+        partialObservation: partial(reason),
+    }));
+    if (target.kind !== "executable")
+        return unavailable("The selected database digest does not identify its original executable bytes. Open that executable to verify original-file coordinates; read_bytes still exposes the database's native bytes.");
+    if (signal?.aborted)
+        return err(new AnalysisCancelledError(OPERATION, {
+            partialObservation: partial("Source verification was cancelled"),
+        }));
+    try {
+        const captured = await snapshotFromPath(target.path, signal);
+        if (!captured.ok)
+            return err(new AnalysisArtifactChangedError(OPERATION, target.path, captured.error, {
+                partialObservation: partial(captured.error),
+            }));
+        const snapshot = captured.value;
+        if (signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION, {
+                partialObservation: partial("Source verification was cancelled"),
+            }));
+        if (snapshot.sha256 !== target.sha256) {
+            const reason = `Source ${target.path} differs from the admitted artifact: expected SHA-256 ${target.sha256}, observed ${snapshot.sha256}. Reopen the changed source for a new analysis identity.`;
+            return err(new AnalysisArtifactChangedError(OPERATION, target.path, reason, {
+                partialObservation: partial(reason),
+            }));
+        }
+        const mapped = originalOffset(snapshot, observation);
+        if (!mapped.ok)
+            return unavailable(mapped.error);
+        return ok({
+            address: observation.address,
+            file_offset: mapped.value + observation.provider_file_offset,
+            provider_file_offset: observation.provider_file_offset,
+            image_base_file_offset: mapped.value,
+            source_path: target.path,
+        });
+    }
+    catch (cause) {
+        if (signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION, {
+                cause,
+                partialObservation: partial("Source verification was cancelled"),
+            }));
+        const reason = `Cannot verify original source bytes: ${cause instanceof Error ? cause.message : String(cause)}`;
+        const code = typeof cause === "object" && cause !== null && "code" in cause
+            ? cause.code
+            : undefined;
+        if (code === "EACCES" || code === "EPERM")
+            return err(new AnalysisAccessDeniedError(OPERATION, target.path, code, {
+                cause,
+                partialObservation: partial(reason),
+            }));
+        return err(new BinaryTargetError(target.path, reason, {
+            cause,
+            partialObservation: partial(reason),
+        }));
+    }
+}
+async function snapshotFromPath(path, signal) {
+    const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        if (!(await file.stat()).isFile())
+            return err(`Source ${path} is no longer a regular file. Restore the admitted executable or reopen a regular source.`);
+        return ok(await readSourceSnapshot(file, signal));
+    }
+    finally {
+        await file.close();
+    }
+}
+function fatLayout(prefix) {
+    const magic = prefix.length < 4 ? 0 : prefix.readUInt32BE(0);
+    if (![0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
+        return ok(null);
+    if (prefix.length < 8)
+        return err("The original FAT header is truncated");
+    const littleEndian = magic === 0xbebafeca || magic === 0xbfbafeca;
+    const wide = magic === 0xcafebabf || magic === 0xbfbafeca;
+    const count = littleEndian ? prefix.readUInt32LE(4) : prefix.readUInt32BE(4);
+    if (count === 0 || count > MAX_FAT_ARCHITECTURES)
+        return err("FAT architecture count is outside the supported 1..128 range");
+    const tableEnd = 8 + count * (wide ? 32 : 20);
+    const table = prefix.subarray(8, tableEnd);
+    const parsed = readFatSliceDeclarations(table, { count, wide, littleEndian });
+    if (parsed.status !== "parsed")
+        return err(parsed.reason);
+    if (wide) {
+        for (const slice of parsed.slices)
+            if ((littleEndian
+                ? table.readUInt32LE(slice.index * 32 + 28)
+                : table.readUInt32BE(slice.index * 32 + 28)) !== 0)
+                return err(`FAT64 architecture ${slice.index} has a nonzero reserved field`);
+    }
+    return ok({ slices: parsed.slices, tableEnd });
+}
+async function readSourceSnapshot(file, signal) {
+    const prefix = Buffer.alloc(PREFIX_BYTES);
+    const hash = createHash("sha256");
+    let size = 0;
+    let layout;
+    const headers = new Map();
+    const capture = (bytes, position) => {
+        if (layout?.ok !== true || layout.value === null)
+            return;
+        for (const slice of layout.value.slices) {
+            const start = Math.max(position, slice.offset);
+            const end = Math.min(position + bytes.length, slice.offset + 12);
+            if (end <= start)
+                continue;
+            let header = headers.get(slice.index);
+            if (header === undefined) {
+                header = Buffer.alloc(12);
+                headers.set(slice.index, header);
+            }
+            bytes.copy(header, start - slice.offset, start - position, end - position);
+        }
+    };
+    for await (const chunk of file.createReadStream({
+        start: 0,
+        autoClose: false,
+        ...(signal === undefined ? {} : { signal }),
+    })) {
+        const bytes = Buffer.from(chunk);
+        hash.update(bytes);
+        if (size < prefix.length)
+            bytes.copy(prefix, size, 0, Math.min(bytes.length, prefix.length - size));
+        if (layout === undefined && size + bytes.length >= prefix.length) {
+            layout = fatLayout(prefix);
+            capture(prefix, 0);
+        }
+        capture(bytes, size);
+        size += bytes.length;
+    }
+    if (layout === undefined) {
+        layout = fatLayout(prefix.subarray(0, size));
+        capture(prefix.subarray(0, size), 0);
+    }
+    return { layout, headers, size, sha256: hash.digest("hex") };
+}
+function originalOffset(snapshot, observation) {
+    const { layout, size, headers } = snapshot;
+    if (!layout.ok)
+        return layout;
+    if (layout.value === null)
+        return observation.provider_file_offset < size
+            ? ok(0)
+            : err("Provider mapping lies outside the admitted executable bytes");
+    const header = observation.provider_image_header_hex === null
+        ? null
+        : Buffer.from(observation.provider_image_header_hex, "hex");
+    const loadedMagic = header?.readUInt32BE(0);
+    if (header === null ||
+        loadedMagic === undefined ||
+        ![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(loadedMagic))
+        return err("Hopper did not expose the loaded Mach-O header needed to identify its FAT slice");
+    const little = loadedMagic === 0xcefaedfe || loadedMagic === 0xcffaedfe;
+    const cpu = little ? header.readUInt32LE(4) : header.readUInt32BE(4);
+    const subtype = little ? header.readUInt32LE(8) : header.readUInt32BE(8);
+    const matches = [];
+    const ranges = [...layout.value.slices].sort((a, b) => a.offset - b.offset);
+    for (let index = 1; index < ranges.length; index++) {
+        const previous = ranges[index - 1];
+        const current = ranges[index];
+        if (previous !== undefined &&
+            current !== undefined &&
+            current.offset < previous.offset + previous.size)
+            return err("Original FAT slices overlap");
+    }
+    for (const slice of layout.value.slices) {
+        const reason = validateFatSlice(slice, size, layout.value.tableEnd);
+        if (reason !== null)
+            return err(reason);
+        const embedded = headers.get(slice.index);
+        if (slice.size < 12 || embedded === undefined)
+            return err(`FAT architecture ${slice.index} has a truncated Mach-O header`);
+        const embeddedMagic = embedded.readUInt32BE(0);
+        if (![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(embeddedMagic))
+            return err(`FAT architecture ${slice.index} does not contain a Mach-O image`);
+        const embeddedLittle = embeddedMagic === 0xcefaedfe || embeddedMagic === 0xcffaedfe;
+        const identityError = validateFatSlice(slice, size, layout.value.tableEnd, {
+            cpuType: embeddedLittle
+                ? embedded.readUInt32LE(4)
+                : embedded.readUInt32BE(4),
+            cpuSubtype: embeddedLittle
+                ? embedded.readUInt32LE(8)
+                : embedded.readUInt32BE(8),
+        });
+        if (identityError !== null)
+            return err(identityError);
+        if (slice.cpuType === cpu && slice.cpuSubtype === subtype)
+            matches.push(slice);
+    }
+    const selected = matches.length === 1 ? matches[0] : undefined;
+    if (selected === undefined)
+        return err(`Original FAT slice matching Hopper's loaded header is ${matches.length === 0 ? "missing" : "ambiguous"}`);
+    if (headers.get(selected.index)?.equals(header) !== true)
+        return err("Original FAT slice header disagrees with Hopper's loaded header");
+    if (observation.provider_file_offset >= selected.size)
+        return err("Provider mapping lies outside the loaded FAT slice");
+    if (!Number.isSafeInteger(selected.offset + observation.provider_file_offset))
+        return err("Original file offset exceeds the exact JSON integer range");
+    return ok(selected.offset);
+}

package/dist/hopper/HopperMachOImage.js

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import { open } from "node:fs/promises";
+import { z } from "zod";
+import { isMachOFormat, } from "../domain/binaryTargetTypes.js";
+import { BinaryTargetError } from "../domain/configurationErrors.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { readFatSliceDeclarations, validateFatSlice, } from "../domain/apple/machoContainer.js";
+import { HopperCancelledError, HopperStartError, } from "../domain/hopperErrors.js";
+import { err, ok } from "../domain/result.js";
+/** Stable source coordinates committed before preparing an owned thin image. */
+export const hopperMachOImageSchema = z.strictObject({
+    method: z.literal("fat64_thin_slice"),
+    architecture_count: z.number().int().min(1).max(128),
+    container_table_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    source_offset: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    byte_length: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    cpu_type: z.number().int().nonnegative(),
+    cpu_subtype: z.number().int().nonnegative(),
+});
+/** Validate the selected FAT64 slice without depending on Apple's lipo tool. */
+export const resolveHopperMachOImage = async (target, signal) => {
+    const invalid = (reason, cause) => err(new BinaryTargetError(target.path, reason, cause === undefined ? undefined : { cause }));
+    if (signal?.aborted)
+        return err(new AnalysisCancelledError("open_binary"));
+    if (!isMachOFormat(target.format) || target.architecture === "mips")
+        return invalid("Hopper FAT64 image preparation requires a Mach-O target");
+    let file;
+    try {
+        file = await open(target.path, "r");
+    }
+    catch (cause) {
+        // Keep the OS error so a read-permission denial reports access_denied.
+        return invalid(`Cannot read FAT64 source for Hopper image preparation: ${cause instanceof Error ? cause.message : String(cause)}`, cause);
+    }
+    try {
+        const read = async (offset, length) => {
+            const bytes = Buffer.alloc(length);
+            const { bytesRead } = await file.read(bytes, 0, length, offset);
+            return bytes.subarray(0, bytesRead);
+        };
+        const header = await read(0, 8);
+        const magic = header.length === 8 ? header.readUInt32BE(0) : 0;
+        if (magic !== 0xcafebabf && magic !== 0xbfbafeca)
+            return invalid("FAT64 source header changed before Hopper image preparation");
+        const littleEndian = magic === 0xbfbafeca;
+        const count = littleEndian
+            ? header.readUInt32LE(4)
+            : header.readUInt32BE(4);
+        const size = (await file.stat()).size;
+        const tableEnd = 8 + count * 32;
+        if (count === 0 || count > 128 || tableEnd > size)
+            return invalid("FAT64 architecture table is truncated or exceeds the supported 128 entries");
+        const table = await read(8, count * 32);
+        const parsed = readFatSliceDeclarations(table, {
+            count,
+            wide: true,
+            littleEndian,
+        });
+        if (parsed.status === "malformed")
+            return invalid(parsed.reason);
+        const cpuTypes = { x86: 7, x86_64: 0x1000007, arm: 12, arm64: 0x100000c };
+        const matches = [];
+        const ranges = [];
+        for (const slice of parsed.slices) {
+            if (signal?.aborted)
+                return err(new AnalysisCancelledError("open_binary"));
+            const rangeError = validateFatSlice(slice, size, tableEnd);
+            if (rangeError !== null)
+                return invalid(rangeError);
+            const reserved = littleEndian
+                ? table.readUInt32LE(slice.index * 32 + 28)
+                : table.readUInt32BE(slice.index * 32 + 28);
+            if (reserved !== 0)
+                return invalid(`FAT64 architecture ${slice.index} has a nonzero reserved field`);
+            if (slice.size < 12)
+                return invalid(`FAT64 architecture ${slice.index} has a truncated Mach-O header`);
+            const embedded = await read(slice.offset, 12);
+            if (embedded.length !== 12)
+                return invalid(`FAT64 architecture ${slice.index} became truncated`);
+            const thinMagic = embedded.readUInt32BE(0);
+            if (![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(thinMagic))
+                return invalid(`FAT64 architecture ${slice.index} does not contain a Mach-O image`);
+            const little = thinMagic === 0xcefaedfe || thinMagic === 0xcffaedfe;
+            const identity = {
+                cpuType: little ? embedded.readUInt32LE(4) : embedded.readUInt32BE(4),
+                cpuSubtype: little
+                    ? embedded.readUInt32LE(8)
+                    : embedded.readUInt32BE(8),
+            };
+            const identityError = validateFatSlice(slice, size, tableEnd, identity);
+            if (identityError !== null)
+                return invalid(identityError);
+            ranges.push(slice);
+            if (slice.cpuType === cpuTypes[target.architecture])
+                matches.push(slice);
+        }
+        ranges.sort((a, b) => a.offset - b.offset);
+        for (let index = 1; index < ranges.length; index++) {
+            const previous = ranges[index - 1];
+            const current = ranges[index];
+            if (previous !== undefined &&
+                current !== undefined &&
+                current.offset < previous.offset + previous.size)
+                return invalid("FAT64 slices overlap");
+        }
+        const selected = matches.length === 1 ? matches[0] : undefined;
+        if (selected === undefined)
+            return invalid(`FAT64 selection for ${target.architecture} is ${matches.length === 0 ? "missing" : "ambiguous"}; extract the exact architecture into a thin image before opening it`);
+        return ok({
+            method: "fat64_thin_slice",
+            architecture_count: count,
+            container_table_sha256: createHash("sha256")
+                .update(header)
+                .update(table)
+                .digest("hex"),
+            source_offset: selected.offset,
+            byte_length: selected.size,
+            cpu_type: selected.cpuType,
+            cpu_subtype: selected.cpuSubtype,
+        });
+    }
+    catch (cause) {
+        return invalid(`Cannot validate FAT64 image: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    finally {
+        await file.close();
+    }
+};
+/** Copy a selected slice and verify the entire original source in the same pass. */
+export const prepareHopperMachOImage = async (sourcePath, sourceSha256, image, destination, signal) => {
+    if (signal?.aborted)
+        return err(new HopperCancelledError());
+    try {
+        const source = await open(sourcePath, "r");
+        try {
+            const output = await open(destination, "wx", 0o600);
+            try {
+                const hash = createHash("sha256");
+                const tableHash = createHash("sha256");
+                const tableEnd = 8 + image.architecture_count * 32;
+                const thinHeader = [];
+                let position = 0;
+                let copied = 0;
+                for await (const chunk of source.createReadStream({
+                    autoClose: false,
+                })) {
+                    if (signal?.aborted)
+                        return err(new HopperCancelledError());
+                    const bytes = Buffer.from(chunk);
+                    hash.update(bytes);
+                    if (position < tableEnd)
+                        tableHash.update(bytes.subarray(0, Math.min(bytes.length, tableEnd - position)));
+                    const start = Math.max(0, image.source_offset - position);
+                    const end = Math.min(bytes.length, image.source_offset + image.byte_length - position);
+                    if (end > start) {
+                        if (copied < 12)
+                            thinHeader.push(bytes.subarray(start, Math.min(end, start + 12 - copied)));
+                        await output.writeFile(bytes.subarray(start, end));
+                        copied += end - start;
+                    }
+                    position += bytes.length;
+                }
+                const observed = hash.digest("hex");
+                const header = Buffer.concat(thinHeader);
+                const magic = header.length === 12 ? header.readUInt32BE(0) : 0;
+                const little = magic === 0xcefaedfe || magic === 0xcffaedfe;
+                const headerMatches = header.length === 12 &&
+                    [0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic) &&
+                    (little ? header.readUInt32LE(4) : header.readUInt32BE(4)) ===
+                        image.cpu_type &&
+                    (little ? header.readUInt32LE(8) : header.readUInt32BE(8)) ===
+                        image.cpu_subtype;
+                if (tableHash.digest("hex") !== image.container_table_sha256 ||
+                    !headerMatches)
+                    return err(new HopperStartError({
+                        userMessage: `FAT64 source ${sourcePath} no longer agrees with its committed architecture table or selected Mach-O header. Open the stable source again.`,
+                    }));
+                if (observed !== sourceSha256 || copied !== image.byte_length)
+                    return err(new HopperStartError({
+                        userMessage: `FAT64 source ${sourcePath} changed before launch: expected SHA-256 ${sourceSha256}, observed ${observed}; copied ${copied} of ${image.byte_length} selected bytes. Open the stable source again.`,
+                    }));
+                return ok(destination);
+            }
+            finally {
+                await output.close();
+            }
+        }
+        finally {
+            await source.close();
+        }
+    }
+    catch (cause) {
+        return signal?.aborted
+            ? err(new HopperCancelledError())
+            : err(new HopperStartError({
+                cause,
+                userMessage: `Cannot prepare the selected FAT64 image from ${sourcePath}: ${cause instanceof Error ? cause.message : String(cause)}`,
+            }));
+    }
+};

package/dist/hopper/HopperOperationStage.js

@@ -0,0 +1,6 @@
+/** Classify Hopper wire operations at their provider boundary. */
+export const hopperOperationStage = (operation) => {
+    if (operation === "health")
+        return "connection";
+    return operation === "procedure_pseudo_code" ? "decompilation" : "analysis";
+};

package/dist/hopper/HopperProcessDiagnostic.js

@@ -0,0 +1,26 @@
+import { hopperStartupFailure, } from "../domain/hopperStartupFailure.js";
+import { parseLinuxPrivateDisplayDiagnostic } from "./LinuxPrivateDisplayDiagnostic.js";
+/**
+ * Hopper's native helper sends activate before its open-document Apple event.
+ * Recognize its explicit authorization rejection. The launcher must separately
+ * establish that caller arguments could not alter the generated AppleScript.
+ * Other script errors, signals, and incomplete output leave ownership unknown.
+ */
+export const nativeHopperLaunchWasDenied = (outcome) => outcome !== undefined &&
+    outcome.exit_code === 2 &&
+    outcome.signal === null &&
+    outcome.output_closed &&
+    !outcome.diagnostic_truncated &&
+    /^Cannot launch Hopper!\r?\nNot authorized to send Apple events to [^\r\n]+\.\r?\n?$/u.test(outcome.stderr.text);
+/** Extract only a matching Linux adapter failure record. */
+export const hopperLauncherFailureDiagnostic = (event) => {
+    const parsed = parseLinuxPrivateDisplayDiagnostic(event.snapshot.stderr.text);
+    if (!parsed.ok)
+        return undefined;
+    const expected = hopperStartupFailure(event.code)?.code;
+    return parsed.value.operation === "launch" &&
+        parsed.value.status === "error" &&
+        parsed.value.failure_code === expected
+        ? parsed.value
+        : undefined;
+};