Skip to content

armgit / rea

Public Imported from GitHub
0

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

39.7 KB
Raw Blame
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import {
  probeGhidraJava,
  type GhidraJavaObservation,
  type GhidraJavaProbeFailure,
  type GhidraJavaProbeOptions,
} from "./GhidraJavaProbe.js";
import { ok, type Result } from "../domain/result.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { readGhidraExecutableHeader } from "./GhidraExecutableHeader.js";
import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
import {
  readGhidraInstallationProperties,
  type GhidraInstallationFileOptions,
} from "./GhidraInstallationProperties.js";
import { constants } from "node:fs";
import { accessSync, realpathSync, statSync } from "node:fs";
import { delimiter as pathDelimiter, dirname, posix, win32 } from "node:path";

import type { ProviderRejectionCode } from "../contracts/providerSelection.js";
import {
  parseExecutableHeader,
  readFatArchitectureFamilies,
  type ExecutableMetadata,
} from "../domain/binaryTarget.js";
import {
  isMachOFormat,
  type BinaryArchitecture,
} from "../domain/binaryTargetTypes.js";
import type { JsonValue } from "../domain/jsonValue.js";
import {
  ghidraApplicationProperties,
  ghidraJavaMajorAccepted,
  ghidraJavaRangeLabel,
  ghidraJavaRequirement,
  type GhidraApplicationProperties,
  type GhidraJavaRequirement,
} from "./GhidraInstallationPolicy.js";
import {
  ghidraReleaseAccepted,
  ghidraReleaseCompatibility,
  ghidraReleaseLine,
  ghidraVersionDetail,
  SUPPORTED_GHIDRA_VERSION,
} from "./GhidraReleasePolicy.js";

const NATIVE_PLATFORMS: Readonly<
  Partial<
    Record<
      NodeJS.Platform,
      Readonly<Partial<Record<NodeJS.Architecture, string>>>
    >
  >
> = {
  linux: { x64: "linux_x86_64", arm64: "linux_arm_64" },
  darwin: { x64: "mac_x86_64", arm64: "mac_arm_64" },
  win32: { x64: "win_x86_64" },
};

/** Executable format each supported host runs its own Ghidra native tools as. */
const NATIVE_TOOL_FORMATS: Readonly<
  Partial<Record<NodeJS.Platform, ExecutableMetadata["format"]>>
> = {
  linux: "elf",
  darwin: "mach-o",
  win32: "pe",
};

/** Node architecture identifiers as the executable-header parser reports them. */
const NATIVE_ARCHITECTURES: readonly {
  readonly node: NodeJS.Architecture;
  readonly binary: BinaryArchitecture;
}[] = [
  { node: "x64", binary: "x86_64" },
  { node: "ia32", binary: "x86" },
  { node: "arm", binary: "arm" },
  { node: "arm64", binary: "arm64" },
];

/** Compatibility of one present native decompiler with the inspected host. */
type NativeDecompilerCompatibility =
  | {
      readonly status: "incompatible";
      readonly detail: string;
      readonly remediation: string;
    }
  | { readonly status: "compatible"; readonly detail: string }
  | { readonly status: "unknown"; readonly detail: string };

/**
 * Judge a native decompiler by its own executable header instead of the
 * directory name that admits it.
 *
 * Only a header that positively contradicts the host is `incompatible`. An
 * absent, unreadable, truncated, or unrecognized header stays `unknown`, so a
 * file the other checks already accept is never refused on missing evidence.
 */
const assessNativeDecompiler = (
  path: string,
  platform: NodeJS.Platform,
  architecture: NodeJS.Architecture,
  probe: GhidraExecutableHeaderProbe | undefined,
): NativeDecompilerCompatibility => {
  const expectedFormat = NATIVE_TOOL_FORMATS[platform];
  const expectedArchitecture = NATIVE_ARCHITECTURES.find(
    ({ node }) => node === architecture,
  )?.binary;
  if (expectedFormat === undefined || expectedArchitecture === undefined)
    return {
      status: "unknown",
      detail: `${path} is executable, but no native tool format is defined for ${platform}/${architecture}`,
    };
  const parsed =
    probe === undefined
      ? undefined
      : parseExecutableHeader(probe.bytes, architecture, probe.size);
  // Slice selection can refuse a FAT table that still proves this host is
  // excluded, such as one declaring only arm64 and arm64e; its validated
  // families decide. A malformed host slice remains an unknown outcome.
  const families =
    probe !== undefined && parsed !== undefined && !parsed.ok
      ? readFatArchitectureFamilies(probe.bytes, probe.size)
      : null;
  const header = parsed?.ok
    ? parsed.value
    : families?.ok &&
        !families.value.some((family) => family === expectedArchitecture)
      ? {
          format: "mach-o-universal" as const,
          architecture: families.value.join("/") || "no supported architecture",
        }
      : undefined;
  if (header === undefined)
    return {
      status: "unknown",
      detail: `${path} is executable, but its executable format for ${platform}/${architecture} could not be established`,
    };
  const observed = `${header.format} ${header.architecture}`;
  const expected = `${expectedFormat} ${expectedArchitecture}`;
  const formatMatches = isMachOFormat(expectedFormat)
    ? isMachOFormat(header.format)
    : header.format === expectedFormat;
  if (formatMatches && header.architecture === expectedArchitecture)
    return {
      status: "compatible",
      detail: `${path} reports ${observed}, which matches ${platform}/${architecture}`,
    };
  const nativeDirectory = NATIVE_PLATFORMS[platform]?.[architecture];
  const executable = platform === "win32" ? "decompile.exe" : "decompile";
  return {
    status: "incompatible",
    detail: `${path} reports ${observed}, but ${platform}/${architecture} requires ${expected}`,
    remediation: `Provide an executable Ghidra/Features/Decompiler/os/${nativeDirectory ?? "<platform>"}/${executable} built for ${expected}, or its build/os equivalent. REA does not build or install native tools.`,
  };
};

