rea/src/hopper/HopperAnalysisProfile.ts

import { createHash } from "node:crypto";
import { createReadStream } from "node:fs";

import type {
  AnalysisProfileResolution,
  ProviderIdentity,
} from "../application/AnalysisProvider.js";
import { createAnalysisProfile } from "../domain/analysisProfile.js";
import {
  isMachOFormat,
  isElfMetadataArchitecture,
  type BinaryTarget,
  type ElfMetadataArchitecture,
  type HeaderArchitecture,
} from "../domain/binaryTargetTypes.js";
import {
  AnalysisCancelledError,
  AnalysisCapabilityUnavailableError,
} from "../domain/analysisErrorCore.js";
import { BinaryTargetError } from "../domain/configurationErrors.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import { err, ok, type Result } from "../domain/result.js";

import {
  resolveHopperMachOImage,
  type HopperMachOImage,
} from "./HopperMachOImage.js";

interface HopperProfileOptions {
  readonly launcherPath: string;
  readonly loaderArgsOverride: readonly string[];
  readonly provider: ProviderIdentity;
  readonly signal?: AbortSignal;
}

/** Resolve Hopper open semantics without placing its CLI flags in BinaryTarget. */
export const resolveHopperAnalysisProfile = async (
  target: BinaryTarget,
  options: HopperProfileOptions,
): Promise<Result<AnalysisProfileResolution, AnalysisError>> => {
  if (target.kind !== "executable" && target.kind !== "database")
    return ok({ profile: null });
  let machoContainer: "thin" | "fat32" | "fat64" | undefined;
  if (target.kind === "executable" && isMachOFormat(target.format)) {
    const header = await readMachoMagic(target.path, options.signal);
    if (!header.ok) return header;
    machoContainer = [0xcafebabf, 0xbfbafeca].includes(header.value)
      ? "fat64"
      : [0xcafebabe, 0xbebafeca].includes(header.value)
        ? "fat32"
        : "thin";
  }
  let preparedImage: HopperMachOImage | undefined;
  if (
    target.kind === "executable" &&
    machoContainer === "fat64" &&
    options.loaderArgsOverride.length === 0
  ) {
    const resolved = await resolveHopperMachOImage(target, options.signal);
    if (!resolved.ok) return resolved;
    preparedImage = resolved.value;
  }
  const derived = hopperLoaderArgsForTarget(
    target,
    preparedImage === undefined ? machoContainer : "thin",
  );
  if (!derived.ok) return derived;
  const loaderArgs =
    options.loaderArgsOverride.length === 0
      ? derived.value
      : [...options.loaderArgsOverride];
  const launcherDigest = await sha256File(options.launcherPath, options.signal);
  if (!launcherDigest.ok) return launcherDigest;
  if (launcherDigest.value === undefined) return ok({ profile: null });
  const provider = {
    id: options.provider.id,
    name: options.provider.name,
    version: `launcher-sha256:${launcherDigest.value}`,
  };
  return ok({
    profile: createAnalysisProfile(provider, {
      target_kind: target.kind,
      target_format: target.format,
      architecture: target.architecture ?? null,
      available_architectures: [
        ...(target.availableArchitectures ?? []),
      ].sort(),
      ...(machoContainer === undefined
        ? {}
        : { macho_container: machoContainer }),
      ...(preparedImage === undefined
        ? {}
        : { prepared_image: { ...preparedImage } }),
      loader: {
        source:
          options.loaderArgsOverride.length === 0
            ? "derived"
            : "configured_override",
        arguments: [...loaderArgs],
      },
    }),
  });
};

/** Ghidra owns these lanes; Hopper names the family it declines rather than guessing. */
const HOPPER_DECLINED_ARCHITECTURE_LABELS: Record<
  ElfMetadataArchitecture,
  string
> = {
  mips: "MIPS",
  riscv: "RISC-V",
};

/** Derive Hopper's complete non-interactive CLI loader selection. */
export const hopperLoaderArgsForTarget = (
  target: BinaryTarget,
  machoContainer?: "thin" | "fat32" | "fat64",
): Result<
  readonly string[],
  ProviderAdapterError | AnalysisCapabilityUnavailableError
