Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions docs/audits/2026-11-15-explorer-audit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Audit: structure, data correctness, security (15 Nov 2026)

Scope: everything the November score audits (`2026-11-berekeningen.md`, `2026-11-site-validatie.md`) did not cover: collectors, size attribution, export, WebView boundary, structure. Baseline: `flutter analyze` clean, 1389 tests pass.

Status per finding: **reproduced** (shown with a run) or **read** (follows from the code; needs a failing test before it is fixed).

The plans in `docs/superpowers/plans/2026-11-15-*.md` implement this document. IDs below are used there.

## D — Data correctness

| ID | Status | Finding | Where |
|---|---|---|---|
| D1 | reproduced (Node) | `__vsv_collect` calls `skip()`, which only exists inside the bootstrap closure. With one dropped resource the whole `resources` section becomes `{ok:false, error:"ReferenceError: skip is not defined"}`. The drop count is lost too, so the page weight is not marked as a lower bound. | `lib/services/collectors/vsv_collect_js.dart:359` |
| D2 | read | Own size lookups treat every `img` as safe to repeat. A cross-origin tracking pixel without Timing-Allow-Origin has no size, so the app sends its own HEAD/GET with the same query. That can double-count pageviews or conversions. | `lib/services/derive/estimate_targets.dart:16` |
| D3 | read | Size matching tier 4 keys on filename + query only (no host, no path): `a.com/x/logo.png` gets the size of `b.com/y/logo.png`. Tier 5 keys on host + last path segment and is shown as measured. | `lib/services/html_service.dart:4507`, `:4560` |
| D4 | read | The HTML document's weight comes from the app's own fetch (own User-Agent, gzip only) and is counted as measured. `PerformanceNavigationTiming` has `transferSize`, `encodedBodySize`, `decodedBodySize`; the collector does not read them. | `lib/services/derive/page_weight.dart:268`, `vsv_collect_js.dart:375` |
| D5 | read | `categorizeResource` falls back to URL substrings: `/lifestyle/api` → CSS, `/subscriptions` → script, anything with `document` → HTML. Video and audio are counted as images, fonts as other. | `lib/services/probe_service.dart:148` |
| D6 | read | The collector lives in the page's own JavaScript world (`window.__vsv_*`, patched `fetch`/`XHR`). A page can fake the data; anti-bot scripts can see the patch. Possibly related to open item O1 (bol.com block page); that link is a hypothesis. | `vsv_collect_js.dart:200` |
| D7 | read | `source/diff.patch` compares line N with line N. One inserted line marks every later line as changed. | `lib/services/inspection_export_service.dart:752` |
| D8 | read | Three definitions of "same site": detection engine (`_sameSite`), Sovereignty (`registrableDomain` with a short suffix list), site-data cleaner. `www.x.nl` and `static.x.nl` are different sites in the engine. | `lib/services/detection/engine.dart:109`, `sovereignty_service.dart:1511` |
| D9 | read | Detection confidence (92/90/88/82/72/40) reads like a percentage but has no basis. Cookie rules: first match wins, not the longest prefix. | `engine.dart:34`, `:222` |
| D10 | read | Only the first resolved IP of a host is used, and for anycast CDNs the GeoLite country is not where the visitor is served. Nothing marks that. | `sovereignty_service.dart:1408`, `:822` |

## S — Security and privacy

| ID | Finding | Where |
|---|---|---|
| S1 | `PRIVACY.md` says URLs never go to third parties. Hostnames and IPs go to RIPEstat, LibreDNS / Google DNS and DuckDuckGo's icon service, and the app makes its own requests to third-party resource hosts. | `PRIVACY.md` |
| S2 | Iframes post their resource URLs to the top frame with `postMessage(…, '*')`. The embedding page can read what a cross-origin frame loaded; any frame can inject fake entries. | `vsv_collect_js.dart:136` |
| S3 | Reader view renders Readability output with JavaScript on and no CSP. Readability removes `<script>` but not inline handlers. | `lib/services/reader_service.dart:302` |
| S4 | The iOS/macOS WebView plugin comes from a personal fork (`wangqiang1588/flutter_inappwebview`), pinned by commit. | `pubspec.yaml` |
| S5 | The export redacts cookie and storage values, but `source/browser-dom.html` and timeline URLs can hold personal data and tokens. No warning at share time. | `lib/widgets/toolbar.dart:192` |
| S6 | `debugPrint` also prints in release builds; there are 250 calls. The deep-link handler logs the full shared text. | `lib/main.dart:100` |
| S7 | RIPEstat calls carry no `sourceapp` parameter (their usage rules ask for one, as I recall; check their docs). | `sovereignty_service.dart:1448` |

