486 lines
16 KiB
TypeScript
486 lines
16 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
|
|
import canonicalize from "canonicalize";
|
|
|
|
import type { ProgressReporter } from "../application/ProgressReporter.js";
|
|
import type {
|
|
ElectronPageInspection,
|
|
InspectElectronPageInput,
|
|
} from "../domain/electronObservation.js";
|
|
import { BrowserObservationError } from "../domain/errors.js";
|
|
import { createWebTextArtifact } from "../domain/webContentArtifact.js";
|
|
import type { CdpConnection, CdpEvent } from "./CdpConnection.js";
|
|
import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js";
|
|
import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
|
|
import {
|
|
boundedText,
|
|
delayWithCancellation,
|
|
numberValue,
|
|
recordValue,
|
|
recordsValue,
|
|
requiredRecord,
|
|
stringValue,
|
|
type UnknownRecord,
|
|
} from "./CdpCaptureValues.js";
|
|
import {
|
|
authorizedElectronFile,
|
|
canonicalElectronRoots,
|
|
} from "./ElectronFileScope.js";
|
|
|
|
interface ElectronContext {
|
|
readonly connection: CdpConnection;
|
|
readonly sessionId: string | undefined;
|
|
readonly discovery: CdpEndpointDiscovery;
|
|
readonly target: CdpEndpointTarget;
|
|
readonly input: InspectElectronPageInput;
|
|
readonly signal?: AbortSignal;
|
|
readonly progress?: ProgressReporter;
|
|
}
|
|
|
|
interface ScriptDraft {
|
|
readonly scriptId: string;
|
|
readonly rawUrl: string;
|
|
readonly hash: string;
|
|
readonly length: number;
|
|
readonly isModule: boolean;
|
|
readonly language: string | null;
|
|
}
|
|
|
|
/** Passively inspect one root-confined Electron file page. */
|
|
export const inspectCdpElectronPage = async (
|
|
context: ElectronContext,
|
|
): Promise<ElectronPageInspection> => {
|
|
const roots = await canonicalElectronRoots(context.input.allowed_file_roots);
|
|
const completeness = new CdpCaptureCompleteness();
|
|
const scripts: ScriptDraft[] = [];
|
|
let mainFrameId: string | undefined;
|
|
let navigationDuringCapture = false;
|
|
const removeListener = context.connection.onEvent((event) => {
|
|
if (event.sessionId !== context.sessionId) return;
|
|
ingestScript(event, scripts, completeness);
|
|
if (mainFrameId !== undefined && navigatedFrameId(event) === mainFrameId)
|
|
navigationDuringCapture = true;
|
|
});
|
|
const startedAt = new Date().toISOString();
|
|
try {
|
|
await report(context.progress, 1, "Authorizing Electron file frames");
|
|
await context.connection.send(
|
|
"Page.enable",
|
|
{},
|
|
context.sessionId,
|
|
context.signal,
|
|
);
|
|
const before = await context.connection.send(
|
|
"Page.getFrameTree",
|
|
{},
|
|
context.sessionId,
|
|
context.signal,
|
|
);
|
|
const frames = await captureFrames(
|
|
before,
|
|
roots,
|
|
context.input.limits.max_frames,
|
|
completeness,
|
|
);
|
|
const main = frames[0];
|
|
if (main === undefined)
|
|
throw new BrowserObservationError(
|
|
"inspect_web_page",
|
|
"target_not_allowed",
|
|
);
|
|
mainFrameId = main.frame_id;
|
|
await context.connection.send(
|
|
"Debugger.enable",
|
|
{ maxScriptsCacheSize: 4 * 1_024 * 1_024 },
|
|
context.sessionId,
|
|
context.signal,
|
|
);
|
|
await delayWithCancellation(
|
|
context.input.observation_ms,
|
|
"inspect_electron_page",
|
|
context.signal,
|
|
);
|
|
await report(context.progress, 2, "Capturing Electron structure");
|
|
const resources = await captureResources(context, roots, completeness);
|
|
const dom = await captureDom(context, roots, completeness);
|
|
const normalizedScripts = await captureScripts(
|
|
context,
|
|
roots,
|
|
scripts,
|
|
completeness,
|
|
);
|
|
const after = await context.connection.send(
|
|
"Page.getFrameTree",
|
|
{},
|
|
context.sessionId,
|
|
context.signal,
|
|
);
|
|
const afterMain = await mainFilePath(after, roots);
|
|
if (afterMain === undefined)
|
|
throw new BrowserObservationError(
|
|
"inspect_web_page",
|
|
"target_not_allowed",
|
|
);
|
|
if (navigationDuringCapture || afterMain !== main.file_path)
|
|
throw new BrowserObservationError("inspect_web_page", "target_changed");
|
|
await report(context.progress, 3, "Electron inspection complete");
|
|
return {
|
|
schema_version: 1,
|
|
browser: context.discovery.version,
|
|
target: {
|
|
target_id: context.target.id,
|
|
type: context.target.type,
|
|
title: context.target.title.slice(0, 16_384),
|
|
file_path: main.file_path,
|
|
attached: context.target.attached,
|
|
},
|
|
capture_window: {
|
|
started_at: startedAt,
|
|
ended_at: new Date().toISOString(),
|
|
observation_ms: context.input.observation_ms,
|
|
},
|
|
completeness: completeness.snapshot(),
|
|
frames,
|
|
dom,
|
|
scripts: normalizedScripts,
|
|
resources,
|
|
limitations: [
|
|
"Only canonical file paths contained by an approved root are retained.",
|
|
"REA does not evaluate renderer JavaScript, invoke Electron APIs, navigate, click, or close the page.",
|
|
"Script contents require separate source-capture approval and remain byte bounded.",
|
|
],
|
|
};
|
|
} finally {
|
|
removeListener();
|
|
}
|
|
};
|
|
|
|
const navigatedFrameId = (event: CdpEvent): string | undefined => {
|
|
const params = recordValue(event.params);
|
|
if (params === undefined) return undefined;
|
|
if (event.method === "Page.frameNavigated")
|
|
return stringValue(recordValue(params.frame)?.id);
|
|
if (event.method === "Page.navigatedWithinDocument")
|
|
return stringValue(params.frameId);
|
|
return undefined;
|
|
};
|
|
|
|
const ingestScript = (
|
|
event: CdpEvent,
|
|
scripts: ScriptDraft[],
|
|
completeness: CdpCaptureCompleteness,
|
|
): void => {
|
|
if (event.method !== "Debugger.scriptParsed") return;
|
|
const value = recordValue(event.params);
|
|
const scriptId = stringValue(value?.scriptId);
|
|
const rawUrl = stringValue(value?.url);
|
|
if (scriptId === undefined || scriptId.length > 256) {
|
|
completeness.exclude("scripts", "invalid_protocol_value");
|
|
return;
|
|
}
|
|
if (rawUrl === undefined || rawUrl === "") {
|
|
completeness.exclude("scripts", "unattributed_origin");
|
|
return;
|
|
}
|
|
if (scripts.length >= 2_000) {
|
|
completeness.drop("scripts");
|
|
return;
|
|
}
|
|
scripts.push({
|
|
scriptId,
|
|
rawUrl,
|
|
hash: (stringValue(value?.hash) ?? "").slice(0, 512),
|
|
length: nonnegativeInteger(value?.length),
|
|
isModule: value?.isModule === true,
|
|
language: boundedText(value?.scriptLanguage, 100),
|
|
});
|
|
};
|
|
|
|
const captureFrames = async (
|
|
result: unknown,
|
|
roots: readonly string[],
|
|
maximum: number,
|
|
completeness: CdpCaptureCompleteness,
|
|
): Promise<ElectronPageInspection["frames"]> => {
|
|
const frameTree = recordValue(requiredRecord(result).frameTree);
|
|
if (frameTree === undefined)
|
|
throw new BrowserObservationError("inspect_web_page", "protocol_error");
|
|
const pending: Array<{
|
|
readonly tree: UnknownRecord;
|
|
readonly parent: string | null;
|
|
}> = [{ tree: frameTree, parent: null }];
|
|
const frames: ElectronPageInspection["frames"] = [];
|
|
while (pending.length > 0) {
|
|
const current = pending.shift();
|
|
if (current === undefined) break;
|
|
const frame = recordValue(current.tree.frame);
|
|
const frameId = stringValue(frame?.id);
|
|
const path = await authorizedElectronFile(
|
|
stringValue(frame?.url) ?? "",
|
|
roots,
|
|
);
|
|
if (frameId === undefined || path === undefined) {
|
|
completeness.exclude("frames", "out_of_target_scope");
|
|
continue;
|
|
}
|
|
if (frames.length >= maximum) {
|
|
completeness.truncate("frames");
|
|
continue;
|
|
}
|
|
frames.push({
|
|
frame_id: frameId.slice(0, 256),
|
|
parent_frame_id: current.parent,
|
|
file_path: path,
|
|
});
|
|
for (const child of recordsValue(current.tree.childFrames))
|
|
pending.push({ tree: child, parent: frameId.slice(0, 256) });
|
|
}
|
|
return frames;
|
|
};
|
|
|
|
const captureResources = async (
|
|
context: ElectronContext,
|
|
roots: readonly string[],
|
|
completeness: CdpCaptureCompleteness,
|
|
): Promise<ElectronPageInspection["resources"]> => {
|
|
const result = await context.connection.send(
|
|
"Page.getResourceTree",
|
|
{},
|
|
context.sessionId,
|
|
context.signal,
|
|
);
|
|
const root = recordValue(requiredRecord(result).frameTree);
|
|
if (root === undefined)
|
|
throw new BrowserObservationError("inspect_web_page", "protocol_error");
|
|
const pending = [root];
|
|
const resources: ElectronPageInspection["resources"] = [];
|
|
const seen = new Set<string>();
|
|
while (pending.length > 0) {
|
|
const tree = pending.shift();
|
|
if (tree === undefined) break;
|
|
for (const resource of recordsValue(tree.resources)) {
|
|
const path = await authorizedElectronFile(
|
|
stringValue(resource.url) ?? "",
|
|
roots,
|
|
);
|
|
if (path === undefined) {
|
|
completeness.exclude("resources", "out_of_target_scope");
|
|
continue;
|
|
}
|
|
const item = {
|
|
file_path: path,
|
|
type: (stringValue(resource.type) ?? "Other").slice(0, 100),
|
|
mime_type: (stringValue(resource.mimeType) ?? "").slice(0, 256),
|
|
content_size:
|
|
numberValue(resource.contentSize) === undefined
|
|
? null
|
|
: Math.max(0, numberValue(resource.contentSize) ?? 0),
|
|
};
|
|
const resourceKey = `electron_resource_${digest(item)}`;
|
|
if (seen.has(resourceKey)) continue;
|
|
seen.add(resourceKey);
|
|
if (resources.length >= context.input.limits.max_resources) {
|
|
completeness.truncate("resources");
|
|
continue;
|
|
}
|
|
resources.push({
|
|
resource_key: resourceKey,
|
|
...item,
|
|
});
|
|
}
|
|
pending.push(...recordsValue(tree.childFrames));
|
|
}
|
|
return resources.sort((left, right) =>
|
|
left.resource_key.localeCompare(right.resource_key),
|
|
);
|
|
};
|
|
|
|
const captureDom = async (
|
|
context: ElectronContext,
|
|
roots: readonly string[],
|
|
completeness: CdpCaptureCompleteness,
|
|
): Promise<ElectronPageInspection["dom"]> => {
|
|
const result = requiredRecord(
|
|
await context.connection.send(
|
|
"DOMSnapshot.captureSnapshot",
|
|
{ computedStyles: [], includePaintOrder: false, includeDOMRects: false },
|
|
context.sessionId,
|
|
context.signal,
|
|
),
|
|
);
|
|
const strings = Array.isArray(result.strings)
|
|
? result.strings.map((value) => (typeof value === "string" ? value : ""))
|
|
: [];
|
|
const nodes: ElectronPageInspection["dom"]["nodes"] = [];
|
|
let total = 0;
|
|
for (const document of recordsValue(result.documents)) {
|
|
const documentUrl = stringAt(strings, document.documentURL);
|
|
if ((await authorizedElectronFile(documentUrl, roots)) === undefined) {
|
|
completeness.exclude("dom", "out_of_target_scope");
|
|
continue;
|
|
}
|
|
const nodeData = recordValue(document.nodes);
|
|
const nodeTypes = arrayValue(nodeData?.nodeType);
|
|
const nodeNames = arrayValue(nodeData?.nodeName);
|
|
const nodeValues = arrayValue(nodeData?.nodeValue);
|
|
const parents = arrayValue(nodeData?.parentIndex);
|
|
const attributes = arrayValue(nodeData?.attributes);
|
|
const baseIndex = nodes.length;
|
|
total += nodeTypes.length;
|
|
for (let index = 0; index < nodeTypes.length; index += 1) {
|
|
if (nodes.length >= context.input.limits.max_dom_nodes) continue;
|
|
const attributeIndexes = arrayValue(attributes[index]);
|
|
const parent = integer(parents[index], -1);
|
|
nodes.push({
|
|
index: nodes.length,
|
|
parent_index: parent < 0 ? -1 : baseIndex + parent,
|
|
node_type: integer(nodeTypes[index], 0),
|
|
node_name: stringAt(strings, nodeNames[index]).slice(0, 1_024),
|
|
node_value_length: Buffer.byteLength(
|
|
stringAt(strings, nodeValues[index]),
|
|
),
|
|
attribute_names: attributeIndexes
|
|
.filter((_value, attributeIndex) => attributeIndex % 2 === 0)
|
|
.map((value) => stringAt(strings, value).slice(0, 1_024))
|
|
.slice(0, 256),
|
|
});
|
|
}
|
|
}
|
|
if (total > nodes.length) completeness.truncate("dom");
|
|
return { total_nodes: total, nodes };
|
|
};
|
|
|
|
const captureScripts = async (
|
|
context: ElectronContext,
|
|
roots: readonly string[],
|
|
scripts: readonly ScriptDraft[],
|
|
completeness: CdpCaptureCompleteness,
|
|
): Promise<ElectronPageInspection["scripts"]> => {
|
|
let total = 0;
|
|
let sourceBytes = 0;
|
|
const items: ElectronPageInspection["scripts"]["items"] = [];
|
|
const seen = new Set<string>();
|
|
for (const script of scripts) {
|
|
const path = await authorizedElectronFile(script.rawUrl, roots);
|
|
if (path === undefined) {
|
|
completeness.exclude("scripts", "out_of_target_scope");
|
|
continue;
|
|
}
|
|
const identity = {
|
|
file_path: path,
|
|
cdp_hash: script.hash,
|
|
length: script.length,
|
|
is_module: script.isModule,
|
|
language: script.language,
|
|
};
|
|
const scriptKey = `electron_script_${digest(identity)}`;
|
|
if (seen.has(scriptKey)) continue;
|
|
seen.add(scriptKey);
|
|
total += 1;
|
|
if (items.length >= context.input.limits.max_scripts) {
|
|
completeness.drop("scripts");
|
|
continue;
|
|
}
|
|
let source: ElectronPageInspection["scripts"]["items"][number]["source"] = {
|
|
included: false,
|
|
reason: "source capture was not approved",
|
|
};
|
|
if (context.input.include_script_sources) {
|
|
if (
|
|
script.length > context.input.limits.max_script_source_bytes ||
|
|
sourceBytes + script.length >
|
|
context.input.limits.max_total_script_source_bytes
|
|
) {
|
|
source = {
|
|
included: false,
|
|
reason: "script source byte limit reached",
|
|
};
|
|
completeness.truncate("script_sources");
|
|
} else {
|
|
const result = requiredRecord(
|
|
await context.connection.send(
|
|
"Debugger.getScriptSource",
|
|
{ scriptId: script.scriptId },
|
|
context.sessionId,
|
|
context.signal,
|
|
),
|
|
);
|
|
const text = stringValue(result.scriptSource) ?? "";
|
|
const bytes = Buffer.byteLength(text);
|
|
if (
|
|
bytes > context.input.limits.max_script_source_bytes ||
|
|
sourceBytes + bytes >
|
|
context.input.limits.max_total_script_source_bytes
|
|
) {
|
|
source = {
|
|
included: false,
|
|
reason: "script source byte limit reached",
|
|
};
|
|
completeness.truncate("script_sources");
|
|
} else {
|
|
source = {
|
|
included: true,
|
|
artifact: createWebTextArtifact(text, "text/javascript"),
|
|
};
|
|
sourceBytes += bytes;
|
|
}
|
|
}
|
|
}
|
|
items.push({
|
|
script_key: scriptKey,
|
|
...identity,
|
|
source,
|
|
});
|
|
}
|
|
if (!context.input.include_script_sources)
|
|
completeness.exclude("script_sources", "not_approved", total);
|
|
return {
|
|
total,
|
|
items: items.sort((left, right) =>
|
|
left.script_key.localeCompare(right.script_key),
|
|
),
|
|
};
|
|
};
|
|
|
|
const mainFilePath = async (
|
|
result: unknown,
|
|
roots: readonly string[],
|
|
): Promise<string | undefined> => {
|
|
const frameTree = recordValue(requiredRecord(result).frameTree);
|
|
const frame = recordValue(frameTree?.frame);
|
|
return await authorizedElectronFile(stringValue(frame?.url) ?? "", roots);
|
|
};
|
|
|
|
const arrayValue = (value: unknown): readonly unknown[] =>
|
|
Array.isArray(value) ? value : [];
|
|
|
|
const stringAt = (strings: readonly string[], value: unknown): string =>
|
|
strings[integer(value, -1)] ?? "";
|
|
|
|
const integer = (value: unknown, fallback: number): number => {
|
|
const number = numberValue(value);
|
|
return number === undefined ? fallback : Math.trunc(number);
|
|
};
|
|
|
|
const nonnegativeInteger = (value: unknown): number =>
|
|
Math.max(0, integer(value, 0));
|
|
|
|
const digest = (value: unknown): string => {
|
|
const encoded = canonicalize(value);
|
|
if (encoded === undefined) throw new TypeError("Expected canonical JSON");
|
|
return createHash("sha256").update(encoded).digest("hex");
|
|
};
|
|
|
|
const report = async (
|
|
progress: ProgressReporter | undefined,
|
|
completed: number,
|
|
message: string,
|
|
): Promise<void> =>
|
|
await progress?.report({
|
|
phase: "browser_observation",
|
|
completed,
|
|
total: 3,
|
|
message,
|
|
...(completed === 3 ? { terminal: true } : {}),
|
|
});
|