Files
rea/src/browser/V8InspectorCaptureProjection.ts
T

160 lines
5.2 KiB
TypeScript

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 createInspectorExclusionCounts = (): Record<
ExclusionReason,
number
> => ({
outside_file_roots: 0,
outside_origins: 0,
unsupported_location: 0,
});
/** Stable safety and protocol limitations shared by target-list Evidence. */
export const describeInspectorTargetLimitations = (): 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 finalizeInspectorCapture = async ({
input,
runtime,
target,
roots,
state,
}: FinalizeCaptureInput): Promise<JavaScriptRuntimeObservation> => {
const exclusions = createInspectorExclusionCounts();
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 < right.script_key
? -1
: left.script_key > right.script_key
? 1
: 0,
);
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 < right.context_key
? -1
: left.context_key > right.context_key
? 1
: 0,
);
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: describeInspectorTargetLimitations(),
};
};
const scriptFromDraft = (
draft: ScriptDraft,
location: JavaScriptRuntimeLocation,
): JavaScriptRuntimeObservation["scripts"]["items"][number] => {
const stable = JSON.stringify({
location,
execution_context_key: draft.executionContextKey,
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",
};
};