Add verified-session evidence bundle + wire JA3 oracle into diagnostics#3
Merged
Conversation
…diagnostics Closes two tracked gaps from ROADMAP.md, building on the existing shared readiness model rather than duplicating it. - browser_diagnostics: add opt-in --ja3-oracle/--expected-ja3. When set, the stock-Chromium probe measures JA3 via the existing echo-oracle helper and records it in fingerprint_validation. Without an oracle it stays not_measured (no fabricated fingerprint match). - scripts/verified_session.py: compose ProjectState + optional page check + optional JA3 oracle into one redacted runtime-evidence.json. Drops PID, basenames the process path, redacts repo root, and records config/profile sha256 hashes so evidence ties to an exact compiled config. - main.py: expose 'verified-session' subcommand and register the new test. - tests: verified_session_tests.py (bundle shape + redaction + honest JA3 defaults) and probe-signature assertions in browser_probe_semantics_test.py; add both new files to the repository structure manifest. - docs: ROADMAP gaps updated; README documents the new command and its redaction/JA3 honesty rules. Full offline suite: 34/34 checks pass.
This was referenced Jun 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR analyzes the proposed integration ideas against the actual state of the repository and lands only the genuinely missing, high-value pieces. Most of the proposal (shared
ProjectState/CheckResult/RepairAction, listener-exposure detection, GUI dashboard next-action, ADRs, maintainer map, release artifact verifier, tests-out-of-scripts) was already implemented. The two concrete items still open inROADMAP.mdwere:Both are now done, built on the existing readiness layer rather than duplicating it.
Changes
scripts/browser_diagnostics.py— opt-in--ja3-oracle/--expected-ja3. When supplied, the stock-Chromium probe measures JA3 via the existingverify_ja3_against_oraclehelper and records it infingerprint_validation. Without an oracle it staysnot_measured— no fabricated fingerprint match (honors ADR-0004).scripts/verified_session.py(new) — composesProjectState+ optional page check + optional JA3 oracle into one redactedruntime-evidence.json:config_sha256+ per-profile hashes so evidence ties to an exact compiled confignot_runand JA3not_measuredunless explicitly requestedmain.py— newverified-sessionsubcommand; registers the new test in the offline suite.verified_session_tests.py(bundle shape, redaction, honest JA3 defaults, sha256 config hash) and probe-signature assertions inbrowser_probe_semantics_test.py; both new files added to the repository-structure manifest.ROADMAP.mdgaps updated;README.mddocuments the command and its redaction/JA3-honesty rules.Why the rest of the proposal was not implemented
The larger architectural suggestions (PyO3 embedding, Cap'n Proto IPC, Tauri/Slint migration, io_uring/eBPF, TCP sequence-injection, embedding the Rust core into Xray) are interesting but conflict with the project's established, deliberately-honest architecture (Xray as runtime source of truth — ADR-0001; browser-proxy-first — ADR-0003) and would be large, risky rewrites rather than coherence improvements. They are better tracked as research items, not merged speculatively.
Testing
Manual:
py -3 main.py verified-session --skip-runtime --skip-trustproduces a redacted bundle (root<redacted>, no PID, JA3not_measured); output path.local-state/runtime-evidence.jsonis gitignored.