diff --git a/src/application/environment/environmentBundleWrite.test.ts b/src/application/environment/environmentBundleWrite.test.ts index b8841955de..9d73b65e15 100644 --- a/src/application/environment/environmentBundleWrite.test.ts +++ b/src/application/environment/environmentBundleWrite.test.ts @@ -480,6 +480,7 @@ it.each([ new ArtifactReaderFailure( "integrity", "Extracted content disagrees with inventory", + { integrityCheck: "container-identity" }, ), }, ] as const)( diff --git a/src/artifacts/ArtifactEmbeddedFormatProbes.ts b/src/artifacts/ArtifactEmbeddedFormatProbes.ts index 1a6c22b8ef..6e16aac199 100644 --- a/src/artifacts/ArtifactEmbeddedFormatProbes.ts +++ b/src/artifacts/ArtifactEmbeddedFormatProbes.ts @@ -30,6 +30,7 @@ import { type PyInstallerCookie, type PyInstallerCookieObservation, } from "./pyinstaller/CArchiveLayout.js"; +import { pyInstallerReaderFailure } from "./pyinstaller/PyInstallerFailure.js"; /** Completed observations and explicit recognition limits; null alone is examined absence. */ export interface ArtifactEmbeddedFormatProbeFacts { @@ -138,8 +139,7 @@ export class ArtifactEmbeddedFormatProbes { this.signal, ); abortIfNeeded(this.signal); - if (!found.ok) - throw new ArtifactReaderFailure(found.error.reason, found.error.message); + if (!found.ok) throw pyInstallerReaderFailure(found.error); this.#facts = { ...this.#facts, pyInstaller: found.value }; return found.value.state === "located" ? found.value.cookie : undefined; } diff --git a/src/artifacts/DotnetBundleArtifactReader.ts b/src/artifacts/DotnetBundleArtifactReader.ts index a1eb79ad40..30aa45a704 100644 --- a/src/artifacts/DotnetBundleArtifactReader.ts +++ b/src/artifacts/DotnetBundleArtifactReader.ts @@ -10,8 +10,8 @@ import type { StableRegularFileDescriptor } from "../filesystem/RegularFile.js"; import { ArtifactResourceScope, ArtifactReaderFailure, + assertProducedEntry, copyArtifactEntry, - sameArtifactEntry, type ArtifactEntry, type ArtifactReader, type ArtifactTraversalOptions, @@ -146,11 +146,11 @@ export class DotnetBundleArtifactReader implements ArtifactReader { const source = await this.#source.readSelectedPath(signal); this.#assertOpen(signal); const selected = this.#entries.get(entry.adapterKey); - if (selected === undefined || !sameArtifactEntry(entry, selected.entry)) - throw new ArtifactReaderFailure( - "integrity", - "Selected .NET bundle entry differs from its observed manifest", - ); + assertProducedEntry( + entry, + selected?.entry, + "Selected .NET bundle entry differs from its observed manifest", + ); const stream = Readable.from( this.#readMember(source, selected.file, signal), { objectMode: false }, diff --git a/src/artifacts/FitArtifactReader.test.ts b/src/artifacts/FitArtifactReader.test.ts index d974f84f26..bf192b575f 100644 --- a/src/artifacts/FitArtifactReader.test.ts +++ b/src/artifacts/FitArtifactReader.test.ts @@ -545,7 +545,9 @@ it("preserves a final validation failure when cancellation overlaps it", async ( ); const controller = new AbortController(); const finalValidation = phaseGate(); - const failure = new ArtifactReaderFailure("integrity", "carrier changed"); + const failure = new ArtifactReaderFailure("integrity", "carrier changed", { + integrityCheck: "container-identity", + }); const read = ArtifactFileSource.prototype.read; const readChunks = fileChunks.readFileHandleChunks; let owner: ArtifactFileSource | undefined; diff --git a/src/artifacts/NativeDmgArtifactReader.ts b/src/artifacts/NativeDmgArtifactReader.ts index 80aa8d1d0e..e923339c17 100644 --- a/src/artifacts/NativeDmgArtifactReader.ts +++ b/src/artifacts/NativeDmgArtifactReader.ts @@ -98,9 +98,8 @@ class NativeDmgCommandFailure extends ArtifactReaderFailure { ? {} : { cancellation: options.cancellation }), // Only hdiutil verify classifies a DMG failure as integrity. - ...(failure.reason === "integrity" - ? { integrityCheck: "image-checksum" as const } - : {}), + integrityCheck: + failure.reason === "integrity" ? "image-checksum" : undefined, }); this.processNotStarted = options?.processNotStarted ?? false; this.verifyDiagnostic = failure.verifyDiagnostic; diff --git a/src/artifacts/PyInstallerArtifactReader.ts b/src/artifacts/PyInstallerArtifactReader.ts index 6ab69f90b9..9014d86f0f 100644 --- a/src/artifacts/PyInstallerArtifactReader.ts +++ b/src/artifacts/PyInstallerArtifactReader.ts @@ -51,7 +51,7 @@ import { type CarrierPathDialect, } from "./pyinstaller/CArchiveMembers.js"; import { readPyzArchive } from "./pyinstaller/PyzArchive.js"; -import type { PyInstallerFailure } from "./pyinstaller/PyInstallerFailure.js"; +import { pyInstallerReaderFailure as failure } from "./pyinstaller/PyInstallerFailure.js"; import { readPyInstallerBytes } from "./pyinstaller/PyInstallerBytes.js"; const MAX_PARSED_FACT_BYTES = 32 * 1024 * 1024; @@ -687,12 +687,3 @@ export class PyInstallerArtifactReader implements ArtifactReader { state.charged += bytes; } } - -const failure = (error: PyInstallerFailure): ArtifactReaderFailure => - new ArtifactReaderFailure( - error.reason, - error.message, - error.reason === "integrity" - ? { integrityCheck: error.integrityCheck } - : undefined, - ); diff --git a/src/artifacts/ReleaseExposureReader.test.ts b/src/artifacts/ReleaseExposureReader.test.ts index 7ddd118b6d..390387bc34 100644 --- a/src/artifacts/ReleaseExposureReader.test.ts +++ b/src/artifacts/ReleaseExposureReader.test.ts @@ -680,6 +680,7 @@ describe("ReleaseExposureReader limits", () => { throw new ArtifactReaderFailure( "integrity", `Artifact changed during inventory: ${target}`, + { integrityCheck: "container-identity" }, ); }; const reader = new ReleaseExposureReader(); diff --git a/src/artifacts/apple/InterfaceBuilderFinalization.test.ts b/src/artifacts/apple/InterfaceBuilderFinalization.test.ts index 14157df649..d14914b69a 100644 --- a/src/artifacts/apple/InterfaceBuilderFinalization.test.ts +++ b/src/artifacts/apple/InterfaceBuilderFinalization.test.ts @@ -109,6 +109,7 @@ it.each([false, true])( const failure = new ArtifactReaderFailure( "integrity", "controlled physical archive refusal", + { integrityCheck: "container-identity" }, ); const open = vi .spyOn(DirectoryArtifactReader.prototype, "open") diff --git a/src/artifacts/pyinstaller/PyInstallerFailure.ts b/src/artifacts/pyinstaller/PyInstallerFailure.ts index 385802bc8d..874ba64288 100644 --- a/src/artifacts/pyinstaller/PyInstallerFailure.ts +++ b/src/artifacts/pyinstaller/PyInstallerFailure.ts @@ -1,4 +1,5 @@ import type { ArtifactIntegrityCheck } from "../../domain/artifactOperationError.js"; +import { ArtifactReaderFailure } from "../../resources/index.js"; /** Typed failure from a pure PyInstaller parser before the reader adapts it. */ export type PyInstallerFailure = @@ -9,6 +10,16 @@ export type PyInstallerFailure = readonly integrityCheck: ArtifactIntegrityCheck; }; +/** Adapt a parser failure, keeping the integrity check it names. */ +export const pyInstallerReaderFailure = ( + error: PyInstallerFailure, +): ArtifactReaderFailure => + error.reason === "integrity" + ? new ArtifactReaderFailure(error.reason, error.message, { + integrityCheck: error.integrityCheck, + }) + : new ArtifactReaderFailure(error.reason, error.message); + export const pyInstallerFailure = ( reason: "format" | "limit", message: string, diff --git a/src/browser/history/CaptureFailures.test.ts b/src/browser/history/CaptureFailures.test.ts index 5891fabd19..e523f7bbee 100644 --- a/src/browser/history/CaptureFailures.test.ts +++ b/src/browser/history/CaptureFailures.test.ts @@ -255,6 +255,7 @@ it.each(["before open", "during read"])( const cause = new ArtifactReaderFailure( "integrity", `Artifact changed ${stage}: ${path}`, + { integrityCheck: "container-identity" }, ); const error = historicalCaptureFailure(input, cause, "capture-read"); const projected = projectAnalysisError(error); @@ -409,7 +410,9 @@ it("preserves the exact cancellation reason and an earlier reader failure", () = const changed = historicalCaptureFailure( input, - new ArtifactReaderFailure("integrity", "Observed changed capture"), + new ArtifactReaderFailure("integrity", "Observed changed capture", { + integrityCheck: "container-identity", + }), "capture-read", { signal: controller.signal }, ); diff --git a/src/native/AppleDispatchMetadata.failure.test.ts b/src/native/AppleDispatchMetadata.failure.test.ts index 4cd3962710..0483d7e266 100644 --- a/src/native/AppleDispatchMetadata.failure.test.ts +++ b/src/native/AppleDispatchMetadata.failure.test.ts @@ -28,7 +28,9 @@ it.each([new RangeError("unexpected range"), new TypeError("unexpected type")])( it.each(["integrity", "path"] as const)( "reports a %s source-read refusal as a change to the bound target, not a provider failure", (reason) => { - const cause = new ArtifactReaderFailure(reason, "source boundary refused"); + const cause = new ArtifactReaderFailure(reason, "source boundary refused", { + integrityCheck: reason === "integrity" ? "container-identity" : undefined, + }); expect(appleDispatchMetadataFailure(cause, "/selected")._tag).toBe( "AnalysisArtifactChangedError", ); diff --git a/src/native/NativeMachoSource.ts b/src/native/NativeMachoSource.ts index 28ccb51922..1f69edbd82 100644 --- a/src/native/NativeMachoSource.ts +++ b/src/native/NativeMachoSource.ts @@ -44,7 +44,7 @@ export class NativeMachoSourceVerificationFailure extends ArtifactReaderFailure ? {} : { cancellation: verificationCause.cancellation }), } - : {}), + : { integrityCheck: undefined }), }, verificationCause instanceof ArtifactReaderFailure ? verificationCause.details diff --git a/src/process/OwnedLease.ts b/src/process/OwnedLease.ts index 7ea91431dc..9d57b116ee 100644 --- a/src/process/OwnedLease.ts +++ b/src/process/OwnedLease.ts @@ -65,6 +65,7 @@ export class OwnedLeaseCleanupFailure extends ArtifactReaderFailure { super(failure.reason, failure.message, { cause: primary, cleanup: failure.cleanup, + integrityCheck: failure.integrityCheck, }); this.cleanupLeases = failure.cleanupLeases; } diff --git a/src/resources/ArtifactReader.test.ts b/src/resources/ArtifactReader.test.ts index 0ac4f82430..6fe5bfa08b 100644 --- a/src/resources/ArtifactReader.test.ts +++ b/src/resources/ArtifactReader.test.ts @@ -56,3 +56,19 @@ it.each([ expect(second.cause).toBe(first); }, ); + +it("requires an integrity failure to name its check, including when rebuilt", () => { + // @ts-expect-error An integrity failure names the check that failed. + void new ArtifactReaderFailure("integrity", "unnamed integrity failure"); + const primary = new ArtifactReaderFailure("integrity", "carrier changed", { + integrityCheck: "container-identity", + }); + const rebuilt = new ArtifactReaderFailure(primary.reason, primary.message, { + cause: primary, + ...primary.primaryFacts(), + }); + expect(rebuilt.integrityCheck).toBe("container-identity"); + const reason: ArtifactReaderFailure["reason"] = primary.reason; + // @ts-expect-error A rebuild with a non-literal reason carries the check. + void new ArtifactReaderFailure(reason, "rebuilt without its check"); +}); diff --git a/src/resources/ArtifactReader.ts b/src/resources/ArtifactReader.ts index bbe58ecc3b..7776d3f321 100644 --- a/src/resources/ArtifactReader.ts +++ b/src/resources/ArtifactReader.ts @@ -42,7 +42,7 @@ export interface ArtifactReaderFailureOptions extends ErrorOptions { readonly admission?: ArtifactAdmissionLimit; readonly readerLimit?: ArtifactReaderLimitFact; /** For an `integrity` failure, the check that failed, when the reader names it. */ - readonly integrityCheck?: ArtifactIntegrityCheck; + readonly integrityCheck?: ArtifactIntegrityCheck | undefined; } /** Archive-neutral entry metadata. Reader adapters never choose output paths. */ @@ -268,6 +268,16 @@ export type CleanupFailedRead = ArtifactReaderFailure & { readonly cleanup: AnalysisCleanupObservation; }; +/** Why an artifact reader failed. */ +export type ArtifactReaderFailureReason = + | "cancelled" + | "format" + | "integrity" + | "io" + | "limit" + | "path" + | "unavailable"; + export class ArtifactReaderFailure extends Error { readonly userMessage: string | undefined; readonly resolvedPath: string | undefined; @@ -282,15 +292,35 @@ export class ArtifactReaderFailure extends Error { readonly readerLimit: ArtifactReaderLimitFact | undefined; readonly integrityCheck: ArtifactIntegrityCheck | undefined; + /** An `integrity` failure names the check that failed. */ constructor( - readonly reason: - | "cancelled" - | "format" - | "integrity" - | "io" - | "limit" - | "path" - | "unavailable", + reason: "integrity", + message: string, + options: ArtifactReaderFailureOptions & { + readonly integrityCheck: ArtifactIntegrityCheck; + }, + details?: ArtifactIntegrityDetails, + ); + constructor( + reason: Exclude, + message: string, + options?: ArtifactReaderFailureOptions, + details?: ArtifactIntegrityDetails, + ); + /** + * A rebuild whose reason is not a literal carries the check explicitly, as + * {@link primaryFacts} does, so a rewrapped integrity failure keeps it. + */ + constructor( + reason: ArtifactReaderFailureReason, + message: string, + options: ArtifactReaderFailureOptions & { + readonly integrityCheck: ArtifactIntegrityCheck | undefined; + }, + details?: ArtifactIntegrityDetails, + ); + constructor( + readonly reason: ArtifactReaderFailureReason, message: string, options?: ArtifactReaderFailureOptions, readonly details?: ArtifactIntegrityDetails, @@ -319,13 +349,8 @@ export class ArtifactReaderFailure extends Error { */ primaryFacts(): Pick< ArtifactReaderFailureOptions, - | "userMessage" - | "resolvedPath" - | "boundary" - | "admission" - | "readerLimit" - | "integrityCheck" - > { + "userMessage" | "resolvedPath" | "boundary" | "admission" | "readerLimit" + > & { readonly integrityCheck: ArtifactIntegrityCheck | undefined } { return { ...(this.userMessage === undefined ? {} @@ -338,9 +363,7 @@ export class ArtifactReaderFailure extends Error { ...(this.readerLimit === undefined ? {} : { readerLimit: this.readerLimit }), - ...(this.integrityCheck === undefined - ? {} - : { integrityCheck: this.integrityCheck }), + integrityCheck: this.integrityCheck, }; } diff --git a/src/resources/ArtifactResourceScope.ts b/src/resources/ArtifactResourceScope.ts index 5ca7bf70ea..2762248fe0 100644 --- a/src/resources/ArtifactResourceScope.ts +++ b/src/resources/ArtifactResourceScope.ts @@ -5,7 +5,10 @@ import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js"; import type { OwnedDirectoryHandle } from "../filesystem/OwnedDirectoryHandle.js"; import type { OwnedStagedOutput } from "../filesystem/OwnedStagedOutput.js"; -import type { ArtifactReader } from "./ArtifactReader.js"; +import type { + ArtifactReader, + ArtifactReaderFailureOptions, +} from "./ArtifactReader.js"; import { ArtifactReaderFailure, artifactPrimaryCleanupLeases, @@ -89,7 +92,7 @@ export class ArtifactResourceRetryFailure extends ArtifactReaderFailure { readonly lease: AnalysisCleanupLease; }[], message: string, - options: ConstructorParameters[2], + options?: ArtifactReaderFailureOptions, ) { super("unavailable", message, options); this.failedOwners = failures.map(({ owner }) => owner); diff --git a/src/resources/DirectoryArtifactReader.ts b/src/resources/DirectoryArtifactReader.ts index 9e4336a9d0..859d8c7db1 100644 --- a/src/resources/DirectoryArtifactReader.ts +++ b/src/resources/DirectoryArtifactReader.ts @@ -776,8 +776,9 @@ const assertContainedDirectory = async ( throw new ArtifactReaderFailure( failureReason, "Directory traversal escaped or changed its artifact root", - failureReason === "integrity" - ? { integrityCheck: "container-identity" } - : undefined, + { + integrityCheck: + failureReason === "integrity" ? "container-identity" : undefined, + }, ); }; diff --git a/src/sqlite/SqliteDatabaseSnapshot.ts b/src/sqlite/SqliteDatabaseSnapshot.ts index af40b534ff..96da783884 100644 --- a/src/sqlite/SqliteDatabaseSnapshot.ts +++ b/src/sqlite/SqliteDatabaseSnapshot.ts @@ -268,9 +268,10 @@ 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" }, + { + integrityCheck: + phase === "initial" ? undefined : "container-identity", + }, ); }, ); diff --git a/tests/boundary/filesystem/artifactInventorySnapshot.test.ts b/tests/boundary/filesystem/artifactInventorySnapshot.test.ts index 0c91b3396a..d6527f1294 100644 --- a/tests/boundary/filesystem/artifactInventorySnapshot.test.ts +++ b/tests/boundary/filesystem/artifactInventorySnapshot.test.ts @@ -132,6 +132,7 @@ it("unwinds every nested traversal and preserves its primary failure", async () throw new ArtifactReaderFailure( "integrity", "primary nested member failure", + { integrityCheck: "container-identity" }, ); }, async return() { diff --git a/tests/boundary/filesystem/assetCatalogFinalization.test.ts b/tests/boundary/filesystem/assetCatalogFinalization.test.ts index ad77dfcd5b..405e90fe7e 100644 --- a/tests/boundary/filesystem/assetCatalogFinalization.test.ts +++ b/tests/boundary/filesystem/assetCatalogFinalization.test.ts @@ -164,6 +164,7 @@ it.each(["decode_interface_builder", "inspect_keyed_archive"] as const)( throw new ArtifactReaderFailure( "integrity", "controlled Interface Builder source change", + { integrityCheck: "container-identity" }, ); }) : undefined; diff --git a/tests/boundary/filesystem/dotnetBundleArtifacts.test.ts b/tests/boundary/filesystem/dotnetBundleArtifacts.test.ts index c78f6549d7..8e81c9966e 100644 --- a/tests/boundary/filesystem/dotnetBundleArtifacts.test.ts +++ b/tests/boundary/filesystem/dotnetBundleArtifacts.test.ts @@ -483,7 +483,16 @@ it("rejects replacement, forged entry metadata and cancellation without losing c const entry = entries[0]!; await expect( reader.open({ ...entry, declaredSize: 1 }), - ).rejects.toMatchObject({ reason: "integrity" }); + ).rejects.toMatchObject({ + reason: "integrity", + integrityCheck: "entry-metadata", + }); + await expect( + reader.open({ ...entry, adapterKey: "foreign" }), + ).rejects.toMatchObject({ + reason: "integrity", + integrityCheck: "foreign-entry", + }); const controller = new AbortController(); controller.abort(); await expect(reader.open(entry, controller.signal)).rejects.toMatchObject({ diff --git a/tests/boundary/filesystem/interfaceBuilderBundle.test.ts b/tests/boundary/filesystem/interfaceBuilderBundle.test.ts index ddeb58577c..817081d8f4 100644 --- a/tests/boundary/filesystem/interfaceBuilderBundle.test.ts +++ b/tests/boundary/filesystem/interfaceBuilderBundle.test.ts @@ -784,6 +784,10 @@ describe("bounded Interface Builder archive decoding", () => { const failure = new ArtifactReaderFailure( reason, "source acquisition failed", + { + integrityCheck: + reason === "integrity" ? "container-identity" : undefined, + }, ); const open = vi .spyOn(DirectoryArtifactReader.prototype, "open") diff --git a/tests/boundary/process/artifactFileOutcomes.test.ts b/tests/boundary/process/artifactFileOutcomes.test.ts index b9f47e6892..ef782d4c79 100644 --- a/tests/boundary/process/artifactFileOutcomes.test.ts +++ b/tests/boundary/process/artifactFileOutcomes.test.ts @@ -61,6 +61,27 @@ const fileOutcomeControls = (["signal", "capture"] as const).flatMap((kind) => type FileOutcomeControl = (typeof fileOutcomeControls)[number]; +/** The physical read failure a control injects, with the facts production names. */ +const physicalFailure = (failure: FileOutcomeControl["failure"]): Error => + failure === "denied" + ? Object.assign(new Error("controlled read denial"), { code: "EACCES" }) + : failure === "format" + ? new ArtifactReaderFailure("format", "controlled physical file failure") + : failure === "limit" + ? // The stable reader names the bound it refused, as production does. + new ArtifactReaderFailure( + "limit", + "controlled physical file failure", + { + boundary: "file-size", + }, + ) + : new ArtifactReaderFailure( + "integrity", + "controlled physical file failure", + { integrityCheck: "container-identity" }, + ); + const createFileOutcomeFixture = async ({ kind, stage, @@ -81,19 +102,7 @@ const createFileOutcomeFixture = async ({ : "if(process.argv.includes('--version')) console.log('TShark (Wireshark) 4.6.9 (fixture)'); else console.log('[]');", { mode: 0o700 }, ); - const physical = - failure === "denied" - ? Object.assign(new Error("controlled read denial"), { code: "EACCES" }) - : new ArtifactReaderFailure( - failure === "format" - ? "format" - : failure === "limit" - ? "limit" - : "integrity", - "controlled physical file failure", - // The stable reader names the bound it refused, as production does. - failure === "limit" ? { boundary: "file-size" } : undefined, - ); + const physical = physicalFailure(failure); const selectedPath = resource === "limiter" ? limiter diff --git a/tests/process-global/stableArtifactConsumers.test.ts b/tests/process-global/stableArtifactConsumers.test.ts index b776c2d8ae..5446efb132 100644 --- a/tests/process-global/stableArtifactConsumers.test.ts +++ b/tests/process-global/stableArtifactConsumers.test.ts @@ -388,7 +388,9 @@ it.each( [ name, makeProvider, - new ArtifactReaderFailure("integrity", "source replacement"), + new ArtifactReaderFailure("integrity", "source replacement", { + integrityCheck: "container-identity", + }), AnalysisArtifactChangedError, ] as const, [ @@ -441,6 +443,7 @@ it.each(staticProviders)( const primary = new ArtifactReaderFailure( "integrity", "controlled source replacement", + { integrityCheck: "container-identity" }, ); fault.readFailure = { cause: primary }; const controller = new AbortController(); @@ -479,6 +482,7 @@ it("clears the Python pyc cleanup flag once a retained descriptor closes", async const primary = new ArtifactReaderFailure( "integrity", "controlled source replacement", + { integrityCheck: "container-identity" }, ); fault.readFailure = { cause: primary }; try { @@ -1176,6 +1180,7 @@ it.each(fileFailureProviders)( const primary = new ArtifactReaderFailure( "integrity", "original source replacement", + { integrityCheck: "container-identity" }, ); try { const nested = await scope