Skip to content

armgit / rea

Public Imported from GitHub
0

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

11.7 KB
Raw Blame
import { KUNA_STRING_MIN_LENGTH } from "./KunaLimits.js";
import { accessSync, constants, statSync } from "node:fs";

import type {
  AnalysisClient,
  AnalysisProfileResolutionOptions,
  AnalysisProviderCandidate,
  ProviderAvailability,
  ProviderTargetSupport,
} from "../application/AnalysisProvider.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import {
  createAnalysisProfile,
  type AnalysisProfileCommitment,
} from "../domain/analysisProfile.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import { err, ok } from "../domain/result.js";
import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";
import {
  resolveRegexMatchingDeadline,
  type RegexMatchingDeadline,
} from "../config/regexMatchingDeadline.js";
import {
  resolveRegexWorkerHeapRequest,
  type RegexWorkerHeapRequest,
} from "../config/regexWorkerHeapRequest.js";
import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
import {
  kunaFileCleanupError,
  kunaRetainedResourceCleanupError,
  type KunaProcessLauncher,
} from "./KunaCommand.js";
import {
  readKunaConfiguration,
  type KunaConfiguration,
} from "./KunaConfiguration.js";
import {
  createKunaResourceScope,
  inspectKunaInstallation,
} from "./KunaInstallation.js";
import { KunaProjectCache } from "./KunaProjectCache.js";
import {
  KUNA_PROVIDER_IDENTITY,
  kunaCapabilities,
} from "./KunaProviderCapabilities.js";
import { KUNA_COMMAND_REMEDIATION, KUNA_PROVIDER_ID } from "./KunaRelease.js";
import { KunaRunSlots } from "./KunaRunSlots.js";
import { KunaSessionClient } from "./KunaSessionClient.js";
import { kunaUnavailable } from "./KunaUnavailable.js";

/** Architectures REA verified Kuna on: x86-64 and AArch64 ELF and Mach-O, plus ARM Thumb. */
const VERIFIED_ARCHITECTURES: ReadonlySet<string> = new Set([
  "x86_64",
  "arm64",
  "arm",
]);

/**
 * Bring-your-own Kuna candidate. Discovery reads configuration and the
 * executable's metadata only; the version probe runs when a target is opened.
 */
export class KunaProvider implements AnalysisProviderCandidate {
  readonly #environment: Readonly<NodeJS.ProcessEnv>;
  readonly #deadline: RegexMatchingDeadline;
  readonly #heapRequest: RegexWorkerHeapRequest;
  readonly #platform: NodeJS.Platform;
  readonly #launcher: KunaProcessLauncher | undefined;
  readonly #probeTimeoutMs: number | undefined;
  readonly #singleFunctionRuns: number | undefined;
  #cache: KunaProjectCache | undefined;
  #runSlots: KunaRunSlots | undefined;

