Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(ghidra): admit installation metadata through owned bounded reads
morluto5112fe07ae44
diff --git a/docs/installation.md b/docs/installation.mdindex 08eace307..57eba7949 100644--- a/docs/installation.md+++ b/docs/installation.md@@ -894,6 +894,13 @@ the launcher fails before preparing its home/cache/config/temp directories orstarting Java. The client may already have allocated private runtime/endpointresources and a target snapshot; existing startup-failure cleanup still applies.Restore the selected release's properties instead of renaming its installation folder.+Inspection follows selected properties symlinks, admits only a regular file,+and caps the metadata payload at 1 MiB under REA's resource budget. A final+one-byte probe checks for growth. This is not a Java+Properties format limit. Reads preserve Ghidra's Latin-1 byte mapping and check+the descriptor and selected name for changes. Permission failures and resource+refusals remain explicit; failed descriptor cleanup must succeed before that+owner admits another inspection.This coordinate selects only REA's session-private configuration directory, notthe installation or an existing user configuration directory.diff --git a/src/application/binary/DeferredAnalysisClient.test.ts b/src/application/binary/DeferredAnalysisClient.test.tsindex 861df20a3..740273dc6 100644--- a/src/application/binary/DeferredAnalysisClient.test.ts+++ b/src/application/binary/DeferredAnalysisClient.test.ts@@ -4,7 +4,12 @@ import {createAnalysisExecution,type AnalysisClient,} from "../AnalysisProvider.js";-import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";+import {+ AnalysisCancelledError,+ AnalysisAccessDeniedError,+ AnalysisArtifactChangedError,+ AnalysisResourceConstraintError,+} from "../../domain/analysisErrorCore.js";import { ProviderAdapterError } from "../../domain/providerAdapterError.js";import { ProviderCleanupError } from "../../domain/providerCleanupError.js";import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";@@ -12,6 +17,51 @@ import { resolvedAnalysisError } from "../../domain/analysisErrorBase.js";import { err, ok } from "../../domain/result.js";const identity = { id: "controlled", name: "Controlled client", version: "1" };++it.each([+ new AnalysisAccessDeniedError(+ "ghidra:installation",+ "/selected/properties",+ "EACCES",+ ),+ new AnalysisArtifactChangedError(+ "ghidra:installation",+ "/selected/properties",+ "selected name changed",+ ),+ new AnalysisResourceConstraintError(+ "ghidra:installation",+ "file-size",+ "metadata budget",+ { maximum_bytes: 1024 },+ { retryable: false },+ ),+])(+ "attributes prerequisite $_tag to the requested operation without changing its facts",+ async (physical) => {+ const client = new DeferredAnalysisClient(async () => {+ throw physical;+ }, identity.id);+ try {+ const result = await client.execute("analyze_function", {});+ if (result.ok) throw new Error("Expected prerequisite failure");+ expect(result.error).toMatchObject({+ _tag: physical._tag,+ operation: "analyze_function",+ });+ expect(result.error.cause).toBe(physical);+ if (physical instanceof AnalysisResourceConstraintError)+ expect(result.error).toMatchObject({+ resource: "file-size",+ reportedLimits: { maximum_bytes: 1024 },+ retryable: false,+ });+ else expect(result.error).toMatchObject({ path: "/selected/properties" });+ } finally {+ await client.close();+ }+ },+);const gate = <T = void>() => {let resolve!: (value: T) => void;const promise = new Promise<T>((finish) => {diff --git a/src/artifacts/ArtifactFileOperation.ts b/src/artifacts/ArtifactFileOperation.tsindex a7d49754e..72576ef99 100644--- a/src/artifacts/ArtifactFileOperation.ts+++ b/src/artifacts/ArtifactFileOperation.ts@@ -10,6 +10,7 @@ import {import { ArtifactReaderFailure } from "./ArtifactReader.js";import {ArtifactResourceRetryFailure,+ type ArtifactResourceOwner,type ArtifactResourceScope,} from "./ArtifactResourceScope.js";import {@@ -179,7 +180,11 @@ export const assertArtifactReadActive = (/** Admit a regular file without blocking on pipes, retaining failed admission closes. */export const withArtifactRegularFile = async <Value>(path: string,- resources: ArtifactResourceScope,+ resources: {+ retain(+ owner: Extract<ArtifactResourceOwner, { readonly kind: "lease" }>,+ ): void;+ },signal: AbortSignal | undefined,operation: (file: FileHandle) => Promise<Value>,symlinks: "follow" | "reject" = "reject",diff --git a/src/filesystem/RegularFile.ts b/src/filesystem/RegularFile.tsindex 8b83f936a..e5850f532 100644--- a/src/filesystem/RegularFile.ts+++ b/src/filesystem/RegularFile.ts@@ -54,8 +54,11 @@ export class RegularFileAdmissionFailure extends Error {/** A regular input no longer matches the extent or identity admitted for reading. */export class RegularFileChangedError extends Error {readonly code = "ESTALE";- constructor(readonly path: string) {- super(`Selected input changed while being read: ${path}`);+ constructor(+ readonly path: string,+ options?: ErrorOptions,+ ) {+ super(`Selected input changed while being read: ${path}`, options);this.name = "RegularFileChangedError";}}diff --git a/src/filesystem/readStableFileBytes.ts b/src/filesystem/readStableFileBytes.tsnew file mode 100644index 000000000..882a43061--- /dev/null+++ b/src/filesystem/readStableFileBytes.ts@@ -0,0 +1,75 @@+import { lstat, stat, type FileHandle } from "node:fs/promises";+import {+ assertRegularFileActive,+ RegularFileChangedError,+ sameRegularFileState,+} from "./RegularFile.js";++/** Resource refusal carries the observed extent before allocating file bytes. */+export class RegularFileCapacityError extends Error {+ readonly _tag = "RegularFileCapacityError";+ constructor(+ readonly path: string,+ readonly maximumBytes: number,+ readonly observedBytes: bigint,+ ) {+ super(`Selected file must be at most ${maximumBytes} bytes: ${path}`);+ this.name = this._tag;+ }+}++/** Read an admitted descriptor completely, checking its extent and selected name. */+export const readStableFileBytes = async (+ file: FileHandle,+ path: string,+ maximumBytes: number,+ options: {+ readonly signal?: AbortSignal;+ readonly symlinks: "follow" | "reject";+ },+): Promise<Buffer> => {+ if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0)+ throw new RangeError(+ "Maximum file bytes must be a nonnegative safe integer",+ );+ assertRegularFileActive(options.signal);+ const before = await file.stat({ bigint: true });+ if (before.size > BigInt(maximumBytes))+ throw new RegularFileCapacityError(path, maximumBytes, before.size);+ assertRegularFileActive(options.signal);+ const bytes = Buffer.alloc(Number(before.size));+ let offset = 0;+ while (offset < bytes.length) {+ assertRegularFileActive(options.signal);+ const read = await file.read(bytes, offset, bytes.length - offset, offset);+ if (read.bytesRead === 0) throw new RegularFileChangedError(path);+ offset += read.bytesRead;+ }+ assertRegularFileActive(options.signal);+ const extra = Buffer.alloc(1);+ const named = async () => {+ try {+ return await (options.symlinks === "follow" ? stat : lstat)(path, {+ bigint: true,+ });+ } catch (cause: unknown) {+ if (+ cause instanceof Error &&+ "code" in cause &&+ (cause.code === "ENOENT" ||+ cause.code === "ENOTDIR" ||+ cause.code === "ELOOP")+ )+ throw new RegularFileChangedError(path, { cause });+ throw cause;+ }+ };+ if (+ (await file.read(extra, 0, 1, offset)).bytesRead !== 0 ||+ !sameRegularFileState(before, await file.stat({ bigint: true })) ||+ !sameRegularFileState(before, await named())+ )+ throw new RegularFileChangedError(path);+ assertRegularFileActive(options.signal);+ return bytes;+};diff --git a/src/ghidra/GhidraAnalysisSeeds.ts b/src/ghidra/GhidraAnalysisSeeds.tsindex 5dc6ba2d6..d1819e35a 100644--- a/src/ghidra/GhidraAnalysisSeeds.ts+++ b/src/ghidra/GhidraAnalysisSeeds.ts@@ -11,8 +11,8 @@ import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.jimport {readGhidraProfileArtifact,writeGhidraProfileArtifact,- ghidraProfileArtifactError,-} from "./GhidraProfileArtifacts.js";+ ghidraFileFailure,+} from "./GhidraFileArtifacts.js";import { err, ok, type Result } from "../domain/result.js";/** Seed file format admitted by this adapter. */@@ -180,7 +180,7 @@ export const resolveGhidraAnalysisSeeds = async (entries = await readSeeds(path, resources, signal);} catch (cause: unknown) {return err(- ghidraProfileArtifactError(cause, "resolve_analysis_profile", {+ ghidraFileFailure(cause, "resolve_analysis_profile", {setting: "REA_GHIDRA_SEED_FILE",path: configured,}),@@ -199,7 +199,7 @@ export const resolveGhidraAnalysisSeeds = async (}).catch((cause: unknown) =>err(- ghidraProfileArtifactError(cause, "resolve_analysis_profile", {+ ghidraFileFailure(cause, "resolve_analysis_profile", {setting: "REA_GHIDRA_SEED_FILE",}),),@@ -232,7 +232,7 @@ export const snapshotGhidraAnalysisSeeds = async (return path;}).catch((cause: unknown) => {- throw ghidraProfileArtifactError(cause, "open_binary", {+ throw ghidraFileFailure(cause, "open_binary", {setting: "REA_GHIDRA_SEED_FILE",path: commitment.path,});diff --git a/src/ghidra/GhidraProfileArtifacts.ts b/src/ghidra/GhidraFileArtifacts.tssimilarity index 58%rename from src/ghidra/GhidraProfileArtifacts.tsrename to src/ghidra/GhidraFileArtifacts.tsindex 3527992ed..ff30de6cc 100644--- a/src/ghidra/GhidraProfileArtifacts.ts+++ b/src/ghidra/GhidraFileArtifacts.ts@@ -1,17 +1,27 @@-import { lstat, open } from "node:fs/promises";+import { open } from "node:fs/promises";import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";import {assertArtifactReadActive,artifactFileCancellationCause,artifactFilePrimaryFailure,+ mapArtifactFileFailure,bindArtifactFileCleanup,withArtifactFileHandle,withArtifactRegularFile,} from "../artifacts/ArtifactFileOperation.js";-import { sameRegularFileState } from "../filesystem/RegularFile.js";+import {+ readStableFileBytes,+ RegularFileCapacityError,+} from "../filesystem/readStableFileBytes.js";import { AnalysisError } from "../domain/analysisErrorBase.js";-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";+import {+ AnalysisCancelledError,+ AnalysisAccessDeniedError,+ AnalysisArtifactChangedError,+ AnalysisResourceConstraintError,+} from "../domain/analysisErrorCore.js";+import { RegularFileChangedError } from "../filesystem/RegularFile.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";@@ -26,34 +36,10 @@ export const readGhidraProfileArtifact = <Value>(interpret: (bytes: Buffer) => Value,): Promise<Value> =>withArtifactRegularFile(path, resources, signal, async (file) => {- const before = await file.stat({ bigint: true });- if (before.size > BigInt(maximumBytes))- throw new Error(- `Ghidra profile artifact must be at most ${String(maximumBytes)} bytes: ${path}`,- );- const bytes = Buffer.alloc(Number(before.size));- let offset = 0;- while (offset < bytes.length) {- assertArtifactReadActive(signal);- const read = await file.read(- bytes,- offset,- bytes.length - offset,- offset,- );- if (read.bytesRead === 0)- throw new Error(`Incomplete Ghidra profile artifact read: ${path}`);- offset += read.bytesRead;- }- assertArtifactReadActive(signal);- const extra = Buffer.alloc(1);- if (- (await file.read(extra, 0, 1, offset)).bytesRead !== 0 ||- !sameRegularFileState(before, await file.stat({ bigint: true })) ||- !sameRegularFileState(before, await lstat(path, { bigint: true }))- )- throw new Error(`Ghidra profile artifact changed during read: ${path}`);- assertArtifactReadActive(signal);+ const bytes = await readStableFileBytes(file, path, maximumBytes, {+ symlinks: "reject",+ ...(signal === undefined ? {} : { signal }),+ });return interpret(bytes);});@@ -72,11 +58,47 @@ export const writeGhidraProfileArtifact = async (};/** Preserve physical failure, exact cancellation, and all retained file leases. */-export const ghidraProfileArtifactError = (+export const ghidraFileFailure = (cause: unknown,operation: string,diagnostics: Readonly<Record<string, JsonValue>> = {},): AnalysisError => {+ cause = mapArtifactFileFailure(cause, (primary) => {+ if (primary instanceof RegularFileCapacityError)+ return new AnalysisResourceConstraintError(+ operation,+ "file-size",+ primary.message,+ {+ maximum_bytes: primary.maximumBytes,+ observed_bytes: primary.observedBytes.toString(),+ },+ { cause: primary, diagnostics, retryable: false },+ );+ if (primary instanceof RegularFileChangedError)+ return new AnalysisArtifactChangedError(+ operation,+ primary.path,+ primary.message,+ { cause: primary, diagnostics },+ );+ if (+ primary instanceof Error &&+ "code" in primary &&+ (primary.code === "EACCES" || primary.code === "EPERM")+ ) {+ const path =+ "path" in primary && typeof primary.path === "string"+ ? primary.path+ : diagnostics.path;+ if (typeof path === "string")+ return new AnalysisAccessDeniedError(operation, path, primary.code, {+ cause: primary,+ diagnostics,+ });+ }+ return primary;+ });if (cause instanceof AnalysisError) return cause;const primary = artifactFilePrimaryFailure(cause);const reason = primary instanceof Error ? primary.message : String(primary);@@ -112,7 +134,20 @@ export const ghidraProfileArtifactError = (: new ProviderAdapterError("ghidra", operation, {cause,cleanup,- diagnostics: { ...diagnostics, reason },+ diagnostics: {+ ...diagnostics,+ ...(primary instanceof Error &&+ "code" in primary &&+ typeof primary.code === "string"+ ? { system_code: primary.code }+ : {}),+ ...(primary instanceof Error &&+ "syscall" in primary &&+ typeof primary.syscall === "string"+ ? { syscall: primary.syscall }+ : {}),+ reason,+ },userMessage: reason,});bindArtifactFileCleanup(cause, error);diff --git a/src/ghidra/GhidraInstallation.ts b/src/ghidra/GhidraInstallation.tsindex 0b351da5b..090dfee35 100644--- a/src/ghidra/GhidraInstallation.ts+++ b/src/ghidra/GhidraInstallation.ts@@ -9,13 +9,16 @@ import {} from "./GhidraJavaProbe.js";import type { Result } from "../domain/result.js";import { snapshotEnvironment } from "../process/snapshotEnvironment.js";+import {+ readGhidraInstallationProperties,+ type GhidraInstallationFileOptions,+} from "./GhidraInstallationProperties.js";import { constants } from "node:fs";import {accessSync,closeSync,fstatSync,openSync,- readFileSync,readSync,realpathSync,statSync,@@ -267,7 +270,10 @@ export interface GhidraExecutableHeaderProbe {export interface GhidraInstallationHost {readonly platform?: NodeJS.Platform;readonly architecture?: NodeJS.Architecture;- readText(path: string): string | undefined;+ 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@@ -467,7 +473,10 @@ const installationCoordinates = async (const properties =applicationPropertiesPath === null? undefined- : host.readText(applicationPropertiesPath);+ : await host.readText(applicationPropertiesPath, {+ resourceOwner: options.resourceOwner,+ ...(options.signal === undefined ? {} : { signal: options.signal }),+ });const javaCommand = (() => {if (options.javaHome !== undefined)return path.join(@@ -942,17 +951,7 @@ const javaRemediation = (};export const systemGhidraInstallationHost = (): GhidraInstallationHost => ({- readText(path) {- try {- // Ghidra loads this file with Properties.load(InputStream), which maps- // bytes as ISO-8859-1 rather than decoding UTF-8.- return readFileSync(path).toString("latin1");- } catch (cause: unknown) {- // best-effort cleanup: optional install probing; unreadable means unknown.- void cause;- return undefined;- }- },+ readText: readGhidraInstallationProperties,executableHeader(path) {let handle: number | undefined;try {diff --git a/src/ghidra/GhidraInstallationProperties.ts b/src/ghidra/GhidraInstallationProperties.tsnew file mode 100644index 000000000..7562cd39a--- /dev/null+++ b/src/ghidra/GhidraInstallationProperties.ts@@ -0,0 +1,96 @@+import { createHash } from "node:crypto";+import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";+import {+ ArtifactFileCancelled,+ ArtifactFileCleanupFailure,+ artifactFilePrimaryFailure,+ withArtifactRegularFile,+} from "../artifacts/ArtifactFileOperation.js";+import { jsonValueSchema } from "../domain/jsonValue.js";+import { NonRegularFileReadError } from "../filesystem/RegularFile.js";+import { readStableFileBytes } from "../filesystem/readStableFileBytes.js";+import { ghidraApplicationProperties } from "./GhidraInstallationPolicy.js";+import { ghidraFileFailure } from "./GhidraFileArtifacts.js";++/** Metadata admission budget, not a Java Properties format limit. */+export const MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES = 1024 * 1024;+export interface GhidraInstallationFileOptions {+ readonly resourceOwner: FileCloseResourceOwner;+ readonly signal?: AbortSignal;+}++/** Preserve Java's Latin-1 byte mapping and follow the caller's selected symlinks. */+export const readGhidraInstallationProperties = async (+ path: string,+ options: GhidraInstallationFileOptions,+): Promise<string | undefined> => {+ try {+ return await options.resourceOwner.run(() =>+ withArtifactRegularFile(+ path,+ {+ retain: (resource) =>+ options.resourceOwner.retain(+ { close: () => resource.lease.release() },+ resource.resource,+ ),+ },+ options.signal,+ async (file) =>+ (+ await readStableFileBytes(+ file,+ path,+ MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES,+ {+ symlinks: "follow",+ ...(options.signal === undefined+ ? {}+ : { signal: options.signal }),+ },+ )+ ).toString("latin1"),+ "follow",+ ),+ );+ } catch (cause: unknown) {+ const physical = artifactFilePrimaryFailure(cause);+ if (+ !(cause instanceof ArtifactFileCleanupFailure) &&+ physical instanceof Error &&+ "code" in physical &&+ "syscall" in physical &&+ physical.syscall === "open" &&+ (physical.code === "ENOENT" || physical.code === "ENOTDIR")+ )+ return undefined;+ const completed =+ cause instanceof ArtifactFileCancelled+ ? cause.fileCancellation.outcome.value+ : cause instanceof ArtifactFileCleanupFailure &&+ cause.fileCleanupFailure.outcome.kind === "completed"+ ? cause.fileCleanupFailure.outcome.value+ : undefined;+ const diagnostics = {+ path,+ stage: "installation_properties",+ ...(physical instanceof NonRegularFileReadError+ ? { system_code: physical.code }+ : {}),+ ...(typeof completed !== "string"+ ? {}+ : {+ completed_properties: {+ bytes: Buffer.byteLength(completed, "latin1"),+ sha256: createHash("sha256")+ .update(completed, "latin1")+ .digest("hex"),+ properties: jsonValueSchema.parse(+ ghidraApplicationProperties(completed),+ ),+ },+ }),+ };+ throw ghidraFileFailure(cause, "ghidra:installation", diagnostics);+ }+};diff --git a/src/ghidra/extensions/GhidraExtensions.ts b/src/ghidra/extensions/GhidraExtensions.tsindex 8d188ec72..890ead74c 100644--- a/src/ghidra/extensions/GhidraExtensions.ts+++ b/src/ghidra/extensions/GhidraExtensions.ts@@ -14,8 +14,8 @@ import { assertArtifactReadActive } from "../../artifacts/ArtifactFileOperation.import {readGhidraProfileArtifact,writeGhidraProfileArtifact,- ghidraProfileArtifactError,-} from "../GhidraProfileArtifacts.js";+ ghidraFileFailure,+} from "../GhidraFileArtifacts.js";import type { AnalysisError } from "../../domain/analysisErrorBase.js";import { jsonObjectSchema } from "../../domain/jsonValue.js";import { err, ok, type Result } from "../../domain/result.js";@@ -125,7 +125,7 @@ export const resolveGhidraExtensions = async (});} catch (cause: unknown) {return err(- ghidraProfileArtifactError(cause, "resolve_analysis_profile", {+ ghidraFileFailure(cause, "resolve_analysis_profile", {extension: adapter.id,path: configured,}),@@ -139,7 +139,7 @@ export const resolveGhidraExtensions = async (return ok(extensions);}).catch((cause: unknown) =>- err(ghidraProfileArtifactError(cause, "resolve_analysis_profile")),+ err(ghidraFileFailure(cause, "resolve_analysis_profile")),);/** Require explicit local configuration before admitting executable code from a profile. */@@ -239,7 +239,7 @@ export const snapshotGhidraExtensions = async (return result;}).catch((cause: unknown) => {- throw ghidraProfileArtifactError(cause, "open_binary");+ throw ghidraFileFailure(cause, "open_binary");});/** Require every configured producer result to match its artifact and registered ABI. */diff --git a/src/providers/AnalysisClientFailure.ts b/src/providers/AnalysisClientFailure.tsindex 5cb04cc26..e00245091 100644--- a/src/providers/AnalysisClientFailure.ts+++ b/src/providers/AnalysisClientFailure.ts@@ -2,6 +2,9 @@ import { AnalysisError } from "../domain/analysisErrorBase.js";import {AnalysisCancelledError,AnalysisCapabilityUnavailableError,+ AnalysisAccessDeniedError,+ AnalysisArtifactChangedError,+ AnalysisResourceConstraintError,} from "../domain/analysisErrorCore.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";@@ -26,7 +29,10 @@ export const analysisClientFailureForOperation = (if (!(cause instanceof AnalysisCancelledError) &&!(cause instanceof ProviderAdapterError) &&- !(cause instanceof AnalysisCapabilityUnavailableError)+ !(cause instanceof AnalysisCapabilityUnavailableError) &&+ !(cause instanceof AnalysisAccessDeniedError) &&+ !(cause instanceof AnalysisArtifactChangedError) &&+ !(cause instanceof AnalysisResourceConstraintError))return cause;const context = {@@ -58,34 +64,65 @@ export const analysisClientFailureForOperation = (}: {}),};- const result =- cause instanceof AnalysisCancelledError- ? new AnalysisCancelledError(operation, {- ...context,- cause: cause.cause,- })- : cause instanceof AnalysisCapabilityUnavailableError- ? new AnalysisCapabilityUnavailableError(- cause.providerId,- operation,- cause.reason,- {- ...context,- ...(cause.userMessage === undefined- ? {}- : { userMessage: cause.userMessage }),- retryable: cause.retryable,- },- )- : new ProviderAdapterError(providerId, operation, {- ...context,- ...(cause.userMessage === undefined- ? {}- : { userMessage: cause.userMessage }),- ...(cause.remediationAction === undefined- ? {}- : { remediationAction: cause.remediationAction }),- });+ let result: AnalysisError;+ if (cause instanceof AnalysisCancelledError)+ result = new AnalysisCancelledError(operation, {+ ...context,+ cause: cause.cause,+ });+ else if (cause instanceof AnalysisCapabilityUnavailableError)+ result = new AnalysisCapabilityUnavailableError(+ cause.providerId,+ operation,+ cause.reason,+ {+ ...context,+ ...(cause.userMessage === undefined+ ? {}+ : { userMessage: cause.userMessage }),+ retryable: cause.retryable,+ },+ );+ else if (cause instanceof AnalysisAccessDeniedError)+ result = new AnalysisAccessDeniedError(+ operation,+ cause.path,+ cause.systemCode,+ context,+ );+ else if (cause instanceof AnalysisArtifactChangedError)+ result = new AnalysisArtifactChangedError(+ operation,+ cause.path,+ cause.reason,+ context,+ );+ else if (cause instanceof AnalysisResourceConstraintError)+ result = new AnalysisResourceConstraintError(+ operation,+ cause.resource,+ cause.reason,+ cause.reportedLimits,+ {+ ...context,+ ...(cause.retryable === undefined+ ? {}+ : { retryable: cause.retryable }),+ ...(cause.remediationAction === undefined+ ? {}+ : { remediationAction: cause.remediationAction }),+ },+ );+ else+ result = new ProviderAdapterError(providerId, operation, {+ ...context,+ ...(cause.userMessage === undefined+ ? {}+ : { userMessage: cause.userMessage }),+ ...(cause.remediationAction === undefined+ ? {}+ : { remediationAction: cause.remediationAction }),+ });return cause.cleanupIncomplete? result.bindCleanupDependencies([cause]): result;diff --git a/tests/boundary/cli/ghidraInstallationProperties.test.ts b/tests/boundary/cli/ghidraInstallationProperties.test.tsnew file mode 100644index 000000000..5f68cb0b1--- /dev/null+++ b/tests/boundary/cli/ghidraInstallationProperties.test.ts@@ -0,0 +1,41 @@+import { execFile } from "node:child_process";+import { promisify } from "node:util";+import { mkdir, truncate, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { expect } from "vitest";+import { MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES } from "../../../src/ghidra/GhidraInstallationProperties.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { cliTest } from "../../support/cli/cliFixture.js";++cliTest.skipIf(process.platform === "win32").for(["pipe", "capacity"] as const)(+ "doctor reports selected properties %s without launching Java",+ async (kind, { cli }) => {+ const root = await createTestTempDirectory("rea-doctor-properties-");+ const install = join(root, "ghidra");+ const path = join(install, "Ghidra/application.properties");+ await mkdir(join(install, "Ghidra"), { recursive: true });+ if (kind === "pipe") await promisify(execFile)("mkfifo", [path]);+ else {+ await writeFile(path, "application.version=12.1.4\n");+ await truncate(path, MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES + 1);+ }+ const result = await cli.run({+ arguments: ["doctor", "--provider", "ghidra", "--json"],+ environment: {+ GHIDRA_INSTALL_DIR: install,+ JAVA_HOME: join(root, "missing-jdk"),+ REA_LOG_LEVEL: "silent",+ },+ timeoutMs: 5000,+ });+ expect(result.exitCode, `${result.stdout}\n${result.stderr}`).toBe(1);+ expect(result.signal).toBeNull();+ expect(result.json).toMatchObject({+ code: kind === "pipe" ? "execution_failure" : "resource_constraint",+ details: {+ operation: "doctor",+ diagnostics: { path, stage: "installation_properties" },+ },+ });+ },+);diff --git a/tests/boundary/filesystem/ghidraInstallationProperties.test.ts b/tests/boundary/filesystem/ghidraInstallationProperties.test.tsnew file mode 100644index 000000000..7cf0f4777--- /dev/null+++ b/tests/boundary/filesystem/ghidraInstallationProperties.test.ts@@ -0,0 +1,346 @@+import { execFile } from "node:child_process";+import { promisify } from "node:util";+import {+ rename,+ chmod,+ appendFile,+ symlink,+ truncate,+ writeFile,+ type FileHandle,+} from "node:fs/promises";+import { join } from "node:path";+import { afterEach, expect, it, vi } from "vitest";+import { AnalysisError } from "../../../src/domain/analysisErrorBase.js";+import { ProviderCleanupError } from "../../../src/domain/providerCleanupError.js";+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";+import {+ readGhidraInstallationProperties,+ MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES,+} from "../../../src/ghidra/GhidraInstallationProperties.js";+import { createInspectionResources } from "../../fixtures/inspectionResources.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";++const controls = vi.hoisted(() => ({+ file: undefined as ((handle: FileHandle, path: string) => void) | undefined,+}));+vi.mock("node:fs/promises", async (importOriginal) => {+ const actual = await importOriginal<typeof import("node:fs/promises")>();+ return {+ ...actual,+ open: async (...args: Parameters<typeof actual.open>) => {+ const handle = await actual.open(...args);+ controls.file?.(handle, String(args[0]));+ return handle;+ },+ };+});+afterEach(() => {+ controls.file = undefined;+ vi.restoreAllMocks();+});++const properties = "application.version=12.1.4\napplication.java.min=21\n";++it("preserves a descriptor read failure instead of reporting absent metadata", async () => {+ const root = await createTestTempDirectory(+ "rea-install-properties-read-missing-",+ );+ const path = join(root, "application.properties");+ await writeFile(path, properties);+ const physical = Object.assign(+ new Error("controlled descriptor read failure"),+ { code: "ENOENT", syscall: "read" },+ );+ controls.file = (handle, opened) => {+ if (opened === path) vi.spyOn(handle, "read").mockRejectedValue(physical);+ };+ const resources = createInspectionResources();+ try {+ await expect(+ readGhidraInstallationProperties(path, {+ resourceOwner: resources.owner,+ }),+ ).rejects.toMatchObject({+ _tag: "ProviderAdapterError",+ cause: physical,+ diagnostics: {+ path,+ stage: "installation_properties",+ system_code: "ENOENT",+ syscall: "read",+ },+ });+ } finally {+ await resources.close();+ }+});++it.skipIf(process.platform === "win32")(+ "preserves Latin-1 bytes and a caller-selected properties symlink",+ async () => {+ const root = await createTestTempDirectory("rea-install-properties-");+ const path = join(root, "actual.properties");+ const selected = join(root, "selected.properties");+ const bytes = Buffer.concat([+ Buffer.from(properties),+ Buffer.from("note=caf\xe9\n", "latin1"),+ ]);+ await writeFile(path, bytes);+ await symlink(path, selected);+ const resources = createInspectionResources();+ try {+ expect(+ await readGhidraInstallationProperties(selected, {+ resourceOwner: resources.owner,+ }),+ ).toBe(bytes.toString("latin1"));+ expect(+ await readGhidraInstallationProperties(join(root, "absent"), {+ resourceOwner: resources.owner,+ }),+ ).toBeUndefined();+ } finally {+ await resources.close();+ }+ },+);++it.skipIf(process.platform === "win32")(+ "refuses a pipe without waiting for a writer",+ async () => {+ const root = await createTestTempDirectory("rea-install-properties-pipe-");+ const path = join(root, "application.properties");+ await promisify(execFile)("mkfifo", [path]);+ const resources = createInspectionResources();+ try {+ await expect(+ readGhidraInstallationProperties(path, {+ resourceOwner: resources.owner,+ }),+ ).rejects.toMatchObject({+ _tag: "ProviderAdapterError",+ diagnostics: {+ path,+ stage: "installation_properties",+ system_code: "ENOTFILE",+ },+ });+ } finally {+ await resources.close();+ }+ },+);++it("refuses an oversized descriptor before reading file bytes", async () => {+ const root = await createTestTempDirectory(+ "rea-install-properties-capacity-",+ );+ const path = join(root, "application.properties");+ await writeFile(path, properties);+ await truncate(path, MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES + 1);+ let reads = 0;+ controls.file = (handle, opened) => {+ if (opened === path) {+ const read = handle.read.bind(handle);+ vi.spyOn(handle, "read").mockImplementation(+ (...args: Parameters<typeof handle.read>) => {+ reads++;+ return read(...args);+ },+ );+ }+ };+ const resources = createInspectionResources();+ try {+ await expect(+ readGhidraInstallationProperties(path, {+ resourceOwner: resources.owner,+ }),+ ).rejects.toMatchObject({+ _tag: "AnalysisResourceConstraintError",+ resource: "file-size",+ retryable: false,+ reportedLimits: {+ maximum_bytes: MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES,+ observed_bytes: String(MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES + 1),+ },+ diagnostics: { path, stage: "installation_properties" },+ });+ expect(reads).toBe(0);+ } finally {+ await resources.close();+ }+});++it("does not open or adopt resources named by a pre-aborted opaque caller error", async () => {+ const resources = createInspectionResources();+ const reason = new ProviderCleanupError("foreign", ["caller-resource"], {+ reason: "caller metadata",+ });+ const controller = new AbortController();+ controller.abort(reason);+ let opens = 0;+ controls.file = () => {+ opens++;+ };+ try {+ await expect(+ readGhidraInstallationProperties("/selected/application.properties", {+ resourceOwner: resources.owner,+ signal: controller.signal,+ }),+ ).rejects.toMatchObject({ _tag: "AnalysisCancelledError", cause: reason });+ expect(opens).toBe(0);+ expect(reason.cleanupIncomplete).toBe(true);+ } finally {+ await resources.close();+ }+});++it.each(["read", "capacity", "completed"] as const)(+ "retains the exact descriptor and primary outcome across refused cleanup (%s)",+ async (outcome) => {+ const root = await createTestTempDirectory("rea-install-properties-retry-");+ const path = join(root, "application.properties");+ await writeFile(path, properties);+ if (outcome === "capacity")+ await truncate(path, MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES + 1);+ const resources = createInspectionResources();+ const controller = new AbortController();+ const reason = { request: "cancel final metadata close" };+ const physical = Object.assign(new Error("controlled metadata EIO"), {+ code: "EIO",+ });+ let denied = true,+ closes = 0;+ let closeActual: (() => Promise<void>) | undefined;+ controls.file = (handle, opened) => {+ if (opened !== path) return;+ controls.file = undefined;+ closeActual = handle.close.bind(handle);+ if (outcome === "read")+ vi.spyOn(handle, "read").mockRejectedValue(physical);+ vi.spyOn(handle, "close").mockImplementation(async () => {+ closes++;+ controller.abort(reason);+ if (denied) throw new Error("controlled metadata close refusal");+ await closeActual?.();+ });+ };+ try {+ const failure = await readGhidraInstallationProperties(path, {+ resourceOwner: resources.owner,+ signal: controller.signal,+ }).catch((cause: unknown) => cause);+ if (!(failure instanceof AnalysisError))+ throw new Error("Expected attributed failure");+ expect(failure.cleanupIncomplete).toBe(true);+ expect(failure.cleanupResources).toEqual([path]);+ await expect(resources.close()).rejects.toThrow();+ expect(closes).toBe(2);+ await rename(path, join(root, "retired.properties"));+ await writeFile(path, "application.version=replacement\n");+ let replacementOpens = 0;+ controls.file = () => {+ replacementOpens++;+ };+ denied = false;+ await resources.close();+ expect(closes).toBe(3);+ expect(replacementOpens).toBe(0);+ expect(failure.cleanupIncomplete).toBe(false);+ if (outcome === "completed") {+ expect(failure).toMatchObject({+ _tag: "AnalysisCancelledError",+ cause: reason,+ diagnostics: {+ completed_properties: {+ bytes: Buffer.byteLength(properties),+ properties: { providerVersion: "12.1.4" },+ },+ },+ });+ } else if (outcome === "capacity") {+ expect(projectAnalysisError(failure).code).toBe("resource_constraint");+ } else {+ expect(failure._tag).toBe("ProviderAdapterError");+ expect(failure.diagnostics).toMatchObject({ system_code: "EIO" });+ expect(JSON.stringify(failure.diagnostics)).toContain(+ "controlled metadata EIO",+ );+ }+ } finally {+ denied = false;+ await resources.close();+ await closeActual?.();+ }+ },+);++it.each(["replace", "grow", "shrink", "disappear"] as const)(+ "rejects metadata that changes during a descriptor read (%s)",+ async (change) => {+ const root = await createTestTempDirectory(+ "rea-install-properties-replace-",+ );+ const path = join(root, "application.properties");+ const replacement = join(root, "replacement");+ await writeFile(path, properties);+ await writeFile(replacement, properties);+ controls.file = (handle, opened) => {+ if (opened !== path) return;+ controls.file = undefined;+ const read = handle.read.bind(handle);+ vi.spyOn(handle, "read").mockImplementationOnce(+ async (...args: Parameters<typeof handle.read>) => {+ const result = await read(...args);+ if (change === "replace") await rename(replacement, path);+ else if (change === "disappear")+ await rename(path, join(root, "retired"));+ else if (change === "grow") await appendFile(path, "changed=true\n");+ else await truncate(path, 1);+ return result;+ },+ );+ };+ const resources = createInspectionResources();+ try {+ await expect(+ readGhidraInstallationProperties(path, {+ resourceOwner: resources.owner,+ }),+ ).rejects.toMatchObject({ _tag: "AnalysisArtifactChangedError", path });+ } finally {+ await resources.close();+ }+ },+);++it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(+ "reports a real metadata permission failure instead of missing installation",+ async () => {+ const root = await createTestTempDirectory(+ "rea-install-properties-permission-",+ );+ const path = join(root, "application.properties");+ await writeFile(path, properties);+ const resources = createInspectionResources();+ try {+ await chmod(path, 0o000);+ await expect(+ readGhidraInstallationProperties(path, {+ resourceOwner: resources.owner,+ }),+ ).rejects.toMatchObject({+ _tag: "AnalysisAccessDeniedError",+ path,+ systemCode: "EACCES",+ diagnostics: { path, stage: "installation_properties" },+ });+ } finally {+ await chmod(path, 0o600);+ await resources.close();+ }+ },+);diff --git a/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.ts b/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.tsindex 652d33b84..7d847495d 100644--- a/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.ts+++ b/tests/boundary/filesystem/ghidraProfileArtifactOwnership.test.ts@@ -8,7 +8,13 @@ import { ghidraProfileInstallationHost } from "../../../src/ghidra/GhidraInstallimport { silentLogger } from "../../../src/logger.js";import { createDeferred } from "../../fixtures/binarySession.js";import { STARTUP_OWNER_CLOSED } from "../../../src/process/SharedStartupAttempt.js";-import { readFile, rename, writeFile, type FileHandle } from "node:fs/promises";+import {+ readFile,+ rename,+ truncate,+ writeFile,+ type FileHandle,+} from "node:fs/promises";import { join } from "node:path";import { afterEach, expect, it, vi } from "vitest";import { ArtifactResourceScope } from "../../../src/artifacts/ArtifactResourceScope.js";@@ -16,6 +22,7 @@ import { parseConfig } from "../../../src/config/parseConfig.js";import {resolveGhidraAnalysisSeeds,snapshotGhidraAnalysisSeeds,+ MAX_GHIDRA_SEED_BYTES,} from "../../../src/ghidra/GhidraAnalysisSeeds.js";import {resolveGhidraExtensions,@@ -65,6 +72,39 @@ const configured = (return result.value;};+it("reports a seed extent over its resource budget without reading the payload", async () => {+ const root = await createTestTempDirectory("rea-profile-capacity-");+ const path = join(root, "seeds.tsv");+ await writeFile(path, "0x1000\tcode\n");+ await truncate(path, MAX_GHIDRA_SEED_BYTES + 1);+ let reads = 0;+ controls.file = (handle, opened) => {+ if (opened !== path) return;+ vi.spyOn(handle, "read").mockImplementation(async () => {+ reads++;+ throw new Error("Oversized input must not be read");+ });+ };+ const resources = new ArtifactResourceScope();+ try {+ expect(await resolveGhidraAnalysisSeeds(path, resources)).toMatchObject({+ ok: false,+ error: {+ _tag: "AnalysisResourceConstraintError",+ resource: "file-size",+ retryable: false,+ reportedLimits: {+ maximum_bytes: MAX_GHIDRA_SEED_BYTES,+ observed_bytes: String(MAX_GHIDRA_SEED_BYTES + 1),+ },+ },+ });+ expect(reads).toBe(0);+ } finally {+ await resources.close();+ }+});+it.each((["seed", "extension"] as const).flatMap((kind) =>[false, true].map((lateAbort) => ({ kind, lateAbort })),