diff --git a/src/application/EvidenceBundleFiles.ts b/src/application/EvidenceBundleFiles.ts index 1f1a0a0b7..83f2f65d9 100644 --- a/src/application/EvidenceBundleFiles.ts +++ b/src/application/EvidenceBundleFiles.ts @@ -1,3 +1,5 @@ +import { resolve } from "node:path"; + import { createImmutableEvidenceBundle, describeEvidenceBundleFailure, @@ -37,13 +39,15 @@ type EvidenceWriteFailure = export const readEvidenceBundle = ( path: string, signal?: AbortSignal, + resources?: ArtifactResourceScope, ): Promise> => - readBundle(path, parseEvidenceBundle, signal); + readBundle(path, parseEvidenceBundle, signal, resources); /** Read an authenticated immutable snapshot for a subsequent session import. */ export const readImmutableEvidenceBundle = ( path: string, signal?: AbortSignal, + resources?: ArtifactResourceScope, ): Promise> => readBundle( path, @@ -52,26 +56,30 @@ export const readImmutableEvidenceBundle = ( return createImmutableEvidenceBundle(bundle.records, bundle.unknowns); }, signal, + resources, ); const readBundle = async ( path: string, parseBundle: (input: unknown) => EvidenceBundle, signal?: AbortSignal, + resources?: ArtifactResourceScope, ): Promise> => { if (signal?.aborted) return err(new AnalysisCancelledError("import_evidence_bundle")); - const loaded = await readJsonFile(path, signal).catch((cause: unknown) => { - // A failed close transfers a live handle owner; preserve that failure. - if ( - signal?.aborted === true && - !(cause instanceof RegularFileCleanupFailure) - ) - return err( - new AnalysisCancelledError("import_evidence_bundle", { cause }), - ); - throw cause; - }); + const loaded = await readJsonFile(path, signal, resources).catch( + (cause: unknown) => { + // A failed close transfers a live handle owner; preserve that failure. + if ( + signal?.aborted === true && + !(cause instanceof RegularFileCleanupFailure) + ) + return err( + new AnalysisCancelledError("import_evidence_bundle", { cause }), + ); + throw cause; + }, + ); if (!loaded.ok) return loaded; if (signal?.aborted) return err(new AnalysisCancelledError("import_evidence_bundle")); @@ -79,10 +87,19 @@ const readBundle = async ( try { bundle = parseBundle(loaded.value); } catch (cause: unknown) { + const failure = describeEvidenceBundleFailure(loaded.value, cause); + if (failure.kind === "single-record") + return err( + new EvidenceFileError("read", "wrong-kind", { + path: resolve(path), + cause, + userMessage: failure.message, + }), + ); return err( new EvidenceIntegrityError("Evidence bundle validation failed", { cause, - userMessage: describeEvidenceBundleFailure(loaded.value, cause), + userMessage: failure.message, }), ); } diff --git a/src/application/JsonFiles.ts b/src/application/JsonFiles.ts index 76a05f9cb..6bd1d66c8 100644 --- a/src/application/JsonFiles.ts +++ b/src/application/JsonFiles.ts @@ -24,6 +24,7 @@ import { type JsonObjectMemberReader, } from "./JsonInputFile.js"; import { NonRegularFileReadError } from "../filesystem/RegularFile.js"; +import { RegularFileCleanupFailure } from "./RegularFileRead.js"; import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js"; @@ -42,12 +43,14 @@ type TextWriteResult = export const readJsonFile = async ( path: string, signal?: AbortSignal, + resources?: ArtifactResourceScope, ): Promise< Result > => readJsonFileInput( path, - (selected) => readJsonInputFile(selected, "read_evidence_file", signal), + (selected) => + readJsonInputFile(selected, "read_evidence_file", signal, resources), signal, ); @@ -56,6 +59,7 @@ export const readJsonObjectMembersFile = ( path: string, scans: readonly ReadonlyMap[], signal?: AbortSignal, + resources?: ArtifactResourceScope, ): Promise< Result< void, @@ -65,7 +69,13 @@ export const readJsonObjectMembersFile = ( readJsonFileInput( path, (selected) => - readJsonObjectFile(selected, "read_evidence_file", scans, signal), + readJsonObjectFile( + selected, + "read_evidence_file", + scans, + signal, + resources, + ), signal, ); @@ -103,6 +113,7 @@ const readJsonFileInput = async ( } return ok(decoded.value); } catch (cause: unknown) { + if (cause instanceof RegularFileCleanupFailure) throw cause; if (cause instanceof AnalysisResourceConstraintError) return err(cause); if (signal?.aborted === true) throw cause; return err( diff --git a/src/application/JsonInputFile.ts b/src/application/JsonInputFile.ts index bceb482d2..a226cb0cc 100644 --- a/src/application/JsonInputFile.ts +++ b/src/application/JsonInputFile.ts @@ -11,6 +11,7 @@ import streamValues from "stream-json/streamers/stream-values.js"; import streamArray from "stream-json/streamers/stream-array.js"; import { RegularFileChangedError } from "../filesystem/RegularFile.js"; +import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; import { withRegularFile } from "./RegularFileRead.js"; import { JSON_BYTE_ORDER_MARK_MESSAGE, @@ -55,6 +56,7 @@ export const readJsonObjectFile = ( operation: string, scans: readonly ReadonlyMap[], signal?: AbortSignal, + resources?: ArtifactResourceScope, ): Promise> => withRegularFile( path, @@ -188,7 +190,10 @@ export const readJsonObjectFile = ( throw cause; } }, - { signal }, + { + signal, + ...(resources === undefined ? {} : { resources }), + }, ); const memberConsumer = ( @@ -236,6 +241,7 @@ export const readJsonInputFile = ( path: string, operation: string, signal?: AbortSignal, + resources?: ArtifactResourceScope, ): Promise> => withRegularFile( path, @@ -294,7 +300,10 @@ export const readJsonInputFile = ( throw cause; } }, - { signal }, + { + signal, + ...(resources === undefined ? {} : { resources }), + }, ); const jsonReadFailure = ( diff --git a/src/application/RegularFileRead.ts b/src/application/RegularFileRead.ts index 9183c9f8a..f09f4c192 100644 --- a/src/application/RegularFileRead.ts +++ b/src/application/RegularFileRead.ts @@ -95,7 +95,8 @@ const withRegularFileOwned = async ( cause.cleanupCause, ); if (options.resources === undefined) throw failure; - await retryRegularFileCleanup(failure, options.resources); + const retry = await retryRegularFileCleanup(failure, options.resources); + if (retry.cleanup !== undefined) throw failure; throw cause.cause; } const owner = new OwnedFileHandle(handle); @@ -128,9 +129,10 @@ const withRegularFileOwned = async ( cleanupCause, ); if (options.resources === undefined) throw failure; - const cleanup = await retryRegularFileCleanup(failure, options.resources); - if (cleanup.outcome.kind === "failed") throw cleanup.outcome.cause; - return cleanup.outcome.value; + const retry = await retryRegularFileCleanup(failure, options.resources); + if (retry.cleanup !== undefined) throw failure; + if (retry.outcome.kind === "failed") throw retry.outcome.cause; + return retry.outcome.value; } if (outcome.kind === "failed") throw outcome.cause; return outcome.value; diff --git a/src/application/binary/AnalysisSnapshotCache.ts b/src/application/binary/AnalysisSnapshotCache.ts index 6440ccf6a..bdaa9f68d 100644 --- a/src/application/binary/AnalysisSnapshotCache.ts +++ b/src/application/binary/AnalysisSnapshotCache.ts @@ -8,6 +8,7 @@ import { } from "../../domain/evidenceErrors.js"; import { NoBinaryOpenError } from "../../domain/configurationErrors.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import type { AnalysisInputError } from "../../domain/analysisErrorCore.js"; import { rebindEvidenceSubjectTargetPath } from "../../domain/evidence.js"; import { err, ok, type Result } from "../../domain/result.js"; import { @@ -190,7 +191,7 @@ export class AnalysisSnapshotCache { | undefined, mergeEvidence: ( bundle: EvidenceBundle, - ) => Result, + ) => Result, ): Result { let validated: AnalysisSnapshot; try { diff --git a/src/application/binary/AnalysisSnapshotFiles.ts b/src/application/binary/AnalysisSnapshotFiles.ts index 174b58bfc..e4b69953a 100644 --- a/src/application/binary/AnalysisSnapshotFiles.ts +++ b/src/application/binary/AnalysisSnapshotFiles.ts @@ -15,6 +15,7 @@ import { err, ok, type Result } from "../../domain/result.js"; import type { AnalysisResourceConstraintError } from "../../domain/analysisErrorCore.js"; import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js"; import { readJsonObjectMembersFile, writeTextFile } from "../JsonFiles.js"; +import { RegularFileCleanupFailure } from "../RegularFileRead.js"; import type { JsonObjectMemberReader } from "../JsonInputFile.js"; import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js"; @@ -24,6 +25,7 @@ type SnapshotFailure = EvidenceFileError | EvidenceIntegrityError; export const readAnalysisSnapshot = async ( path: string, signal?: AbortSignal, + resources?: ArtifactResourceScope, ): Promise< Result< AnalysisSnapshot, @@ -61,6 +63,7 @@ export const readAnalysisSnapshot = async ( metadata, ], signal, + resources, ); if (!loaded.ok) return loaded; signal?.throwIfAborted(); @@ -74,6 +77,7 @@ export const readAnalysisSnapshot = async ( signal?.throwIfAborted(); return ok(snapshot); } catch (cause: unknown) { + if (cause instanceof RegularFileCleanupFailure) throw cause; if (signal?.aborted === true) return err(new AnalysisCancelledError("read_evidence_file", { cause })); return err( diff --git a/src/application/binary/BinarySessionRecords.ts b/src/application/binary/BinarySessionRecords.ts index cfa0fa3b2..5a6bb4dd0 100644 --- a/src/application/binary/BinarySessionRecords.ts +++ b/src/application/binary/BinarySessionRecords.ts @@ -11,6 +11,7 @@ import { AnalysisSnapshotMismatchError, } from "../../domain/evidenceErrors.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import type { AnalysisInputError } from "../../domain/analysisErrorCore.js"; import type { UnknownRegistryError } from "../../domain/unknownRegistryError.js"; import type { RecordUnknownInput, @@ -129,7 +130,7 @@ export abstract class BinarySessionRecords { importEvidenceBundle( bundle: unknown, - ): Result { + ): Result { const imported = this.#records.mergeEvidenceBundle(bundle); if (!imported.ok) return imported; if (imported.value.metadataChanged) this.invalidateSnapshot(); diff --git a/src/application/investigation/EvidenceLedger.test.ts b/src/application/investigation/EvidenceLedger.test.ts index d4750f9c8..995580194 100644 --- a/src/application/investigation/EvidenceLedger.test.ts +++ b/src/application/investigation/EvidenceLedger.test.ts @@ -4,6 +4,7 @@ import type { BinaryTarget } from "../../domain/binaryTargetTypes.js"; import { createEvidence } from "../../domain/evidence.js"; import { createEvidenceBundle } from "../../domain/evidenceBundle.js"; import { recordUnknownInputSchema } from "../../domain/residualUnknown.js"; +import { projectAnalysisError } from "../../domain/analysisErrorProjection.js"; import { EvidenceLedger } from "./EvidenceLedger.js"; const TARGET: BinaryTarget = { @@ -234,6 +235,32 @@ describe("evidence ledger metadata imports", () => { }); describe("evidence bundle imports", () => { + it("classifies an authenticated Evidence record as the wrong import kind", () => { + const record = createEvidence(TARGET, PROVIDER, { + operation: "health", + parameters: {}, + result: true, + }); + const result = new EvidenceLedger().import(record); + expect(result).toMatchObject({ + ok: false, + error: { + _tag: "AnalysisInputError", + userMessage: expect.stringContaining( + `this JSON is one Evidence record (${record.evidence_id})`, + ), + }, + }); + if (result.ok) throw new Error("Expected a wrong-kind import failure"); + expect(projectAnalysisError(result.error)).toMatchObject({ + code: "invalid_request", + category: "invalid_input", + message: expect.stringContaining( + `this JSON is one Evidence record (${record.evidence_id})`, + ), + }); + }); + it("rejects conflicting duplicate IDs without mutating the ledger", () => { const ledger = new EvidenceLedger(); const first = createEvidence(TARGET, PROVIDER, { diff --git a/src/application/investigation/EvidenceLedger.ts b/src/application/investigation/EvidenceLedger.ts index fb27d40c8..7a5cd9f63 100644 --- a/src/application/investigation/EvidenceLedger.ts +++ b/src/application/investigation/EvidenceLedger.ts @@ -8,6 +8,7 @@ import { validateResidualUnknownAddition, type EvidenceBundle, } from "../../domain/evidenceBundle.js"; +import { AnalysisInputError } from "../../domain/analysisErrorCore.js"; import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js"; import { UnknownRegistryError } from "../../domain/unknownRegistryError.js"; import { @@ -37,7 +38,10 @@ export interface EvidenceImportDelta { readonly metadataChanged: boolean; } -type ImportResult = Result; +type ImportResult = Result< + EvidenceImportDelta, + EvidenceLedgerFailure | AnalysisInputError +>; /** Session-owned set of immutable evidence records. */ export class EvidenceLedger { @@ -76,10 +80,18 @@ export class EvidenceLedger { try { bundle = parseEvidenceBundle(input); } catch (cause: unknown) { + const failure = describeEvidenceBundleFailure(input, cause); + if (failure.kind === "single-record") + return err( + new AnalysisInputError("import_evidence_bundle", { + cause, + userMessage: failure.message, + }), + ); return err( new EvidenceIntegrityError("Evidence bundle validation failed", { cause, - userMessage: describeEvidenceBundleFailure(input, cause), + userMessage: failure.message, }), ); } diff --git a/src/application/investigation/InvestigationRecordPort.ts b/src/application/investigation/InvestigationRecordPort.ts index aacf8fa26..efaf9700b 100644 --- a/src/application/investigation/InvestigationRecordPort.ts +++ b/src/application/investigation/InvestigationRecordPort.ts @@ -2,6 +2,7 @@ import type { Evidence } from "../../domain/evidence.js"; import type { EvidenceBundle } from "../../domain/evidenceBundle.js"; import type { EvidenceIntegrityError } from "../../domain/evidenceErrors.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import type { AnalysisInputError } from "../../domain/analysisErrorCore.js"; import type { UnknownRegistryError } from "../../domain/unknownRegistryError.js"; import type { RecordUnknownInput, @@ -67,5 +68,7 @@ export interface InvestigationRecordPort EvidenceWriter, EvidenceUnknownWriter, UnknownRegistryPort { - importEvidenceBundle(bundle: unknown): Result; + importEvidenceBundle( + bundle: unknown, + ): Result; } diff --git a/src/application/investigation/InvestigationRecords.ts b/src/application/investigation/InvestigationRecords.ts index 9f10f14bd..29b93e246 100644 --- a/src/application/investigation/InvestigationRecords.ts +++ b/src/application/investigation/InvestigationRecords.ts @@ -3,6 +3,7 @@ import type { Evidence } from "../../domain/evidence.js"; import type { EvidenceBundle } from "../../domain/evidenceBundle.js"; import type { EvidenceIntegrityError } from "../../domain/evidenceErrors.js"; import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import type { AnalysisInputError } from "../../domain/analysisErrorCore.js"; import type { UnknownRegistryError } from "../../domain/unknownRegistryError.js"; import type { RecordUnknownInput, @@ -65,7 +66,7 @@ export class InvestigationRecords /** Atomically merge a bundle and report changes for the owner's post-commit observers. */ mergeEvidenceBundle( bundle: unknown, - ): Result { + ): Result { return this.#evidence.import(bundle); } diff --git a/src/application/process/ProcessCli.ts b/src/application/process/ProcessCli.ts index c353af622..94cc05c70 100644 --- a/src/application/process/ProcessCli.ts +++ b/src/application/process/ProcessCli.ts @@ -1,7 +1,10 @@ import { z } from "zod"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; -import { AnalysisInputError } from "../../domain/analysisErrorCore.js"; +import { + AnalysisCancelledError, + AnalysisInputError, +} from "../../domain/analysisErrorCore.js"; import { projectAnalysisError } from "../../domain/analysisErrorProjection.js"; import { createEvidence, parseEvidence } from "../../domain/evidence.js"; import { describeValidationFailure } from "../../domain/evidenceBundle.js"; @@ -23,6 +26,7 @@ import { } from "../../domain/process/processEvidenceProvider.js"; import { createProcessCaptureEvidence } from "./ProcessEvidence.js"; import { readJsonFile } from "../JsonFiles.js"; +import { RegularFileCleanupFailure } from "../RegularFileRead.js"; /** Safe process-command failure returned to the CLI adapter. */ export interface ProcessCliErrorOutput { @@ -51,7 +55,7 @@ export const captureProcessScenarioFile = async ( signal?: AbortSignal, ) => { try { - const input = await readJson(path); + const input = await readJson(path, "capture_process_scenario", signal); const parsed = processScenarioSchema.safeParse(input); if (!parsed.success) throw analysisInputErrorFromIssues( @@ -86,6 +90,7 @@ export const captureProcessScenarioFile = async ( if (!captured.ok) return cliAnalysisError(captured.error); return createProcessCaptureEvidence(parsed.data, captured.value); } catch (cause: unknown) { + if (cause instanceof RegularFileCleanupFailure) throw cause; return projectProcessCliError(cause); } }; @@ -95,14 +100,23 @@ export const compareProcessEvidenceFiles = async ( leftPath: string, rightPath: string, traceSpecPath?: string, + signal?: AbortSignal, ) => { try { - const left = parseCaptureEvidence(await readJson(leftPath), "left"); - const right = parseCaptureEvidence(await readJson(rightPath), "right"); + const left = parseCaptureEvidence( + await readJson(leftPath, "compare_process_captures", signal), + "left", + ); + const right = parseCaptureEvidence( + await readJson(rightPath, "compare_process_captures", signal), + "right", + ); const traceSpecification = traceSpecPath === undefined ? undefined - : parseTraceSpecification(await readJson(traceSpecPath)); + : parseTraceSpecification( + await readJson(traceSpecPath, "compare_process_captures", signal), + ); const comparison = traceSpecification === undefined ? compareProcessCaptures(left.capture, right.capture) @@ -129,6 +143,7 @@ export const compareProcessEvidenceFiles = async ( evidenceLinks: [left.id, right.id], }); } catch (cause: unknown) { + if (cause instanceof RegularFileCleanupFailure) throw cause; return projectProcessCliError(cause); } }; @@ -194,8 +209,21 @@ const invalidCaptureEvidence = (cause: unknown): ProcessCliFailure => `Capture evidence is malformed (${describeValidationFailure(cause)}). Create new capture evidence, then try again.`, ); -const readJson = async (path: string): Promise => { - const loaded = await readJsonFile(path); +const readJson = async ( + path: string, + operation: "capture_process_scenario" | "compare_process_captures", + signal?: AbortSignal, +): Promise => { + if (signal?.aborted) throw new AnalysisCancelledError(operation); + const loaded = await readJsonFile(path, signal).catch((cause: unknown) => { + if ( + signal?.aborted === true && + !(cause instanceof RegularFileCleanupFailure) + ) + throw new AnalysisCancelledError(operation, { cause }); + throw cause; + }); + if (signal?.aborted) throw new AnalysisCancelledError(operation); if (loaded.ok) return loaded.value; if (loaded.error._tag !== "EvidenceFileError") throw loaded.error; const detail = describeValidationFailure(loaded.error.cause); diff --git a/src/cli/processCommands.ts b/src/cli/processCommands.ts index d58a4f059..09538a6c4 100644 --- a/src/cli/processCommands.ts +++ b/src/cli/processCommands.ts @@ -40,12 +40,19 @@ export const registerProcessCommands = ( .describe("Optional partial-order or finite-trace specification path"), }), run: ({ args }) => - logCliCommand( - logger, - "compare-process-captures", - () => - compareProcessEvidenceFiles(args.left, args.right, args.traceSpec), - isProcessCliFailure, + withCommandCancellation((signal) => + logCliCommand( + logger, + "compare-process-captures", + () => + compareProcessEvidenceFiles( + args.left, + args.right, + args.traceSpec, + signal, + ), + isProcessCliFailure, + ), ), }); }; diff --git a/src/domain/analysisErrorCore.ts b/src/domain/analysisErrorCore.ts index c13ba891d..8e1138f19 100644 --- a/src/domain/analysisErrorCore.ts +++ b/src/domain/analysisErrorCore.ts @@ -45,13 +45,15 @@ export class AnalysisProtocolError extends AnalysisError { /** Caller input failed provider-neutral application parsing. */ export class AnalysisInputError extends AnalysisError { readonly _tag = "AnalysisInputError"; + override readonly userMessage: string | undefined; constructor( readonly operation: string, - options?: AnalysisErrorOptions, + options?: AnalysisErrorOptions & { readonly userMessage?: string }, readonly issues: readonly AnalysisInputIssue[] = [], ) { super(`Invalid analysis input for ${operation}`, options); + this.userMessage = options?.userMessage; } } diff --git a/src/domain/analysisErrorPresentation.ts b/src/domain/analysisErrorPresentation.ts index 3e6aa049c..fd5db4823 100644 --- a/src/domain/analysisErrorPresentation.ts +++ b/src/domain/analysisErrorPresentation.ts @@ -148,6 +148,7 @@ export const analysisErrorCategory = ( error instanceof EvidenceFileError && (error.reason === "missing" || error.reason === "not-file" || + error.reason === "wrong-kind" || error.reason === "exists") ) return "invalid_input"; @@ -210,7 +211,10 @@ export const analysisErrorUserMessage = (error: AnalysisError): string => { if (error instanceof AnalysisArtifactChangedError) return "The selected artifact changed during acquisition; no stable snapshot was decoded."; if (error instanceof AnalysisInputError) - return "Analysis input is invalid. Check the arguments and try again."; + return ( + error.userMessage ?? + "Analysis input is invalid. Check the arguments and try again." + ); const hopperMessage = hopperErrorUserMessage(error); if (hopperMessage !== undefined) return hopperMessage; if (error.userMessage !== undefined) return error.userMessage; diff --git a/src/domain/evidenceBundle.test.ts b/src/domain/evidenceBundle.test.ts index c0a322fe6..d2f90cbf6 100644 --- a/src/domain/evidenceBundle.test.ts +++ b/src/domain/evidenceBundle.test.ts @@ -5,6 +5,7 @@ import { ANALYSIS_SNAPSHOT_TARGET } from "./analysisSnapshot.fixture.js"; import { createEvidenceBundle, createImmutableEvidenceBundle, + describeEvidenceBundleFailure, evidenceBundleForTarget, parseEvidenceBundle, } from "./evidenceBundle.js"; @@ -18,6 +19,24 @@ const provider = { id: "fixture", name: "Fixture", version: "1" }; const targetDigest = "a".repeat(64); const foreignDigest = "b".repeat(64); +describe("evidence bundle failure classification", () => { + it("treats only authenticated standalone Evidence as the wrong input kind", () => { + const record = createEvidence(undefined, provider, { + operation: "observe", + parameters: {}, + result: { observed: true }, + }); + const single = describeEvidenceBundleFailure(record, new Error("bundle")); + expect(single).toMatchObject({ kind: "single-record" }); + + const tampered = describeEvidenceBundleFailure( + { ...record, normalized_result: { observed: false } }, + new Error("bundle"), + ); + expect(tampered).toMatchObject({ kind: "invalid-bundle" }); + }); +}); + const makeUnknown = ( question: string, scopeDigest: string, diff --git a/src/domain/evidenceBundle.ts b/src/domain/evidenceBundle.ts index 5e94620c7..c1fa3ce1c 100644 --- a/src/domain/evidenceBundle.ts +++ b/src/domain/evidenceBundle.ts @@ -208,16 +208,29 @@ const referencedEvidenceIds = (unknown: ResidualUnknown): readonly string[] => [ * Name the bundle constraint that failed and how to recover. A single * Evidence record, such as one command result, is not a bundle. */ +export type EvidenceBundleFailureDescription = + | { readonly kind: "single-record"; readonly message: string } + | { readonly kind: "invalid-bundle"; readonly message: string }; + export const describeEvidenceBundleFailure = ( input: unknown, cause: unknown, -): string => { - const record = evidenceSchema.safeParse(input); - if (record.success) - return `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.data.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`; - return cause instanceof z.ZodError - ? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.` - : `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`; +): EvidenceBundleFailureDescription => { + try { + const record = parseEvidence(input); + return { + kind: "single-record", + message: `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`, + }; + } catch { + return { + kind: "invalid-bundle", + message: + cause instanceof z.ZodError + ? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.` + : `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`, + }; + } }; /** Locate the first schema issue, or keep a thrown constraint message. */ diff --git a/src/domain/evidenceErrors.ts b/src/domain/evidenceErrors.ts index 364cbe79d..1aae747fd 100644 --- a/src/domain/evidenceErrors.ts +++ b/src/domain/evidenceErrors.ts @@ -45,6 +45,7 @@ export class EvidenceReferenceError extends EvidenceIntegrityError { /** Evidence bundle filesystem access failed within the configured policy. */ export class EvidenceFileError extends AnalysisError { readonly _tag = "EvidenceFileError"; + override readonly userMessage: string | undefined; /** Caller-selected path that failed, resolved against the working directory. */ readonly path: string | undefined; @@ -53,14 +54,22 @@ export class EvidenceFileError extends AnalysisError { constructor( readonly operation: "read" | "write", - readonly reason: "not-file" | "exists" | "invalid-json" | "missing" | "io", + readonly reason: + | "not-file" + | "exists" + | "wrong-kind" + | "invalid-json" + | "missing" + | "io", options?: AnalysisErrorOptions & { readonly path?: string; readonly published?: PublishedEvidenceFile; + readonly userMessage?: string; }, ) { super(`Evidence bundle ${operation} failed: ${reason}`, options); this.path = options?.path; this.published = options?.published; + this.userMessage = options?.userMessage; } } diff --git a/src/process/ProcessOwnership.test.ts b/src/process/ProcessOwnership.test.ts index 0aa644add..de233698c 100644 --- a/src/process/ProcessOwnership.test.ts +++ b/src/process/ProcessOwnership.test.ts @@ -67,81 +67,83 @@ describe("owned process-group cleanup discovery", () => { }); describe("opaque process neighbors during cleanup", () => { - it("cleans verified run-owned groups and records a withheld unrelated neighbor", async () => { - const processes = [ - { pid: 100, parentPid: 1, processGroupId: 100, command: "capture" }, - { - pid: 200, - parentPid: 1, - processGroupId: 200, - command: "detached-child", - }, - { - pid: 900, - parentPid: 1, - processGroupId: 900, - command: "/usr/bin/opaque-neighbor", - }, - ].map((process) => ({ ...process, state: "S" })); - const signalGroup = vi.fn(); - const identities = new Map( - processes.map(({ pid }) => [ - pid, - { state: "readable" as const, identity: `start-${String(pid)}` }, - ]), - ); - const adapter: ProcessOwnershipHost = { - platform: "darwin", - listProcesses: () => Promise.resolve(processes), - environment: (pid) => - Promise.resolve({ - REA_PROCESS_RUN_ID: pid === 900 ? "unowned" : "run-token", - }), - processIdentities: () => Promise.resolve(identities), - runTokens: (members) => - Promise.resolve( - new Map( - members.map(({ pid }) => [ - pid, - pid === 900 - ? { - state: "unavailable" as const, - reason: "platform_binary_environment_withheld", - } - : { state: "readable" as const, runId: "run-token" }, - ]), - ), - ), - signalGroup, - }; - - const result = await cleanupOwnedProcessGroup( - { - ...ownership, - sweepTokenOwnedProcesses: true, - captureBaseline: [], - }, - adapter, - ); - - expect(result).toMatchObject({ - cleaned: true, - signaled: true, - unverified: [ - { pid: 900, diagnostic: "platform_binary_environment_withheld" }, - ], - }); - expect(signalGroup.mock.calls).toEqual([ - [100, "SIGKILL"], - [200, "SIGKILL"], - ]); - expect(signalGroup).not.toHaveBeenCalledWith(900, "SIGKILL"); - }); - it.each([ - "environment_unavailable", + "platform_binary_environment_withheld", "restricted_process_environment_withheld", - ])("fails closed for an unrelated candidate with %s", async (diagnostic) => { + ])( + "cleans verified run-owned groups and records an unrelated %s neighbor", + async (diagnostic) => { + const processes = [ + { pid: 100, parentPid: 1, processGroupId: 100, command: "capture" }, + { + pid: 200, + parentPid: 1, + processGroupId: 200, + command: "detached-child", + }, + { + pid: 900, + parentPid: 1, + processGroupId: 900, + command: "/usr/bin/opaque-neighbor", + }, + ].map((process) => ({ ...process, state: "S" })); + const signalGroup = vi.fn(); + const identities = new Map( + processes.map(({ pid }) => [ + pid, + { state: "readable" as const, identity: `start-${String(pid)}` }, + ]), + ); + const adapter: ProcessOwnershipHost = { + platform: "darwin", + listProcesses: () => Promise.resolve(processes), + environment: (pid) => + Promise.resolve({ + REA_PROCESS_RUN_ID: pid === 900 ? "unowned" : "run-token", + }), + processIdentities: () => Promise.resolve(identities), + runTokens: (members) => + Promise.resolve( + new Map( + members.map(({ pid }) => [ + pid, + pid === 900 + ? { + state: "unavailable" as const, + reason: diagnostic, + } + : { state: "readable" as const, runId: "run-token" }, + ]), + ), + ), + signalGroup, + }; + + const result = await cleanupOwnedProcessGroup( + { + ...ownership, + sweepTokenOwnedProcesses: true, + captureBaseline: [], + }, + adapter, + ); + + expect(result).toMatchObject({ + cleaned: true, + signaled: true, + unverified: [{ pid: 900, diagnostic }], + }); + expect(signalGroup.mock.calls).toEqual([ + [100, "SIGKILL"], + [200, "SIGKILL"], + ]); + expect(signalGroup).not.toHaveBeenCalledWith(900, "SIGKILL"); + }, + ); + + it("fails closed for an unrelated candidate with an ordinary unavailable environment", async () => { + const diagnostic = "environment_unavailable"; const processes = [ { pid: 100, parentPid: 1, processGroupId: 100, command: "capture" }, { @@ -207,75 +209,81 @@ describe("opaque process neighbors during cleanup", () => { }); describe("related sweep candidates during cleanup", () => { - it.each(["environment_unavailable", "platform_binary_environment_withheld"])( - "fails closed for a related candidate with %s", - async (diagnostic) => { - const processes = [ - { - pid: 100, - parentPid: 1, - processGroupId: 100, - state: "S", - command: "capture", - }, - { - pid: 101, - parentPid: 100, - processGroupId: 100, - state: "S", - uid: process.getuid?.() === 0 ? 1 : 0, - command: "ready-hang", - }, - ]; - const signalGroup = vi.fn(); - const identities = new Map( - processes.map(({ pid }) => [ - pid, - { state: "readable" as const, identity: `start-${String(pid)}` }, - ]), - ); - const adapter: ProcessOwnershipHost = { - listProcesses: () => Promise.resolve(processes), - environment: (pid) => - pid === 100 - ? Promise.resolve({ REA_PROCESS_RUN_ID: "run-token" }) - : Promise.reject(new Error("EACCES: permission denied")), - processIdentities: () => Promise.resolve(identities), - runTokens: (members) => - Promise.resolve( - new Map( - members.map(({ pid }) => [ - pid, - pid === 100 - ? { state: "readable" as const, runId: "run-token" } - : { - state: "unavailable" as const, - reason: diagnostic, - }, - ]), - ), + it.each([ + "environment_unavailable", + "platform_binary_environment_withheld", + "restricted_process_environment_withheld", + ])("fails closed for a related candidate with %s", async (diagnostic) => { + const processes = [ + { + pid: 100, + parentPid: 1, + processGroupId: 100, + state: "S", + command: "capture", + }, + { + pid: 101, + parentPid: 100, + processGroupId: 100, + state: "S", + uid: + diagnostic === "restricted_process_environment_withheld" + ? (process.getuid?.() ?? 0) + : process.getuid?.() === 0 + ? 1 + : 0, + command: "ready-hang", + }, + ]; + const signalGroup = vi.fn(); + const identities = new Map( + processes.map(({ pid }) => [ + pid, + { state: "readable" as const, identity: `start-${String(pid)}` }, + ]), + ); + const adapter: ProcessOwnershipHost = { + listProcesses: () => Promise.resolve(processes), + environment: (pid) => + pid === 100 + ? Promise.resolve({ REA_PROCESS_RUN_ID: "run-token" }) + : Promise.reject(new Error("EACCES: permission denied")), + processIdentities: () => Promise.resolve(identities), + runTokens: (members) => + Promise.resolve( + new Map( + members.map(({ pid }) => [ + pid, + pid === 100 + ? { state: "readable" as const, runId: "run-token" } + : { + state: "unavailable" as const, + reason: diagnostic, + }, + ]), ), - signalGroup, - }; - - const result = await cleanupOwnedProcessGroup( - { - ...ownership, - sweepTokenOwnedProcesses: true, - captureBaseline: [], - }, - adapter, - ); - - expect(result).toMatchObject({ - cleaned: false, - reason: expect.stringContaining( - "process ownership token could not be read", ), - }); - expect(signalGroup).not.toHaveBeenCalled(); - }, - ); + signalGroup, + }; + + const result = await cleanupOwnedProcessGroup( + { + ...ownership, + sweepTokenOwnedProcesses: true, + captureBaseline: [], + }, + adapter, + ); + + expect(result).toMatchObject({ + cleaned: false, + reason: expect.stringContaining( + "process ownership token could not be read", + ), + }); + expect(signalGroup).not.toHaveBeenCalled(); + }); }); describe("sampled detached process groups during cleanup", () => { diff --git a/src/process/ProcessOwnership.ts b/src/process/ProcessOwnership.ts index 5b181fe76..399b9cd06 100644 --- a/src/process/ProcessOwnership.ts +++ b/src/process/ProcessOwnership.ts @@ -805,17 +805,21 @@ const TOKEN_READ_RETRY_DELAY_MS = 40; /** Darwin reports this when the kernel withholds a platform binary's environment. */ const PLATFORM_BINARY_ENVIRONMENT_WITHHELD = "platform_binary_environment_withheld"; +/** Darwin reports this when the kernel withholds a restricted process environment. */ +const RESTRICTED_PROCESS_ENVIRONMENT_WITHHELD = + "restricted_process_environment_withheld"; const currentProcessUid = (): number | undefined => typeof process.getuid === "function" ? process.getuid() : undefined; /** * Whether the operating system provably withheld this candidate's run token: - * current macOS omits the environment of Apple platform binaries from - * KERN_PROCARGS2 and fails with EINVAL for processes owned by another - * account, and neither class can be token-verified by any caller. Such a - * candidate is recorded as unverified instead of failing an otherwise clean - * capture; every other unreadable candidate stays fail-closed. + * current macOS omits the environment of Apple platform binaries and + * CS_RESTRICT processes from KERN_PROCARGS2, and fails with EINVAL for + * processes owned by another account. These classes cannot be token-verified + * by this caller. An unrelated candidate is recorded as unverified instead + * of failing an otherwise clean capture; every related or otherwise + * unreadable candidate stays fail-closed. */ const environmentWithheldFromInspection = ( entry: ProcessTableEntry, @@ -824,7 +828,10 @@ const environmentWithheldFromInspection = ( const uid = currentProcessUid(); if (uid !== undefined && entry.uid !== undefined && entry.uid !== uid) return true; - return diagnostic === PLATFORM_BINARY_ENVIRONMENT_WITHHELD; + return ( + diagnostic === PLATFORM_BINARY_ENVIRONMENT_WITHHELD || + diagnostic === RESTRICTED_PROCESS_ENVIRONMENT_WITHHELD + ); }; const scanTokenOwnedProcesses = async ( diff --git a/src/server/registerBundleComparisonTool.ts b/src/server/registerBundleComparisonTool.ts index 18e734cf5..75ef2a618 100644 --- a/src/server/registerBundleComparisonTool.ts +++ b/src/server/registerBundleComparisonTool.ts @@ -12,12 +12,14 @@ import { BUNDLE_COMPARISON_PROVIDER } from "../application/InvestigationProvider import { toolRegistrationOptions } from "./toolRegistrationOptions.js"; import { withAdmittedAnalysis } from "./analysisAdmission.js"; import { runAdmittedToolOperation } from "./admittedToolOperation.js"; +import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; /** Register canonical Evidence bundle comparison. */ export const registerBundleComparisonTool = ( server: EvidenceMcpServer, session: BinarySessionPort, contract: ReturnType>, + resources: ArtifactResourceScope, ): void => { const admission = withAdmittedAnalysis({ kind: "session", session }); server.registerTool( @@ -31,8 +33,16 @@ export const registerBundleComparisonTool = ( context.mcpReq.signal, async () => { const [left, right] = await Promise.all([ - readEvidenceBundle(input.left_bundle_path, context.mcpReq.signal), - readEvidenceBundle(input.right_bundle_path, context.mcpReq.signal), + readEvidenceBundle( + input.left_bundle_path, + context.mcpReq.signal, + resources, + ), + readEvidenceBundle( + input.right_bundle_path, + context.mcpReq.signal, + resources, + ), ]); if (!left.ok) return server.delivery.toCallToolResult(left, contract); if (!right.ok) diff --git a/src/server/registerSessionRecordTools.ts b/src/server/registerSessionRecordTools.ts index 5854aac9d..41efe981e 100644 --- a/src/server/registerSessionRecordTools.ts +++ b/src/server/registerSessionRecordTools.ts @@ -89,6 +89,7 @@ const registerSnapshotEvidenceTool = ({ const registerImportEvidenceTool = ({ server, session, + resources, importContract, }: EvidenceToolRegistration): void => { server.registerTool( @@ -97,7 +98,7 @@ const registerImportEvidenceTool = ({ async (input, context) => { const path = input.path; const signal = context.mcpReq.signal; - const loaded = await readImmutableEvidenceBundle(path, signal); + const loaded = await readImmutableEvidenceBundle(path, signal, resources); if (!loaded.ok) return server.delivery.toCallToolResult(loaded, importContract); const retainedUnknownRevisions = new Set( diff --git a/src/server/registerSessionTools.ts b/src/server/registerSessionTools.ts index 4db8031ce..16b9e6408 100644 --- a/src/server/registerSessionTools.ts +++ b/src/server/registerSessionTools.ts @@ -160,6 +160,7 @@ export interface LifecycleToolRegistration { const registerLifecycleTools = ( registration: LifecycleToolRegistration, + artifactResources: ArtifactResourceScope, ): void => { const { server, @@ -169,7 +170,7 @@ const registerLifecycleTools = ( availabilityPolicy, androidAnalysisAvailability, } = registration; - registerOpenLifecycleTool(registration); + registerOpenLifecycleTool(registration, artifactResources); registerCloseLifecycleTool(registration); registerSessionStatusTool({ server, @@ -181,12 +182,10 @@ const registerLifecycleTools = ( }); }; -const registerOpenLifecycleTool = ({ - server, - session, - logger, - openContract, -}: LifecycleToolRegistration): void => { +const registerOpenLifecycleTool = ( + { server, session, logger, openContract }: LifecycleToolRegistration, + artifactResources: ArtifactResourceScope, +): void => { server.registerTool( openContract.name, toolRegistrationOptions(openContract), @@ -196,6 +195,7 @@ const registerOpenLifecycleTool = ({ const loaded = await readAnalysisSnapshot( input.snapshot_path, context.mcpReq.signal, + artifactResources, ); if (!loaded.ok) return server.delivery.toCallToolResult(loaded, openContract); @@ -302,42 +302,45 @@ export const registerSessionTools = ( const compareBundlesContract = toolContract("compare_bundles"); const snapshotContract = toolContract("get_evidence_bundle"); const processResources = new ProcessCaptureResourceScope(); - registerLifecycleTools({ - server, - session, - logger, - openContract, - closeContract, - statusContract, - startedAt: options.startedAt ?? new Date().toISOString(), - availabilityPolicy: sessionAvailabilityPolicy( - options.availabilityPolicy, - {}, - ), - androidAnalysisAvailability: - options.androidAnalysisAvailability ?? missingAndroidAvailability, - closeProcessResources: async () => { - try { - await processResources.retryCleanup(); - return ok(null); - } catch (cause: unknown) { - return err( - new ProcessCaptureError( - "process capture cleanup remains incomplete", - { - cause, - reason: "cleanup_incomplete", - cleanupResources: ["process_capture_resources"], - executionFailure: - cause instanceof Error - ? cause.message || cause.name - : String(cause), - }, - ), - ); - } + registerLifecycleTools( + { + server, + session, + logger, + openContract, + closeContract, + statusContract, + startedAt: options.startedAt ?? new Date().toISOString(), + availabilityPolicy: sessionAvailabilityPolicy( + options.availabilityPolicy, + {}, + ), + androidAnalysisAvailability: + options.androidAnalysisAvailability ?? missingAndroidAvailability, + closeProcessResources: async () => { + try { + await processResources.retryCleanup(); + return ok(null); + } catch (cause: unknown) { + return err( + new ProcessCaptureError( + "process capture cleanup remains incomplete", + { + cause, + reason: "cleanup_incomplete", + cleanupResources: ["process_capture_resources"], + executionFailure: + cause instanceof Error + ? cause.message || cause.name + : String(cause), + }, + ), + ); + } + }, }, - }); + options.artifactResources, + ); registerEvidenceTools({ server, session, @@ -381,7 +384,12 @@ export const registerSessionTools = ( registerProcessComparisonTool(server, session, compareContract); registerArtifactComparisonTool(server, session, compareArtifactsContract); registerFunctionComparisonTool(server, session, compareFunctionsContract); - registerBundleComparisonTool(server, session, compareBundlesContract); + registerBundleComparisonTool( + server, + session, + compareBundlesContract, + options.artifactResources, + ); registerInvestigationTools(server, session); registerUnknownTools({ server, session }); registerContextTools(server, session); diff --git a/tests/boundary/cli/evidenceBundleCommands.test.ts b/tests/boundary/cli/evidenceBundleCommands.test.ts index 418c20eb4..abb56f7e8 100644 --- a/tests/boundary/cli/evidenceBundleCommands.test.ts +++ b/tests/boundary/cli/evidenceBundleCommands.test.ts @@ -66,6 +66,27 @@ cliTest( }, ); +cliTest( + "reports a standalone Evidence record as the wrong input file kind", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-evidence-record-input-"); + const path = join(root, "record.json"); + const record = revisionBundle().records[0]; + if (record === undefined) throw new Error("Missing fixture Evidence"); + await writeFile(path, JSON.stringify(record)); + const result = await cli.run({ + arguments: ["evidence-import", path, "--json"], + }); + expect(result.exitCode).toBe(1); + expect(result.json).toMatchObject({ + code: "invalid_request", + category: "invalid_input", + details: { path }, + message: expect.stringContaining("this JSON is one Evidence record"), + }); + }, +); + cliTest( "rejects altered Evidence and incomplete unknown history before reporting counts", async ({ cli }) => { diff --git a/tests/boundary/filesystem/analysisSnapshot.test.ts b/tests/boundary/filesystem/analysisSnapshot.test.ts index a235fb4e6..e4b331538 100644 --- a/tests/boundary/filesystem/analysisSnapshot.test.ts +++ b/tests/boundary/filesystem/analysisSnapshot.test.ts @@ -1,10 +1,11 @@ import { readFile, stat, writeFile } from "node:fs/promises"; import { join } from "node:path"; -import { describe, expect, it } from "vitest"; +import { describe, expect, it, onTestFinished, vi } from "vitest"; import { withArtifactResourceScope } from "../../fixtures/artifactInventory.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; +import { holdFirstFileRead } from "../../support/holdFirstFileRead.js"; import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js"; import { @@ -29,6 +30,8 @@ import { createEvidence } from "../../../src/domain/evidence.js"; import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js"; import { readJsonObjectFile } from "../../../src/application/JsonInputFile.js"; import { RegularFileChangedError } from "../../../src/filesystem/RegularFile.js"; +import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js"; +import { RegularFileCleanupFailure } from "../../../src/application/RegularFileRead.js"; const snapshotFixture = (): AnalysisSnapshot => { const target = snapshotTarget(TARGET); @@ -227,20 +230,67 @@ describe("analysis snapshot member decoding", () => { `${" ".repeat(9 * 1024 * 1024)}${JSON.stringify(snapshot)}`, ); const controller = new AbortController(); + const reads = await holdFirstFileRead(path); + onTestFinished(() => { + controller.abort(); + reads.release(); + }); const pending = readAnalysisSnapshot(path, controller.signal); - const timer = setTimeout(() => controller.abort(), 1); + await reads.firstRead; + controller.abort(); + reads.release(); try { expect(await pending).toMatchObject({ ok: false, error: { _tag: "AnalysisCancelledError" }, }); + expect(reads.readCount).toBe(1); } finally { - clearTimeout(timer); + vi.restoreAllMocks(); } const loaded = await readAnalysisSnapshot(path); if (!loaded.ok) throw loaded.error; expect(loaded.value).toEqual(snapshot); }); +}); + +describe("analysis snapshot file ownership", () => { + it.each([false, true])( + "retains the file owner when snapshot close fails (cancelled: %s)", + async (cancelDuringClose) => { + const directory = await createTestTempDirectory("rea-snapshot-cleanup-"); + const path = join(directory, "snapshot.json"); + await writeFile(path, JSON.stringify(snapshotFixture())); + const controller = new AbortController(); + const cleanupCause = new Error("injected snapshot file close failure"); + const close = vi + .spyOn(OwnedFileHandle.prototype, "close") + .mockImplementationOnce(async () => { + if (cancelDuringClose) controller.abort(); + throw cleanupCause; + }); + let failure: unknown; + try { + try { + await readAnalysisSnapshot( + path, + cancelDuringClose ? controller.signal : undefined, + ); + } catch (cause: unknown) { + failure = cause; + } + expect(failure).toBeInstanceOf(RegularFileCleanupFailure); + if (!(failure instanceof RegularFileCleanupFailure)) + throw new Error("Expected the retained snapshot file handle owner"); + expect(failure.cleanupCause).toBe(cleanupCause); + expect(failure.owner.handle.fd).toBeGreaterThanOrEqual(0); + } finally { + close.mockRestore(); + if (failure instanceof RegularFileCleanupFailure) + await failure.owner.close(); + } + }, + ); it("rejects changed bytes between scans on the same descriptor", async () => { const directory = await createTestTempDirectory("rea-snapshot-changed-"); diff --git a/tests/boundary/filesystem/evidenceBundleFiles.test.ts b/tests/boundary/filesystem/evidenceBundleFiles.test.ts index 856a545aa..44d577d26 100644 --- a/tests/boundary/filesystem/evidenceBundleFiles.test.ts +++ b/tests/boundary/filesystem/evidenceBundleFiles.test.ts @@ -434,21 +434,8 @@ describe("evidence bundle filesystem adapter", () => { }, ); - it("names the failed bundle constraint for a single record or schema mismatch", async () => { + it("names schema mismatches that prevent bundle parsing", async () => { const directory = await createTestTempDirectory("rea-evidence-"); - const record = bundle().records[0]; - const single = join(directory, "record.json"); - await writeFile(single, JSON.stringify(record)); - expect(await readEvidenceBundle(single)).toMatchObject({ - ok: false, - error: { - _tag: "EvidenceIntegrityError", - userMessage: expect.stringContaining( - `this JSON is one Evidence record (${String(record?.evidence_id)})`, - ), - }, - }); - const partial = join(directory, "partial.json"); await writeFile(partial, JSON.stringify({ evidence_id: "typo" })); const rejected = await readEvidenceBundle(partial); @@ -477,3 +464,38 @@ describe("evidence bundle filesystem adapter", () => { }); }); }); + +describe("standalone Evidence bundle inputs", () => { + it("classifies a record only after authenticating it", async () => { + const directory = await createTestTempDirectory("rea-evidence-"); + const record = bundle().records[0]; + const single = join(directory, "record.json"); + await writeFile(single, JSON.stringify(record)); + expect(await readEvidenceBundle(single)).toMatchObject({ + ok: false, + error: { + _tag: "EvidenceFileError", + reason: "wrong-kind", + path: single, + userMessage: expect.stringContaining( + `this JSON is one Evidence record (${String(record?.evidence_id)})`, + ), + }, + }); + + const tamperedRecord = join(directory, "tampered-record.json"); + await writeFile( + tamperedRecord, + JSON.stringify({ ...record, normalized_result: "changed" }), + ); + expect(await readEvidenceBundle(tamperedRecord)).toMatchObject({ + ok: false, + error: { + _tag: "EvidenceIntegrityError", + userMessage: expect.stringContaining( + "does not match the bundle schema", + ), + }, + }); + }); +}); diff --git a/tests/boundary/filesystem/jsonFileResourceOwnership.test.ts b/tests/boundary/filesystem/jsonFileResourceOwnership.test.ts new file mode 100644 index 000000000..9e04ec1e0 --- /dev/null +++ b/tests/boundary/filesystem/jsonFileResourceOwnership.test.ts @@ -0,0 +1,75 @@ +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; + +import { expect, it, vi } from "vitest"; + +import { ArtifactResourceScope } from "../../../src/artifacts/ArtifactResourceScope.js"; +import { readJsonFile } from "../../../src/application/JsonFiles.js"; +import { RegularFileCleanupFailure } from "../../../src/application/RegularFileRead.js"; +import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; + +it("retains and retries a JSON file owner after a persistent close failure", async () => { + const root = await createTestTempDirectory("rea-json-file-owner-"); + const path = join(root, "input.json"); + await writeFile(path, '{"value":"retained"}'); + const resources = new ArtifactResourceScope(); + const closeFailure = new Error("injected persistent close failure"); + let attempts = 0; + const close = vi + .spyOn(OwnedFileHandle.prototype, "close") + .mockImplementation(async () => { + attempts += 1; + throw closeFailure; + }); + let failure: unknown; + try { + try { + await readJsonFile(path, undefined, resources); + } catch (cause: unknown) { + failure = cause; + } + expect(failure).toBeInstanceOf(RegularFileCleanupFailure); + if (!(failure instanceof RegularFileCleanupFailure)) + throw new Error("Expected the failed file owner to remain visible"); + expect(failure.cleanupCause).toBe(closeFailure); + expect(failure.outcome).toMatchObject({ + kind: "completed", + value: { ok: true, value: { value: "retained" } }, + }); + expect(failure.owner.handle.fd).toBeGreaterThanOrEqual(0); + expect(attempts).toBe(2); + } finally { + close.mockRestore(); + await resources.close(); + } + if (!(failure instanceof RegularFileCleanupFailure)) + throw new Error("Expected the retained file owner"); + expect(failure.owner.handle.fd).toBe(-1); +}); + +it("returns parsed JSON when a failed file close is recovered by the resource scope", async () => { + const root = await createTestTempDirectory("rea-json-file-close-retry-"); + const path = join(root, "input.json"); + await writeFile(path, '{"value":"retained"}'); + const resources = new ArtifactResourceScope(); + const closeFailure = new Error("injected transient close failure"); + const originalClose = OwnedFileHandle.prototype.close; + let attempts = 0; + const close = vi + .spyOn(OwnedFileHandle.prototype, "close") + .mockImplementation(async function (this: OwnedFileHandle) { + attempts += 1; + if (attempts === 1) throw closeFailure; + await originalClose.call(this); + }); + try { + const parsed = await readJsonFile(path, undefined, resources); + if (!parsed.ok) throw parsed.error; + expect(parsed.value).toEqual({ value: "retained" }); + expect(attempts).toBe(2); + } finally { + close.mockRestore(); + await resources.close(); + } +}); diff --git a/tests/boundary/filesystem/processCliFileInput.test.ts b/tests/boundary/filesystem/processCliFileInput.test.ts index c4b340ffc..10548091a 100644 --- a/tests/boundary/filesystem/processCliFileInput.test.ts +++ b/tests/boundary/filesystem/processCliFileInput.test.ts @@ -1,15 +1,22 @@ import { writeFile } from "node:fs/promises"; import { join } from "node:path"; -import { describe, expect, it } from "vitest"; +import { describe, expect, it, onTestFinished, vi } from "vitest"; import { captureProcessScenarioFile, + compareProcessEvidenceFiles, projectProcessCliError, } from "../../../src/application/process/ProcessCli.js"; import { JSON_BYTE_ORDER_MARK_MESSAGE } from "../../../src/application/Utf8JsonInput.js"; +import { createEvidence } from "../../../src/domain/evidence.js"; +import { PROCESS_PROVIDER } from "../../../src/domain/process/processEvidenceProvider.js"; +import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../../../src/domain/process/processCaptureExample.js"; +import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js"; +import { RegularFileCleanupFailure } from "../../../src/application/RegularFileRead.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; +import { holdFirstFileRead } from "../../support/holdFirstFileRead.js"; -describe("process CLI input diagnostics", () => { +describe("process CLI error projection", () => { it("preserves local diagnostics for unexpected process failures", () => { const projected = projectProcessCliError( new Error("SECRET internal failure /private/path"), @@ -22,7 +29,116 @@ describe("process CLI input diagnostics", () => { }); expect(JSON.stringify(projected)).not.toContain("stack"); }); +}); +describe("process CLI file cancellation", () => { + it("projects pre-aborted file reads as cancellation", async () => { + const root = await createTestTempDirectory("rea-process-cli-cancel-"); + const controller = new AbortController(); + controller.abort(); + expect( + await captureProcessScenarioFile( + join(root, "missing-scenario.json"), + process.env, + controller.signal, + ), + ).toMatchObject({ + error: "Process command failed", + code: "cancelled", + category: "cancelled", + details: { operation: "capture_process_scenario" }, + }); + expect( + await compareProcessEvidenceFiles( + join(root, "missing-left.json"), + join(root, "missing-right.json"), + join(root, "missing-trace.json"), + controller.signal, + ), + ).toMatchObject({ + code: "cancelled", + category: "cancelled", + details: { operation: "compare_process_captures" }, + }); + }); + + it.each([ + { workflow: "capture", input: "scenario" }, + { workflow: "compare", input: "left" }, + { workflow: "compare", input: "right" }, + { workflow: "compare", input: "trace specification" }, + ] as const)( + "stops streamed $workflow $input reads after cancellation", + async ({ workflow, input }) => { + const root = await createTestTempDirectory("rea-process-cli-stream-"); + const paths = { + scenario: join(root, "scenario.json"), + left: join(root, "left.json"), + right: join(root, "right.json"), + trace: join(root, "trace.json"), + }; + const evidence = JSON.stringify(processCaptureEvidence()); + const scenario = JSON.stringify({ + executable: process.execPath, + arguments: [], + }); + const traceSpecification = JSON.stringify(validTraceSpecification()); + const contentsByInput = { + scenario: input === "scenario" ? stream(scenario) : scenario, + left: input === "left" ? stream(evidence) : evidence, + right: input === "right" ? stream(evidence) : evidence, + trace: + input === "trace specification" + ? stream(traceSpecification) + : traceSpecification, + }; + await Promise.all([ + writeFile(paths.scenario, contentsByInput.scenario), + writeFile(paths.left, contentsByInput.left), + writeFile(paths.right, contentsByInput.right), + writeFile(paths.trace, contentsByInput.trace), + ]); + const targetPath = + paths[input === "trace specification" ? "trace" : input]; + const contents = + contentsByInput[input === "trace specification" ? "trace" : input]; + const reader = await holdFirstFileRead(targetPath); + onTestFinished(reader.release); + const controller = new AbortController(); + try { + const pending = + workflow === "capture" + ? captureProcessScenarioFile( + paths.scenario, + process.env, + controller.signal, + ) + : compareProcessEvidenceFiles( + paths.left, + paths.right, + paths.trace, + controller.signal, + ); + await reader.firstRead; + controller.abort(); + reader.release(); + expect(await pending).toMatchObject({ + error: "Process command failed", + code: "cancelled", + category: "cancelled", + }); + expect(reader.readCount).toBe(1); + expect(reader.totalReadBytes).toBeLessThan(contents.length); + } finally { + controller.abort(); + reader.release(); + vi.restoreAllMocks(); + } + }, + ); +}); + +describe("process CLI input diagnostics", () => { it("projects missing, malformed JSON, and invalid scenario files", async () => { const root = await createTestTempDirectory("rea-process-cli-diagnostics-"); const malformed = join(root, "malformed.json"); @@ -78,6 +194,44 @@ describe("process CLI input diagnostics", () => { }); }); + it.each([false, true])( + "preserves the open-file owner when close fails (cancelled: %s)", + async (cancelDuringClose) => { + const root = await createTestTempDirectory("rea-process-cli-cleanup-"); + const path = join(root, "scenario.json"); + await writeFile(path, JSON.stringify({ executable: process.execPath })); + const controller = new AbortController(); + const cleanupCause = new Error("injected file close failure"); + const close = vi + .spyOn(OwnedFileHandle.prototype, "close") + .mockImplementationOnce(async () => { + if (cancelDuringClose) controller.abort(); + throw cleanupCause; + }); + let failure: unknown; + try { + try { + await captureProcessScenarioFile( + path, + process.env, + cancelDuringClose ? controller.signal : undefined, + ); + } catch (cause: unknown) { + failure = cause; + } + expect(failure).toBeInstanceOf(RegularFileCleanupFailure); + if (!(failure instanceof RegularFileCleanupFailure)) + throw new Error("Expected the retained file handle owner"); + expect(failure.cleanupCause).toBe(cleanupCause); + expect(failure.owner.handle.fd).toBeGreaterThanOrEqual(0); + } finally { + close.mockRestore(); + if (failure instanceof RegularFileCleanupFailure) + await failure.owner.close(); + } + }, + ); + it("names a leading byte-order mark instead of quoting it as a token", async () => { const path = join( await createTestTempDirectory("rea-process-cli-diagnostics-"), @@ -91,3 +245,40 @@ describe("process CLI input diagnostics", () => { }); }); }); + +const processCaptureEvidence = () => + createEvidence(undefined, PROCESS_PROVIDER, { + predicateType: "rea.process-capture", + operation: "capture_process_scenario", + parameters: {}, + result: EMPTY_PROCESS_CAPTURE_EXAMPLE, + confidence: "observed", + authority: "controlled-replay", + environment: { + id: "fixture", + platform: "fixture", + architecture: "fixture", + isolation: "process", + }, + }); + +const stream = (json: string) => " ".repeat(8 * 1024 * 1024) + json; + +const validTraceSpecification = () => ({ + events: [ + { + id: "started", + source: "lifecycle", + exact: { state: "started" }, + }, + { + id: "finished", + source: "lifecycle", + exact: { state: "finished" }, + }, + ], + language: { + kind: "partial_order", + happens_before: [{ before: "started", after: "finished" }], + }, +}); diff --git a/tests/boundary/mcp/bundleComparisonCancellation.test.ts b/tests/boundary/mcp/bundleComparisonCancellation.test.ts index b665c54e1..fc0c7c725 100644 --- a/tests/boundary/mcp/bundleComparisonCancellation.test.ts +++ b/tests/boundary/mcp/bundleComparisonCancellation.test.ts @@ -1,5 +1,5 @@ import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; -import { open, writeFile, type FileHandle } from "node:fs/promises"; +import { writeFile } from "node:fs/promises"; import { join } from "node:path"; import { expect, it, onTestFinished, vi } from "vitest"; @@ -13,6 +13,7 @@ import { createServer } from "../../../src/server/createServer.js"; import { ToolResultDelivery } from "../../../src/server/toolResult.js"; import { createTestBinarySession } from "../../fixtures/binarySession.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; +import { holdFirstFileRead } from "../../support/holdFirstFileRead.js"; it("leaves the session unchanged after bundle comparison cancellation and permits a retry", async () => { const root = await createTestTempDirectory("rea-mcp-compare-cancel-"); @@ -58,8 +59,10 @@ it("leaves the session unchanged after bundle comparison cancellation and permit version: "1", }); const controller = new AbortController(); + let releaseRead: (() => void) | undefined; onTestFinished(async () => { controller.abort(); + releaseRead?.(); vi.restoreAllMocks(); await client.close(); await server.close(); @@ -70,8 +73,8 @@ it("leaves the session unchanged after bundle comparison cancellation and permit await server.connect(serverTransport); await client.connect(clientTransport); - const reader = await holdFirstRead(leftPath); - onTestFinished(reader.release); + const reader = await holdFirstFileRead(leftPath); + releaseRead = reader.release; let resolveDispatched: (() => void) | undefined; const dispatched = new Promise((resolve) => { @@ -162,56 +165,3 @@ it("leaves the session unchanged after bundle comparison cancellation and permit ]), ); }); - -const holdFirstRead = async (path: string) => { - // Hold the first streamed read after it reaches the operating system. - const probe = await open(path, "r"); - const identity = await probe.stat(); - const fileHandlePrototype = Object.getPrototypeOf(probe) as { - read( - buffer: Buffer, - offset: number, - length: number, - position: number | null, - ): Promise<{ readonly bytesRead: number; readonly buffer: Buffer }>; - }; - await probe.close(); - let totalReadBytes = 0; - let readCount = 0; - let resolveFirstRead: (() => void) | undefined; - const firstRead = new Promise((resolve) => { - resolveFirstRead = resolve; - }); - let releaseRead: (() => void) | undefined; - const readGate = new Promise((resolve) => { - releaseRead = resolve; - }); - const read = fileHandlePrototype.read; - vi.spyOn(fileHandlePrototype, "read").mockImplementation(async function ( - this: FileHandle, - ...args: [Buffer, number, number, number | null] - ) { - const current = await this.stat(); - const isTarget = - current.dev === identity.dev && current.ino === identity.ino; - const result = await read.call(this, ...args); - if (!isTarget) return result; - totalReadBytes += result.bytesRead; - readCount += 1; - if (readCount === 1) { - resolveFirstRead?.(); - await readGate; - } - return result; - }); - return { - firstRead, - release: () => releaseRead?.(), - get readCount() { - return readCount; - }, - get totalReadBytes() { - return totalReadBytes; - }, - }; -}; diff --git a/tests/boundary/mcp/bundleComparisonMcp.test.ts b/tests/boundary/mcp/bundleComparisonMcp.test.ts index 9fb00e768..ab8838287 100644 --- a/tests/boundary/mcp/bundleComparisonMcp.test.ts +++ b/tests/boundary/mcp/bundleComparisonMcp.test.ts @@ -134,7 +134,9 @@ describe("bundle comparison MCP integration", () => { expect(result.isError).toBe(true); expect(parseMcpToolError(result)).toMatchObject({ error: { - code: "evidence_integrity_mismatch", + code: "invalid_request", + category: "invalid_input", + details: { path: recordPath }, message: expect.stringContaining( `this JSON is one Evidence record (${record.evidence_id})`, ), diff --git a/tests/boundary/mcp/evidenceImportCancellation.test.ts b/tests/boundary/mcp/evidenceImportCancellation.test.ts index cb65dc71a..0413e6ec4 100644 --- a/tests/boundary/mcp/evidenceImportCancellation.test.ts +++ b/tests/boundary/mcp/evidenceImportCancellation.test.ts @@ -7,6 +7,7 @@ import { createEvidence } from "../../../src/domain/evidence.js"; import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js"; import { createServer } from "../../../src/server/createServer.js"; import { ToolResultDelivery } from "../../../src/server/toolResult.js"; +import { OwnedFileHandle } from "../../../src/filesystem/OwnedFileHandle.js"; import { createTestBinarySession } from "../../fixtures/binarySession.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; @@ -137,3 +138,121 @@ it("keeps the complete session unchanged after SDK import cancellation and permi ); await client.ping(); }); + +it("retains a failed import close in the server scope through SDK error projection", async () => { + const root = await createTestTempDirectory("rea-mcp-import-close-"); + const path = join(root, "bundle.json"); + const session = createTestBinarySession(() => { + throw new Error("Evidence import must not start a binary provider"); + }); + const provider = { id: "fixture", name: "Fixture", version: "1" }; + const existing = createEvidence(undefined, provider, { + operation: "existing_observation", + parameters: {}, + result: { retained: true }, + }); + const imported = createEvidence(undefined, provider, { + operation: "imported_observation", + parameters: {}, + result: { retained: "close failure" }, + }); + const recorded = session.recordEvidence(existing); + if (!recorded.ok) throw recorded.error; + await writeFile(path, JSON.stringify(createEvidenceBundle([imported]))); + + let allowClose = false; + let retainedOwner: OwnedFileHandle | undefined; + const originalClose = OwnedFileHandle.prototype.close; + const close = vi + .spyOn(OwnedFileHandle.prototype, "close") + .mockImplementation(async function (this: OwnedFileHandle) { + retainedOwner ??= this; + if (!allowClose) throw new Error("persistent file close failure"); + return originalClose.call(this); + }); + + const server = createServer({ kind: "session", session }); + const client = new Client({ + name: "evidence-import-close-failure", + version: "1", + }); + onTestFinished(async () => { + allowClose = true; + close.mockRestore(); + await client.close(); + await server.close(); + await session.close(); + }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + await server.connect(serverTransport); + await client.connect(clientTransport); + const before = session.exportEvidenceBundle(); + + const result = await client.callTool({ + name: "import_evidence_bundle", + arguments: { path }, + }); + expect(result.isError).toBe(true); + expect(session.exportEvidenceBundle()).toEqual(before); + expect(retainedOwner).toBeDefined(); + expect(retainedOwner?.handle.fd).toBeGreaterThanOrEqual(0); + + await client.close(); + await expect(server.close()).rejects.toThrow("REA session cleanup failed"); + expect(retainedOwner?.handle.fd).toBeGreaterThanOrEqual(0); + allowClose = true; + close.mockRestore(); + await server.close(); + expect(retainedOwner?.handle.fd).toBe(-1); + await session.close(); +}); + +it("retries a transient import close failure before admitting the bundle", async () => { + const root = await createTestTempDirectory("rea-mcp-import-close-retry-"); + const path = join(root, "bundle.json"); + const session = createTestBinarySession(() => { + throw new Error("Evidence import must not start a binary provider"); + }); + const imported = createEvidence( + undefined, + { id: "fixture", name: "Fixture", version: "1" }, + { + operation: "imported_observation", + parameters: {}, + result: { retained: "retry succeeded" }, + }, + ); + await writeFile(path, JSON.stringify(createEvidenceBundle([imported]))); + + const originalClose = OwnedFileHandle.prototype.close; + const close = vi + .spyOn(OwnedFileHandle.prototype, "close") + .mockImplementationOnce(async () => { + throw new Error("one transient file close failure"); + }); + const server = createServer({ kind: "session", session }); + const client = new Client({ + name: "evidence-import-close-retry", + version: "1", + }); + onTestFinished(async () => { + close.mockRestore(); + await client.close(); + await server.close(); + await session.close(); + }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + await server.connect(serverTransport); + await client.connect(clientTransport); + + const result = await client.callTool({ + name: "import_evidence_bundle", + arguments: { path }, + }); + close.mockRestore(); + expect(result.isError).not.toBe(true); + expect(session.exportEvidenceBundle().records).toContainEqual(imported); + await client.ping(); +}); diff --git a/tests/support/holdFirstFileRead.ts b/tests/support/holdFirstFileRead.ts new file mode 100644 index 000000000..3d5082891 --- /dev/null +++ b/tests/support/holdFirstFileRead.ts @@ -0,0 +1,55 @@ +import { open, type FileHandle } from "node:fs/promises"; +import { vi } from "vitest"; + +/** Pause after one selected file chunk reaches the operating system. */ +export const holdFirstFileRead = async (path: string) => { + const probe = await open(path, "r"); + const identity = await probe.stat(); + const fileHandlePrototype = Object.getPrototypeOf(probe) as { + read( + buffer: Buffer, + offset: number, + length: number, + position: number | null, + ): Promise<{ readonly bytesRead: number; readonly buffer: Buffer }>; + }; + await probe.close(); + let totalReadBytes = 0; + let readCount = 0; + let resolveFirstRead: (() => void) | undefined; + const firstRead = new Promise((resolve) => { + resolveFirstRead = resolve; + }); + let releaseRead: (() => void) | undefined; + const readGate = new Promise((resolve) => { + releaseRead = resolve; + }); + const read = fileHandlePrototype.read; + vi.spyOn(fileHandlePrototype, "read").mockImplementation(async function ( + this: FileHandle, + ...args: [Buffer, number, number, number | null] + ) { + const current = await this.stat(); + const isTarget = + current.dev === identity.dev && current.ino === identity.ino; + const result = await read.call(this, ...args); + if (!isTarget) return result; + totalReadBytes += result.bytesRead; + readCount += 1; + if (readCount === 1) { + resolveFirstRead?.(); + await readGate; + } + return result; + }); + return { + firstRead, + release: () => releaseRead?.(), + get readCount() { + return readCount; + }, + get totalReadBytes() { + return totalReadBytes; + }, + }; +};