From be76f8090b5195680cdf73a8c21f65e6516efc92 Mon Sep 17 00:00:00 2001 From: N0zoM1z0 <1705004398@qq.com> Date: Tue, 14 Jul 2026 17:47:50 +0800 Subject: [PATCH] feat: add web and Electron reverse-engineering workflows --- CONTRIBUTING.md | 4 +- README.md | 32 +- README_ar.md | 9 +- README_ja.md | 9 +- README_ko.md | 9 +- README_zh.md | 9 +- docs/architecture.mermaid | 2 +- docs/browser-observation.md | 61 +- docs/electron-observation.md | 35 + docs/mcp-prompts.md | 2 +- package-lock.json | 4 +- package.json | 1 + scripts/fixtures/browser-verifier-site.mjs | 120 ++++ scripts/rea.mjs | 2 +- scripts/verify-package.mjs | 13 +- scripts/verify-published-package.mjs | 4 +- scripts/verify-real-browser.mjs | 282 ++++++-- scripts/verify-real-hopper.mjs | 2 +- skills/rea-analysis/SKILL.md | 28 +- src/application/BrowserEvidence.ts | 162 ++++- src/application/BrowserObservationPort.ts | 44 ++ src/application/BrowserObservationService.ts | 167 ++++- src/application/CapabilityInventory.ts | 10 + src/application/ElectronEvidence.ts | 60 ++ src/application/ElectronObservationPort.ts | 22 + src/application/ElectronObservationService.ts | 116 +++ src/application/ProjectPermissionStore.ts | 1 + src/browser/CdpBrowserProvider.ts | 262 ++++++- src/browser/CdpCaptureCompleteness.ts | 119 +++ src/browser/CdpCaptureDocuments.ts | 264 ++++++- src/browser/CdpCaptureEvents.ts | 457 ++++++++++-- src/browser/CdpCaptureValues.ts | 9 +- src/browser/CdpElectronInspection.ts | 481 +++++++++++++ src/browser/CdpElectronProvider.ts | 223 ++++++ src/browser/CdpEndpoint.ts | 13 +- src/browser/CdpObservationSession.ts | 416 +++++++++++ src/browser/CdpPageCapture.ts | 292 ++++++-- src/browser/CdpSafeMetadata.ts | 277 +++++++ src/browser/CdpScreenshot.ts | 164 +++++ src/browser/CdpWebMcpDiscovery.ts | 373 ++++++++++ src/browser/ElectronFileScope.ts | 56 ++ src/browser/PngVisualDiff.ts | 222 ++++++ src/browser/SensitiveTextCapture.ts | 35 + src/browser/WebSourceMapFetcher.ts | 445 ++++++++++++ src/catalogIdentity.ts | 8 + src/cli.ts | 4 + src/cliBrowserAdvancedCommands.ts | 220 ++++++ src/cliBrowserCommands.ts | 197 +++++ src/cliElectronCommands.ts | 141 ++++ src/cliPolicyCommands.ts | 1 + src/config.ts | 55 ++ src/contracts/browserToolContracts.ts | 330 ++++++++- src/contracts/electronToolContracts.ts | 84 +++ src/contracts/toolContractTypes.ts | 1 + src/contracts/toolContracts.ts | 2 + src/domain/browserCompleteness.ts | 142 ++++ src/domain/browserObservation.ts | 269 ++++++- src/domain/browserSession.ts | 74 ++ src/domain/electronObservation.ts | 194 +++++ src/domain/errors.ts | 15 +- src/domain/jsonShape.ts | 151 ++++ src/domain/permissionPolicy.ts | 1 + src/domain/webBundleAnalysis.ts | 228 ++++++ src/domain/webBundleAnalyzer.ts | 640 +++++++++++++++++ src/domain/webCaptureDiff.ts | 286 ++++++++ src/domain/webContentArtifact.ts | 56 ++ src/domain/webInventory.ts | 120 ++++ src/domain/webMcpDiscovery.ts | 80 +++ src/domain/webScreenshot.ts | 142 ++++ src/generatedPackageMetadata.ts | 4 +- src/main.ts | 7 + src/server/createServer.ts | 10 + src/server/registerBrowserTools.ts | 145 +++- src/server/registerElectronTools.ts | 90 +++ src/server/registerSessionStatusTool.ts | 1 + src/server/registerSessionTools.ts | 3 + tests/browserCli.test.ts | 148 +++- tests/browserMcp.test.ts | 154 +++- tests/browserObservation.test.ts | 53 ++ tests/cdpBrowserProvider.test.ts | 675 +++++++++++++++++- tests/cdpCaptureCompleteness.test.ts | 56 ++ tests/cdpCaptureDocuments.test.ts | 62 ++ tests/cdpElectronProvider.test.ts | 211 ++++++ tests/cdpSafeMetadata.test.ts | 99 +++ tests/config.test.ts | 28 + tests/contractSnapshot.test.ts | 17 +- tests/electronCli.test.ts | 108 +++ tests/electronFileScope.test.ts | 57 ++ tests/electronMcp.test.ts | 131 ++++ tests/enhancedTools.test.ts | 12 +- tests/fixtures/fakeCdpBrowser.ts | 384 +++++++++- tests/integration/serverIntegration.test.ts | 14 +- tests/jsonShape.test.ts | 66 ++ tests/pngVisualDiff.test.ts | 95 +++ tests/promptMcp.test.ts | 2 +- tests/readmeConsistency.test.ts | 6 +- tests/runtime.test.ts | 6 +- tests/sensitiveTextCapture.test.ts | 27 + tests/serverIdentity.test.ts | 10 +- tests/sessionMcp.test.ts | 2 +- tests/setupSkill.test.ts | 2 +- tests/toolContracts.test.ts | 17 +- tests/webBundleAnalyzer.test.ts | 267 +++++++ tests/webCaptureDiff.test.ts | 151 ++++ tests/webInventory.test.ts | 154 ++++ tests/webSourceMapFetcher.test.ts | 264 +++++++ 106 files changed, 11893 insertions(+), 404 deletions(-) create mode 100644 docs/electron-observation.md create mode 100644 scripts/fixtures/browser-verifier-site.mjs create mode 100644 src/application/ElectronEvidence.ts create mode 100644 src/application/ElectronObservationPort.ts create mode 100644 src/application/ElectronObservationService.ts create mode 100644 src/browser/CdpCaptureCompleteness.ts create mode 100644 src/browser/CdpElectronInspection.ts create mode 100644 src/browser/CdpElectronProvider.ts create mode 100644 src/browser/CdpObservationSession.ts create mode 100644 src/browser/CdpSafeMetadata.ts create mode 100644 src/browser/CdpScreenshot.ts create mode 100644 src/browser/CdpWebMcpDiscovery.ts create mode 100644 src/browser/ElectronFileScope.ts create mode 100644 src/browser/PngVisualDiff.ts create mode 100644 src/browser/SensitiveTextCapture.ts create mode 100644 src/browser/WebSourceMapFetcher.ts create mode 100644 src/cliBrowserAdvancedCommands.ts create mode 100644 src/cliElectronCommands.ts create mode 100644 src/contracts/electronToolContracts.ts create mode 100644 src/domain/browserCompleteness.ts create mode 100644 src/domain/browserSession.ts create mode 100644 src/domain/electronObservation.ts create mode 100644 src/domain/jsonShape.ts create mode 100644 src/domain/webBundleAnalysis.ts create mode 100644 src/domain/webBundleAnalyzer.ts create mode 100644 src/domain/webCaptureDiff.ts create mode 100644 src/domain/webContentArtifact.ts create mode 100644 src/domain/webInventory.ts create mode 100644 src/domain/webMcpDiscovery.ts create mode 100644 src/domain/webScreenshot.ts create mode 100644 src/server/registerElectronTools.ts create mode 100644 tests/cdpCaptureCompleteness.test.ts create mode 100644 tests/cdpElectronProvider.test.ts create mode 100644 tests/cdpSafeMetadata.test.ts create mode 100644 tests/electronCli.test.ts create mode 100644 tests/electronFileScope.test.ts create mode 100644 tests/electronMcp.test.ts create mode 100644 tests/jsonShape.test.ts create mode 100644 tests/pngVisualDiff.test.ts create mode 100644 tests/sensitiveTextCapture.test.ts create mode 100644 tests/webBundleAnalyzer.test.ts create mode 100644 tests/webCaptureDiff.test.ts create mode 100644 tests/webInventory.test.ts create mode 100644 tests/webSourceMapFetcher.test.ts diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac09b405e..cb1ae8d8d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,7 @@ npm run build npm test ``` -Keep dependencies flowing inward through the existing domain, contracts, provider, application, server, and adapter layers. Parse unknown values at process and protocol boundaries, model expected failures with `Result`, and preserve the 33 direct, 10 enhanced, 5 native, 2 artifact, 2 browser, and 18 session tools (70 total) unless a deliberate contract change updates every verifier and snapshot. +Keep dependencies flowing inward through the existing domain, contracts, provider, application, server, and adapter layers. Parse unknown values at process and protocol boundaries, model expected failures with `Result`, and preserve the 33 direct, 10 enhanced, 5 native, 2 artifact, 8 browser, 2 Electron, and 18 session tools (78 total) unless a deliberate contract change updates every verifier and snapshot. Before submitting a pull request, run: @@ -70,7 +70,7 @@ Publish the public package: npm publish --access public ``` -After npm registry propagation, verify the published CLI and connect a beta.3 MCP client to the published server to confirm all 70 tools: +After npm registry propagation, verify the published CLI and connect a beta.3 MCP client to the published server to confirm all 78 tools: ```bash npx -y rea-agents --help diff --git a/README.md b/README.md index 08f341812..9175d6263 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,11 @@ [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents) [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml) -[![70 MCP tools](https://img.shields.io/badge/MCP_tools-70-5c4ee5?style=flat-square)](#70-tools-for-investigation) +[![78 MCP tools](https://img.shields.io/badge/MCP_tools-78-5c4ee5?style=flat-square)](#78-tools-for-investigation) [![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/) [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE) -[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [70 tools](#70-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works) +[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [78 tools](#78-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
@@ -30,7 +30,7 @@ See a feature in an app that you want in your own product? Give the app to your agent—even without its source code. With REA, the agent can investigate the feature, explain how it works, show its evidence, and build a version adapted to your stack and requirements. -REA gives agents one consistent way to investigate software. Today that includes deep native analysis through Hopper, complete function dossiers, reproducible Evidence v2 records, and controlled process capture. The longer-term toolkit extends the same agent workflow to packaged apps, JavaScript bundles, websites, APIs, protocols, mobile artifacts, firmware, runtime behavior, and differences between versions. +REA gives agents one consistent way to investigate software. Today that includes deep native analysis through Hopper, complete function dossiers, reproducible Evidence v2 records, controlled process capture, passive website and Electron observation, and bounded JavaScript/source-map reconstruction. The longer-term toolkit extends the same agent workflow to APIs, protocols, mobile artifacts, firmware, richer runtime behavior, and differences between versions. Reverse engineering normally makes the operator choose a tool, learn its API, move evidence between programs, and decide what to inspect next. REA gives that work to the agent through commands, skills, structured results, and repeatable investigation workflows. @@ -294,16 +294,17 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its - Analyze Swift and Objective-C metadata without manually untangling every mangled symbol. - Leave names, comments, and bookmarks in Hopper so human and agent analysis reinforce each other. -## 70 tools for investigation +## 78 tools for investigation -| Tool family | Count | Examples | -| ------------------------- | ----: | ---------------------------------------------------------------------------------------------------------------------------------- | -| Native inspection | 33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations | -| Investigation workflows | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery | -| Native macOS utilities | 5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing | -| Artifact graph | 2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree | -| Browser observation | 2 | exact-origin CDP page discovery and passive DOM, accessibility, script, resource, network, console, worker, and storage inspection | -| Workspace and observation | 18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle | +| Tool family | Count | Examples | +| ------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------- | +| Native inspection | 33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations | +| Investigation workflows | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery | +| Native macOS utilities | 5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing | +| Artifact graph | 2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree | +| Browser observation | 8 | exact-origin CDP capture, bundle and source-map analysis, WebMCP discovery, session timelines, capture diff, and visual evidence | +| Electron observation | 2 | canonical-root-confined file-page discovery and passive DOM, resource, and optionally approved script-source inspection | +| Workspace and observation | 18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle | The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness implements controlled behavioral capture. @@ -312,7 +313,8 @@ The public interface describes what the agent is trying to learn. Providers deci REA is already useful for native application investigation on macOS: - Open Mach-O, ELF, PE, `.app`, ZIP, APK, IPA, ASAR, plist, JavaScript, source-map, and Hopper database targets. -- Attach to a user-owned Chrome-family browser over a configured loopback CDP endpoint, list only pages on approved exact origins, and capture bounded passive web evidence without navigation or JavaScript evaluation. +- Attach to a user-owned Chrome-family browser over a configured loopback CDP endpoint; capture exact-origin web structure, safe metadata, approved value-free payload shapes, bundle/source-map evidence, WebMCP declarations, user-action timelines, capture diffs, and explicitly approved screenshots without navigation or JavaScript evaluation. +- Inspect Electron `file://` renderer pages through a separate canonical-root permission boundary without invoking Electron APIs; script contents remain separately approved and byte bounded. - Traverse content-addressed artifact graphs without extraction; on macOS, read-only DMG traversal additionally requires `native_mount_approved: true` and `REA_ARTIFACT_NATIVE_MOUNT_ENABLED=true`. Materialize only approved occurrences into absent output roots. - Build bounded function dossiers with pseudocode, assembly, CFG edges, comments, calls, references, strings, and names. - Search and trace features across symbols, strings, metadata, references, and call paths. @@ -346,14 +348,14 @@ rea list-browser-targets http://127.0.0.1:9222 --approved --json rea inspect-web-page http://127.0.0.1:9222 TARGET_ID --approved --json ``` -`list_browser_targets` and `inspect_web_page` expose the same Evidence v2 contracts over MCP. Inspection is passive: REA does not evaluate page JavaScript, navigate, click, close the page, or close the browser. It redacts query values and never retains headers, bodies, cookies, storage values, console argument values, or WebSocket payloads. Existing activity before attach is explicitly unavailable. See [Website observation with CDP](docs/browser-observation.md) for browser startup, schemas, limits, and the threat model. +All eight browser tools expose the same Evidence v2 contracts over CLI and MCP. Inspection is passive: REA does not evaluate page JavaScript, navigate, click, close the page, or close the browser. Query values, credentials, cookies, authorization headers, storage values, and raw JSON or WebSocket values are never retained. Separately approved captures can retain bounded redacted console primitives, value-free JSON/WebSocket shapes, script sources, accessibility text, or screenshot pixels. Existing activity before attach is explicitly unavailable. See [Website observation with CDP](docs/browser-observation.md) for browser startup, schemas, limits, and the threat model. ## Roadmap REA is growing into a toolkit for understanding software across static artifacts and observed behavior. The next capability families are: 1. **Artifact decomposition** — DMG, ASAR, ZIP, packages, universal-binary slices, application resources, embedded frameworks, mobile packages, and artifact graphs. -2. **Web and Electron investigation** — extend the shipped passive CDP observation with approved interaction, screenshots, Electron IPC, route discovery, controlled replay, and visual or structural differences. +2. **Web and Electron investigation** — extend the shipped passive CDP, bundle, visual-diff, and file-page observation with approved interaction, controlled replay, Electron IPC observation, semantic UI differences, and deeper JavaScript reconstruction. 3. **Deterministic behavior harnesses** — stronger process-tree ownership, protocol fixtures, network policy, filesystem tracing, signals, reconnects, and cross-version comparison. 4. **JavaScript and source recovery** — bundle indexing, AST/module reconstruction, source-map discovery, historical-source matching, and CodeDB-backed cross-references. 5. **Runtime observation** — approval-gated LLDB, Frida, system logs, process and filesystem observers, and native API tracing. diff --git a/README_ar.md b/README_ar.md index 097053d4c..eca8b8011 100644 --- a/README_ar.md +++ b/README_ar.md @@ -10,11 +10,11 @@ [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents) [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml) -[![70 MCP tools](https://img.shields.io/badge/MCP_tools-70-5c4ee5?style=flat-square)](#منصة-من-70-أداة) +[![78 MCP tools](https://img.shields.io/badge/MCP_tools-78-5c4ee5?style=flat-square)](#منصة-من-78-أداة) [![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/) [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE) -[البدء السريع](#البدء-السريع) · [من الملف التنفيذي إلى السلوك](#من-الملف-التنفيذي-إلى-السلوك) · [70 أداة](#منصة-من-70-أداة) · [كيف يعمل](#كيف-يعمل) · [الأسئلة الشائعة](#الأسئلة-الشائعة) +[البدء السريع](#البدء-السريع) · [من الملف التنفيذي إلى السلوك](#من-الملف-التنفيذي-إلى-السلوك) · [78 أداة](#منصة-من-78-أداة) · [كيف يعمل](#كيف-يعمل) · [الأسئلة الشائعة](#الأسئلة-الشائعة)
@@ -155,7 +155,7 @@ rea uninstall --purge-data افحص التحقق من الإدخال، والتشفير، والصلاحيات، والتخزين، ومسارات الأخطاء من دون رفع الملف التنفيذي إلى خدمة بعيدة. -## منصة من 70 أداة +## منصة من 78 أداة | عائلة الأدوات | العدد | أمثلة | | --------------------- | ----: | ---------------------------------------------------------------------------------------- | @@ -163,7 +163,8 @@ rea uninstall --purge-data | التحليل المركب | 10 | النظرة العامة، وفك الترجمة الدفعي، ومخططات الاستدعاء، والمراجع، واكتشاف الأنواع | | أدوات macOS الأصلية | 5 | بيانات Mach-O والتوقيعات وملفات plist والمعماريات وفك رموز Swift دون تشغيل Hopper | | رسم القطع الأثرية | 2 | جرد حتمي للدلائل وZIP/APK/IPA وASAR واستخراج معاملاتي محدد صراحة | -| مراقبة المتصفح | 2 | اكتشاف صفحات CDP ضمن أصول دقيقة وفحص سلبي لـ DOM وإتاحة الوصول والبرامج والشبكة والتخزين | +| مراقبة المتصفح | 8 | التقاط CDP محدود الأصل وتحليل الحزم وخرائط المصدر واكتشاف WebMCP والفروق والأدلة المرئية | +| مراقبة Electron | 2 | اكتشاف صفحات الملفات ضمن جذور canonical وفحص DOM والموارد والمصادر المعتمدة | | جلسة الملف التنفيذي | 18 | فتح الأهداف وحزم الأدلة ومقارنة العمليات والقطع والدوال وسجل المجهولات المتبقية | ## استخدام REA مع وكلاء برمجة آخرين diff --git a/README_ja.md b/README_ja.md index b7e37cee4..bbfb1f5e0 100644 --- a/README_ja.md +++ b/README_ja.md @@ -10,11 +10,11 @@ [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents) [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml) -[![70 MCP tools](https://img.shields.io/badge/MCP_tools-70-5c4ee5?style=flat-square)](#70-ツールのワークベンチ) +[![78 MCP tools](https://img.shields.io/badge/MCP_tools-78-5c4ee5?style=flat-square)](#78-ツールのワークベンチ) [![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/) [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE) -[クイックスタート](#クイックスタート) · [バイナリから動作へ](#バイナリから動作へ) · [70 ツール](#70-ツールのワークベンチ) · [仕組み](#仕組み) · [FAQ](#faq) +[クイックスタート](#クイックスタート) · [バイナリから動作へ](#バイナリから動作へ) · [78 ツール](#78-ツールのワークベンチ) · [仕組み](#仕組み) · [FAQ](#faq)
@@ -145,7 +145,7 @@ REA は手順 1〜5 のバイナリ解析を処理し、手順 6 はエージェ - Swift / Objective-C のメタデータを解析する。 - Hopper に名前、コメント、ブックマークを残し、人間とエージェントの調査を共有する。 -## 70 ツールのワークベンチ +## 78 ツールのワークベンチ | ツール群 | 数 | 例 | | ---------------------- | --: | ------------------------------------------------------------------------------------------------------------------- | @@ -153,7 +153,8 @@ REA は手順 1〜5 のバイナリ解析を処理し、手順 6 はエージェ | 合成解析 | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift / ObjC 検出 | | macOS ネイティブ | 5 | Mach-O メタデータ、署名、plist、アーキテクチャ、Swift デマングル。Hopper 起動不要 | | アーティファクトグラフ | 2 | ディレクトリ、ZIP/APK/IPA、ASAR の決定的一覧と明示選択されたトランザクション抽出 | -| ブラウザ観察 | 2 | 完全一致 origin に限定した CDP ページ検出と受動的な DOM、アクセシビリティ、スクリプト、通信、保存領域の調査 | +| ブラウザ観察 | 8 | origin 限定 CDP 取得、bundle/source map 解析、WebMCP 検出、セッション、capture diff、視覚証拠 | +| Electron 観察 | 2 | canonical ファイルルート内のページ検出と受動的 DOM、リソース、承認済みスクリプトソース調査 | | バイナリセッション | 18 | `open_binary`、`binary_session`、証拠バンドル、プロセス／成果物／関数比較、残余未知レジストリ | ## 他のコーディングエージェントで使う diff --git a/README_ko.md b/README_ko.md index a7e0c7e46..606fe9b81 100644 --- a/README_ko.md +++ b/README_ko.md @@ -10,11 +10,11 @@ [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents) [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml) -[![70 MCP tools](https://img.shields.io/badge/MCP_tools-70-5c4ee5?style=flat-square)](#70개-도구로-구성된-워크벤치) +[![78 MCP tools](https://img.shields.io/badge/MCP_tools-78-5c4ee5?style=flat-square)](#78개-도구로-구성된-워크벤치) [![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/) [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE) -[빠른 시작](#빠른-시작) · [바이너리에서 동작까지](#바이너리에서-동작까지) · [70개 도구](#70개-도구로-구성된-워크벤치) · [작동 방식](#작동-방식) · [FAQ](#faq) +[빠른 시작](#빠른-시작) · [바이너리에서 동작까지](#바이너리에서-동작까지) · [78개 도구](#78개-도구로-구성된-워크벤치) · [작동 방식](#작동-방식) · [FAQ](#faq)
@@ -145,7 +145,7 @@ REA는 1–5단계의 바이너리 분석을 처리합니다. 6단계는 에이 - Swift 및 Objective-C 메타데이터를 분석합니다. - Hopper에 이름, 주석, 북마크를 남겨 사람과 에이전트의 분석을 연결합니다. -## 70개 도구로 구성된 워크벤치 +## 78개 도구로 구성된 워크벤치 | 도구 그룹 | 수 | 예시 | | ------------------- | --: | -------------------------------------------------------------------------------------------------------------------- | @@ -153,7 +153,8 @@ REA는 1–5단계의 바이너리 분석을 처리합니다. 6단계는 에이 | 합성 분석 | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`, Swift 및 ObjC 탐색 | | macOS 네이티브 도구 | 5 | Mach-O 메타데이터, 코드 서명, plist, 아키텍처, Swift 디맹글링. Hopper 실행 불필요 | | 아티팩트 그래프 | 2 | 디렉터리, ZIP/APK/IPA, ASAR 결정적 인벤토리와 명시적으로 선택한 트랜잭션 추출 | -| 브라우저 관찰 | 2 | 정확한 origin 범위의 CDP 페이지 검색과 수동 DOM, 접근성, 스크립트, 네트워크, 콘솔 및 저장소 조사 | +| 브라우저 관찰 | 8 | origin 제한 CDP 캡처, bundle/source map 분석, WebMCP 검색, 세션 타임라인, capture diff 및 시각 증거 | +| Electron 관찰 | 2 | canonical 파일 루트 내 페이지 검색과 수동 DOM, 리소스 및 별도 승인된 스크립트 소스 조사 | | 바이너리 세션 | 18 | `open_binary`, `binary_session`, 증거 번들, 프로세스·아티팩트·함수 비교, 잔여 미지수 레지스트리 | ## 다른 코딩 에이전트에서 사용하기 diff --git a/README_zh.md b/README_zh.md index 4bdc6cd9c..5ea0536cf 100644 --- a/README_zh.md +++ b/README_zh.md @@ -10,11 +10,11 @@ [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents) [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml) -[![70 MCP tools](https://img.shields.io/badge/MCP_tools-70-5c4ee5?style=flat-square)](#70-个工具组成的工作台) +[![78 MCP tools](https://img.shields.io/badge/MCP_tools-78-5c4ee5?style=flat-square)](#78-个工具组成的工作台) [![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/) [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE) -[快速开始](#快速开始) · [从二进制到行为](#从二进制到行为) · [70 个工具](#70-个工具组成的工作台) · [工作原理](#工作原理) · [常见问题](#常见问题) +[快速开始](#快速开始) · [从二进制到行为](#从二进制到行为) · [78 个工具](#78-个工具组成的工作台) · [工作原理](#工作原理) · [常见问题](#常见问题)
@@ -145,7 +145,7 @@ REA 负责第 1–5 步中的二进制分析。第 6 步由智能体使用其常 - 分析 Swift 和 Objective-C 元数据。 - 在 Hopper 中留下名称、注释与书签，使人与智能体的分析互相增强。 -## 70 个工具组成的工作台 +## 78 个工具组成的工作台 | 工具类别 | 数量 | 示例 | | -------------- | ---: | -------------------------------------------------------------------------------------------------------------------- | @@ -153,7 +153,8 @@ REA 负责第 1–5 步中的二进制分析。第 6 步由智能体使用其常 | 组合分析 | 10 | `binary_overview`, `analyze_function`, `batch_decompile`, `get_call_graph`, `find_xrefs_to_name`、Swift 与 ObjC 发现 | | macOS 原生工具 | 5 | Mach-O 元数据、代码签名、plist、架构与 Swift 符号还原，无需启动 Hopper | | 制品图谱 | 2 | 确定性目录、ZIP/APK/IPA 与 ASAR 清单，以及显式选择的事务式提取 | -| 浏览器观察 | 2 | 基于精确来源范围的 CDP 页面发现，以及被动 DOM、无障碍树、脚本、网络、控制台与存储检查 | +| 浏览器观察 | 8 | 精确来源 CDP 抓取、bundle/source map 分析、WebMCP 发现、会话时间线、capture diff 与视觉证据 | +| Electron 观察 | 2 | 限定 canonical 文件根的页面发现，以及被动 DOM、资源与另行批准的脚本源码检查 | | 二进制会话 | 18 | `open_binary`、`binary_session`、证据包、进程、制品与函数比较、残余未知项注册表 | ## 与其他编程智能体一起使用 diff --git a/docs/architecture.mermaid b/docs/architecture.mermaid index 60d7b68d5..26e608db1 100644 --- a/docs/architecture.mermaid +++ b/docs/architecture.mermaid @@ -25,7 +25,7 @@ graph TD end subgraph "Contracts Layer" - CONTRACTS["src/contracts/
Caller-visible tool schemas
70 analysis, browser, and session tools"] + CONTRACTS["src/contracts/
Caller-visible tool schemas
78 analysis, browser, Electron, and session tools"] end subgraph "Domain Layer" diff --git a/docs/browser-observation.md b/docs/browser-observation.md index 1728d61d3..39fdd989c 100644 --- a/docs/browser-observation.md +++ b/docs/browser-observation.md @@ -5,10 +5,18 @@ REA can attach to a user-owned Chrome-family browser through the Chrome DevTools ## Shipped surfaces - `list_browser_targets` / `rea list-browser-targets` discovers page targets whose current URL matches an approved exact origin. -- `inspect_web_page` / `rea inspect-web-page` captures bounded DOM structure, accessibility nodes, scripts, resources, attach-window network and console metadata, WebSocket frame sizes, workers, quota, and optionally storage key names or script sources. -- Both surfaces return the same provider-neutral normalized results and Evidence v2 provenance. +- `inspect_web_page` / `rea inspect-web-page` captures bounded DOM structure, accessibility nodes, scripts, resources, safe response/DOM metadata, attach-window network and console metadata, WebSocket frame sizes, workers, quota, and optionally storage key names or script sources. +- `analyze_web_bundle` / `rea analyze-web-bundle` parses approved script artifacts without execution and derives chunk edges, route and endpoint candidates, vendor fingerprints, static WebMCP declarations, and optionally approved source-map/original-source evidence. +- `observe_web_session` / `rea observe-web-session` arms a bounded window for an external user action and records ordered reload, SPA navigation, redirect, failure, lifecycle, and target-termination metadata. +- `discover_webmcp_tools` / `rea discover-webmcp-tools` uses the experimental CDP WebMCP domain to inventory page registrations. REA never exposes `WebMCP.invokeTool`. +- `compare_web_captures` / `rea compare-web-captures` compares stable DOM, script, resource, network, metadata, and optional WebMCP identities without treating incomplete absence as equivalence. +- `capture_web_screenshot` / `rea capture-web-screenshot` returns an explicitly approved, bounded, content-addressed visible-viewport PNG. +- `compare_web_screenshots` / `rea compare-web-screenshots` performs bounded local PNG pixel comparison without OCR or external services. +- Every surface has equivalent CLI and MCP contracts and returns Evidence v2 provenance. - MCP session results are retained as `rea://evidence/{evidenceId}` resources. One-shot CLI output is not retained by a long-lived REA session. +Electron `file://` pages use a separate provider, permission capability, and root model; see [electron-observation.md](electron-observation.md). + ## Start a browser Start a separate browser profile with an explicit debugging port. The exact executable name varies by platform and installation: @@ -60,17 +68,39 @@ rea inspect-web-page http://127.0.0.1:9222 TARGET_ID \ --json ``` -Script content and storage key names require separate opt-ins: +Static bundle analysis and a user-driven observation window are separate operations: + +```bash +rea analyze-web-bundle http://127.0.0.1:9222 TARGET_ID \ + --approved --source-capture-approved --json +rea observe-web-session http://127.0.0.1:9222 TARGET_ID \ + --approved --observation-ms 10000 --json +rea discover-webmcp-tools http://127.0.0.1:9222 TARGET_ID \ + --approved --json +``` + +Accessibility names/descriptions, console primitive text, JSON body shapes, WebSocket shapes, script content, and storage key names require separate opt-ins. Console/body/WebSocket capture additionally requires its matching approval flag: ```bash rea inspect-web-page http://127.0.0.1:9222 TARGET_ID \ --approved \ + --include-accessibility-text \ + --include-console-text --console-text-approved \ + --include-json-body-shapes --json-body-schema-approved \ + --include-websocket-shapes --websocket-shape-approved \ --include-script-sources \ --include-storage-keys \ --json ``` -Script content may contain application secrets and becomes part of the returned Evidence. Storage values remain redacted even when key-name capture is approved. +Accessibility text and script content may contain application secrets and become part of the returned Evidence. Accessibility and console text have independent per-field and aggregate UTF-8 byte limits; credential-shaped console substrings are redacted. JSON and WebSocket captures retain paths, types, counts, and truncation only, never values or examples. Storage values remain redacted even when key-name capture is approved. + +Screenshot pixels require both `--approved` and `--screenshot-approved`: + +```bash +rea capture-web-screenshot http://127.0.0.1:9222 TARGET_ID \ + --approved --screenshot-approved --json +``` ## MCP input @@ -81,6 +111,13 @@ Script content may contain application secrets and becomes part of the returned "target_id": "TARGET_ID_FROM_LIST_BROWSER_TARGETS", "approved": true, "observation_ms": 500, + "include_accessibility_text": false, + "include_console_text": false, + "console_text_approved": false, + "include_json_body_shapes": false, + "json_body_schema_approved": false, + "include_websocket_shapes": false, + "websocket_shape_approved": false, "include_script_sources": false, "include_storage_keys": false } @@ -96,11 +133,13 @@ REA removes sensitive values before normalized event data is retained: - URLs retain a bounded path and at most 256 bounded query parameter names, replace every retained query value with `[REDACTED]`, and remove credentials and fragments. - DOM snapshots retain node types, node names, value lengths, and attribute names, but not text or attribute values. -- Network observations retain method, status, MIME type, size, type, and redacted URLs, but not request/response headers, bodies, post data, cookies, or response content. -- Console observations with an approved stack source retain call type, argument types, timestamp, and redacted source location, but not argument values or descriptions. Events without a source URL are excluded because their origin cannot be established. -- WebSocket observations retain direction, opcode, and payload byte length, but not payload content. +- Accessibility structure and roles are retained by default, but names and descriptions require `include_accessibility_text: true` and remain byte-bounded. +- Network observations retain method, status, MIME type, size, type, initiator stack location, and redacted URLs. Headers are discarded after an allowlisted projection of length/encoding, structured CSP/Link/policy fields, and untrusted agent hints. Cookies and authorization headers are never retained. +- Request/response bodies are not requested or parsed by default. With independent approval, only allowed-origin JSON media types are read within per-body and aggregate budgets, converted immediately to value-free property paths/types, and discarded. `Network.getResponseBody` is never sent without that approval. +- Console observations with an approved stack source retain call type, argument types, timestamp, and redacted source location. With independent approval, only already-delivered primitive values are retained after credential redaction and byte bounds; objects, getters, and remote properties are never expanded. +- WebSocket observations retain direction, opcode, and payload byte length. With independent approval, bounded text frames are classified as text or value-free JSON shape; binary bytes, hashes, prefixes, and raw frames are never retained. - Storage observations always redact values. Key names, IndexedDB names, and cache names are omitted unless explicitly requested. -- Script metadata is included only when CDP supplies a URL on an allowed origin. URL-less scripts are excluded because their origin cannot be established. Source content is omitted unless explicitly requested and remains subject to per-script and aggregate byte limits. +- Script metadata is included only when CDP supplies a URL on an allowed origin. Stable keys exclude transient CDP script IDs, and exact transient raw URLs are used only during script/resource reconciliation. URL-less scripts are excluded because their origin cannot be established. Source content is omitted unless explicitly requested and becomes a self-verifying `rea://web-content/sha256/...` artifact subject to per-script and aggregate byte limits. Cross-origin frames, resources, scripts, events, and workers are excluded unless their exact origins are also approved. Excluded target details are counted without being exposed. @@ -108,14 +147,14 @@ Cross-origin frames, resources, scripts, events, and workers are excluded unless The default observation window is 500 ms and the maximum is 10 seconds. Frames (200), DOM nodes (2,000), accessibility nodes (2,000), scripts (200), resources (2,000), workers (500), and each storage key/name inventory (1,000) have conservative defaults and caller-visible hard bounds. Script source bytes, network events, console events, and WebSocket events are bounded separately. The CLI exposes the same limits as kebab-case options such as `--max-frames` and `--max-storage-keys`. -A bounded result reports `completeness.status: "truncated"`, named truncated sections, and dropped event counts rather than implying exhaustive capture. Disallowed-origin entries are filtered before collection-limit accounting, so they cannot consume an approved origin's output budget. +Every result distinguishes `complete_within_window`, `policy_filtered`, `attach_limited`, and `truncated` coverage. It names affected sections and reports sparse excluded-item and per-event-type dropped counts rather than implying exhaustive capture. Disallowed-origin entries are filtered before collection-limit accounting, so they cannot consume an approved origin's output budget. CDP discovery, WebSocket connection, and each command have a 5-second timeout. Version discovery is capped at 64 KiB, target discovery at 2 MiB and 1,000 targets, each WebSocket message at 16 MiB, and correlated pending commands at 128. Malformed unsolicited protocol events poison the connection so later commands fail closed. -Network and console coverage starts only after REA attaches and enables the relevant CDP domains. `prior_activity_available` is always `false`; absence from these arrays is not evidence that an event never occurred. Source maps are reported only as redacted declarative URLs and are never fetched. +Network and console coverage starts only after REA attaches and enables the relevant CDP domains. `prior_activity_available` is always `false`; absence from these arrays is not evidence that an event never occurred. Source maps are not fetched by inspection. Bundle analysis can fetch them only after separate approval, with exact-origin redirect checks, no credentials/cookies/referrer, per-map and aggregate byte limits, a total map-count limit, v3 validation, and bounded generated/original mappings. Source-map results report requested, processed, and dropped counts rather than hiding budget truncation. ## Non-goals and threat model -The first browser provider deliberately does not expose generic CDP commands, `Runtime.evaluate`, navigation, input, downloads, screenshots, page closure, or browser closure. REA disables the domains it enabled, detaches the target session, and closes only its own WebSocket. +The browser provider deliberately does not expose generic CDP commands, `Runtime.evaluate`, WebMCP invocation, navigation, input, downloads, page closure, or browser closure. Screenshot capture is the sole pixel surface and requires separate literal approval. REA disables the domains it enabled, detaches the target session, and closes only its own WebSocket. This feature is not a browser sandbox or network containment mechanism. The attached page and browser continue running with their existing privileges and may make external requests independently of REA. CDP gives deep access to the selected browser profile, so use a dedicated profile, approve only origins you intend to inspect, and treat other same-user processes as outside this boundary. diff --git a/docs/electron-observation.md b/docs/electron-observation.md new file mode 100644 index 000000000..1327de089 --- /dev/null +++ b/docs/electron-observation.md @@ -0,0 +1,35 @@ +# Electron file-page observation + +REA can attach to a user-owned Electron/Chromium CDP endpoint and inspect existing `file://` renderer pages without evaluating JavaScript or invoking Electron APIs. Electron observation is separate from website observation because filesystem roots, not HTTP origins, define its authority. + +## Configure authority + +The capability is disabled by default: + +```bash +export REA_ELECTRON_OBSERVE_ENABLED=true +export REA_ELECTRON_CDP_ENDPOINTS_JSON='["http://127.0.0.1:9223"]' +export REA_ELECTRON_FILE_ROOTS_JSON='["/Applications/Example.app/Contents/Resources"]' +``` + +Endpoints accept only explicit-port loopback HTTP URLs. Roots are canonicalized by the shared permission authority. Each target, frame, script, and resource is independently converted from a hostless `file://` URL to a real path and checked after symlink resolution. UNC hosts, percent-encoded path separators, nonexistent paths, and root escapes are rejected. + +## Workflow + +```bash +rea list-electron-targets http://127.0.0.1:9223 --approved --json +rea inspect-electron-page http://127.0.0.1:9223 TARGET_ID \ + --approved --observation-ms 100 --json +``` + +Script content is excluded by default. Capturing it requires both flags and remains subject to per-script and aggregate byte budgets: + +```bash +rea inspect-electron-page http://127.0.0.1:9223 TARGET_ID \ + --approved \ + --include-script-sources \ + --source-capture-approved \ + --json +``` + +The normalized result contains canonical local paths, bounded frame and DOM structure, resource metadata, stable script/resource identities, explicit completeness, and content-addressed approved source artifacts. It does not retain DOM values, execute renderer code, navigate, click, invoke Electron IPC, close a target, or terminate the application. diff --git a/docs/mcp-prompts.md b/docs/mcp-prompts.md index ce9d44a78..f41fb90aa 100644 --- a/docs/mcp-prompts.md +++ b/docs/mcp-prompts.md @@ -1,7 +1,7 @@ # Guided MCP prompts and completion REA exposes six provider-neutral investigation workflows through the MCP -`prompts` capability. They complement the 70 tools; they do not add, remove, or +`prompts` capability. They complement the 78 tools; they do not add, remove, or invoke tools by themselves. ## Prompt inventory diff --git a/package-lock.json b/package-lock.json index 611098065..049e1ff80 100644 --- a/package-lock.json +++ b/package-lock.json @@ -13,6 +13,7 @@ "@babel/parser": "8.0.4", "@babel/types": "8.0.4", "@electron/asar": "4.2.0", + "@jridgewell/trace-mapping": "0.3.31", "@modelcontextprotocol/server": "2.0.0-beta.4", "@xterm/addon-serialize": "0.14.0", "@xterm/headless": "6.0.0", @@ -221,7 +222,6 @@ "version": "3.1.2", "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==", - "dev": true, "license": "MIT", "engines": { "node": ">=6.0.0" @@ -231,14 +231,12 @@ "version": "1.5.5", "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz", "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==", - "dev": true, "license": "MIT" }, "node_modules/@jridgewell/trace-mapping": { "version": "0.3.31", "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz", "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==", - "dev": true, "license": "MIT", "dependencies": { "@jridgewell/resolve-uri": "^3.1.0", diff --git a/package.json b/package.json index bb6383325..e3a3148a4 100644 --- a/package.json +++ b/package.json @@ -92,6 +92,7 @@ "@babel/parser": "8.0.4", "@babel/types": "8.0.4", "@electron/asar": "4.2.0", + "@jridgewell/trace-mapping": "0.3.31", "@modelcontextprotocol/server": "2.0.0-beta.4", "@xterm/addon-serialize": "0.14.0", "@xterm/headless": "6.0.0", diff --git a/scripts/fixtures/browser-verifier-site.mjs b/scripts/fixtures/browser-verifier-site.mjs new file mode 100644 index 000000000..5c8dd78bb --- /dev/null +++ b/scripts/fixtures/browser-verifier-site.mjs @@ -0,0 +1,120 @@ +import { createServer } from "node:http"; + +import { WebSocketServer } from "ws"; + +/** Start the local HTTP/WS application used by real-browser verification. */ +export async function startBrowserVerifierSite() { + let port = 0; + let sessionGeneration = 0; + const server = createServer((request, response) => { + if (request.url === "/app.js.map") { + response.setHeader("content-type", "application/source-map+json"); + response.end(sourceMap()); + return; + } + if (request.url === "/session-generation") { + response.setHeader("content-type", "application/json"); + response.end(JSON.stringify({ generation: sessionGeneration })); + return; + } + if (request.url?.startsWith("/app.js") === true) { + response.setHeader("content-type", "text/javascript"); + response.end(browserScript(port)); + return; + } + if (request.url?.startsWith("/api") === true) { + response.setHeader("content-type", "application/json"); + response.setHeader( + "content-security-policy", + "default-src 'self'; connect-src 'self' ws:", + ); + response.setHeader( + "link", + '; rel="service-desc"; type="application/json"', + ); + response.setHeader("permissions-policy", "geolocation=(), camera=()"); + response.end('{"ok":true,"secret":"response-secret-value"}'); + return; + } + response.setHeader("content-type", "text/html"); + response.end( + 'REA browser verifier

Browser evidence

', + ); + }); + const webSockets = new WebSocketServer({ noServer: true }); + server.on("upgrade", (request, socket, head) => { + webSockets.handleUpgrade(request, socket, head, (webSocket) => { + webSocket.on("message", () => + webSocket.send("websocket-response-secret"), + ); + }); + }); + await new Promise((resolve, reject) => { + server.once("error", reject); + server.listen(0, "127.0.0.1", resolve); + }); + const address = server.address(); + if (address === null || typeof address === "string") + throw new Error("Local browser verifier did not bind a TCP port"); + port = address.port; + return { + origin: `http://127.0.0.1:${String(port)}`, + triggerSessionNavigation() { + sessionGeneration += 1; + }, + async close() { + for (const client of webSockets.clients) client.terminate(); + await new Promise((resolve) => webSockets.close(resolve)); + await new Promise((resolve, reject) => + server.close((error) => + error === undefined ? resolve() : reject(error), + ), + ); + }, + }; +} + +const browserScript = (port) => ` + export const reaSourceMarker = "approved-source-marker"; + export const verifiedRoute = { path: "/verified-route" }; + localStorage.setItem("rea-storage-key", "storage-secret-value"); + indexedDB.open("rea-browser-db", 1); + caches.open("rea-browser-cache"); + const observe = () => { + console.log("rea-browser-observation", "authorization=Bearer console-secret-value"); + fetch("/api?token=network-secret-value", { + method: "POST", + headers: { + Authorization: "Bearer request-secret-value", + "Content-Type": "application/json" + }, + body: JSON.stringify({ token: "request-body-secret-value", active: true }) + }); + const socket = new WebSocket("ws://127.0.0.1:${String(port)}/live?token=websocket-url-secret"); + socket.addEventListener("open", () => socket.send(JSON.stringify({ token: "websocket-secret-value" }))); + socket.addEventListener("message", () => socket.close()); + }; + observe(); + setInterval(observe, 150); + let observedGeneration = 0; + setInterval(async () => { + const response = await fetch("/session-generation"); + const { generation } = await response.json(); + if (generation <= observedGeneration) return; + observedGeneration = generation; + history.pushState({}, "", "/app/session-" + String(generation)); + }, 100); + //# sourceMappingURL=/app.js.map +`; + +const sourceMap = () => + JSON.stringify({ + version: 3, + file: "app.js", + names: ["reaSourceMarker"], + sources: ["../src/main.ts"], + sourcesContent: [ + "import './dependency.ts';\nexport const reaSourceMarker = 'approved-source-marker';", + ], + mappings: "AAAAA", + }); diff --git a/scripts/rea.mjs b/scripts/rea.mjs index 695fbc79f..6d7433910 100755 --- a/scripts/rea.mjs +++ b/scripts/rea.mjs @@ -1,7 +1,7 @@ #!/usr/bin/env node // Route production MCP before importing Incur. Incur owns registration helpers -// such as `mcp add`, while only dist/main.js may serve the 70-tool stdio server. +// such as `mcp add`, while only dist/main.js may serve the 78-tool stdio server. const args = process.argv.slice(2); const { default: packageJson } = await import("../package.json", { with: { type: "json" }, diff --git a/scripts/verify-package.mjs b/scripts/verify-package.mjs index 1f267ed9a..4603ea416 100644 --- a/scripts/verify-package.mjs +++ b/scripts/verify-package.mjs @@ -345,17 +345,22 @@ try { ); const planned = json(plannedExecution.stdout); if (supportedSetupHost) { + const plannedClaudeConfig = await readFile(claudeConfig, "utf8"); + const plannedCursorConfig = await readFile(cursorConfig, "utf8"); + const plannedSkill = await readFile(skillPath, "utf8"); if ( planned.status !== "needs_confirmation" || plannedExecution.status !== 1 || planned.appliedActions.length !== 0 || !planned.plannedActions.some(({ kind }) => kind === "configure_client") || !planned.plannedActions.some(({ kind }) => kind === "install_skill") || - (await readFile(claudeConfig, "utf8")) !== '{"existing":true}\n' || - (await readFile(cursorConfig, "utf8")) !== '{"existing":true}\n' || - (await readFile(skillPath, "utf8")) !== "stale managed skill\n" + plannedClaudeConfig !== '{"existing":true}\n' || + plannedCursorConfig !== '{"existing":true}\n' || + plannedSkill !== "stale managed skill\n" ) - throw new Error("packaged setup plan mutated files before approval"); + throw new Error( + `packaged setup plan was not read-only: ${JSON.stringify({ status: planned.status, exitCode: plannedExecution.status, plannedKinds: planned.plannedActions.map(({ kind }) => kind), appliedKinds: planned.appliedActions.map(({ kind }) => kind), claudeConfig: plannedClaudeConfig, cursorConfig: plannedCursorConfig, skill: plannedSkill })}`, + ); } const firstExecution = await runWithStatus( cli, diff --git a/scripts/verify-published-package.mjs b/scripts/verify-published-package.mjs index 7b6e0da78..cc9dc7847 100644 --- a/scripts/verify-published-package.mjs +++ b/scripts/verify-published-package.mjs @@ -22,7 +22,7 @@ transport.stderr?.on("data", (chunk) => { try { await client.connect(transport); const tools = await client.listTools(); - if (tools.tools.length !== 70) + if (tools.tools.length !== 78) throw new Error( `Published MCP exposed ${String(tools.tools.length)} tools`, ); @@ -40,5 +40,5 @@ try { } process.stdout.write( - `${JSON.stringify({ package: "rea-agents", version, mcpTools: 70 })}\n`, + `${JSON.stringify({ package: "rea-agents", version, mcpTools: 78 })}\n`, ); diff --git a/scripts/verify-real-browser.mjs b/scripts/verify-real-browser.mjs index 835c2141c..d2cf3c221 100644 --- a/scripts/verify-real-browser.mjs +++ b/scripts/verify-real-browser.mjs @@ -2,28 +2,34 @@ import { spawn } from "node:child_process"; import { access, mkdtemp, readFile, rm } from "node:fs/promises"; -import { createServer } from "node:http"; import { tmpdir } from "node:os"; import { join } from "node:path"; -import { WebSocketServer } from "ws"; - import { CdpBrowserProvider } from "../dist/browser/CdpBrowserProvider.js"; import { inspectWebPageInputSchema, listBrowserTargetsInputSchema, } from "../dist/domain/browserObservation.js"; +import { analyzeWebBundleInputSchema } from "../dist/domain/webBundleAnalysis.js"; +import { observeWebSessionInputSchema } from "../dist/domain/browserSession.js"; +import { compareWebCapturesInputSchema } from "../dist/domain/webCaptureDiff.js"; +import { + captureWebScreenshotInputSchema, + compareWebScreenshotsInputSchema, +} from "../dist/domain/webScreenshot.js"; +import { startBrowserVerifierSite } from "./fixtures/browser-verifier-site.mjs"; const SECRET_VALUES = [ "network-secret-value", "console-secret-value", "storage-secret-value", "websocket-secret-value", + "ax-private-label-value", ]; const executable = await browserExecutable(); const profile = await mkdtemp(join(tmpdir(), "rea-real-browser-")); -const site = await startSite(); +const site = await startBrowserVerifierSite(); let browser; try { browser = spawn( @@ -77,19 +83,113 @@ try { approved: true, target_id: target, observation_ms: 200, + include_accessibility_text: true, include_script_sources: true, + include_console_text: true, + console_text_approved: true, + include_json_body_shapes: true, + json_body_schema_approved: true, + include_websocket_shapes: true, + websocket_shape_approved: true, }), ); if (!withSource.ok) throw withSource.error; const source = withSource.value.scripts.items.find( (script) => script.source.included && - script.source.content.includes("reaSourceMarker"), + script.source.artifact.text.includes("reaSourceMarker"), ); if (source === undefined) throw new Error( "Real Chrome did not return explicitly approved script source", ); + if ( + !withSource.value.accessibility.nodes.some((node) => + node.name?.includes("ax-private-label-value"), + ) + ) + throw new Error( + "Real Chrome did not return independently approved accessibility text", + ); + assertSensitiveShapes(withSource.value); + + const bundle = await provider.analyzeBundle( + analyzeWebBundleInputSchema.parse({ + cdp_endpoint: endpoint, + allowed_origins: [site.origin], + approved: true, + target_id: target, + observation_ms: 200, + source_capture_approved: true, + fetch_source_maps: true, + source_map_fetch_approved: true, + }), + ); + if (!bundle.ok) throw bundle.error; + assertBundleAnalysis(bundle.value); + + const captureDiff = await provider.compareCaptures( + compareWebCapturesInputSchema.parse({ + before: { inspection: observed.value }, + after: { inspection: withSource.value }, + }), + ); + if (!captureDiff.ok) throw captureDiff.error; + if ( + captureDiff.value.dimensions.dom_structure.status !== "unchanged" || + captureDiff.value.dimensions.scripts.status !== "unchanged" + ) + throw new Error("Real Chrome stable capture identities did not reconcile"); + + const screenshot = await provider.captureScreenshot( + captureWebScreenshotInputSchema.parse({ + cdp_endpoint: endpoint, + allowed_origins: [site.origin], + approved: true, + screenshot_approved: true, + target_id: target, + }), + ); + if (!screenshot.ok) throw screenshot.error; + if ( + screenshot.value.viewport.width < 1 || + screenshot.value.viewport.height < 1 || + screenshot.value.artifact.bytes < 1 + ) + throw new Error("Real Chrome screenshot artifact was empty"); + const screenshotDiff = await provider.compareScreenshots( + compareWebScreenshotsInputSchema.parse({ + before: screenshot.value.artifact, + after: screenshot.value.artifact, + }), + ); + if (!screenshotDiff.ok) throw screenshotDiff.error; + if ( + screenshotDiff.value.status !== "identical" || + screenshotDiff.value.changed_pixels !== 0 + ) + throw new Error("Real Chrome PNG artifact did not compare identically"); + + const sessionPromise = provider.observeSession( + observeWebSessionInputSchema.parse({ + cdp_endpoint: endpoint, + allowed_origins: [site.origin], + approved: true, + target_id: target, + observation_ms: 1_500, + }), + ); + await delay(250); + site.triggerSessionNavigation(); + const session = await sessionPromise; + if (!session.ok) throw session.error; + if ( + !session.value.timeline.some( + ({ type }) => type === "same_document_navigation", + ) || + !session.value.target.final_url?.includes("/app/session-1") + ) + throw new Error("Real Chrome same-origin SPA timeline was missing"); process.stdout.write( `${JSON.stringify({ @@ -102,6 +202,10 @@ try { networkRequests: observed.value.network.requests.length, consoleEvents: observed.value.console.events.length, websocketEvents: observed.value.network.websocket_events.length, + bundleScripts: bundle.value.capture.scripts_analyzed, + sourceMaps: bundle.value.observations.source_maps.processed, + sessionEvents: session.value.timeline.length, + screenshotBytes: screenshot.value.artifact.bytes, verified: true, })}\n`, ); @@ -178,6 +282,13 @@ function assertObservation(result, origin) { ); if (result.accessibility.nodes.length < 1) throw new Error("Real Chrome accessibility observation was empty"); + if ( + result.accessibility.text_capture.status !== "not_approved" || + result.accessibility.nodes.some( + (node) => node.name !== null || node.description !== null, + ) + ) + throw new Error("Accessibility text was retained without approval"); if (!result.scripts.items.some((script) => script.url.includes("/app.js"))) throw new Error("Real Chrome script metadata was missing"); if (!result.resources.some((resource) => resource.url.includes("/app.js"))) @@ -186,86 +297,121 @@ function assertObservation(result, origin) { throw new Error( "Real Chrome attach-window network observation was missing", ); + const initiatedRequest = result.network.requests.find((request) => + request.url.includes("/api"), + ); + if ( + !initiatedRequest?.initiator.url?.includes("/app.js") || + initiatedRequest.initiator.line === null || + initiatedRequest.initiator.column === null + ) + throw new Error("Real Chrome script initiator stack was not normalized"); if (result.console.events.length < 1) throw new Error( "Real Chrome attach-window console observation was missing", ); if (result.network.websocket_events.length < 1) throw new Error("Real Chrome WebSocket metadata was missing"); + if ( + result.console.events.some( + (event) => event.text_capture.status !== "not_approved", + ) || + result.network.requests.some( + (request) => request.body_shapes.status !== "not_approved", + ) || + result.network.websocket_events.some( + (event) => event.payload_shape !== null, + ) + ) + throw new Error( + "Sensitive text or payload shapes were retained without approval", + ); if (!result.storage.local_storage_keys.includes("rea-storage-key")) throw new Error("Real Chrome local-storage key inventory was missing"); if (!result.storage.indexed_db_names.includes("rea-browser-db")) throw new Error("Real Chrome IndexedDB name inventory was missing"); if (!result.storage.cache_names.includes("rea-browser-cache")) throw new Error("Real Chrome cache name inventory was missing"); + if ( + !result.metadata.responses.some(({ csp }) => + csp.directives.some(({ name }) => name === "default-src"), + ) || + !result.metadata.agent_hints.some( + ({ declaration }) => declaration === "service-desc", + ) + ) + throw new Error("Real Chrome safe response metadata was missing"); } -async function startSite() { - let port = 0; - const server = createServer((request, response) => { - if (request.url?.startsWith("/app.js") === true) { - response.setHeader("content-type", "text/javascript"); - response.end(script(port)); - return; - } - if (request.url?.startsWith("/api") === true) { - response.setHeader("content-type", "application/json"); - response.end('{"ok":true,"secret":"response-secret-value"}'); - return; - } - response.setHeader("content-type", "text/html"); - response.end( - 'REA browser verifier

Browser evidence

', +function assertBundleAnalysis(result) { + if ( + result.capture.scripts_analyzed < 1 || + !result.observations.routes.some(({ value }) => + value.includes("/verified-route"), + ) || + !result.observations.endpoints.some(({ value }) => value.includes("/api")) + ) + throw new Error("Real Chrome static bundle findings were missing"); + if ( + result.observations.source_maps.status !== "included" || + !result.observations.source_maps.items.some( + ({ status, original_sources, original_module_edges, mappings }) => + status === "included" && + original_sources.some(({ source }) => + source.includes("/src/main.ts"), + ) && + original_module_edges.some( + ({ specifier }) => specifier === "./dependency.ts", + ) && + mappings.length > 0, + ) + ) + throw new Error( + "Real Chrome approved source-map reconstruction was missing", ); - }); - const webSockets = new WebSocketServer({ noServer: true }); - server.on("upgrade", (request, socket, head) => { - webSockets.handleUpgrade(request, socket, head, (webSocket) => { - webSocket.on("message", () => - webSocket.send("websocket-response-secret"), - ); - }); - }); - await new Promise((resolve, reject) => { - server.once("error", reject); - server.listen(0, "127.0.0.1", resolve); - }); - const address = server.address(); - if (address === null || typeof address === "string") - throw new Error("Local browser verifier did not bind a TCP port"); - port = address.port; - return { - origin: `http://127.0.0.1:${String(port)}`, - async close() { - for (const client of webSockets.clients) client.terminate(); - await new Promise((resolve) => webSockets.close(resolve)); - await new Promise((resolve, reject) => - server.close((error) => - error === undefined ? resolve() : reject(error), - ), - ); - }, - }; } -function script(port) { - return ` - export const reaSourceMarker = "approved-source-marker"; - localStorage.setItem("rea-storage-key", "storage-secret-value"); - indexedDB.open("rea-browser-db", 1); - caches.open("rea-browser-cache"); - const observe = () => { - console.log("rea-browser-observation", "console-secret-value"); - fetch("/api?token=network-secret-value", { - headers: { Authorization: "Bearer request-secret-value" } - }); - const socket = new WebSocket("ws://127.0.0.1:${String(port)}/live?token=websocket-url-secret"); - socket.addEventListener("open", () => socket.send("websocket-secret-value")); - socket.addEventListener("message", () => socket.close()); - }; - observe(); - setInterval(observe, 150); -`; +function assertSensitiveShapes(result) { + const request = result.network.requests.find((item) => + item.url.includes("/api"), + ); + const requestPaths = request?.body_shapes.request?.properties.map( + ({ path }) => path, + ); + const responsePaths = request?.body_shapes.response?.properties.map( + ({ path }) => path, + ); + if (!requestPaths?.includes("/token") || !responsePaths?.includes("/secret")) + throw new Error("Real Chrome JSON request/response shapes were missing"); + const consoleText = result.console.events.flatMap( + (event) => event.text_capture.values, + ); + if ( + !consoleText.some(({ text }) => text.includes("[REDACTED]")) || + consoleText.some(({ text }) => text.includes("console-secret-value")) + ) + throw new Error( + "Real Chrome approved console text was not safely redacted", + ); + if ( + !result.network.websocket_events.some( + (event) => + event.payload_shape?.format === "json" && + event.payload_shape.json_shape?.properties.some( + ({ path }) => path === "/token", + ), + ) + ) + throw new Error("Real Chrome WebSocket JSON shape was missing"); + const serialized = JSON.stringify(result); + for (const secret of [ + "request-body-secret-value", + "response-secret-value", + "websocket-secret-value", + "console-secret-value", + ]) + if (serialized.includes(secret)) + throw new Error(`Approved shape capture retained raw value: ${secret}`); } function delay(milliseconds) { diff --git a/scripts/verify-real-hopper.mjs b/scripts/verify-real-hopper.mjs index 2914f11a3..80f249f78 100644 --- a/scripts/verify-real-hopper.mjs +++ b/scripts/verify-real-hopper.mjs @@ -300,7 +300,7 @@ try { const expectedNames = TOOL_CONTRACTS.map(({ name }) => name).sort(); const actualNames = listed.tools.map(({ name }) => name).sort(); if (JSON.stringify(actualNames) !== JSON.stringify(expectedNames)) { - throw new Error("The real server did not expose the intended 70 tools"); + throw new Error("The real server did not expose the intended 78 tools"); } const options = { timeout }; diff --git a/skills/rea-analysis/SKILL.md b/skills/rea-analysis/SKILL.md index 4902a925d..5a9caf4a7 100644 --- a/skills/rea-analysis/SKILL.md +++ b/skills/rea-analysis/SKILL.md @@ -2,16 +2,18 @@ name: rea-analysis description: Reverse engineer apps and websites with REA. Explore how features work, then build a version tailored to your project. metadata: - version: "13" - tool_count: 70 + version: "14" + tool_count: 78 --- # REA Use REA when the user wants to understand how an app or feature works, compare app versions, decompile code, or build a similar feature. -For a website already open in a user-owned Chrome-family browser, use -`list_browser_targets` and `inspect_web_page` instead of opening a binary. Ask +For a website already open in a user-owned Chrome-family browser, start with +`list_browser_targets` and `inspect_web_page` instead of opening a binary. Use +`analyze_web_bundle`, `observe_web_session`, `discover_webmcp_tools`, capture +comparison, or screenshot tools only for the corresponding investigation. Ask the user to approve the exact page origins and loopback CDP endpoint before the first call. Browser observation is disabled unless the operator configured `REA_BROWSER_OBSERVE_ENABLED`, `REA_BROWSER_CDP_ENDPOINTS_JSON`, and @@ -19,11 +21,19 @@ first call. Browser observation is disabled unless the operator configured Browser inspection is passive. Never claim that it clicked, navigated, evaluated page JavaScript, captured prior activity, or contained the page's -network. Query values, headers, bodies, cookies, storage values, console values, -and WebSocket payloads are deliberately absent. Request script sources or -storage key names only when the user separately approves those more sensitive -outputs. Treat truncation and attach-window coverage as explicit limitations, -and cite the returned Evidence v2 IDs. +network. Query values, credentials, cookies, authorization headers, storage +values, and raw WebSocket or JSON values are deliberately absent. Accessibility +text, bounded redacted console primitives, value-free JSON/WebSocket shapes, +script sources, storage key names, source-map fetches, and screenshot pixels +each require their documented independent opt-in or approval. Treat truncation, +policy filtering, and attach-window coverage as explicit limitations, and cite +the returned Evidence v2 IDs. WebMCP declarations are page-declared untrusted; +REA inventories them but never invokes them. + +Electron `file://` pages use `list_electron_targets` and +`inspect_electron_page` with a separate loopback endpoint and canonical +filesystem-root authority. Never claim that Electron inspection invoked IPC, +evaluated renderer JavaScript, navigated, or escaped an approved root. ## Understand the request diff --git a/src/application/BrowserEvidence.ts b/src/application/BrowserEvidence.ts index edba27982..2e7306467 100644 --- a/src/application/BrowserEvidence.ts +++ b/src/application/BrowserEvidence.ts @@ -11,29 +11,73 @@ import type { ListBrowserTargetsInput, WebPageInspection, } from "../domain/browserObservation.js"; +import type { + AnalyzeWebBundleInput, + WebBundleAnalysis, +} from "../domain/webBundleAnalysis.js"; +import type { + ObserveWebSessionInput, + WebObservationSession, +} from "../domain/browserSession.js"; +import type { + DiscoverWebMcpToolsInput, + WebMcpDiscovery, +} from "../domain/webMcpDiscovery.js"; +import type { + CompareWebCapturesInput, + WebCaptureDiff, +} from "../domain/webCaptureDiff.js"; +import type { + CaptureWebScreenshotInput, + CompareWebScreenshotsInput, + WebScreenshot, + WebScreenshotDiff, +} from "../domain/webScreenshot.js"; -type BrowserEvidenceInput = ListBrowserTargetsInput | InspectWebPageInput; -type BrowserEvidenceResult = BrowserTargetList | WebPageInspection; +type BrowserEvidenceInput = + | ListBrowserTargetsInput + | InspectWebPageInput + | AnalyzeWebBundleInput + | ObserveWebSessionInput + | DiscoverWebMcpToolsInput + | CompareWebCapturesInput + | CaptureWebScreenshotInput + | CompareWebScreenshotsInput; +type BrowserEvidenceResult = + | BrowserTargetList + | WebPageInspection + | WebBundleAnalysis + | WebObservationSession + | WebMcpDiscovery + | WebCaptureDiff + | 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"; /** Create Evidence v2 for a policy-scoped external browser observation. */ export const createBrowserEvidence = ( - operation: "list_browser_targets" | "inspect_web_page", + operation: BrowserEvidenceOperation, input: BrowserEvidenceInput, result: BrowserEvidenceResult, provider: ProviderIdentity, ): Evidence => createEvidence(undefined, provider, { - predicateType: - operation === "list_browser_targets" - ? "rea.browser-target-list/v1" - : "rea.web-page-inspection/v1", + predicateType: browserPredicate(operation), operation, parameters: browserParameters(input), result: jsonValueSchema.parse(result), confidence: "observed", authority: "external-service", environment: - "target" in result + "browser" in result ? { id: `${result.browser.product}@${result.browser.revision}`, platform: process.platform, @@ -46,16 +90,92 @@ export const createBrowserEvidence = ( const browserParameters = ( input: BrowserEvidenceInput, -): EvidenceObservation["parameters"] => ({ - cdp_endpoint: input.cdp_endpoint, - allowed_origins: input.allowed_origins, - ...("target_id" in input - ? { - target_id: input.target_id, - observation_ms: input.observation_ms, - include_script_sources: input.include_script_sources, - include_storage_keys: input.include_storage_keys, - limits: input.limits, - } - : { offset: input.offset, limit: input.limit }), -}); +): EvidenceObservation["parameters"] => { + if (!("cdp_endpoint" in input)) { + if ("max_changes" in input) + 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, + max_changes: input.max_changes, + }; + return { + before_artifact_uri: input.before.uri, + after_artifact_uri: input.after.uri, + channel_threshold: input.channel_threshold, + maximum_pixels: input.maximum_pixels, + }; + } + const scope = { + cdp_endpoint: input.cdp_endpoint, + allowed_origins: input.allowed_origins, + }; + if (!("target_id" in input)) + return { ...scope, offset: input.offset, limit: input.limit }; + if ("screenshot_approved" in input) + return { + ...scope, + target_id: input.target_id, + maximum_image_bytes: input.maximum_image_bytes, + }; + if ("max_tools" in input) + return { + ...scope, + target_id: input.target_id, + observation_ms: input.observation_ms, + max_tools: input.max_tools, + max_schema_bytes: input.max_schema_bytes, + max_schema_nodes: input.max_schema_nodes, + max_schema_depth: input.max_schema_depth, + }; + if (!("include_accessibility_text" in input)) + return { + ...scope, + target_id: input.target_id, + observation_ms: input.observation_ms, + max_timeline_events: input.max_timeline_events, + }; + return { + ...scope, + target_id: input.target_id, + observation_ms: input.observation_ms, + 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_script_sources: input.include_script_sources, + include_storage_keys: input.include_storage_keys, + limits: input.limits, + ...(input.include_script_sources && "source_capture_approved" in input + ? { + source_capture_approved: input.source_capture_approved, + fetch_source_maps: input.fetch_source_maps, + source_map_fetch_approved: input.source_map_fetch_approved, + analysis_limits: input.analysis_limits, + } + : {}), + }; +}; + +const browserPredicate = (operation: BrowserEvidenceOperation): string => { + switch (operation) { + case "list_browser_targets": + return "rea.browser-target-list/v1"; + case "inspect_web_page": + return "rea.web-page-inspection/v2"; + case "analyze_web_bundle": + return "rea.web-bundle-analysis/v1"; + case "observe_web_session": + return "rea.web-observation-session/v1"; + case "discover_webmcp_tools": + return "rea.webmcp-discovery/v1"; + case "compare_web_captures": + return "rea.web-capture-diff/v1"; + case "capture_web_screenshot": + return "rea.web-screenshot/v1"; + case "compare_web_screenshots": + return "rea.web-screenshot-diff/v1"; + } +}; diff --git a/src/application/BrowserObservationPort.ts b/src/application/BrowserObservationPort.ts index f9e3cb45a..d966785ab 100644 --- a/src/application/BrowserObservationPort.ts +++ b/src/application/BrowserObservationPort.ts @@ -6,6 +6,28 @@ import type { WebPageInspection, } from "../domain/browserObservation.js"; import type { Result } from "../domain/result.js"; +import type { + AnalyzeWebBundleInput, + WebBundleAnalysis, +} from "../domain/webBundleAnalysis.js"; +import type { + ObserveWebSessionInput, + WebObservationSession, +} from "../domain/browserSession.js"; +import type { + DiscoverWebMcpToolsInput, + WebMcpDiscovery, +} from "../domain/webMcpDiscovery.js"; +import type { + CompareWebCapturesInput, + WebCaptureDiff, +} from "../domain/webCaptureDiff.js"; +import type { + CaptureWebScreenshotInput, + CompareWebScreenshotsInput, + WebScreenshot, + WebScreenshotDiff, +} from "../domain/webScreenshot.js"; import type { ProviderIdentity } from "./AnalysisProvider.js"; import type { ExecutionOptions } from "./AnalysisProvider.js"; @@ -20,4 +42,26 @@ export interface BrowserObservationPort { input: InspectWebPageInput, options?: ExecutionOptions, ): Promise>; + analyzeBundle( + input: AnalyzeWebBundleInput, + options?: ExecutionOptions, + ): Promise>; + observeSession( + input: ObserveWebSessionInput, + options?: ExecutionOptions, + ): Promise>; + discoverWebMcpTools( + input: DiscoverWebMcpToolsInput, + options?: ExecutionOptions, + ): Promise>; + compareCaptures( + input: CompareWebCapturesInput, + ): Promise>; + captureScreenshot( + input: CaptureWebScreenshotInput, + options?: ExecutionOptions, + ): Promise>; + compareScreenshots( + input: CompareWebScreenshotsInput, + ): Promise>; } diff --git a/src/application/BrowserObservationService.ts b/src/application/BrowserObservationService.ts index 859a33168..6ad7c1f58 100644 --- a/src/application/BrowserObservationService.ts +++ b/src/application/BrowserObservationService.ts @@ -3,6 +3,14 @@ import type { InspectWebPageInput, ListBrowserTargetsInput, } from "../domain/browserObservation.js"; +import type { AnalyzeWebBundleInput } from "../domain/webBundleAnalysis.js"; +import type { ObserveWebSessionInput } from "../domain/browserSession.js"; +import type { DiscoverWebMcpToolsInput } from "../domain/webMcpDiscovery.js"; +import type { CompareWebCapturesInput } from "../domain/webCaptureDiff.js"; +import type { + CaptureWebScreenshotInput, + CompareWebScreenshotsInput, +} from "../domain/webScreenshot.js"; import { AnalysisCapabilityUnavailableError, AnalysisProtocolError, @@ -69,11 +77,154 @@ export const inspectWebPage = async ( : result; }; +/** Capture approved sources and derive bounded static web-bundle evidence. */ +export const analyzeWebBundle = async ( + browser: BrowserObservationPort | undefined, + authority: PermissionAuthority | undefined, + input: AnalyzeWebBundleInput, + options: ExecutionOptions = {}, +): Promise> => { + const ready = await prepare(browser, authority, input, "analyze_web_bundle"); + if (!ready.ok) return ready; + const analyzed = await ready.value.analyzeBundle(input, options); + if (!analyzed.ok) return analyzed; + return ok( + createBrowserEvidence( + "analyze_web_bundle", + input, + analyzed.value, + ready.value.identity(), + ), + ); +}; + +/** Observe navigation caused by external user actions during one armed window. */ +export const observeWebSession = async ( + browser: BrowserObservationPort | undefined, + authority: PermissionAuthority | undefined, + input: ObserveWebSessionInput, + options: ExecutionOptions = {}, +): Promise> => { + const ready = await prepare(browser, authority, input, "observe_web_session"); + if (!ready.ok) return ready; + const observed = await ready.value.observeSession(input, options); + return observed.ok + ? ok( + createBrowserEvidence( + "observe_web_session", + input, + observed.value, + ready.value.identity(), + ), + ) + : observed; +}; + +/** Discover WebMCP declarations without exposing an invocation surface. */ +export const discoverWebMcpTools = async ( + browser: BrowserObservationPort | undefined, + authority: PermissionAuthority | undefined, + input: DiscoverWebMcpToolsInput, + options: ExecutionOptions = {}, +): Promise> => { + const ready = await prepare( + browser, + authority, + input, + "discover_webmcp_tools", + ); + if (!ready.ok) return ready; + const discovered = await ready.value.discoverWebMcpTools(input, options); + return discovered.ok + ? ok( + createBrowserEvidence( + "discover_webmcp_tools", + input, + discovered.value, + ready.value.identity(), + ), + ) + : discovered; +}; + +/** Compare two already-normalized web captures without external access. */ +export const compareWebCaptureEvidence = async ( + browser: BrowserObservationPort | undefined, + input: CompareWebCapturesInput, +): Promise> => { + const ready = requireBrowser(browser, "compare_web_captures"); + if (!ready.ok) return ready; + const compared = await ready.value.compareCaptures(input); + return compared.ok + ? ok( + createBrowserEvidence( + "compare_web_captures", + input, + compared.value, + ready.value.identity(), + ), + ) + : compared; +}; + +/** Capture one explicitly approved visible-viewport screenshot. */ +export const captureWebScreenshot = async ( + browser: BrowserObservationPort | undefined, + authority: PermissionAuthority | undefined, + input: CaptureWebScreenshotInput, + options: ExecutionOptions = {}, +): Promise> => { + const ready = await prepare( + browser, + authority, + input, + "capture_web_screenshot", + ); + if (!ready.ok) return ready; + const captured = await ready.value.captureScreenshot(input, options); + return captured.ok + ? ok( + createBrowserEvidence( + "capture_web_screenshot", + input, + captured.value, + ready.value.identity(), + ), + ) + : captured; +}; + +/** Compare two self-verifying PNG artifacts without external access. */ +export const compareWebScreenshotEvidence = async ( + browser: BrowserObservationPort | undefined, + input: CompareWebScreenshotsInput, +): Promise> => { + const ready = requireBrowser(browser, "compare_web_screenshots"); + if (!ready.ok) return ready; + const compared = await ready.value.compareScreenshots(input); + return compared.ok + ? ok( + createBrowserEvidence( + "compare_web_screenshots", + input, + compared.value, + ready.value.identity(), + ), + ) + : compared; +}; + const prepare = async ( browser: BrowserObservationPort | undefined, authority: PermissionAuthority | undefined, input: ScopedBrowserInput, - operation: "list_browser_targets" | "inspect_web_page", + operation: + | "list_browser_targets" + | "inspect_web_page" + | "analyze_web_bundle" + | "observe_web_session" + | "discover_webmcp_tools" + | "capture_web_screenshot", ): Promise> => { if (authority === undefined) return err( @@ -115,6 +266,20 @@ const prepare = async ( : ok(browser); }; +const requireBrowser = ( + browser: BrowserObservationPort | undefined, + operation: string, +): Result => + browser === undefined + ? err( + new AnalysisCapabilityUnavailableError( + "rea-cdp-browser", + operation, + "browser comparison provider is not configured", + ), + ) + : ok(browser); + const browserNetworkScope = ( allowedOrigins: readonly string[], ): "loopback" | "external" => diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.ts index 95e637665..213edefb8 100644 --- a/src/application/CapabilityInventory.ts +++ b/src/application/CapabilityInventory.ts @@ -55,6 +55,7 @@ export const buildCapabilityInventory = ( readonly processCaptureEnabled: boolean; readonly evidenceFileRoots: number; readonly browserObservationEnabled?: boolean; + readonly electronObservationEnabled?: boolean; }, ) => { const status = statusSchema.parse(sessionStatus); @@ -99,6 +100,7 @@ const availabilityFor = ( readonly processCaptureEnabled: boolean; readonly evidenceFileRoots: number; readonly browserObservationEnabled?: boolean; + readonly electronObservationEnabled?: boolean; }, ): { readonly reason: ToolAvailabilityReason; @@ -123,6 +125,14 @@ const availabilityFor = ( remediation: "Enable browser observation and configure exact CDP endpoint and page origins.", }; + if (kind === "electron-provider") + return policy.electronObservationEnabled === true + ? { reason: "available", remediation: null } + : { + reason: "policy_disabled", + remediation: + "Enable Electron observation and configure a loopback CDP endpoint and canonical file roots.", + }; if (kind === "session") return { reason: "available", remediation: null }; if (!targetOpen) return { diff --git a/src/application/ElectronEvidence.ts b/src/application/ElectronEvidence.ts new file mode 100644 index 000000000..7bc33d683 --- /dev/null +++ b/src/application/ElectronEvidence.ts @@ -0,0 +1,60 @@ +import type { ProviderIdentity } from "./AnalysisProvider.js"; +import { + createEvidence, + type Evidence, + type EvidenceObservation, +} from "../domain/evidence.js"; +import { jsonValueSchema } from "../domain/jsonValue.js"; +import type { + ElectronPageInspection, + ElectronTargetList, + InspectElectronPageInput, + ListElectronTargetsInput, +} from "../domain/electronObservation.js"; + +type ElectronOperation = "list_electron_targets" | "inspect_electron_page"; + +/** Create Evidence v2 for one root-confined Electron observation. */ +export const createElectronEvidence = ( + operation: ElectronOperation, + input: ListElectronTargetsInput | InspectElectronPageInput, + result: ElectronTargetList | ElectronPageInspection, + provider: ProviderIdentity, +): Evidence => + createEvidence(undefined, provider, { + predicateType: + operation === "list_electron_targets" + ? "rea.electron-target-list/v1" + : "rea.electron-page-inspection/v1", + operation, + parameters: parameters(input), + result: jsonValueSchema.parse(result), + confidence: "observed", + authority: "external-service", + environment: + "target" in result + ? { + id: `${result.browser.product}@${result.browser.revision}`, + platform: process.platform, + architecture: process.arch, + isolation: "none", + } + : null, + limitations: result.limitations, + }); + +const parameters = ( + input: ListElectronTargetsInput | InspectElectronPageInput, +): EvidenceObservation["parameters"] => ({ + cdp_endpoint: input.cdp_endpoint, + allowed_file_roots: input.allowed_file_roots, + ...("target_id" in input + ? { + target_id: input.target_id, + observation_ms: input.observation_ms, + include_script_sources: input.include_script_sources, + source_capture_approved: input.source_capture_approved, + limits: input.limits, + } + : { offset: input.offset, limit: input.limit }), +}); diff --git a/src/application/ElectronObservationPort.ts b/src/application/ElectronObservationPort.ts new file mode 100644 index 000000000..3b882cae9 --- /dev/null +++ b/src/application/ElectronObservationPort.ts @@ -0,0 +1,22 @@ +import type { ExecutionOptions, ProviderIdentity } from "./AnalysisProvider.js"; +import type { AnalysisError } from "../domain/errors.js"; +import type { + ElectronPageInspection, + ElectronTargetList, + InspectElectronPageInput, + ListElectronTargetsInput, +} from "../domain/electronObservation.js"; +import type { Result } from "../domain/result.js"; + +/** Provider-neutral boundary for root-confined Electron file-page observation. */ +export interface ElectronObservationPort { + identity(): ProviderIdentity; + listTargets( + input: ListElectronTargetsInput, + options?: ExecutionOptions, + ): Promise>; + inspectPage( + input: InspectElectronPageInput, + options?: ExecutionOptions, + ): Promise>; +} diff --git a/src/application/ElectronObservationService.ts b/src/application/ElectronObservationService.ts new file mode 100644 index 000000000..6b007cb0e --- /dev/null +++ b/src/application/ElectronObservationService.ts @@ -0,0 +1,116 @@ +import type { ExecutionOptions } from "./AnalysisProvider.js"; +import type { ElectronObservationPort } from "./ElectronObservationPort.js"; +import type { PermissionAuthority } from "./PermissionAuthority.js"; +import type { Evidence } from "../domain/evidence.js"; +import type { + InspectElectronPageInput, + ListElectronTargetsInput, +} from "../domain/electronObservation.js"; +import { + AnalysisCapabilityUnavailableError, + AnalysisProtocolError, + PermissionRequiredError, + type AnalysisError, +} from "../domain/errors.js"; +import { err, ok, type Result } from "../domain/result.js"; +import { createElectronEvidence } from "./ElectronEvidence.js"; + +/** Authorize and list root-confined Electron page targets. */ +export const listElectronTargets = async ( + provider: ElectronObservationPort | undefined, + authority: PermissionAuthority | undefined, + input: ListElectronTargetsInput, + options: ExecutionOptions = {}, +): Promise> => { + const ready = await prepare( + provider, + authority, + input, + "list_electron_targets", + ); + if (!ready.ok) return ready; + const result = await ready.value.listTargets(input, options); + return result.ok + ? ok( + createElectronEvidence( + "list_electron_targets", + input, + result.value, + ready.value.identity(), + ), + ) + : result; +}; + +/** Authorize and inspect one root-confined Electron page. */ +export const inspectElectronPage = async ( + provider: ElectronObservationPort | undefined, + authority: PermissionAuthority | undefined, + input: InspectElectronPageInput, + options: ExecutionOptions = {}, +): Promise> => { + const ready = await prepare( + provider, + authority, + input, + "inspect_electron_page", + ); + if (!ready.ok) return ready; + const result = await ready.value.inspectPage(input, options); + return result.ok + ? ok( + createElectronEvidence( + "inspect_electron_page", + input, + result.value, + ready.value.identity(), + ), + ) + : result; +}; + +const prepare = async ( + provider: ElectronObservationPort | undefined, + authority: PermissionAuthority | undefined, + input: ListElectronTargetsInput | InspectElectronPageInput, + operation: "list_electron_targets" | "inspect_electron_page", +): Promise> => { + if (authority === undefined) + return err( + new AnalysisCapabilityUnavailableError( + "rea-cdp-electron", + operation, + "Electron observation permission policy is not configured", + ), + ); + const authorized = await authority.authorize( + { + capability: "electron_observe", + roots: input.allowed_file_roots, + executables: [], + environment_names: [], + origins: [input.cdp_endpoint], + network: "loopback", + mount: false, + operation_identity: `${operation}:${"target_id" in input ? input.target_id : input.cdp_endpoint}`, + }, + "read", + ); + if (!authorized.ok) + return err( + authorized.error instanceof PermissionRequiredError + ? authorized.error + : new AnalysisProtocolError(authorized.error.message, { + cause: authorized.error, + }), + ); + return provider === undefined + ? err( + new AnalysisCapabilityUnavailableError( + "rea-cdp-electron", + operation, + "Electron observation provider is not configured", + ), + ) + : ok(provider); +}; diff --git a/src/application/ProjectPermissionStore.ts b/src/application/ProjectPermissionStore.ts index 2c52c77dd..7d4d4b90a 100644 --- a/src/application/ProjectPermissionStore.ts +++ b/src/application/ProjectPermissionStore.ts @@ -23,6 +23,7 @@ const grantSchema = z.object({ capability: z.enum([ "process_capture", "browser_observe", + "electron_observe", "evidence_read", "evidence_write", "investigation_input", diff --git a/src/browser/CdpBrowserProvider.ts b/src/browser/CdpBrowserProvider.ts index 67914d98b..b49202f0c 100644 --- a/src/browser/CdpBrowserProvider.ts +++ b/src/browser/CdpBrowserProvider.ts @@ -10,10 +10,41 @@ import { type ListBrowserTargetsInput, type WebPageInspection, } from "../domain/browserObservation.js"; +import { analyzeCapturedWebBundle } from "../domain/webBundleAnalyzer.js"; +import { + webBundleAnalysisSchema, + type AnalyzeWebBundleInput, + type WebBundleAnalysis, +} from "../domain/webBundleAnalysis.js"; +import { + webObservationSessionSchema, + type ObserveWebSessionInput, + type WebObservationSession, +} from "../domain/browserSession.js"; +import { + webMcpDiscoverySchema, + type DiscoverWebMcpToolsInput, + type WebMcpDiscovery, +} from "../domain/webMcpDiscovery.js"; +import { + compareWebCaptures, + webCaptureDiffSchema, + type CompareWebCapturesInput, + type WebCaptureDiff, +} from "../domain/webCaptureDiff.js"; +import { + webScreenshotDiffSchema, + webScreenshotSchema, + type CaptureWebScreenshotInput, + type CompareWebScreenshotsInput, + type WebScreenshot, + type WebScreenshotDiff, +} from "../domain/webScreenshot.js"; import { AnalysisError, BrowserObservationError, ProviderAdapterError, + type BrowserObservationOperation, } from "../domain/errors.js"; import { err, ok, type Result } from "../domain/result.js"; import { CdpConnection } from "./CdpConnection.js"; @@ -22,12 +53,17 @@ import { type CdpEndpointDiscovery, type CdpEndpointTarget, } from "./CdpEndpoint.js"; -import { capturePage } from "./CdpPageCapture.js"; +import { capturePage, type CapturedPage } from "./CdpPageCapture.js"; +import { fetchWebSourceMaps } from "./WebSourceMapFetcher.js"; +import { observeCdpSession } from "./CdpObservationSession.js"; +import { discoverWebMcp } from "./CdpWebMcpDiscovery.js"; +import { captureCdpScreenshot } from "./CdpScreenshot.js"; +import { comparePngScreenshots } from "./PngVisualDiff.js"; const IDENTITY: ProviderIdentity = { id: "rea-cdp-browser", name: "REA Chrome DevTools Protocol observation provider", - version: "1", + version: "2", }; /** Passive, origin-scoped browser observation through a user-owned CDP endpoint. */ @@ -81,6 +117,41 @@ export class CdpBrowserProvider implements BrowserObservationPort { input: InspectWebPageInput, options: ExecutionOptions = {}, ): Promise> { + try { + const captured = await this.#capture(input, options); + return ok(webPageInspectionSchema.parse(captured.inspection)); + } catch (cause: unknown) { + return err(providerError(cause, "inspect_web_page")); + } + } + + async analyzeBundle( + input: AnalyzeWebBundleInput, + options: ExecutionOptions = {}, + ): Promise> { + try { + const captured = await this.#capture(input, options); + const sourceMaps = input.fetch_source_maps + ? await fetchWebSourceMaps( + captured.sourceMapRequests, + input, + options.signal, + ) + : undefined; + return ok( + webBundleAnalysisSchema.parse( + analyzeCapturedWebBundle(captured.inspection, input, sourceMaps), + ), + ); + } catch (cause: unknown) { + return err(providerError(cause, "analyze_web_bundle")); + } + } + + async observeSession( + input: ObserveWebSessionInput, + options: ExecutionOptions = {}, + ): Promise> { let connection: CdpConnection | undefined; let sessionId: string | undefined; try { @@ -101,7 +172,177 @@ export class CdpBrowserProvider implements BrowserObservationPort { options.signal, ); sessionId = attachedSessionId(attached); - const result = await capturePage({ + return ok( + webObservationSessionSchema.parse( + await observeCdpSession({ + connection, + sessionId, + discovery, + target, + input, + ...(options.signal === undefined ? {} : { signal: options.signal }), + ...(options.progress === undefined + ? {} + : { progress: options.progress }), + }), + ), + ); + } catch (cause: unknown) { + return err(providerError(cause, "observe_web_session")); + } finally { + if (connection !== undefined) { + if (sessionId !== undefined) + await bestEffortCleanup(connection, sessionId); + await connection.close(); + } + } + } + + async discoverWebMcpTools( + input: DiscoverWebMcpToolsInput, + options: ExecutionOptions = {}, + ): Promise> { + let connection: CdpConnection | undefined; + let sessionId: string | undefined; + try { + const discovery = await discoverCdpEndpoint( + input.cdp_endpoint, + "inspect_web_page", + options.signal, + ); + const target = authorizeTarget(discovery, input); + connection = await CdpConnection.connect( + discovery.browserWebSocketUrl, + options.signal, + ); + const attached = await connection.send( + "Target.attachToTarget", + { targetId: target.id, flatten: true }, + undefined, + options.signal, + ); + sessionId = attachedSessionId(attached); + return ok( + webMcpDiscoverySchema.parse( + await discoverWebMcp({ + connection, + sessionId, + discovery, + target, + input, + ...(options.signal === undefined ? {} : { signal: options.signal }), + ...(options.progress === undefined + ? {} + : { progress: options.progress }), + }), + ), + ); + } catch (cause: unknown) { + return err(providerError(cause, "discover_webmcp_tools")); + } finally { + if (connection !== undefined) { + if (sessionId !== undefined) + await bestEffortCleanup(connection, sessionId); + await connection.close(); + } + } + } + + async compareCaptures( + input: CompareWebCapturesInput, + ): Promise> { + try { + return ok(webCaptureDiffSchema.parse(compareWebCaptures(input))); + } catch (cause: unknown) { + return err(providerError(cause, "compare_web_captures")); + } + } + + async captureScreenshot( + input: CaptureWebScreenshotInput, + options: ExecutionOptions = {}, + ): Promise> { + let connection: CdpConnection | undefined; + let sessionId: string | undefined; + try { + const discovery = await discoverCdpEndpoint( + input.cdp_endpoint, + "inspect_web_page", + options.signal, + ); + const target = authorizeTarget(discovery, input); + connection = await CdpConnection.connect( + discovery.browserWebSocketUrl, + options.signal, + ); + const attached = await connection.send( + "Target.attachToTarget", + { targetId: target.id, flatten: true }, + undefined, + options.signal, + ); + sessionId = attachedSessionId(attached); + return ok( + webScreenshotSchema.parse( + await captureCdpScreenshot({ + connection, + sessionId, + discovery, + target, + input, + ...(options.signal === undefined ? {} : { signal: options.signal }), + ...(options.progress === undefined + ? {} + : { progress: options.progress }), + }), + ), + ); + } catch (cause: unknown) { + return err(providerError(cause, "capture_web_screenshot")); + } finally { + if (connection !== undefined) { + if (sessionId !== undefined) + await bestEffortCleanup(connection, sessionId); + await connection.close(); + } + } + } + + async compareScreenshots( + input: CompareWebScreenshotsInput, + ): Promise> { + try { + return ok(webScreenshotDiffSchema.parse(comparePngScreenshots(input))); + } catch (cause: unknown) { + return err(providerError(cause, "compare_web_screenshots")); + } + } + + async #capture( + input: InspectWebPageInput, + options: ExecutionOptions, + ): Promise { + let connection: CdpConnection | undefined; + let sessionId: string | undefined; + try { + const discovery = await discoverCdpEndpoint( + input.cdp_endpoint, + "inspect_web_page", + options.signal, + ); + const target = authorizeTarget(discovery, input); + connection = await CdpConnection.connect( + discovery.browserWebSocketUrl, + options.signal, + ); + const attached = await connection.send( + "Target.attachToTarget", + { targetId: target.id, flatten: true }, + undefined, + options.signal, + ); + sessionId = attachedSessionId(attached); + return await capturePage({ connection, sessionId, discovery, @@ -112,9 +353,6 @@ export class CdpBrowserProvider implements BrowserObservationPort { ? {} : { progress: options.progress }), }); - return ok(webPageInspectionSchema.parse(result)); - } catch (cause: unknown) { - return err(providerError(cause, "inspect_web_page")); } finally { if (connection !== undefined) { if (sessionId !== undefined) @@ -172,7 +410,7 @@ const selectTargets = ( const authorizeTarget = ( discovery: CdpEndpointDiscovery, - input: InspectWebPageInput, + input: Pick, ): CdpEndpointTarget => { const target = discovery.targets.find( (candidate) => candidate.id === input.target_id, @@ -222,8 +460,10 @@ const bestEffortCleanup = async ( const providerError = ( cause: unknown, - operation: "list_browser_targets" | "inspect_web_page", + operation: BrowserObservationOperation, ): AnalysisError => - cause instanceof AnalysisError - ? cause - : new ProviderAdapterError(IDENTITY.id, operation, { cause }); + cause instanceof BrowserObservationError && cause.operation !== operation + ? new BrowserObservationError(operation, cause.reason, { cause }) + : cause instanceof AnalysisError + ? cause + : new ProviderAdapterError(IDENTITY.id, operation, { cause }); diff --git a/src/browser/CdpCaptureCompleteness.ts b/src/browser/CdpCaptureCompleteness.ts new file mode 100644 index 000000000..48e66e311 --- /dev/null +++ b/src/browser/CdpCaptureCompleteness.ts @@ -0,0 +1,119 @@ +import { + classifyBrowserCompleteness, + type BrowserCompleteness, + type BrowserDroppedEventKind, + type BrowserDroppedEvents, + type BrowserExclusion, + type BrowserExclusionReason, + type BrowserSection, +} from "../domain/browserCompleteness.js"; + +const EVENT_SECTIONS: Readonly< + Record +> = { + scripts: "scripts", + network_requests: "network_requests", + console_events: "console_events", + websocket_connections: "websocket_connections", + websocket_frames: "websocket_frames", + webmcp_tools: "webmcp_tools", + timeline_events: "timeline", +}; + +const POLICY_REASONS = new Set([ + "disallowed_origin", + "unsupported_url", + "unattributed_origin", + "not_approved", + "out_of_target_scope", +]); + +/** Mutable adapter ledger projected into immutable, canonical completeness v2. */ +export class CdpCaptureCompleteness { + readonly #initialAttachLimited: readonly BrowserSection[]; + readonly #policyFiltered = new Set(); + readonly #attachLimited = new Set(); + readonly #truncated = new Set(); + readonly #unavailable = new Set(); + readonly #excluded = new Map(); + readonly #dropped: Omit = emptyDropped(); + + constructor(initialAttachLimited: readonly BrowserSection[] = []) { + this.#initialAttachLimited = [...initialAttachLimited]; + this.reset(); + } + + reset(): void { + this.#policyFiltered.clear(); + this.#attachLimited.clear(); + this.#truncated.clear(); + this.#unavailable.clear(); + this.#excluded.clear(); + Object.assign(this.#dropped, emptyDropped()); + for (const section of this.#initialAttachLimited) + this.#attachLimited.add(section); + } + + exclude( + section: BrowserSection, + reason: BrowserExclusionReason, + count: number | null = 1, + ): void { + if (POLICY_REASONS.has(reason)) this.#policyFiltered.add(section); + if ( + reason === "provider_unavailable" || + reason === "invalid_protocol_value" + ) + this.#unavailable.add(section); + const key = `${section}\0${reason}`; + const existing = this.#excluded.get(key); + const combined = + count === null || existing?.count === null + ? null + : (existing?.count ?? 0) + count; + this.#excluded.set(key, { section, reason, count: combined }); + } + + attachLimited(section: BrowserSection): void { + this.#attachLimited.add(section); + } + + unavailable(section: BrowserSection): void { + this.#unavailable.add(section); + this.exclude(section, "provider_unavailable", null); + } + + truncate(section: BrowserSection): void { + this.#truncated.add(section); + } + + drop(kind: BrowserDroppedEventKind, count = 1): void { + this.#dropped[kind] += count; + this.#truncated.add(EVENT_SECTIONS[kind]); + } + + get droppedTotal(): number { + return Object.values(this.#dropped).reduce((sum, count) => sum + count, 0); + } + + snapshot(): BrowserCompleteness { + return classifyBrowserCompleteness({ + policyFilteredSections: this.#policyFiltered, + attachLimitedSections: this.#attachLimited, + truncatedSections: this.#truncated, + unavailableSections: this.#unavailable, + excluded: [...this.#excluded.values()], + droppedEvents: this.#dropped, + }); + } +} + +const emptyDropped = (): Omit => ({ + scripts: 0, + network_requests: 0, + console_events: 0, + websocket_connections: 0, + websocket_frames: 0, + webmcp_tools: 0, + timeline_events: 0, +}); diff --git a/src/browser/CdpCaptureDocuments.ts b/src/browser/CdpCaptureDocuments.ts index b716dbf17..5f7173f74 100644 --- a/src/browser/CdpCaptureDocuments.ts +++ b/src/browser/CdpCaptureDocuments.ts @@ -5,6 +5,7 @@ import type { import { allowedSanitizedUrl, boundedText, + isHttpUrl, numberValue, recordValue, recordsValue, @@ -12,12 +13,19 @@ import { stringValue, type UnknownRecord, } from "./CdpCaptureValues.js"; +import type { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js"; + +export type CapturedResource = Omit< + WebPageInspection["resources"][number], + "resource_key" +> & { readonly rawUrl: string }; /** Normalize allowed frames while retaining a bounded prefix and total count. */ export const captureFrames = ( result: unknown, allowedOrigins: ReadonlySet, maximum: number, + completeness?: CdpCaptureCompleteness, ): { readonly total: number; readonly items: WebPageInspection["frames"]; @@ -30,14 +38,17 @@ export const captureFrames = ( const frame = recordValue(tree.frame); const frameId = stringValue(frame?.id); const sanitized = allowedSanitizedUrl(frame?.url, allowedOrigins); - if ( - frame === undefined || - frameId === undefined || - frameId.length > 256 || - sanitized === undefined || - sanitized.origin === null - ) + if (frame === undefined || frameId === undefined || frameId.length > 256) { + completeness?.exclude("frames", "invalid_protocol_value"); continue; + } + if (sanitized === undefined || sanitized.origin === null) { + completeness?.exclude( + "frames", + exclusionReasonForUrl(stringValue(frame.url)), + ); + continue; + } total += 1; if (items.length >= maximum) continue; items.push({ @@ -62,22 +73,30 @@ export const captureResources = ( result: unknown, allowedOrigins: ReadonlySet, maximum: number, + completeness?: CdpCaptureCompleteness, ): { readonly total: number; - readonly items: WebPageInspection["resources"]; + readonly items: readonly CapturedResource[]; } => { const root = recordValue(requiredRecord(result).frameTree); if (root === undefined) return { total: 0, items: [] }; - const items: WebPageInspection["resources"] = []; + const items: CapturedResource[] = []; let total = 0; for (const tree of walkFrameTrees(root)) { for (const resource of recordsValue(tree.resources)) { const url = allowedSanitizedUrl(resource.url, allowedOrigins); - if (url === undefined || url.origin === null) continue; + if (url === undefined || url.origin === null) { + completeness?.exclude( + "resources", + exclusionReasonForUrl(stringValue(resource.url)), + ); + continue; + } total += 1; if (items.length >= maximum) continue; const contentSize = numberValue(resource.contentSize); items.push({ + rawUrl: stringValue(resource.url) ?? "", url: url.url, origin: url.origin, type: (stringValue(resource.type) ?? "Other").slice(0, 100), @@ -110,20 +129,29 @@ export const captureDom = ( result: unknown, allowedOrigins: ReadonlySet, input: InspectWebPageInput, + completeness?: CdpCaptureCompleteness, ): { readonly total: number; readonly nodes: WebPageInspection["dom"]["nodes"]; + readonly urls: WebPageInspection["metadata"]["dom_urls"]; + readonly agentHints: WebPageInspection["metadata"]["agent_hints"]; + readonly excludedUrls: number; } => { const root = requiredRecord(result); const strings = Array.isArray(root.strings) ? root.strings.map((value) => stringValue(value) ?? "") : []; const nodes: WebPageInspection["dom"]["nodes"] = []; + const urls: WebPageInspection["metadata"]["dom_urls"] = []; + const agentHints: WebPageInspection["metadata"]["agent_hints"] = []; + let excludedUrls = 0; let total = 0; for (const document of recordsValue(root.documents)) { const documentUrl = indexedString(strings, document.documentURL); - if (allowedSanitizedUrl(documentUrl, allowedOrigins) === undefined) + if (allowedSanitizedUrl(documentUrl, allowedOrigins) === undefined) { + completeness?.exclude("dom", exclusionReasonForUrl(documentUrl)); continue; + } const documentNodes = recordValue(document.nodes); if (documentNodes === undefined) continue; const nodeTypes = numberArray(documentNodes.nodeType); @@ -142,42 +170,129 @@ export const captureDom = ( ) { const attributeIndexes = numberArray(attributes[index]); const parent = Math.trunc(parents[index] ?? -1); + const nodeIndex = nodes.length; + const nodeName = indexedString(strings, nodeNames[index]).slice(0, 256); nodes.push({ - index: nodes.length, + index: nodeIndex, parent_index: parent < 0 ? -1 : baseIndex + parent, node_type: Math.max(0, Math.trunc(nodeTypes[index] ?? 0)), - node_name: indexedString(strings, nodeNames[index]).slice(0, 256), + node_name: nodeName, node_value_length: indexedString(strings, nodeValues[index]).length, attribute_names: attributeIndexes .filter((_value, attributeIndex) => attributeIndex % 2 === 0) .map((value) => indexedString(strings, value).slice(0, 256)) .slice(0, 200), }); + const metadata = domMetadata( + strings, + attributeIndexes, + documentUrl, + nodeIndex, + nodeName, + allowedOrigins, + ); + for (const url of metadata.urls) { + if (urls.length >= input.limits.max_resources) { + completeness?.truncate("metadata"); + continue; + } + urls.push(url); + if (url.destination_scope !== "approved") { + excludedUrls += 1; + completeness?.exclude( + "metadata", + url.destination_scope === "outside_policy" + ? "disallowed_origin" + : "unsupported_url", + ); + } + } + agentHints.push(...metadata.agentHints); } } - return { total, nodes }; + return { + total, + nodes, + urls, + agentHints: agentHints.slice(0, input.limits.max_resources), + excludedUrls, + }; }; export const captureAccessibility = ( results: readonly unknown[], maximum: number, + options: { + readonly includeText: boolean; + readonly maximumFieldBytes: number; + readonly maximumTotalBytes: number; + readonly unavailable?: boolean; + }, ): { readonly total: number; readonly nodes: WebPageInspection["accessibility"]["nodes"]; + readonly textCapture: WebPageInspection["accessibility"]["text_capture"]; } => { const all = results.flatMap((result) => recordsValue(requiredRecord(result).nodes), ); - return { - total: all.length, - nodes: all.slice(0, maximum).map((node) => ({ + let retainedBytes = 0; + let excludedFields = 0; + let truncatedFields = 0; + const nodes = all.slice(0, maximum).map((node) => { + const captureText = (value: unknown): string | null => { + const raw = stringValue(recordValue(value)?.value); + if (raw === undefined) return null; + if (!options.includeText) { + excludedFields += 1; + return null; + } + const available = Math.max(0, options.maximumTotalBytes - retainedBytes); + const captured = boundedUtf8( + raw, + Math.min(options.maximumFieldBytes, available), + ); + retainedBytes += captured.bytes; + if (captured.truncated) { + truncatedFields += 1; + if (captured.text === "" && raw !== "") { + excludedFields += 1; + return null; + } + } + return captured.text; + }; + return { node_id: (stringValue(node.nodeId) ?? "").slice(0, 256), parent_id: (stringValue(node.parentId) ?? "").slice(0, 256) || null, role: axText(node.role), - name: axText(node.name), - description: axText(node.description), + name: captureText(node.name), + description: captureText(node.description), ignored: node.ignored === true, - })), + }; + }); + for (const node of all.slice(maximum)) { + for (const value of [node.name, node.description]) { + if (stringValue(recordValue(value)?.value) === undefined) continue; + excludedFields += 1; + if (options.includeText) truncatedFields += 1; + } + } + return { + total: all.length, + nodes, + textCapture: { + status: options.unavailable + ? "unavailable" + : !options.includeText + ? "not_approved" + : truncatedFields > 0 + ? "truncated" + : "included", + retained_bytes: retainedBytes, + excluded_fields: excludedFields, + truncated_fields: truncatedFields, + }, }; }; @@ -196,3 +311,112 @@ const numberArray = (value: unknown): readonly number[] => return number === undefined ? [] : [number]; }) : []; + +const domMetadata = ( + strings: readonly string[], + attributes: readonly number[], + documentUrl: string, + nodeIndex: number, + nodeName: string, + allowedOrigins: ReadonlySet, +): { + readonly urls: WebPageInspection["metadata"]["dom_urls"]; + readonly agentHints: WebPageInspection["metadata"]["agent_hints"]; +} => { + const pairs = new Map(); + for (let index = 0; index + 1 < attributes.length; index += 2) { + const name = indexedString(strings, attributes[index]).toLowerCase(); + const value = indexedString(strings, attributes[index + 1]); + pairs.set(name, value); + } + const urls: WebPageInspection["metadata"]["dom_urls"] = []; + for (const attribute of domUrlAttributes) { + const value = pairs.get(attribute); + if (value === undefined) continue; + const destination = domDestination(value, documentUrl, allowedOrigins); + urls.push({ + node_index: nodeIndex, + attribute, + url: destination.url, + destination_scope: destination.scope, + }); + } + const rel = (pairs.get("rel") ?? "") + .toLowerCase() + .split(/\s+/u) + .filter((value) => agentRelValues.includes(value)); + const href = urls.find(({ attribute }) => attribute === "href")?.url ?? null; + const agentHints = + nodeName.toLowerCase() === "link" && rel.length > 0 + ? rel.map((declaration) => ({ + mechanism: "dom_link_rel" as const, + declaration, + url: href, + trust: "page-declared-untrusted" as const, + })) + : []; + return { urls, agentHints }; +}; + +const domDestination = ( + value: string, + documentUrl: string, + allowedOrigins: ReadonlySet, +): { + readonly url: string | null; + readonly scope: "approved" | "outside_policy" | "unsupported"; +} => { + try { + const parsed = new URL(value, documentUrl); + if (parsed.protocol !== "http:" && parsed.protocol !== "https:") + return { url: null, scope: "unsupported" }; + if (!allowedOrigins.has(parsed.origin)) + return { url: null, scope: "outside_policy" }; + return { + url: allowedSanitizedUrl(parsed.href, allowedOrigins)?.url ?? null, + scope: "approved", + }; + } catch { + return { url: null, scope: "unsupported" }; + } +}; + +const boundedUtf8 = ( + value: string, + maximumBytes: number, +): { + readonly text: string; + readonly bytes: number; + readonly truncated: boolean; +} => { + const total = Buffer.byteLength(value); + if (total <= maximumBytes) + return { text: value, bytes: total, truncated: false }; + let text = ""; + let bytes = 0; + for (const character of value) { + const characterBytes = Buffer.byteLength(character); + if (bytes + characterBytes > maximumBytes) break; + text += character; + bytes += characterBytes; + } + return { text, bytes, truncated: true }; +}; + +const exclusionReasonForUrl = ( + value: string | undefined, +): "disallowed_origin" | "unsupported_url" | "unattributed_origin" => + value === undefined || value === "" + ? "unattributed_origin" + : isHttpUrl(value) + ? "disallowed_origin" + : "unsupported_url"; + +const domUrlAttributes = [ + "href", + "src", + "action", + "formaction", + "poster", +] as const; +const agentRelValues = ["mcp", "model-context", "ai-plugin", "service-desc"]; diff --git a/src/browser/CdpCaptureEvents.ts b/src/browser/CdpCaptureEvents.ts index 2a254af03..67e45974f 100644 --- a/src/browser/CdpCaptureEvents.ts +++ b/src/browser/CdpCaptureEvents.ts @@ -2,7 +2,11 @@ import type { InspectWebPageInput, WebPageInspection, } from "../domain/browserObservation.js"; +import { inferJsonShape, type JsonShape } from "../domain/jsonShape.js"; import type { CdpEvent } from "./CdpConnection.js"; +import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js"; +import { safeResponseMetadata } from "./CdpSafeMetadata.js"; +import { boundedSensitiveText } from "./SensitiveTextCapture.js"; import { allowedSanitizedUrl, boundedText, @@ -16,6 +20,7 @@ import { export interface CapturedScript { readonly scriptId: string; + readonly rawUrl: string; readonly url: string; readonly origin: string | null; readonly hash: string; @@ -23,6 +28,7 @@ export interface CapturedScript { readonly isModule: boolean; readonly language: string | null; readonly sourceMapUrl: string | null; + readonly sourceMapRawUrl: string | null; } type NetworkState = WebPageInspection["network"]["requests"][number]; @@ -34,10 +40,21 @@ export class CdpCaptureEvents { readonly allowedWebSockets = new Set(); readonly console: WebPageInspection["console"]["events"] = []; readonly websockets: WebPageInspection["network"]["websocket_events"] = []; - dropped = 0; + readonly responseMetadata: WebPageInspection["metadata"]["responses"] = []; + readonly agentHints: WebPageInspection["metadata"]["agent_hints"] = []; + readonly completeness = new CdpCaptureCompleteness([ + "network_requests", + "console_events", + "websocket_connections", + "websocket_frames", + "metadata", + ]); originViolation = false; navigationDuringCapture = false; #mainFrameId: string | undefined; + #consoleTextBytes = 0; + #jsonBodyBytes = 0; + #websocketShapeBytes = 0; constructor( private readonly input: InspectWebPageInput, @@ -48,12 +65,23 @@ export class CdpCaptureEvents { this.#mainFrameId = frameId; this.originViolation = false; this.navigationDuringCapture = false; - this.dropped = 0; this.scripts.clear(); this.network.clear(); this.allowedWebSockets.clear(); this.console.length = 0; this.websockets.length = 0; + this.responseMetadata.length = 0; + this.agentHints.length = 0; + this.#consoleTextBytes = 0; + this.#jsonBodyBytes = 0; + this.#websocketShapeBytes = 0; + this.completeness.reset(); + if (!this.input.include_console_text) + this.completeness.exclude("console_text", "not_approved", null); + if (!this.input.include_json_body_shapes) + this.completeness.exclude("json_body_shapes", "not_approved", null); + if (!this.input.include_websocket_shapes) + this.completeness.exclude("websocket_shapes", "not_approved", null); } beginFinalCapture(frameId: string): void { @@ -99,21 +127,25 @@ export class CdpCaptureEvents { const scriptId = stringValue(params.scriptId); const rawUrl = stringValue(params.url) ?? ""; const sanitized = allowedSanitizedUrl(rawUrl, this.allowedOrigins); - if ( - scriptId === undefined || - scriptId.length > 256 || - sanitized === undefined - ) + if (scriptId === undefined || scriptId.length > 256) { + this.completeness.exclude("scripts", "invalid_protocol_value"); return; + } + if (sanitized === undefined) { + this.completeness.exclude("scripts", exclusionReasonForUrl(rawUrl)); + return; + } if ( this.scripts.size >= this.input.limits.max_scripts && !this.scripts.has(scriptId) ) { - this.dropped += 1; + this.completeness.drop("scripts"); return; } + const sourceMap = this.#sourceMap(params.sourceMapURL); this.scripts.set(scriptId, { scriptId, + rawUrl, url: sanitized.url, origin: sanitized.origin, hash: (stringValue(params.hash) ?? "").slice(0, 512), @@ -126,21 +158,43 @@ export class CdpCaptureEvents { ), isModule: params.isModule === true, language: boundedText(params.scriptLanguage, 100), - sourceMapUrl: this.#sourceMap(params.sourceMapURL), + sourceMapUrl: sourceMap.sanitized, + sourceMapRawUrl: sourceMap.raw, }); } - #sourceMap(value: unknown): string | null { - const sanitized = allowedSanitizedUrl(value, this.allowedOrigins); - return sanitized?.url ?? null; + #sourceMap(value: unknown): { + readonly sanitized: string | null; + readonly raw: string | null; + } { + const rawUrl = stringValue(value); + if (rawUrl === undefined || rawUrl === "") + return { sanitized: null, raw: null }; + const sanitized = allowedSanitizedUrl(rawUrl, this.allowedOrigins); + if (sanitized !== undefined) + return { sanitized: sanitized.url, raw: rawUrl }; + this.completeness.exclude("source_maps", exclusionReasonForUrl(rawUrl)); + return { sanitized: null, raw: null }; } #request(params: UnknownRecord): void { const requestId = stringValue(params.requestId); const request = recordValue(params.request); - const sanitized = allowedSanitizedUrl(request?.url, this.allowedOrigins); - if (requestId === undefined || requestId.length > 256) return; - if (request === undefined || sanitized === undefined) { + if (requestId === undefined || requestId.length > 256) { + this.completeness.exclude("network_requests", "invalid_protocol_value"); + return; + } + if (request === undefined) { + this.completeness.exclude("network_requests", "invalid_protocol_value"); + this.network.delete(requestId); + return; + } + const sanitized = allowedSanitizedUrl(request.url, this.allowedOrigins); + if (sanitized === undefined) { + this.completeness.exclude( + "network_requests", + exclusionReasonForUrl(stringValue(request.url)), + ); this.network.delete(requestId); return; } @@ -148,14 +202,21 @@ export class CdpCaptureEvents { this.network.size >= this.input.limits.max_network_events && !this.network.has(requestId) ) { - this.dropped += 1; + this.completeness.drop("network_requests"); return; } const initiator = recordValue(params.initiator); + const initiatorFrame = initiatorLocation(initiator); + const rawInitiatorUrl = stringValue(initiatorFrame?.url); const initiatorUrl = allowedSanitizedUrl( - firstCallFrame(initiator)?.url, + rawInitiatorUrl, this.allowedOrigins, ); + if (rawInitiatorUrl !== undefined && initiatorUrl === undefined) + this.completeness.exclude( + "network_initiators", + exclusionReasonForUrl(rawInitiatorUrl), + ); this.network.set(requestId, { request_id: requestId, url: sanitized.url, @@ -168,20 +229,30 @@ export class CdpCaptureEvents { initiator: { type: (stringValue(initiator?.type) ?? "other").slice(0, 100), url: initiatorUrl?.url ?? null, - line: integerOrNull(firstCallFrame(initiator)?.lineNumber), - column: integerOrNull(firstCallFrame(initiator)?.columnNumber), + line: integerOrNull(initiatorFrame?.lineNumber), + column: integerOrNull(initiatorFrame?.columnNumber), }, + body_shapes: this.#requestBodyShape(request), }); } #response(params: UnknownRecord): void { const requestId = stringValue(params.requestId); - if (requestId === undefined || requestId.length > 256) return; + if (requestId === undefined || requestId.length > 256) { + this.completeness.exclude("network_requests", "invalid_protocol_value"); + return; + } const current = this.network.get(requestId); const response = recordValue(params.response); - const sanitized = allowedSanitizedUrl(response?.url, this.allowedOrigins); if (current === undefined) return; + const sanitized = allowedSanitizedUrl(response?.url, this.allowedOrigins); if (response === undefined || sanitized === undefined) { + this.completeness.exclude( + "network_requests", + response === undefined + ? "invalid_protocol_value" + : exclusionReasonForUrl(stringValue(response.url)), + ); this.network.delete(requestId); return; } @@ -190,6 +261,18 @@ export class CdpCaptureEvents { status: numberValue(response.status) ?? null, mime_type: boundedText(response.mimeType, 256), }); + if (this.responseMetadata.length >= this.input.limits.max_network_events) { + this.completeness.truncate("metadata"); + return; + } + const metadata = safeResponseMetadata( + requestId, + sanitized.url, + response, + this.allowedOrigins, + ); + this.responseMetadata.push(metadata.response); + this.agentHints.push(...metadata.agentHints); } #finished(params: UnknownRecord): void { @@ -208,23 +291,35 @@ export class CdpCaptureEvents { #console(params: UnknownRecord): void { const frame = firstCallFrame(recordValue(params.stackTrace)); - const source = allowedSanitizedUrl(frame?.url, this.allowedOrigins); - if (frame === undefined || source === undefined) return; - if (this.console.length >= this.input.limits.max_console_events) { - this.dropped += 1; + if (frame === undefined) { + this.completeness.exclude("console_events", "unattributed_origin"); return; } + const source = allowedSanitizedUrl(frame.url, this.allowedOrigins); + if (source === undefined) { + this.completeness.exclude( + "console_events", + exclusionReasonForUrl(stringValue(frame.url)), + ); + return; + } + if (this.console.length >= this.input.limits.max_console_events) { + this.completeness.drop("console_events"); + return; + } + const arguments_ = recordsValue(params.args); this.console.push({ type: (stringValue(params.type) ?? "unknown").slice(0, 100), timestamp: numberValue(params.timestamp) ?? 0, - argument_types: recordsValue(params.args) + argument_types: arguments_ .map((argument) => (stringValue(argument.type) ?? "unknown").slice(0, 100), ) .slice(0, 100), - url: source?.url ?? null, - line: integerOrNull(frame?.lineNumber), - column: integerOrNull(frame?.columnNumber), + url: source.url, + line: integerOrNull(frame.lineNumber), + column: integerOrNull(frame.columnNumber), + text_capture: this.#consoleText(arguments_), }); } @@ -237,48 +332,243 @@ export class CdpCaptureEvents { ) return; if (this.websockets.length >= this.input.limits.max_websocket_events) { - this.dropped += 1; + this.completeness.drop("websocket_frames"); return; } const response = recordValue(params.response); const payload = stringValue(response?.payloadData) ?? ""; const opcode = Math.max(0, Math.trunc(numberValue(response?.opcode) ?? 0)); + const decoded = opcode === 1 ? undefined : decodeBase64(payload); + if (opcode !== 1 && decoded === undefined) + this.completeness.exclude("websocket_frames", "invalid_protocol_value"); this.websockets.push({ request_id: requestId, direction, opcode, payload_bytes: - opcode === 1 - ? Buffer.byteLength(payload) - : Buffer.from(payload, "base64").byteLength, + opcode === 1 ? Buffer.byteLength(payload) : (decoded?.byteLength ?? 0), + payload_shape: this.#websocketShape(payload, opcode), }); } + responseBodyRequestIds(): readonly string[] { + if (!this.input.include_json_body_shapes) return []; + return [...this.network.values()] + .filter((request) => isJsonMediaType(request.mime_type)) + .map((request) => request.request_id); + } + + responseBodyUnavailable(requestId: string): void { + this.#updateResponseShape(requestId, null, false); + this.completeness.unavailable("json_body_shapes"); + } + + ingestResponseBody(requestId: string, value: unknown): void { + const result = recordValue(value); + const body = stringValue(result?.body); + if (body === undefined) { + this.#invalidResponseBody(requestId); + return; + } + const decoded = + result?.base64Encoded === true + ? decodeBase64(body)?.toString("utf8") + : body; + if (decoded === undefined) { + this.#invalidResponseBody(requestId); + return; + } + const inferred = this.#inferBodyShape(decoded); + this.#updateResponseShape(requestId, inferred.shape, inferred.truncated); + } + + #invalidResponseBody(requestId: string): void { + this.#updateResponseShape(requestId, null, false); + this.completeness.exclude("json_body_shapes", "invalid_protocol_value"); + } + + #requestBodyShape(request: UnknownRecord): NetworkState["body_shapes"] { + if (!this.input.include_json_body_shapes) + return { status: "not_approved", request: null, response: null }; + const body = stringValue(request.postData); + if (!isJsonContentType(recordValue(request.headers)) || body === undefined) + return { status: "unavailable", request: null, response: null }; + const inferred = this.#inferBodyShape(body); + return { + status: inferred.truncated + ? "truncated" + : inferred.shape === null + ? "unavailable" + : "included", + request: inferred.shape, + response: null, + }; + } + + #inferBodyShape(text: string): { + readonly shape: JsonShape | null; + readonly truncated: boolean; + } { + const bytes = Buffer.byteLength(text); + const remaining = + this.input.limits.max_total_json_body_bytes - this.#jsonBodyBytes; + if (bytes > this.input.limits.max_json_body_bytes || bytes > remaining) { + this.completeness.truncate("json_body_shapes"); + return { shape: null, truncated: true }; + } + this.#jsonBodyBytes += bytes; + const shape = inferJsonShape(text, { + maximumBytes: this.input.limits.max_json_body_bytes, + maximumNodes: this.input.limits.max_json_shape_nodes, + maximumDepth: this.input.limits.max_json_shape_depth, + }); + if (shape?.truncated === true) + this.completeness.truncate("json_body_shapes"); + return { shape, truncated: shape?.truncated === true }; + } + + #updateResponseShape( + requestId: string, + response: JsonShape | null, + truncated: boolean, + ): void { + const current = this.network.get(requestId); + if (current === undefined) return; + const request = current.body_shapes.request; + const status = + truncated || current.body_shapes.status === "truncated" + ? "truncated" + : response !== null + ? "included" + : request !== null + ? "partial" + : "unavailable"; + this.network.set(requestId, { + ...current, + body_shapes: { status, request, response }, + }); + } + + #consoleText( + arguments_: readonly UnknownRecord[], + ): WebPageInspection["console"]["events"][number]["text_capture"] { + if (!this.input.include_console_text) + return { + status: "not_approved", + values: [], + retained_bytes: 0, + truncated_values: 0, + }; + const values: WebPageInspection["console"]["events"][number]["text_capture"]["values"] = + []; + let retainedBytes = 0; + let truncatedValues = 0; + for (const [argumentIndex, argument] of arguments_.entries()) { + const primitive = consolePrimitive(argument); + if (primitive === undefined) continue; + const remaining = + this.input.limits.max_total_console_text_bytes - this.#consoleTextBytes; + if (remaining <= 0) { + truncatedValues += 1; + continue; + } + const bounded = boundedSensitiveText( + primitive.text, + Math.min(this.input.limits.max_console_text_field_bytes, remaining), + ); + values.push({ + argument_index: argumentIndex, + type: primitive.type, + text: bounded.text, + }); + retainedBytes += bounded.bytes; + this.#consoleTextBytes += bounded.bytes; + if (bounded.truncated) truncatedValues += 1; + } + if (truncatedValues > 0) this.completeness.truncate("console_text"); + return { + status: truncatedValues > 0 ? "truncated" : "included", + values, + retained_bytes: retainedBytes, + truncated_values: truncatedValues, + }; + } + + #websocketShape( + payload: string, + opcode: number, + ): WebPageInspection["network"]["websocket_events"][number]["payload_shape"] { + if (!this.input.include_websocket_shapes) return null; + if (opcode !== 1) + return { format: "binary", json_shape: null, truncated: false }; + const bytes = Buffer.byteLength(payload); + const remaining = + this.input.limits.max_total_websocket_shape_bytes - + this.#websocketShapeBytes; + if ( + bytes > this.input.limits.max_websocket_shape_bytes || + bytes > remaining + ) { + this.completeness.truncate("websocket_shapes"); + return { format: "text", json_shape: null, truncated: true }; + } + this.#websocketShapeBytes += bytes; + const shape = inferJsonShape(payload, { + maximumBytes: this.input.limits.max_websocket_shape_bytes, + maximumNodes: this.input.limits.max_json_shape_nodes, + maximumDepth: this.input.limits.max_json_shape_depth, + }); + if (shape?.truncated === true) + this.completeness.truncate("websocket_shapes"); + return { + format: shape === null ? "text" : "json", + json_shape: shape, + truncated: shape?.truncated === true, + }; + } + #websocketCreated(params: UnknownRecord): void { const requestId = stringValue(params.requestId); const rawUrl = stringValue(params.url); - if ( - requestId === undefined || - requestId.length > 256 || - rawUrl === undefined - ) + if (requestId === undefined || requestId.length > 256) { + this.completeness.exclude( + "websocket_connections", + "invalid_protocol_value", + ); return; + } + if (rawUrl === undefined) { + this.completeness.exclude( + "websocket_connections", + "invalid_protocol_value", + ); + return; + } let parsed: URL; try { parsed = new URL(rawUrl); } catch { + this.completeness.exclude("websocket_connections", "unsupported_url"); return; } if (parsed.protocol === "ws:") parsed.protocol = "http:"; else if (parsed.protocol === "wss:") parsed.protocol = "https:"; - else return; + else { + this.completeness.exclude("websocket_connections", "unsupported_url"); + return; + } + if (!this.allowedOrigins.has(parsed.origin)) { + this.completeness.exclude("websocket_connections", "disallowed_origin"); + return; + } if ( - this.allowedOrigins.has(parsed.origin) && - (this.allowedWebSockets.has(requestId) || - this.allowedWebSockets.size < this.input.limits.max_websocket_events) - ) - this.allowedWebSockets.add(requestId); - else if (this.allowedOrigins.has(parsed.origin)) this.dropped += 1; + !this.allowedWebSockets.has(requestId) && + this.allowedWebSockets.size >= this.input.limits.max_websocket_events + ) { + this.completeness.drop("websocket_connections"); + return; + } + this.allowedWebSockets.add(requestId); } #frameNavigated(params: UnknownRecord): void { @@ -296,12 +586,85 @@ export class CdpCaptureEvents { const firstCallFrame = ( value: UnknownRecord | undefined, +): UnknownRecord | undefined => recordsValue(value?.callFrames)[0]; + +const initiatorLocation = ( + initiator: UnknownRecord | undefined, ): UnknownRecord | undefined => { - const callFrames = recordsValue(value?.callFrames); - return callFrames[0]; + let stack = recordValue(initiator?.stack); + for (let depth = 0; depth < 32 && stack !== undefined; depth += 1) { + const frame = firstCallFrame(stack); + if (frame !== undefined) return frame; + stack = recordValue(stack.parent); + } + return stringValue(initiator?.url) === undefined ? undefined : initiator; }; +const exclusionReasonForUrl = ( + value: string | undefined, +): "disallowed_origin" | "unsupported_url" | "unattributed_origin" => + value === undefined || value === "" + ? "unattributed_origin" + : isHttpUrl(value) + ? "disallowed_origin" + : "unsupported_url"; + const integerOrNull = (value: unknown): number | null => { const number = numberValue(value); return number === undefined ? null : Math.max(0, Math.trunc(number)); }; + +const isJsonContentType = (headers: UnknownRecord | undefined): boolean => { + if (headers === undefined) return false; + for (const [name, value] of Object.entries(headers)) + if ( + name.toLowerCase() === "content-type" && + isJsonMediaType(stringValue(value)) + ) + return true; + return false; +}; + +const isJsonMediaType = (value: string | null | undefined): boolean => { + const mediaType = value?.split(";", 1)[0]?.trim().toLowerCase(); + return ( + mediaType === "application/json" || mediaType?.endsWith("+json") === true + ); +}; + +const consolePrimitive = ( + value: UnknownRecord, +): { readonly type: string; readonly text: string } | undefined => { + const type = stringValue(value.type); + switch (type) { + case "string": + return typeof value.value === "string" + ? { type, text: value.value } + : undefined; + case "boolean": + return typeof value.value === "boolean" + ? { type, text: String(value.value) } + : undefined; + case "number": + return typeof value.value === "number" + ? { type, text: String(value.value) } + : typeof value.unserializableValue === "string" + ? { type, text: value.unserializableValue } + : undefined; + case "bigint": + return typeof value.unserializableValue === "string" + ? { type, text: value.unserializableValue } + : undefined; + case "undefined": + return { type, text: "undefined" }; + default: + return undefined; + } +}; + +const BASE64 = /^(?:[A-Za-z\d+/]{4})*(?:[A-Za-z\d+/]{2}==|[A-Za-z\d+/]{3}=)?$/u; + +const decodeBase64 = (value: string): Buffer | undefined => + value.length % 4 === 0 && BASE64.test(value) + ? Buffer.from(value, "base64") + : undefined; diff --git a/src/browser/CdpCaptureValues.ts b/src/browser/CdpCaptureValues.ts index 439786cff..ffa601fc8 100644 --- a/src/browser/CdpCaptureValues.ts +++ b/src/browser/CdpCaptureValues.ts @@ -1,10 +1,9 @@ -import { createHash } from "node:crypto"; - import { AnalysisCancelledError, BrowserObservationError, } from "../domain/errors.js"; import { sanitizeBrowserUrl } from "../domain/browserObservation.js"; +import { createWebTextArtifact } from "../domain/webContentArtifact.js"; export type UnknownRecord = Readonly>; @@ -64,11 +63,9 @@ export const allowedSanitizedUrl = ( export const sourceResult = ( source: string, -): { included: true; sha256: string; bytes: number; content: string } => ({ +): { included: true; artifact: ReturnType } => ({ included: true, - sha256: createHash("sha256").update(source).digest("hex"), - bytes: Buffer.byteLength(source), - content: source, + artifact: createWebTextArtifact(source, "text/javascript"), }); export const sourceExcluded = ( diff --git a/src/browser/CdpElectronInspection.ts b/src/browser/CdpElectronInspection.ts new file mode 100644 index 000000000..9aa0e7172 --- /dev/null +++ b/src/browser/CdpElectronInspection.ts @@ -0,0 +1,481 @@ +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; + 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 => { + 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, 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 => { + 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 => { + 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(); + 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 => { + 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 => { + let total = 0; + let sourceBytes = 0; + const items: ElectronPageInspection["scripts"]["items"] = []; + const seen = new Set(); + 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 => { + 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 => + await progress?.report({ + phase: "browser_observation", + completed, + total: 3, + message, + ...(completed === 3 ? { terminal: true } : {}), + }); diff --git a/src/browser/CdpElectronProvider.ts b/src/browser/CdpElectronProvider.ts new file mode 100644 index 000000000..d779ca5b5 --- /dev/null +++ b/src/browser/CdpElectronProvider.ts @@ -0,0 +1,223 @@ +import type { + ExecutionOptions, + ProviderIdentity, +} from "../application/AnalysisProvider.js"; +import type { ElectronObservationPort } from "../application/ElectronObservationPort.js"; +import { + electronPageInspectionSchema, + electronTargetListSchema, + type ElectronPageInspection, + type ElectronTargetList, + type InspectElectronPageInput, + type ListElectronTargetsInput, +} from "../domain/electronObservation.js"; +import { + AnalysisError, + BrowserObservationError, + ProviderAdapterError, + type BrowserObservationOperation, +} from "../domain/errors.js"; +import { err, ok, type Result } from "../domain/result.js"; +import { CdpConnection } from "./CdpConnection.js"; +import { discoverCdpEndpoint, type CdpEndpointTarget } from "./CdpEndpoint.js"; +import { inspectCdpElectronPage } from "./CdpElectronInspection.js"; +import { + authorizedElectronFile, + canonicalElectronRoots, +} from "./ElectronFileScope.js"; + +const IDENTITY: ProviderIdentity = { + id: "rea-cdp-electron", + name: "REA Electron file-page CDP observation provider", + version: "1", +}; + +/** Passive Electron provider with canonical file-root confinement. */ +export class CdpElectronProvider implements ElectronObservationPort { + identity(): ProviderIdentity { + return IDENTITY; + } + + async listTargets( + input: ListElectronTargetsInput, + options: ExecutionOptions = {}, + ): Promise> { + try { + const roots = await canonicalElectronRoots(input.allowed_file_roots); + const discovery = await discoverCdpEndpoint( + input.cdp_endpoint, + "list_browser_targets", + options.signal, + ); + const allowed = []; + let outsideRoot = 0; + let unsupportedUrl = 0; + let nonPage = 0; + for (const target of discovery.targets) { + if (target.type !== "page") { + nonPage += 1; + continue; + } + const path = await authorizedElectronFile(target.url, roots); + if (path === undefined) { + if (isFileUrl(target.url)) outsideRoot += 1; + else unsupportedUrl += 1; + continue; + } + allowed.push({ + target_id: target.id, + type: target.type, + title: target.title.slice(0, 16_384), + file_path: path, + attached: target.attached, + }); + } + allowed.sort((left, right) => + left.target_id.localeCompare(right.target_id), + ); + const items = allowed.slice(input.offset, input.offset + input.limit); + const next = input.offset + items.length; + return ok( + electronTargetListSchema.parse({ + schema_version: 1, + browser: discovery.version, + targets: { + items, + offset: input.offset, + limit: input.limit, + total: allowed.length, + next_offset: next < allowed.length ? next : null, + has_more: next < allowed.length, + }, + excluded: { + outside_root: outsideRoot, + unsupported_url: unsupportedUrl, + non_page: nonPage, + }, + limitations: [ + "Only page targets whose canonical file path is contained by an approved root are listed.", + ], + }), + ); + } catch (cause: unknown) { + return err(providerError(cause, "list_electron_targets")); + } + } + + async inspectPage( + input: InspectElectronPageInput, + options: ExecutionOptions = {}, + ): Promise> { + let connection: CdpConnection | undefined; + let sessionId: string | undefined; + try { + const roots = await canonicalElectronRoots(input.allowed_file_roots); + const discovery = await discoverCdpEndpoint( + input.cdp_endpoint, + "inspect_web_page", + options.signal, + ); + const target = await authorizeTarget( + discovery.targets, + input.target_id, + roots, + ); + connection = await CdpConnection.connect( + discovery.browserWebSocketUrl, + options.signal, + ); + const attached = await connection.send( + "Target.attachToTarget", + { targetId: target.id, flatten: true }, + undefined, + options.signal, + ); + sessionId = attachedSessionId(attached); + return ok( + electronPageInspectionSchema.parse( + await inspectCdpElectronPage({ + connection, + sessionId, + discovery, + target, + input, + ...(options.signal === undefined ? {} : { signal: options.signal }), + ...(options.progress === undefined + ? {} + : { progress: options.progress }), + }), + ), + ); + } catch (cause: unknown) { + return err(providerError(cause, "inspect_electron_page")); + } finally { + if (connection !== undefined) { + if (sessionId !== undefined) await cleanup(connection, sessionId); + await connection.close(); + } + } + } +} + +const authorizeTarget = async ( + targets: readonly CdpEndpointTarget[], + targetId: string, + roots: readonly string[], +): Promise => { + const target = targets.find(({ id }) => id === targetId); + if (target === undefined) + throw new BrowserObservationError("inspect_web_page", "target_not_found"); + if ( + target.type !== "page" || + (await authorizedElectronFile(target.url, roots)) === undefined + ) + throw new BrowserObservationError("inspect_web_page", "target_not_allowed"); + return target; +}; + +const attachedSessionId = (value: unknown): string => { + if ( + typeof value !== "object" || + value === null || + !("sessionId" in value) || + typeof value.sessionId !== "string" || + value.sessionId.length > 256 + ) + throw new BrowserObservationError("inspect_web_page", "protocol_error"); + return value.sessionId; +}; + +const cleanup = async ( + connection: CdpConnection, + sessionId: string, +): Promise => { + for (const method of ["Debugger.disable", "Page.disable"]) + try { + await connection.send(method, {}, sessionId); + } catch { + // Detach remains the final non-destructive cleanup boundary. + } + try { + await connection.send("Target.detachFromTarget", { sessionId }); + } catch { + // Closing REA's socket never closes the Electron target. + } +}; + +const isFileUrl = (value: string): boolean => { + try { + return new URL(value).protocol === "file:"; + } catch { + return false; + } +}; + +const providerError = ( + cause: unknown, + operation: BrowserObservationOperation, +): AnalysisError => + cause instanceof BrowserObservationError && cause.operation !== operation + ? new BrowserObservationError(operation, cause.reason, { cause }) + : cause instanceof AnalysisError + ? cause + : new ProviderAdapterError(IDENTITY.id, operation, { cause }); diff --git a/src/browser/CdpEndpoint.ts b/src/browser/CdpEndpoint.ts index d63a5e32b..b09c9d1ca 100644 --- a/src/browser/CdpEndpoint.ts +++ b/src/browser/CdpEndpoint.ts @@ -7,6 +7,7 @@ import { AnalysisError, AnalysisTimeoutError, BrowserObservationError, + type BrowserObservationOperation, } from "../domain/errors.js"; const HTTP_TIMEOUT_MS = 5_000; @@ -45,12 +46,10 @@ export interface CdpEndpointDiscovery { readonly targets: readonly CdpEndpointTarget[]; } -type BrowserOperation = "list_browser_targets" | "inspect_web_page"; - /** Read bounded CDP discovery endpoints without following redirects. */ export const discoverCdpEndpoint = async ( endpoint: string, - operation: BrowserOperation, + operation: BrowserObservationOperation, signal?: AbortSignal, ): Promise => { const versionInput = await readJson( @@ -95,7 +94,7 @@ export const discoverCdpEndpoint = async ( const parseEndpointValue = ( schema: z.ZodType, input: unknown, - operation: BrowserOperation, + operation: BrowserObservationOperation, ): Output => { const parsed = schema.safeParse(input); if (!parsed.success) @@ -108,7 +107,7 @@ const parseEndpointValue = ( const safeBrowserWebSocketUrl = ( endpoint: string, reported: string, - operation: BrowserOperation, + operation: BrowserObservationOperation, ): string => { let parsed: URL; try { @@ -136,7 +135,7 @@ const safeBrowserWebSocketUrl = ( const readJson = async ( url: URL, maximumBytes: number, - operation: BrowserOperation, + operation: BrowserObservationOperation, signal?: AbortSignal, ): Promise => await new Promise((resolve, reject) => { @@ -196,7 +195,7 @@ const readJson = async ( const endpointFailure = ( cause: unknown, - operation: BrowserOperation, + operation: BrowserObservationOperation, signal?: AbortSignal, ): AnalysisError => { if (cause instanceof AnalysisError) return cause; diff --git a/src/browser/CdpObservationSession.ts b/src/browser/CdpObservationSession.ts new file mode 100644 index 000000000..2016f651d --- /dev/null +++ b/src/browser/CdpObservationSession.ts @@ -0,0 +1,416 @@ +import type { ProgressReporter } from "../application/ProgressReporter.js"; +import type { + ObserveWebSessionInput, + WebObservationSession, +} from "../domain/browserSession.js"; +import { BrowserObservationError } from "../domain/errors.js"; +import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js"; +import { CdpConnection, type CdpEvent } from "./CdpConnection.js"; +import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js"; +import { + allowedSanitizedUrl, + delayWithCancellation, + isHttpUrl, + numberValue, + recordValue, + stringValue, + type UnknownRecord, +} from "./CdpCaptureValues.js"; +import { mainFrameUrl } from "./CdpCaptureDocuments.js"; + +interface ObservationContext { + readonly connection: CdpConnection; + readonly sessionId: string; + readonly discovery: CdpEndpointDiscovery; + readonly target: CdpEndpointTarget; + readonly input: ObserveWebSessionInput; + readonly signal?: AbortSignal; + readonly progress?: ProgressReporter; +} + +type EndReason = WebObservationSession["window"]["end_reason"]; +type TimelineEvent = WebObservationSession["timeline"][number]; + +/** Observe external user actions without rejecting approved same-origin navigation. */ +export const observeCdpSession = async ( + context: ObservationContext, +): Promise => { + const allowedOrigins = new Set(context.input.allowed_origins); + const initial = await authorizedFrame(context, allowedOrigins); + const initialUrl = mainFrameUrl(initial) ?? ""; + const mainFrameId = frameId(initial); + if (mainFrameId === undefined) + throw new BrowserObservationError("inspect_web_page", "protocol_error"); + const capture = new TimelineCapture( + context.input.max_timeline_events, + allowedOrigins, + mainFrameId, + initialUrl, + ); + const removeListener = context.connection.onEvent((event) => { + if (event.sessionId === context.sessionId) capture.ingest(event); + }); + try { + await context.connection.send( + "Page.enable", + {}, + context.sessionId, + context.signal, + ); + await context.connection.send( + "Network.enable", + { maxTotalBufferSize: 1_024 * 1_024 }, + context.sessionId, + context.signal, + ); + await context.connection.send( + "Page.setLifecycleEventsEnabled", + { enabled: true }, + context.sessionId, + context.signal, + ); + const armedAt = new Date().toISOString(); + await context.progress?.report({ + phase: "browser_observation", + completed: 1, + total: 2, + message: + "Browser observation armed; perform the approved user action now", + }); + let endReason = await waitForWindow( + context.input.observation_ms, + capture, + context.signal, + ); + if (endReason === "window_elapsed") + endReason = await captureFinalUrl(context, capture, allowedOrigins); + await context.progress?.report({ + phase: "browser_observation", + completed: 2, + total: 2, + message: "Browser observation window ended", + terminal: true, + }); + return { + schema_version: 1, + browser: context.discovery.version, + target: { + target_id: context.target.id, + initial_url: allowedSanitizedUrl(initialUrl, allowedOrigins)?.url ?? "", + final_url: capture.finalUrl, + }, + window: { + armed_at: armedAt, + ended_at: new Date().toISOString(), + requested_ms: context.input.observation_ms, + end_reason: endReason, + }, + timeline: capture.timeline, + completeness: capture.completeness.snapshot(), + limitations: [ + "The timeline begins after REA attaches; earlier navigation and network activity is unavailable.", + "Only navigation metadata is retained; headers, bodies, cookies, console values, and payloads are not captured by this tool.", + "An out-of-policy destination ends collection immediately and is recorded without its URL.", + ], + }; + } finally { + removeListener(); + } +}; + +class TimelineCapture { + readonly timeline: TimelineEvent[] = []; + readonly completeness = new CdpCaptureCompleteness(["timeline"]); + finalUrl: string | null; + #sequence = 0; + #pendingReload = false; + #endReason: EndReason | undefined; + readonly #listeners = new Set<(reason: EndReason) => void>(); + + constructor( + private readonly maximum: number, + private readonly allowedOrigins: ReadonlySet, + private readonly mainFrameId: string, + initialUrl: string, + ) { + this.finalUrl = + allowedSanitizedUrl(initialUrl, allowedOrigins)?.url ?? null; + } + + ingest(event: CdpEvent): void { + if (this.#endReason !== undefined) return; + const params = recordValue(event.params); + if (params === undefined) return; + switch (event.method) { + case "Page.frameRequestedNavigation": + this.#navigationRequested(params); + break; + case "Page.frameNavigated": + this.#navigationCommitted(params); + break; + case "Page.navigatedWithinDocument": + this.#sameDocument(params); + break; + case "Network.requestWillBeSent": + this.#redirect(params); + break; + case "Network.loadingFailed": + this.#loadingFailed(params); + break; + case "Page.lifecycleEvent": + this.#lifecycle(params); + break; + case "Inspector.targetCrashed": + case "Target.detachedFromTarget": + this.#add("target_terminated", params, null, null, "target_terminated"); + this.end("target_terminated"); + break; + } + } + + onEnd(listener: (reason: EndReason) => void): () => void { + if (this.#endReason !== undefined) listener(this.#endReason); + else this.#listeners.add(listener); + return () => this.#listeners.delete(listener); + } + + end(reason: EndReason): void { + if (this.#endReason !== undefined) return; + this.#endReason = reason; + for (const listener of this.#listeners) listener(reason); + this.#listeners.clear(); + } + + setFinalUrl(rawUrl: string): void { + const destination = scopedUrl(rawUrl, this.allowedOrigins); + this.finalUrl = destination.scope === "approved" ? destination.url : null; + } + + #navigationRequested(params: UnknownRecord): void { + if (stringValue(params.frameId) !== this.mainFrameId) return; + const reason = safeDetail(params.reason); + this.#pendingReload = reason === "reload"; + this.#add( + "navigation_requested", + params, + stringValue(params.url), + null, + reason, + ); + } + + #navigationCommitted(params: UnknownRecord): void { + const frame = recordValue(params.frame); + if (stringValue(frame?.id) !== this.mainFrameId) return; + const rawUrl = stringValue(frame?.url); + const destination = scopedUrl(rawUrl, this.allowedOrigins); + this.#add( + this.#pendingReload ? "same_origin_reload" : "navigation_committed", + { ...params, frameId: frame?.id, loaderId: frame?.loaderId }, + rawUrl, + null, + safeDetail(frame?.transitionType), + ); + this.#pendingReload = false; + if (destination.scope === "approved") this.finalUrl = destination.url; + else { + this.finalUrl = null; + this.completeness.exclude("timeline", "out_of_target_scope"); + this.end("target_left_scope"); + } + } + + #sameDocument(params: UnknownRecord): void { + if (stringValue(params.frameId) !== this.mainFrameId) return; + const rawUrl = stringValue(params.url); + const destination = scopedUrl(rawUrl, this.allowedOrigins); + this.#add("same_document_navigation", params, rawUrl, null, null); + if (destination.scope === "approved") this.finalUrl = destination.url; + else { + this.finalUrl = null; + this.completeness.exclude("timeline", "out_of_target_scope"); + this.end("target_left_scope"); + } + } + + #redirect(params: UnknownRecord): void { + if ( + stringValue(params.frameId) !== this.mainFrameId || + recordValue(params.redirectResponse) === undefined + ) + return; + const request = recordValue(params.request); + const rawUrl = stringValue(request?.url); + const destination = scopedUrl(rawUrl, this.allowedOrigins); + this.#add( + "redirect", + params, + rawUrl, + stringValue(params.requestId) ?? null, + null, + ); + if (destination.scope !== "approved") { + this.completeness.exclude("timeline", "out_of_target_scope"); + this.end("target_left_scope"); + } + } + + #loadingFailed(params: UnknownRecord): void { + const frame = stringValue(params.frameId); + if (frame !== undefined && frame !== this.mainFrameId) return; + this.#add( + "load_failed", + params, + null, + stringValue(params.requestId) ?? null, + safeNetworkError(params.errorText), + ); + } + + #lifecycle(params: UnknownRecord): void { + if (stringValue(params.frameId) !== this.mainFrameId) return; + this.#add("lifecycle", params, null, null, safeDetail(params.name)); + } + + #add( + type: TimelineEvent["type"], + params: UnknownRecord, + rawUrl: string | null | undefined, + requestId: string | null, + detail: string | null, + ): void { + const destination = + rawUrl == null ? null : scopedUrl(rawUrl, this.allowedOrigins); + if (this.timeline.length >= this.maximum) { + this.completeness.drop("timeline_events"); + return; + } + this.#sequence += 1; + this.timeline.push({ + sequence: this.#sequence, + type, + timestamp: Math.max(0, numberValue(params.timestamp) ?? 0), + frame_id: boundedId(params.frameId), + loader_id: boundedId(params.loaderId), + request_id: requestId?.slice(0, 256) ?? null, + url: destination?.scope === "approved" ? destination.url : null, + destination_scope: destination?.scope ?? null, + detail, + }); + } +} + +const waitForWindow = async ( + durationMs: number, + capture: TimelineCapture, + signal?: AbortSignal, +): Promise => + await new Promise((resolve, reject) => { + let settled = false; + let removeEnd = (): void => {}; + const finish = (reason: EndReason): void => { + if (settled) return; + settled = true; + clearTimeout(timer); + signal?.removeEventListener("abort", onAbort); + removeEnd(); + resolve(reason); + }; + const onAbort = (): void => { + if (settled) return; + settled = true; + clearTimeout(timer); + removeEnd(); + reject(signal?.reason ?? new Error("browser observation cancelled")); + }; + const timer = setTimeout(() => finish("window_elapsed"), durationMs); + removeEnd = capture.onEnd(finish); + signal?.addEventListener("abort", onAbort, { once: true }); + if (signal?.aborted === true) onAbort(); + }); + +const authorizedFrame = async ( + context: ObservationContext, + allowedOrigins: ReadonlySet, +): Promise => { + for (let attempt = 0; attempt < 80; attempt += 1) { + const result = await context.connection.send( + "Page.getFrameTree", + {}, + context.sessionId, + context.signal, + ); + const url = mainFrameUrl(result); + if (allowedSanitizedUrl(url, allowedOrigins) !== undefined) return result; + if (isHttpUrl(url)) + throw new BrowserObservationError( + "inspect_web_page", + "target_not_allowed", + ); + await delayWithCancellation(25, context.signal); + } + throw new BrowserObservationError("inspect_web_page", "target_not_allowed"); +}; + +const captureFinalUrl = async ( + context: ObservationContext, + capture: TimelineCapture, + allowedOrigins: ReadonlySet, +): Promise => { + const result = await context.connection.send( + "Page.getFrameTree", + {}, + context.sessionId, + context.signal, + ); + const url = mainFrameUrl(result); + if ( + url !== undefined && + allowedSanitizedUrl(url, allowedOrigins) !== undefined + ) { + capture.setFinalUrl(url); + return "window_elapsed"; + } + capture.finalUrl = null; + capture.completeness.exclude( + "timeline", + url === undefined ? "invalid_protocol_value" : "out_of_target_scope", + ); + return "target_left_scope"; +}; + +const frameId = (result: unknown): string | undefined => + stringValue( + recordValue(recordValue(recordValue(result)?.frameTree)?.frame)?.id, + ); + +const scopedUrl = ( + value: string | undefined, + allowedOrigins: ReadonlySet, +): { + readonly url: string | null; + readonly scope: "approved" | "outside_policy" | "unsupported"; +} => { + const allowed = allowedSanitizedUrl(value, allowedOrigins); + if (allowed !== undefined) return { url: allowed.url, scope: "approved" }; + return isHttpUrl(value) + ? { url: null, scope: "outside_policy" } + : { url: null, scope: "unsupported" }; +}; + +const boundedId = (value: unknown): string | null => + stringValue(value)?.slice(0, 256) ?? null; + +const safeDetail = (value: unknown): string | null => { + const detail = stringValue(value)?.toLowerCase(); + return detail !== undefined && /^[a-z0-9_.:-]{1,100}$/u.test(detail) + ? detail + : null; +}; + +const safeNetworkError = (value: unknown): string | null => { + const error = stringValue(value); + return error !== undefined && /^net::ERR_[A-Z0-9_]{1,100}$/u.test(error) + ? error + : null; +}; diff --git a/src/browser/CdpPageCapture.ts b/src/browser/CdpPageCapture.ts index 5fdaba4b6..45418e704 100644 --- a/src/browser/CdpPageCapture.ts +++ b/src/browser/CdpPageCapture.ts @@ -4,6 +4,11 @@ import type { } from "../domain/browserObservation.js"; import type { ProgressReporter } from "../application/ProgressReporter.js"; import { BrowserObservationError } from "../domain/errors.js"; +import { + reconcileCapturedWebScript, + stableWebResources, + stableWebScriptKey, +} from "../domain/webInventory.js"; import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js"; import { CdpConnection } from "./CdpConnection.js"; import { CdpCaptureEvents } from "./CdpCaptureEvents.js"; @@ -14,6 +19,7 @@ import { captureDom, captureFrames, captureResources, + type CapturedResource, mainFrameUrl, } from "./CdpCaptureDocuments.js"; import { @@ -27,6 +33,7 @@ import { sourceResult, stringValue, } from "./CdpCaptureValues.js"; +import type { WebSourceMapRequest } from "./WebSourceMapFetcher.js"; interface CaptureContext { readonly connection: CdpConnection; @@ -43,7 +50,6 @@ interface CaptureState { readonly events: CdpCaptureEvents; readonly allowedOrigins: ReadonlySet; readonly limitations: string[]; - readonly truncatedSections: Set; readonly startedAt: string; } @@ -58,10 +64,20 @@ interface CapturedSections { readonly storage: WebPageInspection["storage"]; } +export interface CapturedPage { + readonly inspection: WebPageInspection; + readonly sourceMapRequests: readonly WebSourceMapRequest[]; +} + +interface CapturedScripts { + readonly inventory: WebPageInspection["scripts"]; + readonly sourceMapRequests: readonly WebSourceMapRequest[]; +} + /** Capture and normalize one attached page without evaluating page JavaScript. */ export const capturePage = async ( context: CaptureContext, -): Promise => { +): Promise => { const allowedOrigins = new Set(context.input.allowed_origins); const events = new CdpCaptureEvents(context.input, allowedOrigins); const removeListener = context.connection.onEvent((event) => { @@ -74,11 +90,10 @@ export const capturePage = async ( allowedOrigins, limitations: [ "Observation starts when REA attaches; prior network and console activity is unavailable.", - "Network headers, request bodies, response bodies, cookies, storage values, console values, and WebSocket payloads are not retained.", + "Raw network headers, bodies, cookies, storage values, console objects, and WebSocket payloads are never retained; separately approved captures retain only bounded redacted text or value-free shapes.", "Source maps are reported only as declarative URLs and are not fetched.", "URL-less scripts and console events without an allowed source URL are excluded because their origin cannot be proven.", ], - truncatedSections: new Set(), startedAt: new Date().toISOString(), }; try { @@ -90,19 +105,22 @@ export const capturePage = async ( const captureAuthorizedPage = async ( state: CaptureState, -): Promise => { - const { context, allowedOrigins, limitations, truncatedSections } = state; +): Promise => { + const { context, allowedOrigins, limitations } = state; const { connection, sessionId, input, signal } = context; await authorizeObservationWindow(state); + await captureJsonResponseBodies(state); const frameResult = await authorizedFrameTree(context, allowedOrigins); const attachedUrl = mainFrameUrl(frameResult) ?? ""; const frameCapture = captureFrames( frameResult, allowedOrigins, input.limits.max_frames, + state.events.completeness, ); const frames = frameCapture.items; - if (frameCapture.total > frames.length) truncatedSections.add("frames"); + if (frameCapture.total > frames.length) + state.events.completeness.truncate("frames"); const captureFrame = frames[0]; if (captureFrame === undefined) throw new BrowserObservationError("inspect_web_page", "target_not_allowed"); @@ -111,38 +129,39 @@ const captureAuthorizedPage = async ( await connection.send("Page.getResourceTree", {}, sessionId, signal), allowedOrigins, input.limits.max_resources, + state.events.completeness, ); if (resourceCapture.total > resourceCapture.items.length) - truncatedSections.add("resources"); - const dom = await capturePageDom(state); - if (dom.total > dom.nodes.length) truncatedSections.add("dom"); - const accessibility = await accessibilityForFrames( - context, - frames, - limitations, + state.events.completeness.truncate("resources"); + const resources = stableWebResources( + resourceCapture.items.map(publicResource), ); + const dom = await capturePageDom(state); + if (dom.total > dom.nodes.length) state.events.completeness.truncate("dom"); + const accessibility = await accessibilityForFrames(state, frames); if (accessibility.total > accessibility.nodes.length) - truncatedSections.add("accessibility"); + state.events.completeness.truncate("accessibility"); const scripts = await captureScripts( context, state.events, - truncatedSections, + resourceCapture.items, + resources, ); const workerCapture = await captureWorkers( - context, - allowedOrigins, + state, new Set(frames.map((frame) => frame.frame_id)), - limitations, ); if (workerCapture.total > workerCapture.items.length) - truncatedSections.add("workers"); + state.events.completeness.truncate("workers"); const storageCapture = await captureStorage( context, frames[0]?.origin ?? new URL(attachedUrl).origin, limitations, ); - if (storageCapture.truncated) truncatedSections.add("storage_keys"); - if (state.events.dropped > 0) truncatedSections.add("events"); + if (storageCapture.truncated) + state.events.completeness.truncate("storage_keys"); + if (!input.include_storage_keys) + state.events.completeness.exclude("storage_keys", "not_approved", null); const completedFrameResult = await authorizedFrameTree( context, allowedOrigins, @@ -153,16 +172,42 @@ const captureAuthorizedPage = async ( if (state.events.navigationDuringCapture || completedUrl !== attachedUrl) throw new BrowserObservationError("inspect_web_page", "target_changed"); await report(context.progress, 3, "Normalizing browser evidence"); - return normalizedInspection(state, { - attachedUrl, - frames, - dom, - accessibility, - scripts, - resources: resourceCapture.items, - workers: workerCapture.items, - storage: storageCapture.value, - }); + return { + inspection: normalizedInspection(state, { + attachedUrl, + frames, + dom, + accessibility, + scripts: scripts.inventory, + resources, + workers: workerCapture.items, + storage: storageCapture.value, + }), + sourceMapRequests: scripts.sourceMapRequests, + }; +}; + +const captureJsonResponseBodies = async ( + state: CaptureState, +): Promise => { + const requestIds = state.events.responseBodyRequestIds(); + for (let index = 0; index < requestIds.length; index += 1) { + const requestId = requestIds[index]; + if (requestId === undefined) continue; + const result = await optionalCdpCommand( + state.context, + "Network.getResponseBody", + { requestId }, + state.limitations, + ); + if (result !== undefined) { + state.events.ingestResponseBody(requestId, result); + continue; + } + for (const remaining of requestIds.slice(index)) + state.events.responseBodyUnavailable(remaining); + return; + } }; const authorizeObservationWindow = async ( @@ -199,14 +244,19 @@ const capturePageDom = async ( context.sessionId, context.signal, ); - return captureDom(result, allowedOrigins, context.input); + return captureDom( + result, + allowedOrigins, + context.input, + state.events.completeness, + ); }; const normalizedInspection = ( state: CaptureState, captured: CapturedSections, ): WebPageInspection => ({ - schema_version: 1, + schema_version: 2, browser: state.context.discovery.version, target: normalizedTarget( state.context.target, @@ -218,15 +268,12 @@ const normalizedInspection = ( ended_at: new Date().toISOString(), observation_ms: state.context.input.observation_ms, }, - completeness: { - status: state.truncatedSections.size === 0 ? "complete" : "truncated", - truncated_sections: [...state.truncatedSections].sort(), - dropped_events: state.events.dropped, - }, + completeness: state.events.completeness.snapshot(), frames: [...captured.frames], dom: { total_nodes: captured.dom.total, nodes: [...captured.dom.nodes] }, accessibility: { total_nodes: captured.accessibility.total, + text_capture: captured.accessibility.textCapture, nodes: [...captured.accessibility.nodes], }, scripts: captured.scripts, @@ -243,6 +290,16 @@ const normalizedInspection = ( prior_activity_available: false, }, workers: [...captured.workers], + metadata: { + responses: [...state.events.responseMetadata], + dom_urls: [...captured.dom.urls], + agent_hints: deduplicatedAgentHints([ + ...state.events.agentHints, + ...captured.dom.agentHints, + ]), + excluded_dom_urls: captured.dom.excludedUrls, + headers_allowlisted: true, + }, storage: captured.storage, limitations: state.limitations, }); @@ -295,12 +352,12 @@ const enableObservationDomains = async ( }; const accessibilityForFrames = async ( - context: CaptureContext, + state: CaptureState, frames: readonly { readonly frame_id: string }[], - limitations: string[], ): Promise> => { - const nodes: WebPageInspection["accessibility"]["nodes"] = []; - let total = 0; + const { context, limitations, events } = state; + const results: unknown[] = []; + let unavailable = false; for (const frame of frames) { const result = await optionalCdpCommand( context, @@ -308,24 +365,45 @@ const accessibilityForFrames = async ( { depth: 32, frameId: frame.frame_id }, limitations, ); - if (result === undefined) continue; - const capture = captureAccessibility( - [result], - Math.max(0, context.input.limits.max_ax_nodes - nodes.length), - ); - total += capture.total; - nodes.push(...capture.nodes); + if (result === undefined) unavailable = true; + else results.push(result); } - return { total, nodes }; + if (unavailable) events.completeness.unavailable("accessibility"); + const capture = captureAccessibility( + results, + context.input.limits.max_ax_nodes, + { + includeText: context.input.include_accessibility_text, + maximumFieldBytes: context.input.limits.max_ax_text_field_bytes, + maximumTotalBytes: context.input.limits.max_total_ax_text_bytes, + ...(results.length === 0 && unavailable ? { unavailable: true } : {}), + }, + ); + if (!context.input.include_accessibility_text) + events.completeness.exclude( + "accessibility", + "not_approved", + capture.textCapture.excluded_fields, + ); + if (capture.textCapture.status === "truncated") + events.completeness.truncate("accessibility"); + return capture; }; const captureScripts = async ( context: CaptureContext, events: CdpCaptureEvents, - truncatedSections: Set, -): Promise => { + rawResources: readonly CapturedResource[], + resources: WebPageInspection["resources"], +): Promise => { let totalSourceBytes = 0; - const items: WebPageInspection["scripts"]["items"] = []; + const drafts: { + readonly item: Omit< + WebPageInspection["scripts"]["items"][number], + "script_key" + >; + readonly sourceMapRawUrl: string | null; + }[] = []; for (const script of events.scripts.values()) { let source: WebPageInspection["scripts"]["items"][number]["source"] = sourceExcluded("source capture was not approved"); @@ -334,13 +412,13 @@ const captureScripts = async ( source = sourceExcluded( "declared script length exceeds per-script limit", ); - truncatedSections.add("script_sources"); + events.completeness.truncate("script_sources"); } else if ( totalSourceBytes + script.length > context.input.limits.max_total_script_source_bytes ) { source = sourceExcluded("total script source limit reached"); - truncatedSections.add("script_sources"); + events.completeness.truncate("script_sources"); } else { const result = requiredRecord( await context.connection.send( @@ -360,37 +438,103 @@ const captureScripts = async ( source = sourceExcluded( "actual source exceeds configured byte limits", ); - truncatedSections.add("script_sources"); + events.completeness.truncate("script_sources"); } else { source = sourceResult(content); totalSourceBytes += bytes; } } } - items.push({ - script_id: script.scriptId, + const inventoryScript = { url: script.url, - origin: script.origin, cdp_hash: script.hash, length: script.length, is_module: script.isModule, language: script.language, source_map_url: script.sourceMapUrl, - source, + }; + drafts.push({ + item: { + ...inventoryScript, + origin: script.origin, + resource_reconciliation: reconcileCapturedWebScript( + { ...inventoryScript, rawUrl: script.rawUrl }, + rawResources, + resources, + ), + source, + }, + sourceMapRawUrl: script.sourceMapRawUrl, }); } - return { total: events.scripts.size, items }; + if (!context.input.include_script_sources) + events.completeness.exclude( + "script_sources", + "not_approved", + events.scripts.size, + ); + const keyed = drafts.map((draft) => ({ + ...draft, + base: stableWebScriptKey(draft.item), + })); + keyed.sort( + (left, right) => + left.base.localeCompare(right.base) || + sourceDigest(left.item.source).localeCompare( + sourceDigest(right.item.source), + ), + ); + const totals = new Map(); + for (const { base } of keyed) totals.set(base, (totals.get(base) ?? 0) + 1); + const seen = new Map(); + const sourceMapRequests: WebSourceMapRequest[] = []; + const items = keyed.map(({ base, item, sourceMapRawUrl }) => { + const occurrence = (seen.get(base) ?? 0) + 1; + seen.set(base, occurrence); + const scriptKey = + totals.get(base) === 1 ? base : `${base}_${String(occurrence)}`; + if (item.source_map_url !== null && sourceMapRawUrl !== null) + sourceMapRequests.push({ + scriptKey, + declaredUrl: item.source_map_url, + fetchUrl: sourceMapRawUrl, + }); + return { script_key: scriptKey, ...item }; + }); + return { + inventory: { total: events.scripts.size, items }, + sourceMapRequests, + }; +}; + +const sourceDigest = ( + source: WebPageInspection["scripts"]["items"][number]["source"], +): string => (source.included ? source.artifact.sha256 : source.reason); + +const publicResource = ({ rawUrl: _rawUrl, ...resource }: CapturedResource) => + resource; + +const deduplicatedAgentHints = ( + hints: WebPageInspection["metadata"]["agent_hints"], +): WebPageInspection["metadata"]["agent_hints"] => { + const seen = new Set(); + return hints.filter((hint) => { + const key = `${hint.mechanism}\0${hint.declaration}\0${hint.url ?? ""}`; + if (seen.has(key)) return false; + seen.add(key); + return true; + }); }; const captureWorkers = async ( - context: CaptureContext, - allowedOrigins: ReadonlySet, + state: CaptureState, frameIds: ReadonlySet, - limitations: string[], ): Promise<{ readonly total: number; readonly items: WebPageInspection["workers"]; }> => { + const { context, allowedOrigins, limitations, events } = state; + const completeness = events.completeness; const result = await optionalCdpCommand( { ...context, sessionId: undefined }, "Target.getTargets", @@ -399,6 +543,7 @@ const captureWorkers = async ( ); const items: WebPageInspection["workers"] = []; let total = 0; + if (result === undefined) completeness.unavailable("workers"); for (const target of recordsValue(recordValue(result)?.targetInfos)) { const type = stringValue(target.type) ?? ""; const url = allowedSanitizedUrl(target.url, allowedOrigins); @@ -406,8 +551,23 @@ const captureWorkers = async ( stringValue(target.openerId) === context.target.id || (stringValue(target.parentFrameId) !== undefined && frameIds.has(stringValue(target.parentFrameId) ?? "")); - if (!type.includes("worker") || url === undefined || !relatedToPage) + if (!type.includes("worker")) continue; + if (!relatedToPage) { + completeness.exclude("workers", "out_of_target_scope"); continue; + } + if (url === undefined) { + const rawUrl = stringValue(target.url); + completeness.exclude( + "workers", + rawUrl === undefined || rawUrl === "" + ? "unattributed_origin" + : isHttpUrl(rawUrl) + ? "disallowed_origin" + : "unsupported_url", + ); + continue; + } total += 1; if (items.length >= context.input.limits.max_workers) continue; items.push({ diff --git a/src/browser/CdpSafeMetadata.ts b/src/browser/CdpSafeMetadata.ts new file mode 100644 index 000000000..5f9c80107 --- /dev/null +++ b/src/browser/CdpSafeMetadata.ts @@ -0,0 +1,277 @@ +import type { WebPageInspection } from "../domain/browserObservation.js"; +import { sanitizeBrowserUrl } from "../domain/browserObservation.js"; +import { + numberValue, + stringValue, + type UnknownRecord, +} from "./CdpCaptureValues.js"; + +type ResponseMetadata = WebPageInspection["metadata"]["responses"][number]; +type LinkMetadata = ResponseMetadata["links"][number]; +type AgentHint = WebPageInspection["metadata"]["agent_hints"][number]; + +/** Normalize an allowlisted subset of response metadata and discard raw headers. */ +export const safeResponseMetadata = ( + requestId: string, + url: string, + response: UnknownRecord, + allowedOrigins: ReadonlySet, +): { + readonly response: ResponseMetadata; + readonly agentHints: AgentHint[]; +} => { + const headers = normalizedHeaders(response.headers); + const links = parseLinks(headers.get("link"), url, allowedOrigins); + const csp = parseCsp( + headers.get("content-security-policy"), + url, + allowedOrigins, + ); + const agentHints = [ + ...links.flatMap((link) => + link.rel.some(isAgentRel) + ? [agentHint("link_rel", link.rel.join(" "), link.href)] + : [], + ), + ...agentHeaderNames.flatMap((name) => + headers.has(name) ? [agentHint("response_header", name, null)] : [], + ), + ...wellKnownHint(url), + ]; + return { + response: { + request_id: requestId, + url, + mime_type: boundedHeader(stringValue(response.mimeType)), + content_length: nonnegativeInteger(headers.get("content-length")), + content_encoding: boundedHeader(headers.get("content-encoding")), + csp, + links, + policies: { + coop: policyToken(headers.get("cross-origin-opener-policy")), + coep: policyToken(headers.get("cross-origin-embedder-policy")), + corp: policyToken(headers.get("cross-origin-resource-policy")), + referrer_policy: policyToken(headers.get("referrer-policy")), + x_content_type_options: policyToken( + headers.get("x-content-type-options"), + ), + permissions_policy_features: permissionFeatures( + headers.get("permissions-policy"), + ), + }, + }, + agentHints, + }; +}; + +const normalizedHeaders = (value: unknown): ReadonlyMap => { + if (typeof value !== "object" || value === null || Array.isArray(value)) + return new Map(); + const headers = new Map(); + for (const [name, raw] of Object.entries(value).slice(0, 500)) { + const normalized = name.toLowerCase().slice(0, 256); + const header = + typeof raw === "string" + ? raw + : typeof raw === "number" && Number.isFinite(raw) + ? String(raw) + : undefined; + if (header !== undefined) headers.set(normalized, header.slice(0, 65_536)); + } + return headers; +}; + +const parseCsp = ( + value: string | undefined, + baseUrl: string, + allowedOrigins: ReadonlySet, +): ResponseMetadata["csp"] => { + const directives: ResponseMetadata["csp"]["directives"] = []; + let nonceCount = 0; + let hashCount = 0; + for (const rawDirective of (value ?? "").split(";").slice(0, 100)) { + const [rawName, ...tokens] = rawDirective.trim().split(/\s+/u); + const name = (rawName ?? "").toLowerCase(); + if (!/^[a-z][a-z0-9-]{0,99}$/u.test(name)) continue; + const sources: ResponseMetadata["csp"]["directives"][number]["sources"] = + []; + for (const token of tokens.slice(0, 100)) { + const lower = token.toLowerCase(); + if (lower.startsWith("'nonce-")) { + nonceCount += 1; + continue; + } + if ( + lower.startsWith("'sha256-") || + lower.startsWith("'sha384-") || + lower.startsWith("'sha512-") + ) { + hashCount += 1; + continue; + } + sources.push(cspSource(token, baseUrl, allowedOrigins)); + } + directives.push({ name, sources }); + } + return { directives, nonce_count: nonceCount, hash_count: hashCount }; +}; + +const cspSource = ( + token: string, + baseUrl: string, + allowedOrigins: ReadonlySet, +): ResponseMetadata["csp"]["directives"][number]["sources"][number] => { + const lower = token.toLowerCase(); + if (/^'[a-z0-9-]+'$/u.test(lower)) + return { kind: "keyword", value: lower.slice(0, 100) }; + if (/^[a-z][a-z0-9+.-]*:$/u.test(lower)) + return { kind: "scheme", value: lower.slice(0, 100) }; + try { + const parsed = new URL(token, baseUrl); + return allowedOrigins.has(parsed.origin) + ? { kind: "approved_origin", value: parsed.origin } + : { kind: "external_origin", value: null }; + } catch { + return { kind: "other", value: null }; + } +}; + +const parseLinks = ( + value: string | undefined, + baseUrl: string, + allowedOrigins: ReadonlySet, +): LinkMetadata[] => { + const links: LinkMetadata[] = []; + for (const entry of splitLinkHeader(value ?? "").slice(0, 100)) { + const match = /^\s*<([^>]{1,4096})>(.*)$/u.exec(entry); + if (match === null) continue; + const parameters = linkParameters(match[2] ?? ""); + const destination = safeDestination( + match[1] ?? "", + baseUrl, + allowedOrigins, + ); + links.push({ + href: destination.url, + destination_scope: destination.scope, + rel: (parameters.get("rel") ?? "") + .toLowerCase() + .split(/\s+/u) + .filter(Boolean) + .slice(0, 32), + as: boundedHeader(parameters.get("as")), + type: boundedHeader(parameters.get("type")), + crossorigin: boundedHeader(parameters.get("crossorigin")), + }); + } + return links; +}; + +const splitLinkHeader = (value: string): string[] => { + const entries: string[] = []; + let start = 0; + let quoted = false; + for (let index = 0; index < value.length; index += 1) { + const character = value[index]; + if (character === '"' && value[index - 1] !== "\\") quoted = !quoted; + if (character !== "," || quoted) continue; + entries.push(value.slice(start, index)); + start = index + 1; + } + entries.push(value.slice(start)); + return entries; +}; + +const linkParameters = (value: string): ReadonlyMap => { + const parameters = new Map(); + for (const raw of value.split(";").slice(1, 50)) { + const separator = raw.indexOf("="); + const name = (separator < 0 ? raw : raw.slice(0, separator)) + .trim() + .toLowerCase(); + if (!/^[a-z][a-z0-9-]{0,99}$/u.test(name)) continue; + const parameter = separator < 0 ? "" : raw.slice(separator + 1).trim(); + parameters.set(name, unquote(parameter).slice(0, 1_024)); + } + return parameters; +}; + +const safeDestination = ( + value: string, + baseUrl: string, + allowedOrigins: ReadonlySet, +): { + readonly url: string | null; + readonly scope: LinkMetadata["destination_scope"]; +} => { + try { + const parsed = new URL(value, baseUrl); + if (parsed.protocol !== "http:" && parsed.protocol !== "https:") + return { url: null, scope: "unsupported" }; + if (!allowedOrigins.has(parsed.origin)) + return { url: null, scope: "outside_policy" }; + return { url: sanitizeBrowserUrl(parsed.href).url, scope: "approved" }; + } catch { + return { url: null, scope: "unsupported" }; + } +}; + +const permissionFeatures = (value: string | undefined): string[] => + [ + ...new Set( + (value ?? "") + .split(",") + .map((entry) => entry.split("=", 1)[0]?.trim().toLowerCase() ?? "") + .filter((feature) => /^[a-z][a-z0-9-]{0,99}$/u.test(feature)), + ), + ] + .sort() + .slice(0, 200); + +const wellKnownHint = (url: string): AgentHint[] => { + try { + const path = new URL(url).pathname.toLowerCase(); + return wellKnownAgentPaths.has(path) + ? [agentHint("well_known_resource", path, sanitizeBrowserUrl(url).url)] + : []; + } catch { + return []; + } +}; + +const agentHint = ( + mechanism: AgentHint["mechanism"], + declaration: string, + url: string | null, +): AgentHint => ({ + mechanism, + declaration: declaration.slice(0, 256), + url, + trust: "page-declared-untrusted", +}); + +const isAgentRel = (value: string): boolean => + ["mcp", "model-context", "ai-plugin", "service-desc"].includes(value); + +const policyToken = (value: string | undefined): string | null => { + const token = (value ?? "").trim().toLowerCase(); + return /^[a-z][a-z0-9_.-]{0,99}$/u.test(token) ? token : null; +}; + +const nonnegativeInteger = (value: string | undefined): number | null => { + const number = numberValue(value === undefined ? undefined : Number(value)); + return number === undefined ? null : Math.max(0, Math.trunc(number)); +}; + +const boundedHeader = (value: string | undefined): string | null => + value === undefined ? null : value.trim().toLowerCase().slice(0, 256); + +const unquote = (value: string): string => + value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value; + +const agentHeaderNames = ["x-model-context", "x-webmcp", "mcp-server"] as const; +const wellKnownAgentPaths: ReadonlySet = new Set([ + "/.well-known/ai-plugin.json", + "/.well-known/mcp", + "/.well-known/model-context", +]); diff --git a/src/browser/CdpScreenshot.ts b/src/browser/CdpScreenshot.ts new file mode 100644 index 000000000..6c27518e9 --- /dev/null +++ b/src/browser/CdpScreenshot.ts @@ -0,0 +1,164 @@ +import type { ProgressReporter } from "../application/ProgressReporter.js"; +import type { + CaptureWebScreenshotInput, + WebScreenshot, +} from "../domain/webScreenshot.js"; +import { createWebScreenshotArtifact } from "../domain/webScreenshot.js"; +import { BrowserObservationError } from "../domain/errors.js"; +import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js"; +import type { CdpConnection, CdpEvent } from "./CdpConnection.js"; +import { + allowedSanitizedUrl, + recordValue, + stringValue, +} from "./CdpCaptureValues.js"; +import { mainFrameUrl } from "./CdpCaptureDocuments.js"; +import { captureFrames } from "./CdpCaptureDocuments.js"; +import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js"; +import { decodeCanonicalBase64 } from "../domain/webScreenshot.js"; + +interface ScreenshotContext { + readonly connection: CdpConnection; + readonly sessionId: string; + readonly discovery: CdpEndpointDiscovery; + readonly target: CdpEndpointTarget; + readonly input: CaptureWebScreenshotInput; + readonly signal?: AbortSignal; + readonly progress?: ProgressReporter; +} + +/** Capture the current viewport without navigation, evaluation, or page mutation. */ +export const captureCdpScreenshot = async ( + context: ScreenshotContext, +): Promise => { + const origins = new Set(context.input.allowed_origins); + await context.progress?.report({ + phase: "browser_observation", + completed: 1, + total: 2, + message: "Authorizing current screenshot frame", + }); + await context.connection.send( + "Page.enable", + {}, + context.sessionId, + context.signal, + ); + const before = await context.connection.send( + "Page.getFrameTree", + {}, + context.sessionId, + context.signal, + ); + const beforeUrl = mainFrameUrl(before); + const authorized = allowedSanitizedUrl(beforeUrl, origins); + const mainFrame = captureFrames(before, origins, 1).items[0]; + if (authorized === undefined || mainFrame === undefined) + throw new BrowserObservationError("inspect_web_page", "target_not_allowed"); + const navigation = { changed: false, leftScope: false }; + const removeListener = context.connection.onEvent((event) => { + if (event.sessionId !== context.sessionId) return; + observeScreenshotNavigation(event, mainFrame.frame_id, origins, navigation); + }); + let result: ReturnType; + let after: unknown; + try { + result = recordValue( + await context.connection.send( + "Page.captureScreenshot", + { format: "png", fromSurface: true, captureBeyondViewport: false }, + context.sessionId, + context.signal, + ), + ); + after = await context.connection.send( + "Page.getFrameTree", + {}, + context.sessionId, + context.signal, + ); + } finally { + removeListener(); + } + const encoded = stringValue(result?.data); + const bytes = + encoded === undefined ? undefined : decodeCanonicalBase64(encoded); + if ( + bytes === undefined || + bytes.byteLength > context.input.maximum_image_bytes + ) + throw new BrowserObservationError("inspect_web_page", "payload_limit"); + const dimensions = pngDimensions(bytes); + if (navigation.leftScope) + throw new BrowserObservationError("inspect_web_page", "target_not_allowed"); + const afterUrl = mainFrameUrl(after); + if ( + navigation.changed || + afterUrl !== beforeUrl || + allowedSanitizedUrl(afterUrl, origins) === undefined + ) + throw new BrowserObservationError("inspect_web_page", "target_changed"); + await context.progress?.report({ + phase: "browser_observation", + completed: 2, + total: 2, + message: "Screenshot capture complete", + terminal: true, + }); + return { + schema_version: 1, + browser: context.discovery.version, + target: { + target_id: context.target.id, + url: authorized.url, + origin: authorized.origin ?? "", + }, + captured_at: new Date().toISOString(), + viewport: dimensions, + artifact: createWebScreenshotArtifact(bytes), + completeness: new CdpCaptureCompleteness().snapshot(), + limitations: [ + "The screenshot contains the visible viewport and may include sensitive on-screen content; capture requires separate approval.", + "REA does not scroll, evaluate JavaScript, or capture beyond the current viewport.", + ], + }; +}; + +const observeScreenshotNavigation = ( + event: CdpEvent, + mainFrameId: string, + origins: ReadonlySet, + state: { changed: boolean; leftScope: boolean }, +): void => { + const params = recordValue(event.params); + if (params === undefined) return; + const frame = + event.method === "Page.frameNavigated" ? recordValue(params.frame) : params; + if ( + (event.method !== "Page.frameNavigated" && + event.method !== "Page.navigatedWithinDocument") || + (stringValue(frame?.id) ?? stringValue(frame?.frameId)) !== mainFrameId + ) + return; + state.changed = true; + if (allowedSanitizedUrl(frame?.url, origins) === undefined) + state.leftScope = true; +}; + +const pngDimensions = ( + bytes: Buffer, +): { readonly width: number; readonly height: number } => { + if ( + bytes.byteLength < 24 || + !bytes.subarray(0, 8).equals(PNG_SIGNATURE) || + bytes.subarray(12, 16).toString("ascii") !== "IHDR" + ) + throw new BrowserObservationError("inspect_web_page", "protocol_error"); + const width = bytes.readUInt32BE(16); + const height = bytes.readUInt32BE(20); + if (width === 0 || height === 0 || width * height > 32_000_000) + throw new BrowserObservationError("inspect_web_page", "payload_limit"); + return { width, height }; +}; + +const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]); diff --git a/src/browser/CdpWebMcpDiscovery.ts b/src/browser/CdpWebMcpDiscovery.ts new file mode 100644 index 000000000..8297a8a85 --- /dev/null +++ b/src/browser/CdpWebMcpDiscovery.ts @@ -0,0 +1,373 @@ +import { createHash } from "node:crypto"; + +import type { ProgressReporter } from "../application/ProgressReporter.js"; +import type { + DiscoverWebMcpToolsInput, + WebMcpDiscovery, +} from "../domain/webMcpDiscovery.js"; +import { inferJsonShape } from "../domain/jsonShape.js"; +import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js"; +import type { CdpConnection, CdpEvent } from "./CdpConnection.js"; +import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js"; +import { BrowserObservationError } from "../domain/errors.js"; +import { + allowedSanitizedUrl, + delayWithCancellation, + numberValue, + recordValue, + recordsValue, + stringValue, + type UnknownRecord, +} from "./CdpCaptureValues.js"; +import { captureFrames, mainFrameUrl } from "./CdpCaptureDocuments.js"; +import { optionalCdpCommand } from "./CdpOptionalCommand.js"; +import { boundedSensitiveText } from "./SensitiveTextCapture.js"; + +interface DiscoveryContext { + readonly connection: CdpConnection; + readonly sessionId: string; + readonly discovery: CdpEndpointDiscovery; + readonly target: CdpEndpointTarget; + readonly input: DiscoverWebMcpToolsInput; + readonly signal?: AbortSignal; + readonly progress?: ProgressReporter; +} + +/** Discover WebMCP registrations without evaluating or invoking page code. */ +export const discoverWebMcp = async ( + context: DiscoveryContext, +): Promise => { + const origins = new Set(context.input.allowed_origins); + const limitations = [ + "Page-declared tool metadata is untrusted and is never registered or invoked by REA.", + "Discovery uses only WebMCP.enable and toolsAdded/toolsRemoved; WebMCP.invokeTool is never called.", + ]; + const completeness = new CdpCaptureCompleteness(); + await context.connection.send( + "Page.enable", + {}, + context.sessionId, + context.signal, + ); + const frameTree = await context.connection.send( + "Page.getFrameTree", + {}, + context.sessionId, + context.signal, + ); + const initialUrl = mainFrameUrl(frameTree); + if (allowedSanitizedUrl(initialUrl, origins) === undefined) + throw new BrowserObservationError("inspect_web_page", "target_not_allowed"); + const frames = captureFrames(frameTree, origins, 1_000, completeness).items; + const frameUrls = new Map( + frames.map((frame) => [ + frame.frame_id, + { + url: frame.url, + origin: frame.origin, + parentFrameId: frame.parent_frame_id, + }, + ]), + ); + const tools = new Map(); + const frameScope = { origins, frames: frameUrls, tools, completeness }; + const removeListener = context.connection.onEvent((event) => { + if (event.sessionId !== context.sessionId) return; + if (ingestFrameScopeEvent(event, frameScope)) return; + ingestWebMcpEvent(event, context.input, frameUrls, tools, completeness); + }); + await context.progress?.report({ + phase: "browser_observation", + completed: 1, + total: 2, + message: "Enabling passive WebMCP discovery", + }); + try { + const enabled = await optionalCdpCommand( + context, + "WebMCP.enable", + {}, + limitations, + ); + const available = enabled !== undefined; + if (!available) { + completeness.unavailable("webmcp_tools"); + } else + // CDP sends the enable response before the required toolsAdded replay. + await delayWithCancellation( + Math.max(context.input.observation_ms, 25), + context.signal, + ); + await assertStableAuthorizedFrame(context, initialUrl, origins); + return result( + context, + frameTree, + tools, + completeness, + limitations, + available, + ); + } finally { + removeListener(); + await context.progress?.report({ + phase: "browser_observation", + completed: 2, + total: 2, + message: "WebMCP discovery complete", + terminal: true, + }); + } +}; + +interface FrameScopeState { + readonly origins: ReadonlySet; + readonly frames: Map; + readonly tools: Map; + readonly completeness: CdpCaptureCompleteness; +} + +interface FrameScopeFrame { + readonly url: string; + readonly origin: string | null; + readonly parentFrameId: string | null; +} + +const ingestFrameScopeEvent = ( + event: CdpEvent, + state: FrameScopeState, +): boolean => { + const params = recordValue(event.params); + if (params === undefined) return false; + if (event.method === "Page.frameDetached") { + const frameId = stringValue(params.frameId); + if (frameId === undefined || frameId.length > 256) + state.completeness.exclude("webmcp_tools", "invalid_protocol_value"); + else removeFrame(frameId, state.frames, state.tools); + return true; + } + const frame = + event.method === "Page.frameNavigated" ? recordValue(params.frame) : params; + if ( + event.method !== "Page.frameNavigated" && + event.method !== "Page.navigatedWithinDocument" + ) + return false; + const frameId = stringValue(frame?.id) ?? stringValue(frame?.frameId); + if (frameId === undefined || frameId.length > 256) { + state.completeness.exclude("webmcp_tools", "invalid_protocol_value"); + return true; + } + const url = allowedSanitizedUrl(frame?.url, state.origins); + if (url === undefined || url.origin === null) { + removeFrame(frameId, state.frames, state.tools); + state.completeness.exclude("webmcp_tools", "out_of_target_scope"); + return true; + } + state.frames.set(frameId, { + url: url.url, + origin: url.origin, + parentFrameId: + (stringValue(frame?.parentId) ?? + state.frames.get(frameId)?.parentFrameId ?? + "") || + null, + }); + return true; +}; + +const removeFrame = ( + frameId: string, + frames: Map, + tools: Map, +): void => { + const pending = [frameId]; + const removed = new Set(); + while (pending.length > 0) { + const current = pending.pop(); + if (current === undefined || removed.has(current)) continue; + removed.add(current); + for (const [candidate, frame] of frames) + if (frame.parentFrameId === current) pending.push(candidate); + frames.delete(current); + } + for (const [key, tool] of tools) + if (removed.has(tool.frame_id)) tools.delete(key); +}; + +const assertStableAuthorizedFrame = async ( + context: DiscoveryContext, + initialUrl: string | undefined, + origins: ReadonlySet, +): Promise => { + const finalTree = await context.connection.send( + "Page.getFrameTree", + {}, + context.sessionId, + context.signal, + ); + const finalUrl = mainFrameUrl(finalTree); + if (allowedSanitizedUrl(finalUrl, origins) === undefined) + throw new BrowserObservationError("inspect_web_page", "target_not_allowed"); + if (finalUrl !== initialUrl) + throw new BrowserObservationError("inspect_web_page", "target_changed"); +}; + +const ingestWebMcpEvent = ( + event: CdpEvent, + input: DiscoverWebMcpToolsInput, + frames: ReadonlyMap< + string, + { readonly url: string; readonly origin: string | null } + >, + tools: Map, + completeness: CdpCaptureCompleteness, +): void => { + const params = recordValue(event.params); + if (params === undefined) return; + if (event.method === "WebMCP.toolsRemoved") { + for (const removed of recordsValue(params.tools)) { + const name = stringValue(removed.name); + const frameId = stringValue(removed.frameId); + if (name === undefined || frameId === undefined) continue; + for (const [key, tool] of tools) + if (tool.name === name && tool.frame_id === frameId) tools.delete(key); + } + return; + } + if (event.method !== "WebMCP.toolsAdded") return; + for (const declared of recordsValue(params.tools)) { + const normalized = normalizeTool(declared, input, frames, completeness); + if (normalized === undefined) continue; + if (!tools.has(normalized.tool_key) && tools.size >= input.max_tools) { + completeness.drop("webmcp_tools"); + continue; + } + tools.set(normalized.tool_key, normalized); + } +}; + +const normalizeTool = ( + value: UnknownRecord, + input: DiscoverWebMcpToolsInput, + frames: ReadonlyMap< + string, + { readonly url: string; readonly origin: string | null } + >, + completeness: CdpCaptureCompleteness, +): WebMcpDiscovery["tools"]["items"][number] | undefined => { + const frameId = stringValue(value.frameId); + const name = stringValue(value.name); + const frame = frameId === undefined ? undefined : frames.get(frameId); + if ( + frameId === undefined || + name === undefined || + frame?.origin === null || + frame === undefined + ) { + completeness.exclude("webmcp_tools", "out_of_target_scope"); + return undefined; + } + const description = boundedSensitiveText( + stringValue(value.description) ?? "", + 4_096, + ).text; + const annotations = recordValue(value.annotations); + return { + tool_key: toolKey(frame.url, name), + name: boundedSensitiveText(name, 512).text, + description, + frame_id: frameId.slice(0, 256), + frame_url: frame.url, + owner_origin: frame.origin, + declaration_kind: + numberValue(value.backendNodeId) === undefined + ? "imperative" + : "declarative", + input_schema_shape: schemaShape(value.inputSchema, input, completeness), + annotations: { + read_only: booleanOrNull(annotations?.readOnly), + untrusted_content: booleanOrNull(annotations?.untrustedContent), + autosubmit: booleanOrNull(annotations?.autosubmit), + }, + registration_source: registrationSource( + recordValue(value.stackTrace), + new Set(input.allowed_origins), + ), + trust: "page-declared-untrusted", + }; +}; + +const schemaShape = ( + value: unknown, + input: DiscoverWebMcpToolsInput, + completeness: CdpCaptureCompleteness, +) => { + if (recordValue(value) === undefined) return null; + const encoded = JSON.stringify(value); + const shape = inferJsonShape(encoded, { + maximumBytes: input.max_schema_bytes, + maximumNodes: input.max_schema_nodes, + maximumDepth: input.max_schema_depth, + }); + if (shape === null || shape.truncated) completeness.truncate("webmcp_tools"); + return shape; +}; + +const registrationSource = ( + stack: UnknownRecord | undefined, + allowedOrigins: ReadonlySet, +): WebMcpDiscovery["tools"]["items"][number]["registration_source"] => { + const frame = recordsValue(stack?.callFrames)[0]; + const url = allowedSanitizedUrl(frame?.url, allowedOrigins); + return frame === undefined || url === undefined + ? null + : { + url: url.url, + line: integerOrNull(frame.lineNumber), + column: integerOrNull(frame.columnNumber), + }; +}; + +const result = ( + context: DiscoveryContext, + frameTree: unknown, + tools: ReadonlyMap, + completeness: CdpCaptureCompleteness, + limitations: string[], + available: boolean, +): WebMcpDiscovery => { + const targetUrl = mainFrameUrl(frameTree) ?? context.target.url; + const sanitized = allowedSanitizedUrl( + targetUrl, + new Set(context.input.allowed_origins), + ); + return { + schema_version: 1, + browser: context.discovery.version, + target: { + target_id: context.target.id, + url: sanitized?.url ?? "[unsupported-url]", + origin: sanitized?.origin ?? "", + }, + status: available ? "available" : "unavailable", + tools: { + total: tools.size + completeness.droppedTotal, + items: [...tools.values()].sort((left, right) => + left.tool_key.localeCompare(right.tool_key), + ), + }, + completeness: completeness.snapshot(), + limitations, + }; +}; + +const toolKey = (frameUrl: string, name: string): string => + `webmcp_${createHash("sha256").update(`${frameUrl}\0${name}`).digest("hex")}`; + +const booleanOrNull = (value: unknown): boolean | null => + typeof value === "boolean" ? value : null; + +const integerOrNull = (value: unknown): number | null => { + const number = numberValue(value); + return number === undefined ? null : Math.max(0, Math.trunc(number)); +}; diff --git a/src/browser/ElectronFileScope.ts b/src/browser/ElectronFileScope.ts new file mode 100644 index 000000000..42939ddbc --- /dev/null +++ b/src/browser/ElectronFileScope.ts @@ -0,0 +1,56 @@ +import { realpath } from "node:fs/promises"; +import { isAbsolute, relative } from "node:path"; +import { fileURLToPath } from "node:url"; + +/** Canonicalize operator roots before evaluating any Electron file target. */ +export const canonicalElectronRoots = async ( + roots: readonly string[], +): Promise => { + const canonical: string[] = []; + for (const root of roots) canonical.push(await realpath(root)); + return [...new Set(canonical)].sort(); +}; + +/** Resolve one file URL and reject host, encoding, and symlink root escapes. */ +export const authorizedElectronFile = async ( + value: string, + roots: readonly string[], +): Promise => { + if (value.length > 65_536 || /%(?:2f|5c)/iu.test(value)) return undefined; + let url: URL; + try { + url = new URL(value); + } catch { + return undefined; + } + if ( + url.protocol !== "file:" || + url.hostname !== "" || + url.username !== "" || + url.password !== "" + ) + return undefined; + let path: string; + try { + path = fileURLToPath(url); + } catch { + return undefined; + } + if (!isAbsolute(path) || path.includes("\0")) return undefined; + let canonical: string; + try { + canonical = await realpath(path); + } catch { + return undefined; + } + return roots.some((root) => withinRoot(root, canonical)) + ? canonical + : undefined; +}; + +const withinRoot = (root: string, path: string): boolean => { + const remainder = relative(root, path); + return ( + remainder === "" || (!remainder.startsWith("..") && !isAbsolute(remainder)) + ); +}; diff --git a/src/browser/PngVisualDiff.ts b/src/browser/PngVisualDiff.ts new file mode 100644 index 000000000..40494071b --- /dev/null +++ b/src/browser/PngVisualDiff.ts @@ -0,0 +1,222 @@ +import { inflateSync } from "node:zlib"; + +import type { + CompareWebScreenshotsInput, + WebScreenshotArtifact, + WebScreenshotDiff, +} from "../domain/webScreenshot.js"; +import { decodeCanonicalBase64 } from "../domain/webScreenshot.js"; + +interface DecodedPng { + readonly width: number; + readonly height: number; + readonly rgba: Buffer; +} + +/** Compare two validated screenshots using bounded, deterministic RGBA metrics. */ +export const comparePngScreenshots = ( + input: CompareWebScreenshotsInput, +): WebScreenshotDiff => { + const before = decodePng(input.before, input.maximum_pixels); + const after = decodePng(input.after, input.maximum_pixels); + if (before.width !== after.width || before.height !== after.height) + return { + schema_version: 1, + status: "dimension_mismatch", + before: dimensions(before), + after: dimensions(after), + channel_threshold: input.channel_threshold, + compared_pixels: 0, + changed_pixels: null, + changed_ratio: null, + maximum_channel_delta: null, + mean_absolute_channel_delta: null, + limitations: limitations(), + }; + let changedPixels = 0; + let maximumDelta = 0; + let totalDelta = 0; + for (let offset = 0; offset < before.rgba.length; offset += 4) { + let changed = false; + for (let channel = 0; channel < 4; channel += 1) { + const delta = Math.abs( + (before.rgba[offset + channel] ?? 0) - + (after.rgba[offset + channel] ?? 0), + ); + totalDelta += delta; + maximumDelta = Math.max(maximumDelta, delta); + if (delta > input.channel_threshold) changed = true; + } + if (changed) changedPixels += 1; + } + const pixels = before.width * before.height; + return { + schema_version: 1, + status: changedPixels === 0 ? "identical" : "different", + before: dimensions(before), + after: dimensions(after), + channel_threshold: input.channel_threshold, + compared_pixels: pixels, + changed_pixels: changedPixels, + changed_ratio: changedPixels / pixels, + maximum_channel_delta: maximumDelta, + mean_absolute_channel_delta: totalDelta / (pixels * 4), + limitations: limitations(), + }; +}; + +const decodePng = ( + artifact: WebScreenshotArtifact, + maximumPixels: number, +): DecodedPng => { + const bytes = decodeCanonicalBase64(artifact.data_base64); + if (bytes === undefined || !bytes.subarray(0, 8).equals(PNG_SIGNATURE)) + throw new TypeError("Invalid PNG signature"); + let offset = 8; + let header: ReturnType | undefined; + const compressed: Buffer[] = []; + let sawEnd = false; + while (offset < bytes.length) { + if (offset + 12 > bytes.length) throw new TypeError("Truncated PNG chunk"); + const length = bytes.readUInt32BE(offset); + const type = bytes.subarray(offset + 4, offset + 8).toString("ascii"); + const dataStart = offset + 8; + const dataEnd = dataStart + length; + if (dataEnd + 4 > bytes.length) throw new TypeError("Truncated PNG data"); + const data = bytes.subarray(dataStart, dataEnd); + if (type === "IHDR") header = parseHeader(data, maximumPixels); + else if (type === "IDAT") compressed.push(data); + else if (type === "IEND") { + sawEnd = true; + break; + } + offset = dataEnd + 4; + } + if (header === undefined || !sawEnd || compressed.length === 0) + throw new TypeError("Incomplete PNG"); + const rowBytes = header.width * header.channels; + const expected = (rowBytes + 1) * header.height; + const raw = inflateSync(Buffer.concat(compressed), { + maxOutputLength: expected + 1, + }); + if (raw.byteLength !== expected) throw new TypeError("Unexpected PNG size"); + return { + width: header.width, + height: header.height, + rgba: unfilter(raw, header.width, header.height, header.channels), + }; +}; + +const parseHeader = (data: Buffer, maximumPixels: number) => { + if (data.byteLength !== 13) throw new TypeError("Invalid PNG header"); + const width = data.readUInt32BE(0); + const height = data.readUInt32BE(4); + const bitDepth = data[8]; + const colorType = data[9]; + if ( + width === 0 || + height === 0 || + width * height > maximumPixels || + bitDepth !== 8 || + (colorType !== 2 && colorType !== 6) || + data[10] !== 0 || + data[11] !== 0 || + data[12] !== 0 + ) + throw new TypeError("Unsupported or oversized PNG"); + return { width, height, channels: colorType === 6 ? 4 : 3 }; +}; + +const unfilter = ( + raw: Buffer, + width: number, + height: number, + channels: number, +): Buffer => { + const rowBytes = width * channels; + const decoded = Buffer.alloc(rowBytes * height); + for (let row = 0; row < height; row += 1) { + const rawOffset = row * (rowBytes + 1); + const outputOffset = row * rowBytes; + const filter = raw[rawOffset]; + if (filter === undefined || filter > 4) + throw new TypeError("Unsupported PNG filter"); + for (let column = 0; column < rowBytes; column += 1) { + const source = raw[rawOffset + 1 + column] ?? 0; + const left = + column >= channels + ? (decoded[outputOffset + column - channels] ?? 0) + : 0; + const above = + row > 0 ? (decoded[outputOffset + column - rowBytes] ?? 0) : 0; + const upperLeft = + row > 0 && column >= channels + ? (decoded[outputOffset + column - rowBytes - channels] ?? 0) + : 0; + decoded[outputOffset + column] = applyFilter( + filter, + source, + left, + above, + upperLeft, + ); + } + } + if (channels === 4) return decoded; + const rgba = Buffer.alloc(width * height * 4); + for ( + let source = 0, target = 0; + source < decoded.length; + source += 3, target += 4 + ) { + rgba[target] = decoded[source] ?? 0; + rgba[target + 1] = decoded[source + 1] ?? 0; + rgba[target + 2] = decoded[source + 2] ?? 0; + rgba[target + 3] = 255; + } + return rgba; +}; + +const applyFilter = ( + filter: number, + source: number, + left: number, + above: number, + upperLeft: number, +): number => { + switch (filter) { + case 0: + return source; + case 1: + return (source + left) & 0xff; + case 2: + return (source + above) & 0xff; + case 3: + return (source + Math.floor((left + above) / 2)) & 0xff; + case 4: + return (source + paeth(left, above, upperLeft)) & 0xff; + default: + throw new TypeError("Unsupported PNG filter"); + } +}; + +const paeth = (left: number, above: number, upperLeft: number): number => { + const prediction = left + above - upperLeft; + const leftDistance = Math.abs(prediction - left); + const aboveDistance = Math.abs(prediction - above); + const upperLeftDistance = Math.abs(prediction - upperLeft); + return leftDistance <= aboveDistance && leftDistance <= upperLeftDistance + ? left + : aboveDistance <= upperLeftDistance + ? above + : upperLeft; +}; + +const dimensions = ({ width, height }: DecodedPng) => ({ width, height }); + +const limitations = (): string[] => [ + "Pixel comparison does not perform OCR, semantic layout analysis, or perceptual color correction.", + "Only non-interlaced 8-bit RGB and RGBA PNG screenshots are accepted.", +]; + +const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]); diff --git a/src/browser/SensitiveTextCapture.ts b/src/browser/SensitiveTextCapture.ts new file mode 100644 index 000000000..b302157c3 --- /dev/null +++ b/src/browser/SensitiveTextCapture.ts @@ -0,0 +1,35 @@ +const SECRET_ASSIGNMENT = + /\b(authorization|api[_-]?key|access[_-]?token|refresh[_-]?token|password|passwd|secret|cookie|session)\b\s*[:=]\s*(?:Bearer\s+[A-Za-z0-9._~+/=-]+|"[^"]*"|'[^']*'|[^\s,;]+)/giu; +const BEARER = /\bBearer\s+[A-Za-z0-9._~+/=-]+/giu; +const JWT = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/gu; + +/** Redact credential-shaped substrings before approved console text is retained. */ +export const redactSensitiveText = (value: string): string => + value + .replace(SECRET_ASSIGNMENT, (_match, name: string) => `${name}=[REDACTED]`) + .replace(BEARER, "Bearer [REDACTED]") + .replace(JWT, "[REDACTED_JWT]"); + +/** Return a UTF-8-bounded prefix without splitting a code point. */ +export const boundedSensitiveText = ( + value: string, + maximumBytes: number, +): { + readonly text: string; + readonly bytes: number; + readonly truncated: boolean; +} => { + const redacted = redactSensitiveText(value); + const total = Buffer.byteLength(redacted); + if (total <= maximumBytes) + return { text: redacted, bytes: total, truncated: false }; + let text = ""; + let bytes = 0; + for (const character of redacted) { + const size = Buffer.byteLength(character); + if (bytes + size > maximumBytes) break; + text += character; + bytes += size; + } + return { text, bytes, truncated: true }; +}; diff --git a/src/browser/WebSourceMapFetcher.ts b/src/browser/WebSourceMapFetcher.ts new file mode 100644 index 000000000..e0a532bbd --- /dev/null +++ b/src/browser/WebSourceMapFetcher.ts @@ -0,0 +1,445 @@ +import { AnyMap, eachMapping } from "@jridgewell/trace-mapping"; + +import { sanitizeBrowserUrl } from "../domain/browserObservation.js"; +import type { + AnalyzeWebBundleInput, + WebBundleAnalysis, +} from "../domain/webBundleAnalysis.js"; +import { createWebTextArtifact } from "../domain/webContentArtifact.js"; + +export interface WebSourceMapRequest { + readonly scriptKey: string; + readonly declaredUrl: string; + readonly fetchUrl: string; +} + +interface SourceMapFetchHost { + readonly fetch: typeof fetch; +} + +type SourceMaps = WebBundleAnalysis["observations"]["source_maps"]; +type SourceMapItem = SourceMaps["items"][number]; + +/** Fetch and validate approved source maps without browser credentials. */ +export const fetchWebSourceMaps = async ( + requests: readonly WebSourceMapRequest[], + input: AnalyzeWebBundleInput, + signal?: AbortSignal, + host: SourceMapFetchHost = { fetch: globalThis.fetch }, +): Promise => { + const items: SourceMapItem[] = []; + let remainingBytes = input.analysis_limits.max_total_source_map_bytes; + for (const request of requests.slice( + 0, + input.analysis_limits.max_source_maps, + )) { + if (signal?.aborted === true) throw signal.reason; + if (remainingBytes === 0) break; + const fetched = await fetchOne(request, { + input, + maximumBytes: Math.min( + input.analysis_limits.max_source_map_bytes, + remainingBytes, + ), + signal, + host, + }); + items.push(fetched.item); + remainingBytes = Math.max(0, remainingBytes - fetched.bytesRead); + } + const included = items.filter(({ status }) => status === "included").length; + const dropped = requests.length - items.length; + const truncated = + dropped > 0 || items.some(({ status }) => status === "truncated"); + return { + status: truncated + ? "truncated" + : items.length === 0 + ? "unavailable" + : included === items.length + ? "included" + : included > 0 + ? "partial" + : "unavailable", + requested: requests.length, + processed: items.length, + dropped, + dropped_script_keys: requests + .slice(items.length) + .map(({ scriptKey }) => scriptKey), + items, + }; +}; + +interface SourceMapFetchResult { + readonly item: SourceMapItem; + readonly bytesRead: number; +} + +interface SourceMapFetchContext { + readonly input: AnalyzeWebBundleInput; + readonly maximumBytes: number; + readonly signal: AbortSignal | undefined; + readonly host: SourceMapFetchHost; +} + +const fetchOne = async ( + request: WebSourceMapRequest, + context: SourceMapFetchContext, +): Promise => { + const { input, maximumBytes, signal, host } = context; + const base = emptyItem(request); + if (!approvedUrl(request.fetchUrl, input.allowed_origins)) + return { + item: { + ...base, + status: "policy_filtered", + limitation: + "Declared source-map URL is outside the approved exact origins.", + }, + bytesRead: 0, + }; + try { + const response = await fetchFollowingApprovedRedirects( + request.fetchUrl, + input.allowed_origins, + signal, + host, + ); + if (response === undefined) + return { + item: { + ...base, + status: "policy_filtered", + limitation: "A source-map redirect left the approved exact origins.", + }, + bytesRead: 0, + }; + if (!response.ok) + return { + item: { + ...base, + status: "fetch_failed", + limitation: `Source-map server returned HTTP ${String(response.status)}.`, + }, + bytesRead: 0, + }; + const body = await boundedResponseText(response, maximumBytes); + return { + item: normalizeSourceMap(request, body.text, input), + bytesRead: body.bytes, + }; + } catch (cause: unknown) { + if (signal?.aborted === true) throw cause; + return { + item: { + ...base, + status: isLimitError(cause) ? "truncated" : "fetch_failed", + limitation: isLimitError(cause) + ? "Source-map response exceeded the remaining approved byte budget." + : "Source-map fetch or validation failed.", + }, + bytesRead: cause instanceof SourceMapByteLimitError ? cause.bytesRead : 0, + }; + } +}; + +const fetchFollowingApprovedRedirects = async ( + initialUrl: string, + allowedOrigins: readonly string[], + signal: AbortSignal | undefined, + host: SourceMapFetchHost, +): Promise => { + let current = initialUrl; + for (let redirect = 0; redirect <= 5; redirect += 1) { + if (!approvedUrl(current, allowedOrigins)) return undefined; + const response = await timedFetch(current, signal, host); + if (response.status < 300 || response.status >= 400) return response; + const location = response.headers.get("location"); + if (location === null) return response; + current = new URL(location, current).href; + } + throw new Error("source_map_redirect_limit"); +}; + +const timedFetch = async ( + url: string, + signal: AbortSignal | undefined, + host: SourceMapFetchHost, +): Promise => { + const timeout = AbortSignal.timeout(5_000); + return await host.fetch(url, { + method: "GET", + headers: { Accept: "application/json, application/source-map+json;q=0.9" }, + redirect: "manual", + credentials: "omit", + referrerPolicy: "no-referrer", + signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]), + }); +}; + +const boundedResponseText = async ( + response: Response, + maximumBytes: number, +): Promise<{ readonly text: string; readonly bytes: number }> => { + const declared = Number(response.headers.get("content-length")); + if (Number.isFinite(declared) && declared > maximumBytes) + throw new SourceMapByteLimitError(0); + if (response.body === null) return { text: "", bytes: 0 }; + const reader = response.body.getReader(); + const decoder = new TextDecoder("utf-8", { fatal: true }); + let bytes = 0; + let text = ""; + for (;;) { + const chunk = await reader.read(); + if (chunk.done) break; + bytes += chunk.value.byteLength; + if (bytes > maximumBytes) { + await reader.cancel(); + throw new SourceMapByteLimitError(bytes); + } + text += decoder.decode(chunk.value, { stream: true }); + } + text += decoder.decode(); + return { text, bytes }; +}; + +class SourceMapByteLimitError extends RangeError { + constructor(readonly bytesRead: number) { + super("source_map_bytes"); + } +} + +const normalizeSourceMap = ( + request: WebSourceMapRequest, + text: string, + input: AnalyzeWebBundleInput, +): SourceMapItem => { + const base = emptyItem(request); + if (!validSourceMapEnvelope(text)) + return { + ...base, + status: "invalid", + limitation: "Source-map JSON is not a bounded version 3 map.", + }; + try { + const map = new AnyMap(text, request.fetchUrl); + if (map.sources.length > input.analysis_limits.max_original_sources) + return { + ...base, + status: "truncated", + limitation: "Source map exceeds the original-source inventory limit.", + }; + const resolvedBySource = new Map(); + const originalSources = map.sources.map((source, index) => { + const content = map.sourcesContent?.[index]; + const resolved = + map.resolvedSources[index] ?? source ?? "[unknown-source]"; + if (source !== null) resolvedBySource.set(source, resolved); + return { + source: sanitizeSource(resolved), + artifact: + typeof content === "string" + ? createWebTextArtifact(content, sourceMediaType(source)) + : null, + }; + }); + const mappings: SourceMapItem["mappings"] = []; + let totalMappings = 0; + eachMapping(map, (mapping) => { + if ( + mapping.source === null || + mapping.originalLine === null || + mapping.originalColumn === null + ) + return; + totalMappings += 1; + if (mappings.length >= input.analysis_limits.max_source_map_mappings) + return; + mappings.push({ + generated_line: mapping.generatedLine, + generated_column: mapping.generatedColumn, + source: sanitizeSource( + resolvedBySource.get(mapping.source) ?? mapping.source, + ), + original_line: mapping.originalLine, + original_column: mapping.originalColumn, + name: mapping.name?.slice(0, 1_024) ?? null, + }); + }); + const modules = originalModuleEdges( + originalSources, + input.analysis_limits.max_findings, + ); + const mappingTruncated = totalMappings > mappings.length; + const limitations = [ + ...(mappingTruncated + ? [ + `Mappings were truncated from ${String(totalMappings)} to ${String(mappings.length)}.`, + ] + : []), + ...(modules.truncated + ? [ + `Original module edges were truncated to ${String(modules.edges.length)}.`, + ] + : []), + ]; + return { + ...base, + status: mappingTruncated || modules.truncated ? "truncated" : "included", + artifact: createWebTextArtifact(text, "application/source-map+json"), + original_sources: originalSources, + original_module_edges: modules.edges, + mappings, + limitation: limitations.length === 0 ? null : limitations.join(" "), + }; + } catch { + return { + ...base, + status: "invalid", + limitation: "Source-map mappings could not be decoded safely.", + }; + } +}; + +const originalModuleEdges = ( + sources: SourceMapItem["original_sources"], + maximum: number, +): { + readonly edges: SourceMapItem["original_module_edges"]; + readonly truncated: boolean; +} => { + const edges: SourceMapItem["original_module_edges"] = []; + const seen = new Set(); + for (const source of sources) { + if (source.artifact === null) continue; + for (const detector of originalImportDetectors) { + for (const match of source.artifact.text.matchAll(detector.pattern)) { + const specifier = match[1]?.slice(0, 4_096); + if (specifier === undefined) continue; + const key = `${source.source}\0${detector.kind}\0${specifier}`; + if (seen.has(key)) continue; + seen.add(key); + if (edges.length >= maximum) return { edges, truncated: true }; + edges.push({ + from_source: source.source, + kind: detector.kind, + specifier, + resolved_source: resolveOriginalSource(specifier, source.source), + }); + } + } + } + return { edges, truncated: false }; +}; + +const validSourceMapEnvelope = (text: string): boolean => { + let parsed: unknown; + try { + parsed = JSON.parse(text); + } catch { + return false; + } + if (!isRecord(parsed) || parsed.version !== 3) return false; + if (typeof parsed.mappings === "string") + return Array.isArray(parsed.sources) && Array.isArray(parsed.names); + if (!Array.isArray(parsed.sections) || parsed.sections.length > 10_000) + return false; + const pending: unknown[] = [...parsed.sections]; + let visited = 0; + while (pending.length > 0) { + const section = pending.pop(); + if (!isRecord(section) || !isRecord(section.offset) || !("map" in section)) + return false; + visited += 1; + if (visited > 10_000) return false; + const map = section.map; + if (!isRecord(map) || map.version !== 3) return false; + if (Array.isArray(map.sections)) pending.push(...map.sections); + else if ( + typeof map.mappings !== "string" || + !Array.isArray(map.sources) || + !Array.isArray(map.names) + ) + return false; + } + return true; +}; + +const approvedUrl = ( + value: string, + allowedOrigins: readonly string[], +): boolean => { + try { + const parsed = new URL(value); + return ( + (parsed.protocol === "http:" || parsed.protocol === "https:") && + parsed.username === "" && + parsed.password === "" && + allowedOrigins.includes(parsed.origin) + ); + } catch { + return false; + } +}; + +const emptyItem = (request: WebSourceMapRequest): SourceMapItem => ({ + script_key: request.scriptKey, + declared_url: request.declaredUrl, + status: "fetch_failed", + artifact: null, + original_sources: [], + original_module_edges: [], + mappings: [], + limitation: null, +}); + +const sanitizeSource = (value: string): string => { + const bounded = value.slice(0, 4_096); + try { + const parsed = new URL(bounded); + return parsed.protocol === "http:" || parsed.protocol === "https:" + ? sanitizeBrowserUrl(parsed.href).url + : `${parsed.protocol}//${parsed.host}${parsed.pathname}`; + } catch { + return bounded.split("#", 1)[0]?.split("?", 1)[0] ?? ""; + } +}; + +const resolveOriginalSource = ( + specifier: string, + base: string, +): string | null => { + try { + return sanitizeSource(new URL(specifier, base).href); + } catch { + return null; + } +}; + +const sourceMediaType = (source: string | null): string => + source?.endsWith(".ts") || source?.endsWith(".tsx") + ? "text/typescript" + : "text/javascript"; + +const isRecord = (value: unknown): value is Readonly> => + typeof value === "object" && value !== null && !Array.isArray(value); + +const isLimitError = (value: unknown): value is RangeError => + value instanceof RangeError; + +const originalImportDetectors = [ + { + kind: "static_import" as const, + pattern: + /\b(?:import|export)\s+(?:[^'"\n]*?\s+from\s+)?["']([^"'\n]+)["']/gu, + }, + { + kind: "dynamic_import" as const, + pattern: /\bimport\s*\(\s*["']([^"'\n]+)["']\s*\)/gu, + }, + { + kind: "require" as const, + pattern: /\brequire\s*\(\s*["']([^"'\n]+)["']\s*\)/gu, + }, +] as const; diff --git a/src/catalogIdentity.ts b/src/catalogIdentity.ts index 3778f080b..2e5b21215 100644 --- a/src/catalogIdentity.ts +++ b/src/catalogIdentity.ts @@ -38,6 +38,14 @@ export const CLI_COMMAND_NAMES = [ "policy", "list-browser-targets", "inspect-web-page", + "analyze-web-bundle", + "observe-web-session", + "discover-webmcp-tools", + "compare-web-captures", + "capture-web-screenshot", + "compare-web-screenshots", + "list-electron-targets", + "inspect-electron-page", ] as const; const toolCatalog = TOOL_CONTRACTS.map((contract) => ({ diff --git a/src/cli.ts b/src/cli.ts index ba7f2ec19..a93c699f0 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -28,6 +28,8 @@ import { projectReferenceSourceImportError } from "./application/ReferenceSource import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js"; import { registerPolicyCommands } from "./cliPolicyCommands.js"; import { registerBrowserCommands } from "./cliBrowserCommands.js"; +import { registerAdvancedBrowserCommands } from "./cliBrowserAdvancedCommands.js"; +import { registerElectronCommands } from "./cliElectronCommands.js"; /** * Build the one-shot Incur CLI without starting Hopper at import time. @@ -75,6 +77,8 @@ export const createCli = (): ReturnType => { registerProcessCommands(cli, logger); registerPolicyCommands(cli, logger); registerBrowserCommands(cli, logger); + registerAdvancedBrowserCommands(cli, logger); + registerElectronCommands(cli, logger); return cli; }; diff --git a/src/cliBrowserAdvancedCommands.ts b/src/cliBrowserAdvancedCommands.ts new file mode 100644 index 000000000..cb996dd23 --- /dev/null +++ b/src/cliBrowserAdvancedCommands.ts @@ -0,0 +1,220 @@ +import { Cli, z } from "incur"; + +import { + captureWebScreenshot, + compareWebCaptureEvidence, + compareWebScreenshotEvidence, + discoverWebMcpTools, +} from "./application/BrowserObservationService.js"; +import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js"; +import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js"; +import { logCliCommand } from "./cliLogging.js"; +import { parseConfig } from "./config.js"; +import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js"; +import { compareWebCapturesInputSchema } from "./domain/webCaptureDiff.js"; +import { discoverWebMcpToolsInputSchema } from "./domain/webMcpDiscovery.js"; +import { + captureWebScreenshotInputSchema, + compareWebScreenshotsInputSchema, +} from "./domain/webScreenshot.js"; +import type { JsonValue } from "./domain/jsonValue.js"; +import type { Logger } from "./logger.js"; + +const scopeOptions = { + allowedOrigins: z.array(z.string().min(1)).optional(), + approved: z.boolean().default(false), +}; + +/** Register WebMCP, capture-diff, and screenshot CLI equivalents. */ +export const registerAdvancedBrowserCommands = ( + cli: ReturnType, + logger: Logger, +): void => { + registerWebMcp(cli, logger); + registerCaptureDiff(cli, logger); + registerScreenshot(cli, logger); + registerScreenshotDiff(cli, logger); +}; + +const registerWebMcp = ( + cli: ReturnType, + logger: Logger, +): void => { + cli.command("discover-webmcp-tools", { + description: "Passively discover page-declared WebMCP tools", + args: z.object({ endpoint: z.string(), targetId: z.string() }), + options: z.object({ + ...scopeOptions, + observationMs: z.number().int().min(0).max(10_000).default(100), + maxTools: z.number().int().min(1).max(5_000).default(500), + maxSchemaBytes: z + .number() + .int() + .min(1) + .max(1_024 * 1_024) + .default(256 * 1_024), + maxSchemaNodes: z.number().int().min(1).max(100_000).default(5_000), + maxSchemaDepth: z.number().int().min(1).max(100).default(20), + }), + run: ({ args, options }) => + logCliCommand(logger, "discover-webmcp-tools", async () => { + const context = await browserContext(); + if (!context.ok) return context.error; + const parsed = discoverWebMcpToolsInputSchema.safeParse({ + cdp_endpoint: args.endpoint, + allowed_origins: + options.allowedOrigins ?? context.allowedBrowserOrigins, + target_id: args.targetId, + approved: options.approved, + observation_ms: options.observationMs, + max_tools: options.maxTools, + max_schema_bytes: options.maxSchemaBytes, + max_schema_nodes: options.maxSchemaNodes, + max_schema_depth: options.maxSchemaDepth, + }); + if (!parsed.success) return inputError("discover_webmcp_tools"); + const result = await discoverWebMcpTools( + context.provider, + context.authority, + parsed.data, + ); + return result.ok ? result.value : cliError(result.error); + }), + }); +}; + +const registerCaptureDiff = ( + cli: ReturnType, + logger: Logger, +): void => { + cli.command("compare-web-captures", { + description: "Compare two normalized web capture JSON values", + args: z.object({ beforeJson: z.string(), afterJson: z.string() }), + options: z.object({ + maxChanges: z.number().int().min(1).max(20_000).default(2_000), + }), + run: ({ args, options }) => + logCliCommand(logger, "compare-web-captures", async () => { + const before = parseJson(args.beforeJson); + const after = parseJson(args.afterJson); + const parsed = compareWebCapturesInputSchema.safeParse({ + before, + after, + max_changes: options.maxChanges, + }); + if (!parsed.success) return inputError("compare_web_captures"); + const result = await compareWebCaptureEvidence( + new CdpBrowserProvider(), + parsed.data, + ); + return result.ok ? result.value : cliError(result.error); + }), + }); +}; + +const registerScreenshot = ( + cli: ReturnType, + logger: Logger, +): void => { + cli.command("capture-web-screenshot", { + description: "Capture an explicitly approved visible page viewport", + args: z.object({ endpoint: z.string(), targetId: z.string() }), + options: z.object({ + ...scopeOptions, + screenshotApproved: z.boolean().default(false), + maximumImageBytes: z + .number() + .int() + .min(1) + .max(8 * 1_024 * 1_024) + .default(4 * 1_024 * 1_024), + }), + run: ({ args, options }) => + logCliCommand(logger, "capture-web-screenshot", async () => { + const context = await browserContext(); + if (!context.ok) return context.error; + const parsed = captureWebScreenshotInputSchema.safeParse({ + cdp_endpoint: args.endpoint, + allowed_origins: + options.allowedOrigins ?? context.allowedBrowserOrigins, + target_id: args.targetId, + approved: options.approved, + screenshot_approved: options.screenshotApproved, + maximum_image_bytes: options.maximumImageBytes, + }); + if (!parsed.success) return inputError("capture_web_screenshot"); + const result = await captureWebScreenshot( + context.provider, + context.authority, + parsed.data, + ); + return result.ok ? result.value : cliError(result.error); + }), + }); +}; + +const registerScreenshotDiff = ( + cli: ReturnType, + logger: Logger, +): void => { + cli.command("compare-web-screenshots", { + description: "Compare two self-verifying PNG artifact JSON values", + args: z.object({ beforeJson: z.string(), afterJson: z.string() }), + options: z.object({ + channelThreshold: z.number().int().min(0).max(255).default(0), + maximumPixels: z + .number() + .int() + .min(1) + .max(32_000_000) + .default(16_000_000), + }), + run: ({ args, options }) => + logCliCommand(logger, "compare-web-screenshots", async () => { + const parsed = compareWebScreenshotsInputSchema.safeParse({ + before: parseJson(args.beforeJson), + after: parseJson(args.afterJson), + channel_threshold: options.channelThreshold, + maximum_pixels: options.maximumPixels, + }); + if (!parsed.success) return inputError("compare_web_screenshots"); + const result = await compareWebScreenshotEvidence( + new CdpBrowserProvider(), + parsed.data, + ); + return result.ok ? result.value : cliError(result.error); + }), + }); +}; + +const browserContext = async () => { + const config = parseConfig(process.env); + if (!config.ok) return { ok: false as const, error: cliError(config.error) }; + const authority = await loadConfiguredPermissionAuthority(config.value); + if (!authority.ok) + return { ok: false as const, error: cliError(authority.error) }; + return { + ok: true as const, + authority: authority.value, + provider: new CdpBrowserProvider(), + allowedBrowserOrigins: config.value.browserAllowedOrigins, + }; +}; + +const parseJson = (value: string): unknown => { + try { + return JSON.parse(value); + } catch { + return undefined; + } +}; + +const inputError = (operation: string): JsonValue => + cliError(new AnalysisInputError(operation)); + +const cliError = ( + error: Parameters[0], +): JsonValue => ({ + error: "Browser observation failed", + ...projectAnalysisError(error), +}); diff --git a/src/cliBrowserCommands.ts b/src/cliBrowserCommands.ts index b873df441..298393e10 100644 --- a/src/cliBrowserCommands.ts +++ b/src/cliBrowserCommands.ts @@ -1,8 +1,10 @@ import { Cli, z } from "incur"; import { + analyzeWebBundle, inspectWebPage, listBrowserTargets, + observeWebSession, } from "./application/BrowserObservationService.js"; import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js"; import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js"; @@ -12,6 +14,8 @@ import { inspectWebPageInputSchema, listBrowserTargetsInputSchema, } from "./domain/browserObservation.js"; +import { analyzeWebBundleInputSchema } from "./domain/webBundleAnalysis.js"; +import { observeWebSessionInputSchema } from "./domain/browserSession.js"; import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js"; import type { JsonValue } from "./domain/jsonValue.js"; import type { Logger } from "./logger.js"; @@ -33,6 +37,8 @@ export const registerBrowserCommands = ( ): void => { registerTargetList(cli, logger); registerPageInspection(cli, logger); + registerBundleAnalysis(cli, logger); + registerObservationSession(cli, logger); }; const registerTargetList = ( @@ -86,11 +92,30 @@ const registerPageInspection = ( options: z.object({ ...browserScopeOptions, observationMs: z.number().int().min(0).max(10_000).default(500), + includeAccessibilityText: z.boolean().default(false), + includeConsoleText: z.boolean().default(false), + consoleTextApproved: z.boolean().default(false), + includeJsonBodyShapes: z.boolean().default(false), + jsonBodySchemaApproved: z.boolean().default(false), + includeWebsocketShapes: z.boolean().default(false), + websocketShapeApproved: z.boolean().default(false), includeScriptSources: z.boolean().default(false), includeStorageKeys: z.boolean().default(false), maxFrames: z.number().int().min(1).max(1_000).default(200), maxDomNodes: z.number().int().min(1).max(10_000).default(2_000), maxAxNodes: z.number().int().min(1).max(10_000).default(2_000), + maxAxTextFieldBytes: z + .number() + .int() + .min(1) + .max(16 * 1_024) + .default(1_024), + maxTotalAxTextBytes: z + .number() + .int() + .min(1) + .max(1_024 * 1_024) + .default(64 * 1_024), maxScripts: z.number().int().min(1).max(1_000).default(200), maxResources: z.number().int().min(1).max(10_000).default(2_000), maxWorkers: z.number().int().min(1).max(5_000).default(500), @@ -109,7 +134,45 @@ const registerPageInspection = ( .default(4 * 1_024 * 1_024), maxNetworkEvents: z.number().int().min(1).max(10_000).default(1_000), maxConsoleEvents: z.number().int().min(1).max(2_000).default(200), + maxConsoleTextFieldBytes: z + .number() + .int() + .min(1) + .max(16 * 1_024) + .default(1_024), + maxTotalConsoleTextBytes: z + .number() + .int() + .min(1) + .max(1_024 * 1_024) + .default(64 * 1_024), + maxJsonBodyBytes: z + .number() + .int() + .min(1) + .max(4 * 1_024 * 1_024) + .default(1_024 * 1_024), + maxTotalJsonBodyBytes: z + .number() + .int() + .min(1) + .max(16 * 1_024 * 1_024) + .default(4 * 1_024 * 1_024), + maxJsonShapeNodes: z.number().int().min(1).max(100_000).default(5_000), + maxJsonShapeDepth: z.number().int().min(1).max(100).default(20), maxWebsocketEvents: z.number().int().min(1).max(5_000).default(500), + maxWebsocketShapeBytes: z + .number() + .int() + .min(1) + .max(1_024 * 1_024) + .default(64 * 1_024), + maxTotalWebsocketShapeBytes: z + .number() + .int() + .min(1) + .max(16 * 1_024 * 1_024) + .default(1_024 * 1_024), }), run: ({ args, options }) => logCliCommand(logger, "inspect-web-page", async () => { @@ -122,12 +185,21 @@ const registerPageInspection = ( approved: options.approved, target_id: args.targetId, observation_ms: options.observationMs, + include_accessibility_text: options.includeAccessibilityText, + include_console_text: options.includeConsoleText, + console_text_approved: options.consoleTextApproved, + include_json_body_shapes: options.includeJsonBodyShapes, + json_body_schema_approved: options.jsonBodySchemaApproved, + include_websocket_shapes: options.includeWebsocketShapes, + websocket_shape_approved: options.websocketShapeApproved, include_script_sources: options.includeScriptSources, include_storage_keys: options.includeStorageKeys, limits: { max_frames: options.maxFrames, max_dom_nodes: options.maxDomNodes, max_ax_nodes: options.maxAxNodes, + max_ax_text_field_bytes: options.maxAxTextFieldBytes, + max_total_ax_text_bytes: options.maxTotalAxTextBytes, max_scripts: options.maxScripts, max_resources: options.maxResources, max_workers: options.maxWorkers, @@ -136,7 +208,16 @@ const registerPageInspection = ( max_total_script_source_bytes: options.maxTotalScriptSourceBytes, max_network_events: options.maxNetworkEvents, max_console_events: options.maxConsoleEvents, + max_console_text_field_bytes: options.maxConsoleTextFieldBytes, + max_total_console_text_bytes: options.maxTotalConsoleTextBytes, + max_json_body_bytes: options.maxJsonBodyBytes, + max_total_json_body_bytes: options.maxTotalJsonBodyBytes, + max_json_shape_nodes: options.maxJsonShapeNodes, + max_json_shape_depth: options.maxJsonShapeDepth, max_websocket_events: options.maxWebsocketEvents, + max_websocket_shape_bytes: options.maxWebsocketShapeBytes, + max_total_websocket_shape_bytes: + options.maxTotalWebsocketShapeBytes, }, }); if (!parsed.success) @@ -151,6 +232,122 @@ const registerPageInspection = ( }); }; +const registerBundleAnalysis = ( + cli: ReturnType, + logger: Logger, +): void => { + cli.command("analyze-web-bundle", { + description: "Capture and statically analyze an approved page bundle", + args: z.object({ + endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"), + targetId: z.string().describe("Target ID from list-browser-targets"), + }), + options: z.object({ + ...browserScopeOptions, + sourceCaptureApproved: z.boolean().default(false), + observationMs: z.number().int().min(0).max(10_000).default(500), + fetchSourceMaps: z.boolean().default(false), + sourceMapFetchApproved: z.boolean().default(false), + maxFindings: z.number().int().min(1).max(10_000).default(1_000), + maxAstNodes: z.number().int().min(1).max(2_000_000).default(250_000), + maxSourceMaps: z.number().int().min(1).max(1_000).default(100), + maxSourceMapBytes: z + .number() + .int() + .min(1) + .max(16 * 1_024 * 1_024) + .default(4 * 1_024 * 1_024), + maxTotalSourceMapBytes: z + .number() + .int() + .min(1) + .max(64 * 1_024 * 1_024) + .default(16 * 1_024 * 1_024), + maxSourceMapMappings: z + .number() + .int() + .min(1) + .max(100_000) + .default(10_000), + maxOriginalSources: z.number().int().min(1).max(20_000).default(2_000), + }), + run: ({ args, options }) => + logCliCommand(logger, "analyze-web-bundle", async () => { + const context = await browserContext(); + if (!context.ok) return context.error; + const parsed = analyzeWebBundleInputSchema.safeParse({ + cdp_endpoint: args.endpoint, + allowed_origins: + options.allowedOrigins ?? context.allowedBrowserOrigins, + approved: options.approved, + target_id: args.targetId, + observation_ms: options.observationMs, + include_script_sources: true, + source_capture_approved: options.sourceCaptureApproved, + fetch_source_maps: options.fetchSourceMaps, + source_map_fetch_approved: options.sourceMapFetchApproved, + analysis_limits: { + max_findings: options.maxFindings, + max_ast_nodes: options.maxAstNodes, + max_source_maps: options.maxSourceMaps, + max_source_map_bytes: options.maxSourceMapBytes, + max_total_source_map_bytes: options.maxTotalSourceMapBytes, + max_source_map_mappings: options.maxSourceMapMappings, + max_original_sources: options.maxOriginalSources, + }, + }); + if (!parsed.success) + return cliError(new AnalysisInputError("analyze_web_bundle")); + const result = await analyzeWebBundle( + context.provider, + context.authority, + parsed.data, + ); + return result.ok ? result.value : cliError(result.error); + }), + }); +}; + +const registerObservationSession = ( + cli: ReturnType, + logger: Logger, +): void => { + cli.command("observe-web-session", { + description: "Observe user-driven page navigation during a bounded window", + args: z.object({ + endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"), + targetId: z.string().describe("Target ID from list-browser-targets"), + }), + options: z.object({ + ...browserScopeOptions, + observationMs: z.number().int().min(1).max(60_000).default(10_000), + maxTimelineEvents: z.number().int().min(1).max(20_000).default(2_000), + }), + run: ({ args, options }) => + logCliCommand(logger, "observe-web-session", async () => { + const context = await browserContext(); + if (!context.ok) return context.error; + const parsed = observeWebSessionInputSchema.safeParse({ + cdp_endpoint: args.endpoint, + allowed_origins: + options.allowedOrigins ?? context.allowedBrowserOrigins, + target_id: args.targetId, + approved: options.approved, + observation_ms: options.observationMs, + max_timeline_events: options.maxTimelineEvents, + }); + if (!parsed.success) + return cliError(new AnalysisInputError("observe_web_session")); + const result = await observeWebSession( + context.provider, + context.authority, + parsed.data, + ); + return result.ok ? result.value : cliError(result.error); + }), + }); +}; + const browserContext = async () => { const config = parseConfig(process.env); if (!config.ok) return { ok: false as const, error: cliError(config.error) }; diff --git a/src/cliElectronCommands.ts b/src/cliElectronCommands.ts new file mode 100644 index 000000000..cf6309bbe --- /dev/null +++ b/src/cliElectronCommands.ts @@ -0,0 +1,141 @@ +import { Cli, z } from "incur"; + +import { + inspectElectronPage, + listElectronTargets, +} from "./application/ElectronObservationService.js"; +import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js"; +import { CdpElectronProvider } from "./browser/CdpElectronProvider.js"; +import { logCliCommand } from "./cliLogging.js"; +import { parseConfig } from "./config.js"; +import { + inspectElectronPageInputSchema, + listElectronTargetsInputSchema, +} from "./domain/electronObservation.js"; +import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js"; +import type { JsonValue } from "./domain/jsonValue.js"; +import type { Logger } from "./logger.js"; + +const scopeOptions = { + allowedFileRoots: z + .array(z.string().min(1)) + .optional() + .describe("Filesystem roots; defaults to REA_ELECTRON_FILE_ROOTS_JSON"), + approved: z.boolean().default(false), +}; + +/** Register CLI equivalents of the Electron MCP tools. */ +export const registerElectronCommands = ( + cli: ReturnType, + logger: Logger, +): void => { + cli.command("list-electron-targets", { + description: "List root-confined file pages from Electron CDP", + args: z.object({ endpoint: z.string() }), + options: z.object({ + ...scopeOptions, + offset: z.number().int().min(0).default(0), + limit: z.number().int().min(1).max(200).default(100), + }), + run: ({ args, options }) => + logCliCommand(logger, "list-electron-targets", async () => { + const context = await electronContext(); + if (!context.ok) return context.error; + const parsed = listElectronTargetsInputSchema.safeParse({ + cdp_endpoint: args.endpoint, + allowed_file_roots: + options.allowedFileRoots ?? context.allowedFileRoots, + approved: options.approved, + offset: options.offset, + limit: options.limit, + }); + if (!parsed.success) return inputError("list_electron_targets"); + const result = await listElectronTargets( + context.provider, + context.authority, + parsed.data, + ); + return result.ok ? result.value : cliError(result.error); + }), + }); + cli.command("inspect-electron-page", { + description: "Passively inspect one root-confined Electron file page", + args: z.object({ endpoint: z.string(), targetId: z.string() }), + options: z.object({ + ...scopeOptions, + observationMs: z.number().int().min(0).max(10_000).default(100), + includeScriptSources: z.boolean().default(false), + sourceCaptureApproved: z.boolean().default(false), + maxFrames: z.number().int().min(1).max(1_000).default(200), + maxDomNodes: z.number().int().min(1).max(10_000).default(2_000), + maxScripts: z.number().int().min(1).max(2_000).default(500), + maxResources: z.number().int().min(1).max(10_000).default(2_000), + maxScriptSourceBytes: z + .number() + .int() + .min(1) + .max(4 * 1_024 * 1_024) + .default(1_024 * 1_024), + maxTotalScriptSourceBytes: z + .number() + .int() + .min(1) + .max(16 * 1_024 * 1_024) + .default(4 * 1_024 * 1_024), + }), + run: ({ args, options }) => + logCliCommand(logger, "inspect-electron-page", async () => { + const context = await electronContext(); + if (!context.ok) return context.error; + const parsed = inspectElectronPageInputSchema.safeParse({ + cdp_endpoint: args.endpoint, + allowed_file_roots: + options.allowedFileRoots ?? context.allowedFileRoots, + target_id: args.targetId, + approved: options.approved, + observation_ms: options.observationMs, + include_script_sources: options.includeScriptSources, + source_capture_approved: options.sourceCaptureApproved, + limits: { + max_frames: options.maxFrames, + max_dom_nodes: options.maxDomNodes, + max_scripts: options.maxScripts, + max_resources: options.maxResources, + max_script_source_bytes: options.maxScriptSourceBytes, + max_total_script_source_bytes: options.maxTotalScriptSourceBytes, + }, + }); + if (!parsed.success) return inputError("inspect_electron_page"); + const result = await inspectElectronPage( + context.provider, + context.authority, + parsed.data, + ); + return result.ok ? result.value : cliError(result.error); + }), + }); +}; + +const electronContext = async () => { + const config = parseConfig(process.env); + if (!config.ok) return { ok: false as const, error: cliError(config.error) }; + const authority = await loadConfiguredPermissionAuthority(config.value); + if (!authority.ok) + return { ok: false as const, error: cliError(authority.error) }; + return { + ok: true as const, + authority: authority.value, + provider: new CdpElectronProvider(), + allowedFileRoots: config.value.electronFileRoots, + }; +}; + +const inputError = (operation: string): JsonValue => + cliError(new AnalysisInputError(operation)); + +const cliError = ( + error: Parameters[0], +): JsonValue => ({ + error: "Electron observation failed", + ...projectAnalysisError(error), +}); diff --git a/src/cliPolicyCommands.ts b/src/cliPolicyCommands.ts index 0ed60785b..d28e2abe0 100644 --- a/src/cliPolicyCommands.ts +++ b/src/cliPolicyCommands.ts @@ -17,6 +17,7 @@ import type { Logger } from "./logger.js"; const capabilitySchema = z.enum([ "process_capture", "browser_observe", + "electron_observe", "evidence_read", "evidence_write", "investigation_input", diff --git a/src/config.ts b/src/config.ts index d8ab4b457..109e5a6e9 100644 --- a/src/config.ts +++ b/src/config.ts @@ -14,6 +14,7 @@ import { browserEndpointSchema, browserOriginSchema, } from "./domain/browserObservation.js"; +import { electronFileRootsSchema } from "./domain/electronObservation.js"; const DEFAULT_HOPPER_LAUNCHER_PATH = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper"; @@ -38,6 +39,9 @@ export interface AppConfig { readonly browserObservationEnabled: boolean; readonly browserCdpEndpoints: readonly string[]; readonly browserAllowedOrigins: readonly string[]; + readonly electronObservationEnabled: boolean; + readonly electronCdpEndpoints: readonly string[]; + readonly electronFileRoots: readonly string[]; readonly permissionCeilings: readonly PermissionCeiling[]; readonly administratorPermissionGrants: readonly PermissionGrant[]; readonly permissionProjectRoot: string | undefined; @@ -76,6 +80,9 @@ const environmentSchema = z REA_BROWSER_OBSERVE_ENABLED: z.enum(["true", "false"]).default("false"), REA_BROWSER_CDP_ENDPOINTS_JSON: z.string().default("[]"), REA_BROWSER_ALLOWED_ORIGINS_JSON: z.string().default("[]"), + REA_ELECTRON_OBSERVE_ENABLED: z.enum(["true", "false"]).default("false"), + REA_ELECTRON_CDP_ENDPOINTS_JSON: z.string().default("[]"), + REA_ELECTRON_FILE_ROOTS_JSON: z.string().default("[]"), REA_PERMISSION_PROJECT_ROOT: z.string().min(1).optional(), REA_PERMISSION_PROJECT_STORE: z.string().min(1).optional(), }) @@ -133,6 +140,31 @@ const parseBrowserArray = ( } }; +const parseElectronFileRoots = ( + encoded: string, +): Result => { + try { + const decoded: unknown = JSON.parse(encoded); + if (Array.isArray(decoded) && decoded.length === 0) return ok([]); + const parsed = electronFileRootsSchema.safeParse(decoded); + return parsed.success + ? ok(parsed.data) + : err( + new ConfigurationError( + "REA_ELECTRON_FILE_ROOTS_JSON must encode absolute roots", + { cause: parsed.error }, + ), + ); + } catch (cause: unknown) { + return err( + new ConfigurationError( + "REA_ELECTRON_FILE_ROOTS_JSON must be valid JSON", + { cause }, + ), + ); + } +}; + const filePolicy = (roots: readonly string[]): EvidenceFilePolicy => ({ roots, maxBytes: 64 * 1024 * 1024, @@ -266,6 +298,17 @@ export const parseConfig = ( 32, ); if (!browserOrigins.ok) return browserOrigins; + const electronEndpoints = parseBrowserArray( + parsedEnvironment.data.REA_ELECTRON_CDP_ENDPOINTS_JSON, + "REA_ELECTRON_CDP_ENDPOINTS_JSON", + browserEndpointSchema, + 16, + ); + if (!electronEndpoints.ok) return electronEndpoints; + const electronFileRoots = parseElectronFileRoots( + parsedEnvironment.data.REA_ELECTRON_FILE_ROOTS_JSON, + ); + if (!electronFileRoots.ok) return electronFileRoots; const permissionCeilings = [ ...(parsedEnvironment.data.REA_PROCESS_CAPTURE_ENABLED === "true" ? [ @@ -297,6 +340,14 @@ export const parseConfig = ( }), ] : []), + ...(parsedEnvironment.data.REA_ELECTRON_OBSERVE_ENABLED === "true" + ? [ + permissionScope("electron_observe", electronFileRoots.value, { + origins: electronEndpoints.value, + network: "loopback", + }), + ] + : []), ...(parsedEnvironment.data.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true" ? [permissionScope("native_mount", [], { mount: true })] : []), @@ -336,6 +387,10 @@ export const parseConfig = ( parsedEnvironment.data.REA_BROWSER_OBSERVE_ENABLED === "true", browserCdpEndpoints: browserEndpoints.value, browserAllowedOrigins: browserOrigins.value, + electronObservationEnabled: + parsedEnvironment.data.REA_ELECTRON_OBSERVE_ENABLED === "true", + electronCdpEndpoints: electronEndpoints.value, + electronFileRoots: electronFileRoots.value, permissionCeilings, administratorPermissionGrants: administratorGrants(permissionCeilings), permissionProjectRoot: parsedEnvironment.data.REA_PERMISSION_PROJECT_ROOT, diff --git a/src/contracts/browserToolContracts.ts b/src/contracts/browserToolContracts.ts index 40d6592f1..2d9b883bb 100644 --- a/src/contracts/browserToolContracts.ts +++ b/src/contracts/browserToolContracts.ts @@ -1,4 +1,5 @@ import type { ToolContract } from "./toolContracts.js"; +import { z } from "zod"; import { evidenceSchema } from "../domain/evidence.js"; import { browserTargetListSchema, @@ -6,8 +7,30 @@ import { listBrowserTargetsInputSchema, webPageInspectionSchema, } from "../domain/browserObservation.js"; +import { + analyzeWebBundleInputSchema, + webBundleAnalysisSchema, +} from "../domain/webBundleAnalysis.js"; +import { + observeWebSessionInputSchema, + webObservationSessionSchema, +} from "../domain/browserSession.js"; +import { + discoverWebMcpToolsInputSchema, + webMcpDiscoverySchema, +} from "../domain/webMcpDiscovery.js"; +import { + compareWebCapturesInputSchema, + webCaptureDiffSchema, +} from "../domain/webCaptureDiff.js"; +import { + captureWebScreenshotInputSchema, + compareWebScreenshotsInputSchema, + webScreenshotDiffSchema, + webScreenshotSchema, +} from "../domain/webScreenshot.js"; -const evidenceResult = (schema: typeof browserTargetListSchema) => +const evidenceResult = (schema: Schema) => evidenceSchema .omit({ normalized_result: true }) .extend({ normalized_result: schema }); @@ -15,6 +38,16 @@ const listOutputSchema = evidenceResult(browserTargetListSchema); const inspectionOutputSchema = evidenceSchema .omit({ normalized_result: true }) .extend({ normalized_result: webPageInspectionSchema }); +const bundleOutputSchema = evidenceSchema + .omit({ normalized_result: true }) + .extend({ normalized_result: webBundleAnalysisSchema }); +const observationSessionOutputSchema = evidenceSchema + .omit({ normalized_result: true }) + .extend({ normalized_result: webObservationSessionSchema }); +const webMcpOutputSchema = evidenceResult(webMcpDiscoverySchema); +const captureDiffOutputSchema = evidenceResult(webCaptureDiffSchema); +const screenshotOutputSchema = evidenceResult(webScreenshotSchema); +const screenshotDiffOutputSchema = evidenceResult(webScreenshotDiffSchema); const endpoint = "http://127.0.0.1:9222"; const origin = "https://app.example.test"; @@ -69,12 +102,21 @@ export const BROWSER_TOOL_CONTRACTS = [ approved: true, target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS", observation_ms: 500, + include_accessibility_text: false, + include_console_text: false, + console_text_approved: false, + include_json_body_shapes: false, + json_body_schema_approved: false, + include_websocket_shapes: false, + websocket_shape_approved: false, include_script_sources: false, include_storage_keys: false, limits: { max_frames: 200, max_dom_nodes: 2_000, max_ax_nodes: 2_000, + max_ax_text_field_bytes: 1_024, + max_total_ax_text_bytes: 65_536, max_scripts: 200, max_resources: 2_000, max_workers: 500, @@ -83,10 +125,296 @@ export const BROWSER_TOOL_CONTRACTS = [ max_total_script_source_bytes: 4_194_304, max_network_events: 1_000, max_console_events: 200, + max_console_text_field_bytes: 1_024, + max_total_console_text_bytes: 65_536, + max_json_body_bytes: 1_048_576, + max_total_json_body_bytes: 4_194_304, + max_json_shape_nodes: 5_000, + max_json_shape_depth: 20, max_websocket_events: 500, + max_websocket_shape_bytes: 65_536, + max_total_websocket_shape_bytes: 1_048_576, }, }, }, ], }, + { + name: "analyze_web_bundle", + description: + "Capture explicitly approved JavaScript source from one approved CDP page and statically derive a bounded chunk graph, route and endpoint candidates, vendor fingerprints, page-declared WebMCP metadata, and optional separately approved source-map evidence. JavaScript is parsed but never executed.", + kind: "browser-provider", + inputSchema: analyzeWebBundleInputSchema, + outputSchema: bundleOutputSchema, + annotations: { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: true, + }, + examples: [ + { + title: "Analyze an approved page bundle", + input: { + cdp_endpoint: endpoint, + allowed_origins: [origin], + approved: true, + target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS", + observation_ms: 500, + include_accessibility_text: false, + include_script_sources: true, + include_storage_keys: false, + source_capture_approved: true, + fetch_source_maps: false, + source_map_fetch_approved: false, + analysis_limits: { + max_findings: 1_000, + max_ast_nodes: 250_000, + max_source_maps: 100, + max_source_map_bytes: 4_194_304, + max_total_source_map_bytes: 16_777_216, + max_source_map_mappings: 10_000, + max_original_sources: 2_000, + }, + }, + }, + ], + }, + { + name: "observe_web_session", + description: + "Arm a bounded CDP observation window while the user operates the page. Allows approved same-origin reload and SPA navigation, records ordered navigation, redirect, lifecycle, and failure metadata, and stops before retaining an out-of-policy destination.", + kind: "browser-provider", + inputSchema: observeWebSessionInputSchema, + outputSchema: observationSessionOutputSchema, + annotations: { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: false, + openWorldHint: true, + }, + examples: [ + { + title: "Observe one external user action", + input: { + cdp_endpoint: endpoint, + allowed_origins: [origin], + target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS", + approved: true, + observation_ms: 10_000, + max_timeline_events: 2_000, + }, + }, + ], + }, + { + name: "discover_webmcp_tools", + description: + "Passively inventory page-registered WebMCP tools using the experimental CDP WebMCP domain. Metadata is bounded and page-declared-untrusted; REA never registers or invokes discovered tools.", + kind: "browser-provider", + inputSchema: discoverWebMcpToolsInputSchema, + outputSchema: webMcpOutputSchema, + annotations: { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: true, + }, + examples: [ + { + title: "Discover current WebMCP declarations", + input: { + cdp_endpoint: endpoint, + allowed_origins: [origin], + target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS", + approved: true, + observation_ms: 100, + max_tools: 500, + max_schema_bytes: 262_144, + max_schema_nodes: 5_000, + max_schema_depth: 20, + }, + }, + ], + }, + { + name: "compare_web_captures", + description: + "Compare two normalized web captures across DOM, scripts, resources, network, safe metadata, and optional WebMCP inventories. Stable observed changes are distinguished from unknown absence caused by incomplete capture coverage.", + kind: "browser-provider", + inputSchema: compareWebCapturesInputSchema, + outputSchema: captureDiffOutputSchema, + annotations: { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: false, + }, + examples: [ + { + title: "Compare two normalized captures", + input: { + before: { inspection: exampleInspection() }, + after: { inspection: exampleInspection() }, + max_changes: 2_000, + }, + }, + ], + }, + { + name: "capture_web_screenshot", + description: + "Capture the current visible viewport of one approved page as a bounded, content-addressed PNG artifact. Screenshot capture requires separate explicit approval and never scrolls, navigates, or evaluates page JavaScript.", + kind: "browser-provider", + inputSchema: captureWebScreenshotInputSchema, + outputSchema: screenshotOutputSchema, + annotations: { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: false, + openWorldHint: true, + }, + examples: [ + { + title: "Capture an approved viewport", + input: { + cdp_endpoint: endpoint, + allowed_origins: [origin], + target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS", + approved: true, + screenshot_approved: true, + maximum_image_bytes: 4_194_304, + }, + }, + ], + }, + { + name: "compare_web_screenshots", + description: + "Compare two self-verifying PNG screenshot artifacts with bounded local pixel metrics. Returns exact changed-pixel ratios and channel deltas without OCR or external services.", + kind: "browser-provider", + inputSchema: compareWebScreenshotsInputSchema, + outputSchema: screenshotDiffOutputSchema, + annotations: { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: false, + }, + examples: [ + { + title: "Compare two screenshot artifacts", + input: { + before: exampleScreenshot(), + after: exampleScreenshot(), + channel_threshold: 0, + maximum_pixels: 16_000_000, + }, + }, + ], + }, ] as const satisfies readonly ToolContract[]; + +function exampleCompleteness() { + return { + status: "complete_within_window", + conditions: ["complete_within_window"], + policy_filtered_sections: [], + attach_limited_sections: [], + truncated_sections: [], + unavailable_sections: [], + excluded: [], + dropped_events: { + scripts: 0, + network_requests: 0, + console_events: 0, + websocket_connections: 0, + websocket_frames: 0, + webmcp_tools: 0, + timeline_events: 0, + total: 0, + }, + }; +} + +function exampleInspection() { + return { + schema_version: 2, + browser: { + product: "Chrome/1", + protocol_version: "1.3", + revision: "example", + user_agent: "Chrome", + js_version: "1", + }, + target: { + target_id: "page-1", + type: "page", + title: "Example", + url: `${origin}/`, + origin, + attached: false, + }, + capture_window: { + started_at: "2026-07-14T00:00:00.000Z", + ended_at: "2026-07-14T00:00:01.000Z", + observation_ms: 1_000, + }, + completeness: exampleCompleteness(), + frames: [], + dom: { total_nodes: 0, nodes: [] }, + accessibility: { + total_nodes: 0, + text_capture: { + status: "not_approved", + retained_bytes: 0, + excluded_fields: 0, + truncated_fields: 0, + }, + nodes: [], + }, + scripts: { total: 0, items: [] }, + resources: [], + network: { + requests: [], + websocket_events: [], + coverage_started_at: "2026-07-14T00:00:00.000Z", + prior_activity_available: false, + }, + console: { + events: [], + coverage_started_at: "2026-07-14T00:00:00.000Z", + prior_activity_available: false, + }, + workers: [], + metadata: { + responses: [], + dom_urls: [], + agent_hints: [], + excluded_dom_urls: 0, + headers_allowlisted: true, + }, + storage: { + origin, + usage_bytes: null, + quota_bytes: null, + local_storage_keys: [], + session_storage_keys: [], + indexed_db_names: [], + cache_names: [], + values_redacted: true, + }, + limitations: [], + }; +} + +function exampleScreenshot() { + return { + uri: "rea://web-screenshot/sha256/153cf6c9a526a63053a37b10234c2fd85df38887c2dc0a800d90abfa6631d01c", + sha256: "153cf6c9a526a63053a37b10234c2fd85df38887c2dc0a800d90abfa6631d01c", + bytes: 70, + media_type: "image/png", + data_base64: + "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PzWvWQAAAABJRU5ErkJggg==", + }; +} diff --git a/src/contracts/electronToolContracts.ts b/src/contracts/electronToolContracts.ts new file mode 100644 index 000000000..9184856f7 --- /dev/null +++ b/src/contracts/electronToolContracts.ts @@ -0,0 +1,84 @@ +import type { ToolContract } from "./toolContracts.js"; +import { evidenceSchema } from "../domain/evidence.js"; +import { + electronPageInspectionSchema, + electronTargetListSchema, + inspectElectronPageInputSchema, + listElectronTargetsInputSchema, +} from "../domain/electronObservation.js"; + +const listOutputSchema = evidenceSchema + .omit({ normalized_result: true }) + .extend({ normalized_result: electronTargetListSchema }); +const inspectionOutputSchema = evidenceSchema + .omit({ normalized_result: true }) + .extend({ normalized_result: electronPageInspectionSchema }); + +const endpoint = "http://127.0.0.1:9223"; +const root = "/Applications/Example.app/Contents/Resources"; + +/** Root-confined Electron file-page discovery and inspection contracts. */ +export const ELECTRON_TOOL_CONTRACTS = [ + { + name: "list_electron_targets", + description: + "List Electron file:// page targets from an approved user-owned loopback CDP endpoint. Every path is canonicalized and must remain contained by an approved filesystem root, including after symlink resolution.", + kind: "electron-provider", + inputSchema: listElectronTargetsInputSchema, + outputSchema: listOutputSchema, + annotations: { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: true, + }, + examples: [ + { + title: "List approved Electron file pages", + input: { + cdp_endpoint: endpoint, + allowed_file_roots: [root], + approved: true, + offset: 0, + limit: 100, + }, + }, + ], + }, + { + name: "inspect_electron_page", + description: + "Passively inspect one approved Electron file page through CDP. Returns root-confined frames, DOM structure, resource paths, and scripts without evaluating renderer JavaScript or invoking Electron APIs; script contents require separate approval.", + kind: "electron-provider", + inputSchema: inspectElectronPageInputSchema, + outputSchema: inspectionOutputSchema, + annotations: { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: true, + }, + examples: [ + { + title: "Inspect an approved Electron page", + input: { + cdp_endpoint: endpoint, + allowed_file_roots: [root], + target_id: "TARGET_ID_FROM_LIST_ELECTRON_TARGETS", + approved: true, + observation_ms: 100, + include_script_sources: false, + source_capture_approved: false, + limits: { + max_frames: 200, + max_dom_nodes: 2_000, + max_scripts: 500, + max_resources: 2_000, + max_script_source_bytes: 1_048_576, + max_total_script_source_bytes: 4_194_304, + }, + }, + }, + ], + }, +] as const satisfies readonly ToolContract[]; diff --git a/src/contracts/toolContractTypes.ts b/src/contracts/toolContractTypes.ts index 2e8ada42c..e71312e80 100644 --- a/src/contracts/toolContractTypes.ts +++ b/src/contracts/toolContractTypes.ts @@ -23,6 +23,7 @@ export type ToolKind = | "native-provider" | "artifact-provider" | "browser-provider" + | "electron-provider" | "session"; /** Single source of truth for a public MCP tool. */ diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.ts index 62e29b6d2..a6f3f2d43 100644 --- a/src/contracts/toolContracts.ts +++ b/src/contracts/toolContracts.ts @@ -27,6 +27,7 @@ import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js"; import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js"; import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js"; import { BROWSER_TOOL_CONTRACTS } from "./browserToolContracts.js"; +import { ELECTRON_TOOL_CONTRACTS } from "./electronToolContracts.js"; import { closeBinaryInputSchema, openBinaryInputSchema, @@ -520,5 +521,6 @@ export const TOOL_CONTRACTS = [ ...NATIVE_TOOL_CONTRACTS, ...ARTIFACT_TOOL_CONTRACTS, ...BROWSER_TOOL_CONTRACTS, + ...ELECTRON_TOOL_CONTRACTS, ...SESSION_TOOL_CONTRACTS, ] as const; diff --git a/src/domain/browserCompleteness.ts b/src/domain/browserCompleteness.ts new file mode 100644 index 000000000..2fd8769df --- /dev/null +++ b/src/domain/browserCompleteness.ts @@ -0,0 +1,142 @@ +import { z } from "zod"; + +/** Stable browser sections used by coverage and omission accounting. */ +const browserSectionSchema = z.enum([ + "frames", + "dom", + "accessibility", + "scripts", + "script_sources", + "resources", + "network_requests", + "network_initiators", + "console_events", + "console_text", + "websocket_connections", + "websocket_frames", + "websocket_shapes", + "json_body_shapes", + "workers", + "storage", + "storage_keys", + "metadata", + "webmcp_tools", + "screenshot", + "source_maps", + "timeline", +]); +export type BrowserSection = z.infer; + +/** Why an eligible browser observation was not retained. */ +const browserExclusionReasonSchema = z.enum([ + "disallowed_origin", + "unsupported_url", + "unattributed_origin", + "not_approved", + "out_of_target_scope", + "provider_unavailable", + "invalid_protocol_value", +]); +export type BrowserExclusionReason = z.infer< + typeof browserExclusionReasonSchema +>; + +const browserExclusionSchema = z.object({ + section: browserSectionSchema, + reason: browserExclusionReasonSchema, + count: z.number().int().min(0).nullable(), +}); +export type BrowserExclusion = z.infer; + +const browserDroppedEventsSchema = z.object({ + scripts: z.number().int().min(0), + network_requests: z.number().int().min(0), + console_events: z.number().int().min(0), + websocket_connections: z.number().int().min(0), + websocket_frames: z.number().int().min(0), + webmcp_tools: z.number().int().min(0), + timeline_events: z.number().int().min(0), + total: z.number().int().min(0), +}); +export type BrowserDroppedEvents = z.infer; +export type BrowserDroppedEventKind = Exclude< + keyof BrowserDroppedEvents, + "total" +>; + +const browserCompletenessConditionSchema = z.enum([ + "complete_within_window", + "policy_filtered", + "attach_limited", + "truncated", +]); + +/** Explicit, non-lossy coverage semantics for a bounded browser observation. */ +export const browserCompletenessSchema = z.object({ + status: browserCompletenessConditionSchema, + conditions: z.array(browserCompletenessConditionSchema).min(1).max(3), + policy_filtered_sections: z.array(browserSectionSchema), + attach_limited_sections: z.array(browserSectionSchema), + truncated_sections: z.array(browserSectionSchema), + unavailable_sections: z.array(browserSectionSchema), + excluded: z.array(browserExclusionSchema), + dropped_events: browserDroppedEventsSchema, +}); +export type BrowserCompleteness = z.infer; + +/** Build canonical completeness output from one adapter-owned capture ledger. */ +export const classifyBrowserCompleteness = (input: { + readonly policyFilteredSections: ReadonlySet; + readonly attachLimitedSections: ReadonlySet; + readonly truncatedSections: ReadonlySet; + readonly unavailableSections: ReadonlySet; + readonly excluded: readonly BrowserExclusion[]; + readonly droppedEvents: Omit; +}): BrowserCompleteness => { + const policyFiltered = input.policyFilteredSections.size > 0; + const truncated = + input.truncatedSections.size > 0 || + Object.values(input.droppedEvents).some((count) => count > 0); + const attachLimited = + input.attachLimitedSections.size > 0 || input.unavailableSections.size > 0; + const status = truncated + ? "truncated" + : policyFiltered + ? "policy_filtered" + : attachLimited + ? "attach_limited" + : "complete_within_window"; + const conditions = [ + ...(attachLimited ? (["attach_limited"] as const) : []), + ...(policyFiltered ? (["policy_filtered"] as const) : []), + ...(truncated ? (["truncated"] as const) : []), + ]; + const droppedTotal = Object.values(input.droppedEvents).reduce( + (sum, count) => sum + count, + 0, + ); + return browserCompletenessSchema.parse({ + status, + conditions: + conditions.length === 0 ? ["complete_within_window"] : conditions, + policy_filtered_sections: sortedSections(input.policyFilteredSections), + attach_limited_sections: sortedSections(input.attachLimitedSections), + truncated_sections: sortedSections(input.truncatedSections), + unavailable_sections: sortedSections(input.unavailableSections), + excluded: canonicalExclusions(input.excluded), + dropped_events: { ...input.droppedEvents, total: droppedTotal }, + }); +}; + +const sortedSections = ( + sections: ReadonlySet, +): BrowserSection[] => [...sections].sort(); + +const canonicalExclusions = ( + exclusions: readonly BrowserExclusion[], +): BrowserExclusion[] => + [...exclusions].sort( + (left, right) => + left.section.localeCompare(right.section) || + left.reason.localeCompare(right.reason), + ); diff --git a/src/domain/browserObservation.ts b/src/domain/browserObservation.ts index a04f57dcd..c94f43f92 100644 --- a/src/domain/browserObservation.ts +++ b/src/domain/browserObservation.ts @@ -1,5 +1,9 @@ import { z } from "zod"; +import { browserCompletenessSchema } from "./browserCompleteness.js"; +import { webTextArtifactSchema } from "./webContentArtifact.js"; +import { jsonShapeSchema } from "./jsonShape.js"; + const parseExactOrigin = (value: string): string | undefined => { let url: URL; try { @@ -78,7 +82,7 @@ export const browserEndpointSchema = z return url.origin; }); -const allowedOriginsSchema = z +export const browserAllowedOriginsSchema = z .array(browserOriginSchema) .min(1) .max(32) @@ -86,7 +90,7 @@ const allowedOriginsSchema = z const approvedBrowserInput = { cdp_endpoint: browserEndpointSchema, - allowed_origins: allowedOriginsSchema, + allowed_origins: browserAllowedOriginsSchema, approved: z .literal(true) .describe("Explicit approval for browser observation"), @@ -103,6 +107,18 @@ const browserInspectionLimitsSchema = z.object({ max_frames: z.number().int().min(1).max(1_000).default(200), max_dom_nodes: z.number().int().min(1).max(10_000).default(2_000), max_ax_nodes: z.number().int().min(1).max(10_000).default(2_000), + max_ax_text_field_bytes: z + .number() + .int() + .min(1) + .max(16 * 1_024) + .default(1_024), + max_total_ax_text_bytes: z + .number() + .int() + .min(1) + .max(1_024 * 1_024) + .default(64 * 1_024), max_scripts: z.number().int().min(1).max(1_000).default(200), max_resources: z.number().int().min(1).max(10_000).default(2_000), max_workers: z.number().int().min(1).max(5_000).default(500), @@ -121,13 +137,53 @@ const browserInspectionLimitsSchema = z.object({ .default(4 * 1_024 * 1_024), max_network_events: z.number().int().min(1).max(10_000).default(1_000), max_console_events: z.number().int().min(1).max(2_000).default(200), + max_console_text_field_bytes: z + .number() + .int() + .min(1) + .max(16 * 1_024) + .default(1_024), + max_total_console_text_bytes: z + .number() + .int() + .min(1) + .max(1_024 * 1_024) + .default(64 * 1_024), + max_json_body_bytes: z + .number() + .int() + .min(1) + .max(4 * 1_024 * 1_024) + .default(1_024 * 1_024), + max_total_json_body_bytes: z + .number() + .int() + .min(1) + .max(16 * 1_024 * 1_024) + .default(4 * 1_024 * 1_024), + max_json_shape_nodes: z.number().int().min(1).max(100_000).default(5_000), + max_json_shape_depth: z.number().int().min(1).max(100).default(20), max_websocket_events: z.number().int().min(1).max(5_000).default(500), + max_websocket_shape_bytes: z + .number() + .int() + .min(1) + .max(1_024 * 1_024) + .default(64 * 1_024), + max_total_websocket_shape_bytes: z + .number() + .int() + .min(1) + .max(16 * 1_024 * 1_024) + .default(1_024 * 1_024), }); const DEFAULT_BROWSER_INSPECTION_LIMITS = { max_frames: 200, max_dom_nodes: 2_000, max_ax_nodes: 2_000, + max_ax_text_field_bytes: 1_024, + max_total_ax_text_bytes: 64 * 1_024, max_scripts: 200, max_resources: 2_000, max_workers: 500, @@ -136,7 +192,15 @@ const DEFAULT_BROWSER_INSPECTION_LIMITS = { max_total_script_source_bytes: 4 * 1_024 * 1_024, max_network_events: 1_000, max_console_events: 200, + max_console_text_field_bytes: 1_024, + max_total_console_text_bytes: 64 * 1_024, + max_json_body_bytes: 1_024 * 1_024, + max_total_json_body_bytes: 4 * 1_024 * 1_024, + max_json_shape_nodes: 5_000, + max_json_shape_depth: 20, max_websocket_events: 500, + max_websocket_shape_bytes: 64 * 1_024, + max_total_websocket_shape_bytes: 1_024 * 1_024, } as const; /** Public input for one passive, bounded inspection of an existing page. */ @@ -145,6 +209,13 @@ export const inspectWebPageInputSchema = z ...approvedBrowserInput, target_id: z.string().trim().min(1).max(256), observation_ms: z.number().int().min(0).max(10_000).default(500), + include_accessibility_text: z.boolean().default(false), + include_console_text: z.boolean().default(false), + console_text_approved: z.boolean().default(false), + include_json_body_shapes: z.boolean().default(false), + json_body_schema_approved: z.boolean().default(false), + include_websocket_shapes: z.boolean().default(false), + websocket_shape_approved: z.boolean().default(false), include_script_sources: z.boolean().default(false), include_storage_keys: z.boolean().default(false), limits: browserInspectionLimitsSchema.default( @@ -161,6 +232,66 @@ export const inspectWebPageInputSchema = z path: ["limits", "max_script_source_bytes"], message: "Per-script source limit cannot exceed the total source limit", }); + for (const [include, approved, path, message] of [ + [ + input.include_console_text, + input.console_text_approved, + "console_text_approved", + "Console text capture requires separate approval", + ], + [ + input.include_json_body_shapes, + input.json_body_schema_approved, + "json_body_schema_approved", + "JSON body schema capture requires separate approval", + ], + [ + input.include_websocket_shapes, + input.websocket_shape_approved, + "websocket_shape_approved", + "WebSocket shape capture requires separate approval", + ], + ] as const) + if (include && !approved) + context.addIssue({ code: "custom", path: [path], message }); + if ( + input.limits.max_console_text_field_bytes > + input.limits.max_total_console_text_bytes + ) + context.addIssue({ + code: "custom", + path: ["limits", "max_console_text_field_bytes"], + message: + "Per-field console text limit cannot exceed the total text limit", + }); + if ( + input.limits.max_json_body_bytes > input.limits.max_total_json_body_bytes + ) + context.addIssue({ + code: "custom", + path: ["limits", "max_json_body_bytes"], + message: "Per-body JSON limit cannot exceed the total body limit", + }); + if ( + input.limits.max_websocket_shape_bytes > + input.limits.max_total_websocket_shape_bytes + ) + context.addIssue({ + code: "custom", + path: ["limits", "max_websocket_shape_bytes"], + message: + "Per-frame WebSocket limit cannot exceed the total frame limit", + }); + if ( + input.limits.max_ax_text_field_bytes > + input.limits.max_total_ax_text_bytes + ) + context.addIssue({ + code: "custom", + path: ["limits", "max_ax_text_field_bytes"], + message: + "Per-field accessibility text limit cannot exceed the total text limit", + }); }); export type ListBrowserTargetsInput = z.infer< @@ -280,13 +411,22 @@ const browserScriptSourceSchema = z.discriminatedUnion("included", [ z.object({ included: z.literal(false), reason: z.string() }), z.object({ included: z.literal(true), - sha256: z.string().regex(/^[a-f0-9]{64}$/u), - bytes: z.number().int().min(0), - content: z.string(), + artifact: webTextArtifactSchema, + }), +]); +const browserResourceReconciliationSchema = z.discriminatedUnion("status", [ + z.object({ status: z.literal("exact"), resource_key: z.string() }), + z.object({ + status: z.literal("ambiguous"), + candidate_resource_keys: z.array(z.string()), + }), + z.object({ + status: z.literal("unmatched"), + reason: z.literal("no_exact_sanitized_url"), }), ]); const browserScriptSchema = z.object({ - script_id: z.string(), + script_key: z.string().regex(/^scr_[a-f0-9]{64}(?:_[0-9]+)?$/u), url: z.string(), origin: z.string().nullable(), cdp_hash: z.string(), @@ -294,9 +434,11 @@ const browserScriptSchema = z.object({ is_module: z.boolean(), language: z.string().nullable(), source_map_url: z.string().nullable(), + resource_reconciliation: browserResourceReconciliationSchema, source: browserScriptSourceSchema, }); const browserResourceSchema = z.object({ + resource_key: z.string().regex(/^res_[a-f0-9]{64}$/u), url: z.string(), origin: z.string().nullable(), type: z.string(), @@ -318,6 +460,17 @@ const browserNetworkRequestSchema = z.object({ line: z.number().int().min(0).nullable(), column: z.number().int().min(0).nullable(), }), + body_shapes: z.object({ + status: z.enum([ + "not_approved", + "included", + "partial", + "unavailable", + "truncated", + ]), + request: jsonShapeSchema.nullable(), + response: jsonShapeSchema.nullable(), + }), }); const browserConsoleEventSchema = z.object({ type: z.string(), @@ -326,12 +479,31 @@ const browserConsoleEventSchema = z.object({ url: z.string().nullable(), line: z.number().int().min(0).nullable(), column: z.number().int().min(0).nullable(), + text_capture: z.object({ + status: z.enum(["not_approved", "included", "truncated"]), + values: z.array( + z.object({ + argument_index: z.number().int().min(0), + type: z.string(), + text: z.string(), + }), + ), + retained_bytes: z.number().int().min(0), + truncated_values: z.number().int().min(0), + }), }); const browserWebSocketEventSchema = z.object({ request_id: z.string(), direction: z.enum(["sent", "received"]), opcode: z.number().int().min(0), payload_bytes: z.number().int().min(0), + payload_shape: z + .object({ + format: z.enum(["json", "text", "binary"]), + json_shape: jsonShapeSchema.nullable(), + truncated: z.boolean(), + }) + .nullable(), }); const browserWorkerSchema = z.object({ target_id: z.string(), @@ -340,10 +512,80 @@ const browserWorkerSchema = z.object({ origin: z.string().nullable(), attached: z.boolean(), }); +const browserCspSourceSchema = z.object({ + kind: z.enum([ + "keyword", + "scheme", + "approved_origin", + "external_origin", + "other", + ]), + value: z.string().nullable(), +}); +const browserLinkMetadataSchema = z.object({ + href: z.string().nullable(), + destination_scope: z.enum(["approved", "outside_policy", "unsupported"]), + rel: z.array(z.string()), + as: z.string().nullable(), + type: z.string().nullable(), + crossorigin: z.string().nullable(), +}); +const browserAgentHintSchema = z.object({ + mechanism: z.enum([ + "link_rel", + "dom_link_rel", + "well_known_resource", + "response_header", + ]), + declaration: z.string(), + url: z.string().nullable(), + trust: z.literal("page-declared-untrusted"), +}); +const browserSafeMetadataSchema = z.object({ + responses: z.array( + z.object({ + request_id: z.string(), + url: z.string(), + mime_type: z.string().nullable(), + content_length: z.number().int().min(0).nullable(), + content_encoding: z.string().nullable(), + csp: z.object({ + directives: z.array( + z.object({ + name: z.string(), + sources: z.array(browserCspSourceSchema), + }), + ), + nonce_count: z.number().int().min(0), + hash_count: z.number().int().min(0), + }), + links: z.array(browserLinkMetadataSchema), + policies: z.object({ + coop: z.string().nullable(), + coep: z.string().nullable(), + corp: z.string().nullable(), + referrer_policy: z.string().nullable(), + x_content_type_options: z.string().nullable(), + permissions_policy_features: z.array(z.string()), + }), + }), + ), + dom_urls: z.array( + z.object({ + node_index: z.number().int().min(0), + attribute: z.enum(["href", "src", "action", "formaction", "poster"]), + url: z.string().nullable(), + destination_scope: z.enum(["approved", "outside_policy", "unsupported"]), + }), + ), + agent_hints: z.array(browserAgentHintSchema), + excluded_dom_urls: z.number().int().min(0), + headers_allowlisted: z.literal(true), +}); /** Provider-neutral normalized result for one passive web-page observation. */ export const webPageInspectionSchema = z.object({ - schema_version: z.literal(1), + schema_version: z.literal(2), browser: browserVersionSchema, target: browserTargetSchema, capture_window: z.object({ @@ -351,11 +593,7 @@ export const webPageInspectionSchema = z.object({ ended_at: z.iso.datetime(), observation_ms: z.number().int().min(0), }), - completeness: z.object({ - status: z.enum(["complete", "truncated"]), - truncated_sections: z.array(z.string()), - dropped_events: z.number().int().min(0), - }), + completeness: browserCompletenessSchema, frames: z.array(browserFrameSchema), dom: z.object({ total_nodes: z.number().int().min(0), @@ -363,6 +601,12 @@ export const webPageInspectionSchema = z.object({ }), accessibility: z.object({ total_nodes: z.number().int().min(0), + text_capture: z.object({ + status: z.enum(["not_approved", "included", "truncated", "unavailable"]), + retained_bytes: z.number().int().min(0), + excluded_fields: z.number().int().min(0), + truncated_fields: z.number().int().min(0), + }), nodes: z.array(browserAxNodeSchema), }), scripts: z.object({ @@ -382,6 +626,7 @@ export const webPageInspectionSchema = z.object({ prior_activity_available: z.literal(false), }), workers: z.array(browserWorkerSchema), + metadata: browserSafeMetadataSchema, storage: z.object({ origin: z.string(), usage_bytes: z.number().min(0).nullable(), diff --git a/src/domain/browserSession.ts b/src/domain/browserSession.ts new file mode 100644 index 000000000..313b7a5a8 --- /dev/null +++ b/src/domain/browserSession.ts @@ -0,0 +1,74 @@ +import { z } from "zod"; + +import { + browserAllowedOriginsSchema, + browserEndpointSchema, +} from "./browserObservation.js"; +import { browserCompletenessSchema } from "./browserCompleteness.js"; + +/** Input for a bounded, navigation-aware browser observation window. */ +export const observeWebSessionInputSchema = z.object({ + cdp_endpoint: browserEndpointSchema, + allowed_origins: browserAllowedOriginsSchema, + target_id: z.string().trim().min(1).max(256), + approved: z.literal(true), + observation_ms: z.number().int().min(1).max(60_000).default(10_000), + max_timeline_events: z.number().int().min(1).max(20_000).default(2_000), +}); +export type ObserveWebSessionInput = z.infer< + typeof observeWebSessionInputSchema +>; + +const timelineEventSchema = z.object({ + sequence: z.number().int().min(1), + type: z.enum([ + "navigation_requested", + "navigation_committed", + "same_origin_reload", + "same_document_navigation", + "redirect", + "load_failed", + "lifecycle", + "target_terminated", + ]), + timestamp: z.number().min(0), + frame_id: z.string().nullable(), + loader_id: z.string().nullable(), + request_id: z.string().nullable(), + url: z.string().nullable(), + destination_scope: z + .enum(["approved", "outside_policy", "unsupported"]) + .nullable(), + detail: z.string().nullable(), +}); + +/** Navigation-aware session result for external user actions. */ +export const webObservationSessionSchema = z.object({ + schema_version: z.literal(1), + browser: z.object({ + product: z.string(), + protocol_version: z.string(), + revision: z.string(), + user_agent: z.string(), + js_version: z.string(), + }), + target: z.object({ + target_id: z.string(), + initial_url: z.string(), + final_url: z.string().nullable(), + }), + window: z.object({ + armed_at: z.iso.datetime(), + ended_at: z.iso.datetime(), + requested_ms: z.number().int().min(1), + end_reason: z.enum([ + "window_elapsed", + "target_left_scope", + "target_terminated", + ]), + }), + timeline: z.array(timelineEventSchema), + completeness: browserCompletenessSchema, + limitations: z.array(z.string()), +}); +export type WebObservationSession = z.infer; diff --git a/src/domain/electronObservation.ts b/src/domain/electronObservation.ts new file mode 100644 index 000000000..3c6b911f3 --- /dev/null +++ b/src/domain/electronObservation.ts @@ -0,0 +1,194 @@ +import { isAbsolute } from "node:path"; + +import { z } from "zod"; + +import { browserCompletenessSchema } from "./browserCompleteness.js"; +import { browserEndpointSchema } from "./browserObservation.js"; +import { webTextArtifactSchema } from "./webContentArtifact.js"; + +/** Absolute operator-approved filesystem roots for Electron file pages. */ +export const electronFileRootsSchema = z + .array( + z + .string() + .min(1) + .max(16_384) + .refine(isAbsolute, "Electron file roots must be absolute paths"), + ) + .min(1) + .max(32) + .transform((roots) => [...new Set(roots)].sort()); + +const approvedElectronInput = { + cdp_endpoint: browserEndpointSchema, + allowed_file_roots: electronFileRootsSchema, + approved: z.literal(true), +}; + +/** Input for listing root-confined file:// page targets from Electron CDP. */ +export const listElectronTargetsInputSchema = z.object({ + ...approvedElectronInput, + offset: z.number().int().min(0).default(0), + limit: z.number().int().min(1).max(200).default(100), +}); +export type ListElectronTargetsInput = z.infer< + typeof listElectronTargetsInputSchema +>; + +/** Input for passive structural inspection of one Electron file page. */ +export const inspectElectronPageInputSchema = z + .object({ + ...approvedElectronInput, + target_id: z.string().trim().min(1).max(256), + observation_ms: z.number().int().min(0).max(10_000).default(100), + include_script_sources: z.boolean().default(false), + source_capture_approved: z.boolean().default(false), + limits: z + .object({ + max_frames: z.number().int().min(1).max(1_000).default(200), + max_dom_nodes: z.number().int().min(1).max(10_000).default(2_000), + max_scripts: z.number().int().min(1).max(2_000).default(500), + max_resources: z.number().int().min(1).max(10_000).default(2_000), + max_script_source_bytes: z + .number() + .int() + .min(1) + .max(4 * 1_024 * 1_024) + .default(1_024 * 1_024), + max_total_script_source_bytes: z + .number() + .int() + .min(1) + .max(16 * 1_024 * 1_024) + .default(4 * 1_024 * 1_024), + }) + .default({ + max_frames: 200, + max_dom_nodes: 2_000, + max_scripts: 500, + max_resources: 2_000, + max_script_source_bytes: 1_024 * 1_024, + max_total_script_source_bytes: 4 * 1_024 * 1_024, + }), + }) + .superRefine((input, context) => { + if (input.include_script_sources && !input.source_capture_approved) + context.addIssue({ + code: "custom", + path: ["source_capture_approved"], + message: "Electron script source capture requires separate approval", + }); + if ( + input.limits.max_script_source_bytes > + input.limits.max_total_script_source_bytes + ) + context.addIssue({ + code: "custom", + path: ["limits", "max_script_source_bytes"], + message: "Per-script source limit cannot exceed the total source limit", + }); + }); +export type InspectElectronPageInput = z.infer< + typeof inspectElectronPageInputSchema +>; + +const browserVersionSchema = z.object({ + product: z.string(), + protocol_version: z.string(), + revision: z.string(), + user_agent: z.string(), + js_version: z.string(), +}); +const electronTargetSchema = z.object({ + target_id: z.string(), + type: z.string(), + title: z.string(), + file_path: z.string(), + attached: z.boolean(), +}); + +/** Root-filtered Electron file target inventory. */ +export const electronTargetListSchema = z.object({ + schema_version: z.literal(1), + browser: browserVersionSchema, + targets: z.object({ + items: z.array(electronTargetSchema), + offset: z.number().int().min(0), + limit: z.number().int().min(1), + total: z.number().int().min(0), + next_offset: z.number().int().min(0).nullable(), + has_more: z.boolean(), + }), + excluded: z.object({ + outside_root: z.number().int().min(0), + unsupported_url: z.number().int().min(0), + non_page: z.number().int().min(0), + }), + limitations: z.array(z.string()), +}); +export type ElectronTargetList = z.infer; + +const electronSourceSchema = z.discriminatedUnion("included", [ + z.object({ included: z.literal(false), reason: z.string() }), + z.object({ included: z.literal(true), artifact: webTextArtifactSchema }), +]); + +/** Provider-neutral passive Electron file-page structure and script inventory. */ +export const electronPageInspectionSchema = z.object({ + schema_version: z.literal(1), + browser: browserVersionSchema, + target: electronTargetSchema, + capture_window: z.object({ + started_at: z.iso.datetime(), + ended_at: z.iso.datetime(), + observation_ms: z.number().int().min(0), + }), + completeness: browserCompletenessSchema, + frames: z.array( + z.object({ + frame_id: z.string(), + parent_frame_id: z.string().nullable(), + file_path: z.string(), + }), + ), + dom: z.object({ + total_nodes: z.number().int().min(0), + nodes: z.array( + z.object({ + index: z.number().int().min(0), + parent_index: z.number().int().min(-1), + node_type: z.number().int().min(0), + node_name: z.string(), + node_value_length: z.number().int().min(0), + attribute_names: z.array(z.string()), + }), + ), + }), + scripts: z.object({ + total: z.number().int().min(0), + items: z.array( + z.object({ + script_key: z.string().regex(/^electron_script_[a-f0-9]{64}$/u), + file_path: z.string(), + cdp_hash: z.string(), + length: z.number().int().min(0), + is_module: z.boolean(), + language: z.string().nullable(), + source: electronSourceSchema, + }), + ), + }), + resources: z.array( + z.object({ + resource_key: z.string().regex(/^electron_resource_[a-f0-9]{64}$/u), + file_path: z.string(), + type: z.string(), + mime_type: z.string(), + content_size: z.number().min(0).nullable(), + }), + ), + limitations: z.array(z.string()), +}); +export type ElectronPageInspection = z.infer< + typeof electronPageInspectionSchema +>; diff --git a/src/domain/errors.ts b/src/domain/errors.ts index 5f3414cbb..60469562d 100644 --- a/src/domain/errors.ts +++ b/src/domain/errors.ts @@ -144,12 +144,25 @@ export class ProviderAdapterError extends AnalysisError { } } +/** Public browser and Electron operations that can fail at a CDP boundary. */ +export type BrowserObservationOperation = + | "list_browser_targets" + | "inspect_web_page" + | "analyze_web_bundle" + | "observe_web_session" + | "discover_webmcp_tools" + | "compare_web_captures" + | "capture_web_screenshot" + | "compare_web_screenshots" + | "list_electron_targets" + | "inspect_electron_page"; + /** A bounded passive browser observation failed at its CDP boundary. */ export class BrowserObservationError extends AnalysisError { readonly _tag = "BrowserObservationError"; constructor( - readonly operation: "list_browser_targets" | "inspect_web_page", + readonly operation: BrowserObservationOperation, readonly reason: | "endpoint_unreachable" | "invalid_endpoint_response" diff --git a/src/domain/jsonShape.ts b/src/domain/jsonShape.ts new file mode 100644 index 000000000..1d7271386 --- /dev/null +++ b/src/domain/jsonShape.ts @@ -0,0 +1,151 @@ +import { z } from "zod"; + +const jsonValueTypeSchema = z.enum([ + "object", + "array", + "string", + "number", + "boolean", + "null", +]); +type JsonValueType = z.infer; + +/** Value-free structural summary of one approved JSON payload. */ +export const jsonShapeSchema = z.object({ + root_type: jsonValueTypeSchema, + node_count: z.number().int().min(1), + max_depth_observed: z.number().int().min(0), + properties: z.array( + z.object({ + path: z.string(), + types: z.array(jsonValueTypeSchema).min(1), + observations: z.number().int().min(1), + }), + ), + truncated: z.boolean(), +}); +export type JsonShape = z.infer; + +export interface JsonShapeLimits { + readonly maximumBytes: number; + readonly maximumNodes: number; + readonly maximumDepth: number; +} + +/** Parse approved JSON and immediately discard values after iterative shape inference. */ +export const inferJsonShape = ( + text: string, + limits: JsonShapeLimits, +): JsonShape | null => { + if (Buffer.byteLength(text) > limits.maximumBytes) return null; + let root: unknown; + try { + root = JSON.parse(text); + } catch { + return null; + } + const properties = new Map< + string, + { readonly types: Set; observations: number } + >(); + const pending: Array<{ + readonly value: unknown; + readonly path: string; + readonly depth: number; + }> = [{ value: root, path: "", depth: 0 }]; + let nodeCount = 0; + let maxDepthObserved = 0; + let truncated = false; + while (pending.length > 0) { + const current = pending.pop(); + if (current === undefined) break; + if (nodeCount >= limits.maximumNodes) { + truncated = true; + break; + } + nodeCount += 1; + maxDepthObserved = Math.max(maxDepthObserved, current.depth); + if (current.depth >= limits.maximumDepth) { + if (hasChildren(current.value)) truncated = true; + continue; + } + if (Array.isArray(current.value)) { + const capacity = Math.max( + 0, + limits.maximumNodes - nodeCount - pending.length, + ); + const retained = Math.min(current.value.length, capacity); + if (retained < current.value.length) truncated = true; + for (let index = retained - 1; index >= 0; index -= 1) + pending.push({ + value: current.value[index], + path: `${current.path}/*`, + depth: current.depth + 1, + }); + continue; + } + if (!isRecord(current.value)) continue; + const allEntries = Object.entries(current.value); + const capacity = Math.max( + 0, + limits.maximumNodes - nodeCount - pending.length, + ); + const entries = allEntries.slice(0, capacity); + if (entries.length < allEntries.length) truncated = true; + for (let index = entries.length - 1; index >= 0; index -= 1) { + const entry = entries[index]; + if (entry === undefined) continue; + const [name, value] = entry; + const path = `${current.path}/${pointerName(name)}`.slice(0, 2_048); + const type = jsonValueType(value); + const existing = properties.get(path); + if (existing === undefined) + properties.set(path, { types: new Set([type]), observations: 1 }); + else { + existing.types.add(type); + existing.observations += 1; + } + pending.push({ value, path, depth: current.depth + 1 }); + } + } + return jsonShapeSchema.parse({ + root_type: jsonValueType(root), + node_count: nodeCount, + max_depth_observed: maxDepthObserved, + properties: [...properties.entries()] + .map(([path, value]) => ({ + path, + types: [...value.types].sort(), + observations: value.observations, + })) + .sort((left, right) => left.path.localeCompare(right.path)) + .slice(0, limits.maximumNodes), + truncated, + }); +}; + +const jsonValueType = (value: unknown): JsonValueType => { + if (value === null) return "null"; + if (Array.isArray(value)) return "array"; + switch (typeof value) { + case "string": + return "string"; + case "number": + return "number"; + case "boolean": + return "boolean"; + default: + return "object"; + } +}; + +const hasChildren = (value: unknown): boolean => + Array.isArray(value) + ? value.length > 0 + : isRecord(value) && Object.keys(value).length > 0; + +const isRecord = (value: unknown): value is Readonly> => + typeof value === "object" && value !== null && !Array.isArray(value); + +const pointerName = (value: string): string => + value.slice(0, 256).replaceAll("~", "~0").replaceAll("/", "~1"); diff --git a/src/domain/permissionPolicy.ts b/src/domain/permissionPolicy.ts index 917dff5e9..f4e369725 100644 --- a/src/domain/permissionPolicy.ts +++ b/src/domain/permissionPolicy.ts @@ -6,6 +6,7 @@ import { err, ok, type Result } from "./result.js"; export type PermissionCapability = | "process_capture" | "browser_observe" + | "electron_observe" | "evidence_read" | "evidence_write" | "investigation_input" diff --git a/src/domain/webBundleAnalysis.ts b/src/domain/webBundleAnalysis.ts new file mode 100644 index 000000000..3c88bbf85 --- /dev/null +++ b/src/domain/webBundleAnalysis.ts @@ -0,0 +1,228 @@ +import { z } from "zod"; + +import { inspectWebPageInputSchema } from "./browserObservation.js"; +import { webTextArtifactSchema } from "./webContentArtifact.js"; + +const webBundleLimitsSchema = z.object({ + max_findings: z.number().int().min(1).max(10_000).default(1_000), + max_ast_nodes: z.number().int().min(1).max(2_000_000).default(250_000), + max_source_maps: z.number().int().min(1).max(1_000).default(100), + max_source_map_bytes: z + .number() + .int() + .min(1) + .max(16 * 1_024 * 1_024) + .default(4 * 1_024 * 1_024), + max_total_source_map_bytes: z + .number() + .int() + .min(1) + .max(64 * 1_024 * 1_024) + .default(16 * 1_024 * 1_024), + max_source_map_mappings: z.number().int().min(1).max(100_000).default(10_000), + max_original_sources: z.number().int().min(1).max(20_000).default(2_000), +}); + +/** Capture-and-analyze input with separate source and source-map approvals. */ +export const analyzeWebBundleInputSchema = inspectWebPageInputSchema + .safeExtend({ + include_script_sources: z.literal(true).default(true), + source_capture_approved: z.literal(true), + fetch_source_maps: z.boolean().default(false), + source_map_fetch_approved: z.boolean().default(false), + analysis_limits: webBundleLimitsSchema.default({ + max_findings: 1_000, + max_ast_nodes: 250_000, + max_source_maps: 100, + max_source_map_bytes: 4 * 1_024 * 1_024, + max_total_source_map_bytes: 16 * 1_024 * 1_024, + max_source_map_mappings: 10_000, + max_original_sources: 2_000, + }), + }) + .superRefine((input, context) => { + if (input.fetch_source_maps && !input.source_map_fetch_approved) + context.addIssue({ + code: "custom", + path: ["source_map_fetch_approved"], + message: "Source-map network fetch requires separate approval", + }); + if ( + input.analysis_limits.max_source_map_bytes > + input.analysis_limits.max_total_source_map_bytes + ) + context.addIssue({ + code: "custom", + path: ["analysis_limits", "max_source_map_bytes"], + message: + "Per-map source-map byte limit cannot exceed the aggregate limit", + }); + }); +export type AnalyzeWebBundleInput = z.infer; + +const sourceLocationSchema = z.object({ + script_key: z.string(), + line: z.number().int().min(1).nullable(), + column: z.number().int().min(0).nullable(), +}); + +const basisSchema = z.object({ + script_key: z.string(), + artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u), + line: z.number().int().min(1).nullable(), + column: z.number().int().min(0).nullable(), + detector: z.string(), +}); + +const findingSchema = z.object({ + value: z.string(), + mechanism: z.string(), + location: sourceLocationSchema, +}); + +const sourceMapSchema = z.object({ + script_key: z.string(), + declared_url: z.string(), + status: z.enum([ + "included", + "fetch_failed", + "invalid", + "policy_filtered", + "truncated", + ]), + artifact: webTextArtifactSchema.nullable(), + original_sources: z.array( + z.object({ + source: z.string(), + artifact: webTextArtifactSchema.nullable(), + }), + ), + original_module_edges: z.array( + z.object({ + from_source: z.string(), + kind: z.enum(["static_import", "dynamic_import", "require"]), + specifier: z.string(), + resolved_source: z.string().nullable(), + }), + ), + mappings: z.array( + z.object({ + generated_line: z.number().int().min(1), + generated_column: z.number().int().min(0), + source: z.string(), + original_line: z.number().int().min(1), + original_column: z.number().int().min(0), + name: z.string().nullable(), + }), + ), + limitation: z.string().nullable(), +}); + +const webTextArtifactSummarySchema = z.object({ + uri: z.string().regex(/^rea:\/\/web-content\/sha256\/[a-f0-9]{64}$/u), + sha256: z.string().regex(/^[a-f0-9]{64}$/u), + bytes: z.number().int().min(0), + media_type: z.string().min(1).max(256), + charset: z.literal("utf-8"), + text_available: z.literal(true), +}); + +const sourceMapsSchema = z + .object({ + status: z.enum([ + "not_requested", + "included", + "partial", + "unavailable", + "truncated", + ]), + requested: z.number().int().min(0), + processed: z.number().int().min(0), + dropped: z.number().int().min(0), + dropped_script_keys: z.array(z.string()), + items: z.array(sourceMapSchema), + }) + .superRefine((sourceMaps, context) => { + if ( + sourceMaps.requested !== sourceMaps.processed + sourceMaps.dropped || + sourceMaps.processed !== sourceMaps.items.length || + sourceMaps.dropped !== sourceMaps.dropped_script_keys.length + ) + context.addIssue({ + code: "custom", + message: "Source-map coverage counts are inconsistent", + }); + }); + +/** Provider-neutral result of bounded JavaScript bundle reverse engineering. */ +export const webBundleAnalysisSchema = z.object({ + schema_version: z.literal(1), + capture: z.object({ + target_url: z.string(), + scripts_observed: z.number().int().min(0), + scripts_analyzed: z.number().int().min(0), + source_artifacts: z.array(webTextArtifactSummarySchema), + }), + observations: z.object({ + chunks: z.object({ + nodes: z.array( + z.object({ + script_key: z.string(), + url: z.string(), + artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u), + bytes: z.number().int().min(0), + }), + ), + edges: z.array( + z.object({ + from_script_key: z.string(), + kind: z.enum([ + "static_import", + "dynamic_import", + "require", + "worker_import", + ]), + specifier: z.string(), + resolved_url: z.string().nullable(), + location: sourceLocationSchema, + }), + ), + }), + routes: z.array(findingSchema), + endpoints: z.array(findingSchema), + webmcp_declarations: z.array( + z.object({ + name: z.string().nullable(), + description: z.string().nullable(), + schema_property_names: z.array(z.string()), + trust: z.literal("page-declared-untrusted"), + location: sourceLocationSchema, + }), + ), + source_maps: sourceMapsSchema, + }), + inferences: z.array( + z.object({ + kind: z.enum(["vendor_fingerprint", "route_framework", "bundle_runtime"]), + value: z.string(), + confidence: z.enum(["low", "medium", "high"]), + basis: z.array(basisSchema).min(1), + }), + ), + unknowns: z.array( + z.object({ + dimension: z.string(), + reason: z.string(), + affected_script_keys: z.array(z.string()), + }), + ), + completeness: z.object({ + status: z.enum(["complete_within_limits", "truncated", "partial"]), + parsed_scripts: z.number().int().min(0), + parse_failures: z.number().int().min(0), + visited_ast_nodes: z.number().int().min(0), + dropped_findings: z.number().int().min(0), + }), + limitations: z.array(z.string()), +}); +export type WebBundleAnalysis = z.infer; diff --git a/src/domain/webBundleAnalyzer.ts b/src/domain/webBundleAnalyzer.ts new file mode 100644 index 000000000..19881f492 --- /dev/null +++ b/src/domain/webBundleAnalyzer.ts @@ -0,0 +1,640 @@ +import { parse } from "@babel/parser"; +import * as t from "@babel/types"; + +import type { WebPageInspection } from "./browserObservation.js"; +import { sanitizeBrowserUrl } from "./browserObservation.js"; +import { + webBundleAnalysisSchema, + type AnalyzeWebBundleInput, + type WebBundleAnalysis, +} from "./webBundleAnalysis.js"; + +type BundleObservations = WebBundleAnalysis["observations"]; +type ChunkEdge = BundleObservations["chunks"]["edges"][number]; +type Finding = BundleObservations["routes"][number]; +type WebMcpDeclaration = BundleObservations["webmcp_declarations"][number]; +type Inference = WebBundleAnalysis["inferences"][number]; +type BrowserScript = WebPageInspection["scripts"]["items"][number]; +type IncludedSource = Extract; +type IncludedScript = Omit & { + readonly source: IncludedSource; +}; + +interface AnalysisAccumulator { + readonly edges: ChunkEdge[]; + readonly routes: Finding[]; + readonly endpoints: Finding[]; + readonly webMcp: WebMcpDeclaration[]; + readonly inferences: Inference[]; + readonly seen: Set; + visitedNodes: number; + parsedScripts: number; + parseFailures: number; + droppedFindings: number; + astLimitReached: boolean; +} + +/** Analyze captured, explicitly approved JavaScript source without execution. */ +export const analyzeCapturedWebBundle = ( + inspection: WebPageInspection, + input: AnalyzeWebBundleInput, + sourceMaps: BundleObservations["source_maps"] = { + status: "not_requested", + requested: 0, + processed: 0, + dropped: 0, + dropped_script_keys: [], + items: [], + }, +): WebBundleAnalysis => { + const accumulator = emptyAccumulator(); + const sourceScripts = inspection.scripts.items.filter(isIncludedScript); + for (const script of sourceScripts) analyzeScript(script, input, accumulator); + const unavailable = inspection.scripts.items + .filter((script) => !script.source.included) + .map(({ script_key }) => script_key); + const sourceMapIncomplete = + sourceMaps.status === "partial" || sourceMaps.status === "unavailable"; + const partial = + accumulator.parseFailures > 0 || + unavailable.length > 0 || + sourceMapIncomplete; + const truncated = + accumulator.astLimitReached || + accumulator.droppedFindings > 0 || + sourceMaps.status === "truncated"; + return webBundleAnalysisSchema.parse({ + schema_version: 1, + capture: { + target_url: inspection.target.url, + scripts_observed: inspection.scripts.total, + scripts_analyzed: sourceScripts.length, + source_artifacts: sourceScripts.map((script) => { + if (!script.source.included) + throw new TypeError("Filtered source changed"); + const { text: _text, ...artifact } = script.source.artifact; + return { ...artifact, text_available: true }; + }), + }, + observations: { + chunks: { + nodes: sourceScripts.map((script) => { + if (!script.source.included) + throw new TypeError("Filtered source changed"); + return { + script_key: script.script_key, + url: script.url, + artifact_sha256: script.source.artifact.sha256, + bytes: script.source.artifact.bytes, + }; + }), + edges: accumulator.edges, + }, + routes: accumulator.routes, + endpoints: accumulator.endpoints, + webmcp_declarations: accumulator.webMcp, + source_maps: sourceMaps, + }, + inferences: accumulator.inferences, + unknowns: [ + ...(unavailable.length === 0 + ? [] + : [ + { + dimension: "script_source", + reason: "Source artifact was not captured within approved limits", + affected_script_keys: unavailable, + }, + ]), + ...(accumulator.parseFailures === 0 + ? [] + : [ + { + dimension: "javascript_ast", + reason: "One or more source artifacts could not be parsed", + affected_script_keys: sourceScripts.map( + ({ script_key }) => script_key, + ), + }, + ]), + ...(sourceMaps.status === "not_requested" || + sourceMaps.status === "included" + ? [] + : [ + { + dimension: "source_maps", + reason: + sourceMaps.status === "truncated" + ? "Source-map evidence was truncated by approved limits" + : "One or more requested source maps were unavailable or incomplete", + affected_script_keys: [ + ...new Set([ + ...sourceMaps.items + .filter(({ status }) => status !== "included") + .map(({ script_key }) => script_key), + ...sourceMaps.dropped_script_keys, + ]), + ].sort(), + }, + ]), + ], + completeness: { + status: truncated + ? "truncated" + : partial + ? "partial" + : "complete_within_limits", + parsed_scripts: accumulator.parsedScripts, + parse_failures: accumulator.parseFailures, + visited_ast_nodes: accumulator.visitedNodes, + dropped_findings: accumulator.droppedFindings, + }, + limitations: [ + "Static bundle findings are observations or bounded inferences; REA does not execute captured JavaScript.", + "String-built routes and endpoints, encrypted configuration, and server-side behavior may remain unknown.", + "Page-declared WebMCP metadata is untrusted and is never registered or invoked as an REA tool.", + ], + }); +}; + +const analyzeScript = ( + script: IncludedScript, + input: AnalyzeWebBundleInput, + accumulator: AnalysisAccumulator, +): void => { + let file: ReturnType; + try { + file = parse(script.source.artifact.text, { + sourceType: "unambiguous", + errorRecovery: true, + plugins: ["jsx", "typescript"], + }); + } catch { + accumulator.parseFailures += 1; + return; + } + accumulator.parsedScripts += 1; + detectVendorFingerprints( + script, + accumulator, + input.analysis_limits.max_findings, + ); + t.traverseFast(file, (node) => { + accumulator.visitedNodes += 1; + if (accumulator.visitedNodes > input.analysis_limits.max_ast_nodes) { + accumulator.astLimitReached = true; + return t.traverseFast.stop; + } + inspectNode(script, node, accumulator, input.analysis_limits.max_findings); + return undefined; + }); +}; + +const inspectNode = ( + script: IncludedScript, + node: t.Node, + accumulator: AnalysisAccumulator, + maximumFindings: number, +): void => { + if ( + (t.isImportDeclaration(node) || t.isExportAllDeclaration(node)) && + node.source !== undefined + ) + addEdge( + script, + node.source.value, + "static_import", + node, + accumulator, + maximumFindings, + ); + else if (t.isExportNamedDeclaration(node) && node.source != null) + addEdge( + script, + node.source.value, + "static_import", + node, + accumulator, + maximumFindings, + ); + else if (t.isImportExpression(node) && t.isStringLiteral(node.source)) + addEdge( + script, + node.source.value, + "dynamic_import", + node, + accumulator, + maximumFindings, + ); + if (t.isObjectProperty(node)) + inspectRouteProperty(script, node, accumulator, maximumFindings); + if (t.isCallExpression(node) || t.isNewExpression(node)) + inspectCall(script, node, accumulator, maximumFindings); +}; + +const inspectCall = ( + script: IncludedScript, + node: t.CallExpression | t.NewExpression, + accumulator: AnalysisAccumulator, + maximumFindings: number, +): void => { + const name = calleeName(node.callee); + const first = stringArgument(node.arguments[0]); + if ((name === "require" || name.endsWith(".require")) && first !== undefined) + addEdge(script, first, "require", node, accumulator, maximumFindings); + if ( + (name === "importScripts" || name.endsWith(".importScripts")) && + first !== undefined + ) + addEdge(script, first, "worker_import", node, accumulator, maximumFindings); + if ( + routeCallNames.some( + (candidate) => name === candidate || name.endsWith(`.${candidate}`), + ) + ) { + if (first !== undefined) + addFinding( + accumulator.routes, + script, + first, + `call:${name}`, + node, + accumulator, + maximumFindings, + ); + addRouteFrameworkInference( + script, + name, + node, + accumulator, + maximumFindings, + ); + } + const endpoint = endpointArgument(name, node.arguments); + if (endpoint !== undefined) + addFinding( + accumulator.endpoints, + script, + endpoint, + `call:${name}`, + node, + accumulator, + maximumFindings, + ); + if ( + name.endsWith("modelContext.registerTool") || + name === "modelContext.registerTool" + ) + addWebMcpDeclaration(script, node, accumulator, maximumFindings); +}; + +const inspectRouteProperty = ( + script: IncludedScript, + node: t.ObjectProperty, + accumulator: AnalysisAccumulator, + maximumFindings: number, +): void => { + const key = propertyName(node.key); + if ((key === "path" || key === "route") && t.isStringLiteral(node.value)) + addFinding( + accumulator.routes, + script, + node.value.value, + `property:${key}`, + node, + accumulator, + maximumFindings, + ); +}; + +const addEdge = ( + script: IncludedScript, + specifier: string, + kind: ChunkEdge["kind"], + node: t.Node, + accumulator: AnalysisAccumulator, + maximumFindings: number, +): void => { + const bounded = specifier.slice(0, 4_096); + const key = `edge\0${script.script_key}\0${kind}\0${bounded}`; + addBounded(accumulator, key, maximumFindings, () => + accumulator.edges.push({ + from_script_key: script.script_key, + kind, + specifier: bounded, + resolved_url: resolveSpecifier(bounded, script.url), + location: location(script.script_key, node), + }), + ); +}; + +const addFinding = ( + collection: Finding[], + script: IncludedScript, + rawValue: string, + mechanism: string, + node: t.Node, + accumulator: AnalysisAccumulator, + maximumFindings: number, +): void => { + const value = sanitizeCandidate(rawValue); + const key = `finding\0${mechanism}\0${script.script_key}\0${value}`; + addBounded(accumulator, key, maximumFindings, () => + collection.push({ + value, + mechanism, + location: location(script.script_key, node), + }), + ); +}; + +const addWebMcpDeclaration = ( + script: IncludedScript, + node: t.CallExpression | t.NewExpression, + accumulator: AnalysisAccumulator, + maximumFindings: number, +): void => { + const declaration = node.arguments[0]; + if (!t.isObjectExpression(declaration)) return; + const name = objectString(declaration, "name"); + const description = objectString(declaration, "description"); + const schema = + objectValue(declaration, "inputSchema") ?? + objectValue(declaration, "input_schema"); + const declaredProperties = t.isObjectExpression(schema) + ? objectValue(schema, "properties") + : undefined; + const propertyObject = t.isObjectExpression(declaredProperties) + ? declaredProperties + : schema; + const schemaPropertyNames = t.isObjectExpression(propertyObject) + ? propertyObject.properties.flatMap((property) => + t.isObjectProperty(property) + ? [propertyName(property.key)].filter(Boolean) + : [], + ) + : []; + const key = `webmcp\0${script.script_key}\0${name ?? ""}\0${schemaPropertyNames.join("\0")}`; + addBounded(accumulator, key, maximumFindings, () => + accumulator.webMcp.push({ + name: name?.slice(0, 256) ?? null, + description: description?.slice(0, 2_048) ?? null, + schema_property_names: [...new Set(schemaPropertyNames)] + .sort() + .slice(0, 256), + trust: "page-declared-untrusted", + location: location(script.script_key, node), + }), + ); +}; + +const detectVendorFingerprints = ( + script: IncludedScript, + accumulator: AnalysisAccumulator, + maximumFindings: number, +): void => { + const text = script.source.artifact.text; + for (const detector of vendorDetectors) { + if (!detector.patterns.some((pattern) => text.includes(pattern))) continue; + const key = `vendor\0${script.script_key}\0${detector.value}`; + addBounded(accumulator, key, maximumFindings, () => + accumulator.inferences.push({ + kind: detector.kind, + value: detector.value, + confidence: detector.confidence, + basis: [basis(script, detector.detector)], + }), + ); + } +}; + +const addRouteFrameworkInference = ( + script: IncludedScript, + name: string, + node: t.Node, + accumulator: AnalysisAccumulator, + maximumFindings: number, +): void => { + const value = + name.endsWith("useRoutes") || name.endsWith("createBrowserRouter") + ? "React Router-compatible route API" + : "Generic route registration API"; + const key = `route-framework\0${script.script_key}\0${value}`; + addBounded(accumulator, key, maximumFindings, () => + accumulator.inferences.push({ + kind: "route_framework", + value, + confidence: "medium", + basis: [{ ...basis(script, `call:${name}`), ...locationFields(node) }], + }), + ); +}; + +const addBounded = ( + accumulator: AnalysisAccumulator, + key: string, + maximum: number, + add: () => void, +): void => { + if (accumulator.seen.has(key)) return; + const findings = + accumulator.edges.length + + accumulator.routes.length + + accumulator.endpoints.length + + accumulator.webMcp.length + + accumulator.inferences.length; + if (findings >= maximum) { + accumulator.droppedFindings += 1; + return; + } + accumulator.seen.add(key); + add(); +}; + +const endpointArgument = ( + name: string, + args: readonly ( + | t.Expression + | t.SpreadElement + | t.JSXNamespacedName + | t.ArgumentPlaceholder + )[], +): string | undefined => { + if (name === "fetch" || name.endsWith(".fetch") || name === "WebSocket") + return stringArgument(args[0]); + if (name.endsWith(".open") && stringArgument(args[1]) !== undefined) + return stringArgument(args[1]); + if ( + ["get", "post", "put", "patch", "delete", "request"].some( + (method) => name === method || name.endsWith(`.${method}`), + ) + ) + return stringArgument(args[0]); + return undefined; +}; + +const calleeName = (callee: t.Node): string => { + if (t.isIdentifier(callee)) return callee.name; + if (t.isImport(callee)) return "import"; + if (t.isMemberExpression(callee) || t.isOptionalMemberExpression(callee)) { + const object = t.isExpression(callee.object) + ? calleeName(callee.object) + : ""; + const property = propertyName(callee.property); + return object === "" ? property : `${object}.${property}`; + } + return ""; +}; + +const stringArgument = ( + value: t.Node | null | undefined, +): string | undefined => (t.isStringLiteral(value) ? value.value : undefined); + +const propertyName = (value: t.Node): string => { + if (t.isIdentifier(value)) return value.name; + if (t.isStringLiteral(value)) return value.value; + return ""; +}; + +const objectValue = ( + object: t.ObjectExpression, + name: string, +): t.ObjectProperty["value"] | undefined => { + for (const property of object.properties) + if (t.isObjectProperty(property) && propertyName(property.key) === name) + return property.value; + return undefined; +}; + +const objectString = ( + object: t.ObjectExpression, + name: string, +): string | undefined => { + const value = objectValue(object, name); + return t.isStringLiteral(value) ? value.value : undefined; +}; + +const resolveSpecifier = (specifier: string, base: string): string | null => { + try { + const resolved = new URL(specifier, base); + if (resolved.protocol !== "http:" && resolved.protocol !== "https:") + return null; + return sanitizeBrowserUrl(resolved.href).url; + } catch { + return null; + } +}; + +const sanitizeCandidate = (value: string): string => { + const bounded = value.slice(0, 4_096); + try { + const parsed = new URL(bounded, "https://rea.invalid"); + const sanitized = sanitizeBrowserUrl(parsed.href).url; + return parsed.origin === "https://rea.invalid" + ? sanitized.replace("https://rea.invalid", "") + : sanitized; + } catch { + return bounded.split("#", 1)[0]?.split("?", 1)[0] ?? ""; + } +}; + +const location = (scriptKey: string, node: t.Node) => ({ + script_key: scriptKey, + ...locationFields(node), +}); + +const locationFields = (node: t.Node) => ({ + line: node.loc?.start.line ?? null, + column: node.loc?.start.column ?? null, +}); + +const basis = (script: IncludedScript, detector: string) => ({ + script_key: script.script_key, + artifact_sha256: script.source.artifact.sha256, + line: null, + column: null, + detector, +}); + +const emptyAccumulator = (): AnalysisAccumulator => ({ + edges: [], + routes: [], + endpoints: [], + webMcp: [], + inferences: [], + seen: new Set(), + visitedNodes: 0, + parsedScripts: 0, + parseFailures: 0, + droppedFindings: 0, + astLimitReached: false, +}); + +const isIncludedScript = (script: BrowserScript): script is IncludedScript => + script.source.included; + +const routeCallNames = [ + "route", + "addRoute", + "useRoutes", + "createBrowserRouter", + "createHashRouter", +] as const; + +const vendorDetectors: readonly { + readonly value: string; + readonly detector: string; + readonly patterns: readonly string[]; + readonly confidence: Inference["confidence"]; + readonly kind: Inference["kind"]; +}[] = [ + { + value: "webpack", + detector: "webpack-runtime", + patterns: ["__webpack_require__"], + confidence: "high", + kind: "bundle_runtime", + }, + { + value: "Vite", + detector: "vite-runtime", + patterns: ["__vite__", "import.meta.hot"], + confidence: "medium", + kind: "bundle_runtime", + }, + { + value: "React", + detector: "react-runtime", + patterns: ["__REACT_DEVTOOLS_GLOBAL_HOOK__", "React.createElement"], + confidence: "medium", + kind: "vendor_fingerprint", + }, + { + value: "Vue", + detector: "vue-runtime", + patterns: ["__VUE__", "createApp("], + confidence: "medium", + kind: "vendor_fingerprint", + }, + { + value: "Next.js", + detector: "next-runtime", + patterns: ["__NEXT_DATA__", "/_next/"], + confidence: "high", + kind: "vendor_fingerprint", + }, + { + value: "Angular", + detector: "angular-runtime", + patterns: ["ɵɵdefineComponent"], + confidence: "high", + kind: "vendor_fingerprint", + }, + { + value: "Svelte", + detector: "svelte-runtime", + patterns: ["svelte/internal"], + confidence: "medium", + kind: "vendor_fingerprint", + }, +]; diff --git a/src/domain/webCaptureDiff.ts b/src/domain/webCaptureDiff.ts new file mode 100644 index 000000000..a89b2bb0d --- /dev/null +++ b/src/domain/webCaptureDiff.ts @@ -0,0 +1,286 @@ +import { createHash } from "node:crypto"; + +import canonicalize from "canonicalize"; +import { z } from "zod"; + +import { + webPageInspectionSchema, + type WebPageInspection, +} from "./browserObservation.js"; +import { + webMcpDiscoverySchema, + type WebMcpDiscovery, +} from "./webMcpDiscovery.js"; + +const captureSnapshotSchema = z.object({ + inspection: webPageInspectionSchema, + webmcp: webMcpDiscoverySchema.nullable().default(null), +}); + +/** Input for deterministic comparison of two normalized web captures. */ +export const compareWebCapturesInputSchema = z.object({ + before: captureSnapshotSchema, + after: captureSnapshotSchema, + max_changes: z.number().int().min(1).max(20_000).default(2_000), +}); +export type CompareWebCapturesInput = z.infer< + typeof compareWebCapturesInputSchema +>; + +const changeSchema = z.object({ + identity: z.string(), + change: z.enum(["added", "removed", "modified"]), +}); +const dimensionSchema = z.object({ + status: z.enum(["changed", "unchanged", "unknown"]), + total_changes: z.number().int().min(0), + changes: z.array(changeSchema), + omitted_changes: z.number().int().min(0), + reason: z.string().nullable(), +}); + +/** Completeness-aware changes across stable browser evidence dimensions. */ +export const webCaptureDiffSchema = z.object({ + schema_version: z.literal(1), + overall_status: z.enum(["changed", "unchanged", "unknown"]), + before_target: z.object({ target_id: z.string(), url: z.string() }), + after_target: z.object({ target_id: z.string(), url: z.string() }), + dimensions: z.object({ + dom_structure: dimensionSchema, + scripts: dimensionSchema, + resources: dimensionSchema, + network: dimensionSchema, + metadata: dimensionSchema, + webmcp: dimensionSchema, + }), + limitations: z.array(z.string()), +}); +export type WebCaptureDiff = z.infer; +type Dimension = + WebCaptureDiff["dimensions"][keyof WebCaptureDiff["dimensions"]]; +type Change = Dimension["changes"][number]; + +/** Compare normalized observations without treating incomplete absence as proof. */ +export const compareWebCaptures = ( + input: CompareWebCapturesInput, +): WebCaptureDiff => { + let remaining = input.max_changes; + const dimension = ( + before: ReadonlyMap, + after: ReadonlyMap, + complete: boolean, + reason: string, + ): Dimension => { + const all = compareIdentities(before, after); + const retained = all.slice(0, remaining); + remaining -= retained.length; + return { + status: all.length > 0 ? "changed" : complete ? "unchanged" : "unknown", + total_changes: all.length, + changes: retained, + omitted_changes: all.length - retained.length, + reason: all.length === 0 && !complete ? reason : null, + }; + }; + const before = input.before.inspection; + const after = input.after.inspection; + const dimensions = { + dom_structure: dimension( + singleton("document", digest(domProjection(before))), + singleton("document", digest(domProjection(after))), + sectionsComplete(before, ["frames", "dom"]) && + sectionsComplete(after, ["frames", "dom"]), + "DOM or frame capture was incomplete in at least one observation.", + ), + scripts: dimension( + keyed( + before.scripts.items.map(scriptProjection), + (item) => item.script_key, + ), + keyed( + after.scripts.items.map(scriptProjection), + (item) => item.script_key, + ), + sectionsComplete(before, ["scripts"]) && + sectionsComplete(after, ["scripts"]), + "Script inventory was incomplete in at least one observation.", + ), + resources: dimension( + keyed(before.resources, (item) => item.resource_key), + keyed(after.resources, (item) => item.resource_key), + sectionsComplete(before, ["resources"]) && + sectionsComplete(after, ["resources"]), + "Resource inventory was incomplete in at least one observation.", + ), + network: dimension( + networkMap(before), + networkMap(after), + sectionsComplete(before, ["network_requests"]) && + sectionsComplete(after, ["network_requests"]), + "Network capture is attach-window limited or incomplete.", + ), + metadata: dimension( + singleton("metadata", digest(metadataProjection(before))), + singleton("metadata", digest(metadataProjection(after))), + sectionsComplete(before, ["metadata"]) && + sectionsComplete(after, ["metadata"]), + "Safe metadata capture was incomplete in at least one observation.", + ), + webmcp: dimension( + webMcpMap(input.before.webmcp), + webMcpMap(input.after.webmcp), + webMcpComplete(input.before.webmcp) && webMcpComplete(input.after.webmcp), + "WebMCP discovery was unavailable or incomplete in at least one capture.", + ), + }; + const statuses = Object.values(dimensions).map(({ status }) => status); + return webCaptureDiffSchema.parse({ + schema_version: 1, + overall_status: statuses.includes("changed") + ? "changed" + : statuses.includes("unknown") + ? "unknown" + : "unchanged", + before_target: { + target_id: before.target.target_id, + url: before.target.url, + }, + after_target: { + target_id: after.target.target_id, + url: after.target.url, + }, + dimensions, + limitations: [ + "A changed status proves an observed difference; an unknown status means absence could not be established from capture completeness.", + "Network comparison covers only activity observed after each CDP attachment.", + ], + }); +}; + +const compareIdentities = ( + before: ReadonlyMap, + after: ReadonlyMap, +): Change[] => { + const changes: Change[] = []; + for (const [identity, fingerprint] of before) { + const next = after.get(identity); + if (next === undefined) changes.push({ identity, change: "removed" }); + else if (next !== fingerprint) + changes.push({ identity, change: "modified" }); + } + for (const identity of after.keys()) + if (!before.has(identity)) changes.push({ identity, change: "added" }); + return changes.sort( + (left, right) => + left.identity.localeCompare(right.identity) || + left.change.localeCompare(right.change), + ); +}; + +const keyed = ( + values: readonly T[], + identity: (value: T) => string, +): ReadonlyMap => + new Map(values.map((value) => [identity(value), digest(value)])); + +const networkMap = ( + inspection: WebPageInspection, +): ReadonlyMap => { + const grouped = new Map(); + for (const request of inspection.network.requests) { + const identity = `net_${digest({ + method: request.method, + url: request.url, + resource_type: request.resource_type, + })}`; + const values = grouped.get(identity) ?? []; + values.push({ + status: request.status, + mime_type: request.mime_type, + encoded_data_length: request.encoded_data_length, + initiator: request.initiator, + body_shapes: request.body_shapes, + }); + grouped.set(identity, values); + } + return new Map( + [...grouped].map(([identity, values]) => [ + identity, + digest(values.map((value) => digest(value)).sort()), + ]), + ); +}; + +const webMcpMap = ( + discovery: WebMcpDiscovery | null, +): ReadonlyMap => + discovery === null + ? new Map() + : keyed(discovery.tools.items, (tool) => tool.tool_key); + +const webMcpComplete = (discovery: WebMcpDiscovery | null): boolean => + discovery !== null && + discovery.status === "available" && + !incompleteSections(discovery.completeness).has("webmcp_tools"); + +const sectionsComplete = ( + inspection: WebPageInspection, + sections: readonly string[], +): boolean => { + const incomplete = incompleteSections(inspection.completeness); + return sections.every((section) => !incomplete.has(section)); +}; + +const incompleteSections = (completeness: { + readonly policy_filtered_sections: readonly string[]; + readonly attach_limited_sections: readonly string[]; + readonly truncated_sections: readonly string[]; + readonly unavailable_sections: readonly string[]; +}): ReadonlySet => + new Set([ + ...completeness.policy_filtered_sections, + ...completeness.attach_limited_sections, + ...completeness.truncated_sections, + ...completeness.unavailable_sections, + ]); + +const domProjection = (inspection: WebPageInspection) => ({ + frames: inspection.frames + .map(({ url, origin }) => ({ url, origin })) + .sort((left, right) => left.url.localeCompare(right.url)), + nodes: inspection.dom.nodes.map(({ index: _index, ...node }) => node), +}); + +const scriptProjection = ( + script: WebPageInspection["scripts"]["items"][number], +) => ({ + script_key: script.script_key, + url: script.url, + cdp_hash: script.cdp_hash, + length: script.length, + is_module: script.is_module, + language: script.language, + source_map_url: script.source_map_url, +}); + +const metadataProjection = (inspection: WebPageInspection) => ({ + responses: inspection.metadata.responses + .map(({ request_id: _requestId, ...response }) => response) + .map((value) => digest(value)) + .sort(), + dom_urls: inspection.metadata.dom_urls.map((value) => digest(value)).sort(), + agent_hints: inspection.metadata.agent_hints + .map((value) => digest(value)) + .sort(), + excluded_dom_urls: inspection.metadata.excluded_dom_urls, + headers_allowlisted: inspection.metadata.headers_allowlisted, +}); + +const singleton = (key: string, value: string): ReadonlyMap => + new Map([[key, value]]); + +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"); +}; diff --git a/src/domain/webContentArtifact.ts b/src/domain/webContentArtifact.ts new file mode 100644 index 000000000..308d4d874 --- /dev/null +++ b/src/domain/webContentArtifact.ts @@ -0,0 +1,56 @@ +import { createHash } from "node:crypto"; + +import { z } from "zod"; + +/** Self-verifying text artifact used by web-source analysis boundaries. */ +export const webTextArtifactSchema = z + .object({ + uri: z.string().regex(/^rea:\/\/web-content\/sha256\/[a-f0-9]{64}$/u), + sha256: z.string().regex(/^[a-f0-9]{64}$/u), + bytes: z.number().int().min(0), + media_type: z.string().min(1).max(256), + charset: z.literal("utf-8"), + text: z.string(), + }) + .superRefine((artifact, context) => { + const bytes = Buffer.byteLength(artifact.text); + const digest = createHash("sha256").update(artifact.text).digest("hex"); + if (artifact.bytes !== bytes) + context.addIssue({ + code: "custom", + path: ["bytes"], + message: "Byte count mismatch", + }); + if (artifact.sha256 !== digest) + context.addIssue({ + code: "custom", + path: ["sha256"], + message: "Digest mismatch", + }); + if (artifact.uri !== webContentUri(digest)) + context.addIssue({ + code: "custom", + path: ["uri"], + message: "Content URI mismatch", + }); + }); +export type WebTextArtifact = z.infer; + +/** Build an immutable content-addressed UTF-8 text artifact. */ +export const createWebTextArtifact = ( + text: string, + mediaType: string, +): WebTextArtifact => { + const sha256 = createHash("sha256").update(text).digest("hex"); + return { + uri: webContentUri(sha256), + sha256, + bytes: Buffer.byteLength(text), + media_type: mediaType, + charset: "utf-8", + text, + }; +}; + +const webContentUri = (sha256: string): string => + `rea://web-content/sha256/${sha256}`; diff --git a/src/domain/webInventory.ts b/src/domain/webInventory.ts new file mode 100644 index 000000000..d3f8a2edb --- /dev/null +++ b/src/domain/webInventory.ts @@ -0,0 +1,120 @@ +import { createHash } from "node:crypto"; + +import canonicalize from "canonicalize"; + +export interface WebInventoryResourceInput { + readonly url: string; + readonly origin: string | null; + readonly type: string; + readonly mime_type: string; + readonly content_size: number | null; +} + +export interface WebInventoryScriptInput { + readonly url: string; + readonly cdp_hash: string; + readonly length: number; + readonly is_module: boolean; + readonly language: string | null; + readonly source_map_url: string | null; +} + +export interface StableWebResource extends WebInventoryResourceInput { + readonly resource_key: string; +} + +export type WebResourceReconciliation = + | { readonly status: "exact"; readonly resource_key: string } + | { readonly status: "ambiguous"; readonly candidate_resource_keys: string[] } + | { readonly status: "unmatched"; readonly reason: "no_exact_sanitized_url" }; + +/** Assign deterministic identities to a bounded resource inventory. */ +export const stableWebResources = ( + resources: readonly WebInventoryResourceInput[], +): StableWebResource[] => { + const keyed = resources.map((resource) => ({ + ...resource, + resource_key: `res_${digest(resource)}`, + })); + return [ + ...new Map( + keyed.map((resource) => [resource.resource_key, resource]), + ).values(), + ].sort( + (left, right) => + left.resource_key.localeCompare(right.resource_key) || + left.url.localeCompare(right.url), + ); +}; + +/** Reconcile one script with resource-tree observations without fuzzy matching. */ +export const reconcileWebScript = ( + script: WebInventoryScriptInput, + resources: readonly StableWebResource[], +): WebResourceReconciliation => { + const candidates = resources.filter( + (resource) => resource.url === script.url, + ); + if (candidates.length === 1) + return { status: "exact", resource_key: candidates[0]?.resource_key ?? "" }; + if (candidates.length > 1) + return { + status: "ambiguous", + candidate_resource_keys: uniqueResourceKeys(candidates), + }; + return { status: "unmatched", reason: "no_exact_sanitized_url" }; +}; + +/** Prefer exact transient raw-URL matching, then report sanitized ambiguity. */ +export const reconcileCapturedWebScript = ( + script: WebInventoryScriptInput & { readonly rawUrl: string }, + rawResources: readonly (WebInventoryResourceInput & { + readonly rawUrl: string; + })[], + resources: readonly StableWebResource[], +): WebResourceReconciliation => { + const exact = rawResources.filter( + (resource) => resource.rawUrl === script.rawUrl, + ); + if (exact.length === 1) { + const resource = exact[0]; + if (resource !== undefined) { + const { rawUrl: _rawUrl, ...publicResource } = resource; + const stable = stableWebResources([publicResource])[0]; + if (stable !== undefined) + return { status: "exact", resource_key: stable.resource_key }; + } + } + const candidates = resources.filter( + (resource) => resource.url === script.url, + ); + if (candidates.length > 0) + return { + status: "ambiguous", + candidate_resource_keys: uniqueResourceKeys(candidates), + }; + return { status: "unmatched", reason: "no_exact_sanitized_url" }; +}; + +/** Stable script identity excludes target IDs, CDP script IDs, and timestamps. */ +export const stableWebScriptKey = (script: WebInventoryScriptInput): string => + `scr_${digest({ + url: script.url, + cdp_hash: script.cdp_hash, + length: script.length, + is_module: script.is_module, + language: script.language, + source_map_url: script.source_map_url, + })}`; + +const uniqueResourceKeys = ( + resources: readonly StableWebResource[], +): string[] => + [...new Set(resources.map(({ resource_key }) => resource_key))].sort(); + +const digest = (value: unknown): string => { + const encoded = canonicalize(value); + if (encoded === undefined) + throw new TypeError("Web inventory value is not canonical JSON"); + return createHash("sha256").update(encoded).digest("hex"); +}; diff --git a/src/domain/webMcpDiscovery.ts b/src/domain/webMcpDiscovery.ts new file mode 100644 index 000000000..ad3a4bde0 --- /dev/null +++ b/src/domain/webMcpDiscovery.ts @@ -0,0 +1,80 @@ +import { z } from "zod"; + +import { browserCompletenessSchema } from "./browserCompleteness.js"; +import { + browserAllowedOriginsSchema, + browserEndpointSchema, +} from "./browserObservation.js"; +import { jsonShapeSchema } from "./jsonShape.js"; + +/** Input for passive discovery of page-registered WebMCP tools. */ +export const discoverWebMcpToolsInputSchema = z.object({ + cdp_endpoint: browserEndpointSchema, + allowed_origins: browserAllowedOriginsSchema, + target_id: z.string().trim().min(1).max(256), + approved: z.literal(true), + observation_ms: z.number().int().min(0).max(10_000).default(100), + max_tools: z.number().int().min(1).max(5_000).default(500), + max_schema_bytes: z + .number() + .int() + .min(1) + .max(1_024 * 1_024) + .default(256 * 1_024), + max_schema_nodes: z.number().int().min(1).max(100_000).default(5_000), + max_schema_depth: z.number().int().min(1).max(100).default(20), +}); +export type DiscoverWebMcpToolsInput = z.infer< + typeof discoverWebMcpToolsInputSchema +>; + +const browserVersionSchema = z.object({ + product: z.string(), + protocol_version: z.string(), + revision: z.string(), + user_agent: z.string(), + js_version: z.string(), +}); + +const webMcpToolSchema = z.object({ + tool_key: z.string().regex(/^webmcp_[a-f0-9]{64}$/u), + name: z.string(), + description: z.string(), + frame_id: z.string(), + frame_url: z.string(), + owner_origin: z.string(), + declaration_kind: z.enum(["declarative", "imperative"]), + input_schema_shape: jsonShapeSchema.nullable(), + annotations: z.object({ + read_only: z.boolean().nullable(), + untrusted_content: z.boolean().nullable(), + autosubmit: z.boolean().nullable(), + }), + registration_source: z + .object({ + url: z.string(), + line: z.number().int().min(0).nullable(), + column: z.number().int().min(0).nullable(), + }) + .nullable(), + trust: z.literal("page-declared-untrusted"), +}); + +/** Passive WebMCP inventory; it intentionally has no invocation surface. */ +export const webMcpDiscoverySchema = z.object({ + schema_version: z.literal(1), + browser: browserVersionSchema, + target: z.object({ + target_id: z.string(), + url: z.string(), + origin: z.string(), + }), + status: z.enum(["available", "unavailable"]), + tools: z.object({ + total: z.number().int().min(0), + items: z.array(webMcpToolSchema), + }), + completeness: browserCompletenessSchema, + limitations: z.array(z.string()), +}); +export type WebMcpDiscovery = z.infer; diff --git a/src/domain/webScreenshot.ts b/src/domain/webScreenshot.ts new file mode 100644 index 000000000..7ae7a5645 --- /dev/null +++ b/src/domain/webScreenshot.ts @@ -0,0 +1,142 @@ +import { createHash } from "node:crypto"; + +import { z } from "zod"; + +import { browserCompletenessSchema } from "./browserCompleteness.js"; +import { + browserAllowedOriginsSchema, + browserEndpointSchema, +} from "./browserObservation.js"; + +const MAX_SCREENSHOT_BYTES = 8 * 1_024 * 1_024; + +/** Self-verifying inline PNG artifact for CLI/MCP parity. */ +const webScreenshotArtifactSchema = z + .object({ + uri: z.string().regex(/^rea:\/\/web-screenshot\/sha256\/[a-f0-9]{64}$/u), + sha256: z.string().regex(/^[a-f0-9]{64}$/u), + bytes: z.number().int().min(1).max(MAX_SCREENSHOT_BYTES), + media_type: z.literal("image/png"), + data_base64: z.string().max(Math.ceil((MAX_SCREENSHOT_BYTES * 4) / 3) + 4), + }) + .superRefine((artifact, context) => { + const bytes = decodeCanonicalBase64(artifact.data_base64); + if (bytes === undefined) { + context.addIssue({ code: "custom", message: "Invalid canonical base64" }); + return; + } + const sha256 = createHash("sha256").update(bytes).digest("hex"); + if ( + bytes.byteLength !== artifact.bytes || + sha256 !== artifact.sha256 || + artifact.uri !== `rea://web-screenshot/sha256/${sha256}` + ) + context.addIssue({ + code: "custom", + message: "Screenshot artifact digest or size mismatch", + }); + }); +export type WebScreenshotArtifact = z.infer; + +/** Input for one read-only visible-viewport screenshot. */ +export const captureWebScreenshotInputSchema = z.object({ + cdp_endpoint: browserEndpointSchema, + allowed_origins: browserAllowedOriginsSchema, + target_id: z.string().trim().min(1).max(256), + approved: z.literal(true), + screenshot_approved: z.literal(true), + maximum_image_bytes: z + .number() + .int() + .min(1) + .max(MAX_SCREENSHOT_BYTES) + .default(4 * 1_024 * 1_024), +}); +export type CaptureWebScreenshotInput = z.infer< + typeof captureWebScreenshotInputSchema +>; + +const browserVersionSchema = z.object({ + product: z.string(), + protocol_version: z.string(), + revision: z.string(), + user_agent: z.string(), + js_version: z.string(), +}); + +/** Bounded screenshot observation with embedded immutable artifact bytes. */ +export const webScreenshotSchema = z.object({ + schema_version: z.literal(1), + browser: browserVersionSchema, + target: z.object({ + target_id: z.string(), + url: z.string(), + origin: z.string(), + }), + captured_at: z.iso.datetime(), + viewport: z.object({ + width: z.number().int().min(1), + height: z.number().int().min(1), + }), + artifact: webScreenshotArtifactSchema, + completeness: browserCompletenessSchema, + limitations: z.array(z.string()), +}); +export type WebScreenshot = z.infer; + +/** Input for bounded local pixel comparison of two screenshot artifacts. */ +export const compareWebScreenshotsInputSchema = z.object({ + before: webScreenshotArtifactSchema, + after: webScreenshotArtifactSchema, + channel_threshold: z.number().int().min(0).max(255).default(0), + maximum_pixels: z.number().int().min(1).max(32_000_000).default(16_000_000), +}); +export type CompareWebScreenshotsInput = z.infer< + typeof compareWebScreenshotsInputSchema +>; + +/** Value-only visual difference metrics; no OCR or image mutation. */ +export const webScreenshotDiffSchema = z.object({ + schema_version: z.literal(1), + status: z.enum(["identical", "different", "dimension_mismatch"]), + before: z.object({ + width: z.number().int().min(1), + height: z.number().int().min(1), + }), + after: z.object({ + width: z.number().int().min(1), + height: z.number().int().min(1), + }), + channel_threshold: z.number().int().min(0).max(255), + compared_pixels: z.number().int().min(0), + changed_pixels: z.number().int().min(0).nullable(), + changed_ratio: z.number().min(0).max(1).nullable(), + maximum_channel_delta: z.number().int().min(0).max(255).nullable(), + mean_absolute_channel_delta: z.number().min(0).max(255).nullable(), + limitations: z.array(z.string()), +}); +export type WebScreenshotDiff = z.infer; + +/** Create a content-addressed PNG artifact from already bounded bytes. */ +export const createWebScreenshotArtifact = ( + bytes: Buffer, +): WebScreenshotArtifact => { + const sha256 = createHash("sha256").update(bytes).digest("hex"); + return webScreenshotArtifactSchema.parse({ + uri: `rea://web-screenshot/sha256/${sha256}`, + sha256, + bytes: bytes.byteLength, + media_type: "image/png", + data_base64: bytes.toString("base64"), + }); +}; + +/** Strict canonical base64 decoder used before digest validation. */ +export const decodeCanonicalBase64 = (value: string): Buffer | undefined => { + if (value.length === 0 || value.length % 4 !== 0 || !BASE64.test(value)) + return undefined; + const decoded = Buffer.from(value, "base64"); + return decoded.toString("base64") === value ? decoded : undefined; +}; + +const BASE64 = /^(?:[A-Za-z\d+/]{4})*(?:[A-Za-z\d+/]{2}==|[A-Za-z\d+/]{3}=)?$/u; diff --git a/src/generatedPackageMetadata.ts b/src/generatedPackageMetadata.ts index 3c11aee90..94b9d2129 100644 --- a/src/generatedPackageMetadata.ts +++ b/src/generatedPackageMetadata.ts @@ -1,9 +1,9 @@ /** Generated from package.json and package-lock.json; do not edit. */ export const PACKAGE_METADATA = { name: "rea-agents", - version: "1.4.0", + version: "1.5.0", serverSdkVersion: "2.0.0-beta.4", clientSdkVersion: "2.0.0-beta.4", coreSdkVersion: "2.0.0-beta.4", - skillVersion: "13", + skillVersion: "14", } as const; diff --git a/src/main.ts b/src/main.ts index 05d06b301..7fc4a2c7e 100644 --- a/src/main.ts +++ b/src/main.ts @@ -16,6 +16,7 @@ import { projectAnalysisError } from "./domain/errors.js"; import { readProjectPermissionStore } from "./application/ProjectPermissionStore.js"; import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js"; import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js"; +import { CdpElectronProvider } from "./browser/CdpElectronProvider.js"; const MCP_CONNECTION_LOST = "REA lost its MCP client connection. Restart REA from your MCP client."; @@ -82,6 +83,7 @@ export const run = async ( const session = createBinarySession(config.value, logger); const browserObservation = new CdpBrowserProvider(); + const electronObservation = new CdpElectronProvider(); if (config.value.hopperTargetPath !== undefined) { const opened = await session.open(config.value.hopperTargetPath, { targetKind: config.value.hopperTargetKind, @@ -129,6 +131,7 @@ export const run = async ( analysisSnapshotFilePolicy: runtimeSnapshotPolicy, permissionAuthority: permissionAuthority.value, browserObservation, + electronObservation, artifactIntegrityContinueEnabled: () => currentConfig.artifactIntegrityContinueEnabled, availabilityPolicy: () => ({ @@ -138,6 +141,10 @@ export const run = async ( currentConfig.browserObservationEnabled && currentConfig.browserCdpEndpoints.length > 0 && currentConfig.browserAllowedOrigins.length > 0, + electronObservationEnabled: + currentConfig.electronObservationEnabled && + currentConfig.electronCdpEndpoints.length > 0 && + currentConfig.electronFileRoots.length > 0, }), }); liveServers.add(server); diff --git a/src/server/createServer.ts b/src/server/createServer.ts index e14dfc392..97aface5e 100644 --- a/src/server/createServer.ts +++ b/src/server/createServer.ts @@ -17,6 +17,8 @@ import { createServerIdentity } from "../serverIdentity.js"; import type { PermissionAuthority } from "../application/PermissionAuthority.js"; import type { BrowserObservationPort } from "../application/BrowserObservationPort.js"; import { registerBrowserTools } from "./registerBrowserTools.js"; +import type { ElectronObservationPort } from "../application/ElectronObservationPort.js"; +import { registerElectronTools } from "./registerElectronTools.js"; export interface CreateServerOptions { readonly logger?: Logger; @@ -26,11 +28,13 @@ export interface CreateServerOptions { readonly analysisSnapshotFilePolicy?: EvidenceFilePolicy; readonly permissionAuthority?: PermissionAuthority; readonly browserObservation?: BrowserObservationPort; + readonly electronObservation?: ElectronObservationPort; readonly artifactIntegrityContinueEnabled?: () => boolean; readonly availabilityPolicy?: () => { readonly processCaptureEnabled: boolean; readonly evidenceFileRoots: number; readonly browserObservationEnabled?: boolean; + readonly electronObservationEnabled?: boolean; }; } @@ -146,6 +150,12 @@ export const createServer = ( permissionAuthority: options.permissionAuthority, recordEvidence, }); + registerElectronTools(server, { + logger: toolLogger, + electron: options.electronObservation, + permissionAuthority: options.permissionAuthority, + recordEvidence, + }); registerGuidedPrompts(server, analysis, session); if (session !== undefined) { registerEvidenceResources(server, session); diff --git a/src/server/registerBrowserTools.ts b/src/server/registerBrowserTools.ts index 93e5bb0b8..d88ef4e82 100644 --- a/src/server/registerBrowserTools.ts +++ b/src/server/registerBrowserTools.ts @@ -4,14 +4,28 @@ import type { BrowserObservationPort } from "../application/BrowserObservationPo import type { BinarySessionPort } from "../application/BinarySession.js"; import type { PermissionAuthority } from "../application/PermissionAuthority.js"; import { + analyzeWebBundle, + captureWebScreenshot, + compareWebCaptureEvidence, + compareWebScreenshotEvidence, + discoverWebMcpTools, inspectWebPage, listBrowserTargets, + observeWebSession, } from "../application/BrowserObservationService.js"; import { BROWSER_TOOL_CONTRACTS } from "../contracts/browserToolContracts.js"; import { inspectWebPageInputSchema, listBrowserTargetsInputSchema, } from "../domain/browserObservation.js"; +import { analyzeWebBundleInputSchema } from "../domain/webBundleAnalysis.js"; +import { observeWebSessionInputSchema } from "../domain/browserSession.js"; +import { discoverWebMcpToolsInputSchema } from "../domain/webMcpDiscovery.js"; +import { compareWebCapturesInputSchema } from "../domain/webCaptureDiff.js"; +import { + captureWebScreenshotInputSchema, + compareWebScreenshotsInputSchema, +} from "../domain/webScreenshot.js"; import type { Logger } from "../logger.js"; import { logToolExecution } from "./toolLogging.js"; import { toCallToolResult } from "./toolResult.js"; @@ -30,7 +44,16 @@ export const registerBrowserTools = ( server: McpServer, options: BrowserToolRegistration, ): void => { - const [listContract, inspectContract] = BROWSER_TOOL_CONTRACTS; + const [ + listContract, + inspectContract, + analyzeContract, + sessionContract, + webMcpContract, + captureDiffContract, + screenshotContract, + screenshotDiffContract, + ] = BROWSER_TOOL_CONTRACTS; server.registerTool( listContract.name, toolRegistrationOptions(listContract), @@ -69,6 +92,126 @@ export const registerBrowserTools = ( return evidenceResult(options, inspectContract, result.value); }, ); + server.registerTool( + analyzeContract.name, + toolRegistrationOptions(analyzeContract), + async (input, context) => { + const parsed = analyzeWebBundleInputSchema.parse(input); + const result = await logToolExecution( + options.logger, + analyzeContract.name, + () => + analyzeWebBundle( + options.browser, + options.permissionAuthority, + parsed, + { + signal: context.mcpReq.signal, + progress: mcpProgressReporter(context), + }, + ), + ); + if (!result.ok) return toCallToolResult(result, analyzeContract); + return evidenceResult(options, analyzeContract, result.value); + }, + ); + server.registerTool( + sessionContract.name, + toolRegistrationOptions(sessionContract), + async (input, context) => { + const parsed = observeWebSessionInputSchema.parse(input); + const result = await logToolExecution( + options.logger, + sessionContract.name, + () => + observeWebSession( + options.browser, + options.permissionAuthority, + parsed, + { + signal: context.mcpReq.signal, + progress: mcpProgressReporter(context), + }, + ), + ); + if (!result.ok) return toCallToolResult(result, sessionContract); + return evidenceResult(options, sessionContract, result.value); + }, + ); + server.registerTool( + webMcpContract.name, + toolRegistrationOptions(webMcpContract), + async (input, context) => { + const parsed = discoverWebMcpToolsInputSchema.parse(input); + const result = await logToolExecution( + options.logger, + webMcpContract.name, + () => + discoverWebMcpTools( + options.browser, + options.permissionAuthority, + parsed, + { + signal: context.mcpReq.signal, + progress: mcpProgressReporter(context), + }, + ), + ); + if (!result.ok) return toCallToolResult(result, webMcpContract); + return evidenceResult(options, webMcpContract, result.value); + }, + ); + server.registerTool( + captureDiffContract.name, + toolRegistrationOptions(captureDiffContract), + async (input) => { + const parsed = compareWebCapturesInputSchema.parse(input); + const result = await logToolExecution( + options.logger, + captureDiffContract.name, + () => compareWebCaptureEvidence(options.browser, parsed), + ); + if (!result.ok) return toCallToolResult(result, captureDiffContract); + return evidenceResult(options, captureDiffContract, result.value); + }, + ); + server.registerTool( + screenshotContract.name, + toolRegistrationOptions(screenshotContract), + async (input, context) => { + const parsed = captureWebScreenshotInputSchema.parse(input); + const result = await logToolExecution( + options.logger, + screenshotContract.name, + () => + captureWebScreenshot( + options.browser, + options.permissionAuthority, + parsed, + { + signal: context.mcpReq.signal, + progress: mcpProgressReporter(context), + }, + ), + ); + if (!result.ok) return toCallToolResult(result, screenshotContract); + return evidenceResult(options, screenshotContract, result.value); + }, + ); + server.registerTool( + screenshotDiffContract.name, + toolRegistrationOptions(screenshotDiffContract), + async (input) => { + const parsed = compareWebScreenshotsInputSchema.parse(input); + const result = await logToolExecution( + options.logger, + screenshotDiffContract.name, + () => compareWebScreenshotEvidence(options.browser, parsed), + ); + if (!result.ok) return toCallToolResult(result, screenshotDiffContract); + return evidenceResult(options, screenshotDiffContract, result.value); + }, + ); }; const evidenceResult = ( diff --git a/src/server/registerElectronTools.ts b/src/server/registerElectronTools.ts new file mode 100644 index 000000000..edec00c84 --- /dev/null +++ b/src/server/registerElectronTools.ts @@ -0,0 +1,90 @@ +import type { McpServer } from "@modelcontextprotocol/server"; + +import type { BinarySessionPort } from "../application/BinarySession.js"; +import type { ElectronObservationPort } from "../application/ElectronObservationPort.js"; +import { + inspectElectronPage, + listElectronTargets, +} from "../application/ElectronObservationService.js"; +import type { PermissionAuthority } from "../application/PermissionAuthority.js"; +import { ELECTRON_TOOL_CONTRACTS } from "../contracts/electronToolContracts.js"; +import { + inspectElectronPageInputSchema, + listElectronTargetsInputSchema, +} from "../domain/electronObservation.js"; +import type { Logger } from "../logger.js"; +import { logToolExecution } from "./toolLogging.js"; +import { toCallToolResult } from "./toolResult.js"; +import { toolRegistrationOptions } from "./toolRegistrationOptions.js"; +import { mcpProgressReporter } from "./mcpProgress.js"; + +interface ElectronToolRegistration { + readonly logger: Logger; + readonly electron: ElectronObservationPort | undefined; + readonly permissionAuthority: PermissionAuthority | undefined; + readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined; +} + +/** Register Electron tools even when provider or permission policy is absent. */ +export const registerElectronTools = ( + server: McpServer, + options: ElectronToolRegistration, +): void => { + const [listContract, inspectContract] = ELECTRON_TOOL_CONTRACTS; + server.registerTool( + listContract.name, + toolRegistrationOptions(listContract), + async (input, context) => { + const parsed = listElectronTargetsInputSchema.parse(input); + const result = await logToolExecution( + options.logger, + listContract.name, + () => + listElectronTargets( + options.electron, + options.permissionAuthority, + parsed, + { signal: context.mcpReq.signal }, + ), + ); + if (!result.ok) return toCallToolResult(result, listContract); + return evidenceResult(options, listContract, result.value); + }, + ); + server.registerTool( + inspectContract.name, + toolRegistrationOptions(inspectContract), + async (input, context) => { + const parsed = inspectElectronPageInputSchema.parse(input); + const result = await logToolExecution( + options.logger, + inspectContract.name, + () => + inspectElectronPage( + options.electron, + options.permissionAuthority, + parsed, + { + signal: context.mcpReq.signal, + progress: mcpProgressReporter(context), + }, + ), + ); + if (!result.ok) return toCallToolResult(result, inspectContract); + return evidenceResult(options, inspectContract, result.value); + }, + ); +}; + +const evidenceResult = ( + options: ElectronToolRegistration, + contract: (typeof ELECTRON_TOOL_CONTRACTS)[number], + evidence: import("../domain/evidence.js").Evidence, +) => { + const recorded = options.recordEvidence?.(evidence); + return recorded !== undefined && !recorded.ok + ? toCallToolResult(recorded, contract) + : toCallToolResult({ ok: true, value: evidence }, contract, { + evidenceResourcesAvailable: recorded !== undefined, + }); +}; diff --git a/src/server/registerSessionStatusTool.ts b/src/server/registerSessionStatusTool.ts index aba0a6f7d..6a498ce47 100644 --- a/src/server/registerSessionStatusTool.ts +++ b/src/server/registerSessionStatusTool.ts @@ -20,6 +20,7 @@ export const registerSessionStatusTool = ( readonly processCaptureEnabled: boolean; readonly evidenceFileRoots: number; readonly browserObservationEnabled?: boolean; + readonly electronObservationEnabled?: boolean; }, ): void => { server.registerTool( diff --git a/src/server/registerSessionTools.ts b/src/server/registerSessionTools.ts index 557be110c..f4bbe946f 100644 --- a/src/server/registerSessionTools.ts +++ b/src/server/registerSessionTools.ts @@ -438,6 +438,7 @@ interface LifecycleToolRegistration { readonly processCaptureEnabled: boolean; readonly evidenceFileRoots: number; readonly browserObservationEnabled?: boolean; + readonly electronObservationEnabled?: boolean; }; readonly permissionAuthority?: PermissionAuthority; } @@ -599,6 +600,7 @@ export interface SessionToolOptions { readonly processCaptureEnabled: boolean; readonly evidenceFileRoots: number; readonly browserObservationEnabled?: boolean; + readonly electronObservationEnabled?: boolean; }; } @@ -646,6 +648,7 @@ export const registerSessionTools = ( processCaptureEnabled: processPolicy.enabled, evidenceFileRoots: evidenceFilePolicy.roots.length, browserObservationEnabled: false, + electronObservationEnabled: false, })), ...(options.permissionAuthority === undefined ? {} diff --git a/tests/browserCli.test.ts b/tests/browserCli.test.ts index 6d4177bd4..36880527a 100644 --- a/tests/browserCli.test.ts +++ b/tests/browserCli.test.ts @@ -10,7 +10,7 @@ import { const execute = promisify(execFile); const browsers: FakeCdpBrowser[] = []; -const INTEGRATION_TEST_TIMEOUT_MS = 20_000; +const INTEGRATION_TEST_TIMEOUT_MS = 40_000; afterEach(async () => { await Promise.all(browsers.splice(0).map(async (browser) => browser.close())); @@ -20,7 +20,11 @@ describe("browser CLI parity", () => { it( "returns the same Evidence v2 discovery and inspection contracts", async () => { - const browser = await startFakeCdpBrowser(); + const browser = await startFakeCdpBrowser({ + sessionTimeline: "same_origin", + webMcpTools: true, + sensitiveShapes: true, + }); browsers.push(browser); const environment = { ...process.env, @@ -49,6 +53,12 @@ describe("browser CLI parity", () => { "--approved", "--observation-ms", "0", + "--include-console-text", + "--console-text-approved", + "--include-json-body-shapes", + "--json-body-schema-approved", + "--include-websocket-shapes", + "--websocket-shape-approved", "--json", ], environment, @@ -58,9 +68,122 @@ describe("browser CLI parity", () => { provider: { id: "rea-cdp-browser" }, normalized_result: { target: { target_id: "allowed-page" }, - network: { prior_activity_available: false }, + network: { + prior_activity_available: false, + requests: [ + expect.objectContaining({ + body_shapes: expect.objectContaining({ status: "included" }), + }), + ], + }, }, }); + const inspection = normalizedResult(inspected); + const compared = await runCli( + [ + "compare-web-captures", + JSON.stringify({ inspection }), + JSON.stringify({ inspection }), + "--json", + ], + environment, + ); + expect(compared).toMatchObject({ + operation: "compare_web_captures", + normalized_result: { + overall_status: "unknown", + dimensions: { + network: { status: "unknown", total_changes: 0 }, + }, + }, + }); + const analyzed = await runCli( + [ + "analyze-web-bundle", + browser.endpoint, + "allowed-page", + "--approved", + "--source-capture-approved", + "--observation-ms", + "0", + "--json", + ], + environment, + ); + expect(analyzed).toMatchObject({ + operation: "analyze_web_bundle", + normalized_result: { + capture: { scripts_analyzed: 1 }, + observations: { source_maps: { status: "not_requested" } }, + }, + }); + const observedSession = await runCli( + [ + "observe-web-session", + browser.endpoint, + "allowed-page", + "--approved", + "--observation-ms", + "5", + "--json", + ], + environment, + ); + expect(observedSession).toMatchObject({ + operation: "observe_web_session", + normalized_result: { + window: { end_reason: "window_elapsed" }, + timeline: expect.arrayContaining([ + expect.objectContaining({ type: "same_origin_reload" }), + ]), + }, + }); + const webMcp = await runCli( + [ + "discover-webmcp-tools", + browser.endpoint, + "allowed-page", + "--approved", + "--observation-ms", + "0", + "--json", + ], + environment, + ); + expect(webMcp).toMatchObject({ + operation: "discover_webmcp_tools", + normalized_result: { + tools: { + items: [expect.objectContaining({ name: "search_orders" })], + }, + }, + }); + const screenshot = await runCli( + [ + "capture-web-screenshot", + browser.endpoint, + "allowed-page", + "--approved", + "--screenshot-approved", + "--json", + ], + environment, + ); + const artifact = screenshotArtifact(screenshot); + expect(artifact).toMatchObject({ media_type: "image/png", bytes: 70 }); + const visual = await runCli( + [ + "compare-web-screenshots", + JSON.stringify(artifact), + JSON.stringify(artifact), + "--json", + ], + environment, + ); + expect(visual).toMatchObject({ + operation: "compare_web_screenshots", + normalized_result: { status: "identical", changed_pixels: 0 }, + }); const policy = await runCli( [ "policy", @@ -137,3 +260,22 @@ const runCli = async ( throw cause; } }; + +const screenshotArtifact = (value: unknown): Record => { + if ( + !isRecord(value) || + !isRecord(value.normalized_result) || + !isRecord(value.normalized_result.artifact) + ) + throw new TypeError("Missing CLI screenshot artifact"); + return value.normalized_result.artifact; +}; + +const normalizedResult = (value: unknown): Record => { + if (!isRecord(value) || !isRecord(value.normalized_result)) + throw new TypeError("Missing CLI normalized result"); + return value.normalized_result; +}; + +const isRecord = (value: unknown): value is Record => + typeof value === "object" && value !== null && !Array.isArray(value); diff --git a/tests/browserMcp.test.ts b/tests/browserMcp.test.ts index 948711765..cfc781f2c 100644 --- a/tests/browserMcp.test.ts +++ b/tests/browserMcp.test.ts @@ -27,14 +27,29 @@ describe("browser MCP tools", () => { it( "exposes CLI-equivalent Evidence v2 and session resources", async () => { - const browser = await startFakeCdpBrowser(); + const browser = await startFakeCdpBrowser({ + sessionTimeline: "same_origin", + webMcpTools: true, + sensitiveShapes: true, + }); browsers.push(browser); const connected = await connectBrowser(browser); const tools = await connected.client.listTools(); - expect(tools.tools).toHaveLength(70); + expect(tools.tools).toHaveLength(78); expect(tools.tools.map(({ name }) => name)).toEqual( - expect.arrayContaining(["list_browser_targets", "inspect_web_page"]), + expect.arrayContaining([ + "list_browser_targets", + "inspect_web_page", + "analyze_web_bundle", + "observe_web_session", + "discover_webmcp_tools", + "compare_web_captures", + "capture_web_screenshot", + "compare_web_screenshots", + "list_electron_targets", + "inspect_electron_page", + ]), ); const status = await connected.client.callTool({ name: "binary_session", @@ -65,7 +80,7 @@ describe("browser MCP tools", () => { authority: "external-service", confidence: "observed", subject: null, - provider: { id: "rea-cdp-browser", version: "1" }, + provider: { id: "rea-cdp-browser", version: "2" }, normalized_result: { targets: { items: [{ target_id: "allowed-page" }] }, }, @@ -78,6 +93,12 @@ describe("browser MCP tools", () => { target_id: "allowed-page", approved: true, observation_ms: 0, + include_console_text: true, + console_text_approved: true, + include_json_body_shapes: true, + json_body_schema_approved: true, + include_websocket_shapes: true, + websocket_shape_approved: true, }, }); expect(inspected.isError).not.toBe(true); @@ -85,10 +106,112 @@ describe("browser MCP tools", () => { operation: "inspect_web_page", normalized_result: { target: { target_id: "allowed-page" }, - network: { prior_activity_available: false }, console: { prior_activity_available: false }, + network: { + prior_activity_available: false, + requests: [ + expect.objectContaining({ + body_shapes: expect.objectContaining({ status: "included" }), + }), + ], + }, }, }); + const analyzed = await connected.client.callTool({ + name: "analyze_web_bundle", + arguments: { + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + source_capture_approved: true, + observation_ms: 0, + }, + }); + expect(analyzed.isError).not.toBe(true); + expect(analyzed.structuredContent).toMatchObject({ + operation: "analyze_web_bundle", + normalized_result: { + capture: { scripts_analyzed: 1 }, + observations: { source_maps: { status: "not_requested" } }, + }, + }); + const observedSession = await connected.client.callTool({ + name: "observe_web_session", + arguments: { + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 5, + }, + }); + expect(observedSession.isError).not.toBe(true); + expect(observedSession.structuredContent).toMatchObject({ + operation: "observe_web_session", + normalized_result: { + window: { end_reason: "window_elapsed" }, + timeline: expect.arrayContaining([ + expect.objectContaining({ type: "same_origin_reload" }), + ]), + }, + }); + const webMcp = await connected.client.callTool({ + name: "discover_webmcp_tools", + arguments: { + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + }, + }); + expect(webMcp.isError).not.toBe(true); + expect(webMcp.structuredContent).toMatchObject({ + operation: "discover_webmcp_tools", + normalized_result: { + tools: { + items: [expect.objectContaining({ name: "search_orders" })], + }, + }, + }); + const capture = normalizedResultOf(inspected.structuredContent); + const compared = await connected.client.callTool({ + name: "compare_web_captures", + arguments: { + before: { inspection: capture }, + after: { inspection: capture }, + }, + }); + expect(compared.isError).not.toBe(true); + expect(compared.structuredContent).toMatchObject({ + operation: "compare_web_captures", + normalized_result: { overall_status: "unknown" }, + }); + const screenshot = await connected.client.callTool({ + name: "capture_web_screenshot", + arguments: { + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + screenshot_approved: true, + }, + }); + expect(screenshot.isError).not.toBe(true); + const screenshotArtifact = artifactOf(screenshot.structuredContent); + const visual = await connected.client.callTool({ + name: "compare_web_screenshots", + arguments: { + before: screenshotArtifact, + after: screenshotArtifact, + }, + }); + expect(visual.isError).not.toBe(true); + expect(visual.structuredContent).toMatchObject({ + operation: "compare_web_screenshots", + normalized_result: { status: "identical", changed_pixels: 0 }, + }); const evidenceId = evidenceIdOf(inspected.structuredContent); const evidence = await connected.client.readResource({ uri: `rea://evidence/${evidenceId}`, @@ -168,3 +291,24 @@ const evidenceIdOf = (value: unknown): string => { throw new TypeError("Missing browser evidence ID"); return value.evidence_id; }; + +const normalizedResultOf = (value: unknown): unknown => { + if ( + typeof value !== "object" || + value === null || + !("normalized_result" in value) + ) + throw new TypeError("Missing normalized browser result"); + return value.normalized_result; +}; + +const artifactOf = (value: unknown): unknown => { + const normalized = normalizedResultOf(value); + if ( + typeof normalized !== "object" || + normalized === null || + !("artifact" in normalized) + ) + throw new TypeError("Missing screenshot artifact"); + return normalized.artifact; +}; diff --git a/tests/browserObservation.test.ts b/tests/browserObservation.test.ts index 2d6d41fa6..29cb36c20 100644 --- a/tests/browserObservation.test.ts +++ b/tests/browserObservation.test.ts @@ -7,6 +7,7 @@ import { listBrowserTargetsInputSchema, sanitizeBrowserUrl, } from "../src/domain/browserObservation.js"; +import { captureWebScreenshotInputSchema } from "../src/domain/webScreenshot.js"; describe("browser observation contracts", () => { it("normalizes exact HTTP origins without accepting broader URL scopes", () => { @@ -66,12 +67,21 @@ describe("browser observation contracts", () => { }), ).toMatchObject({ observation_ms: 500, + include_accessibility_text: false, + include_console_text: false, + console_text_approved: false, + include_json_body_shapes: false, + json_body_schema_approved: false, + include_websocket_shapes: false, + websocket_shape_approved: false, include_script_sources: false, include_storage_keys: false, limits: { max_frames: 200, max_dom_nodes: 2_000, max_ax_nodes: 2_000, + max_ax_text_field_bytes: 1_024, + max_total_ax_text_bytes: 65_536, max_scripts: 200, max_resources: 2_000, max_workers: 500, @@ -80,11 +90,54 @@ describe("browser observation contracts", () => { max_total_script_source_bytes: 4_194_304, max_network_events: 1_000, max_console_events: 200, + max_console_text_field_bytes: 1_024, + max_total_console_text_bytes: 65_536, + max_json_body_bytes: 1_048_576, + max_total_json_body_bytes: 4_194_304, + max_json_shape_nodes: 5_000, + max_json_shape_depth: 20, max_websocket_events: 500, + max_websocket_shape_bytes: 65_536, + max_total_websocket_shape_bytes: 1_048_576, }, }); }); + it("requires independent approval for each sensitive capture surface", () => { + const base = { + cdp_endpoint: "http://127.0.0.1:9222", + allowed_origins: ["https://app.example.test"], + target_id: "page-1", + approved: true, + }; + for (const input of [ + { include_console_text: true }, + { include_json_body_shapes: true }, + { include_websocket_shapes: true }, + ]) + expect( + inspectWebPageInputSchema.safeParse({ ...base, ...input }).success, + ).toBe(false); + }); + + it("requires an independent literal approval for screenshot pixels", () => { + const input = { + cdp_endpoint: "http://127.0.0.1:9222", + allowed_origins: ["https://app.example.test"], + target_id: "page-1", + approved: true, + }; + expect(captureWebScreenshotInputSchema.safeParse(input).success).toBe( + false, + ); + expect( + captureWebScreenshotInputSchema.safeParse({ + ...input, + screenshot_approved: true, + }).success, + ).toBe(true); + }); + it("removes credentials, query values, and fragments from observed URLs", () => { expect( sanitizeBrowserUrl( diff --git a/tests/cdpBrowserProvider.test.ts b/tests/cdpBrowserProvider.test.ts index 26d266323..a624bd32c 100644 --- a/tests/cdpBrowserProvider.test.ts +++ b/tests/cdpBrowserProvider.test.ts @@ -6,6 +6,10 @@ import { listBrowserTargetsInputSchema, webPageInspectionSchema, } from "../src/domain/browserObservation.js"; +import { analyzeWebBundleInputSchema } from "../src/domain/webBundleAnalysis.js"; +import { observeWebSessionInputSchema } from "../src/domain/browserSession.js"; +import { discoverWebMcpToolsInputSchema } from "../src/domain/webMcpDiscovery.js"; +import { captureWebScreenshotInputSchema } from "../src/domain/webScreenshot.js"; import { startFakeCdpBrowser, type FakeCdpBrowser, @@ -72,32 +76,92 @@ describe("CdpBrowserProvider", () => { expect(() => webPageInspectionSchema.parse(result.value)).not.toThrow(); expect(result.value.frames).toHaveLength(1); expect(result.value.dom.nodes).toHaveLength(2); - expect(result.value.dom.nodes[1]?.attribute_names).toEqual(["token"]); - expect(result.value.accessibility.nodes[0]?.name).toBe("Submit report"); + expect(result.value.dom.nodes[1]?.attribute_names).toEqual([ + "token", + "href", + "rel", + ]); + expect(result.value.accessibility).toMatchObject({ + text_capture: { + status: "not_approved", + retained_bytes: 0, + }, + nodes: [expect.objectContaining({ name: null, description: null })], + }); expect(result.value.scripts.items).toHaveLength(1); - expect(result.value.scripts.items[0]?.script_id).toBe("script-allowed"); + expect(result.value.scripts.items[0]?.script_key).toMatch( + /^scr_[a-f0-9]{64}$/u, + ); + expect(result.value.scripts.items[0]?.resource_reconciliation).toEqual({ + status: "exact", + resource_key: result.value.resources[0]?.resource_key, + }); expect(result.value.scripts.items[0]?.source).toEqual({ included: false, reason: "source capture was not approved", }); expect(result.value.resources).toHaveLength(1); expect(result.value.network.requests).toHaveLength(1); + expect(result.value.network.requests[0]?.initiator).toEqual({ + type: "script", + url: `${browser.allowedOrigin}/app.js?caller=%5BREDACTED%5D`, + line: 3, + column: 5, + }); expect(result.value.network.websocket_events).toEqual([ { request_id: "websocket-1", direction: "sent", opcode: 1, payload_bytes: Buffer.byteLength("websocket-secret"), + payload_shape: null, }, { request_id: "websocket-1", direction: "received", opcode: 2, payload_bytes: 3, + payload_shape: null, }, ]); expect(result.value.console.events[0]?.argument_types).toEqual(["string"]); expect(result.value.workers).toHaveLength(1); + expect(result.value.metadata).toMatchObject({ + headers_allowlisted: true, + responses: [ + { + content_length: 321, + content_encoding: "br", + csp: { nonce_count: 1, hash_count: 1 }, + policies: { + coop: "same-origin", + coep: "require-corp", + permissions_policy_features: ["camera", "geolocation"], + }, + }, + ], + dom_urls: [ + { + attribute: "href", + url: `${browser.allowedOrigin}/agent?token=%5BREDACTED%5D`, + destination_scope: "approved", + }, + ], + agent_hints: expect.arrayContaining([ + expect.objectContaining({ + mechanism: "link_rel", + declaration: "mcp service-desc", + }), + expect.objectContaining({ + mechanism: "dom_link_rel", + declaration: "mcp", + }), + expect.objectContaining({ + mechanism: "response_header", + declaration: "x-model-context", + }), + ]), + }); expect(result.value.storage).toEqual( expect.objectContaining({ local_storage_keys: ["public-key"], @@ -121,6 +185,7 @@ describe("CdpBrowserProvider", () => { "request-secret", "request-body-secret", "response-secret", + "response-body-secret", "websocket-secret", "websocket-url-secret", "console-secret", @@ -128,6 +193,11 @@ describe("CdpBrowserProvider", () => { "unknown-console-value-secret", "storage-secret", "secret-id", + "dom-url-secret", + "link-secret", + "csp-secret", + "hash-secret", + "header-secret", ]) expect(serialized).not.toContain(secret); const methods = browser.commands.map((command) => command.method); @@ -135,6 +205,218 @@ describe("CdpBrowserProvider", () => { expect(methods).not.toContain("Browser.close"); expect(methods).not.toContain("Target.closeTarget"); expect(methods).not.toContain("Runtime.evaluate"); + expect(methods).not.toContain("Network.getResponseBody"); + }); + + it("captures only approved redacted console text and value-free payload shapes", async () => { + const browser = await startFakeCdpBrowser({ + sensitiveShapes: true, + binaryWebSocketEvent: true, + }); + browsers.push(browser); + const result = await new CdpBrowserProvider().inspectPage( + inspectWebPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + include_console_text: true, + console_text_approved: true, + include_json_body_shapes: true, + json_body_schema_approved: true, + include_websocket_shapes: true, + websocket_shape_approved: true, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value.console.events[0]?.text_capture).toEqual({ + status: "included", + values: [ + { argument_index: 0, type: "string", text: "authorization=[REDACTED]" }, + { argument_index: 1, type: "number", text: "42" }, + ], + retained_bytes: 26, + truncated_values: 0, + }); + expect(result.value.network.requests[0]?.body_shapes).toMatchObject({ + status: "included", + request: { + root_type: "object", + properties: expect.arrayContaining([ + expect.objectContaining({ path: "/token", types: ["string"] }), + expect.objectContaining({ + path: "/filters/active", + types: ["boolean"], + }), + ]), + }, + response: { + root_type: "object", + properties: expect.arrayContaining([ + expect.objectContaining({ + path: "/result/token", + types: ["string"], + }), + expect.objectContaining({ path: "/items/*/id", types: ["number"] }), + ]), + }, + }); + expect(result.value.network.websocket_events).toEqual([ + expect.objectContaining({ + opcode: 1, + payload_shape: expect.objectContaining({ + format: "json", + json_shape: expect.objectContaining({ + properties: expect.arrayContaining([ + expect.objectContaining({ path: "/token", types: ["string"] }), + ]), + }), + }), + }), + expect.objectContaining({ + opcode: 2, + payload_shape: { + format: "binary", + json_shape: null, + truncated: false, + }, + }), + ]); + const serialized = JSON.stringify(result.value); + for (const secret of [ + "request-body-secret", + "response-body-secret", + "websocket-secret", + "console-secret", + "object-secret", + ]) + expect(serialized).not.toContain(secret); + const methods = browser.commands.map(({ method }) => method); + expect(methods).toContain("Network.getResponseBody"); + expect(methods).not.toContain("Runtime.getProperties"); + expect(methods).not.toContain("Runtime.callFunctionOn"); + }); + + it("reports independent sensitive-capture truncation at aggregate byte limits", async () => { + const browser = await startFakeCdpBrowser({ sensitiveShapes: true }); + browsers.push(browser); + const result = await new CdpBrowserProvider().inspectPage( + inspectWebPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + include_console_text: true, + console_text_approved: true, + include_json_body_shapes: true, + json_body_schema_approved: true, + include_websocket_shapes: true, + websocket_shape_approved: true, + limits: { + max_console_text_field_bytes: 5, + max_total_console_text_bytes: 5, + max_json_body_bytes: 10, + max_total_json_body_bytes: 10, + max_websocket_shape_bytes: 5, + max_total_websocket_shape_bytes: 5, + }, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value.console.events[0]?.text_capture).toEqual({ + status: "truncated", + values: [{ argument_index: 0, type: "string", text: "autho" }], + retained_bytes: 5, + truncated_values: 2, + }); + expect(result.value.network.requests[0]?.body_shapes.status).toBe( + "truncated", + ); + expect(result.value.network.websocket_events[0]?.payload_shape).toEqual({ + format: "text", + json_shape: null, + truncated: true, + }); + expect(result.value.completeness.truncated_sections).toEqual( + expect.arrayContaining([ + "console_text", + "json_body_shapes", + "websocket_shapes", + ]), + ); + }); + + it("fails closed on malformed approved response and binary payload encodings", async () => { + const browser = await startFakeCdpBrowser({ + invalidResponseBodyBase64: true, + binaryWebSocketEvent: true, + invalidBinaryWebSocketEvent: true, + }); + browsers.push(browser); + const result = await new CdpBrowserProvider().inspectPage( + inspectWebPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + include_json_body_shapes: true, + json_body_schema_approved: true, + include_websocket_shapes: true, + websocket_shape_approved: true, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value.network.requests[0]?.body_shapes).toMatchObject({ + status: "partial", + request: expect.any(Object), + response: null, + }); + expect(result.value.network.websocket_events[1]).toMatchObject({ + opcode: 2, + payload_bytes: 0, + payload_shape: { format: "binary", json_shape: null }, + }); + expect(result.value.completeness.unavailable_sections).toEqual( + expect.arrayContaining(["json_body_shapes", "websocket_frames"]), + ); + }); + + it("captures bounded accessibility text only after independent approval", async () => { + const browser = await startFakeCdpBrowser(); + browsers.push(browser); + const result = await new CdpBrowserProvider().inspectPage( + inspectWebPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + include_accessibility_text: true, + limits: { + max_ax_text_field_bytes: 6, + max_total_ax_text_bytes: 6, + }, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value.accessibility).toMatchObject({ + text_capture: { + status: "truncated", + retained_bytes: 6, + truncated_fields: 2, + }, + nodes: [expect.objectContaining({ name: "Submit" })], + }); + expect(result.value.completeness.truncated_sections).toContain( + "accessibility", + ); }); it("drops network evidence when a request redirects outside the approved origin", async () => { @@ -175,8 +457,11 @@ describe("CdpBrowserProvider", () => { expect(result.value.scripts.items[0]?.source).toEqual( expect.objectContaining({ included: true, - content: "export const observed = 'source-secret';", - bytes: 40, + artifact: expect.objectContaining({ + text: "export const observed = 'source-secret';", + bytes: 40, + uri: expect.stringMatching(/^rea:\/\/web-content\/sha256\//u), + }), }), ); expect(browser.commands.map((command) => command.method)).toContain( @@ -184,6 +469,380 @@ describe("CdpBrowserProvider", () => { ); }); + it("fetches and validates source maps only after separate approval", async () => { + const browser = await startFakeCdpBrowser({ + sourceMapBody: JSON.stringify({ + version: 3, + names: [], + sources: ["src/main.ts"], + sourcesContent: ["export const original = true;"], + mappings: "AAAA", + }), + }); + browsers.push(browser); + const result = await new CdpBrowserProvider().analyzeBundle( + analyzeWebBundleInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + source_capture_approved: true, + observation_ms: 0, + fetch_source_maps: true, + source_map_fetch_approved: true, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value.observations.source_maps).toMatchObject({ + status: "included", + items: [ + { + status: "included", + original_sources: [ + expect.objectContaining({ + source: `${browser.allowedOrigin}/src/main.ts`, + }), + ], + mappings: [expect.any(Object)], + }, + ], + }); + const sourceMapRequest = browser.httpRequests.find(({ url }) => + url.startsWith("/app.js.map"), + ); + expect(sourceMapRequest).toEqual({ + url: "/app.js.map?token=map-secret", + authorization: undefined, + cookie: undefined, + referer: undefined, + }); + }); + + it("observes user-driven reload, SPA, redirect, failure, and lifecycle events", async () => { + const browser = await startFakeCdpBrowser({ + sessionTimeline: "same_origin", + }); + browsers.push(browser); + const result = await new CdpBrowserProvider().observeSession( + observeWebSessionInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 20, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value.window.end_reason).toBe("window_elapsed"); + expect(result.value.timeline.map(({ type }) => type)).toEqual([ + "navigation_requested", + "same_origin_reload", + "same_document_navigation", + "redirect", + "load_failed", + "lifecycle", + ]); + expect(result.value.timeline).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + type: "same_document_navigation", + url: `${browser.allowedOrigin}/reloaded?token=%5BREDACTED%5D`, + }), + expect.objectContaining({ + type: "load_failed", + detail: "net::ERR_CONNECTION_REFUSED", + }), + ]), + ); + expect(result.value.completeness.status).toBe("attach_limited"); + expect(JSON.stringify(result.value)).not.toContain("session-secret"); + expect(JSON.stringify(result.value)).not.toContain("redirect-secret"); + expect(browser.commands.map(({ method }) => method)).toContain( + "Target.detachFromTarget", + ); + }); + + it("discovers untrusted WebMCP declarations without registering or invoking them", async () => { + const browser = await startFakeCdpBrowser({ webMcpTools: true }); + browsers.push(browser); + const result = await new CdpBrowserProvider().discoverWebMcpTools( + discoverWebMcpToolsInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value).toMatchObject({ + status: "available", + tools: { + total: 1, + items: [ + { + name: "search_orders", + description: "Search orders; authorization=[REDACTED]", + declaration_kind: "declarative", + owner_origin: browser.allowedOrigin, + annotations: { + read_only: true, + untrusted_content: true, + autosubmit: false, + }, + trust: "page-declared-untrusted", + registration_source: { + url: `${browser.allowedOrigin}/app.js?token=%5BREDACTED%5D`, + line: 12, + column: 4, + }, + }, + ], + }, + }); + const serialized = JSON.stringify(result.value); + for (const secret of [ + "tool-secret", + "schema-secret", + "tool-source-secret", + "private-tool-secret", + ]) + expect(serialized).not.toContain(secret); + const methods = browser.commands.map(({ method }) => method); + expect(methods).toContain("WebMCP.enable"); + expect(methods).not.toContain("WebMCP.invokeTool"); + expect(methods).not.toContain("Runtime.evaluate"); + }); + + it("reports WebMCP unavailable when the experimental domain is absent", async () => { + const browser = await startFakeCdpBrowser({ + unsupportedMethods: ["WebMCP.enable"], + }); + browsers.push(browser); + const result = await new CdpBrowserProvider().discoverWebMcpTools( + discoverWebMcpToolsInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value.status).toBe("unavailable"); + expect(result.value.tools.items).toEqual([]); + expect(result.value.completeness.unavailable_sections).toContain( + "webmcp_tools", + ); + }); + + it("rejects WebMCP evidence when the page leaves its approved origin", async () => { + const browser = await startFakeCdpBrowser({ + webMcpTools: true, + frameUrlAfterFirstRead: "https://private.example.test/tools", + }); + browsers.push(browser); + const result = await new CdpBrowserProvider().discoverWebMcpTools( + discoverWebMcpToolsInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + }), + ); + + expect(result).toMatchObject({ + ok: false, + error: { + _tag: "BrowserObservationError", + operation: "discover_webmcp_tools", + reason: "target_not_allowed", + }, + }); + expect(browser.commands.map(({ method }) => method)).not.toContain( + "WebMCP.invokeTool", + ); + }); + + it("bounds WebMCP registration replay and reports dropped declarations", async () => { + const browser = await startFakeCdpBrowser({ + webMcpTools: true, + extraCollections: true, + }); + browsers.push(browser); + const result = await new CdpBrowserProvider().discoverWebMcpTools( + discoverWebMcpToolsInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + max_tools: 1, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value.tools).toMatchObject({ + total: 2, + items: [expect.any(Object)], + }); + expect(result.value.completeness).toMatchObject({ + status: "truncated", + dropped_events: { webmcp_tools: 1 }, + }); + }); + + it("removes WebMCP declarations after their child frame leaves scope", async () => { + const browser = await startFakeCdpBrowser({ + webMcpTools: true, + extraCollections: true, + webMcpChildLeavesScope: true, + }); + browsers.push(browser); + const result = await new CdpBrowserProvider().discoverWebMcpTools( + discoverWebMcpToolsInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + }), + ); + + if (!result.ok) throw result.error; + const names = result.value.tools.items.map(({ name }) => name); + expect(names).toEqual( + expect.arrayContaining(["search_orders", "update_order"]), + ); + expect(names).not.toEqual( + expect.arrayContaining(["child_tool", "escaped_child_tool"]), + ); + expect(result.value.completeness.policy_filtered_sections).toContain( + "webmcp_tools", + ); + expect(JSON.stringify(result.value)).not.toContain( + "cross-origin-child-secret", + ); + }); + + it("captures an explicitly approved content-addressed viewport screenshot", async () => { + const browser = await startFakeCdpBrowser(); + browsers.push(browser); + const result = await new CdpBrowserProvider().captureScreenshot( + captureWebScreenshotInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + screenshot_approved: true, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value).toMatchObject({ + viewport: { width: 1, height: 1 }, + artifact: { + uri: expect.stringMatching(/^rea:\/\/web-screenshot\/sha256\//u), + bytes: 70, + media_type: "image/png", + }, + }); + expect(browser.commands.map(({ method }) => method)).toContain( + "Page.captureScreenshot", + ); + }); + + it("discards screenshot pixels when the main frame navigates during capture", async () => { + const browser = await startFakeCdpBrowser({ + navigateDuringScreenshotUrl: "https://private.example.test/screenshot", + }); + browsers.push(browser); + const result = await new CdpBrowserProvider().captureScreenshot( + captureWebScreenshotInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + screenshot_approved: true, + }), + ); + + expect(result).toMatchObject({ + ok: false, + error: { + _tag: "BrowserObservationError", + operation: "capture_web_screenshot", + reason: "target_not_allowed", + }, + }); + }); + + it("ends immediately when a redirect leaves policy without exposing its URL", async () => { + const browser = await startFakeCdpBrowser({ + sessionTimeline: "outside_policy", + }); + browsers.push(browser); + const result = await new CdpBrowserProvider().observeSession( + observeWebSessionInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 1_000, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value.window.end_reason).toBe("target_left_scope"); + expect(result.value.timeline.at(-1)).toMatchObject({ + type: "redirect", + url: null, + destination_scope: "outside_policy", + }); + expect(result.value.completeness).toMatchObject({ + status: "policy_filtered", + policy_filtered_sections: ["timeline"], + excluded: [ + { + section: "timeline", + reason: "out_of_target_scope", + count: 1, + }, + ], + }); + expect(JSON.stringify(result.value)).not.toContain("private.example.test"); + }); + + it("fails closed when the final session frame leaves policy without an event", async () => { + const browser = await startFakeCdpBrowser({ + frameUrlAfterFirstRead: "https://private.example.test/final", + }); + browsers.push(browser); + const result = await new CdpBrowserProvider().observeSession( + observeWebSessionInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 1, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value.window.end_reason).toBe("target_left_scope"); + expect(result.value.target.final_url).toBeNull(); + expect(result.value.completeness).toMatchObject({ + status: "policy_filtered", + policy_filtered_sections: ["timeline"], + }); + expect(JSON.stringify(result.value)).not.toContain("private.example.test"); + }); + it("rejects missing and disallowed page targets before attaching", async () => { const browser = await startFakeCdpBrowser(); browsers.push(browser); @@ -354,6 +1013,12 @@ describe("CdpBrowserProvider", () => { ); if (!degraded.ok) throw degraded.error; expect(degraded.value.accessibility.nodes).toEqual([]); + expect(degraded.value.accessibility.text_capture.status).toBe( + "unavailable", + ); + expect(degraded.value.completeness.unavailable_sections).toContain( + "accessibility", + ); expect(degraded.value.limitations).toContain( "Accessibility.getFullAXTree was unavailable from this browser target.", ); diff --git a/tests/cdpCaptureCompleteness.test.ts b/tests/cdpCaptureCompleteness.test.ts new file mode 100644 index 000000000..7f6e522dc --- /dev/null +++ b/tests/cdpCaptureCompleteness.test.ts @@ -0,0 +1,56 @@ +import { describe, expect, it } from "vitest"; + +import { CdpCaptureCompleteness } from "../src/browser/CdpCaptureCompleteness.js"; + +describe("CdpCaptureCompleteness", () => { + it("reports attach-window limitations without claiming a complete history", () => { + const capture = new CdpCaptureCompleteness([ + "network_requests", + "console_events", + ]); + + expect(capture.snapshot()).toMatchObject({ + status: "attach_limited", + conditions: ["attach_limited"], + attach_limited_sections: ["console_events", "network_requests"], + excluded: [], + dropped_events: { total: 0 }, + }); + }); + + it("aggregates sparse exclusions and applies explicit status precedence", () => { + const capture = new CdpCaptureCompleteness(["network_requests"]); + capture.exclude("scripts", "disallowed_origin"); + capture.exclude("scripts", "disallowed_origin", 2); + capture.exclude("storage_keys", "not_approved", null); + capture.drop("console_events", 4); + + expect(capture.snapshot()).toMatchObject({ + status: "truncated", + conditions: ["attach_limited", "policy_filtered", "truncated"], + policy_filtered_sections: ["scripts", "storage_keys"], + truncated_sections: ["console_events"], + excluded: [ + { section: "scripts", reason: "disallowed_origin", count: 3 }, + { section: "storage_keys", reason: "not_approved", count: null }, + ], + dropped_events: { console_events: 4, total: 4 }, + }); + }); + + it("restores initial attach limitations when reused for a new capture", () => { + const capture = new CdpCaptureCompleteness(["websocket_frames"]); + capture.drop("scripts"); + capture.exclude("resources", "provider_unavailable", null); + + capture.reset(); + + expect(capture.snapshot()).toMatchObject({ + status: "attach_limited", + attach_limited_sections: ["websocket_frames"], + unavailable_sections: [], + excluded: [], + dropped_events: { total: 0 }, + }); + }); +}); diff --git a/tests/cdpCaptureDocuments.test.ts b/tests/cdpCaptureDocuments.test.ts index 1df0ec5e5..d1d8a8a79 100644 --- a/tests/cdpCaptureDocuments.test.ts +++ b/tests/cdpCaptureDocuments.test.ts @@ -1,6 +1,7 @@ import { describe, expect, it } from "vitest"; import { + captureAccessibility, captureDom, captureFrames, captureResources, @@ -71,4 +72,65 @@ describe("CDP document capture", () => { -1, 0, -1, 2, ]); }); + + it("bounds approved accessibility text by UTF-8 bytes without splitting characters", () => { + const capture = captureAccessibility( + [ + { + nodes: [ + { + nodeId: "node-1", + role: { value: "button" }, + name: { value: "😀a" }, + description: { value: "éé" }, + }, + ], + }, + ], + 10, + { + includeText: true, + maximumFieldBytes: 4, + maximumTotalBytes: 7, + }, + ); + + expect(capture.nodes[0]).toMatchObject({ name: "😀", description: "é" }); + expect(capture.textCapture).toEqual({ + status: "truncated", + retained_bytes: 6, + excluded_fields: 0, + truncated_fields: 2, + }); + }); + + it("counts accessibility fields omitted without text approval", () => { + const capture = captureAccessibility( + [ + { + nodes: [ + { + nodeId: "node-1", + name: { value: "private name" }, + description: { value: "private description" }, + }, + ], + }, + ], + 10, + { + includeText: false, + maximumFieldBytes: 1_024, + maximumTotalBytes: 64 * 1_024, + }, + ); + + expect(capture.nodes[0]).toMatchObject({ name: null, description: null }); + expect(capture.textCapture).toEqual({ + status: "not_approved", + retained_bytes: 0, + excluded_fields: 2, + truncated_fields: 0, + }); + }); }); diff --git a/tests/cdpElectronProvider.test.ts b/tests/cdpElectronProvider.test.ts new file mode 100644 index 000000000..98cac969b --- /dev/null +++ b/tests/cdpElectronProvider.test.ts @@ -0,0 +1,211 @@ +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { pathToFileURL } from "node:url"; + +import { afterEach, describe, expect, it } from "vitest"; + +import { CdpElectronProvider } from "../src/browser/CdpElectronProvider.js"; +import { + inspectElectronPageInputSchema, + listElectronTargetsInputSchema, +} from "../src/domain/electronObservation.js"; +import { + startFakeCdpBrowser, + type FakeCdpBrowser, +} from "./fixtures/fakeCdpBrowser.js"; + +describe("CdpElectronProvider", () => { + const browsers: FakeCdpBrowser[] = []; + const temporary: string[] = []; + + afterEach(async () => { + await Promise.all( + browsers.splice(0).map(async (browser) => browser.close()), + ); + await Promise.all( + temporary + .splice(0) + .map(async (path) => rm(path, { recursive: true, force: true })), + ); + }); + + it("lists and inspects only canonical file targets beneath approved roots", async () => { + const root = await electronFixture(); + const index = join(root, "index.html"); + const browser = await startFakeCdpBrowser({ + electronFileUrl: pathToFileURL(index).href, + duplicateElectronInventory: true, + }); + browsers.push(browser); + const provider = new CdpElectronProvider(); + const listed = await provider.listTargets( + listElectronTargetsInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_file_roots: [root], + approved: true, + }), + ); + if (!listed.ok) throw listed.error; + expect(listed.value.targets.items).toEqual([ + expect.objectContaining({ + target_id: "electron-page", + file_path: index, + }), + ]); + expect(listed.value.excluded).toEqual({ + outside_root: 0, + unsupported_url: 3, + non_page: 1, + }); + + const inspected = await provider.inspectPage( + inspectElectronPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_file_roots: [root], + target_id: "electron-page", + approved: true, + observation_ms: 0, + }), + ); + if (!inspected.ok) throw inspected.error; + expect(inspected.value.target.file_path).toBe(index); + expect(inspected.value.frames).toEqual([ + expect.objectContaining({ file_path: index }), + ]); + expect(inspected.value.dom).toMatchObject({ total_nodes: 2 }); + expect(inspected.value.scripts).toMatchObject({ + total: 1, + items: [ + expect.objectContaining({ + file_path: join(root, "app.js"), + source: { + included: false, + reason: "source capture was not approved", + }, + }), + ], + }); + expect(inspected.value.resources).toEqual([ + expect.objectContaining({ file_path: join(root, "app.js") }), + ]); + const methods = browser.commands.map(({ method }) => method); + expect(methods).not.toContain("Runtime.evaluate"); + expect(methods).not.toContain("Network.enable"); + expect(methods).not.toContain("Debugger.getScriptSource"); + expect(methods).toContain("Target.detachFromTarget"); + + const missing = await provider.inspectPage( + inspectElectronPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_file_roots: [root], + target_id: "missing", + approved: true, + observation_ms: 0, + }), + ); + expect(missing).toMatchObject({ + ok: false, + error: { + _tag: "BrowserObservationError", + operation: "inspect_electron_page", + reason: "target_not_found", + }, + }); + }); + + it("captures Electron script source only after separate approval", async () => { + const root = await electronFixture(); + const browser = await startFakeCdpBrowser({ + electronFileUrl: pathToFileURL(join(root, "index.html")).href, + }); + browsers.push(browser); + const result = await new CdpElectronProvider().inspectPage( + inspectElectronPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_file_roots: [root], + target_id: "electron-page", + approved: true, + observation_ms: 0, + include_script_sources: true, + source_capture_approved: true, + }), + ); + if (!result.ok) throw result.error; + expect(result.value.scripts.items[0]?.source).toMatchObject({ + included: true, + artifact: { text: "export const observed = 'source-secret';" }, + }); + expect(browser.commands.map(({ method }) => method)).toContain( + "Debugger.getScriptSource", + ); + }); + + it("rebases DOM parent indexes across allowed file documents", async () => { + const root = await electronFixture(); + const browser = await startFakeCdpBrowser({ + electronFileUrl: pathToFileURL(join(root, "index.html")).href, + extraCollections: true, + }); + browsers.push(browser); + const result = await new CdpElectronProvider().inspectPage( + inspectElectronPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_file_roots: [root], + target_id: "electron-page", + approved: true, + observation_ms: 0, + }), + ); + + if (!result.ok) throw result.error; + expect(result.value.dom).toMatchObject({ + total_nodes: 4, + nodes: [ + { index: 0, parent_index: -1 }, + { index: 1, parent_index: 0 }, + { index: 2, parent_index: -1 }, + { index: 3, parent_index: 2 }, + ], + }); + }); + + it("rejects mixed Electron evidence when the main frame navigates", async () => { + const root = await electronFixture(); + const page = join(root, "index.html"); + const next = join(root, "next.html"); + await writeFile(next, "next"); + const browser = await startFakeCdpBrowser({ + electronFileUrl: pathToFileURL(page).href, + navigateDuringCaptureUrl: pathToFileURL(next).href, + }); + browsers.push(browser); + const result = await new CdpElectronProvider().inspectPage( + inspectElectronPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_file_roots: [root], + target_id: "electron-page", + approved: true, + observation_ms: 0, + }), + ); + + expect(result).toMatchObject({ + ok: false, + error: { + _tag: "BrowserObservationError", + operation: "inspect_electron_page", + reason: "target_changed", + }, + }); + }); + + const electronFixture = async (): Promise => { + const root = await mkdtemp(join(tmpdir(), "rea-electron-provider-")); + temporary.push(root); + await writeFile(join(root, "index.html"), ""); + await writeFile(join(root, "app.js"), "export const app = true;"); + await writeFile(join(root, "child.html"), "
child
"); + return root; + }; +}); diff --git a/tests/cdpSafeMetadata.test.ts b/tests/cdpSafeMetadata.test.ts new file mode 100644 index 000000000..882a2ad1d --- /dev/null +++ b/tests/cdpSafeMetadata.test.ts @@ -0,0 +1,99 @@ +import { describe, expect, it } from "vitest"; + +import { safeResponseMetadata } from "../src/browser/CdpSafeMetadata.js"; + +const origin = "https://app.example.test"; + +describe("safe CDP response metadata", () => { + it("retains only allowlisted header structure and redacted approved links", () => { + const captured = safeResponseMetadata( + "request-1", + `${origin}/api`, + { + mimeType: "application/json", + headers: { + Authorization: "Bearer credential-secret", + Cookie: "session=cookie-secret", + "Set-Cookie": "session=response-secret", + Link: `; rel="mcp service-desc"; title="a,b", ; rel="mcp"`, + "Content-Security-Policy": + "default-src 'self'; script-src 'nonce-nonce-secret' 'sha256-hash-secret' https://private.example.test", + "Permissions-Policy": + "camera=(), geolocation=(self), invalid secret=()", + "X-Model-Context": "agent-header-secret", + }, + }, + new Set([origin]), + ); + + expect(captured.response).toMatchObject({ + url: `${origin}/api`, + csp: { + nonce_count: 1, + hash_count: 1, + directives: expect.arrayContaining([ + expect.objectContaining({ + name: "script-src", + sources: expect.arrayContaining([ + { kind: "external_origin", value: null }, + ]), + }), + ]), + }, + links: [ + { + href: `${origin}/agent?token=%5BREDACTED%5D`, + destination_scope: "approved", + rel: ["mcp", "service-desc"], + as: null, + type: null, + crossorigin: null, + }, + expect.objectContaining({ + href: null, + destination_scope: "outside_policy", + }), + ], + policies: { permissions_policy_features: ["camera", "geolocation"] }, + }); + expect(captured.agentHints).toEqual( + expect.arrayContaining([ + expect.objectContaining({ mechanism: "link_rel" }), + expect.objectContaining({ + mechanism: "response_header", + declaration: "x-model-context", + }), + ]), + ); + const serialized = JSON.stringify(captured); + for (const secret of [ + "credential-secret", + "cookie-secret", + "response-secret", + "link-secret", + "nonce-secret", + "hash-secret", + "agent-header-secret", + "private.example.test", + ]) + expect(serialized).not.toContain(secret); + }); + + it("reports well-known agent resources as untrusted observations", () => { + const captured = safeResponseMetadata( + "request-2", + `${origin}/.well-known/mcp?token=secret`, + { headers: {} }, + new Set([origin]), + ); + + expect(captured.agentHints).toEqual([ + { + mechanism: "well_known_resource", + declaration: "/.well-known/mcp", + url: `${origin}/.well-known/mcp?token=%5BREDACTED%5D`, + trust: "page-declared-untrusted", + }, + ]); + }); +}); diff --git a/tests/config.test.ts b/tests/config.test.ts index 575ef99c2..3d88afabd 100644 --- a/tests/config.test.ts +++ b/tests/config.test.ts @@ -29,9 +29,37 @@ describe("runtime configuration", () => { expect(result.value.browserObservationEnabled).toBe(false); expect(result.value.browserCdpEndpoints).toEqual([]); expect(result.value.browserAllowedOrigins).toEqual([]); + expect(result.value.electronObservationEnabled).toBe(false); + expect(result.value.electronCdpEndpoints).toEqual([]); + expect(result.value.electronFileRoots).toEqual([]); } }); + it("builds a separate Electron endpoint and file-root ceiling", () => { + const result = parseConfig({ + REA_ELECTRON_OBSERVE_ENABLED: "true", + REA_ELECTRON_CDP_ENDPOINTS_JSON: '["http://127.0.0.1:9223"]', + REA_ELECTRON_FILE_ROOTS_JSON: '["/tmp/electron-app"]', + }); + expect(result.ok).toBe(true); + if (!result.ok) return; + expect(result.value.permissionCeilings).toContainEqual({ + capability: "electron_observe", + roots: ["/tmp/electron-app"], + executables: [], + environment_names: [], + origins: ["http://127.0.0.1:9223"], + network: "loopback", + mount: false, + }); + }); + + it("rejects relative Electron file roots", () => { + expect( + parseConfig({ REA_ELECTRON_FILE_ROOTS_JSON: '["relative/app"]' }).ok, + ).toBe(false); + }); + it("parses database kind and loader arguments", () => { expect( parseConfig({ diff --git a/tests/contractSnapshot.test.ts b/tests/contractSnapshot.test.ts index 6de2985c0..ff56c53ba 100644 --- a/tests/contractSnapshot.test.ts +++ b/tests/contractSnapshot.test.ts @@ -9,6 +9,7 @@ import { import { NATIVE_TOOL_CONTRACTS } from "../src/contracts/nativeToolContracts.js"; import { ARTIFACT_TOOL_CONTRACTS } from "../src/contracts/artifactToolContracts.js"; import { BROWSER_TOOL_CONTRACTS } from "../src/contracts/browserToolContracts.js"; +import { ELECTRON_TOOL_CONTRACTS } from "../src/contracts/electronToolContracts.js"; import { enhancedOutputSchemas, officialOutputSchemas, @@ -36,8 +37,9 @@ describe("tool contract surface", () => { ...NATIVE_TOOL_CONTRACTS, ...ARTIFACT_TOOL_CONTRACTS, ...BROWSER_TOOL_CONTRACTS, + ...ELECTRON_TOOL_CONTRACTS, ]; - expect(contracts).toHaveLength(52); + expect(contracts).toHaveLength(60); for (const contract of contracts) { const inputSchema = z.toJSONSchema(contract.inputSchema, { target: "draft-07", @@ -49,12 +51,8 @@ describe("tool contract surface", () => { }); expect(inputSchema.type).toBe("object"); expect(outputSchema.type).toBe("object"); - expect(contract.annotations).toMatchObject({ - idempotentHint: true, - }); - expect(contract.annotations.openWorldHint).toBe( - contract.kind === "browser-provider", - ); + expect(typeof contract.annotations.idempotentHint).toBe("boolean"); + expect(typeof contract.annotations.openWorldHint).toBe("boolean"); expect(typeof contract.annotations.readOnlyHint).toBe("boolean"); expect(typeof contract.annotations.destructiveHint).toBe("boolean"); expect(contract.examples).toHaveLength(1); @@ -140,16 +138,17 @@ describe("tool contract surface", () => { } }); - it("publishes no unconstrained output-schema holes across all 70 tools", () => { + it("publishes no unconstrained output-schema holes across all 78 tools", () => { const contracts = [ ...OFFICIAL_TOOL_CONTRACTS, ...ENHANCED_TOOL_CONTRACTS, ...NATIVE_TOOL_CONTRACTS, ...ARTIFACT_TOOL_CONTRACTS, ...BROWSER_TOOL_CONTRACTS, + ...ELECTRON_TOOL_CONTRACTS, ...SESSION_TOOL_CONTRACTS, ]; - expect(contracts).toHaveLength(70); + expect(contracts).toHaveLength(78); for (const contract of contracts) { const schema = z.toJSONSchema(contract.outputSchema, { target: "draft-07", diff --git a/tests/electronCli.test.ts b/tests/electronCli.test.ts new file mode 100644 index 000000000..cf3411964 --- /dev/null +++ b/tests/electronCli.test.ts @@ -0,0 +1,108 @@ +import { execFile } from "node:child_process"; +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { pathToFileURL } from "node:url"; +import { promisify } from "node:util"; + +import { afterEach, describe, expect, it } from "vitest"; + +import { + startFakeCdpBrowser, + type FakeCdpBrowser, +} from "./fixtures/fakeCdpBrowser.js"; + +const execute = promisify(execFile); +const INTEGRATION_TEST_TIMEOUT_MS = 20_000; + +describe("Electron CLI parity", () => { + const browsers: FakeCdpBrowser[] = []; + const temporary: string[] = []; + + afterEach(async () => { + await Promise.all( + browsers.splice(0).map(async (browser) => browser.close()), + ); + await Promise.all( + temporary + .splice(0) + .map(async (path) => rm(path, { recursive: true, force: true })), + ); + }); + + it( + "returns the same root-confined Electron Evidence contracts", + async () => { + const root = await mkdtemp(join(tmpdir(), "rea-electron-cli-")); + temporary.push(root); + await writeFile( + join(root, "index.html"), + "", + ); + await writeFile(join(root, "app.js"), "export const app = true;"); + const browser = await startFakeCdpBrowser({ + electronFileUrl: pathToFileURL(join(root, "index.html")).href, + }); + browsers.push(browser); + const environment = { + ...process.env, + REA_ELECTRON_OBSERVE_ENABLED: "true", + REA_ELECTRON_CDP_ENDPOINTS_JSON: JSON.stringify([browser.endpoint]), + REA_ELECTRON_FILE_ROOTS_JSON: JSON.stringify([root]), + }; + const listed = await runCli( + ["list-electron-targets", browser.endpoint, "--approved", "--json"], + environment, + ); + expect(listed).toMatchObject({ + operation: "list_electron_targets", + normalized_result: { + targets: { items: [{ target_id: "electron-page" }] }, + }, + }); + const inspected = await runCli( + [ + "inspect-electron-page", + browser.endpoint, + "electron-page", + "--approved", + "--observation-ms", + "0", + "--json", + ], + environment, + ); + expect(inspected).toMatchObject({ + operation: "inspect_electron_page", + provider: { id: "rea-cdp-electron" }, + normalized_result: { + target: { file_path: join(root, "index.html") }, + }, + }); + }, + INTEGRATION_TEST_TIMEOUT_MS, + ); +}); + +const runCli = async ( + arguments_: readonly string[], + environment: NodeJS.ProcessEnv, +): Promise => { + try { + const { stdout } = await execute( + process.execPath, + ["scripts/rea.mjs", ...arguments_], + { cwd: process.cwd(), env: environment, maxBuffer: 16 * 1_024 * 1_024 }, + ); + return JSON.parse(stdout); + } catch (cause: unknown) { + if ( + typeof cause === "object" && + cause !== null && + "stdout" in cause && + typeof cause.stdout === "string" + ) + return JSON.parse(cause.stdout); + throw cause; + } +}; diff --git a/tests/electronFileScope.test.ts b/tests/electronFileScope.test.ts new file mode 100644 index 000000000..a472aa51d --- /dev/null +++ b/tests/electronFileScope.test.ts @@ -0,0 +1,57 @@ +import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { pathToFileURL } from "node:url"; + +import { afterEach, describe, expect, it } from "vitest"; + +import { + authorizedElectronFile, + canonicalElectronRoots, +} from "../src/browser/ElectronFileScope.js"; + +describe("Electron file scope", () => { + const temporary: string[] = []; + + afterEach(async () => { + await Promise.all( + temporary + .splice(0) + .map(async (path) => rm(path, { recursive: true, force: true })), + ); + }); + + it("accepts canonical files within a root and rejects escape forms", async () => { + const base = await mkdtemp(join(tmpdir(), "rea-electron-scope-")); + temporary.push(base); + const root = join(base, "root"); + const outside = join(base, "outside"); + await mkdir(root); + await mkdir(outside); + const allowed = join(root, "index.html"); + const denied = join(outside, "secret.html"); + await writeFile(allowed, "allowed"); + await writeFile(denied, "denied"); + await symlink(denied, join(root, "escape.html")); + const roots = await canonicalElectronRoots([root]); + + expect( + await authorizedElectronFile(pathToFileURL(allowed).href, roots), + ).toBe(allowed); + expect( + await authorizedElectronFile(pathToFileURL(denied).href, roots), + ).toBeUndefined(); + expect( + await authorizedElectronFile( + pathToFileURL(join(root, "escape.html")).href, + roots, + ), + ).toBeUndefined(); + expect( + await authorizedElectronFile("file://server/share/index.html", roots), + ).toBeUndefined(); + expect( + await authorizedElectronFile("file:///tmp/root%2Findex.html", roots), + ).toBeUndefined(); + }); +}); diff --git a/tests/electronMcp.test.ts b/tests/electronMcp.test.ts new file mode 100644 index 000000000..d75ccf7d8 --- /dev/null +++ b/tests/electronMcp.test.ts @@ -0,0 +1,131 @@ +import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { pathToFileURL } from "node:url"; + +import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; +import { afterEach, describe, expect, it } from "vitest"; + +import { BinarySession } from "../src/application/BinarySession.js"; +import { loadConfiguredPermissionAuthority } from "../src/application/PermissionConfiguration.js"; +import { CdpElectronProvider } from "../src/browser/CdpElectronProvider.js"; +import { parseConfig } from "../src/config.js"; +import { createServer } from "../src/server/createServer.js"; +import { observed } from "./fixtures/analysisExecution.js"; +import { + startFakeCdpBrowser, + type FakeCdpBrowser, +} from "./fixtures/fakeCdpBrowser.js"; + +describe("Electron MCP tools", () => { + const browsers: FakeCdpBrowser[] = []; + const resources: Array<{ close(): Promise }> = []; + const temporary: string[] = []; + + afterEach(async () => { + await Promise.all(resources.splice(0).map(async (item) => item.close())); + await Promise.all( + browsers.splice(0).map(async (browser) => browser.close()), + ); + await Promise.all( + temporary + .splice(0) + .map(async (path) => rm(path, { recursive: true, force: true })), + ); + }); + + it("exposes root-confined Electron discovery and inspection as Evidence v2", async () => { + const root = await mkdtemp(join(tmpdir(), "rea-electron-mcp-")); + temporary.push(root); + await writeFile(join(root, "index.html"), ""); + await writeFile(join(root, "app.js"), "export const app = true;"); + const browser = await startFakeCdpBrowser({ + electronFileUrl: pathToFileURL(join(root, "index.html")).href, + }); + browsers.push(browser); + const config = parseConfig({ + REA_ELECTRON_OBSERVE_ENABLED: "true", + REA_ELECTRON_CDP_ENDPOINTS_JSON: JSON.stringify([browser.endpoint]), + REA_ELECTRON_FILE_ROOTS_JSON: JSON.stringify([root]), + }); + if (!config.ok) throw config.error; + const authority = await loadConfiguredPermissionAuthority(config.value); + if (!authority.ok) throw authority.error; + const session = new BinarySession(() => ({ + execute: () => Promise.resolve(observed(null)), + close: () => Promise.resolve(), + })); + const server = createServer(session, session, { + electronObservation: new CdpElectronProvider(), + permissionAuthority: authority.value, + availabilityPolicy: () => ({ + processCaptureEnabled: false, + evidenceFileRoots: 0, + electronObservationEnabled: true, + }), + }); + const client = new Client({ name: "electron-mcp-test", version: "1" }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + resources.push(client, server, session); + await server.connect(serverTransport); + await client.connect(clientTransport); + + const listed = await client.callTool({ + name: "list_electron_targets", + arguments: { + cdp_endpoint: browser.endpoint, + allowed_file_roots: [root], + approved: true, + }, + }); + expect(listed.isError).not.toBe(true); + expect(listed.structuredContent).toMatchObject({ + operation: "list_electron_targets", + provider: { id: "rea-cdp-electron" }, + normalized_result: { + targets: { items: [{ target_id: "electron-page" }] }, + }, + }); + const inspected = await client.callTool({ + name: "inspect_electron_page", + arguments: { + cdp_endpoint: browser.endpoint, + allowed_file_roots: [root], + target_id: "electron-page", + approved: true, + observation_ms: 0, + }, + }); + expect(inspected.isError).not.toBe(true); + expect(inspected.structuredContent).toMatchObject({ + operation: "inspect_electron_page", + normalized_result: { + target: { file_path: join(root, "index.html") }, + scripts: { + items: [expect.objectContaining({ file_path: join(root, "app.js") })], + }, + }, + }); + const outside = join(root, "..", `outside-${Date.now().toString(16)}`); + await mkdir(outside); + temporary.push(outside); + const commandsBeforeDenial = browser.commands.length; + const denied = await client.callTool({ + name: "list_electron_targets", + arguments: { + cdp_endpoint: browser.endpoint, + allowed_file_roots: [outside], + approved: true, + }, + }); + expect(denied.isError).toBe(true); + expect(denied.structuredContent).toMatchObject({ + error: { + code: "permission_required", + details: { missing: { roots: [outside] } }, + }, + }); + expect(browser.commands).toHaveLength(commandsBeforeDenial); + }); +}); diff --git a/tests/enhancedTools.test.ts b/tests/enhancedTools.test.ts index ca4883fe9..4b1a3b01f 100644 --- a/tests/enhancedTools.test.ts +++ b/tests/enhancedTools.test.ts @@ -4,7 +4,11 @@ import { afterEach, describe, expect, it } from "vitest"; import type { AnalysisOperationPort } from "../src/application/AnalysisProvider.js"; import { EnhancedTools } from "../src/application/EnhancedTools.js"; -import { ENHANCED_TOOL_CONTRACTS } from "../src/contracts/toolContracts.js"; +import { + ENHANCED_TOOL_CONTRACTS, + SESSION_TOOL_CONTRACTS, + TOOL_CONTRACTS, +} from "../src/contracts/toolContracts.js"; import { AnalysisOutputError } from "../src/domain/errors.js"; import { jsonValueSchema, type JsonValue } from "../src/domain/jsonValue.js"; import { err } from "../src/domain/result.js"; @@ -180,10 +184,12 @@ const jsonResult = (result: CallToolResult): JsonValue => { }; describe("enhanced MCP tools", () => { - it("lists the complete 33 plus 10 surface", async () => { + it("lists the complete target-open analysis surface", async () => { const client = await connect(); const listed = await client.listTools(); - expect(listed.tools).toHaveLength(52); + expect(listed.tools).toHaveLength( + TOOL_CONTRACTS.length - SESSION_TOOL_CONTRACTS.length, + ); expect( listed.tools .map(({ name }) => name) diff --git a/tests/fixtures/fakeCdpBrowser.ts b/tests/fixtures/fakeCdpBrowser.ts index 724bf5a3e..1fb384aae 100644 --- a/tests/fixtures/fakeCdpBrowser.ts +++ b/tests/fixtures/fakeCdpBrowser.ts @@ -14,6 +14,12 @@ export interface FakeCdpBrowser { readonly browserWebSocketUrl: string; readonly allowedOrigin: string; readonly commands: readonly FakeCdpCommand[]; + readonly httpRequests: readonly { + readonly url: string; + readonly authorization: string | undefined; + readonly cookie: string | undefined; + readonly referer: string | undefined; + }[]; close(): Promise; } @@ -29,13 +35,24 @@ interface FakeOptions { readonly unsupportedMethods?: readonly string[]; readonly transitionalFrameReads?: number; readonly attachedFrameUrl?: string; + readonly frameUrlAfterFirstRead?: string; readonly navigateDuringObservationUrl?: string; readonly navigateDuringCaptureUrl?: string; + readonly navigateDuringScreenshotUrl?: string; readonly extraCollections?: boolean; readonly foreignSessionEvents?: boolean; readonly redirectToDisallowedOrigin?: boolean; readonly unrelatedWorker?: boolean; readonly binaryWebSocketEvent?: boolean; + readonly invalidBinaryWebSocketEvent?: boolean; + readonly sourceMapBody?: string; + readonly sessionTimeline?: "same_origin" | "outside_policy"; + readonly sensitiveShapes?: boolean; + readonly invalidResponseBodyBase64?: boolean; + readonly webMcpTools?: boolean; + readonly webMcpChildLeavesScope?: boolean; + readonly electronFileUrl?: string; + readonly duplicateElectronInventory?: boolean; } /** Start a real HTTP/WebSocket fake at the same seams as a user-owned browser. */ @@ -43,11 +60,30 @@ export const startFakeCdpBrowser = async ( options: FakeOptions = {}, ): Promise => { const commands: FakeCdpCommand[] = []; + const httpRequests: { + url: string; + authorization: string | undefined; + cookie: string | undefined; + referer: string | undefined; + }[] = []; const sockets = new Set(); let frameTreeReads = 0; let port = 0; const http = createServer((request, response) => { + httpRequests.push({ + url: request.url ?? "", + authorization: request.headers.authorization, + cookie: request.headers.cookie, + referer: request.headers.referer, + }); response.setHeader("content-type", "application/json"); + if ( + request.url?.startsWith("/app.js.map") === true && + options.sourceMapBody !== undefined + ) { + response.end(options.sourceMapBody); + return; + } if (request.url === "/json/version") { response.end( options.oversizedDiscovery === true @@ -138,6 +174,7 @@ export const startFakeCdpBrowser = async ( browserWebSocketUrl: `ws://127.0.0.1:${String(port)}/devtools/browser/fake`, allowedOrigin: endpoint, commands, + httpRequests, async close() { for (const socket of sockets) socket.terminate(); await new Promise((resolve) => webSockets.close(() => resolve())); @@ -208,6 +245,17 @@ const targets = ( }, ] : []), + ...(options.electronFileUrl === undefined + ? [] + : [ + { + id: "electron-page", + type: "page", + title: "Electron application", + url: options.electronFileUrl, + attached: false, + }, + ]), ]; const parseCommand = (text: string): FakeCdpCommand => { @@ -245,19 +293,44 @@ const resultFor = ( case "Page.getFrameTree": return frameTree( port, - frameTreeReads <= (options.transitionalFrameReads ?? 0) - ? ":" - : options.attachedFrameUrl, + frameTreeReads > 1 && options.frameUrlAfterFirstRead !== undefined + ? options.frameUrlAfterFirstRead + : frameTreeReads <= (options.transitionalFrameReads ?? 0) + ? ":" + : (options.electronFileUrl ?? options.attachedFrameUrl), options.extraCollections === true, ); case "Page.getResourceTree": - return resourceTree(port, options.extraCollections === true); + return resourceTree( + port, + options.extraCollections === true, + options.electronFileUrl, + options.duplicateElectronInventory === true, + ); case "DOMSnapshot.captureSnapshot": - return domSnapshot(port); + return domSnapshot( + port, + options.electronFileUrl, + options.extraCollections === true, + ); case "Accessibility.getFullAXTree": return accessibilityTree(options.extraCollections === true); case "Debugger.getScriptSource": return { scriptSource: "export const observed = 'source-secret';" }; + case "Network.getResponseBody": + return options.invalidResponseBodyBase64 === true + ? { body: "%%%not-base64%%%", base64Encoded: true } + : { + body: JSON.stringify({ + result: { ok: true, token: "response-body-secret" }, + items: [{ id: 1 }, { id: 2 }], + }), + base64Encoded: false, + }; + case "Page.captureScreenshot": + return { + data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PzWvWQAAAABJRU5ErkJggg==", + }; case "Target.getTargets": return { targetInfos: targets(port, options).map(endpointTargetToInfo) }; case "Storage.getUsageAndQuota": @@ -348,20 +421,38 @@ const frameTree = ( const resourceTree = ( port: number, extraCollections = false, + electronFileUrl?: string, + duplicateElectronInventory = false, ): Readonly> => ({ frameTree: { frame: { id: "frame-main", loaderId: "loader-main", - url: `http://127.0.0.1:${String(port)}/app`, + url: electronFileUrl ?? `http://127.0.0.1:${String(port)}/app`, }, resources: [ { - url: `http://127.0.0.1:${String(port)}/app.js?api_key=resource-secret`, + url: + electronFileUrl === undefined + ? `http://127.0.0.1:${String(port)}/app.js?token=script-secret` + : new URL("app.js", electronFileUrl).href, type: "Script", mimeType: "text/javascript", contentSize: 128, }, + ...(duplicateElectronInventory + ? [ + { + url: + electronFileUrl === undefined + ? `http://127.0.0.1:${String(port)}/app.js?token=script-secret` + : new URL("app.js", electronFileUrl).href, + type: "Script", + mimeType: "text/javascript", + contentSize: 128, + }, + ] + : []), ...(extraCollections ? [ { @@ -381,16 +472,30 @@ const resourceTree = ( }, }); -const domSnapshot = (port: number): Readonly> => { +const domSnapshot = ( + port: number, + electronFileUrl?: string, + extraCollections = false, +): Readonly> => { + const secondDocumentUrl = + electronFileUrl !== undefined && extraCollections + ? new URL("child.html", electronFileUrl).href + : "https://private.example.test/frame"; const strings = [ - `http://127.0.0.1:${String(port)}/app`, + electronFileUrl ?? `http://127.0.0.1:${String(port)}/app`, "#document", "", - "HTML", + "LINK", "token", "dom-secret", - "https://private.example.test/frame", + secondDocumentUrl, "PRIVATE-TEXT", + "href", + "/agent?token=dom-url-secret", + "rel", + "mcp", + "DIV", + "child text", ]; return { strings, @@ -402,18 +507,27 @@ const domSnapshot = (port: number): Readonly> => { nodeName: [1, 3], nodeValue: [2, 2], parentIndex: [-1, 0], - attributes: [[], [4, 5]], + attributes: [[], [4, 5, 8, 9, 10, 11]], }, }, { documentURL: 6, - nodes: { - nodeType: [3], - nodeName: [1], - nodeValue: [7], - parentIndex: [-1], - attributes: [[]], - }, + nodes: + electronFileUrl !== undefined && extraCollections + ? { + nodeType: [9, 1], + nodeName: [1, 12], + nodeValue: [2, 13], + parentIndex: [-1, 0], + attributes: [[], []], + } + : { + nodeType: [3], + nodeName: [1], + nodeValue: [7], + parentIndex: [-1], + attributes: [[]], + }, }, ], }; @@ -461,13 +575,28 @@ const emitEvents = ( }); event(socket, "Debugger.scriptParsed", command.sessionId, { scriptId: "script-allowed", - url: `http://127.0.0.1:${String(port)}/app.js?token=script-secret`, + url: + options.electronFileUrl === undefined + ? `http://127.0.0.1:${String(port)}/app.js?token=script-secret` + : new URL("app.js", options.electronFileUrl).href, hash: "cdp-hash", length: 40, isModule: true, scriptLanguage: "JavaScript", sourceMapURL: `http://127.0.0.1:${String(port)}/app.js.map?token=map-secret`, }); + if ( + options.electronFileUrl !== undefined && + options.duplicateElectronInventory === true + ) + event(socket, "Debugger.scriptParsed", command.sessionId, { + scriptId: "script-allowed-duplicate", + url: new URL("app.js", options.electronFileUrl).href, + hash: "cdp-hash", + length: 40, + isModule: true, + scriptLanguage: "JavaScript", + }); event(socket, "Debugger.scriptParsed", command.sessionId, { scriptId: "script-private", url: "https://private.example.test/private.js?secret=forbidden", @@ -498,14 +627,27 @@ const emitEvents = ( request: { url, method: "POST", - headers: { Authorization: "Bearer request-secret" }, - postData: "request-body-secret", + headers: { + Authorization: "Bearer request-secret", + "Content-Type": "application/json; charset=utf-8", + }, + postData: JSON.stringify({ + operation: "lookup", + token: "request-body-secret", + filters: { active: true }, + }), }, initiator: { type: "script", - callFrames: [ - { url: `${url}#caller-secret`, lineNumber: 3, columnNumber: 5 }, - ], + stack: { + callFrames: [ + { + url: `http://127.0.0.1:${String(port)}/app.js?caller=caller-secret`, + lineNumber: 3, + columnNumber: 5, + }, + ], + }, }, }); if (options.redirectToDisallowedOrigin === true) @@ -526,7 +668,18 @@ const emitEvents = ( : url, status: 200, mimeType: "application/json", - headers: { "Set-Cookie": "response-secret" }, + headers: { + "Set-Cookie": "response-secret", + "Content-Length": "321", + "Content-Encoding": "br", + "Content-Security-Policy": + "default-src 'self' https:; script-src 'nonce-csp-secret' 'sha256-hash-secret' https://private.example.test https://127.0.0.1", + Link: `; rel="mcp service-desc"; type="application/json", ; rel="mcp"`, + "Cross-Origin-Opener-Policy": "same-origin", + "Cross-Origin-Embedder-Policy": "require-corp", + "Permissions-Policy": "camera=(), geolocation=(self)", + "X-Model-Context": "header-secret", + }, }, }); event(socket, "Network.loadingFinished", command.sessionId, { @@ -539,19 +692,51 @@ const emitEvents = ( }); event(socket, "Network.webSocketFrameSent", command.sessionId, { requestId: "websocket-1", - response: { opcode: 1, payloadData: "websocket-secret" }, + response: { + opcode: 1, + payloadData: + options.sensitiveShapes === true + ? JSON.stringify({ + event: "updated", + token: "websocket-secret", + payload: { count: 2 }, + }) + : "websocket-secret", + }, }); if (options.binaryWebSocketEvent === true) event(socket, "Network.webSocketFrameReceived", command.sessionId, { requestId: "websocket-1", - response: { opcode: 2, payloadData: "AQID" }, + response: { + opcode: 2, + payloadData: + options.invalidBinaryWebSocketEvent === true ? "%%%" : "AQID", + }, }); } if (command.method === "Runtime.enable") { event(socket, "Runtime.consoleAPICalled", command.sessionId, { type: "log", timestamp: 123, - args: [{ type: "string", value: "console-secret" }], + args: [ + { + type: "string", + value: + options.sensitiveShapes === true + ? "authorization=Bearer console-secret" + : "console-secret", + }, + ...(options.sensitiveShapes === true + ? [ + { type: "number", value: 42 }, + { + type: "object", + objectId: "must-not-be-expanded", + description: "object-secret", + }, + ] + : []), + ], stackTrace: { callFrames: [ { @@ -568,6 +753,85 @@ const emitEvents = ( args: [{ type: "string", value: "unknown-console-value-secret" }], }); } + if (command.method === "WebMCP.enable" && options.webMcpTools === true) { + event(socket, "WebMCP.toolsAdded", command.sessionId, { + tools: [ + { + name: "search_orders", + description: "Search orders; authorization=Bearer tool-secret", + frameId: "frame-main", + backendNodeId: 42, + inputSchema: { + type: "object", + properties: { + orderId: { type: "string", example: "schema-secret" }, + includeItems: { type: "boolean", default: true }, + }, + required: ["orderId"], + }, + annotations: { + readOnly: true, + untrustedContent: true, + autosubmit: false, + }, + stackTrace: { + callFrames: [ + { + url: `http://127.0.0.1:${String(port)}/app.js?token=tool-source-secret`, + lineNumber: 12, + columnNumber: 4, + }, + ], + }, + }, + { + name: "private_tool", + description: "private-tool-secret", + frameId: "frame-private", + }, + ...(options.extraCollections === true + ? [ + { + name: "update_order", + description: "Update an order", + frameId: "frame-main", + inputSchema: { + type: "object", + properties: { orderId: { type: "string" } }, + }, + }, + ] + : []), + ...(options.webMcpChildLeavesScope === true + ? [ + { + name: "child_tool", + description: "Must be removed after child navigation", + frameId: "frame-child", + }, + ] + : []), + ], + }); + if (options.webMcpChildLeavesScope === true) { + event(socket, "Page.frameNavigated", command.sessionId, { + frame: { + id: "frame-child", + parentId: "frame-main", + url: "https://private.example.test/escaped", + }, + }); + event(socket, "WebMCP.toolsAdded", command.sessionId, { + tools: [ + { + name: "escaped_child_tool", + description: "cross-origin-child-secret", + frameId: "frame-child", + }, + ], + }); + } + } if ( command.method === "DOMSnapshot.captureSnapshot" && options.navigateDuringCaptureUrl !== undefined @@ -578,6 +842,68 @@ const emitEvents = ( url: options.navigateDuringCaptureUrl, }, }); + if ( + command.method === "Page.captureScreenshot" && + options.navigateDuringScreenshotUrl !== undefined + ) + event(socket, "Page.frameNavigated", command.sessionId, { + frame: { + id: "frame-main", + url: options.navigateDuringScreenshotUrl, + }, + }); + if ( + command.method === "Page.setLifecycleEventsEnabled" && + options.sessionTimeline !== undefined + ) { + const allowed = `http://127.0.0.1:${String(port)}/reloaded?token=session-secret`; + event(socket, "Page.frameRequestedNavigation", command.sessionId, { + frameId: "frame-main", + url: allowed, + reason: "reload", + timestamp: 10, + }); + event(socket, "Page.frameNavigated", command.sessionId, { + frame: { + id: "frame-main", + loaderId: "loader-reload", + url: allowed, + transitionType: "reload", + }, + timestamp: 11, + }); + event(socket, "Page.navigatedWithinDocument", command.sessionId, { + frameId: "frame-main", + url: `${allowed}#spa-secret`, + navigationType: "historyApi", + timestamp: 12, + }); + const redirectUrl = + options.sessionTimeline === "outside_policy" + ? "https://private.example.test/outside?token=redirect-secret" + : `http://127.0.0.1:${String(port)}/redirected?token=redirect-secret`; + event(socket, "Network.requestWillBeSent", command.sessionId, { + requestId: "document-request", + frameId: "frame-main", + loaderId: "loader-redirect", + request: { url: redirectUrl, method: "GET" }, + redirectResponse: { status: 302 }, + timestamp: 13, + }); + event(socket, "Network.loadingFailed", command.sessionId, { + requestId: "failed-request", + frameId: "frame-main", + loaderId: "loader-reload", + errorText: "net::ERR_CONNECTION_REFUSED", + timestamp: 14, + }); + event(socket, "Page.lifecycleEvent", command.sessionId, { + frameId: "frame-main", + loaderId: "loader-reload", + name: "networkIdle", + timestamp: 15, + }); + } }; const event = ( diff --git a/tests/integration/serverIntegration.test.ts b/tests/integration/serverIntegration.test.ts index ebc3b6809..a512aeeb9 100644 --- a/tests/integration/serverIntegration.test.ts +++ b/tests/integration/serverIntegration.test.ts @@ -19,6 +19,10 @@ import { processCaptureSchema } from "../../src/domain/processCapture.js"; import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../../src/contracts/processCaptureExample.js"; import { jsonValueSchema } from "../../src/domain/jsonValue.js"; import { PROCESS_PROVIDER } from "../../src/server/sessionToolPolicies.js"; +import { + SESSION_TOOL_CONTRACTS, + TOOL_CONTRACTS, +} from "../../src/contracts/toolContracts.js"; const resources: Array<{ close(): Promise }> = []; @@ -127,7 +131,7 @@ describe("full MCP integration with multi-tool sequences", () => { }); }); - it("preserves the complete 70-tool inventory with a session", async () => { + it("preserves the complete 78-tool inventory with a session", async () => { const session = new BinarySession( (_path) => ({ @@ -150,7 +154,7 @@ describe("full MCP integration with multi-tool sequences", () => { await client.connect(clientTransport); const listed = await client.listTools(); - expect(listed.tools).toHaveLength(70); + expect(listed.tools).toHaveLength(78); const names = listed.tools.map((t) => t.name); expect(names).toContain("open_binary"); expect(names).toContain("close_binary"); @@ -374,12 +378,14 @@ describe("full MCP integration with multi-tool sequences", () => { }); }); - it("preserves the 52-tool inventory without a session", async () => { + it("preserves the target-open tool inventory without a session", async () => { const client = await connect({ execute: () => Promise.resolve(ok(null)), }); const listed = await client.listTools(); - expect(listed.tools).toHaveLength(52); + expect(listed.tools).toHaveLength( + TOOL_CONTRACTS.length - SESSION_TOOL_CONTRACTS.length, + ); const names = listed.tools.map((t) => t.name); expect(names).toContain("binary_overview"); expect(names).toContain("batch_decompile"); diff --git a/tests/jsonShape.test.ts b/tests/jsonShape.test.ts new file mode 100644 index 000000000..91a0e0ccd --- /dev/null +++ b/tests/jsonShape.test.ts @@ -0,0 +1,66 @@ +import { describe, expect, it } from "vitest"; + +import { inferJsonShape } from "../src/domain/jsonShape.js"; + +describe("inferJsonShape", () => { + it("retains paths and types without retaining JSON values", () => { + const shape = inferJsonShape( + JSON.stringify({ + token: "super-secret", + users: [ + { id: 1, active: true }, + { id: "second-secret", active: false }, + ], + optional: null, + }), + { maximumBytes: 4_096, maximumNodes: 100, maximumDepth: 10 }, + ); + + expect(shape).toMatchObject({ + root_type: "object", + truncated: false, + properties: expect.arrayContaining([ + { path: "/token", types: ["string"], observations: 1 }, + { + path: "/users/*/id", + types: ["number", "string"], + observations: 2, + }, + { + path: "/users/*/active", + types: ["boolean"], + observations: 2, + }, + ]), + }); + expect(JSON.stringify(shape)).not.toContain("super-secret"); + expect(JSON.stringify(shape)).not.toContain("second-secret"); + }); + + it("rejects malformed and oversized JSON without returning a prefix", () => { + const limits = { + maximumBytes: 8, + maximumNodes: 100, + maximumDepth: 10, + }; + expect(inferJsonShape("not-json", limits)).toBeNull(); + expect(inferJsonShape('{"secret":"value"}', limits)).toBeNull(); + }); + + it("reports node and depth truncation deterministically", () => { + expect( + inferJsonShape('{"a":{"b":{"c":1}}}', { + maximumBytes: 1_024, + maximumNodes: 100, + maximumDepth: 1, + }), + ).toMatchObject({ truncated: true, max_depth_observed: 1 }); + expect( + inferJsonShape("[1,2,3,4]", { + maximumBytes: 1_024, + maximumNodes: 2, + maximumDepth: 10, + }), + ).toMatchObject({ truncated: true, node_count: 2 }); + }); +}); diff --git a/tests/pngVisualDiff.test.ts b/tests/pngVisualDiff.test.ts new file mode 100644 index 000000000..7ffc0b1c3 --- /dev/null +++ b/tests/pngVisualDiff.test.ts @@ -0,0 +1,95 @@ +import { deflateSync } from "node:zlib"; + +import { describe, expect, it } from "vitest"; + +import { comparePngScreenshots } from "../src/browser/PngVisualDiff.js"; +import { + compareWebScreenshotsInputSchema, + createWebScreenshotArtifact, +} from "../src/domain/webScreenshot.js"; + +describe("PNG visual diff", () => { + it("reports exact changed-pixel and channel metrics", () => { + const before = artifact(1, 1, [0, 0, 0, 255]); + const after = artifact(1, 1, [10, 0, 0, 255]); + const result = comparePngScreenshots( + compareWebScreenshotsInputSchema.parse({ before, after }), + ); + + expect(result).toMatchObject({ + status: "different", + compared_pixels: 1, + changed_pixels: 1, + changed_ratio: 1, + maximum_channel_delta: 10, + mean_absolute_channel_delta: 2.5, + }); + }); + + it("applies a channel threshold and reports dimension mismatch", () => { + const one = artifact(1, 1, [0, 0, 0, 255]); + const near = artifact(1, 1, [2, 0, 0, 255]); + expect( + comparePngScreenshots( + compareWebScreenshotsInputSchema.parse({ + before: one, + after: near, + channel_threshold: 2, + }), + ).status, + ).toBe("identical"); + expect( + comparePngScreenshots( + compareWebScreenshotsInputSchema.parse({ + before: one, + after: artifact(2, 1, [0, 0, 0, 255, 0, 0, 0, 255]), + }), + ), + ).toMatchObject({ status: "dimension_mismatch", compared_pixels: 0 }); + }); + + it("rejects images above the caller's decoded pixel limit", () => { + const image = artifact(2, 1, [0, 0, 0, 255, 0, 0, 0, 255]); + expect(() => + comparePngScreenshots( + compareWebScreenshotsInputSchema.parse({ + before: image, + after: image, + maximum_pixels: 1, + }), + ), + ).toThrow("oversized PNG"); + }); +}); + +const artifact = (width: number, height: number, pixels: readonly number[]) => + createWebScreenshotArtifact(png(width, height, pixels)); + +const png = ( + width: number, + height: number, + pixels: readonly number[], +): Buffer => { + const header = Buffer.alloc(13); + header.writeUInt32BE(width, 0); + header.writeUInt32BE(height, 4); + header[8] = 8; + header[9] = 6; + const rows: number[] = []; + for (let row = 0; row < height; row += 1) + rows.push(0, ...pixels.slice(row * width * 4, (row + 1) * width * 4)); + return Buffer.concat([ + Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), + chunk("IHDR", header), + chunk("IDAT", deflateSync(Buffer.from(rows))), + chunk("IEND", Buffer.alloc(0)), + ]); +}; + +const chunk = (type: string, data: Buffer): Buffer => { + const result = Buffer.alloc(12 + data.byteLength); + result.writeUInt32BE(data.byteLength, 0); + result.write(type, 4, 4, "ascii"); + data.copy(result, 8); + return result; +}; diff --git a/tests/promptMcp.test.ts b/tests/promptMcp.test.ts index a95fc6c16..b35c1f8b4 100644 --- a/tests/promptMcp.test.ts +++ b/tests/promptMcp.test.ts @@ -54,7 +54,7 @@ describe("guided prompts over MCP", () => { ), ); } - expect((await client.listTools()).tools).toHaveLength(70); + expect((await client.listTools()).tools).toHaveLength(78); const result = await client.getPrompt({ name: "investigate_feature", arguments: { diff --git a/tests/readmeConsistency.test.ts b/tests/readmeConsistency.test.ts index 27e73e0ab..54c92c8c3 100644 --- a/tests/readmeConsistency.test.ts +++ b/tests/readmeConsistency.test.ts @@ -11,6 +11,7 @@ import { import { NATIVE_TOOL_CONTRACTS } from "../src/contracts/nativeToolContracts.js"; import { ARTIFACT_TOOL_CONTRACTS } from "../src/contracts/artifactToolContracts.js"; import { BROWSER_TOOL_CONTRACTS } from "../src/contracts/browserToolContracts.js"; +import { ELECTRON_TOOL_CONTRACTS } from "../src/contracts/electronToolContracts.js"; const readmes = [ "README.md", @@ -26,14 +27,15 @@ const expectedToolCounts = [ NATIVE_TOOL_CONTRACTS.length, ARTIFACT_TOOL_CONTRACTS.length, BROWSER_TOOL_CONTRACTS.length, + ELECTRON_TOOL_CONTRACTS.length, SESSION_TOOL_CONTRACTS.length, ] as const; const toolCountsFromReadme = (content: string, path: string): number[] => { const lines = content.split(/\r?\n/u); - const headingIndex = lines.findIndex((line) => /^## .*70/u.test(line)); + const headingIndex = lines.findIndex((line) => /^## .*78/u.test(line)); if (headingIndex === -1) - throw new Error(`Missing 70-tool heading in ${path}`); + throw new Error(`Missing 78-tool heading in ${path}`); const counts: number[] = []; for (const line of lines.slice(headingIndex + 1)) { diff --git a/tests/runtime.test.ts b/tests/runtime.test.ts index 60a14c8ea..da3bfa55f 100644 --- a/tests/runtime.test.ts +++ b/tests/runtime.test.ts @@ -10,7 +10,7 @@ const fixturePath = fileURLToPath( ); describe("production stdio runtime", () => { - it("starts the built entrypoint, lists 70 tools, calls one, and shuts down", async () => { + it("starts the built entrypoint, lists 78 tools, calls one, and shuts down", async () => { const transport = new StdioClientTransport({ command: process.execPath, args: [mainPath], @@ -32,7 +32,7 @@ describe("production stdio runtime", () => { try { await client.connect(transport); const tools = await client.listTools(); - expect(tools.tools).toHaveLength(70); + expect(tools.tools).toHaveLength(78); const result = await client.callTool({ name: "current_document", arguments: {}, @@ -78,7 +78,7 @@ describe("production stdio runtime", () => { try { await client.connect(transport); - expect((await client.listTools()).tools).toHaveLength(70); + expect((await client.listTools()).tools).toHaveLength(78); } finally { await client.close(); await transport.close(); diff --git a/tests/sensitiveTextCapture.test.ts b/tests/sensitiveTextCapture.test.ts new file mode 100644 index 000000000..6d00acb11 --- /dev/null +++ b/tests/sensitiveTextCapture.test.ts @@ -0,0 +1,27 @@ +import { describe, expect, it } from "vitest"; + +import { + boundedSensitiveText, + redactSensitiveText, +} from "../src/browser/SensitiveTextCapture.js"; + +describe("sensitive console text", () => { + it("redacts assignments, bearer credentials, and JWT-shaped values", () => { + const jwt = "eyJabcdefghijk.abcdefghijkl.abcdefghijk"; + expect( + redactSensitiveText( + `authorization=Bearer abc.def password='hunter2' api_key=key ${jwt}`, + ), + ).toBe( + "authorization=[REDACTED] password=[REDACTED] api_key=[REDACTED] [REDACTED_JWT]", + ); + }); + + it("bounds UTF-8 after redaction without splitting a code point", () => { + expect(boundedSensitiveText("password=secret 你好", 22)).toEqual({ + text: "password=[REDACTED] ", + bytes: 20, + truncated: true, + }); + }); +}); diff --git a/tests/serverIdentity.test.ts b/tests/serverIdentity.test.ts index 3f60fe480..ce74a9bd9 100644 --- a/tests/serverIdentity.test.ts +++ b/tests/serverIdentity.test.ts @@ -24,11 +24,11 @@ describe("server and catalog identity", () => { }); expect(PRODUCT_IDENTITY.packageVersion).toBe(packageJson.version); expect(SDK_IDENTITY.server).toBe("2.0.0-beta.4"); - expect(CLI_COMMAND_NAMES).toHaveLength(30); - expect(new Set(CLI_COMMAND_NAMES).size).toBe(30); + expect(CLI_COMMAND_NAMES).toHaveLength(38); + expect(new Set(CLI_COMMAND_NAMES).size).toBe(38); expect(CATALOG_IDENTITY.counts).toEqual({ - cli_commands: 30, - mcp_tools: 70, + cli_commands: 38, + mcp_tools: 78, mcp_prompts: 6, mcp_resources: 2, mcp_resource_templates: 7, @@ -162,7 +162,7 @@ describe("server and catalog identity", () => { expect(status.structuredContent).toMatchObject({ result: { server_identity: { - catalog: { counts: { mcp_tools: 70, cli_commands: 30 } }, + catalog: { counts: { mcp_tools: 78, cli_commands: 38 } }, alignment: { state: "mcp_server_restart_required" }, }, tool_availability: expect.arrayContaining([ diff --git a/tests/sessionMcp.test.ts b/tests/sessionMcp.test.ts index 711758e82..6b67ee338 100644 --- a/tests/sessionMcp.test.ts +++ b/tests/sessionMcp.test.ts @@ -76,7 +76,7 @@ describe("target-free MCP lifecycle", () => { expect(text(before)).toBe( "No app is open. Ask the user which app to investigate, then call open_binary with its local path.", ); - expect((await mcp.listTools()).tools).toHaveLength(70); + expect((await mcp.listTools()).tools).toHaveLength(78); const deniedCapture = await mcp.callTool({ name: "capture_process_scenario", arguments: { diff --git a/tests/setupSkill.test.ts b/tests/setupSkill.test.ts index 9e7d33747..9e27a8d8a 100644 --- a/tests/setupSkill.test.ts +++ b/tests/setupSkill.test.ts @@ -27,7 +27,7 @@ describe("canonical skill transaction", () => { expect(await readFile(`${destination}.rea.backup`, "utf8")).toBe( "stale managed skill\n", ); - expect(await readFile(destination, "utf8")).toContain('version: "13"'); + expect(await readFile(destination, "utf8")).toContain('version: "14"'); expect(await readFile(destination, "utf8")).toContain( `tool_count: ${String(TOOL_CONTRACTS.length)}`, ); diff --git a/tests/toolContracts.test.ts b/tests/toolContracts.test.ts index fecebb73f..eb7305a8e 100644 --- a/tests/toolContracts.test.ts +++ b/tests/toolContracts.test.ts @@ -9,9 +9,10 @@ import { import { ARTIFACT_TOOL_CONTRACTS } from "../src/contracts/artifactToolContracts.js"; import { NATIVE_TOOL_CONTRACTS } from "../src/contracts/nativeToolContracts.js"; import { BROWSER_TOOL_CONTRACTS } from "../src/contracts/browserToolContracts.js"; +import { ELECTRON_TOOL_CONTRACTS } from "../src/contracts/electronToolContracts.js"; describe("tool contract inventory", () => { - it("publishes 52 analysis contracts and eighteen session tools", () => { + it("publishes 60 analysis contracts and eighteen session tools", () => { expect(OFFICIAL_TOOL_CONTRACTS).toHaveLength(33); expect(ENHANCED_TOOL_CONTRACTS).toHaveLength(10); expect(NATIVE_TOOL_CONTRACTS).toHaveLength(5); @@ -19,6 +20,16 @@ describe("tool contract inventory", () => { expect(BROWSER_TOOL_CONTRACTS.map(({ name }) => name)).toEqual([ "list_browser_targets", "inspect_web_page", + "analyze_web_bundle", + "observe_web_session", + "discover_webmcp_tools", + "compare_web_captures", + "capture_web_screenshot", + "compare_web_screenshots", + ]); + expect(ELECTRON_TOOL_CONTRACTS.map(({ name }) => name)).toEqual([ + "list_electron_targets", + "inspect_electron_page", ]); expect(SESSION_TOOL_CONTRACTS.map(({ name }) => name)).toEqual([ "open_binary", @@ -40,8 +51,8 @@ describe("tool contract inventory", () => { "update_unknown", "verify_unknown_resolution", ]); - expect(TOOL_CONTRACTS).toHaveLength(70); - expect(new Set(TOOL_CONTRACTS.map(({ name }) => name)).size).toBe(70); + expect(TOOL_CONTRACTS).toHaveLength(78); + expect(new Set(TOOL_CONTRACTS.map(({ name }) => name)).size).toBe(78); }); it("retains documented enhanced-tool limits at the input boundary", () => { diff --git a/tests/webBundleAnalyzer.test.ts b/tests/webBundleAnalyzer.test.ts new file mode 100644 index 000000000..5f6fc3a74 --- /dev/null +++ b/tests/webBundleAnalyzer.test.ts @@ -0,0 +1,267 @@ +import { describe, expect, it } from "vitest"; + +import { + inspectWebPageInputSchema, + webPageInspectionSchema, +} from "../src/domain/browserObservation.js"; +import { analyzeCapturedWebBundle } from "../src/domain/webBundleAnalyzer.js"; +import { + analyzeWebBundleInputSchema, + webBundleAnalysisSchema, +} from "../src/domain/webBundleAnalysis.js"; +import { createWebTextArtifact } from "../src/domain/webContentArtifact.js"; + +const origin = "https://app.example.test"; + +describe("web bundle analyzer", () => { + it("extracts bounded graph, route, endpoint, vendor, and WebMCP evidence", () => { + const source = ` + import { createApp } from "./chunk.js?token=secret"; + const lazy = import("./lazy.js"); + const routes = [{ path: "/users/:id?token=secret" }]; + fetch("/api/users?authorization=secret"); + document.modelContext.registerTool({ + name: "lookup-user", + description: "Untrusted page declaration", + inputSchema: { + type: "object", + properties: { + userId: { type: "string" }, + verbose: { type: "boolean" } + } + } + }); + const __webpack_require__ = () => createApp(routes, lazy); + `; + const result = analyzeCapturedWebBundle(inspection(source), input()); + + expect(result.observations.chunks.edges).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + kind: "static_import", + specifier: "./chunk.js?token=secret", + resolved_url: `${origin}/assets/chunk.js?token=%5BREDACTED%5D`, + }), + expect.objectContaining({ + kind: "dynamic_import", + specifier: "./lazy.js", + }), + ]), + ); + expect(result.observations.routes).toEqual([ + expect.objectContaining({ value: "/users/:id?token=%5BREDACTED%5D" }), + ]); + expect(result.observations.endpoints).toEqual([ + expect.objectContaining({ + value: "/api/users?authorization=%5BREDACTED%5D", + }), + ]); + expect(result.observations.webmcp_declarations).toEqual([ + expect.objectContaining({ + name: "lookup-user", + trust: "page-declared-untrusted", + schema_property_names: ["userId", "verbose"], + }), + ]); + expect(result.inferences).toEqual( + expect.arrayContaining([ + expect.objectContaining({ value: "webpack", confidence: "high" }), + expect.objectContaining({ value: "Vue" }), + ]), + ); + expect(JSON.stringify(result)).not.toContain("authorization=secret"); + expect(result.completeness.status).toBe("complete_within_limits"); + }); + + it("reports parser gaps and finding truncation instead of claiming completeness", () => { + const malformed = inspection("function broken( {"); + const failed = analyzeCapturedWebBundle(malformed, input()); + expect(failed.completeness).toMatchObject({ + status: "partial", + parse_failures: 1, + }); + expect(failed.unknowns[0]?.dimension).toBe("javascript_ast"); + + const bounded = analyzeCapturedWebBundle( + inspection("fetch('/one'); fetch('/two'); fetch('/three');"), + input({ analysis_limits: { max_findings: 1 } }), + ); + expect(bounded.observations.endpoints).toHaveLength(1); + expect(bounded.completeness).toMatchObject({ + status: "truncated", + dropped_findings: 2, + }); + }); + + it("propagates source-map truncation into completeness and unknowns", () => { + const analysis = analyzeCapturedWebBundle( + inspection("export {};"), + input(), + { + status: "truncated", + requested: 2, + processed: 1, + dropped: 1, + dropped_script_keys: [`scr_${"2".repeat(64)}`], + items: [ + { + script_key: `scr_${"1".repeat(64)}`, + declared_url: "https://app.example.test/app.js.map", + status: "truncated", + artifact: null, + original_sources: [], + original_module_edges: [], + mappings: [], + limitation: "Source-map response exceeded the byte budget.", + }, + ], + }, + ); + + expect(analysis.completeness.status).toBe("truncated"); + expect(analysis.unknowns).toContainEqual({ + dimension: "source_maps", + reason: "Source-map evidence was truncated by approved limits", + affected_script_keys: [`scr_${"1".repeat(64)}`, `scr_${"2".repeat(64)}`], + }); + }); + + it("rejects inconsistent source-map coverage counts", () => { + const result = analyzeCapturedWebBundle(inspection("export {};"), input()); + expect( + webBundleAnalysisSchema.safeParse({ + ...result, + observations: { + ...result.observations, + source_maps: { + ...result.observations.source_maps, + requested: 1, + }, + }, + }).success, + ).toBe(false); + }); +}); + +const input = (overrides: Record = {}) => + analyzeWebBundleInputSchema.parse({ + ...inspectWebPageInputSchema.parse({ + cdp_endpoint: "http://127.0.0.1:9222", + allowed_origins: [origin], + target_id: "page-1", + approved: true, + include_script_sources: true, + }), + source_capture_approved: true, + ...overrides, + }); + +const inspection = (source: string) => + webPageInspectionSchema.parse({ + schema_version: 2, + browser: { + product: "Fake Chrome", + protocol_version: "1.3", + revision: "1", + user_agent: "fake", + js_version: "1", + }, + target: { + target_id: "page-1", + type: "page", + title: "App", + url: `${origin}/app`, + origin, + attached: false, + }, + capture_window: { + started_at: "2026-07-14T00:00:00.000Z", + ended_at: "2026-07-14T00:00:01.000Z", + observation_ms: 1_000, + }, + completeness: { + status: "attach_limited", + conditions: ["attach_limited"], + policy_filtered_sections: [], + attach_limited_sections: ["network_requests"], + truncated_sections: [], + unavailable_sections: [], + excluded: [], + dropped_events: { + scripts: 0, + network_requests: 0, + console_events: 0, + websocket_connections: 0, + websocket_frames: 0, + webmcp_tools: 0, + timeline_events: 0, + total: 0, + }, + }, + frames: [], + dom: { total_nodes: 0, nodes: [] }, + accessibility: { + total_nodes: 0, + text_capture: { + status: "not_approved", + retained_bytes: 0, + excluded_fields: 0, + truncated_fields: 0, + }, + nodes: [], + }, + scripts: { + total: 1, + items: [ + { + script_key: `scr_${"1".repeat(64)}`, + url: `${origin}/assets/app.js`, + origin, + cdp_hash: "hash", + length: Buffer.byteLength(source), + is_module: true, + language: "JavaScript", + source_map_url: null, + resource_reconciliation: { + status: "unmatched", + reason: "no_exact_sanitized_url", + }, + source: { + included: true, + artifact: createWebTextArtifact(source, "text/javascript"), + }, + }, + ], + }, + resources: [], + network: { + requests: [], + websocket_events: [], + coverage_started_at: "2026-07-14T00:00:00.000Z", + prior_activity_available: false, + }, + console: { + events: [], + coverage_started_at: "2026-07-14T00:00:00.000Z", + prior_activity_available: false, + }, + workers: [], + metadata: { + responses: [], + dom_urls: [], + agent_hints: [], + excluded_dom_urls: 0, + headers_allowlisted: true, + }, + storage: { + origin, + usage_bytes: null, + quota_bytes: null, + local_storage_keys: [], + session_storage_keys: [], + indexed_db_names: [], + cache_names: [], + values_redacted: true, + }, + limitations: [], + }); diff --git a/tests/webCaptureDiff.test.ts b/tests/webCaptureDiff.test.ts new file mode 100644 index 000000000..65a6df17f --- /dev/null +++ b/tests/webCaptureDiff.test.ts @@ -0,0 +1,151 @@ +import { afterEach, describe, expect, it } from "vitest"; + +import { CdpBrowserProvider } from "../src/browser/CdpBrowserProvider.js"; +import { inspectWebPageInputSchema } from "../src/domain/browserObservation.js"; +import { + compareWebCaptures, + compareWebCapturesInputSchema, +} from "../src/domain/webCaptureDiff.js"; +import { + startFakeCdpBrowser, + type FakeCdpBrowser, +} from "./fixtures/fakeCdpBrowser.js"; + +describe("web capture diff", () => { + const browsers: FakeCdpBrowser[] = []; + + afterEach(async () => { + await Promise.all( + browsers.splice(0).map(async (browser) => browser.close()), + ); + }); + + it("reports stable observed changes while preserving unknown dimensions", async () => { + const browser = await startFakeCdpBrowser(); + browsers.push(browser); + const captured = await new CdpBrowserProvider().inspectPage( + inspectWebPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + }), + ); + if (!captured.ok) throw captured.error; + const after = structuredClone(captured.value); + after.scripts.items = []; + const request = after.network.requests[0]; + if (request !== undefined) request.status = 204; + + const result = compareWebCaptures( + compareWebCapturesInputSchema.parse({ + before: { inspection: captured.value }, + after: { inspection: after }, + }), + ); + + expect(result.overall_status).toBe("changed"); + expect(result.dimensions.scripts).toMatchObject({ + status: "changed", + total_changes: 1, + changes: [expect.objectContaining({ change: "removed" })], + }); + expect(result.dimensions.network).toMatchObject({ + status: "changed", + changes: [expect.objectContaining({ change: "modified" })], + }); + expect(result.dimensions.webmcp).toMatchObject({ + status: "unknown", + total_changes: 0, + }); + }); + + it("does not claim unchanged when a relevant section is incomplete", async () => { + const browser = await startFakeCdpBrowser(); + browsers.push(browser); + const captured = await new CdpBrowserProvider().inspectPage( + inspectWebPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + }), + ); + if (!captured.ok) throw captured.error; + const incomplete = structuredClone(captured.value); + incomplete.completeness.truncated_sections.push("dom"); + + const result = compareWebCaptures( + compareWebCapturesInputSchema.parse({ + before: { inspection: incomplete }, + after: { inspection: captured.value }, + }), + ); + + expect(result.dimensions.dom_structure.status).toBe("unknown"); + expect(result.dimensions.dom_structure.reason).toContain("incomplete"); + }); + + it("ignores transient request IDs and capture-approval state", async () => { + const browser = await startFakeCdpBrowser(); + browsers.push(browser); + const captured = await new CdpBrowserProvider().inspectPage( + inspectWebPageInputSchema.parse({ + cdp_endpoint: browser.endpoint, + allowed_origins: [browser.allowedOrigin], + target_id: "allowed-page", + approved: true, + observation_ms: 0, + }), + ); + if (!captured.ok) throw captured.error; + const after = structuredClone(captured.value); + const request = after.network.requests[0]; + if (request !== undefined) request.request_id = "different-cdp-request-id"; + const response = after.metadata.responses[0]; + if (response !== undefined) + response.request_id = "different-cdp-request-id"; + const script = after.scripts.items[0]; + if (script !== undefined && !script.source.included) + script.source.reason = "different approval explanation"; + markSectionsComplete(captured.value, ["scripts", "metadata"]); + markSectionsComplete(after, ["scripts", "metadata"]); + + const result = compareWebCaptures( + compareWebCapturesInputSchema.parse({ + before: { inspection: captured.value }, + after: { inspection: after }, + }), + ); + + expect(result.dimensions.scripts.status).toBe("unchanged"); + expect(result.dimensions.metadata.status).toBe("unchanged"); + expect(result.dimensions.network.status).toBe("unknown"); + expect(result.dimensions.network.total_changes).toBe(0); + }); +}); + +const markSectionsComplete = ( + inspection: { + completeness: { + policy_filtered_sections: string[]; + attach_limited_sections: string[]; + truncated_sections: string[]; + unavailable_sections: string[]; + }; + }, + sections: readonly string[], +): void => { + const completed = new Set(sections); + for (const key of [ + "policy_filtered_sections", + "attach_limited_sections", + "truncated_sections", + "unavailable_sections", + ] as const) + inspection.completeness[key] = inspection.completeness[key].filter( + (section) => !completed.has(section), + ); +}; diff --git a/tests/webInventory.test.ts b/tests/webInventory.test.ts new file mode 100644 index 000000000..ceec1f55e --- /dev/null +++ b/tests/webInventory.test.ts @@ -0,0 +1,154 @@ +import { describe, expect, it } from "vitest"; + +import { + reconcileCapturedWebScript, + reconcileWebScript, + stableWebResources, + stableWebScriptKey, +} from "../src/domain/webInventory.js"; +import { + createWebTextArtifact, + webTextArtifactSchema, +} from "../src/domain/webContentArtifact.js"; + +describe("web content artifacts", () => { + it("binds UTF-8 content, size, digest, and URI", () => { + const artifact = createWebTextArtifact( + "const marker = '😀';", + "text/javascript", + ); + expect(webTextArtifactSchema.parse(artifact)).toEqual(artifact); + expect(artifact.bytes).toBe(Buffer.byteLength(artifact.text)); + expect(artifact.uri).toBe(`rea://web-content/sha256/${artifact.sha256}`); + }); + + it("rejects altered content that reuses an artifact digest", () => { + const artifact = createWebTextArtifact("original", "text/javascript"); + expect( + webTextArtifactSchema.safeParse({ ...artifact, text: "altered!" }) + .success, + ).toBe(false); + }); +}); + +describe("stable web inventory", () => { + const script = { + url: "https://app.example.test/assets/app.js", + cdp_hash: "stable-cdp-hash", + length: 1_024, + is_module: true, + language: "JavaScript", + source_map_url: "https://app.example.test/assets/app.js.map", + }; + + it("excludes transient CDP and target identity from script keys", () => { + expect(stableWebScriptKey(script)).toBe(stableWebScriptKey({ ...script })); + expect(stableWebScriptKey({ ...script, length: 1_025 })).not.toBe( + stableWebScriptKey(script), + ); + }); + + it("sorts resources deterministically and reconciles only exact URLs", () => { + const inputs = [ + { + url: "https://app.example.test/assets/vendor.js", + origin: "https://app.example.test", + type: "Script", + mime_type: "text/javascript", + content_size: 200, + }, + { + url: script.url, + origin: "https://app.example.test", + type: "Script", + mime_type: "text/javascript", + content_size: 1_024, + }, + ]; + const forward = stableWebResources(inputs); + const reverse = stableWebResources([...inputs].reverse()); + + expect(reverse).toEqual(forward); + expect(reconcileWebScript(script, forward)).toEqual({ + status: "exact", + resource_key: forward.find(({ url }) => url === script.url)?.resource_key, + }); + expect( + reconcileWebScript({ ...script, url: `${script.url}?v=2` }, forward), + ).toEqual({ status: "unmatched", reason: "no_exact_sanitized_url" }); + }); + + it("reports duplicate resource observations as ambiguous", () => { + const duplicate = { + url: script.url, + origin: "https://app.example.test", + type: "Script", + mime_type: "text/javascript", + content_size: 1_024, + }; + const resources = stableWebResources([ + duplicate, + { ...duplicate, content_size: 2_048 }, + ]); + + expect(reconcileWebScript(script, resources)).toEqual({ + status: "ambiguous", + candidate_resource_keys: resources + .map(({ resource_key }) => resource_key) + .sort(), + }); + }); + + it("deduplicates identical resource observations by stable identity", () => { + const duplicate = { + url: script.url, + origin: "https://app.example.test", + type: "Script", + mime_type: "text/javascript", + content_size: 1_024, + }; + + expect(stableWebResources([duplicate, duplicate])).toEqual( + stableWebResources([duplicate]), + ); + }); + + it("reconciles raw URLs independently of stable inventory sort order", () => { + const app = { + url: script.url, + origin: "https://app.example.test", + type: "Script", + mime_type: "text/javascript", + content_size: 1_024, + rawUrl: `${script.url}?token=secret`, + }; + const vendor = { + url: "https://app.example.test/assets/vendor.js", + origin: "https://app.example.test", + type: "Script", + mime_type: "text/javascript", + content_size: 2_048, + rawUrl: "https://app.example.test/assets/vendor.js?v=1", + }; + + for (const rawResources of [ + [app, vendor], + [vendor, app], + ]) { + const resources = stableWebResources( + rawResources.map(({ rawUrl: _rawUrl, ...resource }) => resource), + ); + expect( + reconcileCapturedWebScript( + { ...script, rawUrl: app.rawUrl }, + rawResources, + resources, + ), + ).toEqual({ + status: "exact", + resource_key: resources.find(({ url }) => url === script.url) + ?.resource_key, + }); + } + }); +}); diff --git a/tests/webSourceMapFetcher.test.ts b/tests/webSourceMapFetcher.test.ts new file mode 100644 index 000000000..0ec347157 --- /dev/null +++ b/tests/webSourceMapFetcher.test.ts @@ -0,0 +1,264 @@ +import { describe, expect, it } from "vitest"; + +import { fetchWebSourceMaps } from "../src/browser/WebSourceMapFetcher.js"; +import { analyzeWebBundleInputSchema } from "../src/domain/webBundleAnalysis.js"; + +const origin = "https://app.example.test"; +const request = { + scriptKey: `scr_${"1".repeat(64)}`, + declaredUrl: `${origin}/assets/app.js.map?token=%5BREDACTED%5D`, + fetchUrl: `${origin}/assets/app.js.map?token=secret`, +}; + +describe("web source-map fetcher", () => { + it("fetches without credentials and derives mappings and original modules", async () => { + const calls: Array<{ url: string; init: RequestInit | undefined }> = []; + const map = JSON.stringify({ + version: 3, + file: "app.js", + names: ["entry"], + sources: ["../src/main.ts"], + sourcesContent: ["import './dependency.ts';\nexport const entry = 1;"], + mappings: "AAAAA", + }); + const result = await fetchWebSourceMaps([request], input(), undefined, { + fetch: (url, init) => { + calls.push({ url: String(url), init }); + return Promise.resolve( + new Response(map, { + status: 200, + headers: { "content-type": "application/json" }, + }), + ); + }, + }); + + expect(calls).toHaveLength(1); + expect(calls[0]).toMatchObject({ + url: request.fetchUrl, + init: { + credentials: "omit", + redirect: "manual", + referrerPolicy: "no-referrer", + }, + }); + expect(JSON.stringify(calls[0]?.init)).not.toContain("secret"); + expect(result).toMatchObject({ + status: "included", + requested: 1, + processed: 1, + dropped: 0, + dropped_script_keys: [], + items: [ + { + status: "included", + artifact: { media_type: "application/source-map+json" }, + original_sources: [ + { + source: `${origin}/src/main.ts`, + artifact: { media_type: "text/typescript" }, + }, + ], + original_module_edges: [ + { + kind: "static_import", + specifier: "./dependency.ts", + resolved_source: `${origin}/src/dependency.ts`, + }, + ], + mappings: [ + { + generated_line: 1, + generated_column: 0, + original_line: 1, + original_column: 0, + }, + ], + }, + ], + }); + }); + + it("validates sectioned maps and reports bounded mapping truncation", async () => { + const regular = { + version: 3, + names: [], + sources: ["a.js"], + sourcesContent: ["export const a = 1"], + mappings: "AAAA;AACA", + }; + const result = await fetchWebSourceMaps( + [request], + input({ analysis_limits: { max_source_map_mappings: 1 } }), + undefined, + { + fetch: () => + Promise.resolve( + new Response( + JSON.stringify({ + version: 3, + sections: [{ offset: { line: 0, column: 0 }, map: regular }], + }), + { status: 200 }, + ), + ), + }, + ); + + expect(result).toMatchObject({ + status: "truncated", + items: [ + { + status: "truncated", + mappings: [expect.any(Object)], + limitation: expect.stringContaining("truncated from 2 to 1"), + }, + ], + }); + }); + + it("reauthorizes every redirect and never contacts a disallowed origin", async () => { + const calls: string[] = []; + const result = await fetchWebSourceMaps([request], input(), undefined, { + fetch: (url) => { + calls.push(String(url)); + return Promise.resolve( + new Response(null, { + status: 302, + headers: { location: "https://private.example.test/map" }, + }), + ); + }, + }); + + expect(calls).toEqual([request.fetchUrl]); + expect(result).toMatchObject({ + status: "unavailable", + items: [{ status: "policy_filtered" }], + }); + }); + + it("distinguishes invalid JSON from declared or streamed byte truncation", async () => { + for (const response of [ + new Response("not-json", { status: 200 }), + new Response("{}", { + status: 200, + headers: { "content-length": "999999" }, + }), + ]) { + const result = await fetchWebSourceMaps( + [request], + input({ analysis_limits: { max_source_map_bytes: 100 } }), + undefined, + { fetch: () => Promise.resolve(response) }, + ); + expect(result.items[0]?.status).toBe( + response.headers.has("content-length") ? "truncated" : "invalid", + ); + } + }); + + it("bounds aggregate map count and reports omitted requests", async () => { + const calls: string[] = []; + const requests = [0, 1, 2].map((index) => ({ + ...request, + scriptKey: `scr_${String(index + 1).repeat(64)}`, + fetchUrl: `${origin}/assets/${String(index)}.js.map`, + })); + const result = await fetchWebSourceMaps( + requests, + input({ analysis_limits: { max_source_maps: 1 } }), + undefined, + { + fetch: (url) => { + calls.push(String(url)); + return Promise.resolve(validMapResponse()); + }, + }, + ); + + expect(calls).toEqual([requests[0]?.fetchUrl]); + expect(result).toMatchObject({ + status: "truncated", + requested: 3, + processed: 1, + dropped: 2, + dropped_script_keys: [requests[1]?.scriptKey, requests[2]?.scriptKey], + }); + }); + + it("stops after exhausting the aggregate response-byte budget", async () => { + const requests = [0, 1, 2].map((index) => ({ + ...request, + scriptKey: `scr_${String(index + 1).repeat(64)}`, + fetchUrl: `${origin}/assets/${String(index)}.js.map`, + })); + const calls: string[] = []; + const result = await fetchWebSourceMaps( + requests, + input({ + analysis_limits: { + max_source_map_bytes: 128, + max_total_source_map_bytes: 128, + }, + }), + undefined, + { + fetch: (url) => { + calls.push(String(url)); + return Promise.resolve(validMapResponse()); + }, + }, + ); + + expect(calls).toHaveLength(2); + expect(result).toMatchObject({ + status: "truncated", + requested: 3, + processed: 2, + dropped: 1, + dropped_script_keys: [requests[2]?.scriptKey], + items: [{ status: "included" }, { status: "truncated" }], + }); + }); + + it("rejects a per-map byte limit larger than the aggregate limit", () => { + const parsed = analyzeWebBundleInputSchema.safeParse({ + cdp_endpoint: "http://127.0.0.1:9222", + allowed_origins: [origin], + target_id: "page-1", + approved: true, + source_capture_approved: true, + analysis_limits: { + max_source_map_bytes: 2, + max_total_source_map_bytes: 1, + }, + }); + + expect(parsed.success).toBe(false); + }); +}); + +const validMapResponse = () => + new Response( + JSON.stringify({ + version: 3, + names: [], + sources: ["a.js"], + sourcesContent: ["export const a = 1"], + mappings: "AAAA", + }), + { status: 200 }, + ); + +const input = (overrides: Record = {}) => + analyzeWebBundleInputSchema.parse({ + cdp_endpoint: "http://127.0.0.1:9222", + allowed_origins: [origin], + target_id: "page-1", + approved: true, + source_capture_approved: true, + fetch_source_maps: true, + source_map_fetch_approved: true, + ...overrides, + });