Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

refactor(artifacts): centralize stable inventory identities

morluto135d102f9df8
diff --git a/src/artifacts/inventory/ArtifactGraphConstruction.ts b/src/artifacts/inventory/ArtifactGraphConstruction.ts
index 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.ts
index 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.ts
index 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 only
diff --git a/src/domain/artifactIdentity.test.ts b/src/domain/artifactIdentity.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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");
};