/** Caller-owned paths and host coordinates used for one installation probe. */
export interface GhidraInstallationOptions {
  readonly environment: Readonly<NodeJS.ProcessEnv>;
  readonly resourceOwner: RetainedResourceScope;
  readonly signal?: AbortSignal;
  readonly installDir?: string;
  readonly javaHome?: string;
  readonly platform?: NodeJS.Platform;
  readonly architecture?: NodeJS.Architecture;
}

/** One independently actionable part of the supported-installation contract. */
export type GhidraInstallationCheck =
  | {
      readonly status: "passed";
      readonly name: GhidraInstallationCheckName;
      readonly detail: string;
    }
  | {
      readonly status: "failed";
      readonly name: GhidraInstallationCheckName;
      readonly code: ProviderRejectionCode;
      readonly detail: string;
      readonly remediation: string;
    };

/** Stable identity for one Ghidra installation check. */
export type GhidraInstallationCheckName =
  | "configuration"
  | "platform"
  | "architecture"
  | "installation"
  | "version"
  | "headless"
  | "native_decompiler"
  | "java";

interface GhidraInstallationObservation {
  readonly platform: NodeJS.Platform;
  readonly architecture: NodeJS.Architecture;
  readonly applicationPropertiesPath: string | null;
  /** Parsed release identity, never inferred from the installation directory name. */
  readonly configurationDirectoryName: string | null;
  readonly nativeDecompilerPath: string | null;
  readonly nativeDecompilerHeaderFailure?: AnalysisError;
  readonly javaCommand: string;
  readonly javaProbeFailure?: GhidraJavaProbeFailure;
  /** Observed java.vm.name; omitted when the probe cannot establish VM identity. */
  readonly javaVmName?: string;
  /**
   * Observed JVM os.arch; omitted when the probe cannot establish it. Ghidra
   * selects its native decompiler directory from this value.
   */
  readonly javaOsArch?: string;
  /**
   * Observed JVM os.name; omitted when the probe cannot establish it. Ghidra
   * selects its native decompiler OS directory from the JVM OS/architecture
   * pair, so a non-host value selects an unvalidated directory.
   */
  readonly javaOsName?: string;
  readonly checks: readonly GhidraInstallationCheck[];
}

/** Bounded observation of a supported BYO Ghidra installation and JDK. */
export interface AvailableGhidraInstallation extends GhidraInstallationObservation {
  readonly status: "available";
  readonly installDir: string;
  readonly analyzeHeadlessPath: string;
  readonly applicationPropertiesPath: string;
  readonly providerVersion: string;
  readonly javaHome: string;
  readonly javaVersion: string;
}

/** Bounded observation explaining why a BYO Ghidra installation is unusable. */
export interface UnavailableGhidraInstallation extends GhidraInstallationObservation {
  readonly status: "unavailable";
  readonly installDir: string | null;
  readonly analyzeHeadlessPath: string | null;
  readonly providerVersion: string | null;
  readonly javaHome: string | null;
  readonly javaVersion: string | null;
  readonly rejection: Readonly<{
    code: ProviderRejectionCode;
    reason: string;
  }>;
}

/** Parsed available or unavailable state of one BYO Ghidra installation. */
export type GhidraInstallationInspection =
  | AvailableGhidraInstallation
  | UnavailableGhidraInstallation;

/** A bounded executable-header probe: a small prefix plus the whole file size. */
export interface GhidraExecutableHeaderProbe {
  /** A bounded prefix; a larger or unreadable header remains unknown. */
  readonly bytes: Buffer;
  /** Whole-file size, since header commitments are checked against it, not the prefix. */
  readonly size: number;
}

