Harden release readiness checks

Author: maybeknott

.github/workflows/build-gui.yml

@@ -48,6 +48,14 @@ jobs:
           "$($hash.Hash)  $(Split-Path $zip -Leaf)" | Set-Content -Encoding ascii "$zip.sha256"
           Get-ChildItem dist -Filter "MITM-DomainFronting-Control-Center-*.zip*" | Format-Table -AutoSize
 
+      - name: Verify release artifact contents
+        shell: pwsh
+        run: |
+          $tag = "${{ github.ref_name }}"
+          if (-not $tag) { $tag = "dev" }
+          $zip = "dist/MITM-DomainFronting-Control-Center-$tag-windows-x64.zip"
+          python main.py release-check --zip $zip --checksum "$zip.sha256"
+
       - name: Upload GUI build artifact
         if: always()
         uses: actions/upload-artifact@v4

.github/workflows/validate.yml

@@ -109,6 +109,7 @@ jobs:
         run: |
           python tests/python/health_policy_tests.py
           python tests/python/readiness_tests.py
+          python tests/python/release_artifact_tests.py
           python tests/python/gui_readiness_tests.py
 
       - name: Validate transport experiment manifest

CHANGELOG.md

@@ -15,6 +15,9 @@
 - Shared readiness model for CLI/GUI orchestration with `ProjectState`, `CheckResult`, and `RepairAction` contracts.
 - `main.py probe` now emits the shared readiness state instead of running a separate health-probe path.
 - Python regression tests now live under `tests/python/`; `scripts/` is kept for operator commands, diagnostics, builders, and app entrypoints.
+- `main.py release-check` gates release readiness and ZIP artifact verification, including checksum and forbidden local certificate/key checks.
+- Release readiness checks and ZIP artifact verification.
+- Farsi quick start, maintainer map, generated-files policy, roadmap, and architecture decision records.
 
 ### Changed
 
@@ -26,6 +29,7 @@
 - JA3 runtime self-audit comparison extracted to testable `ja3::self_audit` (env: `MITM_STREAM_EXPECTED_JA3`).
 - JA3 MD5 hex encoding writes directly into a pre-sized buffer instead of allocating per byte.
 - No change to default runtime behavior unless maintainers apply optional patches.
+- Removed obsolete historical patch files now superseded by committed loopback and ignore rules.
 
 ### Notes
 

README.md

@@ -177,7 +177,9 @@ Firefox -> Settings -> About Firefox -> پنج بار روی لوگو بزنید
 - `Xray-config/mycert.crt` و `Xray-config/mycert.key`: گواهی و کلید شخصی شما؛ این فایل‌ها local هستند و نباید commit شوند.
 - `scripts/gui.py`: مرکز کنترل گرافیکی برای راه‌اندازی، تست، تعمیر و گزارش محلی.
 - `scripts/`: ابزارهای validate، preflight، health، DNS، route، browser و release.
+- `tests/python/`: تست‌های رگرسیون و ساختار پروژه.
 - `docs/`: راهنماهای جزئی‌تر درباره گواهی، مرورگر، DNS، پروفایل‌ها، سازگاری پلتفرم، release و عیب‌یابی.
+- `ROADMAP.md`: وضعیت کارهای انجام‌شده و شکاف‌های باقی‌مانده.
 - `.local-state/`: گزارش‌ها و تاریخچه محلی برنامه؛ خروجی پشتیبانی است و نباید بدون بازبینی ارسال شود.
 
 ## بررسی و عیب‌یابی محلی
@@ -218,8 +220,11 @@ py -3 scripts\lab_evidence_validate.py lab-evidence.bundle.json
 
 ## راهنماهای تکمیلی
 
+- شروع سریع فارسی: `docs/fa/quick-start.md`
 - راهنمای GUI: `docs/gui.md`
 - یکپارچه‌سازی Chromium: `docs/chromium-integration.md`
+- نقشه نگه‌داری: `docs/reference/maintainer-map.md`
+- مرز فایل‌های منبع و تولیدی: `docs/reference/generated-files.md`
 - چرخه عمر گواهی: `docs/certificate-lifecycle.md`
 - عیب‌یابی و preflight: `docs/preflight-and-diagnostics.md`
 - پروفایل‌های عملیاتی: `docs/operating-profiles.md`

ROADMAP.md

