Skip to content

armgit / rea

Public Imported from GitHub
0

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

19.1 KB
Raw Blame
import { randomUUID, createHash } from "node:crypto";
import { access, realpath, writeFile } from "node:fs/promises";
import { constants } from "node:fs";
import { isAbsolute, join } from "node:path";
import type { ExecutionOptions } from "../application/AnalysisProvider.js";
import { createAnalysisExecution } from "../application/AnalysisProvider.js";
import type {
  WasmArtifactExecution,
  WasmArtifactPort,
} from "../application/wasm/WasmArtifactPort.js";
import { readStableArtifact } from "../artifacts/readStableArtifact.js";
import {
  ArtifactResourceScope,
  ArtifactResourceRetryFailure,
} from "../artifacts/ArtifactResourceScope.js";
import { AnalysisCleanupLeaseGroup } from "../artifacts/AnalysisCleanupLease.js";
import { bindArtifactFileCleanup } from "../artifacts/ArtifactFileOperation.js";
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import type {
  AnalysisError,
  AnalysisCapturedOutput,
} from "../domain/analysisErrorBase.js";
import {
  AnalysisCancelledError,
  AnalysisArtifactChangedError,
  AnalysisCapabilityUnavailableError,
  AnalysisInputError,
  AnalysisOutputError,
} from "../domain/analysisErrorCore.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { createEvidence } from "../domain/evidence.js";
import { createAnalysisExecutionEvidence } from "../domain/analysisObservation.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import {
  wasmArtifactSchema,
  DEFAULT_WASM_COMMAND_TIMEOUT_MS,
  type InspectWasmArtifactInput,
} from "../domain/wasm/wasmArtifact.js";
import { err, ok, type Result } from "../domain/result.js";
import { runOwnedCommand } from "../process/OwnedCommand.js";
import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
import { WabtRuntime } from "./WabtRuntime.js";
import {
  WABT_PROVIDER_IDENTITY,
  WABT_LIMITS,
  WABT_VERSION,
} from "./WabtRelease.js";
import {
  wabtFailure,
  wabtConfigurationRecoveryAction,
  type WabtVersionProbe,
} from "./WabtFailures.js";
import { parseWabtOutput } from "./WabtOutput.js";
import { parseWabtWat } from "./WabtWat.js";
import { associateWasmGlue } from "./WasmGlueAdapter.js";

type Launcher = NonNullable<Parameters<typeof runOwnedCommand>[2]>["launcher"];
const OPERATION = "inspect_wasm_artifact";
const digest = (text: string) =>
  createHash("sha256").update(text).digest("hex");
/** Run caller-supplied WABT against private copies of exactly selected bytes. */
export class WabtArtifactProvider implements WasmArtifactPort {
  readonly #resources = new ArtifactResourceScope();
  constructor(
    readonly environment: Readonly<NodeJS.ProcessEnv> = process.env,
    readonly launcher?: Launcher,
    readonly createRuntime: () => Promise<
      Pick<PrivateRuntimeRoot, "path" | "close">
    > = () => PrivateRuntimeRoot.create({ prefix: "rea-wabt-" }),
  ) {}
  /** Retry retained cleanup without discarding roots that still cannot be removed. */
  async close(): Promise<void> {
    try {
      await this.#resources.close();
    } catch (cause: unknown) {
      throw resourceCleanupFailure(cause);
    }
  }
  async inspect(
    input: InspectWasmArtifactInput,
    options?: ExecutionOptions,
  ): Promise<Result<WasmArtifactExecution, AnalysisError>> {
    try {
      return await this.#resources.run(() => this.#inspect(input, options));
    } catch (cause: unknown) {
      if (cause instanceof ArtifactResourceRetryFailure)
        return err(resourceCleanupFailure(cause));
      if (
        cause instanceof ArtifactReaderFailure &&
        cause.reason === "unavailable" &&
        cause.cleanup === undefined
      )
        return err(this.#closedError());
      return err(wabtFailure(cause, "artifact", input.path));
    }
  }

  #closedError(): AnalysisCapabilityUnavailableError {
    return new AnalysisCapabilityUnavailableError(
      WABT_PROVIDER_IDENTITY.id,
      OPERATION,
      "Provider is closing",
    );
  }