/** Host observations and owned Java prerequisite work; never launches Ghidra. */
export interface GhidraInstallationHost {
  readonly platform?: NodeJS.Platform;
  readonly architecture?: NodeJS.Architecture;
  readText(
    path: string,
    options: GhidraInstallationFileOptions,
  ): string | undefined | Promise<string | undefined>;
  executable(path: string): boolean;
  /**
   * Read a bounded header prefix of one executable so admission can reject a
   * tool built for another platform or architecture. An omitted seam, or an
   * unreadable file, reports the header as unknown and never rejects an
   * installation that the other checks already accept. Cancellation and
   * incomplete descriptor cleanup propagate as failures.
   */
  executableHeader?(
    path: string,
    options: GhidraInstallationFileOptions,
  ):
    | Result<GhidraExecutableHeaderProbe | undefined, AnalysisError>
    | Promise<Result<GhidraExecutableHeaderProbe | undefined, AnalysisError>>;
  probeJava(
    command: string,
    environment: NodeJS.ProcessEnv,
    options: GhidraJavaProbeOptions,
  ):
    | Result<GhidraJavaObservation, GhidraJavaProbeFailure | AnalysisError>
    | Promise<
        Result<GhidraJavaObservation, GhidraJavaProbeFailure | AnalysisError>
      >;
  /** Resolve a PATH launcher to a validated installation without executing it. */
  discoverInstallDirOnPath?(
    environment: Readonly<NodeJS.ProcessEnv>,
    platform: NodeJS.Platform,
  ): string | undefined;
}

interface GhidraInstallationCoordinates {
  readonly installDir: string | null;
  readonly applicationPropertiesPath: string | null;
  readonly analyzeHeadlessPath: string | null;
  readonly nativeDecompilerPath: string | null;
  readonly nativeDecompilerHeader: Result<
    GhidraExecutableHeaderProbe | undefined,
    AnalysisError
  >;
  readonly properties: GhidraApplicationProperties | undefined;
  readonly javaCommand: string;
  readonly java: GhidraJavaObservation | undefined;
  readonly javaProbeFailure: GhidraJavaProbeFailure | undefined;
}

interface GhidraInstallationCheckContext {
  readonly coordinates: GhidraInstallationCoordinates;
  readonly platform: NodeJS.Platform;
  readonly architecture: NodeJS.Architecture;
  readonly javaHome: string | undefined;
  readonly host: GhidraInstallationHost;
}

/** Inspect an installation without importing a target or modifying Ghidra. */
export const inspectGhidraInstallation = async (
  options: GhidraInstallationOptions,
  host: GhidraInstallationHost = systemGhidraInstallationHost(),
): Promise<GhidraInstallationInspection> => {
  if (options.signal?.aborted)
    throw new AnalysisCancelledError("ghidra:installation", {
      cause: options.signal.reason,
    });
  const platform = options.platform ?? process.platform;
  const architecture = options.architecture ?? process.arch;
  const coordinates = await installationCoordinates(
    options,
    platform,
    architecture,
    host,
  );
  const checks = installationChecks({
    coordinates,
    platform,
    architecture,
    javaHome: options.javaHome,
    host,
  });
  const failed = checks.find(
    (check): check is Extract<GhidraInstallationCheck, { status: "failed" }> =>
      check.status === "failed",
  );
  const javaObservation =
    coordinates.java ?? coordinates.javaProbeFailure?.properties;
  const observation = {
    platform,
    architecture,
    applicationPropertiesPath: coordinates.applicationPropertiesPath,
    configurationDirectoryName:
      coordinates.properties?.configurationDirectoryName ?? null,
    nativeDecompilerPath: coordinates.nativeDecompilerPath,
    ...(coordinates.nativeDecompilerHeader.ok
      ? {}
      : {
          nativeDecompilerHeaderFailure:
            coordinates.nativeDecompilerHeader.error,
        }),
    javaCommand: coordinates.javaCommand,
    ...(coordinates.javaProbeFailure === undefined
      ? {}
      : { javaProbeFailure: coordinates.javaProbeFailure }),
    ...(javaObservation?.vmName == null
      ? {}
      : { javaVmName: javaObservation.vmName }),
    ...(javaObservation?.osArch == null
      ? {}
      : { javaOsArch: javaObservation.osArch }),
    ...(javaObservation?.osName == null
      ? {}
      : { javaOsName: javaObservation.osName }),
    checks,
  };
  if (failed !== undefined)
    return {
      status: "unavailable",
      ...observation,
      installDir: coordinates.installDir,
      analyzeHeadlessPath: coordinates.analyzeHeadlessPath,
      providerVersion: coordinates.properties?.providerVersion ?? null,
      javaHome: javaObservation?.home ?? options.javaHome ?? null,
      javaVersion: javaObservation?.version ?? null,
      rejection: { code: failed.code, reason: failed.remediation },
    };
  if (options.signal?.aborted)
    throw new AnalysisCancelledError("ghidra:installation", {
      cause: options.signal.reason,
      diagnostics: ghidraInstallationDiagnostics(
        availableInstallation(coordinates, observation),
      ),
    });
  return availableInstallation(coordinates, observation);
};

