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): centralize stable inventory identities
morluto135d102f9df8
diff --git a/src/artifacts/inventory/ArtifactGraphConstruction.ts b/src/artifacts/inventory/ArtifactGraphConstruction.tsindex a0d1d5e1c..2484a5a03 100644--- a/src/artifacts/inventory/ArtifactGraphConstruction.ts+++ b/src/artifacts/inventory/ArtifactGraphConstruction.ts@@ -1,4 +1,9 @@import { canonicalDigest } from "../../domain/comparisonSemantics.js";+import {+ artifactEdgeId,+ artifactIdForContent,+ occurrenceIdForLocation,+} from "../../domain/artifactIdentity.js";import type { ArtifactEntry } from "../ArtifactReader.js";import type {ArtifactCommand,@@ -159,7 +164,7 @@ export const createArtifactNode = (input: {readonly contentState: ArtifactNode["content_state"];readonly limitations?: readonly string[];}): ArtifactNode => ({- artifact_id: `art_${canonicalDigest({ sha256: input.sha256 }, "Artifact")}`,+ artifact_id: artifactIdForContent(input.sha256),kind: input.kind,format: input.format,sha256: input.sha256,@@ -175,7 +180,11 @@ export const rootOccurrenceFor = (node: ArtifactNode,declaredSize: number,): MutableOccurrence => ({- occurrence_id: `occ_${canonicalDigest({ root: node.artifact_id }, "Artifact")}`,+ occurrence_id: occurrenceIdForLocation({+ rootArtifactId: node.artifact_id,+ logicalPath: ".",+ entryKind: node.format === "directory" ? "directory" : "file",+ }),artifact_id: node.artifact_id,parent_occurrence_id: null,logical_path: ".",@@ -197,14 +206,11 @@ export const rekeyOccurrences = (for (const occurrence of occurrences)replacements.set(occurrence.occurrence_id,- `occ_${canonicalDigest(- {- root_artifact_id: rootArtifactId,- logical_path: occurrence.logical_path,- entry_kind: occurrence.entry_kind,- },- "Artifact",- )}`,+ occurrenceIdForLocation({+ rootArtifactId,+ logicalPath: occurrence.logical_path,+ entryKind: occurrence.entry_kind,+ }),);for (const occurrence of occurrences) {occurrence.occurrence_id =@@ -248,7 +254,7 @@ export const createArtifactEdges = (logical_path: occurrence.logical_path,};edges.push({- edge_id: `edge_${canonicalDigest(semantic, "Artifact")}`,+ edge_id: artifactEdgeId(semantic),...semantic,producer: occurrence.entry_kind === "slice" ? (producer ?? null) : null,ordinal: edges.length,diff --git a/src/artifacts/inventory/scanCanonical.ts b/src/artifacts/inventory/scanCanonical.tsindex 2a746343d..bfef89e07 100644--- a/src/artifacts/inventory/scanCanonical.ts+++ b/src/artifacts/inventory/scanCanonical.ts@@ -21,7 +21,11 @@ import {rootOccurrenceFor,type MutableOccurrence,} from "./ArtifactGraphConstruction.js";-import { canonicalDigest } from "../../domain/comparisonSemantics.js";+import {+ artifactContradictionId,+ artifactGraphDigest,+ artifactManifestId,+} from "../../domain/artifactIdentity.js";import { classifyRoot } from "./classify.js";import { hashReadable, type HashResult } from "../ArtifactHash.js";import { createReader, inventoryLimitations } from "./reader.js";@@ -125,15 +129,12 @@ const buildInventorySnapshot = async (await verifyRootDigest(path, rootDigest, signal);- const graphSha256 = canonicalDigest(- {- nodes: orderedNodes,- occurrences: orderedOccurrences,- edges: orderedEdges,- integrity_contradictions: integrityContradictions,- },- "Artifact",- );+ const graphSha256 = artifactGraphDigest({+ nodes: orderedNodes,+ occurrences: orderedOccurrences,+ edges: orderedEdges,+ contradictions: integrityContradictions,+ });const manifest = buildManifest({rootNode,graphSha256,@@ -171,15 +172,12 @@ const buildIntegrityContradictions = (: occurrenceById.get(occurrence.parent_occurrence_id);const parentArtifactId = parent?.artifact_id ?? rootNode.artifact_id;return {- contradiction_id: `ic_${canonicalDigest(- {- root_artifact_id: rootNode.artifact_id,- logical_path: contradiction.logicalPath,- declared_sha256: contradiction.declaredSha256,- observed_sha256: contradiction.observedSha256,- },- "Artifact",- )}`,+ contradiction_id: artifactContradictionId({+ rootArtifactId: rootNode.artifact_id,+ logicalPath: contradiction.logicalPath,+ declaredSha256: contradiction.declaredSha256,+ observedSha256: contradiction.observedSha256,+ }),occurrence_id: occurrence.occurrence_id,parent_artifact_id: parentArtifactId,logical_path: contradiction.logicalPath,@@ -241,13 +239,7 @@ const buildManifest = ({readonly orderedEdges: readonly { edge_id: string }[];}): ArtifactInventoryResult["manifest"] =>artifactInventoryResultSchema.shape.manifest.parse({- manifest_id: `agm_${canonicalDigest(- {- root_artifact_id: rootNode.artifact_id,- graph_sha256: graphSha256,- },- "Artifact",- )}`,+ manifest_id: artifactManifestId(rootNode.artifact_id, graphSha256),root_artifact_id: rootNode.artifact_id,root_sha256: rootNode.sha256,root_format: rootNode.format,diff --git a/src/domain/apple/appleApplication.ts b/src/domain/apple/appleApplication.tsindex bb88a8c31..9a275d3c9 100644--- a/src/domain/apple/appleApplication.ts+++ b/src/domain/apple/appleApplication.ts@@ -189,10 +189,14 @@ export const projectAppleApplication = (};return appleApplicationProjectionResultSchema.parse({...withoutId,- projection_id: `aap_${digest(withoutId)}`,+ projection_id: appleProjectionId(withoutId),});};+/** Identify the complete projection, including source Evidence provenance. */+export const appleProjectionId = (projection: unknown): string =>+ `aap_${digest(projection)}`;+/*** IPA projection keeps every archive component, as before. Directory, ZIP,* and DMG inventories can hold installers and other siblings, so onlydiff --git a/src/domain/artifactIdentity.test.ts b/src/domain/artifactIdentity.test.tsnew file mode 100644index 000000000..b93ce450d--- /dev/null+++ b/src/domain/artifactIdentity.test.ts@@ -0,0 +1,191 @@+import { expect, it } from "vitest";++import {+ artifactContradictionId,+ artifactEdgeId,+ artifactGraphDigest,+ artifactIdForContent,+ artifactManifestId,+ occurrenceIdForLocation,+} from "./artifactIdentity.js";+import { appleProjectionId } from "./apple/appleApplication.js";++it("keeps content identity separate from occurrence location", () => {+ const root = artifactIdForContent("a".repeat(64));+ expect(root).toBe(+ "art_91d55c997599a1b301a52f2ad8559a9f2bfa28927d7cb2c391f3cedf6072ccdd",+ );+ expect(artifactIdForContent("a".repeat(64))).toBe(root);+ expect(+ occurrenceIdForLocation({+ rootArtifactId: "art_root",+ logicalPath: "one.bin",+ entryKind: "file",+ }),+ ).toBe(+ "occ_e6b5ac5042e4f050a3cb25f5af8419660c01f19523189470161f44113b4c16ec",+ );+ expect(+ occurrenceIdForLocation({+ rootArtifactId: root,+ logicalPath: "one.bin",+ entryKind: "file",+ }),+ ).not.toBe(+ occurrenceIdForLocation({+ rootArtifactId: root,+ logicalPath: "two.bin",+ entryKind: "file",+ }),+ );+ expect(+ occurrenceIdForLocation({+ rootArtifactId: root,+ logicalPath: "one.bin",+ entryKind: "file",+ }),+ ).not.toBe(+ occurrenceIdForLocation({+ rootArtifactId: artifactIdForContent("b".repeat(64)),+ logicalPath: "one.bin",+ entryKind: "file",+ }),+ );+});++it("commits to graph arrays in the order established by their owner", () => {+ const nodes = [+ { artifact_id: "art-a", sha256: "a" },+ { artifact_id: "art-b", sha256: "b" },+ ] as never;+ const occurrences = [+ { occurrence_id: "occ-a", logical_path: "a" },+ { occurrence_id: "occ-b", logical_path: "b" },+ ] as never;+ const edges = [{ edge_id: "edge-a" }] as never;+ const contradictions = [] as never;+ const graph = artifactGraphDigest({+ nodes,+ occurrences,+ edges,+ contradictions,+ });+ expect(+ artifactGraphDigest({+ nodes: [],+ occurrences: [],+ edges: [],+ contradictions: [],+ }),+ ).toBe("d9b34ff5b7099912cce6c39343453ebc7318febd2ed75205ce21caf27113e98f");+ expect(+ artifactGraphDigest({+ nodes: [+ { artifact_id: "art-a", sha256: "changed-bytes" },+ nodes[1],+ ] as never,+ occurrences,+ edges,+ contradictions,+ }),+ ).not.toBe(graph);+ expect(+ artifactGraphDigest({+ nodes,+ occurrences,+ edges,+ contradictions: [{ contradiction_id: "ic-a" }] as never,+ }),+ ).not.toBe(graph);+ const orderedContradictions = [+ {+ contradiction_id: "ic-z",+ logical_path: "z",+ observed_sha256: "a",+ },+ {+ contradiction_id: "ic-a",+ logical_path: "a",+ observed_sha256: "b",+ },+ ] as never;+ const contradictionGraph = artifactGraphDigest({+ nodes: [],+ occurrences: [],+ edges: [],+ contradictions: orderedContradictions,+ });+ const reorderedContradictionGraph = artifactGraphDigest({+ nodes: [],+ occurrences: [],+ edges: [],+ contradictions: [...orderedContradictions].reverse(),+ });+ expect(contradictionGraph).toBe(+ "121f28fb3c5f104e357d502c29994961aea68be22f7f8bcae6c90e540904ddc5",+ );+ expect(reorderedContradictionGraph).toBe(+ "f7ba200f36804975789ee85fab32c4f79922c8a9e603b076d20bab09ba87377e",+ );+ expect(reorderedContradictionGraph).not.toBe(contradictionGraph);+ expect(artifactManifestId("art_root", contradictionGraph)).toBe(+ "agm_e25e6ed72612cab4a39efbbcf17e35f119ef944955ad87c0cbecce1a1c126342",+ );+ expect(artifactManifestId("art_root", reorderedContradictionGraph)).toBe(+ "agm_a7631939867608767e773992a4d8fc672202dd1a4a234239eb9d2e50a625fedb",+ );+ expect(+ artifactContradictionId({+ rootArtifactId: "root",+ logicalPath: "entry",+ declaredSha256: "a",+ observedSha256: "b",+ }),+ ).not.toBe(+ artifactContradictionId({+ rootArtifactId: "root",+ logicalPath: "entry",+ declaredSha256: "a",+ observedSha256: "c",+ }),+ );+ expect(+ artifactContradictionId({+ rootArtifactId: "art_root",+ logicalPath: "one.bin",+ declaredSha256: "a",+ observedSha256: "b",+ }),+ ).toBe("ic_69ee65b6c79c597ca02c91777882edec17064e15a3abeb4ed652adc7781ce4d2");+ expect(artifactManifestId("art_root", "b".repeat(64))).toBe(+ "agm_3940382b43202a6700426217151879f6274e4c362c3728368c84af993fa1f9a6",+ );+ expect(+ artifactEdgeId({+ parent_artifact_id: "art_parent",+ child_artifact_id: "art_child",+ relation: "contains",+ occurrence_id: "occ_child",+ logical_path: "child",+ }),+ ).toMatch(/^edge_[a-f0-9]{64}$/u);+});++it("makes Apple projection identity depend on projected facts and evidence", () => {+ const projection = {+ source_evidence_ids: ["ev-a", "ev-b"],+ classification: ["javascript", "native"],+ };+ expect(appleProjectionId(projection)).toBe(+ "aap_eb45cb11ec77d3c98268fa90ce32d3060760b8f70a534fc9255cdb92de316bf9",+ );+ expect(+ appleProjectionId({ ...projection, classification: ["native"] }),+ ).not.toBe(appleProjectionId(projection));+ expect(+ appleProjectionId({+ ...projection,+ source_evidence_ids: ["ev-a", "ev-c"],+ }),+ ).not.toBe(appleProjectionId(projection));+});diff --git a/src/domain/artifactIdentity.ts b/src/domain/artifactIdentity.tsnew file mode 100644index 000000000..f97cc419b--- /dev/null+++ b/src/domain/artifactIdentity.ts@@ -0,0 +1,84 @@+import { canonicalDigest } from "./comparisonSemantics.js";+import type {+ ArtifactEdge,+ ArtifactNode,+ ArtifactOccurrence,+ IntegrityContradiction,+} from "./artifactGraph.js";++/** Content-address an artifact independently of where it was observed. */+export const artifactIdForContent = (sha256: string): string =>+ `art_${canonicalDigest({ sha256 }, "Artifact")}`;++/** Identify an occurrence by its root and exact logical location. */+export const occurrenceIdForLocation = (input: {+ readonly rootArtifactId: string;+ readonly logicalPath: string;+ readonly entryKind: ArtifactOccurrence["entry_kind"];+}): string =>+ input.logicalPath === "."+ ? `occ_${canonicalDigest({ root: input.rootArtifactId }, "Artifact")}`+ : `occ_${canonicalDigest(+ {+ root_artifact_id: input.rootArtifactId,+ logical_path: input.logicalPath,+ entry_kind: input.entryKind,+ },+ "Artifact",+ )}`;++/** Commit to graph members in the ordering established by the inventory owner. */+export const artifactGraphDigest = (input: {+ readonly nodes: readonly ArtifactNode[];+ readonly occurrences: readonly ArtifactOccurrence[];+ readonly edges: readonly ArtifactEdge[];+ readonly contradictions: readonly IntegrityContradiction[];+}): string =>+ canonicalDigest(+ {+ nodes: input.nodes,+ occurrences: input.occurrences,+ edges: input.edges,+ integrity_contradictions: input.contradictions,+ },+ "Artifact",+ );++/** Bind a root artifact to its graph commitment. */+export const artifactManifestId = (+ rootArtifactId: string,+ graphSha256: string,+): string =>+ `agm_${canonicalDigest(+ { root_artifact_id: rootArtifactId, graph_sha256: graphSha256 },+ "Artifact",+ )}`;++/** Identify one integrity disagreement at its observed logical path. */+export const artifactContradictionId = (input: {+ readonly rootArtifactId: string;+ readonly logicalPath: string;+ readonly declaredSha256: string;+ readonly observedSha256: string;+}): string =>+ `ic_${canonicalDigest(+ {+ root_artifact_id: input.rootArtifactId,+ logical_path: input.logicalPath,+ declared_sha256: input.declaredSha256,+ observed_sha256: input.observedSha256,+ },+ "Artifact",+ )}`;++/** Identify an edge by its semantic relationship and exact occurrence. */+export const artifactEdgeId = (+ semantic: Pick<+ ArtifactEdge,+ | "parent_artifact_id"+ | "child_artifact_id"+ | "relation"+ | "occurrence_id"+ | "logical_path"+ >,+): string => `edge_${canonicalDigest(semantic, "Artifact")}`;diff --git a/src/domain/artifactInventoryEvidence.ts b/src/domain/artifactInventoryEvidence.tsindex efa459ebb..de78563ef 100644--- a/src/domain/artifactInventoryEvidence.ts+++ b/src/domain/artifactInventoryEvidence.ts@@ -5,7 +5,15 @@ import {type ArtifactOccurrence,type IntegrityContradiction,} from "./artifactGraph.js";-import { canonicalDigest, canonicalJson } from "./comparisonSemantics.js";+import { canonicalJson } from "./comparisonSemantics.js";+import {+ artifactContradictionId,+ artifactEdgeId,+ artifactGraphDigest,+ artifactIdForContent,+ artifactManifestId,+ occurrenceIdForLocation,+} from "./artifactIdentity.js";import { parseEvidence, type Evidence } from "./evidence.js";import { artifactInspectionResultSchema } from "./artifactInspection.js";import { err, ok, type Result } from "./result.js";@@ -79,10 +87,7 @@ const validateInventoryPage = (inventory: ArtifactInventoryResult): void => {"edge ID",);for (const node of inventory.nodes)- if (- node.artifact_id !==- `art_${canonicalDigest({ sha256: node.sha256 }, "Artifact inventory")}`- )+ if (node.artifact_id !== artifactIdForContent(node.sha256))throw new TypeError("Artifact node ID is not content-addressed");};@@ -230,38 +235,29 @@ const validateCompleteInventory = (inventory: InventorySet): void => {throw new TypeError("Integrity contradiction references a missing graph member",);- const expectedId = `ic_${canonicalDigest(- {- root_artifact_id: inventory.manifest.root_artifact_id,- logical_path: contradiction.logical_path,- declared_sha256: contradiction.declared_sha256,- observed_sha256: contradiction.observed_sha256,- },- "Artifact inventory",- )}`;+ const expectedId = artifactContradictionId({+ rootArtifactId: inventory.manifest.root_artifact_id,+ logicalPath: contradiction.logical_path,+ declaredSha256: contradiction.declared_sha256,+ observedSha256: contradiction.observed_sha256,+ });if (contradiction.contradiction_id !== expectedId)throw new TypeError("Integrity contradiction ID does not match its identity",);}- const graphSha256 = canonicalDigest(- {- nodes: inventory.nodes,- occurrences: inventory.occurrences,- edges: inventory.edges,- integrity_contradictions: inventory.integrityContradictions,- },- "Artifact inventory",- );+ const graphSha256 = artifactGraphDigest({+ nodes: inventory.nodes,+ occurrences: inventory.occurrences,+ edges: inventory.edges,+ contradictions: inventory.integrityContradictions,+ });if (graphSha256 !== inventory.manifest.graph_sha256)throw new TypeError("Artifact graph commitment does not match its members");- const manifestId = `agm_${canonicalDigest(- {- root_artifact_id: inventory.manifest.root_artifact_id,- graph_sha256: graphSha256,- },- "Artifact inventory",- )}`;+ const manifestId = artifactManifestId(+ inventory.manifest.root_artifact_id,+ graphSha256,+ );if (manifestId !== inventory.manifest.manifest_id)throw new TypeError("Artifact manifest ID does not match its commitment");};@@ -279,17 +275,11 @@ const validateOccurrence = (!occurrenceIds.has(occurrence.parent_occurrence_id))throw new TypeError("Artifact occurrence references a missing parent");- const expectedId =- occurrence.logical_path === "."- ? `occ_${canonicalDigest({ root: inventory.manifest.root_artifact_id }, "Artifact inventory")}`- : `occ_${canonicalDigest(- {- root_artifact_id: inventory.manifest.root_artifact_id,- logical_path: occurrence.logical_path,- entry_kind: occurrence.entry_kind,- },- "Artifact inventory",- )}`;+ const expectedId = occurrenceIdForLocation({+ rootArtifactId: inventory.manifest.root_artifact_id,+ logicalPath: occurrence.logical_path,+ entryKind: occurrence.entry_kind,+ });if (occurrence.occurrence_id !== expectedId)throw new TypeError("Artifact occurrence ID does not match its identity");};@@ -312,9 +302,7 @@ const validateEdge = (occurrence_id: edge.occurrence_id,logical_path: edge.logical_path,};- if (- edge.edge_id !== `edge_${canonicalDigest(semantic, "Artifact inventory")}`- )+ if (edge.edge_id !== artifactEdgeId(semantic))throw new TypeError("Artifact edge ID does not match its identity");};