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(apktool): own file and workspace finalization
morluto4844ae812b35
diff --git a/src/apktool/ApktoolCommandCleanup.ts b/src/apktool/ApktoolCommandCleanup.tsindex f720ef280..62b3188f8 100644--- a/src/apktool/ApktoolCommandCleanup.ts+++ b/src/apktool/ApktoolCommandCleanup.ts@@ -2,7 +2,10 @@ import {AnalysisCleanupLease,AnalysisCleanupLeaseGroup,} from "../artifacts/AnalysisCleanupLease.js";-import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import {+ ArtifactResourceRetryFailure,+ ArtifactResourceScope,+} from "../artifacts/ArtifactResourceScope.js";import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";import { AnalysisError } from "../domain/analysisErrorBase.js";import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";@@ -166,8 +169,13 @@ export class ApktoolCommandCleanup {#retryFailure(cause: unknown, operation: string): unknown {if (- !(cause instanceof ArtifactReaderFailure) ||- cause.cleanup === undefined+ !(cause instanceof ArtifactResourceRetryFailure) ||+ cause.cleanup === undefined ||+ !cause.failedOwners.every(+ (failed) =>+ failed.kind === "lease" &&+ [...this.#owners].some((owner) => owner.lease === failed.lease),+ ))return cause;const owners = [...this.#owners].filter((owner) => !owner.lease.released);diff --git a/src/apktool/ApktoolDecodedInventory.ts b/src/apktool/ApktoolDecodedInventory.tsnew file mode 100644index 000000000..16b6b91e9--- /dev/null+++ b/src/apktool/ApktoolDecodedInventory.ts@@ -0,0 +1,40 @@+import { access } from "node:fs/promises";+import { join } from "node:path";+import { DirectoryArtifactTraversalLimit } from "../artifacts/DirectoryArtifactReader.js";+import { assertArtifactReadActive } from "../artifacts/ArtifactFileOperation.js";+import { androidLocaleQualifierSchema } from "../domain/apktool/apktoolResourceAnalysis.js";+import type { ApktoolWorkspace } from "./ApktoolWorkspace.js";++/** Count files over bounded examined coverage, including omitted special entries. */+export const countDecodedFiles = async (+ workspace: ApktoolWorkspace,+ root: string,+ signal: AbortSignal | undefined,+ maximumEntries: number,+): Promise<{ count: number; capped: boolean; locales: readonly string[] }> => {+ let count = 0;+ let capped = false;+ const locales: string[] = [];+ try {+ for await (const entry of workspace.entries(root, signal, maximumEntries)) {+ assertArtifactReadActive(signal);+ if (entry.kind === "file") count += 1;+ if (entry.kind === "directory") {+ const match = /^res\/values-(.+)$/u.exec(entry.path);+ if (+ match !== null &&+ androidLocaleQualifierSchema.safeParse(match[1]).success &&+ (await access(join(root, entry.path, "strings.xml")).then(+ () => true,+ () => false,+ ))+ )+ locales.push(match[1]!);+ }+ }+ } catch (cause) {+ if (!(cause instanceof DirectoryArtifactTraversalLimit)) throw cause;+ capped = true;+ }+ return { count, capped, locales: locales.sort() };+};diff --git a/src/apktool/ApktoolProvider.test.ts b/src/apktool/ApktoolProvider.test.tsindex 938e08dd2..3edff9dcc 100644--- a/src/apktool/ApktoolProvider.test.ts+++ b/src/apktool/ApktoolProvider.test.ts@@ -1,14 +1,17 @@+import { createDeferred } from "../../tests/fixtures/binarySession.js";+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";import { createHash } from "node:crypto";import {chmod,mkdtemp,readFile,+ stat,rm,truncate,writeFile,} from "node:fs/promises";import { join } from "node:path";-import { describe, expect, onTestFinished, test } from "vitest";+import { describe, expect, onTestFinished, test, vi } from "vitest";import { ApktoolProvider } from "./ApktoolProvider.js";import { ApktoolResourceAnalysisService } from "../application/apktool/ApktoolResourceAnalysisService.js";@@ -622,3 +625,236 @@ it("accepts a BCP47 resource qualifier through the public request schema", asyncconst result = await evidenceResult(providerOver(command), request);expect(result.strings).toEqual([{ name: "greeting", value: "你好" }]);});++it("retains completed Evidence and live cleanup until a denied workspace removal recovers", async () => {+ const { command, root } = await writeApktoolStub(decodeStub());+ const apk = await apkFixture(root);+ let denied = true;+ let owned: string | undefined;+ const provider = new ApktoolProvider({+ environment: { REA_APKTOOL_COMMAND: command },+ removeWorkspace: async (path) => {+ owned = path;+ if (denied) throw new Error("authored removal denial");+ await rm(path, { recursive: true, force: true });+ },+ });+ try {+ const result = await provider.execute({+ operation: "decode_android_resources",+ input: { path: apk.path, include_strings: true },+ });+ if (result.ok) throw new Error("Expected cleanup failure");+ expect(result.error.cleanupIncomplete).toBe(true);+ expect(result.error.partialObservation).toMatchObject({+ operation: "decode_android_resources",+ subject: { local_path: apk.path, digest: { sha256: apk.sha256 } },+ normalized_result: {+ metadata: { package_name: "com.rea.apktool.probe" },+ strings: [+ { name: "api_endpoint", value: "https://api.example.com/v1" },+ { name: "app_name", value: "ApktoolProbe" },+ ],+ },+ });+ const blocked = await provider.execute({+ operation: "inspect_apktool_client",+ input: {},+ });+ if (blocked.ok)+ throw new Error("Expected retained-workspace admission refusal");+ expect(blocked.error.cleanupIncomplete).toBe(true);+ expect(blocked.error.cleanupResources).toContain(owned);+ await expect(provider.close()).rejects.toMatchObject({+ cleanupIncomplete: true,+ });+ denied = false;+ await provider.close();+ expect(result.error.cleanupIncomplete).toBe(false);+ expect(blocked.error.cleanupIncomplete).toBe(false);+ expect(result.error.partialObservation).toMatchObject({+ normalized_result: { target: { sha256: apk.sha256 } },+ });+ } finally {+ denied = false;+ await provider.close();+ }+});++it.each([false, true])(+ "preserves completed Evidence and cancellation during workspace cleanup (denied=%s)",+ async (deniedInitially) => {+ const { command, root } = await writeApktoolStub(decodeStub());+ const apk = await apkFixture(root);+ const controller = new AbortController();+ const reason = { caller: "during final workspace removal" };+ let denied = deniedInitially;+ const provider = new ApktoolProvider({+ environment: { REA_APKTOOL_COMMAND: command },+ removeWorkspace: async (path) => {+ controller.abort(reason);+ if (denied) throw new Error("authored denial");+ await rm(path, { recursive: true, force: true });+ },+ });+ try {+ const result = await provider.execute(+ {+ operation: "decode_android_resources",+ input: { path: apk.path, include_strings: true },+ },+ { signal: controller.signal },+ );+ if (result.ok) throw new Error("Expected finalization cancellation");+ const primary = result.error.cleanupPrimary ?? result.error;+ expect(primary._tag).toBe("AnalysisCancelledError");+ expect(primary.cause).toBe(reason);+ expect(result.error.cleanupIncomplete).toBe(deniedInitially);+ expect(result.error.partialObservation).toMatchObject({+ operation: "decode_android_resources",+ normalized_result: { target: { sha256: apk.sha256 } },+ });+ denied = false;+ await provider.close();+ expect(result.error.cleanupIncomplete).toBe(false);+ } finally {+ denied = false;+ await provider.close();+ }+ },+);++it.each(["decode", "projection"] as const)(+ "keeps a recorded %s failure primary when cancellation arrives during removal",+ async (stage) => {+ const { command, root } = await writeApktoolStub(+ decodeStub({ failDecode: stage === "decode" }),+ );+ const apk = await apkFixture(root);+ if (stage === "projection") {+ const bad = join(root, "bad.xml");+ await writeFile(bad, Buffer.from([0xff]));+ await writeFile(+ command,+ "#!/bin/sh\n" + decodeStub({ stringsFile: bad })(root),+ { mode: 0o755 },+ );+ }+ const controller = new AbortController();+ const provider = new ApktoolProvider({+ environment: { REA_APKTOOL_COMMAND: command },+ removeWorkspace: async (path) => {+ controller.abort({ caller: "after decode refusal" });+ await rm(path, { recursive: true, force: true });+ },+ });+ try {+ const result = await provider.execute(+ {+ operation: "decode_android_resources",+ input: { path: apk.path, include_strings: true },+ },+ { signal: controller.signal },+ );+ if (result.ok) throw new Error("Expected decode refusal");+ expect(controller.signal.aborted).toBe(true);+ expect(result.error._tag).toBe(+ stage === "decode"+ ? "AnalysisUnsupportedTargetError"+ : "AnalysisProtocolError",+ );+ if (stage === "decode")+ expect(result.error.capturedOutput?.stderr).toContain(+ "Could not decode the APK",+ );+ expect(result.error.partialObservation).toMatchObject({+ kind: "file-snapshot-hash",+ path: apk.path,+ sha256: apk.sha256,+ });+ } finally {+ await provider.close();+ }+ },+);++it("releases successful workspace peers once while retaining a denied peer for retry", async () => {+ const { command, root } = await writeApktoolStub(decodeStub());+ const apk = await apkFixture(root);+ let deniedRoot: string | undefined;+ let denied = true;+ const attempts = new Map<string, number>();+ const provider = new ApktoolProvider({+ environment: { REA_APKTOOL_COMMAND: command },+ removeWorkspace: async (path) => {+ attempts.set(path, (attempts.get(path) ?? 0) + 1);+ deniedRoot ??= path;+ if (path === deniedRoot && denied)+ throw new Error("authored peer denial");+ await rm(path, { recursive: true, force: true });+ },+ });+ try {+ const request = {+ operation: "decode_android_resources" as const,+ input: { path: apk.path, include_strings: true },+ };+ const results = await Promise.all([+ provider.execute(request),+ provider.execute(request),+ ]);+ expect(results.filter((result) => result.ok)).toHaveLength(1);+ const retained = results.find((result) => !result.ok);+ if (retained === undefined || retained.ok)+ throw new Error("Expected retained peer");+ expect(attempts.size).toBe(2);+ await expect(provider.close()).rejects.toMatchObject({+ cleanupIncomplete: true,+ });+ denied = false;+ await provider.close();+ expect(retained.error.cleanupIncomplete).toBe(false);+ for (const [path, count] of attempts)+ expect(count).toBe(path === deniedRoot ? 3 : 1);+ } finally {+ denied = false;+ await provider.close();+ }+});++it("joins a late workspace allocation during shutdown and removes its owned root", async () => {+ const { command, root } = await writeApktoolStub(decodeStub());+ const apk = await apkFixture(root);+ const created = createDeferred<string>();+ const release = createDeferred<void>();+ const allocate = PrivateRuntimeRoot.create.bind(PrivateRuntimeRoot);+ const allocation = vi+ .spyOn(PrivateRuntimeRoot, "create")+ .mockImplementationOnce(async (options) => {+ const runtime = await allocate(options);+ created.resolve(runtime.path);+ await release.promise;+ return runtime;+ });+ const provider = providerOver(command);+ const pending = provider.execute({+ operation: "decode_android_resources",+ input: { path: apk.path, include_strings: true },+ });+ let closing: Promise<void> | undefined;+ try {+ const owned = await created.promise;+ closing = provider.close();+ release.resolve();+ const result = await pending;+ if (result.ok) throw new Error("Expected shutdown cancellation");+ expect(result.error._tag).toBe("AnalysisCancelledError");+ await closing;+ await expect(stat(owned)).rejects.toMatchObject({ code: "ENOENT" });+ } finally {+ release.resolve();+ await pending;+ allocation.mockRestore();+ await (closing ?? provider.close());+ }+});diff --git a/src/apktool/ApktoolProvider.ts b/src/apktool/ApktoolProvider.tsindex 8e4c5c288..d4a748a10 100644--- a/src/apktool/ApktoolProvider.ts+++ b/src/apktool/ApktoolProvider.ts@@ -1,25 +1,24 @@+import { countDecodedFiles } from "./ApktoolDecodedInventory.js";+import { ApktoolWorkspace } from "./ApktoolWorkspace.js";+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import {+ AnalysisCleanupLease,+ AnalysisCleanupLeaseGroup,+} from "../artifacts/AnalysisCleanupLease.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import {+ ArtifactFileCleanupFailure,+ artifactFilePrimaryFailure,+ artifactFileCancellationCause,+} from "../artifacts/ArtifactFileOperation.js";+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";import { capturedApktoolCommandOutput } from "./ApktoolCommandOutput.js";import { ApktoolCommandCleanup } from "./ApktoolCommandCleanup.js";import { AnalysisError } from "../domain/analysisErrorBase.js";import { analysisClientFailureForOperation } from "../providers/AnalysisClientFailure.js";-import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";-import { createHash, randomUUID } from "node:crypto";-import { createWriteStream } from "node:fs";-import {- access,- chmod,- mkdir,- mkdtemp,- opendir,- open,- rm,- stat,-} from "node:fs/promises";-import { tmpdir } from "node:os";+import { randomUUID } from "node:crypto";+import { mkdir } from "node:fs/promises";import { join } from "node:path";-import { Transform, type TransformCallback } from "node:stream";-import { pipeline } from "node:stream/promises";-import type { FileHandle } from "node:fs/promises";import type {ExecutionOptions,@@ -28,16 +27,13 @@ import type {import { providerConfigurationRefusal } from "../domain/providerConfigurationRefusal.js";import {createAnalysisExecution,+ createAnalysisExecutionEvidence,type AnalysisExecution,} from "../application/AnalysisProvider.js";-import {- androidLocaleQualifierSchema,- type ApktoolRequest,-} from "../domain/apktool/apktoolResourceAnalysis.js";+import type { ApktoolRequest } from "../domain/apktool/apktoolResourceAnalysis.js";import {AnalysisCapabilityUnavailableError,AnalysisCancelledError,- AnalysisInputError,AnalysisProtocolError,AnalysisResourceConstraintError,AnalysisTimeoutError,@@ -46,10 +42,6 @@ import {import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";import { err, ok, type Result } from "../domain/result.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";-import {- openRegularFile,- sameRegularFileState,-} from "../filesystem/RegularFile.js";import {OwnedCommandFailure,runOwnedCommand,@@ -95,55 +87,6 @@ const throwIfCancelled = (throw new AnalysisCancelledError(operation, { cause: signal.reason });};-/** Read at most the byte budget plus one byte, before decoding UTF-8. */-const readBoundedText = async (- path: string,- budget: number,- operation: string,- signal: AbortSignal | undefined,-): Promise<{ text: string | null; truncated: boolean }> => {- const file = await open(path, "r").catch((cause: unknown) => {- if ((cause as NodeJS.ErrnoException).code === "ENOENT") return null;- throw cause;- });- if (file === null) return { text: null, truncated: false };- try {- throwIfCancelled(operation, signal);- const bytes = Buffer.alloc(budget + 1);- let length = 0;- while (length < bytes.length) {- throwIfCancelled(operation, signal);- const result = await file.read(- bytes,- length,- bytes.length - length,- null,- );- if (result.bytesRead === 0) break;- length += result.bytesRead;- }- throwIfCancelled(operation, signal);- const truncated = length > budget;- // A prefix may end within a UTF-8 character; omit those trailing bytes.- try {- const decoder = new TextDecoder("utf-8", { fatal: true });- return {- text: decoder.decode(bytes.subarray(0, Math.min(length, budget)), {- stream: truncated,- }),- truncated,- };- } catch (cause: unknown) {- throw new AnalysisProtocolError(- `apktool produced invalid UTF-8 in ${path}`,- { cause },- );- }- } finally {- await file.close();- }-};-const localeQualifier = (locale: string): string =>locale.replace(/^([a-z]{2,3})-([A-Z]{2}|[0-9]{3})$/u, "$1-r$2");@@ -259,52 +202,6 @@ const apktoolCommandFailure = ();};-/** Count files while bounding streamed directory-entry traversal. */-const countDecodedFiles = async (- root: string,- signal: AbortSignal | undefined,- operation: string,-): Promise<{- count: number;- capped: boolean;- locales: readonly string[];-}> => {- let count = 0;- let capped = false;- let visited = 0;- const directories = [root];- const locales: string[] = [];- while (directories.length > 0 && !capped) {- throwIfCancelled(operation, signal);- const directory = directories.pop()!;- for await (const entry of await opendir(directory)) {- throwIfCancelled(operation, signal);- if (visited >= MAX_DECODED_ENTRIES_VISITED) {- capped = true;- break;- }- visited += 1;- const path = join(directory, entry.name);- if (entry.isDirectory()) {- directories.push(path);- if (directory === join(root, "res")) {- const match = /^values-(.+)$/u.exec(entry.name);- if (- match !== null &&- androidLocaleQualifierSchema.safeParse(match[1]).success &&- (await access(join(path, "strings.xml")).then(- () => true,- () => false,- ))- )- locales.push(match[1]!);- }- } else if (entry.isFile()) count += 1;- }- }- return { count, capped, locales: locales.sort() };-};-export interface ApktoolProviderOptions {readonly environment?: Readonly<Record<string, string | undefined>>;readonly removeWorkspace?: (path: string) => Promise<void>;@@ -322,8 +219,10 @@ export class ApktoolProvider {| Readonly<Record<string, string | undefined>>| undefined;- private readonly workspaces = new Set<string>();- private readonly removeWorkspace: (path: string) => Promise<void>;+ readonly #artifacts = new ArtifactResourceScope();+ private readonly removeWorkspace:+ | ((path: string) => Promise<void>)+ | undefined;readonly #commands = new ApktoolCommandCleanup();readonly #shutdown = new AbortController();readonly #active = new Set<Promise<void>>();@@ -335,9 +234,7 @@ export class ApktoolProvider {options.environment === undefined? undefined: snapshotEnvironment(options.environment);- this.removeWorkspace =- options.removeWorkspace ??- ((path) => rm(path, { recursive: true, force: true }));+ this.removeWorkspace = options.removeWorkspace;}private operationEnvironment(): Readonly<NodeJS.ProcessEnv> {@@ -363,10 +260,21 @@ export class ApktoolProvider {? this.#shutdown.signal: AbortSignal.any([signal, this.#shutdown.signal]);return this.#track(- this.#commands.run(- () => this.#inspectAvailability(operationSignal),- "inspect_apktool_client",- ),+ this.#commands+ .run(+ () =>+ this.#artifacts.run(() =>+ this.#inspectAvailability(operationSignal),+ ),+ "inspect_apktool_client",+ )+ .catch((cause: unknown) => {+ throw analysisClientFailureForOperation(+ cause,+ "apktool",+ "inspect_apktool_client",+ );+ }),);}@@ -427,7 +335,10 @@ export class ApktoolProvider {: AbortSignal.any([options.signal, this.#shutdown.signal]);return this.#track(this.#commands- .run(() => this.#execute(request, signal), request.operation)+ .run(+ () => this.#artifacts.run(() => this.#execute(request, signal)),+ request.operation,+ ).catch((cause: unknown) =>err(analysisClientFailureForOperation(@@ -524,18 +435,30 @@ export class ApktoolProvider {async #drainAndClean(): Promise<void> {await Promise.all(this.#active);- await this.#commands.close();- const failures: unknown[] = [];- for (const path of this.workspaces) {+ const failures: AnalysisError[] = [];+ for (const close of [+ () => this.#commands.close(),+ () => this.#artifacts.close(),+ ]) {try {- await this.removeWorkspace(path);- this.workspaces.delete(path);+ await close();} catch (cause) {- failures.push(cause);+ failures.push(+ analysisClientFailureForOperation(cause, "apktool", "close"),+ );}}- if (failures.length > 0)- throw new AggregateError(failures, "Apktool workspace cleanup failed");+ const first = failures.shift();+ if (first === undefined) return;+ throw failures.reduce(+ (primary, cleanup) =>+ analysisErrorWithCleanupFailure(+ primary,+ cleanup,+ "close",+ ).bindCleanupDependencies([primary, cleanup]),+ first,+ );}private async decodeResources(@@ -555,101 +478,27 @@ export class ApktoolProvider {},signal: AbortSignal | undefined,): Promise<Result<AnalysisExecution, AnalysisError>> {- const root = await mkdtemp(join(tmpdir(), "rea-apktool-"));- this.workspaces.add(root);+ const runtime = await PrivateRuntimeRoot.create({ prefix: "rea-apktool-" });+ const resources = new ApktoolWorkspace(+ runtime,+ this.#commands,+ this.removeWorkspace,+ );+ const root = resources.path;const workspace = join(root, "decoded");const snapshot = join(root, "input.apk");const framework = join(root, "framework");- let cleanupFailure: string | null = null;- // The workspace is removed before the result is returned, so an- // unremovable workspace is reported instead of silently abandoned.- const removeWorkspace = async (): Promise<void> => {- if (this.#commands.pendingFor(root)) {- cleanupFailure = `The decode workspace is retained until its apktool process stops: ${root}`;- return;- }- try {- await this.removeWorkspace(root);- this.workspaces.delete(root);- } catch {- cleanupFailure = `The decode workspace could not be removed: ${root}`;- }- };- const failureWithCleanup = (failure: AnalysisError): AnalysisError =>- cleanupFailure === null- ? failure- : analysisErrorWithCleanupFailure(- failure,- new ProviderCleanupError(- APKTOOL_PROVIDER_IDENTITY.id,- [root],- { reason: cleanupFailure },- { operation },- ),- operation,- );- let source: FileHandle | undefined;- let sourceAdmissionFailed = false;+ const lease = new AnalysisCleanupLease(() => resources.close(), [root]);+ const owner = { kind: "lease" as const, resource: root, lease };+ this.#artifacts.retain(owner);+ let result: Result<AnalysisExecution, AnalysisError>;try {- throwIfCancelled(operation, signal);- sourceAdmissionFailed = true;- source = await openRegularFile(input.path, {- symlinks: "follow",- ...(signal === undefined ? {} : { signal }),- });- const sourceInfo = await source.stat();- sourceAdmissionFailed = false;- const sourceSize = sourceInfo.size;- let copiedBytes = 0;- const sourceHash = createHash("sha256");- const boundedSource = new Transform({- transform(- chunk: Buffer,- _encoding: BufferEncoding,- callback: TransformCallback,- ) {- copiedBytes += chunk.length;- if (copiedBytes > sourceSize) {- callback(- new AnalysisInputError(operation, {- cause: new Error(- `The selected APK changed while being copied: ${input.path}`,- ),- }),- );- return;- }- sourceHash.update(chunk);- callback(null, chunk);- },- });- await pipeline(- source.createReadStream({- start: 0,- end: sourceSize,- autoClose: false,- ...(signal === undefined ? {} : { signal }),- }),- boundedSource,- createWriteStream(snapshot, { flags: "wx", mode: 0o600 }),- signal === undefined ? {} : { signal },+ const identity = await resources.snapshotInput(+ input.path,+ operation,+ signal,);- const finalSourceInfo = await source.stat();- if (- copiedBytes !== sourceSize ||- !sameRegularFileState(sourceInfo, finalSourceInfo)- )- throw new AnalysisInputError(operation, {- cause: new Error(- `The selected APK changed while being copied: ${input.path}`,- ),- });- const sha256 = sourceHash.digest("hex");- await source.close();- source = undefined;- await chmod(snapshot, 0o400);- throwIfCancelled(operation, signal);- const snapshotInfo = await stat(snapshot);+ const sha256 = identity.sha256;await mkdir(workspace);await mkdir(framework);const decoded = await runApktool(@@ -675,14 +524,12 @@ export class ApktoolProvider {root,);if (!decoded.ok) {- await removeWorkspace();- return err(failureWithCleanup(decoded.error));+ throw decoded.error;}throwIfCancelled(operation, signal);- const yml = await readBoundedText(+ const yml = await resources.readText(join(workspace, "apktool.yml"),MANIFEST_MAX_BYTES,- operation,signal,);if (yml.text === null || yml.truncated) {@@ -691,10 +538,9 @@ export class ApktoolProvider {);}const metadata = parseApktoolYml(yml.text);- const manifestRead = await readBoundedText(+ const manifestRead = await resources.readText(join(workspace, "AndroidManifest.xml"),MANIFEST_MAX_BYTES,- operation,signal,);const manifest = manifestRead.text;@@ -707,10 +553,9 @@ export class ApktoolProvider {? "values": `values-${localeQualifier(input.locale)}`;const stringsRead = input.include_strings- ? await readBoundedText(+ ? await resources.readText(join(workspace, "res", stringsDirectory, "strings.xml"),STRINGS_XML_MAX_BYTES,- operation,signal,): { text: null, truncated: false };@@ -721,7 +566,12 @@ export class ApktoolProvider {? { entries: [], unparsedCount: 0 }: parseDecodedStrings(stringsXml);const bounded = parsedStrings.entries.slice(0, MAX_STRINGS);- const files = await countDecodedFiles(workspace, signal, operation);+ const files = await countDecodedFiles(+ resources,+ workspace,+ signal,+ MAX_DECODED_ENTRIES_VISITED,+ );throwIfCancelled(operation, signal);const coverage =(stringsXml !== null && parsedStrings.entries.length > MAX_STRINGS) ||@@ -731,12 +581,11 @@ export class ApktoolProvider {files.capped? "partial": "complete";- await removeWorkspace();- return ok(+ result = ok(createAnalysisExecution({client,- target: { path: input.path, bytes: snapshotInfo.size, sha256 },+ target: { path: input.path, bytes: identity.bytes, sha256 },metadata: {version_name: metadata.versionName,version_code: metadata.versionCode,@@ -793,43 +642,95 @@ export class ApktoolProvider {`Decoded workspace enumeration stopped after ${String(MAX_DECODED_ENTRIES_VISITED)} entries; decoded_file_count and locales may be partial`,]: []),- ...(cleanupFailure === null ? [] : [cleanupFailure]),],},),);} catch (cause) {- await removeWorkspace();- const cancellation = regularFileCancellation(cause);- if (cancellation !== undefined)- return err(- failureWithCleanup(- new AnalysisCancelledError(operation, {- cause: cancellation.reason,- }),- ),- );+ const physical = artifactFilePrimaryFailure(cause);+ const primary =+ physical instanceof AnalysisError+ ? physical+ : physical instanceof ArtifactReaderFailure &&+ physical.reason === "cancelled"+ ? new AnalysisCancelledError(operation, {+ cause: artifactFileCancellationCause(physical),+ })+ : new AnalysisProtocolError("Apktool resource projection failed", {+ cause: physical,+ });+ const failure = analysisClientFailureForOperation(+ cause,+ "apktool",+ operation,+ );+ if (+ cause instanceof ArtifactReaderFailure &&+ cause.cleanup !== undefined &&+ !(cause instanceof ArtifactFileCleanupFailure)+ )+ new AnalysisCleanupLeaseGroup(failure, [lease]);+ const retained =+ physical === cause && cause instanceof AnalysisError+ ? cause+ : failure.cleanupIncomplete+ ? analysisErrorWithCleanupFailure(+ primary,+ failure,+ operation,+ ).bindCleanupDependencies([primary, failure])+ : primary;+ if (+ resources.snapshot !== undefined &&+ retained.partialObservation === undefined+ )+ retained.retainPartialObservation({+ kind: "file-snapshot-hash",+ ...resources.snapshot,+ });+ result = err(retained);+ }+ const released = await this.#artifacts.release(owner);+ const observation =+ result.ok && (released.kind === "failed" || signal?.aborted === true)+ ? createAnalysisExecutionEvidence(+ operation,+ input,+ result.value,+ "observed",+ )+ : undefined;+ if (result.ok && signal?.aborted)+ result = err(+ new AnalysisCancelledError(operation, {+ cause: signal.reason,+ partialObservation: observation,+ }),+ );+ if (released.kind === "failed") {+ const cleanup = new ProviderCleanupError(+ "apktool",+ [root],+ {},+ {+ operation,+ cause: released.cause,+ ...(observation === undefined+ ? {}+ : { partialObservation: observation }),+ },+ );+ new AnalysisCleanupLeaseGroup(cleanup, [lease]);return err(- failureWithCleanup(- signal?.aborted === true- ? new AnalysisCancelledError(operation, { cause })- : sourceAdmissionFailed- ? new AnalysisInputError(operation, { cause })- : cause instanceof AnalysisInputError- ? cause- : cause instanceof AnalysisCancelledError ||- cause instanceof AnalysisProtocolError- ? cause- : new AnalysisProtocolError(- "Apktool resource projection failed",- {- cause,- },- ),- ),+ result.ok+ ? cleanup+ : analysisErrorWithCleanupFailure(+ result.error,+ cleanup,+ operation,+ ).bindCleanupDependencies([result.error, cleanup]),);- } finally {- await source?.close().catch(() => undefined);}+ return result;}}diff --git a/src/apktool/ApktoolWorkspace.lifecycle.test.ts b/src/apktool/ApktoolWorkspace.lifecycle.test.tsnew file mode 100644index 000000000..ceee8ea00--- /dev/null+++ b/src/apktool/ApktoolWorkspace.lifecycle.test.ts@@ -0,0 +1,262 @@+import { countDecodedFiles } from "./ApktoolDecodedInventory.js";+import * as fs from "node:fs/promises";+import { join } from "node:path";+import { execFile } from "node:child_process";+import { promisify } from "node:util";+import { afterEach, expect, it, vi } from "vitest";+import {+ artifactFilePrimaryFailure,+ ArtifactFileCleanupFailure,+ ArtifactFileCancelled,+} from "../artifacts/ArtifactFileOperation.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";+import { ApktoolCommandCleanup } from "./ApktoolCommandCleanup.js";+import { ApktoolWorkspace } from "./ApktoolWorkspace.js";++vi.mock("node:fs/promises", async (original) => {+ const actual = await original<typeof import("node:fs/promises")>();+ return { ...actual, open: vi.fn(actual.open) };+});+const actual =+ await vi.importActual<typeof import("node:fs/promises")>("node:fs/promises");+afterEach(() => {+ vi.mocked(fs.open).mockImplementation(actual.open);+});++it.each(["source", "snapshot", "output"] as const)(+ "retains the exact %s descriptor after a denied close and fences root removal",+ async (kind) => {+ const root = await PrivateRuntimeRoot.create({+ prefix: "rea-apktool-owned-test-",+ });+ const commands = new ApktoolCommandCleanup();+ const workspace = new ApktoolWorkspace(root, commands);+ const input = join(root.path, "source.apk");+ const output = join(root.path, "output.xml");+ await fs.writeFile(input, "small-authored-apk");+ await fs.writeFile(output, "<resources/>");+ const selected =+ kind === "source"+ ? input+ : kind === "snapshot"+ ? join(root.path, "input.apk")+ : output;+ let denied = true;+ const closes = vi.fn();+ vi.mocked(fs.open).mockImplementation(async (path, flags, mode) => {+ const handle = await actual.open(path, flags, mode);+ if (String(path) === selected) {+ const close = handle.close.bind(handle);+ handle.close = async () => {+ closes();+ if (denied) throw new Error("authored close denial");+ await close();+ };+ }+ return handle;+ });+ try {+ const failure = await (+ kind === "output"+ ? workspace.readText(output, 100)+ : workspace.snapshotInput(input, "decode_android_resources")+ ).catch((cause: unknown) => cause);+ expect(failure).toBeInstanceOf(ArtifactFileCleanupFailure);+ if (!(failure instanceof ArtifactFileCleanupFailure))+ throw new Error("Expected owned descriptor failure");+ expect(failure.cleanupLease.released).toBe(false);+ await expect(workspace.close()).rejects.toBeInstanceOf(+ ArtifactReaderFailure,+ );+ await expect(fs.stat(root.path)).resolves.toBeDefined();+ denied = false;+ await workspace.close();+ expect(failure.cleanupLease.released).toBe(true);+ const count = closes.mock.calls.length;+ await workspace.close();+ expect(closes).toHaveBeenCalledTimes(count);+ await expect(fs.stat(root.path)).rejects.toMatchObject({+ code: "ENOENT",+ });+ } finally {+ denied = false;+ await workspace.close();+ await commands.close();+ }+ },+);++it("retains a physical decode-output failure when cancellation arrives during descriptor close", async () => {+ const root = await PrivateRuntimeRoot.create({+ prefix: "rea-apktool-owned-test-",+ });+ const commands = new ApktoolCommandCleanup();+ const workspace = new ApktoolWorkspace(root, commands);+ const output = join(root.path, "invalid.xml");+ const controller = new AbortController();+ await fs.writeFile(output, Buffer.from([0xff]));+ vi.mocked(fs.open).mockImplementation(async (path, flags, mode) => {+ const handle = await actual.open(path, flags, mode);+ const close = handle.close.bind(handle);+ handle.close = async () => {+ controller.abort({ caller: "after malformed bytes" });+ await close();+ };+ return handle;+ });+ try {+ await expect(+ workspace.readText(output, 100, controller.signal),+ ).rejects.toMatchObject({ _tag: "AnalysisProtocolError" });+ } finally {+ await workspace.close();+ await commands.close();+ }+});++it("records cancellation observed during a successful output descriptor close", async () => {+ const root = await PrivateRuntimeRoot.create({+ prefix: "rea-apktool-owned-test-",+ });+ const commands = new ApktoolCommandCleanup();+ const workspace = new ApktoolWorkspace(root, commands);+ const output = join(root.path, "output.xml");+ const controller = new AbortController();+ const reason = { caller: "during descriptor close" };+ await fs.writeFile(output, "<resources/>");+ vi.mocked(fs.open).mockImplementation(async (path, flags, mode) => {+ const handle = await actual.open(path, flags, mode);+ const close = handle.close.bind(handle);+ handle.close = async () => {+ controller.abort(reason);+ await close();+ };+ return handle;+ });+ try {+ const failure = await workspace+ .readText(output, 100, controller.signal)+ .catch((cause: unknown) => cause);+ expect(failure).toBeInstanceOf(ArtifactFileCancelled);+ if (!(failure instanceof ArtifactFileCancelled))+ throw new Error("Expected close cancellation");+ expect(failure.fileCancellation.reason).toBe(reason);+ expect(failure.fileCancellation.outcome).toEqual({+ kind: "completed",+ value: { text: "<resources/>", truncated: false },+ });+ } finally {+ await workspace.close();+ await commands.close();+ }+});++it.skipIf(process.platform === "win32")(+ "rejects a decoded FIFO without waiting for a writer",+ async () => {+ const root = await PrivateRuntimeRoot.create({+ prefix: "rea-apktool-owned-test-",+ });+ const commands = new ApktoolCommandCleanup();+ const workspace = new ApktoolWorkspace(root, commands);+ const fifo = join(root.path, "strings.xml");+ try {+ await promisify(execFile)("mkfifo", [fifo]);+ await expect(workspace.readText(fifo, 100)).rejects.toMatchObject({+ code: "ENOTFILE",+ });+ } finally {+ await workspace.close();+ await commands.close();+ }+ },+);++it.each([false, true])(+ "keeps malformed UTF-8 primary when final stat observes cancellation (close denied=%s)",+ async (deniedInitially) => {+ const root = await PrivateRuntimeRoot.create({+ prefix: "rea-apktool-owned-test-",+ });+ const commands = new ApktoolCommandCleanup();+ const workspace = new ApktoolWorkspace(root, commands);+ const path = join(root.path, "malformed.xml");+ const controller = new AbortController();+ let denied = deniedInitially;+ await fs.writeFile(path, Buffer.from([0xff]));+ vi.mocked(fs.open).mockImplementation(async (name, flags, mode) => {+ const handle = await actual.open(name, flags, mode);+ const stat = handle.stat.bind(handle);+ let calls = 0;+ handle.stat = ((...args: Parameters<typeof handle.stat>) =>+ stat(...args).then((value) => {+ if (++calls === 3)+ controller.abort({ caller: "after bytes before interpretation" });+ return value;+ })) as typeof handle.stat;+ const close = handle.close.bind(handle);+ handle.close = async () => {+ if (denied) throw new Error("authored denial");+ await close();+ };+ return handle;+ });+ try {+ const failure = await workspace+ .readText(path, 100, controller.signal)+ .catch((cause: unknown) => cause);+ expect(controller.signal.aborted).toBe(true);+ expect(artifactFilePrimaryFailure(failure)).toMatchObject({+ _tag: "AnalysisProtocolError",+ });+ if (denied)+ await expect(workspace.close()).rejects.toBeInstanceOf(+ ArtifactReaderFailure,+ );+ denied = false;+ await workspace.close();+ } finally {+ denied = false;+ await workspace.close();+ await commands.close();+ }+ },+);++it.skipIf(process.platform === "win32")(+ "counts omitted special entries toward the decoded inventory budget",+ async () => {+ const root = await PrivateRuntimeRoot.create({+ prefix: "rea-apktool-owned-test-",+ });+ const commands = new ApktoolCommandCleanup();+ const workspace = new ApktoolWorkspace(root, commands);+ try {+ await fs.writeFile(join(root.path, "one.xml"), "one");+ await fs.writeFile(join(root.path, "two.xml"), "two");+ for (let index = 0; index < 4; index++)+ await promisify(execFile)("mkfifo", [+ join(root.path, `special-${index}`),+ ]);+ const result = await countDecodedFiles(+ workspace,+ root.path,+ undefined,+ 3,+ );+ expect(result.capped).toBe(true);+ expect(result.count).toBeLessThanOrEqual(2);+ const complete = await countDecodedFiles(+ workspace,+ root.path,+ undefined,+ 6,+ );+ expect(complete).toEqual({ count: 2, capped: false, locales: [] });+ } finally {+ await workspace.close();+ await commands.close();+ }+ },+);diff --git a/src/apktool/ApktoolWorkspace.ts b/src/apktool/ApktoolWorkspace.tsnew file mode 100644index 000000000..4d4655f54--- /dev/null+++ b/src/apktool/ApktoolWorkspace.ts@@ -0,0 +1,227 @@+import { readArtifactFileChunks } from "../artifacts/readArtifactFileChunks.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import { createHash } from "node:crypto";+import { chmod, open } from "node:fs/promises";+import { join } from "node:path";+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { DirectoryArtifactReader } from "../artifacts/DirectoryArtifactReader.js";+import {+ assertArtifactReadActive,+ mapArtifactFileFailure,+ withArtifactFileHandle,+ withArtifactRegularFile,+} from "../artifacts/ArtifactFileOperation.js";+import {+ AnalysisInputError,+ AnalysisProtocolError,+} from "../domain/analysisErrorCore.js";+import { sameRegularFileState } from "../filesystem/RegularFile.js";+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";+import type { ApktoolCommandCleanup } from "./ApktoolCommandCleanup.js";++/** One decode's descriptors and root; removal follows confirmed child cleanup. */+export class ApktoolWorkspace {+ readonly #files = new ArtifactResourceScope();+ #snapshot:+ | { readonly path: string; readonly bytes: number; readonly sha256: string }+ | undefined;++ constructor(+ readonly root: PrivateRuntimeRoot,+ readonly commands: ApktoolCommandCleanup,+ readonly removeWorkspace?: (path: string) => Promise<void>,+ ) {}++ get snapshot() {+ return this.#snapshot;+ }++ get path(): string {+ return this.root.path;+ }++ async close(): Promise<void> {+ await this.#files.close();+ if (this.commands.pendingFor(this.path))+ throw new Error(+ "The decode workspace remains owned until its Apktool command stops",+ );+ if (this.removeWorkspace !== undefined)+ await this.removeWorkspace(this.path);+ await this.root.close();+ }++ /** Stream one admitted input into a separately owned immutable snapshot. */+ async snapshotInput(path: string, operation: string, signal?: AbortSignal) {+ let admitted = false;+ try {+ return await withArtifactRegularFile(+ path,+ this.#files,+ signal,+ async (source) => {+ admitted = true;+ const initial = await source.stat();+ const output = join(this.path, "input.apk");+ const file = await open(output, "wx", 0o600);+ await withArtifactFileHandle(+ output,+ file,+ this.#files,+ signal,+ async (destination) => {+ let copied = 0;+ const hash = createHash("sha256");+ for await (const value of readArtifactFileChunks(source, {+ start: 0,+ end: initial.size,+ signal,+ })) {+ assertArtifactReadActive(signal);+ if (!Buffer.isBuffer(value))+ throw new AnalysisProtocolError(+ "APK snapshot stream returned non-byte data",+ );+ copied += value.length;+ if (copied > initial.size)+ throw new AnalysisInputError(operation, {+ cause: new Error(+ `The selected APK changed while being copied: ${path}`,+ ),+ });+ hash.update(value);+ let offset = 0;+ while (offset < value.length) {+ assertArtifactReadActive(signal);+ const written = await destination.write(+ value,+ offset,+ value.length - offset,+ );+ if (written.bytesWritten === 0)+ throw new AnalysisProtocolError(+ "APK snapshot write made no progress",+ );+ offset += written.bytesWritten;+ }+ }+ const final = await source.stat();+ if (+ copied !== initial.size ||+ !sameRegularFileState(initial, final)+ )+ throw new AnalysisInputError(operation, {+ cause: new Error(+ `The selected APK changed while being copied: ${path}`,+ ),+ });+ this.#snapshot = {+ path,+ bytes: copied,+ sha256: hash.digest("hex"),+ };+ },+ );+ await chmod(output, 0o400);+ return this.#snapshot!;+ },+ "follow",+ );+ } catch (cause) {+ throw mapArtifactFileFailure(cause, (physical) =>+ admitted ||+ (physical instanceof ArtifactReaderFailure &&+ physical.reason === "cancelled")+ ? physical+ : new AnalysisInputError(operation, { cause: physical }),+ );+ }+ }++ /** Reject non-regular output before reading; every failed close retains its owner. */+ async readText(+ path: string,+ budget: number,+ signal?: AbortSignal,+ ): Promise<{ text: string | null; truncated: boolean }> {+ let admitted = false;+ try {+ return await withArtifactRegularFile(+ path,+ this.#files,+ signal,+ async (file) => {+ admitted = true;+ const initial = await file.stat();+ const bytes = Buffer.alloc(budget + 1);+ let length = 0;+ while (length < bytes.length) {+ assertArtifactReadActive(signal);+ const result = await file.read(+ bytes,+ length,+ bytes.length - length,+ null,+ );+ if (result.bytesRead === 0) break;+ length += result.bytesRead;+ }+ const final = await file.stat();+ if (!sameRegularFileState(initial, final))+ throw new AnalysisProtocolError(+ `Apktool output changed while being read: ${path}`,+ );+ const truncated = length > budget;+ try {+ return {+ text: new TextDecoder("utf-8", { fatal: true }).decode(+ bytes.subarray(0, Math.min(length, budget)),+ { stream: truncated },+ ),+ truncated,+ };+ } catch (cause) {+ throw new AnalysisProtocolError(+ `apktool produced invalid UTF-8 in ${path}`,+ { cause },+ );+ }+ },+ );+ } catch (cause) {+ if (+ !admitted &&+ cause instanceof Error &&+ "code" in cause &&+ cause.code === "ENOENT"+ )+ return { text: null, truncated: false };+ throw cause;+ }+ }++ async *entries(path: string, signal?: AbortSignal, maximumEntries?: number) {+ const reader = new DirectoryArtifactReader(path);+ const owner = { kind: "reader" as const, resource: path, reader };+ this.#files.retain(owner);+ let failed: { cause: unknown } | undefined;+ try {+ yield* reader.entries(+ signal,+ maximumEntries === undefined ? undefined : { maximumEntries },+ );+ } catch (cause) {+ failed = { cause };+ throw cause;+ } finally {+ const released = await this.#files.release(owner);+ if (released.kind === "failed")+ throw failed === undefined+ ? released.cause+ : ArtifactReaderFailure.withCleanup(+ failed.cause,+ ArtifactReaderFailure.cleanupObservation(released.cause, path),+ );+ }+ }+}diff --git a/src/artifacts/DirectoryArtifactReader.ts b/src/artifacts/DirectoryArtifactReader.tsindex dfab54f22..a85c2b1b1 100644--- a/src/artifacts/DirectoryArtifactReader.ts+++ b/src/artifacts/DirectoryArtifactReader.ts@@ -24,6 +24,20 @@ import { readArtifactFileChunks } from "./readArtifactFileChunks.js";interface DirectoryTraversalOptions extends ArtifactTraversalOptions {readonly descendInto?: (path: string) => boolean;+ /** Bound examined children, including omitted special entries. */+ readonly maximumEntries?: number;+}++/** Exhausted an examined-entry budget; unrelated I/O and cleanup failures stay distinct. */+export class DirectoryArtifactTraversalLimit extends ArtifactReaderFailure {+ constructor(+ readonly examinedEntries: number,+ readonly maximumEntries: number,+ ) {+ super("limit", "Directory traversal reached its examined-entry budget", {+ boundary: "capacity",+ });+ }}/** Non-symlink-following directory reader. */@@ -47,6 +61,20 @@ export class DirectoryArtifactReader implements ArtifactReader {const root = await this.#resolveRoot();const options =typeof selection === "function" ? { descendInto: selection } : selection;+ const maximum = options?.maximumEntries;+ if (+ maximum !== undefined &&+ (!Number.isSafeInteger(maximum) || maximum < 0)+ )+ throw new RangeError(+ "Directory traversal maximumEntries must be a nonnegative safe integer",+ );+ let examined = 0;+ const examine = () => {+ if (maximum !== undefined && examined >= maximum)+ throw new DirectoryArtifactTraversalLimit(examined, maximum);+ examined += 1;+ };const pending = [root];while (pending.length > 0) {abortIfNeeded(signal);@@ -60,6 +88,7 @@ export class DirectoryArtifactReader implements ArtifactReader {pending,signal,options,+ examine,))yield entry;await withDirectoryIoContext("inspect directory", directory, () =>@@ -88,8 +117,9 @@ export class DirectoryArtifactReader implements ArtifactReader {async *#readDirectory(directory: string,pending: string[],- signal?: AbortSignal,- options?: DirectoryTraversalOptions,+ signal: AbortSignal | undefined,+ options: DirectoryTraversalOptions | undefined,+ examine: () => void,): AsyncIterable<ArtifactEntry> {const root = await this.#resolveRoot();const handle = new OwnedDirectoryHandle(@@ -111,6 +141,7 @@ export class DirectoryArtifactReader implements ArtifactReader {);const child = await handle.handle.read();if (child === null) break;+ examine();abortIfNeeded(signal);const absolute = join(directory, child.name);const metadata = await lstat(absolute, { bigint: true }).catch(