[PR #2884] feat(browser): derive API surfaces from retained SAZ captures #5467

New issue

Open

opened 2026-10-31 01:06:53 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:06:53 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2884
Author: @zhangguiping-xydt
Created: 10/13/2026
Status: 🔄 Open

Base: main ← Head: feat/saz-api-surface

📝 Commits (10+)

3d58747 feat(browser): derive API surfaces from retained SAZ captures
cb72786 fix(browser): unfold retained SAZ content type continuations
f6b857c chore(browser): preserve SAZ views with main query-name support
47dd51f fix(browser): consume SAZ parser-owned header continuations
4f32fa0 chore(browser): reconcile SAZ views with current main contracts
5dd2528 chore(ci): integrate upstream EVM and PCAP cleanup repairs
541547c chore(browser): reconcile SAZ API view with current main
e98b396 fix(browser): exclude credentials from unfolded SAZ headers
69323ca chore(browser): synchronize SAZ API surface with main
918c14e test(providers): retain host prerequisites in isolated probes

📊 Changes

18 files changed (+863 additions, -60 deletions)

View changed files

📝 docs/mcp-contracts.md (+1 -1)
📝 docs/web-network-captures.md (+31 -2)
➕ src/browser/history/SazHttp.test.ts (+131 -0)
📝 src/browser/history/SazHttp.ts (+5 -1)
📝 src/browser/history/SazProjection.ts (+29 -2)
📝 src/contracts/analysisViewToolContracts.ts (+1 -1)
📝 src/domain/analysisView/WebNetworkApiSurfaceAccumulator.test.ts (+34 -5)
📝 src/domain/analysisView/WebNetworkApiSurfaceAccumulator.ts (+5 -1)
📝 src/domain/analysisView/WebNetworkProjectionAccumulator.ts (+10 -6)
📝 src/domain/analysisView/environmentManifestView.test.ts (+38 -0)
📝 src/domain/analysisView/environmentManifestView.ts (+2 -2)
➕ src/domain/analysisView/sazApiSurfaceView.test.ts (+237 -0)
➕ src/domain/analysisView/webNetworkApiSurfaceResponse.ts (+84 -0)
📝 src/domain/analysisView/webNetworkApiSurfaceView.test.ts (+8 -8)
📝 src/domain/analysisView/webNetworkApiSurfaceView.ts (+8 -4)
📝 src/domain/analysisView/webNetworkRouteTemplates.ts (+10 -16)
📝 tests/boundary/browser/sazWebCapture.test.ts (+218 -9)
📝 tests/process-global/cutterDescriptorLifetime.test.ts (+11 -2)

📄 Description

What Problem This Solves

The api-surface view accepts HAR but rejects native SAZ captures already retained by REA, forcing analysts to convert archives or group requests manually.

Why This Change Was Made

Reuse the shared bounded capture readers and grouping, with SAZ request lines, textual statuses and a single unambiguous Content-Type header. HTTP unfolding remains owned by the SAZ parser; raw fields and their credential/sensitive-value exclusions remain preserved.

The MIME correction scopes remaining-line-break rejection to SAZ response headers. Shared HAR essence parsing again ignores parameters, so a producer-reported application/json;\r\n charset=utf-8 retains its JSON type and request-body shape. No duplicate HTTP parser or generic HAR normalization was added.

Integrated main bcd1f95e6, preserving the upstream tool descriptions and the earlier collaborator fixes. Environment-manifest and environment-state remain HAR-only; the existing Cutter synchronization stays intact.

User Impact

CLI inspect-analysis-view and MCP inspect_analysis_view group retained or portable SAZ requests by method, recorded origin and inferred path template, including after archive deletion. Query names remain opt-in; no query values, body contents or inferred origin for relative targets are added. No new command, dependency or network activity.

Evidence

Validated head: e687da208b3efd6f6005b66633b6b9000c3e4a84. Linux x64, Node 24.22.1 / npm 11.16.0.

Two new HAR regressions failed before the MIME correction: response content types were empty, and a JSON request body shape was null. Both pass after it. SAZ controls also cover remaining newlines in raw and parser-unfolded parameter text.
Seven focused source suites: 182 passed, covering SAZ parsing, API surfaces, environment manifests/state and resource accounting.
SAZ, compiled CLI/MCP analysis-view and Cutter boundary suites: 74 passed, 1 conditional skip. The first concurrent run had 15 timeouts under heavy host load; all timed-out cases passed on a serial rerun with unchanged code and timeout thresholds. The already-passing MCP and Cutter suites were not rerun.
Actual built CLI and stdio MCP before/after: the same synthetic HAR changes from an empty content-type set / null body shape to application/json / {type: "object", properties: {title: "string"}}. The pre-fix proof used the merged working tree; the successful proof uses the clean committed head above. Portable CLI and retained MCP results agree after source deletion; raw MIME values and capture digests are preserved.
Actual SAZ CLI/MCP controls still accept parser-unfolded CRLF/LF continuations and leave malformed mixed framing unknown, including newlines after the semicolon. Capture bytes remain unchanged.
npm run check: passed, including all six static tasks and architecture guards. npm run docs:check: passed, including 9 README consistency tests. npm run verify:test-discovery: passed, 2,115 files discovered exactly once.

CI and limits

Current-head CI run is blocked by an existing main failure: shard 5 fails the two Inspector exclusion assertions in tests/boundary/browser/cdpScriptMetadata.test.ts (invalid-protocol counts expected 2/1, received 1/0). Main at 45a411e8f fails the same tests with identical results. The test and Inspector implementation are outside this PR's diff. The other seven shards were cancelled; the aggregate Portable tests / CI required checks consequently failed. Full portable-suite success is not claimed.

Build, static checks, docs generation, source tests, reverse-tools quality, real browser/network-capture checks, agentenv export/run, Linux package verification, PR title/readiness and Greptile Review passed. The P2 thread is resolved. GitHub reports the branch mergeable; the PR remains ready for review.

Dependencies used npm ci --ignore-scripts. The host's glibc 2.28 cannot run the pinned GNU tsrs binary, so compilation/typechecking used the same pinned tsrs version's static musl distribution, selected through TSRS_BINARY with TURBO_ENV_MODE=loose and serial Turbo. No repository build configuration was changed. An overlapping static-check run was interrupted during host resource pressure; the subsequent serial check passed.

Synthetic HAR/SAZ inputs do not qualify a particular Fiddler release. Historical folded fields without parser-produced provenance need recapture for MIME derivation. Bodies and Session XML remain outside the SAZ API-surface view. No local macOS/Windows or real Frida/Hopper/Ghidra qualification is claimed.

Author readiness

Human owner: @zhangguiping-xydt

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2884 **Author:** [@zhangguiping-xydt](https://github.com/zhangguiping-xydt) **Created:** 10/13/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/saz-api-surface` --- ### 📝 Commits (10+) - [`3d58747`](https://github.com/morluto/rea/commit/3d5874769bda9300b0a7716389eaf132015f2d49) feat(browser): derive API surfaces from retained SAZ captures - [`cb72786`](https://github.com/morluto/rea/commit/cb727865bae3e3c850271ac9ba13e4061f0de18c) fix(browser): unfold retained SAZ content type continuations - [`f6b857c`](https://github.com/morluto/rea/commit/f6b857c8ac1161015c698ef10ce76046c4efd548) chore(browser): preserve SAZ views with main query-name support - [`47dd51f`](https://github.com/morluto/rea/commit/47dd51f2be329694432db242ad5b7671e77d7b7c) fix(browser): consume SAZ parser-owned header continuations - [`4f32fa0`](https://github.com/morluto/rea/commit/4f32fa09f9571a2ff1b6e1e1c4c722cc923893d1) chore(browser): reconcile SAZ views with current main contracts - [`5dd2528`](https://github.com/morluto/rea/commit/5dd25285e801110a5785151b81212343cb4d5bd5) chore(ci): integrate upstream EVM and PCAP cleanup repairs - [`541547c`](https://github.com/morluto/rea/commit/541547c255c282be60eac98e36895560da90c13b) chore(browser): reconcile SAZ API view with current main - [`e98b396`](https://github.com/morluto/rea/commit/e98b3962289928586bcd85f3ca0c778357ea4566) fix(browser): exclude credentials from unfolded SAZ headers - [`69323ca`](https://github.com/morluto/rea/commit/69323ca5443d60bff2efd4f8ab25ea52d2fd989f) chore(browser): synchronize SAZ API surface with main - [`918c14e`](https://github.com/morluto/rea/commit/918c14e42ccf08353d9f73ec8dd1ccd4fe3e69a0) test(providers): retain host prerequisites in isolated probes ### 📊 Changes **18 files changed** (+863 additions, -60 deletions) <details> <summary>View changed files</summary> 📝 `docs/mcp-contracts.md` (+1 -1) 📝 `docs/web-network-captures.md` (+31 -2) ➕ `src/browser/history/SazHttp.test.ts` (+131 -0) 📝 `src/browser/history/SazHttp.ts` (+5 -1) 📝 `src/browser/history/SazProjection.ts` (+29 -2) 📝 `src/contracts/analysisViewToolContracts.ts` (+1 -1) 📝 `src/domain/analysisView/WebNetworkApiSurfaceAccumulator.test.ts` (+34 -5) 📝 `src/domain/analysisView/WebNetworkApiSurfaceAccumulator.ts` (+5 -1) 📝 `src/domain/analysisView/WebNetworkProjectionAccumulator.ts` (+10 -6) 📝 `src/domain/analysisView/environmentManifestView.test.ts` (+38 -0) 📝 `src/domain/analysisView/environmentManifestView.ts` (+2 -2) ➕ `src/domain/analysisView/sazApiSurfaceView.test.ts` (+237 -0) ➕ `src/domain/analysisView/webNetworkApiSurfaceResponse.ts` (+84 -0) 📝 `src/domain/analysisView/webNetworkApiSurfaceView.test.ts` (+8 -8) 📝 `src/domain/analysisView/webNetworkApiSurfaceView.ts` (+8 -4) 📝 `src/domain/analysisView/webNetworkRouteTemplates.ts` (+10 -16) 📝 `tests/boundary/browser/sazWebCapture.test.ts` (+218 -9) 📝 `tests/process-global/cutterDescriptorLifetime.test.ts` (+11 -2) </details> ### 📄 Description ## What Problem This Solves The `api-surface` view accepts HAR but rejects native SAZ captures already retained by REA, forcing analysts to convert archives or group requests manually. ## Why This Change Was Made Reuse the shared bounded capture readers and grouping, with SAZ request lines, textual statuses and a single unambiguous Content-Type header. HTTP unfolding remains owned by the SAZ parser; raw fields and their credential/sensitive-value exclusions remain preserved. The MIME correction scopes remaining-line-break rejection to SAZ response headers. Shared HAR essence parsing again ignores parameters, so a producer-reported `application/json;\r\n charset=utf-8` retains its JSON type and request-body shape. No duplicate HTTP parser or generic HAR normalization was added. Integrated main `bcd1f95e6`, preserving the upstream tool descriptions and the earlier collaborator fixes. Environment-manifest and environment-state remain HAR-only; the existing Cutter synchronization stays intact. ## User Impact CLI `inspect-analysis-view` and MCP `inspect_analysis_view` group retained or portable SAZ requests by method, recorded origin and inferred path template, including after archive deletion. Query names remain opt-in; no query values, body contents or inferred origin for relative targets are added. No new command, dependency or network activity. ## Evidence Validated head: `e687da208b3efd6f6005b66633b6b9000c3e4a84`. Linux x64, Node 24.22.1 / npm 11.16.0. - Two new HAR regressions failed before the MIME correction: response content types were empty, and a JSON request body shape was null. Both pass after it. SAZ controls also cover remaining newlines in raw and parser-unfolded parameter text. - Seven focused source suites: **182 passed**, covering SAZ parsing, API surfaces, environment manifests/state and resource accounting. - SAZ, compiled CLI/MCP analysis-view and Cutter boundary suites: **74 passed, 1 conditional skip**. The first concurrent run had 15 timeouts under heavy host load; all timed-out cases passed on a serial rerun with unchanged code and timeout thresholds. The already-passing MCP and Cutter suites were not rerun. - Actual built CLI and stdio MCP before/after: the same synthetic HAR changes from an empty content-type set / null body shape to `application/json` / `{type: "object", properties: {title: "string"}}`. The pre-fix proof used the merged working tree; the successful proof uses the clean committed head above. Portable CLI and retained MCP results agree after source deletion; raw MIME values and capture digests are preserved. - Actual SAZ CLI/MCP controls still accept parser-unfolded CRLF/LF continuations and leave malformed mixed framing unknown, including newlines after the semicolon. Capture bytes remain unchanged. - `npm run check`: **passed**, including all six static tasks and architecture guards. `npm run docs:check`: **passed**, including 9 README consistency tests. `npm run verify:test-discovery`: **passed**, 2,115 files discovered exactly once. ## CI and limits Current-head [CI run](https://github.com/morluto/rea/actions/runs/39930806661) is **blocked by an existing main failure**: [shard 5](https://github.com/morluto/rea/actions/runs/39930806661/job/120338711164) fails the two Inspector exclusion assertions in `tests/boundary/browser/cdpScriptMetadata.test.ts` (invalid-protocol counts expected 2/1, received 1/0). [Main at `45a411e8f`](https://github.com/morluto/rea/actions/runs/39929290668/job/120336028750) fails the same tests with identical results. The test and Inspector implementation are outside this PR's diff. The other seven shards were cancelled; the aggregate Portable tests / CI required checks consequently failed. Full portable-suite success is not claimed. Build, static checks, docs generation, source tests, reverse-tools quality, real browser/network-capture checks, agentenv export/run, Linux package verification, PR title/readiness and Greptile Review passed. The P2 thread is resolved. GitHub reports the branch mergeable; the PR remains ready for review. Dependencies used `npm ci --ignore-scripts`. The host's glibc 2.28 cannot run the pinned GNU tsrs binary, so compilation/typechecking used the **same pinned tsrs version's static musl distribution**, selected through `TSRS_BINARY` with `TURBO_ENV_MODE=loose` and serial Turbo. No repository build configuration was changed. An overlapping static-check run was interrupted during host resource pressure; the subsequent serial check passed. Synthetic HAR/SAZ inputs do not qualify a particular Fiddler release. Historical folded fields without parser-produced provenance need recapture for MIME derivation. Bodies and Session XML remain outside the SAZ API-surface view. No local macOS/Windows or real Frida/Hopper/Ghidra qualification is claimed. ## Author readiness Human owner: @zhangguiping-xydt - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-10-31 01:06:53 +00:00

bsakaguchi referenced this issue

2026-11-01 21:44:49 +00:00

[PR #5674] [MERGED] fix(managed): treat extension-only module scopes as unknown identity #7029