Files
reverse-engineering-anything/src/domain/browserObservation.test.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

387 lines
13 KiB
TypeScript

import { describe, expect, it } from "vitest";
import {
browserEndpointSchema,
browserObservationEndpointSchema,
browserOriginSchema,
recordedBrowserOriginSchema,
recordedBrowserObservationEndpointSchema,
browserUrlTargetIdentity,
sanitizeEndpointCandidate,
sanitizeBrowserUrl,
} from "./browserObservation.js";
import { unknownTarget, urlTargetIdentitySchema } from "./targetIdentity.js";
import { webPageInspectionSchema } from "./browserObservationSchemas.js";
import { createWebPageInspection } from "../../tests/support/browser/webPageInspection.js";
describe("browser observation contracts", () => {
it.each(["127.0.0.1", "[::1]"])(
"preserves explicitly supplied default endpoint ports on %s",
(host) => {
const http = `http://${host}:80`;
expect(browserEndpointSchema.parse(http)).toBe(http);
expect(
browserEndpointSchema.parse(browserEndpointSchema.parse(http)),
).toBe(http);
expect(recordedBrowserObservationEndpointSchema.parse(http)).toBe(http);
const socket = `ws://${host}:80/devtools/browser/id`;
expect(browserObservationEndpointSchema.parse(socket)).toEqual({
transport: "browser_websocket",
url: socket,
recorded: `ws://${host}:80/devtools/browser/[REDACTED]`,
});
for (const value of [
`http://${host}`,
`ws://${host}/devtools/browser/id`,
"http://192.0.2.1:80",
])
expect(
browserObservationEndpointSchema.safeParse(value).success,
value,
).toBe(false);
},
);
it("normalizes exact HTTP origins without accepting broader URL scopes", () => {
expect(browserOriginSchema.parse("https://Example.COM:443")).toBe(
"https://example.com",
);
expect(browserOriginSchema.parse("http://example.com:80")).toBe(
"http://example.com",
);
for (const value of [
"https://*.example.com",
"https://example.com/path",
"https://example.com/?token=secret",
"https://example.com/?",
"https://example.com/#",
"https://user:pass@example.com",
"file:///tmp/page.html",
])
expect(browserOriginSchema.safeParse(value).success, value).toBe(false);
});
it("accepts only canonical recorded HTTP origins", () => {
expect(recordedBrowserOriginSchema.parse("https://app.example.test")).toBe(
"https://app.example.test",
);
for (const value of [
"https://%2A.example.com",
"https://*.example.com",
"https://Example.COM:443",
])
expect(recordedBrowserOriginSchema.safeParse(value).success, value).toBe(
false,
);
});
it("accepts only literal loopback HTTP CDP endpoints", () => {
expect(browserEndpointSchema.parse("http://127.0.0.1:9222")).toBe(
"http://127.0.0.1:9222",
);
expect(browserEndpointSchema.parse("http://[::1]:9222")).toBe(
"http://[::1]:9222",
);
for (const value of [
"http://localhost:9222",
"http://192.168.1.2:9222",
"https://127.0.0.1:9222",
"http://127.0.0.1:9222/json/list",
"http://127.0.0.1:9222/?",
"http://127.0.0.1:9222/#",
"http://user:pass@127.0.0.1:9222",
])
expect(browserEndpointSchema.safeParse(value).success, value).toBe(false);
});
it("accepts a loopback browser socket and records it without its identifier", () => {
expect(
browserObservationEndpointSchema.parse("http://127.0.0.1:9222/"),
).toEqual({
transport: "http_discovery",
url: "http://127.0.0.1:9222",
recorded: "http://127.0.0.1:9222",
});
expect(
browserObservationEndpointSchema.parse(
"ws://[::1]:9222/devtools/browser/0b1c-socket-id",
),
).toEqual({
transport: "browser_websocket",
url: "ws://[::1]:9222/devtools/browser/0b1c-socket-id",
recorded: "ws://[::1]:9222/devtools/browser/[REDACTED]",
});
for (const value of [
"ws://127.0.0.1/devtools/browser/id",
"ws://localhost:9222/devtools/browser/id",
"wss://127.0.0.1:9222/devtools/browser/id",
"ws://user:pass@127.0.0.1:9222/devtools/browser/id",
"ws://127.0.0.1:9222/devtools/browser/id?token=x",
"ws://127.0.0.1:9222/devtools/browser/id#fragment",
"ws://127.0.0.1:9222/devtools/browser/id?",
"ws://127.0.0.1:9222/devtools/browser/id#",
"ws://127.0.0.1:9222/devtools/browser/",
"ws://127.0.0.1:9222/devtools/browser/id/extra",
"ws://127.0.0.1:9222/devtools/page/id",
])
expect(
browserObservationEndpointSchema.safeParse(value).success,
value,
).toBe(false);
});
it("accepts recorded browser sockets only in their redacted form", () => {
for (const value of [
"http://127.0.0.1:9222",
"ws://127.0.0.1:9222/devtools/browser/[REDACTED]",
])
expect(
recordedBrowserObservationEndpointSchema.safeParse(value).success,
value,
).toBe(true);
expect(
recordedBrowserObservationEndpointSchema.safeParse(
"ws://127.0.0.1:9222/devtools/browser/0b1c-socket-id",
).success,
).toBe(false);
});
});
it("normalizes equivalent loopback browser-socket spellings while keeping IPv4, IPv6, and socket IDs distinct", () => {
expect(
browserObservationEndpointSchema.parse(
"WS://[0:0:0:0:0:0:0:1]:09222/devtools/browser/0b1c-socket-id",
),
).toEqual({
transport: "browser_websocket",
url: "ws://[::1]:9222/devtools/browser/0b1c-socket-id",
recorded: "ws://[::1]:9222/devtools/browser/[REDACTED]",
});
expect(
browserObservationEndpointSchema.parse(
"WS://127.0.0.1:0080/devtools/browser/0b1c-socket-id",
),
).toEqual({
transport: "browser_websocket",
url: "ws://127.0.0.1:80/devtools/browser/0b1c-socket-id",
recorded: "ws://127.0.0.1:80/devtools/browser/[REDACTED]",
});
expect(
browserObservationEndpointSchema.parse(
"WS://[0000:0000:0000:0000:0000:0000:0000:0001]:09222/devtools/browser/0b1c-socket-id",
).url,
).toBe(
browserObservationEndpointSchema.parse(
"ws://[::1]:9222/devtools/browser/0b1c-socket-id",
).url,
);
expect(
browserObservationEndpointSchema.parse(
"ws://127.0.0.1:9222/devtools/browser/0b1c-socket-id",
).url,
).not.toBe(
browserObservationEndpointSchema.parse(
"ws://[::1]:9222/devtools/browser/0b1c-socket-id",
).url,
);
expect(
browserObservationEndpointSchema.parse(
"ws://127.0.0.1:9222/devtools/browser/Socket-Id",
).url,
).not.toBe(
browserObservationEndpointSchema.parse(
"ws://127.0.0.1:9222/devtools/browser/socket-id",
).url,
);
});
describe("browser observation sensitive surfaces and retention", () => {
it("removes only URL userinfo and preserves the original query and fragment", () => {
expect(
sanitizeBrowserUrl(
"https://user:pass@app.example.test/path?token=secret&mode=full&token=again#part",
),
).toEqual({
url: "https://app.example.test/path?token=secret&mode=full&token=again#part",
origin: "https://app.example.test",
query_parameter_names: ["token", "mode", "token"],
redacted: true,
});
const backslashAuthority = String.raw`https:\\user:pass@app.example.test/path?x=a+b&x=two#part`;
const sanitized = sanitizeBrowserUrl(backslashAuthority);
expect(sanitized.url).toBe(
"https://app.example.test/path?x=a+b&x=two#part",
);
expect(sanitized.url).not.toContain("user:pass");
expect(sanitized.redacted).toBe(true);
});
it("preserves path userinfo-like text after a special-scheme backslash", () => {
const suffix = String.raw`\path@tail/../keep?x=1#frag`;
expect(
sanitizeBrowserUrl(`https://user:pass@app.example.test${suffix}`),
).toEqual({
url: `https://app.example.test${suffix}`,
origin: "https://app.example.test",
query_parameter_names: ["x"],
redacted: true,
});
expect(sanitizeBrowserUrl(`https://app.example.test${suffix}`)).toEqual({
url: `https://app.example.test${suffix}`,
origin: "https://app.example.test",
query_parameter_names: ["x"],
redacted: false,
});
expect(
sanitizeBrowserUrl(
String.raw`custom://user:pass@host\name@tail/path?x=1#frag`,
),
).toEqual({
url: "custom://tail/path?x=1#frag",
origin: null,
query_parameter_names: ["x"],
redacted: true,
});
expect(
sanitizeBrowserUrl("https://us\ter:pass@app.example.test/path?x=1#frag"),
).toEqual({
url: "https://app.example.test/path?x=1#frag",
origin: "https://app.example.test",
query_parameter_names: ["x"],
redacted: true,
});
});
it("retains ordinary query values and malformed URL diagnostics", () => {
const longName = `a${"x".repeat(400)}`;
const parameters = [
`${longName}=secret`,
...Array.from(
{ length: 300 },
(_value, index) => `k${String(index).padStart(3, "0")}=secret`,
),
].join("&");
const sanitized = sanitizeBrowserUrl(
`https://app.example.test/path?${parameters}`,
);
expect(sanitized.query_parameter_names).toHaveLength(301);
expect(sanitized.query_parameter_names).toContain(longName);
expect(sanitized.url).toContain(`${longName}=secret`);
expect(sanitized.url).toContain("k299=secret");
const oversized = sanitizeBrowserUrl(
`https://app.example.test/${"p".repeat(70_000)}`,
);
expect(oversized.origin).toBe("https://app.example.test");
expect(oversized.url.length).toBeGreaterThan(70_000);
expect(oversized.redacted).toBe(false);
const malformed = "https://[invalid?token=diagnostic#fragment";
expect(sanitizeBrowserUrl(malformed)).toEqual({
url: malformed,
origin: null,
query_parameter_names: [],
redacted: false,
});
expect(sanitizeEndpointCandidate(malformed)).toBe(malformed);
expect(sanitizeEndpointCandidate("/api/search?q=rea#results")).toBe(
"/api/search?q=rea#results",
);
});
});
describe("page inspection producer facts", () => {
const inspection = () =>
createWebPageInspection([
{
source: "fetch('/api');",
scriptKey: `scr_${"a".repeat(64)}`,
url: "https://app.example.test/main.js",
origin: "https://app.example.test",
cdpHash: "hash",
},
]);
const axNode = {
node_id: "root",
parent_id: null,
role: "RootWebArea",
name: null,
description: null,
ignored: false,
states: [],
};
const worker = {
target_id: "worker-1",
type: "worker",
url: "https://app.example.test/worker.js",
origin: "https://app.example.test",
attached: false,
opener_target_id: null,
parent_frame_id: null,
};
it.each([
["script frame_id", ["scripts", "items", 0, "frame_id"]],
["accessibility states", ["accessibility", "nodes", 0, "states"]],
["worker opener_target_id", ["workers", 0, "opener_target_id"]],
["worker parent_frame_id", ["workers", 0, "parent_frame_id"]],
] as const)("refuses an inspection without the %s", (_label, path) => {
const base = inspection();
const input = structuredClone({
...base,
accessibility: { ...base.accessibility, nodes: [axNode] },
workers: [worker],
});
expect(webPageInspectionSchema.safeParse(input).success).toBe(true);
const parent = path
.slice(0, -1)
.reduce<unknown>(
(value, key) => Reflect.get(value as object, key),
input,
);
Reflect.deleteProperty(parent as object, path.at(-1)!);
const parsed = webPageInspectionSchema.safeParse(input);
expect(parsed.success).toBe(false);
expect(parsed.error?.issues.map((issue) => issue.path)).toContainEqual(
path,
);
});
});
describe("browser URL target identity", () => {
it("names the reported page URL without userinfo, keeping its query and fragment", () => {
const identity = browserUrlTargetIdentity(
"https://user:pass@app.example.test/path?token=secret#part",
);
expect(identity).toEqual({
kind: "url",
url: "https://app.example.test/path?token=secret#part",
origin: "https://app.example.test",
});
expect(urlTargetIdentitySchema.parse(identity)).toEqual(identity);
const backslash = browserUrlTargetIdentity(
String.raw`https:\\user:pass@app.example.test/path`,
);
expect(urlTargetIdentitySchema.parse(backslash)).toMatchObject({
origin: "https://app.example.test",
});
expect(JSON.stringify(backslash)).not.toContain("user:pass");
});
it("names an opaque origin as null", () => {
expect(browserUrlTargetIdentity("about:blank")).toEqual({
kind: "url",
url: "about:blank",
origin: null,
});
});
it("does not identify a document whose URL was withheld or is not a URL", () => {
for (const value of ["[unsupported-url]", ""])
expect(browserUrlTargetIdentity(value)).toEqual(
unknownTarget("not-observed"),
);
});
});