From aba42b47b9b1933c1a422272f16a4b2fac95aabc Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 03:07:22 +0800 Subject: [PATCH] refactor(domain): compare snapshot targets through one target identity key (#11341) * refactor(domain): compare snapshot targets through one target identity key * fix(domain): refuse snapshot targets whose kind their format cannot have --- src/application/BinaryTargetResolver.ts | 32 +---- .../binary/AnalysisSnapshotCache.ts | 7 +- src/domain/analysisSnapshot.test.ts | 20 +++ src/domain/analysisSnapshot.ts | 128 +++++++++++------- src/domain/binaryTargetTypes.ts | 54 +++++++- src/domain/targetIdentity.test.ts | 92 +++++++++++++ src/domain/targetIdentity.ts | 44 ++++++ 7 files changed, 301 insertions(+), 76 deletions(-) create mode 100644 src/domain/targetIdentity.test.ts create mode 100644 src/domain/targetIdentity.ts diff --git a/src/application/BinaryTargetResolver.ts b/src/application/BinaryTargetResolver.ts index 79a0f9cb3e..8b43d61767 100644 --- a/src/application/BinaryTargetResolver.ts +++ b/src/application/BinaryTargetResolver.ts @@ -37,11 +37,12 @@ import { cancelledBy, carriedReason, } from "../domain/analysisErrorCore.js"; -import type { - BinaryTarget, - BinaryArchitecture, - PeCodeViewRecord, - UniversalMachOSlice, +import { + BINARY_TARGET_FORMAT_KINDS, + type BinaryTarget, + type BinaryArchitecture, + type PeCodeViewRecord, + type UniversalMachOSlice, } from "../domain/binaryTargetTypes.js"; import { err, ok, type Result } from "../domain/result.js"; import { readMipsElfMetadata } from "./MipsElfMetadata.js"; @@ -91,7 +92,6 @@ import { import { espFlashSelectionError } from "../domain/firmware/espFlashSelection.js"; import { locateTrailingZipArchive, - isZipPackageFormat, zipRootPackageFormat, } from "../domain/zipPackageFormat.js"; @@ -874,25 +874,7 @@ const isArchiveFormat = ( | "gamecube-dol" >, ): format is Extract["format"] => - isZipPackageFormat(format) || - [ - "asar", - "ines", - "godot-pck", - "unityfs", - "wxapkg", - "uimage", - "dmg", - "pkg", - "intel-hex", - "srec", - "esp-image", - "uf2", - "dfuse", - "esp-flash-image", - "fit", - "ntfs-mft", - ].includes(format); + BINARY_TARGET_FORMAT_KINDS[format] === "archive"; /** Whether the leading bytes begin any executable header family, valid or not. */ const claimsLeadingExecutableHeader = async ( diff --git a/src/application/binary/AnalysisSnapshotCache.ts b/src/application/binary/AnalysisSnapshotCache.ts index c46efd47f6..1bb4ecc7f0 100644 --- a/src/application/binary/AnalysisSnapshotCache.ts +++ b/src/application/binary/AnalysisSnapshotCache.ts @@ -24,6 +24,7 @@ import { snapshotBindingMismatch, snapshotMatchesProfile, snapshotTarget, + snapshotTargetIdentity, parseAnalysisSnapshot, immutableAnalysisSnapshot, type AnalysisSnapshot, @@ -47,6 +48,7 @@ import { snapshotReplayBinding, type SnapshotReplayBinding, } from "./AnalysisSnapshotReplayBinding.js"; +import { sameTargetIdentity } from "../../domain/targetIdentity.js"; import { createInvestigationEvidenceClosureChecker } from "../investigation/InvestigationEvidence.js"; const RELATIONSHIP_OPERATIONS: ReadonlySet = new Set([ @@ -226,7 +228,10 @@ export class AnalysisSnapshotCache { snapshot = immutableAnalysisSnapshot(snapshot); if ( (this.#target !== undefined && - JSON.stringify(this.#target) !== JSON.stringify(snapshot.target)) || + !sameTargetIdentity( + snapshotTargetIdentity(this.#target), + snapshotTargetIdentity(snapshot.target), + )) || (this.#binding !== undefined && !snapshotMatchesProfile( this.#binding, diff --git a/src/domain/analysisSnapshot.test.ts b/src/domain/analysisSnapshot.test.ts index 74a22f0536..77af142042 100644 --- a/src/domain/analysisSnapshot.test.ts +++ b/src/domain/analysisSnapshot.test.ts @@ -190,6 +190,26 @@ describe("analysis snapshot target identity", () => { }); }); +it("refuses a snapshot target whose kind its format cannot have", () => { + const target = snapshotTarget(ANALYSIS_SNAPSHOT_TARGET); + const snapshot = { + target, + binding: snapshotBinding(ANALYSIS_SNAPSHOT_PROFILE), + entries: [], + workflow_entries: [], + evidence_bundle: createEvidenceBundle([]), + }; + expect(analysisSnapshotSchema.safeParse(snapshot).success).toBe(true); + // Query IDs commit to the kind: such a header would import entries that no + // lookup or export of the executable can reach. + expect( + analysisSnapshotSchema.safeParse({ + ...snapshot, + target: { ...target, kind: "archive" }, + }).success, + ).toBe(false); +}); + describe("analysis snapshot nested subject contract", () => { it.each(RAW_ONLY_ARCHITECTURES)( "rejects raw-only %s in nested detected execution subjects", diff --git a/src/domain/analysisSnapshot.ts b/src/domain/analysisSnapshot.ts index 2b6699908e..7f882c7ad4 100644 --- a/src/domain/analysisSnapshot.ts +++ b/src/domain/analysisSnapshot.ts @@ -10,6 +10,10 @@ import { compositeKey, } from "./unicodeCodePointOrder.js"; import { localPathStringSchema } from "./localPath.js"; +import { + sameTargetIdentity, + type FileTargetIdentity, +} from "./targetIdentity.js"; import { analysisProfileSchema, @@ -20,6 +24,7 @@ import { } from "./analysisProfile.js"; import { BINARY_ARCHITECTURES, + BINARY_TARGET_FORMAT_KINDS, RAW_ONLY_ARCHITECTURES, type BinaryTarget, } from "./binaryTargetTypes.js"; @@ -103,41 +108,57 @@ const targetIdentitySchema = z.object({ kind: kindSchema, architecture: architectureSchema.nullable(), }); -const targetSchema = z.discriminatedUnion("format", [ - targetIdentitySchema.extend({ - format: z.enum( - formatSchema.options.filter( - (format) => - format !== "raw-binary" && - format !== "gamecube-dol" && - format !== "esp-flash-image", +const targetSchema = z + .discriminatedUnion("format", [ + targetIdentitySchema.extend({ + format: z.enum( + formatSchema.options.filter( + (format) => + format !== "raw-binary" && + format !== "gamecube-dol" && + format !== "esp-flash-image", + ), ), - ), - architecture: architectureSchema - .exclude([...RAW_ONLY_ARCHITECTURES]) - .nullable(), - }), - targetIdentitySchema.extend({ - format: z.literal("raw-binary"), - kind: z.literal("executable"), - architecture: binaryArchitectureSchema, - entry_point: rawBinaryEntryPointSchema, - }), - targetIdentitySchema.extend({ - format: z.literal("gamecube-dol"), - kind: z.literal("executable"), - architecture: z.literal("powerpc"), - entry_point: rawBinaryEntryPointSchema, - }), - // The caller's inputs select how the dump is read, so they are identity. - targetIdentitySchema.extend({ - format: z.literal("esp-flash-image"), - kind: z.literal("archive"), - architecture: z.null(), - flash_offset: z.number().int().min(0).max(0xffff_ffff).nullable(), - partition_table_offset: z.number().int().min(0).max(0xffff_ffff).nullable(), - }), -]); + architecture: architectureSchema + .exclude([...RAW_ONLY_ARCHITECTURES]) + .nullable(), + }), + targetIdentitySchema.extend({ + format: z.literal("raw-binary"), + kind: z.literal("executable"), + architecture: binaryArchitectureSchema, + entry_point: rawBinaryEntryPointSchema, + }), + targetIdentitySchema.extend({ + format: z.literal("gamecube-dol"), + kind: z.literal("executable"), + architecture: z.literal("powerpc"), + entry_point: rawBinaryEntryPointSchema, + }), + // The caller's inputs select how the dump is read, so they are identity. + targetIdentitySchema.extend({ + format: z.literal("esp-flash-image"), + kind: z.literal("archive"), + architecture: z.null(), + flash_offset: z.number().int().min(0).max(0xffff_ffff).nullable(), + partition_table_offset: z + .number() + .int() + .min(0) + .max(0xffff_ffff) + .nullable(), + }), + ]) + .superRefine((target, context) => { + // Query IDs commit to the kind, so a kind the format cannot have would + // admit entries that no live lookup or export of this target can reach. + if (target.kind !== BINARY_TARGET_FORMAT_KINDS[target.format]) + context.addIssue({ + code: "custom", + path: ["kind"], + message: `Snapshot target kind ${target.kind} does not match format ${target.format}`, + }); + }); const bindingSchema = z .object({ provider: committedProviderSchema, @@ -475,26 +496,35 @@ export const snapshotBinding = ( analysis_profile: profile, }); +/** The target identity a persisted snapshot target names. */ +export const snapshotTargetIdentity = ( + target: AnalysisSnapshotTarget, +): FileTargetIdentity => ({ + kind: "file", + sha256: target.sha256, + format: target.format, + architecture: target.architecture, + selection: + target.format === "raw-binary" || target.format === "gamecube-dol" + ? { kind: "entry-point", entry_point: target.entry_point } + : target.format === "esp-flash-image" + ? { + kind: "esp-flash", + flash_offset: target.flash_offset, + partition_table_offset: target.partition_table_offset, + } + : null, +}); + /** Compare an open binary with the immutable target identity in a snapshot. */ export const snapshotMatchesTarget = ( snapshot: AnalysisSnapshotTarget, target: BinaryTarget, ): boolean => - snapshot.sha256 === target.sha256 && - snapshot.kind === target.kind && - snapshot.format === target.format && - snapshot.architecture === (target.architecture ?? null) && - (snapshot.format !== "raw-binary" || - (target.format === "raw-binary" && - snapshot.entry_point === target.entryPoint)) && - (snapshot.format !== "gamecube-dol" || - (target.format === "gamecube-dol" && - snapshot.entry_point === target.entryPoint)) && - (snapshot.format !== "esp-flash-image" || - (target.format === "esp-flash-image" && - snapshot.flash_offset === target.espFlash.flashOffset && - snapshot.partition_table_offset === - target.espFlash.partitionTableOffset)); + sameTargetIdentity( + snapshotTargetIdentity(snapshot), + snapshotTargetIdentity(snapshotTarget(target)), + ); /** Compare a snapshot binding with the selected concrete analysis profile. */ export const snapshotMatchesProfile = ( diff --git a/src/domain/binaryTargetTypes.ts b/src/domain/binaryTargetTypes.ts index 7e6ed84afa..c57c2beff5 100644 --- a/src/domain/binaryTargetTypes.ts +++ b/src/domain/binaryTargetTypes.ts @@ -1,5 +1,8 @@ import type { DolHeader } from "./gamecubeDol.js"; -import type { ZipPackageFormat } from "./zipPackageFormat.js"; +import { + ZIP_PACKAGE_FORMATS, + type ZipPackageFormat, +} from "./zipPackageFormat.js"; /** Provider-neutral CPU families detected from headers or explicitly selected raw loads. */ export const BINARY_ARCHITECTURES = [ @@ -336,6 +339,55 @@ export type BinaryTarget = readonly format: "plist" | "javascript" | "source-map"; }); +/** The kind of every target variant that may carry `Format`. */ +type TargetKindOf = BinaryTarget extends infer Target + ? Target extends { readonly format: infer Formats; readonly kind: infer Kind } + ? Format extends Formats + ? Kind + : never + : never + : never; + +/** + * The one kind each target format has. A target, snapshot or identity whose + * kind disagrees with its format is malformed. + */ +export const BINARY_TARGET_FORMAT_KINDS = { + "analysis-database": "database", + "mach-o": "executable", + "mach-o-universal": "executable", + elf: "executable", + pe: "executable", + "dos-mz": "executable", + "dos-com": "executable", + "raw-binary": "executable", + "gamecube-dol": "executable", + ...(Object.fromEntries( + ZIP_PACKAGE_FORMATS.map((format) => [format, "archive"]), + ) as Record), + asar: "archive", + ines: "archive", + "godot-pck": "archive", + unityfs: "archive", + wxapkg: "archive", + uimage: "archive", + dmg: "archive", + pkg: "archive", + "intel-hex": "archive", + srec: "archive", + "esp-image": "archive", + uf2: "archive", + dfuse: "archive", + "esp-flash-image": "archive", + fit: "archive", + "ntfs-mft": "archive", + plist: "artifact", + javascript: "artifact", + "source-map": "artifact", +} as const satisfies { + readonly [Format in BinaryTarget["format"]]: TargetKindOf; +}; + /** Caller inputs that select how an ESP flash dump is read. */ export interface EspFlashTargetSelection { /** The caller selected the format, so the table scan runs without a bootloader. */ diff --git a/src/domain/targetIdentity.test.ts b/src/domain/targetIdentity.test.ts new file mode 100644 index 0000000000..57c5582d65 --- /dev/null +++ b/src/domain/targetIdentity.test.ts @@ -0,0 +1,92 @@ +import { describe, expect, it } from "vitest"; + +import { snapshotTarget, snapshotTargetIdentity } from "./analysisSnapshot.js"; +import type { BinaryTarget } from "./binaryTargetTypes.js"; +import { + sameTargetIdentity, + targetIdentityKey, + type FileTargetIdentity, +} from "./targetIdentity.js"; + +const SHA256 = "a".repeat(64); + +describe("target identity key", () => { + it("does not depend on member order", () => { + const identity: FileTargetIdentity = { + kind: "file", + sha256: SHA256, + format: "raw-binary", + architecture: "arm", + selection: { kind: "entry-point", entry_point: "0x8000000" }, + }; + const reordered: FileTargetIdentity = { + selection: { entry_point: "0x8000000", kind: "entry-point" }, + architecture: "arm", + format: "raw-binary", + sha256: SHA256, + kind: "file", + }; + expect(JSON.stringify(reordered)).not.toBe(JSON.stringify(identity)); + expect(targetIdentityKey(reordered)).toBe(targetIdentityKey(identity)); + expect(targetIdentityKey(identity)).toMatch(/^target_[0-9a-f]{64}$/u); + }); + + it("separates the same bytes under different selections", () => { + const raw: BinaryTarget = { + path: "/fixture/image.bin", + sha256: SHA256, + kind: "executable", + format: "raw-binary", + architecture: "arm", + availableArchitectures: ["arm"], + entryPoint: "0x8000000", + entryPointSource: "0x08000000", + }; + const identity = snapshotTargetIdentity(snapshotTarget(raw)); + expect(identity).toEqual({ + kind: "file", + sha256: SHA256, + format: "raw-binary", + architecture: "arm", + selection: { kind: "entry-point", entry_point: "0x8000000" }, + }); + const moved = snapshotTargetIdentity( + snapshotTarget({ ...raw, entryPoint: "0x9000000" }), + ); + expect(sameTargetIdentity(identity, moved)).toBe(false); + + const flash: BinaryTarget = { + path: "/fixture/flash.bin", + sha256: SHA256, + kind: "archive", + format: "esp-flash-image", + espFlash: { selected: true, flashOffset: 0, partitionTableOffset: null }, + }; + const flashIdentity = snapshotTargetIdentity(snapshotTarget(flash)); + expect(flashIdentity.selection).toEqual({ + kind: "esp-flash", + flash_offset: 0, + partition_table_offset: null, + }); + expect( + sameTargetIdentity( + flashIdentity, + snapshotTargetIdentity( + snapshotTarget({ + ...flash, + espFlash: { ...flash.espFlash, flashOffset: 0x1000 }, + }), + ), + ), + ).toBe(false); + // The path is display, not identity. + expect( + sameTargetIdentity( + flashIdentity, + snapshotTargetIdentity( + snapshotTarget({ ...flash, path: "/elsewhere" }), + ), + ), + ).toBe(true); + }); +}); diff --git a/src/domain/targetIdentity.ts b/src/domain/targetIdentity.ts new file mode 100644 index 0000000000..3b1adfaf84 --- /dev/null +++ b/src/domain/targetIdentity.ts @@ -0,0 +1,44 @@ +import { createHash } from "node:crypto"; + +import canonicalize from "canonicalize"; + +/** + * Facts inside a file's bytes that select what was analysed. Two observations + * of the same bytes with different selections are different targets. + */ +export type FileTargetSelection = + | { readonly kind: "entry-point"; readonly entry_point: string } + | { + readonly kind: "esp-flash"; + readonly flash_offset: number | null; + readonly partition_table_offset: number | null; + }; + +/** A hashed local file, path-free. */ +export interface FileTargetIdentity { + readonly kind: "file"; + readonly sha256: string; + readonly format: string; + readonly architecture: string | null; + readonly selection: FileTargetSelection | null; +} + +/** + * What an observation or cache entry is about. Tagged by `kind`; see + * docs/adr/evidence/target-identity.md for the kinds later slices add. + */ +export type TargetIdentity = FileTargetIdentity; + +/** The only comparison of two target identities: an RFC 8785 canonical digest. */ +export const targetIdentityKey = (identity: TargetIdentity): string => { + const encoded = canonicalize(identity); + if (encoded === undefined) + throw new TypeError("RFC 8785 canonicalization rejected a target identity"); + return `target_${createHash("sha256").update(encoded).digest("hex")}`; +}; + +/** Whether two identities name the same target. */ +export const sameTargetIdentity = ( + left: TargetIdentity, + right: TargetIdentity, +): boolean => targetIdentityKey(left) === targetIdentityKey(right);