const availableInstallation = (
  coordinates: GhidraInstallationCoordinates,
  observation: GhidraInstallationObservation,
): AvailableGhidraInstallation => {
  const providerVersion = coordinates.properties?.providerVersion;
  if (
    coordinates.installDir === null ||
    coordinates.applicationPropertiesPath === null ||
    coordinates.analyzeHeadlessPath === null ||
    providerVersion === null ||
    providerVersion === undefined ||
    coordinates.java === undefined
  )
    throw new TypeError(
      "Passing Ghidra installation checks produced incomplete coordinates",
    );
  return {
    status: "available",
    ...observation,
    installDir: coordinates.installDir,
    analyzeHeadlessPath: coordinates.analyzeHeadlessPath,
    applicationPropertiesPath: coordinates.applicationPropertiesPath,
    providerVersion,
    javaHome: coordinates.java.home,
    javaVersion: coordinates.java.version,
  };
};

const installationCoordinates = async (
  options: GhidraInstallationOptions,
  platform: NodeJS.Platform,
  architecture: NodeJS.Architecture,
  host: GhidraInstallationHost,
): Promise<GhidraInstallationCoordinates> => {
  const path = platform === "win32" ? win32 : posix;
  // An explicit setting remains authoritative even when malformed or stale;
  // automatic discovery is only a fallback when the caller supplied none.
  const installDir =
    options.installDir ??
    host.discoverInstallDirOnPath?.(options.environment, platform) ??
    null;
  const applicationPropertiesPath =
    installDir === null
      ? null
      : path.join(installDir, "Ghidra", "application.properties");
  const analyzeHeadlessPath =
    installDir === null
      ? null
      : path.join(
          installDir,
          "support",
          platform === "win32" ? "analyzeHeadless.bat" : "analyzeHeadless",
        );
  const decompilerPlatform = NATIVE_PLATFORMS[platform]?.[architecture];
  const decompilerExecutable =
    platform === "win32" ? "decompile.exe" : "decompile";
  const nativeDecompilerPath =
    installDir === null || decompilerPlatform === undefined
      ? null
      : ([
          path.join(
            installDir,
            "Ghidra",
            "Features",
            "Decompiler",
            "os",
            decompilerPlatform,
            decompilerExecutable,
          ),
          path.join(
            installDir,
            "Ghidra",
            "Features",
            "Decompiler",
            "build",
            "os",
            decompilerPlatform,
            decompilerExecutable,
          ),
        ].find((candidate) => host.executable(candidate)) ?? null);
  const properties =
    applicationPropertiesPath === null
      ? undefined
      : await host.readText(applicationPropertiesPath, {
          resourceOwner: options.resourceOwner,
          ...(options.signal === undefined ? {} : { signal: options.signal }),
        });
  const nativeDecompilerHeader =
    nativeDecompilerPath === null || host.executableHeader === undefined
      ? ok(undefined)
      : await host.executableHeader(nativeDecompilerPath, {
          resourceOwner: options.resourceOwner,
          ...(options.signal === undefined ? {} : { signal: options.signal }),
        });
  if (
    !nativeDecompilerHeader.ok &&
    (nativeDecompilerHeader.error instanceof AnalysisCancelledError ||
      nativeDecompilerHeader.error.cleanupIncomplete)
  )
    throw nativeDecompilerHeader.error;
  const javaCommand = (() => {
    if (options.javaHome !== undefined)
      return path.join(
        options.javaHome,
        "bin",
        platform === "win32" ? "java.exe" : "java",
      );
    if (platform !== "darwin")
      return platform === "win32" ? "java.exe" : "java";
    // Check the caller's PATH, never a file named java in the working directory.
    const javaOnPath = options.environment.PATH?.split(":").some(
      (directory) =>
        path.isAbsolute(directory) &&
        host.executable(path.join(directory, "java")),
    );
    if (javaOnPath) return "java";
    // Prefer the Homebrew prefix matching the process architecture.
    const prefixes =
      architecture === "arm64"
        ? ["/opt/homebrew", "/usr/local"]
        : ["/usr/local", "/opt/homebrew"];
    return (
      prefixes
        .map((prefix) =>
          path.join(
            prefix,
            "opt/openjdk/libexec/openjdk.jdk/Contents/Home/bin/java",
          ),
        )
        .find((candidate) => host.executable(candidate)) ?? "java"
    );
  })();
  // Java is a prerequisite of a selected installation. Without one, or with a
  // relative JAVA_HOME, configuration validation refuses Ghidra before Java can
  // matter, so callers such as setup and doctor must not execute a host JVM.
  const javaProbe =
    installDir !== null &&
    (options.javaHome === undefined || path.isAbsolute(options.javaHome))
      ? await host.probeJava(
          javaCommand,
          ghidraJavaEnvironment(
            options.javaHome,
            options.environment,
            platform,
          ),
          {
            resourceOwner: options.resourceOwner,
            ...(options.signal === undefined ? {} : { signal: options.signal }),
          },
        )
      : undefined;
  if (
    javaProbe !== undefined &&
    !javaProbe.ok &&
    javaProbe.error instanceof AnalysisError
  )
    throw javaProbe.error;
  return {
    installDir,
    applicationPropertiesPath,
    analyzeHeadlessPath,
    nativeDecompilerPath,
    nativeDecompilerHeader,
    properties:
      properties === undefined
        ? undefined
        : ghidraApplicationProperties(properties),
    javaCommand,
    java: javaProbe?.ok === true ? javaProbe.value : undefined,
    javaProbeFailure:
      javaProbe !== undefined &&
      !javaProbe.ok &&
      !(javaProbe.error instanceof AnalysisError)
        ? javaProbe.error
        : undefined,
  };
};