## Q — Structure, performance, slop

| ID | Finding | Where |
|---|---|---|
| Q1 | `HtmlService` is 5454 lines: navigation, editor widgets, search, sovereignty scheduling, size enrichment, ~600 lines of language mapping (duplicate of `SourceViewerEditor`), filename guessing. | `lib/services/html_service.dart` |
| Q2 | Two data models: the typed `Observed` store, and a metadata `Map<String, dynamic>` mutated in place (113 such maps, 40 `_pageMetadata[...]` accesses) plus "legacy" adapters. | `html_service.dart:4473–4750` |
| Q3 | A new `HttpClient` per request: up to 400 size lookups and ~120 RIPEstat calls each open their own TLS connection. | `transfer_size_lookup.dart:33`, `sovereignty_service.dart:1430` |
| Q4 | Regexes compiled inside loops (header rules, beacons). | `engine.dart:300`, `:494` |
| Q5 | localStorage values cross the JS bridge on every poll; only keys and byte counts are used. | `vsv_collect_js.dart:387` |
| Q6 | Dead or stray code: `utils/page_weight.dart` (`resourcesBySize`, only its test uses it), `loadServerSourceForDiff`, `cancelPendingHighlight`, `HtmlService.getLanguageForExtension` (only tests), Dutch certificate dialog, version hard-coded in three places, `avoid_print: ignore` project-wide. | several |

## F — New datapoints

| ID | Feature | Plan |
|---|---|---|
| F1 | Rule-based summary of the most important findings per site; batch: a list of sites visited one by one, exported like the current package plus that summary. No AI. | 02 |
| F2 | Permissions insight: declared (Permissions-Policy, iframe `allow`), requested (camera, microphone, location), stored (quota, IndexedDB, Cache Storage, service workers). | 03 |
| F3 | Suspicious techniques: canvas / WebGL / audio fingerprinting, WebRTC probing, permission prompts on load (instrumented in the separate fresh load only), plus checks that need no instrumentation: CNAME cloaking, cookie syncing, third-party scripts without SRI, tracking before consent. | 04 |
| F4 | Structural view: a segmented wireframe of the rendered page, coloured by owner or element type. | 05 |

## Not in the plans (decisions for the owner)

- S4: fork `flutter_inappwebview` to your own account and point `dependency_overrides` at it. Needs your GitHub account.
- Q1 beyond the two mechanical extractions in plan 01: splitting `HtmlService` into navigation / editor / analysis controllers needs its own design.
- Q2: moving metadata from maps to typed models. Plan 01 only moves the size matching out; the rest is a separate migration.
- The open decisions from `2026-11-berekeningen.md` §3 (weights, thresholds) are unchanged.
63 changes: 63 additions & 0 deletions docs/superpowers/plans/2026-11-15-00-index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Explorer audit: plans and execution order

Spec for all five plans: `docs/audits/2026-11-15-explorer-audit.md`.

| # | Plan | Covers | Tasks | Needs first |
|---|---|---|---|---|
| 01 | `2026-11-15-01-audit-fixes.md` | D1–D10, S1–S3, S5–S7, Q3–Q6, part of Q1 | 17 | nothing |
| 02 | `2026-11-15-02-summary-and-batch.md` | F1: key findings, batch of sites | 5 | 01 Tasks 6, 9 |
| 03 | `2026-11-15-03-permissions-and-storage.md` | F2: Permissions tab | 5 | 01 Tasks 1, 4, 6 |
| 04 | `2026-11-15-04-suspicious-techniques.md` | F3: fingerprinting, shared identifiers, cloaking, SRI | 5 | 01 Tasks 1, 4, 6 |
| 05 | `2026-11-15-05-structure-view.md` | F4: Structure tab | 4 | 01 Tasks 1, 4, 6 |

## Order