@@ -0,0 +1,34 @@
+# Roadmap And Gap Tracker
+
+This file tracks product coherence work that should remain visible between releases.
+
+## Completed
+
+- Shared `ProjectState`, `CheckResult`, and `RepairAction` readiness layer.
+- `main.py probe` emits shared readiness state.
+- GUI dashboard consumes readiness state for next action, safety banner, and status cards.
+- Unsafe external listener detection is visible in CLI and GUI.
+- Python regression tests moved to `tests/python/`.
+- Release ZIP verifier added and wired into the GUI release workflow.
+- Maintainer map and ADRs added.
+
+## Next
+
+- Extract more of `scripts/gui.py` into focused GUI modules.
+- Add a guided trust checklist panel backed by shared readiness fields.
+- Add explicit JA3 oracle fields and measured-vs-configured UI.
+- Add `verified-session` evidence bundle command.
+- Add release artifact verifier output to release notes.
+- Consolidate CA docs into a single certificate reference.
+- Consolidate DNS/profile/protocol docs into a single network-model reference.
+- Add JSON schemas for `configs/`, `providers/`, and `config-src/`.
+
+## Open Gaps
+
+| Gap | Desired Outcome | Current Status |
+|---|---|---|
+| Per-process telemetry | Show app-owned Xray counters separately from system counters | System counters are labeled; per-process telemetry not implemented |
+| JA3 oracle workflow | User enters oracle URL and expected hash; app records measured result | Readiness model supports fields; GUI flow not complete |
+| Verified runtime session | One command saves redacted runtime evidence | Planned |
+| Docs consolidation | Fewer first-contact docs, stronger reference docs | Started with Farsi quick start, ADRs, maintainer map |
+| GUI modularization | `scripts/gui.py` becomes a small entrypoint | Started with `scripts/core/gui_readiness.py` |

docs/adr/0001-xray-as-runtime.md

@@ -0,0 +1,19 @@
+# ADR 0001: Xray Is The Runtime Source Of Truth
+
+## Status
+
+Accepted.
+
+## Context
+
+The project contains Python diagnostics, GUI orchestration, generated profiles, and Rust validation experiments. Without a clear boundary, these pieces can look like competing runtimes.
+
+## Decision
+
+Xray remains the actual runtime for proxying, routing, MITM, domain-fronting, and uTLS fingerprint behavior. Python, GUI, config-src, tests, and Rust validate, generate, observe, or assist around Xray.
+
+## Consequences
+
+- Runtime behavior must be proven against generated Xray configs.
+- Rust code is validation/experimental unless explicitly promoted later.
+- Native Xray-core integration is deferred until a feature is stable enough to justify a Go/Xray-core implementation.

docs/adr/0002-no-silent-trust-install.md

@@ -0,0 +1,19 @@
+# ADR 0002: No Silent Trust-Store Installation
+
+## Status
+
+Accepted.
+
+## Context
+
+The project creates local CA material for browser MITM diagnostics. Installing trust silently would be risky and surprising.
+
+## Decision
+
+The app may generate local certificate files and show instructions, but it must not silently install a CA into Windows, browser, or machine trust stores.
+
+## Consequences
+
+- Trust setup remains explicit and user-controlled.
+- GUI and CLI should report trust state and recommended next action.
+- Any future trust-changing action must require clear confirmation and must explain system impact.

docs/adr/0003-browser-proxy-first.md

@@ -0,0 +1,19 @@
+# ADR 0003: Browser Proxy First
+
+## Status
+
+Accepted.
+
+## Context
+
+The project supports browser diagnostics and optional fingerprint checks. OS-wide proxy or TUN changes are higher-risk and harder to reason about for newcomers.
+
+## Decision
+
+The default diagnostic path is an explicit browser proxy against the local Xray listener. TUN and OS proxy state are detected or documented, not silently changed.
+
+## Consequences
+
+- Page Check should run before advanced fingerprint checks.
+- CloakBrowser is an app-layer fingerprint path, not a routing engine.
+- System proxy and TUN states are warnings/context unless the user intentionally configures them.

docs/adr/0004-ja3-oracle-honesty.md

@@ -0,0 +1,19 @@
+# ADR 0004: JA3 Oracle Required For Measured Fingerprint Claims
+
+## Status
+
+Accepted.
+
+## Context
+
+Xray can be configured with `tlsSettings.fingerprint: "chrome"`, but that is not the same as externally measured JA3 proof.
+
+## Decision
+
+The app may say a TLS fingerprint is configured when the Xray config sets it. It may only claim a measured JA3 match when an external JA3 oracle returns matching evidence.
+
+## Consequences
+
+- Without an oracle URL and expected value, JA3 status remains `not measured`.
+- GUI/docs must distinguish configured uTLS behavior from measured TLS fingerprint evidence.
+- Browser fingerprint checks and TLS fingerprint checks remain separate concepts.

docs/adr/0005-local-source-labeled-telemetry.md

@@ -0,0 +1,19 @@
+# ADR 0005: Local Source-Labeled Telemetry
+
+## Status
+
+Accepted.
+
+## Context
+
+The GUI shows network and activity telemetry. Some telemetry is system-wide while future telemetry may be app- or process-specific.
+
+## Decision
+
+Telemetry must stay local and must label its source, scope, and confidence. System counter telemetry must not be presented as per-Xray telemetry.
+
+## Consequences
+
+- The right rail can show rates, totals, and running time, but labels must clarify measurement scope.
+- Future per-process or Xray-log telemetry should be shown as a distinct source.
+- No automatic upload of telemetry is allowed.