diff --git a/scripts/verify-real-javascript-runtime-observation.mjs b/scripts/verify-real-javascript-runtime-observation.mjs new file mode 100644 index 000000000..4d01f02cc --- /dev/null +++ b/scripts/verify-real-javascript-runtime-observation.mjs @@ -0,0 +1,127 @@ +import { execFile, spawn } from "node:child_process"; +import { once } from "node:events"; +import { realpath } from "node:fs/promises"; +import { dirname, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { promisify } from "node:util"; + +const execute = promisify(execFile); +const root = resolve( + dirname(fileURLToPath(import.meta.url)), + "../tests/conformance/runtime-inspector", +); +const targetPath = resolve(root, "node-target.mjs"); +const canonicalRoot = await realpath(root); +const child = spawn(process.execPath, ["--inspect=127.0.0.1:0", targetPath], { + stdio: ["ignore", "ignore", "pipe"], +}); + +try { + const webSocketUrl = await inspectorUrl(child); + const socket = new URL(webSocketUrl); + const endpoint = `http://127.0.0.1:${socket.port}`; + const environment = { + ...process.env, + REA_V8_INSPECTOR_OBSERVE_ENABLED: "true", + REA_V8_INSPECTOR_ENDPOINTS_JSON: JSON.stringify([endpoint]), + REA_V8_INSPECTOR_FILE_ROOTS_JSON: JSON.stringify([canonicalRoot]), + REA_V8_INSPECTOR_ALLOWED_ORIGINS_JSON: "[]", + }; + const listed = await runCli( + ["list-javascript-runtime-targets", endpoint, "--approved", "--json"], + environment, + ); + const target = listed.normalized_result?.targets?.items?.[0]; + if ( + listed.operation !== "list_javascript_runtime_targets" || + typeof target?.target_id !== "string" || + target.location?.kind !== "file" || + target.location.file_path !== targetPath + ) + throw new Error("Real Node Inspector target discovery did not match"); + const observed = await runCli( + [ + "observe-javascript-runtime", + endpoint, + target.target_id, + "--runtime-kind", + "node", + "--approved", + "--observation-ms", + "100", + "--json", + ], + environment, + ); + const result = observed.normalized_result; + if ( + observed.operation !== "observe_javascript_runtime" || + observed.provider?.id !== "rea-v8-inspector" || + result?.target?.target_id !== target.target_id || + result?.target?.runtime_kind !== "node" || + !Array.isArray(result?.scripts?.items) || + result.scripts.items.length === 0 + ) + throw new Error("Real Node Inspector observation did not match"); + if ( + !Array.isArray(result.directly_observed) || + !Array.isArray(result.unavailable_without_instrumentation) || + result.capture?.truncated !== false + ) + throw new Error("Real Node Inspector capture was incomplete"); + process.stdout.write( + `${JSON.stringify({ + schema_version: 1, + status: "pass", + provider: observed.provider.id, + target_id: target.target_id, + listed_evidence_id: listed.evidence_id, + observation_evidence_id: observed.evidence_id, + scripts: result.scripts.items.length, + contexts: result.execution_contexts.length, + endpoint, + })}\n`, + ); +} finally { + await terminate(child); +} + +async function inspectorUrl(process_) { + let captured = ""; + for await (const chunk of process_.stderr) { + captured += chunk.toString("utf8"); + const match = /Debugger listening on (ws:\/\/[^\s]+)/u.exec(captured); + if (match?.[1] !== undefined) return match[1]; + if (captured.length > 64 * 1_024) + throw new Error("Inspector startup output exceeded its bound"); + } + throw new Error("Node exited before reporting its Inspector URL"); +} + +async function runCli(arguments_, environment) { + const { stdout } = await execute( + process.execPath, + ["scripts/rea.mjs", ...arguments_], + { + cwd: resolve(dirname(fileURLToPath(import.meta.url)), ".."), + env: environment, + maxBuffer: 16 * 1_024 * 1_024, + }, + ); + return JSON.parse(stdout); +} + +async function terminate(process_) { + if (process_.exitCode !== null) return; + const exited = once(process_, "exit"); + process_.kill("SIGTERM"); + const terminated = await Promise.race([ + exited.then(() => true), + new Promise((resolveTimeout) => + setTimeout(() => resolveTimeout(false), 2_000), + ), + ]); + if (terminated || process_.exitCode !== null) return; + process_.kill("SIGKILL"); + await exited; +} diff --git a/src/application/JavaScriptRuntimeObservationEvidence.ts b/src/application/JavaScriptRuntimeObservationEvidence.ts new file mode 100644 index 000000000..4fffdc9a0 --- /dev/null +++ b/src/application/JavaScriptRuntimeObservationEvidence.ts @@ -0,0 +1,60 @@ +import type { ProviderIdentity } from "./AnalysisProvider.js"; +import { + createEvidence, + type Evidence, + type EvidenceObservation, +} from "../domain/evidence.js"; +import { jsonValueSchema } from "../domain/jsonValue.js"; +import type { + JavaScriptRuntimeObservation, + JavaScriptRuntimeTargetList, + ListJavaScriptRuntimeTargetsInput, + ObserveJavaScriptRuntimeInput, +} from "../domain/javascriptRuntimeObservation.js"; + +type RuntimeObservationOperation = + | "list_javascript_runtime_targets" + | "observe_javascript_runtime"; + +/** Create deterministic Evidence v2 for one passive Inspector operation. */ +export const createJavaScriptRuntimeObservationEvidence = ( + operation: RuntimeObservationOperation, + input: ListJavaScriptRuntimeTargetsInput | ObserveJavaScriptRuntimeInput, + result: JavaScriptRuntimeTargetList | JavaScriptRuntimeObservation, + provider: ProviderIdentity, +): Evidence => + createEvidence(undefined, provider, { + predicateType: + operation === "list_javascript_runtime_targets" + ? "rea.javascript-runtime-target-list/v1" + : "rea.javascript-runtime-observation/v1", + operation, + parameters: parameters(input), + result: jsonValueSchema.parse(result), + rawResult: null, + confidence: "observed", + authority: "external-service", + environment: { + id: `${result.runtime.product}@${result.runtime.protocol_version}`, + platform: process.platform, + architecture: process.arch, + isolation: "none", + }, + limitations: result.limitations, + }); + +const parameters = ( + input: ListJavaScriptRuntimeTargetsInput | ObserveJavaScriptRuntimeInput, +): EvidenceObservation["parameters"] => ({ + inspector_endpoint: input.inspector_endpoint, + allowed_file_roots: input.allowed_file_roots, + allowed_origins: input.allowed_origins, + ...("target_id" in input + ? { + target_id: input.target_id, + runtime_kind: input.runtime_kind, + observation_ms: input.observation_ms, + limits: input.limits, + } + : { offset: input.offset, limit: input.limit }), +}); diff --git a/src/application/JavaScriptRuntimeObservationPort.ts b/src/application/JavaScriptRuntimeObservationPort.ts new file mode 100644 index 000000000..7bb3cfec2 --- /dev/null +++ b/src/application/JavaScriptRuntimeObservationPort.ts @@ -0,0 +1,22 @@ +import type { ExecutionOptions, ProviderIdentity } from "./AnalysisProvider.js"; +import type { + JavaScriptRuntimeObservation, + JavaScriptRuntimeTargetList, + ListJavaScriptRuntimeTargetsInput, + ObserveJavaScriptRuntimeInput, +} from "../domain/javascriptRuntimeObservation.js"; +import type { AnalysisError } from "../domain/errors.js"; +import type { Result } from "../domain/result.js"; + +/** Provider-neutral boundary for passive Node/Electron Inspector observation. */ +export interface JavaScriptRuntimeObservationPort { + identity(): ProviderIdentity; + listTargets( + input: ListJavaScriptRuntimeTargetsInput, + options?: ExecutionOptions, + ): Promise>; + observe( + input: ObserveJavaScriptRuntimeInput, + options?: ExecutionOptions, + ): Promise>; +} diff --git a/src/application/JavaScriptRuntimeObservationService.ts b/src/application/JavaScriptRuntimeObservationService.ts new file mode 100644 index 000000000..3deda9155 --- /dev/null +++ b/src/application/JavaScriptRuntimeObservationService.ts @@ -0,0 +1,116 @@ +import type { ExecutionOptions } from "./AnalysisProvider.js"; +import type { JavaScriptRuntimeObservationPort } from "./JavaScriptRuntimeObservationPort.js"; +import type { PermissionAuthority } from "./PermissionAuthority.js"; +import { createJavaScriptRuntimeObservationEvidence } from "./JavaScriptRuntimeObservationEvidence.js"; +import type { Evidence } from "../domain/evidence.js"; +import { + AnalysisCapabilityUnavailableError, + AnalysisProtocolError, + PermissionRequiredError, + type AnalysisError, +} from "../domain/errors.js"; +import type { + ListJavaScriptRuntimeTargetsInput, + ObserveJavaScriptRuntimeInput, +} from "../domain/javascriptRuntimeObservation.js"; +import { err, ok, type Result } from "../domain/result.js"; + +/** Authorize and list attachable Node/Electron Inspector targets. */ +export const listJavaScriptRuntimeTargets = async ( + provider: JavaScriptRuntimeObservationPort | undefined, + authority: PermissionAuthority | undefined, + input: ListJavaScriptRuntimeTargetsInput, + options: ExecutionOptions = {}, +): Promise> => { + const ready = await prepare( + provider, + authority, + input, + "list_javascript_runtime_targets", + ); + if (!ready.ok) return ready; + const result = await ready.value.listTargets(input, options); + return result.ok + ? ok( + createJavaScriptRuntimeObservationEvidence( + "list_javascript_runtime_targets", + input, + result.value, + ready.value.identity(), + ), + ) + : result; +}; + +/** Authorize one bounded attach-only Inspector observation. */ +export const observeJavaScriptRuntime = async ( + provider: JavaScriptRuntimeObservationPort | undefined, + authority: PermissionAuthority | undefined, + input: ObserveJavaScriptRuntimeInput, + options: ExecutionOptions = {}, +): Promise> => { + const ready = await prepare( + provider, + authority, + input, + "observe_javascript_runtime", + ); + if (!ready.ok) return ready; + const result = await ready.value.observe(input, options); + return result.ok + ? ok( + createJavaScriptRuntimeObservationEvidence( + "observe_javascript_runtime", + input, + result.value, + ready.value.identity(), + ), + ) + : result; +}; + +const prepare = async ( + provider: JavaScriptRuntimeObservationPort | undefined, + authority: PermissionAuthority | undefined, + input: ListJavaScriptRuntimeTargetsInput | ObserveJavaScriptRuntimeInput, + operation: "list_javascript_runtime_targets" | "observe_javascript_runtime", +): Promise> => { + if (authority === undefined) + return err( + new AnalysisCapabilityUnavailableError( + "rea-v8-inspector", + operation, + "V8 Inspector observation permission policy is not configured", + ), + ); + const authorized = await authority.authorize( + { + capability: "v8_inspector_observe", + roots: input.allowed_file_roots, + executables: [], + environment_names: [], + origins: [input.inspector_endpoint, ...input.allowed_origins], + network: "loopback", + mount: false, + operation_identity: `${operation}:${"target_id" in input ? input.target_id : input.inspector_endpoint}`, + }, + "read", + ); + if (!authorized.ok) + return err( + authorized.error instanceof PermissionRequiredError + ? authorized.error + : new AnalysisProtocolError(authorized.error.message, { + cause: authorized.error, + }), + ); + return provider === undefined + ? err( + new AnalysisCapabilityUnavailableError( + "rea-v8-inspector", + operation, + "V8 Inspector observation provider is not configured", + ), + ) + : ok(provider); +}; diff --git a/src/browser/JavaScriptRuntimeScope.ts b/src/browser/JavaScriptRuntimeScope.ts new file mode 100644 index 000000000..47c609e4c --- /dev/null +++ b/src/browser/JavaScriptRuntimeScope.ts @@ -0,0 +1,60 @@ +import { + browserOriginSchema, + sanitizeBrowserUrl, +} from "../domain/browserObservation.js"; +import type { JavaScriptRuntimeLocation } from "../domain/javascriptRuntimeObservation.js"; +import { + authorizedElectronFile, + canonicalElectronRoots, +} from "./ElectronFileScope.js"; + +export type RuntimeLocationDecision = + | { readonly allowed: true; readonly location: JavaScriptRuntimeLocation } + | { + readonly allowed: false; + readonly reason: + | "outside_file_roots" + | "outside_origins" + | "unsupported_location"; + }; + +/** Canonicalize exact filesystem scopes before Inspector attachment. */ +export const canonicalRuntimeRoots = canonicalElectronRoots; + +/** Authorize one protocol URL without retaining an out-of-scope value. */ +export const authorizeRuntimeLocation = async ( + value: string, + roots: readonly string[], + origins: readonly string[], +): Promise => { + if (value.startsWith("node:") && value.length <= 4_096) + return { + allowed: true, + location: { kind: "builtin", specifier: value }, + }; + if (value.startsWith("file:")) { + const filePath = await authorizedElectronFile(value, roots); + return filePath === undefined + ? { allowed: false, reason: "outside_file_roots" } + : { allowed: true, location: { kind: "file", file_path: filePath } }; + } + let url: URL; + try { + url = new URL(value); + } catch { + return { allowed: false, reason: "unsupported_location" }; + } + if (!["http:", "https:"].includes(url.protocol)) + return { allowed: false, reason: "unsupported_location" }; + const parsedOrigin = browserOriginSchema.safeParse(url.origin); + if (!parsedOrigin.success || !origins.includes(parsedOrigin.data)) + return { allowed: false, reason: "outside_origins" }; + return { + allowed: true, + location: { + kind: "url", + origin: parsedOrigin.data, + sanitized_url: sanitizeBrowserUrl(value).url, + }, + }; +}; diff --git a/src/browser/V8InspectorCaptureProjection.ts b/src/browser/V8InspectorCaptureProjection.ts new file mode 100644 index 000000000..4ba0cedac --- /dev/null +++ b/src/browser/V8InspectorCaptureProjection.ts @@ -0,0 +1,145 @@ +import { createHash } from "node:crypto"; + +import type { + JavaScriptRuntimeLocation, + JavaScriptRuntimeObservation, + JavaScriptRuntimeTargetList, + ObserveJavaScriptRuntimeInput, +} from "../domain/javascriptRuntimeObservation.js"; +import { authorizeRuntimeLocation } from "./JavaScriptRuntimeScope.js"; +import type { CaptureState, ScriptDraft } from "./V8InspectorProvider.js"; +import type { AuthorizedV8InspectorTarget } from "./V8InspectorEndpoint.js"; + +type ExclusionReason = + | "outside_file_roots" + | "outside_origins" + | "unsupported_location"; + +/** Empty durable-location exclusion counters. */ +export const v8ExclusionCounts = (): Record => ({ + outside_file_roots: 0, + outside_origins: 0, + unsupported_location: 0, +}); + +/** Stable safety and protocol limitations shared by target-list Evidence. */ +export const v8TargetLimitations = (): string[] => [ + "REA attaches to an already-running exact target and never launches, resumes, evaluates, pauses, or mutates it.", + "Only Runtime.enable and Debugger.enable are sent; source text, object values, EventEmitter activity, and Electron IPC are not inspected.", + "Target IDs and locations are authorized, but the Inspector protocol does not authenticate an operating-system process ID or Electron role.", + "No runtime graph depth is traversed because passive Inspector events do not establish require/import caller edges.", +]; + +interface FinalizeCaptureInput { + readonly input: ObserveJavaScriptRuntimeInput; + readonly runtime: JavaScriptRuntimeTargetList["runtime"]; + readonly target: AuthorizedV8InspectorTarget; + readonly roots: readonly string[]; + readonly state: CaptureState; +} + +/** Canonically authorize, deduplicate, and sort one bounded raw capture. */ +export const finalizeV8InspectorCapture = async ({ + input, + runtime, + target, + roots, + state, +}: FinalizeCaptureInput): Promise => { + const exclusions = v8ExclusionCounts(); + const scripts = new Map< + string, + JavaScriptRuntimeObservation["scripts"]["items"][number] + >(); + for (const draft of state.scripts) { + const decision = await authorizeRuntimeLocation( + draft.rawUrl, + roots, + input.allowed_origins, + ); + if (!decision.allowed) { + exclusions[decision.reason] += 1; + continue; + } + const script = scriptFromDraft(draft, decision.location); + scripts.set(script.script_key, script); + } + const items = [...scripts.values()].sort((left, right) => + left.script_key.localeCompare(right.script_key), + ); + const contexts = [...state.contexts.values()] + .map((context) => ({ + context_key: context.contextKey, + state: context.state, + name: null, + origin: context.origin, + })) + .sort((left, right) => left.context_key.localeCompare(right.context_key)); + return { + schema_version: 1, + runtime, + target: { + target_id: target.id, + protocol_type: target.type, + attached: target.attached, + location: target.location, + runtime_kind: input.runtime_kind, + runtime_kind_authority: "caller-declared-unverified", + }, + capture: { + observation_ms: input.observation_ms, + events_observed: state.eventsObserved, + events_retained: state.eventsRetained, + events_dropped: state.eventsDropped, + metadata_bytes_retained: state.metadataBytes, + truncated: state.truncated, + truncation_reasons: [...state.truncationReasons].sort(), + }, + scripts: { + items, + observed_total: state.scriptsObserved, + excluded: { + ...exclusions, + invalid_protocol_value: state.invalidScripts, + }, + }, + execution_contexts: contexts, + directly_observed: [ + "Debugger.scriptParsed established script presence within the bounded capture window.", + "Runtime execution-context lifecycle events established context creation, destruction, or clearing.", + ], + unavailable_without_instrumentation: [ + "require/import caller-to-callee edges", + "EventEmitter emissions and listener invocation", + "Electron IPC messages and handlers", + "script unload events", + ], + unknowns: [ + "Scripts collected before attachment may have been garbage-collected and therefore omitted.", + "A bounded observation window cannot establish that an unobserved script or behavior never occurs.", + "The declared Node/Electron process role is not authenticated by the Inspector protocol.", + ], + limitations: v8TargetLimitations(), + }; +}; + +const scriptFromDraft = ( + draft: ScriptDraft, + location: JavaScriptRuntimeLocation, +): JavaScriptRuntimeObservation["scripts"]["items"][number] => { + const stable = JSON.stringify({ + location, + cdp_hash: draft.cdpHash, + length: draft.length, + is_module: draft.isModule, + }); + return { + script_key: `v8_script_${createHash("sha256").update(stable).digest("hex")}`, + location, + execution_context_key: draft.executionContextKey, + cdp_hash: draft.cdpHash, + length: draft.length, + is_module: draft.isModule, + status: "observed-loaded", + }; +}; diff --git a/src/browser/V8InspectorEndpoint.ts b/src/browser/V8InspectorEndpoint.ts new file mode 100644 index 000000000..cb63b0c17 --- /dev/null +++ b/src/browser/V8InspectorEndpoint.ts @@ -0,0 +1,141 @@ +import { z } from "zod"; + +import type { + JavaScriptRuntimeTargetList, + JavaScriptRuntimeLocation, +} from "../domain/javascriptRuntimeObservation.js"; +import { + BrowserObservationError, + type BrowserObservationOperation, +} from "../domain/errors.js"; +import { readBoundedCdpJson } from "./CdpEndpoint.js"; + +const MAX_VERSION_BYTES = 64 * 1_024; +const MAX_TARGET_LIST_BYTES = 2 * 1_024 * 1_024; + +const versionSchema = z + .object({ + Browser: z.string().min(1).max(1_024), + "Protocol-Version": z.string().min(1).max(100), + "V8-Version": z.string().max(1_024).optional(), + }) + .passthrough(); + +const targetSchema = z + .object({ + id: z.string().min(1).max(256), + type: z.string().min(1).max(100), + url: z.string().max(65_536), + attached: z.boolean().default(false), + webSocketDebuggerUrl: z.string().min(1).max(2_048), + }) + .passthrough(); +const targetsSchema = z.array(targetSchema).max(1_000); + +export interface V8InspectorTarget { + readonly id: string; + readonly type: string; + readonly url: string; + readonly attached: boolean; + readonly webSocketUrl: string; +} + +export interface V8InspectorDiscovery { + readonly runtime: JavaScriptRuntimeTargetList["runtime"]; + readonly targets: readonly V8InspectorTarget[]; +} + +/** Discover bounded Node/Electron Inspector targets from one loopback endpoint. */ +export const discoverV8Inspector = async ( + endpoint: string, + operation: BrowserObservationOperation, + signal?: AbortSignal, +): Promise => { + const [versionInput, targetsInput] = await Promise.all([ + readBoundedCdpJson( + new URL("/json/version", endpoint), + MAX_VERSION_BYTES, + operation, + signal, + ), + readBoundedCdpJson( + new URL("/json/list", endpoint), + MAX_TARGET_LIST_BYTES, + operation, + signal, + ), + ]); + const version = parse(versionSchema, versionInput, operation); + const targets = parse(targetsSchema, targetsInput, operation); + return { + runtime: { + product: version.Browser, + protocol_version: version["Protocol-Version"], + v8_version: version["V8-Version"] ?? null, + }, + targets: targets.map((target) => ({ + id: target.id, + type: target.type, + url: target.url, + attached: target.attached, + webSocketUrl: validatedInspectorWebSocket( + endpoint, + target.id, + target.webSocketDebuggerUrl, + operation, + ), + })), + }; +}; + +const parse = ( + schema: z.ZodType, + input: unknown, + operation: BrowserObservationOperation, +): Output => { + const parsed = schema.safeParse(input); + if (!parsed.success) + throw new BrowserObservationError(operation, "invalid_endpoint_response", { + cause: parsed.error, + }); + return parsed.data; +}; + +const validatedInspectorWebSocket = ( + endpoint: string, + targetId: string, + reported: string, + operation: BrowserObservationOperation, +): string => { + let socket: URL; + try { + socket = new URL(reported); + } catch (cause: unknown) { + throw new BrowserObservationError(operation, "invalid_endpoint_response", { + cause, + }); + } + const trusted = new URL(endpoint); + const allowedPaths = new Set([ + `/${targetId}`, + `/devtools/node/${targetId}`, + `/devtools/page/${targetId}`, + ]); + if ( + socket.protocol !== "ws:" || + socket.port !== trusted.port || + socket.username !== "" || + socket.password !== "" || + socket.search !== "" || + socket.hash !== "" || + !allowedPaths.has(socket.pathname) + ) + throw new BrowserObservationError(operation, "invalid_endpoint_response"); + socket.hostname = trusted.hostname; + return socket.href; +}; + +/** Authorized target plus its durable location. */ +export interface AuthorizedV8InspectorTarget extends V8InspectorTarget { + readonly location: JavaScriptRuntimeLocation; +} diff --git a/src/browser/V8InspectorProvider.ts b/src/browser/V8InspectorProvider.ts new file mode 100644 index 000000000..815938006 --- /dev/null +++ b/src/browser/V8InspectorProvider.ts @@ -0,0 +1,437 @@ +import type { + ExecutionOptions, + ProviderIdentity, +} from "../application/AnalysisProvider.js"; +import type { JavaScriptRuntimeObservationPort } from "../application/JavaScriptRuntimeObservationPort.js"; +import { + javascriptRuntimeObservationSchema, + javascriptRuntimeTargetListSchema, + type JavaScriptRuntimeObservation, + type JavaScriptRuntimeTargetList, + type ListJavaScriptRuntimeTargetsInput, + type ObserveJavaScriptRuntimeInput, +} from "../domain/javascriptRuntimeObservation.js"; +import { + AnalysisError, + BrowserObservationError, + ProviderAdapterError, + type BrowserObservationOperation, +} from "../domain/errors.js"; +import { err, ok, type Result } from "../domain/result.js"; +import { + boundedText, + numberValue, + recordValue, + stringValue, + delayWithCancellation, +} from "./CdpCaptureValues.js"; +import { CdpConnection, type CdpEvent } from "./CdpConnection.js"; +import { + authorizeRuntimeLocation, + canonicalRuntimeRoots, +} from "./JavaScriptRuntimeScope.js"; +import { + finalizeV8InspectorCapture, + v8ExclusionCounts, + v8TargetLimitations, +} from "./V8InspectorCaptureProjection.js"; +import { + discoverV8Inspector, + type AuthorizedV8InspectorTarget, + type V8InspectorTarget, +} from "./V8InspectorEndpoint.js"; + +/** Public identity committed by passive V8 Inspector observations. */ +export const V8_INSPECTOR_PROVIDER_IDENTITY: ProviderIdentity = Object.freeze({ + id: "rea-v8-inspector", + name: "REA passive Node/Electron V8 Inspector provider", + version: "1", +}); + +export interface ScriptDraft { + readonly rawUrl: string; + readonly executionContextKey: string | null; + readonly cdpHash: string | null; + readonly length: number; + readonly isModule: boolean; +} + +export interface ContextDraft { + readonly contextKey: string; + state: "created" | "destroyed" | "cleared"; + readonly origin: string | null; +} + +export interface CaptureState { + readonly scripts: ScriptDraft[]; + readonly contexts: Map; + eventsObserved: number; + eventsRetained: number; + eventsDropped: number; + metadataBytes: number; + scriptsObserved: number; + invalidScripts: number; + truncated: boolean; + readonly truncationReasons: Set; +} + +/** Attach-only provider; sends only Runtime.enable and Debugger.enable. */ +export class V8InspectorProvider implements JavaScriptRuntimeObservationPort { + identity(): ProviderIdentity { + return V8_INSPECTOR_PROVIDER_IDENTITY; + } + + async listTargets( + input: ListJavaScriptRuntimeTargetsInput, + options: ExecutionOptions = {}, + ): Promise> { + try { + const roots = await canonicalRuntimeRoots(input.allowed_file_roots); + const discovery = await discoverV8Inspector( + input.inspector_endpoint, + "list_javascript_runtime_targets", + options.signal, + ); + const allowed: AuthorizedV8InspectorTarget[] = []; + const excluded = v8ExclusionCounts(); + for (const target of discovery.targets) { + const decision = await authorizeRuntimeLocation( + target.url, + roots, + input.allowed_origins, + ); + if (!decision.allowed) { + excluded[decision.reason] += 1; + continue; + } + if (decision.location.kind === "builtin") { + excluded.unsupported_location += 1; + continue; + } + allowed.push({ ...target, location: decision.location }); + } + allowed.sort((left, right) => left.id.localeCompare(right.id)); + const items = allowed + .slice(input.offset, input.offset + input.limit) + .map(projectTarget); + const nextOffset = input.offset + items.length; + return ok( + javascriptRuntimeTargetListSchema.parse({ + schema_version: 1, + runtime: discovery.runtime, + targets: { + items, + offset: input.offset, + limit: input.limit, + total: allowed.length, + next_offset: nextOffset < allowed.length ? nextOffset : null, + has_more: nextOffset < allowed.length, + }, + excluded: { ...excluded, unconnectable: 0 }, + limitations: v8TargetLimitations(), + }), + ); + } catch (cause: unknown) { + return err(providerError(cause, "list_javascript_runtime_targets")); + } + } + + async observe( + input: ObserveJavaScriptRuntimeInput, + options: ExecutionOptions = {}, + ): Promise> { + let connection: CdpConnection | undefined; + try { + const roots = await canonicalRuntimeRoots(input.allowed_file_roots); + const discovery = await discoverV8Inspector( + input.inspector_endpoint, + "observe_javascript_runtime", + options.signal, + ); + const target = await authorizedTarget(discovery.targets, input, roots); + assertRuntimeKind(target, input.runtime_kind); + connection = await CdpConnection.connect( + target.webSocketUrl, + "observe_javascript_runtime", + options.signal, + ); + const state = emptyCaptureState(); + const removeListener = connection.onEvent((event) => + ingestEvent(event, input, state), + ); + try { + await connection.send("Runtime.enable", {}, undefined, options.signal); + await connection.send("Debugger.enable", {}, undefined, options.signal); + await waitForCapture(connection, input.observation_ms, options.signal); + } finally { + removeListener(); + } + const result = await finalizeV8InspectorCapture({ + input, + runtime: discovery.runtime, + target, + roots, + state, + }); + return ok(javascriptRuntimeObservationSchema.parse(result)); + } catch (cause: unknown) { + return err(providerError(cause, "observe_javascript_runtime")); + } finally { + await connection?.close(); + } + } +} + +const projectTarget = (target: AuthorizedV8InspectorTarget) => ({ + target_id: target.id, + protocol_type: target.type, + attached: target.attached, + location: target.location, +}); + +const authorizedTarget = async ( + targets: readonly V8InspectorTarget[], + input: ObserveJavaScriptRuntimeInput, + roots: readonly string[], +): Promise => { + const target = targets.find(({ id }) => id === input.target_id); + if (target === undefined) + throw new BrowserObservationError( + "observe_javascript_runtime", + "target_not_found", + ); + const decision = await authorizeRuntimeLocation( + target.url, + roots, + input.allowed_origins, + ); + if ( + target.attached || + !decision.allowed || + decision.location.kind === "builtin" + ) + throw new BrowserObservationError( + "observe_javascript_runtime", + "target_not_allowed", + ); + return { ...target, location: decision.location }; +}; + +const assertRuntimeKind = ( + target: AuthorizedV8InspectorTarget, + kind: ObserveJavaScriptRuntimeInput["runtime_kind"], +): void => { + const accepted = + kind === "electron-preload" || kind === "electron-renderer" + ? target.type === "page" + : target.type === "node"; + if (!accepted) + throw new BrowserObservationError( + "observe_javascript_runtime", + "target_not_allowed", + ); +}; + +const emptyCaptureState = (): CaptureState => ({ + scripts: [], + contexts: new Map(), + eventsObserved: 0, + eventsRetained: 0, + eventsDropped: 0, + metadataBytes: 0, + scriptsObserved: 0, + invalidScripts: 0, + truncated: false, + truncationReasons: new Set(), +}); + +const ingestEvent = ( + event: CdpEvent, + input: ObserveJavaScriptRuntimeInput, + state: CaptureState, +): void => { + if ( + event.method !== "Debugger.scriptParsed" && + event.method !== "Debugger.scriptFailedToParse" && + event.method !== "Runtime.executionContextCreated" && + event.method !== "Runtime.executionContextDestroyed" && + event.method !== "Runtime.executionContextsCleared" + ) + return; + state.eventsObserved += 1; + if (state.eventsObserved > input.limits.max_events) { + drop(state, "max_events"); + return; + } + if (event.method === "Debugger.scriptParsed") { + ingestScript(event, input, state); + return; + } + if (event.method === "Debugger.scriptFailedToParse") { + state.invalidScripts += 1; + retainEvent(state, 0, input); + return; + } + ingestContext(event, input, state); +}; + +const ingestScript = ( + event: CdpEvent, + input: ObserveJavaScriptRuntimeInput, + state: CaptureState, +): void => { + state.scriptsObserved += 1; + const value = recordValue(event.params); + const rawUrl = stringValue(value?.url); + if ( + rawUrl === undefined || + rawUrl === "" || + Buffer.byteLength(rawUrl) > input.limits.max_location_bytes + ) { + state.invalidScripts += 1; + retainEvent(state, 0, input); + return; + } + if (state.scripts.length >= input.limits.max_scripts) { + drop(state, "max_scripts"); + return; + } + const draft: ScriptDraft = { + rawUrl, + executionContextKey: contextKey(value?.executionContextId), + cdpHash: boundedText(value?.hash, 512), + length: nonnegativeInteger(value?.length), + isModule: value?.isModule === true, + }; + const bytes = metadataBytes(draft); + if (!retainEvent(state, bytes, input)) return; + state.scripts.push(draft); +}; + +const ingestContext = ( + event: CdpEvent, + input: ObserveJavaScriptRuntimeInput, + state: CaptureState, +): void => { + if (event.method === "Runtime.executionContextsCleared") { + for (const context of state.contexts.values()) context.state = "cleared"; + retainEvent(state, 0, input); + return; + } + const parameters = recordValue(event.params); + const runtimeContext = + event.method === "Runtime.executionContextCreated" + ? recordValue(parameters?.context) + : parameters; + const key = contextKey( + event.method === "Runtime.executionContextCreated" + ? runtimeContext?.id + : runtimeContext?.executionContextId, + ); + if (key === null) { + retainEvent(state, 0, input); + return; + } + if ( + state.contexts.size >= input.limits.max_execution_contexts && + !state.contexts.has(key) + ) { + drop(state, "max_execution_contexts"); + return; + } + const origin = + event.method === "Runtime.executionContextCreated" + ? boundedText(runtimeContext?.origin, 4_096) + : null; + const draft: ContextDraft = { + contextKey: key, + state: + event.method === "Runtime.executionContextCreated" + ? "created" + : "destroyed", + origin: + origin !== null && input.allowed_origins.includes(origin) ? origin : null, + }; + const bytes = metadataBytes(draft); + if (!retainEvent(state, bytes, input)) return; + state.contexts.set(key, draft); +}; + +const retainEvent = ( + state: CaptureState, + bytes: number, + input: ObserveJavaScriptRuntimeInput, +): boolean => { + if (state.metadataBytes + bytes > input.limits.max_total_metadata_bytes) { + drop(state, "max_total_metadata_bytes"); + return false; + } + state.metadataBytes += bytes; + state.eventsRetained += 1; + return true; +}; + +const drop = (state: CaptureState, reason: string): void => { + state.eventsDropped += 1; + state.truncated = true; + state.truncationReasons.add(reason); +}; + +const waitForCapture = async ( + connection: CdpConnection, + observationMs: number, + signal?: AbortSignal, +): Promise => { + let removeDisconnect = (): void => undefined; + const disconnected = new Promise((_resolve, reject) => { + removeDisconnect = connection.onDisconnect(() => + reject( + new BrowserObservationError( + "observe_javascript_runtime", + "disconnected", + ), + ), + ); + }); + try { + await Promise.race([ + delayWithCancellation( + observationMs, + "observe_javascript_runtime", + signal, + ), + disconnected, + ]); + } finally { + removeDisconnect(); + } +}; + +const metadataBytes = (value: object): number => + Buffer.byteLength(JSON.stringify(value)); + +const nonnegativeInteger = (value: unknown): number => { + const parsed = numberValue(value); + return parsed === undefined ? 0 : Math.max(0, Math.trunc(parsed)); +}; + +const contextKey = (value: unknown): string | null => { + const identifier = numberValue(value); + return identifier !== undefined && Number.isSafeInteger(identifier) + ? String(identifier) + : null; +}; + +const providerError = ( + cause: unknown, + operation: BrowserObservationOperation, +): AnalysisError => { + if (cause instanceof AnalysisError) return cause; + return new ProviderAdapterError( + V8_INSPECTOR_PROVIDER_IDENTITY.id, + operation, + { + cause, + }, + ); +}; diff --git a/src/cliJavaScriptRuntimeCommands.ts b/src/cliJavaScriptRuntimeCommands.ts new file mode 100644 index 000000000..032dee226 --- /dev/null +++ b/src/cliJavaScriptRuntimeCommands.ts @@ -0,0 +1,204 @@ +import { Cli, z } from "incur"; + +import { + listJavaScriptRuntimeTargets, + observeJavaScriptRuntime, +} from "./application/JavaScriptRuntimeObservationService.js"; +import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js"; +import { V8InspectorProvider } from "./browser/V8InspectorProvider.js"; +import { CLI_COMMANDS } from "./cliCommandNames.js"; +import { logCliCommand } from "./cliLogging.js"; +import { parseConfig } from "./config.js"; +import { + javascriptRuntimeKindSchema, + listJavaScriptRuntimeTargetsInputSchema, + observeJavaScriptRuntimeInputSchema, +} from "./domain/javascriptRuntimeObservation.js"; +import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js"; +import type { JsonValue } from "./domain/jsonValue.js"; +import type { Logger } from "./logger.js"; + +const scopeOptions = { + allowedFileRoots: z + .array(z.string().min(1)) + .optional() + .describe("Exact roots; defaults to REA_V8_INSPECTOR_FILE_ROOTS_JSON"), + allowedOrigins: z + .array(z.string().min(1)) + .optional() + .describe( + "Exact origins; defaults to REA_V8_INSPECTOR_ALLOWED_ORIGINS_JSON", + ), + approved: z.boolean().default(false).describe("Approve passive attachment"), +}; + +const listOptionsSchema = z.object({ + ...scopeOptions, + offset: z + .number() + .int() + .min(0) + .default(0) + .describe("Zero-based target offset"), + limit: z + .number() + .int() + .min(1) + .max(200) + .default(100) + .describe("Maximum targets to return"), +}); + +const observeOptionsSchema = z.object({ + ...scopeOptions, + runtimeKind: javascriptRuntimeKindSchema.describe( + "Declared target role; Inspector cannot authenticate the Electron role", + ), + observationMs: z + .number() + .int() + .min(0) + .max(10_000) + .default(100) + .describe("Bounded observation window in milliseconds"), + maxEvents: z + .number() + .int() + .min(1) + .max(50_000) + .default(10_000) + .describe("Maximum retained protocol events"), + maxScripts: z + .number() + .int() + .min(1) + .max(10_000) + .default(2_000) + .describe("Maximum retained scripts"), + maxExecutionContexts: z + .number() + .int() + .min(1) + .max(5_000) + .default(1_000) + .describe("Maximum retained execution contexts"), + maxLocationBytes: z + .number() + .int() + .min(64) + .max(65_536) + .default(16_384) + .describe("Maximum bytes in one protocol location"), + maxTotalMetadataBytes: z + .number() + .int() + .min(1_024) + .max(32 * 1_024 * 1_024) + .default(4 * 1_024 * 1_024) + .describe("Maximum retained metadata bytes"), +}); + +/** Register CLI equivalents of passive V8 Inspector tools. */ +export const registerJavaScriptRuntimeObservationCommands = ( + cli: ReturnType, + logger: Logger, +): void => { + cli.command(CLI_COMMANDS.listJavaScriptRuntimeTargets, { + description: "List approved Node/Electron V8 Inspector targets", + args: z.object({ + endpoint: z.string().describe("Configured literal-loopback endpoint"), + }), + options: listOptionsSchema, + run: ({ args, options }) => + logCliCommand( + logger, + CLI_COMMANDS.listJavaScriptRuntimeTargets, + async () => { + const context = await runtimeContext(); + if (!context.ok) return context.error; + const parsed = listJavaScriptRuntimeTargetsInputSchema.safeParse({ + inspector_endpoint: args.endpoint, + allowed_file_roots: + options.allowedFileRoots ?? context.allowedFileRoots, + allowed_origins: options.allowedOrigins ?? context.allowedOrigins, + approved: options.approved, + offset: options.offset, + limit: options.limit, + }); + if (!parsed.success) + return inputError("list_javascript_runtime_targets"); + const result = await listJavaScriptRuntimeTargets( + context.provider, + context.authority, + parsed.data, + ); + return result.ok ? result.value : cliError(result.error); + }, + ), + }); + + cli.command(CLI_COMMANDS.observeJavaScriptRuntime, { + description: "Passively observe one exact Node/Electron Inspector target", + args: z.object({ + endpoint: z.string().describe("Configured literal-loopback endpoint"), + targetId: z + .string() + .describe("Target from list-javascript-runtime-targets"), + }), + options: observeOptionsSchema, + run: ({ args, options }) => + logCliCommand(logger, CLI_COMMANDS.observeJavaScriptRuntime, async () => { + const context = await runtimeContext(); + if (!context.ok) return context.error; + const parsed = observeJavaScriptRuntimeInputSchema.safeParse({ + inspector_endpoint: args.endpoint, + allowed_file_roots: + options.allowedFileRoots ?? context.allowedFileRoots, + allowed_origins: options.allowedOrigins ?? context.allowedOrigins, + target_id: args.targetId, + runtime_kind: options.runtimeKind, + approved: options.approved, + observation_ms: options.observationMs, + limits: { + max_events: options.maxEvents, + max_scripts: options.maxScripts, + max_execution_contexts: options.maxExecutionContexts, + max_location_bytes: options.maxLocationBytes, + max_total_metadata_bytes: options.maxTotalMetadataBytes, + }, + }); + if (!parsed.success) return inputError("observe_javascript_runtime"); + const result = await observeJavaScriptRuntime( + context.provider, + context.authority, + parsed.data, + ); + return result.ok ? result.value : cliError(result.error); + }), + }); +}; + +const runtimeContext = async () => { + const config = parseConfig(process.env); + if (!config.ok) return { ok: false as const, error: cliError(config.error) }; + const authority = await loadConfiguredPermissionAuthority(config.value); + if (!authority.ok) + return { ok: false as const, error: cliError(authority.error) }; + return { + ok: true as const, + authority: authority.value, + provider: new V8InspectorProvider(), + allowedFileRoots: config.value.v8InspectorFileRoots, + allowedOrigins: config.value.v8InspectorAllowedOrigins, + }; +}; + +const inputError = (operation: string): JsonValue => + cliError(new AnalysisInputError(operation)); + +const cliError = ( + error: Parameters[0], +): JsonValue => ({ + error: "JavaScript runtime observation failed", + ...projectAnalysisError(error), +}); diff --git a/src/contracts/javascriptRuntimeObservationToolContracts.ts b/src/contracts/javascriptRuntimeObservationToolContracts.ts new file mode 100644 index 000000000..43e10d12f --- /dev/null +++ b/src/contracts/javascriptRuntimeObservationToolContracts.ts @@ -0,0 +1,68 @@ +import type { ToolContract } from "./toolContracts.js"; +import { toolContractMetadata } from "./toolEffects.js"; +import { evidenceResultOf } from "./toolOutputSchemas.js"; +import { + javascriptRuntimeObservationSchema, + javascriptRuntimeTargetListSchema, + listJavaScriptRuntimeTargetsInputSchema, + observeJavaScriptRuntimeInputSchema, +} from "../domain/javascriptRuntimeObservation.js"; + +const root = "/opt/example-app"; +const endpoint = "http://127.0.0.1:9229"; + +/** Passive Node/Electron V8 Inspector discovery and observation contracts. */ +export const JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS = [ + { + name: "list_javascript_runtime_targets", + ...toolContractMetadata("list_javascript_runtime_targets"), + description: + "List attachable Node/Electron V8 Inspector targets from one approved literal-loopback endpoint. Only targets inside exact canonical file roots or exact HTTP(S) origins are retained; excluded target locations never enter Evidence.", + kind: "runtime-provider", + inputSchema: listJavaScriptRuntimeTargetsInputSchema, + outputSchema: evidenceResultOf(javascriptRuntimeTargetListSchema), + examples: [ + { + title: "List approved Node Inspector targets", + input: { + inspector_endpoint: endpoint, + allowed_file_roots: [root], + allowed_origins: [], + approved: true, + offset: 0, + limit: 100, + }, + }, + ], + }, + { + name: "observe_javascript_runtime", + ...toolContractMetadata("observe_javascript_runtime"), + description: + "Attach passively to one exact approved Node/Electron V8 Inspector target and capture bounded Debugger.scriptParsed plus Runtime execution-context events. REA sends only Runtime.enable and Debugger.enable: it never evaluates, pauses, resumes, reads source, or instruments the target. require/import edges, EventEmitter activity, and Electron IPC remain explicit unknowns; reconcile the returned Evidence with static Application Graph Evidence using reconcile_javascript_runtime.", + kind: "runtime-provider", + inputSchema: observeJavaScriptRuntimeInputSchema, + outputSchema: evidenceResultOf(javascriptRuntimeObservationSchema), + examples: [ + { + title: "Observe one approved Node runtime", + input: { + inspector_endpoint: endpoint, + allowed_file_roots: [root], + allowed_origins: [], + target_id: "TARGET_ID_FROM_LIST_JAVASCRIPT_RUNTIME_TARGETS", + runtime_kind: "node", + approved: true, + observation_ms: 100, + limits: { + max_events: 10_000, + max_scripts: 2_000, + max_execution_contexts: 1_000, + max_location_bytes: 16_384, + max_total_metadata_bytes: 4_194_304, + }, + }, + }, + ], + }, +] as const satisfies readonly ToolContract[]; diff --git a/src/domain/javascriptRuntimeObservation.ts b/src/domain/javascriptRuntimeObservation.ts new file mode 100644 index 000000000..2f3f82f98 --- /dev/null +++ b/src/domain/javascriptRuntimeObservation.ts @@ -0,0 +1,216 @@ +import { isAbsolute, resolve } from "node:path"; + +import { z } from "zod"; + +import { + browserEndpointSchema, + browserOriginSchema, +} from "./browserObservation.js"; + +const boundedTextSchema = z.string().min(1).max(4_096); + +const runtimeFileRootsSchema = z + .array( + z + .string() + .min(1) + .max(16_384) + .refine(isAbsolute, "Runtime file roots must be absolute paths") + .overwrite(resolve), + ) + .max(32) + .overwrite((roots) => [...new Set(roots)].sort()) + .default([]); + +const runtimeOriginsSchema = z + .array(browserOriginSchema) + .max(32) + .overwrite((origins) => [...new Set(origins)].sort()) + .default([]); + +const approvedRuntimeScope = { + inspector_endpoint: browserEndpointSchema, + allowed_file_roots: runtimeFileRootsSchema, + allowed_origins: runtimeOriginsSchema, + approved: z.literal(true), +}; + +const requireRuntimeScope = ( + input: { + readonly allowed_file_roots: readonly string[]; + readonly allowed_origins: readonly string[]; + }, + context: z.RefinementCtx, +): void => { + if ( + input.allowed_file_roots.length === 0 && + input.allowed_origins.length === 0 + ) + context.addIssue({ + code: "custom", + path: ["allowed_file_roots"], + message: "At least one exact file root or HTTP(S) origin is required", + }); +}; + +/** Input for listing approved Node/Electron V8 Inspector targets. */ +export const listJavaScriptRuntimeTargetsInputSchema = z + .strictObject({ + ...approvedRuntimeScope, + offset: z.number().int().min(0).default(0), + limit: z.number().int().min(1).max(200).default(100), + }) + .superRefine(requireRuntimeScope); +export type ListJavaScriptRuntimeTargetsInput = z.infer< + typeof listJavaScriptRuntimeTargetsInputSchema +>; + +export const javascriptRuntimeKindSchema = z.enum([ + "node", + "electron-main", + "electron-preload", + "electron-renderer", +]); + +export const javascriptRuntimeObservationLimitsSchema = z.strictObject({ + max_events: z.number().int().min(1).max(50_000).default(10_000), + max_scripts: z.number().int().min(1).max(10_000).default(2_000), + max_execution_contexts: z.number().int().min(1).max(5_000).default(1_000), + max_location_bytes: z.number().int().min(64).max(65_536).default(16_384), + max_total_metadata_bytes: z + .number() + .int() + .min(1_024) + .max(32 * 1_024 * 1_024) + .default(4 * 1_024 * 1_024), +}); + +/** Input for one bounded, attach-only V8 Inspector observation. */ +export const observeJavaScriptRuntimeInputSchema = z + .strictObject({ + ...approvedRuntimeScope, + target_id: z.string().trim().min(1).max(256), + runtime_kind: javascriptRuntimeKindSchema, + observation_ms: z.number().int().min(0).max(10_000).default(100), + limits: javascriptRuntimeObservationLimitsSchema.default({ + max_events: 10_000, + max_scripts: 2_000, + max_execution_contexts: 1_000, + max_location_bytes: 16_384, + max_total_metadata_bytes: 4 * 1_024 * 1_024, + }), + }) + .superRefine(requireRuntimeScope); +export type ObserveJavaScriptRuntimeInput = z.infer< + typeof observeJavaScriptRuntimeInputSchema +>; + +export const javascriptRuntimeVersionSchema = z.strictObject({ + product: z.string().min(1).max(1_024), + protocol_version: z.string().min(1).max(100), + v8_version: z.string().max(1_024).nullable(), +}); + +export const javascriptRuntimeLocationSchema = z.discriminatedUnion("kind", [ + z.strictObject({ + kind: z.literal("file"), + file_path: z.string().min(1).max(16_384), + }), + z.strictObject({ + kind: z.literal("url"), + origin: z.string().min(1).max(2_048), + sanitized_url: z.string().min(1).max(65_536), + }), + z.strictObject({ + kind: z.literal("builtin"), + specifier: z.string().min(1).max(4_096), + }), +]); +export type JavaScriptRuntimeLocation = z.infer< + typeof javascriptRuntimeLocationSchema +>; + +const javascriptRuntimeTargetSchema = z.strictObject({ + target_id: z.string().min(1).max(256), + protocol_type: z.string().min(1).max(100), + attached: z.boolean(), + location: javascriptRuntimeLocationSchema, +}); + +/** Root/origin-filtered V8 Inspector target inventory. */ +export const javascriptRuntimeTargetListSchema = z.strictObject({ + schema_version: z.literal(1), + runtime: javascriptRuntimeVersionSchema, + targets: z.strictObject({ + items: z.array(javascriptRuntimeTargetSchema), + offset: z.number().int().min(0), + limit: z.number().int().min(1), + total: z.number().int().min(0), + next_offset: z.number().int().min(0).nullable(), + has_more: z.boolean(), + }), + excluded: z.strictObject({ + outside_file_roots: z.number().int().min(0), + outside_origins: z.number().int().min(0), + unsupported_location: z.number().int().min(0), + unconnectable: z.number().int().min(0), + }), + limitations: z.array(boundedTextSchema).max(100), +}); +export type JavaScriptRuntimeTargetList = z.infer< + typeof javascriptRuntimeTargetListSchema +>; + +const javascriptRuntimeScriptSchema = z.strictObject({ + script_key: z.string().regex(/^v8_script_[a-f0-9]{64}$/u), + location: javascriptRuntimeLocationSchema, + execution_context_key: z.string().max(64).nullable(), + cdp_hash: z.string().max(512).nullable(), + length: z.number().int().min(0), + is_module: z.boolean(), + status: z.literal("observed-loaded"), +}); + +const javascriptRuntimeContextSchema = z.strictObject({ + context_key: z.string().min(1).max(64), + state: z.enum(["created", "destroyed", "cleared"]), + name: z.string().max(1_024).nullable(), + origin: z.string().max(4_096).nullable(), +}); + +/** Deterministic passive script/context snapshot from one bounded window. */ +export const javascriptRuntimeObservationSchema = z.strictObject({ + schema_version: z.literal(1), + runtime: javascriptRuntimeVersionSchema, + target: javascriptRuntimeTargetSchema.extend({ + runtime_kind: javascriptRuntimeKindSchema, + runtime_kind_authority: z.literal("caller-declared-unverified"), + }), + capture: z.strictObject({ + observation_ms: z.number().int().min(0), + events_observed: z.number().int().min(0), + events_retained: z.number().int().min(0), + events_dropped: z.number().int().min(0), + metadata_bytes_retained: z.number().int().min(0), + truncated: z.boolean(), + truncation_reasons: z.array(boundedTextSchema).max(20), + }), + scripts: z.strictObject({ + items: z.array(javascriptRuntimeScriptSchema), + observed_total: z.number().int().min(0), + excluded: z.strictObject({ + outside_file_roots: z.number().int().min(0), + outside_origins: z.number().int().min(0), + unsupported_location: z.number().int().min(0), + invalid_protocol_value: z.number().int().min(0), + }), + }), + execution_contexts: z.array(javascriptRuntimeContextSchema), + directly_observed: z.array(boundedTextSchema).max(20), + unavailable_without_instrumentation: z.array(boundedTextSchema).max(20), + unknowns: z.array(boundedTextSchema).max(100), + limitations: z.array(boundedTextSchema).max(100), +}); +export type JavaScriptRuntimeObservation = z.infer< + typeof javascriptRuntimeObservationSchema +>; diff --git a/src/server/registerJavaScriptRuntimeObservationTools.ts b/src/server/registerJavaScriptRuntimeObservationTools.ts new file mode 100644 index 000000000..ea6a7910e --- /dev/null +++ b/src/server/registerJavaScriptRuntimeObservationTools.ts @@ -0,0 +1,98 @@ +import type { McpServer } from "@modelcontextprotocol/server"; +import type { z } from "zod"; + +import type { BinarySessionPort } from "../application/BinarySession.js"; +import type { JavaScriptRuntimeObservationPort } from "../application/JavaScriptRuntimeObservationPort.js"; +import { + listJavaScriptRuntimeTargets, + observeJavaScriptRuntime, +} from "../application/JavaScriptRuntimeObservationService.js"; +import type { PermissionAuthority } from "../application/PermissionAuthority.js"; +import { JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS } from "../contracts/javascriptRuntimeObservationToolContracts.js"; +import type { ToolContract } from "../contracts/toolContracts.js"; +import type { AnalysisError } from "../domain/errors.js"; +import type { Evidence } from "../domain/evidence.js"; +import { + listJavaScriptRuntimeTargetsInputSchema, + observeJavaScriptRuntimeInputSchema, +} from "../domain/javascriptRuntimeObservation.js"; +import type { Result } from "../domain/result.js"; +import type { Logger } from "../logger.js"; +import { logToolExecution } from "./toolLogging.js"; +import { safeParseToolInput } from "./toolInputValidation.js"; +import { toolRegistrationOptions } from "./toolRegistrationOptions.js"; +import { toCallToolResult } from "./toolResult.js"; + +interface RuntimeToolRegistration { + readonly logger: Logger; + readonly runtime: JavaScriptRuntimeObservationPort | undefined; + readonly permissionAuthority: PermissionAuthority | undefined; + readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined; +} + +interface RuntimeToolSpec { + readonly contract: ToolContract; + readonly schema: Schema; + readonly execute: ( + parsed: z.output, + signal: AbortSignal, + ) => Promise>; +} + +/** Register passive Inspector tools even when policy keeps them unavailable. */ +export const registerJavaScriptRuntimeObservationTools = ( + server: McpServer, + options: RuntimeToolRegistration, +): void => { + const [listContract, observeContract] = + JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS; + registerRuntimeTool(server, options, { + contract: listContract, + schema: listJavaScriptRuntimeTargetsInputSchema, + execute: (parsed, signal) => + listJavaScriptRuntimeTargets( + options.runtime, + options.permissionAuthority, + parsed, + { signal }, + ), + }); + registerRuntimeTool(server, options, { + contract: observeContract, + schema: observeJavaScriptRuntimeInputSchema, + execute: (parsed, signal) => + observeJavaScriptRuntime( + options.runtime, + options.permissionAuthority, + parsed, + { signal }, + ), + }); +}; + +const registerRuntimeTool = ( + server: McpServer, + options: RuntimeToolRegistration, + spec: RuntimeToolSpec, +): void => { + server.registerTool( + spec.contract.name, + toolRegistrationOptions(spec.contract), + async (input, context) => { + const parsed = safeParseToolInput(spec.schema, input, spec.contract.name); + if (!parsed.ok) return toCallToolResult(parsed, spec.contract); + const result = await logToolExecution( + options.logger, + spec.contract.name, + () => spec.execute(parsed.value, context.mcpReq.signal), + ); + if (!result.ok) return toCallToolResult(result, spec.contract); + const recorded = options.recordEvidence?.(result.value); + return recorded !== undefined && !recorded.ok + ? toCallToolResult(recorded, spec.contract) + : toCallToolResult({ ok: true, value: result.value }, spec.contract, { + evidenceResourcesAvailable: recorded !== undefined, + }); + }, + ); +}; diff --git a/tests/conformance/runtime-inspector/node-target.mjs b/tests/conformance/runtime-inspector/node-target.mjs new file mode 100644 index 000000000..147e1cdd2 --- /dev/null +++ b/tests/conformance/runtime-inspector/node-target.mjs @@ -0,0 +1 @@ +setInterval(() => undefined, 1_000); diff --git a/tests/fixtures/fakeV8Inspector.ts b/tests/fixtures/fakeV8Inspector.ts new file mode 100644 index 000000000..4e0790084 --- /dev/null +++ b/tests/fixtures/fakeV8Inspector.ts @@ -0,0 +1,181 @@ +import { createServer } from "node:http"; + +import { WebSocket, WebSocketServer } from "ws"; + +interface InspectorCommand { + readonly id: number; + readonly method: string; + readonly params: Readonly>; +} + +interface FakeV8InspectorOptions { + readonly targetUrl: string; + readonly targetType?: "node" | "page"; + readonly scriptUrls?: readonly string[]; + readonly additionalTargetUrl?: string; + readonly closeOnMethod?: string; +} + +export interface FakeV8Inspector { + readonly endpoint: string; + readonly targetId: string; + readonly commands: readonly InspectorCommand[]; + close(): Promise; +} + +/** Real loopback HTTP/WebSocket fake matching Node Inspector discovery. */ +export const startFakeV8Inspector = async ( + options: FakeV8InspectorOptions, +): Promise => { + const targetId = "00000000-0000-4000-8000-000000000001"; + const otherTargetId = "00000000-0000-4000-8000-000000000002"; + const commands: InspectorCommand[] = []; + const sockets = new Set(); + let port = 0; + const http = createServer((request, response) => { + response.setHeader("content-type", "application/json"); + if (request.url === "/json/version") { + response.end( + JSON.stringify({ + Browser: "node.js/v24.4.1", + "Protocol-Version": "1.3", + "V8-Version": "13.6", + }), + ); + return; + } + if (request.url === "/json/list") { + response.end( + JSON.stringify([ + target( + targetId, + options.targetUrl, + options.targetType ?? "node", + port, + ), + ...(options.additionalTargetUrl === undefined + ? [] + : [ + target( + otherTargetId, + options.additionalTargetUrl, + options.targetType ?? "node", + port, + ), + ]), + ]), + ); + return; + } + response.statusCode = 404; + response.end("{}"); + }); + const webSockets = new WebSocketServer({ noServer: true }); + http.on("upgrade", (request, socket, head) => { + if (request.url !== `/${targetId}` && request.url !== `/${otherTargetId}`) { + socket.destroy(); + return; + } + webSockets.handleUpgrade(request, socket, head, (webSocket) => + webSockets.emit("connection", webSocket, request), + ); + }); + webSockets.on("connection", (socket: WebSocket) => { + sockets.add(socket); + socket.on("close", () => sockets.delete(socket)); + socket.on("message", (raw) => { + const command = parseCommand(raw.toString()); + commands.push(command); + if (options.closeOnMethod === command.method) { + socket.close(); + return; + } + socket.send(JSON.stringify({ id: command.id, result: {} })); + if (command.method === "Runtime.enable") + socket.send( + JSON.stringify({ + method: "Runtime.executionContextCreated", + params: { + context: { + id: 1, + origin: "", + name: "node[fixture]", + }, + }, + }), + ); + if (command.method === "Debugger.enable") + for (const [index, url] of ( + options.scriptUrls ?? [options.targetUrl] + ).entries()) + socket.send( + JSON.stringify({ + method: "Debugger.scriptParsed", + params: { + scriptId: String(index + 1), + url, + executionContextId: 1, + hash: `hash-${String(index)}`, + length: 100 + index, + isModule: index % 2 === 0, + }, + }), + ); + }); + }); + await new Promise((resolve, reject) => { + http.once("error", reject); + http.listen(0, "127.0.0.1", () => resolve()); + }); + const address = http.address(); + if (address === null || typeof address === "string") + throw new Error("Fake Inspector did not bind a TCP address"); + port = address.port; + return { + endpoint: `http://127.0.0.1:${String(port)}`, + targetId, + commands, + async close() { + for (const socket of sockets) socket.terminate(); + await new Promise((resolve) => webSockets.close(() => resolve())); + await new Promise((resolve, reject) => + http.close((error) => + error === undefined ? resolve() : reject(error), + ), + ); + }, + }; +}; + +const target = ( + id: string, + url: string, + type: "node" | "page", + port: number, +) => ({ + id, + type, + title: "redacted-by-provider", + url, + attached: false, + webSocketDebuggerUrl: `ws://localhost:${String(port)}/${id}`, +}); + +const parseCommand = (raw: string): InspectorCommand => { + const value: unknown = JSON.parse(raw); + if ( + typeof value !== "object" || + value === null || + typeof Reflect.get(value, "id") !== "number" || + typeof Reflect.get(value, "method") !== "string" + ) + throw new TypeError("Invalid Inspector command"); + const params = Reflect.get(value, "params"); + if (typeof params !== "object" || params === null || Array.isArray(params)) + throw new TypeError("Invalid Inspector command params"); + return { + id: Reflect.get(value, "id"), + method: Reflect.get(value, "method"), + params, + }; +}; diff --git a/tests/javascriptRuntimeObservation.test.ts b/tests/javascriptRuntimeObservation.test.ts new file mode 100644 index 000000000..90e74e76b --- /dev/null +++ b/tests/javascriptRuntimeObservation.test.ts @@ -0,0 +1,362 @@ +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { pathToFileURL } from "node:url"; + +import { afterEach, describe, expect, test } from "vitest"; + +import { createJavaScriptRuntimeObservationEvidence } from "../src/application/JavaScriptRuntimeObservationEvidence.js"; +import { + listJavaScriptRuntimeTargets, + observeJavaScriptRuntime, +} from "../src/application/JavaScriptRuntimeObservationService.js"; +import { createPermissionAuthority } from "../src/application/PermissionAuthority.js"; +import { reconcileJavaScriptRuntimeEvidence } from "../src/application/JavaScriptRuntimeReconciliationService.js"; +import { V8_INSPECTOR_PROVIDER_IDENTITY } from "../src/browser/V8InspectorProvider.js"; +import { V8InspectorProvider } from "../src/browser/V8InspectorProvider.js"; +import { JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE } from "../src/contracts/javascriptRuntimeReconciliationExample.js"; +import type { + JavaScriptRuntimeObservation, + ObserveJavaScriptRuntimeInput, +} from "../src/domain/javascriptRuntimeObservation.js"; +import { javascriptRuntimeReconciliationResultSchema } from "../src/domain/javascriptRuntimeReconciliationSchemas.js"; +import type { + PermissionCeiling, + PermissionGrant, +} from "../src/domain/permissionPolicy.js"; +import { startFakeV8Inspector } from "./fixtures/fakeV8Inspector.js"; + +const temporaryRoots: string[] = []; + +afterEach(async () => { + await Promise.all( + temporaryRoots.splice(0).map((path) => rm(path, { recursive: true })), + ); +}); + +describe("passive V8 Inspector provider", () => { + test("filters target locations and never retains the excluded path", async () => { + const fixture = await runtimeFixture(); + const outside = await temporaryFile("outside.js"); + const fake = await startFakeV8Inspector({ + targetUrl: pathToFileURL(fixture.entry).href, + additionalTargetUrl: pathToFileURL(outside).href, + }); + try { + const result = await new V8InspectorProvider().listTargets({ + inspector_endpoint: fake.endpoint, + allowed_file_roots: [fixture.root], + allowed_origins: [], + approved: true, + offset: 0, + limit: 100, + }); + expect(result.ok).toBe(true); + if (!result.ok) return; + expect(result.value.targets.total).toBe(1); + expect(result.value.excluded.outside_file_roots).toBe(1); + expect(JSON.stringify(result.value)).not.toContain(outside); + } finally { + await fake.close(); + } + }); + + test("captures only bounded metadata with two enable commands", async () => { + const fixture = await runtimeFixture(); + const outside = await temporaryFile("secret.js"); + const fake = await startFakeV8Inspector({ + targetUrl: pathToFileURL(fixture.entry).href, + scriptUrls: [ + pathToFileURL(fixture.entry).href, + "node:fs", + pathToFileURL(outside).href, + ], + }); + try { + const result = await new V8InspectorProvider().observe( + observeInput(fake.endpoint, fake.targetId, fixture.root, "node"), + ); + expect(result.ok).toBe(true); + if (!result.ok) return; + expect(result.value.scripts.items).toHaveLength(2); + expect(result.value.scripts.excluded.outside_file_roots).toBe(1); + expect(result.value.execution_contexts).toEqual([ + { + context_key: "1", + state: "created", + name: null, + origin: null, + }, + ]); + expect(fake.commands.map(({ method }) => method)).toEqual([ + "Runtime.enable", + "Debugger.enable", + ]); + expect(JSON.stringify(result.value)).not.toContain(outside); + expect(result.value.unavailable_without_instrumentation).toContain( + "Electron IPC messages and handlers", + ); + } finally { + await fake.close(); + } + }); + + test.each([ + ["node", "node"], + ["electron-main", "node"], + ["electron-preload", "page"], + ["electron-renderer", "page"], + ] as const)( + "admits declared %s only on its protocol target family", + async (runtimeKind, targetType) => { + const fixture = await runtimeFixture(); + const fake = await startFakeV8Inspector({ + targetUrl: pathToFileURL(fixture.entry).href, + targetType, + }); + try { + const result = await new V8InspectorProvider().observe( + observeInput(fake.endpoint, fake.targetId, fixture.root, runtimeKind), + ); + expect(result.ok).toBe(true); + } finally { + await fake.close(); + } + }, + ); + + test("marks capture truncation instead of claiming complete coverage", async () => { + const fixture = await runtimeFixture(); + const second = join(fixture.root, "second.js"); + await writeFile(second, "export {};\n"); + const fake = await startFakeV8Inspector({ + targetUrl: pathToFileURL(fixture.entry).href, + scriptUrls: [ + pathToFileURL(fixture.entry).href, + pathToFileURL(second).href, + ], + }); + try { + const input = observeInput( + fake.endpoint, + fake.targetId, + fixture.root, + "node", + ); + const result = await new V8InspectorProvider().observe({ + ...input, + limits: { ...input.limits, max_scripts: 1 }, + }); + expect(result.ok).toBe(true); + if (!result.ok) return; + expect(result.value.capture.truncated).toBe(true); + expect(result.value.capture.truncation_reasons).toEqual(["max_scripts"]); + expect(result.value.capture.events_dropped).toBe(1); + } finally { + await fake.close(); + } + }); + + test("produces deterministic Evidence through the authorized service", async () => { + const fixture = await runtimeFixture(); + const fake = await startFakeV8Inspector({ + targetUrl: pathToFileURL(fixture.entry).href, + }); + try { + const input = observeInput( + fake.endpoint, + fake.targetId, + fixture.root, + "node", + ); + const authority = await authorityFor(fake.endpoint, fixture.root); + const first = await observeJavaScriptRuntime( + new V8InspectorProvider(), + authority, + input, + ); + const second = await observeJavaScriptRuntime( + new V8InspectorProvider(), + authority, + input, + ); + expect(first.ok).toBe(true); + expect(second.ok).toBe(true); + if (!first.ok || !second.ok) return; + expect(second.value.evidence_id).toBe(first.value.evidence_id); + + const listed = await listJavaScriptRuntimeTargets( + new V8InspectorProvider(), + authority, + { + inspector_endpoint: fake.endpoint, + allowed_file_roots: [fixture.root], + allowed_origins: [], + approved: true, + offset: 0, + limit: 100, + }, + ); + expect(listed.ok).toBe(true); + } finally { + await fake.close(); + } + }); + + test("reconciles V8 script presence with static Application Graph Evidence", () => { + const root = "/Applications/Example.app/Contents/Resources/app"; + const observation = runtimeObservation( + `${root}/index.html`, + `${root}/renderer.js`, + ); + const runtimeEvidence = createJavaScriptRuntimeObservationEvidence( + "observe_javascript_runtime", + { + inspector_endpoint: "http://127.0.0.1:9229", + allowed_file_roots: [root], + allowed_origins: [], + target_id: "example-v8-target", + runtime_kind: "electron-main", + approved: true, + observation_ms: 100, + limits: { + max_events: 10_000, + max_scripts: 2_000, + max_execution_contexts: 1_000, + max_location_bytes: 16_384, + max_total_metadata_bytes: 4_194_304, + }, + }, + observation, + V8_INSPECTOR_PROVIDER_IDENTITY, + ); + const reconciled = reconcileJavaScriptRuntimeEvidence({ + static_layers: JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE.static_layers, + runtime_observations: [runtimeEvidence], + }); + expect(reconciled.ok).toBe(true); + if (!reconciled.ok) return; + const result = javascriptRuntimeReconciliationResultSchema.parse( + reconciled.value.normalized_result, + ); + expect(result.runtime_captures[0]?.kind).toBe("v8-inspector"); + expect(result.summary.runtime_scripts).toBe(1); + expect(result.summary.matched).toBeGreaterThan(0); + }); +}); + +const runtimeFixture = async () => { + const root = await mkdtemp(join(tmpdir(), "rea-v8-runtime-")); + temporaryRoots.push(root); + const entry = join(root, "entry.js"); + await writeFile(entry, "export const value = 1;\n"); + return { root, entry }; +}; + +const temporaryFile = async (name: string): Promise => { + const root = await mkdtemp(join(tmpdir(), "rea-v8-outside-")); + temporaryRoots.push(root); + const path = join(root, name); + await writeFile(path, "export {};\n"); + return path; +}; + +const observeInput = ( + endpoint: string, + targetId: string, + root: string, + runtimeKind: ObserveJavaScriptRuntimeInput["runtime_kind"], +): ObserveJavaScriptRuntimeInput => ({ + inspector_endpoint: endpoint, + allowed_file_roots: [root], + allowed_origins: [], + target_id: targetId, + runtime_kind: runtimeKind, + approved: true, + observation_ms: 10, + limits: { + max_events: 10_000, + max_scripts: 2_000, + max_execution_contexts: 1_000, + max_location_bytes: 16_384, + max_total_metadata_bytes: 4_194_304, + }, +}); + +const authorityFor = async (endpoint: string, root: string) => { + const scope: PermissionCeiling = { + capability: "v8_inspector_observe", + roots: [root], + executables: [], + environment_names: [], + origins: [endpoint], + network: "loopback", + mount: false, + }; + const grant: PermissionGrant = { + ...scope, + grant_id: "test:v8-inspector", + lifetime: "administrator", + operation_identity: null, + expires_at: null, + }; + const authority = await createPermissionAuthority([scope], [grant]); + if (!authority.ok) throw authority.error; + return authority.value; +}; + +const runtimeObservation = ( + targetPath: string, + scriptPath: string, +): JavaScriptRuntimeObservation => ({ + schema_version: 1, + runtime: { + product: "node.js/v24.4.1", + protocol_version: "1.3", + v8_version: "13.6", + }, + target: { + target_id: "example-v8-target", + protocol_type: "node", + attached: false, + location: { kind: "file", file_path: targetPath }, + runtime_kind: "electron-main", + runtime_kind_authority: "caller-declared-unverified", + }, + capture: { + observation_ms: 100, + events_observed: 1, + events_retained: 1, + events_dropped: 0, + metadata_bytes_retained: 100, + truncated: false, + truncation_reasons: [], + }, + scripts: { + items: [ + { + script_key: `v8_script_${"4".repeat(64)}`, + location: { kind: "file", file_path: scriptPath }, + execution_context_key: "1", + cdp_hash: "v8-hash", + length: 29, + is_module: true, + status: "observed-loaded", + }, + ], + observed_total: 1, + excluded: { + outside_file_roots: 0, + outside_origins: 0, + unsupported_location: 0, + invalid_protocol_value: 0, + }, + }, + execution_contexts: [], + directly_observed: ["Debugger.scriptParsed established script presence."], + unavailable_without_instrumentation: [ + "require/import caller-to-callee edges", + ], + unknowns: ["Capture is bounded."], + limitations: ["Passive Inspector metadata only."], +}); diff --git a/tests/javascriptRuntimeObservationCli.test.ts b/tests/javascriptRuntimeObservationCli.test.ts new file mode 100644 index 000000000..3cf460c54 --- /dev/null +++ b/tests/javascriptRuntimeObservationCli.test.ts @@ -0,0 +1,149 @@ +import { execFile } from "node:child_process"; +import { rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { pathToFileURL } from "node:url"; +import { promisify } from "node:util"; + +import { afterEach, describe, expect, test } from "vitest"; + +import { loadConfiguredPermissionAuthority } from "../src/application/PermissionConfiguration.js"; +import { observeJavaScriptRuntime } from "../src/application/JavaScriptRuntimeObservationService.js"; +import { V8InspectorProvider } from "../src/browser/V8InspectorProvider.js"; +import { parseConfig } from "../src/config.js"; +import { startFakeV8Inspector } from "./fixtures/fakeV8Inspector.js"; +import { createTestTempDirectory } from "./fixtures/temporaryDirectory.js"; + +const execute = promisify(execFile); +const TIMEOUT_MS = 20_000; + +describe("JavaScript runtime observation CLI parity", () => { + const resources: Array<{ close(): Promise }> = []; + const temporary: string[] = []; + + afterEach(async () => { + await Promise.all(resources.splice(0).map((item) => item.close())); + await Promise.all( + temporary + .splice(0) + .map((path) => rm(path, { recursive: true, force: true })), + ); + }); + + test( + "returns the same passive Inspector Evidence contracts", + async () => { + const root = await createTestTempDirectory("rea-v8-cli-"); + temporary.push(root); + const entry = join(root, "entry.js"); + await writeFile(entry, "export const value = 1;\n"); + const inspector = await startFakeV8Inspector({ + targetUrl: pathToFileURL(entry).href, + }); + resources.push(inspector); + const environment = { + ...process.env, + REA_V8_INSPECTOR_OBSERVE_ENABLED: "true", + REA_V8_INSPECTOR_ENDPOINTS_JSON: JSON.stringify([inspector.endpoint]), + REA_V8_INSPECTOR_FILE_ROOTS_JSON: JSON.stringify([root]), + }; + + const listed = await runCli( + [ + "list-javascript-runtime-targets", + inspector.endpoint, + "--approved", + "--json", + ], + environment, + ); + expect(listed).toMatchObject({ + operation: "list_javascript_runtime_targets", + provider: { id: "rea-v8-inspector" }, + normalized_result: { + targets: { items: [{ target_id: inspector.targetId }] }, + }, + }); + + const observed = await runCli( + [ + "observe-javascript-runtime", + inspector.endpoint, + inspector.targetId, + "--runtime-kind", + "node", + "--approved", + "--observation-ms", + "10", + "--json", + ], + environment, + ); + expect(observed).toMatchObject({ + operation: "observe_javascript_runtime", + provider: { id: "rea-v8-inspector" }, + normalized_result: { + target: { target_id: inspector.targetId, runtime_kind: "node" }, + scripts: { + items: [ + expect.objectContaining({ + location: { kind: "file", file_path: entry }, + }), + ], + }, + }, + }); + const config = parseConfig(environment); + if (!config.ok) throw config.error; + const authority = await loadConfiguredPermissionAuthority(config.value); + if (!authority.ok) throw authority.error; + const direct = await observeJavaScriptRuntime( + new V8InspectorProvider(), + authority.value, + { + inspector_endpoint: inspector.endpoint, + allowed_file_roots: [root], + allowed_origins: [], + target_id: inspector.targetId, + runtime_kind: "node", + approved: true, + observation_ms: 10, + limits: { + max_events: 10_000, + max_scripts: 2_000, + max_execution_contexts: 1_000, + max_location_bytes: 16_384, + max_total_metadata_bytes: 4_194_304, + }, + }, + ); + expect(direct.ok).toBe(true); + if (direct.ok) + expect(evidenceIdFrom(observed)).toBe(direct.value.evidence_id); + }, + TIMEOUT_MS, + ); +}); + +const runCli = async ( + arguments_: readonly string[], + environment: NodeJS.ProcessEnv, +): Promise => { + const { stdout } = await execute( + process.execPath, + ["scripts/rea.mjs", ...arguments_], + { + cwd: process.cwd(), + env: environment, + maxBuffer: 16 * 1_024 * 1_024, + }, + ); + return JSON.parse(stdout); +}; + +const evidenceIdFrom = (value: unknown): string => { + if (typeof value !== "object" || value === null) + throw new TypeError("Missing CLI Evidence"); + const id = Reflect.get(value, "evidence_id"); + if (typeof id !== "string") throw new TypeError("Missing CLI Evidence ID"); + return id; +}; diff --git a/tests/javascriptRuntimeObservationMcp.test.ts b/tests/javascriptRuntimeObservationMcp.test.ts new file mode 100644 index 000000000..fa9735960 --- /dev/null +++ b/tests/javascriptRuntimeObservationMcp.test.ts @@ -0,0 +1,152 @@ +import { rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { pathToFileURL } from "node:url"; + +import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; +import { afterEach, describe, expect, test } from "vitest"; + +import { BinarySession } from "../src/application/BinarySession.js"; +import { loadConfiguredPermissionAuthority } from "../src/application/PermissionConfiguration.js"; +import { observeJavaScriptRuntime } from "../src/application/JavaScriptRuntimeObservationService.js"; +import { V8InspectorProvider } from "../src/browser/V8InspectorProvider.js"; +import { parseConfig } from "../src/config.js"; +import { createServer } from "../src/server/createServer.js"; +import { observed } from "./fixtures/analysisExecution.js"; +import { startFakeV8Inspector } from "./fixtures/fakeV8Inspector.js"; +import { createTestTempDirectory } from "./fixtures/temporaryDirectory.js"; + +describe("JavaScript runtime observation MCP tools", () => { + const resources: Array<{ close(): Promise }> = []; + const temporary: string[] = []; + + afterEach(async () => { + await Promise.all(resources.splice(0).map((item) => item.close())); + await Promise.all( + temporary + .splice(0) + .map((path) => rm(path, { recursive: true, force: true })), + ); + }); + + test("lists and observes one target as retained Evidence", async () => { + const root = await createTestTempDirectory("rea-v8-mcp-"); + temporary.push(root); + const entry = join(root, "entry.js"); + await writeFile(entry, "export const value = 1;\n"); + const inspector = await startFakeV8Inspector({ + targetUrl: pathToFileURL(entry).href, + }); + resources.push(inspector); + const config = parseConfig({ + REA_V8_INSPECTOR_OBSERVE_ENABLED: "true", + REA_V8_INSPECTOR_ENDPOINTS_JSON: JSON.stringify([inspector.endpoint]), + REA_V8_INSPECTOR_FILE_ROOTS_JSON: JSON.stringify([root]), + }); + if (!config.ok) throw config.error; + const authority = await loadConfiguredPermissionAuthority(config.value); + if (!authority.ok) throw authority.error; + const session = new BinarySession(() => ({ + execute: () => Promise.resolve(observed(null)), + close: () => Promise.resolve(), + })); + const server = createServer(session, session, { + javascriptRuntimeObservation: new V8InspectorProvider(), + permissionAuthority: authority.value, + availabilityPolicy: () => ({ + processCaptureEnabled: false, + evidenceFileRoots: 0, + investigationInputRoots: 0, + v8InspectorObservationEnabled: true, + }), + }); + const client = new Client({ name: "v8-mcp-test", version: "1" }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + resources.push(client, server, session); + await server.connect(serverTransport); + await client.connect(clientTransport); + + const listed = await client.callTool({ + name: "list_javascript_runtime_targets", + arguments: { + inspector_endpoint: inspector.endpoint, + allowed_file_roots: [root], + allowed_origins: [], + approved: true, + }, + }); + expect(listed.isError).not.toBe(true); + expect(listed.structuredContent).toMatchObject({ + result: { + targets: { items: [{ target_id: inspector.targetId }] }, + }, + }); + + const observedRuntime = await client.callTool({ + name: "observe_javascript_runtime", + arguments: { + inspector_endpoint: inspector.endpoint, + allowed_file_roots: [root], + allowed_origins: [], + target_id: inspector.targetId, + runtime_kind: "node", + approved: true, + observation_ms: 10, + }, + }); + expect(observedRuntime.isError).not.toBe(true); + expect(observedRuntime.structuredContent).toMatchObject({ + result: { + target: { + target_id: inspector.targetId, + runtime_kind: "node", + runtime_kind_authority: "caller-declared-unverified", + }, + scripts: { + items: [ + expect.objectContaining({ + location: { kind: "file", file_path: entry }, + }), + ], + }, + }, + }); + const evidenceId = evidenceIdFrom(observedRuntime.structuredContent); + expect(session.evidenceById(evidenceId)).toBeDefined(); + expect(inspector.commands.map(({ method }) => method)).toEqual([ + "Runtime.enable", + "Debugger.enable", + ]); + const direct = await observeJavaScriptRuntime( + new V8InspectorProvider(), + authority.value, + { + inspector_endpoint: inspector.endpoint, + allowed_file_roots: [root], + allowed_origins: [], + target_id: inspector.targetId, + runtime_kind: "node", + approved: true, + observation_ms: 10, + limits: { + max_events: 10_000, + max_scripts: 2_000, + max_execution_contexts: 1_000, + max_location_bytes: 16_384, + max_total_metadata_bytes: 4_194_304, + }, + }, + ); + expect(direct.ok).toBe(true); + if (direct.ok) expect(evidenceId).toBe(direct.value.evidence_id); + }); +}); + +const evidenceIdFrom = (value: unknown): string => { + if (typeof value !== "object" || value === null) + throw new TypeError("Missing structured result"); + const evidenceId = Reflect.get(value, "evidence_id"); + if (typeof evidenceId !== "string") + throw new TypeError("Missing Evidence ID"); + return evidenceId; +};