Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
refactor(artifacts): select extraction by logical path
morluto7ba3580c8604
diff --git a/docs/javascript-artifact-reconstruction.md b/docs/javascript-artifact-reconstruction.mdindex 969cca14a..f27f3412f 100644--- a/docs/javascript-artifact-reconstruction.md+++ b/docs/javascript-artifact-reconstruction.md@@ -144,23 +144,22 @@ represented by metadata only.## Bounds and coverage-The input schema bounds artifact entries, cumulative artifact bytes, bytes per-entry, compression ratio, path depth and length, selected text files, text bytes,-AST nodes, static findings, bundle modules, source-map originals, and cooperative-parse time. Source-map original limits are shared across all maps in one-reconstruction. Combined input limits are rejected if their conservative graph-projection could exceed the v1 contract's 100,000 nodes or 200,000 edges.+The reconstruction keeps internal resource safeguards for artifact entries,+cumulative artifact bytes, bytes per entry, compression ratio, path depth and+length, selected text files, text bytes, AST nodes, and cooperative parse time.+These safeguards are not caller-selectable output budgets. Source-map parsing+reports truncation when its format or parser safety boundary is reached. The+application graph has no aggregate node, edge, root, or observation prefix cap.Byte, entry, path, and graph-shape bounds are hard limits. The parse deadline ischecked before and between bounded parsing and traversal phases; the synchronousBabel and JSON parser calls cannot be preempted mid-call, so their input bytebounds remain the hard protection for an individual call.-Byte-identical assets share a content-digest node. At most 64 distinct-observations are retained on that node, as required by the graph contract; every-inventoried containment edge remains present, and any omitted observations make-top-level coverage partial and truncated. When an exact omission count is not-knowable, `omitted_count` is `null` rather than a guessed value.+Byte-identical assets share a content-digest node. Every distinct observation+and inventoried containment edge is retained. If parsing or artifact safety+boundaries omit input, coverage reports that omission; when an exact omission+count is not knowable, `omitted_count` is `null` rather than a guessed value.## Verification boundarydiff --git a/scripts/verify-package-artifact.mjs b/scripts/verify-package-artifact.mjsindex 290113a79..9857e7761 100644--- a/scripts/verify-package-artifact.mjs+++ b/scripts/verify-package-artifact.mjs@@ -1,4 +1,4 @@-import { mkdir, readFile, writeFile } from "node:fs/promises";+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";import { isDeepStrictEqual } from "node:util";import { join } from "node:path";import { TextReader, Uint8ArrayWriter, ZipWriter } from "@zip.js/zip.js";@@ -126,37 +126,41 @@ const verifyPackagedArtifactExtraction = async ({artifactInventory,cli,environment,- workspace,}) => {const occurrence = artifactInventory?.occurrences?.items?.find(({ logical_path: path }) => path === "app/main.js",);- if (occurrence?.occurrence_id === undefined)+ if (occurrence?.logical_path === undefined)throw new Error("packaged artifact inventory omitted the selected member");- const outputRoot = join(workspace, "artifact-extraction");const extraction = json(await run(cli,["extract-artifact",artifactArchive,- outputRoot,- "--occurrence-ids",- occurrence.occurrence_id,+ "--paths",+ occurrence.logical_path,"--json",],environment,),);- if (- extraction.operation !== "extract_artifact" ||- extraction.provider?.id !== "rea-artifact-graph" ||- extraction.normalized_result?.containment_verified !== true ||- extraction.normalized_result?.artifacts?.items?.[0]?.relative_path !==- "app/main.js" ||- (await readFile(join(outputRoot, "app/main.js"), "utf8")) !== "main();"- )- throw new Error("packaged artifact extraction CLI failed");+ const outputRoot = extraction.normalized_result?.output_root;+ try {+ if (+ extraction.operation !== "extract_artifact" ||+ extraction.provider?.id !== "rea-artifact-graph" ||+ extraction.normalized_result?.containment_verified !== true ||+ extraction.normalized_result?.artifacts?.items?.[0]?.relative_path !==+ "app/main.js" ||+ typeof outputRoot !== "string" ||+ (await readFile(join(outputRoot, "app/main.js"), "utf8")) !== "main();"+ )+ throw new Error("packaged artifact extraction CLI failed");+ } finally {+ if (typeof outputRoot === "string")+ await rm(outputRoot, { recursive: true, force: true });+ }};const assertRoutedApplicationAnalysis = (analysis) => {diff --git a/src/application/ArtifactExtraction.ts b/src/application/ArtifactExtraction.tsindex bc81f07e0..444232912 100644--- a/src/application/ArtifactExtraction.ts+++ b/src/application/ArtifactExtraction.ts@@ -34,7 +34,9 @@ export interface ArtifactExtractionInput {readonly inputPath: string;readonly inputFormat: BinaryTarget["format"];readonly outputRoot: string;- readonly occurrenceIds: readonly string[];+ readonly selection:+ | { readonly paths: readonly string[] }+ | { readonly occurrenceIds: readonly string[] };readonly limits: ArtifactLimits;}@@ -43,22 +45,34 @@ export const extractArtifact = async (input: ArtifactExtractionInput,signal?: AbortSignal,): Promise<ArtifactExtractionResult> => {- validateSelection(input.occurrenceIds);+ validateSelection(input.selection, input.limits);const sourcePath = await realpath(input.inputPath);- const selectedIds = new Set(input.occurrenceIds);- const inventory = await loadInventory(- sourcePath,- input.limits,- selectedIds,+ const snapshot = await scanArtifactInventory(sourcePath, input.limits, {signal,+ });+ const selectedOccurrences = resolveSelection(+ snapshot.occurrences,+ input.selection,);- const selected = input.occurrenceIds.map((id) => {- const occurrence = inventory.occurrences.get(id);- if (occurrence === undefined)- throw new ArtifactReaderFailure(- "unavailable",- `Selected artifact occurrence was not found: ${id}`,- );+ const selectedIds = new Set(+ selectedOccurrences.map(({ occurrence_id: id }) => id),+ );+ const occurrences = new Map<string, ArtifactOccurrence>();+ const neededNodes = new Set<string>();+ collectOccurrences(+ snapshot.occurrences,+ selectedIds,+ occurrences,+ neededNodes,+ );+ const nodes = new Map<string, ArtifactNode>();+ collectNodes(snapshot.nodes, neededNodes, nodes);+ const inventory: LoadedInventory = {+ manifest: snapshot.manifest,+ occurrences,+ nodes,+ };+ const selected = selectedOccurrences.map((occurrence) => {if ((occurrence.entry_kind !== "file" && occurrence.entry_kind !== "slice") ||occurrence.artifact_id === null ||@@ -67,13 +81,13 @@ export const extractArtifact = async ()throw new ArtifactReaderFailure("format",- `Selected occurrence is not an extractable regular child file: ${id}`,+ `Selected occurrence is not an extractable regular child file: ${occurrence.occurrence_id}`,);const node = inventory.nodes.get(occurrence.artifact_id);if (node === undefined)throw new ArtifactReaderFailure("integrity",- `Selected occurrence has no inventory node: ${id}`,+ `Selected occurrence has no inventory node: ${occurrence.occurrence_id}`,);return { occurrence, node };});@@ -214,26 +228,6 @@ interface LoadedInventory {readonly nodes: ReadonlyMap<string, ArtifactNode>;}-const loadInventory = async (- path: string,- limits: ArtifactLimits,- selectedIds: ReadonlySet<string>,- signal?: AbortSignal,-): Promise<LoadedInventory> => {- const snapshot = await scanArtifactInventory(path, limits, { signal });- const occurrences = new Map<string, ArtifactOccurrence>();- const neededNodes = new Set<string>();- collectOccurrences(- snapshot.occurrences,- selectedIds,- occurrences,- neededNodes,- );- const nodes = new Map<string, ArtifactNode>();- collectNodes(snapshot.nodes, neededNodes, nodes);- return { manifest: snapshot.manifest, occurrences, nodes };-};-const collectOccurrences = (items: readonly ArtifactOccurrence[],selected: ReadonlySet<string>,@@ -278,19 +272,79 @@ const createReader = async ();};-const validateSelection = (ids: readonly string[]): void => {- if (ids.length === 0)+type ArtifactSelection = ArtifactExtractionInput["selection"];++const validateSelection = (+ selection: ArtifactSelection,+ limits: ArtifactLimits,+): void => {+ const values =+ "paths" in selection ? selection.paths : selection.occurrenceIds;+ if (values.length === 0)throw new ArtifactReaderFailure("limit",- "Extraction requires at least one explicitly selected occurrence",+ "Extraction requires at least one selected path or occurrence",);- if (new Set(ids).size !== ids.length)+ const normalized =+ "paths" in selection+ ? values.map((path) => normalizeArtifactPath(path, limits))+ : values;+ if (new Set(normalized).size !== normalized.length)throw new ArtifactReaderFailure("path",- "Extraction occurrence selection contains duplicates",+ "Extraction selection contains duplicates",);};+const resolveSelection = (+ occurrences: readonly ArtifactOccurrence[],+ selection: ArtifactSelection,+): ArtifactOccurrence[] => {+ if ("occurrenceIds" in selection) {+ const byId = new Map(+ occurrences.map((occurrence) => [occurrence.occurrence_id, occurrence]),+ );+ return selection.occurrenceIds.map((id) => {+ const occurrence = byId.get(id);+ if (occurrence === undefined)+ throw new ArtifactReaderFailure(+ "unavailable",+ `Selected artifact occurrence was not found: ${id}`,+ );+ return occurrence;+ });+ }++ const byPath = new Map<string, ArtifactOccurrence[]>();+ for (const occurrence of occurrences) {+ const matches = byPath.get(occurrence.logical_path);+ if (matches === undefined)+ byPath.set(occurrence.logical_path, [occurrence]);+ else matches.push(occurrence);+ }+ return selection.paths.map((path) => {+ const normalizedPath = path.normalize("NFC");+ const matches = byPath.get(normalizedPath) ?? [];+ if (matches.length === 0)+ throw new ArtifactReaderFailure(+ "unavailable",+ `Selected artifact path was not found: ${path}`,+ );+ if (matches.length > 1)+ throw new ArtifactReaderFailure(+ "path",+ `Selected artifact path is ambiguous: ${path}`,+ );+ const match = matches[0];+ if (match === undefined)+ throw new ArtifactReaderFailure(+ "unavailable",+ `Selected artifact path was not found: ${path}`,+ );+ return match;+ });+};+const preflight = (entry: ArtifactEntry, limits: ArtifactLimits): void => {if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)throw new ArtifactReaderFailure(diff --git a/src/artifacts/ArtifactProvider.ts b/src/artifacts/ArtifactProvider.tsindex 161887d7d..2449e7932 100644--- a/src/artifacts/ArtifactProvider.ts+++ b/src/artifacts/ArtifactProvider.ts@@ -119,7 +119,10 @@ class ArtifactClient implements AnalysisClient {inputPath: this.target.sourcePath ?? this.target.path,inputFormat: this.target.format,outputRoot: parsed.output_root,- occurrenceIds: parsed.occurrence_ids,+ selection:+ "paths" in parsed+ ? { paths: parsed.paths }+ : { occurrenceIds: parsed.occurrence_ids },limits: DEFAULT_ARTIFACT_LIMITS,},options?.signal,diff --git a/src/cli/artifactCommands.ts b/src/cli/artifactCommands.tsindex dcc4bf4ac..6d3ab5085 100644--- a/src/cli/artifactCommands.ts+++ b/src/cli/artifactCommands.ts@@ -21,12 +21,24 @@ const registerExtractionCommand = (cli: CliInstance, logger: Logger): void => {args: z.object({path: z.string().describe("Application or package path"),}),- options: z.object({- occurrenceIds: z- .array(z.string().regex(/^occ_[a-f0-9]{64}$/u))- .min(1)- .describe("Exact artifact occurrence IDs selected for extraction"),- }),+ options: z+ .object({+ paths: z+ .array(z.string().min(1))+ .min(1)+ .optional()+ .describe("Logical artifact paths selected for extraction"),+ occurrenceIds: z+ .array(z.string().regex(/^occ_[a-f0-9]{64}$/u))+ .min(1)+ .optional()+ .describe("Alternate exact occurrence IDs selected for extraction"),+ })+ .refine(+ ({ paths, occurrenceIds }) =>+ (paths === undefined) !== (occurrenceIds === undefined),+ "Provide paths or occurrence IDs",+ ),alias: { occurrenceIds: "occurrence-ids" },run: ({ args, options }) =>logCliCommand(logger, "extract-artifact", () =>@@ -35,7 +47,11 @@ const registerExtractionCommand = (cli: CliInstance, logger: Logger): void => {"extract_artifact",{output_root: createArtifactExtractionDestination(),- occurrence_ids: options.occurrenceIds,+ ...(options.paths !== undefined+ ? { paths: options.paths }+ : options.occurrenceIds !== undefined+ ? { occurrence_ids: options.occurrenceIds }+ : {}),},logger,),diff --git a/src/contracts/artifactToolContracts.ts b/src/contracts/artifactToolContracts.tsindex d83dc0ca3..3abf43397 100644--- a/src/contracts/artifactToolContracts.ts+++ b/src/contracts/artifactToolContracts.ts@@ -27,19 +27,34 @@ export const artifactInventoryInputSchema = z.union([]);/** Exact caller boundary for approved artifact extraction. */-export const artifactExtractionInputSchema = z.object({- occurrence_ids: z.array(z.string().regex(/^occ_[a-f0-9]{64}$/u)).min(1),+const artifactOccurrenceSelectionSchema = z.strictObject({+ occurrence_ids: z+ .array(z.string().regex(/^occ_[a-f0-9]{64}$/u))+ .min(1)+ .describe("Alternate exact occurrence IDs from inspect_artifact"),});+const artifactPathSelectionSchema = z.strictObject({+ paths: z+ .array(z.string().min(1))+ .min(1)+ .describe("Exact logical_path values from inspect_artifact"),+});+export const artifactExtractionInputSchema = z.union([+ artifactPathSelectionSchema,+ artifactOccurrenceSelectionSchema,+]);/** Provider input after the local permission boundary chooses its destination. */-export const artifactExtractionExecutionSchema =- artifactExtractionInputSchema.extend({ output_root: z.string().min(1) });+export const artifactExtractionExecutionSchema = z.union([+ artifactPathSelectionSchema.extend({ output_root: z.string().min(1) }),+ artifactOccurrenceSelectionSchema.extend({ output_root: z.string().min(1) }),+]);const exampleInputSchema = z.record(z.string(), jsonValueSchema);const examples: Readonly<Record<string, Readonly<Record<string, unknown>>>> = {inspect_artifact: {},extract_artifact: {- occurrence_ids: [`occ_${"0".repeat(64)}`],+ paths: ["Contents/Info.plist"],},};@@ -77,7 +92,7 @@ export const ARTIFACT_TOOL_CONTRACTS = [),artifact("extract_artifact",- "Extract selected graph artifacts into a fresh temporary directory chosen by REA. The result includes its location. Rejects traversal and symlink escapes, never overwrites, enforces archive integrity checks, and verifies cleanup.",+ "Extract selected regular files by logical paths from inspect_artifact (or by occurrence IDs) into a fresh temporary directory chosen by REA. The result includes its location. Rejects traversal and symlink escapes, never overwrites, enforces archive integrity checks, and verifies cleanup.",artifactExtractionInputSchema,),] as const satisfies readonly ToolContract[];diff --git a/tests/boundary/providers/native/artifactProvider.extraction.test.ts b/tests/boundary/providers/native/artifactProvider.extraction.test.tsindex b3728c848..838cb7ff9 100644--- a/tests/boundary/providers/native/artifactProvider.extraction.test.ts+++ b/tests/boundary/providers/native/artifactProvider.extraction.test.ts@@ -52,7 +52,7 @@ describe("artifact extraction", () => {"extract_artifact",artifactExtractionExecutionSchema.parse({output_root: output,- occurrence_ids: [selected.occurrence_id],+ paths: ["assets/selected.js"],}),);expect(result.ok).toBe(true);@@ -75,6 +75,22 @@ describe("artifact extraction", () => {access(join(output, "assets", "ignored.js")),).rejects.toThrow();+ const traversalOutput = join(root, "traversal-output");+ const traversal = await new ArtifactProvider()+ .createClient(targetValue)+ .execute(+ "extract_artifact",+ artifactExtractionExecutionSchema.parse({+ output_root: traversalOutput,+ paths: ["../source/assets/ignored.js"],+ }),+ );+ expect(traversal).toMatchObject({+ ok: false,+ error: { _tag: "ArtifactOperationError", reason: "path" },+ });+ await expect(access(traversalOutput)).rejects.toThrow();+const relocatedOutput = join(root, "relocated-output");const relocated = await new ArtifactProvider().createClient(targetValue)