Initial Flight DevTools implementation

Author: Евгений Балякин

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run build

.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+.idea/
+.turbo/
+.vite/
+coverage/
+*.log
+.DS_Store
+*.tsbuildinfo

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evgeny Balyakin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,172 @@
+# Flight Security DevTools
+
+**The local-first security boundary inspector for React Server Components and Flight payloads.**
+
+Flight Security DevTools turns unreadable React Flight streams into an explainable map of what crossed the server/client boundary: data, module references, Server Actions, pending refs, parser anomalies, secrets, PII, and RCE-class patterns.
+
+![Flight Security DevTools screenshot](docs/assets/app-screenshot.svg)
+
+## Why It Exists
+
+React Server Components changed the real security boundary of modern React apps. The component tree looks clean, but the Flight payload is where sensitive data, callable server references, module references, errors, and control-flow objects actually cross into the browser.
+
+Flight Security DevTools is built to answer three questions quickly:
+
+- **What crossed the boundary?**
+- **What is risky?**
+- **What should be fixed next?**
+
+## Highlights
+
+- **Chrome DevTools panel**: opens as a dedicated `Flight` tab next to Elements, Console, and Network.
+- **Zero proxy MVP capture**: uses `chrome.devtools.network` to detect completed RSC responses without `debugger` permission.
+- **Parser Worker**: parses Flight payloads off the UI thread.
+- **Boundary Risk Summary**: deterministic 0-100 risk score with Low, Medium, High, and Critical levels.
+- **Security rules**: detects prototype traversal, suspicious thenables, constructor access, dangerous modules, secrets, PII, source/stack exposure, and oversized chunks.
+- **Tree and Raw evidence**: jump from a finding to the parsed chunk or raw Flight row.
+- **Boundary Map**: separates data, callable, module, and control-flow exposure.
+- **Streaming-first parser API**: supports complete responses and incremental stream parsing.
+- **Local-first privacy**: analysis runs locally; long-term storage/export primitives are designed for sanitized traces.
+
+## Architecture
+
+```text
+Chrome DevTools Network capture
+          |
+          v
+Parser Worker -> @flight-devtools/parser -> Boundary Analyzer -> Security Rules
+          |
+          v
+DevTools Panel: Boundary / Tree / Raw / Timeline / Map / Actions / Security / Diff
+```
+
+The parser package is independent from the extension and can be used in Node.js, browsers, workers, and future CI tooling.
+
+## Repository Layout
+
+```text
+packages/
+  parser/      # @flight-devtools/parser, standalone TypeScript parser
+  extension/   # Chrome MV3 DevTools extension
+docs/          # product and API docs
+examples/      # parser usage examples
+```
+
+## Quick Start
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+Load the extension build from:
+
+```text
+packages/extension/dist
+```
+
+Open `chrome://extensions`, enable Developer Mode, choose **Load unpacked**, and select that folder. Then open Chrome DevTools on a Next.js App Router page and switch to the **Flight** panel.
+
+For extension UI development:
+
+```bash
+npm run dev:extension
+```
+
+## Parser API
+
+```ts
+import {
+  createFlightSession,
+  createFlightStreamParser,
+  parseFlightRequest,
+  parseFlightResponse
+} from '@flight-devtools/parser';
+
+const tree = parseFlightResponse(
+  '0:{"user":"$1","action":"$F2"}\n1:{"email":"ada@example.com"}\n'
+);
+
+console.log(tree.boundaryFindings);
+console.log(tree.securityAlerts);
+
+const session = createFlightSession([
+  {
+    request: {
+      id: 'r1',
+      url: 'https://app.test/dashboard?_rsc=1',
+      method: 'GET',
+      startedAt: Date.now()
+    },
+    responseBody: '0:{"user":"$1"}\n1:{"token":"Bearer abcdefghijklmnopqrstuvwxyz"}\n'
+  }
+]);
+
+console.log(session.summary);
+
+const stream = createFlightStreamParser();
+stream.onFinding((finding) => console.log(finding.title));
+stream.write('0:{"later":"$L1"}\n');
+stream.write('1:{"name":"Ada"}\n');
+stream.end();
+```
+
+## MVP Security Rules
+
+| Rule | Detects | Default risk |
+| --- | --- | --- |
+| `S001` | Prototype chain traversal via property selection | Critical |
+| `S002` | Suspicious thenable object | Critical |
+| `S003` | Function constructor access | Critical |
+| `S004` | Dangerous Node/system module references | Warning |
+| `S005` | Deep reference chains | Info |
+| `S006` | Oversized chunks and overfetching | Info |
+| `S007` | Secret exposure: JWT, bearer token, API key, private key, database URL | Critical |
+| `S008` | PII exposure: common PII and high-sensitivity PII use separate impact variants | Warning |
+| `S009` | Broad or suspicious Server Action boundary, escalated for RCE/high-sensitivity context | Warning/Critical |
+| `S010` | Source, stack, or internal diagnostic exposure | Warning |
+
+## Current Status
+
+This is an alpha implementation of the vertical MVP from `FLIGHT_DEVTOOLS_SPEC.md`. The parser is best-effort and uses lenient recovery by default: malformed rows become parser errors and protocol-anomaly findings instead of crashing the UI.
+
+Completed in this alpha:
+
+- TypeScript strict parser core
+- Complete response parser and streaming parser
+- Server Action request body parser
+- Session grouping primitives
+- Boundary risk scoring
+- Redaction and sensitive data detection
+- Chrome DevTools panel scaffold
+- Parser Worker integration
+- Tree, Raw, Timeline, Boundary Map, Actions, Security, and What Changed views
+- Tests for lexer, decoder, resolver, stream parser, sessionizer, and security rules
+
+Planned next:
+
+- Larger React 18/19 and Next.js 14/15 fixture corpus
+- More precise Flight version strategies
+- Virtualized tree rendering for very large payloads
+- CI/CLI workflows for boundary review
+- Sanitized HTML report export
+- Playwright-driven extension screenshot tests
+
+## Development Commands
+
+```bash
+npm run typecheck
+npm test
+npm run build
+node examples/node-script/index.mjs
+```
+
+## Author
+
+Evgeny Balyakin<br>
+GitHub: [github.com/balyakin](https://github.com/balyakin)
+
+## License
+
+MIT (c) Evgeny Balyakin

docs/api/parser.md

@@ -0,0 +1,12 @@
+# Parser API
+
+```ts
+parseFlightResponse(body, options?)
+parseFlightRequest(body, options?)
+createFlightSession(inputs, options?)
+createFlightStreamParser(options?)
+detectFlightVersion(body, options?)
+createBoundaryMap(tree)
+```
+
+Default parsing mode is `lenient`; invalid chunks produce recoverable parser errors and protocol-anomaly findings instead of crashing the caller.

docs/assets/app-screenshot.svg

@@ -0,0 +1,11 @@
+# Flight Protocol Notes
+
+Flight responses are parsed as newline-delimited rows:
+
+```text
+<id>:<tag?><payload>
+```
+
+The MVP parser supports model/JSON rows, `J`, `H`, `I`, `E`, `T`, `D`, `S`, `P`, `B`, and `C` tags. It decodes common `$` encodings including chunk refs, lazy refs, promises, dates, bigints, maps, sets, server functions, and property selections.
+
+Unknown or malformed rows are recorded as recoverable parser errors in lenient mode. The UI keeps raw evidence available so unsupported React versions still have useful diagnostics.