diff --git a/docs/adb-device-analysis.md b/docs/adb-device-analysis.md index aa9e3e251..ee4dc6417 100644 --- a/docs/adb-device-analysis.md +++ b/docs/adb-device-analysis.md @@ -136,6 +136,12 @@ existing analysis families directly, for example - Pull and capture outputs are additive: the destination must not already exist. Re-running a completed pull refuses the existing directory instead of overwriting evidence. +- Cancellation during a package pull preserves caller-selected output. The + error includes partial observations identifying completed artifacts and the + interrupted local path; remaining APKs were not attempted. +- Failed package acquisition rollback retains its directory identity and retries + cleanup before later work and during shutdown. Cleanup refuses a replacement + directory. Terminal shutdown stops admission and drains active operations. - The provider holds no long-lived processes; every invocation is one bounded adb run. The adb server belongs to the caller. diff --git a/src/adb/AdbProvider.ts b/src/adb/AdbProvider.ts index 79a2acbc7..9e33404b9 100644 --- a/src/adb/AdbProvider.ts +++ b/src/adb/AdbProvider.ts @@ -1,6 +1,6 @@ import { execFile } from "node:child_process"; import { createHash } from "node:crypto"; -import { createReadStream, constants as fsConstants } from "node:fs"; +import { constants as fsConstants } from "node:fs"; import { access, lstat, mkdir, rm, stat, writeFile } from "node:fs/promises"; import { basename, join, resolve } from "node:path"; @@ -24,8 +24,11 @@ import { AnalysisTimeoutError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js"; -import type { AnalysisError } from "../domain/analysisErrorBase.js"; +import { AnalysisError } from "../domain/analysisErrorBase.js"; +import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; import { err, ok, type Result } from "../domain/result.js"; +import { hashStableFile } from "../filesystem/StableFileHash.js"; +import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { execFileOutput, execFileOutputFailure, @@ -97,11 +100,18 @@ const STDERR_EXCERPT_BYTES = 512; const UNPARSED_LINES_REPORTED = 10; const STOP_GRACE_MS = 5_000; -/** Stream a local file digest without retaining large files in memory. */ -const sha256File = async (path: string): Promise => { - const hash = createHash("sha256"); - for await (const chunk of createReadStream(path)) hash.update(chunk); - return hash.digest("hex"); +const hashAdbFile = async ( + path: string, + operation: string, + signal: AbortSignal | undefined, +) => { + try { + return await hashStableFile(path, signal); + } catch (cause: unknown) { + if (signal?.aborted === true) + throw new AnalysisCancelledError(operation, { cause }); + throw cause; + } }; /** adb joins shell operands into a remote POSIX command; quote at that boundary. */ @@ -335,6 +345,48 @@ export interface AdbProviderOptions { readonly environment?: Readonly>; } +interface PendingPackageDirectoryCleanup { + readonly path: string; + readonly identity: PackageDirectoryIdentity | undefined; + readonly primary: AnalysisError; + readonly remove: () => Promise; +} + +interface PackageDirectoryIdentity { + readonly dev: number; + readonly ino: number; + readonly mode: number; +} + +const removeOwnedPackageDirectory = async ( + path: string, + identity: PackageDirectoryIdentity | undefined, +): Promise => { + if (identity === undefined) + throw new Error( + `Cannot verify the created package directory identity; refusing to remove ${path}`, + ); + let current: Awaited>; + try { + current = await lstat(path); + } catch (cause: unknown) { + if (cause instanceof Error && Reflect.get(cause, "code") === "ENOENT") + return; + throw cause; + } + if ( + !current.isDirectory() || + current.isSymbolicLink() || + current.dev !== identity.dev || + current.ino !== identity.ino || + current.mode !== identity.mode + ) + throw new Error( + `The created package directory was replaced or changed; refusing to remove ${path}`, + ); + await rm(path, { recursive: true, force: true }); +}; + /** * ADB device inspection and acquisition over a caller-selected adb binary. * @@ -346,6 +398,12 @@ export interface AdbProviderOptions { */ export class AdbProvider { private readonly environment: Readonly>; + readonly #pendingPackageDirectoryCleanup = + new Set(); + readonly #activeOperations = new Set>(); + #closing = false; + #closePromise: Promise | undefined; + #packageCleanupPromise: Promise | undefined; constructor(options: AdbProviderOptions = {}) { this.environment = options.environment ?? process.env; @@ -378,12 +436,121 @@ export class AdbProvider { } } - /** The provider holds no long-lived resources; the adb server is caller-owned. */ - async close(): Promise {} + /** Retry removal of package directories retained after failed rollback. */ + close(): Promise { + this.#closing = true; + if (this.#closePromise !== undefined) return this.#closePromise; + const closing = (async () => { + await Promise.all(this.#activeOperations); + await this.#retryPackageDirectoryCleanup(); + })().finally(() => { + if (this.#closePromise === closing) this.#closePromise = undefined; + }); + this.#closePromise = closing; + return this.#closePromise; + } + + #retryPackageDirectoryCleanup(): Promise { + if (this.#packageCleanupPromise !== undefined) + return this.#packageCleanupPromise; + const cleanup = this.#performPackageDirectoryCleanup().finally(() => { + if (this.#packageCleanupPromise === cleanup) + this.#packageCleanupPromise = undefined; + }); + this.#packageCleanupPromise = cleanup; + return cleanup; + } + + async #performPackageDirectoryCleanup(): Promise { + const failures: AnalysisError[] = []; + for (const owner of this.#pendingPackageDirectoryCleanup) { + try { + await owner.remove(); + this.#pendingPackageDirectoryCleanup.delete(owner); + } catch (cause: unknown) { + const cleanup = new ProviderCleanupError( + ADB_PROVIDER_IDENTITY.id, + [owner.path], + { + reason: cause instanceof Error ? cause.message : String(cause), + }, + { operation: "pull_adb_package", cause }, + ); + failures.push( + analysisErrorWithCleanupFailure( + owner.primary, + cleanup, + "pull_adb_package", + ), + ); + } + } + if (failures.length === 1) throw failures[0]; + if (failures.length > 1) + throw new ProviderCleanupError( + ADB_PROVIDER_IDENTITY.id, + [...this.#pendingPackageDirectoryCleanup].map(({ path }) => path), + { + reason: + "Failed package output directories remain after cleanup retry", + failures: failures.map(({ message, cleanupResources }) => ({ + message, + resources: [...cleanupResources], + })), + }, + { + operation: "pull_adb_package", + cause: new AggregateError( + failures, + "Multiple ADB package rollback cleanups failed", + ), + }, + ); + } async execute( request: AdbRequest, options?: ExecutionOptions, + ): Promise> { + if (this.#closing) + return err(new AnalysisCancelledError(request.operation)); + let release!: () => void; + const active = new Promise((resolve) => { + release = resolve; + }); + this.#activeOperations.add(active); + try { + if (this.#pendingPackageDirectoryCleanup.size > 0) { + try { + await this.#retryPackageDirectoryCleanup(); + } catch (cause: unknown) { + return err( + cause instanceof AnalysisError + ? cause + : new ProviderCleanupError( + ADB_PROVIDER_IDENTITY.id, + [...this.#pendingPackageDirectoryCleanup].map( + ({ path }) => path, + ), + { + reason: + cause instanceof Error ? cause.message : String(cause), + }, + { operation: request.operation, cause }, + ), + ); + } + } + return await this.#executeOperation(request, options); + } finally { + this.#activeOperations.delete(active); + release(); + } + } + + async #executeOperation( + request: AdbRequest, + options?: ExecutionOptions, ): Promise> { const signal = options?.signal; if (signal?.aborted === true) @@ -1010,9 +1177,11 @@ export class AdbProvider { ); if (!directory.ok) return directory; const packageDirectory = join(directory.value, packageName); + let packageDirectoryCreated = false; + let packageDirectoryIdentity: PackageDirectoryIdentity | undefined; try { if ( - await stat(packageDirectory).then( + await lstat(packageDirectory).then( () => true, () => false, ) @@ -1021,14 +1190,44 @@ export class AdbProvider { `The package output directory already exists: ${packageDirectory}`, ); await mkdir(packageDirectory); + packageDirectoryCreated = true; + const created = await lstat(packageDirectory); + if (!created.isDirectory() || created.isSymbolicLink()) + throw new Error( + `The created package output is not a regular directory: ${packageDirectory}`, + ); + packageDirectoryIdentity = { + dev: created.dev, + ino: created.ino, + mode: created.mode, + }; } catch (cause) { - return err( - new AnalysisOutputError( - operation, - cause instanceof Error ? cause.message : String(cause), - { cause }, - ), + const primary = new AnalysisOutputError( + operation, + cause instanceof Error ? cause.message : String(cause), + { cause }, ); + if (!packageDirectoryCreated) return err(primary); + const owner: PendingPackageDirectoryCleanup = { + path: packageDirectory, + identity: packageDirectoryIdentity, + primary, + remove: () => + removeOwnedPackageDirectory( + packageDirectory, + packageDirectoryIdentity, + ), + }; + this.#pendingPackageDirectoryCleanup.add(owner); + const cleanup = new ProviderCleanupError( + ADB_PROVIDER_IDENTITY.id, + [packageDirectory], + { + reason: "Could not establish an owned package directory identity", + }, + { operation, cause }, + ); + return err(analysisErrorWithCleanupFailure(primary, cleanup, operation)); } const artifacts: { device_path: string; @@ -1044,6 +1243,37 @@ export class AdbProvider { stage: "resolve_paths" | "pull" | "digest"; message: string; }[] = []; + const cancelledPackagePull = ( + error: AnalysisCancelledError, + localPath: string, + devicePath: string, + stage: "pull" | "digest", + ) => { + error.retainPartialObservation({ + provider_id: "adb", + operation, + result: { + client, + serial, + package_name: packageName, + output_directory: directory.value, + artifacts, + failures: [ + ...failures, + { + device_path: devicePath, + stage, + message: + stage === "pull" + ? `Pull cancelled; any incomplete file is retained at ${localPath}. Remaining APKs were not attempted.` + : `Digesting the pulled file was cancelled; the file is retained at ${localPath}. Remaining APKs were not attempted.`, + }, + ], + coverage: "partial", + }, + }); + return err(error); + }; const seenFileNames = new Set(); for (const entry of parsed.paths) { if (seenFileNames.has(entry.file_name)) { @@ -1065,7 +1295,13 @@ export class AdbProvider { signal, ); if (!pulled.ok) { - if (pulled.error instanceof AnalysisCancelledError) return pulled; + if (pulled.error instanceof AnalysisCancelledError) + return cancelledPackagePull( + pulled.error, + localPath, + entry.device_path, + "pull", + ); failures.push({ device_path: entry.device_path, stage: "pull", @@ -1074,18 +1310,24 @@ export class AdbProvider { continue; } try { - const info = await stat(localPath); - const sha256 = await sha256File(localPath); + const digest = await hashAdbFile(localPath, operation, signal); artifacts.push({ device_path: entry.device_path, file_name: entry.file_name, local_path: localPath, - bytes: info.size, - sha256, + bytes: digest.bytes, + sha256: digest.sha256, role: entry.role, role_basis: "file_name", }); - } catch { + } catch (cause: unknown) { + if (cause instanceof AnalysisCancelledError) + return cancelledPackagePull( + cause, + localPath, + entry.device_path, + "digest", + ); failures.push({ device_path: entry.device_path, stage: "digest", @@ -1094,14 +1336,36 @@ export class AdbProvider { } } if (artifacts.length === 0 && failures.length > 0) { - await rm(packageDirectory, { recursive: true, force: true }).catch( - () => undefined, - ); - return err( - new AnalysisProtocolError( - `Every APK pull failed for ${packageName} on ${serial}: ${failures[0]!.message}`, - ), + const primary = new AnalysisProtocolError( + `Every APK pull failed for ${packageName} on ${serial}: ${failures[0]!.message}`, ); + const owner: PendingPackageDirectoryCleanup = { + path: packageDirectory, + identity: packageDirectoryIdentity, + primary, + remove: () => + removeOwnedPackageDirectory( + packageDirectory, + packageDirectoryIdentity, + ), + }; + try { + await owner.remove(); + } catch (cause: unknown) { + this.#pendingPackageDirectoryCleanup.add(owner); + const cleanup = new ProviderCleanupError( + ADB_PROVIDER_IDENTITY.id, + [packageDirectory], + { + reason: cause instanceof Error ? cause.message : String(cause), + }, + { operation: operation, cause }, + ); + return err( + analysisErrorWithCleanupFailure(primary, cleanup, operation), + ); + } + return err(primary); } return ok( createAnalysisExecution( @@ -1156,8 +1420,7 @@ export class AdbProvider { ); if (!pulled.ok) return pulled; try { - const info = await stat(localPath); - const sha256 = await sha256File(localPath); + const digest = await hashAdbFile(localPath, operation, signal); return ok( createAnalysisExecution( { @@ -1165,8 +1428,8 @@ export class AdbProvider { serial: input.serial, device_path: input.device_path, local_path: localPath, - bytes: info.size, - sha256, + bytes: digest.bytes, + sha256: digest.sha256, }, provider, { @@ -1177,6 +1440,20 @@ export class AdbProvider { ), ); } catch (cause) { + if (cause instanceof AnalysisCancelledError) { + cause.retainPartialObservation({ + provider_id: "adb", + operation, + result: { + client, + serial: input.serial, + local_path: localPath, + device_path: input.device_path, + digest_status: "unknown", + }, + }); + return err(cause); + } return err( new AnalysisOutputError( operation, @@ -1211,7 +1488,13 @@ export class AdbProvider { cause: new Error(`The local file does not exist: ${localPath}`), }), ); - const sha256 = await sha256File(localPath); + let digest: Awaited>; + try { + digest = await hashAdbFile(localPath, operation, signal); + } catch (cause: unknown) { + if (cause instanceof AnalysisCancelledError) return err(cause); + throw cause; + } const existsProbe = await runAdb( operation, input.device_path, @@ -1257,7 +1540,7 @@ export class AdbProvider { ); if (deviceDigest.ok) { const digestMatch = /^([a-f0-9]{64})\s/u.exec(deviceDigest.value.stdout); - if (digestMatch !== null && digestMatch[1] !== sha256) + if (digestMatch !== null && digestMatch[1] !== digest.sha256) return err( new AnalysisArtifactChangedError( operation, @@ -1272,8 +1555,8 @@ export class AdbProvider { serial: input.serial, local_path: localPath, device_path: input.device_path, - bytes: info.size, - sha256, + bytes: digest.bytes, + sha256: digest.sha256, device_sha256: digestMatch?.[1] ?? null, overwritten: deviceExists, device_digest_source: "device_sha256sum", @@ -1294,8 +1577,8 @@ export class AdbProvider { serial: input.serial, local_path: localPath, device_path: input.device_path, - bytes: info.size, - sha256, + bytes: digest.bytes, + sha256: digest.sha256, device_sha256: null, overwritten: deviceExists, device_digest_source: "unavailable", @@ -1334,7 +1617,13 @@ export class AdbProvider { cause: new Error(`The local APK does not exist: ${apkPath}`), }), ); - const sha256 = await sha256File(apkPath); + let digest: Awaited>; + try { + digest = await hashAdbFile(apkPath, operation, signal); + } catch (cause: unknown) { + if (cause instanceof AnalysisCancelledError) return err(cause); + throw cause; + } const installed = await runAdb( operation, input.serial, @@ -1363,8 +1652,8 @@ export class AdbProvider { client, serial: input.serial, apk_path: apkPath, - bytes: info.size, - sha256, + bytes: digest.bytes, + sha256: digest.sha256, replaced: input.replace, }, provider, @@ -1734,16 +2023,15 @@ export class AdbProvider { ), ); try { - const info = await stat(reportedPath); - const sha256 = await sha256File(reportedPath); + const digest = await hashAdbFile(reportedPath, operation, signal); return ok( createAnalysisExecution( { client, serial: input.serial, local_path: reportedPath, - bytes: info.size, - sha256, + bytes: digest.bytes, + sha256: digest.sha256, adb_reported_path: reportedPath, }, provider, @@ -1755,6 +2043,20 @@ export class AdbProvider { ), ); } catch (cause) { + if (cause instanceof AnalysisCancelledError) { + cause.retainPartialObservation({ + provider_id: "adb", + operation, + result: { + client, + serial: input.serial, + local_path: reportedPath, + adb_reported_path: reportedPath, + digest_status: "unknown", + }, + }); + return err(cause); + } return err( new AnalysisOutputError( operation, diff --git a/src/android/AndroidTargetSnapshot.ts b/src/android/AndroidTargetSnapshot.ts index 2ffb20266..7078caa09 100644 --- a/src/android/AndroidTargetSnapshot.ts +++ b/src/android/AndroidTargetSnapshot.ts @@ -1,20 +1,19 @@ -import { constants, createReadStream } from "node:fs"; -import { chmod, copyFile } from "node:fs/promises"; import { createHash } from "node:crypto"; +import type { Stats } from "node:fs"; +import { chmod, open, rm, stat, type FileHandle } from "node:fs/promises"; import { join } from "node:path"; +import { Transform, type TransformCallback } from "node:stream"; +import { pipeline } from "node:stream/promises"; import { AnalysisInputError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js"; +import { + openRegularFile, + sameRegularFileState, +} from "../filesystem/RegularFile.js"; import type { AndroidOperation } from "../domain/android/androidAnalysis.js"; -/** Stream a local file digest without retaining the APK or JAR in memory. */ -export const hashAndroidFile = async (path: string): Promise => { - const hash = createHash("sha256"); - for await (const chunk of createReadStream(path)) hash.update(chunk); - return hash.digest("hex"); -}; - /** Bind decompiler input to the admitted artifact, even if the original changes. */ export const snapshotAndroidTarget = async ( path: string, @@ -23,18 +22,20 @@ export const snapshotAndroidTarget = async ( operation: AndroidOperation, ): Promise => { const snapshot = join(root, "target.apk"); - await copyFile(path, snapshot, constants.COPYFILE_EXCL); - await chmod(snapshot, 0o400); - if ((await hashAndroidFile(snapshot)) !== sha256) - throw new AnalysisInputError(operation, undefined, [ + try { + await copyAndroidSnapshot(path, snapshot, sha256); + await chmod(snapshot, 0o400); + return snapshot; + } catch (cause: unknown) { + if (!(cause instanceof AndroidSnapshotChangedError)) throw cause; + throw new AnalysisInputError(operation, { cause }, [ { path: ["path"], reason: "invalid_value", - message: - "APK bytes changed after admission; retry against a stable file.", + message: `APK bytes changed after admission at ${path}; retry against a stable file.`, }, ]); - return snapshot; + } }; /** Fingerprint the actual immutable engine bytes executed for this observation. */ @@ -45,13 +46,98 @@ export const snapshotAndroidEngine = async ( operation: AndroidOperation, ): Promise<{ path: string; sha256: string }> => { const path = join(root, "engine.jar"); - await copyFile(source, path, constants.COPYFILE_EXCL); - await chmod(path, 0o400); - if ((await hashAndroidFile(path)) !== sha256) + try { + const observed = await copyAndroidSnapshot(source, path, sha256); + await chmod(path, 0o400); + return { path, sha256: observed }; + } catch (cause: unknown) { + if (!(cause instanceof AndroidSnapshotChangedError)) throw cause; throw new AnalysisCapabilityUnavailableError( "jadx", operation, - "REA_JADX_MCP_JAR bytes changed during admission; retry with a stable engine file.", + `REA_JADX_MCP_JAR bytes changed during admission at ${source}; retry with a stable engine file.`, + { cause }, ); - return { path, sha256 }; + } }; + +const copyAndroidSnapshot = async ( + sourcePath: string, + snapshotPath: string, + expectedSha256: string, +): Promise => { + const source = await openRegularFile(sourcePath, { symlinks: "follow" }); + let destination: FileHandle | undefined; + let copiedBytes = 0; + const hash = createHash("sha256"); + try { + const initial = await source.stat(); + const digest = new Transform({ + transform( + chunk: Buffer, + _encoding: BufferEncoding, + callback: TransformCallback, + ) { + copiedBytes += chunk.length; + if (copiedBytes > initial.size) { + callback( + new AndroidSnapshotChangedError( + `Android input grew while being copied: ${sourcePath}`, + ), + ); + return; + } + hash.update(chunk); + callback(null, chunk); + }, + }); + try { + destination = await open(snapshotPath, "wx", 0o600); + await pipeline( + source.createReadStream({ + start: 0, + end: initial.size, + autoClose: false, + }), + digest, + destination.createWriteStream({ autoClose: false }), + ); + await verifySourceState(source, sourcePath, initial, copiedBytes); + const observedSha256 = hash.digest("hex"); + if (observedSha256 !== expectedSha256) + throw new AndroidSnapshotChangedError( + `Android snapshot digest mismatch for ${sourcePath}`, + ); + return observedSha256; + } catch (cause: unknown) { + if (destination !== undefined) + await rm(snapshotPath, { force: true }).catch(() => undefined); + throw cause; + } + } finally { + await Promise.all([source.close(), destination?.close()]); + } +}; + +const verifySourceState = async ( + handle: Awaited>, + path: string, + initial: Stats, + observedBytes: number, +): Promise => { + const [opened, currentPath] = await Promise.all([handle.stat(), stat(path)]); + if ( + observedBytes !== initial.size || + !sameRegularFileState(initial, opened) || + !sameRegularFileState(initial, currentPath) + ) + throw new AndroidSnapshotChangedError( + `Android input changed while being read: ${path}`, + ); +}; + +class AndroidSnapshotChangedError extends Error { + constructor(message: string, options?: ErrorOptions) { + super(message, options); + } +} diff --git a/src/android/JadxProvider.ts b/src/android/JadxProvider.ts index 98e798cf7..af2e0e700 100644 --- a/src/android/JadxProvider.ts +++ b/src/android/JadxProvider.ts @@ -21,9 +21,10 @@ import { err, ok, type Result } from "../domain/result.js"; import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js"; import { snapshotAndroidEngine, - hashAndroidFile, snapshotAndroidTarget, } from "./AndroidTargetSnapshot.js"; +import { hashStableFile } from "../filesystem/StableFileHash.js"; +import { RegularFileChangedError } from "../filesystem/RegularFile.js"; import { inspectJadxAvailability, resolveJadxConfiguration, @@ -104,6 +105,50 @@ const executionError = (context: { }); }; +const androidTargetChanged = ( + operation: string, + path: string, + cause?: unknown, +): AnalysisInputError => + new AnalysisInputError( + operation, + cause === undefined ? undefined : { cause }, + [ + { + path: ["path"], + reason: "invalid_value", + message: `APK bytes changed after admission at ${path}; retry against a stable file.`, + }, + ], + ); + +const androidSourceChanged = ( + operation: string, + source: string, + cause?: unknown, +): AnalysisCapabilityUnavailableError => + new AnalysisCapabilityUnavailableError( + "jadx", + operation, + `Selected JADX input bytes changed during admission at ${source}; retry with a stable installation.`, + cause === undefined ? undefined : { cause }, + ); + +const hashAndroidSource = async ( + path: string, + operation: string, + signal: AbortSignal, +): Promise => { + try { + return (await hashStableFile(path, signal)).sha256; + } catch (cause: unknown) { + if (signal.aborted) throw cause; + if (cause instanceof RegularFileChangedError) + throw androidSourceChanged(operation, path, cause); + throw cause; + } +}; + interface PendingCleanup { session: JadxSession | undefined; root: PrivateRuntimeRoot | undefined; @@ -147,17 +192,18 @@ const cleanup = async ( await root?.close(); resources.root = undefined; } catch (cause) { - return err( - new ProviderCleanupError( - "jadx", - [root?.path ?? "unknown"], - { - ...diagnostics, - reason: cause instanceof Error ? cause.message : String(cause), - }, - { cause: previousError ?? cause }, - ), + const error = new ProviderCleanupError( + "jadx", + [root?.path ?? "unknown"], + { + ...diagnostics, + reason: cause instanceof Error ? cause.message : String(cause), + }, + { cause: previousError ?? cause }, ); + if (previousError?.partialObservation !== undefined) + error.retainPartialObservation(previousError.partialObservation); + return err(error); } return ok(undefined); }; @@ -293,17 +339,27 @@ export class JadxProvider implements AndroidAnalysisPort { signal, ); signal.throwIfAborted(); - const jarHash = await hashAndroidFile(configuration.jar); - const bridgeHash = await hashAndroidFile(BRIDGE_SOURCE); - if ((await hashAndroidFile(target.path)) !== target.sha256) - throw new AnalysisInputError(request.operation, undefined, [ - { - path: ["path"], - reason: "invalid_value", - message: - "APK bytes changed after admission; retry against a stable file.", - }, - ]); + const jarHash = await hashAndroidSource( + configuration.jar, + request.operation, + signal, + ); + const bridgeHash = await hashAndroidSource( + BRIDGE_SOURCE, + request.operation, + signal, + ); + let targetHash: string; + try { + targetHash = (await hashStableFile(target.path, signal)).sha256; + } catch (cause: unknown) { + if (signal.aborted) throw cause; + if (cause instanceof RegularFileChangedError) + throw androidTargetChanged(request.operation, target.path, cause); + throw cause; + } + if (targetHash !== target.sha256) + throw androidTargetChanged(request.operation, target.path); const key = JSON.stringify({ path: target.path, sha256: target.sha256, @@ -342,11 +398,16 @@ export class JadxProvider implements AndroidAnalysisPort { const bridge = join(root.path, "ReaJadxBridge.java"); await copyFile(BRIDGE_SOURCE, bridge); await chmod(bridge, 0o400); - if ((await hashAndroidFile(bridge)) !== bridgeHash) - throw new AnalysisCapabilityUnavailableError( - "jadx", + const copiedBridgeHash = await hashAndroidSource( + bridge, + request.operation, + signal, + ); + if (copiedBridgeHash !== bridgeHash) + throw androidSourceChanged( request.operation, - "REA Android bridge bytes changed during admission; retry with a stable installation.", + BRIDGE_SOURCE, + undefined, ); signal.throwIfAborted(); session = new JadxSession( diff --git a/src/application/ClientConfigurationFiles.ts b/src/application/ClientConfigurationFiles.ts index 5982f53a9..a3ff426e7 100644 --- a/src/application/ClientConfigurationFiles.ts +++ b/src/application/ClientConfigurationFiles.ts @@ -1,5 +1,5 @@ import { err, ok, type Result } from "../domain/result.js"; -import { readFile } from "node:fs/promises"; +import { readRegularFileText } from "./RegularFileRead.js"; import { effectiveClientServer, parseClientConfiguration, @@ -19,7 +19,7 @@ export const readConfigurationText = async ( path: string, ): Promise> => { try { - return ok(await readFile(path, "utf8")); + return ok(await readRegularFileText(path)); } catch (cause: unknown) { if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") return ok(undefined); diff --git a/src/application/JsonFiles.ts b/src/application/JsonFiles.ts index 916d4fd61..1d3875570 100644 --- a/src/application/JsonFiles.ts +++ b/src/application/JsonFiles.ts @@ -16,8 +16,7 @@ import { AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js"; import { err, ok, type Result } from "../domain/result.js"; -import { parseUtf8Json } from "./Utf8JsonInput.js"; -import { readRegularFile } from "./RegularFileRead.js"; +import { readJsonInputFile } from "./JsonInputFile.js"; import { NonRegularFileReadError } from "../filesystem/RegularFile.js"; /** Request control and its owning operation for an interruptible atomic write. */ @@ -37,12 +36,20 @@ export const readJsonFile = async ( > => { const requestedPath = resolve(path); try { - const encoded = await readRegularFile(requestedPath); - const decoded = parseUtf8Json(encoded, "read_evidence_file", requestedPath); + const decoded = await readJsonInputFile( + requestedPath, + "read_evidence_file", + ); if (!decoded.ok) { + if (decoded.error instanceof AnalysisResourceConstraintError) + return err(decoded.error); return err( new EvidenceFileError("read", "invalid-json", { - cause: decoded.cause ?? new SyntaxError(decoded.error), + cause: + decoded.error.cause ?? + new SyntaxError( + decoded.error.issues[0]?.message ?? decoded.error.message, + ), path: requestedPath, }), ); diff --git a/src/cliJsonFile.ts b/src/application/JsonInputFile.ts similarity index 58% rename from src/cliJsonFile.ts rename to src/application/JsonInputFile.ts index c0d474f69..96d26e61e 100644 --- a/src/cliJsonFile.ts +++ b/src/application/JsonInputFile.ts @@ -6,61 +6,76 @@ import { getHeapStatistics } from "node:v8"; import parser from "stream-json/parser.js"; import streamValues from "stream-json/streamers/stream-values.js"; -import { withRegularFile } from "./application/RegularFileRead.js"; +import { RegularFileChangedError } from "../filesystem/RegularFile.js"; +import { withRegularFile } from "./RegularFileRead.js"; import { JSON_BYTE_ORDER_MARK_MESSAGE, JSON_INPUT_RESOURCE_REMEDIATION, parseUtf8Json, -} from "./application/Utf8JsonInput.js"; +} from "./Utf8JsonInput.js"; import { AnalysisInputError, AnalysisResourceConstraintError, -} from "./domain/analysisErrorCore.js"; -import { err, ok, type Result } from "./domain/result.js"; +} from "../domain/analysisErrorCore.js"; +import { err, ok, type Result } from "../domain/result.js"; -type JsonFileFailure = AnalysisInputError | AnalysisResourceConstraintError; +type JsonInputFileFailure = + | AnalysisInputError + | AnalysisResourceConstraintError; const READ_CHUNK_BYTES = 64 * 1024; -const PACKED_STRING_PART_CODE_UNITS = 64 * 1024; +const PACKED_TOKEN_PART_CODE_UNITS = 64 * 1024; // Retain native-parser speed for modest inputs while bounding its extra copies. // This selects an implementation; larger files remain accepted through streaming. const NATIVE_PARSE_READ_BUDGET = 8 * 1024 * 1024; +/** Keep native parsing only when input copies and value expansion fit live headroom. */ +const nativeParseFits = (inputBytes: number): boolean => + inputBytes <= NATIVE_PARSE_READ_BUDGET && + // The assembler estimate reserves up to 128 bytes per two-byte container. + // Allow that 64x expansion plus byte/text copies before native JSON.parse, + // whose individual container allocations cannot be intercepted. + inputBytes * 72 + READ_CHUNK_BYTES <= + getHeapStatistics().total_available_size; + /** Parse strict UTF-8 JSON without requiring a whole-document string. */ -export const readCliJsonFile = ( +export const readJsonInputFile = ( path: string, operation: string, signal?: AbortSignal, -): Promise> => +): Promise> => withRegularFile( path, async (handle, stats) => { let found = false; let value: unknown; try { - const prefix = - stats.size <= NATIVE_PARSE_READ_BUDGET - ? await readPrefix(handle, stats.size + 1, signal) - : undefined; - if (prefix?.complete === true) { + const prefix = nativeParseFits(stats.size) + ? await readPrefix(handle, stats.size + 1, signal) + : undefined; + if (prefix !== undefined) { + if (!prefix.complete || prefix.bytes.length !== stats.size) + throw new RegularFileChangedError(path); const parsed = parseUtf8Json( prefix.bytes, operation, path, - "cli-json-input", + "json-file-input", ); return parsed.ok ? ok(parsed.value) : err(invalidJson(operation, parsed.error, parsed.cause)); } await pipeline( - decodedChunks(handle, signal, prefix?.bytes), + decodedChunks(handle, stats.size, path, signal), parser.asStream({ jsonStreaming: false, streamValues: false, packKeys: false, packStrings: false, + packNumbers: false, }), - packJsonStrings(operation, stats.size), + packJsonScalars(operation, stats.size, path), + admitJsonAssembly(operation, stats.size, path), streamValues.asStream(), async (rows: AsyncIterable) => { for await (const row of rows) { @@ -107,8 +122,9 @@ export const readCliJsonFile = ( new AnalysisResourceConstraintError( operation, "memory", - "An individual JSON string exceeds the runtime string limit", + "An individual JSON string or number token exceeds the runtime string limit", { + input_path: path, input_file_bytes: stats.size, max_string_code_units: constants.MAX_STRING_LENGTH, }, @@ -121,12 +137,16 @@ export const readCliJsonFile = ( throw cause; } }, - signal, + { signal }, ); -const packJsonStrings = (operation: string, inputFileBytes: number) => +const packJsonScalars = ( + operation: string, + inputFileBytes: number, + path: string, +) => async function* (tokens: AsyncIterable): AsyncGenerator { - let kind: "keyValue" | "stringValue" | undefined; + let kind: "keyValue" | "stringValue" | "numberValue" | undefined; let length = 0; let value = ""; let parts: string[] = []; @@ -139,23 +159,32 @@ const packJsonStrings = (operation: string, inputFileBytes: number) => case "startString": kind = token.name === "startKey" ? "keyValue" : "stringValue"; break; + case "startNumber": + kind = "numberValue"; + break; + case "numberChunk": case "stringChunk": if ( kind === undefined || !("value" in token) || typeof token.value !== "string" ) - throw new Error("Unexpected JSON string fragment"); + throw new Error("Unexpected JSON scalar fragment"); length += token.value.length; if (length > constants.MAX_STRING_LENGTH) throw new RangeError("Invalid string length"); parts.push(token.value); partLength += token.value.length; - if (partLength >= PACKED_STRING_PART_CODE_UNITS) { + if (partLength >= PACKED_TOKEN_PART_CODE_UNITS) { // The tokenizer emits short fragments. Coalesce them before retaining - // a string so millions of substring/rope nodes cannot exhaust the heap + // a scalar so millions of substring/rope nodes cannot exhaust the heap // before the native string-length constraint can be reported. - requireStringAssemblyHeadroom(operation, inputFileBytes, length); + requireStringAssemblyHeadroom( + operation, + inputFileBytes, + path, + length, + ); value += parts.join(""); parts = []; partLength = 0; @@ -163,8 +192,14 @@ const packJsonStrings = (operation: string, inputFileBytes: number) => break; case "endKey": case "endString": - if (kind === undefined) throw new Error("Unexpected JSON string end"); - requireStringAssemblyHeadroom(operation, inputFileBytes, length); + case "endNumber": + if (kind === undefined) throw new Error("Unexpected JSON scalar end"); + requireStringAssemblyHeadroom( + operation, + inputFileBytes, + path, + length, + ); yield { name: kind, value: value + parts.join("") }; kind = undefined; length = 0; @@ -178,22 +213,78 @@ const packJsonStrings = (operation: string, inputFileBytes: number) => } }; +/** Admit the retained value graph before the upstream assembler grows it. */ +const admitJsonAssembly = ( + operation: string, + inputFileBytes: number, + path: string, +) => + async function* (tokens: AsyncIterable): AsyncGenerator { + let projectedBytes = 0; + let nextCheck = 0; + for await (const token of tokens) { + if (typeof token !== "object" || token === null || !("name" in token)) + throw new Error("Unexpected JSON assembly token"); + if (token.name === "startObject" || token.name === "startArray") { + projectedBytes += 128; + } else if (token.name === "keyValue" || token.name === "stringValue") { + if (!("value" in token) || typeof token.value !== "string") + throw new Error("Unexpected packed JSON string"); + projectedBytes += 64 + token.value.length * 2; + } else if ( + token.name === "numberValue" || + token.name === "nullValue" || + token.name === "trueValue" || + token.name === "falseValue" + ) { + projectedBytes += 64; + } + if (projectedBytes >= nextCheck) { + const heap = getHeapStatistics(); + // Conservative capacity for containers, property/array slots and UTF-16 + // values. Keep another whole projection available for container growth, + // plus the next chunk of estimates between samples. This is admission + // against live runtime headroom, not a fixed document-size policy. + const requiredBytes = projectedBytes + READ_CHUNK_BYTES; + if (requiredBytes > heap.total_available_size) + throw new AnalysisResourceConstraintError( + operation, + "memory", + "Insufficient heap headroom to materialize the complete JSON value", + { + input_path: path, + input_file_bytes: inputFileBytes, + projected_value_bytes: projectedBytes, + assembly_headroom_bytes: requiredBytes, + available_heap_bytes: heap.total_available_size, + heap_size_limit_bytes: heap.heap_size_limit, + }, + { remediationAction: JSON_INPUT_RESOURCE_REMEDIATION }, + ); + nextCheck = projectedBytes + READ_CHUNK_BYTES; + } + yield token; + } + }; + const requireStringAssemblyHeadroom = ( operation: string, inputFileBytes: number, + path: string, stringCodeUnits: number, ): void => { - if (stringCodeUnits < PACKED_STRING_PART_CODE_UNITS) return; + if (stringCodeUnits < PACKED_TOKEN_PART_CODE_UNITS) return; const heap = getHeapStatistics(); // Concatenation or key interning may flatten the retained rope. Reserve its // UTF-16 representation and the next coalesced part before that allocation. - const requiredBytes = 2 * (stringCodeUnits + PACKED_STRING_PART_CODE_UNITS); + const requiredBytes = 2 * (stringCodeUnits + PACKED_TOKEN_PART_CODE_UNITS); if (requiredBytes > heap.total_available_size) throw new AnalysisResourceConstraintError( operation, "memory", "Insufficient heap headroom to assemble a complete JSON string", { + input_path: path, input_file_bytes: inputFileBytes, string_code_units: stringCodeUnits, string_assembly_headroom_bytes: requiredBytes, @@ -208,8 +299,9 @@ const requireStringAssemblyHeadroom = ( async function* decodedChunks( handle: FileHandle, + admittedBytes: number, + path: string, signal: AbortSignal | undefined, - prefix?: Uint8Array, ): AsyncGenerator { const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }); let leading = true; @@ -220,25 +312,25 @@ async function* decodedChunks( } return text; }; - if (prefix !== undefined) - for (let offset = 0; offset < prefix.length; offset += READ_CHUNK_BYTES) { - signal?.throwIfAborted(); - yield checked( - decoder.decode(prefix.subarray(offset, offset + READ_CHUNK_BYTES), { - stream: true, - }), - ); - } const bytes = Buffer.allocUnsafe(READ_CHUNK_BYTES); + let observedBytes = 0; while (true) { signal?.throwIfAborted(); - const read = await handle.read(bytes, 0, bytes.length, null); + const read = await handle.read( + bytes, + 0, + Math.min(bytes.length, admittedBytes - observedBytes + 1), + null, + ); signal?.throwIfAborted(); if (read.bytesRead === 0) break; + observedBytes += read.bytesRead; + if (observedBytes > admittedBytes) throw new RegularFileChangedError(path); yield checked( decoder.decode(bytes.subarray(0, read.bytesRead), { stream: true }), ); } + if (observedBytes !== admittedBytes) throw new RegularFileChangedError(path); yield checked(decoder.decode()); } @@ -264,8 +356,7 @@ const readPrefix = async ( return { bytes: bytes.subarray(0, offset), complete: true }; offset += read.bytesRead; } - // The file grew after admission. Continue from this same handle, preserving - // the prefix already read rather than reopening or dropping its bytes. + // One byte beyond the admitted extent proves the selected file changed. return { bytes, complete: false }; }; diff --git a/src/application/ReferenceSourceImportPolicy.ts b/src/application/ReferenceSourceImportPolicy.ts index 0cb467d66..e358c3636 100644 --- a/src/application/ReferenceSourceImportPolicy.ts +++ b/src/application/ReferenceSourceImportPolicy.ts @@ -1,7 +1,8 @@ -import { readFile, realpath, stat } from "node:fs/promises"; +import { lstat, realpath, stat } from "node:fs/promises"; import { join, resolve } from "node:path"; import ignore from "ignore"; +import { readRegularFileText } from "./RegularFileRead.js"; import { err, ok, type Result } from "../domain/result.js"; import { @@ -47,14 +48,27 @@ const resolveRoot = async ( const buildIgnored = async ( root: string, excludePaths: readonly string[], + signal?: AbortSignal, ): Promise> => { const ignored = ignore(); + const policyPath = join(root, ".gitignore"); + let present = true; try { - ignored.add(await readFile(join(root, ".gitignore"), "utf8")); + await lstat(policyPath); } catch (cause: unknown) { - // Missing or unreadable ignore file does not authorize broader access. - void cause; + if ( + !( + typeof cause === "object" && + cause !== null && + "code" in cause && + cause.code === "ENOENT" + ) + ) + throw cause; + present = false; } + signal?.throwIfAborted(); + if (present) ignored.add(await readRegularFileText(policyPath, { signal })); ignored.add([...DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS]); for (const path of excludePaths) { ignored.add(path); @@ -71,9 +85,22 @@ export const prepareReferenceSourceImport = async ( > => { const root = await resolveRoot(options.root); if (!root.ok) return root; - return ok({ - root: root.value, - ignored: await buildIgnored(root.value, options.excludePaths ?? []), - secrets: ignore().add([...options.policy.secretPatterns]), - }); + try { + return ok({ + root: root.value, + ignored: await buildIgnored( + root.value, + options.excludePaths ?? [], + options.signal, + ), + secrets: ignore().add([...options.policy.secretPatterns]), + }); + } catch (cause: unknown) { + return err( + failure( + options.signal?.aborted === true ? "cancelled" : "io", + `Reference source ignore policy could not be read at ${join(root.value, ".gitignore")}: ${cause instanceof Error ? cause.message : String(cause)}`, + ), + ); + } }; diff --git a/src/application/ReferenceSourceVcsAdapter.ts b/src/application/ReferenceSourceVcsAdapter.ts index 3ddad25d7..ef136a2ad 100644 --- a/src/application/ReferenceSourceVcsAdapter.ts +++ b/src/application/ReferenceSourceVcsAdapter.ts @@ -1,6 +1,7 @@ import fs from "node:fs"; -import { lstat, readFile } from "node:fs/promises"; +import { lstat } from "node:fs/promises"; import { join, resolve } from "node:path"; +import { readRegularFile, readRegularFileText } from "./RegularFileRead.js"; export type ReferenceSourceVcsInfo = | { @@ -29,7 +30,7 @@ export const readReferenceSourceVcs = async ( : { kind: "unknown", head: null, dirty: null }; } try { - const head = await resolveSourceHead(root); + const head = await resolveSourceHead(root, signal); if (isAborted(signal)) return { kind: "unknown", head: null, dirty: null }; return { kind: "git", head, dirty: null }; } catch (cause: unknown) { @@ -39,13 +40,44 @@ export const readReferenceSourceVcs = async ( } }; -const resolveSourceHead = async (root: string): Promise => { +const resolveSourceHead = async ( + root: string, + signal?: AbortSignal, +): Promise => { // isomorphic-git is loaded on first use so CLI and MCP startup skip it. const { resolveRef } = await import("isomorphic-git"); + let failedRead: { readonly cause: unknown } | undefined; + const referenceFs = { + ...fs, + promises: { + ...fs.promises, + // isomorphic-git treats every read failure as absence. Preserve real + // failures so a readable packed ref cannot hide an unreadable loose ref. + readFile: async (path: string) => { + try { + return await readRegularFile(path, { signal }); + } catch (cause: unknown) { + if (errorCode(cause) !== "ENOENT") failedRead ??= { cause }; + throw cause; + } + }, + }, + }; + const readRef = async (options: { + readonly gitdir?: string; + readonly ref: string; + }) => { + const head = await resolveRef({ fs: referenceFs, dir: root, ...options }); + signal?.throwIfAborted(); + if (failedRead !== undefined) throw failedRead.cause; + return head; + }; const dotgit = join(root, ".git"); - if (!(await lstat(dotgit)).isFile()) - return resolveRef({ fs, dir: root, ref: "HEAD" }); - const pointer = (await readFile(dotgit, "utf8")).replace(/\r?\n$/u, ""); + if (!(await lstat(dotgit)).isFile()) return readRef({ ref: "HEAD" }); + const pointer = (await readRegularFileText(dotgit, { signal })).replace( + /\r?\n$/u, + "", + ); if (!pointer.startsWith("gitdir: ") || pointer.length === 8) throw new Error("Invalid Git directory pointer"); const gitdir = resolve(root, pointer.slice(8)); @@ -53,25 +85,23 @@ const resolveSourceHead = async (root: string): Promise => { try { commonDirectory = resolve( gitdir, - (await readFile(join(gitdir, "commondir"), "utf8")).replace( - /\r?\n$/u, - "", - ), + ( + await readRegularFileText(join(gitdir, "commondir"), { signal }) + ).replace(/\r?\n$/u, ""), ); } catch (cause: unknown) { if (errorCode(cause) !== "ENOENT") throw cause; - return resolveRef({ fs, dir: root, gitdir, ref: "HEAD" }); + return readRef({ gitdir, ref: "HEAD" }); } - const head = (await readFile(join(gitdir, "HEAD"), "utf8")).trim(); - if (!head.startsWith("ref: ")) - return resolveRef({ fs, dir: root, gitdir, ref: "HEAD" }); + const head = ( + await readRegularFileText(join(gitdir, "HEAD"), { signal }) + ).trim(); + if (!head.startsWith("ref: ")) return readRef({ gitdir, ref: "HEAD" }); const ref = head.slice(5); const privateRef = ["refs/bisect/", "refs/rewritten/", "refs/worktree/"].some( (prefix) => ref.startsWith(prefix), ); - return resolveRef({ - fs, - dir: root, + return readRef({ gitdir: privateRef ? gitdir : commonDirectory, ref, }); diff --git a/src/application/RegularFileRead.ts b/src/application/RegularFileRead.ts index df87b7c5a..f584f1f6e 100644 --- a/src/application/RegularFileRead.ts +++ b/src/application/RegularFileRead.ts @@ -1,20 +1,44 @@ import type { Stats } from "node:fs"; -import type { FileHandle } from "node:fs/promises"; +import { lstat, stat, type FileHandle } from "node:fs/promises"; -import { openRegularFile } from "../filesystem/RegularFile.js"; +import { + openRegularFile, + sameRegularFileState, + RegularFileChangedError, +} from "../filesystem/RegularFile.js"; +import { readBoundedFileBytes } from "../process/BoundedFileBytes.js"; + +/** Filesystem admission policy for one selected regular input. */ +export interface RegularFileReadOptions { + readonly signal?: AbortSignal | undefined; + readonly symlinks?: "follow" | "reject"; +} /** Admit one regular-file handle, retain it through the consumer, and always close it. */ export const withRegularFile = async ( path: string, read: (handle: FileHandle, stats: Stats) => Promise, - signal?: AbortSignal, + options: RegularFileReadOptions = {}, ): Promise => { - const handle = await openRegularFile(path, { symlinks: "follow", signal }); + const { signal } = options; + const handle = await openRegularFile(path, { + symlinks: options.symlinks ?? "follow", + signal, + }); try { const stats = await handle.stat(); signal?.throwIfAborted(); const value = await read(handle, stats); signal?.throwIfAborted(); + const [opened, currentPath] = await Promise.all([ + handle.stat(), + options.symlinks === "reject" ? lstat(path) : stat(path), + ]); + if ( + !sameRegularFileState(stats, opened) || + !sameRegularFileState(stats, currentPath) + ) + throw new RegularFileChangedError(path); return value; } finally { await handle.close(); @@ -24,6 +48,25 @@ export const withRegularFile = async ( /** Admit a regular file without waiting for a pipe, then read its verified handle. */ export const readRegularFile = ( path: string, - signal?: AbortSignal, + options: RegularFileReadOptions = {}, ): Promise => - withRegularFile(path, (handle) => handle.readFile({ signal }), signal); + withRegularFile( + path, + async (handle, stats) => { + const bytes = await readBoundedFileBytes( + handle, + stats.size, + options.signal, + ); + if (bytes === undefined || bytes.length !== stats.size) + throw new RegularFileChangedError(path); + return bytes; + }, + options, + ); + +/** Read one admitted regular file as UTF-8 without waiting on a pipe. */ +export const readRegularFileText = async ( + path: string, + options: RegularFileReadOptions = {}, +): Promise => (await readRegularFile(path, options)).toString("utf8"); diff --git a/src/application/SetupClientConfiguration.ts b/src/application/SetupClientConfiguration.ts index 5cbf95206..4ae8a5ff7 100644 --- a/src/application/SetupClientConfiguration.ts +++ b/src/application/SetupClientConfiguration.ts @@ -14,7 +14,7 @@ import { type ClientRegistrationDialect, } from "./ClientConfigurationDocument.js"; import { constants as fsConstants } from "node:fs"; -import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises"; +import { copyFile, mkdir, rm, writeFile } from "node:fs/promises"; import { dirname } from "node:path"; import writeFileAtomic from "write-file-atomic"; @@ -22,6 +22,7 @@ import { PRODUCT_IDENTITY } from "../identity.js"; import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js"; import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js"; import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js"; +import { readRegularFileText } from "./RegularFileRead.js"; import type { ClientConfigurationInspection, ClientConfigurationResult, @@ -64,7 +65,7 @@ const configureClientDocument = async ( return { status: "failed", reason: "path" }; let original: string | undefined; try { - original = await readFile(transactionPath, "utf8"); + original = await readRegularFileText(transactionPath); } catch (cause: unknown) { if (!isMissing(cause)) return { status: "failed", reason: "readback" }; } @@ -149,7 +150,7 @@ const configureClientDocument = async ( } try { const readback = parseClientConfiguration( - await readFile(transactionPath, "utf8"), + await readRegularFileText(transactionPath), format, ); if (!registrationCurrent(readback, desired)) { @@ -178,7 +179,7 @@ export const clientConfigurationAligned = async ( try { const files = await readClientConfigurationFiles(client); if (!files.ok) return false; - const original = await readFile(client.configPath, "utf8"); + const original = await readRegularFileText(client.configPath); const parsed = parseClientConfiguration(original, client.format); const policy = await readClientPolicyBlock( client, @@ -246,7 +247,7 @@ export const inspectClientConfiguration = async ( }; let original: string; try { - original = await readFile(transactionPath, "utf8"); + original = await readRegularFileText(transactionPath); } catch (cause: unknown) { if (isMissing(cause)) return { status: "create" }; return { diff --git a/src/application/SetupSkill.ts b/src/application/SetupSkill.ts index b0770c31a..25228d14b 100644 --- a/src/application/SetupSkill.ts +++ b/src/application/SetupSkill.ts @@ -4,10 +4,8 @@ import { dirname, join } from "node:path"; import writeFileAtomic from "write-file-atomic"; import { PRODUCT_IDENTITY } from "../identity.js"; -import { - NonRegularFileReadError, - openRegularFile, -} from "../filesystem/RegularFile.js"; +import { NonRegularFileReadError } from "../filesystem/RegularFile.js"; +import { readRegularFileText } from "./RegularFileRead.js"; import { clientSkillDirectories } from "./SupportedClients.js"; export const MANAGED_SKILL_FILES = [ @@ -23,14 +21,8 @@ export const isManagedSkillManifest = (content: string): boolean => content.startsWith(`---\nname: ${PRODUCT_IDENTITY.skillName}\n`) || content.startsWith(`---\r\nname: ${PRODUCT_IDENTITY.skillName}\r\n`); -export const readSkillFile = async (path: string): Promise => { - const handle = await openRegularFile(path, { symlinks: "reject" }); - try { - return await handle.readFile("utf8"); - } finally { - await handle.close(); - } -}; +export const readSkillFile = (path: string): Promise => + readRegularFileText(path, { symlinks: "reject" }); interface CanonicalSkillFile { readonly content: string; @@ -199,7 +191,7 @@ export const installCanonicalSkill = async ( for (const { destination, content } of changed) await writeText(destination, content); for (const { destination, content } of changed) - if ((await readFile(destination, "utf8")) !== content) + if ((await readSkillFile(destination)) !== content) throw new Error(`skill readback mismatch: ${destination}`); return "installed"; } catch (cause: unknown) { @@ -231,7 +223,7 @@ export const readInstalledSkillIdentity = async ( let content: string | undefined; for (const destination of destinations) { try { - content = await readFile(join(destination.path, "SKILL.md"), "utf8"); + content = await readSkillFile(join(destination.path, "SKILL.md")); break; } catch { // Another selected copy may provide metadata; canonical validation below diff --git a/src/application/Uninstall.ts b/src/application/Uninstall.ts index 73986c3c3..6310ce99b 100644 --- a/src/application/Uninstall.ts +++ b/src/application/Uninstall.ts @@ -6,7 +6,7 @@ import { withClientServers, type ClientConfigurationDocument, } from "./ClientConfigurationDocument.js"; -import { copyFile, lstat, readFile, realpath, rm } from "node:fs/promises"; +import { copyFile, lstat, realpath, rm } from "node:fs/promises"; import { constants as fsConstants } from "node:fs"; import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js"; import { join } from "node:path"; @@ -23,6 +23,7 @@ import { } from "./SetupSkill.js"; import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js"; import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js"; +import { readRegularFileText } from "./RegularFileRead.js"; import { manualRegistrationRemediation, supportedClients, @@ -49,7 +50,7 @@ export interface UninstallFileSystem { } const systemFileSystem: UninstallFileSystem = { - readText: (path) => readFile(path, "utf8"), + readText: (path) => readRegularFileText(path), readRegularText: readSkillFile, copy: (source, destination) => copyFile(source, destination, fsConstants.COPYFILE_EXCL), diff --git a/src/application/UpdateMaintenance.ts b/src/application/UpdateMaintenance.ts index 51ae5342f..2a5a286d5 100644 --- a/src/application/UpdateMaintenance.ts +++ b/src/application/UpdateMaintenance.ts @@ -1,4 +1,3 @@ -import { readFile } from "node:fs/promises"; import { z } from "zod"; import { PRODUCT_IDENTITY } from "../identity.js"; @@ -14,6 +13,7 @@ import { supportedClients } from "./SupportedClients.js"; import { existingSkillDestinations } from "./SetupSkill.js"; import type { SetupAction } from "./SetupTypes.js"; import type { Result } from "../domain/result.js"; +import { readRegularFileText } from "./RegularFileRead.js"; /** Existing REA integrations selected for maintenance, without discovering new targets. */ export interface MaintenanceScope { @@ -73,7 +73,7 @@ export const existingMaintenanceScope = async ( const client = supported.find(({ name }) => name === registration.client); if (client === undefined) continue; const parsed = parseClientConfiguration( - await readFile(client.configPath, "utf8"), + await readRegularFileText(client.configPath), client.format, ); const enabled = z diff --git a/src/application/WebScriptExportService.ts b/src/application/WebScriptExportService.ts index 1b3a47b7e..3117cb69a 100644 --- a/src/application/WebScriptExportService.ts +++ b/src/application/WebScriptExportService.ts @@ -27,7 +27,10 @@ import { WebScriptExportError } from "../domain/webScriptExportError.js"; import type { ExecutionOptions } from "./AnalysisProvider.js"; import { WEB_SCRIPT_EXPORT_PROVIDER as PROVIDER } from "./InvestigationProviders.js"; import { readRegularFile } from "./RegularFileRead.js"; -import { NonRegularFileReadError } from "../filesystem/RegularFile.js"; +import { + NonRegularFileReadError, + RegularFileChangedError, +} from "../filesystem/RegularFile.js"; const OPERATION = "export_web_scripts"; @@ -153,7 +156,7 @@ const readCapture = async ( signal: AbortSignal | undefined, ): Promise> => { try { - return ok(await readRegularFile(path, signal)); + return ok(await readRegularFile(path, { signal })); } catch (cause: unknown) { const code = cause instanceof Error && "code" in cause ? String(cause.code) : ""; @@ -163,6 +166,7 @@ const readCapture = async ( ); if ( cause instanceof NonRegularFileReadError || + cause instanceof RegularFileChangedError || code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR" || diff --git a/src/application/adb/AdbDeviceAnalysisPort.ts b/src/application/adb/AdbDeviceAnalysisPort.ts index a4b541a83..3547537a9 100644 --- a/src/application/adb/AdbDeviceAnalysisPort.ts +++ b/src/application/adb/AdbDeviceAnalysisPort.ts @@ -14,7 +14,7 @@ import type { Result } from "../../domain/result.js"; export interface AdbDeviceAnalysisPort { /** Probe the selected adb binary without contacting devices. */ inspectAvailability(signal?: AbortSignal): Promise; - /** The provider holds no long-lived resources; safe to call always. */ + /** Terminally stop admission, drain work, and retry retained package rollback. */ close(): Promise; execute( request: AdbRequest, diff --git a/src/application/native/NativeUiActionTrace.ts b/src/application/native/NativeUiActionTrace.ts index 36e7ec67b..9b975b32c 100644 --- a/src/application/native/NativeUiActionTrace.ts +++ b/src/application/native/NativeUiActionTrace.ts @@ -325,8 +325,7 @@ const resolveUiAction = ( (node) => ["control", "view", "view_controller", "scene"].includes(node.kind) && (node.id === query || - node.attributes.interface_builder_object_id === query || - node.id.endsWith(`:object:${query}`)), + node.attributes.interface_builder_object_id === query), ); const actionIds = new Set( graph.edges.flatMap((edge) => diff --git a/src/artifacts/MachOSliceArtifactReader.ts b/src/artifacts/MachOSliceArtifactReader.ts index f812fdc1a..f306025c8 100644 --- a/src/artifacts/MachOSliceArtifactReader.ts +++ b/src/artifacts/MachOSliceArtifactReader.ts @@ -1,5 +1,5 @@ -import { createReadStream } from "node:fs"; -import { open as openFile, stat } from "node:fs/promises"; +import { lstat } from "node:fs/promises"; +import type { FileHandle } from "node:fs/promises"; import { Readable } from "node:stream"; import type { ArtifactCommand } from "../domain/artifactGraph.js"; @@ -19,11 +19,21 @@ import { type ArtifactReader, } from "./ArtifactReader.js"; import { streamChunkToBuffer } from "./StreamBytes.js"; +import { + openRegularFile, + sameRegularFileState, + type StableRegularFileDescriptor, +} from "../filesystem/RegularFile.js"; /** Read-only universal Mach-O slice reader backed by native lipo metadata. */ export class MachOSliceArtifactReader implements ArtifactReader { readonly format = "file" as const; #command: ArtifactCommand | undefined; + #source: StableRegularFileDescriptor | undefined; + #pendingSource: Promise | undefined; + readonly #ownsSource: boolean; + #closed = false; + #closePromise: Promise | undefined; constructor( private readonly path: string, @@ -31,9 +41,15 @@ export class MachOSliceArtifactReader implements ArtifactReader { private readonly runner: NativeCommandRunner = new XcrunCommandRunner( environment, ), - ) {} + source?: StableRegularFileDescriptor, + ) { + this.#source = source; + this.#ownsSource = source === undefined; + } async *entries(signal?: AbortSignal): AsyncIterable { + const source = await this.#ensureSource(); + await this.#verifySource(source); const captured = await this.runner.run( "lipo", ["-detailed_info", this.path], @@ -53,9 +69,11 @@ export class MachOSliceArtifactReader implements ArtifactReader { exit_code: captured.value.exitCode, effects: ["read"], }; - const fileSize = (await stat(this.path)).size; + await this.#verifySource(source); + const fileSize = source.initial.size; const architectures = parseLipoArchitectures(captured.value.stdout); - const structural = await readStructuralSlices(this.path, fileSize); + const structural = await readStructuralSlices(source.handle, fileSize); + await this.#verifySource(source); if (structural.status === "malformed") throw new ArtifactReaderFailure( "integrity", @@ -168,22 +186,28 @@ export class MachOSliceArtifactReader implements ArtifactReader { "integrity", "Invalid Mach-O slice byte range", ); - const fileSize = (await stat(this.path)).size; - if (!Number.isSafeInteger(offset + size) || offset + size > fileSize) + const source = await this.#ensureSource(); + await this.#verifySource(source); + if ( + !Number.isSafeInteger(offset + size) || + offset + size > source.initial.size + ) throw new ArtifactReaderFailure( "integrity", `Mach-O slice range is outside the artifact: ${entry.path}`, ); - const source = createReadStream(this.path, { + const sourceStream = source.handle.createReadStream({ start: offset, end: offset + size - 1, + autoClose: false, ...(signal === undefined ? {} : { signal }), }); + const verifySource = () => this.#verifySource(source); return Readable.from( (async function* () { let observedBytes = 0; try { - for await (const raw of source) { + for await (const raw of sourceStream) { const chunk = streamChunkToBuffer(raw); observedBytes += chunk.byteLength; if (observedBytes > size) @@ -212,6 +236,7 @@ export class MachOSliceArtifactReader implements ArtifactReader { "integrity", `Mach-O slice size disagrees with lipo metadata: ${entry.path}`, ); + await verifySource(); })(), ); } @@ -220,28 +245,80 @@ export class MachOSliceArtifactReader implements ArtifactReader { return this.#command === undefined ? [] : [structuredClone(this.#command)]; } - close(): Promise { - return Promise.resolve(); + async close(): Promise { + this.#closed = true; + this.#closePromise ??= this.#closeSource().catch((cause: unknown) => { + this.#closePromise = undefined; + throw cause; + }); + return this.#closePromise; + } + + async #ensureSource(): Promise { + if (this.#closed) + throw new ArtifactReaderFailure( + "unavailable", + "Universal Mach-O reader is closed", + ); + if (this.#source !== undefined) return this.#source; + this.#pendingSource ??= this.#acquireSource(); + const source = await this.#pendingSource; + if (this.#closed) + throw new ArtifactReaderFailure( + "unavailable", + "Universal Mach-O reader closed during source acquisition", + ); + return source; + } + + async #acquireSource(): Promise { + const handle = await openRegularFile(this.path, { symlinks: "reject" }); + try { + const initial = await handle.stat(); + const source = { handle, initial }; + this.#source = source; + return source; + } catch (cause: unknown) { + await handle.close().catch(() => undefined); + throw cause; + } + } + + async #closeSource(): Promise { + await this.#pendingSource?.catch(() => undefined); + if (!this.#ownsSource || this.#source === undefined) return; + const source = this.#source; + await source.handle.close(); + this.#source = undefined; + } + + async #verifySource(source: StableRegularFileDescriptor): Promise { + const [opened, currentPath] = await Promise.all([ + source.handle.stat(), + lstat(this.path), + ]); + if ( + !sameRegularFileState(source.initial, opened) || + !sameRegularFileState(source.initial, currentPath) + ) + throw new ArtifactReaderFailure( + "integrity", + `Universal Mach-O source changed during inventory: ${this.path}`, + ); } } /** Compare lipo's independent ranges with structurally parsed slice identity. */ const readStructuralSlices = async ( - path: string, + file: FileHandle, size: number, ): Promise>> => { - const file = await openFile(path, "r"); - try { - const readAt: ReadAt = async (offset, length) => { - const bytes = Buffer.alloc(length); - const { bytesRead } = await file.read(bytes, 0, length, offset); - return bytes.subarray(0, bytesRead); - }; - const facts = await readMachoImage(readAt, size); - return facts; - } finally { - await file.close(); - } + const readAt: ReadAt = async (offset, length) => { + const bytes = Buffer.alloc(length); + const { bytesRead } = await file.read(bytes, 0, length, offset); + return bytes.subarray(0, bytesRead); + }; + return readMachoImage(readAt, size); }; const lipoMatchesSlice = ( diff --git a/src/artifacts/inventory/classify.ts b/src/artifacts/inventory/classify.ts index 6e69c64c8..fbb8215a1 100644 --- a/src/artifacts/inventory/classify.ts +++ b/src/artifacts/inventory/classify.ts @@ -24,7 +24,7 @@ interface RootClassification { } type RootInventoryClassification = RootClassification & { - readonly zipSource: StableRegularFileDescriptor | undefined; + readonly rootSource: StableRegularFileDescriptor | undefined; }; /** Classify and hash one file root through the same stable open descriptor. */ @@ -43,7 +43,7 @@ export const classifyAndHashRoot = async ( try { return { format: result.format, digest: result.digest }; } finally { - await result.zipSource?.handle.close(); + await result.rootSource?.handle.close(); } }; @@ -55,7 +55,7 @@ export const classifyAndHashRootForInventory = async ( signal?: AbortSignal, ): Promise => { if (directory) - return { format: "directory", digest: null, zipSource: undefined }; + return { format: "directory", digest: null, rootSource: undefined }; const handle = await openRootFile(path, signal); let transferHandle = false; try { @@ -72,12 +72,12 @@ export const classifyAndHashRootForInventory = async ( initial, signal, ); - const zipSource = isZipFormat(format); - if (zipSource) transferHandle = true; + const retainSource = isZipFormat(format) || format === "mach-o-universal"; + if (retainSource) transferHandle = true; return { format, digest, - zipSource: zipSource ? { handle, initial } : undefined, + rootSource: retainSource ? { handle, initial } : undefined, }; } finally { if (!transferHandle) await handle.close(); diff --git a/src/artifacts/inventory/reader.ts b/src/artifacts/inventory/reader.ts index 21ad5adea..33e5a195a 100644 --- a/src/artifacts/inventory/reader.ts +++ b/src/artifacts/inventory/reader.ts @@ -13,7 +13,7 @@ export const createReader = async ( format: ArtifactOccurrence["artifact_format"], environment: Readonly, signal?: AbortSignal, - zipSource?: StableRegularFileDescriptor, + rootSource?: StableRegularFileDescriptor, ): Promise => { switch (format) { case "directory": @@ -23,12 +23,12 @@ export const createReader = async ( case "apk": case "msix": case "appx": - return new ZipArtifactReader(path, format, undefined, zipSource); + return new ZipArtifactReader(path, format, undefined, rootSource); case "asar": return new AsarArtifactReader(path); case "mach-o-universal": return process.platform === "darwin" - ? new MachOSliceArtifactReader(path, environment) + ? new MachOSliceArtifactReader(path, environment, undefined, rootSource) : undefined; case "dmg": if (process.platform !== "darwin") return undefined; diff --git a/src/artifacts/inventory/scanCanonical.ts b/src/artifacts/inventory/scanCanonical.ts index 9ae0db083..bec77ca1f 100644 --- a/src/artifacts/inventory/scanCanonical.ts +++ b/src/artifacts/inventory/scanCanonical.ts @@ -58,7 +58,7 @@ export const scanCanonicalArtifactInventory = async ( const { format: rootFormat, digest: rootDigest, - zipSource, + rootSource, } = await classifyAndHashRootForInventory( path, metadata.isDirectory(), @@ -73,7 +73,7 @@ export const scanCanonicalArtifactInventory = async ( rootFormat, options.environment ?? {}, options.signal, - zipSource, + rootSource, ); } catch (cause: unknown) { readerCreationFailure = { cause }; @@ -102,7 +102,7 @@ export const scanCanonicalArtifactInventory = async ( metadata, rootFormat, rootDigest, - zipSource, + rootSource, reader, signal: options.signal, nodes, @@ -133,13 +133,13 @@ export const scanCanonicalArtifactInventory = async ( ); } } - if (zipSource !== undefined) { + if (rootSource !== undefined) { try { - await zipSource.handle.close(); + await rootSource.handle.close(); } catch (cleanupCause: unknown) { const cleanup = ArtifactReaderFailure.cleanupObservation( cleanupCause, - `root ZIP descriptor for ${path}`, + `root artifact descriptor for ${path}`, ); cleanupFailure = ArtifactReaderFailure.withCleanup( cleanupFailure ?? @@ -161,7 +161,7 @@ interface SnapshotBuildInput { readonly metadata: Stats; readonly rootFormat: ArtifactOccurrence["artifact_format"]; readonly rootDigest: HashResult | null; - readonly zipSource: StableRegularFileDescriptor | undefined; + readonly rootSource: StableRegularFileDescriptor | undefined; readonly reader: ArtifactReader | undefined; readonly signal: AbortSignal | undefined; readonly nodes: Map; @@ -173,7 +173,7 @@ interface SnapshotBuildInput { const buildInventorySnapshot = async ( input: SnapshotBuildInput, ): Promise => { - const { path, metadata, rootFormat, rootDigest, zipSource, reader, signal } = + const { path, metadata, rootFormat, rootDigest, rootSource, reader, signal } = input; materializeDirectoryNodes(input.occurrences, input.nodes); const rootNode = createRootNode({ @@ -218,7 +218,7 @@ const buildInventorySnapshot = async ( ordinal, })); - await verifyRootDigest(path, rootDigest, zipSource, signal); + await verifyRootDigest(path, rootDigest, rootSource, signal); const graphSha256 = artifactGraphDigest({ nodes: orderedNodes, @@ -293,17 +293,17 @@ const buildIntegrityContradictions = ( const verifyRootDigest = async ( path: string, rootDigest: HashResult | null, - zipSource: StableRegularFileDescriptor | undefined, + rootSource: StableRegularFileDescriptor | undefined, signal: AbortSignal | undefined, ): Promise => { if (rootDigest === null) return; const verified = - zipSource === undefined + rootSource === undefined ? await hashStableRootArtifact(path, signal) : await hashStableRootArtifactHandle( path, - zipSource.handle, - zipSource.initial, + rootSource.handle, + rootSource.initial, signal, ); if ( diff --git a/src/cliJsonInput.ts b/src/cliJsonInput.ts index 47b1431e4..4dd38a90e 100644 --- a/src/cliJsonInput.ts +++ b/src/cliJsonInput.ts @@ -1,6 +1,6 @@ import { resolve } from "node:path"; -import { readCliJsonFile } from "./cliJsonFile.js"; +import { readJsonInputFile } from "./application/JsonInputFile.js"; import { NonRegularFileReadError } from "./filesystem/RegularFile.js"; import { AnalysisAccessDeniedError, @@ -21,7 +21,7 @@ export const parseCliJsonInput = async ( const inline = safeParseJson(value); if (inline.ok) return { ok: true, value: inline.value }; try { - const parsed = await readCliJsonFile(value, operation); + const parsed = await readJsonInputFile(value, operation); return parsed.ok ? { ok: true, value: parsed.value } : { diff --git a/src/domain/adb/adbDeviceAnalysis.ts b/src/domain/adb/adbDeviceAnalysis.ts index 5966f508b..37c72dbca 100644 --- a/src/domain/adb/adbDeviceAnalysis.ts +++ b/src/domain/adb/adbDeviceAnalysis.ts @@ -699,3 +699,39 @@ export const adbResultSchemas = { package_name: packageNameSchema, }), } as const; + +/** Acquired package facts retained when cancellation leaves caller-owned output. */ +export type AdbPackagePullPartialObservation = { + readonly provider_id: "adb"; + readonly operation: "pull_adb_package"; + readonly result: z.infer; +}; + +/** A completed acquisition whose digest read was cancelled before verification. */ +export type AdbAcquiredFilePartialObservation = + | { + readonly provider_id: "adb"; + readonly operation: "pull_adb_file"; + readonly result: { + readonly client: z.infer< + typeof adbResultSchemas.pull_adb_file + >["client"]; + readonly serial: string; + readonly local_path: string; + readonly device_path: string; + readonly digest_status: "unknown"; + }; + } + | { + readonly provider_id: "adb"; + readonly operation: "collect_adb_bugreport"; + readonly result: { + readonly client: z.infer< + typeof adbResultSchemas.collect_adb_bugreport + >["client"]; + readonly serial: string; + readonly local_path: string; + readonly adb_reported_path: string; + readonly digest_status: "unknown"; + }; + }; diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.ts index 172adda8e..afe271b8e 100644 --- a/src/domain/analysisErrorBase.ts +++ b/src/domain/analysisErrorBase.ts @@ -99,6 +99,10 @@ import type { BrowserScenarioPartialObservation } from "./browserScenarioCapture import type { Evidence } from "./evidence.js"; import type { AndroidPartialObservation } from "./android/androidPartialObservation.js"; import type { FirmwarePartialObservation } from "./firmware/firmwareAnalysis.js"; +import type { + AdbAcquiredFilePartialObservation, + AdbPackagePullPartialObservation, +} from "./adb/adbDeviceAnalysis.js"; import type { NativeUiObservationResult } from "./native/nativeUiObservation.js"; /** Provider-neutral evidence collected before a typed analysis failure. */ @@ -113,4 +117,6 @@ export type AnalysisPartialObservation = | Evidence | AndroidPartialObservation | FirmwarePartialObservation - | NativeUiObservationResult; + | NativeUiObservationResult + | AdbAcquiredFilePartialObservation + | AdbPackagePullPartialObservation; diff --git a/src/filesystem/RegularFile.ts b/src/filesystem/RegularFile.ts index b9a0914c3..69edcad31 100644 --- a/src/filesystem/RegularFile.ts +++ b/src/filesystem/RegularFile.ts @@ -16,6 +16,15 @@ export class NonRegularFileReadError 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}`); + this.name = "RegularFileChangedError"; + } +} + /** One admitted file descriptor and the metadata that identified its contents. */ export interface StableRegularFileDescriptor { readonly handle: FileHandle; diff --git a/src/filesystem/StableFileHash.ts b/src/filesystem/StableFileHash.ts new file mode 100644 index 000000000..11c919361 --- /dev/null +++ b/src/filesystem/StableFileHash.ts @@ -0,0 +1,55 @@ +import { createHash } from "node:crypto"; +import { stat } from "node:fs/promises"; + +import { + openRegularFile, + RegularFileChangedError, + sameRegularFileState, +} from "./RegularFile.js"; + +/** Hash one regular file from its admitted descriptor and verify its path state. */ +export const hashStableFile = async ( + path: string, + signal?: AbortSignal, +): Promise<{ readonly sha256: string; readonly bytes: number }> => { + const handle = await openRegularFile(path, { + symlinks: "follow", + signal, + }); + try { + const initial = await handle.stat(); + if (!Number.isSafeInteger(initial.size) || initial.size < 0) + throw new RangeError( + `Regular file size cannot be represented safely: ${path}`, + ); + const hash = createHash("sha256"); + const chunk = Buffer.allocUnsafe(64 * 1024); + let position = 0; + while (position <= initial.size) { + signal?.throwIfAborted(); + const length = Math.min(chunk.length, initial.size - position + 1); + if (length <= 0) break; + const read = await handle.read(chunk, 0, length, position); + signal?.throwIfAborted(); + if (read.bytesRead === 0) break; + hash.update(chunk.subarray(0, read.bytesRead)); + position += read.bytesRead; + if (position > initial.size) throw new RegularFileChangedError(path); + } + signal?.throwIfAborted(); + const [opened, currentPath] = await Promise.all([ + handle.stat(), + stat(path), + ]); + signal?.throwIfAborted(); + if ( + position !== initial.size || + !sameRegularFileState(initial, opened) || + !sameRegularFileState(initial, currentPath) + ) + throw new RegularFileChangedError(path); + return { sha256: hash.digest("hex"), bytes: position }; + } finally { + await handle.close(); + } +}; diff --git a/src/server/createServer.ts b/src/server/createServer.ts index 3692cb4e1..0523006a6 100644 --- a/src/server/createServer.ts +++ b/src/server/createServer.ts @@ -242,6 +242,7 @@ export const createServer = ( android.close(), apktool.close(), jeb.close(), + adbDevice.close(), evmInterface.close(), webSourceLocation.close(), javascriptRecovery.close?.() ?? Promise.resolve(), diff --git a/tests/boundary/filesystem/cliJsonInput.test.ts b/tests/boundary/filesystem/cliJsonInput.test.ts index dd4809ea8..d2bdcd540 100644 --- a/tests/boundary/filesystem/cliJsonInput.test.ts +++ b/tests/boundary/filesystem/cliJsonInput.test.ts @@ -7,7 +7,7 @@ import { describe, expect, it, onTestFinished } from "vitest"; import { createCli } from "../../../src/cli.js"; import { parseCliJsonInput } from "../../../src/cliJsonInput.js"; -import { readCliJsonFile } from "../../../src/cliJsonFile.js"; +import { readJsonInputFile } from "../../../src/application/JsonInputFile.js"; import { analysisCliErrorEnvelopeSchema } from "../../../src/contracts/errorSchemas.js"; import { JSON_BYTE_ORDER_MARK_MESSAGE } from "../../../src/application/Utf8JsonInput.js"; import { readWithoutFifoWriter } from "../../fixtures/fifoInput.js"; @@ -203,11 +203,11 @@ describe("CLI JSON streamed input", () => { const path = join(root, "input.json"); await writeFile(path, `${" ".repeat(9 * 1024 * 1024)}{"after":true}`); const controller = new AbortController(); - const cancelled = readCliJsonFile(path, "test-input", controller.signal); + const cancelled = readJsonInputFile(path, "test-input", controller.signal); setImmediate(() => controller.abort(new Error("cancel JSON file parse"))); await expect(cancelled).rejects.toThrow("cancel JSON file parse"); await writeFile(path, '{"after":true}'); - expect(await readCliJsonFile(path, "test-input")).toEqual({ + expect(await readJsonInputFile(path, "test-input")).toEqual({ ok: true, value: { after: true }, }); diff --git a/tests/boundary/process/jadxIntegration.test.ts b/tests/boundary/process/jadxIntegration.test.ts index 5d79199bb..93ffa475b 100644 --- a/tests/boundary/process/jadxIntegration.test.ts +++ b/tests/boundary/process/jadxIntegration.test.ts @@ -4,10 +4,8 @@ import { parseBinaryTarget } from "../../../src/application/BinaryTargetResolver import { AndroidAnalysisService } from "../../../src/application/android/AndroidAnalysisService.js"; import { JadxProvider } from "../../../src/android/JadxProvider.js"; import { androidResultSchemas } from "../../../src/domain/android/androidAnalysis.js"; -import { - hashAndroidFile, - snapshotAndroidEngine, -} from "../../../src/android/AndroidTargetSnapshot.js"; +import { snapshotAndroidEngine } from "../../../src/android/AndroidTargetSnapshot.js"; +import { hashStableFile } from "../../../src/filesystem/StableFileHash.js"; import { PrivateRuntimeRoot } from "../../../src/process/PrivateRuntimeRoot.js"; import { createJadxProtocolFixture as setup, @@ -43,7 +41,7 @@ it("cancels Android admission while hashing the selected APK", async () => { it("rejects a copied JAR that differs from its admitted session identity", async () => { const { jar } = await setup(); - const admitted = await hashAndroidFile(jar); + const admitted = (await hashStableFile(jar)).sha256; await writeFile(jar, "engine changed between hashing and copying"); const root = await PrivateRuntimeRoot.create({ prefix: "rea-jadx-admission-",