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(native): retain Apple dispatch metadata descriptor cleanup ownership (#4745)
Kaoru082295b561f2e9af
diff --git a/scripts/verify/apple/dispatch.mjs b/scripts/verify/apple/dispatch.mjsindex 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.tsindex 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.tsindex 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.okdiff --git a/tests/boundary/providers/native/nativeDispatchMetadataFileCleanup.test.ts b/tests/boundary/providers/native/nativeDispatchMetadataFileCleanup.test.tsnew file mode 100644index 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);+});