import { z } from "zod"; import writeFileAtomic from "write-file-atomic"; import { controlledReplayInputSchema, replayExecutionResultSchema, controlledReplayOutputSchema, replayEvidenceSchema, } from "../domain/javascriptReplay.js"; import { AnalysisCapabilityUnavailableError, AnalysisCancelledError, AnalysisInputError, AnalysisProtocolError, PermissionRequiredError, ReplayPlanStaleError, type AnalysisError, } from "../domain/errors.js"; import { createEvidence } from "../domain/evidence.js"; import { projectInputIssues } from "../domain/inputIssueProjection.js"; import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js"; import { err, ok, type Result } from "../domain/result.js"; import type { ExecutionOptions } from "./AnalysisProvider.js"; import type { PermissionAuthority } from "./PermissionAuthority.js"; import { digestBytes, prepareReplayPlan, type JavaScriptReplayHost, type JavaScriptReplayPolicy, type JavaScriptReplayRunner, } from "./JavaScriptReplayPlanning.js"; const OPERATION = "run_controlled_replay" as const; const isAborted = (signal: AbortSignal | undefined): boolean => signal?.aborted === true; export interface JavaScriptReplayDependencies { readonly policy: JavaScriptReplayPolicy; readonly host: JavaScriptReplayHost; readonly runner: JavaScriptReplayRunner; readonly authority: PermissionAuthority | undefined; } /** Plan or execute one content-bound extracted-module replay experiment. */ export const runControlledReplay = async ( dependencies: JavaScriptReplayDependencies, rawInput: unknown, options: ExecutionOptions = {}, ): Promise> => { const parsed = controlledReplayInputSchema.safeParse(rawInput); if (!parsed.success) return err( new AnalysisInputError( OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput), ), ); return runControlledReplayValidated(dependencies, parsed.data, options); }; /** Plan or execute replay input already parsed by a trusted adapter. */ export const runControlledReplayValidated = async ( dependencies: JavaScriptReplayDependencies, input: z.output, options: ExecutionOptions = {}, ): Promise> => { if (!dependencies.policy.enabled) return err( new AnalysisCapabilityUnavailableError( "rea-javascript-replay", OPERATION, "controlled replay is disabled; configure exact roots and executables before enabling it", ), ); if (dependencies.authority === undefined) return err( new AnalysisCapabilityUnavailableError( "rea-javascript-replay", OPERATION, "JavaScript replay permission policy is not configured", ), ); if (isAborted(options.signal)) return err(new AnalysisCancelledError(OPERATION)); const request = permissionRequest(input, dependencies.policy); const authorized = input.mode === "plan" ? await dependencies.authority.explain(request, "read") : await dependencies.authority.authorize(request, "read"); if (!authorized.ok) return err( authorized.error instanceof PermissionRequiredError ? authorized.error : new AnalysisProtocolError(authorized.error.message, { cause: authorized.error, }), ); let prepared; try { prepared = await prepareReplayPlan( input, dependencies.policy, dependencies.host, ); } catch (cause: unknown) { return err( new AnalysisCapabilityUnavailableError( "rea-javascript-replay", OPERATION, cause instanceof Error ? cause.message : "replay planning failed", ), ); } if (isAborted(options.signal)) return err(new AnalysisCancelledError(OPERATION)); if (input.mode === "plan") return ok( asJson({ phase: "plan", plan: prepared.publicPlan, source_evidence: [], evidence: null, }), ); if (input.plan_digest !== prepared.publicPlan.plan_digest) return err( new ReplayPlanStaleError( input.plan_digest ?? "", prepared.publicPlan.plan_digest, ), ); let canonicalExportPath: string | undefined; if (input.reproducer_export !== undefined) { if (input.reproducer_export.approved !== true) return err(new AnalysisInputError(`${OPERATION}:reproducer_export`)); const exportAuthorized = await dependencies.authority.authorize( { capability: "evidence_write", roots: [input.reproducer_export.path], executables: [], environment_names: [], network: "none", mount: false, operation_identity: `${OPERATION}:reproducer:${prepared.publicPlan.plan_digest}`, }, "write", ); if (!exportAuthorized.ok) return err( exportAuthorized.error instanceof PermissionRequiredError ? exportAuthorized.error : new AnalysisProtocolError(exportAuthorized.error.message, { cause: exportAuthorized.error, }), ); canonicalExportPath = exportAuthorized.value.request.roots[0]; if (canonicalExportPath !== input.reproducer_export.path) return err( new AnalysisInputError(`${OPERATION}:reproducer_export:path`, { cause: new TypeError( `Use the canonical reproducer path: ${canonicalExportPath ?? "unavailable"}`, ), }), ); } if (isAborted(options.signal)) return err(new AnalysisCancelledError(OPERATION)); await options.progress?.report({ phase: OPERATION, completed: 0, total: 1, message: "Admitting approved modules into the isolated replay worker", }); if (isAborted(options.signal)) return err(new AnalysisCancelledError(OPERATION)); try { let executed = replayExecutionResultSchema.parse( await dependencies.runner.execute( prepared, dependencies.policy, options.signal, ), ); await options.progress?.report({ phase: OPERATION, completed: 1, total: 1, message: "Controlled replay stopped and sandbox cleanup was observed", terminal: true, }); if (executed.termination === "cancelled") return err(new AnalysisCancelledError(OPERATION)); if ( input.reproducer_export !== undefined && canonicalExportPath !== undefined && executed.cleanup.state === "complete" ) { const manifest = { schema_version: 1, plan: prepared.publicPlan, result: executed, sources: input.reproducer_export.include_sources ? { left: prepared.leftSources, ...(prepared.rightSources === undefined ? {} : { right: prepared.rightSources }), } : null, }; const encoded = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`); try { await writeFileAtomic(canonicalExportPath, encoded, { mode: 0o600, }); executed = replayExecutionResultSchema.parse({ ...executed, reproducer: { state: "written", path: canonicalExportPath, sha256: digestBytes(encoded), }, }); } catch (cause: unknown) { executed = replayExecutionResultSchema.parse({ ...executed, limitations: [ ...executed.limitations, "Replay completed, but the separately approved reproducer export failed.", ], reproducer: { state: "failed", path: canonicalExportPath, error: cause instanceof Error ? cause.message : "unknown reproducer export failure", }, }); } } const leftCount = prepared.publicPlan.cases.length; const sourceEvidence = [ createReplayEvidence( prepared, executed, "left", executed.outcomes.slice(0, leftCount), ), ...(prepared.publicPlan.right === undefined ? [] : [ createReplayEvidence( prepared, executed, "right", executed.outcomes.slice(leftCount), ), ]), ]; const subject = prepared.publicPlan.left.modules[0]; const evidence = createEvidence( subject === undefined ? undefined : { path: subject.canonical_path, sha256: subject.sha256, format: "javascript", }, { id: "rea-javascript-replay", name: "REA isolated JavaScript replay", version: "1", }, { predicateType: "javascript-controlled-replay", operation: OPERATION, parameters: { replay_plan: jsonValueSchema.parse( JSON.parse(JSON.stringify(prepared.publicPlan)), ), }, result: jsonValueSchema.parse(JSON.parse(JSON.stringify(executed))), rawResult: jsonValueSchema.parse( JSON.parse( JSON.stringify({ cases: prepared.publicPlan.cases, outcomes: executed.outcomes, stderr: executed.stderr, }), ), ), confidence: executed.comparison === undefined ? "observed" : "derived", authority: "controlled-replay", environment: { id: prepared.publicPlan.plan_digest, platform: process.platform, architecture: process.arch, isolation: "container", }, limitations: executed.limitations, locations: prepared.publicPlan.left.modules.map((module) => ({ kind: "artifact-path" as const, path: module.canonical_path, })), evidenceLinks: sourceEvidence.map(({ evidence_id: id }) => id), }, ); return ok( asJson({ phase: "execute", plan: null, source_evidence: sourceEvidence.map((item) => replayEvidenceSchema.parse(item), ), evidence: replayEvidenceSchema.parse(evidence), }), ); } catch (cause: unknown) { return err( new AnalysisProtocolError( cause instanceof z.ZodError ? "Controlled replay produced an invalid bounded result" : "Controlled replay could not establish or clean up its sandbox", { cause }, ), ); } }; const createReplayEvidence = ( prepared: Awaited>, executed: z.infer, side: "left" | "right", outcomes: z.infer["outcomes"], ) => { const manifest = side === "left" ? prepared.publicPlan.left : prepared.publicPlan.right; const subject = manifest?.modules[0]; const result = replayExecutionResultSchema.parse({ ...executed, outcomes, comparison: undefined, reproducer: null, }); return createEvidence( subject === undefined ? undefined : { path: subject.canonical_path, sha256: subject.sha256, format: "javascript", }, { id: "rea-javascript-replay", name: "REA isolated JavaScript replay", version: "1", }, { predicateType: "javascript-controlled-replay-observation", operation: OPERATION, parameters: { replay_plan: jsonValueSchema.parse( JSON.parse(JSON.stringify(prepared.publicPlan)), ), side, }, result: jsonValueSchema.parse(JSON.parse(JSON.stringify(result))), rawResult: jsonValueSchema.parse( JSON.parse( JSON.stringify({ cases: prepared.publicPlan.cases, outcomes }), ), ), confidence: "observed", authority: "controlled-replay", environment: { id: prepared.publicPlan.plan_digest, platform: process.platform, architecture: process.arch, isolation: "container", }, limitations: executed.limitations, locations: (manifest?.modules ?? []).map((module) => ({ kind: "artifact-path" as const, path: module.canonical_path, })), }, ); }; const asJson = (value: unknown): JsonValue => jsonValueSchema.parse( JSON.parse( JSON.stringify(controlledReplayOutputSchema.parse(value)), ) as unknown, ); const permissionRequest = ( input: z.infer, policy: JavaScriptReplayPolicy, ) => ({ capability: "javascript_replay" as const, roots: [...input.left.modules, ...(input.right?.modules ?? [])].map( ({ path }) => path, ), executables: [ policy.nodePath, policy.bubblewrapPath, policy.systemdRunPath, policy.systemctlPath, policy.shellPath, ], environment_names: [], network: "none" as const, mount: true, operation_identity: `${OPERATION}:${input.plan_digest ?? "plan"}`, });