1. **Plan 01** first. Its lanes A–D run in parallel; Task 17 (lane E) runs after the four lanes are merged. Plan 01 lane A must be merged before plans 03–05 start, because all three add sections to the collector and use the Node harness.
2. **Plans 02, 03, 04, 05** can then run in parallel, one agent (or one agent team) each, each in its own worktree.
3. Three small follow-ups connect the feature plans. Each is listed in the "Final gate" of its plan and is done by whichever lands second:
- 03 → 02: summary rules `permission-request`, `third-party-device-access`.
- 04 → 02: summary rules `technique-<id>`; batch option `freshLoad` already exists.
- 05 → 02: summary rule `third-party-area`.

## Files more than one plan touches

Agents working in parallel will meet in these files. Each plan adds a separate member or section; rebase before committing and keep additions next to the existing members of the same kind.

| File | Touched by | What each adds |
|---|---|---|
| `lib/services/collectors/vsv_collect_js.dart` | 01 (T1–T5), 03 (T2) | 03 adds the sections `frames`, `siteStorage` |
| `lib/services/collectors/collector_world.dart` | 01 (T4), 05 (T1) | 05 appends `vsvLayoutJs` to the script source |
| `lib/services/collectors/fresh_load_measurer.dart` | 01 (T4, T5), 04 (T2) | 04 adds the second user script and `FreshLoadRaw.techniques` |
| `lib/models/inspection/browser_snapshot.dart` | 01 (T2), 03 (T2) | 03 adds `frames`, `frameCount`, `siteStorage` |
| `lib/models/inspection/page_inspection.dart`, `lib/services/inspection_store.dart` | 03 (T3), 04 (T2), 05 (T2) | `permissionRequests`, `freshTechniques`, `layout` |
| `lib/services/html_service.dart` | every plan | one getter or method each; plan 01 Task 17 removes code and must run before or be rebased under the feature plans |
| `lib/services/inspection_export_service.dart` | 01 (T13), 02 (T2), 03 (T5), 04 (T5), 05 (T4) | one `addJson('analysis/….json', …)` line each |
| `lib/models/app_tab.dart`, `lib/screens/home_screen.dart` | 03 (T5), 05 (T4) | one tab each (`permissions`, `structure`) |
| `test/support/collector_node.dart` | 01 (T1), 04 (T1), 05 (T1) | `runCollector`, then `runJs` |
| `PRIVACY.md` | 01 (T15), 04 (T4) | 04 extends the DoH line |

## Rules for every agent

- Read the plan's header (Global Constraints, Review Focus) and the spec before the first task.
- Test first, see it fail, then implement; one commit per task; never push.
- `flutter analyze --no-pub && flutter test` must be clean before a task is reported done. Report the command output, not a summary of it.
- A step that says "check … before coding" is a real step: if the check contradicts the plan, stop and report it instead of following the plan.
- Steps marked as a real-browser gate or real check need macOS with a display. An agent without one reports the gate as not run; it does not mark it passed.
- Do not touch `docs/superpowers/plans/2026-11-06-centraal-datapunt-tests.md` or the two November audit documents.

## Decisions the owner should confirm before execution

These are choices the plans make that have no external norm. Changing one changes a constant or a rule, not the structure.

1. Plan 01 Task 2: a document sized from the app's own request now counts as an **estimate** (shows `≈`), where it counted as measured.
2. Plan 01 Task 4: on iOS/macOS the collector moves to an isolated world and the fetch/XHR size patch is dropped there. Cross-origin fetch/XHR sizes without Timing-Allow-Origin become "unknown" on those platforms.
3. Plan 01 Task 8: the filename-only size match is removed; image-variant matches are shown as estimates.
4. Plan 02 Task 1: the summary rules and thresholds (5 MB / 2 MB page weight, 50 / 80 header score, top five findings).
5. Plan 02 Task 4: batch defaults (clear site data on, 90 s timeout, 5 s linger, at most 50 sites, one zip with nested packages).
6. Plan 03: the app denies every camera, microphone and location request and records it.
7. Plan 04: fingerprinting is only checked in the separate fresh load, never in the live browser.
8. Plan 05: the Structure tab sits in the Code group before DOM Tree and is browser-only in its first version.

## Not planned here

See "Not in the plans" in the spec: forking the WebView plugin (S4), the full split of `HtmlService` (Q1), typed metadata (Q2), and the open weight/threshold decisions of the earlier audit.
Loading
Loading