From fd9989eadbb5c84a0319972f6f0f99101e81c331 Mon Sep 17 00:00:00 2001 From: phexuss <68733230+phexuss@users.noreply.github.com> Date: Wed, 18 Nov 2026 20:59:33 +0100 Subject: [PATCH] fix(artifacts): keep virtual directory identities distinct from file content (#8574) A virtual directory node was identified from the SHA-256 of its canonical listing JSON through the same function as raw file bytes. A regular file containing exactly that JSON (for example an empty directory's {"children":[],"kind":"directory"}) received the same artifact ID, the directory node overwrote the file node, and extraction of the valid archive failed with an integrity mismatch. Derive virtual node identities in a separate domain and validate node IDs by representation. Inventory Evidence retained with the earlier virtual identity is still accepted. Fixes #8551 Co-authored-by: morluto <76467478+morluto@users.noreply.github.com> --- .../inventory/ArtifactGraphConstruction.ts | 7 +- .../ArtifactOccurrenceIdentity.test.ts | 183 +++++++++++++++++- src/domain/artifactIdentity.ts | 12 ++ src/domain/artifactInventoryEvidence.ts | 10 +- .../artifactDirectoryIdentity.test.ts | 2 + 5 files changed, 209 insertions(+), 5 deletions(-) diff --git a/src/artifacts/inventory/ArtifactGraphConstruction.ts b/src/artifacts/inventory/ArtifactGraphConstruction.ts index f087b5394b..948bd43239 100644 --- a/src/artifacts/inventory/ArtifactGraphConstruction.ts +++ b/src/artifacts/inventory/ArtifactGraphConstruction.ts @@ -14,7 +14,7 @@ import { } from "../../domain/apple/appleArchiveFormat.js"; import { artifactEdgeId, - artifactIdForContent, + artifactIdForNode, occurrenceIdForLocation, logicalPathNfc, } from "../../domain/artifactIdentity.js"; @@ -257,7 +257,10 @@ export const createArtifactNode = (input: { readonly format: ArtifactNode["format"]; readonly contentState: ArtifactNode["content_state"]; }): ArtifactNode => ({ - artifact_id: artifactIdForContent(input.sha256), + artifact_id: artifactIdForNode({ + sha256: input.sha256, + content_state: input.contentState, + }), format: input.format, sha256: input.sha256, size: input.size, diff --git a/src/artifacts/inventory/ArtifactOccurrenceIdentity.test.ts b/src/artifacts/inventory/ArtifactOccurrenceIdentity.test.ts index 9d7fe276f6..0a606bc75c 100644 --- a/src/artifacts/inventory/ArtifactOccurrenceIdentity.test.ts +++ b/src/artifacts/inventory/ArtifactOccurrenceIdentity.test.ts @@ -1,10 +1,20 @@ -import { chmod, mkdir, writeFile } from "node:fs/promises"; +import { chmod, mkdir, readFile, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { TextReader, Uint8ArrayWriter, ZipWriter } from "@zip.js/zip.js"; import { describe, expect, it } from "vitest"; -import { inventoryArtifact } from "../../../tests/fixtures/artifactInventory.js"; +import { + inventoryArtifact, + withArtifactResourceScope, +} from "../../../tests/fixtures/artifactInventory.js"; +import { extractArtifact } from "../extraction/ArtifactExtraction.js"; +import { + artifactEdgeId, + artifactGraphDigest, + artifactIdForContent, + artifactManifestId, +} from "../../domain/artifactIdentity.js"; import { compareArtifacts } from "../../domain/artifactComparison.js"; import { parseArtifactInventoryEvidence } from "../../domain/artifactInventoryEvidence.js"; import { projectAppleInventory } from "../../domain/apple/appleApplication.js"; @@ -239,3 +249,172 @@ describe("directly selected executable formats", () => { }, ); }); + +type Inventory = Awaited>; + +const zipInventoryEvidence = (path: string, inventory: Inventory) => + createEvidence( + { path, sha256: inventory.manifest.root_sha256, format: "zip" }, + { id: "rea-artifact-graph", name: "artifact inventory", version: "1" }, + { + operation: "inventory_artifact", + parameters: {}, + result: inventory, + confidence: "observed", + authority: "shipped-artifact", + }, + ); + +// Identifiers are ASCII, so code-unit order is the canonical order. +const byCodeUnit = (left: string, right: string): number => + left < right ? -1 : left > right ? 1 : 0; + +/** + * Rebuild an inventory page as earlier releases committed it, when virtual + * directory nodes shared the raw-content identity domain. + */ +const withLegacyVirtualIdentities = (current: Inventory): Inventory => { + const legacyId = new Map( + current.nodes + .filter((node) => node.content_state === "virtual") + .map((node) => [node.artifact_id, artifactIdForContent(node.sha256)]), + ); + const relabel = (id: T): T => + ((id !== null ? legacyId.get(id) : undefined) ?? id) as T; + const nodes = current.nodes + .map((node) => ({ ...node, artifact_id: relabel(node.artifact_id) })) + .sort((left, right) => byCodeUnit(left.artifact_id, right.artifact_id)); + const occurrences = current.occurrences.map((occurrence) => ({ + ...occurrence, + artifact_id: relabel(occurrence.artifact_id), + })); + const edges = current.edges + .map((edge) => { + const occurrence = occurrences.find( + (item) => item.occurrence_id === edge.occurrence_id, + ); + const parent_artifact_id = relabel(edge.parent_artifact_id); + return { + ...edge, + parent_artifact_id, + edge_id: + occurrence === undefined + ? edge.edge_id + : artifactEdgeId({ ...edge, parent_artifact_id }, occurrence), + }; + }) + .sort((left, right) => byCodeUnit(left.edge_id, right.edge_id)); + const graph_sha256 = artifactGraphDigest({ + nodes, + occurrences, + edges, + contradictions: current.integrity_contradictions, + }); + return { + ...current, + nodes, + occurrences, + edges, + manifest: { + ...current.manifest, + graph_sha256, + manifest_id: artifactManifestId( + current.manifest.root_artifact_id, + graph_sha256, + ), + }, + }; +}; + +const writeZip = async ( + prefix: string, + entries: readonly (readonly [name: string, content: string | null])[], +) => { + const directory = await createTestTempDirectory(prefix); + const path = join(directory, "fixture.zip"); + const writer = new ZipWriter(new Uint8ArrayWriter()); + const options = { lastModDate: new Date("2020-01-01T00:00:00Z") }; + for (const [name, content] of entries) + await (content === null + ? writer.add(name, undefined, { ...options, directory: true }) + : writer.add(name, new TextReader(content), options)); + await writeFile(path, await writer.close()); + return { directory, path }; +}; + +describe("virtual directory identity", () => { + // The exact canonical JSON hashed to fingerprint an empty directory. + const directoryFingerprint = '{"children":[],"kind":"directory"}'; + + it.each([ + ["directory-first", false], + ["file-first", true], + ] as const)( + "keeps a file holding a directory fingerprint distinct from the directory (%s)", + async (_order, fileFirst) => { + const entries = [ + ["empty/", null], + ["payload.json", directoryFingerprint], + ] as const; + const { directory, path } = await writeZip( + "rea-virtual-identity-", + fileFirst ? [...entries].reverse() : entries, + ); + const inventory = await inventoryArtifact(path); + const node = (logicalPath: string) => { + const occurrence = inventory.occurrences.find( + (item) => item.logical_path === logicalPath, + ); + return inventory.nodes.find( + (item) => item.artifact_id === occurrence?.artifact_id, + ); + }; + const file = node("payload.json"); + const empty = node("empty"); + expect(file).toMatchObject({ + format: "file", + size: Buffer.byteLength(directoryFingerprint), + content_state: "embedded", + }); + expect(empty).toMatchObject({ + format: "directory", + size: 0, + content_state: "virtual", + }); + // Same digest input, different representation: identities must differ. + expect(empty?.sha256).toBe(file?.sha256); + expect(empty?.artifact_id).not.toBe(file?.artifact_id); + expect(() => + parseArtifactInventoryEvidence(zipInventoryEvidence(path, inventory)), + ).not.toThrow(); + + const output = join(directory, "out"); + await withArtifactResourceScope((resourceScope) => + extractArtifact({ + inputPath: path, + inputFormat: "zip", + outputRoot: output, + environment: {}, + integrityPolicy: "fail", + resourceScope, + }), + ); + expect(await readFile(join(output, "payload.json"), "utf8")).toBe( + directoryFingerprint, + ); + }, + ); + + it("still accepts retained Evidence with a legacy virtual directory identity", async () => { + const { path } = await writeZip("rea-legacy-identity-", [ + ["empty/", null], + ["payload.txt", "payload\n"], + ]); + const current = await inventoryArtifact(path); + const legacy = withLegacyVirtualIdentities(current); + expect(legacy.nodes).not.toEqual(current.nodes); + expect(() => + parseArtifactInventoryEvidence(zipInventoryEvidence(path, legacy)), + ).not.toThrow(); + }); +}); diff --git a/src/domain/artifactIdentity.ts b/src/domain/artifactIdentity.ts index a10fd5df79..11df3e6081 100644 --- a/src/domain/artifactIdentity.ts +++ b/src/domain/artifactIdentity.ts @@ -37,6 +37,18 @@ export const logicalPathEscapesRoot = (path: string): boolean => export const artifactIdForContent = (sha256: string): string => `art_${digestCanonicalValue({ sha256 }, "Artifact")}`; +/** + * Identify a node by its digest and representation. A virtual directory's + * digest covers REA's canonical listing JSON, and a regular file may contain + * exactly those bytes, so virtual nodes take a separate identity domain. + */ +export const artifactIdForNode = ( + node: Pick, +): string => + node.content_state === "virtual" + ? `art_${digestCanonicalValue({ sha256: node.sha256, content_state: "virtual" }, "Artifact")}` + : artifactIdForContent(node.sha256); + /** Identify an occurrence by its root and exact logical location. */ export const occurrenceIdForLocation = (input: { readonly rootArtifactId: string; diff --git a/src/domain/artifactInventoryEvidence.ts b/src/domain/artifactInventoryEvidence.ts index 681b09ae36..7ee00f5356 100644 --- a/src/domain/artifactInventoryEvidence.ts +++ b/src/domain/artifactInventoryEvidence.ts @@ -19,6 +19,7 @@ import { artifactEdgeId, artifactGraphDigest, artifactIdForContent, + artifactIdForNode, artifactManifestId, occurrenceIdForLocation, } from "./artifactIdentity.js"; @@ -369,7 +370,14 @@ const validateInventoryPage = (inventory: ArtifactInventoryResult): void => { "edge ID", ); for (const node of inventory.nodes) - if (node.artifact_id !== artifactIdForContent(node.sha256)) + if ( + node.artifact_id !== artifactIdForNode(node) && + // Evidence retained before virtual identities were domain-separated. + !( + node.content_state === "virtual" && + node.artifact_id === artifactIdForContent(node.sha256) + ) + ) throw new ArtifactInventoryValidationError( "Artifact node ID is not content-addressed", ); diff --git a/tests/boundary/filesystem/artifactDirectoryIdentity.test.ts b/tests/boundary/filesystem/artifactDirectoryIdentity.test.ts index 258f1fe098..76fde604d3 100644 --- a/tests/boundary/filesystem/artifactDirectoryIdentity.test.ts +++ b/tests/boundary/filesystem/artifactDirectoryIdentity.test.ts @@ -74,6 +74,8 @@ const directoryIdForChildren = ( }, "Artifact", ), + // Virtual listings take their own identity domain (#8551). + content_state: "virtual", }, "Artifact", )}`;