@parity/product-lab 0.0.1-placeholder → 0.1.1

package/adapters/browser/playwright/src/network-evidence.js

@@ -0,0 +1,575 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { installNativeRtcReceiver } from "./native-rtc.js";
+import { evidenceText, evidenceUrl } from "./evidence-url.js";
+import { WorkerHold } from "./worker-hold.js";
+export const workerRaceGap = (why) => `Worker initialization can race another DevTools session's resume; initial traffic may be missing${why ? ` (worker start not held: ${why})` : ""}`;
+const MAX_PAYLOAD = 65_536;
+const MAX_FINDINGS = 20_000;
+const MAX_SOCKETS = 1_024;
+const HANDSHAKE_WAIT_MS = 2_000;
+const ASSETS = new Set(["Document", "Script", "Stylesheet", "Image", "Font", "Media", "Manifest"]);
+const unavailable = (gaps) => ({ observations: [], coverage: { beforeNavigation: false, pages: false, workers: false, gaps } });
+export function classifyPayload(payload, binary = false) {
+    if (binary)
+        return { operation: "opaque", detail: "Binary traffic, including light-client traffic, cannot be classified as a chain read or submission" };
+    if (payload === undefined)
+        return { operation: "opaque", detail: "Request payload was unavailable" };
+    if (Buffer.byteLength(payload) > MAX_PAYLOAD)
+        return { operation: "opaque", detail: `Payload exceeded the ${MAX_PAYLOAD}-byte classification limit` };
+    let value;
+    try {
+        value = JSON.parse(payload);
+    }
+    catch {
+        return { operation: "opaque", detail: "Payload is not visible JSON-RPC" };
+    }
+    const requests = Array.isArray(value) ? value : [value];
+    if (requests.length > 64)
+        return { operation: "opaque", detail: "JSON-RPC batch exceeded the 64-method classification limit" };
+    const methods = requests.map((request) => request && typeof request === "object" && typeof request.method === "string" ? request.method : undefined);
+    if (!methods.length || methods.some((method) => !method))
+        return { operation: "opaque", detail: "Payload has no visible JSON-RPC method" };
+    if (methods.some((method) => method.length > 128 || !/^[A-Za-z0-9_]+$/.test(method)))
+        return { operation: "opaque", detail: "JSON-RPC method exceeded the 128-character identifier limit or was not a method identifier" };
+    const submit = (method) => /^(author_submit(?:AndWatch)?Extrinsic|transaction_v1_broadcast|transactionWatch_v1_submitAndWatch)$/.test(method);
+    const read = (method) => /^(chain_|chainHead_v1_|state_|system_|rpc_methods$|payment_query|author_pendingExtrinsics$|author_unwatchExtrinsic$|transaction_v1_stop$|transactionWatch_v1_unwatch$)/.test(method);
+    const names = methods;
+    const method = [...new Set(names)].join(", ");
+    if (method.length > 1_024)
+        return { operation: "opaque", detail: "Batch methods exceeded the 1024-character retained classification limit" };
+    if (names.every((name) => submit(name) || read(name)))
+        return { operation: names.some(submit) ? "submit" : "read", method };
+    return { operation: "opaque", method, detail: "JSON-RPC method is not classified as a read or submission" };
+}
+class Channel {
+    parent;
+    sessionId;
+    nextId = 0;
+    pending = new Map();
+    listeners = new Map();
+    constructor(parent, sessionId) {
+        this.parent = parent;
+        this.sessionId = sessionId;
+        parent.on("Target.receivedMessageFromTarget", (params) => {
+            if (params.sessionId !== sessionId || typeof params.message !== "string")
+                return;
+            const message = JSON.parse(params.message);
+            if (message.id !== undefined) {
+                const pending = this.pending.get(message.id);
+                this.pending.delete(message.id);
+                if (message.error)
+                    pending?.reject(new Error(message.error.message));
+                else
+                    pending?.resolve(message.result ?? {});
+            }
+            else if (message.method)
+                for (const listener of this.listeners.get(message.method) ?? [])
+                    listener(message.params ?? {});
+        });
+    }
+    async send(method, params = {}) {
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`CDP ${method} timed out`)); }, 5_000);
+            timer.unref();
+            this.pending.set(id, { resolve: (value) => { clearTimeout(timer); resolve(value); }, reject: (error) => { clearTimeout(timer); reject(error); } });
+            void this.parent.send("Target.sendMessageToTarget", { sessionId: this.sessionId, message: JSON.stringify({ id, method, params }) }).catch((error) => {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(error);
+            });
+        });
+    }
+    on(method, listener) { this.listeners.set(method, [...(this.listeners.get(method) ?? []), listener]); }
+}
+const FILTER = [{ type: "page", exclude: false }, { type: "iframe", exclude: false }, { type: "worker", exclude: false }, { type: "shared_worker", exclude: false }, { type: "service_worker", exclude: false }, { exclude: true }];
+class BrowserEvidence {
+    findings = [];
+    gaps = [];
+    targets = new Map();
+    frameParents = new Map();
+    frameNames = new Map();
+    frameUrls = new Map();
+    nextFinding = 0;
+    opening = new Set();
+    root;
+    error;
+    diagnosticTarget;
+    diagnosticContext;
+    hold;
+    holdOff;
+    ready;
+    constructor(browser, holding = { off: "no debugging port was given to this browser's observer" }) {
+        if (typeof browser.on === "function")
+            browser.on("disconnected", () => this.hold?.close());
+        this.ready = this.install(browser, holding).catch((error) => {
+            this.error = evidenceText(`Chromium network observation unavailable: ${error instanceof Error ? error.message : String(error)}`);
+            this.gap(undefined, this.error);
+        });
+    }
+    gap(target, text) {
+        text = evidenceText(text);
+        if (!this.gaps.some((gap) => gap.context === target?.info.browserContextId && gap.owner === target?.owner && gap.text === text))
+            this.gaps.push({ context: target?.info.browserContextId, owner: target?.owner, text });
+    }
+    record(target, value, frame = target.frame, candidates) {
+        if (this.findings.length >= MAX_FINDINGS) {
+            this.gap(target, `Browser evidence exceeded ${MAX_FINDINGS} findings; later observations were not retained`);
+            return;
+        }
+        const document = frame ? this.frameUrls.get(frame) : undefined;
+        const observation = { id: `browser-${++this.nextFinding}`, at: Date.now(), ...value, endpoint: evidenceUrl(value.endpoint), ...(value.detail ? { detail: evidenceText(value.detail) } : {}), ...(document ? { document } : {}) };
+        this.findings.push({ context: target.info.browserContextId, owner: target.owner, ...(frame ? { frame } : {}), ...(!frame && candidates?.length ? { candidates } : {}), observation });
+        return observation;
+    }
+    inFrame(frame, name) {
+        for (let id = frame, depth = 0; id !== undefined && depth < 64; id = this.frameParents.get(id), depth++)
+            if (this.frameNames.get(id) === name)
+                return true;
+        return false;
+    }
+    async install(browser, holding) {
+        if ("off" in holding)
+            this.holdOff = `the debugging port is off because ${holding.off}`;
+        else {
+            try {
+                this.hold = await WorkerHold.open(holding.debuggingPort, (targetId) => this.targets.has(targetId));
+            }
+            catch (error) {
+                this.holdOff = evidenceText(`the hold could not connect: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const session = await browser.newBrowserCDPSession();
+        this.root = { send: session.send.bind(session), on: session.on.bind(session) };
+        await this.nativeRtc();
+        this.attachListener(this.root);
+        this.root.on("Target.targetInfoChanged", (params) => {
+            const info = params.targetInfo;
+            const target = this.targets.get(info?.targetId);
+            if (target) {
+                target.info.url = info.url ? evidenceUrl(info.url) : undefined;
+                this.document(target, info.url, target.source);
+            }
+        });
+        this.root.on("Target.targetDestroyed", (params) => {
+            if (params.targetId === this.diagnosticTarget)
+                this.gap(undefined, "Native WebRTC tracker closed; later peer traffic is unobserved");
+        });
+        this.root.on("Target.targetCreated", (params) => {
+            const info = params.targetInfo;
+            if (this.diagnostic(info))
+                return;
+            if (info?.type === "page" && !this.targets.has(info.targetId)) {
+                void this.root.send("Target.attachToTarget", { targetId: info.targetId, flatten: false }).catch((error) => this.gap(undefined, `New page observation could not attach: ${String(error)}`));
+            }
+            else if (info?.type === "shared_worker" && !this.targets.has(info.targetId)) {
+                this.gap({ info, source: "shared-worker", ready: Promise.resolve() }, "Shared worker attachment is asynchronous; initial traffic before CDP attached may be missing");
+                void this.root.send("Target.attachToTarget", { targetId: info.targetId, flatten: false }).catch((error) => this.gap(undefined, `Shared worker observation could not attach: ${String(error)}`));
+            }
+        });
+        await this.root.send("Target.setDiscoverTargets", { discover: true, filter: FILTER });
+    }
+    diagnostic(info) { return !!info && (info.targetId === this.diagnosticTarget || info.browserContextId === this.diagnosticContext); }
+    document(target, url, source) {
+        if (!url || url === "about:blank" || url.length > 2_048)
+            return;
+        url = evidenceUrl(url);
+        target.documents ??= new Map();
+        if (target.documents.size >= 1_024) {
+            this.gap(target, "Document attribution exceeded 1024 URLs; later WebRTC ownership may be unknown");
+            return;
+        }
+        const sources = target.documents.get(url) ?? new Set();
+        sources.add(source);
+        target.documents.set(url, sources);
+    }
+    async nativeRtc() {
+        const root = this.root;
+        try {
+            const context = await root.send("Target.createBrowserContext");
+            if (typeof context.browserContextId !== "string")
+                throw new Error("No diagnostic browser context was returned");
+            this.diagnosticContext = context.browserContextId;
+            const page = { url: "about:blank", background: true, browserContextId: this.diagnosticContext };
+            const created = await root.send("Target.createTarget", { ...page, hidden: true }).catch(async (error) => {
+                const version = await root.send("Browser.getVersion").catch(() => ({}));
+                if (typeof version.userAgent === "string" && version.userAgent.includes("HeadlessChrome"))
+                    return root.send("Target.createTarget", page);
+                throw new Error(`WebRTC peers in the lab window are not tracked: this browser cannot hide the tracker's page (${String(error)})`);
+            });
+            if (typeof created.targetId !== "string")
+                throw new Error("No diagnostic target was returned");
+            this.diagnosticTarget = created.targetId;
+            const attached = await root.send("Target.attachToTarget", { targetId: this.diagnosticTarget, flatten: false });
+            if (typeof attached.sessionId !== "string")
+                throw new Error("No diagnostic CDP session was returned");
+            const channel = new Channel(root, attached.sessionId);
+            const binding = "productLabNativeRtcEvidence";
+            channel.on("Runtime.bindingCalled", (params) => {
+                if (params.name !== binding || typeof params.payload !== "string")
+                    return;
+                const event = JSON.parse(params.payload);
+                if (event.gap)
+                    this.gap(undefined, event.gap);
+                else if (event.endpoint && event.detail) {
+                    if (this.findings.length >= MAX_FINDINGS) {
+                        this.gap(undefined, `Browser evidence exceeded ${MAX_FINDINGS} findings; later observations were not retained`);
+                        return;
+                    }
+                    this.findings.push({ rtc: true, document: event.document ? evidenceUrl(event.document) : undefined, observation: { id: `browser-${++this.nextFinding}`, at: event.at ?? Date.now(), endpoint: evidenceUrl(event.endpoint), transport: "other", source: "unknown", operation: "opaque", detail: evidenceText(event.detail) } });
+                }
+            });
+            channel.on("Inspector.targetCrashed", () => this.gap(undefined, "Native WebRTC tracker crashed; later peer traffic is unobserved"));
+            channel.on("Runtime.exceptionThrown", () => this.gap(undefined, "Native WebRTC diagnostic receiver raised an exception; peer transport coverage is incomplete"));
+            await channel.send("Runtime.enable");
+            await channel.send("Page.enable");
+            await channel.send("Runtime.addBinding", { name: binding });
+            await channel.send("Page.addScriptToEvaluateOnNewDocument", { source: `const __name = value => value; (${installNativeRtcReceiver.toString()})(${JSON.stringify(binding)}, (${evidenceUrl.toString()}))` });
+            let loaded = false;
+            channel.on("Page.loadEventFired", () => { loaded = true; });
+            const navigation = await channel.send("Page.navigate", { url: "chrome://webrtc-internals/" });
+            if (navigation.errorText)
+                throw new Error(String(navigation.errorText));
+            const deadline = Date.now() + 5_000;
+            while (!loaded && Date.now() < deadline)
+                await new Promise((resolve) => setTimeout(resolve, 10));
+            if (!loaded)
+                throw new Error("Diagnostic page load timed out");
+            const handshake = await channel.send("Runtime.evaluate", { expression: `(async()=>{const api=await import('chrome://resources/js/cr.js');const response=await api.sendWithPromise('finishedDOMLoad');return globalThis.productLabNativeRtcTrackerReady===true&&typeof response?.eventLogRecordingsEnabled==='boolean';})()`, awaitPromise: true, returnByValue: true });
+            if (handshake.exceptionDetails || handshake.result?.value !== true)
+                throw new Error("Native WebRTC tracker handshake failed");
+        }
+        catch (error) {
+            this.gap(undefined, `Native WebRTC observation unavailable: ${String(error)}; peer transport coverage is incomplete`);
+            if (this.diagnosticContext)
+                await root.send("Target.disposeBrowserContext", { browserContextId: this.diagnosticContext }).catch((cleanup) => this.gap(undefined, `Diagnostic context cleanup failed: ${String(cleanup)}`));
+            this.diagnosticContext = undefined;
+            this.diagnosticTarget = undefined;
+        }
+    }
+    attachListener(parent, inherited) {
+        parent.on("Target.attachedToTarget", (params) => {
+            const info = params.targetInfo;
+            if (!info?.targetId || typeof params.sessionId !== "string")
+                return;
+            if (this.diagnostic(info)) {
+                const diagnostic = new Channel(parent, params.sessionId);
+                void diagnostic.send("Runtime.runIfWaitingForDebugger").catch((error) => this.gap(undefined, `Diagnostic target resume failed: ${String(error)}`));
+                return;
+            }
+            if (!info.browserContextId && inherited?.info.browserContextId)
+                info.browserContextId = inherited.info.browserContextId;
+            const channel = new Channel(parent, params.sessionId);
+            const owner = info.type === "page" ? (info.openerId ? this.targets.get(info.openerId)?.owner ?? info.openerId : info.targetId) : (info.parentId ? this.targets.get(info.parentId)?.owner : undefined) ?? inherited?.owner;
+            const existing = this.targets.get(info.targetId);
+            if (existing) {
+                if (!existing.owner && owner) {
+                    existing.owner = owner;
+                }
+                void existing.ready.then(() => channel.send("Runtime.runIfWaitingForDebugger")).catch((error) => this.gap(existing, `Duplicate observer could not release the target: ${String(error)}`));
+                return;
+            }
+            const source = info.type === "worker" ? "dedicated-worker" : info.type === "shared_worker" ? "shared-worker" : info.type === "service_worker" ? "service-worker" : info.type === "iframe" ? "frame" : "page";
+            const frame = info.type === "iframe" ? info.targetId : /worker/.test(info.type) ? info.parentFrameId : undefined;
+            if (info.type === "iframe" && info.parentFrameId)
+                this.frameParents.set(info.targetId, info.parentFrameId);
+            const target = { info: { ...info, ...(info.url ? { url: evidenceUrl(info.url) } : {}) }, owner, ...(frame ? { frame } : {}), source, ready: Promise.resolve() };
+            this.targets.set(info.targetId, target);
+            this.document(target, info.url, source);
+            const held = info.type === "worker" && this.hold !== undefined;
+            if (/worker/.test(info.type) && !held)
+                this.gap(target, workerRaceGap(info.type === "worker" ? this.holdOff : undefined));
+            if (info.type === "page" && info.openerId)
+                this.gap(target, "Popup initialization can race another DevTools session's resume; initial traffic may be missing");
+            this.network(channel, target);
+            this.attachListener(channel, target);
+            target.ready = (async () => {
+                try {
+                    await channel.send("Network.enable", { maxPostDataSize: MAX_PAYLOAD });
+                    await channel.send("Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: true, flatten: false, filter: FILTER });
+                }
+                catch (error) {
+                    this.gap(target, `Network observation for ${info.type} failed: ${String(error)}`);
+                }
+                finally {
+                    await channel.send("Runtime.runIfWaitingForDebugger").catch((error) => this.gap(target, `Releasing observed ${info.type} failed: ${String(error)}`));
+                }
+                if (held && !(await this.hold.release(info.targetId)))
+                    this.gap(target, workerRaceGap("the hold did not have it paused"));
+            })();
+        });
+    }
+    network(channel, target) {
+        const sockets = new Map();
+        const frames = new Map();
+        const scriptFrames = new Map();
+        const present = new Set();
+        let mainFrame;
+        channel.on("Page.frameNavigated", (params) => {
+            const frame = params.frame;
+            if (typeof frame.id === "string")
+                present.add(frame.id);
+            if (typeof frame.id === "string" && typeof frame.url === "string") {
+                frames.set(frame.id, evidenceUrl(frame.url));
+                this.document(target, frame.url, frame.parentId ? "frame" : target.source);
+            }
+            if (!frame.parentId && typeof frame.id === "string")
+                mainFrame = frame.id;
+            if (typeof frame.id === "string") {
+                this.frameParents.set(frame.id, typeof frame.parentId === "string" ? frame.parentId : this.frameParents.get(frame.id));
+                if (typeof frame.name === "string")
+                    this.frameNames.set(frame.id, frame.name);
+                if (typeof frame.url === "string")
+                    this.frameUrls.set(frame.id, evidenceUrl(frame.url));
+            }
+        });
+        channel.on("Page.frameAttached", (params) => {
+            if (typeof params.frameId === "string")
+                present.add(params.frameId);
+            if (typeof params.frameId === "string" && typeof params.parentFrameId === "string")
+                this.frameParents.set(params.frameId, params.parentFrameId);
+        });
+        channel.on("Page.frameDetached", (params) => { if (typeof params.frameId === "string") {
+            frames.delete(params.frameId);
+            present.delete(params.frameId);
+        } });
+        if (target.source === "page" || target.source === "frame")
+            void channel.send("Page.enable").catch((error) => this.gap(target, `Page frame observation failed: ${String(error)}`));
+        channel.on("Network.requestWillBeSent", (params) => {
+            const request = params.request;
+            if (!request || typeof request.url !== "string" || !/^https?:/.test(request.url))
+                return;
+            const resource = typeof params.type === "string" ? params.type : "unknown";
+            const method = typeof request.method === "string" ? request.method : "unknown";
+            const source = target.source === "page" && mainFrame && params.frameId !== mainFrame ? "frame" : target.source;
+            if (resource === "Script" && typeof params.frameId === "string" && params.frameId && scriptFrames.size < MAX_SOCKETS * 4) {
+                const loaders = scriptFrames.get(evidenceUrl(request.url)) ?? new Set();
+                scriptFrames.set(evidenceUrl(request.url), loaders.add(params.frameId));
+            }
+            const classified = request.hasPostData || request.postData ? classifyPayload(typeof request.postData === "string" ? request.postData : undefined) : /^(GET|HEAD|OPTIONS)$/.test(method) ? { operation: "read", method } : classifyPayload(undefined);
+            let nativeFavicon = false;
+            const initiator = params.initiator;
+            if (resource === "Other" && method === "GET" && !request.hasPostData && !request.postData && target.source === "page" && mainFrame && params.frameId === mainFrame && initiator?.type === "other" && !initiator.stack && !initiator.url && typeof params.documentURL === "string") {
+                try {
+                    const endpoint = new URL(request.url), document = new URL(params.documentURL);
+                    nativeFavicon = endpoint.pathname === "/favicon.ico" && !endpoint.search && !endpoint.hash && !endpoint.username && !endpoint.password && endpoint.origin === document.origin && frames.get(mainFrame) === evidenceUrl(params.documentURL);
+                }
+                catch {  }
+            }
+            this.record(target, { endpoint: request.url, transport: "http", source, ...classified, ...(ASSETS.has(resource) && /^(GET|HEAD)$/.test(method) || nativeFavicon ? { purpose: "app-resource", detail: nativeFavicon ? "Browser native document-origin favicon" : `Browser resource type ${resource}` } : {}) }, typeof params.frameId === "string" && params.frameId ? params.frameId : target.frame);
+        });
+        channel.on("Network.webSocketCreated", (params) => {
+            if (typeof params.requestId !== "string" || typeof params.url !== "string")
+                return;
+            if (sockets.size >= MAX_SOCKETS) {
+                this.gap(target, `More than ${MAX_SOCKETS} concurrent WebSockets; later sockets cannot be classified`);
+                return;
+            }
+            const initiator = params.initiator;
+            const scripts = [];
+            for (let stack = initiator?.stack, depth = 0; stack && depth < 16; stack = stack.parent, depth++)
+                for (const frame of stack.callFrames ?? [])
+                    if (frame.url)
+                        scripts.push(frame.url);
+            let source = target.source;
+            let purpose;
+            let frame = target.frame;
+            let candidates;
+            if (source === "page") {
+                let matching = [...frames].filter(([, url]) => scripts.some((script) => url === evidenceUrl(script)));
+                if (!matching.length) {
+                    const loaded = scripts.map((script) => scriptFrames.get(evidenceUrl(script))).filter((loaders) => !!loaders);
+                    const every = [...frames.keys()].filter((id) => loaded.length > 0 && loaded.every((loaders) => loaders.has(id)));
+                    const any = new Set(loaded.flatMap((loaders) => [...loaders]));
+                    matching = [...frames].filter(([id]) => (every.length ? every.includes(id) : any.has(id)));
+                }
+                if (!matching.length && mainFrame && frames.has(mainFrame) && [...present].every((id) => id === mainFrame))
+                    matching = [[mainFrame, frames.get(mainFrame)]];
+                source = matching.some(([id]) => id === mainFrame) ? "page" : matching.length ? "frame" : "unknown";
+                frame = matching.length === 1 ? matching[0][0] : undefined;
+                candidates = matching.length > 1 ? matching.map(([id]) => id) : undefined;
+                try {
+                    const endpoint = new URL(params.url);
+                    if (scripts.some((script) => { const initiatorUrl = new URL(script); return initiatorUrl.pathname === "/@vite/client" && initiatorUrl.host === endpoint.host && (initiatorUrl.protocol === "https:" ? endpoint.protocol === "wss:" : initiatorUrl.protocol === "http:" && endpoint.protocol === "ws:"); }))
+                        purpose = "development-update";
+                }
+                catch {  }
+            }
+            const first = this.record(target, { endpoint: params.url, transport: "websocket", source, ...(purpose ? { purpose } : {}), operation: "opaque", detail: "WebSocket opened without an observed outgoing payload" }, frame, candidates);
+            let opened;
+            const opening = new Promise((resolve) => {
+                const timer = setTimeout(resolve, HANDSHAKE_WAIT_MS);
+                timer.unref();
+                opened = () => { clearTimeout(timer); resolve(); };
+            }).then(() => { this.opening.delete(opening); });
+            this.opening.add(opening);
+            sockets.set(params.requestId, { endpoint: evidenceUrl(params.url), first, sent: false, source, ...(frame ? { frame } : {}), purpose, opened });
+        });
+        channel.on("Network.webSocketWillSendHandshakeRequest", (params) => {
+            const socket = sockets.get(params.requestId);
+            const headers = params.request?.headers;
+            const protocol = Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === "sec-websocket-protocol")?.[1];
+            const origin = Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === "origin")?.[1];
+            if (socket && typeof origin === "string" && /^https?:\/\/[^/]+$/.test(origin)) {
+                socket.origin = origin;
+                if (socket.first)
+                    Object.assign(socket.first, { origin });
+            }
+            socket?.opened();
+            if (!socket || typeof protocol !== "string" || !protocol.split(",").some((value) => value.trim() === "vite-hmr"))
+                return;
+            const endpoint = new URL(socket.endpoint);
+            const sameAppOrigin = [...frames.values()].some((document) => { try {
+                const url = new URL(document);
+                return url.host === endpoint.host && (url.protocol === "https:" ? endpoint.protocol === "wss:" : url.protocol === "http:" && endpoint.protocol === "ws:");
+            }
+            catch {
+                return false;
+            } });
+            if (sameAppOrigin) {
+                socket.purpose = "development-update";
+                if (socket.first)
+                    Object.assign(socket.first, { purpose: "development-update" });
+            }
+        });
+        channel.on("Network.webSocketFrameSent", (params) => {
+            const socket = sockets.get(params.requestId);
+            if (!socket) {
+                this.gap(target, "An outgoing WebSocket frame had no observed endpoint");
+                return;
+            }
+            const frame = params.response;
+            const classified = classifyPayload(typeof frame?.payloadData === "string" ? frame.payloadData : undefined, frame?.opcode !== 1);
+            if (socket.purpose === "development-update" && classified.operation !== "opaque") {
+                socket.purpose = undefined;
+                if (!socket.sent && socket.first)
+                    delete socket.first.purpose;
+            }
+            if (!socket.sent && socket.first) {
+                delete socket.first.detail;
+                Object.assign(socket.first, classified, { at: Date.now() });
+            }
+            else
+                this.record(target, { endpoint: socket.endpoint, transport: "websocket", source: socket.source, ...(socket.purpose ? { purpose: socket.purpose } : {}), ...(socket.origin ? { origin: socket.origin } : {}), ...classified }, socket.frame);
+            socket.sent = true;
+        });
+        channel.on("Network.webSocketClosed", (params) => { sockets.get(params.requestId)?.opened(); sockets.delete(params.requestId); });
+        channel.on("Network.webTransportCreated", (params) => {
+            if (typeof params.url === "string")
+                this.record(target, { endpoint: params.url, transport: "other", source: target.source, operation: "opaque", detail: "WebTransport payload is unavailable; direct traffic remains opaque" });
+        });
+        channel.on("Network.directTCPSocketCreated", (params) => {
+            if (typeof params.remoteAddr === "string" && typeof params.remotePort === "number")
+                this.record(target, { endpoint: `tcp://${params.remoteAddr}:${params.remotePort}`, transport: "other", source: target.source, operation: "opaque", detail: "Direct TCP payload is not classified; direct traffic remains opaque" });
+        });
+        channel.on("Network.directUDPSocketOpened", (params) => {
+            if (typeof params.remoteAddr === "string" && typeof params.remotePort === "number")
+                this.record(target, { endpoint: `udp://${params.remoteAddr}:${params.remotePort}`, transport: "other", source: target.source, operation: "opaque", detail: "Direct UDP payload is not classified; direct traffic remains opaque" });
+            else
+                this.gap(target, "A direct UDP socket opened without a visible remote endpoint");
+        });
+    }
+    async attach(page) {
+        await this.ready;
+        const early = page.url() === "about:blank";
+        if (!this.root)
+            return unavailable([this.error ?? "Network observer is unavailable"]);
+        let session;
+        let info;
+        try {
+            session = await page.context().newCDPSession(page);
+            info = (await session.send("Target.getTargetInfo")).targetInfo;
+            if (!this.targets.has(info.targetId))
+                await this.root.send("Target.attachToTarget", { targetId: info.targetId, flatten: false });
+            await this.targets.get(info.targetId)?.ready;
+        }
+        catch (error) {
+            await session?.detach().catch(() => undefined);
+            return unavailable([...(this.error ? [this.error] : []), evidenceText(`Page network observation unavailable: ${String(error)}`)]);
+        }
+        let cleanupGap;
+        try {
+            await session.detach();
+        }
+        catch (error) {
+            if (!page.isClosed() && page.context().browser()?.isConnected())
+                cleanupGap = evidenceText(`Page network discovery cleanup failed: ${String(error)}`);
+        }
+        return { owner: this.targets.get(info.targetId)?.owner ?? info.targetId, info, early, ...(cleanupGap ? { cleanupGap } : {}) };
+    }
+    async page(page) {
+        const attached = await this.attach(page);
+        return { evidence: async () => ("owner" in attached ? this.settled(attached) : attached) };
+    }
+    async frames(page) {
+        const attached = await this.attach(page);
+        return { frame: (name) => ({ evidence: async () => ("owner" in attached ? this.settled(attached, name) : attached) }) };
+    }
+    async settled(attached, frameName) {
+        await Promise.all([...this.opening]);
+        return this.evidence(attached, frameName);
+    }
+    evidence({ owner, info, early, cleanupGap }, frameName) {
+        const relevant = (item) => item.owner === owner || (!item.owner && (item.context === undefined || item.context === info.browserContextId));
+        const findings = this.findings.flatMap((item) => {
+            if (!item.rtc)
+                return relevant(item) ? [item] : [];
+            const matches = [...this.targets.values()].filter((target) => !!item.document && target.documents?.has(item.document) && target.owner);
+            const owners = new Set(matches.map((target) => target.owner));
+            if (owners.size === 1) {
+                if (!owners.has(owner))
+                    return [];
+                const sources = new Set(matches.flatMap((target) => [...target.documents.get(item.document)]));
+                const source = sources.size === 1 ? [...sources][0] : "unknown";
+                return [{ ...item, owner, observation: { ...item.observation, source, ...(sources.size > 1 ? { detail: `${item.observation.detail}; document URL matches both page and frame, so its source is ambiguous` } : {}) } }];
+            }
+            return [item];
+        });
+        const claims = (item) => (item.frame !== undefined ? this.inFrame(item.frame, frameName) : !!item.candidates?.length && item.candidates.every((candidate) => this.inFrame(candidate, frameName)));
+        const unknown = (item) => item.frame === undefined && (!item.candidates?.length ? true : item.candidates.some((candidate) => this.inFrame(candidate, frameName)) && !claims(item));
+        const unattributed = frameName === undefined ? [] : findings.filter((item) => unknown(item) && item.observation.purpose !== "development-update");
+        const shown = frameName === undefined ? findings : findings.filter(claims);
+        const gaps = this.gaps.filter(relevant).map((gap) => gap.text);
+        if (cleanupGap)
+            gaps.push(cleanupGap);
+        if (!early)
+            gaps.push("Page observation started after initial navigation");
+        for (const item of unattributed)
+            gaps.push(`${item.observation.endpoint}: Chromium named no frame for this ${item.observation.transport} traffic, so it may be frame "${frameName}"'s`);
+        for (const item of shown) {
+            if (item.observation.transport === "websocket" && item.observation.source === "unknown" && item.observation.purpose !== "development-update")
+                gaps.push(`${item.observation.endpoint}: Chromium did not expose the owning page/frame of this WebSocket`);
+            if (item.rtc && !item.owner)
+                gaps.push("Native WebRTC tracker exposes only document URL; its owning page is unknown or ambiguous across matching URLs");
+            if (!item.owner && new Set([...this.targets.values()].filter((target) => target.info.type === "page" && target.info.browserContextId === info.browserContextId).map((target) => target.owner)).size > 1)
+                gaps.push(`${item.observation.source} attribution is limited to its browser context; its owning page is not exposed by Chromium`);
+            if (item.observation.operation === "opaque" && item.observation.purpose !== "development-update")
+                gaps.push(`${item.observation.endpoint}: ${item.observation.detail ?? "Payload could not be classified"}`);
+        }
+        return { observations: shown.map(({ observation }) => ({ ...observation })), coverage: { beforeNavigation: early, pages: !this.error && !gaps.some((gap) => /Network observation for (page|iframe) failed|Page frame observation failed|Popup initialization/.test(gap)), workers: !this.error && !gaps.some((gap) => /[Ww]orker (attachment|observation|initialization)|Network observation for/.test(gap)), gaps: [...new Set(gaps)] } };
+    }
+}
+const observers = new WeakMap();
+export async function prepareNetworkObservation(browser, holding) {
+    let observer = observers.get(browser);
+    if (!observer) {
+        observer = new BrowserEvidence(browser, holding);
+        observers.set(browser, observer);
+    }
+    await observer.ready;
+}
+export async function observePageNetwork(page) {
+    const browser = page.context().browser();
+    if (!browser)
+        return { evidence: async () => ({ observations: [], coverage: { beforeNavigation: false, pages: false, workers: false, gaps: ["Browser connection is unavailable for passive network observation"] } }) };
+    await prepareNetworkObservation(browser);
+    return observers.get(browser).page(page);
+}
+export async function observeFramesNetwork(page, holding) {
+    const browser = page.context().browser();
+    if (!browser)
+        return { frame: () => ({ evidence: async () => unavailable(["Browser connection is unavailable for passive network observation"]) }) };
+    await prepareNetworkObservation(browser, holding);
+    return observers.get(browser).frames(page);
+}