  constructor(
    environment: Readonly<NodeJS.ProcessEnv>,
    options: {
      readonly platform?: NodeJS.Platform;
      readonly launcher?: KunaProcessLauncher;
      /** Test seam for bounded installation-probe lifecycle cases. */
      readonly probeTimeoutMs?: number;
      /** Test seam for foreground native runs; production derives it from the host. */
      readonly singleFunctionRuns?: number;
      /**
       * Deadline already resolved at startup. Omitted means resolve the
       * selected environment; an invalid setting is refused.
       */
      readonly regexMatchingDeadline?: RegexMatchingDeadline;
      /**
       * Heap request already resolved at startup. Omitted means resolve the
       * selected environment; an invalid setting is refused.
       */
      readonly regexWorkerHeapRequest?: RegexWorkerHeapRequest;
    } = {},
  ) {
    this.#platform = options.platform ?? process.platform;
    this.#environment = snapshotEnvironment(environment, this.#platform);
    this.#deadline =
      options.regexMatchingDeadline ??
      resolveRegexMatchingDeadline(this.#environment);
    this.#heapRequest =
      options.regexWorkerHeapRequest ??
      resolveRegexWorkerHeapRequest(this.#environment);
    this.#launcher = options.launcher;
    this.#probeTimeoutMs = options.probeTimeoutMs;
    this.#singleFunctionRuns = options.singleFunctionRuns;
  }

  identity() {
    return KUNA_PROVIDER_IDENTITY;
  }

  capabilities() {
    const availability = this.inspectAvailability();
    return kunaCapabilities(
      availability.status === "available"
        ? { available: true }
        : {
            available: false,
            reason: availability.reason,
            code: availability.code,
          },
      this.#deadline,
      this.#heapRequest,
    );
  }

  inspectAvailability(): ProviderAvailability {
    const configuration = readKunaConfiguration(
      this.#environment,
      this.#platform,
    );
    if (!configuration.ok)
      return {
        status: "unavailable",
        code: configuration.error.code,
        reason: configuration.error.reason,
        diagnostics: {
          configured: configuration.error.code !== "not_configured",
          version_probed: false,
        },
      };
    const { command } = configuration.value;
    try {
      accessSync(command, constants.X_OK);
      if (!statSync(command).isFile()) throw new Error("not a regular file");
    } catch (cause: unknown) {
      return {
        status: "unavailable",
        code: "executable_missing",
        reason: `Cannot execute REA_KUNA_COMMAND ${command}: ${cause instanceof Error ? cause.message : String(cause)}. ${KUNA_COMMAND_REMEDIATION}`,
        diagnostics: { configured: true, command, version_probed: false },
      };
    }
    return {
      status: "available",
      code: null,
      reason: null,
      diagnostics: {
        configured: true,
        command,
        cache_root: configuration.value.cacheRoot,
        jobs: configuration.value.jobs,
        version_probed: false,
      },
    };
  }

  inspectTargetSupport(target: BinaryTarget): ProviderTargetSupport {
    const diagnostics = {
      target_kind: target.kind,
      target_format: target.format,
    };
    if (target.kind !== "executable")
      return {
        status: "unsupported",
        code: "target_kind_unsupported",
        reason: "Kuna decompiles executable images, not databases or archives.",
        diagnostics,
      };
    if (target.format !== "elf" && target.format !== "mach-o")
      return {
        status: "unsupported",
        code: "target_format_unsupported",
        reason:
          target.format === "mach-o-universal"
            ? "REA's Kuna provider has no verified universal Mach-O slice selection yet; open a thin slice or use another provider."
            : `REA verified the Kuna provider on ELF and thin Mach-O images; ${target.format} is not admitted yet.`,
        diagnostics,
      };
    if (!VERIFIED_ARCHITECTURES.has(target.architecture))
      return {
        status: "unsupported",
        code: "architecture_unsupported",
        reason: `REA verified the Kuna provider on x86-64, AArch64 and ARM; ${target.architecture} is not admitted yet.`,
        diagnostics: { ...diagnostics, architecture: target.architecture },
      };
    return { status: "supported", code: null, reason: null, diagnostics };
  }

  async resolveAnalysisProfile(
    _target: BinaryTarget,
    options?: AnalysisProfileResolutionOptions,
  ) {
    if (options?.signal?.aborted === true)
      return err(
        new AnalysisCancelledError("kuna:profile", {
          cause: options.signal.reason,
        }),
      );
    let installation: Awaited<ReturnType<typeof inspectKunaInstallation>>;
    const resourceScope = options?.resourceScope;
    if (resourceScope === undefined)
      return err(
        kunaUnavailable(
          "kuna:profile",
          "Kuna profile inspection requires a durable resource scope",
        ),
      );
    const kunaResources = createKunaResourceScope(resourceScope);
    try {
      installation = await inspectKunaInstallation(this.#environment, {
        platform: this.#platform,
        ...(options?.signal === undefined ? {} : { signal: options.signal }),
        resourceScope: kunaResources.owner,
        ...(this.#launcher === undefined
          ? {}
          : { processLauncher: this.#launcher }),
        ...(this.#probeTimeoutMs === undefined
          ? {}
          : { probeTimeoutMs: this.#probeTimeoutMs }),
      });
    } catch (cause: unknown) {
      const retainedCleanup = kunaRetainedResourceCleanupError(
        cause,
        "kuna:profile",
      );
      if (retainedCleanup !== undefined) return err(retainedCleanup);
      if (!(cause instanceof RegularFileCleanupFailure)) {
        const cancellation = kunaResources.installationCancellationError(
          cause,
          "kuna:profile",
        );
        if (cancellation !== undefined) return err(cancellation);
      }
      if (!(cause instanceof RegularFileCleanupFailure)) throw cause;
      const error = kunaFileCleanupError(cause, "kuna:profile");
      kunaResources.bindFailure(cause, error);
      return err(error);
    }
    if (!installation.ok) {
      const error = kunaUnavailable("open_binary", installation.error.reason, {
        diagnostics: installation.error.diagnostics,
        ...(!kunaResources.hasPending
          ? {}
          : {
              cleanup: {
                reason: "Kuna version-probe process cleanup is unconfirmed.",
                resources: kunaResources.cleanupResources ?? [],
              },
            }),
      });
      kunaResources.bindRetainedFailure(error);
      return err(error);
    }
    const { value } = installation;
    return ok({
      profile: createAnalysisProfile(
        { ...KUNA_PROVIDER_IDENTITY, version: value.version },
        {
          kuna_version: value.version,
          kuna_sha256: value.sha256,
          verified_release: value.verified,
          jobs: value.configuration.jobs,
          export: "decompile-project",
          reference_graph: {
            command: "decompile-graph",
            schema_version: 4,
            bodies: false,
            edge_kind: "call",
          },
          xrefs: { command: "xrefs", direction: "to", exact_address: true },
          strings: {
            command: "strings",
            encoding: "all",
            min_length: KUNA_STRING_MIN_LENGTH,
            termination: "any",
            xrefs: false,
          },
          cache_policy: "live",
        },
      ),
    });
  }

  /** Shared cache cleanup belongs to the candidate, not a retired client. */
  closeOwnedResources() {
    return this.#cache?.close() ?? Promise.resolve(ok(null));
  }

  hasPendingOwnedResources(): boolean {
    return this.#cache?.hasPendingCleanup === true;
  }

  createClient(
    target: BinaryTarget,
    profile?: AnalysisProfileCommitment,
  ): AnalysisClient {
    const configuration = readKunaConfiguration(
      this.#environment,
      this.#platform,
    );
    if (!configuration.ok)
      return {
        execute: async (operation) =>
          err(kunaUnavailable(operation, configuration.error.reason)),
        close: async () => ok(null),
      };
    return new KunaSessionClient(target, profile, {
      cache: this.#projectCache(configuration.value),
      runSlots: this.#foregroundSlots(configuration.value),
      environment: this.#environment,
      deadline: this.#deadline,
      heapRequest: this.#heapRequest,
      ...(this.#launcher === undefined ? {} : { launcher: this.#launcher }),
    });
  }

  /** One cache per provider, so sessions of one server share exports in flight. */
  #projectCache(configuration: KunaConfiguration): KunaProjectCache {
    this.#cache ??= new KunaProjectCache(configuration.cacheRoot, {
      maxBytes: configuration.cacheMaxBytes,
      ...(this.#launcher === undefined ? {} : { launcher: this.#launcher }),
    });
    return this.#cache;
  }

  /** One admission pool per provider, so concurrent sessions share the host's cores. */
  #foregroundSlots(configuration: KunaConfiguration): KunaRunSlots {
    this.#runSlots ??=
      this.#singleFunctionRuns === undefined
        ? KunaRunSlots.forHost(configuration.jobs)
        : new KunaRunSlots(this.#singleFunctionRuns);
    return this.#runSlots;
  }
}