const installationChecks = ({
  coordinates,
  platform,
  architecture,
  javaHome,
  host,
}: GhidraInstallationCheckContext): readonly GhidraInstallationCheck[] => [
  configurationCheck(coordinates.installDir, javaHome, platform),
  installationCheck({
    name: "platform",
    passed: NATIVE_PLATFORMS[platform] !== undefined,
    code: "unsupported_host",
    detail: platform,
    remediation:
      "Use Linux or macOS x64/arm64, or Windows x64 with matching native Ghidra tools.",
  }),
  installationCheck({
    name: "architecture",
    passed: NATIVE_PLATFORMS[platform]?.[architecture] !== undefined,
    code: "unsupported_host",
    detail: architecture,
    remediation: "Use x64/arm64 on Linux or macOS, or x64 on Windows.",
  }),
  installationCheck({
    name: "installation",
    passed: coordinates.properties !== undefined,
    code: "executable_missing",
    detail:
      coordinates.applicationPropertiesPath ??
      "Ghidra application properties unavailable",
    remediation:
      "Point GHIDRA_INSTALL_DIR at the root of an extracted official Ghidra release.",
  }),
  versionCheck(coordinates.properties),
  installationCheck({
    name: "headless",
    passed:
      coordinates.analyzeHeadlessPath !== null &&
      host.executable(coordinates.analyzeHeadlessPath),
    code: "executable_missing",
    detail: coordinates.analyzeHeadlessPath ?? "analyzeHeadless unavailable",
    remediation:
      "Restore support/analyzeHeadless or support/analyzeHeadless.bat from the official Ghidra release.",
  }),
  nativeDecompilerCheck({ coordinates, platform, architecture }),
  javaCheck(
    coordinates.java,
    coordinates.javaCommand,
    javaHome,
    coordinates.properties,
    platform,
    coordinates.javaProbeFailure,
  ),
];

/**
 * REA's configuration parser, and so the MCP server and analysis, accept only
 * absolute paths; a relative one that happens to resolve here must not pass.
 */
const configurationCheck = (
  installDir: string | null,
  javaHome: string | undefined,
  platform: NodeJS.Platform,
): GhidraInstallationCheck => {
  const { isAbsolute } = platform === "win32" ? win32 : posix;
  const relative = [
    ...(installDir !== null && !isAbsolute(installDir)
      ? ["GHIDRA_INSTALL_DIR"]
      : []),
    ...(javaHome !== undefined && !isAbsolute(javaHome) ? ["JAVA_HOME"] : []),
  ];
  if (installDir === null || relative.length === 0)
    return installationCheck({
      name: "configuration",
      passed: installDir !== null,
      code: "not_configured",
      detail: installDir ?? "GHIDRA_INSTALL_DIR is not set",
      remediation: `Set GHIDRA_INSTALL_DIR to an extracted Ghidra ${ghidraReleaseLine()} release directory.`,
    });
  const settings = relative.join(" and ");
  return installationCheck({
    name: "configuration",
    passed: false,
    code: "not_configured",
    detail: `${settings} must be absolute`,
    remediation: `Set ${settings} to ${relative.length === 1 ? "an absolute path" : "absolute paths"}. REA's analysis and MCP server reject relative paths even when they resolve from the current directory.`,
  });
};

/** Project an installation probe into caller-visible, bounded diagnostics. */
export const ghidraInstallationDiagnostics = (
  inspection: GhidraInstallationInspection,
): Readonly<Record<string, JsonValue>> => ({
  install_dir: inspection.installDir,
  analyze_headless_path: inspection.analyzeHeadlessPath,
  native_decompiler_path: inspection.nativeDecompilerPath,
  ...(inspection.nativeDecompilerHeaderFailure === undefined
    ? {}
    : {
        native_decompiler_header_failure: projectAnalysisError(
          inspection.nativeDecompilerHeaderFailure,
        ),
      }),
  application_properties_path: inspection.applicationPropertiesPath,
  provider_version: inspection.providerVersion,
  java_command: inspection.javaCommand,
  ...(inspection.javaProbeFailure === undefined
    ? {}
    : {
        java_probe_failure: {
          code: inspection.javaProbeFailure.code,
          ...(inspection.javaProbeFailure.processErrorCode === undefined
            ? {}
            : {
                process_error_code:
                  inspection.javaProbeFailure.processErrorCode,
              }),
          detail: inspection.javaProbeFailure.detail,
          ...(inspection.javaProbeFailure.cancellation === undefined
            ? {}
            : { cancellation_observed: true }),
          ...(inspection.javaProbeFailure.properties === undefined
            ? {}
            : { properties: { ...inspection.javaProbeFailure.properties } }),
          ...(inspection.javaProbeFailure.output === undefined
            ? {}
            : { output: { ...inspection.javaProbeFailure.output } }),
        },
      }),
  java_home: inspection.javaHome,
  java_version: inspection.javaVersion,
  java_vm_name: inspection.javaVmName ?? null,
  java_os_arch: inspection.javaOsArch ?? null,
  java_os_name: inspection.javaOsName ?? null,
  platform: inspection.platform,
  architecture: inspection.architecture,
  checks: inspection.checks.map((check) => ({
    name: check.name,
    ok: check.status === "passed",
    code: check.status === "failed" ? check.code : null,
    detail: check.detail,
  })),
});

