Files
reverse-engineering-anything/src/application/BrowserEvidence.ts
T
morluto ff0176256a feat(snapshots)!: persist the target identity as the snapshot target (#11551)
* feat(snapshots)!: persist the target identity as the snapshot target

The snapshot target is now `{ kind, identity }`, where `identity` is the
FileTargetIdentity that `binaryTargetIdentity` produces and `kind` is the
binary kind query IDs commit to. The per-format target projection and
`snapshotTargetIdentity` are deleted; the schema checks the format's
selection, architecture and kind instead of keeping one union arm per format.

Entry execution subjects use the Evidence subject shape (file or explicit
unknown), so a snapshot entry commits to the same identity, including the
selection, as its Evidence record. Workflow entries take the subject of the
workflow's own Evidence. Replay no longer re-derives the selection from the
open target.

`FileTargetSelection` gains `universal-slice` (`offset`, `size`, and the FAT
`cpu_type`/`cpu_subtype` when target admission supplied the FAT table, else
null). `binaryTargetIdentity` produces it for `mach-o-universal` targets, so
Evidence and snapshots for different slices of one container no longer share
an identity.

Refs #11417

BREAKING CHANGE: analysis snapshot files change shape: `target` is
`{ kind, identity: { kind: "file", sha256, format, architecture, selection } }`
and entry `execution.subject` is the Evidence subject
(`{ identity, name, local_path }`, never null). Snapshot binding mismatch
details report `target.snapshot`/`target.selected` in the same shape. Evidence
IDs of universal Mach-O targets change because their subject identity now
carries the selected slice. Recreate saved snapshots and Evidence bundles of
universal Mach-O targets.

* docs(evidence): name the universal Mach-O slice selection in the subject contract

* fix(snapshots): read the snapshot target identity in the Ghidra verification scripts

The real Ghidra snapshot checks (lifecycle, RISC-V, MIPS, PowerPC) read
snapshot.target.sha256 and .architecture, which moved under
snapshot.target.identity, so they would fail after saving a valid snapshot.

* feat(evidence)!: name live browser page Evidence by its page URL (#11559)

Browser page observations (inspect_web_page, analyze_web_bundle,
observe_web_session, discover_webmcp_tools, capture_web_screenshot,
observe_web_execution, inspect_web_event_listeners) named an unknown
(`not-observed`) subject although the provider reports the page URL.

`TargetIdentity` gains a `url` kind: the reported URL with userinfo removed
and its origin (`null` for an opaque origin). The schema refuses a URL that
carries userinfo or an origin the URL does not have.
`browserUrlTargetIdentity` in the browser URL owner builds it from the
provider's reported URL; a withheld or unparseable URL stays unknown
(`not-observed`). Target lists and comparisons still name no single
document. Analysis views keep their parent's URL subject, as they already
keep a file subject.

BREAKING CHANGE: Evidence IDs of live browser page observations and their
analysis views change, and their subject is
`{ "kind": "url", "url", "origin" }` with `name` and `local_path` null.
Recreate stored Evidence for these tools. This lands inside Evidence format
revision 2 under the release hold (#11417); no `evidence_format` bump.
2026-11-16 07:04:34 +08:00

325 lines
11 KiB
TypeScript

import {
unknownTarget,
type NonFileTargetIdentity,
} from "../domain/targetIdentity.js";
import { isDeepStrictEqual } from "node:util";
import type { ProviderIdentity } from "../ports/AnalysisProvider.js";
import {
createEvidence,
type Evidence,
type EvidenceObservation,
} from "../domain/evidence.js";
import {
browserUrlTargetIdentity,
sanitizeBrowserUrl,
} from "../domain/browserObservation.js";
import type {
InspectWebPageInput,
ListBrowserTargetsInput,
} from "../domain/browserObservation.js";
import type {
BrowserTargetList,
WebPageInspection,
} from "../domain/browserObservationSchemas.js";
import type {
AnalyzeWebBundleInput,
WebBundleAcquisitionPartialObservation,
WebBundleAnalysis,
} from "../domain/webBundleAnalysis.js";
import type {
ObserveWebSessionInput,
WebObservationSession,
} from "../domain/browserSession.js";
import type {
DiscoverWebMcpToolsInput,
WebMcpDiscovery,
} from "../domain/webMcpDiscovery.js";
import type {
BrowserCaptureComparison,
BrowserCaptureComparisonInput,
} from "../domain/browserCaptureComparison.js";
import { commitBrowserScenarioNormalization } from "../domain/browserScenarioNormalization.js";
import { digestCanonicalValue } from "../domain/canonicalDigest.js";
import type {
CaptureWebScreenshotInput,
CompareWebScreenshotsInput,
WebScreenshot,
WebScreenshotDiff,
} from "../domain/webScreenshot.js";
import type { JsonValue } from "../domain/jsonValue.js";
/** The own JSON source and the facts admitted by its named output contract. */
export interface BrowserEvidenceReport {
readonly source: JsonValue;
readonly facts: BrowserEvidenceResult;
}
type BrowserEvidenceInput =
| ListBrowserTargetsInput
| InspectWebPageInput
| AnalyzeWebBundleInput
| ObserveWebSessionInput
| DiscoverWebMcpToolsInput
| BrowserCaptureComparisonInput
| CaptureWebScreenshotInput
| CompareWebScreenshotsInput;
type BrowserEvidenceResult =
| BrowserTargetList
| WebPageInspection
| WebBundleAnalysis
| WebBundleAcquisitionPartialObservation
| WebObservationSession
| WebMcpDiscovery
| BrowserCaptureComparison
| WebScreenshot
| WebScreenshotDiff;
type BrowserEvidenceOperation =
| "list_browser_targets"
| "inspect_web_page"
| "analyze_web_bundle"
| "observe_web_session"
| "discover_webmcp_tools"
| "compare_web_captures"
| "capture_web_screenshot"
| "compare_web_screenshots";
const isBundleAcquisition = (
result: BrowserEvidenceResult,
): result is WebBundleAcquisitionPartialObservation =>
"kind" in result && result.kind === "web-bundle-acquisition";
/** Create Evidence for one request-scoped external browser observation. */
export const createBrowserEvidence = (
operation: BrowserEvidenceOperation,
input: BrowserEvidenceInput,
report: BrowserEvidenceReport,
provider: ProviderIdentity,
): Evidence => {
const result = report.facts;
const acquisition = isBundleAcquisition(result);
const observed = acquisition ? result.inspection : result;
const comparison =
operation === "compare_web_captures" ||
operation === "compare_web_screenshots";
return createEvidence(browserSubject(operation, observed), provider, {
predicateType: browserPredicate(operation),
operation,
parameters: {
...browserParameters(input, result),
...(comparison
? {
comparison_input_sha256: digestCanonicalValue(
input,
"Browser comparison input",
),
}
: {}),
},
result,
rawResult: isDeepStrictEqual(report.source, result) ? null : report.source,
confidence: comparison ? "derived" : "observed",
authority: comparison ? "analyst-inference" : "external-service",
environment:
"browser" in observed
? {
id: `${observed.browser.product}@${observed.browser.revision}`,
platform: "unknown",
architecture: "unknown",
isolation: "none",
}
: null,
limitations: [
...observed.limitations,
...(acquisition && result.source_maps.limitation !== undefined
? [result.source_maps.limitation]
: []),
...("browser" in observed
? ["Browser host platform and architecture were not observed."]
: []),
],
});
};
/**
* The document one page observation is about: the URL the provider reported
* for it. Target lists and comparisons observe no single document.
*/
const browserSubject = (
operation: BrowserEvidenceOperation,
observed: Exclude<
BrowserEvidenceResult,
WebBundleAcquisitionPartialObservation
>,
): NonFileTargetIdentity => {
switch (operation) {
case "list_browser_targets":
case "compare_web_captures":
case "compare_web_screenshots":
return unknownTarget("not-observed");
case "analyze_web_bundle":
// A completed analysis reports its captured page; an acquisition that
// stopped before analysis reports the page inspection itself.
if ("capture" in observed && "target_url" in observed.capture)
return browserUrlTargetIdentity(observed.capture.target_url);
if ("target" in observed && "url" in observed.target)
return browserUrlTargetIdentity(observed.target.url);
break;
case "observe_web_session":
if ("target" in observed && "initial_url" in observed.target)
return browserUrlTargetIdentity(observed.target.initial_url);
break;
case "inspect_web_page":
case "discover_webmcp_tools":
case "capture_web_screenshot":
if ("target" in observed && "url" in observed.target)
return browserUrlTargetIdentity(observed.target.url);
break;
}
throw new Error(`Browser ${operation} result does not report its document`);
};
const browserParameters = (
input: BrowserEvidenceInput,
result: BrowserEvidenceResult,
): EvidenceObservation["parameters"] => {
if (!("cdp_endpoint" in input)) {
if ("before_scenario" in input)
return {
comparison_kind: "browser_scenario",
before_browser: input.before_scenario.browser,
after_browser: input.after_scenario.browser,
before_start_origin: input.before_scenario.scenario.start_origin,
after_start_origin: input.after_scenario.scenario.start_origin,
normalization_sha256: commitBrowserScenarioNormalization(
input.normalization,
).sha256,
};
if ("inspection" in input.before && "inspection" in input.after)
return {
before_target_id: input.before.inspection.target.target_id,
before_capture_ended_at:
input.before.inspection.capture_window.ended_at,
after_target_id: input.after.inspection.target.target_id,
after_capture_ended_at: input.after.inspection.capture_window.ended_at,
};
if (isScreenshotComparison(input))
return {
before_artifact_sha256: input.before.sha256,
after_artifact_sha256: input.after.sha256,
channel_threshold: input.channel_threshold,
};
throw new Error("Browser comparison input did not match a comparison type");
}
const observedOrigin = browserResultTargetOrigin(result);
const scope = {
cdp_endpoint: input.cdp_endpoint.recorded,
allowed_origins:
input.allowed_origins.length > 0
? input.allowed_origins
: "target_id" in input && observedOrigin !== undefined
? [observedOrigin]
: [],
...("discovery_timeout_ms" in input &&
input.discovery_timeout_ms !== undefined
? { discovery_timeout_ms: input.discovery_timeout_ms }
: {}),
...("command_timeout_ms" in input && input.command_timeout_ms !== undefined
? { command_timeout_ms: input.command_timeout_ms }
: {}),
};
if (!("target_id" in input)) return scope;
return {
...scope,
target_id: input.target_id,
...("observation_ms" in input
? { observation_ms: input.observation_ms }
: {}),
...("include_accessibility_text" in input
? {
include_accessibility_text: input.include_accessibility_text,
include_console_text: input.include_console_text,
include_json_body_shapes: input.include_json_body_shapes,
include_websocket_shapes: input.include_websocket_shapes,
include_storage_keys: input.include_storage_keys,
include_storage_fingerprints: input.include_storage_fingerprints,
...("include_script_sources" in input
? { include_script_sources: input.include_script_sources }
: {}),
}
: {}),
...("fetch_source_maps" in input
? {
fetch_source_maps: input.fetch_source_maps,
...(input.source_map_limits === undefined
? {}
: { source_map_limits: input.source_map_limits }),
...(input.semantic_precision === undefined
? {}
: { semantic_precision: input.semantic_precision }),
...(input.max_heap_mb === undefined
? {}
: { max_heap_mb: input.max_heap_mb }),
...(input.analysis_timeout_ms === undefined
? {}
: { analysis_timeout_ms: input.analysis_timeout_ms }),
...(input.total_analysis_timeout_ms === undefined
? {}
: { total_analysis_timeout_ms: input.total_analysis_timeout_ms }),
...(input.source_map_fetch_timeout_ms === undefined
? {}
: {
source_map_fetch_timeout_ms: input.source_map_fetch_timeout_ms,
}),
}
: {}),
};
};
const browserResultTargetOrigin = (
result: BrowserEvidenceResult,
): string | undefined => {
if (
"inspection" in result &&
typeof result.inspection === "object" &&
result.inspection !== null &&
"target" in result.inspection &&
typeof result.inspection.target === "object" &&
result.inspection.target !== null &&
"origin" in result.inspection.target &&
typeof result.inspection.target.origin === "string"
)
return result.inspection.target.origin;
if ("capture" in result) return result.capture.target_origin ?? undefined;
if (!("target" in result)) return undefined;
if ("origin" in result.target) return result.target.origin;
if ("initial_url" in result.target)
return sanitizeBrowserUrl(result.target.initial_url).origin ?? undefined;
return undefined;
};
const isScreenshotComparison = (
input: BrowserEvidenceInput,
): input is CompareWebScreenshotsInput => "channel_threshold" in input;
const browserPredicate = (operation: BrowserEvidenceOperation): string => {
switch (operation) {
case "list_browser_targets":
return "rea.browser-target-list";
case "inspect_web_page":
return "rea.web-page-inspection";
case "analyze_web_bundle":
return "rea.web-bundle-analysis";
case "observe_web_session":
return "rea.web-observation-session";
case "discover_webmcp_tools":
return "rea.webmcp-discovery";
case "compare_web_captures":
return "rea.web-capture-diff";
case "capture_web_screenshot":
return "rea.web-screenshot";
case "compare_web_screenshots":
return "rea.web-screenshot-diff";
}
};