From fc3c1d51b1be9db6ba6ad286584fbc34bb305f38 Mon Sep 17 00:00:00 2001 From: Andrew Guschin Date: Fri, 30 Oct 2026 03:32:00 +0400 Subject: Fix protected activation ordering and diagnostic review findings --- docs/implementation-review.md | 33 +++++++++++++++++++++ docs/validation/linux-vm.txt | 67 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 docs/implementation-review.md create mode 100644 docs/validation/linux-vm.txt (limited to 'docs') diff --git a/docs/implementation-review.md b/docs/implementation-review.md new file mode 100644 index 0000000..0bf25c0 --- /dev/null +++ b/docs/implementation-review.md @@ -0,0 +1,33 @@ +# First-release implementation review + +The implementation was reviewed against `40cf3276cdc74bf6f1795990ed600891a637d1fe`. Independent standards and specification reviews inspected candidate `d608ffe`. Corrections followed in the same branch. Review findings do not establish that the release acceptance matrix has passed. + +## Standards + +The standards review found no hard repository-rule violations and three design observations: + +- Numeric TUI screen state allowed a subscription row to be clamped against the configuration list. Refresh now uses the current screen's row bounds. +- Entry validation used free-form strings. Saved entries now use a serialized status enum, and the storage boundary rejects contradictory validation/connection data. +- The controller created Xray probes directly while activation used the runtime boundary. Probe creation now goes through that boundary as well. + +Standards findings: three design observations, zero hard violations. The row-selection bug was the most consequential observation and is corrected. + +## Spec + +The specification review found five correctness issues: + +- Retry could bypass a failed activation preflight. Runtime retries now require successful compatibility checks, and each managed Xray service start repeats the version check. +- An unset selection could reuse a TUN left by the previous controller. Startup first blocks forwarding, and no-selection reconciliation stops the owned core and removes capture. Enabled selection changes block forwarding before committing new state. +- An untrusted local listener could impersonate the probe's SOCKS endpoint. The adapter now generates a private TLS identity for an authenticated HTTPS proxy. Diagnostic requests authenticate that identity before using the proxy, so a reused TCP port cannot authorize a different route. +- Manual diagnostic requests ignored provider cooldowns. Retry-After now prevents further diagnostic requests to that provider, including manual Ping and Speed. +- Competing HTTP and measurement timeouts could turn a completed duration-limited Speed observation into a generic error. Diagnostics now use one measurement deadline and report consumed bytes when the duration cap ends a nonempty measurement. + +Spec findings: five correctness issues, corrected. The stale-selection forwarding path was the most serious finding. VM CLI regressions cover failed preflight retries and startup with stale capture and unset selection. The probe TLS changes and duration/rate-limit behavior still require end-to-end validation with the required current Xray runtime. + +## Validation boundary + +After the user's VM-only instruction, all test execution used the supplied ALT VM. Compilation and formatting used the local checkout. The VM checkpoint precedes package/test preparation and is restored after validation. + +The current package available from that VM's refreshed Sisyphus repository is Xray 26.3.27. The implementation rejects activation with it. The tests therefore distinguish actual guard/controller/polkit/editor/recovery behavior from unverified native-TUN and diagnostic operation with the researched newer Xray contract. The product installer is not counted as a successful installation in this environment; system-bus tests stage their integration fixtures explicitly. + +The final available suite passed on 2026-10-30: 10 Rust CLI/controller acceptance tests and 21 VM workflow checks. The [captured output](validation/linux-vm.txt) records the tested executable digest and each result. Checks include TCP and UDP DNS destination policy, IPv4/IPv6 blocking, retained incoming connections, denial/allow authorization, ordinary-user TUI restoration, editor privacy, failed-preflight retries, stale capture with unset selection, malformed TOML recovery, missing durable state, and uninstall retention/purge. diff --git a/docs/validation/linux-vm.txt b/docs/validation/linux-vm.txt new file mode 100644 index 0000000..604a6de --- /dev/null +++ b/docs/validation/linux-vm.txt @@ -0,0 +1,67 @@ +Candidate SHA-256: 1da493619f430722743b1013faf70da0298d71df620662b6589ccc48e6a5873e +Running: cli_acceptance-8ac5b3df5e4cd10a + +running 2 tests +test subscription_url_cannot_be_passed_on_the_command_line ... ok +test help_describes_the_controller_commands_without_contacting_services ... ok + +test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s + +Running: roentgen-2037e66e0f348630 + +running 0 tests + +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s + +Running: roentgen-0d6b8b6ef4b4cfd3 + +running 0 tests + +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s + +Running: controller_acceptance-7693ccc2191fcbcc + +running 8 tests +test importing_requires_explicit_selection_and_enabling ... ok +test denied_operations_leave_durable_state_unchanged ... ok +test losing_a_selection_keeps_enabled_intent_and_blocks_without_replacement ... ok +test mixed_base64_import_keeps_all_rows_and_prohibits_invalid_selection ... ok +test failed_fetch_preserves_selection_but_an_empty_received_list_clears_it ... ok +test persisted_intent_restores_under_protection_after_controller_restart ... ok +test label_changes_keep_identity_but_duplicate_candidates_clear_selection ... ok +test explicit_unset_and_deletion_never_disable_or_select_another_entry ... ok + +test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s + +Running: vm_guard_acceptance.py +{ + "passed": [ + "private IPv4/IPv6 destinations stay direct on ports 53 and 18080", + "public IPv4/IPv6 destinations are blocked on ports 53 and 18080", + "UDP DNS follows the same IPv4/IPv6 private/public destination rule", + "classified incoming TCP connection survives guard replacement and toggles", + "preexisting outgoing TCP connection receives no established-flow exemption", + "explicit disabled guard restores ordinary direct routing" + ] +} +Running: vm_controller_acceptance.py +{ + "passed": [ + "real HTTP import remains disabled/unselected and public CLI output omits credentials", + "noninteractive non-root mutation is denied with durable state unchanged", + "polkit site allow policy authorizes the actual ordinary bus caller", + "mixed update retains ordered invalid/unsupported rows and normalized identity", + "whole-document failure preserves selection while received empty list clears it", + "unsupported packaged Xray activation is rejected before enabled intent changes", + "service restart retains explicit selection and disabled intent", + "editor receives literal arguments and a user-owned private snapshot that is removed afterward", + "ordinary-user TUI renders, accepts navigation/help/quit, restores terminal modes, and preserves service intent", + "restart and scheduled retry preserve blocked intent after failed compatibility checks", + "restart with unset selection removes stale capture and keeps TUN forwarding blocked", + "explicit recovery persists disabled intent even with malformed editable TOML", + "subscription deletion clears selection without replacement", + "missing durable enabled state fails closed; only explicit recovery initializes disabled state", + "uninstall retains saved data by default, explicit purge removes it, and system Xray remains installed" + ] +} +ALL AVAILABLE VM TESTS PASSED -- cgit v1.2.3