/** Environment that makes an explicitly selected JDK win over PATH discovery. */
export const ghidraJavaEnvironment = (
  javaHome: string | undefined,
  environment: Readonly<NodeJS.ProcessEnv>,
  platform: NodeJS.Platform = process.platform,
): NodeJS.ProcessEnv => {
  const selectedEnvironment = snapshotEnvironment(environment, platform);
  const boundedEnvironment = {
    ...selectedEnvironment,
    _JAVA_OPTIONS: "",
    JAVA_TOOL_OPTIONS: "",
    JDK_JAVA_OPTIONS: "",
    GHIDRA_JAVA_OPTIONS: "",
  };
  return javaHome === undefined
    ? boundedEnvironment
    : {
        ...boundedEnvironment,
        JAVA_HOME: javaHome,
        PATH: `${(platform === "win32" ? win32 : posix).join(
          javaHome,
          "bin",
        )}${platform === "win32" ? win32.delimiter : posix.delimiter}${selectedEnvironment.PATH ?? ""}`,
      };
};

const installationCheck = (options: {
  readonly name: GhidraInstallationCheckName;
  readonly passed: boolean;
  readonly detail: string;
  readonly code: ProviderRejectionCode;
  readonly remediation: string;
}): GhidraInstallationCheck =>
  options.passed
    ? {
        status: "passed",
        name: options.name,
        detail: options.detail,
      }
    : {
        status: "failed",
        name: options.name,
        code: options.code,
        detail: options.detail,
        remediation: options.remediation,
      };

/** Require a present native decompiler without positively incompatible bytes. */
const nativeDecompilerCheck = ({
  coordinates,
  platform,
  architecture,
}: Pick<
  GhidraInstallationCheckContext,
  "coordinates" | "platform" | "architecture"
>): GhidraInstallationCheck => {
  const path = coordinates.nativeDecompilerPath;
  const compatibility =
    path === null
      ? undefined
      : !coordinates.nativeDecompilerHeader.ok
        ? {
            status: "unknown" as const,
            detail: `${path} header is unknown: ${coordinates.nativeDecompilerHeader.error.message}`,
          }
        : assessNativeDecompiler(
            path,
            platform,
            architecture,
            coordinates.nativeDecompilerHeader.value,
          );
  // Ghidra resolves its native decompiler directory from the JVM's os.arch,
  // not the host process architecture. A JDK running under emulation (for
  // example x86_64 under Rosetta on Apple silicon) selects a directory that
  // was never validated, so every analysis fails after a passing doctor.
  // Ghidra resolves the OS directory from the JVM os.name/os.arch pair, so a
  // JVM reporting a non-host os.name (for example through -Dos.name=Windows)
  // selects a different OS directory even when os.arch matches.
  const osArch =
    coordinates.java?.osArch ??
    coordinates.javaProbeFailure?.properties?.osArch ??
    undefined;
  const osName =
    coordinates.java?.osName ??
    coordinates.javaProbeFailure?.properties?.osName ??
    undefined;
  const selectedDirectory = jvmOsArchNativeDirectory(platform, osArch);
  const validatedDirectory = NATIVE_PLATFORMS[platform]?.[architecture];
  // Without a JVM observation the java check reports the missing runtime;
  // the decompiler directory cannot be selected, so this check defers to it.
  if (coordinates.java !== undefined) {
    if (selectedDirectory === undefined)
      return installationCheck({
        name: "native_decompiler",
        passed: false,
        code: "executable_missing",
        detail:
          osArch === undefined
            ? "The Java probe did not report os.arch; the JVM-selected native decompiler directory is unknown and cannot be matched to the validated host directory"
            : `JVM reports unrecognized os.arch=${osArch}; its selected native decompiler directory is unknown and cannot be matched to the validated host directory`,
        remediation: `Point JAVA_HOME at a JDK whose reported architecture maps to the validated Ghidra decompiler (${validatedDirectory ?? "unsupported host"}). REA does not build or install native tools.`,
      });
    if (
      validatedDirectory !== undefined &&
      selectedDirectory !== validatedDirectory &&
      path !== null
    )
      return installationCheck({
        name: "native_decompiler",
        passed: false,
        code: "executable_missing",
        detail: `JVM reports os.arch=${osArch}, so Ghidra selects its native decompiler from os/${selectedDirectory}, but the validated decompiler targets ${validatedDirectory} (host ${platform}/${architecture})`,
        remediation: `Point JAVA_HOME at a JDK whose architecture matches the built decompiler (${validatedDirectory}). REA does not build or install native tools.`,
      });
    if (osName === undefined)
      return installationCheck({
        name: "native_decompiler",
        passed: false,
        code: "executable_missing",
        detail:
          "The Java probe did not report os.name; the JVM-selected native decompiler OS directory is unknown and cannot be matched to the validated host platform",
        remediation: `Point JAVA_HOME at a JDK whose reported operating system matches the host platform (${platform}). REA does not build or install native tools.`,
      });
    if (!jvmOsNameMatchesPlatform(platform, osName) && path !== null)
      return installationCheck({
        name: "native_decompiler",
        passed: false,
        code: "executable_missing",
        detail: `JVM reports os.name=${osName}, which does not match the validated host platform ${platform} (host ${platform}/${architecture})`,
        remediation: `Point JAVA_HOME at a JDK whose reported operating system matches the host platform (${platform}). REA does not build or install native tools.`,
      });
  }
  return installationCheck({
    name: "native_decompiler",
    passed: path !== null && compatibility?.status !== "incompatible",
    code: "executable_missing",
    detail:
      compatibility?.detail ??
      `Matching native decompiler for ${platform}/${architecture} was not found`,
    remediation:
      compatibility?.status === "incompatible"
        ? compatibility.remediation
        : `Provide an executable Ghidra/Features/Decompiler/os/${NATIVE_PLATFORMS[platform]?.[architecture] ?? "<platform>"}/${platform === "win32" ? "decompile.exe" : "decompile"}, or its build/os equivalent. REA does not build or install native tools.`,
  });
};

