feat(process): introduce evidence-safe capture v4
This commit is contained in:
@@ -99,6 +99,8 @@ export const startCommandShimReplay = async (
|
||||
sequence: events.length,
|
||||
at_ms: Math.max(0, Date.now() - started),
|
||||
command: invocation.command,
|
||||
route_index:
|
||||
routeIndex !== undefined && routeIndex >= 0 ? routeIndex : null,
|
||||
arguments: invocation.arguments,
|
||||
working_directory: invocation.working_directory,
|
||||
outcome,
|
||||
|
||||
@@ -11,6 +11,10 @@ import {
|
||||
} from "../domain/evidenceBundle.js";
|
||||
import { EvidenceFileError, EvidenceIntegrityError } from "../domain/errors.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import {
|
||||
LEGACY_PROCESS_CAPTURE_MESSAGE,
|
||||
parseProcessCapture,
|
||||
} from "../domain/processCapture.js";
|
||||
|
||||
type EvidenceReadFailure = EvidenceFileError | EvidenceIntegrityError;
|
||||
type EvidenceWriteFailure = EvidenceFileError | EvidenceIntegrityError;
|
||||
@@ -42,7 +46,14 @@ export const readEvidenceBundle = async (
|
||||
const limits = validateJsonLimits(decoded, policy);
|
||||
if (!limits.ok) return limits;
|
||||
try {
|
||||
return ok(parseEvidenceBundle(decoded));
|
||||
const bundle = parseEvidenceBundle(decoded);
|
||||
for (const record of bundle.records) {
|
||||
if (record.predicate_type === "rea.process-capture/v3")
|
||||
throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);
|
||||
if (record.predicate_type === "rea.process-capture/v4")
|
||||
parseProcessCapture(record.normalized_result);
|
||||
}
|
||||
return ok(bundle);
|
||||
} catch (cause: unknown) {
|
||||
return err(
|
||||
new EvidenceIntegrityError("Evidence bundle validation failed", {
|
||||
|
||||
@@ -5,8 +5,9 @@ import { createEvidence, parseEvidence } from "../domain/evidence.js";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import {
|
||||
compareProcessCaptures,
|
||||
LEGACY_PROCESS_CAPTURE_MESSAGE,
|
||||
parseProcessScenario,
|
||||
processCaptureSchema,
|
||||
parseProcessCapture,
|
||||
} from "../domain/processCapture.js";
|
||||
import { captureProcessScenario } from "./ProcessHarness.js";
|
||||
import {
|
||||
@@ -38,7 +39,7 @@ export const compareProcessEvidenceFiles = async (
|
||||
const right = parseCaptureEvidence(await readJson(rightPath));
|
||||
const comparison = compareProcessCaptures(left.capture, right.capture);
|
||||
return createEvidence(undefined, PROCESS_PROVIDER, {
|
||||
predicateType: "rea.process-comparison/v2",
|
||||
predicateType: "rea.process-comparison/v3",
|
||||
operation: "compare_process_captures",
|
||||
parameters: {
|
||||
left_evidence_id: left.id,
|
||||
@@ -58,14 +59,17 @@ const parseCaptureEvidence = (input: unknown) => {
|
||||
const evidence = parseEvidence(input);
|
||||
if (
|
||||
evidence.operation !== "capture_process_scenario" ||
|
||||
evidence.predicate_type !== "rea.process-capture/v3" ||
|
||||
evidence.predicate_type !== "rea.process-capture/v4" ||
|
||||
evidence.provider.id !== PROCESS_PROVIDER.id ||
|
||||
evidence.provider.version !== PROCESS_PROVIDER.version
|
||||
)
|
||||
throw new TypeError("Expected REA Process Capture v3 Evidence");
|
||||
) {
|
||||
if (evidence.predicate_type === "rea.process-capture/v3")
|
||||
throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);
|
||||
throw new TypeError("Expected REA Process Capture v4 Evidence");
|
||||
}
|
||||
return {
|
||||
id: evidence.evidence_id,
|
||||
capture: processCaptureSchema.parse(evidence.normalized_result),
|
||||
capture: parseProcessCapture(evidence.normalized_result),
|
||||
};
|
||||
};
|
||||
|
||||
|
||||
@@ -5,12 +5,13 @@ import type {
|
||||
ProcessCapture,
|
||||
ProcessScenario,
|
||||
} from "../domain/processCapture.js";
|
||||
import { parseProcessCapture } from "../domain/processCapture.js";
|
||||
|
||||
/** Provider identity for controlled Process Capture v3 evidence. */
|
||||
/** Provider identity for controlled Process Capture v4 evidence. */
|
||||
export const PROCESS_PROVIDER = {
|
||||
id: "rea-process",
|
||||
name: "REA deterministic process harness",
|
||||
version: "2",
|
||||
version: "3",
|
||||
} as const;
|
||||
|
||||
/** Project one process scenario into secret-free Evidence parameters. */
|
||||
@@ -26,16 +27,17 @@ const processEvidenceParameters = (
|
||||
normalization: scenario.normalization,
|
||||
});
|
||||
|
||||
/** Create one canonical observed Process Capture v3 Evidence record. */
|
||||
/** Create one canonical observed Process Capture v4 Evidence record. */
|
||||
export const createProcessCaptureEvidence = (
|
||||
scenario: ProcessScenario,
|
||||
capture: ProcessCapture,
|
||||
) =>
|
||||
createEvidence(undefined, PROCESS_PROVIDER, {
|
||||
predicateType: "rea.process-capture/v3",
|
||||
) => {
|
||||
const validatedCapture = parseProcessCapture(capture);
|
||||
return createEvidence(undefined, PROCESS_PROVIDER, {
|
||||
predicateType: "rea.process-capture/v4",
|
||||
operation: "capture_process_scenario",
|
||||
parameters: processEvidenceParameters(scenario),
|
||||
result: jsonValueSchema.parse(capture),
|
||||
result: jsonValueSchema.parse(validatedCapture),
|
||||
confidence: "observed",
|
||||
authority: "controlled-replay",
|
||||
environment: {
|
||||
@@ -44,5 +46,6 @@ export const createProcessCaptureEvidence = (
|
||||
architecture: process.arch,
|
||||
isolation: "process",
|
||||
},
|
||||
limitations: capture.limitations,
|
||||
limitations: validatedCapture.limitations,
|
||||
});
|
||||
};
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { createHash, randomUUID } from "node:crypto";
|
||||
import { createReadStream } from "node:fs";
|
||||
import { mkdtemp, realpath, rm } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
@@ -12,11 +13,21 @@ import type {
|
||||
ProcessScenario,
|
||||
TerminalFrame,
|
||||
} from "../domain/processCapture.js";
|
||||
import { authorizeProcessScenario } from "../domain/processCapture.js";
|
||||
import {
|
||||
authorizeProcessScenario,
|
||||
digestProcessCommitment,
|
||||
processComparisonContract,
|
||||
processScenarioCommitment,
|
||||
validateProcessCapture,
|
||||
} from "../domain/processCapture.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import { AnalysisError } from "../domain/errors.js";
|
||||
import { PRODUCT_IDENTITY } from "../identity.js";
|
||||
import { startLoopbackReplay, type LoopbackReplay } from "./LoopbackReplay.js";
|
||||
import { cleanupOwnedProcessGroup } from "./ProcessOwnership.js";
|
||||
import {
|
||||
cleanupOwnedProcessGroup,
|
||||
observeOwnedProcessGroup,
|
||||
} from "./ProcessOwnership.js";
|
||||
import { startProcessSampler } from "./ProcessSampling.js";
|
||||
import { snapshotRoots, type SnapshotResult } from "./FilesystemSnapshot.js";
|
||||
import {
|
||||
@@ -33,6 +44,7 @@ import {
|
||||
normalizeProcessText,
|
||||
redactProtocolEvents,
|
||||
} from "./ProcessNormalization.js";
|
||||
import { PROCESS_PROVIDER } from "./ProcessEvidence.js";
|
||||
|
||||
const isWithin = (candidate: string, root: string): boolean =>
|
||||
candidate === root ||
|
||||
@@ -249,19 +261,31 @@ interface CaptureResultOptions {
|
||||
readonly interactions: readonly InteractionEvent[];
|
||||
readonly checkpoints: readonly FilesystemCheckpoint[];
|
||||
readonly shimEvents: ProcessCapture["shim_events"];
|
||||
readonly settlement: ProcessCapture["settlement"];
|
||||
readonly manifest: ProcessCapture["manifest"];
|
||||
}
|
||||
|
||||
const buildCaptureResult = (options: CaptureResultOptions): ProcessCapture => ({
|
||||
schema_version: 3,
|
||||
schema_version: 4,
|
||||
manifest: options.manifest,
|
||||
normalization: options.scenario.normalization,
|
||||
frames: options.frames,
|
||||
rendered_frames: options.renderedFrames,
|
||||
rendered_frames: [...options.renderedFrames]
|
||||
.sort(
|
||||
(left, right) =>
|
||||
left.at_ms - right.at_ms || left.sequence - right.sequence,
|
||||
)
|
||||
.map((frame, sequence) => ({ ...frame, sequence })),
|
||||
interaction_events: options.interactions,
|
||||
exit: {
|
||||
code: options.exit.exitCode < 0 ? null : options.exit.exitCode,
|
||||
code:
|
||||
options.exit.reason === "exited" && options.exit.exitCode >= 0
|
||||
? options.exit.exitCode
|
||||
: null,
|
||||
signal: options.exit.signal ?? null,
|
||||
reason: options.exit.reason,
|
||||
},
|
||||
settlement: options.settlement,
|
||||
process_samples: normalizeProcessSamples(
|
||||
options.samples,
|
||||
options.scenario,
|
||||
@@ -304,6 +328,78 @@ const buildCaptureResult = (options: CaptureResultOptions): ProcessCapture => ({
|
||||
},
|
||||
});
|
||||
|
||||
const hashFile = async (path: string): Promise<string> => {
|
||||
const hash = createHash("sha256");
|
||||
for await (const chunk of createReadStream(path)) hash.update(chunk);
|
||||
return hash.digest("hex");
|
||||
};
|
||||
|
||||
const createRunManifest = async (
|
||||
scenario: ProcessScenario,
|
||||
startedAt: Date,
|
||||
completedAt: Date,
|
||||
): Promise<ProcessCapture["manifest"]> => {
|
||||
const executableSha256 = await hashFile(scenario.executable);
|
||||
const scenarioCommitment = processScenarioCommitment(
|
||||
scenario,
|
||||
executableSha256,
|
||||
);
|
||||
const comparisonContract = processComparisonContract(scenario);
|
||||
return {
|
||||
rea_version: PRODUCT_IDENTITY.packageVersion,
|
||||
provider_version: PROCESS_PROVIDER.version,
|
||||
platform: process.platform,
|
||||
architecture: process.arch,
|
||||
pty_backend: "node-pty",
|
||||
started_at: startedAt.toISOString(),
|
||||
completed_at: completedAt.toISOString(),
|
||||
scenario: scenarioCommitment,
|
||||
comparison_contract: comparisonContract,
|
||||
shim_plan: scenario.command_shims,
|
||||
replay_plan: scenario.replay,
|
||||
full_scenario_sha256: digestProcessCommitment(scenarioCommitment),
|
||||
comparison_contract_sha256: digestProcessCommitment(comparisonContract),
|
||||
executable_sha256: executableSha256,
|
||||
normalization_sha256: digestProcessCommitment(scenario.normalization),
|
||||
shim_plan_sha256: digestProcessCommitment(scenario.command_shims),
|
||||
replay_plan_sha256: digestProcessCommitment(scenario.replay),
|
||||
};
|
||||
};
|
||||
|
||||
const observeSettlement = async (
|
||||
runId: string,
|
||||
processGroupIds: readonly number[],
|
||||
settleMs: number,
|
||||
): Promise<Omit<ProcessCapture["settlement"], "cleanup_outcome">> => {
|
||||
if (process.platform === "win32")
|
||||
return { state: "unverifiable", elapsed_ms: 0 };
|
||||
const started = Date.now();
|
||||
let consecutiveEmpty = 0;
|
||||
let deadlineReached = false;
|
||||
while (!deadlineReached) {
|
||||
const observations = await Promise.all(
|
||||
[...new Set(processGroupIds)].map((processGroupId) =>
|
||||
observeOwnedProcessGroup({
|
||||
runId,
|
||||
leaderPid: processGroupId,
|
||||
processGroupId,
|
||||
}),
|
||||
),
|
||||
);
|
||||
if (observations.some(({ state }) => state === "unverifiable"))
|
||||
return { state: "unverifiable", elapsed_ms: Date.now() - started };
|
||||
if (observations.every(({ state }) => state === "empty")) {
|
||||
consecutiveEmpty += 1;
|
||||
if (consecutiveEmpty >= 2)
|
||||
return { state: "quiesced", elapsed_ms: Date.now() - started };
|
||||
} else consecutiveEmpty = 0;
|
||||
deadlineReached = Date.now() - started >= settleMs;
|
||||
if (deadlineReached) break;
|
||||
await new Promise<void>((resolve) => setTimeout(resolve, 50));
|
||||
}
|
||||
return { state: "alive_at_deadline", elapsed_ms: Date.now() - started };
|
||||
};
|
||||
|
||||
const awaitTerminalExit = async ({
|
||||
terminal,
|
||||
scenario,
|
||||
@@ -523,6 +619,7 @@ const runProcessScenario = async (
|
||||
let checkpoints: ProcessCheckpoints | undefined;
|
||||
let shimReplay: CommandShimReplay | undefined;
|
||||
let started = 0;
|
||||
let startedAt = new Date(0);
|
||||
let lastOutput = 0;
|
||||
const timers = new Set<NodeJS.Timeout>();
|
||||
let capture: ProcessCapture | undefined;
|
||||
@@ -530,11 +627,16 @@ const runProcessScenario = async (
|
||||
let framesTruncated = (): boolean => false;
|
||||
let stopSampler = async () => ({ partial: false });
|
||||
let samplingPartial = false;
|
||||
let settlement: Omit<ProcessCapture["settlement"], "cleanup_outcome"> = {
|
||||
state: "unverifiable",
|
||||
elapsed_ms: 0,
|
||||
};
|
||||
const interactions: InteractionEvent[] = [];
|
||||
const dispatchedEventIndexes = new Set<number>();
|
||||
|
||||
try {
|
||||
replay = await startLoopbackReplay(scenario);
|
||||
startedAt = new Date();
|
||||
started = Date.now();
|
||||
lastOutput = started;
|
||||
renderer = new TerminalRenderer({
|
||||
@@ -601,8 +703,15 @@ const runProcessScenario = async (
|
||||
checkpoints.trigger("root_exit");
|
||||
if (exitReason === "cancelled")
|
||||
throw new ProcessCaptureError("process capture was cancelled");
|
||||
await new Promise((resolveSettle) =>
|
||||
setTimeout(resolveSettle, scenario.settle_ms),
|
||||
settlement = await observeSettlement(
|
||||
runId,
|
||||
[
|
||||
terminal.pid,
|
||||
...samples.flatMap(({ process_group_id }) =>
|
||||
process_group_id === null ? [] : [process_group_id],
|
||||
),
|
||||
],
|
||||
scenario.settle_ms,
|
||||
);
|
||||
checkpoints.trigger("settled");
|
||||
samplingPartial = (await stopSampler()).partial;
|
||||
@@ -610,6 +719,7 @@ const runProcessScenario = async (
|
||||
const after = await snapshotRoots(scenario, signal);
|
||||
const renderedFrames = await renderer.frames();
|
||||
const filesystemCheckpoints = await checkpoints.finish(after);
|
||||
const manifest = await createRunManifest(scenario, startedAt, new Date());
|
||||
truncated ||=
|
||||
after.truncated ||
|
||||
replay.truncated ||
|
||||
@@ -649,6 +759,8 @@ const runProcessScenario = async (
|
||||
terminal?.pid ?? -1,
|
||||
),
|
||||
})),
|
||||
settlement: { ...settlement, cleanup_outcome: "not_required" },
|
||||
manifest,
|
||||
});
|
||||
} catch (cause: unknown) {
|
||||
terminal?.kill("SIGKILL");
|
||||
@@ -668,6 +780,25 @@ const runProcessScenario = async (
|
||||
process_group_id === null ? [] : [process_group_id],
|
||||
),
|
||||
});
|
||||
if (capture !== undefined) {
|
||||
capture = {
|
||||
...capture,
|
||||
settlement: {
|
||||
...capture.settlement,
|
||||
cleanup_outcome:
|
||||
capture.settlement.state === "quiesced"
|
||||
? "not_required"
|
||||
: cleanupFailure === undefined
|
||||
? "cleaned"
|
||||
: "failed",
|
||||
},
|
||||
};
|
||||
const issues = validateProcessCapture(capture);
|
||||
if (issues.length > 0)
|
||||
executionFailure = new ProcessCaptureError(
|
||||
`process capture validation failed: ${issues[0]!.path}: ${issues[0]!.message}`,
|
||||
);
|
||||
}
|
||||
return resolveProcessResult(capture, executionFailure, cleanupFailure);
|
||||
};
|
||||
|
||||
|
||||
@@ -34,6 +34,12 @@ export type ProcessCleanupResult =
|
||||
| { readonly cleaned: true; readonly signaled: boolean }
|
||||
| { readonly cleaned: false; readonly reason: string };
|
||||
|
||||
/** Token-verified liveness result used by post-root-exit settlement. */
|
||||
export type ProcessGroupObservation =
|
||||
| { readonly state: "empty" }
|
||||
| { readonly state: "alive" }
|
||||
| { readonly state: "unverifiable"; readonly reason: string };
|
||||
|
||||
const parseEnvironment = (value: string): Readonly<Record<string, string>> =>
|
||||
Object.fromEntries(
|
||||
value
|
||||
@@ -146,6 +152,41 @@ export const cleanupOwnedProcessGroup = async (
|
||||
return { cleaned: true, signaled: true };
|
||||
};
|
||||
|
||||
/** Observe one group without signaling it, failing closed on identity doubt. */
|
||||
export const observeOwnedProcessGroup = async (
|
||||
ownership: OwnedProcessGroup,
|
||||
host: ProcessOwnershipHost = systemHost,
|
||||
): Promise<ProcessGroupObservation> => {
|
||||
let members: readonly ProcessGroupMember[];
|
||||
try {
|
||||
members = await host.listMembers(ownership.processGroupId);
|
||||
} catch {
|
||||
return {
|
||||
state: "unverifiable",
|
||||
reason: "process group could not be inspected",
|
||||
};
|
||||
}
|
||||
if (members.length === 0) return { state: "empty" };
|
||||
for (const member of members) {
|
||||
try {
|
||||
if (
|
||||
(await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
|
||||
ownership.runId
|
||||
)
|
||||
return {
|
||||
state: "unverifiable",
|
||||
reason: "process ownership did not match",
|
||||
};
|
||||
} catch {
|
||||
return {
|
||||
state: "unverifiable",
|
||||
reason: "process ownership could not be revalidated",
|
||||
};
|
||||
}
|
||||
}
|
||||
return { state: "alive" };
|
||||
};
|
||||
|
||||
const commandMatches = (actual: string, expected: string): boolean => {
|
||||
const normalizedActual = actual.trim();
|
||||
const normalizedExpected = expected.trim();
|
||||
|
||||
Reference in New Issue
Block a user