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(dmg): classify localized verification failures safely
morlutof25c41b832ea
diff --git a/src/artifacts/NativeDmgArtifactReader.ts b/src/artifacts/NativeDmgArtifactReader.tsindex 93c12ece3..d8636f4ae 100644--- a/src/artifacts/NativeDmgArtifactReader.ts+++ b/src/artifacts/NativeDmgArtifactReader.ts@@ -1,4 +1,4 @@-import { mkdtemp, realpath, rm } from "node:fs/promises";+import { mkdtemp, realpath, rm, type FileHandle } from "node:fs/promises";import { tmpdir } from "node:os";import { basename, join } from "node:path";import type { Readable } from "node:stream";@@ -11,6 +11,12 @@ import {type ArtifactTraversalOptions,} from "./ArtifactReader.js";import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";+import {+ NonRegularFileReadError,+ RegularFileAdmissionFailure,+ openRegularFile,+} from "../filesystem/RegularFile.js";+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";import {execFileOutput,execFileOutputFailure,@@ -44,16 +50,24 @@ export interface NativeDmgHost {delay?(milliseconds: number): Promise<void>;}+interface NativeDmgFailureClassification {+ readonly reason: ArtifactReaderFailure["reason"];+ readonly verifyDiagnostic?: string;+ /**+ * hdiutil could not recognize the target, for a reason it reported only in+ * localized text; the cause stays unknown unless the target cannot be opened.+ */+ readonly unrecognizedImage?: boolean;+}+class NativeDmgCommandFailure extends ArtifactReaderFailure {readonly processNotStarted: boolean;readonly verifyDiagnostic: string | undefined;+ readonly unrecognizedImage: boolean;readonly exitCode: number | null;constructor(- failure: {- readonly reason: ArtifactReaderFailure["reason"];- readonly verifyDiagnostic?: string;- },+ failure: NativeDmgFailureClassification,message: string,readonly stdout: string,options?: {@@ -69,6 +83,7 @@ class NativeDmgCommandFailure extends ArtifactReaderFailure {);this.processNotStarted = options?.processNotStarted ?? false;this.verifyDiagnostic = failure.verifyDiagnostic;+ this.unrecognizedImage = failure.unrecognizedImage ?? false;this.exitCode = options?.exitCode ?? null;}}@@ -136,6 +151,7 @@ export class NativeDmgArtifactReader implements ArtifactReader {#closed = false;#closePromise: Promise<void> | undefined;readonly #activeDirectoryOperations = new Set<Promise<unknown>>();+ #verificationProbeHandle: OwnedFileHandle | undefined;constructor(private readonly path: string,@@ -207,6 +223,7 @@ export class NativeDmgArtifactReader implements ArtifactReader {async #closeOwnedResources(): Promise<void> {await this.#initialization?.catch(() => undefined);await Promise.allSettled(this.#activeDirectoryOperations);+ await this.#closeVerificationProbeHandle();await this.#closeMountedDirectory();let detachFailure = await this.#detachOwnedDevices();if (@@ -253,6 +270,23 @@ export class NativeDmgArtifactReader implements ArtifactReader {);}+ async #closeVerificationProbeHandle(): Promise<void> {+ const owner = this.#verificationProbeHandle;+ if (owner === undefined) return;+ try {+ await owner.close();+ this.#verificationProbeHandle = undefined;+ } catch (cause: unknown) {+ throw ArtifactReaderFailure.withCleanup(+ cause,+ ArtifactReaderFailure.cleanupObservation(+ cause,+ `DMG verification target descriptor ${this.path}`,+ ),+ );+ }+ }+async #detachOwnedDevices(): Promise<unknown> {let detachFailure = await this.#reconcileAttachState();let remainingDevices: string[] = [];@@ -455,13 +489,7 @@ export class NativeDmgArtifactReader implements ArtifactReader {const arguments_ = ["verify", this.path];const deadline = performance.now() + HDIUTIL_COMMAND_TIMEOUT_MS;for (let attempt = 0; ; attempt += 1) {- if (signal?.aborted === true)- throw new NativeDmgCommandFailure(- { reason: "cancelled" },- "DMG operation cancelled",- "",- { cause: signal.reason },- );+ this.#throwIfVerificationCancelled(signal);try {await runChecked(this.host, arguments_, signal, {timeoutMs: Math.max(1, Math.ceil(deadline - performance.now())),@@ -471,10 +499,28 @@ export class NativeDmgArtifactReader implements ArtifactReader {} catch (cause: unknown) {if (!(cause instanceof NativeDmgCommandFailure)) throw cause;this.#provenance.push(command(arguments_, ["read"], cause.exitCode));+ if (cause.unrecognizedImage) {+ const unreadable = await this.#isUnreadableTarget(signal, cause);+ this.#throwIfVerificationCancelled(signal);+ if (unreadable)+ throw new NativeDmgCommandFailure(+ { reason: "io" },+ cause.message,+ cause.stdout,+ {+ cause: cause.cause,+ ...(cause.exitCode === null+ ? {}+ : { exitCode: cause.exitCode }),+ },+ );+ }const delayMs = VERIFY_SETTLE_DELAYS_MS[attempt];- // Retry only the producer's explicit transient diagnostic, before any mount.+ // Retry only the producer's explicit transient diagnostic, or a localized+ // refusal of a readable target that may be the same, before any mount.if (- cause.verifyDiagnostic !== "Resource temporarily unavailable" ||+ (cause.verifyDiagnostic !== "Resource temporarily unavailable" &&+ !cause.unrecognizedImage) ||delayMs === undefined ||deadline - performance.now() <= delayMs)@@ -523,6 +569,72 @@ export class NativeDmgArtifactReader implements ArtifactReader {this.#devices = [];return "none";}++ #cancelledVerification(cause: unknown): NativeDmgCommandFailure {+ return new NativeDmgCommandFailure(+ { reason: "cancelled" },+ "DMG operation cancelled",+ "",+ { cause },+ );+ }++ #throwIfVerificationCancelled(signal: AbortSignal | undefined): void {+ if (signal?.aborted === true)+ throw this.#cancelledVerification(signal.reason);+ }++ async #isUnreadableTarget(+ signal: AbortSignal | undefined,+ primaryFailure: NativeDmgCommandFailure,+ ): Promise<boolean> {+ let handle: FileHandle;+ try {+ handle = await openRegularFile(this.path, {+ symlinks: "follow",+ ...(signal === undefined ? {} : { signal }),+ });+ } catch (cause: unknown) {+ if (cause instanceof RegularFileAdmissionFailure) {+ this.#verificationProbeHandle = cause.owner;+ const failure =+ signal?.aborted === true+ ? this.#cancelledVerification(signal.reason)+ : primaryFailure;+ throw ArtifactReaderFailure.withCleanup(+ failure,+ ArtifactReaderFailure.cleanupObservation(+ cause.cleanupCause,+ `DMG verification target descriptor ${this.path}`,+ ),+ );+ }+ if (signal?.aborted === true)+ throw this.#cancelledVerification(signal.reason);+ if (cause instanceof NonRegularFileReadError) return false;+ return classifyCommandFailure(cause, undefined).reason === "io";+ }++ const owner = new OwnedFileHandle(handle);+ this.#verificationProbeHandle = owner;+ try {+ await owner.close();+ this.#verificationProbeHandle = undefined;+ } catch (cause: unknown) {+ throw ArtifactReaderFailure.withCleanup(+ signal?.aborted === true+ ? this.#cancelledVerification(signal.reason)+ : primaryFailure,+ ArtifactReaderFailure.cleanupObservation(+ cause,+ `DMG verification target descriptor ${this.path}`,+ ),+ );+ }+ if (signal?.aborted === true)+ throw this.#cancelledVerification(signal.reason);+ return false;+ }}const failureMessage = (cause: unknown): string =>@@ -644,24 +756,17 @@ const processOutput = (cause: unknown, field: "stdout" | "stderr"): string => {const classifyCommandFailure = (cause: unknown,operation: string | undefined,-): {- readonly reason: ArtifactReaderFailure["reason"];- readonly verifyDiagnostic?: string;-} => {+): NativeDmgFailureClassification => {if (typeof cause !== "object" || cause === null)return { reason: "unavailable" };const code = Reflect.get(cause, "code");const exitCode = Reflect.get(cause, "exitCode");if (typeof code === "number" || typeof exitCode === "number") {if (operation !== "verify") return { reason: "unavailable" };- const diagnostic = verifyFailureDiagnostic(+ return classifyVerifyFailure(processOutput(cause, "stdout"),processOutput(cause, "stderr"),);- return {- reason: verifyFailureReason(diagnostic),- ...(diagnostic === undefined ? {} : { verifyDiagnostic: diagnostic }),- };}if (code === "ENOENT") {const syscall = Reflect.get(cause, "syscall");@@ -687,9 +792,26 @@ const classifyCommandFailure = (return { reason: "unavailable" };};+const classifyVerifyFailure = (+ stdout: string,+ stderr: string,+): NativeDmgFailureClassification => {+ const diagnostic = verifyFailureDiagnostic(stdout, stderr);+ const reason = verifyFailureReason(diagnostic);+ const untranslated =+ reason === undefined+ ? untranslatedVerifyFailure(stdout, stderr)+ : undefined;+ return {+ ...untranslated,+ reason: reason ?? untranslated?.reason ?? "unavailable",+ ...(diagnostic === undefined ? {} : { verifyDiagnostic: diagnostic }),+ };+};+const verifyFailureReason = (diagnostic: string | undefined,-): ArtifactReaderFailure["reason"] => {+): ArtifactReaderFailure["reason"] | undefined => {switch (diagnostic) {// hdiutil follows AppleLanguages, so en-GB and en-AU spell it "recognised".case "image not recognized":@@ -702,8 +824,10 @@ const verifyFailureReason = (case "Permission denied":case "Input/output error":return "io";- default:+ case "Resource temporarily unavailable":return "unavailable";+ default:+ return undefined;}};@@ -712,13 +836,33 @@ const verifyFailureDiagnostic = (stderr: string,): string | undefined => {const prefix = "hdiutil: verify failed - ";- return `${stdout}\n${stderr}`- .split(/\r?\n/u)- .map((line) => line.trim())+ return outputLines(stdout, stderr).find((line) => line.startsWith(prefix))?.slice(prefix.length);};+// hdiutil localizes the trailing failure reason but not its own status lines.+const INVALID_CHECKSUM_LINE = /^hdiutil: verify: checksum of ".*" is INVALID$/u;+const UNRECOGNIZED_IMAGE_LINE =+ /^hdiutil: verify: unable to recognize ".*" as a disk image\./u;++const untranslatedVerifyFailure = (+ stdout: string,+ stderr: string,+): NativeDmgFailureClassification | undefined => {+ const lines = outputLines(stdout, stderr);+ if (lines.some((line) => INVALID_CHECKSUM_LINE.test(line)))+ return { reason: "integrity" };+ // Malformed, unreadable and transiently busy targets all produce this line;+ // only the localized reason distinguishes them, so the cause stays unknown.+ if (lines.some((line) => UNRECOGNIZED_IMAGE_LINE.test(line)))+ return { reason: "unavailable", unrecognizedImage: true };+ return undefined;+};++const outputLines = (stdout: string, stderr: string): string[] =>+ `${stdout}\n${stderr}`.split(/\r?\n/u).map((line) => line.trim());+const command = (arguments_: readonly string[],effects: ArtifactCommand["effects"],diff --git a/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts b/tests/boundary/providers/native/nativeDmgArtifactReader.test.tsindex 72d11abec..8ac69daae 100644--- a/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts+++ b/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts@@ -21,6 +21,7 @@ import {} from "../../../../src/artifacts/ArtifactReader.js";import { ArtifactResourceScope } from "../../../../src/artifacts/ArtifactResourceScope.js";import { DirectoryArtifactReader } from "../../../../src/artifacts/DirectoryArtifactReader.js";+import { OwnedFileHandle } from "../../../../src/filesystem/OwnedFileHandle.js";import {NativeDmgArtifactReader,type NativeDmgHost,@@ -1344,6 +1345,194 @@ describe("native DMG verification resource availability", () => {});});+// Captured from hdiutil with AppleLanguages set to es-419.+const localizedImageRefusal = (path: string, reason: string) => ({+ stdout: "",+ stderr: `hdiutil: verify: unable to recognize ${JSON.stringify(path)} as a disk image. (${reason})\nhdiutil: verify failed - ${reason}\n`,+ exitCode: 1,+});++describe("native DMG localized verification diagnostics", () => {+ it("classifies a localized checksum mismatch from the untranslated status line", async () => {+ const run = vi.fn(async () => ({+ stdout: "",+ stderr:+ 'Calculando suma de disco entero (partición desconocida: 0)…\ndisco entero (partición desconocida:: calculado CRC32 $3816B077, esperado CRC32 $A738EA1C\nhdiutil: verify: checksum of "/tmp/image.dmg" is INVALID\nhdiutil: verify failed - suma no válida\n',+ exitCode: 1,+ }));+ await expect(+ createAttachedReader("/tmp/image.dmg", process.env, undefined, { run }),+ ).rejects.toMatchObject({+ reason: "integrity",+ message: expect.stringContaining("suma no válida"),+ });+ expect(run).toHaveBeenCalledTimes(1);+ });++ it.each([+ ["a malformed image", "imagen no reconocida"],+ ["a transiently busy image", "Recurso no disponible temporalmente"],+ ])(+ "keeps a localized refusal of a readable target unknown and retries it like %s could be",+ async (_target, reason) => {+ const root = await createTestTempDirectory("rea-localized-dmg-readable-");+ const path = join(root, "image.dmg");+ await writeFile(path, "This may or may not be a disk image.\n");+ const run = vi.fn(async () => localizedImageRefusal(path, reason));+ const delay = vi.fn(async () => {});+ const reader = new NativeDmgArtifactReader(path, process.env, {+ run,+ delay,+ });+ await expect(entryPaths(reader)).rejects.toMatchObject({+ reason: "unavailable",+ message: expect.stringContaining(reason),+ });+ await reader.close();+ expect(run.mock.calls).toHaveLength(3);+ expect(delay.mock.calls).toEqual([[250], [500]]);+ expect(reader.provenance().map(({ exit_code }) => exit_code)).toEqual([+ 1, 1, 1,+ ]);+ },+ );++ it("attaches after a localized transient refusal clears", async () => {+ const { host, state } = createOmittedInventoryHost();+ state.inventoryMode = "listed";+ state.detachAttempts = 4;+ const root = await createTestTempDirectory("rea-localized-dmg-transient-");+ const path = join(root, "image.dmg");+ await writeFile(path, "A disk image that is briefly busy.\n");+ let attempts = 0;+ const reader = await createAttachedReader(path, process.env, undefined, {+ ...host,+ delay: async () => {},+ async run(arguments_, signal, options) {+ if (arguments_[0] === "verify") {+ attempts += 1;+ if (attempts === 1)+ return localizedImageRefusal(+ path,+ "Recurso no disponible temporalmente",+ );+ }+ return host.run(arguments_, signal, options);+ },+ });+ onTestFinished(() => reader.close());+ expect(attempts).toBe(2);+ await reader.close();+ expect(state.attached).toBe(false);+ });++ it("classifies a localized refusal of a missing target as an I/O failure", async () => {+ const root = await createTestTempDirectory("rea-localized-dmg-io-");+ const path = join(root, "missing.dmg");+ const run = vi.fn(async () =>+ localizedImageRefusal(path, "No existe este archivo o directorio"),+ );+ const delay = vi.fn(async () => {});+ await expect(+ createAttachedReader(path, process.env, undefined, { run, delay }),+ ).rejects.toMatchObject({+ reason: "io",+ message: expect.stringContaining("No existe este archivo o directorio"),+ });+ expect(run).toHaveBeenCalledTimes(1);+ expect(delay).not.toHaveBeenCalled();+ });++ it.skipIf(process.platform === "win32")(+ "does not block on a target replaced by a named pipe",+ async () => {+ const root = await createTestTempDirectory("rea-localized-dmg-fifo-");+ const path = join(root, "image.dmg");+ await execFileOutput("mkfifo", [path]);+ const run = vi.fn(async () =>+ localizedImageRefusal(path, "imagen no reconocida"),+ );+ await expect(+ createAttachedReader(path, process.env, undefined, {+ run,+ delay: async () => {},+ }),+ ).rejects.toMatchObject({ reason: "unavailable" });+ expect(run).toHaveBeenCalledTimes(3);+ },+ 10_000,+ );++ it("keeps a localized failure without an untranslated status line unavailable", async () => {+ const run = vi.fn(async () => ({+ stdout: "",+ stderr: "hdiutil: verify failed - error desconocido\n",+ exitCode: 1,+ }));+ await expect(+ createAttachedReader("/tmp/image.dmg", process.env, undefined, { run }),+ ).rejects.toMatchObject({ reason: "unavailable" });+ });+});++describe("native DMG localized verification cleanup", () => {+ it("preserves cancellation that arrives before the localized target probe", async () => {+ const root = await createTestTempDirectory("rea-localized-dmg-cancel-");+ const path = join(root, "image.dmg");+ await writeFile(+ path,+ "Readable target; hdiutil refusal remains ambiguous.\n",+ );+ const controller = new AbortController();+ const run = vi.fn(async () => {+ controller.abort(new Error("cancel localized verification"));+ return localizedImageRefusal(path, "Recurso no disponible temporalmente");+ });+ const delay = vi.fn(async () => {});+ await expect(+ createAttachedReader(path, process.env, controller.signal, {+ run,+ delay,+ }),+ ).rejects.toMatchObject({ reason: "cancelled" });+ expect(run).toHaveBeenCalledTimes(1);+ expect(delay).not.toHaveBeenCalled();+ });++ it("retains a failed verification-probe close for reader cleanup", async () => {+ const root = await createTestTempDirectory("rea-localized-dmg-close-");+ const path = join(root, "image.dmg");+ await writeFile(+ path,+ "Readable target; hdiutil refusal remains ambiguous.\n",+ );+ const close = vi+ .spyOn(OwnedFileHandle.prototype, "close")+ .mockImplementationOnce(() =>+ Promise.reject(new Error("injected probe descriptor close failure")),+ );+ try {+ const reader = new NativeDmgArtifactReader(path, process.env, {+ run: async () => localizedImageRefusal(path, "imagen no reconocida"),+ delay: async () => {},+ });+ await expect(entryPaths(reader)).rejects.toMatchObject({+ reason: "unavailable",+ message: expect.stringContaining("imagen no reconocida"),+ cleanup: {+ resources: expect.arrayContaining([+ `DMG verification target descriptor ${path}`,+ ]),+ },+ });+ await reader.close();+ expect(close).toHaveBeenCalledTimes(2);+ } finally {+ close.mockRestore();+ }+ });+});+describe("native DMG real verification diagnostics", () => {it.skipIf(process.platform !== "darwin")("classifies a real hdiutil verify refusal as a format failure with captured output",@@ -1356,7 +1545,13 @@ describe("native DMG real verification diagnostics", () => {);expect(failure).toBeInstanceOf(ArtifactReaderFailure);if (!(failure instanceof ArtifactReaderFailure)) return;- expect(failure.reason).toBe("format");+ // Only English output establishes the cause; a localized reason for a+ // readable target stays unknown (see the localized diagnostics suite).+ expect(failure.reason).toBe(+ /verify failed - image not recogni[sz]ed/u.test(failure.message)+ ? "format"+ : "unavailable",+ );expect(failure.message).toContain('"command":"/usr/bin/hdiutil"');expect(failure.message).toContain('"arguments":["verify"');expect(failure.message).toContain('"exitCode":1');@@ -1374,10 +1569,9 @@ describe("native DMG real verification diagnostics", () => {await writeFile(unreadablePath, "not a disk image\n");await chmod(unreadablePath, 0);try {- for (const [path, expectedDiagnostic] of [- [missingPath, "No such file or directory"],- [unreadablePath, "Permission denied"],- ] as const) {+ for (const path of [missingPath, unreadablePath]) {+ // hdiutil localizes the errno text, but not its own status line.+ const expectedDiagnostic = `hdiutil: verify: unable to recognize ${JSON.stringify(path)} as a disk image.`;const failure = await createAttachedReader(path, process.env).catch((cause: unknown) => cause,);@@ -1388,7 +1582,7 @@ describe("native DMG real verification diagnostics", () => {expect(failure.message).toContain('"arguments":["verify"');expect(failure.message).toContain('"exitCode":1');expect(failure.message).toContain('"stdout":""');- expect(failure.message).toContain(expectedDiagnostic);+ expect(failure.message).toContain("unable to recognize");expect(failure.cause).toBeInstanceOf(Error);if (!(failure.cause instanceof Error)) continue;expect(Reflect.get(failure.cause, "code")).toBe(1);@@ -1459,9 +1653,9 @@ describe("native DMG real verification diagnostics", () => {expect(failure.message).toContain('"command":"/usr/bin/hdiutil"');expect(failure.message).toContain('"arguments":["verify"');expect(failure.message).toContain('"exitCode":1');- expect(failure.message).toContain("calculated CRC32");- expect(failure.message).toContain("expected CRC32");- expect(failure.message).toContain("verify failed - invalid checksum");+ // hdiutil localizes the CRC labels and failure reason, but not this status line.+ expect(failure.message).toContain("CRC32");+ expect(failure.message).toContain("is INVALID");expect(failure.cause).toBeInstanceOf(Error);if (!(failure.cause instanceof Error)) return;expect(Reflect.get(failure.cause, "code")).toBe(1);