/**
 * Whether a JVM os.name value selects the host platform's native OS directory.
 * Unknown values never align with the validated host directory; admission
 * must not treat them as matching.
 */
const jvmOsNameMatchesPlatform = (
  platform: NodeJS.Platform,
  osName: string,
): boolean => {
  const normalized = osName.toLowerCase();
  if (platform === "win32") return normalized.startsWith("windows");
  if (platform === "darwin")
    return normalized.startsWith("mac") || normalized.startsWith("darwin");
  if (platform === "linux") return normalized.startsWith("linux");
  return false;
};

/**
 * Map a JVM os.arch value to the Ghidra native directory that JVM selects.
 * Unknown values stay unknown; admission must not treat them as aligned with
 * the validated host directory.
 */
const jvmOsArchNativeDirectory = (
  platform: NodeJS.Platform,
  osArch: string | undefined,
): string | undefined => {
  if (osArch === undefined) return undefined;
  const normalized = osArch.toLowerCase();
  const node: NodeJS.Architecture | undefined =
    normalized === "x86_64" || normalized === "amd64" || normalized === "x64"
      ? "x64"
      : normalized === "aarch64" || normalized === "arm64"
        ? "arm64"
        : undefined;
  return node === undefined ? undefined : NATIVE_PLATFORMS[platform]?.[node];
};

const versionCheck = (
  properties: GhidraApplicationProperties | undefined,
): GhidraInstallationCheck => {
  const raw = properties?.providerVersion;
  const parseError = properties?.parseError;
  return installationCheck({
    name: "version",
    passed: parseError == null && ghidraReleaseAccepted(raw),
    code:
      parseError != null
        ? "version_unresolved"
        : ghidraReleaseCompatibility(raw).status === "unsupported"
          ? "unsupported_version"
          : "version_unresolved",
    detail:
      parseError == null
        ? ghidraVersionDetail(raw)
        : `application.properties could not be parsed: ${parseError}`,
    remediation: `Install a Ghidra ${ghidraReleaseLine()} release (verified with ${SUPPORTED_GHIDRA_VERSION}), or update REA for another Ghidra line.`,
  });
};

const javaCheck = (
  observation: GhidraJavaObservation | undefined,
  command: string,
  configuredHome: string | undefined,
  properties: GhidraApplicationProperties | undefined,
  platform: NodeJS.Platform,
  failure: GhidraJavaProbeFailure | undefined,
): GhidraInstallationCheck => {
  const requirement = ghidraJavaRequirement(properties);
  const range = ghidraJavaRangeLabel(requirement);
  const supported =
    observation !== undefined &&
    ghidraJavaMajorAccepted(observation.major, requirement) &&
    observation.bits === 64 &&
    observation.runtime === "jdk";
  const bitness =
    observation === undefined
      ? undefined
      : observation.bits === null
        ? `bitness unknown${observation.unparsedBits === undefined ? "" : ` (sun.arch.data.model = ${JSON.stringify(observation.unparsedBits)})`}`
        : `${String(observation.bits)}-bit`;
  const knownMismatch =
    observation !== undefined &&
    (!ghidraJavaMajorAccepted(observation.major, requirement) ||
      (observation.bits !== null && observation.bits !== 64) ||
      observation.runtime !== "jdk");
  const detail =
    observation === undefined
      ? requirement.unresolved === null
        ? (failure?.detail ?? `${command}: Java probe was not attempted`)
        : `${failure?.detail ?? command}; ${requirement.unresolved}`
      : `${observation.version}; ${bitness}; ${observation.runtime === "jdk" ? "JDK" : "runtime only"}; ${observation.home}; accepted ${range}`;
  return installationCheck({
    name: "java",
    passed: supported,
    code:
      requirement.unresolved !== null
        ? "version_unresolved"
        : observation === undefined
          ? (failure?.code ?? "version_unresolved")
          : knownMismatch
            ? "unsupported_version"
            : "version_unresolved",
    detail,
    remediation: javaRemediation(requirement, configuredHome, range, platform),
  });
};

