Skip to content

armgit / rea

Public Imported from GitHub
0

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

fix(native): retain Apple dispatch metadata descriptor cleanup ownership (#4745)

Kaoru082295b561f2e9af
diff --git a/scripts/verify/apple/dispatch.mjs b/scripts/verify/apple/dispatch.mjs
index 2378ae335..cd222e0a5 100644
--- a/scripts/verify/apple/dispatch.mjs
+++ b/scripts/verify/apple/dispatch.mjs
@@ -6,6 +6,7 @@ import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
import { parseBinaryTarget } from "../../../dist/application/BinaryTargetResolver.js";
+import { ArtifactResourceScope } from "../../../dist/artifacts/ArtifactResourceScope.js";
import { inspectAppleDispatchMetadata } from "../../../dist/native/AppleDispatchMetadata.js";
import {
artifactCliEvidence,
@@ -52,10 +53,20 @@ const fixupCoverage = (metadata) =>
const inspect = async (path) => {
const target = await parseBinaryTarget(path);
if (!target.ok) throw target.error;
- return {
- target: target.value,
- metadata: (await inspectAppleDispatchMetadata(target.value, 5000)).result,
- };
+ const resources = new ArtifactResourceScope();
+ try {
+ return {
+ target: target.value,
+ metadata: (
+ await resources.run(() =>
+ inspectAppleDispatchMetadata(target.value, 5000, resources),
+ )
+ ).result,
+ };
+ } finally {
+ // Retry any descriptor whose close failed, surfacing unresolved cleanup.
+ await resources.close();
+ }
};
const checkObjc = (metadata, mode) => {
diff --git a/src/native/AppleDispatchMetadata.ts b/src/native/AppleDispatchMetadata.ts
index dfc5aec6a..641fee400 100644
--- a/src/native/AppleDispatchMetadata.ts
+++ b/src/native/AppleDispatchMetadata.ts
@@ -10,9 +10,23 @@ import {
} from "../domain/binaryTargetTypes.js";
import {
AnalysisCancelledError,
+ AnalysisCapabilityUnavailableError,
AnalysisResourceConstraintError,
} from "../domain/analysisErrorCore.js";
-import { openRegularFile } from "../filesystem/RegularFile.js";
+import {
+ ArtifactFileCleanupFailure,
+ artifactFileCancellationCause,
+ artifactFilePrimaryFailure,
+ bindArtifactFileCleanup,
+ withArtifactRegularFile,
+} from "../artifacts/ArtifactFileOperation.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { NATIVE_MACOS_PROVIDER_IDENTITY as IDENTITY } from "./NativeMacOSProviderMetadata.js";
import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
import { pushDispatchCoverage } from "./AppleDispatchCoverage.js";
@@ -180,10 +194,14 @@ export const decodeAppleDispatchMetadata = (
return objcSwiftMetadataSchema.parse(result);
};
-/** Read digest-verified target bytes under a 64 MiB static metadata budget. */
+/**
+ * Read digest-verified target bytes under a 64 MiB static metadata budget.
+ * The caller's scope retains the target descriptor when its final close fails.
+ */
export const inspectAppleDispatchMetadata = async (
target: BinaryTarget,
maxRecords: number,
+ resources: ArtifactResourceScope,
signal?: AbortSignal,
) => {
if (target.kind !== "executable" || !isMachOFormat(target.format))
@@ -196,38 +214,105 @@ export const inspectAppleDispatchMetadata = async (
"Apple static metadata input exceeds its 64 MiB snapshot budget",
{ input_bytes: maximumBytes },
);
- const handle = await openRegularFile(target.path, {
- symlinks: "reject",
+ const cancelled = () =>
+ new AnalysisCancelledError("inspect_native_dispatch_metadata", {
+ cause: signal?.reason,
+ });
+ const { bytes, digest } = await withArtifactRegularFile(
+ target.path,
+ resources,
signal,
+ async (handle) => {
+ const before = await handle.stat();
+ if (before.size > maximumBytes) throw capacityError();
+ if (signal?.aborted) throw cancelled();
+ const read = await readBoundedFileBytes(
+ handle,
+ maximumBytes,
+ signal,
+ ).catch((cause: unknown) => {
+ // The bounded reader rejects with the caller's exact abort reason.
+ if (signal?.aborted === true && cause === signal.reason)
+ throw cancelled();
+ throw cause;
+ });
+ if (read === undefined) throw capacityError();
+ const sha256 = createHash("sha256").update(read).digest("hex");
+ if (sha256 !== target.sha256)
+ throw new EvidenceIntegrityError(
+ "Apple metadata target digest changed after session binding",
+ );
+ return { bytes: read, digest: sha256 };
+ },
+ "reject",
+ );
+ return nativeDispatchMetadataResultSchema.parse({
+ target_sha256: target.sha256,
+ provider: {
+ id: "native-macos",
+ name: "macOS native inspection utilities",
+ version: "apple-metadata-reader-1",
+ },
+ analysis_profile_digest: null,
+ result: decodeAppleDispatchMetadata(
+ bytes,
+ maxRecords,
+ { path: target.path, sha256: digest },
+ target.architecture,
+ ),
});
- try {
- const before = await handle.stat();
- if (before.size > maximumBytes) throw capacityError();
- if (signal?.aborted)
- throw new AnalysisCancelledError("inspect_native_dispatch_metadata");
- const bytes = await readBoundedFileBytes(handle, maximumBytes, signal);
- if (bytes === undefined) throw capacityError();
- const digest = createHash("sha256").update(bytes).digest("hex");
- if (digest !== target.sha256)
- throw new EvidenceIntegrityError(
- "Apple metadata target digest changed after session binding",
- );
- return nativeDispatchMetadataResultSchema.parse({
- target_sha256: target.sha256,
- provider: {
- id: "native-macos",
- name: "macOS native inspection utilities",
- version: "apple-metadata-reader-1",
+};
+
+const OPERATION = "inspect_native_dispatch_metadata";
+
+/** Translate the owned target read, keeping a failed close beside its physical outcome. */
+export const appleDispatchMetadataFailure = (
+ cause: unknown,
+ path: string,
+): AnalysisError => {
+ if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined) {
+ const physical =
+ cause instanceof ArtifactFileCleanupFailure
+ ? cause.fileCleanupFailure
+ : undefined;
+ const previous =
+ physical?.outcome.kind === "failed"
+ ? appleDispatchMetadataFailure(artifactFilePrimaryFailure(cause), path)
+ : physical?.completionCancellation === undefined
+ ? undefined
+ : new AnalysisCancelledError(OPERATION, {
+ cause: physical.completionCancellation.reason,
+ });
+ const failure = new ProviderCleanupError(
+ IDENTITY.id,
+ cause.cleanup.resources,
+ {
+ reason: cause.cleanup.reason,
+ previous_error:
+ previous === undefined ? null : projectAnalysisError(previous),
},
- analysis_profile_digest: null,
- result: decodeAppleDispatchMetadata(
- bytes,
- maxRecords,
- { path: target.path, sha256: digest },
- target.architecture,
- ),
- });
- } finally {
- await handle.close();
+ { operation: OPERATION, cause, cleanupPrimary: previous },
+ );
+ bindArtifactFileCleanup(cause, failure);
+ return failure;
}
+ if (cause instanceof AnalysisError) return cause;
+ if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled")
+ return new AnalysisCancelledError(OPERATION, {
+ cause: artifactFileCancellationCause(cause),
+ });
+ if (cause instanceof ArtifactReaderFailure && cause.reason === "unavailable")
+ return new AnalysisCapabilityUnavailableError(
+ IDENTITY.id,
+ OPERATION,
+ cause.message,
+ { cause },
+ );
+ return new ProviderAdapterError(IDENTITY.id, OPERATION, {
+ cause,
+ diagnostics: {
+ target_path: path,
+ reason: cause instanceof Error ? cause.message : String(cause),
+ },
+ });
};
diff --git a/src/native/NativeMacOSProvider.ts b/src/native/NativeMacOSProvider.ts
index 341e6c77d..69eb4a541 100644
--- a/src/native/NativeMacOSProvider.ts
+++ b/src/native/NativeMacOSProvider.ts
@@ -10,7 +10,10 @@ import {
NATIVE_MACOS_PROVIDER_IDENTITY as IDENTITY,
nativeMacOSCapabilities,
} from "./NativeMacOSProviderMetadata.js";
-import { inspectAppleDispatchMetadata } from "./AppleDispatchMetadata.js";
+import {
+ appleDispatchMetadataFailure,
+ inspectAppleDispatchMetadata,
+} from "./AppleDispatchMetadata.js";
import {
observeNativeUi,
finishNativeUiObservation,
@@ -57,7 +60,6 @@ import {
AnalysisError,
resolvedAnalysisError,
} from "../domain/analysisErrorBase.js";
-import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
import type { NativeUiObservationResult } from "../domain/native/nativeUiObservation.js";
import {
@@ -161,6 +163,7 @@ class NativeMacOSClient implements AnalysisClient {
readonly #signatureResources = new ArtifactResourceScope();
readonly #plistResources = new ArtifactResourceScope();
readonly #callResources = new ArtifactResourceScope();
+ readonly #dispatchResources = new ArtifactResourceScope();
#nativeUiTail: Promise<void> = Promise.resolve();
#closed = false;
@@ -215,10 +218,13 @@ class NativeMacOSClient implements AnalysisClient {
),
);
try {
- const result = await inspectAppleDispatchMetadata(
- this.target,
- input.data.max_records,
- options?.signal,
+ const result = await this.#dispatchResources.run(() =>
+ inspectAppleDispatchMetadata(
+ this.target,
+ input.data.max_records,
+ this.#dispatchResources,
+ options?.signal,
+ ),
);
return ok(
createAnalysisExecution(result, result.provider, {
@@ -229,26 +235,7 @@ class NativeMacOSClient implements AnalysisClient {
}),
);
} catch (cause) {
- if (cause instanceof AnalysisError) return err(cause);
- const cancellation = regularFileCancellation(cause);
- if (cancellation !== undefined)
- return err(
- new AnalysisCancelledError(operation, {
- cause: cancellation.reason,
- }),
- );
- return err(
- options?.signal?.aborted
- ? new AnalysisCancelledError(operation)
- : new ProviderAdapterError(IDENTITY.id, operation, {
- cause,
- diagnostics: {
- target_path: this.target.path,
- reason:
- cause instanceof Error ? cause.message : String(cause),
- },
- }),
- );
+ return err(appleDispatchMetadataFailure(cause, this.target.path));
}
}
if (!isNativeOperation(operation))
@@ -319,6 +306,10 @@ class NativeMacOSClient implements AnalysisClient {
this.#callResources,
"native-call-target",
);
+ const dispatchCleanup = await closeNativeFileScope(
+ this.#dispatchResources,
+ "native-dispatch-metadata-target",
+ );
const commandCleanup = await this.#retryNativeCommandCleanup();
let result = await this.tracer.close();
const cleanupErrors = [
@@ -329,6 +320,7 @@ class NativeMacOSClient implements AnalysisClient {
...(signatureCleanup === undefined ? [] : [signatureCleanup]),
...(plistCleanup === undefined ? [] : [plistCleanup]),
...(callCleanup === undefined ? [] : [callCleanup]),
+ ...(dispatchCleanup === undefined ? [] : [dispatchCleanup]),
];
for (const cleanupError of cleanupErrors)
result = result.ok
diff --git a/tests/boundary/providers/native/nativeDispatchMetadataFileCleanup.test.ts b/tests/boundary/providers/native/nativeDispatchMetadataFileCleanup.test.ts
new file mode 100644
index 000000000..5d973d218
--- /dev/null
+++ b/tests/boundary/providers/native/nativeDispatchMetadataFileCleanup.test.ts
@@ -0,0 +1,92 @@
+import { open, writeFile, type FileHandle } from "node:fs/promises";
+import { join } from "node:path";
+import { expect, it, onTestFinished, vi } from "vitest";
+import { ProviderCleanupError } from "../../../../src/domain/providerCleanupError.js";
+import { NativeMacOSProvider } from "../../../../src/native/NativeMacOSProvider.js";
+import {
+ NativeFixtureRunner,
+ nativeMachoTarget,
+ nativeMachoTargetForFile,
+} from "../../../fixtures/nativeCommands.js";
+import { createTestTempDirectory } from "../../../fixtures/temporaryDirectory.js";
+
+/** Open a real target and make only its admitted descriptor's close reject until released. */
+const fixture = async (bindActualDigest: boolean) => {
+ const root = await createTestTempDirectory("rea-native-dispatch-close-");
+ const path = join(root, "fixture.macho");
+ await writeFile(path, "bound target bytes");
+ const probe = await open(path, "r");
+ const prototype = Object.getPrototypeOf(probe) as FileHandle;
+ await probe.close();
+ const target = bindActualDigest
+ ? await nativeMachoTargetForFile(path)
+ : nativeMachoTarget(path);
+ const client = new NativeMacOSProvider(
+ {},
+ new NativeFixtureRunner({}),
+ "darwin",
+ ).createClient(target);
+ const state = { failing: true, attempts: 0 };
+ let release: (() => Promise<void>) | undefined;
+ const original = prototype.stat;
+ const stat = vi
+ .spyOn(prototype, "stat")
+ .mockImplementationOnce(async function (
+ this: FileHandle,
+ ...args: Parameters<FileHandle["stat"]>
+ ) {
+ release = this.close.bind(this);
+ this.close = async () => {
+ state.attempts += 1;
+ if (state.failing) throw new Error("dispatch target close failed");
+ await release!();
+ };
+ return Reflect.apply(original, this, args);
+ });
+ onTestFinished(async () => {
+ stat.mockRestore();
+ state.failing = false;
+ await client.close();
+ });
+ return { client, path, state };
+};
+
+it("keeps the integrity failure primary and retains the target descriptor when close rejects", async () => {
+ const { client, path, state } = await fixture(false);
+
+ const result = await client.execute("inspect_native_dispatch_metadata", {});
+ expect(result.ok).toBe(false);
+ if (result.ok) throw new Error("Expected integrity and close failures");
+ expect(result.error.cleanupIncomplete).toBe(true);
+ expect(result.error.cleanupResources).toEqual([path]);
+ expect(result.error.cleanupPrimary?._tag).toBe("EvidenceIntegrityError");
+ expect(state.attempts).toBe(1);
+
+ // Client close retries the exact retained descriptor without reopening it.
+ const held = await client.close();
+ expect(held.ok).toBe(false);
+ expect(state.attempts).toBe(2);
+ expect(result.error.cleanupIncomplete).toBe(true);
+
+ state.failing = false;
+ expect((await client.close()).ok).toBe(true);
+ expect(state.attempts).toBe(3);
+ expect(result.error.cleanupIncomplete).toBe(false);
+});
+
+it("reports a completed read whose close rejects as retained cleanup", async () => {
+ const { client, path, state } = await fixture(true);
+
+ const result = await client.execute("inspect_native_dispatch_metadata", {});
+ expect(result.ok).toBe(false);
+ if (result.ok) throw new Error("Expected the close failure");
+ expect(result.error).toBeInstanceOf(ProviderCleanupError);
+ expect(result.error.cleanupIncomplete).toBe(true);
+ expect(result.error.cleanupResources).toEqual([path]);
+ expect(result.error.cleanupPrimary).toBeUndefined();
+
+ state.failing = false;
+ expect((await client.close()).ok).toBe(true);
+ expect(state.attempts).toBe(2);
+ expect(result.error.cleanupIncomplete).toBe(false);
+});