  async #inspect(
    input: InspectWasmArtifactInput,
    options?: ExecutionOptions,
  ): Promise<Result<WasmArtifactExecution, AnalysisError>> {
    let runtime: WabtRuntime | undefined;
    let phase: "configuration" | "artifact" | "producer" = "configuration";
    let result: Result<WasmArtifactExecution, AnalysisError>;
    let capturedOutput: AnalysisCapturedOutput | undefined;
    let versionProbe: WabtVersionProbe | undefined;
    const commandTimeoutMs =
      input.command_timeout_ms ?? DEFAULT_WASM_COMMAND_TIMEOUT_MS;
    try {
      if (options?.signal?.aborted) throw new AnalysisCancelledError(OPERATION);
      const directory = this.environment.REA_WABT_BIN_DIRECTORY ?? "";
      if (!isAbsolute(directory))
        throw new Error(
          "REA_WABT_BIN_DIRECTORY must be an absolute tool directory.",
        );
      const commands: {
        tool: string;
        path: string;
        sha256: string;
        version_banner: string;
        arguments: string[];
      }[] = [];
      for (const tool of ["wasm-validate", "wasm-objdump", "wasm2wat"]) {
        const path = await realpath(
          join(
            directory,
            `${tool}${process.platform === "win32" ? ".exe" : ""}`,
          ),
        );
        await access(path, constants.X_OK);
        const binary = await readStableArtifact(
          path,
          WABT_LIMITS.toolBytes,
          options?.signal,
          undefined,
          this.#resources,
        );
        commands.push({
          tool,
          path,
          sha256: binary.sha256,
          version_banner: "",
          arguments:
            tool === "wasm-objdump"
              ? ["-h", "-x", "module.wasm"]
              : ["--enable-all", "module.wasm"],
        });
      }
      const root = await this.createRuntime();
      runtime = new WabtRuntime(root);
      const snapshotPath = join(root.path, "module.wasm");
      let snapshotHash: string | undefined;
      const verifySnapshot = async () => {
        if (snapshotHash === undefined) return;
        const bytes = await readStableArtifact(
          snapshotPath,
          WABT_LIMITS.inputBytes,
          options?.signal,
          undefined,
          this.#resources,
        );
        if (bytes.sha256 !== snapshotHash)
          throw new AnalysisArtifactChangedError(
            OPERATION,
            input.path,
            "Private WASM snapshot bytes changed.",
          );
      };
      const execute = async (
        command: (typeof commands)[number],
        args: readonly string[],
        acceptNonZeroExit = false,
      ) => {
        capturedOutput = undefined;
        await verifySnapshot();
        const snapshot = await runOwnedCommand(
          {
            command: command.path,
            arguments: args,
            cwd: root.path,
            expectedCommand: command.path,
            runId: `rea-wabt-${randomUUID()}`,
            hostEnvironment: this.environment,
          },
          {
            timeoutMs: commandTimeoutMs,
            diagnosticBytes: WABT_LIMITS.outputBytes,
            acceptNonZeroExit,
          },
          {
            ...(options?.signal === undefined
              ? {}
              : { signal: options.signal }),
            ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
          },
        );
        const current = await readStableArtifact(
          command.path,
          WABT_LIMITS.toolBytes,
          options?.signal,
          undefined,
          this.#resources,
        );
        if (current.sha256 !== command.sha256)
          throw new AnalysisOutputError(
            OPERATION,
            "Configured WABT executable changed during inspection.",
          );
        await verifySnapshot();
        return snapshot;
      };
      for (const command of commands) {
        versionProbe = {
          configuration_key: "REA_WABT_BIN_DIRECTORY",
          executable_path: command.path,
          tool: command.tool,
          expected_version: WABT_VERSION,
        };
        const version = await execute(command, ["--version"]);
        if (
          version.stdout.text.trim() !== WABT_VERSION ||
          version.stderr.text !== ""
        ) {
          const reason = `Unsupported ${command.tool} version banner; expected ${WABT_VERSION}.`;
          throw new AnalysisCapabilityUnavailableError(
            WABT_PROVIDER_IDENTITY.id,
            OPERATION,
            reason,
            {
              userMessage: reason,
              diagnostics: versionProbe,
              capturedOutput: {
                stdout: version.stdout.text,
                stderr: version.stderr.text,
                truncated: version.diagnosticTruncated === true,
              },
              remediationAction: wabtConfigurationRecoveryAction(),
            },
          );
        }
        command.version_banner = version.stdout.text;
        versionProbe = undefined;
      }
      // Success and validation failure report the same admitted tool/execution facts.
      const toolProfile = {
        source: "https://github.com/WebAssembly/wabt",
        release: WABT_VERSION,
        source_commit: "ff0ef7e0009402740c805a9744c09b05be063e48",
        commands,
        timeout_ms: commandTimeoutMs,
        output_budget_bytes: WABT_LIMITS.outputBytes,
      };
      phase = "artifact";
      const selected = await readStableArtifact(
        input.path,
        WABT_LIMITS.inputBytes,
        options?.signal,
        undefined,
        this.#resources,
      );
      const artifact = {
        path: input.path,
        sha256: selected.sha256,
        bytes: selected.bytes.length,
      };
      const candidates = [];
      for (const path of new Set([input.path, ...input.candidate_paths])) {
        const bytes =
          path === input.path
            ? selected
            : await readStableArtifact(
                path,
                WABT_LIMITS.inputBytes,
                options?.signal,
                undefined,
                this.#resources,
              );
        candidates.push({
          path,
          sha256: bytes.sha256,
          bytes: bytes.bytes.length,
        });
      }
      const glue = [];
      for (const path of input.glue_paths) {
        const bytes = await readStableArtifact(
          path,
          WABT_LIMITS.inputBytes,
          options?.signal,
          undefined,
          this.#resources,
        );
        // Keep source characters intact so locations match the hashed artifact.
        const source = new TextDecoder("utf-8", {
          fatal: true,
          ignoreBOM: true,
        }).decode(bytes.bytes);
        glue.push({
          artifact: { path, sha256: bytes.sha256, bytes: bytes.bytes.length },
          ...associateWasmGlue(
            source,
            path,
            candidates.map((candidate) => candidate.path),
          ),
        });
      }
      await writeFile(snapshotPath, selected.bytes, {
        flag: "wx",
        mode: 0o400,
        ...(options?.signal === undefined ? {} : { signal: options.signal }),
      });
      snapshotHash = selected.sha256;
      phase = "producer";
      const [validate, objdump, decode] = commands;
      if (
        validate === undefined ||
        objdump === undefined ||
        decode === undefined
      )
        throw new Error("Incomplete WABT tool profile.");
      const validation = await execute(validate, validate.arguments, true);
      if (validation.exitCode !== 0)
        throw new AnalysisInputError(
          OPERATION,
          {
            partialObservation: createEvidence(
              { path: input.path, format: "file", sha256: selected.sha256 },
              WABT_PROVIDER_IDENTITY,
              {
                operation: OPERATION,
                parameters: input,
                result: {
                  artifact,
                  validation: "rejected-by-selected-profile",
                  tool_profile: toolProfile,
                  exit_code: validation.exitCode ?? null,
                  stdout: validation.stdout.text,
                  stderr: validation.stderr.text,
                },
                confidence: "observed",
                locations: [{ kind: "artifact-path", path: input.path }],
                limitations: [
                  "WABT rejected these exact selected bytes with --enable-all; no complete inspection or target execution occurred.",
                ],
              },
            ),
            capturedOutput: {
              stdout: validation.stdout.text,
              stderr: validation.stderr.text,
              truncated: false,
            },
          },
          [
            {
              path: ["path"],
              reason: "invalid_format",
              message:
                "Selected bytes failed WABT validation with --enable-all; inspect retained upstream diagnostics.",
            },
          ],
        );
      const dump = await execute(objdump, objdump.arguments);
      capturedOutput = {
        stdout: dump.stdout.text,
        stderr: dump.stderr.text,
        truncated: false,
      };
      if (dump.stderr.text !== "")
        throw new AnalysisOutputError(
          OPERATION,
          "Unexpected WABT section output.",
        );
      const wat = await execute(decode, decode.arguments);
      capturedOutput = {
        stdout: wat.stdout.text,
        stderr: wat.stderr.text,
        truncated: false,
      };
      if (!wat.stdout.text.startsWith("(module") || wat.stderr.text !== "")
        throw new AnalysisOutputError(
          OPERATION,
          "Unexpected WABT decoding output.",
        );
      const {
        imports,
        exports,
        customSectionNames,
        debugModuleNames,
        interface: interfaceFacts,
      } = parseWabtWat(wat.stdout.text);
      capturedOutput = {
        stdout: dump.stdout.text,
        stderr: dump.stderr.text,
        truncated: false,
      };
      const { sections, headers, details } = parseWabtOutput(
        dump.stdout.text,
        artifact.bytes,
        customSectionNames,
        debugModuleNames,
      );
      const limitations = [
        "WAT is a decoded representation, not original source or proof of runtime behavior. Custom annotations may retain payloads, but WAT does not establish original binary layout or round-trip byte identity. Original bytes and objdump output remain authoritative.",
        "Imports and exports retain exact top-level WABT WAT forms. Names remain escaped producer text; unescaped objdump display names are not parsed as unambiguous identifiers.",
        "JavaScript references are AST-observed static literals only. Candidate matches are associations, not proven data flow, URL-to-file identity or runtime loading. Computed references and aliases are not resolved.",
        "No target execution or implicit fetch. WABT tools are trusted caller-supplied executables; SHA-256 identifies their bytes, not publisher authenticity. No OS memory sandbox is claimed.",
        `Each WABT command has a ${String(commandTimeoutMs)} ms deadline and a fixed 32 MiB combined output budget. The deadline is not a whole-inspection budget. Oversized output fails instead of producing truncated success.`,
      ];
      const report = wasmArtifactSchema.parse({
        artifact,
        validation: "valid",
        sections,
        imports,
        exports,
        interface: interfaceFacts,
        headers,
        details,
        wat: {
          text: wat.stdout.text,
          sha256: digest(wat.stdout.text),
          representation: "decoded-wat",
        },
        tool_profile: toolProfile,
        candidates,
        glue,
        runtime_execution: "not-performed",
        network_fetch: "not-performed",
        limitations,
      });
      result = ok(
        createAnalysisExecution(report, WABT_PROVIDER_IDENTITY, {
          subject: {
            path: input.path,
            format: "file",
            sha256: selected.sha256,
          },
          locations: [{ kind: "artifact-path", path: input.path }],
          limitations,
        }),
      );
    } catch (cause: unknown) {
      const failure = wabtFailure(cause, phase, input.path, {
        commandTimeoutMs,
        ...(versionProbe === undefined ? {} : { versionProbe }),
      });
      runtime?.retainCommandFailure(cause, failure, this.#resources);
      result = err(
        failure instanceof AnalysisOutputError &&
          failure.capturedOutput === undefined &&
          capturedOutput !== undefined
          ? new AnalysisOutputError(OPERATION, failure.reason, {
              cause: failure,
              capturedOutput,
              cleanup: failure.cleanup,
              diagnostics: failure.diagnostics,
            }).bindCleanupDependencies([failure])
          : failure,
      );
    }
    if (runtime !== undefined) {
      const cleanup = await this.#resources.release({
        kind: "lease",
        resource: runtime.path,
        lease: runtime.lease,
      });
      let partialObservation = result.ok
        ? undefined
        : result.error.partialObservation;
      if (
        result.ok &&
        (options?.signal?.aborted || cleanup.kind === "failed")
      ) {
        partialObservation = createAnalysisExecutionEvidence(
          OPERATION,
          input,
          result.value,
          "observed",
        );
      }
      if (result.ok && options?.signal?.aborted) {
        result = err(
          new AnalysisCancelledError(OPERATION, {
            cause: options?.signal?.reason,
            ...(partialObservation === undefined ? {} : { partialObservation }),
          }),
        );
      }
      if (cleanup.kind === "failed") {
        const cause = cleanup.cause;
        const retainedObservation = result.ok
          ? partialObservation
          : result.error.partialObservation;
        const failure = new ProviderCleanupError(
          WABT_PROVIDER_IDENTITY.id,
          [runtime.path],
          {
            reason: cause instanceof Error ? cause.message : String(cause),
            previous_error: result.ok
              ? null
              : projectAnalysisError(result.error),
          },
          {
            operation: OPERATION,
            cause,
            ...(retainedObservation === undefined
              ? {}
              : { partialObservation: retainedObservation }),
          },
        );
        new AnalysisCleanupLeaseGroup(failure, [runtime.lease]);
        result = result.ok
          ? err(failure)
          : err(
              analysisErrorWithCleanupFailure(
                result.error,
                failure,
                OPERATION,
              ).bindCleanupDependencies([result.error, failure]),
            );
      }
    }
    return result;
  }
}

/** Retry errors follow their exact retained leases, including partially released groups. */
const resourceCleanupFailure = (cause: unknown): ProviderCleanupError => {
  const cleanup =
    cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined;
  const failure = new ProviderCleanupError(
    WABT_PROVIDER_IDENTITY.id,
    cleanup?.resources ?? ["artifact-resources"],
    {
      reason:
        cleanup?.reason ??
        (cause instanceof Error ? cause.message : String(cause)),
    },
    { operation: OPERATION, cause },
  );
  bindArtifactFileCleanup(cause, failure);
  return failure;
};