import { mkdtemp, realpath, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import { basename, join } from "node:path"; import type { Readable } from "node:stream"; import { parse } from "plist"; import { z } from "zod"; import type { ArtifactCommand } from "../domain/artifactGraph.js"; import { ArtifactReaderFailure, type ArtifactEntry, type ArtifactReader, } from "./ArtifactReader.js"; import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js"; import { execFileOutput } from "../process/ExecFileOutput.js"; const DETACH_TIMEOUT_MS = 120_000; const attachOutputSchema = z.object({ "system-entities": z.array( z.object({ "dev-entry": z.string().startsWith("/dev/"), "mount-point": z.string().optional(), }), ), }); const infoOutputSchema = z.object({ images: z.array( z.object({ "system-entities": z.array(z.object({ "dev-entry": z.string() })), }), ), }); /** Narrow host seam for tested, shell-free hdiutil lifecycle operations. */ export interface NativeDmgHost { run( arguments_: readonly string[], signal?: AbortSignal, options?: { readonly timeoutMs: number }, ): Promise<{ readonly stdout: string; readonly stderr?: string; readonly exitCode: number; readonly cause?: unknown; }>; } const systemHost: NativeDmgHost = { async run(arguments_, signal, options) { try { const { stdout, stderr } = await execFileOutput( "/usr/bin/hdiutil", [...arguments_], { ...(options === undefined ? {} : { timeout: options.timeoutMs }), ...(signal === undefined ? {} : { signal }), }, ); return { stdout, stderr, exitCode: 0 }; } catch (cause: unknown) { if (cause instanceof Error && cause.name === "AbortError") throw new ArtifactReaderFailure("cancelled", "DMG operation cancelled"); const exitCode = processExitCode(cause); if (exitCode !== undefined) return { stdout: processOutput(cause, "stdout"), stderr: processOutput(cause, "stderr"), exitCode, cause, }; throw new ArtifactReaderFailure( commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, { cause }, ); } }, }; /** Read-only macOS DMG adapter that owns attachment and reverse-order detach. */ export class NativeDmgArtifactReader implements ArtifactReader { readonly format = "file" as const; readonly #provenance: ArtifactCommand[] = []; #directory: DirectoryArtifactReader | undefined; #devices: string[] = []; #mountRoot: string | undefined; private constructor( private readonly path: string, private readonly host: NativeDmgHost, ) {} /** Verify and attach one image beneath an exclusively owned temporary root. */ static async create( path: string, signal?: AbortSignal, host: NativeDmgHost = systemHost, ): Promise { if (process.platform !== "darwin" && host === systemHost) throw new ArtifactReaderFailure( "unavailable", "Native DMG traversal is available only on macOS", ); const reader = new NativeDmgArtifactReader(path, host); await reader.attach(signal); return reader; } async *entries(signal?: AbortSignal): AsyncIterable { if (this.#directory === undefined) throw new ArtifactReaderFailure("unavailable", "DMG is not attached"); const prefix = basename(this.path); for await (const entry of this.#directory.entries(signal)) yield { ...entry, path: `${prefix}/${entry.path}` }; } open(entry: ArtifactEntry, signal?: AbortSignal): Promise { if (this.#directory === undefined) return Promise.reject( new ArtifactReaderFailure("unavailable", "DMG is not attached"), ); return this.#directory.open(entry, signal); } provenance(): readonly ArtifactCommand[] { return structuredClone(this.#provenance); } async close(): Promise { let detachFailure: unknown; const remainingDevices: string[] = []; for (const device of [...this.#devices].reverse()) { try { await runChecked(this.host, ["detach", device], undefined, { timeoutMs: DETACH_TIMEOUT_MS, }); this.#provenance.push(command(["detach", device], ["mount"])); } catch (cause: unknown) { // Detaching a synthesized APFS container also ejects the image that // backs it, so a later whole disk of the same image may already be // gone. Only a device that is still attached is a cleanup failure. if (await this.#isAttached(device)) { remainingDevices.push(device); detachFailure ??= cause; } } } this.#devices = remainingDevices.reverse(); if (this.#devices.length === 0 && this.#mountRoot !== undefined) await rm(this.#mountRoot, { recursive: true, force: true }).then( () => { this.#mountRoot = undefined; this.#directory = undefined; }, (cause: unknown) => { detachFailure ??= cause; }, ); if (detachFailure !== undefined) throw new ArtifactReaderFailure( "unavailable", `DMG detach or mount-root cleanup failed for ${JSON.stringify(this.path)}: ${failureMessage(detachFailure)}`, { cause: detachFailure }, ); } /** * Report whether hdiutil still lists a device; unknown state counts as * attached. Like detach, this cleanup query runs after the inventory * snapshot has captured provenance, so it is not recorded there. */ async #isAttached(device: string): Promise { try { const info = await runChecked(this.host, ["info", "-plist"], undefined, { timeoutMs: DETACH_TIMEOUT_MS, }); const parsed = infoOutputSchema.parse(parse(info.stdout)); return parsed.images.some((image) => image["system-entities"].some( (entity) => entity["dev-entry"] === device, ), ); } catch { return true; } } async attach(signal?: AbortSignal): Promise { await runChecked(this.host, ["verify", this.path], signal); this.#provenance.push(command(["verify", this.path], ["read"])); this.#mountRoot = await realpath(await mkdtemp(join(tmpdir(), "rea-dmg-"))); try { const attached = await runChecked( this.host, [ "attach", "-readonly", "-nobrowse", "-plist", "-mountroot", this.#mountRoot, this.path, ], signal, ); const parsed = attachOutputSchema.parse(parse(attached.stdout)); const devices = [ ...new Set( parsed["system-entities"].map((entity) => entity["dev-entry"]), ), ]; // Detaching an observed whole disk also detaches its partitions. Do not // subsequently detach the now-unavailable child devices. this.#devices = devices.filter( (device) => !devices.some( (parent) => /^\/dev\/disk\d+$/u.test(parent) && device.startsWith(`${parent}s`) && /^\d+$/u.test(device.slice(parent.length + 1)), ), ); if (this.#devices.length === 0) throw new ArtifactReaderFailure( "format", "hdiutil returned no attached devices", ); for (const entity of parsed["system-entities"]) if ( entity["mount-point"] !== undefined && !entity["mount-point"].startsWith(`${this.#mountRoot}/`) ) throw new ArtifactReaderFailure( "path", "hdiutil mounted outside the owned root", ); this.#provenance.push( command( [ "attach", "-readonly", "-nobrowse", "-plist", "-mountroot", this.#mountRoot, this.path, ], ["read", "mount"], ), ); this.#directory = new DirectoryArtifactReader(this.#mountRoot); } catch (cause: unknown) { let cleanupFailure: unknown; try { await this.close(); } catch (cleanupCause: unknown) { cleanupFailure = cleanupCause; } if (cleanupFailure !== undefined) throw new ArtifactReaderFailure( "unavailable", `DMG attach failed and cleanup could not detach every device: ${failureMessage(cause)}; cleanup: ${failureMessage(cleanupFailure)}`, { cause: new AggregateError([cause, cleanupFailure]) }, ); throw cause; } } } const failureMessage = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause); const runChecked = async ( host: NativeDmgHost, arguments_: readonly string[], signal?: AbortSignal, options?: { readonly timeoutMs: number }, ): Promise<{ readonly stdout: string; readonly exitCode: 0 }> => { let result: Awaited>; try { result = await host.run(arguments_, signal, options); } catch (cause: unknown) { if (cause instanceof ArtifactReaderFailure) throw cause; if (cause instanceof Error && cause.name === "AbortError") throw new ArtifactReaderFailure("cancelled", "DMG operation cancelled", { cause, }); throw new ArtifactReaderFailure( commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure( cause, arguments_, )}`, { cause }, ); } if (result.exitCode !== 0) { const failure = { command: "/usr/bin/hdiutil", exitCode: result.exitCode, ...(result.cause === undefined ? {} : { code: processExitCode(result.cause) }), stdout: result.stdout, ...(result.stderr === undefined ? {} : { stderr: result.stderr }), }; const reason = commandFailureReason(failure, arguments_[0]); const details = describeCommandFailure(failure, arguments_); const unknownVerifyFailure = arguments_[0] === "verify" && reason === "unavailable"; throw new ArtifactReaderFailure( reason, unknownVerifyFailure ? `hdiutil verify failed; captured diagnostics do not establish the failure cause: ${details}` : `hdiutil ${arguments_[0] ?? "operation"} failed: ${details}`, result.cause === undefined ? undefined : { cause: result.cause }, ); } return { stdout: result.stdout, exitCode: 0 }; }; const describeCommandFailure = ( cause: unknown, arguments_: readonly string[], ): string => { const fields: Record = { command: "/usr/bin/hdiutil", arguments: [...arguments_], }; if (typeof cause === "object" && cause !== null) { for (const key of [ "code", "exitCode", "errno", "syscall", "signal", "stdout", "stderr", ] as const) { const value = Reflect.get(cause, key); if (typeof value === "string" || typeof value === "number") fields[key] = value; } const code = Reflect.get(cause, "code"); if (typeof code === "number") fields.exitCode = code; } if (cause instanceof ArtifactReaderFailure) fields.message = cause.message; else if (cause instanceof Error) fields.message = cause.message; return JSON.stringify(fields); }; const processExitCode = (cause: unknown): number | undefined => { if (typeof cause !== "object" || cause === null) return undefined; const exitCode = Reflect.get(cause, "exitCode"); if (typeof exitCode === "number") return exitCode; const code = Reflect.get(cause, "code"); return typeof code === "number" ? code : undefined; }; const processOutput = (cause: unknown, field: "stdout" | "stderr"): string => { if (typeof cause !== "object" || cause === null) return ""; const value = Reflect.get(cause, field); return typeof value === "string" ? value : ""; }; const commandFailureReason = ( cause: unknown, operation: string | undefined, ): ArtifactReaderFailure["reason"] => { if (typeof cause !== "object" || cause === null) return "unavailable"; const code = Reflect.get(cause, "code"); const exitCode = Reflect.get(cause, "exitCode"); if (typeof code === "number" || typeof exitCode === "number") return operation === "verify" ? verifyFailureReason(cause) : "unavailable"; if (code === "ENOENT") { const syscall = Reflect.get(cause, "syscall"); return typeof syscall === "string" && syscall.startsWith("spawn") ? "unavailable" : "io"; } if ( code === "EACCES" || code === "EPERM" || code === "EIO" || code === "ENOTDIR" || code === "EISDIR" || code === "ENODEV" || code === "EROFS" || code === "EMFILE" || code === "ENFILE" ) return "io"; return "unavailable"; }; const verifyFailureReason = ( cause: unknown, ): ArtifactReaderFailure["reason"] => { const diagnostic = verifyFailureDiagnostic( processOutput(cause, "stdout"), processOutput(cause, "stderr"), ); switch (diagnostic) { case "image not recognized": return "format"; case "invalid checksum": case "image data corrupted": return "integrity"; case "No such file or directory": case "Permission denied": case "Input/output error": return "io"; default: return "unavailable"; } }; const verifyFailureDiagnostic = ( stdout: string, stderr: string, ): string | undefined => { const prefix = "hdiutil: verify failed - "; return `${stdout}\n${stderr}` .split(/\r?\n/u) .map((line) => line.trim()) .find((line) => line.startsWith(prefix)) ?.slice(prefix.length); }; const command = ( arguments_: readonly string[], effects: ArtifactCommand["effects"], ): ArtifactCommand => ({ tool: "/usr/bin/hdiutil", arguments: [...arguments_], tool_version: null, executable_sha256: null, exit_code: 0, effects, });