const javaRemediation = (
  requirement: GhidraJavaRequirement,
  configuredHome: string | undefined,
  range: string,
  platform: NodeJS.Platform,
): string => {
  if (requirement.unresolved !== null)
    return `The Ghidra installation's Java bounds could not be read (${requirement.unresolved}). Install a 64-bit full JDK inside the declared application.java.min and application.java.max.`;
  return configuredHome === undefined
    ? `Select ${range} on PATH, or set JAVA_HOME to its installation root before starting REA.${platform === "darwin" ? " Homebrew OpenJDK can be keg-only: set JAVA_HOME to the selected formula's libexec/openjdk.jdk/Contents/Home (for example /opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home or /usr/local/opt/openjdk/libexec/openjdk.jdk/Contents/Home). The installed JDK must satisfy the declared Ghidra Java bounds." : ""}`
    : `Update JAVA_HOME to the root of ${range} installation.`;
};

export const systemGhidraInstallationHost = (): GhidraInstallationHost => ({
  readText: readGhidraInstallationProperties,
  executableHeader: readGhidraExecutableHeader,
  executable(path) {
    try {
      accessSync(path, constants.X_OK);
      return statSync(path).isFile();
    } catch (cause: unknown) {
      // best-effort cleanup: optional executable probing; failure means missing.
      void cause;
      return false;
    }
  },
  probeJava: probeGhidraJava,
  discoverInstallDirOnPath: discoverGhidraInstallationOnPath,
});

/** Find a PATH launcher whose real target is inside a complete Ghidra tree. */
export const discoverGhidraInstallationOnPath = (
  environment: Readonly<NodeJS.ProcessEnv>,
  platform: NodeJS.Platform,
): string | undefined => {
  if (platform !== process.platform) return undefined;
  const path = platform === "win32" ? win32 : posix;
  const pathValue = environment.PATH;
  if (pathValue === undefined || pathValue.length === 0) return undefined;
  const launchers =
    platform === "win32"
      ? ["ghidra.bat", "ghidraRun.bat", "ghidra.exe", "ghidraRun.exe"]
      : ["ghidra", "ghidraRun"];
  for (const directory of pathValue.split(pathDelimiter)) {
    if (directory.length === 0) continue;
    for (const launcher of launchers) {
      let resolved: string;
      try {
        const candidate = path.resolve(directory, launcher);
        if (!executablePath(candidate)) continue;
        resolved = realpathSync(candidate);
      } catch (cause: unknown) {
        void cause;
        continue;
      }
      const root = dirname(resolved);
      const properties = path.join(root, "Ghidra", "application.properties");
      const headless = path.join(
        root,
        "support",
        platform === "win32" ? "analyzeHeadless.bat" : "analyzeHeadless",
      );
      try {
        if (statSync(properties).isFile() && executablePath(headless))
          return stableGhidraInstallationRoot(root, platform);
      } catch (cause: unknown) {
        void cause;
      }
    }
  }
  return undefined;
};

/**
 * Keep a Homebrew Ghidra registration stable across keg upgrades when its
 * `opt` alias resolves to this exact, already validated installation.
 */
const stableGhidraInstallationRoot = (
  root: string,
  platform: NodeJS.Platform,
): string => {
  if (platform !== "darwin") return root;
  const parsed = posix.parse(root);
  const segments = root.slice(parsed.root.length).split(posix.sep);
  const cellarIndex = segments.length - 4;
  const formula = segments[cellarIndex + 1];
  const version = segments[cellarIndex + 2];
  if (
    cellarIndex < 0 ||
    segments[cellarIndex] !== "Cellar" ||
    formula === undefined ||
    formula.length === 0 ||
    version === undefined ||
    version.length === 0 ||
    segments[cellarIndex + 3] !== "libexec"
  )
    return root;

  const prefix = posix.join(parsed.root, ...segments.slice(0, cellarIndex));
  const candidate = posix.join(prefix, "opt", formula, "libexec");
  try {
    return realpathSync(candidate) === root ? candidate : root;
  } catch (cause: unknown) {
    // An absent or unresolved alias cannot establish a stable installation identity.
    void cause;
    return root;
  }
};

const executablePath = (path: string): boolean => {
  try {
    accessSync(path, constants.X_OK);
    return statSync(path).isFile();
  } catch (cause: unknown) {
    // best-effort cleanup: optional executable probing; failure means missing.
    void cause;
    return false;
  }
};