package/adapters/browser/playwright/src/page-conditions.d.ts

@@ -0,0 +1,37 @@
+import type { Page } from "playwright";
+import { type CpuSlowdown, type NetworkCondition } from "@parity/product-lab/domain/conditions";
+import type { ConditionControl } from "@parity/product-lab/ports/browser";
+import type { SocketRoutes } from "./socket-routes.js";
+export declare class PageConditions implements ConditionControl {
+    private readonly page;
+    /** The context's own socket routes, when known: each conditioned socket is handed on to the one that decides it. */
+    private readonly routes?;
+    readonly unavailable?: {
+        readonly cpu?: string;
+    };
+    private condition;
+    /** The identity's local link now (read for every request and socket: a native host's link moves when it restarts). */
+    private readonly exempt;
+    private readonly routing;
+    /** Settled once the page's requests and sockets are routed (a navigation waits for it). */
+    get ready(): Promise<void>;
+    private cdp;
+    private slowed;
+    /** Sockets proxied while conditioned: closed when the identity goes offline. */
+    private readonly sockets;
+    constructor(page: Page, 
+    /** The identity's local link to its host (origins): never conditioned. */
+    exempt: readonly string[] | (() => readonly string[]), 
+    /** The context's own socket routes, when known: each conditioned socket is handed on to the one that decides it. */
+    routes?: SocketRoutes | undefined);
+    network(condition: NetworkCondition): Promise<void>;
+    cpu(slowdown: CpuSlowdown): Promise<void>;
+    reset(): Promise<void>;
+    /** Every request and socket of the page through the current condition (installed with the control). */
+    private route;
+    /**
+     * One socket outside the local link: refused while offline; else conditioned and handed to the context's own route
+     * for it (a network guard, an endpoint bridge), or connected to its server when there is none, as Playwright would.
+     */
+    private socket;
+}