From 7134053d27268f7e1070c867047ec59bb7fe7497 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 20:35:28 +0800 Subject: [PATCH] feat(artifacts): name integrity checks for DMG, directory and release-exposure readers (#11056) * feat(artifacts): name integrity checks for DMG, directory and release-exposure readers Directory members and release-exposure members whose file identity or bytes changed since inventory report member-identity; a directory entry without captured state reports entry-metadata and a changed directory root container-identity; an hdiutil checksum failure reports image-checksum. AnalysisArtifactChangedError carries the check from the reader failure and projects it as details.integrity_check. * fix(artifacts): name missing directory entry state and keep integrity checks through error copies * feat(artifacts): name integrity checks for ZIP, PyInstaller and changed release files (#11081) feat(artifacts): name integrity checks for ZIP, PyInstaller and changed release files, and keep them through reader projections * feat(artifacts): name integrity checks for the remaining readers and their projections (#11098) --- src/android/AndroidMappingFile.ts | 13 ++--- src/apkSignature/apkSignatureFailures.ts | 10 ++-- .../apiContract/ApiContractRead.ts | 9 +--- src/application/ntfs/NtfsJournalService.ts | 6 +-- .../ArtifactEmbeddedFormatProbes.test.ts | 7 ++- src/artifacts/ArtifactEmbeddedFormatProbes.ts | 1 + .../ArtifactOperationFailure.test.ts | 27 +++++++++- src/artifacts/DirectoryArtifactReader.ts | 52 +++++++++++++------ src/artifacts/FitArtifactReader.test.ts | 1 + src/artifacts/FitArtifactReader.ts | 5 ++ src/artifacts/InesArtifactReader.ts | 24 +++++++-- src/artifacts/MachOSliceArtifactReader.ts | 19 +++++-- src/artifacts/NativeDmgArtifactReader.ts | 22 ++++---- src/artifacts/PyInstallerArtifactReader.ts | 4 ++ src/artifacts/ReleaseExposureReader.test.ts | 52 +++++++++++++++++-- src/artifacts/ReleaseExposureReader.ts | 44 ++++++++++++---- src/artifacts/SafeOutputTree.ts | 7 +++ src/artifacts/SafeOutputTreeReadback.ts | 1 + src/artifacts/StableArtifactFailure.ts | 21 ++++++-- src/artifacts/ZipArtifactReader.ts | 6 +++ src/artifacts/fit/FitStructure.ts | 1 + src/artifacts/inventory/classify.ts | 6 ++- src/artifacts/inventory/scanReader.ts | 9 ++-- .../javascript/JavaScriptArtifactFiles.ts | 8 +++ .../pyinstaller/PyInstallerBoundaries.test.ts | 21 ++++++++ .../pyinstaller/PyInstallerMemberStream.ts | 2 + .../pyinstaller/PyInstallerPyzStore.ts | 1 + src/browser/history/CaptureFailures.ts | 13 ++--- .../history/playwrightTrace/TraceFailure.ts | 10 ++-- src/captures/TsharkCaptureProvider.ts | 5 +- src/domain/analysisErrorCore.ts | 8 ++- src/domain/analysisErrorProjection.test.ts | 16 ++++++ src/domain/analysisErrorProjection.ts | 3 ++ src/domain/artifactOperationError.ts | 22 ++++++-- src/domain/comparisonEvidenceResult.test.ts | 9 ++++ src/domain/comparisonEvidenceResult.ts | 3 ++ src/domain/comparisonSourceEvidence.ts | 8 ++- src/domain/explicitSensitiveFailure.ts | 2 +- .../managed/managedInspectionEvidence.ts | 4 +- .../managedNativeVerificationSource.ts | 2 + src/domain/reconstructionVerification.ts | 2 + src/ghidra/GhidraProvider.behavior.test.ts | 30 +++++++++-- src/ghidra/GhidraProviderClient.ts | 2 +- src/gpu/GpuCodeObjectsProvider.ts | 10 ++-- src/model/ModelArtifactProvider.ts | 11 ++-- src/native/AppleDispatchMetadata.ts | 5 +- src/native/NativeMacOSProvider.ts | 9 +--- src/native/NativePlistSource.ts | 9 +--- src/native/pe/PeBinaryFailure.ts | 9 +--- src/providers/AnalysisClientFailure.test.ts | 18 +++++++ src/providers/AnalysisClientFailure.ts | 2 +- src/providers/classifyProviderFailure.ts | 17 +++--- src/rust/RustBinaryProvider.ts | 6 +-- src/sqlite/SqliteDatabaseFailures.ts | 10 ++-- src/sqlite/SqliteDatabaseSnapshot.ts | 12 ++++- .../artifactAdmittedIdentity.test.ts | 4 +- .../artifactInventoryRegularRoot.test.ts | 2 +- .../filesystem/artifactZipIntegrity.test.ts | 22 +++++--- .../directoryArtifactReaderOpen.test.ts | 5 +- .../boundary/filesystem/inesArtifact.test.ts | 2 +- .../javascriptIntegrityPolicy.test.ts | 2 +- .../artifactProvider.machOSlices.test.ts | 5 +- .../native/nativeDmgArtifactReader.test.ts | 1 + 63 files changed, 494 insertions(+), 185 deletions(-) diff --git a/src/android/AndroidMappingFile.ts b/src/android/AndroidMappingFile.ts index e8dcd71d10..feae218f09 100644 --- a/src/android/AndroidMappingFile.ts +++ b/src/android/AndroidMappingFile.ts @@ -4,7 +4,10 @@ import { bindArtifactFileCleanup, } from "../artifacts/ArtifactFileOperation.js"; import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; -import { stableArtifactInputRecovery } from "../artifacts/StableArtifactFailure.js"; +import { + stableArtifactInputRecovery, + readerIntegrityFailure, +} from "../artifacts/StableArtifactFailure.js"; import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; import { readStableArtifact } from "../artifacts/readStableArtifact.js"; import { @@ -16,7 +19,6 @@ import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; import { AnalysisAccessDeniedError, - AnalysisArtifactChangedError, AnalysisInputError, AnalysisResourceConstraintError, AnalysisTimeoutError, @@ -93,12 +95,7 @@ const readFailurePrimary = ( }, ); if (owned?.reason === "integrity") - return new AnalysisArtifactChangedError( - read.operation, - read.path, - owned.message, - { cause: owned }, - ); + return readerIntegrityFailure(read.operation, read.path, owned); if (owned?.reason === "path") return invalidMapping(read, "invalid_value", owned.message, { cause: owned, diff --git a/src/apkSignature/apkSignatureFailures.ts b/src/apkSignature/apkSignatureFailures.ts index a129774c2e..76d1f84379 100644 --- a/src/apkSignature/apkSignatureFailures.ts +++ b/src/apkSignature/apkSignatureFailures.ts @@ -1,6 +1,9 @@ import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js"; import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; -import { stableArtifactInputFailure } from "../artifacts/StableArtifactFailure.js"; +import { + stableArtifactInputFailure, + readerIntegrityFailure, +} from "../artifacts/StableArtifactFailure.js"; import { artifactFilePrimaryFacts, type ArtifactFilePrimaryFacts, @@ -13,7 +16,6 @@ import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; import { AnalysisAccessDeniedError, - AnalysisArtifactChangedError, AnalysisInputError, AnalysisResourceConstraintError, AnalysisUnsupportedTargetError, @@ -219,9 +221,7 @@ const artifactReaderFailure = ( ): AnalysisError => { switch (cause.reason) { case "integrity": - return new AnalysisArtifactChangedError(OPERATION, path, cause.message, { - cause, - }); + return readerIntegrityFailure(OPERATION, path, cause); case "cancelled": return cancelledBy( OPERATION, diff --git a/src/application/apiContract/ApiContractRead.ts b/src/application/apiContract/ApiContractRead.ts index dc90e4b7a5..e4e72e30fd 100644 --- a/src/application/apiContract/ApiContractRead.ts +++ b/src/application/apiContract/ApiContractRead.ts @@ -8,11 +8,11 @@ import { readStableArtifact } from "../../artifacts/readStableArtifact.js"; import { projectStableArtifactFailure, stableArtifactInputRecovery, + readerIntegrityFailure, } from "../../artifacts/StableArtifactFailure.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; import { AnalysisAccessDeniedError, - AnalysisArtifactChangedError, AnalysisInputError, AnalysisResourceConstraintError, cancelledBy, @@ -69,12 +69,7 @@ const readFailure = ( carriedReason(artifactFileCancellationCause(cause)), ); if (cause.reason === "integrity") - return new AnalysisArtifactChangedError( - operation, - input.path, - cause.message, - { cause }, - ); + return readerIntegrityFailure(operation, input.path, cause); if (cause.reason === "limit") return new AnalysisResourceConstraintError( operation, diff --git a/src/application/ntfs/NtfsJournalService.ts b/src/application/ntfs/NtfsJournalService.ts index ef06cb87a6..9d59c1ba49 100644 --- a/src/application/ntfs/NtfsJournalService.ts +++ b/src/application/ntfs/NtfsJournalService.ts @@ -18,6 +18,7 @@ import { import { projectStableArtifactFailure, stableArtifactInputRecovery, + readerIntegrityFailure, } from "../../artifacts/StableArtifactFailure.js"; import { primaryAnalysisError, @@ -25,7 +26,6 @@ import { } from "../../domain/analysisErrorBase.js"; import { AnalysisAccessDeniedError, - AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisInputError, AnalysisResourceConstraintError, @@ -83,9 +83,7 @@ const readFailure = ( carriedReason(artifactFileCancellationCause(cause)), ); if (cause.reason === "integrity") - return new AnalysisArtifactChangedError(operation, path, cause.message, { - cause, - }); + return readerIntegrityFailure(operation, path, cause); if (cause.reason === "limit") return new AnalysisResourceConstraintError( operation, diff --git a/src/artifacts/ArtifactEmbeddedFormatProbes.test.ts b/src/artifacts/ArtifactEmbeddedFormatProbes.test.ts index 2e9b7a870d..d5912042d6 100644 --- a/src/artifacts/ArtifactEmbeddedFormatProbes.test.ts +++ b/src/artifacts/ArtifactEmbeddedFormatProbes.test.ts @@ -188,7 +188,12 @@ it("reuses a located .NET header only for the same source and honors cached canc await withOwnedRegularFile(path, {}, async (source) => { expect( () => new ArtifactEmbeddedFormatProbes(path, source, undefined, facts), - ).toThrow("Root artifact changed before inventory"); + ).toThrow( + expect.objectContaining({ + reason: "integrity", + integrityCheck: "container-identity", + }), + ); }); expect(locate).toHaveBeenCalledTimes(1); } finally { diff --git a/src/artifacts/ArtifactEmbeddedFormatProbes.ts b/src/artifacts/ArtifactEmbeddedFormatProbes.ts index 75a526b5dd..194a0edbb9 100644 --- a/src/artifacts/ArtifactEmbeddedFormatProbes.ts +++ b/src/artifacts/ArtifactEmbeddedFormatProbes.ts @@ -64,6 +64,7 @@ export class ArtifactEmbeddedFormatProbes { throw new ArtifactReaderFailure( "integrity", `Root artifact changed before inventory: ${path}`, + { integrityCheck: "container-identity" }, ); const reusable = previous !== undefined && diff --git a/src/artifacts/ArtifactOperationFailure.test.ts b/src/artifacts/ArtifactOperationFailure.test.ts index 3a76e63d52..27258bcfdb 100644 --- a/src/artifacts/ArtifactOperationFailure.test.ts +++ b/src/artifacts/ArtifactOperationFailure.test.ts @@ -5,7 +5,10 @@ import { translateArtifactFailure } from "./ArtifactOperationFailure.js"; import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import { artifactReaderLimitFailure } from "./ArtifactReaderLimits.js"; import { constants as bufferConstants } from "node:buffer"; -import { imageFileSizeRemediation } from "./StableArtifactFailure.js"; +import { + imageFileSizeRemediation, + readerIntegrityFailure, +} from "./StableArtifactFailure.js"; import { artifactIntegrityDetails } from "../domain/artifactIntegrity.js"; import { ArtifactFileCleanupFailure } from "./ArtifactFileOperation.js"; import { AnalysisCleanupLease } from "./AnalysisCleanupLease.js"; @@ -224,3 +227,25 @@ it("keeps the named integrity check when a descriptor close failure rebuilds the details: { integrity_check: "read-coverage", cleanup: "incomplete" }, }); }); + +it("keeps a reader's named check when a provider supplies its own cause and options", () => { + const failure = new ArtifactReaderFailure("integrity", "region changed", { + integrityCheck: "reconstruction", + }); + const wrapper = new Error("cleanup wrapper", { cause: failure }); + const capturedOutput = { stdout: "out", stderr: "", truncated: false }; + const changed = readerIntegrityFailure("inspect_gpu", "/target", failure, { + cause: wrapper, + capturedOutput, + }); + expect(changed).toMatchObject({ + cause: wrapper, + capturedOutput, + reason: "region changed", + integrityCheck: "reconstruction", + }); + expect(projectAnalysisError(changed)).toMatchObject({ + code: "artifact_changed", + details: { integrity_check: "reconstruction" }, + }); +}); diff --git a/src/artifacts/DirectoryArtifactReader.ts b/src/artifacts/DirectoryArtifactReader.ts index b9cd95c079..b631f1a3ec 100644 --- a/src/artifacts/DirectoryArtifactReader.ts +++ b/src/artifacts/DirectoryArtifactReader.ts @@ -328,10 +328,14 @@ export class DirectoryArtifactReader implements ArtifactReader { } } + /** Open an entry only against the file state captured when it was enumerated. */ async #openFile( entry: ArtifactEntry, signal?: AbortSignal, - ): Promise> { + ): Promise<{ + readonly owner: OwnedFileHandle; + readonly identity: CapturedSourceIdentity; + }> { abortIfNeeded(signal); await this.#validateRoot(); if (entry.kind !== "file") @@ -339,6 +343,13 @@ export class DirectoryArtifactReader implements ArtifactReader { "format", "Only regular files can be opened", ); + const identity = entry.sourceIdentity; + if (identity === undefined) + throw new ArtifactReaderFailure( + "integrity", + `Directory entry has no captured file state: ${entry.path}`, + { integrityCheck: "entry-metadata" }, + ); const fileHandle = await open( entry.adapterKey, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK, @@ -359,15 +370,16 @@ export class DirectoryArtifactReader implements ArtifactReader { }); if ( !observed.isFile() || - !sameArtifactSourceIdentity(entry.sourceIdentity, observed) + !sameArtifactSourceIdentity(identity, observed) ) { throw new ArtifactReaderFailure( "integrity", `Directory entry changed before open: ${entry.path}`, + { integrityCheck: "member-identity" }, ); } abortIfNeeded(signal); - return owner; + return { owner, identity }; } catch (cause: unknown) { try { await this.#closeFile(owner); @@ -409,7 +421,7 @@ export class DirectoryArtifactReader implements ArtifactReader { inspect: (file: FileHandle) => Promise, signal?: AbortSignal, ): Promise { - const owner = await this.#openFile(entry, signal); + const { owner, identity } = await this.#openFile(entry, signal); try { const value = await withOwnedFileHandle( entry.adapterKey, @@ -444,13 +456,16 @@ export class DirectoryArtifactReader implements ArtifactReader { if ( !opened.isFile() || !named.isFile() || - !sameArtifactSourceIdentity(entry.sourceIdentity, opened) || - !sameArtifactSourceIdentity(entry.sourceIdentity, named) + !sameArtifactSourceIdentity(identity, opened) || + !sameArtifactSourceIdentity(identity, named) ) throw new ArtifactReaderFailure( "integrity", `Directory entry changed during inspection: ${entry.path}${outcome.kind === "failed" ? `; inspection failed: ${failureMessage(outcome.cause)}` : ""}`, - outcome.kind === "failed" ? { cause: outcome.cause } : {}, + { + integrityCheck: "member-identity", + ...(outcome.kind === "failed" ? { cause: outcome.cause } : {}), + }, ); if (outcome.kind === "failed") throw outcome.cause; abortIfNeeded(signal); @@ -482,11 +497,12 @@ export class DirectoryArtifactReader implements ArtifactReader { } async open(entry: ArtifactEntry, signal?: AbortSignal): Promise { - const owner = await this.#openFile(entry, signal); + const { owner, identity } = await this.#openFile(entry, signal); const source = Readable.from( mapStableFileRead( owner.handle, entry, + identity, () => this.#validateRoot(), signal, ), @@ -661,20 +677,18 @@ const entryOpenFailure = ( const failureMessage = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause); +type CapturedSourceIdentity = NonNullable; + const mapStableFileRead = async function* ( handle: FileHandle, entry: ArtifactEntry, + identity: CapturedSourceIdentity, validateRoot: () => Promise, signal?: AbortSignal, ): AsyncGenerator { let bytes = 0n; + const expectedBytes = identity.size; try { - const expectedBytes = entry.sourceIdentity?.size; - if (expectedBytes === undefined) - throw new ArtifactReaderFailure( - "integrity", - `Directory entry has no captured file state: ${entry.path}`, - ); for await (const chunk of readArtifactFileChunks(handle, { // Include one extra byte so a growing file cannot make this read unbounded. end: expectedBytes, @@ -694,13 +708,14 @@ const mapStableFileRead = async function* ( if ( !opened.isFile() || !current.isFile() || - !sameArtifactSourceIdentity(entry.sourceIdentity, opened) || - !sameArtifactSourceIdentity(entry.sourceIdentity, current) || + !sameArtifactSourceIdentity(identity, opened) || + !sameArtifactSourceIdentity(identity, current) || bytes !== expectedBytes ) throw new ArtifactReaderFailure( "integrity", `Directory entry changed during read: ${entry.path}`, + { integrityCheck: "member-identity" }, ); } catch (cause: unknown) { if ( @@ -711,7 +726,7 @@ const mapStableFileRead = async function* ( throw new ArtifactReaderFailure( "integrity", `Directory entry changed during read: ${entry.path}`, - { cause }, + { cause, integrityCheck: "member-identity" }, ); if (!(cause instanceof ArtifactReaderFailure)) throw directoryIoFailure("validate read entry", entry.adapterKey, cause); @@ -763,5 +778,8 @@ const assertContainedDirectory = async ( throw new ArtifactReaderFailure( failureReason, "Directory traversal escaped or changed its artifact root", + failureReason === "integrity" + ? { integrityCheck: "container-identity" } + : undefined, ); }; diff --git a/src/artifacts/FitArtifactReader.test.ts b/src/artifacts/FitArtifactReader.test.ts index d3a28fbccb..87601693f8 100644 --- a/src/artifacts/FitArtifactReader.test.ts +++ b/src/artifacts/FitArtifactReader.test.ts @@ -180,6 +180,7 @@ it.each(["crc32", "md5", "sha1", "sha256", "sha384", "sha512"])( scanCanonicalArtifactInventory(await writeFit("bad.itb", bytes)), ).rejects.toMatchObject({ reason: "integrity", + integrityCheck: "declared-digest", message: expect.stringMatching( new RegExp( `^FIT image kernel hash-1 ${algo} does not match: declared [0-9a-f]+, computed [0-9a-f]+$`, diff --git a/src/artifacts/FitArtifactReader.ts b/src/artifacts/FitArtifactReader.ts index 0825834e75..f78c5249ef 100644 --- a/src/artifacts/FitArtifactReader.ts +++ b/src/artifacts/FitArtifactReader.ts @@ -98,6 +98,10 @@ export class FitArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", "FIT entry does not match its owning inventory", + { + integrityCheck: + stored === undefined ? "foreign-entry" : "entry-metadata", + }, ); const { handle } = await this.#source.read(signal); this.#assertOpen(signal); @@ -241,6 +245,7 @@ export class FitArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", `FIT image ${image.name} ${hash.node} ${hash.algo} does not match: declared ${hash.value.toString("hex")}, computed ${computed.toString("hex")}`, + { integrityCheck: "declared-digest" }, ); } } diff --git a/src/artifacts/InesArtifactReader.ts b/src/artifacts/InesArtifactReader.ts index 21e2870d76..7f380e38ba 100644 --- a/src/artifacts/InesArtifactReader.ts +++ b/src/artifacts/InesArtifactReader.ts @@ -90,12 +90,22 @@ export class InesArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", "iNES region does not match this reader's inventory", + { + integrityCheck: + produced === undefined ? "foreign-entry" : "entry-metadata", + }, ); await this.#verifySource(signal); const offset = produced.byteOffset; const size = produced.declaredSize; if (offset === null || size === null || size <= 0) - throw new ArtifactReaderFailure("integrity", "Invalid iNES region range"); + throw new ArtifactReaderFailure( + "integrity", + "Invalid iNES region range", + { + integrityCheck: "layout-consistency", + }, + ); const stream = readArtifactFileChunks(this.source.handle, { start: offset, end: offset + size - 1, @@ -116,6 +126,7 @@ export class InesArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", "Truncated iNES region", + { integrityCheck: "read-coverage" }, ); await verify(); } catch (cause: unknown) { @@ -138,7 +149,13 @@ export class InesArtifactReader implements ArtifactReader { abortIfNeeded(signal); const layout = this.#layout; if (layout === undefined || this.#entries.size !== layout.regions.length) - throw new ArtifactReaderFailure("integrity", "Incomplete iNES inventory"); + throw new ArtifactReaderFailure( + "integrity", + "Incomplete iNES inventory", + { + integrityCheck: "reconstruction", + }, + ); await this.#verifySource(signal); if ( observed.region_order.length !== layout.regions.length || @@ -151,6 +168,7 @@ export class InesArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", "iNES reconstruction differs from the source", + { integrityCheck: "reconstruction" }, ); return { header: layout.header, @@ -186,7 +204,7 @@ export class InesArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", "iNES source changed during reading", - { cause: cause.cause ?? cause }, + { cause: cause.cause ?? cause, integrityCheck: "container-identity" }, ); throw artifactOperationCause(cause); } diff --git a/src/artifacts/MachOSliceArtifactReader.ts b/src/artifacts/MachOSliceArtifactReader.ts index 446bb7aedb..550a255375 100644 --- a/src/artifacts/MachOSliceArtifactReader.ts +++ b/src/artifacts/MachOSliceArtifactReader.ts @@ -157,6 +157,7 @@ export class MachOSliceArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", `Mach-O structural slice index is malformed: ${structural.reason}`, + { integrityCheck: "layout-consistency" }, ); // A valid universal binary can hold slices REA cannot index, such as // big-endian PowerPC. lipo's own ranges still inventory every slice. @@ -176,7 +177,9 @@ export class MachOSliceArtifactReader implements ArtifactReader { const disagreements: string[] = []; const disagree = (message: string): void => { if (this.integrity === "fail") - throw new ArtifactReaderFailure("integrity", message); + throw new ArtifactReaderFailure("integrity", message, { + integrityCheck: "layout-consistency", + }); disagreements.push(message); }; const hiddenArchitectures = architectures.filter(({ hidden }) => hidden); @@ -298,6 +301,7 @@ export class MachOSliceArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", "lipo omitted a universal slice byte range", + { integrityCheck: "layout-consistency" }, ); yield this.#sliceEntry(architecture.name, offset, sliceSize, fileSize, [ ...architecture.limitations, @@ -342,6 +346,7 @@ export class MachOSliceArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", `Mach-O slice range is outside the artifact: ${name}`, + { integrityCheck: "layout-consistency" }, ); const entry: ArtifactEntry = { path: `slices/${name}`, @@ -380,6 +385,10 @@ export class MachOSliceArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", "Mach-O slice entry metadata does not match this reader's inventory", + { + integrityCheck: + produced === undefined ? "foreign-entry" : "entry-metadata", + }, ); const offset = produced.byteOffset; const size = produced.declaredSize; @@ -394,6 +403,7 @@ export class MachOSliceArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", "Invalid Mach-O slice byte range", + { integrityCheck: "layout-consistency" }, ); const source = await this.#ensureSource(); await this.#source.readSelectedPath(); @@ -409,6 +419,7 @@ export class MachOSliceArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", `Mach-O slice range is outside the artifact: ${entry.path}`, + { integrityCheck: "layout-consistency" }, ); const sourceStream = readArtifactFileChunks(source.handle, { start: offset, @@ -423,11 +434,13 @@ export class MachOSliceArtifactReader implements ArtifactReader { return new ArtifactReaderFailure( "integrity", `Mach-O slice read coverage is incomplete: ${entry.path}`, + { integrityCheck: "read-coverage" }, ); if (coverage.bytes !== BigInt(size)) return new ArtifactReaderFailure( "integrity", `Mach-O slice size disagrees with lipo metadata: ${entry.path}`, + { integrityCheck: "declared-size" }, ); if (signal?.aborted) return new ArtifactReaderFailure( @@ -456,7 +469,7 @@ export class MachOSliceArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", `Could not read Mach-O slice range: ${entry.path}`, - { cause }, + { cause, integrityCheck: "read-coverage" }, ); } validatingSource = true; @@ -494,7 +507,7 @@ export class MachOSliceArtifactReader implements ArtifactReader { : new ArtifactReaderFailure( "integrity", `Could not read Mach-O slice range: ${entry.path}`, - { cause }, + { cause, integrityCheck: "read-coverage" }, )), ); }; diff --git a/src/artifacts/NativeDmgArtifactReader.ts b/src/artifacts/NativeDmgArtifactReader.ts index 5ee2c355d7..d2fbd8f9f3 100644 --- a/src/artifacts/NativeDmgArtifactReader.ts +++ b/src/artifacts/NativeDmgArtifactReader.ts @@ -91,18 +91,16 @@ class NativeDmgCommandFailure extends ArtifactReaderFailure { readonly exitCode?: number; }, ) { - super( - failure.reason, - message, - options === undefined - ? undefined - : { - ...(options.cause === undefined ? {} : { cause: options.cause }), - ...(options.cancellation === undefined - ? {} - : { cancellation: options.cancellation }), - }, - ); + super(failure.reason, message, { + ...(options?.cause === undefined ? {} : { cause: options.cause }), + ...(options?.cancellation === undefined + ? {} + : { cancellation: options.cancellation }), + // Only hdiutil verify classifies a DMG failure as integrity. + ...(failure.reason === "integrity" + ? { integrityCheck: "image-checksum" as const } + : {}), + }); this.processNotStarted = options?.processNotStarted ?? false; this.verifyDiagnostic = failure.verifyDiagnostic; this.unrecognizedImage = failure.unrecognizedImage ?? false; diff --git a/src/artifacts/PyInstallerArtifactReader.ts b/src/artifacts/PyInstallerArtifactReader.ts index 3298164dcd..6da4ba8c4b 100644 --- a/src/artifacts/PyInstallerArtifactReader.ts +++ b/src/artifacts/PyInstallerArtifactReader.ts @@ -199,6 +199,10 @@ export class PyInstallerArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", `PyInstaller entry was not produced by this reader: ${entry.path}`, + { + integrityCheck: + stored === undefined ? "foreign-entry" : "entry-metadata", + }, ); if (entry.kind !== "file") throw new ArtifactReaderFailure( diff --git a/src/artifacts/ReleaseExposureReader.test.ts b/src/artifacts/ReleaseExposureReader.test.ts index 3e12b1be97..bdd045e107 100644 --- a/src/artifacts/ReleaseExposureReader.test.ts +++ b/src/artifacts/ReleaseExposureReader.test.ts @@ -26,6 +26,7 @@ import { PYTHON_39_MAGIC, } from "./pyinstaller/CArchive.fixture.js"; import { ArtifactResourceScope } from "./ArtifactResourceScope.js"; +import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import { asarHeaderBytes } from "../../tests/fixtures/asarHeader.js"; import { binaryPlistObjectTable } from "../../tests/fixtures/binaryPlistObjectTable.js"; import { javaClassFile } from "../../tests/fixtures/javaClassFile.js"; @@ -54,6 +55,7 @@ import { } from "../domain/releaseExposure.js"; import { HTML_INLINE_SCRIPT_LOCATION_LIMIT } from "../domain/javascript/htmlArtifactReferences.js"; import { ReleaseExposureReader } from "./ReleaseExposureReader.js"; +import { RegularFileChangedError } from "../filesystem/RegularFile.js"; import { AsarArtifactReader } from "./AsarArtifactReader.js"; import type { AsarHeaderAdmission } from "../config/asarHeaderAdmission.js"; @@ -788,9 +790,11 @@ describe("ReleaseExposureReader unpacked ASAR members", () => { ); if (result.ok) throw new Error("Expected a failed audit."); expect(result.error).toBeInstanceOf(AnalysisArtifactChangedError); - expect(result.error.message).toContain( - "ASAR member changed before interpretation: dist/notes.txt", - ); + expect(projectAnalysisError(result.error)).toMatchObject({ + code: "artifact_changed", + details: { integrity_check: "member-identity" }, + }); + expect(result.error.message).toContain("dist/notes.txt"); } finally { inventoryRead.impl = undefined; await reader.close(); @@ -5100,3 +5104,45 @@ it.each([ expect(scanned.debug_companions.paths).toEqual([]); }, ); + +it.each(["member", "selected artifact"] as const)( + "names which file changed while being read (%s)", + async (changed) => { + const root = await createTestTempDirectory( + "rea-release-exposure-read-changed-", + ); + const archive = join(root, "app.asar"); + await writeFile(archive, sourceMapArchive()); + const notes = join(root, "notes.txt"); + await writeFile(notes, "release notes\n"); + const real = stableRead.impl; + if (changed === "member") + stableRead.impl = async (...args) => { + if (args[0] === notes) throw new RegularFileChangedError(notes); + return real === undefined ? Promise.reject() : real(...args); + }; + else + inventoryRead.impl = () => + Promise.reject(new RegularFileChangedError(archive)); + const reader = new ReleaseExposureReader(); + try { + const result = await reader.inspect( + { path: changed === "member" ? root : archive }, + undefined, + ignoreText, + ); + if (result.ok) throw new Error("Expected a failed audit."); + expect(projectAnalysisError(result.error)).toMatchObject({ + code: "artifact_changed", + details: { + integrity_check: + changed === "member" ? "member-identity" : "container-identity", + }, + }); + } finally { + stableRead.impl = real; + inventoryRead.impl = undefined; + await reader.close(); + } + }, +); diff --git a/src/artifacts/ReleaseExposureReader.ts b/src/artifacts/ReleaseExposureReader.ts index 8e412eeb51..131bd9e94c 100644 --- a/src/artifacts/ReleaseExposureReader.ts +++ b/src/artifacts/ReleaseExposureReader.ts @@ -56,11 +56,11 @@ import { readStableArtifact } from "./readStableArtifact.js"; import { projectArtifactCloseFailure, projectStableArtifactFailure, + readerIntegrityFailure, } from "./StableArtifactFailure.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; import { AnalysisAccessDeniedError, - AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisInputError, AnalysisResourceConstraintError, @@ -79,7 +79,10 @@ import { import { inspectPeCodeViewFromBuffer } from "../domain/binaryTarget.js"; import { hasBinaryPlistSignature } from "../domain/apple/appleArchiveFormat.js"; import { logicalPathNfc } from "../domain/artifactIdentity.js"; -import type { ArtifactAdmissionLimit } from "../domain/artifactOperationError.js"; +import type { + ArtifactAdmissionLimit, + ArtifactIntegrityCheck, +} from "../domain/artifactOperationError.js"; import { observeMzWindowsHeader } from "../domain/dosMz.js"; import { evidenceSubjectFormatSchema } from "../domain/evidenceSubject.js"; import { byteOrderMarkEncoding } from "../domain/textByteOrderMark.js"; @@ -333,7 +336,8 @@ const scanFile = async ( asarHeaderAdmission: context.asarHeaderAdmission, }); } catch (cause) { - rethrowReadFailure(cause); + // This inventory rereads the selected artifact itself. + rethrowReadFailure(cause, "container-identity"); // A named admission owns its recovery; keep it typed as the directory scan does. if (cause instanceof ArtifactReaderFailure && cause.admission !== undefined) throw cause; @@ -2419,6 +2423,7 @@ const examinePdb = async ( throw new ArtifactReaderFailure( "integrity", `Member changed during acquisition: ${filePath}`, + { integrityCheck: "member-identity" }, ); readPdb(state, snapshot.bytes, filePath); } catch (cause) { @@ -2592,6 +2597,7 @@ const embeddedPackageFormat = async ( throw new ArtifactReaderFailure( "integrity", `Member changed during acquisition: ${filePath}`, + { integrityCheck: "member-identity" }, ); } return { kind: "absent" }; @@ -3059,7 +3065,9 @@ const readStreamBounded = async ( hash !== undefined && hash.digest("hex") !== expected.sha256 ) - throw new ArtifactReaderFailure("integrity", expected.changed); + throw new ArtifactReaderFailure("integrity", expected.changed, { + integrityCheck: "member-identity", + }); } catch (cause) { failure = cause; } @@ -3106,6 +3114,7 @@ const readSpan = async ( throw new ArtifactReaderFailure( "integrity", `Artifact changed before read: ${filePath}`, + { integrityCheck: "member-identity" }, ); if (offset + length > observed.size) return null; // Charge bytes as they arrive, so a read that fails after partial @@ -3126,6 +3135,7 @@ const readSpan = async ( throw new ArtifactReaderFailure( "integrity", `Artifact changed during read: ${filePath}`, + { integrityCheck: "member-identity" }, ); state.memberBytesRead += bytes.length - charged; return Buffer.from(bytes); @@ -3157,6 +3167,7 @@ const readDiskMember = async ( throw new ArtifactReaderFailure( "integrity", `Member changed during acquisition: ${filePath}`, + { integrityCheck: "member-identity" }, ); return { kind: "bytes", bytes: snapshot.bytes }; } catch (cause) { @@ -3177,17 +3188,30 @@ const readDiskMember = async ( } }; -const asReadFailure = (cause: unknown): unknown => +/** + * A file that changed while being read is a changed release member, unless the + * caller is reading the selected artifact itself. + */ +const asReadFailure = ( + cause: unknown, + integrityCheck: ArtifactIntegrityCheck = "member-identity", +): unknown => cause instanceof RegularFileChangedError - ? new ArtifactReaderFailure("integrity", cause.message, { cause }) + ? new ArtifactReaderFailure("integrity", cause.message, { + cause, + integrityCheck, + }) : cause; /** * A read that left cleanup unfinished is never a skipped member, whatever its * reason: only the error tells the caller a descriptor is still retained. */ -const rethrowReadFailure = (cause: unknown): void => { - const failure = asReadFailure(cause); +const rethrowReadFailure = ( + cause: unknown, + integrityCheck?: ArtifactIntegrityCheck, +): void => { + const failure = asReadFailure(cause, integrityCheck); if (failure instanceof AnalysisError) throw failure; if ( failure instanceof ArtifactReaderFailure && @@ -3625,9 +3649,7 @@ const releaseExposureFailurePrimary = ( cause instanceof ArtifactReaderFailure && cause.reason === "integrity" ) - return new AnalysisArtifactChangedError(OPERATION, path, cause.message, { - cause, - }); + return readerIntegrityFailure(OPERATION, path, cause); if ( origin === "owned-or-classified" && cause instanceof ArtifactReaderFailure && diff --git a/src/artifacts/SafeOutputTree.ts b/src/artifacts/SafeOutputTree.ts index 237b7e3181..fb86ad89e3 100644 --- a/src/artifacts/SafeOutputTree.ts +++ b/src/artifacts/SafeOutputTree.ts @@ -339,6 +339,7 @@ export class SafeOutputTree { throw new ArtifactReaderFailure( "integrity", `Extracted content exceeds the inventoried size: ${path}`, + { integrityCheck: "declared-size" }, ); bytes += chunk.length; hash.update(chunk); @@ -348,12 +349,14 @@ export class SafeOutputTree { throw new ArtifactReaderFailure( "integrity", `Extracted content size disagrees with inventory: ${path}`, + { integrityCheck: "declared-size" }, ); const sha256 = hash.digest("hex"); if (sha256 !== expected.sha256) throw new ArtifactReaderFailure( "integrity", `Extracted content disagrees with inventory: ${path}`, + { integrityCheck: "member-identity" }, ); await this.#assertLineage(lineage); await assertFilePathIdentity(destination, fileIdentity); @@ -375,6 +378,7 @@ export class SafeOutputTree { throw new ArtifactReaderFailure( "integrity", `Durable readback verification failed: ${path}`, + { integrityCheck: "output-readback" }, ); return { relativePath: path, sha256, bytesWritten: bytes }; } catch (cause: unknown) { @@ -517,6 +521,7 @@ export class SafeOutputTree { "integrity", `Output cleanup could not be verified${removalFailure === undefined ? "" : `: ${removalFailure instanceof Error ? removalFailure.message : String(removalFailure)}`}`, { + integrityCheck: "output-lifecycle", cause: removalFailure, cleanup: { reason: @@ -686,11 +691,13 @@ export class SafeOutputTree { throw new ArtifactReaderFailure( "integrity", "Extraction tree is already committed", + { integrityCheck: "output-lifecycle" }, ); if (this.#cleanup.status !== "not-required") throw new ArtifactReaderFailure( "integrity", "Extraction tree cleanup has already started", + { integrityCheck: "output-lifecycle" }, ); } diff --git a/src/artifacts/SafeOutputTreeReadback.ts b/src/artifacts/SafeOutputTreeReadback.ts index d524726399..7de73e7244 100644 --- a/src/artifacts/SafeOutputTreeReadback.ts +++ b/src/artifacts/SafeOutputTreeReadback.ts @@ -41,6 +41,7 @@ export const hashOutputFile = async ( throw new ArtifactReaderFailure( "integrity", "Readback exceeded the bytes written", + { integrityCheck: "output-readback" }, ); hash.update(chunk); } diff --git a/src/artifacts/StableArtifactFailure.ts b/src/artifacts/StableArtifactFailure.ts index ec4e18675f..1dfd12cb03 100644 --- a/src/artifacts/StableArtifactFailure.ts +++ b/src/artifacts/StableArtifactFailure.ts @@ -21,6 +21,23 @@ import { carriedReason, } from "../domain/analysisErrorCore.js"; +/** + * A reader's integrity failure as a selected-artifact change, keeping the + * check it named. `options` replaces the default cause (the failure itself), + * for example with a cleanup wrapper around it. + */ +export const readerIntegrityFailure = ( + operation: string, + path: string, + failure: ArtifactReaderFailure, + options: AnalysisErrorOptions = {}, +): AnalysisArtifactChangedError => + new AnalysisArtifactChangedError(operation, path, failure.message, { + cause: failure, + ...options, + integrityCheck: failure.integrityCheck, + }); + /** Preserve ownership classification for stable-file identity and cancellation. */ export const projectOwnedArtifactIdentityFailure = ( facts: ArtifactFilePrimaryFacts, @@ -34,9 +51,7 @@ export const projectOwnedArtifactIdentityFailure = ( ) return undefined; if (cause.reason === "integrity") - return new AnalysisArtifactChangedError(operation, path, cause.message, { - cause, - }); + return readerIntegrityFailure(operation, path, cause); if (cause.reason === "cancelled") return cancelledBy( operation, diff --git a/src/artifacts/ZipArtifactReader.ts b/src/artifacts/ZipArtifactReader.ts index 21d53890ed..291a66e12d 100644 --- a/src/artifacts/ZipArtifactReader.ts +++ b/src/artifacts/ZipArtifactReader.ts @@ -163,6 +163,7 @@ class NodeFileReader extends Reader { throw new ArtifactReaderFailure( "integrity", `ZIP source ended before its admitted extent: ${this.path}`, + { integrityCheck: "read-coverage" }, ); await this.verify(); return bytes; @@ -285,6 +286,7 @@ export class ZipArtifactReader implements ArtifactReader { throw new ArtifactReaderFailure( "integrity", `ZIP member identity changed during enumeration: ${entry.filename}`, + { integrityCheck: "entry-metadata" }, ); if (stored === undefined) this.#entries.set(metadata.adapterKey, { @@ -323,6 +325,10 @@ export class ZipArtifactReader implements ArtifactReader { new ArtifactReaderFailure( "integrity", "ZIP entry metadata does not match this reader's inventory", + { + integrityCheck: + stored === undefined ? "foreign-entry" : "entry-metadata", + }, ), ); const source = stored.source; diff --git a/src/artifacts/fit/FitStructure.ts b/src/artifacts/fit/FitStructure.ts index 355436cb44..23d05294ad 100644 --- a/src/artifacts/fit/FitStructure.ts +++ b/src/artifacts/fit/FitStructure.ts @@ -311,6 +311,7 @@ const imageHashes = ( throw new ArtifactReaderFailure( "integrity", `FIT image ${nodeName(image)} ${name} ${algo} value is ${String(value.bytes)} bytes; ${algo} values are ${String(expected)} bytes`, + { integrityCheck: "declared-digest" }, ); // Copy the value so the devicetree buffer can be released. hashes.push({ diff --git a/src/artifacts/inventory/classify.ts b/src/artifacts/inventory/classify.ts index 15bfa22513..6f17981291 100644 --- a/src/artifacts/inventory/classify.ts +++ b/src/artifacts/inventory/classify.ts @@ -106,6 +106,7 @@ export const classifyAndHashRootForInventory = async ( throw new ArtifactReaderFailure( "integrity", `Root artifact changed before inventory: ${path}`, + { integrityCheck: "container-identity" }, ); } if (directory && options.expectedRootSha256 !== undefined) @@ -113,6 +114,7 @@ export const classifyAndHashRootForInventory = async ( "integrity", `Artifact root changed after target admission: expected an admitted file at ${path}, observed a directory`, { + integrityCheck: "container-identity", userMessage: "The opened file was replaced by a directory. Select the intended artifact and reopen it before retrying.", }, @@ -143,6 +145,7 @@ export const classifyAndHashRootForInventory = async ( throw new ArtifactReaderFailure( "integrity", `Root artifact changed before inventory: ${path}`, + { integrityCheck: "container-identity" }, ); // Prior probe state can prove replacement without interpreting any bytes. const probes = new ArtifactEmbeddedFormatProbes( @@ -321,7 +324,7 @@ const classifyRootFormat = async ( throw new ArtifactReaderFailure( "integrity", `Root artifact changed during classification: ${path}`, - { cause: cause.cause ?? cause }, + { cause: cause.cause ?? cause, integrityCheck: "container-identity" }, ); throw artifactOperationCause(cause); } @@ -576,6 +579,7 @@ export const assertAdmittedRootDigest = ( "integrity", `Artifact root changed after target admission at ${path}: expected ${expected}, observed ${observed}`, { + integrityCheck: "container-identity", userMessage: "The artifact changed after it was opened. Reopen the selected artifact, then retry.", }, diff --git a/src/artifacts/inventory/scanReader.ts b/src/artifacts/inventory/scanReader.ts index 337149407b..270beaec7d 100644 --- a/src/artifacts/inventory/scanReader.ts +++ b/src/artifacts/inventory/scanReader.ts @@ -184,7 +184,7 @@ const containerContradiction = ( throw new ArtifactReaderFailure( "integrity", "Artifact integrity metadata disagrees with content: .", - undefined, + { integrityCheck: "declared-digest" }, artifactContainerIntegrityDetails(".", pair), ); return pair; @@ -421,7 +421,9 @@ const digestArtifactEntry = async ( const reconstruction = currentReader === context.reader ? context.reconstruction : undefined; if (reconstruction !== undefined && entry.byteOffset !== reconstruction.bytes) - throw new ArtifactReaderFailure("integrity", "Noncontiguous iNES regions"); + throw new ArtifactReaderFailure("integrity", "Noncontiguous iNES regions", { + integrityCheck: "reconstruction", + }); const digest = await hashReadable( await currentReader.open(entry, context.signal), context.signal, @@ -448,6 +450,7 @@ const digestArtifactEntry = async ( throw new ArtifactReaderFailure( "integrity", "The selected integrity digest was not computed", + { integrityCheck: "declared-digest" }, ); const mismatched = claim !== null && claim.digest !== observed; if (mismatched && claim !== null && observed !== undefined) { @@ -455,7 +458,7 @@ const digestArtifactEntry = async ( throw new ArtifactReaderFailure( "integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`, - undefined, + { integrityCheck: "declared-digest" }, artifactIntegrityDetails(logicalPath, claim, observed, entry.unpacked), ); context.pendingContradictions.push({ diff --git a/src/artifacts/javascript/JavaScriptArtifactFiles.ts b/src/artifacts/javascript/JavaScriptArtifactFiles.ts index 1b6bd8dc4e..60fca15961 100644 --- a/src/artifacts/javascript/JavaScriptArtifactFiles.ts +++ b/src/artifacts/javascript/JavaScriptArtifactFiles.ts @@ -124,6 +124,7 @@ export const readJavaScriptArtifactFiles = async ( throw new ArtifactReaderFailure( "integrity", "Root artifact node is missing", + { integrityCheck: "inventory-node" }, ); await verifyEntryBytes( await reader.openContainer(signal), @@ -253,6 +254,7 @@ const visitReader = async ( throw new ArtifactReaderFailure( "integrity", `Nested ASAR was not present in inventory: ${path}`, + { integrityCheck: "inventory-node" }, ); if (container.hash_status === "mismatched") continue; if (container.hash_status === "unavailable") continue; @@ -260,6 +262,7 @@ const visitReader = async ( throw new ArtifactReaderFailure( "integrity", `Nested ASAR was not integrity-verified: ${path}`, + { integrityCheck: "inventory-node" }, ); // Inventory expands an ASAR-named file only when its bytes are an // ASAR. One it recorded as ordinary bytes has no members to read. @@ -269,6 +272,7 @@ const visitReader = async ( throw new ArtifactReaderFailure( "integrity", `Verified nested ASAR has no inventory node: ${path}`, + { integrityCheck: "inventory-node" }, ); await verifyEntryBytes( await frame.reader.open(entry, context.signal), @@ -384,6 +388,7 @@ const readText = async ( throw new ArtifactReaderFailure( "integrity", `Artifact entry changed after inventory: ${input.expected.path}`, + { integrityCheck: "member-identity" }, ); context.textBytes += bytes.length; try { @@ -413,6 +418,7 @@ const verifyEntryBytes = async ( throw new ArtifactReaderFailure( "integrity", `Artifact entry changed after inventory: ${expected.path}`, + { integrityCheck: "member-identity" }, ); abortIfNeeded(signal); }; @@ -469,6 +475,7 @@ const expectedInventory = ( throw new ArtifactReaderFailure( "integrity", `Artifact inventory node is missing: ${occurrence.logical_path}`, + { integrityCheck: "inventory-node" }, ); // Inventory occurrences can have content identities for directories too. // Suffixes only describe file candidates; a directory such as @@ -668,6 +675,7 @@ const assertExpectedFilesWereVisited = ( throw new ArtifactReaderFailure( "integrity", `Relevant artifact entry disappeared after inventory: ${path}`, + { integrityCheck: "member-identity" }, ); }; diff --git a/src/artifacts/pyinstaller/PyInstallerBoundaries.test.ts b/src/artifacts/pyinstaller/PyInstallerBoundaries.test.ts index c807d3d294..7ff998e7b6 100644 --- a/src/artifacts/pyinstaller/PyInstallerBoundaries.test.ts +++ b/src/artifacts/pyinstaller/PyInstallerBoundaries.test.ts @@ -283,6 +283,27 @@ it("binds materialization to the inventoried digest and checks cached carrier fr }); }); +it("names whether an opened PyInstaller entry is foreign or differs from inventory", async () => { + const bytes = archive(Buffer.from("first")); + await withPyInstallerReader(bytes, async (reader) => { + await reader.prepareContainer(hash(bytes)); + const [entry] = await members(reader); + if (entry === undefined) throw new Error("Missing member"); + await expect( + reader.open({ ...entry, adapterKey: "not-inventoried" }), + ).rejects.toMatchObject({ + reason: "integrity", + integrityCheck: "foreign-entry", + }); + await expect( + reader.open({ ...entry, declaredSize: (entry.declaredSize ?? 0) + 1 }), + ).rejects.toMatchObject({ + reason: "integrity", + integrityCheck: "entry-metadata", + }); + }); +}); + it.each(["ENOENT", "ENOTDIR"] as const)( "retains changed-source evidence when an admitted carrier becomes unaddressable (%s)", async (code) => { diff --git a/src/artifacts/pyinstaller/PyInstallerMemberStream.ts b/src/artifacts/pyinstaller/PyInstallerMemberStream.ts index 865086e1fb..d2f82f6290 100644 --- a/src/artifacts/pyinstaller/PyInstallerMemberStream.ts +++ b/src/artifacts/pyinstaller/PyInstallerMemberStream.ts @@ -94,6 +94,7 @@ export const pyInstallerMemberStream = ( throw new ArtifactReaderFailure( "integrity", "Compressed PyInstaller member did not consume its complete declared source span", + { integrityCheck: "read-coverage" }, ); if ( options.expectedBytes !== undefined && @@ -102,6 +103,7 @@ export const pyInstallerMemberStream = ( throw new ArtifactReaderFailure( "integrity", "PyInstaller member size disagrees with its declaration or previous observation", + { integrityCheck: "declared-size" }, ); await options.complete?.(bytes); abortIfNeeded(options.signal); diff --git a/src/artifacts/pyinstaller/PyInstallerPyzStore.ts b/src/artifacts/pyinstaller/PyInstallerPyzStore.ts index 0ae63c443e..3a12653d36 100644 --- a/src/artifacts/pyinstaller/PyInstallerPyzStore.ts +++ b/src/artifacts/pyinstaller/PyInstallerPyzStore.ts @@ -312,6 +312,7 @@ export class PyInstallerPyzStore { throw new ArtifactReaderFailure( "integrity", "Private PYZ image changed after parsing", + { integrityCheck: "container-identity" }, ); } } diff --git a/src/browser/history/CaptureFailures.ts b/src/browser/history/CaptureFailures.ts index 1cb3b02ec7..770c1d8bca 100644 --- a/src/browser/history/CaptureFailures.ts +++ b/src/browser/history/CaptureFailures.ts @@ -7,7 +7,10 @@ import { type AnalysisCleanupLease, } from "../../artifacts/AnalysisCleanupLease.js"; import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js"; -import { stableArtifactInputRecovery } from "../../artifacts/StableArtifactFailure.js"; +import { + stableArtifactInputRecovery, + readerIntegrityFailure, +} from "../../artifacts/StableArtifactFailure.js"; import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js"; import { bindArtifactFileCleanup, @@ -18,7 +21,6 @@ import { import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { AnalysisAccessDeniedError, - AnalysisArtifactChangedError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, @@ -203,12 +205,7 @@ export const historicalCaptureFailure = ( cause instanceof ArtifactReaderFailure && cause.reason === "integrity" ) - return new AnalysisArtifactChangedError( - OPERATION, - sourcePath, - cause.message, - { cause }, - ); + return readerIntegrityFailure(OPERATION, sourcePath, cause); if ( origin === "owned-or-classified" && cause instanceof ArtifactReaderFailure && diff --git a/src/browser/history/playwrightTrace/TraceFailure.ts b/src/browser/history/playwrightTrace/TraceFailure.ts index a315dd702d..e0c9bf644d 100644 --- a/src/browser/history/playwrightTrace/TraceFailure.ts +++ b/src/browser/history/playwrightTrace/TraceFailure.ts @@ -1,7 +1,6 @@ import { AnalysisError } from "../../../domain/analysisErrorBase.js"; import { AnalysisAccessDeniedError, - AnalysisArtifactChangedError, AnalysisInputError, AnalysisResourceConstraintError, cancelledBy, @@ -12,7 +11,10 @@ import { PLAYWRIGHT_TRACE_OPERATION as operation } from "../../../domain/playwri import { ArtifactReaderFailure } from "../../../artifacts/ArtifactReader.js"; import { artifactFileCancellationCause } from "../../../artifacts/ArtifactFileOperation.js"; import { isSelectedRegularFileError } from "../../../filesystem/RegularFile.js"; -import { stableArtifactInputFailure } from "../../../artifacts/StableArtifactFailure.js"; +import { + stableArtifactInputFailure, + readerIntegrityFailure, +} from "../../../artifacts/StableArtifactFailure.js"; /** Classify the archive owner's facts without interpreting opaque cancellation reasons. */ export const traceFailure = (cause: unknown, path: string): AnalysisError => { @@ -24,9 +26,7 @@ export const traceFailure = (cause: unknown, path: string): AnalysisError => { carriedReason(artifactFileCancellationCause(cause)), ); if (cause.reason === "integrity") - return new AnalysisArtifactChangedError(operation, path, cause.message, { - cause, - }); + return readerIntegrityFailure(operation, path, cause); if (cause.reason === "limit") return new AnalysisResourceConstraintError( operation, diff --git a/src/captures/TsharkCaptureProvider.ts b/src/captures/TsharkCaptureProvider.ts index 99ff5d5538..088c24ca3d 100644 --- a/src/captures/TsharkCaptureProvider.ts +++ b/src/captures/TsharkCaptureProvider.ts @@ -1,3 +1,4 @@ +import { readerIntegrityFailure } from "../artifacts/StableArtifactFailure.js"; import { classifyProviderFailure, type ProviderFailureDialect, @@ -592,9 +593,7 @@ export class TsharkCaptureProvider implements PacketCapturePort { cause instanceof ArtifactReaderFailure && cause.reason === "integrity" ) - return new AnalysisArtifactChangedError(operation, path, reason, { - cause, - }); + return readerIntegrityFailure(operation, path, cause); return new AnalysisOutputError(operation, reason, { cause, ...(observedOutput === undefined diff --git a/src/domain/analysisErrorCore.ts b/src/domain/analysisErrorCore.ts index 1e9c54462a..111f783dc8 100644 --- a/src/domain/analysisErrorCore.ts +++ b/src/domain/analysisErrorCore.ts @@ -1,6 +1,7 @@ import type { JsonValue } from "./jsonValue.js"; import type { FixedAllowance } from "./fixedAllowanceRemediation.js"; import type { AmbiguousSelector } from "./analysisRefusal.js"; +import type { ArtifactIntegrityCheck } from "./artifactOperationError.js"; import { AnalysisError, type AnalysisErrorOptions, @@ -539,12 +540,17 @@ export class AnalysisAccessDeniedError extends AnalysisError { /** Selected artifact acquisition observed a change, so no stable identity can be reported. */ export class AnalysisArtifactChangedError extends AnalysisError { readonly _tag = "AnalysisArtifactChangedError"; + /** The consistency check the producing reader named, when it named one. */ + readonly integrityCheck: ArtifactIntegrityCheck | undefined; constructor( readonly operation: string, readonly path: string, readonly reason: string, - options?: AnalysisErrorOptions, + options?: AnalysisErrorOptions & { + readonly integrityCheck?: ArtifactIntegrityCheck | undefined; + }, ) { super(`Selected artifact changed during acquisition: ${reason}`, options); + this.integrityCheck = options?.integrityCheck; } } diff --git a/src/domain/analysisErrorProjection.test.ts b/src/domain/analysisErrorProjection.test.ts index 4eed513ce6..4d4193fe35 100644 --- a/src/domain/analysisErrorProjection.test.ts +++ b/src/domain/analysisErrorProjection.test.ts @@ -8,6 +8,7 @@ import { AnalysisCancelledError, AnalysisTimeoutError, AnalysisResourceConstraintError, + AnalysisArtifactChangedError, } from "./analysisErrorCore.js"; import { ArtifactOperationError } from "./artifactOperationError.js"; import { @@ -1852,6 +1853,21 @@ describe("analysis error projection: composed failures for a caller lifetime", ( ); }); + it("keeps the named integrity check when redaction rebuilds an artifact change", () => { + const error = new AnalysisArtifactChangedError( + "inspect_artifact", + "/target/secret-token.bin", + "member changed", + { integrityCheck: "member-identity" }, + ); + const redacted = redactExplicitFailure(error, ["secret-token"]); + expect(redacted).not.toBe(error); + expect(projectAnalysisError(redacted)).toMatchObject({ + code: "artifact_changed", + details: { integrity_check: "member-identity" }, + }); + }); + it("keeps continuing guidance through redaction and redacts its text", () => { const guidance = { userMessage: "The session for secret-token remains usable.", diff --git a/src/domain/analysisErrorProjection.ts b/src/domain/analysisErrorProjection.ts index 3bbeb77790..a00f2c5d27 100644 --- a/src/domain/analysisErrorProjection.ts +++ b/src/domain/analysisErrorProjection.ts @@ -748,6 +748,9 @@ const requestErrorDetails = ( path: error.path, reason: error.reason, boundary: "stable-artifact-read", + ...(error.integrityCheck === undefined + ? {} + : { integrity_check: error.integrityCheck }), }; if (error instanceof AnalysisAccessDeniedError) return { diff --git a/src/domain/artifactOperationError.ts b/src/domain/artifactOperationError.ts index 1fb8a330e5..093055114e 100644 --- a/src/domain/artifactOperationError.ts +++ b/src/domain/artifactOperationError.ts @@ -23,17 +23,33 @@ export interface ArtifactAdmissionLimit { * Which consistency check an `integrity` failure tripped, so consumers need * not read the message: a member the reader did not produce, member metadata * that differs from inventory, a container or unpacked file whose identity - * changed, short read coverage, bytes disagreeing with the declared size, or a - * read stream over a handle the reader does not own. + * changed, a directory or archive member whose file identity or bytes + * changed since inventory, short read coverage, bytes disagreeing with the + * declared size, a disk image whose stored checksum does not verify, a read + * stream over a handle the reader does not own, a format-declared digest or + * checksum that disagrees with content or cannot be checked, layout sources + * (structural index, tool listing, region table) that are malformed, disagree + * or place an entry outside the artifact, entries that do not reassemble into + * the source, an inventory node or verified state a later read relies on + * that is missing, output bytes that do not read back as written, or an + * output tree used after commit or whose cleanup could not be verified. */ export type ArtifactIntegrityCheck = | "foreign-entry" | "entry-metadata" | "container-identity" | "unpacked-entry-identity" + | "member-identity" + | "image-checksum" | "read-coverage" | "declared-size" - | "reader-ownership"; + | "reader-ownership" + | "declared-digest" + | "layout-consistency" + | "reconstruction" + | "inventory-node" + | "output-readback" + | "output-lifecycle"; /** Artifact inventory or extraction failed a typed safety boundary. */ export class ArtifactOperationError extends AnalysisError { diff --git a/src/domain/comparisonEvidenceResult.test.ts b/src/domain/comparisonEvidenceResult.test.ts index 7976cb7cb1..30e0effa76 100644 --- a/src/domain/comparisonEvidenceResult.test.ts +++ b/src/domain/comparisonEvidenceResult.test.ts @@ -106,3 +106,12 @@ describe("same-evidence comparison admission", () => { ).toBe(false); }); }); + +it("locates a comparison payload failure within its Evidence record", () => { + const parsed = readComparisonResult( + evidence({ ...baseline(), status: "changed" }), + "compare_functions", + ); + if (parsed.ok) throw new Error("Expected a status contradiction"); + expect(parsed.error.issuePath).toEqual(["normalized_result", "status"]); +}); diff --git a/src/domain/comparisonEvidenceResult.ts b/src/domain/comparisonEvidenceResult.ts index a671156482..5ad2456870 100644 --- a/src/domain/comparisonEvidenceResult.ts +++ b/src/domain/comparisonEvidenceResult.ts @@ -49,6 +49,7 @@ export function readComparisonResult( const parsed = readEvidencePayload( processCaptureComparisonSchema, evidence.normalized_result, + { within: ["normalized_result"] }, ); if (!parsed.ok) return parsed; return ok({ operation, evidence, result: parsed.value }); @@ -57,6 +58,7 @@ export function readComparisonResult( const parsed = readEvidencePayload( functionComparisonResultSchema, evidence.normalized_result, + { within: ["normalized_result"] }, ); if (!parsed.ok) return parsed; if (parsed.value.function_match.method === "same-evidence") { @@ -102,6 +104,7 @@ export function readComparisonResult( const parsed = readEvidencePayload( artifactComparisonResultSchema, evidence.normalized_result, + { within: ["normalized_result"] }, ); if (!parsed.ok) return parsed; const links = validateFindingLinks(evidence, [ diff --git a/src/domain/comparisonSourceEvidence.ts b/src/domain/comparisonSourceEvidence.ts index 825d2873f8..fe4650ec2b 100644 --- a/src/domain/comparisonSourceEvidence.ts +++ b/src/domain/comparisonSourceEvidence.ts @@ -18,7 +18,13 @@ const sideParametersSchema = z.object({ export const comparisonSourceEvidenceSides = ( evidence: Evidence, ): { left: string[]; right: string[] } => { - const parsed = readEvidencePayload(sideParametersSchema, evidence.parameters); + const parsed = readEvidencePayload( + sideParametersSchema, + evidence.parameters, + { + within: ["parameters"], + }, + ); if (!parsed.ok) throw parsed.error; const parameters = parsed.value; if ( diff --git a/src/domain/explicitSensitiveFailure.ts b/src/domain/explicitSensitiveFailure.ts index 1843935d3f..d666e6eaac 100644 --- a/src/domain/explicitSensitiveFailure.ts +++ b/src/domain/explicitSensitiveFailure.ts @@ -259,7 +259,7 @@ const redactFailure = ( error.operation, text(error.path), text(error.reason), - context, + { ...context, integrityCheck: error.integrityCheck }, ); if (error instanceof AnalysisInputError) return new AnalysisInputError( diff --git a/src/domain/managed/managedInspectionEvidence.ts b/src/domain/managed/managedInspectionEvidence.ts index 926e8aa421..9832b2ba8b 100644 --- a/src/domain/managed/managedInspectionEvidence.ts +++ b/src/domain/managed/managedInspectionEvidence.ts @@ -53,7 +53,9 @@ export const readManagedInspectionEvidence = < ]), ); } - const payload = readEvidencePayload(schema, evidence.normalized_result); + const payload = readEvidencePayload(schema, evidence.normalized_result, { + within: ["normalized_result"], + }); if (!payload.ok) return payload; const result = payload.value; const artifactSha256 = result.artifact.sha256; diff --git a/src/domain/managed/managedNativeVerificationSource.ts b/src/domain/managed/managedNativeVerificationSource.ts index f8e15c3ce5..bd0747794c 100644 --- a/src/domain/managed/managedNativeVerificationSource.ts +++ b/src/domain/managed/managedNativeVerificationSource.ts @@ -73,6 +73,7 @@ const readNativeObservation = ( const payload = readEvidencePayload( inspectMachoSchema, evidence.normalized_result, + { within: ["normalized_result"] }, ); if (!payload.ok) return payload; return ok({ @@ -98,6 +99,7 @@ const readNativeObservation = ( const payload = readEvidencePayload( functionDossierSchema, evidence.normalized_result, + { within: ["normalized_result"] }, ); if (!payload.ok) return payload; return ok({ diff --git a/src/domain/reconstructionVerification.ts b/src/domain/reconstructionVerification.ts index 6833adc419..ff8c0e4d6b 100644 --- a/src/domain/reconstructionVerification.ts +++ b/src/domain/reconstructionVerification.ts @@ -329,6 +329,7 @@ const readValidatedSourceFacts = ( const capture = readEvidencePayload( processCaptureSchema, source.normalized_result, + { within: ["normalized_result"] }, ); if (!capture.ok) throw capture.error; processSources.push({ @@ -339,6 +340,7 @@ const readValidatedSourceFacts = ( const parsedDossier = readEvidencePayload( functionDossierSchema, source.normalized_result, + { within: ["normalized_result"] }, ); if (!parsedDossier.ok) throw parsedDossier.error; const dossier = parsedDossier.value; diff --git a/src/ghidra/GhidraProvider.behavior.test.ts b/src/ghidra/GhidraProvider.behavior.test.ts index 941adc05a6..07e8782150 100644 --- a/src/ghidra/GhidraProvider.behavior.test.ts +++ b/src/ghidra/GhidraProvider.behavior.test.ts @@ -5031,7 +5031,7 @@ describe("Ghidra missing project program", () => { }); describe("Ghidra changed project", () => { - const launchFailure = async (cause: unknown) => { + const launchFailure = async (cause: unknown, viaLauncher = true) => { const root = await mkdtemp(join(tmpdir(), "rea-changed-project-")); onTestFinished(async () => { await rm(root, { recursive: true, force: true }); @@ -5043,9 +5043,9 @@ describe("Ghidra changed project", () => { "Ghidra headless launch failed", { failure_kind: "start" }, { - cause: new GhidraLaunchError("Ghidra headless launch failed", { - cause, - }), + cause: viaLauncher + ? new GhidraLaunchError("Ghidra headless launch failed", { cause }) + : cause, }, ); const ghidra = provider( @@ -5100,6 +5100,28 @@ describe("Ghidra changed project", () => { expect(error.cause).toBe(physical); }); + it.each([true, false])( + "keeps the integrity check a changed artifact named (via launcher: %s)", + async (viaLauncher) => { + const { projected } = await launchFailure( + new AnalysisArtifactChangedError( + "open_binary", + "/projects/selected", + GHIDRA_PROJECT_PROFILE_MISMATCH, + { integrityCheck: "container-identity" }, + ), + viaLauncher, + ); + expect(projected).toMatchObject({ + code: "artifact_changed", + details: { + operation: "list_documents", + integrity_check: "container-identity", + }, + }); + }, + ); + it("keeps the generic start failure for other launch failures", async () => { const { projected } = await launchFailure(new Error("spawn failed")); expect(projected.code).toBe("execution_failure"); diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.ts index 89e8b123a5..403f27e46b 100644 --- a/src/ghidra/GhidraProviderClient.ts +++ b/src/ghidra/GhidraProviderClient.ts @@ -1412,7 +1412,7 @@ const projectPrimarySessionError = ( operation, physicalCause.path, physicalCause.reason, - context, + { ...context, integrityCheck: physicalCause.integrityCheck }, ); if ( failure.kind === "admission" && diff --git a/src/gpu/GpuCodeObjectsProvider.ts b/src/gpu/GpuCodeObjectsProvider.ts index e1f44127a7..03d1b2e4b8 100644 --- a/src/gpu/GpuCodeObjectsProvider.ts +++ b/src/gpu/GpuCodeObjectsProvider.ts @@ -1,3 +1,4 @@ +import { readerIntegrityFailure } from "../artifacts/StableArtifactFailure.js"; import { GPU_CODE_OBJECTS_PROVIDER_IDENTITY } from "./GpuCodeObjectsProviderIdentity.js"; import { lstat, type FileHandle } from "node:fs/promises"; import type { GpuCodeObjectsPort } from "../application/gpu/GpuCodeObjectsPort.js"; @@ -145,12 +146,9 @@ export class GpuCodeObjectsProvider implements GpuCodeObjectsPort { primary instanceof ArtifactReaderFailure && primary.reason === "integrity" ) - error = new AnalysisArtifactChangedError( - OPERATION, - input.path, - primary.message, - { cause }, - ); + error = readerIntegrityFailure(OPERATION, input.path, primary, { + cause, + }); else if ( primary instanceof Error && "code" in primary && diff --git a/src/model/ModelArtifactProvider.ts b/src/model/ModelArtifactProvider.ts index 425a9c5354..2eb0047f9f 100644 --- a/src/model/ModelArtifactProvider.ts +++ b/src/model/ModelArtifactProvider.ts @@ -1,3 +1,4 @@ +import { readerIntegrityFailure } from "../artifacts/StableArtifactFailure.js"; import { MODEL_ARTIFACT_PROVIDER_IDENTITY } from "./ModelArtifactProviderIdentity.js"; import { lstat, type FileHandle } from "node:fs/promises"; import type { ModelArtifactPort } from "../application/model/ModelArtifactPort.js"; @@ -17,7 +18,6 @@ import { } from "../domain/model/modelArtifact.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; import { - AnalysisArtifactChangedError, AnalysisAccessDeniedError, AnalysisResourceConstraintError, cancelledBy, @@ -149,12 +149,9 @@ export class ModelArtifactProvider implements ModelArtifactPort { primary instanceof ArtifactReaderFailure && primary.reason === "integrity" ) - error = new AnalysisArtifactChangedError( - OPERATION, - input.path, - primary.message, - { cause }, - ); + error = readerIntegrityFailure(OPERATION, input.path, primary, { + cause, + }); else if ( primary instanceof Error && "code" in primary && diff --git a/src/native/AppleDispatchMetadata.ts b/src/native/AppleDispatchMetadata.ts index 92f78a31f2..11775ab5a2 100644 --- a/src/native/AppleDispatchMetadata.ts +++ b/src/native/AppleDispatchMetadata.ts @@ -1,4 +1,5 @@ import { decodeStrictUtf8 } from "../domain/strictUtf8.js"; +import { readerIntegrityFailure } from "../artifacts/StableArtifactFailure.js"; import { malformedInput, parseFailureFromCause, @@ -524,9 +525,7 @@ const appleDispatchMetadataPrimaryFailure = ( { cause }, ); if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity") - return new AnalysisArtifactChangedError(OPERATION, path, cause.message, { - cause, - }); + return readerIntegrityFailure(OPERATION, path, cause); if (cause instanceof ArtifactReaderFailure && cause.reason === "path") return new AnalysisArtifactChangedError(OPERATION, path, cause.message, { cause, diff --git a/src/native/NativeMacOSProvider.ts b/src/native/NativeMacOSProvider.ts index 6eafe092b1..4c69d9bd97 100644 --- a/src/native/NativeMacOSProvider.ts +++ b/src/native/NativeMacOSProvider.ts @@ -1,3 +1,4 @@ +import { readerIntegrityFailure } from "../artifacts/StableArtifactFailure.js"; import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js"; import { withArtifactTargetIdentity } from "../artifacts/withArtifactTargetIdentity.js"; import { @@ -74,7 +75,6 @@ import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js" import type { EvidenceLocation } from "../domain/evidence.js"; import { AnalysisCancelledError, - AnalysisArtifactChangedError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, @@ -1800,12 +1800,7 @@ const nativeMachoSourcePrimary = ( if (cause instanceof ArtifactReaderFailure && cause.reason === "format") return new AnalysisOutputError(operation, cause.message, options); if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity") - return new AnalysisArtifactChangedError( - operation, - path, - cause.message, - options, - ); + return readerIntegrityFailure(operation, path, cause, options); return new ProviderAdapterError(IDENTITY.id, operation, { ...options, userMessage: "The selected Mach-O source could not be read safely.", diff --git a/src/native/NativePlistSource.ts b/src/native/NativePlistSource.ts index d76efc68a7..6a131d851a 100644 --- a/src/native/NativePlistSource.ts +++ b/src/native/NativePlistSource.ts @@ -1,3 +1,4 @@ +import { readerIntegrityFailure } from "../artifacts/StableArtifactFailure.js"; import { absoluteCallerPath } from "../filesystem/callerPath.js"; import { readFileHandleRange } from "../filesystem/readFileHandleRange.js"; import { stat } from "node:fs/promises"; @@ -12,7 +13,6 @@ import type { AnalysisErrorOptions, } from "../domain/analysisErrorBase.js"; import { - AnalysisArtifactChangedError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisResourceConstraintError, @@ -206,12 +206,7 @@ const nativePlistPrimaryFailure = ( cause instanceof ArtifactReaderFailure && cause.reason === "integrity" ) - return new AnalysisArtifactChangedError( - "inspect_plist", - selection.path, - cause.message, - { cause }, - ); + return readerIntegrityFailure("inspect_plist", selection.path, cause); if (cause instanceof ArtifactReaderFailure && cause.reason === "limit") { const resource = cause.boundary ?? "memory"; return resource === "file-size" diff --git a/src/native/pe/PeBinaryFailure.ts b/src/native/pe/PeBinaryFailure.ts index 58e2268de1..22dab2236d 100644 --- a/src/native/pe/PeBinaryFailure.ts +++ b/src/native/pe/PeBinaryFailure.ts @@ -3,6 +3,7 @@ import { projectSelectedArtifactFileFailure, stableArtifactInputFailure, projectStableArtifactFailure, + readerIntegrityFailure, } from "../../artifacts/StableArtifactFailure.js"; import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js"; import type { StableArtifactSnapshot } from "../../artifacts/readStableArtifact.js"; @@ -13,7 +14,6 @@ import { } from "../../artifacts/ArtifactFileOperation.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import { - AnalysisArtifactChangedError, AnalysisResourceConstraintError, type ResourceConstraintRecovery, cancelledBy, @@ -48,12 +48,7 @@ const peBinaryFailurePrimary = ( cause instanceof ArtifactReaderFailure && cause.reason === "integrity" ) - return new AnalysisArtifactChangedError( - operation, - input.path, - cause.message, - { cause }, - ); + return readerIntegrityFailure(operation, input.path, cause); if ( origin === "owned-or-classified" && cause instanceof ArtifactReaderFailure && diff --git a/src/providers/AnalysisClientFailure.test.ts b/src/providers/AnalysisClientFailure.test.ts index bb6f5f33d6..f7e1eb7a3f 100644 --- a/src/providers/AnalysisClientFailure.test.ts +++ b/src/providers/AnalysisClientFailure.test.ts @@ -7,6 +7,7 @@ import { AnalysisOutputError, AnalysisTimeoutError, AnalysisResourceConstraintError, + AnalysisArtifactChangedError, } from "../domain/analysisErrorCore.js"; import { analysisSettingLimit } from "../domain/analysisSettingDefinitions.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; @@ -213,3 +214,20 @@ it.each([ 2, ); }); + +it("keeps the named integrity check when an artifact change changes operation", () => { + const attributed = analysisClientFailureForOperation( + new AnalysisArtifactChangedError( + "inspect_artifact", + "/target.app", + "member changed", + { integrityCheck: "member-identity" }, + ), + "ghidra", + "binary_overview", + ); + expect(projectAnalysisError(attributed)).toMatchObject({ + code: "artifact_changed", + details: { integrity_check: "member-identity" }, + }); +}); diff --git a/src/providers/AnalysisClientFailure.ts b/src/providers/AnalysisClientFailure.ts index 5e1036cf08..c539155a59 100644 --- a/src/providers/AnalysisClientFailure.ts +++ b/src/providers/AnalysisClientFailure.ts @@ -256,7 +256,7 @@ export const analysisClientFailureForOperation = ( operation, cause.path, cause.reason, - context, + { ...context, integrityCheck: cause.integrityCheck }, ); else if (cause instanceof AnalysisResourceConstraintError) result = reattributedResourceConstraint(operation, cause, context); diff --git a/src/providers/classifyProviderFailure.ts b/src/providers/classifyProviderFailure.ts index 12df08f507..190d27869a 100644 --- a/src/providers/classifyProviderFailure.ts +++ b/src/providers/classifyProviderFailure.ts @@ -13,6 +13,7 @@ import { projectSelectedArtifactFileFailure, stableArtifactInputFailure, type RequestField, + readerIntegrityFailure, } from "../artifacts/StableArtifactFailure.js"; import { completedStableArtifactObservation } from "../artifacts/StableArtifactObservation.js"; import { @@ -21,11 +22,7 @@ import { type AnalysisErrorOptions, } from "../domain/analysisErrorBase.js"; import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; -import { - AnalysisArtifactChangedError, - cancelledBy, - carriedReason, -} from "../domain/analysisErrorCore.js"; +import { cancelledBy, carriedReason } from "../domain/analysisErrorCore.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { classifyProviderOutcome, @@ -220,12 +217,10 @@ const fileFailure = ( } if (file === undefined) return undefined; if (physical.reason === "integrity") - return new AnalysisArtifactChangedError( - operation, - file.path, - physical.message, - { ...details, cause }, - ); + return readerIntegrityFailure(operation, file.path, physical, { + ...details, + cause, + }); if (physical.reason === "limit" && physical.boundary === "file-size") return file.fileSize?.(physical, { ...details, cause }); if (physical.reason === "path" || physical.reason === "format") diff --git a/src/rust/RustBinaryProvider.ts b/src/rust/RustBinaryProvider.ts index 4e54e1d1b9..183b6108eb 100644 --- a/src/rust/RustBinaryProvider.ts +++ b/src/rust/RustBinaryProvider.ts @@ -4,6 +4,7 @@ import { projectStableArtifactFailure, stableArtifactInputFailure, projectArtifactCloseFailure, + readerIntegrityFailure, } from "../artifacts/StableArtifactFailure.js"; import { type StableArtifactSnapshot, @@ -21,7 +22,6 @@ import type { ExecutionOptions } from "../application/AnalysisProvider.js"; import type { RustBinaryPort } from "../application/rust/RustBinaryPort.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; import { - AnalysisArtifactChangedError, AnalysisOutputError, AnalysisResourceConstraintError, cancelledBy, @@ -404,9 +404,7 @@ const artifactReaderFailure = ( limits: RustProducerLimits, ): AnalysisError => { if (cause.reason === "integrity") - return new AnalysisArtifactChangedError(OPERATION, path, cause.message, { - cause, - }); + return readerIntegrityFailure(OPERATION, path, cause); if (cause.reason === "cancelled") return cancelledBy( OPERATION, diff --git a/src/sqlite/SqliteDatabaseFailures.ts b/src/sqlite/SqliteDatabaseFailures.ts index c8379141a5..44fd52b1d8 100644 --- a/src/sqlite/SqliteDatabaseFailures.ts +++ b/src/sqlite/SqliteDatabaseFailures.ts @@ -1,6 +1,9 @@ import { MAX_NODE_TIMER_DELAY_MS } from "../domain/analysisResourceLimits.js"; import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; -import { stableArtifactInputFailure } from "../artifacts/StableArtifactFailure.js"; +import { + stableArtifactInputFailure, + readerIntegrityFailure, +} from "../artifacts/StableArtifactFailure.js"; import { ArtifactFileCleanupFailure, bindArtifactFileCleanup, @@ -18,7 +21,6 @@ import { import type { JsonValue } from "../domain/jsonValue.js"; import { AnalysisAccessDeniedError, - AnalysisArtifactChangedError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, @@ -164,9 +166,7 @@ export const sqliteDatabaseFailure = ( workerTimeoutMs, ); if (cause.reason === "integrity") - return new AnalysisArtifactChangedError(operation, path, cause.message, { - cause, - }); + return readerIntegrityFailure(operation, path, cause); if (cause.reason === "cancelled") return cancelledBy( operation, diff --git a/src/sqlite/SqliteDatabaseSnapshot.ts b/src/sqlite/SqliteDatabaseSnapshot.ts index b36763829a..25eee1f738 100644 --- a/src/sqlite/SqliteDatabaseSnapshot.ts +++ b/src/sqlite/SqliteDatabaseSnapshot.ts @@ -79,7 +79,7 @@ const optionalSidecarStat = async ( throw new ArtifactReaderFailure( "integrity", `SQLite snapshot file set changed before sidecar inspection: ${databasePath}`, - { cause }, + { cause, integrityCheck: "container-identity" }, ); const remedy = "Use the application's supported consistent offline export or copy workflow to move the complete known database file set to a shorter path. Do not rename a live database or omit its WAL or journal."; @@ -139,13 +139,14 @@ const duringAcquisition = async ( throw new ArtifactReaderFailure( "integrity", `SQLite snapshot file set changed during acquisition: ${path}`, - { cause }, + { cause, integrityCheck: "container-identity" }, ); if (cause instanceof ArtifactReaderFailure && cause.reason === "limit") { const changed = new ArtifactReaderFailure( "integrity", `SQLite snapshot file set exceeded its observed size during acquisition: ${path}`, { + integrityCheck: "container-identity", cause, ...(cause.partialObservation === undefined ? {} @@ -196,6 +197,7 @@ const readObservedArtifact = ( throw new ArtifactReaderFailure( "integrity", `SQLite snapshot file set changed during acquisition: ${selectedPath}`, + { integrityCheck: "container-identity" }, ); return current; }, @@ -234,6 +236,7 @@ const verifyInactiveJournal = async ( throw new ArtifactReaderFailure( "integrity", `SQLite journal changed before open: ${path}`, + { integrityCheck: "container-identity" }, ); // TRUNCATE commits leave an empty file; PERSIST commits zero the complete // 28-byte fixed header. A new active journal may zero only its magic bytes. @@ -256,6 +259,7 @@ const verifyInactiveJournal = async ( throw new ArtifactReaderFailure( "integrity", `SQLite journal changed during inspection: ${path}`, + { integrityCheck: "container-identity" }, ); if ( before.size !== 0n && @@ -266,6 +270,9 @@ const verifyInactiveJournal = async ( phase === "initial" ? `Rollback journal may require recovery: ${path}. Supply a clean offline snapshot; only empty journals or a fully zeroed header are supported.` : `Rollback journal became active or malformed during database acquisition: ${path}`, + phase === "initial" + ? undefined + : { integrityCheck: "container-identity" }, ); }, ); @@ -426,6 +433,7 @@ export const captureSqliteDatabaseSnapshot = async ( throw new ArtifactReaderFailure( "integrity", `SQLite snapshot file set changed during acquisition: ${paths[index] ?? path}`, + { integrityCheck: "container-identity" }, ); assertArtifactReadActive(signal); return { snapshotPath, artifact, wal: walArtifact }; diff --git a/tests/boundary/filesystem/artifactAdmittedIdentity.test.ts b/tests/boundary/filesystem/artifactAdmittedIdentity.test.ts index f1160d2447..c4713753f8 100644 --- a/tests/boundary/filesystem/artifactAdmittedIdentity.test.ts +++ b/tests/boundary/filesystem/artifactAdmittedIdentity.test.ts @@ -170,7 +170,7 @@ it.each([ ok: false, error: { reason: "integrity", - detail: expect.stringContaining("changed after target admission"), + integrityCheck: "container-identity", }, }); await expect(access(output)).rejects.toMatchObject({ code: "ENOENT" }); @@ -349,7 +349,7 @@ it("checks embedded native packs before acceptance while preserving unsupported ok: false, error: { reason: "integrity", - detail: expect.stringContaining("changed after target admission"), + integrityCheck: "container-identity", }, }); await expect(access(output)).rejects.toMatchObject({ code: "ENOENT" }); diff --git a/tests/boundary/filesystem/artifactInventoryRegularRoot.test.ts b/tests/boundary/filesystem/artifactInventoryRegularRoot.test.ts index c0765966e3..7d2abdeab7 100644 --- a/tests/boundary/filesystem/artifactInventoryRegularRoot.test.ts +++ b/tests/boundary/filesystem/artifactInventoryRegularRoot.test.ts @@ -82,7 +82,7 @@ it("rejects a root path replaced between its initial stat and open", async () => classifyAndHashRoot(path, false, expectedMetadata), ).rejects.toMatchObject({ reason: "integrity", - message: `Root artifact changed before inventory: ${path}`, + integrityCheck: "container-identity", }); }); diff --git a/tests/boundary/filesystem/artifactZipIntegrity.test.ts b/tests/boundary/filesystem/artifactZipIntegrity.test.ts index 0437543118..5148d7ec3b 100644 --- a/tests/boundary/filesystem/artifactZipIntegrity.test.ts +++ b/tests/boundary/filesystem/artifactZipIntegrity.test.ts @@ -434,15 +434,25 @@ it("binds ZIP opens to the emitted entry metadata", async () => { if (first === undefined || second === undefined) throw new Error("Expected both ZIP entries"); + const changedMetadata = { + reason: "integrity", + integrityCheck: "entry-metadata", + }; + await expect( + reader.open({ ...second, adapterKey: "not-inventoried" }), + ).rejects.toMatchObject({ + reason: "integrity", + integrityCheck: "foreign-entry", + }); await expect( reader.open({ ...second, adapterKey: first.adapterKey }), - ).rejects.toMatchObject({ reason: "integrity" }); + ).rejects.toMatchObject(changedMetadata); await expect( reader.open({ ...second, path: first.path }), - ).rejects.toMatchObject({ reason: "integrity" }); + ).rejects.toMatchObject(changedMetadata); await expect( reader.open({ ...second, declaredSize: first.declaredSize }), - ).rejects.toMatchObject({ reason: "integrity" }); + ).rejects.toMatchObject(changedMetadata); await expect( reader.open({ ...second, @@ -455,12 +465,10 @@ it("binds ZIP opens to the emitted entry metadata", async () => { ctimeNs: 6n, }, }), - ).rejects.toMatchObject({ reason: "integrity" }); + ).rejects.toMatchObject(changedMetadata); const originalKey = second.adapterKey; Reflect.set(second, "adapterKey", first.adapterKey); - await expect(reader.open(second)).rejects.toMatchObject({ - reason: "integrity", - }); + await expect(reader.open(second)).rejects.toMatchObject(changedMetadata); Reflect.set(second, "adapterKey", originalKey); const stream = await reader.open({ ...second }); diff --git a/tests/boundary/filesystem/directoryArtifactReaderOpen.test.ts b/tests/boundary/filesystem/directoryArtifactReaderOpen.test.ts index 554f23fbde..1f8c67b785 100644 --- a/tests/boundary/filesystem/directoryArtifactReaderOpen.test.ts +++ b/tests/boundary/filesystem/directoryArtifactReaderOpen.test.ts @@ -87,7 +87,7 @@ describe("DirectoryArtifactReader.open", () => { expect(after.ino).toBe(before.ino); await expect(reader.open(entry)).rejects.toMatchObject({ reason: "integrity", - message: expect.stringContaining("changed before open"), + integrityCheck: "member-identity", }); } finally { await reader.close(); @@ -129,7 +129,7 @@ describe("DirectoryArtifactReader.open", () => { } expect(failure).toMatchObject({ reason: "integrity", - message: expect.stringContaining("changed during read"), + integrityCheck: "member-identity", }); expect(observedBytes).toBeLessThanOrEqual(originalBytes + 1); } finally { @@ -172,6 +172,7 @@ describe("DirectoryArtifactReader input identity", () => { const { sourceIdentity: _identity, ...entry } = await sampleEntry(reader); await expect(reader.open(entry)).rejects.toMatchObject({ reason: "integrity", + integrityCheck: "entry-metadata", }); } finally { await reader.close(); diff --git a/tests/boundary/filesystem/inesArtifact.test.ts b/tests/boundary/filesystem/inesArtifact.test.ts index f89d5364e2..efe9accf11 100644 --- a/tests/boundary/filesystem/inesArtifact.test.ts +++ b/tests/boundary/filesystem/inesArtifact.test.ts @@ -102,7 +102,7 @@ it("rejects region bytes that disagree with stable whole-file hashes", async () try { await expect(inventoryArtifact(path)).rejects.toMatchObject({ reason: "integrity", - message: "iNES reconstruction differs from the source", + integrityCheck: "reconstruction", }); expect(changed).toBe(true); expect((await readFile(path)).equals(bytes)).toBe(true); diff --git a/tests/boundary/filesystem/javascriptIntegrityPolicy.test.ts b/tests/boundary/filesystem/javascriptIntegrityPolicy.test.ts index 1ca066b7ed..410748f095 100644 --- a/tests/boundary/filesystem/javascriptIntegrityPolicy.test.ts +++ b/tests/boundary/filesystem/javascriptIntegrityPolicy.test.ts @@ -185,7 +185,7 @@ it("rejects a nested ASAR introduced after inventory as artifact drift", async ( readJavaScriptArtifactFiles(reader, snapshot), ).rejects.toMatchObject({ reason: "integrity", - message: "Nested ASAR was not present in inventory: new.asar", + integrityCheck: "inventory-node", }); } finally { await reader.close(); diff --git a/tests/boundary/providers/native/artifactProvider.machOSlices.test.ts b/tests/boundary/providers/native/artifactProvider.machOSlices.test.ts index 87f89d2a60..0d81d60c73 100644 --- a/tests/boundary/providers/native/artifactProvider.machOSlices.test.ts +++ b/tests/boundary/providers/native/artifactProvider.machOSlices.test.ts @@ -190,7 +190,10 @@ describe("artifact Mach-O slice integrity", () => { for await (const _entry of reader.entries()) { // Malformed structural facts must fail before any slice is yielded. } - }).rejects.toThrow(/structural slice index is malformed/u); + }).rejects.toMatchObject({ + reason: "integrity", + integrityCheck: "layout-consistency", + }); }); // #4280: record-and-continue keeps going with REA's FAT parse as the authority. diff --git a/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts b/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts index 5df143ea40..061508ab86 100644 --- a/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts +++ b/tests/boundary/providers/native/nativeDmgArtifactReader.test.ts @@ -1748,6 +1748,7 @@ describe("native DMG real verification diagnostics", () => { expect(failure).toBeInstanceOf(ArtifactReaderFailure); if (!(failure instanceof ArtifactReaderFailure)) return; expect(failure.reason).toBe("integrity"); + expect(failure.integrityCheck).toBe("image-checksum"); expect(failure.message).toContain('"command":"/usr/bin/hdiutil"'); expect(failure.message).toContain('"arguments":["verify"'); expect(failure.message).toContain('"exitCode":1');