> => {
  if (target.kind === "database") return ok([]);
  if (target.kind !== "executable")
    return err(new ProviderAdapterError("hopper", "resolve_analysis_profile"));
  if (target.format === "raw-binary")
    return err(new ProviderAdapterError("hopper", "resolve_analysis_profile"));
  const architecture = target.architecture;
  if (isElfMetadataArchitecture(architecture))
    return err(
      new AnalysisCapabilityUnavailableError(
        "hopper",
        "resolve_analysis_profile",
        `REA's Hopper adapter does not admit ${HOPPER_DECLINED_ARCHITECTURE_LABELS[architecture]} targets. Select a verified Ghidra ${HOPPER_DECLINED_ARCHITECTURE_LABELS[architecture]} profile instead.`,
      ),
    );
  const flag = hopperArchitectureFlag(architecture);
  if (isMachOFormat(target.format)) {
    if (machoContainer === undefined)
      return err(
        new AnalysisCapabilityUnavailableError(
          "hopper",
          "resolve_analysis_profile",
          "Mach-O container kind is unknown; resolve the Hopper analysis profile before starting its client.",
        ),
      );
    return ok(
      machoContainer === "fat32" || machoContainer === "fat64"
        ? ["-l", "FAT", flag, "-l", "Mach-O"]
        : ["-l", "Mach-O", flag],
    );
  }
  switch (target.format) {
    case "elf":
      return ok(["-l", "ELF", flag]);
    case "pe":
      return ok(["-l", "WinPE", flag]);
    case "dos-mz":
    case "dos-com":
      return err(
        new ProviderAdapterError("hopper", "resolve_analysis_profile"),
      );
  }
};

const hopperArchitectureFlag = (architecture: HeaderArchitecture): string => {
  switch (architecture) {
    case "x86":
      return "--intel-32";
    case "x86_64":
      return "--intel-64";
    case "arm":
      return "--armv7";
    case "arm64":
      return "--aarch64";
  }
};

const readMachoMagic = async (
  path: string,
  signal?: AbortSignal,
): Promise<Result<number, AnalysisError>> => {
  if (signalIsAborted(signal))
    return err(new AnalysisCancelledError("open_binary"));
  const stream = createReadStream(path, { start: 0, end: 3 });
  const onAbort = (): void => {
    stream.destroy();
  };
  signal?.addEventListener("abort", onAbort, { once: true });
  try {
    const chunks: Buffer[] = [];
    for await (const chunk of stream) chunks.push(Buffer.from(chunk));
    if (signalIsAborted(signal))
      return err(new AnalysisCancelledError("open_binary"));
    const bytes = Buffer.concat(chunks);
    return bytes.length === 4
      ? ok(bytes.readUInt32BE(0))
      : err(
          new BinaryTargetError(
            path,
            "Mach-O header became truncated before Hopper loader selection",
          ),
        );
  } catch (cause: unknown) {
    return signalIsAborted(signal)
      ? err(new AnalysisCancelledError("open_binary"))
      : err(
          new BinaryTargetError(
            path,
            `Cannot read the Mach-O container header: ${cause instanceof Error ? cause.message : String(cause)}`,
            { cause },
          ),
        );
  } finally {
    signal?.removeEventListener("abort", onAbort);
  }
};

const sha256File = async (
  path: string,
  signal: AbortSignal | undefined,
): Promise<Result<string | undefined, AnalysisCancelledError>> => {
  if (signalIsAborted(signal))
    return err(new AnalysisCancelledError("open_binary"));
  const stream = createReadStream(path);
  const onAbort = (): void => {
    stream.destroy();
  };
  signal?.addEventListener("abort", onAbort, { once: true });
  try {
    const hash = createHash("sha256");
    for await (const chunk of stream) hash.update(chunk);
    return signalIsAborted(signal)
      ? err(new AnalysisCancelledError("open_binary"))
      : ok(hash.digest("hex"));
  } catch (cause: unknown) {
    // best-effort cleanup: unreadable targets mean no digest; abort still cancels.
    void cause;
    return signalIsAborted(signal)
      ? err(new AnalysisCancelledError("open_binary"))
      : ok(undefined);
  } finally {
    signal?.removeEventListener("abort", onAbort);
  }
};

const signalIsAborted = (signal: AbortSignal | undefined): boolean =>
  signal?.aborted === true;